create-wervt 0.2.9 → 0.2.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "create-wervt",
3
- "version": "0.2.9",
3
+ "version": "0.2.11",
4
4
  "description": "Create a new wervt app: Nuxt 5, Postgres with Drizzle, live data with Electric.",
5
5
  "homepage": "https://wervt.app",
6
6
  "license": "MIT",
@@ -8,7 +8,9 @@ Supabase Edge Runtime) with its own Postgres schema and live data through Electr
8
8
 
9
9
  - `app.vue`, `pages/`, `components/`: the Vue app.
10
10
  - `server/api/`: API routes. `server/api/shapes/`: live data routes.
11
- - `server/tools/`: tools that browser agents can call on the page (WebMCP).
11
+ - `server/tools/`: tools that AI agents can call: in the browser (WebMCP) and at `/mcp` (MCP).
12
+ API routes become tools with `defineToolRoute`.
13
+ - `server/tasks/`: tasks (cron and one-off jobs). `server/tasks/db/seed.ts`: example data.
12
14
  - `server/db/schema.ts`: the Drizzle schema. `drizzle/`: generated migrations. Commit both.
13
15
 
14
16
  ## UI
@@ -77,6 +79,18 @@ const rows = await useDb().select().from(todos).where(eq(todos.done, false))
77
79
  `defineRelations` in `server/db/relations.ts` and use `useDb({ relations })`.
78
80
  - No raw SQL against other schemas, `public`, or system catalogs: the role can't access them.
79
81
 
82
+ ### Seeding
83
+
84
+ Example and fixture data goes into the `db:seed` task in `server/tasks/db/seed.ts`, not into
85
+ migrations. Keep it idempotent: `seedTable(table, rows)` from `@wervt/nuxt/server` only inserts
86
+ while the table is empty.
87
+
88
+ - `nuxt dev` runs it once, right after it created and migrated a new local database.
89
+ `pnpm exec nuxt task run db:seed` runs it again while the dev server is running.
90
+ - It's never scheduled and never runs on deploy. Seed production only when asked:
91
+ `pnpm exec wervt tasks <app> --run db:seed`.
92
+ - Update the seed when the schema changes, so a new database still seeds.
93
+
80
94
  ## Live data
81
95
 
82
96
  Prefer live data over refetching. A shape is one table, optionally filtered:
@@ -85,13 +99,15 @@ Prefer live data over refetching. A shape is one table, optionally filtered:
85
99
  // server/api/shapes/todos.get.ts
86
100
  import { proxyShape } from '@wervt/nuxt/server'
87
101
  import { defineEventHandler } from 'nuxt/server'
102
+ import { todos } from '../../db/schema'
88
103
 
89
- export default defineEventHandler((event) => proxyShape(event, { table: 'todos' }))
104
+ export default defineEventHandler((event) => proxyShape(event, { table: todos }))
90
105
  ```
91
106
 
92
107
  ```vue
93
108
  <script setup lang="ts">
94
- const { data: todos, isLive } = await useShape<Todo>('/api/shapes/todos')
109
+ // Typed from the route: rows are `typeof todos.$inferSelect`, no type argument needed.
110
+ const { data: todos, isLive } = await useShape('/api/shapes/todos')
95
111
  </script>
96
112
  ```
97
113
 
@@ -99,14 +115,19 @@ const { data: todos, isLive } = await useShape<Todo>('/api/shapes/todos')
99
115
  any API route show up in every open tab without refetching.
100
116
  - Writes go through normal API routes (`$fetch('/api/todos', { method: 'POST', body })`).
101
117
  - Shapes can't join. Load several shapes and combine them with `computed`.
102
- - Shape rows are JSON: timestamps arrive as Postgres text (`2026-10-06 01:02:03.123+00`), not
103
- `Date`. Column names are what the client sees, so keep them camelCase like the schema keys.
118
+ - `useShape` calls with the same path share one connection and the same refs, so use it freely in
119
+ several components. `preloadShape(path)` on a link's `@mouseenter` makes the next page instant.
120
+ - Pass the Drizzle table (not its name) to `proxyShape`: `useShape` then knows the row type for
121
+ every route in `server/api/shapes/`. Timestamps arrive as `Date`, like Drizzle reads them; keep
122
+ `timestamp()` in its default mode. `bigint` columns arrive as `BigInt` (use `mode: 'bigint'`).
123
+ - Column names are what the client sees, so keep them camelCase like the schema keys (no
124
+ snake_case `casing`).
104
125
  - Never put secrets in a shape: list the `columns` a client may see.
105
126
  - Do auth checks in the shape route and restrict rows with `where`. Pass values as `params`,
106
127
  never by building the SQL string:
107
128
 
108
129
  ```ts
109
- proxyShape(event, { table: 'notes', where: '"ownerId" = $1', params: [userId] })
130
+ proxyShape(event, { table: notes, where: '"ownerId" = $1', params: [userId] })
110
131
  ```
111
132
 
112
133
  ## New releases
@@ -174,37 +195,78 @@ wervt: { timezone: 'Europe/Berlin' }, // optional, UTC by default
174
195
  `pnpm exec wervt tasks <app> --run <name>`), e.g. for a backfill.
175
196
  - Every run is logged: `pnpm exec wervt logs <app> 'type:=Task'`.
176
197
 
177
- ## Browser agents (WebMCP)
198
+ ## Feedback
199
+
200
+ `wervt: { feedback: { key: 'pk_…' } }` adds kontor's feedback button: reports go into a kontor
201
+ project's triage with page, browser and release. The key comes from the kontor project
202
+ (Settings → Intake keys) and is public. `useWervtFeedback().open()` opens it from your own
203
+ button (`position: 'none'` hides the floating one), `.setContext({ … })` adds context.
204
+
205
+ ## AI agents (WebMCP and MCP)
178
206
 
179
- Tools in `server/tools/` let an agent in the visitor's browser use the app on their behalf
180
- (through WebMCP, `document.modelContext`). Give the app a tool for each thing a user would ask an
181
- agent to do in it: list, add, change.
207
+ Tools let agents use the app on a user's behalf: an agent in the visitor's browser (WebMCP,
208
+ `document.modelContext`), and AI clients like Claude Code or Cursor through the app's MCP endpoint
209
+ at `/mcp`, after the user signed in with wervt. Give the app a tool for each thing a user would ask
210
+ an agent to do in it: list, add, change.
211
+
212
+ When an API route already does it, make the route the tool with `defineToolRoute` instead of
213
+ writing the logic twice:
182
214
 
183
215
  ```ts
184
- // server/tools/add-todo.ts → tool "add-todo" (server/tools/todos/add.ts is "todos.add")
185
- import { defineTool, useDb } from '@wervt/nuxt/server'
216
+ // server/api/todos/[id].patch.ts: the route and the tool "update-todo"
217
+ import { defineToolRoute, useDb, vh } from '@wervt/nuxt/server'
218
+ import { eq } from 'drizzle-orm'
219
+ import { createError } from 'nuxt/server'
186
220
  import * as v from 'valibot'
221
+ import { todos } from '../../db/schema'
222
+
223
+ export default defineToolRoute({
224
+ tool: { name: 'update-todo', description: 'Mark a todo done or not done. Ids from list-todos.' },
225
+ params: { id: vh.id },
226
+ input: { done: v.boolean() },
227
+ async handler(event, { id, done }) {
228
+ const [todo] = await useDb().update(todos).set({ done }).where(eq(todos.id, id)).returning()
229
+ if (!todo) throw createError({ status: 404, message: `No todo with id ${id}` })
230
+ return todo
231
+ },
232
+ })
233
+ ```
234
+
235
+ - `params` are the route's `[params]` (strings, so `vh.*`), `input` the body (the query for GET
236
+ routes). The handler gets both merged; an agent sends them as one JSON object. Both must be
237
+ `{ key: schema }` objects (or `v.object`).
238
+ - `tool.name` is what agents see (default: from the path, `todos.id.patch`). GET routes are
239
+ `readOnly` by default.
240
+ - For tools without a route, put a file in `server/tools/` (`server/tools/list-todos.ts` is the
241
+ tool "list-todos"):
242
+
243
+ ```ts
244
+ import { defineTool, useDb } from '@wervt/nuxt/server'
245
+ import { desc } from 'drizzle-orm'
187
246
  import { todos } from '../db/schema'
188
247
 
189
248
  export default defineTool({
190
- description: 'Add a todo. Returns the new todo.',
191
- input: { title: v.pipe(v.string(), v.trim(), v.nonEmpty(), v.maxLength(200)) },
192
- async handler(event, input) {
193
- const [todo] = await useDb().insert(todos).values(input).returning()
194
- return todo
195
- },
249
+ description: 'List all todos, newest first, with their id, title and whether they are done.',
250
+ readOnly: true,
251
+ handler: () => useDb().select().from(todos).orderBy(desc(todos.createdAt)),
196
252
  })
197
253
  ```
198
254
 
199
255
  - The agent picks tools by their `description`: say what the tool does, what it returns and where
200
- to get ids from. `input` is a valibot schema or `{ key: schema }` (validated like
201
- `useValidatedBody`; agents send JSON, so numbers are numbers: no `vh.*`). Omit it for no input.
256
+ to get ids from. In `defineTool`, `input` is a valibot schema or `{ key: schema }` (validated
257
+ like `useValidatedBody`; agents send JSON, so numbers are numbers: no `vh.*`). Omit it for no
258
+ input.
202
259
  - `readOnly: true` for tools that only read. Agents may call those without asking the user.
203
- - A tool runs as the visitor, like an API route: check `useWervtUser(event)` and ownership in the
204
- handler exactly as the matching route does. Throw `createError` for errors; the agent sees the
205
- message.
260
+ - A tool runs as the user, like an API route: check `useWervtUser(event)` and ownership in the
261
+ handler exactly as the matching route does. Over MCP, `useWervtUser(event)` is the user the
262
+ client signed in as. Throw `createError` for errors; the agent sees the message.
206
263
  - Writes reach the page through live data by themselves; the tool doesn't need to update the UI.
207
- - Browsers without WebMCP ignore the tools. `wervt: { webmcp: false }` turns them off.
264
+ - `/mcp` and its sign-in are set up by `@wervt/nuxt`: don't write an MCP route or OAuth code. For
265
+ how the tools fit together, set `wervt: { mcp: { instructions: '…' } }`.
266
+ - Connect a client: `claude mcp add --transport http <app> https://<app>.wervt.app/mcp`. Under
267
+ `pnpm dev`, `/mcp` serves every client as the dev user, no sign-in.
268
+ - Browsers without WebMCP ignore the tools. `wervt: { webmcp: false }` / `wervt: { mcp: false }`
269
+ turn them off.
208
270
 
209
271
  ## Don'ts
210
272
 
package/template/app.vue CHANGED
@@ -3,7 +3,7 @@ import type { Todo } from './server/db/schema'
3
3
 
4
4
  // Rows arrive with SSR and then stay live: every write below shows up here (and in every
5
5
  // other open tab) through Electric, so there is nothing to refetch.
6
- const { data, isLive } = await useShape<Todo>('/api/shapes/todos')
6
+ const { data, isLive } = await useShape('/api/shapes/todos')
7
7
  const todos = computed(() => data.value.toSorted((a, b) => a.id - b.id))
8
8
  const title = ref('')
9
9
 
@@ -9,14 +9,14 @@
9
9
  "postinstall": "nuxt prepare"
10
10
  },
11
11
  "dependencies": {
12
- "@wervt/nuxt": "^0.2.10",
12
+ "@wervt/nuxt": "^0.3.0",
13
13
  "drizzle-orm": "1.0.0-rc.4",
14
14
  "nuxt": "npm:nuxt-nightly@5x",
15
15
  "valibot": "^1.5.0",
16
16
  "vue": "^3.5.43"
17
17
  },
18
18
  "devDependencies": {
19
- "@wervt/cli": "^0.2.8",
19
+ "@wervt/cli": "^0.2.11",
20
20
  "drizzle-kit": "1.0.0-rc.4",
21
21
  "vite-plus": "^1.0.0"
22
22
  }
@@ -1,6 +1,7 @@
1
1
  import { proxyShape } from '@wervt/nuxt/server'
2
2
  import { defineEventHandler } from 'nuxt/server'
3
+ import { todos } from '../../db/schema'
3
4
 
4
- // Live data for useShape('/api/shapes/todos'). Check auth here and narrow rows with
5
- // `where` before exposing anything user-specific.
6
- export default defineEventHandler((event) => proxyShape(event, { table: 'todos' }))
5
+ // Live data for useShape('/api/shapes/todos'), typed by the table. Check auth here and narrow
6
+ // rows with `where` before exposing anything user-specific.
7
+ export default defineEventHandler((event) => proxyShape(event, { table: todos }))
@@ -1,16 +1,22 @@
1
- import { useDb, useValidatedBody, useValidatedParams, vh } from '@wervt/nuxt/server'
1
+ import { defineToolRoute, useDb, vh } from '@wervt/nuxt/server'
2
2
  import { eq } from 'drizzle-orm'
3
- import { createError, defineEventHandler } from 'nuxt/server'
3
+ import { createError } from 'nuxt/server'
4
4
  import * as v from 'valibot'
5
5
  import { todos } from '../../db/schema'
6
6
 
7
- export default defineEventHandler(async (event) => {
8
- const { id } = await useValidatedParams(event, { id: vh.id })
9
- const values = await useValidatedBody(event, {
7
+ export default defineToolRoute({
8
+ tool: {
9
+ name: 'update-todo',
10
+ description: 'Rename a todo or mark it done or not done. Get the id from list-todos.',
11
+ },
12
+ params: { id: vh.id },
13
+ input: {
10
14
  title: v.optional(v.pipe(v.string(), v.trim(), v.nonEmpty(), v.maxLength(200))),
11
15
  done: v.optional(v.boolean()),
12
- })
13
- const [todo] = await useDb().update(todos).set(values).where(eq(todos.id, id)).returning()
14
- if (!todo) throw createError({ status: 404, message: 'Todo not found' })
15
- return todo
16
+ },
17
+ async handler(_event, { id, ...values }) {
18
+ const [todo] = await useDb().update(todos).set(values).where(eq(todos.id, id)).returning()
19
+ if (!todo) throw createError({ status: 404, message: `No todo with id ${id}` })
20
+ return todo
21
+ },
16
22
  })
@@ -1,12 +1,13 @@
1
- import { useDb, useValidatedBody } from '@wervt/nuxt/server'
2
- import { defineEventHandler } from 'nuxt/server'
1
+ import { defineToolRoute, useDb } from '@wervt/nuxt/server'
3
2
  import * as v from 'valibot'
4
3
  import { todos } from '../db/schema'
5
4
 
6
- export default defineEventHandler(async (event) => {
7
- const values = await useValidatedBody(event, {
8
- title: v.pipe(v.string(), v.trim(), v.nonEmpty(), v.maxLength(200)),
9
- })
10
- const [todo] = await useDb().insert(todos).values(values).returning()
11
- return todo
5
+ // A route agents can call as a tool too (WebMCP on the page, `/mcp` for MCP clients).
6
+ export default defineToolRoute({
7
+ tool: { name: 'add-todo', description: 'Add a todo. Returns the new todo.' },
8
+ input: { title: v.pipe(v.string(), v.trim(), v.nonEmpty(), v.maxLength(200)) },
9
+ async handler(_event, values) {
10
+ const [todo] = await useDb().insert(todos).values(values).returning()
11
+ return todo
12
+ },
12
13
  })
@@ -0,0 +1,15 @@
1
+ import { defineTask, seedTable } from '@wervt/nuxt/server'
2
+ import { todos } from '../../db/schema'
3
+
4
+ // `nuxt dev` runs this once on a new database; `nuxt task run db:seed` runs it again.
5
+ export default defineTask({
6
+ meta: { description: 'Fill an empty database with example todos' },
7
+ async run() {
8
+ const inserted = await seedTable(todos, [
9
+ { title: 'Try the app', done: true },
10
+ { title: 'Change server/db/schema.ts' },
11
+ { title: 'Deploy to wervt' },
12
+ ])
13
+ return { result: { todos: inserted } }
14
+ },
15
+ })
@@ -1,12 +0,0 @@
1
- import { defineTool, useDb } from '@wervt/nuxt/server'
2
- import * as v from 'valibot'
3
- import { todos } from '../db/schema'
4
-
5
- export default defineTool({
6
- description: 'Add a todo. Returns the new todo.',
7
- input: { title: v.pipe(v.string(), v.trim(), v.nonEmpty(), v.maxLength(200)) },
8
- async handler(_event, input) {
9
- const [todo] = await useDb().insert(todos).values(input).returning()
10
- return todo
11
- },
12
- })
@@ -1,15 +0,0 @@
1
- import { defineTool, useDb } from '@wervt/nuxt/server'
2
- import { eq } from 'drizzle-orm'
3
- import { createError } from 'nuxt/server'
4
- import * as v from 'valibot'
5
- import { todos } from '../db/schema'
6
-
7
- export default defineTool({
8
- description: 'Mark a todo as done or not done. Get the id from list-todos.',
9
- input: { id: v.pipe(v.number(), v.integer()), done: v.boolean() },
10
- async handler(_event, { id, done }) {
11
- const [todo] = await useDb().update(todos).set({ done }).where(eq(todos.id, id)).returning()
12
- if (!todo) throw createError({ status: 404, message: `No todo with id ${id}` })
13
- return todo
14
- },
15
- })