agent-merge-broker 0.3.0

package/dist/publisher.js

@@ -0,0 +1,144 @@
+import path from "node:path";
+import { BrokerError } from "./errors.js";
+import { runCommand } from "./process.js";
+function renderTitle(template, batch) {
+    return template.replaceAll("{batchId}", batch.id).replaceAll("{taskCount}", String(batch.taskIds.length));
+}
+function pullRequestBody(batch, tasks) {
+    const rows = tasks.map((task) => `- \`${task.id}\`${task.title ? ` — ${task.title}` : ""}`);
+    return [
+        "## Merge Broker batch",
+        "",
+        `Batch: \`${batch.id}\``,
+        `Base: \`${batch.baseBranch}\` at \`${batch.baseSha}\``,
+        "",
+        "### Tasks",
+        "",
+        ...rows,
+        "",
+        "### Validation",
+        "",
+        ...batch.validations.map((result) => `- ${result.exitCode === 0 ? "✅" : "❌"} ${result.name}`),
+        ...(batch.provenancePath
+            ? ["", "### Provenance", "", `- Batch manifest: \`${batch.provenancePath}\``]
+            : []),
+        "",
+        "Generated by Agent Merge Broker. Commit receipts and validation output remain in local broker state.",
+    ].join("\n");
+}
+export async function publishBatch(options) {
+    const { repo, config, batch, tasks } = options;
+    if (!batch.branchName)
+        throw new BrokerError("NO_BRANCH", `Batch ${batch.id} has no integration branch.`);
+    if (config.publish.mode === "none") {
+        throw new BrokerError("PUBLISH_DISABLED", "Publishing is disabled in .merge-broker/config.json.");
+    }
+    await repo.push(config.remote, batch.branchName);
+    if (config.publish.mode === "branch") {
+        return { mode: "branch", branchName: batch.branchName };
+    }
+    const title = renderTitle(config.publish.titleTemplate, batch);
+    const args = [
+        "pr",
+        "create",
+        "--base",
+        config.baseBranch,
+        "--head",
+        batch.branchName,
+        "--title",
+        title,
+        "--body-file",
+        "-",
+    ];
+    if (config.publish.draft)
+        args.push("--draft");
+    for (const label of config.publish.labels)
+        args.push("--label", label);
+    const result = await runCommand("gh", args, {
+        cwd: repo.root,
+        input: pullRequestBody(batch, tasks),
+    });
+    const url = result.stdout
+        .split("\n")
+        .map((line) => line.trim())
+        .find((line) => /^https?:\/\//u.test(line));
+    if (!url) {
+        throw new BrokerError("PUBLISH_FAILED", "GitHub CLI did not return a pull request URL.", {
+            stdout: result.stdout,
+            stderr: result.stderr,
+        });
+    }
+    const autoMergeEnabled = config.publish.autoMerge ? await enableAutoMerge(repo.root, url, config) : false;
+    return { mode: "pull-request", branchName: batch.branchName, pullRequestUrl: url, autoMergeEnabled };
+}
+/**
+ * GitHub's own view of whether a pull request can merge. Returns undefined when the state cannot be
+ * read at all, which is treated as "do not merge" rather than as permission to proceed.
+ */
+export async function readMergeState(repoRoot, pullRequestUrl) {
+    const result = await runCommand("gh", ["pr", "view", pullRequestUrl, "--json", "state,mergeStateStatus,mergeable"], { cwd: repoRoot, allowFailure: true });
+    if (result.exitCode !== 0)
+        return undefined;
+    try {
+        const value = JSON.parse(result.stdout);
+        return {
+            state: value.state ?? "UNKNOWN",
+            mergeStateStatus: value.mergeStateStatus ?? "UNKNOWN",
+            mergeable: value.mergeable ?? "UNKNOWN",
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Hands the merge decision to GitHub: it lands the pull request once required checks pass, and
+ * updates the branch itself when the base branch requires it. The broker never pushes to the base
+ * branch, so branch protection stays authoritative.
+ */
+export async function enableAutoMerge(repoRoot, pullRequestUrl, config) {
+    const result = await runCommand("gh", ["pr", "merge", pullRequestUrl, "--auto", `--${config.publish.mergeMethod}`], { cwd: repoRoot, allowFailure: true });
+    if (result.exitCode === 0)
+        return true;
+    // GitHub refuses to queue auto-merge on a pull request that is already mergeable, which happens
+    // whenever the required checks finish before publication returns. Ask GitHub what the state is
+    // instead of reading the CLI's prose, which differs across gh versions and locales.
+    const mergeState = await readMergeState(repoRoot, pullRequestUrl);
+    if (mergeState?.state === "MERGED")
+        return true;
+    if (mergeState?.mergeStateStatus === "CLEAN") {
+        // "CLEAN" means mergeable with every required check already passed, so merging now is exactly
+        // what the auto-merge queue would have done.
+        const direct = await runCommand("gh", ["pr", "merge", pullRequestUrl, `--${config.publish.mergeMethod}`], {
+            cwd: repoRoot,
+            allowFailure: true,
+        });
+        if (direct.exitCode === 0)
+            return true;
+        throw new BrokerError("AUTO_MERGE_FAILED", "The pull request reported a clean merge state but did not merge.", {
+            pullRequestUrl,
+            mergeState,
+            stdout: direct.stdout,
+            stderr: direct.stderr,
+        });
+    }
+    throw new BrokerError("AUTO_MERGE_FAILED", "Could not enable auto-merge on the published pull request. Enable auto-merge in the repository settings, or set publish.autoMerge to false.", {
+        pullRequestUrl,
+        ...(mergeState ? { mergeState } : {}),
+        stdout: result.stdout,
+        stderr: result.stderr,
+    });
+}
+export async function inspectPullRequest(repoRoot, pullRequestUrl) {
+    const result = await runCommand("gh", ["pr", "view", pullRequestUrl, "--json", "state,mergedAt,mergeCommit"], { cwd: repoRoot });
+    const value = JSON.parse(result.stdout);
+    return {
+        state: value.state,
+        ...(value.mergedAt ? { mergedAt: value.mergedAt } : {}),
+        ...(value.mergeCommit?.oid ? { mergeCommitSha: value.mergeCommit.oid } : {}),
+    };
+}
+export function defaultProjectTitle(repoRoot) {
+    return path.basename(repoRoot);
+}
+//# sourceMappingURL=publisher.js.map

package/dist/publisher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publisher.js","sourceRoot":"","sources":["../src/publisher.ts"],"names":[],"mappings":"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"}

package/dist/scheduler.d.ts

@@ -0,0 +1,6 @@
+import type { BrokerConfig, BrokerState, SchedulePlan } from "./types.js";
+export declare function scheduleTasks(state: BrokerState, config: BrokerConfig, options?: {
+    taskIds?: string[];
+    maxTasks?: number;
+}): SchedulePlan;
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../src/scheduler.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AA+BtF,wBAAgB,aAAa,CAC3B,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GACtD,YAAY,CA0Ed"}

package/dist/scheduler.js

@@ -0,0 +1,96 @@
+import { matchedSerializedPatterns, pathsOverlap } from "./patterns.js";
+function timestamp(value) {
+    return value ? Date.parse(value) : Number.MAX_SAFE_INTEGER;
+}
+function taskFromState(state, taskId) {
+    return Object.hasOwn(state.tasks, taskId) ? state.tasks[taskId] : undefined;
+}
+function dependencyReady(task, selected, state, requireDependencies) {
+    if (!requireDependencies)
+        return true;
+    return task.dependsOn.every((dependency) => {
+        const dependencyTask = taskFromState(state, dependency);
+        return dependencyTask?.status === "merged" || selected.has(dependency);
+    });
+}
+function compareTasks(left, right) {
+    return (right.priority - left.priority ||
+        timestamp(left.submittedAt) - timestamp(right.submittedAt) ||
+        left.id.localeCompare(right.id));
+}
+export function scheduleTasks(state, config, options = {}) {
+    const requested = options.taskIds ? new Set(options.taskIds) : undefined;
+    const candidates = Object.values(state.tasks)
+        .filter((task) => task.status === "submitted" && (!requested || requested.has(task.id)))
+        .sort(compareTasks);
+    const selected = [];
+    const selectedIds = new Set();
+    const rejected = [];
+    const rejectedIds = new Set();
+    const maxTasks = Math.min(options.maxTasks ?? config.scheduling.maxTasks, config.scheduling.maxTasks);
+    let totalCommits = 0;
+    let madeProgress = true;
+    while (madeProgress && selected.length < maxTasks) {
+        madeProgress = false;
+        for (const task of candidates) {
+            if (selectedIds.has(task.id) || rejectedIds.has(task.id))
+                continue;
+            if (!dependencyReady(task, selectedIds, state, config.policies.requireDependencies))
+                continue;
+            if (totalCommits + task.commits.length > config.scheduling.maxCommits) {
+                // A task larger than the whole limit can never be scheduled, however many times it is
+                // re-planned. Say so, instead of reporting the same transient-looking reason forever.
+                rejected.push({
+                    taskId: task.id,
+                    reason: task.commits.length > config.scheduling.maxCommits
+                        ? `task has ${task.commits.length} commits and can never fit scheduling.maxCommits (${config.scheduling.maxCommits}); raise the limit or split the task`
+                        : "batch commit limit",
+                });
+                rejectedIds.add(task.id);
+                continue;
+            }
+            const collision = selected.find((chosen) => {
+                if (!config.scheduling.allowPathOverlap && pathsOverlap(task.actualPaths, chosen.actualPaths))
+                    return true;
+                const taskResources = matchedSerializedPatterns(task.actualPaths, config.leases.serializedPatterns);
+                const chosenResources = matchedSerializedPatterns(chosen.actualPaths, config.leases.serializedPatterns);
+                return taskResources.some((resource) => chosenResources.includes(resource));
+            });
+            if (collision) {
+                rejected.push({ taskId: task.id, reason: "conflicting change set", conflictsWith: collision.id });
+                rejectedIds.add(task.id);
+                continue;
+            }
+            selected.push(task);
+            selectedIds.add(task.id);
+            totalCommits += task.commits.length;
+            madeProgress = true;
+            if (selected.length >= maxTasks)
+                break;
+        }
+    }
+    for (const task of candidates) {
+        if (selectedIds.has(task.id) || rejectedIds.has(task.id))
+            continue;
+        const missing = config.policies.requireDependencies ? task.dependsOn.filter((dependency) => {
+            const dependencyTask = taskFromState(state, dependency);
+            return dependencyTask?.status !== "merged" && !selectedIds.has(dependency);
+        }) : [];
+        rejected.push({
+            taskId: task.id,
+            reason: missing.length > 0 ? `dependencies not integrated: ${missing.join(", ")}` : "batch task limit",
+        });
+    }
+    if (requested) {
+        for (const taskId of requested) {
+            const task = taskFromState(state, taskId);
+            if (!task)
+                rejected.push({ taskId, reason: "unknown task" });
+            else if (task.status !== "submitted") {
+                rejected.push({ taskId, reason: `task status is ${task.status}` });
+            }
+        }
+    }
+    return { selected, rejected, totalCommits };
+}
+//# sourceMappingURL=scheduler.js.map

package/dist/scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.js","sourceRoot":"","sources":["../src/scheduler.ts"],"names":[],"mappings":"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"}

package/dist/store.d.ts

@@ -0,0 +1,73 @@
+import { type AuditEvent, type BrokerState, type CommitReceipt } from "./types.js";
+export interface LockStatus {
+    name: string;
+    held: boolean;
+    path: string;
+    owner?: {
+        pid?: number;
+        host?: string;
+        createdAt?: string;
+    };
+    ageMs?: number;
+    /** True only when the holder is provably gone: this machine, and the process no longer exists. */
+    abandoned?: boolean;
+}
+export type AuditRecorder = (event: string, fields?: Omit<AuditEvent, "sequence" | "at" | "event">) => void;
+export declare class StateStore {
+    readonly directory: string;
+    readonly worktreesDirectory: string;
+    readonly archiveDirectory: string;
+    readonly tokensDirectory: string;
+    private readonly stateFile;
+    private readonly auditFile;
+    private readonly receiptsDirectory;
+    private readonly batchesDirectory;
+    private readonly lockTimeoutMs;
+    constructor(commonGitDir: string, stateDirectory: string, lockTimeoutSeconds: number);
+    initialize(): Promise<void>;
+    read(): Promise<BrokerState>;
+    transaction<T>(mutator: (state: BrokerState, audit: AuditRecorder) => Promise<T> | T): Promise<T>;
+    withIntegrationLock<T>(operation: () => Promise<T>): Promise<T>;
+    writeReceipt(receipt: CommitReceipt): Promise<string>;
+    tokenPath(taskId: string): string;
+    /**
+     * Holds a worker's lease token for it. A token shown once and never stored forces every adopter to
+     * build a token store, and the obvious implementation puts a live credential in the working tree
+     * where `git add` and validator commands can reach it. Here it stays owner-readable, beside the
+     * state it authorizes, under a directory whose contents are already trusted.
+     */
+    writeToken(taskId: string, token: string, target?: string): Promise<string>;
+    readToken(taskId: string): Promise<string | undefined>;
+    deleteToken(taskId: string): Promise<void>;
+    writeBatchManifest(batchId: string, manifest: unknown): Promise<string>;
+    /**
+     * Reads the tail of the active audit stream. Deliberately tolerant: a tail read can begin
+     * mid-line, and a crash between writing and flushing can leave a truncated final line. Neither is
+     * a reason to make the whole audit trail unreadable, which is exactly when it is needed most.
+     */
+    readAudit(limit?: number): Promise<AuditEvent[]>;
+    /**
+     * Moves the active audit file aside once it grows large enough to make reads expensive. Segments
+     * are never deleted: an audit stream that silently forgets is worse than a large one.
+     */
+    private rotateAuditIfLarge;
+    /** Writes a retired slice of state to the archive directory and returns its path. */
+    archive(name: string, value: unknown): Promise<string>;
+    inspectLock(name: string): Promise<LockStatus>;
+    /**
+     * Releases a held lock. Without `force` this refuses unless the holder is provably gone, because
+     * removing a live lock allows two integrations to run against the same repository at once.
+     */
+    releaseLock(name: string, options?: {
+        force?: boolean;
+    }): Promise<LockStatus>;
+    private withLock;
+    /**
+     * True only when the lock is provably abandoned: written by this machine, by a process that is
+     * gone. An unreadable owner file is not proof -- it is also what a lock looks like in the instant
+     * between creating the directory and recording its owner.
+     */
+    private lockOwnerCrashed;
+    private atomicWrite;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"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"}