acrylblends 0.7.7 → 0.8.0

package/templates/nodejs/src/routes.ts

@@ -0,0 +1,40 @@
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import type { Context } from '@deepseek-ai/cordis'
+import { clientModules } from '../plugins/acryl-node-server/src/client-modules.ts'
+import { Acryl } from '../plugins/acryl-router/src/index.ts'
+import { aboutPage, counterPage } from './page.tsx'
+
+/** The browser builds of the DOM renderer and the typed client, shipped by the `acrylblends` package this app depends on. */
+const runtimeDir = join(
+  dirname(createRequire(import.meta.url).resolve('acrylblends/package.json')),
+  'lib',
+  'browser',
+)
+
+export const APP_NAME = '__APP_NAME__'
+
+/** The routes, in a file that does not import the Node adapter's server, so browser code can import the type: `import type { AppType } from '../routes.ts'`. */
+export const pages = new Acryl()
+  .get('/', (c) => c.json({ app: APP_NAME, ok: true }))
+  .get('/health', (c) => c.json({ ok: true }))
+  .get('/about', (c) => c.html(aboutPage()))
+  .get('/counter', (c) => c.html(counterPage()))
+
+export type AppType = typeof pages
+
+/**
+ * The app's own plugin: the routes above, and the client components without a bundler (`src/client` is compiled when the browser asks; `npm run build`
+ * compiles it once for production, and `NODE_ENV=production` then serves only `dist/client`). The mounts are removed when the plugin is disposed.
+ */
+export const routes = {
+  name: 'routes',
+  inject: ['router'],
+  apply(ctx: Context) {
+    ctx.router.route('/', pages)
+    ctx.router.route(
+      '/client',
+      clientModules({ root: 'src/client', compiled: 'dist/client', runtimeDir }),
+    )
+  },
+}

package/templates/nodejs/template.json

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

package/templates/nodejs/test/app.test.ts

@@ -0,0 +1,78 @@
+import assert from 'node:assert/strict'
+import { mkdirSync } from 'node:fs'
+import { mkdtemp, rm } from 'node:fs/promises'
+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 { APP_NAME } from '../src/routes.ts'
+
+/** Throwaway homes and databases live inside the project (`.acrylblends/` is ignored by git), because 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(scratch, 'app-test-'))
+  const app = await createApp(withPort(pinnedInstance(home, { root: projectRoot }), 0), {
+    listen: false,
+  })
+  try {
+    await run(app)
+  } finally {
+    await app.stop()
+    await rm(home, { recursive: true, force: true })
+  }
+}
+
+test('GET / answers with the app name', () =>
+  withApp(async (app) => {
+    const response = await app.root.router.request('/')
+    assert.equal(response.status, 200)
+    assert.deepEqual(await response.json(), { app: APP_NAME, ok: true })
+  }))
+
+test('GET /about renders the JSX page', () =>
+  withApp(async (app) => {
+    const response = await app.root.router.request('/about')
+    assert.equal(response.status, 200)
+    assert.match(response.headers.get('content-type') ?? '', /html/)
+    assert.match(
+      await response.text(),
+      /<main><h1>About<\/h1><p>Rendered on the server with the JSX runtime in plugins\/acryl-router\.<\/p><\/main>/,
+    )
+  }))
+
+test('an error thrown in a .tsx file names the .tsx line in its stack', async () => {
+  const { failingPage } = await import('../src/page.tsx')
+  let stack = ''
+  try {
+    failingPage()
+  } catch (error) {
+    stack = String((error as Error).stack)
+  }
+  assert.match(stack, /page\.tsx:\d+/)
+})
+
+test('answers health checks and 404 for unknown paths', () =>
+  withApp(async (app) => {
+    assert.equal((await app.root.router.request('/health')).status, 200)
+    assert.equal((await app.root.router.request('/nope')).status, 404)
+  }))
+
+test('GET /counter serves a page with a client component, and the component is compiled for the browser', () =>
+  withApp(async (app) => {
+    const page = await app.root.router.request('/counter')
+    assert.equal(page.status, 200)
+    assert.match(await page.text(), /<script type="module" src="\/client\/counter\.tsx">/)
+    const module = await app.root.router.request('/client/counter.tsx')
+    assert.equal(module.status, 200)
+    assert.match(module.headers.get('content-type') ?? '', /javascript/)
+    assert.doesNotMatch(await module.text(), /<Counter|<button/)
+    // The component's import of the DOM renderer is pointed at the browser build the acrylblends package ships.
+    const runtime = await app.root.router.request('/client/@acrylblends/jsx-dom.js')
+    assert.equal(runtime.status, 200)
+  }))

package/templates/nodejs/test/server.test.ts

@@ -0,0 +1,83 @@
+import assert from 'node:assert/strict'
+import { spawn } from 'node:child_process'
+import { once } from 'node:events'
+import { mkdirSync, mkdtempSync, rmSync } from 'node:fs'
+import { createServer } from 'node:net'
+import { join } from 'node:path'
+import { test } from 'node:test'
+import { fileURLToPath } from 'node:url'
+
+/** Throwaway homes and databases live inside the project (`.acrylblends/` is ignored by git), because 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 sandbox may forbid listening on a port (Codex's workspace-write does); the tests that start the real server are skipped there, and every other test runs in process. */
+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 tests that start the real server (${skip}); every other test ran in process`,
+  )
+
+/** Start `src/main.ts` the way `npm start` does, on a port the system chooses, and read the address it prints. */
+async function start(env: Record<string, string> = {}) {
+  const home = mkdtempSync(join(scratch, 'server-test-'))
+  const child = spawn(
+    process.execPath,
+    ['--import', './plugins/acryl-node-server/src/register.ts', 'src/main.ts'],
+    {
+      env: {
+        ...process.env,
+        ACRYLBLENDS_HOME: home,
+        ACRYLBLENDS_PORT: '0',
+        ACRYL_DOOR: 'off',
+        ...env,
+      },
+      stdio: ['ignore', 'pipe', 'inherit'],
+    },
+  )
+  let out = ''
+  const address = await new Promise<string>((resolve, reject) => {
+    child.once('exit', (code) =>
+      reject(new Error(`the server exited with ${code} before it listened`)),
+    )
+    child.stdout.on('data', (chunk) => {
+      out += chunk
+      const match = /listening on (http:\/\/\S+)/.exec(out)
+      if (match?.[1]) resolve(match[1])
+    })
+  })
+  return { child, address, home }
+}
+
+test('the server listens on 127.0.0.1 unless HOST says otherwise', { skip }, async () => {
+  const { child, address, home } = await start()
+  try {
+    assert.match(address, /^http:\/\/127\.0\.0\.1:\d+$/)
+  } finally {
+    child.kill('SIGTERM')
+    await once(child, 'exit')
+    rmSync(home, { recursive: true, force: true })
+  }
+})
+
+for (const signal of ['SIGTERM', 'SIGINT'] as const) {
+  test(`${signal} stops the server cleanly and frees the port`, { skip }, async () => {
+    const { child, address, home } = await start()
+    try {
+      assert.equal((await fetch(address)).status, 200)
+      const started = Date.now()
+      child.kill(signal)
+      const [code] = await once(child, 'exit')
+      assert.equal(code, 0)
+      assert.ok(Date.now() - started < 5000, 'the server took too long to stop')
+      await assert.rejects(fetch(address), 'the port should be free')
+    } finally {
+      rmSync(home, { recursive: true, force: true })
+    }
+  })
+}

package/templates/nodejs/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2024",
+    "lib": ["ES2024", "DOM", "DOM.Iterable"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noImplicitOverride": true,
+    "verbatimModuleSyntax": true,
+    "erasableSyntaxOnly": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["node"],
+    "jsx": "react-jsx",
+    "jsxImportSource": "#acryl-jsx"
+  },
+  "include": ["src", "test", "plugins"],
+  "exclude": ["src/client"]
+}

package/templates/notes/AGENTS.md

@@ -0,0 +1,26 @@
+
+## This app (notes): accounts, sessions, a database
+
+A Cordis app: `blend.yaml` lists the plugins that are mounted (`acryl-router`, `acryl-db-sqlite`, `routes`, `acryl-node-server`), `src/app.ts` is the one file that names the SQLite provider, and `src/routes.ts` is the app's own plugin: it builds the app on the `db` port and mounts it.
+
+- **The dependency rule:** only `src/app.ts` (the `opener` in `package.json`) imports the provider. Every other file takes a `Db` (`import type { Db } from '../plugins/acryl-db/src/index.ts'`) as an argument and never imports `node:sqlite`, `pg`, another driver or `acryl-db-sqlite`. `npm test` and `npm run check` run `acrylblends check-deps`, which names the file and line of a violation; do not move the `opener` entry to silence it.
+- `src/db.ts`: `notesStore(db)`, the queries for notes. Every `db` call returns a promise: `await` it. Use `?` bindings, never string-built SQL. The database is `data/notes.sqlite` (or the file `$NOTES_DB` names), opened by the `db` row with `migrations/` applied on start. See `docs/framework/guides/data.md`.
+- `migrations/`: the shape of the database, one numbered file per change (`001-notes.sql`). A file that has run is never edited; a change is the next file (`002-name.sql`).
+- `src/auth.ts`: scrypt password hashes (`node:crypto`) and the `sessions` table; the cookie `sid` holds a random token.
+- `src/schema.ts`: the rules for a note and for credentials. The HTML forms and the JSON API both use `checkNote`.
+- `src/views.tsx`: the pages, as JSX components rendered to strings, and the small script for the instant filter.
+- `src/client/`: client components, with their own `tsconfig.json` (browser types). `counter.tsx` is the live character counter. `clientModules` in `notes-app.ts` compiles them when the browser asks; `npm run build` compiles them once into `dist/client` for production. See `docs/framework/guides/client-modules.md`.
+- `src/notes-app.ts`: `createApp(db)` (pages and forms, csrf on) and `createApi(db)` (the JSON API under `/api/notes`, chained so `testClient` is typed).
+- `test/notes.test.ts`: a test for every route. It boots the whole app on a database file in a throwaway home (`createApp` of `src/app.ts` with `database`) and takes `app.root.db`. A form POST in a test needs `origin: 'http://localhost'` (csrf) and the `sid` cookie from sign up.
+- Forms answer an invalid input with status 400 and the same page with the messages; a successful POST redirects with 303.
+- To add a column or a table: write the next migration (`migrations/002-name.sql`), then change `notesStore`, `checkNote`, the form and the list in `views.tsx`, and the tests. Do not edit `001-notes.sql`.
+
+## Before you ship
+
+Read `docs/framework/getting-started/deploy.md`. In short:
+
+- Install with `npm ci --omit=dev`, run `npm run build` (it compiles `src/client` once; with `NODE_ENV=production` only `dist/client` is served), and start with `NODE_ENV=production npm start` (`typescript` stays a runtime dependency: it compiles the `.tsx` pages at start).
+- The app listens on `127.0.0.1`; set `HOST=0.0.0.0` only in a container. `PORT` chooses the port.
+- Put the SQLite file outside the code folder (`NOTES_DB=/var/lib/notes/notes.sqlite`) and back it up.
+- Behind an HTTPS reverse proxy set `TRUST_PROXY=1` and `PUBLIC_ORIGIN=https://your.site`, or the cookie is not `Secure` and csrf refuses form posts.
+- `npm test` includes a test that starts the server and stops it with SIGTERM; keep it passing if you change `src/main.ts`.

package/templates/notes/blend.yaml

@@ -0,0 +1,29 @@
+# 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
+    # The db port, on one SQLite file. The file and the migrations folder are set in src/app.ts (data/notes.sqlite, or the file the NOTES_DB environment variable names).
+    - id: db
+      name: acryl-db-sqlite
+    - id: routes
+      name: routes
+    - id: server
+      name: acryl-node-server
+      config:
+        hostname: "{{parameters.hostname}}"
+    # The door: an agent working in this folder looks at the page and acts on it through .acryl/bin/acryl. Development only: src/app.ts leaves it out when NODE_ENV=production.
+    - id: acryl-door
+      name: acryl-door

package/templates/notes/gitignore

@@ -0,0 +1,6 @@
+node_modules/
+.acrylblends/
+.acryl/
+data/
+*.sqlite
+*.sqlite-*

package/templates/notes/migrations/001-notes.sql

@@ -0,0 +1,18 @@
+CREATE TABLE users (
+  id INTEGER PRIMARY KEY,
+  email TEXT NOT NULL UNIQUE,
+  password_hash TEXT NOT NULL
+);
+
+CREATE TABLE sessions (
+  token TEXT PRIMARY KEY,
+  user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE
+);
+
+CREATE TABLE notes (
+  id INTEGER PRIMARY KEY,
+  user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  title TEXT NOT NULL,
+  body TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);

package/templates/notes/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "__APP_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "imports": {
+    "#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 ./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": "acrylblends check-deps && node --import ./plugins/acryl-node-server/src/register.ts --test \"test/**/*.test.{ts,tsx}\"",
+    "check": "tsc --noEmit && tsc --noEmit -p src/client && acrylblends check-deps",
+    "build": "acrylblends build-client",
+    "lock": "node plugins/manifest/lock.ts",
+    "save": "node plugins/save/cli.ts",
+    "upgrade": "node plugins/manifest/upgrade-cli.ts"
+  },
+  "dependencies": {
+    "acrylblends": "__ACRYLBLENDS_RANGE__",
+    "typescript": "6.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0"
+  },
+  "acryl": {
+    "opener": "src/app.ts"
+  }
+}

package/templates/notes/src/app.ts

@@ -0,0 +1,106 @@
+import { isAbsolute, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { Context, type Fiber } from '@deepseek-ai/cordis'
+import * as db from '../plugins/acryl-db-sqlite/src/index.ts'
+import * as door from '../plugins/acryl-door/src/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'
+import { doorEnabled } from './door.ts'
+import { routes } from './routes.ts'
+
+/** The plugins this app's code provides. `blend.yaml` chooses, orders and configures them. */
+export const registry = {
+  'acryl-router': router,
+  'acryl-db-sqlite': db,
+  'acryl-node-server': nodeServer,
+  'acryl-door': door,
+  routes,
+}
+
+const projectRoot = fileURLToPath(new URL('..', import.meta.url))
+
+/** The manifest next to this app's source. */
+export const MANIFEST = join(projectRoot, 'blend.yaml')
+
+/** The manifest, resolved. `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(projectRoot, 'blueprints')),
+    ...(values ? { values } : {}),
+  })
+}
+
+/** The manifest without some rows: without its server (and so its door) the app is reached in process, through `root.router.request`; the door is also left out in production. */
+function without<M extends { plugins: readonly { use: string }[] }>(
+  manifest: M,
+  ...uses: string[]
+): M {
+  return {
+    ...manifest,
+    plugins: manifest.plugins.map((row) =>
+      uses.includes(row.use) ? { ...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>
+}
+
+export interface AppOptions {
+  readonly values?: Readonly<Record<string, ParameterValue>>
+  /** The SQLite file, relative to the app folder; an absolute path is used as it is (tests give a file in a throwaway home). Default: `data/notes.sqlite`. */
+  readonly database?: string
+  /** 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. */
+  readonly listen?: boolean
+}
+
+/**
+ * The app: `instance` first (where it lives, chosen at run time), then the manifest's rows in order. The `db` row opens the database and applies
+ * `migrations/`; the one place that names the SQLite provider is this file (`acrylblends check-deps`), so a different provider is a change here.
+ */
+export async function createApp(chosen: AppInstance, options: AppOptions = {}): Promise<App> {
+  const manifest = readManifest(options.values)
+  const listen = options.listen
+  const file = options.database ?? 'data/notes.sqlite'
+  const root = new Context()
+  const first = root.plugin(instance, chosen)
+  await first.await()
+  const fibers: Fiber[] = [
+    first,
+    ...(await compose(
+      root,
+      listen === false
+        ? without(manifest, 'acryl-node-server', 'acryl-door')
+        : doorEnabled()
+          ? manifest
+          : without(manifest, 'acryl-door'),
+      registry,
+      {
+        db: {
+          path: isAbsolute(file) ? file : resolve(projectRoot, file),
+          migrations: join(projectRoot, 'migrations'),
+        },
+        server: { port: chosen.port.start, scan: chosen.port.scan ? 20 : 0 },
+      },
+    )),
+  ]
+  return {
+    root,
+    url: listen === false ? '' : root.nodeServer.url,
+    async stop() {
+      for (const fiber of [...fibers].reverse()) await fiber.dispose()
+    },
+  }
+}

package/templates/notes/src/auth.ts

@@ -0,0 +1,57 @@
+import { randomBytes, scrypt, timingSafeEqual } from 'node:crypto'
+import { promisify } from 'node:util'
+import type { Db } from '../plugins/acryl-db/src/index.ts'
+
+const scryptAsync = promisify(scrypt) as (
+  password: string,
+  salt: Buffer,
+  length: number,
+) => Promise<Buffer>
+
+export async function hashPassword(password: string): Promise<string> {
+  const salt = randomBytes(16)
+  const key = await scryptAsync(password, salt, 64)
+  return `${salt.toString('hex')}:${key.toString('hex')}`
+}
+
+export async function verifyPassword(password: string, stored: string): Promise<boolean> {
+  const [salt, key] = stored.split(':')
+  if (!salt || !key) return false
+  const expected = Buffer.from(key, 'hex')
+  const actual = await scryptAsync(password, Buffer.from(salt, 'hex'), expected.length)
+  return timingSafeEqual(actual, expected)
+}
+
+export function authStore(db: Db) {
+  return {
+    findUser(email: string) {
+      return db.get<{ id: number; email: string; password_hash: string }>(
+        'SELECT id, email, password_hash FROM users WHERE email = ?',
+        email,
+      )
+    },
+    async createUser(email: string, password: string): Promise<number> {
+      const user = await db.get<{ id: number }>(
+        'INSERT INTO users (email, password_hash) VALUES (?, ?) RETURNING id',
+        email,
+        await hashPassword(password),
+      )
+      return user!.id
+    },
+    async startSession(userId: number): Promise<string> {
+      const token = randomBytes(32).toString('hex')
+      await db.run('INSERT INTO sessions (token, user_id) VALUES (?, ?)', token, userId)
+      return token
+    },
+    async userFor(token: string | undefined) {
+      if (!token) return undefined
+      return db.get<{ id: number; email: string }>(
+        'SELECT users.id AS id, users.email AS email FROM sessions JOIN users ON users.id = sessions.user_id WHERE token = ?',
+        token,
+      )
+    },
+    async endSession(token: string): Promise<void> {
+      await db.run('DELETE FROM sessions WHERE token = ?', token)
+    },
+  }
+}

package/templates/notes/src/client/counter.tsx

@@ -0,0 +1,21 @@
+import { render, useEffect, useState } from 'acrylblends/jsx/dom'
+
+/** The live character counter of the note form: a client component drawn next to the textarea, compiled on request by clientModules (see src/notes-app.ts). */
+const Count = ({ area }: { area: HTMLTextAreaElement }) => {
+  const [length, setLength] = useState(area.value.length)
+  useEffect(() => {
+    const update = () => setLength(area.value.length)
+    area.addEventListener('input', update)
+    return () => area.removeEventListener('input', update)
+  }, [])
+  return (
+    <>
+      {length} / {area.maxLength}
+    </>
+  )
+}
+
+const area = document.getElementById('body')
+const out = document.querySelector('[data-island="counter"]')
+if (area instanceof HTMLTextAreaElement && out instanceof HTMLElement)
+  render(<Count area={area} />, out)

package/templates/notes/src/client/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "target": "ES2024",
+    "lib": ["ES2024", "DOM", "DOM.Iterable"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "jsx": "react-jsx",
+    "jsxImportSource": "acrylblends/jsx/dom",
+    "types": [],
+    "paths": {
+      "acrylblends/jsx/dom": ["../../plugins/acryl-router/src/browser/jsx-dom.ts"],
+      "acrylblends/jsx/dom/jsx-runtime": [
+        "../../plugins/acryl-router/src/core/jsx/dom/jsx-runtime.ts"
+      ],
+      "acrylblends/jsx/dom/jsx-dev-runtime": [
+        "../../plugins/acryl-router/src/core/jsx/dom/jsx-dev-runtime.ts"
+      ],
+      "acrylblends/jsx/dom/client": ["../../plugins/acryl-router/src/browser/jsx-dom.ts"],
+      "acrylblends/client": ["../../plugins/acryl-router/src/browser/client.ts"]
+    }
+  },
+  "include": ["**/*.ts", "**/*.tsx"]
+}

package/templates/notes/src/db.ts

@@ -0,0 +1,50 @@
+import type { Db } from '../plugins/acryl-db/src/index.ts'
+
+export interface Note {
+  id: number
+  user_id: number
+  title: string
+  body: string
+  updated_at: string
+}
+
+export function notesStore(db: Db) {
+  return {
+    list(userId: number, q = ''): Promise<Note[]> {
+      const like = `%${q.replace(/[\\%_]/g, (m) => `\\${m}`)}%`
+      return db.all<Note>(
+        `SELECT * FROM notes WHERE user_id = ? AND (title LIKE ? ESCAPE '\\' OR body LIKE ? ESCAPE '\\') ORDER BY updated_at DESC, id DESC`,
+        userId,
+        like,
+        like,
+      )
+    },
+    get(userId: number, id: number): Promise<Note | undefined> {
+      return db.get<Note>('SELECT * FROM notes WHERE id = ? AND user_id = ?', id, userId)
+    },
+    async create(userId: number, title: string, body: string): Promise<Note> {
+      const note = await db.get<Note>(
+        'INSERT INTO notes (user_id, title, body, updated_at) VALUES (?, ?, ?, ?) RETURNING *',
+        userId,
+        title,
+        body,
+        new Date().toISOString(),
+      )
+      return note!
+    },
+    update(userId: number, id: number, title: string, body: string): Promise<Note | undefined> {
+      return db.get<Note>(
+        'UPDATE notes SET title = ?, body = ?, updated_at = ? WHERE id = ? AND user_id = ? RETURNING *',
+        title,
+        body,
+        new Date().toISOString(),
+        id,
+        userId,
+      )
+    },
+    async remove(userId: number, id: number): Promise<boolean> {
+      const { changes } = await db.run('DELETE FROM notes WHERE id = ? AND user_id = ?', id, userId)
+      return changes > 0
+    },
+  }
+}

package/templates/notes/src/door.ts

@@ -0,0 +1,7 @@
+/**
+ * The door (`plugins/acryl-door`) lets an agent working in this folder look at the running page and act on it, through `.acryl/bin/acryl`. It is on in development
+ * and off in production (`NODE_ENV=production`) and when `ACRYL_DOOR=off`: `src/app.ts` leaves its row out then, and the pages leave its script tag out. One process
+ * at a time serves a folder's door, so the tests that start the real server set `ACRYL_DOOR=off` and a second `npm start` beside a running one does not fail on it.
+ */
+export const doorEnabled = (): boolean =>
+  process.env.NODE_ENV !== 'production' && process.env.ACRYL_DOOR !== 'off'

package/templates/notes/src/main.ts

@@ -0,0 +1,28 @@
+import { fileURLToPath } from 'node:url'
+import { selectInstance } from '../plugins/instance/index.ts'
+import { createApp } from './app.ts'
+
+// The composition root: the one place that reads the environment and chooses where the app lives.
+const chosen = selectInstance({
+  projectRoot: fileURLToPath(new URL('..', import.meta.url)),
+  // PORT and HOST are the names hosting platforms set; ACRYLBLENDS_PORT and ACRYLBLENDS_HOST win when both are given.
+  env: {
+    ...(process.env.PORT ? { ACRYLBLENDS_PORT: process.env.PORT } : {}),
+    ...(process.env.HOST ? { ACRYLBLENDS_HOST: process.env.HOST } : {}),
+    ...process.env,
+  },
+})
+const app = await createApp(chosen, {
+  ...(process.env.NOTES_DB ? { database: process.env.NOTES_DB } : {}),
+})
+console.log(`listening on ${app.url} (data in ${chosen.home})`)
+
+// Stop taking requests, let the ones in flight finish, then close the database (the db plugin does, when it is disposed) and exit.
+const stop = async () => {
+  const timer = setTimeout(() => process.exit(1), 10_000)
+  timer.unref()
+  await app.stop()
+  process.exit(0)
+}
+process.once('SIGINT', stop)
+process.once('SIGTERM', stop)