@junejs/server 0.0.9 → 0.0.11

package/src/deploy.ts

@@ -1,35 +1,114 @@
-// `june deploy` — ship a June app. Workers target (v1).
-//
-// The verb is fixed, the target is an adapter (same seam philosophy as
-// JuneHost): today this orchestrates `june build` + wrangler (which owns auth,
-// wasm/ttf rules, and the upload API); a future "june-cloud" target swaps the
-// adapter, not the CLI. --dry-run is the CI test (build + wrangler validate,
-// no upload).
+// `june deploy` — ship a June app. The verb is fixed; the TARGET is the adapter
+// (same seam philosophy as JuneHost). `june build` already produced the target's
+// artifacts (workers → worker.js + wrangler.jsonc; vercel → .vercel/output/), so
+// deploy just runs the platform CLI: wrangler for Workers (+ D1 migration first),
+// or `vercel deploy --prebuilt` for Vercel. --dry-run validates without uploading.
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 
 import { juneBuild } from "./build";
 import { loadJuneConfig } from "./config-loader";
+import { blockedMessage } from "./migrate";
+import { migrateD1, resolveD1Database, type D1Exec } from "./d1-migrate";
+
+// One platform-CLI invocation, factored out so tests can drive juneDeploy's
+// orchestration (target dispatch, migrate-before-deploy ordering, the
+// dry-run/destructive gates) without spawning wrangler or vercel.
+type CliRun = (
+  args: string[],
+  cwd: string,
+) => Promise<{ stdout: string; stderr: string; exitCode: number }>;
+
+const spawnCli: CliRun = async (args, cwd) => {
+  const proc = Bun.spawn(args, { cwd, stdout: "pipe", stderr: "pipe" });
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  return { stdout, stderr, exitCode };
+};
 
 export type DeployResult = {
   url: string | null;
   dryRun: boolean;
-  configPath: string;
+  configPath: string; // wrangler config (workers) or the Build Output dir (vercel)
+  migrated: string[]; // D1 migrations applied this deploy (empty for vercel / dry-run)
 };
 
-export async function juneDeploy(
-  appRoot: string,
-  options: { dryRun?: boolean; skipBuild?: boolean } = {},
-): Promise<DeployResult> {
+type DeployOptions = {
+  dryRun?: boolean;
+  skipBuild?: boolean;
+  skipMigrate?: boolean;
+  allowDestructive?: boolean;
+  prod?: boolean; // vercel: deploy to production (default: a preview deploy)
+  d1Exec?: D1Exec; // test seam: the D1 transport
+  runCli?: CliRun; // test seam: the platform CLI invocation
+};
+
+export async function juneDeploy(appRoot: string, options: DeployOptions = {}): Promise<DeployResult> {
   const cfg = await loadJuneConfig(appRoot);
-  const target = cfg.deploy?.target ?? "workers";
-  if (target !== "workers") throw new Error(`unknown deploy target: ${target}`);
+  // The adapter is the source of truth for the target; deploy.target is a legacy
+  // fallback. workers() is the default when neither names one.
+  const adapterName = (cfg.deploy?.adapter as { name?: string } | undefined)?.name;
+  const target = adapterName ?? cfg.deploy?.target ?? "workers";
+  if (target !== "workers" && target !== "vercel") {
+    throw new Error(`unknown deploy target: ${target}`);
+  }
 
   if (!options.skipBuild) {
     const built = await juneBuild(appRoot);
     console.log(`built ${built.outFile}`);
   }
 
+  const run = options.runCli ?? spawnCli;
+  return target === "vercel"
+    ? deployVercel(appRoot, options, run)
+    : deployWorkers(appRoot, cfg, options, run);
+}
+
+// --- Vercel: upload the prebuilt Build Output (.vercel/output/) ---------------
+async function deployVercel(appRoot: string, options: DeployOptions, run: CliRun): Promise<DeployResult> {
+  const out = join(appRoot, ".vercel", "output");
+  if (!existsSync(join(out, "config.json"))) {
+    throw new Error(`no Vercel Build Output found (expected ${out}/config.json) — run june build first`);
+  }
+  if (options.dryRun) {
+    console.log(`dry-run: built ${out} (skipping vercel deploy)`);
+    return { url: null, dryRun: true, configPath: out, migrated: [] };
+  }
+  if (!process.env.VERCEL_TOKEN) {
+    console.log(
+      "note: VERCEL_TOKEN not set — the vercel CLI will use its own login\n" +
+        "      (run `bunx vercel login` once, or export the token).",
+    );
+  }
+  // --prebuilt uploads .vercel/output as-is (no second build); --yes is
+  // non-interactive; --prod targets production (default is a preview deploy).
+  const args = ["bunx", "vercel@latest", "deploy", "--prebuilt", "--yes"];
+  if (options.prod) args.push("--prod");
+
+  const { stdout, stderr, exitCode } = await run(args, appRoot);
+  if (stdout.trim()) console.log(stdout.trimEnd());
+  if (exitCode !== 0) {
+    if (/credentials|token|forbidden|unauthorized/i.test(stderr + stdout)) {
+      throw new Error(
+        "vercel authentication failed — set VERCEL_TOKEN or run `bunx vercel login`.\n" + stderr.trim(),
+      );
+    }
+    throw new Error(`vercel deploy failed (exit ${exitCode})\n${stderr.trim()}`);
+  }
+  const url = stdout.match(/https:\/\/\S+\.vercel\.app\S*/)?.[0] ?? null;
+  return { url, dryRun: false, configPath: out, migrated: [] };
+}
+
+// --- Workers: D1 migration (if any), then wrangler deploy --------------------
+async function deployWorkers(
+  appRoot: string,
+  cfg: Awaited<ReturnType<typeof loadJuneConfig>>,
+  options: DeployOptions,
+  run: CliRun,
+): Promise<DeployResult> {
   // The app's own wrangler config wins; otherwise the one `june build` emits next
   // to the bundle (its `main` is relative to the config file).
   const configPath =
@@ -39,6 +118,32 @@ export async function juneDeploy(
     throw new Error(`no wrangler config found (expected ${configPath}) — run june build first`);
   }
 
+  // Apply pending migrations to the production D1 BEFORE shipping the new worker,
+  // so the deployed code finds the schema it expects. Same migrate() (ledger +
+  // destructive gate) as dev — a destructive migration halts the deploy until you
+  // re-run with --allow-destructive. Skipped on --dry-run (never touches remote
+  // state) and for apps with no declared db.
+  const migrated: string[] = [];
+  if (cfg.resources?.db && !options.skipMigrate && !options.dryRun) {
+    const database = await resolveD1Database(appRoot, configPath);
+    if (database) {
+      const r = await migrateD1({
+        appRoot,
+        database,
+        configPath,
+        allowDestructive: options.allowDestructive,
+        exec: options.d1Exec,
+      });
+      if (r.blocked) throw new Error(`D1 ${database}: ${blockedMessage(r.blocked)}`);
+      migrated.push(...r.applied);
+      console.log(
+        r.applied.length
+          ? `migrated D1 ${database}: ${r.applied.join(", ")}`
+          : `D1 ${database}: migrations up to date`,
+      );
+    }
+  }
+
   if (!options.dryRun && !process.env.CLOUDFLARE_API_TOKEN) {
     console.log(
       "note: CLOUDFLARE_API_TOKEN not set — wrangler will fall back to its own login\n" +
@@ -50,12 +155,7 @@ export async function juneDeploy(
   const args = ["bunx", "wrangler@4.99.0", "deploy", "--config", configPath];
   if (options.dryRun) args.push("--dry-run");
 
-  const proc = Bun.spawn(args, { cwd: appRoot, stdout: "pipe", stderr: "pipe" });
-  const [out, err, code] = await Promise.all([
-    new Response(proc.stdout).text(),
-    new Response(proc.stderr).text(),
-    proc.exited,
-  ]);
+  const { stdout: out, stderr: err, exitCode: code } = await run(args, appRoot);
   if (out.trim()) console.log(out.trimEnd());
   if (code !== 0) {
     if (/authentication|login|10000/i.test(err + out)) {
@@ -68,5 +168,5 @@ export async function juneDeploy(
   }
 
   const url = out.match(/https:\/\/\S+\.workers\.dev\S*/)?.[0] ?? null;
-  return { url, dryRun: options.dryRun ?? false, configPath };
+  return { url, dryRun: options.dryRun ?? false, configPath, migrated };
 }

package/src/dev-reload.ts

@@ -12,15 +12,30 @@
 const EVENTS_PATH = "/__june/events";
 const SCRIPT_PATH = "/__june/reload.js";
 
-const RELOAD_JS = `// june dev live-reload: reconnect-after-drop → location.reload()
+const RELOAD_JS = `// june dev live-reload: reconnect-after-drop → reload; "css" event → hot-swap
 (() => {
   let dropped = false;
+  const swapCss = () => {
+    document.querySelectorAll('link[rel="stylesheet"]').forEach((old) => {
+      const u = new URL(old.href);
+      if (u.pathname !== "/_june/global.css") return;
+      // Clone with a cache-busted href; drop the old one once the new loads so
+      // there's no flash of unstyled content. No page reload → island state and
+      // scroll survive.
+      const next = old.cloneNode();
+      u.searchParams.set("t", Date.now());
+      next.href = u.pathname + u.search;
+      next.addEventListener("load", () => old.remove(), { once: true });
+      old.parentNode.insertBefore(next, old.nextSibling);
+    });
+  };
   const connect = () => {
     const es = new EventSource(${JSON.stringify(EVENTS_PATH)});
     es.addEventListener("open", () => {
       if (dropped) location.reload();
       dropped = false;
     });
+    es.addEventListener("css", swapCss); // stylesheet edit → swap, no reload
     es.addEventListener("error", () => {
       dropped = true;
       // EventSource auto-retries while the connection is flaky, but goes to
@@ -36,14 +51,34 @@ const RELOAD_JS = `// june dev live-reload: reconnect-after-drop → location.re
 })();
 `;
 
+// Live SSE connections, so a CSS edit can be PUSHED to every open browser (a
+// code edit still rides the restart-then-reconnect path). The child watches the
+// stylesheet (dev.ts) and calls notifyCssChange; the supervisor ignores .css so
+// it does NOT restart — that's what keeps this a hot-swap instead of a reload.
+const clients = new Set<ReadableStreamDefaultController<Uint8Array>>();
+const enc = new TextEncoder();
+
+export function notifyCssChange(): void {
+  const msg = enc.encode("event: css\ndata: 1\n\n");
+  for (const c of clients) {
+    try {
+      c.enqueue(msg);
+    } catch {
+      clients.delete(c);
+    }
+  }
+}
+
 function devEvents(): Response {
   let heartbeat: ReturnType<typeof setInterval> | undefined;
+  let self: ReadableStreamDefaultController<Uint8Array> | undefined;
   const stream = new ReadableStream<Uint8Array>({
     start(controller) {
+      self = controller;
+      clients.add(controller);
       // One greeting so the browser fires `open`, then a comment heartbeat:
       // a silent stream gets culled by idle timeouts (hosts, proxies), and a
       // culled stream reads as a restart to the client — which reloads.
-      const enc = new TextEncoder();
       controller.enqueue(enc.encode("retry: 300\n\ndata: connected\n\n"));
       heartbeat = setInterval(() => {
         try {
@@ -55,6 +90,7 @@ function devEvents(): Response {
     },
     cancel() {
       clearInterval(heartbeat);
+      if (self) clients.delete(self);
     },
   });
   return new Response(stream, {
@@ -77,14 +113,24 @@ export function withLiveReload(
     }
 
     const res = await fetchApp(req);
-    if (!res.headers.get("content-type")?.includes("text/html")) return res;
-    // Dev HTML is fully buffered by the pipeline already (allReady), so a
-    // text() round-trip costs nothing.
-    const html = await res.text();
-    const tag = `<script src="${SCRIPT_PATH}" defer></script>`;
-    const injected = html.includes("</body>") ? html.replace("</body>", `${tag}</body>`) : html + tag;
+    if (!res.headers.get("content-type")?.includes("text/html") || !res.body) return res;
+    // Append the reload script WITHOUT buffering — streaming routes must stay
+    // streamed in dev. The trailing <script defer> runs after the document
+    // parses regardless of position, so a final chunk is correct and keeps the
+    // shell-first flush intact.
+    const tag = new TextEncoder().encode(`<script src="${SCRIPT_PATH}" defer></script>`);
+    const tagged = res.body.pipeThrough(
+      new TransformStream<Uint8Array, Uint8Array>({
+        transform(chunk, controller) {
+          controller.enqueue(chunk);
+        },
+        flush(controller) {
+          controller.enqueue(tag);
+        },
+      }),
+    );
     const headers = new Headers(res.headers);
-    headers.delete("content-length"); // the body just grew; let the host recompute
-    return new Response(injected, { status: res.status, headers });
+    headers.delete("content-length"); // the body grew; let the host recompute
+    return new Response(tagged, { status: res.status, headers });
   };
 }

package/src/dev.ts

@@ -4,13 +4,17 @@
 // work), load june.config.ts from the app root (the config the PoC forgot to
 // read), build the app, and serve through the detected JuneHost.
 
+import { watch } from "node:fs";
 import { createServer as createNetServer } from "node:net";
+import { dirname } from "node:path";
 
 import { loadJuneConfig } from "./config-loader";
 import { installAsyncContext } from "./instrumentation";
 import { createApp } from "./app";
-import { withLiveReload } from "./dev-reload";
+import { withLiveReload, notifyCssChange } from "./dev-reload";
 import { host as defaultHost, type JuneHost, type ServeHandle } from "./host";
+import { migrateApp, blockedMessage } from "./migrate";
+import { findGlobalCss, processCssCached, invalidateCss } from "./css";
 
 export type DevServerOptions = {
   appDir: string;
@@ -42,6 +46,14 @@ export async function startDevServer({
 }: DevServerOptions): Promise<DevServer> {
   await installAsyncContext();
   const config = await loadJuneConfig(appDir);
+
+  // Apply pending migrations before serving — dev auto-applies the SAFE ones; a
+  // destructive one is reported and skipped (the server still starts, but the
+  // route using the new schema will fail until you run it explicitly).
+  const m = await migrateApp(dirname(appDir), config);
+  if (m?.applied.length) console.log(`[june] migrated: ${m.applied.join(", ")}`);
+  if (m?.blocked) console.warn(`[june] ${blockedMessage(m.blocked)}`);
+
   const app = createApp({ appDir, config });
   await app.warmup();
 
@@ -56,6 +68,25 @@ export async function startDevServer({
     earlyHints: () => app.earlyHints(),
   });
 
+  // CSS hot-swap: a stylesheet edit pushes a `css` event to open browsers, which
+  // re-fetch /global.css and swap the <link> WITHOUT reloading (island state +
+  // scroll survive). The supervisor ignores .css so it won't restart over it; a
+  // .tsx edit still restarts → full reload (its markup changed too).
+  if (findGlobalCss(appDir)) {
+    watch(appDir, { recursive: true }, (_event, file) => {
+      if (file && file.endsWith(".css")) {
+        invalidateCss(); // next /global.css recompiles fresh
+        notifyCssChange();
+      }
+    });
+    // Warm + cache the stylesheet in the background: Tailwind v4's native engine
+    // costs ~700ms to load and ~145ms to build its design system ONCE. Doing it
+    // now (while the user reads the dev URL) overlaps that with startup AND
+    // populates the cache, so the first page's stylesheet is instant — and every
+    // later navigation serves from cache (recompile only after an edit).
+    void processCssCached(appDir).catch(() => {});
+  }
+
   const url = `http://localhost:${handle.port}`;
   console.log(`june dev → ${url}  (host: ${host.name})`);
   return { ...handle, url };

package/src/host.ts

@@ -25,6 +25,11 @@ import { Readable } from "node:stream";
 import type { JuneDb, RunResult } from "@junejs/core/resources";
 export type { JuneDb, RunResult };
 
+// Local-sqlite driver selection lives in its own layer; the host just delegates
+// openDb to it (bun:sqlite under Bun, node:sqlite under Node, with guidance when
+// Node is too old). See src/sqlite-driver.ts.
+import { openLocalSqlite } from "./sqlite-driver";
+
 export type ServeHandle = { port: number; stop(force?: boolean): void };
 
 export type SpawnedModule = {
@@ -49,59 +54,6 @@ export interface JuneHost {
   openDb(path: string): Promise<JuneDb>;
 }
 
-// --- a tiny sync→async SQLite adapter shared by both hosts ------------------
-
-// The shape bun:sqlite exposes directly and node:sqlite is adapted to: a
-// prepared statement with positional binding.
-type SyncStatement = {
-  all(...params: unknown[]): unknown[];
-  get(...params: unknown[]): unknown;
-  run(...params: unknown[]): { changes: number | bigint; lastInsertRowid?: number | bigint };
-};
-type SyncSqlite = {
-  query(sql: string): SyncStatement;
-  exec(sql: string): void;
-  close(): void;
-};
-
-// Wrap a synchronous SQLite handle as the async JuneDb. The driver work is
-// synchronous, but the SURFACE is async, so swapping in D1 later is invisible
-// to every caller.
-function asyncSqlite(db: SyncSqlite): JuneDb {
-  const self: JuneDb = {
-    async query<T>(sql: string, params: unknown[] = []) {
-      return db.query(sql).all(...params) as T[];
-    },
-    async get<T>(sql: string, params: unknown[] = []) {
-      // Normalize "no row" to undefined — bun:sqlite returns null, node:sqlite
-      // returns undefined; the seam hides the difference.
-      return (db.query(sql).get(...params) ?? undefined) as T | undefined;
-    },
-    async run(sql: string, params: unknown[] = []) {
-      const r = db.query(sql).run(...params);
-      return { changes: Number(r.changes), lastInsertRowid: r.lastInsertRowid ?? 0 };
-    },
-    async exec(sql: string) {
-      db.exec(sql);
-    },
-    async transaction<T>(fn: (tx: JuneDb) => Promise<T>) {
-      db.exec("BEGIN");
-      try {
-        const out = await fn(self); // same connection — sqlite is single-writer
-        db.exec("COMMIT");
-        return out;
-      } catch (e) {
-        db.exec("ROLLBACK");
-        throw e;
-      }
-    },
-    async close() {
-      db.close();
-    },
-  };
-  return self;
-}
-
 // --- Bun host ---------------------------------------------------------------
 
 function bunHost(): JuneHost {
@@ -128,14 +80,7 @@ function bunHost(): JuneHost {
         exited: child.exited,
       };
     },
-    async openDb(path) {
-      // Non-literal specifier: only Bun has bun:sqlite, so resolve it at runtime.
-      const specifier = "bun:sqlite";
-      const { Database } = (await import(specifier)) as {
-        Database: new (p: string, o?: { create?: boolean }) => SyncSqlite;
-      };
-      return asyncSqlite(new Database(path, { create: true }));
-    },
+    openDb: openLocalSqlite, // bun:sqlite under the hood — see sqlite-driver.ts
   };
 }
 
@@ -212,23 +157,7 @@ function nodeHost(): JuneHost {
         exited: new Promise((resolve) => child.on("exit", (code) => resolve(code ?? 0))),
       };
     },
-    async openDb(path) {
-      const specifier = "node:sqlite"; // node-only builtin; resolve at runtime
-      const { DatabaseSync } = (await import(specifier)) as {
-        DatabaseSync: new (p: string) => {
-          prepare(sql: string): SyncStatement;
-          exec(sql: string): void;
-          close(): void;
-        };
-      };
-      const db = new DatabaseSync(path);
-      // Adapt node:sqlite (prepare()) to the query()-shaped SyncSqlite surface.
-      return asyncSqlite({
-        query: (sql) => db.prepare(sql),
-        exec: (sql) => db.exec(sql),
-        close: () => db.close(),
-      });
-    },
+    openDb: openLocalSqlite, // node:sqlite under the hood — see sqlite-driver.ts
   };
 }
 

package/src/index.ts

@@ -1,12 +1,38 @@
 // @junejs/server — June's host adapters + dev server. Host-coupled (`node:*`
 // allowed); it composes ON TOP of the pure `@junejs/core` contract layer.
 
+export {
+  workers,
+  vercel,
+  type JuneAdapter,
+  type AdapterCapabilities,
+  type ResourcePlan,
+  type AdapterEntry,
+  type AdapterEmitContext,
+} from "./adapter";
 export { host, type JuneHost, type JuneDb, type RunResult, type ServeHandle, type SpawnedModule } from "./host";
 export { sqlite, d1, type D1Database } from "./db";
 export { memoryKv, redisKv } from "./kv";
 export { localBlob, r2, type R2Bucket } from "./blob";
-export { memoizeResources } from "./resources";
+export {
+  memoizeResources,
+  bindWorkerResources,
+  type WorkerEnv,
+  type ResourceFlags,
+} from "./resources";
+// Ambient data resources (db/kv/blob) live in their own package, `@junejs/db` —
+// `import { db } from "@junejs/db"`. The host opens the resources and runs each
+// request in the scope they read (pipeline imports runInScope from @junejs/db).
 export { loadJuneConfig } from "./config-loader";
+export {
+  migrate,
+  migrateApp,
+  classify,
+  readMigrations,
+  blockedMessage,
+  type Migration,
+  type MigrateResult,
+} from "./migrate";
 export { collection, entry, type ContentEntry } from "./content";
 export {
   listRoutes,
@@ -39,4 +65,5 @@ export {
   type BuildResult,
 } from "./build";
 export { juneDeploy, type DeployResult } from "./deploy";
+export { migrateD1, wranglerD1, resolveD1Database, type D1Exec } from "./d1-migrate";
 export { startDevServer, type DevServer, type DevServerOptions } from "./dev";

package/src/kv.ts

@@ -1,7 +1,7 @@
 // `kv` resource adapters. The kv resource IS the cache (docs/data-layer-boundary
 // .md: "reframe cache as the kv resource — it already is one"): these wrap
 // @junejs/core/cache's CacheStore (memory / redis) as the simpler JuneKv contract,
-// so there is ONE key-value system, surfaced both as cache() and as ctx.kv.
+// so there is ONE key-value system, surfaced both as cache() and as ambient kv.
 
 import { memory, redis, type CacheStore } from "@junejs/core/cache";
 import type { JuneKv, KvFactory } from "@junejs/core/resources";

package/src/migrate.ts

@@ -0,0 +1,122 @@
+// Migrations — the explicit, versioned schema story (Rails-shaped, adapted).
+//
+// `db/migrations/NNNN_name.sql` are applied IN ORDER; a `_june_migrations` ledger
+// tracks which ran, so applying is idempotent. The deliberate design (see the
+// data-layer discussion): never CREATE tables just because a db is connected —
+// schema is an explicit, developer-owned artifact. Dev auto-applies the SAFE
+// (additive) migrations; a DESTRUCTIVE one (data loss) STOPS and asks for
+// explicit consent rather than silently dropping data. Production never
+// auto-migrates: `june db migrate` is the explicit step.
+
+import { existsSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import type { JuneDb } from "@junejs/core/resources";
+import type { JuneConfig } from "@junejs/core/config";
+
+export type Migration = { id: string; sql: string };
+export type ClassifiedMigration = Migration & { destructive: boolean; reasons: string[] };
+export type MigrateResult = {
+  applied: string[]; // ids applied this run, in order
+  blocked: ClassifiedMigration | null; // the destructive migration that halted, if any
+};
+
+// Static DDL danger classifier. We flag DATA-LOSS verbs; additive DDL
+// (CREATE / ADD COLUMN / INSERT / CREATE INDEX) and pragmas/transactions are
+// safe. Conservative on RECALL — any destructive verb present gates the whole
+// migration: a false positive costs one confirmation, a false negative costs
+// data, so we err toward gating.
+const DESTRUCTIVE: Array<{ re: RegExp; label: string }> = [
+  { re: /\bdrop\s+table\b/i, label: "DROP TABLE" },
+  { re: /\bdrop\s+index\b/i, label: "DROP INDEX" },
+  { re: /\bdrop\s+view\b/i, label: "DROP VIEW" },
+  { re: /\bdrop\s+trigger\b/i, label: "DROP TRIGGER" },
+  { re: /\bdelete\s+from\b/i, label: "DELETE" },
+  { re: /\btruncate\b/i, label: "TRUNCATE" },
+  // SQLite rewrites for column drop/rename go through ALTER TABLE … DROP/RENAME.
+  { re: /\balter\s+table\b[\s\S]*?\bdrop\b/i, label: "ALTER TABLE … DROP" },
+  { re: /\balter\s+table\b[\s\S]*?\brename\b/i, label: "ALTER TABLE … RENAME" },
+];
+
+function stripComments(sql: string): string {
+  return sql.replace(/--[^\n]*/g, "").replace(/\/\*[\s\S]*?\*\//g, "");
+}
+
+export function classify(sql: string): { destructive: boolean; reasons: string[] } {
+  const clean = stripComments(sql);
+  const reasons = DESTRUCTIVE.filter((d) => d.re.test(clean)).map((d) => d.label);
+  return { destructive: reasons.length > 0, reasons };
+}
+
+// Read db/migrations/*.sql in lexical order — zero-padded numeric prefixes
+// (0001_, 0002_) sort correctly and double as the version id.
+export async function readMigrations(dir: string): Promise<Migration[]> {
+  if (!existsSync(dir)) return [];
+  const files = (await readdir(dir)).filter((f) => f.endsWith(".sql")).sort();
+  return Promise.all(files.map(async (id) => ({ id, sql: await readFile(join(dir, id), "utf8") })));
+}
+
+async function ensureLedger(db: JuneDb): Promise<void> {
+  await db.exec(
+    `create table if not exists _june_migrations (id text primary key, applied_at text not null)`,
+  );
+}
+
+export async function appliedIds(db: JuneDb): Promise<Set<string>> {
+  await ensureLedger(db);
+  const rows = await db.query<{ id: string }>("select id from _june_migrations");
+  return new Set(rows.map((r) => r.id));
+}
+
+// Apply pending migrations in order. Stops at the first DESTRUCTIVE one unless
+// allowDestructive — migrations are ordered (a later one may depend on it), so
+// the safe prefix is applied and the destructive one is returned for the caller
+// to surface (dev warns; `june db migrate --allow-destructive` proceeds).
+export async function migrate(
+  db: JuneDb,
+  dir: string,
+  opts: { allowDestructive?: boolean; now?: string } = {},
+): Promise<MigrateResult> {
+  const already = await appliedIds(db);
+  const pending = (await readMigrations(dir)).filter((m) => !already.has(m.id));
+  const stamp = opts.now ?? new Date().toISOString();
+  const applied: string[] = [];
+  for (const m of pending) {
+    const c = classify(m.sql);
+    if (c.destructive && !opts.allowDestructive) {
+      return { applied, blocked: { ...m, ...c } };
+    }
+    await db.exec(m.sql);
+    await db.run("insert into _june_migrations (id, applied_at) values (?, ?)", [m.id, stamp]);
+    applied.push(m.id);
+  }
+  return { applied, blocked: null };
+}
+
+// Open the app's declared db, apply migrations from <root>/db/migrations, close.
+// Returns null when no db resource is declared (nothing to migrate). The CLI and
+// dev startup both call this; they own the logging/exit semantics.
+export async function migrateApp(
+  root: string,
+  config: JuneConfig,
+  opts: { allowDestructive?: boolean } = {},
+): Promise<MigrateResult | null> {
+  const factory = config.resources?.db;
+  if (!factory) return null;
+  const db = await factory.open();
+  try {
+    return await migrate(db, join(root, "db", "migrations"), opts);
+  } finally {
+    await db.close();
+  }
+}
+
+// The "this migration was gated" guidance, shared by dev (warns, keeps serving)
+// and `june db migrate` (exits non-zero).
+export function blockedMessage(m: ClassifiedMigration): string {
+  return (
+    `migration ${m.id} is destructive (${m.reasons.join(", ")}) and was NOT applied.\n` +
+    `  review it, then apply explicitly: june db migrate --allow-destructive`
+  );
+}