Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

6.1 KB
Raw Blame
/** The native SQLite read mechanism is eager: hook admission must not depend on a lazy code chunk.
 *  The optional Node builtin is resolved without a bundler import, and older Node keeps its CLI fallback. */
import { statSync } from 'node:fs'
import { pathToFileURL } from 'node:url'
import { idleWalStore, type SqliteParam, type SqliteReadResult, type SqliteRow } from './sqliteRead.js'

interface StatementLike { all(...params: SqliteParam[]): SqliteRow[] }
export interface DatabaseLike {
  prepare(sql: string): StatementLike
  exec(sql: string): void
  close(): void
}
export interface DatabaseConstructor { new (path: string | URL, options: { readOnly: boolean }): DatabaseLike }

let builtin: DatabaseConstructor | null | undefined

/**
 * `node:sqlite` when this Node has it, else null. Resolved through `process.getBuiltinModule` (Node
 * ≥ 20.16 / 22.3) rather than `import()`: synchronous, and invisible to the bundler, which must not
 * try to resolve a module that only some runtimes have.
 *
 * The binding announces itself with an ExperimentalWarning on first load. That line would land in
 * `harness.log` at every daemon boot, so it is filtered — only that one warning, and every other
 * listener is kept.
 */
export function builtinSqlite(): DatabaseConstructor | null {
  if (builtin !== undefined) return builtin
  builtin = null
  const get = (process as { getBuiltinModule?: (id: string) => unknown }).getBuiltinModule
  if (typeof get !== 'function') return builtin
  const previous = process.listeners('warning')
  process.removeAllListeners('warning')
  process.on('warning', (warning) => {
    if (warning.name === 'ExperimentalWarning' && /SQLite/i.test(warning.message)) return
    for (const listener of previous) listener.call(process, warning)
  })
  try {
    const mod = get.call(process, 'node:sqlite') as { DatabaseSync?: unknown } | undefined
    if (mod && typeof mod.DatabaseSync === 'function') builtin = mod.DatabaseSync as DatabaseConstructor
  } catch {
    builtin = null
  }
  return builtin
}

/**
 * Run a write script statement by statement through `node:sqlite`, the way `sqlite3 -batch -bail` runs
 * it: each `SELECT` row's first column becomes one output line, and the first failure stops the script
 * and rolls back its open transaction. Windows ships no `sqlite3` CLI; the installers' Node has this.
 */
export function runSqliteScript(Database: DatabaseConstructor, path: string, statements: readonly string[]): string[] {
  const db = new Database(path, { readOnly: false })
  const out: string[] = []
  try {
    for (const statement of statements) {
      if (/^\s*SELECT\b/i.test(statement)) {
        for (const row of db.prepare(statement).all()) out.push(String(Object.values(row)[0]))
      } else {
        db.exec(statement)
      }
    }
  } catch (err) {
    try { db.exec('ROLLBACK') } catch { /* no transaction was open */ }
    throw err
  } finally {
    db.close()
  }
  return out
}

interface Handle { db: DatabaseLike; dev: number; ino: number; immutable: boolean; stamp: string; busyTimeoutMs: number }

/** One open handle per store: the readers poll every second, and opening is the expensive part. */
const handles = new Map<string, Handle>()

/**
 * The cached handle, or a fresh one. Keyed by path but checked by inode: an engine that rebuilds its
 * store (a reinstall, a `rm` and restart) leaves a handle on the OLD file, which would keep answering
 * from a database nobody writes to any more — a poller that never sees another row, with no error.
 */
function openHandle(Database: DatabaseConstructor, dbPath: string, busyTimeoutMs: number): DatabaseLike {
  const { dev, ino, size, mtimeMs, ctimeMs } = statSync(dbPath)
  const stamp = `${size}:${mtimeMs}:${ctimeMs}`
  // An idle store is read immutable; once its engine opens it again (a `-wal` appears), it is read live.
  const immutable = idleWalStore(dbPath)
  const cached = handles.get(dbPath)
  const timeout = Math.max(0, Math.trunc(busyTimeoutMs))
  // A writer can open, checkpoint, and close between polls, leaving no WAL. An immutable handle
  // never checks for writes itself, so reuse it only while the main file's fingerprint holds.
  if (cached && cached.dev === dev && cached.ino === ino && cached.immutable === immutable
    && (!immutable || cached.stamp === stamp)) {
    // A control lookup may have less time left than the optional reader that opened this handle.
    if (cached.busyTimeoutMs !== timeout) {
      cached.db.exec(`PRAGMA busy_timeout = ${timeout}`)
      cached.busyTimeoutMs = timeout
    }
    return cached.db
  }
  if (cached) dropHandle(dbPath)
  const url = pathToFileURL(dbPath)
  url.search = 'immutable=1'
  const db = new Database(immutable ? url : dbPath, { readOnly: true })
  // Not a write: the pragma is per-connection state, accepted on a read-only handle.
  db.exec(`PRAGMA busy_timeout = ${timeout}`)
  handles.set(dbPath, { db, dev, ino, immutable, stamp, busyTimeoutMs: timeout })
  return db
}

function dropHandle(dbPath: string): void {
  const handle = handles.get(dbPath)
  handles.delete(dbPath)
  try { handle?.db.close() } catch { /* already gone */ }
}

/** Test seam, and for a store that was replaced on disk: forget every open handle. */
export function closeSqliteHandles(): void {
  for (const path of [...handles.keys()]) dropHandle(path)
}

export function readBuiltin(
  Database: DatabaseConstructor,
  dbPath: string,
  sql: string,
  params: SqliteParam[],
  busyTimeoutMs: number,
): SqliteReadResult {
  try {
    const db = openHandle(Database, dbPath, busyTimeoutMs)
    return { ok: true, rows: db.prepare(sql).all(...params), via: 'builtin' }
  } catch (err) {
    // Locked, mid-checkpoint, the file replaced underneath the handle, not a database at all: every one
    // of these is "try again later" for a poller, and a handle that failed is not trusted again — the
    // next call reopens from the path.
    dropHandle(dbPath)
    return { ok: false, reason: 'transient', error: err instanceof Error ? err : new Error(String(err)) }
  }
}

/** Test seam: force the CLI path (or the built-in one) regardless of what this Node has. */
export function overrideBuiltinSqlite(value: DatabaseConstructor | null | undefined): void {
  builtin = value
}