diff --git a/docs/superpowers/plans/2026-06-06-complete-partial-features.md b/docs/superpowers/plans/2026-06-06-complete-partial-features.md new file mode 100644 index 0000000..5195062 --- /dev/null +++ b/docs/superpowers/plans/2026-06-06-complete-partial-features.md @@ -0,0 +1,134 @@ +# Complete Partial Features Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Finish sshkeeper features that are currently stubbed or partially implemented, then align documentation and screenshots with the actual product. + +**Architecture:** Keep changes surgical and local to existing command, TUI, database, SSH, and tunnel modules. Prefer existing callbacks and model types over new abstractions. Each task must end with focused tests, a commit, and a push to `origin/main`. + +**Tech Stack:** Go 1.25, Cobra, Bubble Tea, SQLite via modernc.org/sqlite, OpenSSH command execution. + +--- + +## Files + +- Modify `cmd/forward.go`: make `forward edit` update stored forwards instead of printing a fake success. +- Modify `cmd/tunnel.go`: add `--background`, `list`, `stop`, and `stop-all` tunnel CLI support. +- Modify `internal/tunnel/manager.go`: improve process status checks, cleanup, and background tunnel startup validation. +- Modify `internal/ssh/command.go` and/or `internal/ssh/pty.go`: support safe non-interactive background tunnel behavior for secret auth or reject unsupported modes clearly. +- Modify `internal/db/servers.go`: search route JSON, tags, and forward fields. +- Modify `internal/tui/forward.go`: fix SOCKS/dynamic focus panic. +- Modify `internal/tui/app.go`, `internal/tui/help_screen.go`, `cmd/tui.go`: remove or implement action-menu stubs. +- Modify `cmd/import.go`, `cmd/extra.go` as needed if TUI import/export should delegate to existing CLI behavior. +- Modify `README.md`, `docs/guide.md`, `docs/roadmap/v0.2.0.md`: bring docs into line with implemented behavior. +- Replace `docs/screenshots/screen_*.png`: clean screenshots for main, action menu, routes, forwards, tunnels. +- Add/modify tests in `cmd/*_test.go`, `internal/db/*_test.go`, `internal/tui/*_test.go`, `internal/tunnel/*_test.go`, `internal/ssh/*_test.go`. + +## Task 1: Small Partial Features and Search + +- [ ] Step 1: Add failing tests for SOCKS forward form focus. + - Test file: `internal/tui/app_test.go`. + - Behavior: selecting dynamic/SOCKS and rendering/updating focus must not panic. + - Run: `env GOCACHE=/tmp/sshkeeper-go-cache go test ./internal/tui -run 'TestForward.*Dynamic|TestForward.*SOCKS'`. + - Expected before implementation: fail or panic. + +- [ ] Step 2: Fix the forward form label/focus logic. + - File: `internal/tui/forward.go`. + - Keep hidden inputs from asking for labels that do not exist for dynamic forwards. + +- [ ] Step 3: Add failing CLI tests for `forward edit`. + - Test file: `cmd/forward_test.go` or existing cmd tests. + - Behavior: editing `--enabled=false` persists the enabled state for the selected forward. + - Run focused cmd tests. + +- [ ] Step 4: Implement `forward edit`. + - File: `cmd/forward.go`. + - Load the forward, validate it exists, apply only changed flags, persist with `appDB.UpdateForward`. + +- [ ] Step 5: Add failing search tests. + - Test file: `internal/db/servers_test.go`. + - Behavior: search finds servers by tags, route hops, and forward ports. + +- [ ] Step 6: Implement expanded search. + - File: `internal/db/servers.go`. + - Use SQL `EXISTS` subqueries for tags and forwards, include `route_hops`. + +- [ ] Step 7: Verify and commit. + - Run: `env GOCACHE=/tmp/sshkeeper-go-cache go test ./internal/tui ./internal/db ./cmd`. + - Run: `env GOCACHE=/tmp/sshkeeper-go-cache go vet ./...`. + - Commit: `fix: complete forwards and search behavior`. + - Push: `git push origin main`. + +## Task 2: Tunnel CLI and Background State + +- [ ] Step 1: Add failing tests for tunnel process status. + - Test file: `internal/tunnel/manager_test.go`. + - Behavior: `IsRunning` returns false for missing/stopped PIDs and uses signal 0 semantics. + +- [ ] Step 2: Fix process status and cleanup. + - File: `internal/tunnel/manager.go`. + - Use `syscall.Signal(0)`, remove stopped states on list/refresh where appropriate, and report save errors when state persistence fails. + +- [ ] Step 3: Add failing command tests for tunnel subcommands. + - Test file: `cmd/tunnel_test.go`. + - Behavior: `tunnel --help` exposes `--background`; `tunnel list`, `tunnel stop `, and `tunnel stop-all` are registered. + +- [ ] Step 4: Implement tunnel CLI subcommands. + - File: `cmd/tunnel.go`. + - `--background` starts `tunnelpkg.Start`; `list` prints saved states and status; `stop` and `stop-all` delegate to manager. + +- [ ] Step 5: Handle secret auth background tunnels safely. + - File: `cmd/tunnel.go` or `internal/tunnel/manager.go`. + - If password/key-passphrase background tunneling cannot be supported safely without interactive PTY, reject with a clear error. Do not create a broken saved state. + +- [ ] Step 6: Verify and commit. + - Run: `env GOCACHE=/tmp/sshkeeper-go-cache go test ./internal/tunnel ./cmd ./internal/ssh`. + - Run: `env GOCACHE=/tmp/sshkeeper-go-cache go vet ./...`. + - Commit: `feat: add tunnel background cli management`. + - Push: `git push origin main`. + +## Task 3: TUI Stub Actions + +- [ ] Step 1: Route action. + - Implement a non-stub route action in TUI. Minimal acceptable behavior: open an edit flow for route hops or delegate to server edit where route/proxy jump can be changed, with clear user-facing text. + - Add tests that action no longer sets `not yet implemented`. + +- [ ] Step 2: Import/export actions. + - Implement TUI import by calling existing import logic and refreshing the server list. + - Implement TUI export if a real export command exists; otherwise remove the TUI action and documentation entry so no fake capability is shown. + +- [ ] Step 3: Vault actions. + - Implement TUI vault lock by locking the current process vault. + - Implement TUI vault change password only if it can safely exit to a CLI prompt; otherwise remove the menu entry and keep the CLI command documented. + +- [ ] Step 4: Verify and commit. + - Run: `env GOCACHE=/tmp/sshkeeper-go-cache go test ./internal/tui ./cmd`. + - Run: `env GOCACHE=/tmp/sshkeeper-go-cache go vet ./...`. + - Commit: `feat: replace tui action stubs`. + - Push: `git push origin main`. + +## Task 4: Documentation and Screenshots + +- [ ] Step 1: Update README and guide. + - Ensure every documented command exists and every TUI action described is implemented or intentionally absent. + - Clarify background tunnels with secret auth limitations if unsupported. + +- [ ] Step 2: Update roadmap status. + - Mark fulfilled features accurately and note remaining future work only if it is not shown as available. + +- [ ] Step 3: Rebuild and capture screenshots. + - Build binary with `env GOCACHE=/tmp/sshkeeper-go-cache go build -o /tmp/sshkeeper-screens .`. + - Use isolated `XDG_CONFIG_HOME` and `XDG_DATA_HOME` under `/tmp`. + - Capture clean terminal screenshots for main list, action menu, route/forward/tunnel screens. + +- [ ] Step 4: Verify and commit. + - Run: `env GOCACHE=/tmp/sshkeeper-go-cache go test ./...`. + - Run: `env GOCACHE=/tmp/sshkeeper-go-cache go vet ./...`. + - Commit: `docs: align guide and screenshots`. + - Push: `git push origin main`. + +## Final Verification + +- [ ] Run full checks: `env GOCACHE=/tmp/sshkeeper-go-cache go test ./...`. +- [ ] Run full vet: `env GOCACHE=/tmp/sshkeeper-go-cache go vet ./...`. +- [ ] Confirm `git status --short --branch` is clean and `main` is pushed.