diff --git a/src/host-tabs.ts b/src/host-tabs.ts new file mode 100644 index 0000000..55e1f46 --- /dev/null +++ b/src/host-tabs.ts @@ -0,0 +1,184 @@ +/** + * Host-side persistence for the session-tab strip. + * + * Why the host and not the browser: **browser storage is scoped to the origin, + * and the origin includes the PORT.** `dsh web` / `dsh test` / the desktop shell + * each pick a port, and a different port is a different origin, so BOTH + * `localStorage` and `sessionStorage` start empty on the next launch. A tab list + * kept there survives a reload only by luck (same port) and is lost on the next + * start. + * + * Host storage has no such problem: one JSON sidecar under `$DSH_HOME`, keyed by + * nothing but the plugin, so every port and every session reads the same file. + * That file IS the strip's memory — it is returned as-is, with no browser-session + * marker gating it. + * + * (An earlier version DID gate on a `sessionKey` kept in `sessionStorage`, to + * express "clear when the browser closes". That cannot work here: the marker is + * itself per-origin, so a port change erased it, the host saw an unfamiliar + * marker, and every restart silently discarded the user's tabs. Persistence the + * user can rely on beats a tidy-up nobody asked for.) + * + * Writes are atomic (temp file + fsync + rename), matching the manual overlay. + */ +import { mkdir, open, readFile, rename, unlink } from 'node:fs/promises' +import { dirname, resolve } from 'node:path' +import { homedir } from 'node:os' + +/** One persisted tab. */ +export interface PersistedTab { + /** Session id the tab points at. */ + readonly sessionId: string + /** Arrival key (React list identity). */ + readonly order: number + /** Pinned tabs are restored at the front of the strip. */ + readonly pinned?: boolean + /** A label the user typed for the tab itself (absent = follow the session). */ + readonly title?: string +} + +/** The persisted document. */ +export interface TabsDocument { + /** + * Shape version. + * + * 1 = `{sessionId, order}` only (what the shipped build writes); 2 adds the + * optional `pinned` / `title` per tab. A version-1 file is READ as version 2 + * with every tab unpinned and untitled — that is exactly what it meant — and + * the next write upgrades it. The two shapes are field-compatible, so no + * conversion step exists: an older build reading a version-2 file would drop + * the extra flags and keep working, which is why this stayed a tolerance + * instead of a hard rejection. + */ + readonly version: 2 + /** Arrival counter, kept ahead of every tab's own order. */ + readonly order: number + readonly tabs: readonly PersistedTab[] +} + +/** Default location: `$DSH_HOME/workspace-groups.tabs.json`. */ +export function defaultTabsPath(): string { + const home = process.env.DSH_HOME !== undefined && process.env.DSH_HOME !== '' + ? process.env.DSH_HOME + : resolve(homedir(), '.dsh') + return resolve(home, 'workspace-groups.tabs.json') +} + +/** + * Normalize one tab row (used by both the file reader and the PUT body check, so + * the two can never drift). + * + * @param entry - one element of a stored/`posted` `tabs` array. + * @returns the tab, or null when the row is unusable. + */ +export function parsePersistedTab(entry: unknown): PersistedTab | null { + if (typeof entry !== 'object' || entry === null) return null + const row = entry as Record + if (typeof row.sessionId !== 'string' || row.sessionId === '') return null + if (typeof row.order !== 'number' || !Number.isFinite(row.order)) return null + const pinned = row.pinned === true + const title = typeof row.title === 'string' && row.title.trim() !== '' ? row.title.trim() : undefined + return { + sessionId: row.sessionId, + order: row.order, + ...(pinned ? { pinned: true } : {}), + ...(title !== undefined ? { title } : {}), + } +} + +/** + * Parse + shape-validate a tabs document. + * + * Tolerant on purpose: this file is a display cache, so a malformed one must + * read as "no tabs" rather than break the strip. Individual bad rows are dropped + * and the rest kept. Unknown fields (such as the `sessionKey` an older build + * wrote) are ignored, so an existing file keeps working across the change. + * + * @param raw - parsed JSON value. + * @returns the normalized document, or null when it is unusable. + */ +export function parseTabsDocument(raw: unknown): TabsDocument | null { + if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return null + const source = raw as Record + // 1 and 2 are field-compatible; anything else is a shape this build cannot + // reason about and is discarded rather than guessed at. + if (source.version !== 1 && source.version !== 2) return null + if (typeof source.order !== 'number' || !Number.isFinite(source.order)) return null + if (!Array.isArray(source.tabs)) return null + const tabs: PersistedTab[] = [] + const seen = new Set() + for (const entry of source.tabs) { + const tab = parsePersistedTab(entry) + if (tab === null) continue + if (seen.has(tab.sessionId)) continue + seen.add(tab.sessionId) + tabs.push(tab) + } + return { + version: 2, + order: source.order, + tabs, + } +} + +/** + * Read the tabs document. + * + * A missing file is not an error (first run). A corrupt one is reported as null + * so the caller starts empty, and the next write repairs the file. + * + * @param path - sidecar path. + * @returns the document, or null when absent/unusable. + */ +export async function readTabsDocument(path: string): Promise { + let text: string + try { + text = await readFile(path, 'utf8') + } catch (error) { + if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null + throw error + } + try { + return parseTabsDocument(JSON.parse(text)) + } catch { + return null + } +} + +/** + * Write the tabs document atomically. + * @param path - sidecar path. + * @param document - document to store. + */ +export async function writeTabsDocument(path: string, document: TabsDocument): Promise { + await mkdir(dirname(path), { recursive: true }) + const temp = `${path}.${process.pid}.${Date.now()}.tmp` + const body = `${JSON.stringify(document, null, 2)}\n` + const handle = await open(temp, 'w') + try { + await handle.writeFile(body, 'utf8') + await handle.sync() + } finally { + await handle.close() + } + try { + await rename(temp, path) + } catch (error) { + await unlink(temp).catch(() => {}) + throw error + } +} + +/** + * Build the document to persist. + * @param state - the client's current strip and its arrival counter. + * @returns the document to write. + */ +export function documentForTabs(state: { order: number; tabs: readonly PersistedTab[] }): TabsDocument { + const highest = state.tabs.reduce((max, tab) => Math.max(max, tab.order), 0) + return { + version: 2, + order: Math.max(state.order, highest), + tabs: [...state.tabs], + } +}