acrylblends 1.3.0 → 1.3.1

package/docs/framework/workshop/README.md

@@ -87,6 +87,8 @@ npm install
 npm run dev
 ```
 
+npm may warn that 5 packages have install scripts not covered by allowScripts; that is a notice, not an error - nothing to do.
+
 `npm install` is bigger than a framework-only app: it brings the frame and the chat engine (about 500 MB together, much less on a warm package
 cache). `npm run dev` starts the app inside the frame and prints one line:
 

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.1",
   "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
+}

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

@@ -14,6 +14,21 @@ The app must be running (`npm run dev`), because the pull installs into it live.
 
 The app remembers where each pulled plugin came from, in the `plugin-share` row of `blend.yaml`. A copy of the app fetches the same bytes at its next start.
 
+A plugin whose route or home widget another plugin already has is refused, and the message names that plugin. A different copy of a plugin with the same name is refused too, and the message says where the copy in the app came from.
+
+## List and remove
+
+```
+npm run acryl -- plugin list
+npm run acryl -- plugin remove <name>
+```
+
+The list names each plugin installed while the app runs, its version and state. A pulled one also shows the source it came from and its author, the GitHub account that released it.
+
+Remove takes the plugin out of the running app and forgets its record. Its folder goes too when it still holds the release exactly as pulled; the pull line brings it back. A folder with someone's work in it stays, and the answer says so: the app's own plugin, or a pulled one changed since. The app then starts it again at its next start unless you delete the folder.
+
+Both work in the frame as well.
+
 ## Publish
 
 ```
@@ -24,7 +39,7 @@ It prints the plan: account, repository, version, visibility and license. Only a
 
 ## An app made by an older version
 
-Every new app has this plugin. `upgrade` does not add it to an older app, so add it and mount it by hand:
+Every new app has this plugin, except one made from the todo template, which installs nothing live. `upgrade` does not add it to an older app, so add it and mount it by hand:
 
 ```
 npx acrylblends add plugin-share