@astryxdesign/cli 0.1.7 → 0.1.8-canary.07362a9

package/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 '../../lib/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/{src → cli}/commands/validate-integration.mjs

@@ -14,37 +14,34 @@
  * an integration package is not a failure).
  */
 
-import {jsonOut, humanLog} from '../lib/json.mjs';
+import {jsonOut, humanLog} from '../../lib/json.mjs';
 import {
-  validateLocalIntegration,
-  validateInstalledIntegration,
+  validateIntegration,
   summarizeIssues,
-} from '../api/validate-integration.mjs';
+} from '../../api/integration/validate-integration.mjs';
 
 /**
  * Render a validation result for humans.
- * @param {import('../api/validate-integration.mjs').ValidateResult} result
+ * @param {import('../../types/validate-integration').ValidateIntegrationResponse['data']} data
  */
-function printHuman(result) {
+function printHuman(data) {
   const label =
-    result.version != null
-      ? `${result.name}@${result.version}`
-      : result.name;
+    data.version != null ? `${data.name}@${data.version}` : data.name;
   humanLog(`Validating integration: ${label}`);
 
-  if (result.issues.length === 0) {
+  if (data.issues.length === 0) {
     humanLog('\n\u2713 No issues found.');
     return;
   }
 
   humanLog('');
-  for (const issue of result.issues) {
+  for (const issue of data.issues) {
     humanLog(`  ${issue.severity} ${issue.code}: ${issue.message}`);
   }
 
-  const {errors, warnings} = summarizeIssues(result.issues);
+  const {errors, warnings} = summarizeIssues(data.issues);
   humanLog(
-    `\n${result.issues.length} issue(s): ${errors} error(s), ${warnings} warning(s)`,
+    `\n${data.issues.length} issue(s): ${errors} error(s), ${warnings} warning(s)`,
   );
 }
 
@@ -74,35 +71,18 @@ export function registerValidateIntegration(program) {
     .action(async pkg => {
       const json = program.opts().json || false;
 
-      const result = pkg
-        ? await validateInstalledIntegration(pkg)
-        : await validateLocalIntegration();
-
-      // No-arg + no local manifest: guidance, not an error.
-      if (!result.found) {
-        if (json) {
-          jsonOut('integration.validate', {
-            name: null,
-            version: null,
-            issues: [],
-          });
-        } else {
-          humanLog(NO_MANIFEST_GUIDANCE);
-        }
-        return;
-      }
+      const result = await validateIntegration(pkg);
 
       if (json) {
-        jsonOut('integration.validate', {
-          name: result.name ?? null,
-          version: result.version ?? null,
-          issues: result.issues,
-        });
+        jsonOut(result.type, result.data);
+      } else if (result.data.name === null) {
+        // No-arg + no local manifest: guidance, not an error.
+        humanLog(NO_MANIFEST_GUIDANCE);
       } else {
-        printHuman(result);
+        printHuman(result.data);
       }
 
-      const {errors} = summarizeIssues(result.issues);
+      const {errors} = summarizeIssues(result.data.issues);
       if (errors > 0) {
         process.exitCode = 1;
       }

package/{src → cli}/index.mjs

@@ -11,14 +11,15 @@ 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 {getRunPrefix} 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 {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));
 
@@ -55,6 +56,7 @@ export const JSON_SUPPORTED = new Set([
   'docs',
   'discover',
   'search',
+  'build',
   'swizzle',
   'template',
   'hook',
@@ -101,7 +103,7 @@ program
     if (extras.length > 0) {
       const unknown = String(extras[0]);
       const known = (program.commands || [])
-        .filter((c) => !c._hidden && c.name() !== 'help')
+        .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())}))
@@ -161,6 +163,7 @@ program
  */
 function fullCommandName(actionCommand) {
   const parts = [];
+  /** @type {import('commander').Command | null} */
   let cmd = actionCommand;
   while (cmd && cmd !== program) {
     parts.unshift(cmd.name());
@@ -174,7 +177,7 @@ function fullCommandName(actionCommand) {
  *
  * 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 clack prompts, no spawned processes).
+ * 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
@@ -237,6 +240,40 @@ program.hook('postAction', (thisCommand, actionCommand) => {
   }
 });
 
+/**
+ * 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).
+ */
+const SETUP_NUDGE_EXEMPT = new Set(['init', 'agent-docs']);
+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.
+  }
+});
+
 /**
  * Command registry — each command is lazy-loaded so a broken command
  * doesn't take down the entire CLI.
@@ -272,10 +309,10 @@ for (const cmd of commands) {
     // Command fails to load but CLI still works
     program
       .command(cmd.name)
-      .description(`(failed to load: ${e.message})`)
+      .description(`(failed to load: ${/** @type {any} */ (e).message})`)
       .action(() => {
         console.error(`Command "${cmd.name}" failed to load:`);
-        console.error(e.message);
+        console.error(/** @type {any} */ (e).message);
         process.exit(1);
       });
   }
@@ -305,25 +342,24 @@ program
       console.log(`  ${c.name}${tag}`);
       if (c.description) console.log(`    ${c.description}`);
     }
-    console.log(`\nRun \`astryx manifest --json\` for the full structured manifest.\n`);
+    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 run = getRunPrefix();
-    const r = `${run} xds`;
-    const pad = (s, len) => s + ' '.repeat(Math.max(0, len - s.length));
+    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 = (s) => `  │ ${pad(s, W)}│`;
+    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          Interactive setup`)}
+${line(`    ${r} init          Setup + AI agent docs`)}
 ${line(`    ${r} --help        See all commands`)}
 ${line('')}
 ${line('  Or run directly:')}
@@ -342,5 +378,5 @@ ${line('')}
 // 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/src/lib/json-shim.mjs for the rationale.
+// See packages/cli/lib/json-shim.mjs for the rationale.
 installJsonShim(program);

package/{src/codemods → codemods}/__tests__/registry.test.mjs

@@ -21,6 +21,7 @@ describe('registry', () => {
         '0.1.3',
         '0.1.5',
         '0.1.7',
+        '0.1.8',
       ]);
     });
   });

package/{src/codemods → codemods}/ensure-jscodeshift.mjs

@@ -3,16 +3,15 @@
 /**
  * @file Lazy jscodeshift installer
  *
- * Checks if jscodeshift is available and offers to install it on-demand.
+ * Checks if jscodeshift is available and installs it on-demand.
  * Keeps the CLI lean — jscodeshift is only needed for codemods.
  *
- * In non-interactive environments (CI, LLM agents), the interactive prompt
- * is skipped. Pass `installDeps: true` to auto-install without prompting,
- * or the command will fail with a helpful error message.
+ * Non-interactive by default (no prompts): pass `installDeps: true` to
+ * auto-install, otherwise the command fails fast with a helpful error.
  */
 
 import {execSync} from 'node:child_process';
-import * as p from '@clack/prompts';
+import * as p from '../lib/term-log.mjs';
 import {detectPackageManager} from '../utils/package-manager.mjs';
 
 /**
@@ -30,32 +29,17 @@ export async function ensureJscodeshift({installDeps = false, silent = false} =
   } catch {
     log.warn('jscodeshift is required for codemods but not installed.');
 
-    const isInteractive = process.stdout.isTTY && !process.env.CI;
-
     if (installDeps) {
-      // Explicit opt-in — install without prompting
+      // Explicit opt-in — install without prompting.
       return installJscodeshift(silent);
     }
 
-    if (!isInteractive || silent) {
-      // Non-interactive environment (or --json) — fail fast with a helpful message
-      log.error(
-        'Cannot run codemods without jscodeshift. ' +
-          'Use --install-deps to auto-install in non-interactive environments.',
-      );
-      return false;
-    }
-
-    // Interactive TTY — prompt as before
-    const shouldInstall = await p.confirm({
-      message: 'Install jscodeshift now?',
-      initialValue: true,
-    });
-    if (p.isCancel(shouldInstall) || !shouldInstall) {
-      p.log.error('Cannot run codemods without jscodeshift.');
-      return false;
-    }
-    return installJscodeshift(silent);
+    // Non-interactive by default: fail fast with a helpful message instead of
+    // prompting (the CLI never blocks on a TTY).
+    log.error(
+      'Cannot run codemods without jscodeshift. Use --install-deps to auto-install.',
+    );
+    return false;
   }
 }
 
@@ -80,7 +64,7 @@ function installJscodeshift(silent = false) {
     log.success('jscodeshift installed.');
     return true;
   } catch (err) {
-    log.error(`Failed to install jscodeshift: ${err.message}`);
+    log.error(`Failed to install jscodeshift: ${/** @type {any} */ (err).message}`);
     return false;
   }
 }

package/{src/codemods → codemods}/integration-discovery.mjs

@@ -27,7 +27,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {loadModuleWithSchema} from '../lib/module-loader.mjs';
-import {CodemodEnvelopeSchema} from '../codemod.mjs';
+import {CodemodEnvelopeSchema} from '../authoring/codemod.mjs';
 import {semverCompare} from '../utils/semver.mjs';
 
 /** File extensions recognized as codemod modules. */
@@ -41,6 +41,7 @@ const CODEMOD_EXTENSIONS = ['.ts', '.mjs', '.js'];
  * @returns {Array<{id: string, file: string}>}
  */
 function collectCodemodFiles(versionDir) {
+  /** @type {Array<{id: string, file: string}>} */
   const out = [];
 
   /** @param {string} dir */
@@ -74,7 +75,7 @@ function collectCodemodFiles(versionDir) {
  *   for that version (across all integrations).
  */
 export async function discoverIntegrationCodemods(loadedIntegrations = []) {
-  /** @type {Map<string, Array<{id: string, type: string, codemod: object, package: string}>>} */
+  /** @type {Map<string, Array<{id: string, type: 'code'|'config', codemod: object, package: string}>>} */
   const byVersion = new Map();
 
   for (const integration of loadedIntegrations ?? []) {
@@ -158,10 +159,12 @@ export async function discoverIntegrationCodemods(loadedIntegrations = []) {
  */
 export function selectIntegrationCodemods(byVersion, from, to) {
   const versions = [...byVersion.keys()].sort(semverCompare);
+  /** @type {Array<{version: string, codemods: Array<object>}>} */
   const results = [];
   for (const version of versions) {
     if (semverCompare(version, from) > 0 && semverCompare(version, to) <= 0) {
-      results.push({version, codemods: byVersion.get(version)});
+      const codemods = byVersion.get(version);
+      if (codemods) results.push({version, codemods});
     }
   }
   return results;