@delegance/claude-autopilot 7.2.1 → 7.4.0

package/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 - v5.6 Phase 7 (docs reconciliation) — pending.
 
+## 7.3.0 (2026-05-10)
+
+**v7.3.0 — library export surface for v8 daemon.** Minor bump
+(new public API surface). The v8 daemon spec needs to call into
+the autopilot pipeline without spawning the CLI as a subprocess
+— subprocess boundaries lose error context, double up dependency
+resolution, and make sandbox enforcement harder. This PR exposes
+a curated set of `run*` functions as a stable library API.
+
+**New exports** at `@delegance/claude-autopilot`:
+
+* Pipeline read-only / discovery: `runScan`, `runScaffold`,
+  `runValidate`, `runFix`, `runCosts`, `runReport`, `runDoctor`,
+  `runSetup`.
+* Pipeline side-effecting: `runDeploy`, `runDeployStatus`,
+  `runDeployRollback` (daemon callers must wrap in policy gates
+  per v8 spec C3).
+* Helpers: `detectProject`.
+* Types: `DetectionResult`, `ScaffoldOptions`, `ScaffoldResult`,
+  `SetupOptions`, `ProfileName`.
+
+**Stability contract** documented in `docs/library-api.md`. Anything
+in that doc is SemVer-stable; deep imports
+(`@delegance/claude-autopilot/dist/...`) are unsupported.
+
+**`package.json` `exports` map** gains a `default` entry pointing
+at `./dist/src/index.js` so consumers can
+`import { runScaffold } from '@delegance/claude-autopilot'`
+instead of deep-importing.
+
+**Deliberate non-exports** (still callable via deep imports, no
+guarantee): JSON-envelope wrappers, internal `_*` helpers, the
+`runs` engine-introspection group (separate v8 prerequisite).
+
+4 new tests verify (a) all declared exports resolve at runtime,
+(b) `detectProject` returns the documented shape on the autopilot
+repo itself, (c) `package.json` `exports` map shape is locked.
+1559 → 1563 CLI tests; tsc clean; build clean.
+
+Version 7.2.1 → 7.3.0 (minor bump for new library surface).
+
 ## 7.2.1 (2026-05-10)
 
 **v7.2.1 — v8 spec codex pass-2 amendment.** Docs-only PR. Folds

package/dist/src/cli/help-text.js

@@ -28,7 +28,7 @@ export const HELP_GROUPS = [
         verbs: [
             { verb: 'init', summary: 'Scaffold guardrail.config.yaml + auto-detect migrate stack (writes .autopilot/stack.md)' },
             { verb: 'setup', summary: 'Auto-detect stack, write config, install pre-push hook' },
-            { verb: 'scaffold', summary: 'Scaffold project skeleton from a spec markdown (--from-spec <path>)' },
+            { verb: 'scaffold', summary: 'Scaffold project skeleton from a spec markdown (--from-spec <path> [--stack node|python|fastapi])' },
             { verb: 'autopilot', summary: 'Multi-phase orchestrator — run scan → spec → plan → implement under one runId (v6.2.0)' },
             { verb: 'brainstorm', summary: 'Pipeline entry point (Claude Code skill — see /brainstorm)' },
             { verb: 'spec', summary: 'Spec-writing pointer (Claude Code skill — see /brainstorm)' },

package/dist/src/cli/index.js

@@ -197,7 +197,7 @@ These are aliases for the flat subcommands; they still work without the 'advance
 // `run resume` form is handled BEFORE the default `run` -> review dispatch
 // kicks in (see disambiguation block just below).
 const SUBCOMMANDS = ['init', 'run', 'runs', 'scan', 'report', 'explain', 'ignore', 'ci', 'pr', 'fix', 'costs', 'watch', 'hook', 'autoregress', 'baseline', 'triage', 'lsp', 'worker', 'mcp', 'test-gen', 'pr-desc', 'doctor', 'preflight', 'setup', 'council', 'migrate-v4', 'migrate', 'migrate-doctor', 'deploy', 'brainstorm', 'spec', 'plan', 'implement', 'review', 'validate', 'autopilot', 'internal', 'help', '--help', '-h'];
-const VALUE_FLAGS = ['base', 'config', 'files', 'format', 'output', 'debounce', 'ask', 'focus', 'fail-on', 'note', 'reason', 'expires', 'profile', 'severity', 'prompt', 'context-file', 'path', 'adapter', 'ref', 'sha', 'spec', 'context', 'mode', 'phases', 'budget'];
+const VALUE_FLAGS = ['base', 'config', 'files', 'format', 'output', 'debounce', 'ask', 'focus', 'fail-on', 'note', 'reason', 'expires', 'profile', 'severity', 'prompt', 'context-file', 'path', 'adapter', 'ref', 'sha', 'spec', 'context', 'mode', 'phases', 'budget', 'stack'];
 // Bare invocation — no subcommand, no flags → show welcome guide
 if (args.length === 0) {
     const hasKey = !!(process.env.ANTHROPIC_API_KEY || process.env.GEMINI_API_KEY ||
@@ -933,14 +933,31 @@ switch (subcommand) {
     }
     case 'scaffold': {
         // v7.2.0 — `claude-autopilot scaffold --from-spec <path>`
+        // v7.4.0 — `--stack <node|python|fastapi>` + `--list-stacks`.
+        if (boolFlag('list-stacks')) {
+            const { printStackList } = await import("./scaffold.js");
+            printStackList();
+            process.exit(0);
+        }
         const fromSpec = flag('from-spec');
         const dryRun = boolFlag('dry-run');
+        const stackArg = flag('stack');
+        if (stackArg && !['node', 'python', 'fastapi'].includes(stackArg)) {
+            console.error(`\x1b[31m[claude-autopilot] --stack "${stackArg}" not recognized — supported: node, python, fastapi\x1b[0m`);
+            console.error(`  See: claude-autopilot scaffold --list-stacks`);
+            process.exit(3);
+        }
         if (!fromSpec) {
             console.error(`\x1b[31m[claude-autopilot] scaffold requires --from-spec <path>\x1b[0m`);
             console.error(`  Example: claude-autopilot scaffold --from-spec docs/specs/foo.md`);
+            console.error(`  Stacks:  claude-autopilot scaffold --list-stacks`);
             process.exit(1);
         }
-        await runScaffold({ specPath: fromSpec, dryRun });
+        await runScaffold({
+            specPath: fromSpec,
+            dryRun,
+            ...(stackArg ? { stack: stackArg } : {}),
+        });
         process.exit(0);
         break;
     }

package/dist/src/cli/scaffold/node.d.ts

@@ -0,0 +1,20 @@
+import type { ParsedFiles, ScaffoldResult, ScaffoldRunContext } from './types.ts';
+/**
+ * Build a minimal starter package.json. Caller passes in any explicit
+ * hints (parsed from spec); we layer Node 22 ESM defaults on top.
+ *
+ * Note: signature unchanged from v7.2.0 — re-exported through ../scaffold.ts
+ * so consumers that imported from the public scaffold module keep working.
+ */
+export declare function buildStarterPackageJson(projectName: string, hints: ParsedFiles['packageHints']): Record<string, unknown>;
+/**
+ * Node ESM scaffolder. Materializes directories + placeholder files,
+ * writes package.json (when listed in spec) and tsconfig.json (when listed),
+ * choosing JS vs TS tsconfig flavor based on which extension dominates the
+ * other listed paths.
+ *
+ * Behavior is intentionally byte-identical to v7.2.0 — the existing
+ * tests/scaffold.test.ts is the regression bar.
+ */
+export declare function scaffoldNode(ctx: ScaffoldRunContext): Promise<ScaffoldResult>;
+//# sourceMappingURL=node.d.ts.map

package/dist/src/cli/scaffold/node.js

@@ -0,0 +1,162 @@
+// v7.4.0 — Node ESM scaffolder, extracted from src/cli/scaffold.ts (was the
+// monolithic v7.2.0 implementation). Pure module split: the buildStarterPackageJson
+// + scaffoldNode functions here are byte-identical-in-behavior to v7.2.0; the
+// existing 11 scaffold tests are the regression bar.
+//
+// Why split: v7.4.0 adds Python + FastAPI per-stack scaffolders (see ./python.ts).
+// Keeping each stack in its own module makes the v7.5+ plan (Go, Rust, Ruby) a
+// drop-in pattern: add a new file, register it in the dispatcher inside
+// ../scaffold.ts.
+import * as fs from 'node:fs';
+import * as fsAsync from 'node:fs/promises';
+import * as path from 'node:path';
+const PASS = '\x1b[32m✓\x1b[0m';
+const SKIP = '\x1b[2m·\x1b[0m';
+const DIM = (t) => `\x1b[2m${t}\x1b[0m`;
+/**
+ * Build a minimal starter package.json. Caller passes in any explicit
+ * hints (parsed from spec); we layer Node 22 ESM defaults on top.
+ *
+ * Note: signature unchanged from v7.2.0 — re-exported through ../scaffold.ts
+ * so consumers that imported from the public scaffold module keep working.
+ */
+export function buildStarterPackageJson(projectName, hints) {
+    const pkg = {
+        name: projectName,
+        version: '0.1.0',
+        private: true,
+        type: hints.type ?? 'module',
+        engines: { node: '>=22' },
+        scripts: {
+            test: 'node --test tests/*.test.js',
+            ...hints.scripts,
+        },
+    };
+    if (hints.bin)
+        pkg.bin = hints.bin;
+    if (hints.dependencies)
+        pkg.dependencies = hints.dependencies;
+    if (hints.devDependencies)
+        pkg.devDependencies = hints.devDependencies;
+    return pkg;
+}
+const STARTER_TSCONFIG_JS = {
+    compilerOptions: {
+        target: 'ES2022',
+        module: 'NodeNext',
+        moduleResolution: 'NodeNext',
+        allowJs: true,
+        checkJs: true,
+        noEmit: true,
+        strict: true,
+        esModuleInterop: true,
+        skipLibCheck: true,
+        types: ['node'],
+    },
+    include: ['bin/**/*', 'src/**/*', 'tests/**/*'],
+};
+const STARTER_TSCONFIG_TS = {
+    compilerOptions: {
+        target: 'ES2022',
+        module: 'NodeNext',
+        moduleResolution: 'NodeNext',
+        outDir: 'dist',
+        strict: true,
+        esModuleInterop: true,
+        skipLibCheck: true,
+        types: ['node'],
+    },
+    include: ['bin/**/*', 'src/**/*', 'tests/**/*'],
+};
+/**
+ * Node ESM scaffolder. Materializes directories + placeholder files,
+ * writes package.json (when listed in spec) and tsconfig.json (when listed),
+ * choosing JS vs TS tsconfig flavor based on which extension dominates the
+ * other listed paths.
+ *
+ * Behavior is intentionally byte-identical to v7.2.0 — the existing
+ * tests/scaffold.test.ts is the regression bar.
+ */
+export async function scaffoldNode(ctx) {
+    const { cwd, parsed, dryRun } = ctx;
+    const projectName = path.basename(cwd);
+    const filesCreated = [];
+    const filesSkippedExisting = [];
+    const dirsCreated = [];
+    let packageJsonAction = 'skipped-exists';
+    let tsconfigAction = 'skipped-no-ts';
+    // 1) Create directories first.
+    const dirs = new Set();
+    for (const p of parsed.paths) {
+        const d = path.dirname(p);
+        if (d && d !== '.')
+            dirs.add(d);
+    }
+    for (const d of dirs) {
+        const abs = path.join(cwd, d);
+        if (fs.existsSync(abs))
+            continue;
+        if (!dryRun)
+            await fsAsync.mkdir(abs, { recursive: true });
+        dirsCreated.push(d);
+        console.log(`  ${PASS}  mkdir   ${DIM(d + '/')}`);
+    }
+    // 2) Create placeholder files (skip ones we'll handle specially).
+    const SPECIAL = new Set(['package.json', 'tsconfig.json']);
+    for (const p of parsed.paths) {
+        if (SPECIAL.has(p))
+            continue;
+        const abs = path.join(cwd, p);
+        if (fs.existsSync(abs)) {
+            filesSkippedExisting.push(p);
+            console.log(`  ${SKIP}  exists  ${DIM(p)}`);
+            continue;
+        }
+        if (!dryRun) {
+            await fsAsync.mkdir(path.dirname(abs), { recursive: true });
+            // Touch — empty file. Real content is the agent's job.
+            await fsAsync.writeFile(abs, '', 'utf8');
+        }
+        filesCreated.push(p);
+        console.log(`  ${PASS}  touch   ${DIM(p)}`);
+    }
+    // 3) package.json — only if the spec lists it.
+    if (parsed.paths.includes('package.json')) {
+        const pkgAbs = path.join(cwd, 'package.json');
+        if (fs.existsSync(pkgAbs)) {
+            packageJsonAction = 'skipped-exists';
+            console.log(`  ${SKIP}  exists  ${DIM('package.json (preserved)')}`);
+        }
+        else {
+            const pkg = buildStarterPackageJson(projectName, parsed.packageHints);
+            if (!dryRun) {
+                await fsAsync.writeFile(pkgAbs, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
+            }
+            packageJsonAction = 'created';
+            console.log(`  ${PASS}  write   ${DIM('package.json (Node 22 ESM starter)')}`);
+        }
+    }
+    // 4) tsconfig.json — only if the spec lists it. JS-flavor when the
+    //    other paths are predominantly .js, TS-flavor for .ts.
+    if (parsed.paths.includes('tsconfig.json')) {
+        const tsAbs = path.join(cwd, 'tsconfig.json');
+        if (fs.existsSync(tsAbs)) {
+            tsconfigAction = 'skipped-exists';
+            console.log(`  ${SKIP}  exists  ${DIM('tsconfig.json (preserved)')}`);
+        }
+        else {
+            const otherPaths = parsed.paths.filter((p) => !SPECIAL.has(p));
+            const tsCount = otherPaths.filter((p) => /\.tsx?$/.test(p)).length;
+            const jsCount = otherPaths.filter((p) => /\.jsx?$/.test(p)).length;
+            const config = tsCount > jsCount ? STARTER_TSCONFIG_TS : STARTER_TSCONFIG_JS;
+            tsconfigAction = 'created';
+            if (!dryRun) {
+                await fsAsync.writeFile(tsAbs, JSON.stringify(config, null, 2) + '\n', 'utf8');
+            }
+            const flavor = config === STARTER_TSCONFIG_TS ? 'compiled TS to dist/' : 'JS w/ JSDoc + checkJs';
+            console.log(`  ${PASS}  write   ${DIM(`tsconfig.json (${flavor})`)}`);
+        }
+    }
+    return { filesCreated, dirsCreated, filesSkippedExisting, packageJsonAction, tsconfigAction };
+}
+//# sourceMappingURL=node.js.map

package/dist/src/cli/scaffold/python.d.ts

@@ -0,0 +1,71 @@
+import type { ScaffoldResult, ScaffoldRunContext } from './types.ts';
+/**
+ * PEP 503 distribution-name normalization, restricted to what we need
+ * here. Lowercase, runs of `[._-]+` collapse to a single `-`, leading +
+ * trailing `[._-]` stripped. Empty result falls back to 'app' (so the
+ * worst-case `cwd` of `___` still produces a buildable pyproject).
+ */
+export declare function normalizeDistributionName(raw: string): string;
+/**
+ * Convert a (PEP 503 normalized) distribution name into a valid Python
+ * identifier suitable for a top-level package directory:
+ *   - replace `-` and `.` with `_`
+ *   - prefix `_` if it starts with a digit (so `2cool` -> `_2cool`)
+ *
+ * Tests pin both transformations:
+ *   my-pkg-2 -> my_pkg_2
+ *   2cool    -> _2cool
+ */
+export declare function packageNameFromDistribution(distribution: string): string;
+/**
+ * Parse a dependency string (`fastapi`, `fastapi>=0.110`,
+ * `uvicorn[standard]`, `pyramid==2.0`) into its PEP 503 normalized
+ * "name" portion — used purely as a dedup key. We don't care about the
+ * version specifier when keying; first-occurrence wins (per spec
+ * "Dedupe by PEP 503 normalized name; first occurrence wins").
+ */
+export declare function dependencyNameKey(dep: string): string;
+/**
+ * Build the dependency list for the generated pyproject.toml. Honors
+ * the narrow contract from spec ("Dependency hint extraction (codex
+ * WARNING #6)"): values flow through verbatim, no version inference,
+ * deduped by PEP 503 normalized name. For FastAPI we ALSO seed
+ * `fastapi>=0.110` and `uvicorn[standard]>=0.27` if not already present.
+ */
+export declare function buildPythonDependencies(hintDeps: string[] | undefined, isFastapi: boolean): string[];
+/**
+ * Generate the pyproject.toml body. Caller supplies the resolved
+ * distribution name, package name, dependency list, and FastAPI flag
+ * (only difference: FastAPI adds a `[project.scripts]` block).
+ */
+export declare function buildPyproject(opts: {
+    distributionName: string;
+    packageName: string;
+    dependencies: string[];
+    isFastapi: boolean;
+}): string;
+/** FastAPI entrypoint — codex CRITICAL #2: must be runnable, not a stub. */
+export declare function buildFastapiMain(packageName: string): string;
+/** Smoke test for the FastAPI scaffold — also auto-included so pytest config isn't dead. */
+export declare function buildFastapiTest(packageName: string): string;
+/**
+ * The Python scaffolder. Materializes:
+ *   - src/<package_name>/__init__.py (empty)
+ *   - tests/ directory
+ *   - pyproject.toml (PEP 621 + hatchling)
+ *   - README.md (only if missing)
+ *
+ * For FastAPI specs it also writes:
+ *   - src/<package_name>/main.py (runnable FastAPI app)
+ *   - tests/test_main.py (smoke test)
+ *
+ * Files explicitly listed in the spec's `## Files` get touched as empty
+ * placeholders if they don't already exist (matches the v7.2.0 Node
+ * behavior). The special files above are written with content even when
+ * not listed in `## Files` — without them the generated pyproject.toml
+ * is invalid (missing package dir) or has dead config (no tests).
+ */
+export declare function scaffoldPython(ctx: ScaffoldRunContext, opts: {
+    isFastapi: boolean;
+}): Promise<ScaffoldResult>;
+//# sourceMappingURL=python.d.ts.map