@delegance/claude-autopilot 1.0.0-alpha.6 → 1.0.0-alpha.8

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 1.0.0-alpha.8
+
+### Added
+
+- **`autopilot autoregress`** — `autoregress run|diff|update|generate` now a first-class `autopilot` subcommand (no more raw `npx tsx scripts/autoregress.ts`)
+- **GitHub Actions CI** — `.github/workflows/ci.yml` runs typecheck + tests on every PR; auto-publishes to npm on `v*` tags
+- **README rewrite** — full feature documentation covering all alphas (all commands, config, GitHub Actions, snapshot regression, architecture)
+
+## 1.0.0-alpha.7
+
+### Added
+
+- **`autopilot hook install`** — writes a `pre-push` git hook that runs `autoregress run` before every push; `hook uninstall` removes it; `hook status` shows current state; `--force` overwrites existing hook
+- **`autoregress diff`** — colored snapshot viewer showing line-by-line JSON diffs between current output and baselines; exits 1 if any diffs found (never modifies baselines — use `update` for that)
+- **`autoregress generate --files <list>`** — explicit comma-separated file list bypasses git detection; generates baselines for any src file on demand
+- **Real baselines** — `tests/snapshots/*.snap.ts` + baselines for `serializer.ts`, `import-scanner.ts`, `impact-selector.ts`, and `sarif.ts` — alpha.6 infrastructure now self-testing via snapshots
+
 ## 1.0.0-alpha.6
 
 ### Added

package/README.md

@@ -1,58 +1,159 @@
-# claude-autopilot
+# @delegance/claude-autopilot
 
-End-to-end Claude Code pipeline: approved spec → plan → worktree → implementation → migrations → validation → PR → review engine → review-bot triage.
+Automated code review pipeline for Claude Code. Runs static rules, an optional LLM review engine, and impact-aware snapshot regression tests — outputs SARIF for GitHub Code Scanning, inline PR annotations, and a pre-push hook for local enforcement.
 
-**Status: v1.0.0-alpha.1** — core architecture in place, ported adapters (codex, github, supabase, cursor), 1 preset (nextjs-supabase), 32 passing tests. API may change through alpha.
+## Install
 
-Full design spec: `docs/superpowers/specs/2026-04-20-claude-autopilot-v1-design.md`
-Implementation plans: `docs/superpowers/plans/`
+```bash
+npm install --save-dev @delegance/claude-autopilot@alpha
+```
 
-## Changes in v1.0 (alpha.1)
+Requires Node 22+.
 
-- Four pluggable integration points (ReviewEngine, VcsHost, MigrationRunner, ReviewBotParser) with shared `AdapterBase`
-- YAML config (`autopilot.config.yaml`) replaces `.autopilot/stack.md`
-- Unified `Finding` type across validate + review-bot, with separate `TriageRecord[]` / `FixAttempt[]` history
-- Merged static-rules phase with global re-check after autofix
-- `AutopilotError` taxonomy with per-code retry policy
-- `apiVersion` + `getCapabilities()` on every adapter
-- Real tests phase — runs `testCommand` from config, emits critical finding on failure
-- NDJSON event log with secret redaction
+## Quick Start
 
-## Prerequisites
+```bash
+# Scaffold config
+npx autopilot init
 
-- Node 22+
-- `gh` CLI authenticated
-- `OPENAI_API_KEY` in `.env.local`
+# Run on changed files
+npx autopilot run
 
-## Install
+# Watch mode (re-runs on every file save)
+npx autopilot watch
+
+# Install pre-push hook
+npx autopilot hook install
+```
+
+## Commands
+
+### `autopilot run`
+
+Runs the pipeline on git-changed files vs the base ref.
 
 ```bash
-npm install --save-dev @delegance/claude-autopilot@alpha
+npx autopilot run                        # diff against HEAD~1
+npx autopilot run --base main            # diff against main
+npx autopilot run --files src/foo.ts     # explicit file list
+npx autopilot run --format sarif --output results.sarif
+npx autopilot run --dry-run              # show what would run, no execution
+```
+
+### `autopilot watch`
+
+Debounced re-run on every file save.
+
+```bash
+npx autopilot watch
+npx autopilot watch --debounce 500
 ```
 
-## Usage (alpha.1)
+### `autopilot hook`
 
-CLI surface is limited to `preflight` in alpha.1. `run`, `init`, `validate`, `codex-pr-review`, `bugbot` land in alpha.4.
+Manages a `pre-push` git hook that runs snapshot regression tests before every push.
 
 ```bash
-npx autopilot          # runs preflight
+npx autopilot hook install          # write .git/hooks/pre-push
+npx autopilot hook install --force  # overwrite existing
+npx autopilot hook uninstall        # remove
+npx autopilot hook status           # show installed hook content
 ```
 
-## Preset quick-start
+Works in git worktrees (handles `.git` as a file pointer).
+
+### `autopilot autoregress`
+
+Impact-aware snapshot regression testing. Only fires tests whose source modules (or one-hop importers) were touched by the current branch.
 
 ```bash
-cp presets/nextjs-supabase/autopilot.config.yaml .
-# Edit adapters / protectedPaths / testCommand as needed
-npx tsx src/cli/preflight.ts
+npx autopilot autoregress run              # impact-selected snapshots (default)
+npx autopilot autoregress run --all        # all snapshots
+npx autopilot autoregress diff             # show JSON diffs vs baselines
+npx autopilot autoregress update           # overwrite baselines with current output
+npx autopilot autoregress generate         # LLM-generate snapshot tests for changed files
+npx autopilot autoregress generate --files src/foo.ts,src/bar.ts
 ```
 
-## Roadmap
+Requires `OPENAI_API_KEY` for `generate` mode.
+
+### `autopilot init`
+
+Scaffolds `autopilot.config.yaml` from a preset.
+
+```bash
+npx autopilot init
+```
+
+Available presets: `nextjs-supabase`, `t3`, `python-fastapi`, `rails-postgres`, `go`.
+
+### `autopilot preflight`
+
+Checks prerequisites (Node version, `gh` CLI auth, `OPENAI_API_KEY`).
+
+## GitHub Actions
+
+Add to your workflow:
+
+```yaml
+- uses: axledbetter/claude-autopilot@v1
+  with:
+    openai-api-key: ${{ secrets.OPENAI_API_KEY }}
+```
+
+Runs the pipeline, uploads SARIF to GitHub Code Scanning, and annotates the PR diff inline.
+
+## SARIF Output
+
+```bash
+npx autopilot run --format sarif --output autopilot.sarif
+```
+
+Compatible with `github/codeql-action/upload-sarif@v3`.
+
+## Config (`autopilot.config.yaml`)
+
+```yaml
+preset: nextjs-supabase          # inherit a base config
+reviewEngine:
+  adapter: codex
+  options:
+    model: gpt-5.3-codex
+testCommand: npm test
+protect:
+  - src/core/**
+  - data/deltas/**
+```
+
+## Snapshot Regression Testing
+
+After each feature lands, generate behavioral baselines:
+
+```bash
+npx autopilot autoregress generate
+```
+
+Future PRs automatically fail if covered behavior diverges. The impact selector uses `git merge-base` diff + one-hop import graph expansion so only relevant snapshots run — keeping CI token-efficient.
+
+High-impact paths (`src/core/pipeline/**`, `src/adapters/**`, `src/core/findings/**`, `src/core/config/**`) always trigger a full run.
+
+## Architecture
+
+Four pluggable adapter points:
+
+| Point | Built-in | Purpose |
+|---|---|---|
+| `review-engine` | `codex` | LLM code review |
+| `vcs-host` | `github` | PR comments + SARIF upload |
+| `migration-runner` | `supabase` | DB migration execution |
+| `review-bot-parser` | `cursor` | Parse review bot comments |
+
+## Requirements
 
-- **alpha.2:** chunking, cost, cache, remaining adapters, 5 presets, 20 scenario tests
-- **alpha.3:** idempotency wiring, concurrency, adapter trust, 60 conformance + 13 safety tests
-- **alpha.4:** full CLI (init, install-github-action, run --resume, etc.) + programmatic API
-- **beta → 1.0.0:** dogfood + npm publish
+- Node ≥ 22
+- `OPENAI_API_KEY` (optional — review engine and `autoregress generate` only)
+- `gh` CLI authenticated (optional — PR creation / vcs-host adapter)
 
 ## License
 
-MIT.
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delegance/claude-autopilot",
-  "version": "1.0.0-alpha.6",
+  "version": "1.0.0-alpha.8",
   "type": "module",
   "description": "Claude Code automation pipeline: spec → plan → implement → validate → PR",
   "keywords": ["claude", "autopilot", "ai", "pipeline", "code-review", "cli"],

package/scripts/autoregress.ts

@@ -2,6 +2,7 @@
 // scripts/autoregress.ts
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import * as os from 'node:os';
 import { execSync, spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { selectSnapshots } from '../src/snapshots/impact-selector.ts';
@@ -19,6 +20,22 @@ function loadJson<T>(p: string, fallback: T): T {
   try { return JSON.parse(fs.readFileSync(p, 'utf8')) as T; } catch { return fallback; }
 }
 
+export function diffBaselines(baselineJson: string, currentJson: string): string[] {
+  if (baselineJson === currentJson) return [];
+  const baselineLines = baselineJson.split('\n');
+  const currentLines = currentJson.split('\n');
+  const lines: string[] = [];
+  const maxLen = Math.max(baselineLines.length, currentLines.length);
+  for (let i = 0; i < maxLen; i++) {
+    const bLine = baselineLines[i];
+    const cLine = currentLines[i];
+    if (bLine === cLine) continue;
+    if (bLine !== undefined) lines.push(`- ${bLine}`);
+    if (cLine !== undefined) lines.push(`+ ${cLine}`);
+  }
+  return lines;
+}
+
 function getChangedFiles(since?: string): string[] | null {
   try {
     const base = since
@@ -155,12 +172,15 @@ Write a snapshot test file. Requirements:
 5. Baseline loading pattern (use slug {slug}):
    const SLUG = '{slug}';
    import { fileURLToPath } from 'node:url';
+   import * as path from 'node:path';
    const baselineRaw = process.env.CAPTURE_BASELINE === '1' ? '{}' : fs.readFileSync(fileURLToPath(new URL('./baselines/{slug}.json', import.meta.url)), 'utf8');
    const baseline = JSON.parse(baselineRaw);
    const captured: Record<string, unknown> = {};
    process.on('exit', () => {
      if (process.env.CAPTURE_BASELINE === '1') {
-       const p = fileURLToPath(new URL('./baselines/{slug}.json', import.meta.url));
+       const p = process.env.AUTOREGRESS_TEMP_BASELINE_DIR
+         ? path.join(process.env.AUTOREGRESS_TEMP_BASELINE_DIR, '{slug}.json')
+         : fileURLToPath(new URL('./baselines/{slug}.json', import.meta.url));
        fs.writeFileSync(p, JSON.stringify(captured, null, 2), 'utf8');
      }
    });
@@ -175,13 +195,24 @@ async function cmdGenerate(args: string[]): Promise<number> {
 
   const sinceIdx = args.indexOf('--since');
   const since = sinceIdx >= 0 ? args[sinceIdx + 1] : undefined;
-  const changed = getChangedFiles(since);
-  if (!changed) { console.error('[autoregress generate] could not determine changed files'); return 1; }
-
-  const srcFiles = changed.filter(f => f.startsWith('src/') && f.endsWith('.ts'));
-  if (srcFiles.length === 0) {
-    console.log('[autoregress generate] no src/*.ts files changed — nothing to generate');
-    return 0;
+  const filesIdx = args.indexOf('--files');
+  const filesArg = filesIdx >= 0 ? args[filesIdx + 1] : undefined;
+
+  let srcFiles: string[];
+  if (filesArg) {
+    srcFiles = filesArg.split(',').map(f => f.trim()).filter(f => f.startsWith('src/') && f.endsWith('.ts'));
+    if (srcFiles.length === 0) {
+      console.error('[autoregress generate] --files must contain at least one src/*.ts path');
+      return 1;
+    }
+  } else {
+    const changed = getChangedFiles(since);
+    if (!changed) { console.error('[autoregress generate] could not determine changed files'); return 1; }
+    srcFiles = changed.filter(f => f.startsWith('src/') && f.endsWith('.ts'));
+    if (srcFiles.length === 0) {
+      console.log('[autoregress generate] no src/*.ts files changed — nothing to generate');
+      return 0;
+    }
   }
 
   console.log(`[autoregress generate] generating snapshots for ${srcFiles.length} file(s)`);
@@ -257,12 +288,98 @@ async function cmdGenerate(args: string[]): Promise<number> {
   return 0;
 }
 
-const [,, subcmd, ...rest] = process.argv;
-switch (subcmd) {
-  case 'run': process.exit(cmdRun(rest)); break;
-  case 'update': process.exit(cmdUpdate(rest)); break;
-  case 'generate': process.exit(await cmdGenerate(rest)); break;
-  default:
-    console.error(`[autoregress] unknown subcommand: ${subcmd ?? '(none)'}`);
-    process.exit(1);
+function cmdDiff(args: string[]): number {
+  const runAll = args.includes('--all');
+  const snapIdx = args.indexOf('--snapshot');
+  const slug = snapIdx >= 0 ? args[snapIdx + 1] : undefined;
+  const sinceIdx = args.indexOf('--since');
+  const since = sinceIdx >= 0 ? args[sinceIdx + 1] : undefined;
+
+  const index = loadJson<Record<string, string[]>>(INDEX_PATH, {});
+  const importMap = loadJson<Record<string, string[]>>(IMPORT_MAP_PATH, {});
+  const snapFiles = slug
+    ? [path.join('tests', 'snapshots', `${slug}.snap.ts`)]
+    : allSnapFiles();
+
+  let selected: string[];
+  if (runAll || slug || snapFiles.length === 0) {
+    selected = snapFiles;
+  } else {
+    const changed = getChangedFiles(since);
+    selected = changed ? selectSnapshots(changed, snapFiles, index, importMap).selected : snapFiles;
+  }
+
+  if (selected.length === 0) {
+    console.log('[autoregress diff] no snapshots to diff');
+    return 0;
+  }
+
+  const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+  const red = useColor ? '\x1b[31m' : '';
+  const green = useColor ? '\x1b[32m' : '';
+  const reset = useColor ? '\x1b[0m' : '';
+
+  let changedCount = 0;
+  for (const snap of selected) {
+    const slug_ = path.basename(snap, '.snap.ts');
+    const baselinePath = path.join(BASELINES_DIR, `${slug_}.json`);
+
+    if (!fs.existsSync(baselinePath)) {
+      console.log(`  ${snap} — ${red}no baseline${reset}`);
+      continue;
+    }
+
+    const tmpBaselinesDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ar-diff-'));
+    const tmpBaselinePath = path.join(tmpBaselinesDir, `${slug_}.json`);
+    fs.copyFileSync(baselinePath, tmpBaselinePath);
+
+    const absSnap = path.join(ROOT, snap);
+    const captureResult = spawnSync('node', ['--test', '--import', 'tsx', absSnap], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      cwd: ROOT,
+      env: { ...process.env, CAPTURE_BASELINE: '1', AUTOREGRESS_TEMP_BASELINE_DIR: tmpBaselinesDir },
+    });
+
+    const baselineJson = fs.readFileSync(baselinePath, 'utf8');
+    const captureOk = fs.existsSync(tmpBaselinePath);
+    const currentJson = captureOk ? fs.readFileSync(tmpBaselinePath, 'utf8') : null;
+    if (!captureOk && captureResult.status !== 0) {
+      const stderr = captureResult.stderr?.toString().trim();
+      if (stderr) console.error(`    ${stderr.slice(0, 120)}`);
+    }
+    fs.rmSync(tmpBaselinesDir, { recursive: true, force: true });
+
+    if (!currentJson) {
+      console.log(`  ${snap} — ${red}capture failed${reset}`);
+      continue;
+    }
+
+    const diffLines = diffBaselines(baselineJson, currentJson);
+    if (diffLines.length === 0) {
+      console.log(`  ${snap} — ${green}✓ no changes${reset}`);
+    } else {
+      changedCount++;
+      console.log(`  ${snap}`);
+      for (const line of diffLines) {
+        if (line.startsWith('-')) console.log(`    ${red}${line}${reset}`);
+        else if (line.startsWith('+')) console.log(`    ${green}${line}${reset}`);
+        else console.log(`    ${line}`);
+      }
+    }
+  }
+
+  return changedCount > 0 ? 1 : 0;
+}
+
+if (fileURLToPath(import.meta.url) === path.resolve(process.argv[1] ?? '')) {
+  const [,, subcmd, ...rest] = process.argv;
+  switch (subcmd) {
+    case 'run': process.exit(cmdRun(rest)); break;
+    case 'update': process.exit(cmdUpdate(rest)); break;
+    case 'generate': process.exit(await cmdGenerate(rest)); break;
+    case 'diff': process.exit(cmdDiff(rest)); break;
+    default:
+      console.error(`[autoregress] unknown subcommand: ${subcmd ?? '(none)'}`);
+      process.exit(1);
+  }
 }

package/src/cli/autoregress-bridge.ts

@@ -0,0 +1,30 @@
+// src/cli/autoregress-bridge.ts
+import * as path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SCRIPT = path.resolve(__dirname, '../../scripts/autoregress.ts');
+
+const VALID_MODES = ['run', 'update', 'generate', 'diff'];
+
+export function buildAutoregressArgs(args: string[]): string[] {
+  const mode = args[0] && VALID_MODES.includes(args[0]) ? args[0] : 'run';
+  const rest = args[0] && VALID_MODES.includes(args[0]) ? args.slice(1) : args;
+  return [mode, ...rest];
+}
+
+export function runAutoregress(args: string[]): number {
+  const resolvedArgs = buildAutoregressArgs(args);
+  const result = spawnSync(
+    process.execPath,
+    ['--import', 'tsx', SCRIPT, ...resolvedArgs],
+    { stdio: 'inherit', cwd: process.cwd() },
+  );
+  if (result.error) {
+    console.error(`[autoregress] failed to launch: ${result.error.message}`);
+    console.error(`  script: ${SCRIPT}`);
+    return 1;
+  }
+  return result.status ?? 1;
+}

package/src/cli/hook.ts

@@ -0,0 +1,79 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const HOOK_CONTENT = `#!/bin/sh
+# autopilot pre-push hook — runs impact-selected snapshots before push
+npx tsx scripts/autoregress.ts run
+`;
+
+function findGitDir(cwd: string): string | null {
+  let dir = path.resolve(cwd);
+  for (let i = 0; i < 10; i++) {
+    const candidate = path.join(dir, '.git');
+    if (fs.existsSync(candidate)) {
+      const stat = fs.statSync(candidate);
+      if (stat.isDirectory()) return candidate;
+      if (stat.isFile()) {
+        const content = fs.readFileSync(candidate, 'utf8');
+        const match = content.match(/^gitdir:\s*(.+)/m);
+        if (match) return path.resolve(dir, match[1]!.trim());
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+
+export async function runHook(
+  sub: string,
+  options: { cwd?: string; force?: boolean } = {},
+): Promise<number> {
+  const cwd = options.cwd ?? process.cwd();
+  const gitDir = findGitDir(cwd);
+
+  if (!gitDir) {
+    console.error('[hook] not inside a git repository');
+    return 1;
+  }
+
+  const hookPath = path.join(gitDir, 'hooks', 'pre-push');
+
+  switch (sub) {
+    case 'install': {
+      if (fs.existsSync(hookPath) && !options.force) {
+        console.error(`[hook] pre-push hook already exists at ${hookPath}`);
+        console.error('       Use --force to overwrite.');
+        return 1;
+      }
+      fs.mkdirSync(path.dirname(hookPath), { recursive: true });
+      fs.writeFileSync(hookPath, HOOK_CONTENT, 'utf8');
+      fs.chmodSync(hookPath, 0o755);
+      console.log(`[hook] installed pre-push hook at ${hookPath}`);
+      return 0;
+    }
+    case 'uninstall': {
+      if (!fs.existsSync(hookPath)) {
+        console.log('[hook] no pre-push hook installed');
+        return 0;
+      }
+      fs.rmSync(hookPath);
+      console.log(`[hook] removed ${hookPath}`);
+      return 0;
+    }
+    case 'status': {
+      if (fs.existsSync(hookPath)) {
+        console.log(`[hook] installed at ${hookPath}`);
+        console.log(fs.readFileSync(hookPath, 'utf8'));
+      } else {
+        console.log('[hook] not installed');
+      }
+      return 0;
+    }
+    default:
+      console.error(`[hook] unknown subcommand: ${sub}`);
+      console.error('Usage: autopilot hook <install|uninstall|status> [--force]');
+      return 1;
+  }
+}

package/src/cli/index.ts

@@ -16,7 +16,7 @@ import { runWatch } from './watch.ts';
 
 const args = process.argv.slice(2);
 
-const SUBCOMMANDS = ['init', 'run', 'preflight', 'help', '--help', '-h'] as const;
+const SUBCOMMANDS = ['init', 'run', 'watch', 'hook', 'autoregress', 'preflight', '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,6 +47,7 @@ Commands:
   watch        Watch for file changes and re-run pipeline on each save
   init         Scaffold autopilot.config.yaml from a preset
   preflight    Check prerequisites
+  autoregress  Run snapshot regression tests (run|diff|update|generate)
 
 Options (run):
   --base <ref>         Git base ref for diff (default: HEAD~1)
@@ -59,6 +60,12 @@ Options (run):
 Options (watch):
   --config <path>      Path to config file (default: ./autopilot.config.yaml)
   --debounce <ms>      Debounce delay in ms (default: 300)
+
+Options (autoregress):
+  --all                    Run/diff all snapshots
+  --since <ref>            Git ref for changed-files detection
+  --snapshot <slug>        Target a single snapshot
+  --files <a,b,c>          Explicit file list for generate (skips git detection)
 `);
 }
 
@@ -118,6 +125,22 @@ switch (subcommand) {
     break;
   }
 
+  case 'hook': {
+    const { runHook } = await import('./hook.ts');
+    const hookSub = args[1] ?? 'status';
+    const force = boolFlag('force');
+    const code = await runHook(hookSub, { force });
+    process.exit(code);
+    break;
+  }
+
+  case 'autoregress': {
+    const { runAutoregress } = await import('./autoregress-bridge.ts');
+    const code = runAutoregress(args.slice(1));
+    process.exit(code);
+    break;
+  }
+
   default:
     console.error(`\x1b[31m[autopilot] Unknown subcommand: "${subcommand}"\x1b[0m`);
     printUsage();