@remogram/core 0.1.0-beta.6 → 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/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

@@ -75,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,
@@ -166,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/package.json

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

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);