resumecontext 0.1.0

package/dist/daemon.js

@@ -0,0 +1,409 @@
+/**
+ * The auto-sync background work, and the machinery that keeps it scheduled.
+ * Once a project finishes agent configuration, the CLI registers it here
+ * and makes sure the OS is scheduled to run it; from then on, syncing that
+ * project happens on its own every DAEMON_INTERVAL_MS without the user ever
+ * running `resumecontext sync` again.
+ *
+ * "Making sure it's scheduled" means registering a real, OS-managed
+ * mechanism -- launchd StartInterval on macOS, a systemd --user timer on
+ * Linux, see daemonService.ts -- so this survives a reboot and keeps firing
+ * even if a given run crashes. There is deliberately no fallback to a plain
+ * detached subprocess: a background process a `kill` or a reboot silently
+ * ends for good, with nothing to notice or revive it, is not what
+ * "auto-sync" is supposed to mean. On a platform with neither mechanism,
+ * ensureDaemonRunning does nothing and auto-sync simply isn't available
+ * there -- `resumecontext sync` still works manually.
+ *
+ * Each tick is its own short-lived process, not one long-running loop.
+ * Earlier this ran as a single persistent process (launchd RunAtLoad +
+ * KeepAlive supervising an in-process `while (true)` loop) on the theory
+ * that starting a fresh Node process every 5 seconds costs more than a
+ * resident one sleeping between ticks. That's true, but it traded away
+ * something more important: in production, one tick hit an unrelated bug
+ * (a stack-overflow deep in a local-history parser) and the process was
+ * observed pinned at sustained high CPU minutes later, with nothing further
+ * ever logged -- one bad tick took down every tick after it, silently,
+ * until someone happened to notice. A supervisor restarts a process that
+ * *exits*; it does nothing for one that's merely stuck. A fresh process per
+ * tick is self-healing from exactly that failure mode: a hung or crashed
+ * tick wastes at most one interval, and the next scheduled tick runs
+ * unaffected in a clean process.
+ *
+ * Because ticks are now separate processes, TWO ticks can be scheduled
+ * before the first finishes (a slow scan, a hung tick that hasn't been
+ * cleaned up yet) -- see acquireLock below for how that's prevented.
+ *
+ * A second project finishing setup while auto-sync is already scheduled
+ * does NOT need a second registration: registerProject just adds an entry
+ * to a shared JSON file that every tick re-reads at the top, so it picks
+ * up the new project on its own within one interval -- see runDaemonTick
+ * below.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { agentConfigFile, daemonRegistryFile, daemonLogFile, daemonLockFile, daemonFingerprintCacheFile, syncStateFile, } from "./paths.js";
+import { apiErrorStatus } from "./apiClient.js";
+import { readAgentConfig } from "./agentConfig.js";
+import { readCredentials } from "./session.js";
+import { scanForNewTurns, pushNewTurns } from "./syncCore.js";
+import { MAX_LOG_BYTES } from "./constants.js";
+import { installPersistentService } from "./daemonService.js";
+import { fingerprintDirsForConfig } from "./localHistory/registry.js";
+import { findProjectRoot } from "./projectRoot.js";
+export function readRegistry() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(daemonRegistryFile(), "utf-8"));
+        if (parsed && typeof parsed.projects === "object")
+            return parsed;
+    }
+    catch {
+        // missing or unparseable -- fall through to empty
+    }
+    return { projects: {} };
+}
+function writeRegistry(registry) {
+    const file = daemonRegistryFile();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(registry, null, 2));
+}
+/** Adds (or updates) one project in the shared registry. Idempotent --
+ * calling this for a project that's already registered just rewrites the
+ * same entry, so every command that touches a project's agent config can
+ * call it unconditionally rather than tracking "did I already register
+ * this." */
+export function registerProject(projectId, root) {
+    const registry = readRegistry();
+    registry.projects[projectId] = { root };
+    writeRegistry(registry);
+}
+/** Removes one project from the registry and deletes its per-project local
+ * files -- the counterpart to registerProject, called when a project is
+ * confirmed gone (a 404 from the cloud API, meaning the project id no longer
+ * exists there at all, whether it was deleted through this CLI or the web
+ * UI). Idempotent. A project id is a UUID that's never reused, so once
+ * confirmed gone there's no future scenario where keeping its agent config
+ * or sync-state helps; deleting them here, not just the registry entry, is
+ * what keeps ~/.resumecontext/agents and ~/.resumecontext/sync-state from
+ * silently accumulating one dead file per deleted project forever. Does not
+ * touch `.resumecontext.json` or anything else. */
+export function deregisterProject(projectId) {
+    const registry = readRegistry();
+    if (!(projectId in registry.projects))
+        return;
+    delete registry.projects[projectId];
+    writeRegistry(registry);
+    fs.rmSync(agentConfigFile(projectId), { force: true });
+    fs.rmSync(syncStateFile(projectId), { force: true });
+}
+// ---- lifecycle: making sure auto-sync is scheduled with the OS --------
+/** Registers auto-sync as a real OS-managed schedule if this platform
+ * supports one (see daemonService.ts) -- no fallback of any kind on a
+ * platform with neither launchd nor systemd, so what's registered is
+ * always something the OS itself keeps firing after a crash or a reboot,
+ * never a subprocess someone can just `kill`.
+ *
+ * Idempotent: safe to call from every command that touches a project's
+ * agent config, not just the first time. Returns which platform mechanism
+ * applies (or "unsupported") and whether this call actually installed
+ * anything, so callers can tell the user when auto-sync isn't available
+ * here at all.
+ *
+ * `installService` is injectable so tests can verify what would be
+ * installed -- which mechanism, which plan -- without ever registering a
+ * real OS service. */
+export function ensureDaemonRunning(installService = installPersistentService) {
+    return installService();
+}
+// ---- log rotation -------------------------------------------------------
+/** Keeps daemonLogFile() bounded, retaining one previous generation.
+ *
+ * Truncates in place rather than renaming: launchd (StandardOutPath) and
+ * systemd (StandardOutput=append:) open this file themselves per-run and
+ * would recreate it anyway, but truncating keeps this correct even if a
+ * platform ever held the descriptor open across runs. Called at the start
+ * of every tick, not just some of them, since ticks no longer share a
+ * process to schedule it from.
+ *
+ * `fsImpl` is injectable so tests can drive the size logic without a real
+ * log file, matching the pattern used in daemonService.ts. */
+export function rotateLogIfNeeded(fsImpl = fs, logPath = daemonLogFile(), maxBytes = MAX_LOG_BYTES) {
+    let size;
+    try {
+        size = fsImpl.statSync(logPath).size;
+    }
+    catch {
+        return false; // no log yet -- nothing to rotate
+    }
+    if (size <= maxBytes)
+        return false;
+    fsImpl.copyFileSync(logPath, `${logPath}.1`);
+    fsImpl.truncateSync(logPath, 0);
+    return true;
+}
+/** True if a process with this pid exists and we have permission to signal
+ * it -- signal 0 sends nothing, it only probes. Throws ESRCH ("no such
+ * process") for a dead pid, EPERM for one that exists but isn't ours;
+ * EPERM still means "alive", just not signalable, so only ESRCH (and any
+ * other throw, conservatively) counts as dead. */
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+/** Tries to take the lock for this tick. Returns false (meaning: skip this
+ * run entirely) when another tick already holds it AND that tick's process
+ * is still alive. A lock file left behind by a process that's no longer
+ * running (killed -9, machine slept mid-write, an old crash) is stale and
+ * self-heals here rather than wedging auto-sync forever -- there is no
+ * "unsupported platform" fallback for locking the way there is for
+ * scheduling, since flock-equivalent primitives (exclusive file create,
+ * process.kill(pid, 0)) are POSIX and both platforms we support have them.
+ *
+ * `fsImpl`/`pid` are injectable so tests can exercise every branch (fresh
+ * lock, live holder, stale holder) without real processes or a real lock
+ * file. */
+export function acquireLock(fsImpl = fs, pid = process.pid, lockPath = daemonLockFile()) {
+    fsImpl.mkdirSync(path.dirname(lockPath), { recursive: true });
+    try {
+        fsImpl.writeFileSync(lockPath, String(pid), { flag: "wx" }); // atomic create-exclusive
+        return true;
+    }
+    catch (err) {
+        if (err.code !== "EEXIST")
+            throw err;
+    }
+    const holderPid = Number(fsImpl.readFileSync(lockPath, "utf8"));
+    if (Number.isInteger(holderPid) && isProcessAlive(holderPid))
+        return false;
+    // Stale: the holder is gone. Take over -- best-effort against another
+    // tick racing to do the same thing at the exact same moment, which is
+    // rare enough (two ticks, both finding the SAME stale lock, within the
+    // gap between the read above and this write) not to guard further; the
+    // worst case is two ticks briefly overlapping once, not corruption.
+    fsImpl.writeFileSync(lockPath, String(pid));
+    return true;
+}
+/** Releases the lock, but only if it's still ours -- guards against
+ * releasing a lock a different process has since taken over (the stale
+ * takeover race noted in acquireLock above). */
+export function releaseLock(fsImpl = fs, pid = process.pid, lockPath = daemonLockFile()) {
+    try {
+        const holderPid = Number(fsImpl.readFileSync(lockPath, "utf8"));
+        if (holderPid === pid)
+            fsImpl.rmSync(lockPath, { force: true });
+    }
+    catch {
+        // already gone, or unreadable -- nothing more to do
+    }
+}
+// ---- change detection -----------------------------------------------------
+/** SQLite's WAL-mode sidecar files -- `<db>-shm` (shared memory index) and
+ * `<db>-wal` (write-ahead log). Excluded from the fingerprint below: opening
+ * a WAL-mode database AT ALL, even with `readOnly: true`, touches -shm's
+ * mtime as an inherent part of SQLite establishing a consistent read
+ * snapshot -- verified directly against a real Cursor store.db (its -shm
+ * mtime advanced on every read-only open; -journal is rollback-mode's
+ * equivalent, same idea). Cursor's own history is exactly this shape (see
+ * cursor.ts), which without this exclusion turned the fingerprint gate into
+ * a self-defeating loop: scanning to check for real changes touched these
+ * files, which changed the next tick's fingerprint, which triggered another
+ * full scan, forever -- a ~73MB Cursor history measured at a genuinely
+ * unchanging multi-second cost on EVERY tick, not just when something
+ * actually changed. Fixing this here, not in cursor.ts's read path, keeps
+ * that path free to keep reading live/current data -- the alternative
+ * (SQLite's `immutable=1` connection mode) would avoid the mtime side
+ * effect but does so by promising SQLite the file won't change during the
+ * read, which is false while Cursor itself might be actively appending. */
+function isFingerprintNoise(filename) {
+    return filename.endsWith("-shm") || filename.endsWith("-wal") || filename.endsWith("-journal");
+}
+/** A cheap fingerprint of everything under `dirs`: newest mtime, total
+ * size, and file count.
+ *
+ * This exists because a full scan is expensive and almost always finds
+ * nothing. collectLocalTurns parses every session file of every project on
+ * the machine and only then filters down to the one project being synced
+ * -- on a 73MB history that measured 442ms of CPU and a 410MB allocation
+ * spike, repeated on every tick regardless of interval, to usually
+ * discover nothing changed. Stat'ing the tree first turns the common case
+ * into a handful of syscalls.
+ *
+ * Size and count are folded in alongside mtime deliberately: mtime has
+ * millisecond granularity, so an append landing in the same millisecond as
+ * our stat would otherwise be invisible until the next unrelated write. */
+export function fingerprintDirs(dirs) {
+    let newest = 0;
+    let totalSize = 0;
+    let fileCount = 0;
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return; // unreadable or deleted -- treat as contributing nothing
+        }
+        for (const entry of entries) {
+            if (isFingerprintNoise(entry.name))
+                continue;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+                continue;
+            }
+            try {
+                const st = fs.statSync(full);
+                newest = Math.max(newest, st.mtimeMs);
+                totalSize += st.size;
+                fileCount += 1;
+            }
+            catch {
+                // vanished between readdir and stat -- ignore
+            }
+        }
+    };
+    for (const dir of dirs)
+        walk(dir);
+    return `${newest}:${totalSize}:${fileCount}`;
+}
+function readFingerprintCache() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(daemonFingerprintCacheFile(), "utf-8"));
+        if (parsed && typeof parsed === "object")
+            return parsed;
+    }
+    catch {
+        // missing or unparseable -- fall through to empty, same as readRegistry
+    }
+    return {};
+}
+function writeFingerprintCache(cache) {
+    const file = daemonFingerprintCacheFile();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(cache, null, 2));
+}
+// ---- the tick itself: only ever run inside a scheduled daemon process ----
+function log(message) {
+    console.log(`[${new Date().toISOString()}] ${message}`);
+}
+export async function tick(cloudApi, localCapture) {
+    const creds = readCredentials();
+    if (!creds)
+        return; // logged out -- nothing to sync until logged back in
+    const fingerprintCache = readFingerprintCache();
+    let fingerprintCacheChanged = false;
+    for (const [projectId, { root: registeredRoot }] of Object.entries(readRegistry().projects)) {
+        try {
+            // The registry remembers where this project was last explicitly set up,
+            // but the marker remains the source of truth. This lets a marker moved
+            // to a parent directory heal itself on the next tick, while a deleted
+            // or replaced marker affects only this one project.
+            const resolved = findProjectRoot(registeredRoot);
+            if (!resolved.projectId) {
+                log(`${projectId}: no .resumecontext.json found at ${registeredRoot} or its parents -- skipped`);
+                continue;
+            }
+            if (resolved.projectId !== projectId) {
+                log(`${projectId}: .resumecontext.json at ${resolved.root} belongs to ${resolved.projectId} -- skipped`);
+                continue;
+            }
+            const root = resolved.root;
+            if (path.resolve(root) !== path.resolve(registeredRoot)) {
+                registerProject(projectId, root);
+                // The configured agent paths can resolve differently under the new
+                // root (notably Cursor), so force one scan instead of trusting a
+                // fingerprint produced for the old location.
+                delete fingerprintCache[projectId];
+                fingerprintCacheChanged = true;
+                log(`${projectId}: project marker moved to ${root} -- updated registration`);
+            }
+            const agentConfig = readAgentConfig(projectId);
+            if (!agentConfig)
+                continue; // agent setup never finished for this one
+            // Skip the expensive scan entirely when nothing on disk has moved.
+            // A config with no directories at all is left ungated on purpose: its
+            // fingerprint would be a constant carrying no information, and there
+            // is nothing to scan in that case anyway, so gating buys nothing and
+            // would only obscure why the scan was skipped.
+            const dirs = fingerprintDirsForConfig(root, agentConfig);
+            const fingerprint = dirs.length > 0 ? fingerprintDirs(dirs) : null;
+            if (fingerprint !== null && fingerprintCache[projectId] === fingerprint)
+                continue;
+            const { newTurns } = await scanForNewTurns(localCapture, root, agentConfig, projectId);
+            if (newTurns.length > 0) {
+                const { accepted } = await pushNewTurns(cloudApi, creds.token, projectId, newTurns);
+                log(`${projectId}: pushed ${accepted} new turn(s)`);
+            }
+            // Only recorded once the work above fully succeeded -- a push that
+            // throws must leave the cached fingerprint unchanged so the next
+            // tick retries rather than treating the failure as "handled".
+            if (fingerprint !== null) {
+                fingerprintCache[projectId] = fingerprint;
+                fingerprintCacheChanged = true;
+            }
+        }
+        catch (err) {
+            if (apiErrorStatus(err) === 404) {
+                deregisterProject(projectId);
+                log(`${projectId}: project no longer exists (deleted) -- stopped syncing it`);
+            }
+            else {
+                // One project's failure (network hiccup, revoked access, a deleted
+                // directory) must never stop this tick from covering the rest, or
+                // from trying this project again next tick.
+                log(`${projectId}: sync failed -- ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    if (fingerprintCacheChanged)
+        writeFingerprintCache(fingerprintCache);
+}
+/** The entire body of one daemon tick (see the hidden `__daemon-run`
+ * command in index.ts) -- runs the shared per-project tick() once and
+ * returns, letting the OS scheduler (launchd StartInterval / a systemd
+ * timer, see daemonService.ts) be the thing that calls this again in
+ * DAEMON_INTERVAL_MS. See this file's module doc comment for why a fresh
+ * process per tick, rather than one persistent process looping forever,
+ * is the design here.
+ *
+ * Takes the lock first and does nothing else at all if it can't get it --
+ * see acquireLock's doc comment. That's the expected, silent outcome when
+ * the previous tick is still running (a slow scan) or hasn't been cleaned
+ * up yet, and deliberately NOT logged: at DAEMON_INTERVAL_MS this is common
+ * enough (a slightly slow scan on one tick pushes the next one into an
+ * overlap) that logging it every time would itself be the noise problem
+ * this function's start/finish lines exist to avoid.
+ *
+ * Explicit "tick started"/"tick finished" lines bracket every real run --
+ * without them, a hung tick (the exact failure mode this whole per-tick-
+ * process design exists to survive, see the module doc comment) looks
+ * IDENTICAL in the log to a healthy one that simply hasn't logged a push
+ * yet: both show nothing after the last line. A start with no matching
+ * finish is the signal that this particular tick never came back, which a
+ * bare list of push/failure lines can't tell you on its own. The elapsed
+ * time on the finish line is the same debugging value: a normal tick
+ * finishes in well under a second; a tick that took 90 seconds to report
+ * "finished" already tells you where to look before you go near `ps`. */
+export async function runDaemonTick(cloudApi, localCapture) {
+    if (!acquireLock())
+        return;
+    rotateLogIfNeeded();
+    const startedAt = Date.now();
+    log("tick started");
+    try {
+        await tick(cloudApi, localCapture);
+        log(`tick finished (${Date.now() - startedAt}ms)`);
+    }
+    catch (err) {
+        log(`tick finished (${Date.now() - startedAt}ms) -- unexpected error: ${err instanceof Error ? err.message : String(err)}`);
+        throw err;
+    }
+    finally {
+        releaseLock();
+    }
+}