An open source design system that's fully customizable and agent ready
TypeScript
feat(cli): deprecate the `astryx layout` command group (DEP-0006) (#7136)
Joey68795f5a443b
diff --git a/.changeset/deprecate-layout-command.md b/.changeset/deprecate-layout-command.mdnew file mode 100644index 0000000000..ef8717a074--- /dev/null+++ b/.changeset/deprecate-layout-command.md@@ -0,0 +1,20 @@+---+'@astryxdesign/cli': patch+---++[feat] Deprecate the `astryx layout` command group++The `astryx layout` command group (`expand`, `check`, `grammar`) is deprecated.+Use `astryx build` to choose the template to start from, `astryx template` to+scaffold it, and `astryx docs layout` for layout guidance.++In human mode each invocation prints a stderr warning naming the replacement.+In JSON mode the response envelope carries machine-readable deprecation metadata+in its `meta` field. Canonical stdout, exit codes, and the `layout.expand` /+`layout.check` / `layout.grammar` response schemas are unchanged.++Deprecation lifecycle (`spec:AST-017` FR28, FR31) — removal only in a later minor whose frozen manifest carries both ids of a pair:++- deprecation `DEP-0006` / cleanup `CLN-0006` — `astryx layout` command group (`expand`, `check`, `grammar`)++@josephfarinadiff --git a/docs/specs/AST-042-cli-command-admission/spec.md b/docs/specs/AST-042-cli-command-admission/spec.mdindex a67b1ade97..49bd06f214 100644--- a/docs/specs/AST-042-cli-command-admission/spec.md+++ b/docs/specs/AST-042-cli-command-admission/spec.md@@ -236,6 +236,35 @@ option, which gives equivalent read-only lookups different automation contracts;requiring a new system record for every subcommand exclusion, which defeats the tieredbar.+## Deprecation and cleanup records++### DEP-0006 — Deprecate the `astryx layout` command group++| Field | Value |+|---|---|+| id | `DEP-0006` |+| cleanup | `CLN-0006` |+| package | `@astryxdesign/cli` |+| surface | CLI command group: `astryx layout` (`expand`, `check`, `grammar`) and its three JSON response types (`layout.expand`, `layout.check`, `layout.grammar`) |+| old contract | Compressed XLE/XLO expressions parsed, validated, and expanded into XDS TSX; expression validation with canonical-surface echo; grammar cheatsheet with alias table |+| replacement | `astryx build` chooses the closest template to start from. `astryx template <name> <path>` scaffolds it. `astryx docs layout` teaches the layout principles (scaffold, structure, spacing, breakpoints). |+| warning | Human mode: one stderr line per invocation naming DEP-0006 and the replacement commands. JSON mode: `meta.deprecation` object in the response envelope carrying `id`, `cleanup`, and `replacement`. |+| migration | Non-mechanical. The XLE/XLO expression language has no source-level equivalent in the replacement commands. Use `astryx build` to find the right template, `astryx template <name>` to scaffold it, and edit the scaffolded code directly. |+| codemod | None — vacuous: expressions are ad-hoc input, not persisted source that a codemod can rewrite. |+| downstream | Maintained agent-docs teach `build` as the front door. The layout guide (`astryx docs layout`) is unaffected. |+| state | `deprecated` |+| target plan | `CLN-0006` removal in the next scheduled minor |++### CLN-0006 — Remove the `astryx layout` command group++| Field | Value |+|---|---|+| id | `CLN-0006` |+| lifecycle | `DEP-0006` |+| delta | Remove command registration, API exports (`layoutExpand`, `layoutCheck`, `layoutGrammar`), CLI bindings, command docs, tests, and the `layout.*` response types. |+| rollback | Re-register the command group with the same API, response types, and tests from the final-patch baseline. |+| state | `pending` — lands only when a minor is scheduled and `CLN-0006` appears in its frozen manifest |+## Open questionsNone.diff --git a/packages/cli/authoring/doctypes/command/command.doc.mjs b/packages/cli/authoring/doctypes/command/command.doc.mjsindex ae3949c295..06754f6a26 100644--- a/packages/cli/authoring/doctypes/command/command.doc.mjs+++ b/packages/cli/authoring/doctypes/command/command.doc.mjs@@ -196,6 +196,11 @@ export const doc = {},],},+ {+ name: 'deprecated',+ type: 'string',+ description: 'Deprecation notice — a DEP-* id and the replacement.',+ },{name: 'related',type: 'string[]',diff --git a/packages/cli/authoring/doctypes/command/type.ts b/packages/cli/authoring/doctypes/command/type.tsindex 919e239518..a516a8c221 100644--- a/packages/cli/authoring/doctypes/command/type.ts+++ b/packages/cli/authoring/doctypes/command/type.ts@@ -81,6 +81,8 @@ export interface CommandDoc extends AuthoredDocGraphFields {examples?: CommandExampleDoc[];/** Documented exit codes. */exitCodes?: {code: number; when: string}[];+ /** Deprecation notice — a DEP-* id and the replacement. */+ deprecated?: string;/** Related command names; the CLI links each to its doc. */related?: string[];/** Freeform prose/notes. */diff --git a/packages/cli/clients/cli/commands/layout-check.doc.mjs b/packages/cli/clients/cli/commands/layout-check.doc.mjsindex c21672548d..98e128f9c1 100644--- a/packages/cli/clients/cli/commands/layout-check.doc.mjs+++ b/packages/cli/clients/cli/commands/layout-check.doc.mjs@@ -61,5 +61,6 @@ export const doc = {when: 'the expression is invalid, empty or over 5 MB (from stdin or --file), has a syntax error, or a bad --form',},],+ deprecated: 'DEP-0006: Use `astryx build` to start from a template, `astryx template` to scaffold, and `astryx docs layout` for guidance.',related: ['layout expand', 'layout grammar'],};diff --git a/packages/cli/clients/cli/commands/layout-expand.doc.mjs b/packages/cli/clients/cli/commands/layout-expand.doc.mjsindex 347f3a7990..0ca1b06908 100644--- a/packages/cli/clients/cli/commands/layout-expand.doc.mjs+++ b/packages/cli/clients/cli/commands/layout-expand.doc.mjs@@ -81,5 +81,6 @@ export const doc = {when: 'a missing, empty or over-5 MB expression (from stdin or --file), a bad --name or --form, a parse/validation error, or a path escape',},],+ deprecated: 'DEP-0006: Use `astryx build` to start from a template, `astryx template` to scaffold, and `astryx docs layout` for guidance.',related: ['layout check', 'layout grammar'],};diff --git a/packages/cli/clients/cli/commands/layout-grammar.doc.mjs b/packages/cli/clients/cli/commands/layout-grammar.doc.mjsindex ea056e75e2..dd2b048ff2 100644--- a/packages/cli/clients/cli/commands/layout-grammar.doc.mjs+++ b/packages/cli/clients/cli/commands/layout-grammar.doc.mjs@@ -26,5 +26,6 @@ export const doc = {{code: 0, when: 'success'},{code: 1, when: 'the component registry cannot be read'},],+ deprecated: 'DEP-0006: Use `astryx build` to start from a template, `astryx template` to scaffold, and `astryx docs layout` for guidance.',related: ['layout expand', 'layout check'],};diff --git a/packages/cli/clients/cli/commands/layout.doc.mjs b/packages/cli/clients/cli/commands/layout.doc.mjsindex 2ee3ba0ab2..12f162993c 100644--- a/packages/cli/clients/cli/commands/layout.doc.mjs+++ b/packages/cli/clients/cli/commands/layout.doc.mjs@@ -30,5 +30,6 @@ export const doc = {{code: 0, when: 'a subcommand succeeded, or --help'},{code: 1, when: 'no subcommand (help is printed) or an unknown subcommand'},],+ deprecated: 'DEP-0006: Use `astryx build` to start from a template, `astryx template` to scaffold, and `astryx docs layout` for guidance.',related: ['template', 'build'],};diff --git a/packages/cli/clients/cli/commands/layout.mjs b/packages/cli/clients/cli/commands/layout.mjsindex 0c26115f86..cdf2668a59 100644--- a/packages/cli/clients/cli/commands/layout.mjs+++ b/packages/cli/clients/cli/commands/layout.mjs@@ -18,7 +18,7 @@import * as fs from 'node:fs';import * as path from 'node:path';-import {jsonOut} from '../../../foundation/response/json.mjs';+import {jsonOut, isJsonMode} from '../../../foundation/response/json.mjs';import {emit, section, text, list, record, code, WARN} from '../formatters/index.mjs';import {cliError} from '../lib/cli-error.mjs';import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';@@ -59,6 +59,44 @@ import {NO_RESULT_SET, resultSet} from '../../../foundation/debug/index.mjs';* @property {boolean} [loose]*/+/**+ * DEP-0006: the `astryx layout` command group is deprecated.+ *+ * Human mode: one stderr warning per invocation.+ * JSON mode: `meta.deprecation` in the response envelope.+ */+const DEPRECATION = {+ id: 'DEP-0006',+ cleanup: 'CLN-0006',+ replacement: [+ 'astryx build "<idea>" — choose the template to start from',+ 'astryx template <name> <path> — scaffold it',+ 'astryx docs layout — layout guidance',+ ],+};++function warnDeprecated() {+ if (!isJsonMode()) {+ console.error(+ '[DEP-0006] astryx layout is deprecated and will be removed in a future minor release.\n' ++ ' Use instead:\n' ++ ' astryx build "<idea>" choose the template to start from\n' ++ ' astryx template <name> scaffold it\n' ++ ' astryx docs layout layout guidance\n',+ );+ }+}++/**+ * Add deprecation metadata to a JSON response before output.+ * Canonical stdout (type, data) is unchanged; the metadata sits in `meta`.+ * @param {{type: string, data: unknown}} result+ * @returns {{type: string, data: unknown, meta: {deprecation: typeof DEPRECATION}}}+ */+function withDeprecation(result) {+ return {...result, meta: {deprecation: DEPRECATION}};+}+/** The largest layout expression read from --file or stdin. */const MAX_EXPRESSION_BYTES = 5 * 1024 * 1024; // 5 MB@@ -143,6 +181,7 @@ export function registerLayout(program) {defineCommand(layoutCmd, layoutExpandCommand, {fn: layoutExpandFn,action: async (/** @type {string} */ expression, /** @type {string} */ targetPath, /** @type {LayoutExpandOptions} */ options) => {+ warnDeprecated();const json = program.opts().json || false;const source = await readExpression(expression, options);if (!source || source.trim() === '') {@@ -168,7 +207,7 @@ export function registerLayout(program) {// Expanding turns an expression into TSX — a transformation, not a// lookup. What it produced is in the output; there is no set to count.if (json) {- jsonOut(result);+ jsonOut(withDeprecation(result));return NO_RESULT_SET;}@@ -205,6 +244,7 @@ export function registerLayout(program) {defineCommand(layoutCmd, layoutCheckCommand, {fn: layoutCheckFn,action: async (/** @type {string} */ expression, /** @type {LayoutCheckOptions} */ options) => {+ warnDeprecated();const json = program.opts().json || false;const source = await readExpression(expression, options);if (!source || source.trim() === '') {@@ -234,7 +274,7 @@ export function registerLayout(program) {// A verdict on one expression: valid or not, with the errors that made// it so. Nothing was looked up.if (json) {- jsonOut(result);+ jsonOut(withDeprecation(result));return NO_RESULT_SET;}@@ -268,6 +308,7 @@ export function registerLayout(program) {defineCommand(layoutCmd, layoutGrammarCommand, {fn: layoutGrammarFn,action: async () => {+ warnDeprecated();const json = program.opts().json || false;/** @type {LayoutGrammarResponse} */let result;@@ -280,7 +321,7 @@ export function registerLayout(program) {// One document, the same one every time: the grammar cheatsheet.const answered = resultSet({count: 1, resultKind: 'doc'});if (json) {- jsonOut(result);+ jsonOut(withDeprecation(result));return answered;}// The cheatsheet is a preformatted document — emit verbatim.diff --git a/packages/cli/foundation/agent-docs/agent-docs.mjs b/packages/cli/foundation/agent-docs/agent-docs.mjsindex 3c88dd749d..2fe56539f9 100644--- a/packages/cli/foundation/agent-docs/agent-docs.mjs+++ b/packages/cli/foundation/agent-docs/agent-docs.mjs@@ -441,7 +441,7 @@ export function generateCompressedIndex(// Rules — the top error-preventers.lines.push('RULES:');lines.push('- No <div> — components do all layout/spacing, page frame included.');- lines.push('- Frame first: the template you scaffold sets the page frame. Read `astryx docs layout` before you change it — region widths, breakpoint behavior.');+ lines.push('- Frame first: the template you scaffold sets the page frame. Read `astryx docs layout` for the principles — region widths, breakpoint behavior.');lines.push('- Dense data = rows (Table, List/Item), never Card-wrapped list items; Card is for standalone widgets. Status = StatusDot/Token; Badge = counts only.');// Styling guidance tailored to the project's configured system — never// recommend a path that isn't compiled here (xstyle needs the StyleX compiler;