@remogram/cli 0.1.0-beta.6 → 0.1.0-beta.9

package/cli-dispatch.js

@@ -3,6 +3,7 @@ import {
   PACKET_TYPES,
   ERROR_CODES,
   forgeError,
+  sanitizeField,
   assertGitRef,
   assertGitRemote,
   throwIfStaleHeadByNumber,
@@ -10,7 +11,20 @@ import {
   forgeFactInventoryPacket,
   assertWriteCommandConfigured,
   parseSinceObservedAt,
+  decodeForgeChangesCursor,
+  paginateForgeChangesBody,
+  DEFAULT_FORGE_CHANGES_PAGE_SIZE,
   normalizeAllowedPaths,
+  assertExpectedSha,
+  buildMergeExecuteBeforeFacts,
+  collectMergeExecuteBlockers,
+  buildCrMergeBlockedBody,
+  buildCrMergedBody,
+  buildMergeExecuteAfterFacts,
+  buildMergeExecuteMergeFacts,
+  mergeExecuteViewFacts,
+  isOpenPrState,
+  bindIdempotencyScope,
 } from '@remogram/core';
 import { parseAllowedPathFlags, parsePositiveInt } from './cli-argv.js';
 
@@ -67,8 +81,9 @@ export async function dispatchForgeCommand({ group, sub, flags, positional, ctx,
       slice_ref: flags.slice_ref,
       limit: parsePositiveInt(flags.limit, '--limit'),
       sort: flags.sort,
+      cursor: flags.cursor,
     });
-    if (inventoryBody.list_truncated === true) {
+    if (inventoryBody.list_truncated === true && !flags.cursor) {
       throw Object.assign(new Error('Open CR list incomplete'), {
         forgeError: forgeError(
           ERROR_CODES.INVENTORY_LIST_INCOMPLETE,
@@ -131,7 +146,6 @@ export async function dispatchForgeCommand({ group, sub, flags, positional, ctx,
     );
   }
   if (group === 'forge' && sub === 'changes') {
-    const sinceIso = parseSinceObservedAt(flags.since);
     if (typeof provider.forgeChanges !== 'function') {
       throw Object.assign(new Error('forge changes not implemented for provider'), {
         forgeError: forgeError(
@@ -140,11 +154,19 @@ export async function dispatchForgeCommand({ group, sub, flags, positional, ctx,
         ),
       });
     }
-    return forgePacket(
-      PACKET_TYPES.FORGE_CHANGES,
-      ctx,
-      await provider.forgeChanges(ctx, { since: sinceIso }),
-    );
+    let sinceIso;
+    let cursorOffset = 0;
+    const pageLimit = parsePositiveInt(flags.limit, '--limit') ?? DEFAULT_FORGE_CHANGES_PAGE_SIZE;
+    if (flags.cursor) {
+      const decoded = decodeForgeChangesCursor(flags.cursor, { since: flags.since });
+      sinceIso = decoded.since;
+      cursorOffset = decoded.offset;
+    } else {
+      sinceIso = parseSinceObservedAt(flags.since);
+    }
+    const body = await provider.forgeChanges(ctx, { since: sinceIso });
+    const paginated = paginateForgeChangesBody(body, { offset: cursorOffset, limit: pageLimit });
+    return forgePacket(PACKET_TYPES.FORGE_CHANGES, ctx, paginated);
   }
   if (group === 'cr' && sub === 'open') {
     if (typeof provider.crOpen !== 'function') {
@@ -166,6 +188,9 @@ export async function dispatchForgeCommand({ group, sub, flags, positional, ctx,
     assertGitRef(flags.head, '--head');
     assertGitRef(flags.base, '--base');
     assertWriteCommandConfigured(ctx.config, 'cr_open');
+    const idempotencyFingerprint = flags.idempotency_key
+      ? bindIdempotencyScope(ctx.repo_id, flags.idempotency_key, [flags.head, flags.base])
+      : null;
     return forgePacket(
       PACKET_TYPES.CHANGE_REQUEST_OPENED,
       ctx,
@@ -174,6 +199,35 @@ export async function dispatchForgeCommand({ group, sub, flags, positional, ctx,
         base: flags.base,
         title: flags.title,
         body: flags.body,
+        idempotencyFingerprint,
+      }),
+    );
+  }
+  if (group === 'issue' && sub === 'open') {
+    if (typeof provider.issueOpen !== 'function') {
+      throw Object.assign(new Error('issue open not implemented for provider'), {
+        forgeError: forgeError(
+          ERROR_CODES.PROVIDER_UNSUPPORTED,
+          'issue open not implemented for provider',
+        ),
+      });
+    }
+    if (!flags.title) {
+      throw Object.assign(new Error('--title required'), {
+        forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--title required for issue open'),
+      });
+    }
+    assertWriteCommandConfigured(ctx.config, 'issue_open');
+    const idempotencyFingerprint = flags.idempotency_key
+      ? bindIdempotencyScope(ctx.repo_id, flags.idempotency_key, [flags.title])
+      : null;
+    return forgePacket(
+      PACKET_TYPES.ISSUE_OPENED,
+      ctx,
+      await provider.issueOpen(ctx, {
+        title: flags.title,
+        body: flags.body,
+        idempotencyFingerprint,
       }),
     );
   }
@@ -187,6 +241,13 @@ export async function dispatchForgeCommand({ group, sub, flags, positional, ctx,
       });
     }
     assertWriteCommandConfigured(ctx.config, 'status_set');
+    const idempotencyFingerprint = flags.idempotency_key
+      ? bindIdempotencyScope(ctx.repo_id, flags.idempotency_key, [
+          flags.sha,
+          flags.context,
+          flags.state,
+        ])
+      : null;
     return forgePacket(
       PACKET_TYPES.COMMIT_STATUS_SET,
       ctx,
@@ -196,6 +257,7 @@ export async function dispatchForgeCommand({ group, sub, flags, positional, ctx,
         state: flags.state,
         target_url: flags.target_url,
         description: flags.description,
+        idempotencyFingerprint,
       }),
     );
   }
@@ -211,8 +273,8 @@ export async function dispatchForgeCommand({ group, sub, flags, positional, ctx,
       ctx,
       PACKET_TYPES.PR_STATUS,
       body,
-      body.head_ref,
-      body.head_sha,
+      body.forge_source_branch_ref,
+      body.forge_source_sha,
     );
     return forgePacket(PACKET_TYPES.PR_STATUS, ctx, body);
   }
@@ -229,9 +291,9 @@ export async function dispatchForgeCommand({ group, sub, flags, positional, ctx,
       throwIfStaleHeadByNumber(
         ctx,
         PACKET_TYPES.PR_CHECKS,
-        { head_sha: view.head_sha },
-        view.head_ref,
-        view.head_sha,
+        { forge_source_sha: view.forge_source_sha },
+        view.forge_source_branch_ref,
+        view.forge_source_sha,
       );
     }
     return forgePacket(
@@ -257,6 +319,216 @@ export async function dispatchForgeCommand({ group, sub, flags, positional, ctx,
       }),
     );
   }
+  if (group === 'merge' && sub === 'execute') {
+    if (typeof provider.mergeExecute !== 'function') {
+      throw Object.assign(new Error('merge execute not implemented for provider'), {
+        forgeError: forgeError(
+          ERROR_CODES.PROVIDER_UNSUPPORTED,
+          'merge execute not implemented for provider',
+        ),
+      });
+    }
+    const number = parsePositiveInt(flags.number, '--number');
+    if (number == null) {
+      throw Object.assign(new Error('--number required'), {
+        forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--number required for merge execute'),
+      });
+    }
+    if (!flags.expected_base_sha || !flags.expected_head_sha) {
+      throw Object.assign(new Error('expected SHAs required'), {
+        forgeError: forgeError(
+          ERROR_CODES.INVALID_ARGS,
+          '--expected-base-sha and --expected-head-sha required for merge execute',
+        ),
+      });
+    }
+    const method = flags.method ? String(flags.method).toLowerCase() : 'merge';
+    if (method !== 'merge') {
+      throw Object.assign(new Error('Unsupported merge method'), {
+        forgeError: forgeError(
+          ERROR_CODES.INVALID_ARGS,
+          'Only --method merge is supported in v1',
+        ),
+      });
+    }
+    const expectedBaseSha = assertExpectedSha(flags.expected_base_sha, '--expected-base-sha');
+    const expectedHeadSha = assertExpectedSha(flags.expected_head_sha, '--expected-head-sha');
+    assertWriteCommandConfigured(ctx.config, 'merge');
+
+    const view = await provider.prView(ctx, { number });
+    const checks = await provider.prChecks(ctx, { number });
+    const mergePlanBody = await provider.mergePlan(ctx, { number });
+    const expected = { baseSha: expectedBaseSha, headSha: expectedHeadSha };
+    const viewFacts = mergeExecuteViewFacts(view);
+
+    let forgeHeadRefSha = null;
+    const headRef = viewFacts.sourceBranchRef ? String(viewFacts.sourceBranchRef).trim() : '';
+    if (!headRef && isOpenPrState(view.state)) {
+      const before = buildMergeExecuteBeforeFacts(
+      view,
+      checks,
+      mergePlanBody,
+      null,
+      ctx.mergePolicy,
+    );
+      return forgePacket(
+        PACKET_TYPES.CR_MERGE_BLOCKED,
+        ctx,
+        buildCrMergeBlockedBody({
+          prNumber: number,
+          expected,
+          before,
+          blockers: ['head_ref_missing'],
+        }),
+        forgeError(ERROR_CODES.MERGE_BLOCKED, 'Open change request missing head branch ref'),
+      );
+    }
+    if (headRef) {
+      if (typeof provider.branchHeadSha !== 'function') {
+        const before = buildMergeExecuteBeforeFacts(
+      view,
+      checks,
+      mergePlanBody,
+      null,
+      ctx.mergePolicy,
+    );
+        return forgePacket(
+          PACKET_TYPES.CR_MERGE_BLOCKED,
+          ctx,
+          buildCrMergeBlockedBody({
+            prNumber: number,
+            expected,
+            before,
+            blockers: ['head_ref_unverified'],
+          }),
+          forgeError(
+            ERROR_CODES.MERGE_BLOCKED,
+            'Forge head branch verification not implemented for provider',
+          ),
+        );
+      }
+      try {
+        assertGitRef(headRef, 'head_ref');
+      } catch (err) {
+        const before = buildMergeExecuteBeforeFacts(
+      view,
+      checks,
+      mergePlanBody,
+      null,
+      ctx.mergePolicy,
+    );
+        return forgePacket(
+          PACKET_TYPES.CR_MERGE_BLOCKED,
+          ctx,
+          buildCrMergeBlockedBody({
+            prNumber: number,
+            expected,
+            before,
+            blockers: ['head_ref_invalid'],
+          }),
+          forgeError(
+            ERROR_CODES.INVALID_ARGS,
+            sanitizeField(err.forgeError?.message || err.message || err.invalidArgs)
+              || 'Head branch ref invalid',
+          ),
+        );
+      }
+      try {
+        forgeHeadRefSha = await provider.branchHeadSha(ctx, headRef, {
+          repoId: view.forge_source_repo_id ?? null,
+        });
+      } catch (err) {
+        if (err.forgeError?.code === ERROR_CODES.INVALID_ARGS) {
+          throw err;
+        }
+        const before = buildMergeExecuteBeforeFacts(
+      view,
+      checks,
+      mergePlanBody,
+      null,
+      ctx.mergePolicy,
+    );
+        return forgePacket(
+          PACKET_TYPES.CR_MERGE_BLOCKED,
+          ctx,
+          buildCrMergeBlockedBody({
+            prNumber: number,
+            expected,
+            before,
+            blockers: ['head_ref_unreadable'],
+          }),
+          forgeError(
+            ERROR_CODES.MERGE_BLOCKED,
+            sanitizeField(err.forgeError?.message || err.message) || 'Head branch ref unreadable',
+            err.status ?? err.forgeError?.status ?? null,
+          ),
+        );
+      }
+    }
+
+    const before = buildMergeExecuteBeforeFacts(
+      view,
+      checks,
+      mergePlanBody,
+      forgeHeadRefSha,
+      ctx.mergePolicy,
+    );
+    const blockers = collectMergeExecuteBlockers(
+      view,
+      checks,
+      mergePlanBody,
+      expected,
+      { forgeHeadRefSha, mergePolicy: ctx.mergePolicy },
+    );
+
+    if (blockers.length > 0) {
+      return forgePacket(
+        PACKET_TYPES.CR_MERGE_BLOCKED,
+        ctx,
+        buildCrMergeBlockedBody({ prNumber: number, expected, before, blockers }),
+        forgeError(ERROR_CODES.MERGE_BLOCKED, 'Merge blocked by preflight'),
+      );
+    }
+
+    try {
+      const providerResult = await provider.mergeExecute(ctx, {
+        number,
+        method,
+        expectedHeadSha: expected.headSha,
+      });
+      const merge = buildMergeExecuteMergeFacts(method, providerResult);
+      const after = buildMergeExecuteAfterFacts(view, providerResult);
+      return forgePacket(
+        PACKET_TYPES.CR_MERGED,
+        ctx,
+        buildCrMergedBody({ prNumber: number, expected, before, merge, after }),
+      );
+    } catch (err) {
+      const status = err.status ?? err.forgeError?.status ?? null;
+      const blockers =
+        Array.isArray(err.mergeBlockedBlockers) && err.mergeBlockedBlockers.length > 0
+          ? err.mergeBlockedBlockers
+          : ['merge_endpoint_failed'];
+      const fe =
+        err.forgeError
+        ?? forgeError(
+          ERROR_CODES.MERGE_ENDPOINT_FAILED,
+          sanitizeField(err.message) || 'Forge merge request failed',
+          status,
+        );
+      return forgePacket(
+        PACKET_TYPES.CR_MERGE_BLOCKED,
+        ctx,
+        buildCrMergeBlockedBody({
+          prNumber: number,
+          expected,
+          before,
+          blockers,
+        }),
+        fe,
+      );
+    }
+  }
   if (group === 'branch' && sub === 'protection') {
     const branchRef = flags.branch_ref;
     if (!branchRef) {
@@ -306,7 +578,7 @@ export async function dispatchForgeCommand({ group, sub, flags, positional, ctx,
   throw Object.assign(new Error(`Unknown command: ${positional.join(' ')}`), {
     forgeError: forgeError(
       ERROR_CODES.INVALID_ARGS,
-      'Unknown command. Try: provider capabilities, repo status, refs compare, refs inventory, cr inventory, cr files, cr comments, cr open, status set, forge changes, pr view, pr checks, merge plan, sync plan, whoami, branch protection',
+      'Unknown command. Try: provider capabilities, repo status, refs compare, refs inventory, cr inventory, cr files, cr comments, cr open, status set, forge changes, pr view, pr checks, merge plan, merge execute, sync plan, whoami, branch protection',
     ),
   });
 }

package/cli-doctor.js

@@ -4,6 +4,7 @@ import {
   gitRemoteUrl,
   parseRemoteUrl,
   trustedBaseUrl,
+  normalizedForgeOrigin,
   assertConfigMatchesRemote,
   forgePacket,
   unknownForgeContext,
@@ -15,6 +16,12 @@ import {
   getEffectiveIngestMaxBytes,
   FORGE_INGEST_MAX_BYTES_ENV,
   MAX_FORGE_INGEST_ENV_BYTES,
+  resolveMergePolicy,
+  ALLOW_MISSING_CHECKS_ENV,
+  ALLOW_PENDING_CHECKS_ENV,
+  buildWriteReadiness,
+  writeReadinessHasWarnings,
+  buildApiReachabilityCheck,
 } from '@remogram/core';
 import { contextFromConfig } from './cli-io.js';
 
@@ -33,25 +40,23 @@ export function doctorSummary(checks) {
   return 'pass';
 }
 
-function finalizeDoctorPacket(ctx, checks, providerCapabilities) {
+function finalizeDoctorPacket(ctx, checks, providerCapabilities, writeConfig = null) {
   const summary = doctorSummary(checks);
   const error =
     summary === 'fail'
       ? forgeError(ERROR_CODES.CONFIG_INVALID, 'Doctor checks failed')
       : null;
-  return forgePacket(
-    PACKET_TYPES.PROVIDER_DOCTOR,
-    ctx,
-    {
-      summary,
-      checks,
-      provider_capabilities: providerCapabilities,
-    },
-    error,
-  );
+  const body = {
+    summary,
+    checks,
+    provider_capabilities: providerCapabilities,
+  };
+  if (writeConfig) body.write_config = writeConfig;
+  return forgePacket(PACKET_TYPES.PROVIDER_DOCTOR, ctx, body, error);
 }
 
-export async function buildDoctorPacket(cwd, providers) {
+export async function buildDoctorPacket(cwd, providers, options = {}) {
+  const { live = false } = options;
   const checks = [];
   const configPath = findConfigPath(cwd);
   let loaded = null;
@@ -132,12 +137,18 @@ export async function buildDoctorPacket(cwd, providers) {
       );
     } else {
       checks.push(doctorCheck('host_binding', 'pass', 'Configured host binding is trusted'));
+      if (config.baseUrl) {
+        ctx = { ...ctx, baseUrl: normalizedForgeOrigin(config) };
+      }
     }
   }
 
+  let writeConfig = null;
+
   if (providerCapabilities) {
     const envNames = providerCapabilities.auth_envs || [];
     const presentEnv = envNames.find((name) => Boolean(process.env[name])) || null;
+    const authPresent = Boolean(presentEnv);
     checks.push(
       doctorCheck(
         'auth',
@@ -148,17 +159,22 @@ export async function buildDoctorPacket(cwd, providers) {
     );
 
     if (providerCapabilities.write_support) {
-      const providerWrites = (providerCapabilities.write_commands || []).filter(Boolean);
-      const configuredWrites = Array.isArray(config?.write_commands) ? config.write_commands : [];
-      const missing = providerWrites.filter((name) => !configuredWrites.includes(name));
+      writeConfig = buildWriteReadiness(config, providerCapabilities, { authPresent });
+      const warn = writeReadinessHasWarnings(writeConfig);
+      const notReady = writeConfig.commands.filter(
+        (entry) => entry.provider_supported && !entry.ready,
+      );
+      const missingConfig = notReady.filter((entry) => !entry.configured).map((entry) => entry.id);
       checks.push(
         doctorCheck(
           'write_config',
-          missing.length ? 'warn' : 'pass',
-          missing.length
-            ? `Provider supports write commands but .remogram.json write_commands omits: ${missing.join(', ')}. Add ids for Remogram CLI/MCP writes, or use forge/CI tooling for those actions outside Remogram.`
-            : 'Consumer write_commands matches provider write surface',
-          { provider_write_commands: providerWrites, configured_write_commands: configuredWrites },
+          warn ? 'warn' : 'pass',
+          warn
+            ? missingConfig.length
+              ? `Provider supports write commands but .remogram.json write_commands omits: ${missingConfig.join(', ')}. Add ids for Remogram CLI/MCP writes, or use forge/CI tooling for those actions outside Remogram.`
+              : 'One or more configured write commands are not ready (check auth or provider support)'
+            : 'All provider write commands are configured and ready',
+          writeConfig,
         ),
       );
     }
@@ -205,7 +221,46 @@ export async function buildDoctorPacket(cwd, providers) {
     );
   }
 
-  checks.push(doctorCheck('api_reachability', 'skipped', 'Live API reachability is not checked by default'));
+  const mergePolicy = resolveMergePolicy(config);
+  if (mergePolicy.allow_missing_checks || mergePolicy.allow_pending_checks) {
+    checks.push(
+      doctorCheck(
+        'merge_policy',
+        'warn',
+        'Merge policy relaxes check blockers for merge plan and merge execute',
+        {
+          allow_missing_checks: mergePolicy.allow_missing_checks,
+          allow_pending_checks: mergePolicy.allow_pending_checks,
+          source: mergePolicy.source,
+          env_names: [ALLOW_MISSING_CHECKS_ENV, ALLOW_PENDING_CHECKS_ENV],
+        },
+      ),
+    );
+  } else {
+    checks.push(
+      doctorCheck(
+        'merge_policy',
+        'pass',
+        'Default merge policy — missing and pending checks block merge',
+        {
+          allow_missing_checks: false,
+          allow_pending_checks: false,
+          source: mergePolicy.source,
+        },
+      ),
+    );
+  }
+
+  const hostBindingPass = checks.some(
+    (check) => check.name === 'host_binding' && check.status === 'pass',
+  );
+  const configPass = checks.some((check) => check.name === 'config' && check.status === 'pass');
+  checks.push(
+    await buildApiReachabilityCheck(ctx, provider, {
+      live,
+      prerequisitesPass: live && configPass && hostBindingPass && parsed != null,
+    }),
+  );
 
-  return finalizeDoctorPacket(ctx, checks, providerCapabilities);
+  return finalizeDoctorPacket(ctx, checks, providerCapabilities, writeConfig);
 }

package/cli-io.js

@@ -1,15 +1,27 @@
-import { forgePacket, forgeErrorPacket, ERROR_CODES, forgeError } from '@remogram/core';
+import {
+  forgePacket,
+  forgeErrorPacket,
+  forgeError,
+  ERROR_CODES,
+  normalizedForgeOrigin,
+  trustedBaseUrl,
+  resolveMergePolicy,
+} from '@remogram/core';
 
 export function output(packet, asJson) {
   console.log(JSON.stringify(packet, null, asJson ? 2 : 0));
 }
 
 export function handleError(err, ctx, asJson) {
-  const fe = err.forgeError || {
-    code: ERROR_CODES.API_ERROR,
-    message: err.message,
-    status: err.status,
-  };
+  const fe =
+    err.forgeError
+    || (err.invalidArgs
+      ? forgeError(ERROR_CODES.INVALID_ARGS, err.invalidArgs)
+      : {
+          code: ERROR_CODES.API_ERROR,
+          message: err.message,
+          status: err.status,
+        });
   const baseCtx = ctx || {
     providerId: 'unknown',
     remoteName: 'origin',
@@ -25,7 +37,7 @@ export function handleError(err, ctx, asJson) {
 }
 
 export function contextFromConfig(config, cwd, parsed = null) {
-  return {
+  const ctx = {
     providerId: config.provider,
     remoteName: config.remote,
     repoId: parsed ? `${parsed.owner}/${parsed.repo}` : `${config.owner}/${config.repo}`,
@@ -33,4 +45,9 @@ export function contextFromConfig(config, cwd, parsed = null) {
     cwd,
     parsed,
   };
+  if (config.baseUrl && (!parsed || trustedBaseUrl(config, parsed.host))) {
+    ctx.baseUrl = normalizedForgeOrigin(config);
+  }
+  ctx.mergePolicy = resolveMergePolicy(config);
+  return ctx;
 }

package/index.js

@@ -30,7 +30,7 @@ export async function runCli(argv, options = {}) {
   const [group, sub] = positional;
 
   if (group === 'doctor' && sub == null) {
-    const packet = await buildDoctorPacket(cwd, providers);
+    const packet = await buildDoctorPacket(cwd, providers, { live: flags.live === true });
     output(packet, asJson);
     if (!packet.ok) process.exitCode = 1;
     return;
@@ -64,6 +64,7 @@ export async function runCli(argv, options = {}) {
   try {
     const packet = await dispatchForgeCommand({ group, sub, flags, positional, ctx, provider });
     output(packet, asJson);
+    if (!packet.ok) process.exitCode = 1;
   } catch (err) {
     handleError(err, ctx, asJson);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remogram/cli",
-  "version": "0.1.0-beta.6",
+  "version": "0.1.0-beta.9",
   "description": "Remogram forge boundary CLI",
   "type": "module",
   "license": "MIT",
@@ -27,11 +27,11 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@remogram/core": "0.1.0-beta.6",
-    "@remogram/provider-gitea-api": "0.1.0-beta.6",
-    "@remogram/provider-github-api": "0.1.0-beta.6",
-    "@remogram/provider-gitlab-api": "0.1.0-beta.6",
-    "@remogram/provider-gitea-tea": "0.1.0-beta.6",
-    "@remogram/provider-github-gh": "0.1.0-beta.6"
+    "@remogram/core": "0.1.0-beta.9",
+    "@remogram/provider-gitea-api": "0.1.0-beta.9",
+    "@remogram/provider-github-api": "0.1.0-beta.9",
+    "@remogram/provider-gitlab-api": "0.1.0-beta.9",
+    "@remogram/provider-gitea-tea": "0.1.0-beta.9",
+    "@remogram/provider-github-gh": "0.1.0-beta.9"
   }
 }