create-wervt 0.2.10 → 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 +58 -14
- package/template/package.json +2 -2
- 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
|
@@ -9,6 +9,8 @@ Supabase Edge Runtime) with its own Postgres schema and live data through Electr
|
|
|
9
9
|
- `app.vue`, `pages/`, `components/`: the Vue app.
|
|
10
10
|
- `server/api/`: API routes. `server/api/shapes/`: live data routes.
|
|
11
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:
|
|
@@ -101,6 +115,8 @@ const { data: todos, isLive } = await useShape('/api/shapes/todos')
|
|
|
101
115
|
any API route show up in every open tab without refetching.
|
|
102
116
|
- Writes go through normal API routes (`$fetch('/api/todos', { method: 'POST', body })`).
|
|
103
117
|
- Shapes can't join. Load several shapes and combine them with `computed`.
|
|
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.
|
|
104
120
|
- Pass the Drizzle table (not its name) to `proxyShape`: `useShape` then knows the row type for
|
|
105
121
|
every route in `server/api/shapes/`. Timestamps arrive as `Date`, like Drizzle reads them; keep
|
|
106
122
|
`timestamp()` in its default mode. `bigint` columns arrive as `BigInt` (use `mode: 'bigint'`).
|
|
@@ -188,30 +204,58 @@ button (`position: 'none'` hides the floating one), `.setContext({ … })` adds
|
|
|
188
204
|
|
|
189
205
|
## AI agents (WebMCP and MCP)
|
|
190
206
|
|
|
191
|
-
Tools
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
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:
|
|
195
214
|
|
|
196
215
|
```ts
|
|
197
|
-
// server/
|
|
198
|
-
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'
|
|
199
220
|
import * as v from 'valibot'
|
|
200
|
-
import { todos } from '
|
|
221
|
+
import { todos } from '../../db/schema'
|
|
201
222
|
|
|
202
|
-
export default
|
|
203
|
-
description: '
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
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}` })
|
|
207
230
|
return todo
|
|
208
231
|
},
|
|
209
232
|
})
|
|
210
233
|
```
|
|
211
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'
|
|
246
|
+
import { todos } from '../db/schema'
|
|
247
|
+
|
|
248
|
+
export default defineTool({
|
|
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)),
|
|
252
|
+
})
|
|
253
|
+
```
|
|
254
|
+
|
|
212
255
|
- The agent picks tools by their `description`: say what the tool does, what it returns and where
|
|
213
|
-
to get ids from. `input` is a valibot schema or `{ key: schema }` (validated
|
|
214
|
-
`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.
|
|
215
259
|
- `readOnly: true` for tools that only read. Agents may call those without asking the user.
|
|
216
260
|
- A tool runs as the user, like an API route: check `useWervtUser(event)` and ownership in the
|
|
217
261
|
handler exactly as the matching route does. Over MCP, `useWervtUser(event)` is the user the
|
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,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
|
-
})
|