An open source design system that's fully customizable and agent ready
TypeScript
spec: cli-surface INV28 — every result names the package each artifact comes from (#6966)
Joeyd50b3536eee2
diff --git a/docs/architecture/cli-surface.md b/docs/architecture/cli-surface.mdindex 20464ba137..48f60e3d9f 100644--- a/docs/architecture/cli-surface.md+++ b/docs/architecture/cli-surface.md@@ -97,7 +97,7 @@ and remains available through explicit Core package selection.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, type, data}` plus optional `package` (INV28) and `meta`. Failure is`{apiVersion, error, code}` plus optional `suggestions`. There is no thirdshape, no partial write, and no raw stack trace: an uncaught throw becomes anenvelope at the bin error boundary.@@ -255,6 +255,20 @@ and remains available through explicit Core package selection.`astryx search` meet it first.A link between docs names its target by doc identity and is resolved onevery read; Doctor warns on one that names no doc.+- **INV28 — Every result names the package each artifact comes from.** A+ `--json` result about one artifact (a component, doc, template, or hook)+ carries `package` in its envelope, directly after `type`. A result+ that lists artifacts gives each listed artifact its own `package`, and a+ doc's sections each name the package that wrote them. Core's components,+ hooks, templates, and codemods name `@astryxdesign/core`; the docs the CLI+ ships name `@astryxdesign/cli`; an integration's artifacts name the+ integration's package, with nothing written for it by the integration's+ author. Two lists of plain names, `hook --list` and `swizzle --list`, hold+ only Core's artifacts and name `package` once, in the envelope; `build`'s+ `frame` and `foundation` are fixed lists of Core component names. Text+ output names the same package. Verbatim source output (`--source`,+ `--showcase`, and a template's source) keeps stdout to the source alone, so+ it pipes byte for byte, and names the package on stderr.Some modules predate INV20–INV23 and do not meet them yet; `spec:AST-042` liststhe known gaps.@@ -352,6 +366,7 @@ non-interactive guarantee.| INV23 | `clients/cli/formatters/index.test.mjs` for the kit; review of handlers; no mechanical check yet | A handler pads, aligns, or draws text itself, or a block kind is missing from the help "Output format" list. || INV24 | `api/integration/add-contribution.test.mjs`, `api/integration/add-theme.test.mjs`, `foundation/discovery/theme-discovery.test.mjs` | New authoring emits an untyped or non-`.doc.mjs` item, adding one item edits a shared file, or an item catalog becomes authoritative. || INV25 | `foundation/discovery/cli-self-docs.test.mjs`, `api/doctor/doctor.test.mjs` | A CLI doc with no namespace, a namespace no topic reads, or no section in its topic passes doctor. |+| INV28 | `test/inv28-package-provenance.test.mjs`, `clients/cli/commands/text-json-parity.test.mjs`, `cli-api-types-verify` | A result about one artifact has no envelope `package`, a listed artifact has no `package`, or text omits the package the envelope names. |## Open questions