refactor(cli): replace sql.js with node:sqlite

Drop the sql.js WASM dependency in favour of Node 22's built-in
node:sqlite (DatabaseSync). This eliminates the ~2 MB WASM binary,
removes the async init ceremony, and lets us open databases in
readonly mode directly on disk instead of loading them into memory.

Breaking: requires Node >= 22.5.0 (sqlite support).

- Remove sql.js from cli dependencies
- Rewrite sense-sqlite.ts to use DatabaseSync
- Update sense command (schema/query) — sync API, no more queryAsObjects
- Update tests to use node:sqlite directly
- Remove sql.js from tsup externals

小橘 🍊（NEKO Team）

.cursor/rules/no-dynamic-import.mdc

@@ -0,0 +1,34 @@
+---
+description: Ban dynamic import() in production code — use static imports instead
+globs: packages/*/src/**/*.ts
+alwaysApply: true
+---
+
+# No Dynamic Import in Production Code
+
+## Rule
+
+Do NOT use `await import()` or dynamic `import()` expressions in production source code.
+Always use static top-level `import` statements.
+
+## Why
+
+- Static imports enable tree-shaking and bundler optimizations
+- They make dependencies explicit and discoverable at a glance
+- Dynamic imports of Node built-ins or project modules add unnecessary async overhead
+
+## Exceptions (must include a comment explaining why)
+
+1. **`sense-runtime.ts`** — loads user-authored sense modules whose paths are only known at runtime
+2. **`workflow-worker.ts`** — loads user-authored workflow modules whose paths are only known at runtime
+
+When suppressing, add a comment directly above:
+
+```ts
+// Dynamic import required: user module path resolved at runtime
+const mod = await import(senseIndexPath);
+```
+
+## Test Files
+
+Test files (`__tests__/**`) are exempt — dynamic import after `vi.mock()` is standard vitest practice.

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/nerve-cli",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "type": "module",
   "bin": {
     "nerve": "dist/cli.js"
@@ -20,13 +20,12 @@
   },
   "dependencies": {
     "@uncaged/nerve-core": "workspace:*",
-    "better-sqlite3": "^11.10.0",
     "citty": "^0.1.6"
   },
   "devDependencies": {
-    "@uncaged/nerve-daemon": "workspace:*",
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.0.0",
+    "@uncaged/nerve-daemon": "workspace:*",
     "vitest": "^4.1.5"
   }
 }

packages/cli/src/__tests__/sense-sqlite.test.ts

@@ -5,8 +5,8 @@
 import { mkdirSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
 
-import Database from "better-sqlite3";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 
 import {
@@ -47,7 +47,7 @@ describe("assertSenseDbExists", () => {
 
   it("returns the path when the file exists", () => {
     const p = join(tmpDir, "data", "senses", "x.db");
-    new Database(p).close();
+    new DatabaseSync(p).close();
     expect(assertSenseDbExists(tmpDir, "x")).toBe(p);
   });
 });
@@ -55,9 +55,9 @@ describe("assertSenseDbExists", () => {
 describe("listTableSqlStatements", () => {
   it("returns CREATE statements ordered by tbl_name", () => {
     const p = join(tmpDir, "data", "senses", "t.db");
-    const db = new Database(p);
+    const db = new DatabaseSync(p);
-    db.exec("CREATE TABLE zebra (id INTEGER);");
+    db.exec("CREATE TABLE zebra (id INTEGER)");
-    db.exec("CREATE TABLE alpha (id INTEGER);");
+    db.exec("CREATE TABLE alpha (id INTEGER)");
     const stmts = listTableSqlStatements(db);
     db.close();
     expect(stmts).toHaveLength(2);
@@ -69,17 +69,17 @@ describe("listTableSqlStatements", () => {
 describe("pickDefaultPreviewTable", () => {
   it("prefers non-_migrations tables when both exist", () => {
     const p = join(tmpDir, "data", "senses", "t.db");
-    const db = new Database(p);
+    const db = new DatabaseSync(p);
-    db.exec(`CREATE TABLE _migrations (name TEXT PRIMARY KEY);
+    db.exec("CREATE TABLE _migrations (name TEXT PRIMARY KEY)");
-             CREATE TABLE readings (id INTEGER);`);
+    db.exec("CREATE TABLE readings (id INTEGER)");
     expect(pickDefaultPreviewTable(db)).toBe("readings");
     db.close();
   });
 
   it("uses _migrations when it is the only table", () => {
     const p = join(tmpDir, "data", "senses", "t.db");
-    const db = new Database(p);
+    const db = new DatabaseSync(p);
-    db.exec("CREATE TABLE _migrations (name TEXT PRIMARY KEY);");
+    db.exec("CREATE TABLE _migrations (name TEXT PRIMARY KEY)");
     expect(pickDefaultPreviewTable(db)).toBe("_migrations");
     db.close();
   });
@@ -140,12 +140,12 @@ describe("collectColumnKeys", () => {
 describe("readonly query integration", () => {
   it("runs default preview SQL on a real db", () => {
     const p = join(tmpDir, "data", "senses", "demo.db");
-    const rw = new Database(p);
+    const rw = new DatabaseSync(p);
-    rw.exec("CREATE TABLE items (id INTEGER PRIMARY KEY, v TEXT);");
+    rw.exec("CREATE TABLE items (id INTEGER PRIMARY KEY, v TEXT)");
-    rw.exec(`INSERT INTO items (v) VALUES ('a'), ('b');`);
+    rw.exec("INSERT INTO items (v) VALUES ('a'), ('b')");
     rw.close();
 
-    const db = new Database(p, { readonly: true, fileMustExist: true });
+    const db = new DatabaseSync(p, { readOnly: true });
     const table = pickDefaultPreviewTable(db);
     expect(table).toBe("items");
     if (table === null) {

packages/cli/src/commands/init.ts

@@ -1,5 +1,7 @@
+import { spawn, execFile } from "node:child_process";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { promisify } from "node:util";
 
 import { defineCommand } from "citty";
 
@@ -42,6 +44,8 @@ const GITIGNORE = `data/
 node_modules/
 `;
 
+const execFileAsync = promisify(execFile);
+
 const CPU_SCHEMA_TS = `import { integer, real, sqliteTable, text } from "drizzle-orm/sqlite-core";
 
 export const cpuUsage = sqliteTable("cpu_usage", {
@@ -90,7 +94,6 @@ function writeFile(filePath: string, content: string): void {
 }
 
 async function runCommand(cmd: string, args: string[], cwd: string): Promise<void> {
-  const { spawn } = await import("node:child_process");
   await new Promise<void>((resolve, reject) => {
     const child = spawn(cmd, args, { cwd, stdio: "inherit" });
     child.on("close", (code) => {
@@ -102,10 +105,6 @@ async function runCommand(cmd: string, args: string[], cwd: string): Promise<voi
 }
 
 async function detectPackageManager(): Promise<{ cmd: string; installArgs: string[] }> {
-  const { execFile } = await import("node:child_process");
-  const { promisify } = await import("node:util");
-  const execFileAsync = promisify(execFile);
-
   for (const pm of ["pnpm", "yarn", "npm"]) {
     try {
       await execFileAsync(pm, ["--version"]);
@@ -223,9 +222,6 @@ async function tryRequireSqlite(nerveRoot: string): Promise<boolean> {
   try {
     const modulePath = join(nerveRoot, "node_modules", "better-sqlite3");
     // Use a child process to test if the native module loads
-    const { execFile } = await import("node:child_process");
-    const { promisify } = await import("node:util");
-    const execFileAsync = promisify(execFile);
     await execFileAsync("node", ["-e", `require(${JSON.stringify(modulePath)})`], {
       cwd: nerveRoot,
       timeout: 10_000,

packages/cli/src/commands/sense.ts

@@ -1,8 +1,8 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
 
 import { type SenseInfo, parseNerveConfig } from "@uncaged/nerve-core";
-import Database from "better-sqlite3";
 import { defineCommand } from "citty";
 
 import { listSensesViaDaemon, triggerSenseViaDaemon } from "../daemon-client.js";
@@ -11,6 +11,7 @@ import {
   defaultPreviewSql,
   formatRowsAsAlignedTable,
   listTableSqlStatements,
+  openSenseDb,
   parseSenseQueryArgs,
   pickDefaultPreviewTable,
 } from "../sense-sqlite.js";
@@ -79,7 +80,6 @@ const senseListCommand = defineCommand({
   },
   async run() {
     if (!isRunning()) {
-      // Daemon not running — show static info from nerve.yaml
       process.stderr.write(
         "⚠️  Daemon is not running — showing static config only (no last signal time).\n\n",
       );
@@ -170,10 +170,9 @@ const senseSchemaCommand = defineCommand({
   },
   async run({ args }) {
     const nerveRoot = getNerveRoot();
-    let db: Database.Database | undefined;
+    let db: DatabaseSync | undefined;
     try {
-      const path = assertSenseDbExists(nerveRoot, args.name);
+      db = openSenseDb(nerveRoot, args.name);
-      db = new Database(path, { readonly: true, fileMustExist: true });
       const statements = listTableSqlStatements(db);
       if (args.json) {
         process.stdout.write(`${JSON.stringify(statements, null, 2)}\n`);
@@ -217,7 +216,7 @@ const senseQueryCommand = defineCommand({
   },
   async run({ args, rawArgs }) {
     const nerveRoot = getNerveRoot();
-    let db: Database.Database | undefined;
+    let db: DatabaseSync | undefined;
     try {
       let parsed: { name: string; sql: string | undefined };
       try {
@@ -228,8 +227,7 @@ const senseQueryCommand = defineCommand({
         process.exit(1);
       }
 
-      const path = assertSenseDbExists(nerveRoot, args.name);
+      db = openSenseDb(nerveRoot, args.name);
-      db = new Database(path, { readonly: true, fileMustExist: true });
 
       let sql = parsed.sql?.trim();
       if (!sql) {
@@ -242,8 +240,7 @@ const senseQueryCommand = defineCommand({
         }
       }
 
-      const stmt = db.prepare(sql);
+      const rows = db.prepare(sql).all() as Record<string, unknown>[];
-      const rows = stmt.all() as Record<string, unknown>[];
 
       if (args.json) {
         process.stdout.write(`${JSON.stringify(rows, null, 2)}\n`);

packages/cli/src/commands/start.ts

@@ -1,3 +1,4 @@
+import { spawn } from "node:child_process";
 import { createWriteStream, existsSync } from "node:fs";
 import { mkdir } from "node:fs/promises";
 import { dirname, join } from "node:path";
@@ -8,6 +9,7 @@ import { defineCommand } from "citty";
 import {
   getLogPath,
   getNerveRoot,
+  getSocketPath,
   isRunning,
   readPidFile,
   removePidFile,
@@ -64,7 +66,6 @@ async function runDaemon(nerveRoot: string): Promise<void> {
   const logPath = getLogPath();
   await mkdir(join(nerveRoot, "logs"), { recursive: true });
 
-  const { spawn } = await import("node:child_process");
   const logStream = createWriteStream(logPath, { flags: "a" });
   await new Promise<void>((resolve) => {
     if (logStream.pending) logStream.once("open", () => resolve());
@@ -90,7 +91,6 @@ async function runDaemon(nerveRoot: string): Promise<void> {
 
   writePidFile(pid);
 
-  const { getSocketPath } = await import("../workspace.js");
   const ready = await waitForSocket(getSocketPath(), 5000);
 
   if (!ready || !isRunning()) {

packages/cli/src/sense-sqlite.ts

@@ -1,7 +1,6 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-
+import { DatabaseSync } from "node:sqlite";
-import type Database from "better-sqlite3";
 
 /** SQLite path for a sense under the nerve workspace root. */
 export function senseDbPath(nerveRoot: string, senseName: string): string {
@@ -16,8 +15,14 @@ export function assertSenseDbExists(nerveRoot: string, senseName: string): strin
   return path;
 }
 
+/** Open a sense SQLite database in readonly mode using node:sqlite. */
+export function openSenseDb(nerveRoot: string, senseName: string): DatabaseSync {
+  const path = assertSenseDbExists(nerveRoot, senseName);
+  return new DatabaseSync(path, { readOnly: true });
+}
+
 /** `SELECT sql FROM sqlite_master WHERE type='table'` (non-null sql only). */
-export function listTableSqlStatements(db: Database.Database): string[] {
+export function listTableSqlStatements(db: DatabaseSync): string[] {
   const rows = db
     .prepare(
       `SELECT sql FROM sqlite_master WHERE type = 'table' AND sql IS NOT NULL ORDER BY tbl_name`,
@@ -30,7 +35,7 @@ export function listTableSqlStatements(db: Database.Database): string[] {
  * Table used for `nerve sense query <name>` with no SQL.
  * Prefers real data tables over `_migrations`, then lexicographic by name.
  */
-export function pickDefaultPreviewTable(db: Database.Database): string | null {
+export function pickDefaultPreviewTable(db: DatabaseSync): string | null {
   const row = db
     .prepare(
       `SELECT name FROM sqlite_master

packages/cli/tsup.config.ts

@@ -9,5 +9,5 @@ export default defineConfig({
     js: "#!/usr/bin/env node",
   },
   /** Daemon is loaded from workspace node_modules at runtime — never bundle it. */
-  external: ["@uncaged/nerve-daemon", "better-sqlite3"],
+  external: ["@uncaged/nerve-daemon"],
 });

packages/daemon/src/sense-runtime.ts

@@ -173,6 +173,7 @@ export async function loadComputeFn(senseIndexPath: string): Promise<Result<Comp
   let mod: unknown;
 
   try {
+    // Dynamic import required: user-authored sense module, path resolved at runtime
     mod = await import(senseIndexPath);
   } catch (e) {
     const msg = e instanceof Error ? e.message : String(e);

packages/daemon/src/workflow-worker.ts

@@ -198,6 +198,7 @@ async function loadWorkflowDefinition(
     );
   }
 
+  // Dynamic import required: user-authored workflow module, path resolved at runtime
   const mod = await import(indexPath);
   const def: unknown = mod.default ?? mod;
 

pnpm-lock.yaml

@@ -23,9 +23,6 @@ importers:
       '@uncaged/nerve-core':
         specifier: workspace:*
         version: link:../core
-      better-sqlite3:
-        specifier: ^11.10.0
-        version: 11.10.0
       citty:
         specifier: ^0.1.6
         version: 0.1.6
@@ -63,7 +60,7 @@ importers:
         version: 11.10.0
       drizzle-orm:
         specifier: ^0.43.1
-        version: 0.43.1(@types/better-sqlite3@7.6.13)(better-sqlite3@11.10.0)
+        version: 0.43.1(@types/better-sqlite3@7.6.13)(better-sqlite3@11.10.0)(sql.js@1.14.1)
       yaml:
         specifier: ^2.8.3
         version: 2.8.3
@@ -1074,6 +1071,9 @@ packages:
     resolution: {integrity: sha512-i5uvt8C3ikiWeNZSVZNWcfZPItFQOsYTUAOkcUPGd8DqDy1uOUikjt5dG+uRlwyvR108Fb9DOd4GvXfT0N2/uQ==}
     engines: {node: '>= 12'}
 
+  sql.js@1.14.1:
+    resolution: {integrity: sha512-gcj8zBWU5cFsi9WUP+4bFNXAyF1iRpA3LLyS/DP5xlrNzGmPIizUeBggKa8DbDwdqaKwUcTEnChtd2grWo/x/A==}
+
   stackback@0.0.2:
     resolution: {integrity: sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==}
 
@@ -1695,10 +1695,11 @@ snapshots:
 
   detect-libc@2.1.2: {}
 
-  drizzle-orm@0.43.1(@types/better-sqlite3@7.6.13)(better-sqlite3@11.10.0):
+  drizzle-orm@0.43.1(@types/better-sqlite3@7.6.13)(better-sqlite3@11.10.0)(sql.js@1.14.1):
     optionalDependencies:
       '@types/better-sqlite3': 7.6.13
       better-sqlite3: 11.10.0
+      sql.js: 1.14.1
 
   end-of-stream@1.4.5:
     dependencies:
@@ -2000,6 +2001,9 @@ snapshots:
 
   source-map@0.7.6: {}
 
+  sql.js@1.14.1:
+    optional: true
+
   stackback@0.0.2: {}
 
   std-env@4.1.0: {}