crossbind 2.0.0-beta.68 → 2.0.0-beta.72

package/src/utils/bridgeTools.js

@@ -0,0 +1,71 @@
+import { execFileSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { DARWIN_CC } from './darwinToolchain.js';
+
+// On a Mac, every bridge step bound for the web image runs with @crossbind/bridge-tools, which crossbind has as an
+// optional dependency there: its SWIG in this process, and Xcode's clang reading headers as the image's em++ does. The
+// two make the same bridges, so a macOS or iOS build needs no Docker. An Android bridge is read with the NDK, in its
+// image.
+const PACKAGE = '@crossbind/bridge-tools';
+// clang reads CPATH and CPLUS_INCLUDE_PATH despite -nostdinc, so it gets only these.
+const CLANG_ENVIRONMENT = ['PATH', 'HOME', 'TMPDIR'];
+// As much as run() takes from a command.
+const OUTPUT_LIMIT = 512 * 1024 * 1024;
+const require = createRequire(import.meta.url);
+
+export const usesBridgeTools = (target, host = process.platform) => host === 'darwin' && target?.platform !== 'android';
+
+export function missingToolsMessage(error, version = require('../../package.json').version, node = process.versions.node) {
+    if (error?.code === 'MODULE_NOT_FOUND') {
+        // A package manager leaves out an optional dependency whose engines the Node it runs on does not meet.
+        const needed = Number(require('../../package.json').engines.node.match(/\d+/)[0]);
+        if (Number(node.split('.')[0]) < needed) {
+            return `crossbind: bridges on a Mac need ${PACKAGE}, which needs Node ${needed} or later, as crossbind does: under Node ${node} the package manager leaves it out. Install again with Node ${needed} or later.`;
+        }
+        return `crossbind: bridges on a Mac need ${PACKAGE}, which installs with crossbind there unless optional dependencies are left out: npm install --save-dev ${PACKAGE}@${version}`;
+    }
+    if (error?.code === 'ENOENT') {
+        return `crossbind: ${PACKAGE} has not been built in this checkout: pnpm --filter ${PACKAGE} build (needs Docker)`;
+    }
+    return `crossbind: ${PACKAGE} does not load: ${error?.message}`;
+}
+
+let loaded;
+export function loadBridgeTools() {
+    if (!loaded) {
+        try {
+            loaded = require(PACKAGE);
+        } catch (error) {
+            throw new Error(missingToolsMessage(error), { cause: error });
+        }
+    }
+    return loaded;
+}
+
+// As run() fails for a command that exits with an error: the output shown, the exit code in the cause.
+export function runSwig(args, cwd, tools = loadBridgeTools()) {
+    let result;
+    try {
+        result = tools.swig(args, { cwd });
+    } catch (error) {
+        if (error.output) console.error(error.output);
+        throw error;
+    }
+    if (result.status === 0) return;
+    if (result.output) console.error(result.output);
+    throw new Error(`crossbind: command failed (swig) with exit code ${result.status}`, { cause: { status: result.status } });
+}
+
+export const clangEnvironment = (env = process.env) => Object.fromEntries(CLANG_ENVIRONMENT.filter((key) => env[key] !== undefined).map((key) => [key, env[key]]));
+
+export function runPreprocessor(args, cwd, tools = loadBridgeTools(), exec = execFileSync) {
+    try {
+        exec(DARWIN_CC, [...tools.preprocessorArgs, ...args], {
+            cwd, env: clangEnvironment(), stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: OUTPUT_LIMIT,
+        });
+    } catch (error) {
+        if (error?.stdout?.length) console.log(error.stdout.toString());
+        if (error?.stderr?.length) console.error(error.stderr.toString());
+        throw new Error(`crossbind: command failed (clang) with exit code ${error?.status ?? 'unknown'}`, { cause: error });
+    }
+}

package/src/utils/configChanges.js

@@ -0,0 +1,30 @@
+// The changes a publisher makes to crossbind.config.js's export for the build it publishes, as JSON in the build's
+// environment: its own process reads the config again.
+export const CONFIG_CHANGES = 'CROSSBIND_CONFIG_CHANGES';
+
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+// A JSON merge patch of a value, as RFC 7386 has it: an object's keys merge into the value's, null removes a key, and
+// any other value takes the place of the one it patches.
+export function mergePatch(target, patch) {
+    if (!isObject(patch)) return patch;
+    const base = isObject(target) ? target : {};
+    return Object.fromEntries([
+        ...Object.entries(base).filter(([key]) => !Object.hasOwn(patch, key)),
+        ...Object.entries(patch).filter(([, value]) => value !== null).map(([key, value]) => [key, mergePatch(base[key], value)]),
+    ]);
+}
+
+// The changes the environment gives a build, or null for none.
+export function configChangesOf(env = process.env) {
+    const text = env[CONFIG_CHANGES];
+    if (!text) return null;
+    let changes;
+    try {
+        changes = JSON.parse(text);
+    } catch (error) {
+        throw new Error(`crossbind: ${CONFIG_CHANGES} holds no JSON: ${error.message}`, { cause: error });
+    }
+    if (!isObject(changes)) throw new Error(`crossbind: ${CONFIG_CHANGES} is no object of changes to crossbind.config.js.`);
+    return changes;
+}

package/src/utils/configWriter.js

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import path from 'node:path';
 import { parseAst } from 'rollup/parseAst';
 
 // The kinds of crossbind.config whose default export can be an object literal to write into.
@@ -12,14 +13,23 @@ const propertyOf = (object, name) => object.properties.find((property) => proper
     && (property.key.name ?? property.key.value) === name);
 // A spread may carry the key, and would win over one written before it.
 const hasSpread = (object) => object.properties.some((property) => property.type === 'SpreadElement');
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+const ESCAPES = {
+    '\\': '\\\\', "'": "\\'", '\n': '\\n', '\r': '\\r', '\t': '\\t', '\u2028': '\\u2028', '\u2029': '\\u2029',
+};
+// A string in single quotes, with what would end its line or its text escaped.
+// eslint-disable-next-line no-control-regex
+const quoted = (text) => `'${text.replace(/[\\'\u0000-\u001f\u2028\u2029]/g, (char) => ESCAPES[char] ?? `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`)}'`;
+// A key as one writes it: a name as it is, anything else quoted.
+const keyOf = (key) => (IDENTIFIER.test(key) ? key : quoted(key));
 // A value as one writes it in a config by hand: { fileTimestamp: ['C617.1'] }.
 function literal(value) {
-    if (typeof value === 'string') return `'${value.replace(/[\\']/g, '\\$&')}'`;
+    if (typeof value === 'string') return quoted(value);
     if (Array.isArray(value)) return `[${value.map(literal).join(', ')}]`;
-    if (value !== null && typeof value === 'object') return `{ ${Object.entries(value).map(([key, item]) => `${key}: ${literal(item)}`).join(', ')} }`;
+    if (value !== null && typeof value === 'object') return `{ ${Object.entries(value).map(([key, item]) => `${keyOf(key)}: ${literal(item)}`).join(', ')} }`;
     return JSON.stringify(value);
 }
-export const entry = (key, value) => `${key}: ${literal(value)}`;
+export const entry = (key, value) => `${keyOf(key)}: ${literal(value)}`;
 
 // How far an object's keys sit in from the line it opens on.
 function indentUnit(source, object) {
@@ -28,37 +38,144 @@ function indentUnit(source, object) {
     return indentOf(source, first.start).slice(indentOf(source, object.start).length) || DEFAULT_INDENT;
 }
 
-// The config's source with `key: value` first in its app section, which it makes where there is none, or null where it
-// cannot place it safely: the default export must be an object literal, its app one too, without the key or a spread.
-export function withAppOption(source, key, value) {
+// `key: value` where the rest of a key's path makes the objects the value goes in: window: { width: 800 }.
+const nestedEntry = ([key, ...rest], value) => entry(key, rest.reduceRight((inner, name) => ({ [name]: inner }), value));
+
+// The source with the entry of `keys` first in `object`, or in the object it holds under the first key, which it makes
+// where there is none, or null where it cannot place it safely: a spread in an object a key goes in may carry the key.
+function withEntry(source, { object, property }, keys, value, unit) {
+    const [key, ...rest] = keys;
+    const found = propertyOf(object, key);
+    if (found) {
+        if (rest.length === 0 || found.value.type !== 'ObjectExpression') return null;
+        return withEntry(source, { object: found.value, property: found }, rest, value, unit);
+    }
+    if (hasSpread(object)) return null;
+    const [first] = object.properties;
+    if (!first && property) {
+        const indent = indentOf(source, property.start);
+        return `${source.slice(0, object.start)}{\n${indent}${unit}${nestedEntry(keys, value)},\n${indent}}${source.slice(object.end)}`;
+    }
+    if (!first || isOneLine(source, object.start, first.start)) return insert(source, object.start + 1, ` ${nestedEntry(keys, value)},`);
+    const indent = indentOf(source, first.start);
+    if (rest.length === 0) return insert(source, object.start + 1, `\n${indent}${entry(key, value)},`);
+    // A section the object lacks opens on lines of its own, as the object writes its keys.
+    return insert(source, object.start + 1, `\n${indent}${key}: {\n${indent}${unit}${nestedEntry(rest, value)},\n${indent}},`);
+}
+
+// The config's source with the option a key's path names, as ['app', 'id'], first in the object it goes in, or null
+// where it cannot place it safely: the default export and each object on the way must be object literals, the last
+// without the key.
+export function withOption(source, keys, value) {
     const exported = parseAst(source).body.find((node) => node.type === 'ExportDefaultDeclaration')?.declaration;
     if (exported?.type !== 'ObjectExpression') return null;
-    const unit = indentUnit(source, exported);
-    const text = entry(key, value);
-    const app = propertyOf(exported, 'app');
-    if (!app) {
-        if (hasSpread(exported)) return null;
-        const [first] = exported.properties;
-        if (!first || isOneLine(source, exported.start, first.start)) return insert(source, exported.start + 1, ` app: { ${text} },`);
-        const indent = indentOf(source, first.start);
-        return insert(source, exported.start + 1, `\n${indent}app: {\n${indent}${unit}${text},\n${indent}},`);
+    return withEntry(source, { object: exported, property: null }, keys, value, indentUnit(source, exported));
+}
+
+// Every name the module's code holds, bound or read, which a name it gains must not take.
+function namesIn(node, names = new Set()) {
+    if (Array.isArray(node)) node.forEach((child) => namesIn(child, names));
+    if (typeof node?.type !== 'string') return names;
+    if (node.type === 'Identifier') names.add(node.name);
+    Object.values(node).filter((child) => child && typeof child === 'object').forEach((child) => namesIn(child, names));
+    return names;
+}
+
+const isCallOf = (identifier) => (element) => element?.type === 'CallExpression' && element.callee.type === 'Identifier'
+    && element.callee.name === identifier;
+// A hashbang and the line comments that open a module, as // @ts-check, stay first in it.
+const TOP_LINES = /^(?:#![^\n]*\n)?(?:\/\/[^\n]*\n)*/;
+
+// The name, or with Extension after it and a number after that, the first the module does not hold.
+function freeName(name, taken) {
+    for (let count = 0; ; count += 1) {
+        const candidate = count === 0 ? name : `${name}Extension${count === 1 ? '' : count}`;
+        if (!taken.has(candidate)) return candidate;
     }
-    if (app.value.type !== 'ObjectExpression' || propertyOf(app.value, key) || hasSpread(app.value)) return null;
-    const [first] = app.value.properties;
-    if (!first) {
-        const indent = indentOf(source, app.start);
-        return `${source.slice(0, app.value.start)}{\n${indent}${unit}${text},\n${indent}}${source.slice(app.value.end)}`;
+}
+
+// Where a call goes first in an extensions list, as the list writes its entries: on a line of its own where they are.
+// Where there is no list, a list of it goes first in the object.
+function listEdit(source, eol, object, list, call) {
+    if (!list) {
+        const [first] = object.properties;
+        if (!first || isOneLine(source, object.start, first.start)) return { at: object.start + 1, text: ` extensions: [${call}],` };
+        return { at: object.start + 1, text: `${eol}${indentOf(source, first.start)}extensions: [${call}],` };
     }
-    if (isOneLine(source, app.value.start, first.start)) return insert(source, app.value.start + 1, ` ${text},`);
-    return insert(source, app.value.start + 1, `\n${indentOf(source, first.start)}${text},`);
+    const [first] = list.elements;
+    if (!first) return { at: list.start + 1, text: call };
+    if (isOneLine(source, list.start, first.start)) return { at: list.start + 1, text: `${call}, ` };
+    return { at: list.start + 1, text: `${eol}${indentOf(source, first.start)}${call},` };
+}
+
+// Where the import of an extension goes: after the module's last import, else after the lines that open it.
+function importEdit(source, eol, program, identifier, specifier) {
+    const line = `import ${identifier} from ${literal(specifier)};`;
+    const last = program.body.filter((node) => node.type === 'ImportDeclaration').at(-1);
+    if (last) return { at: last.end, text: `${eol}${line}` };
+    const at = TOP_LINES.exec(source)[0].length;
+    return { at, text: /^\r?\n/.test(source.slice(at)) ? `${line}${eol}` : `${line}${eol}${eol}` };
+}
+
+// The config's source with the extension a module gives imported under name and called first in its extensions list,
+// and the name its import binds, or null where it cannot place them safely: the default export must be an object
+// literal and its extensions an array literal, without a spread after them that may carry a list of its own. A config
+// that imports the module lists it under that import, and one that lists it already stays as it is.
+export function withExtension(source, specifier, name) {
+    const program = parseAst(source);
+    const exported = program.body.find((node) => node.type === 'ExportDefaultDeclaration')?.declaration;
+    if (exported?.type !== 'ObjectExpression') return null;
+    const property = propertyOf(exported, 'extensions');
+    const isSpreadAfter = exported.properties.slice(exported.properties.indexOf(property) + 1).some((node) => node.type === 'SpreadElement');
+    if ((property && property.value.type !== 'ArrayExpression') || isSpreadAfter) return null;
+    const list = property?.value;
+    const imported = program.body.find((node) => node.type === 'ImportDeclaration' && node.source.value === specifier)
+        ?.specifiers.find((specifierNode) => specifierNode.type === 'ImportDefaultSpecifier')?.local.name;
+    const identifier = imported ?? freeName(name, namesIn(program));
+    if (list?.elements.some(isCallOf(identifier))) return { source, identifier, isListed: true };
+    const eol = source.includes('\r\n') ? '\r\n' : '\n';
+    const edits = [
+        listEdit(source, eol, exported, list, `${identifier}()`),
+        ...(imported ? [] : [importEdit(source, eol, program, identifier, specifier)]),
+    ];
+    // From the end, so each edit lands where the source had its place.
+    const changed = edits.sort((a, b) => b.at - a.at).reduce((text, edit) => insert(text, edit.at, edit.text), source);
+    return { source: changed, identifier, isListed: false };
 }
 
-// Writes `key: value` into the project's crossbind.config, and says whether it could.
-export function writeAppOption(project, key, value) {
-    const file = CONFIG_EXTENSIONS.map((extension) => `${project}/crossbind.config.${extension}`).find((candidate) => fs.existsSync(candidate));
+export const configFileOf = (project) => CONFIG_EXTENSIONS.map((extension) => path.join(project, `crossbind.config.${extension}`))
+    .find((candidate) => fs.existsSync(candidate));
+
+// Writes the extension a module gives into the project's crossbind.config, and says under which name and whether the
+// config listed it already, or null where it could not: a config the change would leave unreadable stays as it is.
+export function writeExtension(project, specifier, name) {
+    const file = configFileOf(project);
+    if (!file) return null;
+    const written = withExtension(fs.readFileSync(file, 'utf8'), specifier, name);
+    if (written === null) return null;
+    if (!written.isListed) {
+        try {
+            parseAst(written.source);
+        } catch {
+            return null;
+        }
+        fs.writeFileSync(file, written.source);
+    }
+    return { file, identifier: written.identifier, isListed: written.isListed };
+}
+
+// Writes the option a key's path names into the project's crossbind.config, and says whether it could: a config the
+// change would leave unreadable stays as it is.
+export function writeOption(project, keys, value) {
+    const file = configFileOf(project);
     if (!file) return false;
-    const changed = withAppOption(fs.readFileSync(file, 'utf8'), key, value);
+    const changed = withOption(fs.readFileSync(file, 'utf8'), keys, value);
     if (changed === null) return false;
+    try {
+        parseAst(changed);
+    } catch {
+        return false;
+    }
     fs.writeFileSync(file, changed);
     return true;
 }

package/src/utils/cppDts.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { stripComments } from './swigInterface.js';
 import writeIfChanged from './writeIfChanged.js';
-import { conanImportOfHeader, conanStageDir } from './conanImport.js';
+import { sourceImportOfHeader, sourceStageDir } from './packageSourceImport.js';
 
 // Best-effort .d.ts for `.h` imports, the C++ analog of the Rust emitDts: parse the
 // binding-rules surface (classes, public methods, primitives/string/shared_ptr), skip
@@ -256,20 +256,20 @@ function declarationsOf(headerFile, exportNames, dtsMode, log) {
 
 // Mirror the declaration under <cache>/types/<project-relative>.d.ts - never next to the
 // user's header. Package headers are skipped: their types ship with the package itself, and a
-// header staged from Conan is typed by its conan: module instead.
-export function writeHeaderDts({ headerFile, exportsFile, projectPath, cacheDir, dtsMode = 'sync', log = () => {} }) {
+// header staged from a package source is typed by its module instead, as conan:zlib/zlib.h is.
+export function writeHeaderDts({ headerFile, exportsFile, projectPath, cacheDir, sources = [], dtsMode = 'sync', log = () => {} }) {
     const relative = path.relative(projectPath, headerFile);
-    if (relative.startsWith('..') || headerFile.startsWith(`${conanStageDir(cacheDir)}/`)) return;
+    if (relative.startsWith('..') || sources.some((source) => headerFile.startsWith(`${sourceStageDir(cacheDir, source)}/`))) return;
     const exportNames = readExportNames(exportsFile, log);
     if (!exportNames) return;
     writeIfChanged(`${cacheDir}/types/${relative}.d.ts`, declarationsOf(headerFile, exportNames, dtsMode, log));
 }
 
-// A conan: specifier names no file the editor could map, so it is typed by an ambient module that
-// @crossbind/typescript-config includes. `declare` is an error inside one (TS1038).
-export function writeConanImportDts({ headerFile, exportsFile, declarationsFile = exportsFile, cacheDir, dtsMode = 'sync', log = () => {} }) {
-    const conanImport = conanImportOfHeader(headerFile, cacheDir);
-    const declared = conanImport && readExportNames(declarationsFile, log);
+// A specifier such as conan:zlib/zlib.h names no file the editor could map, so it is typed by an ambient
+// module, which @crossbind/typescript-config includes for conan. `declare` is an error inside one (TS1038).
+export function writeSourceImportDts({ headerFile, exportsFile, declarationsFile = exportsFile, cacheDir, sources = [], dtsMode = 'sync', log = () => {} }) {
+    const sourceImport = sourceImportOfHeader(headerFile, cacheDir, sources);
+    const declared = sourceImport && readExportNames(declarationsFile, log);
     if (!declared) return;
     // The bridge also binds macros and variadic functions the app imports, which the whole header's SWIG run skips.
     const exportNames = [...new Set([...declared, ...(readExportNames(exportsFile, log) ?? [])])];
@@ -279,7 +279,7 @@ export function writeConanImportDts({ headerFile, exportsFile, declarationsFile
         .map((line) => (line ? `    ${line}` : line))
         .join('\n');
     writeIfChanged(
-        `${conanStageDir(cacheDir)}/types/${conanImport.name}/${conanImport.header}.d.ts`,
-        `declare module 'conan:${conanImport.name}/${conanImport.header}' {\n${body}\n}\n`,
+        `${sourceStageDir(cacheDir, sourceImport.source)}/types/${sourceImport.name}/${sourceImport.header}.d.ts`,
+        `declare module '${sourceImport.source}:${sourceImport.name}/${sourceImport.header}' {\n${body}\n}\n`,
     );
 }

package/src/utils/extensionSteps.js

@@ -0,0 +1,172 @@
+// What a publisher, an installer, a package source and a command of an extension's give, as crossbind takes them.
+
+// A name prefixes the extension's functions and names its C++ entry, crossbind_extension_<name>.
+export const NAME = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+// The platforms a publisher takes apps of, by the command line's names, and desktop for the three of them.
+export const PUBLISH_PLATFORMS = ['android', 'ios', 'macos', 'linux', 'windows'];
+const DESKTOP_PLATFORMS = ['macos', 'linux', 'windows'];
+
+// The platforms a publisher or an installer names, one or a list of those it may, desktop for the three of them.
+function checkedPlatforms(where, platform, allowed) {
+    const named = [platform].flat();
+    if (named.length === 0 || !named.every((one) => [...allowed, 'desktop'].includes(one))) {
+        throw new Error(`crossbind: ${where}.platform is no platform or list of them, of ${[...allowed, 'desktop'].join(', ')}.`);
+    }
+    return [...new Set(named.flatMap((one) => (one === 'desktop' ? DESKTOP_PLATFORMS : [one])))];
+}
+
+// The steps an object gives are functions.
+function assertSteps(where, object, steps) {
+    const notSteps = steps.filter((step) => object[step] !== undefined && typeof object[step] !== 'function');
+    if (notSteps.length > 0) throw new Error(`crossbind: ${where}'s ${notSteps.join(' and ')} ${notSteps.length > 1 ? 'are' : 'is'} no function.`);
+}
+const PUBLISHER_KEYS = ['platform', 'isDefault', 'store', 'options', 'after', 'build', 'check', 'buildNumber', 'buildEnv', 'upload'];
+const PUBLISHER_STEPS = ['build', 'check', 'buildNumber', 'buildEnv', 'upload'];
+// The steps of a publisher that builds, which one after another publisher leaves to that one.
+const BUILD_STEPS = ['build', 'buildNumber', 'buildEnv'];
+// The options `crossbind app publish` has of its own, with crossbind's, and those `vite build` takes, which the command
+// line hands Vite: no publisher's takes the name of one.
+const COMMAND_OPTIONS = ['platform', 'help', 'version'];
+const VITE_OPTIONS = [
+    'app', 'assetsDir', 'assetsInlineLimit', 'base', 'clearScreen', 'config', 'configLoader', 'debug', 'emptyOutDir', 'filter',
+    'logLevel', 'manifest', 'minify', 'mode', 'outDir', 'profile', 'sourcemap', 'ssr', 'ssrManifest', 'target', 'watch',
+];
+// An option's name, as JavaScript writes it, whose --kebab-case the command line takes.
+const OPTION_NAME = /^[a-z][a-zA-Z0-9]*$/;
+const OPTION_KEYS = ['help', 'value', 'default'];
+
+// An option as the command line takes it, which is a flag or takes a value.
+function checkedOption(where, name, option) {
+    const at = `${where}.options.${name}`;
+    if (!OPTION_NAME.test(name) || COMMAND_OPTIONS.includes(name)) {
+        throw new Error(`crossbind: ${where}.options names ${name}, which is no option of its own: one of letters and digits, starting with a lowercase letter, but ${COMMAND_OPTIONS.slice(0, -1).join(', ')} and ${COMMAND_OPTIONS.at(-1)}.`);
+    }
+    if (!isObject(option) || typeof option.help !== 'string') throw new Error(`crossbind: ${at} is no option, which is { help } for a flag and { help, value } for one that takes a value.`);
+    const unknown = Object.keys(option).find((key) => !OPTION_KEYS.includes(key));
+    if (unknown) throw new Error(`crossbind: ${at} takes ${OPTION_KEYS.join(', ')}; ${unknown} is none of them.`);
+    if (option.value !== undefined && typeof option.value !== 'string') throw new Error(`crossbind: ${at}.value is no name of the value it takes, as '<track>'.`);
+    if (option.default !== undefined && (option.value === undefined || typeof option.default !== 'string')) {
+        throw new Error(`crossbind: ${at}.default is no value of an option that takes one: a string, beside its value.`);
+    }
+    return { help: option.help, value: option.value ?? null, default: option.default ?? null };
+}
+
+// A publisher's option, which takes no name of an option of the Vite build its publish runs.
+function checkedPublishOption(where, name, option) {
+    if (VITE_OPTIONS.includes(name)) {
+        throw new Error(`crossbind: ${where}.options names ${name}, which is an option of the Vite build the publish runs, the command line's --${name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}: name it otherwise.`);
+    }
+    return checkedOption(where, name, option);
+}
+
+// A publisher as crossbind runs it: the platforms it takes apps of, whether a publish of those platforms that names no
+// store goes to it, the name its store goes by, the options it takes on the command line, the publisher it comes after, where it does, and its steps, which keep the object as their this.
+export function checkedPublisher(publisher, where) {
+    if (!isObject(publisher)) throw new Error(`crossbind: ${where} is no object.`);
+    const unknown = Object.keys(publisher).find((key) => !PUBLISHER_KEYS.includes(key));
+    if (unknown) throw new Error(`crossbind: ${where} takes ${PUBLISHER_KEYS.join(', ')}; ${unknown} is none of them.`);
+    const platforms = checkedPlatforms(where, publisher.platform, PUBLISH_PLATFORMS);
+    if (publisher.isDefault !== undefined && typeof publisher.isDefault !== 'boolean') throw new Error(`crossbind: ${where}.isDefault is no boolean.`);
+    if (publisher.store !== undefined && typeof publisher.store !== 'string') throw new Error(`crossbind: ${where}.store is no name.`);
+    if (publisher.after !== undefined && (typeof publisher.after !== 'string' || !NAME.test(publisher.after))) {
+        throw new Error(`crossbind: ${where}.after is no name of a publisher.`);
+    }
+    assertSteps(where, publisher, PUBLISHER_STEPS);
+    if (!publisher.upload) throw new Error(`crossbind: ${where} has no upload, the step that sends the app to its store.`);
+    const ownBuild = BUILD_STEPS.filter((step) => publisher[step]);
+    if (publisher.after !== undefined && ownBuild.length > 0) {
+        throw new Error(`crossbind: ${where} comes after ${publisher.after}, whose build it publishes from, so it takes no ${ownBuild.join(' or ')}.`);
+    }
+    const options = publisher.options ?? {};
+    if (!isObject(options)) throw new Error(`crossbind: ${where}.options is no object of options.`);
+    const steps = PUBLISHER_STEPS.filter((step) => publisher[step]).map((step) => [step, publisher[step].bind(publisher)]);
+    return {
+        platforms,
+        ...(publisher.isDefault ? { isDefault: true } : {}),
+        store: publisher.store ?? null,
+        options: Object.fromEntries(Object.entries(options).map(([name, option]) => [name, checkedPublishOption(where, name, option)])),
+        after: publisher.after ?? null,
+        ...Object.fromEntries(steps),
+    };
+}
+
+const INSTALLER_STEPS = ['check', 'make'];
+const INSTALLER_KEYS = ['platform', 'isLast', 'licenses', ...INSTALLER_STEPS];
+
+// An installer as crossbind runs it: the desktop platforms whose apps it makes what installs, whether it runs after the
+// others, whatever app.installers names, and its steps, which keep the object as their this.
+export function checkedInstaller(installer, where) {
+    if (!isObject(installer)) throw new Error(`crossbind: ${where} is no object.`);
+    const unknown = Object.keys(installer).find((key) => !INSTALLER_KEYS.includes(key));
+    if (unknown) throw new Error(`crossbind: ${where} takes ${INSTALLER_KEYS.join(', ')}; ${unknown} is none of them.`);
+    const platforms = checkedPlatforms(where, installer.platform, DESKTOP_PLATFORMS);
+    if (installer.isLast !== undefined && typeof installer.isLast !== 'boolean') throw new Error(`crossbind: ${where}.isLast is no boolean.`);
+    assertSteps(where, installer, INSTALLER_STEPS);
+    if (!installer.make) throw new Error(`crossbind: ${where} has no make, the step that makes what installs the app.`);
+    const steps = INSTALLER_STEPS.filter((step) => installer[step]).map((step) => [step, installer[step].bind(installer)]);
+    return { platforms, ...(installer.isLast ? { isLast: true } : {}), ...Object.fromEntries(steps) };
+}
+
+const PACKAGE_SOURCE_STEPS = ['check', 'inputs', 'install'];
+const PACKAGE_SOURCE_KEYS = ['storeUnits', ...PACKAGE_SOURCE_STEPS];
+// A package source's name starts its imports, its key in crossbind.config.js and its folders beside crossbind's own:
+// one word, and none that means something there already: an import scheme of a bundler or a runtime, a folder of
+// crossbind's, or a device's name, which Windows gives no folder.
+const SOURCE_NAME = /^[a-z][a-z0-9]*$/;
+const KEPT_SOURCE_NAMES = [
+    'cargo', 'node', 'file', 'data', 'http', 'https', 'npm', 'virtual', 'blob', 'bun', 'deno', 'jsr', 'cloudflare', 'workerd',
+    'all', 'android', 'build', 'config', 'deps', 'hermes', 'keys', 'secrets', 'sysroots', 'types',
+    'con', 'prn', 'aux', 'nul',
+];
+const STORE_SEGMENT = /^[A-Za-z0-9_-][A-Za-z0-9_.-]*$/;
+// Folders of a source's store that never change once written, as p/*/p names one in each folder of p.
+const isStoreUnit = (unit) => typeof unit === 'string'
+    && unit.split('/').every((segment) => segment === '*' || STORE_SEGMENT.test(segment))
+    && unit.split('/').includes('*');
+
+// A package source as crossbind runs it, under its extension's name: the folders of its store a remote runner sends
+// back, and its steps, which keep the object as their this.
+export function checkedPackageSource(packageSource, where, name) {
+    if (!isObject(packageSource)) throw new Error(`crossbind: ${where} is no object.`);
+    const unknown = Object.keys(packageSource).find((key) => !PACKAGE_SOURCE_KEYS.includes(key));
+    if (unknown) throw new Error(`crossbind: ${where} takes ${PACKAGE_SOURCE_KEYS.join(', ')}; ${unknown} is none of them.`);
+    if (!SOURCE_NAME.test(name) || KEPT_SOURCE_NAMES.includes(name)) {
+        throw new Error(`crossbind: ${where} makes ${name} the name of a package source, which starts its imports, as ${name}:<package>/<header>: one word of lowercase letters and digits, and none of ${KEPT_SOURCE_NAMES.join(', ')}.`);
+    }
+    const storeUnits = packageSource.storeUnits ?? [];
+    if (!Array.isArray(storeUnits) || !storeUnits.every(isStoreUnit)) {
+        throw new Error(`crossbind: ${where}.storeUnits is no list of the folders of its store that never change once written, each a path with a * for a folder's name, as 'p/*/p'.`);
+    }
+    assertSteps(where, packageSource, PACKAGE_SOURCE_STEPS);
+    if (!packageSource.check) throw new Error(`crossbind: ${where} has no check, the step that takes the project's packages.${name}.`);
+    if (!packageSource.install) throw new Error(`crossbind: ${where} has no install, the step that installs a target's packages.`);
+    const steps = PACKAGE_SOURCE_STEPS.filter((step) => packageSource[step]).map((step) => [step, packageSource[step].bind(packageSource)]);
+    return { storeUnits: [...storeUnits], ...Object.fromEntries(steps) };
+}
+
+const COMMAND_KEYS = ['help', 'options', 'run'];
+
+// The commands an extension adds under crossbind app, by their names: each its line of help, the options it takes, as a
+// publisher's, and the step that does its work, which keeps the object as its this.
+export function checkedCommands(commands, where) {
+    if (!isObject(commands)) throw new Error(`crossbind: ${where} is no object of commands, as { 'my-key': { help, run } }.`);
+    return Object.fromEntries(Object.entries(commands).map(([name, command]) => {
+        const at = `${where}.${name}`;
+        if (!NAME.test(name)) throw new Error(`crossbind: ${where} names ${name}, which is no command of lowercase letters and digits, which dashes may join.`);
+        if (!isObject(command)) throw new Error(`crossbind: ${at} is no command, which is { help, run }.`);
+        const unknown = Object.keys(command).find((key) => !COMMAND_KEYS.includes(key));
+        if (unknown) throw new Error(`crossbind: ${at} takes ${COMMAND_KEYS.join(', ')}; ${unknown} is none of them.`);
+        if (typeof command.help !== 'string' || command.help === '') throw new Error(`crossbind: ${at} has no help, its line in crossbind app --help.`);
+        if (typeof command.run !== 'function') throw new Error(`crossbind: ${at} has no run, the step that does its work.`);
+        const options = command.options ?? {};
+        if (!isObject(options)) throw new Error(`crossbind: ${at}.options is no object of options.`);
+        return [name, {
+            help: command.help,
+            options: Object.fromEntries(Object.entries(options).map(([option, value]) => [option, checkedOption(at, option, value)])),
+            run: command.run.bind(command),
+        }];
+    }));
+}

package/src/utils/nativeImports.js

@@ -11,9 +11,16 @@ export function findImportSpecifiers(text) {
 
 export const nativeExtensions = ({ header, module }) => [...header, ...module, 'rs'];
 
-export const nativeSpecifierTest = (ext) => {
+// Whether a specifier opens with one of the schemes an import names a store by, as cargo: and conan: are.
+export const schemeTest = (schemes) => {
+    const scheme = new RegExp(`^(${schemes.join('|')}):`);
+    return (specifier) => scheme.test(specifier);
+};
+
+export const nativeSpecifierTest = (ext, schemes) => {
     const extension = new RegExp(`\\.(${nativeExtensions(ext).join('|')})$`);
-    return (specifier) => /^(cargo|conan):/.test(specifier) || extension.test(specifier);
+    const hasScheme = schemeTest(schemes);
+    return (specifier) => hasScheme(specifier) || extension.test(specifier);
 };
 
 export function findNativeImportsIn(projectDir, isNative) {

package/src/utils/nodeDevBuild.js

@@ -6,6 +6,7 @@ import loadJson from './loadJson.js';
 import { computeInputStamp } from './inputStamp.js';
 import { findHeaderImportsIn } from './headerImports.js';
 import { findNativeImportsIn, nativeSpecifierTest } from './nativeImports.js';
+import { importSchemesOf } from './packageSources.js';
 
 // Set on the build a dev start runs: that build is a Node process too, which NODE_OPTIONS may hand the dev hooks again.
 export const DEV_BUILD_ENV = 'CROSSBIND_DEV_BUILD';
@@ -49,7 +50,7 @@ export function devFormatOf(project) {
 export function nativeInputsFingerprint(config) {
     const { project, native, header, module: modules } = config.paths;
     const relativeTo = (importer) => upath.relative(project, importer);
-    const imports = findNativeImportsIn(project, nativeSpecifierTest(config.ext))
+    const imports = findNativeImportsIn(project, nativeSpecifierTest(config.ext, importSchemesOf(config)))
         .map(({ importer, specifier }) => ({ importer: relativeTo(importer), specifier }));
     const names = findHeaderImportsIn(project, config.ext.header)
         .map(({ importer, specifier, names: taken }) => JSON.stringify([relativeTo(importer), specifier, taken]));

package/src/utils/openUrl.js

@@ -1,6 +1,7 @@
 import { spawn } from 'node:child_process';
 
-const OPENERS = { darwin: ['open'], win32: ['cmd', '/c', 'start', '""'] };
+// Windows opens it without a shell, whose & would end the command inside the address.
+const OPENERS = { darwin: ['open'], win32: ['rundll32', 'url.dll,FileProtocolHandler'] };
 
 // Opens an address in the user's browser where the system can; whoever calls it prints the address too.
 export default function openUrl(url) {