acrylblends 1.0.1 → 1.0.3

package/README.md

@@ -103,31 +103,33 @@ Every Electron call lives in `plugins/desktop`, so the app's own code never impo
 ## Start from the registry
 
 The registry is a set of starting points people published, browsable at [acrylblends.github.io/blends](https://acrylblends.github.io/blends)
-and readable by any tool as plain JSON at <https://acrylblends.github.io/registry/index.json>. ACRYL's CLI pulls one by id, or from any git
-repository:
+and readable by any tool as plain JSON at <https://acrylblends.github.io/registry/index.json>. Each entry says which runtime it is for. An
+`acrylblends` starter is a whole app, and one command makes it from npm alone:
 
 ```sh
-npm install -g acryl
-acryl new my-app --from acryl.gtd               # a starter from the registry
-acryl new my-app --from github:you/starter      # a repository with an acryl.template.json
+npm create acrylblends@latest my-notes -- --from acrylblends.notes-desktop     # npm needs the -- before the options
+cd my-notes
+npm install
+npm run dev
 ```
 
-Without `--from`, `acryl new` writes the blank app; `--blueprint` picks another built-in Blueprint. A team's own registry is the same layout in
-its own repository: `--registry <git URL or folder>` reads starters from there instead of the public one.
+The other starters in the registry (`acryl.gtd`, `acryl.blank`, ...) are for the ACRYL app: `create-acrylblends` refuses them with a line that
+says so. A repository with an `acryl.template.json` works the same way (`-- --from github:you/starter`), and a team's own registry is the same
+layout in its own repository (`-- --from you.thing --registry github:you/registry`).
 
 ## Publish your app, or your own starter
 
 **Your app** belongs to you and lives in your repository: `npm run save` commits it and pushes to its remote. It refuses a file that looks like
 a secret, and refuses to push a private app to a public remote.
 
-Before an app goes on a server: with `NODE_ENV=production` the door, the agent panel and the PTY driver start nothing, but the `agent` template
-still mounts its own agent, builder and extensions rows. Start from one of the other five templates, or remove those rows from its `blend.yaml`
+Before an app goes on a server: with `NODE_ENV=production` the door, the agent panel and the PTY driver start nothing, the `agent` template leaves its agent, builder and extensions rows out
+(`ACRYL_PRODUCTION_KEEP` names the ones to keep, with a warning), and the `chat` template is closed until it has a `CHAT_ACCESS_TOKEN`
 - see [What runs in production](https://github.com/acrylblends/acrylblends/blob/main/docs/framework/guides/production.md).
 
-**A starter** other people can pull is a pull request to the registry repository: add `registry/blends/<id>/` with a `blend.yaml` (`kind: Blueprint`,
-an id you own, the license, `visibility`, a category and a one-line description), the plugins it adds under `plugins/`, and a `README.md`. CI
-validates every entry and fails when `index.json` is stale, so what the site lists is what passed. The layout, and how to keep a starter private
-without a registry at all, is in
+**A starter** other people can pull is a pull request to the registry repository: add `registry/blends/<id>/` with your app as it stands (without `node_modules/`
+and `dist/`), its `blend.yaml` made public (`id`, a licence, a category and a one-line description) and an `acryl.template.json`, which is what marks it as an
+app for acrylblends. CI validates every entry, makes the app with `create-acrylblends`, and fails when `index.json` is stale, so what the site lists is what
+passed. The layout, and how to keep a starter private without a registry at all, is in
 [the registry README](https://github.com/acrylblends/acrylblends.github.io/tree/main/registry).
 
 ## Keep the framework current
@@ -135,10 +137,12 @@ without a registry at all, is in
 An app carries its framework plugins as source, so a new release moves them in place and leaves your own code alone:
 
 ```sh
-npx acrylblends upgrade --dry-run   # the plan: what would be replaced
-npx acrylblends upgrade             # an edited file stops it with the diff, unless --force
+npx acrylblends@latest upgrade --dry-run   # the plan: what would be replaced
+npx acrylblends@latest upgrade             # an edited file stops it with the diff, unless --force
 ```
 
+Write `@latest`: a bare `npx acrylblends upgrade` runs the copy the app has installed, and an app made before 1.0 has an old one with no `upgrade` verb (it prints its help and exits 0, so it looks as if it worked, or answers "unknown command" and exits 2).
+
 ## Use it as a library
 
 An Acryl app is also a plain function from `Request` to `Response`, which needs no scaffold. Create a folder and install the package:

package/bin/acrylblends.js

@@ -1,4 +1,12 @@
 #!/usr/bin/env node
-import { runCli } from '../dist/index.js'
+// A Node too old to run the package is told so in plain words, before anything is loaded that would fail on it.
+const [major, minor] = process.versions.node.split('.').map(Number)
+if (major < 22 || (major === 22 && minor < 19)) {
+  console.error(
+    `Node 22.19+ needed, you have ${process.versions.node}: install it from https://nodejs.org or with nvm (nvm install 22).`,
+  )
+  process.exit(1)
+}
+const { runCli } = await import('../dist/index.js')
 
 process.exitCode = await runCli(process.argv.slice(2))

package/dist/index.d.ts

@@ -74,6 +74,8 @@ interface InitOptions {
   install: boolean | undefined;
   /** Also add the desktop shell (`add desktop`): an Electron window on the app's own server. */
   desktop: boolean;
+  /** Print no "Next:" block: `create-acrylblends` runs `init` and prints its own, for the package manager it knows. */
+  quietNext: boolean;
   yes: boolean;
 }
 /** Parse `init [dir] [--template t] [--agent|--no-agent] [--name n] [--install] [-y]`. `--agent` means `--template agent`, `--no-agent` means `--template blank`. */

package/dist/index.js

@@ -472,7 +472,33 @@ function mergeTooling(appDir, tooling) {
 		scripts: addedScripts
 	};
 }
-/** Add the lines a plugin needs to the app's `.gitignore` when it has one and they are missing. Returns the lines added. */
+/** What an app runs before `dev`, `start`, `test` and `check`: refuses a Node too old to run it, in plain words, before anything that would fail confusingly (a plain CommonJS file, so any Node can read it). */
+const CHECK_NODE = `// Refuses a Node that is too old to run this app, before the command that would fail on it. Plain CommonJS so that any Node can read it.
+const [major, minor] = process.versions.node.split('.').map(Number)
+if (major < 22 || (major === 22 && minor < 19)) {
+  console.error(
+    \`Node 22.19+ needed, you have \${process.versions.node}: install it from https://nodejs.org or with nvm (nvm install 22), then run this again.\`,
+  )
+  process.exit(1)
+}
+`;
+/** Write \`scripts/check-node.cjs\` and run it before the app's \`dev\`, \`start\`, \`test\` and \`check\` scripts (npm and pnpm run \`pre<script>\` first). Existing \`pre*\` scripts are kept. */
+function addNodePreflight(appDir) {
+	mkdirSync(join(appDir, "scripts"), { recursive: true });
+	writeFileSync(join(appDir, "scripts", "check-node.cjs"), CHECK_NODE);
+	const file = join(appDir, "package.json");
+	const manifest = JSON.parse(readFileSync(file, "utf8"));
+	const scripts = manifest.scripts ?? {};
+	for (const name of [
+		"dev",
+		"start",
+		"test",
+		"check"
+	]) if (name in scripts && !(`pre${name}` in scripts)) scripts[`pre${name}`] = "node scripts/check-node.cjs";
+	manifest.scripts = scripts;
+	writeFileSync(file, `${JSON.stringify(manifest, null, 2)}\n`);
+}
+/** Add the lines a plugin needs to the app's \`.gitignore\` when it has one and they are missing. Returns the lines added. */
 function appendGitignore(appDir, lines) {
 	const file = join(appDir, ".gitignore");
 	if (!lines || lines.length === 0 || !existsSync(file)) return [];
@@ -551,6 +577,7 @@ function parseInitOptions(argv) {
 		template: named ?? alias,
 		install: values.install,
 		desktop: values.desktop === true,
+		quietNext: values["no-next"] === true,
 		yes: values.yes === true
 	};
 }
@@ -565,6 +592,7 @@ const parse$3 = (argv) => parseArgs({
 		"no-agent": { type: "boolean" },
 		install: { type: "boolean" },
 		desktop: { type: "boolean" },
+		"no-next": { type: "boolean" },
 		yes: {
 			type: "boolean",
 			short: "y"
@@ -599,16 +627,19 @@ async function init(options, io) {
 		io.stderr.write(`error: ${error.message}\n`);
 		return 1;
 	}
-	const plugins = closure([...readTemplatePlugins(templateDir(template)), ...options.desktop ? ["desktop"] : []], readLibrary());
+	const own = closure(readTemplatePlugins(templateDir(template)), readLibrary());
+	const plugins = options.desktop ? closure([...own.map((plugin) => plugin.name), "desktop"], readLibrary()) : own;
+	const forDesktop = plugins.filter((plugin) => !own.some((owned) => owned.name === plugin.name));
 	for (const plugin of plugins) {
 		copyPlugin(plugin, directory);
 		if (plugin.imports) mergeImports(directory, plugin.imports, "plugins");
 		mergeDependencies(directory, plugin.dependencies);
 		mergeTooling(directory, plugin);
 	}
+	addNodePreflight(directory);
 	const desktopPath = options.desktop ? readTemplateDesktopPath(templateDir(template)) : void 0;
 	if (desktopPath !== void 0) writeDesktopPath(directory, desktopPath);
-	io.stdout.write(`created ${name} (${template}) in ${directory}: ${files.length} files, plugins ${plugins.map((plugin) => plugin.name).join(", ")}\n`);
+	io.stdout.write(`created ${name} (${template}) in ${directory}: ${files.length} files, plugins ${own.map((plugin) => plugin.name).join(", ")}${forDesktop.length > 0 ? `; the desktop shell adds ${forDesktop.map((plugin) => plugin.name).join(", ")}, which it needs` : ""}\n`);
 	if (install && await io.install(directory) !== 0) {
 		io.stderr.write("error: npm install failed; run it yourself in the new directory\n");
 		return 1;
@@ -618,10 +649,89 @@ async function init(options, io) {
 		install ? "" : "  npm install\n",
 		"  npm run dev\n  npm test\n"
 	];
-	io.stdout.write(`\nNext:\n${steps.join("")}`);
+	if (!options.quietNext) io.stdout.write(`\nNext:\n${steps.join("")}`);
 	return 0;
 }
 //#endregion
+//#region src/mount.ts
+const MOUNTED = [
+	{
+		name: "agent-panel",
+		local: "panel",
+		needs: ["agent", "extensions"]
+	},
+	{
+		name: "driver-pty",
+		local: "driverPty",
+		needs: ["agent-panel"],
+		after: "agent-panel"
+	},
+	{
+		name: "driver-acp",
+		local: "driverAcp",
+		needs: ["agent-panel"],
+		after: "agent-panel"
+	}
+];
+const ROW = /^( *)- id: ?(\S+)\n\1 {2}name: ?(\S+)\n/gmu;
+/** The `name:` of every row of the app's `blend.yaml`, or `undefined` when it has none. */
+function rowNames(appDir) {
+	const file = join(appDir, "blend.yaml");
+	if (!existsSync(file)) return void 0;
+	return [...readFileSync(file, "utf8").matchAll(ROW)].map((match) => match[3]);
+}
+/** What a plugin to be mounted is missing: the rows it needs that neither the app nor this same command brings. */
+function missingRows(appDir, plugin, alsoAdded) {
+	const have = rowNames(appDir) ?? [];
+	return plugin.needs.filter((need) => !have.includes(need) && !alsoAdded.includes(need));
+}
+/** Add the row to `blend.yaml` and the entry to `src/app.ts`; each only when it is not there yet and its place is where the template puts it. */
+function mount(appDir, plugin) {
+	const done = [];
+	const failed = [];
+	const manifestFile = join(appDir, "blend.yaml");
+	if (existsSync(manifestFile)) {
+		let text = readFileSync(manifestFile, "utf8");
+		if ([...text.matchAll(ROW)].some((match) => match[3] === plugin.name)) done.push("blend.yaml (already has the row)");
+		else {
+			const found = (plugin.after ? new RegExp(`^( *)- id: ?\\S+\\n\\1 {2}name: ?${plugin.after}\\n(?:\\1 {2}config:\\n(?:\\1 {4}.*\\n|\\1 {2}\\s*\\n)*)?`, "mu") : /^( *)- id: ?routes\n/mu).exec(text);
+			if (found) {
+				const indent = found[1];
+				const row = `${indent}- id: ${plugin.row ?? plugin.name}\n${indent}  name: ${plugin.name}\n`;
+				const at = plugin.after ? found.index + found[0].length : found.index;
+				text = text.slice(0, at) + row + text.slice(at);
+				writeFileSync(manifestFile, text);
+				done.push(`blend.yaml (row ${plugin.name})`);
+			} else failed.push(`blend.yaml: add a row \`- id: ${plugin.name}\` / \`name: ${plugin.name}\` ${plugin.after ? `after the ${plugin.after} row` : "before the `routes` row"}`);
+		}
+	}
+	const appFile = join(appDir, "src", "app.ts");
+	if (existsSync(appFile)) {
+		let text = readFileSync(appFile, "utf8");
+		const entry = `'${plugin.name}': ${plugin.local}`;
+		if (text.includes(entry)) done.push("src/app.ts (already registered)");
+		else {
+			const last = [...text.matchAll(/^import .* from '\.\.\/plugins\/[^']+'\n/gmu)].at(-1);
+			const table = /^export const registry = \{(\s)/mu.exec(text);
+			if (last && table) {
+				const file = plugin.entry ?? "index.ts";
+				const line = `import * as ${plugin.local} from '../plugins/${plugin.name}/${file}'\n`;
+				const at = table.index + table[0].length;
+				text = text.slice(0, at) + (table[1] === "\n" ? `  ${entry},\n` : `${entry}, `) + text.slice(at);
+				const lastEnd = last.index + last[0].length;
+				text = text.slice(0, lastEnd) + line + text.slice(lastEnd);
+				writeFileSync(appFile, text);
+				done.push(`src/app.ts (registered as ${plugin.local})`);
+			} else failed.push(`src/app.ts: import it as \`${plugin.local}\` from '../plugins/${plugin.name}/${plugin.entry ?? "index.ts"}' and add \`${entry}\` to the registry`);
+		}
+	} else failed.push(`src/app.ts: not found; register ${entry(plugin)} in the app's registry`);
+	return {
+		done: failed.length === 0,
+		note: [done.length > 0 ? `mounted in ${done.join(" and ")}` : "", ...failed.map((line) => `could not edit ${line}`)].filter(Boolean).join("\n")
+	};
+}
+const entry = (plugin) => `'${plugin.name}': ${plugin.local}`;
+//#endregion
 //#region src/add.ts
 /** Parse `add <plugin...> [--dir <app>] [--suite]`. */
 function parseAddOptions(argv) {
@@ -680,6 +790,14 @@ async function add(options, io) {
 		io.stderr.write(`error: the app already has ${already.map((name) => `${relative(appDir, join(pluginsFolder(appDir).dir, name)).split(sep).join("/")}`).join(", ")}\n`);
 		return 1;
 	}
+	const mounting = MOUNTED.filter((plugin) => names.includes(plugin.name));
+	for (const plugin of mounting) {
+		const missing = missingRows(appDir, plugin, names);
+		if (missing.length > 0) {
+			io.stderr.write(`error: ${plugin.name} needs the ${missing.map((row) => `\`${row}\``).join(" and ")} ${missing.length === 1 ? "row" : "rows"} in blend.yaml, and this app has ${describeRows(appDir)}. ${plugin.name === "driver-pty" ? "Add agent-panel first (acrylblends add agent-panel driver-pty), which needs the agent template. " : ""}The rows come with the agent template: start from it (npm create acrylblends@latest my-app agent) and add ${plugin.name} there. Nothing was changed.\n`);
+			return 1;
+		}
+	}
 	const toCopy = closure(names, readLibrary()).filter((plugin) => !present(appDir, plugin.name));
 	const addedDependencies = [];
 	for (const plugin of toCopy) {
@@ -698,9 +816,22 @@ async function add(options, io) {
 	}
 	io.stdout.write(`added ${toCopy.map((plugin) => plugin.name).join(", ")} to ${appDir}\n`);
 	if (addedDependencies.length > 0) io.stdout.write(`new dependencies: ${addedDependencies.join(", ")} (run npm install)\n`);
-	for (const plugin of toCopy.filter((plugin) => names.includes(plugin.name))) io.stdout.write(`\n${plugin.name}: ${plugin.mount ?? `import it from '../plugins/${plugin.name}/index.ts' and mount it in src/app.ts`}\n`);
+	for (const plugin of toCopy.filter((plugin) => names.includes(plugin.name))) {
+		const mounted = MOUNTED.find((candidate) => candidate.name === plugin.name);
+		const result = mounted ? mount(appDir, mounted) : void 0;
+		io.stdout.write(`\n${plugin.name}: ${result?.done ? `${result.note}${extraNote(mounted)}` : `${result ? `${result.note}\n` : ""}${plugin.mount ?? `import it from '../plugins/${plugin.name}/index.ts' and mount it in src/app.ts`}`}\n`);
+	}
 	return 0;
 }
+/** What an app has to say about its rows, for an error: the `name:` of each, or that it has no blend.yaml. */
+function describeRows(appDir) {
+	const rows = rowNames(appDir);
+	return rows === void 0 ? "no blend.yaml" : `the rows ${rows.join(", ") || "(none)"}`;
+}
+/** What to do after `npm install` for a plugin that needs more than the install: node-pty compiles a native module in an install script, which npm 11 and pnpm skip until approved. */
+function extraNote(plugin) {
+	return plugin?.name === "driver-pty" ? "\nnpm 11 and pnpm warn that node-pty's install script was not run, because they ask you to approve dependency install scripts. node-pty ships prebuilt binaries for macOS, Windows and Linux (x64, arm64), so you can usually ignore the warning. If the panel lists no `pty:` terminal (the app prints why at start), approve it and rebuild: `npm approve-scripts node-pty`, then `npm rebuild node-pty` (pnpm: `pnpm approve-builds`)." : "";
+}
 /**
 * The vitest the suites run on. 3.2.x, not the newest: npm 10 (the npm of Node 22) crashes on the dependency tree of vitest 4 and 5 ("Cannot read properties of null (reading
 * 'edgesOut')"), and the suites use only `describe`, `it` and `expect`, which are the same in all of them. An app on a newer npm may raise it.