pi-webapp 0.1.18 → 0.1.20

package/docs/desktop.md

@@ -0,0 +1,228 @@
+# Desktop application
+
+The desktop application **pi** is an optional Electron host for the existing Web UI.
+The `npx pi-webapp` and Pi `/web` entry points remain available. There is no
+second implementation of chat, files, terminals, Git or session storage.
+
+## Build and run
+
+Build on the target OS and architecture (macOS/Linux/Windows, x64 or arm64):
+
+```bash
+npm ci
+npm run check
+npm test
+npm run desktop:prepare
+npm run desktop:start
+```
+
+`desktop:prepare` builds the UI/extension, downloads **Node 22.23.3** from
+nodejs.org, verifies the archive against the official HTTPS SHA-256 manifest,
+and installs the pinned production dependencies from
+`desktop/runtime-manifest/package-lock.json`. It verifies the bundled Pi version
+and actually starts a PTY before declaring success. Internet is required while
+building, not to install Node/Pi on the end user's machine. Model calls,
+authorization and package installation can still require internet.
+
+The staging directory is `.desktop/runtime/`:
+
+- `node/`: standalone Node and npm, including their upstream license.
+- `backend/`: pi-webapp assets, extension, launcher and locked dependencies,
+  including Pi. It is outside ASAR, so Node and native PTY helpers run normally.
+- `build-info.json`: app/runtime versions, platform, architecture and Node checksum.
+
+Electron's renderer has no Node integration or preload bridge. It loads the same
+loopback HTTP page as a browser, with sandboxing, context isolation, normal CSP,
+and the existing bearer-token authentication. External HTTP(S) links require a
+native confirmation and open in the default browser. Other OS protocols, webviews,
+page-created windows, permission requests and downloads are not enabled.
+
+## Create an installer
+
+```bash
+npm run desktop:package             # DMG / NSIS installer / AppImage on this host
+npm run desktop:package -- --dir    # unpacked application for QA
+```
+
+Output is in `desktop-release/`. The macOS bundle is **pi.app**, the native menu
+and window name are **pi**, and installer names include a desktop build number,
+e.g. `pi-0.1.19-desktop.4-mac-arm64.dmg`. “pi → 关于 pi” shows the build number
+and executable location, so different desktop rebuilds are distinguishable even
+when their shared backend stays at the same npm version. `desktop/release.json`
+is the single source for the desktop name/build; increment its build number for
+each delivered rebuild. The CFBundleVersion / Windows file version also changes.
+
+Cross-platform/architecture flags are
+intentionally rejected by the wrapper: using the current machine's Node/native
+modules in another platform's installer would create a broken application. Use
+native runners for each target. A manual GitHub Actions workflow is provided;
+it never publishes a release automatically.
+
+The application embeds Node and Pi. Git, SSH, project compilers and other system
+tools are **not** bundled. Missing tools must be installed by the user. Model
+accounts/API credentials must still be configured in the existing settings UI.
+
+### Signing and updates / “签名更新”
+
+These are two separate release responsibilities:
+
+- **Code signing** identifies the publisher and protects the application from
+  undetected modification. macOS public distribution normally also needs Apple
+  notarization. Windows signing reduces unknown-publisher warnings. These require
+  the publisher's own credentials/certificates and, potentially, paid accounts.
+- **Safe updates** verify an update's publisher/integrity and replace a compatible
+  application/runtime without destroying user data.
+
+This first implementation creates **unsigned local/test installers**, with no
+certificate discovery, notarization, public release, or automatic desktop updater.
+macOS Gatekeeper / Windows SmartScreen may warn or block an unsigned download.
+Do not disable OS security globally to use it. Public distribution needs a
+separately configured, authorized signing/notarization workflow; local successful
+packaging is not proof of public-distribution readiness.
+
+For now, install a newer desktop package to upgrade; if replacing a running
+desktop-owned runtime, first finish tasks and stop that owned service. A desktop
+attached to an external Web service can simply close without stopping the service. Desktop-managed backends reject the Web/npm update and restart paths,
+so the UI cannot overwrite the bundled runtime. A desktop window attached to an
+existing npm-managed backend preserves that backend's original update behavior.
+
+### Upgrading from the former “Pi Webapp” app
+
+1. Quit the old desktop process first. A running old instance cannot be replaced
+   in memory by dragging a new app into Applications. Keep an external Web
+   backend running; an attached desktop's exit never stops it.
+2. Open the **new build-numbered** DMG and drag **pi.app** into Applications.
+   If pi.app already exists, confirm Replace. The formerly named Pi Webapp.app
+   is a separate Finder item and is not silently deleted or overwritten.
+3. Explicitly open `/Applications/pi.app`, not the old Dock shortcut, an older
+   mounted disk image, or Pi Webapp.app. Verify **pi → 关于 pi → 桌面构建 4**.
+4. Remove the old pinned Dock shortcut and pin the new pi.app. Once verified,
+   the old Pi Webapp.app may be removed manually; do not delete `~/.pi`.
+
+The bundle ID remains `dev.pi.webapp`. The old Electron profile/instance-lock
+location (`appData/Pi Webapp`) is retained so the rename does not reset UI
+preferences or allow a second independent desktop instance. Explicit
+`--user-data-dir` overrides are respected for testing. Pi configuration and
+sessions still live in their existing directory. The shared Web document/CLI
+keeps its existing name; this rename is for the native desktop application.
+
+## Application icon
+
+The desktop uses an original deep-teal rounded tile with an ivory **π** monogram
+and a mint **>_** terminal prompt. Editable artwork lives in
+`desktop/icons/icon.svg`; the checked-in `icon.png` (1024px, transparent),
+`icon.icns` (standard/Retina macOS sizes), and `icon.ico` (16–256px Windows sizes)
+are generated from it. Packaging explicitly selects an icon for each platform;
+the window and macOS development Dock also use this artwork instead of Electron's.
+
+To regenerate after editing the SVG:
+
+```bash
+npx playwright install chromium   # only needed to regenerate artwork
+npm run desktop:icons
+# Or use installed Google Chrome: PI_WEB_TEST_CHROME=true npm run desktop:icons
+npm run test:desktop
+npm run desktop:package
+```
+
+Normal packaging uses the committed images and does not need a browser or an
+image-conversion dependency. Installing a rebuilt app replaces its icon; quit
+the old app first and replace it in Applications. A stale pinned Dock shortcut
+may need to be removed and re-added. Do not modify an installed application's
+bundle to change its icon, and do not delete Pi user data to refresh an icon.
+
+## Service ownership and shared state
+
+The existing launcher state directory and exclusive lock are reused under
+`~/.pi/agent/pi-web/` (or `PI_CODING_AGENT_DIR`). Model credentials and Pi sessions
+stay in Pi's existing data directory, not inside the application bundle.
+
+- The desktop checks a live launcher's bridge version, exact app version, token
+  and authenticated version endpoint before attaching. The released **0.1.19**
+  Web launcher predates these metadata fields: when they are absent, the desktop
+  also checks the authenticated session schema (v1) and the initial NDJSON
+  snapshot event before attaching. This is a narrow, tested legacy allowlist,
+  not cross-version compatibility or unconditional acceptance of missing fields.
+- Legacy detection uses only GET requests, cancels its temporary event stream,
+  bounds response size/time, and never rewrites launcher state or claims service
+  ownership. A service replaced during a handshake is rechecked.
+- Explicit incompatible protocols/versions, bad authentication, and failed health
+  checks remain errors with distinct messages. A native dialog offers retry,
+  opening the authenticated existing service in a browser when safe, or exiting.
+  It never stops, upgrades, or migrates an external service automatically. A truly
+  incompatible backend must be switched from its original entry point after
+  finishing tasks; a compatible old Web backend does **not** need to be stopped.
+- If there is no running service, the desktop starts the shared launcher with its
+  bundled Node/Pi. A racing launcher still has to acquire the same exclusive lock.
+- A desktop application is single-instance. Launching it again focuses its window.
+- Closing the window or choosing Quit asks whether to stop the owned service or
+  leave it running. Stopping ends **all** sessions and terminals on that service,
+  including those used by a browser. Cancel leaves the application open.
+- An attached service is never stopped by closing the desktop window.
+- “Window → Open in browser” opens the same backend, not another Pi process.
+- After choosing to leave the service running, reopening the desktop attaches to
+  it. To stop it later, use the Web launcher's `pi-webapp stop` command (or
+  `npm run stop` from this checkout); a new attached desktop does not claim ownership.
+
+The initial workspace is the user's home directory; add/select project workspaces
+using the existing UI. No shell login scripts are executed merely to construct a
+PATH. The bundled Node directory is prepended to the GUI process's environment;
+Git/SSH/toolchain PATH differences on desktop launch should be checked explicitly.
+
+## Tests
+
+```bash
+npm run test:desktop
+npm run desktop:smoke
+npm run desktop:smoke -- --packaged
+# Reproduce the original bug against an installed, pre-desktop 0.1.19 npm release:
+npm run desktop:smoke:legacy -- --packaged --legacy-package /path/to/node_modules/pi-webapp
+```
+
+Smoke testing requires a graphical session (Linux can use Xvfb) and Playwright
+Chromium (`npx playwright install chromium`). Set `PI_WEB_TEST_CHROME=true` to
+use an installed Chrome instead. Build the unpacked application before the
+`--packaged` test. The smoke test uses a temporary HOME/Pi directory and a PATH
+without global Node/Pi. It tests renderer isolation, real PTY interaction,
+authentication, file listing, desktop update protection, a browser connected to
+the same service, and confirmed shutdown/process cleanup. It does **not** submit
+a paid model request, log in to a provider, or use the user's saved credentials.
+Screenshots/results are written to `artifacts/desktop/`.
+
+The legacy smoke uses a temporary HOME/agent directory and copies the old package
+without changing its launcher or extension JavaScript. It prepares node-pty's
+macOS helper executable bit **only in its fixture copy** (as normal installation
+would), leaving the original installed release and live service untouched. It
+starts the genuine old Web backend first, opens a working browser PTY, attaches
+the desktop to the same chat, and verifies that the same PTY and backend survive
+both attachment and desktop exit. The complementary regular smoke covers the
+opposite order: desktop first, then browser. No model request is sent.
+
+If the local harness wraps Git with a forced author, the existing Git history test
+may observe that author instead of its fixture author. Run tests with the normal
+system Git in PATH in an isolated test environment; do not change global Git
+configuration to make a fixture pass.
+
+## Updating runtime dependencies
+
+When production dependencies or pinned Pi versions in the root manifest change:
+
+```bash
+npm run desktop:sync-runtime
+# Review and commit desktop/runtime-manifest/package{,-lock}.json.
+npm run desktop:prepare
+```
+
+The sync command seeds resolutions from the main lockfile and generates a separate
+production-only lockfile. Preparation refuses to proceed when these dependencies
+are out of sync. Electron and electron-builder are development dependencies only;
+they do not enter the published npm package's runtime dependencies.
+
+## Verification scope of the initial delivery
+
+macOS arm64 is the local implementation/QA target. Windows/Linux installer
+configuration is provided but must be tested on their own runners before promising
+support. Custom icons are configured for all platforms; the icon replacement
+has only been verified in a packaged macOS arm64 app.
+Formal signing, automatic desktop updates, tray integration, completion
+notifications and cross-platform end-to-end QA are not included in this delivery.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-webapp",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "type": "module",
   "description": "A browser interface for Pi with live chat, workspaces, models, and attachments",
   "repository": {
@@ -15,7 +15,7 @@
     "pi-webapp": "./bin/pi-webapp.mjs"
   },
   "pi": {
-    "image": "https://cdn.jsdelivr.net/npm/pi-webapp@0.1.18/assets/cover-webapp.png",
+    "image": "https://cdn.jsdelivr.net/npm/pi-webapp@0.1.20/assets/cover-webapp.png",
     "extensions": [
       "./dist/extension.js"
     ]
@@ -31,6 +31,7 @@
     "web/src/ui/shared/LICENSE.txt",
     "docs/sentry.md",
     "docs/sentry-triage.md",
+    "docs/desktop.md",
     "scripts/prepare-terminal.mjs"
   ],
   "scripts": {
@@ -38,7 +39,15 @@
     "status": "node bin/pi-webapp.mjs status",
     "stop": "node bin/pi-webapp.mjs stop",
     "check": "tsc --noEmit && tsc -p web/tsconfig.json",
-    "test": "node --import ./test/setup-env.mjs --experimental-strip-types --test test/*.test.ts",
+    "test": "node --import ./test/setup-env.mjs --experimental-strip-types --test test/*.test.ts && npm run test:desktop",
+    "test:desktop": "node --test desktop/test/*.test.mjs",
+    "desktop:icons": "node scripts/generate-desktop-icons.mjs",
+    "desktop:sync-runtime": "node scripts/sync-desktop-runtime.mjs",
+    "desktop:prepare": "npm run build && node scripts/prepare-desktop.mjs",
+    "desktop:start": "electron desktop",
+    "desktop:smoke": "node scripts/smoke-desktop.mjs",
+    "desktop:smoke:legacy": "node scripts/smoke-desktop-legacy.mjs",
+    "desktop:package": "node scripts/package-desktop.mjs",
     "build": "node scripts/build.mjs",
     "build:web": "node scripts/build.mjs browser",
     "build:extension": "node scripts/build.mjs node",
@@ -70,6 +79,8 @@
     "@types/node": "22.19.19",
     "@types/react": "^18.3.1",
     "@types/react-dom": "^18.3.0",
+    "electron": "44.9.0",
+    "electron-builder": "26.15.3",
     "esbuild": "^0.28.2",
     "micromark-util-types": "^2.0.2",
     "typescript": "7.0.2",

package/web/dist/.vite/manifest.json

@@ -122,13 +122,13 @@
     "isDynamicEntry": true
   },
   "../../node_modules/@shikijs/langs/dist/graphql.mjs": {
-    "file": "assets/graphql-CLuiQLXf.js",
+    "file": "assets/graphql-Bz9lYT3E.js",
     "name": "graphql",
     "src": "../../node_modules/@shikijs/langs/dist/graphql.mjs",
     "isDynamicEntry": true,
     "imports": [
       "_javascript-D_ijBMSX.js",
-      "_app-grSRYeEE.js",
+      "_app-4px1DWHV.js",
       "index.html"
     ]
   },
@@ -161,12 +161,12 @@
     ]
   },
   "../../node_modules/@shikijs/langs/dist/http.mjs": {
-    "file": "assets/http-JHeTzO2o.js",
+    "file": "assets/http-oJQxPuUz.js",
     "name": "http",
     "src": "../../node_modules/@shikijs/langs/dist/http.mjs",
     "isDynamicEntry": true,
     "imports": [
-      "_app-grSRYeEE.js",
+      "_app-4px1DWHV.js",
       "../../node_modules/@shikijs/langs/dist/xml.mjs",
       "../../node_modules/@shikijs/langs/dist/graphql.mjs",
       "index.html",
@@ -275,7 +275,7 @@
     ]
   },
   "../../node_modules/@shikijs/langs/dist/php.mjs": {
-    "file": "assets/php-DX4AdxY7.js",
+    "file": "assets/php-C_eP8QT0.js",
     "name": "php",
     "src": "../../node_modules/@shikijs/langs/dist/php.mjs",
     "isDynamicEntry": true,
@@ -284,7 +284,7 @@
       "../../node_modules/@shikijs/langs/dist/xml.mjs",
       "../../node_modules/@shikijs/langs/dist/sql.mjs",
       "_javascript-D_ijBMSX.js",
-      "_app-grSRYeEE.js",
+      "_app-4px1DWHV.js",
       "../../node_modules/@shikijs/langs/dist/css.mjs",
       "../../node_modules/@shikijs/langs/dist/java.mjs",
       "index.html"
@@ -315,7 +315,7 @@
     "isDynamicEntry": true
   },
   "../../node_modules/@shikijs/langs/dist/rst.mjs": {
-    "file": "assets/rst-DVdeQzC2.js",
+    "file": "assets/rst-D71MTZLw.js",
     "name": "rst",
     "src": "../../node_modules/@shikijs/langs/dist/rst.mjs",
     "isDynamicEntry": true,
@@ -324,7 +324,7 @@
       "../../node_modules/@shikijs/langs/dist/cpp.mjs",
       "../../node_modules/@shikijs/langs/dist/python.mjs",
       "_javascript-D_ijBMSX.js",
-      "_app-grSRYeEE.js",
+      "_app-4px1DWHV.js",
       "../../node_modules/@shikijs/langs/dist/yaml.mjs",
       "../../node_modules/@shikijs/langs/dist/cmake.mjs",
       "../../node_modules/@shikijs/langs/dist/ruby.mjs",
@@ -340,7 +340,7 @@
     ]
   },
   "../../node_modules/@shikijs/langs/dist/ruby.mjs": {
-    "file": "assets/ruby-CwqnXjsB.js",
+    "file": "assets/ruby-DVYYFOy_.js",
     "name": "ruby",
     "src": "../../node_modules/@shikijs/langs/dist/ruby.mjs",
     "isDynamicEntry": true,
@@ -353,7 +353,7 @@
       "../../node_modules/@shikijs/langs/dist/graphql.mjs",
       "../../node_modules/@shikijs/langs/dist/cpp.mjs",
       "../../node_modules/@shikijs/langs/dist/c.mjs",
-      "_app-grSRYeEE.js",
+      "_app-4px1DWHV.js",
       "../../node_modules/@shikijs/langs/dist/lua.mjs",
       "../../node_modules/@shikijs/langs/dist/yaml.mjs",
       "../../node_modules/@shikijs/langs/dist/java.mjs",
@@ -388,13 +388,13 @@
     "isDynamicEntry": true
   },
   "../../node_modules/@shikijs/langs/dist/svelte.mjs": {
-    "file": "assets/svelte-YsqFMt71.js",
+    "file": "assets/svelte-uHeUtAW3.js",
     "name": "svelte",
     "src": "../../node_modules/@shikijs/langs/dist/svelte.mjs",
     "isDynamicEntry": true,
     "imports": [
       "_javascript-D_ijBMSX.js",
-      "_app-grSRYeEE.js",
+      "_app-4px1DWHV.js",
       "../../node_modules/@shikijs/langs/dist/css.mjs",
       "index.html"
     ]
@@ -430,14 +430,14 @@
     "isDynamicEntry": true
   },
   "../../node_modules/@shikijs/langs/dist/vue.mjs": {
-    "file": "assets/vue-D6Eizkci.js",
+    "file": "assets/vue-C1Yqc5Ux.js",
     "name": "vue",
     "src": "../../node_modules/@shikijs/langs/dist/vue.mjs",
     "isDynamicEntry": true,
     "imports": [
       "../../node_modules/@shikijs/langs/dist/css.mjs",
       "_javascript-D_ijBMSX.js",
-      "_app-grSRYeEE.js",
+      "_app-4px1DWHV.js",
       "../../node_modules/@shikijs/langs/dist/html.mjs",
       "_html-derivative-BaRuZAr6.js",
       "index.html"
@@ -695,17 +695,17 @@
     "src": "../../node_modules/katex/dist/fonts/KaTeX_Typewriter-Regular.woff2"
   },
   "WorkspaceTerminal.tsx": {
-    "file": "assets/WorkspaceTerminal-BCq77BLP.js",
+    "file": "assets/WorkspaceTerminal-DF87HK0D.js",
     "name": "WorkspaceTerminal",
     "src": "WorkspaceTerminal.tsx",
     "isDynamicEntry": true,
     "imports": [
-      "_app-grSRYeEE.js",
+      "_app-4px1DWHV.js",
       "index.html"
     ]
   },
-  "_app-grSRYeEE.js": {
-    "file": "assets/app-grSRYeEE.js",
+  "_app-4px1DWHV.js": {
+    "file": "assets/app-4px1DWHV.js",
     "name": "app",
     "isDynamicEntry": true,
     "imports": [
@@ -851,7 +851,7 @@
     "isEntry": true,
     "dynamicImports": [
       "telemetry-client.ts",
-      "_app-grSRYeEE.js"
+      "_app-4px1DWHV.js"
     ]
   },
   "style.css": {

package/web/dist/assets/{WorkspaceTerminal-BCq77BLP.js → WorkspaceTerminal-DF87HK0D.js}

@@ -1,4 +1,4 @@
-var Zr=Object.defineProperty;var Qr=(e,t,i)=>t in e?Zr(e,t,{enumerable:!0,configurable:!0,writable:!0,value:i}):e[t]=i;var V=(e,t,i)=>Qr(e,typeof t!="symbol"?t+"":t,i);import{b as en,a as Lt,H as cs,r as Pt,j as lt,l as tt,B as tn}from"./app-grSRYeEE.js";import{d as sn}from"./app.js";(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},t=new e.Error().stack;t&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[t]="94e921c5-5f1b-46d8-97a2-921f61ed502e",e._sentryDebugIdIdentifier="sentry-dbid-94e921c5-5f1b-46d8-97a2-921f61ed502e")}catch{}})();/**
+var Zr=Object.defineProperty;var Qr=(e,t,i)=>t in e?Zr(e,t,{enumerable:!0,configurable:!0,writable:!0,value:i}):e[t]=i;var V=(e,t,i)=>Qr(e,typeof t!="symbol"?t+"":t,i);import{b as en,a as Lt,H as cs,r as Pt,j as lt,l as tt,B as tn}from"./app-4px1DWHV.js";import{d as sn}from"./app.js";(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},t=new e.Error().stack;t&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[t]="94e921c5-5f1b-46d8-97a2-921f61ed502e",e._sentryDebugIdIdentifier="sentry-dbid-94e921c5-5f1b-46d8-97a2-921f61ed502e")}catch{}})();/**
  * Copyright (c) 2014-2024 The xterm.js authors. All rights reserved.
  * @license MIT
  *