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 SurfaceSnapshot(repoRoot string) (surface.Snapshot, 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) 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 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.