@harness-fe/mcp-server 4.0.0-next.1 → 4.0.0-next.3

package/dist/store/JsonlStore.js

@@ -1,1172 +0,0 @@
-/**
- * JsonlStore — JSONL-based persistence layer (v0.4.0 layout).
- *
- * New layout (v0.4.0):
- *   {dataDir}/projects/{projectId}/meta.json
- *   {dataDir}/projects/{projectId}/notes.jsonl
- *   {dataDir}/projects/{projectId}/builds/{buildId}/meta.json
- *   {dataDir}/tabs/{tabId}/meta.json
- *   {dataDir}/sessions/{sessionId}/meta.json
- *   {dataDir}/sessions/{sessionId}/timeline.jsonl
- *   {dataDir}/sessions/{sessionId}/recording.jsonl
- *   {dataDir}/exports/index.jsonl
- *   {dataDir}/exports/{exportId}.rrweb.json
- *
- * Legacy layout (v0.3.x, read-only fallback):
- *   {dataDir}/{projectId}/sessions/{buildId}/tabs/{tabId}/...
- *   On startup, if legacy dirs are detected a warning is emitted pointing
- *   users to `rm -rf ~/.harness/data`.
- */
-import { appendFileSync, existsSync, mkdirSync, openSync, readSync, closeSync, readdirSync, readFileSync, rmdirSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
-import { WriteQueue } from './WriteQueue.js';
-import { join, resolve } from 'node:path';
-import { randomUUID } from 'node:crypto';
-import { homedir } from 'node:os';
-/**
- * Append to a deduped LRU list capped at `max` entries. Pushing an existing
- * value moves it to the tail (most-recent). Used for VisitorMeta.tabIds and
- * VisitorMeta.projectIds so noisy demo sites don't grow these unboundedly.
- */
-function lruAppend(existing, value, max) {
-    const list = existing ? [...existing] : [];
-    if (!value)
-        return list;
-    const idx = list.indexOf(value);
-    if (idx >= 0)
-        list.splice(idx, 1);
-    list.push(value);
-    while (list.length > max)
-        list.shift();
-    return list;
-}
-const DEFAULT_DATA_DIR = join(homedir(), '.harness', 'data');
-const DEFAULT_RETENTION = {
-    maxAgeDays: 7,
-    maxSessions: 200,
-    recordingRetentionDays: 3,
-    maxRecordingChunksPerSession: 500,
-    maxRecordingBytesPerSession: 250 * 1024 * 1024,
-    preserveMarkedChunks: true,
-    maxExportsPerProject: 50,
-    maxExportBytesPerProject: 200 * 1024 * 1024,
-    maxBuildsPerProject: 100,
-};
-// ─── Helpers ──────────────────────────────────────────────────────────────────
-function ensureDir(dir) {
-    if (!existsSync(dir))
-        mkdirSync(dir, { recursive: true });
-}
-function writeJson(path, data) {
-    writeFileSync(path, JSON.stringify(data, null, 2), 'utf-8');
-}
-function readJson(path) {
-    try {
-        return JSON.parse(readFileSync(path, 'utf-8'));
-    }
-    catch {
-        return undefined;
-    }
-}
-function appendJsonl(path, obj) {
-    appendFileSync(path, JSON.stringify(obj) + '\n', 'utf-8');
-}
-function readLastNLines(filePath, n) {
-    if (!existsSync(filePath))
-        return [];
-    const CHUNK = 16 * 1024;
-    const { size } = statSync(filePath);
-    if (size === 0)
-        return [];
-    if (size <= CHUNK * 2) {
-        const content = readFileSync(filePath, 'utf-8');
-        const lines = content.split('\n').filter((l) => l.trim());
-        return lines.slice(-n);
-    }
-    const fd = openSync(filePath, 'r');
-    try {
-        let pos = size;
-        let collected = '';
-        let lines = [];
-        while (pos > 0 && lines.length < n + 1) {
-            const readSize = Math.min(CHUNK, pos);
-            pos -= readSize;
-            const buf = Buffer.alloc(readSize);
-            readSync(fd, buf, 0, readSize, pos);
-            collected = buf.toString('utf-8') + collected;
-            lines = collected.split('\n').filter((l) => l.trim());
-        }
-        return lines.slice(-n);
-    }
-    finally {
-        closeSync(fd);
-    }
-}
-function readAllLines(filePath) {
-    if (!existsSync(filePath))
-        return [];
-    return readFileSync(filePath, 'utf-8')
-        .split('\n')
-        .filter((l) => l.trim());
-}
-function parseEvent(line) {
-    try {
-        return JSON.parse(line);
-    }
-    catch {
-        return undefined;
-    }
-}
-function parseJsonLine(line) {
-    try {
-        return JSON.parse(line);
-    }
-    catch {
-        return undefined;
-    }
-}
-function parseRecordingChunkLine(line, tabId, fallbackAgeTs, index) {
-    const parsed = parseJsonLine(line);
-    if (!parsed || !Array.isArray(parsed.events))
-        return undefined;
-    if (typeof parsed.chunkId !== 'string') {
-        process.stderr.write(`[harness-fe] recording chunk at index ${index} is missing chunkId — skipping (pre-0.4 data). ` +
-            `Run \`rm -rf ~/.harness/data\` to clear legacy data.\n`);
-        return undefined;
-    }
-    const chunkId = parsed.chunkId;
-    const startTs = typeof parsed.startTs === 'number'
-        ? parsed.startTs
-        : typeof parsed.ts === 'number'
-            ? parsed.ts
-            : undefined;
-    const endTs = typeof parsed.endTs === 'number'
-        ? parsed.endTs
-        : typeof parsed.ts === 'number'
-            ? parsed.ts
-            : undefined;
-    if (startTs === undefined || endTs === undefined)
-        return undefined;
-    return {
-        chunkId,
-        tabId,
-        startTs,
-        endTs,
-        eventCount: typeof parsed.eventCount === 'number'
-            ? parsed.eventCount
-            : parsed.events.length,
-        events: parsed.events,
-        line,
-        bytes: Buffer.byteLength(`${line}\n`, 'utf-8'),
-        marked: false,
-        ageTs: typeof parsed.endTs === 'number'
-            ? parsed.endTs
-            : fallbackAgeTs,
-    };
-}
-const META_EXTENSION_LIMIT_BYTES = 16 * 1024;
-const MAX_EVENT_BYTES = 256 * 1024;
-const MAX_RECORDING_CHUNK_BYTES = 2 * 1024 * 1024;
-function enforceExtensionBudget(meta, label) {
-    const open = JSON.stringify({ tags: meta.tags, metadata: meta.metadata });
-    const size = Buffer.byteLength(open, 'utf-8');
-    if (size > META_EXTENSION_LIMIT_BYTES) {
-        throw new Error(`[harness-fe] refused to write ${label}: tags+metadata payload is ${size} bytes (limit ${META_EXTENSION_LIMIT_BYTES}).`);
-    }
-}
-function matchesType(event, type) {
-    if (!type)
-        return true;
-    if (Array.isArray(type))
-        return type.includes(event.t);
-    return event.t === type;
-}
-function matchesTimeRange(event, since, until) {
-    if (since !== undefined && event.ts < since)
-        return false;
-    if (until !== undefined && event.ts > until)
-        return false;
-    return true;
-}
-function dirSize(dir) {
-    if (!existsSync(dir))
-        return 0;
-    let total = 0;
-    for (const entry of readdirSync(dir, { withFileTypes: true })) {
-        const full = join(dir, entry.name);
-        if (entry.isDirectory())
-            total += dirSize(full);
-        else
-            total += statSync(full).size;
-    }
-    return total;
-}
-function rmrf(dir) {
-    if (!existsSync(dir))
-        return;
-    for (const entry of readdirSync(dir, { withFileTypes: true })) {
-        const full = join(dir, entry.name);
-        if (entry.isDirectory())
-            rmrf(full);
-        else
-            unlinkSync(full);
-    }
-    rmdirSync(dir);
-}
-// ─── JsonlStore ───────────────────────────────────────────────────────────────
-export class JsonlStore {
-    dataDir;
-    writeQueue = new WriteQueue();
-    /**
-     * In-memory index: sessionId → SessionMeta (rebuilt on startup, kept in sync).
-     * Enables O(1) session lookup without disk reads.
-     */
-    sessionIndex = new Map();
-    /**
-     * In-memory index: buildId → projectId (from openBuild / upsertBuild).
-     * Enables resolving project from buildId for legacy bridge compat.
-     */
-    buildIndex = new Map(); // buildId → projectId
-    constructor(dataDir) {
-        const serverStartTimestamp = Date.now();
-        this.dataDir = resolve(dataDir ?? DEFAULT_DATA_DIR);
-        ensureDir(this.dataDir);
-        this._rebuildIndexes(serverStartTimestamp);
-    }
-    /** Scan disk to rebuild in-memory indexes. Mark orphaned sessions (no endedAt). */
-    _rebuildIndexes(serverStartTimestamp) {
-        const sessionsDir = join(this.dataDir, 'sessions');
-        if (!existsSync(sessionsDir))
-            return;
-        let entries;
-        try {
-            entries = readdirSync(sessionsDir, { withFileTypes: true });
-        }
-        catch {
-            return;
-        }
-        for (const entry of entries) {
-            if (!entry.isDirectory())
-                continue;
-            const metaPath = join(sessionsDir, String(entry.name), 'meta.json');
-            const meta = readJson(metaPath);
-            if (!meta || !meta.id)
-                continue;
-            // Mark orphaned sessions (crashed daemons)
-            if (meta.endedAt === undefined) {
-                meta.endedAt = serverStartTimestamp;
-                try {
-                    writeJson(metaPath, meta);
-                }
-                catch (err) {
-                    console.error(`[JsonlStore] startup recovery: failed to write endedAt for session ${meta.id}:`, err);
-                }
-            }
-            this.sessionIndex.set(meta.id, meta);
-        }
-        // Rebuild buildIndex from projects/*/builds/*/meta.json
-        const projectsDir = join(this.dataDir, 'projects');
-        if (!existsSync(projectsDir))
-            return;
-        try {
-            for (const projEntry of readdirSync(projectsDir, { withFileTypes: true })) {
-                if (!projEntry.isDirectory())
-                    continue;
-                const buildsDir = join(projectsDir, String(projEntry.name), 'builds');
-                if (!existsSync(buildsDir))
-                    continue;
-                for (const buildEntry of readdirSync(buildsDir, { withFileTypes: true })) {
-                    if (!buildEntry.isDirectory())
-                        continue;
-                    const buildMeta = readJson(join(buildsDir, String(buildEntry.name), 'meta.json'));
-                    if (buildMeta?.id) {
-                        this.buildIndex.set(buildMeta.id, String(projEntry.name));
-                    }
-                }
-            }
-        }
-        catch {
-            // ignore
-        }
-    }
-    // ── Path helpers ──────────────────────────────────────────────────────
-    projectsDir() {
-        return join(this.dataDir, 'projects');
-    }
-    projectDir(projectId) {
-        return join(this.projectsDir(), sanitizeId(projectId));
-    }
-    buildDir(projectId, buildId) {
-        return join(this.projectDir(projectId), 'builds', sanitizeId(buildId));
-    }
-    visitorsDir() {
-        return join(this.dataDir, 'visitors');
-    }
-    visitorDir(visitorId) {
-        return join(this.visitorsDir(), sanitizeId(visitorId));
-    }
-    tabsDir() {
-        return join(this.dataDir, 'tabs');
-    }
-    tabDir(tabId) {
-        return join(this.tabsDir(), sanitizeId(tabId));
-    }
-    sessionsDir() {
-        return join(this.dataDir, 'sessions');
-    }
-    sessionDir(sessionId) {
-        return join(this.sessionsDir(), sanitizeId(sessionId));
-    }
-    sessionTimeline(sessionId) {
-        return join(this.sessionDir(sessionId), 'timeline.jsonl');
-    }
-    sessionRecording(sessionId) {
-        return join(this.sessionDir(sessionId), 'recording.jsonl');
-    }
-    exportsDir() {
-        return join(this.dataDir, 'exports');
-    }
-    exportIndex() {
-        return join(this.exportsDir(), 'index.jsonl');
-    }
-    exportEventsPath(exportId) {
-        return join(this.exportsDir(), `${sanitizeId(exportId)}.rrweb.json`);
-    }
-    // ── Build lifecycle ───────────────────────────────────────────────────
-    openBuild(projectId, patch = {}) {
-        const buildId = randomUUID().slice(0, 8);
-        this.upsertBuild(projectId, buildId, patch);
-        // Also ensure project meta exists
-        const projMetaPath = join(this.projectDir(projectId), 'meta.json');
-        if (!existsSync(projMetaPath)) {
-            this.upsertProject(projectId, {});
-        }
-        else {
-            // Touch lastActiveAt
-            const existing = readJson(projMetaPath);
-            if (existing) {
-                existing.lastActiveAt = Date.now();
-                writeJson(projMetaPath, existing);
-            }
-        }
-        return buildId;
-    }
-    closeBuild(buildId, closedAt) {
-        const projectId = this.buildIndex.get(buildId);
-        if (!projectId)
-            return;
-        const metaPath = join(this.buildDir(projectId, buildId), 'meta.json');
-        const meta = readJson(metaPath);
-        if (!meta)
-            return;
-        meta.endedAt = closedAt ?? Date.now();
-        writeJson(metaPath, meta);
-    }
-    // ── Tab lifecycle ─────────────────────────────────────────────────────
-    upsertTab(tabId, patch) {
-        const dir = this.tabDir(tabId);
-        ensureDir(dir);
-        const metaPath = join(dir, 'meta.json');
-        const existing = readJson(metaPath);
-        const merged = {
-            connectedAt: Date.now(),
-            ...existing,
-            ...patch,
-            id: tabId,
-        };
-        writeJson(metaPath, merged);
-        return merged;
-    }
-    getTab(tabId) {
-        return readJson(join(this.tabDir(tabId), 'meta.json')) ?? undefined;
-    }
-    closeTab(tabId, disconnectedAt) {
-        const metaPath = join(this.tabDir(tabId), 'meta.json');
-        const meta = readJson(metaPath);
-        if (!meta)
-            return;
-        meta.disconnectedAt = disconnectedAt ?? Date.now();
-        writeJson(metaPath, meta);
-    }
-    // ── Session lifecycle (pageload) ──────────────────────────────────────
-    upsertSession(sessionId, meta) {
-        const dir = this.sessionDir(sessionId);
-        ensureDir(dir);
-        const metaPath = join(dir, 'meta.json');
-        const existing = readJson(metaPath);
-        // Merge participants: add new ones not already in the list
-        const existingParticipants = existing?.participants ?? [];
-        const incomingParticipants = meta.participants ?? [];
-        const merged = {
-            participants: [],
-            ...existing,
-            ...meta,
-            id: sessionId,
-            // Write-once: first principal to open the session owns it.
-            createdBy: existing?.createdBy ?? meta.createdBy,
-        };
-        // Reset participants — we'll rebuild via dedup loop below
-        merged.participants = [];
-        // Build merged participants list
-        const seen = new Set();
-        for (const p of existingParticipants) {
-            const key = `${p.projectId}::${p.buildId ?? ''}`;
-            if (!seen.has(key)) {
-                seen.add(key);
-                merged.participants.push(p);
-            }
-        }
-        for (const p of incomingParticipants) {
-            const key = `${p.projectId}::${p.buildId ?? ''}`;
-            if (!seen.has(key)) {
-                seen.add(key);
-                merged.participants.push(p);
-            }
-        }
-        writeJson(metaPath, merged);
-        this.sessionIndex.set(sessionId, merged);
-        return merged;
-    }
-    closeSession(sessionId, endedAt) {
-        const metaPath = join(this.sessionDir(sessionId), 'meta.json');
-        const meta = readJson(metaPath);
-        if (!meta)
-            return;
-        meta.endedAt = endedAt ?? Date.now();
-        writeJson(metaPath, meta);
-        // Update in-memory index
-        const cached = this.sessionIndex.get(sessionId);
-        if (cached) {
-            cached.endedAt = meta.endedAt;
-        }
-    }
-    getSession(sessionId) {
-        // Check in-memory index first
-        const cached = this.sessionIndex.get(sessionId);
-        if (cached)
-            return cached;
-        // Fall back to disk
-        const meta = readJson(join(this.sessionDir(sessionId), 'meta.json'));
-        if (meta) {
-            this.sessionIndex.set(sessionId, meta);
-        }
-        return meta ?? undefined;
-    }
-    listSessions(opts = {}) {
-        const { tabId, projectId, buildId, limit = 50 } = opts;
-        const sessionsDir = this.sessionsDir();
-        if (!existsSync(sessionsDir))
-            return [];
-        const sessions = [];
-        try {
-            for (const entry of readdirSync(sessionsDir, { withFileTypes: true })) {
-                if (!entry.isDirectory())
-                    continue;
-                const meta = readJson(join(sessionsDir, String(entry.name), 'meta.json'));
-                if (!meta)
-                    continue;
-                // Update index
-                this.sessionIndex.set(meta.id, meta);
-                // Apply filters
-                if (tabId && meta.tabId !== tabId)
-                    continue;
-                if (projectId && !meta.participants.some((p) => p.projectId === projectId))
-                    continue;
-                if (buildId && !meta.participants.some((p) => p.buildId === buildId))
-                    continue;
-                sessions.push(meta);
-            }
-        }
-        catch {
-            // ignore scan errors
-        }
-        return sessions.sort((a, b) => b.startedAt - a.startedAt).slice(0, limit);
-    }
-    // ── Write ─────────────────────────────────────────────────────────────
-    appendEvent(sessionId, event) {
-        if (!this.getSession(sessionId))
-            return;
-        const line = JSON.stringify(event);
-        if (Buffer.byteLength(line, 'utf-8') > MAX_EVENT_BYTES) {
-            process.stderr.write(`[harness-fe] dropping oversized event (${Buffer.byteLength(line, 'utf-8')} bytes > ${MAX_EVENT_BYTES}) — type=${event.t}\n`);
-            return;
-        }
-        this.writeQueue.enqueue(this.sessionTimeline(sessionId), sessionId, line);
-    }
-    appendEventBatch(sessionId, events) {
-        if (!events.length)
-            return;
-        if (!this.getSession(sessionId))
-            return;
-        for (const event of events) {
-            const line = JSON.stringify(event);
-            if (Buffer.byteLength(line, 'utf-8') > MAX_EVENT_BYTES) {
-                process.stderr.write(`[harness-fe] dropping oversized event in batch (${Buffer.byteLength(line, 'utf-8')} bytes) — type=${event.t}\n`);
-                continue;
-            }
-            this.writeQueue.enqueue(this.sessionTimeline(sessionId), sessionId, line);
-        }
-    }
-    appendRecording(sessionId, chunk) {
-        if (!this.getSession(sessionId))
-            return;
-        const line = Array.isArray(chunk) ? { ts: Date.now(), events: chunk } : chunk;
-        const serialized = JSON.stringify(line);
-        if (Buffer.byteLength(serialized, 'utf-8') > MAX_RECORDING_CHUNK_BYTES) {
-            process.stderr.write(`[harness-fe] dropping oversized rrweb chunk (${Buffer.byteLength(serialized, 'utf-8')} bytes > ${MAX_RECORDING_CHUNK_BYTES})\n`);
-            return;
-        }
-        const target = this.sessionRecording(sessionId);
-        ensureDir(this.sessionDir(sessionId));
-        this.writeQueue.enqueue(target, sessionId, serialized);
-    }
-    writeNote(projectId, key, value) {
-        const projDir = this.projectDir(projectId);
-        ensureDir(projDir);
-        appendJsonl(join(projDir, 'notes.jsonl'), { ts: Date.now(), key, value });
-    }
-    // ── Project metadata ───────────────────────────────────────────────────
-    upsertProject(projectId, patch) {
-        const projDir = this.projectDir(projectId);
-        ensureDir(projDir);
-        const metaPath = join(projDir, 'meta.json');
-        const existing = readJson(metaPath);
-        // Cycle detection
-        if (patch.parentProjectId !== undefined && patch.parentProjectId !== null) {
-            if (patch.parentProjectId === projectId) {
-                throw new Error(`[harness-fe] refused to set parentProjectId=${projectId} on itself`);
-            }
-            const visited = new Set();
-            let cursor = patch.parentProjectId;
-            while (cursor) {
-                if (cursor === projectId) {
-                    throw new Error(`[harness-fe] refused to create parent-project cycle: ${projectId} → … → ${projectId}`);
-                }
-                if (visited.has(cursor))
-                    break;
-                visited.add(cursor);
-                const ancestor = readJson(join(this.projectDir(cursor), 'meta.json')) ?? undefined;
-                cursor = ancestor?.parentProjectId;
-            }
-        }
-        const merged = {
-            ...existing,
-            ...patch,
-            id: projectId,
-            createdAt: existing?.createdAt ?? Date.now(),
-            lastActiveAt: Date.now(),
-            // Write-once: the first principal to create the project owns it.
-            createdBy: existing?.createdBy ?? patch.createdBy,
-        };
-        enforceExtensionBudget(merged, `project ${projectId}`);
-        writeJson(metaPath, merged);
-        return merged;
-    }
-    getProject(projectId) {
-        return readJson(join(this.projectDir(projectId), 'meta.json')) ?? undefined;
-    }
-    listProjects() {
-        const projectsDir = this.projectsDir();
-        if (!existsSync(projectsDir))
-            return [];
-        const projects = [];
-        try {
-            for (const entry of readdirSync(projectsDir, { withFileTypes: true })) {
-                if (!entry.isDirectory())
-                    continue;
-                const meta = readJson(join(projectsDir, String(entry.name), 'meta.json'));
-                if (meta)
-                    projects.push(meta);
-            }
-        }
-        catch {
-            // ignore
-        }
-        return projects.sort((a, b) => b.lastActiveAt - a.lastActiveAt);
-    }
-    // ── Visitor metadata (0.5+) ─────────────────────────────────────────────
-    upsertVisitor(visitorId, patch) {
-        const dir = this.visitorDir(visitorId);
-        ensureDir(dir);
-        const metaPath = join(dir, 'meta.json');
-        const existing = readJson(metaPath);
-        const now = patch.seenAt ?? Date.now();
-        const tabIds = lruAppend(existing?.tabIds, patch.addTabId, 50);
-        const projectIds = lruAppend(existing?.projectIds, patch.addProjectId, 50);
-        const merged = {
-            id: visitorId,
-            // userId: prefer fresh non-empty value; otherwise preserve existing
-            userId: patch.userId && patch.userId.length > 0 ? patch.userId : existing?.userId,
-            firstSeenAt: existing?.firstSeenAt ?? now,
-            lastSeenAt: now,
-            sessionCount: (existing?.sessionCount ?? 0) + (patch.incrementSession ? 1 : 0),
-            tabIds,
-            projectIds,
-            lastEnv: patch.lastEnv ?? existing?.lastEnv,
-        };
-        writeJson(metaPath, merged);
-        return merged;
-    }
-    getVisitor(visitorId) {
-        return readJson(join(this.visitorDir(visitorId), 'meta.json')) ?? undefined;
-    }
-    listVisitors(opts = {}) {
-        const dir = this.visitorsDir();
-        if (!existsSync(dir))
-            return [];
-        const out = [];
-        try {
-            for (const entry of readdirSync(dir, { withFileTypes: true })) {
-                if (!entry.isDirectory())
-                    continue;
-                const meta = readJson(join(dir, String(entry.name), 'meta.json'));
-                if (!meta)
-                    continue;
-                if (opts.projectId && !meta.projectIds.includes(opts.projectId))
-                    continue;
-                out.push(meta);
-            }
-        }
-        catch {
-            // ignore
-        }
-        out.sort((a, b) => b.lastSeenAt - a.lastSeenAt);
-        return opts.limit ? out.slice(0, opts.limit) : out;
-    }
-    // ── Build metadata ─────────────────────────────────────────────────────
-    upsertBuild(projectId, buildId, patch) {
-        const dir = this.buildDir(projectId, buildId);
-        ensureDir(dir);
-        const metaPath = join(dir, 'meta.json');
-        const existing = readJson(metaPath);
-        const merged = {
-            ...existing,
-            ...patch,
-            id: buildId,
-            projectId,
-            builtAt: existing?.builtAt ?? Date.now(),
-        };
-        enforceExtensionBudget(merged, `build ${projectId}/${buildId}`);
-        writeJson(metaPath, merged);
-        this.buildIndex.set(buildId, projectId);
-        return merged;
-    }
-    getBuild(projectId, buildId) {
-        return readJson(join(this.buildDir(projectId, buildId), 'meta.json')) ?? undefined;
-    }
-    listBuilds(projectId, limit = 50) {
-        const buildsDir = join(this.projectDir(projectId), 'builds');
-        if (!existsSync(buildsDir))
-            return [];
-        const builds = [];
-        try {
-            for (const entry of readdirSync(buildsDir, { withFileTypes: true })) {
-                if (!entry.isDirectory())
-                    continue;
-                const meta = readJson(join(buildsDir, String(entry.name), 'meta.json'));
-                if (meta)
-                    builds.push(meta);
-            }
-        }
-        catch {
-            // ignore
-        }
-        return builds.sort((a, b) => b.builtAt - a.builtAt).slice(0, limit);
-    }
-    // ── Project tree ───────────────────────────────────────────────────────
-    getProjectTree(rootId) {
-        const all = this.listProjects();
-        const byParent = new Map();
-        for (const p of all) {
-            const parent = p.parentProjectId;
-            if (!parent)
-                continue;
-            const arr = byParent.get(parent) ?? [];
-            arr.push(p);
-            byParent.set(parent, arr);
-        }
-        const sortByLabel = (a, b) => (a.displayName ?? a.id).localeCompare(b.displayName ?? b.id);
-        const seedRoots = rootId
-            ? all.filter((p) => p.id === rootId)
-            : all.filter((p) => !p.parentProjectId);
-        const nodeOf = new Map();
-        const queue = [...seedRoots];
-        const visited = new Set();
-        while (queue.length > 0) {
-            const p = queue.shift();
-            if (visited.has(p.id))
-                continue;
-            visited.add(p.id);
-            nodeOf.set(p.id, { id: p.id, displayName: p.displayName, tags: p.tags, children: [] });
-            const kids = (byParent.get(p.id) ?? []).slice().sort(sortByLabel);
-            for (const k of kids)
-                queue.push(k);
-        }
-        for (const p of all) {
-            if (!nodeOf.has(p.id) || !p.parentProjectId)
-                continue;
-            const parent = nodeOf.get(p.parentProjectId);
-            const me = nodeOf.get(p.id);
-            if (parent && me)
-                parent.children.push(me);
-        }
-        return seedRoots
-            .slice()
-            .sort(sortByLabel)
-            .map((p) => nodeOf.get(p.id))
-            .filter((n) => Boolean(n));
-    }
-    // ── Read ──────────────────────────────────────────────────────────────
-    tail(sessionId, opts = {}) {
-        if (!this.getSession(sessionId))
-            return [];
-        const filePath = this.sessionTimeline(sessionId);
-        const n = opts.n ?? 50;
-        const multiplier = opts.type || opts.since || opts.until || opts.projectId ? 5 : 1;
-        const rawLines = readLastNLines(filePath, n * multiplier);
-        const events = [];
-        for (const line of rawLines) {
-            const event = parseEvent(line);
-            if (!event)
-                continue;
-            if (!matchesType(event, opts.type))
-                continue;
-            if (!matchesTimeRange(event, opts.since, opts.until))
-                continue;
-            if (opts.projectId && event.projectId !== opts.projectId)
-                continue;
-            events.push(event);
-        }
-        return events.slice(-n);
-    }
-    search(sessionId, query, opts = {}) {
-        if (!this.getSession(sessionId))
-            return [];
-        const filePath = this.sessionTimeline(sessionId);
-        const limit = opts.limit ?? 50;
-        const lowerQuery = query.toLowerCase();
-        const results = [];
-        for (const line of readAllLines(filePath)) {
-            if (!line.toLowerCase().includes(lowerQuery))
-                continue;
-            const event = parseEvent(line);
-            if (!event)
-                continue;
-            if (!matchesType(event, opts.type))
-                continue;
-            results.push(event);
-            if (results.length >= limit)
-                break;
-        }
-        return results;
-    }
-    listRecordings(sessionId) {
-        if (!this.getSession(sessionId))
-            return [];
-        const recPath = this.sessionRecording(sessionId);
-        const chunks = [];
-        const sessionMeta = this.getSession(sessionId);
-        const tabId = sessionMeta?.tabId ?? '';
-        readAllLines(recPath).forEach((line, index) => {
-            const chunk = parseRecordingChunkLine(line, tabId, 0, index);
-            if (!chunk)
-                return;
-            chunks.push({
-                chunkId: chunk.chunkId,
-                tabId: chunk.tabId,
-                startTs: chunk.startTs,
-                endTs: chunk.endTs,
-                eventCount: chunk.eventCount,
-            });
-        });
-        return chunks.sort((a, b) => a.startTs - b.startTs);
-    }
-    sliceRecordings(sessionId, since, until) {
-        if (!this.getSession(sessionId))
-            return [];
-        const recPath = this.sessionRecording(sessionId);
-        const sessionMeta = this.getSession(sessionId);
-        const tabId = sessionMeta?.tabId ?? '';
-        const chunks = [];
-        readAllLines(recPath).forEach((line, index) => {
-            const chunk = parseRecordingChunkLine(line, tabId, 0, index);
-            if (!chunk)
-                return;
-            if (chunk.endTs < since || chunk.startTs > until)
-                return;
-            chunks.push({
-                chunkId: chunk.chunkId,
-                tabId: chunk.tabId,
-                startTs: chunk.startTs,
-                endTs: chunk.endTs,
-                eventCount: chunk.eventCount,
-                events: chunk.events,
-            });
-        });
-        return chunks.sort((a, b) => a.startTs - b.startTs);
-    }
-    writeExport(input) {
-        // Determine projectId from session participants
-        const session = this.getSession(input.sessionId);
-        const projectId = session?.participants[0]?.projectId ?? 'unknown';
-        const exportId = `exp_${randomUUID().slice(0, 12)}`;
-        const exportDir = this.exportsDir();
-        ensureDir(exportDir);
-        const eventsPath = this.exportEventsPath(exportId);
-        const payload = JSON.stringify(input.events);
-        writeFileSync(eventsPath, payload, 'utf-8');
-        const meta = {
-            exportId,
-            projectId,
-            sessionId: input.sessionId,
-            tabId: input.tabId,
-            label: input.label,
-            since: input.since,
-            until: input.until,
-            startTs: input.startTs,
-            endTs: input.endTs,
-            chunkCount: input.chunkCount,
-            eventCount: input.events.length,
-            bytes: Buffer.byteLength(payload, 'utf-8'),
-            createdAt: Date.now(),
-        };
-        appendJsonl(this.exportIndex(), meta);
-        return meta;
-    }
-    getExport(exportId) {
-        const indexPath = this.exportIndex();
-        if (!existsSync(indexPath))
-            return undefined;
-        let latest;
-        for (const line of readAllLines(indexPath)) {
-            try {
-                const meta = JSON.parse(line);
-                if (meta?.exportId === exportId)
-                    latest = meta;
-            }
-            catch {
-                /* swallow */
-            }
-        }
-        return latest;
-    }
-    readExportEvents(exportId) {
-        const eventsPath = this.exportEventsPath(exportId);
-        if (!existsSync(eventsPath))
-            return undefined;
-        try {
-            const parsed = JSON.parse(readFileSync(eventsPath, 'utf-8'));
-            return Array.isArray(parsed) ? parsed : undefined;
-        }
-        catch {
-            return undefined;
-        }
-    }
-    listExports(projectId, limit) {
-        const indexPath = this.exportIndex();
-        if (!existsSync(indexPath))
-            return [];
-        const seen = new Map();
-        for (const line of readAllLines(indexPath)) {
-            try {
-                const meta = JSON.parse(line);
-                if (meta?.exportId && (projectId === 'all' || meta.projectId === projectId)) {
-                    seen.set(meta.exportId, meta);
-                }
-            }
-            catch {
-                /* swallow */
-            }
-        }
-        const metas = [];
-        for (const meta of seen.values())
-            metas.push(meta);
-        metas.sort((a, b) => b.createdAt - a.createdAt);
-        return typeof limit === 'number' ? metas.slice(0, limit) : metas;
-    }
-    summary(sessionId) {
-        const session = this.getSession(sessionId);
-        const counts = {};
-        let lastError;
-        let lastActivity;
-        const filePath = this.sessionTimeline(sessionId);
-        for (const line of readAllLines(filePath)) {
-            const event = parseEvent(line);
-            if (!event)
-                continue;
-            counts[event.t] = (counts[event.t] ?? 0) + 1;
-            if (event.t === 'err')
-                lastError = event;
-            if (!lastActivity || event.ts > lastActivity)
-                lastActivity = event.ts;
-        }
-        const tabs = session ? [session.tabId].filter(Boolean) : [];
-        const fallbackSession = {
-            id: sessionId,
-            tabId: 'unknown',
-            startedAt: 0,
-            participants: [],
-        };
-        return {
-            session: session ?? fallbackSession,
-            counts,
-            lastError,
-            lastActivity,
-            tabs,
-        };
-    }
-    listNotes(projectId) {
-        const notesPath = join(this.projectDir(projectId), 'notes.jsonl');
-        const notes = [];
-        for (const line of readAllLines(notesPath)) {
-            const parsed = parseEvent(line);
-            if (parsed?.key)
-                notes.push(parsed);
-        }
-        const latest = new Map();
-        for (const note of notes) {
-            const existing = latest.get(note.key);
-            if (!existing || note.ts >= existing.ts)
-                latest.set(note.key, note);
-        }
-        return [...latest.values()].sort((a, b) => b.ts - a.ts);
-    }
-    // ── Maintenance ───────────────────────────────────────────────────────
-    purge(policy = {}) {
-        // Normalize aliases
-        const maxSessions = policy.maxSessions ?? policy.maxSessionsPerProject ?? DEFAULT_RETENTION.maxSessions;
-        const maxAgeDays = policy.maxAgeDays ?? DEFAULT_RETENTION.maxAgeDays;
-        const recordingRetentionDays = policy.recordingRetentionDays ?? DEFAULT_RETENTION.recordingRetentionDays;
-        const maxChunks = policy.maxRecordingChunksPerSession ?? policy.maxRecordingChunksPerTab ?? DEFAULT_RETENTION.maxRecordingChunksPerSession;
-        const maxBytes = policy.maxRecordingBytesPerSession ?? policy.maxRecordingBytesPerTab ?? DEFAULT_RETENTION.maxRecordingBytesPerSession;
-        const preserveMarkedChunks = policy.preserveMarkedChunks ?? DEFAULT_RETENTION.preserveMarkedChunks;
-        const maxExportsPerProject = policy.maxExportsPerProject ?? DEFAULT_RETENTION.maxExportsPerProject;
-        const maxExportBytesPerProject = policy.maxExportBytesPerProject ?? DEFAULT_RETENTION.maxExportBytesPerProject;
-        const maxBuildsPerProject = policy.maxBuildsPerProject ?? DEFAULT_RETENTION.maxBuildsPerProject;
-        const now = Date.now();
-        const maxAge = maxAgeDays * 86400000;
-        const recMaxAge = recordingRetentionDays * 86400000;
-        let sessionsDeleted = 0;
-        let recordingsDeleted = 0;
-        let exportsDeleted = 0;
-        let bytesFreed = 0;
-        let buildsDeleted = 0;
-        const sessionsDir = this.sessionsDir();
-        if (existsSync(sessionsDir)) {
-            const allSessions = this.listSessions({ limit: Number.MAX_SAFE_INTEGER });
-            // Delete sessions older than maxAge
-            for (const sess of allSessions) {
-                const age = now - sess.startedAt;
-                if (age > maxAge) {
-                    const dir = this.sessionDir(sess.id);
-                    const size = dirSize(dir);
-                    rmrf(dir);
-                    this.sessionIndex.delete(sess.id);
-                    bytesFreed += size;
-                    sessionsDeleted++;
-                }
-            }
-            // Keep only the most recent maxSessions
-            const remaining = this.listSessions({ limit: Number.MAX_SAFE_INTEGER });
-            if (remaining.length > maxSessions) {
-                const toDelete = remaining.slice(maxSessions);
-                for (const sess of toDelete) {
-                    const dir = this.sessionDir(sess.id);
-                    const size = dirSize(dir);
-                    rmrf(dir);
-                    this.sessionIndex.delete(sess.id);
-                    bytesFreed += size;
-                    sessionsDeleted++;
-                }
-            }
-            // Trim recording data per session
-            for (const sess of this.listSessions({ limit: Number.MAX_SAFE_INTEGER })) {
-                const recPath = this.sessionRecording(sess.id);
-                if (!existsSync(recPath))
-                    continue;
-                const timelinePath = this.sessionTimeline(sess.id);
-                const result = this.pruneRecordingFile(recPath, timelinePath, now, recMaxAge, maxChunks, maxBytes, preserveMarkedChunks);
-                bytesFreed += result.bytesFreed;
-                recordingsDeleted += result.chunksDeleted;
-            }
-        }
-        // Trim exports
-        const exportResult = this.pruneExports(maxExportsPerProject, maxExportBytesPerProject);
-        exportsDeleted += exportResult.exportsDeleted;
-        bytesFreed += exportResult.bytesFreed;
-        // Trim builds per project
-        for (const proj of this.listProjects()) {
-            const allBuilds = this.listBuilds(proj.id, Number.MAX_SAFE_INTEGER);
-            if (allBuilds.length > maxBuildsPerProject) {
-                const stale = allBuilds.slice(maxBuildsPerProject);
-                for (const b of stale) {
-                    const dir = this.buildDir(proj.id, b.id);
-                    const size = dirSize(dir);
-                    rmrf(dir);
-                    this.buildIndex.delete(b.id);
-                    bytesFreed += size;
-                    buildsDeleted++;
-                }
-            }
-        }
-        return { sessionsDeleted, recordingsDeleted, exportsDeleted, bytesFreed, buildsDeleted };
-    }
-    pruneExports(maxExports, maxBytes) {
-        // Collect all exports across all projects
-        const indexPath = this.exportIndex();
-        if (!existsSync(indexPath))
-            return { exportsDeleted: 0, bytesFreed: 0 };
-        // Group by project
-        const byProject = new Map();
-        for (const line of readAllLines(indexPath)) {
-            try {
-                const meta = JSON.parse(line);
-                if (!meta?.exportId)
-                    continue;
-                const arr = byProject.get(meta.projectId) ?? [];
-                arr.push(meta);
-                byProject.set(meta.projectId, arr);
-            }
-            catch {
-                /* swallow */
-            }
-        }
-        let totalDeleted = 0;
-        let totalFreed = 0;
-        const keepIds = new Set();
-        for (const [, exports] of byProject) {
-            exports.sort((a, b) => b.createdAt - a.createdAt);
-            let runningBytes = 0;
-            for (const meta of exports) {
-                const fits = keepIds.size < maxExports && runningBytes + meta.bytes <= maxBytes;
-                if (fits) {
-                    keepIds.add(meta.exportId);
-                    runningBytes += meta.bytes;
-                }
-                else {
-                    // Delete this export's events file
-                    const eventsPath = this.exportEventsPath(meta.exportId);
-                    if (existsSync(eventsPath)) {
-                        const size = statSync(eventsPath).size;
-                        try {
-                            unlinkSync(eventsPath);
-                            totalFreed += size;
-                        }
-                        catch { /* swallow */ }
-                    }
-                    totalDeleted++;
-                }
-            }
-        }
-        if (totalDeleted > 0) {
-            // Rewrite index keeping only surviving entries
-            const allLines = readAllLines(indexPath);
-            const kept = allLines.filter((line) => {
-                try {
-                    const meta = JSON.parse(line);
-                    return keepIds.has(meta.exportId);
-                }
-                catch {
-                    return false;
-                }
-            });
-            if (kept.length === 0) {
-                try {
-                    unlinkSync(indexPath);
-                }
-                catch { /* swallow */ }
-            }
-            else {
-                writeFileSync(indexPath, kept.join('\n') + '\n', 'utf-8');
-            }
-        }
-        return { exportsDeleted: totalDeleted, bytesFreed: totalFreed };
-    }
-    /**
-     * Flush all pending WriteQueue entries to disk. Used in tests.
-     */
-    async flush() {
-        await this.writeQueue.drain();
-    }
-    async close() {
-        try {
-            await this.writeQueue.drain();
-        }
-        catch (err) {
-            console.error('[JsonlStore] close: drain failed:', err);
-        }
-    }
-    pruneRecordingFile(recPath, timelinePath, now, recMaxAge, maxChunks, maxBytesLimit, preserveMarkedChunks) {
-        const lines = readAllLines(recPath);
-        if (lines.length === 0)
-            return { chunksDeleted: 0, bytesFreed: 0 };
-        const fallbackAgeTs = statSync(recPath).mtimeMs;
-        const markerTimestamps = this.readMarkerTimestamps(timelinePath);
-        const chunks = [];
-        lines.forEach((line, index) => {
-            const chunk = parseRecordingChunkLine(line, '', fallbackAgeTs, index);
-            if (!chunk)
-                return;
-            chunk.marked = markerTimestamps.some((ts) => ts >= chunk.startTs && ts <= chunk.endTs);
-            chunks.push(chunk);
-        });
-        if (chunks.length === 0)
-            return { chunksDeleted: 0, bytesFreed: 0 };
-        const removed = new Set();
-        for (const chunk of chunks) {
-            if (now - chunk.ageTs > recMaxAge)
-                removed.add(chunk.chunkId);
-        }
-        let kept = chunks.filter((chunk) => !removed.has(chunk.chunkId));
-        const chooseRemovalCandidate = () => {
-            if (kept.length === 0)
-                return undefined;
-            const sorted = [...kept].sort((a, b) => a.startTs - b.startTs);
-            if (!preserveMarkedChunks)
-                return sorted[0];
-            return sorted.find((chunk) => !chunk.marked) ?? sorted[0];
-        };
-        while (kept.length > maxChunks) {
-            const candidate = chooseRemovalCandidate();
-            if (!candidate)
-                break;
-            removed.add(candidate.chunkId);
-            kept = kept.filter((chunk) => chunk.chunkId !== candidate.chunkId);
-        }
-        let totalBytes = kept.reduce((sum, chunk) => sum + chunk.bytes, 0);
-        while (totalBytes > maxBytesLimit) {
-            const candidate = chooseRemovalCandidate();
-            if (!candidate)
-                break;
-            removed.add(candidate.chunkId);
-            kept = kept.filter((chunk) => chunk.chunkId !== candidate.chunkId);
-            totalBytes = kept.reduce((sum, chunk) => sum + chunk.bytes, 0);
-        }
-        if (removed.size === 0)
-            return { chunksDeleted: 0, bytesFreed: 0 };
-        const bytesFreed = chunks
-            .filter((chunk) => removed.has(chunk.chunkId))
-            .reduce((sum, chunk) => sum + chunk.bytes, 0);
-        if (kept.length === 0) {
-            unlinkSync(recPath);
-        }
-        else {
-            writeFileSync(recPath, `${kept.map((chunk) => chunk.line).join('\n')}\n`, 'utf-8');
-        }
-        return { chunksDeleted: removed.size, bytesFreed };
-    }
-    readMarkerTimestamps(timelinePath) {
-        const timestamps = [];
-        for (const line of readAllLines(timelinePath)) {
-            const event = parseEvent(line);
-            if (!event || event.t !== 'rrweb:marker')
-                continue;
-            timestamps.push(event.ts);
-        }
-        return timestamps;
-    }
-}
-// ─── Helpers ──────────────────────────────────────────────────────────────────
-/** Sanitize a string for use as a directory name. */
-export function sanitizeId(id) {
-    return id.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 64);
-}