phoebe-agent 0.0.0 → 0.1.0

package/dist/src/config-schema.js

@@ -1,140 +0,0 @@
-// Shape of the repo-specific configuration the Phoebe engine runs against.
-// The values live in ../phoebe.config.ts — the single file allowed to mention
-// this repository. Engine modules (everything under src/) import the resolved
-// config from ./resolved-config.ts and stay repo-agnostic;
-// src/config-seam.test.ts enforces it.
-//
-// Two shapes live here. `PhoebeUserConfig` is what a consumer writes: only the
-// unavoidable repo/toolchain fields are required; everything else is optional
-// and filled from `CONFIG_DEFAULTS` by `resolveConfig()`. `PhoebeConfig` is the
-// fully-resolved shape the engine sees at runtime — every field populated.
-export const PROVIDER_NAMES = ["cursor", "claude", "codex"];
-/**
- * Engine defaults for every optional user field. These land in the resolved
- * config whenever the consumer's `phoebe.config.ts` omits them, so a minimal
- * consumer config only has to name the repo and its three toolchain commands.
- */
-export const CONFIG_DEFAULTS = {
-    defaultBranch: "main",
-    branchPrefix: "phoebe/",
-    readyLabel: "ready-for-agent",
-    processingLabel: "processing",
-    prScope: "phoebe",
-    draftPrs: "skip-non-phoebe",
-    prOptOutLabel: "ready-for-human",
-    readyCommand: "npm run ready",
-    blockedByPattern: String.raw `Blocked by\s+#(\d+)`,
-    reviewsSuccessHeading: "## Review feedback addressed",
-    promptFiles: {
-        issue: "prompts/prompt.md",
-        conflict: "prompts/conflict-prompt.md",
-        checks: "prompts/checks-prompt.md",
-        reviews: "prompts/reviews-prompt.md",
-    },
-    workOrder: ["conflicts", "checks", "reviews", "issues"],
-    defaultProvider: "cursor",
-    defaultModels: {
-        cursor: "composer-2.5",
-        claude: "claude-sonnet-4-6",
-        codex: "gpt-5.4-mini",
-    },
-    providerEnv: {
-        cursor: "CURSOR_API_KEY",
-        claude: "ANTHROPIC_API_KEY",
-        codex: "OPENAI_KEY",
-    },
-    selfUpdatePaths: ["package.json", "package-lock.json"],
-    paths: {
-        repoDir: "/data/repo",
-        worktreesDir: "/data/worktrees",
-        stateDir: "/data/state",
-    },
-};
-const REQUIRED_USER_FIELDS = [
-    "repoSlug",
-    "repoUrl",
-    "installCommand",
-    "checkCommand",
-    "testCommand",
-];
-/**
- * Count the numbered capture groups defined by a regex source. We compile it
- * with an added empty alternative (`|`) so the resulting regex always matches
- * the empty string; the match array's length minus one then equals the number
- * of capture groups, regardless of whether the original pattern would have
- * matched anything on its own. Escaped parens, non-capturing groups (`(?:…)`),
- * lookarounds, and named groups are handled correctly because we're asking
- * the engine's own group count, not parsing the source ourselves.
- */
-function countCaptureGroups(source) {
-    const compiled = new RegExp(`${source}|`);
-    const match = compiled.exec("");
-    // The extra `|` guarantees a match against ""; TS still narrows to nullable.
-    if (!match) {
-        return 0;
-    }
-    return match.length - 1;
-}
-/**
- * Throw when a required field is missing or blank, or when `blockedByPattern`
- * is not a valid regex or fails to expose the blocker issue number as capture
- * group 1. `parseBlockedBy` reads `match[1]`, so a pattern without a capture
- * group would silently break the entire blocker-detection path — reject it up
- * front. Kept separate from `resolveConfig` so consumers or tests can validate
- * a config independent of the defaults merge.
- */
-export function validateUserConfig(user) {
-    const missing = REQUIRED_USER_FIELDS.filter((key) => {
-        const value = user[key];
-        return typeof value !== "string" || value.trim().length === 0;
-    });
-    if (missing.length > 0) {
-        throw new Error(`phoebe.config.ts is missing required field(s): ${missing.join(", ")}. ` +
-            `Only these five fields are required — the engine fills the rest from its defaults.`);
-    }
-    if (user.blockedByPattern !== undefined) {
-        try {
-            new RegExp(user.blockedByPattern, "gi");
-        }
-        catch (err) {
-            throw new Error(`phoebe.config.ts blockedByPattern is not a valid regex: ${err.message}`);
-        }
-        if (countCaptureGroups(user.blockedByPattern) < 1) {
-            throw new Error(`phoebe.config.ts blockedByPattern must define capture group 1 for the ` +
-                `blocker issue number (parseBlockedBy reads match[1]). Wrap the number ` +
-                `portion in parentheses, e.g. String.raw\`Blocked by\\s+#(\\d+)\`.`);
-        }
-    }
-}
-/**
- * Merge a user config with `CONFIG_DEFAULTS` and return the fully-populated
- * shape the engine runs against. Nested records are shallow-merged so partial
- * overrides (one prompt file, one provider's env var, etc.) work as expected.
- */
-export function resolveConfig(user) {
-    validateUserConfig(user);
-    return {
-        repoSlug: user.repoSlug,
-        repoUrl: user.repoUrl,
-        installCommand: user.installCommand,
-        checkCommand: user.checkCommand,
-        testCommand: user.testCommand,
-        defaultBranch: user.defaultBranch ?? CONFIG_DEFAULTS.defaultBranch,
-        branchPrefix: user.branchPrefix ?? CONFIG_DEFAULTS.branchPrefix,
-        readyLabel: user.readyLabel ?? CONFIG_DEFAULTS.readyLabel,
-        processingLabel: user.processingLabel ?? CONFIG_DEFAULTS.processingLabel,
-        prScope: user.prScope ?? CONFIG_DEFAULTS.prScope,
-        draftPrs: user.draftPrs ?? CONFIG_DEFAULTS.draftPrs,
-        prOptOutLabel: user.prOptOutLabel ?? CONFIG_DEFAULTS.prOptOutLabel,
-        readyCommand: user.readyCommand ?? CONFIG_DEFAULTS.readyCommand,
-        blockedByPattern: user.blockedByPattern ?? CONFIG_DEFAULTS.blockedByPattern,
-        reviewsSuccessHeading: user.reviewsSuccessHeading ?? CONFIG_DEFAULTS.reviewsSuccessHeading,
-        promptFiles: { ...CONFIG_DEFAULTS.promptFiles, ...user.promptFiles },
-        workOrder: user.workOrder ?? CONFIG_DEFAULTS.workOrder,
-        defaultProvider: user.defaultProvider ?? CONFIG_DEFAULTS.defaultProvider,
-        defaultModels: { ...CONFIG_DEFAULTS.defaultModels, ...user.defaultModels },
-        providerEnv: { ...CONFIG_DEFAULTS.providerEnv, ...user.providerEnv },
-        selfUpdatePaths: user.selfUpdatePaths ?? CONFIG_DEFAULTS.selfUpdatePaths,
-        paths: { ...CONFIG_DEFAULTS.paths, ...user.paths },
-    };
-}

package/dist/src/execution-gate.d.ts

@@ -1,9 +0,0 @@
-export declare const CONTAINER_MARKER_PATH = "/.phoebe-container";
-export declare function isInsideContainer(exists?: (path: string) => boolean): boolean;
-export type ExecutionDecision = "execute" | "dry-run" | "refuse";
-/** Pure decision: may this process execute the selected work unit? */
-export declare function executionDecision(opts: {
-    dryRun: boolean;
-    inContainer: boolean;
-}): ExecutionDecision;
-export declare const EXECUTION_REFUSED_MESSAGE: string;

package/dist/src/execution-gate.js

@@ -1,17 +0,0 @@
-// Work-unit execution is gated to the Phoebe container. Selection logic and
-// --dry-run stay host-runnable for fast iteration; anything that mutates a
-// clone, launches an agent CLI, or pushes runs only where the container
-// marker exists (created by the Dockerfile).
-import { existsSync } from "node:fs";
-export const CONTAINER_MARKER_PATH = "/.phoebe-container";
-export function isInsideContainer(exists = existsSync) {
-    return exists(CONTAINER_MARKER_PATH);
-}
-/** Pure decision: may this process execute the selected work unit? */
-export function executionDecision(opts) {
-    if (opts.dryRun)
-        return "dry-run";
-    return opts.inContainer ? "execute" : "refuse";
-}
-export const EXECUTION_REFUSED_MESSAGE = "[phoebe] Refusing to execute a work unit outside the Phoebe container. " +
-    "Use --dry-run to preview selection on the host, or start the container loop.";

package/dist/src/git-model.d.ts

@@ -1,30 +0,0 @@
-export type GitRunner = (args: string[], opts?: {
-    cwd?: string;
-    stdio?: "inherit" | "ignore" | "pipe";
-}) => string;
-export declare const defaultGit: GitRunner;
-/** Clone the repo into `repoDir` unless a clone already exists there. */
-export declare function ensureClone(opts: {
-    repoUrl: string;
-    repoDir: string;
-}, git?: GitRunner): void;
-export declare function fetchOrigin(repoDir: string, git?: GitRunner): void;
-export declare function originBranchSha(repoDir: string, branch: string, git?: GitRunner): string;
-/** Filesystem-safe worktree directory name for a branch. */
-export declare function worktreeDirForBranch(worktreesDir: string, branch: string): string;
-/** Create a worktree on a (possibly new) branch reset to `baseRef`. */
-export declare function addWorktreeForNewBranch(opts: {
-    repoDir: string;
-    worktreeDir: string;
-    branch: string;
-    baseRef: string;
-}, git?: GitRunner): void;
-/** Create a worktree on an existing branch (local first, then origin/<branch>). */
-export declare function addWorktreeForExistingBranch(opts: {
-    repoDir: string;
-    worktreeDir: string;
-    branch: string;
-}, git?: GitRunner): void;
-export declare function removeWorktree(repoDir: string, worktreeDir: string, git?: GitRunner): void;
-export declare function commitCount(worktreeDir: string, range: string, git?: GitRunner): number;
-export declare function pushBranch(worktreeDir: string, branch: string, git?: GitRunner): void;

package/dist/src/git-model.js

@@ -1,71 +0,0 @@
-// Origin-hub git model: a private clone owns all local git state, work units
-// run in worktrees off it, finished branches push straight to origin. Every
-// function takes the clone directory explicitly so tests can run against a
-// temp clone.
-import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, rmSync } from "node:fs";
-import { join } from "node:path";
-export const defaultGit = (args, opts) => execFileSync("git", args, {
-    encoding: "utf8",
-    ...(opts?.cwd ? { cwd: opts.cwd } : {}),
-    ...(opts?.stdio ? { stdio: opts.stdio } : {}),
-});
-/** Clone the repo into `repoDir` unless a clone already exists there. */
-export function ensureClone(opts, git = defaultGit) {
-    if (existsSync(join(opts.repoDir, ".git")))
-        return;
-    mkdirSync(opts.repoDir, { recursive: true });
-    git(["clone", opts.repoUrl, opts.repoDir], { stdio: "inherit" });
-}
-export function fetchOrigin(repoDir, git = defaultGit) {
-    git(["fetch", "origin"], { cwd: repoDir, stdio: "inherit" });
-}
-export function originBranchSha(repoDir, branch, git = defaultGit) {
-    return git(["rev-parse", `origin/${branch}`], { cwd: repoDir }).trim();
-}
-/** Filesystem-safe worktree directory name for a branch. */
-export function worktreeDirForBranch(worktreesDir, branch) {
-    return join(worktreesDir, branch.toLowerCase().replace(/[^a-z0-9]/g, "-"));
-}
-/** Create a worktree on a (possibly new) branch reset to `baseRef`. */
-export function addWorktreeForNewBranch(opts, git = defaultGit) {
-    git(["worktree", "add", "-B", opts.branch, opts.worktreeDir, opts.baseRef], {
-        cwd: opts.repoDir,
-        stdio: "inherit",
-    });
-}
-/** Create a worktree on an existing branch (local first, then origin/<branch>). */
-export function addWorktreeForExistingBranch(opts, git = defaultGit) {
-    try {
-        git(["worktree", "add", opts.worktreeDir, opts.branch], {
-            cwd: opts.repoDir,
-            stdio: "inherit",
-        });
-    }
-    catch {
-        git(["worktree", "add", "-B", opts.branch, opts.worktreeDir, `origin/${opts.branch}`], {
-            cwd: opts.repoDir,
-            stdio: "inherit",
-        });
-    }
-}
-export function removeWorktree(repoDir, worktreeDir, git = defaultGit) {
-    try {
-        git(["worktree", "remove", "--force", worktreeDir], { cwd: repoDir, stdio: "ignore" });
-    }
-    catch {
-        rmSync(worktreeDir, { recursive: true, force: true });
-    }
-    try {
-        git(["worktree", "prune"], { cwd: repoDir, stdio: "ignore" });
-    }
-    catch {
-        // Best-effort.
-    }
-}
-export function commitCount(worktreeDir, range, git = defaultGit) {
-    return Number(git(["rev-list", "--count", range], { cwd: worktreeDir }).trim());
-}
-export function pushBranch(worktreeDir, branch, git = defaultGit) {
-    git(["push", "origin", branch], { cwd: worktreeDir, stdio: "inherit" });
-}

package/dist/src/index.d.ts

@@ -1,2 +0,0 @@
-export { defineConfig } from "./load-config.ts";
-export type { PhoebeConfig, PhoebeUserConfig, PathsConfig, PromptFilesConfig, ProviderName, } from "./config-schema.ts";

package/dist/src/index.js

@@ -1,12 +0,0 @@
-// Public consumer surface for `phoebe-agent`. Deliberately minimal — the
-// packaged v1 has no programmatic runtime API, only the `phoebe` bin. Import
-// this module for type-checked config authoring:
-//
-// ```ts
-// import { defineConfig, type PhoebeUserConfig } from "phoebe-agent";
-// export default defineConfig({ repoSlug: "...", ... });
-// ```
-//
-// Types are structurally identical to their source in ./config-schema.ts;
-// `defineConfig` is the identity typing helper from ./load-config.ts.
-export { defineConfig } from "./load-config.js";

package/dist/src/init.d.ts

@@ -1,82 +0,0 @@
-/** Placeholder tokens rendered into every scaffolded file. */
-export type TemplateParams = {
-    /** The consumer's install command (also written into the config). */
-    installCommand: string;
-    /** The npm package name of the CLI — normally `phoebe-agent`. */
-    cliBin: string;
-};
-export declare const DEFAULT_TEMPLATE_PARAMS: TemplateParams;
-/**
- * One consumer-owned output produced by init. Sources are one of:
- *  - `template`: a file under the shipped `templates/` tree, rendered with
- *    placeholder substitution.
- *  - `shipped-prompt`: a file under the shipped `prompts/` tree, copied
- *    verbatim (prompts already carry their own `{{…}}` markers that the
- *    engine expands at run time — do NOT substitute those here).
- *  - `gitignore`: an additive-merge marker; `entries` are appended to any
- *    existing `.gitignore`, deduped line-wise.
- */
-export type PlannedOutput = {
-    destRelPath: string;
-    source: {
-        kind: "template";
-        templateRelPath: string;
-        executable?: boolean;
-    } | {
-        kind: "shipped-prompt";
-        promptRelPath: string;
-    } | {
-        kind: "gitignore";
-        entries: readonly string[];
-    };
-};
-/**
- * Enumerate every file init will produce. The prompt list is derived from
- * `CONFIG_DEFAULTS.promptFiles` so adding a new prompt kind to the engine
- * automatically gets scaffolded — no drift between the two lists.
- */
-export declare function planInitOutputs(): PlannedOutput[];
-/**
- * Substitute `{{KEY}}` tokens with the matching value. Unknown tokens throw
- * so a typo in a template surfaces during tests rather than silently landing
- * in a consumer's repo. Iteration is over the params (not a regex over the
- * source) so a value that happens to contain a `{{…}}`-shaped substring is
- * never re-scanned.
- */
-export declare function renderTemplate(source: string, params: TemplateParams): string;
-/**
- * Additive `.gitignore` merge — append any missing entries under a `# Phoebe`
- * header, leaving existing lines untouched. An empty file becomes a bare list
- * (no header) because there's nothing else to distinguish it from.
- */
-export declare function mergeGitignore(existing: string, entries: readonly string[]): string;
-export type InitReport = {
-    /** New files written (destination paths, relative to the target dir). */
-    created: string[];
-    /** `.gitignore` entries appended in-place (destination paths). */
-    updated: string[];
-    /** Existing files left alone (destination paths). */
-    skipped: string[];
-};
-export type RunInitOptions = {
-    /** Directory the scaffolded files land under. Created if missing. */
-    targetDir: string;
-    /** Override template params (`installCommand`, `cliBin`). */
-    params?: Partial<TemplateParams>;
-    /** Root for shipped `templates/` and `prompts/` (test seam). Defaults to
-     *  the walk-up from this module. */
-    packageRoot?: string;
-};
-/**
- * Execute the plan: create missing files, additively update `.gitignore`, and
- * leave every existing file alone. Returns a report so the CLI (and tests)
- * can render a summary without re-walking the filesystem.
- *
- * Not idempotent in the "produces the same output twice" sense — running init
- * twice on a directory the consumer has edited must not change their files.
- * That's the entire guarded-re-run contract. A second run into an empty
- * directory *does* reproduce the first-run output.
- */
-export declare function runInit(opts: RunInitOptions): InitReport;
-/** Human-readable summary suitable for the CLI to stdout after init runs. */
-export declare function formatInitReport(report: InitReport, targetDir: string): string;

package/dist/src/init.js

@@ -1,207 +0,0 @@
-// `phoebe init` scaffolder. Given a target directory, drops the consumer-owned
-// runtime into place: `phoebe.config.ts`, a `prompts/` dir with copies of the
-// shipped defaults (edit-and-commit), `.env.example`, `.gitignore` entries,
-// and the `container/` templates (Dockerfile, base compose, daemon overlay,
-// supervisor script). Re-runs are guarded — an existing file is skipped, not
-// silently overwritten, so consumer edits are safe.
-//
-// The plan/render split keeps the pure logic (what files, what placeholders)
-// separately testable from the fs I/O in `runInit`.
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { basename, dirname, join, resolve as resolvePath } from "node:path";
-import { fileURLToPath } from "node:url";
-import { CONFIG_DEFAULTS } from "./config-schema.js";
-export const DEFAULT_TEMPLATE_PARAMS = {
-    installCommand: "npm ci",
-    cliBin: "phoebe-agent",
-};
-const GITIGNORE_ENTRIES = [".env", "node_modules/"];
-/**
- * Enumerate every file init will produce. The prompt list is derived from
- * `CONFIG_DEFAULTS.promptFiles` so adding a new prompt kind to the engine
- * automatically gets scaffolded — no drift between the two lists.
- */
-export function planInitOutputs() {
-    const promptOutputs = Object.values(CONFIG_DEFAULTS.promptFiles).map((relPath) => ({
-        destRelPath: relPath,
-        source: { kind: "shipped-prompt", promptRelPath: relPath },
-    }));
-    return [
-        {
-            destRelPath: "phoebe.config.ts",
-            source: { kind: "template", templateRelPath: "phoebe.config.ts" },
-        },
-        {
-            destRelPath: ".env.example",
-            source: { kind: "template", templateRelPath: ".env.example" },
-        },
-        {
-            destRelPath: "container/Dockerfile",
-            source: { kind: "template", templateRelPath: "container/Dockerfile" },
-        },
-        {
-            destRelPath: "container/compose.yml",
-            source: { kind: "template", templateRelPath: "container/compose.yml" },
-        },
-        {
-            destRelPath: "container/compose.daemon.yml",
-            source: { kind: "template", templateRelPath: "container/compose.daemon.yml" },
-        },
-        {
-            destRelPath: "container/supervisor.sh",
-            source: { kind: "template", templateRelPath: "container/supervisor.sh", executable: true },
-        },
-        ...promptOutputs,
-        {
-            destRelPath: ".gitignore",
-            source: { kind: "gitignore", entries: GITIGNORE_ENTRIES },
-        },
-    ];
-}
-/**
- * Substitute `{{KEY}}` tokens with the matching value. Unknown tokens throw
- * so a typo in a template surfaces during tests rather than silently landing
- * in a consumer's repo. Iteration is over the params (not a regex over the
- * source) so a value that happens to contain a `{{…}}`-shaped substring is
- * never re-scanned.
- */
-export function renderTemplate(source, params) {
-    let rendered = source;
-    for (const [key, value] of Object.entries(params)) {
-        const token = `{{${keyToToken(key)}}}`;
-        rendered = rendered.split(token).join(value);
-    }
-    const leftover = /\{\{([A-Z_]+)\}\}/.exec(rendered);
-    if (leftover) {
-        throw new Error(`Template contained an unrenderable placeholder \`{{${leftover[1]}}}\` — ` +
-            `every {{TOKEN}} in a scaffolded file must map to a TemplateParams field.`);
-    }
-    return rendered;
-}
-function keyToToken(key) {
-    // installCommand -> INSTALL_COMMAND, cliBin -> CLI_BIN
-    return key.replace(/([A-Z])/g, "_$1").toUpperCase();
-}
-/**
- * Additive `.gitignore` merge — append any missing entries under a `# Phoebe`
- * header, leaving existing lines untouched. An empty file becomes a bare list
- * (no header) because there's nothing else to distinguish it from.
- */
-export function mergeGitignore(existing, entries) {
-    const existingLines = new Set(existing
-        .split("\n")
-        .map((line) => line.trim())
-        .filter((line) => line.length > 0 && !line.startsWith("#")));
-    const missing = entries.filter((entry) => !existingLines.has(entry));
-    if (missing.length === 0) {
-        return existing;
-    }
-    if (existing.trim().length === 0) {
-        return `${missing.join("\n")}\n`;
-    }
-    const separator = existing.endsWith("\n") ? "" : "\n";
-    return `${existing}${separator}\n# Phoebe\n${missing.join("\n")}\n`;
-}
-/**
- * Walk up from this module's directory to find the shipped resource root. We
- * emit to `dist/src/init.js` and read `templates/…` + `prompts/…` from the
- * package root, so the walk-up mirrors `resolvePackageFile` in main.ts. Stops
- * at a `node_modules` boundary so an installed dep never resolves resources
- * from the consuming repo.
- */
-function resolvePackageResource(relativePath, moduleDir) {
-    let dir = moduleDir;
-    while (true) {
-        const candidate = join(dir, relativePath);
-        if (existsSync(candidate)) {
-            return candidate;
-        }
-        const parent = dirname(dir);
-        if (parent === dir || basename(parent) === "node_modules") {
-            throw new Error(`Could not find ${relativePath} within the Phoebe package (searched from ${moduleDir})`);
-        }
-        dir = parent;
-    }
-}
-function readShippedFile(relPath, packageRoot, moduleDir) {
-    const absolute = packageRoot
-        ? resolvePath(packageRoot, relPath)
-        : resolvePackageResource(relPath, moduleDir);
-    return readFileSync(absolute, "utf8");
-}
-/**
- * Execute the plan: create missing files, additively update `.gitignore`, and
- * leave every existing file alone. Returns a report so the CLI (and tests)
- * can render a summary without re-walking the filesystem.
- *
- * Not idempotent in the "produces the same output twice" sense — running init
- * twice on a directory the consumer has edited must not change their files.
- * That's the entire guarded-re-run contract. A second run into an empty
- * directory *does* reproduce the first-run output.
- */
-export function runInit(opts) {
-    const targetDir = resolvePath(opts.targetDir);
-    const params = { ...DEFAULT_TEMPLATE_PARAMS, ...opts.params };
-    const moduleDir = dirname(fileURLToPath(import.meta.url));
-    mkdirSync(targetDir, { recursive: true });
-    const report = { created: [], updated: [], skipped: [] };
-    for (const output of planInitOutputs()) {
-        const destAbs = join(targetDir, output.destRelPath);
-        mkdirSync(dirname(destAbs), { recursive: true });
-        if (output.source.kind === "gitignore") {
-            const existing = existsSync(destAbs) ? readFileSync(destAbs, "utf8") : "";
-            const merged = mergeGitignore(existing, output.source.entries);
-            if (merged === existing) {
-                report.skipped.push(output.destRelPath);
-            }
-            else if (existing.length === 0) {
-                writeFileSync(destAbs, merged);
-                report.created.push(output.destRelPath);
-            }
-            else {
-                writeFileSync(destAbs, merged);
-                report.updated.push(output.destRelPath);
-            }
-            continue;
-        }
-        if (existsSync(destAbs)) {
-            report.skipped.push(output.destRelPath);
-            continue;
-        }
-        if (output.source.kind === "template") {
-            const rawTemplate = readShippedFile(join("templates", output.source.templateRelPath), opts.packageRoot, moduleDir);
-            const rendered = renderTemplate(rawTemplate, params);
-            writeFileSync(destAbs, rendered, {
-                mode: output.source.executable ? 0o755 : 0o644,
-            });
-        }
-        else {
-            // Shipped prompts ship verbatim — the engine's own render step handles
-            // their `{{PLACEHOLDER}}` tokens at run time.
-            const prompt = readShippedFile(output.source.promptRelPath, opts.packageRoot, moduleDir);
-            writeFileSync(destAbs, prompt);
-        }
-        report.created.push(output.destRelPath);
-    }
-    return report;
-}
-/** Human-readable summary suitable for the CLI to stdout after init runs. */
-export function formatInitReport(report, targetDir) {
-    const lines = [`[phoebe] init → ${targetDir}`];
-    const emit = (label, paths) => {
-        if (paths.length === 0)
-            return;
-        lines.push(`  ${label}:`);
-        for (const path of paths) {
-            lines.push(`    ${path}`);
-        }
-    };
-    emit("created", report.created);
-    emit("updated", report.updated);
-    emit("skipped (already present)", report.skipped);
-    if (report.skipped.length > 0) {
-        lines.push("");
-        lines.push("Existing files were left untouched. Delete them and re-run init to regenerate.");
-    }
-    return `${lines.join("\n")}\n`;
-}

package/dist/src/load-config.d.ts

@@ -1,88 +0,0 @@
-import type { PhoebeUserConfig } from "./config-schema.ts";
-/**
- * Identity function that types a consumer's `phoebe.config.ts` export as
- * `PhoebeUserConfig`. Consumers write:
- *
- * ```ts
- * import { defineConfig } from "phoebe-agent";
- * export default defineConfig({ repoSlug: "...", ... });
- * ```
- *
- * The engine never reads this at runtime beyond forwarding the value; the
- * whole benefit is editor autocomplete and a compile-time check that only
- * known fields appear.
- */
-export declare function defineConfig(config: PhoebeUserConfig): PhoebeUserConfig;
-/**
- * Scalar-only overlay: each `PHOEBE_*` env var, when set to a non-empty
- * string, replaces the corresponding user-config field. Nested records
- * (`promptFiles`, `paths`, `defaultModels`, `providerEnv`, `workOrder`) stay
- * config-file territory — env vars are for one-off run overrides where the
- * consumer doesn't want to edit `phoebe.config.ts`, and expanding structured
- * shapes into env keys defeats the point.
- *
- * A field-scoped list (rather than magic name-mangling) keeps the surface
- * documented and predictable: users can grep for `PHOEBE_` here and see the
- * complete overlay contract.
- */
-export declare const ENV_OVERLAY_KEYS: readonly [{
-    readonly env: "PHOEBE_REPO_SLUG";
-    readonly key: "repoSlug";
-}, {
-    readonly env: "PHOEBE_REPO_URL";
-    readonly key: "repoUrl";
-}, {
-    readonly env: "PHOEBE_DEFAULT_BRANCH";
-    readonly key: "defaultBranch";
-}, {
-    readonly env: "PHOEBE_BRANCH_PREFIX";
-    readonly key: "branchPrefix";
-}, {
-    readonly env: "PHOEBE_READY_LABEL";
-    readonly key: "readyLabel";
-}, {
-    readonly env: "PHOEBE_PROCESSING_LABEL";
-    readonly key: "processingLabel";
-}, {
-    readonly env: "PHOEBE_PR_OPT_OUT_LABEL";
-    readonly key: "prOptOutLabel";
-}, {
-    readonly env: "PHOEBE_INSTALL_COMMAND";
-    readonly key: "installCommand";
-}, {
-    readonly env: "PHOEBE_CHECK_COMMAND";
-    readonly key: "checkCommand";
-}, {
-    readonly env: "PHOEBE_TEST_COMMAND";
-    readonly key: "testCommand";
-}, {
-    readonly env: "PHOEBE_READY_COMMAND";
-    readonly key: "readyCommand";
-}, {
-    readonly env: "PHOEBE_BLOCKED_BY_PATTERN";
-    readonly key: "blockedByPattern";
-}, {
-    readonly env: "PHOEBE_REVIEWS_SUCCESS_HEADING";
-    readonly key: "reviewsSuccessHeading";
-}];
-/**
- * Apply the `PHOEBE_*` overlay onto a user config and return a new object.
- * The overlay is additive over what the config file declared — an unset env
- * var leaves the field untouched (so `resolveConfig` can still fall back to
- * `CONFIG_DEFAULTS` if the field was also absent from the config file).
- */
-export declare function applyEnvOverlay(user: PhoebeUserConfig, env: NodeJS.ProcessEnv): PhoebeUserConfig;
-/**
- * Resolve a `--config` argument (or the default) to an absolute path and
- * assert the file exists. Split from `loadUserConfig` so the CLI can print
- * a precise "file not found" message before attempting the dynamic import.
- */
-export declare function resolveConfigPath(argPath: string | undefined, cwd: string): string;
-/**
- * Dynamically import a `phoebe.config.ts` and return the user shape. Native
- * Node type-stripping (Node ≥ 22.7 with `--experimental-strip-types`, or
- * ≥ 23 by default) handles the TS syntax — no bundler needed on the consumer
- * side. Accepts either a default export or a named `config` export so the
- * pre-`defineConfig` scaffold still loads.
- */
-export declare function loadUserConfig(configPath: string): Promise<PhoebeUserConfig>;