Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs: record the CLI surface and its contribution rules (#5861)

Joey04542c27dce0
diff --git a/docs/architecture/cli-surface.md b/docs/architecture/cli-surface.md
new file mode 100644
index 0000000000..923c2936e1
--- /dev/null
+++ b/docs/architecture/cli-surface.md
@@ -0,0 +1,165 @@
+---
+schema_version: 1
+template_version: 1
+kind: architecture
+id: architecture:cli-surface
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [joeyfarina]
+applies_to: [packages/cli]
+verified_by:
+ [
+ pnpm check:cli-structure,
+ clients/cli/commands/json-contract.test.mjs,
+ clients/cli/commands/interactive-guard.test.mjs,
+ clients/cli/cli-exit-codes.test.mjs,
+ clients/cli/error-envelope-code.test.mjs,
+ foundation/response/error-codes.test.mjs,
+ clients/cli/formatters/index.test.mjs,
+ ]
+deciding_specs: []
+---
+
+# CLI surface architecture
+
+## Purpose
+
+The Astryx CLI is how an agent reaches Astryx. Everything an agent needs while
+building with the design system — what exists, what it does, how to use it,
+what is wrong with the code in front of it — is reachable through one command
+surface, in one predictable shape, with no person in the loop.
+
+The CLI has one audience: an agent running it in a subprocess. A person at a
+terminal is a supported reader of the output, never the caller the design
+serves. Every rule below follows from that one fact.
+
+This record describes the shipped surface: how a command is invoked, what it
+may emit, how it fails, and where its code lives. It does not describe what
+the commands do.
+
+## System model
+
+A run has four stages, and each one is a place where the surface is enforced
+rather than left to the command author.
+
+1. **Preflight.** `clients/cli/bin/astryx.mjs` gates the Node version using
+ only built-ins, before importing anything that could fail on an old
+ runtime. The gate honours `--json` with a hand-rolled envelope carrying
+ `ERR_NODE_VERSION`.
+2. **Dispatch.** `clients/cli/index.mjs` parses with Commander, sets JSON mode
+ in `preAction` before any command body runs, and rejects a command that
+ cannot support `--json` before any side effect.
+3. **Work.** The command parses its arguments and calls a function in `api/`.
+ The command is a thin wrapper: parse, call, render. The API function is the
+ unit that is scriptable and typed, and it is the source of truth for the
+ `type` discriminator on its own envelope.
+4. **Render.** Exactly one of two paths. In `--json` mode, `jsonOut` writes a
+ single envelope. Otherwise the formatters render the same values as text.
+ Nothing else may write to stdout.
+
+Discovery of components, templates, codemods and docs is not per-command. It
+goes through the `Project` seam in `foundation/config`, which resolves the
+integrations named in `astryx.config`. Each integration is loaded
+independently, so one broken package degrades that package's contribution and
+never fails the run.
+
+## Boundaries and invariants
+
+- **INV1 — The CLI never asks a question.** No prompt, no TTY detection, no
+ read of stdin for control flow. A non-TTY environment is the only supported
+ condition, not a fallback. A command with nothing to do exits with a result,
+ never a question.
+- **INV2 — Every `--json` emission is one valid envelope.** Success is
+ `{apiVersion, type, data}` plus optional `meta`. Failure is
+ `{apiVersion, error, code}` plus optional `suggestions`. There is no third
+ shape, no partial write, and no raw stack trace: an uncaught throw becomes an
+ envelope at the bin error boundary.
+- **INV3 — The code is the contract; the prose is not.** `code` is stable and
+ append-only. Once shipped, a code's meaning never changes and the code is
+ never removed. The `error` string may be reworded at any time. A consumer
+ branches on `code`.
+- **INV4 — Human output is a projection of the JSON, produced only by the
+ formatters.** `emit` accepts a renderer-produced `Block` and nothing else, so
+ a stray string cannot reach stdout. Output is plain ASCII: no colour, no TTY
+ detection, no width wrapping, byte-for-byte identical printed or piped.
+- **INV5 — Text field names mirror JSON keys one to one.** The two views cannot
+ drift, and every field stays greppable.
+- **INV6 — One command, one file.** A command is
+ `clients/cli/commands/<name>.mjs`, or `clients/cli/commands/<name>/index.mjs`
+ when it is a group, with a sibling `<name>.doc.mjs`. A subcommand's doc is
+ `<parent>-<child>.doc.mjs`.
+- **INV7 — Every command ships a `CommandDoc`, and the generated surfaces come
+ from it.** Help text, the README command and error-code tables, and the
+ manifest are generated. None of them is written by hand.
+- **INV8 — Exit codes do not depend on the output mode.** The same condition
+ exits the same way with and without `--json`, so a command works as a gate
+ without parsing stdout.
+- **INV9 — A command that cannot support `--json` is rejected before any side
+ effect**, not part-way through the work.
+- **INV10 — Every write is confined.** Output paths pass `assertWithin`, which
+ canonicalises symlinks and rejects a NUL byte; an escape is
+ `ERR_PATH_TRAVERSAL`. Bounded inputs are capped rather than trusted.
+- **INV11 — A broken integration degrades, it does not fail the run.** The
+ `Project` seam loads each integration independently and records the failure.
+- **INV12 — Human chatter never touches stdout in JSON mode.** `humanLog` and
+ `humanWarn` are the only chatter primitives, and both are no-ops under
+ `--json`.
+
+## Change coupling
+
+A change to any of the following requires this record to be re-read, and
+updated in the same pull request when it moves an invariant:
+
+- adding, removing, or renaming a command or subcommand;
+- adding an error code, or changing what an existing code means;
+- adding a field to the JSON envelope, or changing the shape of one;
+- adding a formatter, or writing to stdout from anywhere other than `emit` and
+ `jsonOut`;
+- changing the file layout under `clients/cli/commands`.
+
+`pnpm check:cli-structure` enforces the layout. The contract tests listed in
+`verified_by` enforce the envelope, the exit codes, the error codes, and the
+non-interactive guarantee.
+
+## Owning code
+
+- `clients/cli/bin/astryx.mjs` — Node floor gate and the error boundary that
+ converts an uncaught throw into an envelope.
+- `clients/cli/index.mjs` — Commander wiring, JSON-mode gate, dispatch.
+- `clients/cli/commands/<name>.mjs` — one command: parse, call the API, render.
+- `clients/cli/commands/<name>.doc.mjs` — the `CommandDoc` that generates help
+ and the published tables.
+- `clients/cli/formatters/index.mjs` — `Block`, `emit`, `section`, `text`,
+ `list`, `record`, `records`, `code`, and the shared ASCII vocabulary.
+- `foundation/response/json.mjs` — `API_VERSION`, `jsonOut`, `jsonError`,
+ `toErrorEnvelope`, `humanLog`, `humanWarn`, the JSON-mode flag.
+- `foundation/response/error-codes.mjs` — the frozen, append-only code set.
+- `foundation/config` — the `Project` discovery seam and the integration
+ manifest loader.
+- `api/<subject>/…` — the scriptable functions the commands wrap; each owns the
+ `type` on its own envelope.
+
+## Deciding specs
+
+None yet. This record describes behaviour that is already shipped. A change to
+an invariant above needs a system spec.
+
+## Verification
+
+| Invariant | Evidence | Failure signal |
+| --------- | --------------------------------------------------- | ---------------------------------------------------------------------- |
+| INV1 | `clients/cli/commands/interactive-guard.test.mjs` | The subprocess hangs: `signal === 'SIGTERM'` and `status === null`. |
+| INV2 | `clients/cli/commands/json-contract.test.mjs` | `--json` stdout does not parse, or parses to a shape outside the two. |
+| INV3 | `foundation/response/error-codes.test.mjs` | A shipped code disappears, or an envelope carries an unregistered one. |
+| INV4 | `clients/cli/formatters/index.test.mjs`, type tests | `emit` accepts a bare string, or output varies between pipe and TTY. |
+| INV6 | `pnpm check:cli-structure` | A command's file or its doc is missing, or sits at the wrong path. |
+| INV8 | `clients/cli/cli-exit-codes.test.mjs` | The same condition exits differently with and without `--json`. |
+
+## Open questions
+
+- **OQ1 — Should the envelope's `meta` carry the resolved integration set?**
+ (`human-api`) An agent cannot currently tell from the output whether a thin
+ result means "nothing matches" or "an integration failed to load".
diff --git a/docs/contributing/README.md b/docs/contributing/README.md
index 6c4431f732..984a26cd35 100644
--- a/docs/contributing/README.md
+++ b/docs/contributing/README.md
@@ -6,3 +6,5 @@ contracts, or component contracts.
- [API conventions](api-conventions.md): shape, propose, implement, and review a
public component API.
+- [CLI conventions](cli-conventions.md): propose, implement, and review a change
+ to the `packages/cli` command surface.
diff --git a/docs/contributing/cli-conventions.md b/docs/contributing/cli-conventions.md
new file mode 100644
index 0000000000..e68c77f42b
--- /dev/null
+++ b/docs/contributing/cli-conventions.md
@@ -0,0 +1,199 @@
+# CLI conventions for contributors
+
+This guide turns the CLI surface architecture into the steps you follow when
+you change `packages/cli`. It does not create policy. Where it and
+`docs/architecture/cli-surface.md` disagree, the architecture record wins.
+
+## Who the CLI is for
+
+The caller is an agent. It runs the CLI in a subprocess, reads `--json`, and
+acts on the result without a person watching. A person reading the text output
+is a supported reader, never the caller the design serves.
+
+Two things follow, and they settle most arguments before they start:
+
+- **The CLI must not impede the agent's flow.** No prompt, no confirmation, no
+ question. A command that cannot finish returns an error with a code the agent
+ can branch on and a suggestion it can act on.
+- **The output is data first.** `--json` is the source of truth. The text output
+ is a projection of the same values, produced by the formatters.
+
+## What the CLI is for
+
+Give an agent access to everything that helps it build with Astryx: what
+components and templates exist, what they do, how they are used, what is wrong
+with the code in front of it, and the utilities that change that code.
+
+The measure of the CLI is coverage and depth of that surface, not the number of
+commands on it. Most valuable work makes an existing command answer better.
+
+## Adding a command
+
+**A new command needs approval from a code owner of `packages/cli` before you
+write it.** `.github/CODEOWNERS` is the source of truth for who that is. Open
+the proposal first: a command is a permanent concept — it appears in help, in
+the manifest, in the README, and in every agent's cheat sheet, and removing one
+is a breaking change.
+
+A command earns its place when all four hold:
+
+1. **It answers a question an agent actually has** while building with Astryx —
+ not a function the CLI happens to be able to expose.
+2. **No existing command can be deepened to answer it.** Deepening is the
+ default. Reach for a new command only after naming the command you would
+ have extended and saying why extending it is wrong.
+3. **It is one job.** If the summary needs an "and", it is two commands.
+4. **Its result is worth returning as data.** If the useful output is prose for
+ a person, it is a docs topic, not a command.
+
+A command that fails any of these is usually a flag, a subcommand, or a docs
+topic.
+
+## Adding a flag
+
+Flags are more forgiving than commands, and they do not need a proposal. They
+are not free: every flag is a branch an agent has to know about, and a
+combination somebody has to keep working.
+
+A good flag:
+
+- **Narrows or redirects work the command already does.** It never gives the
+ command a second job.
+- **Has a default that is the right answer most of the time.** A flag exists to
+ escape the default, not to reach the useful behaviour. If callers must pass it
+ to get a sensible result, the default is wrong.
+- **Is boolean-off or has a value.** A boolean flag that defaults to true is a
+ mis-named opt-out; name the opt-out instead.
+- **Changes what the command produces.** A flag that only changes how the same
+ result is presented belongs to the global set (`--json`, `--detail`,
+ `--lang`), not to your command.
+- **Is not a workaround.** If the flag exists so callers can avoid a defect, fix
+ the defect.
+- **Has a closed composition matrix.** See below — this is the check people
+ skip.
+
+If the flag changes what the command _is_, it is a subcommand.
+
+## The composition matrix
+
+Before you land a flag, pair it with every flag already on that command and
+decide each cell. There are only three legal answers, and every cell needs one:
+
+1. **They compose** — and a test proves it.
+2. **They are refused together** — with a clear message and a code.
+3. **They cannot co-occur** — because another rule already refuses the
+ combination that would reach them.
+
+An undecided cell is the defect. It ships as behaviour nobody chose, and an
+agent finds it before a person does.
+
+### Worked example: `theme build --family`
+
+`--family <base> <children…>` builds a base theme and the themes that `extends`
+it as one unit: the base stylesheet restates the shared declarations once,
+scoped to every member, and each member carries only its own deltas.
+
+Its matrix against the flags already on `theme build`:
+
+| Pair | Answer |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------- |
+| `--family` `--watch` | Refused, explicitly, with a message naming both. |
+| `--family` `--out` | Cannot co-occur: `--out` with more than one file is already refused, and `--family` needs at least two. |
+| `--family` `--check` | They compose — `--check` verifies the family-shaped output. |
+| `--family` `--icons-specifier` | They compose. |
+
+That third row carries a consequence worth writing down: `--check`'s answer now
+depends on whether `--family` was passed, because the two modes emit different
+CSS. CI has to check with the same flags it built with. A cell that changes what
+another flag _means_ is a documentation obligation, not just a test.
+
+## Flags with the same name
+
+A name is a promise across the whole CLI. Two rules:
+
+- **The same flag name means the same thing everywhere, and is spelled the same
+ way.** `--family` means "a base plus the themes that extend it, built as one
+ unit". Nothing else may take that name for another idea.
+- **No command is forced to carry a flag because a sibling has it.** Alignment
+ is on meaning, not on presence. `--family` rests on `extends`, which only
+ themes have, so no other command has anything to point it at.
+
+## Output: use the shared functions
+
+Never call `console.log`. Every path is provided:
+
+| You want | Use |
+| --------------------------- | ------------------------------------------------------- |
+| A machine result | `jsonOut({type, data, meta?})` |
+| An error | `jsonError(message, suggestions, code)` / `AstryxError` |
+| A heading, prose, a list | `section()`, `text()`, `list()` |
+| One record, or many | `record(obj, opts)`, `records(arr, opts)` |
+| A code sample | `code(source)` |
+| To print any of the above | `emit(...blocks)` |
+| Chatter that JSON must hide | `humanLog()`, `humanWarn()` |
+
+`emit` accepts only a renderer-produced `Block`, so a bare string will not
+compile. Keep text field names identical to the JSON keys — the text output is
+a view of the envelope, not a separate design.
+
+## Errors: every failure carries a code
+
+Add a code to `foundation/response/error-codes.mjs` when no existing one fits.
+Codes are `ERR_<SUBJECT>[_<QUALIFIER>]`, grouped by subject, and **append-only**:
+once shipped, a code is never removed and never re-meant. Reword the message
+whenever it helps a reader; never make a caller match on it.
+
+Attach `suggestions` where the agent has an obvious next move — a near-miss
+name, the command that lists valid values.
+
+## Every command ships a doc
+
+A command is not done without its `CommandDoc` in `<name>.doc.mjs`. Fill in
+`summary`, `description`, `args`, `options` (each with a description),
+`examples`, `exitCodes`, and `related`. Help text, the README tables, and the
+manifest are generated from it, so an undocumented flag is an invisible flag.
+
+Give at least one example that an agent would actually run, including a `--json`
+one.
+
+## Marking work in progress
+
+Some of the surface is not finished, and today nothing on it says so. Callers
+cannot tell a settled command from one still being shaped.
+
+When you land a command or subcommand that is not ready to be depended on, mark
+it, and say in the doc what is still expected to change. Treat an unmarked
+command as stable: changing its output shape or its flags is then a breaking
+change.
+
+## Checklist before you open the pull request
+
+- [ ] For a new command: a code owner approved the proposal.
+- [ ] One file per command, with its sibling doc file.
+- [ ] `--json` returns one envelope; the `type` matches the API function.
+- [ ] Every failure path carries a code; new codes are appended, never edited.
+- [ ] No `console.log`; all human output goes through the formatters.
+- [ ] Text field names match the JSON keys.
+- [ ] Exit code is the same with and without `--json`.
+- [ ] The composition matrix is closed: every pair composes with a test, is
+ refused with a message, or cannot co-occur.
+- [ ] Any path you write passes through `assertWithin`.
+- [ ] The doc lists the new flag, an example, and the exit codes.
+- [ ] Marked as work in progress if it is not ready to be depended on.
+
+## Common review smells
+
+- **A flag that only a maintainer would pass.** It is a debugging affordance;
+ keep it out of the surface.
+- **A new command whose summary contains "and".** Two commands.
+- **A flag added because another command has one.** Presence does not have to
+ align; meaning does.
+- **A composition cell nobody decided.** The most common defect in a flag PR.
+- **A code invented at the call site.** Codes live in one frozen table.
+- **Text output built with string concatenation.** It will drift from the JSON
+ within one release.
+- **`--json` output that omits what the text output shows.** The text is the
+ projection; it cannot be the richer of the two.
+- **An error message that tells the agent to "check your configuration".** Name
+ the file, the key, and the expected value, or give a suggestion.
+- **A flag whose default is the unhelpful answer.** Agents will not discover it.