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

package/src/actions/createInterface.js

@@ -2,9 +2,9 @@
 import fs from 'node:fs';
 import upath from 'upath';
 import state, { saveCache } from '../state/index.js';
-import refreshConanDependencies from '../state/refreshConanDependencies.js';
+import refreshPackageSources from '../state/refreshPackageSources.js';
 import refreshBuiltDependencies from '../state/refreshBuiltDependencies.js';
-import { conanInputsOf } from '../utils/conanDependencies.js';
+import { packageSourceInputsOf, sourceNamesOf } from '../utils/packageSources.js';
 import { getContentHash, getFileHash } from '../utils/hash.js';
 import guardAsyncBindings from '../utils/bridgeAsyncGuard.js';
 import fixBridgeRuntime from '../utils/bridgeRuntimeFixes.js';
@@ -12,7 +12,7 @@ import {
     interfaceExtras, bridgeExtras, hasPointerRuntime, withPointerRuntimeAnchor, withoutBridgeExtras, POINTER_RUNTIME_ANCHOR,
 } from '../utils/bridgeExtras.js';
 import resolveNativeImport from '../integration/resolveNativeImport.js';
-import { writeHeaderDts, writeConanImportDts } from '../utils/cppDts.js';
+import { writeHeaderDts, writeSourceImportDts } from '../utils/cppDts.js';
 import { ALL_NAMES, findHeaderImportsIn } from '../utils/headerImports.js';
 import {
     buildInterfaceContent, completingIncludes, findHeaderPrelude, findIgnoredDeclarations, findSwigInlineIncludes, findSwigPreamble,
@@ -21,9 +21,12 @@ import {
 } from '../utils/swigInterface.js';
 import writeIfChanged from '../utils/writeIfChanged.js';
 import { withDirLockSync } from '../utils/dirLock.js';
-import { conanImportOfHeader } from '../utils/conanImport.js';
+import { sourceImportOfHeader } from '../utils/packageSourceImport.js';
 import run, { cxxPreprocessorFor } from './run.js';
 import isSourceCmakePackage from '../utils/isSourceCmakePackage.js';
+import {
+    loadBridgeTools, runPreprocessor, runSwig, usesBridgeTools,
+} from '../utils/bridgeTools.js';
 
 // Part of every interface hash, so interfaces cached by an older generator are rebuilt.
 const INTERFACE_FORMAT = 'swig-macros-4';
@@ -50,10 +53,12 @@ export default function createBridgeFile(headerOrModuleFilePath, target = state.
 }
 
 function bindHeader(headerOrModuleFilePath, target, { withDependencies = true, wholeHeaders = [] } = {}) {
-    // A header can include a Conan package's headers that a build staged after this process loaded, or belong to a
-    // dependency built since.
-    refreshConanDependencies(state.config);
+    // A header can include the headers of a package source's package that a build staged after this process loaded,
+    // or belong to a dependency built since.
+    refreshPackageSources(state.config);
     refreshBuiltDependencies(state.config);
+    // Without bridge-tools on a Mac the macro step would fail quietly, and its interface would be kept without macros.
+    if (usesBridgeTools(target)) loadBridgeTools();
     const interfaceFilePath = upath.resolve(headerOrModuleFilePath);
     if (!fs.existsSync(`${state.config.paths.build}/interface`)) {
         fs.mkdirSync(`${state.config.paths.build}/interface`, { recursive: true });
@@ -71,7 +76,7 @@ function bindHeader(headerOrModuleFilePath, target, { withDependencies = true, w
     const { headerPath } = includeLocation(interfaceFilePath, target);
     const inlined = findSwigInlineIncludes(interfaceFilePath, [state.config, ...state.config.allDependencies], headerPath);
     const swigView = inlined.length ? writeSwigView(interfaceFilePath, headerPath, inlined) : null;
-    const sourceHash = [getFileHash(interfaceFilePath), ...conanInputsHash()].join('\n');
+    const sourceHash = [getFileHash(interfaceFilePath), ...packageInputsHash()].join('\n');
     // The names imported by name decide what the bridge adds to SWIG's output, so another one makes another bridge.
     const bridgeSourceHash = names.named.length ? `${sourceHash}\nnamed:${names.named.join(',')}` : sourceHash;
     const extras = { named: names.named, headerText: () => fs.readFileSync(swigView ? upath.join(swigView.dir, headerPath) : interfaceFilePath, 'utf8') };
@@ -86,13 +91,14 @@ function bindHeader(headerOrModuleFilePath, target, { withDependencies = true, w
             exportsFile: `${bridgeFile}.exports.json`,
             projectPath: state.config.paths.project,
             cacheDir: state.config.paths.cache,
+            sources: sourceNamesOf(state.config),
             dtsMode: state.config.dts,
         };
         writeHeaderDts(dtsOptions);
-        if (conanImportOfHeader(interfaceFilePath, state.config.paths.cache)) {
-            dtsOptions.declarationsFile = createConanDeclarations(interfaceFile, target, sourceDir, sourceHash, swigView);
+        if (sourceImportOfHeader(interfaceFilePath, dtsOptions.cacheDir, dtsOptions.sources)) {
+            dtsOptions.declarationsFile = createSourceDeclarations(interfaceFile, target, sourceDir, sourceHash, swigView);
         }
-        writeConanImportDts(dtsOptions);
+        writeSourceImportDts(dtsOptions);
     }
     if (bridgeFile && withDependencies && !moduleRegex.test(interfaceFilePath)) {
         // A header's own bindings need the types its declarations use registered, which only their headers' bridges do.
@@ -110,11 +116,11 @@ function bindHeader(headerOrModuleFilePath, target, { withDependencies = true, w
     return bridgeFile;
 }
 
-// The Conan packages a header's includes may reach, for the interface and bridge caches: they are
-// staged after a header may already be bound, and restaged in place for another version.
-function conanInputsHash() {
-    const conan = conanInputsOf(state.config);
-    return conan ? [`conan:${getContentHash(JSON.stringify(conan))}`] : [];
+// The packages of package sources a header's includes may reach, for the interface and bridge caches: they
+// are staged after a header may already be bound, and restaged in place for another version.
+function packageInputsHash() {
+    const inputs = packageSourceInputsOf(state.config);
+    return inputs ? [`packages:${getContentHash(JSON.stringify(inputs))}`] : [];
 }
 
 // A header binds the constants the app imports from it, and so the free functions of a dependency's header: the project's
@@ -154,17 +160,18 @@ function createInterfaceFile(headerOrModuleFilePath, target, sourceDir, { consta
     const filePathWithoutExt = headerOrModuleFilePath.match(/^(.*)\..+?$/)?.[1];
     const interfaceFile = !isModule && filePathWithoutExt ? `${filePathWithoutExt}.i` : null;
     // A prelude or ignored-declaration change in the owning package, a completed class moving to another header, an
-    // interface the package ships beside the header changing or going away, another imported name, or Conan packages
-    // its includes may reach being staged or moving to another version must regenerate the interface as well.
+    // interface the package ships beside the header changing or going away, another imported name, packages of a
+    // package source its includes may reach being staged or moving to another version, or the header included by
+    // another path, as another target finds it, must regenerate the interface as well.
     const fileHash = [
-        INTERFACE_FORMAT, getFileHash(headerOrModuleFilePath), ...prelude,
+        INTERFACE_FORMAT, getFileHash(headerOrModuleFilePath), ...(headerPath ? [`include:${headerPath}`] : []), ...prelude,
         ...(ignored.length ? [`ignored:${ignored.join(',')}`] : []), ...(completing.length ? [`completing:${completing.join(',')}`] : []),
         ...(preamble.length ? [`preamble:${preamble.join('\n')}`] : []),
         ...(interfaceFile && fs.existsSync(interfaceFile) ? [`shipped:${getFileHash(interfaceFile)}`] : []),
         ...(constants.length ? [`constants:${constants === ALL_NAMES ? ALL_NAMES : constants.join(',')}`] : []),
         ...(functions === ALL_NAMES ? [] : [`functions:${functions.join(',')}`]),
         ...(named.length ? [`named:${named.join(',')}`] : []),
-        ...conanInputsHash(),
+        ...packageInputsHash(),
     ].join('\n');
     const cachedInterface = state.cache.interfaces[headerOrModuleFilePath];
     if (state.cache.hashes[headerOrModuleFilePath] === fileHash && cachedInterface && fs.existsSync(cachedInterface)
@@ -353,21 +360,25 @@ const RELEASE_DEFINE = '-DNDEBUG';
 
 // One bridge serves every desktop target, so SWIG and the macro table it reads come from the web image's em++,
 // which defines no operating system; an android bridge is read with the NDK it compiles with. The headers
-// still come from the target's own packages.
+// still come from the target's own packages. On a Mac, bridge-tools makes the same bridge, in the build directory the
+// image's tools run in.
 const toolTargetFor = (target) => (target?.platform === 'android' ? target : { ...target, platform: 'wasm' });
 
 function dumpMacros(outputFile, includes, includePath, target, defines = []) {
-    const tool = toolTargetFor(target);
-    run(cxxPreprocessorFor(tool), [
+    const args = [
         '-x', 'c++', '-std=c++17', '-dM', '-E', ...defines,
         ...includePath,
         ...includes.flatMap((header) => ['-include', header]),
         '-o', outputFile,
         '/dev/null',
-    ], null, tool);
+    ];
+    if (usesBridgeTools(target)) runPreprocessor(args, state.config.paths.build);
+    else run(cxxPreprocessorFor(toolTargetFor(target)), args, null, toolTargetFor(target));
     return parseMacroDump(fs.readFileSync(outputFile, 'utf8'));
 }
 
+const runSwigFor = (args, target) => (usesBridgeTools(target) ? runSwig(args, state.config.paths.build) : run('swig', args, null, toolTargetFor(target)));
+
 function swigIncludePath(target, sourceDir) {
     const allHeaders = state.config.dependencyParameters.headerPathWithDepends.split(';');
     const includePath = [
@@ -468,7 +479,7 @@ function createBridgeFileFromInterfaceFile(interfaceFilePath, target, sourceDir
     const bridgeFilePath = `${state.config.paths.build}/bridge/${interfaceFilePath.split('/').at(-1)}.cpp`;
     fs.writeFileSync(keyOf(bridgeFilePath), '');
     // #error lines guard branches SWIG evaluates without the compiler's predefined macros, so they only warn.
-    const swig = () => run('swig', [
+    const swig = () => runSwigFor([
         '-c++',
         '-embind',
         '-cpperraswarn',
@@ -476,7 +487,7 @@ function createBridgeFileFromInterfaceFile(interfaceFilePath, target, sourceDir
         ...(swigView ? [`-I${swigView.dir}`] : []),
         ...swigIncludePath(target, sourceDir),
         interfaceFilePath,
-    ], null, toolTargetFor(target));
+    ], target);
     try {
         swig();
     } catch (e) {
@@ -508,7 +519,7 @@ function createBridgeFileFromInterfaceFile(interfaceFilePath, target, sourceDir
 }
 
 // Generate a full export catalog for the editor, without compiling or linking these extra functions.
-function createConanDeclarations(interfaceFile, target, sourceDir, sourceHash, swigView) {
+function createSourceDeclarations(interfaceFile, target, sourceDir, sourceHash, swigView) {
     const dir = `${state.config.paths.build}/declarations`;
     fs.mkdirSync(dir, { recursive: true });
     const file = `${dir}/${upath.basename(interfaceFile)}`;
@@ -517,8 +528,8 @@ function createConanDeclarations(interfaceFile, target, sourceDir, sourceHash, s
     const hash = getContentHash([BRIDGE_FORMAT, getFileHash(file), sourceHash, swigView?.hash ?? ''].join('\n'));
     if (!fs.existsSync(`${bridge}.exports.json`) || !fs.existsSync(keyOf(bridge)) || fs.readFileSync(keyOf(bridge), 'utf8') !== hash) {
         fs.writeFileSync(keyOf(bridge), '');
-        run('swig', ['-c++', '-embind', '-cpperraswarn', '-o', bridge,
-            ...(swigView ? [`-I${swigView.dir}`] : []), ...swigIncludePath(target, sourceDir), file], null, toolTargetFor(target));
+        runSwigFor(['-c++', '-embind', '-cpperraswarn', '-o', bridge,
+            ...(swigView ? [`-I${swigView.dir}`] : []), ...swigIncludePath(target, sourceDir), file], target);
         fs.writeFileSync(keyOf(bridge), hash);
     }
     return `${bridge}.exports.json`;

package/src/actions/createLib.js

@@ -6,7 +6,6 @@ import run from './run.js';
 import buildCargo from './buildCargo.js';
 import { cargoTripleFor } from '../utils/cargoTarget.js';
 import getCmakeParameters from './getCmakeParameters.js';
-import triggerExtensions from './extensions.js';
 import state from '../state/index.js';
 import logger from '../utils/logger.js';
 import { WASI_EMULATION_LIBS, WASI_LINK_LIBS, wasiCFlags, wasiCxxFlags } from '../utils/wasiToolchain.js';
@@ -17,7 +16,7 @@ import {
 import { getFilesFingerprint, getContentHash } from '../utils/hash.js';
 import { withDependencyBridges } from '../utils/dependencyBridges.js';
 import { targetArchiveFlags } from '../utils/archiveFlags.js';
-import { conanInputsOf } from '../utils/conanDependencies.js';
+import { packageSourceInputsOf } from '../utils/packageSources.js';
 import { nativeSourceStampChanged, writeNativeSourceStamp } from '../utils/nativeSourceStamp.js';
 import resetCMakeCacheForSource from '../utils/resetCMakeCacheForSource.js';
 
@@ -58,10 +57,10 @@ export default function createLib(target, fileType, options = {}) {
     const configEmccFlags = getData('binary', target)?.emccFlags || [];
     const compileOptions = getData('cmake', target)?.compileOptions || [];
     const flagsFingerprintFile = `${libdir}/crossbind-emccflags.fingerprint`;
-    const conanInputs = conanInputsOf(state.config);
+    const packageInputs = packageSourceInputsOf(state.config);
     const compileInputs = compileOptions.length ? { emccFlags: configEmccFlags, compileOptions } : configEmccFlags;
     const flagsInputs = sourceReplacements.length ? { compileInputs, sourceReplacements } : compileInputs;
-    const keyInputs = conanInputs ? [flagsInputs, conanInputs] : flagsInputs;
+    const keyInputs = packageInputs ? [flagsInputs, packageInputs] : flagsInputs;
     // An app's wasi source compiles against <crossbind/http.h>, so a new one misses this cache too.
     const httpHeader = target.platform === 'wasi' && !state.config.build.withBuildConfig
         ? getFilesFingerprint([wasiHttpHeader(state.config.paths.cli)])
@@ -132,7 +131,6 @@ export default function createLib(target, fileType, options = {}) {
 
         const extraLibs = getExtraLibs ? getExtraLibs(target) : [];
 
-        triggerExtensions('createLib', 'setFlagWithBuildConfig', [buildEnv, cFlags, ldFlags]);
         const archiveFlags = targetArchiveFlags(target);
         cFlags.push(...archiveFlags);
         ldFlags.push(...archiveFlags);
@@ -165,8 +163,6 @@ export default function createLib(target, fileType, options = {}) {
         ];
         buildParams = getCmakeParameters(target, { ...options, nativeGlob, headerDirs });
 
-        triggerExtensions('createLib', 'setFlagWithoutBuildConfig', [buildEnv]);
-
         const archiveFlags = targetArchiveFlags(target).join(' ');
         if (archiveFlags) {
             buildEnv.params.push('-e', `CFLAGS=${archiveFlags}`);

package/src/actions/extensionApi.js

@@ -0,0 +1,298 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import state from '../state/index.js';
+import { exportOf } from '../state/loadConfig.js';
+import loadSystemConfig, { extensionSettingsOf, updateSystemConfig } from '../utils/systemConfig.js';
+import systemKeys from '../utils/systemKeys.js';
+import { askLine, askYesNo, hasTerminal } from '../utils/ask.js';
+import openUrl from '../utils/openUrl.js';
+import { readSecret, storeSecret } from '../utils/keychain.js';
+import { configChangesOf } from '../utils/configChanges.js';
+import { entry, writeOption } from '../utils/configWriter.js';
+import { readAppIcon, windowsIcon } from '../utils/appIcon.js';
+import {
+    PRIVACY_CATEGORIES, androidAppId, appCategory, appDisplayName, appEncryption, appId, appPrivacy, appUrlSchemes,
+} from '../utils/appOptions.js';
+import { isJsonValue, linuxDepends } from '../utils/appExtensions.js';
+import { fileTypeOwners } from '../utils/appLaunches.js';
+import { unreasonedImports } from '../utils/requiredReasonApis.js';
+import { resolveHermesDsym } from '../utils/hermes.js';
+import { imageRoleFor } from '../utils/pullDockerImage.js';
+import { isUnderBase } from '../utils/replaceBasePathForDocker.js';
+import {
+    androidVersion, appBuildNumber, appTeam, appVersion,
+} from './buildApp.js';
+import runTool from './run.js';
+import { makeUploadKey, releaseSigningEnv } from './uploadKey.js';
+import { appStoreKey } from './appleSigning.js';
+import { inWindowsImage, jsignScript, windowsSigning } from './windowsSigning.js';
+import { xcodebuild, xcodeTeams } from './xcodebuild.js';
+
+// The api an extension's build-side code gets in place of crossbind's own modules, which it never imports: what the run
+// is, the project and its app as the build reads them, the terminal, this machine's settings and keychain, and the
+// signing and tools crossbind builds and packages each platform's apps with.
+
+const PATH_PART = /^[A-Za-z_$][\w$]*$/;
+const SETTING = /^[A-Z][A-Z0-9_]*$/;
+const ACCOUNT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+function refuse() {
+    throw new TypeError('crossbind: api.config is read-only: api.config.write writes an option into crossbind.config.js.');
+}
+
+const views = new WeakMap();
+const READ_ONLY = {
+    get(target, key, receiver) {
+        const value = Reflect.get(target, key, receiver);
+        const own = Reflect.getOwnPropertyDescriptor(target, key);
+        // A proxy gives a property that never changes as it is.
+        if (own && !own.configurable && !own.writable) return value;
+        return readOnly(value);
+    },
+    // A configurable property's value is a view too; one that never changes is given as it is, as a proxy must.
+    getOwnPropertyDescriptor(target, key) {
+        const own = Reflect.getOwnPropertyDescriptor(target, key);
+        return own?.configurable && 'value' in own ? { ...own, value: readOnly(own.value) } : own;
+    },
+    set: refuse,
+    defineProperty: refuse,
+    deleteProperty: refuse,
+    setPrototypeOf: refuse,
+    preventExtensions: refuse,
+};
+
+function readOnly(value) {
+    if (value === null || typeof value !== 'object') return value;
+    if (!views.has(value)) views.set(value, new Proxy(value, READ_ONLY));
+    return views.get(value);
+}
+
+// crossbind.config.js's export as the run's config read it, with the app's options the api wrote since, which the run's
+// config holds: each read sees them, however long ago the extension took the view.
+function configView(write) {
+    const current = () => ({ ...exportOf(state.config), app: state.config.app });
+    return new Proxy({}, {
+        get: (target, key) => (key === 'write' ? write : readOnly(current()[key])),
+        has: (target, key) => key in current(),
+        ownKeys: () => Reflect.ownKeys(current()),
+        getOwnPropertyDescriptor(target, key) {
+            const own = Reflect.getOwnPropertyDescriptor(current(), key);
+            return own && { ...own, value: readOnly(own.value) };
+        },
+        set: refuse,
+        defineProperty: refuse,
+        deleteProperty: refuse,
+        setPrototypeOf: refuse,
+        preventExtensions: refuse,
+    });
+}
+
+const deepFrozen = (value) => {
+    if (value !== null && typeof value === 'object') Object.values(value).forEach(deepFrozen);
+    return Object.freeze(value);
+};
+
+const valueAt = (object, keys) => keys.reduce((value, key) => (isObject(value) ? value[key] : undefined), object);
+const withValue = (object, [key, ...rest], value) => ({ ...object, [key]: rest.length === 0 ? value : withValue(isObject(object?.[key]) ? object[key] : {}, rest, value) });
+
+// What crossbind checks of an option written into crossbind.config.js, as its builds read it.
+const OPTION_CHECKS = {
+    'app.id': (config, platform) => (platform === 'android' ? androidAppId(config) : appId(config)),
+    'app.name': appDisplayName,
+    'app.icon': readAppIcon,
+    'app.encryption': appEncryption,
+    'app.privacy': appPrivacy,
+};
+
+// Writes an option into crossbind.config.js once the user says yes on a terminal, and into this run's config: one of
+// those crossbind checks as the builds would, alone. One the config sets already is the user's to change, and one the
+// builds would refuse fails as invalid, for the caller to ask again.
+async function writeConfig(name, platform, key, value) {
+    const keys = typeof key === 'string' ? key.split('.') : [];
+    if (keys.length === 0 || !keys.every((part) => PATH_PART.test(part))) throw new Error(`crossbind: ${name} names ${JSON.stringify(key)}, which is no option of crossbind.config.js, as 'app.id' is.`);
+    if (!Object.hasOwn(OPTION_CHECKS, key)) {
+        const writable = Object.keys(OPTION_CHECKS);
+        throw new Error(`crossbind: ${name} writes ${key}, which api.config.write leaves to the app's developer: it writes ${writable.slice(0, -1).join(', ')} and ${writable.at(-1)} alone.`);
+    }
+    if (!isJsonValue(value)) throw new Error(`crossbind: ${name} gives ${key} a value that is no JSON value, which is all crossbind writes into crossbind.config.js.`);
+    // A copy of its own, as the value may hold the api's views of the config.
+    const plain = JSON.parse(JSON.stringify(value));
+    const text = `${keys.slice(0, -1).map((part) => `${part}.`).join('')}${entry(keys.at(-1), plain)}`;
+    if (valueAt(state.config, keys) !== undefined) throw new Error(`crossbind: set ${text} in crossbind.config.js in place of the ${key} there.`);
+    const changed = withValue(state.config, keys, plain);
+    try {
+        OPTION_CHECKS[key]?.(changed, platform);
+    } catch (error) {
+        throw Object.assign(error, { isInvalid: true });
+    }
+    if (!hasTerminal()) throw new Error(`crossbind: ${name} would write ${text} into crossbind.config.js, which takes a yes on a terminal: set it there yourself.`);
+    if (!await askYesNo(`Write ${text} into crossbind.config.js? [Y/n] `)) throw new Error(`crossbind: set ${text} in crossbind.config.js.`);
+    if (!writeOption(state.config.paths.project, keys, plain)) {
+        throw new Error(`crossbind: crossbind.config.js is no config crossbind can write ${key} into safely: set ${text} in it yourself.`);
+    }
+    state.config[keys[0]] = changed[keys[0]];
+}
+
+// This machine's settings: crossbind's own by their names, as `crossbind config set` takes them, and by any other name
+// the extension's own, which ~/.crossbind.json keeps apart for each extension.
+function settingsOf(name) {
+    const isCrossbinds = (key) => Object.hasOwn(systemKeys, key);
+    return Object.freeze({
+        get: (key) => (isCrossbinds(key) ? state.config.system[key] : extensionSettingsOf(state.config.system, name)[key]),
+        set(values) {
+            if (!isObject(values) || !Object.entries(values).every(([key, value]) => SETTING.test(key) && typeof value === 'string')) {
+                throw new Error(`crossbind: ${name} sets settings that are no object of this machine's settings, each an uppercase name with a string.`);
+            }
+            const entries = Object.entries(values);
+            entries.filter(([key]) => systemKeys[key]?.options).forEach(([key, value]) => {
+                if (!systemKeys[key].options.includes(value)) {
+                    throw new Error(`crossbind: ${name} sets ${key} to ${JSON.stringify(value)}, which takes ${systemKeys[key].options.join(', ')} alone.`);
+                }
+            });
+            const own = entries.filter(([key]) => !isCrossbinds(key));
+            updateSystemConfig(Object.fromEntries(entries.filter(([key]) => isCrossbinds(key))), own.length > 0 ? { name, values: Object.fromEntries(own) } : null);
+            state.config.system = loadSystemConfig();
+        },
+    });
+}
+
+// The keychain keeps an extension's secrets under its own service, each by a path the account names, as Windows keeps
+// one in a file beside that path.
+function secretsOf(name) {
+    const service = `crossbind ${name}`;
+    const keyOf = (account) => {
+        if (typeof account !== 'string' || !ACCOUNT.test(account)) throw new Error(`crossbind: ${name} names the secret ${JSON.stringify(account)}, which is no name of letters, digits, dots, dashes and underscores.`);
+        return path.join(os.homedir(), '.crossbind', 'secrets', name, account);
+    };
+    return Object.freeze({
+        get: (account) => readSecret(keyOf(account), { service }),
+        set(account, secret) {
+            const key = keyOf(account);
+            if (typeof secret !== 'string' || !secret) throw new Error(`crossbind: ${name} keeps no secret of ${account}, which is no text.`);
+            fs.mkdirSync(path.dirname(key), { recursive: true, mode: 0o700 });
+            return storeSecret(key, secret, { service });
+        },
+    });
+}
+
+function terminalOf(name) {
+    const assertTerminal = (question) => {
+        if (!hasTerminal()) throw new Error(`crossbind: ${name} asks ${JSON.stringify(question.trim())}, with no terminal to answer it.`);
+    };
+    return {
+        ask(question) {
+            assertTerminal(question);
+            return askLine(question);
+        },
+        askYesNo(question) {
+            assertTerminal(question);
+            return askYesNo(question);
+        },
+    };
+}
+
+// Runs a tool to its end where crossbind packages an app of the target's platform: on this Mac, with Apple's tools on
+// the PATH, for a macOS app, and for a Linux or Windows app in crossbind's image of its platform, which sees the
+// project's base alone, the windows one with the key that signs the app for a tool that signs. An installer's api alone
+// has the target of the app it makes.
+function runOf(name, target) {
+    return (command, options) => {
+        if (!target) throw new Error(`crossbind: ${name} runs a tool with api.run, which an installer's api alone has.`);
+        if (!Array.isArray(command) || command.length === 0 || !command.every((part) => typeof part === 'string')) {
+            throw new Error(`crossbind: ${name} runs no command with api.run, which takes a list of strings: the program and its arguments.`);
+        }
+        const { cwd = state.config.paths.project, isSigning = false } = options ?? {};
+        if (typeof cwd !== 'string') throw new Error(`crossbind: ${name} runs ${command[0]} in ${JSON.stringify(cwd)}, which is no path of a folder.`);
+        const dir = path.resolve(state.config.paths.project, cwd);
+        if (!fs.statSync(dir, { throwIfNoEntry: false })?.isDirectory()) throw new Error(`crossbind: ${name} runs ${command[0]} in ${dir}, which is no folder.`);
+        if (target.platform !== 'darwin' && !isUnderBase(dir, state.config.paths.base)) {
+            throw new Error(`crossbind: ${name} runs ${command[0]} in ${dir}, outside ${state.config.paths.base}, the project's base and all the ${imageRoleFor(target)} container sees. Build the app into a folder under it.`);
+        }
+        if (target.platform === 'win32') inWindowsImage(command, dir, isSigning ? windowsSigning() : null);
+        else runTool(null, command, null, target, { workdir: dir });
+    };
+}
+
+// The api of an extension's run on a platform: the options the command line gave it, the run's build number once the
+// publish picked it, which the app's facts then show, and an installer's target, the app it makes.
+export default function extensionApi(name, {
+    platform, options = {}, isGuided, run = {}, target = null,
+}) {
+    const buildEnv = () => (run.buildNumber === undefined || run.buildNumber === null
+        ? process.env : { ...process.env, CROSSBIND_APP_BUILD_NUMBER: String(run.buildNumber) });
+    const config = configView((key, value) => writeConfig(name, platform, key, value));
+    return Object.freeze({
+        name,
+        platform,
+        isGuided,
+        options: Object.freeze({ ...options }),
+        project: Object.freeze({
+            get root() { return state.config.paths.project; },
+            get name() { return state.config.general.name; },
+            get package() { return readOnly(state.config.package); },
+        }),
+        get workDir() { return path.join(state.config.paths.build, name); },
+        config,
+        get publisherChanges() { return readOnly(configChangesOf()); },
+        app: Object.freeze({
+            get id() { return platform === 'android' ? androidAppId(state.config) : appId(state.config); },
+            get name() { return appDisplayName(state.config); },
+            get version() { return state.config.package?.version ?? '1.0.0'; },
+            get appleVersion() { return appVersion(); },
+            get versionCode() { return androidVersion(buildEnv()).code; },
+            get buildNumber() { return appBuildNumber(buildEnv()); },
+            get team() { return appTeam(); },
+            get encryption() { return appEncryption(state.config); },
+            get urlSchemes() { return Object.freeze(appUrlSchemes(state.config)); },
+            get fileTypes() { return Object.freeze(fileTypeOwners(state.config).map(({ extension, ...type }) => Object.freeze(type))); },
+            // The Debian packages a Linux app needs beside WebKitGTK and GTK, as its extensions' Linux parts list them.
+            get depends() { return Object.freeze(linuxDepends(state.config.extensions ?? [])); },
+            get category() {
+                const category = appCategory(state.config);
+                return category && Object.freeze({ macos: category.darwin, linux: category.linux });
+            },
+        }),
+        log: (text) => console.log(text),
+        warn: (text) => console.warn(text),
+        ...terminalOf(name),
+        openUrl(url) {
+            let address = null;
+            try {
+                address = new URL(url);
+            } catch {
+                // What is no URL is refused below.
+            }
+            if (!['http:', 'https:'].includes(address?.protocol)) throw new Error(`crossbind: ${name} opens ${JSON.stringify(url)}, which is no http or https address.`);
+            openUrl(address.href);
+        },
+        run: runOf(name, target),
+        settings: settingsOf(name),
+        secrets: secretsOf(name),
+        android: Object.freeze({
+            signing: () => releaseSigningEnv(),
+            async makeUploadKey() {
+                await makeUploadKey();
+                state.config.system = loadSystemConfig();
+            },
+        }),
+        apple: Object.freeze({
+            key: () => appStoreKey(),
+            teams: () => xcodeTeams(),
+            xcodebuild: (what, args, xcodebuildOptions) => xcodebuild(what, args, xcodebuildOptions),
+            unreasonedApis: (binary, privacy) => unreasonedImports(binary, privacy),
+            privacyCategories: deepFrozen(structuredClone(PRIVACY_CATEGORIES)),
+            dsyms: async () => [await resolveHermesDsym()],
+        }),
+        windows: Object.freeze({
+            icon() {
+                const icon = readAppIcon(state.config);
+                return icon && windowsIcon(icon);
+            },
+            // The script that signs a file in the windows image with the key, which a tool that signs as it builds runs.
+            get signer() { return windowsSigning() ? jsignScript() : null; },
+        }),
+    });
+}

package/src/actions/extensionCommands.js

@@ -0,0 +1,41 @@
+import { Option } from 'commander';
+import extensionApi from './extensionApi.js';
+import state from '../state/index.js';
+import { hasTerminal } from '../utils/ask.js';
+import { extensionStep, ownExtensions, withoutNamed } from '../utils/appExtensions.js';
+import resolveAppHostRoot from '../utils/resolveAppHost.js';
+
+const kebab = (name) => name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+
+// crossbind's own extensions a project has, none where its host is not installed, which each command that needs it says:
+// the commands of those app.without leaves out, and of those whose role or name another takes, go with them.
+function ownOf(listed, app) {
+    let root;
+    try {
+        root = resolveAppHostRoot();
+    } catch {
+        return [];
+    }
+    const taken = new Set(listed.flatMap(({ name, replaces }) => [name, ...(replaces ?? [])]));
+    return withoutNamed(ownExtensions(root), app).filter(({ name }) => !taken.has(name));
+}
+
+// Adds to crossbind app the commands of an app's extensions, crossbind's own and those crossbind.config.js lists: a name
+// another has stops the run, naming both.
+export default function addExtensionCommands(parent, config = state.config) {
+    if (config?.target?.runtimeEnv !== 'app') return;
+    const listed = config.extensions ?? [];
+    const owners = new Map(parent.commands.map((command) => [command.name(), 'crossbind']));
+    for (const { name: extension, commands = {} } of [...ownOf(listed, config.app), ...listed]) {
+        for (const [name, command] of Object.entries(commands)) {
+            if (owners.has(name)) throw new Error(`crossbind: ${extension} adds the command crossbind app ${name}, which ${owners.get(name)} has.`);
+            owners.set(name, extension);
+            const added = parent.command(name).description(command.help);
+            Object.entries(command.options).forEach(([option, { help, value, default: fallback }]) => {
+                const flag = new Option(`--${kebab(option)}${value ? ` ${value}` : ''}`, help);
+                added.addOption(fallback === null ? flag : flag.default(fallback));
+            });
+            added.action((options) => extensionStep(extension, name, () => command.run(extensionApi(extension, { platform: null, options, isGuided: hasTerminal() }))));
+        }
+    }
+}

package/src/actions/extensionsInApp.js

@@ -0,0 +1,19 @@
+import extensionApi from './extensionApi.js';
+import state from '../state/index.js';
+import {
+    appExtensionsOf, ownExtensions, withFromApp, withRoles, withoutNamed,
+} from '../utils/appExtensions.js';
+import resolveAppHostRoot from '../utils/resolveAppHost.js';
+
+// The platforms as an extension's api names them.
+const API_PLATFORMS = { darwin: 'macos', win32: 'windows' };
+
+// The extensions an app of this platform has: crossbind's own but those app.without leaves out, then those
+// crossbind.config.js lists, each with the roles it holds, which a listed one's replaces takes from the host's, and the
+// options it takes from the app's config, where it does.
+export default function extensionsInApp(platform, warn) {
+    const own = ownExtensions(resolveAppHostRoot());
+    const { app, extensions = [] } = state.config;
+    const held = withRoles(appExtensionsOf(withoutNamed(own, app)), appExtensionsOf(extensions), warn, appExtensionsOf(own));
+    return withFromApp(held, (name) => extensionApi(name, { platform: API_PLATFORMS[platform] ?? platform, isGuided: false }));
+}

package/src/actions/getAllBridges.js

@@ -2,19 +2,34 @@ import fs from 'node:fs';
 import path from 'node:path';
 import findFiles from '../utils/findFiles.js';
 import state from '../state/index.js';
+import { declarationOf, dependenciesOf, sourceImportOfHeader } from '../utils/packageSourceImport.js';
+
+// Why a bridge's header can no longer be included, or null. A package source's stage outlives the declaration, and
+// the source itself, so the header of a package the project no longer declares is still there while its include
+// directory is off the compile. The stage is named by the path, as the project may have dropped the source too.
+function staleReasonOf(header) {
+    if (!fs.existsSync(header)) return 'its header is gone';
+    const { config } = state;
+    const stages = `${config.paths.cache}/`;
+    const [source] = header.startsWith(stages) ? header.slice(stages.length).split('/') : [];
+    const staged = source ? sourceImportOfHeader(header, config.paths.cache, [source]) : null;
+    if (!staged || Object.hasOwn(dependenciesOf(config, source), staged.name)) return null;
+    return `${declarationOf(source)} no longer declares ${staged.name}`;
+}
 
 export default function getAllBridges(log = console.log) {
     return findFiles(`${state.config.paths.build}/bridge/*.i.cpp`).filter((bridge) => {
         // The .source sidecar records the header this bridge was generated from. When that
-        // header is gone, the stale .i.cpp would #include a missing file and break the native
-        // build - the same failure a deleted .rs used to cause. Bridges without a sidecar
-        // predate it and are left alone.
+        // header can no longer be included, the stale .i.cpp would #include a missing file and
+        // break the native build - the same failure a deleted .rs used to cause. Bridges without
+        // a sidecar predate it and are left alone.
         const sidecar = `${bridge}.source`;
         if (!fs.existsSync(sidecar)) return true;
         const source = fs.readFileSync(sidecar, 'utf8').trim();
-        if (!source || fs.existsSync(source)) return true;
+        const reason = source ? staleReasonOf(source) : null;
+        if (!reason) return true;
         [bridge, `${bridge}.exports.json`, `${bridge}.deps`, `${bridge}.warnings`, sidecar].forEach((f) => fs.rmSync(f, { force: true }));
-        log(`crossbind: pruned stale bridge '${path.basename(bridge)}' - its header is gone`);
+        log(`crossbind: pruned stale bridge '${path.basename(bridge)}' - ${reason}`);
         return false;
     });
 }

package/src/actions/getDependLibs.js

@@ -21,6 +21,11 @@ export default function getDependLibs(target) {
                 if (libPaths.length === 0) {
                     libPaths = libsIn(target.releasePath);
                 }
+                // A published port can leave its iOS archive to its xcframework, where the package's paths lead.
+                const xcframeworkLib = target.platform === 'ios' && state.config.allDependencyPaths?.[target.path]?.[fileName]?.lib;
+                if (libPaths.length === 0 && xcframeworkLib) {
+                    libPaths = findFiles(xcframeworkLib, { cwd: d.paths.project });
+                }
                 dependLibs.push(...libPaths);
             });
         }