An open source design system that's fully customizable and agent ready
TypeScript
docs(cli): require complete response schema projection (#6095)
Cindy Zhanga6078be2be20
diff --git a/docs/architecture/cli-surface.md b/docs/architecture/cli-surface.mdindex 923c2936e1..691312163d 100644--- a/docs/architecture/cli-surface.md+++ b/docs/architecture/cli-surface.md@@ -20,7 +20,7 @@ verified_by:foundation/response/error-codes.test.mjs,clients/cli/formatters/index.test.mjs,]-deciding_specs: []+deciding_specs: [spec:AST-017/DEC-4]---# CLI surface architecture@@ -66,6 +66,9 @@ integrations named in `astryx.config`. Each integration is loadedindependently, so one broken package degrades that package's contribution andnever fails the run.+AST-017 DEC-4 owns stable response-entry fields and requires their complete type,+test, applicable text, and consumer-documentation projections.+## Boundaries and invariants- **INV1 — The CLI never asks a question.** No prompt, no TTY detection, no@@ -115,7 +118,8 @@ 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;+- a change to a stable JSON envelope or discriminated response-entry field+ follows `spec:AST-017/DEC-4`;- adding a formatter, or writing to stdout from anywhere other than `emit` and`jsonOut`;- changing the file layout under `clients/cli/commands`.@@ -144,8 +148,8 @@ non-interactive guarantee.## Deciding specs-None yet. This record describes behaviour that is already shipped. A change to-an invariant above needs a system spec.+- `spec:AST-017/DEC-4` — stable response fields and their complete projections+ are current compatibility authority.## Verificationdiff --git a/docs/specs/AST-017/spec.md b/docs/specs/AST-017/spec.mdindex 4c3c920482..bd9725728b 100644--- a/docs/specs/AST-017/spec.md+++ b/docs/specs/AST-017/spec.md@@ -10,7 +10,8 @@ approved_by: cixzhangapproved_at: 2026-09-02phase: acceptedowners: [cixzhang, josephfarina]-affects_architecture: [architecture:public-component-api]+affects_architecture:+ [architecture:public-component-api, architecture:cli-surface]affects_families: []affects_contributing: [contributing:release-process, contributing:templates]affects_consumer_docs: [release-process, templates]@@ -114,6 +115,13 @@ preserves the released contract.adapter when needed; otherwise classify the narrower or higher-floor range asbreaking, describe the range change in its Changeset release note, and meet FR8'smigration obligation.+- **FR13 — Stable machine schemas project every field.** A stable CLI response+ contract includes fields inside discriminated `data` entries as well as the+ outer envelope. Every field is present in the canonical response type, contract+ tests, text projection where the command provides one, and complete+ consumer-facing schema documentation. Adding an optional field is nonbreaking+ when old consumers continue unchanged, but it remains a public schema update and+ does not bypass current-authority review or documentation.### Platform support@@ -141,18 +149,20 @@ updates:- changing or completely rebuilding the template's emitted starter page updatescontent for future generations without modifying projects that already copied it.-The stable compatibility boundary remains the CLI operation and response schema,-not the individual entries currently present in the template catalog.+The stable compatibility boundary remains the CLI operation and complete response+schema, not the individual entries currently present in the template catalog.+Nested entry fields are public schema even when optional; their type, tests, text+projection where present, and consumer schema documentation move together.## Verification-| Contract | Verification | Representative states | Mutation or failure expectation |-| -------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |-| FR1–FR3 | PR compatibility statement plus latest stable package inspection | released export, behavior, CLI command; unreleased and private surface | A change is labeled from diff size or possibility alone, or a released contract change is missed |-| FR4–FR6 | Old-usage type/runtime/CLI regression test | alias retained, deprecation warning, broad rewrite, low-adoption caller | Contractual old usage fails despite a nonbreaking label, or risk is substituted for compatibility |-| FR7–FR8 | `pnpm check:changesets` plus migration review | breaking and patch Changesets; codemoddable and non-codemoddable migration | Category and bump diverge, or a breaking release gives no usable migration path |-| FR9–FR11 | CLI contract tests plus template catalog and output tests | slug rename, metadata edit, source rebuild, command or schema change | Catalog data is frozen as API, or a command/schema incompatibility is mislabeled as a catalog-only edit |-| FR12 | Minimum and representative supported-version tests plus manifest and release-note review | retained range, narrowed range, adapter, coordinated upgrade | An in-range combination breaks under a nonbreaking label, or release coordination hides the affected package or migration |+| Contract | Verification | Representative states | Mutation or failure expectation |+| -------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |+| FR1–FR3 | PR compatibility statement plus latest stable package inspection | released export, behavior, CLI command; unreleased and private surface | A change is labeled from diff size or possibility alone, or a released contract change is missed |+| FR4–FR6 | Old-usage type/runtime/CLI regression test | alias retained, deprecation warning, broad rewrite, low-adoption caller | Contractual old usage fails despite a nonbreaking label, or risk is substituted for compatibility |+| FR7–FR8 | `pnpm check:changesets` plus migration review | breaking and patch Changesets; codemoddable and non-codemoddable migration | Category and bump diverge, or a breaking release gives no usable migration path |+| FR9–FR13 | CLI contract tests, response-schema/type snapshots, text projections, generated consumer docs, and template catalog/output tests | slug rename, metadata edit, source rebuild, optional field addition, command or schema change | Catalog data is frozen as API, a command/schema incompatibility is mislabeled as catalog-only, or a response field lacks a complete projection |+| FR12 | Minimum and representative supported-version tests plus manifest and release-note review | retained range, narrowed range, adapter, coordinated upgrade | An in-range combination breaks under a nonbreaking label, or release coordination hides the affected package or migration |## Decision log@@ -207,6 +217,23 @@ Rejected: marking every dependency bump breaking, which would freeze compatiblemaintenance, or calling an update nonbreaking merely because a coordinated upgradeworks, which would break supported independent consumers.+### DEC-4 — Stable CLI response fields receive complete projections++**Reference:** `spec:AST-017/DEC-4`+**Decider:** `cixzhang`, `2026-09-06`++Treat every field in a stable machine-readable CLI response—including nested+entry fields—as public schema. Keep its canonical type, contract tests, applicable+text output, and complete consumer documentation aligned in the same change.++An optional field addition may remain nonbreaking when old consumers continue+unchanged. That compatibility result does not make the field private or waive+current-authority and documentation requirements.++Rejected: documenting only the outer envelope, relying on implementation typedefs+as consumer documentation, or treating a response-entry field as mutable catalog+data merely because the value it carries may evolve.+## Open questionsNone.