devsandbox

package
v0.13.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 23, 2026 License: AGPL-3.0 Imports: 17 Imported by: 0

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

View Source
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.

View Source
const WorkspaceName = "toy"

WorkspaceName is the name the toy repo is registered under.

Variables

This section is empty.

Functions

func BaseDir

func BaseDir() (string, error)

BaseDir returns the directory holding every sandbox: ${XDG_STATE_HOME:-~/.local/state}/loom-dev.

func DefaultName

func DefaultName(branch string) string

DefaultName derives a sandbox name from a git branch: the leaf after the last "/", lowercased, with runs of other characters collapsed to "-".

func ShellQuote

func ShellQuote(s string) string

ShellQuote single-quotes s for a POSIX shell.

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.

func List

func List() ([]Info, error)

List returns every sandbox under BaseDir, sorted by name.

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

type Sandbox struct {
	Name string
	Dir  string
}

Sandbox is one named, persistent dev environment.

func Open

func Open(name string) (*Sandbox, error)

Open resolves the sandbox called name without touching disk.

func (*Sandbox) BinDir

func (s *Sandbox) BinDir() string

BinDir holds the sandbox's built binaries.

func (*Sandbox) Build

func (s *Sandbox) Build(srcDir string) error

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

func (s *Sandbox) Down() error

Down kills the sandbox's private tmux server and deletes its directory. It refuses any Dir that is not <BaseDir>/<Name>.

func (*Sandbox) DriverRunning

func (s *Sandbox) DriverRunning() bool

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

func (s *Sandbox) Env() []string

Env is the environment overlay every sandboxed loom process runs with.

func (*Sandbox) Environ

func (s *Sandbox) Environ() []string

Environ is os.Environ() with Env() appended; os/exec uses the last value of a duplicated key, so the overlay wins.

func (*Sandbox) FakeAgentBin

func (s *Sandbox) FakeAgentBin() string

FakeAgentBin is the built fakeagent.

func (*Sandbox) GlobalDir

func (s *Sandbox) GlobalDir() string

GlobalDir is LOOM_GLOBAL_DIR: workspaces.json plus the global context's config and state.

func (*Sandbox) HomeDir

func (s *Sandbox) HomeDir() string

HomeDir is LOOM_HOME: startup logs.

func (*Sandbox) LoadMeta

func (s *Sandbox) LoadMeta() (*Meta, error)

LoadMeta reads sandbox.json; the error wraps os.ErrNotExist when the sandbox has never been brought up.

func (*Sandbox) LogFiles

func (s *Sandbox) LogFiles() []string

LogFiles lists the loom.log files a sandboxed loom writes.

func (*Sandbox) LoomBin

func (s *Sandbox) LoomBin() string

LoomBin is the dev build of loom.

func (*Sandbox) OriginDir

func (s *Sandbox) OriginDir() string

OriginDir is the toy repo's bare remote.

func (*Sandbox) PersonaDir

func (s *Sandbox) PersonaDir() string

PersonaDir holds the fakeagent persona symlinks.

func (*Sandbox) RepoDir

func (s *Sandbox) RepoDir() string

RepoDir is the toy workspace repo.

func (*Sandbox) Screen

func (s *Sandbox) Screen(ansi bool) (string, error)

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

func (s *Sandbox) SendKeys(keys ...string) error

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

func (s *Sandbox) SendText(text string) error

SendText types text literally, with no key-name interpretation.

func (*Sandbox) Socket

func (s *Sandbox) Socket() string

Socket is the sandbox's private tmux socket name (tmux -L).

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

func (s *Sandbox) Stop(grace time.Duration) error

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

func (s *Sandbox) TailLogs(n int) string

TailLogs returns the last n lines of each existing sandbox log, each under a tail(1)-style "==> path <==" header.

func (*Sandbox) Up

func (s *Sandbox) Up(opts UpOptions) error

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

func (s *Sandbox) WaitFor(text string, timeout time.Duration) error

WaitFor polls the driver screen until text appears or timeout elapses.

func (*Sandbox) WorkspaceConfigDir

func (s *Sandbox) WorkspaceConfigDir() string

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL