@puddle-code/cli 0.2.3 → 0.2.6

package/CHANGELOG.md

@@ -7,19 +7,8 @@ Past releases: see docs/changelogs/.
 
 # Changelog
 
-## [0.2.3] — 2026-09-21
-
-### Changed
-
-- Present connected browsers as shared compact cards, collapse them under a desktop settings disclosure, and place Delete registration beside the other registration actions.
-- Simplify Puddle Remote home to collapsible host/project groups, add its brand mark, compact the session rail, and hide revoked browsers in mobile and desktop settings.
-- Support long-press-and-drag text selection with a shared Copy action in mobile terminals and file content.
-- Compact the mobile workspace header, switch sessions from the shared title dropdown, follow desktop project/session ordering, and combine file navigation into one toolbar.
-- Replace the mobile keyboard button with an image picker that shares desktop image paste, inserts without submitting, and resizes large photos to fit remote request limits.
+## [0.2.6] — 2026-09-23
 
 ### Fixed
 
-- Fit five-letter project abbreviations in the mobile rail, match desktop gold controls, align the collapse button with both workspace toolbars, and distinguish the Files return action with a computer icon.
-- Prepare browser sign-in before the registration click so its tab opens directly on the machine displaying the UI, including desktop windows connected to SSH hosts.
-- Prefill mobile path browsing with the current directory or file and resolve both file and directory paths before navigating.
-- Keep mobile swipes inside terminal history and agent interfaces, preserve tap-to-type, and prevent terminal, file and session scrolling from moving the surrounding page.
+- Fix standalone CLI distribution checks on Linux and macOS by retaining gzip on the isolated PATH and invoking system utilities at their original paths.

package/README.md

@@ -20,7 +20,27 @@ Puddle manages parallel agents anywhere you SSH into, insulates agents in dedica
 
 ## Quick start
 
-**On your local machine where you will be using the GUI, run:**
+**On your local machine where you will be using the GUI:**
+
+For a standalone installation without Node.js or npm, use your deployed app's
+installer (replace the example host):
+
+```sh
+curl -fsSL https://app.example.com/install.sh | sh
+```
+
+This installs the CLI under `~/.local/share/puddle/cli` and its launcher at
+`~/.local/bin/puddle`. Add `~/.local/bin` to your `PATH` if the installer asks.
+The standalone releases support Linux x64/arm64 and macOS arm64. The script and
+checksum-verified archives are also attached to this repository's GitHub Releases.
+An optional `--version` selects a release; `--prefix` and `--bin-dir` select the
+installation and launcher directories:
+
+```sh
+curl -fsSL https://app.example.com/install.sh | sh -s -- --version X.Y.Z
+```
+
+Alternatively, with Node.js already installed, use npm:
 
 ```sh
 npm install -g @puddle-code/cli
@@ -56,13 +76,11 @@ detached processes, Puddle instead keeps the daemon attached to the cockpit; clo
 live processes. The next `puddle launch` restarts the daemon from the host's persistent state and,
 when auto-resume is enabled (the default), restores the interrupted sessions.
 
-**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
-```
+The [deployed app](docs/mobile-access.md#host-the-installer) serves `/install.sh`
+as the single public installer. Install daemon and desktop components through
+`puddle install daemon [user@host]` and `puddle install desktop`. A first
+`puddle launch user@host` still installs a missing daemon automatically from
+GitHub Releases.
 
 **Managing components:**
 
@@ -76,21 +94,13 @@ puddle remove daemon                      # uninstall; your data stays unless yo
 
 **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.
+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. Install it with `puddle install desktop` (macOS arm64 or Linux x64). Once installed, it runs independently of the CLI.
 
 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:
-
-```sh
-xattr -dr com.apple.quarantine /Applications/Puddle.app
-```
-
-Building from source avoids the dance entirely (locally built apps are never quarantined): `pnpm build && pnpm --filter @puddle/desktop dist`.
-
 **Host requirements**: Linux with glibc 2.28+ (Ubuntu 20.04+, Debian 11+, RHEL/Rocky 8+;
 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
+`PATH`. Standalone CLI installs include Node and require no npm; npm installs require Node 22+. 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
@@ -113,7 +123,7 @@ auth prompts unless you use a key).
                                         └───────────────────────────────────┘
 ```
 
-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. Short-lived host connection leases, separate browser authorisation and exact cockpit Host/Origin checks guard local access. Launch invitations are single-use; browser login survives cockpit restarts, while forwarded applications use a separate loopback origin. After upgrading from the old token flow, run `puddle launch` once to authorise existing tabs.
+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 (`puddle upgrade cli` refreshes the cockpit for every host); the daemon only has to update when the versioned protocol breaks, and the launcher asks for approval before updating it. The prompt shows the host, both protocols and how many live sessions the restart interrupts; declining leaves the daemon running. `--no-upgrade` refuses before prompting, and non-interactive launches require an explicit `puddle upgrade daemon [user@host]` first. Short-lived host connection leases, separate browser authorisation and exact cockpit Host/Origin checks guard local access. Launch invitations are single-use; browser login survives cockpit restarts, while forwarded applications use a separate loopback origin. After upgrading from the old token flow, run `puddle launch` once to authorise existing tabs.
 
 Everything lives under `~/.puddle` on the host, installed without sudo — and `puddle remove daemon` takes it apart again.
 
@@ -121,14 +131,14 @@ Everything lives under `~/.puddle` on the host, installed without sudo — and `
 
 **One daemon, many clients.** There is a single local daemon per machine, living under `~/.puddle` and run by one supervised service (launchd's `dev.puddle.puddled` on macOS, systemd's `puddled` on Linux). The global `puddle` and a repo-run `node packages/cli/dist/index.js` are **both just clients** that talk to — and, when needed, install — that same daemon. They never run side by side, and there is no separate "dev daemon" alongside a "production daemon".
 
-**Dev build vs. production.** `npm i -g @puddle-code/cli` is the production path — its `puddle` fetches and upgrades the daemon from this repo's GitHub Releases. To exercise uncommitted changes, build and run from the repo:
+**Dev build vs. production.** The standalone installer or `npm i -g @puddle-code/cli` is the production path — its `puddle` fetches and upgrades the daemon from this repo's GitHub Releases. To exercise uncommitted changes, build and run from the repo:
 
 ```sh
 pnpm build && pnpm build:tarball
-node packages/cli/dist/index.js start --tarball dist-release/puddled-v*.tar.gz --foreground
+node packages/cli/dist/index.js launch --tarball dist-release/puddled-v*.tar.gz --foreground
 ```
 
-`--tarball` sets the install _source_ only, and is consulted **only when the CLI actually installs the daemon** — when none is running, the daemon is stopped, or a protocol-major upgrade fires. If a compatible daemon (same protocol major) is already up, `start` just serves the cockpit against it and **the tarball is ignored** (even a newer app version — nothing compares app versions). So to load a fresh dev build over a running daemon you must **stop it first** (see _Kill_ below), then re-run `start --tarball …`. `--foreground` keeps the cockpit attached (`connect <user>@<host> --tarball …` is the remote form). Both clients share one `~/.puddle` daemon and cockpit registry, so `puddle list` / `puddle kill` see either — don't point both at the same host at once. (Never launch the daemon from inside a coding-agent shell: it inherits the agent's env and breaks conversation resume — use a plain terminal.)
+`--tarball` sets the install _source_ only, and is consulted **only when the CLI actually installs the daemon** — when none is running, the daemon is stopped, or a protocol-major upgrade fires. If a compatible daemon (same protocol major) is already up, `launch` just serves the cockpit against it and **the tarball is ignored** (even a newer app version — nothing compares app versions). So to load a fresh dev build over a running daemon you must **stop it first** (see _Kill_ below), then re-run `launch --tarball …`. `--foreground` keeps the cockpit attached (`launch <user>@<host> --tarball …` is the remote form). Both clients share one `~/.puddle` daemon and cockpit registry, so `puddle list` / `puddle kill` see either — don't point both at the same host at once. (Never launch the daemon from inside a coding-agent shell: it inherits the agent's env and breaks conversation resume — use a plain terminal.)
 
 **Kill.** `puddle kill --all` (or Ctrl-C in a `--foreground` run) normally stops the local cockpit
 UI only; a supervised daemon and its sessions keep running. When launch reported that it is keeping
@@ -150,7 +160,7 @@ kill "$(cat ~/.puddle/puddled.pid)"                 # nohup fallback (no supervi
 
 ```sh
 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 remove cli              # standalone or npm removal, using its installation channel
 ```
 
 > ⚠️ `~/.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.

package/dist/host-control.mjs

@@ -14539,6 +14539,8 @@ var profileId = external_exports.string().regex(/^[0-9a-f]{10}$/);
 // ../shared/src/api/version.ts
 var versionResponseSchema = external_exports.object({
   version: external_exports.string(),
+  /** Added by the host connector; absent on direct daemon responses and older connectors. */
+  remote_image_uploads: external_exports.boolean().optional(),
   protocol: external_exports.object({
     major: external_exports.number().int().nonnegative(),
     minor: external_exports.number().int().nonnegative()
@@ -15466,6 +15468,11 @@ var fileResponseSchema = external_exports.object({
   size: external_exports.number().int().nonnegative(),
   mtime_ms: external_exports.number()
 });
+var MAX_PREVIEW_ASSET_BYTES = 8 * 1024 * 1024;
+var previewAssetResponseSchema = external_exports.object({
+  mime: external_exports.string().min(1).max(128),
+  data: external_exports.string().max(4 * Math.ceil(MAX_PREVIEW_ASSET_BYTES / 3))
+});
 var putFileRequestSchema = external_exports.object({
   content: external_exports.string(),
   /** Optimistic-concurrency guard: reject the write if the file changed since this mtime. */
@@ -15994,6 +16001,36 @@ var browserAuthorityStateSchema = external_exports.object({
   proxies: external_exports.array(proxyRecordSchema)
 });
 
+// ../shared/src/remote/image-upload.ts
+var IMAGE_UPLOAD_POLICY = {
+  imageBytes: 4 * 1024 * 1024,
+  chunkBytes: 64 * 1024,
+  idleMs: 6e4,
+  lifetimeMs: 5 * 6e4
+};
+var imageUploadRequestSchema = external_exports.discriminatedUnion("action", [
+  external_exports.object({
+    action: external_exports.literal("start"),
+    upload: external_exports.string().uuid(),
+    mime: pasteImageMimeSchema,
+    size: external_exports.number().int().positive().max(IMAGE_UPLOAD_POLICY.imageBytes)
+  }).strict(),
+  external_exports.object({
+    action: external_exports.literal("chunk"),
+    upload: external_exports.string().uuid(),
+    offset: external_exports.number().int().nonnegative().max(IMAGE_UPLOAD_POLICY.imageBytes),
+    data: external_exports.string().min(4).max(4 * Math.ceil(IMAGE_UPLOAD_POLICY.chunkBytes / 3)).regex(/^[A-Za-z0-9+/]+={0,2}$/).refine((data) => {
+      const padding = data.endsWith("==") ? 2 : data.endsWith("=") ? 1 : 0;
+      return data.length % 4 === 0 && data.length / 4 * 3 - padding <= IMAGE_UPLOAD_POLICY.chunkBytes;
+    }, "Image chunk is too large or malformed")
+  }).strict(),
+  external_exports.object({ action: external_exports.literal("finish"), upload: external_exports.string().uuid() }).strict(),
+  external_exports.object({ action: external_exports.literal("cancel"), upload: external_exports.string().uuid() }).strict()
+]);
+var imageUploadProgressSchema = external_exports.object({
+  received: external_exports.number().int().nonnegative().max(IMAGE_UPLOAD_POLICY.imageBytes)
+});
+
 // ../shared/src/remote/service.ts
 var remoteHostSchema = external_exports.object({
   id: remoteIdSchema,
@@ -16018,6 +16055,7 @@ var remoteLoginStateSchema = external_exports.object({
 var registerHostRequestSchema = external_exports.object({ label: remoteLabelSchema }).strict();
 var registrationResponseSchema = external_exports.object({ host: remoteIdSchema, code: remoteSecretSchema, expires: external_exports.number() }).strict();
 var redeemRegistrationSchema = external_exports.object({ code: remoteSecretSchema }).strict();
+var unregisterHostRequestSchema = external_exports.object({ credential: remoteSecretSchema }).strict();
 var desktopRegistrationSchema = external_exports.object({
   challenge: remoteSecretSchema,
   label: remoteLabelSchema,
@@ -16203,7 +16241,7 @@ async function inspectLegacyHost(home) {
   };
   try {
     const version2 = versionResponseSchema.parse(await get("/api/version"));
-    const sessions = sessionSchema.array().parse(await get("/api/sessions"));
+    const sessions = sessionSchema.pick({ status: true }).array().parse(await get("/api/sessions"));
     return hostInspectionSchema.parse({
       t: "inspection",
       port,
@@ -16248,7 +16286,7 @@ async function inspectHostLocally(home) {
       signal: AbortSignal.timeout(3e3)
     });
     if (!response.ok) throw new Error("Host inspection rejected");
-    const sessions = sessionSchema.array().parse(await response.json());
+    const sessions = sessionSchema.pick({ status: true }).array().parse(await response.json());
     return hostInspectionSchema.parse({
       t: "inspection",
       port: grant.port,