163a3333d3
- Activate / Deactivate via flox activate --detach (with graceful SIGTERM→SIGKILL) - Non-privileged IsAlive process check with Linux /proc fallback - Dev-mode stub when flox is missing or FLOXENV_DEV_MODE=1 - Unit and integration tests Closes #16
76 lines
2.1 KiB
Markdown
76 lines
2.1 KiB
Markdown
# 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
|