@jwillert/forgeflow 0.1.0

package/dist/workflows/implement.js

@@ -0,0 +1,154 @@
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { defineWorkflow, Match, labelAdded } from "../core/workflow.js";
+import { checkoutBaseBranch, commitsAhead, pushBranch } from "./shared/git.js";
+import { createPodmanSandbox, piAgent } from "./shared/sandcastle.js";
+import { runWithAgentLifecycle } from "./shared/lifecycle.js";
+const here = dirname(fileURLToPath(import.meta.url));
+const defaultPromptFile = join(here, "prompts/implement.md");
+export function createImplementWorkflow(options = {}) {
+    const triggerLabel = options.triggerLabel ?? "agent:implement";
+    const reviewLabel = options.reviewLabel ?? "agent:review";
+    const promptFile = options.promptFile ?? defaultPromptFile;
+    return defineWorkflow(options.id ?? "implement", {
+        match: async ({ event, workReader }) => {
+            if (!labelAdded(event, triggerLabel))
+                return Match.ignore();
+            if (event.workTarget.kind !== "issue")
+                return Match.ignore();
+            const blockers = await workReader.listBlockingIssues(event.workTarget).catch(() => []);
+            const openBlockerIds = [];
+            for (const blocker of blockers) {
+                const snapshot = await workReader.getTarget(blocker).catch(() => undefined);
+                if (snapshot?.state !== "closed")
+                    openBlockerIds.push(blocker.id);
+            }
+            if (openBlockerIds.length > 0)
+                return Match.defer(`Blocked by #${openBlockerIds.join(", #")}`);
+            return Match.accept();
+        },
+        run: async ({ command, workReader, workTracker, codeHost, codeReviewHost, commandState }) => runWithAgentLifecycle({ workTracker, target: command.workTarget, labels: { trigger: triggerLabel, blocked: options.blockedLabel, inProgress: options.inProgressLabel } }, async () => {
+            const env_1 = { stack: [], error: void 0, hasError: false };
+            try {
+                const issueNumber = command.workTarget.id;
+                const checkout = await codeHost.resolveCheckout(command.codeTarget, command);
+                await checkoutBaseBranch({ baseRef: checkout.baseRef });
+                const issueSnapshot = await workReader.getTarget(command.workTarget).catch(() => undefined);
+                const issueComments = await codeReviewHost.listGeneralComments(command.workTarget).catch(() => []);
+                const issueContext = issueSnapshot
+                    ? [`# ${issueSnapshot.title}\n\n${issueSnapshot.body ?? ""}`, ...issueComments.map(c => `---\n${c.author ?? "unknown"}: ${c.body}`)].join("\n\n")
+                    : command.body ?? `Issue #${issueNumber}: ${command.title}`;
+                const sandbox = __addDisposableResource(env_1, await createPodmanSandbox({
+                    ...options,
+                    branch: checkout.workBranch,
+                    preflightCommand: options.preflightCommand,
+                }), true);
+                const result = await sandbox.run({
+                    name: `implement-#${issueNumber}`,
+                    agent: piAgent(options),
+                    promptFile,
+                    promptArgs: {
+                        ISSUE_NUMBER: issueNumber,
+                        ISSUE_TITLE: command.title,
+                        ISSUE_CONTEXT: issueContext,
+                        BRANCH: checkout.workBranch,
+                        BASE_REF: checkout.baseRef,
+                    },
+                    idleTimeoutSeconds: options.idleTimeoutSeconds ?? 900,
+                });
+                const count = await commitsAhead({ baseRef: checkout.baseRef, cwd: sandbox.worktreePath });
+                if ((!Number.isFinite(count) || count === 0) && result.commits.length === 0) {
+                    throw new Error("Agent finished but no commits were made on the branch.");
+                }
+                await pushBranch({ branch: checkout.workBranch, cwd: sandbox.worktreePath });
+                const existing = await commandState.getLinkedChangeRequest();
+                const changeRequest = await codeHost.openOrUpdateChangeRequest({
+                    existing,
+                    sourceBranch: {
+                        provider: command.codeTarget.provider,
+                        repo: command.codeTarget.repo,
+                        name: checkout.workBranch,
+                    },
+                    targetBranch: checkout.baseRef,
+                    title: `Fix #${issueNumber}: ${command.title}`.slice(0, 256),
+                    body: `Closes #${issueNumber}\n\nImplemented by the Forgeflow external workflow.`,
+                });
+                await commandState.linkChangeRequest(changeRequest);
+                const reviewTarget = {
+                    provider: command.workTarget.provider,
+                    repo: command.workTarget.repo,
+                    project: command.workTarget.project,
+                    kind: changeRequest.kind,
+                    id: changeRequest.id,
+                    url: changeRequest.url,
+                };
+                await workTracker.addLabel(reviewTarget, reviewLabel).catch(() => undefined);
+                await workTracker.addComment(command.workTarget, `Implementation completed.\n\nChange request: ${changeRequest.url ?? changeRequest.id}`);
+                return { summary: `Implementation completed: ${changeRequest.url ?? changeRequest.id}` };
+            }
+            catch (e_1) {
+                env_1.error = e_1;
+                env_1.hasError = true;
+            }
+            finally {
+                const result_1 = __disposeResources(env_1);
+                if (result_1)
+                    await result_1;
+            }
+        }),
+    });
+}
+export const implement = createImplementWorkflow();
+//# sourceMappingURL=implement.js.map

package/dist/workflows/implement.js.map

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

package/dist/workflows/index.d.ts

@@ -0,0 +1,9 @@
+export { createImplementWorkflow, implement } from "./implement.js";
+export type { ImplementWorkflowOptions } from "./implement.js";
+export { createReviewWorkflow, review } from "./review.js";
+export type { ReviewWorkflowOptions } from "./review.js";
+export { createUpdateBranchWorkflow, updateBranch } from "./update-branch.js";
+export type { UpdateBranchWorkflowOptions } from "./update-branch.js";
+export type { SandboxDefaults, AgentThinking } from "./shared/sandcastle.js";
+export { runWithAgentLifecycle } from "./shared/lifecycle.js";
+export type { AgentLifecycleLabels } from "./shared/lifecycle.js";

package/dist/workflows/index.js

@@ -0,0 +1,5 @@
+export { createImplementWorkflow, implement } from "./implement.js";
+export { createReviewWorkflow, review } from "./review.js";
+export { createUpdateBranchWorkflow, updateBranch } from "./update-branch.js";
+export { runWithAgentLifecycle } from "./shared/lifecycle.js";
+//# sourceMappingURL=index.js.map

package/dist/workflows/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/workflows/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAEnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAE1D,OAAO,EAAE,0BAA0B,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAG7E,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/workflows/prompts/implement.md

@@ -0,0 +1,43 @@
+# TASK
+
+Implement issue #{{ISSUE_NUMBER}}: {{ISSUE_TITLE}}
+
+You are on branch `{{BRANCH}}`, already created from `{{BASE_REF}}`.
+
+# ISSUE
+
+{{ISSUE_CONTEXT}}
+
+# CONTEXT
+
+Read the project's domain and architecture docs before changing code, if present:
+
+- `CONTEXT.md`, `CLAUDE.md`, or `README.md`
+- `docs/adr/` or similar architecture-decision records
+- Any coding standards file the repo points to
+
+Explore the repo and relevant tests before editing.
+
+# EXECUTION
+
+Where a test seam already exists, or a new one is being proposed, do red-green-refactor:
+
+1. RED: write a failing test
+2. GREEN: implement the smallest correct change
+3. REPEAT until the issue is done
+4. REFACTOR
+
+Do not improvise new test seams, such as extracting out a function so that it can be tested in isolation. This creates spaghetti tests.
+
+Run this project's standard build/test command before committing (check `package.json` scripts, a `Makefile`, `CONTRIBUTING.md`, or `CLAUDE.md` for what that is). Use focused tests where relevant.
+
+# COMMIT
+
+Make one or more commits on `{{BRANCH}}` with conventional commit messages.
+
+Do not push the branch.
+Do not close the issue.
+Do not edit labels.
+Do not create or edit PRs.
+
+When complete, output `<promise>COMPLETE</promise>`.

package/dist/workflows/prompts/review/extraction.md

@@ -0,0 +1,21 @@
+Emit a single `<output>` block as the last thing in your response.
+
+Do not change files.
+Do not run commands.
+Do not include text outside the `<output>` block.
+Do not wrap the `<output>` block in a markdown code fence (no ``` before or after it) — the JSON goes directly between the tags.
+
+<output>
+{
+  "summary": "1-3 paragraphs explaining your review, including what you changed or why it was already clean.",
+  "inlineComments": [
+    { "path": "relative/file.ts", "line": 123, "body": "Markdown comment" }
+  ],
+  "replies": [
+    { "threadId": "the \"id\" of a thread from review_threads in PR_COMMENTS_JSON", "body": "Markdown reply" }
+  ]
+}
+</output>
+
+Use empty arrays when there are no inline comments or replies.
+Even if there is nothing to change or add, still emit the full JSON object above with an empty summary-appropriate message — never reply with plain prose instead of the `<output>` block.

package/dist/workflows/prompts/review/prompt.md

@@ -0,0 +1,49 @@
+# TASK
+
+Review PR #{{PR_NUMBER}} on branch `{{BRANCH}}`.
+
+PR title: {{PR_TITLE}}
+Linked issue: #{{ISSUE_NUMBER}} {{ISSUE_TITLE}}
+
+You are an expert code reviewer. Your job is not just to comment. Actively improve the branch when a concrete improvement is warranted, then explain what you changed.
+
+# LINKED ISSUE
+
+{{LINKED_ISSUE}}
+
+# DIFF TO MAIN
+
+```diff
+{{DIFF_TO_MAIN}}
+```
+
+# PR COMMENTS
+
+```json
+{{PR_COMMENTS_JSON}}
+```
+
+# REVIEW PROCESS
+
+1. Read the diff carefully.
+2. Verify the PR satisfies the linked issue.
+3. Stress-test edge cases and add tests where useful.
+4. Improve clarity, maintainability, and consistency while preserving behavior.
+5. Respond to unresolved human review threads when useful:
+   - Address: change code and reply
+   - Decline: do not change code, reply with why
+   - Defer: no reply, only for stale/context-only comments
+
+Read this project's domain and architecture docs if present (`CONTEXT.md`, `CLAUDE.md`, `docs/adr/`, or similar).
+
+Run this project's standard build/test command before committing if you make changes (check `package.json` scripts, a `Makefile`, `CONTRIBUTING.md`, or `CLAUDE.md` for what that is). Use focused tests where relevant.
+
+If you make changes, commit them as a single conventional commit.
+If the code is already clean and there is nothing to answer, make no commit.
+
+Do not push.
+Do not edit labels.
+Do not mark review threads resolved.
+Do not create GitHub comments yourself.
+
+When complete, output `<promise>COMPLETE</promise>`.

package/dist/workflows/prompts/update-branch/extraction.md

@@ -0,0 +1,13 @@
+# EMIT STRUCTURED OUTPUT
+
+You have resolved the conflicts and committed the merge. **Do not make any further changes** — only report what you did.
+
+Emit a single block as the last thing in your response:
+
+<output>
+{
+  "comment": "Markdown body posted as a PR comment. Free-form prose. Describe which conflicts existed, how you resolved each, and flag any uncertainty or remaining problems (e.g. build failures, ambiguous intent). Reference commit SHAs or file paths where useful."
+}
+</output>
+
+The comment is the only safety net for the human author. Write it like you're handing the branch back to them and want them to be able to spot any bad call you made in 30 seconds.

package/dist/workflows/prompts/update-branch/prompt.md

@@ -0,0 +1,41 @@
+# TASK
+
+PR #{{PR_NUMBER}} (branch `{{BRANCH}}`) has merge conflicts against its base `{{BASE_REF}}`. A `git merge origin/{{BASE_REF}} --no-edit` has already been attempted and left the working tree in a conflicted state. Your job is to resolve every conflict, finish the merge, and write a PR comment describing what you did.
+
+# CONTEXT
+
+Read this project's domain and architecture docs if present (`CONTEXT.md`, `CLAUDE.md`, `docs/adr/`, or similar) before resolving anything substantive.
+
+<pr-view>
+
+!`gh pr view {{PR_NUMBER}}`
+
+</pr-view>
+
+<merge-status>
+
+!`git status`
+
+</merge-status>
+
+<conflicting-files>
+
+!`git diff --name-only --diff-filter=U`
+
+</conflicting-files>
+
+# RESOLUTION POLICY
+
+Always resolve. Do not abort the merge. Do not leave the branch in a half-finished state.
+
+For each conflicting hunk:
+
+1. **Investigate intent on both sides** before choosing a resolution. Use `git log -p --follow -- <path>` on both `origin/{{BASE_REF}}` and `{{BRANCH}}` to see how each side reached this state. Read the commit messages. If a commit references an issue, pull it with `gh issue view <n>`.
+2. **Pick the resolution that preserves both intents** wherever possible. Where the intents are incompatible, pick the one that best matches the PR's stated goal (in `<pr-view>` above) and note the trade-off in your comment.
+3. **Do not invent new behaviour.** Your job is reconciliation, not feature work. If a sensible resolution requires writing new logic that wasn't on either side, that's a signal to flag uncertainty rather than to be creative.
+
+After resolving, run this project's standard build/test command (check `package.json` scripts, a `Makefile`, `CONTRIBUTING.md`, or `CLAUDE.md` for what that is) — the repo-wide check is strongest; a narrower/focused check is fine if the resolution is localized. If something is broken, fix what you can; if you can't, push what you have and flag it clearly in the comment.
+
+# COMMIT
+
+Stage everything and finish the merge with a single commit. Conventional-commit style, e.g. `chore: merge origin/{{BASE_REF}} into {{BRANCH}}`. The wrapper will push whatever you commit.

package/dist/workflows/review.d.ts

@@ -0,0 +1,14 @@
+import type { Workflow } from "../core/workflow.js";
+import { type SandboxDefaults } from "./shared/sandcastle.js";
+export interface ReviewWorkflowOptions extends SandboxDefaults {
+    readonly id?: string;
+    readonly triggerLabel?: string;
+    readonly blockedLabel?: string;
+    readonly inProgressLabel?: string;
+    readonly promptFile?: string;
+    readonly extractionPrompt?: string;
+    readonly preflightCommand?: string;
+    readonly outputDir?: string;
+}
+export declare function createReviewWorkflow(options?: ReviewWorkflowOptions): Workflow;
+export declare const review: Workflow;

package/dist/workflows/review.js

@@ -0,0 +1,134 @@
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { defineWorkflow, Match, isChangeRequestKind, labelAdded } from "../core/workflow.js";
+import { git, pushBranch } from "./shared/git.js";
+import { createPodmanSandbox, runSandboxWithExtraction } from "./shared/sandcastle.js";
+import { fetchChangeRequestContext, filterInlineComments, filterReplies, validateReviewOutput } from "./shared/review-output.js";
+import { runWithAgentLifecycle } from "./shared/lifecycle.js";
+const here = dirname(fileURLToPath(import.meta.url));
+const defaultPromptFile = join(here, "prompts/review/prompt.md");
+const defaultExtractionPrompt = await import("node:fs").then(fs => fs.readFileSync(join(here, "prompts/review/extraction.md"), "utf8"));
+export function createReviewWorkflow(options = {}) {
+    const triggerLabel = options.triggerLabel ?? "agent:review";
+    const promptFile = options.promptFile ?? defaultPromptFile;
+    const extractionPrompt = options.extractionPrompt ?? defaultExtractionPrompt;
+    return defineWorkflow(options.id ?? "review", {
+        match: ({ event }) => {
+            if (!labelAdded(event, triggerLabel))
+                return Match.ignore();
+            if (!isChangeRequestKind(event.workTarget.kind))
+                return Match.ignore();
+            return Match.accept();
+        },
+        run: async ({ command, workReader, workTracker, codeReviewHost }) => runWithAgentLifecycle({ workTracker, target: command.workTarget, labels: { trigger: triggerLabel, blocked: options.blockedLabel, inProgress: options.inProgressLabel } }, async () => {
+            const env_1 = { stack: [], error: void 0, hasError: false };
+            try {
+                const target = command.workTarget;
+                const outputDir = options.outputDir ?? process.env.FORGEFLOW_OUTPUT_DIR ?? "/tmp/forgeflow-output";
+                const details = await codeReviewHost.getChangeRequestDetails(target);
+                if (details.isCrossRepository)
+                    throw new Error("Refused to run review on a cross-repository change request.");
+                const sandbox = __addDisposableResource(env_1, await createPodmanSandbox({
+                    ...options,
+                    branch: details.sourceBranch,
+                    preflightCommand: options.preflightCommand,
+                }), true);
+                await git(["fetch", "origin", details.targetBranch], { cwd: sandbox.worktreePath });
+                await git(["reset", "--hard", details.sourceSha], { cwd: sandbox.worktreePath });
+                const context = await fetchChangeRequestContext({ target, workReader, codeReviewHost, cwd: sandbox.worktreePath });
+                const result = await runSandboxWithExtraction({
+                    ...options,
+                    sandbox,
+                    name: `review-${target.kind}-${target.id}`,
+                    promptFile,
+                    extractionPrompt,
+                    validate: validateReviewOutput,
+                    promptArgs: {
+                        PR_NUMBER: target.id,
+                        BRANCH: details.sourceBranch,
+                        PR_TITLE: context.prTitle,
+                        ISSUE_NUMBER: context.issueNumber || "(none)",
+                        ISSUE_TITLE: context.issueTitle || "(no linked issue)",
+                        LINKED_ISSUE: context.linkedIssue,
+                        DIFF_TO_MAIN: context.diff,
+                        PR_COMMENTS_JSON: context.prCommentsJson,
+                    },
+                });
+                const validInlineComments = filterInlineComments(result.output.inlineComments, context.diffLines);
+                const validReplies = filterReplies(result.output.replies, context.validReplyIds);
+                const headSha = await git(["rev-parse", "HEAD"], { cwd: sandbox.worktreePath });
+                await pushBranch({ branch: details.sourceBranch, cwd: sandbox.worktreePath, forceWithLease: `refs/heads/${details.sourceBranch}:${details.sourceSha}` });
+                await codeReviewHost.postReview(target, { commitSha: headSha, summary: result.output.summary, inlineComments: validInlineComments });
+                for (const reply of validReplies) {
+                    await codeReviewHost.replyToThread(target, { threadId: reply.threadId, body: reply.body });
+                }
+                await codeReviewHost.markReady(target).catch(() => undefined);
+                await workTracker.addComment(target, `\`${triggerLabel}\` completed.`);
+                return { summary: result.output.summary, outputs: { commits: result.commits.length, inlineComments: validInlineComments.length, replies: validReplies.length, outputDir } };
+            }
+            catch (e_1) {
+                env_1.error = e_1;
+                env_1.hasError = true;
+            }
+            finally {
+                const result_1 = __disposeResources(env_1);
+                if (result_1)
+                    await result_1;
+            }
+        }),
+    });
+}
+export const review = createReviewWorkflow();
+//# sourceMappingURL=review.js.map

package/dist/workflows/review.js.map

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

package/dist/workflows/shared/git.d.ts

@@ -0,0 +1,17 @@
+export declare function git(args: string[], options?: {
+    cwd?: string;
+}): Promise<string>;
+export declare function configureBotGit(cwd?: string): Promise<void>;
+export declare function checkoutBaseBranch(input: {
+    baseRef: string;
+    cwd?: string;
+}): Promise<void>;
+export declare function commitsAhead(input: {
+    baseRef: string;
+    cwd?: string;
+}): Promise<number>;
+export declare function pushBranch(input: {
+    branch: string;
+    cwd?: string;
+    forceWithLease?: string;
+}): Promise<void>;

package/dist/workflows/shared/git.js

@@ -0,0 +1,28 @@
+import { runProcessOrThrow } from "../../process/index.js";
+export async function git(args, options = {}) {
+    const result = await runProcessOrThrow({ command: "git", args, cwd: options.cwd });
+    return result.stdout.trim();
+}
+export async function configureBotGit(cwd) {
+    await git(["config", "user.name", "forgeflow[bot]"], { cwd });
+    await git(["config", "user.email", "forgeflow[bot]@users.noreply.github.com"], { cwd });
+}
+export async function checkoutBaseBranch(input) {
+    await git(["fetch", "origin", `${input.baseRef}:${input.baseRef}`], { cwd: input.cwd }).catch(() => git(["fetch", "origin", input.baseRef], { cwd: input.cwd }));
+    await git(["checkout", input.baseRef], { cwd: input.cwd });
+    await git(["pull", "--ff-only", "origin", input.baseRef], { cwd: input.cwd });
+    await configureBotGit(input.cwd);
+}
+export async function commitsAhead(input) {
+    const count = await git(["rev-list", "--count", `${input.baseRef}..HEAD`], { cwd: input.cwd });
+    return Number(count.trim());
+}
+export async function pushBranch(input) {
+    if (input.forceWithLease) {
+        await git(["push", `--force-with-lease=${input.forceWithLease}`, "origin", input.branch], { cwd: input.cwd });
+    }
+    else {
+        await git(["push", "--force", "origin", input.branch], { cwd: input.cwd });
+    }
+}
+//# sourceMappingURL=git.js.map

package/dist/workflows/shared/git.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../../../src/workflows/shared/git.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAE1D,MAAM,CAAC,KAAK,UAAU,GAAG,CAAC,IAAc,EAAE,UAA4B,EAAE;IACtE,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAA;IAClF,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAA;AAC7B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,GAAY;IAChD,MAAM,GAAG,CAAC,CAAC,QAAQ,EAAE,WAAW,EAAE,gBAAgB,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,CAAA;IAC7D,MAAM,GAAG,CAAC,CAAC,QAAQ,EAAE,YAAY,EAAE,yCAAyC,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,CAAA;AACzF,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,KAAwC;IAC/E,MAAM,GAAG,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAA;IAChK,MAAM,GAAG,CAAC,CAAC,UAAU,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAA;IAC1D,MAAM,GAAG,CAAC,CAAC,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAA;IAC7E,MAAM,eAAe,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;AAClC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,KAAwC;IACzE,MAAM,KAAK,GAAG,MAAM,GAAG,CAAC,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,KAAK,CAAC,OAAO,QAAQ,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAA;IAC9F,OAAO,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAA;AAC7B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,KAAgE;IAC/F,IAAI,KAAK,CAAC,cAAc,EAAE,CAAC;QACzB,MAAM,GAAG,CAAC,CAAC,MAAM,EAAE,sBAAsB,KAAK,CAAC,cAAc,EAAE,EAAE,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAA;IAC/G,CAAC;SAAM,CAAC;QACN,MAAM,GAAG,CAAC,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAA;IAC5E,CAAC;AACH,CAAC"}

package/dist/workflows/shared/lifecycle.d.ts

@@ -0,0 +1,21 @@
+import type { WorkTracker } from "../../core/capabilities.js";
+import type { WorkTargetRef } from "../../core/types.js";
+import type { WorkflowRunResult } from "../../core/workflow.js";
+export interface AgentLifecycleLabels {
+    readonly trigger: string;
+    readonly blocked?: string;
+    readonly inProgress?: string;
+}
+/**
+ * Wraps a workflow body with the label/comment dance every agent workflow needs:
+ * clear the trigger + blocked labels, mark in-progress, run the body, and on
+ * failure add the blocked label back with a comment explaining how to retry.
+ * The body should simply throw on failure — this is the only place that turns
+ * an error into the blocked label + comment, so workflows can't double-report
+ * the same failure by also handling it themselves.
+ */
+export declare function runWithAgentLifecycle(input: {
+    workTracker: WorkTracker;
+    target: WorkTargetRef;
+    labels: AgentLifecycleLabels;
+}, body: () => Promise<WorkflowRunResult | void>): Promise<WorkflowRunResult | void>;

package/dist/workflows/shared/lifecycle.js

@@ -0,0 +1,29 @@
+/**
+ * Wraps a workflow body with the label/comment dance every agent workflow needs:
+ * clear the trigger + blocked labels, mark in-progress, run the body, and on
+ * failure add the blocked label back with a comment explaining how to retry.
+ * The body should simply throw on failure — this is the only place that turns
+ * an error into the blocked label + comment, so workflows can't double-report
+ * the same failure by also handling it themselves.
+ */
+export async function runWithAgentLifecycle(input, body) {
+    const { workTracker, target, labels } = input;
+    const blockedLabel = labels.blocked ?? "agent:blocked";
+    const inProgressLabel = labels.inProgress ?? "agent:in-progress";
+    await workTracker.removeLabel(target, labels.trigger).catch(() => undefined);
+    await workTracker.removeLabel(target, blockedLabel).catch(() => undefined);
+    await workTracker.addLabel(target, inProgressLabel);
+    try {
+        return await body();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        await workTracker.addLabel(target, blockedLabel).catch(() => undefined);
+        await workTracker.addComment(target, `\`${labels.trigger}\` run failed.\n\n**Reason:** ${message}\n\nRe-add \`${labels.trigger}\` or comment \`/agent retry\` to retry.`).catch(() => undefined);
+        throw error;
+    }
+    finally {
+        await workTracker.removeLabel(target, inProgressLabel).catch(() => undefined);
+    }
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/workflows/shared/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../../../src/workflows/shared/lifecycle.ts"],"names":[],"mappings":"AAUA;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,KAAwF,EACxF,IAA6C;IAE7C,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,KAAK,CAAA;IAC7C,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,IAAI,eAAe,CAAA;IACtD,MAAM,eAAe,GAAG,MAAM,CAAC,UAAU,IAAI,mBAAmB,CAAA;IAEhE,MAAM,WAAW,CAAC,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;IAC5E,MAAM,WAAW,CAAC,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;IAC1E,MAAM,WAAW,CAAC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;IAEnD,IAAI,CAAC;QACH,OAAO,MAAM,IAAI,EAAE,CAAA;IACrB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QACtE,MAAM,WAAW,CAAC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;QACvE,MAAM,WAAW,CAAC,UAAU,CAC1B,MAAM,EACN,KAAK,MAAM,CAAC,OAAO,iCAAiC,OAAO,gBAAgB,MAAM,CAAC,OAAO,0CAA0C,CACpI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;QACxB,MAAM,KAAK,CAAA;IACb,CAAC;YAAS,CAAC;QACT,MAAM,WAAW,CAAC,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;IAC/E,CAAC;AACH,CAAC"}