@popcorn245/cornfield 0.1.2 → 0.2.0

package/core/config.js

@@ -22,6 +22,7 @@
  *     topology: 'topology.json',
  *     personas: { roles: null },              // the roles a persona may have (null: any)
  *     releaseNotes: { breakingLabel: 'breaking' },   // the pull request label that lists a change under "Breaking" in the release notes
+ *     hooks: [],                              // [{ url, events }]: signed JSON events posted to outside code (docs/config.md#hooks); the secret is env only
  *     links: [],                              // [{ label, href }] shown in the explorer's header
  *     proxy: {},                              // { '/api/': 'http://127.0.0.1:3245' }: same-origin paths for a live source
  *     importMap: {},                          // bare imports a repo-local browser module needs: { name: '/repo/path.js' }
@@ -63,6 +64,10 @@ export const SOURCE_SLOTS = ['live', 'house', 'devices', 'checker'];
 export const FORGE_TYPES = ['github', 'forgejo'];
 /** How a pull request cornfield lands is merged (`forge.mergeMethod`): the way the repo lands its pull requests */
 export const MERGE_METHODS = ['merge', 'squash', 'rebase'];
+/** The events a hook may ask for (`hooks[].events`), and what each one means: docs/config.md#hooks */
+export const HOOK_EVENTS = Object.freeze(['spec.ready', 'spec.approved', 'spec.sentBack', 'build.opened', 'pr.landed']);
+/** The most hooks a config lists */
+export const MAX_HOOKS = 20;
 
 export const DEFAULTS = Object.freeze({
   title: null,
@@ -80,6 +85,7 @@ export const DEFAULTS = Object.freeze({
   cloud: { parent: 'root' },
   releaseNotes: { breakingLabel: 'breaking' },
   agents: { authors: [], labels: [], branchPrefixes: [], bots: true },
+  hooks: [],
   links: [],
   proxy: {},
   importMap: {},
@@ -173,6 +179,24 @@ export function configProblems(c) {
       }
     }
   }
+  if (c.hooks !== undefined) {
+    if (!Array.isArray(c.hooks)) out.push('"hooks" is a list of { url, events }.');
+    else {
+      if (c.hooks.length > MAX_HOOKS) out.push(`"hooks" lists at most ${MAX_HOOKS} hooks.`);
+      c.hooks.forEach((h, i) => {
+        if (!isObject(h)) { out.push(`hooks[${i}] is { url, events }.`); return; }
+        for (const k of Object.keys(h)) if (k !== 'url' && k !== 'events') out.push(`hooks[${i}].${k}: the keys are url, events (the secret is CORNFIELD_HOOK_SECRET in env, never the config).`);
+        const bad = hookUrlProblem(h.url);
+        if (bad) out.push(`hooks[${i}].url ${bad}`);
+        if (h.events === '*') return;
+        if (!Array.isArray(h.events) || h.events.length === 0) out.push(`hooks[${i}].events is "*" or a non-empty list of ${HOOK_EVENTS.join(', ')}.`);
+        else {
+          for (const e of h.events) if (!HOOK_EVENTS.includes(e)) out.push(`hooks[${i}].events: ${JSON.stringify(e)} is not an event; the events are ${HOOK_EVENTS.join(', ')}.`);
+          if (new Set(h.events).size !== h.events.length) out.push(`hooks[${i}].events names an event twice.`);
+        }
+      });
+    }
+  }
   if (c.releaseNotes !== undefined) {
     if (!isObject(c.releaseNotes)) out.push('"releaseNotes" is { breakingLabel }.');
     else if (c.releaseNotes.breakingLabel !== undefined && (!isText(c.releaseNotes.breakingLabel) || c.releaseNotes.breakingLabel.includes(','))) out.push('releaseNotes.breakingLabel is a label\'s name, like "breaking".');
@@ -203,6 +227,26 @@ export function configProblems(c) {
   return out;
 }
 
+/** Whether a host is the machine itself: `localhost`, 127.x.x.x or ::1 */
+const isLoopbackHost = (host) => host === 'localhost' || host === '[::1]' || /^127(?:\.\d{1,3}){3}$/.test(host);
+
+/** What is wrong with a hook's URL, in words that follow "hooks[i].url", or null: https, or http for the machine itself; no login in it */
+function hookUrlProblem(value) {
+  const say = 'is an https URL, like https://chat.example.org/hooks/cornfield.';
+  if (typeof value !== 'string') return say;
+  let u;
+  try {
+    u = new URL(value);
+  } catch {
+    return say;
+  }
+  if (u.protocol === 'http:' && !isLoopbackHost(u.hostname)) return 'is https; http is only for localhost, 127.0.0.1 and [::1].';
+  if (u.protocol !== 'https:' && u.protocol !== 'http:') return 'is an https URL.';
+  if (u.username || u.password) return 'has a user name or password in it; a hook is signed with CORNFIELD_HOOK_SECRET instead.';
+  if (u.hash) return 'has a # fragment, which is never sent.';
+  return null;
+}
+
 /** A short, file-safe name for a repo root, for the default data folder */
 function slugOf(root) {
   return path.basename(root).toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'repo';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popcorn245/cornfield",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "A self-hostable dev dashboard with the topology map at its centre: proposals on the map, scenarios, outages and what-if edits, for any repo.",
   "license": "MIT",
   "author": "popcorn245 (https://github.com/popcorn245)",

package/server/db.js

@@ -8,6 +8,8 @@
  *   reviews       a cache of the latest review per spec PR and proposal (the PR comment is the truth)
  *   actions       the audit of every action cornfield takes on the forge: who, what, when, the forge's answer
  *   forge_cache   forge answers kept for a while (an ETag and a body), so a page load is not a dozen API calls
+ *   hook_seen     the (pull request, head, proposal) triples whose `spec.ready` event was sent, so a restart sends none twice;
+ *                 a row with `pr = 0` says the repo has been looked at once (server/hooks.js)
  *
  * The schema is a list of numbered migrations (`MIGRATIONS`); the file's `PRAGMA user_version` is the number of
  * the last one it has. `openStore` runs the ones a file lacks, each in its own transaction, so a fresh file and one
@@ -81,6 +83,17 @@ export const MIGRATIONS = Object.freeze([
   ) STRICT;
   CREATE INDEX forge_cache_expires_at ON forge_cache (expires_at);
   `,
+  // 2: event hooks (server/hooks.js): which spec PR heads have been announced
+  `
+  CREATE TABLE hook_seen (
+    repo        TEXT NOT NULL,                  -- 'owner/name'
+    pr          INTEGER NOT NULL,
+    head_sha    TEXT NOT NULL,                  -- the PR's head when cornfield first saw it
+    slug        TEXT NOT NULL,                  -- the proposal file's slug
+    at          TEXT NOT NULL,
+    PRIMARY KEY (repo, pr, head_sha, slug)
+  ) STRICT;
+  `,
 ]);
 
 /** The version a file is at: its `user_version` */

package/server/forge-actions.js

@@ -45,6 +45,7 @@ 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 { 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;
@@ -181,7 +182,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 +276,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/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

@@ -44,6 +44,7 @@ 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 { proposalPayload } from './hooks.js';
 import { findPullProposal, forgeWords, listPullProposals, pullNumber, readPullProposal } from './proposal-pulls.js';
 import { hashPullMockups, serveMockups } from './mockups.js';
 
@@ -195,7 +196,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));
@@ -273,13 +274,15 @@ async function putPullReview(req, res, where, forgeFor, signedIn, slug, n) {
       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 }));
+    const posted = await postReview(forge, n, slug, review, { login: signedIn.login, record: signedIn.record });
+    signedIn.hooks?.emit(review.verdict === 'approved' ? 'spec.approved' : 'spec.sentBack', () => proposalPayload(forge, where, entry, { actor: signedIn.login, note: review.note, edits: review.edits }));
+    return send(res, 200, posted);
   } catch (err) {
     return send(res, forgeStatus(err), { error: forgeWords(err) });
   }
 }
 
-/** @typedef {{ login: string, record: (entry: import('./reviews.js').AuditEntry) => Promise<void> | void }} SignedIn */
+/** @typedef {{ login: string, record: (entry: import('./reviews.js').AuditEntry) => Promise<void> | void, hooks?: import('./hooks.js').Hooks | null }} SignedIn */
 
 /**
  * Answers a request under `/proposals`, or returns false when it is not one.

package/server/server.js

@@ -48,6 +48,7 @@ import { proxyTo } from './proxy.js';
 import { HA_ENV, homeAssistantHouse } from '../plugins/house/home-assistant.js';
 import { assertBind, hostAllowed } from './bind.js';
 import { createAuth, signInSettings } from './auth.js';
+import { createHooks, hooksSettings } from './hooks.js';
 
 export const CORNFIELD_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const EXPLORER_DIR = path.join(CORNFIELD_DIR, 'explorer');
@@ -120,14 +121,20 @@ export const HA_CACHE_MS = 30_000;
 /**
  * The server for one repo. It does not listen: `listen(config)` does, where server/bind.js allows.
  * @param {object} config a loaded config (core/config.js `loadConfig`)
- * @param {Parameters<typeof createAuth>[1] & { homeAssistant?: object }} [opts] what sign-in reads (`env`, and tests' fakes;
+ * @param {Parameters<typeof createAuth>[1] & { homeAssistant?: object, hookFetch?: typeof fetch, hookTimer?: { setTimeout: Function, clearTimeout: Function } }} [opts] what sign-in reads (`env`, and tests' fakes;
  *   see server/auth.js); the Home Assistant URL and token are read from the same `env`, and `homeAssistant` is what
- *   `homeAssistantHouse` is handed besides them (the tests' fake WebSocket)
+ *   `homeAssistantHouse` is handed besides them (the tests' fake WebSocket); `hookFetch` and `hookTimer` are the
+ *   tests' fake network and clock for the event hooks (server/hooks.js)
  * @returns {import('node:http').Server}
  */
 export function createCornfieldServer(config, opts = {}) {
   const { env = process.env, homeAssistant = {} } = opts;
   const auth = createAuth(config, opts);
+  // Hooks listed without a secret (or without sign-in) are a startup error, like a half-configured sign-in
+  const hookSettings = hooksSettings(config, env, auth.enabled);
+  const hooks = hookSettings
+    ? createHooks({ hooks: config.hooks, secret: hookSettings.secret, fetch: opts.hookFetch, record: (entry) => auth.record(entry), store: auth.store, now: opts.now, publicUrl: config.publicUrl, timer: opts.hookTimer })
+    : null;
   const root = config.root;
   const importMap = importMapOf(config);
   const csp = cspOf(importMap);
@@ -172,7 +179,7 @@ export function createCornfieldServer(config, opts = {}) {
       else res.end();
     }
   });
-  server.on('close', () => auth.close());
+  server.on('close', () => { hooks?.close(); auth.close(); });
   return server;
 
   async function answer(req, res) {
@@ -212,11 +219,11 @@ export function createCornfieldServer(config, opts = {}) {
     const signedIn = gate.session ? { login: gate.session.login } : false;
 
     // Before the proxies: a repo's `/api/` proxy must not swallow the panel's own routes
-    if (await serveForge(req, res, reqPath, url, { config, where, session: gate.session, auth, now: opts.now, publicHost })) return;
+    if (await serveForge(req, res, reqPath, url, { config, where, session: gate.session, auth, hooks, now: opts.now, publicHost })) return;
     for (const [prefix, target] of proxies) if (reqPath.startsWith(prefix)) return proxyTo(req, res, target);
     const session = gate.session;
     const forgeFor = session ? () => auth.forgeFor(session) : null;
-    if (serveProposals(req, res, reqPath, url, where, forgeFor, session ? { login: session.login, record: (entry) => auth.record(entry) } : null)) return;
+    if (serveProposals(req, res, reqPath, url, where, forgeFor, session ? { login: session.login, record: (entry) => auth.record(entry), hooks } : null)) return;
 
     if (req.method !== 'GET' && req.method !== 'HEAD') {
       req.resume();