feat(scripts): remote devcontainer orchestration via just recipe (#70)

[gerchowl]

Description

Implements remote devcontainer orchestration: a single command (just remote-devc <host> or devc-remote.sh) that provisions a devcontainer on a remote host and connects your IDE to it. This enables developers to spin up devcontainers on powerful remote machines (GPU servers, cloud VMs) from their local terminal without manual SSH and compose steps.

Key capabilities

• Core orchestration — SSH preflight, container state detection (fresh/running/stopped), compose lifecycle, IDE launch
• gh:org/repo[:branch] targets — Clone a GitHub repo on the remote host and start its devcontainer in one command
• --bootstrap flag — One-time remote host setup (config file, GHCR auth, image build)
• --force flag — Auto-push unpushed commits before deploying; guards against deploying stale code
• --open ssh|cursor|code|none — IDE-agnostic connection modes with auto-detection
• Tailscale SSH integration — Ephemeral auth key generation via OAuth API, TUN device injection, peer wait polling
• Claude Code CLI injection — Subscription OAuth token forwarding for AI-assisted development in containers
• Container lifecycle execution — Runs post-create/post-start scripts inside the container after compose up
• Compose file parsing — Reads dockerComposeFile from devcontainer.json, builds correct -f flags

Implementation

Component	Purpose
scripts/devc-remote.sh	Bash orchestrator: parse_args, check_ssh, remote_preflight, inject_tailscale_key, inject_claude_auth, remote_compose_up, run_container_lifecycle, open_editor
scripts/devc_remote_uri.py	Python helper for Cursor/VS Code nested authority URIs (hex-encoded devcontainer specs)
justfile.base	remote-devc recipe wrapping devc-remote.sh with local git state auto-detection
setup-tailscale.sh	Opt-in Tailscale SSH daemon (install/start subcommands, lifecycle hooks)
setup-claude.sh	Opt-in Claude Code CLI (install/start subcommands, lifecycle hooks)

Type of Change

• feat -- New feature

Issues

Closes #152, #153, #221, #230, #231, #232, #235, #236, #243
Refs: #70, #208, #246

Testing

• Unit tests pass locally (just test)
• Manual integration testing on real remote host (ksb-meatgrinder, chore: manual integration tests for remote devcontainer features #243)

Manual Integration Test Results (#243)

36/39 items verified on a real remote host. Remaining 3 edge cases (low disk, missing compose, missing runtime) covered by unit tests.

Full test matrix (click to expand)

1. Core orchestration

• devc-remote.sh myserver:~/Projects/fd5 — SSH, preflight, compose up
• Re-run with container already running — skips compose up, opens editor
• Re-run with container stopped — restarts and opens
• --open none — infra only, no IDE launch
• --open ssh — waits for Tailscale, prints hostname
• --open code — opens VS Code instead of Cursor
• --yes flag — auto-accepts prompts (reuse running container)

2. Tailscale SSH integration (#208, #230)

• With TS_CLIENT_ID + TS_CLIENT_SECRET set — generates ephemeral key, injects into remote compose
• Container joins tailnet after compose up
• --open ssh mode — polls tailscale status, prints hostname when ready
• Without TS env vars — silently skips (no error)

3. Claude Code CLI (#70)

• With CLAUDE_CODE_OAUTH_TOKEN set — injects token into remote compose
• setup-claude.sh install inside container — installs CLI, creates claude user
• claude wrapper auto-switches to non-root user when run as root
• setup-claude.sh start — refreshes workspace permissions
• Without token — silently skips (no error)

4. Container lifecycle

• Fresh container — runs post-create.sh then post-start.sh inside container
• Existing running container — runs only post-start.sh (skips post-create)
• Lifecycle scripts not present — skips gracefully with log message

5. --bootstrap (#235)

• First run on clean host — prompts for projects_dir, creates config, forwards GHCR auth, clones devcontainer repo, builds image
• --bootstrap --yes — uses defaults without prompting
• Re-run — reads existing config, skips prompts, pulls latest, rebuilds
• GHCR auth forwarding — podman credentials or GHCR_TOKEN copied to remote

6. gh:org/repo[:branch] (#236)

• devc-remote.sh myserver gh:vig-os/fd5 — clones to ~/Projects/fd5, starts devcontainer
• devc-remote.sh myserver gh:vig-os/fd5:feature/my-branch — clones and checks out branch
• Re-run with repo already cloned — fetches, doesn't re-clone
• devc-remote.sh myserver:~/custom/path gh:vig-os/fd5 — overrides clone location
• Branch switch on existing clone — checks out new branch

7. Compose file parsing

• read_compose_files() correctly reads dockerComposeFile array from devcontainer.json
• compose_cmd_with_files() builds correct -f flags
• Works with single file string and multi-file array

8. Edge cases

• Low disk space warning (<2GB) — requires special host (covered by unit test)
• Remote host without compose — requires special host (covered by unit test)
• Remote host without container runtime — requires special host (covered by unit test)
• SSH connection failure — clear error message
• macOS remote host — not tested (covered by unit test)

Bugs found and fixed during testing

• SSH drops empty args / expands ~ in remote_clone_project — fixed with sentinel values (17ca79f)
• GHCR auth forwarding moved from bootstrap-only to every deploy (9280224)
• Tailscale SSH required real TUN device, not userspace networking (c209f1d)
• Tailscale key regenerated on every deploy to avoid expired ephemeral keys (0b0bcef)
• ~/.local/bin added to PATH for SSH compose commands (15120fb)
• Reverted unnecessary podman-compose preference logic (ea3af49)
• Pre-flight check for stale local Tailscale daemon (49c7a4e)

Changelog Entry

See CHANGELOG.md ## Unreleased section — fully up to date.

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my code
• I have updated the documentation accordingly
• I have updated CHANGELOG.md in the [Unreleased] section
• My changes generate no new warnings or errors
• I have added tests that prove my feature works
• New and existing unit tests pass locally with my changes
• Manual integration tests pass (chore: manual integration tests for remote devcontainer features #243)