@astryxdesign/cli 0.2.0 → 0.3.0

package/cli/commands/build-theme.registry.test.mjs

@@ -1,187 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Regression test for issue #4109: theme-build component-override keys
- * must match the class names components actually render.
- *
- * `astryx theme build` emits a component override as a `.astryx-<key>` rule,
- * where `<key>` is the theme's `components` key passed through verbatim
- * (generateThemeRules re-adds the `astryx-` prefix). The CLI's KNOWN_COMPONENTS
- * registry is what the validator accepts and what its "Did you mean?" hints
- * point authors toward — so every registry key MUST correspond to a class a
- * component really renders, or the emitted rule is a dead selector that
- * silently does nothing.
- *
- * The registry had de-hyphenated keys for every multi-word component
- * (`textinput`, `dateinput`, `numberinput`, `timeinput`, `appshell`,
- * `aspectratio`, `checkboxinput`, `dropdownmenu`, `formlayout`, `mobilenav`,
- * `moremenu`, `radiolist`, `sidenav`, `tablist`, `topnav`), while the
- * components render the hyphenated class (`astryx-text-input`, etc.). Authors
- * following the registry shipped dead `.astryx-textinput` rules.
- *
- * Source of truth = the class the component renders, captured in each
- * component's `{Name}.doc.mjs` `theming.targets[].className` (itself guarded
- * against the real `themeProps()`/`stableClassName()` call sites by
- * packages/core/src/theme/themingTargets.test.ts).
- */
-
-import {describe, it, expect, beforeAll} from 'vitest';
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import * as os from 'node:os';
-import {fileURLToPath} from 'node:url';
-import {ensureCoreBuilt} from './ensure-core-built.mjs';
-import {runCli} from '../../test-utils/run-cli.mjs';
-
-const HERE = path.dirname(fileURLToPath(import.meta.url));
-const CORE_SRC = path.resolve(HERE, '../../../core/src');
-const BUILD_THEME_SRC = path.resolve(HERE, '../../api/theme/build/build.mjs');
-
-/**
- * Extract the KNOWN_COMPONENTS registry keys from the build-theme source.
- * Reading the source (rather than importing the un-exported constant) keeps
- * this test decoupled from the module's private surface.
- */
-function knownComponentKeys() {
-  const src = fs.readFileSync(BUILD_THEME_SRC, 'utf8');
-  const start = src.indexOf('const KNOWN_COMPONENTS = {');
-  expect(start).toBeGreaterThan(-1);
-  const end = src.indexOf('};', start);
-  const block = src.slice(start, end);
-  const keys = new Set();
-  const re = /^\s*'?([a-z][a-z0-9-]*)'?\s*:/gm;
-  let m;
-  while ((m = re.exec(block)) !== null) {
-    keys.add(m[1]);
-  }
-  return keys;
-}
-
-/**
- * The set of real override keys: every `theming.targets[].className` across the
- * component docs, with the `astryx-` prefix stripped. This is the canonical
- * source of truth for what selectors the theme build should emit.
- */
-function realOverrideKeys() {
-  const keys = new Set();
-  for (const dir of fs.readdirSync(CORE_SRC, {withFileTypes: true})) {
-    if (!dir.isDirectory()) continue;
-    const docFile = path.join(CORE_SRC, dir.name, `${dir.name}.doc.mjs`);
-    if (!fs.existsSync(docFile)) continue;
-    const text = fs.readFileSync(docFile, 'utf8');
-    const themingIdx = text.indexOf('theming');
-    if (themingIdx === -1) continue;
-    const scoped = text.slice(themingIdx);
-    const re = /className:\s*'astryx-([a-z0-9-]+)'/g;
-    let m;
-    while ((m = re.exec(scoped)) !== null) {
-      keys.add(m[1]);
-    }
-  }
-  return keys;
-}
-
-/**
- * The stable classes components ACTUALLY render: the literal first argument of
- * every `themeProps('<class>', …)` and `stableClassName('<class>')` call across
- * the core `.tsx` source (excluding tests). This is the truest source of truth
- * — the doc `theming.targets` are hand-authored metadata that can drift from
- * it, so both the registry and the targets are validated against these
- * literals. Every call site uses a plain string literal (no dynamic/
- * interpolated names), so this is fully static.
- */
-function renderedClassLiterals() {
-  const classes = new Set();
-  const walk = dir => {
-    for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
-      const full = path.join(dir, entry.name);
-      if (entry.isDirectory()) {
-        walk(full);
-      } else if (entry.name.endsWith('.tsx') && !entry.name.endsWith('.test.tsx')) {
-        const text = fs.readFileSync(full, 'utf8');
-        for (const re of [
-          /themeProps\(\s*'([^']+)'/g,
-          /stableClassName\(\s*'([^']+)'/g,
-        ]) {
-          let m;
-          while ((m = re.exec(text)) !== null) {
-            classes.add(m[1]);
-          }
-        }
-      }
-    }
-  };
-  walk(CORE_SRC);
-  return classes;
-}
-
-describe('theme-build KNOWN_COMPONENTS registry (#4109)', () => {
-  // `layer` is a layout/anchor concept with no rendered `astryx-layer`
-  // class or doc target; it predates and is unrelated to #4109.
-  const allowedWithoutTarget = new Set(['layer']);
-
-  it('every registry key is a class documented as a theming target', () => {
-    const known = knownComponentKeys();
-    const real = realOverrideKeys();
-
-    const dead = [...known].filter(
-      k => !real.has(k) && !allowedWithoutTarget.has(k),
-    );
-    expect(dead).toEqual([]);
-  });
-
-  it('every registry key is a class a component actually renders (themeProps literal)', () => {
-    // Validate the registry against the TRUE source of truth — the literal
-    // passed to themeProps()/stableClassName() in the component source — not
-    // just the hand-authored doc targets. This catches a de-hyphenated key
-    // even if the docs were (wrongly) kept in agreement with it.
-    const known = knownComponentKeys();
-    const rendered = renderedClassLiterals();
-
-    const dead = [...known].filter(
-      k => !rendered.has(k) && !allowedWithoutTarget.has(k),
-    );
-    expect(dead).toEqual([]);
-  });
-
-  it('every documented theming target is backed by a real themeProps literal', () => {
-    // Guards the two "sources of truth" against drift: a component whose
-    // themeProps() arg and doc target className disagree would be a latent bug
-    // that the registry checks above could not catch (they'd validate against
-    // whichever side happened to match). `theming.targets[].className` is
-    // hand-authored; themeProps()/stableClassName() literals are what actually
-    // renders — they must agree.
-    const targets = realOverrideKeys();
-    const rendered = renderedClassLiterals();
-
-    const orphanTargets = [...targets].filter(k => !rendered.has(k));
-    expect(orphanTargets).toEqual([]);
-  });
-});
-
-describe('theme build emits a live TextInput selector (#4109)', () => {
-  let tmpDir;
-  beforeAll(() => {
-    ensureCoreBuilt();
-    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-4109-'));
-  }, 200_000);
-
-  it('emits .astryx-text-input (the rendered class), not the dead .astryx-textinput', async () => {
-    const themeFile = path.join(tmpDir, 'theme.mjs');
-    const outFile = path.join(tmpDir, 'theme.css');
-    fs.writeFileSync(
-      themeFile,
-      `export default {\n` +
-        `  name: 'input-4109',\n` +
-        `  tokens: {},\n` +
-        `  components: { 'text-input': { base: { borderRadius: '16px' } } },\n` +
-        `};\n`,
-    );
-
-    await runCli(['theme', 'build', themeFile, '-o', outFile]);
-    const css = fs.readFileSync(outFile, 'utf8');
-
-    expect(css).toContain('.astryx-text-input');
-    expect(css).not.toContain('.astryx-textinput');
-  });
-});

package/cli/commands/build-theme.variants.test.mjs

@@ -1,171 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Regression test for the custom-variant type augmentations emitted by
- * `astryx theme build` (#3391 companion: #3371).
- *
- * When a theme declares a custom component prop value (e.g.
- * `button['variant:accentOutline']`), the build emits a `<name>.variants.d.ts`
- * with a module augmentation so the custom value type-checks. This suite pins
- * the two bugs that made that augmentation dead code:
- *
- *   1. The augmentation targeted a non-existent, `XDS`-prefixed interface
- *      (`XDSButtonVariantMap`) instead of core's real `ButtonVariantMap`, so it
- *      created a new unused interface and never widened the prop union.
- *   2. Props with no augmentation point (closed literal-union types such as
- *      Button `size` or Heading `type`/`level`) still got a `declare module`
- *      block against a `*Map` interface that doesn't exist.
- *   3. The generated `.variants.d.ts` was never referenced by the main
- *      `<name>.d.ts`, so even a correct augmentation never loaded.
- *
- * Building `astryx theme build` requires a compiled @astryxdesign/core, so this
- * suite builds core once in beforeAll (mirrors build-theme.prose.test.mjs).
- */
-
-import {describe, it, expect, beforeAll, beforeEach, afterEach} from 'vitest';
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import * as os from 'node:os';
-import {ensureCoreBuilt} from './ensure-core-built.mjs';
-import {runCli} from '../../test-utils/run-cli.mjs';
-
-function writeTheme(dir, contents) {
-  fs.mkdirSync(dir, {recursive: true});
-  const file = path.join(dir, 'variants-theme.mjs');
-  fs.writeFileSync(file, contents);
-  return file;
-}
-
-// Build core through the shared lock helper — this suite previously ran its
-// own unguarded `if (!exists) pnpm -F core build`, and when Vitest scheduled
-// it alongside the other build-theme suites on a fresh checkout, the
-// concurrent builds collided on packages/core/dist (core's build starts by
-// wiping dist), nondeterministically breaking whichever suite was mid-read.
-beforeAll(() => {
-  ensureCoreBuilt();
-}, 200_000);
-
-let tmpDir;
-beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-build-theme-variants-'));
-});
-afterEach(() => {
-  fs.rmSync(tmpDir, {recursive: true, force: true});
-});
-
-describe('theme build custom-variant augmentations', () => {
-  it('targets the real (un-prefixed) core interface for a custom variant', async () => {
-    const themeFile = writeTheme(
-      tmpDir,
-      `export default {
-        name: 'variants-theme',
-        tokens: { '--color-bg': '#fff' },
-        components: {
-          button: { 'variant:accentOutline': { backgroundColor: 'transparent' } },
-        },
-      };\n`,
-    );
-
-    const result = await runCli(
-      ['theme', 'build', path.relative(tmpDir, themeFile)],
-      tmpDir,
-    );
-    expect(result.code).toBe(0);
-
-    const variantsPath = path.join(tmpDir, 'variants-theme.variants.d.ts');
-    expect(fs.existsSync(variantsPath)).toBe(true);
-    const dts = fs.readFileSync(variantsPath, 'utf-8');
-
-    // Targets core's actual augmentation point…
-    expect(dts).toContain("declare module '@astryxdesign/core/Button'");
-    expect(dts).toMatch(/interface ButtonVariantMap\b/);
-    expect(dts).toContain("'accentOutline': true;");
-    // …and NOT the old, non-existent XDS-prefixed interface.
-    expect(dts).not.toMatch(/XDSButtonVariantMap/);
-  });
-
-  it('skips props with no augmentation point (Button size, Heading type)', async () => {
-    const themeFile = writeTheme(
-      tmpDir,
-      `export default {
-        name: 'variants-theme',
-        tokens: { '--color-bg': '#fff' },
-        components: {
-          button: {
-            'variant:accentOutline': { backgroundColor: 'transparent' },
-            'size:jumbo': { paddingBlock: '40px' },
-          },
-          heading: { 'type:hero': { fontSize: '80px' } },
-        },
-      };\n`,
-    );
-
-    const result = await runCli(
-      ['theme', 'build', path.relative(tmpDir, themeFile)],
-      tmpDir,
-    );
-    expect(result.code).toBe(0);
-
-    const variantsPath = path.join(tmpDir, 'variants-theme.variants.d.ts');
-    expect(fs.existsSync(variantsPath)).toBe(true);
-    const dts = fs.readFileSync(variantsPath, 'utf-8');
-
-    // The augmentable variant is emitted…
-    expect(dts).toMatch(/interface ButtonVariantMap\b/);
-    // …but closed literal-union props get no dead augmentation.
-    expect(dts).not.toMatch(/ButtonSizeMap/);
-    expect(dts).not.toMatch(/HeadingTypeMap/);
-    expect(dts).not.toContain("declare module '@astryxdesign/core/Heading'");
-  });
-
-  it('does not emit a .variants.d.ts when every custom value is non-augmentable', async () => {
-    const themeFile = writeTheme(
-      tmpDir,
-      `export default {
-        name: 'variants-theme',
-        tokens: { '--color-bg': '#fff' },
-        components: {
-          button: { 'size:jumbo': { paddingBlock: '40px' } },
-        },
-      };\n`,
-    );
-
-    const result = await runCli(
-      ['theme', 'build', path.relative(tmpDir, themeFile)],
-      tmpDir,
-    );
-    expect(result.code).toBe(0);
-    expect(
-      fs.existsSync(path.join(tmpDir, 'variants-theme.variants.d.ts')),
-    ).toBe(false);
-  });
-
-  it('references the variants file from the main .d.ts so the augmentation loads', async () => {
-    const themeFile = writeTheme(
-      tmpDir,
-      `export default {
-        name: 'variants-theme',
-        tokens: { '--color-bg': '#fff' },
-        components: {
-          button: { 'variant:accentOutline': { backgroundColor: 'transparent' } },
-        },
-      };\n`,
-    );
-
-    const result = await runCli(
-      ['theme', 'build', path.relative(tmpDir, themeFile)],
-      tmpDir,
-    );
-    expect(result.code).toBe(0);
-
-    const dts = fs.readFileSync(
-      path.join(tmpDir, 'variants-theme.d.ts'),
-      'utf-8',
-    );
-    // A triple-slash reference to the variants file, so importing the theme's
-    // types also loads the module augmentation.
-    expect(dts).toMatch(
-      /\/\/\/\s*<reference path="\.\/variants-theme\.variants\.d\.ts"\s*\/>/,
-    );
-  });
-});

package/cli/commands/build-theme.watch.test.mjs

@@ -1,159 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Tests for `astryx theme build --watch` (#3375).
- *
- * Watch mode runs an initial build, then rebuilds whenever the theme file
- * changes, until interrupted. Each rebuild runs in a child process so a build
- * error (reported by the single-build path via a hard exit) is contained and
- * the watcher keeps running.
- *
- * Building `astryx theme build` requires a compiled @astryxdesign/core, so this
- * suite builds core once in beforeAll via the shared ensureCoreBuilt() helper —
- * which serializes concurrent Vitest workers behind a lock — to stay
- * self-sufficient regardless of CI job ordering.
- */
-
-import {describe, it, expect, beforeAll, beforeEach, afterEach} from 'vitest';
-import {execFileSync, spawn} 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';
-import {ensureCoreBuilt} from './ensure-core-built.mjs';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const CLI_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');
-
-function runCli(args, cwd) {
-  try {
-    const out = execFileSync('node', [CLI_BIN, ...args], {
-      cwd,
-      encoding: 'utf-8',
-      stdio: ['ignore', 'pipe', 'pipe'],
-      env: {...process.env, FORCE_COLOR: '0'},
-    });
-    return {code: 0, stdout: out, stderr: ''};
-  } catch (e) {
-    return {
-      code: e.status ?? 1,
-      stdout: e.stdout?.toString() ?? '',
-      stderr: e.stderr?.toString() ?? '',
-    };
-  }
-}
-
-/** Poll until `predicate()` is true or the timeout elapses. */
-async function waitFor(predicate, {timeout = 8000, interval = 50} = {}) {
-  const start = Date.now();
-  for (;;) {
-    if (predicate()) return true;
-    if (Date.now() - start > timeout) return false;
-    await new Promise(r => setTimeout(r, interval));
-  }
-}
-
-beforeAll(() => {
-  ensureCoreBuilt();
-}, 200_000);
-
-let tmpDir;
-beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-build-theme-watch-'));
-});
-afterEach(() => {
-  fs.rmSync(tmpDir, {recursive: true, force: true});
-});
-
-describe('theme build --watch', () => {
-  it('advertises the flag in --help', () => {
-    const result = runCli(['theme', 'build', '--help'], process.cwd());
-    const out = result.stdout + result.stderr;
-    expect(out).toMatch(/--watch/);
-  });
-
-  it('rejects --watch together with --json (single-envelope contract)', () => {
-    const themeFile = path.join(tmpDir, 'wt.mjs');
-    fs.writeFileSync(
-      themeFile,
-      `export default { name: 'wt', tokens: { '--color-bg': '#fff' } };\n`,
-    );
-    const result = runCli(
-      ['--json', 'theme', 'build', path.relative(tmpDir, themeFile), '--watch'],
-      tmpDir,
-    );
-    expect(result.code).not.toBe(0);
-    expect(result.stdout + result.stderr).toMatch(/watch/i);
-  });
-
-  it('builds initially, rebuilds on change, and stops cleanly on SIGINT', async () => {
-    const themeFile = path.join(tmpDir, 'wt.mjs');
-    const cssFile = path.join(tmpDir, 'wt.css');
-    fs.writeFileSync(
-      themeFile,
-      `export default { name: 'wt', tokens: { '--color-bg': '#ffffff' } };\n`,
-    );
-
-    const child = spawn(
-      process.execPath,
-      [CLI_BIN, 'theme', 'build', 'wt.mjs', '--watch'],
-      {cwd: tmpDir, env: {...process.env, FORCE_COLOR: '0'}},
-    );
-    let stdout = '';
-    child.stdout.on('data', d => (stdout += d.toString()));
-    child.stderr.on('data', d => (stdout += d.toString()));
-
-    try {
-      // Initial build produces the CSS.
-      const built = await waitFor(() => fs.existsSync(cssFile));
-      expect(built).toBe(true);
-      const firstCss = fs.readFileSync(cssFile, 'utf-8');
-      expect(firstCss).toMatch(/#ffffff/);
-
-      // Wait until the watcher is actually watching before editing, so the
-      // change isn't missed. The "Watching" line is printed only after fs.watch
-      // is armed, so it's a truthful "safe to edit now" signal.
-      await waitFor(() => /Watching/i.test(stdout));
-
-      // Change the theme — the token value changes so the CSS must change.
-      // fs.watch event delivery is best-effort on some platforms/under load, so
-      // re-touch the file until the rebuild is observed (idempotent write).
-      const changed = `export default { name: 'wt', tokens: { '--color-bg': '#010203' } };\n`;
-      fs.writeFileSync(themeFile, changed);
-
-      const rebuilt = await waitFor(
-        () => {
-          try {
-            if (fs.readFileSync(cssFile, 'utf-8').includes('#010203')) return true;
-          } catch {
-            // CSS mid-write; fall through to re-touch.
-          }
-          // Re-touch to recover a dropped watch event under load.
-          try {
-            fs.writeFileSync(themeFile, changed);
-          } catch {
-            // Re-touch failed (e.g. dir mid-teardown); the next poll retries.
-          }
-          return false;
-        },
-        {timeout: 20000, interval: 200},
-      );
-      expect(rebuilt).toBe(true);
-      expect(stdout).toMatch(/rebuild/i);
-    } finally {
-      // SIGINT must stop the watcher and exit cleanly.
-      child.kill('SIGINT');
-    }
-
-    const exited = await new Promise(resolve => {
-      let done = false;
-      child.on('exit', () => {
-        done = true;
-        resolve(true);
-      });
-      setTimeout(() => resolve(done), 4000);
-    });
-    expect(exited).toBe(true);
-    expect(stdout).toMatch(/Stopped watching/);
-  }, 30_000);
-});

package/cli/commands/build.mjs

@@ -1,172 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file build command — thin wrapper around api/build.
- *
- *   astryx build                  → the PLAYBOOK (how to build a page)
- *   astryx build "<what>"         → a COMPOSITION KIT (closest page template,
- *                                   blocks, components) with a recommended START.
- *
- * All grouping/scoring lives in api/build; this file only parses flags and
- * renders. Command strings are prefixed for the caller's package manager here
- * (never in the API payload) via formatCliCommand/getCliInvocation.
- */
-
-import {getCliInvocation, formatCliCommand} from '../../utils/package-manager.mjs';
-import {jsonOut, humanLog} from '../../lib/json.mjs';
-import {cliError} from '../../lib/cli-error.mjs';
-import {build as buildApi} from '../../api/build/build.mjs';
-
-/**
- * Print the build playbook (shown when `build` is run with no query).
- * @param {string} run - The CLI invocation prefix (e.g. `npx astryx`).
- */
-function printPlaybook(run) {
-  const lines = [
-    '',
-    'How to build a page with Astryx',
-    '',
-    "1. Find a starting point for what you're building:",
-    `     ${run} build "<what you're building>"`,
-    '   → returns the closest [page] template, the [block]s that cover parts,',
-    '     and the [component]s to fill the gaps, with a "Compose:" suggestion.',
-    '',
-    '2. If a [page] template matches → scaffold it and adapt:',
-    `     ${run} template <name> [path]`,
-    '',
-    '3. If nothing matches exactly → compose:',
-    `     ${run} template <name> --skeleton   # study a close page's layout`,
-    `     ${run} template <BlockName>         # drop in each block from the kit`,
-    `     ${run} component <Name>             # fill remaining gaps (read props)`,
-    '',
-    '4. Rules (keep it on-system):',
-    '   - No <div>/raw HTML for layout — use VStack/HStack/Grid/Stack/Card etc.',
-    `   - No style={{}} — use component props; design tokens via \`${run} docs tokens\`.`,
-    '   - Wrap the app in <Theme theme={...}> and import core reset.css + astryx.css.',
-    '',
-    `Tip: \`${run} build "<idea>"\` is the fastest way in. For a neutral`,
-    `lookup of any component/doc/template, use \`${run} search <query>\`.`,
-    '',
-  ];
-  for (const l of lines) humanLog(l);
-}
-
-/**
- * @param {import('commander').Command} program
- */
-export function registerBuild(program) {
-  program
-    .command('build [query]')
-    .description('Build a page: composition kit for an idea, or the workflow playbook (no args)')
-    .option('--type <domain>', 'Filter the kit to one domain (component|hook|template)')
-    .option('--limit <n>', 'Max candidates to draw from (default 60)')
-    .option('--detail', 'Verbose output (include import paths and match reason)')
-    .action(async (/** @type {string | undefined} */ query, /** @type {{type?: import('../../types/search').SearchDomain, limit?: string, detail?: boolean}} */ options) => {
-      const run = getCliInvocation();
-      const json = program.opts().json || false;
-
-      // No query → the playbook. Still routed through the API for the envelope.
-      if (!query || !String(query).trim()) {
-        const result = await buildApi(undefined, {cwd: process.cwd()});
-        if (json) return jsonOut(result);
-        printPlaybook(run);
-        return;
-      }
-
-      // Arg validation stays in the CLI.
-      let limit = 60;
-      if (options.limit != null) {
-        const parsed = Number.parseInt(options.limit, 10);
-        if (!Number.isFinite(parsed) || parsed <= 0) {
-          cliError(`Invalid --limit value "${options.limit}". Must be a positive integer.`);
-          return;
-        }
-        limit = parsed;
-      }
-
-      /** @type {import('../../types/build').BuildKitResponse} */
-      let result;
-      try {
-        result = /** @type {import('../../types/build').BuildKitResponse} */ (
-          await buildApi(query, {cwd: process.cwd(), type: options.type, limit})
-        );
-      } catch (e) {
-        const err = /** @type {import('../../api/error.mjs').AstryxError} */ (e);
-        cliError(err.message, {suggestions: err.suggestions});
-        return;
-      }
-
-      if (json) return jsonOut(result);
-
-      const {query: q, hasResults, directMatch, pages, blocks, domain, frame, foundation} =
-        result.data;
-
-      if (!hasResults) {
-        humanLog('');
-        humanLog(`No matches for "${q}".`);
-        humanLog(`Try a broader term, or browse: ${run} component --list`);
-        humanLog('');
-        return;
-      }
-
-      const printItem = (/** @type {import('../../types/search').SearchResultEntry} */ r, /** @type {string} */ label) => {
-        const display = r.domain === 'template' && r.displayName ? r.displayName : r.name;
-        humanLog('');
-        humanLog(`  [${label}] ${display}`);
-        if (r.description) humanLog(`          ${r.description}`);
-        humanLog(`          → ${formatCliCommand(r.command)}`);
-        if (options.detail) {
-          if (r.import) humanLog(`          import: ${r.import}`);
-          humanLog(`          match: ${r.reason} (score ${r.score})`);
-        }
-      };
-
-      humanLog('');
-      humanLog(`Building "${q}":`);
-
-      // START — the single recommended path.
-      humanLog('');
-      if (directMatch) {
-        humanLog(`START → Scaffold the \`${pages[0].name}\` page template, then adapt: ${run} template ${pages[0].name} ./src/App.tsx`);
-      } else if (pages.length) {
-        humanLog(`START → No exact page template. Use \`${pages[0].name}\` as a layout reference (${run} template ${pages[0].name} --skeleton) and compose the pieces below.`);
-      } else {
-        humanLog(`START → No page template fits. Frame with AppShell and compose the blocks + components below.`);
-      }
-
-      // PAGE
-      if (pages.length) {
-        humanLog('');
-        humanLog(directMatch ? 'PAGE TEMPLATE — direct match:' : 'CLOSEST PAGE TEMPLATES — layout reference:');
-        pages.forEach(p => printItem(p, directMatch ? 'page' : 'closest'));
-      }
-
-      // FRAME — always (the page shell).
-      humanLog('');
-      humanLog(`FRAME — page shell (always): ${frame.join(', ')}`);
-      humanLog(`          full-page → AppShell; or Layout + SideNav/TopNav. ${run} component AppShell`);
-
-      // BLOCKS — idea-specific composed patterns.
-      if (blocks.length) {
-        humanLog('');
-        humanLog('BLOCKS — drop-in patterns that cover parts of it:');
-        blocks.forEach(b => printItem(b, 'block'));
-      }
-
-      // DOMAIN COMPONENTS — idea-specific atoms.
-      if (domain.length) {
-        humanLog('');
-        humanLog('DOMAIN COMPONENTS — specific to this idea:');
-        domain.forEach(c => printItem(c, c.domain === 'hook' ? 'hook' : 'component'));
-      }
-
-      // FOUNDATION — always (layout/typography/actions).
-      humanLog('');
-      humanLog(`FOUNDATION — always available (layout/text/actions): ${foundation.join(' ')}`);
-
-      // SETUP — so it renders / stays on-system.
-      humanLog('');
-      humanLog('SETUP — import "@astryxdesign/core/reset.css" + "astryx.css". No <div>/style for layout — use Stack/Grid + tokens.');
-      humanLog('');
-    });
-}