beflow 0.1.0 → 0.2.0

package/src/core/policy.ts

@@ -0,0 +1,214 @@
+import { isAbsolute, resolve } from "node:path";
+
+import { Glob, file, spawn } from "bun";
+
+import type { PolicyDecision, PolicyRule, ResolvedPolicy } from "../model/types.ts";
+import type { Exec } from "./worktree.ts";
+
+/** The change context handed to the policy gate after a run produces a diff. */
+export interface PolicyContext {
+    agent: string;
+    jobKind: string;
+    repo: string;
+    baseBranch: string;
+    changedFiles: string[];
+    issueKey: string;
+}
+
+export interface PolicyResult {
+    decision: PolicyDecision;
+    reason: string;
+}
+
+/**
+ * Injectable runner for the external command evaluator: spawns `argv` in `cwd`,
+ * pipes `stdin` to it, and returns the exit code with stdout/stderr. Tests fake
+ * this; production uses `defaultPolicyExec`.
+ */
+export type PolicyExec = (
+    argv: string[],
+    cwd: string,
+    stdin: string,
+) => Promise<{ exitCode: number; stdout: string; stderr: string }>;
+
+/**
+ * Injectable file reader for the agentowners evaluator: returns the file text, or
+ * `undefined` when the file is absent. Tests fake this; production uses
+ * `defaultPolicyReader`.
+ */
+export type PolicyReader = (path: string) => Promise<string | undefined>;
+
+/** Most-restrictive-wins ordering: a lower rank beats a higher one. */
+const DECISION_RANK: Record<PolicyDecision, number> = { block: 0, require_approval: 1, allow: 2 };
+
+/**
+ * Changed files relative to the merge-base of `base` and HEAD. The three-dot form
+ * isolates the run's own changes from commits that landed on `base` in parallel.
+ */
+export async function computeChangedFiles(cwd: string, base: string, exec: Exec): Promise<string[]> {
+    const result = await exec("git", ["-C", cwd, "diff", "--name-only", `${base}...HEAD`]);
+    if (result.code !== 0) {
+        throw new Error(`beflow: git diff failed (exit ${String(result.code)}): ${result.stderr.trim()}`);
+    }
+    return result.stdout
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+}
+
+function ruleMatches(rule: { paths?: string[]; agent?: string }, context: PolicyContext): boolean {
+    if (rule.agent !== undefined && rule.agent !== context.agent) {
+        return false;
+    }
+    if (rule.paths === undefined) {
+        return true;
+    }
+    return rule.paths.some((pattern) => {
+        const glob = new Glob(pattern);
+        return context.changedFiles.some((file) => glob.match(file));
+    });
+}
+
+/** Most-restrictive-wins evaluation of a rule set against a change context. */
+function evaluateRules(rules: PolicyRule[], context: PolicyContext): PolicyResult {
+    const matched = rules.filter((rule) => ruleMatches(rule, context));
+    if (matched.length === 0) {
+        return { decision: "allow", reason: "no policy rule matched" };
+    }
+    const winner = matched.reduce((best, rule) =>
+        DECISION_RANK[rule.decision] < DECISION_RANK[best.decision] ? rule : best,
+    );
+    const scope = winner.agent !== undefined ? ` agent=${winner.agent}` : "";
+    const paths = winner.paths !== undefined ? ` paths=${winner.paths.join(",")}` : "";
+    return { decision: winner.decision, reason: `rule decision=${winner.decision}${scope}${paths}` };
+}
+
+function evaluateGlobs(context: PolicyContext, policy: ResolvedPolicy): PolicyResult {
+    return evaluateRules(policy.rules ?? [], context);
+}
+
+/**
+ * Parse a CODEOWNERS-style AGENTOWNERS file into policy rules. Each non-blank,
+ * non-comment line is `<path-glob> <decision> [agent]`; `#` starts a comment.
+ * Fails closed: an invalid decision or a malformed line throws rather than being
+ * silently skipped, so a broken policy file never degrades to an allow.
+ */
+export function parseAgentowners(text: string): PolicyRule[] {
+    const rules: PolicyRule[] = [];
+    for (const [index, line] of text.split("\n").entries()) {
+        const stripped = (line.split("#", 1)[0] ?? "").trim();
+        if (stripped.length === 0) {
+            continue;
+        }
+        const [glob, decision, agent, ...rest] = stripped.split(/\s+/);
+        if (glob === undefined || decision === undefined || rest.length > 0) {
+            throw new Error(`beflow: malformed AGENTOWNERS line ${String(index + 1)}: "${line.trim()}"`);
+        }
+        if (!isPolicyDecision(decision)) {
+            throw new Error(`beflow: invalid AGENTOWNERS decision on line ${String(index + 1)}: "${decision}"`);
+        }
+        rules.push({ decision, paths: [glob], ...(agent !== undefined ? { agent } : {}) });
+    }
+    return rules;
+}
+
+async function evaluateAgentowners(
+    context: PolicyContext,
+    policy: ResolvedPolicy,
+    cwd: string,
+    reader: PolicyReader,
+): Promise<PolicyResult> {
+    const configured = policy.agentownersPath ?? ".github/AGENTOWNERS";
+    const path = isAbsolute(configured) ? configured : resolve(cwd, configured);
+    const text = await reader(path);
+    if (text === undefined) {
+        return { decision: "allow", reason: `no AGENTOWNERS file at ${path}` };
+    }
+    return evaluateRules(parseAgentowners(text), context);
+}
+
+function isPolicyDecision(value: unknown): value is PolicyDecision {
+    return value === "block" || value === "require_approval" || value === "allow";
+}
+
+async function evaluateCommand(
+    context: PolicyContext,
+    policy: ResolvedPolicy,
+    exec: PolicyExec,
+): Promise<PolicyResult> {
+    if (policy.command === undefined || policy.command.length === 0) {
+        throw new Error("beflow: policy evaluator is 'command' but policy.command is missing");
+    }
+    const ran = await exec(policy.command, context.repo, JSON.stringify(context));
+    if (ran.exitCode !== 0) {
+        throw new Error(`beflow: policy command failed (exit ${String(ran.exitCode)}): ${ran.stderr.trim()}`);
+    }
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(ran.stdout);
+    } catch {
+        throw new Error(`beflow: policy command emitted non-JSON output: ${ran.stdout.trim()}`);
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+        throw new Error(`beflow: policy command output is not an object: ${ran.stdout.trim()}`);
+    }
+    const { decision, reason } = parsed as { decision?: unknown; reason?: unknown };
+    if (!isPolicyDecision(decision)) {
+        throw new Error(`beflow: policy command returned an invalid decision: ${JSON.stringify(decision)}`);
+    }
+    return { decision, reason: typeof reason === "string" ? reason : "" };
+}
+
+/**
+ * Apply the resolved policy to a change context. `off` always allows; `globs`
+ * runs the rule set with most-restrictive-wins; `agentowners` runs the same engine
+ * over a CODEOWNERS-style file (missing file allows, malformed file throws);
+ * `command` delegates to an external evaluator and treats any engine failure as a
+ * hard error (never a silent allow).
+ */
+export async function evaluatePolicy(
+    context: PolicyContext,
+    policy: ResolvedPolicy,
+    exec: PolicyExec,
+    cwd: string,
+    reader: PolicyReader = defaultPolicyReader,
+): Promise<PolicyResult> {
+    switch (policy.evaluator) {
+        case "off":
+            return { decision: "allow", reason: "policy disabled" };
+        case "globs":
+            return evaluateGlobs(context, policy);
+        case "agentowners":
+            return evaluateAgentowners(context, policy, cwd, reader);
+        case "command":
+            return evaluateCommand(context, policy, exec);
+        default: {
+            const exhaustive: never = policy.evaluator;
+            throw new Error(`beflow: unknown policy evaluator "${String(exhaustive)}"`);
+        }
+    }
+}
+
+/** Default `PolicyExec`: spawn `argv` in `cwd`, write `stdin`, capture stdout/stderr. */
+export async function defaultPolicyExec(
+    argv: string[],
+    cwd: string,
+    stdin: string,
+): Promise<{ exitCode: number; stdout: string; stderr: string }> {
+    const proc = spawn(argv, { cwd, stderr: "pipe", stdin: new TextEncoder().encode(stdin), stdout: "pipe" });
+    const [stdout, stderr, exitCode] = await Promise.all([
+        new Response(proc.stdout).text(),
+        new Response(proc.stderr).text(),
+        proc.exited,
+    ]);
+    return { exitCode, stderr, stdout };
+}
+
+/** Default `PolicyReader`: read `path` via `Bun.file`, returning `undefined` when absent. */
+export async function defaultPolicyReader(path: string): Promise<string | undefined> {
+    const handle = file(path);
+    if (!(await handle.exists())) {
+        return undefined;
+    }
+    return handle.text();
+}

package/src/core/pr.ts

@@ -0,0 +1,169 @@
+import type { Exec } from "./worktree.ts";
+
+export interface PrRef {
+    number: number;
+    url: string;
+}
+
+const AUTO_BASE = "auto";
+
+// stderr substrings gh emits when the requested transition is already done.
+// These are benign (idempotent no-ops), not real failures.
+const ALREADY_READY = /already.*(ready|open for review)|not.*draft/i;
+const ALREADY_CLOSED = /already closed|could not resolve to a pullrequest|no pull requests found/i;
+
+async function runGh(args: string[], exec: Exec): Promise<string> {
+    const result = await exec("gh", args);
+    if (result.code !== 0) {
+        throw new Error(`beflow: gh ${args.join(" ")} failed (exit ${String(result.code)}): ${result.stderr.trim()}`);
+    }
+    return result.stdout;
+}
+
+async function runGitIn(cwd: string, args: string[], exec: Exec): Promise<string> {
+    const fullArgs = ["-C", cwd, ...args];
+    const result = await exec("git", fullArgs);
+    if (result.code !== 0) {
+        throw new Error(
+            `beflow: git ${fullArgs.join(" ")} failed (exit ${String(result.code)}): ${result.stderr.trim()}`,
+        );
+    }
+    return result.stdout;
+}
+
+function prSelector(pr: PrRef | number | string): string {
+    if (typeof pr === "object") {
+        return String(pr.number);
+    }
+    return typeof pr === "number" ? String(pr) : pr;
+}
+
+/**
+ * Resolve the base branch. An explicit value is returned verbatim; the sentinel
+ * `"auto"` triggers detection of the repo's default branch via gh.
+ */
+export async function detectBaseBranch(repo: string, baseBranch: string, exec: Exec): Promise<string> {
+    if (baseBranch !== AUTO_BASE) {
+        return baseBranch;
+    }
+    const stdout = await runGh(
+        ["repo", "view", repo, "--json", "defaultBranchRef", "-q", ".defaultBranchRef.name"],
+        exec,
+    );
+    return stdout.trim();
+}
+
+/**
+ * True iff the worktree's HEAD carries commits that `base` lacks — the
+ * "did the agent actually produce work" check that keeps PR-open a no-op
+ * when nothing changed.
+ */
+export async function hasCommits(cwd: string, base: string, exec: Exec): Promise<boolean> {
+    const stdout = await runGitIn(cwd, ["rev-list", "--count", `${base}..HEAD`], exec);
+    return Number.parseInt(stdout.trim(), 10) > 0;
+}
+
+function parsePrRef(stdout: string): PrRef {
+    const trimmed = stdout.trim();
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(trimmed);
+    } catch {
+        // `gh pr create` prints the bare PR URL on success.
+        const number = Number.parseInt(trimmed.split("/").at(-1) ?? "", 10);
+        if (Number.isNaN(number)) {
+            throw new Error(`beflow: could not parse PR from gh output: ${trimmed}`);
+        }
+        return { number, url: trimmed };
+    }
+    const obj: Record<string, unknown> = typeof parsed === "object" && parsed !== null ? { ...parsed } : {};
+    const url = typeof obj.url === "string" ? obj.url : "";
+    const number = typeof obj.number === "number" ? obj.number : Number.NaN;
+    if (url === "" || Number.isNaN(number)) {
+        throw new Error(`beflow: could not parse PR from gh output: ${trimmed}`);
+    }
+    return { number, url };
+}
+
+/**
+ * Open a draft PR for `head` against `base`. Idempotent: if a PR for that head
+ * already exists, the existing one is returned instead of failing.
+ */
+export async function openDraftPr(
+    args: { repo: string; head: string; base: string; title: string; body: string; cwd: string },
+    exec: Exec,
+): Promise<PrRef> {
+    const created = await exec("gh", [
+        "pr",
+        "create",
+        "--repo",
+        args.repo,
+        "--draft",
+        "--base",
+        args.base,
+        "--head",
+        args.head,
+        "--title",
+        args.title,
+        "--body",
+        args.body,
+    ]);
+    if (created.code === 0) {
+        return parsePrRef(created.stdout);
+    }
+    const existing = await exec("gh", ["pr", "view", args.head, "--repo", args.repo, "--json", "url,number"]);
+    if (existing.code === 0) {
+        return parsePrRef(existing.stdout);
+    }
+    throw new Error(
+        `beflow: gh pr create (head ${args.head}) failed (exit ${String(created.code)}): ${created.stderr.trim()}`,
+    );
+}
+
+/** Mark a PR ready for review. Tolerant of a PR that is already ready. */
+export async function markReady(pr: PrRef | number | string, repo: string, exec: Exec): Promise<void> {
+    const result = await exec("gh", ["pr", "ready", prSelector(pr), "--repo", repo]);
+    if (result.code === 0 || ALREADY_READY.test(result.stderr)) {
+        return;
+    }
+    throw new Error(`beflow: gh pr ready failed (exit ${String(result.code)}): ${result.stderr.trim()}`);
+}
+
+/** Edit a PR's title and/or body. Only the provided fields are passed to gh. */
+export async function editPr(
+    pr: PrRef | number | string,
+    repo: string,
+    fields: { title?: string; body?: string },
+    exec: Exec,
+): Promise<void> {
+    if (fields.title === undefined && fields.body === undefined) {
+        return;
+    }
+    const args = ["pr", "edit", prSelector(pr), "--repo", repo];
+    if (fields.title !== undefined) {
+        args.push("--title", fields.title);
+    }
+    if (fields.body !== undefined) {
+        args.push("--body", fields.body);
+    }
+    await runGh(args, exec);
+}
+
+/**
+ * Close a PR and delete its head branch. Idempotent: an already-closed PR or an
+ * already-gone branch is tolerated; the local branch is best-effort deleted too.
+ */
+export async function closePrAndDeleteBranch(
+    pr: PrRef | number | string,
+    repo: string,
+    branch: string,
+    cwd: string,
+    exec: Exec,
+): Promise<void> {
+    const closed = await exec("gh", ["pr", "close", prSelector(pr), "--repo", repo, "--delete-branch"]);
+    if (closed.code !== 0 && !ALREADY_CLOSED.test(closed.stderr)) {
+        throw new Error(`beflow: gh pr close failed (exit ${String(closed.code)}): ${closed.stderr.trim()}`);
+    }
+    // Best-effort local branch cleanup: a missing branch is the desired end state.
+    await exec("git", ["-C", cwd, "branch", "-D", branch]);
+}

package/src/core/prompts.ts

@@ -133,9 +133,33 @@ export function renderTask(set: PromptSet, issue: Issue, repo: string): string {
     return renderTemplate("task", set.task, buildPromptContext(issue, repo));
 }
 
-export function renderContract(set: PromptSet, jobKind: JobKind, issue: Issue, repo: string): string {
+const AGENT_OWNED_PR_INSTRUCTION = "commit, push, and open a pull request with `gh`, then put the PR URL in `prUrl`.";
+const BEFLOW_OWNED_PR_INSTRUCTION =
+    "commit and push your branch. Do NOT run `gh pr create`, `gh pr edit`, or open or update any pull request — beflow will open the PR from your pushed branch.";
+
+const AGENT_OWNED_PR_CONTINUATION_INSTRUCTION = "UPDATE the existing pull request — do not open a new one.";
+const BEFLOW_OWNED_PR_CONTINUATION_INSTRUCTION =
+    "push your changes. The existing pull request updates automatically — do NOT run `gh pr create` or `gh pr edit`.";
+
+export function renderContract(
+    set: PromptSet,
+    jobKind: JobKind,
+    issue: Issue,
+    repo: string,
+    beflowOwnsPr = false,
+): string {
     const ctx = buildPromptContext(issue, repo);
-    return `${renderTemplate(jobKind, set[jobKind], ctx)}\n\n${renderTemplate("report", set.report, ctx)}`;
+    const promptCtx =
+        jobKind === "implement"
+            ? {
+                  ...ctx,
+                  pr_continuation_instruction: beflowOwnsPr
+                      ? BEFLOW_OWNED_PR_CONTINUATION_INSTRUCTION
+                      : AGENT_OWNED_PR_CONTINUATION_INSTRUCTION,
+                  pr_instruction: beflowOwnsPr ? BEFLOW_OWNED_PR_INSTRUCTION : AGENT_OWNED_PR_INSTRUCTION,
+              }
+            : ctx;
+    return `${renderTemplate(jobKind, set[jobKind], promptCtx)}\n\n${renderTemplate("report", set.report, ctx)}`;
 }
 
 export function renderReviewContract(set: PromptSet, issue: Issue, repo: string): string {

package/src/core/qualitygate.ts

@@ -21,7 +21,7 @@ const MAX_OUTPUT_CHARS = 16000;
  */
 export function resolveQualityGate(config: Config, registry: Registry, projectKey: string): string[] {
     const projectCommands = registry.projects[projectKey]?.qualityGate?.commands;
-    const globalCommands = config.defaults.qualityGate?.commands;
+    const globalCommands = config.qualityGate?.commands;
     return projectCommands ?? globalCommands ?? [];
 }
 

package/src/core/review.ts

@@ -71,11 +71,11 @@ export type ReviewSha = (prUrl: string) => Promise<string | undefined>;
 
 // Project-over-default resolution of the per-project review toggles.
 export function resolveReviewEnabled(config: Config, registry: Registry, projectKey: string): boolean {
-    return registry.projects[projectKey]?.review?.enabled ?? config.defaults.review?.enabled ?? false;
+    return registry.projects[projectKey]?.review?.enabled ?? config.review?.enabled ?? false;
 }
 
 export function resolveReviewPostToPr(config: Config, registry: Registry, projectKey: string): boolean {
-    return registry.projects[projectKey]?.review?.postToPr ?? config.defaults.review?.postToPr ?? false;
+    return registry.projects[projectKey]?.review?.postToPr ?? config.review?.postToPr ?? false;
 }
 
 function projectKeyOf(issueKey: string): string {