agent-cos 163a3333d3 feat(pkg/floxenv): add Flox environment lifecycle management package

- 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

2026-05-29 23:40:22 -07:00

2.1 KiB

Raw Blame History

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

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

Usage

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):

go test ./pkg/floxenv

Integration tests (requires a working Flox installation):

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

2.1 KiB Raw Blame History