syndes 0.1.0 → 0.2.0

package/src/doctor.mjs

@@ -24,6 +24,8 @@ import { isHeld } from '../runtime/lock.mjs';
 import { describe as describeAuth } from '../dashboard/auth.mjs';
 import { probe } from '../notify/index.mjs';
 import { readJson, loadConfig } from '../runtime/config.mjs';
+import { isEnabled as sharingOn, teamConfig, loadState as teamState, readPool, poolRoot } from '../sync/index.mjs';
+import { identity } from '../runtime/identity.mjs';
 import { configFile } from '../runtime/paths.mjs';
 
 function versionOf(file) {
@@ -137,6 +139,34 @@ export async function diagnose({ deep = false } = {}) {
     checks.push(note('system unlock', `${lock.system.method} is available here — syndes lock system`));
   }
 
+  // ── Sharing ───────────────────────────────────────────────────────────────
+  if (!sharingOn()) {
+    checks.push(note('sharing', 'off — this machine reports only to itself'));
+  } else {
+    const state = teamState();
+    const peers = readPool();
+    const mine = peers.find((peer) => peer.deviceId === identity().deviceId);
+
+    checks.push(state.ok === false
+      ? fail('pool', `last exchange failed: ${String(state.error ?? 'unknown').slice(0, 80)}`, 'syndes team sync')
+      : pass('pool', `${teamConfig().transport} · ${displayPath(poolRoot())}`));
+
+    checks.push(mine
+      ? pass('your shelf', `${identity().name} · ${mine.rollups.size} day(s) published`)
+      : fail('your shelf', 'nothing of yours is in the pool yet', 'syndes team sync'));
+
+    // A peer whose shelf has gone quiet is the failure people misread as "they
+    // stopped working". Naming it here is cheaper than them guessing.
+    const stale = peers.filter((peer) => !peer.isMe && (!peer.lastSeen || Date.now() - peer.lastSeen > 6 * 3_600_000));
+    checks.push(stale.length
+      ? note('peers', `${peers.length - 1} other machine(s), ${stale.length} not synced in 6h: ${stale.map((p) => p.name).join(', ')}`)
+      : pass('peers', `${peers.length - 1} other machine(s), all current`));
+
+    checks.push(note('sharing scope', teamConfig().scope === 'detailed'
+      ? 'detailed — counts, tokens, hours, project ids and tool mix. Never prompt text.'
+      : 'summary — counts, tokens and hours only. No paths, no project ids, no prompt text.'));
+  }
+
   const config = readJson(configFile);
   if (config.exists && config.error) {
     checks.push(fail('config', `syndes.json does not parse: ${config.error}`, 'fix or delete it; defaults will be used'));

package/src/term.mjs

@@ -207,10 +207,50 @@ export function beat(ms = 90) {
   return new Promise((resolve) => { setTimeout(resolve, ms); });
 }
 
+/**
+ * Ask, and always come back with something.
+ *
+ * Two ways a question never gets answered, both of which used to hang forever:
+ *
+ *   • There is no terminal. Every caller of this function is interactive by
+ *     nature, so with no tty there is nobody to ask — and reading whatever
+ *     happens to be on a pipe as though a person typed it is worse than not
+ *     asking, particularly for the PIN prompt. This follows the rule the rest
+ *     of the codebase already keeps: a probe that cannot answer returns nothing
+ *     and the caller degrades, rather than "unsupported" and "broken" looking
+ *     alike. It is also the only DETERMINISTIC answer available. When stdin is
+ *     /dev/null — which is exactly what npm hands a postinstall — Node emits no
+ *     `end` and no `close` on it at all, so nothing short of a timeout would
+ *     ever notice, and a timeout in a prompt is a guess about how fast someone
+ *     types.
+ *
+ *   • The user pressed ctrl-D at a real prompt. readline's callback never
+ *     fires, so `close` is what settles it.
+ *
+ * Left unhandled, either one leaves the promise pending and Node exits mid
+ * install with "unsettled top-level await", which reads as a crash with no cause.
+ * An unanswered question resolves empty, and every caller already treats empty
+ * as "no answer given".
+ */
 export function ask(question, { silent = false } = {}) {
   return new Promise((resolve) => {
+    if (!process.stdin.isTTY || process.stdin.readableEnded || process.stdin.destroyed) {
+      resolve('');
+      return;
+    }
+
     const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
 
+    let settled = false;
+    const done = (answer) => {
+      if (settled) return;
+      settled = true;
+      try { rl.close(); } catch { /* already closing */ }
+      resolve(answer);
+    };
+    rl.on('close', () => done(''));
+    rl.on('error', () => done(''));
+
     if (silent) {
       // Echo off by hand: readline has no password mode, and a password printed
       // into a terminal that may be scrolled back or recorded is unacceptable.
@@ -220,13 +260,12 @@ export function ask(question, { silent = false } = {}) {
       rl.question('', (answer) => {
         rl.input.off('data', redraw);
         rl.output.write('\n');
-        rl.close();
-        resolve(answer);
+        done(answer);
       });
       return;
     }
 
-    rl.question(question, (answer) => { rl.close(); resolve(answer.trim()); });
+    rl.question(question, (answer) => done(answer.trim()));
   });
 }
 

package/sync/index.mjs

@@ -0,0 +1,257 @@
+/**
+ * The pool: publish our shelf, read everyone else's.
+ *
+ * This module is the whole of "sharing", and it is deliberately small because
+ * the hard parts were designed away rather than solved:
+ *
+ *   • Nothing is merged. Peer data is never appended to our chain — it is read
+ *     from the pool and displayed beside ours. The ledger keeps exactly one
+ *     writer, forever, which is the invariant everything else here rests on.
+ *   • Nothing conflicts. A device writes only its own shelf (see transport.mjs).
+ *   • Nothing sensitive travels. The unit of sharing is a sanitised rollup, not
+ *     a record (see share.mjs).
+ *
+ * A pull failure is not an error state. The pool is a cache of other people's
+ * numbers; when it cannot be reached, the last copy on disk is still true as of
+ * its own timestamp, and the UI says how old it is rather than going blank.
+ */
+
+import { mkdirSync, existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { teamDir, teamDeviceDir, teamStateFile, rollupFile, packageRoot } from '../runtime/paths.mjs';
+import { loadConfig, rawConfig, saveConfig, setPath, readJson } from '../runtime/config.mjs';
+import { identity } from '../runtime/identity.mjs';
+import { loadRollup, coveredDays } from '../analytics/rollup.mjs';
+import { localDay, shiftDay } from '../analytics/ranges.mjs';
+import { sanitise, manifestFor } from './share.mjs';
+import {
+  transportFor, listDevices, readJsonFile, writeJsonFile, removeFile,
+} from './transport.mjs';
+import { writeFileSync, renameSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { debug } from '../runtime/log.mjs';
+
+/**
+ * Where our own shelf lives inside the pool.
+ *
+ * Takes the root rather than assuming the default working copy: a folder pool
+ * IS the shared folder, and publishing into teamDir instead would write a
+ * perfectly correct shelf somewhere nobody is reading.
+ */
+function shelfOf(root, deviceId) {
+  return teamDeviceDir(root, deviceId);
+}
+
+export function teamConfig() {
+  return loadConfig().team ?? {};
+}
+
+export function isEnabled() {
+  const team = teamConfig();
+  return Boolean(team.enabled && team.transport);
+}
+
+// ── Setup ───────────────────────────────────────────────────────────────────
+
+/**
+ * Join or create a pool.
+ *
+ * @param {{transport: 'git'|'folder', repo: string, scope?: string}} options
+ */
+export function join_(options) {
+  const transport = transportFor(options.transport);
+  if (!transport) throw new Error(`unknown transport: ${options.transport}`);
+  if (!options.repo) throw new Error('a repository url or folder path is required');
+
+  const root = options.transport === 'folder' ? options.repo : teamDir;
+  mkdirSync(root, { recursive: true });
+
+  const started = transport.init(root, { repo: options.repo });
+  if (!started.ok) throw new Error(started.error ?? 'could not reach the pool');
+
+  const next = rawConfig();
+  setPath(next, 'team.enabled', true);
+  setPath(next, 'team.transport', options.transport);
+  setPath(next, 'team.repo', options.repo);
+  if (options.scope) setPath(next, 'team.scope', options.scope);
+  saveConfig(next);
+
+  return { root, transport: transport.id, describe: transport.describe(root) };
+}
+
+export function leave() {
+  const next = rawConfig();
+  setPath(next, 'team.enabled', false);
+  saveConfig(next);
+  return true;
+}
+
+/** The working copy for the configured transport. A folder pool IS the folder. */
+export function poolRoot() {
+  const team = teamConfig();
+  return team.transport === 'folder' && team.repo ? team.repo : teamDir;
+}
+
+// ── Publishing ──────────────────────────────────────────────────────────────
+
+/**
+ * Write our sanitised rollups onto our own shelf.
+ *
+ * Rewrites every day in the window rather than only today: a day that was still
+ * open at the last publish has since been finalised, and a stale copy of it in
+ * the pool would quietly under-report the person who left their laptop early.
+ *
+ * @returns {{written: number, removed: number, days: string[]}}
+ */
+export function publish({ root = poolRoot() } = {}) {
+  const team = teamConfig();
+  const me = identity();
+  const scope = team.scope ?? 'summary';
+  const keepDays = team.shareDays ?? 45;
+
+  const shelf = shelfOf(root, me.deviceId);
+  const rollups = join(shelf, 'rollup');
+  mkdirSync(rollups, { recursive: true });
+
+  const oldest = shiftDay(localDay(Date.now()), -(keepDays - 1));
+  const days = coveredDays().filter((day) => day >= oldest);
+
+  let written = 0;
+  const published = [];
+  for (const day of days) {
+    const rollup = loadRollup(day);
+    if (!rollup) continue;
+    const clean = sanitise(rollup, scope);
+    if (!clean) continue;
+    writeJsonFile(join(rollups, `${day}.json`), clean);
+    published.push(day);
+    written += 1;
+  }
+
+  // Retire days that have aged out of the window, so a shelf is bounded rather
+  // than growing for as long as somebody keeps the tool installed.
+  let removed = 0;
+  try {
+    for (const name of readdirSync(rollups)) {
+      const day = name.replace(/\.json$/, '');
+      if (name.endsWith('.json') && day < oldest) { removeFile(join(rollups, name)); removed += 1; }
+    }
+  } catch { /* nothing published yet */ }
+
+  writeJsonFile(join(shelf, 'meta.json'), manifestFor(me, {
+    scope, version: version(), days: published.length,
+  }));
+
+  return { written, removed, days: published };
+}
+
+// ── Reading the pool ────────────────────────────────────────────────────────
+
+/**
+ * Every shelf in the pool, ours included.
+ *
+ * @returns {{deviceId, name, host, os, scope, lastSeen, isMe, rollups: Map<string,object>}[]}
+ */
+export function readPool({ root = poolRoot(), days = null } = {}) {
+  const me = identity();
+  const wanted = days ? new Set(days) : null;
+  const peers = [];
+
+  for (const deviceId of listDevices(root)) {
+    const shelf = teamDeviceDir(root, deviceId);
+    const meta = readJsonFile(join(shelf, 'meta.json')) ?? {};
+    const rollups = new Map();
+
+    let names = [];
+    try { names = readdirSync(join(shelf, 'rollup')); } catch { names = []; }
+
+    for (const name of names) {
+      if (!name.endsWith('.json')) continue;
+      const day = name.slice(0, -5);
+      if (wanted && !wanted.has(day)) continue;
+      const rollup = readJsonFile(join(shelf, 'rollup', name));
+      if (rollup) rollups.set(day, rollup);
+    }
+
+    peers.push({
+      deviceId,
+      name: meta.name ?? deviceId.slice(0, 6),
+      host: meta.host ?? null,
+      os: meta.os ?? null,
+      scope: meta.scope ?? 'summary',
+      lastSeen: meta.lastSeen ?? null,
+      isMe: deviceId === me.deviceId,
+      rollups,
+    });
+  }
+
+  // Ours first, then most recently seen. A list that reorders itself as people
+  // work is unreadable; anchoring self at the top keeps it stable.
+  peers.sort((a, b) => Number(b.isMe) - Number(a.isMe) || (b.lastSeen ?? 0) - (a.lastSeen ?? 0));
+  return peers;
+}
+
+// ── One cycle ───────────────────────────────────────────────────────────────
+
+/**
+ * Pull, publish, push. The whole exchange, and the only thing the poller calls.
+ *
+ * Pull comes first so our push rebases onto whatever arrived while we were away;
+ * publish comes second so the thing we push is current rather than one cycle
+ * behind, which is what makes the dashboard feel live rather than lagged.
+ */
+export function syncOnce({ push = true } = {}) {
+  if (!isEnabled()) return { ok: false, reason: 'sharing is off', at: Date.now() };
+
+  const team = teamConfig();
+  const transport = transportFor(team.transport);
+  const root = poolRoot();
+  if (!transport) return { ok: false, reason: 'unknown transport', at: Date.now() };
+
+  const pulled = transport.pull(root, { repo: team.repo });
+  const published = publish({ root });
+
+  let pushed = { ok: true, pushed: false, error: null };
+  if (push) {
+    pushed = transport.push(root, {
+      deviceId: identity().deviceId,
+      message: `syndes: ${identity().name} through ${localDay(Date.now())}`,
+    });
+  }
+
+  const state = {
+    ok: pulled.ok && pushed.ok,
+    at: Date.now(),
+    pulled: pulled.ok,
+    pushed: pushed.pushed,
+    published: published.written,
+    error: pulled.error ?? pushed.error ?? null,
+  };
+  saveState(state);
+  debug('team sync', state);
+  return state;
+}
+
+export function loadState() {
+  return readJson(teamStateFile).data ?? { ok: null, at: null, error: null };
+}
+
+function saveState(state) {
+  try {
+    mkdirSync(dirname(teamStateFile), { recursive: true });
+    const staging = `${teamStateFile}.tmp`;
+    writeFileSync(staging, `${JSON.stringify(state)}\n`);
+    renameSync(staging, teamStateFile);
+  } catch { /* the sync happened whether or not we could note it */ }
+}
+
+function version() {
+  try {
+    return JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8')).version;
+  } catch {
+    return null;
+  }
+}
+
+export { join_ as joinPool, sanitise };

package/sync/run-sync.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * One sync cycle, in its own process.
+ *
+ * git talks to a network and the transport calls it synchronously, which is
+ * correct for a CLI and unacceptable inside the dashboard's event loop — a
+ * twenty-five second timeout on a slow remote would freeze every other request
+ * on the server, including the one drawing the page that asked for the sync.
+ *
+ * So the poller spawns this instead of calling syncOnce directly. The child
+ * blocks; the server does not.
+ */
+
+import { syncOnce } from './index.mjs';
+
+try {
+  const result = syncOnce({ push: !process.argv.includes('--no-push') });
+  process.stdout.write(JSON.stringify(result));
+} catch (error) {
+  process.stdout.write(JSON.stringify({ ok: false, at: Date.now(), error: String(error?.message ?? error) }));
+}

package/sync/share.mjs

@@ -0,0 +1,143 @@
+/**
+ * What leaves the machine, and what never does.
+ *
+ * The local ledger holds prompts, file paths and shell commands. A shared pool
+ * is, by definition, somewhere other people can read — so the unit of sharing is
+ * NOT the ledger. It is the daily rollup, with the identifying fields removed
+ * before it is written.
+ *
+ * That choice is deliberate on three counts:
+ *   • A rollup is already a count of things, not a copy of them. There is no
+ *     prompt text in it to leak, because none was ever folded in.
+ *   • It is a few kilobytes a day, so a poll every thirty seconds is free.
+ *   • It carries every number the team view needs, so nothing is lost by
+ *     refusing to ship the records themselves.
+ *
+ * Scopes:
+ *   summary  (default) counts, tokens, time, hours. No paths, no project ids,
+ *            no per-tool breakdown.
+ *   detailed adds project ids and the tool mix, for teams who have agreed to
+ *            it. Still never prompt text, a file path, a command, or a session
+ *            id — those are refused at every scope, because a scope is a dial
+ *            for detail and not a way to opt out of the promise.
+ *
+ * Sanitisation is SUBTRACTIVE ONLY. A key is dropped, never rewritten, so a
+ * reader can always tell "zero" from "not shared". Where a count has to survive
+ * an id being removed it is added under a new `…Count` name rather than
+ * overwriting the field it came from.
+ *
+ * Paths may name a nested key with `*` for "every entry", because the leak this
+ * module exists to prevent hid one level down: volume.bySource carries a
+ * per-agent breakdown, and each of its buckets carried the session ids.
+ */
+
+/** Refused at every scope. Nothing on this list is ever shared. */
+const NEVER = {
+  volume: ['files', 'sessions', 'bySource.*.sessions'],
+  tools: ['targets', 'commands'],
+  rework: ['churn', 'storms'],
+  friction: ['byTarget'],
+  context: ['sessionsWithCompact'],
+};
+
+/** Dropped as well at `summary` — useful detail, but it describes your work. */
+const SUMMARY_ONLY = {
+  volume: ['projects', 'bySource'],
+  tools: ['byTool'],
+  friction: ['byTool'],
+};
+
+/**
+ * @param {object} rollup   from analytics/rollup.mjs buildDay()
+ * @param {'summary'|'detailed'} scope
+ * @returns {object|null} a rollup of the same shape, with fields removed
+ */
+export function sanitise(rollup, scope = 'summary') {
+  if (!rollup?.metrics) return null;
+
+  const metrics = {};
+  for (const [name, metric] of Object.entries(rollup.metrics)) {
+    const paths = scope === 'detailed'
+      ? (NEVER[name] ?? [])
+      : [...(NEVER[name] ?? []), ...(SUMMARY_ONLY[name] ?? [])];
+    metrics[name] = strip(metric, paths);
+  }
+
+  // Counts survive their ids. "Four sessions" is what the team view divides by
+  // and it says nothing about which four.
+  if (rollup.metrics.volume) {
+    metrics.volume.sessionCount = (rollup.metrics.volume.sessions ?? []).length;
+    metrics.volume.projectCount = (rollup.metrics.volume.projects ?? []).length;
+    metrics.volume.fileCount = (rollup.metrics.volume.files ?? []).length;
+  }
+  if (rollup.metrics.context) {
+    metrics.context.sessionsWithCompactCount = (rollup.metrics.context.sessionsWithCompact ?? []).length;
+  }
+  if (rollup.metrics.rework) {
+    // The storms themselves name a command and never travel; the count does,
+    // because the score reads it and a missing one reads as "no storms".
+    metrics.rework.stormCount = (rollup.metrics.rework.storms ?? []).length;
+  }
+
+  return {
+    day: rollup.day,
+    version: rollup.version,
+    records: rollup.records,
+    builtAt: rollup.builtAt,
+    final: rollup.final,
+    scope,
+    metrics,
+  };
+}
+
+/** Remove each path, copying only as deep as a removal actually reaches. */
+function strip(object, paths) {
+  if (!object || typeof object !== 'object') return object;
+  let out = { ...object };
+  for (const path of paths) out = drop(out, path.split('.'));
+  return out;
+}
+
+function drop(node, segments) {
+  if (!node || typeof node !== 'object') return node;
+  const [head, ...rest] = segments;
+
+  if (!rest.length) {
+    if (head === '*') return node;
+    const out = { ...node };
+    delete out[head];
+    return out;
+  }
+
+  if (head === '*') {
+    const out = Array.isArray(node) ? [...node] : { ...node };
+    for (const key of Object.keys(out)) out[key] = drop(out[key], rest);
+    return out;
+  }
+
+  if (!(head in node)) return node;
+  return { ...node, [head]: drop(node[head], rest) };
+}
+
+/**
+ * The card a device leaves beside its rollups.
+ *
+ * Written on every publish rather than once at enrolment, so `lastSeen` is
+ * meaningful: a shelf that has stopped being updated is visibly stale rather
+ * than silently indistinguishable from a quiet day.
+ */
+export function manifestFor(identity, { scope, version, days }) {
+  return {
+    deviceId: identity.deviceId,
+    name: identity.name,
+    host: identity.host,
+    os: identity.os,
+    scope,
+    version,
+    days,
+    firstSeen: identity.createdAt,
+    lastSeen: Date.now(),
+  };
+}
+
+export { NEVER, SUMMARY_ONLY };