Documentation
¶
Overview ¶
Package cli is ptrbox's command surface.
Every command runs on the HOST with your privileges. Nothing here is ever provisioned into a sandbox VM - an agent that can edit its own sandbox's provisioning code is not sandboxed.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var DefaultEditor = openEditor
DefaultEditor is exported so main can install it without knowing how it is resolved.
var ErrReported = errors.New("reported")
ErrReported means the command already explained itself and main should just take the exit status. For failures whose useful form is several lines - a missing dependency and the brew line that fixes it - where restating the headline as "ptrbox: error: ..." would only say it twice.
var ErrUsage = errors.New("usage")
ErrUsage is returned for an unknown command: exit status 2, distinct from a command that ran and failed.
Functions ¶
Types ¶
type CredentialManager ¶ added in v0.1.1
type CredentialManager struct{}
CredentialManager reads a generic credential from Windows Credential Manager. The read itself is one call into advapi32 and lives in keychain_windows.go; everything that can be said without Windows is here, where the suite runs it.
func (CredentialManager) Available ¶ added in v0.1.1
func (CredentialManager) Available() bool
func (CredentialManager) Name ¶ added in v0.1.1
func (CredentialManager) Name() string
func (CredentialManager) SetupAdvice ¶ added in v0.1.1
func (CredentialManager) SetupAdvice(service string) []string
cmdkey with a bare /pass prompts for the secret rather than taking it as an argument. /user is required by cmdkey and read by nothing.
func (CredentialManager) Token ¶ added in v0.1.1
func (CredentialManager) Token(service string) string
type Env ¶
type Env struct {
Cfg *config.Config
Backend backend.Backend
Proxy *proxy.Proxy
Assets fs.FS
// Out carries progress notes; Stdout carries command output that a caller
// might pipe (a log tail, the allowlist).
Out ui.Printer
Stdout io.Writer
Stdin io.Reader
// Keychain is where the Claude token comes from.
Keychain Keychain
// Exe is the path to the running binary, for the PATH symlink offer.
Exe string
// Interactive says whether a question can be asked at all.
Interactive bool
// AssumeYes and NoInput come from install's flags.
AssumeYes bool
NoInput bool
// Editor opens a file for the user. A field so tests can supply one
// without needing a real editor on the machine.
Editor func(path string) error
// Now is the clock, a field so an archive filename is reproducible in
// tests.
Now func() time.Time
// Load resolves the configuration and everything derived from it. It is
// called only for commands that need it, so `ptrbox help` and
// `ptrbox version` still work on a host whose config file does not parse.
Load func(*Env) error
// LoadVM re-resolves the configuration with a VM's per-VM overrides
// layered in, once its name is known. Only `new` calls it: it is the only
// command that consumes a per-VM key, because those keys are frozen into
// the generated Lima config at create time and inert afterwards.
//
// A separate hook rather than a Config method call at the site, because
// re-resolving also re-answers the things main derives from a config -
// which image the narrator names, and the Proxy's view of the world.
LoadVM func(env *Env, vm string) error
}
Env is everything a command needs that is not its own arguments. Assembled once in main and, in tests, assembled against fakes - which is what lets the whole lifecycle be simulated without a Mac.
type ExitStatus ¶ added in v0.1.1
type ExitStatus int
ExitStatus is a command that has nothing to say beyond its exit status: the shell a person just left, whose status is that of the last thing they ran in it. main exits with it and prints nothing - "error: exit status 1" after a session that ended with a failed grep would be ptrbox reporting somebody else's business as its own failure.
func (ExitStatus) Error ¶ added in v0.1.1
func (s ExitStatus) Error() string
type HostOS ¶ added in v0.1.1
type HostOS struct {
Name string
// Symlinks: install may offer to link the binary into BIN_DIR. Not on
// Windows, where creating a symlink takes Developer Mode or an elevated
// shell - and ptrbox never elevates.
Symlinks bool
// FallbackEditor is what opens a file when neither $VISUAL nor $EDITOR
// says.
FallbackEditor string
// GitPackage is the name git goes by in this platform's package manager,
// and InstallAdvice the commands that install a list of packages. ptrbox
// prints them and never runs them.
GitPackage string
InstallAdvice func(packages []string) []string
// PathAdvice is how a directory gets onto PATH: the startup file to
// append to - empty when there is none, or none ptrbox should guess at -
// and the line that does it. ReloadAdvice is what makes it take effect.
PathAdvice func(dir string) (rcFile, line string)
ReloadAdvice func() string
// SamePath compares two PATH entries the way the platform resolves them.
SamePath func(a, b string) bool
}
HostOS is what differs between operating systems on the host side and is not a path (config.Platform) or a VM backend (backend.Facts): how a directory gets onto PATH, what installs a missing dependency, which editor is there when none is configured.
A value swapped at run time, for config.Platform's reason: the Windows behaviour is ordinary code the suite runs on Linux, rather than code first executed on the machine it is for.
type Keychain ¶
type Keychain interface {
// Available reports whether the store can be read here at all.
Available() bool
// Token returns the secret for a service, or "" if there is no such
// entry. A missing entry is not an error - it is the state of a fresh
// machine, and the caller warns rather than fails.
Token(service string) string
// Name is what the store is called, as it reads in a sentence.
Name() string
// SetupAdvice is what to type to create the entry, one command per line.
// Every command here must PROMPT for the secret: advice that puts a token
// on a command line puts it in shell history.
SetupAdvice(service string) []string
}
Keychain is where the Claude OAuth token comes from: the platform's secret store. The only credential ptrbox ever puts in a VM, and the reason this is an interface: the store differs per platform, a machine may have none, and the tests must be able to say so.
func HostKeychain ¶ added in v0.1.1
func HostKeychain() Keychain
HostKeychain is the secret store of the platform ptrbox was built for.
type SecurityKeychain ¶
type SecurityKeychain struct{}
SecurityKeychain reads the macOS Keychain via `security`.
func (SecurityKeychain) Available ¶
func (SecurityKeychain) Available() bool
func (SecurityKeychain) Name ¶ added in v0.1.1
func (SecurityKeychain) Name() string
func (SecurityKeychain) SetupAdvice ¶ added in v0.1.1
func (SecurityKeychain) SetupAdvice(service string) []string
func (SecurityKeychain) Token ¶
func (SecurityKeychain) Token(service string) string
Source Files