acrylblends 1.3.2 → 1.5.0

package/plugins/plugin-share/index.ts

@@ -10,6 +10,7 @@ import {
   readFileSync,
   renameSync,
   rmSync,
+  statSync,
   writeFileSync,
 } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
@@ -54,6 +55,7 @@ import {
   refuse,
   splitDigest,
 } from './pull-check.ts'
+import { LIST_MAX_BYTES, parsePullList, pullListLocation } from './pull-list.ts'
 import { type PulledRecord, pulledRecords, withPulledRecord } from './pulled-records.ts'
 
 export type {
@@ -76,6 +78,8 @@ export interface PluginShareConfig {
   releases?: ReleasePort
   /** Where a publish goes. Defaults to the person's own `gh` and `git`. */
   publish?: PublishPorts
+  /** How an https address is read: a release `.tgz` and a list of sources. Defaults to HTTPS with the hub's size and time limits. */
+  download?: (url: string) => Promise<Uint8Array>
 }
 
 export type PullResult =
@@ -94,6 +98,19 @@ export type PullResult =
     }
   | PullRefused
 
+/** One source of a list and what pulling it did. */
+export interface PullListEntry {
+  /** Its line in the list. */
+  readonly line: number
+  readonly source: string
+  readonly result: PullResult
+}
+
+/** A list pulled: every source with its own result (some may be refused while the others install), or the list itself refused. */
+export type PullListResult =
+  | { readonly ok: true; readonly from: string; readonly entries: readonly PullListEntry[] }
+  | PullRefused
+
 /** One plugin installed while the app runs, as a person reads the list: what it is and, for one pulled, where it came from and who released it. */
 /** What extensions says about an installed plugin (its state, the services a pending one waits for, ...), and where a pulled one came from. */
 export interface SharedPluginInfo extends ExtensionInfo {
@@ -101,6 +118,8 @@ export interface SharedPluginInfo extends ExtensionInfo {
   readonly pulledFrom?: string
   /** Who released it: the account of a `github:` source or of a release address on github.com. */
   readonly author?: string
+  /** The version its `package.json` names (`version` is the installed content's short digest); absent without one. */
+  readonly release?: string
 }
 
 /** What removing a plugin did with its folder in `plugins/`. */
@@ -130,6 +149,20 @@ declare module '@deepseek-ai/cordis' {
 const authorOf = (source: string): string | undefined =>
   (/^github:([^/]+)\//u.exec(source) ?? /^https:\/\/github\.com\/([^/]+)\//u.exec(source))?.[1]
 
+/** The version a plugin folder's `package.json` names, when it names a plain one. */
+function releaseOf(folder: string): string | undefined {
+  try {
+    const version = (
+      JSON.parse(readFileSync(join(folder, 'package.json'), 'utf8')) as { version?: unknown }
+    ).version
+    return typeof version === 'string' && /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.+-]+)?$/u.test(version)
+      ? version
+      : undefined
+  } catch {
+    return undefined
+  }
+}
+
 /** The license a new public plugin is offered under; the plan shows it before the person says yes. */
 const DEFAULT_LICENSE = 'MIT'
 const LICENSE_ID = /^[A-Za-z0-9][A-Za-z0-9.+-]*$/u
@@ -176,6 +209,7 @@ export class PluginShare extends Service {
   readonly restored: Promise<readonly RestoreOutcome[]>
   private readonly dir: string
   private readonly releases: ReleasePort
+  private readonly download: (url: string) => Promise<Uint8Array>
   private readonly ports: PublishPorts
   /** One at a time: two pulls of one name must not race for its folder, nor two publishes for its package. */
   private queue: Promise<unknown> = Promise.resolve()
@@ -193,6 +227,7 @@ export class PluginShare extends Service {
     this.own = ctx
     this.dir = resolve(config.dir ?? join(ctx.appInstance.root, 'plugins'))
     this.releases = config.releases ?? githubReleasesOverHttps()
+    this.download = config.download ?? httpsDownload()
     this.ports = config.publish ?? { host: githubCli(), git: gitCli() }
     // Removing a plugin removes its record. Listened to here, not asked of each caller: every way of removing it goes through extensions.
     ctx.on('extensions/changed', (name, change) => {
@@ -209,6 +244,67 @@ export class PluginShare extends Service {
     return this.inTurn(() => this.pullNow(source))
   }
 
+  /**
+   * Pull every source of a list, a file in the app or an https address (a gist, a file in the group's repository): one after the other and each on
+   * its own, so a source that is refused, or clashes with a plugin already here, is reported with its reason while the others install and keep running.
+   * A list that cannot be read, or has a line that is not one source, pulls nothing.
+   */
+  async pullList(from: string): Promise<PullListResult> {
+    const text = await this.readList(from)
+    if (typeof text !== 'string') return text
+    const { sources, problems } = parsePullList(text)
+    if (problems.length > 0)
+      return refuse('list', `${from}: ${problems.join('; ')}`, 'fix the list; nothing was pulled')
+    if (sources.length === 0)
+      return refuse(
+        'list',
+        `${from} names no plugin`,
+        'write one source per line, e.g. github:someone/pomodoro@0.1.0',
+      )
+    const entries: PullListEntry[] = []
+    for (const { line, source } of sources)
+      entries.push({ line, source, result: await this.pull(source) })
+    return { ok: true, from, entries }
+  }
+
+  /** The text of a list, or why it cannot be read. */
+  private async readList(from: string): Promise<string | PullRefused> {
+    const where = pullListLocation(from)
+    if (where === undefined)
+      return refuse(
+        'list',
+        `"${from}" is not a list`,
+        'name a file in the app (e.g. group.txt) or an https address of one',
+      )
+    try {
+      let bytes: Uint8Array
+      if (where.kind === 'address') bytes = await this.download(where.url)
+      else {
+        const path = resolve(this.own.appInstance.root, where.path)
+        if (!existsSync(path) || !statSync(path).isFile())
+          return refuse(
+            'list',
+            `there is no file ${where.path}`,
+            'name a file in the app, or an https address',
+          )
+        bytes = readFileSync(path)
+      }
+      if (bytes.length > LIST_MAX_BYTES)
+        return refuse(
+          'list',
+          `${from} is larger than ${String(LIST_MAX_BYTES)} bytes, so it is not a list of plugins`,
+          'name the list itself',
+        )
+      return new TextDecoder('utf-8', { fatal: true }).decode(bytes)
+    } catch (cause) {
+      return refuse(
+        'list',
+        `${from} could not be read: ${reasonOf(cause)}`,
+        'check the address; nothing was pulled',
+      )
+    }
+  }
+
   /**
    * The content digest of a pulled plugin as it was installed: set before its folder appears, so whoever sees the folder change can tell the release as
    * pulled from an edit (the frame then does not load the app again for it). A pull from a local file has no record in `blend.yaml`; this knows it too.
@@ -224,10 +320,12 @@ export class PluginShare extends Service {
     return this.own.extensions.list().map((info) => {
       const record = records[info.name]
       const author = record === undefined ? undefined : authorOf(record.source)
+      const release = releaseOf(join(this.dir, info.name))
       return {
         ...info,
         ...(record === undefined ? {} : { pulledFrom: record.source }),
         ...(author === undefined ? {} : { author }),
+        ...(release === undefined ? {} : { release }),
       }
     })
   }
@@ -457,7 +555,7 @@ export class PluginShare extends Service {
           {
             store: new PluginStore(scratch),
             releases: this.releases,
-            download: httpsDownload(),
+            download: this.download,
           },
           expectIntegrity === undefined ? {} : { expectIntegrity },
         )

package/plugins/plugin-share/publish.ts

@@ -58,8 +58,22 @@ export interface PublishPorts {
 export const pullLineOf = (owner: string, repo: string, version: string, digest: string): string =>
   `npm run acryl -- plugin pull github:${owner}/${repo}@${version}@sha256:${digest}`
 
-/** The same plan: what the person confirmed is what would be published now. `released` only explains the version, and is gone once the next one is packaged. */
+/**
+ * The same plan: what the person confirmed is what would be published now. `released` only explains the version, and is gone once the next one is packaged.
+ * Field by field, so a plan that came back through JSON from another surface (the frame's confirm) is the same plan whatever order its fields arrived in.
+ */
 export function samePlan(a: PublishPlan, b: PublishPlan): boolean {
-  const compared = ({ released: _released, ...rest }: PublishPlan) => JSON.stringify(rest)
-  return compared(a) === compared(b)
+  return (
+    a.owner === b.owner &&
+    a.repo === b.repo &&
+    a.version === b.version &&
+    a.visibility === b.visibility &&
+    a.license === b.license &&
+    a.createsRepository === b.createsRepository &&
+    a.integrity === b.integrity &&
+    a.digest === b.digest &&
+    a.pullLine === b.pullLine &&
+    a.files.length === b.files.length &&
+    a.files.every((file, index) => file === b.files[index])
+  )
 }

package/plugins/plugin-share/pull-check.ts

@@ -17,6 +17,8 @@ export type Refusal =
   | 'missing-service'
   | 'folder-exists'
   | 'install'
+  /** A list of sources that cannot be read, or holds a line that is not one source. */
+  | 'list'
 
 export interface PullRefused {
   readonly ok: false

package/plugins/plugin-share/pull-list.ts

@@ -0,0 +1,71 @@
+/**
+ * A group's list of plugins: one source per line, as each person sends it (`github:<owner>/<repo>@<version>@sha256:<digest>`, or the whole line
+ * `plugin publish` prints). The list is text a person or a group keeps (a file in the app, a gist, a file in a repository), so reading it is
+ * forgiving about comments, blank lines and the pasted command, and strict about anything else: a line that is not one source is named, not guessed.
+ */
+
+/** A list is a few lines of text: anything larger is not a list of plugins. */
+export const LIST_MAX_BYTES = 64 * 1024
+
+/** More sources than a group has people is a mistake, not a workshop. */
+export const LIST_MAX_SOURCES = 100
+
+/** The command a person pastes from `plugin publish`: only its source is kept. */
+const PULL_COMMAND = /^(?:npm run acryl --\s+)?plugin pull\s+/u
+
+/** A `#` at the start of a line or after a space begins a comment; a source never holds one there. */
+const COMMENT = /(?:^|\s)#.*$/u
+
+export interface PullListLine {
+  /** Its line in the list, from 1, so a problem is easy to find. */
+  readonly line: number
+  readonly source: string
+}
+
+export interface ParsedPullList {
+  /** The sources in their order, each once. */
+  readonly sources: readonly PullListLine[]
+  /** Lines that are not one source, each with what is wrong. */
+  readonly problems: readonly string[]
+}
+
+/** The sources of a list, in order and without repeats, and the lines that are not a source. */
+export function parsePullList(text: string): ParsedPullList {
+  const sources: PullListLine[] = []
+  const problems: string[] = []
+  const seen = new Set<string>()
+  text.split(/\r?\n/u).forEach((raw, index) => {
+    const line = index + 1
+    const value = raw.replace(COMMENT, '').trim().replace(PULL_COMMAND, '').trim()
+    if (value === '') return
+    if (/\s/u.test(value)) {
+      problems.push(
+        `line ${String(line)} holds more than one word ("${value}"); write one source per line`,
+      )
+      return
+    }
+    if (seen.has(value)) return
+    seen.add(value)
+    sources.push({ line, source: value })
+  })
+  if (sources.length > LIST_MAX_SOURCES)
+    problems.push(
+      `the list has ${String(sources.length)} sources; a list holds at most ${String(LIST_MAX_SOURCES)}`,
+    )
+  return { sources, problems }
+}
+
+/** Where a list is read from: an https address, or a file (relative to the app folder). */
+export type PullListLocation =
+  | { readonly kind: 'address'; readonly url: string }
+  | { readonly kind: 'file'; readonly path: string }
+
+/** @returns undefined for something that is neither (an http: address, a github: source): the caller names what a list may be. */
+export function pullListLocation(from: string): PullListLocation | undefined {
+  const value = from.trim()
+  if (value === '') return undefined
+  if (/^https:\/\//iu.test(value)) return { kind: 'address', url: value }
+  // A drive letter (C:\...) is a path; any other scheme is not a place a list is read from.
+  if (/^[a-z][a-z0-9+.-]+:/iu.test(value) && !/^[a-z]:[\\/]/iu.test(value)) return undefined
+  return { kind: 'file', path: value }
+}

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/shared/skills/acryl-remove-plugin/SKILL.md

@@ -8,5 +8,5 @@ description: Use when the person asks to remove, delete, switch off, hide or und
 
 Find the exact plugin in `plugins/` and its row in `blend.yaml` (never guess the name). To hide it for now, switch it off: `disabled: true` on
 its row (the switch in Settings > Plugins does the same); everything stays and it comes back when switched on. To remove it, and only when the
-person clearly asked: delete its row, its folder and its test; its data in `.acrylblends/` stays unless they ask. Check with `npm test` and
+person clearly asked: delete its row, its folder and its test; its data in `~/.acryl/apps/<id>/data/` stays unless they ask. Check with `npm test` and
 `.acryl/bin/acryl look` that it is gone before you say so. Only touch the plugin the person named.

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/README.md

@@ -5,7 +5,7 @@ Cordis plugin.
 
 ```sh
 npm install
-npm run dev        # prints its URL; data lives in .acrylblends/; it restarts when a file changes (a new port if ACRYLBLENDS_PORT=0)
+npm run dev        # prints its URL; data lives in ~/.acryl/apps/<id>/data/; it restarts when a file changes (a new port if ACRYLBLENDS_PORT=0)
 npm test
 npm run check      # type-check
 

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/gitignore

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

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,