acrylblends 0.11.0 → 1.0.0

package/dist/index.js

@@ -1,10 +1,143 @@
 import { createRequire } from "node:module";
-import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, posix, relative, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
 import { fileURLToPath } from "node:url";
+import { createHash } from "node:crypto";
 import { spawn } from "node:child_process";
 import { createInterface } from "node:readline/promises";
+//#region src/templates.ts
+/** The templates, all Cordis apps: a web app with a page and a client component (nodejs), a notes app and a chat app on the db port (notes, chat), a blank app on the router, a todo list on the router and state, and the blank app with the offline agent. */
+const TEMPLATES = [
+	"blank",
+	"nodejs",
+	"notes",
+	"chat",
+	"todo",
+	"agent"
+];
+/** One line per template: the single list `acrylblends init` and `create-acrylblends` both show (`create-acrylblends` tests that its own copy equals this one). */
+const TEMPLATE_SUMMARY = {
+	blank: "the router, a server and one route: the smallest app",
+	nodejs: "a web app with a page and a client component",
+	notes: "a multi-user notes app on the db port (sign-up, log-in, sessions)",
+	chat: "a chat app that streams an answer over server-sent events",
+	todo: "a to-do list on the router and state",
+	agent: "the blank app with an offline agent that builds plugins into the running app"
+};
+/** Names that were templates once and still work: `create-acrylblends --template acryl-app` made the agent app. */
+const TEMPLATE_ALIASES = { "acryl-app": "agent" };
+function isTemplate(value) {
+	return TEMPLATES.includes(value);
+}
+/** The template a name means: itself, or what an old name stands for; undefined for anything else. */
+function resolveTemplate(value) {
+	return isTemplate(value) ? value : TEMPLATE_ALIASES[value];
+}
+/**
+* The `templates/` folder of this package. The module sits at different depths in source (`src/`) and in the build
+* (`dist/`), so walk up until a `templates` folder holds the `blank` template.
+*/
+function templatesRoot() {
+	let dir = dirname(fileURLToPath(import.meta.url));
+	for (;;) {
+		const candidate = join(dir, "templates");
+		if (existsSync(join(candidate, "blank"))) return candidate;
+		const parent = dirname(dir);
+		if (parent === dir) throw new Error("acrylblends cannot find its templates folder");
+		dir = parent;
+	}
+}
+/** Absolute path of a template folder. */
+function templateDir(template) {
+	return join(templatesRoot(), template);
+}
+/** The text every generated app's `AGENTS.md` starts with (`shared/`, beside `templates/`). */
+function sharedDir() {
+	return join(dirname(templatesRoot()), "shared");
+}
+/**
+* The framework's docs, as ACRYL wrote them: `docs/framework` of the repository, or the copy `prepack` puts inside the package. The module sits at
+* different depths in source and in the build, so walk up until a `docs/framework` folder holds the README.
+*/
+function frameworkDocsRoot() {
+	let dir = dirname(fileURLToPath(import.meta.url));
+	for (;;) {
+		const candidate = join(dir, "docs", "framework");
+		if (existsSync(join(candidate, "README.md"))) return candidate;
+		const parent = dirname(dir);
+		if (parent === dir) throw new Error("acrylblends cannot find the framework docs (docs/framework)");
+		dir = parent;
+	}
+}
+//#endregion
+//#region src/version.ts
+/** The version of this package. */
+const VERSION = createRequire(import.meta.url)("../package.json").version;
+//#endregion
+//#region src/lock.ts
+/**
+* What an app knows about the library plugins it carries: `plugins/library.lock.json` records, for every library plugin copied into the app, the version it came from and a hash of each file
+* as it was copied. `acrylblends upgrade` reads it to tell a file nobody touched (safe to replace) from one the app edited (never replaced without `--force`). An app made before the lock existed
+* has none; for it `upgrade` falls back to the hashes of the released versions (`shared/library-history.json`, made by `scripts/build-library-history.mjs`).
+*/
+const LOCK_FILE = "library.lock.json";
+/** A file's identity: a hash of its text with line endings normalized (a checkout may have changed them), cut to 20 hex digits. */
+function digest(content) {
+	const text = typeof content === "string" ? content : content.toString("utf8");
+	return createHash("sha256").update(text.replace(/\r\n/gu, "\n")).digest("hex").slice(0, 20);
+}
+/** Every file below `dir`, as `relative/path` (forward slashes) to its {@link digest}. */
+function hashFolder(dir) {
+	const files = {};
+	const walk = (folder, inside) => {
+		for (const entry of readdirSync(folder).sort()) {
+			const path = join(folder, entry);
+			const name = inside === "" ? entry : `${inside}/${entry}`;
+			if (statSync(path).isDirectory()) walk(path, name);
+			else files[name] = digest(readFileSync(path));
+		}
+	};
+	if (existsSync(dir)) walk(dir, "");
+	return files;
+}
+function readLock(pluginsDir) {
+	const file = join(pluginsDir, LOCK_FILE);
+	if (!existsSync(file)) return {
+		version: 1,
+		plugins: {}
+	};
+	try {
+		return {
+			version: 1,
+			plugins: JSON.parse(readFileSync(file, "utf8")).plugins ?? {}
+		};
+	} catch {
+		return {
+			version: 1,
+			plugins: {}
+		};
+	}
+}
+/** Record that `name` was copied from this version of the library, with the hashes of the files as they now are. */
+function recordLock(pluginsDir, name, files) {
+	const lock = readLock(pluginsDir);
+	lock.plugins[name] = {
+		from: VERSION,
+		files
+	};
+	const sorted = Object.fromEntries(Object.entries(lock.plugins).sort(([a], [b]) => a.localeCompare(b)));
+	writeFileSync(join(pluginsDir, LOCK_FILE), `${JSON.stringify({
+		version: 1,
+		plugins: sorted
+	}, null, 2)}\n`);
+}
+function readHistory() {
+	const file = join(sharedDir(), "library-history.json");
+	if (!existsSync(file)) return {};
+	return JSON.parse(readFileSync(file, "utf8"));
+}
+//#endregion
 //#region src/rewrite.ts
 function entryTable(library) {
 	const table = /* @__PURE__ */ new Map();
@@ -154,6 +287,7 @@ function pluginsFolder(appDir) {
 }
 /** The warning for an app with the old layout. */
 const LEGACY_WARNING = "warning: this app keeps its plugins in src/plugins/ (and extensions/); plugins now live in one folder, plugins/. Move them with \"git mv src/plugins plugins\", fix the paths in tsconfig.json, package.json and src/, and see docs/framework/agents/index.md. The old layout is read for this release only.";
+/** List `name` among the library copies of a plugins folder (`library.json`). */
 function recordLibraryCopy(folder, name) {
 	const file = join(folder, LIBRARY_LIST);
 	const names = existsSync(file) ? JSON.parse(readFileSync(file, "utf8")).plugins : [];
@@ -177,7 +311,10 @@ function copyPlugin(plugin, appDir, root = libraryRoot()) {
 		}
 	});
 	if (entries) rewriteTree(join(target, "src"), plugin.name, "src", entries);
-	if (!folder.legacy) recordLibraryCopy(folder.dir, plugin.name);
+	if (!folder.legacy) {
+		recordLibraryCopy(folder.dir, plugin.name);
+		recordLock(folder.dir, plugin.name, hashFolder(target));
+	}
 	return target;
 }
 /** Rewrite the `acryl-*` imports of every TypeScript file below `dir` (the plugin's `src/`) to relative paths. */
@@ -194,10 +331,6 @@ function copyRewritten(from, to, plugin, inside, root = libraryRoot()) {
 }
 const relativeName = (appDir, path) => path.slice(appDir.length + 1).split(sep).join("/");
 //#endregion
-//#region src/version.ts
-/** The version of this package. */
-const VERSION = createRequire(import.meta.url)("../package.json").version;
-//#endregion
 //#region src/project.ts
 /** Thrown when the target directory exists and is not empty. Nothing has been written. */
 var TargetNotEmptyError = class extends Error {
@@ -392,56 +525,6 @@ function copyFrameworkDocs(source, target) {
 	return written;
 }
 //#endregion
-//#region src/templates.ts
-/** The templates, all Cordis apps: a web app with a page and a client component (nodejs), a notes app and a chat app on the db port (notes, chat), a blank app on the router, a todo list on the router and state, and the blank app with the offline agent. */
-const TEMPLATES = [
-	"nodejs",
-	"notes",
-	"chat",
-	"blank",
-	"todo",
-	"agent"
-];
-function isTemplate(value) {
-	return TEMPLATES.includes(value);
-}
-/**
-* The `templates/` folder of this package. The module sits at different depths in source (`src/`) and in the build
-* (`dist/`), so walk up until a `templates` folder holds the `blank` template.
-*/
-function templatesRoot() {
-	let dir = dirname(fileURLToPath(import.meta.url));
-	for (;;) {
-		const candidate = join(dir, "templates");
-		if (existsSync(join(candidate, "blank"))) return candidate;
-		const parent = dirname(dir);
-		if (parent === dir) throw new Error("acrylblends cannot find its templates folder");
-		dir = parent;
-	}
-}
-/** Absolute path of a template folder. */
-function templateDir(template) {
-	return join(templatesRoot(), template);
-}
-/** The text every generated app's `AGENTS.md` starts with (`shared/`, beside `templates/`). */
-function sharedDir() {
-	return join(dirname(templatesRoot()), "shared");
-}
-/**
-* The framework's docs, as ACRYL wrote them: `docs/framework` of the repository, or the copy `prepack` puts inside the package. The module sits at
-* different depths in source and in the build, so walk up until a `docs/framework` folder holds the README.
-*/
-function frameworkDocsRoot() {
-	let dir = dirname(fileURLToPath(import.meta.url));
-	for (;;) {
-		const candidate = join(dir, "docs", "framework");
-		if (existsSync(join(candidate, "README.md"))) return candidate;
-		const parent = dirname(dir);
-		if (parent === dir) throw new Error("acrylblends cannot find the framework docs (docs/framework)");
-		dir = parent;
-	}
-}
-//#endregion
 //#region src/init.ts
 /** A command line mistake. The CLI prints it with the help text and exits 2. */
 var UsageError = class extends Error {
@@ -451,26 +534,27 @@ var UsageError = class extends Error {
 function parseInitOptions(argv) {
 	let parsed;
 	try {
-		parsed = parse$2(argv);
+		parsed = parse$3(argv);
 	} catch (error) {
 		throw new UsageError(error.message);
 	}
 	const { values, positionals } = parsed;
 	if (positionals.length > 1) throw new UsageError("init takes at most one directory");
 	if (values.agent && values["no-agent"]) throw new UsageError("use --agent or --no-agent, not both");
-	if (values.template !== void 0 && !isTemplate(values.template)) throw new UsageError(`unknown template "${values.template}" (${TEMPLATES.join(", ")})`);
+	const named = values.template === void 0 ? void 0 : resolveTemplate(values.template);
+	if (values.template !== void 0 && named === void 0) throw new UsageError(`unknown template "${values.template}" (${TEMPLATES.join(", ")})`);
 	const alias = values.agent ? "agent" : values["no-agent"] ? "blank" : void 0;
-	if (values.template !== void 0 && alias !== void 0 && values.template !== alias) throw new UsageError(`--template ${values.template} contradicts --${alias === "agent" ? "agent" : "no-agent"}`);
+	if (named !== void 0 && alias !== void 0 && named !== alias) throw new UsageError(`--template ${values.template} contradicts --${alias === "agent" ? "agent" : "no-agent"}`);
 	return {
 		directory: positionals[0],
 		name: values.name,
-		template: values.template ?? alias,
+		template: named ?? alias,
 		install: values.install,
 		desktop: values.desktop === true,
 		yes: values.yes === true
 	};
 }
-const parse$2 = (argv) => parseArgs({
+const parse$3 = (argv) => parseArgs({
 	args: [...argv],
 	allowPositionals: true,
 	strict: true,
@@ -489,9 +573,10 @@ const parse$2 = (argv) => parseArgs({
 });
 const yes = (answer) => ["y", "yes"].includes(answer.trim().toLowerCase());
 async function askTemplate(ask) {
-	const answer = (await ask(`Template (${TEMPLATES.join(", ")}) [blank]: `)).trim().toLowerCase();
+	const answer = (await ask(`Templates:\n${TEMPLATES.map((name) => `  ${name.padEnd(7)} ${TEMPLATE_SUMMARY[name]}`).join("\n")}\nTemplate [blank]: `)).trim().toLowerCase();
 	if (answer === "") return "blank";
-	if (isTemplate(answer)) return answer;
+	const chosen = resolveTemplate(answer);
+	if (chosen !== void 0) return chosen;
 	throw new UsageError(`unknown template "${answer}" (${TEMPLATES.join(", ")})`);
 }
 /** Scaffold a Cordis app. Returns the exit code: 0 done, 1 refused or failed. Never overwrites anything. */
@@ -542,7 +627,7 @@ async function init(options, io) {
 function parseAddOptions(argv) {
 	let parsed;
 	try {
-		parsed = parse$1(argv);
+		parsed = parse$2(argv);
 	} catch (error) {
 		throw new UsageError(error.message);
 	}
@@ -553,7 +638,7 @@ function parseAddOptions(argv) {
 		suite: parsed.values.suite === true
 	};
 }
-const parse$1 = (argv) => parseArgs({
+const parse$2 = (argv) => parseArgs({
 	args: [...argv],
 	allowPositionals: true,
 	strict: true,
@@ -976,7 +1061,7 @@ function processIo() {
 function parseKvOptions(argv) {
 	let parsed;
 	try {
-		parsed = parse(argv);
+		parsed = parse$1(argv);
 	} catch (error) {
 		throw new UsageError(error.message);
 	}
@@ -991,7 +1076,7 @@ function parseKvOptions(argv) {
 		migrations: parsed.values.migrations
 	};
 }
-const parse = (argv) => parseArgs({
+const parse$1 = (argv) => parseArgs({
 	args: [...argv],
 	allowPositionals: true,
 	strict: true,
@@ -1046,6 +1131,295 @@ async function kvImport(options, io) {
 	}
 }
 //#endregion
+//#region src/diff.ts
+function ops(a, b) {
+	if (a.length * b.length > 6e6) return void 0;
+	const width = b.length + 1;
+	const table = new Uint32Array((a.length + 1) * width);
+	for (let i = a.length - 1; i >= 0; i -= 1) for (let j = b.length - 1; j >= 0; j -= 1) table[i * width + j] = a[i] === b[j] ? table[(i + 1) * width + j + 1] + 1 : Math.max(table[(i + 1) * width + j], table[i * width + j + 1]);
+	const out = [];
+	let i = 0;
+	let j = 0;
+	while (i < a.length && j < b.length) if (a[i] === b[j]) {
+		out.push({
+			kind: " ",
+			line: a[i]
+		});
+		i += 1;
+		j += 1;
+	} else if (table[(i + 1) * width + j] >= table[i * width + j + 1]) {
+		out.push({
+			kind: "-",
+			line: a[i]
+		});
+		i += 1;
+	} else {
+		out.push({
+			kind: "+",
+			line: b[j]
+		});
+		j += 1;
+	}
+	for (; i < a.length; i += 1) out.push({
+		kind: "-",
+		line: a[i]
+	});
+	for (; j < b.length; j += 1) out.push({
+		kind: "+",
+		line: b[j]
+	});
+	return out;
+}
+const lines = (text) => text === "" ? [] : text.replace(/\r\n/gu, "\n").replace(/\n$/u, "").split("\n");
+/** How many lines a change adds and removes; undefined counts when the pair is too large to compare. */
+function diffStat(from, to) {
+	const all = ops(lines(from), lines(to));
+	if (all === void 0) return {
+		added: lines(to).length,
+		removed: lines(from).length
+	};
+	return {
+		added: all.filter((op) => op.kind === "+").length,
+		removed: all.filter((op) => op.kind === "-").length
+	};
+}
+/** `--- a/<name>`, `+++ b/<name>` and the hunks; empty when the texts are equal. */
+function unifiedDiff(name, from, to, context = 3) {
+	const a = lines(from);
+	const b = lines(to);
+	const all = ops(a, b);
+	if (all === void 0) return `--- a/${name}\n+++ b/${name}\n(too large to compare line by line: ${a.length} lines became ${b.length})\n`;
+	if (!all.some((op) => op.kind !== " ")) return "";
+	const out = [`--- a/${name}`, `+++ b/${name}`];
+	let at = 0;
+	let aLine = 1;
+	let bLine = 1;
+	const positions = all.map((op) => {
+		const here = {
+			a: aLine,
+			b: bLine
+		};
+		if (op.kind !== "+") aLine += 1;
+		if (op.kind !== "-") bLine += 1;
+		return here;
+	});
+	while (at < all.length) {
+		while (at < all.length && all[at]?.kind === " ") at += 1;
+		if (at >= all.length) break;
+		const start = Math.max(0, at - context);
+		let end = at;
+		for (let k = at; k < all.length; k += 1) if (all[k]?.kind !== " ") end = k;
+		else if (k - end > context * 2) break;
+		const stop = Math.min(all.length, end + context + 1);
+		const slice = all.slice(start, stop);
+		const first = positions[start];
+		out.push(`@@ -${first.a},${slice.filter((op) => op.kind !== "+").length} +${first.b},${slice.filter((op) => op.kind !== "-").length} @@`);
+		for (const op of slice) out.push(`${op.kind}${op.line}`);
+		at = stop;
+	}
+	return `${out.join("\n")}\n`;
+}
+//#endregion
+//#region src/upgrade.ts
+/** Parse `upgrade [plugin...] [--dir <app>] [--dry-run] [--force] [--diff]`. */
+function parseUpgradeOptions(argv) {
+	let parsed;
+	try {
+		parsed = parse(argv);
+	} catch (error) {
+		throw new UsageError(error.message);
+	}
+	return {
+		names: parsed.positionals,
+		directory: parsed.values.dir,
+		dryRun: parsed.values["dry-run"] === true,
+		force: parsed.values.force === true,
+		diff: parsed.values.diff === true
+	};
+}
+const parse = (argv) => parseArgs({
+	args: [...argv],
+	allowPositionals: true,
+	strict: true,
+	options: {
+		dir: { type: "string" },
+		"dry-run": { type: "boolean" },
+		force: { type: "boolean" },
+		diff: { type: "boolean" }
+	}
+});
+const posix$1 = (path) => path.split(sep).join("/");
+function readText(path) {
+	return readFileSync(path, "utf8");
+}
+/** The library copies an app carries: the plugins listed in `plugins/library.json`, or when there is none the folders of `plugins/` that the library knows. */
+function carriedCopies(dir) {
+	const listFile = join(dir, LIBRARY_LIST);
+	return (existsSync(listFile) ? JSON.parse(readFileSync(listFile, "utf8")).plugins ?? [] : readdirSync(dir).filter((name) => statSync(join(dir, name)).isDirectory())).filter((name) => existsSync(join(dir, name)));
+}
+/**
+* `acrylblends upgrade`: bring the library plugins an app carries (the router, the server, the door, `extensions`, ...) up to the version of this package. Each file is compared with what
+* the app was given: an untouched file is replaced, a file the app edited stops the upgrade (it is shown as a diff and nothing changes) unless `--force`, which saves the edited version
+* under `.acrylblends/upgrade-backup/` first. Returns the exit code: 0 done or nothing to do, 1 refused or failed.
+*/
+async function upgrade(options, io) {
+	const appDir = resolve(io.cwd, options.directory ?? ".");
+	if (!existsSync(join(appDir, "package.json")) || !existsSync(join(appDir, "src"))) {
+		io.stderr.write(`error: ${appDir} is not an app (no package.json and src/); run "acrylblends init" first\n`);
+		return 1;
+	}
+	const folder = pluginsFolder(appDir);
+	if (folder.legacy) {
+		io.stderr.write(`${LEGACY_WARNING}\nerror: upgrade needs the one-folder layout (plugins/); move the plugins first\n`);
+		return 1;
+	}
+	const library = readLibrary();
+	const carried = carriedCopies(folder.dir);
+	const unknown = carried.filter((name) => !library.has(name));
+	for (const name of options.names) if (!carried.includes(name)) {
+		io.stderr.write(`error: the app carries no library plugin "${name}" (it carries: ${carried.filter((n) => library.has(n)).join(", ") || "none"})\n`);
+		return 1;
+	}
+	const selected = (options.names.length > 0 ? [...options.names] : carried).filter((name) => library.has(name));
+	if (selected.length === 0) {
+		io.stdout.write("nothing to upgrade: the app carries no library plugins\n");
+		return 0;
+	}
+	const scratch = join(appDir, ".acrylblends", `upgrade-${process.pid}-${Date.now()}`);
+	const lock = readLock(folder.dir);
+	const history = readHistory();
+	const plans = [];
+	try {
+		mkdirSync(join(scratch, "plugins"), { recursive: true });
+		const wanted = closure(selected, library);
+		for (const plugin of wanted) copyPlugin(plugin, scratch);
+		for (const plugin of wanted) {
+			const here = join(folder.dir, plugin.name);
+			const fresh = hashFolder(join(scratch, "plugins", plugin.name));
+			const files = /* @__PURE__ */ new Map();
+			const isNew = !existsSync(here);
+			const mine = isNew ? {} : hashFolder(here);
+			const recorded = lock.plugins[plugin.name]?.files ?? {};
+			const pristine = (file, hash) => recorded[file] === hash || (history[plugin.name]?.[file]?.includes(hash) ?? false);
+			for (const [file, hash] of Object.entries(fresh)) {
+				const have = mine[file];
+				files.set(file, have === void 0 ? "add" : have === hash ? "same" : pristine(file, have) ? "update" : "conflict");
+			}
+			for (const [file, hash] of Object.entries(mine)) if (!(file in fresh)) files.set(file, pristine(file, hash) ? "remove" : "extra");
+			plans.push({
+				plugin,
+				isNew,
+				files,
+				fresh
+			});
+		}
+		const count = (plan, state) => [...plan.files].filter(([, s]) => s === state).map(([file]) => file);
+		io.stdout.write(`upgrade: the library plugins of ${appDir} to acrylblends ${VERSION}\n`);
+		let conflicts = 0;
+		let changes = 0;
+		for (const plan of plans) {
+			const [updated, added, removed, edited, extra] = [
+				"update",
+				"add",
+				"remove",
+				"conflict",
+				"extra"
+			].map((state) => count(plan, state));
+			const label = plan.plugin.name.padEnd(22);
+			conflicts += edited.length;
+			if (plan.isNew) {
+				changes += 1;
+				io.stdout.write(`  ${label} new (required by a plugin of the app)\n`);
+				continue;
+			}
+			if (updated.length + added.length + removed.length + edited.length === 0) {
+				io.stdout.write(`  ${label} up to date${extra.length > 0 ? ` (keeps ${extra.length} file(s) of its own)` : ""}\n`);
+				continue;
+			}
+			changes += 1;
+			let plus = 0;
+			let minus = 0;
+			for (const file of [...updated, ...edited]) {
+				const stat = diffStat(readText(join(folder.dir, plan.plugin.name, file)), readText(join(scratch, "plugins", plan.plugin.name, file)));
+				plus += stat.added;
+				minus += stat.removed;
+			}
+			const parts = [
+				updated.length > 0 ? `${updated.length} updated (+${plus} -${minus})` : "",
+				added.length > 0 ? `${added.length} added` : "",
+				removed.length > 0 ? `${removed.length} removed` : "",
+				edited.length > 0 ? `${edited.length} EDITED HERE` : "",
+				extra.length > 0 ? `${extra.length} of its own kept` : ""
+			].filter(Boolean);
+			io.stdout.write(`  ${label} ${parts.join(", ")}\n`);
+		}
+		for (const name of unknown) io.stdout.write(`  ${name.padEnd(22)} not in this library: left alone\n`);
+		for (const plan of plans) for (const [file, state] of plan.files) {
+			if (!(state === "conflict" || options.diff && (state === "update" || state === "add" || state === "remove"))) continue;
+			const name = `plugins/${plan.plugin.name}/${file}`;
+			const before = state === "add" ? "" : readText(join(folder.dir, plan.plugin.name, file));
+			const after = state === "remove" ? "" : readText(join(scratch, "plugins", plan.plugin.name, file));
+			io.stdout.write(`\n${state === "conflict" ? "EDITED HERE, the upgrade would replace it:\n" : ""}${unifiedDiff(name, before, after)}`);
+		}
+		if (conflicts > 0 && !options.force) {
+			io.stderr.write(`\nerror: ${conflicts} file(s) were edited in this app and the upgrade would replace them; nothing was changed. Review the diffs above, move your changes out of the plugin (a plugin of your own in plugins/<name>/), or run again with --force (the edited versions are saved under .acrylblends/upgrade-backup/)\n`);
+			return 1;
+		}
+		if (options.dryRun) {
+			io.stdout.write(`\n${changes === 0 ? "everything is up to date" : "dry run: nothing was changed"}\n`);
+			return 0;
+		}
+		if (changes === 0) {
+			io.stdout.write("\neverything is up to date\n");
+			return 0;
+		}
+		const backup = join(appDir, ".acrylblends", "upgrade-backup", (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/gu, "-"));
+		const addedDependencies = [];
+		for (const plan of plans) {
+			const here = join(folder.dir, plan.plugin.name);
+			if (plan.isNew) {
+				mkdirSync(here, { recursive: true });
+				cpSync(join(scratch, "plugins", plan.plugin.name), here, { recursive: true });
+				recordLibraryCopy(folder.dir, plan.plugin.name);
+			} else {
+				for (const [file, state] of plan.files) {
+					const target = join(here, file);
+					if (state === "conflict") {
+						mkdirSync(dirname(join(backup, plan.plugin.name, file)), { recursive: true });
+						cpSync(target, join(backup, plan.plugin.name, file));
+					}
+					if (state === "add" || state === "update" || state === "conflict") {
+						mkdirSync(dirname(target), { recursive: true });
+						cpSync(join(scratch, "plugins", plan.plugin.name, file), target);
+					} else if (state === "remove") rmSync(target, { force: true });
+				}
+				recordLibraryCopy(folder.dir, plan.plugin.name);
+			}
+			recordLock(folder.dir, plan.plugin.name, plan.fresh);
+			const plugin = plan.plugin;
+			if (plugin.imports) mergeImports(appDir, plugin.imports, posix$1(relative(appDir, folder.dir)));
+			addedDependencies.push(...mergeDependencies(appDir, plugin.dependencies));
+			addedDependencies.push(...mergeTooling(appDir, plugin).devDependencies);
+			appendGitignore(appDir, plugin.gitignore);
+		}
+		const manifestFile = join(appDir, "package.json");
+		const manifest = JSON.parse(readFileSync(manifestFile, "utf8"));
+		if (manifest.dependencies?.acrylblends !== void 0 && manifest.dependencies.acrylblends !== `^${VERSION}`) {
+			manifest.dependencies.acrylblends = `^${VERSION}`;
+			writeFileSync(manifestFile, `${JSON.stringify(manifest, null, 2)}\n`);
+		}
+		io.stdout.write(`\nupgraded ${plans.filter((p) => [...p.files.values()].some((s) => s !== "same" && s !== "extra") || p.isNew).map((p) => p.plugin.name).join(", ")}\n`);
+		if (conflicts > 0) io.stdout.write(`the ${conflicts} edited file(s) replaced by --force are saved in ${posix$1(relative(appDir, backup))}/\n`);
+		io.stdout.write(`acrylblends is now ^${VERSION} in package.json${addedDependencies.length > 0 ? `; new dependencies: ${[...new Set(addedDependencies)].join(", ")}` : ""}: run npm install, then npm run check and npm test\n`);
+		return 0;
+	} finally {
+		rmSync(scratch, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+//#endregion
 //#region src/cli.ts
 const HELP = `acrylblends ${VERSION} - scaffold Cordis apps
 
@@ -1054,6 +1428,9 @@ Usage:
   acrylblends add <plugin...> [--dir d] [--suite]  Copy library plugins (and what they require) into an app;
                                       a folder path brings an external plugin into its plugins/;
                                       --suite also copies the port's conformance suite and vitest (add kv --suite)
+  acrylblends upgrade [plugin...] [--dir d] [--dry-run] [--force] [--diff]
+                                      Bring the library plugins an app carries (the router, the server, the door, ...) up to this
+                                      version: untouched files are replaced, an edited file stops it (diff shown) unless --force
   acrylblends plugins                    List the plugin library
   acrylblends build-client [root] [out]  Compile the client modules once for production (src/client to dist/client)
   acrylblends kv import <kv.json> <db>   Move a JSON-file kv store into the kv table of a SQLite database [--overwrite] [--table t] [--migrations dir]
@@ -1061,7 +1438,7 @@ Usage:
                                       package.json "acryl": { "opener": "src/db.ts" } (a port is imported, a provider is not)
 
 Options for init:
-  --template <name>      blank or agent (asked when not given); --agent means --template agent,
+  --template <name>      one of the templates below (asked when not given); --agent means --template agent,
                          --no-agent means --template blank
   --name <name>          the project name (default: the directory name)
   --desktop              also add the desktop shell: npm run desktop opens a window on the app
@@ -1070,6 +1447,9 @@ Options for init:
 
   -h, --help             show this help
   -v, --version          show the version
+
+Templates (the same list as npm create acrylblends):
+${TEMPLATES.map((name) => `  ${name.padEnd(7)} ${TEMPLATE_SUMMARY[name]}`).join("\n")}
 `;
 /**
 * Run the CLI and return the exit code: 0 done, 1 failed or refused, 2 a usage error. Never calls `process.exit`.
@@ -1087,6 +1467,7 @@ async function runCli(argv, io = processIo()) {
 		}
 		if (command === "init") return await init(parseInitOptions(args), io);
 		if (command === "add") return await add(parseAddOptions(args), io);
+		if (command === "upgrade") return await upgrade(parseUpgradeOptions(args), io);
 		if (command === "build-client") return await buildClient(parseBuildClientOptions(args), io);
 		if (command === "kv") return await kvImport(parseKv(args), io);
 		if (command === "check-deps") return checkDeps(parseCheckDeps(args), io);
@@ -1112,6 +1493,6 @@ function parseKv(args) {
 	return parseKvOptions(args);
 }
 //#endregion
-export { HELP, TEMPLATES, TargetNotEmptyError, UsageError, VERSION, add, assertTargetFree, closure, copyPlugin, copyTemplate, init, isOmitted, isTemplate, isValidName, libraryRoot, listPlugins, mergeDependencies, nameFrom, parseAddOptions, parseInitOptions, readLibrary, readTemplatePlugins, runCli, templateDir, templatesRoot };
+export { HELP, TEMPLATES, TEMPLATE_ALIASES, TEMPLATE_SUMMARY, TargetNotEmptyError, UsageError, VERSION, add, assertTargetFree, closure, copyPlugin, copyTemplate, init, isOmitted, isTemplate, isValidName, libraryRoot, listPlugins, mergeDependencies, nameFrom, parseAddOptions, parseInitOptions, parseUpgradeOptions, readLibrary, readTemplatePlugins, resolveTemplate, runCli, templateDir, templatesRoot, upgrade };
 
 //# sourceMappingURL=index.js.map