@towles/tool 0.0.108 → 0.0.110

package/src/commands/doctor/history.test.ts

@@ -0,0 +1,161 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { loadHistory, saveHistory, diffRuns } from "./history.js";
+import type { DoctorRunResult } from "./checks.js";
+
+function makeResult(overrides: Partial<DoctorRunResult> = {}): DoctorRunResult {
+  return {
+    timestamp: new Date().toISOString(),
+    tools: [
+      { name: "git", version: "2.40.0", ok: true },
+      { name: "node", version: "20.11.0", ok: true },
+      { name: "bun", version: "1.1.0", ok: true },
+    ],
+    ghAuth: true,
+    plugins: [{ name: "code-simplifier", ok: true }],
+    agentboard: [{ name: "database", ok: true }],
+    ...overrides,
+  };
+}
+
+describe("loadHistory / saveHistory", () => {
+  let tmpDir: string;
+  let historyPath: string;
+
+  beforeEach(() => {
+    tmpDir = resolve(tmpdir(), `doctor-test-${Date.now()}`);
+    mkdirSync(tmpDir, { recursive: true });
+    historyPath = resolve(tmpDir, "doctor-history.json");
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("returns empty array when no file exists", () => {
+    expect(loadHistory(historyPath)).toEqual([]);
+  });
+
+  it("saves and loads a run", () => {
+    const result = makeResult();
+    saveHistory(result, historyPath);
+
+    const history = loadHistory(historyPath);
+    expect(history).toHaveLength(1);
+    expect(history[0].timestamp).toBe(result.timestamp);
+    expect(history[0].tools).toEqual(result.tools);
+  });
+
+  it("appends multiple runs", () => {
+    saveHistory(makeResult({ timestamp: "2024-01-01T00:00:00Z" }), historyPath);
+    saveHistory(makeResult({ timestamp: "2024-01-02T00:00:00Z" }), historyPath);
+
+    const history = loadHistory(historyPath);
+    expect(history).toHaveLength(2);
+    expect(history[0].timestamp).toBe("2024-01-01T00:00:00Z");
+    expect(history[1].timestamp).toBe("2024-01-02T00:00:00Z");
+  });
+
+  it("caps history at 50 entries", () => {
+    for (let i = 0; i < 55; i++) {
+      saveHistory(
+        makeResult({ timestamp: `2024-01-${String(i + 1).padStart(2, "0")}T00:00:00Z` }),
+        historyPath,
+      );
+    }
+
+    const history = loadHistory(historyPath);
+    expect(history).toHaveLength(50);
+    expect(history[0].timestamp).toBe("2024-01-06T00:00:00Z");
+  });
+
+  it("handles corrupted JSON gracefully", () => {
+    writeFileSync(historyPath, "not json", "utf-8");
+    expect(loadHistory(historyPath)).toEqual([]);
+  });
+});
+
+describe("diffRuns", () => {
+  it("detects version upgrades", () => {
+    const prev = makeResult({ tools: [{ name: "bun", version: "1.0.0", ok: true }] });
+    const curr = makeResult({ tools: [{ name: "bun", version: "1.1.0", ok: true }] });
+
+    const diffs = diffRuns(prev, curr);
+    const bunDiff = diffs.find((d) => d.name === "bun" && d.change === "upgraded");
+    expect(bunDiff).toBeDefined();
+    expect(bunDiff!.oldValue).toBe("1.0.0");
+    expect(bunDiff!.newValue).toBe("1.1.0");
+  });
+
+  it("detects version downgrades", () => {
+    const prev = makeResult({ tools: [{ name: "node", version: "22.0.0", ok: true }] });
+    const curr = makeResult({ tools: [{ name: "node", version: "20.11.0", ok: true }] });
+
+    const diffs = diffRuns(prev, curr);
+    const nodeDiff = diffs.find((d) => d.name === "node" && d.change === "downgraded");
+    expect(nodeDiff).toBeDefined();
+  });
+
+  it("detects new tools", () => {
+    const prev = makeResult({ tools: [] });
+    const curr = makeResult({ tools: [{ name: "git", version: "2.40.0", ok: true }] });
+
+    const diffs = diffRuns(prev, curr);
+    expect(diffs).toContainEqual(
+      expect.objectContaining({ name: "git", change: "added", newValue: "2.40.0" }),
+    );
+  });
+
+  it("detects removed tools", () => {
+    const prev = makeResult({ tools: [{ name: "ttyd", version: "1.7.0", ok: true }] });
+    const curr = makeResult({ tools: [] });
+
+    const diffs = diffRuns(prev, curr);
+    expect(diffs).toContainEqual(
+      expect.objectContaining({ name: "ttyd", change: "removed", oldValue: "1.7.0" }),
+    );
+  });
+
+  it("detects check status flips", () => {
+    const prev = makeResult({ tools: [{ name: "bun", version: "1.1.0", ok: true }] });
+    const curr = makeResult({ tools: [{ name: "bun", version: "1.1.0", ok: false }] });
+
+    const diffs = diffRuns(prev, curr);
+    expect(diffs).toContainEqual(expect.objectContaining({ name: "bun", change: "failed" }));
+  });
+
+  it("detects gh auth changes", () => {
+    const prev = makeResult({ ghAuth: true });
+    const curr = makeResult({ ghAuth: false });
+
+    const diffs = diffRuns(prev, curr);
+    expect(diffs).toContainEqual(expect.objectContaining({ name: "gh auth", change: "failed" }));
+  });
+
+  it("detects plugin status changes", () => {
+    const prev = makeResult({ plugins: [{ name: "code-simplifier", ok: false }] });
+    const curr = makeResult({ plugins: [{ name: "code-simplifier", ok: true }] });
+
+    const diffs = diffRuns(prev, curr);
+    expect(diffs).toContainEqual(
+      expect.objectContaining({ category: "plugin", name: "code-simplifier", change: "passed" }),
+    );
+  });
+
+  it("detects agentboard status changes", () => {
+    const prev = makeResult({ agentboard: [{ name: "database", ok: false }] });
+    const curr = makeResult({ agentboard: [{ name: "database", ok: true }] });
+
+    const diffs = diffRuns(prev, curr);
+    expect(diffs).toContainEqual(
+      expect.objectContaining({ category: "agentboard", name: "database", change: "passed" }),
+    );
+  });
+
+  it("returns empty array when nothing changed", () => {
+    const run = makeResult();
+    expect(diffRuns(run, run)).toEqual([]);
+  });
+});

package/src/commands/doctor/history.ts

@@ -0,0 +1,130 @@
+import { resolve } from "node:path";
+import consola from "consola";
+import { readFile, writeFile, fileExists } from "@towles/shared";
+import type { DoctorRunResult } from "./checks.js";
+
+const MAX_HISTORY = 50;
+
+export interface DiffEntry {
+  category: string;
+  name: string;
+  change: "added" | "removed" | "upgraded" | "downgraded" | "passed" | "failed" | "unchanged";
+  oldValue?: string | null;
+  newValue?: string | null;
+}
+
+function getHistoryPath(): string {
+  const configDir = process.env.XDG_CONFIG_HOME ?? resolve(process.env.HOME ?? "~", ".config");
+  return resolve(configDir, "tt", "doctor-history.json");
+}
+
+export function loadHistory(historyPath?: string): DoctorRunResult[] {
+  const path = historyPath ?? getHistoryPath();
+  if (!fileExists(path)) return [];
+  try {
+    return JSON.parse(readFile(path));
+  } catch (err) {
+    consola.debug(`Failed to parse doctor history at ${path}:`, err);
+    return [];
+  }
+}
+
+export function saveHistory(result: DoctorRunResult, historyPath?: string): void {
+  const path = historyPath ?? getHistoryPath();
+  const history = loadHistory(path);
+  history.push(result);
+  const trimmed = history.slice(-MAX_HISTORY);
+  writeFile(path, JSON.stringify(trimmed, null, 2));
+}
+
+export function diffRuns(previous: DoctorRunResult, current: DoctorRunResult): DiffEntry[] {
+  const entries: DiffEntry[] = [];
+
+  const prevToolMap = new Map(previous.tools.map((t) => [t.name, t]));
+  const currToolMap = new Map(current.tools.map((t) => [t.name, t]));
+
+  for (const [name, curr] of currToolMap) {
+    const prev = prevToolMap.get(name);
+    if (!prev) {
+      entries.push({ category: "tool", name, change: "added", newValue: curr.version });
+      continue;
+    }
+    if (prev.version !== curr.version && prev.version && curr.version) {
+      entries.push({
+        category: "tool",
+        name,
+        change: compareVersions(prev.version, curr.version) > 0 ? "downgraded" : "upgraded",
+        oldValue: prev.version,
+        newValue: curr.version,
+      });
+    }
+    if (prev.ok !== curr.ok) {
+      entries.push({
+        category: "tool",
+        name,
+        change: curr.ok ? "passed" : "failed",
+        oldValue: prev.ok ? "pass" : "fail",
+        newValue: curr.ok ? "pass" : "fail",
+      });
+    }
+  }
+
+  for (const [name, prev] of prevToolMap) {
+    if (!currToolMap.has(name)) {
+      entries.push({ category: "tool", name, change: "removed", oldValue: prev.version });
+    }
+  }
+
+  if (previous.ghAuth !== current.ghAuth) {
+    entries.push({
+      category: "auth",
+      name: "gh auth",
+      change: current.ghAuth ? "passed" : "failed",
+      oldValue: previous.ghAuth ? "pass" : "fail",
+      newValue: current.ghAuth ? "pass" : "fail",
+    });
+  }
+
+  const prevPluginMap = new Map(previous.plugins.map((p) => [p.name, p]));
+  for (const curr of current.plugins) {
+    const prev = prevPluginMap.get(curr.name);
+    if (!prev) {
+      entries.push({ category: "plugin", name: curr.name, change: "added" });
+    } else if (prev.ok !== curr.ok) {
+      entries.push({
+        category: "plugin",
+        name: curr.name,
+        change: curr.ok ? "passed" : "failed",
+      });
+    }
+  }
+
+  const prevAbMap = new Map(previous.agentboard.map((a) => [a.name, a]));
+  for (const curr of current.agentboard) {
+    const prev = prevAbMap.get(curr.name);
+    if (!prev) {
+      entries.push({ category: "agentboard", name: curr.name, change: "added" });
+    } else if (prev.ok !== curr.ok) {
+      entries.push({
+        category: "agentboard",
+        name: curr.name,
+        change: curr.ok ? "passed" : "failed",
+      });
+    }
+  }
+
+  return entries;
+}
+
+function compareVersions(a: string, b: string): number {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const na = pa[i] ?? 0;
+    const nb = pb[i] ?? 0;
+    if (na > nb) return 1;
+    if (na < nb) return -1;
+  }
+  return 0;
+}

package/src/commands/doctor.ts

@@ -1,159 +1,66 @@
-import { existsSync, readFileSync } from "node:fs";
-import { resolve, join } from "node:path";
 import { defineCommand } from "citty";
 import consola from "consola";
-import { x } from "tinyexec";
 import { colors } from "consola/utils";
 import { debugArg } from "./shared.js";
-
-interface CheckResult {
-  name: string;
-  version: string | null;
-  ok: boolean;
-  warning?: string;
-}
-
-async function checkCommand(
-  name: string,
-  args: string[],
-  versionPattern: RegExp,
-  optional = false,
-): Promise<CheckResult> {
-  try {
-    const result = await x(name, args);
-    const output = result.stdout + result.stderr;
-    const match = output.match(versionPattern);
-    return {
-      name,
-      version: match?.[1] ?? output.trim().slice(0, 20),
-      ok: true,
-    };
-  } catch {
-    consola.debug(`Tool check failed for "${name}"`);
-    return {
-      name,
-      version: null,
-      ok: optional,
-      warning: optional ? "optional, not installed" : undefined,
-    };
+import { runAllChecks, checkAgentBoard, checkClaudePlugins } from "./doctor/checks.js";
+import { formatDoctorJson } from "./doctor/format.js";
+import { loadHistory, saveHistory, diffRuns } from "./doctor/history.js";
+import type { DiffEntry } from "./doctor/history.js";
+
+function formatDiffEntry(entry: DiffEntry): string {
+  switch (entry.change) {
+    case "added":
+      return `${colors.green("+")} ${entry.category}/${entry.name}: added${entry.newValue ? ` (${entry.newValue})` : ""}`;
+    case "removed":
+      return `${colors.red("-")} ${entry.category}/${entry.name}: removed${entry.oldValue ? ` (was ${entry.oldValue})` : ""}`;
+    case "upgraded":
+      return `${colors.green("↑")} ${entry.category}/${entry.name}: ${entry.oldValue} → ${entry.newValue}`;
+    case "downgraded":
+      return `${colors.yellow("↓")} ${entry.category}/${entry.name}: ${entry.oldValue} → ${entry.newValue}`;
+    case "passed":
+      return `${colors.green("✓")} ${entry.category}/${entry.name}: now passing`;
+    case "failed":
+      return `${colors.red("✗")} ${entry.category}/${entry.name}: now failing`;
+    default:
+      return `  ${entry.category}/${entry.name}: unchanged`;
   }
 }
 
-async function checkGhAuth(): Promise<{ ok: boolean }> {
-  try {
-    const result = await x("gh", ["auth", "status"]);
-    return { ok: result.exitCode === 0 };
-  } catch {
-    consola.debug("GitHub CLI auth check failed");
-    return { ok: false };
-  }
-}
-
-function checkAgentBoard(): {
-  name: string;
-  value: string;
-  ok: boolean;
-  warning?: string;
-  hint?: string;
-}[] {
-  const results: { name: string; value: string; ok: boolean; warning?: string; hint?: string }[] =
-    [];
-
-  const defaultDataDir = resolve(
-    process.env.XDG_CONFIG_HOME ?? resolve(process.env.HOME ?? "~", ".config"),
-    "towles-tool",
-    "agentboard",
-  );
-  const dataDir = process.env.AGENTBOARD_DATA_DIR ?? defaultDataDir;
-  const dbPath = join(dataDir, "agentboard.db");
-  const configPath = join(dataDir, "config.json");
-
-  const dbExists = existsSync(dbPath);
-  results.push({
-    name: "database",
-    value: dbExists ? dbPath : "not found",
-    ok: dbExists,
-    hint: dbExists ? undefined : "Run: tt ag (starts server and creates DB automatically)",
-  });
-
-  let repoPaths: string[] = [];
-  if (existsSync(configPath)) {
-    try {
-      const config = JSON.parse(readFileSync(configPath, "utf-8"));
-      repoPaths = config.repoPaths ?? [];
-    } catch {
-      // Corrupted config
-    }
-  }
-
-  results.push({
-    name: "scan paths",
-    value: repoPaths.length > 0 ? repoPaths.join(", ") : "none configured",
-    ok: repoPaths.length > 0,
-    warning: repoPaths.length === 0 ? "no scan paths" : undefined,
-    hint:
-      repoPaths.length === 0
-        ? "Run: tt ag → open Workspaces → run the onboarding wizard"
-        : undefined,
-  });
-
-  results.push({
-    name: "data dir",
-    value: dataDir,
-    ok: true,
-  });
-
-  return results;
-}
-
-async function checkClaudePlugins(): Promise<
-  { name: string; ok: boolean; installHint?: string }[]
-> {
-  const requiredPlugins = [
-    {
-      id: "code-simplifier@claude-plugins-official",
-      name: "code-simplifier",
-      installCmd: "claude plugin install code-simplifier@claude-plugins-official --scope user",
+export default defineCommand({
+  meta: { name: "doctor", description: "Check system dependencies and environment" },
+  args: {
+    debug: debugArg,
+    track: {
+      type: "boolean",
+      description: "Save check results to history",
+      default: false,
     },
-  ];
-
-  try {
-    const result = await x("claude", ["plugin", "list", "--json"]);
-    const plugins: { id: string }[] = JSON.parse(result.stdout);
-    const installedIds = new Set(plugins.map((p) => p.id));
+    diff: {
+      type: "boolean",
+      description: "Compare current run against last tracked run",
+      default: false,
+    },
+    format: {
+      type: "string",
+      description: "Output format: text (default) or json",
+      default: "text",
+    },
+  },
+  async run({ args }) {
+    const isJson = args.format === "json";
 
-    return requiredPlugins.map((p) => ({
-      name: p.name,
-      ok: installedIds.has(p.id),
-      installHint: installedIds.has(p.id) ? undefined : `Run: ${p.installCmd}`,
-    }));
-  } catch {
-    consola.debug("Failed to list Claude plugins");
-    return requiredPlugins.map((p) => ({
-      name: p.name,
-      ok: false,
-      installHint: `Run: ${p.installCmd}`,
-    }));
-  }
-}
+    if (!isJson) {
+      consola.info("Checking dependencies...\n");
+    }
 
-export default defineCommand({
-  meta: { name: "doctor", description: "Check system dependencies and environment" },
-  args: { debug: debugArg },
-  async run() {
-    consola.info("Checking dependencies...\n");
+    const result = await runAllChecks();
 
-    const checks: CheckResult[] = await Promise.all([
-      checkCommand("git", ["--version"], /git version ([\d.]+)/),
-      checkCommand("gh", ["--version"], /gh version ([\d.]+)/),
-      checkCommand("node", ["--version"], /v?([\d.]+)/),
-      checkCommand("bun", ["--version"], /([\d.]+)/),
-      checkCommand("claude", ["--version"], /([\d.]+)/),
-      checkCommand("tmux", ["-V"], /tmux ([\d.]+)/),
-      checkCommand("ttyd", ["--version"], /ttyd version ([\d.]+)/, true),
-    ]);
+    if (isJson) {
+      console.log(formatDoctorJson(result));
+      return;
+    }
 
-    for (const check of checks) {
+    for (const check of result.tools) {
       const icon = check.ok
         ? colors.green("✓")
         : check.warning
@@ -167,14 +74,13 @@ export default defineCommand({
     }
 
     consola.log("");
-    const ghAuth = await checkGhAuth();
-    const authIcon = ghAuth.ok ? colors.green("✓") : colors.yellow("⚠");
-    consola.log(`${authIcon} gh auth: ${ghAuth.ok ? "authenticated" : "not authenticated"}`);
-    if (!ghAuth.ok) {
+    const authIcon = result.ghAuth ? colors.green("✓") : colors.yellow("⚠");
+    consola.log(`${authIcon} gh auth: ${result.ghAuth ? "authenticated" : "not authenticated"}`);
+    if (!result.ghAuth) {
       consola.log(`  ${colors.dim("Run: gh auth login")}`);
     }
 
-    const nodeCheck = checks.find((c) => c.name === "node");
+    const nodeCheck = result.tools.find((c) => c.name === "node");
     if (nodeCheck?.version) {
       const major = Number.parseInt(nodeCheck.version.split(".")[0], 10);
       if (major < 18) {
@@ -210,8 +116,8 @@ export default defineCommand({
     }
 
     const allOk =
-      checks.every((c) => c.ok || !!c.warning) &&
-      ghAuth.ok &&
+      result.tools.every((c) => c.ok || !!c.warning) &&
+      result.ghAuth &&
       pluginChecks.every((c) => c.ok) &&
       agentboardChecks.every((c) => c.ok || !!c.warning);
     consola.log("");
@@ -220,5 +126,28 @@ export default defineCommand({
     } else {
       consola.log(colors.yellow("Some checks failed. See above for details."));
     }
+
+    if (args.track) {
+      saveHistory(result);
+      consola.log(colors.dim("\nResults saved to history."));
+    }
+
+    if (args.diff) {
+      const history = loadHistory();
+      if (history.length === 0) {
+        consola.log(colors.yellow("\nNo previous runs tracked. Use --track to save a run first."));
+      } else {
+        const previous = history[history.length - 1];
+        const diffs = diffRuns(previous, result);
+        consola.log(colors.bold(`\nChanges since last tracked run (${previous.timestamp}):`));
+        if (diffs.length === 0) {
+          consola.log(colors.dim("  No changes detected."));
+        } else {
+          for (const entry of diffs) {
+            consola.log(`  ${formatDiffEntry(entry)}`);
+          }
+        }
+      }
+    }
   },
 });

package/src/commands/gh/branch-clean.ts

@@ -1,7 +1,7 @@
 import { defineCommand } from "citty";
 import { colors } from "consola/utils";
 import consola from "consola";
-import { x } from "tinyexec";
+import { run } from "@towles/shared";
 
 import { debugArg } from "../shared.js";
 
@@ -34,11 +34,11 @@ export default defineCommand({
     const baseBranch = args.base;
 
     // Get current branch
-    const currentResult = await x("git", ["branch", "--show-current"]);
+    const currentResult = await run("git", ["branch", "--show-current"]);
     const currentBranch = currentResult.stdout.trim();
 
     // Get merged branches
-    const mergedResult = await x("git", ["branch", "--merged", baseBranch]);
+    const mergedResult = await run("git", ["branch", "--merged", baseBranch]);
     const allMerged = mergedResult.stdout
       .split("\n")
       .map((b) => b.trim().replace(/^\* /, ""))
@@ -81,7 +81,7 @@ export default defineCommand({
 
     for (const branch of toDelete) {
       try {
-        await x("git", ["branch", "-d", branch]);
+        await run("git", ["branch", "-d", branch]);
         consola.log(colors.green(`✓ Deleted ${branch}`));
         deleted++;
       } catch {

package/src/commands/gh/branch.test.ts

@@ -1,6 +1,5 @@
 import { describe, expect, it } from "vitest";
-import stripAnsi from "strip-ansi";
-import type { Issue } from "../../utils/git/gh-cli-wrapper";
+import type { Issue } from "@towles/shared";
 import { buildIssueChoices, computeColumnLayout } from "./branch";
 
 const issues: Issue[] = [
@@ -92,13 +91,13 @@ describe("buildIssueChoices", () => {
 
   it("includes issue title text in description", () => {
     const choices = buildIssueChoices(issues, layout);
-    const desc = stripAnsi(choices[0].description!);
+    const desc = Bun.stripANSI(choices[0].description!);
     expect(desc).toContain("Short bug");
   });
 
   it("includes label names in description", () => {
     const choices = buildIssueChoices(issues, layout);
-    const desc = stripAnsi(choices[1].description!);
+    const desc = Bun.stripANSI(choices[1].description!);
     expect(desc).toContain("enhancement");
     expect(desc).toContain("priority");
   });
@@ -106,7 +105,7 @@ describe("buildIssueChoices", () => {
   it("handles issues with no labels", () => {
     const choices = buildIssueChoices(issues, layout);
     // Issue #7 has no labels — description should still contain the title
-    const desc = stripAnsi(choices[2].description!);
+    const desc = Bun.stripANSI(choices[2].description!);
     expect(desc).toContain("Docs update");
   });
 

package/src/commands/gh/branch.ts

@@ -6,11 +6,16 @@ import { colors } from "consola/utils";
 import { Fzf } from "fzf";
 
 import { debugArg } from "../shared.js";
-import type { Issue } from "../../utils/git/gh-cli-wrapper.js";
-import { getIssues, isGithubCliInstalled } from "../../utils/git/gh-cli-wrapper.js";
-import { git } from "../../utils/git/exec.js";
-import { createBranchNameFromIssue } from "../../utils/git/branch-name.js";
-import { getTerminalColumns, limitText, printWithHexColor } from "../../utils/render.js";
+import type { Issue } from "@towles/shared";
+import {
+  createBranchNameFromIssue,
+  getIssues,
+  getTerminalColumns,
+  git,
+  isGithubCliInstalled,
+  limitText,
+  printWithHexColor,
+} from "@towles/shared";
 
 export interface ColumnLayout {
   longestNumber: number;