acrylblends 1.3.0 → 1.3.2

package/legacy/todo/164274ffcf7f/src/app.ts

@@ -0,0 +1,145 @@
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { Context, type Fiber } from '@deepseek-ai/cordis'
+import * as door from '../plugins/acryl-door/src/index.ts'
+import * as nodeServer from '../plugins/acryl-node-server/src/index.ts'
+import * as router from '../plugins/acryl-router/src/index.ts'
+import * as state from '../plugins/acryl-state/src/index.ts'
+import { type AppInstance, instance } from '../plugins/instance/index.ts'
+import {
+  appPluginNames,
+  blueprintsIn,
+  compose,
+  loadAppPlugins,
+  loadManifest,
+  type ParameterValue,
+} from '../plugins/manifest/index.ts'
+import { doorEnabled } from './door.ts'
+import * as todo from './todo.ts'
+import { FRAME_MOUNT_PREFIX } from './todo.ts'
+
+/** The plugins this app's code provides. `blend.yaml` chooses, orders and configures them, and adds the app's own plugins from `plugins/` by name. */
+export const registry = {
+  'acryl-router': router,
+  'acryl-state': state,
+  todo,
+  'acryl-node-server': nodeServer,
+  'acryl-door': door,
+}
+
+export const APP_NAME = '__APP_NAME__'
+
+/** The manifest next to this app's source. */
+export const MANIFEST = join(fileURLToPath(new URL('..', import.meta.url)), 'blend.yaml')
+/** The app's plugins: the library copies `registry` imports, and the app's own plugins (a feature each), which `blend.yaml` mounts by their folder name. */
+const PLUGINS_DIR = join(fileURLToPath(new URL('..', import.meta.url)), 'plugins')
+
+/**
+ * The app's manifest, resolved. A Blend finds its Blueprint in `blueprints/<id>.yaml`; an app that is itself a Blueprint never looks.
+ * `createApp` and the tests read it the same way.
+ */
+export function readManifest(values?: Readonly<Record<string, ParameterValue>>) {
+  return loadManifest(MANIFEST, {
+    known: [...Object.keys(registry), ...appPluginNames(PLUGINS_DIR)],
+    getBlueprint: blueprintsIn(join(fileURLToPath(new URL('..', import.meta.url)), 'blueprints')),
+    ...(values ? { values } : {}),
+  })
+}
+
+/** The manifest without some rows: without its server (and so its door) the app is reached in process, through `root.router.request`; the door is also left out in production. */
+function without<M extends { plugins: readonly { use: string }[] }>(
+  manifest: M,
+  ...uses: string[]
+): M {
+  return {
+    ...manifest,
+    plugins: manifest.plugins.map((row) =>
+      uses.includes(row.use) ? { ...row, disabled: true } : row,
+    ),
+  }
+}
+
+export interface App {
+  readonly root: Context
+  /** The address the server listens on; empty when the app was made with `listen: false`. */
+  readonly url: string
+  stop(): Promise<void>
+}
+
+export interface AppOptions {
+  readonly values?: Readonly<Record<string, ParameterValue>>
+  /** The path the app is mounted at; absent on its own server, where it keeps `/todo`, and {@link FRAME_MOUNT_PREFIX} in the frame. */
+  readonly prefix?: string
+  /** Start the HTTP server (default). Tests pass `false` and call `app.root.router.request(path)`: it needs no port, so it also runs where a sandbox forbids listening. */
+  readonly listen?: boolean
+}
+
+/** The rows the frame host provides: the app contributes only the plugins that are its own. */
+const HOST_ROWS = [
+  'instance',
+  'acryl-router',
+  'acryl-node-server',
+  'acryl-web-server',
+  'acryl-page',
+  'manifest',
+  'save',
+  'acryl-door',
+]
+
+/**
+ * The app's rows, composed into `ctx`: the app's own server calls this from `createApp`, and the generated frame layer mounts it as one row, so the frame
+ * runs the app exactly as the app's own server does (same rows, same order, same config). `host: true` leaves the infrastructure rows to the frame host,
+ * which is where the door lives too, and mounts the app at {@link FRAME_MOUNT_PREFIX}.
+ */
+export async function composeInto(
+  ctx: Context,
+  chosen: AppInstance,
+  options: AppOptions & { readonly host?: boolean } = {},
+): Promise<Fiber[]> {
+  const read = readManifest(options.values)
+  const own = options.host !== true && options.listen !== false
+  // The frame host mounts the app under its own prefix; the app's own server keeps the app's old path.
+  const prefix = options.prefix ?? (options.host === true ? FRAME_MOUNT_PREFIX : undefined)
+  const leaveOut = new Set<string>(options.host === true ? HOST_ROWS : [])
+  // The server, and the door that needs it, are not mounted when the app is reached in process or inside the frame host.
+  if (!own) leaveOut.add('acryl-node-server').add('acryl-door')
+  if (!doorEnabled()) leaveOut.add('acryl-door')
+  const manifest = without(read, ...leaveOut)
+  // The rows that name one of the app's own plugin folders (a feature: plugins/<name>/ and its row) rather than a registry import; each one that runs is imported here.
+  const ownRows = [
+    ...new Set(read.plugins.map((row) => row.use).filter((use) => !Object.hasOwn(registry, use))),
+  ]
+  const ownPlugins = await loadAppPlugins(
+    PLUGINS_DIR,
+    ownRows.filter((use) => manifest.plugins.some((row) => row.use === use && !row.disabled)),
+  )
+  return compose(
+    ctx,
+    manifest,
+    { ...registry, ...ownPlugins },
+    {
+      // Runtime values the manifest cannot hold: where the list is kept (in the app's home) and, in the frame, the prefix the app answers at.
+      todo: {
+        file: join(chosen.home, 'todo.json'),
+        ...(prefix === undefined ? {} : { prefix }),
+      },
+      // Only the app's own server listens; the frame host owns the server and its port.
+      ...(own ? { server: { port: chosen.port.start, scan: chosen.port.scan ? 20 : 0 } } : {}),
+    },
+  )
+}
+
+/** The app: `instance` first (where it lives, chosen at run time), then the manifest's rows in order. */
+export async function createApp(chosen: AppInstance, options: AppOptions = {}): Promise<App> {
+  const root = new Context()
+  const first = root.plugin(instance, chosen)
+  await first.await()
+  const fibers: Fiber[] = [first, ...(await composeInto(root, chosen, options))]
+  return {
+    root,
+    url: options.listen === false ? '' : root.nodeServer.url,
+    async stop() {
+      for (const fiber of [...fibers].reverse()) await fiber.dispose()
+    },
+  }
+}

package/legacy/todo/164274ffcf7f/src/todo.ts

@@ -0,0 +1,137 @@
+/**
+ * The reference app of the ACRYL Framework: a todo list in one plugin. It needs `router` and `state`, keeps the list in a cell, serves
+ * JSON CRUD plus a page, and writes the list to a file so it survives a restart. Nothing else.
+ */
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+import type { Context } from '@deepseek-ai/cordis'
+import { Acryl, HTTPException } from '../plugins/acryl-router/src/index.ts'
+import { bodyLimit, loopbackOnly, trimTrailingSlash } from '../plugins/acryl-router/src/middleware/index.ts'
+import { schemaValidator, streamSSE, type StandardSchema } from '../plugins/acryl-router/src/helpers/index.ts'
+import type {} from '../plugins/acryl-state/src/index.ts'
+import { pageHtml } from './page.ts'
+
+/** Stable Cordis plugin name, equal to the package name and the Loader row id. */
+export const name = 'acryl-todo'
+export const inject = ['router', 'state']
+
+/**
+ * The only place the app's mount prefix is named: the app answers under `/todo` on its own server (`npm start`), and the ACRYL frame mounts the same app
+ * at `/app` (`npm run dev`). Every URL the page writes is derived from the prefix it is mounted at, so both are served by one source.
+ */
+export const FRAME_MOUNT_PREFIX = '/app'
+
+export interface Todo { id: number, title: string, done: boolean }
+export interface Config {
+  file?: string
+  /**
+   * The path the app is mounted at, and the base of every URL its page writes. `/todo` on the app's own server (and the default); the ACRYL frame passes
+   * `/app` so the same app answers at the frame's app prefix, with nothing else of its URLs moved.
+   */
+  prefix?: string
+}
+
+/** Standard Schema for the body of a new todo, written by hand so the example has no schema library. */
+const NewTodo: StandardSchema<{ title: string }> = {
+  '~standard': {
+    validate: value => {
+      const title = (value as { title?: unknown } | null)?.title
+      return typeof title === 'string' && title.trim() !== '' && title.length <= 200
+        ? { value: { title: title.trim() } }
+        : { issues: [{ message: 'title must be 1 to 200 characters', path: ['title'] }] }
+    },
+  },
+}
+
+/** Standard Schema for a change to a todo. */
+const TodoChange: StandardSchema<{ done: boolean }> = {
+  '~standard': {
+    validate: value => {
+      const done = (value as { done?: unknown } | null)?.done
+      return typeof done === 'boolean' ? { value: { done } } : { issues: [{ message: 'done must be true or false', path: ['done'] }] }
+    },
+  },
+}
+
+/** A todo body is small; anything bigger is refused before it is read. */
+const MAX_BODY_BYTES = 16 * 1024
+
+/** A missing file is a new list. Any other failure (unreadable, corrupt, half-written) refuses to start: starting empty would overwrite the user's real list on the first save. */
+function load(file: string | undefined): Todo[] {
+  if (file === undefined) return []
+  let text: string
+  try {
+    text = readFileSync(file, 'utf8')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return []
+    throw new Error(`acryl-todo: cannot read ${file}: ${(error as Error).message}`, { cause: error })
+  }
+  try {
+    const parsed: unknown = JSON.parse(text)
+    if (!Array.isArray(parsed)) throw new Error('not a list')
+    return parsed as Todo[]
+  } catch (error) {
+    throw new Error(`acryl-todo: ${file} is not a valid todo list (${(error as Error).message}); fix or remove it, it was left untouched`, { cause: error })
+  }
+}
+
+function save(file: string, todos: readonly Todo[]): void {
+  mkdirSync(dirname(file), { recursive: true })
+  const temporary = `${file}.tmp`
+  writeFileSync(temporary, JSON.stringify(todos))
+  renameSync(temporary, file)
+}
+
+export function apply(ctx: Context, config: Config = {}): void {
+  const prefix = config.prefix ?? '/todo'
+  const todos = ctx.state.cell<readonly Todo[]>('todo.list', load(config.file))
+  if (config.file !== undefined) {
+    const file = config.file
+    ctx.effect(() => todos.subscribe(list => { save(file, list) }), 'acryl-todo: save to file')
+  }
+  const nextId = (): number => todos.get().reduce((max, todo) => Math.max(max, todo.id), 0) + 1
+
+  const find = (id: number): Todo => {
+    const todo = todos.get().find(item => item.id === id)
+    if (todo === undefined) throw new HTTPException(404, { message: 'no such todo' })
+    return todo
+  }
+
+  // `/todo/` is what people type: trimTrailingSlash answers a GET for an unknown path ending in `/` with a 301 to the path without it,
+  // so the page is found either way while each route keeps one canonical path (the router itself treats `/a` and `/a/` as different).
+  const api = new Acryl()
+    .use(loopbackOnly({ inProcess: 'allow' }), bodyLimit({ maxSize: MAX_BODY_BYTES }), trimTrailingSlash())
+    .get('/', c => c.html(pageHtml(prefix)))
+    .get('/api', c => c.json(todos.get()))
+    .post('/api', schemaValidator('json', NewTodo), c => {
+      const todo: Todo = { id: nextId(), title: c.req.valid('json').title, done: false }
+      todos.update(list => [...list, todo])
+      return c.json(todo, 201)
+    })
+    .patch('/api/:id', schemaValidator('json', TodoChange), c => {
+      const { id } = find(Number(c.req.param('id')))
+      const { done } = c.req.valid('json')
+      todos.update(list => list.map(todo => todo.id === id ? { ...todo, done } : todo))
+      return c.json(find(id))
+    })
+    .delete('/api/:id', c => {
+      const { id } = find(Number(c.req.param('id')))
+      todos.update(list => list.filter(todo => todo.id !== id))
+      return c.body(null, 204)
+    })
+    .get('/events', c => streamSSE(c, async stream => {
+      const ended = new Promise<void>(resolve => { stream.onAbort(resolve) })
+      // Writes are asynchronous; chaining them keeps events in the order the list changed.
+      let queue: Promise<unknown> = Promise.resolve()
+      const send = (list: readonly Todo[]): void => { queue = queue.then(() => stream.writeSSE({ data: JSON.stringify(list) })).catch(() => {}) }
+      send(todos.get())
+      const unsubscribe = todos.subscribe(send)
+      try {
+        await ended
+      } finally {
+        unsubscribe()
+      }
+    }))
+  ctx.router.route(prefix === '' ? '/' : prefix, api)
+}

package/lib/cordis/door.d.ts

@@ -96,8 +96,12 @@ interface ExtensionsPort {
   reload(): Promise<unknown>;
   list(): readonly unknown[];
 }
-/** The slice of acrylblends' `pluginShare` service the pull verb uses. */
+/** The slice of acrylblends' `pluginShare` service the pull, list and remove verbs use. */
 interface PluginSharePort {
+  /** The plugins installed while the app runs, a pulled one with its source and author. */
+  list(): readonly unknown[];
+  /** Take a plugin out and forget its record; a pulled folder still holding the release as pulled goes too. */
+  remove(name: string): Promise<unknown>;
   pull(source: string): Promise<{
     readonly ok: boolean;
     readonly action?: string;
@@ -207,6 +211,11 @@ declare class Door {
   private parse;
   /** Run one call on the page and record it. The audit holds which control was touched and how it ended, never what was typed. */
   private callPage;
+  /**
+   * Who lists and removes the app's plugins: plugin-share where the app has it, as it knows where each pulled plugin came from and is the one app service
+   * the frame's host reaches (extensions stays in the app's own realm there); extensions elsewhere.
+   */
+  private installed;
   private plugin;
   private share;
   /** Only a plan: no argument of any verb can publish, so an agent never says yes for a person. */

package/lib/cordis/door.js

@@ -706,14 +706,14 @@ var Door = class {
 					text: `done${result.target === void 0 ? "" : `: ${result.target.role} "${result.target.name}"`}${result.detail === void 0 ? "" : ` (${result.detail})`}; look again before the next act`
 				};
 			}
-			case "plugin-list": return this.plugin((extensions) => extensions.list(), false);
+			case "plugin-list": return this.plugin((plugins) => plugins.list(), false, this.installed());
 			case "plugin-add": return this.plugin((extensions) => extensions.install(this.insideApp(input.folder)));
 			case "plugin-pull": return this.pull(input.source);
 			case "plugin-publish": return this.planPublish(input);
 			case "plugin-remove": {
 				const name = input.name;
 				if (typeof name !== "string" || name === "") throw new DoorError("invalid", "plugin remove needs a plugin name");
-				return this.plugin((extensions) => extensions.remove(name));
+				return this.plugin((plugins) => plugins.remove(name), true, this.installed());
 			}
 			case "plugin-reload": return this.plugin((extensions) => extensions.reload());
 			case "tool-list": {
@@ -942,8 +942,15 @@ var Door = class {
 			throw cause;
 		}
 	}
-	async plugin(run, mutates = true) {
-		const extensions = this.deps.extensions();
+	/**
+	* Who lists and removes the app's plugins: plugin-share where the app has it, as it knows where each pulled plugin came from and is the one app service
+	* the frame's host reaches (extensions stays in the app's own realm there); extensions elsewhere.
+	*/
+	installed() {
+		return this.deps.pluginShare?.() ?? this.deps.extensions();
+	}
+	async plugin(run, mutates = true, port = this.deps.extensions()) {
+		const extensions = port;
 		if (extensions === void 0) throw new DoorError("unavailable", "this door has no extensions plugin to drive. In ACRYL's frame none is needed: a saved change in src/ or plugins/ reloads the app by itself, so do not restart it. Elsewhere, the app has no way to install plugins while it runs");
 		const value = await run(extensions);
 		const unchanged = typeof value === "object" && value !== null && value.action === "unchanged";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acrylblends",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "The Acryl web framework (import { Acryl } from \"acrylblends\") and the acrylblends command that scaffolds Cordis apps.",
   "license": "MIT",
   "type": "module",

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

@@ -35,8 +35,12 @@ export interface ExtensionsPort {
   list(): readonly unknown[]
 }
 
-/** The slice of acrylblends' `pluginShare` service the pull verb uses. */
+/** The slice of acrylblends' `pluginShare` service the pull, list and remove verbs use. */
 export interface PluginSharePort {
+  /** The plugins installed while the app runs, a pulled one with its source and author. */
+  list(): readonly unknown[]
+  /** Take a plugin out and forget its record; a pulled folder still holding the release as pulled goes too. */
+  remove(name: string): Promise<unknown>
   pull(source: string): Promise<{ readonly ok: boolean; readonly action?: string; readonly reason?: string; readonly next?: string }>
   planPublish(name: string, options?: PublishOptionsView): Promise<PublishPlanView | { readonly ok: false; readonly reason: string; readonly next: string }>
   publish(name: string, confirmed: PublishPlanView, options?: PublishOptionsView): Promise<{ readonly ok: boolean; readonly reason?: string }>
@@ -153,14 +157,14 @@ export class Door {
         const result = await this.act(input, signal, scope)
         return { value: result, text: `done${result.target === undefined ? '' : `: ${result.target.role} "${result.target.name}"`}${result.detail === undefined ? '' : ` (${result.detail})`}; look again before the next act` }
       }
-      case 'plugin-list': return this.plugin(extensions => extensions.list(), false)
+      case 'plugin-list': return this.plugin(plugins => plugins.list(), false, this.installed())
       case 'plugin-add': return this.plugin(extensions => extensions.install(this.insideApp(input.folder)))
       case 'plugin-pull': return this.pull(input.source)
       case 'plugin-publish': return this.planPublish(input)
       case 'plugin-remove': {
         const name = input.name
         if (typeof name !== 'string' || name === '') throw new DoorError('invalid', 'plugin remove needs a plugin name')
-        return this.plugin(extensions => extensions.remove(name))
+        return this.plugin(plugins => plugins.remove(name), true, this.installed())
       }
       case 'plugin-reload': return this.plugin(extensions => extensions.reload())
       case 'tool-list': {
@@ -337,8 +341,16 @@ export class Door {
     }
   }
 
-  private async plugin(run: (extensions: ExtensionsPort) => unknown, mutates = true): Promise<VerbAnswer> {
-    const extensions = this.deps.extensions()
+  /**
+   * Who lists and removes the app's plugins: plugin-share where the app has it, as it knows where each pulled plugin came from and is the one app service
+   * the frame's host reaches (extensions stays in the app's own realm there); extensions elsewhere.
+   */
+  private installed(): Pick<ExtensionsPort, 'list' | 'remove'> | undefined {
+    return this.deps.pluginShare?.() ?? this.deps.extensions()
+  }
+
+  private async plugin<Port = ExtensionsPort>(run: (plugins: Port) => unknown, mutates = true, port: Port | undefined = this.deps.extensions() as Port | undefined): Promise<VerbAnswer> {
+    const extensions = port
     if (extensions === undefined) throw new DoorError('unavailable', 'this door has no extensions plugin to drive. In ACRYL\'s frame none is needed: a saved change in src/ or plugins/ reloads the app by itself, so do not restart it. Elsewhere, the app has no way to install plugins while it runs')
     const value = await run(extensions)
     // The app changed under the open pages: reload them (not when the plugin was already as it should be), and answer once they are back.

package/plugins/builder/index.ts

@@ -11,7 +11,7 @@ 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 './package.ts'
+import { packagePlugin } from '../plugin-share/package.ts'
 import { builderRules } from './script.ts'
 
 export interface BuilderConfig {

package/plugins/builder/plugin.json

@@ -1,7 +1,7 @@
 {
   "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": {

package/plugins/extensions/index.ts

@@ -32,6 +32,13 @@ import type {} from '../instance/index.ts'
 import type { Sandbox } from '../sandbox/index.ts'
 import { appendLedger, type LedgerEntry, readLedger } from './ledger.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). */
@@ -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_ {
@@ -245,11 +256,13 @@ export class Extensions extends Service {
    */
   private readonly owner: Context
   private readonly store: PluginStore
+  private readonly routePrefix: string
 
   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 ?? [])
@@ -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])
@@ -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,7 +726,7 @@ 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)
@@ -714,6 +764,7 @@ export class Extensions extends Service {
       dir: staged.dir,
       module,
       fiber: mounted.fiber,
+      routes: added,
     })
     this.stale.delete(name)
     this.saveState()
@@ -758,6 +809,7 @@ 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,
@@ -766,6 +818,7 @@ export class Extensions extends Service {
           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) })
@@ -830,6 +883,7 @@ export class Extensions extends Service {
           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) })

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
+}