forge-workflow 0.0.9 → 0.1.0-beta.2

package/lib/plugin-catalog.js

@@ -27,7 +27,6 @@ const STAGES = Object.freeze({
   VALIDATE: 'validate',
   SHIP: 'ship',
   REVIEW: 'review',
-  PREMERGE: 'premerge',
 });
 
 const BUDGET_MODES = Object.freeze({
@@ -326,12 +325,12 @@ const CATALOG = Object.freeze({
     install: { method: 'config', cmd: 'Self-hosted (qodo.ai)' },
   },
 
-  // ── Merge ──
+  // ── Release automation (ship-time) ──
   changesets: {
     name: 'Changesets',
     type: 'cli',
     tier: 'free',
-    stage: 'premerge',
+    stage: 'ship',
     description: 'Versioning and changelog management',
     detectWhen: ['file:package.json'],
     install: { method: 'npm', cmd: 'bun add -D @changesets/cli', dev: true },
@@ -340,7 +339,7 @@ const CATALOG = Object.freeze({
     name: 'Release Please',
     type: 'config',
     tier: 'free',
-    stage: 'premerge',
+    stage: 'ship',
     description: 'Automated release PRs by Google',
     detectWhen: [],
     install: { method: 'config', cmd: 'GitHub Action (google-github-actions/release-please-action)' },

package/lib/plugin-manager.js

@@ -30,12 +30,7 @@ const DEFAULT_SUPPORT_STATUS = 'supported';
 const SURFACE_BY_AGENT_ID = Object.freeze({
   claude: 'cli-first',
   codex: 'cli-first',
-  opencode: 'cli-first',
-  cline: 'editor-native',
   cursor: 'editor-native',
-  copilot: 'editor-native',
-  kilocode: 'editor-native',
-  roo: 'editor-native',
 });
 
 function isPlainObject(value) {

package/lib/pr-bundle.js

@@ -0,0 +1,186 @@
+'use strict';
+
+/**
+ * PR-state bundle — the "everything ready for the agent" gather half of the
+ * monitor (kernel 9b24257f, increment 1).
+ *
+ * `gatherPrBundle` aggregates the COMPLETE, read-only state of an open PR into
+ * one structured object a fixer-agent can act on WITHOUT fetching anything
+ * itself: every unresolved review thread (any author), the merge state, the
+ * full CI rollup (tagged with required-check membership), branch divergence, and
+ * predicted merge conflicts.
+ *
+ * This module is pure aggregation over a validated pr-state adapter. It makes NO
+ * decisions and takes NO actions — it never merges, never resolves threads,
+ * never writes code. The decision state machine stays in lib/pr-shepherd.js; the
+ * agent dispatch, the continuous loop, and close-on-merge that will consume this
+ * bundle are follow-ups, not part of this increment.
+ *
+ * @module pr-bundle
+ */
+
+const { isGreen, isFailed } = require('./pr-shepherd');
+
+/**
+ * Map an unresolved review thread to the agent-input comment shape. The named
+ * `author`/`body` come from the thread opener (the canonical anchor), but the
+ * FULL `comments` array is carried too — so a later human reply on a
+ * bot-opened thread is never hidden from the fixer-agent (which fetches
+ * nothing and acts only on this input). Tolerates adapters/payloads that don't
+ * surface every field.
+ *
+ * @param {object} thread
+ * @returns {{ author: string, path: string|null, line: number|null, body: string, threadId: string|null, comments: {author: string, body: string}[] }}
+ */
+function toUnresolvedComment(thread) {
+  const comments = (Array.isArray(thread.comments) ? thread.comments : []).map((c) => ({
+    author: String((c.author && c.author.login) || c.author || ''),
+    body: String(c.body || ''),
+  }));
+  const first = comments[0] || {};
+  return {
+    author: first.author || String(thread.author || ''),
+    path: thread.path || null,
+    line: typeof thread.line === 'number' ? thread.line : null,
+    body: first.body || String(thread.body || ''),
+    threadId: thread.threadId || thread.id || null,
+    comments,
+  };
+}
+
+/**
+ * Read ALL unresolved review threads (any author) and map them to the agent
+ * comment shape.
+ *
+ * Returns `{ comments, available, error }` — NOT a bare array — so a consumer can
+ * tell three states apart that a `[]`-on-everything collapse would conflate:
+ *   - capability absent  → available:false, error:null  (adapter has no readComments)
+ *   - read succeeded      → available:true,  error:null  (comments is authoritative)
+ *   - read THREW          → available:false, error:msg   (comments unreadable — NOT "none")
+ *
+ * The third case is the critical one: a monitor must never treat "GitHub comments
+ * were unreadable" as "this PR has no unresolved feedback" and silently skip work.
+ * A failed read still degrades gracefully (the rest of the bundle survives), but
+ * the failure is surfaced rather than swallowed.
+ *
+ * @returns {Promise<{ comments: object[], available: boolean, error: string|null }>}
+ */
+async function gatherUnresolvedComments(adapter, { owner, repo, pr }) {
+  if (typeof adapter.readComments !== 'function') {
+    return { comments: [], available: false, error: null };
+  }
+  try {
+    const threads = await adapter.readComments({ owner, repo, pr });
+    const comments = (Array.isArray(threads) ? threads : [])
+      .filter((t) => !(t.isResolved || t.resolved))
+      .map(toUnresolvedComment);
+    return { comments, available: true, error: null };
+  } catch (err) {
+    // A failed comment read must not sink the rest of the bundle, but it MUST be
+    // distinguishable from "no unresolved threads" — preserve the error signal.
+    return { comments: [], available: false, error: err.message || 'comment read failed' };
+  }
+}
+
+/**
+ * Predict merge conflicts. `detectConflicts` is optional on the adapter; when
+ * absent or failing, report it as unsupported rather than throwing.
+ */
+async function gatherConflicts(adapter, { baseRef, cwd }) {
+  if (typeof adapter.detectConflicts !== 'function') {
+    return { supported: false, reason: 'adapter has no detectConflicts capability' };
+  }
+  try {
+    return await adapter.detectConflicts({ baseRef, cwd });
+  } catch (error) {
+    return { supported: false, reason: error.message || 'conflict detection failed' };
+  }
+}
+
+/**
+ * Tag the CI rollup with required-check membership and split out failing/pending.
+ *
+ * `requiredSet` is the branch-protection required set (array), or `null` when it
+ * is unreadable — in which case `required` is left `null` per check rather than
+ * `false`, so the agent is never told "nothing is required" on bad data.
+ *
+ * @param {object[]} checks - Normalized rollup from `readState`.
+ * @param {string[]|null} requiredSet
+ * @returns {{ checks: object[], failing: object[], pending: object[] }}
+ */
+function buildCi(checks, requiredSet) {
+  const isRequired = (name) => (requiredSet === null ? null : requiredSet.includes(name));
+  const tagged = (Array.isArray(checks) ? checks : []).map((c) => ({
+    name: c.name || '',
+    status: c.status || '',
+    conclusion: c.conclusion || '',
+    required: isRequired(c.name || ''),
+    detailsUrl: c.detailsUrl || null,
+  }));
+  return {
+    checks: tagged,
+    failing: tagged.filter((c) => isFailed(c)),
+    pending: tagged.filter((c) => !isGreen(c) && !isFailed(c)),
+  };
+}
+
+/**
+ * Gather the complete read-only PR-state bundle for the monitor's fixer-agent.
+ *
+ * @param {object} ctx
+ * @param {string} ctx.pr
+ * @param {string} ctx.owner
+ * @param {string} ctx.repo
+ * @param {string} ctx.base    - Base BRANCH name (for branch-protection lookup).
+ * @param {string} ctx.baseRef - Base REF for divergence/conflicts (e.g. `origin/master`).
+ * @param {string} [ctx.cwd]
+ * @param {object} ctx.adapter - A validated pr-state adapter.
+ * @returns {Promise<object>} the structured bundle.
+ */
+async function gatherPrBundle({ pr, owner, repo, base, baseRef, cwd, adapter }) {
+  if (!adapter || typeof adapter.readState !== 'function') {
+    throw new Error('gatherPrBundle requires a pr-state adapter with readState');
+  }
+
+  const state = await adapter.readState(pr);
+  // NOTE: required-check lookup needs the base BRANCH name (`base`), not the
+  // remote ref (`baseRef`); passing the ref builds a bad protection path and
+  // silently yields a null required set.
+  const requiredRaw = await adapter.readRequiredChecks({ owner, repo, base });
+  const divergence = await adapter.readDivergence({ baseRef, cwd });
+  const comments = await gatherUnresolvedComments(adapter, { owner, repo, pr });
+  const conflicts = await gatherConflicts(adapter, { baseRef, cwd });
+
+  const requiredSet = requiredRaw === undefined ? null : requiredRaw;
+
+  return {
+    pr: String(pr),
+    owner,
+    repo,
+    base,
+    baseRef,
+    unresolvedComments: comments.comments,
+    // Availability signal for the comment read: when false with a non-null error,
+    // the threads were UNREADABLE (not absent) — a monitor must not treat the empty
+    // unresolvedComments list as "no feedback" and skip work.
+    unresolvedCommentsAvailable: comments.available,
+    unresolvedCommentsError: comments.error,
+    mergeState: {
+      mergeable: state.mergeable || 'UNKNOWN',
+      mergeStateStatus: state.mergeStateStatus || 'UNKNOWN',
+      state: String(state.state || 'OPEN').toUpperCase(),
+    },
+    ci: buildCi(state.checks, requiredSet),
+    branch: {
+      ahead: divergence.ahead || 0,
+      behind: divergence.behind || 0,
+    },
+    conflicts,
+  };
+}
+
+module.exports = {
+  gatherPrBundle,
+  buildCi,
+  toUnresolvedComment,
+};

package/lib/pr-monitor/differ.js

@@ -0,0 +1,195 @@
+'use strict';
+
+/**
+ * PR-monitor differ — the PURE heart of the monitor. `diffSnapshots(prev, next)`
+ * returns the ordered candidate events for the transition between two normalized
+ * snapshots (see lib/pr-monitor/gather.js for the shape). No I/O, no clock, no
+ * randomness — same inputs always yield the same events, which is what makes the
+ * monitor deterministic and duplicate-free across restarts.
+ *
+ * Each event carries a CONTENT key (head sha, threadId, check name+sha, comment
+ * id, review author+commit, surface) so the journal can dedup by identity.
+ *
+ * @module pr-monitor/differ
+ */
+
+const { EVENT_TYPES: T, makeEvent } = require('./events');
+
+/** Index an array of objects by a key field into a Map. */
+function indexBy(list, field) {
+  const map = new Map();
+  for (const item of (Array.isArray(list) ? list : [])) {
+    if (item?.[field] != null) map.set(String(item[field]), item);
+  }
+  return map;
+}
+
+/** True when every check is green (none failed, none pending). */
+function allGreen(checks) {
+  const list = Array.isArray(checks) ? checks : [];
+  return list.length > 0 && list.every((c) => c.class === 'green');
+}
+
+/** head.pushed — the PR's head sha advanced. */
+function diffHead(prev, next, out) {
+  if (next.headSha && prev.headSha !== next.headSha) {
+    out.push(makeEvent(T.HEAD_PUSHED, next.headSha, { from: prev.headSha || null, to: next.headSha }));
+  }
+}
+
+/** check.failed / check.recovered / checks.green — keyed by name+sha. */
+function diffChecks(prev, next, out) {
+  const prevByName = indexBy(prev.checks, 'name');
+  for (const c of (next.checks || [])) {
+    const before = prevByName.get(String(c.name));
+    const wasFailed = before?.class === 'failed';
+    if (c.class === 'failed' && !wasFailed) {
+      out.push(makeEvent(T.CHECK_FAILED, `${c.name}:${next.headSha}`, { name: c.name }));
+    } else if (c.class === 'green' && wasFailed) {
+      out.push(makeEvent(T.CHECK_RECOVERED, `${c.name}:${next.headSha}`, { name: c.name }));
+    }
+  }
+  if (allGreen(next.checks) && !allGreen(prev.checks)) {
+    out.push(makeEvent(T.CHECKS_GREEN, next.headSha, {}));
+  }
+}
+
+/** thread.opened / thread.reply / thread.resolved — keyed by threadId. */
+function diffThreads(prev, next, out) {
+  const prevById = indexBy(prev.threads, 'threadId');
+  for (const t of (next.threads || [])) {
+    const before = prevById.get(String(t.threadId));
+    if (!before) {
+      if (t.actionable) out.push(makeEvent(T.THREAD_OPENED, t.threadId, { path: t.path || null }));
+      continue;
+    }
+    if ((t.commentCount || 0) > (before.commentCount || 0)) {
+      out.push(makeEvent(T.THREAD_REPLY, `${t.threadId}:${t.commentCount}`, { threadId: t.threadId }));
+    }
+    if (t.isResolved && !before.isResolved) {
+      out.push(makeEvent(T.THREAD_RESOLVED, t.threadId, {}));
+    }
+  }
+}
+
+/** comment.posted — a new direct PR issue comment, keyed by comment id. */
+function diffComments(prev, next, out) {
+  const prevIds = indexBy(prev.comments, 'id');
+  for (const c of (next.comments || [])) {
+    if (!prevIds.has(String(c.id))) {
+      out.push(makeEvent(T.COMMENT_POSTED, c.id, { author: c.author || '' }));
+    }
+  }
+}
+
+/** review.submitted — a new/updated review per author (state or commit changed). */
+function diffReviews(prev, next, out) {
+  const prevByAuthor = indexBy(prev.reviews, 'author');
+  for (const r of (next.reviews || [])) {
+    const before = prevByAuthor.get(String(r.author));
+    const changed = !before
+      || before.submittedAt !== r.submittedAt
+      || before.commitOid !== r.commitOid;
+    if (changed) {
+      out.push(makeEvent(T.REVIEW_SUBMITTED, `${r.author}:${r.commitOid || r.submittedAt}`, {
+        author: r.author, verdict: r.state, commitOid: r.commitOid || null,
+      }));
+    }
+  }
+}
+
+/** conflict.appeared / conflict.cleared — keyed by head sha. */
+function diffConflict(prev, next, out) {
+  if (next.conflicts === true && prev.conflicts !== true) {
+    out.push(makeEvent(T.CONFLICT_APPEARED, next.headSha, {}));
+  } else if (next.conflicts === false && prev.conflicts === true) {
+    out.push(makeEvent(T.CONFLICT_CLEARED, next.headSha, {}));
+  }
+}
+
+/** branch.behind — the branch fell behind its base. */
+function diffBehind(prev, next, out) {
+  if ((next.behind || 0) > 0 && (prev.behind || 0) === 0) {
+    out.push(makeEvent(T.BRANCH_BEHIND, `${next.headSha}:${next.behind}`, { behind: next.behind }));
+  }
+}
+
+/** verdict.changed — the fail-closed merge verdict flipped. */
+function diffVerdict(prev, next, out) {
+  const from = prev.verdict ? prev.verdict.state : null;
+  const to = next.verdict ? next.verdict.state : null;
+  if (from !== to) {
+    out.push(makeEvent(T.VERDICT_CHANGED, `${from}->${to}:${next.headSha}`, {
+      from, to, reason: next.verdict ? next.verdict.reason || null : null,
+    }));
+  }
+}
+
+/** pr.merged / pr.closed — terminal transitions from an OPEN PR. */
+function diffPrState(prev, next, out) {
+  if (prev.prState === 'OPEN' && next.prState === 'MERGED') {
+    out.push(makeEvent(T.PR_MERGED, 'MERGED', {}));
+  } else if (prev.prState === 'OPEN' && next.prState === 'CLOSED') {
+    out.push(makeEvent(T.PR_CLOSED, 'CLOSED', {}));
+  }
+}
+
+/** monitor.degraded — a read surface newly became unreadable (fail-closed). */
+function diffDegraded(prev, next, out) {
+  const prevSurfaces = new Set((prev.degraded || []).map((d) => d.surface));
+  for (const d of (next.degraded || [])) {
+    if (!prevSurfaces.has(d.surface)) {
+      out.push(makeEvent(T.MONITOR_DEGRADED, d.surface, { surface: d.surface, error: d.error || '' }));
+    }
+  }
+}
+
+/**
+ * Baseline events for the FIRST pass (no prior snapshot): a single verdict
+ * baseline plus any already-terminal/degraded state — bounded, never a replay of
+ * every historical thread/check.
+ */
+function diffBaseline(next, out) {
+  out.push(makeEvent(T.VERDICT_CHANGED, `baseline:${next.headSha}`, {
+    from: null, to: next.verdict ? next.verdict.state : null,
+    reason: next.verdict ? next.verdict.reason || null : null,
+  }));
+  if (next.prState === 'MERGED') out.push(makeEvent(T.PR_MERGED, 'MERGED', {}));
+  if (next.prState === 'CLOSED') out.push(makeEvent(T.PR_CLOSED, 'CLOSED', {}));
+  for (const d of (next.degraded || [])) {
+    out.push(makeEvent(T.MONITOR_DEGRADED, d.surface, { surface: d.surface, error: d.error || '' }));
+  }
+}
+
+/**
+ * Diff two normalized snapshots into ordered candidate events. `prev === null`
+ * → first-pass baseline.
+ *
+ * @param {object|null} prev
+ * @param {object} next
+ * @returns {Array<{ type: string, key: string, data: object }>}
+ */
+function diffSnapshots(prev, next) {
+  const out = [];
+  if (!prev) {
+    diffBaseline(next, out);
+    return out;
+  }
+  diffHead(prev, next, out);
+  diffChecks(prev, next, out);
+  diffThreads(prev, next, out);
+  diffComments(prev, next, out);
+  diffReviews(prev, next, out);
+  diffConflict(prev, next, out);
+  diffBehind(prev, next, out);
+  diffVerdict(prev, next, out);
+  diffPrState(prev, next, out);
+  diffDegraded(prev, next, out);
+  return out;
+}
+
+module.exports = {
+  diffSnapshots,
+  allGreen,
+  indexBy,
+};

package/lib/pr-monitor/gather.js

@@ -0,0 +1,124 @@
+'use strict';
+
+/**
+ * PR-monitor gather — turn ONE `gatherPrSnapshot` read (the SAME shared read the
+ * `--pull` verdict uses) into the normalized snapshot the differ compares. Because
+ * the verdict and the monitor events both derive from this one read, they can
+ * never disagree (the frame in docs/work/2026-07-13-pr-monitor/plan.md).
+ *
+ * The normalized snapshot is the diff subject:
+ *   { repo, pr, headSha, prState, draft, verdict:{state,reason},
+ *     checks:[{name,class}], threads:[{threadId,isResolved,isOutdated,commentCount,actionable,path}],
+ *     reviews:[{author,state,commitOid,submittedAt}], comments:[{id,author}],
+ *     behind, conflicts:(true|false|null), degraded:[{surface,error}] }
+ *
+ * @module pr-monitor/gather
+ */
+
+const { gatherPrSnapshot } = require('../pr-pull');
+const { isFailed, isGreen } = require('../pr-shepherd');
+
+/** green | failed | pending — reuses the SAME predicates as the verdict core. */
+function classifyCheck(check) {
+  if (isFailed(check)) return 'failed';
+  if (isGreen(check)) return 'green';
+  return 'pending';
+}
+
+function normalizeChecks(checks) {
+  return (Array.isArray(checks) ? checks : []).map((c) => ({
+    name: c.name || '',
+    class: classifyCheck(c),
+  }));
+}
+
+function normalizeThreads(threads) {
+  return (Array.isArray(threads) ? threads : []).map((t) => ({
+    threadId: t.threadId || '',
+    isResolved: Boolean(t.isResolved),
+    isOutdated: Boolean(t.isOutdated),
+    commentCount: Array.isArray(t.comments) ? t.comments.length : 0,
+    actionable: !t.isResolved && !t.isOutdated,
+    path: t.path || null,
+  }));
+}
+
+function normalizeReviews(reviews) {
+  return (Array.isArray(reviews) ? reviews : []).map((r) => ({
+    author: r.author || '',
+    state: r.state || '',
+    commitOid: r.commitOid || null,
+    submittedAt: r.submittedAt || null,
+  }));
+}
+
+function normalizeComments(comments) {
+  return (Array.isArray(comments) ? comments : []).map((c) => ({
+    id: c.id || `${c.author || ''}:${c.createdAt || ''}`,
+    author: c.author || '',
+  }));
+}
+
+function normalizeDegraded(degraded) {
+  return (Array.isArray(degraded) ? degraded : []).map((d) => ({
+    surface: d.source || d.surface || 'unknown',
+    error: d.error || '',
+  }));
+}
+
+/**
+ * Conflict prediction → tri-state boolean: `true`/`false` when supported,
+ * `null` when unknown (unsupported git, unreadable ref) so the differ never
+ * emits a false conflict.appeared/cleared on missing data.
+ */
+function conflictBool(conflicts) {
+  if (conflicts?.supported === true) return Boolean(conflicts.conflicted);
+  return null;
+}
+
+/**
+ * Normalize a raw `gatherPrSnapshot` result into the monitor diff subject.
+ *
+ * @param {object} snap - gatherPrSnapshot result.
+ * @param {{ repo: string, pr: string|number }} ctx
+ * @returns {object}
+ */
+function normalizeSnapshot(snap, ctx) {
+  const state = snap.state || {};
+  return {
+    repo: ctx.repo,
+    pr: String(ctx.pr),
+    headSha: state.headSha || '',
+    prState: String(state.state || 'OPEN').toUpperCase(),
+    draft: Boolean(snap.draft),
+    verdict: { state: snap.verdict || 'UNKNOWN', reason: null },
+    checks: normalizeChecks(state.checks),
+    threads: normalizeThreads(snap.threads),
+    reviews: normalizeReviews(snap.reviews),
+    comments: normalizeComments(snap.issueComments),
+    behind: snap.behind || 0,
+    conflicts: conflictBool(snap.conflicts),
+    degraded: normalizeDegraded(snap.degraded),
+  };
+}
+
+/**
+ * Gather + normalize the monitor snapshot for a PR. `ctx.gatherSnapshot` is
+ * injectable for tests; production uses the shared `gatherPrSnapshot`.
+ *
+ * @param {object} ctx - the same ctx shape gatherPrSnapshot takes (pr, owner,
+ *   repo, base, baseRef, cwd, self, adapter, now, settleWindowMs).
+ * @returns {Promise<object>} normalized snapshot.
+ */
+async function gatherMonitorSnapshot(ctx) {
+  const gather = ctx.gatherSnapshot || gatherPrSnapshot;
+  const snap = await gather(ctx);
+  return normalizeSnapshot(snap, ctx);
+}
+
+module.exports = {
+  gatherMonitorSnapshot,
+  normalizeSnapshot,
+  classifyCheck,
+  conflictBool,
+};