acrylblends 1.2.0 → 1.3.1

package/plugins/acryl-door/src/host/operator-routes.ts

@@ -7,7 +7,7 @@
 
 import { Acryl } from 'acryl-router'
 import { UiControlError } from '../page/protocol.ts'
-import { Door, DoorError } from './door.ts'
+import { Door, DoorError, type PublishPlanView } from './door.ts'
 import { error, INVALID_JSON, jsonBody, operatorOnly, readJson, type ReportError } from './http.ts'
 import { VERBS } from './verbs.ts'
 
@@ -35,4 +35,24 @@ export function operatorRoutes(prefix: string, secret: string, door: Door, repor
         return c.json(error('the verb could not be run'), 500)
       }
     })
+    // A person's yes to a plan, from the prompt in their own terminal. Not a verb, so MCP and the chat do not offer it. An agent with this machine's
+    // secret could still reach it: the door keeps honest agents from publishing by accident, the person's account is the real boundary.
+    .post(`${prefix}/publish-confirmed`, operatorOnly(secret), jsonBody, async (c) => {
+      const body = await readJson(c)
+      const { name, confirm, owner, license } = (body === INVALID_JSON || typeof body !== 'object' || body === null ? {} : body) as { name?: unknown; confirm?: unknown; owner?: unknown; license?: unknown }
+      if (typeof name !== 'string' || typeof confirm !== 'object' || confirm === null) {
+        return c.json({ ok: false, code: 'invalid', message: 'the body is { name, confirm }' } satisfies CallResponse, 400)
+      }
+      try {
+        const value = await door.publishConfirmed(name, confirm as PublishPlanView, {
+          ...(typeof owner === 'string' ? { owner } : {}),
+          ...(typeof license === 'string' ? { license } : {}),
+        })
+        return c.json({ ok: true, value, text: JSON.stringify(value, null, 2) } satisfies CallResponse)
+      } catch (cause) {
+        if (cause instanceof DoorError) return c.json({ ok: false, code: cause.code, message: cause.message } satisfies CallResponse, 409)
+        reportError('publish a plugin', cause)
+        return c.json(error('the plugin could not be published'), 500)
+      }
+    })
 }

package/plugins/acryl-door/src/host/verbs.ts

@@ -9,7 +9,7 @@ import { MAX_SNAPSHOT_NODES, MAX_WAIT_MS } from '../page/protocol.ts'
 /** The verbs that only use the page: what a page-only door (a production assistant) offers. */
 export const PAGE_VERBS = ['look', 'act'] as const satisfies readonly Verb[]
 
-export const VERBS = ['brief', 'look', 'act', 'plugin-list', 'plugin-add', 'plugin-remove', 'plugin-reload', 'tool-list', 'tool-call', 'window-list', 'window-open', 'window-focus', 'window-close', 'window-resize', 'menu-list', 'menu-click'] as const
+export const VERBS = ['brief', 'look', 'act', 'plugin-list', 'plugin-add', 'plugin-pull', 'plugin-publish', 'plugin-remove', 'plugin-reload', 'tool-list', 'tool-call', 'window-list', 'window-open', 'window-focus', 'window-close', 'window-resize', 'menu-list', 'menu-click'] as const
 export type Verb = (typeof VERBS)[number]
 
 /** The JSON Schema of a verb's arguments, as MCP lists it. */
@@ -86,6 +86,16 @@ export const VERB_SPECS: Readonly<Record<Verb, VerbSpec>> = {
     description: 'Check, install and start a plugin folder inside the app, without a restart.',
     arguments: { type: 'object', properties: { folder: { type: 'string', description: 'a folder inside the app, e.g. plugins/pomodoro' } }, required: ['folder'], additionalProperties: false },
   },
+  'plugin-pull': {
+    usage: 'plugin pull <source>: fetch a plugin someone released (github:<owner>/<repo>[@<version>][@sha256:<digest>], or a .tgz), check it and start it, live',
+    description: 'Fetch a plugin someone released, without running anything; check its digest, that it works on every OS and that this app has the services it needs; then install and start it without a restart. A refusal says why and changes nothing.',
+    arguments: { type: 'object', properties: { source: { type: 'string', description: 'github:<owner>/<repo>[@<version>][@sha256:<digest>], or a .tgz path or https address' } }, required: ['source'], additionalProperties: false },
+  },
+  'plugin-publish': {
+    usage: 'plugin publish <name> [--owner <account>] [--license <id>]: show what publishing this plugin would send; in a person\'s own terminal, ask them',
+    description: 'Show what publishing a plugin would send: the account, repository, version, license, files and the line a friend pulls it with. Sends nothing. Only a person can say yes, in their own terminal or with Share in the frame; tell them the plan and how.',
+    arguments: { type: 'object', properties: { name: { type: 'string', description: 'a plugin of plugins/' }, owner: { type: 'string', description: 'the GitHub account or organization; the signed-in one when absent' }, license: { type: 'string', description: 'an SPDX license id; MIT when absent' } }, required: ['name'], additionalProperties: false },
+  },
   'plugin-remove': {
     usage: 'plugin remove <name>: stop and remove an installed plugin',
     description: 'Stop and remove an installed plugin.',

package/plugins/acryl-door/src/index.ts

@@ -19,7 +19,7 @@ import { auditPath, AuditLog } from './host/audit.ts'
 import { UiChannel } from './host/channel.ts'
 import { registerChatTools } from './host/chat-tools.ts'
 import { PAGE_VERBS, VERBS } from './host/verbs.ts'
-import { Door, type ExtensionsPort, type ToolsPort } from './host/door.ts'
+import { Door, type ExtensionsPort, type PluginSharePort, type ToolsPort } from './host/door.ts'
 import { assertDoorIsFree, newSecret, removeDoorFile, stateDir, writeDoorFile } from './host/door-file.ts'
 import { DOOR_PREFIX, privateApi } from './host/http.ts'
 import { mcpRoutes } from './host/mcp-routes.ts'
@@ -182,6 +182,7 @@ export function apply(ctx: Context, rawConfig: Config = {}): void {
     app: { name: app.name, root: app.root, get url() { return address.url } },
     ...(appBase === '' ? {} : { appBase }),
     extensions: () => ctx.get('extensions') as unknown as ExtensionsPort | undefined,
+    pluginShare: () => ctx.get('pluginShare') as unknown as PluginSharePort | undefined,
     tools: () => ctx.get('tools') as unknown as ToolsPort | undefined,
     expose: config.tools?.expose ?? [],
     reloadOnChange: config.reloadOnChange !== false,

package/plugins/builder/index.ts

@@ -5,12 +5,13 @@
  * extensions folder, installs it, and gets back the real result (`active`, `pending` with what it waits for, or the error, with the
  * previous version restored). Writes are confined to that folder. The tools register in `ctx.effect`, so they leave with the builder.
  */
-import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { dirname, extname, isAbsolute, join, normalize, relative, resolve, sep } from 'node:path'
 import type { Context } from '@deepseek-ai/cordis'
 import { scripted, type Tools } from '../agent/index.ts'
 import { NAME } from '../extensions/index.ts'
 import type {} from '../instance/index.ts'
+import { packagePlugin } from '../plugin-share/package.ts'
 import { builderRules } from './script.ts'
 
 export interface BuilderConfig {
@@ -20,22 +21,6 @@ export interface BuilderConfig {
   packagesDir?: string
 }
 
-/** The package.json of a standalone plugin package: the host framework is a peer, never a second installed copy. */
-export function packageManifest(name: string, description: string): Record<string, unknown> {
-  return {
-    name,
-    version: '0.1.0',
-    description,
-    type: 'module',
-    exports: { '.': './index.ts', './package.json': './package.json' },
-    files: ['*.ts', '**/*.ts', 'README.md'],
-    // ACRYL measured it: a host package listed under dependencies brings a second copy of the framework, and its services stop
-    // matching after a restart. A peer names the version and installs nothing.
-    peerDependencies: { '@deepseek-ai/cordis': '4.0.4' },
-    keywords: ['cordis', 'cordis-plugin', 'acrylblends'],
-  }
-}
-
 const EXTENSIONS = new Set(['.ts', '.js', '.mjs', '.json', '.md'])
 const MAX_BYTES = 256 * 1024
 
@@ -154,8 +139,8 @@ export const builder = {
     )
     register(
       'package_plugin',
-      'Turn an extension into a standalone plugin package other apps can use: input { name, description? }. Returns its folder.',
-      (input) => {
+      'Turn an extension into a standalone plugin package other apps can pull: input { name, description? }. Writes the package folder and its release .tgz, the same bytes on every OS. Returns the folder, the file, its sha512 and its content digest.',
+      async (input) => {
         const name = pluginName(input)
         if (
           !existsSync(join(folder(name), 'index.ts')) &&
@@ -166,24 +151,17 @@ export const builder = {
         const description = String(
           (input as { description?: unknown }).description ?? `The ${name} Cordis plugin.`,
         )
-        const target = join(packagesDir, name)
-        rmSync(target, { recursive: true, force: true })
-        mkdirSync(packagesDir, { recursive: true })
-        cpSync(folder(name), target, {
-          recursive: true,
-          filter: (path) => !path.includes('node_modules'),
-        })
-        writeFileSync(
-          join(target, 'package.json'),
-          `${JSON.stringify(packageManifest(name, description), null, 2)}\n`,
-        )
-        if (!existsSync(join(target, 'README.md'))) {
-          writeFileSync(
-            join(target, 'README.md'),
-            `# ${name}\n\n${description}\n\nA Cordis plugin. In an ACRYLBLENDS app: \`acrylblends add <this folder>\`.\n`,
+        try {
+          return {
+            ok: true,
+            name,
+            ...(await packagePlugin(folder(name), packagesDir, name, description)),
+          }
+        } catch (cause) {
+          throw new BuilderError(
+            `${name}: ${cause instanceof Error ? cause.message : String(cause)}`,
           )
         }
-        return { ok: true, name, dir: target }
       },
     )
 

package/plugins/builder/plugin.json

@@ -1,11 +1,13 @@
 {
   "name": "builder",
   "description": "The agent's tools for building the app it runs in: write, install, read, list and remove extensions, with real results.",
-  "requires": ["agent", "extensions", "sandbox"],
+  "requires": ["agent", "extensions", "sandbox", "plugin-share"],
   "inject": ["extensions", "tools", "appInstance"],
   "provides": [],
   "dependencies": {
-    "@deepseek-ai/cordis": "4.0.4"
+    "@deepseek-ai/cordis": "4.0.4",
+    "@webboxes/blends-core": "0.5.0",
+    "@webboxes/plugin-hub": "0.2.0"
   },
   "mount": "mount it after agent and extensions: root.plugin(builder, { dir: join(root, 'plugins') }); dir must be an extensions source"
 }

package/plugins/extensions/index.ts

@@ -31,8 +31,15 @@ import { type Context, type Fiber, Service } from '@deepseek-ai/cordis'
 import type {} from '../instance/index.ts'
 import type { Sandbox } from '../sandbox/index.ts'
 import { appendLedger, type LedgerEntry, readLedger } from './ledger.ts'
-import { resolveFromApp, routerAliases } from './resolve.ts'
-import { discard, hashFolder, prune, stage } from './stage.ts'
+import { type PluginStore, pluginVersion } from './plugin-store.ts'
+import {
+  addedRoutes,
+  type FiberRoutesView,
+  routeClash,
+  type ServedRoute,
+  servedRoutes,
+} from './routes.ts'
+import { folderPluginStore } from './stage.ts'
 
 /** A fiber's lifecycle state, by name (Cordis's own enum is a `const enum`, which does not exist at run time). */
 export type ExtensionState = 'pending' | 'loading' | 'active' | 'failed' | 'disposed' | 'unloading'
@@ -93,6 +100,8 @@ export interface ExtensionsConfig {
    * are not extensions, so they are neither found nor started here, and installing one is refused with that reason.
    */
   rows?: readonly string[]
+  /** The path the app is mounted under (the frame's canvas, `/app`): a message names a route as the plugin wrote it, without it. */
+  routePrefix?: string
 }
 
 const READ_ONLY =
@@ -121,7 +130,7 @@ export type InstallResult =
   | {
       readonly ok: false
       /** check: before anything changed; import: loading the code; activate: starting it; verify: its own `check` failed. */
-      readonly stage: 'check' | 'import' | 'activate' | 'verify' | 'approval'
+      readonly stage: 'check' | 'import' | 'activate' | 'conflict' | 'verify' | 'approval'
       readonly name?: string
       readonly errors: readonly string[]
       /** Present for an update: whether the version that was running is running again. */
@@ -157,6 +166,8 @@ interface Installed {
   readonly dir: string
   readonly module: PluginModule
   fiber: Fiber
+  /** The routes its mount added, so a later plugin whose route is taken is told whose it is. */
+  readonly routes: readonly ServedRoute[]
 }
 
 interface Record_ {
@@ -224,7 +235,6 @@ interface StateService {
 
 export class Extensions extends Service {
   readonly sources: readonly ExtensionSource[]
-  readonly stageRoot: string
   readonly stateFile: string
   readonly ledgerFile: string
   /** Settles when the startup pass is done. */
@@ -245,10 +255,14 @@ export class Extensions extends Service {
    * service's own fiber, so a plugin mounted from it would read `ctx.router` from the installer's fiber and fail. Extensions mount from this one.
    */
   private readonly owner: Context
+  private readonly store: PluginStore
+  private readonly routePrefix: string
 
-  constructor(ctx: Context, config: ExtensionsConfig = {}) {
+  constructor(ctx: Context, config: ExtensionsConfig, store: PluginStore) {
     super(ctx, 'extensions')
     this.owner = ctx
+    this.store = store
+    this.routePrefix = (config.routePrefix ?? '').replace(/\/+$/u, '')
     this.readOnly = config.readOnly === true
     this.off = new Set(config.off ?? [])
     this.rows = new Set(config.rows ?? [])
@@ -260,14 +274,13 @@ export class Extensions extends Service {
         trust: config.approval === true && source.trust === 'install' ? 'ask' : source.trust,
       }),
     )
-    this.stageRoot = join(home, 'extensions-staged')
     this.stateFile = join(home, 'extensions.json')
     this.ledgerFile = join(home, 'extensions-ledger.jsonl')
     // Effects run their disposers newest first: settle pending operations, then dispose every mounted extension, then drop the hook.
     // Staged copies live in the app's home, outside the app: their bare imports are resolved from the app. A read-only start imports the folders where they are (inside the app).
     if (!this.readOnly)
       ctx.effect(
-        () => resolveFromApp(this.stageRoot, root, routerAliases()),
+        () => this.store.resolveImportsFrom(root),
         'extensions: resolve staged imports from the app',
       )
     ctx.effect(
@@ -317,7 +330,7 @@ export class Extensions extends Service {
           this.stale.add(entry.name)
           continue
         }
-        if (hashFolder(entry.source) !== entry.version)
+        if (pluginVersion(entry.source) !== entry.version)
           results.push(await this.installNow(entry.source))
       }
       for (const found of this.discover()) {
@@ -365,7 +378,7 @@ export class Extensions extends Service {
         }
       }
       this.requests.delete(name)
-      if (!existsSync(request.dir) || hashFolder(request.dir) !== request.version) {
+      if (!existsSync(request.dir) || pluginVersion(request.dir) !== request.version) {
         return {
           ok: false,
           stage: 'approval',
@@ -588,6 +601,41 @@ export class Extensions extends Service {
   }
 
   /** Mount a module as a child fiber and wait until it settles. */
+  /** Every route the app serves now, read from the router's labels on every running fiber. */
+  private served(): ServedRoute[] {
+    const fibers = [...this.ctx.registry.values()].flatMap(
+      (runtime) => [...runtime.fibers] as unknown as FiberRoutesView[],
+    )
+    return servedRoutes(fibers)
+  }
+
+  /**
+   * A route the new plugin added that another plugin already serves: the router would answer with the other one, so the new route would never be
+   * reached. Refused before the plugin's own check, which the other plugin's answer would pass.
+   */
+  private conflict(
+    added: readonly ServedRoute[],
+    before: readonly ServedRoute[],
+  ): { stage: 'conflict'; error: string } | undefined {
+    const clash = routeClash(added, before)
+    if (clash === undefined) return undefined
+    const { route, taken } = clash
+    const owner =
+      [...this.installed.values()].find((entry) =>
+        entry.routes.some((own) => own.method === taken.method && own.path === taken.path),
+      )?.name ?? (taken.owner === '' ? 'the app' : taken.owner)
+    const shown = (path: string): string =>
+      this.routePrefix !== '' && path.startsWith(`${this.routePrefix}/`)
+        ? path.slice(this.routePrefix.length)
+        : path
+    const same =
+      taken.path === route.path ? '' : ` (it serves ${taken.method} ${shown(taken.path)})`
+    return {
+      stage: 'conflict',
+      error: `${route.method} ${shown(route.path)} is already served by ${owner}${same}; rename this plugin's route, or remove ${owner} first`,
+    }
+  }
+
   private async mount(module: PluginModule): Promise<{ fiber: Fiber; error?: unknown }> {
     // An extension is a plugin module whose config, if any, comes from its own defaults.
     const fiber = this.owner.plugin(module as unknown as Parameters<Context['plugin']>[0])
@@ -617,7 +665,7 @@ export class Extensions extends Service {
     const { name, dir, errors } = this.check(source)
     if (errors.length > 0) return { ok: false, stage: 'check', name, errors, next: NOTHING }
     const previous = this.installed.get(name)
-    const version = hashFolder(dir)
+    const version = pluginVersion(dir)
     const running =
       previous && previous.version === version && STATES[previous.fiber.state] !== 'failed'
     // A source that asks: this exact version must have been approved. Anything else waits, and the ledger says so.
@@ -648,12 +696,12 @@ export class Extensions extends Service {
     }
 
     // Import the new version while the old one keeps running: a syntax error or a missing export changes nothing.
-    const staged = stage(dir, this.stageRoot, name)
+    const staged = this.store.put(name, dir)
     let module: PluginModule
     try {
       module = await this.load(staged.dir, name)
     } catch (error) {
-      discard(staged.dir)
+      this.store.discard(staged)
       this.record({ kind: 'refused', name, version: staged.version, error: message(error) })
       return {
         ok: false,
@@ -666,8 +714,10 @@ export class Extensions extends Service {
     }
 
     if (previous) await previous.fiber.dispose()
+    const before = this.served()
     const mounted = await this.mount(module)
     const state = STATES[mounted.fiber.state] ?? 'failed'
+    const added = state === 'active' ? addedRoutes(before, this.served()) : []
     // Commit before "done": a plugin that started still has to pass its own check before the install counts.
     const failure =
       mounted.error !== undefined || state === 'failed'
@@ -676,11 +726,11 @@ export class Extensions extends Service {
             error: message(mounted.error ?? 'the plugin failed to start'),
           }
         : state === 'active'
-          ? await this.verify(module, mounted.fiber.ctx)
+          ? (this.conflict(added, before) ?? (await this.verify(module, mounted.fiber.ctx)))
           : undefined
     if (failure) {
       await mounted.fiber.dispose().catch(() => undefined)
-      discard(staged.dir)
+      this.store.discard(staged)
       const error = failure.error
       this.record({ kind: 'refused', name, version: staged.version, error })
       let restored = false
@@ -714,10 +764,11 @@ export class Extensions extends Service {
       dir: staged.dir,
       module,
       fiber: mounted.fiber,
+      routes: added,
     })
     this.stale.delete(name)
     this.saveState()
-    prune(this.stageRoot, name, [staged.dir])
+    this.store.keepOnly(name, staged)
     this.record({ kind: action, name, version: staged.version })
     this.ctx.emit('extensions/changed', name, action)
     return {
@@ -737,7 +788,7 @@ export class Extensions extends Service {
     this.installed.delete(name)
     this.stale.delete(name)
     this.saveState()
-    prune(this.stageRoot, name, [])
+    this.store.keepOnly(name)
     this.record({ kind: 'removed', name, version: entry.version })
     this.ctx.emit('extensions/changed', name, 'removed')
     return { ok: true, name }
@@ -758,14 +809,16 @@ export class Extensions extends Service {
       }
       try {
         const module = await this.load(folder.dir, folder.name)
+        const before = this.served()
         const mounted = await this.mount(module)
         this.installed.set(folder.name, {
           name: folder.name,
           source: folder.dir,
-          version: hashFolder(folder.dir),
+          version: pluginVersion(folder.dir),
           dir: folder.dir,
           module,
           fiber: mounted.fiber,
+          routes: addedRoutes(before, this.served()),
         })
         if (mounted.error !== undefined)
           summary.failed.push({ name: folder.name, error: message(mounted.error) })
@@ -825,11 +878,12 @@ export class Extensions extends Service {
         // The source is gone: the last installed version still runs, and is reported as stale.
         summary.stale.push(name)
         this.stale.add(name)
-        if (!existsSync(record.dir)) {
+        if (!this.store.holds(record)) {
           summary.failed.push({ name, error: 'neither the source nor the staged copy exists' })
           continue
         }
         const module = await this.load(record.dir, name)
+        const before = this.served()
         const mounted = await this.mount(module)
         if (mounted.error !== undefined)
           summary.failed.push({ name, error: message(mounted.error) })
@@ -840,6 +894,7 @@ export class Extensions extends Service {
           dir: record.dir,
           module,
           fiber: mounted.fiber,
+          routes: addedRoutes(before, this.served()),
         })
       } catch (error) {
         summary.failed.push({ name, error: message(error) })
@@ -869,7 +924,11 @@ export const extensions = {
   name: 'extensions',
   inject: ['appInstance'],
   async apply(ctx: Context, config: ExtensionsConfig) {
-    const service = new Extensions(ctx, config ?? {})
+    const service = new Extensions(
+      ctx,
+      config ?? {},
+      folderPluginStore(join(ctx.appInstance.home, 'extensions-staged')),
+    )
     await service.ready
   },
 }

package/plugins/extensions/plugin-store.ts

@@ -0,0 +1,27 @@
+/**
+ * Where installed versions of a plugin are kept, as the install transaction needs it. The transaction (`index.ts`) owns this port and says nothing about folders,
+ * copies or URLs; `stage.ts` is the adapter that keeps them on disk (Clean Architecture: a boundary owned by the use case; the layout is a detail).
+ */
+import { digestFolder } from '@webboxes/blends-core'
+
+/** One kept version of a plugin. `dir` is what the transaction imports it from. */
+export interface StoredPlugin {
+  readonly dir: string
+  readonly version: string
+}
+
+export interface PluginStore {
+  /** Keep this source as a version of `name` and return it. An unchanged source returns the version already kept. */
+  put(name: string, source: string): StoredPlugin
+  /** Whether this version, recorded earlier, is still here. */
+  holds(plugin: StoredPlugin): boolean
+  /** Drop a version that was refused. */
+  discard(plugin: StoredPlugin): void
+  /** Drop every version of `name` but `plugin`; all of them when none is given. */
+  keepOnly(name: string, plugin?: StoredPlugin): void
+  /** Let kept plugins import what the app at `appRoot` provides, until the returned function is called. */
+  resolveImportsFrom(appRoot: string): () => void
+}
+
+/** A short content digest of a plugin's folder: an unchanged source keeps its version. */
+export const pluginVersion = (dir: string): string => digestFolder(dir, 12)

package/plugins/extensions/plugin.json

@@ -6,7 +6,7 @@
   "provides": ["extensions"],
   "dependencies": {
     "@deepseek-ai/cordis": "4.0.4",
-    "@webboxes/blends-core": "0.4.0"
+    "@webboxes/blends-core": "0.5.0"
   },
   "mount": "mount it after instance: root.plugin(extensions, { sources: [{ dir: join(root, 'plugins'), trust: 'install' }] })"
 }

package/plugins/extensions/routes.ts

@@ -0,0 +1,92 @@
+/**
+ * Which routes a plugin brings, and whether one of them is already served (spec 049 T025). Plugins that do not know each other share one app: the router
+ * serves the first mount of a route and ignores the second without a word, so a plugin whose route is taken would look installed and answer nothing.
+ * The router labels each route it serves (`acryl-router: serves GET /notes`, under the mount's effect), so the routes are read from the running system.
+ * Pure functions over those labels; the service reads them from the registry.
+ */
+
+/** One route as the router serves it. */
+export interface ServedRoute {
+  readonly method: string
+  readonly path: string
+  /** The plugin whose fiber holds the label. */
+  readonly owner: string
+}
+
+/** The slice of a Cordis effect this module reads. */
+export interface EffectView {
+  readonly label: string
+  readonly children: readonly EffectView[]
+}
+
+/** The slice of a Cordis fiber this module reads. */
+export interface FiberRoutesView {
+  readonly runtime: { readonly name?: string | undefined } | null
+  getEffects(): readonly EffectView[]
+}
+
+const SERVES = /^acryl-router: serves ([A-Z]+) (\S+)$/u
+
+/** Every route served by the given fibers, with the plugin that holds each. `ALL` is middleware or `all`, which wraps routes rather than taking them. */
+export function servedRoutes(fibers: Iterable<FiberRoutesView>): ServedRoute[] {
+  const routes: ServedRoute[] = []
+  const walk = (effects: readonly EffectView[], owner: string): void => {
+    for (const effect of effects) {
+      const served = SERVES.exec(effect.label)
+      if (served?.[1] !== undefined && served[2] !== undefined && served[1] !== 'ALL')
+        routes.push({ method: served[1], path: served[2], owner })
+      walk(effect.children, owner)
+    }
+  }
+  for (const fiber of fibers) walk(fiber.getEffects(), fiber.runtime?.name ?? '')
+  return routes
+}
+
+const key = (route: ServedRoute): string => `${route.method} ${route.path}`
+
+/** The routes in `after` that `before` did not have: what one mount added, counted, so a second mount of the same route counts as added. */
+export function addedRoutes(
+  before: readonly ServedRoute[],
+  after: readonly ServedRoute[],
+): ServedRoute[] {
+  const left = new Map<string, number>()
+  for (const route of before) left.set(key(route), (left.get(key(route)) ?? 0) + 1)
+  const added: ServedRoute[] = []
+  for (const route of after) {
+    const count = left.get(key(route)) ?? 0
+    if (count > 0) left.set(key(route), count - 1)
+    else added.push(route)
+  }
+  return added
+}
+
+const segments = (path: string): string[] => path.split('/').filter((part) => part !== '')
+
+/**
+ * Whether one request could match both paths: equal segments, a `:param` matching any one segment, a `*` matching the rest. `/notes` and `/notes/list` are
+ * two routes; `/notes/*` and `/notes/list` are not.
+ */
+export function pathsOverlap(a: string, b: string): boolean {
+  const x = segments(a)
+  const y = segments(b)
+  for (let i = 0; ; i += 1) {
+    const p = x[i]
+    const q = y[i]
+    if (p === '*' || q === '*') return true
+    if (p === undefined || q === undefined) return p === q
+    if (p.startsWith(':') || q.startsWith(':')) continue
+    if (p !== q) return false
+  }
+}
+
+/** The first route `added` shares with one already served: same method and an overlapping path. */
+export function routeClash(
+  added: readonly ServedRoute[],
+  served: readonly ServedRoute[],
+): { readonly route: ServedRoute; readonly taken: ServedRoute } | undefined {
+  for (const route of added)
+    for (const taken of served)
+      if (taken.method === route.method && pathsOverlap(taken.path, route.path))
+        return { route, taken }
+  return undefined
+}

package/plugins/extensions/stage.ts

@@ -7,10 +7,9 @@
  */
 import { cpSync, existsSync, mkdirSync, readdirSync, renameSync, rmSync } from 'node:fs'
 import { basename, join } from 'node:path'
-import { digestFolder, FOLDER_DIGEST_SKIPPED } from '@webboxes/blends-core'
-
-/** A short content digest of a folder, so an unchanged source keeps its version. */
-export const hashFolder = (dir: string, length = 12): string => digestFolder(dir, length)
+import { FOLDER_DIGEST_SKIPPED } from '@webboxes/blends-core'
+import { type PluginStore, pluginVersion } from './plugin-store.ts'
+import { resolveFromApp, routerAliases } from './resolve.ts'
 
 /**
  * Whether `node --watch` runs this process. It watches every module the process has imported, and keeps watching the paths of the runs before; a staged copy that is deleted
@@ -40,7 +39,7 @@ export function stage(
   stageRoot: string,
   name: string,
 ): { dir: string; version: string } {
-  const version = hashFolder(source)
+  const version = pluginVersion(source)
   const existing = staged(stageRoot, name, version)
   if (existing !== undefined) return { dir: existing, version }
   const stamp = String(Date.now()).padStart(15, '0')
@@ -70,3 +69,14 @@ export function prune(stageRoot: string, name: string, keep: readonly string[]):
     if (!keep.includes(path)) rmSync(path, { recursive: true, force: true })
   }
 }
+
+/** The plugin store of an app: its versions as staged copies under `stageRoot`. */
+export function folderPluginStore(stageRoot: string): PluginStore {
+  return {
+    put: (name, source) => stage(source, stageRoot, name),
+    holds: ({ dir }) => existsSync(dir),
+    discard: ({ dir }) => discard(dir),
+    keepOnly: (name, plugin) => prune(stageRoot, name, plugin ? [plugin.dir] : []),
+    resolveImportsFrom: (appRoot) => resolveFromApp(stageRoot, appRoot, routerAliases()),
+  }
+}

package/plugins/home/index.ts

@@ -50,7 +50,9 @@ export function createHome(): Home {
           `a widget id is a plugin name (lowercase letters, digits and dashes), not "${widget.id}"`,
         )
       if (registered.has(widget.id))
-        throw new Error(`the home page already has a widget "${widget.id}"`)
+        throw new Error(
+          `the home page already has a widget "${widget.id}", the plugin ${widget.id}'s; a widget's id is the name of the plugin that puts it there`,
+        )
       registered.set(widget.id, widget)
       return () => {
         if (registered.get(widget.id) === widget) registered.delete(widget.id)

package/plugins/manifest/plugin.json

@@ -7,7 +7,7 @@
   "dependencies": {
     "@deepseek-ai/cordis": "4.0.4",
     "yaml": "2.9.0",
-    "@webboxes/blends-core": "0.4.0"
+    "@webboxes/blends-core": "0.5.0"
   },
   "mount": "in src/app.ts: const manifest = loadManifest(join(chosen.root, 'blend.yaml')); await compose(root, manifest, registry)"
 }