|
| 1 | +// @ts-check |
| 2 | +'use strict'; |
| 3 | + |
| 4 | +/* |
| 5 | + * sessionStore.js — the persistence spine for LevelCode chat sessions. |
| 6 | + * |
| 7 | + * Pure Node (fs / path / crypto), no `vscode` — so it unit-tests like update.js and mcpConfig.js. |
| 8 | + * The design lives in docs/levelcode-chat-sessions-design.md (storage) and |
| 9 | + * docs/levelcode-sessions-experience.md (why the shapes are what they are). |
| 10 | + * |
| 11 | + * The one property this module exists to guarantee is FAST RETRIEVAL that does not degrade with a |
| 12 | + * session's age or with the size of the corpus: |
| 13 | + * |
| 14 | + * • LISTING / SEARCHING reads the in-memory INDEX, never the session files. `loadIndex` is paid once; |
| 15 | + * `getEntry` / `listEntries` are pure lookups over that array. A chat created 25 days ago (or a |
| 16 | + * year ago) costs exactly the same as one created a minute ago — the index carries its metadata. |
| 17 | + * • SWITCHING (resume) reads exactly ONE file — that session's `.jsonl` — via `readSession`. It never |
| 18 | + * scans the directory or touches its neighbours, so wall-clock is bounded by that one session's |
| 19 | + * size, not by how many sessions exist or how old this one is. |
| 20 | + * • The index is a CACHE, never load-bearing: `loadIndex` rebuilds it by scanning on any corruption, |
| 21 | + * and `scanProject` (reading the files) is always the source of truth (anti-Copilot #vscdb). |
| 22 | + * |
| 23 | + * Storage layout (per project): |
| 24 | + * <root>/<project-slug>/ |
| 25 | + * index.json cache of derived entries — rebuildable by scanning |
| 26 | + * <session-id>.jsonl one meta line + append-only events |
| 27 | + */ |
| 28 | + |
| 29 | +const fs = require('fs'); |
| 30 | +const path = require('path'); |
| 31 | +const crypto = require('crypto'); |
| 32 | + |
| 33 | +/** Bump only on an incompatible on-disk change; `loadIndex` refuses a newer index and rebuilds. */ |
| 34 | +const SCHEMA_V = 1; |
| 35 | + |
| 36 | +const INDEX_NAME = 'index.json'; |
| 37 | +const PREVIEW_MAX = 96; |
| 38 | + |
| 39 | +// ── slug & ids (pure) ────────────────────────────────────────────────────────────────────────── |
| 40 | + |
| 41 | +/** |
| 42 | + * A project path → a human-readable, filesystem-safe directory slug. |
| 43 | + * "/Users/ada/code/thin.ly" → "-Users-ada-code-thin-ly" |
| 44 | + * |
| 45 | + * Every run of non-`[A-Za-z0-9_]` collapses to a single "-"; the LEADING dash is kept (it encodes the |
| 46 | + * absolute-path root and matches the convention Claude Code and this repo's own memory dir already use), |
| 47 | + * a trailing dash is trimmed. The slug is intentionally lossy (two unicode-only paths can collide); that |
| 48 | + * is safe because the REAL path is stored in each file's meta line — a collision degrades to "listed |
| 49 | + * under a shared name", never to "lost" (design §3 keying). Callers disambiguate on `meta.project`. |
| 50 | + */ |
| 51 | +function projectSlug(projectPath) { |
| 52 | + const s = String(projectPath == null ? '' : projectPath).replace(/[^A-Za-z0-9_]+/g, '-').replace(/-+$/, ''); |
| 53 | + return s || '-'; // the filesystem root (or an empty path) still needs a directory name |
| 54 | +} |
| 55 | + |
| 56 | +/** |
| 57 | + * A sortable, filesystem-safe session id: `YYYY-MM-DDTHH-MM-SS-<rand>` (colons/dots → dashes, so it is a |
| 58 | + * legal filename and lexicographically time-ordered). `now`/`rand` are injected for deterministic tests; |
| 59 | + * default to the clock and 4 base36 chars of randomness. |
| 60 | + */ |
| 61 | +function newSessionId(now, rand) { |
| 62 | + const d = now instanceof Date ? now : new Date(); |
| 63 | + const stamp = d.toISOString().replace(/[:.]/g, '-').slice(0, 19); // 2026-07-28T09-12-33 |
| 64 | + const r = rand != null ? String(rand) : crypto.randomBytes(3).toString('hex').slice(0, 4); |
| 65 | + return stamp + '-' + r; |
| 66 | +} |
| 67 | + |
| 68 | +// ── paths (pure) ─────────────────────────────────────────────────────────────────────────────── |
| 69 | + |
| 70 | +function projectDir(root, slug) { return path.join(root, slug); } |
| 71 | +function sessionFile(root, slug, id) { return path.join(root, slug, String(id) + '.jsonl'); } |
| 72 | +function indexFile(root, slug) { return path.join(root, slug, INDEX_NAME); } |
| 73 | + |
| 74 | +// ── event encoding & parsing (pure) ────────────────────────────────────────────────────────────── |
| 75 | + |
| 76 | +/** The birth line — written once, so even a one-message crash leaves a listable session (design §4). */ |
| 77 | +function metaLine(id, projectPath, createdAtIso, title) { |
| 78 | + return { kind: 'meta', v: SCHEMA_V, id: String(id), project: String(projectPath == null ? '' : projectPath), |
| 79 | + createdAt: String(createdAtIso), title: title == null ? null : String(title) }; |
| 80 | +} |
| 81 | + |
| 82 | +function encodeEvent(event) { return JSON.stringify(event) + '\n'; } |
| 83 | + |
| 84 | +/** |
| 85 | + * Parse a session file's text into `{ meta, events }`. Tolerant by construction: append-only means the |
| 86 | + * only way a line is malformed is a torn final write (crash mid-append), so a trailing unparseable line |
| 87 | + * is DROPPED rather than throwing — the crash costs at most the in-flight event (design §prior-art). |
| 88 | + */ |
| 89 | +function parseSession(text) { |
| 90 | + const lines = String(text == null ? '' : text).split('\n'); |
| 91 | + let meta = null; |
| 92 | + const events = []; |
| 93 | + for (let i = 0; i < lines.length; i++) { |
| 94 | + const line = lines[i]; |
| 95 | + if (!line) { continue; } // blank (incl. the trailing newline's empty tail) |
| 96 | + let obj; |
| 97 | + try { obj = JSON.parse(line); } |
| 98 | + catch { if (i === lines.length - 1) { break; } else { continue; } } // torn last line → stop; a mid-file junk line → skip |
| 99 | + if (obj && obj.kind === 'meta' && !meta) { meta = obj; } |
| 100 | + else { events.push(obj); } |
| 101 | + } |
| 102 | + return { meta, events }; |
| 103 | +} |
| 104 | + |
| 105 | +// ── derive an index entry from a parsed session (pure — the heart of the cache) ────────────────── |
| 106 | + |
| 107 | +function truncate(s, n) { const t = String(s == null ? '' : s); return t.length > n ? t.slice(0, n - 1) + '…' : t; } |
| 108 | + |
| 109 | +/** |
| 110 | + * Fold a parsed session into the compact entry the History list reads. PURE and total — every field |
| 111 | + * degrades gracefully so a partial/old-schema session still yields a listable row (never throws). |
| 112 | + */ |
| 113 | +function deriveEntry(meta, events) { |
| 114 | + const evs = Array.isArray(events) ? events : []; |
| 115 | + const id = meta && meta.id ? String(meta.id) : null; |
| 116 | + const createdAt = meta && meta.createdAt ? meta.createdAt : (evs[0] && evs[0].t) || null; |
| 117 | + |
| 118 | + let title = null, updatedAt = createdAt, model = null, state = 'active', lifecycle = 'active', pinned = false; |
| 119 | + let turns = 0, firstUser = null; |
| 120 | + const editCounts = new Map(); // path → times edited (order-preserving via Map) |
| 121 | + const spark = []; |
| 122 | + |
| 123 | + for (const e of evs) { |
| 124 | + if (!e || typeof e !== 'object') { continue; } |
| 125 | + if (e.t) { updatedAt = e.t; } |
| 126 | + switch (e.kind) { |
| 127 | + case 'user': turns++; if (firstUser == null && e.content != null) { firstUser = String(e.content); } break; |
| 128 | + case 'assistant': case 'agent': if (e.model) { model = e.model; } break; |
| 129 | + case 'title': if (e.title != null) { title = String(e.title); } break; |
| 130 | + case 'end': if (e.state) { state = String(e.state); } break; |
| 131 | + case 'label': |
| 132 | + if (e.lifecycle) { lifecycle = String(e.lifecycle); } |
| 133 | + if (typeof e.pinned === 'boolean') { pinned = e.pinned; } |
| 134 | + break; |
| 135 | + } |
| 136 | + // files edited + the activity sparkline come from agent turns (explicit `edits` + `tools` count) |
| 137 | + if (e.kind === 'agent' || e.kind === 'edit') { |
| 138 | + const paths = e.kind === 'edit' ? (e.path ? [e.path] : []) : (Array.isArray(e.edits) ? e.edits.map((x) => x && x.path).filter(Boolean) : []); |
| 139 | + for (const p of paths) { editCounts.set(p, (editCounts.get(p) || 0) + 1); } |
| 140 | + } |
| 141 | + if (e.kind === 'agent') { spark.push(Number.isFinite(e.tools) ? e.tools : (Array.isArray(e.edits) ? e.edits.length : 0)); } |
| 142 | + } |
| 143 | + |
| 144 | + if (title == null) { title = (meta && meta.title != null) ? String(meta.title) : (firstUser != null ? truncate(firstUser, 56) : null); } |
| 145 | + const filesEdited = [...editCounts.entries()].sort((a, b) => b[1] - a[1]).map(([p]) => p); |
| 146 | + |
| 147 | + return { id, title, createdAt, updatedAt, turns, model, state, lifecycle, pinned, |
| 148 | + filesEdited, spark, preview: firstUser != null ? truncate(firstUser, PREVIEW_MAX) : null }; |
| 149 | +} |
| 150 | + |
| 151 | +// ── writing (append-only) ──────────────────────────────────────────────────────────────────────── |
| 152 | + |
| 153 | +/** Create a session: its directory + the meta birth line. Idempotent-ish (a re-create just rewrites meta). */ |
| 154 | +function createSession(root, slug, id, projectPath, createdAtIso, title) { |
| 155 | + fs.mkdirSync(projectDir(root, slug), { recursive: true }); |
| 156 | + fs.writeFileSync(sessionFile(root, slug, id), encodeEvent(metaLine(id, projectPath, createdAtIso, title))); |
| 157 | + return sessionFile(root, slug, id); |
| 158 | +} |
| 159 | + |
| 160 | +/** Append ONE event line. The only write on the hot (per-turn) path — a tiny, crash-safe append. */ |
| 161 | +function appendEvent(file, event) { fs.appendFileSync(file, encodeEvent(event)); } |
| 162 | + |
| 163 | +// ── reading ONE session (the switch path — exactly one file) ───────────────────────────────────── |
| 164 | + |
| 165 | +/** Read + parse a single session file. This is what `resume`/switch calls: one file, size-bounded. */ |
| 166 | +function readSession(file) { return parseSession(fs.readFileSync(file, 'utf8')); } |
| 167 | + |
| 168 | +// ── the index (cache; rebuildable by scanning) ─────────────────────────────────────────────────── |
| 169 | + |
| 170 | +function listSessionFiles(root, slug) { |
| 171 | + let names; |
| 172 | + try { names = fs.readdirSync(projectDir(root, slug)); } |
| 173 | + catch { return []; } // no project dir yet → no sessions |
| 174 | + return names.filter((n) => n.endsWith('.jsonl')).map((n) => path.join(root, slug, n)); |
| 175 | +} |
| 176 | + |
| 177 | +/** Sort newest-first for the default History order. */ |
| 178 | +function sortEntries(entries) { |
| 179 | + return entries.slice().sort((a, b) => String(b.updatedAt || b.createdAt || '').localeCompare(String(a.updatedAt || a.createdAt || ''))); |
| 180 | +} |
| 181 | + |
| 182 | +/** |
| 183 | + * The SOURCE OF TRUTH: derive every entry by reading the files. O(corpus) and only paid when the cache is |
| 184 | + * absent or corrupt — never on a normal list. This is what makes the index safe to treat as a throwaway. |
| 185 | + */ |
| 186 | +function scanProject(root, slug) { |
| 187 | + const entries = []; |
| 188 | + for (const file of listSessionFiles(root, slug)) { |
| 189 | + try { const { meta, events } = readSession(file); const e = deriveEntry(meta, events); if (e.id) { entries.push(e); } } |
| 190 | + catch { /* a single unreadable file must not sink the scan */ } |
| 191 | + } |
| 192 | + return sortEntries(entries); |
| 193 | +} |
| 194 | + |
| 195 | +/** |
| 196 | + * Load the index CACHE for a project. Reads index.json and validates it; on ANY problem — missing, |
| 197 | + * malformed, wrong/newer schema, not an array — it silently REBUILDS by scanning and reports `rebuilt`, |
| 198 | + * so a corrupt index can never hide sessions that still exist on disk. Returns { v, entries, rebuilt }. |
| 199 | + */ |
| 200 | +function loadIndex(root, slug) { |
| 201 | + try { |
| 202 | + const raw = fs.readFileSync(indexFile(root, slug), 'utf8'); |
| 203 | + const obj = JSON.parse(raw); |
| 204 | + if (obj && obj.v === SCHEMA_V && Array.isArray(obj.entries)) { |
| 205 | + return { v: SCHEMA_V, entries: sortEntries(obj.entries), rebuilt: false }; |
| 206 | + } |
| 207 | + } catch { /* fall through to rebuild */ } |
| 208 | + return { v: SCHEMA_V, entries: scanProject(root, slug), rebuilt: true }; |
| 209 | +} |
| 210 | + |
| 211 | +/** Persist the index atomically (tmp + rename) so a crash never leaves a half-written cache. */ |
| 212 | +function writeIndex(root, slug, entries) { |
| 213 | + fs.mkdirSync(projectDir(root, slug), { recursive: true }); |
| 214 | + const tmp = indexFile(root, slug) + '.' + process.pid + '.tmp'; |
| 215 | + fs.writeFileSync(tmp, JSON.stringify({ v: SCHEMA_V, entries: sortEntries(entries) })); |
| 216 | + fs.renameSync(tmp, indexFile(root, slug)); |
| 217 | +} |
| 218 | + |
| 219 | +/** Incrementally replace-or-insert one entry (by id) — the per-seal update, no full rescan. */ |
| 220 | +function upsertEntry(entries, entry) { |
| 221 | + const out = (Array.isArray(entries) ? entries : []).filter((e) => e && e.id !== entry.id); |
| 222 | + out.push(entry); |
| 223 | + return sortEntries(out); |
| 224 | +} |
| 225 | + |
| 226 | +// ── FAST RETRIEVAL (pure, in-memory — no disk) ─────────────────────────────────────────────────── |
| 227 | + |
| 228 | +/** |
| 229 | + * Look up one entry by id in an ALREADY-LOADED index. Pure: it takes the in-memory `index` and never |
| 230 | + * touches disk, so retrieving a 25-day-old (or any-age) session's metadata is a memory op, independent |
| 231 | + * of the corpus. For very large corpora a Map cache is a drop-in; a linear find over a few thousand |
| 232 | + * entries is already sub-millisecond. |
| 233 | + */ |
| 234 | +function getEntry(index, id) { |
| 235 | + const entries = index && Array.isArray(index.entries) ? index.entries : []; |
| 236 | + for (const e of entries) { if (e && e.id === id) { return e; } } |
| 237 | + return null; |
| 238 | +} |
| 239 | + |
| 240 | +/** The sorted list view (pure). Optional lifecycle filter (e.g. 'active' hides archived). */ |
| 241 | +function listEntries(index, opts) { |
| 242 | + const o = opts || {}; |
| 243 | + let entries = (index && Array.isArray(index.entries) ? index.entries : []).slice(); |
| 244 | + if (o.lifecycle) { entries = entries.filter((e) => (e.lifecycle || 'active') === o.lifecycle); } |
| 245 | + return sortEntries(entries); |
| 246 | +} |
| 247 | + |
| 248 | +module.exports = { |
| 249 | + SCHEMA_V, |
| 250 | + projectSlug, newSessionId, projectDir, sessionFile, indexFile, |
| 251 | + metaLine, encodeEvent, parseSession, deriveEntry, |
| 252 | + createSession, appendEvent, readSession, |
| 253 | + listSessionFiles, scanProject, loadIndex, writeIndex, upsertEntry, |
| 254 | + getEntry, listEntries |
| 255 | +}; |
0 commit comments