@delegance/claude-autopilot 7.2.1 → 7.4.0

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

@@ -0,0 +1,338 @@
+// v7.4.0 — Python + FastAPI scaffolder.
+//
+// Two scaffold flavors share most of this module:
+//   - bare Python (pyproject.toml / requirements.txt detected)
+//   - FastAPI (Python + a main.py + a `fastapi` mention in the spec)
+//
+// FastAPI auto-includes `fastapi>=0.110` and `uvicorn[standard]>=0.27` in
+// dependencies (deduped by PEP 503 normalized name) and emits a runnable
+// `src/<package>/main.py` + `tests/test_main.py` so the generated
+// `[project.scripts]` entrypoint actually resolves on `pip install -e .`
+// — not a dangling stub. This was codex CRITICAL #2 on the v7.4.0 spec.
+//
+// All naming follows the deterministic algorithm described in the spec
+// ("Name normalization (codex WARNING #1)"):
+//   - distribution_name = PEP 503 normalize(basename(cwd))
+//   - package_name = distribution_name with `-`/`.` -> `_`,
+//                    prefix `_` if it would start with a digit.
+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`;
+/**
+ * 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 function normalizeDistributionName(raw) {
+    const lower = raw.toLowerCase();
+    const collapsed = lower.replace(/[._-]+/g, '-');
+    const stripped = collapsed.replace(/^[-]+/, '').replace(/[-]+$/, '');
+    return stripped.length > 0 ? stripped : 'app';
+}
+/**
+ * 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 function packageNameFromDistribution(distribution) {
+    const replaced = distribution.replace(/[-.]/g, '_');
+    return /^[0-9]/.test(replaced) ? `_${replaced}` : replaced;
+}
+/**
+ * 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 function dependencyNameKey(dep) {
+    // Strip extras + version specifier. Match the leading
+    // identifier (PEP 508 names are `[A-Za-z0-9._-]+`).
+    const m = /^[A-Za-z0-9._-]+/.exec(dep.trim());
+    if (!m)
+        return dep.trim().toLowerCase();
+    return normalizeDistributionName(m[0]);
+}
+/**
+ * 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 function buildPythonDependencies(hintDeps, isFastapi) {
+    const out = [];
+    const seen = new Set();
+    const push = (raw) => {
+        const key = dependencyNameKey(raw);
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        out.push(raw);
+    };
+    for (const d of hintDeps ?? [])
+        push(d);
+    if (isFastapi) {
+        // Only auto-add when not already supplied. If the spec listed
+        // `fastapi==0.115`, we keep that pin and don't override it with our
+        // default lower bound.
+        push('fastapi>=0.110');
+        push('uvicorn[standard]>=0.27');
+    }
+    return out;
+}
+/**
+ * Format a TOML string array, one entry per line. Used for the
+ * `dependencies = [...]` block in pyproject.toml. Strings are quoted
+ * with double quotes; we escape backslashes + double quotes.
+ */
+function tomlStringArray(values) {
+    if (values.length === 0)
+        return '[]';
+    const lines = values.map(v => `    "${v.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`);
+    return `[\n${lines.join(',\n')},\n]`;
+}
+/**
+ * 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 function buildPyproject(opts) {
+    const { distributionName, packageName, dependencies, isFastapi } = opts;
+    const lines = [];
+    lines.push('[project]');
+    lines.push(`name = "${distributionName}"`);
+    lines.push('version = "0.1.0"');
+    lines.push('requires-python = ">=3.11"');
+    lines.push(`dependencies = ${tomlStringArray(dependencies)}`);
+    lines.push('');
+    if (isFastapi) {
+        lines.push('[project.scripts]');
+        lines.push(`${distributionName}-server = "${packageName}.main:run"`);
+        lines.push('');
+    }
+    lines.push('[build-system]');
+    lines.push('requires = ["hatchling"]');
+    lines.push('build-backend = "hatchling.build"');
+    lines.push('');
+    // codex W1 — explicit packages list, no auto-discovery.
+    lines.push('[tool.hatch.build.targets.wheel]');
+    lines.push(`packages = ["src/${packageName}"]`);
+    lines.push('');
+    lines.push('[tool.pytest.ini_options]');
+    lines.push('testpaths = ["tests"]');
+    lines.push('');
+    return lines.join('\n');
+}
+/** FastAPI entrypoint — codex CRITICAL #2: must be runnable, not a stub. */
+export function buildFastapiMain(packageName) {
+    return `"""FastAPI entrypoint — auto-scaffolded by claude-autopilot.
+Override the prose docstring + add real routes; keep \`app\` and
+\`run()\` exported so the [project.scripts] entry stays valid.
+"""
+from fastapi import FastAPI
+import uvicorn
+
+app = FastAPI()
+
+
+@app.get("/health")
+def health() -> dict[str, str]:
+    return {"status": "ok"}
+
+
+def run() -> None:
+    uvicorn.run("${packageName}.main:app", host="0.0.0.0", port=8000)
+`;
+}
+/** Smoke test for the FastAPI scaffold — also auto-included so pytest config isn't dead. */
+export function buildFastapiTest(packageName) {
+    return `from fastapi.testclient import TestClient
+from ${packageName}.main import app
+
+client = TestClient(app)
+
+
+def test_health() -> None:
+    response = client.get("/health")
+    assert response.status_code == 200
+    assert response.json() == {"status": "ok"}
+`;
+}
+/** Generic Python README placeholder. Never overwrites an existing README. */
+function buildReadme(distributionName, isFastapi) {
+    const stackLabel = isFastapi ? 'FastAPI' : 'Python';
+    return `# ${distributionName}
+
+${stackLabel} project scaffolded by \`claude-autopilot scaffold --from-spec\`.
+
+## Install
+
+\`\`\`bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e .
+\`\`\`
+
+## Test
+
+\`\`\`bash
+pytest
+\`\`\`
+`;
+}
+/**
+ * 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 async function scaffoldPython(ctx, opts) {
+    const { cwd, parsed, dryRun } = ctx;
+    const { isFastapi } = opts;
+    const distributionName = normalizeDistributionName(path.basename(cwd));
+    const packageName = packageNameFromDistribution(distributionName);
+    const filesCreated = [];
+    const filesSkippedExisting = [];
+    const dirsCreated = [];
+    // We treat these as "managed" — we generate them with content, not
+    // empty placeholders, so the spec's bullet-list entries for them
+    // don't get touched first.
+    const MANAGED_FILES = new Set([
+        'pyproject.toml',
+        'requirements.txt', // we don't generate this, but if listed we leave it
+        `src/${packageName}/__init__.py`,
+        `src/${packageName}/main.py`,
+        'tests/test_main.py',
+        'README.md',
+    ]);
+    // 1) Create directories. Always include the package + tests dirs;
+    //    plus any dirs implied by spec paths.
+    const dirs = new Set([`src/${packageName}`, 'tests']);
+    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) Touch placeholder files for any spec paths we don't manage.
+    for (const p of parsed.paths) {
+        if (MANAGED_FILES.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 });
+            await fsAsync.writeFile(abs, '', 'utf8');
+        }
+        filesCreated.push(p);
+        console.log(`  ${PASS}  touch   ${DIM(p)}`);
+    }
+    // 3) src/<package_name>/__init__.py
+    const initRel = `src/${packageName}/__init__.py`;
+    const initAbs = path.join(cwd, initRel);
+    if (fs.existsSync(initAbs)) {
+        filesSkippedExisting.push(initRel);
+        console.log(`  ${SKIP}  exists  ${DIM(initRel)}`);
+    }
+    else {
+        if (!dryRun)
+            await fsAsync.writeFile(initAbs, '', 'utf8');
+        filesCreated.push(initRel);
+        console.log(`  ${PASS}  touch   ${DIM(initRel)}`);
+    }
+    // 4) FastAPI-only: main.py + tests/test_main.py
+    if (isFastapi) {
+        const mainRel = `src/${packageName}/main.py`;
+        const mainAbs = path.join(cwd, mainRel);
+        if (fs.existsSync(mainAbs)) {
+            filesSkippedExisting.push(mainRel);
+            console.log(`  ${SKIP}  exists  ${DIM(mainRel)}`);
+        }
+        else {
+            if (!dryRun)
+                await fsAsync.writeFile(mainAbs, buildFastapiMain(packageName), 'utf8');
+            filesCreated.push(mainRel);
+            console.log(`  ${PASS}  write   ${DIM(`${mainRel} (FastAPI app + /health + run())`)}`);
+        }
+        const testRel = 'tests/test_main.py';
+        const testAbs = path.join(cwd, testRel);
+        if (fs.existsSync(testAbs)) {
+            filesSkippedExisting.push(testRel);
+            console.log(`  ${SKIP}  exists  ${DIM(testRel)}`);
+        }
+        else {
+            if (!dryRun)
+                await fsAsync.writeFile(testAbs, buildFastapiTest(packageName), 'utf8');
+            filesCreated.push(testRel);
+            console.log(`  ${PASS}  write   ${DIM(`${testRel} (smoke test for /health)`)}`);
+        }
+    }
+    // 5) pyproject.toml
+    const pyprojectAbs = path.join(cwd, 'pyproject.toml');
+    if (fs.existsSync(pyprojectAbs)) {
+        filesSkippedExisting.push('pyproject.toml');
+        console.log(`  ${SKIP}  exists  ${DIM('pyproject.toml (preserved)')}`);
+    }
+    else {
+        const dependencies = buildPythonDependencies(parsed.packageHints.pythonDeps, isFastapi);
+        const body = buildPyproject({ distributionName, packageName, dependencies, isFastapi });
+        if (!dryRun)
+            await fsAsync.writeFile(pyprojectAbs, body, 'utf8');
+        filesCreated.push('pyproject.toml');
+        const flavor = isFastapi ? 'PEP 621 + hatchling + FastAPI deps' : 'PEP 621 + hatchling';
+        console.log(`  ${PASS}  write   ${DIM(`pyproject.toml (${flavor})`)}`);
+    }
+    // 6) README.md — codex NOTE #1 (always create, never overwrite).
+    const readmeAbs = path.join(cwd, 'README.md');
+    if (fs.existsSync(readmeAbs)) {
+        filesSkippedExisting.push('README.md');
+        console.log(`  ${SKIP}  exists  ${DIM('README.md (preserved)')}`);
+    }
+    else {
+        if (!dryRun)
+            await fsAsync.writeFile(readmeAbs, buildReadme(distributionName, isFastapi), 'utf8');
+        filesCreated.push('README.md');
+        console.log(`  ${PASS}  write   ${DIM('README.md')}`);
+    }
+    return {
+        filesCreated,
+        dirsCreated,
+        filesSkippedExisting,
+        // Node-shape fields — we never touch package.json / tsconfig in Python.
+        packageJsonAction: 'skipped-exists',
+        tsconfigAction: 'skipped-no-ts',
+    };
+}
+//# sourceMappingURL=python.js.map

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

@@ -0,0 +1,68 @@
+/** Supported `--stack` values. v7.5+ will add 'go', 'rust', 'ruby'. */
+export type Stack = 'node' | 'python' | 'fastapi';
+/**
+ * Stacks we can DETECT but cannot scaffold yet. Detection still warns +
+ * exits 3 so the operator gets a clear "v7.5" diagnostic instead of a
+ * silent fallback to Node, which would generate a wrong-language skeleton.
+ */
+export type UnsupportedStack = 'go' | 'rust' | 'ruby';
+export interface ParsedFiles {
+    /** Raw paths extracted from the `## Files` section bullets. */
+    paths: string[];
+    /** Loosely-parsed package.json hints found anywhere in the section. */
+    packageHints: {
+        bin?: Record<string, string>;
+        type?: 'module' | 'commonjs';
+        dependencies?: Record<string, string>;
+        devDependencies?: Record<string, string>;
+        scripts?: Record<string, string>;
+        /**
+         * Best-effort stack hint from prose ("uses fastapi", "Python 3.12",
+         * "Node 22 ESM"). Used as a tie-breaker when path heuristics are
+         * ambiguous between Python and FastAPI.
+         */
+        stackHint?: 'node' | 'python' | 'fastapi';
+        /**
+         * Extra Python dependency strings extracted via the narrow contract
+         * documented in the spec ("Dependency hint extraction"):
+         *   - explicit `dependencies: [...]` block in spec prose
+         *   - backticked package names with extras (`uvicorn[standard]`)
+         *   - phrase `depends on <name>`
+         *
+         * Stored verbatim — never version-inferred. Deduped by
+         * PEP 503 normalized name in the Python scaffolder.
+         */
+        pythonDeps?: string[];
+    };
+}
+export interface ScaffoldOptions {
+    cwd?: string;
+    specPath: string;
+    /** When true, log what would happen but don't write anything. */
+    dryRun?: boolean;
+    /**
+     * Explicit stack override. When provided, skips path-based detection
+     * (but still validates the value: unknown → exit 3). v7.4.0 ships
+     * 'node' | 'python' | 'fastapi'.
+     */
+    stack?: Stack;
+}
+export interface ScaffoldResult {
+    filesCreated: string[];
+    dirsCreated: string[];
+    filesSkippedExisting: string[];
+    /** Node-only metadata; Python scaffolder leaves these as 'skipped-no-ts' / 'skipped-exists'. */
+    packageJsonAction: 'created' | 'merged' | 'skipped-exists';
+    tsconfigAction: 'created' | 'skipped-exists' | 'skipped-no-ts';
+    /** v7.4.0 — which stack was used. Useful for tests and for the CLI banner. */
+    stack?: Stack;
+    /** Names of files explicitly skipped because of `--stack` filtering (codex W5). */
+    ignoredOtherStackFiles?: string[];
+}
+/** Per-stack scaffolders share this small context. */
+export interface ScaffoldRunContext {
+    cwd: string;
+    parsed: ParsedFiles;
+    dryRun: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1,6 @@
+// v7.4.0 — shared types for per-stack scaffolders. Lives in its own file
+// (rather than ../scaffold.ts) so that node.ts and python.ts can both import
+// from it without creating a circular dependency back to the public entry
+// module.
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -1,39 +1,53 @@
-export interface ScaffoldOptions {
-    cwd?: string;
-    specPath: string;
-    /** When true, log what would happen but don't write anything. */
-    dryRun?: boolean;
-}
-export interface ScaffoldResult {
-    filesCreated: string[];
-    dirsCreated: string[];
-    filesSkippedExisting: string[];
-    packageJsonAction: 'created' | 'merged' | 'skipped-exists';
-    tsconfigAction: 'created' | 'skipped-exists' | 'skipped-no-ts';
-}
-interface ParsedFiles {
-    /** Raw paths extracted from the `## Files` section bullets. */
-    paths: string[];
-    /** Loosely-parsed package.json hints found anywhere in the section. */
-    packageHints: {
-        bin?: Record<string, string>;
-        type?: 'module' | 'commonjs';
-        dependencies?: Record<string, string>;
-        devDependencies?: Record<string, string>;
-        scripts?: Record<string, string>;
-    };
-}
+import { buildStarterPackageJson } from './scaffold/node.ts';
+import type { ParsedFiles, ScaffoldOptions, ScaffoldResult, Stack, UnsupportedStack } from './scaffold/types.ts';
+export { buildStarterPackageJson };
+export type { ScaffoldOptions, ScaffoldResult, ParsedFiles, Stack };
+/** Valid `--stack` argument values. v7.5+ adds 'go', 'rust', 'ruby'. */
+export declare const SUPPORTED_STACKS: readonly Stack[];
+/** Stacks we DETECT-but-don't-support yet. Mapped to spec exit-3 messages. */
+export declare const UNSUPPORTED_STACK_FILES: Record<UnsupportedStack, string>;
 /**
  * Parse the `## Files` (or `## files`) section of a spec markdown file.
  * Tolerant: missing section returns `null`; malformed bullets are skipped
  * silently. Returns extracted file paths + best-effort package-hint blob.
+ *
+ * v7.4.0 also extracts:
+ *   - `stackHint` — first prose mention of `fastapi` / `python` / `node`
+ *     (case-insensitive). Used as a tie-breaker when path heuristics are
+ *     ambiguous between Python and FastAPI.
+ *   - `pythonDeps` — narrow extraction per spec ("Dependency hint
+ *     extraction"): explicit `dependencies: [...]` block, backticked
+ *     package names with extras, and the phrase `depends on <name>`.
  */
 export declare function parseSpecFiles(markdown: string): ParsedFiles | null;
 /**
- * Build a minimal starter package.json. Caller passes in any explicit
- * hints (parsed from spec); we layer Node 22 ESM defaults on top.
+ * Result of stack detection. `kind` is one of:
+ *   - 'resolved'    — `stack` is set; proceed.
+ *   - 'unsupported' — detected an unsupported stack file (Go/Rust/Ruby).
+ *                     Caller exits 3 with `message`.
+ *   - 'polyglot'    — both Node + Python markers present without --stack.
+ *                     Caller exits 3 with `message`.
  */
-export declare function buildStarterPackageJson(projectName: string, hints: ParsedFiles['packageHints']): Record<string, unknown>;
+export type StackDetection = {
+    kind: 'resolved';
+    stack: Stack;
+} | {
+    kind: 'unsupported';
+    stack: UnsupportedStack;
+    message: string;
+} | {
+    kind: 'polyglot';
+    message: string;
+};
+/**
+ * Apply the precedence ladder documented at the top of this file. Pure
+ * function — no I/O — so it's directly unit-testable.
+ */
+export declare function detectStack(parsed: ParsedFiles, explicit?: Stack): StackDetection;
+/**
+ * Print the `--list-stacks` output (codex NOTE #2). Three sections:
+ * Supported, Auto-detected, Recognized-but-unsupported.
+ */
+export declare function printStackList(): void;
 export declare function runScaffold(opts: ScaffoldOptions): Promise<ScaffoldResult>;
-export {};
 //# sourceMappingURL=scaffold.d.ts.map