acrylblends 0.7.8 → 0.8.1

package/dist/index.d.ts

@@ -18,8 +18,10 @@ interface Io {
 interface AddOptions {
   readonly names: readonly string[];
   readonly directory: string | undefined;
+  /** Also copy the port's conformance suite (`src/conformance.ts`) and the `vitest` it runs on: what a provider of your own must pass. */
+  readonly suite: boolean;
 }
-/** Parse `add <plugin...> [--dir <app>]`. */
+/** Parse `add <plugin...> [--dir <app>] [--suite]`. */
 export declare function parseAddOptions(argv: readonly string[]): AddOptions;
 /**
  * Copy library plugins into an existing app, with the plugins they require, and add their npm packages to its package.json.
@@ -29,9 +31,11 @@ export declare function add(options: AddOptions, io: Io): Promise<number>;
 /** `acrylblends plugins`: the library, one line per plugin. */
 export declare function listPlugins(io: Io): number;
 //#endregion
-//#region src/cli.d.ts
+//#region src/version.d.ts
 /** The version of this package. */
 export declare const VERSION: string;
+//#endregion
+//#region src/cli.d.ts
 export declare const HELP: string;
 /**
  * Run the CLI and return the exit code: 0 done, 1 failed or refused, 2 a usage error. Never calls `process.exit`.
@@ -39,8 +43,8 @@ export declare const HELP: string;
 export declare function runCli(argv: readonly string[], io?: Io): Promise<number>;
 //#endregion
 //#region src/templates.d.ts
-/** The templates: a blank Cordis app on the router, a todo list built only on the router and state, and the blank app with the offline agent. */
-export declare const TEMPLATES: readonly ["blank", "todo", "agent"];
+/** 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. */
+export declare const TEMPLATES: readonly ["nodejs", "notes", "chat", "blank", "todo", "agent"];
 type Template = (typeof TEMPLATES)[number];
 export declare function isTemplate(value: string): value is Template;
 /**
@@ -86,6 +90,10 @@ interface LibraryPlugin {
   readonly scripts?: Readonly<Record<string, string>>;
   /** Lines the app's `.gitignore` needs for this plugin (added when missing, if the app has a `.gitignore`). */
   readonly gitignore?: readonly string[];
+  /** The port's conformance suite, a path inside the plugin: shipped in the package, but copied into an app only by `acrylblends add <plugin> --suite` (it needs vitest). */
+  readonly suite?: string;
+  /** `package.json` "imports" entries the app gets (`#acryl-kv`): a path below the plugins folder. A plugin of your own imports the port by that name, in tests and the type-check as well as when installed live. */
+  readonly imports?: Readonly<Record<string, string>>;
   /** How to mount it, shown after `acrylblends add`. */
   readonly mount?: string;
   /**
@@ -118,7 +126,7 @@ export declare function nameFrom(directory: string): string;
 /** Refuse a target that exists and is not an empty directory. A missing target is fine: it is created. */
 export declare function assertTargetFree(target: string): void;
 /**
- * Copy a template into `target`, replacing `__APP_NAME__` with `name`. Checks the target before writing anything.
+ * Copy a template into `target`, replacing `__APP_NAME__` with `name` and `__ACRYLBLENDS_RANGE__` with the range of this release. Checks the target before writing anything.
  *
  * @returns the copied files, relative to `target`
  */

package/dist/index.js

@@ -1,5 +1,5 @@
 import { createRequire } from "node:module";
-import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
 import { fileURLToPath } from "node:url";
@@ -116,7 +116,7 @@ function copyPlugin(plugin, appDir, root = libraryRoot()) {
 		recursive: true,
 		filter: (path) => {
 			const inside = path.slice(source.length + 1);
-			return !(dirname(path) === source && LIBRARY_ONLY.has(inside)) && !isOmitted(inside, plugin.omit);
+			return !(dirname(path) === source && LIBRARY_ONLY.has(inside)) && !isOmitted(inside, plugin.omit) && inside.split(sep).join("/") !== plugin.suite;
 		}
 	});
 	if (!folder.legacy) recordLibraryCopy(folder.dir, plugin.name);
@@ -124,6 +124,10 @@ function copyPlugin(plugin, appDir, 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 {
@@ -148,7 +152,7 @@ function assertTargetFree(target) {
 	if (!statSync(target).isDirectory() || readdirSync(target).length > 0) throw new TargetNotEmptyError(target);
 }
 /**
-* Copy a template into `target`, replacing `__APP_NAME__` with `name`. Checks the target before writing anything.
+* Copy a template into `target`, replacing `__APP_NAME__` with `name` and `__ACRYLBLENDS_RANGE__` with the range of this release. Checks the target before writing anything.
 *
 * @returns the copied files, relative to `target`
 */
@@ -168,7 +172,7 @@ function copyTemplate(source, target, name) {
 				continue;
 			}
 			const text = readFileSync(sourcePath, "utf8");
-			if (text.includes("__APP_NAME__")) writeFileSync(targetPath, text.replaceAll("__APP_NAME__", name));
+			if (text.includes("__APP_NAME__") || text.includes("__ACRYLBLENDS_RANGE__")) writeFileSync(targetPath, text.replaceAll("__APP_NAME__", name).replaceAll("__ACRYLBLENDS_RANGE__", `^${VERSION}`));
 			else cpSync(sourcePath, targetPath);
 			written.push(`${prefix}${targetName}`);
 		}
@@ -214,6 +218,19 @@ function mergeDependencies(appDir, dependencies) {
 	writeFileSync(file, `${JSON.stringify(manifest, null, 2)}\n`);
 	return added;
 }
+/** Add `package.json` "imports" entries (`#acryl-kv`: `./plugins/acryl-kv/src/index.ts`); an entry the app already has is kept. Returns the names added. */
+function mergeImports(appDir, imports, pluginsDir) {
+	const file = join(appDir, "package.json");
+	const manifest = JSON.parse(readFileSync(file, "utf8"));
+	const current = manifest.imports ?? {};
+	const added = Object.keys(imports).filter((name) => !(name in current));
+	manifest.imports = {
+		...Object.fromEntries(Object.entries(imports).map(([name, path]) => [name, `./${pluginsDir}/${path}`])),
+		...current
+	};
+	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");
@@ -306,8 +323,11 @@ function copyFrameworkDocs(source, target) {
 }
 //#endregion
 //#region src/templates.ts
-/** The templates: a blank Cordis app on the router, a todo list built only on the router and state, and the blank app with the offline agent. */
+/** 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"
@@ -427,6 +447,7 @@ async function init(options, io) {
 	const plugins = closure([...readTemplatePlugins(templateDir(template)), ...options.desktop ? ["desktop"] : []], readLibrary());
 	for (const plugin of plugins) {
 		copyPlugin(plugin, directory);
+		if (plugin.imports) mergeImports(directory, plugin.imports, "plugins");
 		mergeDependencies(directory, plugin.dependencies);
 		mergeTooling(directory, plugin);
 	}
@@ -447,7 +468,7 @@ async function init(options, io) {
 }
 //#endregion
 //#region src/add.ts
-/** Parse `add <plugin...> [--dir <app>]`. */
+/** Parse `add <plugin...> [--dir <app>] [--suite]`. */
 function parseAddOptions(argv) {
 	let parsed;
 	try {
@@ -458,14 +479,18 @@ function parseAddOptions(argv) {
 	if (parsed.positionals.length === 0) throw new UsageError("add needs at least one plugin name (see \"acrylblends plugins\")");
 	return {
 		names: parsed.positionals,
-		directory: parsed.values.dir
+		directory: parsed.values.dir,
+		suite: parsed.values.suite === true
 	};
 }
 const parse$1 = (argv) => parseArgs({
 	args: [...argv],
 	allowPositionals: true,
 	strict: true,
-	options: { dir: { type: "string" } }
+	options: {
+		dir: { type: "string" },
+		suite: { type: "boolean" }
+	}
 });
 const present = (appDir, name) => existsSync(join(pluginsFolder(appDir).dir, name));
 /**
@@ -495,7 +520,7 @@ async function add(options, io) {
 	}
 	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));
+	const already = options.suite ? [] : names.filter((name) => present(appDir, name));
 	if (already.length > 0) {
 		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;
@@ -504,6 +529,7 @@ async function add(options, io) {
 	const addedDependencies = [];
 	for (const plugin of toCopy) {
 		copyPlugin(plugin, appDir);
+		if (plugin.imports) mergeImports(appDir, plugin.imports, relative(appDir, pluginsFolder(appDir).dir).split(sep).join("/"));
 		addedDependencies.push(...mergeDependencies(appDir, plugin.dependencies));
 		const tooling = mergeTooling(appDir, plugin);
 		appendGitignore(appDir, plugin.gitignore);
@@ -511,11 +537,45 @@ async function add(options, io) {
 		addedDependencies.push(...tooling.devDependencies);
 		if (tooling.scripts.length > 0) io.stdout.write(`new scripts: ${tooling.scripts.map((name) => `npm run ${name}`).join(", ")}\n`);
 	}
+	if (options.suite) {
+		const refused = copySuites(names, appDir, addedDependencies, io);
+		if (refused !== 0) return refused;
+	}
 	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`);
 	return 0;
 }
+/** The vitest the suites run on (the version this package is tested with). */
+const SUITE_RUNNER = { vitest: "5.0.3" };
+/**
+* Copy the conformance suite of each named port next to its source (`plugins/<name>/src/conformance.ts`), and add `vitest` to the app's development
+* dependencies. The suite is left out of a normal copy because an app that only uses a port has no use for it. Returns the exit code: 1 when a plugin has none.
+*/
+function copySuites(names, appDir, added, io) {
+	const copies = [];
+	const ports = [...new Set(names.map((name) => name.replace(/^(acryl-(?:kv|db))(?:-.*)?$/u, "$1")))];
+	const library = readLibrary();
+	for (const name of ports) {
+		const suite = library.get(name)?.suite;
+		const from = suite === void 0 ? "" : join(libraryRoot(), name, suite);
+		if (suite === void 0 || !existsSync(from)) {
+			io.stderr.write(`error: ${name} has no conformance suite (the ports db and kv do)\n`);
+			return 1;
+		}
+		copies.push({
+			from,
+			to: join(pluginsFolder(appDir).dir, name, suite)
+		});
+	}
+	for (const { from, to } of copies) {
+		mkdirSync(dirname(to), { recursive: true });
+		copyFileSync(from, to);
+		io.stdout.write(`added the conformance suite ${relative(appDir, to).split(sep).join("/")}\n`);
+	}
+	added.push(...mergeTooling(appDir, { devDependencies: SUITE_RUNNER }).devDependencies);
+	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
@@ -911,14 +971,13 @@ async function kvImport(options, io) {
 }
 //#endregion
 //#region src/cli.ts
-/** The version of this package. */
-const VERSION = createRequire(import.meta.url)("../package.json").version;
 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 plugins/
+  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 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]