mandrel 1.57.0

package/.agents/scripts/providers/github/board-add.js

@@ -0,0 +1,63 @@
+/**
+ * GitHub Provider — shared "add issue to the Projects V2 board" helper.
+ *
+ * Story #3822 — single source of truth for the post-create board-add
+ * step. Issues created through any create path (`createTicket`,
+ * `createIssue` — which backs `/story-plan` persist and the `/epic-plan`
+ * Phase 4 Epic open) must land on the configured Projects V2 board
+ * without relying on GitHub's "Auto-add to project" built-in workflow,
+ * which is off by default on fresh boards and cannot be enabled via API.
+ *
+ * Contract:
+ *   - **No-op when no project number resolves** — returns
+ *     `{ added: false, reason: 'no-project-number' }` without touching
+ *     the network.
+ *   - **Non-fatal** — a failed add warns and returns
+ *     `{ added: false, reason: 'error' }`; it never throws, so issue
+ *     creation always survives a board hiccup.
+ *   - **Idempotent** — the underlying `addProjectV2ItemById` mutation
+ *     returns the existing item when the issue is already on the board,
+ *     so re-running the helper is safe.
+ */
+
+import { Logger } from '../../lib/Logger.js';
+
+/**
+ * Add an issue (by GraphQL `node_id`) to the configured Projects V2
+ * board.
+ *
+ * @param {{
+ *   nodeId: string|null|undefined,
+ *   issueNumber?: number|null,
+ *   getProjectNumber?: () => number|null,
+ *   addItemToProject?: (nodeId: string) => Promise<unknown>,
+ * }} opts
+ * @returns {Promise<{ added: boolean, reason?: string }>}
+ */
+export async function addIssueToBoard({
+  nodeId,
+  issueNumber = null,
+  getProjectNumber,
+  addItemToProject,
+}) {
+  const projectNumber =
+    typeof getProjectNumber === 'function' ? getProjectNumber() : null;
+  if (!projectNumber) return { added: false, reason: 'no-project-number' };
+  if (typeof addItemToProject !== 'function') {
+    return { added: false, reason: 'no-add-hook' };
+  }
+  if (!nodeId) return { added: false, reason: 'no-node-id' };
+  try {
+    await addItemToProject(nodeId);
+    return { added: true };
+  } catch (err) {
+    const label =
+      issueNumber !== null && issueNumber !== undefined
+        ? `Issue #${issueNumber}`
+        : `issue ${nodeId}`;
+    Logger.warn(
+      `[GitHubProvider] Failed to add ${label} to project: ${err.message}`,
+    );
+    return { added: false, reason: 'error' };
+  }
+}

package/.agents/scripts/providers/github/branch-protection.js

@@ -0,0 +1,186 @@
+/**
+ * GitHub Provider — BranchProtectionGateway.
+ *
+ * Owns `getBranchProtection` / `setBranchProtection` against
+ * `/repos/{owner}/{repo}/branches/{branch}/protection`. Also exports the
+ * shared `isNotFoundError` predicate that `branchExists` reuses on the
+ * parent provider — keeping the 404-classification logic single-sourced.
+ *
+ * Extracted from `../github.js` in Story #2462 / Task #2478. Public
+ * surface on `GitHubProvider` is unchanged — both branch-protection
+ * methods delegate here.
+ *
+ * @see Story #2462 — Split GitHubProvider god class into seven composed gateways.
+ */
+
+import { parseApiJson } from './request-helpers.js';
+import { withTransientRetry } from './transient-retry.js';
+
+/**
+ * Detect a 404 across both error surfaces:
+ *
+ *   - `gh-exec`-classified errors land as `GhNotFoundError`
+ *     (`err.name === 'GhNotFoundError'`); the underlying stderr may carry
+ *     "HTTP 404" / "not found" / "Resource not accessible".
+ *   - The legacy `GithubHttpClient` produced `Error('... failed (404): ...')`
+ *     strings; some tests still throw those (and submodules that still
+ *     delegate to the old transport do too).
+ *
+ * Used by `getBranchProtection` (distinguishes "no rule exists" from
+ * transport failures) and `branchExists` on the parent provider.
+ */
+export function isNotFoundError(err) {
+  if (!err) return false;
+  if (err.name === 'GhNotFoundError') return true;
+  const message = err?.message ?? '';
+  const stderr = err?.stderr ?? '';
+  return (
+    /failed \(404\)/.test(message) ||
+    /HTTP 404/i.test(stderr) ||
+    /HTTP 404/i.test(message) ||
+    /\bnot found\b/i.test(stderr) ||
+    // gh-exec carries the failing code on err.code for the test mock path.
+    err?.code === 404
+  );
+}
+
+export class BranchProtectionGateway {
+  /**
+   * @param {{ gh: object, owner: string, repo: string }} deps
+   */
+  constructor({ gh, owner, repo } = {}) {
+    this._gh = gh;
+    this.owner = owner;
+    this.repo = repo;
+  }
+
+  /**
+   * Inspect branch-protection state. A 404 means "no protection rule
+   * exists"; any other error propagates so the caller can distinguish
+   * "intentionally unprotected" from "transport failure."
+   *
+   * @field-manifest GET /repos/{owner}/{repo}/branches/{branch}/protection:
+   *                 required_status_checks, enforce_admins,
+   *                 required_pull_request_reviews, restrictions
+   */
+  async getBranchProtection(branch) {
+    const endpoint = `/repos/${this.owner}/${this.repo}/branches/${encodeURIComponent(branch)}/protection`;
+    try {
+      const result = await withTransientRetry(() =>
+        this._gh.api({ method: 'GET', endpoint }),
+      );
+      const raw = parseApiJson(result) ?? {};
+      return { enabled: true, raw };
+    } catch (err) {
+      if (isNotFoundError(err)) return { enabled: false };
+      throw err;
+    }
+  }
+
+  /**
+   * Set (create or merge) branch protection on `branch`. Additive on the
+   * required-status-check `contexts` list (preserves operator-added
+   * contexts), and honours optional behaviour-shifting overrides
+   * (`enforceAdmins`, `requiredApprovingReviewCount`) so the consumer-
+   * facing bootstrap can promote the framework's hands-off-pipeline
+   * stance without silently flipping operator-tuned values.
+   *
+   * Returns `{ created, added, existing }`.
+   *
+   * @field-manifest PUT /repos/{owner}/{repo}/branches/{branch}/protection:
+   *                 required_status_checks, enforce_admins,
+   *                 required_pull_request_reviews, restrictions
+   *
+   * @param {string} branch
+   * @param {{
+   *   contexts: string[],
+   *   strict?: boolean,
+   *   enforceAdmins?: boolean,
+   *   requiredApprovingReviewCount?: number,
+   * }} opts
+   */
+  async setBranchProtection(branch, opts) {
+    const contexts = Array.isArray(opts?.contexts) ? opts.contexts : [];
+    const strict = opts?.strict !== false;
+    const endpoint = `/repos/${this.owner}/${this.repo}/branches/${encodeURIComponent(branch)}/protection`;
+
+    const current = await this.getBranchProtection(branch);
+    const existingContexts = current.enabled
+      ? (current.raw?.required_status_checks?.contexts ?? [])
+      : [];
+
+    // Additive merge: keep every context the operator already configured
+    // and append only those the prGate suite contributes that are not yet
+    // present.
+    const merged = [...existingContexts];
+    const added = [];
+    for (const ctx of contexts) {
+      if (!merged.includes(ctx)) {
+        merged.push(ctx);
+        added.push(ctx);
+      }
+    }
+
+    // Decide whether to override behaviour-shifting fields. Explicit
+    // `undefined` from legacy callers falls through to the operator's
+    // existing values (or the create-from-scratch defaults).
+    const overrideEnforceAdmins = typeof opts?.enforceAdmins === 'boolean';
+    const overrideApprovalCount =
+      typeof opts?.requiredApprovingReviewCount === 'number';
+
+    let enforceAdmins;
+    if (overrideEnforceAdmins) {
+      enforceAdmins = opts.enforceAdmins;
+    } else if (current.enabled) {
+      enforceAdmins = current.raw?.enforce_admins?.enabled ?? false;
+    } else {
+      enforceAdmins = false;
+    }
+
+    let prReviews;
+    if (overrideApprovalCount) {
+      // Preserve operator-set review flags (dismiss-stale, code-owners,
+      // etc.) — only the count is promoted.
+      const baseReviews = current.enabled
+        ? (current.raw?.required_pull_request_reviews ?? {})
+        : {};
+      prReviews = {
+        ...baseReviews,
+        required_approving_review_count: opts.requiredApprovingReviewCount,
+      };
+    } else {
+      prReviews = current.enabled
+        ? (current.raw?.required_pull_request_reviews ?? null)
+        : null;
+    }
+
+    // PUT requires every top-level field in the body — null disables a
+    // section.
+    const body = current.enabled
+      ? {
+          required_status_checks: {
+            strict: current.raw?.required_status_checks?.strict ?? strict,
+            contexts: merged,
+          },
+          enforce_admins: enforceAdmins,
+          required_pull_request_reviews: prReviews,
+          restrictions: current.raw?.restrictions ?? null,
+        }
+      : {
+          required_status_checks: { strict, contexts: merged },
+          enforce_admins: enforceAdmins,
+          required_pull_request_reviews: prReviews,
+          restrictions: null,
+        };
+
+    await withTransientRetry(() =>
+      this._gh.api({ method: 'PUT', endpoint, body }),
+    );
+
+    return {
+      created: !current.enabled,
+      added,
+      existing: existingContexts,
+    };
+  }
+}

package/.agents/scripts/providers/github/cache.js

@@ -0,0 +1,72 @@
+/**
+ * GitHub Provider — per-instance ticket cache.
+ *
+ * One bare `Map<id, { ticket, insertedAt }>` scoped to the lifetime of a
+ * single `GitHubProvider`, shared by dispatcher, reconciler, and cascade.
+ * The outer TTL wrapper is deliberately omitted because `peekFresh` already
+ * bounds entries by a caller-supplied `maxAgeMs`, and every other reader
+ * trusts the ticket mutators (`updateTicket` / `postComment` /
+ * `addSubIssue` / `removeSubIssue`) to call `invalidate` explicitly.
+ *
+ * Surface is intentionally narrow: only the methods the provider itself
+ * reaches for live here (`has` / `peek` / `peekFresh` / `set` /
+ * `primeIfAbsent` / `primeMany` / `invalidate`).
+ *
+ * Extracted from `../github.js` in Story #1846 / Task #1858.
+ *
+ * @param {{ now?: () => number }} [opts]
+ * @returns {{
+ *   has(ticketId: number): boolean,
+ *   peek(ticketId: number): object|undefined,
+ *   peekFresh(ticketId: number, maxAgeMs: number): object|undefined,
+ *   set(ticketId: number, ticket: object): void,
+ *   primeIfAbsent(ticket: object): void,
+ *   primeMany(tickets: Array<object>): void,
+ *   invalidate(ticketId: number): void,
+ * }}
+ */
+export function createInlineTicketCache({ now = Date.now } = {}) {
+  /** @type {Map<number, { ticket: object, insertedAt: number }>} */
+  const store = new Map();
+
+  function primeIfAbsent(ticket) {
+    if (!ticket || typeof ticket.id !== 'number') return;
+    if (store.has(ticket.id)) return;
+    if (!ticket.labelSet && Array.isArray(ticket.labels)) {
+      ticket.labelSet = new Set(ticket.labels);
+    }
+    store.set(ticket.id, { ticket, insertedAt: now() });
+  }
+
+  return {
+    has(ticketId) {
+      return store.has(ticketId);
+    },
+
+    peek(ticketId) {
+      return store.get(ticketId)?.ticket;
+    },
+
+    peekFresh(ticketId, maxAgeMs) {
+      const entry = store.get(ticketId);
+      if (!entry) return undefined;
+      if (!Number.isFinite(maxAgeMs) || maxAgeMs < 0) return undefined;
+      if (now() - entry.insertedAt >= maxAgeMs) return undefined;
+      return entry.ticket;
+    },
+
+    set(ticketId, ticket) {
+      store.set(ticketId, { ticket, insertedAt: now() });
+    },
+
+    primeIfAbsent,
+
+    primeMany(tickets) {
+      for (const t of tickets ?? []) primeIfAbsent(t);
+    },
+
+    invalidate(ticketId) {
+      store.delete(ticketId);
+    },
+  };
+}

package/.agents/scripts/providers/github/comments.js

@@ -0,0 +1,131 @@
+/**
+ * GitHub Provider — CommentGateway.
+ *
+ * Owns issue-comment CRUD against `/repos/{owner}/{repo}/issues/.../comments`.
+ * `postComment` is the structured-comment writer (it prepends the visible
+ * type-badge); the `<!-- ap:structured-comment ... -->` marker is added by
+ * the upstream `upsertStructuredComment` ticketing helper before the body
+ * lands here.
+ *
+ * Extracted from `../github.js` in Story #2462 / Task #2480. Public
+ * surface on `GitHubProvider` is unchanged — `postComment`,
+ * `getRecentComments`, `getTicketComments`, and `deleteComment` all
+ * delegate here.
+ *
+ * @see Story #2462 — Split GitHubProvider god class into seven composed gateways.
+ */
+
+import { withTransientRetry } from './errors.js';
+import {
+  defaultRetryWarn,
+  paginateRest,
+  parseApiJson,
+} from './request-helpers.js';
+
+// Structured-comment badge — preserved verbatim from the legacy
+// `./github/comments.js`. The upstream `upsertStructuredComment` ticketing
+// helper prepends the `<!-- ap:structured-comment ... -->` marker before
+// the body reaches `postComment`; this badge is the visible header
+// consumers (Slack notifier, dashboard) grep for. Keeping the emoji + bold
+// marker stable is what makes the round-trip with structured-comment
+// detection work across the rewrite.
+const TYPE_BADGES = {
+  progress: '🔄 **Progress**',
+  friction: '⚠️ **Friction**',
+  notification: '📢 **Notification**',
+};
+
+export class CommentGateway {
+  /**
+   * @param {{
+   *   gh: object,
+   *   owner: string,
+   *   repo: string,
+   *   hooks?: { invalidateTicket?: (id: number) => void },
+   * }} deps
+   */
+  constructor({ gh, owner, repo, hooks = {} } = {}) {
+    this._gh = gh;
+    this.owner = owner;
+    this.repo = repo;
+    this._hooks = hooks;
+  }
+
+  /**
+   * Recent comments across all issues in the repo (sorted newest first).
+   *
+   * @field-manifest /repos/{owner}/{repo}/issues/comments?sort=created:
+   *                 id, body, created_at, user, issue_url
+   */
+  async getRecentComments(limit = 100) {
+    const result = await withTransientRetry(
+      () =>
+        this._gh.api({
+          method: 'GET',
+          endpoint: `/repos/${this.owner}/${this.repo}/issues/comments?sort=created&direction=desc&per_page=${limit}`,
+        }),
+      { label: 'getRecentComments', onRetry: defaultRetryWarn },
+    );
+    return parseApiJson(result) ?? [];
+  }
+
+  /**
+   * All comments on a single ticket. Used by the upstream
+   * `findStructuredComment` ticketing helper, which greps each comment
+   * body for the `<!-- ap:structured-comment type="..." -->` marker — so
+   * the per-comment `body` field must round-trip verbatim.
+   *
+   * @field-manifest /repos/{owner}/{repo}/issues/{n}/comments:
+   *                 id, body, created_at, user
+   */
+  async getTicketComments(ticketId) {
+    return paginateRest(
+      this._gh,
+      `/repos/${this.owner}/${this.repo}/issues/${ticketId}/comments`,
+    );
+  }
+
+  /**
+   * Delete a comment by id. Called by `upsertStructuredComment` before
+   * posting the replacement, so the in-place semantics hold even though
+   * the underlying GitHub API has no native upsert.
+   */
+  async deleteComment(commentId) {
+    await this._gh.api({
+      method: 'DELETE',
+      endpoint: `/repos/${this.owner}/${this.repo}/issues/comments/${commentId}`,
+    });
+  }
+
+  /**
+   * Post a comment on an issue. When `payload.type` matches a known
+   * structured-comment kind, prepend the visible type-badge so operators
+   * see the same header the old client produced.
+   *
+   * Accepts either `{ body, type }` (canonical) or a bare string (legacy
+   * shape exercised by `tests/lib/github-provider.test.js` and a handful
+   * of direct callers under `notify.js`).
+   *
+   * @field-manifest POST /repos/{owner}/{repo}/issues/{n}/comments:
+   *                 id (returned for the caller's `commentId`)
+   */
+  async postComment(ticketId, payload) {
+    const normalized =
+      typeof payload === 'string' ? { body: payload } : (payload ?? {});
+    const badge = TYPE_BADGES[normalized.type] ?? '';
+    const body = badge ? `${badge}\n\n${normalized.body}` : normalized.body;
+
+    const result = await this._gh.api({
+      method: 'POST',
+      endpoint: `/repos/${this.owner}/${this.repo}/issues/${ticketId}/comments`,
+      body: { body },
+    });
+    const comment = parseApiJson(result);
+    // Posting a comment mutates the ticket's comment thread. Invalidate so
+    // the next `getTicketComments` / `getTicket` reflects the new comment.
+    if (typeof this._hooks.invalidateTicket === 'function') {
+      this._hooks.invalidateTicket(ticketId);
+    }
+    return { commentId: comment.id };
+  }
+}

package/.agents/scripts/providers/github/compose.js

@@ -0,0 +1,111 @@
+/**
+ * GitHub Provider — gateway composition helper.
+ *
+ * Pulled out of `../github.js` in Story #2462 / Task #2481 so the parent
+ * file can stay under the thin-composer LOC ceiling. This module owns the
+ * mechanical wiring: it builds each gateway, threads the hooks that
+ * cross-link them, and constructs the shared `_ctx` object the projects-v2
+ * shim reads from.
+ *
+ * The provider holds the public surface; this helper holds the wiring.
+ * Splitting the two keeps the composer file readable and reviewable as a
+ * delegation manifest rather than a constructor-shaped wall of new-up
+ * calls.
+ *
+ * @see Story #2462 — Split GitHubProvider god class into seven composed gateways.
+ */
+
+import { BranchProtectionGateway } from './branch-protection.js';
+import { CommentGateway } from './comments.js';
+import { classifyGithubError } from './errors.js';
+import { IssuesGateway } from './issues.js';
+import { LabelGateway } from './labels.js';
+import { MergeMethodsGateway } from './merge-methods.js';
+import { ProjectBoardGateway } from './project-board.js';
+import * as projects from './projects-v2-graphql.js';
+import { PullRequestGateway } from './prs.js';
+import { SubIssueGateway } from './sub-issues.js';
+import { TicketGateway } from './tickets.js';
+
+/**
+ * Wire every gateway onto `provider` and attach the shared `_ctx` object.
+ * Mutates the provider in place — the constructor passes `this` in and
+ * lets this helper own the wiring decisions.
+ */
+export function composeGateways(provider) {
+  const p = provider;
+  const ghDeps = { gh: p._gh, owner: p.owner, repo: p.repo };
+  const addItemToProject = (id) => projects.addItemToProject(p._ctx, id);
+  const getProjectNumber = () => p.projectNumber;
+
+  p.tickets = new TicketGateway({
+    ...ghDeps,
+    cache: p._cache,
+    hooks: {
+      addSubIssue: (a, b) => p.addSubIssue(a, b),
+      addItemToProject,
+      getProjectNumber,
+    },
+  });
+  p.subIssues = new SubIssueGateway({
+    ghGraphql: (q, v, o) => p.graphql(q, v, o),
+    cache: p._cache,
+    classifyGithubError,
+    hooks: {
+      getTicket: (id, o) => p.getTicket(id, o),
+      getTickets: (id) => p.getTickets(id),
+      primeTicketCache: (t) => p.primeTicketCache(t),
+      invalidateTicket: (id) => p.invalidateTicket(id),
+    },
+  });
+  p.comments = new CommentGateway({
+    ...ghDeps,
+    hooks: { invalidateTicket: (id) => p.invalidateTicket(id) },
+  });
+  p.labels = new LabelGateway(ghDeps);
+  p.branchProtection = new BranchProtectionGateway(ghDeps);
+  p.mergeMethods = new MergeMethodsGateway(ghDeps);
+  p.pullRequests = new PullRequestGateway({
+    gh: p._gh,
+    hooks: {
+      getTicket: (id) => p.getTicket(id),
+      addItemToProject,
+      getProjectNumber,
+    },
+  });
+  p.issues = new IssuesGateway({
+    ...ghDeps,
+    hooks: {
+      getTicket: (id, o) => p.getTicket(id, o),
+      getTickets: (id) => p.getTickets(id),
+      getNativeSubIssues: (n, id) => p.subIssues.getNativeSubIssues(n, id),
+      primeTicketCache: (t) => p.primeTicketCache(t),
+    },
+  });
+
+  p._ctx = {
+    owner: p.owner,
+    repo: p.repo,
+    projectOwner: p.projectOwner,
+    projectName: p.projectName,
+    operatorHandle: p.operatorHandle,
+    get projectNumber() {
+      return p.projectNumber;
+    },
+    set projectNumber(v) {
+      p.projectNumber = v;
+    },
+    get cache() {
+      return p._cache;
+    },
+    get token() {
+      return p._memoizedToken;
+    },
+    state: { projectId: null },
+    hooks: {
+      getTicket: (id, o) => p.getTicket(id, o),
+      addItemToProject: (id) => projects.addItemToProject(p._ctx, id),
+    },
+  };
+  p.projectBoard = new ProjectBoardGateway({ ctx: p._ctx });
+}