acrylblends 0.7.6 → 0.7.8

package/dist/index.d.ts

@@ -102,7 +102,7 @@ export declare function libraryRoot(): string;
 export declare function readLibrary(root?: string): Map<string, LibraryPlugin>;
 /** The plugins to copy for `names`: each one after everything it requires, no duplicates. */
 export declare function closure(names: readonly string[], library: Map<string, LibraryPlugin>): LibraryPlugin[];
-/** Copy one library plugin's source into `<app>/src/plugins/<name>/`. Throws when that folder already exists. */
+/** Copy one library plugin's source into `<app>/plugins/<name>/`. Throws when that folder already exists. */
 export declare function copyPlugin(plugin: LibraryPlugin, appDir: string, root?: string): string;
 //#endregion
 //#region src/project.d.ts

package/dist/index.js

@@ -84,10 +84,33 @@ function closure(names, library) {
 	for (const name of names) visit(name, []);
 	return ordered;
 }
-/** Copy one library plugin's source into `<app>/src/plugins/<name>/`. Throws when that folder already exists. */
+/** The one folder every plugin of an app lives in, library copies and the ones an agent writes. */
+const PLUGINS_DIR = "plugins";
+/** Where apps made before 0.7.8 kept library copies; still understood for one release. */
+const LEGACY_PLUGINS_DIR = join("src", "plugins");
+/** The list of library copies in the plugins folder; the extensions plugin installs every other folder there. */
+const LIBRARY_LIST = "library.json";
+/** The plugins folder of an app: `plugins/`, or `src/plugins/` for an app that still has the old layout (and no `plugins/`). */
+function pluginsFolder(appDir) {
+	const legacy = existsSync(join(appDir, LEGACY_PLUGINS_DIR)) && !existsSync(join(appDir, "plugins"));
+	return {
+		dir: join(appDir, legacy ? LEGACY_PLUGINS_DIR : PLUGINS_DIR),
+		legacy
+	};
+}
+/** 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.";
+function recordLibraryCopy(folder, name) {
+	const file = join(folder, LIBRARY_LIST);
+	const names = existsSync(file) ? JSON.parse(readFileSync(file, "utf8")).plugins : [];
+	if (!names.includes(name)) names.push(name);
+	writeFileSync(file, `${JSON.stringify({ plugins: names.sort() }, null, 2)}\n`);
+}
+/** Copy one library plugin's source into `<app>/plugins/<name>/`. Throws when that folder already exists. */
 function copyPlugin(plugin, appDir, root = libraryRoot()) {
-	const target = join(appDir, "src", "plugins", plugin.name);
-	if (existsSync(target)) throw new LibraryError(`src/plugins/${plugin.name} already exists; remove it first to copy a fresh one`);
+	const folder = pluginsFolder(appDir);
+	const target = join(folder.dir, plugin.name);
+	if (existsSync(target)) throw new LibraryError(`${relativeName(appDir, target)} already exists; remove it first to copy a fresh one`);
 	const source = join(root, plugin.name);
 	cpSync(source, target, {
 		recursive: true,
@@ -96,8 +119,10 @@ function copyPlugin(plugin, appDir, root = libraryRoot()) {
 			return !(dirname(path) === source && LIBRARY_ONLY.has(inside)) && !isOmitted(inside, plugin.omit);
 		}
 	});
+	if (!folder.legacy) recordLibraryCopy(folder.dir, plugin.name);
 	return target;
 }
+const relativeName = (appDir, path) => path.slice(appDir.length + 1).split(sep).join("/");
 //#endregion
 //#region src/project.ts
 /** Thrown when the target directory exists and is not empty. Nothing has been written. */
@@ -159,7 +184,7 @@ function readTemplateDesktopPath(templateDir) {
 	if (!existsSync(file)) return void 0;
 	return JSON.parse(readFileSync(file, "utf8")).desktopPath;
 }
-/** Record where the desktop window opens in package.json (`acrylblends.desktopPath`), read by `src/plugins/desktop/main.ts`. */
+/** Record where the desktop window opens in package.json (`acrylblends.desktopPath`), read by `plugins/desktop/main.ts`. */
 function writeDesktopPath(appDir, path) {
 	const file = join(appDir, "package.json");
 	const manifest = JSON.parse(readFileSync(file, "utf8"));
@@ -241,9 +266,17 @@ function appendGitignore(appDir, lines) {
 function writeAgentFiles(sharedDir, templateDir, target, name) {
 	const core = readFileSync(join(sharedDir, "AGENTS.core.md"), "utf8");
 	const own = existsSync(join(templateDir, "AGENTS.md")) ? readFileSync(join(templateDir, "AGENTS.md"), "utf8") : "";
-	writeFileSync(join(target, "AGENTS.md"), `${core}${own}`.replaceAll("__APP_NAME__", name));
-	writeFileSync(join(target, "CLAUDE.md"), "@AGENTS.md\n");
-	return ["AGENTS.md", "CLAUDE.md"];
+	const text = `${core}${readFileSync(join(sharedDir, "DEFAULTS.md"), "utf8")}${own}`.replaceAll("__APP_NAME__", name);
+	writeFileSync(join(target, "AGENTS.md"), text);
+	writeFileSync(join(target, "CLAUDE.md"), text);
+	const skill = readFileSync(join(sharedDir, "SKILL.md"), "utf8").replaceAll("__APP_NAME__", name);
+	const written = ["AGENTS.md", "CLAUDE.md"];
+	for (const folder of [".claude/skills/app-guide", ".agents/skills/app-guide"]) {
+		mkdirSync(join(target, folder), { recursive: true });
+		writeFileSync(join(target, folder, "SKILL.md"), skill);
+		written.push(`${folder}/SKILL.md`);
+	}
+	return written;
 }
 /**
 * Copy the framework's docs (a generated copy of ACRYL's `docs/framework`, already checked against its digest) into `<app>/docs/framework/`,
@@ -328,7 +361,7 @@ var UsageError = class extends Error {
 function parseInitOptions(argv) {
 	let parsed;
 	try {
-		parsed = parse$1(argv);
+		parsed = parse$2(argv);
 	} catch (error) {
 		throw new UsageError(error.message);
 	}
@@ -347,7 +380,7 @@ function parseInitOptions(argv) {
 		yes: values.yes === true
 	};
 }
-const parse$1 = (argv) => parseArgs({
+const parse$2 = (argv) => parseArgs({
 	args: [...argv],
 	allowPositionals: true,
 	strict: true,
@@ -418,7 +451,7 @@ async function init(options, io) {
 function parseAddOptions(argv) {
 	let parsed;
 	try {
-		parsed = parse(argv);
+		parsed = parse$1(argv);
 	} catch (error) {
 		throw new UsageError(error.message);
 	}
@@ -428,13 +461,13 @@ function parseAddOptions(argv) {
 		directory: parsed.values.dir
 	};
 }
-const parse = (argv) => parseArgs({
+const parse$1 = (argv) => parseArgs({
 	args: [...argv],
 	allowPositionals: true,
 	strict: true,
 	options: { dir: { type: "string" } }
 });
-const present = (appDir, name) => existsSync(join(appDir, "src", "plugins", name));
+const present = (appDir, name) => existsSync(join(pluginsFolder(appDir).dir, name));
 /**
 * Copy library plugins into an existing app, with the plugins they require, and add their npm packages to its package.json.
 * Refuses a plugin the app already has. Returns the exit code.
@@ -445,21 +478,26 @@ async function add(options, io) {
 		io.stderr.write(`error: ${appDir} is not an app (no package.json and src/); run "acrylblends init" first\n`);
 		return 1;
 	}
+	if (pluginsFolder(appDir).legacy) io.stderr.write(`${LEGACY_WARNING}\n`);
 	const external = options.names.filter((name) => /[\\/]/.test(name) || name.startsWith("."));
 	for (const folder of external) {
 		const code = addExternal(resolve(io.cwd, folder), appDir, io);
 		if (code !== 0) return code;
 	}
-	const plain = !existsSync(join(appDir, "src", "plugins", "instance"));
+	const plain = !existsSync(join(pluginsFolder(appDir).dir, "instance"));
 	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;
 	}
-	const names = options.names.filter((name) => !external.includes(name)).map((name) => name === "db" ? "acryl-db-sqlite" : name).map((name) => name === "desktop" && plain ? "desktop-web" : name);
+	if (plain && options.names.includes("kv")) {
+		io.stderr.write("error: \"kv\" is the Cordis plugin for a Blend app. A plain Acryl app opens its store with openKv from \"acrylblends/kv/json\" (see docs/framework/guides/data.md#a-tiny-app-kv)\n");
+		return 1;
+	}
+	const names = options.names.filter((name) => !external.includes(name)).map((name) => name === "db" ? "acryl-db-sqlite" : name).map((name) => name === "kv" ? "acryl-kv-json" : name).map((name) => name === "desktop" && plain ? "desktop-web" : name);
 	if (names.length === 0) return 0;
 	const already = names.filter((name) => present(appDir, name));
 	if (already.length > 0) {
-		io.stderr.write(`error: the app already has ${already.map((name) => `src/plugins/${name}`).join(", ")}\n`);
+		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 toCopy = closure(names, readLibrary()).filter((plugin) => !present(appDir, plugin.name));
@@ -475,13 +513,13 @@ 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))) io.stdout.write(`\n${plugin.name}: ${plugin.mount ?? `import it from '../plugins/${plugin.name}/index.ts' and mount it in src/app.ts`}\n`);
 	return 0;
 }
 const PLUGIN_NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 /**
 * Bring an external plugin folder (a package made with the builder's package_plugin, or any folder with an index.ts that exports a
-* Cordis plugin) into the app's `extensions/`, where the extensions plugin installs it like any other: checked, staged, started,
+* Cordis plugin) into the app's `plugins/`, where the extensions plugin installs it like any other: checked, staged, started,
 * verified. Its runtime dependencies are not installed here; they are reported so the user adds them deliberately.
 */
 function addExternal(folder, appDir, io) {
@@ -504,16 +542,16 @@ function addExternal(folder, appDir, io) {
 		io.stderr.write(`error: "${name}" is not a plugin name (lowercase letters, digits and dashes)\n`);
 		return 1;
 	}
-	const target = join(appDir, "extensions", name);
+	const target = join(pluginsFolder(appDir).legacy ? join(appDir, "extensions") : join(appDir, PLUGINS_DIR), name);
 	if (existsSync(target)) {
-		io.stderr.write(`error: the app already has extensions/${name}\n`);
+		io.stderr.write(`error: the app already has ${relative(appDir, target).split(sep).join("/")}\n`);
 		return 1;
 	}
 	cpSync(folder, target, {
 		recursive: true,
 		filter: (path) => !/[\\/](node_modules|\.git)([\\/]|$)/.test(path.slice(folder.length))
 	});
-	io.stdout.write(`added external plugin ${name} to ${join(appDir, "extensions")}; it installs at the next start\n`);
+	io.stdout.write(`added external plugin ${name} to ${dirname(target)}; it installs at the next start\n`);
 	const dependencies = Object.keys(manifest.dependencies ?? {});
 	if (dependencies.length > 0) io.stdout.write(`it uses ${dependencies.join(", ")}: add them to the app with npm install first\n`);
 	return 0;
@@ -592,9 +630,14 @@ const DRIVERS = [
 const OPENERS = ["acrylblends/db/sqlite", "acryl-db-sqlite"];
 /** The desktop shell is where Electron lives (`acrylblends add desktop` copies it). */
 const ELECTRON = "electron";
-const ELECTRON_HOMES = ["src/plugins/desktop/", "src/plugins/desktop-web/"];
+const ELECTRON_HOMES = [
+	"plugins/desktop/",
+	"plugins/desktop-web/",
+	"src/plugins/desktop/",
+	"src/plugins/desktop-web/"
+];
 /** The provider plugins themselves may import what they wrap. */
-const PROVIDER_HOMES = ["src/plugins/acryl-db-sqlite/"];
+const PROVIDER_HOMES = ["plugins/acryl-db-sqlite/", "src/plugins/acryl-db-sqlite/"];
 const SOURCE = /\.(?:[cm]?[jt]s|[jt]sx)$/u;
 const SKIP_DIRS = /* @__PURE__ */ new Set([
 	"node_modules",
@@ -607,6 +650,7 @@ const ROOTS = [
 	"src",
 	"test",
 	"tests",
+	"plugins",
 	"extensions"
 ];
 const matches = (specifier, name) => specifier === name || specifier.startsWith(`${name}/`);
@@ -705,7 +749,7 @@ function findViolations(appDir) {
 }
 const GUIDE = "docs/framework/guides/data.md#why-the-database-is-opened-in-one-place";
 function advice(violation, openers) {
-	if (violation.kind === "electron") return `"${violation.specifier}" is the desktop shell's: only src/plugins/desktop (added with "acrylblends add desktop") imports electron`;
+	if (violation.kind === "electron") return `"${violation.specifier}" is the desktop shell's: only plugins/desktop (added with "acrylblends add desktop") imports electron`;
 	const where = openers.length > 0 ? openers.join(", ") : "a file named in package.json \"acryl\": { \"opener\": \"...\" }";
 	return violation.kind === "driver" ? `"${violation.specifier}" is a database driver; take a Db (import type { Db } from "acrylblends/db") as an argument and let ${where} open the database` : `"${violation.specifier}" opens a database, and only ${where} may; take a Db (import type { Db } from "acrylblends/db") as an argument`;
 }
@@ -791,6 +835,81 @@ function processIo() {
 	};
 }
 //#endregion
+//#region src/kv-import.ts
+/** Parse `kv import <kv.json> <database.sqlite> [--overwrite] [--table name] [--migrations dir]`. */
+function parseKvOptions(argv) {
+	let parsed;
+	try {
+		parsed = parse(argv);
+	} catch (error) {
+		throw new UsageError(error.message);
+	}
+	const [action, from, to, ...rest] = parsed.positionals;
+	if (action !== "import") throw new UsageError("kv takes one subcommand: kv import <kv.json> <database.sqlite>");
+	if (from === void 0 || to === void 0 || rest.length > 0) throw new UsageError("kv import takes two arguments: the JSON file and the SQLite file");
+	return {
+		from,
+		to,
+		overwrite: parsed.values.overwrite ?? false,
+		table: parsed.values.table,
+		migrations: parsed.values.migrations
+	};
+}
+const parse = (argv) => parseArgs({
+	args: [...argv],
+	allowPositionals: true,
+	strict: true,
+	options: {
+		overwrite: { type: "boolean" },
+		table: { type: "string" },
+		migrations: { type: "string" }
+	}
+});
+/** The framework as the app has it installed (so the code that reads the file is the code the app runs), else this package's own. */
+async function framework(io, subpath, own) {
+	const here = createRequire(resolve(io.cwd, "package.json"));
+	try {
+		return await import(here.resolve(`acrylblends/${subpath}`));
+	} catch {
+		return await import(new URL(`../lib/${own}`, import.meta.url).href);
+	}
+}
+/**
+* Import a JSON-file kv store into the `kv` table of an app's SQLite database: the move from `acryl-kv-json` to SQL. The file is not changed.
+* The database is opened with the app's `migrations/` folder when it has one (a database whose schema is newer than the files given is refused),
+* and the table is created when missing. Refuses to overwrite a key the table already has unless `--overwrite`.
+*/
+async function kvImport(options, io) {
+	const from = resolve(io.cwd, options.from);
+	const to = resolve(io.cwd, options.to);
+	if (!existsSync(from)) {
+		io.stderr.write(`error: ${from} does not exist\n`);
+		return 1;
+	}
+	const kvCore = await framework(io, "kv", "kv.js");
+	const json = await framework(io, "kv/json", "kv/json.js");
+	const onDb = await framework(io, "kv/db", "kv/db.js");
+	const sqlite = await framework(io, "db/sqlite", "db/sqlite.js");
+	const migrations = options.migrations !== void 0 ? resolve(io.cwd, options.migrations) : existsSync(resolve(io.cwd, "migrations")) ? resolve(io.cwd, "migrations") : void 0;
+	const source = await json.openKv({ path: from });
+	try {
+		const database = await sqlite.openDb({
+			path: to,
+			...migrations === void 0 ? {} : { migrations }
+		});
+		try {
+			const target = onDb.kvOnDb(database.db, options.table === void 0 ? {} : { table: options.table });
+			const result = await kvCore.copyKv(source.kv, target, { overwrite: options.overwrite });
+			io.stdout.write(`imported ${result.copied} ${result.copied === 1 ? "key" : "keys"} from ${options.from} into ${options.to}${options.table === void 0 ? "" : ` (table ${options.table})`}${result.overwritten > 0 ? `, ${result.overwritten} overwritten` : ""}\n`);
+			return 0;
+		} finally {
+			await database.close();
+		}
+	} finally {
+		await source.close();
+	}
+}
+//#endregion
 //#region src/cli.ts
 /** The version of this package. */
 const VERSION = createRequire(import.meta.url)("../package.json").version;
@@ -799,9 +918,10 @@ const HELP = `acrylblends ${VERSION} - scaffold Cordis apps
 Usage:
   acrylblends init [dir] [options]       Create a Cordis app in an empty or new directory
   acrylblends add <plugin...> [--dir d]  Copy library plugins (and what they require) into an app;
-                                      a folder path brings an external plugin into its extensions/
+                                      a folder path brings an external plugin into its plugins/
   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]
   acrylblends check-deps [dir]           Fail when app code imports a database driver or opener outside the file named in
                                       package.json "acryl": { "opener": "src/db.ts" } (a port is imported, a provider is not)
 
@@ -833,6 +953,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 === "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);
 		if (command === "plugins") return listPlugins(io);
 		throw new UsageError(`unknown command "${command}"`);
@@ -852,6 +973,9 @@ function parseCheckDeps(args) {
 		throw new UsageError(error.message);
 	}
 }
+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 };