@remogram/core 0.1.0-beta.0

package/caps.js

@@ -0,0 +1,57 @@
+export const DEFAULT_MAX_BYTES = 8192;
+export const DEFAULT_FIELD_MAX_BYTES = 512;
+
+export function capText(text, maxBytes = DEFAULT_MAX_BYTES) {
+  if (!text) return { text: '', truncated: false, bytes: 0 };
+  const buf = Buffer.from(text, 'utf8');
+  if (buf.length <= maxBytes) {
+    return { text, truncated: false, bytes: buf.length };
+  }
+  let end = maxBytes;
+  while (end > 0 && (buf[end] & 0xc0) === 0x80) end -= 1;
+  const slice = buf.subarray(0, end).toString('utf8');
+  return { text: slice, truncated: true, bytes: end };
+}
+
+export function sanitizeField(value, maxBytes = DEFAULT_FIELD_MAX_BYTES) {
+  if (value == null) return null;
+  const singleLine = String(value)
+    .replace(/[\x00-\x1f\x7f]/g, ' ')
+    .replace(/\r?\n/g, ' ')
+    .trim();
+  return capText(singleLine, maxBytes).text;
+}
+
+export function sanitizeUrl(value, maxBytes = DEFAULT_FIELD_MAX_BYTES) {
+  if (value == null) return null;
+  try {
+    const u = new URL(String(value));
+    if (u.protocol !== 'http:' && u.protocol !== 'https:') return null;
+    return sanitizeField(u.href, maxBytes);
+  } catch {
+    return null;
+  }
+}
+
+export async function readStreamCapped(stream, maxBytes = DEFAULT_MAX_BYTES) {
+  const chunks = [];
+  let total = 0;
+  let truncated = false;
+
+  for await (const chunk of stream) {
+    const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    if (total + buf.length > maxBytes) {
+      const remaining = maxBytes - total;
+      if (remaining > 0) chunks.push(buf.subarray(0, remaining));
+      truncated = true;
+      break;
+    }
+    chunks.push(buf);
+    total += buf.length;
+  }
+
+  const combined = Buffer.concat(chunks);
+  let end = combined.length;
+  while (end > 0 && (combined[end - 1] & 0xc0) === 0x80) end -= 1;
+  return { text: combined.subarray(0, end).toString('utf8'), truncated, bytes: end };
+}

package/config-schema.js

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+
+const providerSchema = z.enum([
+  'gitea-api',
+  'github-api',
+  'gitlab-api',
+  'gitea-tea',
+  'github-gh',
+]);
+
+const repoSegmentSchema = z
+  .string()
+  .min(1)
+  .refine((s) => !/[/%]/.test(s) && !s.includes('..') && !s.includes('/'), {
+    message: 'owner/repo must not contain /, .., or %',
+  });
+
+export const configSchema = z
+  .object({
+    version: z.literal('1'),
+    provider: providerSchema,
+    remote: z.string().min(1).default('origin'),
+    owner: repoSegmentSchema,
+    repo: repoSegmentSchema,
+    baseUrl: z.string().url().optional(),
+  })
+  .strict();
+
+export function parseConfigFile(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error('Invalid JSON in .remogram.json');
+  }
+  return configSchema.parse(parsed);
+}

package/contracts/envelope.js

@@ -0,0 +1,71 @@
+import { sanitizeField } from '../caps.js';
+
+export const SCHEMA_VERSION = 1;
+
+export const PACKET_TYPES = {
+  REPO_STATUS: 'repo_status',
+  REF_COMPARE: 'ref_compare',
+  PR_STATUS: 'pr_status',
+  PR_CHECKS: 'pr_checks',
+  MERGE_PLAN: 'merge_plan',
+  SYNC_PLAN: 'sync_plan',
+  PROVIDER_CAPABILITIES: 'provider_capabilities',
+  PROVIDER_DOCTOR: 'provider_doctor',
+  FORGE_ERROR: 'forge_error',
+};
+
+export const FORBIDDEN_PACKET_KEYS = new Set([
+  'goal_branch',
+  'lane',
+  'sdlc_task',
+  'queue_selectable',
+]);
+
+function assertNoForbiddenKeys(value) {
+  if (value == null || typeof value !== 'object') return;
+  if (Array.isArray(value)) {
+    for (const item of value) assertNoForbiddenKeys(item);
+    return;
+  }
+  for (const [key, nested] of Object.entries(value)) {
+    if (FORBIDDEN_PACKET_KEYS.has(key)) {
+      throw new Error(`Forbidden Topogram concept in remogram output: ${key}`);
+    }
+    assertNoForbiddenKeys(nested);
+  }
+}
+
+export function forgePacket(type, context, body = {}, error = null) {
+  assertNoForbiddenKeys(body);
+
+  const packet = {
+    ...body,
+    type,
+    schema_version: SCHEMA_VERSION,
+    provider_id: context.providerId,
+    remote_name: context.remoteName,
+    repo_id: context.repoId,
+    observed_at: new Date().toISOString(),
+    ok: error == null,
+  };
+
+  if (error) {
+    packet.error_code = error.code;
+    packet.error_message = sanitizeField(error.message);
+    if (error.status != null) packet.error_status = error.status;
+  }
+
+  return packet;
+}
+
+export function forgeErrorPacket(context, error, type = PACKET_TYPES.FORGE_ERROR) {
+  return forgePacket(type, context, {}, error);
+}
+
+export function unknownForgeContext() {
+  return {
+    providerId: 'unknown',
+    remoteName: 'origin',
+    repoId: 'unknown/unknown',
+  };
+}

package/contracts/errors.js

@@ -0,0 +1,19 @@
+export const ERROR_CODES = {
+  STALE_HEAD: 'stale_head',
+  MISSING_REF: 'missing_ref',
+  DIVERGENT_REMOTES: 'divergent_remotes',
+  UNPARSEABLE_PROVIDER_OUTPUT: 'unparseable_provider_output',
+  OVERSIZED_RAW_OUTPUT: 'oversized_raw_output',
+  UNAUTHENTICATED_PROVIDER: 'unauthenticated_provider',
+  UNTRUSTED_BASE_URL: 'untrusted_base_url',
+  CONFIG_INVALID: 'config_invalid',
+  PROVIDER_UNSUPPORTED: 'provider_unsupported',
+  CONFIG_NOT_FOUND: 'config_not_found',
+  INVALID_ARGS: 'invalid_args',
+  API_ERROR: 'api_error',
+  REMOTE_INFER_FAILED: 'remote_infer_failed',
+};
+
+export function forgeError(code, message, status = null) {
+  return { code, message, ...(status != null ? { status } : {}) };
+}

package/git-args.js

@@ -0,0 +1,37 @@
+import { ERROR_CODES, forgeError } from './contracts/errors.js';
+
+const GIT_REF_RE = /^[A-Za-z0-9._/+-]+$/;
+const GIT_REMOTE_RE = /^[A-Za-z0-9._-]+$/;
+
+function invalidArgs(message) {
+  return Object.assign(new Error(message), {
+    forgeError: forgeError(ERROR_CODES.INVALID_ARGS, message),
+  });
+}
+
+export function assertGitRef(ref, label = 'ref') {
+  if (typeof ref !== 'string' || !ref.trim()) {
+    throw invalidArgs(`${label} is required`);
+  }
+  if (ref.startsWith('-')) {
+    throw invalidArgs(`${label} must not start with '-'`);
+  }
+  if (ref.includes('..')) {
+    throw invalidArgs(`${label} must not contain '..'`);
+  }
+  if (!GIT_REF_RE.test(ref)) {
+    throw invalidArgs(`${label} contains invalid characters`);
+  }
+}
+
+export function assertGitRemote(name, label = 'remote') {
+  if (typeof name !== 'string' || !name.trim()) {
+    throw invalidArgs(`${label} is required`);
+  }
+  if (name.startsWith('-')) {
+    throw invalidArgs(`${label} must not start with '-'`);
+  }
+  if (!GIT_REMOTE_RE.test(name)) {
+    throw invalidArgs(`${label} contains invalid characters`);
+  }
+}

package/git-local.js

@@ -0,0 +1,35 @@
+import { execFileSync } from 'node:child_process';
+import { assertGitRef } from './git-args.js';
+
+const GIT_TIMEOUT_MS = 10_000;
+
+function gitExec(cwd, args) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', timeout: GIT_TIMEOUT_MS }).trim();
+}
+
+export function gitRevParse(cwd, ref) {
+  assertGitRef(ref);
+  try {
+    return gitExec(cwd, ['rev-parse', ref]);
+  } catch {
+    return null;
+  }
+}
+
+export function gitCurrentBranch(cwd) {
+  try {
+    return gitExec(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']);
+  } catch {
+    return null;
+  }
+}
+
+export function gitAheadBehind(cwd, base, head) {
+  try {
+    const out = gitExec(cwd, ['rev-list', '--left-right', '--count', `${base}...${head}`]);
+    const [behind, ahead] = out.split(/\s+/).map(Number);
+    return { ahead_by: ahead, behind_by: behind };
+  } catch {
+    return { ahead_by: null, behind_by: null };
+  }
+}

package/http.js

@@ -0,0 +1,84 @@
+import { ERROR_CODES, forgeError } from './contracts/errors.js';
+import { readStreamCapped, DEFAULT_MAX_BYTES, sanitizeField } from './caps.js';
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_JSON_MAX_BYTES = DEFAULT_MAX_BYTES;
+
+export async function fetchWithTimeout(url, options = {}, timeoutMs = DEFAULT_TIMEOUT_MS) {
+  const signal = AbortSignal.timeout(timeoutMs);
+  return fetch(url, { ...options, signal, redirect: 'manual' });
+}
+
+async function readResponseTextCapped(res, maxBytes) {
+  if (!res.body) return '';
+  const capped = await readStreamCapped(res.body, maxBytes);
+  if (capped.truncated) {
+    throw Object.assign(new Error('Provider output exceeded cap'), {
+      forgeError: forgeError(ERROR_CODES.OVERSIZED_RAW_OUTPUT, 'Provider response exceeded byte cap'),
+      status: res.status,
+    });
+  }
+  return capped.text;
+}
+
+export async function fetchJson(
+  url,
+  options = {},
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  maxBytes = DEFAULT_JSON_MAX_BYTES,
+) {
+  const res = await fetchWithTimeout(url, options, timeoutMs);
+  if (res.status >= 300 && res.status < 400) {
+    const message = 'HTTP redirect rejected';
+    throw Object.assign(new Error(message), {
+      forgeError: forgeError(ERROR_CODES.API_ERROR, message, res.status),
+      status: res.status,
+    });
+  }
+  const text = await readResponseTextCapped(res, maxBytes);
+  let body;
+  try {
+    body = text ? JSON.parse(text) : null;
+  } catch {
+    throw Object.assign(new Error('Unparseable JSON from provider'), {
+      forgeError: forgeError(ERROR_CODES.UNPARSEABLE_PROVIDER_OUTPUT, 'Provider returned invalid JSON'),
+      status: res.status,
+    });
+  }
+  if (!res.ok) {
+    const raw = body?.message || body?.error || res.statusText || 'API error';
+    const message = sanitizeField(raw) || 'API error';
+    throw Object.assign(new Error(message), {
+      forgeError: forgeError(ERROR_CODES.API_ERROR, message, res.status),
+      status: res.status,
+    });
+  }
+  return body;
+}
+
+export async function fetchTextCapped(url, options = {}, maxBytes = DEFAULT_MAX_BYTES) {
+  const res = await fetchWithTimeout(url, options);
+  if (res.status >= 300 && res.status < 400) {
+    const message = 'HTTP redirect rejected';
+    throw Object.assign(new Error(message), {
+      forgeError: forgeError(ERROR_CODES.API_ERROR, message, res.status),
+      status: res.status,
+    });
+  }
+  if (!res.ok) {
+    const raw = await readResponseTextCapped(res, maxBytes).catch(() => res.statusText);
+    const message = sanitizeField(raw) || 'API error';
+    throw Object.assign(new Error(message), {
+      forgeError: forgeError(ERROR_CODES.API_ERROR, message, res.status),
+      status: res.status,
+    });
+  }
+  if (!res.body) return { text: '', truncated: false, bytes: 0 };
+  const capped = await readStreamCapped(res.body, maxBytes);
+  if (capped.truncated) {
+    throw Object.assign(new Error('Provider output exceeded cap'), {
+      forgeError: forgeError(ERROR_CODES.OVERSIZED_RAW_OUTPUT, 'Provider response exceeded byte cap'),
+    });
+  }
+  return capped;
+}

package/index.js

@@ -0,0 +1,17 @@
+export { SCHEMA_VERSION, PACKET_TYPES, forgePacket, forgeErrorPacket, unknownForgeContext, FORBIDDEN_PACKET_KEYS } from './contracts/envelope.js';
+export { ERROR_CODES, forgeError } from './contracts/errors.js';
+export { capText, sanitizeField, sanitizeUrl, readStreamCapped, DEFAULT_MAX_BYTES, DEFAULT_FIELD_MAX_BYTES } from './caps.js';
+export { assertGitRef, assertGitRemote } from './git-args.js';
+export { gitRevParse, gitCurrentBranch, gitAheadBehind } from './git-local.js';
+export { parseConfigFile, configSchema } from './config-schema.js';
+export {
+  findConfigPath,
+  loadConfig,
+  gitRemoteUrl,
+  parseRemoteUrl,
+  trustedBaseUrl,
+  assertConfigMatchesRemote,
+  assertForgeReady,
+  forgeContext,
+} from './resolve.js';
+export { fetchWithTimeout, fetchJson, fetchTextCapped } from './http.js';

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@remogram/core",
+  "version": "0.1.0-beta.0",
+  "description": "Remogram forge envelope, config, caps, and HTTP utilities",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/attebury/remogram.git",
+    "directory": "packages/remogram-core"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "*.js",
+    "contracts/"
+  ],
+  "exports": {
+    ".": "./index.js",
+    "./stub-provider.js": "./stub-provider.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "zod": "^3.25.76"
+  }
+}

package/resolve.js

@@ -0,0 +1,137 @@
+import { execFileSync } from 'node:child_process';
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { parseConfigFile } from './config-schema.js';
+import { ERROR_CODES, forgeError } from './contracts/errors.js';
+import { assertGitRemote } from './git-args.js';
+
+const HOST_ALIASES = new Map([
+  ['localhost:3000', '127.0.0.1:3000'],
+  ['127.0.0.1:3000', 'localhost:3000'],
+]);
+
+export function findConfigPath(startDir = process.cwd()) {
+  let dir = startDir;
+  while (true) {
+    const candidate = join(dir, '.remogram.json');
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+export function loadConfig(cwd = process.cwd()) {
+  const path = findConfigPath(cwd);
+  if (!path) {
+    throw Object.assign(new Error('No .remogram.json found'), {
+      forgeError: forgeError(ERROR_CODES.CONFIG_NOT_FOUND, 'No .remogram.json found'),
+    });
+  }
+  try {
+    const raw = readFileSync(path, 'utf8');
+    return { path, config: parseConfigFile(raw), cwd: dirname(path) };
+  } catch (err) {
+    throw Object.assign(new Error(err.message), {
+      forgeError: forgeError(ERROR_CODES.CONFIG_INVALID, err.message),
+    });
+  }
+}
+
+export function gitRemoteUrl(cwd, remote = 'origin') {
+  assertGitRemote(remote);
+  try {
+    return execFileSync('git', ['remote', 'get-url', remote], {
+      cwd,
+      encoding: 'utf8',
+      timeout: 10_000,
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+export function parseRemoteUrl(url) {
+  if (!url) return null;
+  const ssh = url.match(/^git@([^:]+):(.+?)(?:\.git)?$/);
+  if (ssh) {
+    const [, host, path] = ssh;
+    const parts = path.split('/').filter(Boolean);
+    if (parts.length < 2) return null;
+    const repo = parts.pop();
+    const owner = parts.join('/');
+    return { host, owner, repo };
+  }
+  try {
+    const u = new URL(url.replace(/\.git$/, ''));
+    const parts = u.pathname.split('/').filter(Boolean);
+    if (parts.length < 2) return null;
+    const repo = parts.pop();
+    const owner = parts.join('/');
+    return { host: u.host, owner, repo, protocol: u.protocol };
+  } catch {
+    return null;
+  }
+}
+
+function hostsEquivalent(a, b) {
+  if (a === b) return true;
+  return HOST_ALIASES.get(a) === b || HOST_ALIASES.get(b) === a;
+}
+
+export function trustedBaseUrl(config, remoteHost) {
+  if (!config.baseUrl) return true;
+  let configHost;
+  try {
+    configHost = new URL(config.baseUrl).host;
+  } catch {
+    return false;
+  }
+  return configHost === remoteHost || hostsEquivalent(configHost, remoteHost);
+}
+
+export function assertConfigMatchesRemote(config, parsed) {
+  if (config.owner !== parsed.owner || config.repo !== parsed.repo) {
+    throw Object.assign(new Error('Config owner/repo does not match git remote'), {
+      forgeError: forgeError(
+        ERROR_CODES.CONFIG_INVALID,
+        `Config repo ${config.owner}/${config.repo} does not match remote ${parsed.owner}/${parsed.repo}`,
+      ),
+    });
+  }
+}
+
+export function assertForgeReady(loaded) {
+  const { config, cwd } = loaded;
+  assertGitRemote(config.remote, 'config.remote');
+  const remoteUrl = gitRemoteUrl(cwd, config.remote);
+  const parsed = parseRemoteUrl(remoteUrl);
+  if (!parsed) {
+    throw Object.assign(new Error('Could not parse git remote'), {
+      forgeError: forgeError(ERROR_CODES.REMOTE_INFER_FAILED, 'Could not parse git remote URL'),
+    });
+  }
+  assertConfigMatchesRemote(config, parsed);
+  if (config.baseUrl && !trustedBaseUrl(config, parsed.host)) {
+    throw Object.assign(new Error('baseUrl host not trusted'), {
+      forgeError: forgeError(
+        ERROR_CODES.UNTRUSTED_BASE_URL,
+        `baseUrl host does not match remote host ${parsed.host}`,
+      ),
+    });
+  }
+  return { ...loaded, remoteUrl, parsed };
+}
+
+export function forgeContext(loaded) {
+  const { config, parsed } = loaded;
+  return {
+    providerId: config.provider,
+    remoteName: config.remote,
+    repoId: `${parsed.owner}/${parsed.repo}`,
+    config,
+    cwd: loaded.cwd,
+    parsed,
+  };
+}

package/stub-provider.js

@@ -0,0 +1,37 @@
+import { ERROR_CODES, forgeError } from './contracts/errors.js';
+
+export function createStubProvider(id) {
+  function unsupported() {
+    const err = new Error('Provider not implemented');
+    err.forgeError = forgeError(ERROR_CODES.PROVIDER_UNSUPPORTED, 'Provider not implemented in v1');
+    throw err;
+  }
+  function providerCapabilities() {
+    return {
+      commands: [
+        { name: 'repo_status', implemented: false },
+        { name: 'ref_compare', implemented: false },
+        { name: 'pr_status', implemented: false },
+        { name: 'pr_checks', implemented: false },
+        { name: 'merge_plan', implemented: false },
+        { name: 'sync_plan', implemented: false },
+      ],
+      auth_envs: [],
+      check_sources: [],
+      mergeability_confidence: 'unknown',
+      host_binding: 'unsupported',
+      pagination: 'unsupported',
+      write_support: false,
+    };
+  }
+  return {
+    id,
+    providerCapabilities,
+    repoStatus: unsupported,
+    refsCompare: unsupported,
+    prView: unsupported,
+    prChecks: unsupported,
+    mergePlan: unsupported,
+    syncPlan: unsupported,
+  };
+}