@astryxdesign/cli 0.6.4-canary.f0355e3 → 0.6.4-canary.f372744

package/README.md

@@ -90,6 +90,7 @@ Options:
 | `hook`        | List hooks or print hook docs                                                                 |
 | `init`        | Initialize the design system in your project                                                  |
 | `integration` | Author and verify an Astryx integration package                                               |
+| `layout`      | Generate XDS layouts from compressed expressions (XLE/XLO)                                    |
 | `search`      | Search components, hooks, docs, and templates in one ranked list                              |
 | `swizzle`     | Copy component source for customization                                                       |
 | `template`    | List, show, or scaffold page and block templates                                              |
@@ -478,6 +479,9 @@ Every response has a `type` discriminant. The full set is below (generated from
 | `integration.template-conflicts`  | The integration identity, structural issues, and non-blocking Core template-id conflicts as {id, severity: warning, integrationPackage, integrationType, integrationName, coreMatches, message, command}.                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `integration.component-conflicts` | The integration identity, structural issues, and non-blocking conflicts where an integration component name is also owned by Core; each conflict includes the exact package-qualified command.                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `integration.doc-conflicts`       | The integration identity, structural issues, and Core doc overlaps. Each finding includes `severity` (`info` \| `error`) and `relationship` (`replaces` \| `extends` \| `accidental`).                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `layout.expand`                   | The expansion: parsed form, generated TSX code, componentsUsed, states (count of useState hooks scaffolded), todos, blocksReferenced (each {name, mode}), warnings, and written (the output path, or null when nothing was written).                                                                                                                                                                                                                                                                                                                                                                                  |
+| `layout.check`                    | The validation result: a valid flag, the detected form, errors (each with line/col, message, formatted text, and suggestions), warnings, and the expression re-printed in both canonical surfaces (compact and outline).                                                                                                                                                                                                                                                                                                                                                                                              |
+| `layout.grammar`                  | The XLE/XLO grammar cheatsheet: a text field with the full reference plus an aliases map (short name → canonical component) generated from this install's registry.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 
 <!-- END GENERATED: response-types -->
 <!-- Generated by scripts/generate-cli-readme.mjs from the response-types EnumDoc. Run `pnpm -F @astryxdesign/cli readme`. -->
@@ -578,12 +582,12 @@ There is no factory: write a plain object. For editor autocomplete and
 type-checking, annotate it with the `AstryxConfig` type exported from
 `@astryxdesign/cli/authoring`.
 
-| Field                         | Type                           | Purpose                                                                                                                  |
-| ----------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
-| `integrations`                | `string[]`                     | Integration package names to load (see [Integrations](#integrations)).                                                   |
-| `issuesUrl`                   | `string`                       | Where "report an issue" links point for your project. Defaults to the core issue tracker.                                |
-| `hooks.postCodemod`           | `PostCodemodHook[]`            | Commands to run after `astryx upgrade` applies codemods (e.g. reinstall, rebuild, reformat).                             |
-| `experimental.xle.components` | `Record<string, XleComponent>` | No effect. Its only reader was the removed `layout` command. Still accepted so existing configs keep loading; delete it. |
+| Field                         | Type                           | Purpose                                                                                         |
+| ----------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------- |
+| `integrations`                | `string[]`                     | Integration package names to load (see [Integrations](#integrations)).                          |
+| `issuesUrl`                   | `string`                       | Where "report an issue" links point for your project. Defaults to the core issue tracker.       |
+| `hooks.postCodemod`           | `PostCodemodHook[]`            | Commands to run after `astryx upgrade` applies codemods (e.g. reinstall, rebuild, reformat).    |
+| `experimental.xle.components` | `Record<string, XleComponent>` | Register app-local components so layout (XLE) expressions can reference them by name. Unstable. |
 
 The config is validated against a strict schema when the CLI loads it, so an
 unknown field is a hard error rather than a silent no-op. `astryx doctor`

package/api/index.d.mts

@@ -33,12 +33,14 @@ export * from "./gap-report/gap-report.type.mjs";
 export * from "./upgrade/upgrade.type.mjs";
 export * from "./init/init.type.mjs";
 export * from "./doctor/doctor.type.mjs";
+export * from "./layout/layout.type.mjs";
 export * from "./integration/integration-authoring.type.mjs";
 export * from "./integration/pack-check.type.mjs";
 export * from "./integration/validate-integration.type.mjs";
 export * from "./integration/authoring-checks.type.mjs";
 export type Logger = import("./logger.mjs").Logger;
 export { themeBuild, themeAdd, themeTemplate, themeList, themeListAvailable, themeTargets, themePaletteGenerate, generateTonalPalette, listThemes } from "./theme/theme.mjs";
+export { layoutExpand, layoutCheck, layoutGrammar } from "./layout/layout.mjs";
 export { integrationAdd, integrationAddAgentDoc, integrationAddCodemod, integrationAddComponent, integrationAddDoc, integrationAddTemplate } from "./integration/add-contribution.mjs";
 export { validateIntegration, summarizeIssues } from "./integration/validate-integration.mjs";
 export { integrationTemplateConflicts, integrationComponentConflicts, integrationDocConflicts } from "./integration/authoring-checks.mjs";

package/api/index.mjs

@@ -44,6 +44,7 @@ export {gapReport} from './gap-report/gap-report.mjs';
 export {upgrade} from './upgrade/upgrade.mjs';
 export {init} from './init/init.mjs';
 export {doctor} from './doctor/doctor.mjs';
+export {layoutExpand, layoutCheck, layoutGrammar} from './layout/layout.mjs';
 export {
   integrationAdd,
   integrationAddAgentDoc,
@@ -92,6 +93,7 @@ export * from './gap-report/gap-report.type.mjs';
 export * from './upgrade/upgrade.type.mjs';
 export * from './init/init.type.mjs';
 export * from './doctor/doctor.type.mjs';
+export * from './layout/layout.type.mjs';
 export * from './integration/integration-authoring.type.mjs';
 export * from './integration/pack-check.type.mjs';
 export * from './integration/validate-integration.type.mjs';

package/api/json/index.ts

@@ -26,6 +26,7 @@ export type * from '../gap-report/gap-report.type.mjs';
 export type * from '../upgrade/upgrade.type.mjs';
 export type * from '../init/init.type.mjs';
 export type * from '../doctor/doctor.type.mjs';
+export type * from '../layout/layout.type.mjs';
 export type * from '../integration/validate-integration.type.mjs';
 export type * from '../integration/authoring-checks.type.mjs';
 export type * from '../integration/pack-check.type.mjs';

package/api/layout/_adapter.d.mts

@@ -0,0 +1,34 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/** @param {import('../../foundation/xle/xle-ast').RawIssue} issue */
+export function formatIssue(issue: import("../../foundation/xle/xle-ast").RawIssue): string;
+/**
+ * Parse + validate, throwing structured XDSErrors on failure.
+ * Returns {doc, registry, blocks, warnings}.
+ *
+ * @param {string} expression
+ * @param {{form?: 'compact'|'outline'|'auto', loose?: boolean, cwd?: string}} [options]
+ */
+export function analyze(expression: string, { form, loose, cwd }?: {
+    form?: "compact" | "outline" | "auto";
+    loose?: boolean;
+    cwd?: string;
+}): Promise<{
+    doc: import("../../foundation/xle/xle-ast").XLEDoc;
+    registry: import("../../foundation/xle/xle-ast").Registry;
+    blocks: LayoutBlock[];
+    errors: import("../../foundation/xle/xle-ast").RawIssue[];
+    warnings: import("../../foundation/xle/xle-ast").RawIssue[];
+}>;
+export type LayoutBlock = {
+    dirName: string;
+    name: string;
+    kind: "template" | "component";
+    type?: string | undefined;
+    description?: string | undefined;
+    category?: string | undefined;
+    importPath?: string | undefined;
+    filePath?: string | undefined;
+    isDefault?: boolean | undefined;
+};

package/api/layout/_adapter.mjs

@@ -0,0 +1,148 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Shared analysis layer for the `layout` command's expand/check leaves.
+ *
+ * Loads the block catalog (template blocks + app-registered components), builds
+ * the branch registry, and parses+validates a layout expression into a doc +
+ * issues. Both the expand and check leaves sit on `analyze`; neither parses or
+ * validates directly. (The grammar leaf needs none of this — it only reads the
+ * registry alias table.)
+ *
+ * @input  expression string (+ options)
+ * @output analyze() -> {doc, registry, blocks, errors, warnings}; formatIssue()
+ * @position api — shared core over lib/xle; leaves in expand/ + check/ project it
+ */
+
+import {AstryxError} from '../error.mjs';
+import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
+import {parse, XLEParseError} from '../../foundation/xle/parse.mjs';
+import {validate} from '../../foundation/xle/validate.mjs';
+import {buildRegistry} from '../../foundation/xle/registry.mjs';
+import {discoverTemplates} from '../template/template.mjs';
+import {Project} from '../../foundation/config/project.mjs';
+
+/**
+ * @typedef {object} LayoutBlock
+ * @property {string} dirName
+ * @property {string} name
+ * @property {'template'|'component'} kind
+ * @property {string} [type]
+ * @property {string} [description]
+ * @property {string} [category]
+ * @property {string} [importPath]
+ * @property {string} [filePath]
+ * @property {boolean} [isDefault]
+ */
+
+/**
+ * The catalog a `{hint}` can resolve to: template blocks (spliced inline) plus
+ * any app-registered local components from astryx.config.mjs
+ * `experimental.xle.components` (imported by name). App components are how XLE
+ * reaches domain pieces — the KpiCard/chart/drawer set that the
+ * @astryxdesign/core registry can't see.
+ *
+ * @param {string} cwd
+ * @returns {Promise<LayoutBlock[]>}
+ */
+async function loadBlocks(cwd) {
+  /** @type {LayoutBlock[]} */
+  const blocks = [];
+  try {
+    const all = await discoverTemplates(cwd);
+    const templates = all.filter(template => template.type === 'block');
+    /** @type {Map<string, import('../../foundation/discovery/template-adapter.mjs').DiscoveredTemplate>} */
+    const byId = new Map();
+    // Exact ids are the fallback. Active replacement aliases override them in a
+    // second pass, matching template() regardless of discovery/display order.
+    for (const template of templates) byId.set(template.dirName, template);
+    for (const template of templates) {
+      if (template.replaces != null) byId.set(template.replaces, template);
+    }
+    for (const [id, template] of byId) {
+      blocks.push({...template, dirName: id, kind: 'template'});
+    }
+  } catch {
+    // discovery is best-effort
+  }
+  try {
+    const project = await Project.load(cwd);
+    /** @type {Record<string, {from?: string, description?: string, default?: boolean}>} */
+    const components = project.config.experimental?.xle?.components ?? {};
+    for (const [name, spec] of Object.entries(components)) {
+      const importPath = spec.from;
+      if (!importPath) continue;
+      blocks.push({
+        type: 'block',
+        kind: 'component',
+        dirName: name,
+        name,
+        description: spec.description ?? '',
+        category: 'app',
+        importPath,
+        isDefault: Boolean(spec.default),
+      });
+    }
+  } catch {
+    // config is optional
+  }
+  return blocks;
+}
+
+/** @param {import('../../foundation/xle/xle-ast').RawIssue} issue */
+export function formatIssue(issue) {
+  const where = issue.line != null ? `line ${issue.line}: ` : '';
+  return `${where}${issue.message}`;
+}
+
+/**
+ * Parse + validate, throwing structured XDSErrors on failure.
+ * Returns {doc, registry, blocks, warnings}.
+ *
+ * @param {string} expression
+ * @param {{form?: 'compact'|'outline'|'auto', loose?: boolean, cwd?: string}} [options]
+ */
+export async function analyze(
+  expression,
+  {form = 'auto', loose = false, cwd = process.cwd()} = {},
+) {
+  // Validate inputs in the API (not just the CLI): an empty expression or an
+  // unknown --form must error, not silently parse as an empty/compact layout.
+  if (typeof expression !== 'string' || expression.trim() === '') {
+    throw new AstryxError(
+      'Layout expression is empty.',
+      undefined,
+      ERROR_CODES.ERR_INVALID_ARGUMENT,
+    );
+  }
+  if (form !== 'compact' && form !== 'outline' && form !== 'auto') {
+    throw new AstryxError(
+      `Invalid form "${form}". Must be one of: compact, outline, auto.`,
+      undefined,
+      ERROR_CODES.ERR_INVALID_OPTION,
+    );
+  }
+  const registry =
+    /** @type {import('../../foundation/xle/xle-ast').Registry} */ (
+      /** @type {unknown} */ (await buildRegistry({cwd}))
+    );
+  const blocks = await loadBlocks(cwd);
+
+  /** @type {import('../../foundation/xle/xle-ast').XLEDoc} */
+  let doc;
+  try {
+    doc = parse(expression, {form});
+  } catch (e) {
+    if (e instanceof XLEParseError) {
+      throw new AstryxError(
+        `Layout expression syntax error at line ${e.line}, col ${e.col}: ${e.message}`,
+        undefined,
+        ERROR_CODES.ERR_LAYOUT_PARSE,
+      );
+    }
+    throw e;
+  }
+
+  const {errors, warnings} = validate(doc, registry, blocks, {loose});
+  return {doc, registry, blocks, errors, warnings};
+}

package/api/layout/check/check.d.mts

@@ -0,0 +1,16 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * `astryx layout check "<expr>" [--form compact|outline]`
+ * Validates without expanding; echoes both canonical surfaces.
+ *
+ * @param {string} expression
+ * @param {{form?: 'compact'|'outline'|'auto', loose?: boolean, cwd?: string}} [options]
+ * @returns {Promise<import('../layout.type.mjs').LayoutCheckResponse>}
+ */
+export function layoutCheck(expression: string, options?: {
+    form?: "compact" | "outline" | "auto";
+    loose?: boolean;
+    cwd?: string;
+}): Promise<import("../layout.type.mjs").LayoutCheckResponse>;

package/api/layout/check/check.mjs

@@ -0,0 +1,40 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx layout check` leaf — validate a layout expression without
+ * expanding, echoing both canonical surfaces (compact + outline). Resolution +
+ * validation come from ../_adapter.mjs (analyze); this leaf projects the
+ * `layout.check` envelope.
+ *
+ * @input  expression string (+ options)
+ * @output {type:'layout.check', data}
+ * @position api — leaf over ../_adapter.mjs + lib/xle/print
+ */
+
+import {toCompact, toOutline} from '../../../foundation/xle/print.mjs';
+import {analyze, formatIssue} from '../_adapter.mjs';
+
+/**
+ * `astryx layout check "<expr>" [--form compact|outline]`
+ * Validates without expanding; echoes both canonical surfaces.
+ *
+ * @param {string} expression
+ * @param {{form?: 'compact'|'outline'|'auto', loose?: boolean, cwd?: string}} [options]
+ * @returns {Promise<import('../layout.type.mjs').LayoutCheckResponse>}
+ */
+export async function layoutCheck(expression, options = {}) {
+  const {form = 'auto', loose = false, cwd = process.cwd()} = options;
+  const {doc, errors, warnings} = await analyze(expression, {form, loose, cwd});
+
+  return {
+    type: 'layout.check',
+    data: {
+      valid: errors.length === 0,
+      form: doc.form,
+      errors: errors.map(e => ({...e, formatted: formatIssue(e)})),
+      warnings: warnings.map(formatIssue),
+      compact: toCompact(doc),
+      outline: toOutline(doc),
+    },
+  };
+}

package/api/layout/expand/expand.d.mts

@@ -0,0 +1,22 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * `astryx layout expand "<expr>" [path]`
+ *
+ * @param {string} expression
+ * @param {object} [options]
+ * @param {string} [options.targetPath] - write TSX here (validated against cwd)
+ * @param {'compact'|'outline'|'auto'} [options.form]
+ * @param {boolean} [options.loose] - downgrade unknown {hints} to TODO warnings
+ * @param {string} [options.name] - generated component name
+ * @param {string} [options.cwd]
+ * @returns {Promise<import('../layout.type.mjs').LayoutExpandResponse>}
+ */
+export function layoutExpand(expression: string, options?: {
+    targetPath?: string | undefined;
+    form?: "compact" | "auto" | "outline" | undefined;
+    loose?: boolean | undefined;
+    name?: string | undefined;
+    cwd?: string | undefined;
+}): Promise<import("../layout.type.mjs").LayoutExpandResponse>;

package/api/layout/expand/expand.mjs

@@ -0,0 +1,155 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx layout expand` leaf — expand a validated layout expression into
+ * XDS TSX (optionally written to disk). Resolution + validation come from
+ * ../_adapter.mjs (analyze); this leaf owns block-module assembly, code
+ * generation, and the path-safe write, and projects the `layout.expand` envelope.
+ *
+ * @input  expression string (+ options)
+ * @output {type:'layout.expand', data}
+ * @position api — leaf over ../_adapter.mjs + lib/xle/expand
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {AstryxError} from '../../error.mjs';
+import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
+import {assertWithin, isFilePathArg, PathSafetyError} from '../../../foundation/fs/path-safety.mjs';
+import {detectForm} from '../../../foundation/xle/parse.mjs';
+import {expand} from '../../../foundation/xle/expand.mjs';
+import {stripTemplateAssetRefs} from '../../template/template.mjs';
+import {analyze, formatIssue} from '../_adapter.mjs';
+
+/** @param {string} name */
+const normKey = (name) => name.toLowerCase().replace(/[^a-z0-9]/g, '');
+
+/**
+ * Collect the block names referenced by {hints} anywhere in the doc.
+ * @param {import('../../../foundation/xle/xle-ast').XLEDoc} doc
+ */
+function collectHintNames(doc) {
+  /** @type {Set<string>} */
+  const names = new Set();
+  /** @param {import('../../../foundation/xle/xle-ast').XLEItem} node */
+  const visitNode = (node) => {
+    if (!node || node.kind === 'group') {
+      (node?.children || []).forEach(visit);
+      return;
+    }
+    if (node.hint?.block) names.add(node.hint.block.name);
+    for (const slot of node.slots || []) {
+      const value = slot.value;
+      if (value && typeof value === 'object' && 'hint' in value && value.hint?.block) {
+        names.add(value.hint.block.name);
+      }
+      if (value && typeof value === 'object' && 'subexpr' in value) {
+        (value.subexpr || []).forEach(visit);
+      }
+    }
+    (node.children || []).forEach(visit);
+  };
+  /** @param {import('../../../foundation/xle/xle-ast').XLEItem} item */
+  const visit = (item) => (item?.kind === 'group' ? item.children.forEach(visit) : visitNode(item));
+  doc.roots.forEach(visit);
+  doc.overlays.forEach(visit);
+  return names;
+}
+
+/**
+ * Build the blockModules map expand() needs: import-mode for app components,
+ * splice-mode (reading + asset-stripping the block source) for template blocks.
+ * Only blocks actually referenced are read.
+ *
+ * @param {import('../../../foundation/xle/xle-ast').XLEDoc} doc
+ * @param {import('../_adapter.mjs').LayoutBlock[]} blocks
+ * @returns {Map<string, import('../../../foundation/xle/xle-ast').BlockModule>}
+ */
+function buildBlockModules(doc, blocks) {
+  const referenced = collectHintNames(doc);
+  if (referenced.size === 0) return new Map();
+  const byKey = new Map(blocks.map(b => [normKey(b.dirName), b]));
+  /** @type {Map<string, import('../../../foundation/xle/xle-ast').BlockModule>} */
+  const modules = new Map();
+  for (const name of referenced) {
+    const block = byKey.get(normKey(name));
+    if (!block) continue;
+    if (block.kind === 'component') {
+      modules.set(name, /** @type {import('../../../foundation/xle/xle-ast').BlockModule} */ (/** @type {unknown} */ ({mode: 'import', componentName: block.name, importPath: block.importPath, isDefault: block.isDefault})));
+    } else if (block.filePath && fs.existsSync(block.filePath)) {
+      modules.set(name, /** @type {import('../../../foundation/xle/xle-ast').BlockModule} */ ({mode: 'splice', componentName: block.dirName, source: stripTemplateAssetRefs(fs.readFileSync(block.filePath, 'utf-8'))}));
+    }
+  }
+  return modules;
+}
+
+/**
+ * `astryx layout expand "<expr>" [path]`
+ *
+ * @param {string} expression
+ * @param {object} [options]
+ * @param {string} [options.targetPath] - write TSX here (validated against cwd)
+ * @param {'compact'|'outline'|'auto'} [options.form]
+ * @param {boolean} [options.loose] - downgrade unknown {hints} to TODO warnings
+ * @param {string} [options.name] - generated component name
+ * @param {string} [options.cwd]
+ * @returns {Promise<import('../layout.type.mjs').LayoutExpandResponse>}
+ */
+export async function layoutExpand(expression, options = {}) {
+  const {targetPath, form = 'auto', loose = false, name, cwd = process.cwd()} = options;
+  const {doc, registry, blocks, errors, warnings} = await analyze(expression, {form, loose, cwd});
+
+  if (errors.length > 0) {
+    throw new AstryxError(
+      `Layout expression is invalid:\n` + errors.map(e => `  - ${formatIssue(e)}`).join('\n'),
+      errors.flatMap(e => (e.suggestions || []).map(s => ({name: s, reason: 'did you mean this?'}))),
+      ERROR_CODES.ERR_LAYOUT_INVALID,
+    );
+  }
+
+  const componentName = name || 'GeneratedLayout';
+  if (!/^[A-Z][A-Za-z0-9]*$/.test(componentName)) {
+    throw new AstryxError(
+      `--name must be a PascalCase component name, got '${componentName}'`,
+      undefined,
+      ERROR_CODES.ERR_INVALID_ARGUMENT,
+    );
+  }
+  const blockModules = buildBlockModules(doc, blocks);
+  const result = expand(doc, registry, {componentName, blockModules});
+
+  let written = null;
+  if (targetPath) {
+    // The guard sees the file that will be written, not only its directory:
+    // a symlink at that name would otherwise carry the write outside the root.
+    const fileTarget = isFilePathArg(targetPath)
+      ? targetPath
+      : path.join(targetPath, `${componentName}.tsx`);
+    let filePath;
+    try {
+      filePath = assertWithin(fileTarget, cwd, {label: 'layout target path'});
+    } catch (err) {
+      if (err instanceof PathSafetyError) {
+        throw new AstryxError(err.message, undefined, ERROR_CODES.ERR_PATH_TRAVERSAL);
+      }
+      throw err;
+    }
+    fs.mkdirSync(path.dirname(filePath), {recursive: true});
+    fs.writeFileSync(filePath, result.code);
+    written = path.relative(cwd, filePath);
+  }
+
+  return {
+    type: 'layout.expand',
+    data: {
+      form: form === 'auto' ? detectForm(expression) : form,
+      code: result.code,
+      componentsUsed: result.componentsUsed,
+      states: result.states,
+      todos: result.todos,
+      blocksReferenced: [...blockModules.entries()].map(([name, m]) => ({name, mode: m.mode})),
+      warnings: warnings.map(formatIssue),
+      written,
+    },
+  };
+}

package/api/layout/expand/expand.path-safety.test.mjs

@@ -0,0 +1,53 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Path-safety tests for the `layout.expand` write. The file written, not
+ * only the directory it lands in, must stay inside the project root.
+ */
+
+import {describe, it, expect, beforeAll} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {layoutExpand} from '../layout.mjs';
+import {buildRegistry} from '../../../foundation/xle/registry.mjs';
+
+const SLOW = 30_000;
+
+// The registry imports every component doc on first use; warm it once.
+beforeAll(async () => {
+  await buildRegistry();
+}, 120_000);
+
+describe('layout.expand — write confinement', () => {
+  it('rejects a directory target whose generated file is a symlink leading outside cwd', async () => {
+    // Inside the workspace so @astryxdesign/core resolves.
+    const cwd = fs.mkdtempSync(path.join(process.cwd(), '.xle-confine-test-'));
+    const outside = fs.mkdtempSync(path.join(os.tmpdir(), 'xle-confine-outside-'));
+    try {
+      const victim = path.join(outside, 'victim.tsx');
+      fs.writeFileSync(victim, 'OUTSIDE');
+      fs.mkdirSync(path.join(cwd, 'out'));
+      fs.symlinkSync(victim, path.join(cwd, 'out', 'GeneratedLayout.tsx'));
+
+      await expect(
+        layoutExpand('V > B', {targetPath: './out', cwd}),
+      ).rejects.toMatchObject({code: 'ERR_PATH_TRAVERSAL'});
+      expect(fs.readFileSync(victim, 'utf-8')).toBe('OUTSIDE');
+    } finally {
+      fs.rmSync(cwd, {recursive: true, force: true});
+      fs.rmSync(outside, {recursive: true, force: true});
+    }
+  }, SLOW);
+
+  it('still writes <Name>.tsx into a plain directory target', async () => {
+    const cwd = fs.mkdtempSync(path.join(process.cwd(), '.xle-confine-test-'));
+    try {
+      const result = await layoutExpand('V > B', {targetPath: './out', name: 'Demo', cwd});
+      expect(result.data.written).toBe(path.join('out', 'Demo.tsx'));
+      expect(fs.existsSync(path.join(cwd, 'out', 'Demo.tsx'))).toBe(true);
+    } finally {
+      fs.rmSync(cwd, {recursive: true, force: true});
+    }
+  }, SLOW);
+});

package/api/layout/grammar/grammar.d.mts

@@ -0,0 +1,13 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * `astryx layout grammar` — the agent cheatsheet, with the alias table
+ * generated from this branch's registry (never hand-maintained).
+ *
+ * @param {{cwd?: string}} [options]
+ * @returns {Promise<import('../layout.type.mjs').LayoutGrammarResponse>}
+ */
+export function layoutGrammar(options?: {
+    cwd?: string;
+}): Promise<import("../layout.type.mjs").LayoutGrammarResponse>;

package/api/layout/grammar/grammar.mjs

@@ -0,0 +1,87 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx layout grammar` leaf — the agent cheatsheet, with the alias
+ * table generated from this branch's registry (never hand-maintained). Reads
+ * only the registry; shares nothing with expand/check, so it has no adapter.
+ *
+ * @output {type:'layout.grammar', data}
+ * @position api — leaf over lib/xle/registry
+ */
+
+import {buildRegistry} from '../../../foundation/xle/registry.mjs';
+import {MAX_REPEAT} from '../../../foundation/xle/expand.mjs';
+
+/**
+ * `astryx layout grammar` — the agent cheatsheet, with the alias table
+ * generated from this branch's registry (never hand-maintained).
+ *
+ * @param {{cwd?: string}} [options]
+ * @returns {Promise<import('../layout.type.mjs').LayoutGrammarResponse>}
+ */
+export async function layoutGrammar(options = {}) {
+  const {cwd = process.cwd()} = options;
+  const registry = await buildRegistry({cwd});
+
+  /** @type {string[]} */
+  const aliasLines = [];
+  /** @type {Map<string, string[]>} */
+  const byTarget = new Map();
+  for (const [alias, target] of registry.aliases) {
+    if (!byTarget.has(target)) byTarget.set(target, []);
+    byTarget.get(target)?.push(alias);
+  }
+  for (const [target, aliases] of [...byTarget.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    aliasLines.push(`${aliases.join('/')}=${target}`);
+  }
+
+  const text = `XLE/XLO — XDS layout expressions (branch-generated; aliases reflect this install)
+
+WORKFLOW
+  astryx layout check "<expr>"           validate; echoes canonical compact + outline forms
+  astryx layout expand "<expr>" [path]   emit validated TSX (path optional; --name <Pascal>)
+  Errors carry line/col + suggestions. Fix and resubmit; nothing is guessed.
+
+TWO SURFACES, ONE LANGUAGE (autodetected; --form to force)
+  compact: A[cp6 @topNav=TN] > L > LC > S[p6] > (C{card-callout}*4) + T
+  outline: indentation = nesting · same-indent = siblings · "repeat N:" block = (...)*N
+           slot lines:  topNav: TN     (or a block:  topNav:\\n    TN ...)
+
+NODE ANATOMY   Name#id.enum"payload"[attrs]{hint}*N > children
+  .enum        unique enum value of any prop:  Bd.success  Tx.lg  B.primary
+  "payload"    primary text prop (label/title/heading) or text child:  TI"Email"  B"Save"
+  {hint}       kebab-case template/component reference (see TEMPLATE REFERENCING) — NEVER text
+  *N / xN      repeat, at most ${MAX_REPEAT} copies (use $ for the counter:  Tk"item-$"*3)
+  trailing !   initial selection for scaffolded state:  Tab"Overview"!
+
+ATTRS [...] (outline: bare tokens after the name, no brackets)
+  fused        p6 g4 c4 w240 h2 cp2 mw960 rg2 cg2  (per-component: padding lives on Card/Section/AppShell.cp — p6 on AppShell/Layout/VStack errors with a correction)
+  key=value    t=email href='/x' c{min:340} dv=[top,bottom] — keys validated per component
+  flags        req opt dis striped hover divider … (isX/hasX props) · negate: !scroll
+  align        j= main axis, a= cross axis — expander picks hAlign/vAlign per stack direction
+  slots        @slotName=Node | @slotName=(sub > expr) | @slotName='text' | @slotName=#id
+  trigger      opens=#id  (a plain attr, no @ — binds an onClick that opens the overlay)
+  fill         on a stack child → wraps in <StackItem size="fill">
+
+TEMPLATE REFERENCING  ({hint} pulls in real content — this is how XLE reaches past the @astryxdesign/core shell)
+  C{card-callout}              splice a template block (astryx template --list --type block):
+                              the block is co-defined once in the file, referenced, imports merged
+  {kpi-card}                   standalone reference (no wrapper element) — place a component directly
+  {kpi-card}*4                 repeat a reference; the definition/import is emitted once
+  app components               register local ones in astryx.config.mjs to import them by name:
+                                 export default {experimental: {xle: {components: {KpiCard: {from: '@/components/KpiCard'}}}}}
+                               then {kpi-card} → import {KpiCard} + <KpiCard /> (kebab ↔ Pascal)
+
+STRUCTURE THE EXPANDER HANDLES
+  Layout > LH + LC + LF + LP   children auto-route into header/content/footer/start slots
+  T > (TR>THC*4) + (TR>TC*4)*6 rows partition into TableHeader/TableBody automatically
+  TabList/inputs               required value+onChange scaffold typed useState automatically
+  overlays                     compact: tree ;; Dlg#confirm[...] · outline: overlays: section
+                               trigger: B"Delete"[opens=#confirm]
+
+ALIASES (full component names always valid; XDS prefix optional)
+  ${aliasLines.join('  ')}
+`;
+
+  return {type: 'layout.grammar', data: {text, aliases: Object.fromEntries(registry.aliases)}};
+}