@yoavsh/treekeeper 0.0.0-stage → 0.1.0

package/src/commands/gc.ts

@@ -0,0 +1,108 @@
+import { applyPlan } from "../core/apply.js";
+import { buildPlan } from "../core/plan.js";
+import { renderApply, renderPlan } from "../core/render.js";
+import { color } from "../util/color.js";
+import { formatKb } from "../util/bytes.js";
+import { confirm } from "../util/prompt.js";
+import { acquireLock } from "../daemon/lock.js";
+import { recordSweep } from "../daemon/state.js";
+import type { CliFlags } from "./context.js";
+import { createContext, resolveRepos } from "./context.js";
+
+export async function gcCommand(positionals: string[], flags: CliFlags): Promise<number> {
+  const ctx = await createContext(flags);
+  const repos = await resolveRepos(ctx, positionals, flags);
+
+  if (repos.length === 0) {
+    if (flags.json) {
+      process.stdout.write(JSON.stringify({ version: 1, repos: [], error: "no git repos found" }) + "\n");
+    } else {
+      process.stderr.write(
+        `no git repos found. Looked in ${ctx.config.roots.join(", ")}.\n` +
+        `Set "roots" in your config, pass a path, or run from inside a repo.\n`,
+      );
+    }
+    return 1;
+  }
+
+  const plan = await buildPlan({
+    config: ctx.config,
+    repos,
+    forge: ctx.forge,
+    logger: ctx.logger,
+    force: flags.force,
+    allSizes: flags.sizes,
+    skipWorktrees: flags.branchesOnly,
+  });
+
+  if (!flags.apply) {
+    if (flags.json) {
+      process.stdout.write(JSON.stringify(plan, null, 2) + "\n");
+    } else {
+      const text = renderPlan(plan, { verbose: flags.verbose, quiet: flags.quiet });
+      process.stdout.write(text + "\n");
+      if (plan.summary.worktreesReclaimable > 0 || plan.summary.branchesDeletable > 0) {
+        process.stdout.write(color.gray("re-run with --apply to do it\n"));
+      }
+    }
+    return 0;
+  }
+
+  const nothingToDo =
+    plan.summary.worktreesReclaimable === 0 && plan.summary.branchesDeletable === 0;
+
+  if (!nothingToDo && !flags.yes) {
+    if (!flags.json) {
+      process.stdout.write(renderPlan(plan, { verbose: flags.verbose }) + "\n\n");
+    }
+    const ok = await confirm(
+      `Remove ${plan.summary.worktreesReclaimable} worktree(s) (${formatKb(plan.summary.reclaimKb)}) ` +
+      `and ${plan.summary.branchesDeletable} branch(es)?`,
+      false,
+    );
+    if (!ok) {
+      process.stderr.write("aborted — nothing was removed\n");
+      return 130;
+    }
+  }
+
+  // One sweep at a time per machine: a scheduled sweep and a manual one must
+  // never race over the same worktree.
+  const lock = await acquireLock();
+  if (!lock) {
+    const message = "another treekeeper sweep is already running";
+    if (flags.json) process.stdout.write(JSON.stringify({ error: message }) + "\n");
+    else process.stderr.write(message + "\n");
+    return 75;
+  }
+
+  const startedAt = Date.now();
+  let result;
+  try {
+    result = await applyPlan({
+      plan,
+      config: ctx.config,
+      logger: ctx.logger,
+      force: flags.force,
+    });
+  } finally {
+    await lock.release();
+  }
+
+  await recordSweep({
+    at: startedAt,
+    durationMs: Date.now() - startedAt,
+    repos: plan.summary.repos,
+    worktrees: result.removedWorktrees.length,
+    branches: result.deletedBranches.length,
+    reclaimedKb: result.reclaimedKb,
+    failures: result.failures.length,
+  });
+
+  if (flags.json) {
+    process.stdout.write(JSON.stringify({ plan, result }, null, 2) + "\n");
+  } else {
+    process.stdout.write(renderApply(result, plan) + "\n");
+  }
+  return result.failures.some((f) => f.stage === "archive") ? 1 : 0;
+}

package/src/commands/status.ts

@@ -0,0 +1,68 @@
+import { buildPlan } from "../core/plan.js";
+import { renderPlan } from "../core/render.js";
+import { listArchives } from "../core/archive.js";
+import { discoverRepos } from "../core/scan.js";
+import { daemonStatus } from "../daemon/service.js";
+import { formatKb } from "../util/bytes.js";
+import { color } from "../util/color.js";
+import { shortenPath } from "../util/paths.js";
+import { formatAgo } from "../util/time.js";
+import type { CliFlags } from "./context.js";
+import { createContext } from "./context.js";
+
+/** A whole-machine overview: what is reclaimable, and is the daemon running. */
+export async function statusCommand(flags: CliFlags): Promise<number> {
+  const ctx = await createContext({ ...flags, quiet: true });
+  const repos = await discoverRepos({
+    roots: ctx.config.roots,
+    maxDepth: ctx.config.maxDepth,
+    protectPaths: ctx.config.protectPaths,
+    logger: ctx.logger,
+  });
+
+  const plan = await buildPlan({
+    config: ctx.config,
+    repos,
+    forge: ctx.forge,
+    logger: ctx.logger,
+  });
+
+  const service = await daemonStatus();
+  const archives = await listArchives(ctx.config.archive.dir);
+
+  if (flags.json) {
+    process.stdout.write(
+      JSON.stringify({ plan, daemon: service, archives: archives.length }, null, 2) + "\n",
+    );
+    return 0;
+  }
+
+  const lines: string[] = [];
+  lines.push(
+    `${color.bold("treekeeper")}  ` +
+    color.gray(`${plan.summary.repos} repos · ${plan.summary.worktreesScanned} worktrees · roots ${ctx.config.roots.map(shortenPath).join(", ")}`),
+  );
+  lines.push(
+    service.installed
+      ? `daemon     ${service.active ? color.green("scheduled") : color.yellow("installed, not loaded")}` +
+        color.gray(`  every ${ctx.config.interval}`)
+      : `daemon     ${color.gray("not installed")}  ${color.gray("run `treekeeper daemon install`")}`,
+  );
+  if (service.lastSweep) {
+    lines.push(`last sweep ${formatAgo(service.lastSweep.at)}  ` + color.gray(
+      `reclaimed ${formatKb(service.lastSweep.reclaimedKb)} from ${service.lastSweep.worktrees} worktree(s)`,
+    ));
+  }
+  if (archives.length > 0) {
+    const newest = archives[0]!;
+    lines.push(
+      `archives   ${archives.length} kept in ${shortenPath(ctx.config.archive.dir)}  ` +
+      color.gray(`newest ${formatAgo(Date.parse(newest.createdAt))}, retention ${ctx.config.archive.retention}`),
+    );
+  }
+  lines.push("");
+  lines.push(renderPlan(plan, { verbose: flags.verbose }));
+
+  process.stdout.write(lines.join("\n") + "\n");
+  return 0;
+}

package/src/commands/watch.ts

@@ -0,0 +1,48 @@
+import { color } from "../util/color.js";
+import { formatDuration, parseDuration } from "../util/time.js";
+import { loadConfig } from "../core/config.js";
+import type { CliFlags } from "./context.js";
+import { gcCommand } from "./gc.js";
+
+/**
+ * Foreground watcher, for people who would rather supervise treekeeper
+ * themselves (tmux, pm2, Docker) than install a launchd/systemd unit.
+ *
+ * Config is re-read every pass, so editing config.json takes effect without a
+ * restart.
+ */
+export async function watchCommand(flags: CliFlags): Promise<number> {
+  let stopping = false;
+  const stop = () => {
+    stopping = true;
+  };
+  process.on("SIGINT", stop);
+  process.on("SIGTERM", stop);
+
+  const { config } = await loadConfig();
+  const firstInterval = parseDuration(flags.interval ?? config.interval);
+  process.stderr.write(
+    `${color.bold("treekeeper")} watching ${config.roots.join(", ")} every ${formatDuration(firstInterval)}\n` +
+    color.gray("ctrl-c to stop\n"),
+  );
+
+  while (!stopping) {
+    await gcCommand([], { ...flags, all: true, apply: true, yes: true });
+    if (stopping) break;
+
+    const { config: fresh } = await loadConfig();
+    const intervalMs = parseDuration(flags.interval ?? fresh.interval);
+    // Wake up often enough to notice a signal promptly.
+    const deadline = Date.now() + intervalMs;
+    while (!stopping && Date.now() < deadline) {
+      await sleep(Math.min(1_000, deadline - Date.now()));
+    }
+  }
+
+  process.stderr.write("stopped\n");
+  return 0;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, Math.max(0, ms)));
+}

package/src/core/apply.ts

@@ -0,0 +1,276 @@
+import { stat } from "node:fs/promises";
+import type { Config } from "./config.js";
+import { loadRepoConfig } from "./config.js";
+import type { ArchiveRecord } from "./archive.js";
+import { archiveWork, pruneArchives } from "./archive.js";
+import * as git from "./git.js";
+import type { BranchCandidate, Plan, WorktreeCandidate } from "./plan.js";
+import type { Logger } from "../util/log.js";
+import { parseDuration } from "../util/time.js";
+
+export interface ApplyOptions {
+  plan: Plan;
+  config: Config;
+  logger: Logger;
+  force?: boolean;
+  /** Skip the just-in-time safety re-check (only for tests). */
+  skipReverify?: boolean;
+}
+
+export interface Removal {
+  path: string;
+  branch: string | null;
+  repo: string;
+  sizeKb: number;
+  reason: string;
+  archive: string | null;
+}
+
+export interface Failure {
+  target: string;
+  stage: "reverify" | "archive" | "remove" | "branch";
+  message: string;
+}
+
+export interface ApplyResult {
+  removedWorktrees: Removal[];
+  deletedBranches: Array<{ repo: string; name: string; reason: string; archive: string | null }>;
+  reclaimedKb: number;
+  archives: ArchiveRecord[];
+  failures: Failure[];
+  prunedArchives: string[];
+}
+
+/**
+ * Carry out a plan.
+ *
+ * Each worktree is re-checked immediately before removal, because a plan is a
+ * snapshot: with a daemon, minutes can pass between deciding and acting, and in
+ * that time an agent may have started working in the directory again.
+ */
+export async function applyPlan(opts: ApplyOptions): Promise<ApplyResult> {
+  const { plan, logger } = opts;
+  const result: ApplyResult = {
+    removedWorktrees: [],
+    deletedBranches: [],
+    reclaimedKb: 0,
+    archives: [],
+    failures: [],
+    prunedArchives: [],
+  };
+
+  for (const repoPlan of plan.repos) {
+    if (repoPlan.skipped) continue;
+    const { config: cfg } = await loadRepoConfig(repoPlan.repo, opts.config);
+    const base = await preferredBase(repoPlan.repo, repoPlan.defaultBranch);
+
+    for (const candidate of repoPlan.worktrees) {
+      if (candidate.verdict.action !== "reclaim") continue;
+      await removeWorktree(candidate, { cfg, base, result, logger, opts });
+    }
+
+    for (const branch of repoPlan.branches) {
+      await deleteBranch(branch, { cfg, base, result, logger });
+    }
+
+    await git.pruneWorktrees(repoPlan.repo);
+    if (cfg.pruneRemotes) await git.remotePrune(repoPlan.repo);
+  }
+
+  if (opts.config.archive.enabled) {
+    const pruned = await pruneArchives(
+      opts.config.archive.dir,
+      parseDuration(opts.config.archive.retention),
+      plan.now,
+    );
+    result.prunedArchives = pruned.removed;
+    if (pruned.removed.length > 0) {
+      logger.event("archive-pruned", { count: pruned.removed.length, freedKb: pruned.freedKb });
+    }
+  }
+
+  return result;
+}
+
+interface StepCtx {
+  cfg: Config;
+  base: string | null;
+  result: ApplyResult;
+  logger: Logger;
+  opts?: ApplyOptions;
+}
+
+async function removeWorktree(c: WorktreeCandidate, ctx: StepCtx): Promise<void> {
+  const { logger, result } = ctx;
+
+  if (!(ctx.opts?.skipReverify ?? false)) {
+    const problem = await reverify(c);
+    if (problem) {
+      logger.warn(`skipping ${c.path}: ${problem}`);
+      logger.event("skip", { path: c.path, branch: c.branch, stage: "reverify", reason: problem });
+      result.failures.push({ target: c.path, stage: "reverify", message: problem });
+      return;
+    }
+  }
+
+  let archive: ArchiveRecord | null = null;
+  try {
+    archive = await archiveWork({
+      repo: c.repo,
+      worktreePath: c.path,
+      branch: c.branch,
+      head: c.head,
+      reason: c.verdict.reason,
+      risks: c.verdict.risks,
+      merge: c.merge,
+      base: ctx.base,
+      config: ctx.cfg.archive,
+      logger,
+    });
+  } catch (err) {
+    const message = (err as Error).message;
+    // Never remove work we failed to back up.
+    logger.error(`archive failed for ${c.path}, keeping it: ${message}`);
+    result.failures.push({ target: c.path, stage: "archive", message });
+    return;
+  }
+  if (archive) result.archives.push(archive);
+
+  const archived = archive !== null;
+  let removal = await git.removeWorktree(c.repo, c.path, false);
+  if (!removal.ok && (archived || ctx.opts?.force)) {
+    removal = await git.removeWorktree(c.repo, c.path, true);
+  }
+
+  if (!removal.ok) {
+    const message = removal.error ?? "git worktree remove failed";
+    logger.error(`could not remove ${c.path}: ${message}`);
+    result.failures.push({ target: c.path, stage: "remove", message });
+    return;
+  }
+
+  const sizeKb = c.sizeKb ?? 0;
+  result.removedWorktrees.push({
+    path: c.path,
+    branch: c.branch,
+    repo: c.repo,
+    sizeKb,
+    reason: c.verdict.reason,
+    archive: archive?.dir ?? null,
+  });
+  result.reclaimedKb += sizeKb;
+  logger.event("reclaim", {
+    path: c.path,
+    repo: c.repo,
+    branch: c.branch,
+    sizeKb,
+    reason: c.verdict.reason,
+    risks: c.verdict.risks,
+    archive: archive?.dir ?? null,
+  });
+
+  if (c.branch) {
+    const ok = await git.deleteBranch(c.repo, c.branch, true);
+    if (ok) {
+      result.deletedBranches.push({
+        repo: c.repo,
+        name: c.branch,
+        reason: c.verdict.reason,
+        archive: archive?.dir ?? null,
+      });
+    } else {
+      logger.warn(`removed ${c.path} but could not delete branch ${c.branch}`);
+      result.failures.push({
+        target: `${c.repo}#${c.branch}`,
+        stage: "branch",
+        message: "git branch -D failed",
+      });
+    }
+  }
+}
+
+async function deleteBranch(b: BranchCandidate, ctx: StepCtx): Promise<void> {
+  const { logger, result } = ctx;
+
+  // The tip may have moved since the plan was built.
+  const tip = await git.revParse(b.repo, `refs/heads/${b.name}`);
+  if (tip !== b.head) {
+    const message = "branch tip moved since the plan was built";
+    logger.warn(`skipping branch ${b.name}: ${message}`);
+    result.failures.push({ target: `${b.repo}#${b.name}`, stage: "reverify", message });
+    return;
+  }
+
+  let archive: ArchiveRecord | null = null;
+  if (b.verdict.risks.length > 0) {
+    archive = await archiveWork({
+      repo: b.repo,
+      worktreePath: null,
+      branch: b.name,
+      head: b.head,
+      reason: b.verdict.reason,
+      risks: b.verdict.risks,
+      merge: b.merge,
+      base: ctx.base,
+      config: ctx.cfg.archive,
+      logger,
+    });
+    if (archive) result.archives.push(archive);
+  }
+
+  if (await git.deleteBranch(b.repo, b.name, true)) {
+    result.deletedBranches.push({
+      repo: b.repo,
+      name: b.name,
+      reason: b.verdict.reason,
+      archive: archive?.dir ?? null,
+    });
+    logger.event("branch-delete", {
+      repo: b.repo,
+      branch: b.name,
+      reason: b.verdict.reason,
+      archive: archive?.dir ?? null,
+    });
+  } else {
+    result.failures.push({
+      target: `${b.repo}#${b.name}`,
+      stage: "branch",
+      message: "git branch -D failed",
+    });
+  }
+}
+
+/**
+ * Confirm the worktree is still exactly what the plan described. Anything that
+ * moved — a new commit, a switched branch, a fresh file — means the snapshot is
+ * stale and the worktree is left alone until the next sweep.
+ */
+async function reverify(c: WorktreeCandidate): Promise<string | null> {
+  try {
+    const st = await stat(c.path);
+    if (!st.isDirectory()) return "no longer a directory";
+    if (st.mtimeMs > c.lastTouched + 1_000) return "directory changed since the plan was built";
+  } catch {
+    return "directory no longer exists";
+  }
+
+  const worktrees = await git.listWorktrees(c.repo);
+  const current = worktrees.find((w) => w.path === c.path);
+  if (!current) return "no longer a registered worktree";
+  if (current.branch !== c.branch) return `branch changed to ${current.branch ?? "(detached)"}`;
+  if (current.head !== c.head) return "new commits since the plan was built";
+  if (current.locked) return "worktree was locked";
+
+  if (!c.dirty) {
+    const dirty = await git.dirtyState(c.path);
+    if (dirty.dirty) return "uncommitted changes appeared since the plan was built";
+  }
+  return null;
+}
+
+async function preferredBase(repo: string, defaultBranch: string): Promise<string | null> {
+  for (const ref of [`refs/remotes/origin/${defaultBranch}`, `refs/heads/${defaultBranch}`]) {
+    if (await git.refExists(repo, ref)) return ref;
+  }
+  return null;
+}