@wervt/nuxt 0.2.15 → 0.3.0

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/shape.d.ts

@@ -1,19 +1,26 @@
+import { ShapeResponse } from "../shared/shape.js";
 import { RequestEvent } from "nuxt/server";
+import { InferSelectModel, Table } from "drizzle-orm";
 //#region src/runtime/server/shape.d.ts
-export interface ShapeOptions {
-  /** Table name without schema. */
-  table: string;
+export interface ShapeOptions<T extends Table | string = Table | string> {
+  /**
+   * The Drizzle table (`todos` from `server/db/schema`), or its name without schema. With the
+   * table, `useShape` knows the row type from the route.
+   */
+  table: T;
   /** 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[];
+  columns?: (T extends Table ? keyof InferSelectModel<T> & string : string)[];
 }
+/** The rows a shape of `T` streams: the table's select model, or untyped for a table name. */
+export type ShapeRow<T extends Table | string> = T extends Table ? InferSelectModel<T> : Record<string, unknown>;
 /**
  * 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>;
+export declare function proxyShape<T extends Table | string>(event: RequestEvent, { table: tableOrName, where, params, columns }: ShapeOptions<T>): Promise<ShapeResponse<ShapeRow<T>>>;
 //#endregion

package/dist/runtime/server/shape.js

@@ -1,3 +1,4 @@
+import { getTableName, isTable } from "drizzle-orm";
 //#region src/runtime/server/shape.ts
 const CLIENT_PARAMS = [
 	"offset",
@@ -14,7 +15,8 @@ const CLIENT_PARAMS = [
 * 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 }) {
+async function proxyShape(event, { table: tableOrName, where, params, columns }) {
+	const table = isTable(tableOrName) ? getTableName(tableOrName) : tableOrName;
 	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;

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/runtime/shared/shape.d.ts

@@ -0,0 +1,18 @@
+//#region src/runtime/shared/shape.d.ts
+declare const shapeRow: unique symbol;
+export type ShapeResponse<Row> = Response & {
+  readonly [shapeRow]?: Row;
+};
+/** The row type of a shape route's handler, `never` if it doesn't serve a typed shape. */
+export type ShapeRowOf<Handler> = Handler extends ((...args: never[]) => infer Result) ? Awaited<Result> extends ShapeResponse<infer Row> ? Row : never : never;
+/**
+ * Postgres text of a `timestamp`/`timestamptz` as a Date, like Drizzle's default `mode: 'date'`
+ * reads it. Drizzle stores `timestamp` without time zone as UTC, so it's read as UTC too.
+ */
+export declare function parseTimestamp(value: string): Date;
+/** Electric parsers for the types Drizzle reads differently from Electric's defaults. */
+export declare const shapeParser: {
+  timestamp: typeof parseTimestamp;
+  timestamptz: typeof parseTimestamp;
+};
+//#endregion

package/dist/runtime/shared/shape.js

@@ -0,0 +1,16 @@
+//#region src/runtime/shared/shape.ts
+/**
+* Postgres text of a `timestamp`/`timestamptz` as a Date, like Drizzle's default `mode: 'date'`
+* reads it. Drizzle stores `timestamp` without time zone as UTC, so it's read as UTC too.
+*/
+function parseTimestamp(value) {
+	const iso = value.replace(" ", "T").replace(/([+-]\d{2})$/, "$1:00");
+	return new Date(/(Z|[+-]\d{2}:\d{2})$/.test(iso) ? iso : `${iso}Z`);
+}
+/** Electric parsers for the types Drizzle reads differently from Electric's defaults. */
+const shapeParser = {
+	timestamp: parseTimestamp,
+	timestamptz: parseTimestamp
+};
+//#endregion
+export { parseTimestamp, shapeParser };

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

@@ -0,0 +1,70 @@
+import { readdir } from "node:fs/promises";
+import { extname, join, relative, sep } from "node:path";
+//#region src/shapes.ts
+const ROUTE_EXTENSIONS = /* @__PURE__ */ new Set([
+	".ts",
+	".mts",
+	".js",
+	".mjs"
+]);
+/** The GET routes among `files` (relative to `server/api/shapes`), as Nitro would serve them. */
+function shapeRoutes(files, base = "/api/shapes") {
+	const routes = [];
+	for (const file of files.toSorted((a, b) => a.localeCompare(b))) {
+		const ext = extname(file);
+		if (!ROUTE_EXTENSIONS.has(ext) || file.endsWith(`.d${ext}`)) continue;
+		const parts = file.slice(0, -ext.length).split(sep).join("/").split("/");
+		const last = parts.pop();
+		const method = last.match(/\.(get|post|put|patch|delete|head|options)$/)?.[1];
+		if (method && method !== "get") continue;
+		const name = method ? last.slice(0, -method.length - 1) : last;
+		if (name !== "index") parts.push(name);
+		let dynamic = false;
+		const segments = parts.map((segment) => {
+			if (!/^\[.+\]$/.test(segment)) return segment;
+			dynamic = true;
+			return "${string}";
+		});
+		routes.push({
+			route: [base, ...segments].join("/"),
+			dynamic,
+			file
+		});
+	}
+	return routes;
+}
+async function findShapeRoutes(dir) {
+	return shapeRoutes(await readdir(dir, { recursive: true }).catch(() => [])).map((entry) => ({
+		...entry,
+		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) => {
+		const path = relative(typesDir, file).split(sep).join("/");
+		const ext = extname(path);
+		const withoutExt = ext ? path.slice(0, -ext.length) : path;
+		return withoutExt.startsWith(".") ? withoutExt : `./${withoutExt}`;
+	};
+	const entries = routes.map(({ route, dynamic, file }) => {
+		return `    ${dynamic ? `[path: \`${route}\`]` : JSON.stringify(route)}: ShapeRowOf<typeof import(${JSON.stringify(importPath(file))}).default>`;
+	});
+	return [
+		`import type { ShapeRowOf } from ${JSON.stringify(importPath(shapeTypes))}`,
+		"",
+		"declare global {",
+		"  interface WervtShapeRoutes {",
+		...entries,
+		"  }",
+		"}",
+		"",
+		"export {}",
+		""
+	].join("\n");
+}
+//#endregion
+export { findShapeRoutes, shapeRoutes, shapeRoutesTypes, shapesManifest };

package/package.json

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