@popcorn245/cornfield 0.3.0 → 0.4.0

package/core/config.js

@@ -18,7 +18,7 @@
  *     host: '127.0.0.1',                      // loopback, unless sign-in is configured with an https publicUrl (server/bind.js)
  *     publicUrl: null,                        // the origin people open it at; sign-in needs it (server/auth.js)
  *     worktrees: '.claude/worktrees',         // a folder of git worktrees whose unpushed proposals are listed too
- *     proposals: 'docs/specs/proposals',      // where proposal files live, in the checkout and in each worktree
+ *     proposals: 'docs/specs/proposals',      // where proposal files live, in the checkout and in each worktree; or { dir, approveLands } (docs/config.md#proposals)
  *     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
@@ -93,6 +93,8 @@ export const DEFAULTS = Object.freeze({
 });
 
 const KEYS = Object.keys(DEFAULTS);
+/** The keys of `proposals` when it is an object: the folder, and whether an approval also lands the spec PR (opt-in, off unless true) */
+export const PROPOSALS_KEYS = Object.freeze(['dir', 'approveLands']);
 const AGENT_KEYS = ['authors', 'labels', 'branchPrefixes', 'bots'];
 const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
 const isText = (v) => typeof v === 'string' && v.trim() !== '';
@@ -201,9 +203,17 @@ export function configProblems(c) {
     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".');
   }
-  for (const key of ['worktrees', 'proposals', 'topology']) {
+  for (const key of ['worktrees', 'topology']) {
     if (c[key] !== undefined && c[key] !== null && !inRepo(c[key])) out.push(`"${key}" is a folder or file inside the repo, written relative to it.`);
   }
+  // The folder as a string (always so), or { dir?, approveLands? }: the object form is how the folder's options are set
+  if (c.proposals !== undefined && c.proposals !== null) {
+    if (isObject(c.proposals)) {
+      for (const k of Object.keys(c.proposals)) if (!PROPOSALS_KEYS.includes(k)) out.push(`proposals.${k}: the keys are ${PROPOSALS_KEYS.join(', ')}.`);
+      if (c.proposals.dir !== undefined && !inRepo(c.proposals.dir)) out.push('proposals.dir is the proposals folder, inside the repo and written relative to it.');
+      if (c.proposals.approveLands !== undefined && typeof c.proposals.approveLands !== 'boolean') out.push('proposals.approveLands is true or false: whether approving a spec also lands its pull request once every check is green.');
+    } else if (!inRepo(c.proposals)) out.push('"proposals" is the proposals folder inside the repo, written relative to it (or { dir, approveLands }).');
+  }
   if (c.links !== undefined) {
     if (!Array.isArray(c.links)) out.push('"links" is a list of { label, href }.');
     else c.links.forEach((l, i) => {
@@ -280,6 +290,9 @@ export async function loadConfig(root, { env = process.env, file } = {}) {
     deploys: { ...DEFAULTS.deploys, ...(raw.deploys || {}) },
     agents: { ...DEFAULTS.agents, ...(raw.agents || {}) },
   };
+  // `proposals` is the folder to everything downstream, whichever way the file wrote it; the options are read from `approveLands`
+  config.approveLands = isObject(raw.proposals) && raw.proposals.approveLands === true;
+  config.proposals = (isObject(raw.proposals) ? raw.proposals.dir : raw.proposals) ?? DEFAULTS.proposals;
   if (env.CORNFIELD_PORT) config.port = Number(env.CORNFIELD_PORT);
   if (env.PORT && !env.CORNFIELD_PORT) config.port = Number(env.PORT);
   if (env.CORNFIELD_HOST) config.host = env.CORNFIELD_HOST;

package/explorer/forge-panel-model.js

@@ -22,6 +22,8 @@
  *   specBlock, buildOffers    the pipeline's steps (PIPE-05): why a spec cannot be started on an issue; which proposals of a spec pull request can have a build issue
  *   planUrl, confirmSpec, confirmBuild, specBody, buildBody, existingWords
  *                             where a step's plan is read, what the confirm step shows of it, what is sent to confirm it, and what is said of one that is made already
+ *   landingUrl, cancelLandingUrl, landingWords
+ *                             a spec pull request waiting to land on its approval (`proposals.approveLands`, server/lander.js): where it is read, where it is cancelled, and the words
  *   notesUrl, sinceChoices, notesSummary, validTag, confirmWords, postedWords, draftRequest
  *                             the Release notes view: what to ask, the tags to start from, and the words around a draft
  */
@@ -54,6 +56,21 @@ export const listKeyOf = (kind, state) => (kind === 'deploys' ? 'deploys' : `${k
 /** The address of one pull request with its files and checks */
 export const pullUrl = (n) => `/api/forge/pulls/${n}`;
 
+/** Where a pull request's landing on approval is read (GET) and cancelled (POST) */
+export const landingUrl = (n) => `/api/forge/pulls/${n}/landing`;
+export const cancelLandingUrl = (n) => `/api/forge/pulls/${n}/landing/cancel`;
+
+/**
+ * The line for a pull request waiting to land on its approval: "Will land when checks pass".
+ * @param {{ slug: string, by: string, since: string } | null} landing what the server says is waiting
+ * @param {number} nowMs
+ * @returns {string} empty when nothing is waiting
+ */
+export function landingWords(landing, nowMs) {
+  if (!landing) return '';
+  return `Will land when checks pass. ${landing.slug} was approved by ${landing.by} ${relativeTime(landing.since, nowMs)}; it lands at that head only, and a push cancels it.`;
+}
+
 /** Whether a list's item passes the filters (the state of a pull request is decided here: open, merged, closed without landing) */
 export function matches(item, kind, filters) {
   const f = { ...defaultFilters(), ...filters };

package/explorer/forge-panel.js

@@ -29,6 +29,9 @@
  *     it goes, how, each check); a scrim covers the page, the dialog is `aria-modal`, Tab stays inside, Escape and Cancel close it and give the
  *     focus back, and it is announced. What is sent is the head that was shown: a push since is refused by the server,
  *     which checks everything again (server/forge-actions.js). While one is in flight the buttons are off.
+ *   - With `proposals.approveLands` on, a spec pull request that was approved and is waiting for its checks says **Will land when
+ *     checks pass** (read from `GET /api/forge/pulls/<n>/landing`, the server's own state) with a **Cancel** that POSTs to
+ *     `…/landing/cancel` (server/lander.js). With the key off the panel asks nothing and shows nothing more.
  *   - The pipeline's own steps (PIPE-05, server/pipeline.js), each one button with a confirm step that shows exactly what
  *     will be made, read from the server first (the plan, with a digest the server must find again):
  *       1. an open issue in the Issues list has **Start a spec …**: a branch, a stub proposal and a draft spec pull request;
@@ -56,7 +59,7 @@ import { LAYER_DEFS, toggleLayer } from './layers.js';
 import { WORK_URL, groupWork, filterGroups, groupWords, workStatus, markWords } from './agents-model.js';
 import {
   STATES, defaultFilters, listUrl, pullUrl, serverState, filterItems, facetsOf, stateWords, metaWords, checkWords, checksWords, litFor, errorWords,
-  mergeBlock, rerunWhy, confirmMerge, mergeBody, actionUrl, actionWords,
+  landingUrl, cancelLandingUrl, landingWords, mergeBlock, rerunWhy, confirmMerge, mergeBody, actionUrl, actionWords,
   specBlock, buildOffers, planUrl, confirmSpec, confirmBuild, specBody, buildBody, existingWords,
   listKeyOf, litForDeploy, nodesForRestarts, deployWords, deployMeta,
   DRAFTS_URL, notesUrl, sinceChoices, notesSummary, validTag, confirmWords, postedWords, draftRequest,
@@ -79,6 +82,7 @@ const ui = {
   error: '',
   selected: null, // the pull request's number
   detail: null, // { pull, files, checks, at, rate, stale } of the selected one
+  landing: null, // what waits to land on its approval for the selected pull request ({ slug, by, since }), or null
   detailError: '',
   lit: null, // litFor(detail, nodes)
   deploy: null, // the selected deploy's id; the deploy itself is `deployItem`
@@ -181,6 +185,7 @@ async function selectPull(n) {
   ui.litDeploy = null;
   ui.selected = n;
   ui.detail = null;
+  ui.landing = null;
   ui.detailError = '';
   ui.lit = null;
   ui.note = null;
@@ -198,10 +203,35 @@ async function selectPull(n) {
   }
   ui.detail = { pull: res.body.pull, files: res.body.files || [], checks: res.body.checks || [], specs: res.body.specs || [], at: res.body.at, rate: res.body.rate || '', stale: res.body.stale || '' };
   relight();
+  await loadLanding(n, token);
   $('forge-panel').querySelector('.hx-forge-body').scrollTop = 0; // the pull request's files are what was asked for, not the row that was tapped
   announce(selectionWords());
 }
 
+/** Asks the server whether the selected pull request waits to land on its approval (a read of the server's own state, not of the forge); nothing is shown when it does not */
+async function loadLanding(n, token) {
+  if (!(ui.config && ui.config.forge && ui.config.forge.approveLands)) return; // the key is off: nothing to ask
+  const res = await request(landingUrl(n), true);
+  if (token !== pullToken || ui.selected !== n) return;
+  ui.landing = res.ok && res.body && res.body.landing ? res.body.landing : null;
+  paint();
+}
+
+/** Stops the landing that waits on the selected pull request: a POST from this page, then the pull request is read again */
+async function cancelLanding(n) {
+  if (ui.busy) return;
+  ui.busy = 'landing';
+  ui.note = null;
+  paint();
+  const res = await post(cancelLandingUrl(n), {});
+  ui.busy = '';
+  ui.note = { text: res.ok ? `Pull request #${n} will not land on its own. It stays open.` : `Not cancelled: ${(res.body && res.body.error) || 'cornfield did not answer.'}`, ok: res.ok };
+  announce(ui.note.text);
+  ui.landing = null;
+  paint();
+  if (ui.selected === n) await refreshForge({ quiet: true });
+}
+
 /** Lets go of the selected pull request: nothing is lit any more */
 export function clearPull() {
   pullToken++;
@@ -210,6 +240,7 @@ export function clearPull() {
   ui.selected = null;
   ui.note = null;
   ui.detail = null;
+  ui.landing = null;
   ui.detailError = '';
   ui.lit = null;
   state.forgeLit = null;
@@ -570,6 +601,10 @@ function detailHtml() {
   const act = block
     ? `<p class="hx-forge-why hx-faint">${pull.state === 'merged' ? '' : 'Cannot be landed from here. '}${escHtml(block)}</p>`
     : `<button type="button" class="hx-btn hx-btn--approve hx-forge-act" data-forge-merge="${pull.number}"${ui.busy ? ' disabled' : ''}>Land it …</button><p class="hx-forge-why hx-faint">Opens a confirm step that shows what will land. Never forced, never deployed.</p>`;
+  // A spec approved with `proposals.approveLands` waits for its checks: said here, with a way to stop it
+  const waiting = ui.landing && pull.state === 'open'
+    ? `<div class="hx-forge-step"><p class="hx-forge-notice hx-forge-notice--ok" role="status">${escHtml(landingWords(ui.landing, now()))}</p><button type="button" class="hx-btn hx-forge-act" data-forge-landing-cancel="${pull.number}"${ui.busy ? ' disabled' : ''}>Cancel</button></div>`
+    : '';
   const note = ui.note ? `<p class="hx-forge-notice${ui.note.ok ? ' hx-forge-notice--ok' : ''}">${escHtml(ui.note.text)}</p>` : '';
   // Step 2 of the pipeline: a spec pull request with an approved proposal opens its build issue
   const offers = buildOffers(ui.detail);
@@ -589,6 +624,7 @@ function detailHtml() {
     ${build}
     <h4 class="hx-forge-subact">Land it</h4>
     ${note}
+    ${waiting}
     ${act}
     <h4 class="hx-forge-sub">${escHtml(plural(lit.files.length, 'file'))} changed, ${mapped} on the map</h4>
     ${key}
@@ -951,6 +987,7 @@ export async function refreshForge({ quiet = false } = {}) {
     if (token !== pullToken || !res.ok) return;
     ui.detail = { pull: res.body.pull, files: res.body.files || [], checks: res.body.checks || [], specs: res.body.specs || [], at: res.body.at, rate: res.body.rate || '', stale: res.body.stale || '' };
     relight();
+    await loadLanding(n, token);
   }
 }
 
@@ -1005,6 +1042,8 @@ function onClick(e) {
     announce(`${node.label}, ${node.type}`);
     return;
   }
+  const unland = t.closest('[data-forge-landing-cancel]');
+  if (unland) { cancelLanding(Number(unland.dataset.forgeLandingCancel)); return; }
   const merge = t.closest('[data-forge-merge]');
   if (merge) { openConfirm('[data-forge-merge]'); return; }
   const spec = t.closest('[data-forge-spec]');
@@ -1119,5 +1158,5 @@ export function resetForgePanelForTests(clock = () => Date.now()) {
   pullToken++;
   notesToken++;
   state.forgeLit = null;
-  Object.assign(ui, { config: null, open: false, kind: 'pulls', filters: defaultFilters(), lists: {}, work: null, workFilters: { agentsOnly: false, finished: false }, loading: false, error: '', selected: null, detail: null, detailError: '', lit: null, deploy: null, deployItem: null, litDeploy: null, nodesSeen: null, busy: '', note: null, confirm: null, actNote: null, notes: freshNotes() });
+  Object.assign(ui, { config: null, open: false, kind: 'pulls', filters: defaultFilters(), lists: {}, work: null, workFilters: { agentsOnly: false, finished: false }, loading: false, error: '', selected: null, detail: null, landing: null, detailError: '', lit: null, deploy: null, deployItem: null, litDeploy: null, nodesSeen: null, busy: '', note: null, confirm: null, actNote: null, notes: freshNotes() });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popcorn245/cornfield",
-  "version": "0.3.0",
+  "version": "0.4.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

@@ -11,6 +11,7 @@
  *   review_tokens the review API's tokens: a SHA-256 hash, owner, label, expiry, revoked, last used (never the token)
  *   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)
+ *   landings      the spec PRs an approval is waiting to land (`proposals.approveLands`), so a restart picks them up (server/lander.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
@@ -110,6 +111,20 @@ export const MIGRATIONS = Object.freeze([
   ) STRICT;
   CREATE INDEX review_tokens_user_id ON review_tokens (user_id);
   `,
+  // 4: landing on approval (server/lander.js): a spec PR waiting for its checks, to be landed as the approver
+  `
+  CREATE TABLE landings (
+    repo        TEXT NOT NULL,                  -- 'owner/name'
+    pull        INTEGER NOT NULL,
+    slug        TEXT NOT NULL,                  -- the proposal that was approved
+    sha         TEXT NOT NULL,                  -- the head that was approved: the only one that may land
+    user_id     TEXT NOT NULL,                  -- the approver, by the forge's id: it lands as them, with their own sign-in
+    login       TEXT NOT NULL,                  -- their login when they approved (for the audit)
+    started     TEXT NOT NULL,
+    state       TEXT NOT NULL CHECK (state IN ('pending', 'landed', 'cancelled', 'left-open', 'done')),
+    PRIMARY KEY (repo, pull)
+  ) STRICT;
+  `,
 ]);
 
 /** The version a file is at: its `user_version` */

package/server/forge-actions.js

@@ -113,6 +113,27 @@ async function forgetKept(auth, config) {
   } catch { /* a cache that cannot be cleared expires in a minute */ }
 }
 
+/** How a pull request cornfield lands is merged: the config's `forge.mergeMethod`, `merge` when unset */
+export const mergeMethodOf = (config) => config.forge.mergeMethod || 'merge';
+
+/**
+ * Lands pull request `n` at head `sha`, the one way cornfield lands anything: `forge.merge` with `onlyIfGreen` and the
+ * sha (the forge adapter checks open, not a draft, still at `sha`, every check green and its own readiness), then the
+ * `pr.landed` hook, then the kept forge answers are let go. Land it (above) and landing on approval (server/lander.js)
+ * both call this, so the two cannot differ. Throws what `forge.merge` throws.
+ * @param {{ forge: import('./forge.js').Forge, config: any, where?: { proposals: string }, hooks?: import('./hooks.js').Hooks | null, auth: { store: null | (() => Promise<import('node:sqlite').DatabaseSync>) } }} ctx
+ * @param {number} n
+ * @param {string} sha
+ * @param {string} login who landed it, for the hook
+ * @returns {Promise<{ sha: string }>}
+ */
+export async function landPull({ forge, config, where, hooks, auth }, n, sha, login) {
+  const landed = await forge.merge(n, { onlyIfGreen: true, sha, method: mergeMethodOf(config) });
+  hooks?.emit('pr.landed', () => landedPayload(forge, where || { proposals: config.proposals }, n, sha, login));
+  await forgetKept(auth, config);
+  return landed;
+}
+
 /**
  * The action the request is, or null for any other path.
  * @param {string} reqPath
@@ -229,11 +250,9 @@ export async function serveAction(req, res, what, ctx, send) {
       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';
+      const method = mergeMethodOf(config);
       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);
+      const landed = await landPull({ forge, config, where: ctx.where, hooks: ctx.hooks, auth }, n, /** @type {string} */ (sha), session.login);
       out = { status: 200, body: { ok: true, merged: true, number: n, sha: landed.sha, head: sha, method } };
     } else {
       const pull = await forge.pull(n);

package/server/forge-routes.js

@@ -15,6 +15,7 @@
  *                                                                      (each check says whether cornfield can re-run it: `canRerun`)
  *                                                                      (and `specs`: the proposals it changes and whether each is approved, for the pipeline's step 2)
  *   POST /api/forge/pulls/<n>/merge | /rerun                           land it, re-run a failed check (server/forge-actions.js)
+ *   GET  /api/forge/pulls/<n>/landing, POST …/landing/cancel           a landing waiting on an approval (`proposals.approveLands`), and stopping it (server/lander.js)
  *   GET  /api/forge/issues/<n>/spec                                    the plan of step 1: what starting a spec on the issue would make (server/pipeline.js), never kept
  *   GET  /api/forge/pulls/<n>/build?slug=<proposal>                    the plan of step 2: the build issue of an approved proposal, never kept
  *   POST /api/forge/issues/<n>/spec | /pulls/<n>/build                 do them, with the plan's digest (server/forge-actions.js)
@@ -47,6 +48,7 @@ import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { ForgeError, canRerun, hasAdapter, isMaintainer, isTagName, rateLimitWords } from './forge.js';
 import { actionOf, countAttempt, serveAction } from './forge-actions.js';
+import { landingOf, serveLanding } from './lander.js';
 import { planSpec, planBuild, pullSpecs } from './pipeline.js';
 import { listPullProposals } from './proposal-pulls.js';
 import { deploysOf } from './deploys.js';
@@ -220,13 +222,20 @@ 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 }, 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
+ * @param {{ config: object, where?: { proposals: string }, hooks?: import('./hooks.js').Hooks | null, lander?: import('./lander.js').Lander | 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>}
  */
 export async function serveForge(req, res, reqPath, url, ctx) {
   if (reqPath !== '/api/forge' && !reqPath.startsWith('/api/forge/')) return false;
   const { config, session, auth, now = Date.now } = ctx;
+  const landing = landingOf(reqPath);
+  if (landing) {
+    // What is waiting to land on its approval, and stopping it: nothing is asked of the forge to read, and it is never kept
+    const out = await serveLanding(req, landing, ctx);
+    send(req, res, out.status, out.body, out.headers);
+    return true;
+  }
   const act = actionOf(reqPath);
   if (act) {
     if (!config.forge || !hasAdapter(config.forge.type)) {

package/server/lander.js

@@ -0,0 +1,394 @@
+/**
+ * @module server/lander
+ *
+ * Landing on approval (PIPE-09, docs/proposals.md#land-on-approval): for a team that has set `proposals: { approveLands: true }`,
+ * approving a spec also lands its pull request, once it is mergeable and every check is green, with no second click. It is
+ * off unless the maintainer turned it on (ADR 0006), and with it off nothing here is built.
+ *
+ * `submitReview` (server/submit-review.js) calls `start` once, after an approval is posted, and never for a send-back. The
+ * review is already on the PR by then and its response does not wait for this. A landing is a row in `landings`
+ * (server/db.js) and a timer; on a restart `resume` picks up the rows still pending.
+ *
+ * **One polled path, for both forges.** Forgejo has a server-side "merge when checks succeed" and GitHub does not; using it
+ * would mean two code paths, and the pinned sha and the green rule would be the forge's to enforce rather than ours. So
+ * both are polled (every `POLL_MS` for the first `FAST_FOR_MS`, then every `SLOW_POLL_MS`, for up to `TIMEOUT_MS`; each
+ * look reads the PR, its head and its checks fresh from the forge, never a kept answer, since they decide the merge), and the
+ * landing is `landPull` (server/forge-actions.js): the same
+ * `forge.merge(n, { onlyIfGreen: true, sha })` Land it uses, with the same `pr.landed` hook.
+ *
+ * Each look stops at the first terminal state, in this order:
+ *
+ *   no sign-in left to land with      left open: sign in to land (nothing else is done; there is no token to comment with)
+ *   the PR is closed or merged        done (landed elsewhere, or closed: nothing to say)
+ *   its head is not the approved sha  cancelled, "a push after approval" (the approval covered another version)
+ *   a check is red                    left open: <check> failed
+ *   another proposal not approved     waits, saying nothing (a PR with several proposals lands only once every one of them
+ *                                     is approved by a maintainer at its current SHA-256, `allApproved`)
+ *   green, not a draft, mergeable     lands, pinned to the approved sha
+ *   the time is up                    left open: timed out
+ *
+ * and otherwise (checks still running, the forge still working out mergeability, a forge that did not answer) it waits.
+ *
+ * **As the approver.** It lands with the approver's own forge token, the newest live sign-in of that forge user
+ * (`auth.forgeForUser`, as the review API posts a review), asked who they are and whether they still maintain the repo just
+ * before it merges. Their session ending before the checks finish is "left open: sign in to land".
+ *
+ * **Says so.** A landing that is cancelled or left open (and one a maintainer cancels) posts one comment on the PR as the
+ * approver, through the review's comment call (`postNote`, server/reviews.js) with its mentions and references defused (server/defuse.js:
+ * a check's name is the forge's, not ours). Every state change is a row in `actions` (`action: 'landing'`; a landing itself is the
+ * `merge` row Land it writes, with `via: 'approval'`). A landing posts no comment: the merge is its own news.
+ */
+
+import { ForgeError, isGreen, isMaintainer } from './forge.js';
+import { landPull, mergeMethodOf } from './forge-actions.js';
+import { latestReview, postNote, proposalHash } from './reviews.js';
+import { pullProposals, readPullProposal } from './proposal-pulls.js';
+import { sameOrigin } from './proposals.js';
+import { Refused, countAttempt } from './throttle.js';
+
+/** How often a pending landing looks at its PR, for its first `FAST_FOR_MS` */
+export const POLL_MS = 20_000;
+/** How long a landing is looked at every `POLL_MS`; after that, every `SLOW_POLL_MS` (most checks finish in minutes) */
+export const FAST_FOR_MS = 5 * 60_000;
+export const SLOW_POLL_MS = 60_000;
+/** How long a landing waits for its checks before it is left open */
+export const TIMEOUT_MS = 60 * 60_000;
+/** The most of a check's name that goes into a comment */
+const NAME_MAX = 80;
+
+/** @typedef {'pending' | 'landed' | 'cancelled' | 'left-open' | 'done'} LandingState */
+/** @typedef {{ repo: string, pull: number, slug: string, sha: string, user_id: string, login: string, started: string, state: LandingState }} LandingRow */
+
+const iso = (ms) => new Date(ms).toISOString();
+const oneLine = (v, max) => String(v).replace(/\s+/g, ' ').trim().slice(0, max);
+
+/**
+ * @param {{
+ *   config: any,
+ *   where?: { proposals: string },
+ *   auth: { store: () => Promise<import('node:sqlite').DatabaseSync>, forgeForUser: (userId: string) => Promise<import('./forge.js').Forge>, record: Function },
+ *   hooks?: import('./hooks.js').Hooks | null,
+ *   now?: () => number,
+ *   timer?: { setTimeout: Function, clearTimeout: Function },
+ *   pollMs?: number,
+ *   timeoutMs?: number,
+ * }} opts `timer`, `pollMs` and `timeoutMs` are the tests' clock
+ */
+export function createLander({ config, where, auth, hooks = null, now = Date.now, timer = { setTimeout, clearTimeout }, pollMs = POLL_MS, slowPollMs = SLOW_POLL_MS, fastForMs = FAST_FOR_MS, timeoutMs = TIMEOUT_MS }) {
+  const repo = config.forge.repo;
+  const folder = where || { proposals: config.proposals };
+  const targetOf = (pull) => `${repo}#${pull}`;
+  /** The landings being waited for in this process, by pull request */
+  const jobs = new Map();
+  /** The looks in flight, so a test (and a shutdown) can wait for them */
+  const looking = new Set();
+  let closed = false;
+
+  const log = (what, err) => console.error(`[cornfield] landing on approval: ${what}: ${err instanceof Error ? err.message : err}`);
+
+  const audit = async (job, request, status, answer) => {
+    try {
+      await auth.record({ login: job.login, action: 'landing', target: targetOf(job.pull), request: { slug: job.slug, sha: job.sha, ...request }, status, answer });
+    } catch (err) {
+      log(`the audit row of #${job.pull} could not be written`, err);
+    }
+  };
+
+  const setState = async (job, state) => {
+    try {
+      (await auth.store()).prepare("UPDATE landings SET state = ? WHERE repo = ? AND pull = ? AND sha = ? AND state = 'pending'").run(state, repo, job.pull, job.sha);
+    } catch (err) {
+      log(`#${job.pull} could not be marked ${state}`, err);
+    }
+  };
+
+  /** Ends a landing: marks it, writes the audit row, and posts the one comment when there is one and a forge to post it with */
+  async function end(job, state, why, { forge = null, comment = null, request = {} } = {}) {
+    if (job.over) return;
+    job.over = true;
+    if (job.timer !== null) timer.clearTimeout(job.timer);
+    if (jobs.get(job.pull) === job) jobs.delete(job.pull);
+    await setState(job, state);
+    await audit(job, { state, ...request }, null, { state, why });
+    if (forge && comment) {
+      try {
+        await postNote(forge, job.pull, comment);
+      } catch (err) {
+        log(`the comment on #${job.pull} could not be posted`, err);
+      }
+    }
+  }
+
+  const leftOpen = (job, why, forge) => end(job, 'left-open', why, {
+    forge, comment: `Left open: ${why}. cornfield will not land \`${job.slug}\` on its own now; land it with Land it once it is green.`,
+  });
+
+  /**
+   * Whether every proposal the PR holds at its head has, as its latest review by a maintainer, an approval of the file as it
+   * is now (its SHA-256). Approving one proposal of a PR that holds several does not land the others.
+   * @param {import('./forge.js').Forge} forge
+   * @param {import('./forge.js').Pull} pull read fresh from the forge
+   */
+  async function allApproved(forge, pull) {
+    const entries = await pullProposals(forge, folder, pull);
+    if (!entries.length) return false;
+    const comments = await forge.comments(pull.number);
+    for (const e of entries) {
+      const review = await latestReview(forge, pull.number, e.slug, comments);
+      if (!review || review.verdict !== 'approved' || typeof review.proposal !== 'string') return false;
+      if (review.proposal !== proposalHash(await readPullProposal(forge, folder, e))) return false;
+    }
+    return true;
+  }
+
+  /** One look at the PR. Resolves when it has ended the landing or decided to wait. */
+  async function look(job) {
+    if (job.over) return;
+    if (now() - Date.parse(job.started) >= timeoutMs) {
+      let forge = null;
+      try { forge = await auth.forgeForUser(job.userId); } catch { /* no sign-in left: no comment, the audit row says it */ }
+      return leftOpen(job, `its checks did not pass within ${Math.round(timeoutMs / 60_000)} minutes`, forge);
+    }
+    let forge;
+    try {
+      forge = await auth.forgeForUser(job.userId);
+    } catch (err) {
+      if (err instanceof ForgeError && err.code === 'unauthorized') return end(job, 'left-open', 'sign in to land');
+      log(`#${job.pull} waits`, err);
+      return;
+    }
+    try {
+      const pull = await forge.pull(job.pull);
+      if (pull.state !== 'open') return end(job, 'done', `the pull request is ${pull.state}`);
+      if (pull.head.sha.toLowerCase() !== job.sha) {
+        return end(job, 'cancelled', 'a push after approval', {
+          forge, request: { head: pull.head.sha },
+          comment: `Landing on approval was cancelled: a push after approval (the head is now ${pull.head.sha.slice(0, 7)}, not ${job.sha.slice(0, 7)}). \`${job.slug}\` was approved as it was; approve it again to land it.`,
+        });
+      }
+      const checks = await forge.checks(pull.head.sha);
+      const red = checks.filter((c) => c.state === 'failure' || c.state === 'cancelled');
+      if (red.length) return leftOpen(job, red.map((c) => `${oneLine(c.name, NAME_MAX)} ${c.state === 'failure' ? 'failed' : 'was cancelled'}`).join('; '), forge);
+      if (pull.draft || !isGreen(checks)) return;
+      // The approver, now: their sign-in is theirs, and a maintainer is what lands
+      const me = await forge.me();
+      if (String(me.id) !== job.userId) return end(job, 'left-open', 'sign in to land');
+      if (!isMaintainer(await forge.permission(repo, me.login))) return leftOpen(job, `${oneLine(me.login, NAME_MAX)} is not a maintainer of the repo now`, forge);
+      // Every proposal of the PR approved as it is now, not only the one that started this: else it waits, saying nothing
+      if (!(await allApproved(forge, pull))) return;
+      const method = mergeMethodOf(config);
+      // Stopped (cancelled, approved again, or the server shutting down) while the forge was being asked: nothing more is done
+      if (job.over || closed) return;
+      let landed;
+      try {
+        landed = await landPull({ forge, config, where, hooks, auth }, job.pull, job.sha, me.login);
+      } catch (err) {
+        return await merging(job, forge, err);
+      }
+      job.over = true;
+      if (job.timer !== null) timer.clearTimeout(job.timer);
+      jobs.delete(job.pull);
+      await setState(job, 'landed');
+      try {
+        await auth.record({ login: me.login, action: 'merge', target: targetOf(job.pull), request: { action: 'merge', number: job.pull, sha: job.sha, method, via: 'approval', slug: job.slug }, status: 200, answer: { ok: true, merged: true, number: job.pull, sha: landed.sha, head: job.sha, method } });
+      } catch (err) {
+        log(`the audit row of the landing of #${job.pull} could not be written`, err);
+      }
+    } catch (err) {
+      if (!(err instanceof ForgeError)) return log(`#${job.pull} waits`, err);
+      if (err.code === 'unauthorized') return end(job, 'left-open', 'sign in to land');
+      // Not found, rate-limited, unavailable: the forge's trouble, tried again at the next look (until the time is up)
+    }
+  }
+
+  /** What a refused merge means: not ready yet (wait), the head moved (cancelled), or a refusal for good (left open) */
+  async function merging(job, forge, err) {
+    if (!(err instanceof ForgeError)) throw err;
+    if (err.code === 'unauthorized') return end(job, 'left-open', 'sign in to land');
+    if (err.code === 'not-green' || err.code === 'rate-limited' || err.code === 'unavailable') return;
+    if (err.code === 'conflict') {
+      const pull = await forge.pull(job.pull);
+      if (pull.state !== 'open') return end(job, 'done', `the pull request is ${pull.state}`);
+      if (pull.head.sha.toLowerCase() !== job.sha) {
+        return end(job, 'cancelled', 'a push after approval', {
+          forge, request: { head: pull.head.sha },
+          comment: `Landing on approval was cancelled: a push after approval (the head is now ${pull.head.sha.slice(0, 7)}, not ${job.sha.slice(0, 7)}). \`${job.slug}\` was approved as it was; approve it again to land it.`,
+        });
+      }
+      if (pull.draft) return;
+    }
+    return leftOpen(job, oneLine(err.message, 300).replace(/\.$/, ''), forge);
+  }
+
+  /** A look, now or after a wait; schedules the next unless the landing ended */
+  function run(job) {
+    if (closed || job.over || job.looking) return Promise.resolve();
+    job.looking = true;
+    const p = look(job)
+      .catch((err) => log(`#${job.pull}`, err))
+      .finally(() => {
+        job.looking = false;
+        looking.delete(p);
+        if (!job.over && !closed) schedule(job);
+      });
+    looking.add(p);
+    return p;
+  }
+
+  function schedule(job) {
+    // Often at first, while checks usually finish; then less, so an hour's wait is not a request every 20 seconds
+    const waited = now() - Date.parse(job.started);
+    const t = timer.setTimeout(() => { job.timer = null; run(job); }, waited < fastForMs ? pollMs : slowPollMs);
+    if (t && typeof t.unref === 'function') t.unref();
+    job.timer = t;
+  }
+
+  /** Starts waiting for a landing; the first look is made at once */
+  function begin(row) {
+    const job = { ...row, pull: row.pull, userId: row.user_id, over: false, looking: false, timer: null };
+    const had = jobs.get(job.pull);
+    if (had) {
+      // Approved again: the newer approval replaces the older (its sha, its approver)
+      had.over = true;
+      if (had.timer !== null) timer.clearTimeout(had.timer);
+    }
+    jobs.set(job.pull, job);
+    return job;
+  }
+
+  /**
+   * Starts a landing for a spec PR that was just approved at `sha`, as `who`. Resolves once the row is written and the
+   * first look is made. A second approval of the same PR replaces the first.
+   * @param {{ pull: number, slug: string, sha: string, who: { userId: string, login: string } }} input
+   */
+  async function start({ pull, slug, sha, who }) {
+    if (closed) return;
+    // A PR that holds other proposals not approved as they are now: this approval does not start a landing (the last
+    // approval does). Asked fresh of the forge; a forge that cannot say now is asked again at every look before the merge.
+    try {
+      const forge = await auth.forgeForUser(String(who.userId));
+      const now_ = await forge.pull(pull);
+      if (now_.state === 'open' && now_.head.sha.toLowerCase() === sha.toLowerCase() && !(await allApproved(forge, now_))) return;
+    } catch { /* the looks decide */ }
+    const row = { repo, pull, slug, sha: sha.toLowerCase(), user_id: String(who.userId), login: who.login, started: iso(now()), state: /** @type {LandingState} */ ('pending') };
+    (await auth.store()).prepare("INSERT INTO landings (repo, pull, slug, sha, user_id, login, started, state) VALUES (?, ?, ?, ?, ?, ?, ?, 'pending') ON CONFLICT(repo, pull) DO UPDATE SET slug = excluded.slug, sha = excluded.sha, user_id = excluded.user_id, login = excluded.login, started = excluded.started, state = 'pending'")
+      .run(repo, pull, row.slug, row.sha, row.user_id, row.login, row.started);
+    const job = begin(row);
+    await audit(job, { state: 'pending' }, null, { state: 'pending', why: 'waiting for the checks' });
+    await run(job);
+  }
+
+  /**
+   * Picks up what a restart left: a pending row is waited for again, from when it started; one that is not pending, or whose
+   * time ran out while cornfield was away, is dropped (the timed-out one with an audit row).
+   */
+  async function resume() {
+    if (closed) return;
+    const db = await auth.store();
+    db.prepare("DELETE FROM landings WHERE repo = ? AND state <> 'pending'").run(repo);
+    const rows = /** @type {LandingRow[]} */ (db.prepare("SELECT * FROM landings WHERE repo = ? AND state = 'pending'").all(repo));
+    const looks = [];
+    for (const row of rows) {
+      const job = begin(row);
+      if (now() - Date.parse(row.started) >= timeoutMs) {
+        job.over = true;
+        jobs.delete(row.pull);
+        db.prepare('DELETE FROM landings WHERE repo = ? AND pull = ?').run(repo, row.pull);
+        await audit(job, { state: 'left-open' }, null, { state: 'left-open', why: 'its time ran out while cornfield was not running' });
+        continue;
+      }
+      looks.push(run(job));
+    }
+    await Promise.all(looks);
+  }
+
+  /**
+   * What is being waited for on a PR, or null.
+   * @returns {{ pull: number, slug: string, sha: string, by: string, since: string } | null}
+   */
+  function pending(pull) {
+    const job = jobs.get(pull);
+    return job && !job.over ? { pull, slug: job.slug, sha: job.sha, by: job.login, since: job.started } : null;
+  }
+
+  /**
+   * A maintainer stops a landing. Posts the one comment, as them. False when nothing was waiting.
+   * @param {number} pull
+   * @param {{ forge: import('./forge.js').Forge, login: string }} by
+   */
+  async function cancel(pull, by) {
+    const job = jobs.get(pull);
+    if (!job || job.over) return false;
+    await end(job, 'cancelled', `cancelled by ${by.login}`, {
+      forge: by.forge, request: { by: by.login },
+      comment: `Landing on approval was cancelled by ${oneLine(by.login, NAME_MAX)}. \`${job.slug}\` stays approved and the pull request stays open; land it with Land it when you are ready.`,
+    });
+    return true;
+  }
+
+  /** Waits for the looks in flight (the tests', and a clean shutdown's) */
+  async function idle() {
+    while (looking.size) await Promise.allSettled([...looking]);
+  }
+
+  function close() {
+    closed = true;
+    for (const job of jobs.values()) if (job.timer !== null) timer.clearTimeout(job.timer);
+    jobs.clear();
+  }
+
+  return { start, resume, pending, cancel, idle, close };
+}
+
+/** @typedef {ReturnType<typeof createLander>} Lander */
+
+// ---------------------------------------------------------------------------
+//  The dashboard's two routes
+// ---------------------------------------------------------------------------
+
+/**
+ * The landing route of the path, or null: `GET /api/forge/pulls/<n>/landing` (what is waiting) and
+ * `POST /api/forge/pulls/<n>/landing/cancel` (stop it).
+ * @param {string} reqPath
+ * @returns {{ n: number, cancel: boolean } | null}
+ */
+export function landingOf(reqPath) {
+  const m = /^\/api\/forge\/pulls\/([1-9]\d{0,8})\/landing(\/cancel)?$/.exec(reqPath);
+  return m ? { n: Number(m[1]), cancel: m[2] !== undefined } : null;
+}
+
+/**
+ * Answers a landing route. The read needs only a signed-in maintainer and asks the forge nothing; the cancel is a POST from
+ * cornfield's own page by a maintainer the forge confirms now, counted like any action.
+ * @param {import('node:http').IncomingMessage} req
+ * @param {{ n: number, cancel: boolean }} what
+ * @param {{ config: any, session: { login: string, userId: string } | null, auth: any, lander?: Lander | null, now?: () => number, publicHost?: string | null }} ctx
+ * @returns {Promise<{ status: number, body: object, headers?: Record<string, string> }>}
+ */
+export async function serveLanding(req, what, ctx) {
+  const { config, session, auth, lander = null, now = Date.now } = ctx;
+  req.resume();
+  if (!session) return { status: 403, body: { ok: false, error: 'Landing on approval is for the signed-in maintainer: set up sign-in first (docs/sign-in.md).', code: 'forbidden' } };
+  if (!what.cancel) {
+    if (req.method !== 'GET' && req.method !== 'HEAD') return { status: 405, body: { ok: false, error: 'Ask what is waiting with GET.', code: 'invalid' }, headers: { Allow: 'GET, HEAD' } };
+    return { status: 200, body: { ok: true, enabled: lander !== null, landing: lander ? lander.pending(what.n) : null } };
+  }
+  if (req.method !== 'POST') return { status: 405, body: { ok: false, error: 'Cancelling is done with POST.', code: 'invalid' }, headers: { Allow: 'POST' } };
+  try {
+    const flood = countAttempt(ctx, session.userId, now());
+    if (flood) throw flood;
+    if (!sameOrigin(req, ctx.publicHost ?? null)) throw new Refused(403, 'Do this from cornfield\'s own page.', 'forbidden');
+    if (!lander) throw new Refused(404, 'Landing on approval is not turned on (proposals.approveLands).', 'not-found');
+    const forge = auth.forgeFor(session);
+    const me = await forge.me();
+    if (String(me.id) !== String(session.userId)) throw new Refused(403, 'The forge says this sign-in is someone else now; sign in again.', 'forbidden');
+    if (!isMaintainer(await forge.permission(config.forge.repo, me.login))) throw new Refused(403, `Only the repo's maintainers stop a landing; ${me.login} is not one now.`, 'forbidden');
+    const stopped = await lander.cancel(what.n, { forge, login: me.login });
+    if (!stopped) throw new Refused(404, `Nothing is waiting to land pull request #${what.n}.`, 'not-found');
+    return { status: 200, body: { ok: true, cancelled: true, number: what.n } };
+  } catch (err) {
+    if (err instanceof Refused) return { status: err.status, body: { ok: false, error: err.message, code: err.code }, headers: err.headers };
+    if (err instanceof ForgeError) return { status: err.code === 'unauthorized' ? 401 : 502, body: { ok: false, error: err.message, code: err.code } };
+    throw err;
+  }
+}

package/server/proposals.js

@@ -265,7 +265,7 @@ async function putPullReview(req, res, where, forgeFor, signedIn, slug, n) {
   try {
     // 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,
+      forge: forgeFor, where, repo: signedIn.repo, who: { login: signedIn.login, userId: signedIn.userId }, record: signedIn.record, limits: signedIn.limits, hooks: signedIn.hooks, lander: signedIn.lander,
     }, { pull: n, slug, review: parsed });
     return send(res, 200, found);
   } catch (err) {
@@ -274,7 +274,7 @@ async function putPullReview(req, res, where, forgeFor, signedIn, slug, n) {
   }
 }
 
-/** @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 */
+/** @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, lander?: import('./lander.js').Lander | 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.

package/server/review-api.js

@@ -57,7 +57,7 @@ function send(res, status, body, headers = {}) {
 
 const plainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
 
-/** @typedef {{ config: any, where: any, auth: any, hooks?: import('./hooks.js').Hooks | null, now?: () => number, publicHost?: string | null }} ApiContext */
+/** @typedef {{ config: any, where: any, auth: any, hooks?: import('./hooks.js').Hooks | null, lander?: import('./lander.js').Lander | null, now?: () => number, publicHost?: string | null }} ApiContext */
 
 /**
  * `POST /api/reviews`. The caller has found the path to be this one; this runs before the sign-in guard.
@@ -123,7 +123,7 @@ export async function serveReviewCall(req, res, ctx) {
   try {
     const found = await submitReview({
       forge: () => auth.forgeForUser(row.user_id), where, repo, who: { login: row.login, userId: row.user_id },
-      record: (entry) => auth.record(entry), limits: { auth, now: ctx.now }, via: { token }, requireSha256: true, hooks: ctx.hooks,
+      record: (entry) => auth.record(entry), limits: { auth, now: ctx.now }, via: { token }, requireSha256: true, hooks: ctx.hooks, lander: ctx.lander,
       stillAllowed: async () => {
         const again = findToken(await auth.store(), /** @type {string} */ (presented), now());
         if (again && again.state === 'active') return null;

package/server/reviews.js

@@ -240,6 +240,22 @@ export async function postReview(forge, n, slug, review, { login, record, carrie
   }
 }
 
+/**
+ * Posts a plain note on PR `n`, as the token's user: the other thing cornfield says on a spec PR besides a review (server/lander.js:
+ * a landing on approval that was cancelled or left open). It goes by the same comment call as a review, with every mention and
+ * reference in it defused, since part of it (a check's name) is the forge's text and not cornfield's. The caller records it.
+ * Throws what the forge throws.
+ * @param {import('./forge.js').Forge} forge
+ * @param {number} n
+ * @param {string} text
+ * @returns {Promise<import('./forge.js').Comment>}
+ */
+export async function postNote(forge, n, text) {
+  const body = defuse(text);
+  if (body.length > MAX_COMMENT_CHARS) throw new ForgeError(`That note is too long for a comment (${body.length} characters, at most ${MAX_COMMENT_CHARS}).`, { code: 'invalid' });
+  return forge.comment(n, body);
+}
+
 // ---------------------------------------------------------------------------
 //  Stage 1 reviews, once
 // ---------------------------------------------------------------------------

package/server/server.js

@@ -53,6 +53,7 @@ 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';
+import { createLander } from './lander.js';
 
 export const CORNFIELD_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const EXPLORER_DIR = path.join(CORNFIELD_DIR, 'explorer');
@@ -106,7 +107,7 @@ export function clientConfig(config, signIn = false) {
     version: PKG.version,
     title: config.title,
     links: config.links || [],
-    forge: config.forge ? { type: config.forge.type, url: config.forge.url || (config.forge.type === 'github' ? 'https://github.com' : null), repo: config.forge.repo, mergeMethod: config.forge.mergeMethod || 'merge' } : null,
+    forge: config.forge ? { type: config.forge.type, url: config.forge.url || (config.forge.type === 'github' ? 'https://github.com' : null), repo: config.forge.repo, mergeMethod: config.forge.mergeMethod || 'merge', ...(config.approveLands ? { approveLands: true } : {}) } : null,
     sources: browserSources(config),
     signIn,
   };
@@ -125,10 +126,10 @@ 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, hookFetch?: typeof fetch, hookTimer?: { setTimeout: Function, clearTimeout: Function } }} [opts] what sign-in reads (`env`, and tests' fakes;
+ * @param {Parameters<typeof createAuth>[1] & { homeAssistant?: object, hookFetch?: typeof fetch, hookTimer?: { setTimeout: Function, clearTimeout: Function }, landTimer?: { 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); `hookFetch` and `hookTimer` are the
- *   tests' fake network and clock for the event hooks (server/hooks.js)
+ *   tests' fake network and clock for the event hooks (server/hooks.js); `landTimer` is the clock of landing on approval (server/lander.js)
  * @returns {import('node:http').Server}
  */
 export function createCornfieldServer(config, opts = {}) {
@@ -139,6 +140,8 @@ export function createCornfieldServer(config, opts = {}) {
   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;
+  // Landing on approval needs somebody signed in to land as, like the hooks' events: a half-set key is a startup error
+  if (config.approveLands && !auth.enabled) throw new Error('The config says proposals.approveLands, but sign-in is not set up. An approval is a signed-in maintainer\'s, and it lands as them, so without sign-in nothing would ever land: set up sign-in (docs/sign-in.md), or remove approveLands.');
   const root = config.root;
   const importMap = importMapOf(config);
   const csp = cspOf(importMap);
@@ -146,6 +149,11 @@ export function createCornfieldServer(config, opts = {}) {
   const publicHost = config.publicUrl ? new URL(config.publicUrl).hostname : null;
   const where = { root, proposals: config.proposals, worktrees: config.worktrees, topology: config.topology, dataDir: config.dataDir, publicHost };
   const fixtureCache = new Map();
+  const lander = config.approveLands ? createLander({ config, where, auth, hooks, now: opts.now, timer: opts.landTimer }) : null;
+  if (lander) {
+    // What a restart left waiting: looked at again, in the background
+    lander.resume().catch((err) => console.error(`[cornfield] pending landings could not be picked up: ${err instanceof Error ? err.message : err}`));
+  }
   const proxies = Object.entries(config.proxy || {});
   const houseSource = config.sources.house && (config.sources.house === 'house' || config.sources.house.use === 'house') ? config.sources.house : null;
   const houseFile = houseSource && houseSource.options && houseSource.options.file ? inside(root, houseSource.options.file) : null;
@@ -183,7 +191,7 @@ export function createCornfieldServer(config, opts = {}) {
       else res.end();
     }
   });
-  server.on('close', () => { hooks?.close(); auth.close(); });
+  server.on('close', () => { lander?.close(); hooks?.close(); auth.close(); });
   return server;
 
   async function answer(req, res) {
@@ -219,18 +227,18 @@ export function createCornfieldServer(config, opts = {}) {
       return sendJson(res, 200, { ok: true });
     }
     // The review API takes a token, not a session: it is the one route before the guard (and it reads no cookie)
-    if (reqPath === REVIEWS_PATH) return serveReviewCall(req, res, { config, where, auth, hooks, now: opts.now });
+    if (reqPath === REVIEWS_PATH) return serveReviewCall(req, res, { config, where, auth, hooks, lander, now: opts.now });
     const gate = await auth.gate(req, res, reqPath, url);
     if (gate.done) return;
     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 serveTokenRoutes(req, res, reqPath, { config, where, auth, session: gate.session, now: opts.now, publicHost })) return;
-    if (await serveForge(req, res, reqPath, url, { config, where, session: gate.session, auth, hooks, now: opts.now, publicHost })) return;
+    if (await serveForge(req, res, reqPath, url, { config, where, session: gate.session, auth, hooks, lander, 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;
-    const reviewer = session ? { login: session.login, userId: session.userId, repo: config.forge.repo, record: (entry) => auth.record(entry), limits: { auth, now: opts.now }, hooks } : null;
+    const reviewer = session ? { login: session.login, userId: session.userId, repo: config.forge.repo, record: (entry) => auth.record(entry), limits: { auth, now: opts.now }, hooks, lander } : null;
     if (serveProposals(req, res, reqPath, url, where, forgeFor, reviewer)) return;
 
     if (req.method !== 'GET' && req.method !== 'HEAD') {

package/server/submit-review.js

@@ -28,7 +28,10 @@
  * only its id and label.
  *
  * `submitReview` is the one place a review has been posted, so the event hooks' `spec.approved` and `spec.sentBack`
- * (server/hooks.js) are emitted here, after `postReview`, not in either caller.
+ * (server/hooks.js) are emitted here, after `postReview`, not in either caller. So is landing on approval
+ * (`proposals.approveLands`, server/lander.js): after an approval is posted, and never for a send-back, `lander.start` is
+ * begun in the background with the head that was approved. It is not awaited and cannot fail the review: the review is
+ * already on the PR, and what goes wrong in landing is the lander's to say on the PR.
  */
 
 import { ForgeError, isMaintainer } from './forge.js';
@@ -52,6 +55,7 @@ const MAX_PULL = 999_999_999;
  * @property {{ auth: object, now?: () => number }} limits what `server/throttle.js` counts by (one `auth` per server)
  * @property {import('./reviews.js').ApiVia} [via] set when the review came through the API: the token it came with
  * @property {import('./hooks.js').Hooks | null} [hooks] the event hooks (server/hooks.js): `spec.approved` or `spec.sentBack` after a post
+ * @property {import('./lander.js').Lander | null} [lander] landing on approval (server/lander.js), set only when the config says `proposals.approveLands`
  * @property {boolean} [requireSha256] the caller must name the version it read (the API does; the button reads the head itself)
  * @property {() => string | null | Promise<string | null>} [stillAllowed] asked once more just before the post, after every
  *   forge call: null to go on, or the words for why not (the API's token was revoked or expired meanwhile), refused 403
@@ -129,6 +133,12 @@ export async function submitReview(ctx, { pull, slug, review, sha256 = null, pro
     // The one place a review is posted, so the button and the API fire the same event; the actor is who the forge says
     // the poster is (with the API, the token's owner), never a name the caller sent
     ctx.hooks?.emit(posted.verdict === 'approved' ? 'spec.approved' : 'spec.sentBack', () => proposalPayload(forge, ctx.where, entry, { actor: me.login, note: checkedReview.note, edits: checkedReview.edits }));
+    if (posted.verdict === 'approved' && ctx.lander) {
+      const { lander } = ctx;
+      Promise.resolve()
+        .then(() => lander.start({ pull, slug, sha: entry.sha, who: { userId: who.userId, login: me.login } }))
+        .catch((err) => console.error(`[cornfield] landing ${target} on approval could not begin: ${err instanceof Error ? err.message : err}`));
+    }
     return posted;
   } catch (err) {
     if (!(err instanceof Refused) && !(err instanceof ForgeError)) console.error(`[cornfield] the review of ${target}: ${err instanceof Error ? err.stack || err.message : err}`);