cli

Documentation

Overview

Package cli is the primary adapter: the cobra command tree over the core. The TUI (package tui, launched by `ui`) is a second primary adapter over the same core.

Index

• func ChromeTheme(args []string) design.Theme
• func ExitCode(err error) int
• func NewRootCmd(in io.Reader, out, errOut io.Writer) *cobra.Command
• func WriteError(w io.Writer, err error, asJSON bool)
• type App

Functions

func ChromeTheme

func ChromeTheme(args []string) design.Theme

ChromeTheme resolves the active theme for OUT-OF-BAND chrome — fang's styled help and error boxes. Those render from cobra's help/error path, which returns before PersistentPreRunE ever runs, so App.Th is still the zero default when they draw. Without this, chrome silently ignored --theme and every [theme] table and always painted the built-in default.

It reuses themeName, so chrome and body share ONE precedence contract and cannot drift. Every lookup is best-effort by design: `--help` must keep working outside a planning repo, with no home config, and with an unreadable one.

Discovery starts at the process cwd, so a run that retargets with -C/--space gets that repo's theme for its BODY but cwd's for chrome. That is inherent on the HELP path (nothing has resolved a workspace yet) but not on the ERROR path, where PersistentPreRunE has already populated App.Th with the -C-aware answer and chrome could simply use it. Reconciling the two is tracked separately.

func ExitCode

func ExitCode(err error) int

ExitCode maps an error to a semantic exit code, so agents can route on the code without parsing text. 0 also covers idempotent no-ops.

func NewRootCmd

func NewRootCmd(in io.Reader, out, errOut io.Writer) *cobra.Command

NewRootCmd builds the command tree with explicit DI — no package globals. All I/O flows through the injected streams, which makes commands testable. in is the single stdin owner: it feeds App.In (the prompt gate, prompter, and editor) AND the cobra root (cmd.InOrStdin, which resolveBody reads for `--body-file -`), so a caller/test injects one reader and every input path agrees — production passes os.Stdin.

func WriteError

func WriteError(w io.Writer, err error, asJSON bool)

WriteError reports a fatal error on w: prose normally, a versioned JSON envelope when the run was --json — an agent driving --json must never have to parse prose to learn why a command failed (decided 2026-06-12). It goes to stderr either way; stdout stays empty on failure.

Types

type App

type App struct {
	Out    io.Writer
	ErrOut io.Writer
	In     io.Reader // stdin (for interactive prompts; non-TTY in tests/pipes)

	JSON     bool
	DryRun   bool // preview mutations: full validation, no writes
	Chdir    string
	Space    string // registered entry-point label (--space); explicit alternative to Chdir
	Color    string // auto | always | never
	NoColor  bool   // alias for --color=never
	NoInput  bool   // never prompt; missing required input is an error (also TSKFLW_NO_INPUT)
	NoPager  bool   // force paging off (--no-pager)
	Paginate bool   // force paging on, TTY gate permitting (--paginate)
	Theme    string // color theme name (--theme); overrides TSKFLW_THEME + [theme].name

	Style  render.Style
	Th     design.Theme    // the resolved active theme (flag > env > repo config > user config > default)
	Gate   prompt.Gate     // may we prompt? (resolved once, like Style)
	Prompt prompt.Prompter // the human-recovery face (huh on a TTY)
	Cfg    *config.Config
	// User is the home-scope config (theme/pager preferences that belong to a
	// person, not a repo). Always non-nil after setStyle; the zero value means
	// "nothing set here" and every field falls through to the tier below.
	User *userconfig.Config

	Svc *core.Service
	// SpaceSvc is the repo-independent application boundary for registry catalog,
	// selection, and mutation use cases.
	SpaceSvc *core.SpaceRegistryService
	// SpaceOverviewSvc is the repo-independent, read-only application service behind
	// `status --all`. It reads through a consumer-owned port so another primary adapter
	// can reuse the same grouping, selection, and failure-isolation rules.
	SpaceOverviewSvc *core.SpaceOverviewService
	// WorkspaceSvc opens arbitrary local planning entry points behind a neutral core
	// boundary. The atlas injects it into the TUI rather than teaching Bubble Tea about
	// config discovery or concrete Markdown storage.
	WorkspaceSvc *core.WorkspaceService
	// ConfigSvc is the framework-free configuration application core shared by
	// Cobra, both TUI contexts, and future adapters.
	ConfigSvc *core.ConfigurationService
	// Fixer/Layout/Linter are the narrow fs/text ports that aren't core use cases:
	// `lint --fix` calls Fixer, the TUI watcher reads Layout, and `lint --links` calls
	// Linter — none route through the Service (see core.Fixer/core.Layout/core.Linter).
	Fixer  core.Fixer
	Layout core.Layout
	Linter core.Linter
	// contains filtered or unexported fields
}

App is the dependency container. It is created empty by NewRootCmd and populated lazily in PersistentPreRunE — after flags are parsed, since deps (config, service) depend on flags like --chdir.