mandrel 1.57.0

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

@@ -0,0 +1,381 @@
+/**
+ * GitHub Provider — TicketGateway.
+ *
+ * Owns ticket CRUD against `/repos/{owner}/{repo}/issues` plus the
+ * per-instance ticket cache that the dispatcher / reconciler / cascade
+ * share. Extracted from `../github.js` in Story #2462 / Task #2482 as the
+ * first slice of the seven-gateway split.
+ *
+ * The gateway is constructed with a `{ gh, owner, repo, hooks }` object so
+ * cross-gateway concerns can be threaded in without bloating the constructor
+ * signature. Today the only hooks the ticket surface reaches for are
+ * `addSubIssue` (from the future SubIssueGateway, used by `createTicket` to
+ * link a freshly-created child as a native sub-issue) and `addItemToProject`
+ * (from the projects-v2 shim, used by `createTicket` to add the new issue
+ * to the configured Project V2).
+ *
+ * Public surface: `GitHubProvider.createTicket / createIssue / getTicket /
+ * getTickets / updateTicket / getTicketDependencies / primeTicketCache /
+ * invalidateTicket` all delegate to the same-named methods on this class.
+ *
+ * @see Story #2462 — Split GitHubProvider god class into seven composed gateways.
+ */
+
+import { parseBlockedBy, parseBlocks } from '../../lib/dependency-parser.js';
+import { addIssueToBoard } from './board-add.js';
+import { createInlineTicketCache } from './cache.js';
+import { withTransientRetry } from './errors.js';
+import { issueToListItem, issueToTicket } from './mappers.js';
+import {
+  defaultRetryWarn,
+  paginateRest,
+  parseApiJson,
+} from './request-helpers.js';
+
+/**
+ * Compose the final markdown body for a created ticket. Under the 3-tier
+ * hierarchy (Epic → Feature → Story), `body` is always a string supplied
+ * by the caller (the decomposer, the spec planner, or the reconciler-apply
+ * engine). This helper appends the canonical orchestrator footer
+ * (`parent: #<n>` / `Epic: #<m>` / `blocked by #<x>`) byte-stable with the
+ * format consumers (manifest, close-gate, dispatcher) parse.
+ *
+ * Story #3186 — inlined here when the Task-tier body-renderer helpers
+ * were retired. The structured-body (object) path is gone: Stories carry
+ * inline `acceptance[]` / `verify[]`
+ * arrays on the Story body authored by the decomposer; there is no
+ * server-side rendering of a four-section payload at create time.
+ *
+ * @param {{
+ *   body: string,
+ *   parentId: number,
+ *   epicId?: number,
+ *   dependencies?: number[],
+ * }} opts
+ * @returns {string}
+ *
+ * Story #3958 — this is the single owner of the `blocked by #N` footer.
+ * Callers (the reconciler-apply create path, the spec planner) pass
+ * resolved dependency issue numbers via `dependencies` and supply a body
+ * WITHOUT any pre-appended footer. A caller that also appends a
+ * `blocked by` block to `body` would double every dependency line.
+ */
+export function composeStoryBody({
+  body,
+  parentId,
+  epicId,
+  dependencies = [],
+}) {
+  const head = typeof body === 'string' ? body : '';
+  const lines = ['---', `parent: #${parentId}`];
+  if (epicId !== undefined && epicId !== null && epicId !== parentId) {
+    lines.push(`Epic: #${epicId}`);
+  }
+  if (dependencies.length > 0) {
+    lines.push('');
+    for (const dep of dependencies) {
+      lines.push(`blocked by #${dep}`);
+    }
+  }
+  return `${head}\n\n${lines.join('\n')}`;
+}
+
+export class TicketGateway {
+  /**
+   * @param {{
+   *   gh: object,
+   *   owner: string,
+   *   repo: string,
+   *   hooks?: {
+   *     addSubIssue?: (parentNumber: number, childNodeId: string) => Promise<unknown>,
+   *     addItemToProject?: (nodeId: string) => Promise<unknown>,
+   *     getProjectNumber?: () => number|null,
+   *   },
+   *   cache?: ReturnType<typeof createInlineTicketCache>,
+   * }} deps
+   */
+  constructor({ gh, owner, repo, hooks = {}, cache } = {}) {
+    this._gh = gh;
+    this.owner = owner;
+    this.repo = repo;
+    this._hooks = hooks;
+    this._cache = cache ?? createInlineTicketCache();
+  }
+
+  /**
+   * Expose the cache so the parent provider's other surfaces (sub-issues,
+   * comments) can keep invalidating on mutations. The parent passes the
+   * same cache instance into every gateway constructor.
+   */
+  get cache() {
+    return this._cache;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Read surface
+  // ---------------------------------------------------------------------------
+
+  /**
+   * @field-manifest /repos/{owner}/{repo}/issues/{n}: number, id, node_id,
+   *                 title, body, labels, assignees, state
+   */
+  async getTicket(ticketId, opts = {}) {
+    if (!opts.fresh) {
+      if (Number.isFinite(opts.maxAgeMs)) {
+        const fresh = this._cache.peekFresh(ticketId, opts.maxAgeMs);
+        if (fresh !== undefined) return fresh;
+      } else if (this._cache.has(ticketId)) {
+        return this._cache.peek(ticketId);
+      }
+    }
+    const result = await withTransientRetry(
+      () =>
+        this._gh.api({
+          method: 'GET',
+          endpoint: `/repos/${this.owner}/${this.repo}/issues/${ticketId}`,
+        }),
+      { label: `getTicket #${ticketId}`, onRetry: defaultRetryWarn },
+    );
+    const ticket = issueToTicket(parseApiJson(result));
+    this._cache.set(ticketId, ticket);
+    return ticket;
+  }
+
+  /**
+   * @field-manifest /repos/{owner}/{repo}/issues?state=...&labels=...:
+   *                 number, body, labels, state, pull_request
+   */
+  /* node:coverage ignore next */
+  async getTickets(epicId, filters = {}) {
+    const params = new URLSearchParams({ state: filters.state ?? 'all' });
+    if (filters.label) params.set('labels', filters.label);
+
+    const endpoint = `/repos/${this.owner}/${this.repo}/issues?${params}`;
+    const issues = await paginateRest(this._gh, endpoint);
+
+    // Word-boundary regex prevents #1 matching #10, #100, etc.
+    const epicRefRe = new RegExp(
+      `(?:Epic:\\s*#${epicId}|parent:\\s*#${epicId})(?:\\s|$|[,.)\\]])`,
+    );
+
+    return issues
+      .filter((issue) => {
+        if (issue.pull_request) return false;
+        const body = issue.body ?? '';
+        return epicRefRe.test(body);
+      })
+      .map(issueToListItem);
+  }
+
+  /* node:coverage ignore next */
+  async getTicketDependencies(ticketId) {
+    const ticket = await this.getTicket(ticketId);
+    return {
+      blocks: parseBlocks(ticket.body),
+      blockedBy: parseBlockedBy(ticket.body),
+    };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Cache primers — exposed so the parent provider keeps a stable surface for
+  // `primeTicketCache` / `invalidateTicket` callers.
+  // ---------------------------------------------------------------------------
+
+  primeTicketCache(tickets) {
+    this._cache.primeMany(tickets);
+  }
+
+  invalidateTicket(ticketId) {
+    this._cache.invalidate(ticketId);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Write surface
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Create a new issue. Renders the body via the inline `composeStoryBody`
+   * helper so the `parent: #N` / `Epic: #M` / `blocked by #X` footer is
+   * consistent across creators.
+   *
+   * After the POST, opportunistically link the child as a native sub-issue
+   * (via the `addSubIssue` hook — retried internally on the sub-issue
+   * gateway) and add it to the configured Project V2 (best-effort —
+   * failures warn but do not fail the create).
+   *
+   * @field-manifest POST /repos/{owner}/{repo}/issues: number, id, node_id,
+   *                 html_url
+   */
+  /* node:coverage ignore next */
+  async createTicket(parentId, ticketData) {
+    const epicId = ticketData.epicId || parentId;
+    const renderedBody = composeStoryBody({
+      body: ticketData.body ?? '',
+      parentId,
+      epicId,
+      dependencies: ticketData.dependencies ?? [],
+    });
+
+    const result = await this._gh.api({
+      method: 'POST',
+      endpoint: `/repos/${this.owner}/${this.repo}/issues`,
+      body: {
+        title: ticketData.title,
+        body: renderedBody,
+        labels: ticketData.labels ?? [],
+      },
+    });
+    const issue = parseApiJson(result);
+
+    let subIssueLinked = false;
+    let subIssueError = null;
+    try {
+      if (typeof this._hooks.addSubIssue === 'function') {
+        await this._hooks.addSubIssue(parentId, issue.node_id);
+        subIssueLinked = true;
+      }
+    } catch (err) {
+      subIssueError = err;
+    }
+
+    await addIssueToBoard({
+      nodeId: issue.node_id,
+      issueNumber: issue.number,
+      getProjectNumber: this._hooks.getProjectNumber,
+      addItemToProject: this._hooks.addItemToProject,
+    });
+
+    return {
+      id: issue.number,
+      internalId: issue.id,
+      nodeId: issue.node_id,
+      url: issue.html_url,
+      subIssueLinked,
+      subIssueError,
+    };
+  }
+
+  /**
+   * Create a **bare** issue — no `parent: #N` footer composition and no
+   * sub-issue link. Serves the standalone create paths that bypass
+   * `createTicket`'s Story-shaped body rendering: the `/story-plan`
+   * persist step and the `/epic-plan` Phase 4 Epic open
+   * (`openEpicFromOnePager`'s `createIssue` port).
+   *
+   * After the POST, the new issue is added to the configured Project V2
+   * board via the shared `addIssueToBoard` helper (Story #3822) —
+   * idempotent, non-fatal, and a no-op when no project number resolves —
+   * so board membership never depends on GitHub's "Auto-add to project"
+   * built-in workflow.
+   *
+   * @field-manifest POST /repos/{owner}/{repo}/issues: number, id, node_id,
+   *                 html_url
+   *
+   * @param {{ title: string, body: string, labels?: string[] }} payload
+   * @returns {Promise<{
+   *   id: number,
+   *   number: number,
+   *   internalId: number,
+   *   nodeId: string,
+   *   url: string,
+   *   boardAdd: { added: boolean, reason?: string },
+   * }>}
+   */
+  async createIssue({ title, body, labels = [] }) {
+    const result = await this._gh.api({
+      method: 'POST',
+      endpoint: `/repos/${this.owner}/${this.repo}/issues`,
+      body: { title, body, labels },
+    });
+    const issue = parseApiJson(result);
+
+    const boardAdd = await addIssueToBoard({
+      nodeId: issue.node_id,
+      issueNumber: issue.number,
+      getProjectNumber: this._hooks.getProjectNumber,
+      addItemToProject: this._hooks.addItemToProject,
+    });
+
+    return {
+      id: issue.number,
+      number: issue.number,
+      internalId: issue.id,
+      nodeId: issue.node_id,
+      url: issue.html_url,
+      boardAdd,
+    };
+  }
+
+  /**
+   * Add/remove labels on an issue. When the only mutation is "add", uses the
+   * additive labels endpoint (POST /issues/{n}/labels) for atomicity and to
+   * avoid a read-before-write. When other PATCH fields are present, or when
+   * removing labels, computes the final label set and returns it to the
+   * caller for inclusion in the PATCH.
+   */
+  async _applyLabelMutations(
+    ticketId,
+    labelMutations,
+    hasOtherPatchFields,
+    ticketSnapshot = null,
+  ) {
+    const { add = [], remove = [] } = labelMutations;
+
+    if (add.length > 0 && remove.length === 0 && !hasOtherPatchFields) {
+      await this._gh.api({
+        method: 'POST',
+        endpoint: `/repos/${this.owner}/${this.repo}/issues/${ticketId}/labels`,
+        body: { labels: add },
+      });
+      return { skipPatch: true };
+    }
+
+    // Story #1795 — when `transitionTicketState` threads a pre-fetched
+    // snapshot via `_ticketSnapshot` we reuse its labels rather than
+    // issuing another `getTicket` for the merge.
+    const ticket = ticketSnapshot ?? (await this.getTicket(ticketId));
+    const currentLabels = new Set(ticket.labels ?? []);
+    for (const l of remove) currentLabels.delete(l);
+    for (const l of add) currentLabels.add(l);
+
+    return { skipPatch: false, mergedLabels: Array.from(currentLabels) };
+  }
+
+  /**
+   * @field-manifest PATCH /repos/{owner}/{repo}/issues/{n}:
+   *                 body, assignees, state, state_reason, labels
+   */
+  /* node:coverage ignore next */
+  async updateTicket(ticketId, mutations) {
+    const patch = {};
+    if (mutations.body !== undefined) patch.body = mutations.body;
+    if (mutations.assignees) patch.assignees = mutations.assignees;
+    if (mutations.state !== undefined) patch.state = mutations.state;
+    if (mutations.state_reason !== undefined)
+      patch.state_reason = mutations.state_reason;
+
+    if (mutations.labels) {
+      const hasOtherPatchFields = Object.keys(patch).length > 0;
+      const result = await this._applyLabelMutations(
+        ticketId,
+        mutations.labels,
+        hasOtherPatchFields,
+        mutations._ticketSnapshot ?? null,
+      );
+      if (result.skipPatch) {
+        this.invalidateTicket(ticketId);
+        return;
+      }
+      patch.labels = result.mergedLabels;
+    }
+
+    if (Object.keys(patch).length > 0) {
+      await this._gh.api({
+        method: 'PATCH',
+        endpoint: `/repos/${this.owner}/${this.repo}/issues/${ticketId}`,
+        body: patch,
+      });
+      this.invalidateTicket(ticketId);
+    }
+  }
+}

package/.agents/scripts/providers/github/transient-retry.js

@@ -0,0 +1,62 @@
+/**
+ * transient-retry — shared retry-with-backoff for GitHub provider calls.
+ *
+ * Resilience for flaky connections (e.g. cell hotspots): retry ONLY on
+ * connectivity blips, never on auth / scope / not-found / already-exists /
+ * validation errors. Works for both surfaces the provider uses:
+ *   - the gh CLI path — errors carry the Go HTTP error on `err.stderr`
+ *     (e.g. `dial tcp ...: i/o timeout`); and
+ *   - the direct `fetch` path — errors are a `TypeError: fetch failed` with
+ *     the real reason on `err.cause` (e.g. `ETIMEDOUT`, `ENOTFOUND`).
+ *
+ * Retrying a non-idempotent create is acceptable for the dominant hotspot
+ * failure (`dial tcp ... i/o timeout` means the connection never opened, so
+ * the request never reached GitHub). Callers still gate retry per call so
+ * the genuinely non-idempotent project-create can opt out.
+ */
+
+const TRANSIENT_RE =
+  /i\/o timeout|dial tcp|TLS handshake timeout|connection reset|connection refused|temporary failure|could not resolve host|no such host|network is unreachable|socket hang up|fetch failed|ConnectTimeoutError|UND_ERR_CONNECT_TIMEOUT|ETIMEDOUT|ECONNRESET|ECONNREFUSED|ENOTFOUND|EAI_AGAIN|\b50[234]\b/i;
+
+/** True when an error looks like a retryable network/connectivity blip. */
+export function isTransientNetworkError(err) {
+  const hay = [
+    err?.stderr,
+    err?.message,
+    err?.code,
+    err?.cause?.message,
+    err?.cause?.code,
+  ]
+    .filter(Boolean)
+    .join(' ');
+  return TRANSIENT_RE.test(hay);
+}
+
+/**
+ * Run `fn`, retrying with exponential backoff ONLY on transient network
+ * errors (1s, 2s, 4s by default). Non-transient errors throw immediately so
+ * real failures stay loud. `sleep` is injectable for tests.
+ *
+ * @template T
+ * @param {() => Promise<T>} fn
+ * @param {{ retries?: number, baseDelayMs?: number,
+ *   sleep?: (ms: number) => Promise<void> }} [opts]
+ * @returns {Promise<T>}
+ */
+export async function withTransientRetry(
+  fn,
+  {
+    retries = 3,
+    baseDelayMs = 1000,
+    sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+  } = {},
+) {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      if (attempt >= retries || !isTransientNetworkError(err)) throw err;
+      await sleep(baseDelayMs * 2 ** attempt);
+    }
+  }
+}

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

@@ -0,0 +1,157 @@
+/**
+ * GitHub Provider — composition root (thin composer).
+ *
+ * Story #2462 (Epic #2453) split this class into nine sibling modules under
+ * `./github/`. This file now does two things only:
+ *
+ *   1. **Holds the constructor** that captures config + opts + the gh-exec
+ *      facade, then delegates gateway wiring to `composeGateways()` in
+ *      `./github/compose.js`.
+ *   2. **Installs the ITicketingProvider surface** as one-line delegating
+ *      methods sourced from the `DELEGATIONS` table below — every public
+ *      method forwards verbatim to a concrete gateway.
+ *
+ * Re-exports: only the five error-classification helpers still used by tests
+ * that import through this barrel (classifyGithubError et al.). All other
+ * symbols (mappers, auth helpers, sub-issue constants) are dead exports per
+ * baselines/dead-exports.json and were removed in Story #3650 (Epic #3599).
+ * Callers should import those symbols directly from their ./github/<sub>.js
+ * module.
+ *
+ * Gateway map: tickets, sub-issues, comments, labels, branch-protection,
+ * merge-methods, prs, project-board, issues (epics + sub-tickets +
+ * branch probe + raw GraphQL).
+ */
+
+import { createGh, gh as defaultGh } from '../lib/gh-exec.js';
+import { ITicketingProvider } from '../lib/ITicketingProvider.js';
+import { resolveToken } from './github/auth.js';
+import { createInlineTicketCache } from './github/cache.js';
+import { composeGateways } from './github/compose.js';
+import {
+  classifyGithubError,
+  extractErrorFields,
+  isPermissionSignal,
+  isTransientByCodeOrMessage,
+  isTransientStatus,
+} from './github/errors.js';
+import * as projects from './github/projects-v2-graphql.js';
+
+export {
+  classifyGithubError,
+  extractErrorFields,
+  isPermissionSignal,
+  isTransientByCodeOrMessage,
+  isTransientStatus,
+};
+
+export class GitHubProvider extends ITicketingProvider {
+  constructor(config, opts = {}) {
+    super();
+    this.owner = config.owner;
+    this.repo = config.repo;
+    this.projectNumber = config.projectNumber ?? null;
+    this.projectOwner = config.projectOwner ?? config.owner;
+    this.projectName = config.projectName ?? null;
+    this.operatorHandle = config.operatorHandle ?? null;
+    this._explicitToken = opts.token ?? null;
+    this._memoizedToken = opts.token ?? null;
+    // Resolve the gh-exec default timeout (Story #2860). When the operator
+    // sets `github.defaultTimeoutMs` in `.agentrc.json`, every `gh`
+    // subprocess this provider spawns inherits that timeout ceiling. An
+    // injected `opts.gh` is honored as-is so tests can drive the facade
+    // without going through this fallback. Unset → 60_000 ms in code.
+    if (opts.gh) {
+      this._gh = opts.gh;
+    } else {
+      const defaultTimeoutMs = config.defaultTimeoutMs ?? 60_000;
+      this._gh =
+        defaultTimeoutMs > 0
+          ? createGh(undefined, { timeoutMs: defaultTimeoutMs })
+          : defaultGh;
+    }
+    this._cache = createInlineTicketCache();
+    composeGateways(this);
+  }
+
+  get token() {
+    if (this._memoizedToken) return this._memoizedToken;
+    this._memoizedToken = resolveToken();
+    return this._memoizedToken;
+  }
+
+  /* node:coverage ignore next */
+  async listIssues(filters = {}) {
+    return this.getEpics(filters);
+  }
+
+  static isInsufficientScopes(err) {
+    return projects.isInsufficientScopes(err);
+  }
+}
+
+/**
+ * Delegation table. Each `[publicMethod, 'gatewayName.gatewayMethod']` pair
+ * installs an async wrapper on `GitHubProvider.prototype` that forwards
+ * every argument to the matching gateway method. This keeps the parity
+ * surface explicit and the file under the thin-composer LOC ceiling.
+ */
+const DELEGATIONS = [
+  ['graphql', 'issues.ghGraphql'],
+  ['listIssuesByLabel', 'issues.listIssuesByLabel'],
+  ['getEpics', 'issues.getEpics'],
+  ['getEpic', 'issues.getEpic'],
+  ['branchExists', 'issues.branchExists'],
+  ['getSubTickets', 'issues.getSubTickets'],
+  ['_getReferencedChildren', 'issues._getReferencedChildren'],
+  ['getTickets', 'tickets.getTickets'],
+  ['getTicket', 'tickets.getTicket'],
+  ['getTicketDependencies', 'tickets.getTicketDependencies'],
+  ['createTicket', 'tickets.createTicket'],
+  ['createIssue', 'tickets.createIssue'],
+  ['updateTicket', 'tickets.updateTicket'],
+  ['_applyLabelMutations', 'tickets._applyLabelMutations'],
+  ['_getNativeSubIssues', 'subIssues.getNativeSubIssues'],
+  ['_getNativeParent', 'subIssues.getNativeParent'],
+  ['addSubIssue', 'subIssues.addSubIssue'],
+  ['removeSubIssue', 'subIssues.removeSubIssue'],
+  ['reconcileSubIssueLinks', 'subIssues.reconcileSubIssueLinks'],
+  ['getRecentComments', 'comments.getRecentComments'],
+  ['getTicketComments', 'comments.getTicketComments'],
+  ['deleteComment', 'comments.deleteComment'],
+  ['postComment', 'comments.postComment'],
+  ['getBranchProtection', 'branchProtection.getBranchProtection'],
+  ['setBranchProtection', 'branchProtection.setBranchProtection'],
+  ['createPullRequest', 'pullRequests.createPullRequest'],
+  ['ensureLabels', 'labels.ensureLabels'],
+  ['_reconcileLabelsPresence', 'labels._reconcileLabelsPresence'],
+  ['getMergeMethods', 'mergeMethods.getMergeMethods'],
+  ['setMergeMethods', 'mergeMethods.setMergeMethods'],
+  ['resolveOrCreateProject', 'projectBoard.resolveOrCreateProject'],
+  ['ensureStatusField', 'projectBoard.ensureStatusField'],
+  ['ensureProjectViews', 'projectBoard.ensureProjectViews'],
+  ['ensureProjectFields', 'projectBoard.ensureProjectFields'],
+];
+for (const [name, target] of DELEGATIONS) {
+  const [gw, method] = target.split('.');
+  GitHubProvider.prototype[name] = async function (...args) {
+    return this[gw][method](...args);
+  };
+}
+
+// Synchronous (void-returning or non-promise) delegations.
+GitHubProvider.prototype.primeTicketCache = function (t) {
+  this.tickets.primeTicketCache(t);
+};
+GitHubProvider.prototype.invalidateTicket = function (id) {
+  this.tickets.invalidateTicket(id);
+};
+GitHubProvider.prototype._normalizeLabelListResult = function (r) {
+  return this.labels._normalizeLabelListResult(r);
+};
+GitHubProvider.prototype._getChecklistChildren = function (body) {
+  return this.issues._getChecklistChildren(body);
+};
+GitHubProvider.prototype._updateLabels = function (id, mutations, hasOther) {
+  return this._applyLabelMutations(id, mutations, hasOther);
+};