toiljs 0.0.59 → 0.0.61

package/build/cli/index.js

@@ -1666,12 +1666,12 @@ function gradientAt(t2) {
 }
 function gradientLine(line) {
   const n2 = line.length;
-  let out = "";
+  let out2 = "";
   for (let i2 = 0; i2 < n2; i2++) {
     const [r2, g, b] = gradientAt(n2 > 1 ? i2 / (n2 - 1) : 0);
-    out += `\x1B[38;2;${r2};${g};${b}m${line[i2]}`;
+    out2 += `\x1B[38;2;${r2};${g};${b}m${line[i2]}`;
   }
-  return out + "\x1B[39m";
+  return out2 + "\x1B[39m";
 }
 function version() {
   try {
@@ -2010,6 +2010,7 @@ function isPackageManager(pm) {
 }
 
 // src/cli/create.ts
+var MIGRATIONS_README = "# migrations/\n\nToilDB schema migrations. One file per evolving `@data` value type, named `<Type>.migration.ts`\n(e.g. `User.migration.ts`).\n\nEach file keeps the OLD `@data` shapes (e.g. `UserV1`) alongside the `@migrate` transform(s) that\ncarry old records forward, and imports the CURRENT value type from the app. The build\nauto-discovers every `*.migration.ts` under the project.\n\nDo NOT put `@migrate` anywhere else: a `@migrate` outside a `*.migration.ts` file in a\n`migrations/` folder is a compile error.\n\n## Example\n\n`User.migration.ts`:\n\n```ts\nimport { User } from '../models/User';\n\n// The previous on-disk shape of a User record.\n@data\nexport class UserV1 {\n    name: string = '';\n}\n\n// Carry a UserV1 forward into the current User. Runs once per record on read.\n@migrate\nexport function up(old: UserV1, into: User): void {\n    into.name = old.name;\n}\n```\n";
 var PREPROCESSOR_LABEL2 = {
   css: "Plain CSS",
   sass: "Sass (SCSS)",
@@ -2038,7 +2039,7 @@ function scaffold(name, template, features, aiTools, images) {
     "@types/react-dom": "^19.2.3",
     eslint: "^10.2.0",
     prettier: "^3.8.1",
-    toilscript: "^0.1.36",
+    toilscript: "^0.1.37",
     typescript: "^6.0.3"
   };
   for (const dep of requiredPackages(features).sort()) {
@@ -2079,8 +2080,8 @@ export default defineConfig({
     ".prettierrc": '"toiljs/prettier"\n',
     // Generated files don't need formatting. (toilscript server decorators like @main /
     // @remote-on-functions are handled by the toiljs/prettier-plugin, so server/ is not ignored.)
-    ".prettierignore": "node_modules\nbuild\n.toil\nshared/server.ts\ntoil-env.d.ts\ntoil-routes.d.ts\nserver/_emails.ts\nserver/toil-server-env.d.ts\n",
-    ".gitignore": "node_modules\nbuild\n.toil\nshared/server.ts\ntoil-env.d.ts\ntoil-routes.d.ts\nhosts/*/_tmpl/\n# Local dev env vars/secrets (never commit)\n.env\n.env.secrets\n",
+    ".prettierignore": "node_modules\nbuild\n.toil\nshared/server.ts\ntoil-env.d.ts\ntoil-routes.d.ts\nserver/_emails.ts\nserver/_ssr/\nserver/toil-server-env.d.ts\n",
+    ".gitignore": "node_modules\nbuild\n.toil\nshared/server.ts\ntoil-env.d.ts\ntoil-routes.d.ts\nserver/_ssr/\nhosts/*/_tmpl/\n# Local dev env vars/secrets (never commit)\n.env\n.env.secrets\n",
     // Use the project's pinned TypeScript (node_modules) instead of VS Code's bundled
     // version, and prompt to switch, so the editor loads the toilscript LS plugin wired
     // in server/tsconfig.json (which clears the @database / @data editor false positives).
@@ -2170,7 +2171,11 @@ export default defineConfig({
       "",
       "    npm run build",
       ""
-    ].join("\n")
+    ].join("\n"),
+    // ToilDB migrations live under server/migrations/ (folder + `*.migration.ts` is enforced by
+    // the compiler; the build auto-discovers them). Ship the folder, documented, with no live
+    // *.migration.ts: a @migrate referencing types a fresh project lacks would break the build.
+    "server/migrations/README.md": MIGRATIONS_README
   };
   if (template === "minimal") {
     Object.assign(files, minimalClient(name, features));
@@ -2223,7 +2228,7 @@ function minimalServer() {
     "server/toil-server-env.d.ts": TOIL_SERVER_ENV_DTS,
     "server/core/AppHandler.ts": "import { ToilHandler, Request, Response, Method } from 'toiljs/server/runtime';\n\n/** Every request enters here. Add `@rest` controllers under routes/ as you grow. */\nexport class AppHandler extends ToilHandler {\n    public handle(req: Request): Response {\n        if (req.method != Method.GET && req.method != Method.HEAD) {\n            return Response.empty(405).setHeader('allow', 'GET, HEAD');\n        }\n        if (req.path == '/api/hello') {\n            return Response.text('hello from toiljs\\n');\n        }\n        if (req.path == '/api/hash') {\n            // `crypto` is a global (no import), synchronous Web Crypto.\n            return Response.text(crypto.toHex(crypto.sha256Text(req.path)) + '\\n');\n        }\n        // Yield page routes and assets to the client: under `toiljs dev`\n        // this falls through to Vite so the app renders at /.\n        return Response.unhandled();\n    }\n}\n",
     "server/main.ts": "import { Server } from 'toiljs/server/runtime';\nimport { revertOnError } from 'toiljs/server/runtime/abort/abort';\n\nimport { AppHandler } from './core/AppHandler';\n\n// As you add surface modules (@rest routes, @service/@remote RPC), import them here\n// so a direct `toilscript` run builds the same server `toiljs build` does, e.g.:\n//   import './routes/Players';\n\n// Wire your handler here.\nServer.handler = () => new AppHandler();\n\n// Required: re-export the WASM entry points and the abort hook.\nexport * from 'toiljs/server/runtime/exports';\nexport function abort(message: string, fileName: string, line: u32, column: u32): void {\n    revertOnError(message, fileName, line, column);\n}\n",
-    "server/README.md": "# server/\n\nYour ToilScript backend, compiled to a single WebAssembly module. One folder per concern:\n\n| Folder | What lives here |\n| --- | --- |\n| `main.ts` | The entry point: wires the handler and imports the surface modules. |\n| `core/` | The request handler and shared app logic (state, helpers). |\n| `models/` | `@data` classes, the typed wire model shared by HTTP and RPC. One type per file. |\n| `routes/` | `@rest` controllers (HTTP). One controller per file, named after its class. |\n| `services/` | `@service` classes and free `@remote` functions (typed RPC). |\n| `scheduled/` | Reserved for scheduled tasks (not shipped yet). |\n\nNew decorated files are picked up automatically by `toiljs build`/`dev`; also add an import\nin `main.ts` so a direct `toilscript` run builds the same server.\n"
+    "server/README.md": "# server/\n\nYour ToilScript backend, compiled to a single WebAssembly module. One folder per concern:\n\n| Folder | What lives here |\n| --- | --- |\n| `main.ts` | The entry point: wires the handler and imports the surface modules. |\n| `core/` | The request handler and shared app logic (state, helpers). |\n| `models/` | `@data` classes, the typed wire model shared by HTTP and RPC. One type per file. |\n| `migrations/` | ToilDB schema migrations: a `<Type>.migration.ts` per evolving `@data` value type, holding the old shapes + the `@migrate` transform. |\n| `routes/` | `@rest` controllers (HTTP). One controller per file, named after its class. |\n| `services/` | `@service` classes and free `@remote` functions (typed RPC). |\n| `scheduled/` | Reserved for scheduled tasks (not shipped yet). |\n\nNew decorated files are picked up automatically by `toiljs build`/`dev`; also add an import\nin `main.ts` so a direct `toilscript` run builds the same server.\n"
   };
 }
 function minimalClient(name, features) {
@@ -2528,10 +2533,137 @@ async function runCreate(opts) {
   outro(`Created ${accent(path4.basename(name))}, happy building! ${dim("(v" + version() + ")")}`);
 }
 
-// src/cli/doctor.ts
+// src/cli/db.ts
 import fs4 from "node:fs";
-import { createRequire } from "node:module";
 import path5 from "node:path";
+var FAMILIES = ["store", "views", "members", "counters", "events", "eventDedup", "capacity"];
+function devdataPath(opts) {
+  return path5.join(path5.resolve(opts.root ?? process.cwd()), ".toil", "devdata.json");
+}
+function out(line) {
+  process.stdout.write(line + "\n");
+}
+function familyCounts(file) {
+  let snap;
+  try {
+    snap = JSON.parse(fs4.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+  const counts = {};
+  for (const f of FAMILIES) {
+    const fam = snap[f];
+    counts[f] = fam && typeof fam === "object" ? Object.keys(fam).length : 0;
+  }
+  return counts;
+}
+function isSnapshot(v) {
+  return typeof v === "object" && v !== null && FAMILIES.every((f) => f in v);
+}
+function runDb(action, fileArg, opts) {
+  const file = devdataPath(opts);
+  const rel = path5.relative(process.cwd(), file) || file;
+  switch (action) {
+    case "reset":
+    case "purge": {
+      if (!fs4.existsSync(file)) {
+        out(dim(`  dev database already empty (${rel} not found)`));
+        return;
+      }
+      fs4.rmSync(file);
+      out(success("  \u2713 ") + "dev database reset " + dim(`(${rel} deleted)`));
+      return;
+    }
+    case "export": {
+      if (!fs4.existsSync(file)) {
+        out(warn("  ! ") + `nothing to export (${rel} not found)`);
+        process.exitCode = 1;
+        return;
+      }
+      let pretty;
+      try {
+        pretty = JSON.stringify(JSON.parse(fs4.readFileSync(file, "utf8")), null, 2) + "\n";
+      } catch {
+        out(danger("  \u2717 ") + `the dev database at ${rel} is unreadable`);
+        process.exitCode = 1;
+        return;
+      }
+      if (fileArg === void 0) {
+        process.stdout.write(pretty);
+        return;
+      }
+      fs4.writeFileSync(path5.resolve(fileArg), pretty);
+      out(success("  \u2713 ") + "exported dev database to " + dim(fileArg));
+      return;
+    }
+    case "import": {
+      if (fileArg === void 0) {
+        out(danger("  \u2717 ") + "usage: " + dim("toiljs db import <file>"));
+        process.exitCode = 1;
+        return;
+      }
+      let parsed;
+      try {
+        parsed = JSON.parse(fs4.readFileSync(path5.resolve(fileArg), "utf8"));
+      } catch (e) {
+        out(danger("  \u2717 ") + `cannot read/parse ${fileArg}: ${e.message}`);
+        process.exitCode = 1;
+        return;
+      }
+      if (!isSnapshot(parsed)) {
+        out(danger("  \u2717 ") + `${fileArg} is not a toiljs dev database snapshot`);
+        process.exitCode = 1;
+        return;
+      }
+      fs4.mkdirSync(path5.dirname(file), { recursive: true });
+      fs4.writeFileSync(file, JSON.stringify(parsed));
+      out(success("  \u2713 ") + `imported dev database from ${dim(fileArg)} ` + dim(`(${rel})`));
+      return;
+    }
+    case "path":
+      out(file);
+      return;
+    case "status":
+    case "info": {
+      out(bold("  dev database") + dim(`  ${rel}`));
+      if (!fs4.existsSync(file)) {
+        out(dim("  (empty \u2014 no data written yet; run the dev server to populate it)"));
+        return;
+      }
+      const counts = familyCounts(file);
+      if (counts === null) {
+        out(danger("  \u2717 unreadable snapshot"));
+        process.exitCode = 1;
+        return;
+      }
+      out(dim(`  ${(fs4.statSync(file).size / 1024).toFixed(1)} KiB`));
+      const nonEmpty = FAMILIES.filter((f) => counts[f] > 0);
+      if (nonEmpty.length === 0) out(dim("  (no rows)"));
+      else for (const f of nonEmpty) out("  " + accent(f.padEnd(12)) + String(counts[f]));
+      return;
+    }
+    default:
+      out(
+        [
+          bold("Usage") + "  " + dim("toiljs db") + " <action>",
+          "",
+          bold("Actions"),
+          "  " + accent("status".padEnd(16)) + dim("show the dev DB path + per-family row counts"),
+          "  " + accent("reset".padEnd(16)) + dim("delete all dev data (alias: purge)"),
+          "  " + accent("export [file]".padEnd(16)) + dim("write a snapshot to <file> (or stdout)"),
+          "  " + accent("import <file>".padEnd(16)) + dim("replace the dev DB with a snapshot"),
+          "  " + accent("path".padEnd(16)) + dim("print the devdata.json path")
+        ].join("\n")
+      );
+      if (action !== void 0) process.exitCode = 1;
+      return;
+  }
+}
+
+// src/cli/doctor.ts
+import fs5 from "node:fs";
+import { createRequire } from "node:module";
+import path6 from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 import {
   loadConfig as loadConfig2,
@@ -2879,6 +3011,15 @@ function checkServerTsPlugin(present) {
     fix: 'Run `toiljs doctor --fix` to add { "plugins": [{ "name": "toilscript/std/ts-plugin.cjs" }] } to your server tsconfig, then pick the workspace TypeScript version and restart the TS server.'
   };
 }
+function checkMigrationsDir(exists) {
+  return exists ? { id: "migrations-dir", label: "server/migrations/ directory", status: "pass" } : {
+    id: "migrations-dir",
+    label: "server/migrations/ directory",
+    status: "warn",
+    detail: "no server/migrations/ folder; ToilDB @migrate functions must live in a *.migration.ts file under it",
+    fix: "Create server/migrations/ (one <Type>.migration.ts per evolving @data value type), or run `toiljs update` to add it."
+  };
+}
 function checkAuthSecrets(f) {
   if (!f.usesAuth || f.sessionSecretSet) {
     return { id: "auth-secrets", label: "Session secret", status: "pass" };
@@ -2911,7 +3052,7 @@ function hasFailures(summary) {
 // src/cli/doctor.ts
 function readJsonObject(file) {
   try {
-    const parsed = JSON.parse(fs4.readFileSync(file, "utf8"));
+    const parsed = JSON.parse(fs5.readFileSync(file, "utf8"));
     return typeof parsed === "object" && parsed !== null ? parsed : null;
   } catch {
     return null;
@@ -2919,22 +3060,22 @@ function readJsonObject(file) {
 }
 function stringRecord(value) {
   if (typeof value !== "object" || value === null) return {};
-  const out = {};
-  for (const [k, v] of Object.entries(value)) if (typeof v === "string") out[k] = v;
-  return out;
+  const out2 = {};
+  for (const [k, v] of Object.entries(value)) if (typeof v === "string") out2[k] = v;
+  return out2;
 }
 function readFile(file) {
   try {
-    return fs4.readFileSync(file, "utf8");
+    return fs5.readFileSync(file, "utf8");
   } catch {
     return null;
   }
 }
 function writeFile(file, content) {
-  fs4.writeFileSync(file, content);
+  fs5.writeFileSync(file, content);
 }
 function isPackageInstalled(root, name) {
-  const require2 = createRequire(path5.join(root, "package.json"));
+  const require2 = createRequire(path6.join(root, "package.json"));
   for (const id of [`${name}/package.json`, name]) {
     try {
       require2.resolve(id);
@@ -2943,8 +3084,8 @@ function isPackageInstalled(root, name) {
     }
   }
   for (let dir = root; ; ) {
-    if (fs4.existsSync(path5.join(dir, "node_modules", name, "package.json"))) return true;
-    const parent = path5.dirname(dir);
+    if (fs5.existsSync(path6.join(dir, "node_modules", name, "package.json"))) return true;
+    const parent = path6.dirname(dir);
     if (parent === dir) return false;
     dir = parent;
   }
@@ -2959,14 +3100,14 @@ function looksLikeSemverRange(range) {
   return /^\s*[v^~>=<]*\s*\d+\.\d+/.test(range);
 }
 function gatherRpcFacts(root) {
-  const pkg = readJsonObject(path5.join(root, "package.json"));
+  const pkg = readJsonObject(path6.join(root, "package.json"));
   const scripts = pkg ? stringRecord(pkg.scripts) : {};
   const deps = {
     ...pkg ? stringRecord(pkg.dependencies) : {},
     ...pkg ? stringRecord(pkg.devDependencies) : {}
   };
-  const tsconfig = readJsonObject(path5.join(root, "tsconfig.json"));
-  const gitignore = readFile(path5.join(root, ".gitignore"));
+  const tsconfig = readJsonObject(path6.join(root, "tsconfig.json"));
+  const gitignore = readFile(path6.join(root, ".gitignore"));
   const buildServerWired = [scripts["build:server"], scripts["build"]].some(
     (s) => typeof s === "string" && s.includes("--rpcModule")
   );
@@ -2985,31 +3126,31 @@ function gatherRpcFacts(root) {
 function serverSources(root, toilconfig) {
   const dirs = /* @__PURE__ */ new Set();
   const entries = Array.isArray(toilconfig?.entries) ? toilconfig.entries.filter((e) => typeof e === "string") : [];
-  for (const e of entries) dirs.add(path5.dirname(path5.resolve(root, e)));
-  const out = [];
+  for (const e of entries) dirs.add(path6.dirname(path6.resolve(root, e)));
+  const out2 = [];
   const cap = 200;
   const maxDepth = 16;
   const visit = (current, depth) => {
-    if (out.length >= cap || depth > maxDepth) return;
+    if (out2.length >= cap || depth > maxDepth) return;
     let listing;
     try {
-      listing = fs4.readdirSync(current, { withFileTypes: true });
+      listing = fs5.readdirSync(current, { withFileTypes: true });
     } catch {
       return;
     }
     for (const entry of listing) {
-      if (out.length >= cap) break;
-      const full = path5.join(current, entry.name);
+      if (out2.length >= cap) break;
+      const full = path6.join(current, entry.name);
       if (entry.isDirectory()) {
         if (entry.name !== "node_modules") visit(full, depth + 1);
       } else if (entry.name.endsWith(".ts") && !entry.name.endsWith(".d.ts")) {
         const src = readFile(full);
-        if (src !== null) out.push(src);
+        if (src !== null) out2.push(src);
       }
     }
   };
   for (const dir of dirs) visit(dir, 0);
-  return out;
+  return out2;
 }
 function gatherRestFacts(root, toilconfig) {
   let hasControllers = false;
@@ -3023,7 +3164,7 @@ function gatherRestFacts(root, toilconfig) {
   return { hasControllers, dispatched };
 }
 function secretDefined(root, key) {
-  const raw = readFile(path5.join(root, ".env.secrets"));
+  const raw = readFile(path6.join(root, ".env.secrets"));
   if (raw === null) return false;
   return new RegExp(`^\\s*(?:export\\s+)?${key}\\s*=\\s*\\S`, "m").test(raw);
 }
@@ -3041,14 +3182,24 @@ var TS_PLUGIN_NAME = "toilscript/std/ts-plugin.cjs";
 function serverTsconfigPath(root, toilconfig) {
   const dirs = /* @__PURE__ */ new Set();
   const entries = Array.isArray(toilconfig?.entries) ? toilconfig.entries.filter((e) => typeof e === "string") : [];
-  for (const e of entries) dirs.add(path5.dirname(path5.resolve(root, e)));
-  if (dirs.size === 0) dirs.add(path5.join(root, "server"));
+  for (const e of entries) dirs.add(path6.dirname(path6.resolve(root, e)));
+  if (dirs.size === 0) dirs.add(path6.join(root, "server"));
   for (const dir of dirs) {
-    const p = path5.join(dir, "tsconfig.json");
-    if (fs4.existsSync(p)) return p;
+    const p = path6.join(dir, "tsconfig.json");
+    if (fs5.existsSync(p)) return p;
   }
   return null;
 }
+function serverMigrationsExist(root, toilconfig) {
+  const dirs = /* @__PURE__ */ new Set();
+  const entries = Array.isArray(toilconfig?.entries) ? toilconfig.entries.filter((e) => typeof e === "string") : [];
+  for (const e of entries) dirs.add(path6.dirname(path6.resolve(root, e)));
+  if (dirs.size === 0) dirs.add(path6.join(root, "server"));
+  for (const dir of dirs) {
+    if (fs5.existsSync(path6.join(dir, "migrations"))) return true;
+  }
+  return false;
+}
 function tsconfigHasToilPlugin(tsconfig) {
   const plugins = asRecord(tsconfig?.compilerOptions)?.plugins;
   if (!Array.isArray(plugins)) return false;
@@ -3060,7 +3211,7 @@ function tsconfigHasToilPlugin(tsconfig) {
 function applyRpcFix(root) {
   const changed = [];
   const skipped = [];
-  const pkgPath = path5.join(root, "package.json");
+  const pkgPath = path6.join(root, "package.json");
   const pkgRaw = readFile(pkgPath);
   const pkg = pkgRaw !== null ? readJsonObject(pkgPath) : null;
   if (pkg !== null) {
@@ -3099,7 +3250,7 @@ function applyRpcFix(root) {
   } else if (pkgRaw !== null) {
     skipped.push("package.json (unparseable)");
   }
-  const tsPath = path5.join(root, "tsconfig.json");
+  const tsPath = path6.join(root, "tsconfig.json");
   const tsRaw = readFile(tsPath);
   const tsconfig = tsRaw !== null ? readJsonObject(tsPath) : null;
   if (tsconfig !== null) {
@@ -3138,7 +3289,7 @@ function applyRpcFix(root) {
   } else if (tsRaw !== null) {
     skipped.push('tsconfig.json (JSON with comments, add "shared" + paths by hand)');
   }
-  const giPath = path5.join(root, ".gitignore");
+  const giPath = path6.join(root, ".gitignore");
   const giRaw = readFile(giPath);
   if (giRaw === null) {
     writeFile(giPath, `${RPC_GITIGNORE_LINE}
@@ -3150,21 +3301,21 @@ function applyRpcFix(root) {
 `);
     changed.push(".gitignore");
   }
-  const serverToilconfig = readJsonObject(path5.join(root, "toilconfig.json"));
+  const serverToilconfig = readJsonObject(path6.join(root, "toilconfig.json"));
   if (serverToilconfig !== null) {
     const entries = Array.isArray(serverToilconfig.entries) ? serverToilconfig.entries.filter(
       (e) => typeof e === "string"
     ) : [];
     const dirs = /* @__PURE__ */ new Set();
-    for (const e of entries) dirs.add(path5.dirname(path5.resolve(root, e)));
-    if (dirs.size === 0) dirs.add(path5.join(root, "server"));
+    for (const e of entries) dirs.add(path6.dirname(path6.resolve(root, e)));
+    if (dirs.size === 0) dirs.add(path6.join(root, "server"));
     for (const dir of dirs) {
-      const envPath = path5.join(dir, "toil-server-env.d.ts");
+      const envPath = path6.join(dir, "toil-server-env.d.ts");
       if (readFile(envPath) !== TOIL_SERVER_ENV_DTS2) {
         try {
-          fs4.mkdirSync(dir, { recursive: true });
+          fs5.mkdirSync(dir, { recursive: true });
           writeFile(envPath, TOIL_SERVER_ENV_DTS2);
-          changed.push(path5.relative(root, envPath));
+          changed.push(path6.relative(root, envPath));
         } catch {
         }
       }
@@ -3194,7 +3345,7 @@ function prettierPluginPresent(root, pkg) {
     return true;
   }
   for (const name of PRETTIER_CONFIG_FILES) {
-    const raw = readFile(path5.join(root, name));
+    const raw = readFile(path6.join(root, name));
     if (raw !== null && PRETTIER_MENTION.test(raw)) return true;
   }
   return false;
@@ -3203,7 +3354,7 @@ function applyPrettierFix(root, pkg) {
   const changed = [];
   const skipped = [];
   if (prettierPluginPresent(root, pkg)) return { changed, skipped };
-  const pkgPath = path5.join(root, "package.json");
+  const pkgPath = path6.join(root, "package.json");
   const pkgConfig = pkg ? asRecord(pkg.prettier) : null;
   if (pkgConfig !== null) {
     const full = readJsonObject(pkgPath);
@@ -3219,7 +3370,7 @@ function applyPrettierFix(root, pkg) {
     }
   }
   for (const name of [".prettierrc", ".prettierrc.json"]) {
-    const filePath = path5.join(root, name);
+    const filePath = path6.join(root, name);
     const raw = readFile(filePath);
     if (raw === null) continue;
     const obj = readJsonObject(filePath);
@@ -3232,13 +3383,13 @@ function applyPrettierFix(root, pkg) {
     changed.push(name);
     return { changed, skipped };
   }
-  const jsConfig = PRETTIER_CONFIG_FILES.find((name) => readFile(path5.join(root, name)) !== null);
+  const jsConfig = PRETTIER_CONFIG_FILES.find((name) => readFile(path6.join(root, name)) !== null);
   if (jsConfig) {
     skipped.push(`${jsConfig} (add "${PRETTIER_PLUGIN}" to its plugins by hand)`);
     return { changed, skipped };
   }
   writeFile(
-    path5.join(root, ".prettierrc.json"),
+    path6.join(root, ".prettierrc.json"),
     JSON.stringify({ plugins: [PRETTIER_PLUGIN] }, null, 4) + "\n"
   );
   changed.push(".prettierrc.json");
@@ -3251,7 +3402,7 @@ function applyServerEditorFix(root, toilconfig) {
   if (tsPath === null) {
     skipped.push("server/tsconfig.json (not found; add the toilscript ts-plugin by hand)");
   } else {
-    const rel = path5.relative(root, tsPath);
+    const rel = path6.relative(root, tsPath);
     const raw = readFile(tsPath);
     const parsed = raw !== null ? readJsonObject(tsPath) : null;
     if (parsed === null) {
@@ -3265,7 +3416,7 @@ function applyServerEditorFix(root, toilconfig) {
       changed.push(rel);
     }
   }
-  const vsPath = path5.join(root, ".vscode", "settings.json");
+  const vsPath = path6.join(root, ".vscode", "settings.json");
   const vsRaw = readFile(vsPath);
   const vs = vsRaw !== null ? readJsonObject(vsPath) : {};
   if (vs === null) {
@@ -3281,7 +3432,7 @@ function applyServerEditorFix(root, toilconfig) {
       touched = true;
     }
     if (touched) {
-      fs4.mkdirSync(path5.dirname(vsPath), { recursive: true });
+      fs5.mkdirSync(path6.dirname(vsPath), { recursive: true });
       writeFile(vsPath, JSON.stringify(vs, null, 4) + "\n");
       changed.push(".vscode/settings.json");
     }
@@ -3289,8 +3440,8 @@ function applyServerEditorFix(root, toilconfig) {
   return { changed, skipped };
 }
 function frameworkMeta() {
-  const pkgPath = path5.resolve(
-    path5.dirname(fileURLToPath3(import.meta.url)),
+  const pkgPath = path6.resolve(
+    path6.dirname(fileURLToPath3(import.meta.url)),
     "..",
     "..",
     "package.json"
@@ -3303,34 +3454,34 @@ function frameworkMeta() {
 var LOCKFILES = ["package-lock.json", "pnpm-lock.yaml", "yarn.lock", "bun.lockb"];
 function readEntry(clientAbsDir) {
   for (const name of ["toil.tsx", "toil.jsx", "main.tsx", "main.jsx"]) {
-    const source = readFile(path5.join(clientAbsDir, name));
+    const source = readFile(path6.join(clientAbsDir, name));
     if (source !== null && /toiljs\/routes|\bmount\s*\(/.test(source)) return source;
   }
   return null;
 }
 function collectSources(root, dir, cap) {
-  const out = [];
+  const out2 = [];
   const visit = (current) => {
-    if (out.length >= cap) return;
+    if (out2.length >= cap) return;
     let entries;
     try {
-      entries = fs4.readdirSync(current, { withFileTypes: true });
+      entries = fs5.readdirSync(current, { withFileTypes: true });
     } catch {
       return;
     }
     for (const entry of entries) {
-      if (out.length >= cap) break;
-      const full = path5.join(current, entry.name);
+      if (out2.length >= cap) break;
+      const full = path6.join(current, entry.name);
       if (entry.isDirectory()) {
         if (entry.name !== "node_modules") visit(full);
       } else if (/\.(tsx|jsx)$/.test(entry.name)) {
         const source = readFile(full);
-        if (source !== null) out.push({ path: path5.relative(root, full), source });
+        if (source !== null) out2.push({ path: path6.relative(root, full), source });
       }
     }
   };
   visit(dir);
-  return out;
+  return out2;
 }
 function glyph(status) {
   if (status === "pass") return success("\u2713");
@@ -3339,31 +3490,31 @@ function glyph(status) {
 }
 function renderHuman(groups) {
   const summary = summarize(groups);
-  const out = [];
+  const out2 = [];
   for (const group of groups) {
-    out.push("  " + bold(group.title));
+    out2.push("  " + bold(group.title));
     for (const check of group.checks) {
       let line = `    ${glyph(check.status)} ${check.label}`;
       if (check.detail) line += dim(`  ${check.detail}`);
-      out.push(line);
+      out2.push(line);
       if (check.fix && check.status !== "pass")
-        out.push("       " + dim(`fix: ${check.fix}`));
+        out2.push("       " + dim(`fix: ${check.fix}`));
     }
-    out.push("");
+    out2.push("");
   }
   const parts = [success(`${String(summary.pass)} passed`)];
   if (summary.warn > 0) {
     parts.push(warn(`${String(summary.warn)} warning${summary.warn === 1 ? "" : "s"}`));
   }
   if (summary.fail > 0) parts.push(danger(`${String(summary.fail)} failed`));
-  out.push("  " + parts.join(dim(", ")));
-  out.push("");
-  process.stdout.write(out.join("\n") + "\n");
+  out2.push("  " + parts.join(dim(", ")));
+  out2.push("");
+  process.stdout.write(out2.join("\n") + "\n");
 }
 async function runDoctor(opts) {
-  const root = path5.resolve(opts.root ?? opts.cwd);
+  const root = path6.resolve(opts.root ?? opts.cwd);
   const meta = frameworkMeta();
-  const projectPkg = readJsonObject(path5.join(root, "package.json"));
+  const projectPkg = readJsonObject(path6.join(root, "package.json"));
   const deps = {
     ...projectPkg ? stringRecord(projectPkg.dependencies) : {},
     ...projectPkg ? stringRecord(projectPkg.devDependencies) : {}
@@ -3375,11 +3526,11 @@ async function runDoctor(opts) {
   } catch (err) {
     configError = err instanceof Error ? err.message : String(err);
   }
-  const clientAbsDir = cfg ? cfg.clientAbsDir : path5.join(root, "client");
-  const routesAbsDir = cfg ? cfg.routesAbsDir : path5.join(clientAbsDir, "routes");
-  const publicDir = cfg ? cfg.publicDir : path5.join(clientAbsDir, "public");
+  const clientAbsDir = cfg ? cfg.clientAbsDir : path6.join(root, "client");
+  const routesAbsDir = cfg ? cfg.routesAbsDir : path6.join(clientAbsDir, "routes");
+  const publicDir = cfg ? cfg.publicDir : path6.join(clientAbsDir, "public");
   const entrySource = readEntry(clientAbsDir);
-  const indexHtml = readFile(path5.join(publicDir, "index.html"));
+  const indexHtml = readFile(path6.join(publicDir, "index.html"));
   const routes = scanRoutes(routesAbsDir);
   const mainPatterns = routes.filter((r2) => r2.slot === void 0).map((r2) => r2.pattern);
   const assetIssues = findRelativeAssets(collectSources(root, clientAbsDir, 200));
@@ -3392,14 +3543,14 @@ async function runDoctor(opts) {
   }
   const ppPkg = preprocessorImported ? PREPROCESSOR_PKG[preprocessorImported] : null;
   const preprocessorInstalled = ppPkg === null || ppPkg in deps;
-  const toilconfig = readJsonObject(path5.join(root, "toilconfig.json"));
+  const toilconfig = readJsonObject(path6.join(root, "toilconfig.json"));
   const serverPresent = toilconfig !== null;
   let missingEntries = [];
   let toilscriptInstalled = false;
   let wasmExists = false;
   if (toilconfig) {
     const entries = Array.isArray(toilconfig.entries) ? toilconfig.entries.filter((e) => typeof e === "string") : [];
-    missingEntries = entries.filter((e) => !fs4.existsSync(path5.join(root, e)));
+    missingEntries = entries.filter((e) => !fs5.existsSync(path6.join(root, e)));
     toilscriptInstalled = isPackageInstalled(root, "toilscript");
     const targets = typeof toilconfig.targets === "object" && toilconfig.targets !== null ? toilconfig.targets : {};
     const outFiles = [];
@@ -3409,10 +3560,10 @@ async function runDoctor(opts) {
         if (typeof outFile === "string") outFiles.push(outFile);
       }
     }
-    wasmExists = outFiles.some((f) => fs4.existsSync(path5.join(root, f)));
+    wasmExists = outFiles.some((f) => fs5.existsSync(path6.join(root, f)));
     if (!wasmExists && outFiles.length === 0) {
       try {
-        wasmExists = fs4.readdirSync(path5.join(root, "build", "server")).some((f) => f.endsWith(".wasm"));
+        wasmExists = fs5.readdirSync(path6.join(root, "build", "server")).some((f) => f.endsWith(".wasm"));
       } catch {
         wasmExists = false;
       }
@@ -3428,7 +3579,7 @@ async function runDoctor(opts) {
   const authFacts = gatherAuthFacts(root, toilconfig);
   const prettierPresent = prettierPluginPresent(
     root,
-    readJsonObject(path5.join(root, "package.json"))
+    readJsonObject(path6.join(root, "package.json"))
   );
   const serverTsPath = serverPresent ? serverTsconfigPath(root, toilconfig) : null;
   const serverTsParsed = serverTsPath ? readJsonObject(serverTsPath) : null;
@@ -3452,7 +3603,7 @@ async function runDoctor(opts) {
         checkNode(process.versions.node, meta.node),
         checkToiljsInstalled("toiljs" in deps ? version() : null),
         ...peerChecks,
-        checkPackageManager(LOCKFILES.filter((f) => fs4.existsSync(path5.join(root, f))))
+        checkPackageManager(LOCKFILES.filter((f) => fs5.existsSync(path6.join(root, f))))
       ]
     },
     {
@@ -3461,13 +3612,13 @@ async function runDoctor(opts) {
         checkDir(
           "client-dir",
           "client/ directory",
-          fs4.existsSync(clientAbsDir),
+          fs5.existsSync(clientAbsDir),
           "Create a client/ directory for your app."
         ),
         checkDir(
           "routes-dir",
           "routes/ directory",
-          fs4.existsSync(routesAbsDir),
+          fs5.existsSync(routesAbsDir),
           "Create client/routes/ and add an index.tsx."
         ),
         checkRootElement(indexHtml),
@@ -3502,7 +3653,8 @@ async function runDoctor(opts) {
         checkRpcWiring(rpcFacts),
         checkRestDispatch(restFacts),
         checkPrettierPlugin(prettierPresent),
-        checkServerTsPlugin(serverTsPluginPresent)
+        checkServerTsPlugin(serverTsPluginPresent),
+        checkMigrationsDir(serverMigrationsExist(root, toilconfig))
       ] : [checkToilconfig(false)]
     }
   ];
@@ -3525,30 +3677,30 @@ async function runDoctor(opts) {
   if (hasFailures(summary)) process.exitCode = 1;
 }
 function renderRpcFix(result) {
-  const out = [];
+  const out2 = [];
   if (result.changed.length > 0) {
-    out.push("  " + success("fixed server wiring") + dim(`  ${result.changed.join(", ")}`));
+    out2.push("  " + success("fixed server wiring") + dim(`  ${result.changed.join(", ")}`));
     if (result.changed.includes("package.json")) {
-      out.push(
+      out2.push(
         "  " + dim("run your installer (npm/pnpm/yarn) if the toilscript version changed.")
       );
     }
   } else {
-    out.push("  " + dim("server wiring already in place, nothing to fix."));
+    out2.push("  " + dim("server wiring already in place, nothing to fix."));
   }
-  for (const item of result.skipped) out.push("  " + warn("skipped") + dim(`  ${item}`));
-  process.stdout.write(out.join("\n") + "\n\n");
+  for (const item of result.skipped) out2.push("  " + warn("skipped") + dim(`  ${item}`));
+  process.stdout.write(out2.join("\n") + "\n\n");
 }
 
 // src/cli/notify.ts
-import fs6 from "node:fs";
+import fs7 from "node:fs";
 import os from "node:os";
-import path7 from "node:path";
+import path8 from "node:path";
 import { fileURLToPath as fileURLToPath4 } from "node:url";
 
 // src/cli/update.ts
-import fs5 from "node:fs";
-import path6 from "node:path";
+import fs6 from "node:fs";
+import path7 from "node:path";
 
 // src/cli/updates.ts
 function parseVersion2(v) {
@@ -3571,9 +3723,9 @@ function parseNcuJson(stdout2) {
   try {
     const parsed = JSON.parse(stdout2.slice(start2, end + 1));
     if (typeof parsed !== "object" || parsed === null) return {};
-    const out = {};
-    for (const [k, v] of Object.entries(parsed)) if (typeof v === "string") out[k] = v;
-    return out;
+    const out2 = {};
+    for (const [k, v] of Object.entries(parsed)) if (typeof v === "string") out2[k] = v;
+    return out2;
   } catch {
     return {};
   }
@@ -3588,23 +3740,50 @@ function buildRows(upgraded, currentDeps) {
 
 // src/cli/update.ts
 function detectPackageManager2(root) {
-  if (fs5.existsSync(path6.join(root, "pnpm-lock.yaml"))) return { name: "pnpm", ncuName: "pnpm" };
-  if (fs5.existsSync(path6.join(root, "yarn.lock"))) return { name: "yarn", ncuName: "yarn" };
-  if (fs5.existsSync(path6.join(root, "bun.lockb"))) return { name: "bun", ncuName: "bun" };
+  if (fs6.existsSync(path7.join(root, "pnpm-lock.yaml"))) return { name: "pnpm", ncuName: "pnpm" };
+  if (fs6.existsSync(path7.join(root, "yarn.lock"))) return { name: "yarn", ncuName: "yarn" };
+  if (fs6.existsSync(path7.join(root, "bun.lockb"))) return { name: "bun", ncuName: "bun" };
   return { name: "npm", ncuName: "npm" };
 }
 function readDependencies(pkgPath) {
-  const parsed = JSON.parse(fs5.readFileSync(pkgPath, "utf8"));
+  const parsed = JSON.parse(fs6.readFileSync(pkgPath, "utf8"));
   if (typeof parsed !== "object" || parsed === null) return {};
   const pkg = parsed;
   const merge = (v) => {
     if (typeof v !== "object" || v === null) return {};
-    const out = {};
-    for (const [k, val] of Object.entries(v)) if (typeof val === "string") out[k] = val;
-    return out;
+    const out2 = {};
+    for (const [k, val] of Object.entries(v)) if (typeof val === "string") out2[k] = val;
+    return out2;
   };
   return { ...merge(pkg.dependencies), ...merge(pkg.devDependencies) };
 }
+function serverDirs(root) {
+  const dirs = /* @__PURE__ */ new Set();
+  try {
+    const parsed = JSON.parse(
+      fs6.readFileSync(path7.join(root, "toilconfig.json"), "utf8")
+    );
+    const entries = typeof parsed === "object" && parsed !== null && Array.isArray(parsed.entries) ? parsed.entries.filter(
+      (e) => typeof e === "string"
+    ) : [];
+    for (const e of entries) dirs.add(path7.dirname(path7.resolve(root, e)));
+  } catch {
+  }
+  if (dirs.size === 0) dirs.add(path7.join(root, "server"));
+  return [...dirs];
+}
+function ensureMigrationsDirs(root) {
+  const created = [];
+  for (const dir of serverDirs(root)) {
+    if (!fs6.existsSync(dir)) continue;
+    const migrations = path7.join(dir, "migrations");
+    if (fs6.existsSync(migrations)) continue;
+    fs6.mkdirSync(migrations, { recursive: true });
+    fs6.writeFileSync(path7.join(migrations, "README.md"), MIGRATIONS_README);
+    created.push(path7.relative(root, migrations) || "migrations");
+  }
+  return created;
+}
 function bumpColor(bump, text2) {
   if (bump === "major") return danger(text2);
   if (bump === "minor") return warn(text2);
@@ -3616,9 +3795,9 @@ function rowLine(row) {
 }
 var TARGETS = /* @__PURE__ */ new Set(["latest", "minor", "patch", "newest", "greatest"]);
 async function runUpdate(opts) {
-  const root = path6.resolve(opts.root ?? opts.cwd);
-  const pkgPath = path6.join(root, "package.json");
-  if (!fs5.existsSync(pkgPath)) {
+  const root = path7.resolve(opts.root ?? opts.cwd);
+  const pkgPath = path7.join(root, "package.json");
+  if (!fs6.existsSync(pkgPath)) {
     throw new Error("No package.json here. Run from your project root or pass --root <dir>.");
   }
   const currentDeps = readDependencies(pkgPath);
@@ -3634,6 +3813,13 @@ async function runUpdate(opts) {
     ...extra
   ];
   intro(accent("toiljs update"));
+  const createdMigrations = ensureMigrationsDirs(root);
+  if (createdMigrations.length > 0) {
+    note(
+      createdMigrations.map((p) => `${dim("+")} ${p}/`).join("\n"),
+      "Created ToilDB migrations folder"
+    );
+  }
   const s = spinner();
   s.start("Checking the registry for updates");
   const res = await capture("npx", ncuArgs(["--jsonUpgraded"]), root);
@@ -3773,8 +3959,8 @@ function findOutdated(latest, projectVersion, cliVersion, cliIsLocal, pm) {
 var REGISTRY_URL = "https://registry.npmjs.org/toiljs/latest";
 var FETCH_TIMEOUT_MS = 2e3;
 function cacheFile() {
-  const base = process.env.XDG_CACHE_HOME ?? path7.join(os.homedir(), ".cache");
-  return path7.join(base, "toiljs", "update-check.json");
+  const base = process.env.XDG_CACHE_HOME ?? path8.join(os.homedir(), ".cache");
+  return path8.join(base, "toiljs", "update-check.json");
 }
 async function fetchLatest() {
   const ctrl = new AbortController();
@@ -3800,22 +3986,22 @@ async function fetchLatest() {
 async function resolveLatest() {
   const file = cacheFile();
   try {
-    const cached = parseCheckCache(fs6.readFileSync(file, "utf8"));
+    const cached = parseCheckCache(fs7.readFileSync(file, "utf8"));
     if (cached && isCacheFresh(cached, Date.now())) return cached.latest;
   } catch {
   }
   const latest = await fetchLatest();
   try {
-    fs6.mkdirSync(path7.dirname(file), { recursive: true });
-    fs6.writeFileSync(file, JSON.stringify({ latest, checkedAt: Date.now() }));
+    fs7.mkdirSync(path8.dirname(file), { recursive: true });
+    fs7.writeFileSync(file, JSON.stringify({ latest, checkedAt: Date.now() }));
   } catch {
   }
   return latest;
 }
 function projectToiljsVersion(root) {
   try {
-    const raw = fs6.readFileSync(
-      path7.join(root, "node_modules", "toiljs", "package.json"),
+    const raw = fs7.readFileSync(
+      path8.join(root, "node_modules", "toiljs", "package.json"),
       "utf8"
     );
     const parsed = JSON.parse(raw);
@@ -3840,9 +4026,9 @@ async function notifyIfOutdated(rootArg) {
     if (env.TOILJS_NO_UPDATE_CHECK || env.NO_UPDATE_NOTIFIER || env.CI) return;
     const latest = await resolveLatest();
     if (!latest) return;
-    const root = path7.resolve(rootArg ?? process.cwd());
-    const cliDir = path7.dirname(fileURLToPath4(import.meta.url));
-    const cliIsLocal = cliDir.startsWith(path7.join(root, "node_modules") + path7.sep);
+    const root = path8.resolve(rootArg ?? process.cwd());
+    const cliDir = path8.dirname(fileURLToPath4(import.meta.url));
+    const cliIsLocal = cliDir.startsWith(path8.join(root, "node_modules") + path8.sep);
     const rows = findOutdated(
       latest,
       projectToiljsVersion(root),
@@ -3954,6 +4140,7 @@ function printHelp() {
       cmd("start", "self-host the built app (hyper-express / uWS)"),
       cmd("doctor", "diagnose project setup and dependencies"),
       cmd("update", "check for and apply dependency updates"),
+      cmd("db <action>", "manage dev DB data (status | reset | export | import)"),
       "",
       bold("Options"),
       cmd("--root <dir>", "project root (default: current directory)"),
@@ -4054,6 +4241,12 @@ async function main() {
         target: flags.target
       });
       break;
+    case "db": {
+      const action = rest[0];
+      const fileArg = rest[1] !== void 0 && !rest[1].startsWith("-") ? rest[1] : void 0;
+      runDb(action, fileArg, { root: flags.root });
+      break;
+    }
     case "help":
     case "--help":
     case "-h":