harnery 0.46.0 → 0.47.0

package/dist/core/autoupdate/engine.js

@@ -0,0 +1,548 @@
+/**
+ * Project self-update engine (ADR 0229).
+ *
+ * `autoUpdateTick` is the hot path every prompt, session start, and host CLI
+ * command calls: one stat of the throttle stamp when nothing is due. When the
+ * stamp is stale it claims the stamp and launches a detached
+ * `<harn> autoupdate run --background`, which decides with `checkForUpdate`
+ * and, only when needed, runs the host's configured steps under a lock.
+ */
+import { spawn, spawnSync } from "node:child_process";
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readSync, renameSync, statSync, utimesSync, writeFileSync, } from "node:fs";
+import { dirname, extname, resolve, win32 } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readAutoUpdateConfig, resolveBinName } from "../config.js";
+import { fingerprint } from "./fingerprint.js";
+import { changedFiles, contains, defaultGitRunner, head, lsRemote, upstream, } from "./git.js";
+import { acquireRunLock, addNotice, autoUpdateDir, autoUpdateLogPath, autoUpdateStampPath, inspectLock, mutateAutoUpdateState, readAutoUpdateState, } from "./state.js";
+import { AUTOUPDATE_DEFAULTS, AUTOUPDATE_FILES, EXIT_NEEDS_PERSON, NOTICE_PREFIX, } from "./types.js";
+/** Set on the detached runner and every step so nested CLI calls never tick. */
+export const AUTOUPDATE_CHILD_ENV = "HARNERY_AUTOUPDATE_CHILD";
+const MINUTE_MS = 60_000;
+const DAY_MS = AUTOUPDATE_DEFAULTS.dailyHours * 60 * MINUTE_MS;
+const LOG_ROTATE_BYTES = 256 * 1024;
+const LOG_KEEP_BYTES = 64 * 1024;
+const CLEANUP_TIMEOUT_MS = 5 * MINUTE_MS;
+const KILL_GRACE_MS = 5_000;
+function resolveDeps(deps) {
+    return {
+        now: deps.now ?? Date.now,
+        env: deps.env ?? process.env,
+        readConfig: deps.readConfig ?? readAutoUpdateConfig,
+        git: deps.git ?? defaultGitRunner,
+    };
+}
+// ------------------------------------------------------------------ helpers
+/** The CLI entry the detached runner executes with `process.execPath`. */
+export function harnCliEntry() {
+    const ext = extname(fileURLToPath(import.meta.url)) || ".js";
+    const entry = fileURLToPath(new URL(`../../cli${ext}`, import.meta.url));
+    if (existsSync(entry))
+        return entry;
+    return fileURLToPath(new URL("../../../bin/harn.mjs", import.meta.url));
+}
+/** Set the throttle stamp's mtime (creating it), which is all the tick reads. */
+export function setStamp(coordRoot, atMs) {
+    const path = autoUpdateStampPath(coordRoot);
+    if (!existsSync(path)) {
+        mkdirSync(autoUpdateDir(coordRoot), { recursive: true });
+        writeFileSync(path, "");
+    }
+    const at = atMs / 1000;
+    utimesSync(path, at, at);
+}
+function stampMtime(coordRoot) {
+    try {
+        return statSync(autoUpdateStampPath(coordRoot)).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+/** Keep the log bounded: past 256 KB, keep only its last 64 KB. */
+export function rotateLog(path) {
+    let size;
+    try {
+        size = statSync(path).size;
+    }
+    catch {
+        return;
+    }
+    if (size <= LOG_ROTATE_BYTES)
+        return;
+    const fd = openSync(path, "r");
+    const buffer = Buffer.alloc(LOG_KEEP_BYTES);
+    try {
+        readSync(fd, buffer, 0, LOG_KEEP_BYTES, size - LOG_KEEP_BYTES);
+    }
+    finally {
+        closeSync(fd);
+    }
+    const tmp = `${path}.rotating`;
+    writeFileSync(tmp, buffer);
+    renameSync(tmp, path);
+}
+function appendLog(coordRoot, text) {
+    try {
+        const path = autoUpdateLogPath(coordRoot);
+        mkdirSync(dirname(path), { recursive: true });
+        appendFileSync(path, text);
+    }
+    catch {
+        // Logging is best effort.
+    }
+}
+function logLine(coordRoot, now, line) {
+    appendLog(coordRoot, `${new Date(now).toISOString()} ${line}\n`);
+}
+function isChild(env) {
+    return env[AUTOUPDATE_CHILD_ENV] === "1";
+}
+function dailyDue(cfg, state, now) {
+    if (cfg.dailySteps.length === 0)
+        return false;
+    if (!state.dailyAt)
+        return true;
+    const at = Date.parse(state.dailyAt);
+    return !Number.isFinite(at) || now - at >= DAY_MS;
+}
+function short(sha) {
+    return sha ? sha.slice(0, 7) : "unknown";
+}
+const INSTRUCTION_PREFIXES = [".agents/", ".claude/skills/", ".claude/rules/", ".cursor/rules/"];
+const HOOK_PATHS = new Set([
+    ".claude/settings.json",
+    ".codex/hooks.json",
+    ".codex/config.toml",
+    ".cursor/hooks.json",
+]);
+export function isInstructionPath(path) {
+    const normalized = path.replace(/\\/g, "/");
+    const base = normalized.slice(normalized.lastIndexOf("/") + 1);
+    if (base === "AGENTS.md" || base === "CLAUDE.md" || base === "SKILL.md")
+        return true;
+    if (base.endsWith(".mdc"))
+        return true;
+    return INSTRUCTION_PREFIXES.some((prefix) => normalized.startsWith(prefix));
+}
+export function isHookConfigPath(path) {
+    return HOOK_PATHS.has(path.replace(/\\/g, "/"));
+}
+/** `harnery-notice:` lines in step output. */
+export function parseNoticeLines(output) {
+    const texts = [];
+    for (const raw of output.split(/\r?\n/)) {
+        const line = raw.trimStart();
+        if (!line.startsWith(NOTICE_PREFIX))
+            continue;
+        const text = line.slice(NOTICE_PREFIX.length).trim();
+        if (text)
+            texts.push(text);
+    }
+    return texts;
+}
+// ------------------------------------------------------------------ tick
+function defaultSpawnRunner(coordRoot) {
+    const root = resolve(coordRoot);
+    const logPath = autoUpdateLogPath(root);
+    mkdirSync(dirname(logPath), { recursive: true });
+    rotateLog(logPath);
+    const fd = openSync(logPath, "a");
+    try {
+        const child = spawn(process.execPath, [harnCliEntry(), "autoupdate", "run", "--background"], {
+            cwd: root,
+            detached: true,
+            windowsHide: true,
+            stdio: ["ignore", fd, fd],
+            env: {
+                ...process.env,
+                [AUTOUPDATE_CHILD_ENV]: "1",
+                HARNERY_COORD_ROOT_OVERRIDE: root,
+            },
+        });
+        child.once("error", () => {
+            logLine(root, Date.now(), "runner could not start");
+        });
+        child.unref();
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * Activity hook. Never throws. When throttled it reads the config and stats
+ * one file; it runs no Git and parses no state.
+ */
+export function autoUpdateTick(coordRoot, deps = {}) {
+    try {
+        const d = resolveDeps(deps);
+        if (isChild(d.env))
+            return { action: "disabled", detail: "inside an auto-update run" };
+        const cfg = d.readConfig(coordRoot);
+        if (!cfg?.enabled)
+            return { action: "disabled" };
+        const now = d.now();
+        const mtime = stampMtime(coordRoot);
+        if (mtime !== null && now - mtime < cfg.checkMinutes * MINUTE_MS) {
+            return { action: "throttled" };
+        }
+        const lock = inspectLock(coordRoot, cfg, now);
+        if (lock.held && !lock.stale) {
+            return { action: "locked", detail: lock.owner ? `pid ${lock.owner.pid}` : undefined };
+        }
+        // Claim before launching so concurrent ticks see a fresh stamp.
+        setStamp(coordRoot, now);
+        (deps.spawnRunner ?? defaultSpawnRunner)(coordRoot);
+        return { action: "launched" };
+    }
+    catch (err) {
+        return { action: "error", detail: err?.message ?? String(err) };
+    }
+}
+// ------------------------------------------------------------------ check
+export function checkForUpdate(coordRoot, cfg, state, deps = {}) {
+    const d = resolveDeps(deps);
+    const now = d.now();
+    const root = resolve(coordRoot);
+    const fp = fingerprint(cfg.watch, root, d.env);
+    const currentHead = head(root, d.git);
+    const base = {
+        head: currentHead,
+        upstream: null,
+        remoteSha: null,
+        fingerprint: fp,
+        dailyOnly: false,
+    };
+    if (deps.force)
+        return { ...base, needed: true, reason: "forced" };
+    const drift = !state.converged || state.converged.fingerprint !== fp;
+    const up = upstream(root, d.git);
+    if (!up) {
+        return drift
+            ? { ...base, needed: true, reason: "drift", detail: "watched paths changed" }
+            : { ...base, needed: false, reason: "no-upstream" };
+    }
+    const withUp = { ...base, upstream: up.display };
+    const remoteSha = lsRemote(root, up.remote, up.branch, d.git);
+    if (!remoteSha) {
+        return { ...withUp, needed: false, reason: "offline", detail: `could not reach ${up.remote}` };
+    }
+    const withRemote = { ...withUp, remoteSha };
+    if (!contains(root, remoteSha, d.git)) {
+        return {
+            ...withRemote,
+            needed: true,
+            reason: "behind",
+            detail: `${up.display} at ${short(remoteSha)}`,
+        };
+    }
+    if (drift)
+        return { ...withRemote, needed: true, reason: "drift", detail: "watched paths changed" };
+    const last = state.lastRun;
+    if (last?.outcome === "failed") {
+        const finished = Date.parse(last.finishedAt);
+        if (!Number.isFinite(finished) ||
+            now - finished >= AUTOUPDATE_DEFAULTS.failureBackoffMinutes * MINUTE_MS) {
+            return { ...withRemote, needed: true, reason: "retry" };
+        }
+    }
+    if (dailyDue(cfg, state, now)) {
+        return { ...withRemote, needed: true, reason: "daily", dailyOnly: true };
+    }
+    return { ...withRemote, needed: false, reason: "current" };
+}
+// ------------------------------------------------------------------ run
+/**
+ * Resolve a step's argv for the current platform. On Windows a bare command
+ * name such as `bun` or `git` is looked up on PATH with PATHEXT, because
+ * spawning without a shell does not try `.cmd` shims; a `.cmd` or `.bat`
+ * match runs through `cmd.exe`. Elsewhere the argv is used as is.
+ */
+export function resolveStepCommand(cmd, args, env, platform = process.platform, exists = existsSync) {
+    if (platform !== "win32" || /[\\/]/.test(cmd) || extname(cmd) !== "") {
+        return { cmd, args, verbatim: false };
+    }
+    const pathVar = env.Path ?? env.PATH ?? "";
+    const exts = (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean);
+    for (const dir of pathVar.split(";").filter(Boolean)) {
+        for (const ext of exts) {
+            const candidate = win32.join(dir, cmd + ext.toLowerCase());
+            if (!exists(candidate))
+                continue;
+            if (/^\.(cmd|bat)$/i.test(ext)) {
+                const quote = (s) => (/[\s"&|<>^]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s);
+                const line = [candidate, ...args].map(quote).join(" ");
+                return {
+                    cmd: env.ComSpec ?? "cmd.exe",
+                    args: ["/d", "/s", "/c", `"${line}"`],
+                    verbatim: true,
+                };
+            }
+            return { cmd: candidate, args, verbatim: false };
+        }
+    }
+    return { cmd, args, verbatim: false };
+}
+export const defaultStepRunner = (argv, opts) => new Promise((resolveRun) => {
+    const started = Date.now();
+    let output = "";
+    let timedOut = false;
+    let settled = false;
+    const finish = (exitCode) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        resolveRun({ exitCode, timedOut, output, ms: Date.now() - started });
+    };
+    const [rawCmd, ...rawArgs] = argv;
+    if (!rawCmd) {
+        finish(null);
+        return;
+    }
+    const { cmd, args, verbatim } = resolveStepCommand(rawCmd, rawArgs, opts.env ?? process.env);
+    const child = spawn(cmd, args, {
+        cwd: opts.cwd,
+        env: opts.env,
+        windowsHide: true,
+        windowsVerbatimArguments: verbatim,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    const onData = (stream) => (data) => {
+        const chunk = data.toString("utf8");
+        output += chunk;
+        opts.onChunk?.(chunk, stream);
+    };
+    child.stdout?.on("data", onData("stdout"));
+    child.stderr?.on("data", onData("stderr"));
+    const timer = setTimeout(() => {
+        timedOut = true;
+        child.kill("SIGTERM");
+        setTimeout(() => {
+            if (!settled)
+                child.kill("SIGKILL");
+        }, KILL_GRACE_MS).unref();
+    }, opts.timeoutMs);
+    child.once("error", (err) => {
+        output += `${err.message}\n`;
+        finish(null);
+    });
+    child.once("exit", (code) => {
+        // A grandchild that keeps the pipes open must not hold the run.
+        setTimeout(() => finish(timedOut ? null : code), 2_000).unref();
+    });
+    child.once("close", (code) => finish(timedOut ? null : code));
+});
+function defaultCleanup(coordRoot) {
+    spawnSync(process.execPath, [harnCliEntry(), "artifacts", "clean", "--yes"], {
+        cwd: coordRoot,
+        env: { ...process.env, [AUTOUPDATE_CHILD_ENV]: "1", HARNERY_COORD_ROOT_OVERRIDE: coordRoot },
+        stdio: "ignore",
+        timeout: CLEANUP_TIMEOUT_MS,
+        windowsHide: true,
+    });
+}
+export async function runAutoUpdate(coordRootRaw, opts = {}) {
+    const deps = opts.deps ?? {};
+    const d = resolveDeps(deps);
+    const root = resolve(coordRootRaw);
+    const cfg = d.readConfig(root);
+    if (!cfg || (!cfg.enabled && !opts.force)) {
+        return { outcome: "current", decision: null, record: null, notices: [] };
+    }
+    const startedMs = d.now();
+    const lock = acquireRunLock(root, cfg, startedMs);
+    if (!lock.acquired) {
+        return {
+            outcome: "skipped-locked",
+            decision: null,
+            record: null,
+            notices: [],
+            lockOwner: lock.owner,
+        };
+    }
+    const binName = deps.binName ?? resolveBinName(root);
+    const runStep = deps.runStep ?? defaultStepRunner;
+    const stepEnv = { ...d.env, [AUTOUPDATE_CHILD_ENV]: "1" };
+    const pending = [];
+    const steps = [];
+    const startedAt = new Date(startedMs).toISOString();
+    let decision = null;
+    let outcome = "current";
+    let fromHead = null;
+    let toHead = null;
+    let error;
+    let convergedUpdate;
+    let dailyAt;
+    let backoff = false;
+    const say = (line) => {
+        logLine(root, d.now(), line);
+        opts.onOutput?.(`${line}\n`, "stderr");
+    };
+    // Returns "ok" | "blocked" | "failed".
+    const runPhase = async (list, label) => {
+        for (const argv of list) {
+            const shown = argv.join(" ");
+            say(`${label} start: ${shown}`);
+            const result = await runStep(argv, {
+                cwd: root,
+                timeoutMs: cfg.timeoutMinutes * MINUTE_MS,
+                env: stepEnv,
+                onChunk: (chunk, stream) => {
+                    appendLog(root, chunk);
+                    opts.onOutput?.(chunk, stream);
+                },
+            });
+            steps.push({
+                argv,
+                exitCode: result.exitCode,
+                ms: result.ms,
+                ...(result.timedOut ? { timedOut: true } : {}),
+            });
+            const needsPerson = result.exitCode === EXIT_NEEDS_PERSON;
+            for (const text of parseNoticeLines(result.output)) {
+                pending.push({ kind: needsPerson ? "person" : "info", text });
+            }
+            say(`${label} exit ${result.exitCode ?? "none"}${result.timedOut ? " (timed out)" : ""} in ${result.ms}ms: ${shown}`);
+            if (needsPerson)
+                return "blocked";
+            if (result.exitCode !== 0) {
+                const how = result.timedOut
+                    ? `timed out after ${cfg.timeoutMinutes} min`
+                    : `exit ${result.exitCode ?? "none"}`;
+                pending.push({
+                    kind: "failure",
+                    text: `Auto-update step \`${shown}\` failed (${how}); see .harnery/logs/${AUTOUPDATE_FILES.log} or run \`${binName} autoupdate run\`.`,
+                });
+                return "failed";
+            }
+        }
+        return "ok";
+    };
+    try {
+        const state = readAutoUpdateState(root);
+        decision = checkForUpdate(root, cfg, state, { ...deps, force: opts.force });
+        fromHead = decision.head;
+        toHead = decision.head;
+        say(`check: ${decision.reason}${decision.detail ? ` (${decision.detail})` : ""}`);
+        if (!decision.needed) {
+            outcome = decision.reason === "offline" ? "offline" : "current";
+        }
+        else {
+            let phase = "ok";
+            if (!decision.dailyOnly)
+                phase = await runPhase(cfg.steps, "step");
+            if (phase === "ok") {
+                toHead = head(root, d.git);
+                if (fromHead && toHead && fromHead !== toHead) {
+                    const changed = changedFiles(root, fromHead, toHead, d.git);
+                    const moved = `This checkout updated ${short(fromHead)}→${short(toHead)}.`;
+                    if (changed.some(isInstructionPath)) {
+                        pending.push({
+                            kind: "instructions",
+                            text: `${moved} Re-read AGENTS.md and any skill you are using before continuing.`,
+                        });
+                    }
+                    if (changed.some(isHookConfigPath)) {
+                        pending.push({
+                            kind: "hooks",
+                            text: `${moved} Hook settings changed; start a new session so they load.`,
+                        });
+                    }
+                }
+                convergedUpdate = {
+                    head: toHead ?? "",
+                    remoteSha: decision.remoteSha,
+                    fingerprint: fingerprint(cfg.watch, root, d.env),
+                    at: new Date(d.now()).toISOString(),
+                };
+                if (dailyDue(cfg, state, d.now())) {
+                    const daily = await runPhase(cfg.dailySteps, "daily");
+                    if (daily !== "failed")
+                        dailyAt = new Date(d.now()).toISOString();
+                    phase = daily;
+                }
+            }
+            outcome =
+                phase === "blocked"
+                    ? "blocked"
+                    : phase === "failed"
+                        ? "failed"
+                        : decision.dailyOnly
+                            ? "current"
+                            : "updated";
+            backoff = phase === "failed";
+        }
+    }
+    catch (err) {
+        outcome = "failed";
+        backoff = true;
+        error = err?.message ?? String(err);
+        say(`error: ${error}`);
+    }
+    const notices = [];
+    const finishedMs = d.now();
+    const record = {
+        startedAt,
+        finishedAt: new Date(finishedMs).toISOString(),
+        outcome,
+        reason: decision?.reason ?? "forced",
+        fromHead,
+        toHead,
+        steps,
+        ...(error ? { error } : {}),
+    };
+    let cleanupAt;
+    try {
+        const priorState = readAutoUpdateState(root);
+        const lastCleanup = priorState.cleanupAt ? Date.parse(priorState.cleanupAt) : Number.NaN;
+        const cleanupDue = cfg.cleanup &&
+            (outcome === "updated" || outcome === "current") &&
+            (!Number.isFinite(lastCleanup) || finishedMs - lastCleanup >= DAY_MS);
+        if (cleanupDue) {
+            try {
+                (deps.runCleanup ?? defaultCleanup)(root);
+            }
+            catch {
+                // Cleanup is best effort.
+            }
+            cleanupAt = new Date(d.now()).toISOString();
+        }
+        mutateAutoUpdateState(root, (s) => {
+            s.lastRun = record;
+            if (convergedUpdate)
+                s.converged = convergedUpdate;
+            if (dailyAt)
+                s.dailyAt = dailyAt;
+            if (cleanupAt)
+                s.cleanupAt = cleanupAt;
+            // A run that succeeded resolves earlier failures and person requests,
+            // so sessions that start later are not told about a fixed problem.
+            if (outcome === "updated" || outcome === "current") {
+                s.notices = s.notices.filter((n) => n.kind !== "failure" && n.kind !== "person");
+            }
+            for (const n of pending)
+                notices.push(addNotice(s, n.kind, n.text, finishedMs));
+        });
+        // A failed run pushes the stamp forward so the tick stays one stat while backing off.
+        const backoffMs = AUTOUPDATE_DEFAULTS.failureBackoffMinutes * MINUTE_MS;
+        setStamp(root, backoff ? finishedMs + backoffMs - cfg.checkMinutes * MINUTE_MS : finishedMs);
+        say(`run ${outcome} (${record.reason})`);
+    }
+    finally {
+        lock.release();
+    }
+    return { outcome, decision, record, notices };
+}
+export function autoUpdateStatus(coordRootRaw, deps = {}) {
+    const d = resolveDeps(deps);
+    const root = resolve(coordRootRaw);
+    const config = d.readConfig(root);
+    const now = d.now();
+    const mtime = stampMtime(root);
+    const stampAge = mtime === null ? null : now - mtime;
+    const checkMs = (config?.checkMinutes ?? AUTOUPDATE_DEFAULTS.checkMinutes) * MINUTE_MS;
+    const nextCheckMs = stampAge === null ? 0 : Math.max(0, checkMs - stampAge);
+    const locked = inspectLock(root, config ?? { timeoutMinutes: AUTOUPDATE_DEFAULTS.timeoutMinutes, steps: [], dailySteps: [] }, now);
+    return { config, state: readAutoUpdateState(root), stampAge, nextCheckMs, locked };
+}

package/dist/core/autoupdate/fingerprint.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Fingerprint of the watched paths outside Git. A change in any watched
+ * file's mtime or size, or in a watched directory's direct children, changes
+ * the fingerprint and forces an update run (`drift`).
+ */
+/**
+ * Expand `~/` (or a bare `~`) and `$VAR` / `${VAR}`. Returns null when a
+ * referenced variable is unset, so the entry fingerprints as missing instead
+ * of resolving somewhere unintended.
+ */
+export declare function expandWatchPath(entry: string, projectRoot: string, env?: NodeJS.ProcessEnv): string | null;
+/** The raw lines behind the fingerprint (sorted), for diagnostics and tests. */
+export declare function fingerprintLines(watch: readonly string[], projectRoot: string, env?: NodeJS.ProcessEnv): string[];
+/** sha1 hex of the sorted fingerprint lines. */
+export declare function fingerprint(watch: readonly string[], projectRoot: string, env?: NodeJS.ProcessEnv): string;
+//# sourceMappingURL=fingerprint.d.ts.map

package/dist/core/autoupdate/fingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.d.ts","sourceRoot":"","sources":["../../../src/core/autoupdate/fingerprint.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,GAAG,IAAI,CAmBf;AAWD,gFAAgF;AAChF,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,WAAW,EAAE,MAAM,EACnB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,EAAE,CAsBV;AAED,gDAAgD;AAChD,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,WAAW,EAAE,MAAM,EACnB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAIR"}

package/dist/core/autoupdate/fingerprint.js

@@ -0,0 +1,73 @@
+/**
+ * Fingerprint of the watched paths outside Git. A change in any watched
+ * file's mtime or size, or in a watched directory's direct children, changes
+ * the fingerprint and forces an update run (`drift`).
+ */
+import { createHash } from "node:crypto";
+import { readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+/**
+ * Expand `~/` (or a bare `~`) and `$VAR` / `${VAR}`. Returns null when a
+ * referenced variable is unset, so the entry fingerprints as missing instead
+ * of resolving somewhere unintended.
+ */
+export function expandWatchPath(entry, projectRoot, env = process.env) {
+    let unset = false;
+    let out = entry.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g, (_m, a, b) => {
+        const value = env[(a ?? b)];
+        if (value === undefined || value === "") {
+            unset = true;
+            return "";
+        }
+        return value;
+    });
+    if (unset)
+        return null;
+    if (out === "~" || out.startsWith("~/") || out.startsWith("~\\")) {
+        const home = env.HOME || env.USERPROFILE || homedir();
+        out = join(home, out.slice(1));
+    }
+    return isAbsolute(out) ? resolve(out) : resolve(projectRoot, out);
+}
+function statLine(path) {
+    try {
+        const st = statSync(path);
+        return `${st.isDirectory() ? "dir" : "file"}\t${Math.trunc(st.mtimeMs)}\t${st.isDirectory() ? 0 : st.size}`;
+    }
+    catch {
+        return null;
+    }
+}
+/** The raw lines behind the fingerprint (sorted), for diagnostics and tests. */
+export function fingerprintLines(watch, projectRoot, env = process.env) {
+    const lines = [];
+    for (const entry of watch) {
+        const path = expandWatchPath(entry, projectRoot, env);
+        const self = path ? statLine(path) : null;
+        if (!path || !self) {
+            lines.push(`${entry}\tmissing`);
+            continue;
+        }
+        lines.push(`${entry}\t${self}`);
+        if (!self.startsWith("dir\t"))
+            continue;
+        let children = [];
+        try {
+            children = readdirSync(path);
+        }
+        catch {
+            children = [];
+        }
+        for (const child of children) {
+            lines.push(`${entry}/${child}\t${statLine(join(path, child)) ?? "missing"}`);
+        }
+    }
+    return lines.sort();
+}
+/** sha1 hex of the sorted fingerprint lines. */
+export function fingerprint(watch, projectRoot, env = process.env) {
+    return createHash("sha1")
+        .update(fingerprintLines(watch, projectRoot, env).join("\n"))
+        .digest("hex");
+}

package/dist/core/autoupdate/git.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The few Git reads self-update needs. Every call is synchronous, bounded by a
+ * timeout, and goes through an injectable runner so tests never touch a
+ * network remote.
+ */
+export interface GitResult {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+}
+export type GitRunner = (args: string[], opts: {
+    cwd: string;
+    timeoutMs: number;
+}) => GitResult;
+export declare const defaultGitRunner: GitRunner;
+export declare function head(root: string, run?: GitRunner): string | null;
+export interface Upstream {
+    remote: string;
+    branch: string;
+    /** e.g. `origin/main`. */
+    display: string;
+}
+/** The current branch's upstream, or null when detached or untracked. */
+export declare function upstream(root: string, run?: GitRunner): Upstream | null;
+/** The remote branch's sha, or null when the remote cannot be reached or lacks the branch. */
+export declare function lsRemote(root: string, remote: string, branch: string, run?: GitRunner): string | null;
+/** True when `sha` exists locally and is an ancestor of HEAD. */
+export declare function contains(root: string, sha: string, run?: GitRunner): boolean;
+export declare function changedFiles(root: string, from: string, to: string, run?: GitRunner): string[];
+//# sourceMappingURL=git.d.ts.map

package/dist/core/autoupdate/git.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../../../src/core/autoupdate/git.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,KAAK,SAAS,CAAC;AAKhG,eAAO,MAAM,gBAAgB,EAAE,SAc9B,CAAC;AAcF,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,SAA4B,GAAG,MAAM,GAAG,IAAI,CAEnF;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,yEAAyE;AACzE,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,SAA4B,GAAG,QAAQ,GAAG,IAAI,CAczF;AAED,8FAA8F;AAC9F,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,GAAG,GAAE,SAA4B,GAChC,MAAM,GAAG,IAAI,CAUf;AAED,iEAAiE;AACjE,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,SAA4B,GAAG,OAAO,CAW9F;AAED,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,GAAG,GAAE,SAA4B,GAChC,MAAM,EAAE,CAOV"}