@remogram/core 0.1.0-beta.2 → 0.1.0-beta.3

package/auth-classes.js

@@ -11,6 +11,8 @@ const AUTH_CLASS_VALUES = new Set(Object.values(AUTH_CLASS));
 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,

package/caps.js

@@ -2,6 +2,10 @@ 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';
 
+/** 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;
+
 export function getEffectiveIngestMaxBytes() {
   const raw = process.env[FORGE_INGEST_MAX_BYTES_ENV];
   if (raw == null || raw === '') {
@@ -20,6 +24,30 @@ export function forgeIngestCapabilityFacts() {
   return { forge_ingest_cap_bytes: bytes };
 }
 
+/**
+ * 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',
+    },
+  };
+}
+
 export function capText(text, maxBytes = DEFAULT_MAX_BYTES) {
   if (!text) return { text: '', truncated: false, bytes: 0 };
   const buf = Buffer.from(text, 'utf8');

package/check-pagination.js

@@ -0,0 +1,138 @@
+import { ERROR_CODES } from './contracts/errors.js';
+import { DEFAULT_CHECK_STATUS_PAGE_SIZE, MAX_CHECK_STATUS_PAGES } from './caps.js';
+
+function isOversizedIngestError(err) {
+  return err?.forgeError?.code === ERROR_CODES.OVERSIZED_RAW_OUTPUT;
+}
+
+export function withPerPageParam(url, limit) {
+  const parsed = new URL(url);
+  parsed.searchParams.set('per_page', String(limit));
+  return parsed.toString();
+}
+
+export function withLimitParam(url, limit) {
+  const parsed = new URL(url);
+  parsed.searchParams.set('limit', String(limit));
+  return parsed.toString();
+}
+
+/**
+ * Retry fetch with halved page size when raw ingest exceeds cap.
+ * @template T
+ * @param {(url: string) => Promise<T>} fetchFn
+ * @param {(limit: number) => string} buildUrl
+ * @param {number} [initialLimit]
+ */
+export async function fetchWithIngestPageBackoff(
+  fetchFn,
+  buildUrl,
+  initialLimit = DEFAULT_CHECK_STATUS_PAGE_SIZE,
+) {
+  let limit = initialLimit;
+  while (true) {
+    try {
+      return await fetchFn(buildUrl(limit));
+    } catch (err) {
+      if (isOversizedIngestError(err) && limit > 1) {
+        limit = Math.max(1, Math.floor(limit / 2));
+        continue;
+      }
+      throw err;
+    }
+  }
+}
+
+/**
+ * Fetch one offset page with ingest-cap backoff.
+ * @template T
+ * @param {(opts: { page: number, limit: number }) => Promise<unknown[]>} fetchPage
+ * @param {number} page
+ * @param {number} initialLimit
+ * @returns {Promise<{ items: unknown[], usedLimit: number }>}
+ */
+export async function fetchPageWithIngestBackoff(fetchPage, page, initialLimit) {
+  let usedLimit = initialLimit;
+  const items = await fetchWithIngestPageBackoff(
+    async (limit) => {
+      usedLimit = limit;
+      const pageItems = await fetchPage({ page, limit });
+      return Array.isArray(pageItems) ? pageItems : [];
+    },
+    (limit) => limit,
+    initialLimit,
+  );
+  return { items, usedLimit };
+}
+
+/**
+ * Offset/limit check-status pagination with ingest-cap backoff.
+ * @param {{ fetchPage: (opts: { page: number, limit: number }) => Promise<unknown[]>, pageSize?: number, maxPages?: number }} opts
+ */
+export async function paginateCheckStatusPages({
+  fetchPage,
+  pageSize = DEFAULT_CHECK_STATUS_PAGE_SIZE,
+  maxPages = MAX_CHECK_STATUS_PAGES,
+}) {
+  const all = [];
+  let truncated = false;
+  let activeLimit = pageSize;
+  for (let page = 1; page <= maxPages; page += 1) {
+    const { items: pageItems, usedLimit } = await fetchPageWithIngestBackoff(
+      fetchPage,
+      page,
+      activeLimit,
+    );
+    activeLimit = usedLimit;
+    all.push(...pageItems);
+    if (pageItems.length < usedLimit) {
+      break;
+    }
+    if (page === maxPages) {
+      truncated = true;
+      break;
+    }
+  }
+  return { items: all, truncated };
+}
+
+/**
+ * Offset/limit open-list pagination with ingest-cap backoff and optional list cap.
+ * listLimit bounds request size per page; callers slice returned items when enforcing a hard cap.
+ * @param {{ fetchPage: (opts: { page: number, limit: number }) => Promise<unknown[]>, pageSize: number, listLimit?: number | null, maxPages?: number, maxPagesTruncatesWithLimit?: boolean }} opts
+ * @returns {Promise<{ items: unknown[], list_truncated: boolean }>}
+ */
+export async function paginateOffsetListPages({
+  fetchPage,
+  pageSize,
+  listLimit = null,
+  maxPages = MAX_CHECK_STATUS_PAGES,
+  maxPagesTruncatesWithLimit = false,
+}) {
+  const all = [];
+  let listTruncated = false;
+  let activeLimit = pageSize;
+  for (let page = 1; page <= maxPages; page += 1) {
+    const remaining = listLimit != null ? Math.max(listLimit - all.length, 0) : activeLimit;
+    if (listLimit != null && remaining === 0) break;
+    const requestLimit = listLimit != null ? Math.min(activeLimit, remaining) : activeLimit;
+    const { items, usedLimit } = await fetchPageWithIngestBackoff(fetchPage, page, requestLimit);
+    activeLimit = usedLimit;
+    all.push(...items);
+    if (items.length < usedLimit) break;
+    if (listLimit != null) {
+      if (all.length >= listLimit) {
+        listTruncated = items.length >= usedLimit;
+        break;
+      }
+      if (maxPagesTruncatesWithLimit && page === maxPages) {
+        listTruncated = true;
+        break;
+      }
+    } else if (page === maxPages) {
+      listTruncated = true;
+      break;
+    }
+  }
+  return { items: all, list_truncated: listTruncated };
+}

package/contracts/errors.js

@@ -11,6 +11,7 @@ export const ERROR_CODES = {
   CONFIG_NOT_FOUND: 'config_not_found',
   INVALID_ARGS: 'invalid_args',
   API_ERROR: 'api_error',
+  PR_NOT_OPEN: 'pr_not_open',
   REMOTE_INFER_FAILED: 'remote_infer_failed',
 };
 

package/contracts/observer-fact-inventory.js

@@ -0,0 +1,62 @@
+/**
+ * Remogram fact requirements for Topogram branch-workcycle observer snapshots.
+ * Observer proto today captures remogram repo status only; semantic-diff consumers
+ * may compose additional read-only fact packets listed here.
+ *
+ * @see ../topogram/tools/branch-workcycle/observer-snapshot.sh
+ * @see topo/sdlc/acceptance_criteria/semantic_diff_fact_inventory.tg ac_semantic_diff_observer_facts
+ */
+
+import { FACT_INVENTORY_PACKET_TYPES, V1_READ_PLAN_COMMANDS } from './semantic-diff-facts.js';
+
+/** CLI/MCP surface entries observer consumers may call (read-only). */
+export const OBSERVER_REMOGRAM_COMMANDS = Object.freeze([
+  { command: 'repo status', mcp_tool: 'repo_status', read_only: true, observer_proto: true },
+  { command: 'refs inventory', mcp_tool: 'ref_inventory', read_only: true, observer_proto: false },
+  { command: 'cr inventory', mcp_tool: 'cr_inventory', read_only: true, observer_proto: false },
+  { command: 'refs compare', mcp_tool: 'ref_compare', read_only: true, observer_proto: false },
+  { command: 'pr view', mcp_tool: 'pr_status', read_only: true, observer_proto: false },
+  { command: 'pr checks', mcp_tool: 'pr_checks', read_only: true, observer_proto: false },
+  { command: 'merge plan', mcp_tool: 'merge_plan', read_only: true, observer_proto: false },
+  { command: 'sync plan', mcp_tool: 'sync_plan', read_only: true, observer_proto: false },
+  { command: 'provider capabilities', mcp_tool: 'provider_capabilities', read_only: true, observer_proto: false },
+  { command: 'doctor', mcp_tool: 'doctor', read_only: true, observer_proto: false },
+]);
+
+/** Fact inventory packet types for semantic-diff / branch-workcycle composition. */
+export const OBSERVER_FACT_INVENTORY_PACKETS = Object.freeze([
+  {
+    packet_type: FACT_INVENTORY_PACKET_TYPES.REF_INVENTORY,
+    command: 'refs inventory',
+    mcp_tool: 'ref_inventory',
+    read_only: true,
+  },
+  {
+    packet_type: FACT_INVENTORY_PACKET_TYPES.CR_INVENTORY_SLICE,
+    command: 'cr inventory',
+    mcp_tool: 'cr_inventory',
+    read_only: true,
+  },
+]);
+
+/** Commands captured directly by observer-snapshot.sh today. */
+export function observerProtoRemogramCommands() {
+  return OBSERVER_REMOGRAM_COMMANDS.filter((entry) => entry.observer_proto);
+}
+
+/** Extended fact commands for semantic-diff inventory beyond the proto script. */
+export function semanticDiffFactCommands() {
+  return OBSERVER_REMOGRAM_COMMANDS.filter((entry) => !entry.observer_proto);
+}
+
+/** All v1 read/plan commands remain authoritative alongside fact inventory. */
+export function allObserverEligibleCommands() {
+  return V1_READ_PLAN_COMMANDS.map((command) => {
+    const entry = OBSERVER_REMOGRAM_COMMANDS.find((c) => c.command === command);
+    return {
+      command,
+      mcp_tool: entry?.mcp_tool ?? null,
+      read_only: entry?.read_only ?? true,
+    };
+  });
+}

package/contracts/semantic-diff-facts.js

@@ -0,0 +1,128 @@
+/**
+ * Semantic diff fact inventory contract (wave 1 — registry and trust boundaries).
+ * Command implementations land in waves 2–6 per plan_semantic_diff_fact_inventory.
+ *
+ * @see topo/sdlc/decisions/semantic_diff_fact_layer.tg
+ * @see topo/sdlc/decisions/packet_trust_doctrine.tg
+ */
+
+import { forgePacket, FORBIDDEN_PACKET_KEYS, SCHEMA_VERSION } from './envelope.js';
+
+/** Authoritative v1 read/plan surface today. Fact inventory extends; does not replace. */
+export const V1_READ_PLAN_COMMANDS = Object.freeze([
+  'repo status',
+  'refs compare',
+  'refs inventory',
+  'cr inventory',
+  'pr view',
+  'pr checks',
+  'merge plan',
+  'sync plan',
+  'provider capabilities',
+  'doctor',
+]);
+
+/**
+ * Planned fact-inventory packet types (not emitted until wave 2+ commands ship).
+ * All use schema_version 1 envelope discipline via forgePacket.
+ */
+export const FACT_INVENTORY_PACKET_TYPES = Object.freeze({
+  REF_INVENTORY: 'ref_inventory',
+  CR_INVENTORY_SLICE: 'cr_inventory_slice',
+});
+
+/** Trusted structural envelope on every remogram packet (authoritative for agents). */
+export const TRUSTED_ENVELOPE_FIELDS = Object.freeze([
+  'type',
+  'schema_version',
+  'provider_id',
+  'remote_name',
+  'repo_id',
+  'observed_at',
+  'ok',
+]);
+
+/**
+ * Normalized enum and boolean body fields agents may treat as structural facts
+ * (not forge prose). Provider-specific strings that are normalized to enums
+ * belong here; raw forge copy does not.
+ */
+export const TRUSTED_NORMALIZED_BODY_FIELDS = Object.freeze({
+  mergeability: true,
+  check_conclusion: true,
+  checks_conclusion: true,
+  state: true,
+  truncated: true,
+  list_truncated: true,
+  checks_truncated: true,
+  entry_count: true,
+  mergeability_confidence: true,
+  write_support: true,
+  diverged: true,
+  auth_present: true,
+});
+
+/**
+ * String leaves copied from forge or git resolution that remain semantically
+ * untrusted per decision_packet_trust_doctrine. Structurally sanitized only.
+ */
+export const FORGE_SOURCED_STRING_LEAVES = Object.freeze({
+  repo_status: ['default_branch', 'auth_env', 'capabilities'],
+  ref_compare: ['base_ref', 'head_ref', 'base_sha', 'head_sha'],
+  pr_status: ['url', 'title', 'base_ref', 'head_ref', 'base_sha', 'head_sha'],
+  pr_checks: ['head_sha', 'statuses[].context', 'statuses[].description', 'statuses[].target_url'],
+  merge_plan: ['blockers[].message', 'blockers[].context'],
+  sync_plan: ['remote', 'local_sha', 'remote_sha', 'blockers[].message'],
+  ref_inventory: ['refs[].name', 'refs[].sha', 'default_ref'],
+  cr_inventory_slice: [
+    'entries[].url',
+    'entries[].title',
+    'entries[].base_ref',
+    'entries[].head_ref',
+    'entries[].base_sha',
+    'entries[].head_sha',
+    'entries[].head_reconcile.local_head_sha',
+    'entries[].head_reconcile.head_sha',
+    'entries[].checks[].context',
+    'entries[].checks[].description',
+  ],
+});
+
+/** Keys that must never appear in remogram output (Topogram SDLC/workflow concepts). */
+export { FORBIDDEN_PACKET_KEYS };
+
+/**
+ * Documented body shapes for planned fact inventory packets (wave 2+).
+ * Used by contract tests and provider normalization; not emitted in wave 1.
+ */
+export const FACT_INVENTORY_BODY_SHAPES = Object.freeze({
+  [FACT_INVENTORY_PACKET_TYPES.REF_INVENTORY]: {
+    refs: 'array<{ name: string, sha: string, kind?: string, is_default?: boolean }>',
+    default_ref: 'string optional',
+    ancestry_hints: 'array<{ base_ref: string, head_ref: string, ahead_by?: number, behind_by?: number }> optional',
+  },
+  [FACT_INVENTORY_PACKET_TYPES.CR_INVENTORY_SLICE]: {
+    entries:
+      'array<{ pr_number: number, url?: string, title?: string, state?: string, base_ref?: string, head_ref?: string, base_sha?: string, head_sha?: string, mergeability?: string, checks_conclusion?: string, checks_truncated?: boolean, blockers?: array, head_reconcile?: { stale: boolean, local_head_sha?: string, head_sha?: string } }>',
+    entry_count: 'number',
+    /** true when list cap applied (entry_count > limit), not missing entries */
+    truncated: 'boolean',
+    list_truncated: 'boolean',
+    entries_skipped:
+      'array<{ pr_number: number, error_code: pr_not_open | api_error | oversized_raw_output | ... }> optional',
+    slice_ref: 'string optional',
+  },
+});
+
+/**
+ * Build a fact-inventory packet body through the standard envelope gate.
+ * Throws if body contains forbidden Topogram workflow keys.
+ */
+export function forgeFactInventoryPacket(type, context, body = {}, error = null) {
+  if (!Object.values(FACT_INVENTORY_PACKET_TYPES).includes(type)) {
+    throw new Error(`Unknown fact inventory packet type: ${type}`);
+  }
+  return forgePacket(type, context, body, error);
+}
+
+export { SCHEMA_VERSION };

package/cr-inventory.js

@@ -0,0 +1,111 @@
+import { sanitizeField } from './caps.js';
+import { ERROR_CODES, forgeError } from './contracts/errors.js';
+import { mergeBlockersFromFacts, isOpenPrState } from './merge-blockers.js';
+import { staleHeadDetails } from './pr-head-reconcile.js';
+
+export const DEFAULT_CR_INVENTORY_LIMIT = 50;
+
+export function normalizeCrInventoryLimit(value) {
+  if (value == null || value === '') return DEFAULT_CR_INVENTORY_LIMIT;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n <= 0) {
+    throw Object.assign(new Error('Invalid cr inventory limit'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--limit must be a positive integer'),
+    });
+  }
+  return n;
+}
+
+async function resolveOpenPullList(provider, ctx, limit) {
+  const listOpts = { limit };
+  if (typeof provider.listOpenPullsWithMeta === 'function') {
+    return provider.listOpenPullsWithMeta(ctx, listOpts);
+  }
+  const numbers = await provider.listOpenPulls(ctx, listOpts);
+  return { numbers, list_truncated: false };
+}
+
+function skipErrorCode(err) {
+  if (err?.forgeError?.code) return err.forgeError.code;
+  return ERROR_CODES.API_ERROR;
+}
+
+export function buildHeadReconcile(ctx, view) {
+  const details = staleHeadDetails(
+    ctx.cwd,
+    ctx.config?.remote ?? ctx.remoteName,
+    view.head_ref,
+    view.head_sha,
+  );
+  if (!details) return { stale: false };
+  return {
+    stale: true,
+    local_head_sha: details.local_head_sha,
+    head_sha: details.head_sha,
+  };
+}
+
+/**
+ * Compose one CR inventory entry from pr view and checks facts.
+ */
+export function buildCrInventoryEntry(ctx, view, checks) {
+  const entry = {
+    pr_number: view.pr_number,
+    url: view.url,
+    title: view.title,
+    state: view.state,
+    base_ref: view.base_ref,
+    head_ref: view.head_ref,
+    mergeability: view.mergeability,
+    checks_conclusion: checks.check_conclusion,
+    checks_truncated: checks.checks_truncated === true,
+    blockers: mergeBlockersFromFacts(view, checks),
+    head_reconcile: buildHeadReconcile(ctx, view),
+  };
+  if (view.base_sha) entry.base_sha = view.base_sha;
+  if (view.head_sha) entry.head_sha = view.head_sha;
+  return entry;
+}
+
+/**
+ * Aggregate open change requests into a semantic-diff-oriented inventory slice.
+ * @param {object} ctx forge context
+ * @param {object} provider must expose listOpenPulls, prView, prChecks
+ * @param {{ slice_ref?: string, limit?: number }} [opts]
+ */
+export async function crInventory(ctx, provider, opts = {}) {
+  const limit = normalizeCrInventoryLimit(opts.limit);
+  const { numbers, list_truncated: listTruncated } = await resolveOpenPullList(
+    provider,
+    ctx,
+    limit,
+  );
+  const entryCount = numbers.length;
+  const selected = numbers.slice(0, limit);
+  const entries = [];
+  const entries_skipped = [];
+  for (const number of selected) {
+    try {
+      const view = await provider.prView(ctx, { number });
+      if (!isOpenPrState(view.state)) {
+        entries_skipped.push({ pr_number: number, error_code: ERROR_CODES.PR_NOT_OPEN });
+        continue;
+      }
+      const checks = await provider.prChecks(ctx, { number });
+      entries.push(buildCrInventoryEntry(ctx, view, checks));
+    } catch (err) {
+      entries_skipped.push({
+        pr_number: number,
+        error_code: skipErrorCode(err),
+      });
+    }
+  }
+  return {
+    entries,
+    ...(entries_skipped.length ? { entries_skipped } : {}),
+    entry_count: entryCount,
+    truncated: entryCount > selected.length,
+    list_truncated: listTruncated,
+    ...(opts.slice_ref ? { slice_ref: sanitizeField(opts.slice_ref) } : {}),
+  };
+}

package/http.js

@@ -60,12 +60,46 @@ export function parseLinkHeader(linkHeader) {
   if (!linkHeader) return {};
   const links = {};
   for (const segment of String(linkHeader).split(',')) {
-    const match = segment.trim().match(/^<([^>]+)>;\s*rel="([^"]+)"/);
-    if (match) links[match[2]] = match[1];
+    const match = segment.trim().match(/^<([^>]+)>;\s*rel=(?:"([^"]+)"|'([^']+)')/);
+    if (match) links[(match[2] ?? match[3]).toLowerCase()] = match[1];
   }
   return links;
 }
 
+function normalizePathname(pathname) {
+  if (pathname.length > 1 && pathname.endsWith('/')) {
+    return pathname.replace(/\/+$/, '') || '/';
+  }
+  return pathname;
+}
+
+/** Reject Link rel=next URLs that leave the configured API origin (token exfiltration guard). */
+export function isTrustedPaginationUrl(trustedOrigin, url, resolveBase) {
+  try {
+    if (resolveBase == null || resolveBase === '') {
+      return false;
+    }
+    const baseResolved = new URL(resolveBase);
+    if (baseResolved.username !== '' || baseResolved.password !== '') {
+      return false;
+    }
+    const resolved = new URL(url, resolveBase);
+    if (resolved.username !== '' || resolved.password !== '') {
+      return false;
+    }
+    if (resolved.origin !== trustedOrigin) {
+      return false;
+    }
+    const basePath = normalizePathname(new URL(resolveBase).pathname);
+    if (normalizePathname(resolved.pathname) !== basePath) {
+      return false;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export async function fetchJsonWithMeta(
   url,
   options = {},

package/index.js

@@ -1,4 +1,20 @@
 export { SCHEMA_VERSION, PACKET_TYPES, forgePacket, forgeErrorPacket, unknownForgeContext, FORBIDDEN_PACKET_KEYS } from './contracts/envelope.js';
+export {
+  V1_READ_PLAN_COMMANDS,
+  FACT_INVENTORY_PACKET_TYPES,
+  TRUSTED_ENVELOPE_FIELDS,
+  TRUSTED_NORMALIZED_BODY_FIELDS,
+  FORGE_SOURCED_STRING_LEAVES,
+  FACT_INVENTORY_BODY_SHAPES,
+  forgeFactInventoryPacket,
+} from './contracts/semantic-diff-facts.js';
+export {
+  OBSERVER_REMOGRAM_COMMANDS,
+  OBSERVER_FACT_INVENTORY_PACKETS,
+  observerProtoRemogramCommands,
+  semanticDiffFactCommands,
+  allObserverEligibleCommands,
+} from './contracts/observer-fact-inventory.js';
 export { ERROR_CODES, forgeError } from './contracts/errors.js';
 export {
   capText,
@@ -8,11 +24,25 @@ export {
   DEFAULT_MAX_BYTES,
   DEFAULT_FIELD_MAX_BYTES,
   FORGE_INGEST_MAX_BYTES_ENV,
+  DEFAULT_CHECK_STATUS_PAGE_SIZE,
+  MAX_CHECK_STATUS_PAGES,
   getEffectiveIngestMaxBytes,
   forgeIngestCapabilityFacts,
+  checkPaginationCapabilityFacts,
 } from './caps.js';
+export {
+  paginateCheckStatusPages,
+  paginateOffsetListPages,
+  fetchWithIngestPageBackoff,
+  fetchPageWithIngestBackoff,
+  withPerPageParam,
+  withLimitParam,
+} from './check-pagination.js';
 export { assertGitRef, assertGitRemote } from './git-args.js';
 export { gitRevParse, gitCurrentBranch, gitAheadBehind, gitRepoRoot } from './git-local.js';
+export { buildRefInventoryBody, refsInventory } from './ref-inventory.js';
+export { buildCrInventoryEntry, buildHeadReconcile, crInventory, DEFAULT_CR_INVENTORY_LIMIT, normalizeCrInventoryLimit } from './cr-inventory.js';
+export { mergeBlockersFromFacts, isOpenPrState } from './merge-blockers.js';
 export {
   localHeadShaForPr,
   staleHeadDetails,
@@ -32,7 +62,14 @@ export {
   assertForgeReady,
   forgeContext,
 } from './resolve.js';
-export { fetchWithTimeout, fetchJson, fetchJsonWithMeta, parseLinkHeader, fetchTextCapped } from './http.js';
+export {
+  fetchWithTimeout,
+  fetchJson,
+  fetchJsonWithMeta,
+  parseLinkHeader,
+  isTrustedPaginationUrl,
+  fetchTextCapped,
+} from './http.js';
 export {
   AUTH_CLASS,
   API_PROVIDER_COMMAND_AUTH,

package/merge-blockers.js

@@ -0,0 +1,18 @@
+/**
+ * Derive merge blockers from already-fetched PR view and checks facts.
+ * Shared by merge plan and cr inventory aggregation.
+ */
+export function isOpenPrState(state) {
+  return String(state ?? '').toLowerCase() === 'open';
+}
+
+export function mergeBlockersFromFacts(view, checks) {
+  const blockers = [];
+  if (view.mergeability === 'conflicted') blockers.push('merge_conflict');
+  if (!isOpenPrState(view.state)) blockers.push('pr_not_open');
+  if (checks.checks_truncated === true) blockers.push('checks_incomplete');
+  if (checks.check_conclusion === 'failure') blockers.push('checks_failed');
+  if (checks.check_conclusion === 'missing') blockers.push('checks_missing');
+  if (checks.check_conclusion === 'pending') blockers.push('checks_pending');
+  return blockers;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remogram/core",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.3",
   "description": "Remogram forge envelope, config, caps, and HTTP utilities",
   "type": "module",
   "license": "MIT",

package/ref-inventory.js

@@ -0,0 +1,98 @@
+import { execFileSync } from 'node:child_process';
+import { sanitizeField } from './caps.js';
+import { gitAheadBehind, gitCurrentBranch, gitRevParse } from './git-local.js';
+
+const GIT_TIMEOUT_MS = 10_000;
+
+function gitExec(cwd, args) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', timeout: GIT_TIMEOUT_MS }).trim();
+}
+
+function listRefs(cwd) {
+  try {
+    const out = gitExec(cwd, [
+      'for-each-ref',
+      '--format=%(refname:short)|%(objectname)|%(refname)',
+      'refs/heads',
+      'refs/remotes',
+    ]);
+    if (!out) return [];
+    return out.split('\n').filter(Boolean).map((line) => {
+      const [name, sha, fullRef] = line.split('|');
+      const kind = fullRef.startsWith('refs/heads/') ? 'branch' : 'remote';
+      return { name, sha, kind };
+    });
+  } catch {
+    return [];
+  }
+}
+
+function resolveDefaultRef(cwd, remoteName) {
+  try {
+    const sym = gitExec(cwd, ['symbolic-ref', `refs/remotes/${remoteName}/HEAD`]);
+    const prefix = `refs/remotes/${remoteName}/`;
+    if (sym.startsWith(prefix)) {
+      return sym.slice(prefix.length);
+    }
+    return sym.replace(/^refs\/remotes\/[^/]+\//, '');
+  } catch {
+    return null;
+  }
+}
+
+function buildAncestryHints(cwd, defaultRef, refs) {
+  if (!defaultRef) return [];
+  const defaultEntry = refs.find((r) => r.name === defaultRef || r.name === `origin/${defaultRef}`);
+  const headBranch = gitCurrentBranch(cwd);
+  if (!headBranch || headBranch === 'HEAD') return [];
+  const headEntry = refs.find((r) => r.name === headBranch);
+  if (!defaultEntry?.sha || !headEntry?.sha || defaultEntry.sha === headEntry.sha) return [];
+
+  const counts = gitAheadBehind(cwd, defaultEntry.sha, headEntry.sha);
+  if (counts.ahead_by == null && counts.behind_by == null) return [];
+
+  return [
+    {
+      base_ref: sanitizeField(defaultRef),
+      head_ref: sanitizeField(headBranch),
+      ahead_by: counts.ahead_by,
+      behind_by: counts.behind_by,
+    },
+  ];
+}
+
+/**
+ * Build provider-neutral ref inventory body from local git.
+ * @param {string} cwd repository working directory (git root after config load)
+ * @param {string} [remoteName]
+ */
+export function buildRefInventoryBody(cwd, remoteName = 'origin') {
+  const refs = listRefs(cwd).map((ref) => ({
+    name: sanitizeField(ref.name),
+    sha: ref.sha,
+    kind: ref.kind,
+    is_default: false,
+  }));
+
+  const defaultRef = resolveDefaultRef(cwd, remoteName);
+  if (defaultRef) {
+    for (const ref of refs) {
+      if (ref.name === defaultRef || ref.name === `${remoteName}/${defaultRef}`) {
+        ref.is_default = true;
+      }
+    }
+  }
+
+  const ancestry_hints = buildAncestryHints(cwd, defaultRef, refs);
+
+  return {
+    refs,
+    ...(defaultRef ? { default_ref: sanitizeField(defaultRef) } : {}),
+    ...(ancestry_hints.length > 0 ? { ancestry_hints } : {}),
+  };
+}
+
+export async function refsInventory(ctx) {
+  const remoteName = ctx.config.remote || 'origin';
+  return buildRefInventoryBody(ctx.cwd, remoteName);
+}

package/stub-provider.js

@@ -23,6 +23,8 @@ export function createStubProvider(id) {
     providerCapabilities,
     repoStatus: unsupported,
     refsCompare: unsupported,
+    refsInventory: unsupported,
+    crInventory: unsupported,
     prView: unsupported,
     prChecks: unsupported,
     mergePlan: unsupported,