acrylblends 0.7.5 → 0.7.7

package/dist/index.js

@@ -189,6 +189,19 @@ function mergeDependencies(appDir, dependencies) {
 	writeFileSync(file, `${JSON.stringify(manifest, null, 2)}\n`);
 	return added;
 }
+/** Declare a file as an opener in package.json (`"acryl": { "opener": [...] }`): the one place that may import a database provider. */
+function mergeOpener(appDir, opener) {
+	const file = join(appDir, "package.json");
+	const manifest = JSON.parse(readFileSync(file, "utf8"));
+	const current = manifest.acryl?.opener;
+	const list = typeof current === "string" ? [current] : current ?? [];
+	if (list.includes(opener)) return;
+	manifest.acryl = {
+		...manifest.acryl,
+		opener: [...list, opener]
+	};
+	writeFileSync(file, `${JSON.stringify(manifest, null, 2)}\n`);
+}
 /**
 * Add a plugin's development dependencies and scripts to an app's package.json: nothing the app already has is replaced. Returns the names of the development dependencies
 * and scripts added.
@@ -315,7 +328,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);
 	}
@@ -334,7 +347,7 @@ function parseInitOptions(argv) {
 		yes: values.yes === true
 	};
 }
-const parse$1 = (argv) => parseArgs({
+const parse$2 = (argv) => parseArgs({
 	args: [...argv],
 	allowPositionals: true,
 	strict: true,
@@ -405,7 +418,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);
 	}
@@ -415,7 +428,7 @@ function parseAddOptions(argv) {
 		directory: parsed.values.dir
 	};
 }
-const parse = (argv) => parseArgs({
+const parse$1 = (argv) => parseArgs({
 	args: [...argv],
 	allowPositionals: true,
 	strict: true,
@@ -442,7 +455,11 @@ async function add(options, io) {
 		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) {
@@ -456,6 +473,7 @@ async function add(options, io) {
 		addedDependencies.push(...mergeDependencies(appDir, plugin.dependencies));
 		const tooling = mergeTooling(appDir, plugin);
 		appendGitignore(appDir, plugin.gitignore);
+		if (plugin.name === "acryl-db-sqlite") mergeOpener(appDir, "src/app.ts");
 		addedDependencies.push(...tooling.devDependencies);
 		if (tooling.scripts.length > 0) io.stdout.write(`new scripts: ${tooling.scripts.map((name) => `npm run ${name}`).join(", ")}\n`);
 	}
@@ -551,6 +569,170 @@ async function buildClient(options, io) {
 	return 0;
 }
 //#endregion
+//#region src/check-deps.ts
+/**
+* The dependency rule (spec 049): app code imports a port, never a provider. A port is `acrylblends/db` (the `Db` type); a provider is a
+* driver or the one function that opens a database. Only the opener, a file the app names once in package.json, may import a provider.
+*/
+/** A package that is a database driver. An import of it, or of anything below it, is a provider import. */
+const DRIVERS = [
+	"node:sqlite",
+	"sqlite",
+	"sqlite3",
+	"better-sqlite3",
+	"@libsql/client",
+	"libsql",
+	"pg",
+	"pg-pool",
+	"pg-native",
+	"postgres",
+	"@electric-sql/pglite",
+	"@neondatabase/serverless",
+	"@vercel/postgres",
+	"mysql",
+	"mysql2"
+];
+/** The openers a provider ships: importing one of them is opening a database. */
+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/"];
+/** The provider plugins themselves may import what they wrap. */
+const PROVIDER_HOMES = ["src/plugins/acryl-db-sqlite/"];
+const SOURCE = /\.(?:[cm]?[jt]s|[jt]sx)$/u;
+const SKIP_DIRS = /* @__PURE__ */ new Set([
+	"node_modules",
+	"dist",
+	"lib",
+	"build",
+	"coverage"
+]);
+const ROOTS = [
+	"src",
+	"test",
+	"tests",
+	"extensions"
+];
+const matches = (specifier, name) => specifier === name || specifier.startsWith(`${name}/`);
+/** What a specifier is to the rule, or undefined when it is not a provider. */
+function classifySpecifier(specifier) {
+	if (DRIVERS.some((name) => matches(specifier, name))) return "driver";
+	if (OPENERS.some((name) => matches(specifier, name))) return "opener";
+	if (matches(specifier, ELECTRON)) return "electron";
+}
+/** The source with every comment replaced by spaces (newlines kept), so a line number still means what it did and a commented import is not an import. */
+function blankComments(source) {
+	let out = "";
+	let i = 0;
+	while (i < source.length) {
+		const c = source[i];
+		const next = source[i + 1];
+		if (c === "/" && next === "/") {
+			const end = source.indexOf("\n", i);
+			const stop = end === -1 ? source.length : end;
+			out += " ".repeat(stop - i);
+			i = stop;
+		} else if (c === "/" && next === "*") {
+			const end = source.indexOf("*/", i + 2);
+			const stop = end === -1 ? source.length : end + 2;
+			out += source.slice(i, stop).replace(/[^\n]/gu, " ");
+			i = stop;
+		} else if (c === "'" || c === "\"" || c === "`") {
+			let j = i + 1;
+			while (j < source.length && source[j] !== c) {
+				if (source[j] === "\\") j += 1;
+				else if (c !== "`" && source[j] === "\n") break;
+				j += 1;
+			}
+			out += source.slice(i, Math.min(j + 1, source.length));
+			i = j + 1;
+		} else {
+			out += c;
+			i += 1;
+		}
+	}
+	return out;
+}
+/** `import x from 'a'`, `export * from 'a'`, `import 'a'`, `import('a')` and `require('a')`, with the line of each. */
+const IMPORT = /(?:^|[\s;{}()])(?:import\s*(?:type\s+)?(?:[\w*${},\s]*?\s*from\s*)?|export\s*(?:type\s+)?[\w*${},\s]*?\s*from\s*|import\s*\(\s*|require\s*\(\s*)(['"])([^'"\n]+)\1/gu;
+function importsOf(source) {
+	const code = blankComments(source);
+	const found = [];
+	for (const match of code.matchAll(IMPORT)) {
+		const specifier = match[2];
+		const at = (match.index ?? 0) + match[0].length - specifier.length - 2;
+		found.push({
+			specifier,
+			line: code.slice(0, at).split("\n").length
+		});
+	}
+	return found;
+}
+function listSources(dir, out = []) {
+	if (!existsSync(dir)) return out;
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		if (entry.name.startsWith(".") || SKIP_DIRS.has(entry.name)) continue;
+		const path = join(dir, entry.name);
+		if (entry.isDirectory()) listSources(path, out);
+		else if (SOURCE.test(entry.name) && !entry.name.endsWith(".d.ts")) out.push(path);
+	}
+	return out;
+}
+/** The opener files the app declares: `"acryl": { "opener": "src/db.ts" }` (or a list) in package.json. */
+function openersOf(appDir) {
+	const file = join(appDir, "package.json");
+	if (!existsSync(file)) return [];
+	const declared = JSON.parse(readFileSync(file, "utf8")).acryl?.opener;
+	return (typeof declared === "string" ? [declared] : Array.isArray(declared) ? declared : []).filter((entry) => typeof entry === "string");
+}
+/** Every provider import outside the declared opener (and the homes that may hold one), in file and line order. */
+function findViolations(appDir) {
+	const openers = new Set(openersOf(appDir).map((entry) => entry.split(sep).join("/")));
+	const violations = [];
+	for (const root of ROOTS) for (const path of listSources(join(appDir, root)).sort()) {
+		const file = relative(appDir, path).split(sep).join("/");
+		if (openers.has(file)) continue;
+		for (const { specifier, line } of importsOf(readFileSync(path, "utf8"))) {
+			const kind = classifySpecifier(specifier);
+			if (kind === void 0) continue;
+			if (kind === "electron" && ELECTRON_HOMES.some((home) => file.startsWith(home))) continue;
+			if (kind !== "electron" && PROVIDER_HOMES.some((home) => file.startsWith(home))) continue;
+			violations.push({
+				file,
+				line,
+				specifier,
+				kind
+			});
+		}
+	}
+	return violations;
+}
+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`;
+	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`;
+}
+/** Parse `check-deps [dir]`. */
+function parseCheckDepsOptions(argv) {
+	const args = argv.filter((a) => !a.startsWith("-"));
+	if (args.length !== argv.length || args.length > 1) throw new Error("check-deps takes at most one argument: the app folder");
+	return { directory: args[0] };
+}
+/** Report each provider import outside the opener, as `file:line: why`. Returns the exit code: 1 when there is one. */
+function checkDeps(options, io) {
+	const appDir = resolve(io.cwd, options.directory ?? ".");
+	const violations = findViolations(appDir);
+	if (violations.length === 0) {
+		io.stdout.write("check-deps: no app code imports a database provider outside the opener\n");
+		return 0;
+	}
+	const openers = openersOf(appDir);
+	for (const violation of violations) io.stderr.write(`${violation.file}:${violation.line}: ${advice(violation, openers)}\n`);
+	io.stderr.write(`See ${GUIDE}\n`);
+	return 1;
+}
+//#endregion
 //#region src/spawn.ts
 /**
 * How to start a package manager without the shell option (Node warns about passing args to a shell, DEP0190, and a `.cmd` shim cannot be spawned directly).
@@ -613,6 +795,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;
@@ -624,6 +881,9 @@ Usage:
                                       a folder path brings an external plugin into its extensions/
   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)
 
 Options for init:
   --template <name>      blank or agent (asked when not given); --agent means --template agent,
@@ -653,6 +913,8 @@ 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}"`);
 	} catch (error) {
@@ -664,6 +926,16 @@ async function runCli(argv, io = processIo()) {
 		return 1;
 	}
 }
+function parseCheckDeps(args) {
+	try {
+		return parseCheckDepsOptions(args);
+	} catch (error) {
+		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 };