acrylblends 0.7.7 → 0.8.0

package/templates/agent/test/app.test.ts

@@ -1,19 +1,26 @@
 import assert from 'node:assert/strict'
+import { mkdirSync } from 'node:fs'
 import { mkdtemp, rm } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
+import { createServer } from 'node:net'
 import { join } from 'node:path'
 import { test } from 'node:test'
 import { fileURLToPath } from 'node:url'
+import { pinnedInstance, withPort } from '../plugins/instance/index.ts'
 import { type App, createApp } from '../src/app.ts'
-import { pinnedInstance, withPort } from '../src/plugins/instance/index.ts'
 import { APP_NAME } from '../src/routes.ts'
 
+/** Throwaway homes live inside the project (`.acrylblends/` is ignored by git): a sandboxed agent may not write to the system temp folder. */
+const scratch = join(fileURLToPath(new URL('..', import.meta.url)), '.acrylblends', 'test')
+mkdirSync(scratch, { recursive: true })
+
 const projectRoot = fileURLToPath(new URL('..', import.meta.url))
 
 /** Boot the app in a throwaway home on any free port, run the test, always stop it and remove the home. */
 async function withApp(run: (app: App) => Promise<void>) {
-  const home = await mkdtemp(join(tmpdir(), 'app-test-'))
-  const app = await createApp(withPort(pinnedInstance(home, { root: projectRoot }), 0))
+  const home = await mkdtemp(join(scratch, 'app-test-'))
+  const app = await createApp(withPort(pinnedInstance(home, { root: projectRoot }), 0), {
+    listen: false,
+  })
   try {
     await run(app)
   } finally {
@@ -24,21 +31,35 @@ async function withApp(run: (app: App) => Promise<void>) {
 
 test('serves the index route', () =>
   withApp(async (app) => {
-    const response = await fetch(`${app.url}/`)
+    const response = await app.root.router.request(`/`)
     assert.equal(response.status, 200)
     assert.deepEqual(await response.json(), { app: APP_NAME, ok: true })
   }))
 
 test('answers health checks and 404 for unknown paths', () =>
   withApp(async (app) => {
-    assert.equal((await fetch(`${app.url}/health`)).status, 200)
-    const missing = await fetch(`${app.url}/nope`)
+    assert.equal((await app.root.router.request(`/health`)).status, 200)
+    const missing = await app.root.router.request(`/nope`)
     assert.equal(missing.status, 404)
     await missing.body?.cancel()
   }))
 
-test('stops listening when stopped', async () => {
-  const home = await mkdtemp(join(tmpdir(), 'app-test-'))
+/** A sandbox may forbid listening on a port (Codex's workspace-write does); the one test that starts the real server is skipped there, and says so. */
+const canListen = await new Promise<boolean>((done) => {
+  const probe = createServer()
+  probe.once('error', () => done(false))
+  probe.listen(0, '127.0.0.1', () => probe.close(() => done(true)))
+})
+const skip = canListen ? false : 'this environment does not allow listening on a port'
+if (!canListen)
+  console.log(
+    `skipped: the test that starts the real server (${skip}); every other test ran in process`,
+  )
+
+test('stops listening when stopped', { skip }, async () => {
+  const home = await mkdtemp(join(scratch, 'app-test-'))
+  // The door is left out (ACRYL_DOOR=off): one process at a time serves a folder's door.
+  process.env.ACRYL_DOOR = 'off'
   const app = await createApp(withPort(pinnedInstance(home, { root: projectRoot }), 0))
   await app.stop()
   await assert.rejects(fetch(`${app.url}/health`))

package/templates/agent/test/builder.test.ts

@@ -1,18 +1,23 @@
 import assert from 'node:assert/strict'
+import { mkdirSync } from 'node:fs'
 import { mkdtemp, rm } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { test } from 'node:test'
+import { fileURLToPath } from 'node:url'
+import { pinnedInstance, withPort } from '../plugins/instance/index.ts'
 import { createApp } from '../src/app.ts'
-import { pinnedInstance, withPort } from '../src/plugins/instance/index.ts'
+
+/** Throwaway homes live inside the project (`.acrylblends/` is ignored by git): a sandboxed agent may not write to the system temp folder. */
+const scratch = join(fileURLToPath(new URL('..', import.meta.url)), '.acrylblends', 'test')
+mkdirSync(scratch, { recursive: true })
 
 /** The agent extends the running app through POST /ask; a restart keeps what it built. */
 test('the agent builds, updates, protects and removes a plugin in the running app, and a restart keeps it', async () => {
-  const project = await mkdtemp(join(tmpdir(), 'builder-project-'))
+  const project = await mkdtemp(join(scratch, 'builder-project-'))
   const chosen = withPort(pinnedInstance(join(project, '.acrylblends'), { root: project }), 0)
-  let app = await createApp(chosen)
+  let app = await createApp(chosen, { listen: false })
   const ask = async (question: string) => {
-    const response = await fetch(`${app.url}/ask`, {
+    const response = await app.root.router.request(`/ask`, {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
       body: JSON.stringify({ question }),
@@ -20,7 +25,7 @@ test('the agent builds, updates, protects and removes a plugin in the running ap
     return ((await response.json()) as { output: string }).output
   }
   const hello = async () => {
-    const response = await fetch(`${app.url}/hello`)
+    const response = await app.root.router.request(`/hello`)
     return response.status === 200
       ? ((await response.json()) as { text: string }).text
       : response.status
@@ -36,14 +41,14 @@ test('the agent builds, updates, protects and removes a plugin in the running ap
     // The broken version stays on disk, so put the working one back before restarting.
     await ask('update route hello /hello Bonjour')
     await app.stop()
-    app = await createApp(chosen)
+    app = await createApp(chosen, { listen: false })
     assert.equal(await hello(), 'Bonjour')
 
     assert.equal(await ask('remove plugin hello'), 'hello: done.')
     assert.equal(await hello(), 404)
 
     // Every run is a durable task that owns its tool calls, and the records survived the restart.
-    const records = (await (await fetch(`${app.url}/tasks`)).json()) as Array<{
+    const records = (await (await app.root.router.request(`/tasks`)).json()) as Array<{
       kind: string
       status: string
       parent?: string
@@ -63,12 +68,12 @@ test('the agent builds, updates, protects and removes a plugin in the running ap
 })
 
 test('with approval on, an install waits for the owner; approving it makes it live', async () => {
-  const project = await mkdtemp(join(tmpdir(), 'approval-project-'))
+  const project = await mkdtemp(join(scratch, 'approval-project-'))
   const chosen = withPort(pinnedInstance(join(project, '.acrylblends'), { root: project }), 0)
-  const app = await createApp(chosen, { values: { approval: true } })
+  const app = await createApp(chosen, { values: { approval: true }, listen: false })
   const post = async (path: string, body: unknown) =>
     (await (
-      await fetch(`${app.url}${path}`, {
+      await app.root.router.request(`${path}`, {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify(body),
@@ -79,8 +84,8 @@ test('with approval on, an install waits for the owner; approving it makes it li
       (await post('/ask', { question: 'create route hello /hello Hello' })).output,
       "hello: waiting for the owner's approval.",
     )
-    assert.equal((await fetch(`${app.url}/hello`)).status, 404)
-    const listed = (await (await fetch(`${app.url}/extensions`)).json()) as {
+    assert.equal((await app.root.router.request(`/hello`)).status, 404)
+    const listed = (await (await app.root.router.request(`/extensions`)).json()) as {
       waitingForApproval: Array<{ name: string }>
     }
     assert.deepEqual(
@@ -91,8 +96,10 @@ test('with approval on, an install waits for the owner; approving it makes it li
       ((await post('/extensions/approve', { name: 'hello' })) as { state?: string }).state,
       'active',
     )
-    assert.deepEqual(await (await fetch(`${app.url}/hello`)).json(), { text: 'Hello' })
-    const tasks = (await (await fetch(`${app.url}/tasks`)).json()) as Array<{ manifest?: string }>
+    assert.deepEqual(await (await app.root.router.request(`/hello`)).json(), { text: 'Hello' })
+    const tasks = (await (await app.root.router.request(`/tasks`)).json()) as Array<{
+      manifest?: string
+    }>
     assert.ok(
       tasks.length > 0 && tasks.every((task) => /^sha256:[0-9a-f]{64}$/.test(task.manifest ?? '')),
     )
@@ -103,13 +110,13 @@ test('with approval on, an install waits for the owner; approving it makes it li
 })
 
 test('the agent builds a sandboxed tool, calls it, and the sandbox refuses a tool that reads outside its folder', async () => {
-  const project = await mkdtemp(join(tmpdir(), 'tool-project-'))
+  const project = await mkdtemp(join(scratch, 'tool-project-'))
   const chosen = withPort(pinnedInstance(join(project, '.acrylblends'), { root: project }), 0)
-  const app = await createApp(chosen)
+  const app = await createApp(chosen, { listen: false })
   const ask = async (question: string) =>
     (
       (await (
-        await fetch(`${app.url}/ask`, {
+        await app.root.router.request(`/ask`, {
           method: 'POST',
           headers: { 'content-type': 'application/json' },
           body: JSON.stringify({ question }),
@@ -121,7 +128,7 @@ test('the agent builds a sandboxed tool, calls it, and the sandbox refuses a too
     assert.equal(await ask('run tool triple 14'), '{"n":42}')
     const refused = await ask('spy tool snoop')
     assert.match(refused, /^Refused: its check failed: denied:/)
-    const listed = (await (await fetch(`${app.url}/extensions`)).json()) as {
+    const listed = (await (await app.root.router.request(`/extensions`)).json()) as {
       installed: Array<{ name: string }>
     }
     assert.deepEqual(
@@ -135,13 +142,13 @@ test('the agent builds a sandboxed tool, calls it, and the sandbox refuses a too
 })
 
 test('what happens is streamed from the state cells: the run as a task, and the install as an extension', async () => {
-  const project = await mkdtemp(join(tmpdir(), 'events-project-'))
+  const project = await mkdtemp(join(scratch, 'events-project-'))
   const chosen = withPort(pinnedInstance(join(project, '.acrylblends'), { root: project }), 0)
-  const app = await createApp(chosen)
+  const app = await createApp(chosen, { listen: false })
   const controller = new AbortController()
   /** Follow one server-sent stream: its text so far. */
   const follow = async (path: string) => {
-    const stream = await fetch(`${app.url}${path}`, { signal: controller.signal })
+    const stream = await app.root.router.request(`${path}`, { signal: controller.signal })
     assert.equal(stream.status, 200, path)
     const reader = stream.body!.getReader()
     const decoder = new TextDecoder()
@@ -153,12 +160,12 @@ test('what happens is streamed from the state cells: the run as a task, and the
         seen.text += decoder.decode(value, { stream: true })
       }
     })().catch(() => undefined)
-    return { seen, pump }
+    return { seen, pump, reader }
   }
   try {
     const tasksStream = await follow('/api/state/tasks/events')
     const extensionsStream = await follow('/api/state/extensions/events')
-    await fetch(`${app.url}/ask`, {
+    await app.root.router.request(`/ask`, {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
       body: JSON.stringify({ question: 'create route hello /hello Hello' }),
@@ -185,7 +192,11 @@ test('what happens is streamed from the state cells: the run as a task, and the
       arrived(extensionsStream.seen, /"name":"hello"[^\n]*"state":"active"/),
       'the extension is reported',
     )
+    // In process there is no socket to close: the readers are cancelled, which ends the streams and lets the pumps finish.
     controller.abort()
+    await Promise.all([tasksStream.reader.cancel(), extensionsStream.reader.cancel()]).catch(
+      () => undefined,
+    )
     await Promise.all([tasksStream.pump, extensionsStream.pump])
   } finally {
     await app.stop()

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

@@ -1,16 +1,20 @@
 import assert from 'node:assert/strict'
+import { mkdirSync } from 'node:fs'
 import { mkdtemp, rm } from 'node:fs/promises'
-import { createServer } from 'node:http'
-import type { AddressInfo } from 'node:net'
-import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { test } from 'node:test'
+import { fileURLToPath } from 'node:url'
+import { pinnedInstance, withPort } from '../plugins/instance/index.ts'
 import { createApp } from '../src/app.ts'
-import { pinnedInstance, withPort } from '../src/plugins/instance/index.ts'
+
+/** Throwaway homes live inside the project (`.acrylblends/` is ignored by git): a sandboxed agent may not write to the system temp folder. */
+const scratch = join(fileURLToPath(new URL('..', import.meta.url)), '.acrylblends', 'test')
+mkdirSync(scratch, { recursive: true })
 
 /** A plugin no scripted command knows: the model writes it from scratch. */
 const COUNTER = `import type { Context } from '@deepseek-ai/cordis'
 import { Acryl } from 'acrylblends'
+
 export const name = 'counter'
 export const inject = ['router']
 export function apply(ctx: Context) {
@@ -45,42 +49,43 @@ async function modelApi() {
     },
     { content: 'I built a counter: GET /count.' },
   ]
-  const server = createServer(async (request, response) => {
-    for await (const _ of request) {
-      // the body is not needed: the replies are in order
-    }
-    response.writeHead(200, { 'content-type': 'application/json' })
-    response.end(
-      JSON.stringify({ choices: [{ message: replies.shift() ?? { content: 'no more' } }] }),
-    )
-  })
-  await new Promise<void>((done) => server.listen(0, '127.0.0.1', done))
+  // The model API is answered in process: the global fetch is wrapped for the model's address, so no port is needed.
+  const realFetch = globalThis.fetch
+  const url = 'http://model.test/v1'
+  globalThis.fetch = async (input, init) => {
+    const target = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
+    if (!target.startsWith(url)) return realFetch(input, init)
+    return Response.json({ choices: [{ message: replies.shift() ?? { content: 'no more' } }] })
+  }
   return {
-    url: `http://127.0.0.1:${(server.address() as AddressInfo).port}/v1`,
-    close: () => new Promise<void>((done) => server.close(() => done())),
+    url,
+    close: async () => {
+      globalThis.fetch = realFetch
+    },
   }
 }
 
 test('with a real model, the agent writes a new Cordis plugin and the running app serves it', async () => {
   const api = await modelApi()
-  const project = await mkdtemp(join(tmpdir(), 'model-project-'))
+  const project = await mkdtemp(join(scratch, 'model-project-'))
   const app = await createApp(
     withPort(pinnedInstance(join(project, '.acrylblends'), { root: project }), 0),
     {
       model: { baseUrl: api.url, model: 'test' },
+      listen: false,
     },
   )
   try {
     const answer = await (
-      await fetch(`${app.url}/ask`, {
+      await app.root.router.request(`/ask`, {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify({ question: 'add a counter route' }),
       })
     ).json()
     assert.equal((answer as { output: string }).output, 'I built a counter: GET /count.')
-    assert.deepEqual(await (await fetch(`${app.url}/count`)).json(), { count: 1 })
-    assert.deepEqual(await (await fetch(`${app.url}/count`)).json(), { count: 2 })
+    assert.deepEqual(await (await app.root.router.request(`/count`)).json(), { count: 1 })
+    assert.deepEqual(await (await app.root.router.request(`/count`)).json(), { count: 2 })
   } finally {
     await app.stop()
     await api.close()

package/templates/agent/tsconfig.json

@@ -13,58 +13,56 @@
     "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"],
-      "acrylblends/jsx": ["./src/plugins/acryl-router/src/core/jsx/index.ts"],
-      "acrylblends/jsx/jsx-runtime": ["./src/plugins/acryl-router/src/core/jsx/jsx-runtime.ts"],
-      "acrylblends/jsx/jsx-dev-runtime": [
-        "./src/plugins/acryl-router/src/core/jsx/jsx-dev-runtime.ts"
-      ],
-      "acrylblends/jsx/streaming": ["./src/plugins/acryl-router/src/core/jsx/streaming.ts"]
+      "acrylblends": ["./plugins/acryl-router/src/index.ts"],
+      "acrylblends/conninfo": ["./plugins/acryl-router/src/index.ts"],
+      "acrylblends/http-exception": ["./plugins/acryl-router/src/index.ts"],
+      "acrylblends/types": ["./plugins/acryl-router/src/index.ts"],
+      "acrylblends/client": ["./plugins/acryl-router/src/client.ts"],
+      "acrylblends/basic-auth": ["./plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/bearer-auth": ["./plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/body-limit": ["./plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/combine": ["./plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/compress": ["./plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/context-storage": ["./plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/cors": ["./plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/csrf": ["./plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/etag": ["./plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/ip-restriction": ["./plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/jwk": ["./plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/jwt": ["./plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/language": ["./plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/logger": ["./plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/loopback-only": ["./plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/method-not-allowed": ["./plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/method-override": ["./plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/powered-by": ["./plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/pretty-json": ["./plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/request-id": ["./plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/secure-headers": ["./plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/serve-static": ["./plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/timeout": ["./plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/timing": ["./plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/trailing-slash": ["./plugins/acryl-router/src/middleware/index.ts"],
+      "acrylblends/accepts": ["./plugins/acryl-router/src/helpers/index.ts"],
+      "acrylblends/cookie": ["./plugins/acryl-router/src/helpers/index.ts"],
+      "acrylblends/factory": ["./plugins/acryl-router/src/helpers/index.ts"],
+      "acrylblends/html": ["./plugins/acryl-router/src/helpers/index.ts"],
+      "acrylblends/route": ["./plugins/acryl-router/src/helpers/index.ts"],
+      "acrylblends/schema-validator": ["./plugins/acryl-router/src/helpers/index.ts"],
+      "acrylblends/streaming": ["./plugins/acryl-router/src/helpers/index.ts"],
+      "acrylblends/testing": ["./plugins/acryl-router/src/helpers/index.ts"],
+      "acrylblends/validator": ["./plugins/acryl-router/src/helpers/index.ts"],
+      "acrylblends/ws": ["./plugins/acryl-router/src/helpers/index.ts"],
+      "acryl-router": ["./plugins/acryl-router/src/index.ts"],
+      "acryl-router/middleware": ["./plugins/acryl-router/src/middleware/index.ts"],
+      "acryl-router/helpers": ["./plugins/acryl-router/src/helpers/index.ts"],
+      "acrylblends/jsx": ["./plugins/acryl-router/src/core/jsx/index.ts"],
+      "acrylblends/jsx/jsx-runtime": ["./plugins/acryl-router/src/core/jsx/jsx-runtime.ts"],
+      "acrylblends/jsx/jsx-dev-runtime": ["./plugins/acryl-router/src/core/jsx/jsx-dev-runtime.ts"],
+      "acrylblends/jsx/streaming": ["./plugins/acryl-router/src/core/jsx/streaming.ts"]
     },
     "jsx": "react-jsx",
     "jsxImportSource": "#acryl-jsx"
   },
-  "include": ["src", "test", "extensions"]
+  "include": ["src", "test", "plugins"]
 }

package/templates/blank/AGENTS.md

@@ -2,4 +2,4 @@
 ## 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/`.
+another library plugin (for example `acryl-state`) into `plugins/`.

package/templates/blank/README.md

@@ -10,13 +10,13 @@ npm test
 npm run check      # type-check
 ```
 
-- `src/main.ts` chooses where the app lives (`src/plugins/instance`) and starts it.
+- `src/main.ts` chooses where the app lives (`plugins/instance`) and starts it.
 - `blend.yaml` is the app as data: which plugins it mounts, in what order, with what config and parameters. Switch
   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: 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.
+- `plugins/` holds the plugins copied from the ACRYLBLENDS library. They are yours now; edit them freely.
   Add more with `acrylblends add <plugin>`.
 
 `npm run save -- "message"` commits the app with git (and pushes when it has a remote). It refuses a file that looks like

package/templates/blank/gitignore

@@ -1,2 +1,3 @@
 node_modules/
 .acrylblends/
+.acryl/

package/templates/blank/package.json

@@ -4,20 +4,20 @@
   "private": true,
   "type": "module",
   "imports": {
-    "#acryl-jsx/jsx-runtime": "./src/plugins/acryl-router/src/core/jsx/jsx-runtime.ts",
-    "#acryl-jsx/jsx-dev-runtime": "./src/plugins/acryl-router/src/core/jsx/jsx-dev-runtime.ts"
+    "#acryl-jsx/jsx-runtime": "./plugins/acryl-router/src/core/jsx/jsx-runtime.ts",
+    "#acryl-jsx/jsx-dev-runtime": "./plugins/acryl-router/src/core/jsx/jsx-dev-runtime.ts"
   },
   "engines": {
     "node": ">=22.19.0"
   },
   "scripts": {
-    "start": "node --import ./src/plugins/acryl-node-server/src/register.ts src/main.ts",
-    "dev": "node --watch --import ./src/plugins/acryl-node-server/src/register.ts src/main.ts",
-    "test": "node --import ./src/plugins/acryl-node-server/src/register.ts --test \"test/**/*.test.{ts,tsx}\"",
+    "start": "node --import ./plugins/acryl-node-server/src/register.ts src/main.ts",
+    "dev": "node --watch --import ./plugins/acryl-node-server/src/register.ts src/main.ts",
+    "test": "node --import ./plugins/acryl-node-server/src/register.ts --test \"test/**/*.test.{ts,tsx}\"",
     "check": "tsc --noEmit",
-    "lock": "node src/plugins/manifest/lock.ts",
-    "save": "node src/plugins/save/cli.ts",
-    "upgrade": "node src/plugins/manifest/upgrade-cli.ts"
+    "lock": "node plugins/manifest/lock.ts",
+    "save": "node plugins/save/cli.ts",
+    "upgrade": "node plugins/manifest/upgrade-cli.ts"
   },
   "dependencies": {
     "typescript": "6.0.3"

package/templates/blank/src/about.tsx

@@ -1,8 +1,8 @@
-/** A page written in JSX: the scripts in package.json run Node.js with the vendored register hook (src/plugins/acryl-node-server/src/register.ts), which compiles .tsx with this app's own typescript. */
+/** A page written in JSX: the scripts in package.json run Node.js with the vendored register hook (plugins/acryl-node-server/src/register.ts), which compiles .tsx with this app's own typescript. */
 const About = () => (
   <main>
     <h1>About</h1>
-    <p>Rendered on the server with the JSX runtime in src/plugins/acryl-router.</p>
+    <p>Rendered on the server with the JSX runtime in plugins/acryl-router.</p>
   </main>
 )
 

package/templates/blank/src/app.ts

@@ -1,15 +1,15 @@
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { Context, type Fiber } from '@deepseek-ai/cordis'
-import * as nodeServer from './plugins/acryl-node-server/src/index.ts'
-import * as router from './plugins/acryl-router/src/index.ts'
-import { type AppInstance, instance } from './plugins/instance/index.ts'
+import * as nodeServer from '../plugins/acryl-node-server/src/index.ts'
+import * as router from '../plugins/acryl-router/src/index.ts'
+import { type AppInstance, instance } from '../plugins/instance/index.ts'
 import {
   blueprintsIn,
   compose,
   loadManifest,
   type ParameterValue,
-} from './plugins/manifest/index.ts'
+} from '../plugins/manifest/index.ts'
 import { routes } from './routes.ts'
 
 /** The plugins this app's code provides. `blend.yaml` chooses, orders and configures them. */
@@ -30,8 +30,19 @@ export function readManifest(values?: Readonly<Record<string, ParameterValue>>)
   })
 }
 
+/** The manifest without its server row: the app is then reached in process, through `root.router.request`. */
+function withoutServer<M extends { plugins: readonly { use: string }[] }>(manifest: M): M {
+  return {
+    ...manifest,
+    plugins: manifest.plugins.map((row) =>
+      row.use === 'acryl-node-server' ? { ...row, disabled: true } : row,
+    ),
+  }
+}
+
 export interface App {
   readonly root: Context
+  /** The address the server listens on; empty when the app was made with `listen: false`. */
   readonly url: string
   stop(): Promise<void>
 }
@@ -39,7 +50,11 @@ export interface App {
 /** The app: `instance` first (where it lives, chosen at run time), then the manifest's rows in order. */
 export async function createApp(
   chosen: AppInstance,
-  options: { values?: Readonly<Record<string, ParameterValue>> } = {},
+  options: {
+    values?: Readonly<Record<string, ParameterValue>>
+    /** Start the HTTP server (default). Tests pass `false` and call `app.root.router.request(path)`: it needs no port, so it also runs where a sandbox forbids listening. */
+    listen?: boolean
+  } = {},
 ): Promise<App> {
   const manifest = readManifest(options.values)
   const root = new Context()
@@ -47,13 +62,18 @@ export async function createApp(
   await first.await()
   const fibers: Fiber[] = [
     first,
-    ...(await compose(root, manifest, registry, {
-      server: { port: chosen.port.start, scan: chosen.port.scan ? 20 : 0 },
-    })),
+    ...(await compose(
+      root,
+      options.listen === false ? withoutServer(manifest) : manifest,
+      registry,
+      {
+        server: { port: chosen.port.start, scan: chosen.port.scan ? 20 : 0 },
+      },
+    )),
   ]
   return {
     root,
-    url: root.nodeServer.url,
+    url: options.listen === false ? '' : root.nodeServer.url,
     async stop() {
       for (const fiber of [...fibers].reverse()) await fiber.dispose()
     },

package/templates/blank/src/main.ts

@@ -1,6 +1,6 @@
 import { fileURLToPath } from 'node:url'
+import { selectInstance } from '../plugins/instance/index.ts'
 import { createApp } from './app.ts'
-import { selectInstance } from './plugins/instance/index.ts'
 import { APP_NAME } from './routes.ts'
 
 // The composition root: the one place that reads the environment (through selectInstance) and chooses where the app lives.

package/templates/blank/src/routes.ts

@@ -1,6 +1,6 @@
 import type { Context } from '@deepseek-ai/cordis'
+import { Acryl } from '../plugins/acryl-router/src/index.ts'
 import { aboutPage } from './about.tsx'
-import { Acryl } from './plugins/acryl-router/src/index.ts'
 
 export const APP_NAME = '__APP_NAME__'