@yunazgr/pi-companion 0.2.0 → 0.2.2

package/README.md

@@ -21,7 +21,11 @@ or straight from git:
 
     pi install git:github.com/ygrip/pi-companion
 
-Then start pi as usual and run /companion in each session you want to follow from the dashboard or your phone. It starts the daemon if needed, prints the dashboard address and shares that session with paired devices (`/companion off` stops sharing). Nothing else to configure: the extension finds or starts the daemon on its own, downloading the matching sha256-verified daemon binary from GitHub Releases on first use (see Daemon).
+Then start Pi as usual. Installing the Pi extension is enough for normal use: when a Pi session starts, the extension probes the local admin port and automatically starts the daemon if needed. On first use it downloads the matching sha256-verified daemon binary from GitHub Releases, caches it under `~/.pi/agent/pi-companion/bin/<version>/`, and reuses the same daemon across Pi sessions.
+
+Use `/companion` in each session you want to share with paired devices. It enables remote access for that session and prints the local dashboard address. `/companion off` stops sharing that session.
+
+You do **not** need to run `pi-companion-server` manually for a normal npm install. Manual daemon startup is mainly for local development, debugging, or when `PI_COMPANION_AUTOSTART=0` is set.
 
 ## Architecture
 
@@ -56,7 +60,24 @@ Then start pi as usual and run /companion in each session you want to follow fro
 
 The local administration surface and paired-device surface are separate listeners. If you expose Pi Companion through a tunnel, target only port 43722. Never expose port 43721.
 
-## Daemon
+## How the daemon runs
+
+For a normal install:
+
+    pi install npm:@yunazgr/pi-companion
+
+That is enough. Start Pi normally; the extension will start the daemon on demand and keep its daemon version aligned with the installed extension. Updating the Pi package is therefore enough to update both pieces. You do not need a separate terminal, launch agent, system service, or manual `pi-companion-server` process.
+
+The lifecycle is:
+
+1. A Pi session loads the extension.
+2. The extension probes `http://127.0.0.1:43721`.
+3. If the daemon is already running, the session connects to it.
+4. If not, the extension resolves the daemon binary, downloading the matching GitHub Release on first use if necessary.
+5. It starts the daemon detached in the background.
+6. Other Pi sessions reuse the same daemon.
+7. On extension upgrades, the extension compares its package version with the running daemon. If they differ, it stops the old local daemon, resolves/downloads the matching release, and starts the new daemon automatically.
+8. The daemon keeps running independently until it is stopped or the machine restarts.
 
 There is exactly one daemon per machine, shared by every Pi session. The extension manages it with no configuration:
 
@@ -122,7 +143,7 @@ Dialogs from other extensions (`ctx.ui.select`, `ctx.ui.confirm`, `ctx.ui.input`
 Pairing is daemon-wide rather than session-specific. Everything lives on the **Devices** page of the local console (port 43721):
 
 1. Choose **Pair a device**. The daemon creates a single-use invitation (5 minutes by default, configurable in Settings) and shows it as a QR code, a copyable link and a short code (`XXXX-XXXX`).
-2. On the phone, open the paired-device address. An unpaired device gets a connect screen: scan the QR code with the in-app camera (needs HTTPS; otherwise use the phone's camera app, which opens the invitation link) or type the short code, then give the device a name.
+2. On the phone, open the paired-device address. An unpaired device gets a connect screen: scan the QR code with the in-app camera (HTTPS required), use the phone's camera app to open the invitation link, or type the short code shown beside the QR, then give the device a name. Pi Companion explains why camera access is needed before triggering the browser permission prompt.
 3. The daemon issues a long random credential and stores only its SHA-256 hash.
 
 Typed codes are short, so wrong ones are counted: after ten misses within ten minutes every open invitation is withdrawn and code entry is refused (HTTP 429) until the window passes.
@@ -219,6 +240,7 @@ Design notes:
 - warm amber on graphite or paper, matching the logo; system fonts only, so nothing loads from the network. highlight.js and Mermaid load only when a reply contains code or a diagram
 - the window never scrolls. The sidebar, page content, activity feed, file list, diff, chips and tabs each scroll inside their own container, and the composer and mobile tab bar stay put
 - the activity feed follows new output and stops following when you scroll up ("Jump to latest" brings you back)
+- installable PWA: web app manifest, standalone display mode, Apple home-screen metadata, and a small service worker that caches only the shell and immutable assets; API/session traffic is never cached
 - mobile: bottom tab bar, safe-area insets, 44px touch targets, 16px inputs (no iOS zoom), Enter inserts a newline on touch keyboards
 - accessibility: skip link, visible focus rings, arrow-key tabs, labelled controls, live regions for the feed and questions, reduced-motion support
 - the dot field is Raksara's component, loaded when the browser is idle, paused when hidden, and static under reduced motion
@@ -254,16 +276,20 @@ The initial slice supports:
 
 There is deliberately no arbitrary shell, arbitrary tool invocation, or arbitrary filesystem API.
 
-## Development
+## Running locally from source
+
+Use this only when developing Pi Companion itself. A published install does not require these steps.
 
 Requirements: Node 22.17+ and stable Rust.
 
+Clone the repository, then:
+
     npm install
     npm run serve
 
-This builds the UI, starts the daemon and prints where it is listening:
+`npm run serve` builds the embedded Svelte UI and starts the Rust daemon in the foreground. It prints:
 
-      Pi Companion v0.1.0
+      Pi Companion v0.2.2
 
       Console          http://127.0.0.1:43721
       Paired devices   http://127.0.0.1:43722
@@ -286,17 +312,25 @@ Then, in another shell, start Pi with the extension from this checkout:
 
     pi -e ./src/index.ts
 
+Because the development daemon is already listening on port 43721, the extension detects it and does not launch another daemon.
+
 For hot-reloading UI work, keep the daemon running and use:
 
     npm run ui:dev
 
 which proxies /api and /ws to the daemon on 43721.
 
-Running the daemon manually with npm run serve and the extension side by side just works: the extension sees the running daemon and connects to it. If you don't run it, the extension launches your local cargo build automatically.
+If you start Pi from the checkout without running `npm run serve`, the extension can still auto-start a local daemon build if one exists under `server/target/debug` or `server/target/release`. For predictable UI work, prefer `npm run serve` in one terminal and `pi -e ./src/index.ts` in another.
+
+To test the same behavior as a published install, stop any development daemon first and install the package normally:
+
+    pi install npm:@yunazgr/pi-companion
+
+Then start Pi. The extension downloads and starts the released daemon automatically.
 
 ## Releases
 
-The package carries the pi-package keyword, so published npm versions appear in the Pi package gallery (https://pi.dev/packages). Host-provided packages (@earendil-works/pi-coding-agent, typebox) are peer dependencies, as Pi requires.
+The package carries the required `pi-package` keyword, which makes the published npm package eligible for discovery in the Pi package gallery (https://pi.dev/packages). The manifest also includes focused discovery keywords such as `pi-extension`, `pi-coding-agent`, `remote-control`, and `session-dashboard`. Host-provided packages (@earendil-works/pi-coding-agent, typebox) are peer dependencies, as Pi requires.
 
 GitHub Actions run only for release tags. Pushing ordinary commits or opening pull requests does not trigger any workflow; CI can also be started manually with workflow_dispatch.
 
@@ -304,9 +338,9 @@ A tag matching vX.Y.Z triggers both the CI and release workflows.
 
 Before publishing, the workflow requires X.Y.Z to match both package.json and server/Cargo.toml. It then runs TypeScript and Rust checks, builds native daemon archives for Linux x86_64, macOS arm64, macOS x86_64, and Windows x86_64, generates SHA-256 checksums, and creates a GitHub Release.
 
-Only after the GitHub Release exists, and only if the repository has an NPM_TOKEN secret, the same tag publishes @yunazgr/pi-companion to npm with provenance, so an npm install never looks for a daemon binary that is not uploaded yet. Git installs need no token.
+Only after the GitHub Release exists, the same tag publishes @yunazgr/pi-companion to npm with provenance through npm Trusted Publishing (GitHub OIDC). No long-lived NPM_TOKEN is required. The trusted publisher should point to GitHub owner ygrip, repository pi-companion, workflow release.yml. Git installs need no npm credential.
 
-On first use the extension downloads `pi-companion-server-<os>-<arch>` for its own package version (`releases/download/v<version>/`), verifies it against `SHA256SUMS`, and caches it under `~/.pi/agent/pi-companion/bin/<version>/`. A git install from a branch that is ahead of the newest tag falls back to the latest release.
+On first use the extension downloads `pi-companion-server-<os>-<arch>` for its own package version (`releases/download/v<version>/`), verifies it against `SHA256SUMS`, and caches it under `~/.pi/agent/pi-companion/bin/<version>/`. On later extension upgrades it detects a running daemon with a different version, stops it locally, and starts the matching daemon automatically. A git install from a branch that is ahead of the newest tag falls back to the latest release.
 
 ## Security boundary
 

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "@yunazgr/pi-companion",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Local-first remote control for Pi sessions: live activity feed, steering, git diff, file drop and phone pairing from a single Rust daemon.",
   "keywords": [
     "pi-package",
-    "pi",
     "pi-extension",
     "pi-coding-agent",
+    "pi",
     "remote-control",
+    "remote-agent",
     "companion",
-    "dashboard",
+    "session-dashboard",
+    "developer-tools",
     "mobile"
   ],
   "homepage": "https://github.com/ygrip/pi-companion#readme",
@@ -84,5 +86,8 @@
     "@google/genai": false,
     "protobufjs": false,
     "fsevents": false
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

package/src/daemon.ts

@@ -40,15 +40,22 @@ function isLocalTarget() {
   }
 }
 
-export async function isDaemonUp(timeoutMs = 800) {
+type DaemonContext = { version?: string; pid?: number };
+
+async function daemonContext(timeoutMs = 800): Promise<DaemonContext | null> {
   try {
     const response = await fetch(adminHttpUrl() + "/api/context", { signal: AbortSignal.timeout(timeoutMs) });
-    return response.ok;
+    if (!response.ok) return null;
+    return await response.json() as DaemonContext;
   } catch {
-    return false;
+    return null;
   }
 }
 
+export async function isDaemonUp(timeoutMs = 800) {
+  return Boolean(await daemonContext(timeoutMs));
+}
+
 function packageVersion() {
   try {
     return JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8")).version as string;
@@ -182,35 +189,84 @@ async function acquireLock() {
   }
 }
 
-async function waitForDaemon(ms: number) {
+async function waitForDaemon(ms: number, expectedVersion?: string) {
   const deadline = Date.now() + ms;
   while (Date.now() < deadline) {
-    if (await isDaemonUp(500)) return true;
+    const context = await daemonContext(500);
+    if (context && (!expectedVersion || context.version === expectedVersion)) return true;
     await new Promise(resolve => setTimeout(resolve, 300));
   }
   return false;
 }
 
+async function waitForDaemonDown(ms: number) {
+  const deadline = Date.now() + ms;
+  while (Date.now() < deadline) {
+    if (!(await isDaemonUp(300))) return true;
+    await new Promise(resolve => setTimeout(resolve, 200));
+  }
+  return false;
+}
+
+async function stopDaemonForUpgrade(context: DaemonContext, log: DaemonLog) {
+  try {
+    const response = await fetch(adminHttpUrl() + "/api/shutdown", {
+      method: "POST",
+      signal: AbortSignal.timeout(2_000)
+    });
+    if (response.ok && await waitForDaemonDown(5_000)) return true;
+  } catch {
+    // Older daemons do not have /api/shutdown. Fall through to a local process stop.
+  }
+
+  try {
+    if (typeof context.pid === "number" && Number.isInteger(context.pid) && context.pid > 1) {
+      process.kill(context.pid, "SIGTERM");
+    } else if (process.platform === "win32") {
+      await execFileAsync("taskkill", ["/IM", "pi-companion-server.exe", "/F"]);
+    } else {
+      await execFileAsync("pkill", ["-f", "pi-companion-server"]);
+    }
+  } catch {
+    // The process may already have exited between the probe and the stop attempt.
+  }
+
+  const stopped = await waitForDaemonDown(5_000);
+  if (!stopped) log("Could not stop the older Pi Companion daemon automatically.", "warning");
+  return stopped;
+}
+
 /**
  * Make sure a daemon is reachable. Returns true when one answers.
  * Never spawns when a daemon (manual `cargo run`, another session's daemon, …) is already up.
  */
 export async function ensureDaemon(log: DaemonLog) {
-  if (await isDaemonUp()) return true;
-  if (process.env.PI_COMPANION_AUTOSTART === "0" || !isLocalTarget()) return false;
+  const expectedVersion = packageVersion();
+  const running = await daemonContext();
+  if (running?.version === expectedVersion) return true;
+  if (process.env.PI_COMPANION_AUTOSTART === "0" || !isLocalTarget()) return Boolean(running);
 
   const release = await acquireLock();
-  if (!release) return await waitForDaemon(10_000); // another Pi session is starting it
+  if (!release) return await waitForDaemon(10_000, expectedVersion); // another Pi session is starting/upgrading it
   try {
-    if (await isDaemonUp()) return true; // started while we were taking the lock
+    const current = await daemonContext();
+    if (current?.version === expectedVersion) return true;
+
+    if (current) {
+      log(
+        "Updating Pi Companion daemon from v" + (current.version ?? "unknown") + " to v" + expectedVersion + "…"
+      );
+      if (!(await stopDaemonForUpgrade(current, log))) return false;
+    }
+
     const binary = await resolveDaemonBinary(log);
     await new Promise<void>((resolve, reject) => {
       const child = spawn(binary, [], { detached: true, stdio: "ignore", windowsHide: true });
       child.once("error", reject);
       child.once("spawn", () => { child.unref(); resolve(); });
     });
-    const up = await waitForDaemon(10_000);
-    if (!up) log("Pi Companion daemon did not become ready (" + binary + ")", "warning");
+    const up = await waitForDaemon(10_000, expectedVersion);
+    if (!up) log("Pi Companion daemon v" + expectedVersion + " did not become ready (" + binary + ")", "warning");
     return up;
   } catch (error) {
     log("Could not start Pi Companion daemon: " + (error instanceof Error ? error.message : String(error)), "warning");