@elalfner/relevo 0.0.0-stage → 0.3.0

package/scripts/lib/checklist.mjs

@@ -0,0 +1,68 @@
+// Builds the review checklist from the scenarios of a change specification.
+// One checklist line per `#### Scenario:` found under `<change>/specs/**/spec.md`.
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+const SCENARIO_RE = /^####\s+Scenario:\s*(.+?)\s*$/;
+const STEP_RE = /^\s*[-*]\s+\*\*(AND WHEN|WHEN|THEN|AND THEN|AND)\*\*\s*(.*?)\s*$/;
+
+/** Parse scenarios out of the text of one spec file. */
+export function scenariosFromSpec(text, source = '') {
+  const scenarios = [];
+  let current = null;
+  String(text).split('\n').forEach((line) => {
+    const heading = line.match(/^#{1,6}\s/);
+    const scenario = line.match(SCENARIO_RE);
+    if (scenario) {
+      current = { title: scenario[1], when: [], then: [], source };
+      scenarios.push(current);
+      return;
+    }
+    if (heading) {
+      current = null;
+      return;
+    }
+    const step = current && line.match(STEP_RE);
+    if (!step) return;
+    const [, kind, rest] = step;
+    if (kind.endsWith('WHEN') || (kind === 'AND' && current.then.length === 0)) current.when.push(rest);
+    else current.then.push(rest);
+  });
+  return scenarios;
+}
+
+function specFiles(dir) {
+  const out = [];
+  (function walk(d) {
+    readdirSync(d).sort().forEach((name) => {
+      const path = join(d, name);
+      if (statSync(path).isDirectory()) walk(path);
+      else if (name === 'spec.md') out.push(path);
+    });
+  }(dir));
+  return out;
+}
+
+/** All scenarios of a change directory, in file order. Returns [{ id, title, when, then, source }]. */
+export function checklistFromChange(changeDir) {
+  const specsDir = join(changeDir, 'specs');
+  const items = [];
+  specFiles(specsDir).forEach((file) => {
+    scenariosFromSpec(readFileSync(file, 'utf8'), file.slice(changeDir.length).replace(/^\/+/, '')).forEach((s) => items.push(s));
+  });
+  return items.map((s, i) => ({ id: i + 1, ...s }));
+}
+
+/** Markdown checklist, optionally with the items already confirmed ticked. */
+export function checklistMarkdown(items, statuses = {}, autos = {}) {
+  return items
+    .map((s) => {
+      const mark = statuses[s.id] === 'ok' ? 'x' : ' ';
+      const detail = [s.when.join(' and '), s.then.join(' and ')].filter(Boolean);
+      const text = detail.length === 2 ? `when ${detail[0]}, then ${detail[1]}` : detail.join('');
+      const auto = autos[s.id] ? ` _(verified automatically: ${autos[s.id]})_` : '';
+      return `- [${mark}] ${s.id}. **${s.title}**: ${text}${auto}`;
+    })
+    .join('\n');
+}

package/scripts/lib/cli.mjs

@@ -0,0 +1,82 @@
+// The commands behind `relevo`. They only drive `claude plugin`, so Claude Code stays the one place that installs
+// and updates a plugin; nothing here writes a file. `run` and `has` are injected so a test can use a fake `claude`.
+
+export const MARKETPLACE = 'elalfner/relevo';
+export const MARKETPLACE_NAME = 'relevo';
+export const PLUGIN_ID = 'relevo@relevo';
+export const SCOPES = ['user', 'project', 'local'];
+
+export const USAGE = [
+  'usage: relevo <command> [--scope user|project|local]',
+  '',
+  '  install   add the marketplace and install the plugin (default scope: user)',
+  '  update    update the marketplace and the plugin',
+  '  doctor    check this repository (the same as /relevo:doctor)',
+  '  version   print the version of this package',
+  '',
+  'user: every project of this machine. project: this repository, shared through .claude/settings.json. local: this repository, only you.'
+].join('\n');
+
+/** Parses the arguments; { error } when they are not valid. */
+export function parseArgs(argv) {
+  const [command, ...rest] = argv;
+  if (!command || command === '--help' || command === '-h' || command === 'help') return { command: 'help' };
+  if (!['install', 'update', 'doctor', 'version'].includes(command)) return { error: `unknown command "${command}"` };
+  let scope = 'user';
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i];
+    if (arg === '--scope') { scope = rest[i + 1]; i += 1; } else if (arg.startsWith('--scope=')) scope = arg.slice(8);
+    else return { error: `unknown option "${arg}"` };
+  }
+  if (!SCOPES.includes(scope)) return { error: `the scope must be one of ${SCOPES.join(', ')}` };
+  return { command, scope };
+}
+
+/** The `claude` invocations of a command, in order. */
+export function steps(command, scope) {
+  if (command === 'install') {
+    return [
+      { label: 'add the marketplace (only .claude-plugin/ is downloaded)', args: ['plugin', 'marketplace', 'add', MARKETPLACE, '--scope', scope, '--sparse', '.claude-plugin'] },
+      { label: 'install the plugin', args: ['plugin', 'install', PLUGIN_ID, '--scope', scope] }
+    ];
+  }
+  if (command === 'update') {
+    return [
+      { label: 'update the marketplace', args: ['plugin', 'marketplace', 'update', MARKETPLACE_NAME] },
+      { label: 'update the plugin', args: ['plugin', 'update', PLUGIN_ID, '--scope', scope] }
+    ];
+  }
+  return [];
+}
+
+/**
+ * Runs a command. Returns { code, lines }: the lines to print and the exit code. Stops at the first failing step
+ * and says which one, so the person knows what was already done.
+ */
+export function execute({ command, scope }, { run, has, version, doctorScript }) {
+  const lines = [];
+  if (command === 'version') return { code: 0, lines: [version] };
+  if (command === 'doctor') {
+    const r = run(process.execPath, [doctorScript]);
+    return { code: r.code, lines: [r.output.trimEnd()] };
+  }
+  if (!has('claude')) {
+    return { code: 1, lines: ['Claude Code is required and "claude" was not found on the path.', 'Install it (https://code.claude.com/docs) and run this command again; nothing was changed.'] };
+  }
+  const list = steps(command, scope);
+  for (let i = 0; i < list.length; i += 1) {
+    const step = list[i];
+    lines.push(`[${i + 1}/${list.length}] ${step.label}`);
+    const r = run('claude', step.args);
+    if (r.output.trim()) lines.push(r.output.trimEnd());
+    if (r.code !== 0) {
+      lines.push(`The step "${step.label}" failed${i > 0 ? `; the steps before it were done (${list.slice(0, i).map((s) => s.label).join(', ')})` : ''}. Fix the cause and run the command again: it is safe to repeat.`);
+      return { code: r.code || 1, lines };
+    }
+  }
+  const where = { user: 'for this machine', project: 'for this repository (declared in .claude/settings.json, so commit it to share it)', local: 'for this repository, only for you' }[scope];
+  lines.push(command === 'install'
+    ? `Relevo is installed ${where}. Restart Claude Code and run /relevo:doctor.`
+    : 'Relevo is up to date. Restart Claude Code to apply it.');
+  return { code: 0, lines };
+}

package/scripts/lib/commit-change.mjs

@@ -0,0 +1,57 @@
+// One safe way to commit: name the files, check protected paths, scan the diff, and only then commit.
+// Implements "Safe commits" of the go specification and "Protected paths" of the security specification.
+//
+// `git(args) -> stdout` is injected so the logic can be tested; the command-line wrapper runs the real git.
+
+import { checkScope } from './platform-scope.mjs';
+import { checkProtected, formatViolations } from './protected-paths.mjs';
+import { formatFindings, scanDiff } from './scan.mjs';
+import { explicitStageArgs } from './staging.mjs';
+
+/**
+ * Stage `paths`, check them and commit only them.
+ *   message    the commit message
+ *   paths      the files or folders to commit, named one by one (never "." or "-A")
+ *   allow      globs from the `Allow-paths:` line of the issue (dependency files only)
+ *   rulesFile  the project rules file (`qa.rules_from`), which is never changed
+ *   within     the folder of the platform of the issue: files outside it are refused (`.` or null: no limit)
+ *   change     the change id, whose specification folder may always be committed
+ * Returns { ok, commit, findings, violations }. When something is found nothing is committed and the named paths
+ * are unstaged again (files that were staged for other reasons stay staged).
+ */
+export function commitChange({ git, message, paths, allow = [], rulesFile = null, within = null, change = null }) {
+  if (!String(message ?? '').trim()) throw new Error('give a commit message');
+  const addArgs = explicitStageArgs(paths);
+
+  // A path that is protected is refused before anything is staged.
+  const named = checkProtected(paths, { allow, rulesFile });
+  if (named.violations.some((v) => v.tier === 'hard')) return { ok: false, commit: null, findings: [], violations: named.violations };
+
+  git(addArgs);
+  const unstage = () => git(['reset', '-q', '--', ...paths]);
+
+  // The folders named above may hold protected files: check what is really staged under them.
+  const staged = git(['diff', '--cached', '--name-only', '--', ...paths]).split('\n').filter(Boolean);
+  const violations = [
+    ...checkProtected(staged, { allow, rulesFile }).violations,
+    ...checkScope(staged, { within, change, allow }).violations,
+  ];
+  const findings = scanDiff(git(['diff', '--cached', '-U0', '--', ...paths]));
+  if (violations.length > 0 || findings.length > 0) {
+    unstage();
+    return { ok: false, commit: null, findings, violations };
+  }
+  if (staged.length === 0) throw new Error('nothing to commit: none of the named paths has changes');
+
+  // `--` with paths commits only those paths, so files staged for another reason are left alone.
+  git(['commit', '-q', '-m', message, '--', ...paths]);
+  return { ok: true, commit: git(['rev-parse', '--short', 'HEAD']).trim(), findings: [], violations: [] };
+}
+
+/** The lines to print when a commit was refused. Never contains a secret. */
+export function refusalText({ findings, violations }) {
+  const lines = [];
+  if (violations.length > 0) lines.push(formatViolations(violations));
+  if (findings.length > 0) lines.push(formatFindings(findings));
+  return lines.join('\n');
+}

package/scripts/lib/config.mjs

@@ -0,0 +1,296 @@
+// Schema, defaults and validation for relevo.yml.
+// Implements openspec/specs/configuration/spec.md.
+
+import { parse, YamlLiteError } from './yaml-lite.mjs';
+import { LABEL_KEYS } from './labels.mjs';
+import { SUPPORTED_LANGUAGES } from './messages.mjs';
+import { findCredentials } from './scan.mjs';
+import { normalizePlatforms } from './platforms.mjs';
+
+// One entry per supported setting. `required: true` means there is no default.
+export const SETTINGS = [
+  { path: 'branches.base', type: 'string', default: 'dev' },
+  { path: 'branches.release', type: 'string', default: 'main' },
+  { path: 'tracker', type: 'enum', allowed: ['github'], default: 'github' },
+  { path: 'git_provider', type: 'enum', allowed: ['github'], default: 'github' },
+  { path: 'team.members', type: 'string[]', default: [] },
+  { path: 'team.spec_writer', type: 'string', default: null },
+  { path: 'team.approvers', type: 'string[]', default: [] },
+  { path: 'review.mode', type: 'enum', allowed: ['none', 'peer', 'roles'], default: 'peer' },
+  { path: 'review.merger', type: 'enum', allowed: ['author', 'approver'], default: 'approver' },
+  { path: 'review.autopilot', type: 'enum', allowed: ['off', 'precheck', 'verify'], default: 'off' },
+  { path: 'review.allowed_origins', type: 'origin-list', default: [] },
+  { path: 'limits.built_unreviewed_per_person', type: 'int', min: 1, default: 2 },
+  { path: 'limits.concurrent_agents', type: 'int', min: 1, default: 3 },
+  { path: 'limits.review_sla_hours', type: 'int', min: 1, default: 8 },
+  { path: 'limits.run_max_turns', type: 'int', min: 1, default: 100 },
+  { path: 'limits.building_alert_hours', type: 'int', min: 1, default: 3 },
+  { path: 'limits.run_max_cost', type: 'number', exclusiveMin: 0, required: true },
+  { path: 'qa.retries', type: 'int', min: 0, default: 1 },
+  { path: 'qa.rules_from', type: 'path-list', default: [] },
+  { path: 'skills.allow_scripts', type: 'string[]', default: [] },
+  { path: 'links', type: 'repo-list', default: [] },
+  { path: 'evidence.policy', type: 'enum', allowed: ['attach_to_pr', 'local_only'], default: 'attach_to_pr' },
+  { path: 'digest.issue', type: 'int', min: 1, default: null },
+  { path: 'language', type: 'string', default: 'en' },
+  { path: 'design.images', type: 'bool', default: false },
+  { path: 'trust', type: 'enum', allowed: ['private-team', 'public'], default: 'private-team' },
+];
+
+const GROUPS = new Set(SETTINGS.filter((s) => s.path.includes('.')).map((s) => s.path.split('.')[0]));
+const TOP_SCALARS = new Set(SETTINGS.filter((s) => !s.path.includes('.')).map((s) => s.path));
+const KNOWN_TOP = new Set([...GROUPS, ...TOP_SCALARS, 'labels', 'platform', 'platforms']);
+const ORIGIN_RE = /^https?:\/\/[A-Za-z0-9.-]+(?::\d{1,5})?$/;
+const REPO_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const LANGUAGE_RE = /^[a-z]{2}(-[A-Z]{2})?$/;
+const GITHUB_LABEL_MAX = 50;
+
+function getPath(obj, path) {
+  return path.split('.').reduce((acc, key) => (acc && typeof acc === 'object' ? acc[key] : undefined), obj);
+}
+
+function setPath(obj, path, value) {
+  const keys = path.split('.');
+  let cursor = obj;
+  keys.slice(0, -1).forEach((key) => {
+    if (typeof cursor[key] !== 'object' || cursor[key] === null) cursor[key] = {};
+    cursor = cursor[key];
+  });
+  cursor[keys[keys.length - 1]] = value;
+}
+
+function describeAllowed(allowed) {
+  return allowed.map((v) => `"${v}"`).join(', ');
+}
+
+function checkType(setting, value, errors) {
+  const { path } = setting;
+  switch (setting.type) {
+    case 'string':
+      if (typeof value !== 'string' || value.trim() === '') {
+        errors.push({ path, message: `${path} must be a non-empty string (got ${JSON.stringify(value)})` });
+      }
+      break;
+    case 'string[]':
+      if (!Array.isArray(value) || value.some((v) => typeof v !== 'string' || v.trim() === '')) {
+        errors.push({ path, message: `${path} must be a list of non-empty strings (got ${JSON.stringify(value)})` });
+      }
+      break;
+    case 'path-list':
+      if (!Array.isArray(value) || value.length === 0 || value.some((v) => typeof v !== 'string' || v.trim() === '')) {
+        errors.push({ path, message: `${path} must be a file name or a list of file names (got ${JSON.stringify(value)})` });
+      }
+      break;
+    case 'repo-list': {
+      if (!Array.isArray(value) || value.some((v) => typeof v !== 'string')) {
+        errors.push({ path, message: `${path} must be a list of repositories written owner/repo (got ${JSON.stringify(value)})` });
+        break;
+      }
+      value.filter((v) => !REPO_RE.test(v)).forEach((v) => errors.push({ path, message: `${path}: "${v}" is not a repository; the form is owner/repo` }));
+      value.filter((v, i) => value.indexOf(v) !== i).forEach((v) => errors.push({ path, message: `${path} lists "${v}" more than once` }));
+      break;
+    }
+    case 'origin-list': {
+      if (!Array.isArray(value) || value.some((v) => typeof v !== 'string')) {
+        errors.push({ path, message: `${path} must be a list of web origins written like https://staging.example.com (got ${JSON.stringify(value)})` });
+        break;
+      }
+      value.filter((v) => !ORIGIN_RE.test(v)).forEach((v) => errors.push({ path, message: `${path}: "${v}" is not an origin; write the scheme, the host and optionally the port, with no path (https://staging.example.com)` }));
+      break;
+    }
+    case 'enum':
+      if (!setting.allowed.includes(value)) {
+        errors.push({
+          path,
+          message: `${path} has invalid value ${JSON.stringify(value)}; allowed values: ${describeAllowed(setting.allowed)}`,
+        });
+      }
+      break;
+    case 'bool':
+      if (typeof value !== 'boolean') errors.push({ path, message: `${path} must be true or false (got ${JSON.stringify(value)})` });
+      break;
+    case 'int':
+      if (!Number.isInteger(value) || value < setting.min) {
+        errors.push({ path, message: `${path} must be an integer >= ${setting.min} (got ${JSON.stringify(value)})` });
+      }
+      break;
+    case 'number':
+      if (typeof value !== 'number' || !(value > setting.exclusiveMin)) {
+        errors.push({ path, message: `${path} must be a number > ${setting.exclusiveMin} (got ${JSON.stringify(value)})` });
+      }
+      break;
+    default:
+      break;
+  }
+}
+
+function collectStrings(value, path, out) {
+  if (typeof value === 'string') out.push({ path, value });
+  else if (Array.isArray(value)) value.forEach((v, i) => collectStrings(v, `${path}[${i}]`, out));
+  else if (value && typeof value === 'object') {
+    Object.entries(value).forEach(([k, v]) => collectStrings(v, path ? `${path}.${k}` : k, out));
+  }
+}
+
+/**
+ * Validate a parsed configuration object.
+ * Returns { ok, errors, warnings, config } where config has defaults applied.
+ */
+export function validateConfig(raw, { knownTargets = null, knownChecks = null } = {}) {
+  const errors = [];
+  const warnings = [];
+  const user = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {};
+
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    errors.push({ path: '', message: 'relevo.yml must be a map of settings' });
+  }
+
+  // Unknown top-level keys and unknown keys inside groups (catches typos).
+  Object.keys(user).forEach((key) => {
+    if (!KNOWN_TOP.has(key)) errors.push({ path: key, message: `unknown setting "${key}"` });
+  });
+  GROUPS.forEach((group) => {
+    const value = user[group];
+    if (value === undefined || value === null) return;
+    if (typeof value !== 'object' || Array.isArray(value)) {
+      errors.push({ path: group, message: `${group} must be a map` });
+      return;
+    }
+    const known = new Set(SETTINGS.filter((s) => s.path.startsWith(`${group}.`)).map((s) => s.path.split('.')[1]));
+    Object.keys(value).forEach((k) => {
+      if (!known.has(k)) errors.push({ path: `${group}.${k}`, message: `unknown setting "${group}.${k}"` });
+    });
+  });
+
+  // Per-setting checks and defaults.
+  const config = {};
+  SETTINGS.forEach((setting) => {
+    const value = getPath(user, setting.path);
+    if (value === undefined || value === null) {
+      if (setting.required) {
+        errors.push({
+          path: setting.path,
+          message: `${setting.path} is required: unattended runs must always have a cost limit (amount in US dollars per run)`,
+        });
+        return;
+      }
+      setPath(config, setting.path, structuredClone(setting.default));
+      return;
+    }
+    // A single file name is the same as a list of one.
+    const given = setting.type === 'path-list' && typeof value === 'string' ? [value] : value;
+    checkType(setting, given, errors);
+    setPath(config, setting.path, given);
+  });
+
+  // Platforms: the registry, or the legacy shortcut turned into one entry.
+  const normalized = normalizePlatforms({ platform: user.platform, platforms: user.platforms }, { knownTargets });
+  errors.push(...normalized.errors);
+  config.platforms = normalized.platforms;
+  if (knownChecks) {
+    Object.entries(config.platforms).forEach(([name, entry]) => {
+      const valid = knownChecks(entry.stack);
+      if (!valid) return;
+      Object.keys(entry.checks ?? {}).filter((c) => !valid.includes(c)).forEach((c) => {
+        errors.push({ path: `platforms.${name}.checks.${c}`, message: `platforms.${name}.checks has unknown command "${c}"; the stack "${entry.stack}" defines: ${valid.join(', ')}` });
+      });
+    });
+  }
+
+  // Labels: renameable, unique, within GitHub's length limit.
+  const labels = user.labels;
+  config.labels = {};
+  if (labels !== undefined && labels !== null) {
+    if (typeof labels !== 'object' || Array.isArray(labels)) {
+      errors.push({ path: 'labels', message: 'labels must be a map of label key to label name' });
+    } else {
+      Object.entries(labels).forEach(([key, name]) => {
+        if (!LABEL_KEYS.includes(key)) {
+          errors.push({ path: `labels.${key}`, message: `unknown label key "${key}"; allowed keys: ${describeAllowed(LABEL_KEYS)}` });
+        } else if (typeof name !== 'string' || name.trim() === '' || name.length > GITHUB_LABEL_MAX) {
+          errors.push({ path: `labels.${key}`, message: `labels.${key} must be a non-empty string of at most ${GITHUB_LABEL_MAX} characters` });
+        } else {
+          config.labels[key] = name;
+        }
+      });
+      const names = Object.values(config.labels);
+      if (new Set(names).size !== names.length) {
+        errors.push({ path: 'labels', message: 'label names must be unique' });
+      }
+    }
+  }
+
+  // Language: any language tag; only some have message catalogs.
+  const lang = config.language;
+  if (typeof lang === 'string') {
+    if (!LANGUAGE_RE.test(lang)) {
+      errors.push({ path: 'language', message: `language must look like "en" or "pt-BR" (got ${JSON.stringify(lang)})` });
+    } else if (!SUPPORTED_LANGUAGES.includes(lang.split('-')[0])) {
+      warnings.push({
+        path: 'language',
+        message: `no message catalog for "${lang}"; messages fall back to "en" (available: ${SUPPORTED_LANGUAGES.join(', ')})`,
+      });
+    }
+  }
+
+  // Cross-setting rules.
+  if (config.review.mode === 'roles' && config.team.approvers.length === 0) {
+    errors.push({ path: 'team.approvers', message: 'team.approvers must list at least one person when review.mode is "roles"' });
+  }
+  if (config.trust === 'public' && config.review.mode === 'none') {
+    errors.push({ path: 'review.mode', message: 'trust "public" needs a human review of generated code: review.mode cannot be "none"' });
+  }
+  if (config.review.mode === 'peer' || config.review.mode === 'roles') {
+    const eligible = config.team.members.filter((m) => m !== config.team.spec_writer);
+    if (eligible.length < 2) {
+      warnings.push({
+        path: 'team.members',
+        message: 'review.mode needs a second person to review: team.members should list at least 2 people besides the spec writer',
+      });
+    }
+  }
+
+  // Credentials must never live in this file (checked on every value and key).
+  const strings = [];
+  collectStrings(user, '', strings);
+  strings.forEach(({ path, value }) => {
+    if (findCredentials(value, { strict: true }).length > 0) {
+      errors.push({
+        path,
+        message: `${path || 'value'} looks like a credential; move it to the repository secret store, never to relevo.yml`,
+      });
+    }
+  });
+  const flatKeys = [];
+  (function walk(obj, prefix) {
+    if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return;
+    Object.entries(obj).forEach(([k, v]) => {
+      flatKeys.push({ key: k, path: prefix ? `${prefix}.${k}` : k });
+      walk(v, prefix ? `${prefix}.${k}` : k);
+    });
+  }(user, ''));
+  flatKeys.forEach(({ key, path }) => {
+    if (/(api[_-]?key|secret|password|token)/i.test(key)) {
+      errors.push({
+        path,
+        message: `${path} looks like a credential setting; move it to the repository secret store, never to relevo.yml`,
+      });
+    }
+  });
+
+  return { ok: errors.length === 0, errors, warnings, config };
+}
+
+/** Parse relevo.yml text and validate it. Parse errors are returned as errors. */
+export function loadConfig(text, options = {}) {
+  let raw;
+  try {
+    raw = parse(text);
+  } catch (err) {
+    if (err instanceof YamlLiteError) {
+      return { ok: false, errors: [{ path: '', message: `relevo.yml is not valid: ${err.message}` }], warnings: [], config: null };
+    }
+    throw err;
+  }
+  return validateConfig(raw, options);
+}

package/scripts/lib/design-fetch.mjs

@@ -0,0 +1,156 @@
+// Downloads the references of a design reference, inside fixed limits. Implements "The fetcher stays inside fixed
+// limits" of openspec/specs/go/spec.md. The network and `gh` are injected so the module is tested without either.
+
+import { ATTACHMENT_HOSTS, MAX_REFERENCES } from './issue-parse.mjs';
+
+export const IMAGE_MAX = 5 * 1024 * 1024;
+export const TEXT_MAX = 200 * 1024;
+export const FILES_MAX = MAX_REFERENCES;
+export const HOPS_MAX = 5;
+// Where a download may be redirected to: the attachment domains and the host that serves them signed.
+export const REDIRECT_HOSTS = [...ATTACHMENT_HOSTS, 'objects.githubusercontent.com'];
+// The token is sent only here.
+const TOKEN_HOSTS = new Set(['github.com', 'api.github.com']);
+
+/** png, jpeg, gif or webp from the first bytes, or null. The name and the Content-Type are never trusted. */
+export function sniffImage(buf) {
+  const b = Buffer.from(buf);
+  if (b.length >= 8 && b.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) return 'png';
+  if (b.length >= 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff) return 'jpeg';
+  if (b.length >= 6 && ['GIF87a', 'GIF89a'].includes(b.subarray(0, 6).toString('latin1'))) return 'gif';
+  if (b.length >= 12 && b.subarray(0, 4).toString('latin1') === 'RIFF' && b.subarray(8, 12).toString('latin1') === 'WEBP') return 'webp';
+  return null;
+}
+
+/** Is it UTF-8 text, with no NUL byte? */
+export function isText(buf) {
+  const b = Buffer.from(buf);
+  if (b.includes(0)) return false;
+  try {
+    new TextDecoder('utf-8', { fatal: true }).decode(b);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const hostOf = (url) => {
+  try {
+    const u = new URL(url);
+    return u.protocol === 'https:' ? u.hostname : null;
+  } catch {
+    return null;
+  }
+};
+
+async function readCapped(res, max) {
+  const declared = Number(res.headers?.get?.('content-length'));
+  if (Number.isFinite(declared) && declared > max) return { tooLarge: true };
+  if (!res.body?.getReader) {
+    const buf = Buffer.from(await res.arrayBuffer());
+    return buf.length > max ? { tooLarge: true } : { buf };
+  }
+  const reader = res.body.getReader();
+  const chunks = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.length;
+    if (total > max) {
+      await reader.cancel().catch(() => {});
+      return { tooLarge: true };
+    }
+    chunks.push(Buffer.from(value));
+  }
+  return { buf: Buffer.concat(chunks) };
+}
+
+/**
+ * Download one pasted attachment. Redirects are followed by hand and only to REDIRECT_HOSTS; the token goes only to
+ * GitHub. Returns { ok: true, buf, type } or { ok: false, reason }.
+ */
+export async function downloadAttachment(url, { fetch, token = null, max = IMAGE_MAX } = {}) {
+  let current = url;
+  for (let hop = 0; hop <= HOPS_MAX; hop += 1) {
+    const host = hostOf(current);
+    if (!host || !REDIRECT_HOSTS.includes(host)) return { ok: false, reason: `${host ?? 'that address'} is not an allowed host` };
+    const headers = token && TOKEN_HOSTS.has(host) ? { authorization: `Bearer ${token}` } : {};
+    let res;
+    try {
+      res = await fetch(current, { redirect: 'manual', headers });
+    } catch (error) {
+      return { ok: false, reason: `the download failed: ${String(error?.message ?? error).split('\n')[0]}` };
+    }
+    if (res.status >= 300 && res.status < 400) {
+      const location = res.headers?.get?.('location');
+      if (!location) return { ok: false, reason: 'the redirect has no destination' };
+      current = new URL(location, current).href;
+      continue;
+    }
+    if (res.status !== 200) return { ok: false, reason: `GitHub answered ${res.status}${res.status === 404 || res.status === 403 ? ' (the token may not read it)' : ''}` };
+    const { buf, tooLarge } = await readCapped(res, max);
+    if (tooLarge) return { ok: false, reason: `the file is larger than ${Math.round(max / 1024 / 1024)} MB` };
+    const type = sniffImage(buf);
+    if (!type) return { ok: false, reason: 'the file is not a PNG, JPEG, GIF or WebP image' };
+    return { ok: true, buf, type };
+  }
+  return { ok: false, reason: `more than ${HOPS_MAX} redirects` };
+}
+
+/** One file of a linked repository, read through `gh api` (injected). Returns { ok, buf, type } or { ok: false, reason }. */
+export async function fetchRepoFile({ repo, path }, { gh, max = TEXT_MAX } = {}) {
+  let info;
+  try {
+    info = JSON.parse(gh(['api', `repos/${repo}/contents/${path}`]));
+  } catch (error) {
+    return { ok: false, reason: `${repo} could not be read: ${String(error?.message ?? error).split('\n')[0]}` };
+  }
+  if (Array.isArray(info) || info.type !== 'file') return { ok: false, reason: `${path} is not a file` };
+  if (info.size > max) return { ok: false, reason: `the file is larger than ${Math.round(max / 1024)} KB` };
+  if (info.encoding !== 'base64' || typeof info.content !== 'string') return { ok: false, reason: 'the file could not be read' };
+  const buf = Buffer.from(info.content, 'base64');
+  if (buf.length > max) return { ok: false, reason: `the file is larger than ${Math.round(max / 1024)} KB` };
+  if (!isText(buf)) return { ok: false, reason: 'the file is not text' };
+  return { ok: true, buf, type: 'text' };
+}
+
+/**
+ * The references of an issue (from parseDesign) turned into files.
+ *   references  [{ kind, target, repo?, path?, allowed?, match }]
+ *   images      design.images
+ *   links       the linked repositories
+ *   exists      (path) => boolean, for the references to files of the repository
+ * Returns { files: [{ reference, kind, buf?, type }], refused: [{ reference, reason }] }.
+ * A `path` reference needs no download: it is checked and the builder reads it where it is.
+ */
+export async function fetchReferences({ references, images = false, links = [], exists, fetch, gh, token = null }) {
+  const files = [];
+  const refused = [];
+  for (const ref of references) {
+    if (files.length >= FILES_MAX) {
+      refused.push({ reference: ref.target, reason: `more than ${FILES_MAX} references` });
+      continue;
+    }
+    if (ref.kind === 'path') {
+      if (exists(ref.path)) files.push({ reference: ref.target, kind: 'path', path: ref.path, type: 'repository' });
+      else refused.push({ reference: ref.target, reason: 'the file does not exist in the repository' });
+    } else if (ref.kind === 'attachment') {
+      if (!ref.allowed) refused.push({ reference: ref.target, reason: 'it is not a GitHub attachment' });
+      else if (!images) refused.push({ reference: ref.target, reason: 'design.images is off: turn it on in relevo.yml, or commit the picture to the repository and point to the file' });
+      else {
+        const r = await downloadAttachment(ref.target, { fetch, token });
+        if (r.ok) files.push({ reference: ref.target, kind: 'attachment', buf: r.buf, type: r.type });
+        else refused.push({ reference: ref.target, reason: r.reason });
+      }
+    } else if (ref.kind === 'repo-file') {
+      if (!links.includes(ref.repo)) refused.push({ reference: ref.target, reason: `${ref.repo} is not in links of relevo.yml` });
+      else {
+        const r = await fetchRepoFile(ref, { gh });
+        if (r.ok) files.push({ reference: ref.target, kind: 'repo-file', buf: r.buf, type: r.type, path: ref.path });
+        else refused.push({ reference: ref.target, reason: r.reason });
+      }
+    }
+  }
+  return { files, refused };
+}