feat(cli): add spz port-forward command

[onutc]

TL;DR

This adds a first-class spz port-forward command to the Spritz CLI and wires the Spritz SSH gateway to support it end to end. Callers can now forward one local loopback port into one instance without manual ssh -L composition.

Summary

• add spz port-forward <name> --local <port> --remote <port> [--namespace <ns>] [--print]
• reuse the existing short-lived SSH credential flow used by spz ssh
• extend the Spritz SSH gateway with a custom direct-tcpip handler that forwards into the target pod instead of the gateway pod
• keep the first version loopback-only on both sides and reject unrelated --session / --transport flags
• add targeted CLI tests plus API tests for loopback validation and injected end-to-end SSH forwarding behavior
• keep the generic architecture doc and bundled CLI skill aligned with the new primitive

Review Focus

• shared SSH plumbing in cli/src/index.ts
• pod-scoped forwarding behavior in api/ssh_gateway.go
• loopback-only forwarding contract for the initial implementation
• test coverage for printed CLI behavior and forwarded SSH traffic

Validation

• pnpm --dir /Users/onur/repos/spritz/cli test -- test/help.test.ts test/port-forward.test.ts
• pnpm --dir /Users/onur/repos/spritz/cli build
• pnpm --dir /Users/onur/repos/spritz/cli test
• go test ./... from /Users/onur/repos/spritz/api
• npx -y @simpledoc/simpledoc check
• codex review --base main

[onutc]

Implementation is ready on 2ccbc76.

Validation run:

• pnpm --dir /Users/onur/repos/spritz/cli test -- test/help.test.ts test/port-forward.test.ts
  • passed (6 tests)
• pnpm --dir /Users/onur/repos/spritz/cli build
  • passed
• pnpm --dir /Users/onur/repos/spritz/cli test
  • passed (26 passed, 1 existing skipped terminal test)
• go test ./... from /Users/onur/repos/spritz/api
  • passed
• npx -y @simpledoc/simpledoc check
  • passed (OK: repo matches SimpleDoc conventions.)

What changed after the original CLI commit:

• local codex review --base main initially surfaced a real P1: the new CLI command was advertised before the SSH gateway could actually forward traffic
• fixed that by adding SSH gateway support for pod-scoped direct-tcpip forwarding, loopback-only destination checks, and API coverage for injected end-to-end forwarding behavior
• pushed follow-up commit 2ccbc76 (fix(api): support ssh port forwarding)

GitHub status:

• no PR issue comments
• no inline review comments
• CI is green on the current head (cli-tests, docs-check, go-tests, and Docker builds all succeeded)

One caveat:

• post-fix codex review --base main reruns revalidated the correct CLI/API commands but did not terminate cleanly before manual interruption, so there is no final clean-text “no findings” footer from the tool. It did not surface any additional P0/P1 after the gateway fix.

[gitrank-connector]

👍 GitRank PR Analysis

Score: 20 points

Metric	Value
Component	Other (1× multiplier)
Severity	P2 - Medium (20 base pts)
Final Score	20 × 1 = 20

Eligibility Checks

Check	Status
Issue/Bug Fix	❌
Fix Implementation	✅
PR Documented	✅
Tests	✅
Lines Within Limit	✅

Impact Summary

This PR introduces a first-class spz port-forward command that allows users to forward local loopback ports into private instance ports without manual SSH composition. The implementation reuses existing SSH credential flows, extends the SSH gateway with a custom direct-tcpip handler, and includes comprehensive tests covering CLI behavior, loopback validation, and end-to-end SSH forwarding. The feature is well-documented with architecture decisions and skill documentation updates.

Analysis Details

Component Classification: This PR adds a new feature (port-forward command) that spans CLI, API gateway, and documentation. Since it doesn't fit neatly into a single specialized component category and represents a cross-cutting feature addition, OTHER with 1x multiplier is appropriate.

Severity Justification: This is a new feature addition rather than a bug fix or critical issue. It provides meaningful functionality (instance port forwarding) but is not addressing a service outage or security vulnerability. P2 (Medium) reflects that it's a functional enhancement with proper implementation and testing, but not critical to core operations.

Eligibility Notes: Tests are required and present: the PR includes 224 lines of new test code in port-forward.test.ts covering command execution, SSH argument validation, and error cases, plus 187 lines in ssh_gateway_test.go for loopback validation and port forwarding behavior. The PR is properly linked with detailed description explaining TL;DR, summary, review focus, and validation steps. This is a new feature (not a bug fix), so issue=false. fix_implementation=true because the code changes fully implement the described port-forward command with SSH integration.

---

Analyzed by GitRank 🤖