@drawcall/create 0.1.3 → 0.2.0

package/dist/supervisor.d.ts

@@ -1,28 +1,32 @@
+import { Duration, Effect } from "effect";
+import { type FailureReason } from "./classify.js";
 import { type HarnessName } from "./constants.js";
-import { type CommandResult } from "./subprocess.js";
-export type RunBuildTurnChild = (cwd: string) => Promise<CommandResult>;
-export type SuperviseBuildOptions = {
-    cwd?: string;
-    env?: NodeJS.ProcessEnv;
-    maxTurns?: number;
-    harness?: HarnessName;
-    harnessArgs?: string[];
-    harnessTimeoutMinutes?: number;
-    runBuildTurnChild?: RunBuildTurnChild;
-};
-export type SuperviseBuildResult = {
-    projectDir: string;
-    turns: number;
-    /** Why the loop stopped — surfaced to the caller and the session log. */
-    stop: "plan-consumed" | "budget-exhausted" | "stuck";
-};
-/**
- * Run the build stage so it ALWAYS completes or cleanly resumes, even when a turn's child process
- * is killed mid-turn by an uncatchable OOM/jetsam SIGKILL. Each turn runs as a separate child, so
- * this supervisor holds almost no memory and is an unlikely OOM victim itself; if a turn-child dies
- * without committing, the supervisor resets to the last known-good commit and retries.
- *
- * The repo must already be scaffolded, surveyed, and planned (a committed PLAN.md) — run the
- * earlier stages with a normal `createProject` first. This is the build loop only.
- */
-export declare function superviseBuild(options?: SuperviseBuildOptions): Promise<SuperviseBuildResult>;
+import { PreflightError } from "./errors.js";
+import { Git } from "./git.js";
+import { Harness } from "./harness.js";
+import { Logger } from "./logger.js";
+import { Scaffold } from "./scaffold.js";
+export interface RunOptions {
+    readonly prompt?: string;
+    readonly cwd?: string;
+    readonly resume?: boolean;
+    readonly projectName?: string;
+    readonly here?: boolean;
+    readonly harness?: HarnessName;
+    readonly harnessArgs?: ReadonlyArray<string>;
+    readonly harnessTimeoutMs?: number;
+    readonly maxTurns?: number;
+    readonly skipTemplate?: boolean;
+    readonly backoff?: (attempt: number) => Duration.Duration;
+}
+export type Outcome = "done" | "stuck" | "budget-exhausted";
+export interface RunResult {
+    readonly projectDir: string;
+    readonly outcome: Outcome;
+    readonly staleAttempts: number;
+    readonly errors: ReadonlyArray<FailureReason>;
+    readonly buildTurns: number;
+}
+type Env = Harness | Scaffold | Git | Logger;
+export declare const run: (options: RunOptions) => Effect.Effect<RunResult, PreflightError, Env>;
+export {};

package/dist/supervisor.js

@@ -1,110 +1,154 @@
-import { execFileSync } from "node:child_process";
-import { appendFileSync, existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { CliError, MAX_BUILD_TURNS, PLAN_FILE, SESSION_LOG_FILE } from "./constants.js";
-import { createSubprocessRunner } from "./subprocess.js";
-// Two consecutive turns that neither advance HEAD with real work nor touch PLAN.md mean the build
-// is wedged (a turn that keeps crashing the same way, or a no-op turn the harness can't get past).
-// Stopping then is honest: looping further just burns hours re-running the identical dead step.
-const STUCK_ATTEMPT_LIMIT = 2;
-/**
- * Run the build stage so it ALWAYS completes or cleanly resumes, even when a turn's child process
- * is killed mid-turn by an uncatchable OOM/jetsam SIGKILL. Each turn runs as a separate child, so
- * this supervisor holds almost no memory and is an unlikely OOM victim itself; if a turn-child dies
- * without committing, the supervisor resets to the last known-good commit and retries.
- *
- * The repo must already be scaffolded, surveyed, and planned (a committed PLAN.md) — run the
- * earlier stages with a normal `createProject` first. This is the build loop only.
- */
-export async function superviseBuild(options = {}) {
-    const cwd = resolve(options.cwd ?? process.cwd());
-    const env = options.env ?? process.env;
-    const maxTurns = options.maxTurns ?? MAX_BUILD_TURNS;
-    const runBuildTurnChild = options.runBuildTurnChild ?? defaultRunBuildTurnChild(env, options);
-    if (!existsSync(join(cwd, ".git"))) {
-        throw new CliError(`supervised build expects an existing git repo at ${cwd}`);
-    }
-    const planPath = join(cwd, PLAN_FILE);
-    let staleAttempts = 0;
-    for (let turn = 1; turn <= maxTurns; turn += 1) {
-        if (!existsSync(planPath))
-            return done(cwd, turn - 1, "plan-consumed");
-        // The soccer hazard: a prior turn killed mid-edit can leave the tree dirty with partial,
-        // partially-destructive changes (e.g. half-deleted source). Build turns re-read repo state and
-        // redo the step, so resume ONLY from a clean committed state. `clean -fd` (not -x) preserves
-        // node_modules and the gitignored surveys/proof scratch; never `git add -A` here.
-        resetToLastGoodCommit(cwd);
-        const before = captureProgressMarker(cwd, planPath);
-        await runBuildTurnChild(cwd);
-        const after = captureProgressMarker(cwd, planPath);
-        if (!existsSync(planPath))
-            return done(cwd, turn, "plan-consumed");
-        if (madeProgress(before, after)) {
-            staleAttempts = 0;
-            continue;
-        }
-        staleAttempts += 1;
-        if (staleAttempts >= STUCK_ATTEMPT_LIMIT) {
-            logToSession(cwd, `[drawcall-create] supervised build stuck: ${STUCK_ATTEMPT_LIMIT} turns with no new commit and no ${PLAN_FILE} change`);
-            return done(cwd, turn, "stuck");
-        }
-    }
-    return done(cwd, maxTurns, existsSync(planPath) ? "budget-exhausted" : "plan-consumed");
-}
-function madeProgress(before, after) {
-    return after.head !== before.head || after.planText !== before.planText;
+import { Console, Duration, Effect } from "effect";
+import { humanReason } from "./classify.js";
+import { MAX_BUILD_TURNS } from "./constants.js";
+import { PreflightError, reasonOf } from "./errors.js";
+import { Git } from "./git.js";
+import { Harness } from "./harness.js";
+import { Logger } from "./logger.js";
+import { planNext } from "./resume.js";
+import { buildTurn, runStage } from "./stages.js";
+// How many consecutive attempts that make NO forward progress before we stop. Forward progress
+// resets it to zero — so a long run only gives up when it is genuinely wedged, never on cumulative
+// failures across hours of real work.
+const MAX_STALE_ATTEMPTS = 3;
+const BACKOFF_BASE = Duration.seconds(10);
+const BACKOFF_CAP = Duration.minutes(5);
+function backoff(attempt) {
+    const ms = Math.min(Duration.toMillis(BACKOFF_BASE) * 2 ** (attempt - 1), Duration.toMillis(BACKOFF_CAP));
+    return Duration.millis(ms);
 }
-function captureProgressMarker(cwd, planPath) {
-    return {
-        head: headCommit(cwd),
-        planText: existsSync(planPath) ? readFileSync(planPath, "utf8") : ""
+// The progress fingerprint: newest stage marker + HEAD's tree hash. An --allow-empty checkpoint
+// changes neither the tree nor the marker (for a repeating build turn), so a turn that did nothing
+// real cannot move it — which is exactly what makes "no forward progress" honest.
+const fingerprint = (cwd) => Effect.gen(function* () {
+    const git = yield* Git;
+    const marker = yield* git.latestStage(cwd);
+    const tree = yield* git.treeHash(cwd);
+    return `${marker ?? "none"}:${tree}`;
+});
+const totalBuildTurns = (cwd) => Effect.gen(function* () {
+    const git = yield* Git;
+    return (yield* git.countStage(cwd, "build")) + (yield* git.countStage(cwd, "done"));
+});
+const note = (text) => Effect.flatMap(Logger, (logger) => logger.write(`[create] ${text}`));
+export const run = (options) => Effect.gen(function* () {
+    const resolved = yield* resolveProject(options);
+    const harnessSvc = yield* Harness;
+    const harness = yield* harnessSvc.select(options.harness ?? resolved.harness);
+    const ctx = {
+        cwd: resolved.cwd,
+        prompt: resolved.prompt,
+        harness,
+        harnessArgs: options.harnessArgs ?? resolved.harnessArgs,
+        timeoutMs: options.harnessTimeoutMs ?? resolved.harnessTimeoutMs,
+        skipTemplate: options.skipTemplate ?? resolved.skipTemplate
     };
-}
-// HEAD's commit hash, or "" before the first commit exists. `git rev-parse HEAD` throws on an empty
-// repo, which we read as "no commit yet" rather than a failure.
-function headCommit(cwd) {
-    try {
-        return execFileSync("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf8" }).trim();
+    const maxTurns = options.maxTurns ?? resolved.maxTurns ?? MAX_BUILD_TURNS;
+    // The metadata stamped onto the scaffold checkpoint so a later `--resume` reproduces this run.
+    const runMeta = {
+        prompt: ctx.prompt,
+        harness,
+        harnessArgs: ctx.harnessArgs,
+        harnessTimeoutMs: ctx.timeoutMs,
+        maxTurns,
+        skipTemplate: ctx.skipTemplate
+    };
+    return yield* loop(ctx, runMeta, maxTurns, options.backoff ?? backoff, {
+        staleAttempts: 0,
+        errors: []
+    });
+});
+const loop = (ctx, runMeta, maxTurns, backoffFor, state) => Effect.gen(function* () {
+    const git = yield* Git;
+    const before = yield* fingerprint(ctx.cwd);
+    const step = yield* planNext(ctx.cwd);
+    if (step._tag === "done") {
+        return finish(ctx.cwd, "done", { staleAttempts: 0, errors: [] }, yield* totalBuildTurns(ctx.cwd));
     }
-    catch {
-        return "";
+    const turns = yield* totalBuildTurns(ctx.cwd);
+    if (step.stage === "build" && turns >= maxTurns) {
+        return finish(ctx.cwd, "budget-exhausted", state, turns);
     }
-}
-function resetToLastGoodCommit(cwd) {
-    execFileSync("git", ["reset", "--hard", "HEAD"], { cwd, stdio: "ignore" });
-    execFileSync("git", ["clean", "-fd"], { cwd, stdio: "ignore" });
-}
-function done(cwd, turns, stop) {
-    return { projectDir: cwd, turns, stop };
-}
-function logToSession(cwd, line) {
-    try {
-        appendFileSync(join(cwd, SESSION_LOG_FILE), `${line}\n`);
+    yield* Console.log(`→ ${label(step.stage, ctx.harness)}`);
+    const work = step.stage === "build"
+        ? buildTurn(ctx, turns + 1)
+        : runStage(step.stage, ctx, step.stage === "scaffold" ? runMeta : undefined);
+    const outcome = yield* Effect.either(work);
+    let reason;
+    if (outcome._tag === "Left") {
+        reason = reasonOf(outcome.left);
+        yield* Console.error(`✕ ${label(step.stage, ctx.harness)} — ${humanReason(reason)}`);
+        yield* note(`${step.stage} failed: ${humanReason(reason)}`);
+        // Resume only from a clean committed state. If even the reset fails (rare), surface it to the
+        // log and still loop — aborting the whole run over a failed cleanup would be worse, and a
+        // genuinely wedged tree is caught by the no-progress stop anyway.
+        yield* git
+            .resetClean(ctx.cwd)
+            .pipe(Effect.catchAll((failure) => note(`reset to clean state failed: ${failure.detail}`)));
+    }
+    const after = yield* fingerprint(ctx.cwd);
+    if (after !== before) {
+        if (outcome._tag === "Right")
+            yield* Console.log(`✓ ${label(step.stage, ctx.harness)}`);
+        // Forward progress — reset the stale counter and the error accumulator; only the failures that
+        // actually precede a stop should appear in its report.
+        return yield* loop(ctx, runMeta, maxTurns, backoffFor, { staleAttempts: 0, errors: [] });
     }
-    catch {
-        // No session log on disk (e.g. a test working dir) — the supervisor proceeds anyway.
+    const staleAttempts = state.staleAttempts + 1;
+    const errors = reason ? [...state.errors, reason] : state.errors;
+    if (outcome._tag === "Right")
+        yield* note(`${step.stage} made no changes`);
+    if (staleAttempts >= MAX_STALE_ATTEMPTS) {
+        return finish(ctx.cwd, "stuck", { staleAttempts, errors }, yield* totalBuildTurns(ctx.cwd));
     }
+    yield* note(`no progress; attempt ${staleAttempts}/${MAX_STALE_ATTEMPTS}, backing off`);
+    yield* Effect.sleep(backoffFor(staleAttempts));
+    return yield* loop(ctx, runMeta, maxTurns, backoffFor, { staleAttempts, errors });
+});
+const finish = (projectDir, outcome, state, buildTurns) => ({
+    projectDir,
+    outcome,
+    staleAttempts: state.staleAttempts,
+    errors: state.errors,
+    buildTurns
+});
+function label(stage, harness) {
+    return stage === "scaffold" ? "scaffolding" : `${stage} (${harness})`;
 }
-// Re-invoke this CLI's own build stage as a fresh child: `--stage build` runs exactly one turn
-// (create.ts turnBudget), so the heavy turn state lives and dies in the child, not in the
-// supervisor. cli.js sits next to this compiled module.
-function defaultRunBuildTurnChild(env, options) {
-    const cliPath = fileURLToPath(new URL("./cli.js", import.meta.url));
-    const runner = createSubprocessRunner({ env, stdio: "inherit" });
-    const args = [cliPath, "--stage", "build"];
-    if (options.harness)
-        args.push("--harness", options.harness);
-    if (options.harnessTimeoutMinutes !== undefined) {
-        args.push("--harness-timeout-minutes", String(options.harnessTimeoutMinutes));
+// A new run creates (or adopts, with --here) the project directory; a resume reads the run metadata
+// back out of git history so it continues with nothing re-typed.
+const resolveProject = (options) => options.resume ? resolveResume(options) : resolveNew(options);
+const resolveResume = (options) => Effect.gen(function* () {
+    const git = yield* Git;
+    const cwd = resolve(options.cwd ?? process.cwd());
+    if (!existsSync(join(cwd, ".git"))) {
+        return yield* Effect.fail(new PreflightError({ message: `${cwd} is not a drawcall-create project (no .git)` }));
     }
-    args.push(BUILD_RESUME_PROMPT);
-    if (options.harnessArgs && options.harnessArgs.length > 0) {
-        args.push("--", ...options.harnessArgs);
+    const meta = yield* git.readRunMeta(cwd);
+    const prompt = options.prompt ?? meta?.prompt;
+    if (!prompt) {
+        return yield* Effect.fail(new PreflightError({
+            message: `cannot resume ${cwd}: no recorded prompt — pass the prompt to resume this run`
+        }));
     }
-    return (cwd) => runner({ command: process.execPath, args, cwd });
-}
-// The build stage re-reads the committed records (GOAL.md/PLAN.md/README.md) and continues the
-// plan, so the prompt is just a resume marker — the real instructions live in the build prompt the
-// child assembles. The CLI requires a non-empty prompt.
-const BUILD_RESUME_PROMPT = "resume the build from the committed plan";
+    return {
+        cwd,
+        prompt,
+        harness: meta?.harness,
+        harnessArgs: meta?.harnessArgs,
+        harnessTimeoutMs: meta?.harnessTimeoutMs,
+        maxTurns: meta?.maxTurns,
+        skipTemplate: meta?.skipTemplate
+    };
+});
+// The project directory is computed and created by the CLI before the Effect program starts (the log
+// layer needs the path up front), so here we only validate the prompt and trust the resolved cwd.
+const resolveNew = (options) => Effect.gen(function* () {
+    const prompt = options.prompt?.trim();
+    if (!prompt) {
+        return yield* Effect.fail(new PreflightError({ message: "a prompt is required for a new run" }));
+    }
+    return { cwd: resolve(options.cwd ?? process.cwd()), prompt };
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drawcall/create",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "type": "module",
   "description": "Create projects with an installed local harness.",
   "license": "MIT",
@@ -35,6 +35,7 @@
   },
   "dependencies": {
     "commander": "^14.0.3",
+    "effect": "^3.21.4",
     "which": "^6.0.1"
   },
   "devDependencies": {

package/dist/create.d.ts

@@ -1,35 +0,0 @@
-import { type HarnessName, type Stage } from "./constants.js";
-import { type HarnessRunner } from "./harness.js";
-import { type CommandExists, type CommandRunner } from "./subprocess.js";
-import { ProgressLog } from "./progress-log.js";
-export type CreateProjectOptions = {
-    cwd?: string;
-    env?: NodeJS.ProcessEnv;
-    stage?: Stage;
-    harness?: HarnessName;
-    harnessArgs?: string[];
-    harnessTimeoutMs?: number;
-    maxTurns?: number;
-    projectName?: string;
-    skipTemplate?: boolean;
-    runner?: CommandRunner;
-    commandExists?: CommandExists;
-};
-export type CreateProjectResult = {
-    projectDir: string;
-    projectName: string;
-    harness: HarnessName;
-    exitCode: number;
-    turns: number;
-    maxTurns: number;
-    durationMs: number;
-};
-export declare function createProject(prompt: string, options?: CreateProjectOptions): Promise<CreateProjectResult>;
-/** Build-stage: loop build-turns against the plan up to the build-turn-budget. */
-export declare function runBuildTurns(harnessRunner: HarnessRunner, userPrompt: string, options?: {
-    maxTurns?: number;
-    progressLog?: ProgressLog;
-}): Promise<{
-    exitCode: number;
-    turns: number;
-}>;