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

package/src/lib/manifest.mjs

@@ -0,0 +1,248 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Capability manifest — self-describing CLI surface for agents.
+ *
+ * `astryx --json` (and `astryx manifest --json`) emit a structured manifest that
+ * lets an AI agent drive the entire CLI WITHOUT scraping `--help` text. It is
+ * to the CLI what an OpenAPI spec is to an HTTP API.
+ *
+ * Most of the manifest is DERIVED from Commander metadata (program.commands,
+ * cmd.options, cmd.registeredArguments, cmd.description()) so it cannot drift
+ * out of sync with the real command definitions. The two pieces Commander does
+ * not know about — whether a command supports `--json`, and which response
+ * `type` discriminators it can emit — are layered on from:
+ *
+ *   - JSON_SUPPORTED  (the allowlist in index.mjs), and
+ *   - RESPONSE_TYPES  (the declarative map below).
+ *
+ * A drift-guard test (manifest.test.mjs) asserts every registered command
+ * appears in the manifest and every JSON-supported command has a response-type
+ * entry, so adding a command without describing it fails CI.
+ *
+ * @input  a configured Commander `program` + the JSON_SUPPORTED allowlist
+ * @output a `{ name, version, globalOptions, commands, responseTypes }` object
+ * @position consumed by the bare `astryx --json` action and the `manifest` command
+ */
+
+import {API_VERSION} from './json.mjs';
+
+/**
+ * Response `type` discriminators each fully-qualified command can emit in
+ * `--json` mode. Keyed by the same name Commander reports (parent + leaf,
+ * space-joined), e.g. `theme build`. Commander has no knowledge of these —
+ * they come from each command's `jsonOut(...)` call sites — so we keep them
+ * here, close to the JSON_SUPPORTED allowlist, and guard them with a test.
+ *
+ * @type {Record<string, string[]>}
+ */
+export const RESPONSE_TYPES = {
+  component: [
+    'component.list',
+    'component.brief',
+    'component.full',
+    'component.detail',
+    'component.detail.props',
+    'component.detail.source',
+    'component.detail.showcase',
+    'component.detail.blocks',
+  ],
+  docs: ['docs.list', 'docs.detail', 'docs.detail.section'],
+  discover: ['discover.list', 'discover.detail', 'discover.detail.doc', 'discover.search'],
+  search: ['search'],
+  swizzle: ['swizzle.list', 'swizzle.copy'],
+  template: [
+    'template.list',
+    'template.show',
+    'template.skeleton',
+    'template.copy',
+    'template.get',
+  ],
+  hook: ['hook.list', 'hook.brief', 'hook.full', 'hook.detail', 'hook.detail.params'],
+  'theme build': ['theme.build'],
+  upgrade: ['upgrade.list', 'upgrade.status', 'upgrade.run'],
+  'gap-report': ['gap-report.categories', 'gap-report.dryRun', 'gap-report.file'],
+  manifest: ['manifest'],
+  doctor: ['doctor'],
+};
+
+/**
+ * Example invocations per fully-qualified command. Optional, agent-facing.
+ * @type {Record<string, string[]>}
+ */
+const EXAMPLES = {
+  component: ['astryx component', 'astryx component XDSButton', 'astryx component XDSButton --props --json'],
+  docs: ['astryx docs', 'astryx docs spacing --json'],
+  discover: ['astryx discover --json'],
+  search: ['astryx search modal --json', 'astryx search button --type component --json'],
+  swizzle: ['astryx swizzle XDSButton'],
+  template: ['astryx template --json', 'astryx template dashboard ./src/app'],
+  hook: ['astryx hook', 'astryx hook useToggle --json'],
+  'theme build': ['astryx theme build ./src/themes/ocean.ts --out ./dist/ocean.css'],
+  upgrade: ['astryx upgrade --json'],
+  manifest: ['astryx manifest --json', 'astryx --json'],
+  doctor: ['astryx doctor', 'astryx doctor --json'],
+  init: ['astryx init'],
+};
+
+/**
+ * Map a Commander Option to a flag descriptor. Derives type from whether the
+ * option takes a value (boolean vs string), surfaces `choices` and `default`.
+ *
+ * @param {import('commander').Option} opt
+ * @returns {{flag: string, description: string, type: string, choices?: string[], default?: unknown, negate?: boolean}}
+ */
+function describeOption(opt) {
+  const o = /** @type {any} */ (opt);
+  const takesValue = o.required || o.optional;
+  /** @type {any} */
+  const d = {
+    flag: o.flags,
+    description: o.description || '',
+    type: takesValue ? 'string' : 'boolean',
+  };
+  if (Array.isArray(o.argChoices) && o.argChoices.length > 0) {
+    d.choices = [...o.argChoices];
+    d.type = 'enum';
+  }
+  if (o.defaultValue !== undefined) d.default = o.defaultValue;
+  // `--no-foo` style negation flags
+  if (o.negate) d.negate = true;
+  return d;
+}
+
+/**
+ * Map a Commander positional argument to an arg descriptor.
+ * @param {import('commander').Argument} arg
+ * @returns {{name: string, required: boolean, variadic: boolean, description: string}}
+ */
+function describeArgument(arg) {
+  const a = /** @type {any} */ (arg);
+  return {
+    name: a.name(),
+    required: a.required === true,
+    variadic: a.variadic === true,
+    description: a.description || '',
+  };
+}
+
+/**
+ * Compute the fully-qualified command name relative to the root program,
+ * e.g. `theme build`. The root program itself maps to ''.
+ * @param {import('commander').Command} cmd
+ * @param {import('commander').Command} root
+ * @returns {string}
+ */
+function fullName(cmd, root) {
+  const parts = [];
+  /** @type {import('commander').Command | null} */
+  let c = cmd;
+  while (c && c !== root) {
+    parts.unshift(c.name());
+    c = c.parent;
+  }
+  return parts.join(' ');
+}
+
+/**
+ * Recursively describe a Commander command and its subcommands.
+ *
+ * @param {import('commander').Command} cmd
+ * @param {import('commander').Command} root
+ * @param {Set<string>} jsonSupported  fully-qualified names that support --json
+ * @returns {object | null}  null for hidden/internal commands
+ */
+function describeCommand(cmd, root, jsonSupported) {
+  const name = fullName(cmd, root);
+  // Skip the auto-generated help command and any hidden/internal commands
+  // (e.g. the postinstall shim) — agents never invoke these directly.
+  // `_hidden` is a Commander internal not present on its public types.
+  if (!name || /** @type {any} */ (cmd)._hidden || name === 'help') return null;
+
+  const subcommands = /** @type {object[]} */ ((cmd.commands || [])
+    .map((sub) => describeCommand(sub, root, jsonSupported))
+    .filter(Boolean));
+
+  // `registeredArguments` is Commander 12's public-ish accessor; `_args` is the
+  // older internal. Cast through any to read whichever exists.
+  const args =
+    /** @type {any[]} */ (/** @type {any} */ (cmd).registeredArguments || /** @type {any} */ (cmd)._args || []);
+
+  /** @type {any} */
+  const entry = {
+    name,
+    description: cmd.description() || '',
+    arguments: args.map(describeArgument),
+    options: (cmd.options || []).map(describeOption),
+    json: jsonSupported.has(name),
+  };
+
+  const aliases = cmd.aliases ? cmd.aliases() : [];
+  if (aliases && aliases.length > 0) entry.aliases = [...aliases];
+
+  // Response types this command can emit in --json mode (only meaningful for
+  // JSON-supported leaves). Subcommand groups (e.g. bare `theme`) have none.
+  if (RESPONSE_TYPES[name]) entry.responseTypes = [...RESPONSE_TYPES[name]];
+
+  if (EXAMPLES[name]) entry.examples = [...EXAMPLES[name]];
+
+  if (subcommands.length > 0) entry.subcommands = subcommands;
+
+  return entry;
+}
+
+/**
+ * Describe the global options declared on the root program (--json, --lang,
+ * --detail, --zh, --dense, --version). Documented once at top level so each
+ * command entry doesn't repeat them.
+ *
+ * @param {import('commander').Command} program
+ * @returns {Array<object>}
+ */
+function describeGlobalOptions(program) {
+  const opts = (program.options || []).map(describeOption);
+  // Commander registers a built-in --version flag; if for some reason it
+  // isn't present in program.options, surface it so the manifest is complete.
+  if (!opts.some((o) => /(^|[\s,])--version\b/.test(o.flag))) {
+    opts.push({
+      flag: '-V, --version',
+      description: 'Output the version number',
+      type: 'boolean',
+    });
+  }
+  return opts;
+}
+
+/**
+ * Build the full capability manifest from a configured Commander program.
+ *
+ * @param {import('commander').Command} program  the root program
+ * @param {object} [opts]
+ * @param {Set<string>} [opts.jsonSupported]  the JSON_SUPPORTED allowlist
+ * @param {string} [opts.version]  CLI version (defaults to program.version())
+ * @returns {object}  the manifest `data` payload (sans envelope)
+ */
+export function buildManifest(program, opts = {}) {
+  const jsonSupported = opts.jsonSupported || new Set();
+  const version = opts.version || /** @type {any} */ (program)._version || '';
+
+  const commands = /** @type {any[]} */ ((program.commands || [])
+    .map((cmd) => describeCommand(cmd, program, jsonSupported))
+    .filter(Boolean))
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  return {
+    name: 'astryx',
+    version,
+    apiVersion: API_VERSION,
+    description: program.description() || '',
+    globalOptions: describeGlobalOptions(program),
+    commands,
+    jsonSupported: [...jsonSupported].sort(),
+    // Flat index of every response `type` discriminator the CLI can emit,
+    // keyed by command — lets an agent know what to expect back per call.
+    responseTypes: Object.fromEntries(
+      Object.entries(RESPONSE_TYPES).map(([k, v]) => [k, [...v]]),
+    ),
+  };
+}

package/src/lib/manifest.test.mjs

@@ -0,0 +1,176 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Tests for the CLI capability manifest.
+ *
+ * Two jobs:
+ *   1. DRIFT GUARDS — the manifest is the agent-facing contract for the whole
+ *      CLI surface. These tests fail if a command is added without describing
+ *      it: every registered command must appear in the manifest, every
+ *      JSON-supported command must declare its response types, and every
+ *      response-type key must map to a real command.
+ *   2. SHAPE — each command entry carries the required fields, global options
+ *      are described once, and the bare `xds --json` / `astryx manifest --json`
+ *      surfaces emit valid, enriched JSON.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {spawnSync} from 'node:child_process';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {program, JSON_SUPPORTED} from '../index.mjs';
+import {buildManifest, RESPONSE_TYPES} from './manifest.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');
+
+const manifest = buildManifest(program, {jsonSupported: JSON_SUPPORTED, version: '0.0.0-test'});
+
+/** Flatten the manifest command tree into fully-qualified names. */
+function flatten(cmds, out = []) {
+  for (const c of cmds) {
+    out.push(c);
+    if (c.subcommands) flatten(c.subcommands, out);
+  }
+  return out;
+}
+const allEntries = flatten(manifest.commands);
+const allNames = new Set(allEntries.map((c) => c.name));
+
+/** Fully-qualified names of every registered, non-hidden command in the program. */
+function registeredNames() {
+  const names = [];
+  const walk = (cmd, prefix) => {
+    for (const sub of cmd.commands || []) {
+      if (sub._hidden || sub.name() === 'help') continue;
+      const full = prefix ? `${prefix} ${sub.name()}` : sub.name();
+      names.push(full);
+      walk(sub, full);
+    }
+  };
+  walk(program, '');
+  return names;
+}
+
+describe('manifest: drift guards', () => {
+  it('lists every registered (non-hidden) command', () => {
+    for (const name of registeredNames()) {
+      expect(allNames.has(name), `manifest is missing command "${name}"`).toBe(true);
+    }
+  });
+
+  it('marks every JSON_SUPPORTED command as json:true', () => {
+    for (const name of JSON_SUPPORTED) {
+      const entry = allEntries.find((c) => c.name === name);
+      expect(entry, `JSON_SUPPORTED command "${name}" not in manifest`).toBeDefined();
+      expect(entry.json, `"${name}" should be json:true`).toBe(true);
+    }
+  });
+
+  it('declares response types for every JSON-supported command', () => {
+    for (const name of JSON_SUPPORTED) {
+      expect(
+        RESPONSE_TYPES[name],
+        `JSON-supported command "${name}" has no response-type entry`,
+      ).toBeDefined();
+      expect(RESPONSE_TYPES[name].length).toBeGreaterThan(0);
+    }
+  });
+
+  it('has no response-type entry for a command that does not exist', () => {
+    for (const name of Object.keys(RESPONSE_TYPES)) {
+      expect(allNames.has(name), `RESPONSE_TYPES key "${name}" is not a real command`).toBe(true);
+    }
+  });
+
+  it('every command with response types is json-supported', () => {
+    for (const entry of allEntries) {
+      if (entry.responseTypes) {
+        expect(entry.json, `"${entry.name}" emits types but isn't json-supported`).toBe(true);
+      }
+    }
+  });
+});
+
+describe('manifest: shape', () => {
+  it('has top-level metadata', () => {
+    expect(manifest.name).toBe('astryx');
+    expect(manifest.apiVersion).toBe(1);
+    expect(typeof manifest.description).toBe('string');
+    expect(Array.isArray(manifest.commands)).toBe(true);
+    expect(Array.isArray(manifest.globalOptions)).toBe(true);
+  });
+
+  it('describes global options once at top level (--json, --lang, --detail, --version)', () => {
+    const flags = manifest.globalOptions.map((o) => o.flag).join(' ');
+    expect(flags).toContain('--json');
+    expect(flags).toContain('--lang');
+    expect(flags).toContain('--detail');
+    expect(flags).toContain('--version');
+    // No duplicate --version
+    const versionCount = manifest.globalOptions.filter((o) => /--version\b/.test(o.flag)).length;
+    expect(versionCount).toBe(1);
+  });
+
+  it('surfaces enum choices and defaults on options', () => {
+    const detail = manifest.globalOptions.find((o) => o.flag.includes('--detail'));
+    expect(detail.type).toBe('enum');
+    expect(detail.choices).toEqual(['full', 'compact', 'brief']);
+    expect(detail.default).toBe('full');
+  });
+
+  it('each command entry carries the required fields', () => {
+    for (const c of allEntries) {
+      expect(typeof c.name).toBe('string');
+      expect(typeof c.description).toBe('string');
+      expect(Array.isArray(c.arguments)).toBe(true);
+      expect(Array.isArray(c.options)).toBe(true);
+      expect(typeof c.json).toBe('boolean');
+    }
+  });
+
+  it('derives arguments from Commander metadata', () => {
+    const component = allEntries.find((c) => c.name === 'component');
+    expect(component.arguments.map((a) => a.name)).toContain('name');
+    const themeBuild = allEntries.find((c) => c.name === 'theme build');
+    expect(themeBuild.arguments.map((a) => a.name)).toContain('file');
+    expect(themeBuild.arguments.find((a) => a.name === 'file').required).toBe(true);
+  });
+});
+
+function runCli(args) {
+  const res = spawnSync('node', [CLI_BIN, ...args], {encoding: 'utf-8', timeout: 20_000});
+  return {status: res.status, stdout: res.stdout || '', stderr: res.stderr || ''};
+}
+
+describe('manifest: e2e', () => {
+  it('astryx manifest --json emits a valid manifest envelope', () => {
+    const {status, stdout} = runCli(['manifest', '--json']);
+    expect(status).toBe(0);
+    const parsed = JSON.parse(stdout);
+    expect(parsed.apiVersion).toBe(1);
+    expect(parsed.type).toBe('manifest');
+    expect(parsed.data.name).toBe('astryx');
+    const names = parsed.data.commands.map((c) => c.name);
+    expect(names).toContain('component');
+    expect(names).toContain('theme');
+    expect(names).toContain('manifest');
+  });
+
+  it('bare xds --json stays backwards-compatible AND embeds the manifest', () => {
+    const {status, stdout} = runCli(['--json']);
+    expect(status).toBe(0);
+    const parsed = JSON.parse(stdout);
+    // Back-compat: still type:'help' with name/version/commands(names)/jsonSupported
+    expect(parsed.type).toBe('help');
+    expect(parsed.data.name).toBe('astryx');
+    expect(Array.isArray(parsed.data.commands)).toBe(true);
+    expect(parsed.data.commands.every((c) => typeof c === 'string')).toBe(true);
+    expect(parsed.data.commands).toContain('component');
+    expect(Array.isArray(parsed.data.jsonSupported)).toBe(true);
+    // Enriched: the full structured manifest is embedded.
+    expect(parsed.data.manifest).toBeDefined();
+    expect(parsed.data.manifest.commands.find((c) => c.name === 'component').responseTypes)
+      .toContain('component.list');
+  });
+});

package/src/lib/node-version.mjs

@@ -0,0 +1,69 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Node.js version preflight — runtime support gate.
+ *
+ * The CLI (and its dependencies) rely on `styleText` from `node:util`, which
+ * was only added in Node 22.13.0. On older runtimes the lazy-loaded
+ * subcommands die with a cryptic ESM error:
+ *
+ *   failed to load: The requested module 'node:util' does not provide an
+ *   export named 'styleText'
+ *
+ * This module exposes a tiny, dependency-free comparison helper so the entry
+ * point can gate on the running Node version BEFORE importing anything that
+ * touches `styleText`, and surface a clear "upgrade Node" message instead.
+ *
+ * Kept free of any non-builtin imports so it can run on the unsupported
+ * runtimes it is meant to guard against.
+ */
+
+/** Minimum supported Node.js version. */
+export const MIN_NODE_VERSION = '22.13.0';
+
+/**
+ * Parse a Node.js version string ("22.14.1", "v20.10.0", "16.20.2-nightly")
+ * into a {major, minor, patch} record. Missing or non-numeric segments
+ * default to 0.
+ *
+ * @param {string} version
+ * @returns {{major: number, minor: number, patch: number}}
+ */
+export function parseNodeVersion(version) {
+  const cleaned = String(version).trim().replace(/^v/, '');
+  const [major = 0, minor = 0, patch = 0] = cleaned
+    .split('.')
+    .map((seg) => parseInt(seg, 10) || 0);
+  return {major, minor, patch};
+}
+
+/**
+ * Returns true when `version` is greater than or equal to `minimum`.
+ * Compares major, then minor, then patch.
+ *
+ * @param {string} version - the running Node version (e.g. process.versions.node)
+ * @param {string} [minimum] - the minimum supported version
+ * @returns {boolean}
+ */
+export function isNodeVersionSupported(version, minimum = MIN_NODE_VERSION) {
+  const v = parseNodeVersion(version);
+  const min = parseNodeVersion(minimum);
+  if (v.major !== min.major) return v.major > min.major;
+  if (v.minor !== min.minor) return v.minor > min.minor;
+  return v.patch >= min.patch;
+}
+
+/**
+ * Builds the friendly, human-facing message shown when the runtime is too old.
+ *
+ * @param {string} version - the running Node version
+ * @param {string} [minimum] - the minimum supported version
+ * @returns {string}
+ */
+export function unsupportedNodeMessage(version, minimum = MIN_NODE_VERSION) {
+  const clean = String(version).trim().replace(/^v/, '');
+  return (
+    `astryx requires Node.js >=${minimum} (you have v${clean}). ` +
+    `Please upgrade Node and try again.`
+  );
+}

package/src/lib/node-version.test.mjs

@@ -0,0 +1,91 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Unit tests for the Node.js version preflight gate (`node-version.mjs`).
+ *
+ * The CLI requires Node >=22.13.0 because dependencies import `styleText` from
+ * `node:util`, which only exists from that version onward. These tests lock in
+ * the parsing and comparison logic that decides whether the running runtime is
+ * supported, so the entry-point guard reliably rejects old Node and accepts new
+ * Node across the major.minor.patch boundary.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {
+  MIN_NODE_VERSION,
+  parseNodeVersion,
+  isNodeVersionSupported,
+  unsupportedNodeMessage,
+} from './node-version.mjs';
+
+describe('parseNodeVersion', () => {
+  it('parses a plain semver string', () => {
+    expect(parseNodeVersion('22.14.1')).toEqual({major: 22, minor: 14, patch: 1});
+  });
+
+  it('strips a leading v', () => {
+    expect(parseNodeVersion('v20.10.0')).toEqual({major: 20, minor: 10, patch: 0});
+  });
+
+  it('ignores a prerelease/build suffix on the patch segment', () => {
+    expect(parseNodeVersion('16.20.2-nightly')).toEqual({major: 16, minor: 20, patch: 2});
+  });
+
+  it('defaults missing segments to 0', () => {
+    expect(parseNodeVersion('24')).toEqual({major: 24, minor: 0, patch: 0});
+  });
+});
+
+describe('isNodeVersionSupported', () => {
+  it('rejects clearly old majors', () => {
+    expect(isNodeVersionSupported('16.20.2')).toBe(false);
+    expect(isNodeVersionSupported('20.10.0')).toBe(false);
+  });
+
+  it('rejects the same major but an older minor', () => {
+    expect(isNodeVersionSupported('22.12.0')).toBe(false);
+  });
+
+  it('rejects the same major but an older minor regardless of patch', () => {
+    expect(isNodeVersionSupported('22.12.99')).toBe(false);
+  });
+
+  it('accepts exactly the minimum version', () => {
+    expect(isNodeVersionSupported('22.13.0')).toBe(true);
+  });
+
+  it('accepts a newer patch within the minimum minor', () => {
+    expect(isNodeVersionSupported('22.13.1')).toBe(true);
+  });
+
+  it('accepts a newer minor', () => {
+    expect(isNodeVersionSupported('22.14.1')).toBe(true);
+  });
+
+  it('accepts a newer major', () => {
+    expect(isNodeVersionSupported('24.1.0')).toBe(true);
+  });
+
+  it('handles a v-prefixed running version', () => {
+    expect(isNodeVersionSupported('v22.13.0')).toBe(true);
+    expect(isNodeVersionSupported('v18.0.0')).toBe(false);
+  });
+
+  it('uses MIN_NODE_VERSION (22.13.0) as the default threshold', () => {
+    expect(MIN_NODE_VERSION).toBe('22.13.0');
+    expect(isNodeVersionSupported(MIN_NODE_VERSION)).toBe(true);
+  });
+});
+
+describe('unsupportedNodeMessage', () => {
+  it('names both the required minimum and the running version', () => {
+    const msg = unsupportedNodeMessage('16.20.2');
+    expect(msg).toContain('>=22.13.0');
+    expect(msg).toContain('v16.20.2');
+    expect(msg).toContain('upgrade Node');
+  });
+
+  it('normalizes a v-prefixed running version to a single v', () => {
+    expect(unsupportedNodeMessage('v20.10.0')).toContain('v20.10.0');
+  });
+});

package/src/lib/package-scanner.mjs

@@ -0,0 +1,94 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Package scanner for config-based discovery
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export function scanDirectory(scanDir) {
+  if (!fs.existsSync(scanDir)) return [];
+  const entries = fs.readdirSync(scanDir, {withFileTypes: true});
+  const packages = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const pkgPath = path.join(scanDir, entry.name, 'package.json');
+    if (!fs.existsSync(pkgPath)) continue;
+    let pkg;
+    try { pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')); } catch { continue; }
+    if (!pkg.astryx || !pkg.astryx.docs) continue;
+    const pkgDir = path.join(scanDir, entry.name);
+    const docsDir = path.resolve(pkgDir, pkg.astryx.docs);
+    const components = discoverDocComponents(docsDir);
+    if (components.length === 0) continue;
+    packages.push({
+      name: pkg.name || entry.name,
+      version: pkg.version,
+      description: pkg.description,
+      displayName: pkg.displayName,
+      dir: pkgDir,
+      astryx: pkg.astryx,
+      category: pkg.astryx.category || pkg.name || entry.name,
+      docsDir,
+      components,
+    });
+  }
+  return packages;
+}
+
+export function scanAllPackages(packageDirs) {
+  const all = [];
+  const seen = new Set();
+  for (const dir of packageDirs) {
+    for (const pkg of scanDirectory(dir)) {
+      if (seen.has(pkg.name)) continue;
+      seen.add(pkg.name);
+      all.push(pkg);
+    }
+  }
+  return all;
+}
+
+function discoverDocComponents(docsDir) {
+  if (!fs.existsSync(docsDir)) return [];
+  const components = [];
+  function walk(dir) {
+    let entries;
+    try { entries = fs.readdirSync(dir, {withFileTypes: true}); } catch { return; }
+    for (const entry of entries) {
+      if (entry.name === 'node_modules' || entry.name === '__tests__') continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.name.endsWith('.doc.mjs')) components.push(entry.name.replace('.doc.mjs', ''));
+    }
+  }
+  walk(docsDir);
+  return components.sort();
+}
+
+export function findComponentInPackages(packages, name) {
+  const lower = name.toLowerCase();
+  for (const pkg of packages) {
+    const match = pkg.components.find(c => c.toLowerCase() === lower);
+    if (!match) continue;
+    const docPath = findDocFile(pkg.docsDir, match);
+    if (docPath) return {pkg, docPath, componentName: match};
+  }
+  return null;
+}
+
+function findDocFile(docsDir, name) {
+  const target = name + '.doc.mjs';
+  function walk(dir) {
+    let entries;
+    try { entries = fs.readdirSync(dir, {withFileTypes: true}); } catch { return null; }
+    for (const entry of entries) {
+      if (entry.name === 'node_modules' || entry.name === '__tests__') continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) { const f = walk(full); if (f) return f; }
+      else if (entry.name === target) return full;
+    }
+    return null;
+  }
+  return walk(docsDir);
+}