@remogram/core 0.1.0-beta.2 → 0.1.0-beta.4

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/package.json

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

package/path-allowlist.js

@@ -0,0 +1,63 @@
+/**
+ * Glob allowlist matching for autonomous Observer auto-merge scope checks.
+ * Supports `**`, `*`, and literal path segments (e.g. README.md).
+ */
+
+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 = filePath.replace(/\\/g, '/').replace(/^\.\//, '');
+  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/ref-inventory.js

@@ -0,0 +1,98 @@
+import { execFileSync } from 'node:child_process';
+import { sanitizeField } from './caps.js';
+import { gitAheadBehind, gitCurrentBranch, gitRevParse } from './git-local.js';
+
+const GIT_TIMEOUT_MS = 10_000;
+
+function gitExec(cwd, args) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', timeout: GIT_TIMEOUT_MS }).trim();
+}
+
+function listRefs(cwd) {
+  try {
+    const out = gitExec(cwd, [
+      'for-each-ref',
+      '--format=%(refname:short)|%(objectname)|%(refname)',
+      'refs/heads',
+      'refs/remotes',
+    ]);
+    if (!out) return [];
+    return out.split('\n').filter(Boolean).map((line) => {
+      const [name, sha, fullRef] = line.split('|');
+      const kind = fullRef.startsWith('refs/heads/') ? 'branch' : 'remote';
+      return { name, sha, kind };
+    });
+  } catch {
+    return [];
+  }
+}
+
+function resolveDefaultRef(cwd, remoteName) {
+  try {
+    const sym = gitExec(cwd, ['symbolic-ref', `refs/remotes/${remoteName}/HEAD`]);
+    const prefix = `refs/remotes/${remoteName}/`;
+    if (sym.startsWith(prefix)) {
+      return sym.slice(prefix.length);
+    }
+    return sym.replace(/^refs\/remotes\/[^/]+\//, '');
+  } catch {
+    return null;
+  }
+}
+
+function buildAncestryHints(cwd, defaultRef, refs) {
+  if (!defaultRef) return [];
+  const defaultEntry = refs.find((r) => r.name === defaultRef || r.name === `origin/${defaultRef}`);
+  const headBranch = gitCurrentBranch(cwd);
+  if (!headBranch || headBranch === 'HEAD') return [];
+  const headEntry = refs.find((r) => r.name === headBranch);
+  if (!defaultEntry?.sha || !headEntry?.sha || defaultEntry.sha === headEntry.sha) return [];
+
+  const counts = gitAheadBehind(cwd, defaultEntry.sha, headEntry.sha);
+  if (counts.ahead_by == null && counts.behind_by == null) return [];
+
+  return [
+    {
+      base_ref: sanitizeField(defaultRef),
+      head_ref: sanitizeField(headBranch),
+      ahead_by: counts.ahead_by,
+      behind_by: counts.behind_by,
+    },
+  ];
+}
+
+/**
+ * Build provider-neutral ref inventory body from local git.
+ * @param {string} cwd repository working directory (git root after config load)
+ * @param {string} [remoteName]
+ */
+export function buildRefInventoryBody(cwd, remoteName = 'origin') {
+  const refs = listRefs(cwd).map((ref) => ({
+    name: sanitizeField(ref.name),
+    sha: ref.sha,
+    kind: ref.kind,
+    is_default: false,
+  }));
+
+  const defaultRef = resolveDefaultRef(cwd, remoteName);
+  if (defaultRef) {
+    for (const ref of refs) {
+      if (ref.name === defaultRef || ref.name === `${remoteName}/${defaultRef}`) {
+        ref.is_default = true;
+      }
+    }
+  }
+
+  const ancestry_hints = buildAncestryHints(cwd, defaultRef, refs);
+
+  return {
+    refs,
+    ...(defaultRef ? { default_ref: sanitizeField(defaultRef) } : {}),
+    ...(ancestry_hints.length > 0 ? { ancestry_hints } : {}),
+  };
+}
+
+export async function refsInventory(ctx) {
+  const remoteName = ctx.config.remote || 'origin';
+  return buildRefInventoryBody(ctx.cwd, remoteName);
+}

package/stub-provider.js

@@ -23,6 +23,8 @@ export function createStubProvider(id) {
     providerCapabilities,
     repoStatus: unsupported,
     refsCompare: unsupported,
+    refsInventory: unsupported,
+    crInventory: unsupported,
     prView: unsupported,
     prChecks: unsupported,
     mergePlan: unsupported,

package/write-config.js

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import { ERROR_CODES, forgeError } from './contracts/errors.js';
+
+/** Canonical v1 consumer write command ids (schema + gate single source). */
+export const WRITE_COMMAND_IDS = Object.freeze(['cr_open']);
+
+export const writeCommandSchema = z.enum(WRITE_COMMAND_IDS);
+
+/** @deprecated use WRITE_COMMAND_IDS */
+export const CONFIGURED_WRITE_COMMANDS = WRITE_COMMAND_IDS;
+
+export function isWriteCommandConfigured(config, commandName) {
+  if (!writeCommandSchema.safeParse(commandName).success) return false;
+  const allowed = config?.write_commands;
+  return Array.isArray(allowed) && allowed.includes(commandName);
+}
+
+export function assertWriteCommandConfigured(config, commandName) {
+  if (!writeCommandSchema.safeParse(commandName).success) {
+    throw Object.assign(new Error(`Unknown write command: ${commandName}`), {
+      forgeError: forgeError(
+        ERROR_CODES.INVALID_ARGS,
+        `Unknown write command "${commandName}"; supported: ${WRITE_COMMAND_IDS.join(', ')}`,
+      ),
+    });
+  }
+  if (isWriteCommandConfigured(config, commandName)) return;
+  throw Object.assign(new Error(`Write command not configured: ${commandName}`), {
+    forgeError: forgeError(
+      ERROR_CODES.WRITE_NOT_CONFIGURED,
+      `Add "${commandName}" to write_commands in .remogram.json to enable this command`,
+    ),
+  });
+}