@puddle-code/cli 0.0.1 → 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+<!--
+Rolling changelog for the NEXT release. Governance lives in CLAUDE.md §"Changelog discipline".
+On publish: retitle [Unreleased] to [X.Y.Z] — date, archive a copy to
+docs/changelogs/CHANGELOG-vX.Y.Z.md, then reset this file to this template.
+Past releases: see docs/changelogs/.
+-->
+
+# Changelog
+
+## [0.0.2] — 2026-07-15
+
+### Added
+
+- The npm page for **`@puddle-code/cli`** now renders this repository's `README.md` and links back to the repo — the package gains `homepage`, `repository`, and `bugs` fields, and the build copies the root README into the package at publish time (npm only renders a README that sits in the package directory). The README gains an npm version badge and a licence badge.
+- Profiles can now be **renamed** in Settings → Profile — the Name field is editable (previously read-only). The name is a display label that keys nothing on disk (directories are id-keyed), so a rename touches no files; it stays letters/digits/dot/underscore/hyphen and must be unique (a clash is rejected). `PATCH /api/profiles/:id` now accepts an optional `name` alongside `branch_prefix` (additive; `PROTOCOL_VERSION` minor bump) — SPEC §6.
+- The right sidebar now shows **every project's sessions**, grouped by project (a header per project when expanded, a divider between groups on the collapsed rail), with the project order inheriting the homescreen's — clicking a session jumps into its own project. A per-browser toggle (Settings → Appearance, on by default) reverts to the current-project-only view. The list scrolls without a visible scrollbar so a long list still works while the new-terminal/new-session controls stay fixed, and a collapsed dot's tooltip now shows the session name over its branch. New query `GET /api/sessions?profile=…` (SPEC §12).
+- Homescreen projects can now be **renamed**, **archived**, and **reordered**. Hover a card (or right-click it) for rename/archive; archiving is a reversible hide — the project drops into a collapsed "Archived" disclosure at the bottom, keeping every session and worktree, and reopening restores it. Drag cards to reorder (newest first until dragged); the order persists per profile (`profileSettings.projectOrder`) and the cross-project session sidebar inherits it. New endpoint `PATCH /api/projects/:id {name?, archived?}` + `projects.archived` column (migration 011; additive `PROTOCOL_VERSION` minor bump) — SPEC §11.
+- The workspace centre is now a **free-form tiling area** (SPEC §8): editor tabs (files, diffs, media) and agent terminals share one space — drag any tab onto a pane to reorder it, or onto a pane's edge to split it into an arbitrary grid of resizable panes (VSCode editor-groups style). Terminals stay mounted and their DOM is adopted into whichever pane shows them, so moving one never drops its PTY/scrollback; the same file may open in two panes sharing one editor model. The layout persists as a recursive tree in `ui_state.layout_tree` (legacy layouts migrate automatically; additive `PROTOCOL_VERSION` minor bump).
+- Cmd/Ctrl+click now opens more terminal paths: extensionless directories and files with path structure (`.worktrees/hil-demos`, `~/.claude/prompts/up-fix`, `/home/bios/waddle`), not just paths ending in a recognised extension. A leading `@` (Claude Code's file-ref syntax) is stripped. The daemon's `/resolve` check still gates underlining (SPEC §7).
+- macOS copy/paste in terminals: **⌘C** copies the terminal's selection to the clipboard (`Ctrl-C` stays the interrupt), and **⌘V** pastes. Only on Mac clients (SPEC §7).
+- The file explorer is now VSCode-grade (SPEC §8): git decorations (a status colour + one-letter badge — **U**ntracked/**M**odified/**A**dded/**D**eleted/**R**enamed/**C**onflict, git-ignored files greyed, folders tinted by their most-significant descendant), colourful per-type file icons, rich right-click menus on files, folders and empty space, a cut/copy/paste clipboard with drag-to-move, multi-select (⌘/⇧-click), full arrow-key navigation with type-to-jump, inline create/rename with a delete confirmation, and a header utility bar (New File · New Folder · Refresh · Collapse Folders) whose branch title eases sideways on hover to reveal the tail the icons occlude. Backed by new daemon endpoints — `GET /git-status` and `POST /create|/rename|/copy|/delete` on `/api/worktrees/:sid`, every path confined to the worktree (additive; `PROTOCOL_VERSION` minor bump).
+- Images, video, audio and PDFs now open as an inline preview tab instead of the "Binary — use Download" fallback. A new `GET /api/worktrees/:sid/media` streams the file with its real content-type (`image/*`, `video/*`, `audio/*`, `application/pdf`) and an `inline` disposition; the viewer fetches it through the authed API and renders from an object URL, so no token ever rides in an element `src`. Unknown binaries keep the download fallback (SPEC §8; additive `PROTOCOL_VERSION` minor bump).
+- The file editor gained VSCode keybindings: **⌥Z** toggles line wrap (it flips the `editorWordWrap` client setting, so every open editor follows and the choice persists). ⌘/Ctrl+S still saves; Monaco's stock multi-cursor / comment / find bindings are unchanged (SPEC §8).
+- Right-click a session — its sidebar row, its collapsed status dot, or its tab in the top strip — to open the same kill / resume / rename / archive / move menu as the row's ellipsis (SPEC §12).
+- Settings → **Sessions** (renamed from Permissions & Safety) now edits the launch-text templates an agent receives when it starts a freshly created worktree (`{{rules}}` injects the repo's onboarding notes) or joins an existing/shared one. Either template may be cleared to send no preamble, or reset to the built-in default (SPEC §4).
+- Archived sessions are no longer hidden away: they collapse under an **Archived** header at the bottom of the sessions sidebar and reopen (view-only, to read their terminal history) — archiving is not deletion (SPEC §4).
+- `puddle start` and `puddle connect` now run the cockpit **in the background** once ready: the command bootstraps interactively (ssh prompts still land on your terminal), detaches, prints the URL, and exits — the terminal may close. `--foreground` keeps the old attached behaviour. New commands: `puddle list` shows running cockpits (verified by pid + a per-instance nonce the UI server echoes as `X-Puddle-Cockpit`, never by reachability alone) and `puddle kill [local | user@host | --all]` stops one — sessions keep running on the host. Cockpit records live in `~/.puddle/cockpits/`, background logs in `~/.puddle/logs/cockpit-<target>.log` (SPEC §10).
+
+### Changed
+
+- **Protocol major bump 5.9 → 6.0**, on purpose and with no schema shape change: a major mismatch makes every connected CLI auto-upgrade its daemon on the next handshake, so this release forces every host onto the new daemon (`packages/shared/src/protocol.ts`; PROTOCOL.md, "The rule").
+- GitHub release notes are now taken from the release's changelog (`docs/changelogs/CHANGELOG-v<version>.md` via `scripts/extract-changelog.mjs`) instead of being auto-derived from commits, and `@puddle-code/cli` now ships that same changelog as its `CHANGELOG.md` — one changelog drives the release notes and the npm package.
+- The Worktrees navigator's status badges are terser, matching VSCode: a dirty worktree shows a yellow **M** (the explorer's modified-decoration colour) instead of "uncommitted", and a worktree with live sessions shows a green count (e.g. **3**) instead of "3 running". Both keep the full text on hover.
+- The top bar is slimmer — a shorter header with a smaller mark sized inline with the title — reclaiming vertical space for the workspace.
+- The daemon no longer crashes (or crash-loops under its supervisor) when its configured port is already in use: it now **falls back to an OS-assigned free port** and records where it actually bound in `~/.puddle/runtime.json`. `puddle connect`/`start` discover the daemon from that file (falling back to `config.json`, then 7434), always revalidating by token, so a busy 7434 no longer breaks a connection. Every start still prefers the configured port, so the daemon returns to it once the conflict clears (SPEC §10).
+- A session's default display name is now the agent's own session name (for Claude Code, the transcript's ai-title / agent-name — what its resume picker shows) instead of the leading hex block of the puddle session id. A user rename still overrides it, and clearing the rename reverts to the agent's name (then the id). This retires the `.puddle/session-title` marker file, which could not work once several agents shared one worktree. Additive protocol change: the `sessions.agent_title` field and the `renamed` WS event's `agent_title` (`PROTOCOL_VERSION` minor bump).
+- Releases no longer publish a `darwin-x64` daemon tarball: GitHub's last Intel Mac runner (`macos-13`) queues so long it blocked the whole release. Intel Mac hosts are unsupported until the entry is restored (or built under Rosetta); Apple-silicon Macs and Linux are unaffected.
+
+### Fixed
+
+- Client-side navigation now updates the view immediately instead of only after a page reload. react-router v7+ wraps every location update in `React.startTransition` by default, so under React 19 clicking a session, creating one, or clicking the logo changed the URL synchronously while the matched route stayed deferred as a pending transition — the view appeared frozen until a reload. The router is now mounted with `useTransitions={false}`, making navigation an urgent, synchronous update.
+- Clicking a file (editor) tab that shares a pane with the bound session's terminal no longer flips straight back to the terminal. The workspace's deep-link effect — which ensures and focuses the URL session's terminal — was keyed on the ui-state handle, a fresh object every render, so it re-ran on **every** re-render (each agent status tick, each keystroke) and kept re-asserting the terminal as the pane's active tab. It now fires once per genuine session navigation, so a file tab you open stays open and a new tab/session lands in the currently focused pane rather than being yanked to the session's terminal (SPEC §8).
+- Account login (and agent spawning generally) failed when the agent CLI lived in a dir the supervisor's bare PATH omits — notably Claude Code's native-installer `~/.local/bin`, which launchd's `/usr/bin:/bin:/usr/sbin:/sbin` doesn't include: the daemon couldn't find `claude`, so the login terminal was blank and accounts read as logged-out. The install now bakes a richer PATH into the systemd unit and launchd plist, and the daemon prepends `config.json`'s new `agentPath` (default covers `~/.local/bin`, `~/bin`, Homebrew, `/usr/local/bin`; editable in Settings → Terminal & editor) to its PATH at boot. Additive `PROTOCOL_VERSION` minor bump (SPEC §5, §10).
+- A remote `puddle connect` no longer risks making a later local `puddle start` report a spurious port conflict. Its UI server was told to avoid the *remote* daemon's port when auto-picking, but the port a local `start` actually probes is *this* machine's daemon port — the two coincide only when the remote daemon runs on the default 7434. A connect cockpit's proxy could therefore land on the local daemon's port and be mistaken for it. The avoided port is now discovered from this machine the same way `start` finds its own daemon, so they can never collide (SPEC §10).
+- "Skip permission prompts" now actually skips them for Claude Code. The `--dangerously-skip-permissions` flag was delivered correctly but Claude 2.1.x silently downgraded it to normal prompts because its bypass-mode disclaimer had never been accepted in puddle's managed config dir (that acceptance is only offered interactively, which a non-interactive PTY can't do). Opening the profile skip gate — the existing typed-confirmation dialogue in Settings → Sessions — now records that acceptance (`bypassPermissionsModeAccepted`) for the profile's skip-capable accounts, as does opting an individual account in afterwards, so the flag takes effect. Verified against Claude Code 2.1.210.
+- Renaming a session now sticks. The `.puddle/session-title` marker sync used to re-apply the agent's on-disk title over a UI rename on the next `.puddle` change; that title mechanism is gone, so a rename persists.
+- Proxied apps with absolute asset paths (any Vite/CRA-style build) no longer render a blank page through `/proxy/<sid>/<port>/`. Their `/assets/…` and `fetch('/api/…')` requests used to escape the proxy prefix and receive puddle's own `index.html` (the "Failed to load module script … MIME type of text/html" console error); the cockpit origin now 307-redirects any stray request whose `Referer` is a proxied page back under that page's prefix, and the static handler 404s missing assets instead of SPA-falling-back to HTML. WS handshakes and `no-referrer` apps still need the per-port `ssh -L` fallback (SPEC §9, §15.5 resolved).
+- A request with a malformed percent-escape (e.g. `/100%_done.png`) no longer crashes the whole cockpit process: the static handler answers 404 instead of letting `decodeURIComponent` throw through the request listener.
+- `puddle connect` no longer loops "tunnel lost — reconnecting… / tunnel restored". Three causes: the ssh forward ran with no keepalives, so idle NAT/firewall timeouts felled it on every quiet spell (`ServerAliveInterval=15`/`ServerAliveCountMax=3` on every ssh spawn now); a forward child killed after a failed readiness probe re-triggered the exit handler and spawned a second reconnect loop racing the first; and every sub-second blip printed a lost/restored pair (outages healing within a 2s grace window are now silent, unless the tunnel is genuinely flapping — a drop within 30s of a restore — which announces immediately). The forward also runs with `ExitOnForwardFailure=yes` so a failed `-L` bind dies visibly.
+- `puddle start` can no longer be fooled by another cockpit's UI server sitting on the daemon's port. The UI server never auto-picks the daemon's own port (a `puddle connect` launched while 7433 was busy used to land exactly on 7434), and the daemon probe now verifies identity — only a 200 with this host's token counts; a 401/403 is reported as a clear port conflict instead of "token rejected" (or, worse, silently wiring the local cockpit to a remote daemon). A state directory without a managed install now bootstraps one rather than refusing (`start`/`connect` promise a running daemon — SPEC §10; the existing db/token/worktrees are untouched).
+- The CLI build wipes `dist/` before bundling, so the published npm package can no longer pick up leftovers from earlier builds (v0.0.1 shipped three stray tsc artefacts from the pre-Phase-6 stub this way); the `bin` path is normalised to the form npm was auto-correcting at publish time. No protocol change.

package/README.md

@@ -0,0 +1,78 @@
+# Puddle
+
+[![npm](https://img.shields.io/npm/v/@puddle-code/cli?logo=npm)](https://www.npmjs.com/package/@puddle-code/cli)
+[![Licence: MIT](https://img.shields.io/badge/licence-MIT-blue)](LICENSE)
+
+Puddle is an open-source, multi-account coding agent orchestrator with first-class SSH support and a lightweight GUI. With a single command,
+
+```bash
+puddle connect <user>@<host>
+```
+
+Puddle manages parallel agents anywhere you SSH into, insulates agents in dedicated worktrees, and keeps your agents alive across disconnects and restarts.
+
+## Quick start
+
+**On your local machine where you will be using the GUI, run:**
+
+```sh
+npm install -g @puddle-code/cli
+```
+
+**To launch agents on a remote host:**
+
+```sh
+puddle connect <user>@<host>
+```
+
+This connects Puddle to the remote host over SSH, bootstrapping the Puddle daemon on first contact and enabling you to begin development.
+
+Puddle works using your system `ssh`, so `~/.ssh/config`, agents, and jump hosts apply.
+
+**For development on your own machine:**
+
+```sh
+puddle start
+```
+
+This installs the Puddle daemon under `~/.puddle` and serves the GUI at `http://localhost:7433`.
+
+Note that Ctrl-C closes the GUI only, while agent sessions keep running.
+
+**Daemon-only installs:**
+
+Daemon-only installs (no CLI) use the `install.sh` attached to each release — see the Releases page of this repository:
+
+```sh
+curl -fsSL https://github.com/PerceptronV/puddle-code/releases/latest/download/install.sh | sh
+```
+
+**Host requirements**: Linux (glibc — Ubuntu 22.04+, Debian 12+, RHEL 9+; Alpine is not supported) or macOS, with `git` and `curl`, plus whichever agent CLIs you want on `PATH`. The client side works from any OS with a browser and `ssh` (Windows works, with repeated auth prompts unless you use a key).
+
+## How it works
+
+- **The Puddle daemon works anywhere you can SSH into.** It is installed on your host during every fresh connect, relaying information across SSH to your local GUI. The daemon is the parent of every agent process, keeping sessions running when your laptop sleeps, the window closes, or the SSH connection drops. Puddle also maintains a stateful memory of your conversations to survive machine reboots.
+- **Puddle orchestrates parallel isolated agents** each working in a unique git worktree and branch. You can choose the branch and worktree during session creation.
+- **Puddle's lightweight GUI** allows you to track agent progress, session usage, and active worktrees.
+- **Puddle's philosophy is that any good developer must stay grounded in their code.** Puddle natively integrates live terminals, file editing in Monaco, git commit grahps, diff views, and opens worktrees in your favourite IDE.
+- **Multiple profiles and accounts** enable several collaborators to collaborate on a shared remote host. Puddle manages multiple accounts per agent type and profile, symlinking conversation histories so you can run from multiple Claude Code accounts at once and move your conversations between each.
+
+```
+ client machine                          host machine (local or remote)
+┌──────────────────────────────┐        ┌───────────────────────────────────┐
+│ browser ── localhost:7433    │        │  puddled  (systemd user service)  │
+│               │              │ local: │   ├─ REST + WS API                │
+│  puddle CLI ◄─┘              │ direct │   ├─ PTY manager                  │
+│   ├─ static web UI assets    │───────►│   ├─ git worktree manager         │
+│   └─ /api + /ws proxy        │ remote:│   ├─ per-agent adapters           │
+└──────────────────────────────┘ ssh -L │   └─ SQLite + append-only logs    │
+                                        └───────────────────────────────────┘
+```
+
+The CLI serves the UI at a stable local origin and reverse-proxies the API to the daemon, directly in local mode, through the tunnel in SSH mode. The daemon is headless and host-agnostic on `127.0.0.1:7434`. UI updates ship with the CLI (`npm update -g @puddle-code/cli` refreshes the cockpit for every host); the daemon only has to update when the versioned protocol breaks, and the CLI does that automatically. A mandatory bearer token plus Host/Origin validation guard the localhost API against malicious web pages.
+
+Everything lives under `~/.puddle` on the host, installed without sudo. Uninstalling is stopping the service and deleting that directory.
+
+## Licence
+
+Puddle is licensed under the [MIT License](LICENSE). Copyright (c) 2026 Yiding Song.