phoebe-agent 0.0.0 → 0.1.1

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>;

package/dist/src/load-config.js

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

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