@idl3/claude-control 0.1.0

package/lib/transcript.js

@@ -0,0 +1,451 @@
+// lib/transcript.js — bounded transcript tailing for claude-cockpit.
+// Resource doctrine: NEVER read a whole file. Initial load reads only the last
+// min(size, 1 MB) bytes (tail), then watches and reads ONLY new bytes via offset.
+// Files can be 200 MB+; whole-file reads will blow RAM.
+
+import fs from 'node:fs';
+import { EventEmitter } from 'node:events';
+
+const TAIL_MAX_BYTES = 1 * 1024 * 1024; // 1 MB initial tail cap
+
+// ---------------------------------------------------------------------------
+// Internal helper: read the last `maxBytes` of a file without loading it all.
+// Returns a Buffer of at most maxBytes bytes from the end of the file.
+// ---------------------------------------------------------------------------
+async function readTail(filePath, maxBytes) {
+  const stat = await fs.promises.stat(filePath);
+  const size = stat.size;
+  if (size === 0) return { buf: Buffer.alloc(0), readFrom: 0, fileSize: 0 };
+  const readFrom = Math.max(0, size - maxBytes);
+  const toRead = size - readFrom;
+  const buf = Buffer.allocUnsafe(toRead);
+  const fh = await fs.promises.open(filePath, 'r');
+  try {
+    let totalRead = 0;
+    while (totalRead < toRead) {
+      const { bytesRead } = await fh.read(buf, totalRead, toRead - totalRead, readFrom + totalRead);
+      if (bytesRead === 0) break;
+      totalRead += bytesRead;
+    }
+    return { buf: buf.slice(0, totalRead), readFrom, fileSize: size };
+  } finally {
+    await fh.close();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Read bytes [start, end) from an open path. Returns a Buffer.
+// ---------------------------------------------------------------------------
+async function readRange(filePath, start, end) {
+  if (end <= start) return Buffer.alloc(0);
+  const toRead = end - start;
+  const buf = Buffer.allocUnsafe(toRead);
+  const fh = await fs.promises.open(filePath, 'r');
+  try {
+    let totalRead = 0;
+    while (totalRead < toRead) {
+      const { bytesRead } = await fh.read(buf, totalRead, toRead - totalRead, start + totalRead);
+      if (bytesRead === 0) break;
+      totalRead += bytesRead;
+    }
+    return buf.slice(0, totalRead);
+  } finally {
+    await fh.close();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Flatten tool_result content: string | {type:'text',text}[] -> string
+// ---------------------------------------------------------------------------
+function flattenContent(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content
+      .filter((b) => b && b.type === 'text')
+      .map((b) => b.text ?? '')
+      .join('');
+  }
+  return '';
+}
+
+// ---------------------------------------------------------------------------
+// Build a one-line <=120-char summary of a tool_use input object.
+// ---------------------------------------------------------------------------
+function inputSummary(input) {
+  if (input == null) return '';
+  let s;
+  try {
+    s = JSON.stringify(input);
+  } catch {
+    s = String(input);
+  }
+  // Collapse newlines/tabs to spaces, then truncate.
+  s = s.replace(/[\r\n\t]+/g, ' ');
+  if (s.length > 120) s = s.slice(0, 117) + '...';
+  return s;
+}
+
+// ---------------------------------------------------------------------------
+// parseRecord(line) -> NormalizedMessage | null
+//
+// Parses one JSONL line. Only type:"user" and type:"assistant" produce messages.
+// All other types (summary, last-prompt, tool, etc.) return null.
+// ---------------------------------------------------------------------------
+export function parseRecord(line) {
+  const trimmed = line.trim();
+  if (!trimmed) return null;
+
+  let record;
+  try {
+    record = JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+
+  const rawType = record.type;
+  if (rawType !== 'user' && rawType !== 'assistant') return null;
+
+  const msg = record.message;
+  if (!msg) return null;
+
+  const role = rawType; // 'user' | 'assistant'
+  const uuid = record.uuid ?? null;
+  const ts = record.timestamp ?? null;
+
+  // Normalize content -> Block[]
+  const rawContent = msg.content;
+  let blocks = [];
+
+  if (typeof rawContent === 'string') {
+    // User prompt as plain string.
+    blocks = [{ kind: 'text', text: rawContent }];
+  } else if (Array.isArray(rawContent)) {
+    for (const block of rawContent) {
+      if (!block || typeof block !== 'object') continue;
+      const btype = block.type;
+
+      if (btype === 'text') {
+        blocks.push({ kind: 'text', text: block.text ?? '' });
+
+      } else if (btype === 'thinking') {
+        blocks.push({ kind: 'thinking', text: block.thinking ?? block.text ?? '' });
+
+      } else if (btype === 'tool_use') {
+        blocks.push({
+          kind: 'tool_use',
+          id: block.id ?? null,
+          name: block.name ?? '',
+          input: block.input ?? {},
+          inputSummary: inputSummary(block.input),
+        });
+
+      } else if (btype === 'tool_result') {
+        blocks.push({
+          kind: 'tool_result',
+          forId: block.tool_use_id ?? null,
+          text: flattenContent(block.content),
+          isError: !!block.is_error,
+        });
+      }
+      // Unknown block types are silently skipped.
+    }
+  }
+
+  return { uuid, role, ts, blocks, rawType };
+}
+
+// ---------------------------------------------------------------------------
+// TranscriptTailer — EventEmitter that tails a single JSONL transcript file.
+//
+// Events:
+//   'append'  (msgs: NormalizedMessage[])   new messages parsed since last read
+//   'pending' (p: Pending | null)           AskUserQuestion open/close state changed
+//   'error'   (err)
+// ---------------------------------------------------------------------------
+export class TranscriptTailer extends EventEmitter {
+  /**
+   * @param {string} filePath
+   * @param {{ maxBuffer?: number, debounceMs?: number }} options
+   */
+  constructor(filePath, { maxBuffer = 500, debounceMs = 150 } = {}) {
+    super();
+    this._filePath = filePath;
+    this._maxBuffer = maxBuffer;
+    this._debounceMs = debounceMs;
+
+    /** @type {import('./transcript.js').NormalizedMessage[]} */
+    this._messages = [];
+
+    /** Byte offset: next read starts here. */
+    this._offset = 0;
+
+    /** Partial line leftover from the last incremental read. */
+    this._leftover = '';
+
+    /** Map of open AskUserQuestion tool_use_id -> Pending */
+    this._pendingMap = new Map();
+
+    /** The currently-reported Pending (what we last emitted). null = none. */
+    this._currentPending = null;
+
+    /** fs.FSWatcher | null */
+    this._watcher = null;
+
+    /** Debounce timer handle */
+    this._debounceTimer = null;
+
+    /** Serializes _readIncremental so two reads can't double-consume bytes. */
+    this._reading = false;
+
+    /** Set by stop(); guards against attaching a watcher after teardown. */
+    this._stopped = false;
+  }
+
+  // -------------------------------------------------------------------------
+  // Public API
+  // -------------------------------------------------------------------------
+
+  /** Full buffered message list (up to maxBuffer most recent). */
+  getMessages() {
+    return this._messages.slice();
+  }
+
+  /** Most-recently-opened still-open Pending, or null. */
+  getPending() {
+    return this._currentPending;
+  }
+
+  /** Drop all but the most recent `keepN` buffered messages (memory pressure relief). */
+  trim(keepN) {
+    if (keepN >= 0 && this._messages.length > keepN) {
+      this._messages = this._messages.slice(this._messages.length - keepN);
+    }
+  }
+
+  /**
+   * Perform the bounded initial tail load, set the byte offset, then start
+   * watching for new data. Safe to call only once; calling again is a no-op
+   * if already watching.
+   */
+  async start() {
+    if (this._watcher) return;
+
+    try {
+      await this._initialLoad();
+    } catch (err) {
+      this.emit('error', err);
+      return;
+    }
+
+    // stop() may have been called while the bounded tail read was awaiting
+    // (e.g. the subscribing client disconnected mid-load). Don't attach a
+    // watcher to a tailer nobody is listening to — that would leak an fd.
+    if (this._stopped) return;
+
+    // Start watching. Use 'rename' events too (handles log rotation).
+    try {
+      this._watcher = fs.watch(this._filePath, { persistent: false }, () => {
+        this._scheduleRead();
+      });
+      this._watcher.on('error', (err) => this.emit('error', err));
+    } catch (err) {
+      this.emit('error', err);
+      return;
+    }
+
+    // Bridge the race window: bytes may have arrived between the initial stat
+    // (which set this._offset) and the watcher being registered by the OS.
+    // Kick off an immediate incremental read to catch any bytes missed in that gap.
+    // Use setImmediate to let the watcher finish OS-level registration first.
+    setImmediate(() => {
+      if (!this._watcher) return; // stop() was called before this fired
+      this._readIncremental().catch((err) => {
+        // ENOENT means the file was deleted/rotated; not a hard error here.
+        if (err.code !== 'ENOENT') this.emit('error', err);
+      });
+    });
+  }
+
+  /** Stop watching, cancel any pending debounce. */
+  stop() {
+    this._stopped = true;
+    if (this._debounceTimer !== null) {
+      clearTimeout(this._debounceTimer);
+      this._debounceTimer = null;
+    }
+    if (this._watcher) {
+      try { this._watcher.close(); } catch { /* ignore */ }
+      this._watcher = null;
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Private helpers
+  // -------------------------------------------------------------------------
+
+  /** Load the last TAIL_MAX_BYTES, parse, populate buffer, set offset. */
+  async _initialLoad() {
+    const { buf, readFrom, fileSize } = await readTail(this._filePath, TAIL_MAX_BYTES);
+    this._offset = fileSize;
+
+    if (buf.length === 0) return;
+
+    const text = buf.toString('utf8');
+    let lines = text.split('\n');
+
+    // If we started reading mid-file, the first segment is a partial line.
+    // Drop it unless we read from byte 0.
+    if (readFrom > 0) {
+      lines = lines.slice(1);
+    }
+
+    // Trailing partial: if text doesn't end with \n, the last element is an
+    // in-progress record. Carry it as leftover (offset already points past it),
+    // so the next incremental read reassembles the full record instead of
+    // dropping it.
+    this._leftover = '';
+    if (text.length > 0 && text[text.length - 1] !== '\n') {
+      this._leftover = lines[lines.length - 1];
+      lines = lines.slice(0, -1);
+    }
+
+    const parsed = [];
+    for (const line of lines) {
+      const msg = parseRecord(line);
+      if (msg) {
+        parsed.push(msg);
+        this._trackPending(msg);
+      }
+    }
+
+    // Cap buffer.
+    const all = parsed;
+    if (all.length > this._maxBuffer) {
+      this._messages = all.slice(all.length - this._maxBuffer);
+    } else {
+      this._messages = all;
+    }
+
+    // Emit initial pending state (so a question already on-screen is detected).
+    this._syncPending();
+  }
+
+  _scheduleRead() {
+    if (this._debounceTimer !== null) return;
+    this._debounceTimer = setTimeout(() => {
+      this._debounceTimer = null;
+      this._readIncremental().catch((err) => this.emit('error', err));
+    }, this._debounceMs);
+  }
+
+  async _readIncremental() {
+    if (this._stopped) return;
+    // Serialize: if a read is already in flight, ask for another pass after it
+    // finishes rather than double-consuming the same byte range.
+    if (this._reading) {
+      this._scheduleRead();
+      return;
+    }
+    this._reading = true;
+    try {
+      let stat;
+      try {
+        stat = await fs.promises.stat(this._filePath);
+      } catch (err) {
+        this.emit('error', err);
+        return;
+      }
+
+      const newSize = stat.size;
+
+      // Truncation / log rotation: the file is effectively new. Re-initialize
+      // from the bounded tail so we never read a multi-MB replacement in full.
+      if (newSize < this._offset) {
+        this._leftover = '';
+        this._pendingMap.clear();
+        await this._initialLoad();
+        return;
+      }
+
+      if (newSize <= this._offset) return; // Nothing new.
+
+      const rawBuf = await readRange(this._filePath, this._offset, newSize);
+      this._offset = newSize;
+
+      const chunk = this._leftover + rawBuf.toString('utf8');
+      const lines = chunk.split('\n');
+
+      // Last element: may be an incomplete line if no trailing newline.
+      this._leftover = lines[lines.length - 1];
+      // Guard against a pathological never-newline-terminated line growing
+      // without bound (honors the same 1 MB ceiling as the initial tail).
+      if (this._leftover.length > TAIL_MAX_BYTES) this._leftover = '';
+      const complete = lines.slice(0, -1);
+
+      const newMsgs = [];
+      for (const line of complete) {
+        const msg = parseRecord(line);
+        if (msg) {
+          newMsgs.push(msg);
+          this._trackPending(msg);
+        }
+      }
+
+      if (newMsgs.length > 0) {
+        // Append to buffer, cap at maxBuffer.
+        this._messages.push(...newMsgs);
+        if (this._messages.length > this._maxBuffer) {
+          this._messages = this._messages.slice(this._messages.length - this._maxBuffer);
+        }
+        this.emit('append', newMsgs);
+      }
+
+      this._syncPending();
+    } finally {
+      this._reading = false;
+    }
+  }
+
+  /**
+   * Inspect a newly-parsed message for AskUserQuestion tool_use blocks
+   * (adds to pendingMap) and tool_result blocks (closes them).
+   */
+  _trackPending(msg) {
+    for (const block of msg.blocks) {
+      if (block.kind === 'tool_use' && block.name === 'AskUserQuestion') {
+        // input.questions is the questions array per CONTRACT spec.
+        const questions = Array.isArray(block.input?.questions)
+          ? block.input.questions
+          : [];
+        this._pendingMap.set(block.id, {
+          toolUseId: block.id,
+          ts: msg.ts,
+          questions,
+        });
+      } else if (block.kind === 'tool_result' && block.forId) {
+        this._pendingMap.delete(block.forId);
+      }
+    }
+  }
+
+  /**
+   * Derive the effective pending (most-recently-opened still-open entry).
+   * Emit 'pending' only when it actually changes.
+   */
+  _syncPending() {
+    // Most-recently-opened = last entry in insertion order of the Map.
+    let latest = null;
+    for (const v of this._pendingMap.values()) {
+      latest = v; // last wins (Map preserves insertion order)
+    }
+
+    // Compare by toolUseId; null == null.
+    const prevId = this._currentPending?.toolUseId ?? null;
+    const nextId = latest?.toolUseId ?? null;
+
+    if (prevId !== nextId) {
+      this._currentPending = latest;
+      this.emit('pending', this._currentPending);
+    }
+  }
+}

package/lib/tui.js

@@ -0,0 +1,50 @@
+// lib/tui.js — parse the Claude Code TUI status line from a capture-pane dump.
+//
+// The bottom of a Claude session renders a status line such as:
+//   /claude-cockpit Opus 4.8 (1M context) ctx:35%      Remote Control active
+// and a title rule line such as:
+//   ───────────────────── auto-cleanup-uploads ──
+// We extract the model label, the context-remaining percentage, and (best
+// effort) the title. All fields are optional — older/narrower panes may omit them.
+
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+const CTX_RE = /ctx:\s*(\d+)\s*%/i;
+const MODEL_RE = /\b(Opus|Sonnet|Haiku)\s+[\d.]+(?:\s*\([^)]*\))?/i;
+
+/**
+ * @param {string} capture  raw `tmux capture-pane -p` output (ANSI ok)
+ * @returns {{ ctxPct: number|null, model: string|null }}
+ */
+export function parseTuiStatus(capture) {
+  const text = String(capture || '').replace(ANSI_RE, '');
+
+  let ctxPct = null;
+  const ctxMatch = text.match(CTX_RE);
+  if (ctxMatch) {
+    const n = Number(ctxMatch[1]);
+    if (Number.isFinite(n) && n >= 0 && n <= 100) ctxPct = n;
+  }
+
+  let model = null;
+  const modelMatch = text.match(MODEL_RE);
+  if (modelMatch) model = modelMatch[0].replace(/\s+/g, ' ').trim();
+
+  return { ctxPct, model };
+}
+
+/**
+ * Prettify a transcript model id (e.g. "claude-opus-4-8") into a short label
+ * ("Opus 4.8"). Falls back to the raw id when the shape is unfamiliar.
+ *
+ * @param {string|null} modelId
+ * @returns {string|null}
+ */
+export function prettyModel(modelId) {
+  if (!modelId || typeof modelId !== 'string') return null;
+  const m = modelId.match(/(opus|sonnet|haiku)-(\d+)-(\d+)/i);
+  if (m) {
+    const family = m[1][0].toUpperCase() + m[1].slice(1).toLowerCase();
+    return `${family} ${m[2]}.${m[3]}`;
+  }
+  return modelId;
+}

package/lib/uploads.js

@@ -0,0 +1,42 @@
+// lib/uploads.js — retention sweep for the attachment uploads directory.
+// Deletes files older than ttlMs. Safe to call on a missing directory.
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * Remove files in `dir` whose mtime is older than `ttlMs`.
+ *
+ * @param {string} dir
+ * @param {number} ttlMs    max age in milliseconds
+ * @param {number} [now]    current epoch ms (injectable for tests)
+ * @returns {Promise<{removed:number, kept:number}>}
+ */
+export async function sweepUploads(dir, ttlMs, now = Date.now()) {
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT') return { removed: 0, kept: 0 };
+    throw err;
+  }
+
+  let removed = 0;
+  let kept = 0;
+  for (const e of entries) {
+    if (!e.isFile()) continue;
+    const full = path.join(dir, e.name);
+    try {
+      const st = await fs.stat(full);
+      if (now - st.mtimeMs > ttlMs) {
+        await fs.unlink(full);
+        removed += 1;
+      } else {
+        kept += 1;
+      }
+    } catch {
+      // Ignore per-file races (e.g. concurrently deleted); count nothing.
+    }
+  }
+  return { removed, kept };
+}

package/lib/version.js

@@ -0,0 +1,73 @@
+/**
+ * lib/version.js — release-update detection (git-based).
+ *
+ * claude-control is distributed as a git checkout and updates via `git pull`
+ * (the in-UI "Update now" button), so "is there a new release?" is answered by
+ * comparing the local checkout against its `origin` upstream — accurate, and
+ * immune to npm name-squatting (the public `claude-control`/`claude-cockpit`
+ * names are namesakes, not this project). Version NUMBERS still follow npm
+ * semver via package.json.
+ *
+ * Best-effort + cached: a non-git checkout, missing origin, or offline state
+ * simply reports "no update" and never throws.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFile as _execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFile = promisify(_execFile);
+const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
+const PKG_PATH = path.join(ROOT, 'package.json');
+const REFRESH_MS = 6 * 60 * 60 * 1000; // re-check upstream at most every 6h
+
+/** Running version from package.json. */
+export function currentVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(PKG_PATH, 'utf8')).version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+async function git(args) {
+  const { stdout } = await execFile('git', args, { cwd: ROOT, timeout: 8000 });
+  return stdout.trim();
+}
+
+let cache = { info: null, checkedAt: 0 };
+
+/**
+ * { current, latest, behind, updateAvailable }.
+ * - behind: commits on origin/<branch> not in HEAD.
+ * - latest: version field of origin's package.json (may equal current if the
+ *   upstream bumped commits without bumping the version).
+ */
+export async function getVersionInfo({ force = false, now = Date.now() } = {}) {
+  const current = currentVersion();
+  if (!force && cache.info && now - cache.checkedAt < REFRESH_MS) {
+    return { current, ...cache.info };
+  }
+
+  let behind = 0;
+  let latest = null;
+  try {
+    const branch = await git(['rev-parse', '--abbrev-ref', 'HEAD']);
+    await git(['fetch', '--quiet', 'origin', branch]);
+    behind = parseInt(await git(['rev-list', '--count', `HEAD..origin/${branch}`]), 10) || 0;
+    if (behind > 0) {
+      try {
+        latest = JSON.parse(await git(['show', `origin/${branch}:package.json`])).version || null;
+      } catch {
+        latest = null;
+      }
+    }
+  } catch {
+    // not a git checkout / no origin / offline — treat as up to date.
+  }
+
+  const info = { latest, behind, updateAvailable: behind > 0 };
+  cache = { info, checkedAt: now };
+  return { current, ...info };
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@idl3/claude-control",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Local web UI to watch and drive your Claude Code sessions running in tmux — live transcripts, reply, answer AskUserQuestion, attach files, from a browser or phone.",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "tmux",
+    "dashboard",
+    "agent"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/idl3/claude-control.git"
+  },
+  "homepage": "https://github.com/idl3/claude-control#readme",
+  "bin": {
+    "claude-control": "bin/cli.js"
+  },
+  "files": [
+    "server.js",
+    "lib/",
+    "public/",
+    "web/dist/",
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node server.js",
+    "dev": "node --watch server.js",
+    "test": "node --test",
+    "build:web": "cd web && npm install && npm run build",
+    "build": "npm run build:web",
+    "prepack": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "web-push": "^3.6.7",
+    "ws": "^8.18.0"
+  }
+}