# floxenv

Go package for managing Flox environment lifecycles via `flox activate --detach`.

## Features

- **Activate** — start a Flox environment and return an `envID` + PID.
- **Deactivate** — graceful shutdown with `SIGTERM` then `SIGKILL` after a 10-second grace period.
- **IsAlive** — lightweight, non-privileged process-existence check using zero-signal delivery.
- **Dev-mode stub** — transparently falls back to a long-running shell command when `flox` is not installed (or when `FLOXENV_DEV_MODE=1` is set), useful for CI and local development.

## Installation

```bash
go get github.com/marcus/scobleclaw/pkg/floxenv
```

## Usage

```go
package main

import (
    "fmt"
    "log"

    "github.com/marcus/scobleclaw/pkg/floxenv"
)

func main() {
    r := floxenv.NewRegistry()

    envID, pid, err := r.Activate("/path/to/env/.flox/env/manifest.toml")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("activated %s (pid %d)\n", envID, pid)

    // later …
    if err := r.Deactivate(envID, pid); err != nil {
        log.Fatal(err)
    }
}
```

## Dev mode

When the `flox` binary is absent, or when `FLOXENV_DEV_MODE=1` is set in the environment, the package runs a lightweight stub that forks a shell `sleep` process instead of invoking `flox activate`. This keeps dependent tests green in environments where Flox is not available.

## Running tests

Unit tests (uses the dev-mode stub):

```bash
go test ./pkg/floxenv
```

Integration tests (requires a working Flox installation):

```bash
go test -tags=integration ./pkg/floxenv
```

## API

| Function | Signature | Description |
|----------|-----------|-------------|
| `NewRegistry` | `() *Registry` | Create a new registry, auto-detecting dev mode. |
| `(*Registry) Activate` | `(manifestPath string) (envID string, pid int, err error)` | Activate a Flox environment. |
| `(*Registry) Deactivate` | `(envID string, pid int) error` | Shutdown an active environment. |
| `IsAlive` | `(pid int) bool` | Non-privileged process existence check. |
| `(*Registry) List` | `() []Info` | Snapshot of tracked environments. |

## License

MIT