@wervt/nuxt 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,26 @@
-# Temporary Holding Version
+# @wervt/nuxt
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Nuxt module for apps hosted on [wervt](https://wervt.app): each app runs in its own isolate with
+its own Postgres schema, Drizzle, and live data through Electric shapes.
+
+```bash
+npm create wervt@latest my-app
+```
+
+or add it to an existing Nuxt app:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  modules: ['@wervt/nuxt'],
+})
+```
+
+- `useDb()` (server): Drizzle on the app's own schema, with migrations from `drizzle/`.
+- `proxyShape()` (server) and `useShape()` (app): live rows from Postgres via Electric.
+- `useWervtUser()`: the signed-in wervt user, on the server and in the app.
+- `useValidatedBody()` / `useValidatedQuery()` / `useValidatedParams()`: valibot validation.
+- `nuxt dev` starts against the local wervt stack (Postgres, Electric) and a dev user.
+
+Deploy with [`@wervt/cli`](https://www.npmjs.com/package/@wervt/cli): `wervt deploy`.
+
+Docs: https://wervt.app

package/dist/dev.d.ts

@@ -0,0 +1,22 @@
+import "nuxt/schema";
+//#region src/dev.d.ts
+export interface DevOptions {
+  /** Superuser URL of the local wervt Postgres. */
+  adminUrl?: string;
+  /** WERVT_DB_SECRET of the local setup. */
+  dbSecret?: string;
+  electricUrl?: string;
+  electricSecret?: string;
+  /**
+   * Who `/_wervt/login` signs in as during `nuxt dev` (there's no wervt auth locally).
+   * Defaults to a dev user with a Twitch account linked.
+   */
+  user?: {
+    id: string;
+    email: string;
+    name?: string;
+    image?: string;
+    accounts?: Record<string, string>;
+  };
+}
+//#endregion

package/dist/dev.js

@@ -0,0 +1,73 @@
+import { appDatabaseUrl, dbRole, provisionDatabase } from "./provision.js";
+import { useLogger } from "nuxt/kit";
+import { existsSync, watch } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+//#region src/dev.ts
+const DEFAULTS = {
+	adminUrl: "postgres://postgres:postgres@localhost:5432/wervt",
+	dbSecret: "dev-secret",
+	electricUrl: "http://localhost:3030",
+	electricSecret: "dev-electric-secret"
+};
+const logger = useLogger("wervt");
+/**
+* `nuxt dev` against the local compose stack: provisions the app's role and schema,
+* runs its migrations (again whenever `drizzle/` changes) and points the dev server
+* at the app's database and Electric.
+*/
+async function setupDev(nuxt, app, options) {
+	const config = {
+		adminUrl: process.env.WERVT_PG_ADMIN_URL ?? options.adminUrl ?? DEFAULTS.adminUrl,
+		dbSecret: process.env.WERVT_DB_SECRET ?? options.dbSecret ?? DEFAULTS.dbSecret,
+		electricUrl: process.env.ELECTRIC_URL ?? options.electricUrl ?? DEFAULTS.electricUrl,
+		electricSecret: process.env.ELECTRIC_SECRET ?? options.electricSecret ?? DEFAULTS.electricSecret
+	};
+	process.env.WERVT_DEV_USER ??= JSON.stringify(options.user ?? {
+		id: "dev",
+		email: "dev@wervt.localhost",
+		name: "Dev",
+		accounts: { twitch: "dev" }
+	});
+	const migrationsFolder = join(nuxt.options.rootDir, "drizzle");
+	if (!existsSync(migrationsFolder)) return;
+	const provision = {
+		app,
+		adminUrl: config.adminUrl,
+		secret: config.dbSecret,
+		migrationsFolder
+	};
+	const migrate = async () => {
+		try {
+			await provisionDatabase(provision);
+			logger.success(`Database \`${dbRole(app)}\` is up to date`);
+		} catch (e) {
+			logger.warn(`Could not migrate \`${dbRole(app)}\`. Is the wervt stack running (docker compose up -d)?`, e instanceof Error ? e.message : e);
+		}
+	};
+	await migrate();
+	process.env.DATABASE_URL ??= await appDatabaseUrl(provision);
+	process.env.WERVT_DB_SCHEMA ??= dbRole(app);
+	process.env.ELECTRIC_URL ??= config.electricUrl;
+	process.env.ELECTRIC_SECRET ??= config.electricSecret;
+	let timer;
+	const watcher = watch(migrationsFolder, { recursive: true }, (_event, file) => {
+		if (!file?.endsWith(".sql")) return;
+		clearTimeout(timer);
+		timer = setTimeout(() => {
+			logger.info("Migrations changed, migrating…");
+			migrate();
+		}, 300);
+	});
+	nuxt.hook("close", () => watcher.close());
+}
+/** App name from the module option or package.json, normalised to `[a-z0-9-]+`. */
+async function resolveAppName(rootDir, name) {
+	if (!name) {
+		const pkg = JSON.parse(await readFile(join(rootDir, "package.json"), "utf8").catch(() => "{}"));
+		name = String(pkg.name ?? "app").replace(/^@[^/]+\//, "");
+	}
+	return name.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+}
+//#endregion
+export { resolveAppName, setupDev };

package/dist/module.d.ts

@@ -0,0 +1,11 @@
+import { DevOptions } from "./dev.js";
+//#region src/module.d.ts
+export interface ModuleOptions {
+  /** App name on wervt. Defaults to the package.json name. */
+  app?: string;
+  /** Local stack used by `nuxt dev`. Defaults match the wervt compose setup. */
+  dev?: DevOptions;
+}
+declare const _default: import("nuxt/schema").NuxtModule<ModuleOptions, ModuleOptions, false>;
+//#endregion
+export { _default as default };

package/dist/module.js

@@ -0,0 +1,142 @@
+import { resolveAppName, setupDev } from "./dev.js";
+import { addImports, addPlugin, addServerHandler, createResolver, defineNuxtModule, hasNuxtModule, installModule } from "nuxt/kit";
+import { builtinModules } from "node:module";
+import evlog from "evlog/nuxt";
+//#region src/module.ts
+const CONTENT_DATABASE = {
+	type: "postgres",
+	url: "{{DATABASE_URL}}"
+};
+var module_default = defineNuxtModule({
+	meta: {
+		name: "@wervt/nuxt",
+		configKey: "wervt"
+	},
+	async setup(options, nuxt) {
+		const resolver = createResolver(import.meta.url);
+		const nitro = nuxt.options.nitro;
+		if (!nuxt.options.dev) nitro.preset ||= "deno-server";
+		if (!hasNuxtModule("evlog/nuxt", nuxt)) {
+			const app = await resolveAppName(nuxt.options.rootDir, options.app);
+			const config = nuxt.options;
+			config.evlog = {
+				env: { service: app },
+				redact: true,
+				exclude: [
+					"/_wervt/**",
+					"/_nuxt/**",
+					"/__nuxt_error",
+					"/_fonts/**"
+				],
+				...config.evlog
+			};
+			await installModule(evlog, void 0, nuxt);
+		}
+		const useContentDatabase = !nuxt.options.dev && hasNuxtModule("@nuxt/content", nuxt);
+		if (useContentDatabase) {
+			const options = nuxt.options;
+			options.content = {
+				...options.content,
+				database: CONTENT_DATABASE
+			};
+		}
+		nuxt.hook("nitro:config", (config) => {
+			const options = config;
+			options.externals = {
+				...options.externals,
+				inline: [
+					...options.externals?.inline ?? [],
+					resolver.resolve("./runtime"),
+					/(^|\/node_modules\/)(drizzle-orm|postgres|valibot|@electric-sql\/client|evlog)(\/|$)/
+				]
+			};
+			const exclude = options.esbuild?.options?.exclude ?? /node_modules/;
+			options.esbuild = {
+				...options.esbuild,
+				options: {
+					...options.esbuild?.options,
+					exclude: [exclude].flat().map((pattern) => typeof pattern === "string" ? pattern : exceptRuntime(pattern))
+				}
+			};
+			if (useContentDatabase) {
+				options.experimental = {
+					...options.experimental,
+					envExpansion: true
+				};
+				if (options.runtimeConfig?.content) options.runtimeConfig.content.database = CONTENT_DATABASE;
+			}
+			if (!nuxt.options.dev) options.rollupConfig = {
+				...options.rollupConfig,
+				plugins: [...[options.rollupConfig?.plugins ?? []].flat(), prefixNodeBuiltins()]
+			};
+			options.unenv = [...options.unenv ? [options.unenv].flat() : [], { inject: {
+				Buffer: ["node:buffer", "Buffer"],
+				setImmediate: ["node:timers", "setImmediate"],
+				clearImmediate: ["node:timers", "clearImmediate"]
+			} }];
+		});
+		if (nuxt.options.dev && !nuxt.options._prepare) {
+			const app = await resolveAppName(nuxt.options.rootDir, options.app);
+			await setupDev(nuxt, app, options.dev ?? {});
+		}
+		if (nuxt.options.dev) for (const route of ["/_wervt/login", "/_wervt/logout"]) addServerHandler({
+			route,
+			handler: resolver.resolve("./runtime/server/dev-auth")
+		});
+		addServerHandler({
+			route: "/_wervt/user",
+			method: "get",
+			handler: resolver.resolve("./runtime/server/user-route")
+		});
+		addPlugin({
+			src: resolver.resolve("./runtime/app/plugins/user.client"),
+			mode: "client"
+		});
+		nuxt.options.build.transpile.push(resolver.resolve("./runtime"));
+		addImports([
+			{
+				name: "useShape",
+				from: resolver.resolve("./runtime/app/useShape")
+			},
+			{
+				name: "useWervtUser",
+				from: resolver.resolve("./runtime/app/useWervtUser")
+			},
+			{
+				name: "wervtLoginUrl",
+				from: resolver.resolve("./runtime/app/useWervtUser")
+			},
+			{
+				name: "wervtLogoutUrl",
+				from: resolver.resolve("./runtime/app/useWervtUser")
+			}
+		]);
+	}
+});
+const BUILTINS = new Set(builtinModules.filter((name) => !name.startsWith("_")));
+/** Rewrites `from 'os'` / `import('os')` to `node:os` in the output chunks. */
+function prefixNodeBuiltins() {
+	const IMPORT_RE = /(\bfrom\s*|\bimport\s*\(\s*|\bimport\s+)(['"])([a-z_/]+)\2/g;
+	return {
+		name: "wervt:prefix-node-builtins",
+		renderChunk(code) {
+			let changed = false;
+			const out = code.replace(IMPORT_RE, (match, lead, quote, id) => {
+				if (!BUILTINS.has(id)) return match;
+				changed = true;
+				return `${lead}${quote}node:${id}${quote}`;
+			});
+			return changed ? {
+				code: out,
+				map: null
+			} : null;
+		}
+	};
+}
+/** `pattern`, except for files of this module's runtime. */
+function exceptRuntime(pattern) {
+	if (pattern.source.startsWith("^")) return pattern;
+	return new RegExp(`^(?![\\s\\S]*[\\\\/]@wervt[\\\\/]nuxt[\\\\/]src[\\\\/]runtime[\\\\/])[\\s\\S]*?(?:${pattern.source})`, pattern.flags);
+}
+//#endregion
+export { module_default as default };

package/dist/provision.d.ts

@@ -0,0 +1,26 @@
+//#region src/provision.d.ts
+export interface ProvisionOptions {
+  /** App name, `[a-z0-9-]+`. */
+  app: string;
+  /** Superuser connection URL to the `wervt` database. */
+  adminUrl: string;
+  /** Secret the role password is derived from (WERVT_DB_SECRET). */
+  secret: string;
+  /** Drizzle migrations folder. Skipped when undefined. */
+  migrationsFolder?: string;
+}
+export declare function dbRole(app: string): string;
+export declare function hmac(secret: string, message: string): Promise<string>;
+export declare function dbPassword(app: string, secret: string): Promise<string>;
+/** Connection URL for the app's own role, on the same host and database as `adminUrl`. */
+export declare function appDatabaseUrl({ app, adminUrl, secret }: ProvisionOptions): Promise<string>;
+/**
+ * Creates (or updates) the app's role and schema and runs its Drizzle migrations as
+ * that role. Each app gets a role and schema named `app_<name>`; the role's
+ * search_path is its own schema, it can't create schemas or touch `public`, and it can
+ * only connect to the wervt database.
+ */
+export declare function provisionDatabase(options: ProvisionOptions): Promise<void>;
+/** Drops the app's schema (all its data) and role. */
+export declare function dropDatabase({ app, adminUrl }: Pick<ProvisionOptions, 'app' | 'adminUrl'>): Promise<void>;
+//#endregion

package/dist/provision.js

@@ -0,0 +1,123 @@
+import { drizzle } from "drizzle-orm/postgres-js";
+import { migrate } from "drizzle-orm/postgres-js/migrator";
+import postgres from "postgres";
+//#region src/provision.ts
+function dbRole(app) {
+	return `app_${app.replaceAll("-", "_")}`;
+}
+async function hmac(secret, message) {
+	const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+	const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(message));
+	return Array.from(new Uint8Array(sig), (b) => b.toString(16).padStart(2, "0")).join("");
+}
+function dbPassword(app, secret) {
+	return hmac(secret, app);
+}
+/** Connection URL for the app's own role, on the same host and database as `adminUrl`. */
+async function appDatabaseUrl({ app, adminUrl, secret }) {
+	const url = new URL(adminUrl);
+	url.username = dbRole(app);
+	url.password = await dbPassword(app, secret);
+	return url.href;
+}
+/**
+* Creates (or updates) the app's role and schema and runs its Drizzle migrations as
+* that role. Each app gets a role and schema named `app_<name>`; the role's
+* search_path is its own schema, it can't create schemas or touch `public`, and it can
+* only connect to the wervt database.
+*/
+async function provisionDatabase(options) {
+	const { app, adminUrl, secret, migrationsFolder } = options;
+	const role = dbRole(app);
+	const password = await dbPassword(app, secret);
+	const database = new URL(adminUrl).pathname.slice(1);
+	const admin = postgres(adminUrl, {
+		max: 1,
+		onnotice: () => {}
+	});
+	try {
+		const [row] = await admin`select exists(select 1 from pg_roles where rolname = ${role})`;
+		const exists = Boolean(row?.exists);
+		await admin.unsafe(`${exists ? "alter" : "create"} role "${role}" login password '${password}' connection limit 10`);
+		await admin.unsafe(`create schema if not exists "${role}" authorization "${role}"`);
+		await claimSchema(admin, role);
+		await admin.unsafe(`alter role "${role}" set search_path = "${role}"`);
+		for (const db of [
+			database,
+			"postgres",
+			"template1"
+		]) await admin.unsafe(`revoke all on database "${db}" from public`);
+		await admin.unsafe(`grant connect on database "${database}" to "${role}"`);
+		await admin.unsafe(`revoke all on schema public from public`);
+		if (!migrationsFolder) return;
+		await admin.unsafe(`grant create on database "${database}" to "${role}"`);
+		const client = postgres(await appDatabaseUrl(options), {
+			max: 1,
+			onnotice: () => {}
+		});
+		try {
+			await migrate(drizzle({ client }), {
+				migrationsFolder,
+				migrationsSchema: role
+			});
+		} finally {
+			await client.end();
+			await admin.unsafe(`revoke create on database "${database}" from "${role}"`);
+		}
+	} finally {
+		await admin.end();
+	}
+}
+/**
+* Gives the role its schema and everything in it back. A dump restored with `--no-owner`
+* (Coolify's backups) leaves all of it owned by the restoring superuser.
+*/
+async function claimSchema(admin, role) {
+	await admin.unsafe(`alter schema "${role}" owner to "${role}"`);
+	const objects = await admin`
+    select case c.relkind when 'S' then 'sequence' when 'v' then 'view'
+             when 'm' then 'materialized view' when 'f' then 'foreign table' else 'table' end as kind,
+           format('%I.%I', n.nspname, c.relname) as name
+      from pg_class c join pg_namespace n on n.oid = c.relnamespace
+     where n.nspname = ${role} and c.relkind in ('r', 'p', 'v', 'm', 'f', 'S')
+       and c.relowner <> ${role}::regrole
+       -- identity and serial sequences follow their table
+       and not exists (select 1 from pg_depend d where d.classid = 'pg_class'::regclass
+             and d.objid = c.oid and d.deptype in ('a', 'i'))
+    union all
+    select case t.typtype when 'd' then 'domain' else 'type' end, format('%I.%I', n.nspname, t.typname)
+      from pg_type t join pg_namespace n on n.oid = t.typnamespace
+     where n.nspname = ${role} and t.typtype in ('e', 'd')
+       and t.typowner <> ${role}::regrole
+    union all
+    select case p.prokind when 'p' then 'procedure' when 'a' then 'aggregate' else 'function' end,
+           p.oid::regprocedure::text
+      from pg_proc p join pg_namespace n on n.oid = p.pronamespace
+     where n.nspname = ${role} and p.proowner <> ${role}::regrole`;
+	for (const { kind, name } of objects) await admin.unsafe(`alter ${kind} ${name} owner to "${role}"`);
+}
+/** Drops the app's schema (all its data) and role. */
+async function dropDatabase({ app, adminUrl }) {
+	const role = dbRole(app);
+	const database = new URL(adminUrl).pathname.slice(1);
+	const admin = postgres(adminUrl, {
+		max: 1,
+		onnotice: () => {}
+	});
+	try {
+		await admin`select pg_terminate_backend(pid) from pg_stat_activity where usename = ${role}`;
+		await admin.unsafe(`drop schema if exists "${role}" cascade`);
+		const [row] = await admin`select exists(select 1 from pg_roles where rolname = ${role})`;
+		if (Boolean(row?.exists)) {
+			await admin.unsafe(`revoke all on database "${database}" from "${role}"`);
+			await admin.unsafe(`drop role "${role}"`);
+		}
+	} finally {
+		await admin.end();
+	}
+}
+//#endregion
+export { appDatabaseUrl, dbPassword, dbRole, dropDatabase, hmac, provisionDatabase };

package/dist/runtime/app/plugins/user.client.d.ts

@@ -0,0 +1,4 @@
+//#region src/runtime/app/plugins/user.client.d.ts
+declare const _default: import("#app").Plugin<Record<string, unknown>> & import("#app").ObjectPlugin<Record<string, unknown>>;
+//#endregion
+export { _default as default };

package/dist/runtime/app/plugins/user.client.js

@@ -0,0 +1,18 @@
+import { useWervtUser } from "../useWervtUser.js";
+import { defineNuxtPlugin } from "#app";
+//#region src/runtime/app/plugins/user.client.ts
+var user_client_default = defineNuxtPlugin({
+	name: "wervt:user",
+	async setup(nuxtApp) {
+		if (nuxtApp.payload.serverRendered) return;
+		const user = useWervtUser();
+		try {
+			const res = await fetch("/_wervt/user");
+			user.value = res.ok ? (await res.json()).user : null;
+		} catch {
+			user.value = null;
+		}
+	}
+});
+//#endregion
+export { user_client_default as default };

package/dist/runtime/app/useShape.d.ts

@@ -0,0 +1,26 @@
+import { Row } from "@electric-sql/client";
+//#region src/runtime/app/useShape.d.ts
+export interface UseShapeOptions {
+  /** Payload key. Defaults to the path. */
+  key?: string;
+  /** Keep the shape live on the client. Defaults to true. */
+  live?: boolean;
+}
+/**
+ * Live rows of an Electric shape served by one of the app's shape routes
+ * (see `proxyShape`). The snapshot is loaded during SSR and sent in the payload;
+ * the client resumes the stream from the snapshot's offset, so rows are not
+ * fetched twice.
+ *
+ * @example const { data: todos } = await useShape<Todo>('/api/shapes/todos')
+ */
+export declare function useShape<T extends Row<unknown>>(path: string, options?: UseShapeOptions): Promise<{
+  data: import("vue").ShallowRef<T[], T[]>;
+  error: import("vue").Ref<unknown, unknown>;
+  isLive: import("vue").Ref<boolean, boolean>;
+}> & {
+  data: import("vue").ShallowRef<T[], T[]>;
+  error: import("vue").Ref<unknown, unknown>;
+  isLive: import("vue").Ref<boolean, boolean>;
+};
+//#endregion

package/dist/runtime/app/useShape.js

@@ -0,0 +1,140 @@
+import { ShapeStream, isChangeMessage, isControlMessage } from "@electric-sql/client";
+import { getCurrentScope, onScopeDispose, ref, shallowRef } from "vue";
+import { onNuxtReady, useAsyncData, useRequestEvent, useRequestFetch } from "#app";
+//#region src/runtime/app/useShape.ts
+/**
+* Live rows of an Electric shape served by one of the app's shape routes
+* (see `proxyShape`). The snapshot is loaded during SSR and sent in the payload;
+* the client resumes the stream from the snapshot's offset, so rows are not
+* fetched twice.
+*
+* @example const { data: todos } = await useShape<Todo>('/api/shapes/todos')
+*/
+function useShape(path, options = {}) {
+	const fetchClient = import.meta.server ? inProcessFetch() : void 0;
+	const asyncData = useAsyncData(options.key ?? `wervt-shape:${path}`, () => loadSnapshot(path, fetchClient));
+	const rows = /* @__PURE__ */ new Map();
+	const data = shallowRef([]);
+	const error = ref(null);
+	const isLive = ref(false);
+	const result = {
+		data,
+		error,
+		isLive
+	};
+	const ready = Promise.resolve(asyncData).then(() => {
+		for (const [key, row] of asyncData.data.value?.rows ?? []) rows.set(key, row);
+		data.value = [...rows.values()];
+		error.value = asyncData.error.value ?? null;
+		if (error.value) console.error(`[wervt] useShape('${path}') failed:`, error.value);
+		return result;
+	});
+	if (import.meta.client && options.live !== false) {
+		let stream;
+		const controller = new AbortController();
+		onNuxtReady(async () => {
+			await ready;
+			if (controller.signal.aborted) return;
+			const snapshot = asyncData.data.value;
+			stream = new ShapeStream({
+				url: absolute(path),
+				offset: snapshot?.offset,
+				handle: snapshot?.handle,
+				signal: controller.signal,
+				onError: (e) => {
+					error.value = e;
+				}
+			});
+			stream.subscribe((messages) => {
+				if (applyMessages(rows, messages)) data.value = [...rows.values()];
+				isLive.value = stream?.isUpToDate ?? false;
+			});
+		});
+		if (getCurrentScope()) onScopeDispose(() => {
+			controller.abort();
+			stream?.unsubscribeAll();
+		});
+	}
+	return Object.assign(ready, result);
+}
+async function loadSnapshot(path, fetchClient) {
+	const rows = /* @__PURE__ */ new Map();
+	let fail = () => {};
+	const stream = new ShapeStream({
+		url: absolute(path),
+		subscribe: false,
+		fetchClient,
+		onError: (e) => fail(e)
+	});
+	await new Promise((resolve, reject) => {
+		fail = reject;
+		stream.subscribe((messages) => {
+			applyMessages(rows, messages);
+			if (stream.isUpToDate) resolve();
+		}, (e) => reject(e));
+	});
+	stream.unsubscribeAll();
+	return {
+		rows: [...rows],
+		offset: stream.lastOffset,
+		handle: stream.shapeHandle
+	};
+}
+/** Applies Electric change messages to `rows`. Returns whether anything changed. */
+function applyMessages(rows, messages) {
+	let changed = false;
+	for (const message of messages) if (isChangeMessage(message)) {
+		const { key, value } = message;
+		switch (message.headers.operation) {
+			case "insert":
+				rows.set(key, value);
+				break;
+			case "update":
+				rows.set(key, {
+					...rows.get(key),
+					...value
+				});
+				break;
+			case "delete": rows.delete(key);
+		}
+		changed = true;
+	} else if (isControlMessage(message) && message.headers.control === "must-refetch") {
+		rows.clear();
+		changed = true;
+	}
+	return changed;
+}
+/**
+* During SSR, calls the shape route in-process with the request's headers (cookies, auth).
+* Nitro 2 (Nuxt 4.6) has `event.fetch`, which returns a Response; on Nitro 3 (Nuxt 5) the
+* request's `$fetch` has `.raw`.
+*/
+function inProcessFetch() {
+	const event = useRequestEvent();
+	if (typeof event?.fetch === "function") {
+		const eventFetch = event.fetch;
+		return ((input, init) => {
+			const url = new URL(input instanceof Request ? input.url : input);
+			return eventFetch(url.pathname + url.search, init);
+		});
+	}
+	const requestFetch = useRequestFetch();
+	return (async (input, init) => {
+		const url = new URL(input instanceof Request ? input.url : input);
+		const res = await requestFetch.raw(url.pathname + url.search, {
+			method: init?.method ?? "GET",
+			headers: init?.headers,
+			responseType: "stream",
+			ignoreResponseError: true
+		});
+		return new Response(res._data, {
+			status: res.status,
+			headers: res.headers
+		});
+	});
+}
+function absolute(path) {
+	return new URL(path, import.meta.client ? location.origin : "http://localhost").href;
+}
+//#endregion
+export { useShape };

package/dist/runtime/app/useWervtUser.d.ts

@@ -0,0 +1,13 @@
+import { WervtUser } from "../shared/user.js";
+//#region src/runtime/app/useWervtUser.d.ts
+/**
+ * The signed-in wervt user, or `null`. Read during SSR and kept in the payload; apps without
+ * SSR load it from `/_wervt/user` before they render. Public apps get one when the visitor
+ * is signed in.
+ */
+export declare function useWervtUser(): import("vue").Ref<WervtUser | null, WervtUser | null>;
+/** Sign in with wervt, then come back to `redirect` (a path in this app). */
+export declare const wervtLoginUrl: (redirect?: string) => string;
+/** Sign out of wervt (all apps), then come back to `redirect`. */
+export declare const wervtLogoutUrl: (redirect?: string) => string;
+//#endregion

package/dist/runtime/app/useWervtUser.js

@@ -0,0 +1,18 @@
+import { DEV_LOGIN_COOKIE, devUser, parseWervtUser } from "../shared/user.js";
+import { useCookie, useRequestHeaders, useState } from "#app";
+//#region src/runtime/app/useWervtUser.ts
+/**
+* The signed-in wervt user, or `null`. Read during SSR and kept in the payload; apps without
+* SSR load it from `/_wervt/user` before they render. Public apps get one when the visitor
+* is signed in.
+*/
+function useWervtUser() {
+	const devLogin = import.meta.dev ? useCookie(DEV_LOGIN_COOKIE) : void 0;
+	return useState("wervt-user", () => import.meta.server ? parseWervtUser(useRequestHeaders(["x-wervt-user"])["x-wervt-user"]) ?? devUser(String(devLogin?.value) === "1") ?? null : null);
+}
+/** Sign in with wervt, then come back to `redirect` (a path in this app). */
+const wervtLoginUrl = (redirect = "/") => `/_wervt/login?redirect=${encodeURIComponent(redirect)}`;
+/** Sign out of wervt (all apps), then come back to `redirect`. */
+const wervtLogoutUrl = (redirect = "/") => `/_wervt/logout?redirect=${encodeURIComponent(redirect)}`;
+//#endregion
+export { useWervtUser, wervtLoginUrl, wervtLogoutUrl };

package/dist/runtime/server/db.d.ts

@@ -0,0 +1,19 @@
+import { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import { AnyRelations, EmptyRelations } from "drizzle-orm";
+//#region src/runtime/server/db.d.ts
+/**
+ * Drizzle client for the app's database. In production the wervt runtime injects
+ * DATABASE_URL for the app's own role, whose search_path is its own schema, so
+ * tables are declared without a schema.
+ *
+ * Pass the app's relations (from `defineRelations`) to use `db.query.*`. All clients
+ * share one connection pool.
+ *
+ * @example
+ * const db = useDb({ relations })
+ * const room = await db.query.rooms.findFirst({ where: { id }, with: { players: true } })
+ */
+export declare function useDb<TRelations extends AnyRelations = EmptyRelations>(options?: {
+  relations?: TRelations;
+}): PostgresJsDatabase<TRelations>;
+//#endregion

package/dist/runtime/server/db.js

@@ -0,0 +1,36 @@
+import { drizzle } from "drizzle-orm/postgres-js";
+import postgres from "postgres";
+//#region src/runtime/server/db.ts
+let client;
+const clients = /* @__PURE__ */ new Map();
+/**
+* Drizzle client for the app's database. In production the wervt runtime injects
+* DATABASE_URL for the app's own role, whose search_path is its own schema, so
+* tables are declared without a schema.
+*
+* Pass the app's relations (from `defineRelations`) to use `db.query.*`. All clients
+* share one connection pool.
+*
+* @example
+* const db = useDb({ relations })
+* const room = await db.query.rooms.findFirst({ where: { id }, with: { players: true } })
+*/
+function useDb(options) {
+	if (!process.env.DATABASE_URL) throw new Error("DATABASE_URL is not set");
+	client ??= postgres(process.env.DATABASE_URL, {
+		max: 2,
+		idle_timeout: 20
+	});
+	const relations = options?.relations;
+	let db = clients.get(relations);
+	if (!db) {
+		db = drizzle({
+			client,
+			relations
+		});
+		clients.set(relations, db);
+	}
+	return db;
+}
+//#endregion
+export { useDb };

package/dist/runtime/server/dev-auth.d.ts

@@ -0,0 +1,4 @@
+//#region src/runtime/server/dev-auth.d.ts
+declare const _default: import("nuxt/server").EventHandler<string>;
+//#endregion
+export { _default as default };

package/dist/runtime/server/dev-auth.js

@@ -0,0 +1,15 @@
+import { DEV_LOGIN_COOKIE } from "../shared/user.js";
+import { defineEventHandler, deleteCookie, getQuery, sendRedirect, setCookie } from "nuxt/server";
+//#region src/runtime/server/dev-auth.ts
+var dev_auth_default = defineEventHandler((event) => {
+	const { redirect } = getQuery(event);
+	const target = typeof redirect === "string" && redirect.startsWith("/") ? redirect : "/";
+	if (new URL(event.req.url).pathname === "/_wervt/login") setCookie(event, DEV_LOGIN_COOKIE, "1", {
+		path: "/",
+		sameSite: "lax"
+	});
+	else deleteCookie(event, DEV_LOGIN_COOKIE, { path: "/" });
+	return sendRedirect(event, target);
+});
+//#endregion
+export { dev_auth_default as default };

package/dist/runtime/server/index.d.ts

@@ -0,0 +1,6 @@
+import { WervtUser } from "../shared/user.js";
+import { useDb } from "./db.js";
+import { ShapeOptions, proxyShape } from "./shape.js";
+import { useWervtUser } from "./user.js";
+import { SafeResult, useSafeValidatedBody, useSafeValidatedParams, useSafeValidatedQuery, useValidatedBody, useValidatedParams, useValidatedQuery, vh } from "./validate.js";
+export { type SafeResult, type ShapeOptions, type WervtUser, proxyShape, useDb, useSafeValidatedBody, useSafeValidatedParams, useSafeValidatedQuery, useValidatedBody, useValidatedParams, useValidatedQuery, useWervtUser, vh };

package/dist/runtime/server/index.js

@@ -0,0 +1,5 @@
+import { useDb } from "./db.js";
+import { proxyShape } from "./shape.js";
+import { useWervtUser } from "./user.js";
+import { useSafeValidatedBody, useSafeValidatedParams, useSafeValidatedQuery, useValidatedBody, useValidatedParams, useValidatedQuery, vh } from "./validate.js";
+export { proxyShape, useDb, useSafeValidatedBody, useSafeValidatedParams, useSafeValidatedQuery, useValidatedBody, useValidatedParams, useValidatedQuery, useWervtUser, vh };

package/dist/runtime/server/shape.d.ts

@@ -0,0 +1,19 @@
+import { RequestEvent } from "nuxt/server";
+//#region src/runtime/server/shape.d.ts
+export interface ShapeOptions {
+  /** Table name without schema. */
+  table: string;
+  /** SQL where clause. Use `$1`, `$2`, … placeholders with `params` for values. */
+  where?: string;
+  /** Values for the `$n` placeholders in `where`. */
+  params?: (string | number | boolean)[];
+  columns?: string[];
+}
+/**
+ * Serves an Electric shape from a route. Do auth checks before calling it.
+ *
+ * In production the request goes through the wervt runtime gateway, which pins the
+ * table to this app's schema. In dev it goes to Electric directly (ELECTRIC_URL).
+ */
+export declare function proxyShape(event: RequestEvent, { table, where, params, columns }: ShapeOptions): Promise<Response>;
+//#endregion

package/dist/runtime/server/shape.js

@@ -0,0 +1,55 @@
+//#region src/runtime/server/shape.ts
+const CLIENT_PARAMS = [
+	"offset",
+	"handle",
+	"live",
+	"live_sse",
+	"cursor",
+	"replica",
+	"log"
+];
+/**
+* Serves an Electric shape from a route. Do auth checks before calling it.
+*
+* In production the request goes through the wervt runtime gateway, which pins the
+* table to this app's schema. In dev it goes to Electric directly (ELECTRIC_URL).
+*/
+async function proxyShape(event, { table, where, params, columns }) {
+	const runtime = process.env.WERVT_RUNTIME_URL;
+	const url = runtime ? new URL("/_wervt/electric/v1/shape", runtime) : new URL("/v1/shape", process.env.ELECTRIC_URL ?? "http://localhost:3000");
+	const query = new URL(event.req.url).searchParams;
+	for (const key of CLIENT_PARAMS) {
+		const value = query.get(key);
+		if (value !== null) url.searchParams.set(key, value);
+	}
+	url.searchParams.set("table", runtime ? table : devTable(table));
+	if (where) url.searchParams.set("where", where);
+	params?.forEach((value, i) => url.searchParams.set(`params[${i + 1}]`, String(value)));
+	if (columns) url.searchParams.set("columns", columns.map(quoteIdentifier).join(","));
+	if (!runtime && process.env.ELECTRIC_SECRET) url.searchParams.set("secret", process.env.ELECTRIC_SECRET);
+	const headers = {};
+	if (runtime) {
+		headers["x-wervt-app"] = process.env.WERVT_APP ?? "";
+		headers["x-wervt-token"] = process.env.WERVT_TOKEN ?? "";
+	}
+	const res = await fetch(url, {
+		headers,
+		signal: event.req.signal
+	});
+	const out = new Headers(res.headers);
+	out.delete("content-encoding");
+	out.delete("content-length");
+	return new Response(res.body, {
+		status: res.status,
+		headers: out
+	});
+}
+function devTable(table) {
+	const schema = process.env.WERVT_DB_SCHEMA;
+	return schema ? `${schema}.${table}` : table;
+}
+function quoteIdentifier(name) {
+	return /^[a-z_][a-z0-9_]*$/.test(name) ? name : `"${name.replaceAll("\"", "\"\"")}"`;
+}
+//#endregion
+export { proxyShape };

package/dist/runtime/server/user-route.d.ts

@@ -0,0 +1,8 @@
+import { WervtUser } from "../shared/user.js";
+import "./user.js";
+//#region src/runtime/server/user-route.d.ts
+declare const _default: import("nuxt/server").EventHandler<{
+  user: WervtUser | null;
+}>;
+//#endregion
+export { _default as default };

package/dist/runtime/server/user-route.js

@@ -0,0 +1,9 @@
+import { useWervtUser } from "./user.js";
+import { defineEventHandler } from "nuxt/server";
+//#region src/runtime/server/user-route.ts
+var user_route_default = defineEventHandler((event) => {
+	event.res.headers.set("cache-control", "private, no-store");
+	return { user: useWervtUser(event) ?? null };
+});
+//#endregion
+export { user_route_default as default };

package/dist/runtime/server/user.d.ts

@@ -0,0 +1,12 @@
+import { DEV_LOGIN_COOKIE, WervtUser, parseWervtUser } from "../shared/user.js";
+import "./user.js";
+import { RequestEvent } from "nuxt/server";
+//#region src/runtime/server/user.d.ts
+/**
+ * The signed-in wervt user, or `undefined` when nobody is signed in.
+ * Private apps always have one (the runtime checked the login and the allow-list); public
+ * apps get one when the visitor is signed in. Send people to `/_wervt/login` to sign in.
+ */
+export declare const useWervtUser: (event: RequestEvent) => WervtUser | undefined;
+//#endregion
+export { DEV_LOGIN_COOKIE, type WervtUser, parseWervtUser };

package/dist/runtime/server/user.js

@@ -0,0 +1,11 @@
+import { DEV_LOGIN_COOKIE, devUser, parseWervtUser } from "../shared/user.js";
+import { getCookie } from "nuxt/server";
+//#region src/runtime/server/user.ts
+/**
+* The signed-in wervt user, or `undefined` when nobody is signed in.
+* Private apps always have one (the runtime checked the login and the allow-list); public
+* apps get one when the visitor is signed in. Send people to `/_wervt/login` to sign in.
+*/
+const useWervtUser = (event) => parseWervtUser(event.req.headers.get("x-wervt-user")) ?? devUser(getCookie(event, "wervt_dev_login") === "1");
+//#endregion
+export { DEV_LOGIN_COOKIE, parseWervtUser, useWervtUser };

package/dist/runtime/server/validate.d.ts

@@ -0,0 +1,40 @@
+import { RequestEvent } from "nuxt/server";
+import * as v from "valibot";
+//#region src/runtime/server/validate.d.ts
+type Schema = v.GenericSchema | v.GenericSchemaAsync;
+type Shape = v.ObjectEntriesAsync;
+type Input = Schema | Shape;
+type Output<T extends Input> = T extends Schema ? v.InferOutput<T> : T extends Shape ? v.InferOutput<v.ObjectSchemaAsync<T, undefined>> : never;
+export type SafeResult<T extends Input> = {
+  success: true;
+  data: Output<T>;
+  issues?: undefined;
+} | {
+  success: false;
+  data?: undefined;
+  issues: v.FlatErrors<undefined>;
+};
+/** Parsed JSON body. Throws a 400 with flattened issues when invalid. */
+export declare const useValidatedBody: <T extends Input>(event: RequestEvent, schema: T) => Promise<Output<T>>;
+/** Query parameters (strings; use `vh.*` to coerce). Throws a 400 when invalid. */
+export declare const useValidatedQuery: <T extends Input>(event: RequestEvent, schema: T) => Promise<Output<T>>;
+/** Route params like `[id]` (strings; use `vh.*` to coerce). Throws a 400 when invalid. */
+export declare const useValidatedParams: <T extends Input>(event: RequestEvent, schema: T) => Promise<Output<T>>;
+/** Like `useValidatedBody`, but returns `{ success, data | issues }` instead of throwing. */
+export declare const useSafeValidatedBody: <T extends Input>(event: RequestEvent, schema: T) => Promise<SafeResult<T>>;
+export declare const useSafeValidatedQuery: <T extends Input>(event: RequestEvent, schema: T) => Promise<SafeResult<T>>;
+export declare const useSafeValidatedParams: <T extends Input>(event: RequestEvent, schema: T) => Promise<SafeResult<T>>;
+/** Schemas for values that arrive as strings (query, route params, form fields). */
+export declare const vh: {
+  /** `'true'` / `'false'` → boolean. */
+  boolAsString: v.SchemaWithPipe<readonly [v.PicklistSchema<["true", "false"], undefined>, v.TransformAction<"true" | "false", boolean>]>;
+  /** HTML checkbox: `'on'` or missing → boolean. */
+  checkboxAsString: v.SchemaWithPipe<readonly [v.OptionalSchema<v.LiteralSchema<"on", undefined>, undefined>, v.TransformAction<"on" | undefined, boolean>]>;
+  /** Integer string → number. */
+  intAsString: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>, v.TransformAction<any, number>, v.SafeIntegerAction<number, undefined>]>;
+  /** Numeric string → number. */
+  numAsString: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.DecimalAction<string, undefined>, v.TransformAction<any, number>]>;
+  /** Positive integer id (e.g. a serial primary key) → number. */
+  id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.DigitsAction<string, undefined>, v.TransformAction<any, number>, v.SafeIntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>;
+};
+//#endregion

package/dist/runtime/server/validate.js

@@ -0,0 +1,51 @@
+import { createError, getQuery, getRouterParams, readBody } from "nuxt/server";
+import * as v from "valibot";
+//#region src/runtime/server/validate.ts
+function toSchema(input) {
+	return "kind" in input && input.kind === "schema" ? input : v.objectAsync(input);
+}
+async function safeValidate(input, data) {
+	const result = await v.safeParseAsync(toSchema(input), data);
+	return result.success ? {
+		success: true,
+		data: result.output
+	} : {
+		success: false,
+		issues: v.flatten(result.issues)
+	};
+}
+async function validate(input, data) {
+	const result = await safeValidate(input, data);
+	if (result.success) return result.data;
+	throw createError({
+		status: 400,
+		statusText: "Validation failed",
+		message: "Validation failed",
+		data: result.issues
+	});
+}
+/** Parsed JSON body. Throws a 400 with flattened issues when invalid. */
+const useValidatedBody = (event, schema) => readBody(event).then((body) => validate(schema, body));
+/** Query parameters (strings; use `vh.*` to coerce). Throws a 400 when invalid. */
+const useValidatedQuery = (event, schema) => validate(schema, getQuery(event));
+/** Route params like `[id]` (strings; use `vh.*` to coerce). Throws a 400 when invalid. */
+const useValidatedParams = (event, schema) => validate(schema, getRouterParams(event, { decode: true }));
+/** Like `useValidatedBody`, but returns `{ success, data | issues }` instead of throwing. */
+const useSafeValidatedBody = (event, schema) => readBody(event).then((body) => safeValidate(schema, body));
+const useSafeValidatedQuery = (event, schema) => safeValidate(schema, getQuery(event));
+const useSafeValidatedParams = (event, schema) => safeValidate(schema, getRouterParams(event, { decode: true }));
+/** Schemas for values that arrive as strings (query, route params, form fields). */
+const vh = {
+	/** `'true'` / `'false'` → boolean. */
+	boolAsString: v.pipe(v.picklist(["true", "false"]), v.transform((s) => s === "true")),
+	/** HTML checkbox: `'on'` or missing → boolean. */
+	checkboxAsString: v.pipe(v.optional(v.literal("on")), v.transform((s) => s === "on")),
+	/** Integer string → number. */
+	intAsString: v.pipe(v.string(), v.regex(/^-?\d+$/), v.transform(Number), v.safeInteger()),
+	/** Numeric string → number. */
+	numAsString: v.pipe(v.string(), v.decimal(), v.transform(Number)),
+	/** Positive integer id (e.g. a serial primary key) → number. */
+	id: v.pipe(v.string(), v.digits(), v.transform(Number), v.safeInteger(), v.minValue(1))
+};
+//#endregion
+export { useSafeValidatedBody, useSafeValidatedParams, useSafeValidatedQuery, useValidatedBody, useValidatedParams, useValidatedQuery, vh };

package/dist/runtime/shared/user.d.ts

@@ -0,0 +1,16 @@
+//#region src/runtime/shared/user.d.ts
+export interface WervtUser {
+  id: string;
+  email: string;
+  name?: string;
+  image?: string;
+  /** Linked login accounts, provider id to the user's id there, e.g. `{ twitch: '1234' }`. */
+  accounts?: Record<string, string>;
+}
+/** Cookie set by the dev stand-in for `/_wervt/login` (see `server/dev-auth.ts`). */
+export declare const DEV_LOGIN_COOKIE = "wervt_dev_login";
+/** Parses the `x-wervt-user` header the runtime sets (and strips from client requests). */
+export declare function parseWervtUser(header: string | null | undefined): WervtUser | undefined;
+/** During `nuxt dev`: the configured dev user, after `/_wervt/login`. */
+export declare function devUser(loggedIn: boolean): WervtUser | undefined;
+//#endregion

package/dist/runtime/shared/user.js

@@ -0,0 +1,20 @@
+//#region src/runtime/shared/user.ts
+/** Cookie set by the dev stand-in for `/_wervt/login` (see `server/dev-auth.ts`). */
+const DEV_LOGIN_COOKIE = "wervt_dev_login";
+/** Parses the `x-wervt-user` header the runtime sets (and strips from client requests). */
+function parseWervtUser(header) {
+	if (!header) return void 0;
+	try {
+		return JSON.parse(decodeURIComponent(header));
+	} catch {
+		return;
+	}
+}
+/** During `nuxt dev`: the configured dev user, after `/_wervt/login`. */
+function devUser(loggedIn) {
+	const user = process.env.WERVT_DEV_USER;
+	if (!import.meta.dev || !loggedIn || !user) return void 0;
+	return JSON.parse(user);
+}
+//#endregion
+export { DEV_LOGIN_COOKIE, devUser, parseWervtUser };

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@wervt/nuxt",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Nuxt module for apps hosted on wervt: database, live data and runtime setup.",
+  "keywords": [
+    "drizzle",
+    "electric",
+    "nuxt",
+    "nuxt-module",
+    "postgres",
+    "wervt"
+  ],
+  "homepage": "https://wervt.app",
+  "license": "MIT",
+  "author": "Niki2k1",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wervt-app/wervt.git",
+    "directory": "packages/nuxt"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/module.d.ts",
+      "default": "./dist/module.js"
+    },
+    "./server": {
+      "types": "./dist/runtime/server/index.d.ts",
+      "default": "./dist/runtime/server/index.js"
+    },
+    "./provision": {
+      "types": "./dist/provision.d.ts",
+      "default": "./dist/provision.js"
+    }
+  },
+  "dependencies": {
+    "@electric-sql/client": "^1.5.28",
+    "evlog": "^2.30.0",
+    "postgres": "^3.4.9",
+    "valibot": "^1.5.0"
+  },
+  "devDependencies": {
+    "drizzle-orm": "1.0.0-rc.4",
+    "nitro": "3.0.260903-beta",
+    "nuxt": "npm:nuxt-nightly@5x",
+    "vue": "^3.5.43"
+  },
+  "peerDependencies": {
+    "drizzle-orm": "1.0.0-rc.4",
+    "nuxt": ">=4.2"
+  },
+  "scripts": {
+    "build": "vp pack"
+  }
 }