cornfield 0.1.2 → 0.3.0

package/server/forge-actions.js

@@ -45,13 +45,12 @@ import { ForgeError, RERUN_STATES, canRerun, isMaintainer } from './forge.js';
 import { sameOrigin } from './proposals.js';
 import { planSpec, planBuild, startSpec, openBuildIssue } from './pipeline.js';
 import { PROPOSAL_FILE } from './files.js';
+import { Refused, throttle, countAttempt } from './throttle.js';
+
+// The limits live in server/throttle.js (reviews share them); these are re-exported for the callers that always had them here
+export { COOLDOWN_MS, PER_MINUTE, ATTEMPTS_PER_MINUTE, countAttempt } from './throttle.js';
+import { proposalPayload, landedPayload } from './hooks.js';
 
-/** The same action on the same target is not asked again for this long (a double click, a retry before the forge has caught up) */
-export const COOLDOWN_MS = 5000;
-/** The most actions one person takes in a minute */
-export const PER_MINUTE = 20;
-/** The most attempts of any kind (refused ones too) one person makes in a minute, before any is written down */
-export const ATTEMPTS_PER_MINUTE = 60;
 /** A request body is a sha and a check's id */
 const MAX_BODY = 4096;
 
@@ -62,39 +61,6 @@ const DIGEST = /^[0-9a-f]{32}$/;
 const DOING = { merge: 'Landing', rerun: 'Re-running', spec: 'Starting a spec', build: 'Opening the build issue' };
 const ONLY_MAINTAINERS = { merge: 'land pull requests or re-run checks', rerun: 'land pull requests or re-run checks', spec: 'start specs', build: 'open build issues' };
 
-/** @type {WeakMap<object, { busy: Set<string>, last: Map<string, number>, perUser: Map<string, number[]>, attempts: Map<string, number[]> }>} */
-const throttles = new WeakMap();
-
-function throttlesOf(auth) {
-  let t = throttles.get(auth);
-  if (!t) throttles.set(auth, (t = { busy: new Set(), last: new Map(), perUser: new Map(), attempts: new Map() }));
-  return t;
-}
-
-/** Counts an attempt of any kind; refuses one past the ceiling, without writing anything down (the release draft shares it) */
-export function countAttempt(ctx, userId, at) {
-  const t = throttlesOf(ctx.auth);
-  for (const [k, list] of t.attempts) if (!list.length || at - list[list.length - 1] >= 60_000) t.attempts.delete(k);
-  const mine = (t.attempts.get(userId) || []).filter((when) => at - when < 60_000);
-  if (mine.length >= ATTEMPTS_PER_MINUTE) {
-    t.attempts.set(userId, mine);
-    return new Refused(429, `That is ${ATTEMPTS_PER_MINUTE} attempts in a minute; wait a little.`, 'rate-limited', { 'Retry-After': String(Math.max(1, Math.ceil((60_000 - (at - mine[0])) / 1000))) });
-  }
-  mine.push(at);
-  t.attempts.set(userId, mine);
-  return null;
-}
-
-/** An action's own refusal: the status to answer and the words */
-class Refused extends Error {
-  constructor(status, message, code, headers = {}) {
-    super(message);
-    this.status = status;
-    this.code = code;
-    this.headers = headers;
-  }
-}
-
 /** Reads a small JSON object body, or refuses */
 function readJson(req) {
   return new Promise((resolve, reject) => {
@@ -129,23 +95,6 @@ function readJson(req) {
   });
 }
 
-/** Refuses a repeat and a flood; answers the key to release when the attempt is over */
-function throttle(ctx, userId, key, at) {
-  const t = throttlesOf(ctx.auth);
-  for (const [k, when] of t.last) if (at - when >= COOLDOWN_MS) t.last.delete(k);
-  const mine = (t.perUser.get(userId) || []).filter((when) => at - when < 60_000);
-  t.perUser.set(userId, mine);
-  const wait = (ms, words) => new Refused(429, words, 'rate-limited', { 'Retry-After': String(Math.max(1, Math.ceil(ms / 1000))) });
-  if (t.busy.has(key)) throw wait(COOLDOWN_MS, 'That is already being done; wait for it to finish.');
-  const before = t.last.get(key);
-  if (before !== undefined && at - before < COOLDOWN_MS) throw wait(COOLDOWN_MS - (at - before), 'That was just asked; wait a few seconds before asking again.');
-  if (mine.length >= PER_MINUTE) throw wait(60_000 - (at - mine[0]), `That is ${PER_MINUTE} actions in a minute; wait a little.`);
-  t.busy.add(key);
-  t.last.set(key, at);
-  mine.push(at);
-  return () => { t.busy.delete(key); };
-}
-
 /**
  * The permission of the signed-in user on the repo, asked of the forge now with their own token. Refuses unless it is
  * the same forge user as the session's and a maintainer.
@@ -181,7 +130,7 @@ export function actionOf(reqPath) {
  * @param {import('node:http').IncomingMessage} req
  * @param {import('node:http').ServerResponse} res
  * @param {{ n: number, action: 'merge' | 'rerun' | 'spec' | 'build' }} what
- * @param {{ config: object, where?: { proposals: string }, session: { login: string, userId: string } | null, auth: { store: null | (() => Promise<import('node:sqlite').DatabaseSync>), forgeFor: Function }, now?: () => number, publicHost?: string | null }} ctx
+ * @param {{ config: object, where?: { proposals: string }, hooks?: import('./hooks.js').Hooks | null, session: { login: string, userId: string } | null, auth: { store: null | (() => Promise<import('node:sqlite').DatabaseSync>), forgeFor: Function }, now?: () => number, publicHost?: string | null }} ctx
  * @param {(status: number, body: object, headers?: object) => void} send
  */
 export async function serveAction(req, res, what, ctx, send) {
@@ -275,12 +224,15 @@ export async function serveAction(req, res, what, ctx, send) {
       if (!plan.existing && plan.sha.toLowerCase() !== sha) throw new ForgeError(`Pull request #${n} has changed since it was looked at (its proposal is now at ${plan.sha.slice(0, 7)}); look again.`, { code: 'conflict' });
       if (!plan.existing && plan.digest !== digest) throw new ForgeError(`What the build issue for ${slug} would say has changed since it was shown (a new review, or a push); look again.`, { code: 'conflict' });
       const done = await openBuildIssue(forge, plan);
+      // Only an issue this ask made is news: a second ask that found the first one's says nothing again
+      if (done.created) ctx.hooks?.emit('build.opened', () => proposalPayload(forge, ctx.where || { proposals: config.proposals }, plan, { actor: session.login }));
       await forgetKept(auth, config);
       out = { status: done.created ? 201 : 200, body: { ok: true, action, created: done.created, number: n, slug, issue: done.issue, path: plan.path } };
     } else if (action === 'merge') {
       const method = config.forge.mergeMethod || 'merge';
       request.method = method;
       const landed = await forge.merge(n, { onlyIfGreen: true, sha, method });
+      ctx.hooks?.emit('pr.landed', () => landedPayload(forge, ctx.where || { proposals: config.proposals }, n, /** @type {string} */ (sha), session.login));
       await forgetKept(auth, config);
       out = { status: 200, body: { ok: true, merged: true, number: n, sha: landed.sha, head: sha, method } };
     } else {

package/server/forge-routes.js

@@ -111,7 +111,7 @@ function notesInput(config, since) {
  * The reads: the request's route, the forge call that answers it, and the key it is kept under.
  * @returns {{ key: string, load: (forge: import('./forge.js').Forge) => Promise<object> } | null}
  */
-function routeOf(reqPath, url, config, where) {
+function routeOf(reqPath, url, config, where, hooks = null) {
   if (reqPath === '/api/forge/release-notes') {
     const since = sinceOf(url.searchParams.get('since'));
     return { key: `release-notes?since=${since ?? ''}&label=${config.releaseNotes?.breakingLabel ?? ''}`, load: (forge) => releaseNotes(forge, notesInput(config, since)) };
@@ -136,7 +136,7 @@ function routeOf(reqPath, url, config, where) {
       key: 'work',
       load: async (forge) => {
         const [pulls, issues, branches, specs] = await Promise.all([
-          forge.pulls({ state: 'all', limit: WORK_PULLS }), forge.issues({ state: 'all', labels: [], limit: WORK_ISSUES }), forge.branches(), listPullProposals(forge, config),
+          forge.pulls({ state: 'all', limit: WORK_PULLS }), forge.issues({ state: 'all', labels: [], limit: WORK_ISSUES }), forge.branches(), listPullProposals(forge, config, { hooks }),
         ]);
         return {
           pulls: pulls.map((p) => ({ ...p, body: p.body.slice(0, WORK_BODY_MAX) })),
@@ -220,7 +220,7 @@ async function servePlan(req, res, act, url, ctx) {
  * @param {import('node:http').ServerResponse} res
  * @param {string} reqPath the decoded path
  * @param {URL} url
- * @param {{ config: object, where?: { proposals: string }, session: { userId: string, login: string } | null, publicHost?: string | null, auth: { store: null | (() => Promise<import('node:sqlite').DatabaseSync>), forgeFor: Function }, now?: () => number }} ctx
+ * @param {{ config: object, where?: { proposals: string }, hooks?: import('./hooks.js').Hooks | null, session: { userId: string, login: string } | null, publicHost?: string | null, auth: { store: null | (() => Promise<import('node:sqlite').DatabaseSync>), forgeFor: Function }, now?: () => number }} ctx
  *   `session` is the signed-in maintainer's (null without sign-in)
  * @returns {Promise<boolean>}
  */
@@ -270,7 +270,7 @@ export async function serveForge(req, res, reqPath, url, ctx) {
     return true;
   }
   try {
-    const route = routeOf(reqPath, url, config, ctx.where);
+    const route = routeOf(reqPath, url, config, ctx.where, ctx.hooks);
     if (!route) {
       send(req, res, 404, { ok: false, error: `${reqPath} is not a forge route.`, code: 'not-found' });
       return true;

package/server/hooks.js

@@ -0,0 +1,303 @@
+/**
+ * @module server/hooks
+ *
+ * Event hooks (PIPE-07, docs/config.md#hooks): cornfield tells outside code what happened. The config's
+ * `hooks: [{ url, events }]` lists where; when something happens, `emit(event, payload)` posts one JSON body to each
+ * hook that asked for that event:
+ *
+ *   spec.ready      a spec PR that is not a draft was first seen, or was seen at a new head: it is waiting for review.
+ *                   A draft (a "Start a spec" stub among them) is never announced; one marked ready is, at its head.
+ *                   cornfield has no webhook receiver: it notices when it next lists the PRs, so this fires when
+ *                   cornfield next looks, not at the push. The first look at a repo after hooks are added announces
+ *                   nothing: it records what is open, so only what changes after it is news
+ *   spec.approved   a maintainer approved a proposal          spec.sentBack   a maintainer sent one back
+ *   build.opened    the build issue of an approved proposal was opened
+ *   pr.landed       a pull request was landed through cornfield (its Land it); a merge made on the forge sends nothing
+ *
+ * **A hook never gets in the way.** `emit` returns at once and never throws; the delivery runs in the background, from a
+ * queue in memory. A failed delivery (a network error, a timeout, anything but a 2xx) is tried again after 1s, 5s and 30s
+ * (four attempts in all) and every attempt is a row in the `actions` audit table (`action: 'hook'`). A hook that is
+ * dead, slow or wrong changes nothing else in cornfield. Deliveries wait in memory only: a restart forgets the ones
+ * still being retried.
+ *
+ * **What is sent.** `{ event, at, slug, pull, headSha, proposalSha256, actor, note?, edits?, mapUrl }`, built here from
+ * a fixed list of fields, so nothing else can leak into it: never file contents, a token or an email. The hook's URL
+ * comes only from the maintainer's config and is still treated with care: no redirect is followed, a request is given
+ * 10 seconds, and at most `MAX_RESPONSE_BYTES` of the answer are read (it is never kept). The audit rows name the hook's
+ * origin only, never its path or query, which may hold a secret of the receiver's.
+ *
+ * **Signed.** Each request carries `X-Cornfield-Signature: sha256=<hex>`, the HMAC-SHA256 of the raw body under
+ * CORNFIELD_HOOK_SECRET (env only, at least 32 characters; hooks without it are a startup error, `hooksSettings`), and
+ * `X-Cornfield-Event`, `X-Cornfield-Delivery` (a UUID, the same on every retry) and `X-Cornfield-Timestamp` (the body's
+ * `at`), so a receiver can refuse a replay. The secret is never logged or put in a row.
+ */
+
+import { createHmac, randomUUID } from 'node:crypto';
+import { HOOK_EVENTS } from '../core/config.js';
+import { pullProposals, readPullProposal } from './proposal-pulls.js';
+import { proposalHash } from './reviews.js';
+
+/** @typedef {ReturnType<typeof createHooks>} Hooks */
+
+export { HOOK_EVENTS };
+/** The env var the signing secret is read from: never the config file */
+export const HOOK_SECRET_ENV = 'CORNFIELD_HOOK_SECRET';
+export const MIN_HOOK_SECRET = 32;
+/** The wait before each retry; the first attempt is made at once, so a failing hook is tried four times */
+export const BACKOFF_MS = Object.freeze([1_000, 5_000, 30_000]);
+/** How long one request may take */
+export const TIMEOUT_MS = 10_000;
+/** How much of an answer is read before it is dropped */
+export const MAX_RESPONSE_BYTES = 4096;
+/** The most deliveries waiting (or being retried) at once; one past it is dropped, and the audit table says so */
+export const MAX_PENDING = 500;
+
+/**
+ * The hook settings env gives, or null when the config lists no hooks. Throws, in words, when hooks are listed but cannot
+ * work: no secret, a short one, or no sign-in (every event comes from a signed-in maintainer's action or listing).
+ * @param {{ hooks?: unknown[] }} config
+ * @param {Record<string, string | undefined>} [env]
+ * @param {boolean} [signIn] whether sign-in is configured
+ * @returns {null | { secret: string }}
+ */
+export function hooksSettings(config, env = process.env, signIn = true) {
+  if (!Array.isArray(config.hooks) || config.hooks.length === 0) return null;
+  const secret = env[HOOK_SECRET_ENV];
+  if (typeof secret !== 'string' || secret === '') throw new Error(`The config lists hooks, so ${HOOK_SECRET_ENV} is needed: a random value of at least ${MIN_HOOK_SECRET} characters that signs every event (openssl rand -base64 48). Never put it in the config.`);
+  if (secret.length < MIN_HOOK_SECRET) throw new Error(`${HOOK_SECRET_ENV} is too short: use at least ${MIN_HOOK_SECRET} random characters (openssl rand -base64 48).`);
+  if (!signIn) throw new Error('The config lists hooks, but sign-in is not set up. Every event comes from something a signed-in maintainer does in cornfield (a review, a build issue, a landing) or from the spec PRs cornfield lists for them, so without sign-in no hook would ever fire: set up sign-in (docs/sign-in.md), or remove `hooks`.');
+  return { secret };
+}
+
+/** The HMAC-SHA256 of a body under the secret, as a request header carries it */
+export const sign = (secret, body) => `sha256=${createHmac('sha256', secret).update(body).digest('hex')}`;
+
+/** A hook's address for the audit table: the origin only (a path or query may be a secret of the receiver's) */
+const originOf = (url) => new URL(url).origin;
+
+/** What went wrong with a request, without its message (a fetch error's text can hold the URL) */
+const reasonOf = (err) => {
+  if (err && err.name === 'AbortError') return 'timeout';
+  const code = err && (err.cause?.code || err.code);
+  return typeof code === 'string' ? code : 'error';
+};
+
+/** Reads at most `cap` bytes of a response and drops the rest, so the connection is freed */
+async function drain(res, cap) {
+  if (!res.body) return;
+  const reader = res.body.getReader();
+  let read = 0;
+  try {
+    while (read < cap) {
+      const { done, value } = await reader.read();
+      if (done) return;
+      read += value.length;
+    }
+  } finally {
+    await reader.cancel().catch(() => {});
+  }
+}
+
+/**
+ * The hooks of a server.
+ * @param {{
+ *   hooks: { url: string, events: string[] | '*' }[],
+ *   secret: string,
+ *   fetch?: typeof fetch,
+ *   record?: (entry: { login: string, action: string, target: string, request?: object, status?: number | null, answer?: object | null }) => Promise<void> | void,
+ *   store?: (() => Promise<import('node:sqlite').DatabaseSync>) | null,
+ *   now?: () => number,
+ *   publicUrl?: string | null,
+ *   timer?: { setTimeout: Function, clearTimeout: Function },
+ *   backoff?: readonly number[],
+ * }} opts `fetch`, `timer` and `backoff` are for tests; `store` is the SQLite file `spec.ready` remembers what it sent in
+ */
+export function createHooks({ hooks, secret, fetch: doFetch = globalThis.fetch, record, store = null, now = Date.now, publicUrl = null, timer = { setTimeout, clearTimeout }, backoff = BACKOFF_MS }) {
+  if (typeof secret !== 'string' || secret.length < MIN_HOOK_SECRET) throw new Error(`${HOOK_SECRET_ENV} must be at least ${MIN_HOOK_SECRET} characters.`);
+  const targets = hooks.map((h, i) => ({ index: i, url: h.url, origin: originOf(h.url), events: h.events === '*' ? HOOK_EVENTS : h.events }));
+  const timers = new Set();
+  let pending = 0;
+  let closed = false;
+
+  const later = (fn, ms) => {
+    const t = timer.setTimeout(() => { timers.delete(t); fn(); }, ms);
+    if (t && typeof t.unref === 'function') t.unref();
+    timers.add(t);
+    return t;
+  };
+
+  const audit = async (target, request, status, answer) => {
+    if (!record || closed) return;
+    try {
+      await record({ login: 'cornfield', action: 'hook', target, request, status, answer });
+    } catch (err) {
+      console.error(`[cornfield] a hook delivery could not be written to the audit table: ${err instanceof Error ? err.message : err}`);
+    }
+  };
+
+  /** One request, answered with its HTTP status (null when there was none) and why it failed (null when it did not) */
+  async function post(t, headers, body) {
+    const ctl = new AbortController();
+    const cut = timer.setTimeout(() => ctl.abort(), TIMEOUT_MS);
+    // A request still in flight at shutdown must not keep the process alive for its last seconds
+    if (cut && typeof cut.unref === 'function') cut.unref();
+    try {
+      // A redirect is never followed: the address is the maintainer's, and only it
+      const res = await doFetch(t.url, { method: 'POST', headers, body, redirect: 'manual', signal: ctl.signal });
+      await drain(res, MAX_RESPONSE_BYTES);
+      return res.status >= 200 && res.status < 300 ? { status: res.status, failed: null } : { status: res.status, failed: res.status >= 300 && res.status < 400 ? 'redirect' : 'status' };
+    } catch (err) {
+      return { status: null, failed: reasonOf(err) };
+    } finally {
+      timer.clearTimeout(cut);
+    }
+  }
+
+  function deliver(t, event, delivery, body) {
+    const headers = {
+      'Content-Type': 'application/json',
+      'User-Agent': 'cornfield-hooks',
+      'X-Cornfield-Event': event,
+      'X-Cornfield-Delivery': delivery,
+      'X-Cornfield-Timestamp': JSON.parse(body).at,
+      'X-Cornfield-Signature': sign(secret, body),
+    };
+    const target = `${event} to ${t.origin}`;
+    const attempt = async (n) => {
+      if (closed) { pending -= 1; return; }
+      const out = await post(t, headers, body);
+      // Shut down while the request was in flight: nothing more is written or scheduled
+      if (closed) { pending -= 1; return; }
+      const last = out.failed !== null && n > backoff.length;
+      const request = { event, delivery, hook: t.index, origin: t.origin, attempt: n };
+      await audit(target, request, out.status, out.failed === null ? { ok: true } : { ok: false, reason: out.failed, ...(last ? { gaveUp: true } : { retryInMs: backoff[n - 1] }) });
+      if (out.failed === null || last) { pending -= 1; return; }
+      later(() => { attempt(n + 1).catch(() => {}); }, backoff[n - 1]);
+    };
+    attempt(1).catch((err) => console.error(`[cornfield] a hook delivery failed unexpectedly: ${err instanceof Error ? err.message : err}`));
+  }
+
+  /** The body of an event: only the fields of the payload, in a fixed order */
+  function bodyOf(event, p) {
+    const out = {
+      event, at: new Date(now()).toISOString(), slug: p.slug ?? null, pull: p.pull ?? null, headSha: p.headSha ?? null,
+      proposalSha256: p.proposalSha256 ?? null, actor: p.actor ?? null,
+    };
+    if (p.note !== undefined) out.note = p.note;
+    if (p.edits !== undefined) out.edits = p.edits;
+    out.mapUrl = publicUrl || null;
+    return JSON.stringify(out);
+  }
+
+  /**
+   * Sends `event` to each hook that asked for it. Returns at once and never throws. The payload is an object, or a
+   * function returning one (or a promise of one): that is run in the background too, so gathering it never slows the
+   * action down, and a failure gathering it is written down and sends nothing.
+   * @param {string} event one of HOOK_EVENTS
+   * @param {object | (() => object | Promise<object>)} payload
+   */
+  function emit(event, payload) {
+    try {
+      if (closed || !HOOK_EVENTS.includes(event)) return;
+      const to = targets.filter((t) => t.events.includes(event));
+      if (!to.length) return;
+      Promise.resolve()
+        .then(() => (typeof payload === 'function' ? payload() : payload))
+        .then((p) => {
+          const body = bodyOf(event, p || {});
+          for (const t of to) {
+            if (pending >= MAX_PENDING) {
+              audit(`${event} to ${t.origin}`, { event, hook: t.index, origin: t.origin }, null, { ok: false, reason: 'queue-full', gaveUp: true });
+              continue;
+            }
+            pending += 1;
+            deliver(t, event, randomUUID(), body);
+          }
+        })
+        .catch((err) => {
+          console.error(`[cornfield] the ${event} hook event could not be built: ${err instanceof Error ? err.message : err}`);
+          audit(`${event}`, { event }, null, { ok: false, reason: 'payload', gaveUp: true });
+        });
+    } catch (err) {
+      console.error(`[cornfield] the ${event} hook event was not sent: ${err instanceof Error ? err.message : err}`);
+    }
+  }
+
+  /**
+   * `spec.ready`: the spec PRs a listing just showed. A (pull request, head, proposal) that is not a draft and was not
+   * seen before is announced once, and remembered in the SQLite file so a restart does not announce it again. A draft is
+   * not recorded, so marking it ready announces it at its head. The first listing of a repo (no `hook_seen` row for it,
+   * not even the `pr = 0` row that says it has been looked at) records what is open and announces nothing. Returns at
+   * once, never throws.
+   * @param {string} repo 'owner/name'
+   * @param {import('./proposal-pulls.js').PullEntry[]} entries
+   * @param {(entry: import('./proposal-pulls.js').PullEntry) => Promise<string>} read the proposal's text at its head
+   */
+  function specsSeen(repo, entries, read) {
+    // Even an empty listing counts: it is what makes the first spec PR opened afterwards news
+    if (closed || !store || !Array.isArray(entries)) return;
+    (async () => {
+      const db = await store();
+      const at = new Date(now()).toISOString();
+      const looked = db.prepare('SELECT 1 FROM hook_seen WHERE repo = ? AND pr = 0').get(repo) !== undefined;
+      const insert = db.prepare('INSERT OR IGNORE INTO hook_seen (repo, pr, head_sha, slug, at) VALUES (?, ?, ?, ?, ?)');
+      for (const e of entries) {
+        // Waiting for review is not a draft: a draft is left out, so it is news once it is marked ready
+        if (e.pull.draft) continue;
+        if (insert.run(repo, e.pull.number, e.sha, e.slug, at).changes !== 1 || !looked) continue;
+        emit('spec.ready', async () => ({
+          slug: e.slug, pull: e.pull.number, headSha: e.sha, proposalSha256: await hashOf(read, e), actor: e.pull.author,
+        }));
+      }
+      // The repo has been looked at: from now on, what is new is announced
+      if (!looked) insert.run(repo, 0, '', '', at);
+    })().catch((err) => console.error(`[cornfield] the spec PRs could not be checked for spec.ready: ${err instanceof Error ? err.message : err}`));
+  }
+
+  function close() {
+    closed = true;
+    for (const t of timers) timer.clearTimeout(t);
+    timers.clear();
+  }
+
+  return { emit, specsSeen, close };
+}
+
+/** The SHA-256 of a proposal file as `read` gives it, or null when it cannot be read (an event still goes out) */
+async function hashOf(read, entry) {
+  try {
+    return proposalHash(await read(entry));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The payload of an event about a proposal on a spec PR: the slug, the PR, its head and the file's hash. `extra` is who
+ * acted and, for a review, the note and edits.
+ * @param {import('./forge.js').Forge} forge
+ * @param {{ proposals: string }} where
+ * @param {{ slug: string, sha: string, path: string, pull: { number: number } }} entry
+ * @param {{ actor: string | null, note?: string, edits?: object[] }} extra
+ */
+export async function proposalPayload(forge, where, entry, extra) {
+  return { slug: entry.slug, pull: entry.pull.number, headSha: entry.sha, proposalSha256: await hashOf((e) => readPullProposal(forge, where, e), entry), ...extra };
+}
+
+/**
+ * The payload of `pr.landed`: the PR, the head that landed, and, when it is a spec PR, its proposal's slug and hash (the
+ * first when it holds several). A forge that cannot say leaves those null; the event still goes out.
+ * @param {import('./forge.js').Forge} forge
+ * @param {{ proposals: string }} where
+ * @param {number} n the landed pull request
+ * @param {string} sha the head that landed
+ * @param {string} actor
+ */
+export async function landedPayload(forge, where, n, sha, actor) {
+  let entry = null;
+  try {
+    entry = (await pullProposals(forge, where, await forge.pull(n)))[0] ?? null;
+  } catch { /* not known: a plain pull request */ }
+  if (!entry) return { slug: null, pull: n, headSha: sha, proposalSha256: null, actor };
+  return { ...(await proposalPayload(forge, where, entry, { actor })), pull: n, headSha: sha };
+}

package/server/pipeline.js

@@ -35,6 +35,7 @@ import { ForgeError, MAX_BODY, MAX_TITLE, isMaintainer } from './forge.js';
 import { PROPOSAL_FILE } from './files.js';
 import { findPullProposal, folderOf, readPullProposal } from './proposal-pulls.js';
 import { latestReview, proposalHash } from './reviews.js';
+import { defuse } from './defuse.js';
 import { applyEdits, slug as slugOf, validateProposal } from '../core/proposal.js';
 
 /** The longest slug of a proposal's name made from an issue's title, before its number */
@@ -62,16 +63,8 @@ export function plain(value, max = 200) {
   return defuse(clip(one, max)).replace(/[&<>\\`*_[\]|~!]/g, (c) => `&#${c.charCodeAt(0)};`);
 }
 
-/** A zero-width space: it ends a mention or a reference without showing */
-const ZW = '\u200B';
-
-/**
- * Text with every mention and reference broken: `@user`, `@org/team`, `#1`, `owner/repo#1`, `GH-1`, and links the forge
- * would make of `https://…` or `www.…`. A zero-width space after the character keeps the text as it reads.
- */
-export function defuse(text) {
-  return String(text).replace(/[@#]/g, (c) => `${c}${ZW}`).replace(/\b(GH)-(?=\d)/gi, `$1${ZW}-`).replace(/:\/\//g, `:${ZW}//`).replace(/\b(www)\./gi, `$1${ZW}.`);
-}
+// Mentions and references are broken by server/defuse.js, which reviews share; re-exported for the callers that had it here
+export { defuse } from './defuse.js';
 
 /** Untrusted text as a code span: no backtick or control character can end it */
 export function code(value, max = 100) {

package/server/proposal-pulls.js

@@ -79,11 +79,14 @@ function entryOf(pull, file) {
 /**
  * The proposals of every open PR that touches the proposals folder, newest PR first. A forge that cannot answer
  * gives `problem` in words, with what was found before it; the caller shows both.
+ * With `hooks` (server/hooks.js), the spec PRs found are handed over to announce the new ones (`spec.ready`); that runs
+ * in the background and changes nothing about the answer.
  * @param {import('./forge.js').Forge} forge
  * @param {{ proposals: string }} where
+ * @param {{ hooks?: { specsSeen: Function } | null }} [opts]
  * @returns {Promise<{ entries: PullEntry[], problem: string | null }>}
  */
-export async function listPullProposals(forge, where) {
+export async function listPullProposals(forge, where, { hooks = null } = {}) {
   const folder = folderOf(where);
   let pulls;
   try {
@@ -105,7 +108,23 @@ export async function listPullProposals(forge, where) {
     }
   };
   await Promise.all(Array.from({ length: Math.min(PARALLEL, pulls.length) }, worker));
-  return { entries: found.flat(), problem };
+  const entries = found.flat();
+  if (hooks) {
+    try { hooks.specsSeen(forge.repo, entries, (entry) => readPullProposal(forge, where, entry)); } catch { /* a hook never gets in the way */ }
+  }
+  return { entries, problem };
+}
+
+/**
+ * The proposals a pull request holds (open or not), read at its head.
+ * @param {import('./forge.js').Forge} forge
+ * @param {{ proposals: string }} where
+ * @param {{ number: number, title: string, url: string, draft: boolean, author: { login: string } | null, head: { sha: string } }} pull
+ * @returns {Promise<PullEntry[]>}
+ */
+export async function pullProposals(forge, where, pull) {
+  const folder = folderOf(where);
+  return (await filesAt(forge, where, pull)).filter((f) => isProposal(f, folder)).map((f) => entryOf(pull, f));
 }
 
 /**

package/server/proposals.js

@@ -19,8 +19,9 @@
  * holds it when the maintainer approves (`hashPullMockups`); every approval also carries `proposal`, the SHA-256 of the
  * proposal file at the head (`proposalHash`). The page never sends either, and a PUT that does is refused. The agent drafting the spec
  * reads it (`cornfield review <slug>`) and folds the edits into the proposal. The PUT is same-origin only
- * (`sameOrigin`), at most `REVIEW_LIMIT` bytes, checked by `validateReview`, and only for a proposal the forge
- * says the PR holds; it is written to the `actions` audit table. A proposal in the checkout or a worktree has no
+ * (`sameOrigin`), at most `REVIEW_LIMIT` bytes, and goes through `submitReview` (server/submit-review.js), the one path the review
+ * API shares: the review is checked, the maintainer asked of the forge now, and only a proposal the forge says the PR
+ * holds is reviewed; every attempt is written to the `actions` audit table. A proposal in the checkout or a worktree has no
  * PR yet, so there is nothing to review it on: the PUT answers 409 and says to push it as a spec PR. Stage 1 kept
  * the review in the data folder; `migrateStage1Reviews` carries those over once, when the menu is opened.
  *
@@ -43,9 +44,10 @@ import path from 'node:path';
 import { findProposalFile, listProposalFiles } from './files.js';
 import { summarize, proposalProblems } from '../core/proposal.js';
 import { ForgeError } from './forge.js';
-import { REVIEW_LIMIT, validateReview, latestReview, postReview, migrateStage1Reviews, proposalHash } from './reviews.js';
+import { REVIEW_LIMIT, latestReview, migrateStage1Reviews } from './reviews.js';
+import { submitReview, refusal } from './submit-review.js';
 import { findPullProposal, forgeWords, listPullProposals, pullNumber, readPullProposal } from './proposal-pulls.js';
-import { hashPullMockups, serveMockups } from './mockups.js';
+import { serveMockups } from './mockups.js';
 
 // The review's checks live in server/reviews.js; these are re-exported for the callers that always had them here
 export { REVIEW_LIMIT, MAX_REVIEW_EDITS, MAX_NOTE_CHARS, validateReview } from './reviews.js';
@@ -195,7 +197,7 @@ async function listWithPulls(where, forgeFor, signedIn) {
   } catch (err) {
     return { list: local, problem: forgeWords(err) };
   }
-  const { entries, problem } = await listPullProposals(forge, where);
+  const { entries, problem } = await listPullProposals(forge, where, { hooks: signedIn?.hooks });
   if (signedIn && entries.length) await migrateStage1Reviews({ forge, dataDir: where.dataDir, entries, login: signedIn.login, record: signedIn.record });
   const pulls = await Promise.all(entries.map((entry) => describePull(entry, forge, where, topology)));
   const list = [...local, ...pulls].sort((a, b) => (a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0));
@@ -260,26 +262,19 @@ async function putPullReview(req, res, where, forgeFor, signedIn, slug, n) {
   }
   // What an approval covers is the server's to record, from the files themselves, never the page's word
   if (parsed !== null && typeof parsed === 'object' && ('mockups' in parsed || 'proposal' in parsed)) return send(res, 400, { error: 'What an approval covers (the proposal and its mockups) is recorded by the server; a review does not send it.' });
-  const checked = validateReview(parsed);
-  if (!checked.ok) return send(res, 400, { error: checked.error });
   try {
-    const forge = forgeFor();
-    const entry = await findPullProposal(forge, where, slug, n);
-    if (!entry) return send(res, 404, { error: 'No such proposal' });
-    let review = checked.value;
-    if (review.verdict === 'approved') {
-      // The proposal as the head holds it now: a later push that changes it is not this approval's
-      review = { ...review, proposal: proposalHash(await readPullProposal(forge, where, entry)) };
-      const mockups = await hashPullMockups(forge, where, entry);
-      if (mockups.length) review = { ...review, mockups };
-    }
-    return send(res, 200, await postReview(forge, n, slug, review, { login: signedIn.login, record: signedIn.record }));
+    // The checks and the post are submitReview's, shared with the review API (server/submit-review.js)
+    const found = await submitReview({
+      forge: forgeFor, where, repo: signedIn.repo, who: { login: signedIn.login, userId: signedIn.userId }, record: signedIn.record, limits: signedIn.limits, hooks: signedIn.hooks,
+    }, { pull: n, slug, review: parsed });
+    return send(res, 200, found);
   } catch (err) {
-    return send(res, forgeStatus(err), { error: forgeWords(err) });
+    const out = refusal(err);
+    return send(res, out.status, { error: out.body.error }, out.headers);
   }
 }
 
-/** @typedef {{ login: string, record: (entry: import('./reviews.js').AuditEntry) => Promise<void> | void }} SignedIn */
+/** @typedef {{ login: string, userId: string, repo: string, record: (entry: import('./reviews.js').AuditEntry) => Promise<void> | void, limits: { auth: object, now?: () => number }, hooks?: import('./hooks.js').Hooks | null }} SignedIn who is signed in, the repo, where their actions are recorded, and what the flood and repeat limits count by */
 
 /**
  * Answers a request under `/proposals`, or returns false when it is not one.