acrylblends 1.4.0 → 1.5.0

package/README.md

@@ -397,10 +397,13 @@ plugins installed while the app runs, an agent that builds plugins, durable task
 secrets):
 
 ```sh
-npx acrylblends init my-app --agent -y
-cd my-app && npm install && npm run dev
+npx acrylblends@latest init my-app -y
+cd my-app && npm install && npm run dev      # the app in the ACRYL frame: chat, agents, branches, versions, Settings
+npm run desktop                               # the same in its own window
 ```
 
+`--bare` makes the plain app without the frame.
+
 See the [ACRYLBLENDS documentation](https://github.com/acrylblends/acrylblends/blob/main/docs/README.md) and
 [Acryl in a Cordis app](https://github.com/acrylblends/acrylblends/blob/main/docs/framework/cordis/acryl-in-a-cordis-app.md).
 

package/dist/index.d.ts

@@ -53,7 +53,10 @@ interface FrameUrlRecord {
   readonly pid: number;
   readonly writtenAt: string;
 }
-/** The app home the frame uses: `ACRYLBLENDS_HOME` when set, else `<app>/.acrylblends` (the launcher's own rule). */
+/**
+ * The app home the frame uses, as the app's own family chooses it (`plugins/instance`, which its launcher asks too): the CLI never keeps a second copy
+ * of that rule. A folder without the family is not a frame app.
+ */
 export declare function frameHome(appRoot: string, env?: Record<string, string | undefined>): string;
 export declare function frameUrlPath(home: string): string;
 /** The token a frame address carries, if it carries one. */
@@ -116,13 +119,13 @@ interface InitOptions {
   name: string | undefined;
   template: Template | undefined;
   install: boolean | undefined;
-  /** Also add the desktop shell (`add desktop`): an Electron window on the app's own server. */
+  /** In the ACRYL frame with the desktop shell (`add desktop`): the default; `--bare` makes a plain app. */
   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`. */
+/** Parse `init [dir] [--template t] [--agent|--no-agent] [--name n] [--install] [--bare] [-y]`. `--agent` means `--template agent`, `--no-agent` means `--template blank`. */
 export declare function parseInitOptions(argv: readonly string[]): InitOptions;
 /** Scaffold a Cordis app. Returns the exit code: 0 done, 1 refused or failed. Never overwrites anything. */
 export declare function init(options: InitOptions, io: Io): Promise<number>;
@@ -221,7 +224,7 @@ export declare function parseUpgradeOptions(argv: readonly string[]): UpgradeOpt
 /**
  * `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.
+ * under `.acryl/upgrade-backup/` first. Returns the exit code: 0 done or nothing to do, 1 refused or failed.
  */
 export declare function upgrade(options: UpgradeOptions, io: Io): Promise<number>;
 //#endregion

package/dist/index.js

@@ -18,7 +18,7 @@ var packages = {
 	},
 	"dsh-client-ui-brand-acryl": {
 		"name": "brand-client",
-		"version": "0.1.0"
+		"version": "0.1.1"
 	},
 	"acryl-app-shell": {
 		"name": "app-shell",
@@ -70,11 +70,11 @@ var packages = {
 	},
 	"acryl-versions": {
 		"name": "versions",
-		"version": "0.1.0"
+		"version": "0.1.1"
 	},
 	"acryl-blends-frame": {
 		"name": "blends-frame",
-		"version": "0.1.1"
+		"version": "0.1.2"
 	}
 };
 //#endregion
@@ -88,19 +88,17 @@ var packages = {
 */
 /** Where an app keeps its data, for the plugins that inject `appInstance` (the framework's settings service does): the slice 0 row, kept in the app. */
 const APP_INSTANCE_ROW = `// Generated by acrylblends: the app's own folder family, for the plugins that inject appInstance.
-import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { selectInstance } from '../plugins/instance/index.ts'
 
 export const name = 'app-instance'
 
 export function apply(ctx) {
   ctx.effect(() => {
-    const home = process.env.ACRYLBLENDS_HOME ?? join(process.cwd(), '.acrylblends')
-    const instance = ctx.reflect.provide('appInstance', {
-      root: process.cwd(),
-      home,
-      // The engine home ACRYL's plugins read (support serves \`dshHome/logs\`); in this host the engine and the app share one home.
-      dshHome: home,
-    })
+    // Chosen by the app's own family, as the host chose it: this folder, or the source a desktop product names. The engine home ACRYL's plugins read
+    // (support serves \`dshHome/logs\`) is the app's home.
+    const chosen = selectInstance({ projectRoot: fileURLToPath(new URL('..', import.meta.url)), env: process.env })
+    const instance = ctx.reflect.provide('appInstance', chosen)
     return () => {
       void instance()
     }
@@ -525,9 +523,22 @@ function hostScriptOf(profile, frameModule) {
 		"import { DEFAULT_SCHEMA, dump as dumpYaml, Type, load as parseYaml } from 'js-yaml'",
 		"import { Acryl } from 'acrylblends'",
 		"",
-		"const appRoot = join(dirname(fileURLToPath(import.meta.url)), '..')",
+		"// The framework's files (this launcher, the composition it reads) sit next to it; the app is chosen by the app's own family: this folder, or the",
+		"// source a desktop product names when it runs the framework from its bundle. Its home and its port come with it, decided once.",
+		"const frameworkRoot = join(dirname(fileURLToPath(import.meta.url)), '..')",
+		"const { selectInstance } = await import(new URL('../plugins/instance/index.ts', import.meta.url).href)",
+		"const chosen = selectInstance({ projectRoot: frameworkRoot, env: process.env })",
+		"const appRoot = chosen.root",
+		"const home = chosen.home",
 		`const profileName = '${profile}'`,
-		"const home = process.env.ACRYLBLENDS_HOME ?? join(appRoot, '.acrylblends')",
+		"// The page and its tab are named for the app: the package's name, as the frame's header says it, else the folder's.",
+		"const appTitle = (() => {",
+		"  try {",
+		"    const name = JSON.parse(readFileSync(join(appRoot, 'package.json'), 'utf8')).name",
+		"    if (typeof name === 'string' && name.trim() !== '') return name.trim()",
+		"  } catch {}",
+		"  return chosen.name",
+		"})()",
 		"// DSH's rows keep their files in this app's own home: set before any driver row is imported.",
 		"process.env.DSH_HOME = home",
 		"// Development only: the app's code can be loaded again in this host (a version gone back to, a file written by the chat, an agent or an editor). Every file",
@@ -543,8 +554,7 @@ function hostScriptOf(profile, frameModule) {
 		"const { boot } = await import('@deepseek-ai/dsh-app-boot')",
 		"// The frame listens where the app's own server would: the folder's stable port (or the home's, when ACRYLBLENDS_HOME pins one). A restart then",
 		"// keeps the page's origin, its auth cookie and its tabs; ACRYLBLENDS_PORT still decides, and the gates pass 0 for any free port.",
-		"const { selectInstance } = await import(new URL('../plugins/instance/index.ts', import.meta.url).href)",
-		"const port = String(selectInstance({ projectRoot: appRoot, env: process.env }).port.start)",
+		"const port = String(chosen.port.start)",
 		"const check = process.argv.includes('--check')",
 		"const require = createRequire(import.meta.url)",
 		"/** The `!!js` tag the loader evaluates: js-yaml needs the same type the Cordis include plugin declares. */",
@@ -593,7 +603,8 @@ function hostScriptOf(profile, frameModule) {
 		"  return kept",
 		"}",
 		"",
-		"const frameLayer = anchorRows(load(readFileSync(join(appRoot, 'cordis.patch.yml'), 'utf8')) ?? [], appRoot)",
+		"// The frame layer is the framework's file; its rows are anchored at the app, so the composition DSH keeps names the app's files, never the bundle's.",
+		"const frameLayer = anchorRows(load(readFileSync(join(frameworkRoot, 'cordis.patch.yml'), 'utf8')) ?? [], appRoot)",
 		"/** Our host rows first: the framework's node server, then the webServer port the driver rows register on (they are the app's, not DSH's). */",
 		`const clientRows = ${JSON.stringify(CLIENT_ROWS, null, 2).replaceAll("\\n", "\\n")}`,
 		`const agentRows = ${JSON.stringify(AGENT_PRESET_ROWS, null, 2)}`,
@@ -613,7 +624,7 @@ function hostScriptOf(profile, frameModule) {
 		"  insert: [",
 		"    { id: 'node-server', name: './plugins/acryl-node-server/src/index.ts', config: { hostname: '127.0.0.1', port: Number(port), scan: Number(port) === 0 ? 0 : 20 } },",
 		"    { id: 'web-server', name: './plugins/acryl-web-server/src/index.ts' },",
-		"    { id: 'page', name: './plugins/acryl-page/src/index.ts' },",
+		"    { id: 'page', name: './plugins/acryl-page/src/index.ts', config: { title: appTitle } },",
 		"    ...clientRows,",
 		"    ...agentRows,",
 		"  ],",
@@ -664,7 +675,7 @@ function hostScriptOf(profile, frameModule) {
 		"const layers = [compositionLayer, settingsLayer]",
 		"let ctx",
 		"try {",
-		"  ctx = await boot('" + profile + "', join(appRoot, 'cordis.yml'), layers.flat(), (hostContext) => {",
+		"  ctx = await boot('" + profile + "', join(frameworkRoot, 'cordis.yml'), layers.flat(), (hostContext) => {",
 		"    hostContext.provide('profileContext', profileContext)",
 		"  }, pathToFileURL(join(appRoot, 'package.json')).href)",
 		"} catch (error) {",
@@ -837,9 +848,10 @@ function overlayOf(packages, door = false, appRows = []) {
 	for (const entry of rows) {
 		lines.push(`    - id: ${entry.row ?? entry.name}`, `      name: ${yamlName(entry.name)}`);
 		if ((entry.row ?? entry.name) === "acryl-blends-frame") lines.push("      config:", `        appPage: ${FRAME_PAGE_PREFIX}`);
+		if ((entry.row ?? entry.name) === "acryl-router") lines.push("      config:", "        trailingSlash: ignore");
 	}
 	lines.push("- id: connection", "  inject: []", "  config:", "    trustedHosts: ['127.0.0.1']");
-	lines.push("- id: workspace-controller", "  config:", "    documentsDirectory: !!js process.env.ACRYLBLENDS_HOME ?? process.cwd() + '/.acrylblends'");
+	lines.push("- id: workspace-controller", "  config:", "    documentsDirectory: !!js process.env.DSH_HOME");
 	for (const id of [...disabled].sort()) lines.push(`- id: ${id}`, "  disabled: true");
 	return `${lines.join("\n")}\n`;
 }
@@ -1890,7 +1902,7 @@ function startRepository(directory) {
 		"Initial commit from acrylblends"
 	]);
 }
-/** Parse `init [dir] [--template t] [--agent|--no-agent] [--name n] [--install] [-y]`. `--agent` means `--template agent`, `--no-agent` means `--template blank`. */
+/** Parse `init [dir] [--template t] [--agent|--no-agent] [--name n] [--install] [--bare] [-y]`. `--agent` means `--template agent`, `--no-agent` means `--template blank`. */
 function parseInitOptions(argv) {
 	let parsed;
 	try {
@@ -1900,6 +1912,7 @@ function parseInitOptions(argv) {
 	}
 	const { values, positionals } = parsed;
 	if (positionals.length > 1) throw new UsageError("init takes at most one directory");
+	if (values.bare === true && values.desktop === true) throw new UsageError("use --bare or --desktop, not both");
 	if (values.agent && values["no-agent"]) throw new UsageError("use --agent or --no-agent, not both");
 	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(", ")})`);
@@ -1910,7 +1923,7 @@ function parseInitOptions(argv) {
 		name: values.name,
 		template: named ?? alias,
 		install: values.install,
-		desktop: values.desktop === true,
+		desktop: values.bare !== true,
 		quietNext: values["no-next"] === true,
 		yes: values.yes === true
 	};
@@ -1926,6 +1939,7 @@ const parse$3 = (argv) => parseArgs({
 		"no-agent": { type: "boolean" },
 		install: { type: "boolean" },
 		desktop: { type: "boolean" },
+		bare: { type: "boolean" },
 		"no-next": { type: "boolean" },
 		yes: {
 			type: "boolean",
@@ -2141,7 +2155,8 @@ async function add(options, io) {
 		const code = addExternal(resolve(io.cwd, folder), appDir, io);
 		if (code !== 0) return code;
 	}
-	const plain = !existsSync(join(pluginsFolder(appDir).dir, "instance"));
+	const folder = pluginsFolder(appDir).dir;
+	const plain = !existsSync(join(appDir, "blend.yaml")) && (!existsSync(join(folder, "instance")) || existsSync(join(folder, "desktop-web")));
 	if (plain && options.names.includes("db")) {
 		io.stderr.write("error: \"db\" is the Cordis plugin for a Blend app. A plain Acryl app opens its database with openDb from \"acrylblends/db/sqlite\" (see docs/framework/guides/data.md)\n");
 		return 1;
@@ -2497,7 +2512,7 @@ function checkDeps(options, io) {
 * The running frame's address, kept where the app's own data lives.
 *
 * The generated launcher prints the frame's URL with the launch token in it, and that token is the only way into a frame whose browser session ended.
-* So the address is written where the app keeps its data - `.acrylblends/`, which every scaffold's `.gitignore` already covers - at mint time,
+* So the address is written where the app keeps its data - its folder under `~/.acryl`, outside the repository - at mint time,
 * owner-only (0600 here; a restricted ACL on Windows), and atomically (a temp file in the same folder renamed over it, so a reader never sees half a
 * record). On every later boot the launcher reuses the stored token instead of minting a new one, so the address - and an open page - survives a
 * restart; `acrylblends open` prints it, and `acrylblends open --new` rotates it (the running host replaces the token in place through
@@ -2512,10 +2527,20 @@ function checkDeps(options, io) {
 const FRAME_URL_FILE = "frame-url.json";
 /** Where a running frame rotates its token: a route the launcher mounts on the frame's own router. */
 const FRAME_TOKEN_PATH = "/api/acryl-frame/token/new";
-/** The app home the frame uses: `ACRYLBLENDS_HOME` when set, else `<app>/.acrylblends` (the launcher's own rule). */
+/** Where an app keeps its own family: the instance plugin its launcher imports. */
+const familyOf = (appRoot) => join(resolve(appRoot), "plugins", "instance", "index.ts");
+/**
+* The app home the frame uses, as the app's own family chooses it (`plugins/instance`, which its launcher asks too): the CLI never keeps a second copy
+* of that rule. A folder without the family is not a frame app.
+*/
 function frameHome(appRoot, env = process.env) {
-	const pinned = env.ACRYLBLENDS_HOME?.trim();
-	return pinned === void 0 || pinned === "" ? join(resolve(appRoot), ".acrylblends") : resolve(pinned);
+	const family = familyOf(appRoot);
+	if (!existsSync(family)) throw new Error(`${appRoot} is not a frame app: it has no plugins/instance/index.ts`);
+	const { selectInstance } = createRequire(import.meta.url)(family);
+	return selectInstance({
+		projectRoot: resolve(appRoot),
+		env
+	}).home;
 }
 function frameUrlPath(home) {
 	return join(home, FRAME_URL_FILE);
@@ -2674,6 +2699,10 @@ async function openFrame(args, io) {
 		return 2;
 	}
 	const directory = resolve(io.cwd, rest[0] ?? ".");
+	if (!existsSync(familyOf(directory))) {
+		io.stderr.write(`no frame has run in ${directory}: it is not a frame app (it has no plugins/instance)\n`);
+		return 1;
+	}
 	const found = await lookUpFrameUrl(directory);
 	if (found.kind === "none") {
 		io.stderr.write(`no frame has run in ${directory} yet; start it with npm run dev\n`);
@@ -3526,7 +3555,15 @@ function planFrameStep(appDir, library, templateDirFor = templateDir) {
 		file: broken
 	};
 	const template = identifyTemplate(appDir, name);
-	if (template === void 0) return { kind: "unidentified" };
+	if (template === void 0) {
+		if (!ownsFrameRow(appDir)) return { kind: "unidentified" };
+		const specs = frameProfileForApp(appDir);
+		if (specs === void 0) return {
+			kind: "unavailable",
+			template: void 0
+		};
+		return planFrameWrites(appDir, library, name, specs, void 0, [], [], void 0);
+	}
 	if (!carriesFrame(template, templateDirFor(template))) return {
 		kind: "no-frame-template",
 		template
@@ -3567,6 +3604,18 @@ function planFrameStep(appDir, library, templateDirFor = templateDir) {
 			else conflictLines = { "src/app.ts": ownerChangeLines(current, target) };
 		}
 	}
+	return planFrameWrites(appDir, library, name, specs, template, files, kept, conflictLines);
+}
+/**
+* Whether an app built on its own carries what the frame mounts: its routes row (`src/frame.ts`), a `src/routes.ts` that says where the frame shows it, and
+* the composition the generated row calls (`composeInto` in `src/app.ts`). A registry blueprint made in the frame has all three.
+*/
+function ownsFrameRow(appDir) {
+	const at = (file) => join(appDir, "src", file);
+	return existsSync(at("frame.ts")) && existsSync(at("routes.ts")) && FRAME_PREFIX_EXPORT.test(readText(at("routes.ts"))) && existsSync(at("app.ts")) && carriesComposeInto(readText(at("app.ts")));
+}
+/** The part of the frame plan every framed app shares: the generated composition row, the host plugins, the launcher and overlay, and what conflicts. */
+function planFrameWrites(appDir, library, name, specs, template, files, kept, conflictLines) {
 	const appTs = files.find((file) => file.file === "src/app.ts")?.text ?? (existsSync(join(appDir, "src", "app.ts")) ? readText(join(appDir, "src", "app.ts")) : void 0);
 	const rows = appFrameRows(appDir, {
 		...appTs === void 0 ? {} : { appTs },
@@ -3621,7 +3670,7 @@ function frameReport(frame) {
 /**
 * `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.
+* under `.acryl/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 ?? ".");
@@ -3646,7 +3695,7 @@ async function upgrade(options, io) {
 	if (frame.kind === "planned" && frame.conflicts.length > 0 && !options.force) {
 		const own = frame.conflictLines?.["src/app.ts"] ?? [];
 		const detail = own.length === 0 ? "" : `\n  src/app.ts keeps the framework's plugin registrations; the app's own lines are ${own.map((line) => `line ${String(line.line)} (${JSON.stringify(line.text)})`).join(", ")}`;
-		io.stderr.write(`error: ${frame.conflicts.join(", ")} in ${appDir} ${frame.conflicts.length === 1 ? "is" : "are"} not the previous release's scaffold and acrylblends did not write ${frame.conflicts.length === 1 ? "it" : "them"}; nothing was changed.${detail} Move the app's version aside (or merge it into the template's) and run again, or run again with --force (the app's versions are saved under .acrylblends/upgrade-backup/ first)\n`);
+		io.stderr.write(`error: ${frame.conflicts.join(", ")} in ${appDir} ${frame.conflicts.length === 1 ? "is" : "are"} not the previous release's scaffold and acrylblends did not write ${frame.conflicts.length === 1 ? "it" : "them"}; nothing was changed.${detail} Move the app's version aside (or merge it into the template's) and run again, or run again with --force (the app's versions are saved under .acryl/upgrade-backup/ first)\n`);
 		return 1;
 	}
 	const frameChanged = frame.kind === "planned" && frame.changed;
@@ -3654,7 +3703,7 @@ async function upgrade(options, io) {
 		io.stdout.write(frame.kind === "planned" ? "nothing to upgrade: the library plugins and the frame are up to date\n" : `nothing to upgrade: the app carries no library plugins\n  ${"frame".padEnd(22)} ${frameReport(frame)}\n`);
 		return 0;
 	}
-	const scratch = join(appDir, ".acrylblends", `upgrade-${process.pid}-${Date.now()}`);
+	const scratch = join(appDir, ".acryl", `upgrade-${process.pid}-${Date.now()}`);
 	const lock = readLock(folder.dir);
 	const history = readHistory();
 	const plans = [];
@@ -3732,7 +3781,7 @@ async function upgrade(options, io) {
 			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`);
+			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 .acryl/upgrade-backup/)\n`);
 			return 1;
 		}
 		if (options.dryRun) {
@@ -3743,7 +3792,7 @@ async function upgrade(options, io) {
 			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 backup = join(appDir, ".acryl", "upgrade-backup", (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/gu, "-"));
 		const addedDependencies = [];
 		for (const plan of plans) {
 			const here = join(folder.dir, plan.plugin.name);
@@ -3843,7 +3892,8 @@ Options for init:
   --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
+  --bare                 a plain app, without the ACRYL frame (the frame, its chat and agents and npm run desktop, are the default)
+  --desktop              the frame and the desktop shell (the default; kept for older scripts)
   --install              run npm install after copying
   -y, --yes              ask nothing; use defaults (the blank template, no install)