@towles/tool 0.0.62 → 0.0.63

package/src/lib/graph/labels.ts

@@ -0,0 +1,87 @@
+import type { JournalEntry } from "./types.js";
+
+/**
+ * Extract a meaningful label from session entries.
+ */
+export function extractSessionLabel(entries: JournalEntry[], sessionId: string): string {
+  let firstUserText: string | undefined;
+  let firstAssistantText: string | undefined;
+  let gitBranch: string | undefined;
+  let slug: string | undefined;
+
+  for (const entry of entries) {
+    // Extract metadata from any entry
+    if (!gitBranch && (entry as any).gitBranch) {
+      gitBranch = (entry as any).gitBranch;
+    }
+    if (!slug && (entry as any).slug) {
+      slug = (entry as any).slug;
+    }
+
+    if (!entry.message) continue;
+
+    // Look for first user message with actual text (not UUID reference)
+    if (!firstUserText && entry.type === "user" && entry.message.role === "user") {
+      const content = entry.message.content;
+      if (typeof content === "string") {
+        // Check if it's a UUID (skip those) or actual text
+        const isUuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(
+          content,
+        );
+        if (!isUuid && content.length > 0) {
+          firstUserText = content;
+        }
+      } else if (Array.isArray(content)) {
+        // Look for text blocks in array content
+        for (const block of content) {
+          if (block.type === "text" && block.text && block.text.length > 0) {
+            firstUserText = block.text;
+            break;
+          }
+        }
+      }
+    }
+
+    // Look for first assistant text response
+    if (!firstAssistantText && entry.type === "assistant" && entry.message.role === "assistant") {
+      const content = entry.message.content;
+      if (Array.isArray(content)) {
+        for (const block of content) {
+          if (block.type === "text" && block.text && block.text.length > 0) {
+            firstAssistantText = block.text;
+            break;
+          }
+        }
+      }
+    }
+
+    // Stop early if we have user text
+    if (firstUserText) break;
+  }
+
+  // Priority: user text > assistant text > git branch > slug > short ID
+  let label = firstUserText || firstAssistantText || gitBranch || slug || sessionId.slice(0, 8);
+
+  // Clean up the label
+  label = label
+    .replace(/^\/\S+\s*/, "") // Remove /command prefixes
+    .replace(/<[^>]+>[^<]*<\/[^>]+>/g, "") // Remove XML-style tags with content
+    .replace(/<[^>]+>/g, "") // Remove remaining XML tags
+    .replace(/^\s*Caveat:.*$/m, "") // Remove caveat lines
+    .replace(/\n.*/g, "") // Take only first line
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\x00-\x1F]+/g, " ") // Replace control characters with space
+    .trim();
+
+  // If still empty or too short, use fallback
+  if (label.length < 3) {
+    label = slug || sessionId.slice(0, 8);
+  }
+
+  // Truncate very long labels (will be smart-truncated in UI based on box size)
+  if (label.length > 80) {
+    label = label.slice(0, 77) + "...";
+  }
+
+  return label;
+}

package/src/lib/graph/parser.test.ts

@@ -0,0 +1,150 @@
+import * as fs from "node:fs";
+import { describe, expect, it, vi } from "vitest";
+
+import { calculateCutoffMs, filterByDays, parseJsonl, quickTokenCount } from "./parser";
+
+vi.mock("node:fs", () => ({
+  readFileSync: vi.fn(),
+}));
+
+const mockedReadFileSync = vi.mocked(fs.readFileSync);
+
+// ── Pure functions (no mocking needed) ──
+
+describe("calculateCutoffMs", () => {
+  it("returns 0 for days <= 0", () => {
+    expect(calculateCutoffMs(0)).toBe(0);
+    expect(calculateCutoffMs(-1)).toBe(0);
+  });
+
+  it("returns a timestamp in the past for positive days", () => {
+    const now = Date.now();
+    const cutoff = calculateCutoffMs(7);
+    const expectedApprox = now - 7 * 24 * 60 * 60 * 1000;
+    // Allow 100ms tolerance for execution time
+    expect(Math.abs(cutoff - expectedApprox)).toBeLessThan(100);
+  });
+
+  it("returns larger cutoff for more days", () => {
+    const cutoff7 = calculateCutoffMs(7);
+    const cutoff30 = calculateCutoffMs(30);
+    expect(cutoff30).toBeLessThan(cutoff7); // Further in the past
+  });
+});
+
+describe("filterByDays", () => {
+  const now = Date.now();
+  const items = [
+    { mtime: now - 1 * 24 * 60 * 60 * 1000, name: "1-day-ago" },
+    { mtime: now - 5 * 24 * 60 * 60 * 1000, name: "5-days-ago" },
+    { mtime: now - 10 * 24 * 60 * 60 * 1000, name: "10-days-ago" },
+    { mtime: now - 20 * 24 * 60 * 60 * 1000, name: "20-days-ago" },
+  ];
+
+  it("returns all items when days <= 0", () => {
+    expect(filterByDays(items, 0)).toEqual(items);
+    expect(filterByDays(items, -5)).toEqual(items);
+  });
+
+  it("filters items older than cutoff", () => {
+    const result = filterByDays(items, 7);
+    expect(result).toHaveLength(2);
+    expect(result.map((i) => i.name)).toEqual(["1-day-ago", "5-days-ago"]);
+  });
+
+  it("returns empty array when all items are too old", () => {
+    const result = filterByDays(items, 0.001); // ~86ms
+    expect(result).toHaveLength(0);
+  });
+
+  it("returns all items when cutoff is very large", () => {
+    const result = filterByDays(items, 365);
+    expect(result).toHaveLength(4);
+  });
+
+  it("handles empty array", () => {
+    expect(filterByDays([], 7)).toEqual([]);
+  });
+});
+
+// ── parseJsonl and quickTokenCount (require fs mock) ──
+
+describe("parseJsonl", () => {
+  it("parses valid JSONL lines", () => {
+    mockedReadFileSync.mockReturnValue(
+      '{"type":"user","sessionId":"s1","timestamp":"2025-01-01T00:00:00Z"}\n{"type":"assistant","sessionId":"s1","timestamp":"2025-01-01T00:01:00Z"}\n',
+    );
+    const entries = parseJsonl("/fake/path.jsonl");
+    expect(entries).toHaveLength(2);
+    expect(entries[0].type).toBe("user");
+    expect(entries[1].type).toBe("assistant");
+  });
+
+  it("skips empty lines", () => {
+    mockedReadFileSync.mockReturnValue(
+      '{"type":"user","sessionId":"s1","timestamp":"t"}\n\n\n{"type":"assistant","sessionId":"s1","timestamp":"t"}\n',
+    );
+    const entries = parseJsonl("/fake/path.jsonl");
+    expect(entries).toHaveLength(2);
+  });
+
+  it("skips invalid JSON lines", () => {
+    mockedReadFileSync.mockReturnValue(
+      '{"type":"user","sessionId":"s1","timestamp":"t"}\nnot-json\n{"type":"assistant","sessionId":"s1","timestamp":"t"}\n',
+    );
+    const entries = parseJsonl("/fake/path.jsonl");
+    expect(entries).toHaveLength(2);
+  });
+
+  it("returns empty array for empty file", () => {
+    mockedReadFileSync.mockReturnValue("");
+    const entries = parseJsonl("/fake/path.jsonl");
+    expect(entries).toHaveLength(0);
+  });
+});
+
+describe("quickTokenCount", () => {
+  it("sums input and output tokens from entries with usage", () => {
+    const lines = [
+      JSON.stringify({
+        message: { usage: { input_tokens: 100, output_tokens: 50 } },
+      }),
+      JSON.stringify({
+        message: { usage: { input_tokens: 200, output_tokens: 75 } },
+      }),
+    ].join("\n");
+    mockedReadFileSync.mockReturnValue(lines);
+    expect(quickTokenCount("/fake/path.jsonl")).toBe(425);
+  });
+
+  it("skips entries without usage", () => {
+    const lines = [
+      JSON.stringify({ message: { content: "text" } }),
+      JSON.stringify({ message: { usage: { input_tokens: 100, output_tokens: 50 } } }),
+    ].join("\n");
+    mockedReadFileSync.mockReturnValue(lines);
+    expect(quickTokenCount("/fake/path.jsonl")).toBe(150);
+  });
+
+  it("returns 0 for unreadable files", () => {
+    mockedReadFileSync.mockImplementation(() => {
+      throw new Error("ENOENT");
+    });
+    expect(quickTokenCount("/missing/file.jsonl")).toBe(0);
+  });
+
+  it("handles entries with partial usage (only input_tokens)", () => {
+    const lines = JSON.stringify({
+      message: { usage: { input_tokens: 100 } },
+    });
+    mockedReadFileSync.mockReturnValue(lines);
+    expect(quickTokenCount("/fake/path.jsonl")).toBe(100);
+  });
+
+  it("skips invalid JSON lines gracefully", () => {
+    mockedReadFileSync.mockReturnValue(
+      '{"message":{"usage":{"input_tokens":50,"output_tokens":50}}}\nbadline\n',
+    );
+    expect(quickTokenCount("/fake/path.jsonl")).toBe(100);
+  });
+});

package/src/lib/graph/parser.ts

@@ -0,0 +1,65 @@
+import * as fs from "node:fs";
+import type { JournalEntry } from "./types.js";
+
+/**
+ * Calculate cutoff timestamp for days filtering.
+ * Returns 0 if days <= 0 (no filtering).
+ */
+export function calculateCutoffMs(days: number): number {
+  return days > 0 ? Date.now() - days * 24 * 60 * 60 * 1000 : 0;
+}
+
+/**
+ * Filter items by mtime against a days cutoff.
+ * Returns all items if days <= 0.
+ */
+export function filterByDays<T extends { mtime: number }>(items: T[], days: number): T[] {
+  const cutoff = calculateCutoffMs(days);
+  if (cutoff === 0) return items;
+  return items.filter((item) => item.mtime >= cutoff);
+}
+
+/**
+ * Parse JSONL file into JournalEntry array.
+ */
+export function parseJsonl(filePath: string): JournalEntry[] {
+  const content = fs.readFileSync(filePath, "utf-8");
+  const entries: JournalEntry[] = [];
+
+  for (const line of content.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      entries.push(JSON.parse(line) as JournalEntry);
+    } catch {
+      // Skip invalid lines
+    }
+  }
+
+  return entries;
+}
+
+/**
+ * Quick token count from a JSONL file without full parsing.
+ */
+export function quickTokenCount(filePath: string): number {
+  try {
+    const content = fs.readFileSync(filePath, "utf-8");
+    let total = 0;
+    for (const line of content.split("\n")) {
+      if (!line.trim()) continue;
+      try {
+        const entry = JSON.parse(line) as JournalEntry;
+        if (entry.message?.usage) {
+          total +=
+            (entry.message.usage.input_tokens || 0) + (entry.message.usage.output_tokens || 0);
+        }
+      } catch {
+        // Skip invalid lines
+      }
+    }
+    return total;
+  } catch {
+    // File unreadable or missing — treat token count as 0
+    return 0;
+  }
+}

package/src/lib/graph/render.ts

@@ -0,0 +1,25 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { BarChartData, TreemapNode } from "./types.js";
+
+// Load HTML template from file (resolved relative to this module)
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_PATH = path.join(__dirname, "..", "graph-template.html");
+
+/**
+ * Generate HTML from treemap data and bar chart data using the template.
+ */
+export function generateTreemapHtml(data: TreemapNode, barChartData: BarChartData): string {
+  const width = 1200;
+  const height = 800;
+
+  // Read template from file and replace placeholders
+  // Use function replacement to avoid special $& $' $` patterns in data being interpreted
+  const template = fs.readFileSync(TEMPLATE_PATH, "utf-8");
+  return template
+    .replace(/\{\{WIDTH\}\}/g, String(width))
+    .replace(/\{\{HEIGHT\}\}/g, String(height))
+    .replace(/\{\{DATA\}\}/g, () => JSON.stringify(data))
+    .replace(/\{\{BAR_CHART_DATA\}\}/g, () => JSON.stringify(barChartData));
+}

package/src/lib/graph/server.ts

@@ -0,0 +1,70 @@
+import * as http from "node:http";
+import { x } from "tinyexec";
+
+/**
+ * Start a local HTTP server to serve the generated HTML.
+ * Tries successive ports if the initial port is in use.
+ * Returns the actual port used.
+ */
+export async function startServer(
+  html: string,
+  filename: string,
+  startPort: number,
+): Promise<{ server: http.Server; port: number }> {
+  const server = http.createServer((req, res) => {
+    if (req.url === "/" || req.url === `/${filename}`) {
+      res.writeHead(200, { "Content-Type": "text/html" });
+      res.end(html);
+    } else {
+      res.writeHead(404);
+      res.end("Not found");
+    }
+  });
+
+  const maxAttempts = 10;
+
+  const tryPort = (port: number): Promise<number> => {
+    return new Promise((resolve, reject) => {
+      const onError = (err: NodeJS.ErrnoException) => {
+        server.removeListener("listening", onListening);
+        if (err.code === "EADDRINUSE" && port < startPort + maxAttempts - 1) {
+          resolve(tryPort(port + 1));
+        } else {
+          reject(err);
+        }
+      };
+
+      const onListening = () => {
+        server.removeListener("error", onError);
+        resolve(port);
+      };
+
+      server.once("error", onError);
+      server.once("listening", onListening);
+      server.listen(port);
+    });
+  };
+
+  const port = await tryPort(startPort);
+  return { server, port };
+}
+
+/**
+ * Open a URL in the default browser.
+ */
+export function openInBrowser(url: string): void {
+  const openCmd = process.platform === "darwin" ? "open" : "xdg-open";
+  x(openCmd, [url]);
+}
+
+/**
+ * Wait for SIGINT and then close the server.
+ */
+export function waitForShutdown(server: http.Server): Promise<void> {
+  return new Promise<void>((resolve) => {
+    process.on("SIGINT", () => {
+      server.close();
+      resolve();
+    });
+  });
+}

package/src/lib/graph/sessions.ts

@@ -0,0 +1,104 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { extractProjectName } from "./analyzer.js";
+import { calculateCutoffMs, quickTokenCount } from "./parser.js";
+import type { BarChartData, BarChartDay, ProjectBar, SessionResult } from "./types.js";
+
+/**
+ * Find recent sessions from the projects directory.
+ */
+export function findRecentSessions(
+  projectsDir: string,
+  limit: number,
+  days: number,
+): SessionResult[] {
+  const sessions: SessionResult[] = [];
+
+  const cutoffMs = calculateCutoffMs(days);
+
+  const projectDirs = fs.readdirSync(projectsDir);
+  for (const project of projectDirs) {
+    const projectPath = path.join(projectsDir, project);
+    if (!fs.statSync(projectPath).isDirectory()) continue;
+
+    const files = fs.readdirSync(projectPath).filter((f) => f.endsWith(".jsonl"));
+    for (const file of files) {
+      const filePath = path.join(projectPath, file);
+      const stat = fs.statSync(filePath);
+
+      // Filter by days if cutoff is set
+      if (cutoffMs > 0 && stat.mtimeMs < cutoffMs) continue;
+
+      const sessionId = file.replace(".jsonl", "");
+
+      // Quick token count from file
+      const tokens = quickTokenCount(filePath);
+
+      sessions.push({
+        sessionId,
+        path: filePath,
+        date: stat.mtime.toLocaleDateString("en-CA"), // YYYY-MM-DD in local timezone
+        tokens,
+        project,
+        mtime: stat.mtimeMs,
+      });
+    }
+  }
+
+  // Sort by modification time, most recent first
+  sessions.sort((a, b) => b.mtime - a.mtime);
+  return sessions.slice(0, limit);
+}
+
+/**
+ * Find the file path for a specific session ID.
+ */
+export function findSessionPath(projectsDir: string, sessionId: string): string | undefined {
+  const projectDirs = fs.readdirSync(projectsDir);
+  for (const project of projectDirs) {
+    const projectPath = path.join(projectsDir, project);
+    if (!fs.statSync(projectPath).isDirectory()) continue;
+
+    const jsonlPath = path.join(projectPath, `${sessionId}.jsonl`);
+    if (fs.existsSync(jsonlPath)) {
+      return jsonlPath;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Build bar chart data structure from session results.
+ * Groups sessions by date and project folder, aggregating tokens per project per day.
+ */
+export function buildBarChartData(sessions: SessionResult[]): BarChartData {
+  if (sessions.length === 0) {
+    return { days: [] };
+  }
+
+  // Group sessions by date, then by project
+  const byDateProject = new Map<string, Map<string, number>>();
+
+  for (const session of sessions) {
+    const project = extractProjectName(session.project);
+
+    if (!byDateProject.has(session.date)) {
+      byDateProject.set(session.date, new Map());
+    }
+    const projectMap = byDateProject.get(session.date)!;
+    projectMap.set(project, (projectMap.get(project) || 0) + session.tokens);
+  }
+
+  // Build days array sorted chronologically (oldest first for x-axis)
+  const sortedDates = [...byDateProject.keys()].sort();
+  const days: BarChartDay[] = sortedDates.map((date) => {
+    const projectMap = byDateProject.get(date)!;
+    // Sort projects by total tokens descending
+    const projects: ProjectBar[] = [...projectMap.entries()]
+      .map(([project, totalTokens]) => ({ project, totalTokens }))
+      .sort((a, b) => b.totalTokens - a.totalTokens);
+    return { date, projects };
+  });
+
+  return { days };
+}

package/src/lib/graph/tools.ts

@@ -0,0 +1,90 @@
+import type { ContentBlock, ToolData } from "./types.js";
+
+/**
+ * Sanitize string by replacing control characters (newlines, tabs, etc.) with spaces.
+ */
+export function sanitizeString(str: string): string {
+  // Replace all control characters (ASCII 0-31) with space, collapse multiple spaces
+  // eslint-disable-next-line no-control-regex
+  return str.replace(/[\x00-\x1F]+/g, " ").trim();
+}
+
+/**
+ * Truncate a string and extract just the filename for paths.
+ */
+export function truncateDetail(str: string | undefined, maxLen = 30): string | undefined {
+  if (!str) return undefined;
+  // Sanitize control characters first
+  const sanitized = sanitizeString(str);
+  // For file paths, show just the filename
+  if (sanitized.includes("/")) {
+    const parts = sanitized.split("/");
+    const filename = parts[parts.length - 1];
+    return filename.length > maxLen ? filename.slice(0, maxLen - 3) + "..." : filename;
+  }
+  return sanitized.length > maxLen ? sanitized.slice(0, maxLen - 3) + "..." : sanitized;
+}
+
+/**
+ * Extract a meaningful detail string from tool input.
+ */
+export function extractToolDetail(
+  toolName: string,
+  input?: Record<string, unknown>,
+): string | undefined {
+  if (!input) return undefined;
+
+  switch (toolName) {
+    case "Read":
+    case "Write":
+    case "Edit":
+      return truncateDetail(input.file_path as string);
+    case "Bash":
+      return truncateDetail(input.command as string, 50);
+    case "Glob":
+    case "Grep":
+      return truncateDetail(input.pattern as string, 50);
+    case "Task":
+      return truncateDetail(input.description as string, 50);
+    case "WebFetch":
+      return truncateDetail(input.url as string, 40);
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Extract individual tool calls from message content blocks.
+ * Returns each tool call with its detail (file path, command, etc.).
+ */
+export function extractToolData(
+  content: ContentBlock[] | string | undefined,
+  turnInputTokens: number,
+  turnOutputTokens: number,
+): ToolData[] {
+  if (!content || typeof content === "string") return [];
+
+  // Collect individual tool_use blocks
+  const toolBlocks: Array<{ name: string; detail?: string }> = [];
+  for (const block of content) {
+    if (block.type === "tool_use" && block.name) {
+      const detail = extractToolDetail(block.name, block.input);
+      toolBlocks.push({ name: block.name, detail });
+    }
+  }
+
+  if (toolBlocks.length === 0) return [];
+
+  // Distribute tokens proportionally across individual calls
+  const tokensPerCall = {
+    input: Math.round(turnInputTokens / toolBlocks.length),
+    output: Math.round(turnOutputTokens / toolBlocks.length),
+  };
+
+  return toolBlocks.map((tool) => ({
+    name: tool.name,
+    detail: tool.detail,
+    inputTokens: tokensPerCall.input,
+    outputTokens: tokensPerCall.output,
+  }));
+}