@astryxdesign/cli 0.2.0 → 0.3.0

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

@@ -1,143 +0,0 @@
-// 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, beforeAll} from 'vitest';
-import * as path from 'node:path';
-import {fileURLToPath} from 'node:url';
-import {runCli} from '../../test-utils/run-cli.mjs';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-// Repo root holds packages/core, which findCoreDir() walks up to locate.
-const REPO_ROOT = path.resolve(__dirname, '../../../..');
-
-async function listOutputs(cmd) {
-  const brief = (await runCli([cmd, '--list', '--detail', 'brief'], REPO_ROOT)).stdout;
-  const compact = (await runCli([cmd, '--list', '--detail', 'compact'], REPO_ROOT)).stdout;
-  const full = (await runCli([cmd, '--list', '--detail', 'full'], REPO_ROOT)).stdout;
-  return {brief, compact, full};
-}
-
-describe('--detail level ordering: component --list', () => {
-  let brief, compact, full;
-  beforeAll(async () => {
-    ({brief, compact, full} = await listOutputs('component'));
-  }, 60_000);
-
-  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('--json list emits one component.list type across all detail levels, tagged by data.detail', async () => {
-    const names = JSON.parse((await runCli(['component', '--list', '--json'], REPO_ROOT)).stdout);
-    expect(names.type).toBe('component.list');
-    expect(names.apiVersion).toBe(1);
-    expect(names.data.detail).toBe('names');
-    expect(typeof names.data.components).toBe('object');
-
-    const compact = JSON.parse((await runCli(['component', '--list', '--detail', 'compact', '--json'], REPO_ROOT)).stdout);
-    expect(compact.type).toBe('component.list');
-    expect(compact.data.detail).toBe('compact');
-    expect(typeof compact.data.components).toBe('object');
-
-    const full = JSON.parse((await runCli(['component', '--list', '--detail', 'full', '--json'], REPO_ROOT)).stdout);
-    expect(full.type).toBe('component.list');
-    expect(full.data.detail).toBe('full');
-    expect(typeof full.data.components).toBe('object');
-  }, 60_000);
-});
-
-describe('--detail level ordering: hook --list', () => {
-  let brief, compact, full;
-  beforeAll(async () => {
-    ({brief, compact, full} = await listOutputs('hook'));
-  }, 60_000);
-
-  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('--json list emits one hook.list type across all detail levels, tagged by data.detail', async () => {
-    const names = JSON.parse((await runCli(['hook', '--list', '--json'], REPO_ROOT)).stdout);
-    expect(names.type).toBe('hook.list');
-    expect(names.apiVersion).toBe(1);
-    expect(names.data.detail).toBe('names');
-    expect(typeof names.data.components).toBe('object');
-
-    const compact = JSON.parse((await runCli(['hook', '--list', '--detail', 'compact', '--json'], REPO_ROOT)).stdout);
-    expect(compact.type).toBe('hook.list');
-    expect(compact.data.detail).toBe('compact');
-    expect(typeof compact.data.components).toBe('object');
-
-    const full = JSON.parse((await runCli(['hook', '--list', '--detail', 'full', '--json'], REPO_ROOT)).stdout);
-    expect(full.type).toBe('hook.list');
-    expect(full.data.detail).toBe('full');
-    expect(typeof full.data.components).toBe('object');
-  }, 60_000);
-});

package/cli/commands/discover.mjs

@@ -1,143 +0,0 @@
-// 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 {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/discover.mjs';
-import {getCliInvocation} from '../../utils/package-manager.mjs';
-
-/**
- * @param {import('commander').Command} program
- */
-export function registerDiscover(program) {
-  program
-    .command('discover [query]')
-    .description('Discover external packages and components')
-    .option('--components', 'List components only')
-    .action(
-      /**
-       * @param {string | undefined} query
-       * @param {{components?: boolean}} options
-       */
-      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;
-      const run = getCliInvocation();
-
-      let result;
-      try {
-        result = await discoverApi(query, {components: options.components, lang, zh});
-      } catch (e) {
-        const err = /** @type {import('../../api/error.mjs').AstryxError} */ (e);
-        cliError(err.message, {suggestions: err.suggestions, code: err.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);
-      }
-
-      switch (result.type) {
-        case 'discover.list': {
-          if (result.data.length === 0) {
-            humanLog('');
-            if (result.meta && result.meta.configured === false) {
-              humanLog('No integrations configured.');
-              humanLog('');
-              humanLog('Add integration package names to astryx.config.mjs:');
-              humanLog('');
-              humanLog('  export default {');
-              humanLog("    integrations: ['@scope/your-integration'],");
-              humanLog('  };');
-            } else {
-              humanLog('No external components found in configured integrations.');
-            }
-            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(`  ${run} discover <package>            Browse a package`);
-            humanLog(`  ${run} discover <package>/Component  View component docs`);
-            humanLog(`  ${run} 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: ${run} 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(`  ${run} discover ` + m.package + '/' + m.component);
-          }
-          humanLog('');
-          break;
-        }
-      }
-    });
-}

package/cli/commands/docs.mjs

@@ -1,181 +0,0 @@
-// 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 {getCliInvocation} 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/docs.mjs';
-
-// ─── Formatting ──────────────────────────────────────────────────────────────
-
-/**
- * @param {string[]} headers
- * @param {string[][]} rows
- * @returns {string}
- */
-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}`;
-}
-
-/**
- * @param {string[]} headers
- * @param {string[][]} rows
- * @returns {string}
- */
-function formatTableCompact(headers, rows) {
-  return rows.map(r => r.join(' = ')).join('\n');
-}
-
-/**
- * @param {import('../../../core/src/docs-types').ContentBlock} block
- * @param {'full' | 'compact' | 'brief'} detail
- * @returns {string | null}
- */
-function formatBlock(block, detail) {
-  switch (block.type) {
-    case 'prose':
-      return block.text;
-
-    case 'heading':
-      return `${'#'.repeat(block.level || 3)} ${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' ? (/** @type {number} */ i) => `${i + 1}. `
-        : block.style === 'dont' ? () => '❌ '
-        : block.style === 'do' ? () => '✓ '
-        : () => '- ';
-      return block.items.map((item, i) => `${prefix(i)}${item}`).join('\n');
-    }
-
-    default:
-      return null;
-  }
-}
-
-/**
- * @param {import('../../../core/src/docs-types').ReferenceSection} section
- * @param {'full' | 'compact' | 'brief'} detail
- * @returns {string}
- */
-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')}`;
-}
-
-/**
- * @param {import('../../../core/src/docs-types').ReferenceDoc} docs
- * @param {'full' | 'compact' | 'brief'} detail
- * @returns {string}
- */
-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 ─────────────────────────────────────────────────────────────────
-
-/**
- * @param {import('commander').Command} program
- */
-export function registerDocs(program) {
-  program
-    .command('docs [topic] [section]')
-    .description('Print reference docs')
-    .action(async (/** @type {string | undefined} */ topic, /** @type {string | undefined} */ section) => {
-      const run = getCliInvocation();
-      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.
-        const err = /** @type {import('../../api/error.mjs').AstryxError} */ (e);
-        cliError(err.message, {suggestions: err.suggestions || [], code: err.code});
-        return;
-      }
-
-      if (json) return jsonOut(result);
-
-      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} docs <topic>`);
-          humanLog(`       ${run} 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/cli/commands/docs.test.mjs

@@ -1,101 +0,0 @@
-// 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(), 'astryx-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/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/cli/commands/doctor.mjs

@@ -1,85 +0,0 @@
-// 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/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/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({type: 'doctor', data: report});
-      } else {
-        printHuman(report);
-      }
-
-      // Exit code is the contract: any FAIL → exit 1. Warnings never fail.
-      if (hasFailure) {
-        process.exitCode = 1;
-      }
-    });
-}