@hasna/terminal 0.1.5 → 0.2.0

package/src/compression.ts

@@ -0,0 +1,140 @@
+// Token compression engine — reduces CLI output to fit within token budgets
+
+import { parseOutput, estimateTokens, tokenSavings } from "./parsers/index.js";
+
+export interface CompressOptions {
+  /** Max tokens for the output (default: unlimited) */
+  maxTokens?: number;
+  /** Output format */
+  format?: "text" | "json" | "summary";
+  /** Strip ANSI escape codes (default: true) */
+  stripAnsi?: boolean;
+}
+
+export interface CompressedOutput {
+  content: string;
+  format: "text" | "json" | "summary";
+  originalTokens: number;
+  compressedTokens: number;
+  tokensSaved: number;
+  savingsPercent: number;
+}
+
+/** Strip ANSI escape codes from text */
+export function stripAnsi(text: string): string {
+  // eslint-disable-next-line no-control-regex
+  return text.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, "").replace(/\x1b\][^\x07]*\x07/g, "");
+}
+
+/** Deduplicate consecutive similar lines (e.g., "Compiling X... Compiling Y...") */
+function deduplicateLines(lines: string[]): string[] {
+  if (lines.length <= 3) return lines;
+
+  const result: string[] = [];
+  let repeatCount = 0;
+  let repeatPattern = "";
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    // Extract a "pattern" — the line without numbers, paths, specific identifiers
+    const pattern = line.replace(/[0-9]+/g, "N").replace(/\/\S+/g, "/PATH").replace(/\s+/g, " ").trim();
+
+    if (pattern === repeatPattern) {
+      repeatCount++;
+    } else {
+      if (repeatCount > 2) {
+        result.push(`  ... (${repeatCount} similar lines)`);
+      } else if (repeatCount > 0) {
+        // Push the skipped lines back
+        for (let j = i - repeatCount; j < i; j++) {
+          result.push(lines[j]);
+        }
+      }
+      result.push(line);
+      repeatPattern = pattern;
+      repeatCount = 0;
+    }
+  }
+
+  if (repeatCount > 2) {
+    result.push(`  ... (${repeatCount} similar lines)`);
+  } else {
+    for (let j = lines.length - repeatCount; j < lines.length; j++) {
+      result.push(lines[j]);
+    }
+  }
+
+  return result;
+}
+
+/** Smart truncation: keep first N + last M lines */
+function smartTruncate(text: string, maxTokens: number): string {
+  const lines = text.split("\n");
+  const currentTokens = estimateTokens(text);
+
+  if (currentTokens <= maxTokens) return text;
+
+  // Keep proportional first/last, with first getting more
+  const targetLines = Math.floor((maxTokens * lines.length) / currentTokens);
+  const firstCount = Math.ceil(targetLines * 0.6);
+  const lastCount = Math.floor(targetLines * 0.4);
+
+  if (firstCount + lastCount >= lines.length) return text;
+
+  const first = lines.slice(0, firstCount);
+  const last = lines.slice(-lastCount);
+  const hiddenCount = lines.length - firstCount - lastCount;
+
+  return [...first, `\n--- ${hiddenCount} lines hidden ---\n`, ...last].join("\n");
+}
+
+/** Compress command output to fit within a token budget */
+export function compress(command: string, output: string, options: CompressOptions = {}): CompressedOutput {
+  const { maxTokens, format = "text", stripAnsi: doStrip = true } = options;
+  const originalTokens = estimateTokens(output);
+
+  // Step 1: Strip ANSI codes
+  let text = doStrip ? stripAnsi(output) : output;
+
+  // Step 2: Try structured parsing (format=json or when it saves tokens)
+  if (format === "json" || format === "summary") {
+    const parsed = parseOutput(command, text);
+    if (parsed) {
+      const json = JSON.stringify(parsed.data, null, format === "summary" ? 0 : 2);
+      const savings = tokenSavings(output, parsed.data);
+      const compressedTokens = estimateTokens(json);
+
+      // If within budget or no budget, return structured
+      if (!maxTokens || compressedTokens <= maxTokens) {
+        return {
+          content: json,
+          format: "json",
+          originalTokens,
+          compressedTokens,
+          tokensSaved: savings.saved,
+          savingsPercent: savings.percent,
+        };
+      }
+    }
+  }
+
+  // Step 3: Deduplicate similar lines
+  const lines = text.split("\n");
+  const deduped = deduplicateLines(lines);
+  text = deduped.join("\n");
+
+  // Step 4: Smart truncation if over budget
+  if (maxTokens) {
+    text = smartTruncate(text, maxTokens);
+  }
+
+  const compressedTokens = estimateTokens(text);
+  return {
+    content: text,
+    format: "text",
+    originalTokens,
+    compressedTokens,
+    tokensSaved: Math.max(0, originalTokens - compressedTokens),
+    savingsPercent: originalTokens > 0 ? Math.round(((originalTokens - compressedTokens) / originalTokens) * 100) : 0,
+  };
+}

package/src/diff-cache.test.ts

@@ -0,0 +1,30 @@
+import { describe, it, expect } from "bun:test";
+import { diffOutput, clearDiffCache } from "./diff-cache.js";
+
+describe("diffOutput", () => {
+  it("returns first run with no previous", () => {
+    clearDiffCache();
+    const result = diffOutput("npm test", "/tmp", "PASS\n5 passed");
+    expect(result.hasPrevious).toBe(false);
+    expect(result.diffSummary).toBe("first run");
+    expect(result.tokensSaved).toBe(0);
+  });
+
+  it("detects identical output", () => {
+    clearDiffCache();
+    diffOutput("npm test", "/tmp/id", "PASS\n5 passed");
+    const result = diffOutput("npm test", "/tmp/id", "PASS\n5 passed");
+    expect(result.unchanged).toBe(true);
+    expect(result.diffSummary).toBe("identical to previous run");
+  });
+
+  it("computes diff for changed output", () => {
+    clearDiffCache();
+    diffOutput("npm test", "/tmp/diff", "PASS test1\nPASS test2\nFAIL test3");
+    const result = diffOutput("npm test", "/tmp/diff", "PASS test1\nPASS test2\nPASS test3");
+    expect(result.hasPrevious).toBe(true);
+    expect(result.unchanged).toBe(false);
+    expect(result.added).toContain("PASS test3");
+    expect(result.removed).toContain("FAIL test3");
+  });
+});

package/src/diff-cache.ts

@@ -0,0 +1,125 @@
+// Diff-aware output caching — when same command runs again, return only what changed
+
+import { estimateTokens } from "./parsers/index.js";
+
+interface CachedOutput {
+  command: string;
+  cwd: string;
+  output: string;
+  timestamp: number;
+}
+
+const cache = new Map<string, CachedOutput>();
+
+function cacheKey(command: string, cwd: string): string {
+  return `${cwd}:${command}`;
+}
+
+/** Compute a simple line diff between two outputs */
+function lineDiff(prev: string, curr: string): { added: string[]; removed: string[]; unchanged: number } {
+  const prevLines = new Set(prev.split("\n"));
+  const currLines = curr.split("\n");
+
+  const added: string[] = [];
+  const removed: string[] = [];
+  let unchanged = 0;
+
+  for (const line of currLines) {
+    if (prevLines.has(line)) {
+      unchanged++;
+      prevLines.delete(line);
+    } else {
+      added.push(line);
+    }
+  }
+
+  for (const line of prevLines) {
+    removed.push(line);
+  }
+
+  return { added, removed, unchanged };
+}
+
+/** Generate a human-readable diff summary */
+function summarizeDiff(diff: { added: string[]; removed: string[]; unchanged: number }): string {
+  const parts: string[] = [];
+  if (diff.added.length > 0) parts.push(`+${diff.added.length} new lines`);
+  if (diff.removed.length > 0) parts.push(`-${diff.removed.length} removed lines`);
+  parts.push(`${diff.unchanged} unchanged`);
+  return parts.join(", ");
+}
+
+export interface DiffResult {
+  /** Full current output */
+  full: string;
+  /** Was there a previous run to diff against? */
+  hasPrevious: boolean;
+  /** Lines added since last run */
+  added: string[];
+  /** Lines removed since last run */
+  removed: string[];
+  /** Summary of changes */
+  diffSummary: string;
+  /** Whether output is identical to last run */
+  unchanged: boolean;
+  /** Tokens saved by returning diff instead of full output */
+  tokensSaved: number;
+}
+
+/** Run diffing on command output. Caches the output for next comparison. */
+export function diffOutput(command: string, cwd: string, output: string): DiffResult {
+  const key = cacheKey(command, cwd);
+  const prev = cache.get(key);
+
+  // Store current for next time
+  cache.set(key, { command, cwd, output, timestamp: Date.now() });
+
+  if (!prev) {
+    return {
+      full: output,
+      hasPrevious: false,
+      added: [],
+      removed: [],
+      diffSummary: "first run",
+      unchanged: false,
+      tokensSaved: 0,
+    };
+  }
+
+  if (prev.output === output) {
+    const fullTokens = estimateTokens(output);
+    return {
+      full: output,
+      hasPrevious: true,
+      added: [],
+      removed: [],
+      diffSummary: "identical to previous run",
+      unchanged: true,
+      tokensSaved: fullTokens - 10, // ~10 tokens for the "unchanged" message
+    };
+  }
+
+  const diff = lineDiff(prev.output, output);
+  const diffContent = [
+    ...diff.added.map(l => `+ ${l}`),
+    ...diff.removed.map(l => `- ${l}`),
+  ].join("\n");
+
+  const fullTokens = estimateTokens(output);
+  const diffTokens = estimateTokens(diffContent);
+
+  return {
+    full: output,
+    hasPrevious: true,
+    added: diff.added,
+    removed: diff.removed,
+    diffSummary: summarizeDiff(diff),
+    unchanged: false,
+    tokensSaved: Math.max(0, fullTokens - diffTokens),
+  };
+}
+
+/** Clear the diff cache */
+export function clearDiffCache(): void {
+  cache.clear();
+}

package/src/economy.test.ts

@@ -0,0 +1,16 @@
+import { describe, it, expect } from "bun:test";
+import { formatTokens } from "./economy.js";
+
+describe("formatTokens", () => {
+  it("formats small numbers", () => {
+    expect(formatTokens(42)).toBe("42");
+  });
+
+  it("formats thousands", () => {
+    expect(formatTokens(1500)).toBe("1.5K");
+  });
+
+  it("formats millions", () => {
+    expect(formatTokens(2500000)).toBe("2.5M");
+  });
+});

package/src/economy.ts

@@ -0,0 +1,99 @@
+// Token economy tracker — tracks token savings across all interactions
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+const DIR = join(homedir(), ".terminal");
+const ECONOMY_FILE = join(DIR, "economy.json");
+
+export interface EconomyStats {
+  totalTokensSaved: number;
+  totalTokensUsed: number;
+  savingsByFeature: {
+    structured: number;
+    compressed: number;
+    diff: number;
+    cache: number;
+    search: number;
+  };
+  sessionStart: number;
+  sessionSaved: number;
+  sessionUsed: number;
+}
+
+let stats: EconomyStats | null = null;
+
+function ensureDir() {
+  if (!existsSync(DIR)) mkdirSync(DIR, { recursive: true });
+}
+
+function loadStats(): EconomyStats {
+  if (stats) return stats;
+  ensureDir();
+  if (existsSync(ECONOMY_FILE)) {
+    try {
+      const saved = JSON.parse(readFileSync(ECONOMY_FILE, "utf8"));
+      stats = {
+        totalTokensSaved: saved.totalTokensSaved ?? 0,
+        totalTokensUsed: saved.totalTokensUsed ?? 0,
+        savingsByFeature: {
+          structured: saved.savingsByFeature?.structured ?? 0,
+          compressed: saved.savingsByFeature?.compressed ?? 0,
+          diff: saved.savingsByFeature?.diff ?? 0,
+          cache: saved.savingsByFeature?.cache ?? 0,
+          search: saved.savingsByFeature?.search ?? 0,
+        },
+        sessionStart: Date.now(),
+        sessionSaved: 0,
+        sessionUsed: 0,
+      };
+      return stats;
+    } catch {}
+  }
+  stats = {
+    totalTokensSaved: 0,
+    totalTokensUsed: 0,
+    savingsByFeature: { structured: 0, compressed: 0, diff: 0, cache: 0, search: 0 },
+    sessionStart: Date.now(),
+    sessionSaved: 0,
+    sessionUsed: 0,
+  };
+  return stats;
+}
+
+function saveStats() {
+  ensureDir();
+  if (stats) {
+    writeFileSync(ECONOMY_FILE, JSON.stringify(stats, null, 2));
+  }
+}
+
+/** Record token savings from a feature */
+export function recordSaving(feature: keyof EconomyStats["savingsByFeature"], tokensSaved: number) {
+  const s = loadStats();
+  s.totalTokensSaved += tokensSaved;
+  s.sessionSaved += tokensSaved;
+  s.savingsByFeature[feature] += tokensSaved;
+  saveStats();
+}
+
+/** Record tokens used (for AI calls) */
+export function recordUsage(tokens: number) {
+  const s = loadStats();
+  s.totalTokensUsed += tokens;
+  s.sessionUsed += tokens;
+  saveStats();
+}
+
+/** Get current economy stats */
+export function getEconomyStats(): EconomyStats {
+  return { ...loadStats() };
+}
+
+/** Format token count for display */
+export function formatTokens(n: number): string {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}K`;
+  return `${n}`;
+}

package/src/mcp/install.ts

@@ -0,0 +1,94 @@
+// MCP installation helper — register open-terminal as MCP server for various agents
+
+import { execSync } from "child_process";
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+const TERMINAL_BIN = "terminal"; // the CLI binary name
+
+function which(cmd: string): string | null {
+  try {
+    return execSync(`which ${cmd}`, { encoding: "utf8" }).trim();
+  } catch {
+    return null;
+  }
+}
+
+export function installClaude(): boolean {
+  try {
+    execSync(
+      `claude mcp add --transport stdio --scope user open-terminal -- ${which(TERMINAL_BIN) ?? "npx"} ${which(TERMINAL_BIN) ? "mcp serve" : "@hasna/terminal mcp serve"}`,
+      { stdio: "inherit" }
+    );
+    console.log("✓ Installed open-terminal MCP server for Claude Code");
+    return true;
+  } catch (e) {
+    console.error("Failed to install for Claude Code:", e);
+    return false;
+  }
+}
+
+export function installCodex(): boolean {
+  const configPath = join(homedir(), ".codex", "config.toml");
+  try {
+    let content = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
+    if (content.includes("[mcp_servers.open-terminal]")) {
+      console.log("✓ open-terminal already configured for Codex");
+      return true;
+    }
+    const bin = which(TERMINAL_BIN) ?? "npx @hasna/terminal";
+    content += `\n[mcp_servers.open-terminal]\ncommand = "${bin}"\nargs = ["mcp", "serve"]\n`;
+    writeFileSync(configPath, content);
+    console.log("✓ Installed open-terminal MCP server for Codex");
+    return true;
+  } catch (e) {
+    console.error("Failed to install for Codex:", e);
+    return false;
+  }
+}
+
+export function installGemini(): boolean {
+  const configPath = join(homedir(), ".gemini", "settings.json");
+  try {
+    let config: any = {};
+    if (existsSync(configPath)) {
+      config = JSON.parse(readFileSync(configPath, "utf8"));
+    }
+    if (!config.mcpServers) config.mcpServers = {};
+    const bin = which(TERMINAL_BIN) ?? "npx";
+    const args = which(TERMINAL_BIN) ? ["mcp", "serve"] : ["@hasna/terminal", "mcp", "serve"];
+    config.mcpServers["open-terminal"] = { command: bin, args };
+    writeFileSync(configPath, JSON.stringify(config, null, 2));
+    console.log("✓ Installed open-terminal MCP server for Gemini");
+    return true;
+  } catch (e) {
+    console.error("Failed to install for Gemini:", e);
+    return false;
+  }
+}
+
+export function installAll(): void {
+  installClaude();
+  installCodex();
+  installGemini();
+}
+
+export function handleMcpInstall(args: string[]): void {
+  const flags = new Set(args);
+
+  if (flags.has("--all")) { installAll(); return; }
+  if (flags.has("--claude")) { installClaude(); return; }
+  if (flags.has("--codex")) { installCodex(); return; }
+  if (flags.has("--gemini")) { installGemini(); return; }
+
+  console.log("Usage: t mcp install [--claude|--codex|--gemini|--all]");
+  console.log("");
+  console.log("Install open-terminal as an MCP server for AI coding agents.");
+  console.log("");
+  console.log("Options:");
+  console.log("  --claude    Install for Claude Code");
+  console.log("  --codex     Install for OpenAI Codex");
+  console.log("  --gemini    Install for Gemini CLI");
+  console.log("  --all       Install for all agents");
+}