@astryxdesign/cli 0.2.0 → 0.3.0

package/cli/e2e-smoke.test.mjs

@@ -1,96 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Real-binary e2e smoke — the process boundary the in-process harness
- * cannot cover.
- *
- * Every other CLI suite now drives the program IN-PROCESS via
- * test-utils/run-cli.mjs (createProgram + parseAsync), which is fast and
- * deterministic but deliberately bypasses `bin/astryx.mjs`: the Node-version
- * preflight gate, the realpath-based `importSrc` module resolution, the real
- * `process.exit` code, and the top-level try/catch error boundary. This file is
- * the small, high-signal counterweight that spawns the ACTUAL binary and asserts
- * the things only a real process can prove:
- *
- *   - the bin boots and a happy command exits 0;
- *   - a real command's output reaches stdout across the process boundary;
- *   - failures produce a NON-ZERO real exit code (not just process.exitCode);
- *   - the --json error boundary emits a valid envelope on stdout end-to-end;
- *   - Commander parse errors route through handleCommanderError in the REAL
- *     bin — i.e. the harness's in-process replica of that path matches reality.
- *
- * Keep this SMALL. Behavior/coverage of individual commands lives in their
- * in-process suites; this only guards the boundary. Do not grow it into a
- * per-command spawn suite (that flakiness is exactly what the rollout removed).
- */
-
-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');
-
-/** Spawn the real binary. Returns the raw exit status + captured streams. */
-function spawnCli(args) {
-  const res = spawnSync(process.execPath, [CLI_BIN, ...args], {
-    encoding: 'utf8',
-    timeout: 30_000,
-    stdio: ['ignore', 'pipe', 'pipe'],
-    // Deterministic output: no color, and don't let a CI env flip behavior.
-    env: {...process.env, FORCE_COLOR: '0', CI: ''},
-  });
-  return {
-    status: res.status,
-    stdout: res.stdout || '',
-    stderr: res.stderr || '',
-  };
-}
-
-describe('e2e smoke: real binary boots + exits (happy paths)', () => {
-  it('astryx --version boots and exits 0 with a semver', () => {
-    const {status, stdout} = spawnCli(['--version']);
-    expect(status).toBe(0);
-    expect(stdout).toMatch(/\d+\.\d+\.\d+/);
-  });
-
-  it('astryx template --list runs a real command and prints to stdout (exit 0)', () => {
-    // `template` is bundled with the CLI (no compiled core needed), so this
-    // exercises the full command-load path through the real bin without a build.
-    const {status, stdout} = spawnCli(['template', '--list']);
-    expect(status).toBe(0);
-    expect(stdout.trim().length).toBeGreaterThan(0);
-  });
-});
-
-describe('e2e smoke: real binary error boundary + exit codes', () => {
-  it('unknown command exits non-zero with a stderr message', () => {
-    const {status, stderr} = spawnCli(['definitely-not-a-real-command']);
-    expect(status).not.toBe(0);
-    expect(stderr).toMatch(/unknown command/i);
-  });
-
-  it('init --json is rejected with a real exit 1 + JSON error envelope on stdout', () => {
-    // Proves the whole chain across the process boundary: bin boots → Commander
-    // runs → preAction --json gate rejects init → error envelope on stdout →
-    // process really exits 1 (not merely process.exitCode set in-process).
-    const {status, stdout} = spawnCli(['init', '--json']);
-    expect(status).toBe(1);
-    const parsed = JSON.parse(stdout);
-    expect(parsed).toHaveProperty('error');
-    expect(parsed).not.toHaveProperty('type');
-  });
-
-  it('a Commander parse error routes through handleCommanderError in the real bin', () => {
-    // `theme build` with no <file> fails at parse time (missing argument) BEFORE
-    // any command action or core load. In --json mode the real bin must convert
-    // that CommanderError into a valid envelope on stdout with a mapped ERR_
-    // code and exit 1 — the exact path run-cli.mjs replicates in-process.
-    const {status, stdout} = spawnCli(['theme', 'build', '--json']);
-    expect(status).toBe(1);
-    const parsed = JSON.parse(stdout);
-    expect(parsed).toHaveProperty('error');
-    expect(parsed.code).toMatch(/^ERR_/);
-  });
-});

package/cli/index.mjs

@@ -1,412 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Astryx CLI — Commander program setup
- *
- * Registers all commands via lazy loading. If one command fails to load
- * (bad import, syntax error), the other commands still work.
- *
- * The program is built by {@link createProgram} — a factory so tests can drive
- * a FRESH program in-process (via parseAsync) instead of spawning `node
- * bin/astryx.mjs` per assertion. `bin/astryx.mjs` and legacy importers use the
- * eager {@link program} singleton, which is just `await createProgram()`.
- */
-
-import {Command, Option} from 'commander';
-import {fileURLToPath} from 'node:url';
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import {checkForUpdate} from '../utils/update-check.mjs';
-import {getCliInvocation} from '../utils/package-manager.mjs';
-import {API_VERSION, setJsonMode} from '../lib/json.mjs';
-import {buildManifest} from '../lib/manifest.mjs';
-import {cliError} from '../lib/cli-error.mjs';
-import {ERROR_CODES} from '../lib/error-codes.mjs';
-import {levenshteinDistance} from '../lib/string-utils.mjs';
-import {installJsonShim} from '../lib/json-shim.mjs';
-import {isAstryxInitialized} from '../lib/agent-docs/agent-docs.mjs';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-
-// Read version from package.json so it stays in sync
-const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8'));
-
-// Intercept `xds --version --json` (or `-V --json`) before Commander processes
-// the version flag and exits. Commander's built-in version handler prints the
-// raw version string and calls process.exit, bypassing our hooks — so the
-// only correct place to JSON-ify it is here. (Bin-time only: guarded on argv,
-// so importing this module in tests is a no-op.)
-const _argv = process.argv.slice(2);
-if (
-  (_argv.includes('--version') || _argv.includes('-V')) &&
-  _argv.includes('--json')
-) {
-  process.__xdsJsonHandled = true;
-  console.log(JSON.stringify({apiVersion: API_VERSION, type: 'version', data: {version: pkg.version}}, null, 2));
-  process.exit(0);
-}
-
-/**
- * Allowlist of fully-qualified command names that natively support --json.
- * Subcommands are listed by their full path (parent + leaf), e.g. "theme build".
- *
- * Commands NOT in this set will be rejected by the preAction hook below
- * BEFORE any side effects can run. This protects users from partial state
- * (e.g. files written, then --json error printed) on commands that don't
- * yet support structured output.
- */
-export const JSON_SUPPORTED = new Set([
-  'component',
-  'docs',
-  'blog',
-  'discover',
-  'search',
-  'build',
-  'swizzle',
-  'template',
-  'hook',
-  'theme build',
-  'theme list',
-  'theme add',
-  'upgrade',
-  'manifest',
-  'doctor',
-  'validate-integration',
-  'layout expand',
-  'layout check',
-  'layout grammar',
-]);
-
-/**
- * Compute the fully qualified command name, e.g. "theme build" or "swizzle".
- * @param {import('commander').Command} actionCommand
- * @param {import('commander').Command} root the root program
- * @returns {string}
- */
-function fullCommandName(actionCommand, root) {
-  const parts = [];
-  /** @type {import('commander').Command | null} */
-  let cmd = actionCommand;
-  while (cmd && cmd !== root) {
-    parts.unshift(cmd.name());
-    cmd = cmd.parent;
-  }
-  return parts.join(' ');
-}
-
-/**
- * Command registry — each command is lazy-loaded so a broken command
- * doesn't take down the entire CLI.
- */
-const commands = [
-  {name: 'init', path: './commands/init.mjs', register: 'registerInit'},
-  {name: 'component', path: './commands/component/index.mjs', register: 'registerComponent'},
-  {name: 'docs', path: './commands/docs.mjs', register: 'registerDocs'},
-  {name: 'blog', path: './commands/blog.mjs', register: 'registerBlog'},
-  {name: 'swizzle', path: './commands/swizzle.mjs', register: 'registerSwizzle'},
-  // agent-docs folded into init — functions still importable from agent-docs.mjs
-  {name: 'template', path: './commands/template.mjs', register: 'registerTemplate'},
-  {name: 'layout', path: './commands/layout.mjs', register: 'registerLayout'},
-  {name: 'upgrade', path: './commands/upgrade.mjs', register: 'registerUpgrade'},
-  {name: 'theme', path: './commands/build-theme.mjs', register: 'registerTheme'},
-  {name: 'hook', path: './commands/hook/index.mjs', register: 'registerHook'},
-  {name: 'discover', path: './commands/discover.mjs', register: 'registerDiscover'},
-  {name: 'search', path: './commands/search.mjs', register: 'registerSearch'},
-  {name: 'build', path: './commands/build.mjs', register: 'registerBuild'},
-  {name: 'doctor', path: './commands/doctor.mjs', register: 'registerDoctor'},
-  {
-    name: 'validate-integration',
-    path: './commands/validate-integration.mjs',
-    register: 'registerValidateIntegration',
-  },
-];
-
-const UPDATE_HINT_COMMANDS = new Set(['component', 'docs']);
-const SETUP_NUDGE_EXEMPT = new Set(['init', 'agent-docs']);
-
-/**
- * Build a fresh, fully-wired Astryx CLI program (root options, hooks, all
- * commands, manifest/postinstall, json-shim). Async because commands are
- * lazy-imported. Each call returns an independent Command so tests can
- * parseAsync repeatedly without commander state leaking between runs.
- *
- * @returns {Promise<import('commander').Command>}
- */
-export async function createProgram() {
-  const program = new Command();
-
-  program
-    .name('astryx')
-    .description('Design system CLI — components, themes, and tooling')
-    .version(pkg.version)
-    .option('--zh', 'Output docs in Chinese Simplified')
-    .option('--dense', 'Output docs in compressed dense format (token-efficient)')
-    .addOption(
-      new Option(
-        '--lang <locale>',
-        'Output docs in specified language/format (en, zh, dense)',
-      ).choices(['en', 'zh', 'dense']),
-    )
-    .addOption(
-      new Option('--detail <level>', 'Output detail level (full, compact, brief)')
-        .choices(['full', 'compact', 'brief'])
-        .default('full'),
-    )
-    .option(
-      '--json',
-      'Output as typed JSON. Success envelope: { type, data }. Error envelope: { error, suggestions? }.',
-    )
-    .addHelpCommand('help', 'Show all commands')
-    .action((options, cmd) => {
-      // If Commander handed us a positional that didn't match any subcommand,
-      // treat it as "unknown command" — exit 1 with a helpful suggestion.
-      // This is the bare-invocation handler; if cmd.args has content here,
-      // none of the registered subcommands matched.
-      const extras = (cmd && cmd.args) || [];
-      if (extras.length > 0) {
-        const unknown = String(extras[0]);
-        const known = (program.commands || [])
-          .filter((c) => !(/** @type {any} */ (c)._hidden) && c.name() !== 'help')
-          .map((c) => c.name());
-        const close = known
-          .map((name) => ({name, distance: levenshteinDistance(unknown.toLowerCase(), name.toLowerCase())}))
-          .filter((s) => s.distance <= 3)
-          .sort((a, b) => a.distance - b.distance)
-          .slice(0, 3)
-          .map((s) => ({name: s.name, reason: 'did you mean this?'}));
-        // If we have close matches, surface those. Otherwise list all known commands
-        // so callers (including AI agents) can see what's available.
-        const suggestions = close.length > 0
-          ? close
-          : known.map((name) => ({name, reason: 'available command'}));
-        cliError(`unknown command '${unknown}'`, {suggestions, code: ERROR_CODES.ERR_UNKNOWN_COMMAND});
-        return;
-      }
-
-      // `xds` (no subcommand) — print help, or emit a JSON envelope when --json.
-      if (program.opts().json) {
-        // Emit the full capability manifest so an agent can drive the entire
-        // CLI from one call — no need to scrape `--help` text. We derive this
-        // from Commander metadata (commands, args, flags) and layer on the
-        // JSON_SUPPORTED allowlist + per-command response types. See
-        // lib/manifest.mjs.
-        //
-        // Backwards-compat: the envelope keeps `type: 'help'` and the original
-        // shallow fields (`name`, `version`, `commands` as a string[] of names,
-        // `jsonSupported`) that earlier consumers read. The richer, structured
-        // surface is embedded under `data.manifest` (and is also available
-        // standalone via `astryx manifest --json` as `type: 'manifest'`).
-        process.__xdsJsonHandled = true;
-        const manifest = buildManifest(program, {
-          jsonSupported: JSON_SUPPORTED,
-          version: pkg.version,
-        });
-        console.log(JSON.stringify({
-          apiVersion: API_VERSION,
-          type: 'help',
-          data: {
-            name: manifest.name,
-            version: manifest.version,
-            // Original flat list of command names (string[]) — kept for compat.
-            commands: manifest.commands.map((c) => c.name),
-            jsonSupported: manifest.jsonSupported,
-            // Enriched, self-describing surface (the full manifest payload).
-            manifest,
-          },
-        }, null, 2));
-        return;
-      }
-      program.help();
-    });
-
-  /**
-   * Pre-action hook: gate --json BEFORE any command body runs.
-   *
-   * If --json is set on a command that is not on the JSON_SUPPORTED allowlist,
-   * emit a structured error envelope and exit 1 — without running the command's
-   * action (so no filesystem mutations, no interactive prompts, no spawned processes).
-   *
-   * This is the single source of truth for "command does not support --json".
-   * Individual commands should NOT re-check this; they may assume that if their
-   * action runs with --json, they are responsible for emitting an envelope on
-   * every code path.
-   */
-  program.hook('preAction', (thisCommand, actionCommand) => {
-    if (!program.opts().json) return;
-    // Engage global JSON mode so humanLog()/humanWarn() across commands become
-    // no-ops — stdout now carries only the JSON envelope.
-    setJsonMode(true);
-    // The root program's own action (no subcommand) is handled directly in
-    // its action handler — let it through. fullCommandName is '' there.
-    if (actionCommand === program) return;
-    const fullName = fullCommandName(actionCommand, program);
-    if (JSON_SUPPORTED.has(fullName)) return;
-    process.__xdsJsonHandled = true;
-    console.log(JSON.stringify({
-      apiVersion: API_VERSION,
-      error: `JSON output is not supported for the '${fullName}' command`,
-      code: ERROR_CODES.ERR_INVALID_OPTION,
-    }, null, 2));
-    process.exit(1);
-  });
-
-  /**
-   * Belt-and-suspenders postAction: if a "supported" command somehow forgot
-   * to emit a JSON envelope on a code path, surface that as a structured error
-   * rather than silent stdout corruption. This should never fire in practice;
-   * if it does, it's a bug in the command implementation.
-   */
-  program.hook('postAction', (thisCommand, actionCommand) => {
-    if (!program.opts().json) return;
-    if (process.__xdsJsonHandled) return;
-    const fullName = fullCommandName(actionCommand, program);
-    console.log(JSON.stringify({
-      apiVersion: API_VERSION,
-      error: `Internal: '${fullName}' completed without emitting a JSON envelope`,
-    }, null, 2));
-    process.exit(1);
-  });
-
-  /**
-   * Post-action hook: print update hint after any command output.
-   * Only fires for commands that produce output agents read (component, docs, etc.).
-   * Suppressed when --json is active to avoid contaminating stdout.
-   */
-  program.hook('postAction', (thisCommand, actionCommand) => {
-    if (program.opts().json) return;
-    try {
-      if (UPDATE_HINT_COMMANDS.has(actionCommand.name())) {
-        const hint = checkForUpdate();
-        if (hint) {
-          console.error(`\n${hint}`);
-        }
-      }
-    } catch {
-      // Never let update check break the CLI
-    }
-  });
-
-  /**
-   * Enforcement layer 3 — setup nudge. If this project hasn't run `astryx init`
-   * yet (no Astryx marker in any agent-doc file — see isAstryxInitialized), remind
-   * the user/agent that setup is missing.
-   *
-   * Uses `preAction` (not postAction) so it fires for EVERY valid command — even
-   * ones whose action errors or calls process.exit (postAction is skipped then).
-   *
-   * Suppressed in --json: that is machine output with a strict clean stdout+stderr
-   * contract (json-shim.test: "error envelopes have empty stderr"), and --json
-   * consumers parse stdout, not stderr — a stderr nudge would not reach them anyway.
-   * The core/cli postinstall layers already nudge at install time regardless of
-   * --json; a machine-readable nudge could later be an envelope field. Also skipped
-   * for the installer commands themselves and outside a project (no package.json).
-   */
-  program.hook('preAction', (thisCommand, actionCommand) => {
-    try {
-      if (program.opts().json) return; // machine mode — keep --json output clean
-      if (SETUP_NUDGE_EXEMPT.has(actionCommand.name())) return;
-      const cwd = process.cwd();
-      if (!fs.existsSync(path.join(cwd, 'package.json'))) return; // not a project
-      if (isAstryxInitialized(cwd)) return; // already set up — stay quiet
-      // Same wording as the core/cli postinstall nudges. #4151's getCliInvocation()
-      // renders the correct form for THIS project — scoped `npx @astryxdesign/cli`
-      // one-off, or `<pm> astryx` when installed — never the bare `npx astryx` footgun.
-      console.error(
-        `\nNext step: run \`${getCliInvocation(cwd)} init\` to finish setup and install the Astryx agent prompt.`,
-      );
-    } catch {
-      // Never let the nudge break a command.
-    }
-  });
-
-  for (const cmd of commands) {
-    try {
-      const mod = await import(cmd.path);
-      mod[cmd.register](program);
-    } catch (e) {
-      // Command fails to load but CLI still works
-      program
-        .command(cmd.name)
-        .description(`(failed to load: ${/** @type {any} */ (e).message})`)
-        .action(() => {
-          console.error(`Command "${cmd.name}" failed to load:`);
-          console.error(/** @type {any} */ (e).message);
-          process.exit(1);
-        });
-    }
-  }
-
-  // Capability manifest — a single, self-describing view of the whole CLI so
-  // agents can discover every command, argument, flag, and response type without
-  // scraping `--help`. `astryx manifest --json` is the dedicated surface; the bare
-  // `xds --json` embeds the same payload under data.manifest for convenience.
-  // Intentionally CLI-special — no `api/manifest`. It introspects the live
-  // Commander `program`, so extracting it to `api/` would create the `api → cli`
-  // cycle from #4302. `buildManifest(program)` lives in lib/; see its header.
-  program
-    .command('manifest')
-    .description('Print the full CLI capability manifest (use with --json)')
-    .action(() => {
-      const manifest = buildManifest(program, {
-        jsonSupported: JSON_SUPPORTED,
-        version: pkg.version,
-      });
-      if (program.opts().json) {
-        process.__xdsJsonHandled = true;
-        console.log(JSON.stringify({apiVersion: API_VERSION, type: 'manifest', data: manifest}, null, 2));
-        return;
-      }
-      // Human-readable summary. Agents should use --json.
-      console.log(`\n${manifest.name} v${manifest.version} — ${manifest.commands.length} commands\n`);
-      for (const c of manifest.commands) {
-        const tag = c.json ? ' [--json]' : '';
-        console.log(`  ${c.name}${tag}`);
-        if (c.description) console.log(`    ${c.description}`);
-      }
-      console.log(`\nRun \`${getCliInvocation()} manifest --json\` for the full structured manifest.\n`);
-    });
-
-  // Hidden command used by package.json postinstall scripts
-  program
-    .command('postinstall', {hidden: true})
-    .action(() => {
-      const r = getCliInvocation();
-      const pad = (/** @type {string} */ s, /** @type {number} */ len) => s + ' '.repeat(Math.max(0, len - s.length));
-      const W = 49; // inner width of the box
-      const line = (/** @type {string} */ s) => `  │ ${pad(s, W)}│`;
-      console.log(`
-  ╭${'─'.repeat(W + 2)}╮
-${line('')}
-${line('  Design system installed!')}
-${line('')}
-${line('  Get started:')}
-${line(`    ${r} init          Setup + AI agent docs`)}
-${line(`    ${r} --help        See all commands`)}
-${line('')}
-${line('  Or run directly:')}
-${line(`    ${r} init           Setup + AI agent docs`)}
-${line(`    ${r} component     Browse component docs`)}
-${line(`    ${r} hook          Browse hook docs`)}
-${line(`    ${r} docs          Design system reference`)}
-${line(`    ${r} swizzle       Customize a component`)}
-${line(`    ${r} template      Add a page template`)}
-${line('')}
-  ╰${'─'.repeat(W + 2)}╯
-`);
-    });
-
-  // Install the JSON shim AFTER all commands are registered so we can
-  // patch outputHelp on every command (root + subcommands). The shim
-  // extends the --json contract to cover Commander's parse-time short
-  // circuits (parse errors, unknown options, --help, unknown commands).
-  // See packages/cli/lib/json-shim.mjs for the rationale.
-  installJsonShim(program);
-
-  return program;
-}
-
-/**
- * Eager singleton program for `bin/astryx.mjs` and legacy importers. Tests
- * should call {@link createProgram} to get an isolated instance.
- */
-export const program = await createProgram();

package/codemods/__tests__/registry.test.mjs

@@ -1,67 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-import {describe, expect, test} from 'vitest';
-import {versions, getTransformsBetween} from '../registry.mjs';
-
-describe('registry', () => {
-  describe('versions', () => {
-    test('are sorted in ascending semver order across digit boundaries', () => {
-      expect(versions).toEqual([
-        '0.0.2',
-        '0.0.6',
-        '0.0.7',
-        '0.0.8',
-        '0.0.10',
-        '0.0.12',
-        '0.0.13',
-        '0.0.14',
-        '0.0.15',
-        '0.1.0',
-        '0.1.2',
-        '0.1.3',
-        '0.1.5',
-        '0.1.7',
-        '0.1.8',
-        '0.2.0',
-      ]);
-    });
-  });
-
-  describe('getTransformsBetween', () => {
-    test('returns v0.0.10 transforms for range 0.0.9 to 0.0.10', async () => {
-      const results = await getTransformsBetween('0.0.9', '0.0.10');
-      expect(results.map(r => r.version)).toEqual(['0.0.10']);
-    });
-
-    test('returns v0.0.6, v0.0.7, v0.0.8 for range 0.0.2 to 0.0.8', async () => {
-      const results = await getTransformsBetween('0.0.2', '0.0.8');
-      expect(results.map(r => r.version)).toEqual(['0.0.6', '0.0.7', '0.0.8']);
-    });
-
-    test('returns empty array when from equals to', async () => {
-      const results = await getTransformsBetween('0.0.6', '0.0.6');
-      expect(results).toEqual([]);
-    });
-
-    test('returns empty array when from is greater than to', async () => {
-      const results = await getTransformsBetween('0.0.8', '0.0.2');
-      expect(results).toEqual([]);
-    });
-
-    test('handles prerelease suffixes in --to (canary versions)', async () => {
-      const results = await getTransformsBetween(
-        '0.0.12',
-        '0.0.13-canary.21d98fa',
-      );
-      expect(results.map(r => r.version)).toEqual(['0.0.13']);
-    });
-
-    test('handles prerelease suffixes in --from', async () => {
-      const results = await getTransformsBetween(
-        '0.0.12-canary.abc1234',
-        '0.0.13',
-      );
-      expect(results.map(r => r.version)).toEqual(['0.0.13']);
-    });
-  });
-});