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

package/src/commands/detail-levels.test.mjs

@@ -0,0 +1,133 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Integration tests for the --detail level contract on list views.
+ *
+ * Spawns the CLI as a subprocess against the real monorepo core dir and
+ * asserts the documented size ordering for both `component --list` and
+ * `hook --list`:
+ *
+ *   brief  (names only)              <  smallest
+ *   compact (name + 1-line desc)     <  middle
+ *   full   (dense per-entry docs)       largest
+ *
+ * All three levels must produce DISTINCT output. This guards against the
+ * historically-inverted behavior where `brief` was densest and `full`
+ * duplicated `compact`.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {spawnSync} from 'node:child_process';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');
+// Repo root holds packages/core, which findCoreDir() walks up to locate.
+const REPO_ROOT = path.resolve(__dirname, '../../../..');
+
+function runCli(args) {
+  const res = spawnSync('node', [CLI_BIN, ...args], {
+    cwd: REPO_ROOT,
+    encoding: 'utf-8',
+    timeout: 60_000,
+    // component.full JSON can exceed the default 1MB stdout buffer.
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  return {
+    status: res.status,
+    stdout: res.stdout || '',
+    stderr: res.stderr || '',
+  };
+}
+
+function listOutputs(cmd) {
+  const brief = runCli([cmd, '--list', '--detail', 'brief']).stdout;
+  const compact = runCli([cmd, '--list', '--detail', 'compact']).stdout;
+  const full = runCli([cmd, '--list', '--detail', 'full']).stdout;
+  return {brief, compact, full};
+}
+
+describe('--detail level ordering: component --list', () => {
+  const {brief, compact, full} = listOutputs('component');
+
+  it('produces strictly increasing output size: brief < compact < full', () => {
+    expect(brief.length).toBeGreaterThan(0);
+    expect(compact.length).toBeGreaterThan(brief.length);
+    expect(full.length).toBeGreaterThan(compact.length);
+  });
+
+  it('produces three distinct outputs', () => {
+    expect(brief).not.toEqual(compact);
+    expect(compact).not.toEqual(full);
+    expect(brief).not.toEqual(full);
+  });
+
+  it('brief is names-only (no targets, import hints, or prose descriptions)', () => {
+    expect(brief).not.toMatch(/Targets:/);
+    expect(brief).not.toMatch(/\u2190 from/);
+    // Names only — should contain XDS component names but no " — " desc separator.
+    expect(brief).toMatch(/Button/);
+    expect(brief).not.toMatch(/ \u2014 /);
+  });
+
+  it('compact has 1-line descriptions (name + em-dash separator)', () => {
+    expect(compact).toMatch(/ \u2014 /);
+  });
+
+  it('full has dense per-entry docs (props, targets, and import hints)', () => {
+    expect(full).toMatch(/Targets:/);
+    expect(full).toMatch(/\u2190 from/);
+    // Prop name lists appear in the dense brief-all rendering.
+    expect(full).toMatch(/children/);
+  });
+
+  it('full --json returns a valid component.full envelope', () => {
+    const {stdout} = runCli(['component', '--list', '--detail', 'full', '--json']);
+    const parsed = JSON.parse(stdout);
+    expect(parsed.type).toBe('component.full');
+    expect(parsed.apiVersion).toBe(1);
+    expect(typeof parsed.data).toBe('object');
+  });
+});
+
+describe('--detail level ordering: hook --list', () => {
+  const {brief, compact, full} = listOutputs('hook');
+
+  it('produces strictly increasing output size: brief < compact < full', () => {
+    expect(brief.length).toBeGreaterThan(0);
+    expect(compact.length).toBeGreaterThan(brief.length);
+    expect(full.length).toBeGreaterThan(compact.length);
+  });
+
+  it('produces three distinct outputs', () => {
+    expect(brief).not.toEqual(compact);
+    expect(compact).not.toEqual(full);
+    expect(brief).not.toEqual(full);
+  });
+
+  it('brief is names-only (no param tables or import blocks)', () => {
+    expect(brief).not.toMatch(/\| Param \|/);
+    expect(brief).not.toMatch(/## Parameters/);
+    expect(brief).not.toMatch(/import \{/);
+    expect(brief).toMatch(/use[A-Z]/);
+    expect(brief).not.toMatch(/ \u2014 /);
+  });
+
+  it('compact has 1-line descriptions (name + em-dash separator)', () => {
+    expect(compact).toMatch(/ \u2014 /);
+  });
+
+  it('full has dense docs (param tables and import statements)', () => {
+    expect(full).toMatch(/\| Param \|/);
+    expect(full).toMatch(/import \{/);
+  });
+
+  it('full --json returns a valid hook.full envelope', () => {
+    const {stdout} = runCli(['hook', '--list', '--detail', 'full', '--json']);
+    const parsed = JSON.parse(stdout);
+    expect(parsed.type).toBe('hook.full');
+    expect(parsed.apiVersion).toBe(1);
+    expect(typeof parsed.data).toBe('object');
+  });
+});

package/src/commands/discover.mjs

@@ -0,0 +1,143 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file discover command — find external Astryx packages and components
+ *
+ * Usage:
+ *   astryx discover                           List all packages
+ *   astryx discover @scope/name               List components in a package
+ *   astryx discover @scope/name/Component     Show docs for a component
+ *   astryx discover searchterm                Search across all packages
+ */
+
+import {loadConfig} from '../lib/config.mjs';
+import {formatFull, formatBrief, formatCompact} from '../lib/component-format.mjs';
+import {jsonOut, humanLog} from '../lib/json.mjs';
+import {cliError} from '../lib/cli-error.mjs';
+import {discover as discoverApi} from '../api/discover.mjs';
+
+export function registerDiscover(program) {
+  program
+    .command('discover [query]')
+    .description('Discover external packages and components')
+    .option('--components', 'List components only')
+    .action(async (query, options) => {
+      const detail = program.opts().detail || 'full';
+      const json = program.opts().json || false;
+      const lang = program.opts().lang || null;
+      const zh = program.opts().zh || false;
+
+      let result;
+      try {
+        result = await discoverApi(query, {components: options.components, lang, zh});
+      } catch (e) {
+        cliError(e.message, {suggestions: e.suggestions, code: e.code});
+        return;
+      }
+
+      if (json) {
+        // Forward optional meta (e.g. configured flag for discover.list) as a
+        // sibling of data via jsonOut, so the envelope still carries
+        // apiVersion and goes through the single sanctioned emit path.
+        return jsonOut(result.type, result.data, result.meta);
+      }
+
+      switch (result.type) {
+        case 'discover.list': {
+          if (result.data.length === 0) {
+            const config = await loadConfig();
+            humanLog('');
+            if (config.packages.length === 0) {
+              humanLog('No package directories configured.');
+              humanLog('');
+              humanLog('Add a packages field to astryx.config.mjs:');
+              humanLog('');
+              humanLog('  export default {');
+              humanLog("    packages: ['/path/to/your/libs'],");
+              humanLog('  };');
+            } else {
+              humanLog('No external packages found.');
+              humanLog('');
+              humanLog('Packages opt in by adding an "astryx" field to package.json:');
+              humanLog('');
+              humanLog('  {');
+              humanLog('    "astryx": {');
+              humanLog('      "docs": "./src",');
+              humanLog('      "category": "Common"');
+              humanLog('    }');
+              humanLog('  }');
+            }
+            humanLog('');
+          } else {
+            humanLog('');
+            for (const pkg of result.data) {
+              const count = pkg.components.length;
+              const label = count === 1 ? 'component' : 'components';
+              const heading = pkg.displayName
+                ? pkg.displayName + '  ' + pkg.name + ' (' + count + ' ' + label + ')'
+                : pkg.name + ' (' + count + ' ' + label + ')';
+              humanLog(heading);
+              if (pkg.description) humanLog('  ' + pkg.description);
+
+              if (options.components) {
+                for (const comp of pkg.components) humanLog('  ' + comp);
+              } else {
+                const maxShow = 10;
+                const shown = pkg.components.slice(0, maxShow);
+                const remaining = count - maxShow;
+                const list = shown.join(', ');
+                humanLog(remaining > 0 ? '  ' + list + ', +' + remaining + ' more' : '  ' + list);
+              }
+              humanLog('');
+            }
+            humanLog('Usage:');
+            humanLog('  astryx discover <package>            Browse a package');
+            humanLog('  astryx discover <package>/Component  View component docs');
+            humanLog('  astryx discover <search>             Search all packages');
+            humanLog('');
+          }
+          break;
+        }
+
+        case 'discover.detail': {
+          humanLog('');
+          const d = result.data;
+          const detailHeading = d.displayName
+            ? d.displayName + '  ' + d.name + ' (' + d.components.length + ' components)'
+            : d.name + ' (' + d.components.length + ' components)';
+          humanLog(detailHeading);
+          if (d.description) humanLog('  ' + d.description);
+          humanLog('');
+          for (const comp of result.data.components) humanLog('  ' + comp);
+          humanLog('');
+          humanLog('Usage: astryx discover ' + result.data.name + '/<ComponentName>');
+          humanLog('');
+          break;
+        }
+
+        case 'discover.detail.doc': {
+          const docs = result.data;
+          if (detail === 'brief') {
+            humanLog(formatBrief(docs, docs.name, ''));
+          } else if (detail === 'compact') {
+            humanLog(formatCompact(docs, docs.name, ''));
+          } else {
+            humanLog(formatFull(docs));
+          }
+          humanLog('');
+          break;
+        }
+
+        case 'discover.search': {
+          humanLog('');
+          humanLog('Found ' + result.data.matches.length + ' matches for "' + result.data.query + '":');
+          humanLog('');
+          for (const m of result.data.matches) {
+            humanLog('  astryx discover ' + m.package + '/' + m.component);
+          }
+          humanLog('');
+          break;
+        }
+      }
+    });
+}

package/src/commands/docs.mjs

@@ -0,0 +1,149 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file docs command — Print Astryx reference docs
+ *
+ * Auto-discovers .doc.mjs files from the docs/ directory.
+ * Supports --detail (full|compact|brief) and --lang (en|zh|dense).
+ *
+ * Usage:
+ *   astryx docs                          List available topics
+ *   astryx docs <topic>                  Print full doc
+ *   astryx docs <topic> <section>        Print one section
+ */
+
+import {getRunPrefix} from '../utils/package-manager.mjs';
+import {jsonOut, humanLog} from '../lib/json.mjs';
+import {cliError} from '../lib/cli-error.mjs';
+import {docs as docsApi} from '../api/docs.mjs';
+
+// ─── Formatting ──────────────────────────────────────────────────────────────
+
+function formatTable(headers, rows) {
+  const widths = headers.map((h, i) =>
+    Math.max(h.length, ...rows.map(r => (r[i] || '').length)),
+  );
+  const sep = widths.map(w => '-'.repeat(w)).join(' | ');
+  const head = headers.map((h, i) => h.padEnd(widths[i])).join(' | ');
+  const body = rows
+    .map(r => r.map((c, i) => (c || '').padEnd(widths[i])).join(' | '))
+    .join('\n');
+  return `${head}\n${sep}\n${body}`;
+}
+
+function formatTableCompact(headers, rows) {
+  return rows.map(r => r.join(' = ')).join('\n');
+}
+
+function formatBlock(block, detail) {
+  switch (block.type) {
+    case 'prose':
+      return block.text;
+
+    case 'code':
+      if (detail === 'compact' || detail === 'brief') return null;
+      {
+        const label = block.label ? `// ${block.label}\n` : '';
+        return `\`\`\`${block.lang}\n${label}${block.code}\n\`\`\``;
+      }
+
+    case 'table':
+      if (detail === 'brief') {
+        return block.rows.map(r => r.slice(0, 2).join('=')).join(' | ');
+      }
+      if (detail === 'compact') {
+        return formatTableCompact(block.headers, block.rows);
+      }
+      return formatTable(block.headers, block.rows);
+
+    case 'list': {
+      const prefix = block.style === 'ordered' ? (i) => `${i + 1}. `
+        : block.style === 'dont' ? () => '❌ '
+        : block.style === 'do' ? () => '✓ '
+        : () => '- ';
+      return block.items.map((item, i) => `${prefix(i)}${item}`).join('\n');
+    }
+
+    default:
+      return null;
+  }
+}
+
+function formatSection(section, detail) {
+  const blocks = section.content
+    .map(b => formatBlock(b, detail))
+    .filter(Boolean);
+
+  if (detail === 'brief') {
+    const first = blocks[0] || '';
+    return `${section.title}: ${first.split('\n')[0]}`;
+  }
+
+  const heading = detail === 'compact' ? `[${section.title}]` : `## ${section.title}`;
+  return `${heading}\n\n${blocks.join('\n\n')}`;
+}
+
+function formatReferenceFull(docs, detail) {
+  if (detail === 'brief') {
+    const header = `${docs.title}: ${docs.description}`;
+    const sections = docs.sections.map(s => formatSection(s, detail));
+    return `${header}\n${sections.join('\n')}`;
+  }
+
+  const header = detail === 'compact'
+    ? `# ${docs.title}\n${docs.description}`
+    : `# ${docs.title}\n\n${docs.description}`;
+  const sections = docs.sections.map(s => formatSection(s, detail));
+  const sep = detail === 'compact' ? '\n\n' : '\n\n';
+  return `${header}\n\n${sections.join(sep)}`;
+}
+
+// ─── Command ─────────────────────────────────────────────────────────────────
+
+export function registerDocs(program) {
+  program
+    .command('docs [topic] [section]')
+    .description('Print reference docs')
+    .action(async (topic, section) => {
+      const run = getRunPrefix();
+      const lang = program.opts().lang || null;
+      const zh = program.opts().zh || false;
+      const dense = program.opts().dense || false;
+      const detail = program.opts().detail || 'full';
+      const json = program.opts().json || false;
+
+      let result;
+      try {
+        result = await docsApi(topic, section, {lang, zh, dense});
+      } catch (e) {
+        // docs API throws structured errors with {name, reason} suggestions —
+        // pass them through untouched so the CLI envelope matches the API.
+        cliError(e.message, {suggestions: e.suggestions || [], code: e.code});
+        return;
+      }
+
+      if (json) return jsonOut(result.type, result.data);
+
+      switch (result.type) {
+        case 'docs.list': {
+          humanLog('\nAvailable docs:\n');
+          for (const entry of result.data) {
+            humanLog(`  ${entry.topic.padEnd(14)} ${entry.description}`);
+          }
+          humanLog(`\nUsage: ${run} astryx docs <topic>`);
+          humanLog(`       ${run} astryx docs <topic> <section>\n`);
+          break;
+        }
+
+        case 'docs.detail': {
+          humanLog(formatReferenceFull(result.data, detail));
+          break;
+        }
+
+        case 'docs.detail.section': {
+          humanLog(formatSection(result.data, detail));
+          break;
+        }
+      }
+    });
+}

package/src/commands/docs.test.mjs

@@ -0,0 +1,101 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {Command} from 'commander';
+import {registerDocs} from './docs.mjs';
+
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-docs-test-'));
+  vi.spyOn(console, 'log').mockImplementation(() => {});
+  vi.spyOn(console, 'error').mockImplementation(() => {});
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+  vi.restoreAllMocks();
+});
+
+function createProgram() {
+  const program = new Command();
+  program.exitOverride(); // Throw instead of calling process.exit
+  registerDocs(program);
+  return program;
+}
+
+describe('registerDocs', () => {
+  it('lists available topics when no topic given', async () => {
+    const program = createProgram();
+    await program.parseAsync(['node', 'astryx', 'docs']);
+
+    const output = console.log.mock.calls.map(c => c[0]).join('\n');
+    expect(output).toContain('principles');
+    expect(output).toContain('tokens');
+  });
+
+  it('errors for unknown topic', async () => {
+    const program = createProgram();
+    vi.spyOn(process, 'exit').mockImplementation(code => {
+      throw new Error(`exit ${code}`);
+    });
+
+    await expect(
+      program.parseAsync(['node', 'astryx', 'docs', 'nonexistent']),
+    ).rejects.toThrow('exit 1');
+
+    const errorOutput = console.error.mock.calls.map(c => c[0]).join('\n');
+    expect(errorOutput).toContain('Unknown topic');
+  });
+});
+
+describe('hyphenated doc filenames', () => {
+  it('lists hyphenated topics like getting-started', async () => {
+    const program = createProgram();
+    await program.parseAsync(['node', 'astryx', 'docs']);
+
+    const output = console.log.mock.calls.map(c => c[0]).join('\n');
+    expect(output).toContain('getting-started');
+  });
+
+  it('loads a hyphenated topic by name', async () => {
+    const program = createProgram();
+    await program.parseAsync(['node', 'astryx', 'docs', 'getting-started']);
+
+    const output = console.log.mock.calls.map(c => c[0]).join('\n');
+    expect(output.length).toBeGreaterThan(0);
+    expect(console.error).not.toHaveBeenCalled();
+  });
+
+  it('returns docs.detail via API for hyphenated topic', async () => {
+    const {docs: docsApi} = await import('../api/docs.mjs');
+    const result = await docsApi('getting-started');
+    expect(result.type).toBe('docs.detail');
+    expect(result.data).toBeDefined();
+    expect(result.data.description).toBeDefined();
+  });
+});
+
+describe('migration docs', () => {
+  it('lists the migration topic', async () => {
+    const program = createProgram();
+    await program.parseAsync(['node', 'astryx', 'docs']);
+
+    const output = console.log.mock.calls.map(c => c[0]).join('\n');
+    expect(output).toContain('migration');
+    expect(output).toContain('Tailwind');
+  });
+
+  it('loads migration docs by topic name', async () => {
+    const program = createProgram();
+    await program.parseAsync(['node', 'astryx', 'docs', 'migration']);
+
+    const output = console.log.mock.calls.map(c => c[0]).join('\n');
+    expect(output).toContain('Migration Guide');
+    expect(output).toContain('Recommended Order');
+    expect(output).toContain('Map shadcn and Radix Primitives');
+  });
+});

package/src/commands/doctor.mjs

@@ -0,0 +1,85 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx doctor` command — diagnose a project + environment and report
+ * PASS / WARN / FAIL for each check with an actionable fix.
+ *
+ * Designed to be usable both by humans (clean monochrome checklist) and by
+ * AI agents / CI (`--json`). Exit code is the contract: 0 when there are no
+ * FAILs (warnings are fine), 1 when any check FAILs — so `astryx doctor` works
+ * as a CI gate.
+ */
+
+import {runChecks} from '../api/doctor.mjs';
+import {jsonOut, humanLog} from '../lib/json.mjs';
+
+/** Status → human glyph (monochrome, matching the rest of the CLI). */
+const GLYPH = {
+  pass: '\u2713', // ✓
+  warn: '\u26a0', // ⚠
+  fail: '\u2717', // ✗
+  info: '\u2139', // ℹ
+};
+
+/**
+ * Render the report as a human-readable checklist.
+ * @param {import('../api/doctor.mjs').DoctorReport} report
+ */
+function printHuman(report) {
+  humanLog('astryx doctor — diagnosing your setup\n');
+  for (const check of report.checks) {
+    const glyph = GLYPH[check.status] ?? '\u00b7';
+    humanLog(`  ${glyph} ${check.label}`);
+    humanLog(`      ${check.message}`);
+    if (check.fix) {
+      humanLog(`      \u2192 fix: ${check.fix}`);
+    }
+  }
+
+  const {pass, warn, fail, info} = report.summary;
+  humanLog('');
+  humanLog(
+    `Summary: ${pass} passed, ${warn} warning${warn === 1 ? '' : 's'}, ` +
+      `${fail} failure${fail === 1 ? '' : 's'}` +
+      (info ? `, ${info} info` : ''),
+  );
+  if (fail > 0) {
+    humanLog('\nSome checks failed. Address the items marked \u2717 above.');
+  } else if (warn > 0) {
+    humanLog('\nNo failures — but review the \u26a0 warnings above when you can.');
+  } else {
+    humanLog('\nAll checks passed. Your XDS setup looks healthy.');
+  }
+}
+
+/**
+ * Register the `astryx doctor` command.
+ * @param {import('commander').Command} program
+ */
+export function registerDoctor(program) {
+  program
+    .command('doctor')
+    .description('Diagnose your XDS setup and report problems with fixes')
+    .addHelpText(
+      'after',
+      '\nExit code:\n' +
+        '  0  no failures (warnings are allowed) — safe as a CI gate\n' +
+        '  1  one or more checks failed\n',
+    )
+    .action(async () => {
+      const json = program.opts().json || false;
+      const report = await runChecks();
+      const hasFailure = report.summary.fail > 0;
+
+      if (json) {
+        jsonOut('doctor', report);
+      } else {
+        printHuman(report);
+      }
+
+      // Exit code is the contract: any FAIL → exit 1. Warnings never fail.
+      if (hasFailure) {
+        process.exitCode = 1;
+      }
+    });
+}