@puddle-code/cli 0.0.33 → 0.0.34

package/CHANGELOG.md

@@ -7,12 +7,10 @@ Past releases: see docs/changelogs/.
 
 # Changelog
 
-## [0.0.33] — 2026-08-07
+## [0.0.34] — 2026-08-07
 
 ### Added
 
-- "App shortcuts in terminals" (a switch atop Settings → Hotkeys, per profile like the bindings it governs; protocol 14.2, default on): chords bound to puddle actions — ⌃⇥/⌃⇧⇥ tab cycling, ⌘K, sidebar toggles — now work while a terminal is focused, instead of being eaten by xterm and sent to the agent. Turn it off to hand those keys back to terminal apps; terminal-owned keys (⌃A, ⌃`) go to the terminal either way.
-
-### Fixed
-
-- Auto-theming agents (e.g. Claude Code with `theme: auto`) no longer come up dark under a light puddle theme: they sample the terminal background at spawn, usually before any viewer has attached, so the browser-side answer to their OSC 10/11 colour query arrived for nobody. The daemon now answers those queries itself, from the colours the client reports over the WS on connect and on every theme switch (protocol 14.1, additive — against an older daemon the viewer-side answering remains). A running agent that already sampled keeps its choice until its next start/resume.
+- `puddle install <daemon|desktop>[@version] [user@host]` — ensure a component is present: a no-op (that says so) when it already is and no version is named; an exact version otherwise, downgrades included. On Linux, `install desktop` asks where the AppImage should live (default `~/puddle`; the checksum-verified file lands as `Puddle.AppImage` so launchers and the in-app updater keep a fixed path) and opens the folder in the file manager. Pinning the daemon to a version other than the CLI's own prints a warning that the next `puddle launch` would force-upgrade it across a protocol major (pin the CLI too, or launch `--no-upgrade`).
+- `puddle upgrade` grows components and versions: `[cli|daemon|desktop][@version] [user@host]` moves one component to the newest release (resolved from GitHub, falling back to the CLI's version train offline) or the named one, installing it when missing; **bare `puddle upgrade` now upgrades everything installed on the target** (previously it meant the CLI alone), the CLI strictly last since npm replaces the running code; `upgrade cli` is a valid spelling again.
+- `puddle remove <cli|daemon|desktop> [user@host]` — confirmed removal, defaulting to no (`--yes` for scripts). Removing the daemon lists its version, the running sessions it interrupts, and its profiles first; it stops and unregisters the supervisor (systemd/launchd/nohup) and keeps `~/.puddle`'s data — profiles, session history, worktrees, credentials — unless separately confirmed (`--purge`), and before purging it sweeps worktrees for uncommitted or unpushed work and asks again when it finds any. cli removal requires a real npm global install; desktop removal deletes the closed macOS bundle and its staged-update cache.

package/README.md

@@ -54,11 +54,21 @@ Daemon-only installs (no CLI) use the `install.sh` attached to each release —
 curl -fsSL https://github.com/PerceptronV/puddle-code/releases/latest/download/install.sh | sh
 ```
 
+**Managing components:**
+
+The CLI installs, upgrades, and removes all three components — daemon, desktop app, and itself — with optional versions and SSH targets:
+
+```sh
+puddle upgrade                            # everything installed → the newest release
+puddle install daemon@v0.0.32 user@host   # pin a host's daemon to a version
+puddle remove daemon                      # uninstall; your data stays unless you --purge
+```
+
 **Desktop app (optional):**
 
 The same cockpit also ships as a standalone desktop app — identical UI and engine, plus a File → "Connect to SSH Host…" menu for remote hosts. Grab the dmg (macOS arm64) or AppImage (Linux x64) from the Releases page.
 
-On macOS, an installed Puddle CLI can install or update the desktop app directly: quit Puddle, then run `puddle upgrade desktop`. A fresh install goes to `/Applications` when writable, otherwise `~/Applications`.
+An installed Puddle CLI manages the desktop app directly: quit Puddle, then `puddle install desktop`, `puddle upgrade desktop`, or `puddle remove desktop`. On macOS a fresh install goes to `/Applications` when writable, otherwise `~/Applications`; on Linux `install desktop` asks where to put the AppImage (default `~/puddle`) and opens the folder — later updates happen from inside the app.
 
 The macOS downloads are **not code-signed** (an open-source project without Apple Developer Program fees), so Gatekeeper will refuse the first launch. Either allow it once — open the app, let macOS block it, then System Settings → Privacy & Security → **Open Anyway** — or clear the download quarantine in a terminal:
 
@@ -92,7 +102,7 @@ Building from source avoids the dance entirely (locally built apps are never qua
 
 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.
+Everything lives under `~/.puddle` on the host, installed without sudo — and `puddle remove daemon` takes it apart again.
 
 ## Development & teardown
 
@@ -115,19 +125,17 @@ systemctl --user disable --now puddled              # Linux (systemd user unit)
 kill "$(cat ~/.puddle/puddled.pid)"                 # nohup fallback (no supervisor)
 ```
 
-**Restore the production daemon.** When you're done testing, put the release build back over your dev one: stop the daemon (above), clear the installed binaries with `rm -rf ~/.puddle/bin` (your `~/.puddle` state — profiles, sessions, worktrees — is untouched), then run the production `puddle launch`, which refetches the daemon from GitHub Releases. (Clearing `bin` is what forces the refetch: the installer skips a version whose files are already present, so a dev build sharing the release's version number would otherwise stay put.)
-
-**Uninstall.** Removing the CLI alone leaves the daemon installed and running — a full teardown stops the daemon, then removes its state, its service file, and the production CLI:
+**Restore the production daemon.** When you're done testing, `puddle remove daemon` (answer no to the purge question — your profiles, sessions, and worktrees stay), then run the production `puddle launch`, which refetches the daemon from GitHub Releases. (Removal is what forces the refetch: the installer skips a version whose files are already present, so a dev build sharing the release's version number would otherwise stay put.)
 
-> ⚠️ `~/.puddle` **is** your local state — the SQLite database with every profile, account, and session (plus conversation history), the daemon's worktree tracking, and the auth token. Deleting it is irreversible and wipes all of it. Uninstall only when you mean to start clean.
+**Uninstall.** Removing the CLI alone leaves the daemon installed and running — a full teardown is:
 
 ```sh
-rm -rf ~/.puddle
-rm ~/Library/LaunchAgents/dev.puddle.puddled.plist                            # macOS
-rm ~/.config/systemd/user/puddled.service && systemctl --user daemon-reload   # Linux
-npm uninstall -g @puddle-code/cli
+puddle remove daemon --purge   # stops the daemon, unregisters its service, deletes ~/.puddle
+puddle remove cli              # npm uninstall -g, once the daemons you care about are gone
 ```
 
+> ⚠️ `~/.puddle` **is** your local state — the SQLite database with every profile, account, and session (plus conversation history), the daemon's worktree tracking, and the auth token. `--purge` deletes it irreversibly (the command lists dirty or unpushed worktrees and asks first); without it, `puddle remove daemon` keeps the data for a later reinstall.
+
 ## Licence
 
 Puddle is licensed under the [MIT License](LICENSE). Copyright (c) 2026 Yiding Song.