Merge pull request #2 from Benjamin-Connelly/feat/ssh-remote

feat: SSH remote file browsing

Author: Benjamin-Connelly

CLAUDE.md

@@ -47,6 +47,10 @@ internal/
   git/
     git.go                      # go-git: repo, status, branches, log, remotes
     permalink.go                # URL generation (GitHub/GitLab/Bitbucket/Gitea/Codeberg)
+  remote/
+    remote.go                   # SCP-style path parsing, Target type
+    conn.go                     # SSH connection (ssh-agent, key files, ~/.ssh/config)
+    sync.go                     # SFTP sync/cache with periodic polling
   export/export.go              # Markdown → HTML with Chroma highlighting
   doctor/doctor.go              # 8 environment checks with colored output
   plugin/plugin.go              # YAML hook system (prepend/append/replace)
@@ -84,6 +88,12 @@ go build -o lookit ./cmd/lookit
 ./lookit serve [path]
 ./lookit serve --port 3000 --open
 
+# Remote browsing (SSH)
+./lookit myhost:/path/to/docs       # SCP-style remote path
+./lookit user@host:/path            # with explicit user
+./lookit --remote myhost /path      # flag-style alternative
+./lookit @docs                      # named remote from config
+
 # Utilities
 ./lookit cat README.md              # render markdown to terminal
 ./lookit export --format html       # export markdown to HTML
@@ -117,3 +127,6 @@ GOOS=darwin GOARCH=arm64 go build -o lookit-darwin-arm64 ./cmd/lookit
 - Permalink generation detects forge style from remote URL (GitHub/GitLab/Bitbucket/Gitea/Codeberg).
 - Plugin hooks loaded from `~/.config/lookit/plugins/*.yaml`.
 - Task extraction recognizes `!high`/`!medium`/`!low` priority, `#tag`, `@due(YYYY-MM-DD)`.
+- Remote mode caches files to `~/.cache/lookit/remote/<hash>/`. Git features disabled for remote.
+- SSH auth: ssh-agent → key files → ~/.ssh/config. TOFU for unknown host keys.
+- Remote polling interval: 15 seconds. No real-time change notification (SFTP limitation).

README.md

@@ -26,6 +26,7 @@ Requires Go 1.24+. Pure Go, no CGO — cross-compiles to linux/darwin on amd64/a
 ```bash
 lookit                          # TUI mode — browse current directory
 lookit ~/docs                   # TUI mode — browse specific directory
+lookit myhost:~/docs            # SSH remote — browse files on a remote host
 lookit serve                    # Web mode — localhost:7777
 lookit serve --port 3000 --open # Web mode — custom port, auto-open browser
 lookit cat README.md            # Render markdown to terminal
@@ -38,6 +39,7 @@ lookit doctor                   # Environment diagnostics
 | Feature | `glow` | `mdcat` | `frogmouth` | **lookit** |
 |---------|:------:|:-------:|:-----------:|:----------:|
 | TUI file browser | Stash only | No | Single-pane | **Split-pane tree + preview** |
+| SSH remote browsing | No | No | No | **`host:/path` — browse remote docs** |
 | Full-text search | No | No | No | **Bleve BM25 index** |
 | Inter-document links | No | No | No | **History, backlinks, `[[wikilinks]]`** |
 | Broken link detection | No | No | No | **Files + `#heading` anchors** |
@@ -92,6 +94,32 @@ Lightweight HTTP server with live reload.
 - **Security headers** — CSP, X-Frame-Options, Referrer-Policy, Permissions-Policy
 - **ETag caching** — MD5-based for HTML, size+mtime for static
 
+### SSH Remote Browsing
+
+Browse files on remote hosts over SSH — no installation required on the remote machine.
+
+```bash
+lookit myhost:~/docs                # SSH config alias with ~ expansion
+lookit user@192.168.1.50:/var/docs  # Explicit user and IP
+lookit --remote myhost ~/docs       # Flag-style alternative
+lookit @docs                        # Named remote from config
+```
+
+- **Zero remote setup** — uses SFTP, nothing to install on the server
+- **SSH config support** — respects `~/.ssh/config` (Host aliases, Hostname, User, Port, IdentityFile)
+- **Auth chain** — ssh-agent → key files → SSH config (TOFU for unknown host keys)
+- **Sync/cache model** — files cached locally at `~/.cache/lookit/remote/`, polled every 15s for changes
+- **Status bar** — shows connection state (Connected/Reconnecting/Disconnected) and last sync time
+- **Auto-reconnect** — exponential backoff on connection loss
+- **Named remotes** — configure aliases in `config.yaml`:
+  ```yaml
+  remotes:
+    docs:
+      host: myserver
+      user: deploy
+      path: /home/deploy/docs
+  ```
+
 ### Shared
 
 - **Full-text search** — Bleve persistent index with BM25 scoring, field boosting, and highlighted snippets
@@ -185,6 +213,10 @@ Lightweight HTTP server with live reload.
 
 ```
 lookit [path]                    # TUI mode (default)
+lookit host:/path                # SSH remote (SCP-style)
+lookit @alias                    # Named remote from config
+  --remote <host>                # Remote host (SSH config alias or user@host)
+  --remote-port <port>           # Remote SSH port
   --keymap vim|emacs|default     # Keybinding preset
   --theme dark|light|auto|ascii  # Color theme
   --no-color                     # Alias for --theme ascii
@@ -231,6 +263,12 @@ git:
 ignore:
   - "*.tmp"
   - "vendor/"
+
+remotes:                # Named remote hosts for SSH browsing
+  docs:
+    host: myserver      # SSH config alias or hostname
+    user: deploy        # SSH user (optional)
+    path: /home/deploy/docs
 ```
 
 **Per-project config:** Place `.lookit.toml` or `.lookit.yaml` in your project root. Lookit walks up from the current directory and merges the first one found over the global config.
@@ -298,6 +336,12 @@ Lookit exists because generous people write extraordinary software and give it a
 - [D3.js](https://d3js.org) — the gold standard for data visualization on the web
 - [Mermaid](https://mermaid.js.org) — diagrams from text, rendered beautifully in the browser
 
+**SSH & Networking**
+- [x/crypto/ssh](https://pkg.go.dev/golang.org/x/crypto/ssh) — pure Go SSH client from the Go team
+- [sftp](https://github.com/pkg/sftp) — SFTP client that makes remote file access feel local
+- [ssh_config](https://github.com/kevinburke/ssh_config) — OpenSSH config parser (maintained by Tailscale)
+- [knownhosts](https://github.com/skeema/knownhosts) — SSH host key verification with known_hosts support
+
 **Utilities**
 - [clipboard](https://github.com/atotto/clipboard) — cross-platform clipboard access
 - [fsnotify](https://github.com/fsnotify/fsnotify) — cross-platform file system notifications

cmd/lookit/main.go

@@ -7,6 +7,7 @@ import (
 	"os"
 	"path/filepath"
 	"strings"
+	"time"
 
 	tea "github.com/charmbracelet/bubbletea"
 	"github.com/spf13/cobra"
@@ -17,6 +18,7 @@ import (
 	"github.com/Benjamin-Connelly/lookit/internal/doctor"
 	"github.com/Benjamin-Connelly/lookit/internal/export"
 	"github.com/Benjamin-Connelly/lookit/internal/index"
+	"github.com/Benjamin-Connelly/lookit/internal/remote"
 	"github.com/Benjamin-Connelly/lookit/internal/render"
 	"github.com/Benjamin-Connelly/lookit/internal/tui"
 	"github.com/Benjamin-Connelly/lookit/internal/web"
@@ -32,7 +34,12 @@ var rootCmd = &cobra.Command{
 	Version: version,
 	Long: `Lookit is a dual-mode markdown navigator that provides both TUI and web
 interfaces for browsing code, markdown, and files. Features inter-document
-link navigation with history, backlinks, and broken link detection.`,
+link navigation with history, backlinks, and broken link detection.
+
+Supports browsing remote files over SSH:
+  lookit myhost:/path/to/docs
+  lookit user@host:/path
+  lookit --remote myhost /path`,
 	Args:              cobra.MaximumNArgs(1),
 	PersistentPreRunE: loadConfig,
 	RunE: func(cmd *cobra.Command, args []string) error {
@@ -57,6 +64,23 @@ link navigation with history, backlinks, and broken link detection.`,
 			return nil
 		}
 
+		// Check for remote path (host:/path syntax or --remote flag)
+		if remoteHost, _ := cmd.Flags().GetString("remote"); remoteHost != "" {
+			remotePath := "."
+			if len(args) > 0 {
+				remotePath = args[0]
+			}
+			remotePort, _ := cmd.Flags().GetInt("remote-port")
+			target := &remote.Target{Host: remoteHost, Path: remotePath, Port: remotePort}
+			return runRemote(target)
+		}
+		if len(args) > 0 {
+			target := resolveRemoteTarget(args[0])
+			if target != nil {
+				return runRemote(target)
+			}
+		}
+
 		root, err := resolveRoot(args)
 		if err != nil {
 			return err
@@ -476,6 +500,8 @@ func init() {
 	rootCmd.PersistentFlags().Bool("no-color", false, "disable colors (ascii theme)")
 
 	rootCmd.Flags().String("keymap", "", "keybinding preset (default|vim|emacs)")
+	rootCmd.Flags().String("remote", "", "remote host (SSH config alias or user@host)")
+	rootCmd.Flags().Int("remote-port", 0, "remote SSH port (default: from ssh config or 22)")
 
 	serveCmd.Flags().IntP("port", "p", 0, "server port")
 	serveCmd.Flags().Bool("open", false, "open browser after starting")
@@ -557,6 +583,146 @@ func resolveRoot(args []string) (string, error) {
 	return absRoot, nil
 }
 
+// resolveRemoteTarget checks if the arg is a remote path spec or a named
+// remote from config. Returns nil if the arg is a local path.
+func resolveRemoteTarget(arg string) *remote.Target {
+	// Try SCP-style parsing first (host:/path)
+	if target := remote.ParseTarget(arg); target != nil {
+		return target
+	}
+
+	// Check named remotes in config (e.g. @docs)
+	if strings.HasPrefix(arg, "@") && cfg.Remotes != nil {
+		name := arg[1:]
+		if rc, ok := cfg.Remotes[name]; ok {
+			return &remote.Target{
+				Host: rc.Host,
+				User: rc.User,
+				Port: rc.Port,
+				Path: rc.Path,
+			}
+		}
+	}
+
+	return nil
+}
+
+// runRemote handles the full lifecycle of browsing a remote host.
+func runRemote(target *remote.Target) error {
+	// Check minimum terminal size
+	if w, h, err := term.GetSize(int(os.Stdout.Fd())); err == nil {
+		if w < 80 || h < 24 {
+			return fmt.Errorf("terminal too small (%dx%d). Lookit requires at least 80x24", w, h)
+		}
+	}
+
+	fmt.Fprintf(os.Stderr, "Connecting to %s...\n", target.Display())
+
+	// Establish SSH connection
+	conn := remote.NewConn(*target)
+	if err := conn.Connect(); err != nil {
+		return fmt.Errorf("connecting to %s: %w", target.Display(), err)
+	}
+	defer conn.Close()
+
+	// Use the resolved target (~ expanded, relative paths resolved)
+	resolved := conn.Target()
+
+	fmt.Fprintf(os.Stderr, "Connected to %s. Syncing files...\n", resolved.Display())
+
+	// Set up local cache
+	cacheDir, err := remote.CachePath(resolved)
+	if err != nil {
+		return fmt.Errorf("cache path: %w", err)
+	}
+
+	// Sync remote files to local cache
+	syncer := remote.NewSyncer(conn, cacheDir)
+	if err := syncer.InitialSync(); err != nil {
+		return fmt.Errorf("initial sync from %s: %w", resolved.Display(), err)
+	}
+
+	fmt.Fprintf(os.Stderr, "Sync complete. Starting TUI...\n")
+
+	// Build index from cached files
+	idx := index.New(syncer.CacheDir())
+	if err := idx.Build(); err != nil {
+		return fmt.Errorf("building index: %w", err)
+	}
+
+	// Build fulltext search index
+	fulltextDir, _ := os.UserCacheDir()
+	if fulltextDir != "" {
+		fulltextDir = filepath.Join(fulltextDir, "lookit")
+	}
+	if err := idx.BuildFulltext(fulltextDir); err != nil {
+		fmt.Fprintf(os.Stderr, "warning: fulltext index unavailable: %v\n", err)
+	}
+	defer idx.CloseFulltext()
+
+	links := index.NewLinkGraph()
+	links.BuildFromIndex(idx)
+
+	// Set up file watcher on local cache (catches sync updates)
+	watcher, err := index.NewWatcher(idx, links, nil)
+	if err != nil {
+		return fmt.Errorf("starting watcher: %w", err)
+	}
+	defer watcher.Close()
+	if err := watcher.Start(); err != nil {
+		return fmt.Errorf("watching files: %w", err)
+	}
+
+	// Start background polling for remote changes
+	syncer.SetOnChange(func() {
+		// Watcher will pick up changes via fsnotify on the cache dir
+	})
+	syncer.StartPolling()
+	defer syncer.Stop()
+
+	// Create TUI with remote info
+	model := tui.New(cfg, idx, links)
+	model.SetRemoteInfo(&tui.RemoteInfo{
+		Display: resolved.Display(),
+		State:   conn.State().String(),
+	})
+
+	// Start a goroutine to update remote status periodically
+	done := make(chan struct{})
+	defer close(done)
+	go func() {
+		ticker := time.NewTicker(1 * time.Second)
+		defer ticker.Stop()
+		for {
+			select {
+			case <-ticker.C:
+				status := syncer.Status()
+				elapsed := time.Since(status.LastSync).Truncate(time.Second)
+				syncText := ""
+				switch status.State {
+				case remote.SyncRunning:
+					syncText = "syncing..."
+				default:
+					if !status.LastSync.IsZero() {
+						syncText = fmt.Sprintf("synced %s ago", elapsed)
+					}
+				}
+				model.SetRemoteInfo(&tui.RemoteInfo{
+					Display:  resolved.Display(),
+					State:    conn.State().String(),
+					LastSync: syncText,
+				})
+			case <-done:
+				return
+			}
+		}
+	}()
+
+	p := tea.NewProgram(model, tea.WithAltScreen())
+	_, err = p.Run()
+	return err
+}
+
 func main() {
 	if err := rootCmd.Execute(); err != nil {
 		os.Exit(1)

go.mod

@@ -18,6 +18,7 @@ require (
 	github.com/yuin/goldmark v1.7.8
 	github.com/yuin/goldmark-emoji v1.0.5
 	go.yaml.in/yaml/v3 v3.0.4
+	golang.org/x/crypto v0.45.0
 	golang.org/x/term v0.37.0
 )
 
@@ -69,7 +70,8 @@ require (
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/jbenet/go-context v0.0.0-20150711004518-d14ea06fba99 // indirect
 	github.com/json-iterator/go v0.0.0-20171115153421-f7279a603ede // indirect
-	github.com/kevinburke/ssh_config v1.2.0 // indirect
+	github.com/kevinburke/ssh_config v1.2.0
+	github.com/kr/fs v0.1.0 // indirect
 	github.com/lucasb-eyer/go-colorful v1.3.0 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/mattn/go-localereader v0.0.1 // indirect
@@ -82,11 +84,12 @@ require (
 	github.com/muesli/termenv v0.16.0 // indirect
 	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
 	github.com/pjbgf/sha1cd v0.3.2 // indirect
+	github.com/pkg/sftp v1.13.10
 	github.com/rivo/uniseg v0.4.7 // indirect
 	github.com/russross/blackfriday/v2 v2.1.0 // indirect
 	github.com/sagikazarmark/locafero v0.11.0 // indirect
 	github.com/sergi/go-diff v1.3.2-0.20230802210424-5b0b94c5c0d3 // indirect
-	github.com/skeema/knownhosts v1.3.1 // indirect
+	github.com/skeema/knownhosts v1.3.1
 	github.com/sourcegraph/conc v0.3.1-0.20240121214520-5f936abd7ae8 // indirect
 	github.com/spf13/afero v1.15.0 // indirect
 	github.com/spf13/cast v1.10.0 // indirect
@@ -95,7 +98,6 @@ require (
 	github.com/xanzy/ssh-agent v0.3.3 // indirect
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
 	go.etcd.io/bbolt v1.4.0 // indirect
-	golang.org/x/crypto v0.45.0 // indirect
 	golang.org/x/net v0.47.0 // indirect
 	golang.org/x/sys v0.38.0 // indirect
 	golang.org/x/text v0.31.0 // indirect

go.sum

@@ -145,6 +145,8 @@ github.com/json-iterator/go v0.0.0-20171115153421-f7279a603ede h1:YrgBGwxMRK0Vq0
 github.com/json-iterator/go v0.0.0-20171115153421-f7279a603ede/go.mod h1:+SdeFBvtyEkXs7REEP0seUULqWtbJapLOCVDaaPEHmU=
 github.com/kevinburke/ssh_config v1.2.0 h1:x584FjTGwHzMwvHx18PXxbBVzfnxogHaAReU4gf13a4=
 github.com/kevinburke/ssh_config v1.2.0/go.mod h1:CT57kijsi8u/K/BOFA39wgDQJ9CxiF4nAY/ojJ6r6mM=
+github.com/kr/fs v0.1.0 h1:Jskdu9ieNAYnjxsi0LbQp1ulIKZV1LAFgK1tWhpZgl8=
+github.com/kr/fs v0.1.0/go.mod h1:FFnZGqtBN9Gxj7eW1uZ42v5BccTP0vu6NEaFoC2HwRg=
 github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
 github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
 github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
@@ -183,6 +185,8 @@ github.com/pjbgf/sha1cd v0.3.2 h1:a9wb0bp1oC2TGwStyn0Umc/IGKQnEgF0vVaZ8QF8eo4=
 github.com/pjbgf/sha1cd v0.3.2/go.mod h1:zQWigSxVmsHEZow5qaLtPYxpcKMMQpa09ixqBxuCS6A=
 github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
 github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
+github.com/pkg/sftp v1.13.10 h1:+5FbKNTe5Z9aspU88DPIKJ9z2KZoaGCu6Sr6kKR/5mU=
+github.com/pkg/sftp v1.13.10/go.mod h1:bJ1a7uDhrX/4OII+agvy28lzRvQrmIQuaHrcI1HbeGA=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/rivo/uniseg v0.1.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=