Import src/host-tabs.ts

This commit is contained in:
QQ 2026-11-11 22:34:08 +08:00
parent c72ba17ea5
commit 3282274599
1 changed files with 184 additions and 0 deletions

184
src/host-tabs.ts Normal file
View File

@ -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<string, unknown>
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<string, unknown>
// 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<string>()
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<TabsDocument | null> {
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<void> {
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],
}
}