sidekick-shared 0.27.6 → 0.28.0

package/dist/esm/writers/atomic.js

@@ -0,0 +1,375 @@
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+const LOCK_STALE_MS = 10_000;
+/**
+ * How long to wait for a lock that is making no progress.
+ *
+ * This budget detects a wedged holder, not a long queue. It is measured from the
+ * last time the lock changed hands rather than from the first attempt, because a
+ * writer queued behind other healthy writers is waiting, not failing — see
+ * {@link acquireLock}.
+ */
+const LOCK_NO_PROGRESS_MS = 3_000;
+/**
+ * A live async holder heartbeats every LOCK_STALE_MS / 3; an mtime frozen this
+ * long means the heartbeat timer is gone — the owner is dead (possibly with its
+ * PID recycled by the OS) or wedged beyond recovery. Reclaim regardless of the
+ * PID probe, which cannot tell a recycled PID from a live owner. Sync holders
+ * have no heartbeat; they usually hold locks for milliseconds, and even the
+ * slowest (a keychain read through `security` behind the auth-swap lock, up to
+ * a few seconds) stays far under this ceiling.
+ */
+const LOCK_ABANDONED_MS = 120_000;
+/**
+ * Hard ceiling on how long a synchronous waiter blocks, regardless of queue
+ * progress. Progress resets are correct for async waiters, but a sync waiter
+ * blocks its process's event loop while queued, so healthy-queue churn must not
+ * extend the block indefinitely.
+ */
+const SYNC_LOCK_MAX_WAIT_MS = 15_000;
+const LOCK_WAIT_INTERVAL_MS = 15;
+const lockSleepView = new Int32Array(new SharedArrayBuffer(4));
+/**
+ * Windows refuses to replace a file another process holds open (antivirus
+ * scanners, an editor extension re-reading `auth.json`) with EPERM/EBUSY/EACCES
+ * even though the rename would succeed a few milliseconds later. Retry with a
+ * short back-off on that platform only; other platforms surface the error.
+ */
+const WIN32_RENAME_RETRY_CODES = new Set(['EPERM', 'EBUSY', 'EACCES']);
+const WIN32_RENAME_MAX_ATTEMPTS = 10;
+function renameRetryDelayMs(attempt) {
+    return Math.min(320, 20 * 2 ** attempt);
+}
+function shouldRetryRename(error, attempt) {
+    if (process.platform !== 'win32')
+        return false;
+    if (attempt >= WIN32_RENAME_MAX_ATTEMPTS - 1)
+        return false;
+    const code = error.code ?? '';
+    return WIN32_RENAME_RETRY_CODES.has(code);
+}
+export function renameSyncWithRetry(from, to) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            fs.renameSync(from, to);
+            return;
+        }
+        catch (error) {
+            if (!shouldRetryRename(error, attempt))
+                throw error;
+            Atomics.wait(lockSleepView, 0, 0, renameRetryDelayMs(attempt));
+        }
+    }
+}
+export async function renameWithRetry(from, to) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            await fs.promises.rename(from, to);
+            return;
+        }
+        catch (error) {
+            if (!shouldRetryRename(error, attempt))
+                throw error;
+            await new Promise((resolve) => setTimeout(resolve, renameRetryDelayMs(attempt)));
+        }
+    }
+}
+async function syncDirectory(directory) {
+    let handle;
+    try {
+        handle = await fs.promises.open(directory, 'r');
+        await handle.sync();
+    }
+    catch (error) {
+        const code = error.code;
+        if (!['EISDIR', 'EINVAL', 'ENOSYS', 'EPERM', 'EACCES'].includes(code ?? ''))
+            throw error;
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+function syncDirectorySync(directory) {
+    let descriptor;
+    try {
+        descriptor = fs.openSync(directory, 'r');
+        fs.fsyncSync(descriptor);
+    }
+    catch (error) {
+        const code = error.code;
+        if (!['EISDIR', 'EINVAL', 'ENOSYS', 'EPERM', 'EACCES'].includes(code ?? ''))
+            throw error;
+    }
+    finally {
+        if (descriptor !== undefined)
+            fs.closeSync(descriptor);
+    }
+}
+export async function atomicWriteJson(filePath, value) {
+    await fs.promises.mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    const tempPath = `${filePath}.${process.pid}.${crypto.randomBytes(8).toString('hex')}.tmp`;
+    let handle;
+    try {
+        handle = await fs.promises.open(tempPath, 'wx', 0o600);
+        await handle.writeFile(JSON.stringify(value, null, 2), 'utf8');
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await renameWithRetry(tempPath, filePath);
+        await syncDirectory(path.dirname(filePath));
+    }
+    catch (error) {
+        await handle?.close().catch(() => undefined);
+        await fs.promises.rm(tempPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+export function atomicWriteJsonSync(filePath, value) {
+    atomicWriteFileSync(filePath, JSON.stringify(value, null, 2));
+}
+/** Raw-string sibling of {@link atomicWriteJsonSync} for non-JSON payloads. */
+export function atomicWriteFileSync(filePath, content, mode = 0o600) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    const tempPath = `${filePath}.${process.pid}.${crypto.randomBytes(8).toString('hex')}.tmp`;
+    let descriptor;
+    try {
+        descriptor = fs.openSync(tempPath, 'wx', mode);
+        fs.writeFileSync(descriptor, content, { encoding: 'utf8' });
+        fs.fsyncSync(descriptor);
+        fs.closeSync(descriptor);
+        descriptor = undefined;
+        renameSyncWithRetry(tempPath, filePath);
+        syncDirectorySync(path.dirname(filePath));
+    }
+    catch (error) {
+        if (descriptor !== undefined)
+            fs.closeSync(descriptor);
+        fs.rmSync(tempPath, { force: true });
+        throw error;
+    }
+}
+/** Serializes read-modify-write cycles across Sidekick processes. */
+export async function updateJsonStoreAtomic(filePath, createEmpty, update) {
+    await fs.promises.mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    const lockPath = `${filePath}.lock`;
+    const lock = await acquireLock(lockPath);
+    try {
+        let latest = createEmpty();
+        let raw;
+        try {
+            raw = await fs.promises.readFile(filePath, 'utf8');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (raw !== undefined) {
+            try {
+                latest = JSON.parse(raw);
+            }
+            catch {
+                const corruptPath = `${filePath}.corrupt-${Date.now()}-${crypto.randomBytes(4).toString('hex')}`;
+                await fs.promises.rename(filePath, corruptPath);
+            }
+        }
+        const next = await update(latest);
+        await atomicWriteJson(filePath, next);
+        return next;
+    }
+    finally {
+        await releaseLock(lockPath, lock);
+    }
+}
+/**
+ * Waits for exclusive ownership of `lockPath`.
+ *
+ * The wait budget is reset every time the lock changes hands. A flat budget from
+ * the first attempt conflated two unrelated conditions — a wedged holder and a
+ * queue of healthy writers — so under real contention the writers at the back of
+ * the queue failed even though every lock was being acquired and released
+ * correctly. Each cycle costs three fsyncs (lock file, temp file, directory), so
+ * on slow storage a burst of concurrent captures drained slower than the budget.
+ *
+ * A stuck holder keeps the same token, so it makes no progress and still trips
+ * the timeout; the stale-reclaim path below still handles an owner that died.
+ */
+async function acquireLock(lockPath) {
+    let deadline = Date.now() + LOCK_NO_PROGRESS_MS;
+    let observedOwner = null;
+    while (true) {
+        try {
+            const handle = await fs.promises.open(lockPath, 'wx', 0o600);
+            const token = `${process.pid}:${crypto.randomBytes(16).toString('hex')}`;
+            await handle.writeFile(token, 'utf8');
+            await handle.sync();
+            const heartbeat = setInterval(() => {
+                fs.promises.utimes(lockPath, new Date(), new Date()).catch(() => undefined);
+            }, Math.floor(LOCK_STALE_MS / 3));
+            heartbeat.unref();
+            return { handle, token, heartbeat };
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            // The token identifies the current holder. mtime cannot stand in for it:
+            // the heartbeat keeps touching the file, so even a wedged holder looks
+            // fresh. A different token means the queue advanced.
+            const currentOwner = await fs.promises.readFile(lockPath, 'utf8').catch(() => null);
+            if (currentOwner !== null && currentOwner !== observedOwner) {
+                observedOwner = currentOwner;
+                deadline = Date.now() + LOCK_NO_PROGRESS_MS;
+            }
+            try {
+                const stat = await fs.promises.stat(lockPath);
+                const frozenMs = Date.now() - stat.mtimeMs;
+                if (frozenMs > LOCK_STALE_MS && !lockOwnerAlive(currentOwner, frozenMs)) {
+                    await fs.promises.rm(lockPath, { force: true });
+                }
+            }
+            catch {
+                // The other writer released between checks.
+            }
+            if (Date.now() >= deadline) {
+                throw new Error(`Timed out waiting for store lock: ${lockPath} (no progress for ${LOCK_NO_PROGRESS_MS}ms)`);
+            }
+            await new Promise((resolve) => setTimeout(resolve, 15));
+        }
+    }
+}
+async function releaseLock(lockPath, lock) {
+    clearInterval(lock.heartbeat);
+    await lock.handle.close().catch(() => undefined);
+    try {
+        const currentToken = await fs.promises.readFile(lockPath, 'utf8');
+        if (currentToken === lock.token)
+            await fs.promises.rm(lockPath, { force: true });
+    }
+    catch {
+        // The lock was already released or replaced; never delete another owner's lock.
+    }
+}
+/**
+ * Whether the recorded owner of a stale lock should still be treated as alive.
+ * An mtime frozen past {@link LOCK_ABANDONED_MS} overrides the PID probe — see
+ * the constant for why the probe alone cannot be trusted at that age.
+ */
+function lockOwnerAlive(owner, frozenMs) {
+    if (frozenMs > LOCK_ABANDONED_MS)
+        return false;
+    const ownerPid = Number.parseInt((owner ?? '').split(':', 1)[0], 10);
+    if (!Number.isInteger(ownerPid) || ownerPid <= 0)
+        return false;
+    try {
+        process.kill(ownerPid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+/**
+ * Synchronous counterpart of {@link acquireLock}, sharing its lock-file
+ * protocol so sync and async waiters exclude each other across processes.
+ *
+ * Two timeout rules apply instead of one: the same progress-based budget as the
+ * async path (a token that never changes trips it in LOCK_NO_PROGRESS_MS), plus
+ * an absolute {@link SYNC_LOCK_MAX_WAIT_MS} ceiling, because a sync waiter
+ * blocks its event loop while queued. Sync holders take no heartbeat — their
+ * critical sections must stay well under LOCK_STALE_MS (in-repo users are
+ * local-filesystem read-modify-writes, plus keychain reads behind the
+ * auth-swap locks that can take a few seconds).
+ *
+ * The caller must ensure `dirname(lockPath)` exists — a missing parent
+ * surfaces as a raw ENOENT, not a timeout.
+ */
+export function withFileLockSync(lockPath, operation) {
+    const token = acquireLockSync(lockPath);
+    try {
+        return operation();
+    }
+    finally {
+        try {
+            if (fs.readFileSync(lockPath, 'utf8') === token)
+                fs.rmSync(lockPath, { force: true });
+        }
+        catch {
+            // The lock was already released or replaced; never delete another owner's lock.
+        }
+    }
+}
+function acquireLockSync(lockPath) {
+    const start = Date.now();
+    let deadline = start + LOCK_NO_PROGRESS_MS;
+    let observedOwner = null;
+    while (true) {
+        try {
+            const descriptor = fs.openSync(lockPath, 'wx', 0o600);
+            const token = `${process.pid}:${crypto.randomBytes(16).toString('hex')}`;
+            fs.writeFileSync(descriptor, token, 'utf8');
+            fs.fsyncSync(descriptor);
+            fs.closeSync(descriptor);
+            return token;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            let currentOwner = null;
+            try {
+                currentOwner = fs.readFileSync(lockPath, 'utf8');
+            }
+            catch {
+                // The other writer released between checks.
+            }
+            if (currentOwner !== null && currentOwner !== observedOwner) {
+                observedOwner = currentOwner;
+                deadline = Date.now() + LOCK_NO_PROGRESS_MS;
+            }
+            try {
+                const stat = fs.statSync(lockPath);
+                const frozenMs = Date.now() - stat.mtimeMs;
+                if (frozenMs > LOCK_STALE_MS && !lockOwnerAlive(currentOwner, frozenMs)) {
+                    fs.rmSync(lockPath, { force: true });
+                }
+            }
+            catch {
+                // The other writer released between checks.
+            }
+            const now = Date.now();
+            if (now >= deadline) {
+                throw new Error(`Timed out waiting for store lock: ${lockPath} (no progress for ${LOCK_NO_PROGRESS_MS}ms)`);
+            }
+            if (now - start >= SYNC_LOCK_MAX_WAIT_MS) {
+                throw new Error(`Timed out waiting for store lock: ${lockPath} (blocked synchronously for ${SYNC_LOCK_MAX_WAIT_MS}ms)`);
+            }
+            Atomics.wait(lockSleepView, 0, 0, LOCK_WAIT_INTERVAL_MS);
+        }
+    }
+}
+/** Synchronous mirror of {@link updateJsonStoreAtomic}. */
+export function updateJsonStoreAtomicSync(filePath, createEmpty, update) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    return withFileLockSync(`${filePath}.lock`, () => {
+        let latest = createEmpty();
+        let raw;
+        try {
+            raw = fs.readFileSync(filePath, 'utf8');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (raw !== undefined) {
+            try {
+                latest = JSON.parse(raw);
+            }
+            catch {
+                const corruptPath = `${filePath}.corrupt-${Date.now()}-${crypto.randomBytes(4).toString('hex')}`;
+                fs.renameSync(filePath, corruptPath);
+            }
+        }
+        const next = update(latest);
+        atomicWriteJsonSync(filePath, next);
+        return next;
+    });
+}

package/dist/esm/writers/decisions.js

@@ -0,0 +1,51 @@
+import * as crypto from 'crypto';
+import { getProjectDataPath, resolveProjectIdentity } from '../paths';
+import { migrateLegacyProjectStores } from '../projectMigration';
+import { DECISION_LOG_SCHEMA_VERSION, } from '../types/decisionLog';
+import { updateJsonStoreAtomic } from './atomic';
+function emptyDecisionStore() {
+    return {
+        schemaVersion: DECISION_LOG_SCHEMA_VERSION,
+        decisions: {},
+        lastSessionId: 'cli',
+        lastSaved: new Date().toISOString(),
+    };
+}
+export function decisionFingerprint(decision) {
+    return `${decision.source}::${decision.description.toLowerCase().trim()}`;
+}
+export async function addDecision(cwd, description, options = {}) {
+    const project = resolveProjectIdentity(cwd);
+    migrateLegacyProjectStores(project);
+    const filePath = getProjectDataPath(project.canonicalSlug, 'decisions');
+    const decision = {
+        id: crypto.randomUUID(),
+        description: description.trim(),
+        rationale: options.rationale?.trim() || 'Captured from the Sidekick CLI.',
+        chosenOption: options.chosenOption?.trim() || description.trim(),
+        alternatives: options.alternatives,
+        source: options.source ?? 'text_pattern',
+        sessionId: 'cli',
+        timestamp: new Date().toISOString(),
+        tags: options.tags,
+    };
+    let added = false;
+    let persisted = decision;
+    await updateJsonStoreAtomic(filePath, emptyDecisionStore, (store) => {
+        const fingerprint = decisionFingerprint(decision);
+        const duplicate = Object.values(store.decisions).find((entry) => decisionFingerprint(entry) === fingerprint);
+        if (duplicate) {
+            persisted = duplicate;
+            return store;
+        }
+        added = true;
+        return {
+            ...store,
+            schemaVersion: DECISION_LOG_SCHEMA_VERSION,
+            decisions: { ...store.decisions, [decision.id]: decision },
+            lastSessionId: 'cli',
+            lastSaved: decision.timestamp,
+        };
+    });
+    return { decision: persisted, added };
+}

package/dist/esm/writers/notes.js

@@ -0,0 +1,46 @@
+import * as crypto from 'crypto';
+import { getProjectDataPath, resolveProjectIdentity } from '../paths';
+import { migrateLegacyProjectStores } from '../projectMigration';
+import { KNOWLEDGE_NOTE_SCHEMA_VERSION, } from '../types/knowledgeNote';
+import { updateJsonStoreAtomic } from './atomic';
+function emptyNoteStore() {
+    return {
+        schemaVersion: KNOWLEDGE_NOTE_SCHEMA_VERSION,
+        notesByFile: {},
+        lastSaved: new Date().toISOString(),
+        totalNotes: 0,
+    };
+}
+export async function addNote(cwd, content, options = {}) {
+    const project = resolveProjectIdentity(cwd);
+    migrateLegacyProjectStores(project);
+    const filePath = getProjectDataPath(project.canonicalSlug, 'knowledge-notes');
+    const now = new Date().toISOString();
+    const notePath = options.filePath?.trim() || '.';
+    const note = {
+        id: crypto.randomUUID(),
+        noteType: options.noteType ?? 'tip',
+        content: content.trim(),
+        title: options.title,
+        filePath: notePath,
+        source: 'manual',
+        status: 'active',
+        importance: options.importance ?? 'medium',
+        createdAt: now,
+        updatedAt: now,
+        lastReviewedAt: now,
+        tags: options.tags,
+    };
+    await updateJsonStoreAtomic(filePath, emptyNoteStore, (store) => {
+        const existing = store.notesByFile[notePath] ?? [];
+        const notesByFile = { ...store.notesByFile, [notePath]: [...existing, note] };
+        return {
+            ...store,
+            schemaVersion: KNOWLEDGE_NOTE_SCHEMA_VERSION,
+            notesByFile,
+            totalNotes: Object.values(notesByFile).reduce((sum, notes) => sum + notes.length, 0),
+            lastSaved: now,
+        };
+    });
+    return note;
+}

package/dist/esm/writers/tasks.js

@@ -0,0 +1,63 @@
+import * as crypto from 'crypto';
+import { getProjectDataPath, resolveProjectIdentity } from '../paths';
+import { migrateLegacyProjectStores } from '../projectMigration';
+import { TASK_PERSISTENCE_SCHEMA_VERSION, } from '../types/taskPersistence';
+import { updateJsonStoreAtomic } from './atomic';
+function emptyTaskStore() {
+    return {
+        schemaVersion: TASK_PERSISTENCE_SCHEMA_VERSION,
+        tasks: {},
+        lastSessionId: 'cli',
+        sessionCount: 0,
+        lastSaved: new Date().toISOString(),
+    };
+}
+export async function addTask(cwd, subject, options = {}) {
+    const project = resolveProjectIdentity(cwd);
+    migrateLegacyProjectStores(project);
+    const filePath = getProjectDataPath(project.canonicalSlug, 'tasks');
+    const now = new Date().toISOString();
+    const task = {
+        taskId: crypto.randomUUID(),
+        subject: subject.trim(),
+        description: options.description,
+        status: 'pending',
+        createdAt: now,
+        updatedAt: now,
+        toolCallCount: 0,
+        blockedBy: [],
+        blocks: [],
+        sessionOrigin: 'cli',
+        carriedOver: false,
+        sessionAge: 0,
+        tags: options.tags,
+    };
+    await updateJsonStoreAtomic(filePath, emptyTaskStore, (store) => ({
+        ...store,
+        schemaVersion: TASK_PERSISTENCE_SCHEMA_VERSION,
+        tasks: { ...store.tasks, [task.taskId]: task },
+        lastSessionId: store.lastSessionId || 'cli',
+        lastSaved: now,
+    }));
+    return task;
+}
+export async function completeTask(cwd, taskIdOrPrefix) {
+    const project = resolveProjectIdentity(cwd);
+    migrateLegacyProjectStores(project);
+    const filePath = getProjectDataPath(project.canonicalSlug, 'tasks');
+    let completed;
+    await updateJsonStoreAtomic(filePath, emptyTaskStore, (store) => {
+        const matches = Object.values(store.tasks).filter((task) => task.taskId === taskIdOrPrefix || task.taskId.startsWith(taskIdOrPrefix));
+        if (matches.length !== 1) {
+            throw new Error(matches.length === 0 ? `Task not found: ${taskIdOrPrefix}` : 'Task ID is ambiguous');
+        }
+        const now = new Date().toISOString();
+        completed = { ...matches[0], status: 'completed', updatedAt: now };
+        return {
+            ...store,
+            tasks: { ...store.tasks, [completed.taskId]: completed },
+            lastSaved: now,
+        };
+    });
+    return completed;
+}