luv-cli 0.4.0__tar.gz → 0.5.1__tar.gz

luv_cli-0.5.1/.failproofai/policies/version-policies.mjs

@@ -0,0 +1,107 @@
+/**
+ * version-policies.mjs — remind the agent to bump the release version.
+ *
+ * Auto-loaded by failproofai from .failproofai/policies/ — no install step.
+ *
+ * Publishing here is driven by the version in the manifest: a push to main
+ * whose version has no tag yet releases itself (.github/workflows/publish.yml).
+ * So a branch that changes the tool and forgets the version merges into a main
+ * that publishes nothing, and the change sits unreleased until someone notices.
+ *
+ * So this says so on `git commit`, and only while the branch's version still
+ * matches the base branch's — it is context, not a block, and bumping the
+ * version is what turns it off for the rest of the branch.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { customPolicies, allow, instruct } from "failproofai";
+
+// First match wins, so the order is "most likely to be the release manifest".
+const MANIFESTS = [
+  { file: "pyproject.toml", re: /^\s*version\s*=\s*["']([^"']+)["']/m },
+  { file: "package.json", re: /"version"\s*:\s*"([^"]+)"/ },
+  { file: "Cargo.toml", re: /^\s*version\s*=\s*["']([^"']+)["']/m },
+];
+
+const BASE_REFS = ["origin/main", "main", "origin/master", "master"];
+
+// A `git … commit` that starts a command, so a shell segment is allowed to
+// carry flags and their values (`git -C dir commit`) but a `commit` merely
+// spoken about (`echo "run git commit later"`) is not mistaken for one.
+const GIT_COMMIT = /(?:^|[;&|\n(]|&&|\|\|)\s*(?:\w+=\S+\s+)*git\b[^;&|\n]*?\bcommit\b/;
+
+/** git, or null on any failure — this policy never gets in the way. */
+function git(cwd, args) {
+  try {
+    return execFileSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5000,
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function versionIn(text, re) {
+  const m = text == null ? null : text.match(re);
+  return m ? m[1] : null;
+}
+
+/** The manifest this repo releases from, with the version on both sides. */
+function releaseVersions(cwd) {
+  const base = BASE_REFS.find((ref) =>
+    git(cwd, ["rev-parse", "--verify", "--quiet", ref]) !== null);
+  if (!base) return null;
+
+  for (const { file, re } of MANIFESTS) {
+    if (!existsSync(join(cwd, file))) continue;
+    let head;
+    try {
+      head = versionIn(readFileSync(join(cwd, file), "utf8"), re);
+    } catch {
+      return null;
+    }
+    // No version on the base side means the manifest is new on this branch;
+    // there is nothing to bump relative to.
+    const baseVersion = versionIn(git(cwd, ["show", `${base}:${file}`]), re);
+    if (!head || !baseVersion) return null;
+    return { file, base, head, baseVersion };
+  }
+  return null;
+}
+
+customPolicies.add({
+  name: "remind-version-bump-on-commit",
+  description: "On git commit, remind that the release version is still the base branch's",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = String(ctx.toolInput?.command ?? "");
+    if (!GIT_COMMIT.test(cmd)) return allow();
+
+    const cwd = ctx.session?.cwd ?? process.cwd();
+
+    // Committing on the base branch is a different problem, and one the
+    // block-work-on-main policy already has an opinion about.
+    const branch = git(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]);
+    if (branch === null || branch === "main" || branch === "master") return allow();
+
+    const found = releaseVersions(cwd);
+    if (!found) return allow();
+    if (found.head !== found.baseVersion) return allow(); // already bumped
+
+    return instruct(
+      `${found.file} still says version ${found.head}, the same as ${found.base}. ` +
+      "Releases are cut from that version when this branch lands, so a merge " +
+      "with it unchanged publishes nothing. Bump it in this branch — patch for " +
+      "a fix or polish, minor for a feature — unless the change is docs, tests, " +
+      "or CI only, in which case say so and carry on."
+    );
+  },
+});
+
+export { customPolicies };

luv_cli-0.5.1/.github/workflows/publish.yml

@@ -0,0 +1,117 @@
+name: Publish to PyPI
+
+# Two ways in.
+#
+#   * A push to main publishes when the version in pyproject.toml is one no tag
+#     exists for yet. That is what makes a merged version bump release itself.
+#   * A v* tag publishes whatever it points at, kept so a release can still be
+#     cut by hand.
+#
+# The tag is created here rather than by a separate workflow because a tag
+# pushed with GITHUB_TOKEN does not trigger other workflows — GitHub's recursion
+# guard. Tagging elsewhere and relying on the v* trigger to fire would leave the
+# tag in place and nothing published, which is the worst of both.
+#
+# Deliberately no `paths:` filter. It would be evaluated for tag pushes as well,
+# so `paths: [pyproject.toml]` would silently drop a hand-pushed tag whose commit
+# did not happen to touch that file. The "is this already tagged" check below is
+# the real guard; a filter would only be an optimisation, and a lossy one.
+
+on:
+  push:
+    tags:
+      - "v*"
+    branches:
+      - main
+
+concurrency:
+  group: publish
+  cancel-in-progress: false
+
+jobs:
+  decide:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      publish: ${{ steps.resolve.outputs.publish }}
+      version: ${{ steps.resolve.outputs.version }}
+      needs_tag: ${{ steps.resolve.outputs.needs_tag }}
+    steps:
+      # Its own job so the pypi environment — which may require a reviewer — is
+      # never entered by a run that turns out to have nothing to publish.
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # tags, so the guard below can see them
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Work out whether there is a release to make
+        id: resolve
+        run: |
+          set -euo pipefail
+
+          if [ "${GITHUB_REF_TYPE}" = "tag" ]; then
+            version="${GITHUB_REF_NAME#v}"
+            needs_tag=false
+          else
+            version="$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')"
+            needs_tag=true
+          fi
+
+          if [ -z "${version}" ]; then
+            echo "could not determine a version to publish" >&2
+            exit 1
+          fi
+
+          if [ "${needs_tag}" = true ] && git rev-parse -q --verify "refs/tags/v${version}" >/dev/null; then
+            echo "v${version} is already tagged — nothing to release"
+            echo "publish=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          echo "releasing ${version}"
+          echo "version=${version}" >> "$GITHUB_OUTPUT"
+          echo "needs_tag=${needs_tag}" >> "$GITHUB_OUTPUT"
+          echo "publish=true" >> "$GITHUB_OUTPUT"
+
+  publish:
+    needs: decide
+    if: needs.decide.outputs.publish == 'true'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: write # push the tag a merged version bump implies
+      id-token: write # PyPI trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      # Before the build, so a tag that cannot be pushed — protected tags, say —
+      # fails the run rather than publishing a version with no tag to show for it.
+      - name: Tag the release
+        if: needs.decide.outputs.needs_tag == 'true'
+        env:
+          VERSION: ${{ needs.decide.outputs.version }}
+        run: |
+          set -euo pipefail
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag -a "v${VERSION}" -m "v${VERSION}"
+          git push origin "v${VERSION}"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

{luv_cli-0.4.0 → luv_cli-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: luv-cli
-Version: 0.4.0
+Version: 0.5.1
 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
@@ -121,7 +121,9 @@ also keeps reusing its workspace — it names a workspace, where a URL names a P
 | `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 |
@@ -235,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:

{luv_cli-0.4.0 → luv_cli-0.5.1}/README.md

@@ -98,7 +98,9 @@ also keeps reusing its workspace — it names a workspace, where a URL names a P
 | `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 |
@@ -212,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:

{luv_cli-0.4.0 → luv_cli-0.5.1}/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.4.0 → luv_cli-0.5.1}/docs/remote-sessions.md

@@ -256,6 +256,98 @@ 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.
 
+When a session ends on its own — the connection drops, ssh is killed, the pane
+dies — luv prints the way back in, already filled in for that session:
+
+```
+luv: session ended unexpectedly — continue it with:
+
+    luv continue myrepo 42
+```
+
+Copy that line and run it. If the agent took the tmux session down with it,
+there is nothing left to attach to; `luv continue` says so and hands you
+`luv myrepo 42 -r`, which reopens the workspace and resumes the conversation.
+
+## 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 →
@@ -330,7 +422,7 @@ machine with `--from` and luv will move the folder and start it fresh.
 | Step | What happens |
 |---|---|
 | `luv myrepo "…"` | Laptop records a registry entry, opens SSH, creates the tmux session, remote luv clones and launches the agent |
-| `Ctrl-b d` or lost connection | tmux session keeps running; agent unaffected; Docker containers stay up |
+| `Ctrl-b d` or lost connection | tmux session keeps running; agent unaffected; Docker containers stay up. A connection that broke leaves the exact `luv continue <repo> <n>` for it in your terminal |
 | `luv ls` | Laptop queries every known host's tmux and refreshes the registry, adopting sessions another machine started |
 | `luv continue` | Reattaches; other clients are detached so the pane isn't size-clamped |
 | Agent exits | The pane's command ends, tmux session disappears, Docker environment is torn down, `luv ls` prunes the entry on its next run |

{luv_cli-0.4.0 → luv_cli-0.5.1}/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
     }
   ]
 }
@@ -65,6 +68,9 @@ the session (which luv does as soon as the clone lands) breaks nothing.
 | `pr_checked` | Unix time GitHub was last asked about it |
 | `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.