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 +1 -1
- package/template/AGENTS.md +86 -24
- package/template/app.vue +1 -1
- package/template/package.json +2 -2
- package/template/server/api/shapes/todos.get.ts +4 -3
- package/template/server/api/todos/[id].patch.ts +15 -9
- package/template/server/api/todos.post.ts +9 -8
- package/template/server/tasks/db/seed.ts +15 -0
- package/template/server/tools/add-todo.ts +0 -12
- package/template/server/tools/set-todo-done.ts +0 -15
package/package.json
CHANGED
package/template/AGENTS.md
CHANGED
|
@@ -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
|
|
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:
|
|
104
|
+
export default defineEventHandler((event) => proxyShape(event, { table: todos }))
|
|
90
105
|
```
|
|
91
106
|
|
|
92
107
|
```vue
|
|
93
108
|
<script setup lang="ts">
|
|
94
|
-
|
|
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
|
-
-
|
|
103
|
-
|
|
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:
|
|
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
|
-
##
|
|
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
|
|
180
|
-
|
|
181
|
-
|
|
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/
|
|
185
|
-
import {
|
|
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: '
|
|
191
|
-
|
|
192
|
-
|
|
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
|
|
201
|
-
`useValidatedBody`; agents send JSON, so numbers are numbers: no `vh.*`). Omit it for no
|
|
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
|
|
204
|
-
handler exactly as the matching route does.
|
|
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
|
-
-
|
|
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
|
|
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
|
|
package/template/package.json
CHANGED
|
@@ -9,14 +9,14 @@
|
|
|
9
9
|
"postinstall": "nuxt prepare"
|
|
10
10
|
},
|
|
11
11
|
"dependencies": {
|
|
12
|
-
"@wervt/nuxt": "^0.
|
|
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.
|
|
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
|
|
5
|
-
// `where` before exposing anything user-specific.
|
|
6
|
-
export default defineEventHandler((event) => proxyShape(event, { table:
|
|
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 {
|
|
1
|
+
import { defineToolRoute, useDb, vh } from '@wervt/nuxt/server'
|
|
2
2
|
import { eq } from 'drizzle-orm'
|
|
3
|
-
import { createError
|
|
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
|
|
8
|
-
|
|
9
|
-
|
|
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
|
-
|
|
14
|
-
|
|
15
|
-
|
|
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 {
|
|
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
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
}
|
|
10
|
-
|
|
11
|
-
|
|
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
|
-
})
|