dsh-checklists 0.0.0-stage → 0.3.3

package/lib/store.js

@@ -0,0 +1,174 @@
+/**
+ * Durable per-session checklist storage.
+ *
+ * Layout under the DSH home directory:
+ *
+ *   $DSH_HOME/storages/dsh-checklist/
+ *   ├─ sessions/<sessionId>.json   one document per session
+ *   └─ templates.json              reusable, cross-session templates
+ *
+ * The store keeps an in-process cache because the system-prompt digest is
+ * rendered synchronously, while disk access is not. Writes are serialized per
+ * session and land atomically (temp file + rename), so two concurrent tool
+ * calls cannot interleave into a torn document.
+ */
+import { mkdir, readFile, readdir, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { emptyDoc } from './model.js';
+/** Conservative allowlist: a session id becomes a file name. */
+const SAFE_ID = /^[A-Za-z0-9._-]{1,200}$/;
+/** Resolve the DSH home directory (env override wins). */
+export function resolveDshHome(env = process.env) {
+    const fromEnv = env.DSH_HOME?.trim();
+    return fromEnv && fromEnv.length > 0 ? fromEnv : join(homedir(), '.dsh');
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === 'string');
+}
+export class ChecklistStore {
+    root;
+    cache = new Map();
+    chains = new Map();
+    inflight = new Map();
+    constructor(root) {
+        this.root = root ?? join(resolveDshHome(), 'storages', 'dsh-checklist');
+    }
+    /** The synchronous view used by the prompt digest; `undefined` until primed. */
+    peek(sessionId) {
+        return this.cache.get(sessionId);
+    }
+    /** Load one session (cache first, then disk). */
+    async prime(sessionId) {
+        const cached = this.cache.get(sessionId);
+        if (cached)
+            return cached;
+        const running = this.inflight.get(sessionId);
+        if (running)
+            return running;
+        const load = this.read(sessionId).then((doc) => {
+            this.cache.set(sessionId, doc);
+            this.inflight.delete(sessionId);
+            return doc;
+        }, (error) => {
+            this.inflight.delete(sessionId);
+            throw error;
+        });
+        this.inflight.set(sessionId, load);
+        return load;
+    }
+    /**
+     * Apply one mutation to a session and persist it.
+     *
+     * The mutator receives a fresh clone, so a throw leaves the cached document
+     * untouched. Calls for one session are serialized.
+     */
+    async update(sessionId, mutate) {
+        const previous = this.chains.get(sessionId) ?? Promise.resolve();
+        const run = previous.then(async () => {
+            const current = await this.prime(sessionId);
+            const draft = structuredClone(current);
+            const result = await mutate(draft);
+            await this.write(draft);
+            return result;
+        });
+        this.chains.set(sessionId, run.then(() => undefined, () => undefined));
+        return run;
+    }
+    async readTemplates() {
+        try {
+            const raw = await readFile(this.templatesFile(), 'utf8');
+            const parsed = JSON.parse(raw);
+            if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+                return {};
+            const out = {};
+            for (const [name, value] of Object.entries(parsed)) {
+                if (isStringArray(value))
+                    out[name] = value;
+            }
+            return out;
+        }
+        catch {
+            return {};
+        }
+    }
+    async writeTemplates(templates) {
+        await mkdir(this.root, { recursive: true });
+        const file = this.templatesFile();
+        const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+        await writeFile(tmp, `${JSON.stringify(templates, null, 2)}\n`, 'utf8');
+        await rename(tmp, file);
+    }
+    /** Delete session files untouched for `maxAgeDays`. Returns the count removed. */
+    async prune(maxAgeDays) {
+        const dir = join(this.root, 'sessions');
+        let names;
+        try {
+            names = await readdir(dir);
+        }
+        catch {
+            return 0;
+        }
+        const cutoff = Date.now() - maxAgeDays * 86_400_000;
+        let removed = 0;
+        for (const name of names) {
+            if (!name.endsWith('.json'))
+                continue;
+            const path = join(dir, name);
+            try {
+                const info = await stat(path);
+                if (info.mtimeMs >= cutoff)
+                    continue;
+                await unlink(path);
+                removed += 1;
+            }
+            catch {
+                // Raced with another process; nothing to do.
+            }
+        }
+        return removed;
+    }
+    templatesFile() {
+        return join(this.root, 'templates.json');
+    }
+    fileFor(sessionId) {
+        if (!SAFE_ID.test(sessionId)) {
+            throw new Error(`checklist: refusing unsafe session id ${JSON.stringify(sessionId)}`);
+        }
+        return join(this.root, 'sessions', `${sessionId}.json`);
+    }
+    async read(sessionId) {
+        const file = this.fileFor(sessionId);
+        let raw;
+        try {
+            raw = await readFile(file, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return emptyDoc(sessionId);
+            throw error;
+        }
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed !== null &&
+                typeof parsed === 'object' &&
+                parsed.version === 1 &&
+                parsed.sessionId === sessionId &&
+                Array.isArray(parsed.lists)) {
+                return parsed;
+            }
+        }
+        catch {
+            // Corrupt document: start clean rather than failing every turn.
+        }
+        return emptyDoc(sessionId);
+    }
+    async write(doc) {
+        const file = this.fileFor(doc.sessionId);
+        await mkdir(join(this.root, 'sessions'), { recursive: true });
+        const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+        await writeFile(tmp, `${JSON.stringify(doc, null, 2)}\n`, 'utf8');
+        await rename(tmp, file);
+        this.cache.set(doc.sessionId, doc);
+    }
+}