tmux-ide 1.2.1 → 2.0.0

package/src/lib/authorship.ts

@@ -0,0 +1,280 @@
+/**
+ * Character-range authorship tracking for plan files.
+ *
+ * Follows the @proof/core marks model: each mark tracks authorship at the
+ * character range level with quote-based re-anchoring when positions shift.
+ *
+ * @module authorship
+ */
+
+// ============================================================================
+// Types (following @proof/core marks model)
+// ============================================================================
+
+export type MarkKind =
+  | "authored"
+  | "approved"
+  | "flagged"
+  | "comment"
+  | "insert"
+  | "delete"
+  | "replace";
+
+export interface MarkRange {
+  from: number;
+  to: number;
+}
+
+export interface Mark {
+  id: string;
+  kind: MarkKind;
+  by: string; // "ai:François" or "human:thijs"
+  at: string; // ISO timestamp
+  range: MarkRange; // character positions in the clean content
+  quote: string; // text content for re-anchoring
+  orphaned?: boolean;
+}
+
+export interface MarksDocument {
+  version: number;
+  marks: Record<string, Mark>;
+}
+
+export interface AuthorshipStats {
+  aiPercent: number;
+  humanPercent: number;
+  totalChars: number;
+}
+
+// ============================================================================
+// Comment block format
+// ============================================================================
+
+const MARKS_START = "<!-- TMUX-IDE:MARKS";
+const MARKS_END = "-->";
+
+// ============================================================================
+// ID generation
+// ============================================================================
+
+let markIdCounter = 0;
+
+export function generateMarkId(): string {
+  return `m${Date.now()}_${++markIdCounter}`;
+}
+
+// ============================================================================
+// Quote normalization (matches @proof/core)
+// ============================================================================
+
+export function normalizeQuote(text: string): string {
+  return text.replace(/\s+/g, " ").trim();
+}
+
+// ============================================================================
+// Extract / Embed
+// ============================================================================
+
+/**
+ * Extract marks from a markdown file.
+ * Returns clean content (without the comment block) and parsed marks.
+ */
+export function extractMarks(markdown: string): {
+  content: string;
+  marks: MarksDocument | null;
+} {
+  const startIdx = markdown.lastIndexOf(MARKS_START);
+  if (startIdx === -1) {
+    return { content: markdown, marks: null };
+  }
+
+  const endIdx = markdown.indexOf(MARKS_END, startIdx + MARKS_START.length);
+  if (endIdx === -1) {
+    return { content: markdown, marks: null };
+  }
+
+  const jsonStr = markdown.slice(startIdx + MARKS_START.length, endIdx).trim();
+  const content = (
+    markdown.slice(0, startIdx) + markdown.slice(endIdx + MARKS_END.length)
+  ).trimEnd();
+
+  try {
+    const data = JSON.parse(jsonStr) as MarksDocument;
+    return { content, marks: data };
+  } catch {
+    return { content, marks: null };
+  }
+}
+
+/**
+ * Embed marks into a markdown file.
+ * Strips any existing marks comment and appends a new one at the end.
+ */
+export function embedMarks(markdown: string, doc: MarksDocument): string {
+  const { content } = extractMarks(markdown);
+  const json = JSON.stringify(doc, null, 2);
+  return `${content}\n\n${MARKS_START}\n${json}\n${MARKS_END}\n`;
+}
+
+// ============================================================================
+// Mark creation helpers
+// ============================================================================
+
+export function createAuthored(by: string, range: MarkRange, quote: string): Mark {
+  return {
+    id: generateMarkId(),
+    kind: "authored",
+    by,
+    at: new Date().toISOString(),
+    range,
+    quote: normalizeQuote(quote),
+  };
+}
+
+// ============================================================================
+// Stats calculation
+// ============================================================================
+
+/**
+ * Calculate AI vs human authorship percentages from marks.
+ * Only counts 'authored' marks. Uses character range lengths.
+ */
+export function calculateStats(marks: Record<string, Mark>): AuthorshipStats {
+  let aiChars = 0;
+  let humanChars = 0;
+
+  for (const mark of Object.values(marks)) {
+    if (mark.kind !== "authored") continue;
+    if (mark.orphaned) continue;
+    const chars = mark.range.to - mark.range.from;
+    if (mark.by.startsWith("ai:") || mark.by === "ai") {
+      aiChars += chars;
+    } else {
+      humanChars += chars;
+    }
+  }
+
+  const totalChars = aiChars + humanChars;
+  if (totalChars === 0) {
+    return { aiPercent: 0, humanPercent: 0, totalChars: 0 };
+  }
+
+  return {
+    aiPercent: Math.round((aiChars / totalChars) * 100),
+    humanPercent: Math.round((humanChars / totalChars) * 100),
+    totalChars,
+  };
+}
+
+// ============================================================================
+// Re-anchoring: recover positions when content shifts
+// ============================================================================
+
+/**
+ * Find the position of a quote in content text.
+ * Returns { from, to } or null if not found.
+ */
+function findQuotePosition(content: string, quote: string): MarkRange | null {
+  if (!quote) return null;
+  const normalized = normalizeQuote(quote);
+  const normalizedContent = normalizeQuote(content);
+  const idx = normalizedContent.indexOf(normalized);
+  if (idx === -1) return null;
+
+  // Map back to original content positions (approximate — whitespace may differ)
+  // Walk through original content counting normalized chars
+  let origFrom = -1;
+  let normalizedPos = 0;
+  for (let i = 0; i < content.length; i++) {
+    if (/\s/.test(content[i]!) && (i === 0 || /\s/.test(content[i - 1]!))) continue;
+    if (normalizedPos === idx && origFrom === -1) origFrom = i;
+    if (normalizedPos === idx + normalized.length) {
+      return { from: origFrom, to: i };
+    }
+    normalizedPos++;
+  }
+
+  // Fallback: simple indexOf on original
+  const simpleIdx = content.indexOf(quote);
+  if (simpleIdx !== -1) {
+    return { from: simpleIdx, to: simpleIdx + quote.length };
+  }
+
+  return null;
+}
+
+/**
+ * Re-anchor marks whose ranges may have shifted due to content edits.
+ * Uses quote text to find new positions. Marks orphaned if quote not found.
+ */
+export function reanchorMarks(content: string, marks: Record<string, Mark>): Record<string, Mark> {
+  const result: Record<string, Mark> = {};
+
+  for (const [id, mark] of Object.entries(marks)) {
+    // Check if current range still matches quote
+    const currentText = content.slice(mark.range.from, mark.range.to);
+    if (normalizeQuote(currentText) === normalizeQuote(mark.quote)) {
+      result[id] = mark;
+      continue;
+    }
+
+    // Try to re-anchor using quote
+    const newRange = findQuotePosition(content, mark.quote);
+    if (newRange) {
+      result[id] = { ...mark, range: newRange, orphaned: false };
+    } else {
+      result[id] = { ...mark, orphaned: true };
+    }
+  }
+
+  return result;
+}
+
+// ============================================================================
+// Tagging: tag entire content as authored by a given actor
+// ============================================================================
+
+/**
+ * Tag the full content as authored by the given actor.
+ * Preserves existing marks and only adds a mark for uncovered ranges.
+ */
+export function tagContent(markdown: string, by: string): string {
+  const { content, marks: existingDoc } = extractMarks(markdown);
+  const existingMarks = existingDoc?.marks ?? {};
+
+  // Re-anchor existing marks against current content
+  const anchored =
+    Object.keys(existingMarks).length > 0 ? reanchorMarks(content, existingMarks) : {};
+
+  // Find uncovered character ranges
+  const covered = new Set<number>();
+  for (const mark of Object.values(anchored)) {
+    if (mark.kind !== "authored" || mark.orphaned) continue;
+    for (let i = mark.range.from; i < mark.range.to && i < content.length; i++) {
+      covered.add(i);
+    }
+  }
+
+  // Build marks for uncovered ranges (coalesce adjacent)
+  const newMarks: Record<string, Mark> = { ...anchored };
+  let rangeStart = -1;
+
+  for (let i = 0; i <= content.length; i++) {
+    const isCovered = covered.has(i);
+    const atEnd = i === content.length;
+
+    if (!isCovered && !atEnd && rangeStart === -1) {
+      rangeStart = i;
+    } else if ((isCovered || atEnd) && rangeStart !== -1) {
+      const quote = content.slice(rangeStart, i);
+      if (quote.trim().length > 0) {
+        const mark = createAuthored(by, { from: rangeStart, to: i }, quote);
+        newMarks[mark.id] = mark;
+      }
+      rangeStart = -1;
+    }
+  }
+
+  const doc: MarksDocument = { version: 2, marks: newMarks };
+  return embedMarks(content, doc);
+}

package/src/lib/cast/recorder.test.ts

@@ -0,0 +1,127 @@
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { AsciicastRecorder } from "./recorder.ts";
+
+describe("AsciicastRecorder", () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "cast-test-"));
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("creates recording directory", () => {
+    const rec = new AsciicastRecorder({
+      dir,
+      session: "test-sess",
+      paneId: "%0",
+    });
+    // Starting will fail since no tmux is running, but the file should be created
+    try {
+      rec.start();
+      rec.stop();
+    } catch {
+      // expected in test environment
+    }
+
+    // The .tasks/recordings/ directory should have been created
+    // existsSync imported at top
+    expect(existsSync(join(dir, ".tasks", "recordings"))).toBe(true);
+  });
+
+  it("writes asciicast v2 header on start", () => {
+    const rec = new AsciicastRecorder({
+      dir,
+      session: "test-sess",
+      paneId: "%0",
+      intervalMs: 60000, // long interval so timer doesn't fire
+    });
+
+    const filePath = rec.start();
+    rec.stop();
+
+    const content = readFileSync(filePath, "utf-8");
+    const lines = content.trim().split("\n");
+    expect(lines.length).toBeGreaterThanOrEqual(1);
+
+    const header = JSON.parse(lines[0]!);
+    expect(header.version).toBe(2);
+    expect(typeof header.width).toBe("number");
+    expect(typeof header.height).toBe("number");
+    expect(typeof header.timestamp).toBe("number");
+    expect(header.width).toBeGreaterThan(0);
+    expect(header.height).toBeGreaterThan(0);
+  });
+
+  it("getFilePath returns the .cast file path", () => {
+    const rec = new AsciicastRecorder({
+      dir,
+      session: "my-session",
+      paneId: "%5",
+    });
+    const path = rec.start();
+    rec.stop();
+    expect(path).toBe(rec.getFilePath());
+    expect(path).toContain(".cast");
+    expect(path).toContain("my-session");
+    expect(path).toContain("5"); // %5 with % stripped
+  });
+
+  it("file is in .tasks/recordings/", () => {
+    const rec = new AsciicastRecorder({
+      dir,
+      session: "s",
+      paneId: "%0",
+    });
+    const path = rec.start();
+    rec.stop();
+    expect(path).toContain(join(".tasks", "recordings"));
+  });
+
+  it("event lines follow asciicast v2 format", () => {
+    // We can't easily capture from a real tmux pane in tests, but we can
+    // verify the header format is correct and that stop doesn't throw.
+    const rec = new AsciicastRecorder({
+      dir,
+      session: "fmt-test",
+      paneId: "%0",
+      intervalMs: 60000,
+    });
+    rec.start();
+    rec.stop();
+
+    const content = readFileSync(rec.getFilePath(), "utf-8");
+    const lines = content.trim().split("\n").filter(Boolean);
+
+    // First line is header
+    const header = JSON.parse(lines[0]!);
+    expect(header.version).toBe(2);
+
+    // Any subsequent lines should be [number, "o", string] arrays
+    for (const line of lines.slice(1)) {
+      const event = JSON.parse(line);
+      expect(Array.isArray(event)).toBe(true);
+      expect(event.length).toBe(3);
+      expect(typeof event[0]).toBe("number"); // elapsed seconds
+      expect(event[1]).toBe("o"); // output event type
+      expect(typeof event[2]).toBe("string"); // data
+    }
+  });
+
+  it("stop is idempotent", () => {
+    const rec = new AsciicastRecorder({
+      dir,
+      session: "s",
+      paneId: "%0",
+      intervalMs: 60000,
+    });
+    rec.start();
+    rec.stop();
+    rec.stop(); // should not throw
+  });
+});

package/src/lib/cast/recorder.ts

@@ -0,0 +1,148 @@
+/**
+ * Records tmux pane output in asciicast v2 format.
+ *
+ * Uses `tmux capture-pane -p -t <paneId>` to snapshot pane content and
+ * emits only the delta between snapshots as asciicast event lines.
+ *
+ * File format (one JSON object per line):
+ *   Line 1 (header): {"version":2,"width":W,"height":H,"timestamp":T}
+ *   Line 2+:         [elapsed_seconds, "o", "data"]
+ *
+ * @see https://docs.asciinema.org/manual/asciicast/v2/
+ */
+
+import { execFileSync } from "node:child_process";
+import { appendFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export interface RecorderOptions {
+  /** Project directory (recordings go in .tasks/recordings/). */
+  dir: string;
+  /** tmux session name. */
+  session: string;
+  /** tmux pane ID (e.g. %0). */
+  paneId: string;
+  /** Capture interval in ms (default 1000). */
+  intervalMs?: number;
+}
+
+export class AsciicastRecorder {
+  private filePath: string;
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private startTime: number = 0;
+  private lastSnapshot: string = "";
+  private session: string;
+  private paneId: string;
+  private intervalMs: number;
+
+  constructor(opts: RecorderOptions) {
+    this.session = opts.session;
+    this.paneId = opts.paneId;
+    this.intervalMs = opts.intervalMs ?? 1000;
+
+    const recDir = join(opts.dir, ".tasks", "recordings");
+    if (!existsSync(recDir)) mkdirSync(recDir, { recursive: true });
+
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    const safePane = this.paneId.replace(/%/g, "");
+    this.filePath = join(recDir, `${this.session}_${safePane}_${ts}.cast`);
+  }
+
+  /** Start recording. Writes the header and begins periodic captures. */
+  start(): string {
+    const { width, height } = this.getPaneSize();
+    this.startTime = Date.now();
+
+    const header = {
+      version: 2,
+      width,
+      height,
+      timestamp: Math.floor(this.startTime / 1000),
+    };
+    writeFileSync(this.filePath, JSON.stringify(header) + "\n");
+    this.lastSnapshot = "";
+
+    this.timer = setInterval(() => this.capture(), this.intervalMs);
+    this.capture(); // immediate first capture
+
+    return this.filePath;
+  }
+
+  /** Stop recording and flush. */
+  stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    // Final capture
+    this.capture();
+  }
+
+  /** Path to the recording file. */
+  getFilePath(): string {
+    return this.filePath;
+  }
+
+  /** Single capture tick — computes delta and appends event. */
+  private capture(): void {
+    try {
+      const current = execFileSync("tmux", ["capture-pane", "-p", "-t", this.paneId], {
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "ignore"],
+      });
+
+      if (current === this.lastSnapshot) return; // no change
+
+      const elapsed = (Date.now() - this.startTime) / 1000;
+      const delta = this.computeDelta(this.lastSnapshot, current);
+      this.lastSnapshot = current;
+
+      if (delta.length === 0) return;
+
+      const event = JSON.stringify([elapsed, "o", delta]);
+      appendFileSync(this.filePath, event + "\n");
+    } catch {
+      // pane gone or tmux not available — stop silently
+    }
+  }
+
+  /** Compute the new/changed content between two snapshots. */
+  private computeDelta(prev: string, current: string): string {
+    if (prev === "") return current;
+
+    const prevLines = prev.split("\n");
+    const curLines = current.split("\n");
+
+    // Find first differing line
+    let firstDiff = 0;
+    while (
+      firstDiff < prevLines.length &&
+      firstDiff < curLines.length &&
+      prevLines[firstDiff] === curLines[firstDiff]
+    ) {
+      firstDiff++;
+    }
+
+    if (firstDiff >= curLines.length) return "";
+
+    // Return the changed portion with ANSI cursor positioning
+    const changedLines = curLines.slice(firstDiff);
+    const moveToLine = `\x1b[${firstDiff + 1};1H`;
+    return moveToLine + changedLines.join("\n");
+  }
+
+  /** Get pane dimensions from tmux. */
+  private getPaneSize(): { width: number; height: number } {
+    try {
+      const raw = execFileSync(
+        "tmux",
+        ["display-message", "-p", "-t", this.paneId, "#{pane_width}\t#{pane_height}"],
+        { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] },
+      ).trim();
+      const [w, h] = raw.split("\t");
+      return { width: parseInt(w!, 10) || 80, height: parseInt(h!, 10) || 24 };
+    } catch {
+      return { width: 80, height: 24 };
+    }
+  }
+}

package/src/lib/daemon-watchdog.ts

@@ -0,0 +1,102 @@
+/**
+ * Minimal crash-recovery watchdog for the tmux-ide daemon.
+ * Respawns daemon.ts on unexpected exits with exponential backoff.
+ * Gives up after 5 crashes within 60 seconds.
+ *
+ * Entry: bun src/lib/daemon-watchdog.ts <session> [port]
+ *
+ * ZERO imports from business logic — this file must never crash
+ * due to broken application code.
+ */
+
+import { spawn, type ChildProcess } from "node:child_process";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { appendFileSync, mkdirSync, existsSync } from "node:fs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const sessionArg = process.argv[2];
+const port = process.argv[3] ?? "0";
+
+if (!sessionArg) {
+  console.error("Usage: daemon-watchdog.ts <session> [port]");
+  process.exit(1);
+}
+
+const session: string = sessionArg;
+
+const daemonScript = resolve(__dirname, "daemon.ts");
+
+let backoffMs = 1000;
+let crashCount = 0;
+let lastCrashTime = 0;
+let child: ChildProcess | null = null;
+
+function logError(msg: string): void {
+  try {
+    const tasksDir = resolve(process.cwd(), ".tasks");
+    if (!existsSync(tasksDir)) mkdirSync(tasksDir, { recursive: true });
+    const entry = JSON.stringify({
+      timestamp: new Date().toISOString(),
+      type: "error",
+      source: "daemon-watchdog",
+      message: msg,
+    });
+    appendFileSync(resolve(tasksDir, "events.log"), entry + "\n");
+  } catch {
+    // If even logging fails, silently continue
+  }
+}
+
+function spawnDaemon(): void {
+  child = spawn("bun", [daemonScript, session, port], {
+    cwd: process.cwd(),
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+
+  // Pipe child stdout/stderr to our own so logs are visible in the detached process
+  child.stdout?.pipe(process.stdout);
+  child.stderr?.pipe(process.stderr);
+
+  child.on("exit", (code) => {
+    child = null;
+
+    // Clean shutdown (code 0) — don't respawn
+    if (code === 0) {
+      process.exit(0);
+    }
+
+    const now = Date.now();
+
+    // Reset crash counter if the last crash was more than 60s ago
+    if (now - lastCrashTime > 60_000) {
+      crashCount = 0;
+      backoffMs = 1000;
+    }
+
+    crashCount++;
+    lastCrashTime = now;
+
+    if (crashCount > 5) {
+      logError(`Daemon crashed ${crashCount} times in 60s — giving up`);
+      process.exit(1);
+    }
+
+    logError(`Daemon exited with code ${code}, respawning in ${backoffMs}ms`);
+    setTimeout(spawnDaemon, backoffMs);
+    backoffMs = Math.min(backoffMs * 2, 30_000);
+  });
+}
+
+// Forward termination signals to the child daemon
+process.on("SIGTERM", () => {
+  if (child) child.kill("SIGTERM");
+  else process.exit(0);
+});
+
+process.on("SIGINT", () => {
+  if (child) child.kill("SIGTERM");
+  else process.exit(0);
+});
+
+spawnDaemon();