@automattic/vip 3.25.0 → 3.25.2-dev.0

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

@@ -0,0 +1,75 @@
+"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/constants/dev-environment.js

@@ -36,4 +36,4 @@ const DEV_ENVIRONMENT_DEFAULTS = exports.DEV_ENVIRONMENT_DEFAULTS = {
   multisite: false,
   phpVersion: Object.keys(DEV_ENVIRONMENT_PHP_VERSIONS)[0]
 };
-const DEV_ENVIRONMENT_VERSION = exports.DEV_ENVIRONMENT_VERSION = '2.3.2';
+const DEV_ENVIRONMENT_VERSION = exports.DEV_ENVIRONMENT_VERSION = '2.3.3';

package/dist/lib/dev-environment/dev-environment-cli.js

@@ -38,7 +38,6 @@ var _chalk = _interopRequireDefault(require("chalk"));
 var _child_process = require("child_process");
 var _debug = _interopRequireDefault(require("debug"));
 var _enquirer = require("enquirer");
-var _formatters = _interopRequireDefault(require("lando/lib/formatters"));
 var _nodeFs = require("node:fs");
 var _nodeOs = require("node:os");
 var _path = _interopRequireDefault(require("path"));
@@ -46,6 +45,7 @@ var _shelljs = require("shelljs");
 var _devEnvironmentConfigurationFile = require("./dev-environment-configuration-file");
 var _devEnvironmentCore = require("./dev-environment-core");
 var _devEnvironmentLando = require("./dev-environment-lando");
+var _landoLoader = require("./lando-loader");
 var _user = require("../api/user");
 var _devEnvironment = require("../constants/dev-environment");
 var _tracker = require("../tracker");
@@ -55,6 +55,13 @@ const debug = (0, _debug.default)('@automattic/vip:bin:dev-environment');
 const DEFAULT_SLUG = exports.DEFAULT_SLUG = 'vip-local';
 const CONFIGURATION_FOLDER = exports.CONFIGURATION_FOLDER = '.wpvip';
 let isStdinTTY = Boolean(process.stdin.isTTY);
+let landoFormatters = null;
+const getLandoFormatters = () => {
+  if (!landoFormatters) {
+    landoFormatters = (0, _landoLoader.loadLandoModule)('lando/lib/formatters');
+  }
+  return landoFormatters;
+};
 
 /**
  * Used internally for tests
@@ -150,7 +157,7 @@ function getEnvironmentStartCommand(slug, configurationFileOptions) {
   return `${_devEnvironment.DEV_ENVIRONMENT_FULL_COMMAND} start --slug ${slug}`;
 }
 function printTable(data) {
-  const formattedData = _formatters.default.formatData(data, {
+  const formattedData = getLandoFormatters().formatData(data, {
     format: 'table'
   }, {
     border: false

package/dist/lib/dev-environment/dev-environment-core.js

@@ -28,7 +28,6 @@ var _debug = _interopRequireDefault(require("debug"));
 var _ejs = _interopRequireDefault(require("ejs"));
 var _enquirer = require("enquirer");
 var _graphql = require("graphql");
-var _utils = require("lando/lib/utils");
 var _nodeFetch = _interopRequireDefault(require("node-fetch"));
 var _nodeCrypto = require("node:crypto");
 var _nodeFs = _interopRequireDefault(require("node:fs"));
@@ -37,6 +36,7 @@ var _nodePath = _interopRequireDefault(require("node:path"));
 var _semver = _interopRequireDefault(require("semver"));
 var _devEnvironmentCli = require("./dev-environment-cli");
 var _devEnvironmentLando = require("./dev-environment-lando");
+var _landoLoader = require("./lando-loader");
 var _app = _interopRequireDefault(require("../api/app"));
 var _software = require("../config/software");
 var _devEnvironment = require("../constants/dev-environment");
@@ -47,7 +47,9 @@ var _xdgData = require("../xdg-data");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 const debug = (0, _debug.default)('@automattic/vip:bin:dev-environment');
 const landoFileTemplatePath = _nodePath.default.join(__dirname, '..', '..', '..', 'assets', 'dev-env.lando.template.yml.ejs');
+const landoTemplateAssetKey = 'dev-env.lando.template.yml.ejs';
 const nginxFileTemplatePath = _nodePath.default.join(__dirname, '..', '..', '..', 'assets', 'dev-env.nginx.template.conf.ejs');
+const nginxTemplateAssetKey = 'dev-env.nginx.template.conf.ejs';
 const landoFileName = '.lando.yml';
 const landoOverridesFileName = '.lando.local.yml';
 const landoBackupFileName = '.lando.backup.yml';
@@ -58,6 +60,53 @@ const integrationsConfigBackupFileName = 'integrations.json.bak';
 const uploadPathString = 'uploads';
 const nginxPathString = 'nginx';
 const integrationsConfigPathString = 'integrations-config';
+const STARTUP_READY_ATTEMPTS = 6;
+const STARTUP_READY_DELAY_MS = 2000;
+let dockerComposifyFromLando = null;
+const dockerComposify = value => {
+  if (!dockerComposifyFromLando) {
+    const landoUtils = (0, _landoLoader.loadLandoModule)('lando/lib/utils');
+    dockerComposifyFromLando = landoUtils.dockerComposify;
+  }
+  return dockerComposifyFromLando(value);
+};
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+let seaModulePromise = null;
+const getSeaModule = async () => {
+  if (!seaModulePromise) {
+    seaModulePromise = (async () => {
+      try {
+        return await import('node:sea');
+      } catch {
+        return null;
+      }
+    })();
+  }
+  return seaModulePromise;
+};
+const renderTemplateFile = async (filePath, assetKey, templateData) => {
+  const sea = await getSeaModule();
+  if (sea?.isSea?.() && sea.getAsset) {
+    const template = sea.getAsset(assetKey, 'utf8');
+    if (typeof template === 'string') {
+      return _ejs.default.render(template, templateData);
+    }
+  }
+  return _ejs.default.renderFile(filePath, templateData);
+};
+async function waitForEnvironmentToBeUp(lando, instancePath) {
+  return pollEnvironmentUpStatus(lando, instancePath, 1);
+}
+async function pollEnvironmentUpStatus(lando, instancePath, attempt) {
+  if (await (0, _devEnvironmentLando.isEnvUp)(lando, instancePath)) {
+    return true;
+  }
+  if (attempt >= STARTUP_READY_ATTEMPTS) {
+    return false;
+  }
+  await sleep(STARTUP_READY_DELAY_MS);
+  return pollEnvironmentUpStatus(lando, instancePath, attempt + 1);
+}
 async function startEnvironment(lando, slug, options) {
   debug('Will start an environment', slug);
   const instancePath = getEnvironmentPath(slug);
@@ -82,6 +131,15 @@ async function startEnvironment(lando, slug, options) {
   } else {
     await (0, _devEnvironmentLando.landoRebuild)(lando, instancePath);
   }
+  let isEnvironmentUp = await waitForEnvironmentToBeUp(lando, instancePath);
+  if (!isEnvironmentUp) {
+    // A second startup pass helps recover after Docker network auto-cleanup edge cases.
+    await (0, _devEnvironmentLando.landoStart)(lando, instancePath);
+    isEnvironmentUp = await waitForEnvironmentToBeUp(lando, instancePath);
+  }
+  if (!isEnvironmentUp) {
+    throw new _userError.default(`Environment "${slug}" did not reach a running state. Please try "${_chalk.default.bold(`vip dev-env start --slug ${slug}`)}" again.`);
+  }
   await printEnvironmentInfo(lando, slug, {
     extended: false
   });
@@ -166,7 +224,7 @@ async function destroyEnvironment(lando, slug, removeFiles) {
   } else {
     debug("Lando file doesn't exist, skipping lando destroy.");
   }
-  await _nodeFs.default.promises.rm(_nodePath.default.join((0, _xdgData.xdgData)(), 'vip', 'lando', 'compose', (0, _utils.dockerComposify)(slug)), {
+  await _nodeFs.default.promises.rm(_nodePath.default.join((0, _xdgData.xdgData)(), 'vip', 'lando', 'compose', dockerComposify(slug)), {
     force: true,
     recursive: true
   });
@@ -349,8 +407,8 @@ async function prepareLandoEnv(lando, instanceData, instancePath, integrationsCo
     ...instanceData,
     domain: lando.config.domain
   };
-  const landoFile = await _ejs.default.renderFile(landoFileTemplatePath, templateData);
-  const nginxFile = await _ejs.default.renderFile(nginxFileTemplatePath, templateData);
+  const landoFile = await renderTemplateFile(landoFileTemplatePath, landoTemplateAssetKey, templateData);
+  const nginxFile = await renderTemplateFile(nginxFileTemplatePath, nginxTemplateAssetKey, templateData);
   const instanceDataFile = JSON.stringify(instanceData);
   const landoFileTargetPath = _nodePath.default.join(instancePath, landoFileName);
   const landoOverridesFileTargetPath = _nodePath.default.join(instancePath, landoOverridesFileName);

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

@@ -18,10 +18,6 @@ exports.removeProxyCache = removeProxyCache;
 exports.validateDockerInstalled = validateDockerInstalled;
 var _chalk = _interopRequireDefault(require("chalk"));
 var _debug = _interopRequireDefault(require("debug"));
-var _bootstrap = require("lando/lib/bootstrap");
-var _lando = _interopRequireDefault(require("lando/lib/lando"));
-var _utils = _interopRequireDefault(require("lando/plugins/lando-core/lib/utils"));
-var _build = _interopRequireDefault(require("lando/plugins/lando-tooling/lib/build"));
 var _nodeChild_process = require("node:child_process");
 var _promises = require("node:dns/promises");
 var _promises2 = require("node:fs/promises");
@@ -31,6 +27,8 @@ var _nodeUtil = require("node:util");
 var _semver = require("semver");
 var _devEnvironmentCore = require("./dev-environment-core");
 var _dockerUtils = require("./docker-utils");
+var _landoLoader = require("./lando-loader");
+var _runtimeMode = require("../cli/runtime-mode");
 var _devEnvironment = require("../constants/dev-environment");
 var _env = _interopRequireDefault(require("../env"));
 var _userError = _interopRequireDefault(require("../user-error"));
@@ -43,6 +41,44 @@ function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e
 const DEBUG_KEY = '@automattic/vip:bin:dev-environment';
 const debug = (0, _debug.default)(DEBUG_KEY);
 const execFileAsync = (0, _nodeUtil.promisify)(_nodeChild_process.execFile);
+const unwrapLandoModuleDefault = loaded => {
+  if (loaded && typeof loaded === 'object' && 'default' in loaded) {
+    return loaded.default;
+  }
+  return loaded;
+};
+let landoConstructor = null;
+let landoBuildTaskFn = null;
+let landoUtilsModule = null;
+let buildConfigFn = null;
+const getLandoConstructor = () => {
+  if (!landoConstructor) {
+    landoConstructor = unwrapLandoModuleDefault((0, _landoLoader.loadLandoModule)('lando/lib/lando'));
+  }
+  return landoConstructor;
+};
+const getLandoBuildTask = () => {
+  if (!landoBuildTaskFn) {
+    landoBuildTaskFn = unwrapLandoModuleDefault((0, _landoLoader.loadLandoModule)('lando/plugins/lando-tooling/lib/build'));
+  }
+  return landoBuildTaskFn;
+};
+const getLandoUtils = () => {
+  if (!landoUtilsModule) {
+    landoUtilsModule = unwrapLandoModuleDefault((0, _landoLoader.loadLandoModule)('lando/plugins/lando-core/lib/utils'));
+  }
+  return landoUtilsModule;
+};
+const getLandoBuildConfig = () => {
+  if (!buildConfigFn) {
+    const loaded = (0, _landoLoader.loadLandoModule)('lando/lib/bootstrap');
+    buildConfigFn = loaded.buildConfig ?? loaded.default?.buildConfig ?? null;
+    if (!buildConfigFn) {
+      throw new Error('Unable to load Lando bootstrap buildConfig.');
+    }
+  }
+  return buildConfigFn;
+};
 const bannerLabelWidth = 18;
 let logPathRegistered = false;
 let resolvedLogPath = null;
@@ -146,7 +182,7 @@ const writeLogBanner = async config => {
   });
   const dockerVersions = await getDockerVersions(config);
   const command = process.argv.slice(1).join(' ');
-  const bannerLines = ['=== VIP Dev Env Log ===', formatBannerLine('COMMAND', command), formatBannerLine('OS', `${_env.default.os.name} ${_env.default.os.version} ${_env.default.os.arch}`), formatBannerLine('NODE', _env.default.node.version), formatBannerLine('VIP-CLI', _env.default.app.version), formatBannerLine('DOCKER ENGINE', dockerVersions.engine), formatBannerLine('DOCKER COMPOSE', dockerVersions.compose), formatBannerLine('COMPOSE PLUGIN', dockerVersions.composePlugin), formatBannerLine('DOCKER BIN', config.dockerBin ?? 'unknown'), formatBannerLine('COMPOSE BIN', config.composeBin ?? 'unknown'), formatBannerLine('RAM', formatBytes((0, _nodeOs.totalmem)())), formatBannerLine('CPU', String((0, _nodeOs.cpus)().length)), '===', '', ''];
+  const bannerLines = ['=== VIP Dev Env Log ===', formatBannerLine('COMMAND', command), formatBannerLine('OS', `${_env.default.os.name} ${_env.default.os.version} ${_env.default.os.arch}`), formatBannerLine('NODE', _env.default.node.version), formatBannerLine('VIP-CLI', _env.default.app.version), formatBannerLine('RUNTIME', (0, _runtimeMode.getRuntimeModeLabel)()), formatBannerLine('DOCKER ENGINE', dockerVersions.engine), formatBannerLine('DOCKER COMPOSE', dockerVersions.compose), formatBannerLine('COMPOSE PLUGIN', dockerVersions.composePlugin), formatBannerLine('DOCKER BIN', config.dockerBin ?? 'unknown'), formatBannerLine('COMPOSE BIN', config.composeBin ?? 'unknown'), formatBannerLine('RAM', formatBytes((0, _nodeOs.totalmem)())), formatBannerLine('CPU', String((0, _nodeOs.cpus)().length)), '===', '', ''];
   await (0, _promises2.writeFile)(logFilePath, bannerLines.join('\n'), {
     flag: 'a'
   });
@@ -157,7 +193,7 @@ const writeLogBanner = async config => {
  */
 async function getLandoConfig(options = {}) {
   // The path will be smth like `yarn/global/node_modules/lando/lib/lando.js`; we need the path up to `lando` (inclusive)
-  const landoPath = (0, _nodePath.dirname)((0, _nodePath.dirname)(require.resolve('lando')));
+  const landoPath = (0, _nodePath.dirname)((0, _nodePath.dirname)((0, _landoLoader.resolveLandoModule)('lando')));
   debug(`Getting Lando config, using paths '${landoPath}' for plugins`);
   const isLandoDebugSelected = _debug.default.enabled(DEBUG_KEY);
   const isAllDebugSelected = _debug.default.enabled('"*"');
@@ -201,7 +237,7 @@ async function getLandoConfig(options = {}) {
       LANDO_HOST_GROUP_ID: process.platform === 'win32' ? '1000' : `${(0, _nodeOs.userInfo)().gid}`
     }
   };
-  return (0, _bootstrap.buildConfig)(config);
+  return getLandoBuildConfig()(config);
 }
 const appMap = new Map();
 async function initLandoApplication(lando, instancePath) {
@@ -290,7 +326,8 @@ async function bootstrapLando(options = {}) {
     }
     registerLogPathOutput(config, Boolean(options.quiet));
     await writeLogBanner(config);
-    const lando = new _lando.default(config);
+    const LandoClass = getLandoConstructor();
+    const lando = new LandoClass(config);
     _debug.default.log = (message, ...args) => {
       lando.log.debug(message, ...args);
     };
@@ -425,7 +462,7 @@ async function landoInfo(lando, instancePath, options = {}) {
   const started = new Date();
   try {
     const app = await getLandoApplication(lando, instancePath);
-    const info = _utils.default.startTable(app);
+    const info = getLandoUtils().startTable(app);
     const reachableServices = app.info.filter(service => service.urls.length);
     reachableServices.forEach(service => info[`${service.service} urls`] = service.urls);
     const health = await checkEnvHealth(lando, app);
@@ -638,7 +675,7 @@ async function landoExec(lando, instancePath, toolName, args, options) {
     if (options.stdio) {
       tool.stdio = options.stdio;
     }
-    const task = (0, _build.default)(tool, lando);
+    const task = getLandoBuildTask()(tool, lando);
     const argv = {
       // eslint-disable-next-line id-length
       _: args

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

@@ -0,0 +1,48 @@
+"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

@@ -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