@astryxdesign/cli 0.1.1 → 0.1.2-canary.2149fa3

package/src/commands/build-theme.mjs

@@ -17,10 +17,15 @@ import * as path from 'node:path';
 import {pathToFileURL, fileURLToPath} from 'node:url';
 import {createJiti} from 'jiti';
 import {getRunPrefix} from '../utils/package-manager.mjs';
-import {sanitizeName, PathSafetyError} from '../utils/path-safety.mjs';
+import {
+  sanitizeName,
+  PathSafetyError,
+  isNonInteractive,
+} from '../utils/path-safety.mjs';
 import {jsonOut, humanLog} from '../lib/json.mjs';
 import {cliError} from '../lib/cli-error.mjs';
 import {ERROR_CODES} from '../lib/error-codes.mjs';
+import {themeAdd, listThemes} from '../api/theme-add.mjs';
 
 // Import shared theme processing from core. `astryx theme build` MUST produce the
 // exact same CSS as the `<Theme>` runtime, so it has exactly one generation
@@ -75,6 +80,18 @@ function toIdentifier(name) {
   return name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
 }
 
+/**
+ * Import specifier for install/scaffold instructions. Drops a leading `src/`
+ * from the cwd-relative dir (most consumers import from a file under src/) but
+ * keeps the rest of the path (e.g. `themes/gothic`). Callers note the path is
+ * relative to the consumer's file.
+ */
+function importSpecifier(relDir, base) {
+  const normalized = relDir === '.' ? '' : relDir;
+  const withinSrc = normalized.replace(/^src\/?/, '').replace(/\/+$/, '');
+  return withinSrc ? `./${withinSrc}/${base}` : `./${base}`;
+}
+
 /**
  * Convert a kebab-case component name to PascalCase.
  * e.g. 'button' → 'Button', 'progress-bar' → 'ProgressBar', 'avatar-status-dot' → 'AvatarStatusDot'
@@ -443,7 +460,7 @@ const KNOWN_COMPONENTS = {
   breadcrumbs: ['variant'],
   button: ['variant', 'size'],
   calendar: [],
-  card: [],
+  card: ['variant'],
   center: [],
   checkboxinput: [],
   collapsible: [],
@@ -737,10 +754,12 @@ export function registerTheme(program) {
       const sourceRelative = path.relative(process.cwd(), filePath);
       const buildCommand = `astryx theme build ${sourceRelative}${options.out ? ' --out ' + path.relative(process.cwd(), path.resolve(process.cwd(), options.out)) : ''}`;
 
-      // Determine output path
+      // Derive the default CSS name from the theme name so .css/.js/.d.ts
+      // share one scheme; an explicit --out still wins.
+      const baseName = themeDef.name;
       const outPath = options.out
         ? path.resolve(process.cwd(), options.out)
-        : filePath.replace(/\.(ts|tsx|js|jsx|mjs)$/, '.css');
+        : path.join(path.dirname(filePath), `${baseName}.css`);
 
       const displayTheme = resolvedTheme || themeDef;
       const tokenCount = displayTheme.tokens ? Object.keys(displayTheme.tokens).length : 0;
@@ -753,7 +772,6 @@ export function registerTheme(program) {
       // was left as orphaned half-built output. Stage-then-commit avoids
       // that.
       const outDir = path.dirname(outPath);
-      const baseName = themeDef.name;
       const jsPath = path.join(outDir, `${baseName}.js`);
       const dtsPath = path.join(outDir, `${baseName}.d.ts`);
 
@@ -834,18 +852,16 @@ export function registerTheme(program) {
         });
       }
 
-      // Print install instructions
-      const relDir = path.relative(process.cwd(), outDir);
-      // When the output dir is the cwd, relDir is empty — avoid emitting a
-      // double-slash import path like './/<name>'. Build a './<relDir>/'
-      // prefix that collapses to './' when relDir is empty.
-      const importPrefix = relDir ? `./${relDir}/` : './';
+      const relOutDir = path.relative(process.cwd(), outDir) || '.';
+      const cssBase = path.basename(outPath, '.css');
+      const jsImport = importSpecifier(relOutDir, baseName);
+      const cssImport = importSpecifier(relOutDir, cssBase) + '.css';
       const exportName = `${toIdentifier(baseName)}Theme`;
       humanLog(`
-Install in your app:
+Install in your app (paths are relative to a file in src/ — adjust if yours lives elsewhere):
 
-  import { ${exportName} } from '${importPrefix}${baseName}';
-  import '${importPrefix}${baseName}.css';
+  import { ${exportName} } from '${jsImport}';
+  import '${cssImport}';
 
   <Theme theme={${exportName}}>
     <App />
@@ -853,9 +869,9 @@ Install in your app:
 
 Or with a <link> tag:
 
-  import { ${exportName} } from '${importPrefix}${baseName}';
+  import { ${exportName} } from '${jsImport}';
 
-  <link rel="stylesheet" href="${importPrefix}${baseName}.css" />
+  <link rel="stylesheet" href="${cssImport}" />
   <Theme theme={${exportName}}>
     <App />
   </Theme>
@@ -871,4 +887,157 @@ Or with a <link> tag:
         humanLog('');
       }
     });
+
+  theme
+    .command('list')
+    .description('List themes available to add')
+    .action(async () => {
+      const json = program.opts().json || false;
+      let result;
+      try {
+        result = await themeAdd(undefined, {list: true, cwd: process.cwd()});
+      } catch (e) {
+        cliError(e.message, {suggestions: e.suggestions || [], code: e.code});
+        return;
+      }
+
+      if (json) return jsonOut(result.type, result.data);
+
+      const themes = result.data;
+      if (themes.length === 0) {
+        humanLog('\nNo themes are bundled with this CLI build.\n');
+        return;
+      }
+      humanLog('\nThemes:\n');
+      for (const t of themes) {
+        const tag = t.maintained ? ' (maintained)' : '';
+        humanLog(`  ${t.slug}${tag}`);
+        if (t.description) humanLog(`    ${t.description}`);
+      }
+      humanLog('\nUsage:');
+      humanLog('  astryx theme add <slug> [target-path]   Scaffold a theme file you own\n');
+    });
+
+  theme
+    .command('add [slug] [path]')
+    .description('Scaffold a theme into your project as editable source')
+    .option('-f, --overwrite', 'Overwrite existing files without prompting')
+    .option('--list', 'List available themes')
+    .action(async (slug, targetPath, options) => {
+      const json = program.opts().json || false;
+
+      // Only prompt with a real TTY on stdin — a piped/redirected stdin would
+      // make clack hang. Non-interactive callers fall through to the API's
+      // ERR_FILE_EXISTS guard.
+      const interactive =
+        !json && !isNonInteractive({json}) && Boolean(process.stdin.isTTY);
+      if (slug && !options.list && !options.overwrite && interactive) {
+        const collision = await detectThemeCollision(slug, targetPath);
+        if (collision) {
+          const rel = path.relative(process.cwd(), collision) || collision;
+          const p = await import('@clack/prompts');
+          const confirmed = await p.confirm({
+            message: `Overwrite existing file ${rel}?`,
+            initialValue: false,
+          });
+          if (p.isCancel(confirmed)) {
+            p.cancel('Cancelled.');
+            return;
+          }
+          if (!confirmed) {
+            humanLog('Aborted. Re-run with --overwrite to replace the file.');
+            return;
+          }
+          options.overwrite = true;
+        }
+      }
+
+      let result;
+      try {
+        result = await themeAdd(slug, {
+          list: options.list,
+          targetPath,
+          overwrite: options.overwrite,
+          cwd: process.cwd(),
+        });
+      } catch (e) {
+        cliError(e.message, {suggestions: e.suggestions || [], code: e.code});
+        return;
+      }
+
+      if (json) return jsonOut(result.type, result.data);
+
+      if (result.type === 'theme.list') {
+        const themes = result.data;
+        humanLog('\nThemes:\n');
+        for (const t of themes) {
+          const tag = t.maintained ? ' (maintained)' : '';
+          humanLog(`  ${t.slug}${tag}`);
+          if (t.description) humanLog(`    ${t.description}`);
+        }
+        humanLog('\nUsage:');
+        humanLog('  astryx theme add <slug> [target-path]   Scaffold a theme file you own\n');
+        return;
+      }
+
+      // theme.add — print where files landed + how to use the theme.
+      const {displayName, outputDir, entry, exportName, files} = result.data;
+      humanLog(`\n✓ Added ${displayName} theme to ${outputDir}/`);
+      for (const f of files) {
+        humanLog(`  ${outputDir}/${f}`);
+      }
+      const entryModule = importSpecifier(
+        outputDir,
+        entry.replace(/\.tsx?$/, ''),
+      );
+      humanLog(`
+Use it in your app (import path is relative to a file in src/ — adjust if yours lives elsewhere):
+
+  import { ${exportName} } from '${entryModule}';
+
+  <Theme theme={${exportName}}>
+    <App />
+  </Theme>
+
+This is your copy of the ${displayName} theme — edit ${entry} to make it your own.
+`);
+    });
+}
+
+/**
+ * First existing file that scaffolding <slug> into <targetPath> would clobber,
+ * or null. Used to prompt before invoking the API; the API re-validates and
+ * owns any authoritative error.
+ *
+ * @param {string} slug
+ * @param {string} [targetPath]
+ * @returns {Promise<string|null>}
+ */
+async function detectThemeCollision(slug, targetPath) {
+  let themes;
+  try {
+    themes = listThemes();
+  } catch {
+    return null;
+  }
+  const match = themes.find(t => t.slug.toLowerCase() === slug.toLowerCase());
+  if (!match) return null;
+
+  const rawTarget = targetPath || path.join('src', 'themes', match.slug);
+  let resolvedDir;
+  try {
+    // Fail soft (null) on traversal; the API surfaces the real error.
+    const {assertWithin} = await import('../utils/path-safety.mjs');
+    resolvedDir = assertWithin(rawTarget, process.cwd(), {
+      label: 'theme target path',
+    });
+  } catch {
+    return null;
+  }
+
+  for (const name of match.files) {
+    const dest = path.join(resolvedDir, name);
+    if (fs.existsSync(dest)) return dest;
+  }
+  return null;
 }

package/src/commands/gap-report.mjs

@@ -132,7 +132,7 @@ export function registerGapReport(program) {
     .action(async () => {
       p.intro('Gap report setup');
 
-      const config = loadGapReportConfig();
+      const config = await loadGapReportConfig();
       const currentMode = !config.enabled
         ? 'disabled'
         : config.command
@@ -252,9 +252,14 @@ export function registerGapReport(program) {
         return;
       }
 
-      const config = loadGapReportConfig();
+      const config = await loadGapReportConfig();
       if (!config.enabled) {
-        if (json) return jsonError('Gap reporting is disabled', undefined, ERROR_CODES.ERR_GAP_REPORT_FAILED);
+        if (json)
+          return jsonError(
+            'Gap reporting is disabled',
+            undefined,
+            ERROR_CODES.ERR_GAP_REPORT_FAILED,
+          );
         humanLog(
           `Gap reporting is disabled (ASTRYX_GAP_REPORT=off or astryx.config.mjs).\n` +
             `Run \`${getRunPrefix()} astryx gap-report setup\` to configure.`,
@@ -295,7 +300,7 @@ export function registerGapReport(program) {
           return;
         }
 
-        const preview = buildGapReportPreview({
+        const preview = await buildGapReportPreview({
           component: options.component,
           category: options.category,
           intention: options.reason,
@@ -326,7 +331,7 @@ export function registerGapReport(program) {
         }
 
         try {
-          const url = createGapReport({
+          const url = await createGapReport({
             component: options.component,
             category: options.category,
             intention: options.reason,
@@ -343,7 +348,9 @@ export function registerGapReport(program) {
             humanLog('\nGap reporting is disabled via configuration.\n');
           }
         } catch (err) {
-          cliError(`Filing gap report failed: ${err.message}`, {code: ERROR_CODES.ERR_GAP_REPORT_FAILED});
+          cliError(`Filing gap report failed: ${err.message}`, {
+            code: ERROR_CODES.ERR_GAP_REPORT_FAILED,
+          });
           return;
         }
         return;
@@ -386,7 +393,8 @@ export function registerGapReport(program) {
           placeholder:
             'e.g. "Need a compact variant for use in dense data tables"',
           validate: val => {
-            if (!val.trim()) return 'Please describe what you were trying to do';
+            if (!val.trim())
+              return 'Please describe what you were trying to do';
           },
         }),
       );
@@ -406,7 +414,7 @@ export function registerGapReport(program) {
         source: 'interactive',
       };
 
-      const preview = buildGapReportPreview(previewArgs);
+      const preview = await buildGapReportPreview(previewArgs);
 
       // Always show the user exactly what would be filed before sending.
       p.note(
@@ -440,7 +448,7 @@ export function registerGapReport(program) {
       s.start('Filing gap report');
 
       try {
-        const url = createGapReport(previewArgs);
+        const url = await createGapReport(previewArgs);
         s.stop(url ? 'Gap report filed' : 'Gap reporting is disabled');
         if (url) {
           p.log.success(url);

package/src/commands/gap-report.test.mjs

@@ -40,9 +40,9 @@ describe('shouldActuallyFile', () => {
   });
 
   it('--dry-run wins over --commit (safety)', () => {
-    expect(
-      shouldActuallyFile({isTTY: true, commit: true, dryRun: true}),
-    ).toBe(false);
+    expect(shouldActuallyFile({isTTY: true, commit: true, dryRun: true})).toBe(
+      false,
+    );
   });
 });
 
@@ -54,7 +54,9 @@ describe('formatPreview', () => {
       title: '[gap] Button: missing compact variant',
       body: '## User Intention\n\nNeed a compact variant',
     });
-    expect(out).toContain('Would file GitHub issue on facebookexperimental/xds');
+    expect(out).toContain(
+      'Would file GitHub issue on facebookexperimental/xds',
+    );
     expect(out).toContain('[gap] Button');
     expect(out).toContain('Need a compact variant');
     expect(out).toContain('Labels: gap-report');
@@ -91,13 +93,14 @@ describe('ASTRYX_GAP_REPORT=off env var', () => {
   it('disables gap reporting when set to "off"', async () => {
     process.env.ASTRYX_GAP_REPORT = 'off';
     vi.resetModules();
-    const {loadGapReportConfig, createGapReport} = await import(
-      '../utils/github.mjs'
-    );
-    expect(loadGapReportConfig().enabled).toBe(false);
+    const {loadGapReportConfig, createGapReport} =
+      await import('../utils/github.mjs');
+    await expect(loadGapReportConfig()).resolves.toMatchObject({
+      enabled: false,
+    });
 
     // createGapReport must return null and never invoke gh.
-    const result = createGapReport({
+    const result = await createGapReport({
       component: 'Button',
       category: 'other',
       intention: 'test',
@@ -109,12 +112,16 @@ describe('ASTRYX_GAP_REPORT=off env var', () => {
     process.env.ASTRYX_GAP_REPORT = 'false';
     vi.resetModules();
     let mod = await import('../utils/github.mjs');
-    expect(mod.loadGapReportConfig().enabled).toBe(false);
+    await expect(mod.loadGapReportConfig()).resolves.toMatchObject({
+      enabled: false,
+    });
 
     process.env.ASTRYX_GAP_REPORT = '0';
     vi.resetModules();
     mod = await import('../utils/github.mjs');
-    expect(mod.loadGapReportConfig().enabled).toBe(false);
+    await expect(mod.loadGapReportConfig()).resolves.toMatchObject({
+      enabled: false,
+    });
   });
 });
 
@@ -133,16 +140,14 @@ describe('buildGapReportPreview', () => {
   it('renders title and body without invoking gh', async () => {
     vi.resetModules();
     const {buildGapReportPreview} = await import('../utils/github.mjs');
-    const preview = buildGapReportPreview({
+    const preview = await buildGapReportPreview({
       component: 'Button',
       category: 'missing_variant',
       intention: 'Need compact variant for tables',
     });
     expect(preview.mode).toBe('github');
     expect(preview.enabled).toBe(true);
-    expect(preview.title).toBe(
-      '[gap] Button: Need compact variant for tables',
-    );
+    expect(preview.title).toBe('[gap] Button: Need compact variant for tables');
     expect(preview.body).toContain('| **Component** | Button |');
     expect(preview.body).toContain('Need compact variant for tables');
     expect(preview.repo).toBe('facebookexperimental/xds');
@@ -152,7 +157,7 @@ describe('buildGapReportPreview', () => {
     process.env.ASTRYX_GAP_REPORT = 'off';
     vi.resetModules();
     const {buildGapReportPreview} = await import('../utils/github.mjs');
-    const preview = buildGapReportPreview({
+    const preview = await buildGapReportPreview({
       component: 'Button',
       category: 'other',
       intention: 'x',

package/src/commands/init.mjs

@@ -29,6 +29,37 @@ import {requireInteractive} from '../utils/interactive.mjs';
 const VALID_FEATURES = ['agents', 'theme', 'template'];
 const run = getRunPrefix();
 
+/**
+ * Build the "Next steps" lines printed at the end of `astryx init`.
+ *
+ * Theme guidance must match the runtime recommendation emitted by core's
+ * <Theme> component (packages/core/src/theme/Theme.tsx): the pre-built theme
+ * path (`/built` import + `theme.css`) plus the base CSS import, so users
+ * don't end up with an unstyled app or the slower runtime style-injection
+ * path. See https://github.com/facebook/astryx/issues/3080.
+ *
+ * Exported for testing.
+ *
+ * @param {string} runPrefix package-manager run prefix (e.g. `npx`)
+ * @returns {string[]} ordered list of human-facing lines
+ */
+export function getNextSteps(runPrefix) {
+  return [
+    '',
+    '  Next steps:',
+    "    1. Import base styles: import '@astryxdesign/core/reset.css'",
+    "       and import '@astryxdesign/core/astryx.css'",
+    "    2. Import components: import { Button } from '@astryxdesign/core'",
+    '    3. Optionally add a theme (use the pre-built path for performance):',
+    "       import { neutralTheme } from '@astryxdesign/theme-neutral/built'",
+    "       import '@astryxdesign/theme-neutral/theme.css'",
+    '       <Theme theme={neutralTheme}>...</Theme>',
+    `       For custom themes, run \`${runPrefix} astryx theme build <file>\` to generate the built artifacts.`,
+    `    4. ${runPrefix} astryx --help for all commands`,
+    '',
+  ];
+}
+
 function isCancel(value) {
   if (p.isCancel(value)) {
     p.cancel('Setup cancelled.');
@@ -250,13 +281,8 @@ export function registerInit(program) {
       // Outro
       p.outro('Design system initialized!');
 
-      humanLog('');
-      humanLog('  Next steps:');
-      humanLog("    1. Import components: import { Button } from '@astryxdesign/core'");
-      humanLog('    2. Optionally add a theme:');
-      humanLog("       import { neutralTheme } from '@astryxdesign/theme-neutral'");
-      humanLog('       <Theme theme={neutralTheme}>...</Theme>');
-      humanLog(`    3. ${run} astryx --help for all commands`);
-      humanLog('');
+      for (const line of getNextSteps(run)) {
+        humanLog(line);
+      }
     });
 }

package/src/commands/init.next-steps.test.mjs

@@ -0,0 +1,46 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Regression test for `astryx init` "Next steps" theme guidance.
+ *
+ * The init command previously steered users toward the slower runtime
+ * style-injection path:
+ *
+ *   import { neutralTheme } from '@astryxdesign/theme-neutral'
+ *   <Theme theme={neutralTheme}>...</Theme>
+ *
+ * ...which contradicted the runtime console warning emitted by core's
+ * <Theme> component (packages/core/src/theme/Theme.tsx) recommending the
+ * pre-built path, and left users with an unstyled app because the base CSS
+ * imports were never mentioned (facebook/astryx#3080).
+ *
+ * These assertions lock in the corrected guidance: base CSS imports, the
+ * pre-built (`/built` + `theme.css`) theme path, and the custom-theme build
+ * command.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {getNextSteps} from './init.mjs';
+
+describe('init Next steps theme guidance', () => {
+  const text = getNextSteps('npx').join('\n');
+
+  it('mentions the base CSS imports so the app is not left unstyled', () => {
+    expect(text).toContain("'@astryxdesign/core/reset.css'");
+    expect(text).toContain("'@astryxdesign/core/astryx.css'");
+  });
+
+  it('uses the pre-built theme path matching the runtime recommendation', () => {
+    expect(text).toContain("'@astryxdesign/theme-neutral/built'");
+    expect(text).toContain("'@astryxdesign/theme-neutral/theme.css'");
+  });
+
+  it('mentions building custom themes via `astryx theme build`', () => {
+    expect(text).toContain('astryx theme build <file>');
+  });
+
+  it('does not steer users to the runtime style-injection import', () => {
+    // The bare source import (no `/built`) is the slow runtime-injection path.
+    expect(text).not.toContain("from '@astryxdesign/theme-neutral'");
+  });
+});

package/src/commands/layout.mjs

@@ -0,0 +1,139 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file layout command — thin CLI wrapper around api/layout.mjs.
+ *
+ * Subcommands:
+ *   astryx layout expand "<expr>" [path]   compressed expression → validated TSX
+ *   astryx layout check "<expr>"           validate + echo both canonical surfaces
+ *   astryx layout grammar                  agent cheatsheet (alias table is branch-generated)
+ *
+ * The expression argument may also come from --file or stdin (`-`),
+ * which is how multi-line outline (XLO) input usually arrives.
+ */
+
+import * as fs from 'node:fs';
+import {jsonOut, humanLog} from '../lib/json.mjs';
+import {cliError} from '../lib/cli-error.mjs';
+import {layoutExpand, layoutCheck, layoutGrammar} from '../api/layout.mjs';
+
+/** Resolve the expression from arg, --file, or stdin ('-'). */
+async function readExpression(expr, options) {
+  if (options.file) return fs.readFileSync(options.file, 'utf-8');
+  if (expr === '-' || (!expr && !process.stdin.isTTY)) {
+    const chunks = [];
+    for await (const chunk of process.stdin) chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf-8');
+  }
+  return expr;
+}
+
+export function registerLayout(program) {
+  const layoutCmd = program
+    .command('layout')
+    .description('Generate XDS layouts from compressed expressions (XLE/XLO)');
+
+  layoutCmd
+    .command('expand [expression] [path]')
+    .description('Expand a layout expression into validated XDS TSX')
+    .option('--file <file>', 'Read the expression from a file')
+    .option('--form <form>', 'Input surface: compact, outline, or auto', 'auto')
+    .option('--name <name>', 'Generated component name (PascalCase)', 'GeneratedLayout')
+    .option('--loose', 'Downgrade unknown {block} hints to TODO placeholders')
+    .action(async (expression, targetPath, options) => {
+      const json = program.opts().json || false;
+      const source = await readExpression(expression, options);
+      if (!source || source.trim() === '') {
+        cliError('No layout expression given — pass it as an argument, via --file, or on stdin');
+        return;
+      }
+      let result;
+      try {
+        result = await layoutExpand(source, {
+          targetPath,
+          form: options.form,
+          loose: options.loose || false,
+          name: options.name,
+          cwd: process.cwd(),
+        });
+      } catch (e) {
+        cliError(e.message, {suggestions: e.suggestions || [], code: e.code});
+        return;
+      }
+      if (json) return jsonOut(result.type, result.data);
+
+      for (const warning of result.data.warnings) humanLog(`⚠ ${warning}`);
+      if (result.data.written) {
+        humanLog(`\n✓ Expanded to ${result.data.written}`);
+        humanLog(`  Components: ${result.data.componentsUsed.join(', ')}`);
+        if (result.data.todos.length > 0) {
+          humanLog(`  TODOs: ${result.data.todos.length} (search for "TODO(xle)")`);
+        }
+        humanLog('');
+      } else {
+        humanLog(result.data.code);
+      }
+    });
+
+  layoutCmd
+    .command('check [expression]')
+    .description('Validate a layout expression and echo canonical compact/outline forms')
+    .option('--file <file>', 'Read the expression from a file')
+    .option('--form <form>', 'Input surface: compact, outline, or auto', 'auto')
+    .option('--loose', 'Downgrade unknown {block} hints to TODO placeholders')
+    .action(async (expression, options) => {
+      const json = program.opts().json || false;
+      const source = await readExpression(expression, options);
+      if (!source || source.trim() === '') {
+        cliError('No layout expression given — pass it as an argument, via --file, or on stdin');
+        return;
+      }
+      let result;
+      try {
+        result = await layoutCheck(source, {
+          form: options.form,
+          loose: options.loose || false,
+          cwd: process.cwd(),
+        });
+      } catch (e) {
+        cliError(e.message, {suggestions: e.suggestions || [], code: e.code});
+        return;
+      }
+      if (json) return jsonOut(result.type, result.data);
+
+      const {valid, form, errors, warnings, compact, outline} = result.data;
+      if (!valid) {
+        humanLog(`\n✗ Invalid (${errors.length} error${errors.length === 1 ? '' : 's'}):`);
+        for (const e of errors) {
+          humanLog(`  - ${e.formatted}`);
+          if (e.suggestions?.length > 0) humanLog(`    did you mean: ${e.suggestions.join(', ')}?`);
+        }
+        humanLog('');
+        process.exitCode = 1;
+        return;
+      }
+      humanLog(`\n✓ Valid (parsed as ${form})`);
+      for (const warning of warnings) humanLog(`⚠ ${warning}`);
+      humanLog('\ncompact:');
+      humanLog(`  ${compact}`);
+      humanLog('\noutline:');
+      humanLog(outline.split('\n').map(l => `  ${l}`).join('\n'));
+      humanLog('');
+    });
+
+  layoutCmd
+    .command('grammar')
+    .description('Print the XLE/XLO cheatsheet (alias table generated from this branch)')
+    .action(async () => {
+      const json = program.opts().json || false;
+      let result;
+      try {
+        result = await layoutGrammar({cwd: process.cwd()});
+      } catch (e) {
+        cliError(e.message, {suggestions: e.suggestions || [], code: e.code});
+        return;
+      }
+      if (json) return jsonOut(result.type, result.data);
+      humanLog(result.data.text);
+    });
+}