mirivlad
/
sshkeeper
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 1 Wiki Activity
sshkeeper/docs/superpowers/plans/2026-06-06-complete-partial...

7.3 KiB
Raw Blame History

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 <id>, 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.