Doc updates

Author: rinatkhaziev

AGENTS.md

@@ -14,6 +14,7 @@ Guide for future agents working on this codebase. Focus on traps, cross-cutting
 - `_opts` knobs: `appContext`/`envContext`/`childEnvContext` run GraphQL lookups (using `appQuery` + optional fragments) and interactive prompts when `--app/--env` are missing; `childEnvContext` forbids production. `requiredArgs` enforces positional count; `wildcardCommand` disables subcommand validation. `format` adds `--format` defaulting to table and postprocesses handler results; `requireConfirm` + `--force` gates destructive paths with `enquirer` prompts; `skipConfirmPrompt` bypasses the prompt (used in tests).
 - Alias handling happens before parsing: `@app` or `@app.env` is stripped from `argv` in `envAlias.ts` (only before `--`) and populates `options.app/options.env`. Using both alias and `--app/--env` exits with an error.
 - Global flags injected everywhere: `--help/--version/--debug`. `--debug` enables `debug` namespaces (`*` when boolean). `update-notifier` runs after validation unless `NODE_ENV=test`.
+- Short-flag parity detail: if an option has no explicit short alias, the wrapper can auto-assign one from the first long-option character (for `args` compatibility), except reserved globals (`h`, `v`, `d`) and already-used short names.
 - Nested subcommands are dispatched by the wrapper to sibling bin scripts (`vip-config` -> `vip-config-envvar` -> `vip-config-envvar-set`) using local `dist/bin` paths when available.
 - Output contract: if handler returns `{header,data}` it prints header as key/value then formats `data`; if it returns an array it strips `__typename` and formats; returning `undefined` skips printing. Formatting uses `formatData` with `table|csv|json`.
 - Caveat: `_opts` is shared. Instantiating multiple command runners in one process (tests, composite commands) can leak settings—avoid or refactor.
@@ -49,6 +50,9 @@ Guide for future agents working on this codebase. Focus on traps, cross-cutting
 - Implemented under `src/lib/dev-environment/**`; shells out to Lando and Docker, renders templates from `assets/dev-env.*.ejs`, and writes to per-environment folders inside `xdgData()/vip-cli` (overridden by `XDG_DATA_HOME`). Running these commands mutates local docker networks and may fetch WP/PHP version metadata from GitHub constants.
 - Proxy helpers live in `src/lib/http/proxy-*`; dev-env code constructs agents automatically using `VIP_PROXY`/`SOCKS_PROXY`/`HTTP_PROXY`/`VIP_USE_SYSTEM_PROXY`. Unexpected proxies can break downloads—clear those env vars when debugging.
 - Avoid invoking dev-env logic in unit tests unless you mock `lando`, filesystem, and network; the E2E suite covers the real paths.
+- Runtime resilience safeguards:
+  - `startEnvironment()` performs bounded readiness checks after start/rebuild and attempts one recovery `landoStart` pass if status remains down.
+  - `vip-dev-env-exec` performs bounded readiness polling before failing with "running environment required", reducing false negatives under heavy Docker/Lando load.
 
 ## Import/Export/Sync Commands (high validation)
 - Heavy validators live in `src/lib/site-import/**` and `src/lib/validations/**`. `vip import sql` enforces file name rules, extension checks, size caps (`SQL_IMPORT_FILE_SIZE_LIMIT*`), and detects multisite; it may upload to S3 via `src/lib/client-file-uploader.ts` (expects readable file or URL and optional MD5). These paths also emit analytics; use `NODE_ENV=test` and stubs to avoid network.

docs/COMMANDER-MIGRATION.md

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