cli

Documentation

Overview

Package cli is abcd's default front door: a Cobra command tree that marshals internal/core results to the terminal (human text or, with --json, machine output). It holds no business logic — every command delegates to core and only formats the result, so an MCP or other front door can expose the same core verbs without duplicating behaviour.

Index

• Constants
• func GenerateReference() string
• func GenerateSurface(repoRoot string) ([]byte, error)
• func GuardSurface(repoRoot string) (changelog.SurfaceGuard, error)
• func IdentityGenSource(title, tagline string) []byte
• func NewRootCommand() *cobra.Command
• func Run(args []string, stdout, stderr io.Writer) int
• func SurfaceChapters(repoRoot string) ([]surface.RegeneratedChapter, error)
• func SurfaceSnapshot(repoRoot string) (surface.Snapshot, error)
• type SentencePage
  • func SentencePages(repoRoot string) ([]SentencePage, error)

Constants

const ReferencePagePath = "docs/reference/cli/commands.md"

ReferencePagePath is the committed CLI reference page, relative to the repo root. The generator writes it and the drift test (reference_test.go) diffs the freshly-walked tree against it, so the two agree on one location.

const SurfaceSnapshotPath = surface.SnapshotPath

SurfaceSnapshotPath is the committed compatibility snapshot, relative to the repo root. The generator writes it, the drift test (surface_test.go) diffs the freshly-walked surface against it, and the release guardrail reads the baseline copy of it out of the last release tag — so all three agree on one location, declared once beside the type in internal/core/surface. It sits under the development record rather than under docs/ because it is a release-gate input, not something a reader of the documentation consumes.

Functions

func GenerateReference

func GenerateReference() string

GenerateReference walks the abcd command tree and renders it as a single, deterministic Markdown reference page — the source of truth for docs/reference/cli/commands.md. Hidden commands (the operator-internal `hook` subtree) and the stubs of spellings that moved are omitted, and children are emitted in a stable alphabetical order, so the output depends only on the command tree — never on registration order or the clock. That determinism is what lets a `go test` diff detect drift.

func GenerateSurface

func GenerateSurface(repoRoot string) ([]byte, error)

GenerateSurface renders the current surface as the committed artefact's bytes. Both the generator and the drift test call it, so the file that is written and the file that is checked are produced by one code path and can never disagree on formatting.

func GuardSurface

func GuardSurface(repoRoot string) (changelog.SurfaceGuard, error)

GuardSurface runs the release surface guardrail for the repository at repoRoot: it builds the CURRENT compatibility surface from the live command tree and the live manifests, and hands it to the core guardrail, which reads the baseline out of the last release tag and answers whether a narrowing was declared.

This is the split the architecture requires. Building the current surface means walking cobra, which internal/core may not do; judging a break is domain logic, which must not depend on a transport. The front door therefore owns the walk and core owns the verdict, and the dependency points one way only.

It is the entry point the ship flow calls. There is deliberately no `launch ship` verb yet — the write path is a later phase — so today this is reached from tests and from whatever front door composes the cut next; the guardrail itself is complete and does not change when that verb arrives.

func IdentityGenSource

func IdentityGenSource(title, tagline string) []byte

IdentityGenSource is the single template for the generated identity file: the identitygen command writes it, and the drift test regenerates and byte-compares the committed file against it — one source, so the file can drift in neither values nor form (the livery RenderSVG shape).

func NewRootCommand

func NewRootCommand() *cobra.Command

NewRootCommand builds the abcd command tree. Bare `abcd` renders a read-only status board (abcd's convention: bare invocation never mutates); subcommands carry the actions.

func Run

func Run(args []string, stdout, stderr io.Writer) int

Execute runs the root command; main sets the process exit code on error. Run builds the command tree, executes it against args, and renders any error as a single diagnostic line — the one place that maps a command error to a process exit code, so main stays a thin shell. stdout/stderr are injected so the whole front door (including its error surface) is testable.

func SurfaceChapters

func SurfaceChapters(repoRoot string) ([]surface.RegeneratedChapter, error)

SurfaceChapters regenerates every brief surface chapter's appendix from the live command tree (itd-147). It walks the tree with commandSurface — the walk that builds the compatibility snapshot — so the snapshot and the chapters are derived from one traversal and cannot disagree about what the tree holds. The generator (cmd/abcd-gen-surface) writes each chapter's Want and the drift test compares it with Committed, so both come from this one call.

Which shipped surfaces are host-delegated is read from the record-lint config's surface_coverage host_delegated list, the one place it is declared, so an appendix calls a command host-delegated only when that list does (iss-2609302306003610).

func SurfaceSnapshot

func SurfaceSnapshot(repoRoot string) (surface.Snapshot, error)

SurfaceSnapshot builds the current compatibility surface: every command in the tree with its flags, plus the declared entries of the two plugin manifests under repoRoot.

It walks the shared NewRootCommand() tree — the one canonical root command, the same one the CLI executes — rather than the Markdown reference walker. GenerateReference emits prose, returns early on hidden commands, and carries no structured requiredness or manifest data; reusing it would bake those blind spots into a compatibility gate. What is shared is the tree, which is the part that must not diverge.

The tree is built fresh here and never executed. Cobra lazily attaches its default `help` and `completion` machinery during execution, so snapshotting an executed tree would record surface that a freshly-built one does not have, and the answer would depend on what else ran first in the process.

Types

type SentencePage

type SentencePage struct {
	File      string
	Committed string
	Want      string
}

SentencePage is one plugin command page: its repo-relative path, the bytes committed, and the bytes it holds once its description is the verb's sentence. The generator writes Want where the two differ, and the drift test fails on any page where they do.

func SentencePages

func SentencePages(repoRoot string) ([]SentencePage, error)

SentencePages renders every plugin command page that backs a visible verb of the tree: commands/<verb>.md for each visible top-level verb, and the root's own page, commands/abcd.md. A verb with no page (abcd has verbs no page documents on its own) contributes nothing, and a page with no verb (a page whose work runs in the host) is not this manifest's to rewrite.

A page that exists but carries no frontmatter description is an error naming the page, rather than a description inserted at a guessed position.