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.mdnew file mode 100644index 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.mdindex 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 apublic 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.mdnew file mode 100644index 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.