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

package/lib/api.mjs

@@ -0,0 +1,399 @@
+/** The local HTTP API and the window's static files; every error leaves as the google.rpc.Status envelope from lib/errors.mjs. */
+import { createServer } from 'node:http';
+import { join } from 'node:path';
+import { createStatic } from './static.mjs';
+import { ApiError, toApiError } from './errors.mjs';
+import { connectorCatalogue, secretTarget, secretsRequired } from '../connectors/index.mjs';
+import { entryShapeViolations, normaliseWorkspaces, WORKSPACE_FIELDS } from './config.mjs';
+import { FACTS } from './facts.mjs';
+import { createFeedback, isConfigured } from './feedback.mjs';
+import { composeIssue, DEFAULT_COMPOSER } from './compose.mjs';
+import { readSize, saveSize, checkMode, spawnOpener } from './window.mjs';
+import { frameHandOff } from './handoff.mjs';
+
+const send = (response, code, body, contentType = 'application/json', cacheControl = 'no-store') => {
+  const data = Buffer.isBuffer(body) ? body : Buffer.from(contentType === 'application/json' ? JSON.stringify(body) : body);
+  response.writeHead(code, { 'Content-Type': `${contentType}; charset=utf-8`, 'Cache-Control': cacheControl, 'Content-Length': data.length });
+  response.end(data);
+};
+
+const readBody = (request) => new Promise((resolve, reject) => {
+  const chunks = [];
+  request.on('data', (chunk) => chunks.push(chunk));
+  request.on('end', () => {
+    try {
+      resolve(chunks.length ? JSON.parse(Buffer.concat(chunks).toString('utf8')) : {});
+    } catch {
+      reject(new ApiError('INVALID_BODY'));
+    }
+  });
+  request.on('error', reject);
+});
+
+const assertLocal = (request, port) => {
+  const allowedHosts = [`127.0.0.1:${port}`, `localhost:${port}`];
+  if (!allowedHosts.includes(request.headers.host || '')) {
+    throw new ApiError('FORBIDDEN_ORIGIN', { host: request.headers.host || '' });
+  }
+  const origin = request.headers.origin;
+  if (origin && !allowedHosts.map((host) => `http://${host}`).includes(origin)) {
+    throw new ApiError('FORBIDDEN_ORIGIN', { origin });
+  }
+  if (request.method === 'POST' && !/^application\/json/.test(request.headers['content-type'] || '')) {
+    throw new ApiError('INVALID_BODY', { content_type: request.headers['content-type'] || '' });
+  }
+};
+
+const CLOCK_SKEW_MS = 60 * 1000;
+
+/** Names the first wrong field in a marks write, or returns '' when the body is fine. */
+const marksProblem = (body) => {
+  if (body.seen !== undefined && !(Array.isArray(body.seen) && body.seen.every((id) => typeof id === 'string'))) {
+    return 'seen must be a list of strings';
+  }
+  if ('base' in body && !(Number.isFinite(body.base) && body.base <= Date.now() + CLOCK_SKEW_MS)) {
+    return 'base must be a number of milliseconds, not in the future';
+  }
+  if (body.handled === undefined) {
+    return '';
+  }
+  if (!body.handled || typeof body.handled !== 'object' || Array.isArray(body.handled)) {
+    return 'handled must map row ids to an ISO date or null';
+  }
+  const wrong = Object.entries(body.handled).find(([, value]) => value !== null && !(typeof value === 'string' && Number.isFinite(Date.parse(value))));
+  return wrong ? `handled.${wrong[0]} must be an ISO date or null` : '';
+};
+
+const aggregateSummary = (workspaces) => {
+  const parts = workspaces.map((workspace) => workspace.summary());
+  const errors = {};
+  for (const part of parts) {
+    for (const [source, message] of Object.entries(part.errors)) {
+      errors[parts.length > 1 ? `${part.id}.${source}` : source] = message;
+    }
+  }
+  return {
+    moves: parts.flatMap((part) => part.moves.map((move) => ({ ...move, ws: part.id }))),
+    new_events: parts.reduce((sum, part) => sum + part.new_events, 0),
+    todos: parts.flatMap((part) => part.todos.map((todo) => ({ ...todo, ws: part.id }))),
+    polled_at: parts.map((part) => part.polled_at).filter(Boolean).sort()[0] || '',
+    errors,
+    health: {
+      ok: parts.every((part) => part.health.ok),
+      alerts: parts.flatMap((part) => part.health.alerts.map((alert) => (parts.length > 1 ? `${part.name}: ${alert.text}` : alert.text))),
+    },
+    workspaces: parts,
+  };
+};
+
+const OPEN_COOLDOWN_MS = 5000;
+
+export const startApi = async ({ port, appDir, registry, requestPoll, saveConfig, secrets, inbox, http, reports, dataDir, opener = spawnOpener(appDir) }) => {
+  const windowFile = createStatic(join(appDir, 'dist'));
+  const feedbackCache = {};
+  const pick = (id) => {
+    const workspaces = registry.workspaces;
+    if (!workspaces.length) {
+      throw new ApiError('NO_WORKSPACE');
+    }
+    if (!id) {
+      return workspaces[0];
+    }
+    const found = workspaces.find((workspace) => workspace.id === id);
+    if (!found) {
+      throw new ApiError('NO_SUCH_WORKSPACE', { ws: id });
+    }
+    return found;
+  };
+  // README.md § API; RMA-115
+  const pickForWrite = (id) => {
+    if (!id) {
+      throw new ApiError('INVALID_ARGUMENT', { detail: 'ws names the workspace this write belongs to' });
+    }
+    return pick(id);
+  };
+
+  const stream = (response) => {
+    response.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-store' });
+    const write = (event) => response.write(`data: ${JSON.stringify(event)}\n\n`);
+    for (const workspace of registry.workspaces) {
+      write({ ws: workspace.id, version: workspace.store.state.version, polled_at: workspace.store.state.polled_at });
+    }
+    const unsubscribe = registry.subscribe(write);
+    const keepAlive = setInterval(() => response.write(': keep-alive\n\n'), 25000);
+    response.on('close', () => {
+      clearInterval(keepAlive);
+      unsubscribe();
+    });
+  };
+
+  const handleGet = async (url, request, response) => {
+    const file = url.pathname.startsWith('/api/') ? null : await windowFile(url.pathname);
+    if (file) {
+      return send(response, 200, file.body, file.type, file.cacheControl);
+    }
+    if (url.pathname === '/api/workspaces') {
+      return send(response, 200, registry.workspaces.map((workspace) => workspace.describe()));
+    }
+    if (url.pathname === '/api/state') {
+      if (!registry.workspaces.length) {
+        return send(response, 200, { workspaces: [], problems: registry.problems });
+      }
+      const workspace = pick(url.searchParams.get('ws'));
+      return send(response, 200, { ...workspace.snapshot(url.searchParams.get('full') === '1'), workspaces: registry.workspaces.map((item) => item.describe()), problems: registry.problems });
+    }
+    if (url.pathname === '/api/summary') {
+      return send(response, 200, { ...aggregateSummary(registry.workspaces), problems: registry.problems, handed: inbox.pending().length });
+    }
+    if (url.pathname === '/api/config') {
+      const tables = Object.fromEntries(registry.workspaces.map((workspace) => [workspace.id, workspace.rulesTable]));
+      return send(response, 200, { workspaces: registry.rawWorkspaces, problems: registry.problems, connectors: connectorCatalogue(), fields: WORKSPACE_FIELDS, facts: FACTS, tables, config_file: registry.configFile });
+    }
+    if (url.pathname === '/api/inbox') {
+      return send(response, 200, { items: inbox.pending(url.searchParams.get('consumer') || '') });
+    }
+    if (url.pathname === '/api/feedback') {
+      const id = url.searchParams.get('id');
+      if (id) {
+        return send(response, 200, { report: await reports.detail(reportDeps(), id) });
+      }
+      const list = await reports.states(reportDeps());
+      return send(response, 200, { configured: isConfigured(registry.feedback), project: registry.feedback ? registry.feedback.project : '', reports: list });
+    }
+    if (url.pathname === '/api/handoff') {
+      if (url.searchParams.get('all') === '1') {
+        return send(response, 200, frameHandOff('all workspaces', registry.workspaces.map((workspace) => workspace.handOffBody('workspace', workspace.id))), 'text/markdown');
+      }
+      const workspace = pick(url.searchParams.get('ws'));
+      const kind = url.searchParams.get('kind') || 'workspace';
+      const text = workspace.handOffText(kind, kind === 'workspace' ? workspace.id : url.searchParams.get('ref') || '');
+      if (!text) {
+        throw new ApiError('NOT_FOUND', { kind, ref: url.searchParams.get('ref') || '' });
+      }
+      return send(response, 200, text, 'text/markdown');
+    }
+    if (url.pathname === '/api/window') {
+      return send(response, 200, readSize(dataDir));
+    }
+    if (url.pathname === '/api/stream') {
+      return stream(response);
+    }
+    throw new ApiError('NOT_FOUND', { path: url.pathname });
+  };
+
+  const handleTodos = (workspace, body) => {
+    if (body.action === 'add') {
+      if (!String(body.text || '').trim()) {
+        throw new ApiError('INVALID_ARGUMENT', { detail: 'text is empty' }, [{ field: 'text', description: 'A to-do needs some text.' }]);
+      }
+      workspace.addTodo(body);
+    } else {
+      const todo = workspace.store.todos.find((item) => item.id === body.id);
+      if (!todo) {
+        throw new ApiError('NO_SUCH_TODO', { id: body.id || '' });
+      }
+      if (!workspace.changeTodo(todo, body)) {
+        throw new ApiError('UNKNOWN_ACTION', { action: body.action || '' });
+      }
+    }
+    workspace.saveTodos();
+    return workspace.store.todos;
+  };
+
+  const resolveSecrets = (workspaces, pending) => pending.map((item) => {
+    const workspace = workspaces.find((candidate) => candidate.id === item.ws);
+    const entry = workspace?.connectors.find((candidate) => candidate.id === item.connector);
+    const target = entry ? secretTarget(entry, item.key) : null;
+    if (!target || !String(item.value || '').trim()) {
+      throw new ApiError('INVALID_ARGUMENT', { detail: `no secret field ${item.key || ''} on connector ${item.connector || ''} of workspace ${item.ws || ''}, or the account for it is empty` });
+    }
+    return { ...target, value: String(item.value).trim() };
+  });
+
+  const handleConfig = async (body) => {
+    if (!Array.isArray(body.workspaces)) {
+      throw new ApiError('INVALID_ARGUMENT', { detail: 'workspaces must be a list' });
+    }
+    if (!body.workspaces.length) {
+      throw new ApiError('INVALID_ARGUMENT', { detail: 'keep at least one workspace' });
+    }
+    const shape = entryShapeViolations(body.workspaces);
+    if (shape.length) {
+      throw new ApiError('INVALID_CONFIG', { count: String(shape.length) }, shape);
+    }
+    const { workspaces, problems } = normaliseWorkspaces(body.workspaces);
+    if (problems.length) {
+      throw new ApiError('INVALID_CONFIG', { count: String(problems.length) }, problems);
+    }
+    const stored = resolveSecrets(workspaces, Array.isArray(body.secrets) ? body.secrets : []);
+    const currentEntries = normaliseWorkspaces(registry.rawWorkspaces).workspaces.flatMap((workspace) => workspace.connectors);
+    const missing = [];
+    for (const workspace of workspaces) {
+      for (const entry of workspace.connectors) {
+        for (const key of secretsRequired(currentEntries, entry)) {
+          const supplied = (body.secrets || []).some((item) => item.ws === workspace.id && item.connector === entry.id && item.key === key && String(item.value || '').trim());
+          if (!supplied) {
+            missing.push(`Workspace "${workspace.id}", connector "${entry.id}": the ${key} must be entered again because its account, store entry or endpoint changed.`);
+          }
+        }
+      }
+    }
+    if (missing.length) {
+      throw new ApiError('INVALID_CONFIG', { count: String(missing.length) }, missing);
+    }
+    for (const secret of stored) {
+      await secrets.set(secret.service, secret.account, secret.value);
+    }
+    await saveConfig(body.workspaces);
+    return { workspaces: registry.workspaces.map((workspace) => workspace.describe()), problems: registry.problems, secrets_stored: stored.map(({ service, account }) => ({ service, account })) };
+  };
+
+  const handleSecret = async (body) => {
+    const service = String(body.service || '').trim();
+    const account = String(body.account || '').trim();
+    const value = String(body.value || '').trim();
+    if (!/^[\w.-]{1,80}$/.test(service) || !account || !value) {
+      throw new ApiError('INVALID_ARGUMENT', { detail: 'service, account and value are required' });
+    }
+    await secrets.set(service, account, value);
+    return { ok: true, service, account };
+  };
+
+  const withContext = (item) => {
+    const workspace = registry.workspaces.find((candidate) => candidate.id === item.ws);
+    return { ...item, context: workspace ? workspace.handOff(item.kind, item.ref) : null };
+  };
+
+  const handleInbox = (body) => {
+    if (body.action === 'clear') {
+      inbox.clear();
+      return { items: [] };
+    }
+    if (body.action === 'take') {
+      const consumer = String(body.consumer || '').trim();
+      if (!consumer) {
+        throw new ApiError('INVALID_ARGUMENT', { detail: 'consumer names who takes the items' });
+      }
+      return { items: inbox.take(consumer).map(withContext) };
+    }
+    const workspace = pickForWrite(body.ws);
+    const kind = String(body.kind || 'workspace');
+    const ref = kind === 'workspace' ? workspace.id : String(body.ref || '');
+    const snapshot = workspace.handOffSnapshot(kind, ref);
+    if (!snapshot) {
+      throw new ApiError('NOT_FOUND', { kind, ref });
+    }
+    return { item: inbox.add({ ws: workspace.id, ws_name: workspace.name, kind, ref, snapshot }) };
+  };
+
+  const reportDeps = () => ({ settings: registry.feedback, secrets, http });
+
+  let lastRemark = { text: '', at: 0 };
+  const handleFeedback = async (body) => {
+    if (!isConfigured(registry.feedback)) {
+      throw new ApiError('NOT_CONFIGURED');
+    }
+    const remark = typeof body.text === 'string' ? body.text.trim() : '';
+    if (!remark && !String(body.title || '').trim()) {
+      throw new ApiError('INVALID_ARGUMENT', { detail: 'text is empty' }, [{ field: 'text', description: 'Write the remark, or pass a title.' }]);
+    }
+    if (remark && remark === lastRemark.text && Date.now() - lastRemark.at < 60_000) {
+      throw new ApiError('INVALID_ARGUMENT', { detail: 'the same remark was just sent' });
+    }
+    if (remark) {
+      lastRemark = { text: remark, at: Date.now() };
+    }
+    let context = null;
+    if (body.ws && body.kind_ref) {
+      const workspace = pick(body.ws);
+      context = workspace.handOffText(body.kind_ref.kind, body.kind_ref.ref);
+    }
+    try {
+      const composer = registry.feedback && registry.feedback.composer && registry.feedback.composer.command ? registry.feedback.composer : DEFAULT_COMPOSER;
+      const shaped = remark ? await composeIssue(remark, { about: context || '', composer, bugWords: registry.feedback && registry.feedback.bug_words }) : { kind: body.kind, title: body.title, body: body.body, composed_by: body.from || 'caller' };
+      const issue = await createFeedback({ settings: registry.feedback, secrets, http, cache: feedbackCache, reports }, { kind: shaped.kind, title: shaped.title, body: shaped.body, from: body.from, context: context || body.context || null });
+      return { issue, composed_by: shaped.composed_by, reports: await reports.states(reportDeps()) };
+    } catch (error) {
+      lastRemark = { text: '', at: 0 };
+      throw error;
+    }
+  };
+
+  const lastOpen = new Map();
+
+  const handlePost = async (url, request, response) => {
+    const body = await readBody(request);
+    if (url.pathname === '/api/feedback') {
+      return send(response, 200, await handleFeedback(body));
+    }
+    if (url.pathname === '/api/inbox') {
+      return send(response, 200, handleInbox(body));
+    }
+    if (url.pathname === '/api/config') {
+      return send(response, 200, await handleConfig(body));
+    }
+    if (url.pathname === '/api/secrets') {
+      return send(response, 200, await handleSecret(body));
+    }
+    if (url.pathname === '/api/window') {
+      return send(response, 200, saveSize(dataDir, body));
+    }
+    if (url.pathname === '/api/open') {
+      const mode = checkMode(body.mode);
+      const wait = OPEN_COOLDOWN_MS - (Date.now() - (lastOpen.get(mode) || -Infinity));
+      if (wait > 0) {
+        throw new ApiError('OPEN_TOO_SOON', { retry_after_seconds: Math.ceil(wait / 1000) });
+      }
+      lastOpen.set(mode, Date.now());
+      opener({ mode, port });
+      return send(response, 200, { ok: true });
+    }
+    if (url.pathname === '/api/refresh') {
+      requestPoll();
+      return send(response, 200, { ok: true });
+    }
+    const workspace = pickForWrite(body.ws);
+    if (url.pathname === '/api/marks') {
+      const detail = marksProblem(body);
+      if (detail) {
+        throw new ApiError('INVALID_ARGUMENT', { detail });
+      }
+      return send(response, 200, workspace.updateMarks(body));
+    }
+    if (url.pathname === '/api/todos') {
+      return send(response, 200, handleTodos(workspace, body));
+    }
+    throw new ApiError('NOT_FOUND', { path: url.pathname });
+  };
+
+  const server = createServer(async (request, response) => {
+    const url = new URL(request.url, `http://127.0.0.1:${port}`);
+    try {
+      assertLocal(request, port);
+      if (request.method === 'GET') {
+        await handleGet(url, request, response);
+      } else if (request.method === 'POST') {
+        await handlePost(url, request, response);
+      } else {
+        response.setHeader('Allow', 'GET, POST');
+        throw new ApiError('METHOD_NOT_ALLOWED', { method: request.method || '' });
+      }
+    } catch (error) {
+      if (!(error instanceof ApiError)) {
+        console.error(error);
+      }
+      const apiError = toApiError(error);
+      send(response, apiError.code, apiError.toEnvelope());
+    }
+  });
+  await new Promise((resolve, reject) => {
+    const refuse = (error) => reject(error.code === 'EADDRINUSE' ? new Error(`Port ${port} is already in use: stop the server holding it, or set WHOSE_TURN_PORT to a free port.`, { cause: error }) : error);
+    server.once('error', refuse);
+    server.listen(port, '127.0.0.1', () => {
+      server.off('error', refuse);
+      resolve(undefined);
+    });
+  });
+  port = /** @type {import('node:net').AddressInfo} */ (server.address()).port;
+  return server;
+};

package/lib/backoff.mjs

@@ -0,0 +1,2 @@
+/** The next poll delay in seconds: doubled up to 15 minutes while any source is rate limited, else the normal interval. */
+export const nextDelay = (outcomes, delay, pollSeconds) => (outcomes.some((outcome) => outcome.rateLimited) ? Math.min(delay * 2, 15 * 60) : pollSeconds);

package/lib/compose.mjs

@@ -0,0 +1,67 @@
+/** Turns a remark into an issue (title, kind, body) with the user's own agent CLI, `claude -p` unless the config names another; falls back to the first line as the title. RMA-109. */
+import { execFile } from 'node:child_process';
+import { escapeRegex } from './text.mjs';
+import { untrustedBlock } from './handoff.mjs';
+
+const KINDS = ['bug', 'improvement', 'idea'];
+export const DEFAULT_COMPOSER = { command: 'claude', args: ['-p', '--output-format', 'json', '--model', 'claude-haiku-5-5'] };
+
+const PROMPT = (text, about) => `You turn a user's remark about a tool called Whose Turn (a local monitor of tickets and pull requests) into an issue for its backlog.
+Answer with one JSON object only, no prose, no code fence: {"title": string, "kind": "bug" | "improvement" | "idea", "body": string}.
+Rules: the title and the body are in English whatever language the remark is in; translate faithfully, keep every detail the user gave, add nothing the user did not say. The title is one line under 80 characters; kind is bug when something misbehaves, improvement when something that exists should be better, idea when it is new; the body restates the remark clearly and may end with one line "Context: …" taken from the context below if it helps a developer find the place, and, when the remark was not in English, with one line "Original: …" quoting it as written.
+Remark:
+${text}
+${about ? `\nContext of the window at that moment:\n${untrustedBlock(about.slice(0, 3000))}` : ''}`;
+
+const DEFAULT_BUG_WORDS = ['bug', 'broken', 'crash', 'error', 'fail', 'wrong'];
+const fallback = (text, bugWords) => {
+  const [first, ...rest] = String(text).trim().split('\n');
+  const words = [...DEFAULT_BUG_WORDS, ...[].concat(bugWords || [])].map(escapeRegex).join('|');
+  const kind = new RegExp(`(^|[^\\p{L}\\p{N}])(${words})`, 'iu').test(text) ? 'bug' : 'improvement';
+  return { title: first.trim().slice(0, 120), kind, body: rest.join('\n').trim(), composed_by: 'fallback' };
+};
+
+const issueFrom = (text) => {
+  const match = /\{[\s\S]*\}/.exec(text);
+  const issue = JSON.parse(match ? match[0] : text);
+  if (!issue.title || !KINDS.includes(issue.kind)) {
+    throw new Error('incomplete answer');
+  }
+  return { title: String(issue.title).slice(0, 120), kind: issue.kind, body: String(issue.body || '') };
+};
+
+const parse = (output, label) => {
+  let text = output;
+  try {
+    const payload = JSON.parse(output);
+    if (payload && typeof payload.result === 'string') {
+      text = payload.result;
+    } else if (payload && payload.title) {
+      return { ...issueFrom(output), composed_by: label };
+    }
+  } catch {
+    /* not a wrapper; the output is the answer itself */
+  }
+  return { ...issueFrom(text), composed_by: label };
+};
+
+const runCommand = (composer) => (prompt, timeoutMs) => new Promise((resolve, reject) => {
+  const child = execFile(composer.command, composer.args || [], { timeout: timeoutMs, maxBuffer: 1024 * 1024 }, (error, stdout) => (error ? reject(error) : resolve(stdout)));
+  child.stdin.end(prompt);
+});
+
+/** @param {string} text @param {{ about?: string, composer?: object, bugWords?: string[], run?: Function, timeoutMs?: number }} [options] */
+export const composeIssue = async (text, { about = '', composer = DEFAULT_COMPOSER, bugWords = [], run, timeoutMs = 45000 } = {}) => {
+  const clean = String(text || '').trim();
+  if (!clean) {
+    throw new Error('Write at least one line');
+  }
+  const args = composer.args || [];
+  const model = args[args.indexOf('--model') + 1];
+  const label = composer.label || (args.includes('--model') && model ? `${composer.command} ${model}` : composer.command);
+  try {
+    return parse(await (run || runCommand(composer))(PROMPT(clean, about), timeoutMs), label);
+  } catch {
+    return fallback(clean, bugWords);
+  }
+};