@lakutata/builder 3.1.3 → 3.1.6

package/dist/esm/lib/mobile/Node.js

@@ -0,0 +1,190 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { cp, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { runCommand } from '../Processes.js';
+import { cacheDirectory, downloadFile, moveIntoCache } from '../Tools.js';
+/**
+ * The version of Node.js of the mobile applications when their libnode does not tell it: the one of the release of
+ * lakutata/libnode they download (MOBILE_NODE_RELEASE)
+ */
+export const MOBILE_NODE_VERSION = '24.20.0';
+/**
+ * The architectures of Android of a libnode built for them (the arch of Node.js names the native tree of the
+ * architecture, the target names the compilers of the NDK)
+ */
+export const ANDROID_ABIS = {
+    'arm64-v8a': { arch: 'arm64', target: 'aarch64-linux-android' },
+    'armeabi-v7a': { arch: 'arm', target: 'armv7a-linux-androideabi' },
+    'x86_64': { arch: 'x64', target: 'x86_64-linux-android' }
+};
+/**
+ * The version of Node.js of a libnode: the one of its headers (include/node/node_version.h)
+ * @param directory the export of the libnode
+ * @internal
+ */
+export function mobileNodeVersion(directory) {
+    const header = readFileSync(path.join(directory, 'include', 'node', 'node_version.h'), 'utf8');
+    const part = (name) => new RegExp(`#define NODE_${name}_VERSION (\\d+)`).exec(header)?.[1];
+    const [major, minor, patch] = [part('MAJOR'), part('MINOR'), part('PATCH')];
+    if (!major || !minor || !patch)
+        throw new Error(`${directory} holds no version of Node.js (include/node/node_version.h)`);
+    return `${major}.${minor}.${patch}`;
+}
+/**
+ * The architectures of Android a libnode is built for (libs/<abi>/libnode.so)
+ * @param directory the export of the libnode of Android
+ * @internal
+ */
+export function mobileNodeAbis(directory) {
+    return Object.keys(ANDROID_ABIS).filter((abi) => existsSync(path.join(directory, 'libs', abi, 'libnode.so')));
+}
+/**
+ * Check the export of a libnode of a system: its headers, and its libraries (Android: libs/<abi>/libnode.so, HarmonyOS:
+ * libs/arm64-v8a/libnode.so) or its framework (iOS: NodeMobile.xcframework)
+ * @param platform
+ * @param directory
+ * @internal
+ */
+export function checkMobileNode(platform, directory) {
+    const missing = (what) => new Error(`${directory} is not the libnode of ${platform} (${what} missing): download it (lakutata mobile node ${platform})`);
+    if (!existsSync(path.join(directory, 'include', 'node', 'node_api.h')))
+        throw missing('include/node/node_api.h');
+    if (platform === 'ios' && !existsSync(path.join(directory, 'NodeMobile.xcframework', 'Info.plist')))
+        throw missing('NodeMobile.xcframework');
+    if (platform === 'android' && !mobileNodeAbis(directory).length)
+        throw missing('libs/<abi>/libnode.so');
+    if (platform === 'harmony' && !existsSync(path.join(directory, 'libs', 'arm64-v8a', 'libnode.so')))
+        throw missing('libs/arm64-v8a/libnode.so');
+}
+/**
+ * The release of lakutata/libnode the mobile applications download their libnode from: its tag is v<release> (the
+ * version of Node.js, then -<revision> for a release of the same version built again)
+ */
+export const MOBILE_NODE_RELEASE = '24.20.0';
+/**
+ * The architectures of HarmonyOS the mobile applications ship (the libs/arm64-v8a of their HAP)
+ */
+const HARMONY_ABIS = { 'arm64-v8a': { arch: 'arm64' } };
+/**
+ * Where the releases of lakutata/libnode are downloaded from: LAKUTATA_LIBNODE_MIRROR (a mirror of them, its files laid
+ * out as the ones of GitHub: v<release>/<archive>), else the releases of the repository on GitHub
+ */
+function libnodeMirror() {
+    return (process.env.LAKUTATA_LIBNODE_MIRROR ?? 'https://github.com/lakutata/libnode/releases/download').replace(/\/+$/, '');
+}
+/**
+ * An archive of the release, downloaded once into the cache (~/.cache/lakutata/mobile/libnode, LAKUTATA_CACHE_DIR),
+ * checked with the SHA256SUMS of the release and extracted
+ * @param name the archive without its extension: libnode_<platform>_<arch>
+ * @param sums the sha256 of the archives of the release, by their names
+ * @param progress
+ * @returns the directory extracted: lib/libnode.so or NodeMobile.xcframework, include/node, LICENSE, libnode.json
+ */
+async function libnodeArchive(name, sums, progress) {
+    const directory = path.join(cacheDirectory(), 'mobile', 'libnode', MOBILE_NODE_RELEASE, name);
+    if (existsSync(path.join(directory, '.complete')))
+        return directory;
+    const archive = `${name}.tar.gz`;
+    const url = `${libnodeMirror()}/v${MOBILE_NODE_RELEASE}/${archive}`;
+    const sum = (await sums()).get(archive);
+    if (!sum)
+        throw new Error(`The release ${MOBILE_NODE_RELEASE} of libnode has no ${archive} in its SHA256SUMS`);
+    progress?.(`${archive} (libnode ${MOBILE_NODE_RELEASE})`);
+    //Extracted aside, then moved into the cache: the builds running together do not see it partly written
+    await mkdir(path.dirname(directory), { recursive: true });
+    const temporary = await mkdtemp(`${directory}.`);
+    try {
+        const file = path.join(temporary, archive);
+        const downloaded = await downloadFile(url, file, { progress: progress }).catch((error) => {
+            throw new Error(`${error.message}: a mirror of the releases of lakutata/libnode is given by LAKUTATA_LIBNODE_MIRROR, a libnode of your own by LAKUTATA_MOBILE_NODE_DIR`);
+        });
+        if (downloaded !== sum)
+            throw new Error(`The ${archive} downloaded is not the one of the release ${MOBILE_NODE_RELEASE} of libnode (sha256 ${downloaded}, ${sum} expected)`);
+        const extracted = await runCommand('tar', ['-xf', archive], temporary);
+        if (extracted.code !== 0)
+            throw new Error(`${archive} cannot be extracted: ${extracted.output.trim()}`);
+        await rm(file);
+        const root = path.join(temporary, name);
+        if (!existsSync(path.join(root, 'include', 'node', 'node_api.h')))
+            throw new Error(`${archive} has no ${name}/include/node`);
+        await writeFile(path.join(root, '.complete'), '');
+        await moveIntoCache(root, directory, () => existsSync(path.join(directory, '.complete')));
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true });
+    }
+    return directory;
+}
+/**
+ * Download the libnode of a mobile system from the releases of lakutata/libnode (LAKUTATA_LIBNODE_MIRROR: a mirror of
+ * them), once: its archives are checked with the SHA256SUMS of the release and kept in the cache
+ * (~/.cache/lakutata/mobile, LAKUTATA_CACHE_DIR). LAKUTATA_MOBILE_NODE_DIR gives exports of a libnode of your own instead
+ * (a directory per system: android, ios, harmony; built with the repository of lakutata/libnode)
+ * @param options
+ * @returns the directory of the export: its headers (include/node) and its libraries (libs/<abi>/libnode.so) or its
+ * framework (NodeMobile.xcframework)
+ * @example
+ * import {downloadMobileNode} from '@lakutata/builder'
+ *
+ * const directory = await downloadMobileNode({platform: 'android', abis: ['arm64-v8a'], progress: console.log})
+ * console.log(directory)
+ */
+export async function downloadMobileNode(options) {
+    const given = process.env.LAKUTATA_MOBILE_NODE_DIR;
+    if (given) {
+        const directory = path.resolve(given, options.platform);
+        checkMobileNode(options.platform, directory);
+        return directory;
+    }
+    //The archives by architecture: the ABI of their library in the export
+    const archives = options.platform === 'ios'
+        ? [['libnode_ios_arm64', undefined]]
+        : options.platform === 'harmony'
+            ? Object.entries(HARMONY_ABIS).map(([abi, { arch }]) => [`libnode_harmony_${arch}`, abi])
+            : [...new Set(options.abis ?? ['arm64-v8a', 'x86_64'])].map((abi) => {
+                if (!ANDROID_ABIS[abi])
+                    throw new Error(`${abi} is not an architecture of Android (${Object.keys(ANDROID_ABIS).join(', ')})`);
+                return [`libnode_android_${ANDROID_ABIS[abi].arch}`, abi];
+            });
+    const target = path.join(cacheDirectory(), 'mobile', 'node', MOBILE_NODE_RELEASE, [options.platform, ...archives.map(([, abi]) => abi ?? '')].filter(Boolean).join('-'));
+    if (existsSync(path.join(target, '.complete')))
+        return target;
+    //The checksums of the release, read once and only when an archive is downloaded
+    let sums;
+    const checksums = () => sums ??= (async () => {
+        const response = await fetch(`${libnodeMirror()}/v${MOBILE_NODE_RELEASE}/SHA256SUMS`).catch((error) => {
+            throw new Error(`The checksums of the release ${MOBILE_NODE_RELEASE} of libnode cannot be downloaded (${error.message}): a mirror of the releases of lakutata/libnode is given by LAKUTATA_LIBNODE_MIRROR`);
+        });
+        if (!response.ok)
+            throw new Error(`The checksums of the release ${MOBILE_NODE_RELEASE} of libnode cannot be downloaded (${response.url}: ${response.status})`);
+        return new Map((await response.text()).split('\n').map((line) => /^([0-9a-f]{64})\s+\*?(\S+)$/.exec(line.trim())).filter((match) => !!match).map((match) => [match[2], match[1]]));
+    })();
+    const extracted = [];
+    for (const [name, abi] of archives)
+        extracted.push([await libnodeArchive(name, checksums, options.progress), abi]);
+    //The export: the headers and the description of the first archive, the library of each architecture
+    await mkdir(path.dirname(target), { recursive: true });
+    const temporary = await mkdtemp(`${target}.`);
+    try {
+        const [first] = extracted[0];
+        await cp(path.join(first, 'include'), path.join(temporary, 'include'), { recursive: true });
+        for (const file of ['LICENSE', 'libnode.json'])
+            if (existsSync(path.join(first, file)))
+                await cp(path.join(first, file), path.join(temporary, file));
+        for (const [directory, abi] of extracted) {
+            if (abi) {
+                await mkdir(path.join(temporary, 'libs', abi), { recursive: true });
+                await cp(path.join(directory, 'lib', 'libnode.so'), path.join(temporary, 'libs', abi, 'libnode.so'));
+            }
+            else
+                await cp(path.join(directory, 'NodeMobile.xcframework'), path.join(temporary, 'NodeMobile.xcframework'), { recursive: true, verbatimSymlinks: true });
+        }
+        checkMobileNode(options.platform, temporary);
+        await writeFile(path.join(temporary, '.complete'), '');
+        await moveIntoCache(temporary, target, () => existsSync(path.join(target, '.complete')));
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true });
+    }
+    return target;
+}

package/dist/esm/lib/mobile/Stage.js

@@ -0,0 +1,180 @@
+import { existsSync } from 'node:fs';
+import { lstat, mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { bundleProject } from '../Bundle.js';
+import { packNativeTree, writeNativeTree } from '../Native.js';
+import { BUN_NATIVE_ASSETS } from '../NativeRuntime.js';
+import { MOBILE_ADDONS_FILE, prepareAndroidAddons, prepareHarmonyAddons, prepareIosAddons } from './Addons.js';
+import { checkMobileNode, MOBILE_NODE_VERSION, mobileNodeVersion } from './Node.js';
+/**
+ * The package of a file of the native tree: the last one of the node_modules in its path
+ * @param file
+ */
+function packageOf(file) {
+    const parts = file.split('/');
+    const index = parts.lastIndexOf('node_modules');
+    if (index < 0)
+        return file;
+    return parts.slice(index + 1, parts[index + 1]?.startsWith('@') ? index + 3 : index + 2).join('/');
+}
+/**
+ * The files of the embedded native tree of HarmonyOS, next to the entry (names without a leading dot: the resources of
+ * the HAP leave those out)
+ */
+const NATIVE_DATA = 'native.gz';
+const NATIVE_INDEX = 'native.json';
+/**
+ * The entry of the Node.js project: the fetch() of Node.js put away without WebAssembly (V8 runs --jitless on
+ * HarmonyOS: its first call would throw an uncaught exception). The native tree embedded in the project (HarmonyOS) is
+ * given to the bundle, which extracts it at its first run into the directory LAKUTATA_NATIVE_DIR gives (the native
+ * module sets it). The addons of iOS and HarmonyOS are loaded from where the system keeps them (MOBILE_ADDONS_FILE: the
+ * frameworks of the application, the libraries of the HAP), in place of their placeholders in the tree. Then the
+ * application, bundled
+ */
+const ENTRY_SCRIPT = `//The entry of the application in the Node.js of the mobile application: fetch() put away without WebAssembly, the native tree embedded (HarmonyOS) given to the bundle, the native addons of iOS and HarmonyOS loaded from where the system keeps them, then the application, bundled
+const fs = require('fs')
+const path = require('path')
+if (typeof WebAssembly === 'undefined') delete globalThis.fetch
+const tree = path.join(__dirname, '${NATIVE_INDEX}')
+if (fs.existsSync(tree)) globalThis[Symbol.for('${BUN_NATIVE_ASSETS}')] = {data: path.join(__dirname, '${NATIVE_DATA}'), index: tree}
+const addons = path.join(__dirname, '${MOBILE_ADDONS_FILE}')
+if (fs.existsSync(addons)) {
+    //The placeholders are keyed by their paths in the tree, wherever the tree is (next to the bundle, extracted)
+    const {directory, files} = JSON.parse(fs.readFileSync(addons, 'utf8'))
+    const base = path.resolve(fs.realpathSync(__dirname), directory)
+    const keys = Object.keys(files)
+    const dlopen = process.dlopen
+    process.dlopen = function (module, filename, ...rest) {
+        let real
+        try {
+            real = fs.realpathSync(filename).split(path.sep).join('/')
+        } catch {
+            real = undefined
+        }
+        const key = real && keys.find((key) => real.endsWith('/' + key))
+        return dlopen.call(this, module, key ? path.join(base, files[key]) : filename, ...rest)
+    }
+}
+require('./app.cjs')
+`;
+/**
+ * The files of a native tree written in a directory, its links left out (they stay the links of the tree)
+ * @param directory
+ * @param base
+ */
+async function treeFiles(directory, base = directory) {
+    const files = [];
+    for (const entry of (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+        const file = path.join(directory, entry.name);
+        if (entry.isSymbolicLink())
+            continue;
+        if (entry.isDirectory())
+            files.push(...await treeFiles(file, base));
+        else if (entry.isFile())
+            files.push({ path: path.relative(base, file).split(path.sep).join('/'), source: file, mode: (await lstat(file)).mode & 0o777 });
+    }
+    return files;
+}
+/**
+ * Make the Node.js project of a mobile application of React Native (Android, iOS, HarmonyOS), which the native module
+ * of the application runs in its libnode: the bundle of the application (CommonJS, for the version of Node.js of the
+ * libnode) and its resources (lakutata.resources), its manifest and its entry. The bundle holds the dependencies: the
+ * project is packed into the application as it is. The native addons are built for the system from the sources of their
+ * packages, against the headers and the libraries of the libnode: on Android, a native tree per architecture (node-gyp
+ * and the NDK of Android); on iOS, a framework per addon for each SDK (node-gyp and Xcode), in the directory of the
+ * frameworks the project of iOS embeds; on HarmonyOS, a library per addon (node-gyp and the native SDK of HarmonyOS),
+ * in the libraries of the HAP
+ * @param options
+ * @example
+ * import {stageMobileApp} from '@lakutata/builder'
+ *
+ * //In packages/app of a project of the mobile-react template, before the application of Android is built
+ * const stage = await stageMobileApp({
+ *     platform: 'android',
+ *     outdir: '../../android/app/src/main/assets/nodejs',
+ *     node: '../ipc/native/node/out/android'
+ * })
+ * console.log(stage.directory, stage.node)
+ */
+export async function stageMobileApp(options) {
+    const project = path.resolve(options.project ?? process.cwd());
+    const manifestFile = path.join(project, 'package.json');
+    if (!existsSync(manifestFile))
+        throw new Error(`${project} has no package.json`);
+    const manifest = JSON.parse(await readFile(manifestFile, 'utf8'));
+    const directory = path.resolve(project, options.outdir);
+    //The directory is made again: never the project or a directory holding it
+    if (!path.relative(directory, project).startsWith('..'))
+        throw new Error(`The Node.js project of the mobile application is made in a directory of its own, not ${directory}`);
+    const node = options.node ? path.resolve(project, options.node) : undefined;
+    if (node)
+        checkMobileNode(options.platform, node);
+    const version = node ? mobileNodeVersion(node) : MOBILE_NODE_VERSION;
+    await rm(directory, { recursive: true, force: true });
+    await mkdir(directory, { recursive: true });
+    //The frameworks of the addons of iOS made before for the SDKs built: made again, or none (the ones of the other SDK
+    //kept: the development builds for the simulators only); the libraries of the addons of HarmonyOS made before
+    const frameworks = options.platform === 'ios' && options.frameworks ? path.resolve(project, options.frameworks) : undefined;
+    if (frameworks)
+        for (const sdk of options.sdks?.length ? options.sdks : ['iphoneos', 'iphonesimulator'])
+            await rm(path.join(frameworks, sdk), { recursive: true, force: true });
+    const libraries = options.platform === 'harmony' && options.libraries ? path.resolve(project, options.libraries) : undefined;
+    if (libraries && existsSync(libraries)) {
+        for (const name of await readdir(libraries))
+            if (/^libaddon-.*\.so$/.test(name))
+                await rm(path.join(libraries, name), { force: true });
+    }
+    //The resources of the HAP of HarmonyOS leave out the files whose names start with a dot (the .lakutata of the native
+    //tree): there the tree is embedded, packed into the project, extracted at run time
+    const harmony = options.platform === 'harmony';
+    const bundle = await bundleProject({
+        project: project,
+        entry: options.entry,
+        outfile: path.join(directory, 'app.cjs'),
+        node: version,
+        minify: options.minify ?? true,
+        external: ['@lakutata/netif', ...options.external ?? []],
+        native: harmony ? 'embedded' : 'directory',
+        directories: { native: 'app.native', resources: 'resources' }
+    });
+    //The tree its addons are built in: next to the bundle, or written there to be packed (HarmonyOS)
+    const tree = harmony && bundle.native ? path.join(directory, 'app.native') : bundle.nativeDirectory;
+    if (harmony && bundle.native)
+        await writeNativeTree(bundle.native, tree);
+    //The native tree holds the scripts of the workers too: its addons only are built
+    const files = bundle.native?.files ?? [];
+    const addonFiles = files.map((file) => file.path).filter((file) => file.endsWith('.node'));
+    let addons;
+    if (addonFiles.length) {
+        const packages = [...new Set(addonFiles.map(packageOf))].join(', ');
+        try {
+            if (!node)
+                throw new Error(`The native addons of the application are built against the libnode of ${options.platform}: give the directory of its export to the stage (node; ${packages})`);
+            if (options.platform === 'ios' && !frameworks)
+                throw new Error(`The native addons of the application are built for iOS into the frameworks the project of iOS embeds: give their directory (frameworks) to the stage (${packages})`);
+            if (options.platform === 'harmony' && !libraries)
+                throw new Error(`The native addons of the application are built for HarmonyOS into the libraries of the HAP: give their directory (libraries) to the stage (${packages})`);
+            if (options.platform === 'ios')
+                addons = await prepareIosAddons(project, directory, tree, files, frameworks, node, { sdks: options.sdks, progress: options.progress });
+            else if (options.platform === 'harmony')
+                addons = await prepareHarmonyAddons(project, directory, tree, files, libraries, node, { progress: options.progress });
+            else
+                addons = await prepareAndroidAddons(project, tree, files, node, { abis: options.abis, progress: options.progress });
+        }
+        catch (error) {
+            await rm(directory, { recursive: true, force: true });
+            throw error;
+        }
+    }
+    if (harmony && bundle.native) {
+        //Packed as the tree of an executable of Bun: the bundle extracts it as it is (its hash names the directory)
+        const links = bundle.native.links;
+        const packed = packNativeTree({ ...bundle.native, files: await treeFiles(tree), links: links });
+        await writeFile(path.join(directory, NATIVE_DATA), packed.data);
+        await writeFile(path.join(directory, NATIVE_INDEX), JSON.stringify(packed.index));
+        await rm(tree, { recursive: true, force: true });
+    }
+    await writeFile(path.join(directory, 'package.json'), `${JSON.stringify({ name: manifest.name ?? 'app', version: manifest.version ?? '0.0.0', private: true, main: 'main.js' }, null, 2)}\n`);
+    await writeFile(path.join(directory, 'main.js'), ENTRY_SCRIPT);
+    return { directory: directory, platform: options.platform, node: version, bundle: bundle, addons: addons };
+}