Skip to content

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.md
new file mode 100644
index 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`)
+
+@josephfarina
diff --git a/docs/specs/AST-042-cli-command-admission/spec.md b/docs/specs/AST-042-cli-command-admission/spec.md
index 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 tiered
bar.
+## 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 questions
None.
diff --git a/packages/cli/authoring/doctypes/command/command.doc.mjs b/packages/cli/authoring/doctypes/command/command.doc.mjs
index 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.ts
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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;