acrylblends 0.0.0-stage → 0.3.0

package/templates/blank/test/app.test.ts

@@ -0,0 +1,56 @@
+import assert from 'node:assert/strict'
+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 { type App, createApp } from '../src/app.ts'
+import { pinnedInstance, withPort } from '../src/plugins/instance/index.ts'
+import { APP_NAME } from '../src/routes.ts'
+
+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))
+  try {
+    await run(app)
+  } finally {
+    await app.stop()
+    await rm(home, { recursive: true, force: true })
+  }
+}
+
+test('serves the index route', () =>
+  withApp(async (app) => {
+    const response = await fetch(`${app.url}/`)
+    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(missing.status, 404)
+    await missing.body?.cancel()
+  }))
+
+test('stops listening when stopped', async () => {
+  const home = await mkdtemp(join(tmpdir(), 'app-test-'))
+  const app = await createApp(withPort(pinnedInstance(home, { root: projectRoot }), 0))
+  await app.stop()
+  await assert.rejects(fetch(`${app.url}/health`))
+  await rm(home, { recursive: true, force: true })
+})
+
+test('the manifest decides what is mounted: a parameter changes the server, an unknown value is refused', async () => {
+  const { readManifest } = await import('../src/app.ts')
+  const manifest = readManifest()
+  assert.deepEqual(
+    manifest.plugins.map((row) => row.id),
+    ['router', 'routes', 'server'],
+  )
+  assert.throws(() => readManifest({ nothing: 1 }), /parameter-override-unknown/)
+})

package/templates/blank/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "verbatimModuleSyntax": true,
+    "erasableSyntaxOnly": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["src", "test"]
+}

package/templates/todo/README.md

@@ -0,0 +1,27 @@
+# __APP_NAME__
+
+A todo list built on the ACRYL framework: only the router and shared state. The list is a state cell, the routes are on the router, and the list is
+written to a file in the app's home so it survives a restart. `src/todo.ts` is ACRYL's reference app, copied as it is; the files you own are
+`blend.yaml` (what is mounted), `src/app.ts` (the composition) and the tests.
+
+```sh
+npm install
+npm test
+npm run dev          # prints the URL, for example http://127.0.0.1:3100
+```
+
+```sh
+URL=http://127.0.0.1:3100   # the address `npm run dev` printed
+curl -X POST $URL/todo/api -H 'content-type: application/json' -d '{"title":"write the docs"}'   # {"id":1,"title":"write the docs","done":false}
+curl $URL/todo/api                                                                                  # the list
+curl -X PATCH $URL/todo/api/1 -H 'content-type: application/json' -d '{"done":true}'
+curl -X DELETE $URL/todo/api/1
+curl -N $URL/todo/events                                                                            # the list now, then again on every change
+```
+
+The routes only answer a caller on this machine: a request from another site's page (a foreign `Origin`, or `Origin: null`) or addressed to another host name gets `403`.
+
+Open `$URL/todo` for the page. Stop the app and start it again: the list is still there (`<home>/todo.json`, `.acrylblends/` unless `ACRYLBLENDS_HOME` says otherwise).
+
+- `blend.yaml` is the app as data. `npm run lock` records what it is built from; `npm run save` commits it, refusing secrets and public remotes for a private app.
+- The framework plugins are in `src/plugins/acryl-*/src`. Do not edit them: they are ACRYL's, vendored; the text that explains them is in the ACRYLBLENDS docs.

package/templates/todo/blend.yaml

@@ -0,0 +1,25 @@
+# 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.
+apiVersion: blends.acryl.dev/v1alpha1
+kind: Blueprint
+metadata:
+  id: acrylblends.__APP_NAME__
+  name: __APP_NAME__
+  version: 0.1.0
+  visibility: private # `npm run save` never pushes a private app to a public remote
+spec:
+  runtime: cordis
+  parameters:
+    # The address the server listens on.
+    hostname: { type: string, default: 127.0.0.1 }
+  rows:
+    - id: router
+      name: acryl-router
+    - id: state
+      name: acryl-state
+    - id: todo
+      name: todo
+    - id: server
+      name: acryl-node-server
+      config:
+        hostname: "{{parameters.hostname}}"

package/templates/todo/gitignore

@@ -0,0 +1,2 @@
+node_modules/
+.acrylblends/

package/templates/todo/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "__APP_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "start": "node src/main.ts",
+    "dev": "node --watch src/main.ts",
+    "test": "node --test",
+    "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"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "6.0.3"
+  }
+}

package/templates/todo/src/app.ts

@@ -0,0 +1,71 @@
+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 * as state from './plugins/acryl-state/src/index.ts'
+import { type AppInstance, instance } from './plugins/instance/index.ts'
+import {
+  blueprintsIn,
+  compose,
+  loadManifest,
+  type ParameterValue,
+} from './plugins/manifest/index.ts'
+import * as todo from './todo.ts'
+
+/** The plugins this app's code provides. `blend.yaml` chooses, orders and configures them. */
+export const registry = {
+  'acryl-router': router,
+  'acryl-state': state,
+  todo,
+  'acryl-node-server': nodeServer,
+}
+
+export const APP_NAME = '__APP_NAME__'
+
+/** The manifest next to this app's source. */
+export const MANIFEST = join(fileURLToPath(new URL('..', import.meta.url)), 'blend.yaml')
+
+/**
+ * The app's manifest, resolved. A Blend finds its Blueprint in `blueprints/<id>.yaml`; an app that is itself a Blueprint never looks.
+ * `createApp` and the tests read it the same way.
+ */
+export function readManifest(values?: Readonly<Record<string, ParameterValue>>) {
+  return loadManifest(MANIFEST, {
+    known: Object.keys(registry),
+    getBlueprint: blueprintsIn(join(fileURLToPath(new URL('..', import.meta.url)), 'blueprints')),
+    ...(values ? { values } : {}),
+  })
+}
+
+export interface App {
+  readonly root: Context
+  readonly url: string
+  stop(): Promise<void>
+}
+
+/** 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>> } = {},
+): Promise<App> {
+  const manifest = readManifest(options.values)
+  const root = new Context()
+  const first = root.plugin(instance, chosen)
+  await first.await()
+  const fibers: Fiber[] = [
+    first,
+    ...(await compose(root, manifest, registry, {
+      // Runtime values the manifest cannot hold: where the list is kept (in the app's home) and where the server listens.
+      todo: { file: join(chosen.home, 'todo.json') },
+      server: { port: chosen.port.start, scan: chosen.port.scan ? 20 : 0 },
+    })),
+  ]
+  return {
+    root,
+    url: root.nodeServer.url,
+    async stop() {
+      for (const fiber of [...fibers].reverse()) await fiber.dispose()
+    },
+  }
+}

package/templates/todo/src/main.ts

@@ -0,0 +1,19 @@
+import { fileURLToPath } from 'node:url'
+import { APP_NAME, createApp } from './app.ts'
+import { selectInstance } from './plugins/instance/index.ts'
+
+// The composition root: the one place that reads the environment (through selectInstance) and chooses where the app lives.
+const chosen = selectInstance({
+  projectRoot: fileURLToPath(new URL('..', import.meta.url)),
+  env: process.env,
+})
+const app = await createApp(chosen)
+console.log(`${APP_NAME} listening on ${app.url} (data in ${chosen.home})`)
+
+const stop = async () => {
+  await app.stop()
+  console.log('stopped')
+  process.exit(0)
+}
+process.once('SIGINT', stop)
+process.once('SIGTERM', stop)

package/templates/todo/src/page.ts

@@ -0,0 +1,28 @@
+/** The page: plain HTML and a few lines of script; it follows the list through the server-sent event stream. */
+export const PAGE = `<!doctype html>
+<meta charset="utf-8"><title>Todo</title>
+<style>body{font:16px system-ui;max-width:32rem;margin:2rem auto}li{display:flex;gap:.5rem;padding:.25rem 0}.done span{text-decoration:line-through;opacity:.6}</style>
+<h1>Todo</h1>
+<form id="add"><input id="title" placeholder="What needs doing?" autofocus> <button>Add</button></form>
+<ul id="list"></ul>
+<script>
+const list = document.getElementById('list')
+const send = (url, method, body) => fetch(url, { method, headers: { 'content-type': 'application/json' }, body: body && JSON.stringify(body) })
+document.getElementById('add').onsubmit = async event => {
+  event.preventDefault()
+  const input = document.getElementById('title')
+  await send('/todo/api', 'POST', { title: input.value })
+  input.value = ''
+}
+new EventSource('/todo/events').onmessage = event => {
+  list.replaceChildren(...JSON.parse(event.data).map(todo => {
+    const item = document.createElement('li')
+    item.className = todo.done ? 'done' : ''
+    const box = Object.assign(document.createElement('input'), { type: 'checkbox', checked: todo.done, onchange: () => send('/todo/api/' + todo.id, 'PATCH', { done: box.checked }) })
+    const title = document.createElement('span'); title.textContent = todo.title
+    const remove = Object.assign(document.createElement('button'), { textContent: 'x', onclick: () => send('/todo/api/' + todo.id, 'DELETE') })
+    item.append(box, title, remove)
+    return item
+  }))
+}
+</script>`

package/templates/todo/src/todo.ts

@@ -0,0 +1,96 @@
+/**
+ * The reference app of the ACRYL Framework: a todo list in one plugin. It needs `router` and `state`, keeps the list in a cell, serves
+ * JSON CRUD plus a page, and writes the list to a file so it survives a restart. Nothing else.
+ */
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+import type { Context } from '@deepseek-ai/cordis'
+import { HttpError } from './plugins/acryl-router/src/index.ts'
+import { loopbackOnly } from './plugins/acryl-router/src/middleware/index.ts'
+import { readJson, streamSSE, valid, validate, type StandardSchema } from './plugins/acryl-router/src/helpers/index.ts'
+import type {} from './plugins/acryl-state/src/index.ts'
+import { PAGE } from './page.ts'
+
+/** Stable Cordis plugin name, equal to the package name and the Loader row id. */
+export const name = 'acryl-todo'
+export const inject = ['router', 'state']
+
+export interface Todo { id: number, title: string, done: boolean }
+export interface Config { file?: string }
+
+/** Standard Schema for the body of a new todo, written by hand so the example has no schema library. */
+const NewTodo: StandardSchema<{ title: string }> = {
+  '~standard': {
+    validate: value => {
+      const title = (value as { title?: unknown } | null)?.title
+      return typeof title === 'string' && title.trim() !== '' && title.length <= 200
+        ? { value: { title: title.trim() } }
+        : { issues: [{ message: 'title must be 1 to 200 characters', path: ['title'] }] }
+    },
+  },
+}
+
+/** A missing file is a new list. Any other failure (unreadable, corrupt, half-written) refuses to start: starting empty would overwrite the user's real list on the first save. */
+function load(file: string | undefined): Todo[] {
+  if (file === undefined) return []
+  let text: string
+  try {
+    text = readFileSync(file, 'utf8')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return []
+    throw new Error(`acryl-todo: cannot read ${file}: ${(error as Error).message}`, { cause: error })
+  }
+  try {
+    const parsed: unknown = JSON.parse(text)
+    if (!Array.isArray(parsed)) throw new Error('not a list')
+    return parsed as Todo[]
+  } catch (error) {
+    throw new Error(`acryl-todo: ${file} is not a valid todo list (${(error as Error).message}); fix or remove it, it was left untouched`, { cause: error })
+  }
+}
+
+function save(file: string, todos: readonly Todo[]): void {
+  mkdirSync(dirname(file), { recursive: true })
+  const temporary = `${file}.tmp`
+  writeFileSync(temporary, JSON.stringify(todos))
+  renameSync(temporary, file)
+}
+
+export function apply(ctx: Context, config: Config = {}): void {
+  const todos = ctx.state.cell<readonly Todo[]>('todo.list', load(config.file))
+  if (config.file !== undefined) {
+    const file = config.file
+    ctx.effect(() => todos.subscribe(list => { save(file, list) }), 'acryl-todo: save to file')
+  }
+  const nextId = (): number => todos.get().reduce((max, todo) => Math.max(max, todo.id), 0) + 1
+
+  const api = ctx.router.group('/todo', loopbackOnly({ inProcess: 'allow' }))
+  api.get('/', c => c.html(PAGE))
+  api.get('/api', c => c.json(todos.get()))
+  api.post('/api', validate('json', NewTodo), c => {
+    const todo: Todo = { id: nextId(), title: valid<{ title: string }>(c, 'json').title, done: false }
+    todos.update(list => [...list, todo])
+    return c.json(todo, 201)
+  })
+  api.patch('/api/:id', async c => {
+    const id = Number(c.param('id'))
+    const change = await readJson(c) as { done?: unknown }
+    if (!todos.get().some(todo => todo.id === id)) throw new HttpError(404, { message: 'no such todo' })
+    if (typeof change.done !== 'boolean') throw new HttpError(400, { message: 'done must be true or false' })
+    todos.update(list => list.map(todo => todo.id === id ? { ...todo, done: change.done as boolean } : todo))
+    return c.json(todos.get().find(todo => todo.id === id))
+  })
+  api.delete('/api/:id', c => {
+    const id = Number(c.param('id'))
+    if (!todos.get().some(todo => todo.id === id)) throw new HttpError(404, { message: 'no such todo' })
+    todos.update(list => list.filter(todo => todo.id !== id))
+    return c.body(null, 204)
+  })
+  api.get('/events', c => streamSSE(c, stream => {
+    stream.send(todos.get())
+    return todos.subscribe(list => { stream.send(list) })
+  }))
+
+  ctx.inject(['routerHttp'], inner => { inner.routerHttp.mount('/todo') })
+}

package/templates/todo/template.json

@@ -0,0 +1 @@
+{ "plugins": ["instance", "acryl-router", "acryl-state", "acryl-node-server", "manifest", "save"] }

package/templates/todo/test/todo.test.ts

@@ -0,0 +1,145 @@
+import assert from 'node:assert/strict'
+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 { type App, createApp, readManifest } from '../src/app.ts'
+import { pinnedInstance, withPort } from '../src/plugins/instance/index.ts'
+
+const projectRoot = fileURLToPath(new URL('..', import.meta.url))
+
+/** Boot the app on any free port with its data in `home`, run the test, always stop it. */
+async function withApp(home: string, run: (app: App) => Promise<void>) {
+  const app = await createApp(withPort(pinnedInstance(home, { root: projectRoot }), 0))
+  try {
+    await run(app)
+  } finally {
+    await app.stop()
+  }
+}
+
+async function withHome(run: (home: string) => Promise<void>) {
+  const home = await mkdtemp(join(tmpdir(), 'todo-test-'))
+  try {
+    await run(home)
+  } finally {
+    await rm(home, { recursive: true, force: true })
+  }
+}
+
+const send = (app: App, method: string, path: string, body?: unknown) =>
+  fetch(`${app.url}${path}`, {
+    method,
+    headers: { 'content-type': 'application/json' },
+    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+  })
+
+test('creates, completes, lists and deletes', () =>
+  withHome((home) =>
+    withApp(home, async (app) => {
+      const created = await send(app, 'POST', '/todo/api', { title: ' buy milk ' })
+      assert.equal(created.status, 201)
+      assert.deepEqual(await created.json(), { id: 1, title: 'buy milk', done: false })
+
+      const done = await send(app, 'PATCH', '/todo/api/1', { done: true })
+      assert.deepEqual(await done.json(), { id: 1, title: 'buy milk', done: true })
+      assert.deepEqual(await (await send(app, 'GET', '/todo/api')).json(), [
+        { id: 1, title: 'buy milk', done: true },
+      ])
+
+      assert.equal((await send(app, 'DELETE', '/todo/api/1')).status, 204)
+      assert.deepEqual(await (await send(app, 'GET', '/todo/api')).json(), [])
+    }),
+  ))
+
+test('a change from a foreign origin is refused; a plain request from this machine works', () =>
+  withHome((home) =>
+    withApp(home, async (app) => {
+      const post = (headers: Record<string, string>) =>
+        fetch(`${app.url}/todo/api`, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json', ...headers },
+          body: JSON.stringify({ title: 'x' }),
+        })
+      assert.equal((await post({ origin: 'http://evil.example' })).status, 403)
+      assert.equal((await post({ origin: 'null' })).status, 403)
+      assert.equal((await post({})).status, 201)
+      assert.equal((await post({ origin: new URL(app.url).origin })).status, 201)
+    }),
+  ))
+
+test('rejects bad input and unknown ids', () =>
+  withHome((home) =>
+    withApp(home, async (app) => {
+      assert.equal((await send(app, 'POST', '/todo/api', { title: '' })).status, 400)
+      assert.equal((await send(app, 'POST', '/todo/api', { title: 42 })).status, 400)
+      assert.equal((await send(app, 'DELETE', '/todo/api/9')).status, 404)
+      assert.equal((await send(app, 'PATCH', '/todo/api/9', { done: true })).status, 404)
+      assert.equal((await send(app, 'GET', '/nope')).status, 404)
+    }),
+  ))
+
+test('the list survives a restart: a second app on the same home sees it', () =>
+  withHome(async (home) => {
+    await withApp(home, async (app) => {
+      await send(app, 'POST', '/todo/api', { title: 'first' })
+      await send(app, 'POST', '/todo/api', { title: 'second' })
+      await send(app, 'PATCH', '/todo/api/2', { done: true })
+    })
+    await withApp(home, async (app) => {
+      const list = (await (await send(app, 'GET', '/todo/api')).json()) as Array<{
+        id: number
+        done: boolean
+      }>
+      assert.deepEqual(
+        list.map((todo) => [todo.id, todo.done]),
+        [
+          [1, false],
+          [2, true],
+        ],
+      )
+      const created = (await (await send(app, 'POST', '/todo/api', { title: 'third' })).json()) as {
+        id: number
+      }
+      assert.equal(created.id, 3)
+    })
+  }))
+
+test('serves the page, and streams the list: now, and again on every change', () =>
+  withHome((home) =>
+    withApp(home, async (app) => {
+      const page = await send(app, 'GET', '/todo')
+      assert.equal(page.status, 200)
+      assert.match(await page.text(), /<title>Todo<\/title>/)
+
+      const controller = new AbortController()
+      const stream = await fetch(`${app.url}/todo/events`, { signal: controller.signal })
+      const reader = stream.body!.getReader()
+      const decoder = new TextDecoder()
+      let text = ''
+      const until = async (what: RegExp) => {
+        for (let waited = 0; !what.test(text) && waited < 3000; waited += 25) {
+          const next = await Promise.race([
+            reader.read(),
+            new Promise<{ done: true; value: undefined }>((done) =>
+              setTimeout(() => done({ done: true, value: undefined }), 25),
+            ),
+          ])
+          if (next.value) text += decoder.decode(next.value, { stream: true })
+        }
+        assert.match(text, what)
+      }
+      await until(/data: \[\]/)
+      await send(app, 'POST', '/todo/api', { title: 'streamed' })
+      await until(/"title":"streamed"/)
+      controller.abort()
+    }),
+  ))
+
+test('the manifest decides what is mounted', () => {
+  assert.deepEqual(
+    readManifest().plugins.map((row) => row.id),
+    ['router', 'state', 'todo', 'server'],
+  )
+})

package/templates/todo/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "verbatimModuleSyntax": true,
+    "erasableSyntaxOnly": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["src", "test"]
+}

package/templates/todo/upstream.json

@@ -0,0 +1,12 @@
+{
+  "source": {
+    "repo": "acryldev/acryl",
+    "files": {
+      "examples/acryl-todo/src/index.ts": "src/todo.ts",
+      "examples/acryl-todo/src/page.ts": "src/page.ts"
+    },
+    "commit": "11fed295161c0282d144b5ac62616988b58d8189"
+  },
+  "rewrittenSpecifiers": 4,
+  "digest": "sha256:5ca4e0883b7ff0fdec8cf18baac5271209ee27fcc8ce8decf298c9720256f92c"
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.