@shawnstack/quickforge 1.7.10 → 1.7.11

package/server/session-state-import.mjs

@@ -0,0 +1,157 @@
+import { getSqliteStorage } from './sqlite/database.mjs'
+import { createSessionStateRepository } from './sqlite/session-state-repository.mjs'
+import { logger as defaultLogger } from './utils/logger.mjs'
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype
+}
+
+// Bucket validation mirrors session-state-cutover.mjs's normalizeBucket: the
+// importer walks the same physical JSON tree the cutover source did.
+function normalizeBucket(raw) {
+  if (raw.scope === 'global') {
+    if (raw.projectId !== undefined && raw.projectId !== null && raw.projectId !== '') throw new TypeError('Global session bucket cannot have projectId')
+    return { scope: 'global', projectId: null }
+  }
+  if (raw.scope !== 'project' || typeof raw.projectId !== 'string' || !raw.projectId.trim() || raw.projectId === '.' || raw.projectId === '..' || /[\\/]/.test(raw.projectId)) {
+    throw new TypeError('Invalid session bucket')
+  }
+  return { scope: 'project', projectId: raw.projectId }
+}
+
+// Metadata derivation for body-only files (no sessions-metadata entry) —
+// identical shaping to the cutover's deriveMetadata.
+function deriveMetadata(sessionId, state, bucket) {
+  const createdAt = typeof state.createdAt === 'string'
+    ? state.createdAt
+    : (typeof state.lastModified === 'string' ? state.lastModified : '1970-01-01T00:00:00.000Z')
+  return {
+    id: sessionId,
+    title: typeof state.title === 'string' ? state.title : 'New chat',
+    titleSource: state.titleSource,
+    createdAt,
+    lastModified: typeof state.lastModified === 'string' ? state.lastModified : createdAt,
+    messageCount: state.messages.length,
+    stateVersion: Number.isInteger(state.stateVersion) && state.stateVersion >= 0 ? state.stateVersion : 0,
+    thinkingLevel: typeof state.thinkingLevel === 'string' ? state.thinkingLevel : 'off',
+    scope: bucket.scope,
+    ...(bucket.scope === 'project' ? { projectId: bucket.projectId } : {}),
+    taskStatus: state.taskStatus || 'idle',
+    taskStartedAt: state.taskStartedAt ?? null,
+    taskFinishedAt: state.taskFinishedAt ?? null,
+  }
+}
+
+// Per-session normalization with the cutover's normalizeSessionEntry
+// validation semantics: id/scope/projectId consistency between bucket, body
+// and metadata; orphan metadata-only entries are dropped (diagnosed by the
+// caller); body-only files derive their metadata. Returns the repository
+// record, or null for a metadata-only orphan.
+function normalizeSessionEntry(bucket, sessionId, rawState, rawMetadata, diagnostics) {
+  if (!rawState && rawMetadata) {
+    diagnostics.push({ kind: 'metadata-only-orphan', scope: bucket.scope, projectId: bucket.projectId, sessionId })
+    return null
+  }
+  if (!isPlainObject(rawState)) throw new TypeError(`Invalid session state: ${sessionId}`)
+  if (!Array.isArray(rawState.messages)) throw new TypeError(`Session messages must be an array: ${sessionId}`)
+  if (rawState.id !== undefined && rawState.id !== sessionId) throw new TypeError(`Session body id mismatch: ${sessionId}`)
+  if (rawState.scope !== undefined && rawState.scope !== bucket.scope) throw new TypeError(`Session body scope mismatch: ${sessionId}`)
+  if (bucket.scope === 'project' && rawState.projectId !== undefined && rawState.projectId !== bucket.projectId) throw new TypeError(`Session body project mismatch: ${sessionId}`)
+  if (bucket.scope === 'global' && rawState.projectId !== undefined && rawState.projectId !== null) throw new TypeError(`Global session body project mismatch: ${sessionId}`)
+  let metadata
+  if (rawMetadata === undefined) {
+    diagnostics.push({ kind: 'body-only', scope: bucket.scope, projectId: bucket.projectId, sessionId })
+    metadata = deriveMetadata(sessionId, rawState, bucket)
+  } else {
+    if (!isPlainObject(rawMetadata)) throw new TypeError(`Invalid session metadata: ${sessionId}`)
+    if (rawMetadata.id !== undefined && rawMetadata.id !== sessionId) throw new TypeError(`Session metadata id mismatch: ${sessionId}`)
+    if (rawMetadata.scope !== undefined && rawMetadata.scope !== bucket.scope) throw new TypeError(`Session metadata scope mismatch: ${sessionId}`)
+    if (bucket.scope === 'project' && rawMetadata.projectId !== undefined && rawMetadata.projectId !== bucket.projectId) throw new TypeError(`Session metadata project mismatch: ${sessionId}`)
+    if (bucket.scope === 'global' && rawMetadata.projectId !== undefined && rawMetadata.projectId !== null) throw new TypeError(`Global session metadata project mismatch: ${sessionId}`)
+    metadata = structuredClone(rawMetadata)
+  }
+  const stateVersion = rawState.stateVersion ?? metadata.stateVersion ?? 0
+  if (!Number.isInteger(stateVersion) || stateVersion < 0) throw new TypeError(`Invalid session stateVersion: ${sessionId}`)
+  const state = { ...structuredClone(rawState), id: sessionId, scope: bucket.scope, stateVersion }
+  metadata = { ...metadata, id: sessionId, scope: bucket.scope, stateVersion }
+  if (bucket.scope === 'project') {
+    state.projectId = bucket.projectId
+    metadata.projectId = bucket.projectId
+  } else {
+    delete state.projectId
+    delete metadata.projectId
+  }
+  for (const field of ['pinnedAt', 'archivedAt']) {
+    if (metadata[field] !== undefined) state[field] = metadata[field]
+  }
+  return { scope: bucket.scope, projectId: bucket.projectId ?? null, sessionId, state, metadata }
+}
+
+// Schema v11 JSON importer: streams the physical session-state JSON tree
+// (the same layout createPhysicalSessionStateFsAdapter walks for the old
+// cutover) and re-imports every session into the v2 SQLite store, one
+// transaction per session — repository.save extracts the messages (inline or
+// legacy split-marked bodies alike), so the import is idempotent and can be
+// re-run after any interruption. JSON files are read-only here: nothing is
+// written back, no mirror, no phase state.
+//
+// Resilience: a failing entry (unreadable file, validation mismatch,
+// cross-bucket duplicate) never aborts the run — it is counted in `skipped`
+// and described in `diagnostics` so the operator can inspect and fix the
+// source tree, then simply re-run.
+export async function importSessionStateFromJson({ storage = null, logger = defaultLogger } = {}) {
+  const storageModule = storage ?? await import('./storage.mjs')
+  const fsAdapter = storageModule.createPhysicalSessionStateFsAdapter()
+  const repository = createSessionStateRepository(getSqliteStorage())
+  const diagnostics = []
+  let imported = 0
+  let skipped = 0
+
+  for await (const rawBucket of fsAdapter.listBuckets()) {
+    const bucket = normalizeBucket(rawBucket)
+    const metadata = await fsAdapter.readMetadataBucket(rawBucket)
+    if (!isPlainObject(metadata)) throw new TypeError('Session bucket stores must be objects')
+    const fileIds = new Set()
+    for await (const sessionId of fsAdapter.listSessionFiles(rawBucket)) fileIds.add(sessionId)
+    const ids = [...new Set([...fileIds, ...Object.keys(metadata)])].sort((left, right) => left.localeCompare(right))
+    for (const sessionId of ids) {
+      let record
+      try {
+        const rawState = fileIds.has(sessionId) ? await fsAdapter.readSessionState(rawBucket, sessionId) : undefined
+        record = normalizeSessionEntry(bucket, sessionId, rawState, metadata[sessionId], diagnostics)
+      } catch (error) {
+        skipped += 1
+        diagnostics.push({ kind: 'invalid-entry', scope: bucket.scope, projectId: bucket.projectId, sessionId, message: error instanceof Error ? error.message : String(error) })
+        continue
+      }
+      if (!record) {
+        skipped += 1
+        continue
+      }
+      try {
+        repository.save(record)
+        imported += 1
+      } catch (error) {
+        skipped += 1
+        diagnostics.push({
+          kind: 'save-error',
+          scope: record.scope,
+          projectId: record.projectId,
+          sessionId,
+          errorCode: error?.errorCode ?? null,
+          message: error instanceof Error ? error.message : String(error),
+        })
+      }
+    }
+  }
+
+  try {
+    repository.checkpointWal()
+  } catch (error) {
+    logger.warn('Session state import WAL checkpoint failed', {
+      error: error instanceof Error ? error.message : String(error),
+    })
+  }
+  logger.info('Session state JSON import finished', { imported, skipped })
+  return { imported, skipped, diagnostics }
+}

package/server/session-state-maintenance.mjs

@@ -0,0 +1,126 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { randomUUID } from 'node:crypto'
+import { getSqliteStorage } from './sqlite/database.mjs'
+
+// Session-domain maintenance lock (extracted from the retired
+// session-state-cutover.mjs when the JSON→SQLite phase machine was removed):
+// restore/verify operations serialize across processes through the
+// `session_state_maintenance_lock` table (created by SQLite migration v6 and
+// kept by schema v11), with owner liveness, fencing tokens and a TTL renewed
+// by heartbeat while an operation runs.
+
+const DEFAULT_LOCK_TTL_MS = 60_000
+const DEFAULT_WAIT_TIMEOUT_MS = 65_000
+const maintenanceContext = new AsyncLocalStorage()
+let maintenanceCount = 0
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype
+}
+
+function ownerPid(current) {
+  const value = Number(current.owner_pid)
+  return Number.isInteger(value) && value > 0 ? value : null
+}
+
+function pidAlive(pid) {
+  try { process.kill(pid, 0); return true } catch (error) { return error?.code === 'EPERM' }
+}
+
+export function acquireSessionStateMaintenanceLock(storage, options = {}) {
+  const nowMs = Number(options.now?.() ?? Date.now())
+  const acquiredAt = new Date(nowMs).toISOString()
+  const expiresAt = new Date(nowMs + (options.ttlMs ?? DEFAULT_LOCK_TTL_MS)).toISOString()
+  const identity = isPlainObject(options.owner)
+    ? { id: options.owner.id || `${options.owner.pid || process.pid}:${randomUUID()}`, pid: options.owner.pid || process.pid }
+    : { id: options.owner || `${process.pid}:${randomUUID()}`, pid: process.pid }
+  const isPidAlive = options.pidAlive || pidAlive
+  return storage.transaction((database) => {
+    const current = database.prepare('SELECT * FROM session_state_maintenance_lock WHERE singleton = 1').get()
+    if (current && current.owner === identity.id) {
+      database.prepare(`UPDATE session_state_maintenance_lock SET owner_pid = ?, operation = ?, heartbeat_at = ?, expires_at = ?
+        WHERE singleton = 1 AND owner = ? AND fencing = ?`)
+        .run(identity.pid, options.operation || current.operation, acquiredAt, expiresAt, identity.id, current.fencing)
+      return { owner: identity.id, ownerPid: identity.pid, fencing: Number(current.fencing), expiresAt }
+    }
+    if (current) {
+      const expired = Date.parse(current.expires_at) <= nowMs
+      const pid = ownerPid(current)
+      if (!expired || pid === null || isPidAlive(pid)) return null
+    }
+    const fencing = Number(current?.fencing || 0) + 1
+    database.prepare(`INSERT INTO session_state_maintenance_lock
+      (singleton, owner, owner_pid, fencing, operation, acquired_at, heartbeat_at, expires_at)
+      VALUES (1, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(singleton) DO UPDATE SET owner=excluded.owner, owner_pid=excluded.owner_pid, fencing=excluded.fencing,
+      operation=excluded.operation, acquired_at=excluded.acquired_at, heartbeat_at=excluded.heartbeat_at, expires_at=excluded.expires_at`)
+      .run(identity.id, identity.pid, fencing, options.operation || 'session-state-maintenance', acquiredAt, acquiredAt, expiresAt)
+    return { owner: identity.id, ownerPid: identity.pid, fencing, expiresAt }
+  }, { mode: 'immediate' })
+}
+
+export function renewSessionStateMaintenanceLock(storage, lease, options = {}) {
+  const nowMs = Number(options.now?.() ?? Date.now())
+  const heartbeatAt = new Date(nowMs).toISOString()
+  const expiresAt = new Date(nowMs + (options.ttlMs ?? DEFAULT_LOCK_TTL_MS)).toISOString()
+  const result = storage.prepare(`UPDATE session_state_maintenance_lock SET heartbeat_at = ?, expires_at = ? WHERE singleton = 1 AND owner = ? AND fencing = ?`)
+    .run(heartbeatAt, expiresAt, lease.owner, lease.fencing)
+  lease.expiresAt = expiresAt
+  return Number(result.changes) === 1
+}
+
+export function releaseSessionStateMaintenanceLock(storage, lease) {
+  return Number(storage.prepare('DELETE FROM session_state_maintenance_lock WHERE singleton = 1 AND owner = ? AND fencing = ?').run(lease.owner, lease.fencing).changes) === 1
+}
+
+async function waitForLock(storage, options) {
+  const deadline = Date.now() + (options.waitTimeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS)
+  while (Date.now() < deadline) {
+    const lease = acquireSessionStateMaintenanceLock(storage, options)
+    if (lease) return lease
+    await new Promise((resolve) => setTimeout(resolve, options.pollIntervalMs ?? 100))
+  }
+  throw new Error('Timed out waiting for session state maintenance lock')
+}
+
+export async function runSessionStateMaintenance(operation, options = {}) {
+  const existing = maintenanceContext.getStore()
+  if (existing) return operation(existing)
+  const storage = options.storage || getSqliteStorage()
+  const lease = await waitForLock(storage, options)
+  const interval = options.heartbeatIntervalMs ?? Math.max(10, Math.floor((options.ttlMs ?? DEFAULT_LOCK_TTL_MS) / 3))
+  const timer = setInterval(() => {
+    try {
+      if (!renewSessionStateMaintenanceLock(storage, lease, options)) throw new Error('Session state maintenance lock fencing was lost')
+    } catch (error) {
+      heartbeatError = error
+      rejectHeartbeat(error)
+    }
+  }, interval)
+  timer.unref?.()
+  let rejectHeartbeat
+  let heartbeatError = null
+  const heartbeatFailure = new Promise((_, reject) => { rejectHeartbeat = reject })
+  maintenanceCount += 1
+  try {
+    const context = { storage, lease }
+    const result = await Promise.race([maintenanceContext.run(context, () => Promise.resolve().then(() => operation(context))), heartbeatFailure])
+    if (heartbeatError) throw heartbeatError
+    return result
+  } finally {
+    clearInterval(timer)
+    releaseSessionStateMaintenanceLock(storage, lease)
+    maintenanceCount = Math.max(0, maintenanceCount - 1)
+  }
+}
+
+export function isSessionStateMaintenanceActive(storage) {
+  if (!storage) {
+    try { storage = getSqliteStorage() } catch { return false }
+  }
+  return maintenanceCount > 0 || Boolean(storage.prepare('SELECT 1 AS active FROM session_state_maintenance_lock WHERE singleton = 1').get())
+}
+
+export function currentSessionStateMaintenanceContext() {
+  return maintenanceContext.getStore() || null
+}