@wervt/nuxt 0.2.15 → 0.3.0

package/README.md

@@ -23,7 +23,8 @@ export default defineNuxtConfig({
 - `wervt: { feedback: { key } }` and `useWervtFeedback()`: the kontor feedback widget, reports go into a kontor project's triage.
 - `defineTool()` (server): tools in `server/tools/` that browser agents call through WebMCP, and
   MCP clients (Claude Code, Cursor, …) at `/mcp`, signed in through wervt's OAuth login.
-- `nuxt dev` starts against the local wervt stack (Postgres, Electric) and a dev user.
+- `nuxt dev` starts against the local wervt stack (Postgres, Electric) and a dev user, and runs
+  the `db:seed` task (`seedTable()` inserts into empty tables) once on a new database.
 
 Deploy with [`@wervt/cli`](https://www.npmjs.com/package/@wervt/cli): `wervt deploy`.
 

package/dist/dev.d.ts

@@ -11,6 +11,11 @@ export interface DevOptions {
   s3Url?: string;
   garageAdminUrl?: string;
   garageAdminToken?: string;
+  /**
+   * Runs the app's `db:seed` task (`server/tasks/db/seed.ts`) once its database was just created
+   * and migrated. Defaults to true; `false` leaves seeding to `nuxt task run db:seed`.
+   */
+  seed?: boolean;
   /**
    * 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.

package/dist/dev.js

@@ -1,5 +1,6 @@
 import { createStorage } from "./storage.js";
 import { appDatabaseUrl, dbRole, provisionDatabase, storageCredentials } from "./provision.js";
+import { SEED_TASK, runDevSeed } from "./seed.js";
 import { useLogger } from "nuxt/kit";
 import { existsSync, watch } from "node:fs";
 import { readFile } from "node:fs/promises";
@@ -17,8 +18,8 @@ const DEFAULTS = {
 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.
+* runs its migrations (again whenever `drizzle/` changes), seeds a new database and
+* points the dev server at the app's database and Electric.
 */
 async function setupDev(nuxt, app, options, features = {}) {
 	const config = {
@@ -42,10 +43,29 @@ async function setupDev(nuxt, app, options, features = {}) {
 		secret: config.dbSecret,
 		migrationsFolder
 	};
+	let serverUrl;
+	let seedPending = false;
+	const seed = async () => {
+		if (!seedPending || !serverUrl) return;
+		seedPending = false;
+		try {
+			if ((await runDevSeed(serverUrl)).status === "seeded") logger.success(`Seeded \`${dbRole(app)}\` (${SEED_TASK})`);
+		} catch (e) {
+			logger.warn(`\`${SEED_TASK}\` failed:`, e instanceof Error ? e.message : e);
+		}
+	};
+	if (options.seed !== false) nuxt.hook("listen", (_server, listener) => {
+		serverUrl = listener.url;
+		seed();
+	});
 	const migrate = async () => {
 		try {
-			await provisionDatabase(provision);
+			const { fresh } = await provisionDatabase(provision);
 			logger.success(`Database \`${dbRole(app)}\` is up to date`);
+			if (fresh && options.seed !== false) {
+				seedPending = true;
+				seed();
+			}
 		} catch (e) {
 			logger.warn(`Could not migrate \`${dbRole(app)}\`. Is the wervt stack running (docker compose up -d)?`, e instanceof Error ? e.message : e);
 		}

package/dist/module.js

@@ -1,5 +1,8 @@
+import { SEED_TASK, unscheduleSeed } from "./seed.js";
 import { resolveAppName, setupDev } from "./dev.js";
-import { addImports, addPlugin, addServerHandler, addServerPlugin, addServerTemplate, addTypeTemplate, createResolver, defineNuxtModule, getNuxtVersion, hasNuxtModule, installModule, useLogger } from "nuxt/kit";
+import { findRouteTools } from "./route-tools.js";
+import { findShapeRoutes, shapeRoutesTypes, shapesManifest } from "./shapes.js";
+import { addImports, addPlugin, addServerHandler, addServerPlugin, addServerTemplate, addTypeTemplate, createResolver, defineNuxtModule, getNuxtVersion, hasNuxtModule, installModule, updateTemplates, useLogger } from "nuxt/kit";
 import { existsSync } from "node:fs";
 import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import { builtinModules, createRequire } from "node:module";
@@ -128,6 +131,14 @@ var module_default = defineNuxtModule({
 			...nitro.experimental,
 			tasks: true
 		};
+		nuxt.hook("nitro:config", (config) => {
+			const options = config;
+			if (!options.scheduledTasks) return;
+			const { schedules, removed } = unscheduleSeed(options.scheduledTasks);
+			if (removed.length === 0) return;
+			logger.warn(`\`${SEED_TASK}\` is not scheduled (${removed.join(", ")}): seeding only runs on request.`);
+			options.scheduledTasks = schedules;
+		});
 		const nitroVersion = nitroMajor >= 3 ? "nitro3" : "nitro2";
 		addServerHandler({
 			route: "/_wervt/tasks/**",
@@ -165,14 +176,20 @@ var module_default = defineNuxtModule({
 		const toolsDir = join(nuxt.options.serverDir, "tools");
 		const webmcp = options.webmcp !== false;
 		let mcp = options.mcp !== false;
-		const tools = webmcp || mcp ? await findTools(toolsDir) : [];
+		const routeDirs = [join(nuxt.options.serverDir, "api"), join(nuxt.options.serverDir, "routes")];
+		const routeTools = webmcp || mcp ? (await Promise.all(routeDirs.map((dir) => findRouteTools(dir)))).flat().filter((tool) => {
+			if (TOOL_NAME_RE.test(tool.name)) return true;
+			logger.warn(`Skipping ${tool.path} as a tool: pass a \`tool.name\` without spaces.`);
+			return false;
+		}) : [];
+		const tools = webmcp || mcp ? [...await findTools(toolsDir), ...routeTools] : [];
 		if (tools.length > 0 && mcp && nitroMajor < 3) {
 			if (options.mcp) logger.warn("`/mcp` needs Nuxt 5; this app keeps its tools for WebMCP only.");
 			mcp = false;
 		}
 		if (tools.length > 0) addServerTemplate({
 			filename: "#wervt/tools",
-			getContents: () => `export const tools = {\n${tools.map(({ name, path }) => `  ${JSON.stringify(name)}: () => import(${JSON.stringify(path)}),`).join("\n")}\n}\n`
+			getContents: () => `export const tools = {\n${tools.map(({ name, path }) => `  ${JSON.stringify(name)}: () => import(${JSON.stringify(path)}),`).join("\n")}\n}\nexport const routeMethods = ${JSON.stringify(Object.fromEntries(routeTools.map(({ name, method }) => [name, method ?? null])))}\n`
 		});
 		if (tools.length > 0 && webmcp) {
 			addServerHandler({
@@ -217,10 +234,16 @@ var module_default = defineNuxtModule({
 				handler: resolver.resolve("./runtime/server/mcp-auth-server")
 			});
 		}
-		if (nuxt.options.dev && (webmcp || mcp)) nuxt.hook("builder:watch", async (event, path) => {
-			const file = relative(toolsDir, resolve(nuxt.options.srcDir, path));
-			if ((event === "add" || event === "unlink") && !file.startsWith("..")) await nuxt.callHook("restart");
-		});
+		if (nuxt.options.dev && (webmcp || mcp)) {
+			const routeToolPaths = new Set(routeTools.map((tool) => tool.path));
+			nuxt.hook("builder:watch", async (event, path) => {
+				const absolute = resolve(nuxt.options.srcDir, path);
+				const file = relative(toolsDir, absolute);
+				if ((event === "add" || event === "unlink") && !file.startsWith("..")) return nuxt.callHook("restart");
+				if (!routeDirs.some((dir) => !relative(dir, absolute).startsWith(".."))) return;
+				if ((event !== "unlink" && (await readFile(absolute, "utf8").catch(() => "")).includes("defineToolRoute(")) !== routeToolPaths.has(absolute)) await nuxt.callHook("restart");
+			});
+		}
 		if (nuxt.options.dev && nitroMajor >= 3) {
 			if (!hasPackage(nuxt.options.rootDir, "vue")) logger.warn("`vue` is not a dependency of this app, so `nuxt dev` fails with \"module is not defined\". Run `pnpm add vue`.");
 		}
@@ -298,12 +321,32 @@ var module_default = defineNuxtModule({
 				mode: "client"
 			});
 		}
+		const shapesDir = join(nuxt.options.serverDir, "api/shapes");
+		const shapeTypes = addTypeTemplate({
+			filename: "types/wervt-shapes.d.ts",
+			getContents: async () => shapeRoutesTypes(await findShapeRoutes(shapesDir), join(nuxt.options.buildDir, "types"), resolver.resolve("./runtime/shared/shape"))
+		});
+		if (nuxt.options.dev) nuxt.hook("builder:watch", async (event, path) => {
+			const file = relative(shapesDir, resolve(nuxt.options.srcDir, path));
+			if ((event === "add" || event === "unlink") && !file.startsWith("..")) await updateTemplates({ filter: (template) => template.filename === shapeTypes.filename });
+		});
+		else nuxt.hook("nitro:init", (instance) => {
+			const { serverDir } = instance.options.output;
+			instance.hooks.hook("compiled", async () => {
+				await mkdir(serverDir, { recursive: true });
+				await writeFile(join(serverDir, "wervt-shapes.json"), `${JSON.stringify(shapesManifest(await findShapeRoutes(shapesDir)), null, 2)}\n`);
+			});
+		});
 		nuxt.options.build.transpile.push(resolver.resolve("./runtime"));
 		addImports([
 			{
 				name: "useShape",
 				from: resolver.resolve("./runtime/app/useShape")
 			},
+			{
+				name: "preloadShape",
+				from: resolver.resolve("./runtime/app/useShape")
+			},
 			{
 				name: "useWervtUser",
 				from: resolver.resolve("./runtime/app/useWervtUser")

package/dist/provision.d.ts

@@ -26,8 +26,12 @@ export declare function appDatabaseUrl({ app, adminUrl, secret }: ProvisionOptio
  * 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.
+ *
+ * `fresh` is true when no migration had been applied before, so `nuxt dev` knows when to seed.
  */
-export declare function provisionDatabase(options: ProvisionOptions): Promise<void>;
+export declare function provisionDatabase(options: ProvisionOptions): Promise<{
+  fresh: boolean;
+}>;
 /** The role PgBouncer signs in with to look up app roles' password hashes (`auth_query`). */
 export declare const POOLER_ROLE = "pgbouncer";
 /**

package/dist/provision.js

@@ -37,6 +37,8 @@ async function appDatabaseUrl({ app, adminUrl, secret }) {
 * 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.
+*
+* `fresh` is true when no migration had been applied before, so `nuxt dev` knows when to seed.
 */
 async function provisionDatabase(options) {
 	const { app, adminUrl, secret, migrationsFolder } = options;
@@ -61,7 +63,15 @@ async function provisionDatabase(options) {
 		]) 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;
+		if (!migrationsFolder) return { fresh: false };
+		const table = `"${role}"."__drizzle_migrations"`;
+		const [state] = await admin`
+      select to_regclass(${table}) is not null as exists`;
+		let fresh = !state?.exists;
+		if (!fresh) {
+			const [row] = await admin.unsafe(`select exists(select 1 from ${table}) as applied`);
+			fresh = !row?.applied;
+		}
 		await admin.unsafe(`grant create on database "${database}" to "${role}"`);
 		const client = postgres(await appDatabaseUrl(options), {
 			max: 1,
@@ -76,6 +86,7 @@ async function provisionDatabase(options) {
 			await client.end();
 			await admin.unsafe(`revoke create on database "${database}" from "${role}"`);
 		}
+		return { fresh };
 	} finally {
 		await admin.end();
 	}

package/dist/route-tools.js

@@ -0,0 +1,44 @@
+import { readFile, readdir } from "node:fs/promises";
+import { extname, join, sep } from "node:path";
+//#region src/route-tools.ts
+const EXTENSIONS = /* @__PURE__ */ new Set([
+	".ts",
+	".js",
+	".mts",
+	".mjs"
+]);
+const METHOD_RE = /\.(get|post|put|patch|delete)$/;
+/** The name and method a route file gets as a tool, or undefined for files that aren't routes. */
+function routeToolName(file, prefix = []) {
+	const ext = extname(file);
+	if (!EXTENSIONS.has(ext) || file.endsWith(`.d${ext}`)) return void 0;
+	const parts = file.slice(0, -ext.length).split(sep).join("/").split("/");
+	let last = parts.pop();
+	const method = last.match(METHOD_RE)?.[1];
+	if (method) last = last.slice(0, -method.length - 1);
+	if (last !== "index") parts.push(last);
+	const segments = [...prefix, ...parts].map((segment) => segment.replace(/^\[(?:\.\.\.)?(.+)\]$/, "$1")).filter(Boolean);
+	if (method) segments.push(method);
+	return {
+		name: segments.join("."),
+		method
+	};
+}
+/** Route files under `dir` that call `defineToolRoute`. */
+async function findRouteTools(dir, prefix = []) {
+	const files = await readdir(dir, { recursive: true }).catch(() => []);
+	const found = [];
+	for (const file of files.toSorted((a, b) => a.localeCompare(b))) {
+		const route = routeToolName(file, prefix);
+		if (!route) continue;
+		const path = join(dir, file);
+		if (!(await readFile(path, "utf8")).includes("defineToolRoute(")) continue;
+		found.push({
+			...route,
+			path
+		});
+	}
+	return found;
+}
+//#endregion
+export { findRouteTools, routeToolName };

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

@@ -1,26 +1,47 @@
 import { Row } from "@electric-sql/client";
+import { Ref, ShallowRef } from "vue";
 //#region src/runtime/app/useShape.d.ts
+declare global {
+  /**
+   * Shape routes and their rows, generated from `server/api/shapes/` (`.nuxt/types/wervt-shapes.d.ts`).
+   */
+  interface WervtShapeRoutes {}
+}
 export interface UseShapeOptions {
   /** Payload key. Defaults to the path. */
   key?: string;
   /** Keep the shape live on the client. Defaults to true. */
   live?: boolean;
 }
+type ShapeResult<T> = Promise<ShapeRefs<T>> & ShapeRefs<T>;
+interface ShapeRefs<T> {
+  data: ShallowRef<T[]>;
+  error: Ref<unknown>;
+  isLive: Ref<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.
+ * fetched twice. Timestamps arrive as Dates, like Drizzle reads them.
+ *
+ * The row type comes from the route when it passes a Drizzle table to `proxyShape`.
+ *
+ * @example const { data: todos } = await useShape('/api/shapes/todos')
+ */
+export declare function useShape<P extends keyof WervtShapeRoutes>(path: P, options?: UseShapeOptions): ShapeResult<WervtShapeRoutes[P]>;
+export declare function useShape<T extends Row<unknown>>(path: string, options?: UseShapeOptions): ShapeResult<T>;
+/**
+ * Opens a shape ahead of time, e.g. when a link is hovered, so the page that uses it renders
+ * from rows that are already here instead of waiting for the snapshot. Resolves once the rows
+ * are up to date. Client only; on the server it does nothing.
  *
- * @example const { data: todos } = await useShape<Todo>('/api/shapes/todos')
+ * @example <NuxtLink to="/todos" @mouseenter="preloadShape('/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>;
-};
+export declare function preloadShape<P extends keyof WervtShapeRoutes>(path: P, options?: {
+  key?: string;
+}): Promise<void>;
+export declare function preloadShape(path: string, options?: {
+  key?: string;
+}): Promise<void>;
 //#endregion

package/dist/runtime/app/useShape.js

@@ -1,62 +1,123 @@
+import { shapeParser } from "../shared/shape.js";
 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 key = options.key ?? `wervt-shape:${path}`;
 	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 asyncData = useAsyncData(key, () => {
+		const live = import.meta.client ? shapes.get(key) : void 0;
+		return live?.stream ? live.settled.then(() => snapshotOf(live)) : loadSnapshot(path, fetchClient);
+	});
+	const shape = import.meta.client && options.live !== false ? acquire(key, path) : (import.meta.client ? shapes.get(key) : void 0) ?? createShape(path);
 	const result = {
-		data,
-		error,
-		isLive
+		data: shape.data,
+		error: shape.error,
+		isLive: shape.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);
+		if (!shape.stream && !shape.seeded) {
+			for (const [rowKey, row] of asyncData.data.value?.rows ?? []) shape.rows.set(rowKey, row);
+			shape.data.value = [...shape.rows.values()];
+			shape.offset = asyncData.data.value?.offset;
+			shape.handle = asyncData.data.value?.handle;
+			shape.seeded = true;
+		}
+		const error = asyncData.error.value ?? null;
+		if (error) {
+			shape.error.value = error;
+			console.error(`[wervt] useShape('${path}') failed:`, error);
+		}
 		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();
+			start(shape);
 		});
+		if (getCurrentScope()) onScopeDispose(() => release(key, shape, KEEP_AFTER_UNMOUNT_MS));
 	}
 	return Object.assign(ready, result);
 }
+function preloadShape(path, options = {}) {
+	if (!import.meta.client) return Promise.resolve();
+	const key = options.key ?? `wervt-shape:${path}`;
+	const shape = acquire(key, path);
+	start(shape);
+	return shape.settled.then(() => release(key, shape, KEEP_AFTER_PRELOAD_MS));
+}
+/** How long a shape keeps streaming once nothing uses it: a page change shouldn't reconnect. */
+const KEEP_AFTER_UNMOUNT_MS = 1e4;
+/** A preloaded shape waits a little longer for the navigation that uses it. */
+const KEEP_AFTER_PRELOAD_MS = 3e4;
+/** The shapes of this tab, one per key. Client only (see `useShape`). */
+const shapes = /* @__PURE__ */ new Map();
+function createShape(path) {
+	let settle = () => {};
+	const settled = new Promise((resolve) => settle = resolve);
+	return {
+		path,
+		rows: /* @__PURE__ */ new Map(),
+		data: shallowRef([]),
+		error: ref(null),
+		isLive: ref(false),
+		seeded: false,
+		settled,
+		settle,
+		users: 0
+	};
+}
+function acquire(key, path) {
+	let shape = shapes.get(key);
+	if (!shape) {
+		shape = createShape(path);
+		shapes.set(key, shape);
+	}
+	shape.users++;
+	clearTimeout(shape.releaseTimer);
+	return shape;
+}
+function release(key, shape, keepMs) {
+	shape.users--;
+	if (shape.users > 0) return;
+	clearTimeout(shape.releaseTimer);
+	shape.releaseTimer = setTimeout(() => {
+		if (shape.users > 0 || shapes.get(key) !== shape) return;
+		shape.controller?.abort();
+		shape.stream?.unsubscribeAll();
+		shapes.delete(key);
+	}, keepMs);
+}
+/** Starts the shape's one stream, if it isn't running yet. */
+function start(shape) {
+	if (shape.stream) return;
+	shape.controller = new AbortController();
+	const stream = new ShapeStream({
+		url: absolute(shape.path),
+		offset: shape.offset,
+		handle: shape.handle,
+		parser: shapeParser,
+		signal: shape.controller.signal,
+		onError: (e) => {
+			shape.error.value = e;
+			shape.settle();
+		}
+	});
+	shape.stream = stream;
+	stream.subscribe((messages) => {
+		if (applyMessages(shape.rows, messages)) shape.data.value = [...shape.rows.values()];
+		shape.isLive.value = stream.isUpToDate;
+		if (stream.isUpToDate) shape.settle();
+	});
+}
+function snapshotOf(shape) {
+	return {
+		rows: [...shape.rows],
+		offset: shape.stream?.lastOffset ?? shape.offset ?? "-1",
+		handle: shape.stream?.shapeHandle ?? shape.handle
+	};
+}
 async function loadSnapshot(path, fetchClient) {
 	const rows = /* @__PURE__ */ new Map();
 	let fail = () => {};
@@ -64,6 +125,7 @@ async function loadSnapshot(path, fetchClient) {
 		url: absolute(path),
 		subscribe: false,
 		fetchClient,
+		parser: shapeParser,
 		onError: (e) => fail(e)
 	});
 	await new Promise((resolve, reject) => {
@@ -137,4 +199,4 @@ function absolute(path) {
 	return new URL(path, import.meta.client ? location.origin : "http://localhost").href;
 }
 //#endregion
-export { useShape };
+export { preloadShape, useShape };