orez 0.1.4 → 0.1.6

package/src/shim/hooks.mjs

@@ -1,8 +1,15 @@
 // esm loader hooks — intercept @rocicorp/zero-sqlite3 with bedrock-sqlite wasm.
+//
+// NOTE: this file is currently UNUSED. orez uses in-place CJS patching via
+// src/sqlite-mode/apply-mode.ts instead. this file is kept for potential future
+// use with Node.js ESM loader hooks (--import flag).
+//
 // __BEDROCK_PATH__ is replaced at runtime by orez before writing to tmpdir.
 
 const SHIM_URL = 'orez-sqlite-shim://shim'
 const BEDROCK_PATH = '__BEDROCK_PATH__'
+// __JOURNAL_MODE__ would be replaced at runtime (delete for wasm, wal2 for native)
+const JOURNAL_MODE = '__JOURNAL_MODE__'
 
 export function resolve(specifier, context, nextResolve) {
   if (
@@ -16,10 +23,18 @@ export function resolve(specifier, context, nextResolve) {
 
 export function load(url, context, nextLoad) {
   if (url === SHIM_URL) {
+    // journal mode differs between native and wasm:
+    // - native: wal2 for better concurrency
+    // - wasm: delete for compatibility (wal2 can corrupt wasm vfs)
+    const journalMode = JOURNAL_MODE === '__JOURNAL_MODE__' ? 'delete' : JOURNAL_MODE
+
     return {
       format: 'module',
       shortCircuit: true,
       source: `
+// orez sqlite shim - wraps bedrock-sqlite for zero-cache compatibility
+// journal_mode: ${journalMode}
+
 // catch uncaught exceptions from bedrock-sqlite wasm clearly
 process.on('uncaughtException', (err) => {
   console.error('[orez-shim] UNCAUGHT EXCEPTION:', err?.message || err);
@@ -27,49 +42,55 @@ process.on('uncaughtException', (err) => {
   console.error('[orez-shim] stack:', err?.stack?.split('\\n').slice(0, 5).join('\\n'));
   process.exit(1);
 });
+
 import { createRequire } from 'node:module';
 const require = createRequire('${BEDROCK_PATH}');
 const mod = require('${BEDROCK_PATH}');
 const OrigDatabase = mod.Database;
 const SqliteError = mod.SqliteError;
+
 function Database(...args) {
   const db = new OrigDatabase(...args);
-  try { db.pragma('journal_mode = delete'); db.pragma('busy_timeout = 30000'); db.pragma('synchronous = normal'); } catch(e) {}
+  try {
+    db.pragma('journal_mode = ${journalMode}');
+    db.pragma('busy_timeout = 30000');
+    db.pragma('synchronous = normal');
+  } catch(e) {}
   return db;
 }
+
 Database.prototype = OrigDatabase.prototype;
 Database.prototype.constructor = Database;
 Object.keys(OrigDatabase).forEach(k => { Database[k] = OrigDatabase[k]; });
+
+// api polyfills for better-sqlite3 compatibility
 Database.prototype.unsafeMode = function() { return this; };
-// wrap pragma to skip optimize (corrupts wasm vfs) and swallow sqlite errors
+if (!Database.prototype.defaultSafeIntegers) {
+  Database.prototype.defaultSafeIntegers = function() { return this; };
+}
+if (!Database.prototype.serialize) {
+  Database.prototype.serialize = function() { throw new Error('not supported in wasm'); };
+}
+if (!Database.prototype.backup) {
+  Database.prototype.backup = function() { throw new Error('not supported in wasm'); };
+}
+
+// wrap pragma to skip optimize (can corrupt wasm vfs) and swallow sqlite errors
 const origPragma = OrigDatabase.prototype.pragma;
 Database.prototype.pragma = function(str, opts) {
   if (str && str.trim().toLowerCase().startsWith('optimize')) return [];
   try { return origPragma.call(this, str, opts); }
   catch(e) { if (e && (e.code === 'SQLITE_CORRUPT' || e.code === 'SQLITE_IOERR')) return []; throw e; }
 };
+
 // wrap close to swallow wasm errors during shutdown
 const origClose = OrigDatabase.prototype.close;
 Database.prototype.close = function() {
   try { return origClose.call(this); }
   catch(e) { console.error('[orez-shim] close error (swallowed):', e?.message || e); }
 };
-// trace writes to _zero.changeLog and _zero.replicationState to debug view-syncer
-const origRun = OrigDatabase.prototype.run;
-Database.prototype.run = function(sql, ...args) {
-  if (typeof sql === 'string') {
-    if (sql.includes('_zero.changeLog')) {
-      console.info('[orez-shim] changeLog write:', sql.slice(0, 120), args.length ? JSON.stringify(args[0]).slice(0, 80) : '');
-    }
-    if (sql.includes('_zero.replicationState') && (sql.includes('UPDATE') || sql.includes('INSERT'))) {
-      console.info('[orez-shim] replicationState update:', sql.slice(0, 120), args.length ? JSON.stringify(args[0]).slice(0, 80) : '');
-    }
-  }
-  return origRun.call(this, sql, ...args);
-};
-if (!Database.prototype.defaultSafeIntegers) Database.prototype.defaultSafeIntegers = function() { return this; };
-if (!Database.prototype.serialize) Database.prototype.serialize = function() { throw new Error('not supported in wasm'); };
-if (!Database.prototype.backup) Database.prototype.backup = function() { throw new Error('not supported in wasm'); };
+
+// statement prototype polyfills
 const tmpDb = new OrigDatabase(':memory:');
 const tmpStmt = tmpDb.prepare('SELECT 1');
 const SP = Object.getPrototypeOf(tmpStmt);
@@ -78,6 +99,8 @@ SP.scanStatus = function() { return undefined; };
 SP.scanStatusV2 = function() { return []; };
 SP.scanStatusReset = function() {};
 tmpDb.close();
+
+// scanstat constants for query planner compatibility
 Database.SQLITE_SCANSTAT_NLOOP = 0;
 Database.SQLITE_SCANSTAT_NVISIT = 1;
 Database.SQLITE_SCANSTAT_EST = 2;
@@ -87,6 +110,7 @@ Database.SQLITE_SCANSTAT_SELECTID = 5;
 Database.SQLITE_SCANSTAT_PARENTID = 6;
 Database.SQLITE_SCANSTAT_NCYCLE = 7;
 Database.SQLITE_SCANSTAT_COMPLEX = 8;
+
 export default Database;
 export { SqliteError };
 `,

package/src/sqlite-mode/apply-mode.ts

@@ -0,0 +1,224 @@
+/**
+ * apply sqlite mode - handles shim installation with backup/restore lifecycle
+ *
+ * this module manages the in-place patching of @rocicorp/zero-sqlite3 with proper
+ * backup/restore to prevent mode contamination when switching between wasm and native.
+ */
+
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+import { generateCjsShim } from './shim-template.js'
+import { BACKUP_MARKER, type SqliteMode, type SqliteModeConfig } from './types.js'
+
+interface ApplyResult {
+  success: boolean
+  shimPath?: string
+  error?: string
+}
+
+/**
+ * find the index.js file to shim in @rocicorp/zero-sqlite3
+ */
+function findZeroSqliteIndex(zeroSqlitePath: string): string | null {
+  // find package root (contains package.json)
+  let dir = zeroSqlitePath
+  while (dir && !existsSync(resolve(dir, 'package.json'))) {
+    const parent = resolve(dir, '..')
+    if (parent === dir) break
+    dir = parent
+  }
+
+  // try lib/index.js first, then root index.js
+  const libIndex = resolve(dir, 'lib', 'index.js')
+  if (existsSync(libIndex)) return libIndex
+
+  const rootIndex = resolve(dir, 'index.js')
+  if (existsSync(rootIndex)) return rootIndex
+
+  return null
+}
+
+/**
+ * get backup path for an index file
+ */
+function getBackupPath(indexPath: string): string {
+  return indexPath + BACKUP_MARKER
+}
+
+/**
+ * check if a file is already shimmed by orez
+ */
+function isOrezShimmed(indexPath: string): boolean {
+  if (!existsSync(indexPath)) return false
+  const content = readFileSync(indexPath, 'utf-8')
+  return content.includes('orez sqlite shim')
+}
+
+/**
+ * check what mode an existing shim is configured for
+ */
+export function getShimMode(indexPath: string): SqliteMode | null {
+  if (!existsSync(indexPath)) return null
+  const content = readFileSync(indexPath, 'utf-8')
+  if (!content.includes('orez sqlite shim')) return null
+
+  // extract mode from comment: "// mode: wasm, journal_mode: delete"
+  const match = content.match(/\/\/ mode: (native|wasm),/)
+  return match ? (match[1] as SqliteMode) : null
+}
+
+/**
+ * backup the original @rocicorp/zero-sqlite3 index.js
+ * only backs up if not already backed up and not already shimmed
+ */
+export function backupOriginal(indexPath: string): boolean {
+  const backupPath = getBackupPath(indexPath)
+
+  // already have a backup
+  if (existsSync(backupPath)) return true
+
+  // don't backup if file is already shimmed (would backup the shim)
+  if (isOrezShimmed(indexPath)) {
+    return false
+  }
+
+  if (!existsSync(indexPath)) return false
+
+  const content = readFileSync(indexPath, 'utf-8')
+  writeFileSync(backupPath, content)
+  return true
+}
+
+/**
+ * restore the original @rocicorp/zero-sqlite3 from backup
+ */
+export function restoreOriginal(indexPath: string): boolean {
+  const backupPath = getBackupPath(indexPath)
+
+  if (!existsSync(backupPath)) {
+    // no backup to restore from
+    return false
+  }
+
+  const content = readFileSync(backupPath, 'utf-8')
+  writeFileSync(indexPath, content)
+  rmSync(backupPath)
+  return true
+}
+
+/**
+ * check if backup exists
+ */
+export function hasBackup(indexPath: string): boolean {
+  return existsSync(getBackupPath(indexPath))
+}
+
+/**
+ * apply wasm mode shim to @rocicorp/zero-sqlite3
+ * backs up original first, writes shim in place
+ */
+export function applyWasmShim(config: SqliteModeConfig): ApplyResult {
+  if (config.mode !== 'wasm') {
+    return { success: false, error: 'applyWasmShim called with non-wasm mode' }
+  }
+
+  if (!config.zeroSqlitePath) {
+    return { success: false, error: '@rocicorp/zero-sqlite3 not found' }
+  }
+
+  if (!config.bedrockPath) {
+    return { success: false, error: 'bedrock-sqlite not found' }
+  }
+
+  const indexPath = findZeroSqliteIndex(config.zeroSqlitePath)
+  if (!indexPath) {
+    return { success: false, error: 'could not find @rocicorp/zero-sqlite3 index.js' }
+  }
+
+  // check if already shimmed for wasm mode
+  const existingMode = getShimMode(indexPath)
+  if (existingMode === 'wasm') {
+    return { success: true, shimPath: indexPath }
+  }
+
+  // backup original before shimming - must succeed
+  const backedUp = backupOriginal(indexPath)
+  if (!backedUp && !hasBackup(indexPath)) {
+    // file is shimmed (possibly by another mode) but no backup exists
+    // cannot safely proceed - would lose ability to restore
+    return {
+      success: false,
+      error:
+        'cannot apply wasm shim: file is already shimmed with no backup. reinstall @rocicorp/zero-sqlite3',
+    }
+  }
+
+  // generate and write shim
+  const shimCode = generateCjsShim({
+    mode: 'wasm',
+    bedrockPath: config.bedrockPath,
+    includeTracing: false,
+  })
+
+  writeFileSync(indexPath, shimCode)
+
+  return { success: true, shimPath: indexPath }
+}
+
+/**
+ * restore native mode by removing shim and restoring original
+ */
+export function restoreNativeMode(zeroSqlitePath: string): ApplyResult {
+  const indexPath = findZeroSqliteIndex(zeroSqlitePath)
+  if (!indexPath) {
+    return { success: false, error: 'could not find @rocicorp/zero-sqlite3 index.js' }
+  }
+
+  // check if currently shimmed
+  if (!isOrezShimmed(indexPath)) {
+    // not shimmed, nothing to do
+    return { success: true }
+  }
+
+  // restore from backup
+  if (restoreOriginal(indexPath)) {
+    return { success: true }
+  }
+
+  // no backup available - this is a problem
+  return {
+    success: false,
+    error:
+      'cannot restore native mode: no backup found. reinstall @rocicorp/zero-sqlite3',
+  }
+}
+
+/**
+ * apply sqlite mode - main entry point
+ * handles both installing wasm shim and restoring to native
+ */
+export function applySqliteMode(config: SqliteModeConfig): ApplyResult {
+  if (config.mode === 'native') {
+    // for native mode, restore original if shimmed
+    if (config.zeroSqlitePath) {
+      return restoreNativeMode(config.zeroSqlitePath)
+    }
+    return { success: true }
+  }
+
+  return applyWasmShim(config)
+}
+
+/**
+ * cleanup any shim artifacts - used during shutdown or cleanup
+ */
+export function cleanupShim(zeroSqlitePath: string | undefined): void {
+  if (!zeroSqlitePath) return
+
+  const indexPath = findZeroSqliteIndex(zeroSqlitePath)
+  if (!indexPath) return
+
+  // restore original if we have a backup
+  restoreOriginal(indexPath)
+}

package/src/sqlite-mode/index.ts

@@ -0,0 +1,14 @@
+/**
+ * sqlite-mode module - unified sqlite mode handling for orez
+ *
+ * this module provides:
+ * - type definitions for sqlite modes
+ * - mode resolution from config
+ * - shim generation (single source of truth)
+ * - safe mode application with backup/restore
+ */
+
+export * from './types.js'
+export * from './resolve-mode.js'
+export * from './apply-mode.js'
+export * from './shim-template.js'

package/src/sqlite-mode/resolve-mode.ts

@@ -0,0 +1,71 @@
+/**
+ * mode resolution - canonical place to determine sqlite mode from config/env
+ */
+
+import { createRequire } from 'node:module'
+
+import type { SqliteMode, SqliteModeConfig } from './types.js'
+
+/**
+ * resolve a package entry path
+ * import.meta.resolve doesn't work in vitest, so we fall back to require.resolve
+ */
+export function resolvePackage(pkg: string): string {
+  try {
+    const resolved = import.meta.resolve(pkg)
+    if (resolved) return resolved.replace('file://', '')
+  } catch {}
+  try {
+    const require = createRequire(import.meta.url)
+    return require.resolve(pkg)
+  } catch {}
+  return ''
+}
+
+/**
+ * resolve sqlite mode from config
+ * single source of truth for mode selection
+ */
+export function resolveSqliteMode(disableWasmSqlite: boolean): SqliteMode {
+  return disableWasmSqlite ? 'native' : 'wasm'
+}
+
+/**
+ * resolve full sqlite mode config including paths
+ * returns null if required packages aren't installed
+ */
+export function resolveSqliteModeConfig(
+  disableWasmSqlite: boolean
+): SqliteModeConfig | null {
+  const mode = resolveSqliteMode(disableWasmSqlite)
+  const zeroSqlitePath = resolvePackage('@rocicorp/zero-sqlite3') || undefined
+
+  // native mode may still need zero-sqlite3 path for restoring from a prior shim
+  if (mode === 'native') {
+    return { mode, zeroSqlitePath }
+  }
+
+  // wasm mode needs bedrock-sqlite and zero-sqlite3 paths
+  const bedrockPath = resolvePackage('bedrock-sqlite')
+
+  if (!bedrockPath) {
+    return null // bedrock-sqlite not installed
+  }
+
+  if (!zeroSqlitePath) {
+    return null // zero-sqlite3 not installed
+  }
+
+  return {
+    mode,
+    bedrockPath,
+    zeroSqlitePath,
+  }
+}
+
+/**
+ * get mode display string for logging
+ */
+export function getModeDisplayString(mode: SqliteMode): string {
+  return mode
+}

package/src/sqlite-mode/shim-template.ts

@@ -0,0 +1,158 @@
+/**
+ * shim template generator - single source of truth for both cjs and esm shims.
+ * generates the shim code that wraps bedrock-sqlite to be compatible with
+ * @rocicorp/zero-sqlite3 (better-sqlite3 api).
+ */
+
+import { COMMON_PRAGMAS, JOURNAL_MODE, type SqliteMode } from './types.js'
+
+export interface ShimOptions {
+  mode: SqliteMode
+  bedrockPath: string
+  // include debug tracing for changeLog/replicationState writes
+  includeTracing?: boolean
+}
+
+/**
+ * generate the core shim code (shared between cjs and esm)
+ * this is the constructor wrapper and api polyfills
+ */
+function generateShimCore(opts: ShimOptions): string {
+  const journalMode = JOURNAL_MODE[opts.mode]
+  const { busy_timeout, synchronous } = COMMON_PRAGMAS
+
+  return `
+var OrigDatabase = mod.Database;
+var SqliteError = mod.SqliteError;
+
+function Database() {
+  var db = new OrigDatabase(...arguments);
+  try {
+    db.pragma('journal_mode = ${journalMode}');
+    db.pragma('busy_timeout = ${busy_timeout}');
+    db.pragma('synchronous = ${synchronous}');
+  } catch(e) {}
+  return db;
+}
+
+Database.prototype = OrigDatabase.prototype;
+Database.prototype.constructor = Database;
+Object.keys(OrigDatabase).forEach(function(k) { Database[k] = OrigDatabase[k]; });
+
+// api polyfills for better-sqlite3 compatibility
+Database.prototype.unsafeMode = function() { return this; };
+if (!Database.prototype.defaultSafeIntegers) {
+  Database.prototype.defaultSafeIntegers = function() { return this; };
+}
+if (!Database.prototype.serialize) {
+  Database.prototype.serialize = function() { throw new Error('not supported in wasm'); };
+}
+if (!Database.prototype.backup) {
+  Database.prototype.backup = function() { throw new Error('not supported in wasm'); };
+}
+
+// wrap pragma to skip optimize (can corrupt wasm vfs) and swallow sqlite errors
+var origPragma = OrigDatabase.prototype.pragma;
+Database.prototype.pragma = function(str, opts) {
+  if (str && str.trim().toLowerCase().startsWith('optimize')) return [];
+  try { return origPragma.call(this, str, opts); }
+  catch(e) { if (e && (e.code === 'SQLITE_CORRUPT' || e.code === 'SQLITE_IOERR')) return []; throw e; }
+};
+
+// wrap close to swallow wasm errors during shutdown
+var origClose = OrigDatabase.prototype.close;
+Database.prototype.close = function() {
+  try { return origClose.call(this); }
+  catch(e) { console.error('[orez-shim] close error (swallowed):', e?.message || e); }
+};
+
+// statement prototype polyfills
+var tmpDb = new OrigDatabase(':memory:');
+var tmpStmt = tmpDb.prepare('SELECT 1');
+var SP = Object.getPrototypeOf(tmpStmt);
+if (!SP.safeIntegers) SP.safeIntegers = function() { return this; };
+SP.scanStatus = function() { return undefined; };
+SP.scanStatusV2 = function() { return []; };
+SP.scanStatusReset = function() {};
+tmpDb.close();
+
+// scanstat constants for query planner compatibility
+Database.SQLITE_SCANSTAT_NLOOP = 0;
+Database.SQLITE_SCANSTAT_NVISIT = 1;
+Database.SQLITE_SCANSTAT_EST = 2;
+Database.SQLITE_SCANSTAT_NAME = 3;
+Database.SQLITE_SCANSTAT_EXPLAIN = 4;
+Database.SQLITE_SCANSTAT_SELECTID = 5;
+Database.SQLITE_SCANSTAT_PARENTID = 6;
+Database.SQLITE_SCANSTAT_NCYCLE = 7;
+Database.SQLITE_SCANSTAT_COMPLEX = 8;
+`.trim()
+}
+
+/**
+ * generate debug tracing code for run() method
+ */
+function generateTracing(): string {
+  return `
+// trace writes to _zero.changeLog and _zero.replicationState for debugging
+var origRun = OrigDatabase.prototype.run;
+Database.prototype.run = function(sql) {
+  var args = Array.prototype.slice.call(arguments, 1);
+  if (typeof sql === 'string') {
+    if (sql.includes('_zero.changeLog')) {
+      console.info('[orez-shim] changeLog write:', sql.slice(0, 120), args.length ? JSON.stringify(args[0]).slice(0, 80) : '');
+    }
+    if (sql.includes('_zero.replicationState') && (sql.includes('UPDATE') || sql.includes('INSERT'))) {
+      console.info('[orez-shim] replicationState update:', sql.slice(0, 120), args.length ? JSON.stringify(args[0]).slice(0, 80) : '');
+    }
+  }
+  return origRun.apply(this, arguments);
+};
+`.trim()
+}
+
+/**
+ * generate commonjs shim for in-place patching of @rocicorp/zero-sqlite3
+ */
+export function generateCjsShim(opts: ShimOptions): string {
+  const core = generateShimCore(opts)
+  const tracing = opts.includeTracing ? '\n' + generateTracing() : ''
+
+  return `'use strict';
+// orez sqlite shim - wraps bedrock-sqlite for zero-cache compatibility
+// mode: ${opts.mode}, journal_mode: ${JOURNAL_MODE[opts.mode]}
+var mod = require('${opts.bedrockPath}');
+${core}
+${tracing}
+module.exports = Database;
+module.exports.SqliteError = SqliteError;
+`
+}
+
+/**
+ * generate esm shim for loader hooks
+ */
+export function generateEsmShim(opts: ShimOptions): string {
+  const core = generateShimCore(opts)
+  const tracing = opts.includeTracing ? '\n' + generateTracing() : ''
+
+  return `// orez sqlite shim - wraps bedrock-sqlite for zero-cache compatibility
+// mode: ${opts.mode}, journal_mode: ${JOURNAL_MODE[opts.mode]}
+
+// catch uncaught exceptions from bedrock-sqlite wasm clearly
+process.on('uncaughtException', (err) => {
+  console.error('[orez-shim] UNCAUGHT EXCEPTION:', err?.message || err);
+  console.error('[orez-shim] code:', err?.code, 'name:', err?.name);
+  console.error('[orez-shim] stack:', err?.stack?.split('\\n').slice(0, 5).join('\\n'));
+  process.exit(1);
+});
+
+import { createRequire } from 'node:module';
+const require = createRequire('${opts.bedrockPath}');
+var mod = require('${opts.bedrockPath}');
+${core}
+${tracing}
+export default Database;
+export { SqliteError };
+`
+}