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

package/cli-argv.js

@@ -0,0 +1,50 @@
+import { ERROR_CODES, forgeError } from '@remogram/core';
+
+export const REPEATABLE_FLAGS = new Set(['allowed_path']);
+
+export function parseAllowedPathFlags(flags) {
+  if (flags.allowed_path == null) return undefined;
+  return Array.isArray(flags.allowed_path) ? flags.allowed_path : [flags.allowed_path];
+}
+
+export function parsePositiveInt(value, name) {
+  if (value == null) return undefined;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n <= 0) {
+    throw Object.assign(new Error(`Invalid ${name}`), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, `${name} must be a positive integer`),
+    });
+  }
+  return n;
+}
+
+export function parseCliArgv(argv) {
+  const positional = [];
+  let asJson = false;
+  const flags = {};
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--json') asJson = true;
+    else if (arg.startsWith('--')) {
+      const key = arg.slice(2).replace(/-/g, '_');
+      const next = argv[i + 1];
+      if (REPEATABLE_FLAGS.has(key)) {
+        if (!flags[key]) flags[key] = [];
+        if (next != null && !next.startsWith('--')) {
+          flags[key].push(next);
+          i += 1;
+        }
+      } else if (next != null && !next.startsWith('--')) {
+        flags[key] = next;
+        i += 1;
+      } else {
+        flags[key] = true;
+      }
+    } else {
+      positional.push(arg);
+    }
+  }
+
+  return { positional, asJson, flags };
+}

package/cli-dispatch.js

@@ -0,0 +1,585 @@
+import {
+  forgePacket,
+  PACKET_TYPES,
+  ERROR_CODES,
+  forgeError,
+  sanitizeField,
+  assertGitRef,
+  assertGitRemote,
+  assertCrOpenBranchRef,
+  throwIfStaleHeadByNumber,
+  FACT_INVENTORY_PACKET_TYPES,
+  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';
+
+export async function dispatchForgeCommand({ group, sub, flags, positional, ctx, provider }) {
+  if (group === 'provider' && sub === 'capabilities') {
+    return forgePacket(
+      PACKET_TYPES.PROVIDER_CAPABILITIES,
+      ctx,
+      await provider.providerCapabilities(ctx),
+    );
+  }
+  if (group === 'repo' && sub === 'status') {
+    return forgePacket(PACKET_TYPES.REPO_STATUS, ctx, await provider.repoStatus(ctx));
+  }
+  if (group === 'refs' && sub === 'compare') {
+    if (!flags.base || !flags.head) {
+      throw Object.assign(new Error('--base and --head required'), {
+        forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--base and --head required'),
+      });
+    }
+    assertGitRef(flags.base, '--base');
+    assertGitRef(flags.head, '--head');
+    return forgePacket(
+      PACKET_TYPES.REF_COMPARE,
+      ctx,
+      await provider.refsCompare(ctx, flags.base, flags.head),
+    );
+  }
+  if (group === 'refs' && sub === 'inventory') {
+    if (typeof provider.refsInventory !== 'function') {
+      throw Object.assign(new Error('refs inventory not implemented for provider'), {
+        forgeError: forgeError(
+          ERROR_CODES.PROVIDER_UNSUPPORTED,
+          'refs inventory not implemented for provider',
+        ),
+      });
+    }
+    return forgeFactInventoryPacket(
+      FACT_INVENTORY_PACKET_TYPES.REF_INVENTORY,
+      ctx,
+      await provider.refsInventory(ctx),
+    );
+  }
+  if (group === 'cr' && sub === 'inventory') {
+    if (typeof provider.crInventory !== 'function') {
+      throw Object.assign(new Error('cr inventory not implemented for provider'), {
+        forgeError: forgeError(
+          ERROR_CODES.PROVIDER_UNSUPPORTED,
+          'cr inventory not implemented for provider',
+        ),
+      });
+    }
+    const inventoryBody = await provider.crInventory(ctx, {
+      slice_ref: flags.slice_ref,
+      limit: parsePositiveInt(flags.limit, '--limit'),
+      sort: flags.sort,
+      cursor: flags.cursor,
+    });
+    if (inventoryBody.list_truncated === true && !flags.cursor) {
+      throw Object.assign(new Error('Open CR list incomplete'), {
+        forgeError: forgeError(
+          ERROR_CODES.INVENTORY_LIST_INCOMPLETE,
+          'Open change request list could not be proved complete within pagination bounds',
+          null,
+          {
+            inventory_list: {
+              entry_count: inventoryBody.entry_count,
+            },
+          },
+        ),
+      });
+    }
+    return forgeFactInventoryPacket(
+      FACT_INVENTORY_PACKET_TYPES.CR_INVENTORY_SLICE,
+      ctx,
+      inventoryBody,
+    );
+  }
+  if (group === 'cr' && sub === 'files') {
+    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 cr files'),
+      });
+    }
+    if (typeof provider.crFiles !== 'function') {
+      throw Object.assign(new Error('cr files not implemented for provider'), {
+        forgeError: forgeError(
+          ERROR_CODES.PROVIDER_UNSUPPORTED,
+          'cr files not implemented for provider',
+        ),
+      });
+    }
+    return forgePacket(
+      PACKET_TYPES.CR_FILES,
+      ctx,
+      await provider.crFiles(ctx, { number }),
+    );
+  }
+  if (group === 'cr' && sub === 'comments') {
+    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 cr comments'),
+      });
+    }
+    if (typeof provider.crComments !== 'function') {
+      throw Object.assign(new Error('cr comments not implemented for provider'), {
+        forgeError: forgeError(
+          ERROR_CODES.PROVIDER_UNSUPPORTED,
+          'cr comments not implemented for provider',
+        ),
+      });
+    }
+    return forgePacket(
+      PACKET_TYPES.CR_COMMENTS,
+      ctx,
+      await provider.crComments(ctx, { number }),
+    );
+  }
+  if (group === 'forge' && sub === 'changes') {
+    if (typeof provider.forgeChanges !== 'function') {
+      throw Object.assign(new Error('forge changes not implemented for provider'), {
+        forgeError: forgeError(
+          ERROR_CODES.PROVIDER_UNSUPPORTED,
+          'forge changes not implemented for provider',
+        ),
+      });
+    }
+    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') {
+      throw Object.assign(new Error('cr open not implemented for provider'), {
+        forgeError: forgeError(
+          ERROR_CODES.PROVIDER_UNSUPPORTED,
+          'cr open not implemented for provider',
+        ),
+      });
+    }
+    if (!flags.head || !flags.base || !flags.title) {
+      throw Object.assign(new Error('--head, --base, and --title required'), {
+        forgeError: forgeError(
+          ERROR_CODES.INVALID_ARGS,
+          '--head, --base, and --title required for cr open',
+        ),
+      });
+    }
+    assertCrOpenBranchRef(flags.head, '--head');
+    assertCrOpenBranchRef(flags.base, '--base');
+    assertWriteCommandConfigured(ctx.writePolicy ?? 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,
+      await provider.crOpen(ctx, {
+        head: flags.head,
+        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.writePolicy ?? 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,
+      }),
+    );
+  }
+  if (group === 'status' && sub === 'set') {
+    if (typeof provider.statusSet !== 'function') {
+      throw Object.assign(new Error('status set not implemented for provider'), {
+        forgeError: forgeError(
+          ERROR_CODES.PROVIDER_UNSUPPORTED,
+          'status set not implemented for provider',
+        ),
+      });
+    }
+    assertWriteCommandConfigured(ctx.writePolicy ?? 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,
+      await provider.statusSet(ctx, {
+        sha: flags.sha,
+        context: flags.context,
+        state: flags.state,
+        target_url: flags.target_url,
+        description: flags.description,
+        idempotencyFingerprint,
+      }),
+    );
+  }
+  if (group === 'pr' && sub === 'view') {
+    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 pr view'),
+      });
+    }
+    const body = await provider.prView(ctx, { number });
+    throwIfStaleHeadByNumber(
+      ctx,
+      PACKET_TYPES.PR_STATUS,
+      body,
+      body.forge_source_branch_ref,
+      body.forge_source_sha,
+    );
+    return forgePacket(PACKET_TYPES.PR_STATUS, ctx, body);
+  }
+  if (group === 'pr' && sub === 'checks') {
+    const number = parsePositiveInt(flags.number, '--number');
+    if (number == null && !flags.ref) {
+      throw Object.assign(new Error('--number or --ref required'), {
+        forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--number or --ref required for pr checks'),
+      });
+    }
+    if (flags.ref) assertGitRef(flags.ref, '--ref');
+    if (number != null && !flags.ref) {
+      const view = await provider.prView(ctx, { number });
+      throwIfStaleHeadByNumber(
+        ctx,
+        PACKET_TYPES.PR_CHECKS,
+        { forge_source_sha: view.forge_source_sha },
+        view.forge_source_branch_ref,
+        view.forge_source_sha,
+      );
+    }
+    return forgePacket(
+      PACKET_TYPES.PR_CHECKS,
+      ctx,
+      await provider.prChecks(ctx, { number, ref: flags.ref }),
+    );
+  }
+  if (group === 'merge' && sub === 'plan') {
+    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 plan'),
+      });
+    }
+    const allowedPaths = normalizeAllowedPaths(parseAllowedPathFlags(flags) ?? []);
+    return forgePacket(
+      PACKET_TYPES.MERGE_PLAN,
+      ctx,
+      await provider.mergePlan(ctx, {
+        number,
+        ...(allowedPaths ? { allowed_paths: allowedPaths } : {}),
+      }),
+    );
+  }
+  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.writePolicy ?? 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) {
+      throw Object.assign(new Error('--branch-ref required'), {
+        forgeError: forgeError(
+          ERROR_CODES.INVALID_ARGS,
+          '--branch-ref required for branch protection',
+        ),
+      });
+    }
+    assertGitRef(branchRef, '--branch-ref');
+    if (typeof provider.branchProtection !== 'function') {
+      throw Object.assign(new Error('branch protection not implemented for provider'), {
+        forgeError: forgeError(
+          ERROR_CODES.PROVIDER_UNSUPPORTED,
+          'branch protection not implemented for provider',
+        ),
+      });
+    }
+    return forgePacket(
+      PACKET_TYPES.BRANCH_PROTECTION,
+      ctx,
+      await provider.branchProtection(ctx, { branchRef }),
+    );
+  }
+  if (group === 'whoami' && sub == null) {
+    if (typeof provider.whoami !== 'function') {
+      throw Object.assign(new Error('whoami not implemented for provider'), {
+        forgeError: forgeError(
+          ERROR_CODES.PROVIDER_UNSUPPORTED,
+          'whoami not implemented for provider',
+        ),
+      });
+    }
+    return forgePacket(PACKET_TYPES.PROVIDER_IDENTITY, ctx, await provider.whoami(ctx));
+  }
+  if (group === 'sync' && sub === 'plan') {
+    const remote = flags.remote || ctx.config.remote;
+    assertGitRemote(remote, '--remote');
+    return forgePacket(
+      PACKET_TYPES.SYNC_PLAN,
+      ctx,
+      await provider.syncPlan(ctx, remote),
+    );
+  }
+
+  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, merge execute, sync plan, whoami, branch protection',
+    ),
+  });
+}

package/cli-doctor.js

@@ -0,0 +1,358 @@
+import {
+  loadConfig,
+  findConfigPath,
+  gitRemoteUrl,
+  parseRemoteUrl,
+  trustedBaseUrl,
+  normalizedForgeOrigin,
+  assertConfigMatchesRemote,
+  forgePacket,
+  unknownForgeContext,
+  PACKET_TYPES,
+  ERROR_CODES,
+  forgeError,
+  sanitizeField,
+  assertGitRemote,
+  getEffectiveIngestMaxBytes,
+  FORGE_INGEST_MAX_BYTES_ENV,
+  MAX_FORGE_INGEST_ENV_BYTES,
+  resolveMergePolicy,
+  ALLOW_MISSING_CHECKS_ENV,
+  ALLOW_PENDING_CHECKS_ENV,
+  buildWriteReadiness,
+  writeReadinessHasWarnings,
+  buildApiReachabilityCheck,
+  resolveWritePolicyForForge,
+  forgeWriteFieldCapabilityFacts,
+  resolveEffectiveWriteFieldPolicy,
+  loadOperatorConfig,
+  WRITE_FIELD_MAX_BYTES_ENV,
+  MAX_WRITE_FIELD_ENV_BYTES,
+} from '@remogram/core';
+import { contextFromConfig } from './cli-io.js';
+
+export function doctorCheck(name, status, message, details = null) {
+  return {
+    name,
+    status,
+    message: sanitizeField(message),
+    ...(details ? { details } : {}),
+  };
+}
+
+export function doctorSummary(checks) {
+  if (checks.some((check) => check.status === 'fail')) return 'fail';
+  if (checks.some((check) => check.status === 'warn')) return 'warn';
+  return 'pass';
+}
+
+function finalizeDoctorPacket(ctx, checks, providerCapabilities, writeConfig = null) {
+  const summary = doctorSummary(checks);
+  const error =
+    summary === 'fail'
+      ? forgeError(ERROR_CODES.CONFIG_INVALID, 'Doctor checks failed')
+      : null;
+  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, options = {}) {
+  const { live = false, operatorConfigPath = null } = options;
+  const checks = [];
+  const configPath = findConfigPath(cwd);
+  let loaded = null;
+  let config = null;
+  let parsed = null;
+  let ctx = unknownForgeContext();
+  let providerCapabilities = null;
+
+  if (!configPath) {
+    checks.push(doctorCheck('config', 'fail', 'No .remogram.json found'));
+    return finalizeDoctorPacket(ctx, checks, null);
+  }
+
+  try {
+    loaded = loadConfig(cwd);
+    config = loaded.config;
+    ctx = contextFromConfig(config, loaded.cwd);
+    checks.push(doctorCheck('config', 'pass', '.remogram.json is present and valid'));
+  } catch (err) {
+    checks.push(doctorCheck('config', 'fail', err.forgeError?.message || err.message));
+    return finalizeDoctorPacket(ctx, checks, null);
+  }
+
+  const provider = providers[config.provider];
+  if (!provider) {
+    checks.push(doctorCheck('provider', 'fail', `Unsupported provider: ${config.provider}`));
+  }
+
+  try {
+    assertGitRemote(config.remote, 'config.remote');
+    const remoteUrl = gitRemoteUrl(loaded.cwd, config.remote);
+    parsed = parseRemoteUrl(remoteUrl);
+    if (!parsed) {
+      checks.push(doctorCheck('remote', 'fail', 'Could not parse git remote URL'));
+    } else {
+      ctx = contextFromConfig(config, loaded.cwd, parsed);
+      checks.push(doctorCheck('remote', 'pass', 'Git remote URL parses successfully', {
+        host: sanitizeField(parsed.host),
+        owner: sanitizeField(parsed.owner),
+        repo: sanitizeField(parsed.repo),
+      }));
+    }
+  } catch (err) {
+    checks.push(doctorCheck('remote', 'fail', err.forgeError?.message || err.message));
+  }
+
+  if (parsed) {
+    try {
+      assertConfigMatchesRemote(config, parsed);
+      checks.push(doctorCheck('repo_match', 'pass', 'Config owner/repo matches git remote'));
+    } catch (err) {
+      checks.push(doctorCheck('repo_match', 'fail', err.forgeError?.message || err.message));
+    }
+
+    if (config.baseUrl && !trustedBaseUrl(config, parsed.host)) {
+      checks.push(
+        doctorCheck('host_binding', 'fail', `baseUrl host does not match remote host ${parsed.host}`),
+      );
+    } else {
+      checks.push(doctorCheck('host_binding', 'pass', 'Configured host binding is trusted'));
+      if (config.baseUrl) {
+        ctx = { ...ctx, baseUrl: normalizedForgeOrigin(config) };
+      }
+    }
+  }
+
+  if (parsed && loaded) {
+    const operatorLoad = loadOperatorConfig({ cliPath: operatorConfigPath, forgeContext: ctx });
+    ctx.writeFieldPolicy = resolveEffectiveWriteFieldPolicy(config, operatorLoad);
+  }
+
+  if (provider) {
+    if (typeof provider.providerCapabilities === 'function') {
+      providerCapabilities = await provider.providerCapabilities(ctx);
+      const stubProvider =
+        providerCapabilities.commands?.length > 0
+        && providerCapabilities.commands.every((command) => command.implemented === false);
+      checks.push(
+        doctorCheck(
+          'provider',
+          stubProvider ? 'warn' : 'pass',
+          stubProvider
+            ? `${config.provider} is not fully supported in v1; use an *-api provider`
+            : `${config.provider} is registered`,
+        ),
+      );
+      checks.push(doctorCheck('capabilities', 'pass', 'Provider capabilities are available'));
+    } else {
+      checks.push(doctorCheck('provider', 'pass', `${config.provider} is registered`));
+      checks.push(doctorCheck('capabilities', 'fail', 'Provider capabilities are not implemented'));
+    }
+  }
+
+  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',
+        presentEnv ? 'pass' : 'warn',
+        presentEnv ? `${presentEnv} is present` : 'No provider auth environment variable is set',
+        { env_names: envNames, present_env: presentEnv },
+      ),
+    );
+
+    if (providerCapabilities.write_support) {
+      const writePolicy = resolveWritePolicyForForge(ctx, { operatorConfigPath });
+      writeConfig = buildWriteReadiness(writePolicy, 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);
+      if (writePolicy.operatorMeta?.discovered_via && writePolicy.operatorMeta.discovered_via !== 'none') {
+        if (writePolicy.operatorError) {
+          checks.push(
+            doctorCheck(
+              'operator_config',
+              'fail',
+              writePolicy.operatorError.message,
+              {
+                ...writePolicy.operatorMeta,
+                ...(writePolicy.operatorError.fields ? { bind_error: writePolicy.operatorError.fields } : {}),
+              },
+            ),
+          );
+        } else {
+          checks.push(
+            doctorCheck(
+              'operator_config',
+              'pass',
+              'Operator write overlay loaded and bound to forge identity',
+              writePolicy.operatorMeta,
+            ),
+          );
+        }
+      } else {
+        checks.push(
+          doctorCheck(
+            'operator_config',
+            'pass',
+            'No operator write overlay configured (repo-only write policy)',
+            { discovered_via: 'none', path: null, bind_ok: null },
+          ),
+        );
+      }
+      checks.push(
+        doctorCheck(
+          'write_config',
+          warn ? 'warn' : 'pass',
+          warn
+            ? missingConfig.length
+              ? `Provider supports write commands but effective write_commands omits: ${missingConfig.join(', ')}. Add ids to .remogram.json or a bound operator config (REMOGRAM_OPERATOR_CONFIG / --operator-config) for Remogram CLI/MCP writes, or use forge/CI tooling for those actions outside Remogram.`
+              : writePolicy.operatorError
+                ? 'Operator write overlay failed validation; writes are blocked until bind and schema checks pass'
+                : 'One or more configured write commands are not ready (check auth or provider support)'
+            : 'All provider write commands are configured and ready',
+          writeConfig,
+        ),
+      );
+    }
+
+    if (!providerCapabilities.check_sources?.length) {
+      checks.push(doctorCheck('checks', 'warn', 'Provider does not report forge check sources'));
+    } else {
+      checks.push(doctorCheck('checks', 'pass', 'Provider reports forge check sources', {
+        sources: providerCapabilities.check_sources,
+      }));
+    }
+  }
+
+  const { bytes: ingestCapBytes, envOverride: ingestEnvOverride, invalidEnv: ingestInvalidEnv, clamped: ingestClamped } =
+    getEffectiveIngestMaxBytes();
+  if (ingestInvalidEnv) {
+    checks.push(
+      doctorCheck(
+        'forge_ingest_cap',
+        'warn',
+        `${FORGE_INGEST_MAX_BYTES_ENV} is invalid; using default 8192 bytes`,
+        { effective_bytes: ingestCapBytes, env_override: false },
+      ),
+    );
+  } else if (ingestEnvOverride) {
+    checks.push(
+      doctorCheck(
+        'forge_ingest_cap',
+        'warn',
+        ingestClamped
+          ? `${FORGE_INGEST_MAX_BYTES_ENV} exceeds max ${MAX_FORGE_INGEST_ENV_BYTES}; clamped — agent-safe guarantee is weakened`
+          : `${FORGE_INGEST_MAX_BYTES_ENV} overrides default ingest cap; agent-safe guarantee is weakened`,
+        { effective_bytes: ingestCapBytes, env_override: true, ...(ingestClamped ? { clamped: true } : {}) },
+      ),
+    );
+  } else {
+    checks.push(
+      doctorCheck(
+        'forge_ingest_cap',
+        'pass',
+        'Forge HTTP ingest cap is default 8192 bytes',
+        { effective_bytes: ingestCapBytes, env_override: false },
+      ),
+    );
+  }
+
+  const writeFieldFacts = forgeWriteFieldCapabilityFacts(ctx.writeFieldPolicy);
+  if (writeFieldFacts.write_field_env_invalid) {
+    checks.push(
+      doctorCheck(
+        'forge_write_field_cap',
+        'warn',
+        `${WRITE_FIELD_MAX_BYTES_ENV} is invalid; using configured/default write field cap`,
+        writeFieldFacts,
+      ),
+    );
+  } else if (writeFieldFacts.write_field_env_override) {
+    checks.push(
+      doctorCheck(
+        'forge_write_field_cap',
+        'warn',
+        writeFieldFacts.write_field_cap_clamped
+          ? `${WRITE_FIELD_MAX_BYTES_ENV} exceeds max ${MAX_WRITE_FIELD_ENV_BYTES}; clamped — agent-safe guarantee is weakened`
+          : writeFieldFacts.write_field_uncapped
+            ? `${WRITE_FIELD_MAX_BYTES_ENV} disables forge write field cap; agent-safe guarantee is weakened`
+            : `${WRITE_FIELD_MAX_BYTES_ENV} overrides forge write field cap; agent-safe guarantee is weakened`,
+        writeFieldFacts,
+      ),
+    );
+  } else if (writeFieldFacts.write_field_uncapped) {
+    checks.push(
+      doctorCheck(
+        'forge_write_field_cap',
+        'warn',
+        'Forge write bodies are uncapped for this binding (read packets remain capped at 512 bytes)',
+        writeFieldFacts,
+      ),
+    );
+  } else {
+    checks.push(
+      doctorCheck(
+        'forge_write_field_cap',
+        'pass',
+        `Forge write field cap is ${writeFieldFacts.write_field_max_bytes} bytes (read cap fixed at 512)`,
+        writeFieldFacts,
+      ),
+    );
+  }
+
+  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, writeConfig);
+}

package/cli-io.js

@@ -0,0 +1,53 @@
+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
+    || (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',
+    repoId: 'unknown/unknown',
+  };
+  if (err.staleHeadPacket) {
+    output(forgePacket(err.staleHeadPacket.type, baseCtx, err.staleHeadPacket.body, fe), asJson);
+    process.exitCode = 1;
+    return;
+  }
+  output(forgeErrorPacket(baseCtx, fe), asJson);
+  process.exitCode = 1;
+}
+
+export function contextFromConfig(config, cwd, parsed = null) {
+  const ctx = {
+    providerId: config.provider,
+    remoteName: config.remote,
+    repoId: parsed ? `${parsed.owner}/${parsed.repo}` : `${config.owner}/${config.repo}`,
+    config,
+    cwd,
+    parsed,
+  };
+  if (config.baseUrl && (!parsed || trustedBaseUrl(config, parsed.host))) {
+    ctx.baseUrl = normalizedForgeOrigin(config);
+  }
+  ctx.mergePolicy = resolveMergePolicy(config);
+  return ctx;
+}

package/index.js

@@ -1,27 +1,19 @@
 import {
   loadConfig,
-  findConfigPath,
   assertForgeReady,
-  gitRemoteUrl,
-  parseRemoteUrl,
-  trustedBaseUrl,
-  assertConfigMatchesRemote,
   forgeContext,
-  forgePacket,
-  forgeErrorPacket,
-  unknownForgeContext,
-  PACKET_TYPES,
   ERROR_CODES,
   forgeError,
-  sanitizeField,
-  assertGitRef,
-  assertGitRemote,
 } from '@remogram/core';
 import { provider as giteaApi } from '@remogram/provider-gitea-api';
 import { provider as githubApi } from '@remogram/provider-github-api';
 import { provider as gitlabApi } from '@remogram/provider-gitlab-api';
 import { provider as giteaTea } from '@remogram/provider-gitea-tea';
 import { provider as githubGh } from '@remogram/provider-github-gh';
+import { output, handleError } from './cli-io.js';
+import { parseCliArgv } from './cli-argv.js';
+import { buildDoctorPacket } from './cli-doctor.js';
+import { dispatchForgeCommand } from './cli-dispatch.js';
 
 const PROVIDERS = {
   'gitea-api': giteaApi,
@@ -31,208 +23,28 @@ const PROVIDERS = {
   'github-gh': githubGh,
 };
 
-function parsePositiveInt(value, name) {
-  if (value == null) return undefined;
-  const n = Number(value);
-  if (!Number.isInteger(n) || n <= 0) {
-    throw Object.assign(new Error(`Invalid ${name}`), {
-      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, `${name} must be a positive integer`),
-    });
-  }
-  return n;
-}
-
-function output(packet, asJson) {
-  console.log(JSON.stringify(packet, null, asJson ? 2 : 0));
-}
-
-function handleError(err, ctx, asJson) {
-  const fe = err.forgeError || {
-    code: ERROR_CODES.API_ERROR,
-    message: err.message,
-    status: err.status,
-  };
-  const baseCtx = ctx || {
-    providerId: 'unknown',
-    remoteName: 'origin',
-    repoId: 'unknown/unknown',
-  };
-  output(forgeErrorPacket(baseCtx, fe), asJson);
-  process.exitCode = 1;
-}
-
-function doctorCheck(name, status, message, details = null) {
-  return {
-    name,
-    status,
-    message: sanitizeField(message),
-    ...(details ? { details } : {}),
-  };
-}
-
-function doctorSummary(checks) {
-  if (checks.some((check) => check.status === 'fail')) return 'fail';
-  if (checks.some((check) => check.status === 'warn')) return 'warn';
-  return 'pass';
-}
-
-function contextFromConfig(config, cwd, parsed = null) {
-  return {
-    providerId: config.provider,
-    remoteName: config.remote,
-    repoId: parsed ? `${parsed.owner}/${parsed.repo}` : `${config.owner}/${config.repo}`,
-    config,
-    cwd,
-    parsed,
-  };
-}
-
-async function buildDoctorPacket(cwd, providers) {
-  const checks = [];
-  const configPath = findConfigPath(cwd);
-  let loaded = null;
-  let config = null;
-  let parsed = null;
-  let ctx = unknownForgeContext();
-  let providerCapabilities = null;
-
-  if (!configPath) {
-    checks.push(doctorCheck('config', 'fail', 'No .remogram.json found'));
-    return forgePacket(PACKET_TYPES.PROVIDER_DOCTOR, ctx, {
-      summary: doctorSummary(checks),
-      checks,
-      provider_capabilities: null,
-    });
-  }
-
-  try {
-    loaded = loadConfig(cwd);
-    config = loaded.config;
-    ctx = contextFromConfig(config, loaded.cwd);
-    checks.push(doctorCheck('config', 'pass', '.remogram.json is present and valid'));
-  } catch (err) {
-    checks.push(doctorCheck('config', 'fail', err.forgeError?.message || err.message));
-    return forgePacket(PACKET_TYPES.PROVIDER_DOCTOR, ctx, {
-      summary: doctorSummary(checks),
-      checks,
-      provider_capabilities: null,
-    });
-  }
-
-  const provider = providers[config.provider];
-  if (!provider) {
-    checks.push(doctorCheck('provider', 'fail', `Unsupported provider: ${config.provider}`));
-  } else {
-    checks.push(doctorCheck('provider', 'pass', `${config.provider} is registered`));
-    if (typeof provider.providerCapabilities === 'function') {
-      providerCapabilities = await provider.providerCapabilities(ctx);
-      checks.push(doctorCheck('capabilities', 'pass', 'Provider capabilities are available'));
-    } else {
-      checks.push(doctorCheck('capabilities', 'fail', 'Provider capabilities are not implemented'));
-    }
-  }
-
-  let remoteUrl = null;
-  try {
-    assertGitRemote(config.remote, 'config.remote');
-    remoteUrl = gitRemoteUrl(loaded.cwd, config.remote);
-    parsed = parseRemoteUrl(remoteUrl);
-    if (!parsed) {
-      checks.push(doctorCheck('remote', 'fail', 'Could not parse git remote URL'));
-    } else {
-      ctx = contextFromConfig(config, loaded.cwd, parsed);
-      checks.push(doctorCheck('remote', 'pass', 'Git remote URL parses successfully', {
-        host: sanitizeField(parsed.host),
-        owner: sanitizeField(parsed.owner),
-        repo: sanitizeField(parsed.repo),
-      }));
-    }
-  } catch (err) {
-    checks.push(doctorCheck('remote', 'fail', err.forgeError?.message || err.message));
-  }
-
-  if (parsed) {
-    try {
-      assertConfigMatchesRemote(config, parsed);
-      checks.push(doctorCheck('repo_match', 'pass', 'Config owner/repo matches git remote'));
-    } catch (err) {
-      checks.push(doctorCheck('repo_match', 'fail', err.forgeError?.message || err.message));
-    }
-
-    if (config.baseUrl && !trustedBaseUrl(config, parsed.host)) {
-      checks.push(
-        doctorCheck('host_binding', 'fail', `baseUrl host does not match remote host ${parsed.host}`),
-      );
-    } else {
-      checks.push(doctorCheck('host_binding', 'pass', 'Configured host binding is trusted'));
-    }
-  }
-
-  if (providerCapabilities) {
-    const envNames = providerCapabilities.auth_envs || [];
-    const presentEnv = envNames.find((name) => Boolean(process.env[name])) || null;
-    checks.push(
-      doctorCheck(
-        'auth',
-        presentEnv ? 'pass' : 'warn',
-        presentEnv ? `${presentEnv} is present` : 'No provider auth environment variable is set',
-        { env_names: envNames, present_env: presentEnv },
-      ),
-    );
-
-    if (!providerCapabilities.check_sources?.length) {
-      checks.push(doctorCheck('checks', 'warn', 'Provider does not report forge check sources'));
-    } else {
-      checks.push(doctorCheck('checks', 'pass', 'Provider reports forge check sources', {
-        sources: providerCapabilities.check_sources,
-      }));
-    }
-  }
-
-  checks.push(doctorCheck('api_reachability', 'skipped', 'Live API reachability is not checked by default'));
-
-  return forgePacket(PACKET_TYPES.PROVIDER_DOCTOR, ctx, {
-    summary: doctorSummary(checks),
-    checks,
-    provider_capabilities: providerCapabilities,
-  });
-}
-
 export async function runCli(argv, options = {}) {
   const cwd = options.cwd ?? process.env.REMOGRAM_CWD ?? process.cwd();
   const providers = options.providers ?? PROVIDERS;
-  const positional = [];
-  let asJson = false;
-  const flags = {};
-
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    if (arg === '--json') asJson = true;
-    else if (arg.startsWith('--')) {
-      const key = arg.slice(2).replace(/-/g, '_');
-      const next = argv[i + 1];
-      if (next != null && !next.startsWith('--')) {
-        flags[key] = next;
-        i += 1;
-      } else {
-        flags[key] = true;
-      }
-    } else {
-      positional.push(arg);
-    }
-  }
-
+  const { positional, asJson, flags } = parseCliArgv(argv);
+  const operatorConfigPath =
+    options.operatorConfigPath ?? flags.operator_config ?? null;
   const [group, sub] = positional;
 
   if (group === 'doctor' && sub == null) {
-    output(await buildDoctorPacket(cwd, providers), asJson);
+    const packet = await buildDoctorPacket(cwd, providers, {
+      live: flags.live === true,
+      operatorConfigPath,
+    });
+    output(packet, asJson);
+    if (!packet.ok) process.exitCode = 1;
     return;
   }
 
   let ctx;
   try {
     const loaded = assertForgeReady(loadConfig(cwd));
-    ctx = forgeContext(loaded);
+    ctx = forgeContext(loaded, { operatorConfigPath });
   } catch (err) {
     handleError(err, null, asJson);
     return;
@@ -255,74 +67,9 @@ export async function runCli(argv, options = {}) {
   }
 
   try {
-    let packet;
-    if (group === 'provider' && sub === 'capabilities') {
-      packet = forgePacket(
-        PACKET_TYPES.PROVIDER_CAPABILITIES,
-        ctx,
-        await provider.providerCapabilities(ctx),
-      );
-    } else if (group === 'repo' && sub === 'status') {
-      packet = forgePacket(PACKET_TYPES.REPO_STATUS, ctx, await provider.repoStatus(ctx));
-    } else if (group === 'refs' && sub === 'compare') {
-      if (!flags.base || !flags.head) {
-        throw Object.assign(new Error('--base and --head required'), {
-          forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--base and --head required'),
-        });
-      }
-      assertGitRef(flags.base, '--base');
-      assertGitRef(flags.head, '--head');
-      packet = forgePacket(
-        PACKET_TYPES.REF_COMPARE,
-        ctx,
-        await provider.refsCompare(ctx, flags.base, flags.head),
-      );
-    } else if (group === 'pr' && sub === 'view') {
-      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 pr view'),
-        });
-      }
-      packet = forgePacket(PACKET_TYPES.PR_STATUS, ctx, await provider.prView(ctx, { number }));
-    } else if (group === 'pr' && sub === 'checks') {
-      const number = parsePositiveInt(flags.number, '--number');
-      if (number == null && !flags.ref) {
-        throw Object.assign(new Error('--number or --ref required'), {
-          forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--number or --ref required for pr checks'),
-        });
-      }
-      if (flags.ref) assertGitRef(flags.ref, '--ref');
-      packet = forgePacket(
-        PACKET_TYPES.PR_CHECKS,
-        ctx,
-        await provider.prChecks(ctx, { number, ref: flags.ref }),
-      );
-    } else if (group === 'merge' && sub === 'plan') {
-      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 plan'),
-        });
-      }
-      packet = forgePacket(PACKET_TYPES.MERGE_PLAN, ctx, await provider.mergePlan(ctx, { number }));
-    } else if (group === 'sync' && sub === 'plan') {
-      const remote = flags.remote || ctx.config.remote;
-      assertGitRemote(remote, '--remote');
-      packet = forgePacket(
-        PACKET_TYPES.SYNC_PLAN,
-        ctx,
-        await provider.syncPlan(ctx, remote),
-      );
-    } else {
-      throw Object.assign(new Error(`Unknown command: ${positional.join(' ')}`), {
-        forgeError: forgeError(
-          ERROR_CODES.INVALID_ARGS,
-          'Unknown command. Try: provider capabilities, repo status, refs compare, pr view, pr checks, merge plan, sync plan',
-        ),
-      });
-    }
+    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.0",
+  "version": "0.1.0-beta.10",
   "description": "Remogram forge boundary CLI",
   "type": "module",
   "license": "MIT",
@@ -27,11 +27,11 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@remogram/core": "0.1.0-beta.0",
-    "@remogram/provider-gitea-api": "0.1.0-beta.0",
-    "@remogram/provider-github-api": "0.1.0-beta.0",
-    "@remogram/provider-gitlab-api": "0.1.0-beta.0",
-    "@remogram/provider-gitea-tea": "0.1.0-beta.0",
-    "@remogram/provider-github-gh": "0.1.0-beta.0"
+    "@remogram/core": "0.1.0-beta.10",
+    "@remogram/provider-gitea-api": "0.1.0-beta.10",
+    "@remogram/provider-github-api": "0.1.0-beta.10",
+    "@remogram/provider-gitlab-api": "0.1.0-beta.10",
+    "@remogram/provider-gitea-tea": "0.1.0-beta.10",
+    "@remogram/provider-github-gh": "0.1.0-beta.10"
   }
 }