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
- 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) Down() error
- func (s *Sandbox) DriverRunning() bool
- func (s *Sandbox) Env() []string
- func (s *Sandbox) Environ() []string
- func (s *Sandbox) FakeAgentBin() string
- func (s *Sandbox) GlobalDir() string
- func (s *Sandbox) HomeDir() string
- 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) 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) TailLogs(n int) string
- func (s *Sandbox) Up(opts UpOptions) error
- func (s *Sandbox) WaitFor(text string, timeout time.Duration) 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 ¶
This section is empty.
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
}
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.
func (*Sandbox) Down ¶
Down kills the sandbox's private tmux server and deletes its directory. It refuses any Dir that is not <BaseDir>/<Name>.
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) GlobalDir ¶
GlobalDir is LOOM_GLOBAL_DIR: workspaces.json plus the global context's config and state.
func (*Sandbox) LoadMeta ¶
LoadMeta reads sandbox.json; the error wraps os.ErrNotExist when the sandbox has never been brought up.
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) 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 unless opts.Restart is set; a dead one is replaced.
func (*Sandbox) Stop ¶
Stop asks the driver's program to quit with `q`, waits up to grace for it to exit, then removes the driver session. Loom's own agent sessions stay on the private server, as after a real quit.
func (*Sandbox) TailLogs ¶
TailLogs returns the last n lines of each existing sandbox log, each under a tail(1)-style "==> path <==" header.
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) 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