Implement standalone executables

Author: rinatkhaziev

AGENTS.md

@@ -67,6 +67,11 @@ Guide for future agents working on this codebase. Focus on traps, cross-cutting
 - `prepare` runs `npm run clean && npm run build`; npm package bins point to `dist/**`. Always rebuild before publishing so dist matches src.
 - `helpers/prepublishOnly.js` enforces branch `trunk` for `npm publish --tag latest` and optionally reruns `npm test`. Release flows expect a clean node version that satisfies `engines.node`.
 
+## Standalone SEA Packaging
+- Canonical runbook for standalone executable build/signing is in `docs/SEA-BUILD-SIGNING.md`. Use it for macOS, Linux, Windows native, and WSL-mediated Windows builds.
+- SEA builds are Node 22 only (enforced in `helpers/build-sea.js`); always verify `node -v` before `npm run build:sea`.
+- The executable is self-contained for Node runtime + JS deps, but `dev-env` commands still require host Docker/Compose availability.
+
 ## Common Pitfalls Checklist
 - Running CLI without a token opens a browser (`open`) and waits for interactive input—pass `--help` or set `WPVIP_DEPLOY_TOKEN` in automation.
 - Forgetting `--app/--env` or alias when a command expects them triggers extra GraphQL lookups and prompts; in headless contexts set `_opts.appContext=false` or supply explicit flags.

CLAUDE.md

@@ -1,3 +1,4 @@
 # CLAUDE
 
 For guidance on working in this repo, traps, and migration notes, see `AGENTS.md`.
+For standalone SEA build/signing by platform, see `docs/SEA-BUILD-SIGNING.md`.

docs/SEA-BUILD-SIGNING.md

@@ -0,0 +1,137 @@
+# SEA Build and Signing Runbook
+
+Purpose: build and sign the standalone VIP CLI executable (`dist/sea/vip` or `dist/sea/vip.exe`) for each supported platform.
+
+This repo uses `helpers/build-sea.js` and the `npm run build:sea` script. SEA build is pinned to Node 22.
+
+## Shared Prerequisites
+- Use Node 22.x exactly for SEA builds.
+- Install dependencies before building: `npm ci`.
+- Build from repo root.
+- The build script embeds:
+  - Node runtime
+  - bundled CLI code (`src/bin/vip-sea.js`)
+  - SEA assets and runtime dependency archive (`sea.node_modules.tgz`)
+- Output paths:
+  - Unix: `dist/sea/vip`
+  - Windows: `dist/sea/vip.exe`
+
+## Shared Build Steps
+```bash
+npm ci
+npm run build
+npm run build:sea
+```
+
+Quick smoke checks after every build:
+```bash
+dist/sea/vip --version
+dist/sea/vip whoami --help
+dist/sea/vip dev-env info --help
+```
+
+## macOS (native)
+Node/tool setup:
+```bash
+export NVM_DIR="$HOME/.nvm"
+. "$NVM_DIR/nvm.sh"
+nvm use 22
+node -v
+```
+
+Build:
+```bash
+npm ci
+npm run build
+npm run build:sea
+```
+
+Notes:
+- `helpers/build-sea.js` already does ad-hoc signing (`codesign --sign -`) after blob injection so local execution works.
+- For distribution, replace ad-hoc signature with a real Developer ID certificate.
+
+Distribution signing:
+```bash
+codesign --remove-signature dist/sea/vip
+codesign --sign "Developer ID Application: <TEAM/ORG>" --force --options runtime dist/sea/vip
+codesign --verify --strict --verbose=2 dist/sea/vip
+spctl -a -t exec -vv dist/sea/vip
+```
+
+## Linux (native)
+Node/tool setup:
+```bash
+node -v
+```
+(Use Node 22 before build.)
+
+Build:
+```bash
+npm ci
+npm run build
+npm run build:sea
+chmod +x dist/sea/vip
+```
+
+Signing guidance:
+- Linux does not have a universal OS-enforced Authenticode-style executable signature.
+- Recommended: publish checksums and detached signatures.
+
+Checksum + GPG example:
+```bash
+sha256sum dist/sea/vip > dist/sea/vip.sha256
+gpg --armor --detach-sign dist/sea/vip
+```
+
+Cosign blob example:
+```bash
+cosign sign-blob --yes --output-signature dist/sea/vip.sig dist/sea/vip
+cosign verify-blob --signature dist/sea/vip.sig dist/sea/vip
+```
+
+## Windows (native)
+Use PowerShell or `cmd.exe` on Windows (not WSL) when producing Windows artifacts.
+
+Build:
+```powershell
+npm ci
+npm run build
+npm run build:sea
+.\dist\sea\vip.exe --version
+```
+
+Authenticode signing (SignTool):
+```powershell
+signtool sign /fd SHA256 /td SHA256 /tr http://timestamp.digicert.com /a .\dist\sea\vip.exe
+signtool verify /pa /v .\dist\sea\vip.exe
+```
+
+If your cert is in a PFX file:
+```powershell
+signtool sign /f C:\path\cert.pfx /p <PFX_PASSWORD> /fd SHA256 /td SHA256 /tr http://timestamp.digicert.com .\dist\sea\vip.exe
+```
+
+## Windows from WSL
+Important: WSL builds Linux binaries by default.
+
+- If target is Linux binary: build/sign inside WSL using the Linux flow.
+- If target is Windows `.exe`: run the build and signing commands in Windows context.
+
+From WSL, invoke Windows PowerShell for a Windows-target build:
+```bash
+WIN_REPO_PATH="$(wslpath -w "$PWD")"
+powershell.exe -NoProfile -Command "Set-Location '$WIN_REPO_PATH'; npm ci; npm run build; npm run build:sea"
+```
+
+Then sign in Windows context:
+```bash
+powershell.exe -NoProfile -Command "Set-Location '$WIN_REPO_PATH'; signtool sign /fd SHA256 /td SHA256 /tr http://timestamp.digicert.com /a .\\dist\\sea\\vip.exe; signtool verify /pa /v .\\dist\\sea\\vip.exe"
+```
+
+## Release Checklist for Agents
+- Confirm Node 22 before SEA build.
+- Confirm artifact type matches target OS (`vip` vs `vip.exe`).
+- Run smoke checks on the produced executable.
+- Apply platform-appropriate signature method.
+- Verify signature/checksum before publishing.
+- Record signing method and timestamp authority in release notes.

helpers/build-sea.js

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+
+const { buildSync } = require( 'esbuild' );
+const { spawnSync } = require( 'node:child_process' );
+const { chmodSync, copyFileSync, mkdirSync, readFileSync, writeFileSync } = require( 'node:fs' );
+const path = require( 'node:path' );
+const tar = require( 'tar' );
+
+const SEA_FUSE = 'NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2';
+
+const projectRoot = path.resolve( __dirname, '..' );
+const seaDir = path.join( projectRoot, 'dist', 'sea' );
+const bundlePath = path.join( seaDir, 'vip.bundle.cjs' );
+const blobPath = path.join( seaDir, 'vip.blob' );
+const seaConfigPath = path.join( seaDir, 'sea-config.json' );
+const executablePath = path.join( seaDir, process.platform === 'win32' ? 'vip.exe' : 'vip' );
+const nodeModulesArchivePath = path.join( seaDir, 'node_modules.tgz' );
+
+function run( command, args, options = {} ) {
+	const result = spawnSync( command, args, {
+		cwd: projectRoot,
+		stdio: 'inherit',
+		...options,
+	} );
+
+	if ( result.status !== 0 ) {
+		process.exit( result.status || 1 );
+	}
+}
+
+function ensureNode22() {
+	const major = Number( process.versions.node.split( '.' )[ 0 ] );
+	if ( major !== 22 ) {
+		console.error(
+			`Error: SEA build requires Node 22.x. Current version is ${ process.versions.node }.`
+		);
+		process.exit( 1 );
+	}
+}
+
+async function createRuntimeArchive() {
+	await tar.c(
+		{
+			cwd: projectRoot,
+			file: nodeModulesArchivePath,
+			gzip: true,
+			portable: true,
+			noMtime: true,
+		},
+		[ 'node_modules' ]
+	);
+}
+
+function writeSeaConfig() {
+	const config = {
+		main: bundlePath,
+		output: blobPath,
+		disableExperimentalSEAWarning: true,
+		assets: {
+			'dev-env.lando.template.yml.ejs': path.join(
+				projectRoot,
+				'assets',
+				'dev-env.lando.template.yml.ejs'
+			),
+			'dev-env.nginx.template.conf.ejs': path.join(
+				projectRoot,
+				'assets',
+				'dev-env.nginx.template.conf.ejs'
+			),
+			'sea.node_modules.tgz': nodeModulesArchivePath,
+		},
+	};
+
+	writeFileSync( seaConfigPath, `${ JSON.stringify( config, null, 2 ) }\n`, 'utf8' );
+}
+
+function buildBundle() {
+	buildSync( {
+		entryPoints: [ path.join( projectRoot, 'src', 'bin', 'vip-sea.js' ) ],
+		bundle: true,
+		platform: 'node',
+		target: 'node22',
+		format: 'cjs',
+		outfile: bundlePath,
+		external: [
+			'@postman/node-keytar',
+			'@postman/node-keytar/*',
+			'cpu-features',
+			'cpu-features/*',
+			'lando',
+			'lando/*',
+			'ssh2',
+			'ssh2/*',
+			'*.node',
+		],
+	} );
+}
+
+function stripBundleShebang() {
+	const bundleContent = readFileSync( bundlePath, 'utf8' );
+	if ( ! bundleContent.startsWith( '#!' ) ) {
+		return;
+	}
+
+	writeFileSync( bundlePath, bundleContent.replace( /^#![^\n]*\n/, '' ), 'utf8' );
+}
+
+function buildBlob() {
+	run( process.execPath, [ '--experimental-sea-config', seaConfigPath ] );
+}
+
+function prepareExecutable() {
+	copyFileSync( process.execPath, executablePath );
+
+	if ( process.platform === 'darwin' ) {
+		run( 'codesign', [ '--remove-signature', executablePath ] );
+	}
+}
+
+function injectBlob() {
+	const postjectCli = require.resolve( 'postject/dist/cli.js' );
+	const args = [
+		postjectCli,
+		executablePath,
+		'NODE_SEA_BLOB',
+		blobPath,
+		'--sentinel-fuse',
+		SEA_FUSE,
+	];
+
+	if ( process.platform === 'darwin' ) {
+		args.push( '--macho-segment-name', 'NODE_SEA' );
+	}
+
+	if ( process.platform === 'windows' ) {
+		args.push( '--overwrite' );
+	}
+
+	run( process.execPath, args );
+}
+
+function finalizeExecutable() {
+	if ( process.platform === 'darwin' ) {
+		run( 'codesign', [ '--sign', '-', '--force', executablePath ] );
+	}
+
+	if ( process.platform !== 'win32' ) {
+		chmodSync( executablePath, 0o755 );
+	}
+}
+
+async function main() {
+	ensureNode22();
+	mkdirSync( seaDir, { recursive: true } );
+	await createRuntimeArchive();
+	writeSeaConfig();
+	buildBundle();
+	stripBundleShebang();
+	buildBlob();
+	prepareExecutable();
+	injectBlob();
+	finalizeExecutable();
+
+	console.log( `SEA executable written to ${ executablePath }` );
+}
+
+void main();