cornfield 0.11.0 → 0.13.0

package/explorer/runs-map.js

@@ -0,0 +1,135 @@
+/**
+ * @module explorer/runs-map
+ *
+ * Agent runs on the map (issue #82, spec 0005 D9): the nodes an open run is changing **pulse**, and a node two or more open runs are
+ * changing carries a **collision** mark. The marks are a layer of their own over the map (`#run-overlay`, a DOM layer, so one drawing serves the
+ * Canvas 2D and the WebGL renderer, and the pulse is plain CSS that `prefers-reduced-motion` turns into a still ring):
+ *
+ *   - in flight   a ring that pulses (still under reduced motion: a thicker ring, no movement)
+ *   - collision   a dashed ring, a warning sign and the words "Collision" with how many runs: shape and text, never colour alone
+ *
+ * The layer is a toggle in the Layers menu ("Runs in flight", on unless turned off). The layer is decoration for the eye (`aria-hidden`):
+ * what a screen reader gets is the Runs view, which names each run's nodes and collisions in words, and the live region, which says when a
+ * state or a collision changes. The positions come from the scene the map just drew, so they follow every view, zoom and pan.
+ */
+
+import { state } from './state.js';
+import { render, onPaint } from './render.js';
+import { overlayOf } from './runs-model.js';
+import { flowReduceMotion } from './flows.js';
+
+/** The most marks drawn at once: past this the Runs view still lists them all */
+export const MAX_MARKS = 80;
+
+/** The key of the layer in the Layers menu and `state.activeLayers` */
+export const RUNS_LAYER = 'runs';
+
+/** @type {Map<string, HTMLElement>} the marks on the page by `<kind>:<node id>`, kept so a pulse is not restarted by every pan */
+const marks = new Map();
+let wired = false;
+/** What the marks were last placed for: a paint with the same scene, camera, runs, layer and motion moves nothing (packet frames) */
+let placed = '';
+let placedFor = null;
+let placedScene = null;
+let placedLayer = null;
+let reduce = null;
+
+/** Whether motion is reduced: the page's setting, or a test's */
+const reducedMotion = () => (reduce === null ? flowReduceMotion : reduce);
+/** For tests: force reduced motion on or off (null: follow the page's setting) */
+export function setReducedMotionForTests(on) { reduce = on; }
+
+/** Whether the layer is on */
+export const runsLayerOn = () => state.activeLayers[RUNS_LAYER] !== false;
+
+/** Hands the map the runs the API listed: what pulses and what collides is worked out here, and the map is drawn again */
+export function setRunsOnMap(runs) {
+  state.runsMap = Array.isArray(runs) && runs.length ? { ...overlayOf(runs), runs } : null;
+  wire();
+  paintLegend();
+  render();
+}
+
+/** Takes the marks off (the panel is reset, or there is no forge) */
+export function clearRunsOnMap() {
+  state.runsMap = null;
+  clearMarks();
+  paintLegend();
+}
+
+function wire() {
+  if (wired) return;
+  wired = true;
+  onPaint((scene, camera) => syncRunOverlay(scene, camera));
+}
+
+function clearMarks() {
+  for (const el of marks.values()) el.remove();
+  marks.clear();
+  placed = '';
+}
+
+/** The words on a collision mark */
+export const collisionTag = (n) => `Collision · ${n} runs`;
+
+/**
+ * Puts the marks on the nodes the scene drew, at the camera. Marks are kept between frames (only their place changes), so a pan does not
+ * restart the pulse.
+ * @param {{ nodes: { id: string, x: number, y: number, r: number, alpha: number }[] }} scene
+ * @param {{ x: number, y: number, zoom: number }} camera
+ */
+export function syncRunOverlay(scene, camera) {
+  const layer = typeof document !== 'undefined' ? document.getElementById('run-overlay') : null;
+  if (!layer) return;
+  const map = state.runsMap;
+  if (!map || !runsLayerOn() || (!map.flight.size && !map.collide.size)) { if (marks.size) clearMarks(); layer.hidden = true; placed = ''; return; }
+  // The map paints every frame while packets move; the marks only move with the scene or the camera
+  const key = `${scene.version}|${camera.x}|${camera.y}|${camera.zoom}|${reducedMotion()}`;
+  if (key === placed && placedFor === map && placedScene === scene && placedLayer === layer) return;
+  placed = key;
+  placedLayer = layer;
+  placedFor = map;
+  placedScene = scene;
+  layer.hidden = false;
+  layer.classList.toggle('is-static', reducedMotion());
+  const seen = new Set();
+  let n = 0;
+  for (const node of scene.nodes) {
+    if (n >= MAX_MARKS) break;
+    const runs = map.collide.get(node.id) || map.flight.get(node.id);
+    if (!runs || !(node.alpha > 0.2)) continue;
+    const kind = map.collide.has(node.id) ? 'collision' : 'flight';
+    const key = `${kind}:${node.id}`;
+    n += 1;
+    seen.add(key);
+    let el = marks.get(key);
+    if (!el) {
+      el = document.createElement('span');
+      el.className = `hx-run-mark hx-run-mark--${kind}`;
+      el.dataset.node = node.id;
+      el.dataset.kind = kind;
+      el.innerHTML = `<span class="hx-run-ring"></span>${kind === 'collision' ? `<span class="hx-run-tag"><span class="hx-run-sign">⚠</span> ${collisionTag(runs.length)}</span>` : ''}`;
+      layer.append(el);
+      marks.set(key, el);
+    }
+    const r = Math.max(10, (node.r + 9) * camera.zoom);
+    el.style.left = `${(node.x * camera.zoom + camera.x).toFixed(1)}px`;
+    el.style.top = `${(node.y * camera.zoom + camera.y).toFixed(1)}px`;
+    el.style.setProperty('--r', `${r.toFixed(1)}px`);
+  }
+  for (const [key, el] of marks) if (!seen.has(key)) { el.remove(); marks.delete(key); }
+}
+
+/** The legend in the Layers menu: shown while runs are on the map, saying in words what each mark is */
+export function paintLegend() {
+  const el = typeof document !== 'undefined' ? document.getElementById('runs-legend') : null;
+  if (!el) return;
+  el.hidden = !(state.runsMap && (state.runsMap.flight.size || state.runsMap.collide.size));
+}
+
+/** For tests: forget the page */
+export function resetRunsMapForTests() {
+  clearMarks();
+  state.runsMap = null;
+  reduce = null;
+}

package/explorer/runs-model.js

@@ -123,3 +123,149 @@ export function confirmStartWords(refs, forgeName) {
   const where = refs.proposal != null ? `the spec pull request of proposal ${refs.proposal}` : refs.thread != null ? `thread #${refs.thread}` : `issue #${refs.issue}`;
   return `This posts a request as a comment on ${where} on ${forgeName}, as you. Your runner picks it up. cornfield starts nothing and sends no credentials.`;
 }
+
+// ---------------------------------------------------------------------------
+//  Runs on the map (issue #82): the Runs view, the compare, the timeline, and what the map shows
+// ---------------------------------------------------------------------------
+
+/** Runs asked for within this long of each other, on the same subject, kind and brief, are one request under different profiles */
+export const COMPARE_WINDOW_MS = 3 * 60_000;
+
+const plural = (n, one) => `${n} ${n === 1 ? one : `${one}s`}`;
+const listWords = (items) => (items.length <= 2 ? items.join(' and ') : `${items.slice(0, -1).join(', ')} and ${items[items.length - 1]}`);
+
+/** The subject of a run as a key: the same issue, thread and proposal */
+const subjectKey = (refs) => JSON.stringify([refs?.issue ?? null, refs?.thread ?? null, refs?.proposal ?? null]);
+
+/**
+ * The runs for the view, newest first: a run on its own, or a **compare**: the same request (same subject, kind and brief) asked for under
+ * different profiles within `COMPARE_WINDOW_MS`, shown side by side. A group sits where its newest run is; inside it the runs are in profile order.
+ * @param {object[]} runs as the API lists them (newest first)
+ * @returns {({ kind: 'run', run: object } | { kind: 'compare', key: string, runs: object[] })[]}
+ */
+export function groupRuns(runs) {
+  const clusters = [];
+  const byKey = new Map();
+  for (const run of runs) {
+    const key = `${subjectKey(run.refs)}|${run.kind}|${typeof run.brief === 'string' ? run.brief : ''}`;
+    const at = Date.parse(run.requestedAt);
+    const open = byKey.get(key) ?? [];
+    // Newest first: a run joins the cluster its time is within the window of, if that cluster has not got its profile yet
+    const home = open.find((c) => Math.abs(c.newest - at) <= COMPARE_WINDOW_MS && !c.runs.some((r) => (r.profile ?? '') === (run.profile ?? '')));
+    if (home) { home.runs.push(run); continue; }
+    const fresh = { key, newest: at, runs: [run], first: clusters.length };
+    open.push(fresh);
+    byKey.set(key, open);
+    clusters.push(fresh);
+  }
+  return clusters.map((c) => (c.runs.length > 1
+    ? { kind: 'compare', key: c.runs.map((r) => r.runId).join('+'), runs: [...c.runs].sort((a, b) => String(a.profile ?? '').localeCompare(String(b.profile ?? ''))) }
+    : { kind: 'run', run: c.runs[0] }));
+}
+
+/** What the group is titled: "Code on issue #7 under 2 profiles: claude and qwen" */
+export function compareTitle(runs) {
+  const first = runs[0];
+  const kind = (KINDS.find(([k]) => k === first.kind) || [first.kind, first.kind])[1].split(':')[0];
+  return `${kind} on ${aboutWords(first.refs)} under ${plural(runs.length, 'profile')}: ${listWords(runs.map((r) => r.profile || 'no profile'))}`;
+}
+
+/** Limits beside what the runner reported: a row for each of minutes, turns, cost and tokens that has either, in words (never a bare dash) */
+export function limitRows(run) {
+  const l = run.limits || {};
+  const r = run.report || {};
+  const rows = [];
+  const add = (name, limit, reported) => {
+    if (limit == null && reported == null) return;
+    rows.push({ name, limit: limit == null ? 'no limit asked' : String(limit), reported: reported == null ? 'not reported' : String(reported) });
+  };
+  add('Minutes', l.minutes, null);
+  add('Turns', l.turns, null);
+  add('Cost', l.cost, r.cost);
+  add('Tokens', null, r.tokens);
+  return rows;
+}
+
+/** The checks of a run's pull request, said short */
+export function checksWords(run) {
+  if (!run.pull) return 'No pull request yet, so no checks.';
+  return { success: 'Checks passing', failure: 'Checks failing', running: 'Checks running', none: 'The pull request has no checks' }[run.checks] || 'Checks not read yet';
+}
+
+/** One line of a run's timeline, and the runner's words under it (data for the page to escape) */
+export function timelineWords(entry) {
+  const by = entry.actor ? ` by ${entry.actor}` : '';
+  switch (entry.kind) {
+    case 'requested': return { what: `Requested${by}${entry.ref ? ` under the profile ${entry.ref}` : ''}`, note: '' };
+    case 'claimed': return { what: `Claimed${by}`, note: entry.note || '' };
+    case 'report': return { what: `Reported ${entry.ref || 'in'}${by}`, note: entry.note || '' };
+    // When cornfield saw it, not when it was pushed: the forge does not say
+    case 'push': return { what: `Push seen: ${String(entry.ref || '').slice(0, 7)}${entry.note ? ` on ${entry.note}` : ''}`, note: '' };
+    case 'pull-opened': return { what: `Opened pull request ${entry.ref || ''}${by}`.trim(), note: '' };
+    case 'checks': return { what: { success: 'Checks passed', failure: 'Checks failed', running: 'Checks running', none: 'No checks' }[entry.ref] || 'Checks changed', note: '' };
+    case 'stop-requested': return { what: `Asked to stop${by}`, note: entry.note || '' };
+    case 'merged': return { what: `Landed: pull request ${entry.ref || ''} merged`, note: '' };
+    case 'closed': return { what: `Pull request ${entry.ref || ''} closed without landing`, note: '' };
+    case 'quiet': return { what: 'Went quiet: nothing reported or pushed for a while', note: '' };
+    default: return { what: entry.kind, note: entry.note || '' };
+  }
+}
+
+/** The ids of the nodes a run names, as the names the map shows (an id the map lacks is shown as it is) */
+export function nodeLabels(ids, nodes) {
+  const byId = new Map((nodes || []).map((n) => [n.id, n.label || n.id]));
+  return (ids || []).map((id) => byId.get(id) || id);
+}
+
+/**
+ * What the map shows of the runs: the nodes of the open runs (in flight), and those two or more open runs share (collisions). A run that
+ * is finished or quiet marks nothing.
+ * @param {object[]} runs
+ * @returns {{ flight: Map<string, string[]>, collide: Map<string, string[]> }} node id to the ids of the open runs that name it
+ */
+export function overlayOf(runs) {
+  const flight = new Map();
+  for (const run of runs || []) {
+    if (!run.open) continue;
+    for (const id of run.nodes || []) flight.set(id, [...(flight.get(id) || []), run.runId]);
+  }
+  const collide = new Map([...flight].filter(([, ids]) => ids.length > 1));
+  return { flight, collide };
+}
+
+/** What a run lights when it is selected, like a pull request: its nodes, whatever its state */
+export const litOfRun = (run) => ({ changed: new Set(run ? run.nodes || [] : []), failing: new Set() });
+
+/** The collision of a run in words: "Collides with run-… on orders and cart" (null when it does not) */
+export function collisionWords(run, runs, nodes) {
+  const others = (run.collidesWith || []);
+  if (!run.open || !others.length) return null;
+  const mine = new Set(run.nodes || []);
+  const shared = [...new Set(others.flatMap((id) => ((runs.find((r) => r.runId === id) || {}).nodes || []).filter((n) => mine.has(n))))];
+  return `Collides with ${listWords(others)}${shared.length ? ` on ${listWords(nodeLabels(shared, nodes))}` : ''}`;
+}
+
+/**
+ * What changed between two answers, as sentences for the live region: a run that appeared, a new state, a collision begun or cleared.
+ * Nothing before the first answer (`before` is null): the page does not read its whole list out on load.
+ * @param {object[] | null} before
+ * @param {object[]} after
+ * @returns {string[]}
+ */
+export function changeWords(before, after) {
+  if (!before) return [];
+  const was = new Map(before.map((r) => [r.runId, r]));
+  const out = [];
+  for (const run of after) {
+    const old = was.get(run.runId);
+    if (!old) { out.push(`New run ${run.runId}: ${run.kind} on ${aboutWords(run.refs)}, ${statusWords(run).toLowerCase()}`); continue; }
+    if (old.status !== run.status) out.push(`Run ${run.runId} is now ${statusWords(run).toLowerCase()}`);
+    const was2 = new Set(old.open ? old.collidesWith || [] : []);
+    const now2 = new Set(run.open ? run.collidesWith || [] : []);
+    const added = [...now2].filter((id) => !was2.has(id));
+    const gone = [...was2].filter((id) => !now2.has(id));
+    if (added.length) out.push(`Run ${run.runId} now collides with ${listWords(added)}`);
+    if (gone.length && !now2.size) out.push(`Run ${run.runId} no longer collides`);
+  }
+  return out;
+}

package/explorer/runs-view.js

@@ -0,0 +1,101 @@
+/**
+ * @module explorer/runs-view
+ *
+ * The markup of the Runs view in the Agents tab (issue #82), as strings: each run's state as a word, its profile, its limits beside what
+ * the runner reported, its thread, branch, pull request and checks, the nodes it changes and any collision, a timeline in order, and the
+ * runner's own `url` as "Runner's log" (cornfield streams no log). Runs of one request under different profiles are a **compare**: side by
+ * side on a wide panel, stacked on a narrow one. Pure: no DOM, no clock; the panel hands in what it knows and paints the string.
+ * Every word from a runner or the forge is escaped.
+ */
+
+import { relativeTime } from './review-model.js';
+import { aboutWords, statusWords, statusWhy, runMeta, canStop, groupRuns, compareTitle, limitRows, checksWords, timelineWords, nodeLabels, collisionWords } from './runs-model.js';
+
+const TONE = { done: 'success', merged: 'success', failed: 'failure', quiet: 'queued', 'stop-requested': 'queued' };
+
+/**
+ * @typedef {object} ViewContext
+ * @property {(s: unknown) => string} esc HTML escaping
+ * @property {(u: unknown) => string | null} safeUrl an http(s) address, or null
+ * @property {string} forgeName "GitHub"
+ * @property {string | null} repoUrl the repo's address on the forge ("https://github.com/owner/name"), or null
+ * @property {string} forgeType 'github' | 'forgejo'
+ * @property {number} now
+ * @property {{ id: string, label?: string }[]} nodes the map's nodes, for names
+ * @property {string | null} selected the run lit on the map
+ * @property {Set<string>} timelines the runs whose timeline is open
+ * @property {boolean} busy an action is in flight
+ */
+
+/** A link that opens a new tab, said so for a screen reader */
+const link = (ctx, href, text, after = '') => (ctx.safeUrl(href) ? `<a class="hx-link" href="${ctx.esc(href)}" target="_blank" rel="noreferrer">${ctx.esc(text)} <span class="hx-sr-only">(new tab)</span></a>${after}` : '');
+
+/** The address of a branch on the forge, or null */
+function branchUrl(ctx, branch) {
+  if (!ctx.repoUrl || !branch) return null;
+  const at = branch.split('/').map(encodeURIComponent).join('/');
+  return ctx.forgeType === 'forgejo' ? `${ctx.repoUrl}/src/branch/${at}` : `${ctx.repoUrl}/tree/${at}`;
+}
+
+/** The links of a run: the request, its thread, its branch, its pull request, and the runner's log (the runner's own `url`; nothing is streamed here) */
+function linksHtml(ctx, run) {
+  const thread = run.refs.thread ?? run.refs.issue;
+  return [
+    link(ctx, run.comment && run.comment.url, `Request on ${ctx.forgeName}`),
+    thread != null && ctx.repoUrl ? link(ctx, `${ctx.repoUrl}/issues/${thread}`, `Thread #${thread}`) : '',
+    run.branch ? link(ctx, branchUrl(ctx, run.branch), `Branch ${run.branch}`) : '',
+    run.pull ? link(ctx, run.pull.url, `Pull request #${run.pull.number}`, run.pull.trusted ? '' : ' <span class="hx-faint">(not from a runner, so it moves nothing)</span>') : '',
+    link(ctx, run.report && run.report.url, 'Runner\'s log'),
+  ].filter(Boolean).join(' · ');
+}
+
+function timelineHtml(ctx, run) {
+  const items = (run.timeline || []).map((e) => {
+    const w = timelineWords(e);
+    return `<li><time datetime="${ctx.esc(e.at)}" title="${ctx.esc(e.at)}">${ctx.esc(relativeTime(e.at, ctx.now) || e.at)}</time>${ctx.esc(w.what)}${w.note ? `<span class="hx-run-note">${ctx.esc(w.note)}</span>` : ''}</li>`;
+  });
+  return `<ol class="hx-run-timeline" id="run-tl-${ctx.esc(run.runId)}" aria-label="Timeline of ${ctx.esc(run.runId)}, oldest first">${items.join('')}</ol>`;
+}
+
+/** One run */
+export function runHtml(ctx, run, all) {
+  const lit = ctx.selected === run.runId;
+  const open = ctx.timelines.has(run.runId);
+  const tone = TONE[run.status] || 'running';
+  const why = statusWhy(run);
+  const note = run.report && run.report.note ? `<p class="hx-forge-meta">Runner: ${ctx.esc(run.report.note)}</p>` : '';
+  const stop = canStop(run) ? `<button type="button" class="hx-btn hx-forge-act" data-forge-stop="${ctx.esc(run.runId)}" aria-label="Stop run ${ctx.esc(run.runId)}"${ctx.busy ? ' disabled' : ''}>Stop</button>` : '';
+  const names = nodeLabels(run.nodes, ctx.nodes);
+  const collision = collisionWords(run, all, ctx.nodes);
+  const limits = limitRows(run);
+  const count = (run.timeline || []).length;
+  const links = linksHtml(ctx, run);
+  return `<li class="hx-run hx-forge-file" data-run="${ctx.esc(run.runId)}">
+    <div class="hx-run-head"><span class="hx-forge-state hx-forge-state--${tone}">${ctx.esc(statusWords(run))}</span> <span class="hx-name">${ctx.esc(run.kind)} on ${ctx.esc(aboutWords(run.refs))}</span>${run.profile ? ` <span class="hx-faint">profile ${ctx.esc(run.profile)}</span>` : ''}</div>
+    ${collision ? `<p class="hx-run-collide"><span aria-hidden="true">⚠</span> ${ctx.esc(collision)}</p>` : ''}
+    <p class="hx-forge-meta">${ctx.esc(runMeta(run, ctx.now))}</p>${why ? `<p class="hx-forge-why hx-faint">${ctx.esc(why)}</p>` : ''}${note}
+    <dl class="hx-run-limits" aria-label="Limits and what the runner reported">${limits.length ? limits.map((r) => `<dt>${ctx.esc(r.name)}</dt><dd>limit: ${ctx.esc(r.limit)}; reported: ${ctx.esc(r.reported)}</dd>`).join('') : '<dt>Limits</dt><dd>none asked, nothing reported</dd>'}</dl>
+    <p class="hx-forge-meta">${ctx.esc(checksWords(run))}</p>
+    <p class="hx-forge-meta">${names.length ? `Changing ${run.nodesFrom === 'files' ? '' : 'or expected to change '}${ctx.esc(names.join(', '))}` : 'No node on the map yet.'}</p>
+    ${links ? `<p class="hx-forge-meta">${links}</p>` : ''}
+    <div class="hx-run-actions">${stop}
+      <button type="button" class="hx-btn hx-forge-act" data-run-select="${ctx.esc(run.runId)}" aria-pressed="${lit}" aria-label="Light the nodes of ${ctx.esc(run.runId)} on the map"${(run.nodes || []).length ? '' : ' disabled'}>${lit ? 'Lit on the map' : 'Light on the map'}</button>
+      <button type="button" class="hx-btn hx-forge-act" data-run-timeline="${ctx.esc(run.runId)}" aria-expanded="${open}" aria-controls="run-tl-${ctx.esc(run.runId)}">Timeline (${count})</button></div>
+    ${open ? timelineHtml(ctx, run) : ''}</li>`;
+}
+
+/**
+ * The list: runs on their own and compares, as the items of the list.
+ * @param {ViewContext} ctx
+ * @param {object[]} runs
+ */
+export function runsHtml(ctx, runs) {
+  return groupRuns(runs).map((g) => {
+    if (g.kind === 'run') return runHtml(ctx, g.run, runs);
+    const id = `cmp-${g.runs[0].runId}`;
+    return `<li class="hx-run-group"><section class="hx-run-compare" aria-labelledby="${ctx.esc(id)}">
+      <h4 class="hx-run-compare-title" id="${ctx.esc(id)}">${ctx.esc(compareTitle(g.runs))}</h4>
+      <p class="hx-forge-meta hx-faint">The same request under each profile, side by side.</p>
+      <ul class="hx-run-columns" aria-label="${ctx.esc(g.runs.length)} profiles compared">${g.runs.map((r) => runHtml(ctx, r, runs)).join('')}</ul></section></li>`;
+  }).join('');
+}

package/explorer/state.js

@@ -119,6 +119,12 @@ export const state = {
    */
   forgeLit: null,
 
+  /**
+   * The runs on the map (explorer/runs-map.js): `{ flight: Map<nodeId, runId[]>, collide: Map<nodeId, runId[]>, runs }` for the open runs'
+   * nodes, or null when there are none. The map's marks over the nodes are drawn from it.
+   */
+  runsMap: null,
+
   /**
    * Which threads mention which nodes (forge-panel.js, docs/threads.md), for a node's panel: `{ for(nodeId) -> thread[] | null,
    * ensure(), open(number) }`, or null when threads are off or there is no forge. `for` answers null until the list has been

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cornfield",
-  "version": "0.11.0",
+  "version": "0.13.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)",