acrylblends 0.4.0 → 0.4.1

package/docs/framework/validation.md

@@ -0,0 +1,135 @@
+# Validation
+
+Validate untrusted input at the route boundary. `schemaValidator` takes any [Standard Schema](https://standardschema.dev): Schemastery
+(the schema library Cordis already uses for plugin config), Zod and Valibot all implement it, so a route needs no extra dependency.
+
+## Validate JSON
+
+```ts
+import z from '@deepseek-ai/schemastery'
+import { App } from 'acryl-router'
+import { schemaValidator } from 'acryl-router/helpers'
+
+const NewTodo = z.object({
+  title: z.string().required(),
+  done: z.boolean().default(false),
+})
+
+const app = new App().post('/todos', schemaValidator('json', NewTodo), c => {
+  const todo = c.req.valid('json')   // typed by the schema's output
+  return c.json({ todo }, 201)
+})
+```
+
+A validated route has three parts: a schema for one input target, the validator middleware for that target, and a handler that reads
+`c.req.valid(target)` instead of the raw body.
+
+## Failures
+
+When the schema reports issues the handler does not run and the answer is 400 with `Content-Type: application/json` and exactly this
+shape:
+
+```ts
+{ error: `invalid ${target}`, issues: Array<{ message: string, path: string }> }
+```
+
+```json
+{ "error": "invalid json", "issues": [{ "message": "title must be 1 to 200 characters", "path": "title" }] }
+```
+
+- `error` names the target: `invalid json`, `invalid query`, `invalid param`, ...
+- There is one entry per issue the schema reported, in its order, with the schema's own `message`.
+- `path` is the issue's path joined with dots: `["items", 0, "title"]` becomes `"items.0.title"`, and a path segment given as
+  `{ key }` (as Standard Schema allows) contributes its `key`.
+- An issue without a path, which a hand-written Standard Schema often reports for a whole-value check, gets `"path": ""`.
+  `{ issues: [{ message: 'not allowed' }] }` answers `{ "error": "invalid json", "issues": [{ "message": "not allowed", "path": "" }] }`.
+  Give issues a path when a client should point at a field.
+
+### A JSON body without a JSON content type
+
+A `json` target reads the body only when the request's `Content-Type` is JSON (`application/json`, with or without parameters such as
+`; charset=utf-8`, or `application/*+json`). Any other content type, or none, is not an error by itself: the schema sees `{}`. So a
+client that forgets the header gets a misleading field error for a field it did send:
+
+```sh
+curl -X POST -d '{"title":"milk"}' http://127.0.0.1:<port>/todo/api      # no content type: curl sends a form type
+# 400 {"error":"invalid json","issues":[{"message":"title must be 1 to 200 characters","path":"title"}]}
+```
+
+If you see a field error for a field the request clearly carries, check the request's `Content-Type` first. A route that wants to say so
+explicitly can refuse other content types before the validator:
+
+```ts
+import type { MiddlewareHandler } from 'acryl-router'
+
+const jsonOnly: MiddlewareHandler = async (c, next) => {
+  // The same types the json target reads: application/json and application/*+json, parameters allowed.
+  const type = c.req.header('content-type')?.split(';', 1)[0]?.trim() ?? ''
+  if (!/^application\/([a-z.-]+\+)?json$/i.test(type)) return c.json({ error: 'content type must be JSON' }, 415)
+  await next()
+}
+
+app.post('/todos', jsonOnly, schemaValidator('json', NewTodo), createTodo)
+```
+
+### A body that is not JSON
+
+A JSON content type with a body that does not parse fails before the schema runs: the answer is 400 with the text body
+`Malformed JSON in request body` (a thrown `HTTPException`, so an `onError` handler can reshape it). The `form` target does the same for
+a form body that does not parse, with the text `Malformed FormData request.`
+
+Keep the public failure shape consistent across the application and do not leak internals in messages. An application that needs a
+different body writes its own check with the core `validator` (below). Valid input is not proof that the caller may use it:
+authentication and authorization stay separate checks.
+
+## Targets
+
+| Target | Read from |
+| --- | --- |
+| `json` | the JSON body |
+| `form` | a `multipart/form-data` or `application/x-www-form-urlencoded` body |
+| `query` | the query string |
+| `param` | route parameters |
+| `header` | request headers (names in lowercase) |
+| `cookie` | cookies |
+
+Validate only the targets the route uses, and chain one validator per target:
+
+```ts
+app.get('/todos/:id', schemaValidator('param', z.object({ id: z.natural() })), schemaValidator('query', Paging), handler)
+```
+
+## The core validator
+
+`validator` (also from `acryl-router/helpers`) takes a function instead of a schema. Return the value the handler should see, or a
+response to refuse:
+
+```ts
+import { validator } from 'acryl-router/helpers'
+
+app.post('/posts', validator('form', (value, c) => {
+  const body = value['body']
+  if (typeof body !== 'string') return c.text('Invalid!', 400)
+  return { body }
+}), c => c.json({ body: c.req.valid('form').body }, 201))
+```
+
+## Limit the body first
+
+Validation reads the whole body. Put `bodyLimit` in front of a validator on any route open to untrusted callers:
+
+```ts
+import { bodyLimit } from 'acryl-router/middleware'
+
+app.post('/todos', bodyLimit({ maxSize: 16 * 1024 }), schemaValidator('json', NewTodo), createTodo)
+```
+
+## Typed clients
+
+The validated input types flow into the route types, so the typed `testClient` and `acryl-router/client` check the request a caller sends.
+See [Helpers](./helpers.md#testing).
+
+## What not to validate twice
+
+Validate shape at the HTTP boundary, then enforce domain rules in the domain service. The route checks that `title` is a string; the
+todo service decides whether that title is allowed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acrylblends",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Scaffold Cordis apps: acrylblends init.",
   "license": "MIT",
   "type": "module",
@@ -20,7 +20,9 @@
     "bin",
     "dist",
     "templates",
-    "plugins"
+    "shared",
+    "plugins",
+    "docs"
   ],
   "scripts": {
     "build": "tsdown",

package/plugins/acryl-inspect/src/report.ts

@@ -47,13 +47,19 @@ export interface PluginReport {
 }
 
 const PROVIDE = /^ctx\.provide\("(.+)"\)$/
-const MOUNT = /^acryl-router: route (\S+) \((.*)\)$/
-const SERVED = /^([A-Z]+) (\S+)$/
+const MOUNT = /^acryl-router: route (\S+)$/
+const SERVES = /^acryl-router: serves ([A-Z]+) (\S+)$/
 
 function flatten(effects: readonly EffectLabel[]): string[] {
   return effects.flatMap(effect => [effect.label, ...flatten(effect.children)])
 }
 
+/** A mount's children name the routes it serves; they describe that one registration and are not registrations of their own. */
+function routeOf(label: string): RouteReport | undefined {
+  const served = SERVES.exec(label)
+  return served?.[1] !== undefined && served[2] !== undefined ? { method: served[1], path: served[2] } : undefined
+}
+
 export function stateName(state: number): FiberStateName {
   return STATE_NAMES[state] ?? 'FAILED'
 }
@@ -78,17 +84,16 @@ export function reportFiber(fiber: FiberView, adopted: readonly FiberView[] = []
   const routes: RouteReport[] = []
   const other: string[] = []
   const labels = [fiber, ...adopted].flatMap(source => flatten(source.getEffects()))
+  let registrations = 0
   for (const label of labels) {
     const provided = PROVIDE.exec(label)
     const mount = MOUNT.exec(label)
+    const route = routeOf(label)
+    if (route !== undefined) { routes.push(route); continue }
+    registrations += 1
     if (provided?.[1] !== undefined) provides.push(provided[1])
-    else if (mount?.[1] !== undefined) {
-      mounts.push(mount[1])
-      for (const entry of (mount[2] ?? '').split(', ')) {
-        const served = SERVED.exec(entry)
-        if (served?.[1] !== undefined && served[2] !== undefined) routes.push({ method: served[1], path: served[2] })
-      }
-    } else other.push(label)
+    else if (mount?.[1] !== undefined) mounts.push(mount[1])
+    else other.push(label)
   }
   return {
     name: isNamed(fiber) ? fiber.runtime?.name ?? 'anonymous' : 'anonymous',
@@ -98,7 +103,7 @@ export function reportFiber(fiber: FiberView, adopted: readonly FiberView[] = []
     mounts,
     routes,
     other,
-    removedOnUnload: labels.length,
+    removedOnUnload: registrations,
   }
 }
 

package/plugins/acryl-inspect/tests/report.spec.ts

@@ -12,8 +12,14 @@ describe('reportFiber', () => {
       inject: { router: null, acrylSettings: null },
       effects: [
         { label: 'ctx.provide("things")', children: [] },
-        { label: 'acryl-router: route /api (ALL /api/*, GET /api/things/:id)', children: [] },
-        { label: 'acryl-router: route /api/things (POST /api/things)', children: [{ label: 'inner timer', children: [] }] },
+        { label: 'acryl-router: route /api', children: [
+          { label: 'acryl-router: serves ALL /api/*', children: [] },
+          { label: 'acryl-router: serves GET /api/things/:id', children: [] },
+        ] },
+        { label: 'acryl-router: route /api/things', children: [
+          { label: 'acryl-router: serves POST /api/things', children: [] },
+          { label: 'inner timer', children: [] },
+        ] },
         { label: 'ctx.on("internal/status")', children: [] },
       ],
     }))
@@ -41,7 +47,7 @@ describe('explain', () => {
   it('says what a plugin needs, adds and removes on unload', () => {
     const text = explain(reportFiber(fiber({
       inject: { router: null },
-      effects: [{ label: 'acryl-router: route / (GET /a)', children: [] }],
+      effects: [{ label: 'acryl-router: route /', children: [{ label: 'acryl-router: serves GET /a', children: [] }] }],
     })))
     expect(text).toContain('demo (ACTIVE)')
     expect(text).toContain('needs:     router')

package/plugins/acryl-inspect/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-inspect",
-    "commit": "df79b188398b6d4f8cceda35a72b88300a10a9ce"
+    "commit": "64e7c9d2e787f74b2da82492644fbbb46a601074"
   },
   "vendored": [
     "src",
@@ -10,7 +10,7 @@
     "LICENSE"
   ],
   "rewrittenSpecifiers": 3,
-  "digest": "sha256:e9887df0d2b5274d4fc5de4c730975528a84fd1d270994ee85a2789bec101db7",
+  "digest": "sha256:434ed3cf6b9028da90ad6b395209affbc917a62aa994f2b3c8f1d98a26398ea7",
   "testsNotRun": {},
   "notice": [
     "LICENSE"

package/plugins/acryl-node-server/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-node-server",
-    "commit": "df79b188398b6d4f8cceda35a72b88300a10a9ce"
+    "commit": "64e7c9d2e787f74b2da82492644fbbb46a601074"
   },
   "vendored": [
     "src",

package/plugins/acryl-router/src/middleware/index.ts

@@ -22,4 +22,4 @@ export { NONCE, secureHeaders, type SecureHeadersVariables } from '../core/middl
 export { timeout } from '../core/middleware/timeout/index.ts'
 export { endTime, setMetric, startTime, timing, wrapTime, type TimingVariables } from '../core/middleware/timing/index.ts'
 export { appendTrailingSlash, trimTrailingSlash } from '../core/middleware/trailing-slash/index.ts'
-export { LOOPBACK_HOSTNAMES, loopbackAuthority, loopbackOnly, sameOrigin, type LoopbackOptions } from './loopback-only.ts'
+export { LOOPBACK_HOSTNAMES, fromOwnPage, loopbackAuthority, loopbackOnly, sameOrigin, type LoopbackOptions } from './loopback-only.ts'

package/plugins/acryl-router/src/middleware/loopback-only.ts

@@ -19,6 +19,13 @@ export interface LoopbackOptions {
    * checked in full: only a call with no connection facts at all counts as in process.
    */
   readonly inProcess?: 'deny' | 'allow'
+  /**
+   * Who may call. `local` (default): any program on this machine, a browser page only as `mutations` allows. `own-page`: only this app's own page,
+   * for private routes a script on the machine must not drive or read either. A request then shows an `Origin` that is exactly this authority (with
+   * `Sec-Fetch-Site` absent or `same-origin`), or, for a read (GET, HEAD, OPTIONS), which browsers often send without `Origin`, `Sec-Fetch-Site:
+   * same-origin` and a `Referer` from this authority. `mutations` is not consulted: every request is held to that rule.
+   */
+  readonly callers?: 'local' | 'own-page'
 }
 
 const loopback = new BlockList()
@@ -68,10 +75,31 @@ export function sameOrigin(c: Context, authority: URL): boolean {
   }
 }
 
-/** Only requests from this machine to this app: loopback peer, the real port, an allowed `Host`, and for mutations a matching `Origin`. Everything else gets a 403. */
+function originOf(value: string | undefined): string | undefined {
+  if (value === undefined) return undefined
+  try {
+    return new URL(value).origin
+  } catch {
+    return undefined
+  }
+}
+
+/** Whether the request comes from a page served by this authority itself: the `own-page` rule of {@link LoopbackOptions.callers}. */
+export function fromOwnPage(c: Context, authority: URL): boolean {
+  const origin = c.req.header('origin')
+  const fetchSite = c.req.header('sec-fetch-site')
+  if (origin !== undefined && originOf(origin) === origin && origin === authority.origin) return fetchSite === undefined || fetchSite === 'same-origin'
+  return SAFE_METHODS.has(c.req.method) && fetchSite === 'same-origin' && originOf(c.req.header('referer')) === authority.origin
+}
+
+/**
+ * Only requests from this machine to this app: loopback peer, the real port, an allowed `Host`, and for mutations a matching `Origin` (with
+ * `callers: 'own-page'`, every request from this app's own page). Everything else gets a 403.
+ */
 export function loopbackOnly(options: LoopbackOptions = {}): MiddlewareHandler {
   const mutations = options.mutations ?? 'same-origin'
   const inProcess = options.inProcess ?? 'deny'
+  const ownPage = options.callers === 'own-page'
   return async (c, next) => {
     const connection = connectionOf(c)
     if (inProcess === 'allow' && connection.remoteAddress === undefined && connection.localPort === undefined) {
@@ -80,6 +108,11 @@ export function loopbackOnly(options: LoopbackOptions = {}): MiddlewareHandler {
     }
     const authority = loopbackAuthority(c, options.hostnames)
     if (authority === undefined) return c.json({ error: 'request authority rejected' }, 403)
+    if (ownPage) {
+      if (!fromOwnPage(c, authority)) return c.json({ error: 'only this app\'s own page may call this' }, 403)
+      await next()
+      return
+    }
     if (mutations === 'same-origin' && !SAFE_METHODS.has(c.req.method) && !sameOrigin(c, authority)) {
       return c.json({ error: 'a change must come from this app\'s own origin' }, 403)
     }

package/plugins/acryl-router/src/service.ts

@@ -144,9 +144,15 @@ export class Router extends Service {
       this.state.composed = undefined
       return this.end([...this.flights].filter(flight => (flight.running.get(mount) ?? 0) > 0 || flight.producer === mount), `removing ${path}`)
     }
-    // The label lists what the mount serves, so the inspector can report routes without asking the router (`ALL` is middleware or `all`).
-    const served = app.routes.map(route => `${route.method} ${mergePath(path, route.path)}`).join(', ')
-    this.ctx.effect(() => remove, `acryl-router: route ${path} (${served})`)
+    // Each route the mount serves is a child effect of it, labeled on its own, so the inspector can report routes without asking the
+    // router and no label grows with the size of the app (`ALL` is middleware or `all`). The children hold nothing: the mount does.
+    // (Cordis adopts an effect as a child only when the parent's body yields it.)
+    const served = new Set(app.routes.map(route => `${route.method} ${mergePath(path, route.path)}`))
+    const owner = this.ctx
+    owner.effect(function* () {
+      for (const route of served) yield owner.effect(() => () => {}, `acryl-router: serves ${route}`)
+      yield remove
+    }, `acryl-router: route ${path}`)
     return () => { void remove() }
   }
 

package/plugins/acryl-router/tests/loopback-only.spec.ts

@@ -0,0 +1,80 @@
+/**
+ * `loopbackOnly`, the guard of a local app's own routes: the peer and port come from the transport, the `Host` names this app, and the
+ * `callers` rule decides whether any local program or only the app's own page may call.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { App, type ConnectionInfo } from '../src/index.ts'
+import { loopbackOnly, type LoopbackOptions } from '../src/middleware/index.ts'
+
+const PORT = 43_120
+const SELF = `http://127.0.0.1:${String(PORT)}`
+const LOCAL: ConnectionInfo = { remoteAddress: '127.0.0.1', localPort: PORT }
+
+function guarded(options: LoopbackOptions = {}): App {
+  return new App().use(loopbackOnly(options)).get('/x', c => c.text('read')).post('/x', c => c.text('changed'))
+}
+
+async function status(
+  app: App,
+  method: string,
+  headers: Record<string, string>,
+  connection: ConnectionInfo = LOCAL,
+): Promise<number> {
+  const response = await app.fetch(new Request(`${SELF}/x`, { method, headers: { host: `127.0.0.1:${String(PORT)}`, ...headers } }), { connection })
+  return response.status
+}
+
+describe('loopbackOnly, callers: local (the default)', () => {
+  const app = guarded()
+
+  it('lets a local program read and change, and a page of this app change', async () => {
+    expect(await status(app, 'GET', {})).toBe(200)
+    expect(await status(app, 'POST', {})).toBe(200)
+    expect(await status(app, 'POST', { origin: SELF })).toBe(200)
+  })
+
+  it('refuses another origin\'s change, a foreign peer, a wrong port, a foreign Host and an in-process call', async () => {
+    expect(await status(app, 'POST', { origin: 'http://evil.test' })).toBe(403)
+    expect(await status(app, 'GET', {}, { remoteAddress: '192.168.1.5', localPort: PORT })).toBe(403)
+    expect(await status(app, 'GET', {}, { remoteAddress: '127.0.0.1', localPort: PORT + 1 })).toBe(403)
+    expect(await status(app, 'GET', { host: 'evil.test' })).toBe(403)
+    expect(await status(app, 'GET', {}, {})).toBe(403)
+  })
+
+  it('lets an in-process call through only when the host says so', async () => {
+    expect(await status(guarded({ inProcess: 'allow' }), 'GET', {}, {})).toBe(200)
+  })
+})
+
+describe('loopbackOnly, callers: own-page', () => {
+  const app = guarded({ callers: 'own-page', hostnames: ['127.0.0.1'] })
+
+  it('lets this app\'s page read and change with its exact Origin', async () => {
+    expect(await status(app, 'GET', { origin: SELF, 'sec-fetch-site': 'same-origin' })).toBe(200)
+    expect(await status(app, 'POST', { origin: SELF, 'sec-fetch-site': 'same-origin' })).toBe(200)
+    expect(await status(app, 'POST', { origin: SELF })).toBe(200)
+  })
+
+  it('lets a same-origin read without Origin through by its Referer, as browsers send it', async () => {
+    expect(await status(app, 'GET', { 'sec-fetch-site': 'same-origin', referer: `${SELF}/page?tab=1` })).toBe(200)
+  })
+
+  it('refuses a local program (no Origin), even for a read', async () => {
+    expect(await status(app, 'GET', {})).toBe(403)
+    expect(await status(app, 'POST', {})).toBe(403)
+  })
+
+  it('refuses a change that only has the read evidence, and Origin forms that are not exact', async () => {
+    expect(await status(app, 'POST', { 'sec-fetch-site': 'same-origin', referer: `${SELF}/` })).toBe(403)
+    expect(await status(app, 'POST', { origin: `${SELF}/` })).toBe(403)
+    expect(await status(app, 'POST', { origin: 'null' })).toBe(403)
+    expect(await status(app, 'POST', { origin: SELF, 'sec-fetch-site': 'same-site' })).toBe(403)
+  })
+
+  it('refuses another page, a Referer from elsewhere and a Host this app does not answer to', async () => {
+    expect(await status(app, 'GET', { origin: 'http://evil.test', 'sec-fetch-site': 'cross-site' })).toBe(403)
+    expect(await status(app, 'GET', { 'sec-fetch-site': 'same-origin', referer: 'http://evil.test/' })).toBe(403)
+    expect(await status(app, 'GET', { host: `localhost:${String(PORT)}`, origin: `http://localhost:${String(PORT)}` })).toBe(403)
+  })
+})

package/plugins/acryl-router/tests/service.spec.ts

@@ -152,6 +152,23 @@ describe('acryl-router lifecycle through Cordis', () => {
     expect(router.size).toBe(1)
   })
 
+  it('labels a mount by its path with one child per route, so no label grows with the app (an inspector caps label length)', async () => {
+    const { ctx, router } = await mountRouter()
+    const big = new App().use('/api/*', async (_c, next) => { await next() })
+    for (let i = 0; i < 60; i += 1) big.get(`/api/a-fairly-long-resource-name-${String(i)}`, c => c.text('ok'))
+    const fiber = ctx.plugin({ name: 'big', inject: ['router'], apply: (inner: Context) => { inner.router.route('/', big) } })
+    await settle()
+    const [mount, ...rest] = fiber.getEffects()
+    expect(rest).toEqual([])
+    expect(mount?.label).toBe('acryl-router: route /')
+    expect(mount?.children).toHaveLength(61)
+    expect(mount?.children[0]?.label).toBe('acryl-router: serves ALL /api/*')
+    expect(mount?.children.every(child => child.label.length < 100 && child.children.length === 0)).toBe(true)
+    expect(router.size).toBe(1)
+    await fiber.dispose()
+    expect(router.size).toBe(0)
+  })
+
   it('replaces the provider without leaving doubled registrations: consumers re-register exactly once', async () => {
     const ctx = root()
     const first = ctx.plugin(provider, config)

package/plugins/acryl-router/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-router",
-    "commit": "df79b188398b6d4f8cceda35a72b88300a10a9ce"
+    "commit": "64e7c9d2e787f74b2da82492644fbbb46a601074"
   },
   "vendored": [
     "src",
@@ -10,7 +10,7 @@
     "LICENSE"
   ],
   "rewrittenSpecifiers": 0,
-  "digest": "sha256:6e15f8ce0499b94c95649342f6fe984bc9b2aec0f5a142e8853a5badcc3b85f5",
+  "digest": "sha256:9ad75d259a74b2a07fe1d8a269e7c83c30061acc90f8a1630e6049b68ba10aa3",
   "testsNotRun": {
     "tests/loader.spec.ts": "loads the built lib/ entry through the real Loader; the library ships source and has no build"
   },

package/plugins/acryl-router-http/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-router-http",
-    "commit": "df79b188398b6d4f8cceda35a72b88300a10a9ce"
+    "commit": "64e7c9d2e787f74b2da82492644fbbb46a601074"
   },
   "vendored": [
     "src",

package/plugins/acryl-state/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-state",
-    "commit": "df79b188398b6d4f8cceda35a72b88300a10a9ce"
+    "commit": "64e7c9d2e787f74b2da82492644fbbb46a601074"
   },
   "vendored": [
     "src",

package/plugins/builder/script.ts

@@ -30,7 +30,7 @@ export function apply(ctx: Context) {
 }
 
 export async function check(ctx: Context) {
-  const reply = await ctx.get('router')!.request(${JSON.stringify(path)})
+  const reply = await ctx.router.request(${JSON.stringify(path)})
   if (!reply.ok) throw new Error(\`GET ${path} answered \${reply.status}\`)
 }
 `

package/plugins/extensions/index.ts

@@ -109,7 +109,7 @@ interface PluginModule {
   readonly name?: unknown
   readonly inject?: unknown
   readonly apply: (...args: unknown[]) => unknown
-  /** Optional self-check, run after the plugin starts: it throws (or rejects) when the plugin does not work. */
+  /** Optional self-check, run after the plugin starts with the plugin's own context (so `ctx.router` reads as in `apply`): it throws (or rejects) when the plugin does not work. */
   readonly check?: (ctx: Context) => unknown
 }
 
@@ -507,6 +507,7 @@ export class Extensions extends Service {
   /** Run the extension's own `check`, if it has one, with a time limit. Returns the failure, or `undefined` when it passes. */
   private async verify(
     module: PluginModule,
+    ctx: Context,
   ): Promise<{ stage: 'verify'; error: string } | undefined> {
     if (typeof module.check !== 'function') return undefined
     let timer: ReturnType<typeof setTimeout> | undefined
@@ -517,7 +518,7 @@ export class Extensions extends Service {
           CHECK_TIMEOUT_MS,
         )
       })
-      await Promise.race([Promise.resolve(module.check(this.ctx)), limit])
+      await Promise.race([Promise.resolve(module.check(ctx)), limit])
       return undefined
     } catch (error) {
       return { stage: 'verify', error: `its check failed: ${message(error)}` }
@@ -615,7 +616,7 @@ export class Extensions extends Service {
             error: message(mounted.error ?? 'the plugin failed to start'),
           }
         : state === 'active'
-          ? await this.verify(module)
+          ? await this.verify(module, mounted.fiber.ctx)
           : undefined
     if (failure) {
       await mounted.fiber.dispose().catch(() => undefined)

package/plugins/openai/prompt.ts

@@ -17,14 +17,14 @@ A plugin's index.ts is TypeScript that Node runs directly (erasable syntax only:
     ctx.router.route('/', new App().get('/hello', (c) => c.json({ text: 'Hello' })))   // removed when the plugin is unloaded
   }
   export async function check(ctx: Context) {   // optional: must pass, or the install is rolled back
-    const reply = await ctx.get('router')!.request('/hello')
+    const reply = await ctx.router.request('/hello')
     if (!reply.ok) throw new Error('GET /hello failed')
   }
 
 The router: build an App (import { App } from 'acryl-router'), register routes on it with app.get/post/put/patch/delete(path, handler) and mount it with
 ctx.router.route(prefix, app). A path parameter is :id and is read with c.req.param('id'); c.json(body, status) answers JSON, c.text(...) answers text,
 await c.req.json() reads a JSON body, throw new HTTPException(404, { message }) (also from 'acryl-router') answers an error. Routes added to an app
-after route() are not served: build the whole app first. ctx.get('router')!.request('/path', { method: 'POST', body: ... }) calls a route in process (use it in
+after route() are not served: build the whole app first. ctx.router.request('/path', { method: 'POST', body: ... }) calls a route in process (use it in
 check). The mount goes away when the plugin is unloaded.
 
 For a capability that is a pure function of data (parse, convert, compute), write a sandboxed TOOL instead of a plugin. It cannot touch the

package/shared/AGENTS.core.md

@@ -0,0 +1,54 @@
+# __APP_NAME__
+
+A Cordis app on the ACRYL framework: TypeScript that Node 22.19 or newer runs directly (no build step; erasable syntax only, so no enums and no
+parameter properties). Every part of it is a Cordis plugin.
+
+## The framework's API is in `docs/framework/`
+
+Start at `docs/framework/README.md`; `api-summary.md` is the one-page summary. Read before you write routes: `routing.md` (the `App`), `request.md` (`c.req`), `context.md` (`c`),
+`validation.md`, `helpers.md` (`streamSSE`), `middleware.md`, `plugin-lifecycle.md` (what a plugin owns and when it is unloaded) and
+`node-server.md`. The framework's source is vendored in `src/plugins/acryl-*/src`: read it, do not edit it (a change belongs in ACRYL, upstream).
+The docs write `from 'acryl-router'`; in this app that is `./plugins/acryl-router/src/index.ts` (relative to `src/`), `acryl-router/middleware`
+is `./plugins/acryl-router/src/middleware/index.ts` and `acryl-router/helpers` is `./plugins/acryl-router/src/helpers/index.ts`.
+A plugin written into `extensions/` while the app runs can import `acryl-router`, `acryl-router/middleware` and `acryl-router/helpers` by those names.
+
+## How a feature is built
+
+Routes are an ordinary `App` that a plugin mounts once with `ctx.router.route(prefix, app)`. The mount belongs to the plugin and goes away when it unloads.
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import { App, HTTPException } from './plugins/acryl-router/src/index.ts'
+import { schemaValidator, type StandardSchema } from './plugins/acryl-router/src/helpers/index.ts'
+
+export const name = 'notes'               // a plugin's name; blend.yaml refers to it
+export const inject = ['router']          // services it needs
+export function apply(ctx: Context) {
+  const app = new App()
+    .get('/', (c) => c.json({ ok: true }))
+    .get('/:id', (c) => c.json({ id: c.req.param('id') }))
+    .post('/', schemaValidator('json', NewNote), (c) => c.json(c.req.valid('json'), 201))   // NewNote is a Standard Schema
+  ctx.router.route('/notes', app)         // build the whole app first: routes added after route() are not served
+}
+```
+
+- A small route goes on the `App` in `src/routes.ts`. A new feature is a new plugin file: add it to `registry` in `src/app.ts`, add a row
+  (`- id: notes` / `name: notes`) to `blend.yaml` before the `acryl-node-server` row, and pass runtime values (a data file) as its config in `createApp`.
+- State, when `src/plugins/acryl-state` exists: `const cell = ctx.state.cell<T>('notes.list', initial)` (add `'state'` to `inject`), then
+  `cell.get()`, `cell.set(value)`, `cell.update(fn)` and `cell.subscribe(fn)` (returns the unsubscribe). Every cell is also served as JSON at `/api/state/<key>`
+  and streamed at `/api/state/<key>/events`.
+- Test a route without a socket: `await ctx.router.request('/notes')`, or boot the app as `test/app.test.ts` does and use `fetch`.
+
+## Things that surprise people
+
+- A page mounted at `/x` answers `/x`, not `/x/` (trailing slashes are strict); `trimTrailingSlash()` (middleware) redirects `/x/` to `/x` for GET and HEAD.
+- `schemaValidator('json', ...)` needs a JSON `Content-Type`; without it the schema sees `{}`. A failure answers 400 with
+  `{ "error": "invalid json", "issues": [{ "message", "path" }] }`: the human text is `issues[0].message`. A `jsonOnly` recipe in `docs/framework/validation.md` answers 415 instead.
+- Throw `new HTTPException(404, { message })` for an error response; the body is the message as plain text (use `c.json({ error }, status)` when a page expects JSON).
+- Handlers get the request as `c.req`: `c.req.param('id')`, `c.req.query('q')`, `await c.req.json()`, `c.req.raw` for the Web `Request`.
+- A server-sent stream is `streamSSE(c, async (stream) => { await stream.writeSSE({ data: JSON.stringify(x) }) ... })`; call `stream.onAbort(cleanup)`.
+- `npm run dev` restarts the app whenever a file changes.
+
+## Before you say you are done
+
+`npm test` and `npm run check` (type-check) both pass. Put tests in `test/`, written with `node:test` like `test/app.test.ts`.

package/templates/agent/AGENTS.md

@@ -0,0 +1,6 @@
+
+## This app (agent)
+
+Besides `src/routes.ts`, the app runs an agent (`POST /ask`) that can write plugins into `extensions/` while the app runs and install them with
+rollback; `GET /extensions` and `GET /tasks` show what it did. A plugin there is a folder with an `index.ts` exporting `name`, `inject`, `apply(ctx)`
+and an optional `check(ctx)` that receives the plugin's own context (so `ctx.router` reads as in `apply`). It may import `acryl-router`.

package/templates/agent/README.md

@@ -5,7 +5,7 @@ Cordis plugin.
 
 ```sh
 npm install
-npm run dev        # prints its URL; data lives in .acrylblends/
+npm run dev        # prints its URL; data lives in .acrylblends/; it restarts when a file changes (a new port if ACRYLBLENDS_PORT=0)
 npm test
 npm run check      # type-check
 
@@ -41,7 +41,7 @@ curl <url>/tasks              # every run as a durable task, with the tool calls
 
 Other commands: `update route <name> <path> <text>`, `break plugin <name>` (shows the rollback), `remove plugin <name>`,
 `list plugins`. What the agent writes lands in `extensions/`, is part of your app, and starts again at the next start.
-- `src/routes.ts` is your own plugin: routes added inside `ctx.effect`.
+- `src/routes.ts` is your own plugin: it builds an `App` (`import { App } from './plugins/acryl-router/src/index.ts'`) and mounts it with `ctx.router.route(prefix, app)`. Routes added to the app after it is mounted are not served. A page mounted at `/x` answers `/x`, not `/x/` (trailing slashes are strict). The router API is documented at https://acrylblends.github.io/docs/framework/the-acryl-framework and in `docs/framework` of the acrylblends repository.
 - `src/plugins/` holds the plugins copied from the ACRYLBLENDS library. They are yours now; edit them freely.
   Add more with `acrylblends add <plugin>`.