@cstart/coldstart 2.0.0

package/dist/daemon-lock.js

@@ -0,0 +1,218 @@
+import { readFile, writeFile, mkdir, unlink, open, readdir } from 'node:fs/promises';
+import { readFileSync, watch, existsSync } from 'node:fs';
+import { join, resolve, basename, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+export function daemonDir() {
+    return join(homedir(), '.coldstart', 'daemon');
+}
+export function rootHash(rootDir) {
+    return createHash('sha256').update(resolve(rootDir)).digest('hex').slice(0, 16);
+}
+export function lockBasename(rootDir) {
+    const abs = resolve(rootDir);
+    return `${basename(abs)}-${rootHash(abs)}`;
+}
+function lockPath(rootDir) {
+    return join(daemonDir(), `${lockBasename(rootDir)}.json`);
+}
+function spawnLockPath(rootDir) {
+    return join(daemonDir(), `${lockBasename(rootDir)}.spawn`);
+}
+export function daemonLogPath(rootDir) {
+    return join(daemonDir(), `${lockBasename(rootDir)}.log`);
+}
+export function daemonLogPrevPath(rootDir) {
+    return join(daemonDir(), `${lockBasename(rootDir)}.log.prev`);
+}
+export async function readLock(rootDir) {
+    try {
+        const raw = await readFile(lockPath(rootDir), 'utf-8');
+        const lock = JSON.parse(raw);
+        if (typeof lock.pid !== 'number')
+            return null;
+        return lock;
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeLock(rootDir, pid, version) {
+    await mkdir(daemonDir(), { recursive: true });
+    const payload = { pid, rootDir: resolve(rootDir), version };
+    await writeFile(lockPath(rootDir), JSON.stringify(payload));
+}
+export async function deleteLock(rootDir) {
+    try {
+        await unlink(lockPath(rootDir));
+    }
+    catch { /* ignore */ }
+}
+export async function listDaemonLocks() {
+    let entries;
+    try {
+        entries = await readdir(daemonDir());
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of entries) {
+        if (!name.endsWith('.json'))
+            continue;
+        const full = join(daemonDir(), name);
+        try {
+            const raw = await readFile(full, 'utf-8');
+            const parsed = JSON.parse(raw);
+            if (typeof parsed.pid !== 'number')
+                continue;
+            out.push({
+                basename: name.replace(/\.json$/, ''),
+                lockPath: full,
+                lock: parsed,
+            });
+        }
+        catch { /* skip malformed */ }
+    }
+    return out;
+}
+export function isDaemonAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get the current version of coldstart-mcp from package.json.
+ */
+export function getCurrentVersion() {
+    try {
+        const __filename = fileURLToPath(import.meta.url);
+        const pkgPath = resolve(dirname(__filename), '..', 'package.json');
+        const content = readFileSync(pkgPath, 'utf-8');
+        const pkg = JSON.parse(content);
+        return pkg.version ?? 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * Kill a daemon by PID with escalating signals: SIGTERM (5s wait), then SIGKILL.
+ * Returns true if the daemon was alive and has been killed; false if already dead.
+ */
+export async function killDaemon(pid) {
+    if (!isDaemonAlive(pid))
+        return false;
+    try {
+        process.kill(pid, 'SIGTERM');
+    }
+    catch {
+        return false;
+    }
+    // Wait up to 5 seconds for graceful shutdown
+    const deadline = Date.now() + 5000;
+    while (Date.now() < deadline) {
+        if (!isDaemonAlive(pid))
+            return true;
+        await new Promise(r => setTimeout(r, 100));
+    }
+    // SIGKILL if still alive
+    try {
+        process.kill(pid, 'SIGKILL');
+    }
+    catch {
+        // Already dead or permission denied — either way, treat as killed
+    }
+    return true;
+}
+/**
+ * Try to atomically acquire a spawn lock so only one reader spawns the keeper.
+ * Returns a release function if acquired, null if another process already holds it.
+ */
+export async function tryAcquireSpawnLock(rootDir) {
+    await mkdir(daemonDir(), { recursive: true });
+    const path = spawnLockPath(rootDir);
+    try {
+        const fd = await open(path, 'wx'); // O_CREAT | O_EXCL — atomic
+        await fd.writeFile(String(process.pid));
+        await fd.close();
+        return async () => { try {
+            await unlink(path);
+        }
+        catch { /* ignore */ } };
+    }
+    catch {
+        return null; // Another reader already holds the spawn lock
+    }
+}
+/**
+ * Fix #6: Watch the daemon lockfile directory for deletions of our own lockfile.
+ * If our lockfile is deleted (e.g., user ran `rm ~/.coldstart/daemon/foo.json`),
+ * call onMissing() so the daemon can exit cleanly.
+ *
+ * fs.watch drops events under load (observed live: a keeper surviving its
+ * lockfile deletion, then coexisting with its replacement — two keepers
+ * racing saves on one root). Two hardenings:
+ *   - a slow poll backstop, so a missed event only delays shutdown
+ *   - lock OWNERSHIP: if the lockfile exists but names a different pid,
+ *     another keeper has taken over this root — the old one must exit.
+ *
+ * Returns a function to stop watching.
+ */
+export const LOCK_POLL_INTERVAL_MS = 30_000;
+export function watchOwnLockfile(rootDir, onMissing, pollIntervalMs = LOCK_POLL_INTERVAL_MS) {
+    const lock = lockPath(rootDir);
+    const parent = daemonDir();
+    let debounceTimer = null;
+    let watcher = null;
+    let fired = false;
+    const lockLost = () => {
+        if (!existsSync(lock))
+            return true;
+        try {
+            const parsed = JSON.parse(readFileSync(lock, 'utf-8'));
+            return typeof parsed.pid === 'number' && parsed.pid !== process.pid;
+        }
+        catch {
+            return false; // unreadable mid-write — never shut down on a read race
+        }
+    };
+    const fire = () => {
+        if (fired)
+            return;
+        fired = true;
+        onMissing();
+    };
+    const poll = setInterval(() => { if (lockLost())
+        fire(); }, pollIntervalMs);
+    poll.unref();
+    try {
+        watcher = watch(parent, (_eventType, _filename) => {
+            if (debounceTimer)
+                clearTimeout(debounceTimer);
+            debounceTimer = setTimeout(() => {
+                debounceTimer = null;
+                if (lockLost())
+                    fire();
+            }, 200);
+        });
+    }
+    catch (err) {
+        // Keep the poll backstop even when fs.watch is unavailable.
+        return () => {
+            clearInterval(poll);
+        };
+    }
+    return () => {
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        clearInterval(poll);
+        watcher?.close();
+    };
+}
+//# sourceMappingURL=daemon-lock.js.map

package/dist/daemon-lock.js.map

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

package/dist/daemon-log.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Per-daemon log file lives next to the daemon lockfile at
+ * `~/.coldstart/daemon/<basename>-<hash>.log`. On rotation the previous
+ * contents move to `<basename>-<hash>.log.prev` so the most recent crash
+ * is always preserved.
+ *
+ * Sizing rationale: a daemon emits ~5 KB of startup output on a normal
+ * repo and is near-silent in steady state. 1 MB comfortably holds a full
+ * workday of patch events plus an occasional error storm without thrashing
+ * disk, and worst-case per project is 2 MB across .log + .log.prev.
+ */
+export declare const MAX_LOG_BYTES: number;
+/**
+ * Attach a file-backed logger for the running daemon process.
+ *
+ * - Rotates any existing `.log` to `.log.prev` before opening a fresh file,
+ *   so the new daemon run starts with a clean log and the previous run's
+ *   output (likely containing the crash, if any) is preserved.
+ * - Overrides `process.stderr.write` so all existing `log()` call sites
+ *   automatically land in the file — no caller changes needed.
+ * - Starts a 60 s timer that rotates the file when it crosses 1 MB.
+ *
+ * Returns a teardown function for graceful shutdown.
+ */
+export declare function attachDaemonLogger(rootDir: string): () => void;
+//# sourceMappingURL=daemon-log.d.ts.map

package/dist/daemon-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon-log.d.ts","sourceRoot":"","sources":["../src/daemon-log.ts"],"names":[],"mappings":"AAWA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,QAAkB,CAAC;AAqB7C;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,IAAI,CAyD9D"}

package/dist/daemon-log.js

@@ -0,0 +1,110 @@
+import { createWriteStream, existsSync, mkdirSync, renameSync, statSync, } from 'node:fs';
+import { dirname } from 'node:path';
+import { daemonLogPath, daemonLogPrevPath } from './daemon-lock.js';
+/**
+ * Per-daemon log file lives next to the daemon lockfile at
+ * `~/.coldstart/daemon/<basename>-<hash>.log`. On rotation the previous
+ * contents move to `<basename>-<hash>.log.prev` so the most recent crash
+ * is always preserved.
+ *
+ * Sizing rationale: a daemon emits ~5 KB of startup output on a normal
+ * repo and is near-silent in steady state. 1 MB comfortably holds a full
+ * workday of patch events plus an occasional error storm without thrashing
+ * disk, and worst-case per project is 2 MB across .log + .log.prev.
+ */
+export const MAX_LOG_BYTES = 1 * 1024 * 1024;
+const ROTATE_CHECK_INTERVAL_MS = 60 * 1000;
+let currentStream = null;
+let currentPath = null;
+let prevPath = null;
+let rotateTimer = null;
+let originalStderrWrite = null;
+/**
+ * Atomically rotate `<root>.log` to `<root>.log.prev`. Best-effort —
+ * rotation must never crash the daemon, so all errors are swallowed.
+ */
+function rotateNow(logPath, prevTarget) {
+    try {
+        if (existsSync(logPath)) {
+            try {
+                renameSync(logPath, prevTarget);
+            }
+            catch { /* ignore */ }
+        }
+    }
+    catch { /* ignore */ }
+}
+/**
+ * Attach a file-backed logger for the running daemon process.
+ *
+ * - Rotates any existing `.log` to `.log.prev` before opening a fresh file,
+ *   so the new daemon run starts with a clean log and the previous run's
+ *   output (likely containing the crash, if any) is preserved.
+ * - Overrides `process.stderr.write` so all existing `log()` call sites
+ *   automatically land in the file — no caller changes needed.
+ * - Starts a 60 s timer that rotates the file when it crosses 1 MB.
+ *
+ * Returns a teardown function for graceful shutdown.
+ */
+export function attachDaemonLogger(rootDir) {
+    const logPath = daemonLogPath(rootDir);
+    const prevTarget = daemonLogPrevPath(rootDir);
+    try {
+        mkdirSync(dirname(logPath), { recursive: true });
+    }
+    catch { /* directory may already exist */ }
+    rotateNow(logPath, prevTarget);
+    currentStream = createWriteStream(logPath, { flags: 'a' });
+    currentPath = logPath;
+    prevPath = prevTarget;
+    originalStderrWrite = process.stderr.write.bind(process.stderr);
+    // Route every process.stderr.write through the log file. Cast through
+    // unknown because Node's Writable.write has three overloaded signatures.
+    process.stderr.write =
+        (chunk, ...rest) => {
+            const stream = currentStream;
+            if (!stream)
+                return originalStderrWrite(chunk, ...rest);
+            return stream.write(chunk, ...rest);
+        };
+    rotateTimer = setInterval(() => {
+        try {
+            if (!currentPath || !prevPath)
+                return;
+            if (!existsSync(currentPath))
+                return;
+            const size = statSync(currentPath).size;
+            if (size <= MAX_LOG_BYTES)
+                return;
+            const oldStream = currentStream;
+            currentStream = null;
+            if (oldStream)
+                oldStream.end();
+            rotateNow(currentPath, prevPath);
+            currentStream = createWriteStream(currentPath, { flags: 'a' });
+        }
+        catch {
+            // Rotation is best-effort — never crash the daemon over a log roll.
+        }
+    }, ROTATE_CHECK_INTERVAL_MS);
+    // Don't keep the daemon alive solely because of the rotation timer.
+    rotateTimer.unref();
+    return () => {
+        if (rotateTimer) {
+            clearInterval(rotateTimer);
+            rotateTimer = null;
+        }
+        const stream = currentStream;
+        currentStream = null;
+        currentPath = null;
+        prevPath = null;
+        if (stream)
+            stream.end();
+        if (originalStderrWrite) {
+            process.stderr.write =
+                originalStderrWrite;
+            originalStderrWrite = null;
+        }
+    };
+}
+//# sourceMappingURL=daemon-log.js.map

package/dist/daemon-log.js.map

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

package/dist/index-manager.d.ts

@@ -0,0 +1,103 @@
+import type { CodebaseIndex } from './types.js';
+export type RebuildFn = () => Promise<CodebaseIndex>;
+export interface IndexContext {
+    index: CodebaseIndex;
+    /** True while a full rebuild is running. Tool calls served from previous snapshot. */
+    isRebuilding: boolean;
+}
+/**
+ * Owns the live in-memory index and orchestrates incremental patches vs full rebuilds.
+ *
+ * Decision logic (fires on each debounced batch from the file watcher):
+ *   - batch.size === 0        → no-op
+ *   - batch.size <= 30        → incremental patch (serial, ~2-5ms per file)
+ *   - batch.size > 30         → full rebuild in background, serve stale index until complete
+ *   - patch throws            → fallback to full rebuild
+ *
+ * Changes that arrive WHILE a rebuild is running are collected into a pending set.
+ * After the rebuild completes, the pending set is processed as a new batch so no
+ * changes are silently dropped.
+ *
+ * Tool calls always read `getContext().index` which is the last stable snapshot.
+ * Index swaps are atomic (single JS assignment).
+ */
+export declare class IndexManager {
+    private readonly rebuild;
+    private readonly cacheDir;
+    private readonly noCache;
+    private readonly quiet;
+    private activeIndex;
+    private rebuilding;
+    private stopWatcherFn;
+    private stopCacheWatcherFn;
+    private pendingCacheSave;
+    /**
+     * Paths that changed while a rebuild was in progress.
+     * Processed as a follow-up batch once the rebuild completes.
+     */
+    private pendingDuringRebuild;
+    constructor(initialIndex: CodebaseIndex, rebuild: RebuildFn, cacheDir: string | undefined, noCache: boolean, quiet: boolean);
+    /** Returns the current index snapshot and rebuild status for tool calls. */
+    getContext(): IndexContext;
+    /** Start watching the project root for file changes. */
+    startWatching(): void;
+    /** Stop watching (called on process exit). */
+    stopWatching(): void;
+    private log;
+    /**
+     * Notebook `.raw` logs changed (an agent wrote a note, or a git merge
+     * unioned two logs) — re-fold and re-render the derived md for those ids.
+     * Never touches the code index; md here is a browsability nicety (search
+     * folds from `.raw` directly), so failures only log.
+     */
+    private handleNotebookRawBatch;
+    /**
+     * Rebuild the keeper-maintained KB notes index (per-anchor symbol
+     * inventories + absence verdict stamps) from the live code index, and
+     * persist it beside the cache. Single-flight: a refresh landing while one
+     * runs is coalesced into one follow-up pass, so stamps never go stale
+     * silently. kb readers only ever READ this file (C1 decoupling).
+     */
+    private refreshingKb;
+    private kbRefreshQueued;
+    private refreshKbNotesIndex;
+    private handleBatch;
+    /** Best-effort observability writers (skipped under --no-cache). Stamps are
+     *  serialized through one promise chain: updateKeeperState is read-merge-
+     *  write, so two in-flight stamps would silently drop each other's fields. */
+    private stampChain;
+    private stamp;
+    private report;
+    private triggerRebuild;
+    /**
+     * A failed rebuild leaves the keeper serving a stale snapshot with no
+     * guarantee another change event ever arrives — retry on a timer, backing
+     * off, and give up (until the next real change) after a few attempts.
+     */
+    private rebuildFailures;
+    private rebuildRetryTimer;
+    private scheduleRebuildRetry;
+    /**
+     * Sampled fingerprint audit — after each cache save, stat a rotating window
+     * of indexed files against their parse-time fingerprints. Catches changes
+     * the watcher missed (dropped fs events, edits in paths fs.watch didn't
+     * cover); drifted files are re-fed through the normal patch path.
+     */
+    private auditCursor;
+    private auditFingerprints;
+    /** Debounced cache write — avoids hammering disk on rapid successive patches. */
+    private savingCache;
+    private scheduleCacheSave;
+    /**
+     * Fix #2: Watch the cache directory for manual deletes (e.g., user runs
+     * `rm -rf ~/.coldstart/indexes/<x>/meta.json`). If meta.json is missing,
+     * trigger a rebuild so the cache is recreated.
+     *
+     * Uses fs.watch on the parent directory (Windows quirk) and checks for
+     * meta.json existence. The existence check prevents a loop: the daemon
+     * itself writes meta.json on every save, which would fire the watch event,
+     * but we only rebuild if meta.json is MISSING.
+     */
+    private startCacheWatcher;
+}
+//# sourceMappingURL=index-manager.d.ts.map

package/dist/index-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-manager.d.ts","sourceRoot":"","sources":["../src/index-manager.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAYhD,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,aAAa,CAAC,CAAC;AAErD,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,aAAa,CAAC;IACrB,sFAAsF;IACtF,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,YAAY;IAerB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAjBxB,OAAO,CAAC,WAAW,CAAgB;IACnC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,aAAa,CAA6B;IAClD,OAAO,CAAC,kBAAkB,CAA6B;IACvD,OAAO,CAAC,gBAAgB,CAA8C;IAEtE;;;OAGG;IACH,OAAO,CAAC,oBAAoB,CAAqB;gBAG/C,YAAY,EAAE,aAAa,EACV,OAAO,EAAE,SAAS,EAClB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,OAAO;IAKjC,4EAA4E;IAC5E,UAAU,IAAI,YAAY;IAI1B,wDAAwD;IACxD,aAAa,IAAI,IAAI;IAgBrB,8CAA8C;IAC9C,YAAY,IAAI,IAAI;IAapB,OAAO,CAAC,GAAG;IAIX;;;;;OAKG;IACH,OAAO,CAAC,sBAAsB;IAe9B;;;;;;OAMG;IACH,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,eAAe,CAAS;YAClB,mBAAmB;YAoBnB,WAAW;IAuCzB;;kFAE8E;IAC9E,OAAO,CAAC,UAAU,CAAoC;YACxC,KAAK;YAQL,MAAM;YAKN,cAAc;IA4B5B;;;;OAIG;IACH,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,iBAAiB,CAA8C;IACvE,OAAO,CAAC,oBAAoB;IAgB5B;;;;;OAKG;IACH,OAAO,CAAC,WAAW,CAAK;YACV,iBAAiB;IAsB/B,iFAAiF;IACjF,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,iBAAiB;IAwBzB;;;;;;;;;OASG;IACH,OAAO,CAAC,iBAAiB;CAwC1B"}