feat(cli): polish lifecycle UX and make ports/sync idempotent

Author: acmore

docs/command-reference.md

@@ -30,5 +30,9 @@
   - Maintains managed host alias in `~/.ssh/config` as `okdev-<session>`.
   - `--no-tmux`: bypass tmux for this SSH session when tmux mode is enabled.
 - `okdev ports`
+  - Advanced/recovery command. Rebuilds managed SSH `LocalForward` state from `spec.ports` after disconnects or local port changes.
+  - No-op when managed forwards are already healthy and config is unchanged.
 - `okdev sync [--mode up|down|bi] [--background] [--dry-run]`
+  - Advanced command. Use for foreground sync debugging, or explicit one-way sync (`up`/`down`).
+  - For default `--mode bi`, no-op when background sync is already active for the session.
 - `okdev prune [--ttl-hours 72] [--all-namespaces] [--all-users] [--include-pvc] [--dry-run]`

docs/quickstart.md

@@ -110,6 +110,17 @@ Notes:
 ./bin/okdev list --all-users
 ```
 
+## Advanced Recovery Commands
+
+```bash
+# Reconcile managed SSH LocalForward rules from spec.ports
+./bin/okdev ports
+
+# Run sync in foreground for troubleshooting or one-way flows
+./bin/okdev sync --mode up
+./bin/okdev sync --mode down
+```
+
 ## Teardown and Cleanup
 
 ```bash

internal/cli/down.go

@@ -6,6 +6,7 @@ import (
 	"path/filepath"
 	"strings"
 
+	"github.com/acmore/okdev/internal/config"
 	"github.com/acmore/okdev/internal/session"
 	"github.com/spf13/cobra"
 	apierrors "k8s.io/apimachinery/pkg/api/errors"
@@ -19,21 +20,31 @@ func newDownCmd(opts *Options) *cobra.Command {
 		Use:   "down",
 		Short: "Delete a dev session pod",
 		RunE: func(cmd *cobra.Command, args []string) error {
+			ui := newUpUI(cmd.OutOrStdout(), cmd.ErrOrStderr())
+			ui.section("Validate")
 			cfg, ns, err := loadConfigAndNamespace(opts)
 			if err != nil {
 				return err
 			}
+			cfgPath, pathErr := config.ResolvePath(opts.ConfigPath)
+			if pathErr == nil {
+				ui.stepDone("config", cfgPath)
+			}
 			sn, err := resolveSessionNameForUpDown(opts, cfg, ns)
 			if err != nil {
 				return err
 			}
+			ui.stepDone("session", sn)
+			ui.stepDone("namespace", ns)
 			k := newKubeClient(opts)
 			if err := ensureSessionOwnership(opts, k, ns, sn, false); err != nil {
 				return err
 			}
+			ui.stepDone("ownership", "ok")
 			ctx, cancel := defaultContext()
 			defer cancel()
 			if dryRun {
+				ui.section("Dry Run")
 				fmt.Fprintf(cmd.OutOrStdout(), "DRY RUN: session=%s namespace=%s\n", sn, ns)
 				fmt.Fprintf(cmd.OutOrStdout(), "- would delete pod/%s\n", podName(sn))
 				if deletePVC && cfg.Spec.Workspace.PVC.ClaimName == "" {
@@ -44,23 +55,48 @@ func newDownCmd(opts *Options) *cobra.Command {
 				return nil
 			}
 
+			ui.section("Delete")
+			ui.stepRun("pod", podName(sn))
 			if err := k.Delete(ctx, ns, "pod", podName(sn), true); err != nil && !apierrors.IsNotFound(err) {
 				return fmt.Errorf("delete session pod: %w", err)
 			}
+			ui.stepDone("pod", "deleted")
 			if deletePVC && cfg.Spec.Workspace.PVC.ClaimName == "" {
+				ui.stepRun("pvc", pvcName(cfg, sn))
 				if err := k.Delete(ctx, ns, "pvc", pvcName(cfg, sn), true); err != nil && !apierrors.IsNotFound(err) {
 					return fmt.Errorf("delete workspace pvc: %w", err)
 				}
+				ui.stepDone("pvc", "deleted")
+			} else if cfg.Spec.Workspace.PVC.ClaimName == "" {
+				ui.stepDone("pvc", "retained")
+			} else {
+				ui.stepDone("pvc", "external claim")
 			}
 			alias := sshHostAlias(sn)
+			ui.section("Cleanup")
 			_ = stopManagedSSHForward(alias)
-			_ = removeSSHConfigEntry(alias)
+			ui.stepDone("ssh forward", "stopped")
+			if err := removeSSHConfigEntry(alias); err != nil {
+				ui.warnf("failed to remove SSH config entry for %s: %v", alias, err)
+			} else {
+				ui.stepDone("ssh config", "cleaned")
+			}
 			if active, err := session.LoadActiveSession(); err == nil && active == sn {
 				_ = session.ClearActiveSession()
+				ui.stepDone("active session", "cleared")
 			}
-			fmt.Fprintf(cmd.OutOrStdout(), "Session stopped: %s\n", sn)
+			ui.printWarnings()
+			ui.section("Ready")
+			fmt.Fprintf(cmd.OutOrStdout(), "session:   %s\n", sn)
+			fmt.Fprintf(cmd.OutOrStdout(), "namespace: %s\n", ns)
+			fmt.Fprintln(cmd.OutOrStdout(), "status:    stopped")
 			if !deletePVC && cfg.Spec.Workspace.PVC.ClaimName == "" {
-				fmt.Fprintf(cmd.OutOrStdout(), "Workspace PVC retained: %s (use --delete-pvc to remove)\n", pvcName(cfg, sn))
+				fmt.Fprintf(cmd.OutOrStdout(), "workspace: retained (%s)\n", pvcName(cfg, sn))
+				fmt.Fprintln(cmd.OutOrStdout(), "note:      use --delete-pvc to remove workspace storage")
+			} else if deletePVC && cfg.Spec.Workspace.PVC.ClaimName == "" {
+				fmt.Fprintln(cmd.OutOrStdout(), "workspace: deleted")
+			} else {
+				fmt.Fprintf(cmd.OutOrStdout(), "workspace: external claim (%s)\n", cfg.Spec.Workspace.PVC.ClaimName)
 			}
 			return nil
 		},

internal/cli/ports.go

@@ -2,25 +2,27 @@ package cli
 
 import (
 	"fmt"
-	"log/slog"
-	"os"
-	"strconv"
+	"strings"
 	"time"
 
-	portsrunner "github.com/acmore/okdev/internal/ports"
+	"github.com/acmore/okdev/internal/config"
 	"github.com/spf13/cobra"
 )
 
 func newPortsCmd(opts *Options) *cobra.Command {
 	return &cobra.Command{
 		Use:   "ports",
-		Short: "Start port-forwarding for configured ports",
+		Short: "Reconcile managed SSH port forwards for configured ports",
 		RunE: func(cmd *cobra.Command, args []string) error {
 			cfg, ns, err := loadConfigAndNamespace(opts)
 			if err != nil {
 				return err
 			}
-			sn, err := resolveSessionName(opts, cfg)
+			cfgPath, err := config.ResolvePath(opts.ConfigPath)
+			if err != nil {
+				return err
+			}
+			sn, err := resolveSessionNameForUpDown(opts, cfg, ns)
 			if err != nil {
 				return err
 			}
@@ -33,23 +35,52 @@ func newPortsCmd(opts *Options) *cobra.Command {
 			if len(cfg.Spec.Ports) == 0 {
 				return fmt.Errorf("no ports configured in config")
 			}
-
-			forwards := make([]string, 0, len(cfg.Spec.Ports))
+			validForwards := make([]string, 0, len(cfg.Spec.Ports))
 			for _, p := range cfg.Spec.Ports {
 				if p.Local <= 0 || p.Remote <= 0 {
 					continue
 				}
-				forwards = append(forwards, strconv.Itoa(p.Local)+":"+strconv.Itoa(p.Remote))
+				validForwards = append(validForwards, fmt.Sprintf("%d:%d", p.Local, p.Remote))
 			}
-			if len(forwards) == 0 {
+			if len(validForwards) == 0 {
 				return fmt.Errorf("no valid ports configured")
 			}
 
-			ctx, cancel := interactiveContext()
-			defer cancel()
-			fmt.Fprintf(cmd.OutOrStdout(), "Forwarding %v from session %s\n", forwards, sn)
-			slog.Debug("ports start", "namespace", ns, "session", sn, "forwards", forwards)
-			return portsrunner.ForwardWithRetry(ctx, k, ns, podName(sn), forwards, os.Stdout, cmd.ErrOrStderr(), 30*time.Second)
+			keyPath, err := defaultSSHKeyPath(cfg)
+			if err != nil {
+				return fmt.Errorf("resolve SSH key path: %w", err)
+			}
+			if err := ensureSSHKeyOnPod(opts, cfg, ns, podName(sn), keyPath); err != nil {
+				return fmt.Errorf("setup SSH key in pod: %w", err)
+			}
+			if err := waitForSSHDReady(opts, cfg, ns, podName(sn), 20*time.Second); err != nil {
+				return fmt.Errorf("wait for sshd ready: %w", err)
+			}
+			alias := sshHostAlias(sn)
+			changed, err := ensureSSHConfigEntry(alias, sn, ns, cfg.Spec.SSH.User, cfg.Spec.SSH.RemotePort, keyPath, cfgPath, cfg.Spec.Ports)
+			if err != nil {
+				return fmt.Errorf("update ~/.ssh/config for managed forwards: %w", err)
+			}
+			running, runErr := isManagedSSHForwardRunning(alias)
+			if runErr != nil {
+				return fmt.Errorf("check managed SSH forward state: %w", runErr)
+			}
+			if running && !changed {
+				fmt.Fprintf(cmd.OutOrStdout(), "Managed forwards already active for %s: %s\n", alias, strings.Join(validForwards, ", "))
+				return nil
+			}
+			if running {
+				_ = stopManagedSSHForward(alias)
+			}
+			if err := startManagedSSHForward(alias); err != nil {
+				return fmt.Errorf("start managed SSH forwards: %w", err)
+			}
+			if changed {
+				fmt.Fprintf(cmd.OutOrStdout(), "Managed forwards updated for %s: %s\n", alias, strings.Join(validForwards, ", "))
+			} else {
+				fmt.Fprintf(cmd.OutOrStdout(), "Managed forwards started for %s: %s\n", alias, strings.Join(validForwards, ", "))
+			}
+			return nil
 		},
 	}
 }

internal/cli/ssh.go

@@ -90,7 +90,7 @@ func newSSHCmd(opts *Options) *cobra.Command {
 
 			sshHost := sshHostAlias(sn)
 			cfgPath, _ := config.ResolvePath(opts.ConfigPath)
-			if cfgErr := ensureSSHConfigEntry(sshHost, sn, ns, user, remotePort, keyPath, cfgPath, cfg.Spec.Ports); cfgErr != nil {
+			if _, cfgErr := ensureSSHConfigEntry(sshHost, sn, ns, user, remotePort, keyPath, cfgPath, cfg.Spec.Ports); cfgErr != nil {
 				fmt.Fprintf(cmd.ErrOrStderr(), "warning: failed to update ~/.ssh/config: %v\n", cfgErr)
 			}
 
@@ -313,14 +313,14 @@ func sshHostAlias(sessionName string) string {
 	return "okdev-" + sessionName
 }
 
-func ensureSSHConfigEntry(hostAlias, sessionName, namespace, user string, remotePort int, keyPath, okdevConfigPath string, forwards []config.PortMapping) error {
+func ensureSSHConfigEntry(hostAlias, sessionName, namespace, user string, remotePort int, keyPath, okdevConfigPath string, forwards []config.PortMapping) (bool, error) {
 	home, err := os.UserHomeDir()
 	if err != nil {
-		return err
+		return false, err
 	}
 	sshDir := filepath.Join(home, ".ssh")
 	if err := os.MkdirAll(sshDir, 0o700); err != nil {
-		return err
+		return false, err
 	}
 	sshConfigPath := filepath.Join(sshDir, "config")
 	begin := "# BEGIN OKDEV " + hostAlias
@@ -355,10 +355,41 @@ func ensureSSHConfigEntry(hostAlias, sessionName, namespace, user string, remote
 		end,
 	)
 	block := strings.Join(blockLines, "\n") + "\n"
-	return updateSSHConfigWithLock(sshConfigPath, func(existing string) string {
-		updated := stripManagedSSHBlock(existing, begin, end) + "\n" + block
-		return strings.TrimSpace(updated) + "\n"
-	})
+	lockPath := sshConfigPath + ".okdev.lock"
+	lockFile, err := os.OpenFile(lockPath, os.O_CREATE|os.O_RDWR, 0o600)
+	if err != nil {
+		return false, err
+	}
+	defer lockFile.Close()
+	if err := syscall.Flock(int(lockFile.Fd()), syscall.LOCK_EX); err != nil {
+		return false, err
+	}
+	defer func() {
+		_ = syscall.Flock(int(lockFile.Fd()), syscall.LOCK_UN)
+	}()
+
+	existingBytes, _ := os.ReadFile(sshConfigPath)
+	existing := string(existingBytes)
+	updated := strings.TrimSpace(stripManagedSSHBlock(existing, begin, end)+"\n"+block) + "\n"
+	if updated == existing {
+		return false, nil
+	}
+	if err := os.WriteFile(sshConfigPath, []byte(updated), 0o600); err != nil {
+		return false, err
+	}
+	return true, nil
+}
+
+func isManagedSSHForwardRunning(hostAlias string) (bool, error) {
+	socketPath, err := sshControlSocketPath(hostAlias)
+	if err != nil {
+		return false, err
+	}
+	check := exec.Command("ssh", "-S", socketPath, "-O", "check", hostAlias)
+	if err := check.Run(); err == nil {
+		return true, nil
+	}
+	return false, nil
 }
 
 func stripManagedSSHBlock(content, begin, end string) string {

internal/cli/ssh_config_test.go

@@ -19,7 +19,7 @@ func TestEnsureSSHConfigEntryIncludesNamespaceInProxyCommand(t *testing.T) {
 		_ = os.Setenv("HOME", origHome)
 	}()
 
-	err := ensureSSHConfigEntry(
+	_, err := ensureSSHConfigEntry(
 		"okdev-test",
 		"test-session",
 		"dev-ns",

internal/cli/sync.go

@@ -10,6 +10,7 @@ import (
 	"syscall"
 	"time"
 
+	"github.com/acmore/okdev/internal/config"
 	syncengine "github.com/acmore/okdev/internal/sync"
 	"github.com/spf13/cobra"
 )
@@ -27,7 +28,11 @@ func newSyncCmd(opts *Options) *cobra.Command {
 			if err != nil {
 				return err
 			}
-			sn, err := resolveSessionName(opts, cfg)
+			cfgPath, err := config.ResolvePath(opts.ConfigPath)
+			if err != nil {
+				return err
+			}
+			sn, err := resolveSessionNameForUpDown(opts, cfg, ns)
 			if err != nil {
 				return err
 			}
@@ -57,8 +62,17 @@ func newSyncCmd(opts *Options) *cobra.Command {
 			stopMaintenance := startSessionMaintenance(opts, cfg, ns, sn, cmd.OutOrStdout(), false, true)
 			defer stopMaintenance()
 
+			if !background && mode == "bi" && os.Getenv("OKDEV_SYNCTHING_BACKGROUND_CHILD") != "1" {
+				if pidPath, err := syncthingPIDPath(sn); err == nil {
+					if pid, ok := readSyncthingPID(pidPath); ok && processAlive(pid) && processLooksLikeSyncthingSync(pid) {
+						fmt.Fprintf(cmd.OutOrStdout(), "Syncthing sync already active in background for session %s\n", sn)
+						return nil
+					}
+				}
+			}
+
 			if background && os.Getenv("OKDEV_SYNCTHING_BACKGROUND_CHILD") != "1" {
-				logPath, started, err := startDetachedSyncthingSync(opts, mode, sn)
+				logPath, started, err := startDetachedSyncthingSync(opts, mode, sn, ns, cfgPath)
 				if err != nil {
 					return err
 				}
@@ -80,7 +94,7 @@ func newSyncCmd(opts *Options) *cobra.Command {
 	return cmd
 }
 
-func startDetachedSyncthingSync(opts *Options, mode, sessionName string) (string, bool, error) {
+func startDetachedSyncthingSync(opts *Options, mode, sessionName, namespace, cfgPath string) (string, bool, error) {
 	exe, err := os.Executable()
 	if err != nil {
 		return "", false, err
@@ -110,14 +124,14 @@ func startDetachedSyncthingSync(opts *Options, mode, sessionName string) (string
 	}
 
 	args := make([]string, 0, 16)
-	if opts.ConfigPath != "" {
-		args = append(args, "--config", opts.ConfigPath)
+	if cfgPath != "" {
+		args = append(args, "--config", cfgPath)
 	}
-	if opts.Session != "" {
-		args = append(args, "--session", opts.Session)
+	if sessionName != "" {
+		args = append(args, "--session", sessionName)
 	}
-	if opts.Namespace != "" {
-		args = append(args, "--namespace", opts.Namespace)
+	if namespace != "" {
+		args = append(args, "--namespace", namespace)
 	}
 	if opts.Context != "" {
 		args = append(args, "--context", opts.Context)