@astryxdesign/cli 0.0.0-bootstrap.0 → 0.0.15

package/src/commands/json-contract.test.mjs

@@ -0,0 +1,227 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Integration tests for the global --json contract.
+ *
+ * These tests spawn the CLI as a subprocess (the only way to exercise
+ * Commander hooks end-to-end) in a tmp directory, then assert:
+ *
+ *   1. Commands NOT on the JSON_SUPPORTED allowlist reject --json BEFORE
+ *      running any side effects (no files written, exit 1, valid JSON
+ *      error envelope on stdout).
+ *
+ *   2. Commands ON the allowlist emit valid JSON envelopes for their
+ *      common code paths (success and error).
+ *
+ *   3. The --version --json variant emits a structured envelope.
+ *
+ * Spawning a real subprocess (vs. importing program.mjs) is essential
+ * because Commander's preAction hooks and process.exit calls only fire
+ * during a real .parse() against argv.
+ */
+
+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_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');
+
+function runCli(args, {cwd} = {}) {
+  const res = spawnSync('node', [CLI_BIN, ...args], {
+    cwd: cwd || process.cwd(),
+    encoding: 'utf-8',
+    timeout: 20_000,
+  });
+  return {
+    status: res.status,
+    stdout: res.stdout || '',
+    stderr: res.stderr || '',
+  };
+}
+
+function parseJson(stdout) {
+  // CLI emits a single JSON document. If anything else snuck onto stdout
+  // (clack output, console.log strings, etc.) JSON.parse will throw —
+  // which is exactly the failure mode we want to catch in tests.
+  return JSON.parse(stdout);
+}
+
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-json-contract-'));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('--json contract: rejects before side effects', () => {
+  it('astryx init --json --features agents does not write .claude/CLAUDE.md', () => {
+    const before = fs.readdirSync(tmpDir);
+    expect(before).toEqual([]);
+
+    const {status, stdout} = runCli(['init', '--json', '--features', 'agents'], {cwd: tmpDir});
+
+    // 1. Exit code must be non-zero.
+    expect(status).toBe(1);
+
+    // 2. Stdout must be valid JSON with an error envelope.
+    const parsed = parseJson(stdout);
+    expect(parsed).toHaveProperty('error');
+    expect(parsed.error).toMatch(/json/i);
+    expect(parsed.error).toMatch(/init/i);
+
+    // 3. CRITICAL — no filesystem mutation took place.
+    const after = fs.readdirSync(tmpDir);
+    expect(after).toEqual([]);
+    expect(fs.existsSync(path.join(tmpDir, '.claude'))).toBe(false);
+    expect(fs.existsSync(path.join(tmpDir, '.claude/CLAUDE.md'))).toBe(false);
+    expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(false);
+  });
+
+  it('astryx init --json --all does not write any files', () => {
+    const {status, stdout} = runCli(['init', '--json', '--all'], {cwd: tmpDir});
+    expect(status).toBe(1);
+    parseJson(stdout); // valid JSON
+    expect(fs.readdirSync(tmpDir)).toEqual([]);
+  });
+
+  it('astryx gap-report setup --json rejects before prompting', () => {
+    const {status, stdout} = runCli(['gap-report', 'setup', '--json'], {cwd: tmpDir});
+    expect(status).toBe(1);
+    const parsed = parseJson(stdout);
+    expect(parsed.error).toMatch(/gap-report setup/);
+    // No astryx.config.mjs written.
+    expect(fs.existsSync(path.join(tmpDir, 'astryx.config.mjs'))).toBe(false);
+  });
+
+  it('astryx theme --json (parent, no subcommand) rejects without printing help', () => {
+    const {status, stdout, stderr} = runCli(['theme', '--json'], {cwd: tmpDir});
+    expect(status).toBe(1);
+    const parsed = parseJson(stdout);
+    expect(parsed.error).toMatch(/theme/);
+    // Human help text would mention "Usage:" — must NOT appear on stdout.
+    expect(stdout).not.toMatch(/Usage:/);
+    expect(stderr).not.toMatch(/Usage:/);
+  });
+
+  it('astryx postinstall --json rejects (hidden command not on allowlist)', () => {
+    const {status, stdout} = runCli(['postinstall', '--json'], {cwd: tmpDir});
+    expect(status).toBe(1);
+    const parsed = parseJson(stdout);
+    expect(parsed).toHaveProperty('error');
+  });
+
+  it('error envelope is { error, suggestions? } — never { type, data }', () => {
+    const {stdout} = runCli(['init', '--json'], {cwd: tmpDir});
+    const parsed = parseJson(stdout);
+    expect(parsed).toHaveProperty('error');
+    expect(parsed).not.toHaveProperty('type');
+    expect(parsed).not.toHaveProperty('data');
+  });
+});
+
+describe('--json contract: supported commands emit valid envelopes', () => {
+  it('astryx --version --json emits { type: "version", data: { version } }', () => {
+    const {status, stdout} = runCli(['--version', '--json']);
+    expect(status).toBe(0);
+    const parsed = parseJson(stdout);
+    expect(parsed.type).toBe('version');
+    expect(parsed.data).toHaveProperty('version');
+    expect(typeof parsed.data.version).toBe('string');
+  });
+
+  it('astryx --json (no subcommand) emits a help envelope', () => {
+    const {status, stdout} = runCli(['--json']);
+    expect(status).toBe(0);
+    const parsed = parseJson(stdout);
+    expect(parsed.type).toBe('help');
+    expect(Array.isArray(parsed.data.commands)).toBe(true);
+    expect(Array.isArray(parsed.data.jsonSupported)).toBe(true);
+  });
+
+  it('astryx gap-report --json --list-categories returns a typed envelope', () => {
+    const {status, stdout} = runCli(['gap-report', '--json', '--list-categories'], {cwd: tmpDir});
+    expect(status).toBe(0);
+    const parsed = parseJson(stdout);
+    expect(parsed.type).toBe('gap-report.categories');
+    expect(Array.isArray(parsed.data)).toBe(true);
+  });
+
+  it('astryx gap-report --json without required flags emits a structured error (no clack)', () => {
+    // Configure gap-report so it doesn't error on "disabled" — we want to
+    // hit the "interactive prompt would start" branch.
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.config.mjs'),
+      'export default { gapReport: { command: "true" } };\n',
+    );
+    const {status, stdout} = runCli(['gap-report', '--json'], {cwd: tmpDir});
+    expect(status).toBe(1);
+    const parsed = parseJson(stdout);
+    expect(parsed.error).toMatch(/component/i);
+    // Must not contain clack-rendered prompt characters.
+    expect(stdout).not.toMatch(/Which component/);
+  });
+
+  it('astryx upgrade --json --list returns the codemod list', () => {
+    const {status, stdout} = runCli(['upgrade', '--json', '--list'], {cwd: tmpDir});
+    expect(status).toBe(0);
+    const parsed = parseJson(stdout);
+    expect(parsed.type).toBe('upgrade.list');
+    expect(Array.isArray(parsed.data)).toBe(true);
+  });
+
+  it('astryx upgrade --json (already up to date) emits upgrade.status', () => {
+    // Force a no-op range: from > to.
+    const {status, stdout} = runCli(
+      ['upgrade', '--json', '--from', '99.0.0', '--to', '0.0.1'],
+      {cwd: tmpDir},
+    );
+    expect(status).toBe(0);
+    const parsed = parseJson(stdout);
+    expect(parsed.type).toBe('upgrade.status');
+    expect(parsed.data.status).toBe('up_to_date');
+    expect(parsed.data.from).toBe('99.0.0');
+    expect(parsed.data.to).toBe('0.0.1');
+  });
+
+  it('astryx discover --json (no config) includes meta.configured=false', () => {
+    const {status, stdout} = runCli(['discover', '--json'], {cwd: tmpDir});
+    expect(status).toBe(0);
+    const parsed = parseJson(stdout);
+    expect(parsed.type).toBe('discover.list');
+    expect(parsed.data).toEqual([]);
+    expect(parsed.meta).toEqual({configured: false});
+  });
+
+  it('astryx template --json emits a typed envelope', () => {
+    const {status, stdout} = runCli(['template', '--json'], {cwd: tmpDir});
+    expect(status).toBe(0);
+    const parsed = parseJson(stdout);
+    expect(parsed.type).toBe('template.list');
+    expect(Array.isArray(parsed.data)).toBe(true);
+  });
+
+  it('astryx docs --json emits a typed envelope', () => {
+    const {status, stdout} = runCli(['docs', '--json'], {cwd: tmpDir});
+    expect(status).toBe(0);
+    const parsed = parseJson(stdout);
+    expect(parsed.type).toMatch(/^docs\./);
+  });
+
+  it('astryx doctor --json emits a doctor envelope with checks + summary', () => {
+    // Run in a bare tmp dir → @astryxdesign/core won't resolve → a FAIL → exit 1.
+    const {status, stdout} = runCli(['doctor', '--json'], {cwd: tmpDir});
+    expect(status).toBe(1);
+    const parsed = parseJson(stdout);
+    expect(parsed.type).toBe('doctor');
+    expect(Array.isArray(parsed.data.checks)).toBe(true);
+    expect(parsed.data.summary).toHaveProperty('fail');
+    expect(parsed.data.summary.fail).toBeGreaterThan(0);
+  });
+});

package/src/commands/search.mjs

@@ -0,0 +1,100 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file search command — unified ranked search across all content domains.
+ *
+ * One "I'm looking for X" entry point spanning components, hooks, docs topics,
+ * and templates (page + block). Results are ranked by relevance and tagged
+ * with their domain, with a follow-up command so the user knows what to run
+ * next.
+ *
+ * Usage:
+ *   astryx search button                 Ranked results across all domains
+ *   astryx search modal --type component Filter to a single domain
+ *   astryx search forms --limit 5        Cap the result count
+ *   astryx search button --detail        Verbose (include import / reason)
+ *   astryx search button --json          Typed JSON envelope
+ */
+
+import {getRunPrefix} from '../utils/package-manager.mjs';
+import {jsonOut, humanLog} from '../lib/json.mjs';
+import {cliError} from '../lib/cli-error.mjs';
+import {search as searchApi, SEARCH_DOMAINS} from '../api/search.mjs';
+
+const DOMAIN_LABEL = {
+  component: 'component',
+  hook: 'hook',
+  doc: 'docs',
+  template: 'template',
+};
+
+export function registerSearch(program) {
+  program
+    .command('search <query>')
+    .description('Search components, hooks, docs, and templates in one ranked list')
+    .option('--type <domain>', `Filter to one domain (${SEARCH_DOMAINS.join('|')})`)
+    .option('--limit <n>', 'Max number of results (default 20)')
+    .option('--detail', 'Verbose output (include import paths and match reason)')
+    .action(async (query, options) => {
+      const json = program.opts().json || false;
+
+      let limit = 20;
+      if (options.limit != null) {
+        const parsed = Number.parseInt(options.limit, 10);
+        if (!Number.isFinite(parsed) || parsed <= 0) {
+          cliError(`Invalid --limit value "${options.limit}". Must be a positive integer.`);
+          return;
+        }
+        limit = parsed;
+      }
+
+      let result;
+      try {
+        result = await searchApi(query, {
+          cwd: process.cwd(),
+          type: options.type,
+          limit,
+        });
+      } catch (e) {
+        cliError(e.message, {suggestions: e.suggestions});
+        return;
+      }
+
+      if (json) return jsonOut(result.type, result.data);
+
+      // ── Text output ──────────────────────────────────────────────
+      const run = getRunPrefix();
+      const {query: q, results} = result.data;
+
+      // No matches is a valid, successful outcome — clean message, exit 0.
+      if (results.length === 0) {
+        humanLog('');
+        humanLog(`No results for "${q}".`);
+        humanLog('');
+        humanLog(`Try a broader term, or browse: ${run} astryx component --list`);
+        humanLog('');
+        return;
+      }
+
+      humanLog('');
+      humanLog(`Results for "${q}" (${results.length}):`);
+      humanLog('');
+      for (const r of results) {
+        const tag = `[${DOMAIN_LABEL[r.domain] || r.domain}]`.padEnd(12);
+        const display = r.domain === 'template' && r.displayName ? r.displayName : r.name;
+        humanLog(`  ${tag} ${display}`);
+        if (r.description) {
+          humanLog(`               ${r.description}`);
+        }
+        humanLog(`               → ${run} ${r.command}`);
+        if (options.detail) {
+          if (r.import) humanLog(`               import: ${r.import}`);
+          humanLog(`               match: ${r.reason} (score ${r.score})`);
+        }
+        humanLog('');
+      }
+    });
+}
+
+// Re-export the API for external consumers.
+export {search, SEARCH_DOMAINS} from '../api/search.mjs';

package/src/commands/search.test.mjs

@@ -0,0 +1,202 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Tests for the unified `search` command + its programmatic API.
+ *
+ * Two layers:
+ *   1. API-level (direct import of api/search.mjs) — ranking, cross-domain
+ *      results, --type/--limit, typo tolerance, empty results, envelope shape.
+ *   2. CLI-level (spawned subprocess) — exit codes and the --json contract,
+ *      which only fire through a real Commander .parse() against argv.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {spawnSync} from 'node:child_process';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {search, scoreCandidate, SEARCH_DOMAINS} from '../api/search.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');
+// Run against the monorepo root so @astryxdesign/core is discoverable.
+const REPO_ROOT = path.resolve(__dirname, '../../../..');
+const OPTS = {cwd: REPO_ROOT};
+
+function runCli(args) {
+  const res = spawnSync('node', [CLI_BIN, ...args], {
+    cwd: REPO_ROOT,
+    encoding: 'utf-8',
+    timeout: 30_000,
+  });
+  return {status: res.status, stdout: res.stdout || '', stderr: res.stderr || ''};
+}
+
+describe('search() API — ranking', () => {
+  it('ranks an exact component name match first', async () => {
+    const {data} = await search('button', OPTS);
+    expect(data.results.length).toBeGreaterThan(0);
+    const top = data.results[0];
+    expect(top.domain).toBe('component');
+    expect(top.name).toBe('Button');
+    expect(top.score).toBe(100);
+    expect(top.command).toBe('astryx component Button');
+  });
+
+  it('returns components/hooks tagged with a matching keyword', async () => {
+    const {data} = await search('button', OPTS);
+    // IconButton carries the "button" keyword; should be present and scored
+    // on a keyword (not name) signal.
+    const iconButton = data.results.find(r => r.name === 'IconButton');
+    expect(iconButton).toBeTruthy();
+    expect(iconButton.domain).toBe('component');
+    expect(iconButton.score).toBeGreaterThanOrEqual(70);
+    expect(iconButton.reason.toLowerCase()).toContain('keyword');
+  });
+});
+
+describe('search() API — cross-domain', () => {
+  it('returns results from more than one domain for a broad query', async () => {
+    const {data} = await search('color', OPTS);
+    const domains = new Set(data.results.map(r => r.domain));
+    // "color" is a doc topic AND appears across components.
+    expect(domains.has('doc')).toBe(true);
+    expect(domains.size).toBeGreaterThan(1);
+    // The doc topic should carry a follow-up `astryx docs` command.
+    const docHit = data.results.find(r => r.domain === 'doc');
+    expect(docHit.command.startsWith('astryx docs ')).toBe(true);
+  });
+
+  it('every result is tagged with a known domain and a command', async () => {
+    const {data} = await search('button', OPTS);
+    for (const r of data.results) {
+      expect(SEARCH_DOMAINS).toContain(r.domain);
+      expect(typeof r.command).toBe('string');
+      expect(r.command.length).toBeGreaterThan(0);
+    }
+  });
+});
+
+describe('search() API — filters', () => {
+  it('--type component returns only components', async () => {
+    const {data} = await search('modal', {...OPTS, type: 'component'});
+    expect(data.results.length).toBeGreaterThan(0);
+    for (const r of data.results) {
+      expect(r.domain).toBe('component');
+    }
+  });
+
+  it('--type doc returns only docs', async () => {
+    const {data} = await search('color', {...OPTS, type: 'doc'});
+    for (const r of data.results) {
+      expect(r.domain).toBe('doc');
+    }
+  });
+
+  it('respects --limit', async () => {
+    const {data} = await search('button', {...OPTS, limit: 3});
+    expect(data.results.length).toBeLessThanOrEqual(3);
+  });
+
+  it('rejects an unknown --type', async () => {
+    await expect(search('x', {...OPTS, type: 'bogus'})).rejects.toThrow(/Unknown --type/);
+  });
+});
+
+describe('search() API — fuzzy / typo tolerance', () => {
+  it('finds Button for the typo "buton"', async () => {
+    const {data} = await search('buton', OPTS);
+    const button = data.results.find(r => r.name === 'Button');
+    expect(button).toBeTruthy();
+    expect(button.domain).toBe('component');
+  });
+});
+
+describe('search() API — empty + envelope', () => {
+  it('returns an empty result set (not an error) for a no-match query', async () => {
+    const {type, data} = await search('zzqqxx_definitely_no_match', OPTS);
+    expect(type).toBe('search');
+    expect(data.results).toEqual([]);
+    expect(data.query).toBe('zzqqxx_definitely_no_match');
+  });
+
+  it('throws when the query is empty', async () => {
+    await expect(search('', OPTS)).rejects.toThrow(/query is required/);
+  });
+
+  it('returns the correct envelope shape', async () => {
+    const result = await search('button', OPTS);
+    expect(result.type).toBe('search');
+    expect(result.data).toHaveProperty('query');
+    expect(Array.isArray(result.data.results)).toBe(true);
+    const top = result.data.results[0];
+    expect(top).toHaveProperty('domain');
+    expect(top).toHaveProperty('name');
+    expect(top).toHaveProperty('score');
+    expect(top).toHaveProperty('description');
+    expect(top).toHaveProperty('command');
+  });
+});
+
+describe('scoreCandidate()', () => {
+  it('scores an exact name match at 100', () => {
+    expect(scoreCandidate('button', {name: 'button'}).score).toBe(100);
+  });
+
+  it('scores an exact keyword above a description mention', () => {
+    const kw = scoreCandidate('toggle', {name: 'Switch', keywords: ['toggle']});
+    const desc = scoreCandidate('toggle', {name: 'Switch', description: 'A toggle control'});
+    expect(kw.score).toBeGreaterThan(desc.score);
+  });
+
+  it('returns null when nothing matches', () => {
+    expect(scoreCandidate('zzzz', {name: 'Button', keywords: ['cta']})).toBeNull();
+  });
+});
+
+describe('search CLI — exit codes + JSON contract', () => {
+  it('exits 0 for a successful search', () => {
+    const r = runCli(['search', 'button']);
+    expect(r.status).toBe(0);
+  });
+
+  it('exits 0 for a no-match query (valid empty result, not failure)', () => {
+    const r = runCli(['search', 'zzqqxx_no_match']);
+    expect(r.status).toBe(0);
+    expect(r.stdout).toContain('No results');
+  });
+
+  it('exits 1 for an invalid --type', () => {
+    const r = runCli(['search', 'x', '--type', 'bogus']);
+    expect(r.status).toBe(1);
+  });
+
+  it('exits 1 for an invalid --limit', () => {
+    const r = runCli(['search', 'x', '--limit', '0']);
+    expect(r.status).toBe(1);
+  });
+
+  it('emits a valid --json envelope', () => {
+    const r = runCli(['--json', 'search', 'button']);
+    expect(r.status).toBe(0);
+    const parsed = JSON.parse(r.stdout);
+    expect(parsed.apiVersion).toBe(1);
+    expect(parsed.type).toBe('search');
+    expect(parsed.data.query).toBe('button');
+    expect(Array.isArray(parsed.data.results)).toBe(true);
+    expect(parsed.data.results[0].name).toBe('Button');
+  });
+
+  it('emits a valid --json envelope with empty results for no match', () => {
+    const r = runCli(['--json', 'search', 'zzqqxx_no_match']);
+    expect(r.status).toBe(0);
+    const parsed = JSON.parse(r.stdout);
+    expect(parsed.type).toBe('search');
+    expect(parsed.data.results).toEqual([]);
+  });
+
+  it('shows the follow-up command hint in human output', () => {
+    const r = runCli(['search', 'button']);
+    expect(r.stdout).toContain('astryx component Button');
+    expect(r.stdout).toContain('[component]');
+  });
+});