@yoavsh/treekeeper 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "@yoavsh/treekeeper",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Reclaim disk from finished agent worktrees. Watches git, forge PR state and agent sessions, archives anything unique, then removes what is done.",
+  "keywords": [
+    "git",
+    "worktree",
+    "cleanup",
+    "gc",
+    "disk-space",
+    "agent",
+    "ai-agent",
+    "claude-code",
+    "codex",
+    "aider",
+    "cursor",
+    "branches",
+    "daemon"
+  ],
+  "homepage": "https://github.com/yoavshmariahu/treekeeper#readme",
+  "bugs": {
+    "url": "https://github.com/yoavshmariahu/treekeeper/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yoavshmariahu/treekeeper.git"
+  },
+  "license": "MIT",
+  "author": "Yoav Shmariahu",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "treekeeper": "dist/cli.js",
+    "tk": "dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src",
+    "docs",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "watch": "tsc -w -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "start": "node dist/cli.js",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { parseArgs } from "node:util";
+import { archiveCommand } from "./commands/archive.js";
+import { configCommand } from "./commands/config.js";
+import { daemonCommand } from "./commands/daemon.js";
+import { doctorCommand } from "./commands/doctor.js";
+import { gcCommand } from "./commands/gc.js";
+import { statusCommand } from "./commands/status.js";
+import { watchCommand } from "./commands/watch.js";
+import type { CliFlags } from "./commands/context.js";
+import { color } from "./util/color.js";
+
+const HELP = `${color.bold("treekeeper")} — reclaim disk from finished agent worktrees
+
+${color.bold("USAGE")}
+  treekeeper <command> [options] [path...]
+
+${color.bold("COMMANDS")}
+  gc [path...]        Plan a sweep (default). Add --apply to carry it out.
+  status              What is reclaimable right now, plus daemon state.
+  watch               Sweep on an interval in the foreground.
+  daemon <sub>        install | uninstall | start | stop | status | logs
+  archive <sub>       list | prune | path
+  config <sub>        show | path | init
+  doctor              Check git, gh, lsof, config and detectors.
+
+${color.bold("OPTIONS")}
+  --apply             Actually remove things (default is a dry run)
+  -y, --yes           Skip the confirmation prompt
+  --all               Every repo under the configured roots
+  --json              Machine-readable output on stdout
+  -q, --quiet         Summary only
+  -v, --verbose       Show kept worktrees and debug logging
+  --force             Bypass the age gate and the dirty / closed-PR holds
+  --min-age <dur>     Override minAge, e.g. 2h
+  --session-grace <d> Override how long after agent activity a worktree is held
+  --forge <kind>      github | none  (none = git ancestry only)
+  --refresh           Ignore the cached pull-request data
+  --branches-only     Prune branches, leave every worktree alone
+  --worktrees-only    Remove worktrees, do not prune other branches
+  --sizes             Measure every worktree, not just the removable ones
+  --root <dir>        Override roots (repeatable)
+  --interval <dur>    Interval for watch / daemon install
+  --config <file>     Use a specific config file
+  -h, --help          This text
+  --version           Version
+
+${color.bold("EXAMPLES")}
+  treekeeper gc --all                   # what could go, across every repo
+  treekeeper gc --all --apply --yes     # the sweep a harness hook should run
+  treekeeper gc --json | jq .summary    # read the plan from a script
+  treekeeper daemon install             # sweep on a schedule, forever
+
+${color.gray("A worktree is only ever removed when its work is merged, or its pull request")}
+${color.gray("was merged or closed — and anything unique is archived before it goes.")}
+`;
+
+export async function main(argv: string[]): Promise<number> {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      allowPositionals: true,
+      strict: true,
+      options: {
+        apply: { type: "boolean" },
+        yes: { type: "boolean", short: "y" },
+        all: { type: "boolean" },
+        json: { type: "boolean" },
+        quiet: { type: "boolean", short: "q" },
+        verbose: { type: "boolean", short: "v" },
+        force: { type: "boolean" },
+        refresh: { type: "boolean" },
+        sizes: { type: "boolean" },
+        "branches-only": { type: "boolean" },
+        "worktrees-only": { type: "boolean" },
+        "min-age": { type: "string" },
+        "session-grace": { type: "string" },
+        forge: { type: "string" },
+        root: { type: "string", multiple: true },
+        interval: { type: "string" },
+        config: { type: "string" },
+        help: { type: "boolean", short: "h" },
+        version: { type: "boolean" },
+      },
+    });
+  } catch (err) {
+    process.stderr.write(`${(err as Error).message}\nTry \`treekeeper --help\`.\n`);
+    return 2;
+  }
+
+  const { values, positionals } = parsed;
+
+  if (values.version) {
+    process.stdout.write((await version()) + "\n");
+    return 0;
+  }
+
+  const [command = "gc", ...rest] = positionals;
+
+  if (values.help) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+
+  const flags: CliFlags = {
+    apply: values.apply,
+    yes: values.yes,
+    json: values.json,
+    quiet: values.quiet,
+    verbose: values.verbose,
+    all: values.all,
+    force: values.force,
+    refresh: values.refresh,
+    sizes: values.sizes,
+    branchesOnly: values["branches-only"],
+    worktreesOnly: values["worktrees-only"],
+    minAge: values["min-age"],
+    sessionGrace: values["session-grace"],
+    forge: values.forge,
+    interval: values.interval,
+    config: values.config,
+    roots: values.root,
+  };
+
+  switch (command) {
+    case "gc":
+    case "clean":
+      return gcCommand(rest, flags);
+    case "status":
+      return statusCommand(flags);
+    case "watch":
+      return watchCommand(flags);
+    case "daemon":
+      return daemonCommand(rest, flags);
+    case "archive":
+      return archiveCommand(rest, flags);
+    case "config":
+      return configCommand(rest);
+    case "doctor":
+      return doctorCommand(values.json === true);
+    case "help":
+      process.stdout.write(HELP);
+      return 0;
+    default:
+      process.stderr.write(`unknown command "${command}". Try \`treekeeper --help\`.\n`);
+      return 2;
+  }
+}
+
+async function version(): Promise<string> {
+  try {
+    const text = await readFile(new URL("../package.json", import.meta.url), "utf8");
+    const pkg: unknown = JSON.parse(text);
+    return String((pkg as { version?: unknown }).version ?? "0.0.0");
+  } catch {
+    return "0.0.0";
+  }
+}
+
+const isDirectRun =
+  process.argv[1] !== undefined &&
+  (import.meta.url.endsWith("/cli.js") || import.meta.url.endsWith("/cli.ts"));
+
+if (isDirectRun) {
+  main(process.argv.slice(2))
+    .then((code) => {
+      process.exitCode = code;
+    })
+    .catch((err: unknown) => {
+      process.stderr.write(`treekeeper: ${(err as Error).stack ?? String(err)}\n`);
+      process.exitCode = 1;
+    });
+}

package/src/commands/archive.ts

@@ -0,0 +1,72 @@
+import { listArchives, pruneArchives } from "../core/archive.js";
+import { loadConfig } from "../core/config.js";
+import { dirSizeKb } from "../core/size.js";
+import { formatBytes, formatKb } from "../util/bytes.js";
+import { color } from "../util/color.js";
+import { shortenPath } from "../util/paths.js";
+import { formatAgo, parseDuration } from "../util/time.js";
+import type { CliFlags } from "./context.js";
+
+const USAGE = `usage: treekeeper archive <list|prune|path>`;
+
+export async function archiveCommand(args: string[], flags: CliFlags): Promise<number> {
+  const { config } = await loadConfig();
+  const sub = args[0] ?? "list";
+
+  if (sub === "path") {
+    process.stdout.write(config.archive.dir + "\n");
+    return 0;
+  }
+
+  if (sub === "prune") {
+    const retention = parseDuration(config.archive.retention);
+    const result = await pruneArchives(config.archive.dir, retention);
+    process.stdout.write(
+      result.removed.length === 0
+        ? `nothing older than ${config.archive.retention}\n`
+        : `pruned ${result.removed.length} archive(s), freed ${formatKb(result.freedKb)}\n`,
+    );
+    return 0;
+  }
+
+  if (sub !== "list") {
+    process.stderr.write(USAGE + "\n");
+    return 2;
+  }
+
+  const records = await listArchives(config.archive.dir);
+  if (flags.json) {
+    process.stdout.write(JSON.stringify(records, null, 2) + "\n");
+    return 0;
+  }
+
+  if (records.length === 0) {
+    process.stdout.write(`no archives in ${shortenPath(config.archive.dir)}\n`);
+    return 0;
+  }
+
+  const total = (await dirSizeKb(config.archive.dir)) ?? 0;
+  process.stdout.write(
+    `${color.bold(String(records.length))} archive(s) in ${shortenPath(config.archive.dir)} ` +
+    color.gray(`(${formatKb(total)}, retention ${config.archive.retention})\n\n`),
+  );
+
+  for (const r of records) {
+    const bits = [
+      r.bundle ? `${r.bundle.commits} unmerged commit${r.bundle.commits === 1 ? "" : "s"}` : null,
+      r.patch ? `diff ${formatBytes(r.patch.bytes)}` : null,
+      r.untracked
+        ? `${r.untracked.count} untracked${r.untracked.truncated ? " (list only)" : ""}`
+        : null,
+    ].filter(Boolean);
+    process.stdout.write(
+      `${color.cyan(r.id)}  ${color.gray(formatAgo(Date.parse(r.createdAt)))}\n` +
+      `  ${color.gray(r.reason)}${bits.length > 0 ? `  ${color.yellow(bits.join(", "))}` : color.gray("  (nothing unique)")}\n` +
+      `  ${color.gray(shortenPath(r.dir))}\n`,
+    );
+  }
+  process.stdout.write(
+    color.gray("\neach archive has a RESTORE.md with the exact commands to bring it back\n"),
+  );
+  return 0;
+}

package/src/commands/config.ts

@@ -0,0 +1,57 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { defaultConfig, globalConfigPath, loadConfig } from "../core/config.js";
+import { color } from "../util/color.js";
+import { shortenPath } from "../util/paths.js";
+
+const USAGE = `usage: treekeeper config <show|path|init>`;
+
+export async function configCommand(args: string[]): Promise<number> {
+  const sub = args[0] ?? "show";
+
+  if (sub === "path") {
+    process.stdout.write(globalConfigPath() + "\n");
+    return 0;
+  }
+
+  if (sub === "show") {
+    const { config, sources, warnings } = await loadConfig();
+    process.stdout.write(JSON.stringify(config, null, 2) + "\n");
+    if (sources.length === 0) {
+      process.stderr.write(color.gray(`(defaults — no file at ${shortenPath(globalConfigPath())})\n`));
+    }
+    for (const w of warnings) process.stderr.write(color.yellow(`warn ${w}\n`));
+    return 0;
+  }
+
+  if (sub === "init") {
+    const path = globalConfigPath();
+    const starter = {
+      $schema: "https://github.com/yoavshmariahu/treekeeper",
+      roots: defaultConfig().roots,
+      minAge: "30m",
+      interval: "15m",
+      onDirty: "archive",
+      onClosedPr: "archive",
+      protectBranches: defaultConfig().protectBranches,
+      protectPaths: [],
+      sessions: { grace: "20m" },
+    };
+    try {
+      await mkdir(dirname(path), { recursive: true });
+      await writeFile(path, JSON.stringify(starter, null, 2) + "\n", { flag: "wx" });
+      process.stdout.write(`wrote ${shortenPath(path)}\n`);
+      return 0;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "EEXIST") {
+        process.stderr.write(`${shortenPath(path)} already exists\n`);
+        return 1;
+      }
+      process.stderr.write(`could not write ${path}: ${(err as Error).message}\n`);
+      return 1;
+    }
+  }
+
+  process.stderr.write(USAGE + "\n");
+  return 2;
+}

package/src/commands/context.ts

@@ -0,0 +1,86 @@
+import type { Config } from "../core/config.js";
+import { loadConfig } from "../core/config.js";
+import type { Forge } from "../core/forge.js";
+import { createForge } from "../core/forge.js";
+import { discoverRepos, reposFromPaths } from "../core/scan.js";
+import { Logger } from "../util/log.js";
+import { expandPath } from "../util/paths.js";
+
+export interface CliFlags {
+  apply?: boolean;
+  yes?: boolean;
+  json?: boolean;
+  quiet?: boolean;
+  verbose?: boolean;
+  all?: boolean;
+  force?: boolean;
+  minAge?: string;
+  sessionGrace?: string;
+  forge?: string;
+  refresh?: boolean;
+  branchesOnly?: boolean;
+  worktreesOnly?: boolean;
+  sizes?: boolean;
+  interval?: string;
+  config?: string;
+  roots?: string[];
+}
+
+export interface Context {
+  config: Config;
+  logger: Logger;
+  forge: Forge;
+  warnings: string[];
+  configSources: string[];
+}
+
+/** Load config, apply CLI overrides, and build the shared logger and forge. */
+export async function createContext(flags: CliFlags): Promise<Context> {
+  const loaded = await loadConfig(flags.config ? expandPath(flags.config) : undefined);
+  const config = loaded.config;
+
+  if (flags.minAge !== undefined) config.minAge = flags.minAge;
+  if (flags.sessionGrace !== undefined) config.sessions.grace = flags.sessionGrace;
+  if (flags.forge === "none" || flags.forge === "github") config.forge = flags.forge;
+  if (flags.worktreesOnly) config.pruneBranches = false;
+  if (flags.roots && flags.roots.length > 0) config.roots = flags.roots.map((r) => expandPath(r));
+  if (flags.verbose) config.logLevel = "debug";
+
+  const logger = new Logger({
+    level: config.logLevel,
+    file: config.logFile,
+    quiet: flags.quiet === true,
+  });
+
+  for (const w of loaded.warnings) logger.warn(w);
+
+  const forge = createForge({
+    kind: config.forge,
+    cacheTtl: config.forgeCacheTtl,
+    logger,
+    refresh: flags.refresh === true,
+  });
+
+  return { config, logger, forge, warnings: loaded.warnings, configSources: loaded.sources };
+}
+
+/** Which repos a command should operate on, from positionals, `--all`, or cwd. */
+export async function resolveRepos(
+  ctx: Context,
+  positionals: string[],
+  flags: CliFlags,
+): Promise<string[]> {
+  const scan = { maxDepth: ctx.config.maxDepth, protectPaths: ctx.config.protectPaths, logger: ctx.logger };
+
+  if (positionals.length > 0) {
+    return reposFromPaths(positionals.map((p) => expandPath(p)), scan);
+  }
+  if (flags.all) {
+    return discoverRepos({ ...scan, roots: ctx.config.roots });
+  }
+  // Default to the repo containing the cwd, falling back to the configured
+  // roots when the cwd is not inside one (e.g. the daemon, started from "/").
+  const here = await reposFromPaths([process.cwd()], { ...scan, maxDepth: 1 });
+  if (here.length > 0) return here;
+  return discoverRepos({ ...scan, roots: ctx.config.roots });
+}

package/src/commands/daemon.ts

@@ -0,0 +1,86 @@
+import { readFile } from "node:fs/promises";
+import { loadConfig } from "../core/config.js";
+import {
+  daemonStatus, installDaemon, setDaemonRunning, sweepArgv, uninstallDaemon,
+} from "../daemon/service.js";
+import { formatKb } from "../util/bytes.js";
+import { color } from "../util/color.js";
+import { shortenPath } from "../util/paths.js";
+import { formatAgo, formatDuration } from "../util/time.js";
+import type { CliFlags } from "./context.js";
+
+const USAGE = `usage: treekeeper daemon <install|uninstall|start|stop|status|logs>`;
+
+export async function daemonCommand(args: string[], flags: CliFlags): Promise<number> {
+  const sub = args[0] ?? "status";
+
+  switch (sub) {
+    case "install": {
+      const { config } = await loadConfig();
+      const interval = flags.interval ?? config.interval;
+      const result = await installDaemon(interval);
+      for (const m of result.messages) {
+        process.stdout.write((result.ok ? "" : color.yellow("warn ")) + m + "\n");
+      }
+      if (result.ok) {
+        process.stdout.write(
+          color.gray(`it runs: ${sweepArgv().slice(1).join(" ")}\n`) +
+          color.gray("change the interval in config.json, then re-run `treekeeper daemon install`\n"),
+        );
+      }
+      return result.ok ? 0 : 1;
+    }
+    case "uninstall": {
+      const result = await uninstallDaemon();
+      for (const m of result.messages) process.stdout.write(m + "\n");
+      return result.ok ? 0 : 1;
+    }
+    case "start":
+    case "stop": {
+      const result = await setDaemonRunning(sub === "start");
+      for (const m of result.messages) process.stdout.write(m + "\n");
+      return result.ok ? 0 : 1;
+    }
+    case "status": {
+      const status = await daemonStatus();
+      if (flags.json) {
+        process.stdout.write(JSON.stringify(status, null, 2) + "\n");
+        return 0;
+      }
+      const lines = [
+        `manager   ${status.manager}`,
+        `installed ${status.installed ? color.green("yes") : color.gray("no")}` +
+          (status.unitPath ? color.gray(`  ${shortenPath(status.unitPath)}`) : ""),
+        `scheduled ${status.active ? color.green("yes") : color.gray("no")}` +
+          (status.intervalSeconds ? color.gray(`  every ${formatDuration(status.intervalSeconds * 1000)}`) : ""),
+      ];
+      if (status.lastSweep) {
+        const s = status.lastSweep;
+        lines.push(
+          `last run  ${formatAgo(s.at)}` +
+            color.gray(`  ${s.worktrees} worktree(s), ${s.branches} branch(es), ${formatKb(s.reclaimedKb)} in ${formatDuration(s.durationMs)}`),
+        );
+      } else {
+        lines.push(`last run  ${color.gray("never")}`);
+      }
+      lines.push(`logs      ${shortenPath(status.logFile)}`);
+      process.stdout.write(lines.join("\n") + "\n");
+      return 0;
+    }
+    case "logs": {
+      const status = await daemonStatus();
+      try {
+        const text = await readFile(status.logFile, "utf8");
+        const lines = text.split("\n");
+        process.stdout.write(lines.slice(-200).join("\n"));
+      } catch {
+        process.stderr.write(`no daemon log yet at ${status.logFile}\n`);
+        return 1;
+      }
+      return 0;
+    }
+    default:
+      process.stderr.write(USAGE + "\n");
+      return 2;
+  }
+}

package/src/commands/doctor.ts

@@ -0,0 +1,131 @@
+import { access, constants } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { globalConfigPath, loadConfig } from "../core/config.js";
+import { discoverRepos } from "../core/scan.js";
+import { daemonStatus } from "../daemon/service.js";
+import { gitVersion } from "../core/git.js";
+import { have, runOk } from "../util/exec.js";
+import { color } from "../util/color.js";
+import { Logger } from "../util/log.js";
+import { shortenPath } from "../util/paths.js";
+
+interface Check {
+  name: string;
+  ok: boolean | "warn";
+  detail: string;
+}
+
+/** Check that everything treekeeper depends on is actually present. */
+export async function doctorCommand(json: boolean): Promise<number> {
+  const checks: Check[] = [];
+  const { config, warnings, sources } = await loadConfig();
+
+  const git = await gitVersion();
+  checks.push({
+    name: "git",
+    ok: git !== null,
+    detail: git ?? "not found on PATH — treekeeper cannot do anything without it",
+  });
+
+  const gh = await have("gh");
+  if (config.forge === "github") {
+    if (!gh) {
+      checks.push({
+        name: "gh",
+        ok: "warn",
+        detail: "not installed — squash-merged branches will not be detected (brew install gh)",
+      });
+    } else {
+      const auth = await runOk("gh", ["auth", "status"], { timeoutMs: 20_000 });
+      checks.push({
+        name: "gh",
+        ok: auth !== null ? true : "warn",
+        detail: auth !== null ? "installed and authenticated" : "installed but not logged in (gh auth login)",
+      });
+    }
+  } else {
+    checks.push({ name: "gh", ok: true, detail: "forge is disabled in config" });
+  }
+
+  const lsof = await have("lsof");
+  checks.push({
+    name: "lsof",
+    ok: lsof ? true : "warn",
+    detail: lsof
+      ? "available — can tell when a process is still in a worktree"
+      : "missing — the 'process' session detector will be skipped",
+  });
+
+  checks.push({
+    name: "config",
+    ok: warnings.length === 0,
+    detail: sources.length > 0
+      ? `${shortenPath(sources[0]!)}${warnings.length > 0 ? ` — ${warnings.length} warning(s)` : ""}`
+      : `using defaults (no file at ${shortenPath(globalConfigPath())})`,
+  });
+
+  const repos = await discoverRepos({
+    roots: config.roots,
+    maxDepth: config.maxDepth,
+    protectPaths: config.protectPaths,
+    logger: new Logger({ level: "error" }),
+  });
+  checks.push({
+    name: "roots",
+    ok: repos.length > 0 ? true : "warn",
+    detail: `${repos.length} repo(s) under ${config.roots.map(shortenPath).join(", ")}`,
+  });
+
+  for (const detector of config.sessions.detectors) {
+    if (detector === "claude-code") {
+      const dir = join(homedir(), ".claude", "projects");
+      const present = await exists(dir);
+      checks.push({
+        name: "detector claude-code",
+        ok: true,
+        detail: present ? `reading ${shortenPath(dir)}` : "no Claude Code sessions on this machine",
+      });
+    } else if (detector === "codex") {
+      const dir = join(homedir(), ".codex", "sessions");
+      const present = await exists(dir);
+      checks.push({
+        name: "detector codex",
+        ok: true,
+        detail: present ? `reading ${shortenPath(dir)}` : "no Codex sessions on this machine",
+      });
+    }
+  }
+
+  const daemon = await daemonStatus();
+  checks.push({
+    name: "daemon",
+    ok: daemon.installed ? (daemon.active ? true : "warn") : "warn",
+    detail: daemon.installed
+      ? daemon.active ? "installed and scheduled" : "installed but not loaded (treekeeper daemon start)"
+      : "not installed (treekeeper daemon install)",
+  });
+
+  if (json) {
+    process.stdout.write(JSON.stringify({ checks, warnings }, null, 2) + "\n");
+    return checks.some((c) => c.ok === false) ? 1 : 0;
+  }
+
+  const width = Math.max(...checks.map((c) => c.name.length));
+  for (const c of checks) {
+    const mark = c.ok === true ? color.green("ok  ") : c.ok === "warn" ? color.yellow("warn") : color.red("fail");
+    process.stdout.write(`${mark}  ${c.name.padEnd(width)}  ${color.gray(c.detail)}\n`);
+  }
+  for (const w of warnings) process.stdout.write(color.yellow(`warn  config: ${w}\n`));
+
+  return checks.some((c) => c.ok === false) ? 1 : 0;
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await access(path, constants.R_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}