♻️ enforce sqlite single-writer state and bootstrap legacy migration

Introduce explicit read/write store modes, enforce a single writer path, and add one-time legacy JSON bootstrap on CLI startup.\n\nAlso updates routers/services/tests for read-mode access, resets in-memory TDD runtime state on baseline reset, and adds migration/mode contract coverage.

Author: Robdel12

src/cli.js

@@ -53,6 +53,7 @@ import {
   generateStaticReport,
   getReportFileUrl,
 } from './services/static-report-generator.js';
+import { bootstrapLegacyStateIfNeeded } from './tdd/state-store.js';
 import { openBrowser } from './utils/browser.js';
 import { colors } from './utils/colors.js';
 import { loadConfig } from './utils/config-loader.js';
@@ -331,6 +332,11 @@ output.configure({
   json: jsonArg,
 });
 
+bootstrapLegacyStateIfNeeded({
+  workingDir: process.cwd(),
+  output,
+});
+
 const config = await loadConfig(configPath, {});
 const services = createServices(config);
 const pluginServices = createPluginServices(services);

src/server/handlers/tdd-handler.js

@@ -202,6 +202,7 @@ export const createTddHandler = (
     createStateStore({
       workingDir,
       output,
+      mode: 'write',
     });
 
   /**
@@ -736,6 +737,11 @@ export const createTddHandler = (
       // Clear state store data entirely - fresh start
       stateStore.resetReportData();
 
+      // Reset in-memory TDD runtime caches so the current process is also fresh.
+      if (typeof tddService.resetRuntimeState === 'function') {
+        tddService.resetRuntimeState();
+      }
+
       output.info(
         `Baselines reset - ${deletedBaselines} baselines deleted, ${deletedCurrents} current screenshots deleted, ${deletedDiffs} diffs deleted`
       );

src/server/routers/dashboard.js

@@ -26,7 +26,7 @@ export function createDashboardRouter(context) {
 
     // API endpoint for fetching report data
     if (pathname === '/api/report-data') {
-      let stateStore = createStateStore({ workingDir, output });
+      let stateStore = createStateStore({ workingDir, output, mode: 'read' });
       try {
         let data = stateStore.readReportData();
         if (!data) {
@@ -58,7 +58,7 @@ export function createDashboardRouter(context) {
         return true;
       }
 
-      let stateStore = createStateStore({ workingDir, output });
+      let stateStore = createStateStore({ workingDir, output, mode: 'read' });
       try {
         let reportData = stateStore.readReportData();
         if (!reportData) {
@@ -94,7 +94,7 @@ export function createDashboardRouter(context) {
     if (SPA_ROUTES.includes(pathname) || pathname.startsWith('/comparison/')) {
       let reportData = null;
 
-      let stateStore = createStateStore({ workingDir, output });
+      let stateStore = createStateStore({ workingDir, output, mode: 'read' });
       try {
         reportData = stateStore.readReportData();
         if (reportData) {

src/server/routers/events.js

@@ -17,14 +17,19 @@ export function createEventsRouter(context) {
   /**
    * Read and parse report data with baseline metadata included
    */
-  let readReportData = stateStore => {
-    let data = stateStore.readReportData();
-    if (!data) {
-      return null;
-    }
+  let readReportData = () => {
+    let snapshotStore = createStateStore({ workingDir, mode: 'read' });
+    try {
+      let data = snapshotStore.readReportData();
+      if (!data) {
+        return null;
+      }
 
-    data.baseline = stateStore.getBaselineMetadata();
-    return data;
+      data.baseline = snapshotStore.getBaselineMetadata();
+      return data;
+    } finally {
+      snapshotStore.close();
+    }
   };
 
   /**
@@ -111,7 +116,7 @@ export function createEventsRouter(context) {
       return false;
     }
 
-    let stateStore = createStateStore({ workingDir });
+    let subscriptionStore = createStateStore({ workingDir, mode: 'read' });
 
     // Set SSE headers
     res.writeHead(200, {
@@ -122,7 +127,7 @@ export function createEventsRouter(context) {
     });
 
     // Send initial full data immediately
-    let lastSentData = readReportData(stateStore);
+    let lastSentData = readReportData();
     if (lastSentData) {
       sendEvent(res, 'reportData', lastSentData);
     }
@@ -131,7 +136,7 @@ export function createEventsRouter(context) {
     let updateQueued = false;
 
     let sendUpdate = () => {
-      let newData = readReportData(stateStore);
+      let newData = readReportData();
       if (!newData) return;
 
       if (!lastSentData) {
@@ -159,7 +164,7 @@ export function createEventsRouter(context) {
       });
     };
 
-    let unsubscribe = stateStore.subscribe(queueUpdate);
+    let unsubscribe = subscriptionStore.subscribe(queueUpdate);
 
     // Heartbeat to keep connection alive (every 30 seconds)
     let heartbeatInterval = setInterval(() => {
@@ -173,7 +178,7 @@ export function createEventsRouter(context) {
       closed = true;
       clearInterval(heartbeatInterval);
       unsubscribe();
-      stateStore.close();
+      subscriptionStore.close();
     };
 
     req.on('close', cleanup);

src/server/routers/health.js

@@ -26,7 +26,7 @@ export function createHealthRouter({
 
     let reportData = null;
     let baselineInfo = null;
-    let stateStore = createStateStore({ workingDir });
+    let stateStore = createStateStore({ workingDir, mode: 'read' });
     try {
       reportData = stateStore.readReportData();
       baselineInfo = stateStore.getBaselineMetadata();

src/services/static-report-generator.js

@@ -157,7 +157,7 @@ export async function generateStaticReport(workingDir, options = {}) {
   try {
     let reportData = null;
     let baselineMetadata = null;
-    let stateStore = createStateStore({ workingDir });
+    let stateStore = createStateStore({ workingDir, mode: 'read' });
     try {
       reportData = stateStore.readReportData();
       baselineMetadata = stateStore.getBaselineMetadata();

src/tdd/metadata/baseline-metadata.js

@@ -21,8 +21,8 @@ function resolveWorkingDirFromBaselinePath(baselinePath) {
   return resolvedPath;
 }
 
-function withStateStore(workingDir, operation) {
-  let store = createStateStore({ workingDir });
+function withStateStore(workingDir, mode, operation) {
+  let store = createStateStore({ workingDir, mode });
 
   try {
     return operation(store);
@@ -37,10 +37,11 @@ function withStateStore(workingDir, operation) {
  * @param {string} baselinePath - Path to baselines directory
  * @returns {Object|null} Baseline metadata or null if not found
  */
-export function loadBaselineMetadata(baselinePath) {
+export function loadBaselineMetadata(baselinePath, options = {}) {
+  let { mode = 'read' } = options;
   let workingDir = resolveWorkingDirFromBaselinePath(baselinePath);
 
-  return withStateStore(workingDir, store => {
+  return withStateStore(workingDir, mode, store => {
     try {
       return store.getBaselineMetadata();
     } catch (error) {
@@ -59,7 +60,7 @@ export function loadBaselineMetadata(baselinePath) {
 export function saveBaselineMetadata(baselinePath, metadata) {
   let workingDir = resolveWorkingDirFromBaselinePath(baselinePath);
 
-  withStateStore(workingDir, store => {
+  withStateStore(workingDir, 'write', store => {
     store.setBaselineMetadata(metadata);
   });
 }
@@ -70,8 +71,10 @@ export function saveBaselineMetadata(baselinePath, metadata) {
  * @param {string} workingDir - Working directory containing .vizzly
  * @returns {Object|null} Baseline build metadata or null
  */
-export function loadBaselineBuildMetadata(workingDir) {
-  return withStateStore(workingDir, store => {
+export function loadBaselineBuildMetadata(workingDir, options = {}) {
+  let { mode = 'read' } = options;
+
+  return withStateStore(workingDir, mode, store => {
     try {
       return store.getBaselineBuildMetadata();
     } catch (error) {
@@ -90,7 +93,7 @@ export function loadBaselineBuildMetadata(workingDir) {
  * @param {Object} metadata - Metadata object to save
  */
 export function saveBaselineBuildMetadata(workingDir, metadata) {
-  withStateStore(workingDir, store => {
+  withStateStore(workingDir, 'write', store => {
     store.setBaselineBuildMetadata(metadata);
   });
 }

src/tdd/metadata/hotspot-metadata.js

@@ -8,8 +8,8 @@
 
 import { createStateStore } from '../state-store.js';
 
-function withStateStore(workingDir, operation) {
-  let store = createStateStore({ workingDir });
+function withStateStore(workingDir, mode, operation) {
+  let store = createStateStore({ workingDir, mode });
 
   try {
     return operation(store);
@@ -24,8 +24,10 @@ function withStateStore(workingDir, operation) {
  * @param {string} workingDir - Working directory containing .vizzly folder
  * @returns {Object|null} Hotspot data keyed by screenshot name, or null if not found
  */
-export function loadHotspotMetadata(workingDir) {
-  return withStateStore(workingDir, store => {
+export function loadHotspotMetadata(workingDir, options = {}) {
+  let { mode = 'read' } = options;
+
+  return withStateStore(workingDir, mode, store => {
     try {
       return store.getHotspotMetadata();
     } catch {
@@ -42,7 +44,7 @@ export function loadHotspotMetadata(workingDir) {
  * @param {Object} summary - Summary information about the hotspots
  */
 export function saveHotspotMetadata(workingDir, hotspotData, summary = {}) {
-  withStateStore(workingDir, store => {
+  withStateStore(workingDir, 'write', store => {
     store.setHotspotMetadata(hotspotData, summary);
   });
 }

src/tdd/metadata/region-metadata.js

@@ -7,8 +7,8 @@
 
 import { createStateStore } from '../state-store.js';
 
-function withStateStore(workingDir, operation) {
-  let store = createStateStore({ workingDir });
+function withStateStore(workingDir, mode, operation) {
+  let store = createStateStore({ workingDir, mode });
 
   try {
     return operation(store);
@@ -23,8 +23,10 @@ function withStateStore(workingDir, operation) {
  * @param {string} workingDir - Working directory containing .vizzly folder
  * @returns {Object|null} Region data keyed by screenshot name, or null if not found
  */
-export function loadRegionMetadata(workingDir) {
-  return withStateStore(workingDir, store => {
+export function loadRegionMetadata(workingDir, options = {}) {
+  let { mode = 'read' } = options;
+
+  return withStateStore(workingDir, mode, store => {
     try {
       return store.getRegionMetadata();
     } catch {
@@ -41,7 +43,7 @@ export function loadRegionMetadata(workingDir) {
  * @param {Object} summary - Summary information about the regions
  */
 export function saveRegionMetadata(workingDir, regionData, summary = {}) {
-  withStateStore(workingDir, store => {
+  withStateStore(workingDir, 'write', store => {
     store.setRegionMetadata(regionData, summary);
   });
 }

src/tdd/state-store.js

@@ -6,6 +6,8 @@
  * SQLite is the only supported backend.
  */
 
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 import { STATE_METADATA_KEYS } from './state-store/constants.js';
 import {
   createSqliteStateStore,
@@ -14,6 +16,60 @@ import {
 
 export { STATE_METADATA_KEYS, createSqliteStateStore, getStateDbPath };
 
-export function createStateStore(options) {
+export function createStateStore(options = {}) {
   return createSqliteStateStore(options);
 }
+
+let LEGACY_STATE_FILES = [
+  'report-data.json',
+  'comparison-details.json',
+  join('baselines', 'metadata.json'),
+  'hotspots.json',
+  'regions.json',
+  'baseline-metadata.json',
+];
+
+/**
+ * Bootstrap legacy JSON state into SQLite once, the first time CLI runs
+ * in a project that has legacy files and no state.db yet.
+ *
+ * @returns {boolean} true when bootstrap migration was executed
+ */
+export function bootstrapLegacyStateIfNeeded(options = {}) {
+  let {
+    workingDir = process.cwd(),
+    output = {},
+    createStore = createStateStore,
+    fs = {},
+    joinPath = join,
+  } = options;
+
+  let { existsSync: existsSyncImpl = existsSync } = fs;
+  let vizzlyDir = joinPath(workingDir, '.vizzly');
+  let stateDbPath = joinPath(vizzlyDir, 'state.db');
+
+  if (!existsSyncImpl(vizzlyDir) || existsSyncImpl(stateDbPath)) {
+    return false;
+  }
+
+  let hasLegacyFiles = LEGACY_STATE_FILES.some(relativePath =>
+    existsSyncImpl(joinPath(vizzlyDir, relativePath))
+  );
+
+  if (!hasLegacyFiles) {
+    return false;
+  }
+
+  try {
+    let store = createStore({ workingDir, output, mode: 'write' });
+    store.close();
+    output.debug?.('state', 'bootstrapped legacy JSON state to SQLite');
+    return true;
+  } catch (error) {
+    output.debug?.(
+      'state',
+      `legacy bootstrap migration skipped: ${error.message}`
+    );
+    return false;
+  }
+}