@astryxdesign/cli 0.0.0-bootstrap.0 → 0.1.0-canary.08d4cf4

package/src/commands/build-theme.path-safety.test.mjs

@@ -0,0 +1,117 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Path-safety regression tests for `astryx theme build`.
+ *
+ * Covers:
+ *   - Theme name with `..` segments cannot escape the output directory.
+ *   - Theme name with `/` is rejected with a clear error (vs. ENOENT).
+ *   - Multi-file write is atomic: if one file fails, none are left behind.
+ *
+ * Runs the CLI via execFileSync against a tiny synthetic theme file.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import {execFileSync} 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_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() ?? '',
+    };
+  }
+}
+
+function writeTheme(dir, name) {
+  fs.mkdirSync(dir, {recursive: true});
+  const file = path.join(dir, 'theme.mjs');
+  // Plain object literal so the legacy regex+eval path can parse it
+  // without needing jiti / TS, and without depending on @astryxdesign/core being
+  // built. The eval path explicitly supports this shape.
+  fs.writeFileSync(
+    file,
+    `export default { name: ${JSON.stringify(name)}, tokens: { '--color-bg': '#fff' } };\n`,
+  );
+  return file;
+}
+
+let tmpDir;
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-build-theme-paths-'));
+});
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('theme build path safety', () => {
+  it('rejects a theme name containing ../ traversal and writes no JS outside the input dir', () => {
+    const project = path.join(tmpDir, 'project');
+    const themesDir = path.join(project, 'themes');
+    const outside = path.join(tmpDir, 'outside');
+    fs.mkdirSync(outside, {recursive: true});
+
+    const themeFile = writeTheme(themesDir, '../../escaped');
+
+    const result = runCli(
+      ['theme', 'build', path.relative(project, themeFile)],
+      project,
+    );
+
+    expect(result.code).not.toBe(0);
+    expect(result.stderr + result.stdout).toMatch(/path separator|invalid theme name/i);
+
+    // The traversal target must not exist.
+    expect(fs.existsSync(path.join(tmpDir, 'escaped.js'))).toBe(false);
+    expect(fs.existsSync(path.join(tmpDir, 'escaped.css'))).toBe(false);
+    expect(fs.readdirSync(outside)).toEqual([]);
+  });
+
+  it('rejects a theme name containing /', () => {
+    const project = path.join(tmpDir, 'project');
+    const themesDir = path.join(project, 'themes');
+
+    const themeFile = writeTheme(themesDir, 'bad/name');
+
+    const result = runCli(
+      ['theme', 'build', path.relative(project, themeFile)],
+      project,
+    );
+
+    expect(result.code).not.toBe(0);
+    expect(result.stderr + result.stdout).toMatch(/path separator/i);
+
+    // No partial output — neither bad nor bad/name files should exist.
+    expect(fs.existsSync(path.join(themesDir, 'bad.js'))).toBe(false);
+    expect(fs.existsSync(path.join(themesDir, 'bad', 'name.js'))).toBe(false);
+  });
+
+  it('does not leave partial output (no CSS without JS) on a sanitized rejection', () => {
+    const project = path.join(tmpDir, 'project');
+    const themesDir = path.join(project, 'themes');
+
+    const themeFile = writeTheme(themesDir, '../leak');
+
+    runCli(['theme', 'build', path.relative(project, themeFile)], project);
+
+    // Neither the CSS nor any sibling JS should have been written.
+    const entries = fs.readdirSync(themesDir).sort();
+    expect(entries).toEqual(['theme.mjs']);
+  });
+});

package/src/commands/build-theme.prose.test.mjs

@@ -0,0 +1,135 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Regression test for prose output of `astryx theme build`.
+ *
+ * `astryx theme build` has a single CSS-generation path — @astryxdesign/core's generator,
+ * the same one the <Theme> runtime uses (generateThemeCSS). It always emits
+ * prose element defaults (h1–h6, p, small, code, hr) so unstyled HTML inherits
+ * the theme's typography, exactly like the runtime. There is intentionally no
+ * way to omit them (the old `--no-prose` flag was removed: it let the build
+ * emit something the runtime never would, breaking the build⇄runtime parity).
+ *
+ * Covers:
+ *   - prose defaults ship in `@layer reset` (zero-specificity :where()), NOT
+ *     `@layer astryx-theme`, so component/Markdown StyleX always wins;
+ *   - no raw element margins are emitted (reset.css zeroes them and the
+ *     components own block spacing — see the docsite Markdown regression);
+ *   - paragraphs use the body font, not the heading font.
+ *
+ * Building `astryx theme build` requires a compiled @astryxdesign/core (there is no in-CLI
+ * fallback generator), so this suite builds core once in beforeAll — mirroring
+ * scripts/build-css.test.mjs — to stay self-sufficient regardless of CI job
+ * ordering.
+ */
+
+import {describe, it, expect, beforeAll, beforeEach, afterEach} from 'vitest';
+import {execFileSync} 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_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');
+const REPO_ROOT = path.resolve(__dirname, '../../../..');
+const CORE_THEME_ENTRY = path.join(
+  REPO_ROOT,
+  'packages/core/dist/theme/index.js',
+);
+
+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() ?? '',
+    };
+  }
+}
+
+function writeTheme(dir, name) {
+  fs.mkdirSync(dir, {recursive: true});
+  // The CLI writes <basename>.css next to the source file, so use the
+  // theme name as the filename for unambiguous fixtures.
+  const file = path.join(dir, `${name}.mjs`);
+  fs.writeFileSync(
+    file,
+    `export default { name: ${JSON.stringify(name)}, tokens: { '--color-bg': '#fff' } };\n`,
+  );
+  return file;
+}
+
+// `astryx theme build` imports the compiled @astryxdesign/core/theme entry. Build core
+// once if it isn't already present so the suite works in any CI job.
+beforeAll(() => {
+  if (!fs.existsSync(CORE_THEME_ENTRY)) {
+    execFileSync('pnpm', ['-F', '@astryxdesign/core', 'build'], {
+      cwd: REPO_ROOT,
+      stdio: 'pipe',
+      timeout: 180_000,
+    });
+  }
+}, 200_000);
+
+let tmpDir;
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-build-theme-prose-'));
+});
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('theme build prose output', () => {
+  it('always emits prose mappings in @layer reset', () => {
+    const project = path.join(tmpDir, 'project');
+    const themesDir = path.join(project, 'themes');
+    const themeFile = writeTheme(themesDir, 'with-prose');
+
+    const result = runCli(
+      ['theme', 'build', path.relative(project, themeFile)],
+      project,
+    );
+
+    expect(result.code).toBe(0);
+
+    const cssPath = path.join(themesDir, 'with-prose.css');
+    expect(fs.existsSync(cssPath)).toBe(true);
+    const css = fs.readFileSync(cssPath, 'utf-8');
+
+    // Prose defaults are zero-specificity :where() rules in @layer reset,
+    // NOT @layer astryx-theme, so Markdown/component StyleX always wins.
+    expect(css).toMatch(/@layer reset/);
+    expect(css).toMatch(/:where\(h1, h2, h3, h4, h5, h6\)/);
+    // Paragraphs use the body font (regression: they used the heading font).
+    expect(css).toMatch(/:where\(p\)[^}]*font-family: var\(--font-family-body\)/);
+    // No raw element margins — reset.css + component StyleX own spacing.
+    const proseBlock = css.slice(
+      css.indexOf('@layer reset'),
+      css.indexOf('@layer astryx-theme'),
+    );
+    expect(proseBlock).not.toMatch(/margin/);
+
+    // Layer placement: prose (reset) must come before component overrides
+    // (astryx-theme) so the cascade resolves correctly.
+    const resetIndex = css.indexOf('@layer reset');
+    const themeIndex = css.indexOf('@layer astryx-theme');
+    expect(resetIndex).toBeGreaterThanOrEqual(0);
+    expect(themeIndex).toBeGreaterThan(resetIndex);
+    expect(css.indexOf(':where(p)')).toBeLessThan(themeIndex);
+  });
+
+  it('has no --no-prose flag (prose is non-optional)', () => {
+    const result = runCli(['theme', 'build', '--help'], process.cwd());
+    // The flag was removed; build always emits prose to match the runtime.
+    expect(result.stdout + result.stderr).not.toContain('--no-prose');
+  });
+});

package/src/commands/build.mjs

@@ -0,0 +1,196 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file build command — the page-building assistant.
+ *
+ * Two modes:
+ *   astryx build                  → the PLAYBOOK: how to build a page with Astryx
+ *   astryx build "<what>"         → a COMPOSITION KIT for what you're building:
+ *                                   the closest page template (scaffold or layout
+ *                                   reference), the blocks that cover parts, and
+ *                                   the components to fill gaps, plus a one-line
+ *                                   "Compose:" suggestion.
+ *
+ * `build` is the opinionated "assemble a page" verb. For a neutral lookup across
+ * the whole CLI, use `astryx search <query>` instead.
+ */
+
+import {getRunPrefix} from '../utils/package-manager.mjs';
+import {jsonOut, humanLog} from '../lib/json.mjs';
+import {cliError} from '../lib/cli-error.mjs';
+import {search as searchApi} from '../api/search.mjs';
+
+/** A page scoring at/above this is confident enough to call a direct match. */
+const PAGE_DIRECT = 95;
+/** Below this a page is too weak to even offer as a layout reference. */
+const PAGE_FLOOR = 50;
+/** Below this a block/domain-component match is incidental noise, not surfaced. */
+const DOMAIN_FLOOR = 55;
+
+/**
+ * Always-surfaced primitives. Every page needs a shell + layout/typography/
+ * action atoms, but these never keyword-match an idea ("dashboard" != "Stack"),
+ * so search alone never returns them. We list them unconditionally so an agent
+ * composing from scratch has the whole kit (esp. off-template).
+ */
+const FRAME = ['AppShell', 'TopNav', 'SideNav', 'Layout'];
+const FOUNDATION = [
+  'VStack', 'HStack', 'Grid', 'StackItem', 'Card', 'Section',
+  'Text', 'Heading', 'Button', 'Icon', 'Badge', 'Divider',
+];
+const ALWAYS = new Set([...FRAME, ...FOUNDATION]);
+
+/** Print the build playbook (shown when `build` is run with no query). */
+function printPlaybook(run) {
+  const lines = [
+    '',
+    'How to build a page with Astryx',
+    '',
+    "1. Find a starting point for what you're building:",
+    `     ${run} astryx 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} astryx template <name> [path]`,
+    '',
+    '3. If nothing matches exactly → compose:',
+    `     ${run} astryx template <name> --skeleton   # study a close page's layout`,
+    `     ${run} astryx template <BlockName>         # drop in each block from the kit`,
+    `     ${run} astryx 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 `astryx docs tokens`.',
+    '   - Wrap the app in <Theme theme={...}> and import core reset.css + astryx.css.',
+    '',
+    `Tip: \`${run} astryx build "<idea>"\` is the fastest way in. For a neutral`,
+    `lookup of any component/doc/template, use \`${run} astryx search <query>\`.`,
+    '',
+  ];
+  for (const l of lines) humanLog(l);
+}
+
+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 (query, options) => {
+      const run = getRunPrefix();
+      const json = program.opts().json || false;
+
+      // No query → print the playbook (the "how to build" skill).
+      if (!query || !String(query).trim()) {
+        if (json) return jsonOut('build.help', {playbook: true});
+        printPlaybook(run);
+        return;
+      }
+
+      // Default to a deep pool so each role section has candidates after grouping.
+      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;
+      }
+
+      let result;
+      try {
+        result = await searchApi(query, {cwd: process.cwd(), type: options.type, limit});
+      } catch (e) {
+        cliError(e.message, {suggestions: e.suggestions});
+        return;
+      }
+
+      if (json) return jsonOut(result.type, result.data);
+
+      const {query: q, results} = result.data;
+
+      if (results.length === 0) {
+        humanLog('');
+        humanLog(`No matches for "${q}".`);
+        humanLog(`Try a broader term, or browse: ${run} astryx component --list`);
+        humanLog('');
+        return;
+      }
+
+      // ── Group results by role (the build kit) ──────────────────────
+      const pages = results
+        .filter(r => r.domain === 'template' && r.kind !== 'block' && r.score >= PAGE_FLOOR)
+        .slice(0, 3);
+      const blocks = results
+        .filter(r => r.domain === 'template' && r.kind === 'block' && r.score >= DOMAIN_FLOOR)
+        .slice(0, 5);
+      // Idea-specific atoms = matched components/hooks MINUS the always-on kit.
+      const domain = results
+        .filter(r => (r.domain === 'component' || r.domain === 'hook') && r.score >= DOMAIN_FLOOR && !ALWAYS.has(r.name))
+        .slice(0, 6);
+      const directMatch = pages.length > 0 && pages[0].score >= PAGE_DIRECT;
+
+      const printItem = (r, label) => {
+        const display = r.domain === 'template' && r.displayName ? r.displayName : r.name;
+        humanLog('');
+        humanLog(`  [${label}] ${display}`);
+        if (r.description) humanLog(`          ${r.description}`);
+        humanLog(`          → ${run} ${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} astryx 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} astryx 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} astryx 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('');
+    });
+}

package/src/commands/component/index.mjs

@@ -0,0 +1,224 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file component command — List components and print component docs
+ *
+ * Global options: --detail full|compact|brief, --lang en|zh|dense
+ */
+
+import {findCoreDir} from '../../utils/paths.mjs';
+import {
+  resolveImportPath,
+} from '../../lib/component-discovery.mjs';
+import {
+  formatFull,
+  formatCompact,
+  formatBrief,
+  formatProps,
+  formatBriefAll,
+} from '../../lib/component-format.mjs';
+import {resolveTheme} from '../../lib/resolve-theme.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 {component as componentApi} from '../../api/component.mjs';
+import {findRelatedBlocks} from '../../api/template.mjs';
+
+export function registerComponent(program) {
+  program
+    .command('component [name]')
+    .description('List components or print component docs')
+    .option('--list', 'List all components grouped by category')
+    .option('--category <category>', 'List components in a specific category')
+    .option('--props', 'Print only the props table')
+    .option('--source', 'Print component source code')
+    .option('--showcase', 'Print showcase source code')
+    .option('--blocks', 'List example blocks: showcase, examples, and related')
+    .option('--package <name>', 'Scope lookup to an external package (e.g. @acme/xds-widgets)')
+    .action(async (name, options) => {
+      const run = getRunPrefix();
+      const zh = program.opts().zh || false;
+      const dense = program.opts().dense || false;
+      const lang = program.opts().lang || null;
+      const detailSource = program.getOptionValueSource('detail');
+      const isListView = options.list || options.category || !name;
+      // Default detail level is full for single-component view, brief for list views.
+      // (List views are scannable name lists; users can opt into compact/full.)
+      let detail = program.opts().detail || 'full';
+      if (isListView && detailSource === 'default') detail = 'brief';
+      const json = program.opts().json || false;
+
+      const validDetails = ['full', 'compact', 'brief'];
+      if (!validDetails.includes(detail)) {
+        cliError(`Invalid --detail value "${detail}". Valid levels: ${validDetails.join(', ')}`, {code: ERROR_CODES.ERR_INVALID_DETAIL});
+        return;
+      }
+
+      let result;
+      try {
+        result = await componentApi(name, {
+          cwd: process.cwd(),
+          list: options.list,
+          category: options.category,
+          package: options.package,
+          props: options.props,
+          source: options.source,
+          showcase: options.showcase,
+          blocks: options.blocks,
+          detail,
+          lang, zh, dense,
+        });
+      } catch (e) {
+        cliError(e.message, {suggestions: e.suggestions, code: e.code});
+        return;
+      }
+
+      if (json) return jsonOut(result.type, result.data);
+
+      // ── Text output ────────────────────────────────────────────
+      const coreDir = findCoreDir(process.cwd());
+      const themeData = resolveTheme(process.cwd());
+
+      switch (result.type) {
+        case 'component.list': {
+          // --detail brief (default for list views) — names with import paths.
+          if (options.category) {
+            const [cat, comps] = Object.entries(result.data)[0];
+            humanLog(`\n${cat}:`);
+            for (const comp of comps) {
+              const importPath = resolveImportPath(coreDir, comp);
+              humanLog(`  ${comp}  ← ${importPath}`);
+            }
+            humanLog('');
+          } else {
+            humanLog('');
+            for (const [key, comps] of Object.entries(result.data)) {
+              const isUngrouped = comps.length === 1 && comps[0] === key;
+              if (isUngrouped) {
+                const importPath = resolveImportPath(coreDir, key);
+                humanLog(`${key}  ← ${importPath}`);
+              } else {
+                humanLog(`${key} (group)`);
+                for (const comp of comps) {
+                  const importPath = resolveImportPath(coreDir, comp);
+                  humanLog(`  ${comp}  ← ${importPath}`);
+                }
+              }
+            }
+            humanLog('');
+            humanLog(`Import from the path shown (e.g. import {Button} from '@astryxdesign/core/Button')`);
+            humanLog(`Usage: ${run} astryx component <name>`);
+            humanLog('');
+          }
+          break;
+        }
+
+        case 'component.brief': {
+          // --detail compact — name + 1-line description per entry.
+          humanLog('');
+          const entries = Object.entries(result.data);
+          for (const [cat, items] of entries) {
+            // Skip the synthetic group header when there's only one ungrouped category
+            const isUngrouped =
+              entries.length === 1 && items.length === 1 && items[0]?.name === cat;
+            if (!isUngrouped) humanLog(`${cat} (group)`);
+            for (const item of items) {
+              const importHint = item.import ? `  ← ${item.import}` : '';
+              const desc = item.description ? ` — ${item.description}` : '';
+              humanLog(`  XDS${item.name}${importHint}${desc}`);
+            }
+            humanLog('');
+          }
+          humanLog(`Import from the path shown (e.g. import {Button} from '@astryxdesign/core/Button')`);
+          humanLog(`Usage: ${run} astryx component <name>`);
+          humanLog('');
+          break;
+        }
+
+        case 'component.full': {
+          // --detail full — dense per-component docs (signature, props, theming, examples).
+          humanLog(await formatBriefAll(coreDir, {zh, lang, themeData}));
+          break;
+        }
+
+        case 'component.detail': {
+          if (detail === 'brief') {
+            const resolvedName = (name || '').replace(/^XDS/, '');
+            const importHint = resolveImportPath(coreDir, resolvedName);
+            humanLog(formatBrief(result.data, resolvedName, importHint, {themeData}));
+          } else if (detail === 'compact') {
+            const resolvedName = (name || '').replace(/^XDS/, '');
+            const importHint = resolveImportPath(coreDir, resolvedName);
+            humanLog(formatCompact(result.data, resolvedName, importHint));
+          } else {
+            const resolvedName = (name || '').replace(/^XDS/, '');
+            const importHint = resolveImportPath(coreDir, resolvedName);
+            humanLog(formatFull(result.data, {themeData, importHint}));
+          }
+          const compName = (name || '').replace(/^XDS/, '');
+          const related = await findRelatedBlocks(compName);
+          if (related.length > 0) {
+            humanLog('\nRelated block templates:\n');
+            for (const b of related) {
+              humanLog(`  ${b.dirName}`);
+              if (b.description) humanLog(`    ${b.description}`);
+            }
+            humanLog('');
+          }
+          break;
+        }
+
+        case 'component.detail.props': {
+          const resolvedName = (name || '').replace(/^XDS/, '');
+          humanLog(formatProps({props: result.data}, resolvedName));
+          break;
+        }
+
+        case 'component.detail.source': {
+          humanLog(result.data.source);
+          break;
+        }
+
+        case 'component.detail.showcase': {
+          humanLog(result.data.source);
+          break;
+        }
+
+        case 'component.detail.blocks': {
+          const {showcase, examples, related} = result.data;
+          if (showcase) {
+            humanLog(`\nShowcase: ${showcase.displayName}`);
+            if (showcase.description) humanLog(`  ${showcase.description}`);
+          }
+          if (examples.length > 0) {
+            humanLog('\nExamples:\n');
+            for (const b of examples) {
+              humanLog(`  ${b.name}`);
+              if (b.description) humanLog(`    ${b.description}`);
+            }
+          }
+          if (related.length > 0) {
+            humanLog(`\nRelated: ${related.length} blocks that use ${result.data.component}\n`);
+            for (const b of related) {
+              humanLog(`  ${b.name}`);
+            }
+          }
+          if (!showcase && examples.length === 0 && related.length === 0) {
+            humanLog(`\nNo blocks found for ${result.data.component}`);
+          }
+          humanLog('');
+          break;
+        }
+      }
+    });
+}
+
+
+// Re-export lib functions for backward compatibility
+// (agent-docs.mjs, tests, and generate-skill-doc.sh import from here)
+export {discoverComponents, discoverExternalComponents, discoverExternalComponentsGrouped, findComponentReadme, findComponentSource, findExternalComponentDoc, resolveImportPath} from '../../lib/component-discovery.mjs';
+export {discoverExternalPackages} from '../../utils/paths.mjs';
+export {loadDocs} from '../../lib/component-loader.mjs';
+export {formatFull, formatCompact, formatBrief, formatProps, formatBriefAll} from '../../lib/component-format.mjs';
+export {levenshteinDistance, findClosestComponents, searchComponents} from '../../lib/string-utils.mjs';