@lakutata/builder 3.0.0-beta.0

package/dist/types/lib/Executable.d.ts

@@ -0,0 +1,50 @@
+import { type BundleOptions } from './Bundle.js';
+export type ExecutableOptions = Omit<BundleOptions, 'outfile' | 'native' | 'directories'> & {
+    /**
+     * The directory of the executable, dist by default
+     */
+    outdir?: string;
+    /**
+     * One file, its native tree and its resources embedded, extracted at its first run (by default); or a directory, the
+     * executable and its native tree (native) and its resources (resources) next to it, loaded from there (the
+     * installers, the images)
+     */
+    layout?: 'file' | 'directory';
+};
+export type ExecutableResult = {
+    name: string;
+    /**
+     * The executable, and its platform ("darwin-arm64")
+     */
+    file: string;
+    platform: string;
+    size: number;
+    /**
+     * The packages of native addons embedded, extracted at the first run, or next to the executable
+     */
+    native: string[];
+    /**
+     * The resources of the application (their paths in the resources)
+     */
+    resources: string[];
+    /**
+     * The directory of the executable, its native tree and its resources (the layout directory)
+     */
+    directory?: string;
+    /**
+     * The runtime embedded in the executable, and its version ("Node.js v24.11.1", "Bun 1.4.2")
+     */
+    runtime: string;
+    /**
+     * What to do before distributing the executable (sign it)
+     */
+    warnings: string[];
+};
+/**
+ * Make the executable of the application for the platform it is made on, which runs without Node.js installed: its bundle
+ * embedded in the Node.js binary running the tool (the single executable applications of Node.js), or compiled by Bun.
+ * The executables of the other platforms are made on them (their native addons are built there), as the applications are
+ * built there
+ * @param options
+ */
+export declare function buildExecutable(options: ExecutableOptions): Promise<ExecutableResult>;

package/dist/types/lib/Icons.d.ts

@@ -0,0 +1,70 @@
+/**
+ * An image: its pixels, red, green, blue and alpha (8 bits each), by rows
+ */
+export type Image = {
+    width: number;
+    height: number;
+    pixels: Buffer;
+};
+/**
+ * Decode a PNG file (not interlaced): its pixels in RGBA, whatever its colors (gray, RGB, palette, with alpha) and its
+ * depth (1 to 16 bits)
+ * @param data
+ * @param file its name, in the errors
+ */
+export declare function decodePng(data: Buffer, file?: string): Image;
+/**
+ * Encode an image into a PNG file (RGBA, 8 bits)
+ * @param image
+ */
+export declare function encodePng(image: Image): Buffer;
+/**
+ * Resize an image (a square into a square): each pixel the average of the ones it covers, weighted by their alpha
+ * (premultiplied, the transparent edges keep their colors)
+ * @param image
+ * @param size
+ */
+export declare function resize(image: Image, size: number): Image;
+/**
+ * The sizes of the icons of Windows (ico)
+ */
+export declare const ICO_SIZES: number[];
+/**
+ * The icon of Windows (ico) of an image, in its sizes: the bitmaps of the ones smaller than 256 (the format every tool
+ * reads: the resources of the executables, NSIS, Windows Installer), the PNG of 256
+ * @param image
+ */
+export declare function icoFile(image: Image): Buffer;
+/**
+ * The icon of macOS (icns) of an image: its PNG in the sizes of macOS, but the ones larger than it
+ * @param image
+ */
+export declare function icnsFile(image: Image): Buffer;
+/**
+ * The sizes of the icons of Linux (the hicolor theme)
+ */
+export declare const LINUX_SIZES: number[];
+/**
+ * Write the icons of Linux of an image into a directory: its PNG in the sizes of the hicolor theme (<size>x<size>.png),
+ * but the ones larger than it
+ * @param image
+ * @param directory
+ */
+export declare function writeLinuxIcons(image: Image, directory: string): Promise<string[]>;
+/**
+ * Give an executable of Windows the icon (ico), as its icon groups (the one of node.exe), its signature removed (it does
+ * not match it anymore)
+ * @param file
+ * @param ico
+ */
+export declare function setExecutableIcon(file: string, ico: Buffer): Promise<void>;
+/**
+ * The icon of the application (lakutata.icon of its package.json): a square PNG image, 256 pixels at least (1024 for
+ * the Retina screens of macOS), undefined without icon
+ * @param project
+ * @param manifest
+ */
+export declare function applicationIcon(project: string, manifest: Record<string, any>): {
+    file: string;
+    image: Image;
+} | undefined;

package/dist/types/lib/Installer.d.ts

@@ -0,0 +1,242 @@
+import { type ExecutableResult } from './Executable.js';
+import { type InstallerScripts, type NativeScripts, type TargetScripts } from './Scripts.js';
+import { type LinuxTarget } from './linux/Linux.js';
+import { type MacTarget } from './mac/Mac.js';
+import { type WindowsTarget } from './win/Windows.js';
+/**
+ * The service an installer registers (systemd, OpenRC): the application runs at the start of the system
+ */
+export type ServiceOptions = {
+    /**
+     * The name of the service, the one of the package by default
+     */
+    name?: string;
+    description?: string;
+    /**
+     * The arguments of the application
+     */
+    args?: string[];
+    /**
+     * Its environment, written to the environment file of the service (/etc/<name>/<name>.env), which the
+     * administrators change: MODE=production by default
+     */
+    env?: Record<string, string>;
+    /**
+     * The user running it: a system user named after the package by default (created by the installer), or root; on
+     * Windows, its virtual account by default (NT SERVICE\<service>), LocalService, NetworkService or LocalSystem
+     */
+    user?: string;
+    /**
+     * Whether it is started again when it exits: on-failure (by default), always or no
+     */
+    restart?: 'on-failure' | 'always' | 'no';
+    /**
+     * Whether it is enabled and started by the installation (by default), or by the administrators
+     */
+    autoStart?: boolean;
+};
+/**
+ * The installers of an application, declared by the "lakutata.installer" of its package.json (as the configuration of
+ * electron-builder)
+ */
+export type InstallerConfig = {
+    /**
+     * The name of the package (lower case), the one of the program by default
+     */
+    name?: string;
+    /**
+     * The identifier of the application (reverse DNS: com.acme.app), its name by default: the identifier of the package
+     * of macOS and the label of its service (launchd), the key of its uninstaller and of its upgrades on Windows
+     */
+    appId?: string;
+    /**
+     * The name of the application shown to the users (the installers, the programs of Windows), its name by default
+     */
+    productName?: string;
+    /**
+     * The description, the maintainer, the home page and the license: the ones of the package.json by default
+     */
+    description?: string;
+    maintainer?: string;
+    homepage?: string;
+    license?: string;
+    vendor?: string;
+    /**
+     * The runtime of the executable: node (by default) or bun; electron for the Electron applications, whose installers
+     * are made by electron-builder
+     */
+    runtime?: 'node' | 'bun' | 'electron';
+    /**
+     * The configuration of electron-builder of an Electron application, merged over the one made from lakutata.installer
+     */
+    electron?: Record<string, unknown>;
+    /**
+     * Whether the program is in the PATH of the system (/usr/bin/<program>), by default
+     */
+    addToPath?: boolean;
+    /**
+     * The service of the application, none by default
+     */
+    service?: boolean | ServiceOptions;
+    linux?: {
+        /**
+         * The packages: deb, rpm and tar.gz on the systems of the glibc, apk and tar.gz on the ones of musl (Alpine) by
+         * default
+         */
+        targets?: LinuxTarget[];
+        /**
+         * The packages of the system it needs
+         */
+        depends?: string[];
+        recommends?: string[];
+        section?: string;
+        priority?: string;
+        /**
+         * The scripts the packages run (sh), given install, upgrade or remove
+         */
+        scripts?: InstallerScripts;
+        /**
+         * The ones of each package, replacing them; its native scripts, run as nFPM gives them to the package (with its
+         * own arguments)
+         */
+        deb?: {
+            scripts?: InstallerScripts;
+            nativeScripts?: NativeScripts;
+        };
+        rpm?: {
+            scripts?: InstallerScripts;
+            nativeScripts?: NativeScripts;
+        };
+        apk?: {
+            scripts?: InstallerScripts;
+            nativeScripts?: NativeScripts;
+        };
+        archlinux?: {
+            scripts?: InstallerScripts;
+            nativeScripts?: NativeScripts;
+        };
+    };
+    mac?: {
+        /**
+         * The installers: pkg and tar.gz by default
+         */
+        targets?: MacTarget[];
+        /**
+         * The scripts the package runs (sh), given install, upgrade or remove (the removal is the one of its uninstall
+         * script)
+         */
+        scripts?: InstallerScripts;
+        pkg?: {
+            scripts?: InstallerScripts;
+        };
+    };
+    win?: {
+        /**
+         * The installers: nsis, msi and zip by default
+         */
+        targets?: WindowsTarget[];
+        /**
+         * The scripts the installers run (PowerShell, .ps1), given install, upgrade or remove
+         */
+        scripts?: InstallerScripts;
+        /**
+         * The ones of the installer of NSIS, replacing them; the file of NSIS it includes (.nsh), its macros inserted
+         * (customHeader, customInit, customInstall, customUnInit, customUnInstall)
+         */
+        nsis?: {
+            scripts?: InstallerScripts;
+            include?: string;
+        };
+        msi?: {
+            scripts?: InstallerScripts;
+        };
+    };
+};
+export type InstallerOptions = {
+    /**
+     * The directory of the project (its package.json)
+     */
+    project: string;
+    entry?: string;
+    minify?: boolean;
+    external?: string[];
+    /**
+     * The packages made, the ones of the configuration by default
+     */
+    targets?: string[];
+    /**
+     * The directory of the packages, dist/installer by default
+     */
+    outdir?: string;
+};
+export type InstallerResult = {
+    name: string;
+    version: string;
+    /**
+     * The packages made
+     */
+    files: {
+        target: string;
+        file: string;
+        size: number;
+    }[];
+    /**
+     * The executable they install
+     */
+    executable: ExecutableResult;
+    warnings: string[];
+};
+/**
+ * What an installer installs, resolved from the configuration
+ */
+export type InstallerPlan = {
+    /**
+     * The name of the package, its identifier, the name of the program, the version
+     */
+    name: string;
+    appId: string;
+    productName: string;
+    program: string;
+    version: string;
+    description: string;
+    maintainer: string;
+    homepage?: string;
+    license?: string;
+    vendor?: string;
+    addToPath: boolean;
+    service?: Required<Omit<ServiceOptions, 'description'>> & {
+        description: string;
+    };
+    /**
+     * The packages of the system it needs and recommends, its section and its priority (deb)
+     */
+    depends: string[];
+    recommends: string[];
+    section?: string;
+    priority?: string;
+    /**
+     * The directory of the executable, its native addons and its resources
+     */
+    directory: string;
+    /**
+     * Where it is installed (/opt/<name> on Linux, /usr/local/lib/<name> on macOS)
+     */
+    prefix: string;
+    /**
+     * The scripts of the application each installer runs
+     */
+    scripts: Record<string, TargetScripts>;
+    /**
+     * The icon of the installers of Windows and of their application (ico), made from the icon of the application
+     * (lakutata.icon), none without it
+     */
+    icon?: string;
+};
+/**
+ * Make the installers of the application for the platform it is made on (the installers of the other platforms are
+ * made on them, as its executables): its executable in a directory, with its native addons and its resources, installed
+ * in /opt/<name> (Linux) or /usr/local/lib/<name> (macOS), its program in the PATH, its service registered (systemd,
+ * OpenRC, launchd)
+ * @param options
+ */
+export declare function buildInstaller(options: InstallerOptions): Promise<InstallerResult>;

package/dist/types/lib/Native.d.ts

@@ -0,0 +1,196 @@
+import type { Plugin, PluginBuild } from 'esbuild';
+/**
+ * A file of the native tree: its path in the tree ("/" separated) and where it is read
+ */
+export type NativeFile = {
+    path: string;
+    source: string;
+    mode: number;
+};
+/**
+ * A link of the native tree to a directory of the tree, as the links of the node_modules (pnpm, the workspaces)
+ */
+export type NativeLink = {
+    path: string;
+    target: string;
+};
+/**
+ * The native addons of an application and what they need at run time, which cannot be bundled: their packages (and
+ * the packages they load), laid out as node lays them out, loaded from the disk.
+ * The tree is the layout of the packages from the directory of their node_modules (the project, the workspace): node
+ * finds them there as it finds them in the project; the links of the tree are the ones of the project (the packages of
+ * the workspace, pnpm) and the packages the application loads which are not in its node_modules. The addons loaded by the
+ * application itself are in .lakutata/addons
+ */
+export type NativeTree = {
+    /**
+     * The packages the application loads from the tree
+     */
+    modules: string[];
+    files: NativeFile[];
+    links: NativeLink[];
+    /**
+     * The hash of the tree, which names the directory it is extracted into
+     */
+    hash: string;
+};
+/**
+ * The index of a packed native tree
+ */
+export type NativeIndex = {
+    hash: string;
+    files: {
+        path: string;
+        offset: number;
+        size: number;
+        mode: number;
+    }[];
+    links: NativeLink[];
+};
+type PackageInfo = {
+    root: string;
+    name: string;
+    manifest: Record<string, any>;
+    addons: boolean;
+    libraries: boolean;
+};
+/**
+ * The name of the package of a module specifier ("@scope/name/sub/path" → "@scope/name"), undefined for a path
+ * @param specifier
+ */
+export declare function specifierPackage(specifier: string): string | undefined;
+/**
+ * Find the native addons of an application while it is bundled: the packages holding addons (and the packages loading
+ * them with computed paths, such as sharp) are left out of the bundle and gathered, with the packages they load, into
+ * a native tree; the addons of the application itself are loaded from the tree
+ */
+export declare class NativeCollector {
+    protected readonly project: string;
+    protected readonly runtime: 'node' | 'bun';
+    protected readonly packages: Map<string, PackageInfo | undefined>;
+    protected readonly roots: Map<string, string | undefined>;
+    /**
+     * The packages left out of the bundle, by the name the application loads them with, and the files it loads
+     */
+    protected readonly externals: Map<string, {
+        root: string;
+        entries: Set<string>;
+    }>;
+    /**
+     * The addons of the application itself, by their key in the tree
+     */
+    protected readonly addons: Map<string, string>;
+    /**
+     * The files of the packages of the tree which are loaded, by package (traced)
+     */
+    protected readonly loaded: Map<string, Set<string>>;
+    /**
+     * The packages of the tree kept as a whole: the ones which are not traced, the ones loading their files by paths
+     * esbuild cannot follow
+     */
+    protected readonly whole: Set<string>;
+    /**
+     * The packages each package of the tree requires, by their names (traced)
+     */
+    protected readonly required: Map<string, Map<string, string>>;
+    /**
+     * @param project the directory of the project, whose files are bundled
+     * @param runtime the runtime loading the tree: Bun resolves the packages with its condition (bun) first
+     */
+    constructor(project: string, runtime?: 'node' | 'bun');
+    /**
+     * The directory of the package a file belongs to: the nearest directory with a named package.json
+     * @param file
+     */
+    protected packageRoot(file: string): string | undefined;
+    /**
+     * A package: its manifest and whether it holds addons or shared libraries
+     * @param root
+     */
+    protected package(root: string): PackageInfo | undefined;
+    /**
+     * The dependencies of a package, as node finds them from it: the path looked up (a link with pnpm) and the package
+     * @param root
+     */
+    protected dependencies(root: string): {
+        name: string;
+        lookup: string;
+        root: string;
+    }[];
+    /**
+     * Whether a package is left out of the bundle: it holds addons, or one of its dependencies does (it loads them,
+     * with computed paths often), and it is not the project
+     * @param root
+     */
+    protected isNative(root: string | undefined): root is string;
+    /**
+     * Resolve an import as esbuild does
+     * @param build
+     * @param args
+     */
+    protected resolve(build: PluginBuild, args: {
+        path: string;
+        kind: any;
+        resolveDir: string;
+        importer: string;
+    }): Promise<string | undefined>;
+    /**
+     * The plugin of the bundle: the native packages are external, the addons of the application are loaded from the tree
+     */
+    plugin(): Plugin;
+    /**
+     * The packages a native package loads at run time: the JavaScript it requires (followed by esbuild), the packages of
+     * shared libraries it depends on (the libraries linked with its addons), and the native packages it loads
+     * @param build the build function of esbuild
+     * @param root
+     * @param entries the files of the package which are loaded
+     * @param included the packages of the tree
+     */
+    protected trace(build: typeof import('esbuild').build, root: string, entries: Set<string>, included: Set<string>): Promise<void>;
+    /**
+     * The packages a package requires, by their names
+     * @param root
+     */
+    protected requires(root: string): Map<string, string>;
+    /**
+     * The layout of the packages of the tree, without links (as npm installs them, the tree is moved, copied, archived
+     * and installed as it is): the packages the application loads in node_modules, the packages each package requires
+     * (traced) or declares where node finds them from it: shared when node finds the same package, at the top when its
+     * name is free there, else in the node_modules of the package
+     * @param included the packages of the tree
+     * @return the packages by their directories in the tree
+     */
+    protected layout(included: Set<string>): Map<string, string>;
+    /**
+     * The files of a package of the tree which are loaded at run time, without the ones node never loads (UNUSED): the
+     * packages of shared libraries (which find their addons by computed paths), and the ones kept as a whole, have all
+     * their files; the others have the JavaScript files they load (traced) and all their other files (the data they read)
+     * @param root
+     */
+    protected packageFiles(root: string): string[];
+    /**
+     * The native tree of the application, once it is bundled; undefined when it has no native addon
+     */
+    collect(): Promise<NativeTree | undefined>;
+}
+/**
+ * The hash of a native tree, which names the directory it is extracted into: its files and their content, its links
+ * @param files
+ * @param links
+ */
+export declare function hashNativeTree(files: NativeFile[], links: NativeLink[]): string;
+/**
+ * Write a native tree into a directory (next to a bundle)
+ * @param tree
+ * @param directory
+ */
+export declare function writeNativeTree(tree: NativeTree, directory: string): Promise<void>;
+/**
+ * Pack a native tree into the assets of an executable: its gzipped files and their index
+ * @param tree
+ */
+export declare function packNativeTree(tree: NativeTree): {
+    index: NativeIndex;
+    data: Buffer;
+};
+export {};

package/dist/types/lib/NativeRuntime.d.ts

@@ -0,0 +1,75 @@
+/**
+ * What the require of a bundle knows of its native tree
+ */
+export type NativeRuntimeConfig = {
+    /**
+     * The name of the program, which names its cache directory
+     */
+    name: string;
+    /**
+     * The hash of the tree, which names the directory it is extracted into
+     */
+    hash: string;
+    /**
+     * The directory of the tree next to the bundle (the bundles run by node), or in the resources of a packaged Electron
+     * application
+     */
+    directory: string;
+    /**
+     * The packages loaded from the tree
+     */
+    modules: string[];
+    /**
+     * Whether the tree is embedded in an executable, extracted at its first run (with the resources of the application,
+     * in its .lakutata/resources), or a directory next to the bundle
+     */
+    embedded: boolean;
+};
+/**
+ * The global symbol of the packed applications giving the directory of their resources (resourcesPath of lakutata)
+ */
+export declare const PACKAGED: string;
+/**
+ * The directory of the resources of the embedded trees
+ */
+export declare const EMBEDDED_RESOURCES: string;
+/**
+ * The asset of the executables holding the files of the native tree (gzipped), and the one of its index
+ */
+export declare const NATIVE_DATA_ASSET: string;
+export declare const NATIVE_INDEX_ASSET: string;
+/**
+ * The global symbol of the executables of Bun giving the files of the native tree they embed: {data, index}, their paths
+ * in the executable
+ */
+export declare const BUN_NATIVE_ASSETS: string;
+/**
+ * The require of a bundle having native addons, which loads the native packages from the native tree: next to the bundle,
+ * or, in an executable, extracted from its assets once into the cache directory of the program (a directory named after
+ * the hash of the tree: the versions of the program do not share it). The assets are the ones of a single executable
+ * application of Node.js, or the files embedded in an executable of Bun. The other modules are loaded by the require of node.
+ * Its source is written at the top of the bundle: it uses nothing but its arguments and the modules of node
+ * @param nodeRequire
+ * @param config
+ */
+export declare function lakutataNativeRequire(nodeRequire: NodeJS.Require, config: NativeRuntimeConfig): NodeJS.Require;
+/**
+ * Load the environment file of the application into its environment, before it starts: the file given by
+ * LAKUTATA_ENV_FILE (the services of Windows, whose wrapper has none), its lines NAME=value or NAME="value" (the
+ * quoted values with their \\ escapes, as the installers write them), its comments (#). Its source is written at the top
+ * of the bundle: it uses nothing but its argument and the modules of node
+ * @param nodeRequire
+ */
+export declare function lakutataEnvironmentFile(nodeRequire: NodeJS.Require): void;
+/**
+ * The source given to the top of every bundle: it is packed (isPackaged of lakutata), its resources are in a directory
+ * next to it, or in the resources of a packaged Electron application (outside of its archive); its environment file is
+ * loaded (LAKUTATA_ENV_FILE)
+ * @param directory the directory of the resources, relative to the bundle
+ */
+export declare function packagedBanner(directory: string): string;
+/**
+ * The source given to the top of a bundle: its require loads the native packages from the tree
+ * @param config
+ */
+export declare function nativeBanner(config: NativeRuntimeConfig): string;

package/dist/types/lib/Platform.d.ts

@@ -0,0 +1,4 @@
+/**
+ * The C library of Linux: the executables made on it run on the systems of the same library (undefined out of Linux)
+ */
+export declare function detectLibc(): 'glibc' | 'musl' | undefined;

package/dist/types/lib/Processes.d.ts

@@ -0,0 +1,21 @@
+import { type ChildProcess, type SpawnOptions } from 'node:child_process';
+/**
+ * Spawn a command: on Windows, the commands found in the PATH by their names (the package managers, the commands of npm:
+ * npm.cmd, bun.cmd) are scripts, run by cmd.exe with their arguments quoted; the executables given by their paths (the
+ * ones of spaces: C:\Program Files\nodejs\node.exe) are run as they are
+ * @param command
+ * @param args
+ * @param options
+ */
+export declare function spawnCommand(command: string, args: string[], options: SpawnOptions): ChildProcess;
+/**
+ * Run a command, its output is given back
+ * @param command
+ * @param args
+ * @param cwd
+ * @return the exit code and the output
+ */
+export declare function runCommand(command: string, args: string[], cwd: string): Promise<{
+    code: number;
+    output: string;
+}>;