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

package/check-pagination.js

@@ -0,0 +1,216 @@
+import { ERROR_CODES } from './contracts/errors.js';
+import { DEFAULT_CHECK_STATUS_PAGE_SIZE, MAX_CHECK_STATUS_PAGES } from './caps.js';
+import { resolvePaginatedEntryCount } from './open-pull-list.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 };
+}
+
+/**
+ * When a full page lands on maxPages, probe one item on the next page to distinguish
+ * end-of-list from truncation.
+ * @template T
+ * @param {(opts: { page: number, limit: number }) => Promise<unknown[]>} fetchPage
+ * @param {number} page
+ * @param {number} maxPages
+ * @returns {Promise<boolean>} true when list is truncated (more items exist)
+ */
+async function probeNextPageHasItems(fetchPage, page, maxPages) {
+  if (page > maxPages) return true;
+  const { items: probeItems } = await fetchPageWithIngestBackoff(fetchPage, page + 1, 1);
+  return probeItems.length > 0;
+}
+
+/**
+ * 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, retainMax?: number | null, trustedEntryCount?: number | null, seededFirstPage?: { items: unknown[], usedLimit: number } | null, startPage?: number, suppressFinalPageProbe?: boolean }} opts
+ * @returns {Promise<{ items: unknown[], list_truncated: boolean, walked_count: number, entry_count?: number }>}
+ */
+export async function paginateOffsetListPages({
+  fetchPage,
+  pageSize,
+  listLimit = null,
+  maxPages = MAX_CHECK_STATUS_PAGES,
+  maxPagesTruncatesWithLimit = false,
+  retainMax = null,
+  trustedEntryCount = null,
+  seededFirstPage = null,
+  startPage = 1,
+  suppressFinalPageProbe = false,
+}) {
+  const all = [];
+  let entryCount = 0;
+  let listTruncated = false;
+  let activeLimit = pageSize;
+
+  async function afterPage(page, items, usedLimit) {
+    entryCount += items.length;
+    if (retainMax != null) {
+      const space = Math.max(retainMax - all.length, 0);
+      if (space > 0) all.push(...items.slice(0, space));
+    } else {
+      all.push(...items);
+    }
+    if (items.length < usedLimit) {
+      if (
+        trustedEntryCount != null &&
+        trustedEntryCount > entryCount &&
+        page === 1 &&
+        page < maxPages
+      ) {
+        return false;
+      }
+      return true;
+    }
+    if (listLimit != null && all.length >= listLimit) {
+      listTruncated = await probeNextPageHasItems(fetchPage, page, maxPages);
+      return true;
+    }
+    if (listLimit != null) {
+      if (maxPagesTruncatesWithLimit && page === maxPages) {
+        listTruncated = true;
+        return true;
+      }
+    } else if (page === maxPages) {
+      if (suppressFinalPageProbe) {
+        listTruncated = items.length >= usedLimit;
+      } else {
+        listTruncated = await probeNextPageHasItems(fetchPage, page, maxPages);
+      }
+      return true;
+    }
+    return false;
+  }
+
+  let page = startPage;
+  if (seededFirstPage && startPage === 1) {
+    const { items, usedLimit } = seededFirstPage;
+    activeLimit = usedLimit;
+    if (await afterPage(1, items, usedLimit)) {
+      return {
+        items: all,
+        list_truncated: listTruncated,
+        walked_count: entryCount,
+        ...(retainMax != null || trustedEntryCount != null
+          ? { entry_count: resolvePaginatedEntryCount(trustedEntryCount, entryCount) }
+          : {}),
+      };
+    }
+    page = 2;
+    activeLimit = pageSize;
+  }
+
+  for (; 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;
+    if (await afterPage(page, items, usedLimit)) {
+      break;
+    }
+  }
+
+  return {
+    items: all,
+    list_truncated: listTruncated,
+    walked_count: entryCount,
+    ...(retainMax != null || trustedEntryCount != null
+      ? {
+          entry_count: resolvePaginatedEntryCount(trustedEntryCount, entryCount),
+        }
+      : {}),
+  };
+}

package/config-schema.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { writeCommandSchema } from './write-config.js';
 
 const providerSchema = z.enum([
   'gitea-api',
@@ -15,6 +16,18 @@ const repoSegmentSchema = z
     message: 'owner/repo must not contain /, .., or %',
   });
 
+const fieldMaxBytesSchema = z.union([
+  z.number().int().positive(),
+  z.null(),
+  z.literal('none'),
+]);
+
+export const forgeWritePolicySchema = z
+  .object({
+    field_max_bytes: fieldMaxBytesSchema.optional(),
+  })
+  .strict();
+
 export const configSchema = z
   .object({
     version: z.literal('1'),
@@ -23,6 +36,14 @@ export const configSchema = z
     owner: repoSegmentSchema,
     repo: repoSegmentSchema,
     baseUrl: z.string().url().optional(),
+    write_commands: z.array(writeCommandSchema).optional(),
+    forge_write_policy: forgeWritePolicySchema.optional(),
+    merge_policy: z
+      .object({
+        allow_missing_checks: z.boolean().optional(),
+        allow_pending_checks: z.boolean().optional(),
+      })
+      .optional(),
   })
   .strict();
 

package/contracts/envelope.js

@@ -1,4 +1,5 @@
 import { sanitizeField } from '../caps.js';
+import { normalizeForgeErrorFields } from './forge-error-fields.js';
 
 export const SCHEMA_VERSION = 1;
 
@@ -12,6 +13,16 @@ export const PACKET_TYPES = {
   PROVIDER_CAPABILITIES: 'provider_capabilities',
   PROVIDER_DOCTOR: 'provider_doctor',
   FORGE_ERROR: 'forge_error',
+  CHANGE_REQUEST_OPENED: 'change_request_opened',
+  ISSUE_OPENED: 'issue_opened',
+  COMMIT_STATUS_SET: 'commit_status_set',
+  PROVIDER_IDENTITY: 'provider_identity',
+  BRANCH_PROTECTION: 'branch_protection',
+  CR_FILES: 'cr_files',
+  CR_COMMENTS: 'cr_comments',
+  FORGE_CHANGES: 'forge_changes',
+  CR_MERGED: 'cr_merged',
+  CR_MERGE_BLOCKED: 'cr_merge_blocked',
 };
 
 export const FORBIDDEN_PACKET_KEYS = new Set([
@@ -29,7 +40,7 @@ function assertNoForbiddenKeys(value) {
   }
   for (const [key, nested] of Object.entries(value)) {
     if (FORBIDDEN_PACKET_KEYS.has(key)) {
-      throw new Error(`Forbidden Topogram concept in remogram output: ${key}`);
+      throw new Error(`Forbidden workflow/planning-tool key in remogram output: ${key}`);
     }
     assertNoForbiddenKeys(nested);
   }
@@ -49,17 +60,30 @@ export function forgePacket(type, context, body = {}, error = null) {
     ok: error == null,
   };
 
+  delete packet.base_url;
+  if (context.baseUrl) {
+    packet.base_url = context.baseUrl;
+  }
+
   if (error) {
     packet.error_code = error.code;
     packet.error_message = sanitizeField(error.message);
     if (error.status != null) packet.error_status = error.status;
+    if (error.fields != null && typeof error.fields === 'object') {
+      assertNoForbiddenKeys(error.fields);
+      const trustedFields = normalizeForgeErrorFields(error.code, error.fields);
+      if (trustedFields != null) {
+        Object.assign(packet, trustedFields);
+      }
+    }
   }
 
   return packet;
 }
 
 export function forgeErrorPacket(context, error, type = PACKET_TYPES.FORGE_ERROR) {
-  return forgePacket(type, context, {}, error);
+  const body = error?.fields != null && typeof error.fields === 'object' ? error.fields : {};
+  return forgePacket(type, context, body, error);
 }
 
 export function unknownForgeContext() {

package/contracts/errors.js

@@ -11,9 +11,21 @@ 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',
+  WRITE_NOT_CONFIGURED: 'write_not_configured',
+  IDEMPOTENCY_SCAN_INCOMPLETE: 'idempotency_scan_incomplete',
+  IDEMPOTENCY_CONFLICT: 'idempotency_conflict',
+  INVENTORY_LIST_INCOMPLETE: 'inventory_list_incomplete',
+  MERGE_BLOCKED: 'merge_blocked',
+  MERGE_ENDPOINT_FAILED: 'merge_endpoint_failed',
 };
 
-export function forgeError(code, message, status = null) {
-  return { code, message, ...(status != null ? { status } : {}) };
+export function forgeError(code, message, status = null, fields = null) {
+  return {
+    code,
+    message,
+    ...(status != null ? { status } : {}),
+    ...(fields != null && typeof fields === 'object' ? { fields } : {}),
+  };
 }

package/contracts/forge-error-fields.js

@@ -0,0 +1,124 @@
+import { ERROR_CODES } from './errors.js';
+
+/** Top-level packet keys forge error fields must never override. */
+const FORBIDDEN_ERROR_FIELD_KEYS = new Set([
+  'type',
+  'schema_version',
+  'provider_id',
+  'remote_name',
+  'repo_id',
+  'base_url',
+  'observed_at',
+  'ok',
+  'error_code',
+  'error_message',
+  'error_status',
+]);
+
+/** Trusted body fields allowed per forge error code. */
+export const FORGE_ERROR_FIELD_ALLOWLIST = Object.freeze({
+  [ERROR_CODES.IDEMPOTENCY_SCAN_INCOMPLETE]: ['idempotency_scan'],
+  [ERROR_CODES.INVENTORY_LIST_INCOMPLETE]: ['inventory_list'],
+  [ERROR_CODES.CONFIG_INVALID]: [
+    'reason',
+    'field',
+    'expected',
+    'actual',
+    'discovered_via',
+    'operator_config_path',
+    'remediation',
+  ],
+});
+
+function assertPositiveInteger(name, value) {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`Invalid forge error field ${name}: must be a positive integer`);
+  }
+}
+
+function validateIdempotencyScan(scan) {
+  if (scan == null || typeof scan !== 'object' || Array.isArray(scan)) {
+    throw new Error('Invalid forge error field idempotency_scan: must be an object');
+  }
+  const keys = Object.keys(scan).sort();
+  const expected = ['max_pages', 'page_size', 'pages'];
+  if (keys.length !== expected.length || !expected.every((k) => keys.includes(k))) {
+    throw new Error('Invalid forge error field idempotency_scan: unexpected keys');
+  }
+  assertPositiveInteger('idempotency_scan.pages', scan.pages);
+  assertPositiveInteger('idempotency_scan.max_pages', scan.max_pages);
+  assertPositiveInteger('idempotency_scan.page_size', scan.page_size);
+  return { idempotency_scan: scan };
+}
+
+function validateInventoryList(list) {
+  if (list == null || typeof list !== 'object' || Array.isArray(list)) {
+    throw new Error('Invalid forge error field inventory_list: must be an object');
+  }
+  const keys = Object.keys(list).sort();
+  if (keys.length !== 1 || keys[0] !== 'entry_count') {
+    throw new Error('Invalid forge error field inventory_list: unexpected keys');
+  }
+  assertPositiveInteger('inventory_list.entry_count', list.entry_count);
+  return { inventory_list: list };
+}
+
+function validateConfigInvalidFields(fields) {
+  const allowed = FORGE_ERROR_FIELD_ALLOWLIST[ERROR_CODES.CONFIG_INVALID];
+  const out = {};
+  for (const key of allowed) {
+    if (fields[key] == null) continue;
+    if (typeof fields[key] !== 'string') {
+      throw new Error(`Invalid forge error field ${key}: must be a string`);
+    }
+    out[key] = fields[key];
+  }
+  return Object.keys(out).length ? out : null;
+}
+
+/**
+ * Validate and normalize trusted forge_error body fields before packet merge.
+ * @param {string} code
+ * @param {Record<string, unknown> | null | undefined} fields
+ * @returns {Record<string, unknown> | null}
+ */
+export function normalizeForgeErrorFields(code, fields) {
+  if (fields == null) return null;
+  if (typeof fields !== 'object' || Array.isArray(fields)) {
+    throw new Error('Invalid forge error fields: must be an object');
+  }
+
+  const keys = Object.keys(fields);
+  if (keys.length === 0) return null;
+
+  for (const key of keys) {
+    if (FORBIDDEN_ERROR_FIELD_KEYS.has(key)) {
+      throw new Error(`Forge error fields cannot override packet field ${key}`);
+    }
+  }
+
+  const allowlist = FORGE_ERROR_FIELD_ALLOWLIST[code];
+  if (!allowlist) {
+    throw new Error(`Forge error code ${code} does not allow trusted fields`);
+  }
+
+  for (const key of keys) {
+    if (!allowlist.includes(key)) {
+      throw new Error(`Forge error field ${key} is not allowed for code ${code}`);
+    }
+  }
+
+  if (fields.idempotency_scan != null) {
+    return validateIdempotencyScan(fields.idempotency_scan);
+  }
+
+  if (fields.inventory_list != null) {
+    return validateInventoryList(fields.inventory_list);
+  }
+
+  if (code === ERROR_CODES.CONFIG_INVALID) {
+    return validateConfigInvalidFields(fields);
+  }
+
+  return fields;
+}

package/contracts/observer-fact-inventory.js

@@ -0,0 +1,64 @@
+/**
+ * Remogram fact requirements for observer and semantic-diff consumer snapshots.
+ * Observer proto today captures remogram repo status only; downstream consumers
+ * may compose additional read-only fact packets listed here.
+ */
+
+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 },
+  { command: 'whoami', mcp_tool: 'whoami', read_only: true, observer_proto: false },
+  { command: 'branch protection', mcp_tool: 'branch_protection', read_only: true, observer_proto: false },
+  { command: 'cr files', mcp_tool: 'cr_files', read_only: true, observer_proto: false },
+  { command: 'cr comments', mcp_tool: 'cr_comments', read_only: true, observer_proto: false },
+  { command: 'forge changes', mcp_tool: 'forge_changes', 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,
+    };
+  });
+}