seabox 0.1.0-beta.3 → 0.1.0

package/README.md

@@ -1,22 +1,23 @@
 # seabox
 
-A reusable tool for building Node.js Single Executable Applications (SEA) with native-module support.
+A reusable tool for building Node.js Single Executable Applications (SEA) with native-module support and binary extraction. 
 
 ## Features
 
 - Bundle Node.js applications into standalone executables
-- Automatic native module (.node, .dll, .so, .dylib) extraction and loading
-- Asset encryption with obfuscated keys embedded in V8 snapshots
+- **Automatic asset detection** from `path.join(__dirname, ...)` patterns
+- **Automatic native module detection** (.node files) with pattern transforms
+- Platform-specific library extraction (DLLs, shared libraries)
+- Asset encryption with obfuscated keys
 - Multi-platform targeting (Windows, Linux, macOS)
 - V8 snapshot support for faster startup
 - Integrity checking for extracted binaries
 - Automatic code signature removal before injection
-- Simple configuration via package.json
 
 ## Use case
-This tooling was created as an alternative to pkg, which is unfortunatly deprecated, and where forks were running foul of virus checkers. By using node's SEA, the executables are directly from nodejs's distribution source, and built using node's native Single Executable Application solution. Unfortunatly this does mean native modules embedded within the exe cannot run directly and must be extracted to a location on the disk on first run - This tooling automates that process for you, while providing arbitrary asset embedding. Embedded assets are _not_ extracted and access to them is handled by intercepting require and fs.  
+This tooling was created as an alternative to pkg, which is unfortunatly deprecated, and where forks were running foul of virus checkers. By using node's SEA, the executables are directly downloaded from nodejs's distribution source, and built using node's native Single Executable Application solution. Unfortunatly this does mean native modules embedded within the exe cannot run directly and must be extracted to a location on the disk on first run - This tooling automates that process for you, while providing arbitrary asset embedding. Embedded assets are _not_ extracted and access to them is handled by intercepting require and fs.  
 
-Note: **V8 snapshot includes and embedds the original source**, this is currently a limitation of Node's SEA tooling as far as I can tell; thus the snapshot is only useful for faster startup.  
+Note: **V8 snapshot includes and embedds the original source**, this is currently a limitation of Node's SEA tooling as far as I can tell; thus the snapshot is only useful for faster startup. Its possible to get around this by using bytenode's vm.script hack (embed the bytenode code as an asset and run another vm snapshot with the faux script input) and I'll look into supporting it in the future. 
 
 ## Installation
 
@@ -26,65 +27,82 @@ npm install --save-dev seabox
 
 ## Configuration
 
-Add a `sea` configuration to your `package.json`:
+Create a `seabox.config.json` file in your project root:
 
 ```json
 {
-  "sea": {
-    "entry": "./out/server.js",
-    "assets": [
-      "./out/client/**/*",
-      "./out/lib/**/*",
-      "./out/native/**/*",
-      "!**/*.md",
-      "!**/test/**"
-    ],
-    "binaries": [
-      "*.node",
-      "*.dll"
-    ],
-    "targets": [
-      "node24.11.0-win32-x64"
-    ],
-    "output": "myapp.exe",
-    "outputPath": "dist",
-    "disableExperimentalSEAWarning": true,
-    "useSnapshot": true,
-    "useCodeCache": false
-  }
+  "entry": "./src/index.js",
+  "outputs": [
+    {
+      "path": "./dist/win",
+      "target": "node24.11.0-win32-x64",
+      "output": "myapp.exe"
+    }
+  ],
+  "bundler": {
+    "external": []
+  },
+  "encryptAssets": false,
+  "useSnapshot": true,
+  "verbose": false
 }
 ```
 
 ## Configuration Options
 
-- **entry**: Path to your bundled application entry point
-- **assets**: Array of glob patterns for files to include (supports `!` prefix for exclusions, e.g., `"!**/*.md"`)
-- **binaries**: Patterns to identify binary files that need extraction (e.g., `.node`, `.dll`)
-- **targets**: Array of target platforms (format: `nodeX.Y.Z-platform-arch`)
-- **output**: Name of the output executable
-- **outputPath**: Directory for build output
-- **disableExperimentalSEAWarning**: Suppress Node.js SEA experimental warnings (default: true)
-- **useSnapshot**: Enable V8 snapshot for faster startup (default: false)
-- **useCodeCache**: Enable V8 code cache (default: false)
-- **encryptAssets**: Enable encryption for assets (default: false)
-- **encryptExclude**: Patterns to exclude from encryption (e.g., `['*.txt']`)
-- **rebuild**: Automatically rebuild native modules for the target platform before building the SEA (default: false)
-- **rcedit**: (Windows only) Customize executable icon and version information. See [rcedit options](#windows-executable-customization-rcedit)
-- **cacheLocation**: Custom cache directory for extracted binaries (default: `'./.sea-cache'`). Supports environment variable expansion (e.g., `'%LOCALAPPDATA%\\myapp-cache'` on Windows or `'$HOME/.cache/myapp'` on Unix)
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `entry` | `string` | Yes | Path to your application's entry point |
+| `outputs` | `array` | Yes | Array of build targets |
+| `outputs[].path` | `string` | Yes | Output directory for this target |
+| `outputs[].target` | `string` | Yes | Build target (format: `nodeX.Y.Z-platform-arch`) |
+| `outputs[].output` | `string` | Yes | Output filename |
+| `outputs[].libraries` | `array` | No | Explicit glob patterns for shared libraries (DLLs/SOs) requiring filesystem extraction. Libraries referenced in code via `, ...)` are automatically detected. |
+| `outputs[].rcedit` | `object` | No | Windows executable metadata (icon, version info) |
+| `assets` | `array` | No | Glob patterns for assets to embed (merged with auto-detected assets) |
+| `bundler` | `object` | No | Rolldown Bundler options |
+| `bundler.external` | `array` | No | Modules to exclude from bundling |
+| `bundler.plugins` | `array` | No | Additional Rolldown plugins |
+| `bundler.minify` | `boolean` | No | Minify bundled code |
+| `bundler.sourcemap` | `boolean` | No | Generate source maps |
+| `encryptAssets` | `boolean` | No | Enable asset encryption (default: false) |
+| `encryptExclude` | `array` | No | Glob patterns to exclude from encryption |
+| `useSnapshot` | `boolean` | No | Enable V8 startup snapshots (default: true) |
+| `useCodeCache` | `boolean` | No | Enable V8 code cache (default: false) |
+| `cacheLocation` | `string` | No | Path for code cache storage |
+| `sign` | `string` | No | Path to custom signing script (.mjs/.cjs) |
+| `verbose` | `boolean` | No | Enable verbose logging (default: false) |
 
 ## Usage
 
-After installing `seabox` as a dev dependency and configuring your `package.json`, build your SEA executable:
+### CLI Commands
+
+```bash
+# Build executable(s)
+npx seabox build
+
+# Build with verbose output
+npx seabox build --verbose
+
+# Specify custom config file
+npx seabox build --config custom-config.json
 
-### npm script (recommended)
+# Initialize a new config file
+npx seabox init
 
-Add a build script to your `package.json`:
+# Show help
+npx seabox help
+```
+
+### npm Scripts (Recommended)
+
+Add to your `package.json`:
 
 ```json
 {
   "scripts": {
-    "build:exe": "seabox",
-    "build:exe:verbose": "seabox --verbose"
+    "build": "seabox build",
+    "build:verbose": "seabox build --verbose"
   }
 }
 ```
@@ -92,27 +110,13 @@ Add a build script to your `package.json`:
 Then run:
 
 ```bash
-npm run build:exe
-```
-
-### CLI
-
-```bash
-# Build using package.json configuration
-npx seabox
-
-# Build using a standalone config file (alternative to package.json)
-npx seabox --config sea-config.json
-
-# Verbose output
-npx seabox --verbose
-
+npm run build
 ```
 
 ### Programmatic API
 
 ```javascript
-const { build } = require('seabox');
+import { build } from 'seabox';
 
 await build({
   projectRoot: process.cwd(),
@@ -122,118 +126,139 @@ await build({
 
 ## How It Works
 
-1. **Asset Scanning**: Scans and resolves all files matching your asset patterns
-2. **Manifest Generation**: Creates a runtime manifest with metadata for binary extraction
-3. **Bootstrap Injection**: Prepends bootstrap code to handle native module extraction
-4. **Blob Creation**: Uses Node.js SEA tooling to create the application blob
-5. **Binary Fetching**: Downloads the target Node.js binary and removes its signature
-6. **Injection**: Uses postject to inject the blob into the Node binary
-7. **Output**: Produces a standalone executable ready for signing and distribution
+seabox automates the entire SEA build process:
 
-## Binary Extraction
+1. **Bundling** - Automatically bundles your app with Rolldown, detecting:
+   - Native module patterns (`bindings`, `node-gyp-build`, direct `.node` requires)
+   - Asset references via `path.join(__dirname, 'relative/path')`
+   - Additional 
 
-Native modules (`.node`, `.dll`, `.so`, `.dylib`) are automatically:
-- Extracted to a cache directory on first run
-- Integrity-checked using SHA-256 hashes
-- Loaded via custom module resolution
+2. **Asset Collection** - Gathers assets from three sources:
+   - **Auto-detected**: Files referenced via `path.join(__dirname, ...)` patterns
+   - **Config globs**: Patterns specified in `assets` array
+   - **Libraries**: Platform-specific shared libraries (DLLs/SOs)
 
-### Cache Location
+3. **Native Module Rebuilding** - Rebuilds native modules for target platform
 
-By default, binaries are extracted to: `./.sea-cache/<appname>/<version>-<platform>-<arch>`
+4. **Bootstrap Injection** - Adds runtime code for asset loading and native module extraction
 
-You can customize the cache location in your configuration:
+5. **SEA Blob Creation** - Packages everything using Node.js SEA tooling
 
-```json
-{
-  "sea": {
-    "cacheLocation": "%LOCALAPPDATA%\\myapp-cache"
-  }
-}
-```
+6. **Binary Preparation** - Downloads target Node.js binary and removes code signature
 
-The cache location supports environment variable expansion:
-- **Windows**: `%LOCALAPPDATA%`, `%APPDATA%`, `%TEMP%`, etc.
-- **Unix/Linux/macOS**: `$HOME`, `$TMPDIR`, `${XDG_CACHE_HOME}`, etc.
+7. **Injection** - Uses `postject` to inject the blob into the Node.js binary
 
-**Override at runtime**: Set the `SEACACHE` environment variable to override the configured location:
+8. **Output** - Produces standalone executable(s) ready for distribution
 
-```bash
-# Windows
-set SEACACHE=C:\custom\cache\path
-myapp.exe
+### Automatic Asset Detection
+
+**Like pkg**, seabox automatically detects and embeds assets referenced in your code:
+
+```javascript
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
-# Unix/Linux/macOS
-export SEACACHE=/custom/cache/path
-./myapp
+// This asset will be automatically detected and embedded
+const configPath = path.join(__dirname, '../config/app.json');
+const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
 ```
 
-## Native Module Rebuilding
+**Asset sources (merged and deduplicated):**
+1. **Auto-detected** from code analysis during bundling
+2. **Config globs** from `assets: ["./data/**/*", "./public/**/*"]`
+3. **Platform libraries** from `outputs[].libraries` (e.g., DLLs for Windows)
 
-If your project has native modules (e.g., `.node` bindings), you may need to rebuild them for the target Node.js version:
+### Native Module Support
 
-```bash
-# Rebuild for a specific target
-npx seabox-rebuild --target node24.11.0-win32-x64
+seabox automatically handles native modules without any configuration:
 
-# Rebuild with separate options
-npx seabox-rebuild --node-version 24.11.0 --platform linux --arch x64
+**Supported patterns:**
+- `require('bindings')('module')` - Standard bindings package
+- `require('./build/Release/addon.node')` - Direct requires
+- `require('node-gyp-build')(__dirname)` - Prebuild binaries
+- `require('node-pre-gyp')` patterns - Pre-compiled binaries
 
-# Rebuild in a specific directory
-npx seabox-rebuild /path/to/project --target node24.11.0-linux-x64
-```
+**At runtime:**
+- Native modules are extracted to a cache directory on first run
+- Modules are integrity-checked with SHA-256 hashes
+- Custom `require()` shim loads modules from cache
+
+### Platform-Specific Libraries
+
+Libraries that require filesystem access (like DLLs loaded via `dlopen`) can be included in two ways:
 
-The rebuilder will:
-- Scan all dependencies for native modules (those with `binding.gyp` or `gypfile: true`)
-- Rebuild each one using `node-gyp` for the target platform and Node.js version
-- Download necessary headers for cross-compilation
+**1. Automatic Detection (Recommended)**
 
-**Note**: Cross-compilation may require additional platform-specific build tools installed.
+If your code references a DLL using `path.join(__dirname, ...)`, it will be automatically detected and included:
+
+```javascript
+// This will be automatically detected during bundling
+const dllPath = path.join(__dirname, './lib/RGDevice.dll');
+```
 
-## Windows Executable Customization (rcedit)
+**2. Explicit Glob Patterns**
 
-For Windows executables, you can customize the icon and version information using the `rcedit` configuration option:
+You can also explicitly specify library patterns in your config:
 
 ```json
 {
-  "sea": {
-    "output": "myapp.exe",
-    "targets": ["node24.11.0-win32-x64"],
-    "rcedit": {
-      "icon": ".\\assets\\myapp.ico",
-      "file-version": "1.2.3.4",
-      "product-version": "1.2.3.4",
-      "version-string": {
-        "CompanyName": "My Company",
-        "FileDescription": "My Application",
-        "ProductName": "MyApp",
-        "InternalName": "myapp.exe",
-        "OriginalFilename": "myapp.exe",
-        "LegalCopyright": "Copyright (C) 2025 My Company"
-      }
+  "outputs": [
+    {
+      "target": "node24.11.0-win32-x64",
+      "libraries": ["lib/*.dll"]  // Manually specify DLLs to include
     }
-  }
+  ]
 }
 ```
 
-### rcedit Options
 
-- **icon**: Path to `.ico` file for the executable icon
-- **file-version**: File version in `X.X.X.X` format
-- **product-version**: Product version in `X.X.X.X` format
-- **version-string**: Object containing version string properties:
-  - `CompanyName`: Company name
-  - `FileDescription`: Description of the file
-  - `ProductName`: Product name
-  - `InternalName`: Internal name
-  - `OriginalFilename`: Original filename
-  - `LegalCopyright`: Copyright notice
-  - `LegalTrademarks`: Trademark information (optional)
-  - `PrivateBuild`: Private build description (optional)
-  - `SpecialBuild`: Special build description (optional)
+These files are extracted on first run (like `.node` files) since they need to be loaded from the filesystem.
+
+### Code Signature Removal
+
+Required before SEA injection. Platform-specific tools needed:
+- **Windows**: `signtool.exe` (from Windows SDK)
+- **macOS**: `codesign` (included with Xcode)
+- **Linux**: Not required
+
+### Custom Signing
+
+You can apply code signing after the build completes by specifying a custom signing script:
+
+```json
+{
+  "sign": "./scripts/sign.mjs"
+}
+```
 
-The rcedit step runs after signature removal and before the SEA blob injection. This only works for Windows (`win32`) targets.
+The signing script must export a default function that receives a config object:
+
+```javascript
+// scripts/sign.mjs
+export default async function sign(config) {
+  const { exePath, target, platform, arch, nodeVersion, projectRoot } = config;
+  
+  // Example: Windows code signing with signtool
+  if (platform === 'win32') {
+    execSync(`signtool sign /fd SHA256 /a "${exePath}"`);
+  }
+  
+  // Example: macOS code signing
+  if (platform === 'darwin') {
+    execSync(`codesign --force --sign "Developer ID" "${exePath}"`);
+  }
+}
+```
 
-For more details, see the [rcedit documentation](https://github.com/electron/rcedit).
+**Config parameters:**
+- `exePath` - Absolute path to the built executable
+- `target` - Full target string (e.g., "node24.11.0-win32-x64")
+- `platform` - Platform name (win32, linux, darwin)
+- `arch` - Architecture (x64, arm64)
+- `nodeVersion` - Node.js version
+- `projectRoot` - Absolute path to project root
 
 ## Asset Encryption
 
@@ -254,25 +279,23 @@ seabox supports optional AES-256-GCM encryption of embedded assets to protect yo
 1. **Build Time**: A random 256-bit encryption key is generated
 2. **Asset Encryption**: Non-binary assets are encrypted using AES-256-GCM
 3. **Key Embedding**: The encryption key is obfuscated and embedded in the bootstrap code
-4. **Key Obfuscation**: the bootstrap and key code are obfuscated, but not removed 
+4. **Key Obfuscation**: the bootstrap and key code are obfuscated
 5. **Runtime Decryption**: Assets are transparently decrypted when accessed
 
 ### Considerations
 
 - **Binary files** (`.node`, `.dll`, `.so`, `.dylib`) are **never encrypted** as they must be extracted as-is
 - The manifest (`sea-manifest.json`) is **not encrypted** to allow bootstrap initialization
-- **V8 snapshot includes the original source**, this is currently a limitation of Node's SEA. 
+- **V8 snapshot includes the original source**, this is currently a limitation of Node's SEA tooling. 
 - Encryption provides **obfuscation**, not cryptographic security against determined attackers
 - The bootloader code, that includes the encryption key, is obfuscated in the source embedded by Node's SEA
   
+## Contributing
 
-## Platform Support
-
-- **Windows**: `win32-x64`, `win32-arm64`
-- **Linux**: `linux-x64`, `linux-arm64`
-- **macOS**: `darwin-x64`, `darwin-arm64`
+Contributions welcome! Please open an issue or PR on [GitHub](https://github.com/MeirionHughes/seabox).
 
 ## License
 
 MIT
-Copyright Meirion Hughes 2025
+
+Copyright © 2025 Meirion Hughes

package/bin/seabox-rebuild.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * seabox-rebuild.mjs
+ * Rebuild native modules for target platform/architecture
+ */
+
+import { execSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import * as diag from '../lib/diagnostics.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Rebuild a native module for a specific target
+ * @param {string} modulePath - Path to the native module
+ * @param {string} platform - Target platform (win32, linux, darwin)
+ * @param {string} arch - Target architecture (x64, arm64)
+ * @param {boolean} verbose - Enable verbose logging
+ */
+function rebuildNativeModule(modulePath, platform, arch, verbose = false) {
+  diag.setVerbose(verbose);
+  
+  diag.verbose(`Rebuilding native module: ${modulePath}`);
+  diag.verbose(`Target: ${platform}-${arch}`);
+
+  const packageJsonPath = path.join(modulePath, 'package.json');
+  if (!fs.existsSync(packageJsonPath)) {
+    throw new Error(`No package.json found in ${modulePath}`);
+  }
+
+  const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+  const moduleName = pkg.name;
+
+  // Check if module has native bindings
+  const hasBindingGyp = fs.existsSync(path.join(modulePath, 'binding.gyp'));
+  if (!hasBindingGyp && !pkg.gypfile) {
+    diag.verbose(`Module ${moduleName} does not appear to have native bindings, skipping`);
+    return;
+  }
+
+  try {
+    // Use node-gyp to rebuild for the target platform
+    const cmd = `npx node-gyp rebuild --target_platform=${platform} --target_arch=${arch}`;
+    
+    diag.verbose(`Running: ${cmd}`);
+
+    execSync(cmd, {
+      cwd: modulePath,
+      stdio: verbose ? 'inherit' : 'pipe',
+      env: {
+        ...process.env,
+        npm_config_target_platform: platform,
+        npm_config_target_arch: arch
+      }
+    });
+
+    diag.verbose(`Successfully rebuilt ${moduleName}`);
+  } catch (error) {
+    diag.verbose(`Failed to rebuild ${moduleName}: ${error.message}`);
+    throw error;
+  }
+}
+
+// CLI entry point
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const args = process.argv.slice(2);
+  
+  if (args.length < 3) {
+    diag.error('Usage: seabox-rebuild <module-path> <platform> <arch> [--verbose]');
+    process.exit(1);
+  }
+
+  const [modulePath, platform, arch] = args;
+  const verbose = args.includes('--verbose') || args.includes('-v');
+
+  try {
+    rebuildNativeModule(modulePath, platform, arch, verbose);
+    process.exit(0);
+  } catch (error) {
+    diag.error(`Rebuild failed: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+export { rebuildNativeModule };