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

package/lib/workspace.mjs

@@ -0,0 +1,294 @@
+/** One workspace: polls its connector entries, stores each result by source, merges them by kind, evaluates the rules once per version and notifies. */
+import { openStore } from './store.mjs';
+import { compileRules, turnRows, feedRows, myMoves, isHandled, withHandled, turnCounts, ticketEvents } from './rules.mjs';
+import { makeKeyFinder, nowIso, daysAgoIso, unionCapped, DAY } from './text.mjs';
+import { buildHandOff, snapshotOf, renderHandOff, frameHandOff } from './handoff.mjs';
+import { notify as desktopNotify } from './notify.mjs';
+import { DEFAULT_LIMITS, nextFails, assess, transition } from './health.mjs';
+import { paletteFrom, derivedSeed } from './palette.mjs';
+import { CONNECTORS, connectorSummaries } from '../connectors/index.mjs';
+import { RateLimited } from './http-client.mjs';
+const KINDS = ['tickets', 'comments', 'prs', 'activity', 'asks', 'runs'];
+
+const stamp = (result, sourceId) => {
+  const stamped = { ...result };
+  for (const kind of KINDS) {
+    stamped[kind] = (result[kind] || []).map((item) => ({ ...item, source: sourceId }));
+  }
+  return stamped;
+};
+
+export const createWorkspace = (definition, { dataDir, historyDays, http, secrets, limits = () => DEFAULT_LIMITS, notify = desktopNotify }) => {
+  const store = openStore(dataDir, definition.id);
+  const rules = compileRules(definition.rules);
+  const keyOf = makeKeyFinder(definition.key_pattern);
+  const seed = definition.theme?.seed || definition.derived_seed || derivedSeed(definition.id);
+  const theme = paletteFrom(seed, definition.theme?.accent);
+  const caches = {};
+  const listeners = new Set();
+  let digest = '';
+  let derived = null;
+  let freshAt = '';
+  const startedAt = nowIso();
+
+  const sources = () => Object.values(store.state.sources);
+  const merged = () => Object.fromEntries(KINDS.map((kind) => [kind, sources().flatMap((source) => source[kind] || [])]));
+  const me = () => Object.fromEntries(Object.entries(store.state.sources).map(([id, source]) => [id, source.me || '']));
+  const ticketUrl = (key) => {
+    const base = sources().map((source) => source.ticket_base).find(Boolean);
+    return base ? `${base}${key}` : '';
+  };
+
+  const rows = () => {
+    const day = nowIso().slice(0, 10);
+    if (!derived || derived.version !== store.state.version || derived.day !== day) {
+      const sources = merged();
+      const state = { ...sources, events: store.state.events };
+      const context = { me: me(), rules, historyDays, ticketUrl };
+      derived = { version: store.state.version, day, turn: turnRows(sources, context), feed: feedRows(state, context) };
+    }
+    return derived;
+  };
+
+  const emit = () => {
+    const message = { ws: definition.id, version: store.state.version, polled_at: store.state.polled_at, open_moves: myMoves(rows().turn, store.marks).length };
+    for (const listener of listeners) {
+      listener(message);
+    }
+  };
+
+  const notifyNewMoves = () => {
+    const moves = myMoves(rows().turn, store.marks);
+    const known = new Set(store.marks.notified);
+    const fresh = moves.filter((move) => !known.has(move.row_id));
+    if (!fresh.length) {
+      return;
+    }
+    if (store.marks.notified_seeded) {
+      const title = fresh.length === 1 ? `${definition.name}: your move on ${fresh[0].key}` : `${definition.name}: ${fresh.length} new items are your move`;
+      notify(title, fresh.length === 1 ? fresh[0].next : fresh.slice(0, 3).map((move) => `${move.key} — ${move.next}`).join('; '));
+    }
+    store.marks.notified = unionCapped(store.marks.notified, fresh.map((move) => move.row_id));
+    store.saveMarks();
+  };
+
+  const health = () => assess({ fails: store.state.fails, freshAt: freshAt || startedAt, now: Date.now(), limits: limits(), sourceCount: definition.connectors.length });
+
+  let shownStreaks = '';
+
+  const checkHealth = () => {
+    const { alerts } = health();
+    const { raised, recovered, alerted } = transition(store.marks.health_alerted, alerts);
+    const streaks = alerts.filter((alert) => alert.id.startsWith('failing:')).map((alert) => alert.text).join('\n');
+    if (!raised.length && !recovered.length) {
+      if (streaks !== shownStreaks) {
+        shownStreaks = streaks;
+        store.state.version += 1;
+        emit();
+      }
+      return;
+    }
+    shownStreaks = streaks;
+    if (raised.length) {
+      notify(`${definition.name}: monitor needs attention`, raised.map((alert) => alert.text).join('; '));
+    } else if (!alerted.length) {
+      notify(`${definition.name}: monitor recovered`, 'Data is flowing again');
+    }
+    store.marks.health_alerted = alerted;
+    store.saveMarks();
+    store.state.version += 1;
+    emit();
+  };
+
+  const pollSource = async (entry) => {
+    const connector = CONNECTORS[entry.type];
+    if (!connector) {
+      return { errors: { [entry.id]: `Unknown connector type "${entry.type}"` } };
+    }
+    caches[entry.id] = caches[entry.id] || store.loadCache(entry.id);
+    try {
+      const result = await connector.poll({ settings: entry, http, secrets, cache: caches[entry.id], sinceIso: daysAgoIso(historyDays), historyDays, keyOf });
+      const errors = Object.fromEntries(Object.entries(result.errors || {}).map(([part, message]) => [`${entry.id}.${part}`, message]));
+      return { data: stamp(result, entry.id), errors };
+    } catch (error) {
+      const rateLimited = error instanceof RateLimited;
+      return { errors: { [entry.id]: `${rateLimited ? 'rate limited' : error.name}: ${error.message}` }, rateLimited };
+    }
+  };
+
+  const saveCaches = () => {
+    const keysByEntry = Object.fromEntries(definition.connectors.map((entry) => [entry.id, CONNECTORS[entry.type]?.persistedCache || []]));
+    store.saveCaches(caches, keysByEntry);
+  };
+
+  const poll = async () => {
+    expireHandled();
+    const outcomes = await Promise.all(definition.connectors.map(pollSource));
+    const state = store.state;
+    const errors = {};
+    const ticketsBefore = merged().tickets;
+    definition.connectors.forEach((entry, index) => {
+      const outcome = outcomes[index];
+      Object.assign(errors, outcome.errors);
+      if (outcome.data) {
+        state.sources[entry.id] = outcome.data;
+      }
+    });
+    for (const id of Object.keys(state.sources)) {
+      if (!definition.connectors.some((entry) => entry.id === id)) {
+        delete state.sources[id];
+      }
+    }
+    if (ticketsBefore.length) {
+      state.events = [...ticketEvents(ticketsBefore, merged().tickets), ...state.events].slice(0, 500);
+    }
+    state.errors = errors;
+    state.polled_at = nowIso();
+    if (outcomes.some((outcome) => outcome.data)) {
+      freshAt = state.polled_at;
+    }
+    const fails = nextFails(state.fails, definition.connectors.map((entry, index) => ({ id: entry.id, failed: Object.keys(outcomes[index].errors).length > 0 })));
+    const failsChanged = JSON.stringify(fails) !== JSON.stringify(state.fails);
+    state.fails = fails;
+    const next = JSON.stringify([state.sources, state.errors]);
+    if (next !== digest) {
+      digest = next;
+      state.version += 1;
+      store.saveState();
+      if (outcomes.some((outcome) => outcome.data)) {
+        notifyNewMoves();
+        store.marks.notified_seeded = true;
+        store.saveMarks();
+      }
+    } else if (failsChanged) {
+      store.saveState();
+    }
+    if (outcomes.some((outcome) => outcome.data)) {
+      saveCaches();
+    }
+    checkHealth();
+    emit();
+    return { errors, rateLimited: outcomes.some((outcome) => outcome.rateLimited) };
+  };
+
+  const quickLinks = () => {
+    const derived = definition.connectors.flatMap((entry) => (CONNECTORS[entry.type]?.links ? CONNECTORS[entry.type].links(entry) : []));
+    const own = definition.links || [];
+    const seen = new Set();
+    return [...own, ...derived].filter((link) => !seen.has(link.url) && seen.add(link.url));
+  };
+
+  const expireHandled = () => {
+    const limit = Date.now() - 7 * DAY;
+    let changed = false;
+    for (const [rowId, at] of Object.entries(store.marks.handled)) {
+      if (new Date(at).getTime() < limit) {
+        delete store.marks.handled[rowId];
+        changed = true;
+      }
+    }
+    if (changed) {
+      store.saveMarks();
+    }
+  };
+
+  const identity = () => ({
+    id: definition.id, name: definition.name, key_pattern: definition.key_pattern, links: quickLinks(),
+    connectors: connectorSummaries(definition.connectors),
+    open_moves: myMoves(rows().turn, store.marks).length,
+  });
+
+  const describe = () => ({ ...identity(), theme, theme_seed: seed });
+
+  const todosWithLinks = () => store.todos.map((todo) => ({ ...todo, ticket_url: todo.key ? ticketUrl(todo.key) : '' }));
+
+  /** The part of the snapshot a marks write changes: the marks, the rows with their handled flags and the counts. */
+  const marked = () => ({ marks: store.marks, turn: withHandled(rows().turn, store.marks), counts: turnCounts(rows().turn, store.marks) });
+
+  const snapshot = (full) => ({
+    version: store.state.version, polled_at: store.state.polled_at, errors: store.state.errors, health: health(), me: me(),
+    ...marked(), feed: rows().feed, todos: todosWithLinks(), workspace: describe(),
+    ...(full ? { ...merged(), events: store.state.events } : {}),
+  });
+
+  const handOffSource = () => ({
+    data: merged(), turn: rows().turn, feed: rows().feed, workspace: describe(), rules: definition.rules,
+    moves: myMoves(rows().turn, store.marks), todos: todosWithLinks().filter((todo) => !todo.done), errors: store.state.errors,
+    handled: (row) => isHandled(row, store.marks),
+  });
+  const handOff = (kind, ref) => buildHandOff(kind, ref, handOffSource());
+  const handOffBody = (kind, ref) => {
+    const context = handOff(kind, ref);
+    return context ? renderHandOff(kind, context) : null;
+  };
+  const handOffText = (kind, ref) => {
+    const body = handOffBody(kind, ref);
+    return body && frameHandOff(definition.name, [body]);
+  };
+  const handOffSnapshot = (kind, ref) => snapshotOf(kind, ref, handOffSource());
+
+  const summary = () => {
+    const seen = new Set(store.marks.seen);
+    const unread = rows().feed.filter((item) => !seen.has(item.id) && new Date(item.at).getTime() > store.marks.base).length;
+    return { ...identity(), moves: myMoves(rows().turn, store.marks), new_events: unread, todos: todosWithLinks().filter((todo) => !todo.done), polled_at: store.state.polled_at, errors: store.state.errors, health: health() };
+  };
+
+  const updateMarks = (body) => {
+    const marks = store.marks;
+    if (body.seen) {
+      marks.seen = unionCapped(marks.seen, body.seen);
+    }
+    if ('base' in body) {
+      marks.base = body.base;
+    }
+    for (const [rowId, value] of Object.entries(body.handled || {})) {
+      if (value === null) {
+        delete marks.handled[rowId];
+      } else {
+        marks.handled[rowId] = value;
+      }
+    }
+    store.saveMarks();
+    emit();
+    return marked();
+  };
+
+  const addTodo = (body) => {
+    const text = String(body.text).trim().slice(0, 500);
+    store.todos.unshift({ id: `t${Date.now()}`, text, key: body.key || keyOf(text), created: nowIso(), by: String(body.by || 'you').slice(0, 20), done: null });
+  };
+
+  const changeTodo = (todo, body) => {
+    switch (body.action) {
+      case 'done':
+        todo.done = nowIso();
+        return true;
+      case 'undo':
+        todo.done = null;
+        return true;
+      case 'delete':
+        store.todos.splice(store.todos.indexOf(todo), 1);
+        return true;
+      case 'edit':
+        if (!String(body.text || '').trim()) {
+          return false;
+        }
+        todo.text = String(body.text).trim().slice(0, 500);
+        todo.key = keyOf(todo.text) || todo.key || '';
+        return true;
+      default:
+        return false;
+    }
+  };
+
+  const saveTodos = () => {
+    store.saveTodos();
+    store.state.version += 1;
+    emit();
+  };
+
+  return {
+    id: definition.id, name: definition.name, rulesTable: rules.table, store, poll, snapshot, summary, describe, checkHealth, handOff, handOffBody, handOffText, handOffSnapshot, updateMarks, addTodo, changeTodo, saveTodos,
+    subscribe: (listener) => { listeners.add(listener); return () => listeners.delete(listener); },
+  };
+};

package/open.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# Opens the monitor as its own Chrome or Edge app window at the remembered size, or in a browser tab with --browser or when neither is installed.
+port=${WHOSE_TURN_PORT:-8765}
+base=http://127.0.0.1:$port
+width=1500
+height=950
+
+size=$(curl -fs --max-time 1 "$base/api/window" 2>/dev/null)
+[[ $size =~ \"width\":([0-9]+) ]] && width=${BASH_REMATCH[1]}
+[[ $size =~ \"height\":([0-9]+) ]] && height=${BASH_REMATCH[1]}
+
+tab() {
+  if [[ $(uname) == Darwin ]]; then open "$base/"; else xdg-open "$base/"; fi
+}
+
+if [[ $1 == --browser ]]; then
+  tab
+  exit
+fi
+
+url="$base/?mode=app"
+size_flag=--window-size=$width,$height
+
+if [[ $(uname) == Darwin ]]; then
+  if open -Ra "Google Chrome" 2>/dev/null; then
+    open -na "Google Chrome" --args --app="$url" "$size_flag"
+  else
+    tab
+  fi
+  exit
+fi
+
+for browser in google-chrome chromium chromium-browser microsoft-edge; do
+  if command -v "$browser" >/dev/null; then
+    "$browser" --app="$url" "$size_flag" >/dev/null 2>&1 &
+    disown
+    exit
+  fi
+done
+tab

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "whose-turn",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0-alpha.3",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aquivalabs/whose-turn.git"
+  },
+  "files": [
+    "server.mjs",
+    "lib/",
+    "connectors/",
+    "dist/",
+    "install.sh",
+    "open.sh",
+    "config.example.json",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Local monitor that answers what is waiting on you across Jira, GitHub and Linear.",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "prepare": "git config core.hooksPath .githooks 2>/dev/null || true",
+    "start": "node server.mjs",
+    "dev": "WHOSE_TURN_DATA=.users-files/dev WHOSE_TURN_PORT=8766 node server.mjs",
+    "test": "node --experimental-strip-types --test \"test/**/*.test.mjs\"",
+    "dev:web": "vite",
+    "build": "vue-tsc --noEmit && vite build",
+    "typecheck": "vue-tsc --noEmit && tsc -p tsconfig.server.json",
+    "lint": "eslint web/src lib connectors server.mjs test",
+    "lint:style": "stylelint \"web/src/**/*.{vue,css}\"",
+    "format": "prettier --write web/src",
+    "check": "npm run typecheck && npm run lint && npm run lint:style && npm test && npm run test:web",
+    "test:web": "vitest run"
+  },
+  "bin": {
+    "whose-turn": "server.mjs"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@testing-library/dom": "10.4.2",
+    "@testing-library/vue": "8.1.0",
+    "@types/node": "22.19.19",
+    "@vitejs/plugin-vue": "^5.2.0",
+    "@vue/test-utils": "2.5.1",
+    "@vueuse/core": "15.0.0",
+    "eslint": "10.13.0",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-plugin-vue": "10.11.1",
+    "happy-dom": "21.0.4",
+    "postcss-html": "2.0.0",
+    "prettier": "3.9.10",
+    "stylelint": "17.16.0",
+    "stylelint-config-html": "2.0.0",
+    "stylelint-config-standard": "40.0.0",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.71.2",
+    "vite": "^6.0.0",
+    "vitest": "5.1.0",
+    "vue": "^3.5.0",
+    "vue-eslint-parser": "10.4.1",
+    "vue-tsc": "3.3.13"
+  }
+}

package/server.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+/** Whose Turn server: loads the workspace config, polls every workspace on one loop with rate-limit backoff, checks data health on a timer, serves the window and the local API. */
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadConfig, saveWorkspaces, normaliseWorkspaces } from './lib/config.mjs';
+import { createHttpClient } from './lib/http-client.mjs';
+import { nextDelay } from './lib/backoff.mjs';
+import { createSecrets } from './lib/secrets.mjs';
+import { createWorkspace } from './lib/workspace.mjs';
+import { createRegistry } from './lib/registry.mjs';
+import { openInbox } from './lib/inbox.mjs';
+import { openReports } from './lib/feedback.mjs';
+import { startApi } from './lib/api.mjs';
+import { notify } from './lib/notify.mjs';
+import { createUpdater, restartServer, runsInstalled } from './lib/update.mjs';
+
+const appDir = dirname(fileURLToPath(import.meta.url));
+const http = createHttpClient();
+const first = loadConfig();
+const secrets = createSecrets(first.dataDir);
+const inbox = openInbox(first.dataDir);
+const reports = openReports(first.dataDir);
+const { version } = JSON.parse(readFileSync(join(appDir, 'package.json'), 'utf8'));
+let server;
+const updater = createUpdater({
+  http,
+  dataDir: first.dataDir,
+  version,
+  installed: runsInstalled(appDir, first.dataDir),
+  notify,
+  registry: process.env.WHOSE_TURN_REGISTRY,
+  npm: process.env.WHOSE_TURN_NPM,
+  restart: () => restartServer({ server, root: appDir, dataDir: first.dataDir }),
+});
+let pollSeconds = first.pollSeconds;
+/** @type {{ stale_minutes: number, failing_polls: number }} */
+let healthLimits = /** @type {any} */ (first.health);
+
+const registry = createRegistry({
+  load: () => {
+    const config = loadConfig();
+    pollSeconds = config.pollSeconds;
+    healthLimits = /** @type {any} */ (config.health);
+    return config;
+  },
+  save: (rawWorkspaces) => saveWorkspaces(first.configFile, rawWorkspaces),
+  normalise: (rawWorkspaces) => normaliseWorkspaces(rawWorkspaces).workspaces,
+  build: (definition, config) => createWorkspace(definition, { dataDir: config.dataDir, historyDays: config.historyDays, http, secrets, limits: () => healthLimits }),
+});
+
+let wake = null;
+const requestPoll = () => wake?.();
+const sleep = (seconds) => new Promise((resolve) => {
+  const timer = setTimeout(resolve, seconds * 1000);
+  wake = () => { clearTimeout(timer); resolve(); };
+});
+
+const pollLoop = async () => {
+  let delay = pollSeconds;
+  for (;;) {
+    const outcomes = await Promise.all(registry.workspaces.map((workspace) => workspace.poll()));
+    delay = nextDelay(outcomes, delay, pollSeconds);
+    await sleep(delay);
+  }
+};
+
+const saveConfig = async (rawWorkspaces) => {
+  const created = await registry.save(rawWorkspaces);
+  await Promise.all(created.map((workspace) => workspace.poll()));
+};
+
+try {
+  server = await startApi({ port: first.port, appDir, registry, requestPoll, saveConfig, secrets, inbox, http, reports, dataDir: first.dataDir, updater });
+} catch (error) {
+  console.error(error.message);
+  process.exit(1);
+}
+console.log(`whose-turn ${version} on http://127.0.0.1:${first.port} · data ${first.dataDir} · workspaces ${registry.workspaces.map((workspace) => workspace.id).join(', ') || 'none'}`);
+for (const problem of registry.problems) {
+  console.error(problem);
+}
+pollLoop();
+updater.start();
+
+const HEALTH_TICK = 30000;
+let lastTick = Date.now();
+setInterval(() => {
+  const slept = Date.now() - lastTick > 3 * HEALTH_TICK;
+  lastTick = Date.now();
+  if (slept) {
+    requestPoll();
+    return;
+  }
+  registry.workspaces.forEach((workspace) => workspace.checkHealth());
+}, HEALTH_TICK).unref();