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

package/contracts/semantic-diff-facts.js

@@ -0,0 +1,168 @@
+/**
+ * Semantic diff fact inventory contract (wave 1 — registry and trust boundaries).
+ * Command implementations land in waves 2–6 per plan_semantic_diff_fact_inventory.
+ *
+ * @see topo/sdlc/decisions/semantic_diff_fact_layer.tg
+ * @see topo/sdlc/decisions/packet_trust_doctrine.tg
+ */
+
+import { forgePacket, FORBIDDEN_PACKET_KEYS, SCHEMA_VERSION } from './envelope.js';
+
+/** Authoritative v1 read/plan surface today. Fact inventory extends; does not replace. */
+export const V1_READ_PLAN_COMMANDS = Object.freeze([
+  'repo status',
+  'refs compare',
+  'refs inventory',
+  'cr inventory',
+  'pr view',
+  'pr checks',
+  'merge plan',
+  'sync plan',
+  'provider capabilities',
+  'doctor',
+  'whoami',
+  'branch protection',
+  'cr files',
+  'cr comments',
+  'forge changes',
+]);
+
+/** v1 write surface (Gitea cr open and status set in first slices). */
+export const V1_WRITE_COMMANDS = Object.freeze(['cr open', 'status set', 'merge execute', 'issue open']);
+
+/**
+ * Planned fact-inventory packet types (not emitted until wave 2+ commands ship).
+ * All use schema_version 1 envelope discipline via forgePacket.
+ */
+export const FACT_INVENTORY_PACKET_TYPES = Object.freeze({
+  REF_INVENTORY: 'ref_inventory',
+  CR_INVENTORY_SLICE: 'cr_inventory_slice',
+});
+
+/** Trusted structural envelope on every remogram packet (authoritative for agents). */
+export const TRUSTED_ENVELOPE_FIELDS = Object.freeze([
+  'type',
+  'schema_version',
+  'provider_id',
+  'remote_name',
+  'repo_id',
+  'base_url',
+  'observed_at',
+  'ok',
+]);
+
+/**
+ * Normalized enum and boolean body fields agents may treat as structural facts
+ * (not forge prose). Provider-specific strings that are normalized to enums
+ * belong here; raw forge copy does not.
+ */
+export const TRUSTED_NORMALIZED_BODY_FIELDS = Object.freeze({
+  mergeability: true,
+  check_conclusion: true,
+  checks_conclusion: true,
+  state: true,
+  truncated: true,
+  list_truncated: true,
+  checks_truncated: true,
+  paths_truncated: true,
+  comments_truncated: true,
+  events_truncated: true,
+  slice_sort: true,
+  entry_count: true,
+  mergeability_confidence: true,
+  write_support: true,
+  diverged: true,
+  auth_present: true,
+  can_write: true,
+  reused_existing: true,
+  created: true,
+  idempotency_fingerprint: true,
+  ambiguous_after_write: true,
+  idempotency_scan: true,
+});
+
+/**
+ * String leaves copied from forge or git resolution that remain semantically
+ * untrusted per decision_packet_trust_doctrine. Structurally sanitized only.
+ */
+export const FORGE_SOURCED_STRING_LEAVES = Object.freeze({
+  repo_status: ['default_branch', 'auth_env', 'capabilities'],
+  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'],
+  change_request_opened: ['url', 'title', 'head', 'base'],
+  commit_status_set: ['sha', 'context', 'description', 'target_url'],
+  provider_identity: ['login'],
+  branch_protection: [
+    'branch_ref',
+    'required_status_contexts[]',
+    'protected_branch_rules[].name',
+  ],
+  cr_files: ['changed_paths[]'],
+  cr_comments: ['comments[].id', 'comments[].author', 'comments[].path', 'comments[].body'],
+  forge_changes: ['events[].title', 'events[].url', 'events[].forge_source_sha'],
+  cr_inventory_slice: [
+    'entries[].url',
+    'entries[].title',
+    '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.forge_source_sha',
+    'entries[].checks[].context',
+    'entries[].checks[].description',
+  ],
+});
+
+/** Keys that must never appear in remogram output (external planning/SDLC workflow concepts). */
+export { FORBIDDEN_PACKET_KEYS };
+
+/**
+ * Documented body shapes for planned fact inventory packets (wave 2+).
+ * Used by contract tests and provider normalization; not emitted in wave 1.
+ */
+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<{ 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, 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',
+    list_truncated: 'boolean',
+    /** true when more pages remain via next_cursor */
+    has_more: 'boolean',
+    /** true when open-list enumeration is complete for slice_sort */
+    complete: 'boolean',
+    /** opaque cursor for the next page when has_more is true */
+    next_cursor: 'string optional',
+    /** numbers consumed from open-list ordering including skipped entries */
+    entry_count_observed: 'number',
+    /** normalized slice sort preset applied to open-list resolution */
+    slice_sort: 'string',
+    entries_skipped:
+      'array<{ pr_number: number, error_code: pr_not_open | api_error | oversized_raw_output | ... }> optional',
+    slice_ref: 'string optional',
+  },
+});
+
+/**
+ * Build a fact-inventory packet body through the standard envelope gate.
+ * Throws if body contains forbidden workflow/planning-tool keys.
+ */
+export function forgeFactInventoryPacket(type, context, body = {}, error = null) {
+  if (!Object.values(FACT_INVENTORY_PACKET_TYPES).includes(type)) {
+    throw new Error(`Unknown fact inventory packet type: ${type}`);
+  }
+  return forgePacket(type, context, body, error);
+}
+
+export { SCHEMA_VERSION };

package/cr-comments.js

@@ -0,0 +1,93 @@
+import { sanitizeField } from './caps.js';
+
+export const MAX_CR_COMMENTS = 256;
+
+export function normalizeCrComment(raw) {
+  if (raw == null || typeof raw !== 'object') return null;
+  const id = raw.id ?? raw.comment_id;
+  if (id == null) return null;
+
+  const author =
+    sanitizeField(
+      raw.author ??
+        raw.user?.login ??
+        raw.user?.username ??
+        raw.user?.name ??
+        '',
+    ) || null;
+  const path =
+    raw.path != null && String(raw.path).trim() !== '' ? sanitizeField(raw.path) : null;
+  const lineRaw = raw.line ?? raw.original_line ?? raw.new_line;
+  const line =
+    lineRaw != null && Number.isFinite(Number(lineRaw)) ? Math.floor(Number(lineRaw)) : null;
+  const body = sanitizeField(raw.body ?? raw.note ?? '') ?? '';
+  const resolved = Boolean(raw.resolved ?? raw.is_resolved ?? false);
+
+  return {
+    id: sanitizeField(String(id)),
+    author,
+    path,
+    line,
+    body,
+    resolved,
+  };
+}
+
+export function buildCrCommentsBody({ pr_number, comments, comments_truncated, comment_count }) {
+  const list = Array.isArray(comments) ? comments : [];
+  const count = Number.isFinite(Number(comment_count))
+    ? Math.floor(Number(comment_count))
+    : list.length;
+  return {
+    pr_number: Math.floor(Number(pr_number)),
+    comments: list,
+    comments_truncated: Boolean(comments_truncated),
+    comment_count: count,
+  };
+}
+
+function buildCrCommentsFromNormalizedList(prNumber, all) {
+  const comment_count = all.length;
+  const capped = all.length > MAX_CR_COMMENTS;
+  const comments = all.slice(0, MAX_CR_COMMENTS);
+  return buildCrCommentsBody({
+    pr_number: prNumber,
+    comments,
+    comments_truncated: capped,
+    comment_count,
+  });
+}
+
+export function buildCrCommentsFromGiteaComments(prNumber, commentsArray) {
+  const all = [];
+  if (Array.isArray(commentsArray)) {
+    for (const item of commentsArray) {
+      const normalized = normalizeCrComment(item);
+      if (normalized) all.push(normalized);
+    }
+  }
+  return buildCrCommentsFromNormalizedList(prNumber, all);
+}
+
+export function buildCrCommentsFromGitLabDiscussions(prNumber, discussionsArray) {
+  const all = [];
+  if (Array.isArray(discussionsArray)) {
+    for (const discussion of discussionsArray) {
+      const notes = Array.isArray(discussion?.notes) ? discussion.notes : [];
+      for (const note of notes) {
+        if (note?.system === true) continue;
+        const position = note.position && typeof note.position === 'object' ? note.position : null;
+        const normalized = normalizeCrComment({
+          id: note.id,
+          author: note.author?.username ?? note.author?.name ?? '',
+          path: position?.new_path ?? position?.old_path ?? null,
+          line: position?.new_line ?? position?.old_line ?? null,
+          body: note.body ?? '',
+          resolved: note.resolved ?? false,
+        });
+        if (normalized) all.push(normalized);
+      }
+    }
+  }
+  return buildCrCommentsFromNormalizedList(prNumber, all);
+}

package/cr-files.js

@@ -0,0 +1,62 @@
+import { sanitizeField } from './caps.js';
+
+export const MAX_CR_FILES_PATHS = 256;
+
+function sanitizePathList(filesArray) {
+  if (!Array.isArray(filesArray)) return [];
+  const paths = [];
+  for (const file of filesArray) {
+    if (file == null || typeof file !== 'object') continue;
+    const sanitized = sanitizeField(file.filename);
+    if (sanitized) paths.push(sanitized);
+  }
+  return paths;
+}
+
+export function buildCrFilesBody({ pr_number, changed_paths, paths_truncated, path_count }) {
+  const paths = Array.isArray(changed_paths) ? changed_paths : [];
+  const count = Number.isFinite(Number(path_count)) ? Math.floor(Number(path_count)) : paths.length;
+  return {
+    pr_number: Math.floor(Number(pr_number)),
+    changed_paths: paths,
+    paths_truncated: Boolean(paths_truncated),
+    path_count: count,
+  };
+}
+
+export function buildCrFilesFromGiteaFiles(prNumber, filesArray) {
+  const allPaths = sanitizePathList(filesArray);
+  const path_count = allPaths.length;
+  const capped = allPaths.length > MAX_CR_FILES_PATHS;
+  const changed_paths = allPaths.slice(0, MAX_CR_FILES_PATHS);
+  return buildCrFilesBody({
+    pr_number: prNumber,
+    changed_paths,
+    paths_truncated: capped,
+    path_count,
+  });
+}
+
+export function buildCrFilesFromGitLabChanges(prNumber, changesArray) {
+  const paths = [];
+  const seen = new Set();
+  if (Array.isArray(changesArray)) {
+    for (const change of changesArray) {
+      if (change == null || typeof change !== 'object') continue;
+      const path = sanitizeField(change.new_path ?? change.old_path ?? '');
+      if (path && !seen.has(path)) {
+        seen.add(path);
+        paths.push(path);
+      }
+    }
+  }
+  const path_count = paths.length;
+  const capped = paths.length > MAX_CR_FILES_PATHS;
+  const changed_paths = paths.slice(0, MAX_CR_FILES_PATHS);
+  return buildCrFilesBody({
+    pr_number: prNumber,
+    changed_paths,
+    paths_truncated: capped,
+    path_count,
+  });
+}

package/cr-inventory-cursor.js

@@ -0,0 +1,64 @@
+import { ERROR_CODES, forgeError } from './contracts/errors.js';
+import { normalizeCrInventorySort } from './open-pull-list.js';
+
+export const CR_INVENTORY_CURSOR_VERSION = 1;
+
+/**
+ * @param {{ sort: string, offset: number }} state
+ * @returns {string}
+ */
+export function encodeCrInventoryCursor(state) {
+  const sort = normalizeCrInventorySort(state.sort);
+  const offset = Number(state.offset);
+  if (!Number.isInteger(offset) || offset < 0) {
+    throw Object.assign(new Error('Invalid cursor offset'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, 'cursor offset must be a non-negative integer'),
+    });
+  }
+  const payload = JSON.stringify({ v: CR_INVENTORY_CURSOR_VERSION, sort, offset });
+  return Buffer.from(payload, 'utf8').toString('base64url');
+}
+
+/**
+ * @param {unknown} raw
+ * @param {{ sort?: string | null }} [opts]
+ * @returns {{ sort: string, offset: number }}
+ */
+export function decodeCrInventoryCursor(raw, opts = {}) {
+  if (raw == null || raw === '') {
+    throw Object.assign(new Error('Missing cursor'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--cursor must not be empty when provided'),
+    });
+  }
+  let decoded;
+  try {
+    decoded = JSON.parse(Buffer.from(String(raw), 'base64url').toString('utf8'));
+  } catch {
+    throw Object.assign(new Error('Invalid cursor'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--cursor is malformed or not base64url JSON'),
+    });
+  }
+  if (decoded?.v !== CR_INVENTORY_CURSOR_VERSION) {
+    throw Object.assign(new Error('Invalid cursor version'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--cursor version is unsupported'),
+    });
+  }
+  const sort = normalizeCrInventorySort(decoded.sort);
+  const offset = Number(decoded.offset);
+  if (!Number.isInteger(offset) || offset < 0) {
+    throw Object.assign(new Error('Invalid cursor offset'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--cursor offset must be a non-negative integer'),
+    });
+  }
+  const requestedSort =
+    opts.sort == null || opts.sort === '' ? null : normalizeCrInventorySort(opts.sort);
+  if (requestedSort != null && requestedSort !== sort) {
+    throw Object.assign(new Error('Cursor sort mismatch'), {
+      forgeError: forgeError(
+        ERROR_CODES.INVALID_ARGS,
+        '--sort must match the cursor slice_sort when both are provided',
+      ),
+    });
+  }
+  return { sort, offset };
+}

package/cr-inventory.js

@@ -0,0 +1,136 @@
+import { sanitizeField } from './caps.js';
+import { ERROR_CODES, forgeError } from './contracts/errors.js';
+import { decodeCrInventoryCursor, encodeCrInventoryCursor } from './cr-inventory-cursor.js';
+import { mergeBlockersFromFacts, isOpenPrState } from './merge-blockers.js';
+import {
+  DEFAULT_CR_INVENTORY_SLICE_SORT,
+  normalizeCrInventorySort,
+} from './open-pull-list.js';
+import { staleHeadDetails } from './pr-head-reconcile.js';
+
+export const DEFAULT_CR_INVENTORY_LIMIT = 50;
+/** Default bound when `--limit` is omitted (keeps forge ingest under cap on large repos). */
+export const DEFAULT_CR_INVENTORY_SAFE_LIMIT = 3;
+
+export function normalizeCrInventoryLimit(value) {
+  if (value == null || value === '') return DEFAULT_CR_INVENTORY_SAFE_LIMIT;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n <= 0) {
+    throw Object.assign(new Error('Invalid cr inventory limit'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--limit must be a positive integer'),
+    });
+  }
+  return n;
+}
+
+async function resolveOpenPullList(provider, ctx, listWindow, sliceSort) {
+  if (typeof provider.listOpenPullsWithMeta === 'function') {
+    return provider.listOpenPullsWithMeta(ctx, { retain_max: listWindow, sort: sliceSort });
+  }
+  const numbers = await provider.listOpenPulls(ctx, {});
+  return { numbers, list_truncated: false };
+}
+
+function skipErrorCode(err) {
+  if (err?.forgeError?.code) return err.forgeError.code;
+  return ERROR_CODES.API_ERROR;
+}
+
+export function buildHeadReconcile(ctx, view) {
+  const details = staleHeadDetails(
+    ctx.cwd,
+    ctx.config?.remote ?? ctx.remoteName,
+    view.forge_source_branch_ref,
+    view.forge_source_sha,
+  );
+  if (!details) return { stale: false };
+  return {
+    stale: true,
+    local_head_sha: details.local_head_sha,
+    forge_source_sha: details.forge_source_sha,
+  };
+}
+
+/**
+ * Compose one CR inventory entry from pr view and checks facts.
+ */
+export function buildCrInventoryEntry(ctx, view, checks) {
+  const entry = {
+    pr_number: view.pr_number,
+    url: view.url,
+    title: view.title,
+    state: view.state,
+    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, {}, ctx.mergePolicy ?? {}),
+    head_reconcile: buildHeadReconcile(ctx, view),
+  };
+  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;
+}
+
+/**
+ * Aggregate open change requests into a semantic-diff-oriented inventory slice.
+ * @param {object} ctx forge context
+ * @param {object} provider must expose listOpenPulls, prView, prChecks
+ * @param {{ slice_ref?: string, limit?: number, sort?: string, cursor?: string }} [opts]
+ */
+export async function crInventory(ctx, provider, opts = {}) {
+  const limit = normalizeCrInventoryLimit(opts.limit);
+  let sliceSort = normalizeCrInventorySort(opts.sort);
+  let offset = 0;
+  if (opts.cursor != null && opts.cursor !== '') {
+    const decoded = decodeCrInventoryCursor(opts.cursor, { sort: opts.sort });
+    offset = decoded.offset;
+    sliceSort = decoded.sort;
+  }
+
+  const listWindow = offset + limit;
+  const {
+    numbers,
+    list_truncated: listTruncated,
+    entry_count: providerEntryCount,
+  } = await resolveOpenPullList(provider, ctx, listWindow, sliceSort);
+  const entryCount = providerEntryCount ?? numbers.length;
+  const selected = numbers.slice(offset, offset + limit);
+  const entries = [];
+  const entries_skipped = [];
+  for (const number of selected) {
+    try {
+      const view = await provider.prView(ctx, { number });
+      if (!isOpenPrState(view.state)) {
+        entries_skipped.push({ pr_number: number, error_code: ERROR_CODES.PR_NOT_OPEN });
+        continue;
+      }
+      const checks = await provider.prChecks(ctx, { number });
+      entries.push(buildCrInventoryEntry(ctx, view, checks));
+    } catch (err) {
+      entries_skipped.push({
+        pr_number: number,
+        error_code: skipErrorCode(err),
+      });
+    }
+  }
+
+  const observedEnd = offset + selected.length;
+  const hasMore = listTruncated || observedEnd < entryCount;
+  const complete = !hasMore;
+
+  return {
+    entries,
+    ...(entries_skipped.length ? { entries_skipped } : {}),
+    entry_count: entryCount,
+    entry_count_observed: observedEnd,
+    truncated: entryCount > observedEnd || listTruncated,
+    list_truncated: listTruncated,
+    slice_sort: sliceSort ?? DEFAULT_CR_INVENTORY_SLICE_SORT,
+    has_more: hasMore,
+    complete,
+    ...(hasMore ? { next_cursor: encodeCrInventoryCursor({ sort: sliceSort, offset: observedEnd }) } : {}),
+    ...(opts.slice_ref ? { slice_ref: sanitizeField(opts.slice_ref) } : {}),
+  };
+}

package/cr-open.js

@@ -0,0 +1,38 @@
+import { sanitizeField, sanitizeUrl } from './caps.js';
+import { ERROR_CODES, forgeError } from './contracts/errors.js';
+
+/** Normalize Gitea pull create response into change_request_opened body fields. */
+export function buildChangeRequestOpenedBody(
+  pull,
+  { head, base, title },
+  { reusedExisting = false, idempotencyFields = null } = {},
+) {
+  const prNumber = Number(pull?.number);
+  if (!Number.isInteger(prNumber) || prNumber <= 0) {
+    throw Object.assign(new Error('Provider returned invalid pull number'), {
+      forgeError: forgeError(
+        ERROR_CODES.UNPARSEABLE_PROVIDER_OUTPUT,
+        'Provider returned invalid pull number',
+      ),
+    });
+  }
+  const resolvedTitle = reusedExisting
+    ? sanitizeField(pull?.title ?? title)
+    : sanitizeField(title ?? pull?.title);
+  const body = {
+    pr_number: prNumber,
+    url: sanitizeUrl(pull.html_url ?? pull.url),
+    head: sanitizeField(head),
+    base: sanitizeField(base),
+    title: resolvedTitle,
+  };
+  if (reusedExisting) {
+    body.reused_existing = true;
+  } else {
+    body.created = true;
+  }
+  if (idempotencyFields && typeof idempotencyFields === 'object') {
+    Object.assign(body, idempotencyFields);
+  }
+  return body;
+}

package/effective-write-policy.js

@@ -0,0 +1,68 @@
+import { WRITE_COMMAND_IDS } from './write-config.js';
+
+function uniqueSorted(list) {
+  return [...new Set(list.filter(Boolean))].sort((a, b) => a.localeCompare(b));
+}
+
+export function writeSourceForCommand(repoConfigured, operatorConfigured) {
+  if (repoConfigured && operatorConfigured) return 'both';
+  if (repoConfigured) return 'repo';
+  if (operatorConfigured) return 'operator';
+  return 'none';
+}
+
+/**
+ * @param {object} repoConfig
+ * @param {{ config?: object | null, meta?: object, error?: object | null }} operatorLoad
+ */
+export function resolveEffectiveWritePolicy(repoConfig, operatorLoad = {}) {
+  const repoWriteCommands = uniqueSorted(
+    Array.isArray(repoConfig?.write_commands) ? repoConfig.write_commands : [],
+  );
+  const operatorWriteCommands =
+    operatorLoad.error || !operatorLoad.config
+      ? []
+      : uniqueSorted(operatorLoad.config.write_commands ?? []);
+  const effectiveWriteCommands = uniqueSorted([...repoWriteCommands, ...operatorWriteCommands]);
+
+  return {
+    repoWriteCommands,
+    operatorWriteCommands,
+    effectiveWriteCommands,
+    operatorMeta: operatorLoad.meta ?? { discovered_via: 'none', path: null, bind_ok: null },
+    operatorError: operatorLoad.error ?? null,
+  };
+}
+
+export function isWriteCommandAllowed(writePolicy, commandName) {
+  if (!writePolicy || !commandName) return false;
+  return writePolicy.effectiveWriteCommands.includes(commandName);
+}
+
+export function writePolicyFromLegacyConfig(config) {
+  return resolveEffectiveWritePolicy(config, { config: null, meta: { discovered_via: 'none' }, error: null });
+}
+
+export function normalizeWritePolicyInput(input) {
+  if (input && Array.isArray(input.effectiveWriteCommands)) {
+    return input;
+  }
+  if (input?.writePolicy && Array.isArray(input.writePolicy.effectiveWriteCommands)) {
+    return input.writePolicy;
+  }
+  return writePolicyFromLegacyConfig(input);
+}
+
+export function buildOperatorConfigSnippet(commandId, operatorWriteCommands = []) {
+  const next = uniqueSorted([...operatorWriteCommands, commandId]);
+  return `"write_commands": ${JSON.stringify(next)}`;
+}
+
+export function buildRepoConfigSnippet(commandId, repoWriteCommands = []) {
+  const next = uniqueSorted([...repoWriteCommands, commandId]);
+  return `"write_commands": ${JSON.stringify(next)}`;
+}
+
+export function allKnownWriteCommandIds() {
+  return [...WRITE_COMMAND_IDS];
+}