@wervt/nuxt 0.2.16 → 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,7 @@
+import { SEED_TASK, unscheduleSeed } from "./seed.js";
 import { resolveAppName, setupDev } from "./dev.js";
-import { findShapeRoutes, shapeRoutesTypes } from "./shapes.js";
+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";
@@ -129,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/**",
@@ -166,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({
@@ -218,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`.");
 		}
@@ -308,12 +330,23 @@ var module_default = defineNuxtModule({
 			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

@@ -31,4 +31,17 @@ interface ShapeRefs<T> {
  */
 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 <NuxtLink to="/todos" @mouseenter="preloadShape('/api/shapes/todos')">
+ */
+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

@@ -4,53 +4,120 @@ import { getCurrentScope, onScopeDispose, ref, shallowRef } from "vue";
 import { onNuxtReady, useAsyncData, useRequestEvent, useRequestFetch } from "#app";
 //#region src/runtime/app/useShape.ts
 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,
-				parser: shapeParser,
-				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 = () => {};
@@ -132,4 +199,4 @@ function absolute(path) {
 	return new URL(path, import.meta.client ? location.origin : "http://localhost").href;
 }
 //#endregion
-export { useShape };
+export { preloadShape, useShape };

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

@@ -3,8 +3,8 @@ declare const _default: import("nuxt/server").EventHandler<{
   error: string;
   ok?: undefined;
 } | {
-  ok: boolean;
   error?: undefined;
+  ok: boolean;
 }>;
 //#endregion
 export { _default as default };

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

@@ -4,10 +4,11 @@ import { useDb } from "./db.js";
 import { createEvlogError, log, useLogger } from "./logger.js";
 import { SendMailOptions, sendMail } from "./mail.js";
 import { McpTokenContext } from "./mcp-auth.js";
+import { seedTable } from "./seed.js";
 import { ShapeResponse } from "../shared/shape.js";
 import { ShapeOptions, ShapeRow, proxyShape } from "./shape.js";
 import { Task, TaskEvent, TaskResult, defineTask } from "./tasks.js";
 import { SafeResult, useSafeValidatedBody, useSafeValidatedParams, useSafeValidatedQuery, useValidatedBody, useValidatedParams, useValidatedQuery, vh } from "./validate.js";
-import { Tool, defineTool } from "./tools.js";
+import { Tool, ToolRoute, defineTool, defineToolRoute } from "./tools.js";
 import { useWervtUser } from "./user.js";
-export { type EmailProps, type McpTokenContext, type RenderedEmail, type SafeResult, type SendMailOptions, type ShapeOptions, type ShapeResponse, type ShapeRow, type Task, type TaskEvent, type TaskResult, type Tool, type WervtUser, createEvlogError, defineTask, defineTool, log, proxyShape, renderEmail, sendMail, useDb, useLogger, useSafeValidatedBody, useSafeValidatedParams, useSafeValidatedQuery, useValidatedBody, useValidatedParams, useValidatedQuery, useWervtUser, vh };
+export { type EmailProps, type McpTokenContext, type RenderedEmail, type SafeResult, type SendMailOptions, type ShapeOptions, type ShapeResponse, type ShapeRow, type Task, type TaskEvent, type TaskResult, type Tool, type ToolRoute, type WervtUser, createEvlogError, defineTask, defineTool, defineToolRoute, log, proxyShape, renderEmail, seedTable, sendMail, useDb, useLogger, useSafeValidatedBody, useSafeValidatedParams, useSafeValidatedQuery, useValidatedBody, useValidatedParams, useValidatedQuery, useWervtUser, vh };

package/dist/runtime/server/index.js

@@ -2,9 +2,10 @@ import { renderEmail } from "../email/render.js";
 import { useDb } from "./db.js";
 import { createEvlogError, log, useLogger } from "./logger.js";
 import { sendMail } from "./mail.js";
+import { seedTable } from "./seed.js";
 import { proxyShape } from "./shape.js";
 import { defineTask } from "./tasks.js";
-import { defineTool } from "./tools.js";
-import { useWervtUser } from "./user.js";
 import { useSafeValidatedBody, useSafeValidatedParams, useSafeValidatedQuery, useValidatedBody, useValidatedParams, useValidatedQuery, vh } from "./validate.js";
-export { createEvlogError, defineTask, defineTool, log, proxyShape, renderEmail, sendMail, useDb, useLogger, useSafeValidatedBody, useSafeValidatedParams, useSafeValidatedQuery, useValidatedBody, useValidatedParams, useValidatedQuery, useWervtUser, vh };
+import { defineTool, defineToolRoute } from "./tools.js";
+import { useWervtUser } from "./user.js";
+export { createEvlogError, defineTask, defineTool, defineToolRoute, log, proxyShape, renderEmail, seedTable, sendMail, useDb, useLogger, useSafeValidatedBody, useSafeValidatedParams, useSafeValidatedQuery, useValidatedBody, useValidatedParams, useValidatedQuery, useWervtUser, vh };

package/dist/runtime/server/mcp.js

@@ -2,10 +2,9 @@ import { devUser } from "../shared/user.js";
 import { useLogger } from "./logger.js";
 import { safeValidate } from "./validate.js";
 import { authenticateMcp, mcpEndpoint, setMcpUser } from "./mcp-auth.js";
-import { loadTool, toolInputSchema } from "./tool-handlers.js";
+import { allTools, toolInputSchema } from "./tool-handlers.js";
 import { defineEventHandler } from "nuxt/server";
 import { server } from "#wervt/mcp";
-import { tools } from "#wervt/tools";
 import { defineMcpHandler } from "h3-mcp";
 //#region src/runtime/server/mcp.ts
 const MAX_BODY = 4194304;
@@ -56,10 +55,7 @@ function toMcpTool(name, tool) {
 }
 let handler;
 async function createHandler() {
-	const definitions = (await Promise.all(Object.keys(tools).map(async (name) => {
-		const tool = await loadTool(name);
-		return tool ? toMcpTool(name, tool) : void 0;
-	}))).filter((tool) => tool !== void 0);
+	const definitions = [...await allTools()].map(([name, tool]) => toMcpTool(name, tool));
 	return defineMcpHandler((event) => ({
 		...server,
 		tools: definitions,

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

@@ -0,0 +1,18 @@
+import { InferInsertModel } from "drizzle-orm";
+import { PgTable } from "drizzle-orm/pg-core";
+//#region src/runtime/server/seed.d.ts
+/**
+ * Inserts `rows` into `table` only while it is empty, so a seed task can run again without
+ * duplicating data or touching what users created. Returns how many rows it inserted.
+ *
+ * @example
+ * // server/tasks/db/seed.ts
+ * export default defineTask({
+ *   meta: { description: 'Fill an empty database with example data' },
+ *   async run() {
+ *     return { result: { todos: await seedTable(todos, [{ title: 'Try wervt' }]) } }
+ *   },
+ * })
+ */
+export declare function seedTable<T extends PgTable>(table: T, rows: InferInsertModel<T>[]): Promise<number>;
+//#endregion

package/dist/runtime/server/seed.js

@@ -0,0 +1,27 @@
+import { useDb } from "./db.js";
+import { sql } from "drizzle-orm";
+//#region src/runtime/server/seed.ts
+/**
+* Inserts `rows` into `table` only while it is empty, so a seed task can run again without
+* duplicating data or touching what users created. Returns how many rows it inserted.
+*
+* @example
+* // server/tasks/db/seed.ts
+* export default defineTask({
+*   meta: { description: 'Fill an empty database with example data' },
+*   async run() {
+*     return { result: { todos: await seedTable(todos, [{ title: 'Try wervt' }]) } }
+*   },
+* })
+*/
+async function seedTable(table, rows) {
+	if (rows.length === 0) return 0;
+	const db = useDb();
+	const target = table;
+	const [existing] = await db.select({ one: sql`1` }).from(target).limit(1);
+	if (existing) return 0;
+	await db.insert(target).values(rows);
+	return rows.length;
+}
+//#endregion
+export { seedTable };

package/dist/runtime/server/tool-handlers.d.ts

@@ -1,6 +1,11 @@
 import { Input } from "./validate.js";
 import { Tool } from "./tools.js";
 //#region src/runtime/server/tool-handlers.d.ts
+/**
+ * Every tool by the name agents see. A tool may rename itself (`name`), so the file-derived
+ * keys of `#wervt/tools` are only a default and the whole list is loaded once.
+ */
+export declare function allTools(): Promise<Map<string, Tool<Input | undefined, unknown>>>;
 export declare function loadTool(name: string): Promise<Tool<Input | undefined, unknown> | undefined>;
 export declare function toolInputSchema(tool: Tool): import("@valibot/to-json-schema").JsonSchema | {
   type: string;

package/dist/runtime/server/tool-handlers.js

@@ -1,11 +1,39 @@
 import { useLogger } from "./logger.js";
 import { safeValidate, toSchema } from "./validate.js";
+import { TOOL_ROUTE } from "./tools.js";
 import { defineEventHandler } from "nuxt/server";
-import { tools } from "#wervt/tools";
 import { toJsonSchema } from "@valibot/to-json-schema";
+import { routeMethods, tools } from "#wervt/tools";
 //#region src/runtime/server/tool-handlers.ts
+let index;
+/**
+* Every tool by the name agents see. A tool may rename itself (`name`), so the file-derived
+* keys of `#wervt/tools` are only a default and the whole list is loaded once.
+*/
+function allTools() {
+	index ??= (async () => {
+		const byName = /* @__PURE__ */ new Map();
+		for (const [key, load] of Object.entries(tools)) {
+			const exported = (await load())?.default;
+			const tool = exported?.[TOOL_ROUTE] ?? exported;
+			if (!tool) continue;
+			const method = Object.hasOwn(routeMethods, key) ? routeMethods[key] : void 0;
+			const name = tool.name ?? key;
+			if (byName.has(name)) console.warn(`[wervt] Two tools are named ${name}; the last one wins.`);
+			byName.set(name, method ? {
+				...tool,
+				readOnly: tool.readOnly ?? method === "get"
+			} : tool);
+		}
+		return byName;
+	})().catch((error) => {
+		index = void 0;
+		throw error;
+	});
+	return index;
+}
 async function loadTool(name) {
-	return (await (Object.hasOwn(tools, name) ? tools[name] : void 0)?.())?.default;
+	return (await allTools()).get(name);
 }
 function toolInputSchema(tool) {
 	if (!tool.input) return {
@@ -22,16 +50,12 @@ function toolInputSchema(tool) {
 /** `GET /_wervt/tools`: name, description and JSON Schema of each tool, for the client plugin. */
 const listTools = defineEventHandler(async (event) => {
 	event.res.headers.set("cache-control", "no-store");
-	return (await Promise.all(Object.keys(tools).map(async (name) => {
-		const tool = await loadTool(name);
-		if (!tool) return void 0;
-		return {
-			name,
-			description: tool.description,
-			inputSchema: toolInputSchema(tool),
-			readOnly: tool.readOnly === true
-		};
-	}))).filter((tool) => tool !== void 0);
+	return [...await allTools()].map(([name, tool]) => ({
+		name,
+		description: tool.description,
+		inputSchema: toolInputSchema(tool),
+		readOnly: tool.readOnly === true
+	}));
 });
 function crossSite(event) {
 	const site = event.req.headers.get("sec-fetch-site");
@@ -67,4 +91,4 @@ const runTool = defineEventHandler(async (event) => {
 	return { result: await tool.handler(event, input) ?? null };
 });
 //#endregion
-export { listTools, loadTool, runTool, toolInputSchema };
+export { allTools, listTools, loadTool, runTool, toolInputSchema };

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

@@ -2,6 +2,8 @@ import { Input, Output } from "./validate.js";
 import { RequestEvent } from "nuxt/server";
 //#region src/runtime/server/tools.d.ts
 export interface Tool<I extends Input | undefined = Input | undefined, R = unknown> {
+  /** Overrides the name from the file path. Agents see it, so keep it short and stable. */
+  name?: string;
   /** What the tool does and when an agent should call it. Agents read this to pick a tool. */
   description: string;
   /** valibot schema or `{ key: schema }` shape of the arguments. Omit it for no arguments. */
@@ -12,4 +14,38 @@ export interface Tool<I extends Input | undefined = Input | undefined, R = unkno
 }
 /** A tool in `server/tools/` (`server/tools/todos/add.ts` is `todos.add`). */
 export declare function defineTool<R, I extends Input | undefined = undefined>(tool: Tool<I, R>): Tool<I, R>;
+type Values<T extends Input | undefined> = T extends Input ? Output<T> : {};
+export interface ToolRoute<P extends Input | undefined, I extends Input | undefined, R> {
+  /** How agents see the route. `readOnly` defaults to true for GET routes. */
+  tool: {
+    name?: string;
+    description: string;
+    readOnly?: boolean;
+  };
+  /** Route params like `[id]` (strings on the route; use `vh.*` to coerce). */
+  params?: P;
+  /** The body, or the query for GET routes. */
+  input?: I;
+  /** Gets params and input merged, from the request or from an agent's arguments. */
+  handler(event: RequestEvent, input: Values<P> & Values<I>): R | Promise<R>;
+}
+/** Where `defineToolRoute` keeps the tool on the event handler, for the module's tool list. */
+export declare const TOOL_ROUTE: unique symbol;
+/**
+ * An API route that agents can call as a tool too, over WebMCP and `/mcp`: no separate file in
+ * `server/tools/` repeating the route's logic and validation.
+ *
+ * ```ts
+ * // server/api/todos/[id].patch.ts
+ * export default defineToolRoute({
+ *   tool: { name: 'todos.update', description: 'Mark a todo done or not done.' },
+ *   params: { id: vh.id },
+ *   input: { done: v.boolean() },
+ *   handler: (event, { id, done }) => …,
+ * })
+ * ```
+ */
+export declare function defineToolRoute<R, P extends Input | undefined = undefined, I extends Input | undefined = undefined>(route: ToolRoute<P, I, R>): import("nuxt/server").EventHandler<Promise<R>> & {
+  [TOOL_ROUTE]: Tool<Input | undefined, unknown>;
+};
 //#endregion

package/dist/runtime/server/tools.js

@@ -1,7 +1,59 @@
+import { validate } from "./validate.js";
+import { defineEventHandler, getQuery, getRouterParams, readBody } from "nuxt/server";
+import * as v from "valibot";
 //#region src/runtime/server/tools.ts
 /** A tool in `server/tools/` (`server/tools/todos/add.ts` is `todos.add`). */
 function defineTool(tool) {
 	return tool;
 }
+/** Where `defineToolRoute` keeps the tool on the event handler, for the module's tool list. */
+const TOOL_ROUTE = Symbol.for("wervt.toolRoute");
+/**
+* An API route that agents can call as a tool too, over WebMCP and `/mcp`: no separate file in
+* `server/tools/` repeating the route's logic and validation.
+*
+* ```ts
+* // server/api/todos/[id].patch.ts
+* export default defineToolRoute({
+*   tool: { name: 'todos.update', description: 'Mark a todo done or not done.' },
+*   params: { id: vh.id },
+*   input: { done: v.boolean() },
+*   handler: (event, { id, done }) => …,
+* })
+* ```
+*/
+function defineToolRoute(route) {
+	const handler = defineEventHandler(async (event) => {
+		const params = route.params ? await validate(route.params, getRouterParams(event, { decode: true })) : {};
+		const reads = event.req.method === "GET" || event.req.method === "HEAD";
+		const input = route.input ? await validate(route.input, reads ? getQuery(event) : await readBody(event) ?? {}) : {};
+		return route.handler(event, {
+			...params,
+			...input
+		});
+	});
+	const tool = {
+		name: route.tool.name,
+		description: route.tool.description,
+		readOnly: route.tool.readOnly,
+		input: toolInput(route.params, route.input),
+		handler: (event, input) => route.handler(event, input ?? {})
+	};
+	return Object.assign(handler, { [TOOL_ROUTE]: tool });
+}
+/** An agent sends params and input as one object, so the tool's schema is both merged. */
+function toolInput(params, input) {
+	if (!params) return input;
+	if (!input) return params;
+	return v.objectAsync({
+		...entries(params),
+		...entries(input)
+	});
+}
+function entries(input) {
+	if (!("kind" in input && input.kind === "schema")) return input;
+	if ("entries" in input) return input.entries;
+	throw new Error("defineToolRoute: `params` and `input` must be objects to merge into a tool.");
+}
 //#endregion
-export { defineTool };
+export { TOOL_ROUTE, defineTool, defineToolRoute };

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

@@ -16,6 +16,7 @@ export type SafeResult<T extends Input> = {
 };
 export declare function toSchema(input: Input): Schema;
 export declare function safeValidate<T extends Input>(input: T, data: unknown): Promise<SafeResult<T>>;
+export declare function validate<T extends Input>(input: T, data: unknown): Promise<Output<T>>;
 /** 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. */

package/dist/runtime/server/validate.js

@@ -48,4 +48,4 @@ const vh = {
 	id: v.pipe(v.string(), v.digits(), v.transform(Number), v.safeInteger(), v.minValue(1))
 };
 //#endregion
-export { safeValidate, toSchema, useSafeValidatedBody, useSafeValidatedParams, useSafeValidatedQuery, useValidatedBody, useValidatedParams, useValidatedQuery, vh };
+export { safeValidate, toSchema, useSafeValidatedBody, useSafeValidatedParams, useSafeValidatedQuery, useValidatedBody, useValidatedParams, useValidatedQuery, validate, vh };

package/dist/seed.js

@@ -0,0 +1,52 @@
+//#region src/seed.ts
+/** The conventional seed task: `server/tasks/db/seed.ts`. */
+const SEED_TASK = "db:seed";
+/**
+* `nitro.scheduledTasks` without the seed task, and the crons it was listed under. Seeding fills
+* an empty database on request; on a schedule it would run against production data.
+*/
+function unscheduleSeed(schedules) {
+	const kept = {};
+	const removed = [];
+	for (const [cron, entry] of Object.entries(schedules)) {
+		const tasks = [entry].flat();
+		const rest = tasks.filter((task) => task !== SEED_TASK);
+		if (rest.length < tasks.length) removed.push(cron);
+		if (rest.length > 0) kept[cron] = Array.isArray(entry) ? rest : rest[0];
+	}
+	return {
+		schedules: kept,
+		removed
+	};
+}
+/**
+* Runs `db:seed` through the Nitro dev server's task route, once the server answers. The dev
+* server is still building when it starts listening, so its task list is polled first; that
+* also tells whether the app has a seed task at all.
+*/
+async function runDevSeed(baseUrl, { fetch: request = fetch, timeout = 12e4, interval = 500 } = {}) {
+	const base = baseUrl.replace(/\/+$/, "");
+	const deadline = Date.now() + timeout;
+	let tasks;
+	while (!tasks) {
+		const response = await request(`${base}/_nitro/tasks`).catch(() => void 0);
+		const body = response?.ok ? await response.json().catch(() => void 0) : void 0;
+		if (body && typeof body === "object" && "tasks" in body) tasks = body.tasks;
+		else if (Date.now() >= deadline) throw new Error("the dev server did not answer in time");
+		else await new Promise((resolve) => setTimeout(resolve, interval));
+	}
+	if (!("db:seed" in tasks)) return { status: "missing" };
+	const response = await request(`${base}/_nitro/tasks/${SEED_TASK}`, {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify({ payload: {} })
+	});
+	const body = await response.json().catch(() => ({}));
+	if (!response.ok) throw new Error(body.message ?? `${response.status} ${response.statusText}`);
+	return {
+		status: "seeded",
+		result: body.result
+	};
+}
+//#endregion
+export { SEED_TASK, runDevSeed, unscheduleSeed };

package/dist/shapes.js

@@ -39,6 +39,9 @@ async function findShapeRoutes(dir) {
 		file: join(dir, entry.file)
 	}));
 }
+function shapesManifest(routes) {
+	return { shapes: routes.filter((route) => !route.dynamic).map((route) => route.route) };
+}
 /** The `.d.ts` declaring `WervtShapeRoutes`; paths are made relative to `typesDir`. */
 function shapeRoutesTypes(routes, typesDir, shapeTypes) {
 	const importPath = (file) => {
@@ -64,4 +67,4 @@ function shapeRoutesTypes(routes, typesDir, shapeTypes) {
 	].join("\n");
 }
 //#endregion
-export { findShapeRoutes, shapeRoutes, shapeRoutesTypes };
+export { findShapeRoutes, shapeRoutes, shapeRoutesTypes, shapesManifest };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wervt/nuxt",
-  "version": "0.2.16",
+  "version": "0.3.0",
   "description": "Nuxt module for apps hosted on wervt: database, live data, MCP and runtime setup.",
   "keywords": [
     "drizzle",