phoebe-agent 0.0.0

package/dist/src/execution-gate.js

@@ -0,0 +1,17 @@
+// 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

@@ -0,0 +1,30 @@
+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

@@ -0,0 +1,71 @@
+// 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

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

package/dist/src/index.js

@@ -0,0 +1,12 @@
+// 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

@@ -0,0 +1,82 @@
+/** 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

@@ -0,0 +1,207 @@
+// `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

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

package/dist/src/load-config.js

@@ -0,0 +1,153 @@
+// Consumer-facing config plumbing: `defineConfig` (identity typing helper),
+// `loadUserConfig` (dynamic TS import via native Node type-stripping), and
+// `applyEnvOverlay` (`PHOEBE_*` overrides for scalar fields).
+//
+// The Phoebe CLI (src/cli.ts) chains these three: load the user's config,
+// overlay env vars, then `resolveConfig` fills the shipped defaults. Kept
+// separate from `config-schema.ts` so the schema stays a pure data contract
+// and only the CLI path pulls in Node's fs/url runtime.
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { pathToFileURL } from "node:url";
+import { existsSync } from "node:fs";
+import { isAbsolute, resolve as resolvePath } from "node:path";
+import { PROVIDER_NAMES } from "./config-schema.js";
+/**
+ * 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 function defineConfig(config) {
+    return config;
+}
+/**
+ * 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 const ENV_OVERLAY_KEYS = [
+    { env: "PHOEBE_REPO_SLUG", key: "repoSlug" },
+    { env: "PHOEBE_REPO_URL", key: "repoUrl" },
+    { env: "PHOEBE_DEFAULT_BRANCH", key: "defaultBranch" },
+    { env: "PHOEBE_BRANCH_PREFIX", key: "branchPrefix" },
+    { env: "PHOEBE_READY_LABEL", key: "readyLabel" },
+    { env: "PHOEBE_PROCESSING_LABEL", key: "processingLabel" },
+    { env: "PHOEBE_PR_OPT_OUT_LABEL", key: "prOptOutLabel" },
+    { env: "PHOEBE_INSTALL_COMMAND", key: "installCommand" },
+    { env: "PHOEBE_CHECK_COMMAND", key: "checkCommand" },
+    { env: "PHOEBE_TEST_COMMAND", key: "testCommand" },
+    { env: "PHOEBE_READY_COMMAND", key: "readyCommand" },
+    { env: "PHOEBE_BLOCKED_BY_PATTERN", key: "blockedByPattern" },
+    { env: "PHOEBE_REVIEWS_SUCCESS_HEADING", key: "reviewsSuccessHeading" },
+];
+const PR_SCOPE_VALUES = ["phoebe", "all"];
+const DRAFT_PRS_VALUES = ["skip-non-phoebe", "skip-all", "include"];
+function readNonEmpty(env, key) {
+    const raw = env[key];
+    if (typeof raw !== "string" || raw.length === 0)
+        return undefined;
+    return raw;
+}
+/**
+ * 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 function applyEnvOverlay(user, env) {
+    const overlaid = { ...user };
+    for (const { env: envKey, key } of ENV_OVERLAY_KEYS) {
+        const value = readNonEmpty(env, envKey);
+        if (value !== undefined) {
+            overlaid[key] = value;
+        }
+    }
+    const prScope = readNonEmpty(env, "PHOEBE_PR_SCOPE");
+    if (prScope !== undefined) {
+        if (!PR_SCOPE_VALUES.includes(prScope)) {
+            throw new Error(`PHOEBE_PR_SCOPE must be one of ${PR_SCOPE_VALUES.join(", ")} (got "${prScope}").`);
+        }
+        overlaid.prScope = prScope;
+    }
+    const draftPrs = readNonEmpty(env, "PHOEBE_DRAFT_PRS");
+    if (draftPrs !== undefined) {
+        if (!DRAFT_PRS_VALUES.includes(draftPrs)) {
+            throw new Error(`PHOEBE_DRAFT_PRS must be one of ${DRAFT_PRS_VALUES.join(", ")} (got "${draftPrs}").`);
+        }
+        overlaid.draftPrs = draftPrs;
+    }
+    const defaultProvider = readNonEmpty(env, "PHOEBE_DEFAULT_PROVIDER");
+    if (defaultProvider !== undefined) {
+        if (!PROVIDER_NAMES.includes(defaultProvider)) {
+            throw new Error(`PHOEBE_DEFAULT_PROVIDER must be one of ${PROVIDER_NAMES.join(", ")} (got "${defaultProvider}").`);
+        }
+        overlaid.defaultProvider = defaultProvider;
+    }
+    return overlaid;
+}
+/**
+ * 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 function resolveConfigPath(argPath, cwd) {
+    const candidate = argPath ?? "phoebe.config.ts";
+    const absolute = isAbsolute(candidate) ? candidate : resolvePath(cwd, candidate);
+    if (!existsSync(absolute)) {
+        throw new Error(argPath
+            ? `Config file not found: ${absolute} (passed via --config).`
+            : `Config file not found: ${absolute}. ` +
+                `Create a phoebe.config.ts in the current directory or pass --config <path>.`);
+    }
+    return absolute;
+}
+/**
+ * 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 async function loadUserConfig(configPath) {
+    const url = pathToFileURL(configPath).href;
+    let mod;
+    try {
+        mod = await import(__rewriteRelativeImportExtension(url));
+    }
+    catch (error) {
+        throw new Error(`Failed to load ${configPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const record = mod;
+    const candidate = (typeof record["default"] === "object" && record["default"] !== null
+        ? record["default"]
+        : undefined) ??
+        (typeof record["config"] === "object" && record["config"] !== null
+            ? record["config"]
+            : undefined);
+    if (!candidate) {
+        throw new Error(`${configPath} must export a Phoebe config as \`export default defineConfig({ ... })\` ` +
+            `or a named \`export const config = { ... }\`.`);
+    }
+    return candidate;
+}

package/dist/src/main.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Drive the Phoebe worker loop until it exits (persistent mode) or completes
+ * one unit (`--run-once`). Called by src/cli.ts after the resolved config is
+ * installed; the CLI passes its argv with `--config <path>` already stripped
+ * so this only sees engine-level flags.
+ */
+export declare function runEngine(argv?: readonly string[]): Promise<void>;