@automattic/vip 3.25.1 → 3.25.2-dev.0

package/docs/COMMANDER-MIGRATION.md

@@ -0,0 +1,55 @@
+# Commander Migration Status
+
+Goal: remove the abandoned `args` package, keep CLI behavior stable, and support packaging to a single bundled executable (Node SEA or similar). See `AGENTS.md` for broader architecture traps.
+
+## Migration Outcome
+
+- `src/lib/cli/command.js` is the active Commander-backed compatibility wrapper for all bins that call `command()`.
+- `args` has been removed from `package.json` and `npm-shrinkwrap.json`.
+- Root command flow (`src/bin/vip.js`) now dispatches via the shared Commander wrapper again, preserving login gating and subcommand chaining.
+- Temporary side-path wrapper work has been removed (`src/lib/cli/command-commander.ts` deleted).
+
+## Compatibility Behaviors Preserved
+
+- Legacy command contract stays the same: `command(opts).option(...).argv(process.argv, handler)`.
+- Alias behavior remains pre-parse: `@app` and `@app.env` are stripped before `--`; alias + `--app/--env` still errors.
+- `_opts` controls are still honored: app/env context fetch, confirmation gating, output formatting, wildcard command handling, required positional args.
+- Shared formatting/output and telemetry hooks are still in the wrapper path.
+- Local nested subcommand dispatch still works via sibling executable resolution.
+
+## Post-Migration Hardening
+
+- Short-flag compatibility was restored for long options without explicit aliases:
+  - Example: `--elasticsearch` accepts `-e`, `--phpmyadmin` accepts `-p`, etc.
+  - Auto-short generation skips reserved global flags (`-h`, `-v`, `-d`) and avoids duplicate collisions.
+- `vip dev-env exec` now performs bounded readiness checks before deciding an environment is not running.
+- `startEnvironment()` now includes bounded post-start readiness checks and one recovery `landoStart` retry if the environment stays `DOWN` after rebuild/start.
+
+## Remaining Technical Debt
+
+- `_opts` is still module-level state in `src/lib/cli/command.js` and can leak between command instances in one process.
+- Help text parity against historical `args` output is close but still a verification target for high-traffic commands.
+- Full dev-env E2E can still show Docker/Lando infrastructure flakiness (network cleanup and startup latency), which is environment-level, not parser-level.
+
+## Verification Commands
+
+- `npm run build`
+- `npm run check-types`
+- `npm run test:e2e:dev-env -- --runInBand __tests__/devenv-e2e/001-create.spec.js __tests__/devenv-e2e/005-update.spec.js`
+- `npm run test:e2e:dev-env -- --runInBand __tests__/devenv-e2e/008-exec.spec.js __tests__/devenv-e2e/010-import-sql.spec.js`
+
+## Single-Bundle Direction
+
+- Preferred: `esbuild` bundle rooted at `src/bin/vip.js`.
+- Keep native deps external (`@postman/node-keytar`) for SEA/packaging workflows.
+- Candidate build target:
+  - `dist/vip.bundle.cjs` for SEA ingestion or launcher wrapping.
+- Example command:
+  - `esbuild src/bin/vip.js --bundle --platform=node --target=node20 --format=cjs --outfile=dist/vip.bundle.cjs --banner:js="#!/usr/bin/env node" --external:@postman/node-keytar`
+
+## Next Refactor Steps
+
+1. Remove global `_opts` state from `src/lib/cli/command.js` by moving to per-instance configuration.
+2. Add parser contract tests for aliasing, wildcard behavior, and short/long boolean coercion.
+3. Add stable startup/readiness integration checks around dev-env commands in CI environments with Docker.
+4. Add bundling script(s) and SEA config proof-of-concept for a single-file executable artifact.

package/docs/SEA-BUILD-SIGNING.md

@@ -0,0 +1,171 @@
+# 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.
+
+## GitHub Actions Automation
+
+- Workflow: `.github/workflows/sea-build-sign.yml`
+- Trigger: manual `workflow_dispatch`
+- Jobs: native macOS/Linux/Windows SEA builds plus a Windows WSL SEA build
+- Optional signing: set `sign_artifacts=true` and provide signing secrets/vars:
+  - macOS: `MACOS_CERTIFICATE_P12_BASE64`, `MACOS_CERTIFICATE_PASSWORD`, `MACOS_SIGNING_IDENTITY`
+  - Windows: `WINDOWS_CERTIFICATE_PFX_BASE64`, `WINDOWS_CERTIFICATE_PASSWORD`
+  - optional variable: `WINDOWS_TIMESTAMP_URL`
+- Output: uploaded SEA binary + SHA256 artifact per job

package/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 === 'win32' ) {
+		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();