@automattic/vip 3.25.2-dev.0 → 3.25.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automattic/vip",
-  "version": "3.25.2-dev.0",
+  "version": "3.25.2",
   "description": "The VIP Javascript library & CLI",
   "main": "index.js",
   "bin": {
@@ -72,13 +72,12 @@
     "test": "npm run lint && npm run check-types && jest --coverage --testPathIgnorePatterns __tests__/devenv-e2e/",
     "test:e2e:dev-env": "jest -c __tests__/devenv-e2e/jest/jest.config.js",
     "clean": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
-    "cmd:format": "prettier \"**/*.{js,json,jsx,md,ts,tsx,yml,yaml}\"",
+    "cmd:format": "prettier '**/*.(js|json|jsx|md|ts|tsx|yml|yaml)'",
     "cmd:lint": "eslint --ext 'js,jsx,ts,tsx'",
     "prepare": "npm run clean && npm run build",
     "check-types": "tsc",
     "postinstall": "node ./helpers/check-version.js",
     "build": "babel src -d dist --extensions=\".js,.ts\"",
-    "build:sea": "node ./helpers/build-sea.js",
     "build:watch": "babel src -d dist --watch --source-maps --extensions=\".js,.ts\"",
     "format": "npm run cmd:format -- --write",
     "format:check": "npm run cmd:format -- --check",
@@ -115,7 +114,7 @@
     "@automattic/eslint-plugin-wpvip": "^1.0.0",
     "@babel/cli": "7.28.6",
     "@babel/core": "7.29.0",
-    "@babel/preset-env": "7.29.0",
+    "@babel/preset-env": "7.29.3",
     "@babel/preset-typescript": "7.28.5",
     "@jest/globals": "^30.0.0",
     "@jest/test-sequencer": "^30.0.0",
@@ -132,35 +131,33 @@
     "@types/ssh2": "^1.15.4",
     "@types/tar": "^7.0.87",
     "@types/xml2js": "^0.4.14",
-    "dockerode": "^4.0.0",
-    "esbuild": "^0.27.3",
+    "dockerode": "^5.0.0",
     "jest": "^30.0.0",
     "nock": "13.5.6",
-    "postject": "^1.0.0-alpha.6",
     "prettier": "npm:wp-prettier@3.0.3",
-    "typescript": "^5.2.2"
+    "typescript": "^6.0.2"
   },
   "dependencies": {
-    "@apollo/client": "4.1.6",
+    "@apollo/client": "4.1.8",
     "@automattic/vip-search-replace": "^2.0.0",
     "@json2csv/plainjs": "^7.0.3",
     "@wwa/single-line-log": "^1.1.4",
+    "args": "5.0.3",
     "chalk": "^5.6.2",
     "check-disk-space": "3.4.0",
     "cli-columns": "^4.0.0",
     "cli-table3": "^0.6.3",
-    "commander": "^14.0.3",
     "configstore": "^8.0.0",
     "debug": "4.4.3",
     "ejs": "^5.0.1",
     "enquirer": "2.4.1",
     "fetch-retry": "^6.0.0",
-    "graphql": "16.13.1",
+    "graphql": "16.13.2",
     "graphql-tag": "2.12.6",
-    "https-proxy-agent": "^7.0.6",
+    "https-proxy-agent": "^9.0.0",
     "js-yaml": "^4.1.0",
     "jwt-decode": "4.0.0",
-    "lando": "github:automattic/lando-cli#c7dd51e8fb341e59e0e51a1aac453aa81dc2faf6",
+    "lando": "github:automattic/lando-cli#78d382fcf40357c4a4cebe4a3cfaef032eab743a",
     "node-fetch": "^3.3.2",
     "node-stream-zip": "1.15.0",
     "open": "^11.0.0",
@@ -169,7 +166,7 @@
     "shelljs": "^0.10.0",
     "socket.io-client": "^4.5.3",
     "socket.io-stream": "npm:@wwa/socket.io-stream@^0.10.0",
-    "socks-proxy-agent": "^8.0.5",
+    "socks-proxy-agent": "^10.0.0",
     "ssh2": "1.17.0",
     "tar": "^7.4.0",
     "update-notifier": "7.3.1",

package/tsconfig.json

@@ -3,23 +3,17 @@
     "lib": [ "ES2022" ],
     "module": "nodenext",
     "strict": true,
-    "esModuleInterop": true,
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true,
     "moduleResolution": "nodenext",
+    "types": [ "node", "jest" ],
 
-    // Target latest version of ECMAScript.
     "target": "ES2022",
-    // Don't parse types from JS as TS doesn't play well with Flow-ish JS.
-    "allowJs": false,
     // Don't emit; allow Babel to transform files.
     "noEmit": true,
-    // Can't checkJs if we don't allowJs, so this remains false
-    "checkJs": false,
     // Disallow features that require cross-file information for emit as we're using Babel
     "isolatedModules": true,
     "resolveJsonModule": true,
-    "baseUrl": ".",
     "paths": {
       "*": [ "./types/*", "./node_modules/@types/node/*" ]
     },

package/dist/bin/vip-sea.js

@@ -1,19 +0,0 @@
-#!/usr/bin/env node
-"use strict";
-
-var _seaDispatch = require("../lib/cli/sea-dispatch");
-var _seaRuntime = require("../lib/cli/sea-runtime");
-const run = async () => {
-  if ((0, _seaDispatch.isSeaRuntime)()) {
-    process.env.VIP_CLI_SEA_MODE = '1';
-    await (0, _seaRuntime.prepareSeaRuntimeFilesystem)();
-    const resolution = (0, _seaDispatch.resolveInternalBinFromArgv)(process.argv);
-    if (resolution.bin !== 'vip') {
-      process.env.VIP_CLI_TARGET_BIN = resolution.bin;
-      process.env.VIP_CLI_TARGET_START = String(resolution.start);
-      process.env.VIP_CLI_TARGET_LENGTH = String(resolution.length);
-    }
-  }
-  await import('./vip.js');
-};
-void run();

package/dist/lib/cli/internal-bin-loader.js

@@ -1,81 +0,0 @@
-"use strict";
-
-exports.__esModule = true;
-exports.hasInternalBin = hasInternalBin;
-exports.internalBinNames = void 0;
-exports.loadInternalBin = loadInternalBin;
-const internalBinLoaders = {
-  vip: () => import('../../bin/vip'),
-  'vip-app': () => import('../../bin/vip-app'),
-  'vip-app-deploy': () => import('../../bin/vip-app-deploy'),
-  'vip-app-deploy-validate': () => import('../../bin/vip-app-deploy-validate'),
-  'vip-app-list': () => import('../../bin/vip-app-list'),
-  'vip-backup': () => import('../../bin/vip-backup'),
-  'vip-backup-db': () => import('../../bin/vip-backup-db'),
-  'vip-cache': () => import('../../bin/vip-cache'),
-  'vip-cache-purge-url': () => import('../../bin/vip-cache-purge-url'),
-  'vip-config': () => import('../../bin/vip-config'),
-  'vip-config-envvar': () => import('../../bin/vip-config-envvar'),
-  'vip-config-envvar-delete': () => import('../../bin/vip-config-envvar-delete'),
-  'vip-config-envvar-get': () => import('../../bin/vip-config-envvar-get'),
-  'vip-config-envvar-get-all': () => import('../../bin/vip-config-envvar-get-all'),
-  'vip-config-envvar-list': () => import('../../bin/vip-config-envvar-list'),
-  'vip-config-envvar-set': () => import('../../bin/vip-config-envvar-set'),
-  'vip-config-software': () => import('../../bin/vip-config-software'),
-  'vip-config-software-get': () => import('../../bin/vip-config-software-get'),
-  'vip-config-software-update': () => import('../../bin/vip-config-software-update'),
-  'vip-db': () => import('../../bin/vip-db'),
-  'vip-db-phpmyadmin': () => import('../../bin/vip-db-phpmyadmin'),
-  'vip-dev-env': () => import('../../bin/vip-dev-env'),
-  'vip-dev-env-create': () => import('../../bin/vip-dev-env-create'),
-  'vip-dev-env-destroy': () => import('../../bin/vip-dev-env-destroy'),
-  'vip-dev-env-envvar': () => import('../../bin/vip-dev-env-envvar'),
-  'vip-dev-env-envvar-delete': () => import('../../bin/vip-dev-env-envvar-delete'),
-  'vip-dev-env-envvar-get': () => import('../../bin/vip-dev-env-envvar-get'),
-  'vip-dev-env-envvar-get-all': () => import('../../bin/vip-dev-env-envvar-get-all'),
-  'vip-dev-env-envvar-list': () => import('../../bin/vip-dev-env-envvar-list'),
-  'vip-dev-env-envvar-set': () => import('../../bin/vip-dev-env-envvar-set'),
-  'vip-dev-env-exec': () => import('../../bin/vip-dev-env-exec'),
-  'vip-dev-env-import': () => import('../../bin/vip-dev-env-import'),
-  'vip-dev-env-import-media': () => import('../../bin/vip-dev-env-import-media'),
-  'vip-dev-env-import-sql': () => import('../../bin/vip-dev-env-import-sql'),
-  'vip-dev-env-info': () => import('../../bin/vip-dev-env-info'),
-  'vip-dev-env-list': () => import('../../bin/vip-dev-env-list'),
-  'vip-dev-env-logs': () => import('../../bin/vip-dev-env-logs'),
-  'vip-dev-env-purge': () => import('../../bin/vip-dev-env-purge'),
-  'vip-dev-env-shell': () => import('../../bin/vip-dev-env-shell'),
-  'vip-dev-env-start': () => import('../../bin/vip-dev-env-start'),
-  'vip-dev-env-stop': () => import('../../bin/vip-dev-env-stop'),
-  'vip-dev-env-sync': () => import('../../bin/vip-dev-env-sync'),
-  'vip-dev-env-sync-sql': () => import('../../bin/vip-dev-env-sync-sql'),
-  'vip-dev-env-update': () => import('../../bin/vip-dev-env-update'),
-  'vip-export': () => import('../../bin/vip-export'),
-  'vip-export-sql': () => import('../../bin/vip-export-sql'),
-  'vip-import': () => import('../../bin/vip-import'),
-  'vip-import-media': () => import('../../bin/vip-import-media'),
-  'vip-import-media-abort': () => import('../../bin/vip-import-media-abort'),
-  'vip-import-media-status': () => import('../../bin/vip-import-media-status'),
-  'vip-import-sql': () => import('../../bin/vip-import-sql'),
-  'vip-import-sql-status': () => import('../../bin/vip-import-sql-status'),
-  'vip-import-validate-files': () => import('../../bin/vip-import-validate-files'),
-  'vip-import-validate-sql': () => import('../../bin/vip-import-validate-sql'),
-  'vip-logout': () => import('../../bin/vip-logout'),
-  'vip-logs': () => import('../../bin/vip-logs'),
-  'vip-search-replace': () => import('../../bin/vip-search-replace'),
-  'vip-slowlogs': () => import('../../bin/vip-slowlogs'),
-  'vip-sync': () => import('../../bin/vip-sync'),
-  'vip-whoami': () => import('../../bin/vip-whoami'),
-  'vip-wp': () => import('../../bin/vip-wp')
-};
-const internalBinNames = exports.internalBinNames = Object.freeze(Object.keys(internalBinLoaders));
-async function loadInternalBin(binName) {
-  const loader = internalBinLoaders[binName];
-  if (!loader) {
-    return false;
-  }
-  await loader();
-  return true;
-}
-function hasInternalBin(binName) {
-  return Object.hasOwn(internalBinLoaders, binName);
-}

package/dist/lib/cli/runtime-mode.js

@@ -1,21 +0,0 @@
-"use strict";
-
-exports.__esModule = true;
-exports.getRuntimeModeLabel = getRuntimeModeLabel;
-exports.isStandaloneExecutableRuntime = isStandaloneExecutableRuntime;
-var _nodeModule = require("node:module");
-const runtimeRequire = (0, _nodeModule.createRequire)(__filename);
-function isStandaloneExecutableRuntime() {
-  if (process.env.VIP_CLI_SEA_MODE === '1') {
-    return true;
-  }
-  try {
-    const sea = runtimeRequire('node:sea');
-    return Boolean(sea?.isSea?.());
-  } catch {
-    return false;
-  }
-}
-function getRuntimeModeLabel() {
-  return isStandaloneExecutableRuntime() ? 'standalone-sea' : 'node-script';
-}

package/dist/lib/cli/sea-dispatch.js

@@ -1,88 +0,0 @@
-"use strict";
-
-exports.__esModule = true;
-exports.isSeaRuntime = isSeaRuntime;
-exports.resolveInternalBinFromArgv = resolveInternalBinFromArgv;
-exports.rewriteArgvForInternalBin = rewriteArgvForInternalBin;
-var _envAlias = require("./envAlias");
-var _internalBinLoader = require("./internal-bin-loader");
-const internalBinSet = new Set(_internalBinLoader.internalBinNames);
-
-/**
- * Resolve the best matching internal bin for a command argv.
- *
- * @param {string[]} argv process.argv style array
- * @returns {{ bin: string, start: number, length: number }}
- */
-function resolveInternalBinFromArgv(argv) {
-  const args = argv.slice(2);
-  const dashDashIndex = args.indexOf('--');
-  const commandBoundary = dashDashIndex > -1 ? dashDashIndex : args.length;
-  let best = {
-    bin: 'vip',
-    start: 0,
-    length: 0
-  };
-  for (let start = 0; start < commandBoundary; start++) {
-    const firstToken = args[start];
-    if (!firstToken || firstToken.startsWith('-') || (0, _envAlias.isAlias)(firstToken)) {
-      continue;
-    }
-    const commandParts = [];
-    for (let index = start; index < commandBoundary; index++) {
-      const token = args[index];
-      if (!token || token.startsWith('-') || (0, _envAlias.isAlias)(token)) {
-        break;
-      }
-      commandParts.push(token);
-      const candidateBin = `vip-${commandParts.join('-')}`;
-      if (internalBinSet.has(candidateBin)) {
-        const isLongerMatch = commandParts.length > best.length;
-        const isEarlierEqualMatch = commandParts.length === best.length && commandParts.length > 0 && start < best.start;
-        if (isLongerMatch || isEarlierEqualMatch) {
-          best = {
-            bin: candidateBin,
-            start,
-            length: commandParts.length
-          };
-        }
-      }
-    }
-  }
-  return best;
-}
-
-/**
- * Rewrites argv so the resolved command segment is removed and the target bin
- * can parse its native flags/args shape.
- *
- * @param {string[]} argv process.argv style array
- * @param {{ start: number, length: number }} resolution command resolution
- * @returns {string[]} rewritten argv
- */
-function rewriteArgvForInternalBin(argv, resolution) {
-  const args = argv.slice(2);
-  const start = resolution.start ?? 0;
-  const length = resolution.length ?? 0;
-  if (length <= 0) {
-    return argv.slice(0);
-  }
-  const rewrittenArgs = args.slice(0, start).concat(args.slice(start + length));
-  return [argv[0], argv[1], ...rewrittenArgs];
-}
-
-/**
- * @returns {boolean}
- */
-function isSeaRuntime() {
-  try {
-    const runtimeRequire = typeof module !== 'undefined' && module?.require ? module.require.bind(module) : null;
-    if (!runtimeRequire) {
-      return false;
-    }
-    const sea = runtimeRequire('node:sea');
-    return Boolean(sea?.isSea?.());
-  } catch {
-    return false;
-  }
-}

package/dist/lib/cli/sea-runtime.js

@@ -1,75 +0,0 @@
-"use strict";
-
-exports.__esModule = true;
-exports.prepareSeaRuntimeFilesystem = prepareSeaRuntimeFilesystem;
-var _nodeFs = require("node:fs");
-var _promises = require("node:fs/promises");
-var _nodePath = _interopRequireDefault(require("node:path"));
-var _package = _interopRequireDefault(require("../../../package.json"));
-var _xdgData = require("../xdg-data");
-function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-const RUNTIME_ARCHIVE_KEY = 'sea.node_modules.tgz';
-const RUNTIME_DIR_NAME = 'sea-runtime';
-const READY_FILE_NAME = '.ready';
-const ARCHIVE_FILE_NAME = 'node_modules.tgz';
-async function getSeaModule() {
-  try {
-    return await import('node:sea');
-  } catch {
-    return null;
-  }
-}
-function getRuntimeRootPath() {
-  return _nodePath.default.join((0, _xdgData.xdgData)(), 'vip', RUNTIME_DIR_NAME, _package.default.version);
-}
-function getRuntimeNodeModulesPath(runtimeRootPath) {
-  return _nodePath.default.join(runtimeRootPath, 'node_modules');
-}
-function getRuntimeReadyPath(runtimeRootPath) {
-  return _nodePath.default.join(runtimeRootPath, READY_FILE_NAME);
-}
-function appendNodePath(nodeModulesPath) {
-  const existing = process.env.NODE_PATH ? process.env.NODE_PATH.split(_nodePath.default.delimiter) : [];
-  if (!existing.includes(nodeModulesPath)) {
-    process.env.NODE_PATH = [nodeModulesPath, ...existing].join(_nodePath.default.delimiter);
-  }
-  const Module = require('node:module');
-  Module.Module._initPaths();
-  const runtimeEntryPath = _nodePath.default.join(nodeModulesPath, '..', '__sea-entry__.js');
-  const runtimeRequire = Module.createRequire(runtimeEntryPath);
-  module.filename = runtimeEntryPath;
-  module.paths = Module._nodeModulePaths(_nodePath.default.dirname(runtimeEntryPath));
-  module.require = runtimeRequire;
-}
-async function extractRuntimeDependencies(runtimeRootPath, archiveBuffer) {
-  await (0, _promises.rm)(runtimeRootPath, {
-    recursive: true,
-    force: true
-  });
-  await (0, _promises.mkdir)(runtimeRootPath, {
-    recursive: true
-  });
-  const archivePath = _nodePath.default.join(runtimeRootPath, ARCHIVE_FILE_NAME);
-  await (0, _promises.writeFile)(archivePath, archiveBuffer);
-  const tar = require('tar');
-  await tar.x({
-    file: archivePath,
-    cwd: runtimeRootPath
-  });
-  await (0, _promises.writeFile)(getRuntimeReadyPath(runtimeRootPath), _package.default.version, 'utf8');
-}
-async function prepareSeaRuntimeFilesystem() {
-  const sea = await getSeaModule();
-  if (!sea?.isSea?.() || !sea.getAsset) {
-    return;
-  }
-  const runtimeRootPath = getRuntimeRootPath();
-  const runtimeNodeModulesPath = getRuntimeNodeModulesPath(runtimeRootPath);
-  const runtimeReadyPath = getRuntimeReadyPath(runtimeRootPath);
-  if (!(0, _nodeFs.existsSync)(runtimeReadyPath) || !(0, _nodeFs.existsSync)(runtimeNodeModulesPath)) {
-    const archiveAsset = sea.getAsset(RUNTIME_ARCHIVE_KEY);
-    const archiveBuffer = Buffer.isBuffer(archiveAsset) ? archiveAsset : Buffer.from(archiveAsset);
-    await extractRuntimeDependencies(runtimeRootPath, archiveBuffer);
-  }
-  appendNodePath(runtimeNodeModulesPath);
-}

package/dist/lib/dev-environment/lando-loader.js

@@ -1,48 +0,0 @@
-"use strict";
-
-exports.__esModule = true;
-exports.loadLandoModule = loadLandoModule;
-exports.resolveLandoModule = resolveLandoModule;
-var _nodeFs = require("node:fs");
-var _nodeModule = require("node:module");
-var _nodePath = _interopRequireDefault(require("node:path"));
-var _package = _interopRequireDefault(require("../../../package.json"));
-var _xdgData = require("../xdg-data");
-function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-const SEA_RUNTIME_DIR_NAME = 'sea-runtime';
-let cachedRequire = null;
-let didResolveRequire = false;
-const baseRequire = (0, _nodeModule.createRequire)(__filename);
-function isSeaRuntime() {
-  try {
-    const sea = baseRequire('node:sea');
-    return Boolean(sea?.isSea?.());
-  } catch {
-    return false;
-  }
-}
-function getSeaRuntimeNodeModulesPath() {
-  return _nodePath.default.join((0, _xdgData.xdgData)(), 'vip', SEA_RUNTIME_DIR_NAME, _package.default.version, 'node_modules');
-}
-function getRuntimeRequire() {
-  if (didResolveRequire && cachedRequire) {
-    return cachedRequire;
-  }
-  didResolveRequire = true;
-  if (isSeaRuntime()) {
-    const runtimeNodeModulesPath = getSeaRuntimeNodeModulesPath();
-    if ((0, _nodeFs.existsSync)(runtimeNodeModulesPath)) {
-      const runtimeEntryPath = _nodePath.default.join(runtimeNodeModulesPath, '..', '__sea-entry__.js');
-      cachedRequire = (0, _nodeModule.createRequire)(runtimeEntryPath);
-      return cachedRequire;
-    }
-  }
-  cachedRequire = baseRequire;
-  return cachedRequire;
-}
-function loadLandoModule(request) {
-  return getRuntimeRequire()(request);
-}
-function resolveLandoModule(request) {
-  return getRuntimeRequire().resolve(request);
-}

package/docs/COMMANDER-MIGRATION.md

@@ -1,55 +0,0 @@
-# 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

@@ -1,171 +0,0 @@
-# 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