@delegance/claude-autopilot 1.1.0 → 1.2.1

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.2.0] — 2026-04-21
+
+### Added
+- `autopilot doctor` — prerequisite checker: verifies Node 22+, tsx, gh CLI auth, claude CLI, OPENAI_API_KEY, git config, superpowers plugin; shows exact fix command for each failure; exits 1 if any blockers
+- `autopilot setup` now runs `doctor` automatically at the end so users immediately see what still needs attention
+- `autopilot preflight` kept as alias for `doctor`
+
 ## [1.1.0] — 2026-04-21
 
 ### Added

package/README.md

@@ -94,9 +94,17 @@ npx autopilot init
 
 Available presets: `nextjs-supabase`, `t3`, `python-fastapi`, `rails-postgres`, `go`.
 
-### `autopilot preflight`
+### `autopilot doctor`
 
-Checks prerequisites (Node version, `gh` CLI auth, `OPENAI_API_KEY`).
+Checks prerequisites and shows exact fix commands for each failure.
+
+```bash
+npx autopilot doctor    # Check prerequisites and show exact fix commands
+```
+
+Verifies: Node 22+, tsx, gh CLI auth, claude CLI, OPENAI_API_KEY, git user config, superpowers plugin. Exits 1 if any blockers are found. Also runs automatically at the end of `autopilot setup`.
+
+`autopilot preflight` is kept as an alias for `doctor`.
 
 ## GitHub Actions
 

package/bin/autopilot.js

@@ -1,15 +1,20 @@
 #!/usr/bin/env node
-// Thin launcher that uses tsx to run the TypeScript CLI entry point.
-// This is what `npx autopilot` resolves to — it hands off to tsx so TypeScript
-// source can execute without a separate build step during alpha.
-import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
 import * as path from 'node:path';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const tsxBin = path.resolve(__dirname, '..', 'node_modules', '.bin', 'tsx');
 const entrypoint = path.resolve(__dirname, '..', 'src', 'cli', 'index.ts');
 
-const result = spawnSync(tsxBin, [entrypoint, ...process.argv.slice(2)], { stdio: 'inherit' });
+// Locate tsx: own node_modules (dev) → consumer's node_modules/.bin → PATH
+function findTsx() {
+  const own = path.resolve(__dirname, '..', 'node_modules', '.bin', 'tsx');
+  if (fs.existsSync(own)) return own;
+  const consumer = path.resolve(__dirname, '..', '..', '..', '.bin', 'tsx');
+  if (fs.existsSync(consumer)) return consumer;
+  return 'tsx';
+}
+
+const result = spawnSync(findTsx(), [entrypoint, ...process.argv.slice(2)], { stdio: 'inherit' });
 process.exit(result.status ?? 1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delegance/claude-autopilot",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "type": "module",
   "description": "Claude Code automation pipeline: spec \u2192 plan \u2192 implement \u2192 validate \u2192 PR",
   "keywords": [

package/src/cli/detector.ts

@@ -24,10 +24,14 @@ function fileContains(filePath: string, needle: string): boolean {
   }
 }
 
+const DEFAULT_TEST_PLACEHOLDER = /^echo .error: no test specified/i;
+
 function nodeTestCommand(cwd: string): string {
   const pkg = readJson(path.join(cwd, 'package.json'));
   const scripts = pkg?.['scripts'] as Record<string, string> | undefined;
-  return scripts?.['test'] ?? 'npm test';
+  const cmd = scripts?.['test'];
+  if (!cmd || DEFAULT_TEST_PLACEHOLDER.test(cmd)) return 'npm test';
+  return cmd;
 }
 
 export function detectProject(cwd: string): DetectionResult {

package/src/cli/index.ts

@@ -8,16 +8,17 @@
  *   autopilot run --base main   diff against a specific branch
  *   autopilot run --dry-run     show what would run, no execution
  *   autopilot watch             re-run pipeline on every file save (debounced)
- *   autopilot preflight         check prerequisites
+ *   autopilot doctor            check prerequisites (alias: preflight)
  */
 import { runInit } from './init.ts';
 import { runCommand } from './run.ts';
 import { runWatch } from './watch.ts';
 import { runSetup } from './setup.ts';
+import { runDoctor } from './preflight.ts';
 
 const args = process.argv.slice(2);
 
-const SUBCOMMANDS = ['init', 'run', 'watch', 'hook', 'autoregress', 'preflight', 'setup', 'help', '--help', '-h'] as const;
+const SUBCOMMANDS = ['init', 'run', 'watch', 'hook', 'autoregress', 'doctor', 'preflight', 'setup', 'help', '--help', '-h'] as const;
 const VALUE_FLAGS = ['base', 'config', 'files', 'format', 'output', 'debounce'];
 
 // Detect first non-flag arg as subcommand, default to 'run'
@@ -47,7 +48,7 @@ Commands:
   run          Run the pipeline on git-changed files (default)
   watch        Watch for file changes and re-run pipeline on each save
   init         Scaffold autopilot.config.yaml from a preset
-  preflight    Check prerequisites
+  doctor       Check prerequisites and show exact fix commands (alias: preflight)
   autoregress  Run snapshot regression tests (run|diff|update|generate)
 
 Options (run):
@@ -75,9 +76,12 @@ switch (subcommand) {
     await runInit(process.cwd());
     break;
 
-  case 'preflight':
-    await import('./preflight.ts');
+  case 'doctor':
+  case 'preflight': {
+    const result = await runDoctor();
+    process.exit(result.blockers > 0 ? 1 : 0);
     break;
+  }
 
   case 'help':
   case '--help':

package/src/cli/preflight.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { runSafe } from '../core/shell.ts';
 
 const PASS = '\x1b[32m✓\x1b[0m';
@@ -30,125 +31,140 @@ function loadEnvFile(filePath: string): Record<string, string> {
   return vars;
 }
 
-const checks: Check[] = [];
-
-// 1. Node version
-const nodeVersion = process.version;
-const nodeMajor = parseInt(nodeVersion.slice(1).split('.')[0]!, 10);
-checks.push({
-  name: `Node.js ${nodeVersion}`,
-  result: nodeMajor >= 22 ? 'pass' : 'fail',
-  message: nodeMajor < 22 ? `Node 22+ required — current: ${nodeVersion}. Install via nvm: nvm install 22` : undefined,
-});
-
-// 2. tsx available
-const localTsx = path.join(process.cwd(), 'node_modules', '.bin', 'tsx');
-const tsxVersion = fs.existsSync(localTsx)
-  ? runSafe(localTsx, ['--version'])
-  : runSafe('tsx', ['--version']);
-checks.push({
-  name: 'tsx available',
-  result: tsxVersion ? 'pass' : 'fail',
-  message: !tsxVersion ? 'tsx not found — run: npm install @delegance/claude-autopilot (includes tsx)' : undefined,
-});
-
-// 3. gh CLI authenticated
-const ghAuth = runSafe('gh', ['auth', 'status']);
-checks.push({
-  name: 'gh CLI authenticated',
-  result: ghAuth !== null ? 'pass' : 'fail',
-  message: ghAuth === null ? 'gh CLI not authenticated — run: gh auth login' : undefined,
-});
-
-// 4. autopilot.config.yaml in cwd
-const configYaml = path.join(process.cwd(), 'autopilot.config.yaml');
-checks.push({
-  name: 'autopilot.config.yaml',
-  result: fs.existsSync(configYaml) ? 'pass' : 'warn',
-  message: !fs.existsSync(configYaml)
-    ? 'autopilot.config.yaml not found in current directory — copy from a preset: presets/nextjs-supabase/autopilot.config.yaml'
-    : undefined,
-});
-
-// 5. Local env file exists
-const envFile = ENV_CANDIDATES.find(f => fs.existsSync(f));
-checks.push({
-  name: `Local env file (${envFile ?? 'none found'})`,
-  result: envFile ? 'pass' : 'warn',
-  message: !envFile
-    ? `No env file found. Looked for: ${ENV_CANDIDATES.join(', ')}. Create one with your OPENAI_API_KEY.`
-    : undefined,
-});
-
-// 6. OPENAI_API_KEY set
-const envVars = envFile ? loadEnvFile(envFile) : {};
-const hasOpenAI = !!process.env.OPENAI_API_KEY || !!envVars['OPENAI_API_KEY'];
-checks.push({
-  name: 'OPENAI_API_KEY',
-  result: hasOpenAI ? 'pass' : 'warn',
-  message: !hasOpenAI
-    ? `OPENAI_API_KEY not set — Codex review steps will be skipped`
-    : undefined,
-});
-
-// 7. claude CLI available
-const claudeVersion = runSafe('claude', ['--version']);
-checks.push({
-  name: 'claude CLI',
-  result: claudeVersion ? 'pass' : 'fail',
-  message: !claudeVersion
-    ? 'claude CLI not found — required for autofix. Install Claude Code: https://claude.ai/claude-code'
-    : undefined,
-});
-
-// 8. git user config
-const gitName = runSafe('git', ['config', 'user.name']);
-const gitEmail = runSafe('git', ['config', 'user.email']);
-const gitConfigOk = !!(gitName?.trim()) && !!(gitEmail?.trim());
-checks.push({
-  name: 'git user config',
-  result: gitConfigOk ? 'pass' : 'warn',
-  message: !gitConfigOk
-    ? 'git user.name / user.email not set — commits will fail.'
-    : undefined,
-});
-
-// 9. superpowers plugin
-const home = process.env.HOME ?? '';
-const superpowersPaths = [
-  path.join(home, '.claude', 'plugins', 'cache', 'claude-plugins-official', 'superpowers'),
-  path.join(home, '.claude', 'plugins', 'cache', 'superpowers-marketplace', 'superpowers'),
-  path.join(home, '.claude', 'plugins', 'superpowers'),
-];
-const superpowersOk = superpowersPaths.some(p => fs.existsSync(p));
-checks.push({
-  name: 'superpowers plugin',
-  result: superpowersOk ? 'pass' : 'warn',
-  message: !superpowersOk
-    ? 'superpowers plugin not detected — install: /plugin install superpowers@claude-plugins-official'
-    : undefined,
-});
-
-// Print results
-console.log('\n\x1b[1m[preflight] Autopilot prerequisite check\x1b[0m\n');
-let failures = 0;
-let warnings = 0;
-for (const check of checks) {
-  const icon = check.result === 'pass' ? PASS : check.result === 'warn' ? WARN : FAIL;
-  console.log(`  ${icon}  ${check.name}`);
-  if (check.message) {
-    console.log(`       \x1b[2m${check.message}\x1b[0m`);
+export interface DoctorResult {
+  blockers: number;
+  warnings: number;
+}
+
+export async function runDoctor(): Promise<DoctorResult> {
+  const checks: Check[] = [];
+
+  // 1. Node version
+  const nodeVersion = process.version;
+  const nodeMajor = parseInt(nodeVersion.slice(1).split('.')[0]!, 10);
+  checks.push({
+    name: `Node.js ${nodeVersion}`,
+    result: nodeMajor >= 22 ? 'pass' : 'fail',
+    message: nodeMajor < 22 ? `Node 22+ required — current: ${nodeVersion}. Install via nvm: nvm install 22` : undefined,
+  });
+
+  // 2. tsx available
+  const localTsx = path.join(process.cwd(), 'node_modules', '.bin', 'tsx');
+  const tsxVersion = fs.existsSync(localTsx)
+    ? runSafe(localTsx, ['--version'])
+    : runSafe('tsx', ['--version']);
+  checks.push({
+    name: 'tsx available',
+    result: tsxVersion ? 'pass' : 'fail',
+    message: !tsxVersion ? 'tsx not found — run: npm install @delegance/claude-autopilot (includes tsx)' : undefined,
+  });
+
+  // 3. gh CLI authenticated
+  const ghAuth = runSafe('gh', ['auth', 'status']);
+  checks.push({
+    name: 'gh CLI authenticated',
+    result: ghAuth !== null ? 'pass' : 'fail',
+    message: ghAuth === null ? 'gh CLI not authenticated — run: gh auth login' : undefined,
+  });
+
+  // 4. autopilot.config.yaml in cwd
+  const configYaml = path.join(process.cwd(), 'autopilot.config.yaml');
+  checks.push({
+    name: 'autopilot.config.yaml',
+    result: fs.existsSync(configYaml) ? 'pass' : 'warn',
+    message: !fs.existsSync(configYaml)
+      ? 'autopilot.config.yaml not found in current directory — copy from a preset: presets/nextjs-supabase/autopilot.config.yaml'
+      : undefined,
+  });
+
+  // 5. Local env file exists
+  const envFile = ENV_CANDIDATES.find(f => fs.existsSync(f));
+  checks.push({
+    name: `Local env file (${envFile ?? 'none found'})`,
+    result: envFile ? 'pass' : 'warn',
+    message: !envFile
+      ? `No env file found. Looked for: ${ENV_CANDIDATES.join(', ')}. Create one with your OPENAI_API_KEY.`
+      : undefined,
+  });
+
+  // 6. OPENAI_API_KEY set
+  const envVars = envFile ? loadEnvFile(envFile) : {};
+  const hasOpenAI = !!process.env.OPENAI_API_KEY || !!envVars['OPENAI_API_KEY'];
+  checks.push({
+    name: 'OPENAI_API_KEY',
+    result: hasOpenAI ? 'pass' : 'warn',
+    message: !hasOpenAI
+      ? `OPENAI_API_KEY not set — Codex review steps will be skipped`
+      : undefined,
+  });
+
+  // 7. claude CLI available
+  const claudeVersion = runSafe('claude', ['--version']);
+  checks.push({
+    name: 'claude CLI',
+    result: claudeVersion ? 'pass' : 'fail',
+    message: !claudeVersion
+      ? 'claude CLI not found — required for autofix. Install Claude Code: https://claude.ai/claude-code'
+      : undefined,
+  });
+
+  // 8. git user config
+  const gitName = runSafe('git', ['config', 'user.name']);
+  const gitEmail = runSafe('git', ['config', 'user.email']);
+  const gitConfigOk = !!(gitName?.trim()) && !!(gitEmail?.trim());
+  checks.push({
+    name: 'git user config',
+    result: gitConfigOk ? 'pass' : 'warn',
+    message: !gitConfigOk
+      ? 'git user.name / user.email not set — commits will fail.'
+      : undefined,
+  });
+
+  // 9. superpowers plugin
+  const home = process.env.HOME ?? '';
+  const superpowersPaths = [
+    path.join(home, '.claude', 'plugins', 'cache', 'claude-plugins-official', 'superpowers'),
+    path.join(home, '.claude', 'plugins', 'cache', 'superpowers-marketplace', 'superpowers'),
+    path.join(home, '.claude', 'plugins', 'superpowers'),
+  ];
+  const superpowersOk = superpowersPaths.some(p => fs.existsSync(p));
+  checks.push({
+    name: 'superpowers plugin',
+    result: superpowersOk ? 'pass' : 'warn',
+    message: !superpowersOk
+      ? 'superpowers plugin not detected — install: /plugin install superpowers@claude-plugins-official'
+      : undefined,
+  });
+
+  // Print results
+  console.log('\n\x1b[1m[doctor] Autopilot prerequisite check\x1b[0m\n');
+  let blockers = 0;
+  let warnings = 0;
+  for (const check of checks) {
+    const icon = check.result === 'pass' ? PASS : check.result === 'warn' ? WARN : FAIL;
+    console.log(`  ${icon}  ${check.name}`);
+    if (check.message) {
+      console.log(`       \x1b[2m${check.message}\x1b[0m`);
+    }
+    if (check.result === 'fail') blockers++;
+    if (check.result === 'warn') warnings++;
   }
-  if (check.result === 'fail') failures++;
-  if (check.result === 'warn') warnings++;
+
+  console.log('');
+  if (blockers > 0) {
+    console.log(`\x1b[31m[doctor] ${blockers} blocker(s) — fix before running npx autopilot run\x1b[0m\n`);
+  } else if (warnings > 0) {
+    console.log(`\x1b[33m[doctor] ${warnings} warning(s) — pipeline will run but some steps may be skipped\x1b[0m\n`);
+  } else {
+    console.log(`\x1b[32m[doctor] All checks passed — ready to run\x1b[0m\n`);
+  }
+
+  return { blockers, warnings };
 }
 
-console.log('');
-if (failures > 0) {
-  console.log(`\x1b[31m[preflight] ${failures} check(s) failed — fix before running /autopilot\x1b[0m\n`);
-  process.exit(1);
-} else if (warnings > 0) {
-  console.log(`\x1b[33m[preflight] ${warnings} warning(s) — pipeline will run but some steps may be degraded\x1b[0m\n`);
-} else {
-  console.log(`\x1b[32m[preflight] All checks passed\x1b[0m\n`);
+// Run when invoked directly
+const isMain = process.argv[1] !== undefined &&
+  fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);
+if (isMain) {
+  runDoctor().then(r => process.exit(r.blockers > 0 ? 1 : 0));
 }

package/src/cli/setup.ts

@@ -4,6 +4,7 @@ import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { detectProject } from './detector.ts';
 import { runHook } from './hook.ts';
+import { runDoctor } from './preflight.ts';
 
 const PASS = '\x1b[32m✓\x1b[0m';
 const WARN = '\x1b[33m!\x1b[0m';
@@ -77,5 +78,8 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
     }
   }
 
+  console.log('\n[setup] Checking prerequisites...');
+  await runDoctor();
+
   console.log('\n[setup] Done. Run: npx autopilot run\n');
 }