@yoavsh/treekeeper 0.0.0-stage → 0.1.0

package/src/daemon/service.ts

@@ -0,0 +1,321 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { run } from "../util/exec.js";
+import { treekeeperHome } from "../util/paths.js";
+import { parseDuration } from "../util/time.js";
+import type { SweepRecord } from "./state.js";
+import { readState } from "./state.js";
+
+export const LABEL = "com.treekeeper.agent";
+export const SYSTEMD_UNIT = "treekeeper";
+
+export type Manager = "launchd" | "systemd" | "unsupported";
+
+export interface DaemonStatus {
+  manager: Manager;
+  installed: boolean;
+  /** Loaded with the service manager and scheduled to run. */
+  active: boolean;
+  unitPath: string | null;
+  intervalSeconds: number | null;
+  lastSweep: SweepRecord | null;
+  logFile: string;
+}
+
+export function currentManager(): Manager {
+  if (process.platform === "darwin") return "launchd";
+  if (process.platform === "linux") return "systemd";
+  return "unsupported";
+}
+
+function launchAgentPath(): string {
+  return join(homedir(), "Library", "LaunchAgents", `${LABEL}.plist`);
+}
+
+function systemdDir(): string {
+  const base = process.env.XDG_CONFIG_HOME
+    ? resolve(process.env.XDG_CONFIG_HOME)
+    : join(homedir(), ".config");
+  return join(base, "systemd", "user");
+}
+
+function daemonLogPath(): string {
+  return join(treekeeperHome(), "daemon.out.log");
+}
+
+/** Absolute path to this installation's CLI entry point. */
+export function cliPath(): string {
+  return resolve(fileURLToPath(new URL("../cli.js", import.meta.url)));
+}
+
+/** The command a scheduled sweep runs. */
+export function sweepArgv(extra: string[] = []): string[] {
+  return [process.execPath, cliPath(), "gc", "--all", "--apply", "--yes", "--quiet", ...extra];
+}
+
+export async function daemonStatus(): Promise<DaemonStatus> {
+  const manager = currentManager();
+  const state = await readState();
+  const base: DaemonStatus = {
+    manager,
+    installed: false,
+    active: false,
+    unitPath: null,
+    intervalSeconds: null,
+    lastSweep: state.lastSweep,
+    logFile: daemonLogPath(),
+  };
+
+  if (manager === "launchd") {
+    const path = launchAgentPath();
+    const plist = await readIfPresent(path);
+    base.unitPath = path;
+    base.installed = plist !== null;
+    if (plist) {
+      const m = /<key>StartInterval<\/key>\s*<integer>(\d+)<\/integer>/.exec(plist);
+      base.intervalSeconds = m?.[1] ? Number(m[1]) : null;
+      const list = await run("launchctl", ["list", LABEL], { timeoutMs: 10_000 });
+      base.active = list.code === 0;
+    }
+    return base;
+  }
+
+  if (manager === "systemd") {
+    const timer = join(systemdDir(), `${SYSTEMD_UNIT}.timer`);
+    const unit = await readIfPresent(timer);
+    base.unitPath = timer;
+    base.installed = unit !== null;
+    if (unit) {
+      const m = /OnUnitActiveSec=(\d+)/.exec(unit);
+      base.intervalSeconds = m?.[1] ? Number(m[1]) : null;
+      const active = await run("systemctl", ["--user", "is-active", `${SYSTEMD_UNIT}.timer`], {
+        timeoutMs: 10_000,
+      });
+      base.active = active.stdout.trim() === "active";
+    }
+    return base;
+  }
+
+  return base;
+}
+
+export interface InstallResult {
+  ok: boolean;
+  manager: Manager;
+  unitPath: string | null;
+  messages: string[];
+}
+
+/** Write and load the service definition for the current platform. */
+export async function installDaemon(interval: string): Promise<InstallResult> {
+  const manager = currentManager();
+  const seconds = Math.max(60, Math.round(parseDuration(interval) / 1000));
+  const messages: string[] = [];
+
+  if (manager === "launchd") {
+    const path = launchAgentPath();
+    await mkdir(dirname(path), { recursive: true });
+    await mkdir(treekeeperHome(), { recursive: true });
+    await writeFile(path, launchdPlist(seconds));
+
+    // bootout first so a re-install picks up a changed interval.
+    await run("launchctl", ["bootout", `gui/${process.getuid?.() ?? 501}/${LABEL}`], { timeoutMs: 15_000 });
+    const boot = await run(
+      "launchctl",
+      ["bootstrap", `gui/${process.getuid?.() ?? 501}`, path],
+      { timeoutMs: 20_000 },
+    );
+    if (boot.code !== 0) {
+      const legacy = await run("launchctl", ["load", "-w", path], { timeoutMs: 20_000 });
+      if (legacy.code !== 0) {
+        messages.push(`wrote ${path} but launchctl could not load it: ${(boot.stderr || legacy.stderr).trim()}`);
+        return { ok: false, manager, unitPath: path, messages };
+      }
+    }
+    messages.push(`installed ${path}`, `sweeping every ${seconds}s · logs in ${daemonLogPath()}`);
+    return { ok: true, manager, unitPath: path, messages };
+  }
+
+  if (manager === "systemd") {
+    const dir = systemdDir();
+    await mkdir(dir, { recursive: true });
+    await mkdir(treekeeperHome(), { recursive: true });
+    const servicePath = join(dir, `${SYSTEMD_UNIT}.service`);
+    const timerPath = join(dir, `${SYSTEMD_UNIT}.timer`);
+    await writeFile(servicePath, systemdService());
+    await writeFile(timerPath, systemdTimer(seconds));
+
+    await run("systemctl", ["--user", "daemon-reload"], { timeoutMs: 20_000 });
+    const enable = await run(
+      "systemctl",
+      ["--user", "enable", "--now", `${SYSTEMD_UNIT}.timer`],
+      { timeoutMs: 20_000 },
+    );
+    if (enable.code !== 0) {
+      messages.push(`wrote the units but systemctl failed: ${enable.stderr.trim()}`);
+      return { ok: false, manager, unitPath: timerPath, messages };
+    }
+    messages.push(
+      `installed ${servicePath} and ${timerPath}`,
+      `sweeping every ${seconds}s`,
+      "tip: `loginctl enable-linger $USER` keeps the timer running while you are logged out",
+    );
+    return { ok: true, manager, unitPath: timerPath, messages };
+  }
+
+  messages.push(
+    `no supported service manager on ${process.platform}.`,
+    "Run `treekeeper watch` under your own supervisor, or schedule `treekeeper gc --all --apply --yes`.",
+  );
+  return { ok: false, manager, unitPath: null, messages };
+}
+
+export async function uninstallDaemon(): Promise<InstallResult> {
+  const manager = currentManager();
+  const messages: string[] = [];
+
+  if (manager === "launchd") {
+    const path = launchAgentPath();
+    await run("launchctl", ["bootout", `gui/${process.getuid?.() ?? 501}/${LABEL}`], { timeoutMs: 15_000 });
+    await run("launchctl", ["unload", "-w", path], { timeoutMs: 15_000 });
+    await rm(path, { force: true });
+    messages.push(`removed ${path}`);
+    return { ok: true, manager, unitPath: path, messages };
+  }
+
+  if (manager === "systemd") {
+    const dir = systemdDir();
+    await run("systemctl", ["--user", "disable", "--now", `${SYSTEMD_UNIT}.timer`], { timeoutMs: 20_000 });
+    await rm(join(dir, `${SYSTEMD_UNIT}.timer`), { force: true });
+    await rm(join(dir, `${SYSTEMD_UNIT}.service`), { force: true });
+    await run("systemctl", ["--user", "daemon-reload"], { timeoutMs: 20_000 });
+    messages.push("removed the treekeeper timer and service");
+    return { ok: true, manager, unitPath: null, messages };
+  }
+
+  messages.push("nothing to uninstall");
+  return { ok: true, manager, unitPath: null, messages };
+}
+
+export async function setDaemonRunning(running: boolean): Promise<InstallResult> {
+  const manager = currentManager();
+  const messages: string[] = [];
+  if (manager === "launchd") {
+    const path = launchAgentPath();
+    const uid = process.getuid?.() ?? 501;
+    const r = running
+      ? await run("launchctl", ["bootstrap", `gui/${uid}`, path], { timeoutMs: 20_000 })
+      : await run("launchctl", ["bootout", `gui/${uid}/${LABEL}`], { timeoutMs: 20_000 });
+    messages.push(r.code === 0 ? (running ? "started" : "stopped") : (r.stderr || r.stdout).trim());
+    return { ok: r.code === 0, manager, unitPath: path, messages };
+  }
+  if (manager === "systemd") {
+    const r = await run(
+      "systemctl",
+      ["--user", running ? "start" : "stop", `${SYSTEMD_UNIT}.timer`],
+      { timeoutMs: 20_000 },
+    );
+    messages.push(r.code === 0 ? (running ? "started" : "stopped") : r.stderr.trim());
+    return { ok: r.code === 0, manager, unitPath: null, messages };
+  }
+  messages.push(`not supported on ${process.platform}`);
+  return { ok: false, manager, unitPath: null, messages };
+}
+
+export function launchdPlist(seconds: number): string {
+  const args = sweepArgv()
+    .map((a) => `    <string>${escapeXml(a)}</string>`)
+    .join("\n");
+  const log = escapeXml(daemonLogPath());
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+${args}
+  </array>
+  <key>StartInterval</key>
+  <integer>${seconds}</integer>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>LowPriorityIO</key>
+  <true/>
+  <key>Nice</key>
+  <integer>5</integer>
+  <key>ProcessType</key>
+  <string>Background</string>
+  <key>StandardOutPath</key>
+  <string>${log}</string>
+  <key>StandardErrorPath</key>
+  <string>${log}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${escapeXml(schedulerPath())}</string>
+  </dict>
+</dict>
+</plist>
+`;
+}
+
+export function systemdService(): string {
+  const [exe, ...rest] = sweepArgv();
+  return `[Unit]
+Description=treekeeper — reclaim disk from finished agent worktrees
+Documentation=https://github.com/yoavshmariahu/treekeeper
+
+[Service]
+Type=oneshot
+Nice=5
+IOSchedulingClass=idle
+Environment=PATH=${schedulerPath()}
+ExecStart=${exe} ${rest.join(" ")}
+`;
+}
+
+export function systemdTimer(seconds: number): string {
+  return `[Unit]
+Description=treekeeper periodic sweep
+
+[Timer]
+OnBootSec=300
+OnUnitActiveSec=${seconds}
+AccuracySec=60
+Persistent=true
+
+[Install]
+WantedBy=timers.target
+`;
+}
+
+/**
+ * Service managers start jobs with a minimal PATH, which would hide `git` and
+ * `gh`. Carry the installing shell's PATH plus the usual suspects.
+ */
+function schedulerPath(): string {
+  const extra = ["/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin", "/usr/sbin", "/sbin"];
+  const current = (process.env.PATH ?? "").split(":").filter((p) => p !== "");
+  const seen = new Set<string>();
+  return [...current, ...extra].filter((p) => (seen.has(p) ? false : (seen.add(p), true))).join(":");
+}
+
+function escapeXml(s: string): string {
+  return s
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}
+
+async function readIfPresent(path: string): Promise<string | null> {
+  try {
+    return await readFile(path, "utf8");
+  } catch {
+    return null;
+  }
+}

package/src/daemon/state.ts

@@ -0,0 +1,49 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { treekeeperHome } from "../util/paths.js";
+
+export interface SweepRecord {
+  at: number;
+  durationMs: number;
+  repos: number;
+  worktrees: number;
+  branches: number;
+  reclaimedKb: number;
+  failures: number;
+}
+
+export interface State {
+  version: 1;
+  lastSweep: SweepRecord | null;
+  sweeps: number;
+  totalReclaimedKb: number;
+}
+
+export function statePath(): string {
+  return join(treekeeperHome(), "state.json");
+}
+
+export async function readState(): Promise<State> {
+  try {
+    const parsed: unknown = JSON.parse(await readFile(statePath(), "utf8"));
+    if (parsed && typeof parsed === "object" && (parsed as State).version === 1) {
+      return parsed as State;
+    }
+  } catch {
+    /* first run */
+  }
+  return { version: 1, lastSweep: null, sweeps: 0, totalReclaimedKb: 0 };
+}
+
+export async function recordSweep(sweep: SweepRecord): Promise<void> {
+  const state = await readState();
+  state.lastSweep = sweep;
+  state.sweeps += 1;
+  state.totalReclaimedKb += sweep.reclaimedKb;
+  try {
+    await mkdir(treekeeperHome(), { recursive: true });
+    await writeFile(statePath(), JSON.stringify(state, null, 2) + "\n");
+  } catch {
+    /* a missing state file only costs a status line */
+  }
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Programmatic entry point, for harnesses that would rather call treekeeper
+ * in-process than shell out to the CLI.
+ *
+ *   import { loadConfig, createForge, discoverRepos, buildPlan, applyPlan } from "@yoavsh/treekeeper";
+ */
+export { loadConfig, loadRepoConfig, defaultConfig, globalConfigPath } from "./core/config.js";
+export type { Config, SessionConfig, ArchiveConfig, DirtyPolicy } from "./core/config.js";
+
+export { buildPlan, policyFromConfig, reclaimable, mergeStatus } from "./core/plan.js";
+export type {
+  Plan, PlanOptions, PlanSummary, RepoPlan, WorktreeCandidate, BranchCandidate,
+} from "./core/plan.js";
+
+export { decideWorktree, decideBranch } from "./core/decide.js";
+export type {
+  Verdict, Policy, WorktreeFacts, BranchFacts, MergeStatus, Risk,
+} from "./core/decide.js";
+
+export { applyPlan } from "./core/apply.js";
+export type { ApplyOptions, ApplyResult, Removal, Failure } from "./core/apply.js";
+
+export { archiveWork, listArchives, pruneArchives } from "./core/archive.js";
+export type { ArchiveRecord } from "./core/archive.js";
+
+export { createForge, selectPr } from "./core/forge.js";
+export type { Forge, PrRef, PrIndex, PrState } from "./core/forge.js";
+
+export { discoverRepos, reposFromPaths } from "./core/scan.js";
+export { createActivityContext, detectActivity, isActive } from "./core/sessions.js";
+export type { ActivityContext, ActivityHit } from "./core/sessions.js";
+
+export { renderPlan, renderApply, summaryLine } from "./core/render.js";
+export { Logger } from "./util/log.js";
+export { parseDuration, formatDuration } from "./util/time.js";
+export { main as cli } from "./cli.js";

package/src/util/bytes.ts

@@ -0,0 +1,11 @@
+/** Kilobytes (as reported by `du -sk`) to a short human string. */
+export function formatKb(kb: number): string {
+  if (!Number.isFinite(kb) || kb < 0) return "?";
+  if (kb >= 1024 * 1024) return `${(kb / (1024 * 1024)).toFixed(1)}G`;
+  if (kb >= 1024) return `${Math.round(kb / 1024)}M`;
+  return `${Math.round(kb)}K`;
+}
+
+export function formatBytes(bytes: number): string {
+  return formatKb(bytes / 1024);
+}

package/src/util/color.ts

@@ -0,0 +1,33 @@
+const enabled = (() => {
+  if (process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== "") return false;
+  if (process.env.FORCE_COLOR !== undefined && process.env.FORCE_COLOR !== "0") return true;
+  if (process.env.TERM === "dumb") return false;
+  return Boolean(process.stdout.isTTY);
+})();
+
+const wrap = (open: string, close = "\u001b[0m") => (s: string | number) =>
+  enabled ? `${open}${s}${close}` : String(s);
+
+export const color = {
+  enabled,
+  bold: wrap("\u001b[1m"),
+  dim: wrap("\u001b[2m"),
+  red: wrap("\u001b[31m"),
+  green: wrap("\u001b[32m"),
+  yellow: wrap("\u001b[33m"),
+  blue: wrap("\u001b[34m"),
+  magenta: wrap("\u001b[35m"),
+  cyan: wrap("\u001b[36m"),
+  gray: wrap("\u001b[90m"),
+};
+
+/** Visible width, ignoring ANSI escapes, so columns line up when colour is on. */
+export function visibleWidth(s: string): number {
+  // eslint-disable-next-line no-control-regex
+  return s.replace(/\u001b\[[0-9;]*m/g, "").length;
+}
+
+export function padEndVisible(s: string, width: number): string {
+  const pad = width - visibleWidth(s);
+  return pad > 0 ? s + " ".repeat(pad) : s;
+}

package/src/util/exec.ts

@@ -0,0 +1,80 @@
+import { execFile } from "node:child_process";
+
+export interface RunResult {
+  code: number;
+  stdout: string;
+  stderr: string;
+  /** True when the binary itself could not be launched (not installed, EACCES, timeout). */
+  failedToStart: boolean;
+}
+
+export interface RunOptions {
+  cwd?: string;
+  timeoutMs?: number;
+  env?: NodeJS.ProcessEnv;
+  maxBuffer?: number;
+  input?: string;
+}
+
+/**
+ * Run a command without ever throwing. Every caller in treekeeper has to make a
+ * decision from the exit code (a missing `gh`, a repo without a remote, a branch
+ * that vanished), so an exception-based API would just mean try/catch everywhere.
+ */
+export function run(cmd: string, args: string[], opts: RunOptions = {}): Promise<RunResult> {
+  return new Promise((resolve) => {
+    const child = execFile(
+      cmd,
+      args,
+      {
+        cwd: opts.cwd,
+        timeout: opts.timeoutMs ?? 60_000,
+        maxBuffer: opts.maxBuffer ?? 64 * 1024 * 1024,
+        env: opts.env ?? process.env,
+        encoding: "utf8",
+      },
+      (err, stdout, stderr) => {
+        if (!err) {
+          resolve({ code: 0, stdout, stderr, failedToStart: false });
+          return;
+        }
+        const code = typeof err.code === "number" ? err.code : null;
+        resolve({
+          code: code ?? 127,
+          stdout: stdout ?? "",
+          stderr: stderr ?? String(err.message ?? ""),
+          failedToStart: code === null,
+        });
+      },
+    );
+    if (opts.input !== undefined) {
+      child.stdin?.end(opts.input);
+    }
+  });
+}
+
+/** stdout trimmed on success, `null` on any failure. */
+export async function runOk(cmd: string, args: string[], opts: RunOptions = {}): Promise<string | null> {
+  const r = await run(cmd, args, opts);
+  return r.code === 0 ? r.stdout.trim() : null;
+}
+
+/** stdout split into non-empty trimmed lines; `[]` on failure. */
+export async function runLines(cmd: string, args: string[], opts: RunOptions = {}): Promise<string[]> {
+  const out = await runOk(cmd, args, opts);
+  if (out === null || out === "") return [];
+  return out.split("\n").map((l) => l.trim()).filter((l) => l.length > 0);
+}
+
+const haveCache = new Map<string, boolean>();
+
+/** Whether an executable is on PATH. Cached for the life of the process. */
+export async function have(cmd: string): Promise<boolean> {
+  const cached = haveCache.get(cmd);
+  if (cached !== undefined) return cached;
+  const probe = process.platform === "win32" ? "where" : "which";
+  const r = await run(probe, [cmd], { timeoutMs: 5_000 });
+  const ok = r.code === 0 && r.stdout.trim().length > 0;
+  haveCache.set(cmd, ok);
+  return ok;
+}

package/src/util/log.ts

@@ -0,0 +1,88 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import type { LogLevel } from "../core/config.js";
+import { color } from "./color.js";
+import { redactSecrets, redactValue } from "./redact.js";
+import { formatClock } from "./time.js";
+
+const ORDER: Record<LogLevel, number> = { debug: 10, info: 20, warn: 30, error: 40 };
+
+export type LogFields = Record<string, unknown>;
+
+export interface LoggerOptions {
+  level?: LogLevel;
+  /** JSONL destination. Omit to log to the console only. */
+  file?: string;
+  /** Suppress console output (the log file still receives everything). */
+  quiet?: boolean;
+}
+
+export class Logger {
+  readonly level: LogLevel;
+  private readonly file: string | undefined;
+  private readonly quiet: boolean;
+  private fileBroken = false;
+
+  constructor(opts: LoggerOptions = {}) {
+    this.level = opts.level ?? "info";
+    this.file = opts.file;
+    this.quiet = opts.quiet ?? false;
+  }
+
+  debug(msg: string, fields?: LogFields): void {
+    this.emit("debug", msg, fields);
+  }
+  info(msg: string, fields?: LogFields): void {
+    this.emit("info", msg, fields);
+  }
+  warn(msg: string, fields?: LogFields): void {
+    this.emit("warn", msg, fields);
+  }
+  error(msg: string, fields?: LogFields): void {
+    this.emit("error", msg, fields);
+  }
+
+  /**
+   * A durable record of something treekeeper *did* (or decided not to do).
+   * Always written to the log file regardless of level, because this is the
+   * audit trail a developer reads after a worktree disappears.
+   */
+  event(type: string, fields: LogFields = {}): void {
+    this.write({ ts: new Date().toISOString(), level: "info", type, ...redactValue(fields) });
+  }
+
+  private emit(level: LogLevel, rawMsg: string, rawFields?: LogFields): void {
+    const msg = redactSecrets(rawMsg);
+    const fields = rawFields ? redactValue(rawFields) : undefined;
+    this.write({ ts: new Date().toISOString(), level, msg, ...(fields ?? {}) });
+    if (this.quiet || ORDER[level] < ORDER[this.level]) return;
+    const tag =
+      level === "error" ? color.red("error") :
+      level === "warn" ? color.yellow("warn") :
+      level === "debug" ? color.gray("debug") :
+      color.gray(formatClock(Date.now()));
+    const extra = fields && Object.keys(fields).length > 0 ? color.gray(` ${compact(fields)}`) : "";
+    // stderr, so that `--json` keeps stdout machine-readable.
+    process.stderr.write(`${tag} ${msg}${extra}\n`);
+  }
+
+  private write(record: LogFields): void {
+    if (!this.file || this.fileBroken) return;
+    try {
+      mkdirSync(dirname(this.file), { recursive: true });
+      appendFileSync(this.file, JSON.stringify(record) + "\n");
+    } catch {
+      // A broken log file must never take the daemon down; report once.
+      this.fileBroken = true;
+      if (!this.quiet) {
+        process.stderr.write(color.yellow(`warn could not write log file ${this.file}\n`));
+      }
+    }
+  }
+}
+
+function compact(fields: LogFields): string {
+  return Object.entries(fields)
+    .map(([k, v]) => `${k}=${typeof v === "string" ? v : JSON.stringify(v)}`)
+    .join(" ");
+}