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

package/open-pull-list.js

@@ -0,0 +1,256 @@
+import { ERROR_CODES, forgeError } from './contracts/errors.js';
+
+/** Normalized slice sort keys exposed on CLI/MCP and success packets. */
+export const CR_INVENTORY_SLICE_SORTS = Object.freeze([
+  'number_asc',
+  'number_desc',
+  'recent_update',
+  'recent_created',
+]);
+
+export const DEFAULT_CR_INVENTORY_SLICE_SORT = 'number_asc';
+
+/**
+ * @param {unknown} value
+ * @returns {typeof CR_INVENTORY_SLICE_SORTS[number]}
+ */
+export function normalizeCrInventorySort(value) {
+  if (value == null || value === '') return DEFAULT_CR_INVENTORY_SLICE_SORT;
+  const sort = String(value).trim().toLowerCase();
+  if (!CR_INVENTORY_SLICE_SORTS.includes(sort)) {
+    throw Object.assign(new Error('Invalid cr inventory sort'), {
+      forgeError: forgeError(
+        ERROR_CODES.INVALID_ARGS,
+        `--sort must be one of: ${CR_INVENTORY_SLICE_SORTS.join(', ')}`,
+      ),
+    });
+  }
+  return sort;
+}
+
+/**
+ * Parse forge total-count response header as a positive integer within sanity bounds.
+ * @param {Headers | Record<string, string> | null | undefined} headers
+ * @param {string} headerName
+ * @param {{ maxTrusted: number }} opts
+ * @returns {number | null}
+ */
+export function parseTotalCountHeader(headers, headerName, { maxTrusted }) {
+  if (headers == null || maxTrusted <= 0) return null;
+  const read =
+    typeof headers.get === 'function'
+      ? (name) => headers.get(name)
+      : (name) => headers[name] ?? headers[String(name).toLowerCase()];
+  const raw = read(headerName) ?? read(String(headerName).toLowerCase());
+  if (raw == null || raw === '') return null;
+  const n = Number.parseInt(String(raw).trim(), 10);
+  if (!Number.isFinite(n) || n <= 0 || n > maxTrusted) return null;
+  return n;
+}
+
+/**
+ * Fast path applies to cr inventory retain_max slices, not idempotency scans.
+ * @param {{ retain_max?: number | null, limit?: number | null }} opts
+ */
+export function isCrInventoryFastPathEligible(opts = {}) {
+  return (
+    opts.retain_max != null &&
+    Number.isInteger(Number(opts.retain_max)) &&
+    Number(opts.retain_max) > 0
+  );
+}
+
+/**
+ * When forge order is authoritative, skip client-side number reordering.
+ * @param {string} sliceSort
+ */
+export function forgeOrderAuthoritative(sliceSort) {
+  return sliceSort === 'recent_update' || sliceSort === 'recent_created';
+}
+
+/**
+ * Fast path requires the first page to contain the expected item count.
+ * @param {number} totalCount
+ * @param {number} requestLimit
+ * @param {number} bodyLength
+ */
+export function validateFastPathPageLength(totalCount, requestLimit, bodyLength) {
+  const expected = Math.min(totalCount, requestLimit);
+  return bodyLength === expected;
+}
+
+/**
+ * Number sorts need full local reorder; skip fast path when total exceeds retain_max.
+ * @param {number} totalCount
+ * @param {number} retainMax
+ * @param {string} sliceSort
+ */
+export function isNumberSortFastPathEligible(totalCount, retainMax, sliceSort) {
+  if (sliceSort !== 'number_asc' && sliceSort !== 'number_desc') return true;
+  return totalCount <= retainMax;
+}
+
+/**
+ * Prefer forge header/search total over summed pagination lengths on fallback.
+ * @param {number | null | undefined} trustedTotal
+ * @param {number} summedCount
+ */
+export function resolvePaginatedEntryCount(trustedTotal, summedCount) {
+  if (trustedTotal != null && Number.isInteger(trustedTotal) && trustedTotal > 0) {
+    return trustedTotal;
+  }
+  return summedCount;
+}
+
+/**
+ * When forge total is trusted but pagination walked fewer items, mark truncated.
+ * @param {{ listTruncated: boolean, trustedTotalCount?: number | null, walkedCount: number, fullCollect?: boolean }} opts
+ */
+export function resolveListTruncatedWithTrustedTotal({
+  listTruncated,
+  trustedTotalCount,
+  walkedCount,
+  fullCollect = false,
+}) {
+  if (
+    trustedTotalCount != null &&
+    Number.isInteger(trustedTotalCount) &&
+    trustedTotalCount > 0 &&
+    walkedCount < trustedTotalCount
+  ) {
+    return true;
+  }
+  return listTruncated;
+}
+
+/**
+ * Gitea recent_created uses oldest sort; fast path only when total fits retain_max.
+ * @param {number} totalCount
+ * @param {number} retainMax
+ * @param {string} sliceSort
+ * @param {string} providerId
+ */
+export function isRecentCreatedFastPathEligible(totalCount, retainMax, sliceSort, providerId) {
+  if (sliceSort !== 'recent_created' || providerId !== 'gitea-api') return true;
+  return totalCount <= retainMax;
+}
+
+/**
+ * Last page index for Gitea sort=oldest when fetching globally newest-created slice.
+ * @param {number} totalCount
+ * @param {number} pageSize
+ */
+export function giteaRecentCreatedTailPage(totalCount, pageSize) {
+  if (!Number.isInteger(totalCount) || totalCount <= 0) return 1;
+  if (!Number.isInteger(pageSize) || pageSize <= 0) return 1;
+  return Math.max(1, Math.ceil(totalCount / pageSize));
+}
+
+/**
+ * Number sorts need full local reorder when total exceeds retain_max.
+ * @param {number} totalCount
+ * @param {number} retainMax
+ * @param {string} sliceSort
+ */
+export function isNumberSortFullCollectRequired(totalCount, retainMax, sliceSort) {
+  if (forgeOrderAuthoritative(sliceSort)) return false;
+  return !isNumberSortFastPathEligible(totalCount, retainMax, sliceSort);
+}
+
+/**
+ * Gitea sort=oldest returns oldest-first; recent_created needs newest-first.
+ * @param {unknown[]} items
+ * @param {string} sliceSort
+ */
+export function prepareGiteaOpenPullPageItems(items, sliceSort) {
+  if (sliceSort !== 'recent_created' || !Array.isArray(items)) return items;
+  return items.slice().reverse();
+}
+
+/**
+ * @param {unknown[]} items
+ * @param {(item: unknown) => number | null | undefined} getNumber
+ * @param {string} sliceSort
+ * @returns {number[]}
+ */
+export function orderOpenPullNumbers(items, getNumber, sliceSort) {
+  const numbers = items
+    .map(getNumber)
+    .filter((number) => Number.isInteger(number));
+  if (forgeOrderAuthoritative(sliceSort)) return numbers;
+  numbers.sort((a, b) => (sliceSort === 'number_desc' ? b - a : a - b));
+  return numbers;
+}
+
+/**
+ * @param {{ totalCount?: number | null, numbers: number[], listTruncated: boolean, sliceSort?: string }} meta
+ */
+export function buildOpenPullListMeta({ totalCount, numbers, listTruncated, sliceSort }) {
+  return {
+    numbers,
+    list_truncated: listTruncated,
+    ...(totalCount != null ? { entry_count: totalCount } : {}),
+    ...(sliceSort ? { slice_sort: sliceSort } : {}),
+  };
+}
+
+/**
+ * Gitea query params for normalized slice sort.
+ * @param {string} sliceSort
+ */
+export function giteaOpenPullSortQuery(sliceSort) {
+  switch (sliceSort) {
+    case 'recent_update':
+      return { sort: 'recentupdate' };
+    case 'recent_created':
+      return { sort: 'oldest' };
+    default:
+      return {};
+  }
+}
+
+/**
+ * GitLab query params for normalized slice sort.
+ * @param {string} sliceSort
+ */
+export function gitlabOpenPullSortQuery(sliceSort) {
+  switch (sliceSort) {
+    case 'recent_update':
+      return { order_by: 'updated_at', sort: 'desc' };
+    case 'recent_created':
+      return { order_by: 'created_at', sort: 'desc' };
+    case 'number_desc':
+      return { order_by: 'created_at', sort: 'desc' };
+    default:
+      return { order_by: 'created_at', sort: 'asc' };
+  }
+}
+
+/**
+ * GitHub query params for normalized slice sort on list pulls.
+ * @param {string} sliceSort
+ */
+export function githubOpenPullSortQuery(sliceSort) {
+  switch (sliceSort) {
+    case 'recent_update':
+      return { sort: 'updated', direction: 'desc' };
+    case 'recent_created':
+      return { sort: 'created', direction: 'desc' };
+    case 'number_desc':
+      return { sort: 'created', direction: 'desc' };
+    default:
+      return { sort: 'created', direction: 'asc' };
+  }
+}
+
+/**
+ * Append URLSearchParams for forge sort query entries.
+ * @param {string} path
+ * @param {Record<string, string>} query
+ */
+export function appendSortQuery(path, query) {
+  if (!query || Object.keys(query).length === 0) return path;
+  const sep = path.includes('?') ? '&' : '?';
+  const params = new URLSearchParams(query);
+  return `${path}${sep}${params.toString()}`;
+}

package/operator-config.js

@@ -0,0 +1,260 @@
+import { readFileSync, existsSync, statSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve, isAbsolute } from 'node:path';
+import { z } from 'zod';
+import { writeCommandSchema } from './write-config.js';
+import { forgeWritePolicySchema } from './config-schema.js';
+import { ERROR_CODES, forgeError } from './contracts/errors.js';
+import { normalizedForgeOrigin } from './forge-identity.js';
+
+export const REMOGRAM_OPERATOR_CONFIG_ENV = 'REMOGRAM_OPERATOR_CONFIG';
+export const MAX_OPERATOR_CONFIG_BYTES = 8192;
+
+const FORBIDDEN_CONFIG_KEYS = new Set(['token', 'password', 'secret', 'api_key', 'apiKey']);
+
+const repoSegmentSchema = z
+  .string()
+  .min(1)
+  .refine((s) => !/[/%]/.test(s) && !s.includes('..') && !s.includes('/'), {
+    message: 'owner/repo must not contain /, .., or %',
+  });
+
+const operatorBindSchema = z
+  .object({
+    provider: z.enum(['gitea-api', 'github-api', 'gitlab-api', 'gitea-tea', 'github-gh']),
+    remote: z.string().min(1),
+    owner: repoSegmentSchema,
+    repo: repoSegmentSchema,
+    baseUrl: z.string().url().optional(),
+  })
+  .strict();
+
+export const operatorConfigSchema = z
+  .object({
+    version: z.literal('1'),
+    bind: operatorBindSchema,
+    write_commands: z.array(writeCommandSchema).min(1),
+    forge_write_policy: forgeWritePolicySchema.optional(),
+  })
+  .strict();
+
+function xdgConfigHome() {
+  return process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+}
+
+export function defaultOperatorConfigPath(forgeContext) {
+  const { config, parsed } = forgeContext;
+  const owner = parsed?.owner ?? config.owner;
+  const repo = parsed?.repo ?? config.repo;
+  const safeOwner = String(owner).replace(/[^a-zA-Z0-9._-]+/g, '_');
+  const safeRepo = String(repo).replace(/[^a-zA-Z0-9._-]+/g, '_');
+  const filename = `${config.provider}-${safeOwner}-${safeRepo}.json`;
+  return join(xdgConfigHome(), 'remogram', 'operator', filename);
+}
+
+export function discoverOperatorConfigPath(options = {}) {
+  const cliPath = options.cliPath ?? options.operatorConfigPath ?? null;
+  if (cliPath) {
+    return { path: cliPath, discovered_via: 'cli_flag' };
+  }
+  const envPath = process.env[REMOGRAM_OPERATOR_CONFIG_ENV];
+  if (envPath) {
+    return { path: envPath, discovered_via: 'env' };
+  }
+  if (options.forgeContext) {
+    const defaultPath = defaultOperatorConfigPath(options.forgeContext);
+    if (existsSync(defaultPath)) {
+      return { path: defaultPath, discovered_via: 'xdg_default' };
+    }
+  }
+  return { path: null, discovered_via: 'none' };
+}
+
+function assertForbiddenKeys(obj, pathPrefix = '') {
+  if (!obj || typeof obj !== 'object') return;
+  for (const [key, value] of Object.entries(obj)) {
+    if (FORBIDDEN_CONFIG_KEYS.has(key)) {
+      throw new Error(`Forbidden key "${pathPrefix}${key}" in operator config`);
+    }
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      assertForbiddenKeys(value, `${pathPrefix}${key}.`);
+    }
+  }
+}
+
+function assertPathSafeToRead(configPath) {
+  if (!configPath || typeof configPath !== 'string') {
+    throw new Error('Operator config path is missing');
+  }
+  if (configPath.includes('\0')) {
+    throw new Error('Operator config path contains invalid characters');
+  }
+  const expanded = configPath.startsWith('~') ? join(homedir(), configPath.slice(1)) : configPath;
+  const absolute = isAbsolute(expanded) ? expanded : resolve(expanded);
+  if (!existsSync(absolute)) {
+    throw new Error(`Operator config not found: ${configPath}`);
+  }
+  let stat;
+  try {
+    stat = statSync(absolute);
+  } catch {
+    throw new Error(`Operator config is not readable: ${configPath}`);
+  }
+  if (!stat.isFile()) {
+    throw new Error(`Operator config is not a regular file: ${configPath}`);
+  }
+  if (stat.size > MAX_OPERATOR_CONFIG_BYTES) {
+    throw new Error(`Operator config exceeds ${MAX_OPERATOR_CONFIG_BYTES} bytes`);
+  }
+  if ((stat.mode & 0o002) !== 0) {
+    throw new Error('Operator config is world-writable');
+  }
+  try {
+    realpathSync(absolute);
+  } catch {
+    throw new Error(`Operator config path could not be resolved: ${configPath}`);
+  }
+  return absolute;
+}
+
+export function parseOperatorConfigFile(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error('Invalid JSON in operator config');
+  }
+  assertForbiddenKeys(parsed);
+  return operatorConfigSchema.parse(parsed);
+}
+
+export function loadOperatorConfigFile(configPath) {
+  const absolute = assertPathSafeToRead(configPath);
+  const raw = readFileSync(absolute, 'utf8');
+  const config = parseOperatorConfigFile(raw);
+  return { path: absolute, config };
+}
+
+export function assertOperatorBindMatches(operatorConfig, forgeContext, meta = {}) {
+  const bind = operatorConfig.bind;
+  const { config, parsed } = forgeContext;
+  const owner = parsed?.owner ?? config.owner;
+  const repo = parsed?.repo ?? config.repo;
+  const ctxOrigin = forgeContext.baseUrl ?? normalizedForgeOrigin(config);
+
+  if (bind.provider !== config.provider) {
+    throw bindMismatch({
+      field: 'provider',
+      expected: config.provider,
+      actual: bind.provider,
+      message: `operator bind provider ${bind.provider} does not match repo config ${config.provider}`,
+      meta,
+    });
+  }
+  if (bind.remote !== config.remote) {
+    throw bindMismatch({
+      field: 'remote',
+      expected: config.remote,
+      actual: bind.remote,
+      message: `operator bind remote ${bind.remote} does not match repo config ${config.remote}`,
+      meta,
+    });
+  }
+  if (bind.owner !== owner || bind.repo !== repo) {
+    throw bindMismatch({
+      field: 'repo',
+      expected: `${owner}/${repo}`,
+      actual: `${bind.owner}/${bind.repo}`,
+      message: `operator bind repo ${bind.owner}/${bind.repo} does not match forge identity ${owner}/${repo}`,
+      meta,
+    });
+  }
+  if (bind.baseUrl) {
+    const bindOrigin = normalizedForgeOrigin({ baseUrl: bind.baseUrl });
+    if (bindOrigin !== ctxOrigin) {
+      throw bindMismatch({
+        field: 'baseUrl',
+        expected: ctxOrigin,
+        actual: bindOrigin,
+        message: `operator bind baseUrl ${bind.baseUrl} does not match forge baseUrl ${ctxOrigin}`,
+        meta,
+      });
+    }
+  }
+}
+
+function bindRemediation(meta = {}) {
+  const via = meta.discovered_via ?? 'unknown';
+  const pathHint = meta.path ? ` at ${meta.path}` : '';
+  if (via === 'env') {
+    return (
+      `Check REMOGRAM_OPERATOR_CONFIG${pathHint}: update bind to match this repo's .remogram.json `
+      + 'or unset the env var if the overlay is stale.'
+    );
+  }
+  if (via === 'xdg_default') {
+    return (
+      `Update the XDG operator overlay${pathHint} bind block to match this repo's .remogram.json `
+      + 'or remove the file if it targets a different repository.'
+    );
+  }
+  return (
+    `Update operator config bind${pathHint} to match this repo's .remogram.json `
+    + '(provider, remote, owner, repo, baseUrl).'
+  );
+}
+
+function bindMismatch({ field, expected, actual, message, meta = {} }) {
+  const remediation = bindRemediation(meta);
+  const fullMessage = `${message}. ${remediation}`;
+  return Object.assign(new Error(fullMessage), {
+    forgeError: forgeError(ERROR_CODES.CONFIG_INVALID, fullMessage, null, {
+      reason: 'operator_bind_mismatch',
+      field,
+      expected,
+      actual,
+      discovered_via: meta.discovered_via ?? null,
+      operator_config_path: meta.path ?? null,
+      remediation,
+    }),
+  });
+}
+
+/**
+ * @param {{ cliPath?: string | null, forgeContext: object }} options
+ * @returns {{ config: object | null, meta: object, error?: object }}
+ */
+export function loadOperatorConfig(options = {}) {
+  const discovery = discoverOperatorConfigPath(options);
+  const meta = {
+    discovered_via: discovery.discovered_via,
+    path: discovery.path ? sanitizePathForEmit(discovery.path) : null,
+    bind_ok: null,
+  };
+  if (!discovery.path) {
+    return { config: null, meta, error: null };
+  }
+  try {
+    const loaded = loadOperatorConfigFile(discovery.path);
+    assertOperatorBindMatches(loaded.config, options.forgeContext, meta);
+    meta.path = sanitizePathForEmit(loaded.path);
+    meta.bind_ok = true;
+    return { config: loaded.config, meta, error: null };
+  } catch (err) {
+    meta.bind_ok = false;
+    const forgeErr = err.forgeError || forgeError(ERROR_CODES.CONFIG_INVALID, err.message);
+    return {
+      config: null,
+      meta,
+      error: forgeErr,
+    };
+  }
+}
+
+function sanitizePathForEmit(configPath) {
+  const home = homedir();
+  if (configPath.startsWith(home)) {
+    return `~${configPath.slice(home.length)}`;
+  }
+  return configPath;
+}

package/package.json

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

package/path-allowlist.js

@@ -0,0 +1,114 @@
+/**
+ * Glob allowlist matching for autonomous Observer auto-merge scope checks.
+ * Supports `**`, `*`, and literal path segments (e.g. README.md).
+ */
+
+/**
+ * Collapse `.` / `..` segments; reject absolute paths and repo-root escape.
+ * @param {string} filePath
+ * @returns {string|null}
+ */
+export function normalizeRepoRelativePath(filePath) {
+  if (typeof filePath !== 'string') return null;
+  let path = filePath.replace(/\\/g, '/').replace(/^\.\//, '');
+  if (path === '') return null;
+  if (path.startsWith('/')) return null;
+  if (path === '..' || path.startsWith('../')) return null;
+  const parts = path.split('/');
+  const out = [];
+  for (const part of parts) {
+    if (part === '' || part === '.') continue;
+    if (part === '..') {
+      if (out.length > 0) out.pop();
+      continue;
+    }
+    out.push(part);
+  }
+  return out.join('/');
+}
+
+function changedPathHasDotDotSegment(filePath) {
+  if (typeof filePath !== 'string') return false;
+  const normalized = filePath.replace(/\\/g, '/').replace(/^\.\//, '');
+  if (normalized === '..' || normalized.startsWith('../') || normalized.includes('/../')) {
+    return true;
+  }
+  return normalized.split('/').some((segment) => segment === '..');
+}
+
+/**
+ * Normalize a forge changed-path list for allowlist scope; null if any path is unnormalizable.
+ * @param {unknown} changedPaths
+ * @returns {string[]|null}
+ */
+export function normalizeChangedPathList(changedPaths) {
+  if (!Array.isArray(changedPaths)) return null;
+  const normalized = [];
+  for (const filePath of changedPaths) {
+    if (changedPathHasDotDotSegment(filePath)) return null;
+    const repoPath = normalizeRepoRelativePath(filePath);
+    if (repoPath == null) return null;
+    normalized.push(repoPath);
+  }
+  return normalized;
+}
+
+function globToRegExp(glob) {
+  let pattern = '';
+  for (let i = 0; i < glob.length; i += 1) {
+    const ch = glob[i];
+    if (ch === '*' && glob[i + 1] === '*') {
+      pattern += '.*';
+      i += 1;
+      if (glob[i + 1] === '/') i += 1;
+    } else if (ch === '*') {
+      pattern += '[^/]*';
+    } else if (/[+?^${}()|[\]\\]/.test(ch)) {
+      pattern += `\\${ch}`;
+    } else {
+      pattern += ch;
+    }
+  }
+  return new RegExp(`^${pattern}$`);
+}
+
+/**
+ * @param {string} glob
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+export function matchPathAllowlist(glob, filePath) {
+  if (typeof glob !== 'string' || typeof filePath !== 'string') return false;
+  const normalized = normalizeRepoRelativePath(filePath);
+  if (normalized == null) return false;
+  return globToRegExp(glob).test(normalized);
+}
+
+/**
+ * @param {string[]} allowedPaths
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+export function isPathAllowed(allowedPaths, filePath) {
+  if (!Array.isArray(allowedPaths) || allowedPaths.length === 0) return false;
+  return allowedPaths.some((glob) => matchPathAllowlist(glob, filePath));
+}
+
+/**
+ * @param {string[]} allowedPaths
+ * @param {string[]} changedPaths
+ * @returns {string[]}
+ */
+export function pathsOutsideAllowlist(allowedPaths, changedPaths) {
+  if (!Array.isArray(changedPaths)) return [];
+  return changedPaths.filter((filePath) => !isPathAllowed(allowedPaths, filePath));
+}
+
+/**
+ * @param {string[]} allowedPaths
+ * @param {string[]} changedPaths
+ * @returns {boolean}
+ */
+export function allPathsAllowed(allowedPaths, changedPaths) {
+  return pathsOutsideAllowlist(allowedPaths, changedPaths).length === 0;
+}

package/pr-head-reconcile.js

@@ -0,0 +1,38 @@
+import { assertGitRemote } from './git-args.js';
+import { ERROR_CODES, forgeError } from './contracts/errors.js';
+import { gitRevParse } from './git-local.js';
+
+export const STALE_HEAD_MESSAGE =
+  'Forge PR head SHA diverges from locally resolved git; fetch or refresh before trusting forge_source_sha';
+
+export function localHeadShaForPr(cwd, remoteName, headRef) {
+  if (!headRef) return null;
+  assertGitRemote(remoteName, 'remote');
+  const trackingRef = `${remoteName}/${headRef}`;
+  return gitRevParse(cwd, trackingRef) ?? gitRevParse(cwd, headRef);
+}
+
+export function staleHeadDetails(cwd, remoteName, headRef, forgeHeadSha) {
+  if (!headRef || !forgeHeadSha) return null;
+  const localHeadSha = localHeadShaForPr(cwd, remoteName, headRef);
+  if (!localHeadSha) return null;
+  if (localHeadSha.toLowerCase() === String(forgeHeadSha).toLowerCase()) return null;
+  return {
+    forge_source_branch_ref: headRef,
+    forge_source_sha: forgeHeadSha,
+    local_head_sha: localHeadSha,
+  };
+}
+
+export function staleHeadForgeError() {
+  return forgeError(ERROR_CODES.STALE_HEAD, STALE_HEAD_MESSAGE);
+}
+
+export function throwIfStaleHeadByNumber(ctx, packetType, body, headRef, forgeHeadSha) {
+  const details = staleHeadDetails(ctx.cwd, ctx.config?.remote ?? ctx.remoteName, headRef, forgeHeadSha);
+  if (!details) return;
+  const err = new Error(STALE_HEAD_MESSAGE);
+  err.forgeError = staleHeadForgeError();
+  err.staleHeadPacket = { type: packetType, body: { ...body, ...details } };
+  throw err;
+}