@vimoxshah/tokenflow 1.1.0

package/src/core/yaml.js

@@ -0,0 +1,209 @@
+/**
+ * A deliberately small YAML subset — enough for a config file, with zero
+ * dependencies and no surprises.
+ *
+ * Supported: nested mappings by indentation, block sequences (`- x`),
+ * sequences of mappings, scalars (string / number / bool / null), single- and
+ * double-quoted strings, inline flow arrays (`[a, b]`), `#` comments,
+ * `key:` with an empty value (=> {}), and multi-line values via `|` / `>`.
+ *
+ * NOT supported (and rejected loudly rather than mis-parsed): anchors,
+ * aliases, tags, multiple documents, complex keys, flow mappings.
+ * `config.json` is always accepted as an alternative.
+ */
+
+export function parseYaml(text) {
+  const lines = String(text).split(/\r?\n/);
+  const rows = [];
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    if (/^\s*$/.test(raw)) continue;
+    if (/^\s*#/.test(raw)) continue;
+    if (/^\s*(---|\.\.\.)\s*$/.test(raw)) continue;
+    if (/^\s*[&*!]/.test(raw)) throw new Error(`yaml: anchors/aliases/tags are not supported (line ${i + 1})`);
+    const indent = raw.match(/^ */)[0].length;
+    rows.push({ indent, text: stripComment(raw.trim()), line: i + 1 });
+  }
+  const [value] = parseBlock(rows, 0, rows.length > 0 ? rows[0].indent : 0);
+  return value ?? {};
+}
+
+function stripComment(s) {
+  let out = '';
+  let q = null;
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (q) {
+      out += c;
+      if (c === q && s[i - 1] !== '\\') q = null;
+      continue;
+    }
+    if (c === '"' || c === "'") { q = c; out += c; continue; }
+    if (c === '#' && (i === 0 || /\s/.test(s[i - 1]))) break;
+    out += c;
+  }
+  return out.trim();
+}
+
+function parseBlock(rows, i, indent) {
+  if (i >= rows.length) return [null, i];
+  if (rows[i].text.startsWith('- ') || rows[i].text === '-') return parseSeq(rows, i, indent);
+  return parseMap(rows, i, indent);
+}
+
+function parseMap(rows, i, indent) {
+  const obj = {};
+  while (i < rows.length && rows[i].indent >= indent) {
+    if (rows[i].indent > indent) throw new Error(`yaml: unexpected indent (line ${rows[i].line})`);
+    const { text, line } = rows[i];
+    const m = text.match(/^([^:]+):(?:\s+(.*))?$/);
+    if (!m) throw new Error(`yaml: expected "key: value" (line ${line}): ${text}`);
+    const key = unquote(m[1].trim());
+    const inline = m[2] === undefined ? '' : m[2].trim();
+    i++;
+    if (inline === '|' || inline === '>' || inline === '|-' || inline === '>-') {
+      const childIndent = i < rows.length ? rows[i].indent : indent + 2;
+      const parts = [];
+      while (i < rows.length && rows[i].indent >= childIndent && childIndent > indent) {
+        parts.push(rows[i].text);
+        i++;
+      }
+      obj[key] = inline[0] === '|' ? parts.join('\n') : parts.join(' ');
+      continue;
+    }
+    if (inline !== '') {
+      obj[key] = scalar(inline);
+      continue;
+    }
+    // Nested block, if the next row is deeper.
+    if (i < rows.length && rows[i].indent > indent) {
+      const [v, ni] = parseBlock(rows, i, rows[i].indent);
+      obj[key] = v;
+      i = ni;
+    } else if (i < rows.length && rows[i].indent === indent && rows[i].text.startsWith('- ')) {
+      // A sequence at the same indent as its key (valid YAML).
+      const [v, ni] = parseSeq(rows, i, indent);
+      obj[key] = v;
+      i = ni;
+    } else {
+      obj[key] = {};
+    }
+  }
+  return [obj, i];
+}
+
+function parseSeq(rows, i, indent) {
+  const arr = [];
+  while (i < rows.length && rows[i].indent === indent && (rows[i].text.startsWith('- ') || rows[i].text === '-')) {
+    const body = rows[i].text === '-' ? '' : rows[i].text.slice(2).trim();
+    i++;
+    if (body === '') {
+      if (i < rows.length && rows[i].indent > indent) {
+        const [v, ni] = parseBlock(rows, i, rows[i].indent);
+        arr.push(v);
+        i = ni;
+      } else arr.push(null);
+      continue;
+    }
+    if (/^[^:\s][^:]*:(\s|$)/.test(body)) {
+      // sequence of mappings: "- key: value" plus deeper sibling keys
+      const synthetic = [{ indent: indent + 2, text: body, line: rows[i - 1].line }];
+      while (i < rows.length && rows[i].indent > indent) {
+        synthetic.push({ indent: indent + 2, text: rows[i].text, line: rows[i].line });
+        i++;
+      }
+      const [v] = parseMap(synthetic, 0, indent + 2);
+      arr.push(v);
+      continue;
+    }
+    arr.push(scalar(body));
+  }
+  return [arr, i];
+}
+
+function scalar(s) {
+  // An anchor, alias or tag in a value position: refuse rather than store the
+  // literal text and quietly change the meaning of someone's config.
+  if (/^[&*!]/.test(s)) throw new Error(`yaml: anchors/aliases/tags are not supported ("${s}")`);
+  if (s.startsWith('[') && s.endsWith(']')) {
+    const inner = s.slice(1, -1).trim();
+    if (!inner) return [];
+    return splitFlow(inner).map((x) => scalar(x.trim()));
+  }
+  if (s === '{}') return {};
+  if (s.startsWith('{')) throw new Error('yaml: flow mappings are not supported (use nested keys)');
+  if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) return unquote(s);
+  if (s === '~' || s === 'null' || s === 'Null' || s === 'NULL') return null;
+  if (s === 'true' || s === 'True' || s === 'yes' || s === 'on') return true;
+  if (s === 'false' || s === 'False' || s === 'no' || s === 'off') return false;
+  if (/^-?\d+$/.test(s)) return parseInt(s, 10);
+  if (/^-?\d*\.\d+(e[-+]?\d+)?$/i.test(s)) return parseFloat(s);
+  return s;
+}
+
+function splitFlow(s) {
+  const out = [];
+  let depth = 0, q = null, cur = '';
+  for (const c of s) {
+    if (q) { cur += c; if (c === q) q = null; continue; }
+    if (c === '"' || c === "'") { q = c; cur += c; continue; }
+    if (c === '[') depth++;
+    if (c === ']') depth--;
+    if (c === ',' && depth === 0) { out.push(cur); cur = ''; continue; }
+    cur += c;
+  }
+  if (cur.trim()) out.push(cur);
+  return out;
+}
+
+function unquote(s) {
+  if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
+    const body = s.slice(1, -1);
+    return s[0] === '"' ? body.replace(/\\n/g, '\n').replace(/\\"/g, '"').replace(/\\\\/g, '\\') : body.replace(/''/g, "'");
+  }
+  return s;
+}
+
+// ---------------------------------------------------------------------------
+
+export function stringifyYaml(value, indent = 0) {
+  const pad = ' '.repeat(indent);
+  if (value === null || value === undefined) return 'null';
+  if (Array.isArray(value)) {
+    if (value.length === 0) return '[]';
+    return value
+      .map((v) => {
+        if (v !== null && typeof v === 'object') {
+          const body = stringifyYaml(v, indent + 2);
+          return `${pad}- ${body.trimStart()}`;
+        }
+        return `${pad}- ${scalarOut(v)}`;
+      })
+      .join('\n');
+  }
+  if (typeof value === 'object') {
+    const keys = Object.keys(value);
+    if (keys.length === 0) return '{}';
+    return keys
+      .map((k) => {
+        const v = value[k];
+        if (v !== null && typeof v === 'object' && (Array.isArray(v) ? v.length : Object.keys(v).length)) {
+          return `${pad}${k}:\n${stringifyYaml(v, indent + 2)}`;
+        }
+        if (v !== null && typeof v === 'object') return `${pad}${k}: ${Array.isArray(v) ? '[]' : '{}'}`;
+        return `${pad}${k}: ${scalarOut(v)}`;
+      })
+      .join('\n');
+  }
+  return scalarOut(value);
+}
+
+function scalarOut(v) {
+  if (v === null || v === undefined) return 'null';
+  if (typeof v === 'boolean' || typeof v === 'number') return String(v);
+  const s = String(v);
+  if (s === '' || /^[\s]|[\s]$|[:#\[\]{}&*!|>'"%@`,]|^(true|false|null|yes|no|on|off|~|-?\d)/i.test(s)) {
+    return '"' + s.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n') + '"';
+  }
+  return s;
+}

package/src/export/bundler.js

@@ -0,0 +1,107 @@
+/**
+ * A ~100-line ES-module bundler.
+ *
+ * The dev path has no build step at all — the browser imports the same modules
+ * the CLI does. This exists only so `tokenflow export --html` can emit ONE
+ * self-contained file that works offline, from a file:// URL, or attached to an
+ * email, where `import` from a relative path is not available.
+ *
+ * Rather than rename identifiers (which is where naive concatenating bundlers
+ * break), each module keeps its own function scope and exports are wired
+ * through a tiny require registry. The module graph here is acyclic and uses
+ * only static imports, which is what makes this safe.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+const IMPORT_RE = /^[ \t]*import\s+(?:([\w$]+)\s*,\s*)?(?:\{([^}]*)\}|\*\s*as\s+([\w$]+)|([\w$]+))?\s*(?:from\s*)?['"]([^'"]+)['"]\s*;?[ \t]*$/gm;
+// `export { a, b }` — possibly spanning many lines, as re-export barrels do.
+const EXPORT_LIST_RE = /^[ \t]*export\s*\{([\s\S]*?)\}[ \t]*;?[ \t]*$/gm;
+const EXPORT_DECL_RE = /^[ \t]*export\s+(async\s+function|function\*?|class|const|let|var)\s+([\w$]+)/gm;
+const EXPORT_DEFAULT_RE = /^[ \t]*export\s+default\s+/m;
+
+export function bundle(entry, { root = process.cwd() } = {}) {
+  const modules = new Map();
+  const order = [];
+
+  const load = (file) => {
+    const abs = path.resolve(file);
+    if (modules.has(abs)) return abs;
+    const src = fs.readFileSync(abs, 'utf8');
+    const mod = { abs, id: rel(abs, root), src, deps: [], exports: new Set(), hasDefault: false };
+    modules.set(abs, mod);
+
+    // ---- collect + rewrite imports
+    let body = src.replace(IMPORT_RE, (m, defWithNamed, named, ns, defOnly, spec) => {
+      if (!spec.startsWith('.') && !spec.startsWith('/')) {
+        throw new Error(`snapshot bundler: bare import "${spec}" in ${mod.id} — only relative imports are supported`);
+      }
+      const depAbs = resolve(abs, spec);
+      mod.deps.push(depAbs);
+      const id = rel(depAbs, root);
+      const parts = [];
+      const defName = defWithNamed || defOnly;
+      if (defName && !ns) parts.push(`const ${defName} = __req(${JSON.stringify(id)}).default;`);
+      if (ns) parts.push(`const ${ns} = __req(${JSON.stringify(id)});`);
+      if (named) {
+        const bindings = named.split(',').map((s) => s.trim()).filter(Boolean)
+          .map((s) => {
+            const mm = s.split(/\s+as\s+/);
+            return mm.length === 2 ? `${mm[0].trim()}: ${mm[1].trim()}` : s;
+          });
+        if (bindings.length) parts.push(`const { ${bindings.join(', ')} } = __req(${JSON.stringify(id)});`);
+      }
+      return parts.join(' ');
+    });
+
+    // ---- collect exports
+    for (const m of src.matchAll(EXPORT_DECL_RE)) mod.exports.add(m[2]);
+    for (const m of src.matchAll(EXPORT_LIST_RE)) {
+      for (const s of m[1].split(',')) {
+        const t = s.trim();
+        if (!t) continue;
+        const parts = t.split(/\s+as\s+/);
+        mod.exports.add((parts[1] || parts[0]).trim());
+      }
+    }
+    if (EXPORT_DEFAULT_RE.test(src)) mod.hasDefault = true;
+
+    // ---- strip the `export` keyword / statements
+    body = body
+      .replace(EXPORT_LIST_RE, '')
+      .replace(/^([ \t]*)export\s+default\s+/m, '$1const __default = ')
+      .replace(/^([ \t]*)export\s+/gm, '$1');
+    mod.body = body;
+
+    for (const d of mod.deps) load(d);
+    order.push(abs);
+    return abs;
+  };
+
+  const entryAbs = load(entry);
+
+  let out = '';
+  out += '(function(){\n"use strict";\nvar __registry = {}, __cache = {};\n';
+  out += 'function __req(id){ if(__cache[id]) return __cache[id].e; var m=__registry[id]; if(!m) throw new Error("module not found: "+id); var e={}; __cache[id]={e:e}; m(e); return e; }\n';
+  for (const abs of order) {
+    const m = modules.get(abs);
+    const assigns = [...m.exports].map((n) => `  __exports.${n} = ${n};`).join('\n');
+    const def = m.hasDefault ? '  __exports.default = __default;\n' : '';
+    out += `__registry[${JSON.stringify(m.id)}] = function(__exports){\n${m.body}\n${assigns}\n${def}};\n`;
+  }
+  out += `__req(${JSON.stringify(modules.get(entryAbs).id)});\n})();\n`;
+  return out;
+}
+
+function resolve(fromFile, spec) {
+  const p = path.resolve(path.dirname(fromFile), spec);
+  if (fs.existsSync(p)) return p;
+  for (const ext of ['.js', '.mjs', '/index.js']) {
+    if (fs.existsSync(p + ext)) return p + ext;
+  }
+  throw new Error(`snapshot bundler: cannot resolve "${spec}" from ${fromFile}`);
+}
+
+function rel(abs, root) {
+  return path.relative(root, abs).split(path.sep).join('/');
+}

package/src/export/csv.js

@@ -0,0 +1,100 @@
+/**
+ * CSV export.
+ *
+ * Two modes, both streamed so a full export never buffers the dataset:
+ *   - "view"  the current filtered slice, at request granularity
+ *   - "all"   every normalized record in the store
+ *
+ * Missing values are written as an empty cell, never as 0 — the whole point of
+ * the null contract survives the export, so a spreadsheet can't silently turn
+ * "not reported" into "zero".
+ */
+import { Store, decodeRecord } from '../core/store.js';
+
+export const RECORD_COLUMNS = [
+  ['timestamp', 'ts'],
+  ['date', 'd'],
+  ['hour', 'h'],
+  ['provider', 'p'],
+  ['model', 'm'],
+  ['model_family', 'mf'],
+  ['gateway', 'g'],
+  ['client', 'c'],
+  ['interface', 'i'],
+  ['input_tokens', 'in'],
+  ['output_tokens', 'ou'],
+  ['cache_read_tokens', 'cr'],
+  ['cache_write_tokens', 'cw'],
+  ['cache_refresh_tokens', 'cf'],
+  ['reasoning_tokens', 'rs'],
+  ['total_tokens', 'tt'],
+  ['total_is_partial', 'tp'],
+  ['session_id', 's'],
+  ['conversation_id', 'cv'],
+  ['request_id', 'rq'],
+  ['project', 'pj'],
+  ['repository', 'rp'],
+  ['git_branch', 'br'],
+  ['category', 'k'],
+  ['service_tier', 'tr'],
+  ['estimated_cost', 'co'],
+  ['cost_basis', 'cb'],
+  ['measurement', 'ms'],
+  ['source', 'so'],
+  ['duration_ms', 'du'],
+  ['user', 'u'],
+  ['machine', 'mc'],
+];
+
+export function csvCell(v) {
+  if (v === null || v === undefined) return '';
+  if (typeof v === 'boolean') return v ? 'true' : 'false';
+  const s = String(v);
+  return /[",\n\r]/.test(s) ? '"' + s.replace(/"/g, '""') + '"' : s;
+}
+
+export function csvLine(values) {
+  return values.map(csvCell).join(',') + '\n';
+}
+
+/**
+ * Stream records as CSV.
+ * @param {(chunk:string)=>void} write
+ * @param {object} filter same shape as queryRecords
+ */
+export function streamRecordsCsv(write, filter = {}) {
+  const store = new Store();
+  write(csvLine(RECORD_COLUMNS.map(([name]) => name)));
+  let n = 0;
+  const from = filter.from || null;
+  const to = filter.to || null;
+  const sets = {};
+  for (const [k, key] of [['provider', 'p'], ['model', 'm'], ['client', 'c'], ['interface', 'i'], ['project', 'pj'], ['source', 'so'], ['measurement', 'ms']]) {
+    const v = filter[k];
+    if (v) sets[key] = new Set(Array.isArray(v) ? v : String(v).split(',').map((s) => s.trim()));
+  }
+  let buf = '';
+  store.scanRecords((o) => {
+    if (from && o.d < from) return;
+    if (to && o.d > to) return;
+    for (const [key, set] of Object.entries(sets)) if (!set.has(o[key])) return;
+    buf += csvLine(RECORD_COLUMNS.map(([, k]) => (k === 'tp' ? !!o[k] : o[k])));
+    n++;
+    if (buf.length > 1 << 18) { write(buf); buf = ''; }
+  });
+  if (buf) write(buf);
+  return n;
+}
+
+/** Aggregated CSV of any computed table (used by per-chart "export table"). */
+export function tableToCsv(columns, rows) {
+  let out = csvLine(columns.map((c) => c.label ?? c.key));
+  for (const r of rows) out += csvLine(columns.map((c) => (typeof c.value === 'function' ? c.value(r) : r[c.key])));
+  return out;
+}
+
+/** tokenflow-usage-2026-08-20.csv */
+export function exportFilename(prefix = 'tokenflow-usage', date = new Date(), ext = 'csv') {
+  const d = date.toISOString().slice(0, 10);
+  return `${prefix}-${d}.${ext}`;
+}

package/src/export/html-snapshot.js

@@ -0,0 +1,101 @@
+/**
+ * Self-contained HTML snapshot.
+ *
+ * One file: inlined CSS, an inlined bundle of the same analytics + chart code
+ * the live dashboard uses, and the data bundle embedded as JSON. It opens from
+ * a file:// URL with no server, no network and no build step, which makes it
+ * the thing you can archive, attach, or hand to someone else.
+ *
+ * The ↻ Refresh button is hidden in a snapshot (there is nothing to re-read),
+ * and a bounded sample of request-level records is embedded so the Data
+ * Explorer and CSV export still work offline.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import { bundle } from './bundler.js';
+import { buildBundle, rootDir } from '../core/bundle.js';
+import { Store } from '../core/store.js';
+import { loadConfig } from '../core/config.js';
+
+function candidatePorts() {
+  let configured = null;
+  try { configured = loadConfig().ui?.port || null; } catch { configured = null; }
+  return [...new Set([configured, 7799, 7800, 8799].filter(Boolean))];
+}
+
+export function buildSnapshot({ maxRecords = 20000, title = 'Tokenflow' } = {}) {
+  const ROOT = rootDir();
+  const css = fs.readFileSync(path.join(ROOT, 'src', 'ui', 'styles.css'), 'utf8');
+  const html = fs.readFileSync(path.join(ROOT, 'src', 'ui', 'index.html'), 'utf8');
+  const js = bundle(path.join(ROOT, 'src', 'ui', 'app.js'), { root: ROOT });
+  // A snapshot that does not parse is worse than a failed export, so check the
+  // bundle compiles before writing it. `new vm.Script` parses without running.
+  try {
+    new vm.Script(js, { filename: 'tokenflow-snapshot-bundle.js' });
+  } catch (err) {
+    throw new Error(`snapshot bundle failed to compile: ${err.message}`);
+  }
+  const data = buildBundle();
+
+  // Newest records first, capped — an archive should stay a file, not a dump.
+  const store = new Store();
+  const recs = [];
+  store.scanRecords((o) => {
+    recs.push(o);
+    if (recs.length > maxRecords * 3) {
+      recs.sort((a, b) => (a.ts < b.ts ? 1 : -1));
+      recs.length = maxRecords;
+    }
+  });
+  recs.sort((a, b) => (a.ts < b.ts ? 1 : -1));
+  const records = recs.slice(0, maxRecords);
+
+  // NOTE: every replacement below passes a FUNCTION, never a string. A string
+  // replacement expands `$&`, `$1` and especially `$'` (the text after the
+  // match) — and the code being inlined contains `'$' + n.toFixed(2)`, which
+  // would silently splice the rest of the document into the middle of a string
+  // literal and produce an unparseable snapshot.
+  const dataScript = [
+    '<script>',
+    `window.__TOKENFLOW_BUNDLE__ = ${safeJson(data)};`,
+    `window.__TOKENFLOW_RECORDS__ = ${safeJson(records)};`,
+    `window.__TOKENFLOW_SNAPSHOT_AT__ = ${JSON.stringify(new Date().toISOString())};`,
+    // Where to look for a live dashboard when this file is opened later: the
+    // configured port first, then the usual fallbacks the server tries.
+    `window.__TOKENFLOW_PORTS__ = ${JSON.stringify(candidatePorts())};`,
+    '</scr' + 'ipt>',
+    '<script>',
+    js,
+    '</scr' + 'ipt>',
+  ].join('\n');
+
+  const body = html
+    .replace(/<link rel="stylesheet"[^>]*>/, () => `<style>\n${css}\n</style>`)
+    .replace(/<script type="module" src="[^"]*"><\/script>/, () => dataScript)
+    .replace('<title>Tokenflow</title>', () => `<title>${escapeHtml(title)}</title>`)
+    .replace('loading…', () => 'static snapshot');
+
+  return {
+    html: body,
+    stats: {
+      bytes: Buffer.byteLength(body),
+      records: records.length,
+      recordsTruncated: recs.length > records.length || records.length === maxRecords,
+      cubeRows: data.cube.rows.length,
+      sessions: data.sessions.length,
+    },
+  };
+}
+
+/** JSON safe to embed inside a <script> tag. */
+function safeJson(v) {
+  return JSON.stringify(v)
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+}
+function escapeHtml(s) {
+  return String(s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]));
+}

package/src/export/menubar.js

@@ -0,0 +1,158 @@
+/**
+ * Menu-bar surfaces for external bars (SwiftBar / xbar and compatible).
+ *
+ * TokenFlow stays zero-dependency and out of your way: rather than shipping an
+ * always-running Electron tray, it renders the same live status snapshot into
+ * whatever menu bar you already run. One text protocol covers them all —
+ * SwiftBar, xbar, Argos, Waybar's custom modules — so this file is pure string
+ * shaping over `buildLiveStatus()` output.
+ *
+ *   line 1            becomes the menu-bar title
+ *   "--" prefixed     become dropdown items ("----" alone is a separator)
+ *   "| key=value…"    attach actions (href, bash, refresh…)
+ */
+import { fileURLToPath } from 'node:url';
+import fs from 'node:fs';
+import path from 'node:path';
+import { barLine, countdown, compactTokens, money } from '../core/live-status.js';
+import { processAlive } from '../core/watch.js';
+
+/** Absolute path of this clone's CLI — stable across working directories. */
+export function cliPath() {
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'bin', 'tokenflow.js');
+}
+
+const GLYPH = { ok: '', warn: '⚠ ', exceeded: '✗' };
+
+/**
+ * Render the full xbar-format text for a live status snapshot.
+ * @param {object} status live status (see core/live-status.js)
+ * @param {{mode?:string, dashboardUrl?:string}} opt
+ */
+export function renderXbar(status, opt = {}) {
+  const mode = opt.mode || 'auto';
+  const url = opt.dashboardUrl || 'http://127.0.0.1:7799';
+  const lines = [];
+
+  const head = barLine(status, mode);
+  const empty = head.text.trim().endsWith('—');
+  // SwiftBar re-renders on any stdout change; the href makes the whole bar
+  // clickable into the dashboard.
+  lines.push(head.text + (empty ? '' : ` | href=${url}`));
+  if (!status.usage && !status.capacity) {
+    lines.push('No data yet — run `tokenflow setup && tokenflow refresh`', `Open docs | href=${url}`);
+    return lines.join('\n');
+  }
+  lines.push('---');
+
+  const u = status.usage?.today || {};
+  const t = u.tokens || {};
+  lines.push(
+    `Today: ${compactTokens(t.total ?? 0)} tokens${costSuffix(u)} · ${u.requests ?? 0} requests | href=${url}`,
+  );
+  const w = status.usage?.weekToDate || {};
+  const m = status.usage?.monthToDate || {};
+  lines.push(`Week: ${compactTokens(w.tokens?.total ?? 0)}${costSuffix(w)}`);
+  lines.push(`Month: ${compactTokens(m.tokens?.total ?? 0)}${costSuffix(m)}`);
+  if (u.sessions != null) lines.push(`Sessions today: ${u.sessions}`);
+
+  // ---- by source / by model -------------------------------------------------
+  // Source = the tool that wrote the log (claude-code, opencode, hermes…).
+  // Provider rows name each model's vendor, so Hermes traffic appears under
+  // its vendors there; "by source" is where Hermes shows as itself.
+  const sources = status.sourcesToday || [];
+  const models = status.modelsToday || [];
+  if (sources.length || models.length) {
+    lines.push('---');
+    for (const p of sources.slice(0, 6)) {
+      lines.push(`source ${p.key}: ${compactTokens(p.tokens ?? 0)}${costSuffix(p)} · ${p.requests ?? 0} req | font-size=12`);
+    }
+    for (const mrow of models.slice(0, 5)) {
+      lines.push(`model ${mrow.key}: ${compactTokens(mrow.tokens ?? 0)}${costSuffix(mrow)} | font-size=12`);
+    }
+  }
+
+  // ---- limits -------------------------------------------------------------
+  const states = status.capacity?.states || [];
+  if (states.length) {
+    lines.push('---');
+    for (const s of states.slice(0, 6)) {
+      const pctText = s.pctUsed == null ? '—' : `${Math.round(s.pctUsed * 100)}%`;
+      const resetIn = s.resetsInMs != null ? `, resets in ${countdown(s.resetsInMs)}` : '';
+      const eta = s.etaHours != null ? ` · ETA ${countdown(s.etaHours * 3600000)}` : '';
+      lines.push(`${GLYPH[s.status] || ''}${s.label}: ${pctText}${resetIn}${eta} | font-size=12`);
+    }
+  }
+
+  // ---- forecast -----------------------------------------------------------
+  const f = status.forecast;
+  if (f && f.tomorrow !== null && f.confidence) {
+    lines.push('---');
+    lines.push(`Tomorrow (projected): ${compactTokens(f.tomorrow)} | font-size=12`);
+    if (f.monthEnd !== null) lines.push(`Month-end (projected): ${compactTokens(f.monthEnd)} | font-size=12`);
+    if (f.monthEndCost !== null) lines.push(`Month-end spend (projected): ${money(f.monthEndCost)} est. | font-size=12`);
+    lines.push(`Confidence: ${f.confidence}${f.n ? ` (${f.n}-day trend)` : ''} | font-size=11`);
+  }
+
+  // ---- anomalies ----------------------------------------------------------
+  const alerts = (status.anomalies || []).filter((a) => a.severity === 'high' || a.severity === 'warn');
+  if (alerts.length) {
+    lines.push('---');
+    for (const a of alerts.slice(0, 3)) {
+      lines.push(`${a.severity === 'high' ? '‼️' : '⚠️'} ${a.detail.replace(/\|/g, '/')} | font-size=12`);
+    }
+  }
+
+  // ---- freshness + actions ------------------------------------------------
+  lines.push('---');
+  const fr = status.freshness || {};
+  const age = fr.ageMs != null ? countdown(fr.ageMs) : null;
+  lines.push(
+    `${fr.stale ? 'Data stale' : 'Updated'}${age ? ` ${age} ago` : ''} | font-size=11`,
+  );
+  const watcher = status.watcher;
+  const alive = !!(watcher?.pid && processAlive(watcher.pid));
+  lines.push(
+    alive
+      ? `Watcher: running (pid ${watcher.pid}, every ${watcher.intervalSeconds ?? '?'}s) | font-size=11`
+      : 'Watcher: not running — `tokenflow watch` | font-size=11',
+  );
+  lines.push(`Refresh now | bash=/usr/bin/env param1=node param2=${cliPath()} param3=refresh terminal=true refresh=true`);
+  lines.push(`Open Dashboard | href=${url}`);
+  return lines.join('\n');
+}
+
+function costSuffix(slice) {
+  const c = slice?.cost ?? slice?.costMeasured;
+  return c != null ? ` · ${money(c)}` : '';
+}
+
+/**
+ * The tiny shell wrapper SwiftBar/xbar execute on their own schedule.
+ * Kept minimal on purpose: everything dynamic happens inside Node.
+ */
+export function swiftBarScript({ nodeBin = 'node', cli = 'bin/tokenflow.js', mode = 'auto', intervalMinutes = 2 } = {}) {
+  return `#!/bin/bash
+# TokenFlow menu-bar plugin — generated by \`tokenflow menubar --swiftbar\`.
+# Refreshes every ${intervalMinutes} min (filename convention). Requires nothing but Node.
+export TOKENFLOW_MENUBAR_MODE="${mode}"
+exec "${nodeBin}" "${cli}" menubar --render
+`;
+}
+
+/**
+ * Install (or refresh) the plugin into a SwiftBar plugin directory.
+ * Returns the written path.
+ */
+export function installSwiftBarPlugin({ dir, mode = 'auto', intervalMinutes = 2 }) {
+  const file = path.join(dir, `tokenflow.${intervalMinutes}m.sh`);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(file, swiftBarScript({
+    nodeBin: process.execPath,
+    cli: cliPath(),
+    mode,
+    intervalMinutes,
+  }));
+  fs.chmodSync(file, 0o755);
+  return file;
+}