@astryxdesign/cli 0.2.0 → 0.3.0

package/clients/cli/commands/upgrade.test.mjs

@@ -0,0 +1,314 @@
+// 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 {registerUpgrade} from './upgrade.mjs';
+import {generateCompressedIndex} from '../../../foundation/agent-docs/agent-docs.mjs';
+
+let tmpDir;
+let originalCwd;
+let logCalls;
+let stdoutCalls;
+let exitCode;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-upgrade-test-'));
+  originalCwd = process.cwd();
+  process.chdir(tmpDir);
+  logCalls = [];
+  stdoutCalls = [];
+  exitCode = undefined;
+  vi.spyOn(console, 'log').mockImplementation((...args) => {
+    logCalls.push(args.join(' '));
+  });
+  vi.spyOn(console, 'error').mockImplementation(() => {});
+  // Some human logs are written straight to process.stdout — capture that too.
+  vi.spyOn(process.stdout, 'write').mockImplementation((chunk) => {
+    stdoutCalls.push(typeof chunk === 'string' ? chunk : chunk.toString());
+    return true;
+  });
+  // jsonError() calls process.exit(1) directly. Trap it so tests can assert.
+  vi.spyOn(process, 'exit').mockImplementation((code) => {
+    exitCode = code;
+    throw new Error(`__exit ${code}`);
+  });
+});
+
+afterEach(() => {
+  process.chdir(originalCwd);
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+  vi.restoreAllMocks();
+});
+
+function createProgram() {
+  const program = new Command();
+  program.exitOverride();
+  // Mirror the global --json flag from src/index.mjs so program.opts().json
+  // resolves the same way in tests.
+  program.option('--json', 'Output as typed JSON');
+  registerUpgrade(program);
+  return program;
+}
+
+function writePkg(deps = {}) {
+  fs.writeFileSync(
+    path.join(tmpDir, 'package.json'),
+    JSON.stringify({name: 'fixture', dependencies: deps}, null, 2),
+  );
+}
+
+function writeInstalledCore(version, packageName = '@astryxdesign/core') {
+  const parts = packageName.split('/');
+  const dir = path.join(tmpDir, 'node_modules', ...parts);
+  fs.mkdirSync(dir, {recursive: true});
+  fs.writeFileSync(
+    path.join(dir, 'package.json'),
+    JSON.stringify({name: packageName, version}, null, 2),
+  );
+}
+
+function writeSourceFile() {
+  fs.mkdirSync(path.join(tmpDir, 'src'), {recursive: true});
+  fs.writeFileSync(path.join(tmpDir, 'src', 'index.ts'), 'const x = 1;\n');
+}
+
+/** Run a command and capture the parsed JSON response (last printed JSON line). */
+async function runJson(args) {
+  const program = createProgram();
+  try {
+    await program.parseAsync(['node', 'astryx', ...args]);
+  } catch (err) {
+    if (!String(err?.message || '').startsWith('__exit')) throw err;
+  }
+  // Find the most recent stringified JSON envelope in console.log output.
+  for (let i = logCalls.length - 1; i >= 0; i--) {
+    const line = logCalls[i];
+    if (line.startsWith('{')) {
+      try {
+        return JSON.parse(line);
+      } catch {
+        // not JSON, keep looking
+      }
+    }
+  }
+  return null;
+}
+
+describe('upgrade gate (semver comparison)', () => {
+  it('does NOT block an upgrade from 0.0.9 to installed 0.0.10 (regression)', async () => {
+    // The original bug: string compare said '0.0.9' >= '0.0.10', so the
+    // gate told users "Already up to date" without --force.
+    writePkg();
+    writeInstalledCore('0.0.10');
+    writeSourceFile();
+
+    const result = await runJson(['--json', 'upgrade', '--from', '0.0.9', '--path', 'src']);
+    expect(result).not.toBeNull();
+    expect(result.type === 'upgrade.run' || result.error || logCalls.some(l => l.includes('No codemods'))).toBeTruthy();
+  });
+
+  it('blocks when --from >= installed target by semver (e.g. 0.0.10 → 0.0.9)', async () => {
+    writePkg();
+    writeInstalledCore('0.0.9');
+    const program = createProgram();
+    await program.parseAsync(['node', 'astryx', 'upgrade', '--from', '0.0.10']);
+    const output = stdoutCalls.join('') + logCalls.join('\n');
+    expect(output).toMatch(/up to date|Already/i);
+  });
+});
+
+describe('upgrade argument validation', () => {
+  it('requires --from for upgrade runs', async () => {
+    writePkg();
+    writeInstalledCore('0.0.15');
+    const result = await runJson(['--json', 'upgrade']);
+    expect(result).not.toBeNull();
+    expect(result.error).toMatch(/Missing required --from/);
+    expect(exitCode).toBe(1);
+  });
+
+  it('rejects bogus --from values', async () => {
+    writePkg();
+    writeInstalledCore('0.0.15');
+    const result = await runJson(['--json', 'upgrade', '--from', 'not-a-version']);
+    expect(result).not.toBeNull();
+    expect(result.error).toMatch(/Invalid --from/);
+    expect(exitCode).toBe(1);
+  });
+
+  it('detects the installed target version from @astryxdesign/core', async () => {
+    writePkg();
+    writeInstalledCore('0.0.15');
+    writeSourceFile();
+    const result = await runJson(['--json', 'upgrade', '--from', '0.0.14', '--path', 'src']);
+    expect(result?.error || '').not.toMatch(/Could not find installed/);
+  });
+});
+
+describe('upgrade --list dedup', () => {
+  it('lists each codemod exactly once', async () => {
+    const result = await runJson(['--json', 'upgrade', '--list']);
+    expect(result).not.toBeNull();
+    expect(result.type).toBe('upgrade.list');
+    const names = result.data.map((c) => c.name);
+    const unique = new Set(names);
+    // The bug: 31 unique codemods printed 9× → 201 entries.
+    expect(names.length).toBe(unique.size);
+  });
+});
+
+// Issue #4168 — `upgrade` must refresh the managed agent-docs block after a
+// version bump, on EVERY path (the block documents the installed library, not
+// the codemod outcome), and must NOT write during a dry run.
+describe('upgrade agent-docs refresh (#4168)', () => {
+  /** Write an agent-doc file with a managed block generated for `version`. */
+  function writeAgentBlock(rel, version) {
+    const filePath = path.join(tmpDir, rel);
+    fs.mkdirSync(path.dirname(filePath), {recursive: true});
+    fs.writeFileSync(filePath, `# Doc\n\n${generateCompressedIndex(version)}\n`);
+  }
+
+  it('refreshes a stale block with --apply, even when there are no codemods (up-to-date path)', async () => {
+    writePkg();
+    writeInstalledCore('0.0.15');
+    writeAgentBlock('AGENTS.md', '0.0.1');
+
+    // --from == installed → up-to-date short-circuit: no codemods run, yet the
+    // stale block must still be brought current. This is the exact gap in #4168.
+    const result = await runJson(['--json', 'upgrade', '--from', '0.0.15', '--apply']);
+
+    expect(result.type).toBe('upgrade.status');
+    expect(result.data.status).toBe('up_to_date');
+    expect(result.data.agentDocs.status).toBe('stale');
+    expect(result.data.agentDocs.action).toBe('refreshed');
+    expect(result.data.agentDocs.refreshed).toBe(true);
+    expect(result.data.agentDocs.fromVersions).toEqual(['0.0.1']);
+    expect(result.data.agentDocs.files).toContain('AGENTS.md');
+
+    const content = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
+    expect(content).toMatch(/Astryx v0\.0\.15 ·/);
+    expect(content).not.toMatch(/Astryx v0\.0\.1 ·/);
+  });
+
+  it('reports a stale block on a dry run WITHOUT writing', async () => {
+    writePkg();
+    writeInstalledCore('0.0.15');
+    writeAgentBlock('AGENTS.md', '0.0.1');
+    const before = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
+
+    const result = await runJson(['--json', 'upgrade', '--from', '0.0.15']); // no --apply
+
+    expect(result.data.agentDocs.status).toBe('stale');
+    expect(result.data.agentDocs.action).toBe('would-refresh');
+    expect(result.data.agentDocs.refreshed).toBe(false);
+    // The file must be untouched by a dry run.
+    expect(fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8')).toBe(before);
+  });
+
+  it('refreshes a stale block on the no-codemods path (--apply)', async () => {
+    writePkg();
+    writeInstalledCore('0.0.11'); // (0.0.10, 0.0.11] has no registered codemods
+    writeSourceFile();
+    writeAgentBlock('CLAUDE.md', '0.0.1');
+
+    const result = await runJson(['--json', 'upgrade', '--from', '0.0.10', '--apply', '--path', 'src']);
+
+    expect(result.type).toBe('upgrade.status');
+    expect(result.data.status).toBe('no_codemods');
+    expect(result.data.agentDocs.refreshed).toBe(true);
+    expect(fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8')).toMatch(/Astryx v0\.0\.11 ·/);
+  });
+
+  it('nudges to run init when core is installed but no managed block exists', async () => {
+    writePkg();
+    writeInstalledCore('0.0.15');
+    // No agent-doc files at all.
+
+    const result = await runJson(['--json', 'upgrade', '--from', '0.0.15', '--apply']);
+
+    expect(result.data.agentDocs.status).toBe('missing');
+    expect(result.data.agentDocs.action).toBe('nudge-init');
+    expect(result.data.agentDocs.refreshed).toBe(false);
+    // Must NOT silently create docs during an upgrade.
+    expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(false);
+    expect(fs.existsSync(path.join(tmpDir, '.claude', 'CLAUDE.md'))).toBe(false);
+  });
+
+  it('treats an agent file without our markers as "never initialized" (missing)', async () => {
+    writePkg();
+    writeInstalledCore('0.0.15');
+    fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '# Agents\n\nHand-written, no astryx block.\n');
+    const before = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
+
+    const result = await runJson(['--json', 'upgrade', '--from', '0.0.15', '--apply']);
+
+    expect(result.data.agentDocs.status).toBe('missing');
+    expect(result.data.agentDocs.action).toBe('nudge-init');
+    // An unmarked file is left exactly as-is.
+    expect(fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8')).toBe(before);
+  });
+
+  it('does not silently no-op a stale block with malformed markers (START without END)', async () => {
+    writePkg();
+    writeInstalledCore('0.0.15');
+    // A corrupted block: START + version header but no matching END marker, so
+    // the writer can't safely splice it. This must not crash, corrupt the file,
+    // or falsely claim success — it should surface an error and nudge re-init.
+    const corrupted =
+      '# A\n\n<!-- ASTRYX:START -->\nAstryx v0.0.1 · 9 components\nguidance, but no end marker\n';
+    fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), corrupted);
+
+    const result = await runJson(['--json', 'upgrade', '--from', '0.0.15', '--apply']);
+
+    expect(result.data.agentDocs.status).toBe('stale');
+    expect(result.data.agentDocs.action).toBe('error');
+    expect(result.data.agentDocs.refreshed).toBe(false);
+    // File left byte-for-byte intact — never corrupted.
+    expect(fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8')).toBe(corrupted);
+  });
+
+  it('stays silent when the block already matches the installed version', async () => {
+    writePkg();
+    writeInstalledCore('0.0.15');
+    writeAgentBlock('AGENTS.md', '0.0.15');
+
+    const result = await runJson(['--json', 'upgrade', '--from', '0.0.15', '--apply']);
+
+    expect(result.data.agentDocs.status).toBe('current');
+    expect(result.data.agentDocs.action).toBe('none');
+    expect(result.data.agentDocs.refreshed).toBe(false);
+  });
+
+  it('migrates a legacy XDS block to the current Astryx block (--apply)', async () => {
+    writePkg();
+    writeInstalledCore('0.0.15');
+    fs.writeFileSync(
+      path.join(tmpDir, 'CLAUDE.md'),
+      '# Claude\n\n<!-- XDS:START -->\nlegacy index\n<!-- XDS:END -->\n\nMore rules.\n',
+    );
+
+    const result = await runJson(['--json', 'upgrade', '--from', '0.0.15', '--apply']);
+
+    expect(result.data.agentDocs.status).toBe('stale');
+    expect(result.data.agentDocs.refreshed).toBe(true);
+    const content = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
+    expect(content).toContain('<!-- ASTRYX:START -->');
+    expect(content).toMatch(/Astryx v0\.0\.15 ·/);
+    expect(content).not.toContain('legacy index');
+    expect(content).toContain('More rules.');
+  });
+
+  it('surfaces agentDocs in the human output on the up-to-date path', async () => {
+    writePkg();
+    writeInstalledCore('0.0.15');
+    writeAgentBlock('AGENTS.md', '0.0.1');
+
+    const program = createProgram();
+    await program.parseAsync(['node', 'astryx', 'upgrade', '--from', '0.0.15', '--apply']);
+    const output = stdoutCalls.join('') + logCalls.join('\n');
+    expect(output).toMatch(/Agent docs refreshed/i);
+  });
+});

package/clients/cli/commands/validate-integration.mjs

@@ -0,0 +1,94 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx validate-integration` command — validate ONE integration
+ * package's manifest and contributions and report findings using the
+ * AstryxIntegrationIssue model.
+ *
+ *   astryx validate-integration            validate the local package (cwd)
+ *   astryx validate-integration <pkg>      validate an installed package
+ *
+ * Exit code is the contract: 0 when there are no severity:'error' issues
+ * (warnings are fine), 1 when any error issue is present — so it works as a CI
+ * gate. The no-arg + no-local-manifest case prints guidance and exits 0 (not
+ * an integration package is not a failure).
+ */
+
+import {jsonOut} from '../../../foundation/response/json.mjs';
+import {emit, section, text, records} from '../formatters/index.mjs';
+import {
+  validateIntegration,
+  summarizeIssues,
+} from '../../../api/integration/validate-integration.mjs';
+
+/**
+ * Render a validation result for humans.
+ * @param {import('../../../api/integration/validate-integration.type.mjs').ValidateIntegrationResponse['data']} data
+ */
+function printHuman(data) {
+  const label =
+    data.version != null ? `${data.name}@${data.version}` : data.name;
+
+  if (data.issues.length === 0) {
+    emit(
+      section(`Validating integration: ${label}`),
+      text('[ok] No issues found.'),
+    );
+    return;
+  }
+
+  // The issue list is a projection of the JSON: one record per issue, fields
+  // mirroring the JSON keys (severity/code/message).
+  const {errors, warnings} = summarizeIssues(data.issues);
+  emit(
+    section(`Validating integration: ${label}`),
+    records(data.issues, {fields: ['severity', 'code', 'message']}),
+    text(
+      `${data.issues.length} issue(s): ${errors} error(s), ${warnings} warning(s)`,
+    ),
+  );
+}
+
+const NO_MANIFEST_GUIDANCE =
+  'No astryx.integration.* found next to package.json. ' +
+  'To validate an installed integration: astryx validate-integration <package>';
+
+/**
+ * Register the `astryx validate-integration` command.
+ * @param {import('commander').Command} program
+ */
+export function registerValidateIntegration(program) {
+  program
+    .command('validate-integration [package]')
+    .description(
+      'Validate an Astryx integration package (manifest + contributions)',
+    )
+    .addHelpText(
+      'after',
+      '\nWith no argument, validates the integration package rooted at the\n' +
+        'current directory. Pass a package name to validate an installed\n' +
+        'integration resolved from ./node_modules.\n\n' +
+        'Exit code:\n' +
+        '  0  no error issues (warnings are allowed) — safe as a CI gate\n' +
+        '  1  one or more error issues\n',
+    )
+    .action(async pkg => {
+      const json = program.opts().json || false;
+
+      const result = await validateIntegration(pkg);
+
+      if (json) {
+        jsonOut(result);
+      } else if (result.data.name === null) {
+        // No-arg + no local manifest: guidance, not an error.
+        emit(text(NO_MANIFEST_GUIDANCE));
+      } else {
+        printHuman(result.data);
+      }
+
+      const {errors} = summarizeIssues(result.data.issues);
+      if (errors > 0) {
+        process.exitCode = 1;
+      }
+    });
+}

package/clients/cli/e2e-smoke.test.mjs

@@ -0,0 +1,96 @@
+// 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/clients/cli/error-envelope-code.test.mjs

@@ -0,0 +1,38 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Static regression: every inline JSON error envelope constructed in
+ * cli/index.mjs carries a `code` field.
+ *
+ * The JSON contract guarantees `code` always appears on an error envelope so
+ * consumers can branch on it unconditionally. Most error envelopes flow through
+ * `toErrorEnvelope`/`cliError` (which always set a code), but cli/index.mjs
+ * hand-builds two envelopes (the --json gate rejection and the postAction
+ * "completed without emitting an envelope" fallback). This scan catches a new
+ * hand-built envelope that forgets `code`.
+ */
+
+import {describe, it, expect} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+describe('inline JSON error envelopes carry a `code`', () => {
+  it('cli/index.mjs — no hand-built error envelope missing code', () => {
+    const file = path.resolve(HERE, 'index.mjs');
+    const lines = fs.readFileSync(file, 'utf-8').split('\n');
+    const offenders = [];
+    lines.forEach((ln, i) => {
+      if (/^\s*error:/.test(ln)) {
+        const windowText = lines.slice(Math.max(0, i - 4), i + 6).join('\n');
+        if (!/\bcode:/.test(windowText)) offenders.push(i + 1);
+      }
+    });
+    expect(
+      offenders,
+      `index.mjs error envelope(s) missing code at line(s) ${offenders.join(', ')}`,
+    ).toEqual([]);
+  });
+});