@escalay/kit 0.0.0-stage → 1.7.0

package/templates/app/test/api.test.ts

@@ -0,0 +1,34 @@
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import { createApp, TOOLS } from '../src/app.js'
+import { FEATURES } from '../src/features/index.js'
+import { guideFiles, guideModuleSource, hashApiKey, testDb } from '../src/kit/index.js'
+import { guideGaps, lintOpenApi, toolRoutes, toolsRun } from '../src/kit/testing/index.js'
+
+const GUIDE_DIR = fileURLToPath(new URL('../guide', import.meta.url))
+const KEY = 'test-key'
+const headers = { authorization: `Bearer ${KEY}` }
+const app = await createApp({ db: await testDb(), env: { API_KEYS: `tester:${hashApiKey(KEY)}` } })
+const request = async (path: string, init: RequestInit = {}) => app.request(path, { ...init, headers: { ...headers, 'content-type': 'application/json', ...(init.headers as Record<string, string>) } })
+const doc = async () => (await app.request('/openapi.json', { headers })).json()
+
+describe('the API', () => {
+  it('documents every route to the standard, and every tool lands on one', async () => {
+    expect(lintOpenApi(await doc())).toEqual([])
+    expect(toolRoutes(TOOLS, await doc())).toEqual([])
+  })
+
+  it('runs every MCP tool against its route', async () => {
+    const samples = Object.assign({}, ...(await Promise.all(FEATURES.map((feature) => feature.samples(request)))))
+    expect(await toolsRun(TOOLS, app, samples, { headers })).toEqual([])
+  })
+
+  it('fills every placeholder in the agent guide', async () => {
+    expect(guideGaps(guideFiles(GUIDE_DIR), {}, { doc: await doc(), tools: TOOLS })).toEqual([])
+  })
+
+  it('serves the guide folder as it is now (run `pnpm guide` after editing guide/)', () => {
+    expect(readFileSync(new URL('../src/guide.gen.ts', import.meta.url), 'utf8')).toBe(guideModuleSource(guideFiles(GUIDE_DIR)))
+  })
+})

package/templates/app/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["node"],
+    "noUncheckedIndexedAccess": true
+  },
+  "include": ["src/**/*.ts", "test/**/*.ts", "scripts/**/*.ts"],
+  "$comment": "Workers code is checked by test/workers/tsconfig.json when the app runs on Cloudflare",
+  "exclude": ["src/worker.ts", "test/workers"]
+}

package/templates/feature/feature.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest'
+import { createApp } from '../../app.js'
+import { hashApiKey, testDb } from '../../kit/index.js'
+
+const headers = { authorization: 'Bearer test-key', 'content-type': 'application/json' }
+const app = await createApp({ db: await testDb(), env: { API_KEYS: `tester:${hashApiKey('test-key')}` } })
+
+describe('__labels__', () => {
+  it('makes, lists, changes and deletes a __label__', async () => {
+    const made = await app.request('/api/__name__', { method: 'POST', headers, body: JSON.stringify({ title: 'First' }) })
+    expect(made.status).toBe(201)
+    const { id } = (await made.json()) as { id: string }
+    expect(made.headers.get('location')).toBe(`/api/__name__/${id}`)
+    expect(await (await app.request('/api/__name__', { headers })).json()).toMatchObject({ count: 1 })
+    expect(await (await app.request(`/api/__name__/${id}`, { method: 'PATCH', headers, body: JSON.stringify({ body: 'more' }) })).json()).toMatchObject({ title: 'First', body: 'more' })
+    expect((await app.request(`/api/__name__/${id}`, { method: 'DELETE', headers })).status).toBe(204)
+    expect((await app.request(`/api/__name__/${id}`, { headers })).status).toBe(404)
+  })
+})

package/templates/feature/handlers.ts

@@ -0,0 +1,43 @@
+/** The __labels__ routes' handlers: request → repo → HAL answer; a missing __label__ is a problem. No queries here. */
+import type { RouteHandler } from '@hono/zod-openapi'
+import { linksOf, originOf, ProblemError } from '../../kit/index.js'
+import type { __Pascal__Repo } from './repo.js'
+import { PATH, type routes } from './routes.js'
+import type { __Singular__Row } from './schema.js'
+
+type Routes = typeof routes
+
+export const __camel__Handlers = (repo: __Pascal__Repo) => {
+  const rowOf = async (id: string) => {
+    const row = await repo.get(id)
+    if (!row) throw new ProblemError('not_found', { detail: `No __label__ ${id}. GET ${PATH} lists them.` })
+    return row
+  }
+  const cardOf = (origin: string, row: __Singular__Row) => ({ ...row, _links: linksOf(origin, { self: `${PATH}/${row.id}`, list: PATH }) })
+
+  const list: RouteHandler<Routes['list']> = async (c) => {
+    const rows = await repo.list(c.req.valid('query').limit)
+    const origin = originOf(c)
+    return c.json({ count: rows.length, _links: linksOf(origin, { self: PATH }), _embedded: { __camel__: rows.map((row) => cardOf(origin, row)) } }, 200)
+  }
+  const get: RouteHandler<Routes['get']> = async (c) => c.json(cardOf(originOf(c), await rowOf(c.req.valid('param').id)), 200)
+  const create: RouteHandler<Routes['create']> = async (c) => {
+    const { title, body } = c.req.valid('json')
+    const id = await repo.create({ title: title.trim(), body: body ?? null })
+    return c.json(cardOf(originOf(c), await rowOf(id)), 201, { location: `${PATH}/${id}` })
+  }
+  const update: RouteHandler<Routes['update']> = async (c) => {
+    const { id } = c.req.valid('param')
+    await rowOf(id)
+    const { title, body } = c.req.valid('json')
+    await repo.update(id, { ...(title === undefined ? {} : { title: title.trim() }), ...(body === undefined ? {} : { body }) })
+    return c.json(cardOf(originOf(c), await rowOf(id)), 200)
+  }
+  const remove: RouteHandler<Routes['remove']> = async (c) => {
+    const { id } = c.req.valid('param')
+    await rowOf(id)
+    await repo.remove(id)
+    return c.body(null, 204)
+  }
+  return { list, get, create, update, remove }
+}

package/templates/feature/index.ts

@@ -0,0 +1,34 @@
+/** __Pascal__: the feature as the app registers it (routes and tables), its MCP tools, and sample tool arguments. */
+import { migrate } from '../../kit/index.js'
+import type { Feature } from '../index.js'
+import { __camel__Handlers } from './handlers.js'
+import { __camel__Repo } from './repo.js'
+import { PATH, routes, TAG } from './routes.js'
+import { __CONST___MIGRATIONS } from './schema.js'
+import { __camel__Tools } from './tools.js'
+
+export const feature: Feature = {
+  name: '__name__',
+  tag: { name: TAG, description: '__Pascal__: make, list, change and delete them.' },
+  migrations: __CONST___MIGRATIONS,
+  register: async (app, { db }) => {
+    await migrate(db, '__name__', __CONST___MIGRATIONS)
+    const handle = __camel__Handlers(__camel__Repo(db))
+    app.openapi(routes.list, handle.list)
+    app.openapi(routes.get, handle.get)
+    app.openapi(routes.create, handle.create)
+    app.openapi(routes.update, handle.update)
+    app.openapi(routes.remove, handle.remove)
+  },
+  tools: __camel__Tools,
+  samples: async (request) => {
+    const { id } = (await (await request(PATH, { method: 'POST', body: JSON.stringify({ title: 'A sample __label__' }) })).json()) as { id: string }
+    return {
+      list___snake__: {},
+      get___snake_singular__: { id },
+      create___snake_singular__: { title: 'Made by a tool' },
+      update___snake_singular__: { id, body: 'Changed by a tool' },
+      delete___snake_singular__: { id },
+    }
+  },
+}

package/templates/feature/repo.ts

@@ -0,0 +1,24 @@
+/** __Pascal__ in the database: the only place they are queried, and nothing about HTTP. */
+import { randomUUID } from 'node:crypto'
+import { desc, eq } from 'drizzle-orm'
+import type { Db } from '../../kit/index.js'
+import { __camel__ } from './schema.js'
+
+export const __camel__Repo = (db: Db) => {
+  const now = () => new Date().toISOString()
+  return {
+    /** The newest changed first. */
+    list: (limit: number) => db.select().from(__camel__).orderBy(desc(__camel__.updatedAt)).limit(limit),
+    get: async (id: string) => (await db.select().from(__camel__).where(eq(__camel__.id, id)))[0],
+    create: async ({ title, body }: { title: string; body?: string | null }) => {
+      const id = randomUUID()
+      const at = now()
+      await db.insert(__camel__).values({ id, title, body: body ?? null, createdAt: at, updatedAt: at })
+      return id
+    },
+    update: (id: string, change: { title?: string; body?: string | null }) => db.update(__camel__).set({ ...change, updatedAt: now() }).where(eq(__camel__.id, id)),
+    remove: (id: string) => db.delete(__camel__).where(eq(__camel__.id, id)),
+  }
+}
+
+export type __Pascal__Repo = ReturnType<typeof __camel__Repo>

package/templates/feature/routes.ts

@@ -0,0 +1,43 @@
+/** The __labels__ routes as OpenAPI contracts: paths, parameters, bodies and answers. */
+import { createRoute, z } from '@hono/zod-openapi'
+import { HAL_JSON, LinksSchema, problemResponses } from '../../kit/index.js'
+
+export const PATH = '/api/__name__'
+export const TAG = '__Pascal__'
+
+export const __Singular__Schema = z
+  .object({ id: z.string(), title: z.string(), body: z.string().nullable(), createdAt: z.string(), updatedAt: z.string(), _links: LinksSchema })
+  .openapi('__Singular__', { description: 'A __label__.' })
+const __Singular__ListSchema = z.object({ count: z.number().int(), _links: LinksSchema, _embedded: z.object({ __camel__: z.array(__Singular__Schema) }) }).openapi('__Singular__List', { description: '__Pascal__, the newest changed first.' })
+const __Singular__InputSchema = z.object({ title: z.string().min(1).max(200).openapi({ example: 'First __label__' }), body: z.string().max(10_000).optional().openapi({ description: 'Its text.' }) }).openapi('__Singular__Input', { description: 'A __label__’s title and text.' })
+const __Singular__PatchSchema = __Singular__InputSchema.partial().openapi('__Singular__Patch', { description: 'A new title or text.' })
+const id = z.string().min(1).max(80).openapi({ description: 'The __label__’s id.' })
+const ok = <Schema extends z.ZodTypeAny>(description: string, schema: Schema) => ({ content: { [HAL_JSON]: { schema } }, description })
+
+export const routes = {
+  list: createRoute({
+    method: 'get', path: PATH, operationId: 'list__Pascal__', tags: [TAG], summary: '__Pascal__', description: 'Every __label__, the newest changed first, each with its link.',
+    request: { query: z.object({ limit: z.coerce.number().int().min(1).max(100).default(50).openapi({ description: 'At most this many (1–100, default 50).' }) }) },
+    responses: { 200: ok('__Pascal__.', __Singular__ListSchema), ...problemResponses(400, 401) },
+  }),
+  get: createRoute({
+    method: 'get', path: `${PATH}/{id}`, operationId: 'get__Singular__', tags: [TAG], summary: 'One __label__', description: 'A __label__ with its title and text.',
+    request: { params: z.object({ id }) },
+    responses: { 200: ok('The __label__.', __Singular__Schema), ...problemResponses(401, 404) },
+  }),
+  create: createRoute({
+    method: 'post', path: PATH, operationId: 'create__Singular__', tags: [TAG], summary: 'Make a __label__', description: 'A new __label__. Answers 201 with its address in `Location`.',
+    request: { body: { required: true, content: { 'application/json': { schema: __Singular__InputSchema } } } },
+    responses: { 201: ok('The new __label__.', __Singular__Schema), ...problemResponses(400, 401, 403) },
+  }),
+  update: createRoute({
+    method: 'patch', path: `${PATH}/{id}`, operationId: 'update__Singular__', tags: [TAG], summary: 'Change a __label__', description: 'Changes a __label__’s title, its text, or both.',
+    request: { params: z.object({ id }), body: { required: true, content: { 'application/json': { schema: __Singular__PatchSchema } } } },
+    responses: { 200: ok('The __label__.', __Singular__Schema), ...problemResponses(400, 401, 403, 404) },
+  }),
+  remove: createRoute({
+    method: 'delete', path: `${PATH}/{id}`, operationId: 'delete__Singular__', tags: [TAG], summary: 'Delete a __label__', description: 'Deletes the __label__ for good.',
+    request: { params: z.object({ id }) },
+    responses: { 204: { description: 'Deleted.' }, ...problemResponses(401, 403, 404) },
+  }),
+}

package/templates/feature/schema.ts

@@ -0,0 +1,14 @@
+/** The __labels__ table, and the SQL that makes it: one migration step per change, never edited once it has run. */
+import { sqliteTable, text } from 'drizzle-orm/sqlite-core'
+
+export const __camel__ = sqliteTable('__table__', {
+  id: text('id').primaryKey(),
+  title: text('title').notNull(),
+  body: text('body'),
+  createdAt: text('created_at').notNull(),
+  updatedAt: text('updated_at').notNull(),
+})
+
+export const __CONST___MIGRATIONS = ['create table if not exists __table__ (id text primary key, title text not null, body text, created_at text not null, updated_at text not null)'] as const
+
+export type __Singular__Row = typeof __camel__.$inferSelect

package/templates/feature/tools.ts

@@ -0,0 +1,46 @@
+/** The __labels__ routes as MCP tools: thin calls an agent makes with the owner's credentials. */
+import { z } from '@hono/zod-openapi'
+import { mcpTool, type McpTool } from '../../kit/mcp/index.js'
+import { PATH } from './routes.js'
+
+type Card = { id: string; title: string; body: string | null; updatedAt: string }
+const line = (row: Card) => `${row.title} · id ${row.id} · changed ${row.updatedAt.slice(0, 10)}`
+const id = z.string().describe('The __label__’s id, from list___snake__.')
+
+export const __camel__Tools: McpTool[] = [
+  mcpTool({
+    name: 'list___snake__', title: '__Pascal__', description: 'Every __label__, the newest changed first, with its id. Start here.',
+    input: z.object({ limit: z.number().int().min(1).max(100).optional().describe('At most this many (default 50).') }),
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    call: (args) => ({ path: PATH, query: args }),
+    summarize: (json: { _embedded: { __camel__: Card[] } }) => json._embedded.__camel__.map(line).join('\n') || 'None yet.',
+  }),
+  mcpTool({
+    name: 'get___snake_singular__', title: 'One __label__', description: 'A __label__ with its full text.',
+    input: z.object({ id }),
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    call: ({ id }) => ({ path: `${PATH}/${encodeURIComponent(id)}` }),
+    summarize: (row: Card) => `${line(row)}\n\n${row.body ?? '(no text)'}`,
+  }),
+  mcpTool({
+    name: 'create___snake_singular__', title: 'Make a __label__', description: 'Makes a __label__ with a title and, optionally, its text.',
+    input: z.object({ title: z.string().min(1).max(200), body: z.string().max(10_000).optional() }),
+    annotations: { openWorldHint: false },
+    call: (body) => ({ method: 'POST', path: PATH, body }),
+    summarize: (row: Card) => `Made: ${line(row)}`,
+  }),
+  mcpTool({
+    name: 'update___snake_singular__', title: 'Change a __label__', description: 'Changes a __label__’s title, its text, or both.',
+    input: z.object({ id, title: z.string().min(1).max(200).optional(), body: z.string().max(10_000).optional() }),
+    annotations: { idempotentHint: true, openWorldHint: false },
+    call: ({ id, ...change }) => ({ method: 'PATCH', path: `${PATH}/${encodeURIComponent(id)}`, body: change }),
+    summarize: (row: Card) => `Changed: ${line(row)}`,
+  }),
+  mcpTool({
+    name: 'delete___snake_singular__', title: 'Delete a __label__', description: 'Deletes a __label__ for good. Ask the owner first.',
+    input: z.object({ id }),
+    annotations: { destructiveHint: true, openWorldHint: false },
+    call: ({ id }) => ({ method: 'DELETE', path: `${PATH}/${encodeURIComponent(id)}` }),
+    summarize: () => 'Deleted.',
+  }),
+]

package/templates/runtime-cloudflare/dev.vars.example

@@ -0,0 +1,3 @@
+# Local secrets for `wrangler dev`: copy to .dev.vars (git-ignored). API_KEYS holds name:sha256 hashes, never keys.
+API_KEYS=""
+PUBLIC_HOST="localhost"

package/templates/runtime-cloudflare/scripts/migrations.ts

@@ -0,0 +1,43 @@
+/**
+ * Writes migrations/ for D1 from the kit's tables and every feature's steps, one file per step with its kit_migrations
+ * record, so `wrangler d1 migrations apply DB --remote` brings the database up at deploy and `migrate()` finds every
+ * step done at runtime. Files are only added; a step that changed after it was written stops the script (a change is a
+ * new step at the end of the feature's list). Run `wrangler d1 migrations apply` before the first `wrangler dev`: a step
+ * `migrate()` already ran is replayed, and only `create … if not exists` steps replay cleanly.
+ */
+import { createHash } from 'node:crypto'
+import { mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { FEATURES } from '../src/features/index.js'
+import { GUARD_MIGRATIONS, OAUTH_MIGRATIONS } from '../src/kit/index.js'
+
+const dir = fileURLToPath(new URL('../migrations', import.meta.url))
+const sets: [string, readonly string[]][] = [['oauth', OAUTH_MIGRATIONS], ['guards', GUARD_MIGRATIONS], ...FEATURES.map((feature): [string, readonly string[]] => [feature.name, feature.migrations])]
+const sha = (text: string) => createHash('sha256').update(text).digest('hex')
+const HEADER = /^-- kit: (\S+) step (\d+) sha256 ([0-9a-f]{64})$/m
+
+mkdirSync(dir, { recursive: true })
+const files = readdirSync(dir).filter((file) => file.endsWith('.sql')).sort()
+const written = new Map(files.flatMap((file) => {
+  const match = readFileSync(join(dir, file), 'utf8').match(HEADER)
+  return match ? [[`${match[1]} ${match[2]}`, { file, hash: match[3] }] as const] : []
+}))
+let next = files.length
+const write = (name: string, text: string) => writeFileSync(join(dir, `${String(next++).padStart(4, '0')}_${name}.sql`), text)
+
+if (!files.length) write('kit_migrations', 'create table if not exists kit_migrations (feature text not null, step integer not null, applied_at text not null, primary key (feature, step));\n')
+let added = 0
+for (const [feature, steps] of sets)
+  for (const [index, step] of steps.entries()) {
+    const shipped = written.get(`${feature} ${index + 1}`)
+    if (shipped) {
+      if (shipped.hash !== sha(step)) throw new Error(`${feature} step ${index + 1} changed after ${shipped.file} was written; shipped steps never change, add a new step instead`)
+      continue
+    }
+    // `or ignore`: in local dev `migrate()` may have run the step and recorded it first
+    const record = `insert or ignore into kit_migrations (feature, step, applied_at) values ('${feature}', ${index + 1}, strftime('%Y-%m-%dT%H:%M:%fZ', 'now'));`
+    write(`${feature}_${index + 1}`, `-- kit: ${feature} step ${index + 1} sha256 ${sha(step)}\n${step.trim().replace(/;?$/, ';')}\n${record}\n`)
+    added++
+  }
+console.log(added ? `Wrote ${added} migration files to migrations/` : 'migrations/ is current')

package/templates/runtime-cloudflare/src/worker.ts

@@ -0,0 +1,19 @@
+/**
+ * __title__ on Cloudflare Workers: the D1 binding through Drizzle, then the same `createApp` as on Node. The app is built
+ * on the first request of each isolate (Workers allow no I/O or random values at global scope) and kept for the next.
+ */
+import { drizzle } from 'drizzle-orm/d1'
+import { createApp, type Env } from './app.js'
+import { openDb, type Db } from './kit/index.js'
+
+type Bindings = Env & { DB: D1Database }
+
+let ready: ReturnType<typeof createApp> | undefined
+
+export default {
+  fetch: (request, env, ctx) =>
+    (ready ??= openDb(drizzle(env.DB) as unknown as Db).then((db) => createApp({ db, env })).catch((error) => {
+      ready = undefined
+      throw error
+    })).then((app) => app.fetch(request, env, ctx)),
+} satisfies ExportedHandler<Bindings>

package/templates/runtime-cloudflare/test/workers/api.test.ts

@@ -0,0 +1,37 @@
+import { exports } from 'cloudflare:workers'
+import { describe, expect, it } from 'vitest'
+import { TEST_KEY } from './key.js'
+
+const headers = { authorization: `Bearer ${TEST_KEY}`, 'content-type': 'application/json' }
+
+// worker.ts in workerd over D1, brought up by migrations/: what a deploy runs
+describe('__title__ on Workers', () => {
+  it('starts and serves the standard routes and the guide', async () => {
+    for (const path of ['/api/health', '/openapi.json', '/llms.txt', '/.well-known/api-catalog']) expect((await exports.default.fetch(`https://api.test${path}`, { headers })).status, path).toBe(200)
+  })
+
+  it('answers every feature list route with a key, and refuses without one', async () => {
+    const doc = (await (await exports.default.fetch('https://api.test/openapi.json', { headers })).json()) as { paths: Record<string, { get?: unknown }> }
+    const lists = Object.keys(doc.paths).filter((path) => path.startsWith('/api/') && path !== '/api/health' && !path.includes('{') && doc.paths[path]!.get)
+    expect(lists.length).toBeGreaterThan(0)
+    for (const path of lists) {
+      expect((await exports.default.fetch(`https://api.test${path}`, { headers })).status, path).toBe(200)
+      expect((await exports.default.fetch(`https://api.test${path}`)).status, path).toBe(401)
+    }
+  })
+
+  it('serves MCP: lists the tools and calls one through its route', async () => {
+    const meta = { 'io.modelcontextprotocol/protocolVersion': '2026-07-28', 'io.modelcontextprotocol/clientCapabilities': {} }
+    const rpc = (method: string, params: Record<string, unknown> = {}) =>
+      exports.default.fetch('https://api.test/mcp', {
+        method: 'POST',
+        headers: { ...headers, accept: 'application/json, text/event-stream', 'mcp-protocol-version': '2026-07-28', 'mcp-method': method, ...(method === 'tools/call' ? { 'mcp-name': String(params.name) } : {}) },
+        body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params: { ...params, _meta: meta } }),
+      })
+    const list = (await (await rpc('tools/list')).json()) as { result: { tools: { name: string; inputSchema: { required?: string[] } }[] } }
+    expect(list.result.tools.length).toBeGreaterThan(0)
+    const tool = list.result.tools.find((candidate) => !candidate.inputSchema.required?.length)!
+    const called = (await (await rpc('tools/call', { name: tool.name, arguments: {} })).json()) as { result: { isError?: boolean } }
+    expect(called.result.isError ?? false, tool.name).toBe(false)
+  })
+})

package/templates/runtime-cloudflare/test/workers/apply-migrations.ts

@@ -0,0 +1,5 @@
+import { applyD1Migrations } from 'cloudflare:test'
+import { env } from 'cloudflare:workers'
+
+// The same files a deploy applies; applying them twice is a no-op
+await applyD1Migrations(env.DB, env.TEST_MIGRATIONS)

package/templates/runtime-cloudflare/test/workers/env.d.ts

@@ -0,0 +1,11 @@
+declare namespace Cloudflare {
+  // Types `exports.default` in the tests as this app's worker
+  interface GlobalProps {
+    mainModule: typeof import('../../src/worker.js')
+  }
+  interface Env {
+    DB: D1Database
+    API_KEYS: string
+    TEST_MIGRATIONS: import('cloudflare:test').D1Migration[]
+  }
+}

package/templates/runtime-cloudflare/test/workers/key.ts

@@ -0,0 +1,2 @@
+/** The API key the workerd tests use; vitest.config.ts puts its hash in API_KEYS. */
+export const TEST_KEY = 'workers-test-key'

package/templates/runtime-cloudflare/test/workers/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "$comment": "src/worker.ts and the workerd tests: Workers types, with Node's for what nodejs_compat provides",
+  "extends": "../../tsconfig.json",
+  "compilerOptions": { "types": ["@cloudflare/workers-types", "@cloudflare/vitest-plugin/types", "node"] },
+  "include": ["./**/*.ts", "../../src/**/*.ts"],
+  "exclude": ["../../src/server.ts", "../../src/**/*.test.ts"]
+}

package/templates/runtime-cloudflare/vitest.config.ts

@@ -0,0 +1,23 @@
+import { createHash } from 'node:crypto'
+import { cloudflareTest, readD1Migrations } from '@cloudflare/vitest-plugin'
+import { defineConfig } from 'vitest/config'
+import { TEST_KEY } from './test/workers/key.js'
+
+// Two projects, one app: `node` runs every test on Node; `workers` runs test/workers inside workerd, over D1 brought
+// up by the files in migrations/ (`pnpm migrations` writes them)
+export default defineConfig(async () => ({
+  test: {
+    projects: [
+      { test: { name: 'node', include: ['src/**/*.test.ts', 'test/**/*.test.ts'], exclude: ['test/workers/**', '**/node_modules/**'] } },
+      {
+        plugins: [
+          cloudflareTest({
+            wrangler: { configPath: './wrangler.jsonc' },
+            miniflare: { bindings: { API_KEYS: `tester:${createHash('sha256').update(TEST_KEY).digest('hex')}`, TEST_MIGRATIONS: await readD1Migrations('./migrations') } },
+          }),
+        ],
+        test: { name: 'workers', include: ['test/workers/**/*.test.ts'], setupFiles: ['./test/workers/apply-migrations.ts'] },
+      },
+    ],
+  },
+}))

package/templates/runtime-cloudflare/wrangler.jsonc

@@ -0,0 +1,16 @@
+// __title__ on Cloudflare Workers. Secrets (API_KEYS, OAUTH_SIGNING_KEY) go in with `wrangler secret put`, locally in
+// .dev.vars (git-ignored; copy .dev.vars.example). Before the first deploy: pin account_id (wrangler's login may be
+// another account), `wrangler d1 create __name__` and put its id below.
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "__name__",
+  "main": "src/worker.ts",
+  // "account_id": "<the Cloudflare account this deploys to>",
+  "compatibility_date": "__date__",
+  "compatibility_flags": ["nodejs_compat"],
+  "observability": { "enabled": true },
+  "d1_databases": [
+    // migrations/ is written by `pnpm migrations` from every feature's steps and applied at deploy
+    { "binding": "DB", "database_name": "__name__", "database_id": "00000000-0000-0000-0000-000000000000", "migrations_dir": "migrations" }
+  ]
+}