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

package/forge-changes-cursor.js

@@ -0,0 +1,88 @@
+import { ERROR_CODES, forgeError } from './contracts/errors.js';
+import { parseSinceObservedAt } from './forge-changes.js';
+
+export const FORGE_CHANGES_CURSOR_VERSION = 1;
+export const DEFAULT_FORGE_CHANGES_PAGE_SIZE = 64;
+
+/**
+ * @param {{ since: string, offset: number }} state
+ * @returns {string}
+ */
+export function encodeForgeChangesCursor(state) {
+  const since = parseSinceObservedAt(state.since);
+  const offset = Number(state.offset);
+  if (!Number.isInteger(offset) || offset < 0) {
+    throw Object.assign(new Error('Invalid forge changes cursor offset'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, 'cursor offset must be a non-negative integer'),
+    });
+  }
+  const payload = JSON.stringify({ v: FORGE_CHANGES_CURSOR_VERSION, since, offset });
+  return Buffer.from(payload, 'utf8').toString('base64url');
+}
+
+/**
+ * @param {unknown} raw
+ * @param {{ since?: string }} [opts]
+ * @returns {{ since: string, offset: number }}
+ */
+export function decodeForgeChangesCursor(raw, opts = {}) {
+  if (raw == null || raw === '') {
+    throw Object.assign(new Error('Missing forge changes cursor'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--cursor must not be empty when provided'),
+    });
+  }
+  let decoded;
+  try {
+    decoded = JSON.parse(Buffer.from(String(raw), 'base64url').toString('utf8'));
+  } catch {
+    throw Object.assign(new Error('Invalid forge changes cursor'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--cursor is malformed or not base64url JSON'),
+    });
+  }
+  if (decoded?.v !== FORGE_CHANGES_CURSOR_VERSION) {
+    throw Object.assign(new Error('Invalid forge changes cursor version'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--cursor version is unsupported'),
+    });
+  }
+  const since = parseSinceObservedAt(decoded.since);
+  const offset = Number(decoded.offset);
+  if (!Number.isInteger(offset) || offset < 0) {
+    throw Object.assign(new Error('Invalid forge changes cursor offset'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--cursor offset must be a non-negative integer'),
+    });
+  }
+  if (opts.since != null && opts.since !== '') {
+    const requestedSince = parseSinceObservedAt(opts.since);
+    if (requestedSince !== since) {
+      throw Object.assign(new Error('Forge changes cursor since mismatch'), {
+        forgeError: forgeError(
+          ERROR_CODES.INVALID_ARGS,
+          '--since must match the cursor since when both are provided',
+        ),
+      });
+    }
+  }
+  return { since, offset };
+}
+
+/**
+ * @param {object} body
+ * @param {{ offset?: number, limit?: number }} [opts]
+ */
+export function paginateForgeChangesBody(body, opts = {}) {
+  const offset = opts.offset ?? 0;
+  const limit = opts.limit ?? DEFAULT_FORGE_CHANGES_PAGE_SIZE;
+  const allEvents = Array.isArray(body.events) ? body.events : [];
+  const pageEvents = allEvents.slice(offset, offset + limit);
+  const observedEnd = offset + pageEvents.length;
+  const hasMore = observedEnd < allEvents.length || body.events_truncated === true;
+  return {
+    ...body,
+    events: pageEvents,
+    has_more: hasMore,
+    complete: !hasMore,
+    ...(hasMore
+      ? { next_cursor: encodeForgeChangesCursor({ since: body.since, offset: observedEnd }) }
+      : {}),
+  };
+}

package/forge-changes.js

@@ -0,0 +1,181 @@
+import { sanitizeField, sanitizeUrl } from './caps.js';
+import { ERROR_CODES, forgeError } from './contracts/errors.js';
+
+export const MAX_FORGE_CHANGES_EVENTS = 256;
+
+export const FORGE_CHANGE_EVENT_KINDS = Object.freeze({
+  PR_OPENED: 'pr_opened',
+  PR_CLOSED: 'pr_closed',
+  PR_MERGED: 'pr_merged',
+  HEAD_SHA_MOVED: 'head_sha_moved',
+  CHECKS_CONCLUSION_OBSERVED: 'checks_conclusion_observed',
+});
+
+export function parseSinceObservedAt(raw) {
+  if (raw == null || String(raw).trim() === '') {
+    throw Object.assign(new Error('--since required'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--since required for forge changes'),
+    });
+  }
+  const ms = Date.parse(String(raw));
+  if (!Number.isFinite(ms)) {
+    throw Object.assign(new Error('Invalid --since'), {
+      forgeError: forgeError(
+        ERROR_CODES.INVALID_ARGS,
+        '--since must be a parseable ISO-8601 timestamp',
+      ),
+    });
+  }
+  return new Date(ms).toISOString();
+}
+
+function timestampMs(value) {
+  const ms = Date.parse(value ?? '');
+  return Number.isFinite(ms) ? ms : null;
+}
+
+function isAtOrAfter(value, sinceIso) {
+  const ms = timestampMs(value);
+  const sinceMs = timestampMs(sinceIso);
+  if (ms == null || sinceMs == null) return false;
+  return ms >= sinceMs;
+}
+
+function isBefore(value, sinceIso) {
+  const ms = timestampMs(value);
+  const sinceMs = timestampMs(sinceIso);
+  if (ms == null || sinceMs == null) return false;
+  return ms < sinceMs;
+}
+
+function normalizePrState(state) {
+  const normalized = String(state ?? '').toLowerCase();
+  if (normalized === 'open') return 'open';
+  if (normalized === 'closed') return 'closed';
+  return 'unknown';
+}
+
+function normalizeIsoTimestamp(value) {
+  const ms = timestampMs(value);
+  return ms == null ? null : new Date(ms).toISOString();
+}
+
+function baseEventFields(pull) {
+  return {
+    pr_number: Math.floor(Number(pull.number)),
+    title: sanitizeField(pull.title ?? '') || null,
+    url: sanitizeUrl(pull.html_url ?? pull.url) || null,
+  };
+}
+
+export function buildChecksConclusionObservedEvent(prNumber, checksBody) {
+  return {
+    kind: FORGE_CHANGE_EVENT_KINDS.CHECKS_CONCLUSION_OBSERVED,
+    pr_number: Math.floor(Number(prNumber)),
+    forge_source_sha: sanitizeField(checksBody?.forge_source_sha ?? '') || null,
+    check_conclusion: sanitizeField(checksBody?.check_conclusion ?? '') || 'unknown',
+    checks_truncated: Boolean(checksBody?.checks_truncated ?? false),
+  };
+}
+
+export function buildForgeChangesBody({
+  since,
+  events,
+  events_truncated,
+  event_count,
+  since_kind = 'observed_at',
+}) {
+  const list = Array.isArray(events) ? events : [];
+  const count = Number.isFinite(Number(event_count))
+    ? Math.floor(Number(event_count))
+    : list.length;
+  return {
+    since,
+    since_kind,
+    events: list,
+    events_truncated: Boolean(events_truncated),
+    event_count: count,
+  };
+}
+
+function capForgeChangeEvents(allEvents, sinceIso, { listTruncated = false } = {}) {
+  const event_count = allEvents.length;
+  const capped = allEvents.length > MAX_FORGE_CHANGES_EVENTS;
+  return buildForgeChangesBody({
+    since: sinceIso,
+    events: allEvents.slice(0, MAX_FORGE_CHANGES_EVENTS),
+    events_truncated: capped || listTruncated,
+    event_count,
+  });
+}
+
+export function appendForgeChangeEvents(body, additionalEvents, { listTruncated = false } = {}) {
+  const merged = [...(body.events ?? []), ...(Array.isArray(additionalEvents) ? additionalEvents : [])];
+  return capForgeChangeEvents(merged, body.since, {
+    listTruncated: listTruncated || body.events_truncated,
+  });
+}
+
+export function buildForgeChangesFromGiteaPulls(sinceIso, pullsArray, opts = {}) {
+  const since = parseSinceObservedAt(sinceIso);
+  const events = [];
+  if (Array.isArray(pullsArray)) {
+    for (const pull of pullsArray) {
+      if (pull == null || pull.number == null) continue;
+      const state = normalizePrState(pull.state);
+      const base = baseEventFields(pull);
+      const createdAt = pull.created_at;
+      const updatedAt = pull.updated_at;
+      const closedAt = pull.closed_at;
+      const mergedAt = pull.merged_at;
+      const mergedInWindow = isAtOrAfter(mergedAt, since);
+
+      if (isAtOrAfter(createdAt, since)) {
+        events.push({
+          kind: FORGE_CHANGE_EVENT_KINDS.PR_OPENED,
+          ...base,
+          state,
+          opened_at: normalizeIsoTimestamp(createdAt),
+        });
+      }
+
+      if (mergedInWindow) {
+        events.push({
+          kind: FORGE_CHANGE_EVENT_KINDS.PR_MERGED,
+          ...base,
+          state: 'closed',
+          merged_at: normalizeIsoTimestamp(mergedAt),
+        });
+      }
+
+      const closedNotMerged =
+        state === 'closed' && (mergedAt == null || String(mergedAt).trim() === '');
+      const closedInWindow =
+        isAtOrAfter(closedAt, since) ||
+        (closedAt == null && closedNotMerged && isAtOrAfter(updatedAt, since));
+      if (!mergedInWindow && closedNotMerged && closedInWindow) {
+        events.push({
+          kind: FORGE_CHANGE_EVENT_KINDS.PR_CLOSED,
+          ...base,
+          state: 'closed',
+          closed_at: normalizeIsoTimestamp(closedAt ?? updatedAt),
+        });
+      }
+
+      if (
+        state === 'open' &&
+        isAtOrAfter(updatedAt, since) &&
+        isBefore(createdAt, since)
+      ) {
+        events.push({
+          kind: FORGE_CHANGE_EVENT_KINDS.HEAD_SHA_MOVED,
+          ...base,
+          state: 'open',
+          forge_source_sha: sanitizeField(pull.head?.sha ?? '') || null,
+          updated_at: normalizeIsoTimestamp(updatedAt),
+        });
+      }
+    }
+  }
+  return capForgeChangeEvents(events, since, { listTruncated: Boolean(opts.listTruncated) });
+}

package/forge-identity.js

@@ -0,0 +1,42 @@
+import { ERROR_CODES, forgeError } from './contracts/errors.js';
+
+/**
+ * Canonical forge origin (scheme + host + port) from configured baseUrl.
+ * Config-derived trusted identity — not forge-sourced.
+ *
+ * @param {{ baseUrl?: string }} config
+ * @returns {string | null}
+ */
+export function normalizedForgeOrigin(config) {
+  if (!config?.baseUrl) return null;
+  let url;
+  try {
+    url = new URL(config.baseUrl);
+  } catch {
+    throw Object.assign(new Error('Invalid baseUrl'), {
+      forgeError: forgeError(ERROR_CODES.CONFIG_INVALID, 'Invalid baseUrl in .remogram.json'),
+    });
+  }
+  if (url.username || url.password) {
+    throw Object.assign(new Error('baseUrl must not contain userinfo'), {
+      forgeError: forgeError(ERROR_CODES.CONFIG_INVALID, 'baseUrl must not contain userinfo'),
+    });
+  }
+  if (url.pathname && url.pathname !== '/') {
+    throw Object.assign(new Error('baseUrl must be a forge origin'), {
+      forgeError: forgeError(
+        ERROR_CODES.CONFIG_INVALID,
+        'baseUrl must be a forge origin without a path',
+      ),
+    });
+  }
+  if (url.search || url.hash) {
+    throw Object.assign(new Error('baseUrl must be a forge origin'), {
+      forgeError: forgeError(
+        ERROR_CODES.CONFIG_INVALID,
+        'baseUrl must be a forge origin without query or fragment',
+      ),
+    });
+  }
+  return url.origin;
+}

package/git-args.js

@@ -35,3 +35,22 @@ export function assertGitRemote(name, label = 'remote') {
     throw invalidArgs(`${label} contains invalid characters`);
   }
 }
+
+const CR_OPEN_REMOTE_PREFIXES = new Set(['origin', 'upstream', 'gitea', 'github', 'gitlab']);
+
+/**
+ * cr open --head/--base expect forge branch names, not git remote/ref pairs.
+ */
+export function assertCrOpenBranchRef(ref, label = 'ref') {
+  assertGitRef(ref, label);
+  const slash = ref.indexOf('/');
+  if (slash <= 0) return;
+  const remotePrefix = ref.slice(0, slash);
+  if (!CR_OPEN_REMOTE_PREFIXES.has(remotePrefix)) return;
+  const branchHint = ref.slice(slash + 1);
+  throw invalidArgs(
+    `${label} looks like a remote/ref (${ref}); cr open expects a forge branch name `
+    + `(e.g. ${branchHint}). Compare forge_target_branch_ref from pr view to your workflow `
+    + 'canonical_integration_ref outside Remogram.',
+  );
+}

package/git-local.js

@@ -24,7 +24,17 @@ export function gitCurrentBranch(cwd) {
   }
 }
 
+export function gitRepoRoot(cwd) {
+  try {
+    return gitExec(cwd, ['rev-parse', '--show-toplevel']);
+  } catch {
+    return null;
+  }
+}
+
 export function gitAheadBehind(cwd, base, head) {
+  assertGitRef(base, 'base');
+  assertGitRef(head, 'head');
   try {
     const out = gitExec(cwd, ['rev-list', '--left-right', '--count', `${base}...${head}`]);
     const [behind, ahead] = out.split(/\s+/).map(Number);
@@ -33,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

@@ -1,8 +1,8 @@
 import { ERROR_CODES, forgeError } from './contracts/errors.js';
-import { readStreamCapped, DEFAULT_MAX_BYTES, sanitizeField } from './caps.js';
+import { readStreamCapped, getEffectiveIngestMaxBytes, sanitizeField } from './caps.js';
 
 const DEFAULT_TIMEOUT_MS = 30_000;
-const DEFAULT_JSON_MAX_BYTES = DEFAULT_MAX_BYTES;
+const DEFAULT_JSON_MAX_BYTES = () => getEffectiveIngestMaxBytes().bytes;
 
 export async function fetchWithTimeout(url, options = {}, timeoutMs = DEFAULT_TIMEOUT_MS) {
   const signal = AbortSignal.timeout(timeoutMs);
@@ -25,7 +25,7 @@ export async function fetchJson(
   url,
   options = {},
   timeoutMs = DEFAULT_TIMEOUT_MS,
-  maxBytes = DEFAULT_JSON_MAX_BYTES,
+  maxBytes = DEFAULT_JSON_MAX_BYTES(),
 ) {
   const res = await fetchWithTimeout(url, options, timeoutMs);
   if (res.status >= 300 && res.status < 400) {
@@ -56,7 +56,86 @@ export async function fetchJson(
   return body;
 }
 
-export async function fetchTextCapped(url, options = {}, maxBytes = DEFAULT_MAX_BYTES) {
+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[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 = {},
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  maxBytes = DEFAULT_JSON_MAX_BYTES(),
+) {
+  const res = await fetchWithTimeout(url, options, timeoutMs);
+  if (res.status >= 300 && res.status < 400) {
+    const message = 'HTTP redirect rejected';
+    throw Object.assign(new Error(message), {
+      forgeError: forgeError(ERROR_CODES.API_ERROR, message, res.status),
+      status: res.status,
+    });
+  }
+  const text = await readResponseTextCapped(res, maxBytes);
+  let body;
+  try {
+    body = text ? JSON.parse(text) : null;
+  } catch {
+    throw Object.assign(new Error('Unparseable JSON from provider'), {
+      forgeError: forgeError(ERROR_CODES.UNPARSEABLE_PROVIDER_OUTPUT, 'Provider returned invalid JSON'),
+      status: res.status,
+    });
+  }
+  if (!res.ok) {
+    const raw = body?.message || body?.error || res.statusText || 'API error';
+    const message = sanitizeField(raw) || 'API error';
+    throw Object.assign(new Error(message), {
+      forgeError: forgeError(ERROR_CODES.API_ERROR, message, res.status),
+      status: res.status,
+    });
+  }
+  return { body, headers: res.headers, status: res.status };
+}
+
+export async function fetchTextCapped(url, options = {}, maxBytes = getEffectiveIngestMaxBytes().bytes) {
   const res = await fetchWithTimeout(url, options);
   if (res.status >= 300 && res.status < 400) {
     const message = 'HTTP redirect rejected';

package/idempotency.js

@@ -0,0 +1,69 @@
+import { createHash } from 'node:crypto';
+import { sanitizeField } from './caps.js';
+import { ERROR_CODES, forgeError } from './contracts/errors.js';
+
+const KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+
+/** @type {Map<string, string>} */
+const scopeBindings = new Map();
+
+export function resetIdempotencyScopeBindings() {
+  scopeBindings.clear();
+}
+
+export function normalizeIdempotencyKey(value) {
+  if (value == null || value === '') return null;
+  const key = sanitizeField(String(value).trim());
+  if (!key || !KEY_PATTERN.test(key)) {
+    throw Object.assign(new Error('Invalid idempotency key'), {
+      forgeError: forgeError(
+        ERROR_CODES.INVALID_ARGS,
+        'idempotency key must be 1-128 characters from [A-Za-z0-9._:-]',
+      ),
+    });
+  }
+  return key;
+}
+
+export function idempotencyFingerprint(key, scopeParts = []) {
+  const normalizedKey = normalizeIdempotencyKey(key);
+  if (!normalizedKey) return null;
+  const scope = scopeParts.map((part) => sanitizeField(String(part ?? ''))).join('\0');
+  return createHash('sha256').update(`${normalizedKey}\0${scope}`).digest('hex').slice(0, 16);
+}
+
+export function idempotencyScopeKey(repoId, key) {
+  const normalizedKey = normalizeIdempotencyKey(key);
+  if (!normalizedKey) return null;
+  return `${sanitizeField(repoId)}:${normalizedKey}`;
+}
+
+export function bindIdempotencyScope(repoId, key, scopeParts) {
+  const normalizedKey = normalizeIdempotencyKey(key);
+  if (!normalizedKey) return null;
+  const bindingKey = idempotencyScopeKey(repoId, normalizedKey);
+  const serialized = JSON.stringify(scopeParts.map((part) => sanitizeField(String(part ?? ''))));
+  const prior = scopeBindings.get(bindingKey);
+  if (prior && prior !== serialized) {
+    throw Object.assign(new Error('Idempotency key scope conflict'), {
+      forgeError: forgeError(
+        ERROR_CODES.IDEMPOTENCY_CONFLICT,
+        'idempotency key was already used with a different write scope',
+      ),
+    });
+  }
+  scopeBindings.set(bindingKey, serialized);
+  return idempotencyFingerprint(normalizedKey, scopeParts);
+}
+
+export function idempotencyPacketFields(fingerprint, { reusedExisting = false, ambiguousAfterWrite = false } = {}) {
+  const fields = {};
+  if (fingerprint) fields.idempotency_fingerprint = fingerprint;
+  if (reusedExisting) {
+    fields.reused_existing = true;
+  } else {
+    fields.created = true;
+  }
+  if (ambiguousAfterWrite) fields.ambiguous_after_write = true;
+  return fields;
+}