acrylblends 0.5.0 → 0.5.1

package/README.md

@@ -0,0 +1,325 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/acrylblends/acrylblends/main/docs/assets/acrylblends-logo.png" alt="ACRYLBLENDS" width="120">
+</p>
+
+<h1 align="center">acrylblends</h1>
+
+<p align="center"><strong>Acryl, a small web framework on Web Standards, for Node.js.</strong><br>
+One <code>Request</code> in, one <code>Response</code> out: routing, middleware, validation, a typed client and a Node.js server, with no dependencies.</p>
+
+<p align="center">
+  <a href="https://github.com/acryldev/acryl/blob/main/docs/framework/README.md">Documentation</a> ·
+  <a href="https://github.com/acryldev/acryl/blob/main/docs/framework/getting-started/basic.md">Getting started</a> ·
+  <a href="https://github.com/acryldev/acryl/blob/main/docs/framework/api/index.md">API</a> ·
+  <a href="https://acrylblends.github.io">acrylblends.github.io</a> ·
+  <a href="https://acryl.dev">acryl.dev</a> ·
+  <a href="https://github.com/acrylblends/acrylblends">GitHub</a>
+</p>
+
+---
+
+```ts
+import { Acryl } from 'acrylblends'
+
+const app = new Acryl()
+app.get('/', (c) => c.text('Hello Acryl!'))
+
+export default app
+```
+
+## Contents
+
+- [Requirements](#requirements)
+- [Quick start](#quick-start)
+- [Start from a template](#start-from-a-template)
+- [A first API](#a-first-api)
+- [Middleware](#middleware)
+- [Validation](#validation)
+- [Typed client](#typed-client)
+- [Testing](#testing)
+- [Serving on Node.js](#serving-on-nodejs)
+- [What is in the package](#what-is-in-the-package)
+- [Upgrading from 0.4](#upgrading-from-04)
+- [The acrylblends command](#the-acrylblends-command)
+- [Links](#links)
+- [License](#license)
+
+## Requirements
+
+- **Node.js 22.19 or newer.** Node.js is the verified runtime, and it runs `.ts` files directly, so there is no build step.
+- **Bun** runs the same app (`export default app`) and is experimental.
+- `acrylblends` has no dependencies. Its types need only Node's types (`@types/node`), not the DOM library.
+
+## Quick start
+
+Create a folder and install the package:
+
+```sh
+mkdir my-app && cd my-app
+npm init -y
+npm pkg set type=module
+npm install acrylblends
+```
+
+Write the app in `index.ts`:
+
+```ts
+import { Acryl } from 'acrylblends'
+
+const app = new Acryl()
+
+app.get('/', (c) => c.text('Hello Acryl!'))
+
+export default app
+```
+
+Serve it on Node.js with the adapter in `server.ts`:
+
+```ts
+import { serve } from 'acrylblends/node-server'
+import app from './index.ts'
+
+serve({ fetch: app.fetch, port: 3000 }, (info) => {
+  console.log(`Listening on http://localhost:${info.port}`)
+})
+```
+
+Run it and open http://localhost:3000:
+
+```sh
+node server.ts
+```
+
+For Bun, `bun run index.ts` serves the same `export default app`.
+
+## Start from a template
+
+`create-acrylblends` creates a ready project with `dev`, `test` and `start` scripts:
+
+```sh
+npm create acrylblends@latest my-app
+cd my-app
+npm install
+npm run dev
+```
+
+The `nodejs` template is a minimal Acryl app. `bun` is the same for Bun (experimental). `acryl-app` is a Cordis app built from plugins,
+with an agent that can extend it while it runs. See the
+[create-acrylblends guide](https://github.com/acryldev/acryl/blob/main/docs/framework/guides/create-acrylblends.md).
+
+## A first API
+
+```ts
+import { Acryl } from 'acrylblends'
+import { HTTPException } from 'acrylblends/http-exception'
+
+type Book = { id: string, title: string }
+const books = new Map<string, Book>()
+
+const app = new Acryl()
+
+app.get('/api/books', (c) => c.json([...books.values()]))
+
+app.get('/api/books/:id', (c) => {
+  const book = books.get(c.req.param('id'))
+  if (book === undefined) throw new HTTPException(404, { message: 'no such book' })
+  return c.json(book)
+})
+
+app.post('/api/books', async (c) => {
+  const { title } = await c.req.json<{ title: string }>()
+  const book = { id: crypto.randomUUID(), title }
+  books.set(book.id, book)
+  return c.json(book, 201)
+})
+
+app.notFound((c) => c.json({ error: 'not found' }, 404))
+app.onError((error, c) => error instanceof HTTPException ? error.getResponse() : c.json({ error: 'internal error' }, 500))
+
+export default app
+```
+
+Read more: [Routing](https://github.com/acryldev/acryl/blob/main/docs/framework/api/routing.md),
+[Context](https://github.com/acryldev/acryl/blob/main/docs/framework/api/context.md),
+[Request](https://github.com/acryldev/acryl/blob/main/docs/framework/api/request.md),
+[Exceptions](https://github.com/acryldev/acryl/blob/main/docs/framework/api/exception.md).
+
+## Middleware
+
+Each built-in middleware has its own subpath:
+
+```ts
+import { Acryl } from 'acrylblends'
+import { cors } from 'acrylblends/cors'
+import { logger } from 'acrylblends/logger'
+import { secureHeaders } from 'acrylblends/secure-headers'
+import { bearerAuth } from 'acrylblends/bearer-auth'
+
+const app = new Acryl()
+
+app.use(logger())
+app.use(secureHeaders())
+app.use('/api/*', cors())
+app.use('/admin/*', bearerAuth({ token: process.env.ADMIN_TOKEN ?? '' }))
+```
+
+Built in: `basic-auth`, `bearer-auth`, `body-limit`, `combine`, `compress`, `context-storage`, `cors`, `csrf`, `etag`, `ip-restriction`,
+`jwk`, `jwt`, `language`, `logger`, `method-not-allowed`, `method-override`, `powered-by`, `pretty-json`, `request-id`, `secure-headers`,
+`serve-static`, `timeout`, `timing`, `trailing-slash`, plus ACRYL's `loopback-only`. Each one is documented under
+[Middleware](https://github.com/acryldev/acryl/tree/main/docs/framework/middleware/builtin). To write your own, see the
+[middleware guide](https://github.com/acryldev/acryl/blob/main/docs/framework/guides/middleware.md).
+
+## Validation
+
+`acrylblends/validator` validates any part of a request: `json`, `form`, `query`, `param`, `header`, `cookie`. The validated value is typed
+in the handler:
+
+```ts
+import { Acryl } from 'acrylblends'
+import { validator } from 'acrylblends/validator'
+
+const app = new Acryl()
+
+app.post(
+  '/api/books',
+  validator('json', (value, c) => {
+    const title = (value as { title?: unknown }).title
+    if (typeof title !== 'string' || title === '') return c.json({ error: 'title is required' }, 400)
+    return { title }
+  }),
+  (c) => c.json({ title: c.req.valid('json').title }, 201),
+)
+```
+
+`acrylblends/schema-validator` drives the same validator with any [Standard Schema](https://standardschema.dev) library (Zod, Valibot,
+ArkType and others). See the [validation guide](https://github.com/acryldev/acryl/blob/main/docs/framework/guides/validation.md).
+
+## Typed client
+
+Export the app's type, and `acrylblends/client` calls its routes with typed paths, inputs and answers:
+
+```ts
+// api.ts
+import { Acryl } from 'acrylblends'
+
+const app = new Acryl().get('/api/hello', (c) => c.json({ message: 'Hello Acryl!' }))
+export type AppType = typeof app
+export default app
+```
+
+```ts
+// client.ts
+import { hc } from 'acrylblends/client'
+import type { AppType } from './api.ts'
+
+const client = hc<AppType>('http://localhost:3000')
+const answer = await client.api.hello.$get()
+console.log((await answer.json()).message)
+```
+
+See [RPC](https://github.com/acryldev/acryl/blob/main/docs/framework/guides/rpc.md).
+
+## Testing
+
+`app.request()` answers a request in process, with no server and no port, so tests need nothing else running:
+
+```ts
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import app from './index.ts'
+
+test('GET / says hello', async () => {
+  const response = await app.request('/')
+  assert.equal(response.status, 200)
+  assert.equal(await response.text(), 'Hello Acryl!')
+})
+```
+
+Run it with `node --test`. `acrylblends/testing` adds `testClient`, the typed client over `app.request()`. See the
+[testing guide](https://github.com/acryldev/acryl/blob/main/docs/framework/guides/testing.md).
+
+## Serving on Node.js
+
+`acrylblends/node-server` serves any Acryl app on Node's `http` module (or `http2` and `https` with `createServer`), streams bodies, aborts
+`c.req.raw.signal` when the client goes away, and serves files:
+
+```ts
+import { Acryl } from 'acrylblends'
+import { serve } from 'acrylblends/node-server'
+import { serveStatic } from 'acrylblends/node-server/serve-static'
+import { getConnInfo } from 'acrylblends/node-server/conninfo'
+
+const app = new Acryl()
+app.use('/static/*', serveStatic({ root: './' }))
+app.get('/ip', (c) => c.text(getConnInfo(c).remote.address ?? 'unknown'))
+
+const server = serve({ fetch: app.fetch, port: 3000, hostname: '127.0.0.1' })
+process.on('SIGTERM', () => { server.close() })
+```
+
+See [Node.js](https://github.com/acryldev/acryl/blob/main/docs/framework/getting-started/nodejs.md).
+
+## What is in the package
+
+| Import | What |
+| --- | --- |
+| `acrylblends` | `Acryl`, `Context`, `AcrylRequest`, and the types |
+| `acrylblends/<middleware>` | each built-in middleware, for example `acrylblends/cors` |
+| `acrylblends/validator`, `acrylblends/schema-validator` | request validation |
+| `acrylblends/client`, `acrylblends/testing` | the typed client and its in-process test version |
+| `acrylblends/accepts`, `adapter`, `cookie`, `factory`, `html`, `route`, `streaming`, `ws`, `conninfo` | helpers ([helpers docs](https://github.com/acryldev/acryl/tree/main/docs/framework/helpers)) |
+| `acrylblends/http-exception` | `HTTPException` |
+| `acrylblends/router/*` | the routers: `reg-exp-router`, `smart-router`, `trie-router`, `pattern-router`, `linear-router` ([routers](https://github.com/acryldev/acryl/blob/main/docs/framework/concepts/routers.md)) |
+| `acrylblends/utils/*` | the utilities the framework is built from |
+| `acrylblends/node-server` | `serve`, `createAdaptorServer`, `getRequestListener`; with `node-server/serve-static` and `node-server/conninfo` |
+
+Every subpath is listed in the package's `exports`. JSX, SSG, the cache, mount, proxy and dev helpers and other runtimes' adapters are
+being ported. The docs mark them "not yet available" until they ship
+([FAQ](https://github.com/acryldev/acryl/blob/main/docs/framework/guides/faq.md)).
+
+To extend the context's typed variables, augment the root module:
+
+```ts
+declare module 'acrylblends' {
+  interface ContextVariableMap {
+    user: string
+  }
+}
+```
+
+## Upgrading from 0.4
+
+From 0.5 the package's root is the framework. `App` and `AppRequest`, the 0.4 names, still work as deprecated aliases of `Acryl` and
+`AcrylRequest` for one release. The scaffolding API that was the root in 0.4 is now `acrylblends/cli`. See
+[Migration from 0.4](https://github.com/acryldev/acryl/blob/main/docs/framework/cordis/migration-from-0-4.md).
+
+## The acrylblends command
+
+The package also carries the `acrylblends` command. It scaffolds Cordis apps with ACRYL's plugins as code you own (instance, settings,
+plugins installed while the app runs, an agent that builds plugins, durable tasks, the app as data in `blend.yaml`, a save that refuses
+secrets):
+
+```sh
+npx acrylblends init my-app --agent -y
+cd my-app && npm install && npm run dev
+```
+
+See the [ACRYLBLENDS documentation](https://github.com/acrylblends/acrylblends/blob/main/docs/README.md) and
+[Acryl in a Cordis app](https://github.com/acryldev/acryl/blob/main/docs/framework/cordis/acryl-in-a-cordis-app.md).
+
+## Links
+
+| | |
+| --- | --- |
+| Framework documentation | https://github.com/acryldev/acryl/blob/main/docs/framework/README.md |
+| ACRYLBLENDS website | https://acrylblends.github.io |
+| ACRYL website | https://acryl.dev |
+| This package's source and issues | https://github.com/acrylblends/acrylblends ([issues](https://github.com/acrylblends/acrylblends/issues)) |
+| The framework's source | https://github.com/acryldev/acryl (`plugins/acryl-router`, `plugins/acryl-node-server`) |
+| For coding agents | https://github.com/acryldev/acryl/blob/main/docs/framework/agents/index.md |
+| npm | https://www.npmjs.com/package/acrylblends |
+
+## License
+
+MIT. Copyright (c) 2026 WebBoxes s.r.o. The framework is ported from MIT-licensed open-source projects. Their notices are kept in the
+package's `LICENSE` file.

package/docs/framework/UPSTREAM.md

@@ -1,3 +1,3 @@
 # Generated copy
 
-This folder is a copy of `docs/framework` of acryldev/acryl at commit `f5151e7f0c4de3b81bddb5cc686b5ef329e48e1c`, made by `scripts/sync-framework.mjs`. Do not edit it here: change the text in ACRYL and sync again. `pnpm run verify:framework` fails when a page differs from the recorded digest.
+This folder is a copy of `docs/framework` of acryldev/acryl at commit `5743482e4199ded676a77f594bce15fd4aa0ca2f`, made by `scripts/sync-framework.mjs`. Do not edit it here: change the text in ACRYL and sync again. `pnpm run verify:framework` fails when a page differs from the recorded digest.

package/docs/framework/cordis/migration-from-dsh-webserver.md

@@ -91,6 +91,12 @@ an `Allow` header on every route; a missing or wrong agent-hook token is 401 wit
 must be the app's own loopback address. Its routes refuse an in-process call on purpose (the guard needs a socket to check), so its tests
 run over loopback through the same adapter (`tests/serve-api.ts`), which is the "test over the Host" below.
 
+`acryl-agent-control` (the door `acryl control`, workers and the MCP config use) moved the same way and kept its trust model exactly:
+operator routes still answer a non-loopback peer or a missing or wrong secret with 403 `{ "error": "forbidden" }`, which `acryl control`
+reads as "refused", never the bearer middleware's 401. What changed there: an oversized body is 413 (was 400), a wrong method's `Allow`
+lists what the router serves (`GET, HEAD` for the audit log), and a page route's refusal carries `loopbackOnly`'s message instead of
+`forbidden`. Only the page channel's WebSocket stays a webServer upgrade.
+
 ## Completion check
 
 A capability is migrated when:

package/docs/framework/upstream.json

@@ -2,8 +2,8 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "docs/framework",
-    "commit": "f5151e7f0c4de3b81bddb5cc686b5ef329e48e1c"
+    "commit": "5743482e4199ded676a77f594bce15fd4aa0ca2f"
   },
   "files": 87,
-  "digest": "sha256:fcaa5ddb5ba4b3912151959e2031c8463d1a61ce543057ca328ebdd6e2e63d4a"
+  "digest": "sha256:31bf1c46fbe74d7d2664b3b935a18bd916b8cab1b9ee9c2b006b8a75617a04f6"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acrylblends",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "The Acryl web framework (import { Acryl } from \"acrylblends\") and the acrylblends command that scaffolds Cordis apps.",
   "license": "MIT",
   "type": "module",

package/plugins/acryl-inspect/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-inspect",
-    "commit": "f5151e7f0c4de3b81bddb5cc686b5ef329e48e1c"
+    "commit": "5743482e4199ded676a77f594bce15fd4aa0ca2f"
   },
   "vendored": [
     "src",

package/plugins/acryl-node-server/tests/adapter/server.test.ts

@@ -186,6 +186,7 @@ describe('various response body types', () => {
     const largeText = 'a'.repeat(1024 * 1024 * 10)
     let server: ServerType
     let resolveReadableStreamPromise: () => void
+    let resolveReadableStreamFirstChunkPromise: () => void
     let resolveEventStreamPromise: () => void
     let resolveEventStreamWithoutTransferEncodingPromise: () => void
     beforeAll(() => {
@@ -223,11 +224,17 @@ describe('various response body types', () => {
       const readableStreamPromise = new Promise<void>((resolve) => {
         resolveReadableStreamPromise = resolve
       })
+      const readableStreamFirstChunkPromise = new Promise<void>((resolve) => {
+        resolveReadableStreamFirstChunkPromise = resolve
+      })
       app.get('/readable-stream', () => {
         const stream = new ReadableStream({
           async start(controller) {
             await readableStreamPromise
             controller.enqueue('Hello!')
+            // The second chunk waits until the client has the first, so the two arrive as two reads on every platform (TCP may join
+            // two back-to-back writes into one read, as it does on Windows).
+            await readableStreamFirstChunkPromise
             controller.enqueue(' Node!')
             controller.close()
           },
@@ -376,6 +383,9 @@ describe('various response body types', () => {
             expect(headers.get('transfer-encoding')).toBe('chunked')
             resolveReadableStreamPromise()
           },
+          onChunk: (_chunk, index) => {
+            if (index === 0) resolveReadableStreamFirstChunkPromise()
+          },
         }
       )
       expect(res.status).toBe(200)

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

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-node-server",
-    "commit": "f5151e7f0c4de3b81bddb5cc686b5ef329e48e1c"
+    "commit": "5743482e4199ded676a77f594bce15fd4aa0ca2f"
   },
   "vendored": [
     "src",
@@ -10,7 +10,7 @@
     "LICENSE"
   ],
   "rewrittenSpecifiers": 28,
-  "digest": "sha256:551c97b074171e63d4dd09ae7624b2c4cd15050e4a8021603bc2e2e95ab790b3",
+  "digest": "sha256:2adaa64028c1f2a40ed94c0eacf64d32c8c3b8171b52338cb02bfae2fd56ab7c",
   "testsNotRun": {},
   "notice": [
     "LICENSE"

package/plugins/acryl-router/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-router",
-    "commit": "f5151e7f0c4de3b81bddb5cc686b5ef329e48e1c"
+    "commit": "5743482e4199ded676a77f594bce15fd4aa0ca2f"
   },
   "vendored": [
     "src",

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

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-router-http",
-    "commit": "f5151e7f0c4de3b81bddb5cc686b5ef329e48e1c"
+    "commit": "5743482e4199ded676a77f594bce15fd4aa0ca2f"
   },
   "vendored": [
     "src",

package/plugins/acryl-state/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-state",
-    "commit": "f5151e7f0c4de3b81bddb5cc686b5ef329e48e1c"
+    "commit": "5743482e4199ded676a77f594bce15fd4aa0ca2f"
   },
   "vendored": [
     "src",

package/templates/todo/upstream.json

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