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

package/src/commands/hook/index.mjs

@@ -0,0 +1,163 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file hook command — List hooks and print hook docs
+ *
+ * Global options: --detail full|compact|brief, --lang en|zh
+ */
+
+import {
+  formatHookFull,
+  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';
+
+export function registerHook(program) {
+  program
+    .command('hook [name]')
+    .description('List hooks or print hook docs')
+    .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();
+      const zh = program.opts().zh || 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-hook view, brief for list views.
+      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 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});
+        return;
+      }
+
+      if (json) return jsonOut(result.type, result.data);
+
+      // ── Text output ────────────────────────────────────────────
+      switch (result.type) {
+        case 'hook.list': {
+          // --detail brief (default for list views) — names only.
+          if (options.category) {
+            const [cat, hookNames] = Object.entries(result.data)[0];
+            humanLog(`\n${cat}:`);
+            for (const h of hookNames) humanLog(`  ${h}`);
+            humanLog('');
+          } else {
+            humanLog('');
+            for (const [category, hookNames] of Object.entries(result.data)) {
+              humanLog(category);
+              for (const h of hookNames) humanLog(`  ${h}`);
+            }
+            humanLog('');
+            humanLog(`Usage: ${run} astryx hook <name>`);
+            humanLog('');
+          }
+          break;
+        }
+
+        case 'hook.brief': {
+          // --detail compact — name + 1-line description per entry.
+          humanLog('');
+          for (const [cat, items] of Object.entries(result.data)) {
+            humanLog(cat);
+            for (const item of items) {
+              const desc = item.description ? ` — ${item.description}` : '';
+              humanLog(`  ${item.name}${desc}`);
+            }
+            humanLog('');
+          }
+          humanLog(`Usage: ${run} astryx hook <name>`);
+          humanLog('');
+          break;
+        }
+
+        case 'hook.full': {
+          // --detail full — dense per-hook docs grouped by category
+          // (import block, best practices, full params + returns tables, related).
+          humanLog('');
+          for (const [cat, items] of Object.entries(result.data)) {
+            humanLog(`## ${cat}\n`);
+            for (const item of items) {
+              const importPath = item.importPath || '@astryxdesign/core/hooks';
+              humanLog(formatHookCompact(item, importPath));
+            }
+          }
+          break;
+        }
+
+        case 'hook.detail': {
+          if (detail === 'brief') {
+            humanLog(formatHookBrief(result.data));
+          } else if (detail === 'compact') {
+            const importPath = result.data.importPath || '@astryxdesign/core/hooks';
+            humanLog(formatHookCompact(result.data, importPath));
+          } else {
+            humanLog(formatHookFull(result.data));
+          }
+          // Show related block templates from relatedComponents
+          const relatedComps = result.data.relatedComponents || [];
+          const allBlocks = [];
+          for (const comp of relatedComps) {
+            const blocks = await findRelatedBlocks(comp);
+            for (const b of blocks) {
+              if (!allBlocks.some(existing => existing.dirName === b.dirName)) {
+                allBlocks.push(b);
+              }
+            }
+          }
+          if (allBlocks.length > 0) {
+            humanLog('\nRelated block templates:\n');
+            for (const b of allBlocks) {
+              humanLog(`  ${b.dirName}`);
+              if (b.description) humanLog(`    ${b.description}`);
+            }
+            humanLog('');
+          }
+          break;
+        }
+
+        case 'hook.detail.params': {
+          humanLog(formatHookParams({params: result.data, name: name}));
+          break;
+        }
+      }
+    });
+}
+
+// Re-export lib functions for external consumers
+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';

package/src/commands/import-hint-correctness.test.mjs

@@ -0,0 +1,182 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Validates that every CLI-discoverable component produces a correct
+ * import hint that matches an actual package.json export subpath.
+ *
+ * This guards against:
+ * - Import paths pointing to non-existent exports
+ * - Case mismatches (Theme vs theme)
+ * - Group names leaking as import paths
+ * - resolveImportPath regressions
+ *
+ * Runs against the real packages/core source, not mocks.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {execFileSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {
+  resolveImportPath,
+  discoverComponents,
+  findComponentSource,
+} from './component/index.mjs';
+import {findCoreDir} from '../utils/paths.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');
+const REPO_ROOT = path.resolve(__dirname, '../../../..');
+
+function runCli(args) {
+  try {
+    const out = execFileSync('node', [CLI_BIN, ...args], {
+      cwd: REPO_ROOT,
+      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() ?? '',
+    };
+  }
+}
+
+describe('import hint correctness', () => {
+  const coreDir = findCoreDir();
+  const pkg = JSON.parse(
+    fs.readFileSync(path.join(coreDir, 'package.json'), 'utf-8'),
+  );
+  const validExports = new Set(
+    Object.keys(pkg.exports || {})
+      .filter(k => k !== '.' && k !== './package.json')
+      .map(k => k.replace('./', '')),
+  );
+
+  const componentMap = discoverComponents(coreDir);
+  const groupNames = Object.keys(componentMap);
+
+  // Collect all individual component names (non-group)
+  const individualComponents = [];
+  for (const [group, members] of Object.entries(componentMap)) {
+    for (const member of members) {
+      individualComponents.push(member);
+    }
+  }
+
+  describe('every component resolves to a tree-shakeable subpath (not bare @astryxdesign/core)', () => {
+    for (const name of individualComponents) {
+      it(`${name} resolves to @astryxdesign/core/<subpath>, not bare @astryxdesign/core`, () => {
+        const importPath = resolveImportPath(coreDir, name);
+
+        // Must never be empty
+        expect(importPath).toBeTruthy();
+
+        // Must resolve to a specific subpath — bare @astryxdesign/core is not tree-shakeable
+        expect(importPath).not.toBe('@astryxdesign/core');
+
+        // The subpath must exist in package.json exports
+        const subpath = importPath.replace('@astryxdesign/core/', '');
+        expect(validExports.has(subpath)).toBe(true);
+      });
+    }
+  });
+
+  describe('import hint case matches package.json exports exactly', () => {
+    for (const name of individualComponents) {
+      it(`${name} import path has correct casing`, () => {
+        const importPath = resolveImportPath(coreDir, name);
+        if (importPath === '@astryxdesign/core') return; // skip bare fallback
+
+        const subpath = importPath.replace('@astryxdesign/core/', '');
+
+        // Must be an exact (case-sensitive) match to an export key
+        const exportKeys = Object.keys(pkg.exports || {}).map(k =>
+          k.replace('./', ''),
+        );
+        expect(exportKeys).toContain(subpath);
+      });
+    }
+  });
+
+  describe('CLI --detail brief shows correct import path', () => {
+    // Test a representative set across different patterns
+    const representative = [
+      {name: 'Button', expected: '@astryxdesign/core/Button'},
+      {name: 'Theme', expected: '@astryxdesign/core/theme'},
+      {name: 'CheckboxInput', expected: '@astryxdesign/core/CheckboxInput'},
+      {name: 'Table', expected: '@astryxdesign/core/Table'},
+      {name: 'TextInput', expected: '@astryxdesign/core/TextInput'},
+      {name: 'Layout', expected: '@astryxdesign/core/Layout'},
+      {name: 'AppShell', expected: '@astryxdesign/core/AppShell'},
+      {name: 'Card', expected: '@astryxdesign/core/Card'},
+      {name: 'Dialog', expected: '@astryxdesign/core/Dialog'},
+      {name: 'TabList', expected: '@astryxdesign/core/TabList'},
+    ];
+
+    for (const {name, expected} of representative) {
+      it(`npx astryx component ${name} --detail brief shows ${expected}`, () => {
+        const result = runCli(['component', name, '--detail', 'brief']);
+        expect(result.code).toBe(0);
+        expect(result.stdout).toContain(expected);
+      });
+    }
+  });
+
+  describe('CLI --detail full shows import hint', () => {
+    const representative = ['Button', 'Theme', 'Table', 'CheckboxInput'];
+
+    for (const name of representative) {
+      it(`npx astryx component ${name} (full) includes import statement`, () => {
+        const result = runCli(['component', name]);
+        expect(result.code).toBe(0);
+        // The PR adds: **Import:** `import {XDS...} from '...';`
+        expect(result.stdout).toMatch(/import\s*\{/);
+        expect(result.stdout).toContain('@astryxdesign/core');
+      });
+    }
+  });
+
+  describe('group names do NOT resolve to incorrect import paths', () => {
+    const groups = ['Checkbox', 'Radio', 'Chat', 'Tabs', 'Resizable', 'Utilities'];
+
+    for (const group of groups) {
+      it(`group "${group}" does not produce a subpath import`, () => {
+        // Groups should either fail to find a source file (returning bare @astryxdesign/core)
+        // or correctly return the group-level export if one exists
+        const importPath = resolveImportPath(coreDir, group);
+        if (importPath !== '@astryxdesign/core') {
+          // If it does resolve, it must be a valid export
+          const subpath = importPath.replace('@astryxdesign/core/', '');
+          expect(validExports.has(subpath)).toBe(true);
+        }
+      });
+    }
+  });
+
+  describe('import path matches actual source file location', () => {
+    for (const name of individualComponents) {
+      it(`${name} import path leads to its source directory`, () => {
+        const source = findComponentSource(coreDir, name);
+        if (!source) return; // some sub-components don't have direct source
+
+        const importPath = resolveImportPath(coreDir, name);
+        if (importPath === '@astryxdesign/core') return;
+
+        const subpath = importPath.replace('@astryxdesign/core/', '');
+        const srcDir = path.join(coreDir, 'src');
+        const relToSrc = path.relative(srcDir, source);
+        const topDir = relToSrc.split(path.sep)[0];
+
+        // The import subpath should match the top-level src directory
+        // (case-insensitive check since theme/Theme is valid)
+        expect(subpath.toLowerCase()).toBe(topDir.toLowerCase());
+      });
+    }
+  });
+});

package/src/commands/init.mjs

@@ -0,0 +1,254 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file init command — Interactive initialization wizard + feature installer
+ *
+ * Interactive: `astryx init` walks through all features
+ * Non-interactive: `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    — Scaffold a custom theme file
+ *   template — Copy a starter page template
+ */
+
+import * as p from '@clack/prompts';
+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 {getRunPrefix} from '../utils/package-manager.mjs';
+import {installAgentDocs, removeAgentDocs} from './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';
+import {requireInteractive} from '../utils/interactive.mjs';
+
+const VALID_FEATURES = ['agents', 'theme', 'template'];
+const run = getRunPrefix();
+
+function isCancel(value) {
+  if (p.isCancel(value)) {
+    p.cancel('Setup cancelled.');
+    process.exit(0);
+  }
+  return value;
+}
+
+// ─── Feature: agents ─────────────────────────────────────────────────────────
+
+function runAgents(targetDir, {interactive = true, agent, agentDocsPath} = {}) {
+  try {
+    const paths = agentDocsPath
+      ? Array.isArray(agentDocsPath)
+        ? agentDocsPath
+        : [agentDocsPath]
+      : undefined;
+    const written = installAgentDocs(targetDir, {agent, paths});
+    const summary = written.join(', ');
+    if (interactive) {
+      p.log.success(`AI agent docs installed → ${summary}`);
+    } else {
+      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) {
+      const msg = `Error: ${err.message}`;
+      if (interactive) {
+        p.log.error(msg);
+      } else {
+        console.error(msg);
+      }
+      process.exitCode = 1;
+      return;
+    }
+    const msg = `Could not install agent docs. Try again with \`${run} astryx init --features agents\`.`;
+    if (interactive) {
+      p.log.warning(msg);
+    } else {
+      console.error(msg);
+    }
+  }
+}
+
+// ─── Feature: theme ──────────────────────────────────────────────────────────
+
+async function runTheme({interactive = true} = {}) {
+  if (!interactive) {
+    humanLog(`✓ Theme scaffolding requires interactive mode. Run \`${run} astryx theme\` instead.`);
+    return;
+  }
+
+  p.note(
+    'Create a custom theme with your brand colors.\n' +
+    `Run \`${run} astryx theme\` for the full theme wizard.\n` +
+    `Run \`${run} astryx theme --list\` to see existing themes.`,
+    'Themes',
+  );
+}
+
+// ─── Feature: template ───────────────────────────────────────────────────────
+
+async function runTemplate(targetDir, {interactive = true, templateName} = {}) {
+  const templates = listTemplates();
+  if (templates.length === 0) return;
+
+  if (!interactive) {
+    if (!templateName) {
+      humanLog(`✓ Available templates: ${templates.join(', ')}. Use ${run} astryx template <name> [path].`);
+      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`);
+    return;
+  }
+
+  const TEMPLATE_OPTIONS = [
+    {value: 'skip', label: 'Skip — No template'},
+    {value: 'blank', label: 'Blank Page — Minimal scaffold'},
+    {value: 'table', label: 'Table Page — Data table with actions'},
+    {value: 'login', label: 'Login Page — Auth form with inputs'},
+  ];
+
+  const templateChoice = isCancel(
+    await p.select({
+      message: 'Start with a page template?',
+      options: TEMPLATE_OPTIONS,
+    }),
+  );
+
+  if (templateChoice === 'skip') return;
+
+  const targetPath = isCancel(
+    await p.text({
+      message: 'Where should the template be created?',
+      initialValue: `./src/pages/${templateChoice}`,
+      placeholder: `./src/pages/${templateChoice}`,
+    }),
+  );
+
+  const outputDir = path.resolve(targetDir, targetPath);
+  const srcPath = path.join(CLI_ROOT, 'templates', 'pages', templateChoice, 'page.tsx');
+
+  fs.mkdirSync(outputDir, {recursive: true});
+  fs.copyFileSync(srcPath, path.join(outputDir, 'page.tsx'));
+
+  p.log.success(`Template created at ${path.relative(targetDir, outputDir)}/page.tsx`);
+}
+
+// ─── Command ─────────────────────────────────────────────────────────────────
+
+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, all')
+    .option('--agent-docs-path <path...>', 'Explicit file path(s) for agent docs')
+    .action(async (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
+          : 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, {
+            interactive: false,
+            agent: options.agent,
+            agentDocsPath: options.agentDocsPath,
+          });
+          if (feature === 'theme') await runTheme({interactive: false});
+          if (feature === 'template') await runTemplate(targetDir, {interactive: false});
+        }
+        return;
+      }
+
+      // Interactive wizard
+      //
+      // Guard: this wizard blocks on prompts. In a non-interactive context
+      // (CI, piped stdin/stdout, no TTY) it would hang forever. Fail fast
+      // with actionable guidance via the shared interactivity contract.
+      requireInteractive({
+        command: 'init',
+        hint: `\`${run} astryx init --all\` or \`--features agents,theme,template\``,
+      });
+
+      p.intro('Welcome to the design system');
+
+      p.note(
+        'A design system for building internal tools\nwith 300+ React components.',
+        'About',
+      );
+
+      // Feature: agents
+      const shouldInstallAgents = isCancel(
+        await p.confirm({
+          message: 'Install AI agent support? (adds a design system cheat sheet to AGENTS.md)',
+          initialValue: true,
+        }),
+      );
+
+      if (shouldInstallAgents) {
+        const s = p.spinner();
+        s.start('Installing agent docs');
+        runAgents(targetDir);
+        s.stop('Done');
+      }
+
+      // Feature: swizzle awareness
+      p.note(
+        `You can customize any component with:\n  ${run} astryx swizzle Button\n  ${run} astryx swizzle --list`,
+        'Component Customization',
+      );
+
+      // Feature: template
+      await runTemplate(targetDir);
+
+      // Feature: theme awareness
+      await runTheme();
+
+      // Outro
+      p.outro('Design system initialized!');
+
+      humanLog('');
+      humanLog('  Next steps:');
+      humanLog("    1. Import components: import { Button } from '@astryxdesign/core'");
+      humanLog('    2. Optionally add a theme:');
+      humanLog("       import { neutralTheme } from '@astryxdesign/theme-neutral'");
+      humanLog('       <Theme theme={neutralTheme}>...</Theme>');
+      humanLog(`    3. ${run} astryx --help for all commands`);
+      humanLog('');
+    });
+}

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

@@ -0,0 +1,69 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Subprocess no-hang tests for the interactivity contract.
+ *
+ * The wizard command `init` blocks on @clack/prompts. In a
+ * non-interactive context it must fail fast (exit 1) instead of hanging.
+ * These tests spawn the CLI as a real subprocess with stdin/stdout NOT a TTY
+ * (stdio 'ignore'/'pipe'), which is exactly the CI / piped condition. If the
+ * guard were missing, spawnSync would hit the timeout (signal SIGTERM,
+ * status null) — so asserting `signal === null && status === 1` proves the
+ * process exited cleanly rather than hanging.
+ */
+
+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(), 'xds-interactive-guard-'));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('init non-interactive safety', () => {
+  it('fails fast (exit 1, no hang) and writes no files', () => {
+    const r = runCli(['init']);
+    expect(r.signal).toBeNull();
+    expect(r.status).toBe(1);
+    expect(fs.readdirSync(tmpDir)).toEqual([]);
+  });
+
+  it('prints actionable guidance (--all / --features)', () => {
+    const out = (() => {
+      const r = runCli(['init']);
+      return r.stderr + r.stdout;
+    })();
+    expect(out).toMatch(/requires a TTY/i);
+    expect(out).toMatch(/--all/);
+    expect(out).toMatch(/--features/);
+  });
+
+  it('still runs --features agents non-interactively (guard does not over-catch)', () => {
+    const r = runCli(['init', '--features', 'agents']);
+    expect(r.signal).toBeNull();
+    expect(r.status).toBe(0);
+    expect(fs.readdirSync(tmpDir).length).toBeGreaterThan(0);
+  });
+});