ccsniff 1.0.33 → 1.1.2

package/README.md

@@ -33,6 +33,20 @@ CommonJS:
 const { watch, JsonlWatcher } = require('ccsniff');
 ```
 
+## Mountable Express router (`/v1/history/*`)
+
+ccsniff ships a mountable router that hosts all the read-only history endpoints used by AgentGUI's live client (`/v1/history/snapshot`, `/sessions`, `/sessions/:sid/events`, `/search`, `/stream` SSE, and `POST /reindex`). It reads `~/.claude/projects` by default; override with the `CLAUDE_PROJECTS_DIR` env var. `express` is an optional peer dependency — install it in the host app.
+
+```js
+import express from 'express';
+import { createHistoryRouter } from 'ccsniff';
+
+const app = express();
+app.use(await createHistoryRouter({ projectsDir: process.env.CLAUDE_PROJECTS_DIR }));
+app.listen(3000);
+```
+
+
 ## CLI
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccsniff",
-  "version": "1.0.33",
+  "version": "1.1.2",
   "description": "Watch Claude Code JSONL output files and emit structured events as a Node.js EventEmitter",
   "type": "module",
   "main": "./src/index.js",
@@ -39,5 +39,13 @@
   "homepage": "https://anentrypoint.github.io/ccsniff",
   "engines": {
     "node": ">=18"
+  },
+  "peerDependencies": {
+    "express": "^4 || ^5"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    }
   }
 }

package/src/cli.js

@@ -29,7 +29,7 @@ const FLAGS = {
   string: ['since', 'until', 'before', 'after', 'grep', 'igrep', 'cwd', 'project', 'role', 'type', 'tool', 'session', 'sid', 'parent', 'rollup', 'format', 'sort', 'unsloth', 'unsloth-format'],
   multi: ['grep', 'igrep', 'role', 'type', 'tool', 'session', 'sid', 'project', 'cwd'],
   number: ['limit', 'head', 'tail-n', 'ctx', 'truncate'],
-  bool: ['json', 'ndjson', 'tail', 'f', 'full', 'reverse', 'invert', 'no-subagents', 'only-subagents', 'no-meta', 'only-meta', 'list-sessions', 'list-projects', 'list-tools', 'stats', 'count', 'help', 'h'],
+  bool: ['json', 'ndjson', 'tail', 'f', 'full', 'reverse', 'invert', 'no-subagents', 'only-subagents', 'no-meta', 'only-meta', 'list-sessions', 'list-projects', 'list-tools', 'bash-discipline', 'stats', 'count', 'help', 'h'],
 };
 
 function parseArgs(argv) {
@@ -62,6 +62,7 @@ USAGE
   ccsniff --list-sessions [filters]
   ccsniff --list-projects
   ccsniff --list-tools
+  ccsniff --bash-discipline [--stats]   Bash calls that should have used Read/Glob/Grep
   ccsniff --stats [filters]
 
 TIME (any ISO date, epoch ms, or relative Ns/Nm/Nh/Nd/Nw)
@@ -237,6 +238,38 @@ if (opts['list-projects']) {
   process.exit(0);
 }
 
+// ---------- bash-discipline (flag Bash calls that should have been Read/Glob/Grep/dispatch)
+if (opts['bash-discipline']) {
+  const BAD_LEADING = /^\s*(cat|head|tail|ls|grep|find|sed|awk|echo)\b/;
+  const SLEEP_POLL = /\bsleep\s+\d+\s*;.*(cat|ls|grep|find|head|tail)/;
+  const violations = [];
+  for (const ev of all) {
+    if (!filter(ev)) continue;
+    if (ev.block?.type !== 'tool_use' || ev.block?.name !== 'Bash') continue;
+    const cmd = ev.block?.input?.command || '';
+    const kind = SLEEP_POLL.test(cmd) ? 'sleep-poll' : (BAD_LEADING.test(cmd) ? 'bad-leading-cmd' : null);
+    if (!kind) continue;
+    violations.push({ ts: ev.timestamp, sid: ev.conversation.id, project: path.basename(ev.conversation.cwd || ''), kind, cmd: cmd.slice(0, 200) });
+  }
+  const byKind = new Map();
+  for (const v of violations) byKind.set(v.kind, (byKind.get(v.kind) || 0) + 1);
+  if (opts.stats || opts.count) {
+    if (opts.count) { process.stdout.write(`${violations.length}\n`); process.exit(0); }
+    process.stdout.write(`# ${violations.length} bash-discipline violations\n`);
+    for (const [k, c] of [...byKind.entries()].sort((a, b) => b[1] - a[1])) process.stdout.write(`  ${String(c).padStart(6)}  ${k}\n`);
+    const byProj = new Map();
+    for (const v of violations) byProj.set(v.project, (byProj.get(v.project) || 0) + 1);
+    process.stdout.write(`# by project\n`);
+    for (const [p, c] of [...byProj.entries()].sort((a, b) => b[1] - a[1])) process.stdout.write(`  ${String(c).padStart(6)}  ${p}\n`);
+    process.exit(0);
+  }
+  for (const v of violations) {
+    process.stdout.write(`${new Date(v.ts).toISOString().slice(0, 19)}  ${v.sid.slice(0, 8)}  ${v.kind.padEnd(15)} [${v.project}]  ${v.cmd}\n`);
+  }
+  process.stderr.write(`# ${violations.length} violations (${[...byKind.entries()].map(([k, c]) => `${k}:${c}`).join(' ')})\n`);
+  process.exit(0);
+}
+
 // ---------- list-tools
 if (opts['list-tools']) {
   const tools = new Map();

package/src/index.js

@@ -3,7 +3,8 @@ import path from 'path';
 import os from 'os';
 import { EventEmitter } from 'events';
 
-const DEFAULT_DIR = path.join(os.homedir(), '.claude', 'projects');
+const DEFAULT_DIR = process.env.CLAUDE_PROJECTS_DIR || path.join(os.homedir(), '.claude', 'projects');
+export { DEFAULT_DIR };
 const DEBOUNCE_MS = 16;
 
 export class JsonlWatcher extends EventEmitter {
@@ -265,6 +266,9 @@ export function vault({ projectsDir = DEFAULT_DIR, destDir = path.join(os.homedi
   return { copied, skipped };
 }
 
+export { Store, getStore, flattenEvent, blockText, DEFAULT_PROJECTS_DIR } from './store.js';
+export { createHistoryRouter } from './router.js';
+
 export async function rollup({ projectsDir, since = 0, out, format = 'ndjson' } = {}) {
   if (!out) throw new Error('rollup: out path required');
   const r = new JsonlReplayer(projectsDir);

package/src/router.js

@@ -0,0 +1,86 @@
+// Mountable Express router exposing /v1/history/* — mount at app.use('/', createHistoryRouter()).
+// Express is a peer dependency. Caller must `npm i express`.
+import { Store, getStore, DEFAULT_PROJECTS_DIR } from './store.js';
+
+function loadExpress() {
+  // Lazy import so ccsniff doesn't hard-require express for its other exports.
+  // Caller (e.g. agentgui) already has express in its deps.
+  // eslint-disable-next-line no-undef
+  return import('express').then(m => m.default || m);
+}
+
+export async function createHistoryRouter({ projectsDir, store: providedStore } = {}) {
+  const express = await loadExpress();
+  const router = express.Router();
+  const store = providedStore || getStore(projectsDir || DEFAULT_PROJECTS_DIR);
+
+  const corsHeaders = (res) => {
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Cache-Control', 'no-cache');
+  };
+
+  router.use((req, res, next) => { corsHeaders(res); next(); });
+
+  router.get('/v1/history/snapshot', (req, res) => {
+    try { res.json(store.snapshot()); }
+    catch (e) { res.status(500).json({ error: { message: e.message } }); }
+  });
+
+  router.get('/v1/history/sessions', (req, res) => {
+    try { res.json({ sessions: store.sessions() }); }
+    catch (e) { res.status(500).json({ error: { message: e.message } }); }
+  });
+
+  router.get('/v1/history/sessions/:sid/events', (req, res) => {
+    try { res.json({ sid: req.params.sid, events: store.sessionEvents(req.params.sid) }); }
+    catch (e) { res.status(500).json({ error: { message: e.message } }); }
+  });
+
+  router.get('/v1/history/search', (req, res) => {
+    try {
+      const q = req.query.q || '';
+      const limit = parseInt(req.query.limit, 10) || 50;
+      const opts = { limit };
+      for (const k of ['role', 'type', 'project', 'sid']) {
+        if (req.query[k]) opts[k] = req.query[k];
+      }
+      const results = q ? store.search(q, opts) : [];
+      const hits = results.map(r => ({ sid: r.sid, snippet: r.snippet, score: r.score, ts: r.ts, role: r.role, type: r.type, project: r.project, text: r.text }));
+      res.json({ query: q, hits, results });
+    } catch (e) {
+      res.status(500).json({ error: { message: e.message } });
+    }
+  });
+
+  router.post('/v1/history/reindex', (req, res) => {
+    try { store.rebuildIndex(); res.json({ ok: true, at: store.lastBuilt }); }
+    catch (e) { res.status(500).json({ error: { message: e.message } }); }
+  });
+
+  router.get('/v1/history/stream', (req, res) => {
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      'Connection': 'keep-alive',
+      'Access-Control-Allow-Origin': '*',
+    });
+    res.write('event: hello\ndata: {}\n\n');
+    store.sseClients.add(res);
+    req.on('close', () => store.sseClients.delete(res));
+  });
+
+  // Compatibility GET reindex (some clients may call GET).
+  router.get('/v1/history/reindex', (req, res) => {
+    try { store.rebuildIndex(); res.json({ ok: true, at: store.lastBuilt }); }
+    catch (e) { res.status(500).json({ error: { message: e.message } }); }
+  });
+
+  router.get('/v1/history', (req, res) => {
+    try { res.json(store.snapshot()); }
+    catch (e) { res.status(500).json({ error: { message: e.message } }); }
+  });
+
+  return router;
+}
+
+export { Store, getStore, DEFAULT_PROJECTS_DIR };

package/src/store.js

@@ -0,0 +1,294 @@
+// Shared store for both legacy /api/* (gui-server.js) and new /v1/history/* (router.js).
+import path from 'path';
+import os from 'os';
+import { JsonlReplayer, JsonlWatcher } from './index.js';
+import { buildIndex, search, snippet, tokenize } from './bm25.js';
+
+export const DEFAULT_PROJECTS_DIR =
+  process.env.CLAUDE_PROJECTS_DIR || path.join(os.homedir(), '.claude', 'projects');
+
+export function blockText(b) {
+  if (!b) return '';
+  if (typeof b.text === 'string') return b.text;
+  if (typeof b.content === 'string') return b.content;
+  if (Array.isArray(b.content)) return b.content.map(c => c?.text || '').join('');
+  if (b.input) { try { return JSON.stringify(b.input); } catch { return ''; } }
+  return '';
+}
+
+export function flattenEvent(ev, idx) {
+  const c = ev.conversation || {};
+  const b = ev.block || {};
+  return {
+    i: idx,
+    ts: ev.timestamp || 0,
+    sid: c.id || '',
+    parent: c.parentSid || null,
+    cwd: c.cwd || '',
+    project: path.basename(c.cwd || ''),
+    isSubagent: !!c.isSubagent,
+    role: ev.role,
+    type: b.type || null,
+    tool: b.name || null,
+    text: blockText(b),
+    isError: !!b.is_error || ev.role === 'streaming_error',
+    isMeta: !!b.isMeta,
+    cost: b.total_cost_usd || null,
+    duration: b.duration_ms || null,
+    subtype: b.subtype || null,
+    model: b.model || null,
+  };
+}
+
+export class Store {
+  constructor(projectsDir) {
+    this.projectsDir = projectsDir || DEFAULT_PROJECTS_DIR;
+    this.events = [];
+    this.errors = [];
+    this.fileBytes = 0;
+    this.fileCount = 0;
+    this.index = null;
+    this.lastBuilt = 0;
+    this.watcher = null;
+    this.sseClients = new Set();
+    this.convs = new Map();
+  }
+
+  loadOnce() {
+    const r = new JsonlReplayer(this.projectsDir);
+    let i = 0;
+    r.on('conversation_created', ev => this.convs.set(ev.conversation.id, ev.conversation));
+    r.on('streaming_progress', ev => { this.events.push(flattenEvent(ev, i++)); });
+    r.on('streaming_error', ev => { this.errors.push({ ts: ev.timestamp, sid: ev.conversationId, error: ev.error, recoverable: ev.recoverable }); });
+    const stats = r.replay({});
+    this.fileCount = stats.files;
+    this.rebuildIndex();
+    return stats;
+  }
+
+  rebuildIndex() {
+    this.index = buildIndex(this.events, e => e.text);
+    this.lastBuilt = Date.now();
+  }
+
+  startLive() {
+    if (this.watcher) return;
+    this.watcher = new JsonlWatcher(this.projectsDir);
+    this.watcher.on('conversation_created', ev => {
+      this.convs.set(ev.conversation.id, ev.conversation);
+      this.broadcast('conversation', { conv: ev.conversation, ts: ev.timestamp });
+    });
+    this.watcher.on('streaming_progress', ev => {
+      const fl = flattenEvent(ev, this.events.length);
+      this.events.push(fl);
+      this.broadcast('event', { sid: fl.sid, payload: fl });
+    });
+    this.watcher.on('streaming_error', ev => {
+      const e = { ts: ev.timestamp, sid: ev.conversationId, error: ev.error, recoverable: ev.recoverable };
+      this.errors.push(e);
+      this.broadcast('error', e);
+    });
+    this.watcher.on('streaming_start', ev => this.broadcast('start', { sid: ev.conversationId, ts: ev.timestamp }));
+    this.watcher.on('streaming_complete', ev => this.broadcast('complete', { sid: ev.conversationId, ts: ev.timestamp }));
+    this.watcher.start();
+  }
+
+  stop() {
+    if (this.watcher) this.watcher.stop();
+    for (const r of this.sseClients) try { r.end(); } catch {}
+    this.sseClients.clear();
+  }
+
+  broadcast(kind, data) {
+    const payload = `event: ${kind}\ndata: ${JSON.stringify(data)}\n\n`;
+    for (const res of this.sseClients) { try { res.write(payload); } catch {} }
+  }
+
+  snapshot() {
+    const sids = new Set(), projects = new Set(), tools = new Map();
+    let earliest = Infinity, latest = 0, bytes = 0;
+    for (const e of this.events) {
+      sids.add(e.sid); if (e.project) projects.add(e.project);
+      if (e.tool) tools.set(e.tool, (tools.get(e.tool) || 0) + 1);
+      if (e.ts < earliest) earliest = e.ts;
+      if (e.ts > latest) latest = e.ts;
+      bytes += (e.text || '').length;
+    }
+    return {
+      events: this.events.length,
+      sessions: sids.size,
+      projects: projects.size,
+      tools: tools.size,
+      errors: this.errors.length,
+      files: this.fileCount,
+      bytes,
+      earliest: earliest === Infinity ? 0 : earliest,
+      latest,
+      dateRange: { earliest: earliest === Infinity ? 0 : earliest, latest },
+      indexedAt: this.lastBuilt,
+    };
+  }
+
+  sessions() {
+    const map = new Map();
+    for (const e of this.events) {
+      let s = map.get(e.sid);
+      if (!s) {
+        const conv = this.convs.get(e.sid) || {};
+        s = { sid: e.sid, title: conv.title || '', project: e.project, cwd: e.cwd, parent: e.parent, isSubagent: e.isSubagent, first: e.ts, last: e.ts, events: 0, tools: 0, userTurns: 0, cost: 0, errors: 0 };
+        map.set(e.sid, s);
+      }
+      s.events++;
+      if (e.ts < s.first) s.first = e.ts;
+      if (e.ts > s.last) s.last = e.ts;
+      if (e.type === 'tool_use') s.tools++;
+      if (e.role === 'user' && e.type === 'text') s.userTurns++;
+      if (e.cost) s.cost += e.cost;
+      if (e.isError) s.errors++;
+    }
+    return [...map.values()].sort((a, b) => b.last - a.last);
+  }
+
+  sessionEvents(sid) {
+    return this.events.filter(e => e.sid === sid);
+  }
+
+  projects() {
+    const map = new Map();
+    for (const e of this.events) {
+      if (!e.project) continue;
+      let p = map.get(e.project);
+      if (!p) { p = { project: e.project, sessions: new Set(), events: 0, tools: 0, last: 0, errors: 0, cost: 0 }; map.set(e.project, p); }
+      p.events++;
+      p.sessions.add(e.sid);
+      if (e.type === 'tool_use') p.tools++;
+      if (e.ts > p.last) p.last = e.ts;
+      if (e.cost) p.cost += e.cost;
+      if (e.isError) p.errors++;
+    }
+    return [...map.values()].map(p => ({ ...p, sessions: p.sessions.size })).sort((a, b) => b.last - a.last);
+  }
+
+  tools() {
+    const map = new Map();
+    for (const e of this.events) {
+      if (!e.tool) continue;
+      let t = map.get(e.tool);
+      if (!t) { t = { tool: e.tool, count: 0, sessions: new Set(), errors: 0, last: 0 }; map.set(e.tool, t); }
+      t.count++;
+      t.sessions.add(e.sid);
+      if (e.isError) t.errors++;
+      if (e.ts > t.last) t.last = e.ts;
+    }
+    return [...map.values()].map(t => ({ ...t, sessions: t.sessions.size })).sort((a, b) => b.count - a.count);
+  }
+
+  timeline(bucketMs = 3600_000) {
+    const buckets = new Map();
+    for (const e of this.events) {
+      const k = Math.floor(e.ts / bucketMs) * bucketMs;
+      let b = buckets.get(k);
+      if (!b) { b = { t: k, events: 0, tools: 0, errors: 0, sessions: new Set() }; buckets.set(k, b); }
+      b.events++;
+      if (e.type === 'tool_use') b.tools++;
+      if (e.isError) b.errors++;
+      b.sessions.add(e.sid);
+    }
+    return [...buckets.values()].map(b => ({ ...b, sessions: b.sessions.size })).sort((a, b) => a.t - b.t);
+  }
+
+  stats() {
+    const role = {}, type = {}, model = {};
+    let cost = 0, dur = 0, results = 0;
+    for (const e of this.events) {
+      role[e.role || '?'] = (role[e.role || '?'] || 0) + 1;
+      type[e.type || '?'] = (type[e.type || '?'] || 0) + 1;
+      if (e.model) model[e.model] = (model[e.model] || 0) + 1;
+      if (e.cost) { cost += e.cost; results++; }
+      if (e.duration) dur += e.duration;
+    }
+    return { role, type, model, totalCostUsd: cost, totalDurationMs: dur, results };
+  }
+
+  errorsList() { return this.errors.slice(-200).reverse(); }
+
+  subagents() {
+    const tree = new Map();
+    for (const e of this.events) {
+      if (!e.isSubagent) continue;
+      const parent = e.parent || 'orphan';
+      let p = tree.get(parent);
+      if (!p) { p = { parent, children: new Map() }; tree.set(parent, p); }
+      let c = p.children.get(e.sid);
+      if (!c) { c = { sid: e.sid, project: e.project, events: 0, last: 0 }; p.children.set(e.sid, c); }
+      c.events++;
+      if (e.ts > c.last) c.last = e.ts;
+    }
+    return [...tree.values()].map(p => ({ parent: p.parent, children: [...p.children.values()] }));
+  }
+
+  search(q, { limit = 50, role, type, project, sid } = {}) {
+    if (!this.index) this.rebuildIndex();
+    const hits = search(this.index, q, { limit: limit * 4 });
+    const out = [];
+    for (const h of hits) {
+      const e = this.events[h.i];
+      if (role && e.role !== role) continue;
+      if (type && e.type !== type) continue;
+      if (project && e.project !== project) continue;
+      if (sid && !e.sid.startsWith(sid)) continue;
+      out.push({ ...e, score: h.score, terms: h.terms, snippet: snippet(e.text, h.terms) });
+      if (out.length >= limit) break;
+    }
+    return out;
+  }
+
+  events_filtered({ role, type, project, sid, tool, since, until, limit = 200, offset = 0, q, grep, igrep, isMeta, isSubagent, isError, parent } = {}) {
+    let arr = this.events;
+    let greRe = null, igreRe = null;
+    try {
+      if (grep) greRe = new RegExp(grep, 'i');
+      if (igrep) igreRe = new RegExp(igrep, 'i');
+    } catch (e) {
+      return { total: 0, rows: [], error: `invalid regex: ${e.message}` };
+    }
+    if (q) {
+      const tokens = [...new Set(tokenize(q))];
+      if (tokens.length) {
+        arr = arr.filter(e => { const t = tokenize(e.text); return tokens.every(x => t.includes(x)); });
+      } else {
+        const needle = String(q).toLowerCase();
+        arr = arr.filter(e => (e.text || '').toLowerCase().includes(needle));
+      }
+    }
+    arr = arr.filter(e => {
+      if (role && e.role !== role) return false;
+      if (type && e.type !== type) return false;
+      if (project && e.project !== project) return false;
+      if (sid && !e.sid.startsWith(sid)) return false;
+      if (parent && e.parent !== parent) return false;
+      if (tool && e.tool !== tool) return false;
+      if (since && e.ts < since) return false;
+      if (until && e.ts > until) return false;
+      if (isMeta === true && !e.isMeta) return false;
+      if (isMeta === false && e.isMeta) return false;
+      if (isSubagent === true && !e.isSubagent) return false;
+      if (isSubagent === false && e.isSubagent) return false;
+      if (isError === true && !e.isError) return false;
+      if (isError === false && e.isError) return false;
+      if (greRe && !greRe.test(e.text || '')) return false;
+      if (igreRe && igreRe.test(e.text || '')) return false;
+      return true;
+    });
+    return { total: arr.length, rows: arr.slice(offset, offset + limit) };
+  }
+}
+
+let _shared = null;
+export function getStore(projectsDir) {
+  if (_shared) return _shared;
+  _shared = new Store(projectsDir);
+  _shared.loadOnce();
+  _shared.startLive();
+  return _shared;
+}