acrylblends 1.3.2 → 1.4.0

package/plugins/showcase/cards.ts

@@ -0,0 +1,162 @@
+/**
+ * The showcase's cards: what each plugin in the app is, who made it and where to find what it adds. Pure, so the page, the stream and the tests
+ * render the same thing.
+ */
+import type { SharedPluginInfo } from '../plugin-share/index.ts'
+
+/** One plugin as the showcase shows it. */
+export interface ShowcaseCard {
+  readonly name: string
+  /** The release's version, or the installed content's short digest for a plugin without one. */
+  readonly version: string
+  readonly state: string
+  /** The GitHub login of whoever released it; absent for a plugin made in this app or pulled from a local file. */
+  readonly author?: string
+  /** Where it came from: the pulled source, or `this app`. */
+  readonly source: string
+  /** The pages it serves (`GET` routes without parameters), as the plugin wrote them. */
+  readonly pages: readonly string[]
+  /** It has a widget on the home page. */
+  readonly widget: boolean
+  /** The tool of its name, when it registered one. */
+  readonly tool?: string
+}
+
+/** What else the app knows about its plugins: the tools registered and the home page's widgets, by name. */
+export interface Offered {
+  readonly tools: readonly string[]
+  readonly widgets: readonly string[]
+}
+
+/** A GitHub login: what `author` must look like before the page links to github.com. */
+const LOGIN = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/u
+
+/** A path a person can open: no `:param`, no wildcard. */
+const PAGE = /^\/[^:*]*$/u
+
+/** The cards, one per plugin, in the order the app lists them. */
+export function showcaseCards(
+  plugins: readonly SharedPluginInfo[],
+  offered: Offered,
+): ShowcaseCard[] {
+  return plugins.map((plugin) => {
+    const pages = [
+      ...new Set(
+        plugin.routes
+          .filter((route) => route.method === 'GET' && PAGE.test(route.path))
+          .map((route) => route.path),
+      ),
+    ]
+    return {
+      name: plugin.name,
+      version: plugin.release ?? plugin.version,
+      state: plugin.state,
+      ...(plugin.author !== undefined && LOGIN.test(plugin.author)
+        ? { author: plugin.author }
+        : {}),
+      source: plugin.pulledFrom ?? 'this app',
+      pages,
+      widget: offered.widgets.includes(plugin.name),
+      ...(offered.tools.includes(plugin.name) ? { tool: plugin.name } : {}),
+    }
+  })
+}
+
+const escapeHtml = (text: string): string =>
+  text
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+
+/**
+ * The path the app is served at, read from the showcase's own request path: `''` on the app's own server, `/app` in the frame. Links are built from it,
+ * because a relative link cannot name the app's root (`./` from `/app/showcase` is `/app/`, which the app does not serve).
+ */
+export function appBase(requestPath: string): string {
+  const at = requestPath.lastIndexOf('/showcase')
+  return at <= 0 ? '' : requestPath.slice(0, at)
+}
+
+/** A path of the app as the browser asks for it: under `base`, and the root as `base` itself (or `/`). */
+const inApp = (base: string, path: string): string =>
+  path === '/' ? base || '/' : `${base}${path}`
+
+/** The cards as HTML: the list the page shows, and what the stream sends on each change. Every value is escaped. */
+export function renderCards(cards: readonly ShowcaseCard[], base = ''): string {
+  if (cards.length === 0)
+    return '<p class="empty">No plugins yet. Pull one: <code>npm run acryl -- plugin pull github:&lt;owner&gt;/&lt;repo&gt;</code>, or a group\'s list with <code>--from group.txt</code>.</p>'
+  return cards
+    .map((card) => {
+      const author =
+        card.author === undefined
+          ? '<span class="dim">made here</span>'
+          : `<a href="https://github.com/${escapeHtml(card.author)}" target="_blank" rel="noopener">@${escapeHtml(card.author)}</a>`
+      const links = [
+        ...card.pages.map(
+          (page) => `<a href="${escapeHtml(inApp(base, page))}">${escapeHtml(page)}</a>`,
+        ),
+        ...(card.widget ? [`<a href="${escapeHtml(inApp(base, '/'))}">home widget</a>`] : []),
+        ...(card.tool === undefined
+          ? []
+          : [
+              `<span title="the app's agent can call it">tool <code>${escapeHtml(card.tool)}</code></span>`,
+            ]),
+      ]
+      return [
+        `<article class="card" data-plugin="${escapeHtml(card.name)}" data-state="${escapeHtml(card.state)}">`,
+        `<header><h2>${escapeHtml(card.name)}</h2><p class="meta"><span class="version">${escapeHtml(card.version)}</span><span class="state state-${escapeHtml(card.state)}">${escapeHtml(card.state)}</span></p></header>`,
+        `<p class="author">${author}</p>`,
+        `<p class="source"><code>${escapeHtml(card.source)}</code></p>`,
+        links.length === 0
+          ? '<p class="dim">no page of its own</p>'
+          : `<p class="links">${links.join(' ')}</p>`,
+        '</article>',
+      ].join('')
+    })
+    .join('\n')
+}
+
+const STYLES = `:root{--bg:#fff;--surface:#f7f7f9;--border:#e2e2e8;--text:#18181b;--dim:#6b6b75;--accent:#5468ff;--ok:#2f9e44;--warn:#d9480f;color-scheme:light}
+@media (prefers-color-scheme:dark){:root{--bg:#0b0b0d;--surface:#18181b;--border:#2a2a2f;--text:#e8e8ea;--dim:#8b8b93;color-scheme:dark}}
+*{box-sizing:border-box}
+body{margin:0;padding:24px 16px;background:var(--bg);color:var(--text);font:14px/1.5 system-ui,-apple-system,"Segoe UI",sans-serif}
+main{max-width:1080px;margin:0 auto}
+h1{margin:0 0 4px;font-size:20px}
+.lead{margin:0 0 20px;color:var(--dim)}
+#cards{display:grid;grid-template-columns:repeat(auto-fill,minmax(260px,1fr));gap:12px}
+.card{padding:14px 16px;border:1px solid var(--border);border-radius:12px;background:var(--surface);min-width:0}
+.card header{margin-bottom:8px}
+.card h2{margin:0 0 4px;font-size:15px;font-weight:600;overflow-wrap:anywhere}
+.card .meta{display:flex;align-items:center;gap:8px;margin:0}
+.version{color:var(--dim);font-variant-numeric:tabular-nums}
+.state{padding:1px 8px;border-radius:999px;border:1px solid var(--border);font-size:12px;color:var(--dim)}
+.state-active{color:var(--ok);border-color:currentColor}
+.state-failed,.state-pending{color:var(--warn);border-color:currentColor}
+.card p{margin:4px 0}
+.source code{font-size:12px;color:var(--dim);overflow-wrap:anywhere}
+.links{display:flex;flex-wrap:wrap;gap:6px 12px}
+a{color:var(--accent);text-decoration:none}
+a:hover{text-decoration:underline}
+.dim,.empty{color:var(--dim)}
+#live{font-size:12px;color:var(--dim)}`
+
+/** The whole page; the script follows the stream and replaces the cards on each change. */
+export function renderPage(cards: readonly ShowcaseCard[], base = ''): string {
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Showcase</title><style>${STYLES}</style></head>
+<body><main>
+<h1>Showcase</h1>
+<p class="lead">Every plugin in this app, who made it and where it came from. <span id="live" role="status"></span></p>
+<section id="cards" aria-live="polite">${renderCards(cards, base)}</section>
+</main>
+<script type="module">
+const cards = document.getElementById('cards')
+const live = document.getElementById('live')
+const events = new EventSource(${JSON.stringify(`${base}/showcase/events`).replaceAll('<', '\\u003c')})
+events.addEventListener('cards', (event) => { cards.innerHTML = event.data; live.textContent = 'live' })
+events.onerror = () => { live.textContent = 'reconnecting...' }
+</script>
+</body></html>`
+}

package/plugins/showcase/index.ts

@@ -0,0 +1,116 @@
+/**
+ * The collective app's showcase: every plugin in the app as a card (name, author, version, source, state, links to what it adds) at `/showcase`,
+ * updated live as plugins are pulled and removed.
+ *
+ * A group pulls its members' plugins into one app (`plugin pull --from group.txt`); this page is where they see what the group made. It reads the
+ * app's plugins through `pluginShare` (which knows where each pulled one came from), and follows `extensions/changed`: every install, update,
+ * restore and removal goes through extensions, so one event covers them all. The stream's open connections end with the plugin.
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import { streamSSE } from '../acryl-router/src/helpers/index.ts'
+import { Acryl } from '../acryl-router/src/index.ts'
+import type {} from '../extensions/index.ts'
+import type {} from '../plugin-share/index.ts'
+import {
+  appBase,
+  type Offered,
+  renderCards,
+  renderPage,
+  type ShowcaseCard,
+  showcaseCards,
+} from './cards.ts'
+
+export type { ShowcaseCard } from './cards.ts'
+export { appBase, renderCards, showcaseCards } from './cards.ts'
+
+export const name = 'showcase'
+export const inject = ['router', 'pluginShare']
+
+/** A comment line this often keeps an idle stream open through proxies and browsers. */
+const KEEP_ALIVE_MS = 15_000
+
+/**
+ * The names an optional service lists, or none when it is absent or is not the service the showcase knows. A name can be someone else's: in the
+ * frame `tools` is the host's (the DSH harness's tool registry, with another shape), not the app's agent tools, so the shape is checked, not assumed.
+ */
+function namesOf(service: unknown, method: string, key: string): string[] {
+  const list = (service as Record<string, unknown> | undefined)?.[method]
+  if (typeof list !== 'function') return []
+  let entries: unknown
+  try {
+    entries = (list as () => unknown).call(service)
+  } catch {
+    return []
+  }
+  if (!Array.isArray(entries)) return []
+  return entries.flatMap((entry) => {
+    const value = (entry as Record<string, unknown> | null)?.[key]
+    return typeof value === 'string' ? [value] : []
+  })
+}
+
+/** The optional services the cards link to, read where they are now: an app without an agent has no tools, one without a home page no widgets. */
+function offered(ctx: Context): Offered {
+  const get = ctx.get as (service: string) => unknown
+  return {
+    tools: namesOf(get('tools'), 'list', 'name'),
+    widgets: namesOf(get('home'), 'widgets', 'id'),
+  }
+}
+
+export function apply(ctx: Context): void {
+  const cards = (): ShowcaseCard[] => showcaseCards(ctx.pluginShare.list(), offered(ctx))
+
+  // The pages that follow the stream; each gets the cards again after every change, rendered for the path it is served at.
+  const listeners = new Set<(now: readonly ShowcaseCard[]) => void>()
+  const ends = new Set<() => void>()
+  ctx.on('extensions/changed', () => {
+    if (listeners.size === 0) return
+    const now = cards()
+    for (const listener of listeners) listener(now)
+  })
+  ctx.effect(
+    () => () => {
+      for (const end of ends) end()
+    },
+    'showcase: end the open streams',
+  )
+
+  const app = new Acryl()
+    .get('/showcase', (c) =>
+      c.html(renderPage(cards(), appBase(c.req.path)), 200, { 'cache-control': 'no-store' }),
+    )
+    .get('/showcase/plugins', (c) => c.json(cards(), 200, { 'cache-control': 'no-store' }))
+    .get('/showcase/events', (c) =>
+      streamSSE(c, async (stream) => {
+        const base = appBase(c.req.path)
+        let queue: Promise<unknown> = Promise.resolve()
+        const send = (now: readonly ShowcaseCard[]): void => {
+          queue = queue
+            .then(() => stream.writeSSE({ event: 'cards', data: renderCards(now, base) }))
+            .catch(() => undefined)
+        }
+        let finish = (): void => undefined
+        const ended = new Promise<void>((resolve) => {
+          finish = resolve
+          stream.onAbort(resolve)
+        })
+        ends.add(finish)
+        listeners.add(send)
+        send(cards())
+        const keepAlive = setInterval(() => {
+          queue = queue.then(() => stream.write(': keepalive\n\n')).catch(() => undefined)
+        }, KEEP_ALIVE_MS)
+        keepAlive.unref()
+        try {
+          await ended
+        } finally {
+          clearInterval(keepAlive)
+          listeners.delete(send)
+          ends.delete(finish)
+          await queue
+        }
+      }),
+    )
+  ctx.router.route('/', app)
+}

package/plugins/showcase/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "showcase",
+  "description": "The collective app's showcase: a page at /showcase with a card for every plugin in the app (name, author, version, where it came from, its state, and links to its pages, its home widget and its tool), updated live as plugins are pulled and removed.",
+  "requires": ["acryl-router", "plugin-share", "extensions"],
+  "inject": ["router", "pluginShare"],
+  "provides": [],
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.4"
+  },
+  "mount": "a row `- id: showcase` / `name: showcase` after the plugin-share row in blend.yaml, and 'showcase': showcase in the registry of src/app.ts (acrylblends add showcase does both)"
+}

package/templates/agent/AGENTS.md

@@ -5,6 +5,10 @@ Besides `src/routes.ts`, the app runs an agent (`POST /ask`) that can write plug
 rollback; `GET /extensions` and `GET /tasks` show what it did. A plugin there is a folder with an `index.ts` exporting `name`, `inject`, `apply(ctx)`
 and an optional `check(ctx)` that receives the plugin's own context (so `ctx.router` reads as in `apply`). It may import `acryl-router`.
 
+**A plugin's UI on the home page.** The home page shows the widget of every plugin that registers one (the `home` row): `inject: ['home']` and
+`ctx.effect(() => ctx.home.widget({ id: '<plugin name>', title, render: () => '<p>...</p>' }))`. The widget leaves with its plugin, and a second
+plugin with the same widget id is refused naming the first. A widget is the way a plugin someone else pulls into this app shows up on the first screen.
+
 **Write an extension, not a row.** A feature you build while the app runs is a folder `plugins/<name>/` installed with `.acryl/bin/acryl plugin add plugins/<name>` (the `extensions` plugin loads it again at every start). Add a row to `blend.yaml` (`- id: <name>` / `name: <name>`; `src/app.ts` finds the folder by that name) only when the person asks for a plugin that is part of the app itself. Both kinds may import the framework by name (`acrylblends`, `acrylblends/body-limit`, `acryl-router`); a row's relative imports of its sibling plugins also work.
 
 **Drive the app you build.** `.acryl/bin/acryl look` reads the open page as text with refs, and `acryl act click|type|press|scroll|wait --ref <ref>` presses its buttons, opens its sidebars and fills its forms (look again before each act: the refs change). `act navigate --path /settings` goes to another page of the app; a path the app does not serve answers `404 at /nope` and the window shows a 404 page, so navigate on from there. In the desktop app (`npm run desktop`) the app's windows and menu are verbs too: `acryl window list`, `acryl window open --path /settings`, `acryl look --window <id>` (and `act ... --window <id>`) to drive that window's page, `acryl window resize|focus|close --id <id>`, `acryl menu list` and `acryl menu click --path "File>New Note"`. Closing the last window and Quit end the desktop app, so they need `--force`: do not use it unless the person asks. The app has a `/settings` page already (the appearance: system, light or dark, kept in the browser) and the desktop app's menu has a Settings item that opens it; add a person's other settings to that page, not to a new one, so `acryl menu click --path "File>Settings..."` and `acryl window open --path /settings` keep opening them (on macOS the item is in the application menu). Without a desktop app these answer "no desktop window is attached; run npm run desktop".

package/templates/agent/blend.yaml

@@ -39,6 +39,9 @@ spec:
         steps: "{{parameters.steps}}"
     - id: router
       name: acryl-router
+    # The home page's widgets: a plugin puts its UI on the home page with ctx.home.widget (one pulled from someone else's app too), and it leaves with the plugin.
+    - id: home
+      name: home
     - id: state
       name: acryl-state
     - id: sandbox

package/templates/agent/src/app.ts

@@ -10,6 +10,7 @@ import { agent, memory, model, scripted, tools } from '../plugins/agent/index.ts
 import * as panel from '../plugins/agent-panel/index.ts'
 import { builder } from '../plugins/builder/index.ts'
 import { extensions } from '../plugins/extensions/index.ts'
+import * as home from '../plugins/home/index.ts'
 import { type AppInstance, instance } from '../plugins/instance/index.ts'
 import {
   appPluginNames,
@@ -34,6 +35,7 @@ export const registry = {
   memory,
   agent,
   'acryl-router': router,
+  home,
   'acryl-state': state,
   extensions,
   builder,

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