@puddle-code/cli 0.0.13 → 0.0.14

package/dist/index.js

@@ -2307,8 +2307,8 @@ var require_websocket = __commonJS({
     var http = __require("http");
     var net = __require("net");
     var tls = __require("tls");
-    var { randomBytes, createHash } = __require("crypto");
-    var { Duplex, Readable } = __require("stream");
+    var { randomBytes, createHash: createHash2 } = __require("crypto");
+    var { Duplex, Readable: Readable2 } = __require("stream");
     var { URL: URL2 } = __require("url");
     var PerMessageDeflate2 = require_permessage_deflate();
     var Receiver2 = require_receiver();
@@ -2975,7 +2975,7 @@ var require_websocket = __commonJS({
           abortHandshake(websocket, socket, "Invalid Upgrade header");
           return;
         }
-        const digest = createHash("sha1").update(key + GUID).digest("base64");
+        const digest = createHash2("sha1").update(key + GUID).digest("base64");
         if (res.headers["sec-websocket-accept"] !== digest) {
           abortHandshake(websocket, socket, "Invalid Sec-WebSocket-Accept header");
           return;
@@ -3344,7 +3344,7 @@ var require_websocket_server = __commonJS({
     var EventEmitter = __require("events");
     var http = __require("http");
     var { Duplex } = __require("stream");
-    var { createHash } = __require("crypto");
+    var { createHash: createHash2 } = __require("crypto");
     var extension2 = require_extension();
     var PerMessageDeflate2 = require_permessage_deflate();
     var subprotocol2 = require_subprotocol();
@@ -3651,7 +3651,7 @@ var require_websocket_server = __commonJS({
           );
         }
         if (this._state > RUNNING) return abortHandshake(socket, 503);
-        const digest = createHash("sha1").update(key + GUID).digest("base64");
+        const digest = createHash2("sha1").update(key + GUID).digest("base64");
         const headers = [
           "HTTP/1.1 101 Switching Protocols",
           "Upgrade: websocket",
@@ -3908,10 +3908,8 @@ init_types();
 var USAGE = `puddle \u2014 self-hosted orchestrator for CLI coding agents
 
 usage:
-  puddle start   [--port <p>] [--foreground] [--no-browser] [--no-upgrade]
-                 [--tarball <path>]
-  puddle connect user@host [--port <local>] [--remote-port <p>] [--foreground]
-                 [--no-browser] [--no-upgrade] [--tarball <path>]
+  puddle launch  [local | user@host] [--port <p>] [--remote-port <p>]
+                 [--foreground] [--no-browser] [--no-upgrade] [--tarball <path>]
   puddle refresh [local | user@host] [--port <p>] [--remote-port <p>]
                  [--foreground] [--no-browser] [--no-upgrade] [--tarball <path>]
   puddle list
@@ -3919,17 +3917,18 @@ usage:
   puddle status  [user@host]
   puddle attach  [user@host] <session> [--term <id>]
   puddle logs    [user@host] [session] [--term <id>] [-f|--follow]
-  puddle upgrade [user@host]
+  puddle upgrade <cli | daemon | desktop> [user@host]
   puddle --version | --help
 
-start serves the cockpit at http://localhost:7433 against the daemon on this
-machine (installing it under ~/.puddle if needed); connect does the same for
-an SSH host through one tunnel. Both keep running in the background once
-ready, so the terminal may close (--foreground to stay attached; Ctrl-C then
-stops the cockpit). refresh stops a target's cockpit (even a wedged one) and
-runs the full start/connect flow again \u2014 tunnel, daemon restart if needed \u2014
-keeping the old UI port so open tabs survive. list shows running cockpits;
-kill stops one \u2014 sessions keep running on the host either way.`;
+launch serves the cockpit at http://localhost:7433 against the daemon on this
+machine when no host (or 'local') is given \u2014 installing it under ~/.puddle if
+needed \u2014 and does the same for an SSH host through one tunnel. It keeps
+running in the background once ready, so the terminal may close (--foreground
+to stay attached; Ctrl-C then stops the cockpit). refresh stops a target's
+cockpit (even a wedged one) and runs the full launch flow again \u2014 tunnel,
+daemon restart if needed \u2014 keeping the old UI port so open tabs survive.
+list shows running cockpits; kill stops one \u2014 sessions keep running on the
+host either way.`;
 function parseArgs(argv) {
   const [cmd, ...rest] = argv;
   if (cmd === void 0 || cmd === "help" || cmd === "--help" || cmd === "-h")
@@ -3977,40 +3976,10 @@ function parseArgs(argv) {
     }
   };
   switch (cmd) {
-    case "start": {
-      if (positionals.length > 0) {
-        throw new CliError(
-          "bad_arguments",
-          `start takes no positional arguments (got '${positionals[0]}')`
-        );
-      }
-      const port = intFlag("--port");
-      const preferPort = intFlag("--prefer-port");
-      const tarball = strFlag("--tarball");
-      expect(
-        "--port",
-        "--prefer-port",
-        "--no-browser",
-        "--no-upgrade",
-        "--tarball",
-        "--foreground"
-      );
-      return {
-        cmd: "start",
-        ...port !== void 0 ? { port } : {},
-        ...preferPort !== void 0 ? { preferPort } : {},
-        ...tarball !== void 0 ? { tarball } : {},
-        noBrowser: flags.has("--no-browser"),
-        noUpgrade: flags.has("--no-upgrade"),
-        foreground: flags.has("--foreground")
-      };
-    }
-    case "connect": {
-      const host = positionals[0];
-      if (host === void 0)
-        throw new CliError("bad_arguments", "connect needs a host: puddle connect user@host");
+    case "launch": {
       if (positionals.length > 1)
-        throw new CliError("bad_arguments", "connect takes exactly one host");
+        throw new CliError("bad_arguments", "launch takes at most one target");
+      const target = positionals[0] ?? "local";
       const port = intFlag("--port");
       const preferPort = intFlag("--prefer-port");
       const remotePort = intFlag("--remote-port");
@@ -4024,9 +3993,12 @@ function parseArgs(argv) {
         "--tarball",
         "--foreground"
       );
+      if (target === "local" && remotePort !== void 0) {
+        throw new CliError("bad_arguments", "--remote-port only applies to an SSH target");
+      }
       return {
-        cmd: "connect",
-        host,
+        cmd: "launch",
+        target,
         ...port !== void 0 ? { port } : {},
         ...preferPort !== void 0 ? { preferPort } : {},
         ...remotePort !== void 0 ? { remotePort } : {},
@@ -4036,6 +4008,14 @@ function parseArgs(argv) {
         foreground: flags.has("--foreground")
       };
     }
+    // The pre-unification verbs, kept only to say what replaced them.
+    case "start":
+      throw new CliError("bad_arguments", `'start' is now: puddle launch`);
+    case "connect":
+      throw new CliError(
+        "bad_arguments",
+        `'connect' is now: puddle launch ${positionals[0] ?? "user@host"}`
+      );
     case "refresh": {
       if (positionals.length > 1)
         throw new CliError("bad_arguments", "refresh takes at most one target");
@@ -4120,24 +4100,29 @@ function parseArgs(argv) {
       return first.includes("@") ? { cmd: "logs", host: first, follow, ...term !== void 0 ? { term } : {} } : { cmd: "logs", session: first, follow, ...term !== void 0 ? { term } : {} };
     }
     case "upgrade": {
-      if (positionals.length > 1)
-        throw new CliError("bad_arguments", "upgrade takes at most a host");
+      const [what, host, extra] = positionals;
+      if (what !== "cli" && what !== "daemon" && what !== "desktop") {
+        throw new CliError(
+          "bad_arguments",
+          "upgrade needs a subject: puddle upgrade <cli | daemon | desktop> [user@host]",
+          what !== void 0 && what.includes("@") ? `to upgrade the daemon on ${what}: puddle upgrade daemon ${what}` : void 0
+        );
+      }
+      if (extra !== void 0)
+        throw new CliError("bad_arguments", "upgrade takes at most a subject + host");
       expect();
-      const host = positionals[0];
-      return { cmd: "upgrade", ...host !== void 0 ? { host } : {} };
+      return { cmd: "upgrade", what, ...host !== void 0 ? { host } : {} };
     }
     default:
       throw new CliError("bad_arguments", `unknown command '${cmd}'`, "see: puddle --help");
   }
 }
 function argvFor(command) {
-  const argv = [command.cmd];
-  if (command.cmd === "connect") argv.push(command.host);
+  const argv = ["launch"];
+  if (command.target !== "local") argv.push(command.target);
   if (command.port !== void 0) argv.push("--port", String(command.port));
   if (command.preferPort !== void 0) argv.push("--prefer-port", String(command.preferPort));
-  if (command.cmd === "connect" && command.remotePort !== void 0) {
-    argv.push("--remote-port", String(command.remotePort));
-  }
+  if (command.remotePort !== void 0) argv.push("--remote-port", String(command.remotePort));
   if (command.tarball !== void 0) argv.push("--tarball", command.tarball);
   if (command.noBrowser) argv.push("--no-browser");
   if (command.noUpgrade) argv.push("--no-upgrade");
@@ -4147,16 +4132,288 @@ function argvFor(command) {
 
 // src/cli/run.ts
 init_attach();
+import { spawn as spawn7 } from "node:child_process";
 import { existsSync as existsSync3 } from "node:fs";
-import { dirname as dirname6, join as join8 } from "node:path";
+import { dirname as dirname6, join as join9 } from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 
-// src/lib/browser.ts
+// src/lib/desktop-update.ts
+import { createHash } from "node:crypto";
 import { spawn } from "node:child_process";
+import { createReadStream, createWriteStream } from "node:fs";
+import { chmod, mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import { join as join3 } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+
+// src/lib/paths.ts
+import { homedir } from "node:os";
+import { join } from "node:path";
+function clientHome(env = process.env) {
+  return env.PUDDLE_HOME ?? join(homedir(), ".puddle");
+}
+var HOST_HOME = '"${PUDDLE_HOME:-$HOME/.puddle}"';
+var hostPaths = {
+  home: HOST_HOME,
+  token: `${HOST_HOME}/token`,
+  config: `${HOST_HOME}/config.json`,
+  runtime: `${HOST_HOME}/runtime.json`,
+  current: `${HOST_HOME}/bin/current`,
+  cache: `${HOST_HOME}/cache`,
+  logs: `${HOST_HOME}/logs`
+};
+
+// src/lib/desktop-update.ts
+init_types();
+
+// src/lib/version.ts
+import { readFileSync } from "node:fs";
+import { dirname, join as join2 } from "node:path";
+import { fileURLToPath } from "node:url";
+function cliVersion() {
+  if (true) return "0.0.14";
+  const here = dirname(fileURLToPath(import.meta.url));
+  for (const candidate of [
+    join2(here, "..", "..", "package.json"),
+    join2(here, "..", "package.json")
+  ]) {
+    try {
+      const pkg = JSON.parse(readFileSync(candidate, "utf8"));
+      if (pkg.version !== void 0) return pkg.version;
+    } catch {
+    }
+  }
+  return "0.0.0";
+}
+function pinnedDaemonVersion() {
+  return cliVersion();
+}
+function repoSlug(env = process.env) {
+  if (env.PUDDLE_REPO !== void 0 && env.PUDDLE_REPO !== "") return env.PUDDLE_REPO;
+  if (true) return "PerceptronV/puddle-code";
+  return void 0;
+}
+
+// src/lib/desktop-update.ts
+function isNewerVersion(candidate, current) {
+  const parse3 = (v) => {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(v.trim());
+    return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+  };
+  const a = parse3(candidate);
+  const b = parse3(current);
+  if (a === null || b === null) return false;
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return a[i] > b[i];
+  }
+  return false;
+}
+function pickDesktopAsset(assets, platform, arch) {
+  const suffix = platform === "darwin" ? "-mac.zip" : platform === "linux" ? ".AppImage" : null;
+  if (suffix === null) return null;
+  return assets.find(
+    (a) => a.name.endsWith(suffix) && a.name.includes("-arm64") === (arch === "arm64")
+  ) ?? null;
+}
+function parseSums(text) {
+  const sums = /* @__PURE__ */ new Map();
+  for (const line of text.split("\n")) {
+    const match = /^([0-9a-f]{64})\s+\*?(.+?)\s*$/.exec(line.trim());
+    if (match) sums.set(match[2], match[1]);
+  }
+  return sums;
+}
+async function checkForDesktopUpdate(currentVersion, opts = {}) {
+  const slug2 = repoSlug();
+  if (slug2 === void 0) return null;
+  const fetchFn = opts.fetchFn ?? fetch;
+  const response = await fetchFn(`https://api.github.com/repos/${slug2}/releases/latest`, {
+    headers: { accept: "application/vnd.github+json", "user-agent": "puddle-desktop" }
+  });
+  if (!response.ok) {
+    throw new CliError("not_installed", `release lookup failed (HTTP ${response.status})`);
+  }
+  const release = await response.json();
+  const version2 = (release.tag_name ?? "").replace(/^v/, "");
+  if (!isNewerVersion(version2, currentVersion)) return null;
+  const assets = release.assets ?? [];
+  const asset = pickDesktopAsset(
+    assets,
+    opts.platform ?? process.platform,
+    opts.arch ?? process.arch
+  );
+  const sums = assets.find((a) => a.name === "SHA256SUMS");
+  if (asset === null || sums === void 0) return null;
+  return {
+    version: version2,
+    asset: { name: asset.name, url: asset.browser_download_url },
+    sumsUrl: sums.browser_download_url
+  };
+}
+async function stageDesktopUpdate(update, opts = {}) {
+  const logger = opts.logger ?? silentLogger;
+  const fetchFn = opts.fetchFn ?? fetch;
+  const dir = join3(opts.cacheDir ?? join3(clientHome(), "cache", "desktop"), update.version);
+  await rm(dir, { recursive: true, force: true });
+  await mkdir(dir, { recursive: true });
+  try {
+    logger.info(`downloading ${update.asset.name}`);
+    const archive = join3(dir, update.asset.name);
+    const response = await fetchFn(update.asset.url, {
+      headers: { "user-agent": "puddle-desktop" }
+    });
+    if (!response.ok || response.body === null) {
+      throw new CliError("not_installed", `download failed (HTTP ${response.status})`);
+    }
+    await pipeline(
+      Readable.fromWeb(response.body),
+      createWriteStream(archive)
+    );
+    const sumsResponse = await fetchFn(update.sumsUrl, {
+      headers: { "user-agent": "puddle-desktop" }
+    });
+    if (!sumsResponse.ok) {
+      throw new CliError("not_installed", `SHA256SUMS fetch failed (HTTP ${sumsResponse.status})`);
+    }
+    const expected = parseSums(await sumsResponse.text()).get(update.asset.name);
+    if (expected === void 0) {
+      throw new CliError("not_installed", `${update.asset.name} is not in SHA256SUMS`);
+    }
+    const actual = await fileSha256(archive);
+    if (actual !== expected) {
+      throw new CliError(
+        "not_installed",
+        `checksum mismatch for ${update.asset.name}`,
+        `expected ${expected}, got ${actual}`
+      );
+    }
+    if (update.asset.name.endsWith(".zip")) {
+      const extractDir = join3(dir, "extract");
+      await run("/usr/bin/ditto", ["-x", "-k", archive, extractDir]);
+      const bundle = (await readdir(extractDir)).find((name) => name.endsWith(".app"));
+      if (bundle === void 0) {
+        throw new CliError("not_installed", "the update zip contains no .app bundle");
+      }
+      logger.info(`staged ${update.version} at ${join3(extractDir, bundle)}`);
+      return {
+        version: update.version,
+        kind: "mac-app",
+        stagedPath: join3(extractDir, bundle),
+        dir
+      };
+    }
+    await chmod(archive, 493);
+    logger.info(`staged ${update.version} at ${archive}`);
+    return { version: update.version, kind: "appimage", stagedPath: archive, dir };
+  } catch (e) {
+    await rm(dir, { recursive: true, force: true });
+    throw e;
+  }
+}
+async function applyDesktopUpdate(staged, opts) {
+  const logger = opts.logger ?? silentLogger;
+  const script = swapScript(staged, opts);
+  const scriptPath = join3(staged.dir, "apply.sh");
+  await writeFile(scriptPath, script, { mode: 493 });
+  logger.info(`applying ${staged.version} via ${scriptPath}`);
+  if (opts.detach ?? true) {
+    const child = spawn("/bin/sh", [scriptPath], { detached: true, stdio: "ignore" });
+    child.unref();
+    return;
+  }
+  await run("/bin/sh", [scriptPath]);
+}
+var q = (s) => `'${s.replaceAll("'", `'\\''`)}'`;
+function swapScript(staged, opts) {
+  const wait = opts.waitPid === void 0 ? [] : [
+    `i=0`,
+    `while kill -0 ${opts.waitPid} 2>/dev/null; do`,
+    `  i=$((i+1)); [ "$i" -gt 600 ] && exit 1`,
+    `  sleep 0.1`,
+    `done`
+  ];
+  if (staged.kind === "mac-app") {
+    return [
+      `#!/bin/sh`,
+      `# puddle desktop update ${staged.version} \u2014 swap once the app exits`,
+      ...wait,
+      `target=${q(opts.targetPath)}`,
+      `staged=${q(staged.stagedPath)}`,
+      `rm -rf "$target.old"`,
+      `mv "$target" "$target.old" || exit 1`,
+      `if mv "$staged" "$target" 2>/dev/null || /usr/bin/ditto "$staged" "$target"; then`,
+      // Defence in depth: the normal path never quarantines (node's fetch is
+      // not a quarantine-opted-in app, and ditto only propagates what the
+      // zip already carries), but if the bundle ever acquires the attribute
+      // the swap must not resurrect the Gatekeeper prompt.
+      `  /usr/bin/xattr -dr com.apple.quarantine "$target" 2>/dev/null`,
+      `  rm -rf "$target.old" ${q(staged.dir)}`,
+      ...opts.relaunch ? [`  open "$target"`] : [],
+      `else`,
+      `  mv "$target.old" "$target"`,
+      `  exit 1`,
+      `fi`,
+      ``
+    ].join("\n");
+  }
+  return [
+    `#!/bin/sh`,
+    `# puddle desktop update ${staged.version} \u2014 swap once the app exits`,
+    ...wait,
+    `target=${q(opts.targetPath)}`,
+    `cp -f ${q(staged.stagedPath)} "$target" || exit 1`,
+    `chmod +x "$target"`,
+    `rm -rf ${q(staged.dir)}`,
+    ...opts.relaunch ? [`"$target" >/dev/null 2>&1 &`] : [],
+    ``
+  ].join("\n");
+}
+async function findInstalledDesktopApp() {
+  if (process.platform !== "darwin") return null;
+  const { readFile } = await import("node:fs/promises");
+  const { homedir: homedir2 } = await import("node:os");
+  for (const appPath of ["/Applications/Puddle.app", join3(homedir2(), "Applications/Puddle.app")]) {
+    try {
+      const plist = await readFile(join3(appPath, "Contents/Info.plist"), "utf8");
+      const match = /<key>CFBundleShortVersionString<\/key>\s*<string>([^<]+)<\/string>/.exec(
+        plist
+      );
+      if (match) return { appPath, version: match[1] };
+    } catch {
+    }
+  }
+  return null;
+}
+function isDesktopAppRunning(appPath) {
+  return new Promise((resolve3) => {
+    const child = spawn("/usr/bin/pgrep", ["-f", `${appPath}/Contents/MacOS/`], {
+      stdio: "ignore"
+    });
+    child.on("error", () => resolve3(false));
+    child.on("exit", (code) => resolve3(code === 0));
+  });
+}
+function fileSha256(path) {
+  const hash2 = createHash("sha256");
+  return pipeline(createReadStream(path), hash2).then(() => hash2.digest("hex"));
+}
+function run(command, args) {
+  return new Promise((resolve3, reject) => {
+    const child = spawn(command, args, { stdio: "ignore" });
+    child.on("error", reject);
+    child.on(
+      "exit",
+      (code) => code === 0 ? resolve3() : reject(new CliError("not_installed", `${command} exited with ${code ?? "signal"}`))
+    );
+  });
+}
+
+// src/lib/browser.ts
+import { spawn as spawn2 } from "node:child_process";
 function openBrowser(url2, platform = process.platform) {
   const command = platform === "darwin" ? { bin: "open", args: [url2] } : platform === "win32" ? { bin: "cmd", args: ["/c", "start", "", url2] } : { bin: "xdg-open", args: [url2] };
   try {
-    const child = spawn(command.bin, command.args, { stdio: "ignore", detached: true });
+    const child = spawn2(command.bin, command.args, { stdio: "ignore", detached: true });
     child.on("error", () => {
     });
     child.unref();
@@ -4167,7 +4424,7 @@ function openBrowser(url2, platform = process.platform) {
 }
 
 // src/lib/connect.ts
-import { join as join5 } from "node:path";
+import { join as join6 } from "node:path";
 
 // ../shared/src/protocol.ts
 var PROTOCOL_VERSION = { major: 10, minor: 1 };
@@ -19537,23 +19794,6 @@ function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
 
-// src/lib/paths.ts
-import { homedir } from "node:os";
-import { join } from "node:path";
-function clientHome(env = process.env) {
-  return env.PUDDLE_HOME ?? join(homedir(), ".puddle");
-}
-var HOST_HOME = '"${PUDDLE_HOME:-$HOME/.puddle}"';
-var hostPaths = {
-  home: HOST_HOME,
-  token: `${HOST_HOME}/token`,
-  config: `${HOST_HOME}/config.json`,
-  runtime: `${HOST_HOME}/runtime.json`,
-  current: `${HOST_HOME}/bin/current`,
-  cache: `${HOST_HOME}/cache`,
-  logs: `${HOST_HOME}/logs`
-};
-
 // src/lib/daemon-client.ts
 init_types();
 var LIVE = /* @__PURE__ */ new Set(["starting", "running", "waiting_input"]);
@@ -19652,39 +19892,9 @@ async function waitForToken(transport, timeoutMs) {
 
 // src/lib/bootstrap.ts
 import { existsSync, readFileSync as readFileSync2 } from "node:fs";
-import { dirname as dirname2, join as join3, resolve } from "node:path";
+import { dirname as dirname2, join as join4, resolve } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 init_types();
-
-// src/lib/version.ts
-import { readFileSync } from "node:fs";
-import { dirname, join as join2 } from "node:path";
-import { fileURLToPath } from "node:url";
-function cliVersion() {
-  if (true) return "0.0.13";
-  const here = dirname(fileURLToPath(import.meta.url));
-  for (const candidate of [
-    join2(here, "..", "..", "package.json"),
-    join2(here, "..", "package.json")
-  ]) {
-    try {
-      const pkg = JSON.parse(readFileSync(candidate, "utf8"));
-      if (pkg.version !== void 0) return pkg.version;
-    } catch {
-    }
-  }
-  return "0.0.0";
-}
-function pinnedDaemonVersion() {
-  return cliVersion();
-}
-function repoSlug(env = process.env) {
-  if (env.PUDDLE_REPO !== void 0 && env.PUDDLE_REPO !== "") return env.PUDDLE_REPO;
-  if (true) return "PerceptronV/puddle-code";
-  return void 0;
-}
-
-// src/lib/bootstrap.ts
 async function installedVersion(transport) {
   const result = await transport.exec(`readlink ${hostPaths.current}`, { timeoutMs: 15e3 });
   if (result.code !== 0) return null;
@@ -19754,9 +19964,9 @@ function lastLines(text, count = 3) {
 function readInstallScript() {
   const here = dirname2(fileURLToPath2(import.meta.url));
   const candidates = [
-    join3(here, "install.sh"),
+    join4(here, "install.sh"),
     // dist/index.js → dist/install.sh
-    join3(here, "..", "..", "..", "..", "scripts", "install.sh")
+    join4(here, "..", "..", "..", "..", "scripts", "install.sh")
     // src/lib/ → repo root
   ];
   for (const candidate of candidates) {
@@ -20004,8 +20214,8 @@ function recoverProxiedPath(referer, requestUrl) {
 }
 
 // src/lib/serve/static.ts
-import { createReadStream, existsSync as existsSync2, statSync } from "node:fs";
-import { extname, join as join4, normalize, resolve as resolve2, sep } from "node:path";
+import { createReadStream as createReadStream2, existsSync as existsSync2, statSync } from "node:fs";
+import { extname, join as join5, normalize, resolve as resolve2, sep } from "node:path";
 var MIME = {
   ".html": "text/html; charset=utf-8",
   ".js": "text/javascript; charset=utf-8",
@@ -20033,14 +20243,14 @@ function createStaticHandler(rootDir) {
       res.writeHead(404, { "content-type": "text/plain" }).end("not found");
       return;
     }
-    const requested = normalize(join4(root, decoded));
+    const requested = normalize(join5(root, decoded));
     const candidate = requested.startsWith(root + sep) || requested === root ? requested : root;
     const isFile = existsSync2(candidate) && statSync(candidate).isFile();
     if (!isFile && extname(pathname) !== "") {
       res.writeHead(404, { "content-type": "text/plain" }).end("not found");
       return;
     }
-    const file2 = isFile ? candidate : join4(root, "index.html");
+    const file2 = isFile ? candidate : join5(root, "index.html");
     if (!existsSync2(file2)) {
       res.writeHead(404, { "content-type": "text/plain" }).end("not found");
       return;
@@ -20053,7 +20263,7 @@ function createStaticHandler(rootDir) {
       res.end();
       return;
     }
-    createReadStream(file2).pipe(res);
+    createReadStream2(file2).pipe(res);
   };
 }
 
@@ -20318,7 +20528,7 @@ async function listen(server, startPort, strict, avoidPort) {
 }
 
 // src/lib/tunnel.ts
-import { spawn as spawn2 } from "node:child_process";
+import { spawn as spawn3 } from "node:child_process";
 init_types();
 var RECONNECT_INITIAL_MS = 500;
 var RECONNECT_MAX_MS = 1e4;
@@ -20342,7 +20552,7 @@ async function openTunnel(ssh, remotePort, opts = {}) {
   let healthTimer = null;
   const spawnForward = async (port) => {
     if (stopping) return false;
-    const child = spawn2(
+    const child = spawn3(
       sshBinary,
       ssh.args("-N", "-L", `${port}:127.0.0.1:${remotePort}`, ssh.host),
       { stdio: ["ignore", "ignore", "inherit"] }
@@ -20465,7 +20675,7 @@ async function openTunnel(ssh, remotePort, opts = {}) {
 }
 
 // src/lib/transport/local.ts
-import { spawn as spawn3 } from "node:child_process";
+import { spawn as spawn4 } from "node:child_process";
 import { copyFileSync, mkdirSync as mkdirSync2, readFileSync as readFileSync4 } from "node:fs";
 import { dirname as dirname4 } from "node:path";
 var LocalTransport = class {
@@ -20473,7 +20683,7 @@ var LocalTransport = class {
   label = "this machine";
   exec(command, opts = {}) {
     return new Promise((resolve3) => {
-      const child = spawn3("sh", ["-c", command], { stdio: ["pipe", "pipe", "pipe"] });
+      const child = spawn4("sh", ["-c", command], { stdio: ["pipe", "pipe", "pipe"] });
       let stdout = "";
       let stderr = "";
       let timer;
@@ -20520,7 +20730,7 @@ function expandHome(path) {
 }
 
 // src/lib/transport/ssh.ts
-import { spawn as spawn4 } from "node:child_process";
+import { spawn as spawn5 } from "node:child_process";
 import { mkdirSync as mkdirSync3 } from "node:fs";
 init_types();
 var SshTransport = class {
@@ -20567,7 +20777,7 @@ var SshTransport = class {
    */
   open() {
     return new Promise((resolve3, reject) => {
-      const child = spawn4(this.ssh, this.args(this.host, "true"), { stdio: "inherit" });
+      const child = spawn5(this.ssh, this.args(this.host, "true"), { stdio: "inherit" });
       child.on(
         "error",
         (err) => reject(new CliError("ssh_unreachable", `could not run ${this.ssh}: ${err.message}`))
@@ -20590,7 +20800,7 @@ var SshTransport = class {
   isAlive() {
     if (!this.hasControlMaster) return Promise.resolve(true);
     return new Promise((resolve3) => {
-      const child = spawn4(this.ssh, this.args("-O", "check", this.host), { stdio: "ignore" });
+      const child = spawn5(this.ssh, this.args("-O", "check", this.host), { stdio: "ignore" });
       child.on("error", () => resolve3(false));
       child.on("close", (code) => resolve3(code === 0));
     });
@@ -20607,7 +20817,7 @@ var SshTransport = class {
     if (!this.hasControlMaster) return Promise.resolve();
     return new Promise((resolve3) => {
       const spec = `${localPort}:127.0.0.1:${remotePort}`;
-      const child = spawn4(this.ssh, this.args("-O", "cancel", "-L", spec, this.host), {
+      const child = spawn5(this.ssh, this.args("-O", "cancel", "-L", spec, this.host), {
         stdio: "ignore"
       });
       child.on("error", () => resolve3());
@@ -20616,7 +20826,7 @@ var SshTransport = class {
   }
   exec(command, opts = {}) {
     return new Promise((resolve3) => {
-      const child = spawn4(this.ssh, this.args(this.host, "--", `sh -c ${shellQuote(command)}`), {
+      const child = spawn5(this.ssh, this.args(this.host, "--", `sh -c ${shellQuote(command)}`), {
         stdio: ["pipe", "pipe", "pipe"]
       });
       let stdout = "";
@@ -20651,7 +20861,7 @@ var SshTransport = class {
   async copyTo(localPath, destPath) {
     await this.exec(`mkdir -p $(dirname ${destPath})`, { timeoutMs: 15e3 });
     await new Promise((resolve3, reject) => {
-      const child = spawn4(this.scp, [...this.controlArgs, localPath, `${this.host}:${destPath}`], {
+      const child = spawn5(this.scp, [...this.controlArgs, localPath, `${this.host}:${destPath}`], {
         stdio: ["ignore", "ignore", "inherit"]
       });
       child.on("error", reject);
@@ -20711,7 +20921,7 @@ async function connectRemote(opts) {
     ...opts.onRefreshRequest !== void 0 ? { control: { token: endpoint.token, onRefresh: opts.onRefreshRequest } } : {},
     // The store lives on the CLIENT machine — every cockpit here shares it,
     // whichever remote daemon each one drives.
-    localSync: { token: endpoint.token, file: join5(clientHome(), "local-sync.json") }
+    localSync: { token: endpoint.token, file: join6(clientHome(), "local-sync.json") }
   });
   tunnel.onPortChange((port) => ui.setTarget({ host: "127.0.0.1", port }));
   const eventCbs = /* @__PURE__ */ new Set();
@@ -20762,18 +20972,18 @@ async function showLogs(transport, opts) {
 
 // src/lib/registry.ts
 import { mkdirSync as mkdirSync4, readdirSync, readFileSync as readFileSync5, rmSync, writeFileSync as writeFileSync2 } from "node:fs";
-import { join as join6 } from "node:path";
+import { join as join7 } from "node:path";
 function cockpitsDir(env) {
-  return join6(clientHome(env), "cockpits");
+  return join7(clientHome(env), "cockpits");
 }
 function slug(target) {
   return target.replace(/[^A-Za-z0-9@._-]/g, "_");
 }
 function cockpitRecordPath(target) {
-  return join6(cockpitsDir(), `${slug(target)}.json`);
+  return join7(cockpitsDir(), `${slug(target)}.json`);
 }
 function cockpitLogPath(target) {
-  return join6(clientHome(), "logs", `cockpit-${slug(target)}.log`);
+  return join7(clientHome(), "logs", `cockpit-${slug(target)}.log`);
 }
 function writeCockpitRecord(record2) {
   mkdirSync4(cockpitsDir(), { recursive: true, mode: 448 });
@@ -20802,7 +21012,7 @@ function listCockpitRecords() {
   for (const name of names) {
     if (!name.endsWith(".json")) continue;
     try {
-      records.push(JSON.parse(readFileSync5(join6(cockpitsDir(), name), "utf8")));
+      records.push(JSON.parse(readFileSync5(join7(cockpitsDir(), name), "utf8")));
     } catch {
     }
   }
@@ -20834,7 +21044,7 @@ async function checkCockpit(record2) {
 }
 
 // src/lib/start.ts
-import { join as join7 } from "node:path";
+import { join as join8 } from "node:path";
 init_types();
 async function startLocal(opts) {
   const logger = opts.logger ?? silentLogger;
@@ -20857,7 +21067,7 @@ async function startLocal(opts) {
     // never squat the daemon's own port
     target: { host: "127.0.0.1", port: endpoint.port },
     ...opts.onRefreshRequest !== void 0 ? { control: { token: endpoint.token, onRefresh: opts.onRefreshRequest } } : {},
-    localSync: { token: endpoint.token, file: join7(clientHome(), "local-sync.json") }
+    localSync: { token: endpoint.token, file: join8(clientHome(), "local-sync.json") }
   });
   const eventCbs = /* @__PURE__ */ new Set();
   return {
@@ -20919,7 +21129,7 @@ async function upgradeDaemon(transport, opts = {}) {
 }
 
 // src/cli/detach.ts
-import { spawn as spawn5 } from "node:child_process";
+import { spawn as spawn6 } from "node:child_process";
 import { closeSync, mkdirSync as mkdirSync5, openSync, readFileSync as readFileSync6 } from "node:fs";
 import { dirname as dirname5 } from "node:path";
 init_types();
@@ -20965,7 +21175,7 @@ async function launchDetached(opts) {
   mkdirSync5(dirname5(logFile), { recursive: true });
   const fd = openSync(logFile, "w");
   const argv = opts.argv ?? process.argv.slice(2);
-  const child = spawn5(process.execPath, [process.argv[1] ?? "", ...argv], {
+  const child = spawn6(process.execPath, [process.argv[1] ?? "", ...argv], {
     detached: true,
     stdio: ["ignore", fd, fd],
     env: { ...process.env, [COCKPIT_CHILD_ENV]: "1" }
@@ -21031,7 +21241,7 @@ function spawnDetachedRefresh(target, argv) {
   const fd = openSync(logFile, "a");
   const env = { ...process.env };
   delete env[COCKPIT_CHILD_ENV];
-  const child = spawn5(process.execPath, [process.argv[1] ?? "", ...argv], {
+  const child = spawn6(process.execPath, [process.argv[1] ?? "", ...argv], {
     detached: true,
     stdio: ["ignore", fd, fd],
     env
@@ -21085,8 +21295,8 @@ function timestampedLogger() {
 // src/cli/run.ts
 function assetsDir() {
   const here = dirname6(fileURLToPath3(import.meta.url));
-  for (const candidate of [join8(here, "public"), join8(here, "..", "..", "dist", "public")]) {
-    if (existsSync3(join8(candidate, "index.html"))) return candidate;
+  for (const candidate of [join9(here, "public"), join9(here, "..", "..", "dist", "public")]) {
+    if (existsSync3(join9(candidate, "index.html"))) return candidate;
   }
   throw new CliError(
     "not_installed",
@@ -21102,7 +21312,7 @@ async function openTarget(host) {
     throw new CliError(
       "not_installed",
       `no puddle daemon is set up on ${transport.label}`,
-      host === void 0 ? "run: puddle start" : `run: puddle connect ${host}`
+      host === void 0 ? "run: puddle launch" : `run: puddle launch ${host}`
     );
   }
   const daemonPort = await readDaemonPort(transport);
@@ -21141,7 +21351,7 @@ ${farewell}
     });
   });
 }
-async function run(command) {
+async function run2(command) {
   const logger = terminalLogger();
   switch (command.cmd) {
     case "help":
@@ -21151,9 +21361,8 @@ async function run(command) {
       process.stdout.write(`puddle ${cliVersion()}
 `);
       return 0;
-    case "start":
-    case "connect": {
-      const target = command.cmd === "connect" ? command.host : "local";
+    case "launch": {
+      const target = command.target;
       if (!command.foreground && !isCockpitChild()) {
         return launchDetached({ target, noBrowser: command.noBrowser, logger });
       }
@@ -21203,11 +21412,11 @@ async function run(command) {
         noUpgrade: command.noUpgrade,
         foreground: command.foreground
       };
-      const next = target === "local" ? { cmd: "start", ...shared } : {
-        cmd: "connect",
-        host: target,
+      const next = {
+        cmd: "launch",
+        target,
         ...shared,
-        ...command.remotePort !== void 0 ? { remotePort: command.remotePort } : {}
+        ...target !== "local" && command.remotePort !== void 0 ? { remotePort: command.remotePort } : {}
       };
       if (!command.foreground && !isCockpitChild()) {
         return launchDetached({
@@ -21370,18 +21579,88 @@ async function run(command) {
       }
     }
     case "upgrade": {
-      const transport = command.host === void 0 ? new LocalTransport() : new SshTransport(command.host);
-      if (transport instanceof SshTransport) await transport.open();
-      try {
-        const result = await upgradeDaemon(transport, { logger });
-        logger.info(`puddled ${result.from ?? "(unmanaged)"} \u2192 ${result.to} on ${transport.label}`);
-        return 0;
-      } finally {
-        transport.dispose();
+      const local = command.host === void 0 || command.host === "local";
+      if (command.what === "daemon") {
+        const transport = local ? new LocalTransport() : new SshTransport(command.host);
+        if (transport instanceof SshTransport) await transport.open();
+        try {
+          const result = await upgradeDaemon(transport, { logger });
+          logger.info(
+            `puddled ${result.from ?? "(unmanaged)"} \u2192 ${result.to} on ${transport.label}`
+          );
+          return 0;
+        } finally {
+          transport.dispose();
+        }
       }
+      if (!local) {
+        throw new CliError(
+          "bad_arguments",
+          `puddle upgrade ${command.what} runs on the machine it upgrades`,
+          `ssh into ${command.host} and run it there \u2014 user@host targets the daemon only`
+        );
+      }
+      return command.what === "cli" ? upgradeCli(logger) : upgradeDesktop(logger);
     }
   }
 }
+function upgradeCli(logger) {
+  logger.info(`puddle CLI ${cliVersion()} \u2014 asking npm for the latest release`);
+  return new Promise((resolve3, reject) => {
+    const child = spawn7("npm", ["install", "-g", "@puddle-code/cli@latest"], {
+      stdio: "inherit"
+    });
+    child.on(
+      "error",
+      () => reject(
+        new CliError(
+          "not_installed",
+          "npm is not on PATH",
+          "the CLI is installed and upgraded via npm: npm install -g @puddle-code/cli@latest"
+        )
+      )
+    );
+    child.on("exit", (code) => {
+      if (code === 0) {
+        logger.info("done \u2014 `puddle --version` shows the installed version");
+        resolve3(0);
+      } else {
+        reject(new CliError("not_installed", `npm install exited with ${code ?? "a signal"}`));
+      }
+    });
+  });
+}
+async function upgradeDesktop(logger) {
+  const installed = await findInstalledDesktopApp();
+  if (installed === null) {
+    throw new CliError(
+      "not_installed",
+      "no Puddle.app in /Applications or ~/Applications",
+      process.platform === "linux" ? "AppImages carry no fixed path \u2014 update from the app itself (its banner knows $APPIMAGE)" : void 0
+    );
+  }
+  if (await isDesktopAppRunning(installed.appPath)) {
+    throw new CliError(
+      "already_running",
+      "Puddle is running \u2014 use its update banner, or quit it and rerun"
+    );
+  }
+  const update = await checkForDesktopUpdate(installed.version);
+  if (update === null) {
+    logger.info(`Puddle ${installed.version} is already the latest release`);
+    return 0;
+  }
+  logger.info(`Puddle ${installed.version} \u2192 ${update.version}`);
+  const staged = await stageDesktopUpdate(update, { logger });
+  await applyDesktopUpdate(staged, {
+    targetPath: installed.appPath,
+    detach: false,
+    relaunch: false,
+    logger
+  });
+  logger.info(`Puddle ${update.version} installed at ${installed.appPath}`);
+  return 0;
+}
 async function runCockpit(command, target, terminal) {
   const detached = isCockpitChild();
   const logger = detached ? timestampedLogger() : terminal;
@@ -21413,14 +21692,15 @@ async function runCockpit(command, target, terminal) {
       "--no-browser",
       // the requesting tab reloads itself; no second tab
       ...command.port !== void 0 ? ["--port", String(command.port)] : [],
-      ...command.cmd === "connect" && command.remotePort !== void 0 ? ["--remote-port", String(command.remotePort)] : [],
+      ...command.remotePort !== void 0 ? ["--remote-port", String(command.remotePort)] : [],
       ...command.tarball !== void 0 ? ["--tarball", command.tarball] : [],
       ...command.noUpgrade ? ["--no-upgrade"] : []
     ]);
   };
   let cockpit;
   try {
-    cockpit = command.cmd === "start" ? await startLocal({ ...command, assetsDir: assetsDir(), logger, onRefreshRequest }) : await connectRemote({ ...command, assetsDir: assetsDir(), logger, onRefreshRequest });
+    const common = { ...command, assetsDir: assetsDir(), logger, onRefreshRequest };
+    cockpit = command.target === "local" ? await startLocal(common) : await connectRemote({ ...common, host: command.target });
   } catch (err) {
     if (err instanceof CliError) {
       writeCockpitRecord({
@@ -21441,13 +21721,13 @@ async function runCockpit(command, target, terminal) {
     browserUrl: cockpit.browserUrl,
     nonce: cockpit.nonce
   });
-  const arrow = command.cmd === "connect" ? ` \u2192 ${command.host}` : "";
+  const arrow = command.target === "local" ? "" : ` \u2192 ${command.target}`;
   logger.info(`puddle cockpit at ${cockpit.origin}${arrow} (daemon ${cockpit.daemon.version})`);
   if (!detached) {
     if (!command.noBrowser) openBrowser(cockpit.browserUrl);
     logger.info(`open: ${cockpit.browserUrl}`);
   }
-  const where = command.cmd === "start" ? "this machine" : command.host;
+  const where = command.target === "local" ? "this machine" : command.target;
   await runUntilInterrupted(async () => {
     await cockpit.stop();
     removeCockpitRecord(target);
@@ -21462,7 +21742,7 @@ function pad(text, width) {
 init_types();
 try {
   const command = parseArgs(process.argv.slice(2));
-  process.exit(await run(command));
+  process.exit(await run2(command));
 } catch (err) {
   if (err instanceof CliError) {
     process.stderr.write(`puddle: ${err.message}