@popcorn245/cornfield 0.2.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/explorer.css

@@ -879,6 +879,16 @@ a.hx-forge-row:hover, button.hx-forge-row:hover { background: var(--hx-control-h
 .hx-confirm-pre:focus-visible { outline: 2px solid var(--hx-indigo); outline-offset: 2px; }
 .hx-confirm-note { margin: 0; color: var(--hx-text-2); line-height: 1.5; }
 .hx-confirm-actions { display: flex; justify-content: flex-end; gap: 8px; }
+.hx-tokens-list { display: flex; flex-direction: column; gap: 6px; margin: 0; padding: 0; list-style: none; }
+.hx-tokens-item { display: grid; grid-template-columns: 1fr auto; gap: 2px 8px; align-items: center; padding: 6px 8px; border-radius: 8px; border: 1px solid var(--hx-line); background: var(--hx-well-soft); }
+.hx-tokens-item[data-state="revoked"], .hx-tokens-item[data-state="expired"] { opacity: 0.65; }
+.hx-tokens-label { font-weight: 600; color: var(--hx-ink); overflow-wrap: anywhere; }
+.hx-tokens-meta { grid-column: 1; }
+.hx-tokens-item .hx-btn { grid-column: 2; grid-row: 1 / span 2; }
+.hx-tokens-row { display: flex; gap: 8px; align-items: center; }
+.hx-tokens-row .hx-forge-input { flex: 1; }
+.hx-tokens-form { display: grid; grid-template-columns: 1fr 5rem; gap: 8px; align-items: end; }
+.hx-tokens-form .hx-btn { grid-column: 1 / -1; justify-self: start; }
 .hx-forge-nodes { flex-basis: 100%; display: flex; flex-wrap: wrap; gap: 4px; padding-left: 62px; }
 .hx-forge-node { padding: 1px 8px; border-radius: 9999px; border: 1px solid var(--hx-amber); background: var(--hx-well-soft); color: var(--hx-text-2); font-size: 11px; }
 .hx-forge-node:hover { background: var(--hx-control-hover); }

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/explorer/index.html

@@ -103,6 +103,12 @@
         <span id="forge-btn-lit" class="hx-forge-lit" hidden></span>
       </button>
 
+      <!-- Review tokens (explorer/review-tokens.js): shown only when somebody is signed in to a forge -->
+      <button type="button" id="tokens-btn" class="hx-btn" aria-haspopup="dialog" aria-expanded="false" aria-controls="tokens-dialog" aria-label="Review tokens" title="Review tokens: let a script or a chat bot approve or send back a proposal as you" hidden>
+        <span aria-hidden="true">⚿</span>
+        <span class="hx-only-wide">Review tokens</span>
+      </button>
+
       <!-- The live layer's chip (explorer/live.js, spec 0029): shown once a live layer is on; a dot on a phone, its line on tap -->
       <div id="live-wrap" class="hx-menu-wrap hx-live" data-tone="idle" hidden>
         <button type="button" id="live-chip" class="hx-btn hx-live-chip" aria-haspopup="true" aria-expanded="false" aria-label="Live layer">
@@ -315,6 +321,32 @@
     </div>
   </div>
 
+  <!-- Review tokens (review-tokens.js): make one (shown once), list them, revoke; a modal dialog over a scrim, the focus stays in it -->
+  <div id="tokens-dialog" class="hx-confirm-scrim" hidden>
+    <div class="hx-confirm glass" role="dialog" aria-modal="true" aria-labelledby="tokens-title" aria-describedby="tokens-intro">
+      <h2 id="tokens-title" class="hx-confirm-title" tabindex="-1">Review tokens</h2>
+      <p id="tokens-intro" class="hx-confirm-note">A review token lets a script or a chat bot approve or send back a proposal as you (<code class="hx-code">POST /api/reviews</code>). It works while you are signed in here and still maintain the repo; it expires, and you can revoke it below.</p>
+      <p id="tokens-msg" class="hx-forge-msg" role="status" hidden></p>
+      <div id="tokens-secret" class="hx-tokens-secret" hidden>
+        <label class="hx-forge-field" for="tokens-secret-value">Your new token (copy it now, it is not shown again)</label>
+        <div class="hx-tokens-row">
+          <input id="tokens-secret-value" class="hx-forge-input hx-mono" type="text" readonly spellcheck="false" autocomplete="off" />
+          <button type="button" class="hx-btn" data-tokens-copy>Copy</button>
+        </div>
+      </div>
+      <ul id="tokens-list" class="hx-tokens-list" aria-label="Your review tokens"></ul>
+      <form id="tokens-form" class="hx-tokens-form" autocomplete="off">
+        <label class="hx-forge-field">Label<input id="tokens-label" class="hx-forge-input" type="text" maxlength="60" placeholder="chat bot" /></label>
+        <label class="hx-forge-field">Days<input id="tokens-days" class="hx-forge-input" type="text" inputmode="numeric" maxlength="2" aria-describedby="tokens-days-hint" /></label>
+        <span id="tokens-days-hint" class="hx-sr-only"></span>
+        <button type="submit" id="tokens-make" class="hx-btn hx-btn--approve">Make a token</button>
+      </form>
+      <div class="hx-confirm-actions">
+        <button type="button" class="hx-btn" data-tokens-close>Close</button>
+      </div>
+    </div>
+  </div>
+
   <script type="module" src="/explorer/main.js"></script>
 </body>
 </html>

package/explorer/main.js

@@ -17,6 +17,7 @@
  *   bench.js    /?bench=1 stopwatch and /?fixture=5k (the generated topology, from the server)
  *   keyboard.js the map by keyboard and the screen reader's announcer; keyboard-model.js its pure half
  *   live.js     the live layer: the chip, polling, laying a live source's answer over the map; live-model.js its pure half
+ *   review-tokens.js  review tokens for the review API, when somebody is signed in: make one (shown once), list, revoke; review-tokens-model.js its pure half
  *   forge-panel.js  the issues and PRs panel, when the config names a forge: a PR lights the nodes it changes; forge-panel-model.js its pure half
  *   theme.js    light or dark: the system setting and the header toggle; theme-model.js the colours (theme-boot.js before the first paint)
  */
@@ -41,6 +42,7 @@ import { initHouse } from './house.js';
 import { initChecks } from './check.js';
 import { initKeyboard } from './keyboard.js';
 import { initForgePanel } from './forge-panel.js';
+import { initReviewTokens } from './review-tokens.js';
 import { loadClientConfig, loadSources, applyBranding } from './plugins.js';
 import { cycleTheme, initTheme } from './theme.js';
 
@@ -207,6 +209,7 @@ loadTopology().then(async (ok) => {
   const config = await configReady;
   const { liveSource, floorRenderer, checker } = await loadSources(config);
   initForgePanel(config); // issues and PRs: only when the config names a forge (forge-panel.js)
+  initReviewTokens(config); // review tokens for the review API: only for somebody signed in (review-tokens.js)
   initWhatIf(); // before a proposal can open, so its edits come with it
   initReview(); // after it: the review controls sit under the edit controls on the bar
   initMockups(); // a proposal's screens open from the node they name

package/explorer/review-tokens-model.js

@@ -0,0 +1,86 @@
+/**
+ * @module explorer/review-tokens-model
+ *
+ * The pure half of the review tokens panel (spec 0002): no DOM, no `window`, no clock (the time is passed in).
+ * review-tokens.js is the half that touches the page and the network; the words and the request are decided here so
+ * they can be tested without a page.
+ *
+ *   TOKENS_URL         the server's address for them (server/review-api.js)
+ *   makeRequest        what a new token's form sends: { label, days? }, or why it cannot be sent yet
+ *   tokenLine          one token as the list shows it: its label, its state, when it ends, when it was last used
+ *   revokeUrl          the address that revokes one
+ *   errorWords         what a refusal of the server says, in plain words
+ *
+ * The server answers a list as `{ ok, tokens: [{ id, login, label, created, expires, revoked, lastUsed, state }], defaultDays, maxDays, maxActive }`
+ * and a new token as `{ ok, secret, token }`: the secret is in that answer only.
+ */
+
+import { relativeTime } from './review-model.js';
+
+export const TOKENS_URL = '/api/review-tokens';
+export const DEFAULT_DAYS = 30;
+export const MAX_DAYS = 90;
+export const MAX_LABEL = 60;
+const DAY = 24 * 60 * 60 * 1000;
+const HOUR = 60 * 60 * 1000;
+const LABEL = /^[\p{L}\p{N}][\p{L}\p{N} ._:/()-]*$/u;
+
+/** The address that revokes token `id` */
+export const revokeUrl = (id) => `${TOKENS_URL}/${encodeURIComponent(String(id))}/revoke`;
+
+/**
+ * What the form sends: the label, and the days when they were given. The server checks everything again.
+ * @param {string} label
+ * @param {string} days what the field holds; empty is the default
+ * @returns {{ ok: true, body: { label: string, days?: number } } | { ok: false, error: string }}
+ */
+export function makeRequest(label, days) {
+  const text = typeof label === 'string' ? label.trim() : '';
+  if (!text) return { ok: false, error: 'Give the token a label: what will use it, like "chat bot".' };
+  if (text.length > MAX_LABEL) return { ok: false, error: `A label is at most ${MAX_LABEL} characters.` };
+  if (!LABEL.test(text)) return { ok: false, error: 'A label is letters, digits, spaces and . _ : / ( ) - only.' };
+  const d = typeof days === 'string' ? days.trim() : '';
+  if (d === '') return { ok: true, body: { label: text } };
+  if (!/^\d{1,3}$/.test(d) || Number(d) < 1 || Number(d) > MAX_DAYS) return { ok: false, error: `A token lasts 1 to ${MAX_DAYS} days.` };
+  return { ok: true, body: { label: text, days: Number(d) } };
+}
+
+/** "in 12 days", "in 5 hours", "in under an hour", or "" for a time that does not read or is not ahead */
+function untilWords(iso, nowMs) {
+  const then = typeof iso === 'string' ? Date.parse(iso) : NaN;
+  if (!Number.isFinite(then) || !Number.isFinite(nowMs) || then <= nowMs) return '';
+  const left = then - nowMs;
+  if (left < HOUR) return 'in under an hour';
+  if (left < DAY) { const h = Math.floor(left / HOUR); return `in ${h} hour${h === 1 ? '' : 's'}`; }
+  const d = Math.floor(left / DAY);
+  return `in ${d} day${d === 1 ? '' : 's'}`;
+}
+
+/**
+ * One token as the list shows it.
+ * @param {{ id: number, label: string, expires: string, revoked: string | null, lastUsed: string | null, state: string }} token
+ * @param {number} nowMs
+ * @returns {{ id: number, label: string, state: 'active' | 'expired' | 'revoked', status: string, used: string, canRevoke: boolean }}
+ */
+export function tokenLine(token, nowMs) {
+  const state = token.state === 'revoked' || token.state === 'expired' ? token.state : 'active';
+  const status = state === 'revoked' ? `Revoked ${relativeTime(token.revoked, nowMs)}`.trim()
+    : state === 'expired' ? `Expired ${relativeTime(token.expires, nowMs)}`.trim()
+      : `Expires ${untilWords(token.expires, nowMs)}`.trim();
+  const used = token.lastUsed ? `Last used ${relativeTime(token.lastUsed, nowMs)}` : 'Never used';
+  return { id: token.id, label: String(token.label), state, status, used, canRevoke: state !== 'revoked' };
+}
+
+/**
+ * What a refusal says, in plain words: the server's own where it gave some.
+ * @param {number | null} status null when the server could not be reached
+ * @param {{ error?: string } | null} body
+ */
+export function errorWords(status, body) {
+  if (status === null) return 'cornfield could not be reached. Try again in a moment.';
+  if (status === 401) return 'Your sign-in has ended. Sign in again.';
+  if (body && typeof body.error === 'string' && body.error) return body.error;
+  if (status === 403) return 'Only the repo\'s maintainers can do that.';
+  if (status === 429) return 'Too many tries. Wait a little.';
+  return 'That did not work. Try again in a moment.';
+}

package/explorer/review-tokens.js

@@ -0,0 +1,216 @@
+/**
+ * @module explorer/review-tokens
+ *
+ * Review tokens in the dashboard (spec 0002, server/review-api.js): a signed-in maintainer makes a token so a script or a
+ * chat bot can Approve or Send back a proposal as them (`POST /api/reviews`), sees the tokens they hold and revokes one.
+ * A header button opens a dialog over the map (a scrim, `aria-modal`, the focus stays in it, Escape and Close give it
+ * back to the button). Shown only when the config names a forge and somebody is signed in: without sign-in there are no
+ * tokens.
+ *
+ *   GET  /api/review-tokens              the list: label, when it ends, when it was last used
+ *   POST /api/review-tokens              { label, days? } -> the new token, **in that answer only**
+ *   POST /api/review-tokens/<id>/revoke  ends one
+ *
+ * A new token is put in a read-only field with a Copy button and the words that it is not shown again; it lives in
+ * that field and nowhere else (not in a variable, a storage or an announcement for a screen reader), and Close or
+ * making another empties it. The list never holds a secret; the server has only a hash.
+ *
+ * The words and the request are review-tokens-model.js, tested without a page.
+ */
+
+import { escHtml } from './state.js';
+import { announce } from './keyboard.js';
+import { TOKENS_URL, DEFAULT_DAYS, MAX_DAYS, makeRequest, revokeUrl, tokenLine, errorWords } from './review-tokens-model.js';
+
+const $ = (id) => document.getElementById(id);
+let wired = false;
+let now = () => Date.now();
+const ui = { open: false, busy: false, tokens: [], loaded: false, message: null };
+
+const dialog = () => $('tokens-dialog');
+
+async function request(method, url, payload) {
+  try {
+    const res = await fetch(url, { method, cache: 'no-store', headers: payload === undefined ? {} : { 'Content-Type': 'application/json' }, ...(payload === undefined ? {} : { body: JSON.stringify(payload) }) });
+    let body = null;
+    try { body = await res.json(); } catch { /* no body */ }
+    return { ok: !!res.ok && !!body && body.ok === true, status: res.status, body };
+  } catch {
+    return { ok: false, status: null, body: null };
+  }
+}
+
+function say(text, ok = true) {
+  ui.message = text ? { text, ok } : null;
+  paint();
+  if (text) announce(text);
+}
+
+/** Everything the dialog shows, from `ui` */
+function paint() {
+  if (!dialog()) return;
+  const list = $('tokens-list');
+  if (!ui.loaded) list.innerHTML = '<li class="hx-faint">Loading …</li>';
+  else if (!ui.tokens.length) list.innerHTML = '<li class="hx-faint">You have no review tokens yet.</li>';
+  else {
+    list.innerHTML = ui.tokens.map((t) => {
+      const line = tokenLine(t, now());
+      return `<li class="hx-tokens-item" data-state="${line.state}"><span class="hx-tokens-label">${escHtml(line.label)}</span> <span class="hx-tokens-meta hx-faint">${escHtml(line.status)} · ${escHtml(line.used)}</span> ${line.canRevoke ? `<button type="button" class="hx-btn hx-btn--quiet" data-revoke="${escHtml(String(line.id))}" aria-label="Revoke ${escHtml(line.label)}"${ui.busy ? ' disabled' : ''}>Revoke</button>` : ''}</li>`;
+    }).join('');
+  }
+  const msg = $('tokens-msg');
+  msg.hidden = !ui.message;
+  msg.textContent = ui.message ? ui.message.text : '';
+  msg.classList.toggle('hx-forge-msg--bad', !!ui.message && !ui.message.ok);
+  $('tokens-make').disabled = ui.busy;
+}
+
+async function load() {
+  const res = await request('GET', TOKENS_URL);
+  if (res.ok && Array.isArray(res.body.tokens)) {
+    ui.tokens = res.body.tokens;
+    ui.loaded = true;
+    paint();
+    return;
+  }
+  ui.loaded = true;
+  ui.tokens = [];
+  say(errorWords(res.status, res.body), false);
+}
+
+function clearSecret() {
+  const box = $('tokens-secret');
+  $('tokens-secret-value').value = '';
+  box.hidden = true;
+}
+
+async function make(e) {
+  e.preventDefault();
+  if (ui.busy) return;
+  const checked = makeRequest($('tokens-label').value, $('tokens-days').value);
+  if (!checked.ok) { say(checked.error, false); $('tokens-label').focus(); return; }
+  clearSecret();
+  ui.busy = true;
+  say('');
+  const res = await request('POST', TOKENS_URL, checked.body);
+  ui.busy = false;
+  if (!res.ok || typeof res.body.secret !== 'string') { say(errorWords(res.status, res.body), false); return; }
+  // The one time the secret is seen: in the field, and not in a live region
+  $('tokens-secret-value').value = res.body.secret;
+  $('tokens-secret').hidden = false;
+  $('tokens-label').value = '';
+  $('tokens-days').value = '';
+  say(`Made the token "${res.body.token.label}". Copy it now: it is not shown again.`);
+  $('tokens-secret-value').focus();
+  $('tokens-secret-value').select();
+  await load();
+}
+
+async function revoke(id) {
+  if (ui.busy) return;
+  ui.busy = true;
+  paint();
+  const res = await request('POST', revokeUrl(id), {});
+  ui.busy = false;
+  if (!res.ok) say(errorWords(res.status, res.body), false);
+  else say(`Revoked "${res.body.token.label}". It no longer works.`);
+  await load();
+}
+
+async function copy() {
+  const field = $('tokens-secret-value');
+  try {
+    await navigator.clipboard.writeText(field.value);
+    announce('Copied.');
+    say('Copied. It is not shown again.');
+  } catch {
+    field.focus();
+    field.select();
+    say('Select the token and copy it by hand.', false);
+  }
+}
+
+/** While the dialog is open the focus cannot leave it */
+function keepFocusIn(e) {
+  const el = dialog();
+  if (ui.open && el && !el.contains(e.target)) $('tokens-title').focus();
+}
+
+export function openTokens() {
+  const el = dialog();
+  if (!el || ui.open) return;
+  ui.open = true;
+  ui.loaded = false;
+  ui.message = null;
+  document.addEventListener('focusin', keepFocusIn);
+  el.hidden = false;
+  $('tokens-btn').setAttribute('aria-expanded', 'true');
+  paint();
+  $('tokens-title').focus();
+  load();
+}
+
+export function closeTokens({ restoreFocus = true } = {}) {
+  const el = dialog();
+  if (!el || !ui.open) return;
+  ui.open = false;
+  clearSecret();
+  el.hidden = true;
+  document.removeEventListener('focusin', keepFocusIn);
+  $('tokens-btn').setAttribute('aria-expanded', 'false');
+  if (restoreFocus) $('tokens-btn').focus();
+}
+
+function onClick(e) {
+  if (e.target === dialog()) { closeTokens(); return; } // the scrim
+  const t = e.target.closest ? e.target.closest('button') : null;
+  if (!t) return;
+  if (t.hasAttribute('data-tokens-close')) closeTokens();
+  else if (t.hasAttribute('data-tokens-copy')) copy();
+  else if (t.hasAttribute('data-revoke')) revoke(t.getAttribute('data-revoke'));
+}
+
+/** Escape closes; Tab stays inside; nothing reaches the map behind */
+function onKey(e) {
+  e.stopPropagation();
+  if (e.key === 'Escape') { e.preventDefault(); closeTokens(); return; }
+  if (e.key !== 'Tab') return;
+  const items = [...dialog().querySelectorAll('button:not([disabled]), input:not([disabled])')].filter((el) => !el.closest('[hidden]'));
+  if (!items.length) { e.preventDefault(); return; }
+  const at = items.indexOf(document.activeElement);
+  const next = e.shiftKey ? (at <= 0 ? items.length - 1 : at - 1) : (at === -1 || at === items.length - 1 ? 0 : at + 1);
+  e.preventDefault();
+  items[next].focus();
+}
+
+/**
+ * Wires the button and the dialog (main.js calls this once the config is read). With no forge in the config, or nobody
+ * signed in, both stay hidden, and this returns false.
+ * @param {{ forge?: { type: string, repo: string } | null, signIn?: false | { login: string } }} config what `/cornfield/config.json` said
+ * @param {{ clock?: () => number }} [opts] `clock` for the times shown (tests)
+ * @returns {boolean} whether it is on
+ */
+export function initReviewTokens(config, opts = {}) {
+  const btn = $('tokens-btn');
+  if (!config || !config.forge || !config.signIn || !btn || !dialog()) return false;
+  if (opts.clock) now = opts.clock;
+  btn.hidden = false;
+  $('tokens-days').placeholder = String(DEFAULT_DAYS);
+  $('tokens-days-hint').textContent = `1 to ${MAX_DAYS}, ${DEFAULT_DAYS} if left empty`;
+  if (!wired) {
+    wired = true;
+    btn.addEventListener('click', openTokens);
+    dialog().addEventListener('click', onClick);
+    dialog().addEventListener('keydown', onKey);
+    $('tokens-form').addEventListener('submit', make);
+  }
+  return true;
+}
+
+/** For tests: forget the page this was wired to, and everything shown */
+export function resetReviewTokensForTests(clock = () => Date.now()) {
+  if (ui.open) closeTokens({ restoreFocus: false });
+  wired = false;
+  now = clock;
+  Object.assign(ui, { open: false, busy: false, tokens: [], loaded: false, message: null });
+}

package/package.json

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

@@ -279,6 +279,7 @@ export function createAuth(config, { env = process.env, now = Date.now, fetch: d
       /** Stage 1: everything passes; the routes under /auth/ are not there */
       gate: async () => ({ done: false, session: null }),
       forgeFor: () => { throw new Error('Sign-in is not configured.'); },
+      forgeForUser: async () => { throw new Error('Sign-in is not configured.'); },
       record: async () => { throw new Error('Sign-in is not configured.'); },
       begin: async () => { throw new Error('Sign-in is not configured.'); },
       finish: async () => { throw new Error('Sign-in is not configured.'); },
@@ -578,6 +579,20 @@ export function createAuth(config, { env = process.env, now = Date.now, fetch: d
       if (token === null) throw new ForgeError(`${forgeName} sign-in has to be renewed; sign in again.`, { code: 'unauthorized', forge: forgeName });
       return forgeWith(token);
     },
+    /**
+     * The forge as a user who may not be at the dashboard now, with the token their newest live sign-in keeps (a
+     * maintainer's session row holds it, encrypted, until the session ends: sign-out, expiry, or a demotion). This is how
+     * a review that came through the API (server/review-api.js) is posted as its token's owner. Throws a ForgeError
+     * `unauthorized` when they have no live sign-in, so there is nothing to post with. It does not check the permission:
+     * the caller asks the forge, with this token, every time.
+     * @param {string} userId the forge's id for the user
+     */
+    async forgeForUser(userId) {
+      const row = /** @type {SessionRow | undefined} */ ((await store()).prepare('SELECT * FROM sessions WHERE user_id = ? AND token <> ? AND expires_at > ? ORDER BY created_at DESC, rowid DESC LIMIT 1').get(String(userId), NO_TOKEN, iso(now())));
+      const token = row ? openToken(keys.enc, row.token) : null;
+      if (token === null) throw new ForgeError(`The token's owner has no live sign-in to ${forgeName}; they sign in to cornfield again, then the token works again.`, { code: 'unauthorized', forge: forgeName });
+      return forgeWith(token);
+    },
     /** The SQLite file (opened on first use), for the routes that keep answers in it (server/forge-routes.js) */
     store,
     close() {