Skip to content

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.md
index 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 third
shape, no partial write, and no raw stack trace: an uncaught throw becomes an
envelope 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 on
every 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` lists
the 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