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

package/contracts/semantic-diff-facts.js

@@ -0,0 +1,137 @@
+/**
+ * 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',
+]);
+
+/** v1 write surface (Gitea cr open only in first slice). */
+export const V1_WRITE_COMMANDS = Object.freeze(['cr open']);
+
+/**
+ * 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,
+  slice_sort: true,
+  entry_count: true,
+  mergeability_confidence: true,
+  write_support: true,
+  diverged: true,
+  auth_present: true,
+  reused_existing: true,
+  idempotency_scan: 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'],
+  change_request_opened: ['url', 'title', 'head', 'base'],
+  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 (external planning/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',
+    /** normalized slice sort preset applied to open-list resolution */
+    slice_sort: 'string',
+    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 workflow/planning-tool 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,118 @@
+import { sanitizeField } from './caps.js';
+import { ERROR_CODES, forgeError } from './contracts/errors.js';
+import { mergeBlockersFromFacts, isOpenPrState } from './merge-blockers.js';
+import {
+  DEFAULT_CR_INVENTORY_SLICE_SORT,
+  normalizeCrInventorySort,
+} from './open-pull-list.js';
+import { staleHeadDetails } from './pr-head-reconcile.js';
+
+export const DEFAULT_CR_INVENTORY_LIMIT = 50;
+/** Default bound when `--limit` is omitted (keeps forge ingest under cap on large repos). */
+export const DEFAULT_CR_INVENTORY_SAFE_LIMIT = 3;
+
+export function normalizeCrInventoryLimit(value) {
+  if (value == null || value === '') return DEFAULT_CR_INVENTORY_SAFE_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, entryLimit, sliceSort) {
+  if (typeof provider.listOpenPullsWithMeta === 'function') {
+    return provider.listOpenPullsWithMeta(ctx, { retain_max: entryLimit, sort: sliceSort });
+  }
+  const numbers = await provider.listOpenPulls(ctx, {});
+  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, sort?: string }} [opts]
+ */
+export async function crInventory(ctx, provider, opts = {}) {
+  const limit = normalizeCrInventoryLimit(opts.limit);
+  const sliceSort = normalizeCrInventorySort(opts.sort);
+  const {
+    numbers,
+    list_truncated: listTruncated,
+    entry_count: providerEntryCount,
+  } = await resolveOpenPullList(provider, ctx, limit, sliceSort);
+  const entryCount = providerEntryCount ?? 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,
+    slice_sort: sliceSort ?? DEFAULT_CR_INVENTORY_SLICE_SORT,
+    ...(opts.slice_ref ? { slice_ref: sanitizeField(opts.slice_ref) } : {}),
+  };
+}

package/cr-open.js

@@ -0,0 +1,33 @@
+import { sanitizeField, sanitizeUrl } from './caps.js';
+import { ERROR_CODES, forgeError } from './contracts/errors.js';
+
+/** Normalize Gitea pull create response into change_request_opened body fields. */
+export function buildChangeRequestOpenedBody(
+  pull,
+  { head, base, title },
+  { reusedExisting = false } = {},
+) {
+  const prNumber = Number(pull?.number);
+  if (!Number.isInteger(prNumber) || prNumber <= 0) {
+    throw Object.assign(new Error('Provider returned invalid pull number'), {
+      forgeError: forgeError(
+        ERROR_CODES.UNPARSEABLE_PROVIDER_OUTPUT,
+        'Provider returned invalid pull number',
+      ),
+    });
+  }
+  const resolvedTitle = reusedExisting
+    ? sanitizeField(pull?.title ?? title)
+    : sanitizeField(title ?? pull?.title);
+  const body = {
+    pr_number: prNumber,
+    url: sanitizeUrl(pull.html_url ?? pull.url),
+    head: sanitizeField(head),
+    base: sanitizeField(base),
+    title: resolvedTitle,
+  };
+  if (reusedExisting) {
+    body.reused_existing = true;
+  }
+  return body;
+}

package/git-local.js

@@ -43,3 +43,15 @@ export function gitAheadBehind(cwd, base, head) {
     return { ahead_by: null, behind_by: null };
   }
 }
+
+export function gitDiffNameOnly(cwd, base, head) {
+  assertGitRef(base, 'base');
+  assertGitRef(head, 'head');
+  try {
+    const out = gitExec(cwd, ['diff', '--name-only', base, head]);
+    if (!out) return [];
+    return out.split('\n').filter(Boolean);
+  } catch {
+    return null;
+  }
+}

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,5 +1,25 @@
 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 {
+  FORGE_ERROR_FIELD_ALLOWLIST,
+  normalizeForgeErrorFields,
+} from './contracts/forge-error-fields.js';
 export {
   capText,
   sanitizeField,
@@ -8,11 +28,70 @@ export {
   DEFAULT_MAX_BYTES,
   DEFAULT_FIELD_MAX_BYTES,
   FORGE_INGEST_MAX_BYTES_ENV,
+  DEFAULT_CHECK_STATUS_PAGE_SIZE,
+  MAX_CHECK_STATUS_PAGES,
+  DEFAULT_OPEN_PULL_LIST_PAGE_SIZE,
+  MAX_OPEN_PULL_IDEMPOTENCY_PAGES,
   getEffectiveIngestMaxBytes,
   forgeIngestCapabilityFacts,
+  checkPaginationCapabilityFacts,
+  idempotencyScanCapabilityFacts,
+  openPullListCapabilityFacts,
 } 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 { gitRevParse, gitCurrentBranch, gitAheadBehind, gitRepoRoot, gitDiffNameOnly } from './git-local.js';
+export { buildRefInventoryBody, refsInventory } from './ref-inventory.js';
+export { buildCrInventoryEntry, buildHeadReconcile, crInventory, DEFAULT_CR_INVENTORY_LIMIT, DEFAULT_CR_INVENTORY_SAFE_LIMIT, normalizeCrInventoryLimit } from './cr-inventory.js';
+export {
+  CR_INVENTORY_SLICE_SORTS,
+  DEFAULT_CR_INVENTORY_SLICE_SORT,
+  normalizeCrInventorySort,
+  parseTotalCountHeader,
+  isCrInventoryFastPathEligible,
+  forgeOrderAuthoritative,
+  validateFastPathPageLength,
+  isNumberSortFastPathEligible,
+  resolvePaginatedEntryCount,
+  resolveListTruncatedWithTrustedTotal,
+  isRecentCreatedFastPathEligible,
+  giteaRecentCreatedTailPage,
+  isNumberSortFullCollectRequired,
+  prepareGiteaOpenPullPageItems,
+  orderOpenPullNumbers,
+  buildOpenPullListMeta,
+  giteaOpenPullSortQuery,
+  gitlabOpenPullSortQuery,
+  githubOpenPullSortQuery,
+  appendSortQuery,
+} from './open-pull-list.js';
+export { buildChangeRequestOpenedBody } from './cr-open.js';
+export {
+  WRITE_COMMAND_IDS,
+  CONFIGURED_WRITE_COMMANDS,
+  writeCommandSchema,
+  assertWriteCommandConfigured,
+  isWriteCommandConfigured,
+} from './write-config.js';
+export { mergeBlockersFromFacts, isOpenPrState } from './merge-blockers.js';
+export {
+  resolveMergePlanPathScope,
+  buildMergePlanBody,
+  buildMergePlanBodyFromFacts,
+} from './merge-plan.js';
+export {
+  matchPathAllowlist,
+  isPathAllowed,
+  pathsOutsideAllowlist,
+  allPathsAllowed,
+} from './path-allowlist.js';
 export {
   localHeadShaForPr,
   staleHeadDetails,
@@ -32,7 +111,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,36 @@
+import { allPathsAllowed } from './path-allowlist.js';
+
+/**
+ * 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';
+}
+
+/**
+ * @param {object} view
+ * @param {object} checks
+ * @param {{ allowed_paths?: string[], changed_paths?: string[] | null }} [pathScope]
+ */
+export function mergeBlockersFromFacts(view, checks, pathScope = {}) {
+  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');
+
+  const allowedPaths = pathScope.allowed_paths;
+  if (Array.isArray(allowedPaths) && allowedPaths.length > 0) {
+    const changedPaths = pathScope.changed_paths;
+    if (changedPaths == null) {
+      blockers.push('changed_paths_unavailable');
+    } else if (!allPathsAllowed(allowedPaths, changedPaths)) {
+      blockers.push('path_scope_violation');
+    }
+  }
+
+  return blockers;
+}

package/merge-plan.js

@@ -0,0 +1,34 @@
+import { gitDiffNameOnly } from './git-local.js';
+import { mergeBlockersFromFacts } from './merge-blockers.js';
+
+function normalizeAllowedPaths(allowedPaths) {
+  if (!Array.isArray(allowedPaths)) return null;
+  const normalized = allowedPaths.filter((entry) => typeof entry === 'string' && entry.length > 0);
+  return normalized.length > 0 ? normalized : null;
+}
+
+export function resolveMergePlanPathScope(ctx, view, opts = {}) {
+  const allowedPaths = normalizeAllowedPaths(opts.allowed_paths);
+  if (!allowedPaths) {
+    return { allowed_paths: null, changed_paths: null };
+  }
+  if (!view.base_sha || !view.head_sha) {
+    return { allowed_paths: allowedPaths, changed_paths: null };
+  }
+  const changedPaths = gitDiffNameOnly(ctx.cwd, view.base_sha, view.head_sha);
+  return { allowed_paths: allowedPaths, changed_paths: changedPaths };
+}
+
+export function buildMergePlanBody(view, checks, pathScope = {}) {
+  return {
+    pr_number: view.pr_number,
+    mergeability: view.mergeability,
+    checks_conclusion: checks.check_conclusion,
+    blockers: mergeBlockersFromFacts(view, checks, pathScope),
+  };
+}
+
+export function buildMergePlanBodyFromFacts(ctx, view, checks, opts = {}) {
+  const pathScope = resolveMergePlanPathScope(ctx, view, opts);
+  return buildMergePlanBody(view, checks, pathScope);
+}