create-wervt 0.2.10 → 0.2.12

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/README.md CHANGED
@@ -1,3 +1,14 @@
1
1
  # create-wervt
2
2
 
3
- `npm create wervt` will scaffold a new wervt app. Work in progress, nothing usable yet.
3
+ Scaffolds a [wervt](https://wervt.app) app: Nuxt with `@wervt/nuxt`, Drizzle, valibot and Vite+,
4
+ a todo example, an `AGENTS.md` for your agent and a GitHub Actions workflow that deploys on push.
5
+
6
+ ```bash
7
+ vp create wervt my-app # or: pnpm create wervt my-app
8
+ cd my-app
9
+ vp exec wervt deploy
10
+ ```
11
+
12
+ `--empty` leaves out the todo example. Sign in first with
13
+ `vpx @wervt/cli login --url <control plane URL>`. See the
14
+ [quickstart](https://wervt.app/getting-started/quickstart).
package/index.js CHANGED
@@ -173,9 +173,10 @@ const main = defineCommand({
173
173
  [
174
174
  cd && `cd ${cd}`,
175
175
  !args.install && 'pnpm install',
176
- 'pnpm dev',
177
176
  monorepo && `pnpm app:deploy ${name} # from the repo root`,
178
- !monorepo && 'pnpm exec wervt deploy # or from CI: .github/workflows/deploy.yml',
177
+ !monorepo && 'pnpm exec wervt deploy # or push: .github/workflows/deploy.yml',
178
+ // The local stack is optional, so the dev server comes second: a deploy is the real test.
179
+ 'pnpm dev # optional; the database needs the local wervt stack',
179
180
  ]
180
181
  .filter(Boolean)
181
182
  .join('\n'),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "create-wervt",
3
- "version": "0.2.10",
3
+ "version": "0.2.12",
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",
@@ -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 in `server/tools/` let agents use the app on a user's behalf: an agent in the visitor's
192
- browser (WebMCP, `document.modelContext`), and AI clients like Claude Code or Cursor through the
193
- app's MCP endpoint at `/mcp`, after the user signed in with wervt. Give the app a tool for each
194
- thing a user would ask an 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:
195
214
 
196
215
  ```ts
197
- // server/tools/add-todo.ts → tool "add-todo" (server/tools/todos/add.ts is "todos.add")
198
- 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'
199
220
  import * as v from 'valibot'
200
- import { todos } from '../db/schema'
221
+ import { todos } from '../../db/schema'
201
222
 
202
- export default defineTool({
203
- description: 'Add a todo. Returns the new todo.',
204
- input: { title: v.pipe(v.string(), v.trim(), v.nonEmpty(), v.maxLength(200)) },
205
- async handler(event, input) {
206
- const [todo] = await useDb().insert(todos).values(input).returning()
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 like
214
- `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.
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
@@ -258,7 +302,9 @@ Queries are LogsQL. Logs may contain user data: quote only what's needed.
258
302
 
259
303
  ## Commands
260
304
 
261
- - `pnpm dev`: dev server against the local wervt stack (`docker compose up -d` in the wervt repo).
305
+ - `pnpm dev`: dev server. Pages and API routes work on their own; the database, live data and
306
+ files need the local wervt stack (`docker compose up -d` in the wervt repo), which is optional.
307
+ Without it, check database work on the deployed app.
262
308
  - `pnpm db:generate`: generate a migration from the schema.
263
309
  - `pnpm exec vp check --fix`: format, lint and type check. Run it before finishing.
264
310
  - Deploys: pushing to `main` deploys through `.github/workflows/deploy.yml`.
@@ -9,14 +9,14 @@
9
9
  "postinstall": "nuxt prepare"
10
10
  },
11
11
  "dependencies": {
12
- "@wervt/nuxt": "^0.2.16",
12
+ "@wervt/nuxt": "^0.3.1",
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.10",
19
+ "@wervt/cli": "^0.2.12",
20
20
  "drizzle-kit": "1.0.0-rc.4",
21
21
  "vite-plus": "^1.0.0"
22
22
  }
@@ -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
- })