@vertaaux/cli 0.3.3 → 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,97 @@
+# Changelog
+
+All notable changes to `@vertaaux/cli` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.5.0] - 2026-03-19
+
+### Added
+
+- **Interactive terminal app** — full-screen menu-driven interface with keyboard navigation, live dashboard, and canvas layout (launched via `vertaa` with no args)
+- **@vertaaux/tui package** — terminal UI primitives (spinner, table, progress, box, error-box, step-list, viewport) bundled into the CLI
+- **PTY test infrastructure** — node-pty based terminal tests with ANSI serializers, xterm-256color emulation, and dedicated vitest config
+- **Subprocess test infrastructure** — process-level E2E tests with build caching, mock audit server, and contract validation
+- **Snapshot test infrastructure** — long-running compilation snapshot tests with NO_COLOR determinism
+- **Package install tests** — artifact validation via `npm pack` and tarball installation
+- **Cross-platform CI matrix** — Ubuntu/macOS/Windows × Node 20/22 in `cli-e2e.yml` workflow
+- **1953 unit tests** across 112 test files covering commands, auth, config, output, security, caching, CI detection, monorepo support, and quality gates
+- **Credential file support** — reads API key from `~/.vertaaux/credentials.json` as fallback (with symlink and permission checks)
+- **Error propagation improvements** — unhandled errors in command handlers now produce exit code 2 with branded error boxes
+
+### Changed
+
+- **Commander upgraded to v14** — from v12, with improved help formatting and error handling
+- **Vitest upgraded to v4** — from v3, with `fileParallelism: false` replacing deprecated `poolOptions.forks.singleFork`
+- **Error rendering** — all command errors now render through `renderError()` with suggestion hints and proper exit codes
+
+### Fixed
+
+- **Flaky TTY detection** in subprocess tests
+- **Fetch resource leak** — unclosed responses in API client
+- **Timer cleanup** — lingering timers in polling commands
+- **ESLint compliance** — replaced `require()` calls with string concatenation for no-require-imports rule
+
+### Security
+
+- **Symlink check on credentials** — refuses to read `~/.vertaaux/credentials.json` if it's a symlink (SECVAL-1)
+- **Permission check on credentials** — warns if file permissions are overly permissive on Unix systems (SECVAL-2)
+
+## [0.4.0] - 2026-02-15
+
+### Added
+
+- **Localhost/private URL auditing** via static HTML analysis
+- `whoami` command shows name, email, and plan
+
+## [0.3.3] - 2026-02-10
+
+### Fixed
+
+- Documentation accuracy improvements
+
+## [0.3.0] - 2026-02-08
+
+### Added
+
+- **AI Intelligence commands** — `suggest`, `triage`, `fix-plan`, `patch-review`, `release-notes`, `compare`, `doc`
+- **Pipeline input** — all AI commands accept stdin pipe, `--file`, or `--job`
+- Per-command format validation with format registry
+- JSON output envelope with metadata
+- `--machine` flag for strict machine-readable output
+- Branded error messages with typo suggestions
+- `doctor` command for CLI health diagnostics
+- Exit code 3 for threshold breaches
+
+### Changed
+
+- `--format` moved from global to per-command option
+- Diagnostic output moved to stderr (stdout reserved for format output)
+- Strict input validation with exit code 2
+
+## [0.2.0] - 2026-01-25
+
+### Added
+
+- Per-command format system
+- JSON output envelope
+- `--machine` flag
+- `doctor` command
+- Levenshtein suggestions for enum flags
+- Branch name validation
+- Artifact path traversal protection
+
+### Changed
+
+- Breaking: `--format` is now per-command
+- Breaking: JSON output wrapped in envelope
+- Breaking: diagnostics moved to stderr
+- Breaking: strict input validation (exit code 2)
+- Breaking: exit code 3 for threshold breach (was 1)
+
+[0.5.0]: https://github.com/PetriLahdelma/vertaa/compare/cli-v0.4.0...cli-v0.5.0
+[0.4.0]: https://github.com/PetriLahdelma/vertaa/compare/cli-v0.3.3...cli-v0.4.0
+[0.3.3]: https://github.com/PetriLahdelma/vertaa/compare/cli-v0.3.0...cli-v0.3.3
+[0.3.0]: https://github.com/PetriLahdelma/vertaa/compare/cli-v0.2.0...cli-v0.3.0
+[0.2.0]: https://github.com/PetriLahdelma/vertaa/releases/tag/cli-v0.2.0

package/MIGRATION.md

@@ -0,0 +1,239 @@
+# VertaaUX CLI Migration Guide
+
+## Upgrading to v0.5.0
+
+This release adds the interactive terminal app, credential file support, and a major test infrastructure overhaul. One behavior change: running `vertaa` with no arguments now launches an interactive app instead of printing help — see below for migration.
+
+### New: Interactive App
+
+Running `vertaa` with no arguments now launches a full-screen interactive menu. If you have scripts that run `vertaa` with no args and expect help output, add `--help` explicitly:
+
+```bash
+# Before (printed help)
+vertaa
+
+# After (launches interactive app)
+vertaa
+
+# To get help output in scripts
+vertaa --help
+```
+
+### New: Credential File Fallback
+
+The CLI now reads API keys from `~/.vertaaux/credentials.json` when neither `VERTAAUX_API_KEY` nor `--api-key` is set. This file is created by `vertaa login`.
+
+Auth resolution order: `VERTAAUX_API_KEY` env var → `apiKey` in config file (`.vertaaux.yml`) → `~/.vertaaux/credentials.json`.
+
+If you relied on the CLI failing when no env var was set (e.g., to detect missing CI configuration), be aware that stored credentials on the machine may now be used as a fallback. To ensure no credentials are used, point `HOME` (or `USERPROFILE` on Windows) to an empty directory.
+
+### New: Error Rendering
+
+Unhandled errors in command handlers now produce branded error boxes on stderr with a `vertaa doctor` suggestion, instead of raw stack traces. Exit codes are unchanged (still 2 for errors).
+
+### Dependency Changes
+
+| Dependency | Before | After |
+|-----------|--------|-------|
+| `commander` | ^12.x | ^14.0.2 |
+| `@vertaaux/tui` | — | bundled |
+| `node-pty` | — | ^1.1.0 (dev) |
+| `vitest` | ^3.x | ^4.0.15 (dev) |
+
+### Security Hardening
+
+- Credentials file is rejected if it's a symlink
+- Warning emitted if credentials file permissions are too open (non-Windows)
+
+These checks are transparent — no action needed unless you store credentials as symlinks.
+
+## Upgrading to v0.4.0
+
+### Added
+
+- Localhost and private URL auditing via static HTML analysis
+- `whoami` shows name, email, and plan tier
+
+No breaking changes.
+
+## Upgrading to v0.2.0
+
+This release includes several breaking changes from the CLI hardening phases (36-39). Most changes improve correctness and safety -- existing scripts using standard patterns will work without modification.
+
+### Breaking Changes
+
+#### 1. Format Flag Scope Changed
+
+**Before:** `--format` was a global flag applied to all commands.
+
+**After:** `--format` is a per-command option with different allowed values per command.
+
+| Command | Allowed Formats | Default |
+|---------|----------------|---------|
+| `audit` | `human`, `json`, `sarif`, `junit`, `html` | `human` |
+| `comment` | `json`, `markdown` | `markdown` |
+| `explain` | `human`, `json` | `human` |
+| `policy show` | `json`, `yaml` | `yaml` |
+| `diff` | `human`, `json` | `human` |
+
+**Migration:**
+
+Move `--format` from before the command to after it:
+
+```bash
+# Before
+vertaa --format json audit https://example.com
+
+# After
+vertaa audit https://example.com --format json
+```
+
+Using an unsupported format for a command now exits with code 2:
+
+```bash
+vertaa comment --format sarif  # Error: Invalid format "sarif" for "comment"
+```
+
+#### 2. JSON Output Wrapped in Envelope
+
+**Before:** JSON output was a raw data object.
+
+**After:** JSON output is wrapped in an envelope containing metadata.
+
+```json
+// Before
+{
+  "scores": { "overall": 85 },
+  "issues": [...]
+}
+
+// After
+{
+  "meta": {
+    "version": "0.3.2",
+    "timestamp": "2026-02-08T12:00:00.000Z",
+    "command": "audit",
+    "args": ["https://example.com", "--format", "json"]
+  },
+  "data": {
+    "scores": { "overall": 85 },
+    "issues": [...]
+  }
+}
+```
+
+**Migration:**
+
+Update JSON parsers to access `.data` instead of the top level:
+
+```bash
+# Before
+cat results.json | jq '.scores.overall'
+
+# After
+cat results.json | jq '.data.scores.overall'
+```
+
+```javascript
+// Before
+const result = JSON.parse(output);
+console.log(result.scores.overall);
+
+// After
+const envelope = JSON.parse(output);
+console.log(envelope.data.scores.overall);
+// Bonus: envelope.meta.version, envelope.meta.timestamp available
+```
+
+#### 3. Diagnostic Output Moved to stderr
+
+**Before:** Banners, progress indicators, and diagnostic messages were mixed into stdout.
+
+**After:** Only format output goes to stdout. All diagnostics go to stderr.
+
+**Migration:**
+
+If you were parsing stdout and filtering out banners, you can now pipe directly:
+
+```bash
+# Before (required filtering)
+vertaa audit https://example.com --format json 2>/dev/null | grep -v "VertaaUX" | jq .
+
+# After (clean piping)
+vertaa audit https://example.com --format json | jq .
+```
+
+If you were capturing stderr for errors, note that progress and banner output now also goes to stderr.
+
+#### 4. Strict Input Validation
+
+**Before:** Invalid flag values were silently accepted or caused confusing runtime errors.
+
+**After:** Invalid values are rejected immediately with exit code 2 and clear error messages.
+
+```bash
+# Numeric validation
+vertaa audit https://example.com --timeout abc
+# error: expected a number, got "abc"
+# Exit code: 2
+
+# Enum validation with suggestions
+vertaa audit https://example.com --mode depp
+# error: invalid value for --mode
+#   hint: Did you mean "deep"?
+#   valid: basic, standard, deep
+# Exit code: 2
+
+# Range validation
+vertaa audit https://example.com --threshold 150
+# error: expected 0-100, got 150
+# Exit code: 2
+```
+
+**Migration:**
+
+No action needed unless your scripts intentionally pass invalid values. Scripts that were relying on invalid values being silently ignored will now fail with exit code 2.
+
+#### 5. Branch Name Sanitization
+
+**Before:** Any string was accepted as a branch name in `--base-branch`.
+
+**After:** Branch names are validated against `/^[a-zA-Z0-9._\/-]+$/` with a maximum length of 255 characters. Shell metacharacters are rejected.
+
+**Migration:**
+
+No action needed for standard git branch names. If you have branches with unusual characters, they will be rejected.
+
+```bash
+# These work fine
+vertaa audit --incremental --base-branch main
+vertaa audit --incremental --base-branch feature/my-feature
+vertaa audit --incremental --base-branch release/v1.2.3
+
+# These are now rejected
+vertaa audit --incremental --base-branch "main; rm -rf /"
+vertaa audit --incremental --base-branch 'feat$(whoami)'
+```
+
+### New Features
+
+| Feature | Description |
+|---------|-------------|
+| `vertaa doctor` | Diagnose CLI health (config, auth, network connectivity) |
+| `--config <path>` | Explicit config file path (overrides auto-detection) |
+| `--machine` | Strict machine-readable output mode (JSON stdout, diagnostics stderr) |
+| Levenshtein suggestions | Typo corrections for enum flags (e.g., `depp` suggests `deep`) |
+| Branded errors | Box-drawn error frames with flag/value context and help hints |
+| `--force` on init | Overwrite existing `.vertaaux.yml` configuration |
+| `--yes` on init | Skip interactive prompts, use defaults |
+
+### Exit Code Changes
+
+| Code | Before | After |
+|------|--------|-------|
+| `0` | Success | Success (unchanged) |
+| `1` | Issues found | Issues found (unchanged) |
+| `2` | Error | Error AND validation errors (expanded) |
+| `3` | - | Threshold breach (new) |
+
+Exit code 2 now covers all validation errors (previously some caused exit code 1 or undefined behavior). Exit code 3 is new for `--threshold` breaches (previously used exit code 1).

package/README.md

@@ -29,22 +29,40 @@ vertaa doctor
 
 ## Authentication
 
-The CLI checks for credentials in this order:
+The CLI uses the `@vertaaux/sdk` for all API calls. The SDK handles auth automatically — you
+only need to configure credentials once. Three methods are supported:
 
-1. **Environment variables** (checked in order):
-   - `VERTAAUX_TOKEN`
-   - `VERTAAUX_API_KEY`
+### 1. Default credentials (recommended)
 
-2. **Stored credentials** from interactive login:
-   ```bash
-   vertaa login
-   ```
-   Credentials are stored in `~/.vertaaux/credentials.json`.
+Run `vertaa login` to store credentials in `~/.vertaaux/credentials.json`. The SDK reads
+these on every subsequent command — no flags needed.
 
-3. **Direct token** for CI/non-interactive use:
-   ```bash
-   vertaa login --token <api-key>
-   ```
+```bash
+vertaa login
+```
+
+This stores credentials for SDK-based auth. Use `vertaa whoami` to verify.
+
+### 2. Environment variable
+
+Set `VERTAAUX_API_KEY` (or `VERTAAUX_TOKEN`) in your shell or CI environment. The SDK
+reads this automatically on every command.
+
+```bash
+export VERTAAUX_API_KEY=vtx_...
+vertaa audit https://example.com --wait
+```
+
+### 3. `--api-key` flag (override for scripts and CI)
+
+Pass `--api-key <key>` to any command to override SDK auth for that invocation. This is
+intended for CI pipelines where the key comes from a secret manager or is passed inline.
+
+```bash
+VERTAAUX_API_KEY=${{ secrets.VERTAAUX_API_KEY }} vertaa audit https://example.com
+```
+
+**Auth priority:** `--api-key` flag > `VERTAAUX_API_KEY` env > `VERTAAUX_TOKEN` env > stored credentials.
 
 Verify authentication:
 
@@ -147,7 +165,7 @@ The `--machine` global flag enables strict machine-readable mode:
 ```json
 {
   "meta": {
-    "version": "0.3.3",
+    "version": "0.5.0",
     "timestamp": "2026-02-08T12:00:00.000Z",
     "command": "audit",
     "args": ["https://example.com", "--format", "json"]
@@ -339,8 +357,8 @@ JSON envelope output automatically filters CLI arguments containing API keys or
 
 | Variable | Purpose |
 |----------|---------|
-| `VERTAAUX_API_KEY` | API authentication key |
-| `VERTAAUX_TOKEN` | Alternative auth token (checked first) |
+| `VERTAAUX_API_KEY` | API key (used by SDK; `--api-key` flag overrides this per-command) |
+| `VERTAAUX_TOKEN` | Alternative auth token (checked before `VERTAAUX_API_KEY`) |
 | `VERTAAUX_API_BASE` | API base URL override |
 | `VERTAAUX_AUTH_BASE` | Auth endpoint override (default: `https://vertaaux.ai`) |
 | `VERTAAUX_LOG_LEVEL` | Log verbosity: `debug\|info\|warn\|error` (default: `info`) |

package/dist/app/interactive-app.d.ts

@@ -0,0 +1,101 @@
+/**
+ * InteractiveApp — Persistent 3-section interactive CLI shell.
+ *
+ * Manages a fixed layout:
+ *   [Header]   — sticky banner at top (buildFrame3)
+ *   [Canvas]   — active view content, fixed height
+ *   [Footer]   — status left, keyboard shortcuts right
+ *
+ * Uses alternate screen buffer (CSI ?1049h/l) so the layout is scroll-proof.
+ * Each frame redraw uses cursor.home + screen.clear — no cursor arithmetic needed.
+ *
+ * All writes go to the injected output stream (defaults to process.stderr).
+ * stdout is reserved for --format json output.
+ */
+import type { CommandView, AppState } from "./types.js";
+/**
+ * InteractiveApp provides the persistent 3-section layout for the
+ * `vertaa` (no-args) interactive mode.
+ *
+ * Usage:
+ *   const app = new InteractiveApp();
+ *   await app.run(); // blocks until Ctrl+C or app.dispose()
+ */
+export declare class InteractiveApp {
+    /** @internal — exposed for testing via private access */
+    _state: AppState;
+    /**
+     * Whether the app is currently on the alternate screen.
+     * @internal — exposed for testing
+     */
+    private entered;
+    /** @internal — exposed for testing */
+    _suspended: boolean;
+    private output;
+    private tickTimer;
+    private resizeTimer;
+    private frameIndex;
+    private version;
+    private resolveRun;
+    constructor(output?: NodeJS.WritableStream);
+    /**
+     * Start the interactive app.
+     *
+     * Enters alternate screen buffer, configures stdin for raw keyboard input,
+     * renders the initial frame, and returns a Promise that resolves when
+     * dispose() is called.
+     */
+    run(): Promise<void>;
+    /**
+     * Build the complete frame string for the current state.
+     *
+     * Frame = header + canvas + footer, sized to terminal dimensions.
+     */
+    buildFrame(): string;
+    /**
+     * Redraw the terminal using home+clear on the alternate screen.
+     *
+     * Guarded by `if (!this.entered) return` — prevents double-redraw race
+     * when setView() calls this.redraw() after onMount() completes while
+     * the app is suspended (entered === false).
+     */
+    redraw(): void;
+    /**
+     * Set the active view, calling lifecycle hooks.
+     *
+     * Unmounts any existing view, mounts the new one, switches to command
+     * screen, and triggers an immediate redraw.
+     *
+     * NOTE: When the app is suspended (entered === false), the post-onMount
+     * redraw() call is a safe no-op — guarded by the `!this.entered` check.
+     */
+    setView(view: CommandView): Promise<void>;
+    /**
+     * Unmount the active view and return to the menu screen.
+     */
+    clearView(): Promise<void>;
+    /**
+     * Suspend the app — exit alternate screen and stop the tick loop.
+     *
+     * Call before launching @inquirer/prompts or running a command handler
+     * to hand control back to the normal terminal.
+     */
+    suspend(): void;
+    /**
+     * Resume the app — re-enter alternate screen and restart the tick loop.
+     *
+     * Call after a command handler completes to restore the interactive layout.
+     */
+    resume(): void;
+    /**
+     * Tear down the app — exits alternate screen, stops tick, removes listeners.
+     */
+    dispose(): void;
+    /** Get the current animation frame index (for spinner rendering in views). */
+    getFrameIndex(): number;
+    private startTick;
+    private stopTick;
+    private onResize;
+    private onKeyData;
+}
+//# sourceMappingURL=interactive-app.d.ts.map

package/dist/app/interactive-app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interactive-app.d.ts","sourceRoot":"","sources":["../../src/app/interactive-app.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAUH,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAa,MAAM,YAAY,CAAC;AAWnE;;;;;;;GAOG;AACH,qBAAa,cAAc;IACzB,yDAAyD;IACzD,MAAM,EAAE,QAAQ,CAId;IAEF;;;OAGG;IACH,OAAO,CAAC,OAAO,CAAS;IAExB,sCAAsC;IACtC,UAAU,UAAS;IAEnB,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,SAAS,CAA+C;IAChE,OAAO,CAAC,WAAW,CAA8C;IACjE,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,UAAU,CAA6B;gBAEnC,MAAM,GAAE,MAAM,CAAC,cAA+B;IAQ1D;;;;;;OAMG;IACG,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IAuB1B;;;;OAIG;IACH,UAAU,IAAI,MAAM;IA6BpB;;;;;;OAMG;IACH,MAAM,IAAI,IAAI;IAMd;;;;;;;;OAQG;IACG,OAAO,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAY/C;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAUhC;;;;;OAKG;IACH,OAAO,IAAI,IAAI;IAsBf;;;;OAIG;IACH,MAAM,IAAI,IAAI;IAoBd;;OAEG;IACH,OAAO,IAAI,IAAI;IAgCf,8EAA8E;IAC9E,aAAa,IAAI,MAAM;IAMvB,OAAO,CAAC,SAAS;IAUjB,OAAO,CAAC,QAAQ;IAOhB,OAAO,CAAC,QAAQ,CAWd;IAEF,OAAO,CAAC,SAAS,CAmCf;CACH"}