@escalay/kit 0.0.0-stage → 1.7.0

package/src/vectors/index.ts

@@ -0,0 +1,326 @@
+/**
+ * Embeddings and vector search as apps built on the kit share them. Gemini Embedding 2 (through OpenRouter) puts text and
+ * images in one 768-dimension space, so an item gets up to two vectors:
+ *   look     its picture, flattened onto white at most 384 px: "looks like this", search by a pasted image
+ *   meaning  its words in Gemini's document format: what it shows and is about
+ * and a query, typed or pasted, is compared against either. Vectors come back unit length: a dot product is the cosine.
+ *
+ * A paid call is never lost: `embedMissing` appends each batch to an append-only JSONL ledger the moment it returns,
+ * keyed by a hash of model, size and content, so a crash, a rerun or another machine pays only for what changed. A
+ * 402/403 from OpenRouter (the key's cap or the account's credit) is a `SpendCapError` that stops the run.
+ *
+ * Plain fetch for texts and images alike: the AI SDK's embed() takes strings only.
+ *
+ * @example
+ * const embedder = createEmbedder({ apiKey: process.env.OPENROUTER_API_KEY! })
+ * await embedMissing({ file: 'vectors/meaning.jsonl', items: notes.map((note) => ({ key: note.id, content: documentText(note.client, [note.industry]) })), embed: embedder.documents })
+ * const meaning = vectorSpace(await readLedger('vectors/meaning.jsonl'))
+ * standouts(meaning, await embedder.query('a fox made of triangles'), { limit: 24 })
+ */
+import { createHash } from 'node:crypto'
+import { appendFile, readFile } from 'node:fs/promises'
+
+export const EMBEDDING_MODEL = 'google/gemini-embedding-2'
+export const DIMENSIONS = 768
+export const IMAGE_PX = 384
+/** The least a row must stand out (standard deviations above the query's mean) to count as a match; see `standouts`. */
+export const MIN_Z = 3.5
+
+const ENDPOINT = 'https://openrouter.ai/api/v1/embeddings'
+// Gemini's batchEmbedContents limit for texts; images are heavier per request
+const TEXTS_PER_REQUEST = 100
+const IMAGES_PER_REQUEST = 32
+const RETRY_ON = /\b(408|429|5\d\d)\b|fetch failed|ECONNRESET|ETIMEDOUT|terminated/
+
+/** OpenRouter refused for money: the key's own cap or the account's credit ran out. Stops a build; a route answers 503. */
+export class SpendCapError extends Error {}
+
+/** A text, or an image as a data URL (`imageDataUrl`). */
+export type EmbeddingInput = string | { image: string }
+export type Embedded = { vectors: Float32Array[]; tokens: number; cost: number }
+export type LedgerLine = { key: string; hash: string; vector: string }
+export type VectorSpace = { keys: string[]; matrix: Float32Array; rowOf: Map<string, number> }
+export type Match = { key: string; score: number }
+
+/**
+ * A document in the format Gemini Embedding 2 reads (it has no task type; it reads these prefixes). Empty parts drop.
+ *
+ * @example
+ * documentText('Doctor with a patient', ['A consultation.', 'Category: Medical']) // 'title: Doctor with a patient | text: A consultation.. Category: Medical'
+ */
+export const documentText = (title: string, parts: (string | null | undefined | false)[]) => `title: ${title} | text: ${parts.filter(Boolean).join('. ')}`
+
+/** A search in Gemini's query format. @example queryText(' dark mode ') // 'task: search result | query: dark mode' */
+export const queryText = (query: string) => `task: search result | query: ${query.trim()}`
+
+/** Changes with the content, the model or the size, so the ledger re-embeds exactly what went stale. @example hashOf(documentText(…)) */
+export const hashOf = (content: string | Uint8Array) => createHash('sha256').update(`${EMBEDDING_MODEL}|${DIMENSIONS}|`).update(content).digest('hex').slice(0, 16)
+
+/**
+ * Any image → the JPEG data URL a look vector is made from: at most 384 px (258 tokens), transparency on white. Loads
+ * `sharp` on first use, so an app that embeds only text never needs it.
+ *
+ * @example
+ * await imageDataUrl(pngBuffer)
+ */
+export const imageDataUrl = async (input: Uint8Array | string) => {
+  const { default: sharp } = await import('sharp')
+  const jpeg = await sharp(input).resize(IMAGE_PX, IMAGE_PX, { fit: 'inside', withoutEnlargement: true }).flatten({ background: '#ffffff' }).jpeg({ quality: 85 }).toBuffer()
+  return `data:image/jpeg;base64,${jpeg.toString('base64')}`
+}
+
+const toUnitVector = (values: ArrayLike<number>) => {
+  const vector = Float32Array.from(values)
+  let length = 0
+  for (const value of vector) length += value * value
+  length = Math.sqrt(length) || 1
+  return vector.map((value) => value / length)
+}
+
+/** A vector as the ledger stores it, and back. @example decodeVector(encodeVector(v)) */
+export const encodeVector = (vector: Float32Array) => Buffer.from(vector.buffer, vector.byteOffset, vector.byteLength).toString('base64')
+export const decodeVector = (base64: string) => {
+  const bytes = Buffer.from(base64, 'base64')
+  return new Float32Array(bytes.buffer, bytes.byteOffset, bytes.byteLength / 4)
+}
+
+const withRetries = async <T>(attempt: () => Promise<T>, tries = 6): Promise<T> => {
+  for (let n = 1; ; n++) {
+    try {
+      return await attempt()
+    } catch (error) {
+      if (error instanceof SpendCapError || n >= tries || !RETRY_ON.test(String(error))) throw error
+      await new Promise((resolve) => setTimeout(resolve, Math.min(60_000, 2 ** n * 500)))
+    }
+  }
+}
+
+/**
+ * One OpenRouter request: inputs → unit vectors in order, with what it says it cost. Retries rate limits and server
+ * errors with backoff; throws `SpendCapError` on 402/403.
+ *
+ * @example
+ * const { vectors, cost } = await embedRequest(key, [queryText('soup'), { image: await imageDataUrl(png) }])
+ */
+export const embedRequest = (apiKey: string, inputs: EmbeddingInput[], fetchImpl: typeof fetch = fetch): Promise<Embedded> =>
+  withRetries(async () => {
+    const response = await fetchImpl(ENDPOINT, {
+      method: 'POST',
+      headers: { authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' },
+      body: JSON.stringify({ model: EMBEDDING_MODEL, dimensions: DIMENSIONS, input: inputs.map((input) => (typeof input === 'string' ? input : { content: [{ type: 'image_url', image_url: { url: input.image } }] })) }),
+    })
+    const body = (await response.json().catch(() => ({}))) as { data?: { index: number; embedding: number[] }[]; usage?: { prompt_tokens?: number; cost?: number }; error?: { message?: string } }
+    if (response.status === 402 || response.status === 403) throw new SpendCapError(`OpenRouter ${response.status}: ${body.error?.message ?? 'refused'}`)
+    if (!response.ok || body.data?.length !== inputs.length) throw new Error(`OpenRouter ${response.status}: ${body.error?.message ?? `${body.data?.length ?? 0} of ${inputs.length} embeddings`}`)
+    return { vectors: [...body.data].sort((a, b) => a.index - b.index).map((item) => toUnitVector(item.embedding)), tokens: body.usage?.prompt_tokens ?? 0, cost: body.usage?.cost ?? 0 }
+  })
+
+const inBatches = async (apiKey: string, fetchImpl: typeof fetch, inputs: EmbeddingInput[], size: number): Promise<Embedded> => {
+  const batches = await Promise.all(Array.from({ length: Math.ceil(inputs.length / size) }, (_, n) => embedRequest(apiKey, inputs.slice(n * size, (n + 1) * size), fetchImpl)))
+  return { vectors: batches.flatMap((batch) => batch.vectors), tokens: batches.reduce((sum, batch) => sum + batch.tokens, 0), cost: batches.reduce((sum, batch) => sum + batch.cost, 0) }
+}
+
+/**
+ * The embedder an app holds: documents and images in batches for a build, and queries (typed or a picture) for a
+ * search, each cached (the last `cacheSize`) so a repeated query costs nothing.
+ *
+ * @example
+ * const embedder = createEmbedder({ apiKey: env.OPENROUTER_API_KEY })
+ * await embedder.query('a lettermark with negative space') // Float32Array(768)
+ * await embedder.image(await imageDataUrl(upload))         // a picture as a query
+ */
+export const createEmbedder = ({ apiKey, fetchImpl = fetch, cacheSize = 500 }: { apiKey: string; fetchImpl?: typeof fetch; cacheSize?: number }) => {
+  const cache = new Map<string, Float32Array>()
+  const cached = async (id: string, input: EmbeddingInput) => {
+    const hit = cache.get(id)
+    if (hit) return hit
+    const [vector] = (await embedRequest(apiKey, [input], fetchImpl)).vectors
+    if (cache.size >= cacheSize) cache.delete(cache.keys().next().value!)
+    cache.set(id, vector!)
+    return vector!
+  }
+  return {
+    /** Documents (`documentText`) → vectors in order, 100 per request. */
+    documents: (texts: string[]) => inBatches(apiKey, fetchImpl, texts, TEXTS_PER_REQUEST),
+    /** Image data URLs → vectors in order, 32 per request. */
+    images: (dataUrls: string[]) => inBatches(apiKey, fetchImpl, dataUrls.map((image) => ({ image })), IMAGES_PER_REQUEST),
+    /** A typed search in Gemini's query format; case and spacing don't make a new call. */
+    query: (query: string) => cached(`q:${query.trim().toLowerCase()}`, queryText(query.trim().toLowerCase())),
+    /** A picture as a query (`imageDataUrl` first). */
+    image: (dataUrl: string) => cached(`i:${hashOf(dataUrl)}`, { image: dataUrl }),
+  }
+}
+
+export type Embedder = ReturnType<typeof createEmbedder>
+
+// ---- Ledgers: one JSONL per space, append-only, the last line per key wins ----
+
+/** A space's ledger by key; a missing file is an empty ledger. @example const ledger = await readLedger('vectors/look.jsonl') */
+export const readLedger = async (file: string): Promise<Map<string, LedgerLine>> => {
+  const text = await readFile(file, 'utf8').catch(() => '')
+  return new Map(text.split('\n').filter(Boolean).map((line) => JSON.parse(line) as LedgerLine).map((line) => [line.key, line]))
+}
+
+/** Adds lines to a ledger; never rewrites it. @example await appendLedger(file, [{ key, hash, vector: encodeVector(v) }]) */
+export const appendLedger = (file: string, lines: LedgerLine[]) => appendFile(file, lines.map((line) => `${JSON.stringify(line)}\n`).join(''))
+
+export type LedgerItem = {
+  key: string
+  /** What the vector is made from: a document's text, or an image's bytes. Its hash decides whether it is stale. */
+  content: string | Uint8Array
+  /** What to send, when it differs from `content` (an image's data URL); made only for stale items. */
+  input?: () => EmbeddingInput | Promise<EmbeddingInput>
+}
+
+export type EmbedRun = { embedded: number; fresh: number; failed: string[]; tokens: number; cost: number; stopped?: 'budget' | 'spend cap' }
+
+/**
+ * Embeds the items whose vectors are missing or stale and appends each batch to the ledger as soon as it returns, so
+ * nothing paid for is lost. Starts no new batch once `budget` (USD, as OpenRouter reports it) is spent, and stops on a
+ * `SpendCapError`; a rerun picks up where it stopped. `limit` embeds at most that many (a pilot). An item whose input
+ * can't be made (a picture that won't render) is skipped and named in `failed`; the rest of its batch still goes.
+ *
+ * @example
+ * await embedMissing({ file: 'vectors/look.jsonl', items: notes.map((l) => ({ key: l.id, content: l.svg, input: async () => ({ image: await imageDataUrl(l.png) }) })), embed: (inputs) => embedRequest(key, inputs), batchSize: 32, budget: 2, limit: 200 })
+ */
+export const embedMissing = async ({ file, items, embed, batchSize = 100, concurrency = 4, budget = Infinity, limit = Infinity, log = () => {} }: { file: string; items: LedgerItem[]; embed: (inputs: EmbeddingInput[]) => Promise<Embedded>; batchSize?: number; concurrency?: number; budget?: number; limit?: number; log?: (message: string) => void }): Promise<EmbedRun> => {
+  const ledger = await readLedger(file)
+  const outdated = items.map((item) => ({ item, hash: hashOf(item.content) })).filter(({ item, hash }) => ledger.get(item.key)?.hash !== hash)
+  const stale = outdated.slice(0, limit)
+  const run: EmbedRun = { embedded: 0, fresh: items.length - outdated.length, failed: [], tokens: 0, cost: 0 }
+  const batches = Array.from({ length: Math.ceil(stale.length / batchSize) }, (_, n) => stale.slice(n * batchSize, (n + 1) * batchSize))
+  let next = 0
+  const worker = async () => {
+    while (next < batches.length && !run.stopped) {
+      if (run.cost >= budget) {
+        run.stopped = 'budget'
+        return
+      }
+      const made = await Promise.allSettled(batches[next++]!.map(async ({ item, hash }) => ({ item, hash, input: await (item.input?.() ?? (typeof item.content === 'string' ? item.content : Promise.reject(new Error(`${item.key}: bytes need an input() that makes the image data URL`)))) })))
+      const batch = made.flatMap((result) => (result.status === 'fulfilled' ? [result.value] : []))
+      for (const result of made)
+        if (result.status === 'rejected') {
+          const reason = String((result.reason as Error)?.message ?? result.reason)
+          run.failed.push(reason)
+          log(`skipped: ${reason}`)
+        }
+      if (!batch.length) continue
+      const inputs = batch.map(({ input }) => input)
+      try {
+        const { vectors, tokens, cost } = await embed(inputs)
+        await appendLedger(file, batch.map(({ item, hash }, n) => ({ key: item.key, hash, vector: encodeVector(vectors[n]!) })))
+        run.embedded += batch.length
+        run.tokens += tokens
+        run.cost += cost
+        log(`${run.embedded}/${stale.length} embedded · ${run.tokens} tokens · $${run.cost.toFixed(4)}`)
+      } catch (error) {
+        if (!(error instanceof SpendCapError)) throw error
+        run.stopped = 'spend cap'
+        log(String(error.message))
+      }
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(concurrency, batches.length) }, worker))
+  return run
+}
+
+// ---- Search ----
+
+/**
+ * A ledger as a searchable matrix; `keep` drops keys no longer in the catalog.
+ *
+ * @example
+ * const look = vectorSpace(await readLedger('vectors/look.jsonl'), (key) => catalog.has(key))
+ */
+export const vectorSpace = (ledger: Map<string, LedgerLine>, keep: (key: string) => boolean = () => true): VectorSpace => {
+  const keys = [...ledger.keys()].filter(keep)
+  const matrix = new Float32Array(keys.length * DIMENSIONS)
+  keys.forEach((key, row) => matrix.set(decodeVector(ledger.get(key)!.vector), row * DIMENSIONS))
+  return { keys, matrix, rowOf: new Map(keys.map((key, row) => [key, row])) }
+}
+
+/** One key's vector, or undefined. @example vectorOf(look, 'note:1') */
+export const vectorOf = (space: VectorSpace, key: string) => {
+  const row = space.rowOf.get(key)
+  return row === undefined ? undefined : space.matrix.subarray(row * DIMENSIONS, (row + 1) * DIMENSIONS)
+}
+
+/** The normalised mean of some rows: a collection's style as one vector. @example centroid(look, pack.keys) */
+export const centroid = (space: VectorSpace, keys: string[]) => {
+  const sum = new Float32Array(DIMENSIONS)
+  for (const key of keys) {
+    const row = vectorOf(space, key)
+    if (row) for (let d = 0; d < DIMENSIONS; d++) sum[d]! += row[d]!
+  }
+  return toUnitVector(sum)
+}
+
+const similarities = (space: VectorSpace, query: Float32Array) => {
+  const scores = new Float32Array(space.keys.length)
+  for (let row = 0, at = 0; row < scores.length; row++) {
+    let sum = 0
+    for (let d = 0; d < DIMENSIONS; d++, at++) sum += space.matrix[at]! * query[d]!
+    scores[row] = sum
+  }
+  return scores
+}
+
+type Pick = { limit: number; keep?: (key: string) => boolean; groupOf?: (key: string) => string; perGroup?: number }
+
+// Sorts only the rows that pass, then caps each group (an app, a pack) so a page isn't one group's items
+const best = (space: VectorSpace, scores: Float32Array, pass: (row: number) => boolean, { limit, keep = () => true, groupOf, perGroup = Infinity }: Pick) => {
+  const rows: number[] = []
+  for (let row = 0; row < scores.length; row++) if (pass(row) && keep(space.keys[row]!)) rows.push(row)
+  rows.sort((a, b) => scores[b]! - scores[a]!)
+  const taken = new Map<string, number>()
+  const picked: number[] = []
+  for (const row of rows) {
+    if (picked.length >= limit) break
+    const group = groupOf?.(space.keys[row]!)
+    if (group !== undefined) {
+      if ((taken.get(group) ?? 0) >= perGroup) continue
+      taken.set(group, (taken.get(group) ?? 0) + 1)
+    }
+    picked.push(row)
+  }
+  return picked
+}
+
+const rounded = (value: number) => Math.round(value * 1000) / 1000
+
+/**
+ * The `limit` rows most like `query` that `keep` allows, best first, at most `perGroup` per `groupOf`. For "similar to
+ * this item", where there is always an answer.
+ *
+ * @example
+ * nearest(look, vectorOf(look, 'note:1')!, { limit: 12, keep: (key) => key !== 'note:1' })
+ */
+export const nearest = (space: VectorSpace, query: Float32Array, pick: Pick): Match[] => {
+  const scores = similarities(space, query)
+  return best(space, scores, () => true, pick).map((row) => ({ key: space.keys[row]!, score: rounded(scores[row]!) }))
+}
+
+/**
+ * The rows that stand out for this query, best first, with how far they stand out (`z`). Gemini's similarities sit in
+ * a narrow band (a nonsense query scored 0.52–0.60 against everything, real matches 0.55–0.71), so no fixed floor
+ * separates them. Scoring every row gives the query's own distribution: a match is `minZ` standard deviations above its
+ * mean. Noise alone reaches about √(2 ln n) among n rows, so the default bar rises with the catalog (3.5 at 552 rows,
+ * 4.12 at 42k, measured on a 42k-row catalogue). `keep` applies after, so a small filtered set can still stand out.
+ * A query matching nothing returns nothing. `minScore` adds a raw-similarity floor for a corpus that is all about one
+ * subject, where everything stands out a little and only the score separates a real match.
+ *
+ * @example
+ * standouts(meaning, await embedder.query('a fox'), { limit: 24, groupOf: (key) => authorOf(key), perGroup: 3 })
+ */
+export const standouts = (space: VectorSpace, query: Float32Array, { minZ, minScore = -Infinity, ...pick }: Pick & { minZ?: number; minScore?: number }): (Match & { z: number })[] => {
+  const scores = similarities(space, query)
+  if (scores.length < 2) return best(space, scores, () => true, pick).map((row) => ({ key: space.keys[row]!, score: rounded(scores[row]!), z: 0 }))
+  let mean = 0
+  for (const score of scores) mean += score / scores.length
+  let variance = 0
+  for (const score of scores) variance += (score - mean) ** 2 / scores.length
+  const deviation = Math.sqrt(variance) || 1
+  const bar = minZ ?? Math.max(MIN_Z, Math.sqrt(2 * Math.log(scores.length)) - 0.5)
+  const floor = Math.max(mean + bar * deviation, minScore)
+  return best(space, scores, (row) => scores[row]! >= floor, pick).map((row) => ({ key: space.keys[row]!, score: rounded(scores[row]!), z: rounded((scores[row]! - mean) / deviation) }))
+}

package/src/web/README.md

@@ -0,0 +1,21 @@
+# web
+
+The front door: an app's own web pages served by the API. An optional public page at `/`, the browser app under
+`/app` behind the sign-in, old addresses redirected, and hashed assets cached for good.
+
+Needs: `core`, `@hono/node-server`.
+
+```ts
+import { frontDoorOpen, serveFrontDoor } from './kit/index.js'
+
+const web = { dir: join(APP_DIR, 'web/dist'), private: true }
+const app = createAgentApi({ …, auth: { …, open: frontDoorOpen(web) } })   // the pages' files carry no data
+// … routes, guide, MCP …
+serveFrontDoor(app, web)                                                    // last: it answers what nothing else did
+```
+
+## Rules
+
+- Register it last. Vite's hashed `/assets/` are served unversioned (a `?v=` on them loads each module twice).
+- In private mode `/` redirects to `/app` and nothing public names the service.
+- Not to be confused with the browser modules (`browser/`), which go into the frontend.

package/src/web/index.ts

@@ -0,0 +1,100 @@
+/**
+ * A browser app on the API's own origin, with a public front page in front of it:
+ *   /              `landing.html`: what the service is and how agents connect (no data), so scanners and agents find
+ *                  the discovery files; `Accept: text/markdown` still gets the agent guide (the kit answers it first)
+ *   /app, /app/*   the app: a file of that name when there is one, else `index.html`, so deep links open the app
+ *   moved paths    the app's addresses from before it moved under /app, and `/?query` deep links, redirect there
+ * Files at the top of `dir` (the landing's script and styles, a plain viewer's `app.js`) are served as they are.
+ * Single sign-on gates only `/app` (the only paths Access covers, with the OAuth approval pages); the app's data calls carry its cookie, so the browser never
+ * holds an API key. `frontDoorOpen` lists what the API's auth must leave open: the page files, never data.
+ *
+ * The pages' own scripts and stylesheets are linked with `?v=<content hash>`, so a CDN or browser that keeps static
+ * files for hours (Cloudflare's browser TTL overrides `no-cache`) still loads the new ones after a deploy. Hashed build
+ * output (`immutable`) keeps its plain name: its chunks import each other by that name, and a second URL for the same
+ * module would load it twice (two React Query clients, two routers).
+ *
+ * Call `serveFrontDoor` last, after every API route: anything they didn't answer is a page.
+ *
+ * @example
+ * const web = { dir: join(APP_DIR, 'public'), moved: ['/notes'] }
+ * const app = createAgentApi({ …, home: false, auth: { …, open: frontDoorOpen(web) } })
+ * serveFrontDoor(app, web)
+ */
+import { createHash } from 'node:crypto'
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { serveStatic } from '@hono/node-server/serve-static'
+import type { Hono } from 'hono'
+
+export type FrontDoorConfig = {
+  /** The built app: `index.html`, optionally `landing.html`, and its files. */
+  dir: string
+  /** Where the app lives (default `/app`). */
+  base?: string
+  /** Addresses the app answered before it moved under `base`, redirected there with their path and query. */
+  moved?: string[]
+  /** Hashed build output that never changes under its name (default `/assets/`). */
+  immutable?: string
+  /**
+   * Private (with the API's `private`): no front page, `/` goes to the app (behind the sign-in), the app's files need
+   * the same credentials as the API and are never kept in a shared cache, and every page says `noindex`.
+   */
+  private?: boolean
+}
+
+const topFiles = (dir: string) => (existsSync(dir) ? readdirSync(dir).filter((name) => name !== 'index.html' && statSync(join(dir, name)).isFile()) : [])
+
+/**
+ * The paths the API's auth leaves open for the front door: `/`, the files at the top of `dir`, the immutable build
+ * output and the old addresses (they only redirect). `/app` itself stays behind the sign-in.
+ *
+ * @example
+ * auth: { realm: 'notes', keys, access, open: frontDoorOpen({ dir, moved: ['/notes'] }) }
+ */
+export const frontDoorOpen = ({ dir, moved = [], immutable = '/assets/', private: hidden = false }: FrontDoorConfig) =>
+  hidden ? ['/', ...moved.map((prefix) => `${prefix}*`)] : ['/', `${immutable}*`, ...topFiles(dir).map((name) => `/${name}`), ...moved.map((prefix) => `${prefix}*`)]
+
+/**
+ * A page with its local `.js` and `.css` links versioned by content: `src="app.js"` → `src="app.js?v=1a2b3c4d"`. Files
+ * under `immutable` are left as they are (their names are hashes already).
+ *
+ * @example
+ * versionAssets('<script src="app.js"></script>', dir) // '<script src="app.js?v=…"></script>'
+ */
+export const versionAssets = (html: string, dir: string, immutable = '/assets/') =>
+  html.replace(/\b(src|href)="(\/?)([\w./-]+\.(?:js|css))"/g, (match, attribute: string, slash: string, file: string) => {
+    const path = join(dir, file)
+    if (file.includes('..') || `/${file}`.startsWith(immutable) || !existsSync(path)) return match
+    return `${attribute}="${slash}${file}?v=${createHash('sha256').update(readFileSync(path)).digest('hex').slice(0, 8)}"`
+  })
+
+/** Serves the front page, the app under `base` and the redirects; false when `dir` has no `index.html`. @example serveFrontDoor(app, { dir }) */
+export const serveFrontDoor = (app: Hono<any, any, any>, { dir, base = '/app', moved = [], immutable = '/assets/', private: hidden = false }: FrontDoorConfig) => {
+  const index = join(dir, 'index.html')
+  if (!existsSync(index)) return false
+  const noindex = (page: string) => (hidden && !page.includes('name="robots"') ? page.replace(/<head>/i, '<head><meta name="robots" content="noindex, nofollow">') : page)
+  const html = noindex(versionAssets(readFileSync(index, 'utf8'), dir, immutable))
+  const landing = !hidden && existsSync(join(dir, 'landing.html')) ? versionAssets(readFileSync(join(dir, 'landing.html'), 'utf8'), dir, immutable) : null
+
+  app.use(`${immutable}*`, async (c, next) => {
+    await next()
+    if (c.res.ok) c.res.headers.set('cache-control', `${hidden ? 'private' : 'public'}, max-age=31536000, immutable`)
+  })
+  app.get('/', (c) => {
+    // `/?item=…` was a deep link into the app before it moved
+    const search = new URL(c.req.url).search
+    if (search || !landing) return c.redirect(`${base}${search}`, search ? 301 : 302)
+    return c.html(landing, 200, { 'cache-control': 'no-cache' })
+  })
+  // A plain viewer refers to its files relatively, so `/app/app.js` is `/app.js`; `/app` itself is the page below
+  const appFiles = serveStatic({ root: dir, rewriteRequestPath: (path) => path.slice(base.length), onFound: (_path, c) => c.header('cache-control', 'no-cache') })
+  app.use(`${base}/*`, (c, next) => (c.req.path === base || c.req.path === `${base}/` ? next() : appFiles(c, next)))
+  app.use('*', serveStatic({ root: dir, onFound: (path, c) => { if (!path.includes(immutable)) c.header('cache-control', 'no-cache') } }))
+  app.get('*', (c, next) => {
+    const path = c.req.path
+    if (path === base || path.startsWith(`${base}/`)) return c.html(html, 200, { 'cache-control': 'no-cache' })
+    if (moved.some((prefix) => path === prefix || path.startsWith(`${prefix}/`))) return c.redirect(`${base}${path}${new URL(c.req.url).search}`, 301)
+    return next()
+  })
+  return true
+}

package/templates/app/AGENTS.md

@@ -0,0 +1,41 @@
+# __title__
+
+An agent-ready HTTP API built on [api-kit](https://github.com/escalay/api-kit) (the standard: its
+`docs/STANDARD.md`). Every route is documented OpenAPI, every answer HAL, every error problem+json, and every route
+an MCP tool.
+
+## Commands
+
+`pnpm install` · `pnpm test` · `pnpm typecheck` · `pnpm guide` (after editing `guide/`)
+
+- `pnpm dev`: the API on Node at http://localhost:4400 (`/docs`, `/llms.txt`, `/mcp`) <!-- runtime:node -->
+- `pnpm __worker_dev__`: the Worker locally over a local D1 (`/docs`, `/llms.txt`, `/mcp`) <!-- runtime:workers -->
+- `pnpm migrations` after adding a migration step; `pnpm run deploy` (not `pnpm deploy`, which is pnpm's own command): guide, migrations, `wrangler d1 migrations apply`, `wrangler deploy` <!-- runtime:workers -->
+
+A new feature: `npx @escalay/kit feature <plural-name>`, then fill in its files.
+
+## Layout
+
+| Path | What |
+|---|---|
+| `src/server.ts` | Node: env → `openDb` → `createApp` → listen | <!-- runtime:node -->
+| `src/worker.ts`, `wrangler.jsonc` | Workers: the D1 binding → `openDb(drizzle(env.DB))` → the same `createApp`; bindings and secrets | <!-- runtime:workers -->
+| `src/guide.gen.ts` | `guide/` as a module (`pnpm guide`), served the same on both runtimes; a test fails when it is older than `guide/` |
+| `migrations/`, `scripts/migrations.ts` | Workers: one D1 migration file per kit and feature step, written by `pnpm migrations`, applied at deploy | <!-- runtime:workers -->
+| `src/app.ts` | the wiring only: auth and OAuth, every feature, the guide, MCP |
+| `src/features/index.ts` | `FEATURES`, the one list of features, and the `Feature` shape |
+| `src/features/<name>/` | one feature: `schema.ts` (tables + migration steps) · `repo.ts` (the only queries) · `routes.ts` (OpenAPI contracts) · `handlers.ts` (request → repo → HAL) · `tools.ts` (MCP tools) · `index.ts` (register, tools, sample tool arguments) · `<name>.test.ts` |
+| `src/kit/` | the copied kit, owned by this app; `kit.json` records its version, and each part's `README.md` says what it is for and its rules (start with `core`, `db`, `mcp`, `testing`). Update with `diff --patch`, then `update` |
+| `guide/` | the agent guide: templates whose `{{api.endpoints}}` and `{{mcp.tools}}` are generated from the code |
+| `test/api.test.ts` | every route linted, every MCP tool run (`toolsRun`), every guide placeholder filled |
+| `container/entrypoint.sh` | the env allowlist: the API sees only the variables it reads | <!-- runtime:node -->
+
+## Rules
+
+- Only a feature's `repo.ts` queries the database; handlers call the repo. That keeps a move off SQLite to one file
+  per feature (`openDb` takes any Drizzle SQLite database: Turso via `drizzle-orm/libsql`, D1 via `drizzle(env.DB)`).
+- A migration step never changes once it has run anywhere; a change is a new step at the end of the list.
+- On Workers, run `pnpm migrations` after adding a step (it refuses to rewrite a shipped one). On a fresh local D1, `wrangler d1 migrations apply DB --local` before the first `wrangler dev`: files replayed over steps `migrate()` already ran must be idempotent. <!-- runtime:workers -->
+- Nothing runs at global scope that Workers refuse there (random values, I/O, timers): do it in `createApp` or a handler. <!-- runtime:workers -->
+- A new secret: `wrangler secret put <NAME>`, and locally `.dev.vars` (copy `.dev.vars.example`). <!-- runtime:workers -->
+- A new env var the API reads goes into `container/entrypoint.sh` too. <!-- runtime:node -->

package/templates/app/CLAUDE.md

@@ -0,0 +1,3 @@
+# __title__
+
+@AGENTS.md

package/templates/app/Dockerfile

@@ -0,0 +1,12 @@
+FROM node:22-alpine
+WORKDIR /app
+RUN corepack enable
+COPY package.json pnpm-lock.yaml* ./
+RUN pnpm install --prod
+COPY src src
+COPY guide guide
+COPY container container
+ENV PORT=80 STATE_DIR=/state
+EXPOSE 80
+HEALTHCHECK CMD wget -qO- http://127.0.0.1/api/health || exit 1
+ENTRYPOINT ["/app/container/entrypoint.sh"]

package/templates/app/container/entrypoint.sh

@@ -0,0 +1,7 @@
+#!/bin/sh
+# The API gets only the env it reads, never the platform's whole .env
+set -e
+exec env -i PATH="$PATH" HOME="${HOME:-/root}" ${PORT:+PORT="$PORT"} ${STATE_DIR:+STATE_DIR="$STATE_DIR"} ${DATABASE_FILE:+DATABASE_FILE="$DATABASE_FILE"} \
+  ${API_KEYS:+API_KEYS="$API_KEYS"} ${OAUTH_SIGNING_KEY:+OAUTH_SIGNING_KEY="$OAUTH_SIGNING_KEY"} ${ACCESS_TEAM:+ACCESS_TEAM="$ACCESS_TEAM"} \
+  ${ACCESS_AUD:+ACCESS_AUD="$ACCESS_AUD"} ${PUBLIC_HOST:+PUBLIC_HOST="$PUBLIC_HOST"} \
+  node_modules/.bin/tsx src/server.ts

package/templates/app/gitignore

@@ -0,0 +1,4 @@
+node_modules/
+.state/
+.wrangler/
+.dev.vars

package/templates/app/guide/llms.txt

@@ -0,0 +1,11 @@
+# __title__
+
+> __title__: an agent-ready API. Send `Authorization: Bearer <key>` on every call; MCP clients connect to `/mcp`.
+
+## Endpoints
+
+{{api.endpoints}}
+
+## MCP tools
+
+{{mcp.tools}}

package/templates/app/pnpm-workspace.yaml

@@ -0,0 +1,5 @@
+# Packages that ship prebuilt binaries as optional packages: nothing to build, so pnpm skips their scripts
+allowBuilds:
+  esbuild: false
+  workerd: false
+  sharp: false

package/templates/app/scripts/guide.ts

@@ -0,0 +1,8 @@
+/** Writes src/guide.gen.ts from guide/: the guide as a module, served the same on Node and on Workers. Run after editing guide/. */
+import { writeFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { guideFiles, guideModuleSource } from '../src/kit/index.js'
+
+const files = guideFiles(fileURLToPath(new URL('../guide', import.meta.url)))
+writeFileSync(new URL('../src/guide.gen.ts', import.meta.url), guideModuleSource(files))
+console.log(`Wrote ${files.size} guide files to src/guide.gen.ts`)

package/templates/app/src/app.ts

@@ -0,0 +1,39 @@
+/**
+ * __title__: the kit's agent-ready API with this app's features on it. Each feature in `features/` brings its routes,
+ * tables and MCP tools; this file only wires them: auth and OAuth, every feature, the agent guide, MCP.
+ *
+ * The same on every runtime: `server.ts` (Node) and `worker.ts` (Cloudflare Workers) each open the database and call it.
+ *
+ * @example
+ * const app = await createApp({ db: await openDb('file:.state/state.sqlite'), env: process.env })
+ */
+import { FEATURES } from './features/index.js'
+import { GUIDE_FILES } from './guide.gen.js'
+import { accessOwner, createAgentApi, createOAuth, dbGuardStore, dbOAuthStore, parseApiKeys, serveGuide, type Db } from './kit/index.js'
+import { inProcess, mcpServerFactory, mountMcp } from './kit/mcp/index.js'
+
+export type Env = { API_KEYS?: string; OAUTH_SIGNING_KEY?: string; ACCESS_TEAM?: string; ACCESS_AUD?: string; PUBLIC_HOST?: string }
+
+export const VERSION = '0.1.0'
+export const TOOLS = FEATURES.flatMap((feature) => feature.tools)
+
+export const createApp = async ({ db, env }: { db: Db; env: Env }) => {
+  const access = env.ACCESS_TEAM && env.ACCESS_AUD ? { team: env.ACCESS_TEAM, audience: env.ACCESS_AUD } : undefined
+  const oauth = env.OAUTH_SIGNING_KEY ? createOAuth({ name: '__title__', signingKey: env.OAUTH_SIGNING_KEY, store: await dbOAuthStore(db), owner: access ? accessOwner(access) : async () => null }) : undefined
+  const app = createAgentApi({
+    title: '__title__',
+    version: VERSION,
+    description: ['__title__.', '', '- **Auth:** `Authorization: Bearer <key>`, or an OAuth token the owner approves.', '- **Agent guide:** [/llms.txt](/llms.txt). **MCP:** `/mcp`.'].join('\n'),
+    tags: FEATURES.map((feature) => feature.tag),
+    auth: { realm: '__name__', keys: parseApiKeys(env.API_KEYS), access },
+    oauth,
+    // In the database, so every instance (each Worker isolate) shares Idempotency-Key answers
+    guards: { store: await dbGuardStore(db) },
+  })
+  for (const feature of FEATURES) await feature.register(app, { db })
+  // guide/ as a module (`pnpm guide` writes it), so it serves the same on Workers, which can't read a folder
+  serveGuide(app, { files: GUIDE_FILES, vars: () => ({}), full: ['llms.txt'] })
+  const factory = mcpServerFactory({ info: { name: '__name__', title: '__title__', version: VERSION }, instructions: '__title__: read the guide at /llms.txt first.', tools: TOOLS, callApi: inProcess(app) })
+  mountMcp(app, { factory, allowedHostnames: [env.PUBLIC_HOST ?? 'localhost', 'localhost', '127.0.0.1'] })
+  return app
+}

package/templates/app/src/features/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Every feature of the app, one folder each (`kit feature <name>` makes one and lists it here):
+ *   schema.ts    Drizzle tables + the SQL migration steps
+ *   repo.ts      the only file with queries
+ *   routes.ts    OpenAPI contracts (createRoute)
+ *   handlers.ts  request → repo → HAL answer, errors as problems
+ *   tools.ts     MCP tools over the routes
+ *   index.ts     the feature: register, tools, sample tool arguments for the tests
+ */
+import type { OpenAPIHono } from '@hono/zod-openapi'
+import type { Db } from '../kit/index.js'
+import type { McpTool } from '../kit/mcp/index.js'
+// kit:imports
+
+export type Feature = {
+  name: string
+  /** The OpenAPI tag its routes carry. */
+  tag: { name: string; description: string }
+  /** Its tables as SQL steps, in order (also written to `migrations/` for D1 by `pnpm migrations`). */
+  migrations: readonly string[]
+  /** Migrates its tables, then registers its routes. */
+  register: (app: OpenAPIHono, context: { db: Db }) => Promise<void>
+  tools: McpTool[]
+  /** Sample arguments for each of its tools (making what they need through the API), for `toolsRun`. */
+  samples: (request: (path: string, init?: RequestInit) => Promise<Response>) => Promise<Record<string, Record<string, unknown>>>
+}
+
+export const FEATURES: Feature[] = [
+  // kit:features
+]

package/templates/app/src/server.ts

@@ -0,0 +1,14 @@
+/** Starts __title__: opens the database, builds the app, listens on PORT. */
+import { mkdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { serve } from '@hono/node-server'
+import { createApp } from './app.js'
+import { openDb } from './kit/index.js'
+
+const stateDir = process.env.STATE_DIR ?? '.state'
+mkdirSync(stateDir, { recursive: true })
+// A node:sqlite file by default; to move to Turso or D1, open its Drizzle database here and pass it in
+const db = await openDb(process.env.DATABASE_FILE ?? `file:${join(stateDir, 'state.sqlite')}`)
+const app = await createApp({ db, env: process.env })
+const port = Number(process.env.PORT ?? 4400)
+serve({ fetch: app.fetch, hostname: '0.0.0.0', port }, (info) => console.log(`__name__ → http://localhost:${info.port} (/docs, /llms.txt, /mcp)`))