create-wervt 0.2.6 → 0.2.8
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/index.js +51 -2
- package/package.json +1 -1
- package/template/AGENTS.md +42 -3
- package/template/_gitignore +2 -0
- package/template/package.json +2 -2
- package/template/pnpm-workspace.yaml +6 -0
- package/template/server/tools/add-todo.ts +12 -0
- package/template/server/tools/list-todos.ts +10 -0
- package/template/server/tools/set-todo-done.ts +15 -0
- package/template/vite.config.ts +3 -1
package/index.js
CHANGED
|
@@ -12,6 +12,40 @@ import { installDependencies } from 'nypm'
|
|
|
12
12
|
const BUNDLED_TEMPLATE = new URL('./template', import.meta.url).pathname
|
|
13
13
|
const NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
|
|
14
14
|
|
|
15
|
+
// Without a terminal (CI logs, agent shells), clack's spinner prints every frame as text.
|
|
16
|
+
const interactive = process.stdout.isTTY === true && !process.env.CI
|
|
17
|
+
|
|
18
|
+
function progress() {
|
|
19
|
+
if (interactive) return p.spinner()
|
|
20
|
+
return { start: (message) => p.log.step(message), stop: (message) => p.log.success(message) }
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
// `--empty`: the todo example's files, and what replaces the ones an app always has.
|
|
24
|
+
const EXAMPLE_FILES = [
|
|
25
|
+
'server/api/todos.post.ts',
|
|
26
|
+
'server/api/todos',
|
|
27
|
+
'server/api/shapes/todos.get.ts',
|
|
28
|
+
'server/tools',
|
|
29
|
+
'drizzle',
|
|
30
|
+
]
|
|
31
|
+
const EMPTY_SCHEMA = `// Tables are declared without a schema: on wervt the app's database role only sees
|
|
32
|
+
// its own schema. Run \`pnpm db:generate\` after changing this file.
|
|
33
|
+
//
|
|
34
|
+
// import { pgTable, serial, text } from 'drizzle-orm/pg-core'
|
|
35
|
+
//
|
|
36
|
+
// export const notes = pgTable('notes', {
|
|
37
|
+
// id: serial().primaryKey(),
|
|
38
|
+
// text: text().notNull(),
|
|
39
|
+
// })
|
|
40
|
+
export {}
|
|
41
|
+
`
|
|
42
|
+
const EMPTY_APP = `<template>
|
|
43
|
+
<main>
|
|
44
|
+
<h1>Hello from wervt</h1>
|
|
45
|
+
</main>
|
|
46
|
+
</template>
|
|
47
|
+
`
|
|
48
|
+
|
|
15
49
|
/**
|
|
16
50
|
* The newest version of a package on npm. Releases of @wervt/nuxt and @wervt/cli don't release
|
|
17
51
|
* this package, so new apps ask the registry instead of keeping the versions bundled at pack
|
|
@@ -57,6 +91,11 @@ const main = defineCommand({
|
|
|
57
91
|
},
|
|
58
92
|
install: { type: 'boolean', default: true, description: 'Install dependencies' },
|
|
59
93
|
force: { type: 'boolean', default: false, description: 'Overwrite an existing directory' },
|
|
94
|
+
empty: {
|
|
95
|
+
type: 'boolean',
|
|
96
|
+
default: false,
|
|
97
|
+
description: 'Without the todo example (no API routes, tools, table or migration)',
|
|
98
|
+
},
|
|
60
99
|
},
|
|
61
100
|
async run({ args }) {
|
|
62
101
|
p.intro('create-wervt')
|
|
@@ -78,7 +117,7 @@ const main = defineCommand({
|
|
|
78
117
|
if (existsSync(dir) && !args.force)
|
|
79
118
|
throw new Error(`${relative(process.cwd(), dir) || dir} already exists (use --force)`)
|
|
80
119
|
|
|
81
|
-
const spinner =
|
|
120
|
+
const spinner = progress()
|
|
82
121
|
spinner.start('Creating app')
|
|
83
122
|
if (args.template) {
|
|
84
123
|
await downloadTemplate(args.template, { dir, force: args.force })
|
|
@@ -89,6 +128,12 @@ const main = defineCommand({
|
|
|
89
128
|
await rename(join(dir, '_gitignore'), join(dir, '.gitignore'))
|
|
90
129
|
}
|
|
91
130
|
|
|
131
|
+
if (args.empty) {
|
|
132
|
+
for (const file of EXAMPLE_FILES) await rm(join(dir, file), { recursive: true, force: true })
|
|
133
|
+
await writeFile(join(dir, 'server/db/schema.ts'), EMPTY_SCHEMA)
|
|
134
|
+
await writeFile(join(dir, 'app.vue'), EMPTY_APP)
|
|
135
|
+
}
|
|
136
|
+
|
|
92
137
|
const pkgPath = join(dir, 'package.json')
|
|
93
138
|
const pkg = JSON.parse(await readFile(pkgPath, 'utf8'))
|
|
94
139
|
pkg.name = name
|
|
@@ -100,6 +145,8 @@ const main = defineCommand({
|
|
|
100
145
|
await rm(join(dir, 'vite.config.ts'), { force: true })
|
|
101
146
|
// Apps in the repo are deployed from the repo, not by their own workflow.
|
|
102
147
|
await rm(join(dir, '.github'), { recursive: true, force: true })
|
|
148
|
+
// The repo's own pnpm-workspace.yaml covers the app; its own would split it off.
|
|
149
|
+
await rm(join(dir, 'pnpm-workspace.yaml'), { force: true })
|
|
103
150
|
} else {
|
|
104
151
|
for (const [deps, name] of [
|
|
105
152
|
['dependencies', '@wervt/nuxt'],
|
|
@@ -134,7 +181,9 @@ const main = defineCommand({
|
|
|
134
181
|
.join('\n'),
|
|
135
182
|
'Next steps',
|
|
136
183
|
)
|
|
137
|
-
|
|
184
|
+
// clack's outro ends with blank lines; without a terminal the last line is the message.
|
|
185
|
+
if (interactive) p.outro('Agents: read AGENTS.md before writing code.')
|
|
186
|
+
else console.log('Agents: read AGENTS.md before writing code.')
|
|
138
187
|
},
|
|
139
188
|
})
|
|
140
189
|
|
package/package.json
CHANGED
package/template/AGENTS.md
CHANGED
|
@@ -8,6 +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
12
|
- `server/db/schema.ts`: the Drizzle schema. `drizzle/`: generated migrations. Commit both.
|
|
12
13
|
|
|
13
14
|
## UI
|
|
@@ -108,6 +109,12 @@ const { data: todos, isLive } = await useShape<Todo>('/api/shapes/todos')
|
|
|
108
109
|
proxyShape(event, { table: 'notes', where: '"ownerId" = $1', params: [userId] })
|
|
109
110
|
```
|
|
110
111
|
|
|
112
|
+
## New releases
|
|
113
|
+
|
|
114
|
+
Open tabs notice a new release by themselves and show a reload banner. Don't build your own
|
|
115
|
+
version polling. For a banner in the app's own design, set `wervt: { updates: 'manual' }` and use
|
|
116
|
+
`const { available, reload } = useWervtUpdate()`.
|
|
117
|
+
|
|
111
118
|
## Users and sessions
|
|
112
119
|
|
|
113
120
|
- `useWervtUser(event)` (server, from `@wervt/nuxt/server`) and `useWervtUser()` (app,
|
|
@@ -167,6 +174,38 @@ wervt: { timezone: 'Europe/Berlin' }, // optional, UTC by default
|
|
|
167
174
|
`pnpm exec wervt tasks <app> --run <name>`), e.g. for a backfill.
|
|
168
175
|
- Every run is logged: `pnpm exec wervt logs <app> 'type:=Task'`.
|
|
169
176
|
|
|
177
|
+
## Browser agents (WebMCP)
|
|
178
|
+
|
|
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.
|
|
182
|
+
|
|
183
|
+
```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'
|
|
186
|
+
import * as v from 'valibot'
|
|
187
|
+
import { todos } from '../db/schema'
|
|
188
|
+
|
|
189
|
+
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
|
+
},
|
|
196
|
+
})
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
- 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.
|
|
202
|
+
- `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.
|
|
206
|
+
- 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.
|
|
208
|
+
|
|
170
209
|
## Don'ts
|
|
171
210
|
|
|
172
211
|
- No Node-only APIs that Deno lacks (`child_process`, native addons, writing to the filesystem).
|
|
@@ -204,6 +243,6 @@ Queries are LogsQL. Logs may contain user data: quote only what's needed.
|
|
|
204
243
|
- `pnpm dev`: dev server against the local wervt stack (`docker compose up -d` in the wervt repo).
|
|
205
244
|
- `pnpm db:generate`: generate a migration from the schema.
|
|
206
245
|
- `pnpm exec vp check --fix`: format, lint and type check. Run it before finishing.
|
|
207
|
-
- Deploys: pushing to `main` deploys through `.github/workflows/deploy.yml`.
|
|
208
|
-
releases <app>` lists releases with their commits. Don't deploy, roll back or
|
|
209
|
-
unless asked.
|
|
246
|
+
- Deploys: pushing to `main` deploys through `.github/workflows/deploy.yml`.
|
|
247
|
+
`pnpm exec wervt releases <app>` lists releases with their commits. Don't deploy, roll back or
|
|
248
|
+
create tokens unless asked.
|
package/template/_gitignore
CHANGED
package/template/package.json
CHANGED
|
@@ -9,13 +9,13 @@
|
|
|
9
9
|
"postinstall": "nuxt prepare"
|
|
10
10
|
},
|
|
11
11
|
"dependencies": {
|
|
12
|
-
"@wervt/nuxt": "^0.2.
|
|
12
|
+
"@wervt/nuxt": "^0.2.9",
|
|
13
13
|
"drizzle-orm": "1.0.0-rc.4",
|
|
14
14
|
"nuxt": "npm:nuxt-nightly@5x",
|
|
15
15
|
"valibot": "^1.5.0"
|
|
16
16
|
},
|
|
17
17
|
"devDependencies": {
|
|
18
|
-
"@wervt/cli": "^0.2.
|
|
18
|
+
"@wervt/cli": "^0.2.8",
|
|
19
19
|
"drizzle-kit": "1.0.0-rc.4",
|
|
20
20
|
"vite-plus": "^1.0.0"
|
|
21
21
|
}
|
|
@@ -0,0 +1,12 @@
|
|
|
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
|
+
})
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import { defineTool, useDb } from '@wervt/nuxt/server'
|
|
2
|
+
import { desc } from 'drizzle-orm'
|
|
3
|
+
import { todos } from '../db/schema'
|
|
4
|
+
|
|
5
|
+
// Browser agents (WebMCP) can call the tools in this folder on the open page, as the visitor.
|
|
6
|
+
export default defineTool({
|
|
7
|
+
description: 'List all todos, newest first, with their id, title and whether they are done.',
|
|
8
|
+
readOnly: true,
|
|
9
|
+
handler: () => useDb().select().from(todos).orderBy(desc(todos.createdAt)),
|
|
10
|
+
})
|
|
@@ -0,0 +1,15 @@
|
|
|
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
|
+
})
|
package/template/vite.config.ts
CHANGED
|
@@ -5,9 +5,11 @@ export default defineConfig({
|
|
|
5
5
|
singleQuote: true,
|
|
6
6
|
semi: false,
|
|
7
7
|
printWidth: 100,
|
|
8
|
-
|
|
8
|
+
// Generated migrations, and the bundled Nuxt UI skills (kept as published).
|
|
9
|
+
ignorePatterns: ['drizzle/**', '.claude/skills/nuxt-ui*/**'],
|
|
9
10
|
},
|
|
10
11
|
lint: {
|
|
12
|
+
ignorePatterns: ['.claude/skills/nuxt-ui*/**'],
|
|
11
13
|
options: { typeAware: true, typeCheck: true },
|
|
12
14
|
},
|
|
13
15
|
})
|