syndes 0.1.0 → 0.3.0

package/sync/index.mjs

@@ -0,0 +1,336 @@
+/**
+ * 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 { encode as encodeInvite } from './invite.mjs';
+import {
+  transportFor, listDevices, readJsonFile, writeJsonFile, removeFile, git,
+} from './transport.mjs';
+import { rmSync } from 'node:fs';
+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;
+}
+
+/**
+ * An invite for this pool, for the owner to send.
+ *
+ * Carries the repository address and a label — never a credential. Who may join
+ * is decided by the repository's collaborator list, which is the only place that
+ * decision can be revoked from.
+ */
+export function inviteCode({ from = null } = {}) {
+  const team = teamConfig();
+  if (!team.enabled || !team.repo) throw new Error('sharing is off — join or create a pool first');
+  return encodeInvite({
+    repo: team.repo,
+    transport: team.transport ?? 'git',
+    pool: poolName(),
+    from: from ?? identity().name,
+  });
+}
+
+/** A readable label for the pool, taken from the repository name. */
+export function poolName() {
+  const repo = teamConfig().repo ?? '';
+  const last = repo.replace(/\.git$/, '').split(/[/\\:]/).filter(Boolean).pop();
+  return last || 'pool';
+}
+
+/**
+ * Remove someone's shelf from the pool.
+ *
+ * This is the ONE operation that deliberately writes outside our own directory,
+ * and it is an explicit administrative act rather than part of any sync. Git
+ * permissions are per-repository, so anyone with write access could already do
+ * this by hand; having a command for it means it is done correctly — the folder
+ * removed, the change pushed — instead of half-done.
+ *
+ * It removes them from view, not from history. Earlier commits still hold the
+ * data and anyone who pulled before still has a copy. The caller is expected to
+ * have said so before calling this.
+ *
+ * @returns {{removed: boolean, name: string|null, pushed: boolean, error: string|null}}
+ */
+export function removeDevice(target, { push = true } = {}) {
+  const root = poolRoot();
+  const me = identity();
+
+  const peers = readPool({ root });
+  const match = peers.find((peer) => peer.deviceId === target)
+    ?? peers.find((peer) => peer.name?.toLowerCase() === String(target).toLowerCase());
+
+  if (!match) return { removed: false, name: null, pushed: false, error: `no machine called "${target}" in the pool` };
+  if (match.deviceId === me.deviceId) {
+    // Deleting your own shelf while still publishing would simply re-create it
+    // on the next sync, which looks like the command silently failed.
+    return { removed: false, name: match.name, pushed: false, error: 'that is this machine — use `syndes team leave` instead' };
+  }
+
+  const shelf = teamDeviceDir(root, match.deviceId);
+  const relative = `devices/${match.deviceId}`;
+
+  if ((teamConfig().transport ?? 'git') !== 'git') {
+    try { rmSync(shelf, { recursive: true, force: true }); } catch (error) { return { removed: false, name: match.name, pushed: false, error: error.message }; }
+    return { removed: true, name: match.name, pushed: true, error: null };
+  }
+
+  const removed = git(root, ['rm', '-r', '--quiet', '--', relative]);
+  if (!removed.ok) return { removed: false, name: match.name, pushed: false, error: removed.error };
+
+  const committed = git(root, ['commit', '-m', `syndes: remove ${match.name} from the pool`, '--', relative]);
+  if (!committed.ok) return { removed: true, name: match.name, pushed: false, error: committed.error };
+
+  if (!push) return { removed: true, name: match.name, pushed: false, error: null };
+
+  const transport = transportFor('git');
+  transport.pull(root);
+  const pushed = git(root, ['push', 'origin', 'HEAD'], 25_000);
+  return { removed: true, name: match.name, pushed: pushed.ok, error: pushed.ok ? null : pushed.error };
+}
+
+// ── 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/invite.mjs

@@ -0,0 +1,70 @@
+/**
+ * Invites: one string that carries everything a new machine needs to join.
+ *
+ * The alternative is a paragraph of instructions — "install this, then run that,
+ * paste this URL, use your own GitHub" — which is where onboarding goes to die.
+ * An invite collapses it into a line the inviter copies and the joiner pastes.
+ *
+ * ── An invite is NOT a credential ──────────────────────────────────────────
+ * It carries a repository address and a label, nothing else. Access is decided
+ * entirely by whether GitHub lets that person in, which the repository owner
+ * controls with collaborator permissions and can revoke. Encoding a token here
+ * would mean the inviter's own credentials travelling through a chat app, which
+ * is exactly the practice this tool should not be teaching. So the invite is
+ * base64 for tidiness, not for secrecy, and it is safe to say so out loud.
+ */
+
+const PREFIX = 'syndes1_';
+const VERSION = 1;
+
+/**
+ * @param {{repo: string, transport: 'git'|'folder', pool?: string, from?: string}} details
+ * @returns {string}
+ */
+export function encode({ repo, transport = 'git', pool = null, from = null }) {
+  if (!repo) throw new Error('an invite needs a repository');
+  const body = { v: VERSION, r: repo, t: transport };
+  if (pool) body.p = pool.slice(0, 60);
+  if (from) body.f = from.slice(0, 40);
+  return PREFIX + Buffer.from(JSON.stringify(body), 'utf8').toString('base64url');
+}
+
+/**
+ * Decode, tolerating what people actually paste — surrounding quotes, a stray
+ * backtick from a chat app, the whole command line rather than just the code.
+ *
+ * @returns {{repo, transport, pool, from}|null} null when it is not an invite
+ */
+export function decode(input) {
+  if (typeof input !== 'string') return null;
+
+  let text = input.trim().replace(/^[`'"]+|[`'"]+$/g, '');
+  const found = /syndes1_[A-Za-z0-9_-]+/.exec(text);
+  if (found) text = found[0];
+  if (!text.startsWith(PREFIX)) return null;
+
+  try {
+    const body = JSON.parse(Buffer.from(text.slice(PREFIX.length), 'base64url').toString('utf8'));
+    if (body.v !== VERSION || typeof body.r !== 'string' || !body.r) return null;
+    return {
+      repo: body.r,
+      transport: body.t === 'folder' ? 'folder' : 'git',
+      pool: typeof body.p === 'string' ? body.p : null,
+      from: typeof body.f === 'string' ? body.f : null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** The line an inviter sends. Two steps, because the install must be global. */
+export function commandFor(code) {
+  return `npm install -g syndes && syndes join ${code}`;
+}
+
+/** True for anything that looks like an invite, so `join` can accept a raw URL too. */
+export function looksLikeInvite(input) {
+  return typeof input === 'string' && input.includes(PREFIX);
+}
+
+export { PREFIX };

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 };