acrylblends 1.3.2 → 1.5.0

package/templates/agent/src/routes.ts

@@ -3,6 +3,7 @@ import { Acryl } from '../plugins/acryl-router/src/index.ts'
 import { bodyLimit } from '../plugins/acryl-router/src/middleware/index.ts'
 import type {} from '../plugins/agent/index.ts'
 import type {} from '../plugins/extensions/index.ts'
+import { type Home, renderWidgets } from '../plugins/home/index.ts'
 import type {} from '../plugins/tasks/index.ts'
 
 export const APP_NAME = '__APP_NAME__'
@@ -59,20 +60,24 @@ const appearanceScript = (prefix: string) => `<script src="${prefix}/appearance.
 const settingsPage = (prefix: string) =>
   `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>Settings - ${APP_NAME}</title>${APPEARANCE_STYLE}${appearanceScript(prefix)}</head><body><h1>Settings</h1><p><label for="theme">Appearance</label> <select id="theme" name="theme"><option value="system">Match the system</option><option value="light">Light</option><option value="dark">Dark</option></select></p><p id="saved" role="status"></p><p><a href="${prefix}/">Back to ${APP_NAME}</a></p><script>(function(){var select=document.getElementById('theme'),saved=document.getElementById('saved');try{select.value=localStorage.getItem('theme')||'system'}catch(e){}select.addEventListener('change',function(){var value=select.value;try{if(value==='system'){localStorage.removeItem('theme');delete document.documentElement.dataset.theme}else{localStorage.setItem('theme',value);document.documentElement.dataset.theme=value}saved.textContent='Saved: '+select.options[select.selectedIndex].text}catch(e){saved.textContent='This browser would not keep the setting.'}})})()</script></body></html>`
 
+const widgetsOf = (home: Home | undefined): Promise<string> =>
+  home === undefined ? Promise.resolve('') : renderWidgets(home)
+
 /**
  * The app's own pages and routes, mountable at any prefix: the standalone server mounts it at the root, the frame row at {@link FRAME_MOUNT_PREFIX}.
- * Every absolute URL a page writes is derived from the prefix it is mounted at.
+ * Every absolute URL a page writes is derived from the prefix it is mounted at. The home page shows the widgets of the app's plugins (`ctx.home`), read
+ * at each request through `home()`, so a plugin pulled, switched off or removed shows at the next load; without a home service the page has none.
  */
-export function makeApp(prefix = ''): Acryl {
+export function makeApp(prefix = '', home: () => Home | undefined = () => undefined): Acryl {
   const limit = bodyLimit({ maxSize: 64 * 1024 })
   return (
     new Acryl()
       .use(limit)
       // A browser gets a page (the door's and the agent panel's script tags are added where they are mounted); everything else gets the JSON.
-      .get('/', (c) =>
+      .get('/', async (c) =>
         (c.req.header('accept') ?? '').includes('text/html')
           ? c.html(
-              `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>${APP_NAME}</title>${APPEARANCE_STYLE}${appearanceScript(prefix)}</head><body><h1>${APP_NAME}</h1><p>This app runs an agent unless it is switched off (production switches it off, see ACRYL_PRODUCTION_KEEP in AGENTS.md). In ACRYL, ask it for a change in the chat beside the app (or with <code>POST /ask</code>); published with the assistant on, it helps visitors use the app without changing it.</p>${DOOR_TAG}</body></html>`,
+              `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>${APP_NAME}</title>${APPEARANCE_STYLE}${appearanceScript(prefix)}</head><body><h1>${APP_NAME}</h1><p>This app runs an agent unless it is switched off (production switches it off, see ACRYL_PRODUCTION_KEEP in AGENTS.md). In ACRYL, ask it for a change in the chat beside the app (or with <code>POST /ask</code>); published with the assistant on, it helps visitors use the app without changing it.</p>${await widgetsOf(home())}${DOOR_TAG}</body></html>`,
             )
           : c.json({ app: APP_NAME, ok: true }),
       )
@@ -102,7 +107,20 @@ export const routes = {
     }
     const limit = bodyLimit({ maxSize: 64 * 1024 })
     // The app's own page and routes at the one prefix; the agent routes below mount at the same prefix.
-    ctx.router.route(prefix === '' ? '/' : prefix, makeApp(prefix))
+    // The home page's widgets while a `home` row runs: an app made before the agent template mounted `home` (its blend.yaml has no such row) keeps its pages.
+    let home: Home | undefined
+    ctx.inject(['home'], (inner) => {
+      inner.effect(() => {
+        home = inner.home
+        return () => {
+          home = undefined
+        }
+      }, 'routes: the home page widgets')
+    })
+    ctx.router.route(
+      prefix === '' ? '/' : prefix,
+      makeApp(prefix, () => home),
+    )
     // The routes that give a visitor the agent: mounted only while the agent, the extensions and the tasks run (see the header).
     // `agentRoutes: false` (the production Assistant) keeps them unmounted although the agent runs.
     if (options.agentRoutes === false) return

package/templates/agent/template.json

@@ -2,6 +2,7 @@
   "plugins": [
     "instance",
     "acryl-router",
+    "home",
     "acryl-state",
     "acryl-node-server",
     "acryl-page",

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

@@ -44,6 +44,32 @@ test('answers health checks and 404 for unknown paths', () =>
     await missing.body?.cancel()
   }))
 
+test('a plugin puts its widget on the home page, and the widget leaves with the plugin', () =>
+  withApp(async (app) => {
+    const page = async () =>
+      (await app.root.router.request('/', { headers: { accept: 'text/html' } })).text()
+    const feature = app.root.plugin({
+      name: 'hello-widget',
+      inject: ['home'],
+      apply(ctx: typeof app.root) {
+        ctx.effect(() =>
+          ctx.home.widget({
+            id: 'hello-widget',
+            title: 'Hello',
+            render: () => '<p id="hello">hi</p>',
+          }),
+        )
+      },
+    })
+    await feature.await()
+    assert.match(
+      await page(),
+      /<section class="widget" data-widget="hello-widget">[\s\S]*<p id="hello">hi<\/p>/,
+    )
+    await feature.dispose()
+    assert.doesNotMatch(await page(), /data-widget="hello-widget"/)
+  }))
+
 /** 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. */
 /**
  * Whether this environment forbids listening at all: only a sandbox's refusal (EPERM/EACCES) means the real-server test must skip. A loaded

package/templates/blank/README.md

@@ -5,7 +5,7 @@ Cordis plugin.
 
 ```sh
 npm install
-npm run dev        # prints its URL; data lives in .acrylblends/
+npm run dev        # prints its URL; data lives in ~/.acryl/apps/<id>/data/
 npm test
 npm run check      # type-check
 ```

package/templates/blank/gitignore

@@ -2,3 +2,5 @@ node_modules/
 .acrylblends/
 .acryl/
 package-lock.json
+.env
+.env.*

package/templates/blank/src/routes.ts

@@ -9,7 +9,7 @@ export const APP_NAME = '__APP_NAME__'
 /**
  * The only place the app's mount prefix is named. On its own server (production, `npm start`) the app mounts at the root and
  * its public URLs are `/`, `/about`, `/health`; when the ACRYL frame hosts it (`npm run dev`) the routes mount here, and the
- * frame opens its tile at `/app/`. Every page link and asset URL this template writes is derived from the prefix it is
+ * frame opens its tile at `/app` (`/app/` answers too). Every page link and asset URL this template writes is derived from the prefix it is
  * mounted at, so the same source serves both.
  */
 export const FRAME_MOUNT_PREFIX = '/app'
@@ -50,14 +50,14 @@ const homePage = (name: string, widgets: string): string => `<!doctype html>
  * The app's own pages and routes, mountable at any prefix: the standalone server mounts it at the root, the frame host at {@link FRAME_MOUNT_PREFIX}.
  * The first screen shows the widgets of the app's plugins (`ctx.home`), read at each request, so a plugin switched on or off shows at the next load.
  */
-export function makeApp(home: Home): Acryl {
+export function makeApp(home: Home, name: () => string = () => APP_NAME): Acryl {
   return (
     new Acryl()
       // A browser gets the first screen; an API client gets the JSON hello.
       .get('/', async (c) =>
         (c.req.header('accept') ?? '').includes('text/html')
-          ? c.html(homePage(APP_NAME, await renderWidgets(home)))
-          : c.json({ app: APP_NAME, ok: true }),
+          ? c.html(homePage(name(), await renderWidgets(home)))
+          : c.json({ app: name(), ok: true }),
       )
       .get('/health', (c) => c.json({ ok: true }))
       .get('/about', (c) => c.html(aboutPage()))
@@ -70,6 +70,10 @@ export const routes = {
   inject: ['router', 'home'],
   apply(ctx: Context, options: { readonly prefix?: string } = {}) {
     const prefix = options.prefix ?? ''
-    ctx.router.route(prefix === '' ? '/' : prefix, makeApp(ctx.home))
+    // The name the app has now (Settings > App renames it), else the one the scaffold was made with.
+    ctx.router.route(
+      prefix === '' ? '/' : prefix,
+      makeApp(ctx.home, () => ctx.get('appInstance')?.name ?? APP_NAME),
+    )
   },
 }

package/templates/chat/gitignore

@@ -5,3 +5,5 @@ data/
 *.sqlite
 *.sqlite-*
 package-lock.json
+.env
+.env.*

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

@@ -7,7 +7,7 @@ import {
 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 { type Llm, MissingKey, openAiCompatible } from './llm.ts'
 import { chatPage } from './page.tsx'
 
 interface ChatInput {
@@ -99,10 +99,14 @@ export function createApp(
       } catch (error) {
         if (!signal.aborted) {
           console.error(error)
-          // The reason stays in the log; the page gets a plain message.
+          // The reason stays in the log; the page gets a plain message, or how to set the missing key.
           await stream.writeSSE({
             event: 'error',
-            data: JSON.stringify('The model could not answer. Try again.'),
+            data: JSON.stringify(
+              error instanceof MissingKey
+                ? error.message
+                : 'The model could not answer. Try again.',
+            ),
           })
         }
       } finally {

package/templates/chat/src/llm.ts

@@ -4,13 +4,19 @@ export type Llm = (
   signal: AbortSignal,
 ) => AsyncIterable<string>
 
+/** The model has no key: the one failure whose message the page may show, since it names the fix and holds no detail from the service. */
+export class MissingKey extends Error {}
+
 /**
  * An OpenAI-compatible chat completions API with `stream: true` (DeepSeek by default). The key is read from DEEPSEEK_API_KEY at the moment of the call and
  * is never stored; DEEPSEEK_BASE_URL and DEEPSEEK_MODEL choose the service.
  */
 export const openAiCompatible: Llm = async function* (messages, signal) {
   const key = process.env.DEEPSEEK_API_KEY
-  if (!key) throw new Error('DEEPSEEK_API_KEY is not set')
+  if (!key)
+    throw new MissingKey(
+      'DEEPSEEK_API_KEY is not set: set it in the terminal that runs the app, then start the app again.',
+    )
   const base = (process.env.DEEPSEEK_BASE_URL ?? 'https://api.deepseek.com').replace(/\/$/, '')
   const response = await fetch(`${base}/chat/completions`, {
     method: 'POST',

package/templates/chat/test/chat.test.ts

@@ -12,7 +12,7 @@ import { pinnedInstance, withPort } from '../plugins/instance/index.ts'
 import { chatAccess } from '../src/access.ts'
 import { createApp as boot } from '../src/app.ts'
 import { createApp } from '../src/chat-app.ts'
-import type { Llm } from '../src/llm.ts'
+import { type Llm, openAiCompatible } from '../src/llm.ts'
 import { FRAME_MOUNT_PREFIX } 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. */
@@ -155,6 +155,21 @@ test('a failing model sends an error event with a plain message and no detail',
   assert.match(last?.[1] ?? '', /could not answer/)
 })
 
+test('a model without its key tells the page which variable to set', async () => {
+  const saved = process.env.DEEPSEEK_API_KEY
+  delete process.env.DEEPSEEK_API_KEY
+  try {
+    const app = createApp(await memoryDb(), openAiCompatible)
+    const last = events(await (await app.request('/api/chat', post({ message: 'hi' }))).text()).at(
+      -1,
+    )
+    assert.equal(last?.[0], 'error')
+    assert.match(last?.[1] ?? '', /DEEPSEEK_API_KEY is not set/)
+  } finally {
+    if (saved !== undefined) process.env.DEEPSEEK_API_KEY = saved
+  }
+})
+
 test('when the client goes away the model call is aborted and what arrived is kept', async () => {
   let sawAbort: (value: boolean) => void = () => {}
   const aborted = new Promise<boolean>((resolve) => {

package/templates/nodejs/gitignore

@@ -2,3 +2,5 @@ node_modules/
 .acrylblends/
 .acryl/
 package-lock.json
+.env
+.env.*

package/templates/notes/gitignore

@@ -5,3 +5,5 @@ data/
 *.sqlite
 *.sqlite-*
 package-lock.json
+.env
+.env.*

package/templates/todo/README.md

@@ -21,7 +21,7 @@ curl -N $URL/todo/events
 
 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).
+Open `$URL/todo` for the page. Stop the app and start it again: the list is still there (`<home>/todo.json`, `~/.acryl/apps/<id>/data/` 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 `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/gitignore

@@ -2,3 +2,5 @@ node_modules/
 .acrylblends/
 .acryl/
 package-lock.json
+.env
+.env.*