dial/dial-v2-plan.md

# dial — v2 Plan

Written against the v1 REPORT.md handoff. v1 is complete, tested, and out of
scope to modify except where noted. This plan is scoped to be handed to
Claude Code as-is; every judgment call is flagged so it can be overridden.

---

## 1. Alphabetical sort (small, do first)

- Add a third sort mode to the existing `s` toggle: **recently used → most
  used → alphabetical → (back to recently used)**.
- Alphabetical sorts by `Host` alias (the thing the user actually types/sees
  first in the list), case-insensitive.
- Favourites still pin to the top regardless of sort mode (unchanged v1
  behaviour).
- Persist the selected mode the same way recents/frequency already persist
  (`~/.ssh/.dial/data.json`).

No open questions here — this is a straightforward extension of existing code.

---

## 2. SSH key generation tool (`dial keygen`)

Rebuilt from the logic in `create_ssh_keypair.sh`, fixing the cross-platform
and UX issues found in it, and wired into `dial` as a new subcommand rather
than folded into the interactive picker.

**Why a separate subcommand, not part of the picker:** the picker's core
read-only-config guarantee is a deliberate v1 property. Keygen necessarily
*writes* to `~/.ssh/config` and creates key files, so it should be a distinct,
explicitly-invoked action (`dial keygen`) — not something that can happen by
accidentally pressing a key while browsing hosts.

### Fixes over the original script
- Replace the macOS-only `sed -i ''` public-key-comment logic with something
  that works identically on macOS/Linux/Windows (Go string handling, no shell
  `sed` dependency at all).
- Default algorithm: **ed25519**. Offer `--rsa` (4096-bit) as an explicit
  opt-out for hosts that don't support ed25519 (some older network gear, e.g.
  legacy broadcast equipment, may not).
- **Keep the `.pub` file.** Don't delete it after displaying it once — that
  behaviour in the original script means a lost copy-paste = a wasted key.
  Still print it to the terminal for convenience, but leave the file in place.
- Proper quoting/escaping when appending to `~/.ssh/config` (avoid the blind
  `read` + string-concat approach in the original).

### Proposed flow
```
dial keygen
  → prompt: key name / label
  → prompt: algorithm (default ed25519, flag for rsa)
  → generate into ~/.ssh/<label>  (and .pub alongside, kept)
  → prompt: add a Host entry to ~/.ssh/config now? (y/n)
      → if yes: Host alias / HostName / User / Port (default 22) / tag (optional, using existing `# tag:` convention)
  → print the public key once for easy copy, key file left on disk
```

**Assumption flagged:** this reuses `dial`'s existing static-list, low-light-
friendly prompt styling rather than plain unstyled `read` prompts like the
original script, for consistency with the rest of the tool.

---

## 3. Remaining v2 features (from REPORT.md open questions)

Going through the report's nine open questions individually, with a decision
made and flagged for each so this can go straight to Claude Code.

### 3.1 SFTP / file transfer mode — **in scope for v2: full in-app browser**
- After selecting a host, a second action (`t` for transfer, alongside `enter`
  to shell in) opens an **in-app SFTP file browser** — not a shell-out to the
  system `sftp` binary.
- Built directly against a Go SFTP library (`pkg/sftp` + `golang.org/x/crypto/
  ssh` for the underlying connection) rather than shelling out, so dial owns
  the whole UI.
- **Core browser UX** (following the same static, high-contrast, low-light-
  friendly list styling as the host picker — no cramped/dense text):
  - Split view or toggle-view of local vs. remote directory listing.
  - Arrow-key navigation through directories on both sides; `enter` on a
    directory descends into it, a clear "up one level" entry at the top of
    each listing.
  - **Batch selection:** a keypress (e.g. `space`) toggles selection on the
    highlighted entry without moving the cursor, same pattern as v1's `f`
    favourite toggle. Multiple files (and/or directories) can be selected
    before triggering a push/pull.
  - Push (local → remote) or pull (remote → local) on the current selection —
    a single file, multiple files, a single directory, or a mix.
  - **Directory transfers are recursive**, walking the full tree on the
    source side and recreating structure on the destination side.
  - Progress UI: per-item progress plus an aggregate "3 of 12 files, 40% of
    total" view when a batch/directory transfer is in flight — legible at the
    same size/contrast as the rest of the UI.
  - Clear error states: connection drop mid-transfer, permission denied, disk
    full, file already exists (prompt overwrite/skip/rename rather than
    silently clobbering) — applies per-item within a batch, with an option to
    apply the same choice to all remaining conflicts rather than prompting
    per file.
- **Resume on failure: basic, same-session only.** If a transfer (or a batch/
  directory transfer) is interrupted — network drop, connection reset — and
  retried within the same `dial` session, dial seeks both the local and
  remote file to the last confirmed byte offset and continues rather than
  restarting from zero. This applies per-file within a batch/directory
  transfer (finished files stay finished; only the interrupted one resumes).
  - **Explicitly not included:** resume that survives closing/restarting
    `dial` or the machine. That requires persisting transfer state to disk and
    verifying partial files weren't corrupted before trusting them — a
    meaningfully bigger, separate piece of work. Flag if this turns out to
    matter in practice (e.g. regularly moving very large files where a lost
    session is costly) and it can be scoped as a v2.x follow-up.
- Reuses the connection details already resolved from `~/.ssh/config` for the
  selected host (same auth, same `ProxyJump` if present) — no separate
  credential entry.
- **Gate coverage:** as already decided in §3.4, the YubiKey gate (when
  enabled) covers entry into this mode too, not just app launch.

### 3.2 How to pick the action (shell vs SFTP) — **decided**
- Second keypress on the highlighted host, not a separate menu: `enter` = ssh,
  `t` = sftp. Keeps the static-list simplicity intact rather than adding a
  submenu/modal.

### 3.3 Distribution/trust (signing, Homebrew, Scoop, CI) — **deferred, not v2**
- This is packaging/ops work, not a feature, and doesn't block daily use on
  your own machines via Syncthing + manual install. Flagging as a separate
  future task rather than bundling into this feature-focused v2 pass.

### 3.4 Gate ergonomics — **small change: gate now also covers SFTP**
- Every-launch touch stays as-is (no idle-timeout added — the report notes
  this as a "worth adding later" maybe, not a v2 must-have).
  **Assumption flagged:** leaving idle-timeout out of v2; say the word if you
  want it added now instead.
- The YubiKey gate (when enabled) now also gates the new `t` (SFTP) action,
  not just app launch, since it's a second way to move data off/onto a host.

### 3.5 Recovery-code UX — **unchanged**
- Current design (terminal-only, shown once, single-use, auto-rotates) stays
  as-is. No changes requested and the report doesn't flag it as a problem.

### 3.6 Richer metadata (tag grouping/colour-coding) — **in scope, small**
- Add optional **section headers by tag** in the static list when sorted
  alphabetically or by tag (new sort mode candidate — see note below).
- Colour-code tag pills using the existing `internal/theme` high-contrast
  palette (e.g. a distinct colour per tag), not free-form colour — keeps the
  low-light-readable requirement intact.
- **Open question for you, not decided here:** should "group by tag" be its
  own 4th+ sort mode, or a toggle independent of sort? Recommend: independent
  toggle (`g` to group), since it's orthogonal to alphabetical/recent/most-used
  ordering. Flagging for Claude Code to confirm with you if ambiguous during
  build.

### 3.7 Search behaviour (fuzzy vs substring) — **kept as substring, not changed**
- Report explicitly chose substring to honour the "readable, not cramped"
  ethos. No reason surfaced in this conversation to revisit — leaving as-is
  for v2.

### 3.8 Multi-select / batch actions across hosts — **deferred, flagged as scope creep**
- Note: this is distinct from the batch *file* selection now included in the
  SFTP browser (§3.1), which is about selecting multiple files/folders within
  one host's transfer session. This item is about running a command or
  transfer across *multiple hosts* at once — the report itself raises this as
  possible scope creep. Recommend leaving it out of v2 — that's a meaningfully
  different tool shape (more like an orchestration tool than a picker) and
  deserves its own dedicated design pass if wanted later, not a bolt-on here.

### 3.9 Connection history/analytics beyond recents — **small addition**
- Add a **last-connected timestamp** shown in the preview pane (already
  tracking recency internally for sort — this just surfaces it visually).
- Per-host notes: **deferred** — no clear use case surfaced yet; easy to add
  later without restructuring anything, so not worth the effort now.

---

## v2 Scope Summary

**Building now:**
1. Alphabetical sort mode
2. `dial keygen` subcommand (cross-platform, ed25519-default, config-append)
3. In-app SFTP file browser (`t` to open, `pkg/sftp`-based — local/remote
   listings, batch file/folder selection, recursive directory transfers,
   same-session resume-on-failure, aggregate progress, overwrite prompts)
4. Tag grouping toggle + colour-coded tag pills
5. YubiKey gate extended to cover the new SFTP browser
6. Last-connected timestamp in preview pane

**Explicitly deferred (not this pass):**
- Resume that survives closing/restarting dial (crash-persistent resume)
- Idle-timeout gate option
- Distribution/signing/CI/package managers
- Multi-select/batch actions *across hosts* (§3.8) — distinct from in-browser
  batch file selection, which is now in scope
- Per-host notes
- Fuzzy search

---

## Notes for Claude Code
- The SFTP browser is a genuinely new subsystem (`internal/sftp` or similar),
  not a reuse of `internal/connect`'s exec-handover pattern — it needs its own
  connection lifecycle via `pkg/sftp`/`golang.org/x/crypto/ssh` since dial
  stays in the foreground driving the UI, rather than handing off the process
  like the SSH connect flow does.
- `dial keygen` is a new top-level subcommand alongside the existing
  `yubikey enable/disable/status/recovery`, `version`, `help` — not part of
  the TUI picker's keybindings.
- Confirm with the user during implementation: tag-grouping as toggle vs sort
  mode (§3.6), if it's not obvious once in the code.
- Given the SFTP browser is now the largest single piece of v2, worth
  sequencing it last (after alphabetical sort, keygen, tag grouping, last-
  connected timestamp) so the smaller wins land first and the browser gets
  full attention/testing time.