@delegance/claude-autopilot 1.0.2 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # 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
+- `autopilot setup` — zero-prompt setup: auto-detects project type (Go, Rails, FastAPI, T3, Next.js+Supabase), infers test command, writes config, installs git hook in one command
+- `autopilot setup --force` — overwrite existing config
+
 ## [1.0.2] — 2026-04-21
 
 ### Fixed

package/README.md

@@ -13,19 +13,15 @@ Requires Node 22+. Also requires `gh` CLI authenticated and `claude` CLI install
 ## Quick Start
 
 ```bash
-# Scaffold config
-npx autopilot init
+# One command — auto-detects project type, writes config, installs hook
+npx autopilot setup
 
-# Run on changed files
+# Then run your first pipeline
 npx autopilot run
-
-# Watch mode (re-runs on every file save)
-npx autopilot watch
-
-# Install pre-push hook
-npx autopilot hook install
 ```
 
+Requires Node 22+, `gh` CLI authenticated, `claude` CLI (Claude Code).
+
 ## Commands
 
 ### `autopilot run`
@@ -77,6 +73,17 @@ npx autopilot autoregress generate --files src/foo.ts,src/bar.ts
 
 Requires `OPENAI_API_KEY` for `generate` mode.
 
+### `autopilot setup`
+
+Zero-prompt setup: auto-detects project type, writes config, installs git hook in one command.
+
+```bash
+npx autopilot setup            # Auto-detect project, write config, install hook
+npx autopilot setup --force    # Overwrite existing autopilot.config.yaml
+```
+
+Auto-detection supports: Go, Rails, FastAPI, T3, Next.js+Supabase.
+
 ### `autopilot init`
 
 Scaffolds `autopilot.config.yaml` from a preset.
@@ -87,9 +94,17 @@ npx autopilot init
 
 Available presets: `nextjs-supabase`, `t3`, `python-fastapi`, `rails-postgres`, `go`.
 
-### `autopilot preflight`
+### `autopilot doctor`
+
+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`.
 
-Checks prerequisites (Node version, `gh` CLI auth, `OPENAI_API_KEY`).
+`autopilot preflight` is kept as an alias for `doctor`.
 
 ## GitHub Actions
 

package/package.json

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

package/src/cli/detector.ts

@@ -0,0 +1,72 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export interface DetectionResult {
+  preset: string;
+  testCommand: string;
+  confidence: 'high' | 'low';
+  evidence: string;
+}
+
+function readJson(filePath: string): Record<string, unknown> | null {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function fileContains(filePath: string, needle: string): boolean {
+  try {
+    return fs.readFileSync(filePath, 'utf8').includes(needle);
+  } catch {
+    return false;
+  }
+}
+
+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';
+}
+
+export function detectProject(cwd: string): DetectionResult {
+  if (fs.existsSync(path.join(cwd, 'go.mod'))) {
+    return { preset: 'go', testCommand: 'go test ./...', confidence: 'high', evidence: 'found go.mod' };
+  }
+
+  const gemfile = path.join(cwd, 'Gemfile');
+  if (fs.existsSync(gemfile) && fileContains(gemfile, 'rails')) {
+    return { preset: 'rails-postgres', testCommand: 'bundle exec rails test', confidence: 'high', evidence: "found Gemfile with 'rails'" };
+  }
+
+  const reqTxt = path.join(cwd, 'requirements.txt');
+  const pyproject = path.join(cwd, 'pyproject.toml');
+  if ((fs.existsSync(reqTxt) && fileContains(reqTxt, 'fastapi')) ||
+      (fs.existsSync(pyproject) && fileContains(pyproject, 'fastapi'))) {
+    return { preset: 'python-fastapi', testCommand: 'pytest', confidence: 'high', evidence: 'found fastapi in requirements' };
+  }
+
+  const pkgPath = path.join(cwd, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    const pkg = readJson(pkgPath);
+    const deps = {
+      ...(pkg?.['dependencies'] as Record<string, string> ?? {}),
+      ...(pkg?.['devDependencies'] as Record<string, string> ?? {}),
+    };
+    const testCmd = nodeTestCommand(cwd);
+
+    if ('@trpc/server' in deps) {
+      return { preset: 't3', testCommand: testCmd, confidence: 'high', evidence: 'found @trpc/server in package.json' };
+    }
+    if ('next' in deps && '@supabase/supabase-js' in deps) {
+      return { preset: 'nextjs-supabase', testCommand: testCmd, confidence: 'high', evidence: 'found next + @supabase/supabase-js in package.json' };
+    }
+    if ('next' in deps) {
+      return { preset: 'nextjs-supabase', testCommand: testCmd, confidence: 'low', evidence: 'found next in package.json (no supabase detected)' };
+    }
+    return { preset: 'nextjs-supabase', testCommand: testCmd, confidence: 'low', evidence: 'found package.json (no strong framework signals)' };
+  }
+
+  return { preset: 'nextjs-supabase', testCommand: 'npm test', confidence: 'low', evidence: 'no project signals found — using default preset' };
+}

package/src/cli/index.ts

@@ -8,15 +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', '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'
@@ -46,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):
@@ -74,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':
@@ -141,6 +146,12 @@ switch (subcommand) {
     break;
   }
 
+  case 'setup': {
+    const force = args.includes('--force');
+    await runSetup({ force });
+    break;
+  }
+
   default:
     console.error(`\x1b[31m[autopilot] Unknown subcommand: "${subcommand}"\x1b[0m`);
     printUsage();

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

@@ -0,0 +1,85 @@
+import * as fs from 'node:fs';
+import * as fsAsync from 'node:fs/promises';
+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';
+
+const PRESET_LABELS: Record<string, string> = {
+  'nextjs-supabase': 'Next.js + Supabase',
+  't3': 'T3 Stack (Next.js + tRPC + Prisma)',
+  'rails-postgres': 'Ruby on Rails + PostgreSQL',
+  'python-fastapi': 'Python FastAPI',
+  'go': 'Go + PostgreSQL',
+};
+
+export interface SetupOptions {
+  cwd?: string;
+  force?: boolean;
+  skipHook?: boolean;
+}
+
+function presetSearchPaths(name: string, cwd: string): string[] {
+  const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+  return [
+    path.join(pkgRoot, 'presets', name, 'autopilot.config.yaml'),
+    path.join(cwd, 'node_modules', '@delegance', 'claude-autopilot', 'presets', name, 'autopilot.config.yaml'),
+  ];
+}
+
+function findPresetConfig(name: string, cwd: string): string | null {
+  for (const p of presetSearchPaths(name, cwd)) {
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+export async function runSetup(options: SetupOptions = {}): Promise<void> {
+  const cwd = options.cwd ?? process.cwd();
+  const dest = path.join(cwd, 'autopilot.config.yaml');
+
+  if (fs.existsSync(dest) && !options.force) {
+    throw new Error('autopilot.config.yaml already exists — use --force to overwrite');
+  }
+
+  console.log('\n[setup] Detecting project type...');
+
+  const detection = detectProject(cwd);
+  const label = PRESET_LABELS[detection.preset] ?? detection.preset;
+
+  if (detection.confidence === 'high') {
+    console.log(`  ${PASS}  ${label} (${detection.evidence})`);
+  } else {
+    console.log(`  ${WARN}  ${label} — no strong signals found, defaulted to ${detection.preset}`);
+    console.log(`       \x1b[2mEdit autopilot.config.yaml to switch presets if needed\x1b[0m`);
+  }
+  console.log(`  ${PASS}  Test command: ${detection.testCommand}`);
+
+  const presetConfigPath = findPresetConfig(detection.preset, cwd);
+  if (!presetConfigPath) {
+    throw new Error(`Preset config not found for: ${detection.preset}. Looked in:\n  ${presetSearchPaths(detection.preset, cwd).join('\n  ')}`);
+  }
+
+  let presetContent = await fsAsync.readFile(presetConfigPath, 'utf8');
+  presetContent = presetContent.trimEnd() + `\ntestCommand: "${detection.testCommand}"\n`;
+  await fsAsync.writeFile(dest, presetContent, 'utf8');
+  console.log(`  ${PASS}  Created autopilot.config.yaml`);
+
+  if (!options.skipHook) {
+    const hookCode = await runHook('install', { cwd });
+    if (hookCode === 0) {
+      console.log(`  ${PASS}  Installed pre-push git hook`);
+    } else {
+      console.log(`  ${WARN}  Hook install failed (not fatal — run: npx autopilot hook install)`);
+    }
+  }
+
+  console.log('\n[setup] Checking prerequisites...');
+  await runDoctor();
+
+  console.log('\n[setup] Done. Run: npx autopilot run\n');
+}