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

package/lib/config.mjs

@@ -0,0 +1,290 @@
+/** Loads the workspace config: data directory, defaults, and the list of workspaces, each with its connector entries and rules. */
+import { readFileSync, writeFileSync, renameSync, mkdirSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { isHex, derivedSeeds } from './palette.mjs';
+import { statusGroups } from './facts.mjs';
+import { tableProblems } from './table.mjs';
+import { DEFAULT_LIMITS } from './health.mjs';
+import { CONNECTORS } from '../connectors/index.mjs';
+
+export const DEFAULT_RULES = {
+  release_branch_prefix: 'release/',
+  approved_next: 'Merge it',
+  approved_release_next: 'Hand over to QA',
+  passed_next: 'Merge it and close the ticket',
+  merged_next: 'Close the ticket',
+  statuses: {
+    passed: ['passed'],
+    code_review: ['code review', 'in review'],
+    qa: ['ready for qa', 'in qa', 'testing'],
+    on_hold: ['on hold', 'blocked'],
+    backlog: ['backlog'],
+  },
+  automation_authors: ['automation'],
+  backlog_rows: 'hide',
+  question_words: ['please', 'pls', 'can you', 'could you', 'would you', 'let me know', 'need you', 'need your', 'thoughts', 'recommend', 'advise', 'confirm', 'clarify'],
+};
+
+export const DEFAULT_KEY_PATTERN = '\\b[A-Z][A-Z0-9_]+-\\d+\\b';
+
+/** What a settings form or Claude may edit on a workspace, beyond its connectors: one entry per field, neutral wording. */
+export const WORKSPACE_FIELDS = {
+  workspace: [
+    { key: 'id', label: 'Id', hint: 'short, used in the API and on disk', required: true },
+    { key: 'name', label: 'Name' },
+    { key: 'key_pattern', label: 'Ticket key pattern', hint: 'regex for keys in PR titles and to-dos; empty matches any Jira-style key' },
+    { key: 'links', label: 'Quick links', hint: 'one per entry as "Label https://…", comma-separated; the repository, Jira site and Linear project come by themselves', list: true },
+  ],
+  theme: [
+    { key: 'seed', label: 'Seed colour', hint: 'the scheme is derived from it; empty derives one from the workspace id', colour: true },
+    { key: 'accent', label: 'Accent colour', hint: 'optional second hue', colour: true },
+  ],
+  rules: [
+    { key: 'approved_next', label: 'Approved PR', hint: 'next step when a PR under review is approved' },
+    { key: 'approved_release_next', label: 'Approved release PR', hint: 'same, for a PR into a branch with the release prefix' },
+    { key: 'release_branch_prefix', label: 'Release branch prefix' },
+    { key: 'passed_next', label: 'Ticket passed', hint: 'next step when the ticket reached a passed status' },
+    { key: 'merged_next', label: 'PR merged', hint: 'next step when the PR is merged and the ticket is still on you' },
+    { key: 'automation_authors', label: 'Automation authors', hint: 'comment authors to ignore', list: true },
+    { key: 'backlog_rows', label: 'Backlog tickets', hint: 'hide, or list: show them under Waiting on others as a plain task list, for a project you run alone' },
+  ],
+  statuses: [
+    { key: 'code_review', label: 'Review statuses', list: true },
+    { key: 'qa', label: 'Verification statuses', list: true },
+    { key: 'passed', label: 'Passed statuses', list: true },
+    { key: 'on_hold', label: 'On hold statuses', list: true },
+    { key: 'backlog', label: 'Backlog statuses', list: true },
+  ],
+};
+
+/** The per-platform directory that holds config.json and the state, unless WHOSE_TURN_DATA overrides it. */
+export const defaultDataDir = () => {
+  if (process.platform === 'darwin') {
+    return join(homedir(), 'Library', 'Application Support', 'whose-turn');
+  }
+  if (process.platform === 'win32') {
+    return join(process.env.APPDATA || homedir(), 'whose-turn');
+  }
+  return join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'whose-turn');
+};
+
+const readJson = (path) => {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch (error) {
+    return error.code === 'ENOENT' ? null : { parse_error: error.message };
+  }
+};
+
+/** The monitor's port: WHOSE_TURN_PORT, then `port` in the config file, then 8765. */
+export const resolvePort = (dataDir, env = process.env) => {
+  if (env.WHOSE_TURN_PORT) {
+    return Number(env.WHOSE_TURN_PORT);
+  }
+  const raw = readJson(env.WHOSE_TURN_CONFIG || join(dataDir, 'config.json'));
+  return Number(raw?.port || 8765);
+};
+
+const mergeRules = (rules = {}) => ({
+  ...DEFAULT_RULES,
+  ...rules,
+  statuses: { ...DEFAULT_RULES.statuses, ...(rules.statuses || {}) },
+});
+
+const normaliseRules = (rules, problems, workspaceId) => {
+  const merged = /** @type {any} */ (mergeRules(rules));
+  const issues = tableProblems(merged.table, statusGroups(merged.statuses));
+  if (issues.length) {
+    problems.push(...issues.map((issue) => `Workspace "${workspaceId}": ${issue}; the table is ignored.`));
+    delete merged.table;
+  }
+  return merged;
+};
+
+const legacyWorkspace = (raw) => {
+  const connectors = [];
+  if (raw.github?.repo) {
+    connectors.push({ type: 'github', ...raw.github });
+  }
+  if (raw.jira?.base) {
+    connectors.push({ type: 'jira', ...raw.jira });
+  }
+  return { id: 'default', name: 'Default', connectors, rules: raw.rules, key_pattern: raw.jira?.key_pattern };
+};
+
+const isObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+
+const connectorEntries = (connectors) => {
+  const list = Array.isArray(connectors) ? connectors : Object.entries(connectors || {}).map(([type, settings]) => ({ type, ...settings }));
+  return list.filter(isObject).map((entry) => ({ ...entry, id: String(entry.id || entry.type) }));
+};
+
+const normaliseTheme = (theme, problems, workspaceId) => {
+  if (!theme) {
+    return null;
+  }
+  if (!isHex(theme.seed)) {
+    problems.push(`Workspace "${workspaceId}": theme.seed must be a hex colour like #3d7a5c; the theme is ignored.`);
+    return null;
+  }
+  if (theme.accent !== undefined && !isHex(theme.accent)) {
+    problems.push(`Workspace "${workspaceId}": theme.accent must be a hex colour like #c27a2c; the accent is ignored.`);
+  }
+  return { seed: theme.seed.toLowerCase(), ...(isHex(theme.accent) ? { accent: theme.accent.toLowerCase() } : {}) };
+};
+
+const normaliseLinks = (links) => (Array.isArray(links) ? links : []).map((entry) => {
+  if (typeof entry === 'string') {
+    const match = /^(.*?)\s*(https?:\/\/\S+)$/.exec(entry.trim());
+    return match ? { label: match[1].trim() || match[2].replace(/^https?:\/\//, ''), url: match[2] } : null;
+  }
+  return entry && /^https?:\/\//.test(String(entry.url || '')) ? { label: String(entry.label || entry.url), url: String(entry.url) } : null;
+}).filter(Boolean);
+
+const isStringList = (value) => Array.isArray(value) && value.every((item) => typeof item === 'string');
+
+const fieldProblems = (workspace, id) => {
+  const problems = [];
+  const where = `Workspace "${id}"`;
+  if (workspace.key_pattern) {
+    try {
+      new RegExp(workspace.key_pattern);
+    } catch (error) {
+      problems.push(`${where}: key_pattern is not a valid regular expression: ${error.message}`);
+    }
+  }
+  const rules = workspace.rules || {};
+  const statuses = rules.statuses;
+  if (statuses !== undefined && (!statuses || typeof statuses !== 'object' || Array.isArray(statuses))) {
+    problems.push(`${where}: rules.statuses must be an object of lists.`);
+  } else {
+    for (const [group, list] of Object.entries(statuses || {})) {
+      if (!isStringList(list) || list.some((item) => !item.trim())) {
+        problems.push(`${where}: rules.statuses.${group} must be a list of non-empty strings.`);
+      }
+    }
+  }
+  for (const key of ['automation_authors', 'question_words']) {
+    if (rules[key] !== undefined && !isStringList(rules[key])) {
+      problems.push(`${where}: rules.${key} must be a list of strings.`);
+    }
+  }
+  for (const entry of connectorEntries(workspace.connectors)) {
+    for (const field of CONNECTORS[entry.type]?.fields || []) {
+      if (field.boolean && entry[field.key] !== undefined && typeof entry[field.key] !== 'boolean') {
+        problems.push(`${where}: connector "${entry.id}": ${field.key} must be true or false.`);
+      }
+    }
+  }
+  return problems;
+};
+
+const WORKSPACE_ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
+
+const normaliseWorkspace = (workspace, index, problems) => {
+  const missing = workspace.id === undefined || workspace.id === null;
+  const id = String(missing ? `ws${index + 1}` : workspace.id);
+  if (!missing && !(typeof workspace.id === 'string' && WORKSPACE_ID.test(id))) {
+    problems.push(`Workspace ${index + 1}: the id "${id}" must be 1 to 40 lowercase letters, digits or hyphens, starting with a letter or digit.`);
+  }
+  problems.push(...fieldProblems(workspace, id));
+  return {
+    id,
+    links: normaliseLinks(workspace.links),
+    name: String(workspace.name || workspace.id || `Workspace ${index + 1}`),
+    connectors: connectorEntries(workspace.connectors),
+    rules: normaliseRules(workspace.rules, problems, id),
+    key_pattern: workspace.key_pattern || DEFAULT_KEY_PATTERN,
+    theme: normaliseTheme(workspace.theme, problems, id),
+  };
+};
+
+export const loadConfig = (env = process.env) => {
+  const dataDir = env.WHOSE_TURN_DATA || defaultDataDir();
+  const configFile = env.WHOSE_TURN_CONFIG || join(dataDir, 'config.json');
+  const raw = readJson(configFile);
+  const problems = [];
+  if (raw === null) {
+    problems.push(`No workspace config yet: open Settings (the gear) to add a source, or try the demo workspace. It will be written to ${configFile}.`);
+  } else if (raw.parse_error) {
+    problems.push(`Cannot parse ${configFile}: ${raw.parse_error}`);
+  }
+  const source = raw && !raw.parse_error ? raw : {};
+  const rawWorkspaces = Array.isArray(source.workspaces) ? source.workspaces : [legacyWorkspace(source)];
+  const { workspaces: normalised, problems: shapeProblems } = normaliseWorkspaces(rawWorkspaces);
+  const workspaces = normalised.filter((workspace) => WORKSPACE_ID.test(workspace.id));
+  return {
+    dataDir,
+    configFile,
+    port: resolvePort(dataDir, env),
+    pollSeconds: Number(source.poll_seconds || 60),
+    historyDays: Number(source.history_days || 14),
+    health: normaliseHealth(source, problems),
+    feedback: source.feedback && typeof source.feedback === 'object' ? source.feedback : null,
+    workspaces,
+    rawWorkspaces,
+    problems: [...problems, ...shapeProblems],
+  };
+};
+
+const normaliseHealth = (source, problems) => Object.fromEntries(Object.entries(DEFAULT_LIMITS).map(([key, fallback]) => {
+  const value = source[key] === undefined ? fallback : Number(source[key]);
+  if (!(value > 0)) {
+    problems.push(`${key} must be a positive number; using ${fallback}.`);
+    return [key, fallback];
+  }
+  return [key, value];
+}));
+
+/** Field violations for entries that are not objects: a workspace, or a connector in a workspace's connectors list. Checked before normalising, which assumes objects. */
+export const entryShapeViolations = (rawWorkspaces) => (Array.isArray(rawWorkspaces) ? rawWorkspaces : []).flatMap((workspace, index) => {
+  if (!isObject(workspace)) {
+    return [{ field: `workspaces[${index}]`, description: 'Every workspace must be an object.' }];
+  }
+  return (Array.isArray(workspace.connectors) ? workspace.connectors : []).flatMap((entry, at) => (isObject(entry)
+    ? []
+    : [{ field: `workspaces[${index}].connectors[${at}]`, description: 'Every connector must be an object.' }]));
+});
+
+/** Normalises a raw workspace list and reports what is wrong with it, without touching disk. */
+export const normaliseWorkspaces = (rawWorkspaces) => {
+  const problems = [];
+  const list = Array.isArray(rawWorkspaces) ? rawWorkspaces : [];
+  const workspaces = list.map((workspace, index) => normaliseWorkspace(isObject(workspace) ? workspace : {}, index, problems));
+  const seeds = derivedSeeds(workspaces.map((workspace) => ({ id: workspace.id, seed: workspace.theme?.seed })));
+  for (const workspace of workspaces) {
+    if (seeds[workspace.id]) {
+      workspace.derived_seed = seeds[workspace.id];
+    }
+  }
+  const seen = new Set();
+  for (const workspace of workspaces) {
+    if (seen.has(workspace.id)) {
+      problems.push(`Two workspaces share the id "${workspace.id}".`);
+    }
+    seen.add(workspace.id);
+    const connectorIds = workspace.connectors.map((entry) => entry.id);
+    if (new Set(connectorIds).size !== connectorIds.length) {
+      problems.push(`Workspace "${workspace.id}" has two connectors with the same id; give each an "id".`);
+    }
+  }
+  return { workspaces, problems };
+};
+
+/** Writes the workspace list into the config file, keeping its other top-level keys and dropping the flat pre-workspace keys; the previous file is kept as config.json.bak. */
+export const saveWorkspaces = (configFile, rawWorkspaces) => {
+  const current = readJson(configFile);
+  const source = current && !current.parse_error ? current : {};
+  delete source.github;
+  delete source.jira;
+  delete source.rules;
+  const next = { ...source, workspaces: rawWorkspaces };
+  mkdirSync(dirname(configFile), { recursive: true });
+  if (existsSync(configFile)) {
+    writeFileSync(`${configFile}.bak.tmp`, readFileSync(configFile));
+    renameSync(`${configFile}.bak.tmp`, `${configFile}.bak`);
+  }
+  writeFileSync(`${configFile}.tmp`, `${JSON.stringify(next, null, 2)}\n`);
+  renameSync(`${configFile}.tmp`, configFile);
+};

package/lib/default-table.mjs

@@ -0,0 +1,58 @@
+/** The plugin's default rules table, built from a workspace's rule texts; a workspace table replaces it or places it with the "default" marker. See docs/mechanisms/rules-table.md. */
+
+export const defaultTable = (rules) => [
+  {
+    when: { 'run.failed': true, 'run.mine': true },
+    then: { whose: 'you', next: 'Look at the failed run of {run.workflow} on {run.branch}', why: 'The latest {run.workflow} run on {run.branch} failed after your push.', rank: 0 },
+  },
+  { when: { 'run.failed': true }, then: { whose: 'hidden' } },
+  {
+    when: { 'ticket.status': 'backlog', 'ticket.done': false, 'pr.open': false },
+    then: rules.backlog_rows === 'list' ? { whose: 'them', next: '{ticket.status_name}' } : { whose: 'hidden' },
+  },
+  {
+    when: { 'pr.open': true, 'pr.checks': 'failing' },
+    then: { whose: 'you', next: 'Look at the failing checks', why: 'PR #{pr.number} has failing checks.', rank: 0 },
+  },
+  {
+    when: { 'pr.open': true, 'pr.review': 'changes_requested' },
+    then: { whose: 'you', next: 'Address the requested changes', why: 'A reviewer requested changes on PR #{pr.number}.', rank: 1 },
+  },
+  {
+    when: { 'pr.open': true, 'pr.unanswered': true },
+    then: { whose: 'you', next: 'Read and answer the new comment', why: '{pr.commenter} commented on PR #{pr.number} after your last reply there.' },
+  },
+  {
+    when: { 'ticket.status': 'passed' },
+    then: { whose: 'you', next: rules.passed_next, why: 'Ticket status is {ticket.status_name}: QA passed, the PR can go in.' },
+  },
+  {
+    when: { 'ticket.done': true, 'pr.open': true },
+    then: { whose: 'you', next: 'Ticket is Done but the PR is open: merge it', why: 'The ticket is {ticket.status_name} while PR #{pr.number} is still open.' },
+  },
+  {
+    when: { 'ticket.done': false, 'pr.merged': true, 'ticket.assignee': 'me' },
+    then: { whose: 'you', next: rules.merged_next, why: 'PR #{pr.number} is merged but the ticket is still {ticket.status_name} and on you.' },
+  },
+  {
+    when: { 'ticket.status': 'code_review', 'pr.open': true, 'pr.review': 'approved', 'pr.base': { prefix: rules.release_branch_prefix } },
+    then: { whose: 'you', next: rules.approved_release_next, why: 'PR #{pr.number} into {pr.base} is approved; the ticket is still in {ticket.status_name}.' },
+  },
+  {
+    when: { 'ticket.status': 'code_review', 'pr.open': true, 'pr.review': 'approved' },
+    then: { whose: 'you', next: rules.approved_next, why: 'PR #{pr.number} into {pr.base} is approved; the ticket is still in {ticket.status_name}.' },
+  },
+  { when: { 'ticket.status': 'code_review' }, then: { whose: 'reviewer', next: 'Code review' } },
+  { when: { 'ticket.status': 'qa' }, then: { whose: 'them', next: 'QA' } },
+  { when: { 'ticket.status': 'on_hold', 'ticket.hold_reason': { present: true } }, then: { whose: 'them', next: 'On hold: {ticket.hold_reason}', hold: true } },
+  { when: { 'ticket.status': 'on_hold' }, then: { whose: 'them', next: 'On hold' } },
+  {
+    when: { 'ticket.done': false, 'ticket.assignee': 'me', 'ticket.started': true },
+    then: { whose: 'you', next: 'Continue the work', why: 'Assigned to you and in progress, status {ticket.status_name}, no PR step pending.', rank: 2, started: true },
+  },
+  {
+    when: { 'ticket.done': false, 'ticket.assignee': 'me' },
+    then: { whose: 'you', next: 'Pick it up', why: 'Assigned to you, status {ticket.status_name}, no PR step pending.' },
+  },
+  { when: {}, then: { whose: 'them', next: 'Not yours now' } },
+];

package/lib/errors.mjs

@@ -0,0 +1,53 @@
+/** Error envelope (google.rpc.Status) and the reason registry for the local API. */
+
+const REASONS = {
+  NOT_FOUND: { code: 404, status: 'NOT_FOUND', message: 'No such path.' },
+  NO_SUCH_WORKSPACE: { code: 404, status: 'NOT_FOUND', message: 'No such workspace.' },
+  NO_SUCH_TODO: { code: 404, status: 'NOT_FOUND', message: 'No such to-do.' },
+  METHOD_NOT_ALLOWED: { code: 405, status: 'UNIMPLEMENTED', message: 'This path answers GET and POST only.' },
+  UNKNOWN_ACTION: { code: 400, status: 'INVALID_ARGUMENT', message: 'Unknown action.' },
+  INVALID_BODY: { code: 400, status: 'INVALID_ARGUMENT', message: 'The request body is not valid JSON.' },
+  INVALID_ARGUMENT: { code: 400, status: 'INVALID_ARGUMENT', message: 'A required value is missing or has the wrong shape.' },
+  INVALID_CONFIG: { code: 400, status: 'INVALID_ARGUMENT', message: 'The workspace list has problems; nothing was saved.' },
+  NO_WORKSPACE: { code: 412, status: 'FAILED_PRECONDITION', message: 'No workspace is configured; open Settings to add one.' },
+  NOT_CONFIGURED: { code: 412, status: 'FAILED_PRECONDITION', message: 'Feedback is not configured: set feedback.workspace, feedback.team and feedback.project in the config.' },
+  UPSTREAM_FAILED: { code: 502, status: 'UNAVAILABLE', message: 'The tracker did not answer; try again in a minute.' },
+  RATE_LIMITED: { code: 429, status: 'RESOURCE_EXHAUSTED', message: 'The source is rate-limited; try again later.' },
+  OPEN_TOO_SOON: { code: 429, status: 'RESOURCE_EXHAUSTED', message: 'The window was just opened; wait a few seconds before opening it again.' },
+  FORBIDDEN_ORIGIN: { code: 403, status: 'PERMISSION_DENIED', message: 'Only the local window may call this API.' },
+  INTERNAL: { code: 500, status: 'INTERNAL', message: 'The local server failed on this request; the details are in its log.' },
+};
+
+export class ApiError extends Error {
+  constructor(reason, metadata = {}, violations = []) {
+    const entry = REASONS[reason];
+    super(entry.message);
+    this.reason = reason;
+    this.code = entry.code;
+    this.status = entry.status;
+    this.metadata = metadata;
+    this.violations = violations;
+    this.debug = '';
+  }
+
+  toEnvelope() {
+    const details = /** @type {object[]} */ ([{ '@type': 'ErrorInfo', reason: this.reason, domain: 'whose-turn', metadata: this.metadata }]);
+    if (this.violations.length) {
+      details.push({ '@type': 'BadRequest', field_violations: this.violations.map((violation) => (typeof violation === 'string' ? { field: 'workspaces', description: violation } : violation)) });
+    }
+    if (this.debug && process.env.WHOSE_TURN_DEBUG === '1') {
+      details.push({ '@type': 'DebugInfo', detail: this.debug });
+    }
+    return { error: { code: this.code, status: this.status, message: this.message, details } };
+  }
+}
+
+/** The envelope of any failure: an ApiError as it is, anything else as INTERNAL with the raw text only under DebugInfo. */
+export const toApiError = (error) => {
+  if (error instanceof ApiError) {
+    return error;
+  }
+  const internal = new ApiError('INTERNAL');
+  internal.debug = String((error && error.message) || error);
+  return internal;
+};

package/lib/facts.mjs

@@ -0,0 +1,128 @@
+/** The closed fact dictionary the rules table reads: one flat object per ticket, computed from the normalized connector output. See docs/mechanisms/rules-table.md. */
+import { DAY, oneline, newestFirst } from './text.mjs';
+
+export const shortDate = (iso) => new Date(iso).toLocaleDateString('en-US', { month: 'short', day: 'numeric' });
+
+const CATEGORY_GROUPS = { new: 'todo', indeterminate: 'in_progress', done: 'done' };
+const CHAIN_GROUPS = ['backlog', 'passed', 'code_review', 'qa', 'on_hold'];
+
+/** Every fact a table row may test or quote: its type, the closed values when there are any, and where it comes from. */
+export const FACTS = {
+  connector: { type: 'string', from: 'the connector entry id the ticket came from' },
+  'ticket.key': { type: 'string', from: 'tracker connectors (jira, linear, demo)' },
+  'ticket.status': { type: 'string', values: 'status groups', from: 'the ticket status matched against rules.statuses; else todo, in_progress or done from the status category' },
+  'ticket.status_name': { type: 'string', from: 'the status as the tracker names it' },
+  'ticket.assignee': { type: 'string', from: '"me" when the ticket is on you, else the assignee name' },
+  'ticket.done': { type: 'boolean', from: 'the status category is done' },
+  'ticket.started': { type: 'boolean', from: 'the status category is in progress' },
+  'ticket.hold_reason': { type: 'string', from: 'the comment that explains an on_hold status; missing when none does' },
+  'pr.open': { type: 'boolean', from: 'github: the ticket has an open PR; false when it has none' },
+  'pr.merged': { type: 'boolean', from: 'github: the ticket PR is merged; false when it has none' },
+  'pr.number': { type: 'number', from: 'github' },
+  'pr.checks': { type: 'string', values: ['passing', 'failing', 'running', 'none'], from: 'github' },
+  'pr.review': { type: 'string', values: ['approved', 'changes_requested', 'none'], from: 'github' },
+  'pr.base': { type: 'string', from: 'github: the branch the PR goes into' },
+  'pr.unanswered': { type: 'boolean', from: 'github: a human commented after your last comment and it is not an approval' },
+  'pr.commenter': { type: 'string', from: 'github: the author of that last comment' },
+  'comment.mentions_me': { type: 'boolean', from: 'tracker comments: an unanswered @-mention of you on the ticket' },
+  'comment.is_question': { type: 'boolean', from: 'the newest unanswered mention reads as a question' },
+  'comment.author': { type: 'string', from: 'the author of the newest unanswered mention' },
+  unanswered_count: { type: 'number', from: 'how many @-mentions of you on the ticket are unanswered' },
+  'run.failed': { type: 'boolean', from: 'github: the latest completed run of a workflow on the default branch failed; missing on tickets' },
+  'run.workflow': { type: 'string', from: 'github: the name of that workflow' },
+  'run.branch': { type: 'string', from: 'github: the branch it ran on, the default branch' },
+  'run.mine': { type: 'boolean', from: 'github: you pushed the commit or started the run' },
+};
+
+/** The order status words are tried in: the chain's groups first, then any extra group in rules.statuses. */
+export const statusGroupOrder = (statuses) => [...new Set([...CHAIN_GROUPS.filter((group) => group in statuses), ...Object.keys(statuses)])];
+
+/** Every value ticket.status can take: the configured groups, then the category fallbacks. */
+export const statusGroups = (statuses) => [...new Set([...statusGroupOrder(statuses), ...Object.values(CATEGORY_GROUPS)])];
+
+/** The chain group a row carries as status_group for the window's pill tone: one of the chain's groups, else ''. */
+export const chainGroup = (group) => (CHAIN_GROUPS.includes(group) ? group : '');
+
+const statusGroupOf = (ticket, rules) => rules.statusOrder.find((group) => rules.statusIs(group, ticket.status)) || CATEGORY_GROUPS[ticket.status_category] || null;
+
+const firstSentence = (body) => {
+  const line = body.split('\n').map((candidate) => candidate.trim()).find((candidate) => candidate && !/^\[image\]$/.test(candidate)) || '';
+  const stripped = line.replace(/^@[\w .'-]+?\s+[—–-]\s+/, '').replace(/^.*?on hold\s*[:—–-]\s*/i, '').trim() || line;
+  return oneline(stripped.split(/(?<=[.!?])\s/)[0].replace(/\*\*|`/g, ''), 140);
+};
+
+export const holdReason = (ticketComments, ticket) => {
+  const change = ticket.status_change;
+  let chosen = null;
+  if (change && change.since) {
+    const holdTime = new Date(change.since).getTime();
+    const byMover = ticketComments.filter((comment) => comment.author === change.by).sort((a, b) => Math.abs(new Date(a.at).getTime() - holdTime) - Math.abs(new Date(b.at).getTime() - holdTime))[0];
+    if (byMover && Math.abs(new Date(byMover.at).getTime() - holdTime) < 2 * DAY) {
+      chosen = byMover;
+    }
+    if (!chosen) {
+      chosen = newestFirst(ticketComments.filter((comment) => new Date(comment.at).getTime() <= holdTime + 10 * 60000))[0] || null;
+    }
+  }
+  if (!chosen) {
+    chosen = newestFirst(ticketComments.filter((comment) => /on hold/i.test(comment.body)))[0] || null;
+  }
+  if (!chosen) {
+    return null;
+  }
+  return { text: firstSentence(chosen.body), full: `${chosen.author} · ${shortDate(chosen.at)}\n\n${chosen.body.trim().slice(0, 1500)}`, url: chosen.url };
+};
+
+const prFacts = (pr) => {
+  if (!pr) {
+    return { 'pr.open': false, 'pr.merged': false };
+  }
+  return {
+    'pr.open': pr.state === 'OPEN',
+    'pr.merged': pr.state === 'MERGED',
+    'pr.number': pr.pr,
+    'pr.checks': pr.checks || null,
+    'pr.review': pr.review ? pr.review.toLowerCase() : 'none',
+    'pr.base': pr.base || null,
+    'pr.unanswered': Boolean(pr.unanswered),
+    'pr.commenter': pr.last_comment_by || null,
+  };
+};
+
+const commentFacts = (mentions) => {
+  const newest = mentions[mentions.length - 1];
+  return {
+    'comment.mentions_me': Boolean(newest),
+    'comment.is_question': newest ? newest.question : null,
+    'comment.author': newest ? newest.comment.author : null,
+    unanswered_count: mentions.length,
+  };
+};
+
+/** The facts of one failing workflow run (RMA-152); the ticket and PR facts are missing, so ticket rows never match it. */
+export const runFacts = (run) => ({
+  connector: run.source || null,
+  'run.failed': Boolean(run.failed),
+  'run.workflow': run.workflow,
+  'run.branch': run.branch,
+  'run.mine': Boolean(run.mine),
+});
+
+/** The facts of one ticket with its chosen PR, its comments and its open mentions of you (oldest first); the hold reason is returned whole for the row's link and tooltip. */
+export const ticketFacts = (ticket, pr, { myName, rules, comments = [], mentions = [] }) => {
+  const group = statusGroupOf(ticket, rules);
+  const reason = group === 'on_hold' ? holdReason(comments, ticket) : null;
+  const facts = {
+    connector: ticket.source || null,
+    'ticket.key': ticket.key,
+    'ticket.status': group,
+    'ticket.status_name': ticket.status,
+    'ticket.assignee': myName && ticket.assignee === myName ? 'me' : ticket.assignee || null,
+    'ticket.done': ticket.status_category === 'done',
+    'ticket.started': ticket.status_category === 'indeterminate',
+    'ticket.hold_reason': reason ? reason.text : null,
+    ...prFacts(pr),
+    ...commentFacts(mentions),
+  };
+  return { facts, reason };
+};