create-wervt 0.2.9 → 0.2.10

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.10",
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,7 @@ 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
12
  - `server/db/schema.ts`: the Drizzle schema. `drizzle/`: generated migrations. Commit both.
13
13
 
14
14
  ## UI
@@ -85,13 +85,15 @@ Prefer live data over refetching. A shape is one table, optionally filtered:
85
85
  // server/api/shapes/todos.get.ts
86
86
  import { proxyShape } from '@wervt/nuxt/server'
87
87
  import { defineEventHandler } from 'nuxt/server'
88
+ import { todos } from '../../db/schema'
88
89
 
89
- export default defineEventHandler((event) => proxyShape(event, { table: 'todos' }))
90
+ export default defineEventHandler((event) => proxyShape(event, { table: todos }))
90
91
  ```
91
92
 
92
93
  ```vue
93
94
  <script setup lang="ts">
94
- const { data: todos, isLive } = await useShape<Todo>('/api/shapes/todos')
95
+ // Typed from the route: rows are `typeof todos.$inferSelect`, no type argument needed.
96
+ const { data: todos, isLive } = await useShape('/api/shapes/todos')
95
97
  </script>
96
98
  ```
97
99
 
@@ -99,14 +101,17 @@ const { data: todos, isLive } = await useShape<Todo>('/api/shapes/todos')
99
101
  any API route show up in every open tab without refetching.
100
102
  - Writes go through normal API routes (`$fetch('/api/todos', { method: 'POST', body })`).
101
103
  - 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.
104
+ - Pass the Drizzle table (not its name) to `proxyShape`: `useShape` then knows the row type for
105
+ every route in `server/api/shapes/`. Timestamps arrive as `Date`, like Drizzle reads them; keep
106
+ `timestamp()` in its default mode. `bigint` columns arrive as `BigInt` (use `mode: 'bigint'`).
107
+ - Column names are what the client sees, so keep them camelCase like the schema keys (no
108
+ snake_case `casing`).
104
109
  - Never put secrets in a shape: list the `columns` a client may see.
105
110
  - Do auth checks in the shape route and restrict rows with `where`. Pass values as `params`,
106
111
  never by building the SQL string:
107
112
 
108
113
  ```ts
109
- proxyShape(event, { table: 'notes', where: '"ownerId" = $1', params: [userId] })
114
+ proxyShape(event, { table: notes, where: '"ownerId" = $1', params: [userId] })
110
115
  ```
111
116
 
112
117
  ## New releases
@@ -174,11 +179,19 @@ wervt: { timezone: 'Europe/Berlin' }, // optional, UTC by default
174
179
  `pnpm exec wervt tasks <app> --run <name>`), e.g. for a backfill.
175
180
  - Every run is logged: `pnpm exec wervt logs <app> 'type:=Task'`.
176
181
 
177
- ## Browser agents (WebMCP)
182
+ ## Feedback
178
183
 
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.
184
+ `wervt: { feedback: { key: 'pk_…' } }` adds kontor's feedback button: reports go into a kontor
185
+ project's triage with page, browser and release. The key comes from the kontor project
186
+ (Settings → Intake keys) and is public. `useWervtFeedback().open()` opens it from your own
187
+ button (`position: 'none'` hides the floating one), `.setContext({ … })` adds context.
188
+
189
+ ## AI agents (WebMCP and MCP)
190
+
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.
182
195
 
183
196
  ```ts
184
197
  // server/tools/add-todo.ts → tool "add-todo" (server/tools/todos/add.ts is "todos.add")
@@ -200,11 +213,16 @@ export default defineTool({
200
213
  to get ids from. `input` is a valibot schema or `{ key: schema }` (validated like
201
214
  `useValidatedBody`; agents send JSON, so numbers are numbers: no `vh.*`). Omit it for no input.
202
215
  - `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.
216
+ - A tool runs as the user, like an API route: check `useWervtUser(event)` and ownership in the
217
+ handler exactly as the matching route does. Over MCP, `useWervtUser(event)` is the user the
218
+ client signed in as. Throw `createError` for errors; the agent sees the message.
206
219
  - 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.
220
+ - `/mcp` and its sign-in are set up by `@wervt/nuxt`: don't write an MCP route or OAuth code. For
221
+ how the tools fit together, set `wervt: { mcp: { instructions: '…' } }`.
222
+ - Connect a client: `claude mcp add --transport http <app> https://<app>.wervt.app/mcp`. Under
223
+ `pnpm dev`, `/mcp` serves every client as the dev user, no sign-in.
224
+ - Browsers without WebMCP ignore the tools. `wervt: { webmcp: false }` / `wervt: { mcp: false }`
225
+ turn them off.
208
226
 
209
227
  ## Don'ts
210
228
 
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.2.16",
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.10",
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 }))