syndes 0.1.0

package/src/term.mjs

@@ -0,0 +1,272 @@
+/**
+ * Colours, boxes, tables and prompts.
+ *
+ * Honours NO_COLOR and a non-TTY stdout, and falls back to ASCII where the code
+ * page cannot draw box characters — a garbled report on Windows Terminal is a
+ * bug report we should not have to receive.
+ *
+ * The escape byte is built with fromCharCode rather than written literally, so
+ * this source file stays free of control characters and survives every editor,
+ * diff viewer and patch tool it will pass through.
+ */
+
+import { createInterface } from 'node:readline';
+import { isWindows } from '../runtime/platform.mjs';
+
+const ESC = String.fromCharCode(27);
+const CSI = `${ESC}[`;
+const ANSI = new RegExp(`${ESC}\\[[0-9;]*m`, 'g');
+
+const COLOR = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR && process.env.TERM !== 'dumb';
+
+/** Windows consoles on a legacy code page render box drawing as mojibake. */
+const UNICODE = !isWindows || Boolean(process.env.WT_SESSION) || Boolean(process.env.TERM_PROGRAM);
+
+const wrap = (code) => (text) => (COLOR ? `${CSI}${code}m${text}${CSI}0m` : String(text));
+
+export const bold = wrap(1);
+export const dim = wrap(2);
+export const red = wrap(31);
+export const green = wrap(32);
+export const yellow = wrap(33);
+export const blue = wrap(34);
+export const magenta = wrap(35);
+export const cyan = wrap(36);
+export const grey = wrap(90);
+
+export const OK = green(UNICODE ? '✓' : 'OK');
+export const FAIL = red(UNICODE ? '✗' : 'X');
+export const WARN = yellow('!');
+export const DOT = UNICODE ? '·' : '-';
+
+export const BOX = UNICODE
+  ? { tl: '┌', tr: '┐', bl: '└', br: '┘', h: '─', v: '│', lt: '├', rt: '┤' }
+  : { tl: '+', tr: '+', bl: '+', br: '+', h: '-', v: '|', lt: '+', rt: '+' };
+
+export function write(text = '') {
+  process.stdout.write(`${text}\n`);
+}
+
+export const width = () => Math.min(process.stdout.columns || 80, 100);
+
+/** Visible length, ignoring colour escapes — padEnd on a coloured string lies. */
+export function visible(text) {
+  return String(text).replace(ANSI, '').length;
+}
+
+export function pad(text, size) {
+  const gap = size - visible(text);
+  return gap > 0 ? text + ' '.repeat(gap) : text;
+}
+
+export function padStart(text, size) {
+  const gap = size - visible(text);
+  return gap > 0 ? ' '.repeat(gap) + text : text;
+}
+
+export function rule(size = width()) {
+  return grey(BOX.h.repeat(size));
+}
+
+export function table(rows, { align = [] } = {}) {
+  if (!rows.length) return [];
+  const columns = Math.max(...rows.map((row) => row.length));
+  const widths = [];
+  for (let column = 0; column < columns; column += 1) {
+    widths.push(Math.max(...rows.map((row) => visible(row[column] ?? ''))));
+  }
+  return rows.map((row) => row
+    .map((cell, column) => (align[column] === 'right'
+      ? padStart(cell ?? '', widths[column])
+      : pad(cell ?? '', widths[column])))
+    .join('  ')
+    .trimEnd());
+}
+
+/** A horizontal bar for proportions. Never the only channel carrying meaning. */
+export function bar(fraction, size = 20, colour = cyan) {
+  const filled = Math.max(0, Math.min(size, Math.round((fraction ?? 0) * size)));
+  const glyph = UNICODE ? '█' : '#';
+  const empty = UNICODE ? '░' : '.';
+  return colour(glyph.repeat(filled)) + grey(empty.repeat(size - filled));
+}
+
+export function sparkline(values) {
+  if (!values.length) return '';
+  const glyphs = UNICODE ? '▁▂▃▄▅▆▇█' : '.:-=+*#@';
+  const max = Math.max(...values, 1);
+  return values
+    .map((value) => glyphs[Math.min(glyphs.length - 1, Math.floor((value / max) * (glyphs.length - 1)))])
+    .join('');
+}
+
+/**
+ * A spinner for work that takes long enough to notice.
+ *
+ * Animation is a courtesy, not a requirement: when stdout is not a TTY — piped
+ * to a file, running in CI, read by another program — this degrades to one
+ * printed line per step, because writing cursor escapes into a log file
+ * produces garbage nobody can read.
+ */
+const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+
+export function spinner(label) {
+  const animated = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR && !process.env.CI;
+  let frame = 0;
+  let text = label;
+  let timer = null;
+
+  const paint = () => {
+    process.stdout.write(`\r${CSI}2K  ${cyan(FRAMES[frame])} ${text}`);
+    frame = (frame + 1) % FRAMES.length;
+  };
+
+  if (animated) {
+    paint();
+    timer = setInterval(paint, 80);
+    timer.unref?.();
+  }
+  // Non-TTY prints nothing on start: the result line says what happened, and
+  // emitting both turns a clean log into two lines per step saying the same thing.
+
+  const stop = (mark, message, detail) => {
+    if (timer) clearInterval(timer);
+    if (animated) process.stdout.write(`\r${CSI}2K`);
+    write(`  ${mark} ${message}${detail ? ` ${grey(detail)}` : ''}`);
+  };
+
+  return {
+    update(next) { text = next; },
+    succeed: (detail) => stop(OK, text, detail),
+    skip: (detail) => stop(grey(DOT), grey(text), detail),
+    fail: (detail) => stop(FAIL, text, detail),
+  };
+}
+
+/**
+ * Print text progressively, the way a model streams tokens.
+ *
+ * Two things make this non-trivial. Colour escapes must never be split across
+ * writes — half of `\e[36m` on the wire is garbage on screen — so the text is
+ * tokenised with each escape sequence kept whole. And it degrades to an instant
+ * write whenever nobody is watching: a non-TTY, CI, or NO_COLOR. Streaming into
+ * a log file is just a slow way to produce the same bytes.
+ *
+ * @param {string} text  may already contain colour
+ * @param {{speed?: number}} options  milliseconds between words
+ */
+export async function stream(text, { speed = 11 } = {}) {
+  const animated = Boolean(process.stdout.isTTY) && !process.env.CI && process.env.SYNDES_NO_ANIMATION !== '1';
+  if (!animated) return write(text);
+
+  for (const chunk of tokenise(text)) {
+    process.stdout.write(chunk);
+    // A line break is a beat: it is where a reader's eye moves anyway.
+    await pause(chunk.endsWith('\n') ? speed * 6 : speed);
+  }
+  process.stdout.write('\n');
+  return undefined;
+}
+
+/** Split into word-sized chunks, never cutting an escape sequence in half. */
+function tokenise(text) {
+  const out = [];
+  let buffer = '';
+
+  for (let i = 0; i < text.length; i += 1) {
+    const char = text[i];
+    if (char === ESC) {
+      const end = text.indexOf('m', i);
+      if (end === -1) { buffer += char; continue; }
+      buffer += text.slice(i, end + 1);
+      i = end;
+      continue;
+    }
+    buffer += char;
+    if (char === ' ' || char === '\n') { out.push(buffer); buffer = ''; }
+  }
+  if (buffer) out.push(buffer);
+  return out;
+}
+
+function pause(ms) {
+  return new Promise((resolve) => { setTimeout(resolve, ms); });
+}
+
+/** The wordmark, for the top of a first run. */
+export function banner() {
+  const mark = UNICODE ? '◆' : '*';
+  write();
+  write(`  ${bold(cyan(mark))}  ${bold('SynDes')}  ${grey('· a record of how you work with coding agents')}`);
+  write();
+}
+
+/** Hold for a beat so a sequence of steps reads as progress rather than a dump. */
+export function beat(ms = 90) {
+  if (!process.stdout.isTTY) return Promise.resolve();
+  return new Promise((resolve) => { setTimeout(resolve, ms); });
+}
+
+export function ask(question, { silent = false } = {}) {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+
+    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.
+      const redraw = () => { rl.output.write(`${CSI}2K${CSI}200D${question}`); };
+      rl.output.write(question);
+      rl.input.on('data', redraw);
+      rl.question('', (answer) => {
+        rl.input.off('data', redraw);
+        rl.output.write('\n');
+        rl.close();
+        resolve(answer);
+      });
+      return;
+    }
+
+    rl.question(question, (answer) => { rl.close(); resolve(answer.trim()); });
+  });
+}
+
+export async function confirm(question, fallback = false) {
+  const suffix = fallback ? '[Y/n]' : '[y/N]';
+  const answer = (await ask(`${question} ${suffix} `)).toLowerCase();
+  if (!answer) return fallback;
+  return answer === 'y' || answer === 'yes';
+}
+
+export function bytes(value) {
+  const units = ['B', 'KB', 'MB', 'GB'];
+  let size = value ?? 0;
+  let unit = 0;
+  while (size >= 1024 && unit < units.length - 1) { size /= 1024; unit += 1; }
+  return `${size < 10 && unit > 0 ? size.toFixed(1) : Math.round(size)}${units[unit]}`;
+}
+
+export function compact(value) {
+  if (value === null || value === undefined) return '—';
+  if (Math.abs(value) >= 1_000_000) return `${(value / 1_000_000).toFixed(1)}M`;
+  if (Math.abs(value) >= 1000) return `${(value / 1000).toFixed(1)}k`;
+  return String(Math.round(value));
+}
+
+export function usd(value) {
+  if (value === null || value === undefined) return '—';
+  return value >= 100 ? `$${Math.round(value)}` : `$${value.toFixed(2)}`;
+}
+
+export function duration(ms) {
+  if (!ms || ms < 0) return '0m';
+  const minutes = Math.round(ms / 60_000);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  return minutes % 60 ? `${hours}h${minutes % 60}m` : `${hours}h`;
+}
+
+export function percent(fraction) {
+  return fraction === null || fraction === undefined ? '—' : `${Math.round(fraction * 100)}%`;
+}
+
+export { COLOR, UNICODE, CSI };

package/src/uninstall.mjs

@@ -0,0 +1,43 @@
+/**
+ * Remove every syndes hook, leave everyone else's alone, and ASK before
+ * touching the ledger.
+ *
+ * The default is to keep the data. Uninstalling a tracker is not the same as
+ * asking it to destroy your history, and conflating the two is unrecoverable.
+ */
+
+import { rmSync, existsSync } from 'node:fs';
+import { installDir, dataDir, displayPath } from '../runtime/paths.mjs';
+import { uninstallHooks } from './settings.mjs';
+import { height } from '../ledger/read.mjs';
+import { usage } from '../ledger/retention.mjs';
+
+export function uninstall({ purge = false } = {}) {
+  const steps = [];
+
+  const { removed, backup } = uninstallHooks();
+  steps.push({ step: 'hooks', detail: removed.length ? `removed from ${removed.join(', ')}` : 'none were wired', backup });
+
+  if (existsSync(installDir)) {
+    rmSync(installDir, { recursive: true, force: true });
+    steps.push({ step: 'files', detail: displayPath(installDir) });
+  }
+
+  if (purge) {
+    const { seq } = height();
+    const { bytes } = usage();
+    rmSync(dataDir, { recursive: true, force: true });
+    steps.push({ step: 'ledger', detail: `deleted ${seq + 1} records (${bytes} bytes)`, destructive: true });
+  } else {
+    steps.push({ step: 'ledger', detail: `kept at ${displayPath(dataDir)} — use --purge to delete` });
+  }
+
+  return { steps, purged: purge };
+}
+
+/** What a purge would destroy, so the confirmation can name it. */
+export function purgeImpact() {
+  const { seq, days } = height();
+  const { bytes } = usage();
+  return { records: seq + 1, days, bytes, path: dataDir };
+}