@omg-dev/vite-plugin 0.4.24

package/src/index.ts

@@ -0,0 +1,967 @@
+import path from "node:path"
+import fs from "node:fs"
+import type { Plugin, ViteDevServer, ResolvedConfig } from "vite"
+import { fetchAuthUpstream, relayAuthUpstream } from "./auth-bridge.ts"
+import { generateAll, regenerateRoutes, regenerateSchema, regenerateTriggers, regenerateWorkflows } from "./codegen.ts"
+import { appendErrorEntry, errorsPathFor, stripAnsi } from "./error-sink.ts"
+import {
+  APPLE_TOUCH_ICON,
+  MANIFEST_FILE,
+  PWA_ICONS,
+  buildWebManifest,
+  injectPwaTags,
+  isAppEntry,
+  resolvePwaConfig,
+  type PwaOptions,
+} from "./pwa.ts"
+import type { VibesServerInstance } from "@omg-dev/server"
+import type { Schema } from "@omg-dev/schema"
+
+export type { PwaOptions } from "./pwa.ts"
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+export interface VibesOptions {
+  /** Root directory of the app (defaults to Vite's root) */
+  root?: string
+  /** SQLite database file path, relative to root (default: ".vibes/data.db") */
+  db?: string
+  /** Auth mode (default: "vibes") */
+  auth?: "vibes" | "local"
+  /** Static assets directory for production serving */
+  staticDir?: string
+  /** PWA installability for published builds — manifest + meta tags + soft
+   * install prompt. Default ON; pass `false` to opt out, or an options
+   * object to customize (see PwaOptions). */
+  pwa?: boolean | PwaOptions
+  /** Shake-to-report feedback widget for published builds — auto-mounts
+   * <VibesFeedback/> outside the app's React tree (shake / two-finger press
+   * summons it; report → agent /_report → LFG triage). Default ON; pass
+   * `false` to opt out and place <VibesFeedback/> from @omg-dev/sdk/feedback
+   * manually. */
+  feedback?: boolean
+  /** Small "omg" badge for published apps. Auto-mounts outside the app's React
+   * tree and opens a built-in "What is omg?" dialog. Default ON; pass `false`
+   * to omit it for a specific app while this rolls out. */
+  brandBadge?: boolean
+}
+
+// Resolve @omg-dev/pwa for `importer` and report whether its package.json declares
+// the given subpath (e.g. "./remix-cta") in its `exports` map. Used to keep the
+// build-time CTA injection skew-safe: an older baked @omg-dev/pwa that predates a
+// subpath export must NOT get the import appended, or the bundle fails to resolve.
+// Returns false on any resolution / parse hiccup — the CTA is additive, so when
+// in doubt we skip it rather than risk breaking the user's build.
+async function pwaDeclaresSubpathExport(
+  resolve: (source: string, importer: string) => Promise<{ id: string } | null>,
+  importer: string,
+  subpath: string,
+): Promise<boolean> {
+  try {
+    // Resolve the always-present root export, then walk up to the owning
+    // package.json. We can't resolve "@omg-dev/pwa/package.json" directly because
+    // an older exports map may not expose "./package.json".
+    const rootEntry = await resolve("@omg-dev/pwa", importer)
+    if (!rootEntry?.id) return false
+    let dir = path.dirname(rootEntry.id.split("?")[0])
+    for (let i = 0; i < 12; i++) {
+      const pkgPath = path.join(dir, "package.json")
+      if (fs.existsSync(pkgPath)) {
+        try {
+          const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"))
+          if (pkg.name === "@omg-dev/pwa") {
+            const exp = pkg.exports
+            return !!exp && typeof exp === "object" && subpath in exp
+          }
+        } catch {
+          // Unreadable/!JSON package.json — keep climbing toward the real one.
+        }
+      }
+      const parent = path.dirname(dir)
+      if (parent === dir) break
+      dir = parent
+    }
+    return false
+  } catch {
+    return false
+  }
+}
+
+// ── Plugin ────────────────────────────────────────────────────────────────────
+
+export default function vibes(opts: VibesOptions = {}): Plugin {
+  let resolvedRoot: string
+  let config: ResolvedConfig
+  let serverInstance: VibesServerInstance | null = null
+
+  const pwaEnabled = opts.pwa !== false
+  const pwaOpts: PwaOptions = typeof opts.pwa === "object" ? opts.pwa : {}
+  let pwaAutoInjected = false
+  let remixCtaInjected = false
+
+  const feedbackEnabled = opts.feedback !== false
+  let feedbackInjected = false
+  const brandBadgeEnabled = opts.brandBadge !== false
+  let brandBadgeInjected = false
+
+  // Icon files present in the app's public dir — manifest entries and the
+  // apple-touch link are only emitted for files that actually exist.
+  function existingIconFiles(): string[] {
+    const publicDir = config?.publicDir
+    if (!publicDir) return []
+    return [...PWA_ICONS.map((i) => i.file), APPLE_TOUCH_ICON].filter((f) =>
+      fs.existsSync(path.join(publicDir, f)),
+    )
+  }
+
+  // An app that ships its own manifest in public/ wins over ours.
+  function userManifestHref(): string | null {
+    const publicDir = config?.publicDir
+    if (!publicDir) return null
+    if (fs.existsSync(path.join(publicDir, MANIFEST_FILE))) return `/${MANIFEST_FILE}`
+    if (fs.existsSync(path.join(publicDir, "manifest.json"))) return "/manifest.json"
+    return null
+  }
+
+  return {
+    name: "vibes",
+    enforce: "pre",
+
+    // ── config ────────────────────────────────────────────────────────────────
+    // Without this, every POST/PATCH/DELETE that mutates a row triggers a
+    // full page reload: chokidar fires on the SQLite file (.vibes/data.db)
+    // when bun:sqlite writes, no plugin claims it via handleHotUpdate, and
+    // Vite's default for an unknown file change is `full-reload`. The same
+    // hits .vibes/routes.json, errors.jsonl, and the WAL/journal sidecars.
+    // .vibes/ is sandbox-internal — its contents should never reach the
+    // browser, so blanket-ignore it.
+    config() {
+      return {
+        // When the brand badge is on (default), it bundles the feedback sheet
+        // (no separate floating button). Expose whether feedback is actually
+        // enabled so the badge can omit it when the app opts out via
+        // vibes({ feedback: false }).
+        define: {
+          __VIBES_BRAND_FEEDBACK__: JSON.stringify(brandBadgeEnabled && feedbackEnabled),
+        },
+        server: {
+          watch: {
+            ignored: ["**/.vibes/**"],
+          },
+        },
+      }
+    },
+
+    // ── configResolved ────────────────────────────────────────────────────────
+    configResolved(resolvedConfig) {
+      config = resolvedConfig
+      resolvedRoot = opts.root ?? resolvedConfig.root
+    },
+
+    // ── transformIndexHtml (dev only) ─────────────────────────────────────────
+    // Inject a runtime-error reporter into every dev-served HTML document so
+    // crashes inside the running app reach the sandbox-local error sink
+    // (.vibes/errors.jsonl). Pi reads that sink between turns. Production
+    // bundles never see this — gated by `config.command === 'serve'`.
+    transformIndexHtml: {
+      order: "pre" as const,
+      handler(html: string) {
+        // Production analytics: when the orchestrator supplies a website id at
+        // build time, inject the self-hosted Umami tracker. Only on `build` —
+        // the dev/preview server (command === "serve") never tracks, so a
+        // builder's own preview sessions don't pollute the app's stats. The
+        // script host is configurable (VIBES_ANALYTICS_SRC) for self-hosting.
+        if (config?.command === "build") {
+          const websiteId = process.env.VIBES_ANALYTICS_WEBSITE_ID
+          if (websiteId) {
+            const src = process.env.VIBES_ANALYTICS_SRC || "https://analytics.omg.dev/script.js"
+            if (!html.includes(src)) {
+              const tag = `<script defer src="${src}" data-website-id="${websiteId}"></script>`
+              html = /<\/head>/i.test(html)
+                ? html.replace(/<\/head>/i, `${tag}</head>`)
+                : tag + html
+            }
+          }
+          if (pwaEnabled) {
+            html = injectPwaTags(html, resolvePwaConfig(pwaOpts, html), {
+              hasAppleIcon: existingIconFiles().includes(APPLE_TOUCH_ICON),
+              manifestHref: userManifestHref() ?? undefined,
+            })
+          }
+          return html
+        }
+        if (config?.command !== "serve") return html
+        const appId = readPreviewAppId(resolvedRoot)
+        const authBootstrap = appId
+          ? `
+<script>
+window.__VIBES_APP_ID = ${JSON.stringify(appId)};
+window.__VIBES_AUTH_TOKEN_URL = "/__vibes/auth/token";
+window.__VIBES_AUTH_SESSION_URL = "/__vibes/auth/session";
+</script>`
+          : ""
+        const reporter = `
+<script>
+(function(){
+  if (window.__vibesReporterInstalled) return;
+  window.__vibesReporterInstalled = true;
+  function send(payload){
+    var msg = Object.assign({ kind: "runtime", at: Date.now() }, payload);
+    // POST into the dev server so it lands in .vibes/errors.jsonl. Use
+    // keepalive so errors thrown right before navigation still flush.
+    // Surface the response status to the parent so a 404/CORS/etc on
+    // the sink endpoint is diagnosable without looking at sandbox logs.
+    try {
+      fetch("/__vibes/runtime-error", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(msg),
+        keepalive: true,
+      }).then(function(r){
+        if (!r.ok) {
+          try { window.parent && window.parent.postMessage(
+            { type: "vibes:reporter-fetch", status: r.status, ok: false }, "*"); } catch (_) {}
+        }
+      }).catch(function(err){
+        try { window.parent && window.parent.postMessage(
+          { type: "vibes:reporter-fetch", error: String(err && err.message || err), ok: false }, "*"); } catch (_) {}
+      });
+    } catch (e) {}
+    // Also notify the parent shell for UI surfacing.
+    try {
+      window.parent && window.parent.postMessage(
+        Object.assign({ type: "vibes:runtime-error" }, msg), "*");
+    } catch (e) {}
+  }
+  window.addEventListener("error", function(ev){
+    var err = ev.error;
+    send({
+      message: (err && err.message) || ev.message || "Error",
+      stack: (err && err.stack) || null,
+      source: ev.filename || null,
+      line: ev.lineno || null,
+      col: ev.colno || null,
+    });
+  });
+  window.addEventListener("unhandledrejection", function(ev){
+    var r = ev.reason;
+    send({
+      message: (r && (r.message || String(r))) || "Unhandled rejection",
+      stack: (r && r.stack) || null,
+      rejection: true,
+    });
+  });
+  var origErr = console.error;
+  console.error = function(){
+    try {
+      var args = Array.prototype.slice.call(arguments);
+      var msg = args.map(function(a){
+        if (a instanceof Error) return a.message;
+        if (typeof a === "string") return a;
+        try { return JSON.stringify(a); } catch (e) { return String(a); }
+      }).join(" ");
+      send({ message: msg, viaConsole: true });
+    } catch (e) {}
+    origErr.apply(console, arguments);
+  };
+})();
+</script>`
+        if (/<head[^>]*>/i.test(html)) {
+          return html.replace(/<head[^>]*>/i, function (m) { return m + authBootstrap + reporter })
+        }
+        return authBootstrap + reporter + html
+      },
+    },
+
+    // ── configureServer (dev) ─────────────────────────────────────────────────
+    async configureServer(server: ViteDevServer) {
+      // Sandbox-local error sink. Pi reads this between turns so it can
+      // see build (Vite) and runtime (browser) errors it would otherwise
+      // miss. Path is fixed; agent-server tails it.
+      const errorsPath = errorsPathFor(resolvedRoot)
+
+      // Wrap Vite's logger.error so transform/resolve/build failures land
+      // in the sink. Vite-plus calls logger.error with the rendered
+      // "[vite] Internal Server Error\n…" string we saw in the diary case.
+      const logger = server.config.logger
+      const origErr = logger.error.bind(logger)
+      logger.error = (msg: string, opts?: unknown) => {
+        try {
+          const text = typeof msg === "string" ? msg : String(msg)
+          // Skip our own self-emitted noise to avoid loops.
+          if (!text.includes("__vibes-self")) {
+            appendErrorEntry(errorsPath, {
+              kind: "server",
+              source: "vite",
+              message: stripAnsi(text).slice(0, 4000),
+            })
+          }
+        } catch {}
+        return origErr(msg, opts as never)
+      }
+
+      // Runtime-error sink: the in-iframe reporter POSTs here.
+      server.middlewares.use((req, res, next) => {
+        if (req.url !== "/__vibes/runtime-error" || req.method !== "POST") return next()
+        const chunks: Buffer[] = []
+        req.on("data", (c: Buffer) => chunks.push(c))
+        req.on("end", () => {
+          try {
+            const body = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}") as Record<string, unknown>
+            appendErrorEntry(errorsPath, {
+              kind: "runtime",
+              source: "browser",
+              message: String(body.message ?? "").slice(0, 4000),
+              stack: body.stack ? String(body.stack).slice(0, 4000) : undefined,
+              file: body.source,
+              line: body.line,
+              col: body.col,
+              viaConsole: body.viaConsole,
+              rejection: body.rejection,
+            })
+          } catch {}
+          res.statusCode = 204
+          res.end()
+        })
+        req.on("error", () => { res.statusCode = 400; res.end() })
+      })
+
+      // Preview auth bridge. Preview iframes run on
+      // `{sandboxId}-5173.preview.omg.dev`, which does not contain the app
+      // slug. The control plane writes `.vibes/app.json`; this middleware
+      // mints tokens for that slug only, so generated app code cannot choose
+      // an arbitrary appId from a preview host.
+      server.middlewares.use((req, res, next) => {
+        if (req.url !== "/__vibes/auth/token") return next()
+        if (req.method === "OPTIONS") {
+          res.statusCode = 204
+          res.end()
+          return
+        }
+        if (req.method !== "POST") {
+          res.statusCode = 405
+          res.setHeader("Content-Type", "application/json")
+          res.end(JSON.stringify({ error: "method not allowed" }))
+          return
+        }
+
+        const appId = readPreviewAppId(resolvedRoot)
+        if (!appId) {
+          res.statusCode = 404
+          res.setHeader("Content-Type", "application/json")
+          res.end(JSON.stringify({ error: "preview app id not configured" }))
+          return
+        }
+
+        req.on("data", () => {})
+        req.on("end", async () => {
+          try {
+            const upstream = await fetchAuthUpstream("token", {
+              method: "POST",
+              headers: {
+                "Content-Type": "application/json",
+                // auth.omg.dev allows dashboard-origin lazy app registration.
+                // The preview middleware is platform-owned and pins appId from
+                // disk, so this does not let app code mint for arbitrary slugs.
+                Origin: "https://omg.dev",
+                ...(req.headers.cookie ? { Cookie: req.headers.cookie } : {}),
+              },
+              body: JSON.stringify({ appId }),
+            })
+            await relayAuthUpstream(res, upstream)
+          } catch (err) {
+            res.statusCode = 502
+            res.setHeader("Content-Type", "application/json")
+            res.end(JSON.stringify({ error: err instanceof Error ? err.message : "auth token proxy failed" }))
+          }
+        })
+        req.on("error", () => { res.statusCode = 400; res.end() })
+      })
+
+      // Preview session bridge. Counterpart to the token bridge above: the
+      // better-auth client's get-session read is the only auth call that goes
+      // cross-origin to auth.omg.dev, where third-party-cookie blocking / ITP
+      // can drop the .omg.dev cookie and make a signed-in dashboard user look
+      // signed-out — popping a needless login in preview. Forward it
+      // same-origin with the browser cookie so the read always sees the shared
+      // session. Read-only GET; never relays Set-Cookie (sign-in/out still go
+      // direct to auth.omg.dev through the better-auth client).
+      server.middlewares.use((req, res, next) => {
+        const path = (req.url ?? "").split("?")[0]
+        if (path !== "/__vibes/auth/session") return next()
+        if (req.method === "OPTIONS") {
+          res.statusCode = 204
+          res.end()
+          return
+        }
+        if (req.method !== "GET") {
+          res.statusCode = 405
+          res.setHeader("Content-Type", "application/json")
+          res.end(JSON.stringify({ error: "method not allowed" }))
+          return
+        }
+        ;(async () => {
+          try {
+            const qs = (req.url ?? "").includes("?") ? (req.url ?? "").slice((req.url ?? "").indexOf("?")) : ""
+            const upstream = await fetchAuthUpstream("session", {
+              method: "GET",
+              headers: {
+                // auth.omg.dev trusts the dashboard origin; the preview server
+                // is platform-owned, so this can't be spoofed by app code.
+                Origin: "https://omg.dev",
+                ...(req.headers.cookie ? { Cookie: req.headers.cookie } : {}),
+              },
+            }, qs)
+            await relayAuthUpstream(res, upstream)
+          } catch (err) {
+            res.statusCode = 502
+            res.setHeader("Content-Type", "application/json")
+            res.end(JSON.stringify({ error: err instanceof Error ? err.message : "auth session proxy failed" }))
+          }
+        })()
+      })
+
+      // Run initial codegen
+      await generateAll(resolvedRoot)
+
+      // Load schema
+      const schema = await loadSchema(resolvedRoot)
+
+      // Signal dev mode to @omg-dev/server so its trigger module uses the
+      // in-process scheduler + emit bus instead of forwarding to the
+      // in-VM agent (which doesn't exist outside a Firecracker).
+      process.env.VIBES_MODE = "dev"
+
+      // Create vibes server instance — dynamic import so bun:sqlite isn't loaded
+      // at config-parse time (which runs under Node.js in vite-plus)
+      const { createVibesServer } = await import("@omg-dev/server")
+      const dbPath = opts.db ?? ".vibes/data.db"
+      serverInstance = await createVibesServer({
+        root: resolvedRoot,
+        db: dbPath,
+        auth: opts.auth ?? "vibes",
+        schema: schema ?? undefined,
+      })
+
+      // Import broker for realtime invalidation
+      const { addClient, removeClient } = await import("@omg-dev/server")
+      // Import subscription registry for per-query reactive subs (Phase 1).
+      const { addSubClient, removeSubClient, handleSubMessage } = await import("@omg-dev/server")
+
+      // 25s heartbeat matches stream-worker so SDK clients see identical
+      // behavior across dev and prod.
+      const HEARTBEAT_MS = 25_000
+      server.middlewares.use((req, res, next) => {
+        if (req.url !== "/__vibes_events") return next()
+
+        res.writeHead(200, {
+          "Content-Type": "text/event-stream",
+          "Cache-Control": "no-cache",
+          Connection: "keep-alive",
+          "Access-Control-Allow-Origin": "*",
+          "X-Accel-Buffering": "no",
+        })
+        res.write(":\n\n")
+
+        const client = {
+          readyState: 1,
+          send(data: string) {
+            res.write(`data: ${data}\n\n`)
+          },
+        }
+        addClient(client)
+
+        const cleanup = () => {
+          if (client.readyState === 3) return
+          client.readyState = 3
+          clearInterval(hb)
+          removeClient(client)
+        }
+        const hb: ReturnType<typeof setInterval> = setInterval(() => {
+          try {
+            if (!res.write(":hb\n\n")) {
+              // Backpressure or already-closed; tear down.
+              cleanup()
+            }
+          } catch {
+            cleanup()
+          }
+        }, HEARTBEAT_MS)
+
+        req.on("close", cleanup)
+      })
+
+      // ── /__vibes_sub WebSocket endpoint ──────────────────────────────────
+      // Per-client subscription transport (Phase 1 of delta-push). The
+      // existing /__vibes_events SSE stays as a broadcast invalidate
+      // channel; /__vibes_sub is the per-query channel that will eventually
+      // carry row-level deltas (Phase 3). For now it just delivers a fresh
+      // snapshot on subscribe and on every write to the collection.
+      //
+      // Auth: deferred to Phase 6 hardening. An anonymous WS upgrade still
+      // works — scoped collections gate at the snapshot layer (the
+      // `_owner = ?` predicate in db.ts throws VibesAuthRequiredError,
+      // which the subscriptions module reports as `snapshot_failed`).
+      const { WebSocketServer } = await import("ws")
+      // Echo the client's chosen subprotocol so the browser doesn't drop
+      // the connection. The client uses subprotocol to smuggle the JWT
+      // (vibes-bearer.<token>) since browser WS API can't set headers.
+      const wss = new WebSocketServer({
+        noServer: true,
+        handleProtocols: (protocols) => {
+          for (const p of protocols) if (p.startsWith("vibes-bearer.")) return p
+          // No bearer? Pick any sent protocol (or false to send none).
+          const first = protocols.values().next().value
+          return first ?? false
+        },
+      })
+
+      // Build a per-dev-server auth middleware so the WS path verifies the
+      // same way prod does. Local auth mode is also acceptable; the dev
+      // plugin honours the configured opts.auth setting.
+      const { createAuthMiddleware } = await import("@omg-dev/auth")
+      const subAuthMW = createAuthMiddleware(opts.auth ?? "vibes")
+
+      const httpServer = server.httpServer
+      if (httpServer) {
+        httpServer.on("upgrade", async (req, socket, head) => {
+          try {
+            const url = new URL(req.url ?? "/", "http://localhost")
+            if (url.pathname !== "/__vibes_sub") return
+
+            // Pull the bearer subprotocol BEFORE handleUpgrade — once the
+            // upgrade is committed, errors are awkward to surface.
+            const protoHeader = (req.headers["sec-websocket-protocol"] as string | undefined) ?? ""
+            const protos = protoHeader.split(",").map(s => s.trim()).filter(Boolean)
+            const bearerProto = protos.find(p => p.startsWith("vibes-bearer."))
+            let userId: string | null = null
+            if (bearerProto) {
+              const token = bearerProto.slice("vibes-bearer.".length)
+              try {
+                const fakeReq = new Request("http://localhost/__vibes_sub", {
+                  headers: { authorization: `Bearer ${token}` },
+                })
+                const result = await subAuthMW(fakeReq)
+                userId = result?.userId ?? null
+              } catch {
+                // Invalid token → anonymous; snapshot layer gates scoped subs.
+              }
+            }
+
+            wss.handleUpgrade(req, socket, head, (ws) => {
+              const subClient = {
+                readyState: 1,
+                send(data: string) {
+                  try { ws.send(data) } catch { /* ws closed mid-send */ }
+                },
+                ctx: { userId },
+              }
+              addSubClient(subClient)
+              ws.on("message", (data: Buffer | ArrayBuffer | Buffer[]) => {
+                const raw = typeof data === "string"
+                  ? data
+                  : Buffer.isBuffer(data)
+                    ? data.toString("utf8")
+                    : Array.isArray(data)
+                      ? Buffer.concat(data).toString("utf8")
+                      : Buffer.from(data as ArrayBuffer).toString("utf8")
+                void handleSubMessage(subClient, raw)
+              })
+              const closeOut = () => {
+                if (subClient.readyState === 3) return
+                subClient.readyState = 3
+                removeSubClient(subClient)
+              }
+              ws.on("close", closeOut)
+              ws.on("error", closeOut)
+            })
+          } catch {
+            try { socket.destroy() } catch { /* already gone */ }
+          }
+        })
+      }
+
+      // Dev-mode object storage proxy. In prod, browsers PUT/GET directly
+      // against Tigris via presigned URLs. Dev has no Tigris — instead the
+      // user app's storage.uploadUrl() returns a Vite-local URL that this
+      // middleware accepts:
+      //
+      //   PUT  /_vibes_storage/<scope>/<...>/<key>?t=<sig>&ct=<content-type>
+      //   GET  /_vibes_storage/<scope>/<...>/<key>?t=<sig>
+      //
+      // Files land under .vibes/storage/ inside the project. Signed tokens
+      // are HMAC-bound to (rel, action, expiresAt) so a token minted for one
+      // path can't be used for another.
+      const storageMod = await import("@omg-dev/server")
+      server.middlewares.use(async (req, res, next) => {
+        if (!req.url) return next()
+        const STORAGE_PREFIX = "/_vibes_storage/"
+        if (!req.url.startsWith(STORAGE_PREFIX)) return next()
+        try {
+          // Parse: strip prefix, split off query string.
+          const qIdx = req.url.indexOf("?")
+          const rawPath = qIdx === -1 ? req.url : req.url.slice(0, qIdx)
+          const queryStr = qIdx === -1 ? "" : req.url.slice(qIdx + 1)
+          const rel = decodeURIComponent(rawPath.slice(STORAGE_PREFIX.length))
+          const params = new URLSearchParams(queryStr)
+          const token = params.get("t") ?? ""
+          // Reject traversal / double slashes / empty up front; storage.ts
+          // helper does the same on the upload side.
+          if (!rel || rel.includes("..") || rel.includes("//")) {
+            res.statusCode = 400
+            return res.end(JSON.stringify({ error: "invalid path" }))
+          }
+
+          // Resolve (scope, userId, key) from the relative path. Layout:
+          //   users/<userId>/<key...>     scope=user
+          //   app/<key...>                scope=app
+          let scope: "user" | "app"
+          let userId = ""
+          let key = ""
+          if (rel.startsWith("users/")) {
+            const rest = rel.slice("users/".length)
+            const slash = rest.indexOf("/")
+            if (slash <= 0) {
+              res.statusCode = 400
+              return res.end(JSON.stringify({ error: "invalid path" }))
+            }
+            scope = "user"
+            userId = rest.slice(0, slash)
+            key = rest.slice(slash + 1)
+          } else if (rel.startsWith("app/")) {
+            scope = "app"
+            key = rel.slice("app/".length)
+          } else {
+            res.statusCode = 400
+            return res.end(JSON.stringify({ error: "invalid scope prefix" }))
+          }
+
+          const method = (req.method ?? "GET").toUpperCase()
+          if (method === "PUT") {
+            if (!storageMod._verifyDevStorageToken(rel, "put", token)) {
+              res.statusCode = 403
+              return res.end(JSON.stringify({ error: "invalid or expired token" }))
+            }
+            const chunks: Buffer[] = []
+            let size = 0
+            const MAX = 25 * 1024 * 1024
+            req.on("data", (c: Buffer) => {
+              size += c.length
+              if (size > MAX) {
+                req.destroy()
+                res.statusCode = 413
+                res.end(JSON.stringify({ error: "exceeds 25MB" }))
+                return
+              }
+              chunks.push(c)
+            })
+            req.on("end", () => {
+              try {
+                storageMod._devStorageWrite(scope, userId, key, Buffer.concat(chunks))
+                res.statusCode = 200
+                res.setHeader("Content-Type", "application/json")
+                res.end(JSON.stringify({ ok: true, size }))
+              } catch (err) {
+                res.statusCode = 500
+                res.end(JSON.stringify({ error: String((err as Error).message) }))
+              }
+            })
+            req.on("error", () => { res.statusCode = 400; res.end() })
+            return
+          }
+          if (method === "GET" || method === "HEAD") {
+            if (!storageMod._verifyDevStorageToken(rel, "get", token)) {
+              res.statusCode = 403
+              return res.end(JSON.stringify({ error: "invalid or expired token" }))
+            }
+            const abs = storageMod._devStorageRead(scope, userId, key)
+            if (!abs) {
+              res.statusCode = 404
+              return res.end(JSON.stringify({ error: "not found" }))
+            }
+            const stat = fs.statSync(abs)
+            res.setHeader("Content-Length", String(stat.size))
+            // Best-effort content-type from extension; the browser-side <img>
+            // doesn't care about exact MIME for images, but JSON callers might.
+            const ext = path.extname(key).toLowerCase()
+            const ctMap: Record<string, string> = {
+              ".png": "image/png",
+              ".jpg": "image/jpeg",
+              ".jpeg": "image/jpeg",
+              ".gif": "image/gif",
+              ".webp": "image/webp",
+              ".svg": "image/svg+xml",
+              ".json": "application/json",
+              ".pdf": "application/pdf",
+              ".mp4": "video/mp4",
+              ".webm": "video/webm",
+              ".txt": "text/plain",
+            }
+            res.setHeader("Content-Type", ctMap[ext] ?? "application/octet-stream")
+            res.statusCode = 200
+            if (method === "HEAD") return res.end()
+            fs.createReadStream(abs).pipe(res)
+            return
+          }
+          if (method === "OPTIONS") {
+            res.statusCode = 204
+            res.setHeader("Access-Control-Allow-Origin", "*")
+            res.setHeader("Access-Control-Allow-Methods", "PUT,GET,HEAD,OPTIONS")
+            res.setHeader("Access-Control-Allow-Headers", "Content-Type,Authorization")
+            return res.end()
+          }
+          res.statusCode = 405
+          res.end(JSON.stringify({ error: "method not allowed" }))
+        } catch (err) {
+          res.statusCode = 500
+          res.end(JSON.stringify({ error: String((err as Error).message) }))
+        }
+      })
+
+      // API + /_vibes/* handler
+      server.middlewares.use(async (req, res, next) => {
+        const isApi = req.url?.startsWith("/api/")
+        const isVibesInternal = req.url?.startsWith("/_vibes/")
+        if (!isApi && !isVibesInternal) return next()
+
+        try {
+          const url = `http://localhost${req.url}`
+          const headers: Record<string, string> = {}
+          for (const [key, value] of Object.entries(req.headers)) {
+            if (typeof value === "string") headers[key] = value
+            else if (Array.isArray(value)) headers[key] = value.join(", ")
+          }
+
+          const body = await new Promise<Buffer>((resolve, reject) => {
+            const chunks: Buffer[] = []
+            req.on("data", (chunk: Buffer) => chunks.push(chunk))
+            req.on("end", () => resolve(Buffer.concat(chunks)))
+            req.on("error", reject)
+          })
+
+          const fetchReq = new Request(url, {
+            method: req.method,
+            headers,
+            body: body.length > 0 ? body : undefined,
+          })
+
+          // /_vibes/* goes through fetch() (handles dispatch + dev-inspect);
+          // /api/* goes through apiHandler() (route table + auth).
+          const response = isVibesInternal
+            ? await serverInstance!.fetch(fetchReq)
+            : await serverInstance!.apiHandler(fetchReq)
+
+          res.statusCode = response.status
+          response.headers.forEach((value, key) => {
+            res.setHeader(key, value)
+          })
+          const responseBody = await response.arrayBuffer()
+          res.end(Buffer.from(responseBody))
+        } catch (err) {
+          console.error("[vibes] API handler error:", err)
+          res.statusCode = 500
+          res.end(JSON.stringify({ error: "Internal server error" }))
+        }
+      })
+
+      console.log("[vibes] Dev server ready (with realtime).")
+    },
+
+    // ── handleHotUpdate ───────────────────────────────────────────────────────
+    async handleHotUpdate({ file }) {
+      const rel = path.relative(resolvedRoot, file)
+
+      if (rel === "schema.ts") {
+        console.log("[vibes] schema.ts changed — regenerating...")
+        await regenerateSchema(resolvedRoot)
+        if (serverInstance) {
+          const newSchema = await loadSchema(resolvedRoot)
+          if (newSchema) serverInstance.migrate(newSchema)
+        }
+        return []
+      }
+
+      if (rel.startsWith("functions/") && rel.endsWith(".ts")) {
+        console.log(`[vibes] functions/${path.basename(file)} changed — rescanning routes + triggers...`)
+        await regenerateRoutes(resolvedRoot)
+        try {
+          await regenerateTriggers(resolvedRoot)
+          await serverInstance?.reloadTriggers()
+        } catch (err) {
+          // Surface trigger scan errors prominently — they're build-time
+          // user-fixable mistakes (non-literal cron expr / topic etc).
+          console.error(`[vibes] trigger scan failed:`, err)
+        }
+        try {
+          await regenerateWorkflows(resolvedRoot)
+          await serverInstance?.reloadWorkflows()
+        } catch (err) {
+          // Same posture as triggers: scan errors (non-literal / duplicate
+          // workflow name) are user-fixable — log loudly, keep dev alive.
+          console.error(`[vibes] workflow scan failed:`, err)
+        }
+        serverInstance?.reloadFunctions()
+        return []
+      }
+
+      return undefined
+    },
+
+    // ── buildStart ────────────────────────────────────────────────────────────
+    async buildStart() {
+      await generateAll(resolvedRoot)
+    },
+
+    // ── transform ─────────────────────────────────────────────────────────────
+    // Published builds get two side-effect imports appended to the app entry:
+    //   - @omg-dev/pwa/auto       — the soft install prompt (gated by autoPrompt)
+    //   - @omg-dev/pwa/remix-cta  — the "Make your own" remix bridge (always on
+    //                             when pwa is enabled; self-gates on the baked
+    //                             VITE_APP_SLUG, so it's inert if not published)
+    // Build-time injection (not template source) so both survive agent rewrites
+    // of main.tsx and never load in dev preview.
+    async transform(code: string, id: string) {
+      if (config?.command !== "build") return null
+      if (!pwaEnabled && !feedbackEnabled && !brandBadgeEnabled) return null
+      if (!isAppEntry(id, resolvedRoot)) return null
+
+      const imports: string[] = []
+
+      // Platform attribution badge — opt-out via vibes({ brandBadge: false }).
+      // Build-only + outside the React tree, so it survives agent rewrites of
+      // main.tsx and never appears in dev preview.
+      if (brandBadgeEnabled && !brandBadgeInjected) {
+        const resolvedBrand = await this.resolve("@omg-dev/sdk/brand/auto", id)
+        if (!resolvedBrand) {
+          this.warn(
+            "[vibes] brand badge: @omg-dev/sdk/brand/auto is not available — badge skipped. " +
+              "Update @omg-dev/sdk, or silence this with vibes({ brandBadge: false }).",
+          )
+        } else {
+          brandBadgeInjected = true
+          imports.push(`import "@omg-dev/sdk/brand/auto";`)
+        }
+      }
+
+      // Shake-to-report feedback widget — opt-out via vibes({ feedback: false }).
+      // Build-only + outside the React tree, so it survives agent rewrites of
+      // main.tsx and never arms a gesture listener in the dev preview iframe.
+      //
+      // When the brand badge is on (default) it ALREADY mounts a button-less
+      // feedback sheet and summons it from its dialog, so injecting the
+      // standalone widget here would double-mount it (two floating controls —
+      // the exact duplication we're collapsing). Only inject standalone feedback
+      // when the brand badge is disabled.
+      if (feedbackEnabled && !brandBadgeEnabled && !feedbackInjected) {
+        const resolvedFb = await this.resolve("@omg-dev/sdk/feedback/auto", id)
+        if (!resolvedFb) {
+          this.warn(
+            "[vibes] feedback: @omg-dev/sdk is not installed — shake-to-report skipped. " +
+              "Add @omg-dev/sdk to dependencies, or silence this with vibes({ feedback: false }).",
+          )
+        } else {
+          feedbackInjected = true
+          imports.push(`import "@omg-dev/sdk/feedback/auto";`)
+        }
+      }
+
+      // Soft install prompt — opt-out via vibes({ pwa: { autoPrompt: false } }).
+      if (pwaEnabled && pwaOpts.autoPrompt !== false && !pwaAutoInjected) {
+        const resolved = await this.resolve("@omg-dev/pwa/auto", id)
+        if (!resolved) {
+          this.warn(
+            "[vibes] pwa: @omg-dev/pwa is not installed — soft install prompt skipped. " +
+              "Add @omg-dev/pwa to dependencies, or silence this with vibes({ pwa: { autoPrompt: false } }).",
+          )
+        } else {
+          pwaAutoInjected = true
+          imports.push(`import "@omg-dev/pwa/auto";`)
+        }
+      }
+
+      // "Make your own" remix CTA — independent of autoPrompt. It self-gates at
+      // runtime on import.meta.env.VITE_APP_SLUG (baked by the orchestrator on
+      // deploy), so it renders nothing on a non-published build.
+      //
+      // Skew guard: the remix-cta subpath shipped in @omg-dev/pwa >= 0.4.16. An app
+      // whose baked @omg-dev/pwa predates it (e.g. 0.4.12) has no "./remix-cta" in
+      // its exports map, so injecting the import hard-fails the build with
+      // "Errored while resolving @omg-dev/pwa/remix-cta". this.resolve() alone is not
+      // a reliable gate across this version skew, so only inject once we've
+      // confirmed the resolved package actually declares the subpath export.
+      //
+      // The brand badge (default on) now hosts "Make it mine" itself: same omg
+      // mark, remix CTA first, and it collapses to the plain branding badge on
+      // dismiss. So only inject the standalone remix-cta when the brand badge is
+      // off — otherwise we'd render two corner pills with the same intent.
+      if (pwaEnabled && !brandBadgeEnabled && !remixCtaInjected) {
+        const exported = await pwaDeclaresSubpathExport(
+          (source, importer) => this.resolve(source, importer),
+          id,
+          "./remix-cta",
+        )
+        if (exported) {
+          remixCtaInjected = true
+          imports.push(`import "@omg-dev/pwa/remix-cta";`)
+        }
+      }
+
+      if (imports.length === 0) return null
+      return { code: `${code}\n${imports.join("\n")}\n`, map: null }
+    },
+
+    // ── generateBundle ────────────────────────────────────────────────────────
+    generateBundle() {
+      if (!pwaEnabled) return
+      // An app shipping its own public/manifest wins — only fill the gap.
+      if (userManifestHref()) return
+      const indexPath = path.join(resolvedRoot, "index.html")
+      const indexHtml = fs.existsSync(indexPath) ? fs.readFileSync(indexPath, "utf-8") : ""
+      const cfg = resolvePwaConfig(pwaOpts, indexHtml)
+      this.emitFile({
+        type: "asset",
+        fileName: MANIFEST_FILE,
+        source: buildWebManifest(cfg, existingIconFiles()),
+      })
+    },
+
+    // ── closeBundle ───────────────────────────────────────────────────────────
+    closeBundle() {
+      serverInstance?.close()
+      serverInstance = null
+    },
+  }
+}
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+async function loadSchema(root: string): Promise<Schema | null> {
+  const schemaPath = path.join(root, "schema.ts")
+  if (!fs.existsSync(schemaPath)) return null
+  try {
+    // Cache-bust on every load — the dynamic-import module cache otherwise
+    // returns the previous value on every HMR re-import, so edits to
+    // schema.ts get pinned to whatever was first loaded at server boot.
+    const mod = (await import(`${schemaPath}?t=${Date.now()}`)) as { default: Schema }
+    return mod.default
+  } catch (err) {
+    console.error("[vibes] Failed to load schema.ts:", err)
+    return null
+  }
+}
+
+function readPreviewAppId(root: string): string | null {
+  const fromEnv = process.env.VIBES_APP_ID?.trim()
+  if (fromEnv && /^[a-z0-9-]+$/.test(fromEnv)) return fromEnv
+
+  const metaPath = path.join(root, ".vibes", "app.json")
+  if (!fs.existsSync(metaPath)) return null
+  try {
+    const meta = JSON.parse(fs.readFileSync(metaPath, "utf-8")) as { appId?: unknown }
+    return typeof meta.appId === "string" && /^[a-z0-9-]+$/.test(meta.appId)
+      ? meta.appId
+      : null
+  } catch {
+    return null
+  }
+}