crossbind 2.0.0-beta.67 → 2.0.0-beta.69

package/src/utils/appTargets.js

@@ -0,0 +1,168 @@
+import { IOS_DEPLOYMENT_TARGET } from './iosToolchain.js';
+
+// Apple's app extensions an iOS app's extensions add, each a target of the app's Xcode project of its own, by their
+// kinds: the extension point each runs at, which an other target names itself, the options it needs or may give, and
+// the frameworks iOS starts it with, which its code may name nothing of, so that the linker would leave them out.
+const KINDS = {
+    widget: { point: 'com.apple.widgetkit-extension', needs: [], takes: [] },
+    share: { point: 'com.apple.share-services', needs: ['principalClass', 'activation'], takes: [] },
+    'notification-service': { point: 'com.apple.usernotifications.service', needs: ['principalClass'], takes: [] },
+    'notification-content': {
+        point: 'com.apple.usernotifications.content-extension', needs: ['principalClass', 'categories'], takes: [], frameworks: ['UserNotifications', 'UserNotificationsUI'],
+    },
+    other: { point: null, needs: ['extensionPoint'], takes: ['principalClass'] },
+};
+
+// The frameworks a target links: its kind's, and its own.
+export const targetFrameworks = (target) => [...new Set([...(KINDS[target.kind].frameworks ?? []), ...(target.frameworks ?? [])])];
+
+// The widget targets whose Swift names no containerBackground, through which iOS 17 asks a widget's view for its
+// background: a debug build draws "Please adopt containerBackground API" in place of one without it. read(target, file)
+// gives a source's text.
+export const widgetsWithoutBackground = (targets, read) => targets
+    .filter((target) => target.kind === 'widget')
+    .filter((target) => !target.sources.some((file) => file.endsWith('.swift') && read(target, file).includes('containerBackground')))
+    .map((target) => target.name);
+const KIND_KEYS = ['principalClass', 'activation', 'categories', 'extensionPoint'];
+const TARGET_KEYS = ['name', 'kind', 'sources', 'resources', 'displayName', 'plist', 'entitlements', 'frameworks', 'privacy', 'appGroup',
+    'deploymentTarget', ...KIND_KEYS, 'attributes'];
+const NEEDED = {
+    principalClass: 'the class iOS makes as it starts the target',
+    activation: "what of the share sheet's items it takes, as { images: 10 }",
+    categories: 'the notification categories it shows',
+    extensionPoint: 'the extension point iOS runs it at, as com.apple.keyboard-service',
+};
+// What of the share sheet's items a share extension takes, by the keys of Apple's activation rule: a count of each kind,
+// and text or none.
+const ACTIVATION = {
+    attachments: 'NSExtensionActivationSupportsAttachmentsWithMaxCount',
+    files: 'NSExtensionActivationSupportsFileWithMaxCount',
+    images: 'NSExtensionActivationSupportsImageWithMaxCount',
+    movies: 'NSExtensionActivationSupportsMovieWithMaxCount',
+    text: 'NSExtensionActivationSupportsText',
+    urls: 'NSExtensionActivationSupportsWebURLWithMaxCount',
+    webPages: 'NSExtensionActivationSupportsWebPageWithMaxCount',
+};
+// The attributes crossbind writes from a target's options, and the Info.plist keys it writes for every target, the App
+// Group, which the target's code reads, of one that asks for it.
+const WRITTEN_ATTRIBUTES = { NSExtensionActivationRule: 'activation', UNNotificationExtensionCategory: 'categories' };
+const APP_GROUP_KEY = 'CrossbindAppGroup';
+const WRITTEN_KEYS = ['CFBundleDevelopmentRegion', 'CFBundleDisplayName', 'CFBundleExecutable', 'CFBundleIdentifier', 'CFBundleInfoDictionaryVersion',
+    'CFBundleName', 'CFBundlePackageType', 'CFBundleShortVersionString', 'CFBundleVersion', 'NSExtension', APP_GROUP_KEY];
+
+const NAME = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const CLASS = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const EXTENSION_POINT = /^[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)+$/;
+const VERSION = /^\d+\.\d+$/;
+// ExtensionKit's points, whose extensions are of another product, in the app's Extensions, which crossbind makes none of.
+const EXTENSION_KIT_POINTS = ['com.apple.appintents-extension'];
+// What a target compiles apart from its headers, and the sources of Objective-C, beside which a class goes by its own name.
+export const isHeader = (file) => /\.(h|hpp)$/.test(file);
+const isObjectiveC = (file) => /\.(m|mm)$/.test(file);
+const kindOf = (kind) => `${/^[aeiou]/.test(kind) ? 'an' : 'a'} ${kind} target`;
+
+const isBelow = (version, floor) => {
+    const [major, minor] = version.split('.').map(Number);
+    const [floorMajor, floorMinor] = floor.split('.').map(Number);
+    return major < floorMajor || (major === floorMajor && minor < floorMinor);
+};
+
+// A target's name and kind, of the keys a target takes alone.
+export function checkedTargetKind(at, target) {
+    const unknown = Object.keys(target).find((key) => !TARGET_KEYS.includes(key));
+    if (unknown) throw new Error(`crossbind: ${at} takes ${TARGET_KEYS.join(', ')}; ${unknown} is none of them.`);
+    if (typeof target.name !== 'string' || !NAME.test(target.name)) {
+        throw new Error(`crossbind: ${at}.name ${JSON.stringify(target.name)} is no name of lowercase letters and digits, which dashes may join.`);
+    }
+    if (!Object.hasOwn(KINDS, target.kind)) throw new Error(`crossbind: ${at}.kind ${JSON.stringify(target.kind)} is none of ${Object.keys(KINDS).join(', ')}.`);
+}
+
+function checkedActivation(at, activation) {
+    const isTaken = (key, value) => Object.hasOwn(ACTIVATION, key) && (key === 'text' ? value === true : Number.isInteger(value) && value >= 1);
+    if (activation === null || typeof activation !== 'object' || Array.isArray(activation) || Object.keys(activation).length === 0
+        || !Object.entries(activation).every(([key, value]) => isTaken(key, value))) {
+        throw new Error(`crossbind: ${at}.activation is no object of ${Object.keys(ACTIVATION).join(', ')}, each a count from 1 and text true, as { images: 10, urls: 1 } is.`);
+    }
+}
+
+// What a target's kind takes and the rest of its own keys, once its sources and the values every part takes are checked.
+export function checkedTargetOptions(at, target, sources) {
+    const { kind } = target;
+    for (const key of KIND_KEYS) {
+        const isGiven = target[key] !== undefined;
+        if (isGiven && !KINDS[kind].needs.includes(key) && !KINDS[kind].takes.includes(key)) throw new Error(`crossbind: ${at}, ${kindOf(kind)}, takes no ${key}.`);
+        if (!isGiven && KINDS[kind].needs.includes(key)) throw new Error(`crossbind: ${at}, ${kindOf(kind)}, has no ${key}: ${NEEDED[key]}.`);
+    }
+    if (kind === 'widget' && !sources.some((file) => file.endsWith('.swift'))) {
+        throw new Error(`crossbind: ${at} is a widget, whose SwiftUI needs a Swift source among its sources.`);
+    }
+    if (target.principalClass !== undefined && (typeof target.principalClass !== 'string' || !CLASS.test(target.principalClass))) {
+        throw new Error(`crossbind: ${at}.principalClass ${JSON.stringify(target.principalClass)} is no class name.`);
+    }
+    if (target.activation !== undefined) checkedActivation(at, target.activation);
+    if (target.categories !== undefined
+        && (!Array.isArray(target.categories) || target.categories.length === 0 || !target.categories.every((id) => typeof id === 'string' && id !== ''))) {
+        throw new Error(`crossbind: ${at}.categories is no list of the notification categories the target shows.`);
+    }
+    if (target.extensionPoint !== undefined && (typeof target.extensionPoint !== 'string' || !EXTENSION_POINT.test(target.extensionPoint))) {
+        throw new Error(`crossbind: ${at}.extensionPoint ${JSON.stringify(target.extensionPoint)} is no extension point, as com.apple.keyboard-service is.`);
+    }
+    if (EXTENSION_KIT_POINTS.includes(target.extensionPoint)) {
+        throw new Error(`crossbind: ${at}.extensionPoint ${target.extensionPoint} is ExtensionKit's, whose extensions crossbind makes none of yet.`);
+    }
+    // The attributes of an option its kind takes, which an other target gives itself.
+    const written = Object.keys(target.attributes ?? {}).find((key) => Object.hasOwn(WRITTEN_ATTRIBUTES, key) && KINDS[kind].needs.includes(WRITTEN_ATTRIBUTES[key]));
+    if (written) throw new Error(`crossbind: ${at}.attributes gives ${written}, which crossbind writes from the target's ${WRITTEN_ATTRIBUTES[written]}.`);
+    const own = Object.keys(target.plist ?? {}).find((key) => WRITTEN_KEYS.includes(key));
+    if (own) throw new Error(`crossbind: ${at}.plist gives ${own}, which crossbind writes for each target.`);
+    const files = ['Info.plist', ...(target.privacy ? ['PrivacyInfo.xcprivacy'] : [])];
+    const resource = (target.resources ?? []).find((file) => files.includes(file.split('/').at(-1)));
+    if (resource) throw new Error(`crossbind: ${at}.resources names ${resource}, a file crossbind writes into the target's bundle.`);
+    const version = target.deploymentTarget;
+    if (version !== undefined && (typeof version !== 'string' || !VERSION.test(version))) {
+        throw new Error(`crossbind: ${at}.deploymentTarget ${JSON.stringify(version)} is no iOS version, as '17.0' is.`);
+    }
+    if (version !== undefined && isBelow(version, IOS_DEPLOYMENT_TARGET)) {
+        throw new Error(`crossbind: ${at}.deploymentTarget ${version} is below the app's iOS ${IOS_DEPLOYMENT_TARGET}, which each of its targets runs on as well.`);
+    }
+    if (target.appGroup !== undefined && typeof target.appGroup !== 'boolean') throw new Error(`crossbind: ${at}.appGroup is no boolean.`);
+    if (target.displayName !== undefined && (typeof target.displayName !== 'string' || target.displayName.trim() === '')) {
+        throw new Error(`crossbind: ${at}.displayName is no name the system shows.`);
+    }
+}
+
+// The Swift module a target's sources make, whose name takes no dash.
+export const targetModule = (name) => name.replace(/-/g, '_');
+
+// A target's Info.plist, as crossbind writes it, with the target's own keys: its bundle, by Xcode's settings, its
+// extension point, principal class and attributes, and the App Group it asks for. The principal class of a target
+// without Objective-C is Swift's, in its module, as Xcode's templates name it; one beside Objective-C goes by the name its
+// runtime knows.
+export function targetPlist(target, label, appGroup) {
+    const hasObjectiveC = target.sources.some(isObjectiveC);
+    const attributes = {
+        ...(target.kind === 'notification-content' ? { UNNotificationExtensionInitialContentSizeRatio: 1 } : {}),
+        ...target.attributes,
+        ...(target.activation ? { NSExtensionActivationRule: Object.fromEntries(Object.entries(target.activation).map(([key, value]) => [ACTIVATION[key], value])) } : {}),
+        ...(target.categories ? { UNNotificationExtensionCategory: target.categories.length === 1 ? target.categories[0] : target.categories } : {}),
+    };
+    const principal = target.principalClass && (hasObjectiveC ? target.principalClass : `$(PRODUCT_MODULE_NAME).${target.principalClass}`);
+    return {
+        CFBundleDevelopmentRegion: 'en',
+        CFBundleDisplayName: target.displayName ?? label,
+        CFBundleExecutable: '$(EXECUTABLE_NAME)',
+        CFBundleIdentifier: '$(PRODUCT_BUNDLE_IDENTIFIER)',
+        CFBundleInfoDictionaryVersion: '6.0',
+        CFBundleName: '$(PRODUCT_NAME)',
+        CFBundlePackageType: '$(PRODUCT_BUNDLE_PACKAGE_TYPE)',
+        CFBundleShortVersionString: '$(MARKETING_VERSION)',
+        CFBundleVersion: '$(CURRENT_PROJECT_VERSION)',
+        NSExtension: {
+            NSExtensionPointIdentifier: target.extensionPoint ?? KINDS[target.kind].point,
+            ...(principal ? { NSExtensionPrincipalClass: principal } : {}),
+            ...(Object.keys(attributes).length > 0 ? { NSExtensionAttributes: attributes } : {}),
+        },
+        ...(target.appGroup ? { [APP_GROUP_KEY]: appGroup } : {}),
+        ...target.plist,
+    };
+}

package/src/utils/ask.js

@@ -0,0 +1,38 @@
+import readline from 'node:readline';
+import { Writable } from 'node:stream';
+
+// Whether someone is at a terminal to answer a question, as no one is in CI or behind a pipe.
+export const hasTerminal = () => Boolean(process.stdin.isTTY && process.stderr.isTTY);
+
+function ask(question, { input, output, isHidden }) {
+    output.write(question);
+    // A hidden answer is echoed into nothing, while the terminal, in raw mode, shows none of it either.
+    const echo = isHidden ? new Writable({ write: (chunk, encoding, done) => done() }) : output;
+    const reader = readline.createInterface({ input, output: echo, terminal: isHidden });
+    return new Promise((resolve, reject) => {
+        let isAnswered = false;
+        reader.once('line', (line) => {
+            isAnswered = true;
+            reader.close();
+            if (isHidden) output.write('\n');
+            resolve(line);
+        });
+        reader.once('SIGINT', () => {
+            reader.close();
+            output.write('\n');
+            reject(new Error('crossbind: stopped at the question.'));
+        });
+        reader.once('close', () => {
+            if (!isAnswered) reject(new Error('crossbind: the terminal closed before an answer.'));
+        });
+    });
+}
+
+// An answer typed on the terminal that the terminal does not show, as a password.
+export const askHidden = (question, { input = process.stdin, output = process.stderr } = {}) => ask(question, { input, output, isHidden: true });
+
+// An answer typed on the terminal.
+export const askLine = (question, { input = process.stdin, output = process.stderr } = {}) => ask(question, { input, output, isHidden: false });
+
+// A yes or no typed on the terminal: yes unless it starts with n.
+export const askYesNo = async (question, streams) => !/^\s*n/i.test(await askLine(question, streams));

package/src/utils/bridgeTools.js

@@ -0,0 +1,66 @@
+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) {
+    if (error?.code === 'MODULE_NOT_FOUND') {
+        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

@@ -0,0 +1,181 @@
+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.
+const CONFIG_EXTENSIONS = ['js', 'mjs', 'cjs'];
+const DEFAULT_INDENT = '    ';
+
+const indentOf = (source, at) => source.slice(source.lastIndexOf('\n', at - 1) + 1).match(/^[ \t]*/)[0];
+const isOneLine = (source, from, to) => !source.slice(from, to).includes('\n');
+const insert = (source, at, text) => `${source.slice(0, at)}${text}${source.slice(at)}`;
+const propertyOf = (object, name) => object.properties.find((property) => property.type === 'Property' && !property.computed
+    && (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 quoted(value);
+    if (Array.isArray(value)) return `[${value.map(literal).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) => `${keyOf(key)}: ${literal(value)}`;
+
+// How far an object's keys sit in from the line it opens on.
+function indentUnit(source, object) {
+    const [first] = object.properties;
+    if (!first || isOneLine(source, object.start, first.start)) return DEFAULT_INDENT;
+    return indentOf(source, first.start).slice(indentOf(source, object.start).length) || DEFAULT_INDENT;
+}
+
+// `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;
+    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;
+    }
+}
+
+// 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}],` };
+    }
+    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 };
+}
+
+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 = 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/extensionSteps.js

@@ -0,0 +1,135 @@
+// What a publisher, an installer 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 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),
+        }];
+    }));
+}