acrylblends 1.4.0 → 1.5.1

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.*