acrylblends 1.0.1 → 1.0.3

package/docs/framework/workshop/facilitator.md

@@ -0,0 +1,107 @@
+# Facilitator notes: the 90-minute ACRYL Blends workshop
+
+Read the attendee handout first (`docs/framework/workshop/README.md`); this page is the room around it: what to put on each machine, what actually breaks, and
+where to cut when the clock runs. Every timing and every failure below was measured on the published `acrylblends` 1.0.0 during the readiness walk
+(`docs/plans/workshop-readiness.md`).
+
+## Before the room: put this on every machine
+
+| What | Why | How |
+| --- | --- | --- |
+| Node.js 22.19 or newer (24 LTS or 26 tested), npm 11 | the app runs TypeScript directly, no build step | `node -v`; if missing, the LTS from nodejs.org or `brew install node` (Node 26 today, which is tested) |
+| git | the registry block clones the registry | `git --version` |
+| A warm npm cache | the first `npm create` downloads the initializer, `npm install` downloads Electron | create one app and add the desktop shell once per machine (below) |
+| A coding agent, logged in | step 7 drives Codex or Claude Code through the panel | `codex login status` or run `claude` once |
+| `~/acryl-workshop/prepared/` | the no-network fallback and the reset | copy the two prepared apps (below) |
+| A GitHub account with `gh auth login` | step 10 forks the workshop registry and opens a pull request | `gh auth status` |
+| A device with `git` and a text editor | the edits in steps 2, 4 and 8 are small but real | `git --version` |
+
+Warm-up, once per machine (this is also the exact smoke test that the room works):
+
+```sh
+mkdir -p ~/acryl-workshop && cd ~/acryl-workshop
+npm create acrylblends@latest warmup notes
+cd warmup && npm install && npm test
+npx acrylblends add desktop && npm install
+cd ~/acryl-workshop && cp -R warmup prepared-notes && rm -rf warmup
+```
+
+That leaves `prepared-notes` with everything installed, including Electron.
+
+## Timings, checkpoints, and what to make optional
+
+The handout's own timings, as measured on the published 1.0.2 (macOS, cold npm cache in a throwaway home):
+
+| Minutes | Step | Measured | If late |
+| --- | --- | --- | --- |
+| 0-10 | installs and checks | seconds each | never cut |
+| 10-15 | create and run the blank app | create 9 s cold (2 s warm), install 2 s, boot 2 s | never cut |
+| 15-22 | change one route | reload is instant | never cut |
+| 22-30 | tests and the typecheck | test 0.5-2 s, check 2.5-4 s | keep; cut the "write a test" exercise |
+| 30-38 | data: JSON then SQLite (**optional**) | two adds plus edits, ~8 min | **cut first** |
+| 38-45 | the desktop window | add 2 s, install 3 s, first Electron boot ~20 s | pre-warm Electron on every machine or demo it |
+| 45-53 | pull a starter | create 4 s, install 3 s, runs at once | keep; it is the fastest win in the room |
+| 53-60 | create from a template | create + install + add desktop 4 s | drop the second app |
+| 60-75 | the agent builds a feature | set-up 4 s; codex wrote a page and tests in about 7 minutes | never cut; demo it if the room is behind |
+| 75-82 | upgrade | seconds: a fresh app answers "everything is up to date" | keep; it is a 2-minute talk |
+| 82-90 | publish and the hero moment | the registry steps are seconds; the PR is talk | always keep at least the hero talk |
+
+Checkpoints in the handout, and what to look for as you walk the room: **15 minutes** every screen shows `{"app":"my-hero","ok":true}`; **45 minutes**
+every screen has the app in a desktop window; **75 minutes** every screen has `/board` open with the agent's page. A machine behind at a checkpoint is
+what the optional column is for, and the handout names the same choices so nobody has to guess.
+
+## What breaks in the room, and what to say
+
+These are the defects found by the walk. They are known; say so rather than letting people think they broke something.
+
+- **The data step is the slow one.** Wiring `kv` then `db` by hand is about ten minutes of edits for a newcomer (two rows, two registry lines, two
+  type imports, the migrations folder). It is the block the handout names optional, and the one to help with first.
+- **A relative migrations path in `blend.yaml` fails.** `migrations: migrations` in the row stops the app with "this app has no file base URL to
+  resolve it from". The folder is named in `src/app.ts`'s compose options instead; the handout teaches that form and the stuck line names the error.
+- **`pi` shows up only when the app can see its login.** 1.0.2 offers pi as a chat driver when `DEEPSEEK_API_KEY` is exported or `~/.pi/agent/auth.json`
+  holds a deepseek entry, read from the HOME the app runs in. On a normal attendee machine it is there; in a run with a moved HOME it is not (and pi
+  would fail on its first message anyway). `pty:pi` needs only the program.
+- **The agent run takes minutes, not seconds.** Codex wrote the page and its tests in about seven; tell the room to start it and keep talking.
+- **Publishing.** The workshop registry is `github.com/acryldev/workshop-2026-11-20`, public and open. Attendees fork it, run
+  `node scripts/make-entry.mjs ../agent-app <login>.agent-app --description "..."`, push and open a pull request; a check merges it, usually well under
+  two minutes, and a refusal comes as a comment. Taking an app down is a pull request that removes its folder. Pulling is
+  `--from <id> --registry github:acryldev/workshop-2026-11-20` (rehearsed on 1.0.2: create 12 s, install 3 s, runs at once).
+- **Browser-only attendees (TODO(M9)).** The handout's hosted-workspace stub is empty until M9 is live; until then a browser-only attendee can follow
+  along but not create an app.
+- **node-pty's install script (C5).** `npm install` warns that npm 11 blocked `node-pty`'s script. The terminal drivers still list; the workshop does
+  not open one.
+
+## The no-network fallback
+
+If the venue has no reliable network:
+
+1. Every machine gets `prepared-notes` and a prepared agent app from the sheet above, so steps 1-6 skip creation and installs.
+2. Step 8 uses the cloned registry and the installed `blends-core`; no network needed.
+3. Step 7 needs the agent's own model, so it cannot run offline. Demo it from your machine on a tethered connection, or record it (a 4-minute
+   screen recording of the codex run is enough).
+4. Keep one machine on a phone hotspot for `npm create` failures.
+
+## Demo script for the agent block (5 minutes, if you demo instead of hands-on)
+
+1. On the prepared agent app: `npm run dev`, open the page, click the panel button.
+2. Ask: "Add a route GET /agent-built to src/routes.ts that returns {\"built\": true}, then run the tests and tell me what happened."
+3. Narrate while it runs: the agent reads `AGENTS.md`, reads `docs/framework`, edits `src/routes.ts`, runs the tests; the terminal prints
+   `Change detected … Restarting`; reload `/agent-built` and show `{"built":true}`.
+4. Point at the panel's stop button and the audit line the panel writes under `.acrylblends/audit/`.
+
+## Resetting between sessions
+
+Everything a person makes lives inside their app folder and `~/acryl-workshop`. To reset a machine:
+
+```sh
+rm -rf ~/acryl-workshop/[a-z]*-app ~/acryl-workshop/registry
+cp -R ~/acryl-workshop/prepared/* ~/acryl-workshop/    # if you keep a prepared/ folder
+```
+
+Nothing is installed globally except the agent and Bun; neither needs cleaning between sessions.
+
+## What is still open
+
+- Starter pull (B1), the panel's rows (C1) and the upgrade command in the docs (B2) are with the framework team; when they land, the handout's
+  TODO lines become normal steps and this page's "what breaks" list shrinks.
+- The Windows and Linux runs of the attendee handout are being replayed separately; add what differs to the handout's OS column rather than here.

package/lib/cordis/db-sqlite.js

@@ -15,6 +15,10 @@ import z from "@deepseek-ai/schemastery";
 */
 /** Stable Cordis plugin name, equal to the package name and the Loader row id. */
 const name = "acryl-db-sqlite";
+/** The project folder of an acrylblends app (`appInstance.root`), when the instance has one: where a relative path in a row's config is read from, since such an app has no Loader base URL. */
+function appRoot(value) {
+	return typeof value === "object" && value !== null && "root" in value && typeof value.root === "string" ? value.root : void 0;
+}
 function isAppHome(value) {
 	return typeof value === "object" && value !== null && "home" in value && typeof value.home === "string";
 }
@@ -26,12 +30,16 @@ const Config = z.object({
 });
 /** The file name used in the app home when `path` is not configured. */
 const DEFAULT_FILE = "data.sqlite";
-/** A configured path as a file path: absolute as given, relative to the Loader's base URL (the app) otherwise. */
+/** A configured path as a file path: absolute as given, relative to the Loader's base URL (the app) otherwise, or to the app's project folder (`appInstance.root`) where there is no base URL. */
 function resolveFromApp(ctx, path, option) {
 	if (path.startsWith("file:")) return fileURLToPath(path);
 	if (isAbsolute(path)) return path;
 	const base = ctx.baseUrl;
-	if (base === void 0 || !base.startsWith("file:")) throw new Error(`acryl-db-sqlite: ${option} ${JSON.stringify(path)} is relative, but this app has no file base URL to resolve it from; give an absolute path`);
+	if (base === void 0 || !base.startsWith("file:")) {
+		const root = appRoot(ctx.get("appInstance"));
+		if (root !== void 0) return resolve(root, path);
+		throw new Error(`acryl-db-sqlite: ${option} ${JSON.stringify(path)} is relative, but this app has no file base URL to resolve it from; give an absolute path`);
+	}
 	return resolve(base.endsWith("/") ? fileURLToPath(base) : dirname(fileURLToPath(base)), path);
 }
 async function apply(ctx, rawConfig = {}) {

package/lib/cordis/kv-json.js

@@ -19,12 +19,20 @@ function isAppHome(value) {
 const Config = z.object({ path: z.string().description("The JSON file, absolute or relative to the app. Defaults to kv.json in the ACRYL app home; required where there is none.") });
 /** The file name used in the app home when `path` is not configured. */
 const DEFAULT_FILE = "kv.json";
-/** A configured path as a file path: absolute as given, relative to the Loader's base URL (the app) otherwise. */
+/** The project folder of an acrylblends app (`appInstance.root`), when the instance has one: where a relative path in a row's config is read from, since such an app has no Loader base URL. */
+function appRoot(value) {
+	return typeof value === "object" && value !== null && "root" in value && typeof value.root === "string" ? value.root : void 0;
+}
+/** A configured path as a file path: absolute as given, relative to the Loader's base URL (the app) otherwise, or to the app's project folder (`appInstance.root`) where there is no base URL. */
 function resolveFromApp(ctx, path) {
 	if (path.startsWith("file:")) return fileURLToPath(path);
 	if (isAbsolute(path)) return path;
 	const base = ctx.baseUrl;
-	if (base === void 0 || !base.startsWith("file:")) throw new Error(`acryl-kv-json: path ${JSON.stringify(path)} is relative, but this app has no file base URL to resolve it from; give an absolute path`);
+	if (base === void 0 || !base.startsWith("file:")) {
+		const root = appRoot(ctx.get("appInstance"));
+		if (root !== void 0) return resolve(root, path);
+		throw new Error(`acryl-kv-json: path ${JSON.stringify(path)} is relative, but this app has no file base URL to resolve it from; give an absolute path`);
+	}
 	return resolve(base.endsWith("/") ? fileURLToPath(base) : dirname(fileURLToPath(base)), path);
 }
 async function apply(ctx, rawConfig = {}) {

package/lib/cordis/node-server.js

@@ -1,4 +1,4 @@
-import { c as Request, i as createAdaptorServer, l as RequestError, n as UpgradeEmitter, r as UpgradeHub, t as testWebSocket } from "../test-websocket-ZXHNHQSU.js";
+import { c as Request, i as createAdaptorServer, l as RequestError, n as UpgradeEmitter, r as UpgradeHub, t as testWebSocket } from "../test-websocket-D8WWqE5G.js";
 import { t as serveStatic } from "../serve-static-3uo_9rjF.js";
 import { Service } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";

package/lib/cordis/router-http.js

@@ -1,4 +1,4 @@
-import { n as UpgradeEmitter, r as UpgradeHub } from "../test-websocket-ZXHNHQSU.js";
+import { n as UpgradeEmitter, r as UpgradeHub } from "../test-websocket-D8WWqE5G.js";
 import "./node-server.js";
 import { Readable } from "node:stream";
 import { Service } from "@deepseek-ai/cordis";

package/lib/node-server.js

@@ -1,4 +1,4 @@
-import { a as serve, i as createAdaptorServer, l as RequestError, n as UpgradeEmitter, o as upgradeWebSocket, r as UpgradeHub, s as getRequestListener, t as testWebSocket } from "./test-websocket-ZXHNHQSU.js";
+import { a as serve, i as createAdaptorServer, l as RequestError, n as UpgradeEmitter, o as upgradeWebSocket, r as UpgradeHub, s as getRequestListener, t as testWebSocket } from "./test-websocket-D8WWqE5G.js";
 import { t as serveStatic } from "./serve-static-3uo_9rjF.js";
 import { getConnInfo } from "./node-server/conninfo.js";
 import { n as clientModules, t as buildClientModules } from "./client-modules-CLvWOjbd.js";

package/lib/{test-websocket-ZXHNHQSU.js → test-websocket-D8WWqE5G.js}

@@ -226,8 +226,7 @@ const readBodyBufferedBeforeDisconnect = (incoming, chunks) => {
 	else if (incomingWithRecovery[bodyBufferedLengthBeforeDisconnectKey] !== void 0 && incoming.readableLength !== incomingWithRecovery[bodyBufferedLengthBeforeDisconnectKey]) result = newBodyUnusableError();
 	else {
 		const bodyChunks = chunks ?? [];
-		const chunk = incoming.read();
-		if (chunk !== null) bodyChunks.push(toBufferChunk(chunk, incoming.readableEncoding));
+		for (let chunk = incoming.read(); chunk !== null; chunk = incoming.read()) bodyChunks.push(toBufferChunk(chunk, incoming.readableEncoding));
 		const buffer = bodyChunks.length === 1 ? bodyChunks[0] : Buffer.concat(bodyChunks);
 		result = buffer;
 		const contentLength = incoming.headers["content-length"];

package/package.json

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

package/plugins/acryl-db-sqlite/plugin.json

@@ -8,7 +8,7 @@
     "@deepseek-ai/cordis": "4.0.4",
     "@deepseek-ai/schemastery": "3.18.4"
   },
-  "mount": "mount it after instance: root.plugin(dbSqlite, { migrations: 'migrations' }) with the migrations/ folder (001-name.sql, ...) next to src/; then a plugin that declares inject: ['db'] calls await ctx.db.all('SELECT ...', value)",
+  "mount": "mount it after instance, either as a row in blend.yaml (`- id: db` / `name: acryl-db-sqlite` / `config: { migrations: migrations }`, registered in src/app.ts as 'acryl-db-sqlite') or as root.plugin(dbSqlite, { migrations: 'migrations' }); a relative path is read from the app's folder, and the migrations/ folder (001-name.sql, ...) sits next to src/. Then a plugin that declares inject: ['db'] calls await ctx.db.all('SELECT ...', value)",
   "omit": ["**/*.test.*", "**/*.spec.*", "**/*.case.ts"],
   "imports": {
     "#acryl-db-sqlite": "acryl-db-sqlite/src/index.ts"

package/plugins/acryl-db-sqlite/src/index.ts

@@ -30,6 +30,11 @@ interface AppHome {
   readonly home: string
 }
 
+/** The project folder of an acrylblends app (`appInstance.root`), when the instance has one: where a relative path in a row's config is read from, since such an app has no Loader base URL. */
+function appRoot(value: unknown): string | undefined {
+  return typeof value === 'object' && value !== null && 'root' in value && typeof value.root === 'string' ? value.root : undefined
+}
+
 function isAppHome(value: unknown): value is AppHome {
   return typeof value === 'object' && value !== null && 'home' in value && typeof value.home === 'string'
 }
@@ -51,12 +56,14 @@ export const Config: z<Config> = z.object({
 /** The file name used in the app home when `path` is not configured. */
 export const DEFAULT_FILE = 'data.sqlite'
 
-/** A configured path as a file path: absolute as given, relative to the Loader's base URL (the app) otherwise. */
+/** A configured path as a file path: absolute as given, relative to the Loader's base URL (the app) otherwise, or to the app's project folder (`appInstance.root`) where there is no base URL. */
 function resolveFromApp(ctx: Context, path: string, option: string): string {
   if (path.startsWith('file:')) return fileURLToPath(path)
   if (isAbsolute(path)) return path
   const base = ctx.baseUrl
   if (base === undefined || !base.startsWith('file:')) {
+    const root = appRoot(ctx.get('appInstance'))
+    if (root !== undefined) return resolve(root, path)
     throw new Error(`acryl-db-sqlite: ${option} ${JSON.stringify(path)} is relative, but this app has no file base URL to resolve it from; give an absolute path`)
   }
   const appDir = base.endsWith('/') ? fileURLToPath(base) : dirname(fileURLToPath(base))

package/plugins/acryl-kv-json/plugin.json

@@ -8,7 +8,7 @@
     "@deepseek-ai/cordis": "4.0.4",
     "@deepseek-ai/schemastery": "3.18.4"
   },
-  "mount": "mount it after instance: root.plugin(kvJson, {}) (the file is kv.json in the app home, or set path); then a plugin that declares inject: ['kv'] calls await ctx.kv.set('theme', 'dark') and ctx.kv.update('visits', (n) => (n ?? 0) + 1)",
+  "mount": "mount it after instance, as a row in blend.yaml (`- id: kv` / `name: acryl-kv-json`, registered in src/app.ts as 'acryl-kv-json') or as root.plugin(kvJson, {}) (the file is kv.json in the app home, or set path; a relative path is read from the app's folder); then a plugin that declares inject: ['kv'] calls await ctx.kv.set('theme', 'dark') and ctx.kv.update('visits', (n) => (n ?? 0) + 1)",
   "omit": ["**/*.test.*", "**/*.spec.*", "**/*.case.ts"],
   "imports": {
     "#acryl-kv-json": "acryl-kv-json/src/index.ts"

package/plugins/acryl-kv-json/src/index.ts

@@ -41,12 +41,19 @@ export const Config: z<Config> = z.object({
 /** The file name used in the app home when `path` is not configured. */
 export const DEFAULT_FILE = 'kv.json'
 
-/** A configured path as a file path: absolute as given, relative to the Loader's base URL (the app) otherwise. */
+/** The project folder of an acrylblends app (`appInstance.root`), when the instance has one: where a relative path in a row's config is read from, since such an app has no Loader base URL. */
+function appRoot(value: unknown): string | undefined {
+  return typeof value === 'object' && value !== null && 'root' in value && typeof value.root === 'string' ? value.root : undefined
+}
+
+/** A configured path as a file path: absolute as given, relative to the Loader's base URL (the app) otherwise, or to the app's project folder (`appInstance.root`) where there is no base URL. */
 function resolveFromApp(ctx: Context, path: string): string {
   if (path.startsWith('file:')) return fileURLToPath(path)
   if (isAbsolute(path)) return path
   const base = ctx.baseUrl
   if (base === undefined || !base.startsWith('file:')) {
+    const root = appRoot(ctx.get('appInstance'))
+    if (root !== undefined) return resolve(root, path)
     throw new Error(`acryl-kv-json: path ${JSON.stringify(path)} is relative, but this app has no file base URL to resolve it from; give an absolute path`)
   }
   const appDir = base.endsWith('/') ? fileURLToPath(base) : dirname(fileURLToPath(base))

package/plugins/acryl-node-server/src/adapter/request.ts

@@ -135,8 +135,9 @@ const readBodyBufferedBeforeDisconnect = (
     result = newBodyUnusableError()
   } else {
     const bodyChunks = chunks ?? []
-    const chunk = incoming.read() as Buffer | string | null
-    if (chunk !== null) {
+    // Drain what is still buffered. On a destroyed stream one read() returns all of it on some Node versions and only the first chunk on others (Node 26), so read until
+    // the stream says there is no more: that is what Readable#read() promises, and it needs nothing of Node's internals.
+    for (let chunk = incoming.read() as Buffer | string | null; chunk !== null; chunk = incoming.read()) {
       bodyChunks.push(toBufferChunk(chunk, incoming.readableEncoding))
     }
     const buffer = bodyChunks.length === 1 ? bodyChunks[0] : Buffer.concat(bodyChunks)

package/plugins/agent-panel/headless.ts

@@ -1,5 +1,8 @@
 /** The panel's own drivers, all `chat`: the app's agent, and the coding agents (`claude`, `codex`, `pi`) started headless in the app folder. */
 import { spawn, spawnSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
 import type { Context } from '@deepseek-ai/cordis'
 import type { ChatDriver, ChatEvent } from './drivers.ts'
 
@@ -62,11 +65,30 @@ export function onPath(program: string): boolean {
   return found.status === 0
 }
 
-/** The headless programs this machine can offer: installed (pi also needs its key in the environment). */
+/** Whether pi can reach DeepSeek: the key in the environment, or the one pi stored for itself when its owner logged in (`~/.pi/agent/auth.json`, a `deepseek` entry). */
+export function piHasDeepseekKey(
+  env: NodeJS.ProcessEnv = process.env,
+  home: string = homedir(),
+): boolean {
+  if (env.DEEPSEEK_API_KEY) return true
+  try {
+    const stored = JSON.parse(
+      readFileSync(
+        join(env.PI_CODING_AGENT_DIR ?? join(home, '.pi', 'agent'), 'auth.json'),
+        'utf8',
+      ),
+    ) as Record<string, { key?: unknown } | undefined>
+    return typeof stored.deepseek?.key === 'string' && stored.deepseek.key !== ''
+  } catch {
+    return false
+  }
+}
+
+/** The headless programs this machine can offer: installed (an executable on the PATH; a wrapper function around it is fine) and, for pi, able to reach its model. */
 export function availableHeadless(wanted?: readonly HeadlessName[]): HeadlessName[] {
   const found: HeadlessName[] = []
   for (const driver of wanted ?? (['claude', 'codex', 'pi'] as const)) {
-    if (driver === 'pi' && !process.env.DEEPSEEK_API_KEY) continue
+    if (driver === 'pi' && !piHasDeepseekKey()) continue
     if (onPath(driver)) found.push(driver)
   }
   return found

package/plugins/desktop/launch.ts

@@ -0,0 +1,48 @@
+/**
+ * `npm run desktop`: starts Electron on `main.ts` next to this file. It exists for one case: on Linux where the kernel restricts unprivileged user namespaces
+ * (Ubuntu 23.10 and later: `kernel.apparmor_restrict_unprivileged_userns=1`), Chromium's sandbox cannot start for an Electron that npm unpacked into node_modules, and Electron
+ * aborts before any of our code runs. There, and only there, it starts with `--no-sandbox` and says so; everywhere else Electron starts exactly as it does with the sandbox on.
+ */
+import { spawn } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** The sysctl that makes the sandbox fail for an Electron without an AppArmor profile; its value, or `undefined` where it does not exist (every system but a recent Ubuntu). */
+export const RESTRICT_USERNS = '/proc/sys/kernel/apparmor_restrict_unprivileged_userns'
+
+/** Whether the sandbox cannot start here: Linux, with the restriction on. `read` returns a file's text, or throws when there is none. */
+export function sandboxBlocked(
+  platform: string,
+  read: (path: string) => string = (path) => readFileSync(path, 'utf8'),
+): boolean {
+  if (platform !== 'linux') return false
+  try {
+    return read(RESTRICT_USERNS).trim() === '1'
+  } catch {
+    return false
+  }
+}
+
+export const SANDBOX_NOTICE =
+  "desktop: this Linux restricts unprivileged user namespaces (kernel.apparmor_restrict_unprivileged_userns=1), so Electron's sandbox cannot start; starting with --no-sandbox. " +
+  'To keep the sandbox, give Electron an AppArmor profile that allows `userns` (the way the VS Code and Chrome packages do): see docs/framework/getting-started/desktop.md'
+
+/** The arguments for Electron: the entry file, with `--no-sandbox` first when the sandbox is blocked. */
+export function electronArgs(entry: string, blocked: boolean): string[] {
+  return blocked ? ['--no-sandbox', entry] : [entry]
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  const electron = createRequire(import.meta.url)('electron') as string
+  // ACRYLBLENDS_DESKTOP_SANDBOX=1: the owner has given Electron an AppArmor profile and wants the sandbox.
+  const blocked =
+    process.env.ACRYLBLENDS_DESKTOP_SANDBOX !== '1' && sandboxBlocked(process.platform)
+  if (blocked) console.warn(SANDBOX_NOTICE)
+  const child = spawn(electron, electronArgs(join(import.meta.dirname, 'main.ts'), blocked), {
+    stdio: 'inherit',
+  })
+  for (const signal of ['SIGINT', 'SIGTERM'] as const) process.on(signal, () => child.kill(signal))
+  child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)))
+}

package/plugins/desktop/plugin.json

@@ -9,7 +9,7 @@
     "electron": "44.9.3"
   },
   "scripts": {
-    "desktop": "electron plugins/desktop/main.ts"
+    "desktop": "node plugins/desktop/launch.ts"
   },
   "omit": ["**/*.test.*"],
   "mount": "nothing to mount: run `npm install`, then `npm run desktop` (the window opens on the app's own server; every electron call is in plugins/desktop)"

package/plugins/desktop-web/launch.ts

@@ -0,0 +1,48 @@
+/**
+ * `npm run desktop`: starts Electron on `main.ts` next to this file. It exists for one case: on Linux where the kernel restricts unprivileged user namespaces
+ * (Ubuntu 23.10 and later: `kernel.apparmor_restrict_unprivileged_userns=1`), Chromium's sandbox cannot start for an Electron that npm unpacked into node_modules, and Electron
+ * aborts before any of our code runs. There, and only there, it starts with `--no-sandbox` and says so; everywhere else Electron starts exactly as it does with the sandbox on.
+ */
+import { spawn } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** The sysctl that makes the sandbox fail for an Electron without an AppArmor profile; its value, or `undefined` where it does not exist (every system but a recent Ubuntu). */
+export const RESTRICT_USERNS = '/proc/sys/kernel/apparmor_restrict_unprivileged_userns'
+
+/** Whether the sandbox cannot start here: Linux, with the restriction on. `read` returns a file's text, or throws when there is none. */
+export function sandboxBlocked(
+  platform: string,
+  read: (path: string) => string = (path) => readFileSync(path, 'utf8'),
+): boolean {
+  if (platform !== 'linux') return false
+  try {
+    return read(RESTRICT_USERNS).trim() === '1'
+  } catch {
+    return false
+  }
+}
+
+export const SANDBOX_NOTICE =
+  "desktop: this Linux restricts unprivileged user namespaces (kernel.apparmor_restrict_unprivileged_userns=1), so Electron's sandbox cannot start; starting with --no-sandbox. " +
+  'To keep the sandbox, give Electron an AppArmor profile that allows `userns` (the way the VS Code and Chrome packages do): see docs/framework/getting-started/desktop.md'
+
+/** The arguments for Electron: the entry file, with `--no-sandbox` first when the sandbox is blocked. */
+export function electronArgs(entry: string, blocked: boolean): string[] {
+  return blocked ? ['--no-sandbox', entry] : [entry]
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  const electron = createRequire(import.meta.url)('electron') as string
+  // ACRYLBLENDS_DESKTOP_SANDBOX=1: the owner has given Electron an AppArmor profile and wants the sandbox.
+  const blocked =
+    process.env.ACRYLBLENDS_DESKTOP_SANDBOX !== '1' && sandboxBlocked(process.platform)
+  if (blocked) console.warn(SANDBOX_NOTICE)
+  const child = spawn(electron, electronArgs(join(import.meta.dirname, 'main.ts'), blocked), {
+    stdio: 'inherit',
+  })
+  for (const signal of ['SIGINT', 'SIGTERM'] as const) process.on(signal, () => child.kill(signal))
+  child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)))
+}

package/plugins/desktop-web/plugin.json

@@ -9,7 +9,7 @@
     "electron": "44.9.3"
   },
   "scripts": {
-    "desktop": "electron plugins/desktop-web/main.ts"
+    "desktop": "node plugins/desktop-web/launch.ts"
   },
   "gitignore": [".acrylblends/"],
   "omit": ["**/*.test.*"],

package/templates/chat/AGENTS.md

@@ -13,4 +13,4 @@ A Cordis app: `blend.yaml` lists the plugins that are mounted (`acryl-router`, `
 
 ## Before you ship
 
-Read `docs/framework/getting-started/deploy.md`. In short: `npm ci --omit=dev`, `npm run build`, `NODE_ENV=production npm start`; the app listens on `127.0.0.1` (`HOST=0.0.0.0` only in a container); the SQLite file goes outside the code folder (`CHAT_DB=/var/lib/chat/chat.sqlite`) and is backed up; the model key is an environment variable of the service (a root-only environment file for systemd), never a file in the repository. Anyone who can reach the app can spend your key: put it behind a login or on a private network before it is public.
+Read `docs/framework/getting-started/deploy.md`. In short: `npm ci --omit=dev`, `npm run build`, `NODE_ENV=production npm start`; the app listens on `127.0.0.1` (`HOST=0.0.0.0` only in a container); the SQLite file goes outside the code folder (`CHAT_DB=/var/lib/chat/chat.sqlite`) and is backed up; the model key is an environment variable of the service (a root-only environment file for systemd), never a file in the repository. Anyone who can reach the app can spend your key, so with `NODE_ENV=production` the chat is **closed**: every route but `GET /health` answers 503 (`src/access.ts`). Set `CHAT_ACCESS_TOKEN` (the browser asks for it; any user name, the token as the password), or name the chat in `ACRYL_PRODUCTION_KEEP=chat` to make it public on purpose: that prints a `WARNING` at start and limits one address to `CHAT_RATE_PER_MINUTE` messages a minute (default 20). Prefer your own login in front of a public chat.

package/templates/chat/src/access.ts

@@ -0,0 +1,110 @@
+import { createHash, timingSafeEqual } from 'node:crypto'
+import { connectionOf, createMiddleware } from '../plugins/acryl-router/src/helpers/index.ts'
+import type { Context } from '../plugins/acryl-router/src/index.ts'
+import { basicAuth } from '../plugins/acryl-router/src/middleware/index.ts'
+
+/** Who may use the chat, and what the app prints about it at start. */
+export type Access =
+  /** Development, and every test: no gate. */
+  | { kind: 'open' }
+  /** Production with `ACRYL_PRODUCTION_KEEP=chat`: anyone, with a per-IP rate limit. */
+  | { kind: 'public'; perMinute: number; trustProxy: boolean }
+  /** Production with `CHAT_ACCESS_TOKEN`: the browser asks for it (any user name, the token as the password). */
+  | { kind: 'token'; token: string }
+  /** Production with neither: every route but `/health` answers 503. */
+  | { kind: 'closed' }
+
+export interface Decision {
+  readonly access: Access
+  /** Lines to print at start (a `WARNING` for a public chat, the reason for a closed one). */
+  readonly notices: readonly string[]
+}
+
+/**
+ * Anyone who can reach the chat spends the model key, so in production it is closed by default. Name the chat in `ACRYL_PRODUCTION_KEEP` to make it public
+ * (loudly, with a rate limit), or set `CHAT_ACCESS_TOKEN` to ask for a shared token.
+ */
+export function chatAccess(env: Readonly<Record<string, string | undefined>>): Decision {
+  if (env.NODE_ENV !== 'production') return { access: { kind: 'open' }, notices: [] }
+  const keep = (env.ACRYL_PRODUCTION_KEEP ?? '')
+    .split(',')
+    .map((name) => name.trim())
+    .filter(Boolean)
+  if (keep.includes('chat')) {
+    const perMinute = Number(env.CHAT_RATE_PER_MINUTE)
+    return {
+      access: {
+        kind: 'public',
+        perMinute: Number.isInteger(perMinute) && perMinute > 0 ? perMinute : 20,
+        trustProxy: env.TRUST_PROXY === '1',
+      },
+      notices: [
+        'WARNING: the chat is public in production because ACRYL_PRODUCTION_KEEP names "chat": anyone who can reach it spends your model key (each address is limited to a few messages a minute). Put your own login in front of it, or set CHAT_ACCESS_TOKEN instead.',
+      ],
+    }
+  }
+  const token = env.CHAT_ACCESS_TOKEN?.trim()
+  if (token) return { access: { kind: 'token', token }, notices: [] }
+  return {
+    access: { kind: 'closed' },
+    notices: [
+      'The chat is closed: with NODE_ENV=production it needs CHAT_ACCESS_TOKEN (the browser asks for it) or ACRYL_PRODUCTION_KEEP=chat to be public. Every route but /health answers 503 until then.',
+    ],
+  }
+}
+
+const digest = (text: string) => createHash('sha256').update(text).digest()
+
+/** The middleware for an access mode, mounted before the routes. `/health` is always open. */
+export function accessGate(access: Access) {
+  if (access.kind === 'open') return undefined
+  if (access.kind === 'closed')
+    return createMiddleware(async (c, next) => {
+      if (c.req.path === '/health') return next()
+      return c.json(
+        {
+          error:
+            'The chat is closed. Set CHAT_ACCESS_TOKEN, or ACRYL_PRODUCTION_KEEP=chat to make it public.',
+        },
+        503,
+      )
+    })
+  if (access.kind === 'token') {
+    const expected = digest(access.token)
+    const ask = basicAuth({
+      realm: 'chat',
+      verifyUser: (_user, password) => timingSafeEqual(digest(password), expected),
+    })
+    return createMiddleware(async (c, next) => (c.req.path === '/health' ? next() : ask(c, next)))
+  }
+  return rateLimit(access.perMinute, access.trustProxy)
+}
+
+/** At most `perMinute` messages a minute from one address (`POST /api/chat`); the table forgets an address a minute after its last message. */
+function rateLimit(perMinute: number, trustProxy: boolean) {
+  const seen = new Map<string, number[]>()
+  const addressOf = (c: Context) => {
+    if (trustProxy) {
+      const forwarded = c.req.header('x-forwarded-for')?.split(',').at(-1)?.trim()
+      if (forwarded) return forwarded
+    }
+    return connectionOf(c).remoteAddress ?? 'unknown'
+  }
+  return createMiddleware(async (c, next) => {
+    if (c.req.method !== 'POST' || c.req.path !== '/api/chat') return next()
+    const now = Date.now()
+    for (const [address, times] of seen)
+      if (now - (times.at(-1) ?? 0) > 60_000) seen.delete(address)
+    const address = addressOf(c)
+    const recent = (seen.get(address) ?? []).filter((time) => now - time < 60_000)
+    if (recent.length >= perMinute) {
+      seen.set(address, recent)
+      const wait = Math.ceil((60_000 - (now - (recent[0] ?? now))) / 1000)
+      c.header('retry-after', String(wait))
+      return c.json({ error: 'Too many messages. Try again in a minute.' }, 429)
+    }
+    recent.push(now)
+    seen.set(address, recent)
+    return next()
+  })
+}

package/templates/chat/src/chat-app.ts

@@ -5,6 +5,7 @@ import {
   streamSSE,
 } from '../plugins/acryl-router/src/helpers/index.ts'
 import { Acryl } from '../plugins/acryl-router/src/index.ts'
+import { type Access, accessGate } from './access.ts'
 import { chatStore } from './db.ts'
 import { type Llm, openAiCompatible } from './llm.ts'
 import { chatPage } from './page.tsx'
@@ -32,9 +33,14 @@ const ChatSchema: StandardSchema<ChatInput> = {
   },
 }
 
-export function createApp(db: Db, llm: Llm = openAiCompatible) {
+/** `access` is who may use the chat (default: anyone, as in development and in the tests); see `src/access.ts`. */
+export function createApp(db: Db, llm: Llm = openAiCompatible, access: Access = { kind: 'open' }) {
   const store = chatStore(db)
   const app = new Acryl()
+  const gate = accessGate(access)
+  if (gate) app.use(gate)
+
+  app.get('/health', (c) => c.json({ ok: true }))
 
   app.get('/', async (c) => {
     const id = Number(c.req.query('c'))

package/templates/chat/src/routes.ts

@@ -1,5 +1,6 @@
 import type { Context } from '@deepseek-ai/cordis'
 import type {} from '../plugins/acryl-db/src/cordis.ts'
+import { chatAccess } from './access.ts'
 import { createApp } from './chat-app.ts'
 import { openAiCompatible } from './llm.ts'
 import { createClient } from './runtime.ts'
@@ -9,7 +10,10 @@ export const routes = {
   name: 'routes',
   inject: ['router', 'db'],
   apply(ctx: Context) {
-    ctx.router.route('/', createApp(ctx.db, openAiCompatible))
+    // In production the chat is closed unless it has a token or is made public on purpose: anyone who reaches it spends the model key.
+    const { access, notices } = chatAccess(process.env)
+    for (const line of notices) console.warn(line)
+    ctx.router.route('/', createApp(ctx.db, openAiCompatible, access))
     ctx.router.route('/client', createClient())
   },
 }