syndes 0.1.0

package/ledger/schema.mjs

@@ -0,0 +1,96 @@
+/**
+ * Record shapes, and the version stamp that lets old records stay readable.
+ *
+ * Envelope on every record:
+ *   { v, seq, ts, source, kind, session, project, data, prev, hash }
+ *
+ * `source` names which agent the event came from — claude-code, codex, and so
+ * on. It is part of the hashed body, not a later annotation, because a record
+ * that cannot prove which tool produced it is not evidence of anything once
+ * more than one tool is being recorded.
+ *
+ * `hash` covers everything except itself; `prev` is fed in separately as the
+ * chaining input. Editing any field, including `prev`, breaks the chain.
+ *
+ * Records are immutable and additive. A field is never repurposed and never
+ * removed — a reader from v1 must still read a v3 segment, because the point of
+ * the ledger is that the past stays legible.
+ */
+
+/**
+ * Record version.
+ *
+ * v1 had no `source`. v2 adds it to the hashed body — which means v1 records
+ * must keep hashing exactly as they did, over an object with no source key at
+ * all. Defaulting the value would not be enough: a key that was absent when the
+ * hash was taken has to stay absent, or every chain written before this change
+ * fails to verify.
+ */
+export const VERSION = 2;
+
+/** What a record with no explicit source is taken to be. */
+export const DEFAULT_SOURCE = 'claude-code';
+
+export const KIND = {
+  GENESIS: 'ledger.genesis',
+  SEAL: 'ledger.seal',
+  PRUNE: 'ledger.prune',
+  KEYROTATE: 'ledger.keyrotate',
+  INSTALL: 'ledger.install',
+  CONFIG: 'ledger.config',
+  TRACKING: 'ledger.tracking',
+
+  SESSION_START: 'session.start',
+  SESSION_END: 'session.end',
+  COMPACT: 'session.compact',
+
+  PROMPT: 'prompt.submit',
+  STOP: 'turn.stop',
+  SUBAGENT_STOP: 'turn.subagent_stop',
+  NOTIFY: 'turn.notify',
+
+  TOOL_PRE: 'tool.pre',
+  TOOL_POST: 'tool.post',
+  TOOL_BLOCKED: 'tool.blocked',
+
+  USAGE: 'usage.sample',
+  FILE_TOUCH: 'file.touch',
+  GIT_COMMIT: 'git.commit',
+
+  COACH: 'coach.nudge',
+};
+
+const KINDS = new Set(Object.values(KIND));
+
+/** The fields covered by the hash, in the order canonical() will sort them anyway. */
+export function hashable(record) {
+  const body = {
+    v: record.v,
+    seq: record.seq,
+    ts: record.ts,
+    kind: record.kind,
+    session: record.session ?? null,
+    project: record.project ?? null,
+    data: record.data ?? {},
+    ...(record.key === undefined ? {} : { key: record.key }),
+  };
+
+  // `source` joined the envelope at v2. A v1 record is hashed without the key,
+  // exactly as it was written, so an existing chain keeps verifying across the
+  // upgrade instead of reporting every record as tampered.
+  if ((record.v ?? 1) >= 2) body.source = record.source ?? DEFAULT_SOURCE;
+  return body;
+}
+
+/** A draft record, before the chain assigns it a seq, prev and hash. */
+export function draft(kind, {
+  ts = Date.now(), session = null, project = null, data = {},
+  source = DEFAULT_SOURCE, key,
+} = {}) {
+  if (!KINDS.has(kind)) throw new Error(`unknown record kind: ${kind}`);
+  return { v: VERSION, ts, source, kind, session, project, data, ...(key ? { key } : {}) };
+}
+
+export function isKnownKind(kind) {
+  return KINDS.has(kind);
+}

package/ledger/segments.mjs

@@ -0,0 +1,109 @@
+/**
+ * Daily segments: log/YYYY-MM-DD.jsonl, in UTC.
+ *
+ * UTC, not local time, so a laptop crossing timezones cannot produce two
+ * segments claiming the same day or one that appears to run backwards. Local-day
+ * bucketing happens at read time, in analytics/ranges.mjs, where it belongs.
+ *
+ * Rotation seals the closed segment. Sealed segments are read-only forever.
+ */
+
+import { readdirSync, existsSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { logDir, sealDir, segmentFile, sealFileFor } from '../runtime/paths.mjs';
+import { streamRecords } from '../runtime/jsonl.mjs';
+import { segmentRoot } from './chain.mjs';
+import { readJson } from '../runtime/config.mjs';
+
+const NAME = /^(\d{4}-\d{2}-\d{2})\.jsonl(\.gz)?$/;
+
+export function dayOf(ts) {
+  return new Date(ts).toISOString().slice(0, 10);
+}
+
+/** Every day that has a segment, oldest first, gzipped or not. */
+export function listDays() {
+  try {
+    return readdirSync(logDir)
+      .map((name) => NAME.exec(name))
+      .filter(Boolean)
+      .map((match) => match[1])
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+/** The readable file for a day, preferring the plain segment over the archive. */
+export function fileForDay(day) {
+  const plain = segmentFile(day);
+  if (existsSync(plain)) return plain;
+  const gz = `${plain}.gz`;
+  return existsSync(gz) ? gz : null;
+}
+
+export function isSealed(day) {
+  return existsSync(sealFileFor(day));
+}
+
+export function readSeal(day) {
+  return readJson(sealFileFor(day)).data;
+}
+
+export function listSeals() {
+  try {
+    return readdirSync(sealDir)
+      .filter((name) => name.endsWith('.seal.json'))
+      .map((name) => name.replace('.seal.json', ''))
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Compute a day's seal without writing it.
+ *
+ * The caller writes the seal file only after the matching ledger.seal record is
+ * durably in the chain, so a crash can leave the record without the file (which
+ * verify tolerates) but never the file without the record (which would look
+ * like a seal nobody witnessed).
+ *
+ * @returns {Promise<object|null>} null when the day has no readable segment
+ */
+export async function computeSeal(day) {
+  const file = fileForDay(day);
+  if (!file) return null;
+
+  const hashes = [];
+  let first = null;
+  let last = null;
+  let keyId = null;
+
+  for await (const record of streamRecords(file)) {
+    if (typeof record.hash !== 'string') continue;
+    if (first === null) first = record.seq;
+    last = record.seq;
+    if (record.key) keyId = record.key;
+    hashes.push(record.hash);
+  }
+  if (first === null) return null;
+
+  return {
+    day,
+    first_seq: first,
+    last_seq: last,
+    count: hashes.length,
+    root: segmentRoot(hashes),
+    tip_hash: hashes[hashes.length - 1],
+    key_id: keyId,
+    sealed_at: Date.now(),
+  };
+}
+
+export function writeSeal(seal) {
+  mkdirSync(sealDir, { recursive: true });
+  writeFileSync(sealFileFor(seal.day), `${JSON.stringify(seal, null, 2)}\n`);
+}
+
+export { segmentFile, sealFileFor };

package/ledger/verify.mjs

@@ -0,0 +1,174 @@
+/**
+ * `syndes verify` — walk the chain and report the truth about it.
+ *
+ * A verifier that only says "invalid" is not worth running, so every problem
+ * carries the seq, the file and what specifically failed. It also distinguishes
+ * the four things that look alike to a naive checker:
+ *
+ *   tampered      a record's own hash does not recompute
+ *   broken link   a record's `prev` is not its predecessor's hash
+ *   gap           seq numbers skip, and no prune record declares it
+ *   torn tail     the final line is half-written — a killed worker, not an edit
+ *
+ * Confusing a torn tail with tampering would cry wolf on an ordinary crash, and
+ * false alarms train people to ignore the real ones.
+ */
+
+import { listDays, fileForDay, listSeals, readSeal } from './segments.mjs';
+import { streamRecords, lastRecordOf } from '../runtime/jsonl.mjs';
+import { computeHash, hashMatches, segmentRoot, ZERO } from './chain.mjs';
+import { loadKeyById, loadKey } from './keys.mjs';
+import { KIND } from './schema.mjs';
+
+/**
+ * @param {{full?: boolean}} options  full also re-checks every segment seal
+ * @returns {Promise<{ok, records, days, problems, firstBad, tip, checkedSeals}>}
+ */
+export async function verify({ full = false } = {}) {
+  const problems = [];
+  const declaredGaps = [];
+  const observedGaps = [];
+
+  const current = loadKey();
+  let key = current?.key ?? null;
+  let keyId = current?.keyId ?? null;
+
+  let expectedSeq = 0;
+  let previousHash = ZERO;
+  let records = 0;
+  let tip = null;
+  const days = listDays();
+  const rootsByDay = new Map();
+
+  for (const day of days) {
+    const file = fileForDay(day);
+    if (!file) continue;
+    const hashes = [];
+
+    for await (const record of streamRecords(file)) {
+      records += 1;
+
+      // A record may hand the chain a new key: genesis states the first one,
+      // keyrotate states the next. Both are signed with the key then in force.
+      if (record.key && record.key !== keyId) {
+        const found = loadKeyById(record.key);
+        if (!found) {
+          problems.push(problem('unknown-key', record, file, `no key ${record.key} on disk`));
+          key = null;
+        } else {
+          key = found;
+          keyId = record.key;
+        }
+      }
+
+      if (record.seq !== expectedSeq) {
+        if (record.seq > expectedSeq) observedGaps.push([expectedSeq, record.seq - 1, day]);
+        else problems.push(problem('out-of-order', record, file, `expected seq ${expectedSeq}`));
+        expectedSeq = record.seq;
+      }
+
+      if (!hashMatches(record.prev, previousHash)) {
+        problems.push(problem('broken-link', record, file,
+          `prev ${short(record.prev)} does not match previous hash ${short(previousHash)}`));
+      }
+
+      if (key) {
+        const recomputed = computeHash(key, record.prev, record);
+        if (!hashMatches(recomputed, record.hash)) {
+          problems.push(problem('tampered', record, file,
+            `hash is ${short(record.hash)}, recomputes to ${short(recomputed)}`));
+        }
+      }
+
+      if (record.kind === KIND.PRUNE && Array.isArray(record.data?.ranges)) {
+        for (const [first, last] of record.data.ranges) declaredGaps.push([first, last]);
+      }
+
+      hashes.push(record.hash);
+      previousHash = record.hash;
+      expectedSeq = record.seq + 1;
+      tip = record;
+    }
+
+    rootsByDay.set(day, segmentRoot(hashes));
+  }
+
+  // A gap is only a problem if nothing in the chain admits to it.
+  //
+  // Coverage is checked against the UNION of declared ranges, not against any
+  // single one. Pruning two consecutive days declares [0,4] and [5,9] but leaves
+  // one contiguous hole 0..9, and asking whether one range covers it would call
+  // an ordinary retention run tampering.
+  const declared = mergeRanges(declaredGaps);
+
+  for (const [first, last, day] of observedGaps) {
+    const covered = declared.some(([a, b]) => a <= first && b >= last);
+    if (!covered) {
+      problems.push({
+        type: 'gap', seq: first, day, file: fileForDay(day),
+        detail: `seq ${first}..${last} missing, and no ledger.prune record declares it`,
+      });
+    }
+  }
+
+  // A torn final line is a killed worker mid-write. Reported as its own thing.
+  const newest = days[days.length - 1];
+  if (newest) {
+    const file = fileForDay(newest);
+    if (file && lastRecordOf(file).torn) {
+      problems.push({ type: 'torn-tail', seq: tip?.seq ?? null, day: newest, file,
+        detail: 'the last line is incomplete — a worker was killed mid-write' });
+    }
+  }
+
+  let checkedSeals = 0;
+  if (full) {
+    for (const day of listSeals()) {
+      const seal = readSeal(day);
+      const actual = rootsByDay.get(day);
+      checkedSeals += 1;
+      if (!actual) {
+        problems.push({ type: 'seal-orphan', day, seq: seal?.first_seq ?? null,
+          detail: 'a seal exists for a day with no segment' });
+      } else if (seal?.root && seal.root !== actual) {
+        problems.push({ type: 'seal-mismatch', day, seq: seal.first_seq,
+          detail: `seal root ${short(seal.root)} does not match the segment's ${short(actual)}` });
+      }
+    }
+  }
+
+  problems.sort((a, b) => (a.seq ?? 0) - (b.seq ?? 0));
+
+  return {
+    ok: problems.length === 0,
+    records,
+    days: days.length,
+    problems,
+    firstBad: problems[0] ?? null,
+    tip: tip ? { seq: tip.seq, hash: tip.hash, ts: tip.ts } : null,
+    checkedSeals,
+  };
+}
+
+/** Sort and coalesce ranges, joining ones that touch or overlap. */
+function mergeRanges(ranges) {
+  const sorted = [...ranges].sort((a, b) => a[0] - b[0]);
+  const merged = [];
+
+  for (const [first, last] of sorted) {
+    const previous = merged[merged.length - 1];
+    // `first <= previous[1] + 1` joins [0,4] and [5,9]: seq numbers are dense,
+    // so adjacent ranges leave no gap between them.
+    if (previous && first <= previous[1] + 1) previous[1] = Math.max(previous[1], last);
+    else merged.push([first, last]);
+  }
+  return merged;
+}
+
+function problem(type, record, file, detail) {
+  return { type, seq: record.seq, kind: record.kind, day: undefined, file, detail };
+}
+
+function short(hash) {
+  return typeof hash === 'string' ? hash.slice(0, 12) : String(hash);
+}

package/notify/index.mjs

@@ -0,0 +1,67 @@
+/**
+ * Desktop notification: one API, three platforms, always degrading rather than
+ * failing.
+ *
+ * Resolution order is the platform channel, then nothing — the terminal card is
+ * a separate channel that practices/deliver.mjs writes in parallel, not a
+ * fallback this module fakes.
+ *
+ * A channel that cannot answer returns false. The failure to design out is a
+ * Windows install that reports notifications working and silently drops each one.
+ */
+
+import { isMac, isWindows, isLinux } from '../runtime/platform.mjs';
+import { debug } from '../runtime/log.mjs';
+
+let channel;
+
+async function resolve() {
+  if (channel !== undefined) return channel;
+
+  // Deliberately NOT deferring to claude-noti when it is installed. It answers
+  // "your session needs you"; this answers "here is how last week went". They
+  // are different messages at different moments, and silently suppressing ours
+  // because a neighbour exists would be a surprise, not a courtesy.
+  try {
+    if (isMac) channel = await import('./mac.mjs');
+    else if (isWindows) channel = await import('./windows.mjs');
+    else if (isLinux) channel = await import('./linux.mjs');
+    else channel = null;
+  } catch (error) {
+    debug('notification channel failed to load', error.message);
+    channel = null;
+  }
+
+  if (channel && !channel.available()) channel = null;
+  return channel;
+}
+
+/**
+ * @param {{title: string, subtitle?: string, message: string}} notification
+ * @returns {Promise<boolean>} whether it was actually delivered
+ */
+export async function notify(notification) {
+  const target = await resolve();
+  if (!target) return false;
+
+  try {
+    return await target.send(notification);
+  } catch (error) {
+    debug('notification failed', error.message);
+    return false;
+  }
+}
+
+/** What `doctor` reports: probed, not assumed. */
+export async function probe() {
+  const target = await resolve();
+  return {
+    platform: isMac ? 'macOS' : isWindows ? 'Windows' : isLinux ? 'Linux' : process.platform,
+    channel: target?.name ?? null,
+    available: Boolean(target),
+  };
+}
+
+export function resetCache() {
+  channel = undefined;
+}

package/notify/linux.mjs

@@ -0,0 +1,41 @@
+/**
+ * Linux notifications: notify-send, with a gdbus call as fallback.
+ *
+ * Headless boxes and WSL have neither, and both return false rather than
+ * pretending — a tracker that claims to have notified you on a machine with no
+ * notification daemon has told you something false about your own system.
+ */
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { which } from '../runtime/platform.mjs';
+
+const run = promisify(execFile);
+export const name = 'notify-send';
+
+export function available() {
+  if (!process.env.DISPLAY && !process.env.WAYLAND_DISPLAY) return false;
+  return Boolean(which('notify-send') || which('gdbus'));
+}
+
+export async function send({ title, subtitle, message }) {
+  const body = [subtitle, message].filter(Boolean).join('\n');
+
+  const notifySend = which('notify-send');
+  if (notifySend) {
+    await run(notifySend, ['--app-name=syndes', '--expire-time=8000', title, body], { timeout: 5000 });
+    return true;
+  }
+
+  const gdbus = which('gdbus');
+  if (!gdbus) return false;
+
+  await run(gdbus, [
+    'call', '--session',
+    '--dest', 'org.freedesktop.Notifications',
+    '--object-path', '/org/freedesktop/Notifications',
+    '--method', 'org.freedesktop.Notifications.Notify',
+    'syndes', '0', '', title, body, '[]', '{}', '8000',
+  ], { timeout: 5000 });
+  return true;
+}

package/notify/mac.mjs

@@ -0,0 +1,44 @@
+/**
+ * macOS notifications.
+ *
+ * terminal-notifier when present — it can carry a click action and is not
+ * subject to Script Editor's notification settings — otherwise osascript.
+ *
+ * execFile with an argv array, never a shell string: a nudge quotes ledger data,
+ * and ledger data contains apostrophes, quotes and dollar signs.
+ */
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { which } from '../runtime/platform.mjs';
+
+const run = promisify(execFile);
+export const name = 'macOS';
+
+export function available() {
+  return Boolean(which('terminal-notifier') || which('osascript'));
+}
+
+export async function send({ title, subtitle, message }) {
+  const notifier = which('terminal-notifier');
+  if (notifier) {
+    await run(notifier, [
+      '-title', title,
+      ...(subtitle ? ['-subtitle', subtitle] : []),
+      '-message', message,
+      '-group', 'syndes',
+    ], { timeout: 5000 });
+    return true;
+  }
+
+  const osascript = which('osascript');
+  if (!osascript) return false;
+
+  // AppleScript string literals escape only backslash and double quote.
+  const quote = (value) => `"${String(value ?? '').replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+  const script = `display notification ${quote(message)} with title ${quote(title)}` +
+    (subtitle ? ` subtitle ${quote(subtitle)}` : '');
+
+  await run(osascript, ['-e', script], { timeout: 5000 });
+  return true;
+}

package/notify/terminal.mjs

@@ -0,0 +1,15 @@
+/**
+ * The universal channel: a boxed card printed at SessionStart through the hook's
+ * stdout. Works everywhere the desktop channels do not — over ssh, in a
+ * container, on a headless box.
+ *
+ * The rendering lives in practices/deliver.mjs, next to the wording it formats.
+ * This module exists so `doctor` can report the channel as present without
+ * pretending it is a desktop notifier.
+ */
+
+export const name = 'terminal card';
+
+export function available() {
+  return true;
+}

package/notify/windows.mjs

@@ -0,0 +1,61 @@
+/**
+ * Windows notifications: a WinRT toast through PowerShell.
+ *
+ * -NoProfile matters: a user profile that loads modules can take seconds, and
+ * this runs in a worker that should not be alive that long. -NonInteractive
+ * guarantees it can never stop waiting for input on a machine nobody is watching.
+ *
+ * The script is passed as one -Command argument with the text interpolated as
+ * XML-escaped literals, so ledger content cannot break out into PowerShell.
+ */
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { which } from '../runtime/platform.mjs';
+
+const run = promisify(execFile);
+export const name = 'Windows toast';
+
+let shell;
+
+function powershell() {
+  if (shell === undefined) shell = which('powershell') ?? which('pwsh') ?? null;
+  return shell;
+}
+
+export function available() {
+  return Boolean(powershell());
+}
+
+export async function send({ title, subtitle, message }) {
+  const binary = powershell();
+  if (!binary) return false;
+
+  const heading = xml(title);
+  const body = xml([subtitle, message].filter(Boolean).join(' — '));
+
+  const script = `
+$ErrorActionPreference = 'Stop'
+[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] > $null
+$xml = New-Object Windows.Data.Xml.Dom.XmlDocument
+$xml.LoadXml('<toast><visual><binding template="ToastText02"><text id="1">${heading}</text><text id="2">${body}</text></binding></visual></toast>')
+$toast = New-Object Windows.UI.Notifications.ToastNotification $xml
+[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('syndes').Show($toast)
+`.trim();
+
+  await run(binary, ['-NoProfile', '-NonInteractive', '-WindowStyle', 'Hidden', '-Command', script], {
+    timeout: 10_000,
+    windowsHide: true,
+  });
+  return true;
+}
+
+/** Escape for XML text AND for the single-quoted PowerShell string wrapping it. */
+function xml(value) {
+  return String(value ?? '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, "''");
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "syndes",
+  "version": "0.1.0",
+  "description": "SynDes \u2014 a tamper-evident ledger of everything you do in Claude Code, an efficiency score built from it, and a local dashboard that shows you how you actually work. macOS, Windows and Linux. Zero dependencies.",
+  "keywords": [
+    "syndes",
+    "claude",
+    "claude-code",
+    "ledger",
+    "audit-log",
+    "usage",
+    "metrics",
+    "analytics",
+    "efficiency",
+    "productivity",
+    "dashboard",
+    "hooks",
+    "tokens",
+    "cost",
+    "macos",
+    "windows",
+    "linux",
+    "cli"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "syndes": "bin/cli.mjs"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "adapters",
+    "analytics",
+    "bin",
+    "collect",
+    "dashboard",
+    "ledger",
+    "notify",
+    "practices",
+    "runtime",
+    "src"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.mjs\"",
+    "bench": "node test/hook-latency.test.mjs --bench",
+    "prepublishOnly": "npm test",
+    "postinstall": "node bin/postinstall.mjs"
+  },
+  "dependencies": {},
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "guruprasath005",
+  "homepage": "https://github.com/guruprasath005/syndes#readme",
+  "bugs": {
+    "url": "https://github.com/guruprasath005/syndes/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/guruprasath005/syndes.git"
+  }
+}