luv-cli 0.3.0__tar.gz → 0.5.0__tar.gz

{luv_cli-0.3.0 → luv_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: luv-cli
-Version: 0.3.0
+Version: 0.5.0
 Summary: Launch Claude Code or Codex agents on GitHub repos with isolated workspaces and optional Docker dev environments
 Project-URL: Homepage, https://github.com/exospherehost/luv
 Project-URL: Repository, https://github.com/exospherehost/luv
@@ -63,7 +63,7 @@ luv other-org/my-repo "fix the bug"
 # Reopen workspace #42
 luv my-repo 42
 
-# Open any GitHub PR by URL
+# Clone any GitHub PR by URL into a fresh workspace
 luv -l https://github.com/org/repo/pull/123
 
 # Open a shell instead of Claude
@@ -97,6 +97,22 @@ The machine name is what keeps two computers apart. Each one works out the next
 
 With a remote host configured, steps 1–4 happen on that machine inside a tmux session instead — see [Remote sessions](#remote-sessions).
 
+### Opening an existing PR
+
+`luv -l <PR URL>` gives you the PR as it is *right now*: a full clone into a
+workspace of its own, checked out on the PR's head branch. It never reuses a
+folder that happens to be sitting there — a URL you paste is a request to look
+at that PR, not at whatever was checked out in `myrepo-mbp-123` last week. Run
+it twice on the same PR and you get `myrepo-mbp-123` and `myrepo-mbp-123_2`,
+which are independent workspaces you can run side by side. When the PR comes
+from a fork, the base repo is added as `upstream` and fetched too, so the branch
+you need to diff or rebase against is there.
+
+`-r` is the exception: resuming means picking up a conversation, and a
+conversation lives in the folder it was held in, so `luv -l <URL> -r` reopens the
+newest workspace for that PR instead of cloning another. `luv <repo> -pr <N>`
+also keeps reusing its workspace — it names a workspace, where a URL names a PR.
+
 ## Commands
 
 | Command | Description |
@@ -105,7 +121,9 @@ With a remote host configured, steps 1–4 happen on that machine inside a tmux
 | `luv config set\|get\|unset <key> [value]` | Read or write a single setting |
 | `luv config list` | Show all settings |
 | `luv --init` | Configure default GitHub org only |
-| `luv ls [--host H] [--prune] [--no-pr]` | List every live session on every host, with each one's PR link |
+| `luv ls [--host H] [--prune] [--no-pr] [--no-ports]` | List every live session on every host, with each one's PR link and detected ports |
+| `luv ports [<repo> [n]] [--watch [N]]` | Show ports the sessions are listening on; naming one forwards it to localhost |
+| `luv ports --off [<repo> [n]]` | Drop forwards again |
 | `luv continue [<repo> [number]]` | Attach to a live session |
 | `luv handover [<repo> [n]] --to HOST` | Move a session to another machine and resume it there |
 | `luv rm <session\|workspace>...` | Kill a session and delete its workspace on its host |
@@ -115,8 +133,8 @@ With a remote host configured, steps 1–4 happen on that machine inside a tmux
 | `luv --codex [org/]<repo> [prompt...]` | Create a workspace and launch Codex in YOLO mode |
 | `luv [org/]<repo> -b <branch> [prompt...]` | Create a workspace based off `<branch>` instead of the default |
 | `luv [org/]<repo> <number> [prompt]` | Reopen an existing workspace |
-| `luv -l <PR URL> [prompt]` | Open any GitHub PR by URL |
-| `luv [org/]<repo> -pr <number> [prompt]` | Open a PR by repo + number |
+| `luv -l <PR URL> [prompt]` | Clone any GitHub PR by URL into a fresh workspace |
+| `luv [org/]<repo> -pr <number> [prompt]` | Open a PR by repo + number, reusing its workspace |
 | `luv --clean` | Delete workspaces where the branch is fully pushed/merged |
 | `luv --clean -f` | Force delete all workspaces |
 | `luv --clean --safe -f` | Force delete only workspaces older than 24h |
@@ -219,6 +237,20 @@ luv continue                        # reattach exactly where you left off
 
 Use `--local` for a one-off local run, `-s HOST` to target a different machine, and `-i PATH` for a different SSH key.
 
+### Reaching servers the agent started
+
+Agents working on a remote start servers there. luv finds them and forwards them to this machine on the same port number wherever it's free, so the URL in the agent's output is the URL that works for you.
+
+```bash
+luv ls                       # PORTS column: what was detected, on every session
+luv ports myrepo 42          # forward that session's ports to localhost
+luv ports --off myrepo 42    # drop them again
+```
+
+The session you're **attached to** is forwarded automatically as servers come and go, and announces each one on the tmux status line (`luv: localhost:3000 → dashboard`) — nothing to run. Everything else is opted in by name, because a busy host carries dozens of sessions and they shouldn't all claim local ports uninvited.
+
+Both processes under the session's tmux pane and Docker Compose stacks belonging to the workspace are found; forwards bind `127.0.0.1`, and they outlive detaching so a long-running session stays reachable.
+
 ### Handing a session to another machine
 
 Start something on your laptop, then move it — workspace, uncommitted work, and the agent's conversation — to a machine that won't go to sleep:
@@ -270,9 +302,10 @@ registry as soon as its tmux session exits, but the clone it was working in
 stays on the remote disk. Those orphans are invisible to `luv ls` and are
 usually what is actually filling up the box.
 
-Only folders ending in `-{N}` are ever eligible — `{repo}-{machine}-{N}` and
-pre-slug `{repo}-{N}` alike. Anything else in the workspace root is left alone,
-and a target that doesn't resolve to one is an error rather than an `rm -rf`.
+Only folders ending in `-{N}` are ever eligible — `{repo}-{machine}-{N}`, a
+`luv -l` copy `{repo}-{machine}-{N}_2`, and pre-slug `{repo}-{N}` alike.
+Anything else in the workspace root is left alone, and a target that doesn't
+resolve to one is an error rather than an `rm -rf`.
 
 ## Configuration
 

{luv_cli-0.3.0 → luv_cli-0.5.0}/README.md

@@ -40,7 +40,7 @@ luv other-org/my-repo "fix the bug"
 # Reopen workspace #42
 luv my-repo 42
 
-# Open any GitHub PR by URL
+# Clone any GitHub PR by URL into a fresh workspace
 luv -l https://github.com/org/repo/pull/123
 
 # Open a shell instead of Claude
@@ -74,6 +74,22 @@ The machine name is what keeps two computers apart. Each one works out the next
 
 With a remote host configured, steps 1–4 happen on that machine inside a tmux session instead — see [Remote sessions](#remote-sessions).
 
+### Opening an existing PR
+
+`luv -l <PR URL>` gives you the PR as it is *right now*: a full clone into a
+workspace of its own, checked out on the PR's head branch. It never reuses a
+folder that happens to be sitting there — a URL you paste is a request to look
+at that PR, not at whatever was checked out in `myrepo-mbp-123` last week. Run
+it twice on the same PR and you get `myrepo-mbp-123` and `myrepo-mbp-123_2`,
+which are independent workspaces you can run side by side. When the PR comes
+from a fork, the base repo is added as `upstream` and fetched too, so the branch
+you need to diff or rebase against is there.
+
+`-r` is the exception: resuming means picking up a conversation, and a
+conversation lives in the folder it was held in, so `luv -l <URL> -r` reopens the
+newest workspace for that PR instead of cloning another. `luv <repo> -pr <N>`
+also keeps reusing its workspace — it names a workspace, where a URL names a PR.
+
 ## Commands
 
 | Command | Description |
@@ -82,7 +98,9 @@ With a remote host configured, steps 1–4 happen on that machine inside a tmux
 | `luv config set\|get\|unset <key> [value]` | Read or write a single setting |
 | `luv config list` | Show all settings |
 | `luv --init` | Configure default GitHub org only |
-| `luv ls [--host H] [--prune] [--no-pr]` | List every live session on every host, with each one's PR link |
+| `luv ls [--host H] [--prune] [--no-pr] [--no-ports]` | List every live session on every host, with each one's PR link and detected ports |
+| `luv ports [<repo> [n]] [--watch [N]]` | Show ports the sessions are listening on; naming one forwards it to localhost |
+| `luv ports --off [<repo> [n]]` | Drop forwards again |
 | `luv continue [<repo> [number]]` | Attach to a live session |
 | `luv handover [<repo> [n]] --to HOST` | Move a session to another machine and resume it there |
 | `luv rm <session\|workspace>...` | Kill a session and delete its workspace on its host |
@@ -92,8 +110,8 @@ With a remote host configured, steps 1–4 happen on that machine inside a tmux
 | `luv --codex [org/]<repo> [prompt...]` | Create a workspace and launch Codex in YOLO mode |
 | `luv [org/]<repo> -b <branch> [prompt...]` | Create a workspace based off `<branch>` instead of the default |
 | `luv [org/]<repo> <number> [prompt]` | Reopen an existing workspace |
-| `luv -l <PR URL> [prompt]` | Open any GitHub PR by URL |
-| `luv [org/]<repo> -pr <number> [prompt]` | Open a PR by repo + number |
+| `luv -l <PR URL> [prompt]` | Clone any GitHub PR by URL into a fresh workspace |
+| `luv [org/]<repo> -pr <number> [prompt]` | Open a PR by repo + number, reusing its workspace |
 | `luv --clean` | Delete workspaces where the branch is fully pushed/merged |
 | `luv --clean -f` | Force delete all workspaces |
 | `luv --clean --safe -f` | Force delete only workspaces older than 24h |
@@ -196,6 +214,20 @@ luv continue                        # reattach exactly where you left off
 
 Use `--local` for a one-off local run, `-s HOST` to target a different machine, and `-i PATH` for a different SSH key.
 
+### Reaching servers the agent started
+
+Agents working on a remote start servers there. luv finds them and forwards them to this machine on the same port number wherever it's free, so the URL in the agent's output is the URL that works for you.
+
+```bash
+luv ls                       # PORTS column: what was detected, on every session
+luv ports myrepo 42          # forward that session's ports to localhost
+luv ports --off myrepo 42    # drop them again
+```
+
+The session you're **attached to** is forwarded automatically as servers come and go, and announces each one on the tmux status line (`luv: localhost:3000 → dashboard`) — nothing to run. Everything else is opted in by name, because a busy host carries dozens of sessions and they shouldn't all claim local ports uninvited.
+
+Both processes under the session's tmux pane and Docker Compose stacks belonging to the workspace are found; forwards bind `127.0.0.1`, and they outlive detaching so a long-running session stays reachable.
+
 ### Handing a session to another machine
 
 Start something on your laptop, then move it — workspace, uncommitted work, and the agent's conversation — to a machine that won't go to sleep:
@@ -247,9 +279,10 @@ registry as soon as its tmux session exits, but the clone it was working in
 stays on the remote disk. Those orphans are invisible to `luv ls` and are
 usually what is actually filling up the box.
 
-Only folders ending in `-{N}` are ever eligible — `{repo}-{machine}-{N}` and
-pre-slug `{repo}-{N}` alike. Anything else in the workspace root is left alone,
-and a target that doesn't resolve to one is an error rather than an `rm -rf`.
+Only folders ending in `-{N}` are ever eligible — `{repo}-{machine}-{N}`, a
+`luv -l` copy `{repo}-{machine}-{N}_2`, and pre-slug `{repo}-{N}` alike.
+Anything else in the workspace root is left alone, and a target that doesn't
+resolve to one is an error rather than an `rm -rf`.
 
 ## Configuration
 

{luv_cli-0.3.0 → luv_cli-0.5.0}/docs/configuration.md

@@ -109,6 +109,30 @@ or `ssh_opts` may be set here and takes precedence over the `remote.*` value of
 the same name. This is what makes `-s otherbox` usable: without it, one global
 key would be wrong for every host but the default.
 
+### `ports`
+
+*object.* Port forwarding. Servers an agent starts on a remote host are
+detected and tunnelled to this machine — see
+[remote-sessions.md](remote-sessions.md#reaching-servers-the-agent-started).
+Every key is optional:
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `auto` | `true` | Forward the session you are attached to, as servers come and go. `false` leaves everything to `luv ports`. |
+| `interval` | `10` | Seconds between re-checks while attached. Minimum 2. |
+| `bind` | `"127.0.0.1"` | Local address the forwards listen on. `"0.0.0.0"` would publish the agent's dev server to your whole network. |
+| `min` | `1024` | Ports below this are ignored; a dev server is not on 80. |
+| `ignore` | `[]` | Specific ports never to forward. |
+| `max_per_session` | `12` | Cap on forwards per session, so one stack cannot eat the local port space. |
+
+```bash
+luv config set ports.interval 5
+luv config set ports.ignore '[5432, 6379]'
+luv config set ports.auto false
+```
+
+Unlike `remote.*`, these are global — there is no `remote.hosts.<name>.ports`.
+
 ## Resolution order
 
 **Host:** `-s HOST` → `remote.host`. If neither, luv runs locally.

{luv_cli-0.3.0 → luv_cli-0.5.0}/docs/remote-sessions.md

@@ -256,6 +256,85 @@ luv -i ~/.ssh/other_key myrepo      # use a different key this once
 Detach from a session with `Ctrl-b d` (tmux's default prefix). The agent keeps
 running.
 
+## Reaching servers the agent started
+
+An agent working on the remote starts servers there — a dev server, a compose
+stack, a database. luv finds them and tunnels them to this machine, on the same
+port number wherever it is free, so the URL the agent prints in its own output
+is the URL that works here.
+
+**The session you are attached to is forwarded automatically.** It is re-checked
+every few seconds, so a server started ten minutes into a session is reachable
+shortly after it comes up, without running anything. When a forward appears the
+session says so on its tmux status line:
+
+```
+luv: localhost:3000 → dashboard, localhost:8080 → server
+```
+
+The ports are also set on the tmux session as `@luv_ports`, if you would rather
+have them permanently in your own `status-right`.
+
+**Everything else is opted in by name.** A busy host carries dozens of sessions
+and they should not all get a piece of this machine's port space uninvited:
+
+```bash
+luv ls                          # PORTS column: what was detected, forwarded or not
+luv ports                       # detail view; refreshes what is already forwarded
+luv ports myrepo 42             # forward this session's ports
+luv ports myrepo 42 --watch     # ...and keep it up to date, printing each change
+luv ports --off myrepo 42       # drop them again
+luv ports --off                 # drop everything
+```
+
+```
+HOST  WORKSPACE      REMOTE  LOCAL  URL                    SERVICE    STATE
+box   myrepo-box-42    3000   3001  http://localhost:3001  dashboard  up
+box   myrepo-box-42    5173   5173  http://localhost:5173  vite       up
+box   other-box-17     5432   5432  -                      postgres   detected
+```
+
+Forwards outlive detaching — the session is still running and `localhost:3000`
+should keep working — so `luv ports myrepo 42` is also how a long-running
+session stays reachable after you close the window.
+
+`REMOTE` and `LOCAL` differ when the local number was already taken, by another
+session or by something of your own; luv walks up from the remote number and
+remembers what it chose, so the URL stays put across runs.
+
+### What gets found
+
+Two sources, because neither sees everything:
+
+- **Processes under the session's tmux pane.** A server the agent started
+  itself — `npm run dev`, `python -m http.server` — is a descendant of the pane,
+  which is what ties the port to a session. Only your own processes are visible
+  this way, so other people's services on a shared box never appear.
+- **Docker Compose stacks belonging to the workspace.** A published port is held
+  by `docker-proxy` rather than by anything under the pane, so the Compose
+  project label answers instead. Both the project luv starts (`luv-<workspace>`)
+  and the one an agent gets by running `docker compose up` itself (named after
+  the workspace folder) count as the workspace's.
+
+A port that is only *exposed* to the Compose network — `9009/tcp` with no host
+mapping — has nothing on the host to point a tunnel at and is not offered. Add a
+`ports:` entry to the compose file if you want it.
+
+Forwards bind `127.0.0.1` on this machine, so nothing is republished to your
+network. See [`ports.*`](configuration.md#ports) to change the interval, the
+bind address, or which ports are skipped, and `ports.auto` to turn the automatic
+half off entirely.
+
+### When it doesn't work
+
+- **Nothing detected, and the host is otherwise fine.** The host needs a luv new
+  enough to know `luv --listening`; an older one reports nothing rather than
+  failing. Upgrade luv there.
+- **`warning: <host> refuses port forwarding`.** That host's `sshd_config` has
+  `AllowTcpForwarding no`.
+- **A forward that stopped working.** The watcher logs to `~/.luv/ports.log`; it
+  cannot print while a full-screen agent UI owns the terminal.
+
 ## Handing a session to another machine
 
 `luv handover` relocates a running workspace. The usual direction is laptop →
@@ -345,19 +424,27 @@ a laptop and a box would routinely pick the same one and push the same branch.
 Folders and branches created before slugs existed keep working — luv looks for
 its own name first, then any other machine's, then the plain `{repo}-{number}`.
 
+`luv -l <PR URL>` clones into a folder of its own every time, so a second run on
+the same PR gets `{repo}-{machine}-{number}_2`, a third `_3`. The suffix is part
+of the number's segment, so those folders are still workspace `{number}`
+everywhere it matters — `luv ls`, `luv rm`, `--clean`, handover. Where a number
+has several copies, the newest wins: that is the one you just made.
+
 Sessions are named after the workspace folder: `~/prs/myrepo-box-42` becomes
 `luv-myrepo-box-42`. tmux forbids `.` and `:` in session names, so a repo like
 `foo.js` becomes `luv-foo_js-box-42`.
 
-When the workspace is already known — reopening by number, `-pr`, or `-l` — the
-laptop pins the session name down before dispatching, so `tmux new-session -A`
-doubles as "attach if it's already running". It can't compute that name, though,
-since the slug belongs to the machine holding the folder: it takes it from the
-session registry, or asks the host directly, and falls back to the
+When the workspace is already known — reopening by number, `-pr`, or `-l -r` —
+the laptop pins the session name down before dispatching, so `tmux new-session
+-A` doubles as "attach if it's already running". It can't compute that name,
+though, since the slug belongs to the machine holding the folder: it takes it
+from the session registry, or asks the host directly, and falls back to the
 `luv-pending-<id>` rename-on-arrival path if the host doesn't answer.
 
-When it isn't known — a brand new workspace, or bare `-n`/`-r` — the laptop uses
-a placeholder `luv-pending-<id>` and the remote renames it once the clone lands.
+When it isn't known — a brand new workspace, plain `luv -l` (whose folder the
+remote only picks once it sees what is already there), or bare `-n`/`-r` — the
+laptop uses a placeholder `luv-pending-<id>` and the remote renames it once the
+clone lands.
 If the target name is already taken by another live session, luv keeps the
 session under `luv-myrepo-box-42-2` and warns rather than failing.
 

{luv_cli-0.3.0 → luv_cli-0.5.0}/docs/sessions.md

@@ -42,7 +42,10 @@ the session (which luv does as soon as the clone lands) breaks nothing.
       "pr_number": 42,
       "pr_url": "https://github.com/exosphere/myrepo/pull/42",
       "pr_state": "OPEN",
-      "pr_checked": 1753408899
+      "pr_checked": 1753408899,
+      "ports": [3000, 5173],
+      "forwards": [{"remote": 3000, "local": 3001, "label": "dashboard"}],
+      "ports_checked": 1753408899
     }
   ]
 }
@@ -63,8 +66,11 @@ the session (which luv does as soon as the clone lands) breaks nothing.
 | `pr_number`, `pr_url` | The session's pull request; `null` until one exists |
 | `pr_state` | `OPEN`, `CLOSED` or `MERGED` — what `luv rm --merged` selects on |
 | `pr_checked` | Unix time GitHub was last asked about it |
-| `pr_hint` | PR number known at dispatch (`-l` / `-pr` only); absent otherwise |
+| `pr_hint` | PR number known at dispatch (`-l` / `-pr` only); absent otherwise. Set even when the folder isn't yet known, which is always the case for `-l` |
 | `adopted` | Present when this machine found the session rather than starting it |
+| `ports` | Ports the session was last seen listening on, on its own host |
+| `forwards` | Live tunnels to this machine: `remote` port, the `local` one it landed on, and the service `label`. Persisted so a URL stays put across runs, and so a forward survives detaching |
+| `ports_checked` | Unix time the forwards were last brought in line |
 
 `attached`, `activity`, and `live` are recomputed on every reconcile and are
 deliberately **not** written back to the file.
@@ -230,10 +236,11 @@ case.
 
 Two things bound the damage:
 
-- Only names ending in `-{N}` are eligible — `{repo}-{machine}-{N}` and pre-slug
-  `{repo}-{N}` alike — checked again immediately before the `rm -rf` rather than
-  only at selection time. A stray directory in the workspace root is never a
-  candidate, and a target that resolves to one is an error, not a deletion.
+- Only names ending in `-{N}` are eligible — `{repo}-{machine}-{N}`, a `luv -l`
+  copy `{repo}-{machine}-{N}_2`, and pre-slug `{repo}-{N}` alike — checked again
+  immediately before the `rm -rf` rather than only at selection time. A stray
+  directory in the workspace root is never a candidate, and a target that
+  resolves to one is an error, not a deletion.
 - A named target is its own confirmation, but `--merged` and `--dead` print what
   they matched and ask, because a selector can sweep up folders on a machine you
   are not looking at. `-f` skips the prompt.