@yoavsh/treekeeper 0.0.0-stage → 0.1.0

package/dist/util/log.js

@@ -0,0 +1,72 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { color } from "./color.js";
+import { redactSecrets, redactValue } from "./redact.js";
+import { formatClock } from "./time.js";
+const ORDER = { debug: 10, info: 20, warn: 30, error: 40 };
+export class Logger {
+    level;
+    file;
+    quiet;
+    fileBroken = false;
+    constructor(opts = {}) {
+        this.level = opts.level ?? "info";
+        this.file = opts.file;
+        this.quiet = opts.quiet ?? false;
+    }
+    debug(msg, fields) {
+        this.emit("debug", msg, fields);
+    }
+    info(msg, fields) {
+        this.emit("info", msg, fields);
+    }
+    warn(msg, fields) {
+        this.emit("warn", msg, fields);
+    }
+    error(msg, fields) {
+        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, fields = {}) {
+        this.write({ ts: new Date().toISOString(), level: "info", type, ...redactValue(fields) });
+    }
+    emit(level, rawMsg, rawFields) {
+        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`);
+    }
+    write(record) {
+        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) {
+    return Object.entries(fields)
+        .map(([k, v]) => `${k}=${typeof v === "string" ? v : JSON.stringify(v)}`)
+        .join(" ");
+}
+//# sourceMappingURL=log.js.map

package/dist/util/log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.js","sourceRoot":"","sources":["../../src/util/log.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAExC,MAAM,KAAK,GAA6B,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;AAYrF,MAAM,OAAO,MAAM;IACR,KAAK,CAAW;IACR,IAAI,CAAqB;IACzB,KAAK,CAAU;IACxB,UAAU,GAAG,KAAK,CAAC;IAE3B,YAAY,OAAsB,EAAE;QAClC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,MAAM,CAAC;QAClC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC;IACnC,CAAC;IAED,KAAK,CAAC,GAAW,EAAE,MAAkB;QACnC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;IAClC,CAAC;IACD,IAAI,CAAC,GAAW,EAAE,MAAkB;QAClC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;IACjC,CAAC;IACD,IAAI,CAAC,GAAW,EAAE,MAAkB;QAClC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;IACjC,CAAC;IACD,KAAK,CAAC,GAAW,EAAE,MAAkB;QACnC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;IAClC,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,IAAY,EAAE,SAAoB,EAAE;QACxC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC5F,CAAC;IAEO,IAAI,CAAC,KAAe,EAAE,MAAc,EAAE,SAAqB;QACjE,MAAM,GAAG,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;QAClC,MAAM,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC9D,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;QAC5E,IAAI,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO;QAC3D,MAAM,GAAG,GACP,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;YACxC,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;gBACzC,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;oBACzC,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACtC,MAAM,KAAK,GAAG,MAAM,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAChG,0DAA0D;QAC1D,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,GAAG,IAAI,GAAG,GAAG,KAAK,IAAI,CAAC,CAAC;IAClD,CAAC;IAEO,KAAK,CAAC,MAAiB;QAC7B,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,UAAU;YAAE,OAAO;QAC1C,IAAI,CAAC;YACH,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACnD,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC;QAC3D,CAAC;QAAC,MAAM,CAAC;YACP,kEAAkE;YAClE,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;YACvB,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;gBAChB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,iCAAiC,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC;YACrF,CAAC;QACH,CAAC;IACH,CAAC;CACF;AAED,SAAS,OAAO,CAAC,MAAiB;IAChC,OAAO,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;SAC1B,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;SACxE,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC"}

package/dist/util/paths.d.ts

@@ -0,0 +1,18 @@
+/** Expand a leading `~` and resolve to an absolute path. */
+export declare function expandPath(input: string, base?: string): string;
+/** Collapse `$HOME` back to `~` for display. */
+export declare function shortenPath(p: string): string;
+/** True when `child` is `parent` or lives underneath it. Pure string compare. */
+export declare function isInside(parent: string, child: string): boolean;
+/** realpath that falls back to the input when the path does not exist. */
+export declare function realpathSafe(p: string): Promise<string>;
+/** Where treekeeper keeps config, logs, cache and archives. */
+export declare function treekeeperHome(): string;
+/**
+ * Very small glob matcher: supports `*` (not crossing `/`), `**` (crossing it)
+ * and `?`. Enough for branch names and path patterns, and it keeps the
+ * dependency count at zero.
+ */
+export declare function matchGlob(pattern: string, value: string): boolean;
+export declare function matchAnyGlob(patterns: readonly string[], value: string): boolean;
+//# sourceMappingURL=paths.d.ts.map

package/dist/util/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/util/paths.ts"],"names":[],"mappings":"AAIA,4DAA4D;AAC5D,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,SAAgB,GAAG,MAAM,CAKtE;AAED,gDAAgD;AAChD,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAG7C;AAED,iFAAiF;AACjF,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAI/D;AAED,0EAA0E;AAC1E,wBAAsB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAM7D;AAED,+DAA+D;AAC/D,wBAAgB,cAAc,IAAI,MAAM,CAIvC;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAGjE;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAEhF"}

package/dist/util/paths.js

@@ -0,0 +1,87 @@
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve, sep } from "node:path";
+import { realpath } from "node:fs/promises";
+/** Expand a leading `~` and resolve to an absolute path. */
+export function expandPath(input, base = process.cwd()) {
+    let p = input.trim();
+    if (p === "~")
+        p = homedir();
+    else if (p.startsWith("~/") || p.startsWith(`~${sep}`))
+        p = join(homedir(), p.slice(2));
+    return isAbsolute(p) ? resolve(p) : resolve(base, p);
+}
+/** Collapse `$HOME` back to `~` for display. */
+export function shortenPath(p) {
+    const home = homedir();
+    return p === home || p.startsWith(home + sep) ? "~" + p.slice(home.length) : p;
+}
+/** True when `child` is `parent` or lives underneath it. Pure string compare. */
+export function isInside(parent, child) {
+    if (parent === child)
+        return true;
+    const base = parent.endsWith(sep) ? parent : parent + sep;
+    return child.startsWith(base);
+}
+/** realpath that falls back to the input when the path does not exist. */
+export async function realpathSafe(p) {
+    try {
+        return await realpath(p);
+    }
+    catch {
+        return p;
+    }
+}
+/** Where treekeeper keeps config, logs, cache and archives. */
+export function treekeeperHome() {
+    const override = process.env.TREEKEEPER_HOME;
+    if (override && override.trim() !== "")
+        return expandPath(override);
+    return join(homedir(), ".treekeeper");
+}
+/**
+ * Very small glob matcher: supports `*` (not crossing `/`), `**` (crossing it)
+ * and `?`. Enough for branch names and path patterns, and it keeps the
+ * dependency count at zero.
+ */
+export function matchGlob(pattern, value) {
+    const re = globToRegExp(pattern);
+    return re.test(value);
+}
+export function matchAnyGlob(patterns, value) {
+    return patterns.some((p) => matchGlob(p, value));
+}
+const cache = new Map();
+function globToRegExp(pattern) {
+    const hit = cache.get(pattern);
+    if (hit)
+        return hit;
+    let out = "^";
+    for (let i = 0; i < pattern.length; i += 1) {
+        const c = pattern[i];
+        if (c === "*") {
+            if (pattern[i + 1] === "*") {
+                i += 1;
+                if (pattern[i + 1] === "/")
+                    i += 1;
+                out += "(?:.*\\/)?";
+            }
+            else {
+                out += "[^/]*";
+            }
+        }
+        else if (c === "?") {
+            out += "[^/]";
+        }
+        else if ("\\^$.|+()[]{}".includes(c)) {
+            out += "\\" + c;
+        }
+        else {
+            out += c;
+        }
+    }
+    out += "$";
+    const re = new RegExp(out);
+    cache.set(pattern, re);
+    return re;
+}
+//# sourceMappingURL=paths.js.map

package/dist/util/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/util/paths.ts"],"names":[],"mappings":"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"}

package/dist/util/prompt.d.ts

@@ -0,0 +1,3 @@
+/** Ask a yes/no question. Returns `fallback` when stdin is not a TTY. */
+export declare function confirm(question: string, fallback?: boolean): Promise<boolean>;
+//# sourceMappingURL=prompt.d.ts.map

package/dist/util/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../src/util/prompt.ts"],"names":[],"mappings":"AAEA,yEAAyE;AACzE,wBAAsB,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,UAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CASlF"}

package/dist/util/prompt.js

@@ -0,0 +1,15 @@
+import { createInterface } from "node:readline/promises";
+/** Ask a yes/no question. Returns `fallback` when stdin is not a TTY. */
+export async function confirm(question, fallback = false) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        return fallback;
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = (await rl.question(`${question} [y/N] `)).trim().toLowerCase();
+        return answer === "y" || answer === "yes";
+    }
+    finally {
+        rl.close();
+    }
+}
+//# sourceMappingURL=prompt.js.map

package/dist/util/prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../src/util/prompt.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,yEAAyE;AACzE,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,QAAgB,EAAE,QAAQ,GAAG,KAAK;IAC9D,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK;QAAE,OAAO,QAAQ,CAAC;IACnE,MAAM,EAAE,GAAG,eAAe,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC7E,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,GAAG,QAAQ,SAAS,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC9E,OAAO,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,KAAK,CAAC;IAC5C,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,KAAK,EAAE,CAAC;IACb,CAAC;AACH,CAAC"}

package/dist/util/redact.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Credential scrubbing for anything that might reach a log file or stdout.
+ *
+ * Remotes routinely carry secrets — `https://user:ghp_xxx@github.com/o/r.git`
+ * is a perfectly ordinary origin URL — and git and gh echo them back in error
+ * messages. treekeeper writes a persistent log, so a token must never make it
+ * that far.
+ */
+/** `https://user:token@host/path` -> `https://host/path`. */
+export declare function redactRemote(url: string): string;
+/** Remove credentials from free text. */
+export declare function redactSecrets(text: string): string;
+/** Recursively redact strings in a value destined for a log record. */
+export declare function redactValue<T>(value: T): T;
+//# sourceMappingURL=redact.d.ts.map

package/dist/util/redact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../../src/util/redact.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,6DAA6D;AAC7D,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD;AAaD,yCAAyC;AACzC,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIlD;AAED,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAS1C"}

package/dist/util/redact.js

@@ -0,0 +1,44 @@
+/**
+ * Credential scrubbing for anything that might reach a log file or stdout.
+ *
+ * Remotes routinely carry secrets — `https://user:ghp_xxx@github.com/o/r.git`
+ * is a perfectly ordinary origin URL — and git and gh echo them back in error
+ * messages. treekeeper writes a persistent log, so a token must never make it
+ * that far.
+ */
+/** `https://user:token@host/path` -> `https://host/path`. */
+export function redactRemote(url) {
+    return url.replace(/^([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)[^@/]*@/, "$1");
+}
+const PATTERNS = [
+    // userinfo in any URL
+    [/([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)[^@/\s]*@/g, "$1"],
+    // well-known token shapes, even when they appear bare
+    [/\bgh[pousr]_[A-Za-z0-9]{16,}/g, "[redacted]"],
+    [/\bgithub_pat_[A-Za-z0-9_]{20,}/g, "[redacted]"],
+    [/\bglpat-[A-Za-z0-9_-]{16,}/g, "[redacted]"],
+    [/\b(?:xox[baprs]-)[A-Za-z0-9-]{10,}/g, "[redacted]"],
+    [/\bAKIA[0-9A-Z]{16}\b/g, "[redacted]"],
+];
+/** Remove credentials from free text. */
+export function redactSecrets(text) {
+    let out = text;
+    for (const [re, replacement] of PATTERNS)
+        out = out.replace(re, replacement);
+    return out;
+}
+/** Recursively redact strings in a value destined for a log record. */
+export function redactValue(value) {
+    if (typeof value === "string")
+        return redactSecrets(value);
+    if (Array.isArray(value))
+        return value.map((v) => redactValue(v));
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value))
+            out[k] = redactValue(v);
+        return out;
+    }
+    return value;
+}
+//# sourceMappingURL=redact.js.map

package/dist/util/redact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.js","sourceRoot":"","sources":["../../src/util/redact.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,6DAA6D;AAC7D,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,OAAO,GAAG,CAAC,OAAO,CAAC,wCAAwC,EAAE,IAAI,CAAC,CAAC;AACrE,CAAC;AAED,MAAM,QAAQ,GAA4B;IACxC,sBAAsB;IACtB,CAAC,0CAA0C,EAAE,IAAI,CAAC;IAClD,sDAAsD;IACtD,CAAC,+BAA+B,EAAE,YAAY,CAAC;IAC/C,CAAC,iCAAiC,EAAE,YAAY,CAAC;IACjD,CAAC,6BAA6B,EAAE,YAAY,CAAC;IAC7C,CAAC,qCAAqC,EAAE,YAAY,CAAC;IACrD,CAAC,uBAAuB,EAAE,YAAY,CAAC;CACxC,CAAC;AAEF,yCAAyC;AACzC,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,IAAI,GAAG,GAAG,IAAI,CAAC;IACf,KAAK,MAAM,CAAC,EAAE,EAAE,WAAW,CAAC,IAAI,QAAQ;QAAE,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,EAAE,EAAE,WAAW,CAAC,CAAC;IAC7E,OAAO,GAAG,CAAC;AACb,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,WAAW,CAAI,KAAQ;IACrC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,aAAa,CAAC,KAAK,CAAiB,CAAC;IAC3E,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,CAAiB,CAAC;IAClF,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,MAAM,GAAG,GAA4B,EAAE,CAAC;QACxC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,GAAG,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;QACpE,OAAO,GAAmB,CAAC;IAC7B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/util/time.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Parse a duration like "30m", "2h", "7d", "1h30m", "0" or a bare number of
+ * milliseconds. Throws on anything else so a typo in a config file is loud
+ * rather than silently becoming 0 (which would disable a safety gate).
+ */
+export declare function parseDuration(input: string | number): number;
+/** "3m", "2h 10m", "4d" — compact, at most two units. */
+export declare function formatDuration(ms: number): string;
+/** "12m ago" / "just now" */
+export declare function formatAgo(timestamp: number, now?: number): string;
+export declare function formatClock(timestamp: number): string;
+export declare function formatStamp(timestamp: number): string;
+//# sourceMappingURL=time.d.ts.map

package/dist/util/time.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time.d.ts","sourceRoot":"","sources":["../../src/util/time.ts"],"names":[],"mappings":"AASA;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAwB5D;AAED,yDAAyD;AACzD,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAWjD;AAED,6BAA6B;AAC7B,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,SAAa,GAAG,MAAM,CAIrE;AAED,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAIrD;AAED,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAOrD"}

package/dist/util/time.js

@@ -0,0 +1,77 @@
+const UNITS = {
+    ms: 1,
+    s: 1_000,
+    m: 60_000,
+    h: 3_600_000,
+    d: 86_400_000,
+    w: 604_800_000,
+};
+/**
+ * Parse a duration like "30m", "2h", "7d", "1h30m", "0" or a bare number of
+ * milliseconds. Throws on anything else so a typo in a config file is loud
+ * rather than silently becoming 0 (which would disable a safety gate).
+ */
+export function parseDuration(input) {
+    if (typeof input === "number") {
+        if (!Number.isFinite(input) || input < 0)
+            throw new Error(`invalid duration: ${input}`);
+        return Math.round(input);
+    }
+    const text = input.trim().toLowerCase();
+    if (text === "")
+        throw new Error("invalid duration: empty string");
+    if (/^\d+$/.test(text))
+        return Number(text);
+    const re = /(\d+(?:\.\d+)?)\s*(ms|s|m|h|d|w)/g;
+    let total = 0;
+    let matched = 0;
+    let consumed = 0;
+    for (const m of text.matchAll(re)) {
+        const [whole, value, unit] = m;
+        total += Number(value) * UNITS[unit];
+        matched += 1;
+        consumed += whole.length;
+    }
+    const stripped = text.replace(/[\s,]/g, "");
+    if (matched === 0 || consumed < stripped.length) {
+        throw new Error(`invalid duration: ${input} (use e.g. 30m, 2h, 7d)`);
+    }
+    return Math.round(total);
+}
+/** "3m", "2h 10m", "4d" — compact, at most two units. */
+export function formatDuration(ms) {
+    if (!Number.isFinite(ms) || ms < 0)
+        return "?";
+    if (ms < 1_000)
+        return `${Math.round(ms)}ms`;
+    const d = Math.floor(ms / UNITS.d);
+    const h = Math.floor((ms % UNITS.d) / UNITS.h);
+    const m = Math.floor((ms % UNITS.h) / UNITS.m);
+    const s = Math.floor((ms % UNITS.m) / UNITS.s);
+    if (d > 0)
+        return h > 0 ? `${d}d ${h}h` : `${d}d`;
+    if (h > 0)
+        return m > 0 ? `${h}h ${m}m` : `${h}h`;
+    if (m > 0)
+        return `${m}m`;
+    return `${s}s`;
+}
+/** "12m ago" / "just now" */
+export function formatAgo(timestamp, now = Date.now()) {
+    const delta = now - timestamp;
+    if (delta < 45_000)
+        return "just now";
+    return `${formatDuration(delta)} ago`;
+}
+export function formatClock(timestamp) {
+    const d = new Date(timestamp);
+    const pad = (n) => String(n).padStart(2, "0");
+    return `${pad(d.getHours())}:${pad(d.getMinutes())}`;
+}
+export function formatStamp(timestamp) {
+    const d = new Date(timestamp);
+    const pad = (n) => String(n).padStart(2, "0");
+    return (`${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}` +
+        `-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`);
+}
+//# sourceMappingURL=time.js.map

package/dist/util/time.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"time.js","sourceRoot":"","sources":["../../src/util/time.ts"],"names":[],"mappings":"AAAA,MAAM,KAAK,GAA2B;IACpC,EAAE,EAAE,CAAC;IACL,CAAC,EAAE,KAAK;IACR,CAAC,EAAE,MAAM;IACT,CAAC,EAAE,SAAS;IACZ,CAAC,EAAE,UAAU;IACb,CAAC,EAAE,WAAW;CACf,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,KAAsB;IAClD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,KAAK,EAAE,CAAC,CAAC;QACxF,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;IACD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACxC,IAAI,IAAI,KAAK,EAAE;QAAG,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACpE,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC;IAE5C,MAAM,EAAE,GAAG,mCAAmC,CAAC;IAC/C,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;QAClC,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;QAC/B,KAAK,IAAI,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,IAAc,CAAE,CAAC;QAChD,OAAO,IAAI,CAAC,CAAC;QACb,QAAQ,IAAI,KAAK,CAAC,MAAM,CAAC;IAC3B,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IAC5C,IAAI,OAAO,KAAK,CAAC,IAAI,QAAQ,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CAAC,qBAAqB,KAAK,yBAAyB,CAAC,CAAC;IACvE,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;AAC3B,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,cAAc,CAAC,EAAU;IACvC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC;IAC/C,IAAI,EAAE,GAAG,KAAK;QAAE,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC;IAC7C,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,KAAK,CAAC,CAAE,CAAC,CAAC;IACpC,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,CAAE,CAAC,GAAG,KAAK,CAAC,CAAE,CAAC,CAAC;IACjD,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,CAAE,CAAC,GAAG,KAAK,CAAC,CAAE,CAAC,CAAC;IACjD,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,CAAE,CAAC,GAAG,KAAK,CAAC,CAAE,CAAC,CAAC;IACjD,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;IAClD,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;IAClD,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC,GAAG,CAAC;IAC1B,OAAO,GAAG,CAAC,GAAG,CAAC;AACjB,CAAC;AAED,6BAA6B;AAC7B,MAAM,UAAU,SAAS,CAAC,SAAiB,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;IAC3D,MAAM,KAAK,GAAG,GAAG,GAAG,SAAS,CAAC;IAC9B,IAAI,KAAK,GAAG,MAAM;QAAE,OAAO,UAAU,CAAC;IACtC,OAAO,GAAG,cAAc,CAAC,KAAK,CAAC,MAAM,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,SAAiB;IAC3C,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC;IAC9B,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACtD,OAAO,GAAG,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,EAAE,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,SAAiB;IAC3C,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC;IAC9B,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACtD,OAAO,CACL,GAAG,CAAC,CAAC,WAAW,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE;QAC/D,IAAI,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,EAAE,CACpE,CAAC;AACJ,CAAC"}

package/docs/integrations.md

@@ -0,0 +1,128 @@
+# Integrating treekeeper with an agent harness
+
+treekeeper decides from state — git, your forge, and what the agents left on disk — not from harness callbacks. So the best integration is usually **no integration**:
+
+```bash
+treekeeper daemon install
+```
+
+That installs a launchd agent (macOS) or a systemd user timer (Linux) that sweeps every `interval`. It works for every harness at once, including ones you install next month.
+
+The snippets below are for when you want a sweep tied to a specific moment instead.
+
+## The command to run
+
+Whatever the harness, the hook body is the same:
+
+```bash
+npx -y @yoavsh/treekeeper gc --all --apply --yes --quiet
+```
+
+- `--yes` skips the confirmation prompt (hooks have no TTY)
+- `--quiet` prints only the summary line; the full record still goes to `~/.treekeeper/treekeeper.log`
+- exit code is 0 on success, 75 if another sweep holds the lock, 1 if something could not be archived
+
+Drop `--all` to limit the sweep to the repo the hook fired in.
+
+## Claude Code
+
+Add a `SessionEnd` hook to `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "SessionEnd": [
+      {
+        "hooks": [
+          { "type": "command", "command": "npx -y @yoavsh/treekeeper gc --all --apply --yes --quiet" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+treekeeper reads `~/.claude/projects/<slugified-cwd>/*.jsonl` to tell when a Claude Code session last touched a worktree, so a sweep triggered by one session will not remove a worktree another session is still using. Set `CLAUDE_CONFIG_DIR` if your config lives elsewhere.
+
+A slash command is often nicer than a hook, because you see the plan first. `~/.claude/commands/gc.md`:
+
+```markdown
+---
+description: Remove worktrees and branches whose work is already merged
+allowed-tools: Bash(treekeeper:*)
+---
+
+Run `treekeeper gc --all` and show me the plan. If it looks right, run it with `--apply --yes`.
+```
+
+## Codex CLI
+
+treekeeper detects Codex activity from `~/.codex/sessions/**/*.jsonl` (matching the recorded `cwd`). To sweep on a schedule instead, use the daemon. To sweep from a notify hook in `~/.codex/config.toml`:
+
+```toml
+notify = ["bash", "-lc", "npx -y @yoavsh/treekeeper gc --all --apply --yes --quiet"]
+```
+
+## Cursor / Windsurf / JetBrains agents
+
+These keep session state in editor-internal databases, so treekeeper relies on its generic detectors instead — the `process` detector (an agent working in a directory is a process whose cwd is that directory) and `mtime`. Both are on by default and need no setup; just run the daemon.
+
+## Aider
+
+`.aider.chat.history.md` inside the worktree is the activity signal, and it is on by default. For a sweep after each session, wrap your invocation:
+
+```bash
+aider "$@"; npx -y @yoavsh/treekeeper gc --apply --yes --quiet
+```
+
+## A harness treekeeper has never heard of
+
+Teach it the activity signal rather than wiring up a hook. Either point at a file whose mtime tracks the session:
+
+```json
+{
+  "sessions": {
+    "extraPaths": ["{worktree}/.myagent/session.log", "~/.myharness/state/{worktree}.json"]
+  }
+}
+```
+
+...or give it a command, where exit 0 means "an agent is still working here":
+
+```json
+{
+  "sessions": {
+    "commands": [
+      { "name": "myharness", "command": "pgrep -f \"myharness.*$TREEKEEPER_WORKTREE\" > /dev/null" }
+    ]
+  }
+}
+```
+
+`$TREEKEEPER_WORKTREE` is set to the worktree being considered.
+
+## Reading the plan from a script
+
+```bash
+treekeeper gc --all --json > plan.json
+
+jq '.summary' plan.json
+jq -r '.repos[].worktrees[] | select(.verdict.action == "reclaim") | "\(.path)\t\(.sizeKb)\t\(.verdict.reason)"' plan.json
+jq -r '.repos[].worktrees[] | select(.verdict.action == "keep") | "\(.path)\t\(.verdict.code)"' plan.json
+```
+
+Each worktree carries a `verdict` with a stable `code` (`merged-ancestor`, `unmerged`, `session-active`, `too-young`, `dirty`, `closed-pr-grace`, `protected-branch`, …), a human `reason`, and the `risks` that would need archiving. Script against `code`, show `reason` to people.
+
+With `--apply --json` you get `{ "plan": …, "result": … }`, where `result` lists what was removed, what was archived and what was skipped.
+
+## CI
+
+treekeeper is built for developer machines, where worktrees outlive their usefulness. In CI, where the checkout is thrown away anyway, it buys you nothing — except on a long-lived self-hosted runner, where a nightly job is reasonable:
+
+```yaml
+- run: npx -y @yoavsh/treekeeper gc --root "$RUNNER_WORKDIR" --apply --yes
+  env:
+    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+Set `archive.enabled: false` there if the runner has no business keeping archives.

package/docs/safety.md

@@ -0,0 +1,62 @@
+# What treekeeper will and will not delete
+
+treekeeper deletes directories and git branches without being asked, so the rules matter more than the features. They live in one pure function, [`src/core/decide.ts`](../src/core/decide.ts), with a truth table in [`test/decide.test.ts`](../test/decide.test.ts).
+
+## The invariant
+
+> A worktree is removed only when its commits are reachable from the default branch, or its pull request was merged or closed.
+
+Nothing overrides this. `--force` does not. If treekeeper cannot establish that the work landed — no ancestry, no PR data, `gh` missing, GitHub unreachable — the answer is *keep*. Being unable to tell is treated as "not finished", never as "no PR exists".
+
+## Never touched, under any flags
+
+- the repo's main worktree
+- the worktree containing your current directory
+- a worktree held by `git worktree lock`
+- a detached HEAD (no branch to reason about)
+- a branch matching `protectBranches` (`main`, `master`, `trunk`, `develop`, `dev`, `release/*` by default)
+- a path matching `protectPaths`
+- a repo with `{"enabled": false}` in its `.treekeeper.json`
+- the default branch, and any branch currently checked out somewhere
+
+## Held back until the coast is clear
+
+These are the gates `--force` bypasses, except where noted:
+
+| Gate | Default | `--force` |
+|---|---|---|
+| Agent session activity within `sessions.grace` | 20m | **still held** |
+| A process whose cwd is inside the worktree | — | **still held** |
+| Worktree touched within `minAge` | 30m | bypassed |
+| Uncommitted changes (`onDirty`) | archive, then remove | bypassed |
+| Merged PR with extra local commits (`onExtraCommits`) | keep | bypassed |
+| Closed-unmerged PR inside `closedPrGrace` (`onClosedPr`) | 7d hold, then archive | bypassed |
+
+A live session or a live process always wins. Everything else is a policy you can set.
+
+## Before every removal
+
+1. **Archive.** Commits not on the default branch become a `git bundle`; uncommitted changes become a `git diff HEAD --binary` patch; untracked non-ignored files become a tarball. Each archive has a `RESTORE.md` with the commands to undo it. If archiving fails, the worktree is kept.
+2. **Re-verify.** The plan is a snapshot, and a daemon may have built it minutes ago. Immediately before removal treekeeper re-checks that the directory still exists, the branch and HEAD have not moved, the worktree is not newly locked, and no uncommitted changes appeared. Anything that moved is left for the next sweep.
+3. **Remove with git.** `git worktree remove`, never a blind `rm -rf`, so git's own bookkeeping stays correct. `--force` is used only after a successful archive.
+4. **Log.** A JSON line per removal in `~/.treekeeper/treekeeper.log`: path, branch, size, reason, risks, archive location.
+
+## Concurrency
+
+Multiple agents and multiple sessions share a machine, so:
+
+- a lock file (`~/.treekeeper/sweep.lock`) allows one sweep at a time; a second exits with code 75 rather than racing
+- a stale lock from a killed process is detected by pid liveness and cleared
+- the `process` detector means a worktree another session is actively sitting in is never a candidate, even if its branch is merged
+
+## Credentials
+
+Remotes with embedded tokens (`https://user:ghp_…@github.com/o/r.git`) are common, and `git` and `gh` echo them in error messages. treekeeper scrubs credentials at the logging chokepoint, so no token reaches the log file, the PR cache or stdout. See [`src/util/redact.ts`](../src/util/redact.ts).
+
+## Branches
+
+Deleting a branch only drops a pointer, but it can still orphan commits, so the same rules apply: unmerged branches are never deleted, and a closed-PR branch is bundled before it goes. A branch still checked out in a worktree treekeeper decided to keep is kept with it.
+
+## Reporting a problem
+
+If treekeeper removed something it should not have, the archive directory and `~/.treekeeper/treekeeper.log` together say exactly what happened and why. Both are worth attaching to an issue.