Documentation
¶
Overview ¶
Package devsandbox creates and drives isolated loom dev environments: a named directory holding a dev build, a toy workspace repo, seeded config, and a private tmux server, so a dev loom can run from inside a loom pane without touching the host's sessions or state. See docs/superpowers/specs/2026-09-16-dev-sandbox-design.md.
Index ¶
- Constants
- Variables
- func BaseDir() (string, error)
- func DefaultName(branch string) string
- func ShellQuote(s string) string
- type Info
- type Meta
- type Sandbox
- func (s *Sandbox) BinDir() string
- func (s *Sandbox) Build(srcDir string) error
- func (s *Sandbox) BuildLoom(srcDir, out, ldflags string) error
- func (s *Sandbox) Cmd(argv ...string) *exec.Cmd
- func (s *Sandbox) Daemon() (rec daemon.Record, held bool)
- func (s *Sandbox) Down() error
- func (s *Sandbox) Driver() string
- func (s *Sandbox) DriverRunning() bool
- func (s *Sandbox) Env() []string
- func (s *Sandbox) Environ() []string
- func (s *Sandbox) FakeAgentBin() string
- func (s *Sandbox) ForceDown() error
- func (s *Sandbox) GlobalDir() string
- func (s *Sandbox) HomeDir() string
- func (s *Sandbox) KillDaemon() (daemon.Record, error)
- func (s *Sandbox) LoadMeta() (*Meta, error)
- func (s *Sandbox) LogFiles() []string
- func (s *Sandbox) LoomBin() string
- func (s *Sandbox) OriginDir() string
- func (s *Sandbox) PersonaDir() string
- func (s *Sandbox) RepoDir() string
- func (s *Sandbox) Screen(ansi bool) (string, error)
- func (s *Sandbox) SeedWorkspace(repoDir string) error
- func (s *Sandbox) SendKeys(keys ...string) error
- func (s *Sandbox) SendText(text string) error
- func (s *Sandbox) Socket() string
- func (s *Sandbox) Start(opts StartOptions) error
- func (s *Sandbox) Stop(grace time.Duration) error
- func (s *Sandbox) StopDaemon() error
- func (s *Sandbox) StopDriver(grace time.Duration) error
- func (s *Sandbox) TailLogs(n int) string
- func (s *Sandbox) Text() (string, error)
- func (s *Sandbox) Up(opts UpOptions) error
- func (s *Sandbox) WaitFor(text string, timeout time.Duration) error
- func (s *Sandbox) WithDriver(name string) (*Sandbox, error)
- func (s *Sandbox) WorkspaceConfigDir() string
- type StartOptions
- type UpOptions
- type WaitTimeoutError
Constants ¶
const DriverSession = "dev-driver"
DriverSession is the tmux session the headless dev loom runs in. It has no loom_ prefix, so loom's orphan sweep never touches it.
const WorkspaceName = "toy"
WorkspaceName is the name the toy repo is registered under.
Variables ¶
var ErrNoDaemon = errors.New("no loom daemon runs in the sandbox")
ErrNoDaemon: nothing holds the sandbox's lock, so there is no daemon to kill.
Functions ¶
func BaseDir ¶
BaseDir returns the directory holding every sandbox: ${XDG_STATE_HOME:-~/.local/state}/loom-dev.
func DefaultName ¶
DefaultName derives a sandbox name from a git branch: the leaf after the last "/", lowercased, with runs of other characters collapsed to "-".
Types ¶
type Info ¶
type Info struct {
Name string
Dir string
ServerAlive bool
Meta *Meta // nil when sandbox.json is missing or unreadable
// Daemon is the lock record of the process holding the sandbox's global
// dir (its daemon, or one still booting: no socket yet); nil when none
// holds it.
Daemon *daemon.Record
}
Info summarizes one sandbox for List.
type Meta ¶
type Meta struct {
Name string `json:"name"`
Socket string `json:"socket"`
SourceWorktree string `json:"source_worktree"`
BuildSHA string `json:"build_sha,omitempty"`
RealClaude bool `json:"real_claude"`
CreatedAt time.Time `json:"created_at"`
}
Meta is the sandbox's sandbox.json.
type Sandbox ¶
Sandbox is one named, persistent dev environment.
func (*Sandbox) Build ¶
Build compiles loom and fakeagent from the module rooted at srcDir into the sandbox and records the source revision. The sandbox must be Up. A sandbox daemon still running the previous build is replaced by the next sandboxed loom to start when this build is newer (rpc.CompareBuilds: a later commit, or an edited tree rebuilt at the same one, which takes a srcDir that is a git checkout, so the build names its commit); an older one is refused, and one naming no commit joins the running daemon, so the daemon must be stopped first.
func (*Sandbox) BuildLoom ¶ added in v0.14.0
BuildLoom compiles loom from the module rooted at srcDir to out, with ldflags when not empty: another build beside the sandbox's own, such as `-X main.version=99.0.0` for a newer release. Run it with Cmd, or in a driver (StartOptions.Command), to use the sandbox.
func (*Sandbox) Cmd ¶ added in v0.14.0
Cmd runs argv in the sandbox's environment from the toy repo, as a sandboxed loom would run: Cmd(sb.LoomBin(), "serve", "stop"), say.
func (*Sandbox) Daemon ¶ added in v0.14.0
Daemon reads the lock record of the sandbox's daemon, the `loom serve` a sandboxed loom started (with the sandbox's global dir). held reports whether a process holds the lock now: a daemon, or one still booting (no socket yet).
func (*Sandbox) Down ¶
Down stops the sandbox's loom daemon (a sandboxed loom started it, with the sandbox's global dir), kills its private tmux server and deletes its directory, and the socket files both leave outside it. It refuses any Dir that is not <BaseDir>/<Name>. A daemon that won't stop, or a loom from before the daemon holding the sandbox's lock, stops it with nothing removed; ForceDown kills that process instead.
func (*Sandbox) DriverRunning ¶
DriverRunning reports whether the driver session exists and its program is still alive (a dead pane is kept by remain-on-exit). false also covers a session that has been fully removed (e.g. after Stop), even when paneDead's underlying query returns the empty-output false-success some tmux builds give for a missing target — see paneDead.
func (*Sandbox) Environ ¶
Environ is os.Environ() with Env() appended; os/exec uses the last value of a duplicated key, so the overlay wins.
func (*Sandbox) FakeAgentBin ¶
FakeAgentBin is the built fakeagent.
func (*Sandbox) ForceDown ¶ added in v0.14.0
ForceDown is Down, except that a process holding the sandbox's lock that won't stop (a daemon past its stop timeout, a loom from before the daemon) is killed with SIGKILL, once it is proved the sandbox's own loom (killSandboxLoom).
func (*Sandbox) GlobalDir ¶
GlobalDir is LOOM_GLOBAL_DIR: workspaces.json plus the global context's config and state.
func (*Sandbox) KillDaemon ¶ added in v0.14.0
KillDaemon kills the sandbox's daemon with SIGKILL, as a crash does: no bye, no save, and the socket file stays behind. The sessions keep running on the sandbox's tmux server, and a TUI open on the daemon sees a crash, not a stop. It kills only a process proved a build in the sandbox's bin dir (killHolder), and returns the record of the daemon it killed; ErrNoDaemon when none runs, or when it exited before the signal arrived.
func (*Sandbox) LoadMeta ¶
LoadMeta reads sandbox.json; the error wraps os.ErrNotExist when the sandbox has never been brought up.
func (*Sandbox) LogFiles ¶
LogFiles lists the log files a sandboxed loom writes: its TUI's loom.log files, and its daemon's serve.log and the crash file beside it (the runtime's own report of a fatal error, which serve.log can't hold).
func (*Sandbox) PersonaDir ¶
PersonaDir holds the fakeagent persona symlinks.
func (*Sandbox) Screen ¶
Screen captures the driver pane; ansi keeps colors and attributes. A live pane is captured exactly as shown, nothing more. Once the pane's program has exited, one extra line of scrollback is included: on this tmux, writing the remain-on-exit message unconditionally scrolls a dead pane up by exactly one line before printing "Pane is dead …", which would otherwise drop the program's last line of output from a plain capture.
func (*Sandbox) SeedWorkspace ¶ added in v0.14.0
SeedWorkspace gives the workspace repository repoDir, which a test registers with `loom workspace add`, the toy workspace's config and state (as Up does the toy repo): its sessions run the fake agent, and no first-run overlay stops a headless driver. Without it a workspace defaults to the real `claude`. The sandbox must be Up.
func (*Sandbox) SendKeys ¶
SendKeys sends tmux key names (e.g. "n", "Enter", "Escape", "C-c") to the driver pane. A word tmux does not recognize is typed as characters.
func (*Sandbox) Start ¶
func (s *Sandbox) Start(opts StartOptions) error
Start launches the driver session on the private server. A running driver is kept and a dead one replaced, unless opts.Restart is set: that stops the driver and the sandbox's daemon first (Stop), so the dev loom starts afresh.
func (*Sandbox) Stop ¶
Stop quits the dev loom: its TUI (StopDriver), then the sandbox's daemon (StopDaemon). Loom's own agent sessions stay on the private server, so the next Start boots a fresh daemon that reattaches them: the restore path. A daemon serves every driver, so stopping it ends another driver's TUI too.
func (*Sandbox) StopDaemon ¶ added in v0.14.0
StopDaemon stops the sandbox's daemon gracefully (it saves first) and waits for it to go; no daemon running is fine. The sessions keep running on the sandbox's tmux server, and the next sandboxed loom starts a fresh daemon, which reattaches them.
func (*Sandbox) StopDriver ¶ added in v0.14.0
StopDriver asks the driver's program to quit with `q`, waits up to grace for it to exit, then removes the driver session. The sandbox's daemon keeps running, as after a real quit, so the next Start connects to it.
func (*Sandbox) TailLogs ¶
TailLogs returns the last n lines of each existing sandbox log, each under a tail(1)-style "==> path <==" header.
func (*Sandbox) Text ¶ added in v0.14.0
Text captures the driver pane's text, its scrollback included, with lines the pane wrapped joined: a message wider than the pane (an exited loom's error, say) reads whole.
func (*Sandbox) Up ¶
Up creates the sandbox or tops up a partial one. Each step checks for its own artifact, so re-running is safe; config.json is only rewritten when it is missing or opts asks for a profile change.
func (*Sandbox) WithDriver ¶ added in v0.14.0
WithDriver is the sandbox driven through the tmux session name rather than DriverSession: a second headless loom beside the first, on the same server and the same daemon. Everything else is the sandbox's own.
func (*Sandbox) WorkspaceConfigDir ¶
WorkspaceConfigDir is the toy workspace's .loom directory.
type StartOptions ¶
type StartOptions struct {
// Width and Height size the driver pane (0 means 160×48).
Width, Height int
// Restart replaces an already-running driver instead of keeping it.
Restart bool
// Command overrides the program (default: the dev loom on the toy
// workspace). Tests use it to drive plain shell programs.
Command []string
}
StartOptions configures Start.
type UpOptions ¶
type UpOptions struct {
// SourceWorktree is the loom checkout the sandbox builds from.
SourceWorktree string
// RealClaude adds a profile running the real claude CLI. Sticky.
RealClaude bool
// DefaultProfile selects config.json's default profile ("" keeps the
// existing file, or "fake" for a new one). Non-empty rewrites config.json.
DefaultProfile string
// Warn, when non-nil, receives non-fatal warnings.
Warn io.Writer
}
UpOptions configures Up.
type WaitTimeoutError ¶
type WaitTimeoutError struct {
Text string
Timeout time.Duration
// Screen is the last successful capture, for diagnosis.
Screen string
}
WaitTimeoutError is returned by WaitFor when the text never appears.
func (*WaitTimeoutError) Error ¶
func (e *WaitTimeoutError) Error() string