@remogram/core 0.1.0-beta.5 → 0.1.0-beta.8

package/auth-classes.js

@@ -24,6 +24,7 @@ export const API_PROVIDER_COMMAND_AUTH = {
   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 } = {}) {
@@ -41,6 +42,7 @@ export function apiProviderCommands({
   crFilesImplemented = false,
   crCommentsImplemented = false,
   forgeChangesImplemented = false,
+  mergeExecuteImplemented = false,
 } = {}) {
   return Object.keys(API_PROVIDER_COMMAND_AUTH).map((name) => {
     let implemented = true;
@@ -50,6 +52,7 @@ export function apiProviderCommands({
     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 });
   });
 }

package/caps.js

@@ -1,6 +1,8 @@
 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;
@@ -20,13 +22,20 @@ export function getEffectiveIngestMaxBytes() {
   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 } = getEffectiveIngestMaxBytes();
-  return { forge_ingest_cap_bytes: bytes };
+  const { bytes, envOverride, clamped } = getEffectiveIngestMaxBytes();
+  return {
+    forge_ingest_cap_bytes: bytes,
+    ...(envOverride ? { forge_ingest_env_override: true } : {}),
+    ...(clamped ? { forge_ingest_cap_clamped: true } : {}),
+  };
 }
 
 /**

package/change-request-merge-execute.js

@@ -0,0 +1,139 @@
+import { sanitizeField } from './caps.js';
+import { mergeBlockersFromFacts } from './merge-blockers.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) {
+  const viewFacts = mergeExecuteViewFacts(view);
+  const checksFacts = mergeExecuteChecksFacts(checks);
+  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] : [],
+  };
+}
+
+/**
+ * Collect merge-execute blockers before forge mutation.
+ * @returns {string[]} normalized blocker ids
+ */
+export function collectMergeExecuteBlockers(
+  view,
+  checks,
+  mergePlanBody,
+  expected,
+  { forgeHeadRefSha } = {},
+) {
+  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, {});
+  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/contracts/envelope.js

@@ -20,6 +20,8 @@ export const PACKET_TYPES = {
   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([
@@ -57,6 +59,11 @@ 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);

package/contracts/errors.js

@@ -16,6 +16,8 @@ export const ERROR_CODES = {
   WRITE_NOT_CONFIGURED: 'write_not_configured',
   IDEMPOTENCY_SCAN_INCOMPLETE: 'idempotency_scan_incomplete',
   INVENTORY_LIST_INCOMPLETE: 'inventory_list_incomplete',
+  MERGE_BLOCKED: 'merge_blocked',
+  MERGE_ENDPOINT_FAILED: 'merge_endpoint_failed',
 };
 
 export function forgeError(code, message, status = null, fields = null) {

package/contracts/forge-error-fields.js

@@ -7,6 +7,7 @@ const FORBIDDEN_ERROR_FIELD_KEYS = new Set([
   'provider_id',
   'remote_name',
   'repo_id',
+  'base_url',
   'observed_at',
   'ok',
   'error_code',

package/contracts/semantic-diff-facts.js

@@ -28,7 +28,7 @@ export const V1_READ_PLAN_COMMANDS = Object.freeze([
 ]);
 
 /** v1 write surface (Gitea cr open and status set in first slices). */
-export const V1_WRITE_COMMANDS = Object.freeze(['cr open', 'status set']);
+export const V1_WRITE_COMMANDS = Object.freeze(['cr open', 'status set', 'merge execute']);
 
 /**
  * Planned fact-inventory packet types (not emitted until wave 2+ commands ship).
@@ -46,6 +46,7 @@ export const TRUSTED_ENVELOPE_FIELDS = Object.freeze([
   'provider_id',
   'remote_name',
   'repo_id',
+  'base_url',
   'observed_at',
   'ok',
 ]);
@@ -83,9 +84,9 @@ export const TRUSTED_NORMALIZED_BODY_FIELDS = Object.freeze({
  */
 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'],
+  ref_compare: ['compare_base_ref', 'compare_head_ref', 'compare_base_sha', 'compare_head_sha'],
+  pr_status: ['url', 'title', 'forge_target_branch_ref', 'forge_source_branch_ref', 'forge_target_sha', 'forge_source_sha'],
+  pr_checks: ['forge_source_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'],
@@ -99,16 +100,16 @@ export const FORGE_SOURCED_STRING_LEAVES = Object.freeze({
   ],
   cr_files: ['changed_paths[]'],
   cr_comments: ['comments[].id', 'comments[].author', 'comments[].path', 'comments[].body'],
-  forge_changes: ['events[].title', 'events[].url', 'events[].head_sha'],
+  forge_changes: ['events[].title', 'events[].url', 'events[].forge_source_sha'],
   cr_inventory_slice: [
     'entries[].url',
     'entries[].title',
-    'entries[].base_ref',
-    'entries[].head_ref',
-    'entries[].base_sha',
-    'entries[].head_sha',
+    'entries[].forge_target_branch_ref',
+    'entries[].forge_source_branch_ref',
+    'entries[].forge_target_sha',
+    'entries[].forge_source_sha',
     'entries[].head_reconcile.local_head_sha',
-    'entries[].head_reconcile.head_sha',
+    'entries[].head_reconcile.forge_source_sha',
     'entries[].checks[].context',
     'entries[].checks[].description',
   ],
@@ -125,11 +126,11 @@ 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',
+    ancestry_hints: 'array<{ compare_base_ref: string, compare_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 } }>',
+      'array<{ pr_number: number, url?: string, title?: string, state?: string, forge_target_branch_ref?: string, forge_source_branch_ref?: string, forge_target_sha?: string, forge_source_sha?: string, mergeability?: string, checks_conclusion?: string, checks_truncated?: boolean, blockers?: array, head_reconcile?: { stale: boolean, local_head_sha?: string, forge_source_sha?: string } }>',
     entry_count: 'number',
     /** true when list cap applied (entry_count > limit), not missing entries */
     truncated: 'boolean',

package/cr-inventory.js

@@ -39,14 +39,14 @@ export function buildHeadReconcile(ctx, view) {
   const details = staleHeadDetails(
     ctx.cwd,
     ctx.config?.remote ?? ctx.remoteName,
-    view.head_ref,
-    view.head_sha,
+    view.forge_source_branch_ref,
+    view.forge_source_sha,
   );
   if (!details) return { stale: false };
   return {
     stale: true,
     local_head_sha: details.local_head_sha,
-    head_sha: details.head_sha,
+    forge_source_sha: details.forge_source_sha,
   };
 }
 
@@ -59,16 +59,16 @@ export function buildCrInventoryEntry(ctx, view, checks) {
     url: view.url,
     title: view.title,
     state: view.state,
-    base_ref: view.base_ref,
-    head_ref: view.head_ref,
+    forge_target_branch_ref: view.forge_target_branch_ref,
+    forge_source_branch_ref: view.forge_source_branch_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;
+  if (view.forge_target_sha) entry.forge_target_sha = view.forge_target_sha;
+  if (view.forge_source_sha) entry.forge_source_sha = view.forge_source_sha;
   return entry;
 }
 

package/forge-changes.js

@@ -72,7 +72,7 @@ export function buildChecksConclusionObservedEvent(prNumber, checksBody) {
   return {
     kind: FORGE_CHANGE_EVENT_KINDS.CHECKS_CONCLUSION_OBSERVED,
     pr_number: Math.floor(Number(prNumber)),
-    head_sha: sanitizeField(checksBody?.head_sha ?? '') || null,
+    forge_source_sha: sanitizeField(checksBody?.forge_source_sha ?? '') || null,
     check_conclusion: sanitizeField(checksBody?.check_conclusion ?? '') || 'unknown',
     checks_truncated: Boolean(checksBody?.checks_truncated ?? false),
   };
@@ -171,7 +171,7 @@ export function buildForgeChangesFromGiteaPulls(sinceIso, pullsArray, opts = {})
           kind: FORGE_CHANGE_EVENT_KINDS.HEAD_SHA_MOVED,
           ...base,
           state: 'open',
-          head_sha: sanitizeField(pull.head?.sha ?? '') || null,
+          forge_source_sha: sanitizeField(pull.head?.sha ?? '') || null,
           updated_at: normalizeIsoTimestamp(updatedAt),
         });
       }

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/index.js

@@ -28,6 +28,7 @@ export {
   DEFAULT_MAX_BYTES,
   DEFAULT_FIELD_MAX_BYTES,
   FORGE_INGEST_MAX_BYTES_ENV,
+  MAX_FORGE_INGEST_ENV_BYTES,
   DEFAULT_CHECK_STATUS_PAGE_SIZE,
   MAX_CHECK_STATUS_PAGES,
   DEFAULT_OPEN_PULL_LIST_PAGE_SIZE,
@@ -74,6 +75,17 @@ export {
   appendSortQuery,
 } from './open-pull-list.js';
 export { buildChangeRequestOpenedBody } from './cr-open.js';
+export {
+  assertExpectedSha,
+  mergeExecuteViewFacts,
+  mergeExecuteChecksFacts,
+  buildMergeExecuteBeforeFacts,
+  collectMergeExecuteBlockers,
+  buildCrMergeBlockedBody,
+  buildCrMergedBody,
+  buildMergeExecuteAfterFacts,
+  buildMergeExecuteMergeFacts,
+} from './change-request-merge-execute.js';
 export {
   STATUS_SET_STATES,
   assertCommitSha,
@@ -135,15 +147,26 @@ export {
 } from './write-config.js';
 export { mergeBlockersFromFacts, isOpenPrState } from './merge-blockers.js';
 export {
+  applyForgePathScopeForMergePlan,
+  isCrFilesScopeComplete,
   resolveMergePlanPathScope,
   buildMergePlanBody,
   buildMergePlanBodyFromFacts,
+  normalizeAllowedPaths,
 } from './merge-plan.js';
+export {
+  isMergePlanForgeScopeRethrowError,
+  MERGE_PLAN_FORGE_SCOPE_RETHROW_CODES,
+  resolveMergePlanOptsWithForgePaths,
+  buildMergePlanFromProviderFacts,
+} from './merge-plan-forge.js';
 export {
   matchPathAllowlist,
   isPathAllowed,
   pathsOutsideAllowlist,
   allPathsAllowed,
+  normalizeRepoRelativePath,
+  normalizeChangedPathList,
 } from './path-allowlist.js';
 export {
   localHeadShaForPr,
@@ -154,6 +177,7 @@ export {
   throwIfStaleHeadByNumber,
 } from './pr-head-reconcile.js';
 export { parseConfigFile, configSchema } from './config-schema.js';
+export { normalizedForgeOrigin } from './forge-identity.js';
 export {
   findConfigPath,
   loadConfig,

package/merge-blockers.js

@@ -1,4 +1,4 @@
-import { allPathsAllowed } from './path-allowlist.js';
+import { allPathsAllowed, normalizeChangedPathList } from './path-allowlist.js';
 
 /**
  * Derive merge blockers from already-fetched PR view and checks facts.
@@ -27,8 +27,15 @@ export function mergeBlockersFromFacts(view, checks, pathScope = {}) {
     const changedPaths = pathScope.changed_paths;
     if (changedPaths == null) {
       blockers.push('changed_paths_unavailable');
-    } else if (!allPathsAllowed(allowedPaths, changedPaths)) {
-      blockers.push('path_scope_violation');
+    } else if (Array.isArray(changedPaths)) {
+      const normalizedPaths = normalizeChangedPathList(changedPaths);
+      if (normalizedPaths == null) {
+        blockers.push('changed_paths_unavailable');
+      } else if (!allPathsAllowed(allowedPaths, normalizedPaths)) {
+        blockers.push('path_scope_violation');
+      }
+    } else {
+      blockers.push('changed_paths_unavailable');
     }
   }
 

package/merge-plan-forge.js

@@ -0,0 +1,62 @@
+import { ERROR_CODES } from './contracts/errors.js';
+import {
+  applyForgePathScopeForMergePlan,
+  buildMergePlanBodyFromFacts,
+  normalizeAllowedPaths,
+} from './merge-plan.js';
+
+/** Errors that must propagate from crFiles during merge-plan path scope — not mapped to changed_paths_unavailable. */
+export const MERGE_PLAN_FORGE_SCOPE_RETHROW_CODES = new Set([
+  ERROR_CODES.UNAUTHENTICATED_PROVIDER,
+  ERROR_CODES.INVALID_ARGS,
+  ERROR_CODES.UNTRUSTED_BASE_URL,
+  ERROR_CODES.PROVIDER_UNSUPPORTED,
+  ERROR_CODES.CONFIG_INVALID,
+  ERROR_CODES.OVERSIZED_RAW_OUTPUT,
+  ERROR_CODES.CONFIG_NOT_FOUND,
+  ERROR_CODES.UNPARSEABLE_PROVIDER_OUTPUT,
+  ERROR_CODES.STALE_HEAD,
+  ERROR_CODES.MISSING_REF,
+  ERROR_CODES.PR_NOT_OPEN,
+  ERROR_CODES.REMOTE_INFER_FAILED,
+]);
+
+export function isMergePlanForgeScopeRethrowError(err) {
+  const code = err?.forgeError?.code;
+  return typeof code === 'string' && MERGE_PLAN_FORGE_SCOPE_RETHROW_CODES.has(code);
+}
+
+export { normalizeAllowedPaths } from './merge-plan.js';
+
+/**
+ * Resolve merge plan opts with forge cr_files when an allowlist is configured.
+ * @param {object} opts
+ * @param {() => Promise<object>} crFilesFn
+ */
+export async function resolveMergePlanOptsWithForgePaths(opts, crFilesFn) {
+  if (!normalizeAllowedPaths(opts.allowed_paths)) return opts;
+  try {
+    const crFilesBody = await crFilesFn();
+    return applyForgePathScopeForMergePlan(opts, crFilesBody);
+  } catch (err) {
+    if (isMergePlanForgeScopeRethrowError(err)) throw err;
+    // Intentional mask bucket: transient api_error → changed_paths_unavailable.
+    // write_not_configured / idempotency codes are not emitted by crFiles today.
+    return applyForgePathScopeForMergePlan(opts, null);
+  }
+}
+
+/**
+ * Build merge_plan body from provider deps (shared tri-provider orchestration).
+ * @param {object} ctx
+ * @param {object} opts
+ * @param {{ prView: Function, prChecks: Function, crFiles: Function }} deps
+ */
+export async function buildMergePlanFromProviderFacts(ctx, opts, deps) {
+  const view = await deps.prView(ctx, opts);
+  const checks = await deps.prChecks(ctx, { number: view.pr_number });
+  const mergeOpts = await resolveMergePlanOptsWithForgePaths(opts, () =>
+    deps.crFiles(ctx, { number: view.pr_number }),
+  );
+  return buildMergePlanBodyFromFacts(view, checks, mergeOpts);
+}

package/merge-plan.js

@@ -1,25 +1,64 @@
-import { gitDiffNameOnly } from './git-local.js';
 import { mergeBlockersFromFacts } from './merge-blockers.js';
+import { normalizeChangedPathList } from './path-allowlist.js';
 
-function normalizeAllowedPaths(allowedPaths) {
+function allowlistGlobHasDotDotSegment(glob) {
+  if (typeof glob !== 'string') return false;
+  const normalized = glob.replace(/\\/g, '/');
+  if (normalized === '..' || normalized.startsWith('../') || normalized.includes('/../')) {
+    return true;
+  }
+  return normalized.split('/').some((segment) => segment === '..');
+}
+
+export function normalizeAllowedPaths(allowedPaths) {
   if (!Array.isArray(allowedPaths)) return null;
-  const normalized = allowedPaths.filter((entry) => typeof entry === 'string' && entry.length > 0);
+  const normalized = allowedPaths
+    .filter((entry) => typeof entry === 'string')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0 && !allowlistGlobHasDotDotSegment(entry));
   return normalized.length > 0 ? normalized : null;
 }
 
-export function resolveMergePlanPathScope(ctx, view, opts = {}) {
+/** True when cr_files body is complete enough for merge-plan path scope. */
+export function isCrFilesScopeComplete(crFilesBody) {
+  if (!crFilesBody || crFilesBody.paths_truncated) return false;
+  const changedPaths = crFilesBody.changed_paths;
+  if (!Array.isArray(changedPaths)) return false;
+  const pathCount = Number.isFinite(Number(crFilesBody.path_count))
+    ? Math.floor(Number(crFilesBody.path_count))
+    : changedPaths.length;
+  if (pathCount > 0 && changedPaths.length === 0) return false;
+  if (pathCount > changedPaths.length) return false;
+  if (changedPaths.length > pathCount) return false;
+  return true;
+}
+
+/** Apply forge cr_files facts to merge plan opts when an allowlist is configured. */
+export function applyForgePathScopeForMergePlan(opts, crFilesBody) {
+  if (!normalizeAllowedPaths(opts.allowed_paths)) return opts;
+  if (!isCrFilesScopeComplete(crFilesBody)) {
+    return { ...opts, changed_paths: null };
+  }
+  const normalizedPaths = normalizeChangedPathList(crFilesBody.changed_paths);
+  if (normalizedPaths == null) {
+    return { ...opts, changed_paths: null };
+  }
+  return { ...opts, changed_paths: normalizedPaths };
+}
+
+export function resolveMergePlanPathScope(opts = {}) {
   const allowedPaths = normalizeAllowedPaths(opts.allowed_paths);
   if (!allowedPaths) {
     return { allowed_paths: null, changed_paths: null };
   }
   if (Array.isArray(opts.changed_paths)) {
-    return { allowed_paths: allowedPaths, changed_paths: opts.changed_paths };
-  }
-  if (!view.base_sha || !view.head_sha) {
-    return { allowed_paths: allowedPaths, changed_paths: null };
+    const normalizedPaths = normalizeChangedPathList(opts.changed_paths);
+    return {
+      allowed_paths: allowedPaths,
+      changed_paths: normalizedPaths,
+    };
   }
-  const changedPaths = gitDiffNameOnly(ctx.cwd, view.base_sha, view.head_sha);
-  return { allowed_paths: allowedPaths, changed_paths: changedPaths };
+  return { allowed_paths: allowedPaths, changed_paths: null };
 }
 
 export function buildMergePlanBody(view, checks, pathScope = {}) {
@@ -31,7 +70,7 @@ export function buildMergePlanBody(view, checks, pathScope = {}) {
   };
 }
 
-export function buildMergePlanBodyFromFacts(ctx, view, checks, opts = {}) {
-  const pathScope = resolveMergePlanPathScope(ctx, view, opts);
+export function buildMergePlanBodyFromFacts(view, checks, opts = {}) {
+  const pathScope = resolveMergePlanPathScope(opts);
   return buildMergePlanBody(view, checks, pathScope);
 }

package/package.json

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

package/path-allowlist.js

@@ -3,6 +3,56 @@
  * Supports `**`, `*`, and literal path segments (e.g. README.md).
  */
 
+/**
+ * Collapse `.` / `..` segments; reject absolute paths and repo-root escape.
+ * @param {string} filePath
+ * @returns {string|null}
+ */
+export function normalizeRepoRelativePath(filePath) {
+  if (typeof filePath !== 'string') return null;
+  let path = filePath.replace(/\\/g, '/').replace(/^\.\//, '');
+  if (path === '') return null;
+  if (path.startsWith('/')) return null;
+  if (path === '..' || path.startsWith('../')) return null;
+  const parts = path.split('/');
+  const out = [];
+  for (const part of parts) {
+    if (part === '' || part === '.') continue;
+    if (part === '..') {
+      if (out.length > 0) out.pop();
+      continue;
+    }
+    out.push(part);
+  }
+  return out.join('/');
+}
+
+function changedPathHasDotDotSegment(filePath) {
+  if (typeof filePath !== 'string') return false;
+  const normalized = filePath.replace(/\\/g, '/').replace(/^\.\//, '');
+  if (normalized === '..' || normalized.startsWith('../') || normalized.includes('/../')) {
+    return true;
+  }
+  return normalized.split('/').some((segment) => segment === '..');
+}
+
+/**
+ * Normalize a forge changed-path list for allowlist scope; null if any path is unnormalizable.
+ * @param {unknown} changedPaths
+ * @returns {string[]|null}
+ */
+export function normalizeChangedPathList(changedPaths) {
+  if (!Array.isArray(changedPaths)) return null;
+  const normalized = [];
+  for (const filePath of changedPaths) {
+    if (changedPathHasDotDotSegment(filePath)) return null;
+    const repoPath = normalizeRepoRelativePath(filePath);
+    if (repoPath == null) return null;
+    normalized.push(repoPath);
+  }
+  return normalized;
+}
+
 function globToRegExp(glob) {
   let pattern = '';
   for (let i = 0; i < glob.length; i += 1) {
@@ -29,7 +79,8 @@ function globToRegExp(glob) {
  */
 export function matchPathAllowlist(glob, filePath) {
   if (typeof glob !== 'string' || typeof filePath !== 'string') return false;
-  const normalized = filePath.replace(/\\/g, '/').replace(/^\.\//, '');
+  const normalized = normalizeRepoRelativePath(filePath);
+  if (normalized == null) return false;
   return globToRegExp(glob).test(normalized);
 }
 

package/pr-head-reconcile.js

@@ -3,7 +3,7 @@ import { ERROR_CODES, forgeError } from './contracts/errors.js';
 import { gitRevParse } from './git-local.js';
 
 export const STALE_HEAD_MESSAGE =
-  'Forge PR head SHA diverges from locally resolved git; fetch or refresh before trusting head_sha';
+  'Forge PR head SHA diverges from locally resolved git; fetch or refresh before trusting forge_source_sha';
 
 export function localHeadShaForPr(cwd, remoteName, headRef) {
   if (!headRef) return null;
@@ -18,8 +18,8 @@ export function staleHeadDetails(cwd, remoteName, headRef, forgeHeadSha) {
   if (!localHeadSha) return null;
   if (localHeadSha.toLowerCase() === String(forgeHeadSha).toLowerCase()) return null;
   return {
-    head_ref: headRef,
-    head_sha: forgeHeadSha,
+    forge_source_branch_ref: headRef,
+    forge_source_sha: forgeHeadSha,
     local_head_sha: localHeadSha,
   };
 }

package/ref-inventory.js

@@ -53,8 +53,8 @@ function buildAncestryHints(cwd, defaultRef, refs) {
 
   return [
     {
-      base_ref: sanitizeField(defaultRef),
-      head_ref: sanitizeField(headBranch),
+      compare_base_ref: sanitizeField(defaultRef),
+      compare_head_ref: sanitizeField(headBranch),
       ahead_by: counts.ahead_by,
       behind_by: counts.behind_by,
     },

package/resolve.js

@@ -3,6 +3,7 @@ import { readFileSync, existsSync, realpathSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { parseConfigFile } from './config-schema.js';
 import { ERROR_CODES, forgeError } from './contracts/errors.js';
+import { normalizedForgeOrigin } from './forge-identity.js';
 import { assertGitRemote } from './git-args.js';
 import { gitRepoRoot } from './git-local.js';
 
@@ -145,6 +146,7 @@ export function forgeContext(loaded) {
     providerId: config.provider,
     remoteName: config.remote,
     repoId: `${parsed.owner}/${parsed.repo}`,
+    baseUrl: normalizedForgeOrigin(config),
     config,
     cwd: loaded.cwd,
     parsed,

package/write-config.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { ERROR_CODES, forgeError } from './contracts/errors.js';
 
 /** Canonical v1 consumer write command ids (schema + gate single source). */
-export const WRITE_COMMAND_IDS = Object.freeze(['cr_open', 'status_set']);
+export const WRITE_COMMAND_IDS = Object.freeze(['cr_open', 'status_set', 'merge']);
 
 export const writeCommandSchema = z.enum(WRITE_COMMAND_IDS);