acrylblends 1.2.0 → 1.3.0

package/docs/framework/guides/create-acrylblends.md

@@ -55,7 +55,7 @@ bun create acrylblends@latest my-app --template nodejs
 | `[source]` | A template from outside the package: `github:owner/repo[#ref]`, `@scope/name[@version]` or a packed `.tgz` file. See [Templates from a repository or a package](#templates-from-a-repository-or-a-package). | `github:acme/starter` |
 | `--template <template>` | One of `blank`, `nodejs`, `notes`, `chat`, `todo`, `agent` (the same list as `acrylblends init --template`; `acryl-app` is accepted as `agent`). Skips the template question; a bare name after the directory means the same. | `--template notes` |
 | `--from <id \| source>` | A starter from the registry by its id (`acrylblends.notes-desktop`), or any source above. Only starters that declare `runtime: acrylblends` are made; an ACRYL app starter is refused. See [Starters from the registry](#starters-from-the-registry). | `-- --from acrylblends.notes-desktop` |
-| `--registry <source>` | Read the ids from this registry instead of the public one: `github:owner/repo` or a folder, with an `index.json` (at its root or in `registry/`). | `-- --from login.thing --registry github:acryldev/workshop-2026-11-20` |
+| `--registry <source>` | Read the ids from this registry instead of the public one: `github:owner/repo`, an `https://` address, or a folder, with an `index.json` (at its root or in `registry/`). | `-- --from login.thing --registry github:acryldev/workshop-2026-11-20` |
 | `--install` | Install the dependencies with the package manager after creating the project. For a template from a source, the install scripts it will run are listed first. | `--install` |
 | `--pm <packageManager>` | The package manager for `--install`: `npm`, `pnpm`, `yarn` or `bun`. Defaults to the one that started the initializer. | `--pm pnpm` |
 | `--yes`, `-y` | Ask nothing: use `nodejs` unless `--template` is given, and the directory `acryl-app`. | `-y` |
@@ -78,7 +78,9 @@ npm run dev
 - A starter with `runtime: acrylblends` is an `acrylblends` app: this command downloads its folder, gives the manifest to the new app (`metadata.id: acrylblends.my-notes`, `visibility: private`; the starter's id and licence stay the starter's), checks it for anything that looks like a secret, and writes it. Nothing in it is installed or run: `npm install` is yours to run, and the dependencies of the starter (a desktop starter brings `electron`) are in its `package.json`.
 - A starter for the ACRYL app (`runtime: acryl`, the older `acryl.*` entries) is refused with one line that says so, because its plugins run only inside the ACRYL app. Nothing is written.
 - An unknown id lists the starters this command can make.
-- The ids come from `https://acrylblends.github.io/registry/index.json`. `--registry github:owner/repo` reads another registry with the same layout (`index.json` and `blends/<id>/`), a team's own or a workshop's; `--registry ./folder` reads one on disk.
+- The ids come from `https://acrylblends.github.io/registry/index.json`, and only the starter you asked for is downloaded, as one archive checked against the integrity in the index; an archive that does not match is refused. When the site cannot give the starter, the registry's repository is read instead. `--registry github:owner/repo` reads another registry with the same layout (`index.json` and `blends/<id>/`), a team's own or a workshop's; `--registry ./folder` reads one on disk.
+
+A registry on any static host works with `--registry https://...`, if its `index.json` names an `archive` and an `integrity` for each entry: `workshop-registry/scripts/registry-archives.mjs` in this repository writes both when you deploy, on the copy you publish.
 
 To publish a starter of your own, see [the registry README](https://github.com/acrylblends/acrylblends.github.io/tree/main/registry): the folder of your app under `blends/<id>/` with an `acryl.template.json`, in a pull request.
 

package/docs/framework/workshop/README.md

@@ -8,7 +8,7 @@ app around it: a folder of Cordis plugins with a `blend.yaml`, running on your m
 The frame is the workshop's point. You do not edit a folder and alt-tab to a browser: your app is a page inside the workspace, the agents work in
 the same folder the frame shows, and every change you or an agent makes is one restart away from the page.
 
-This guide is for **acrylblends 1.2.0 or newer**; `npm create acrylblends@latest` gives you that. An app you made with an older release gets the
+This guide is for **acrylblends 1.3.0 or newer**; `npm create acrylblends@latest` gives you that. An app you made with an older release gets the
 frame with the upgrade in block 6.
 
 ## 0. Before you start (10 minutes)
@@ -81,7 +81,7 @@ between watching and building.
 ## 1. Create the app; the frame opens on it (10 minutes)
 
 ```sh
-npm create acrylblends@latest my-app agent
+npm create acrylblends@latest my-app agent -- --desktop
 cd my-app
 npm install
 npm run dev

package/docs/framework/workshop/facilitator.md

@@ -5,7 +5,7 @@ app is created, then **opened inside ACRYL's IDE** (projects on the left, the ap
 chat model works on the app from inside the frame, and coding agents run in terminal tabs in the same folder. The data layer, the desktop window and
 the panel-first flow of the previous handout are gone.
 
-The handout is written for **acrylblends 1.2.0 or newer** (the release that carries the frame). A room on an older release is on the previous handout;
+The handout is written for **acrylblends 1.3.0 or newer** (the release whose `create --desktop` makes the framed app). A room on an older release is on the previous handout;
 check with `npx acrylblends@latest --version` before the day.
 
 ## Before the room: put this on every machine

package/lib/cordis/door.d.ts

@@ -84,7 +84,7 @@ declare class ShellChannel {
 }
 //#endregion
 //#region ../../plugins/acryl-door/src/host/door.d.ts
-type DoorErrorCode = 'invalid' | 'unknown-verb' | 'unavailable' | 'not-exposed' | 'outside-app' | 'failed' | ShellErrorCode;
+type DoorErrorCode = 'invalid' | 'unknown-verb' | 'unavailable' | 'not-exposed' | 'outside-app' | 'failed' | 'refused' | ShellErrorCode;
 declare class DoorError extends Error {
   readonly code: DoorErrorCode;
   constructor(code: DoorErrorCode, message: string);
@@ -96,6 +96,41 @@ interface ExtensionsPort {
   reload(): Promise<unknown>;
   list(): readonly unknown[];
 }
+/** The slice of acrylblends' `pluginShare` service the pull verb uses. */
+interface PluginSharePort {
+  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;
+  }>;
+}
+/** Who a plan publishes as, and under which license; the service's defaults when absent. */
+interface PublishOptionsView {
+  readonly owner?: string;
+  readonly license?: string;
+}
+/** A plan as the door shows it. The service owns it; the door passes it back unchanged. */
+interface PublishPlanView {
+  readonly owner: string;
+  readonly repo: string;
+  readonly version: string;
+  readonly visibility: string;
+  readonly license: string;
+  readonly createsRepository: boolean;
+  readonly files: readonly string[];
+  readonly digest: string;
+  readonly pullLine: string;
+}
 /** The slice of acrylblends' `tools` registry (the `agent` plugin's) the tool verbs use, and where the built-in chat finds the verbs. */
 interface ToolsPort {
   /** @returns the function that removes the tool. @throws when the name is taken. */
@@ -128,6 +163,8 @@ interface DoorDeps {
   readonly appBase?: string | undefined;
   /** Read at each call: the services may come and go while the door runs. */
   readonly extensions: () => ExtensionsPort | undefined;
+  /** Read at each call, as `extensions` is; absent where the app has no plugin-share row. */
+  readonly pluginShare?: () => PluginSharePort | undefined;
   readonly tools: () => ToolsPort | undefined;
   /** The app tools the door offers; anything else is refused before it reaches the registry. */
   readonly expose: readonly string[];
@@ -171,6 +208,12 @@ declare class Door {
   /** 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;
   private plugin;
+  private share;
+  /** Only a plan: no argument of any verb can publish, so an agent never says yes for a person. */
+  private planPublish;
+  /** 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 folder named by an agent, resolved from the app folder; it must be inside the app. */
   private insideApp;
   private offeredTools;
@@ -185,7 +228,7 @@ declare class Door {
 /** Every verb, in the order `brief` lists them. */
 /** The verbs that only use the page: what a page-only door (a production assistant) offers. */
 declare const PAGE_VERBS: readonly ["look", "act"];
-declare const VERBS: readonly ["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"];
+declare const VERBS: readonly ["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"];
 type Verb = (typeof VERBS)[number];
 /** The JSON Schema of a verb's arguments, as MCP lists it. */
 interface ArgumentsSchema {

package/lib/cordis/door.js

@@ -306,6 +306,8 @@ const VERBS = [
 	"act",
 	"plugin-list",
 	"plugin-add",
+	"plugin-pull",
+	"plugin-publish",
 	"plugin-remove",
 	"plugin-reload",
 	"tool-list",
@@ -461,6 +463,42 @@ const VERB_SPECS = {
 			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.",
@@ -615,6 +653,14 @@ var DoorError = class extends Error {
 		this.name = "DoorError";
 	}
 };
+/** What a plan says, for a person deciding. */
+function renderPublishPlan(plan) {
+	return [
+		`Publish to ${plan.owner}/${plan.repo}${plan.createsRepository ? " (a new repository)" : ""}, ${plan.visibility}, version ${plan.version}, license ${plan.license}.`,
+		`Files: ${plan.files.join(", ")}.`,
+		`A friend gets exactly these bytes with: ${plan.pullLine}`
+	].join("\n");
+}
 /** A shell answer as text an agent reads: windows and menu items one to a line. */
 function renderShell(result) {
 	if ("windows" in result) return result.windows.length === 0 ? "no windows are open" : result.windows.map((window) => `${String(window.id)}  ${JSON.stringify(window.title)}  ${window.path}  ${String(window.width)}x${String(window.height)}${window.x === void 0 || window.y === void 0 ? "" : `@${String(window.x)},${String(window.y)}`}${window.focused ? "  focused" : ""}`).join("\n");
@@ -662,6 +708,8 @@ var Door = class {
 			}
 			case "plugin-list": return this.plugin((extensions) => extensions.list(), false);
 			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");
@@ -905,6 +953,50 @@ var Door = class {
 			text: JSON.stringify(value, null, 2)
 		};
 	}
+	share() {
+		const share = this.deps.pluginShare?.();
+		if (share === void 0) throw new DoorError("unavailable", "plugin-share is not running in this app. If the app just changed it is restarting, so try again in a moment. An app made by an older version does not have it, and upgrade does not add it: run `npx acrylblends add plugin-share` and follow its README");
+		return share;
+	}
+	/** Only a plan: no argument of any verb can publish, so an agent never says yes for a person. */
+	async planPublish(input) {
+		const { name, owner, license } = input;
+		if (typeof name !== "string" || name === "") throw new DoorError("invalid", "plugin publish needs a plugin name, e.g. plugin publish pomodoro");
+		const value = await this.share().planPublish(name, {
+			...typeof owner === "string" && owner !== "" ? { owner } : {},
+			...typeof license === "string" && license !== "" ? { license } : {}
+		});
+		if ("ok" in value) throw new DoorError("refused", `${value.reason}. ${value.next}.`);
+		return {
+			value,
+			text: `${renderPublishPlan(value)}\nNothing was sent. Only a person can say yes: they run \`npm run acryl -- plugin publish ${name}\` in their own terminal, or press Share in the frame. \`--license <id>\` changes the license before the yes.`
+		};
+	}
+	/** The person's yes, from their own terminal. Not a verb: MCP and the chat do not have it. */
+	async publishConfirmed(name, confirmed, options) {
+		const value = await this.share().publish(name, confirmed, options);
+		this.deps.audit.record({
+			at: (/* @__PURE__ */ new Date()).toISOString(),
+			tool: "plugin-publish",
+			target: {
+				role: "plugin",
+				name: `${confirmed.owner}/${confirmed.repo}@${confirmed.version}`
+			},
+			outcome: value.ok ? "ok" : "refused",
+			approval: "token"
+		});
+		return value;
+	}
+	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.action !== "unchanged" && this.deps.reloadOnChange !== false) await this.deps.channel.reloadAll();
+		return {
+			value,
+			text: JSON.stringify(value, null, 2)
+		};
+	}
 	/** 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");
@@ -1196,6 +1288,33 @@ function operatorRoutes(prefix, secret, door, reportError) {
 			reportError(`run the door verb ${verb}`, cause);
 			return c.json(error("the verb could not be run"), 500);
 		}
+	}).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;
+		if (typeof name !== "string" || typeof confirm !== "object" || confirm === null) return c.json({
+			ok: false,
+			code: "invalid",
+			message: "the body is { name, confirm }"
+		}, 400);
+		try {
+			const value = await door.publishConfirmed(name, confirm, {
+				...typeof owner === "string" ? { owner } : {},
+				...typeof license === "string" ? { license } : {}
+			});
+			return c.json({
+				ok: true,
+				value,
+				text: JSON.stringify(value, null, 2)
+			});
+		} catch (cause) {
+			if (cause instanceof DoorError) return c.json({
+				ok: false,
+				code: cause.code,
+				message: cause.message
+			}, 409);
+			reportError("publish a plugin", cause);
+			return c.json(error("the plugin could not be published"), 500);
+		}
 	});
 }
 /** The upgrade request comes from this app's own page: a loopback peer on this port, and an `Origin` that is exactly this app's origin. Nothing else is read as proof. */
@@ -1473,6 +1592,7 @@ function apply(ctx, rawConfig = {}) {
 		},
 		...appBase === "" ? {} : { appBase },
 		extensions: () => ctx.get("extensions"),
+		pluginShare: () => ctx.get("pluginShare"),
 		tools: () => ctx.get("tools"),
 		expose: config.tools?.expose ?? [],
 		reloadOnChange: config.reloadOnChange !== false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acrylblends",
-  "version": "1.2.0",
+  "version": "1.3.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/plugin.json

@@ -11,6 +11,9 @@
   "devDependencies": {
     "ws": "8.21.3"
   },
+  "scripts": {
+    "acryl": "node plugins/acryl-door/src/cli/acryl.ts"
+  },
   "mount": "mount it after acryl-node-server and extensions in development builds: root.plugin(door); add <script type=\"module\" src=\"/api/acryl-door/page.js\"></script> to the pages; the command is .acryl/bin/acryl",
   "gitignore": [".acryl/"],
   "omit": ["**/*.test.*", "**/*.spec.*", "**/*.case.ts"],

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

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * The door's operator client: what `<app>/.acryl/bin/acryl` runs. It finds the app from the folder it is started in (the nearest
+ * The door's operator client: what `npm run acryl -- <verb>` and `<app>/.acryl/bin/acryl` run. It finds the app from the folder it is started in (the nearest
  * `.acryl/door.json` upward, or `--dir`), never through PATH or a machine-wide registry, so it reaches only the app running from that
  * folder. The secret is read from that file and sent as a `Bearer` header; it is never printed.
  *
@@ -10,13 +10,14 @@
  * Exit codes: 0 done, 1 the verb failed (its code and message are printed), 2 a usage error, 3 no running app in this folder.
  */
 
+import { createInterface } from 'node:readline/promises'
 import { existsSync, realpathSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 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', '--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'])
 const FLAGS = new Set(['--json', '--submit', '--no-clear', '--gone', '--force', '--help'])
 
 export class UsageError extends Error {}
@@ -42,7 +43,7 @@ const USAGE = `usage: acryl <verb> [options] [--json] [--dir <app folder>]
   act navigate --path <path of the app, e.g. /demo>
   act wait (--text <t> | --role <role> [--name <n>]) [--gone] [--timeout-ms <ms>]
   (look and every act take --window <n>: the desktop window whose page it is for; window list prints the numbers)
-  plugin list | plugin add <folder> | plugin remove <name> | plugin reload
+  plugin list | plugin add <folder> | plugin pull <source> | plugin publish <name> [--owner <account>] [--license <id>] | plugin remove <name> | plugin reload
   window list | window open [--path <p>] | window focus --id <n> | window close --id <n> [--force]
   window resize --id <n> --width <px> --height <px>
   menu list | menu click --path "File>New Note" [--force]
@@ -138,8 +139,15 @@ 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 === 'publish') {
+        if (third === undefined) throw new UsageError('plugin publish needs a plugin name, e.g. plugin publish pomodoro')
+        const owner = values.get('--owner')
+        const license = values.get('--license')
+        return make('plugin-publish', { name: third, ...(owner === undefined ? {} : { owner }), ...(license === undefined ? {} : { license }) })
+      }
       if (second === 'remove') { if (third === undefined) throw new UsageError('plugin remove needs a plugin name'); return make('plugin-remove', { name: third }) }
-      throw new UsageError(`plugin needs list, add, remove or reload\n${USAGE}`)
+      throw new UsageError(`plugin needs list, add, pull, publish, remove or reload\n${USAGE}`)
     }
     case 'window': {
       const id = integer(values, '--id')
@@ -199,6 +207,11 @@ export interface Io {
   readonly out: (text: string) => void
   readonly err: (text: string) => void
   readonly fetch?: typeof fetch
+  /**
+   * Ask the person at this terminal; absent when nobody is there (a pipe, an agent's shell), and then nothing that needs a yes can happen.
+   * @returns whether they said yes.
+   */
+  readonly ask?: (question: string) => Promise<boolean>
 }
 
 /** Run one invocation. @returns the exit code. */
@@ -214,7 +227,7 @@ export async function main(argv: readonly string[], io: Io): Promise<number> {
   const app = findApp(io.cwd, invocation.dir)
   const file = app === undefined ? undefined : readDoorFile(app)
   if (app === undefined || file === undefined) {
-    io.err(`no running app${app === undefined ? ` in ${io.cwd} or above it` : ` in ${app}`}: start it (npm run dev) in its folder, then try again\n`)
+    io.err(`no running app${app === undefined ? ` in ${io.cwd} or above it` : ` in ${app}`}: these commands reach the running app, so start it (npm run dev) in its folder in another terminal, then run the same line again\n`)
     return 3
   }
   const request = io.fetch ?? fetch
@@ -225,7 +238,7 @@ export async function main(argv: readonly string[], io: Io): Promise<number> {
       ? await request(`${file.url}/api/acryl-door/verbs`, { headers })
       : await request(`${file.url}/api/acryl-door/call`, { method: 'POST', headers, body: JSON.stringify({ verb: invocation.verb, args: invocation.args }) })
   } catch {
-    io.err(`no running app in ${app}: ${file.url} does not answer (it stopped without removing .acryl/door.json?); start it again\n`)
+    io.err(`no running app in ${app}: ${file.url} does not answer (it stopped without removing .acryl/door.json?); start it (npm run dev), then run the same line again\n`)
     return 3
   }
   if (response.status === 403) {
@@ -243,9 +256,52 @@ export async function main(argv: readonly string[], io: Io): Promise<number> {
     return 1
   }
   io.out(invocation.json ? `${JSON.stringify(body.value)}\n` : `${body.text ?? ''}\n`)
+  if (invocation.verb === 'plugin-publish' && io.ask !== undefined && isPlan(body.value)) return confirmPublish(invocation, body.value, io, request, `${file.url}/api/acryl-door/publish-confirmed`, headers)
   return 0
 }
 
+const isPlan = (value: unknown): value is PlanAsked =>
+  typeof value === 'object' && value !== null && 'owner' in value
+
+/** What the prompt names. */
+interface PlanAsked {
+  readonly owner: string
+  readonly repo: string
+  readonly version: string
+  readonly license: string
+}
+
+/** The person's yes: only what they just read is published, and anything but a plain yes sends nothing. */
+async function confirmPublish(
+  invocation: Invocation,
+  plan: PlanAsked,
+  io: Io,
+  request: typeof fetch,
+  url: string,
+  headers: Record<string, string>,
+): Promise<number> {
+  const yes = await io.ask?.(`Publish ${plan.owner}/${plan.repo} v${plan.version} under ${plan.license}? Type yes to send it: `)
+  if (yes !== true) { io.out('Nothing was sent.\n'); return 0 }
+  const response = await request(url, { method: 'POST', headers, body: JSON.stringify({ name: invocation.args.name, owner: invocation.args.owner, license: invocation.args.license, confirm: plan }) })
+  const body = await response.json().catch(() => undefined) as { ok?: boolean; message?: string; value?: { ok?: boolean; releaseUrl?: string; pullLine?: string; reason?: string; next?: string } } | undefined
+  const result = body?.value
+  if (body?.ok !== true || result?.ok !== true) {
+    io.err(`Not published: ${result?.reason ?? body?.message ?? 'the app did not answer'}${result?.next === undefined ? '' : `. ${result.next}`}\n`)
+    return 1
+  }
+  io.out(`Published: ${result.releaseUrl ?? ''}\nA friend gets exactly these bytes with:\n  ${result.pullLine ?? ''}\n`)
+  return 0
+}
+
+async function askAtTerminal(question: string): Promise<boolean> {
+  const prompt = createInterface({ input: process.stdin, output: process.stdout })
+  try {
+    return (await prompt.question(question)).trim().toLowerCase() === 'yes'
+  } finally {
+    prompt.close()
+  }
+}
+
 /** True when this file is the program Node was started with (not imported by a test). */
 function isProgram(): boolean {
   const entry = process.argv[1]
@@ -262,6 +318,7 @@ if (isProgram()) {
     cwd: process.cwd(),
     out: (text) => { process.stdout.write(text) },
     err: (text) => { process.stderr.write(text) },
+    ...(process.stdin.isTTY && process.stdout.isTTY ? { ask: askAtTerminal } : {}),
   }).then((code) => { process.exitCode = code }, (cause: unknown) => {
     process.stderr.write(`${cause instanceof Error ? cause.message : String(cause)}\n`)
     process.exitCode = 1

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

@@ -15,7 +15,7 @@ import type { UiChannel } from './channel.ts'
 import { NO_DESKTOP, type ShellChannel } from './shell.ts'
 import { VERB_SPECS, VERBS } from './verbs.ts'
 
-export type DoorErrorCode = 'invalid' | 'unknown-verb' | 'unavailable' | 'not-exposed' | 'outside-app' | 'failed' | ShellErrorCode
+export type DoorErrorCode = 'invalid' | 'unknown-verb' | 'unavailable' | 'not-exposed' | 'outside-app' | 'failed' | 'refused' | ShellErrorCode
 
 export class DoorError extends Error {
   readonly code: DoorErrorCode
@@ -35,6 +35,41 @@ export interface ExtensionsPort {
   list(): readonly unknown[]
 }
 
+/** The slice of acrylblends' `pluginShare` service the pull verb uses. */
+export interface PluginSharePort {
+  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 }>
+}
+
+/** Who a plan publishes as, and under which license; the service's defaults when absent. */
+export interface PublishOptionsView {
+  readonly owner?: string
+  readonly license?: string
+}
+
+/** A plan as the door shows it. The service owns it; the door passes it back unchanged. */
+export interface PublishPlanView {
+  readonly owner: string
+  readonly repo: string
+  readonly version: string
+  readonly visibility: string
+  readonly license: string
+  readonly createsRepository: boolean
+  readonly files: readonly string[]
+  readonly digest: string
+  readonly pullLine: string
+}
+
+/** What a plan says, for a person deciding. */
+export function renderPublishPlan(plan: PublishPlanView): string {
+  return [
+    `Publish to ${plan.owner}/${plan.repo}${plan.createsRepository ? ' (a new repository)' : ''}, ${plan.visibility}, version ${plan.version}, license ${plan.license}.`,
+    `Files: ${plan.files.join(', ')}.`,
+    `A friend gets exactly these bytes with: ${plan.pullLine}`,
+  ].join('\n')
+}
+
 /** The slice of acrylblends' `tools` registry (the `agent` plugin's) the tool verbs use, and where the built-in chat finds the verbs. */
 export interface ToolsPort {
   /** @returns the function that removes the tool. @throws when the name is taken. */
@@ -54,6 +89,8 @@ export interface DoorDeps {
   readonly appBase?: string | undefined
   /** Read at each call: the services may come and go while the door runs. */
   readonly extensions: () => ExtensionsPort | undefined
+  /** Read at each call, as `extensions` is; absent where the app has no plugin-share row. */
+  readonly pluginShare?: () => PluginSharePort | undefined
   readonly tools: () => ToolsPort | undefined
   /** The app tools the door offers; anything else is refused before it reaches the registry. */
   readonly expose: readonly string[]
@@ -118,6 +155,8 @@ export class Door {
       }
       case 'plugin-list': return this.plugin(extensions => extensions.list(), false)
       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')
@@ -308,6 +347,41 @@ export class Door {
     return { value, text: JSON.stringify(value, null, 2) }
   }
 
+  private share(): PluginSharePort {
+    const share = this.deps.pluginShare?.()
+    if (share === undefined) throw new DoorError('unavailable', 'plugin-share is not running in this app. If the app just changed it is restarting, so try again in a moment. An app made by an older version does not have it, and upgrade does not add it: run `npx acrylblends add plugin-share` and follow its README')
+    return share
+  }
+
+  /** Only a plan: no argument of any verb can publish, so an agent never says yes for a person. */
+  private async planPublish(input: Record<string, unknown>): Promise<VerbAnswer> {
+    const { name, owner, license } = input
+    if (typeof name !== 'string' || name === '') throw new DoorError('invalid', 'plugin publish needs a plugin name, e.g. plugin publish pomodoro')
+    const value = await this.share().planPublish(name, {
+      ...(typeof owner === 'string' && owner !== '' ? { owner } : {}),
+      ...(typeof license === 'string' && license !== '' ? { license } : {}),
+    })
+    if ('ok' in value) throw new DoorError('refused', `${value.reason}. ${value.next}.`)
+    return { value, text: `${renderPublishPlan(value)}\nNothing was sent. Only a person can say yes: they run \`npm run acryl -- plugin publish ${name}\` in their own terminal, or press Share in the frame. \`--license <id>\` changes the license before the yes.` }
+  }
+
+  /** The person's yes, from their own terminal. Not a verb: MCP and the chat do not have it. */
+  async publishConfirmed(name: string, confirmed: PublishPlanView, options: PublishOptionsView): Promise<unknown> {
+    const value = await this.share().publish(name, confirmed, options)
+    this.deps.audit.record({ at: new Date().toISOString(), tool: 'plugin-publish', target: { role: 'plugin', name: `${confirmed.owner}/${confirmed.repo}@${confirmed.version}` }, outcome: value.ok ? 'ok' : 'refused', approval: 'token' })
+    return value
+  }
+
+  private async pull(source: unknown): Promise<VerbAnswer> {
+    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'}.`)
+    // 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 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')

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.',