@astryxdesign/cli 0.1.7 → 0.1.8-canary.07362a9

package/{src → cli}/commands/doctor.test.mjs

@@ -19,8 +19,8 @@ import {
   checkAgentDocs,
   checkPeerDeps,
   checkPackageManager,
-} from '../api/doctor.mjs';
-import {MIN_NODE_VERSION} from '../lib/node-version.mjs';
+} from '../../api/doctor/doctor.mjs';
+import {MIN_NODE_VERSION} from '../../lib/node-version.mjs';
 
 let tmpDir;
 let logCalls;

package/{src → cli}/commands/ensure-core-built.mjs

@@ -40,6 +40,7 @@ const BUILD_TIMEOUT_MS = 180_000;
 const STALE_LOCK_MS = BUILD_TIMEOUT_MS + 20_000;
 const POLL_MS = 250;
 
+/** @param {number} ms */
 function sleepSync(ms) {
   Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
@@ -67,7 +68,7 @@ function tryAcquire() {
     fs.mkdirSync(LOCK_DIR);
     return true;
   } catch (err) {
-    if (err.code !== 'EEXIST') {
+    if (/** @type {NodeJS.ErrnoException} */ (err).code !== 'EEXIST') {
       throw err;
     }
     if (lockIsStale()) {
@@ -76,7 +77,7 @@ function tryAcquire() {
         fs.mkdirSync(LOCK_DIR);
         return true;
       } catch (retryErr) {
-        if (retryErr.code !== 'EEXIST') {
+        if (/** @type {NodeJS.ErrnoException} */ (retryErr).code !== 'EEXIST') {
           throw retryErr;
         }
       }

package/{src → cli}/commands/external-showcase.test.mjs

@@ -4,7 +4,7 @@ import {describe, it, expect, beforeEach, afterEach} from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
-import {findShowcase, findRelatedBlocks} from '../api/template.mjs';
+import {findShowcase, findRelatedBlocks} from '../../api/template/template.mjs';
 
 // These tests verify that findShowcase and findRelatedBlocks can discover
 // blocks from external packages that declare xds.blocks in package.json.

package/{src → cli}/commands/hook/index.mjs

@@ -11,14 +11,29 @@ import {
   formatHookCompact,
   formatHookBrief,
   formatHookParams,
-} from '../../lib/hook-format.mjs';
-import {getRunPrefix} from '../../utils/package-manager.mjs';
-import {jsonOut, humanLog} from '../../lib/json.mjs';
-import {cliError} from '../../lib/cli-error.mjs';
-import {ERROR_CODES} from '../../lib/error-codes.mjs';
-import {hook as hookApi} from '../../api/hook.mjs';
-import {findRelatedBlocks} from '../../api/template.mjs';
+} from '../../../lib/hook-format.mjs';
+import {getCliInvocation} from '../../../utils/package-manager.mjs';
+import {jsonOut, humanLog} from '../../../lib/json.mjs';
+import {cliError} from '../../../lib/cli-error.mjs';
+import {ERROR_CODES} from '../../../lib/error-codes.mjs';
+import {hook as hookApi} from '../../../api/hook/hook.mjs';
+import {findRelatedBlocks} from '../../../api/template/template.mjs';
 
+/**
+ * The api layer's hook() widens its return to `{type: string, data: unknown}`,
+ * so annotate the command-local result with the precise discriminated union from
+ * src/types/hook to get narrowing + typed data.
+ *
+ * @typedef {(
+ *   | import('../../../types/hook').HookListResponse
+ *   | import('../../../types/hook').HookBriefResponse
+ *   | import('../../../types/hook').HookFullResponse
+ *   | import('../../../types/hook').HookDetailResponse
+ *   | import('../../../types/hook').HookDetailParamsResponse
+ * )} HookResult
+ */
+
+/** @param {import('commander').Command} program */
 export function registerHook(program) {
   program
     .command('hook [name]')
@@ -26,8 +41,13 @@ export function registerHook(program) {
     .option('--list', 'List all hooks grouped by category')
     .option('--category <category>', 'List hooks in a specific category')
     .option('--params', 'Print only the parameters table')
-    .action(async (name, options) => {
-      const run = getRunPrefix();
+    .action(
+      /**
+       * @param {string|undefined} name
+       * @param {{list?: boolean, category?: string, params?: boolean}} options
+       */
+      async (name, options) => {
+      const run = getCliInvocation();
       const zh = program.opts().zh || false;
       const lang = program.opts().lang || null;
       const detailSource = program.getOptionValueSource('detail');
@@ -43,18 +63,20 @@ export function registerHook(program) {
         return;
       }
 
+      /** @type {HookResult} */
       let result;
       try {
-        result = await hookApi(name, {
+        result = /** @type {HookResult} */ (await hookApi(name, {
           cwd: process.cwd(),
           list: options.list,
           category: options.category,
           params: options.params,
           detail,
           lang, zh,
-        });
+        }));
       } catch (e) {
-        cliError(e.message, {suggestions: e.suggestions, code: e.code});
+        const err = /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
+        cliError(err.message, {suggestions: err.suggestions, code: err.code});
         return;
       }
 
@@ -76,7 +98,7 @@ export function registerHook(program) {
               for (const h of hookNames) humanLog(`  ${h}`);
             }
             humanLog('');
-            humanLog(`Usage: ${run} astryx hook <name>`);
+            humanLog(`Usage: ${run} hook <name>`);
             humanLog('');
           }
           break;
@@ -93,7 +115,7 @@ export function registerHook(program) {
             }
             humanLog('');
           }
-          humanLog(`Usage: ${run} astryx hook <name>`);
+          humanLog(`Usage: ${run} hook <name>`);
           humanLog('');
           break;
         }
@@ -123,6 +145,7 @@ export function registerHook(program) {
           }
           // Show related block templates from relatedComponents
           const relatedComps = result.data.relatedComponents || [];
+          /** @type {import('../../../api/template/template.mjs').DiscoveredTemplate[]} */
           const allBlocks = [];
           for (const comp of relatedComps) {
             const blocks = await findRelatedBlocks(comp);
@@ -152,12 +175,12 @@ export function registerHook(program) {
 }
 
 // Re-export lib functions for external consumers
-export {discoverHooks, findHookDoc, getAllHookNames} from '../../lib/hook-discovery.mjs';
-export {loadDocs} from '../../lib/component-loader.mjs';
+export {discoverHooks, findHookDoc, getAllHookNames} from '../../../lib/hook-discovery.mjs';
+export {loadDocs} from '../../../lib/component-loader.mjs';
 export {
   formatHookFull,
   formatHookCompact,
   formatHookBrief,
   formatHookBriefAll,
   formatHookParams,
-} from '../../lib/hook-format.mjs';
+} from '../../../lib/hook-format.mjs';

package/{src → cli}/commands/import-hint-correctness.test.mjs

@@ -23,7 +23,7 @@ import {
   discoverComponents,
   findComponentSource,
 } from './component/index.mjs';
-import {findCoreDir} from '../utils/paths.mjs';
+import {findCoreDir} from '../../utils/paths.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const CLI_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');

package/cli/commands/init.mjs

@@ -0,0 +1,195 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file init command — non-interactive setup + feature installer
+ *
+ * `astryx init` is non-interactive by default: it installs the AGENTS.md/
+ * CLAUDE.md cheat sheet with NO prompts, so it behaves identically for humans,
+ * AI agents, CI, and piped I/O — it never hangs or errors on a missing TTY.
+ * Non-interactive feature install: `astryx init --features agents,theme,template`
+ * Re-runnable: safe to run multiple times, idempotent
+ *
+ * Features:
+ *   agents   — Install AGENTS.md/CLAUDE.md cheat sheet for AI coding agents
+ *   theme    — Point to the theme workflow (`astryx theme`)
+ *   template — Copy a starter page template
+ */
+
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import {CLI_ROOT} from '../../utils/paths.mjs';
+import {PathSafetyError} from '../../utils/path-safety.mjs';
+import {getCliInvocation} from '../../utils/package-manager.mjs';
+import {installAgentDocs, removeAgentDocs} from '../../lib/agent-docs/agent-docs.mjs';
+import {listTemplates} from './template.mjs';
+import {humanLog} from '../../lib/json.mjs';
+import {cliError} from '../../lib/cli-error.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
+
+const VALID_FEATURES = ['agents', 'theme', 'template'];
+const run = getCliInvocation();
+
+/**
+ * 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} invocation install-aware CLI invocation stem (e.g. `npx astryx`, `pnpm exec astryx`, or `npx @astryxdesign/cli` for one-off runs)
+ * @returns {string[]} ordered list of human-facing lines
+ */
+export function getNextSteps(invocation) {
+  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 \`${invocation} theme build <file>\` to generate the built artifacts.`,
+    `    4. ${invocation} --help for all commands`,
+    '',
+  ];
+}
+
+// ─── Feature: agents ─────────────────────────────────────────────────────────
+
+/**
+ * @param {string} targetDir
+ * @param {{agent?: string, agentDocsPath?: string | string[]}} [opts]
+ */
+function runAgents(targetDir, {agent, agentDocsPath} = {}) {
+  try {
+    const paths = agentDocsPath
+      ? Array.isArray(agentDocsPath)
+        ? agentDocsPath
+        : [agentDocsPath]
+      : undefined;
+    const written = installAgentDocs(targetDir, {agent, paths});
+    const summary = written.join(', ');
+    humanLog(`✓ AI agent docs installed → ${summary}`);
+  } catch (err) {
+    // PathSafetyError carries a precise, user-actionable message —
+    // surface it instead of the generic "could not install" warning so
+    // misconfigured --agent-docs-path values aren't silently swallowed.
+    if (err instanceof PathSafetyError) {
+      console.error(`Error: ${err.message}`);
+      process.exitCode = 1;
+      return;
+    }
+    console.error(`Could not install agent docs. Try again with \`${run} init --features agents\`.`);
+  }
+}
+
+// ─── Feature: theme ──────────────────────────────────────────────────────────
+
+function runTheme() {
+  humanLog(`✓ For a custom theme, run \`${run} theme\` (browse) or \`${run} theme add <slug>\` (scaffold).`);
+}
+
+// ─── Feature: template ───────────────────────────────────────────────────────
+
+/**
+ * @param {string} targetDir
+ * @param {{templateName?: string}} [opts]
+ */
+function runTemplate(targetDir, {templateName} = {}) {
+  const templates = listTemplates();
+  if (templates.length === 0) return;
+
+  if (!templateName) {
+    // Point agents at the build workflow rather than dumping page-template
+    // names — `build` surfaces pages AND blocks AND components for an idea,
+    // and `build` with no args is the full how-to-build playbook.
+    humanLog('✓ To build UI, use these commands:');
+    humanLog('');
+    humanLog(`    ${run} build "<what you're building>"   build a page — kit: closest template + blocks + components`);
+    humanLog(`    ${run} build                            the how-to-build workflow (read this first)`);
+    humanLog(`    ${run} search <query>                   find anything — components, docs, templates, blocks`);
+    humanLog('');
+    return;
+  }
+
+  if (!templates.includes(templateName)) {
+    cliError(`Unknown template "${templateName}". Available: ${templates.join(', ')}`, {code: ERROR_CODES.ERR_UNKNOWN_TEMPLATE});
+    return;
+  }
+
+  const outputDir = path.resolve(targetDir, `./src/pages/${templateName}`);
+  const srcPath = path.join(CLI_ROOT, 'templates', 'pages', templateName, 'page.tsx');
+  fs.mkdirSync(outputDir, {recursive: true});
+  fs.copyFileSync(srcPath, path.join(outputDir, 'page.tsx'));
+  humanLog(`✓ Template created at ${path.relative(targetDir, outputDir)}/page.tsx`);
+}
+
+// ─── Command ─────────────────────────────────────────────────────────────────
+
+/**
+ * @param {import('commander').Command} program
+ */
+export function registerInit(program) {
+  program
+    .command('init')
+    .description('Initialize the design system in your project')
+    .option('--features <list>', 'Comma-separated features to install (agents, theme, template)')
+    .option('--all', 'Install all features, no prompts')
+    .option('--remove-agents', 'Remove AI agent docs from all agent doc files')
+    .option('--agent <tool>', 'Target AI tool for agent docs: claude, cursor, codex, hermes, all')
+    .option('--agent-docs-path <path...>', 'Explicit file path(s) for agent docs')
+    .action((/** @type {{features?: string, all?: boolean, removeAgents?: boolean, agent?: string, agentDocsPath?: string | string[]}} */ options) => {
+      const targetDir = process.cwd();
+
+      // Remove mode
+      if (options.removeAgents) {
+        removeAgentDocs(targetDir);
+        humanLog('✓ AI agent docs removed.');
+        return;
+      }
+
+      // Non-interactive: --features or --all
+      if (options.features || options.all) {
+        const features = options.all
+          ? VALID_FEATURES
+          : /** @type {string} */ (options.features).split(',').map(f => f.trim().toLowerCase());
+
+        const invalid = features.filter(f => !VALID_FEATURES.includes(f));
+        if (invalid.length > 0) {
+          cliError(`Unknown features: ${invalid.join(', ')}. Valid features: ${VALID_FEATURES.join(', ')}`, {code: ERROR_CODES.ERR_UNKNOWN_FEATURE});
+          return;
+        }
+
+        for (const feature of features) {
+          if (feature === 'agents') runAgents(targetDir, {
+            agent: options.agent,
+            agentDocsPath: options.agentDocsPath,
+          });
+          if (feature === 'theme') runTheme();
+          if (feature === 'template') runTemplate(targetDir, {});
+        }
+        return;
+      }
+
+      // No flags: TTY-free default. `astryx init` installs the AI agent cheat
+      // sheet with NO prompts, so it behaves identically for humans, agents, CI,
+      // and piped I/O — it never hangs or errors on a missing TTY. (A guided
+      // `--interactive` setup may return later as an explicit opt-in.)
+      runAgents(targetDir, {
+        agent: options.agent,
+        agentDocsPath: options.agentDocsPath,
+      });
+      humanLog('');
+      humanLog(`  Tip: \`${run} init --all\` also points you to the theme and page-building workflows.`);
+
+      for (const line of getNextSteps(run)) {
+        humanLog(line);
+      }
+    });
+}

package/{src → cli}/commands/init.next-steps.test.mjs

@@ -23,7 +23,7 @@ import {describe, it, expect} from 'vitest';
 import {getNextSteps} from './init.mjs';
 
 describe('init Next steps theme guidance', () => {
-  const text = getNextSteps('npx').join('\n');
+  const text = getNextSteps('npx astryx').join('\n');
 
   it('mentions the base CSS imports so the app is not left unstyled', () => {
     expect(text).toContain("'@astryxdesign/core/reset.css'");

package/cli/commands/interactive-guard.test.mjs

@@ -0,0 +1,66 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Subprocess no-hang tests for `astryx init`.
+ *
+ * TTY was removed from the CLI: `init` is non-interactive by default and must
+ * run cleanly (exit 0, writing the agent cheat sheet) instead of hanging on a
+ * prompt. These tests spawn the CLI with stdin/stdout NOT a TTY (the CI / piped
+ * / agent condition). A hang would show as signal SIGTERM + status null; we
+ * assert `signal === null && status === 0` to prove it exits cleanly and works.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import {spawnSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {fileURLToPath} from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI = path.resolve(__dirname, '..', '..', 'bin', 'astryx.mjs');
+
+let tmpDir;
+
+function runCli(args) {
+  return spawnSync(process.execPath, [CLI, ...args], {
+    cwd: tmpDir,
+    encoding: 'utf8',
+    timeout: 20_000,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: {...process.env, FORCE_COLOR: '0', CI: ''},
+  });
+}
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-interactive-guard-'));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('init is non-interactive by default (no TTY needed)', () => {
+  it('runs cleanly (exit 0, no hang) and writes agent docs', () => {
+    const r = runCli(['init']);
+    expect(r.signal).toBeNull(); // did not hang
+    expect(r.status).toBe(0); // succeeded without a TTY
+    expect(fs.readdirSync(tmpDir).length).toBeGreaterThan(0); // wrote the cheat sheet
+  });
+
+  it('writes an agent-doc file containing the ASTRYX cheat-sheet marker', () => {
+    runCli(['init']);
+    // init injects into existing agent-doc files if present, else creates AGENTS.md
+    const candidates = ['AGENTS.md', 'CLAUDE.md', '.cursorrules', path.join('.claude', 'CLAUDE.md')];
+    const doc = candidates.find(f => fs.existsSync(path.join(tmpDir, f)));
+    expect(doc).toBeTruthy();
+    expect(fs.readFileSync(path.join(tmpDir, doc), 'utf8')).toMatch(/ASTRYX:START/);
+  });
+
+  it('still runs --features agents non-interactively', () => {
+    const r = runCli(['init', '--features', 'agents']);
+    expect(r.signal).toBeNull();
+    expect(r.status).toBe(0);
+    expect(fs.readdirSync(tmpDir).length).toBeGreaterThan(0);
+  });
+});

package/{src → cli}/commands/json-contract.test.mjs

@@ -45,7 +45,7 @@ function runCli(args, {cwd} = {}) {
 
 function parseJson(stdout) {
   // CLI emits a single JSON document. If anything else snuck onto stdout
-  // (clack output, console.log strings, etc.) JSON.parse will throw —
+  // (log output, console.log strings, etc.) JSON.parse will throw —
   // which is exactly the failure mode we want to catch in tests.
   return JSON.parse(stdout);
 }
@@ -61,7 +61,7 @@ afterEach(() => {
 });
 
 describe('--json contract: rejects before side effects', () => {
-  it('astryx init --json --features agents does not write .claude/CLAUDE.md', () => {
+  it('astryx init --json --features agents does not write agent docs', () => {
     const before = fs.readdirSync(tmpDir);
     expect(before).toEqual([]);
 

package/{src → cli}/commands/layout.mjs

@@ -13,21 +13,55 @@
  */
 
 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';
+import {jsonOut, humanLog} from '../../lib/json.mjs';
+import {cliError} from '../../lib/cli-error.mjs';
+import {layoutExpand, layoutCheck, layoutGrammar} from '../../api/layout/layout.mjs';
 
-/** Resolve the expression from arg, --file, or stdin ('-'). */
-async function readExpression(expr, options) {
+/**
+ * The api layer's @returns for these functions widen the `type` discriminator
+ * to `string`, so annotate the command-local result with the precise response
+ * shapes from src/types/layout so narrowing + jsonOut typecheck.
+ *
+ * @typedef {import('../../types/layout').LayoutExpandResponse} LayoutExpandResponse
+ * @typedef {import('../../types/layout').LayoutCheckResponse} LayoutCheckResponse
+ * @typedef {import('../../types/layout').LayoutGrammarResponse} LayoutGrammarResponse
+ */
+
+/**
+ * @typedef {object} LayoutExpandOptions
+ * @property {string} [file]
+ * @property {'compact'|'outline'|'auto'} [form]
+ * @property {string} [name]
+ * @property {boolean} [loose]
+ */
+
+/**
+ * @typedef {object} LayoutCheckOptions
+ * @property {string} [file]
+ * @property {'compact'|'outline'|'auto'} [form]
+ * @property {boolean} [loose]
+ */
+
+/**
+ * Resolve the expression from arg, --file, or stdin ('-').
+ * @param {string} [expr]
+ * @param {{file?: string}} [options]
+ * @returns {Promise<string>}
+ */
+async function readExpression(expr, options = {}) {
   if (options.file) return fs.readFileSync(options.file, 'utf-8');
-  if (expr === '-' || (!expr && !process.stdin.isTTY)) {
+  if (expr === '-') {
+    /** @type {Buffer[]} */
     const chunks = [];
-    for await (const chunk of process.stdin) chunks.push(chunk);
+    for await (const chunk of process.stdin) chunks.push(/** @type {Buffer} */ (chunk));
     return Buffer.concat(chunks).toString('utf-8');
   }
-  return expr;
+  return expr ?? '';
 }
 
+/**
+ * @param {import('commander').Command} program
+ */
 export function registerLayout(program) {
   const layoutCmd = program
     .command('layout')
@@ -40,24 +74,26 @@ export function registerLayout(program) {
     .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) => {
+    .action(async (/** @type {string} */ expression, /** @type {string} */ targetPath, /** @type {LayoutExpandOptions} */ 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;
       }
+      /** @type {LayoutExpandResponse} */
       let result;
       try {
-        result = await layoutExpand(source, {
+        result = /** @type {LayoutExpandResponse} */ (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});
+        const err = /** @type {import('../../api/error.mjs').AstryxError} */ (e);
+        cliError(err.message, {suggestions: err.suggestions || [], code: err.code});
         return;
       }
       if (json) return jsonOut(result.type, result.data);
@@ -81,22 +117,24 @@ export function registerLayout(program) {
     .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) => {
+    .action(async (/** @type {string} */ expression, /** @type {LayoutCheckOptions} */ 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;
       }
+      /** @type {LayoutCheckResponse} */
       let result;
       try {
-        result = await layoutCheck(source, {
+        result = /** @type {LayoutCheckResponse} */ (await layoutCheck(source, {
           form: options.form,
           loose: options.loose || false,
           cwd: process.cwd(),
-        });
+        }));
       } catch (e) {
-        cliError(e.message, {suggestions: e.suggestions || [], code: e.code});
+        const err = /** @type {import('../../api/error.mjs').AstryxError} */ (e);
+        cliError(err.message, {suggestions: err.suggestions || [], code: err.code});
         return;
       }
       if (json) return jsonOut(result.type, result.data);
@@ -106,7 +144,7 @@ export function registerLayout(program) {
         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(', ')}?`);
+          if (e.suggestions && e.suggestions.length > 0) humanLog(`    did you mean: ${e.suggestions.join(', ')}?`);
         }
         humanLog('');
         process.exitCode = 1;
@@ -126,11 +164,13 @@ export function registerLayout(program) {
     .description('Print the XLE/XLO cheatsheet (alias table generated from this branch)')
     .action(async () => {
       const json = program.opts().json || false;
+      /** @type {LayoutGrammarResponse} */
       let result;
       try {
-        result = await layoutGrammar({cwd: process.cwd()});
+        result = /** @type {LayoutGrammarResponse} */ (await layoutGrammar({cwd: process.cwd()}));
       } catch (e) {
-        cliError(e.message, {suggestions: e.suggestions || [], code: e.code});
+        const err = /** @type {import('../../api/error.mjs').AstryxError} */ (e);
+        cliError(err.message, {suggestions: err.suggestions || [], code: err.code});
         return;
       }
       if (json) return jsonOut(result.type, result.data);