acrylblends 1.3.1 → 1.4.0

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

@@ -102,12 +102,9 @@ interface PluginSharePort {
   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;
-  }>;
+  pull(source: string): Promise<PullView>;
+  /** Pull each source of a group's list on its own: one that is refused does not stop the others. */
+  pullList(from: string): Promise<PullListView>;
   planPublish(name: string, options?: PublishOptionsView): Promise<PublishPlanView | {
     readonly ok: false;
     readonly reason: string;
@@ -118,6 +115,28 @@ interface PluginSharePort {
     readonly reason?: string;
   }>;
 }
+/** What one pull did, or why it was refused. */
+interface PullView {
+  readonly ok: boolean;
+  readonly action?: string;
+  readonly name?: string;
+  readonly reason?: string;
+  readonly next?: string;
+}
+/** What a list pull did for each source, or why the list itself was refused (then nothing was pulled). */
+type PullListView = {
+  readonly ok: true;
+  readonly from: string;
+  readonly entries: readonly {
+    readonly line: number;
+    readonly source: string;
+    readonly result: PullView;
+  }[];
+} | {
+  readonly ok: false;
+  readonly reason: string;
+  readonly next: string;
+};
 /** Who a plan publishes as, and under which license; the service's defaults when absent. */
 interface PublishOptionsView {
   readonly owner?: string;
@@ -223,6 +242,8 @@ declare class Door {
   /** The person's yes, from their own terminal. Not a verb: MCP and the chat do not have it. */
   publishConfirmed(name: string, confirmed: PublishPlanView, options: PublishOptionsView): Promise<unknown>;
   private pull;
+  /** A group's list: every source is pulled on its own, so one refused plugin is named with its reason and the others still install and run. */
+  private pullList;
   /** A folder named by an agent, resolved from the app folder; it must be inside the app. */
   private insideApp;
   private offeredTools;

package/lib/cordis/door.js

@@ -464,15 +464,20 @@ const VERB_SPECS = {
 		}
 	},
 	"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.",
+		usage: "plugin pull <source> | --from <list>: fetch a plugin someone released (github:<owner>/<repo>[@<version>][@sha256:<digest>], or a .tgz), or every plugin of a group's list, check each 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. With from instead of source, pull every source of a group's list (one per line, # comments); each is pulled on its own, so a refused one is named with its reason and the others still come in.",
 		arguments: {
 			type: "object",
-			properties: { source: {
-				type: "string",
-				description: "github:<owner>/<repo>[@<version>][@sha256:<digest>], or a .tgz path or https address"
-			} },
-			required: ["source"],
+			properties: {
+				source: {
+					type: "string",
+					description: "github:<owner>/<repo>[@<version>][@sha256:<digest>], or a .tgz path or https address"
+				},
+				from: {
+					type: "string",
+					description: "instead of source: a list of sources, a file in the app (e.g. group.txt) or an https address"
+				}
+			},
 			additionalProperties: false
 		}
 	},
@@ -708,7 +713,7 @@ var Door = class {
 			}
 			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-pull": return input.from === void 0 ? this.pull(input.source) : this.pullList(input.from, input.source);
 			case "plugin-publish": return this.planPublish(input);
 			case "plugin-remove": {
 				const name = input.name;
@@ -997,13 +1002,29 @@ var Door = class {
 	async pull(source) {
 		if (typeof source !== "string" || source === "") throw new DoorError("invalid", "plugin pull needs a source, e.g. plugin pull github:someone/pomodoro@0.1.0");
 		const value = await this.share().pull(source);
-		if (!value.ok) throw new DoorError("refused", `${value.reason ?? "the pull was refused"}. ${value.next ?? "nothing changed"}.`);
+		if (!value.ok) throw new DoorError("refused", `${sentence(value.reason ?? "the pull was refused")} ${sentence(value.next ?? "nothing changed")}`);
 		if (value.action !== "unchanged" && this.deps.reloadOnChange !== false) await this.deps.channel.reloadAll();
 		return {
 			value,
 			text: JSON.stringify(value, null, 2)
 		};
 	}
+	/** A group's list: every source is pulled on its own, so one refused plugin is named with its reason and the others still install and run. */
+	async pullList(from, source) {
+		if (source !== void 0) throw new DoorError("invalid", "plugin pull takes a source or --from <list>, not both");
+		if (typeof from !== "string" || from === "") throw new DoorError("invalid", "plugin pull --from needs a list, e.g. plugin pull --from group.txt");
+		const value = await this.share().pullList(from);
+		if (!value.ok) throw new DoorError("refused", `${sentence(value.reason)} ${sentence(value.next)}`);
+		if (value.entries.some((entry) => entry.result.ok && entry.result.action !== "unchanged") && this.deps.reloadOnChange !== false) await this.deps.channel.reloadAll();
+		const lines = value.entries.map((entry) => `${entry.source}: ${pullLine(entry.result)}`);
+		const refused = value.entries.filter((entry) => !entry.result.ok);
+		const summary = `${String(value.entries.length - refused.length)} of ${String(value.entries.length)} from ${value.from} pulled`;
+		if (refused.length > 0) throw new DoorError("refused", [`${summary}; ${String(refused.length)} refused, the others are in and running.`, ...lines].join("\n"));
+		return {
+			value,
+			text: [`${summary}.`, ...lines].join("\n")
+		};
+	}
 	/** A folder named by an agent, resolved from the app folder; it must be inside the app. */
 	insideApp(folder) {
 		if (typeof folder !== "string" || folder === "") throw new DoorError("invalid", "plugin add needs a folder, e.g. plugins/pomodoro");
@@ -1040,6 +1061,16 @@ var Door = class {
 		};
 	}
 };
+/** One source's outcome in a list pull, as a person reads it. */
+function pullLine(result) {
+	if (!result.ok) return `refused: ${sentence(result.reason ?? "the pull was refused")} ${sentence(result.next ?? "nothing changed")}`;
+	return `${result.action ?? "pulled"}${result.name === void 0 ? "" : ` ${result.name}`}`;
+}
+/** A text as one sentence: the full stop added only when it has no closing punctuation of its own (a reason may end with one, a next step often does). */
+function sentence(text) {
+	const trimmed = text.trim();
+	return /[.!?]$/u.test(trimmed) ? trimmed : `${trimmed}.`;
+}
 //#endregion
 //#region ../../plugins/acryl-door/src/host/chat-tools.ts
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acrylblends",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "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/cli/acryl.ts

@@ -17,7 +17,7 @@ import { fileURLToPath } from 'node:url'
 import { readDoorFile, STATE_DIR, DOOR_FILE } from '../host/door-file.ts'
 
 const ACT_OPS = new Set(['click', 'type', 'select', 'press', 'scroll', 'wait', 'reload', 'navigate'])
-const VALUED = new Set(['--dir', '--owner', '--license', '--ref', '--text', '--option', '--key', '--direction', '--amount', '--cursor', '--max-nodes', '--role', '--name', '--timeout-ms', '--id', '--width', '--height', '--window', '--tool', '--args', '--path'])
+const VALUED = new Set(['--dir', '--owner', '--license', '--ref', '--text', '--option', '--key', '--direction', '--amount', '--cursor', '--max-nodes', '--role', '--name', '--timeout-ms', '--id', '--width', '--height', '--window', '--tool', '--args', '--path', '--from'])
 const FLAGS = new Set(['--json', '--submit', '--no-clear', '--gone', '--force', '--help'])
 
 export class UsageError extends Error {}
@@ -139,7 +139,12 @@ export function parseInvocation(argv: readonly string[], env: NodeJS.ProcessEnv
     case 'plugin': {
       if (second === 'list' || second === 'reload') return make(`plugin-${second}`)
       if (second === 'add') { if (third === undefined) throw new UsageError('plugin add needs a folder, e.g. plugin add plugins/pomodoro'); return make('plugin-add', { folder: third }) }
-      if (second === 'pull') { if (third === undefined) throw new UsageError('plugin pull needs a source, e.g. plugin pull github:someone/pomodoro@0.1.0'); return make('plugin-pull', { source: third }) }
+      if (second === 'pull') {
+        const from = values.get('--from')
+        if (from !== undefined) { if (third !== undefined) throw new UsageError('plugin pull takes a source or --from <list>, not both'); return make('plugin-pull', { from }) }
+        if (third === undefined) throw new UsageError('plugin pull needs a source, e.g. plugin pull github:someone/pomodoro@0.1.0, or --from <list>')
+        return make('plugin-pull', { source: third })
+      }
       if (second === 'publish') {
         if (third === undefined) throw new UsageError('plugin publish needs a plugin name, e.g. plugin publish pomodoro')
         const owner = values.get('--owner')

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

@@ -41,11 +41,21 @@ export interface PluginSharePort {
   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 }>
+  pull(source: string): Promise<PullView>
+  /** Pull each source of a group's list on its own: one that is refused does not stop the others. */
+  pullList(from: string): Promise<PullListView>
   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 }>
 }
 
+/** What one pull did, or why it was refused. */
+export interface PullView { readonly ok: boolean; readonly action?: string; readonly name?: string; readonly reason?: string; readonly next?: string }
+
+/** What a list pull did for each source, or why the list itself was refused (then nothing was pulled). */
+export type PullListView =
+  | { readonly ok: true; readonly from: string; readonly entries: readonly { readonly line: number; readonly source: string; readonly result: PullView }[] }
+  | { readonly ok: false; readonly reason: string; readonly next: string }
+
 /** Who a plan publishes as, and under which license; the service's defaults when absent. */
 export interface PublishOptionsView {
   readonly owner?: string
@@ -159,7 +169,7 @@ export class Door {
       }
       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-pull': return input.from === undefined ? this.pull(input.source) : this.pullList(input.from, input.source)
       case 'plugin-publish': return this.planPublish(input)
       case 'plugin-remove': {
         const name = input.name
@@ -388,12 +398,28 @@ export class Door {
     if (typeof source !== 'string' || source === '') throw new DoorError('invalid', 'plugin pull needs a source, e.g. plugin pull github:someone/pomodoro@0.1.0')
     const value = await this.share().pull(source)
     // A refusal is a failed command, so a script does not read it as done; it changed nothing, and the open pages stay.
-    if (!value.ok) throw new DoorError('refused', `${value.reason ?? 'the pull was refused'}. ${value.next ?? 'nothing changed'}.`)
+    if (!value.ok) throw new DoorError('refused', `${sentence(value.reason ?? 'the pull was refused')} ${sentence(value.next ?? 'nothing changed')}`)
     // Neither did pulling what is already there change anything.
     if (value.action !== 'unchanged' && this.deps.reloadOnChange !== false) await this.deps.channel.reloadAll()
     return { value, text: JSON.stringify(value, null, 2) }
   }
 
+  /** A group's list: every source is pulled on its own, so one refused plugin is named with its reason and the others still install and run. */
+  private async pullList(from: unknown, source: unknown): Promise<VerbAnswer> {
+    if (source !== undefined) throw new DoorError('invalid', 'plugin pull takes a source or --from <list>, not both')
+    if (typeof from !== 'string' || from === '') throw new DoorError('invalid', 'plugin pull --from needs a list, e.g. plugin pull --from group.txt')
+    const value = await this.share().pullList(from)
+    if (!value.ok) throw new DoorError('refused', `${sentence(value.reason)} ${sentence(value.next)}`)
+    const changed = value.entries.some(entry => entry.result.ok && entry.result.action !== 'unchanged')
+    if (changed && this.deps.reloadOnChange !== false) await this.deps.channel.reloadAll()
+    const lines = value.entries.map(entry => `${entry.source}: ${pullLine(entry.result)}`)
+    const refused = value.entries.filter(entry => !entry.result.ok)
+    const summary = `${String(value.entries.length - refused.length)} of ${String(value.entries.length)} from ${value.from} pulled`
+    // Some refused: the command failed, so a script sees it, but the ones that came in stay in and keep running.
+    if (refused.length > 0) throw new DoorError('refused', [`${summary}; ${String(refused.length)} refused, the others are in and running.`, ...lines].join('\n'))
+    return { value, text: [`${summary}.`, ...lines].join('\n') }
+  }
+
   /** A folder named by an agent, resolved from the app folder; it must be inside the app. */
   private insideApp(folder: unknown): string {
     if (typeof folder !== 'string' || folder === '') throw new DoorError('invalid', 'plugin add needs a folder, e.g. plugins/pomodoro')
@@ -426,3 +452,15 @@ export class Door {
     return { value, text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) }
   }
 }
+
+/** One source's outcome in a list pull, as a person reads it. */
+function pullLine(result: PullView): string {
+  if (!result.ok) return `refused: ${sentence(result.reason ?? 'the pull was refused')} ${sentence(result.next ?? 'nothing changed')}`
+  return `${result.action ?? 'pulled'}${result.name === undefined ? '' : ` ${result.name}`}`
+}
+
+/** A text as one sentence: the full stop added only when it has no closing punctuation of its own (a reason may end with one, a next step often does). */
+function sentence(text: string): string {
+  const trimmed = text.trim()
+  return /[.!?]$/u.test(trimmed) ? trimmed : `${trimmed}.`
+}

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

@@ -87,9 +87,9 @@ export const VERB_SPECS: Readonly<Record<Verb, VerbSpec>> = {
     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 },
+    usage: 'plugin pull <source> | --from <list>: fetch a plugin someone released (github:<owner>/<repo>[@<version>][@sha256:<digest>], or a .tgz), or every plugin of a group\'s list, check each 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. With from instead of source, pull every source of a group\'s list (one per line, # comments); each is pulled on its own, so a refused one is named with its reason and the others still come in.',
+    arguments: { type: 'object', properties: { source: { type: 'string', description: 'github:<owner>/<repo>[@<version>][@sha256:<digest>], or a .tgz path or https address' }, from: { type: 'string', description: 'instead of source: a list of sources, a file in the app (e.g. group.txt) or an https address' } }, 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',

package/plugins/extensions/index.ts

@@ -116,6 +116,8 @@ export interface ExtensionInfo {
   readonly missing: readonly string[]
   /** The source folder no longer exists; the last installed version still runs. */
   readonly stale: boolean
+  /** The routes its mount added, as the plugin wrote them (without the frame's prefix), so a surface can link to its pages. */
+  readonly routes: readonly { readonly method: string; readonly path: string }[]
 }
 
 export type InstallResult =
@@ -353,6 +355,7 @@ export class Extensions extends Service {
           state,
           missing: state === 'pending' ? this.missing(entry.module) : [],
           stale: this.stale.has(entry.name),
+          routes: entry.routes.map(({ method, path }) => ({ method, path: this.written(path) })),
         }
       })
       .sort((a, b) => a.name.localeCompare(b.name))
@@ -609,6 +612,13 @@ export class Extensions extends Service {
     return servedRoutes(fibers)
   }
 
+  /** A served path as the plugin wrote it: without the frame's canvas prefix. */
+  private written(path: string): string {
+    return this.routePrefix !== '' && path.startsWith(`${this.routePrefix}/`)
+      ? path.slice(this.routePrefix.length)
+      : path
+  }
+
   /**
    * 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.
@@ -624,15 +634,11 @@ export class Extensions extends Service {
       [...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)})`
+      taken.path === route.path ? '' : ` (it serves ${taken.method} ${this.written(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`,
+      error: `${route.method} ${this.written(route.path)} is already served by ${owner}${same}; rename this plugin's route, or remove ${owner} first`,
     }
   }