@remogram/core 0.1.0-beta.0 → 0.1.0-beta.10

package/auth-classes.js

@@ -0,0 +1,73 @@
+/** Per-command auth requirements for structured provider capabilities. */
+export const AUTH_CLASS = {
+  NONE: 'none',
+  GIT_ONLY: 'git_only',
+  TOKEN_REQUIRED: 'token_required',
+};
+
+const AUTH_CLASS_VALUES = new Set(Object.values(AUTH_CLASS));
+
+/** Runtime auth requirements for fully implemented API providers. */
+export const API_PROVIDER_COMMAND_AUTH = {
+  repo_status: AUTH_CLASS.NONE,
+  ref_compare: AUTH_CLASS.GIT_ONLY,
+  ref_inventory: AUTH_CLASS.GIT_ONLY,
+  cr_inventory: AUTH_CLASS.TOKEN_REQUIRED,
+  pr_status: AUTH_CLASS.TOKEN_REQUIRED,
+  pr_checks: AUTH_CLASS.TOKEN_REQUIRED,
+  merge_plan: AUTH_CLASS.TOKEN_REQUIRED,
+  sync_plan: AUTH_CLASS.GIT_ONLY,
+  cr_open: AUTH_CLASS.TOKEN_REQUIRED,
+  issue_open: AUTH_CLASS.TOKEN_REQUIRED,
+  status_set: AUTH_CLASS.TOKEN_REQUIRED,
+  whoami: AUTH_CLASS.TOKEN_REQUIRED,
+  branch_protection: AUTH_CLASS.TOKEN_REQUIRED,
+  cr_files: AUTH_CLASS.TOKEN_REQUIRED,
+  cr_comments: AUTH_CLASS.TOKEN_REQUIRED,
+  forge_changes: AUTH_CLASS.TOKEN_REQUIRED,
+  merge_execute: AUTH_CLASS.TOKEN_REQUIRED,
+};
+
+export function commandCapability(name, { implemented = true } = {}) {
+  const auth_class = API_PROVIDER_COMMAND_AUTH[name];
+  if (!auth_class) {
+    throw new Error(`Unknown command: ${name}`);
+  }
+  return { name, implemented, auth_class };
+}
+
+export function apiProviderCommands({
+  writeCommandsImplemented = false,
+  issueOpenImplemented = false,
+  statusSetImplemented = false,
+  branchProtectionImplemented = false,
+  crFilesImplemented = false,
+  crCommentsImplemented = false,
+  forgeChangesImplemented = false,
+  mergeExecuteImplemented = false,
+} = {}) {
+  return Object.keys(API_PROVIDER_COMMAND_AUTH).map((name) => {
+    let implemented = true;
+    if (name === 'cr_open') implemented = writeCommandsImplemented;
+    if (name === 'issue_open') implemented = issueOpenImplemented;
+    if (name === 'status_set') implemented = statusSetImplemented;
+    if (name === 'branch_protection') implemented = branchProtectionImplemented;
+    if (name === 'cr_files') implemented = crFilesImplemented;
+    if (name === 'cr_comments') implemented = crCommentsImplemented;
+    if (name === 'forge_changes') implemented = forgeChangesImplemented;
+    if (name === 'merge_execute') implemented = mergeExecuteImplemented;
+    return commandCapability(name, { implemented });
+  });
+}
+
+export function stubProviderCommands() {
+  return Object.keys(API_PROVIDER_COMMAND_AUTH).map((name) =>
+    commandCapability(name, { implemented: false }),
+  );
+}
+
+export function assertAuthClass(value) {
+  if (!AUTH_CLASS_VALUES.has(value)) {
+    throw new Error(`Invalid auth_class: ${value}`);
+  }
+}

package/branch-protection.js

@@ -0,0 +1,155 @@
+import { sanitizeField } from './caps.js';
+
+export const MAX_BRANCH_PROTECTION_STATUS_CONTEXTS = 64;
+export const MAX_BRANCH_PROTECTION_RULES = 32;
+
+/** Gitea exposes required_approvals on branch protection; omit when unavailable. */
+export function unimplementedApprovalsRequiredSignal() {
+  return { implemented: false, count: null };
+}
+
+function sanitizeStringList(values, maxItems) {
+  if (!Array.isArray(values)) return [];
+  const out = [];
+  for (const value of values) {
+    if (out.length >= maxItems) break;
+    const sanitized = sanitizeField(value);
+    if (sanitized) out.push(sanitized);
+  }
+  return out;
+}
+
+function normalizeApprovalsRequired(signal) {
+  if (signal == null || typeof signal !== 'object') {
+    return unimplementedApprovalsRequiredSignal();
+  }
+  if (signal.implemented === false) {
+    return { implemented: false, count: null };
+  }
+  if (signal.implemented === true) {
+    if (signal.count == null) {
+      return { implemented: true, count: null };
+    }
+    const count = Number(signal.count);
+    if (!Number.isFinite(count) || count < 0) {
+      return { implemented: true, count: null };
+    }
+    return { implemented: true, count: Math.floor(count) };
+  }
+  return unimplementedApprovalsRequiredSignal();
+}
+
+export function buildBranchProtectionBody({
+  branch_ref,
+  required_status_contexts,
+  protected_branch_rules,
+  approvals_required,
+}) {
+  const rules = (Array.isArray(protected_branch_rules) ? protected_branch_rules : [])
+    .slice(0, MAX_BRANCH_PROTECTION_RULES)
+    .map((rule) => {
+      const name =
+        rule != null && typeof rule === 'object'
+          ? sanitizeField(rule.name)
+          : sanitizeField(rule);
+      return name ? { name } : null;
+    })
+    .filter(Boolean);
+
+  return {
+    branch_ref: sanitizeField(branch_ref),
+    required_status_contexts: sanitizeStringList(
+      required_status_contexts,
+      MAX_BRANCH_PROTECTION_STATUS_CONTEXTS,
+    ),
+    protected_branch_rules: rules,
+    approvals_required: normalizeApprovalsRequired(approvals_required),
+  };
+}
+
+export function buildBranchProtectionFromGitLabProtection(
+  branchRef,
+  { protectedBranch = null, approvalRules = [] } = {},
+) {
+  if (protectedBranch == null) {
+    return buildBranchProtectionBody({
+      branch_ref: branchRef,
+      required_status_contexts: [],
+      protected_branch_rules: [],
+      approvals_required: unimplementedApprovalsRequiredSignal(),
+    });
+  }
+  const ruleName = sanitizeField(protectedBranch.name ?? branchRef);
+  let approvals_required = unimplementedApprovalsRequiredSignal();
+  if (Array.isArray(approvalRules) && approvalRules.length > 0) {
+    const counts = approvalRules
+      .map((rule) => Number(rule.approvals_required))
+      .filter((count) => Number.isFinite(count) && count >= 0);
+    if (counts.length > 0) {
+      approvals_required = { implemented: true, count: Math.max(...counts) };
+    }
+  }
+  return buildBranchProtectionBody({
+    branch_ref: branchRef,
+    required_status_contexts: [],
+    protected_branch_rules: ruleName ? [{ name: ruleName }] : [],
+    approvals_required,
+  });
+}
+
+export function buildBranchProtectionFromGitHubProtection(branchRef, protectionPayload) {
+  if (protectionPayload == null) {
+    return buildBranchProtectionBody({
+      branch_ref: branchRef,
+      required_status_contexts: [],
+      protected_branch_rules: [],
+      approvals_required: unimplementedApprovalsRequiredSignal(),
+    });
+  }
+  const payload =
+    protectionPayload != null && typeof protectionPayload === 'object' ? protectionPayload : {};
+  const required_status_contexts = sanitizeStringList(
+    payload.required_status_checks?.contexts,
+    MAX_BRANCH_PROTECTION_STATUS_CONTEXTS,
+  );
+  let approvals_required = unimplementedApprovalsRequiredSignal();
+  const reviews = payload.required_pull_request_reviews;
+  if (reviews != null && typeof reviews === 'object' && 'required_approving_review_count' in reviews) {
+    const count = Number(reviews.required_approving_review_count);
+    if (Number.isFinite(count) && count >= 0) {
+      approvals_required = { implemented: true, count: Math.floor(count) };
+    }
+  }
+  const ruleName = sanitizeField(branchRef);
+  return buildBranchProtectionBody({
+    branch_ref: branchRef,
+    required_status_contexts,
+    protected_branch_rules: ruleName ? [{ name: ruleName }] : [],
+    approvals_required,
+  });
+}
+
+export function buildBranchProtectionFromGiteaProtection(branchRef, protectionPayload) {
+  const payload =
+    protectionPayload != null && typeof protectionPayload === 'object' ? protectionPayload : {};
+  const ruleName = sanitizeField(payload.branch_name ?? payload.rule_name ?? branchRef);
+  const required_status_contexts =
+    payload.enable_status_check === false
+      ? []
+      : sanitizeStringList(payload.status_check_contexts, MAX_BRANCH_PROTECTION_STATUS_CONTEXTS);
+
+  let approvals_required = unimplementedApprovalsRequiredSignal();
+  if ('required_approvals' in payload) {
+    const count = Number(payload.required_approvals);
+    if (Number.isFinite(count) && count >= 0) {
+      approvals_required = { implemented: true, count: Math.floor(count) };
+    }
+  }
+
+  return buildBranchProtectionBody({
+    branch_ref: branchRef,
+    required_status_contexts,
+    protected_branch_rules: ruleName ? [{ name: ruleName }] : [],
+    approvals_required,
+  });
+}

package/caps.js

@@ -1,10 +1,122 @@
 export const DEFAULT_MAX_BYTES = 8192;
 export const DEFAULT_FIELD_MAX_BYTES = 512;
+export const FORGE_INGEST_MAX_BYTES_ENV = 'REMOGRAM_FORGE_INGEST_MAX_BYTES';
+/** Upper bound for undocumented REMOGRAM_FORGE_INGEST_MAX_BYTES debug override. */
+export const MAX_FORGE_INGEST_ENV_BYTES = 65536;
+
+/** Conservative check/status page size vs DEFAULT_MAX_BYTES raw ingest cap (pre-parse). */
+export const DEFAULT_CHECK_STATUS_PAGE_SIZE = 25;
+export const MAX_CHECK_STATUS_PAGES = 50;
+
+/** Gitea open-pull list page size for idempotency scan and inventory list bounds. */
+export const DEFAULT_OPEN_PULL_LIST_PAGE_SIZE = 100;
+/** Max pages scanned before cr open idempotency fails closed (decoupled from check-status pagination). */
+export const MAX_OPEN_PULL_IDEMPOTENCY_PAGES = 50;
+
+export function getEffectiveIngestMaxBytes() {
+  const raw = process.env[FORGE_INGEST_MAX_BYTES_ENV];
+  if (raw == null || raw === '') {
+    return { bytes: DEFAULT_MAX_BYTES, envOverride: false };
+  }
+  const parsed = Number.parseInt(String(raw), 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return { bytes: DEFAULT_MAX_BYTES, envOverride: false, invalidEnv: true };
+  }
+  if (parsed > MAX_FORGE_INGEST_ENV_BYTES) {
+    return { bytes: MAX_FORGE_INGEST_ENV_BYTES, envOverride: true, clamped: true };
+  }
+  return { bytes: parsed, envOverride: true };
+}
+
+/** Facts for provider capabilities packets (forge ingest policy). */
+export function forgeIngestCapabilityFacts() {
+  const { bytes, envOverride, clamped } = getEffectiveIngestMaxBytes();
+  return {
+    forge_ingest_cap_bytes: bytes,
+    ...(envOverride ? { forge_ingest_env_override: true } : {}),
+    ...(clamped ? { forge_ingest_cap_clamped: true } : {}),
+  };
+}
+
+/**
+ * Structured check-list pagination facts for provider capabilities.
+ * @param {{ strategy: 'offset_limit' | 'link_header', pageSizeParam: 'limit' | 'per_page' | null, sourceCount?: number }} opts
+ */
+export function checkPaginationCapabilityFacts({ strategy, pageSizeParam, sourceCount = 1 }) {
+  const perSource = DEFAULT_CHECK_STATUS_PAGE_SIZE * MAX_CHECK_STATUS_PAGES;
+  return {
+    check_pagination: {
+      strategy,
+      page_size: DEFAULT_CHECK_STATUS_PAGE_SIZE,
+      max_pages: MAX_CHECK_STATUS_PAGES,
+      page_size_param: pageSizeParam,
+      ingest_backoff: 'halve_until_fit',
+      on_page_cap: 'set_checks_truncated',
+      compliant_max_items_per_source: perSource,
+      check_source_count: sourceCount,
+      truncation_combination:
+        sourceCount > 1 ? 'any_source_truncated' : 'single_source',
+      compliant_max_items_total: perSource * sourceCount,
+      truncation_packet_field: 'checks_truncated',
+    },
+  };
+}
+
+/** Structured idempotency scan facts for provider capabilities (cr open). */
+export function idempotencyScanCapabilityFacts() {
+  return {
+    idempotency_scan: {
+      max_pages: MAX_OPEN_PULL_IDEMPOTENCY_PAGES,
+      page_size: DEFAULT_OPEN_PULL_LIST_PAGE_SIZE,
+      ingest_backoff: 'halve_until_fit',
+    },
+  };
+}
+
+/** Idempotency scan facts for status set (commit-status list pagination). */
+export function statusSetIdempotencyScanCapabilityFacts() {
+  return {
+    idempotency_scan: {
+      max_pages: MAX_OPEN_PULL_IDEMPOTENCY_PAGES,
+      page_size: DEFAULT_CHECK_STATUS_PAGE_SIZE,
+      ingest_backoff: 'halve_until_fit',
+    },
+  };
+}
+
+/** Structured open-pull list pagination facts for provider capabilities (cr inventory). */
+export function openPullListCapabilityFacts({
+  totalCountSource = null,
+  totalCountHeader = null,
+  sliceSortNotes = null,
+} = {}) {
+  const compliantMaxItems = DEFAULT_OPEN_PULL_LIST_PAGE_SIZE * MAX_CHECK_STATUS_PAGES;
+  return {
+    open_pull_list: {
+      max_pages: MAX_CHECK_STATUS_PAGES,
+      page_size: DEFAULT_OPEN_PULL_LIST_PAGE_SIZE,
+      ingest_backoff: 'halve_until_fit',
+      compliant_max_items: compliantMaxItems,
+      truncation_packet_field: 'list_truncated',
+      incomplete_error_code: 'inventory_list_incomplete',
+      default_slice_sort: 'number_asc',
+      supported_slice_sorts: [
+        'number_asc',
+        'number_desc',
+        'recent_update',
+        'recent_created',
+      ],
+      ...(totalCountSource ? { total_count_source: totalCountSource } : {}),
+      ...(totalCountHeader ? { total_count_header: totalCountHeader } : {}),
+      ...(sliceSortNotes ? { slice_sort_notes: sliceSortNotes } : {}),
+    },
+  };
+}
 
 export function capText(text, maxBytes = DEFAULT_MAX_BYTES) {
   if (!text) return { text: '', truncated: false, bytes: 0 };
   const buf = Buffer.from(text, 'utf8');
-  if (buf.length <= maxBytes) {
+  if (maxBytes == null || buf.length <= maxBytes) {
     return { text, truncated: false, bytes: buf.length };
   }
   let end = maxBytes;
@@ -13,13 +125,78 @@ export function capText(text, maxBytes = DEFAULT_MAX_BYTES) {
   return { text: slice, truncated: true, bytes: end };
 }
 
-export function sanitizeField(value, maxBytes = DEFAULT_FIELD_MAX_BYTES) {
-  if (value == null) return null;
-  const singleLine = String(value)
+function redactSecretPatterns(text) {
+  return text
+    .replace(/Bearer\s+\S+/gi, 'Bearer [REDACTED]')
+    .replace(/\bghp_[A-Za-z0-9]+\b/g, '[REDACTED]')
+    .replace(/\bgho_[A-Za-z0-9]+\b/g, '[REDACTED]')
+    .replace(/\bghs_[A-Za-z0-9._-]{36,}/g, '[REDACTED]')
+    .replace(/\bghs_[A-Za-z0-9_-]+\b/g, '[REDACTED]')
+    .replace(/\bglpat-[A-Za-z0-9_-]+\b/g, '[REDACTED]')
+    .replace(/\b(GITHUB_TOKEN|GH_TOKEN|GITLAB_TOKEN|GITEA_TOKEN)\b/gi, '[REDACTED]');
+}
+
+function stripControlChars(text, { preserveNewlines = false } = {}) {
+  if (preserveNewlines) {
+    return String(text)
+      .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, ' ')
+      .replace(/\r\n/g, '\n')
+      .replace(/\r/g, '\n');
+  }
+  return String(text)
     .replace(/[\x00-\x1f\x7f]/g, ' ')
     .replace(/\r?\n/g, ' ')
     .trim();
-  return capText(singleLine, maxBytes).text;
+}
+
+function applyFieldCap(text, maxBytes) {
+  if (maxBytes == null) return text;
+  return capText(text, maxBytes).text;
+}
+
+/**
+ * Read/packet sanitization — always capped at DEFAULT_FIELD_MAX_BYTES; newlines collapsed.
+ */
+export function sanitizeReadField(value, maxBytes = DEFAULT_FIELD_MAX_BYTES) {
+  if (value == null) return null;
+  const singleLine = stripControlChars(value, { preserveNewlines: false });
+  const redacted = redactSecretPatterns(singleLine);
+  return applyFieldCap(redacted, maxBytes);
+}
+
+/** @deprecated Use sanitizeReadField for read paths; alias preserved for compatibility. */
+export function sanitizeField(value, maxBytes = DEFAULT_FIELD_MAX_BYTES) {
+  return sanitizeReadField(value, maxBytes);
+}
+
+/**
+ * Forge write body sanitization — secret redaction always on; newlines preserved; cap configurable.
+ * @param {string | null | undefined} value
+ * @param {{ fieldMaxBytes?: number | null } | null} writeFieldPolicy
+ */
+export function sanitizeWriteBody(value, writeFieldPolicy = null) {
+  if (value == null) return null;
+  const maxBytes = writeFieldPolicy?.uncapped
+    ? null
+    : (writeFieldPolicy?.fieldMaxBytes ?? DEFAULT_FIELD_MAX_BYTES);
+  const cleaned = stripControlChars(value, { preserveNewlines: true }).trim();
+  const redacted = redactSecretPatterns(cleaned);
+  return applyFieldCap(redacted, maxBytes);
+}
+
+/**
+ * Forge write title/short field — redact + cap; single-line normalization.
+ * @param {string | null | undefined} value
+ * @param {{ fieldMaxBytes?: number | null, uncapped?: boolean } | null} writeFieldPolicy
+ */
+export function sanitizeWriteTitle(value, writeFieldPolicy = null) {
+  if (value == null) return null;
+  const maxBytes = writeFieldPolicy?.uncapped
+    ? null
+    : (writeFieldPolicy?.fieldMaxBytes ?? DEFAULT_FIELD_MAX_BYTES);
+  const singleLine = stripControlChars(value, { preserveNewlines: false });
+  const redacted = redactSecretPatterns(singleLine);
+  return applyFieldCap(redacted, maxBytes);
 }
 
 export function sanitizeUrl(value, maxBytes = DEFAULT_FIELD_MAX_BYTES) {
@@ -27,7 +204,9 @@ export function sanitizeUrl(value, maxBytes = DEFAULT_FIELD_MAX_BYTES) {
   try {
     const u = new URL(String(value));
     if (u.protocol !== 'http:' && u.protocol !== 'https:') return null;
-    return sanitizeField(u.href, maxBytes);
+    u.username = '';
+    u.password = '';
+    return sanitizeReadField(u.href, maxBytes);
   } catch {
     return null;
   }

package/change-request-merge-execute.js

@@ -0,0 +1,148 @@
+import { sanitizeField } from './caps.js';
+import { mergeBlockersFromFacts } from './merge-blockers.js';
+import { mergePolicyAuditFacts } from './merge-policy.js';
+
+const SHA40 = /^[0-9a-f]{40}$/i;
+
+export function mergeExecuteViewFacts(view) {
+  return {
+    sourceBranchRef: view.forge_source_branch_ref ?? view.head_ref ?? null,
+    sourceSha: view.forge_source_sha ?? view.head_sha ?? null,
+    targetSha: view.forge_target_sha ?? view.base_sha ?? null,
+  };
+}
+
+export function mergeExecuteChecksFacts(checks) {
+  return {
+    sourceSha: checks.forge_source_sha ?? checks.head_sha ?? null,
+  };
+}
+
+export function assertExpectedSha(value, flagName) {
+  const normalized = String(value ?? '').trim().toLowerCase();
+  if (!SHA40.test(normalized)) {
+    throw Object.assign(new Error(`Invalid ${flagName}`), {
+      invalidArgs: `${flagName} must be a 40-character git SHA`,
+    });
+  }
+  return normalized;
+}
+
+export function buildMergeExecuteBeforeFacts(
+  view,
+  checks,
+  mergePlanBody,
+  forgeHeadRefSha = null,
+  mergePolicy = null,
+) {
+  const viewFacts = mergeExecuteViewFacts(view);
+  const checksFacts = mergeExecuteChecksFacts(checks);
+  const audit = mergePolicyAuditFacts(mergePolicy);
+  return {
+    base_sha: viewFacts.targetSha ?? null,
+    head_sha: viewFacts.sourceSha ?? null,
+    checks_head_sha: checksFacts.sourceSha ?? null,
+    forge_head_ref_sha: forgeHeadRefSha ?? null,
+    mergeability: view.mergeability ?? 'unknown',
+    checks_conclusion: checks.check_conclusion ?? 'unknown',
+    checks_truncated: checks.checks_truncated === true,
+    merge_plan_blockers: Array.isArray(mergePlanBody.blockers) ? [...mergePlanBody.blockers] : [],
+    ...(audit ? { merge_policy: audit } : {}),
+  };
+}
+
+/**
+ * Collect merge-execute blockers before forge mutation.
+ * @returns {string[]} normalized blocker ids
+ */
+export function collectMergeExecuteBlockers(
+  view,
+  checks,
+  mergePlanBody,
+  expected,
+  { forgeHeadRefSha, mergePolicy = {} } = {},
+) {
+  const viewFacts = mergeExecuteViewFacts(view);
+  const checksFacts = mergeExecuteChecksFacts(checks);
+  const blockers = [];
+  const baseSha = viewFacts.targetSha ? String(viewFacts.targetSha).toLowerCase() : null;
+  const headSha = viewFacts.sourceSha ? String(viewFacts.sourceSha).toLowerCase() : null;
+
+  if (baseSha && expected.baseSha !== baseSha) blockers.push('base_sha_mismatch');
+  if (headSha && expected.headSha !== headSha) blockers.push('head_sha_mismatch');
+
+  const forgeHead = forgeHeadRefSha ? String(forgeHeadRefSha).toLowerCase() : null;
+  const checksHead = checksFacts.sourceSha ? String(checksFacts.sourceSha).toLowerCase() : null;
+  if (headSha && checksHead && headSha !== checksHead) blockers.push('checks_head_sha_mismatch');
+  if (headSha && forgeHead && headSha !== forgeHead) blockers.push('forge_pr_head_mismatch');
+  if (checksHead && forgeHead && checksHead !== forgeHead) blockers.push('checks_forge_head_mismatch');
+  if (forgeHead && forgeHead !== expected.headSha) blockers.push('head_ref_moved');
+
+  const planBlockers = mergeBlockersFromFacts(view, checks, {}, mergePolicy);
+  for (const blocker of planBlockers) {
+    if (!blockers.includes(blocker)) blockers.push(blocker);
+  }
+
+  if (view.mergeability !== 'clean') {
+    if (view.mergeability === 'conflicted' && !blockers.includes('merge_conflict')) {
+      blockers.push('merge_conflict');
+    } else if (view.mergeability !== 'conflicted' && !blockers.includes('mergeability_not_clean')) {
+      blockers.push('mergeability_not_clean');
+    }
+  }
+
+  return blockers;
+}
+
+export function buildCrMergeBlockedBody({
+  prNumber,
+  expected,
+  before,
+  blockers,
+}) {
+  return {
+    change_request: { number: prNumber },
+    expected: {
+      base_sha: expected.baseSha,
+      head_sha: expected.headSha,
+    },
+    before,
+    blockers,
+  };
+}
+
+export function buildCrMergedBody({
+  prNumber,
+  expected,
+  before,
+  merge,
+  after,
+}) {
+  return {
+    change_request: { number: prNumber, state: 'merged' },
+    expected: {
+      base_sha: expected.baseSha,
+      head_sha: expected.headSha,
+    },
+    before,
+    merge,
+    after,
+  };
+}
+
+export function buildMergeExecuteAfterFacts(view, mergeResult = {}) {
+  const viewFacts = mergeExecuteViewFacts(view);
+  return {
+    state: 'merged',
+    base_sha: mergeResult.base_sha ?? viewFacts.targetSha ?? null,
+    head_sha: viewFacts.sourceSha ?? null,
+  };
+}
+
+export function buildMergeExecuteMergeFacts(method, providerResult = {}) {
+  return {
+    method: sanitizeField(method),
+    commit_sha: providerResult.commit_sha ?? null,
+    provider_status: providerResult.provider_status ?? null,
+  };
+}

package/check-diagnostics.js

@@ -0,0 +1,92 @@
+import { sanitizeField } from './caps.js';
+
+function uniqueSorted(values) {
+  return [...new Set(values.filter(Boolean))].sort((a, b) => a.localeCompare(b));
+}
+
+/**
+ * @param {object} entry
+ * @param {{ headSha?: string | null, requiredContexts?: Set<string> }} opts
+ */
+export function enrichCheckStatus(entry, opts = {}) {
+  const headSha = opts.headSha ?? null;
+  const context = sanitizeField(entry?.context);
+  const rawSha = entry?.sha != null ? sanitizeField(entry.sha) : headSha;
+  const sha = rawSha || null;
+  const stale = Boolean(headSha && sha && sha !== headSha);
+  const required = context ? opts.requiredContexts?.has(context) === true : false;
+  return {
+    context,
+    state: entry?.state ?? 'unknown',
+    ...(sha ? { sha } : {}),
+    required,
+    source: sanitizeField(entry?.source) || 'commit_status',
+    ...(entry?.target_url ? { target_url: sanitizeField(entry.target_url) } : {}),
+    ...(entry?.description ? { description: sanitizeField(entry.description) } : {}),
+    ...(stale ? { stale: true } : {}),
+  };
+}
+
+/**
+ * @param {object[]} statuses
+ * @param {{ headSha?: string | null, requiredContexts?: string[] }} opts
+ */
+export function buildCheckDiagnostics(statuses, opts = {}) {
+  const headSha = opts.headSha ?? null;
+  const requiredContexts = uniqueSorted(
+    Array.isArray(opts.requiredContexts) ? opts.requiredContexts.map((c) => sanitizeField(c)) : [],
+  );
+  const requiredSet = new Set(requiredContexts);
+  const enriched = (Array.isArray(statuses) ? statuses : []).map((entry) =>
+    enrichCheckStatus(entry, { headSha, requiredContexts: requiredSet }),
+  );
+  const byContext = new Map();
+  for (const status of enriched) {
+    if (status.context) byContext.set(status.context, status);
+  }
+
+  const failed_contexts = [];
+  const pending_contexts = [];
+  const stale_contexts = [];
+  for (const status of enriched) {
+    if (!status.context) continue;
+    if (status.stale === true) stale_contexts.push(status.context);
+    if (status.state === 'failure') failed_contexts.push(status.context);
+    if (status.state === 'pending') pending_contexts.push(status.context);
+  }
+
+  const missing_required_contexts = [];
+  for (const context of requiredContexts) {
+    if (!byContext.has(context)) missing_required_contexts.push(context);
+  }
+
+  return {
+    statuses: enriched,
+    required_contexts: requiredContexts,
+    missing_required_contexts: uniqueSorted(missing_required_contexts),
+    failed_contexts: uniqueSorted(failed_contexts),
+    pending_contexts: uniqueSorted(pending_contexts),
+    stale_contexts: uniqueSorted(stale_contexts),
+  };
+}
+
+/**
+ * @param {{ forge_source_sha: string, check_conclusion: string, checks_truncated?: boolean, statuses?: object[], required_contexts?: string[] }} body
+ */
+export function buildPrChecksBody(body) {
+  const diagnostics = buildCheckDiagnostics(body.statuses ?? [], {
+    headSha: body.forge_source_sha,
+    requiredContexts: body.required_contexts ?? [],
+  });
+  return {
+    forge_source_sha: body.forge_source_sha,
+    check_conclusion: body.check_conclusion,
+    checks_truncated: body.checks_truncated === true,
+    statuses: diagnostics.statuses,
+    required_contexts: diagnostics.required_contexts,
+    missing_required_contexts: diagnostics.missing_required_contexts,
+    failed_contexts: diagnostics.failed_contexts,
+    pending_contexts: diagnostics.pending_contexts,
+    stale_contexts: diagnostics.stale_contexts,
+  };
+}