phoebe-agent 0.0.0 → 0.1.1

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

@@ -1,163 +0,0 @@
-export declare const PROVIDER_NAMES: readonly ["cursor", "claude", "codex"];
-export type ProviderName = (typeof PROVIDER_NAMES)[number];
-export type PromptFilesConfig = {
-    issue: string;
-    conflict: string;
-    checks: string;
-    reviews: string;
-};
-export type PathsConfig = {
-    /** The private clone (origin hub). */
-    repoDir: string;
-    /** Per-unit git worktrees. */
-    worktreesDir: string;
-    /** Lock, markers, logs. */
-    stateDir: string;
-};
-export type PhoebeConfig = {
-    /** GitHub `owner/repo` slug, passed to every `gh -R` call. */
-    repoSlug: string;
-    /** HTTPS clone URL for the container's private clone. */
-    repoUrl: string;
-    /** Branch PRs target and worktrees base off (usually `main`). */
-    defaultBranch: string;
-    /** Prefix for agent branches; issue branches are `<prefix>issue-<n>`. */
-    branchPrefix: string;
-    /** Label marking issues Phoebe may pick up. */
-    readyLabel: string;
-    /** Label the agent applies to an issue it has claimed and is working. */
-    processingLabel: string;
-    /** Which open PRs the conflicts/checks/reviews work-kinds scan.
-     *  "phoebe" = only branchPrefix branches. "all" = any same-repo PR. */
-    prScope: "phoebe" | "all";
-    /** Draft PR handling: "skip-non-phoebe" = drafts on non-Phoebe branches are
-     *  off-limits; "skip-all" = never touch drafts; "include" = drafts are fair game. */
-    draftPrs: "skip-non-phoebe" | "skip-all" | "include";
-    /** PRs carrying this label are excluded from the PR scan in every mode. */
-    prOptOutLabel: string;
-    /** Shell command strings — toolchains differ per repo, so these are data. */
-    installCommand: string;
-    checkCommand: string;
-    testCommand: string;
-    /** The all-in-one gate the agent runs before pushing (e.g. `npm run ready`).
-     *  Substituted into default prompts as `{{READY_COMMAND}}`. */
-    readyCommand: string;
-    /**
-     * JavaScript-compatible regex source that matches an issue-blocker reference
-     * in issue body text. Must expose the blocker issue number as capture group 1.
-     * Compiled with the `gi` flags.
-     */
-    blockedByPattern: string;
-    /**
-     * Markdown heading the reviews agent must include when it posts its summary
-     * comment. The orchestrator detects the summary by substring match on this
-     * exact string, so it must be unique enough not to collide with other
-     * comments. Substituted into the default reviews prompt as
-     * `{{REVIEWS_SUCCESS_HEADING}}`.
-     */
-    reviewsSuccessHeading: string;
-    /** Prompt template paths, relative to the package root (apps/phoebe). */
-    promptFiles: PromptFilesConfig;
-    /** Ordered work kinds, validated by the orchestrator at startup. */
-    workOrder: readonly string[];
-    defaultProvider: ProviderName;
-    defaultModels: Record<ProviderName, string>;
-    /** Env var holding each provider's API key — the only key the agent child inherits. */
-    providerEnv: Record<ProviderName, string>;
-    /**
-     * Repo paths that mean "Phoebe's own code changed" — a fetch of the default
-     * branch touching these makes the orchestrator exit for a supervisor
-     * reinstall + re-exec. Directory entries must end with `/`.
-     */
-    selfUpdatePaths: readonly string[];
-    /** Container filesystem layout (named volumes). */
-    paths: PathsConfig;
-};
-/**
- * User-facing shape of `phoebe.config.ts`. Only the five fields with no sane
- * cross-repo default are required; everything else is optional and filled from
- * `CONFIG_DEFAULTS` by `resolveConfig()`. Nested objects (`promptFiles`,
- * `paths`, `defaultModels`, `providerEnv`) are merged key-by-key, so overriding
- * one provider's model or one prompt file does not force the caller to supply
- * the rest.
- */
-export type PhoebeUserConfig = {
-    repoSlug: string;
-    repoUrl: string;
-    installCommand: string;
-    checkCommand: string;
-    testCommand: string;
-    defaultBranch?: string;
-    branchPrefix?: string;
-    readyLabel?: string;
-    processingLabel?: string;
-    prScope?: PhoebeConfig["prScope"];
-    draftPrs?: PhoebeConfig["draftPrs"];
-    prOptOutLabel?: string;
-    readyCommand?: string;
-    blockedByPattern?: string;
-    reviewsSuccessHeading?: string;
-    promptFiles?: Partial<PromptFilesConfig>;
-    workOrder?: readonly string[];
-    defaultProvider?: ProviderName;
-    defaultModels?: Partial<Record<ProviderName, string>>;
-    providerEnv?: Partial<Record<ProviderName, string>>;
-    selfUpdatePaths?: readonly string[];
-    paths?: Partial<PathsConfig>;
-};
-/**
- * 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 declare const CONFIG_DEFAULTS: {
-    readonly defaultBranch: "main";
-    readonly branchPrefix: "phoebe/";
-    readonly readyLabel: "ready-for-agent";
-    readonly processingLabel: "processing";
-    readonly prScope: "phoebe";
-    readonly draftPrs: "skip-non-phoebe";
-    readonly prOptOutLabel: "ready-for-human";
-    readonly readyCommand: "npm run ready";
-    readonly blockedByPattern: string;
-    readonly reviewsSuccessHeading: "## Review feedback addressed";
-    readonly promptFiles: {
-        issue: string;
-        conflict: string;
-        checks: string;
-        reviews: string;
-    };
-    readonly workOrder: readonly string[];
-    readonly defaultProvider: ProviderName;
-    readonly defaultModels: {
-        cursor: string;
-        claude: string;
-        codex: string;
-    };
-    readonly providerEnv: {
-        cursor: string;
-        claude: string;
-        codex: string;
-    };
-    readonly selfUpdatePaths: readonly string[];
-    readonly paths: {
-        repoDir: string;
-        worktreesDir: string;
-        stateDir: string;
-    };
-};
-/**
- * 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 declare function validateUserConfig(user: PhoebeUserConfig): void;
-/**
- * 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 declare function resolveConfig(user: PhoebeUserConfig): PhoebeConfig;

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;