acrylblends 0.4.0 → 0.5.0

package/plugins/extensions/resolve.ts

@@ -12,21 +12,81 @@ import { registerHooks } from 'node:module'
 import { join } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 
+const PACKAGE = 'acrylblends'
+
 const isBare = (specifier: string) => !/^[./]/.test(specifier) && !specifier.includes(':')
 
-/** The router's specifiers, as files of the vendored plugin that sits beside this one; empty when the app has no router. */
+/**
+ * The framework's specifiers, as files of the vendored router plugin that sits beside this one. A plugin written while the app runs (by the agent, from the docs in the app)
+ * imports `acrylblends` and `acrylblends/<subpath>` as the docs write them; the old `acryl-router` names keep working. Empty when the app has no router.
+ */
+const MIDDLEWARE = [
+  'basic-auth',
+  'bearer-auth',
+  'body-limit',
+  'combine',
+  'compress',
+  'context-storage',
+  'cors',
+  'csrf',
+  'etag',
+  'ip-restriction',
+  'jwk',
+  'jwt',
+  'language',
+  'logger',
+  'loopback-only',
+  'method-not-allowed',
+  'method-override',
+  'powered-by',
+  'pretty-json',
+  'request-id',
+  'secure-headers',
+  'serve-static',
+  'timeout',
+  'timing',
+  'trailing-slash',
+]
+const HELPERS = [
+  'accepts',
+  'cookie',
+  'factory',
+  'html',
+  'route',
+  'schema-validator',
+  'streaming',
+  'testing',
+  'validator',
+  'ws',
+]
+
+/** The `acrylblends/...` names a plugin installed live may import, with the file each resolves to under `acryl-router/src`. */
+export function frameworkSpecifiers(): Record<string, string> {
+  const map: Record<string, string> = {
+    '': 'index.ts',
+    conninfo: 'index.ts',
+    'http-exception': 'index.ts',
+    types: 'index.ts',
+    client: 'client.ts',
+  }
+  for (const name of MIDDLEWARE) map[name] = 'middleware/index.ts'
+  for (const name of HELPERS) map[name] = 'helpers/index.ts'
+  return map
+}
+
 export function routerAliases(): Record<string, string> {
   const src = new URL('../acryl-router/src/', import.meta.url)
-  const files = {
-    'acryl-router': 'index.ts',
-    'acryl-router/middleware': 'middleware/index.ts',
-    'acryl-router/helpers': 'helpers/index.ts',
+  const aliases: Record<string, string> = {}
+  const add = (specifier: string, file: string) => {
+    const path = fileURLToPath(new URL(file, src))
+    if (existsSync(path)) aliases[specifier] = path
   }
-  return Object.fromEntries(
-    Object.entries(files)
-      .map(([specifier, file]) => [specifier, fileURLToPath(new URL(file, src))] as const)
-      .filter(([, path]) => existsSync(path)),
-  )
+  for (const [sub, file] of Object.entries(frameworkSpecifiers()))
+    add(sub === '' ? PACKAGE : `${PACKAGE}/${sub}`, file)
+  add('acryl-router', 'index.ts')
+  add('acryl-router/middleware', 'middleware/index.ts')
+  add('acryl-router/helpers', 'helpers/index.ts')
+  return aliases
 }
 
 export function resolveFromApp(

package/plugins/openai/prompt.ts

@@ -10,21 +10,21 @@ To add a capability:
 A plugin's index.ts is TypeScript that Node runs directly (erasable syntax only: no enums, no parameter properties):
 
   import type { Context } from '@deepseek-ai/cordis'
-  import { App } from 'acryl-router'
+  import { Acryl } from 'acrylblends'
   export const name = 'hello'            // must equal the folder name
   export const inject = ['router']        // services it needs; it waits (pending) until they exist
   export function apply(ctx: Context) {
-    ctx.router.route('/', new App().get('/hello', (c) => c.json({ text: 'Hello' })))   // removed when the plugin is unloaded
+    ctx.router.route('/', new Acryl().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
+The router: build an Acryl app (import { Acryl } from 'acrylblends'), 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
+await c.req.json() reads a JSON body, throw new HTTPException(404, { message }) (also from 'acrylblends') answers an error. Routes added to an app
+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
@@ -32,6 +32,6 @@ host: it runs in a separate process that can read only its own folder. Files: in
   { "description": "what it does and its input", "examples": [ { "input": {...}, "output": {...} } ] }
 The examples are run in the sandbox at install and must match exactly, or the install is refused. Use write_plugin and install_plugin for tools too.
 
-Rules: import only relative files, node: built-ins, @deepseek-ai/cordis and acryl-router. Provide services with ctx.provide(name, value) and
+Rules: import only relative files, node: built-ins, @deepseek-ai/cordis and acrylblends (and its subpaths such as acrylblends/cors, whose docs are in docs/framework). Provide services with ctx.provide(name, value) and
 use others with ctx.get(name). Put timers, listeners and routes inside ctx.effect(() => cleanup). Use list_plugins and
 read_plugin to see what exists. When you are done, answer in one or two plain sentences saying what you built.`

package/shared/AGENTS.core.md

@@ -0,0 +1,61 @@
+# __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: `api/routing.md` (the `Acryl` app), `api/request.md` (`c.req`),
+`api/context.md` (`c`), `cordis/validation.md` and `guides/validation.md`, `guides/helpers.md` (`streamSSE`), `concepts/middleware.md`, `cordis/plugin-lifecycle.md` (what a plugin
+owns and when it is unloaded), `cordis/mounting.md` and `cordis/node-server.md`. Pages marked "not yet available" describe parts that are not in this app.
+
+The docs write `import { Acryl } from 'acrylblends'` and `from 'acrylblends/<subpath>'`. In this app the framework is the vendored plugin source in `src/plugins/acryl-router/src`
+(read it, do not edit it: a change belongs in ACRYL, upstream), so from a file in `src/` import:
+
+- `./plugins/acryl-router/src/index.ts` for `Acryl`, `Context`, `HTTPException`, `connectionOf`, `getConnInfo` and the types;
+- `./plugins/acryl-router/src/middleware/index.ts` for every middleware (`cors`, `bodyLimit`, `trimTrailingSlash`, `loopbackOnly`, ...);
+- `./plugins/acryl-router/src/helpers/index.ts` for the helpers and validators (`streamSSE`, `schemaValidator`, `validator`, cookies, `testClient`, ...).
+
+A plugin written into `extensions/` while the app runs may use the docs' own names instead: `acrylblends` and `acrylblends/<subpath>` resolve to the same files. `App` is the
+deprecated name of `Acryl`.
+
+## How a feature is built
+
+Routes are an ordinary `Acryl` 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 { Acryl, 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 Acryl()
+    .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>`.
 

package/templates/agent/blend.yaml

@@ -1,6 +1,6 @@
 # The app as data, in ACRYL's Blend format (blends.acryl.dev/v1alpha1): which plugins it mounts, in what order, with what config.
 # Edit this, not app.ts, to switch a plugin off (disabled: true) or change its config. `npm run lock` records what the app is built from.
-# Order matters: http comes before extensions, because installed extensions start again at boot and may add routes.
+# Order matters: acryl-router comes before extensions, because installed extensions start again at boot and may add routes.
 apiVersion: blends.acryl.dev/v1alpha1
 kind: Blueprint
 metadata:

package/templates/agent/src/routes.ts

@@ -1,5 +1,5 @@
 import type { Context } from '@deepseek-ai/cordis'
-import { App } from './plugins/acryl-router/src/index.ts'
+import { Acryl } from './plugins/acryl-router/src/index.ts'
 import { bodyLimit } from './plugins/acryl-router/src/middleware/index.ts'
 import type {} from './plugins/agent/index.ts'
 import type {} from './plugins/extensions/index.ts'
@@ -23,7 +23,7 @@ export const routes = {
       const body = await c.req.json().catch(() => undefined)
       return typeof body === 'object' && body !== null ? (body as Record<string, unknown>) : {}
     }
-    const app = new App()
+    const app = new Acryl()
       .use(bodyLimit({ maxSize: 64 * 1024 }))
       .get('/', (c) => c.json({ app: APP_NAME, ok: true }))
       .get('/health', (c) => c.json({ ok: true }))

package/templates/agent/test/model.test.ts

@@ -10,12 +10,12 @@ import { pinnedInstance, withPort } from '../src/plugins/instance/index.ts'
 
 /** A plugin no scripted command knows: the model writes it from scratch. */
 const COUNTER = `import type { Context } from '@deepseek-ai/cordis'
-import { App } from 'acryl-router'
+import { Acryl } from 'acrylblends'
 export const name = 'counter'
 export const inject = ['router']
 export function apply(ctx: Context) {
   let count = 0
-  ctx.router.route('/', new App().get('/count', (c) => c.json({ count: ++count })))
+  ctx.router.route('/', new Acryl().get('/count', (c) => c.json({ count: ++count })))
 }
 `
 

package/templates/agent/tsconfig.json

@@ -13,6 +13,46 @@
     "skipLibCheck": true,
     "types": ["node"],
     "paths": {
+      "acrylblends": ["./src/plugins/acryl-router/src/index.ts"],
+      "acrylblends/conninfo": ["./src/plugins/acryl-router/src/index.ts"],
+      "acrylblends/http-exception": ["./src/plugins/acryl-router/src/index.ts"],
+      "acrylblends/types": ["./src/plugins/acryl-router/src/index.ts"],
+      "acrylblends/client": ["./src/plugins/acryl-router/src/client.ts"],
+      "acrylblends/basic-auth": ["./src/plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/bearer-auth": ["./src/plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/body-limit": ["./src/plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/combine": ["./src/plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/compress": ["./src/plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/context-storage": ["./src/plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/cors": ["./src/plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/csrf": ["./src/plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/etag": ["./src/plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/ip-restriction": ["./src/plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/jwk": ["./src/plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/jwt": ["./src/plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/language": ["./src/plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/logger": ["./src/plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/loopback-only": ["./src/plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/method-not-allowed": ["./src/plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/method-override": ["./src/plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/powered-by": ["./src/plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/pretty-json": ["./src/plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/request-id": ["./src/plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/secure-headers": ["./src/plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/serve-static": ["./src/plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/timeout": ["./src/plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/timing": ["./src/plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/trailing-slash": ["./src/plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/accepts": ["./src/plugins/acryl-router/src/helpers/index.ts"],
+      "acrylblends/cookie": ["./src/plugins/acryl-router/src/helpers/index.ts"],
+      "acrylblends/factory": ["./src/plugins/acryl-router/src/helpers/index.ts"],
+      "acrylblends/html": ["./src/plugins/acryl-router/src/helpers/index.ts"],
+      "acrylblends/route": ["./src/plugins/acryl-router/src/helpers/index.ts"],
+      "acrylblends/schema-validator": ["./src/plugins/acryl-router/src/helpers/index.ts"],
+      "acrylblends/streaming": ["./src/plugins/acryl-router/src/helpers/index.ts"],
+      "acrylblends/testing": ["./src/plugins/acryl-router/src/helpers/index.ts"],
+      "acrylblends/validator": ["./src/plugins/acryl-router/src/helpers/index.ts"],
+      "acrylblends/ws": ["./src/plugins/acryl-router/src/helpers/index.ts"],
       "acryl-router": ["./src/plugins/acryl-router/src/index.ts"],
       "acryl-router/middleware": ["./src/plugins/acryl-router/src/middleware/index.ts"],
       "acryl-router/helpers": ["./src/plugins/acryl-router/src/helpers/index.ts"]

package/templates/blank/AGENTS.md

@@ -0,0 +1,5 @@
+
+## This app (blank)
+
+`src/routes.ts` is the app's own plugin: add routes to its `App`. `blend.yaml` lists the plugins that are mounted. `acrylblends add <plugin>` copies
+another library plugin (for example `acryl-state`) into `src/plugins/`.

package/templates/blank/README.md

@@ -15,7 +15,7 @@ npm run check      # type-check
   one off with `disabled: true`. `npm run lock` writes `blend.lock.json`: the manifest's digest and a digest of
   every plugin folder, so a diff of the lock shows what changed.
 - `src/app.ts` holds the registry of plugins the code provides, and mounts the manifest's rows.
-- `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>`.
 

package/templates/blank/src/routes.ts

@@ -1,5 +1,5 @@
 import type { Context } from '@deepseek-ai/cordis'
-import { App } from './plugins/acryl-router/src/index.ts'
+import { Acryl } from './plugins/acryl-router/src/index.ts'
 
 export const APP_NAME = '__APP_NAME__'
 
@@ -8,7 +8,7 @@ export const routes = {
   name: 'routes',
   inject: ['router'],
   apply(ctx: Context) {
-    const app = new App()
+    const app = new Acryl()
       .get('/', (c) => c.json({ app: APP_NAME, ok: true }))
       .get('/health', (c) => c.json({ ok: true }))
     ctx.router.route('/', app)

package/templates/todo/AGENTS.md

@@ -0,0 +1,5 @@
+
+## This app (todo)
+
+`src/todo.ts` is the whole feature: a plugin that mounts an `App` (CRUD, a page, a server-sent stream) and keeps the list in a state cell that it
+also writes to a file in the app's home. Use it as the reference for a new plugin, and keep its tests passing when you change it.

package/templates/todo/src/todo.ts

@@ -6,8 +6,8 @@
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
 import { dirname } from 'node:path'
 import type { Context } from '@deepseek-ai/cordis'
-import { App, HTTPException } from './plugins/acryl-router/src/index.ts'
-import { bodyLimit, loopbackOnly } from './plugins/acryl-router/src/middleware/index.ts'
+import { Acryl, HTTPException } from './plugins/acryl-router/src/index.ts'
+import { bodyLimit, loopbackOnly, trimTrailingSlash } from './plugins/acryl-router/src/middleware/index.ts'
 import { schemaValidator, streamSSE, type StandardSchema } from './plugins/acryl-router/src/helpers/index.ts'
 import type {} from './plugins/acryl-state/src/index.ts'
 import { PAGE } from './page.ts'
@@ -84,8 +84,10 @@ export function apply(ctx: Context, config: Config = {}): void {
     return todo
   }
 
-  const api = new App()
-    .use(loopbackOnly({ inProcess: 'allow' }), bodyLimit({ maxSize: MAX_BODY_BYTES }))
+  // `/todo/` is what people type: trimTrailingSlash answers a GET for an unknown path ending in `/` with a 301 to the path without it,
+  // so the page is found either way while each route keeps one canonical path (the router itself treats `/a` and `/a/` as different).
+  const api = new Acryl()
+    .use(loopbackOnly({ inProcess: 'allow' }), bodyLimit({ maxSize: MAX_BODY_BYTES }), trimTrailingSlash())
     .get('/', c => c.html(PAGE))
     .get('/api', c => c.json(todos.get()))
     .post('/api', schemaValidator('json', NewTodo), c => {

package/templates/todo/upstream.json

@@ -5,8 +5,8 @@
       "examples/acryl-todo/src/index.ts": "src/todo.ts",
       "examples/acryl-todo/src/page.ts": "src/page.ts"
     },
-    "commit": "df79b188398b6d4f8cceda35a72b88300a10a9ce"
+    "commit": "f5151e7f0c4de3b81bddb5cc686b5ef329e48e1c"
   },
   "rewrittenSpecifiers": 4,
-  "digest": "sha256:c4efede39387681003c6d2f0f2858e157a84bcaaf9ae94ebe23d10f72a538ffd"
+  "digest": "sha256:9093704776563001f7f472f94cc5c2fdd79206342c1cb59c11fce62aa74df3ed"
 }