whose-turn 0.0.0-stage → 1.0.0-alpha.3

package/lib/static.mjs

@@ -0,0 +1,36 @@
+/** Serves the built window from dist/ (ADR 0001): hashed assets cached by the browser for good, the pages never cached, files read once per build. A checkout without a build gets a plain notice. */
+import { readFile, stat } from 'node:fs/promises';
+import { join, extname } from 'node:path';
+
+const TYPES = { '.html': 'text/html', '.js': 'application/javascript', '.css': 'text/css', '.svg': 'image/svg+xml', '.map': 'application/json' };
+const PAGES = { '/': 'index.html', '/report': 'report.html', '/sheet': 'sheet.html' };
+const UNBUILT = Buffer.from('<!doctype html><meta charset="utf-8"><title>Whose Turn</title><p style="font: 15px system-ui; margin: 40px">The window is not built. Run <code>npm run build</code> in the whose-turn directory, then reload. The API on this port works without it.</p>');
+
+export const createStatic = (distDir) => {
+  const cache = new Map();
+  const read = async (relative) => {
+    const file = join(distDir, relative);
+    const { mtimeMs } = await stat(file);
+    const hit = cache.get(relative);
+    if (hit && hit.mtimeMs === mtimeMs) {
+      return hit.body;
+    }
+    const body = await readFile(file);
+    cache.set(relative, { mtimeMs, body });
+    return body;
+  };
+  /** The file for a path, with its type and cache header, or null when the path is not a window file; the unbuilt notice stands in for a missing page. */
+  return async (pathname) => {
+    const relative = PAGES[pathname] || pathname.replace(/^\/+/, '');
+    const type = TYPES[extname(relative)];
+    if (!type || relative.split('/').includes('..')) {
+      return null;
+    }
+    const page = Boolean(PAGES[pathname]);
+    try {
+      return { body: await read(relative), type, cacheControl: page ? 'no-store' : relative.startsWith('assets/') ? 'public, max-age=31536000, immutable' : 'public, max-age=3600' };
+    } catch {
+      return page ? { body: UNBUILT, type: 'text/html', cacheControl: 'no-store' } : null;
+    }
+  };
+};

package/lib/store.mjs

@@ -0,0 +1,61 @@
+/** One workspace's files on disk: state.json (last poll per source), marks.json (seen, handled, notified, health alerts already announced), todos.json and cache.json (connector caches that are data). */
+import { mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import { DAY } from './text.mjs';
+
+export const readJson = (path, fallback) => {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return fallback;
+  }
+};
+
+export const writeJson = (path, value) => {
+  writeFileSync(`${path}.tmp`, JSON.stringify(value));
+  renameSync(`${path}.tmp`, path);
+};
+
+const CACHE_VERSION = 1;
+
+const encodeCache = (cache, keys) => Object.fromEntries(keys.filter((key) => cache[key] instanceof Map).map((key) => [key, [...cache[key]]]));
+
+const decodeCache = (saved) => Object.fromEntries(Object.entries(saved || {}).filter(([, entries]) => Array.isArray(entries)).map(([key, entries]) => [key, new Map(entries)]));
+
+export const openStore = (dataDir, workspaceId) => {
+  const root = resolve(dataDir, 'workspaces');
+  const dir = resolve(root, workspaceId);
+  if (!dir.startsWith(root + sep)) {
+    throw new Error(`Workspace id "${workspaceId}" resolves outside the data directory.`);
+  }
+  mkdirSync(dir, { recursive: true });
+  const files = { state: join(dir, 'state.json'), marks: join(dir, 'marks.json'), todos: join(dir, 'todos.json'), cache: join(dir, 'cache.json') };
+  const state = { version: 0, errors: {}, polled_at: '', fails: {}, sources: {}, events: [], ...readJson(files.state, {}) };
+  const marks = { seen: [], base: null, handled: {}, notified: [], notified_seeded: false, health_alerted: [], ...readJson(files.marks, {}) };
+  if (!marks.base) {
+    marks.base = Date.now() - 3 * DAY;
+  }
+  const todos = readJson(files.todos, []);
+  const saved = readJson(files.cache, {});
+  const savedCaches = saved.version === CACHE_VERSION && saved.entries ? saved.entries : {};
+  let savedText = '';
+  return {
+    state,
+    marks,
+    todos,
+    saveState: () => writeJson(files.state, state),
+    saveMarks: () => writeJson(files.marks, marks),
+    saveTodos: () => writeJson(files.todos, todos),
+    loadCache: (entryId) => decodeCache(savedCaches[entryId]),
+    /** keysByEntry: entry id → the cache keys that are data; anything else (the token) never reaches disk. */
+    saveCaches: (caches, keysByEntry) => {
+      const entries = Object.fromEntries(Object.entries(keysByEntry).map(([entryId, keys]) => [entryId, encodeCache(caches[entryId] || {}, keys)]));
+      const file = { version: CACHE_VERSION, entries };
+      const text = JSON.stringify(file);
+      if (text !== savedText) {
+        savedText = text;
+        writeJson(files.cache, file);
+      }
+    },
+  };
+};

package/lib/table.mjs

@@ -0,0 +1,148 @@
+/** The rules table: validating rows, expanding the "default" marker, finding the first row whose conditions hold, filling {fact} placeholders. See docs/mechanisms/rules-table.md. */
+import { FACTS } from './facts.mjs';
+
+/** `then.whose` values: the label the row shows, and the feed group it forces (none keeps the seed row's group). */
+export const WHOSE = {
+  you: { label: 'You', group: 'you' },
+  reviewer: { label: 'Reviewer', group: null },
+  qa: { label: 'QA', group: null },
+  them: { label: null, group: null },
+  hidden: { label: null, group: 'gone' },
+};
+const THEN_KEYS = ['whose', 'next', 'why', 'rank', 'started', 'hold'];
+const DEFAULT_MARKER = 'default';
+
+const present = (value) => value !== null && value !== undefined;
+const NUMBER_OPERATORS = {
+  gt: (value, operand) => present(value) && value > operand,
+  gte: (value, operand) => present(value) && value >= operand,
+  lt: (value, operand) => present(value) && value < operand,
+  lte: (value, operand) => present(value) && value <= operand,
+};
+const OPERATORS = {
+  ...NUMBER_OPERATORS,
+  prefix: (value, operand) => present(value) && String(value).startsWith(operand),
+  present: (value, operand) => present(value) === operand,
+};
+const PLACEHOLDER = /\{([\w.]+)\}/g;
+
+const isPlainObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+
+const conditionHolds = (value, condition) => {
+  if (Array.isArray(condition)) {
+    return condition.includes(value);
+  }
+  if (isPlainObject(condition)) {
+    return Object.entries(condition).every(([operator, operand]) => OPERATORS[operator](value, operand));
+  }
+  return value === condition;
+};
+
+export const firstMatch = (table, facts) => table.find((row) => Object.entries(row.when).every(([fact, condition]) => conditionHolds(facts[fact], condition)));
+
+/** Replaces each {fact} with its value; a missing fact becomes empty text, an unknown name is left as written. */
+export const fillText = (text, facts) => String(text || '').replace(PLACEHOLDER, (placeholder, name) => (name in FACTS ? String(facts[name] ?? '') : placeholder));
+
+export const expandTable = (table, defaults) => (Array.isArray(table) ? table.flatMap((row) => (row === DEFAULT_MARKER ? defaults : [row])) : defaults);
+
+const closedValues = (name, groups) => {
+  const values = FACTS[name].values;
+  return values === 'status groups' ? groups : values;
+};
+
+const valueProblem = (name, value, groups) => {
+  const fact = FACTS[name];
+  if (typeof value !== fact.type) {
+    return `"${name}" is a ${fact.type}, got ${JSON.stringify(value)}`;
+  }
+  const values = closedValues(name, groups);
+  return values && !values.includes(value) ? `"${name}" is one of ${values.join(', ')}, got ${JSON.stringify(value)}` : null;
+};
+
+const operatorProblem = (name, operator, operand) => {
+  const type = FACTS[name].type;
+  if (operator in NUMBER_OPERATORS) {
+    return type === 'number' && typeof operand === 'number' ? null : `"${operator}" needs a number fact and a number, "${name}" is a ${type}`;
+  }
+  if (operator === 'prefix') {
+    return type === 'string' && typeof operand === 'string' ? null : `"prefix" needs a text fact and a text, "${name}" is a ${type}`;
+  }
+  if (operator === 'present') {
+    return typeof operand === 'boolean' ? null : `"present" needs true or false, got ${JSON.stringify(operand)}`;
+  }
+  return `unknown operator "${operator}" on "${name}"; use gt, gte, lt, lte, prefix or present`;
+};
+
+const conditionProblems = (name, condition, groups) => {
+  if (!(name in FACTS)) {
+    return [`unknown fact "${name}"; GET /api/config lists the facts`];
+  }
+  if (Array.isArray(condition)) {
+    return condition.length ? condition.map((value) => valueProblem(name, value, groups)).filter(Boolean) : [`the list for "${name}" is empty`];
+  }
+  if (isPlainObject(condition)) {
+    const entries = Object.entries(condition);
+    return entries.length ? entries.map(([operator, operand]) => operatorProblem(name, operator, operand)).filter(Boolean) : [`the condition on "${name}" is an empty object`];
+  }
+  const problem = valueProblem(name, condition, groups);
+  return problem ? [problem] : [];
+};
+
+const placeholderProblems = (text) => [...String(text).matchAll(PLACEHOLDER)].filter(([, name]) => !(name in FACTS)).map(([, name]) => `unknown fact "{${name}}" in the text`);
+
+const thenProblems = (then) => {
+  if (!isPlainObject(then)) {
+    return ['"then" must be an object { whose, next, why?, rank?, started?, hold? }'];
+  }
+  const problems = Object.keys(then).filter((key) => !THEN_KEYS.includes(key)).map((key) => `unknown key "then.${key}"`);
+  if (!(then.whose in WHOSE)) {
+    problems.push(`"then.whose" is one of ${Object.keys(WHOSE).join(', ')}, got ${JSON.stringify(then.whose)}`);
+  }
+  for (const key of ['started', 'hold']) {
+    if (then[key] !== undefined && typeof then[key] !== 'boolean') {
+      problems.push(`"then.${key}" must be true or false`);
+    }
+  }
+  if (then.rank !== undefined && !(Number.isInteger(then.rank) && then.rank >= 0)) {
+    problems.push('"then.rank" must be a whole number, 0 or more');
+  }
+  for (const key of ['next', 'why']) {
+    if (then[key] !== undefined && typeof then[key] !== 'string') {
+      problems.push(`"then.${key}" must be text`);
+    } else if (then[key]) {
+      problems.push(...placeholderProblems(then[key]));
+    }
+  }
+  if (then.whose !== 'hidden' && !then.next) {
+    problems.push('"then.next" is required unless whose is hidden');
+  }
+  return problems;
+};
+
+const rowProblems = (row, groups) => {
+  if (!isPlainObject(row)) {
+    return [`a row is { when, then } or the text "${DEFAULT_MARKER}"`];
+  }
+  const problems = Object.keys(row).filter((key) => !['when', 'then'].includes(key)).map((key) => `unknown key "${key}"`);
+  if (!isPlainObject(row.when)) {
+    problems.push('"when" must be an object of { fact: condition }');
+  } else {
+    problems.push(...Object.entries(row.when).flatMap(([name, condition]) => conditionProblems(name, condition, groups)));
+  }
+  return [...problems, ...thenProblems(row.then)];
+};
+
+/** What is wrong with a workspace table, one line per problem, each naming its row (1-based); empty when the table is fine or absent. */
+export const tableProblems = (table, groups) => {
+  if (table === undefined) {
+    return [];
+  }
+  if (!Array.isArray(table)) {
+    return ['rules.table must be a list of rows'];
+  }
+  const problems = table.flatMap((row, index) => (row === DEFAULT_MARKER ? [] : rowProblems(row, groups).map((problem) => `rules.table row ${index + 1}: ${problem}`)));
+  if (table.filter((row) => row === DEFAULT_MARKER).length > 1) {
+    problems.push(`rules.table: "${DEFAULT_MARKER}" may appear once`);
+  }
+  return problems;
+};

package/lib/text.mjs

@@ -0,0 +1,46 @@
+/** Small text and time helpers shared by connectors, rules and the store. */
+
+export const DAY = 86400000;
+
+export const toIsoUtc = (value) => {
+  const time = new Date(value || '').getTime();
+  return Number.isFinite(time) ? new Date(time).toISOString().replace(/\.\d{3}Z$/, 'Z') : '';
+};
+
+export const nowIso = () => toIsoUtc(Date.now());
+
+export const daysAgoIso = (days) => toIsoUtc(Date.now() - days * DAY);
+
+export const oneline = (text, limit = 140) => {
+  const flat = String(text || '').replace(/\s+/g, ' ').trim();
+  return flat.length <= limit ? flat : `${flat.slice(0, limit - 1)}…`;
+};
+
+export const escapeRegex = (text) => String(text).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+export const wordsRegex = (words, flags = 'i') => new RegExp(words.length ? words.map(escapeRegex).join('|') : '(?!)', flags);
+
+export const makeKeyFinder = (pattern) => {
+  const regex = new RegExp(pattern);
+  return (text) => {
+    const match = regex.exec(text || '');
+    return match ? match[0] : '';
+  };
+};
+
+export const newestFirst = (list) => list.slice().sort((a, b) => String(b.at).localeCompare(String(a.at)));
+
+export const unionCapped = (list, additions, cap = 5000) => [...new Set([...list, ...additions])].slice(-cap);
+
+export const mapLimit = async (items, limit, worker) => {
+  const results = new Array(items.length);
+  let next = 0;
+  const lane = async () => {
+    while (next < items.length) {
+      const index = next++;
+      results[index] = await worker(items[index], index);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, lane));
+  return results;
+};

package/lib/token-cache.mjs

@@ -0,0 +1,12 @@
+/** The one token cache of the connectors: a token read once and kept for ten minutes. */
+
+const TOKEN_TTL = 10 * 60 * 1000;
+
+/** The token `read` resolves to, kept in `cache.token` for ten minutes; an empty token is read again next time. */
+export const cachedToken = async (cache, read) => {
+  if (!cache.token || Date.now() - cache.tokenAt > TOKEN_TTL) {
+    cache.token = await read();
+    cache.tokenAt = Date.now();
+  }
+  return cache.token;
+};

package/lib/update.mjs

@@ -0,0 +1,134 @@
+/** Self-update of an installed package: a dist-tags check every ten minutes, one desktop notification per new version, and the one-click install and restart behind POST /api/update. ADR 0007, RMA-231. */
+import { execFile, spawn as spawnChild } from 'node:child_process';
+import { openSync, readFileSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+import { ApiError } from './errors.mjs';
+import { readJson, writeJson } from './store.mjs';
+
+export const PACKAGE = 'whose-turn';
+export const AGENT_LABEL = 'local.whose-turn';
+export const UPDATE_CHECK_MS = 10 * 60 * 1000;
+const INSTALL_TIMEOUT_MS = 10 * 60 * 1000;
+const VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+
+/** Where the BladeForge plugin installs the package: `<dataDir>/app/node_modules/whose-turn`. */
+export const installedRoot = (dataDir) => join(dataDir, 'app', 'node_modules', PACKAGE);
+
+/** True when the server runs from the plugin's install, so an update has somewhere to land; a checkout is never offered one. */
+export const runsInstalled = (appDir, dataDir, real = realpathSync) => {
+  try {
+    return real(appDir) === real(installedRoot(dataDir));
+  } catch {
+    return false;
+  }
+};
+
+/** The dist-tag every install follows: `latest`, which the release workflow moves on every publish, prereleases included (RMA-230). */
+export const CHANNEL = 'latest';
+
+/** The launch agent this process runs under, as the exit code that brings it back, or null when it runs on its own: launchd names its job in XPC_SERVICE_NAME and restarts on any exit (KeepAlive); the systemd unit shows in the cgroup and restarts only on a non-zero exit (Restart=on-failure). */
+export const probeAgent = ({ platform = process.platform, env = process.env, cgroup = () => readFileSync('/proc/self/cgroup', 'utf8') } = {}) => {
+  if (platform === 'darwin') {
+    return env.XPC_SERVICE_NAME === AGENT_LABEL ? { exitCode: 0 } : null;
+  }
+  if (platform === 'linux') {
+    try {
+      return cgroup().includes(`/${PACKAGE}.service`) ? { exitCode: 75 } : null;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+};
+
+/** Runs npm and resolves with '' when it succeeded, else with the last lines it printed; on Windows npm is a .cmd, which needs a shell, so every argument is quoted. */
+export const runNpm = (npm, args, platform = process.platform) => new Promise((resolve) => {
+  const shell = platform === 'win32';
+  execFile(npm, shell ? args.map((arg) => `"${arg}"`) : args, { timeout: INSTALL_TIMEOUT_MS, maxBuffer: 4 * 1024 * 1024, shell }, (error, stdout, stderr) => {
+    if (!error) {
+      return resolve('');
+    }
+    const lines = String(stderr || stdout || error.message).split('\n').map((line) => line.trim()).filter(Boolean);
+    resolve(lines.slice(-3).join(' ').slice(0, 400) || 'npm failed');
+  });
+});
+
+/** The restart after an install: under a launch agent exit and let it bring the new copy back; without one close the port, start the new copy detached and exit. */
+export const restartServer = ({ server, root, dataDir, agent = () => probeAgent(), spawn = spawnChild, exit = process.exit }) => {
+  const found = agent();
+  if (found) {
+    return exit(found.exitCode);
+  }
+  return new Promise((resolve) => {
+    server.close(resolve);
+    server.closeAllConnections();
+  }).then(() => {
+    const log = openSync(join(dataDir, 'server.log'), 'a');
+    spawn(process.execPath, [join(root, 'server.mjs')], { cwd: root, env: process.env, detached: true, stdio: ['ignore', log, log] }).unref();
+    exit(0);
+  });
+};
+
+/** The updater the API reads and writes; `installed` false (a checkout) keeps it idle and offers nothing. */
+export const createUpdater = ({ http, dataDir, version, installed, notify, registry = 'https://registry.npmjs.org', npm = 'npm', run = runNpm, restart }) => {
+  const listeners = new Set();
+  const memoFile = join(dataDir, 'update.json');
+  let latest = '';
+  let state = 'idle';
+  let reason = '';
+
+  const status = () => ({ current: version, latest, available: installed && Boolean(latest) && latest !== version, state, ...(state === 'failed' ? { reason } : {}) });
+  const announce = () => listeners.forEach((listener) => listener({ update: status() }));
+  const move = (next, why = '') => {
+    state = next;
+    reason = why;
+    announce();
+  };
+
+  const check = async () => {
+    if (!installed) {
+      return status();
+    }
+    const found = await http.fetchJson(`${registry}/-/package/${PACKAGE}/dist-tags`).then((tags) => tags && tags[CHANNEL], () => '');
+    if (typeof found === 'string' && VERSION.test(found) && found !== latest) {
+      latest = found;
+      announce();
+      if (found !== version && readJson(memoFile, {}).notified !== found) {
+        writeJson(memoFile, { notified: found });
+        notify(`Whose Turn ${found} is out`, 'Update from the window or your next session.');
+      }
+    }
+    return status();
+  };
+
+  const install = async () => {
+    const failure = await run(npm, ['install', '--prefix', join(dataDir, 'app'), '--no-audit', '--no-fund', '--no-save', `${PACKAGE}@${latest}`]);
+    if (failure) {
+      return move('failed', failure);
+    }
+    move('restarting');
+    await restart();
+  };
+
+  const apply = () => {
+    if (state === 'installing' || state === 'restarting') {
+      throw new ApiError('UPDATE_IN_PROGRESS', { state });
+    }
+    if (!status().available) {
+      throw new ApiError('UPDATE_UNAVAILABLE', { current: version, latest });
+    }
+    move('installing');
+    install().catch((error) => move('failed', String(error?.message || error)));
+    return status();
+  };
+
+  const start = () => {
+    check();
+    setInterval(check, UPDATE_CHECK_MS).unref();
+  };
+
+  return { status, check, apply, start, subscribe: (listener) => { listeners.add(listener); return () => listeners.delete(listener); } };
+};
+
+/** An updater for a server with nothing to update, the API's default. */
+export const noUpdates = () => createUpdater({ http: null, dataDir: '', version: '', installed: false, notify: () => {}, restart: async () => {} });

package/lib/window.mjs

@@ -0,0 +1,33 @@
+/** The app window's remembered size in <data>/window.json, and the launcher behind the window's "Open as app" button. */
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+import { ApiError } from './errors.mjs';
+import { readJson, writeJson } from './store.mjs';
+
+const MODES = ['app', 'browser'];
+const inRange = (value) => Number.isInteger(value) && value >= 300 && value <= 10000;
+
+export const readSize = (dataDir) => {
+  const { width, height } = readJson(join(dataDir, 'window.json'), {});
+  return inRange(width) && inRange(height) ? { width, height } : {};
+};
+
+export const saveSize = (dataDir, { width, height }) => {
+  if (!inRange(width) || !inRange(height)) {
+    throw new ApiError('INVALID_ARGUMENT', { detail: 'width and height are whole pixels between 300 and 10000' });
+  }
+  writeJson(join(dataDir, 'window.json'), { width, height });
+  return { width, height };
+};
+
+export const checkMode = (mode) => {
+  if (!MODES.includes(mode)) {
+    throw new ApiError('INVALID_ARGUMENT', { detail: `mode is one of ${MODES.join(', ')}` });
+  }
+  return mode;
+};
+
+export const spawnOpener = (appDir) => ({ mode, port }) => {
+  const args = mode === 'browser' ? ['--browser'] : [];
+  spawn(join(appDir, 'open.sh'), args, { env: { ...process.env, WHOSE_TURN_PORT: String(port) }, detached: true, stdio: 'ignore' }).unref();
+};