@drawcall/create 0.0.0

package/README.md

@@ -0,0 +1,249 @@
+# @drawcall/create
+
+`@drawcall/create` is the project creator for the Drawcall 3D app/game stack. It does more than create files: it starts a new repo, installs the local agent toolkit, runs a harness to survey the available Drawcall assets and technologies, turns the user's prompt into a fixed goal, writes a plan, and then runs build turns until the plan is closed or the turn budget is reached.
+
+The package is a local-orchestration layer over the rest of the Drawcall workspace. The sibling projects provide the actual capabilities:
+
+- `../skills` routes an agent from a topic in the user's goal to the right technology, pattern, and quality bar.
+- `../market` provides access to semantically searchable templates and assets.
+- `../acta` provides 3D character behavior and animation logic.
+- `../uikitml` provides spatial/XR UI authoring and conversion.
+- `../vitexec` provides runtime proof from inside a running Vite app.
+- `../speech` provides text-to-speech for apps that need voice output.
+- `../flipbook` allows to render flipbook animations.
+
+`create` is the glue that installs those capabilities into a generated project and gives the selected harness a staged way to use them without shrinking the user's goal into a nominal prototype.
+
+## Why This Exists
+
+The hard part of AI-generated 3D apps is not making the first canvas appear. It is keeping each harness turn grounded in what is real:
+
+- what the user actually asked for,
+- what the current product actually does,
+- which assets and technologies actually fit,
+- what still remains,
+- and what has been proven in the running product.
+
+`@drawcall/create` turns that into a small set of records and stages. A turn either thinks and writes context, or builds and proves a slice. The harness is never supposed to silently replace the goal with a smaller demo just because a part is hard or no fitting tool exists.
+
+## Pipeline
+
+The full pipeline is:
+
+```text
+scaffold -> (template || survey-assets || survey-technology) -> goal -> plan -> build...
+```
+
+The middle group runs concurrently during a `full` run because those stages write disjoint outputs:
+
+- `template` may apply a fitting Market starter into the product.
+- `survey-assets` writes a scratch survey of fitting Market assets.
+- `survey-technology` writes a scratch survey of fitting installed skills and packages.
+
+After that barrier, the `goal` stage writes the goal record, the `plan` stage writes ordered build steps, and each `build` turn implements the first remaining step, proves it in the real product, and updates the records.
+
+## Records
+
+Generated projects use three committed records:
+
+| File        | Role                                                              |
+| ----------- | ----------------------------------------------------------------- |
+| `README.md` | State record: what the product actually is right now.             |
+| `GOAL.md`   | Goal record: the fixed finished product and what real-done means. |
+| `PLAN.md`   | Plan record: ordered steps from current state to goal.            |
+
+They also use scratch files that should not be committed:
+
+| File                    | Role                                                                           |
+| ----------------------- | ------------------------------------------------------------------------------ |
+| `surveys/ASSETS.md`     | Asset survey: fitting Market templates/assets and named fit-gaps.              |
+| `surveys/TECHNOLOGY.md` | Technology survey: fitting installed skills/packages and the APIs that matter. |
+| `proof/`                | Screenshots, clips, traces, and other proof files.                             |
+| `drawcall-create.log`   | Full subprocess session log.                                                   |
+
+The surveys are deliberately scratch. They ground the goal and plan stages, but the lasting truth of the project lives in `README.md`, `GOAL.md`, and `PLAN.md`.
+
+## Stages
+
+`drawcall-create` exposes the pipeline as stages:
+
+| Stage               | What it does                                                                                                                                        |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `scaffold`          | Creates a new repo, base folders, `.gitignore`, package file, installed skills, and npm dependencies. No harness turn and no README.                |
+| `template`          | Runs one harness turn to search `@drawcall/market` for a fitting starter and apply it into the existing repo. Ensures a state-record README exists. |
+| `survey-assets`     | Runs one survey turn and writes `surveys/ASSETS.md`.                                                                                                |
+| `survey-technology` | Runs one survey turn and writes `surveys/TECHNOLOGY.md`.                                                                                            |
+| `goal`              | Writes `GOAL.md` from the user's prompt, current state, and surveys.                                                                                |
+| `plan`              | Writes `PLAN.md` from the fixed goal, current state, and surveys, then updates `README.md`.                                                         |
+| `build`             | Runs one build turn against the first remaining plan step.                                                                                          |
+| `full`              | Runs the whole chain, then loops build turns up to the configured turn budget.                                                                      |
+
+Stages after `scaffold` operate on an existing git repo in the current directory. `full` and `scaffold` create a new project directory.
+
+## CLI
+
+```sh
+npm run dev -- --name my-game "make a third-person island adventure"
+```
+
+After publishing/building, the binary is:
+
+```sh
+drawcall-create --name my-game "make a third-person island adventure"
+```
+
+Useful options:
+
+```sh
+drawcall-create --stage scaffold --name my-game "make a marble maze"
+drawcall-create --stage template "make a marble maze"
+drawcall-create --stage survey-assets "make a marble maze"
+drawcall-create --stage survey-technology "make a marble maze"
+drawcall-create --stage goal "make a marble maze"
+drawcall-create --stage plan "make a marble maze"
+drawcall-create --stage build "make a marble maze"
+
+drawcall-create --harness codex "make a marble maze"
+drawcall-create --harness-timeout-minutes 30 "make a marble maze"
+drawcall-create --max-turns 5 "make a marble maze"
+drawcall-create --skip-template "make a marble maze"
+drawcall-create "make a marble maze" -- --model gpt-5
+```
+
+Supported harnesses are `opencode`, `codex`, `claude`, `pi`, and `gemini`. If no harness is specified, `create` picks the first supported command available on `PATH`.
+
+Each harness invocation defaults to a 20 minute timeout. A `full` run defaults to 10 build turns.
+Use `--skip-template` on a `full` run to skip starter-template search and build from scratch while still surveying assets and technology.
+
+## Installed Toolkit
+
+Fresh projects get agent skills from:
+
+- `drawcall-ai/vitexec`
+- `drawcall-ai/uikitml`
+- `drawcall-ai/acta`
+- `drawcall-ai/market`
+- `drawcall-ai/speech`
+- `drawcall-ai/flipbook`
+- `drawcall-ai/skills`
+
+Fresh projects also install the runtime packages that those skills commonly route to:
+
+- `vitexec`
+- `@drawcall/uikitml`
+- `@drawcall/acta`
+- `@drawcall/market`
+- `@drawcall/flipbook`
+- `@pmndrs/uikit`
+- `@pmndrs/pointer-events`
+- `@pmndrs/viverse`
+- `navcat`
+- `three`
+- `vite`
+- `typescript`
+- `elics`
+- `postprocessing`
+
+`create` also patches local CLI shims for `@drawcall/acta` and `@drawcall/market` after installation so their CLIs resolve correctly inside a fresh generated project.
+
+## Related Projects
+
+### `../skills`
+
+`../skills` is the general Drawcall skill pack. It is not one runtime library; it is the routing layer that teaches a harness which technology and pattern to use for a need in a 3D app.
+
+Its skills cover:
+
+- actions and input mapping through `@pmndrs/viverse`,
+- audio coverage for feedback moments,
+- camera behavior and camera math,
+- ECS structure with `elics`,
+- lighting and cascaded shadows,
+- materials, textures, and color space,
+- navigation meshes with `navcat`,
+- performance profiling and optimization,
+- BVH character physics through `@pmndrs/viverse`,
+- pointer events through `@pmndrs/pointer-events`,
+- postprocessing,
+- spatial vs. 2D user interface routing,
+- VFX and particles,
+- world scale, terrain, fog, horizon, and density.
+
+This repository installs `drawcall-ai/skills` so the technology-survey can map a user goal like "open-world shooter" to the specific skills and packages that carry world scale, input, camera, navigation, character motion, effects, UI, proof, and performance.
+
+### `../market`
+
+`../market` is the asset marketplace. It defines versioned asset types such as `model`, `humanoid-model`, `texture`, `humanoid-animation`, `template`, `sound-effect`, `background-music`, `environment`, and `flipbook`.
+
+`create` uses it in two places:
+
+- the `template` stage searches for a fitting starter template and applies it into the generated repo;
+- the `asset-survey` searches and previews assets so the later goal and plan can choose real content instead of vague placeholders.
+
+Generated projects get the `@drawcall/market` package and the `market` skill so harnesses can search, preview, install, and reason about assets with the real CLI and API.
+
+### `../acta`
+
+`../acta` is the character-behavior system. Acta behavior JSON describes locomotion, actions, animation states, timed effects, movement output, and jump output for Three.js characters. It supports playable characters, NPCs, enemies, companions, and crowds.
+
+In generated projects, Acta is the preferred fit when the user asks for an embodied thing that moves, acts, aims, jumps, attacks, or reacts. The harness can validate behavior JSON, test animation/effect timelines, or convert behavior JSON into TypeScript character classes.
+
+### `../uikitml`
+
+`../uikitml` is an HTML-like markup format and CLI for spatial UI. Harnesses can write `.uikitml`, validate it, render a preview, and convert it into Three.js, React Three Fiber, IWSDK, or pmndrs/uikit code.
+
+The general `../skills` UI skill routes UI work:
+
+- spatial or XR panels use `drawcall-ai/uikitml`;
+- ordinary non-XR HUDs and menus can stay as HTML/CSS over the canvas.
+
+### `../vitexec`
+
+`../vitexec` lets a harness run scripts inside a live Vite app with Playwright. It can drive input, inspect runtime state, collect logs, take screenshots, record video, and capture traces.
+
+`create` treats this as the default proof tool for generated Vite/Three.js apps. A build turn is not done just because TypeScript compiles; it needs a proof-run that demonstrates the product behavior in the running app.
+
+### `../speech`
+
+`../speech` is a production REST API for text-to-speech. It is installed as an agent skill so goals involving voice, narration, NPC speech, or accessibility can route to a real service instead of hand-waving audio output.
+
+### `../flipbook`
+
+`../flipbook` provides `@drawcall/flipbook`, a tiny Three.js runtime for KTX2 flipbook billboards such as explosions, flames, and particles. Market `flipbook` assets are meant to render through this package.
+
+## Design Contract
+
+The prompts in `src/prompts.ts` enforce the same principles across all stages:
+
+- Real, not nominal: a step is done only when the product actually does the thing when run.
+- Fit the tools: use the installed Drawcall skills, packages, and Market assets where they genuinely fit.
+- Name fit-gaps honestly instead of silently substituting fake stand-ins.
+- Present feedback where the player perceives it, without debug UI leaking into the default product.
+- See and judge each step against the goal's look and feel by observing the real running product from the player's seat, iterating until it reads right — not by checking mere presence.
+- Treat moving or acting things as embodied: motion, animation, behavior, and feedback belong to the feature, not to a later polish pass.
+
+The vocabulary behind those rules lives in `LANGUAGE.md`.
+
+## Development
+
+```sh
+npm install
+npm test
+npm run typecheck
+npm run build
+```
+
+Important source files:
+
+- `src/command.ts` defines the CLI surface and argument parsing (the create-command).
+- `src/create.ts` runs the create-session: it orchestrates the pipeline of stages and the build-turn loop.
+- `src/scaffold.ts` creates the repo, installs skills/packages, commits records, and patches local CLI shims.
+- `src/harness.ts` builds the harness-command for each supported harness and bundles it as the harness-runner that runs one harness-turn.
+- `src/subprocess.ts` defines the command-runner interface and the built-in subprocess-runner (spawns the process, writes the session-log, forwards signals, enforces the timeout).
+- `src/progress-log.ts` writes progress-notes and mirrors them into the session-log.
+- `src/prompts.ts` defines the harness prompts for each stage.
+- `src/constants.ts` defines stage names, installed skills/packages, record paths, scratch paths, timeouts, and the build-turn-budget.
+
+The vocabulary used throughout (records, surveys, turns, stages, runners) is defined in `LANGUAGE.md`.
+
+The tests in `test/index.test.ts` encode the expected stage order, stage isolation, harness selection, generated files, commits, and prompt contracts.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { Command } from "commander";
+import { CliError } from "./constants.js";
+import { createCreateCommand } from "./command.js";
+const packageJson = createRequire(import.meta.url)("../package.json");
+const program = createCreateCommand(new Command(), {
+    version: packageJson.version
+});
+try {
+    await program.parseAsync(process.argv);
+}
+catch (error) {
+    if (!(error instanceof CliError))
+        throw error;
+    console.error(`error ${error.message}`);
+    process.exit(error.exitCode);
+}

package/dist/command.d.ts

@@ -0,0 +1,16 @@
+import { Command } from "commander";
+import { type HarnessName, type Stage } from "./constants.js";
+import { createProject } from "./create.js";
+export declare function createCreateCommand(command?: Command, options?: {
+    version?: string;
+    createProject?: typeof createProject;
+}): Command;
+export declare function splitHarnessArgs(args: string[]): {
+    promptParts: string[];
+    harnessArgs: string[];
+};
+export declare function parsePromptParts(promptParts: string[]): string;
+export declare function parseHarnessName(value: string | undefined): HarnessName | undefined;
+export declare function parseStage(value: string | undefined): Stage | undefined;
+export declare function parsePositiveInteger(value: string | undefined, optionName: string): number | undefined;
+export declare function parseHarnessTimeoutMs(value: string | undefined): number | undefined;

package/dist/command.js

@@ -0,0 +1,123 @@
+import { Command } from "commander";
+import { CliError, DEFAULT_HARNESS_TIMEOUT_MS, HARNESS_NAMES, MAX_BUILD_TURNS, STAGES } from "./constants.js";
+import { createProject } from "./create.js";
+import { formatDuration } from "./progress-log.js";
+const CLI_OPTION_NAMES = [
+    "--stage",
+    "--harness",
+    "--harness-timeout-minutes",
+    "--max-turns",
+    "--name",
+    "--skip-template"
+];
+export function createCreateCommand(command = new Command(), options = {}) {
+    const create = options.createProject ?? createProject;
+    command
+        .name("drawcall-create")
+        .description("Create a project with an installed local harness")
+        .argument("<args...>", "what should be created; use -- to pass following args to the harness")
+        .option("--stage <name>", `which stage to run (${STAGES.join(", ")})`)
+        .option("--harness <name>", `harness to use (${HARNESS_NAMES.join(", ")})`)
+        .option("--harness-timeout-minutes <count>", `timeout for each harness invocation in minutes (default: ${DEFAULT_HARNESS_TIMEOUT_MS / 60_000})`)
+        .option("--max-turns <count>", `maximum build turns (default: ${MAX_BUILD_TURNS})`)
+        .option("--name <name>", "project directory name (default: a generated dc-xxxxxx name)")
+        .option("--skip-template", "during a full run, skip starter template search and build from scratch")
+        .passThroughOptions()
+        .version(options.version ?? "0.0.0")
+        .action(async (args, commandOptions) => {
+        const { promptParts, harnessArgs } = splitHarnessArgs(args);
+        const prompt = parsePromptParts(promptParts);
+        const result = await create(prompt, {
+            stage: parseStage(commandOptions.stage),
+            harness: parseHarnessName(commandOptions.harness),
+            harnessTimeoutMs: parseHarnessTimeoutMs(commandOptions.harnessTimeoutMinutes),
+            harnessArgs,
+            maxTurns: parsePositiveInteger(commandOptions.maxTurns, "--max-turns"),
+            projectName: commandOptions.name,
+            skipTemplate: commandOptions.skipTemplate === true
+        });
+        const ok = result.exitCode === 0;
+        const write = ok ? console.log : console.error;
+        write(ok ? formatSuccess(result) : formatFailure(result));
+        process.exitCode = result.exitCode;
+    });
+    return command;
+}
+export function splitHarnessArgs(args) {
+    const separatorIndex = args.indexOf("--");
+    if (separatorIndex === -1)
+        return { promptParts: args, harnessArgs: [] };
+    return {
+        promptParts: args.slice(0, separatorIndex),
+        harnessArgs: args.slice(separatorIndex + 1)
+    };
+}
+export function parsePromptParts(promptParts) {
+    // passThroughOptions() turns options placed after the prompt into prompt words; reject them
+    // instead of silently sending them to the harness.
+    const misplaced = promptParts.find((part) => CLI_OPTION_NAMES.includes(part));
+    if (misplaced) {
+        const valuePlaceholder = misplaced === "--skip-template" ? "" : " <value>";
+        throw new CliError(`${misplaced} must come before the prompt, e.g. drawcall-create ${misplaced}${valuePlaceholder} "<prompt>"`);
+    }
+    const prompt = promptParts.join(" ").trim();
+    if (!prompt)
+        throw new CliError("prompt is required");
+    return prompt;
+}
+export function parseHarnessName(value) {
+    if (!value)
+        return undefined;
+    if (HARNESS_NAMES.includes(value))
+        return value;
+    throw new CliError(`unsupported harness "${value}". Supported: ${HARNESS_NAMES.join(", ")}`);
+}
+export function parseStage(value) {
+    if (!value)
+        return undefined;
+    if (STAGES.includes(value))
+        return value;
+    throw new CliError(`unsupported stage "${value}". Supported: ${STAGES.join(", ")}`);
+}
+export function parsePositiveInteger(value, optionName) {
+    if (value === undefined)
+        return undefined;
+    if (!/^[1-9]\d*$/.test(value)) {
+        throw new CliError(`${optionName} must be a positive integer`);
+    }
+    return Number(value);
+}
+export function parseHarnessTimeoutMs(value) {
+    const minutes = parsePositiveInteger(value, "--harness-timeout-minutes");
+    return minutes === undefined ? undefined : minutes * 60_000;
+}
+function formatSuccess(result) {
+    const lines = [
+        "",
+        `Project ready in ${formatDuration(result.durationMs)}`,
+        `Path  ${result.projectDir}`,
+        `Log   drawcall-create.log`
+    ];
+    const turns = formatTurns(result);
+    if (turns)
+        lines.splice(3, 0, `Turns ${turns}`);
+    return lines.join("\n");
+}
+function formatFailure(result) {
+    const lines = [
+        "",
+        `Stopped after ${formatDuration(result.durationMs)}`,
+        `Exit code  ${result.exitCode}`,
+        `Path       ${result.projectDir}`,
+        `Log        drawcall-create.log`
+    ];
+    const turns = formatTurns(result);
+    if (turns)
+        lines.splice(3, 0, `Turns      ${turns}`);
+    return lines.join("\n");
+}
+function formatTurns(result) {
+    if (result.maxTurns === 0)
+        return undefined;
+    return `${result.turns}/${result.maxTurns}`;
+}

package/dist/constants.d.ts

@@ -0,0 +1,26 @@
+export declare const HARNESS_NAMES: readonly ["opencode", "codex", "claude", "pi", "gemini", "grok", "forge"];
+export type HarnessName = (typeof HARNESS_NAMES)[number];
+export declare const STAGES: readonly ["scaffold", "template", "survey-assets", "survey-technology", "goal", "plan", "build", "full"];
+export type Stage = (typeof STAGES)[number];
+export declare const PARALLEL_STAGES: readonly ["template", "survey-assets", "survey-technology"];
+export declare const SKILLS: readonly ["drawcall-ai/vitexec", "drawcall-ai/uikitml", "drawcall-ai/acta", "drawcall-ai/market", "drawcall-ai/speech", "drawcall-ai/flipbook", "drawcall-ai/skills"];
+export declare const PACKAGES: readonly ["vitexec@latest", "@drawcall/uikitml@latest", "@drawcall/acta@latest", "@drawcall/market@latest", "@drawcall/flipbook@latest", "@pmndrs/uikit@latest", "@pmndrs/pointer-events@latest", "@pmndrs/viverse@latest", "navcat@^0.4.1", "three@^0.184.0", "vite@^8.0.16", "typescript@^6.0.3", "elics@^3.4.2", "postprocessing@^6.39.1"];
+export declare const PACKAGE_NAMES: readonly ["vitexec", "@drawcall/uikitml", "@drawcall/acta", "@drawcall/market", "@drawcall/flipbook", "@pmndrs/uikit", "@pmndrs/pointer-events", "@pmndrs/viverse", "navcat", "three", "vite", "typescript", "elics"];
+export declare const MAX_BUILD_TURNS = 10;
+export declare const DEFAULT_HARNESS_TIMEOUT_MS: number;
+export declare const TIMEOUT_EXIT_CODE = 124;
+export declare const TIMEOUT_KILL_GRACE_MS = 5000;
+export declare const GOAL_FILE = "GOAL.md";
+export declare const README_FILE = "README.md";
+export declare const PLAN_FILE = "PLAN.md";
+export declare const SURVEY_DIR = "surveys";
+export declare const ASSET_SURVEY_FILE = "surveys/ASSETS.md";
+export declare const TECH_SURVEY_FILE = "surveys/TECHNOLOGY.md";
+export declare const PROOF_DIR = "proof";
+export declare const SESSION_LOG_FILE = "drawcall-create.log";
+export declare const GITIGNORE_ENTRIES: readonly ["node_modules/", "dist/", "build/", "coverage/", ".env", ".env.*", ".DS_Store", "surveys/", "proof/", "drawcall-create.log"];
+/** Error whose message is shown to the user and whose code becomes the process exit code. */
+export declare class CliError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode?: number);
+}

package/dist/constants.js

@@ -0,0 +1,94 @@
+export const HARNESS_NAMES = ["opencode", "codex", "claude", "pi", "gemini", "grok", "forge"];
+export const STAGES = [
+    "scaffold",
+    "template",
+    "survey-assets",
+    "survey-technology",
+    "goal",
+    "plan",
+    "build",
+    "full"
+];
+// In a "full" run these three stages run concurrently after scaffolding: they write disjoint
+// outputs (template touches the product; the surveys write gitignored scratch files) and none
+// of them depends on the others, so they share a barrier before the goal stage.
+export const PARALLEL_STAGES = ["template", "survey-assets", "survey-technology"];
+export const SKILLS = [
+    "drawcall-ai/vitexec",
+    "drawcall-ai/uikitml",
+    "drawcall-ai/acta",
+    "drawcall-ai/market",
+    "drawcall-ai/speech",
+    "drawcall-ai/flipbook",
+    "drawcall-ai/skills"
+];
+export const PACKAGES = [
+    "vitexec@latest",
+    "@drawcall/uikitml@latest",
+    "@drawcall/acta@latest",
+    "@drawcall/market@latest",
+    "@drawcall/flipbook@latest",
+    "@pmndrs/uikit@latest",
+    "@pmndrs/pointer-events@latest",
+    "@pmndrs/viverse@latest",
+    "navcat@^0.4.1",
+    "three@^0.184.0",
+    "vite@^8.0.16",
+    "typescript@^6.0.3",
+    "elics@^3.4.2",
+    "postprocessing@^6.39.1"
+];
+export const PACKAGE_NAMES = [
+    "vitexec",
+    "@drawcall/uikitml",
+    "@drawcall/acta",
+    "@drawcall/market",
+    "@drawcall/flipbook",
+    "@pmndrs/uikit",
+    "@pmndrs/pointer-events",
+    "@pmndrs/viverse",
+    "navcat",
+    "three",
+    "vite",
+    "typescript",
+    "elics"
+];
+export const MAX_BUILD_TURNS = 10;
+export const DEFAULT_HARNESS_TIMEOUT_MS = 20 * 60 * 1000;
+export const TIMEOUT_EXIT_CODE = 124;
+export const TIMEOUT_KILL_GRACE_MS = 5000;
+// The three committed records (see LANGUAGE.md): the fixed goal, the current state,
+// and the plan between them.
+export const GOAL_FILE = "GOAL.md";
+export const README_FILE = "README.md";
+export const PLAN_FILE = "PLAN.md";
+// The two scratch surveys: a harness walks every fitting Market asset / installed skill
+// and writes what fits here. They feed the goal and plan stages and are never committed.
+export const SURVEY_DIR = "surveys";
+export const ASSET_SURVEY_FILE = `${SURVEY_DIR}/ASSETS.md`;
+export const TECH_SURVEY_FILE = `${SURVEY_DIR}/TECHNOLOGY.md`;
+// Build turns drop proof files here; gitignored scratch (the durable record of what was proven
+// lives in README.md), so generated repos don't fill with committed binaries.
+export const PROOF_DIR = "proof";
+export const SESSION_LOG_FILE = "drawcall-create.log";
+export const GITIGNORE_ENTRIES = [
+    "node_modules/",
+    "dist/",
+    "build/",
+    "coverage/",
+    ".env",
+    ".env.*",
+    ".DS_Store",
+    `${SURVEY_DIR}/`,
+    `${PROOF_DIR}/`,
+    SESSION_LOG_FILE
+];
+/** Error whose message is shown to the user and whose code becomes the process exit code. */
+export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.name = "CliError";
+        this.exitCode = exitCode;
+    }
+}

package/dist/create.d.ts

@@ -0,0 +1,35 @@
+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;
+}>;