pi-ui-extend 1.0.50 → 2.0.0

package/README.md

@@ -123,8 +123,26 @@ Later files override earlier ones. Disable modules with `disabledModules`, `PI_T
 
 ## Install
 
+### Download a ready-to-run release
+
+[GitHub Releases](https://github.com/dnaroid/pix/releases) contains published
+portable TUI archives and Pix Desktop installers when a release has completed
+the native build/verification pipeline. Choose **TUI** or **Desktop** and your
+OS/CPU: Windows x64, macOS Apple Silicon, macOS Intel, or Linux x64.
+
+These packages contain Node.js and the Pix/ACP runtime; no separate Node/npm
+installation is required to launch them. For TUI, extract the whole archive and
+run `pix` (macOS/Linux) or `pix.cmd` (Windows) from your terminal. For Desktop,
+use the `.dmg`, Windows installer, `.AppImage`, or `.deb` for your system.
+Git, tools needed by your projects, provider credentials and optional voice/
+clipboard helpers are separate. Unsigned/ad-hoc builds may show OS warnings;
+check the release notes before installing. See the [release guide](docs/release.md)
+for building, signing, checksums and updates. npm installation remains available below.
+
 ### Requirements
 
+The Node/npm requirements below apply to the npm/source installation channel.
+
 - **Node.js `>=22.19.0 <25`**
 - macOS, Linux, or Windows terminal with 256-color support
 - npm or another way to run the published npm package

package/dist/app/cli/release-update.d.ts

@@ -0,0 +1,4 @@
+export declare const PIX_RELEASES_URL = "https://github.com/dnaroid/pix/releases/latest";
+export declare function isReleaseInstall(packageRoot: string): boolean;
+export declare function fetchLatestReleaseVersion(_packageName: string, currentVersion: string, timeoutMs: number): Promise<string | undefined>;
+export declare function releaseUpdateHint(): string;

package/dist/app/cli/release-update.js

@@ -0,0 +1,25 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+export const PIX_RELEASES_URL = "https://github.com/dnaroid/pix/releases/latest";
+export function isReleaseInstall(packageRoot) {
+    // Presence alone fails closed: a damaged manifest must never enable global npm mutation.
+    return existsSync(join(packageRoot, ".pix-portable.json"));
+}
+export async function fetchLatestReleaseVersion(_packageName, currentVersion, timeoutMs) {
+    const response = await fetch("https://api.github.com/repos/dnaroid/pix/releases/latest", {
+        headers: { accept: "application/vnd.github+json", "User-Agent": `pix/${currentVersion}` },
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (response.status === 404)
+        return undefined;
+    if (!response.ok)
+        throw new Error(`GitHub Releases returned ${response.status}`);
+    const data = await response.json();
+    if (data.draft === true || data.prerelease === true)
+        return undefined;
+    return typeof data.tag_name === "string" && /^v\d+\.\d+\.\d+$/u.test(data.tag_name)
+        ? data.tag_name.slice(1) : undefined;
+}
+export function releaseUpdateHint() {
+    return `Download the complete package for your OS/CPU from ${PIX_RELEASES_URL}. Close Pix before replacing it. Settings and sessions remain in your user profile. This installation does not update global npm/Pi packages.`;
+}

package/dist/app/cli/update.d.ts

@@ -1,3 +1,4 @@
+export { isReleaseInstall } from "./release-update.js";
 type PixUpdateTestDeps = {
     checkPixUpdate: typeof checkPixUpdate;
     runCommand: typeof runCommand;
@@ -59,4 +60,3 @@ export declare function getPixSelfUpdateCommand(packageName: string, latestVersi
 export declare function getGlobalPiUpdateCommand(targetVersion: string, pixPackageRoot?: string): PixSelfUpdateCommand | undefined;
 export declare function runPixUpdateCli(argv?: readonly string[]): Promise<number>;
 declare function runCommand(command: PixSelfUpdateCommand): Promise<void>;
-export {};

package/dist/app/cli/update.js

@@ -3,6 +3,8 @@ import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { getAgentDir, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { fetchLatestReleaseVersion, isReleaseInstall, releaseUpdateHint } from "./release-update.js";
+export { isReleaseInstall } from "./release-update.js";
 const DEFAULT_UPDATE_TIMEOUT_MS = 10_000;
 const NPM_REGISTRY_URL = "https://registry.npmjs.org";
 const PI_PACKAGE_NAME = "@earendil-works/pi-coding-agent";
@@ -25,6 +27,7 @@ Options:
   -h, --help Show this help
 
 Inside the TUI, /update performs the same non-mutating check.
+Portable/Desktop GitHub Releases are replaced as a complete package; --force never changes global packages for those installations.
 The bundled skills payload under skills/ is copied into ~/.agents/skills on startup.
 The pi-tools-suite payload under external/pi-tools-suite is updated with Pix and linked into ~/.pi/agent/extensions on startup.`;
 }
@@ -54,7 +57,9 @@ export function getPixPackageVersion(packageRoot) {
 }
 export async function checkPixUpdate(options = {}) {
     const packageInfo = readPixPackageInfo(options.packageRoot);
-    return await checkPackageUpdate(packageInfo, options);
+    return await checkPackageUpdate(packageInfo, isReleaseInstall(packageInfo.packageRoot)
+        ? { ...options, fetchLatestVersion: options.fetchLatestVersion ?? fetchLatestReleaseVersion }
+        : options);
 }
 export async function checkPiUpdate(options = {}) {
     const packageRoot = options.packageRoot ?? findPiPackageRoot(options.pixPackageRoot);
@@ -133,7 +138,7 @@ async function checkPackageUpdate(packageInfo, options) {
     try {
         const latestVersion = await (options.fetchLatestVersion ?? fetchLatestNpmVersion)(packageInfo.name, packageInfo.version, options.timeoutMs ?? DEFAULT_UPDATE_TIMEOUT_MS);
         if (!latestVersion) {
-            return { ...base, status: "unknown", reason: "npm registry did not return a latest version" };
+            return { ...base, status: "unknown", reason: "the distribution channel did not return a latest version" };
         }
         return {
             ...base,
@@ -150,6 +155,11 @@ async function checkPackageUpdate(packageInfo, options) {
     }
 }
 export function formatPixUpdateCheck(result) {
+    if (isReleaseInstall(result.packageRoot)) {
+        return ["Pix update (GitHub Release)", `current: ${result.packageName} v${result.currentVersion}`,
+            ...(result.latestVersion ? [`latest: ${result.latestVersion}`] : []),
+            `status: ${result.status}${result.reason ? ` (${result.reason})` : ""}`, releaseUpdateHint()].join("\n");
+    }
     const lines = [
         "Pix update",
         `current: ${result.packageName} v${result.currentVersion}`,
@@ -204,6 +214,8 @@ export function formatGlobalPiCheck(result) {
     return lines.join("\n");
 }
 export function formatPixStartupUpdateDialog(result) {
+    if (isReleaseInstall(result.packageRoot))
+        return formatPixUpdateCheck(result);
     const lines = [
         "A new Pix version is available.",
         `current: ${result.packageName} v${result.currentVersion}`,
@@ -231,6 +243,8 @@ export function getGlobalPiUpdateCommand(targetVersion, pixPackageRoot = readPix
     return getGlobalPackageUpdateCommand(PI_PACKAGE_NAME, targetVersion, pixPackageRoot);
 }
 function getGlobalPackageUpdateCommand(packageName, version, packageRoot) {
+    if (isReleaseInstall(packageRoot))
+        return undefined;
     if (!packageRootLooksPackageManaged(packageRoot))
         return undefined;
     const installSpec = version ? `${packageName}@${version}` : packageName;
@@ -266,6 +280,10 @@ export async function runPixUpdateCli(argv = process.argv.slice(2)) {
     }
     const check = await pixUpdateDeps.checkPixUpdate();
     console.log(formatPixUpdateCheck(check));
+    if (isReleaseInstall(check.packageRoot)) {
+        // Portable/Desktop installs are replaced as a unit. Even --force must not modify global packages.
+        return options.checkOnly && check.status !== "unknown" && check.status !== "unavailable" ? 0 : 1;
+    }
     let globalPiCheck = checkGlobalPiInstall(check.packageRoot);
     console.log(`\n${formatGlobalPiCheck(globalPiCheck)}`);
     if (options.checkOnly)

package/dist/app/commands/command-session-actions.js

@@ -9,7 +9,7 @@ import { createId } from "../id.js";
 import { runProcess } from "../process.js";
 import { copyTextToClipboard } from "../screen/clipboard.js";
 import { formatAccountUsageReport, queryAccountUsageReport } from "../model/model-usage-status.js";
-import { checkGlobalPiInstall, checkPixUpdate, formatGlobalPiCheck, formatPixUpdateCheck, parsePixUpdateArgs, pixUpdateUsage, } from "../cli/update.js";
+import { checkGlobalPiInstall, isReleaseInstall, checkPixUpdate, formatGlobalPiCheck, formatPixUpdateCheck, parsePixUpdateArgs, pixUpdateUsage, } from "../cli/update.js";
 import { createStartupInfoMessage } from "../cli/startup-info.js";
 import { createReloadContextInventory, formatReloadContextInventory } from "./reload-context-inventory.js";
 import { getCompleteSessionStats } from "../session/session-stats.js";
@@ -259,6 +259,17 @@ export class SessionCommandActions {
         const result = await checkPixUpdate();
         if (!isCommandScopeActive(this.host, scope))
             return;
+        if (isReleaseInstall(result.packageRoot)) {
+            this.host.addEntry({ id: createId("system"), kind: "system", text: formatPixUpdateCheck(result) });
+            this.host.setSessionStatus(runtime.session);
+            if (result.status === "newer")
+                this.host.toast.info("A new Pix release is available");
+            else if (result.status === "current")
+                this.host.toast.success("Pix is up to date");
+            else
+                this.host.toast.warning("Pix update check incomplete");
+            return;
+        }
         const globalPiResult = checkGlobalPiInstall(result.packageRoot);
         const forceHint = options.force ? "\n\n/update is check-only. To force a reinstall, run `pix update --force` in your shell and restart Pix." : "";
         this.host.addEntry({

package/docs/desktop-mvp.md

@@ -39,7 +39,9 @@ current product non-goals.
   markdown/diff rendering, or authentication management.
 - Bundling Node or a platform-specific standalone `pix-acp` executable in this
   first slice. Development uses Node plus pix-acp's pinned pi npm dependency;
-  distributable sidecar packaging is a follow-up milestone.
+  distributable packaging is now governed by
+  [`release-distribution.md`](../specs/release-distribution.md), using bundled Node,
+  Pix and ACP resources for release builds while preserving source-mode development.
 - Reimplementing the pi runtime in Rust or the webview.
 
 ## Behavior

package/docs/release.md

@@ -2,6 +2,125 @@
 
 Use this checklist before publishing `pi-ui-extend` so installs work on macOS, Linux, and Windows and the `pi-tools-suite` extension payload is included.
 
+## Downloadable TUI and Desktop releases
+
+One stable `vX.Y.Z` tag produces npm publication and a **draft GitHub Release**
+containing portable TUI and Desktop installers. The contract is in
+[`specs/release-distribution.md`](../specs/release-distribution.md).
+
+| Target | TUI | Desktop |
+| --- | --- | --- |
+| Windows x64 | `.zip` with `pix.cmd` | NSIS `-setup.exe` and `.msi` |
+| macOS Apple Silicon | `.tar.gz` with `pix` | `.dmg` |
+| macOS Intel | `.tar.gz` with `pix` | `.dmg` |
+| Linux x64 | `.tar.gz` with `pix` | `.AppImage` and `.deb` |
+
+Each download contains its own pinned Node.js and dependencies. Users do not need
+Node/npm to launch Pix. Keep the complete TUI directory together and run its
+launcher from a terminal; add that directory to PATH or symlink `pix` on Unix.
+Desktop includes ACP and does not require an npm-installed Pix. Git, shells,
+project runtimes, optional helpers and provider credentials remain separate.
+macOS release packages require 13.5 or newer, matching the bundled Node 24 binary.
+Linux bundles are built on Ubuntu 22.04; do not advertise support for older
+glibc/WebKit environments without running additional compatibility tests.
+
+### Local build
+
+Select a supported Node on PATH (`.node-version` is the CI/build pin), install
+Rust and the platform's [Tauri build prerequisites](https://v2.tauri.app/start/prerequisites/), then run:
+
+```bash
+npm ci --ignore-scripts
+npm ci --prefix acp --ignore-scripts
+npm ci --prefix desktop --ignore-scripts
+npm run release:build
+# Or specify this machine's target:
+npm run release:build -- macos-arm64
+# Only the portable TUI archive:
+npm run release:build -- macos-arm64 --tui-only
+```
+
+Use the corresponding native machine/runner for each target. Cross-host packaging
+is rejected because native modules must match both CPU and OS. Output is under
+`.artifacts/releases/<target>/assets/`. Builds test the real unpacked package and
+the relocated/installed GUI, including an app copied from a mounted read-only DMG.
+The release builder sets `CI=true` even locally so DMG creation does not need Finder
+automation permissions. Development commands (`dev:desktop`, `watch:all`,
+`build:desktop`) remain separate and do not make distributable bundles.
+
+To iterate on the Desktop wrapper after preparing its runtime, use
+`npm run release:build:desktop -- <target>`; rebuild the full release after any
+Pix/ACP/dependency change. `release:smoke` and `release:smoke:desktop` rerun checks
+against already built artifacts. These harnesses create temporary user profiles;
+do not invoke `verify.mjs` or the native diagnostic directly with your real HOME.
+
+### Package contents and size checks
+
+The TUI archive includes Pix and its Node runtime, **not ACP**. The Desktop
+runtime additionally includes ACP. Preparation cleans generated `dist` directories
+before compilation so old emitted files or Vosk models cannot leak into a release;
+it does not delete source files or the user's `models/` directory.
+
+The packager removes foreign esbuild/PTY/clipboard variants and debug source maps,
+then shares only ACP packages proven equivalent to the parent installation by
+file content and dependency graph. Different dependency versions/contexts remain
+isolated. Runtime TypeScript, declarations, native binaries for this target,
+WASM and license files are preserved.
+
+Inspect `.artifacts/releases/<target>/pix/SIZE.json` for TUI and
+`.artifacts/releases/<target>/desktop/pix/SIZE.json` for the Desktop backend.
+Adjacent `OPTIMIZATIONS.json` reports explain the pruning and sharing decisions.
+Sizes count regular-file bytes, not filesystem block allocation. The native
+Desktop host and signing metadata are additional to its backend payload.
+
+Builds fail above these budgets: TUI 384 MiB unpacked / 160 MiB download;
+Desktop backend 512 MiB unpacked / 240 MiB installer. The limits live in
+`scripts/release/size-budget.mjs`; review dependency growth before changing them.
+CI also uploads `size-<target>` report artifacts separately from release assets.
+Smoke tests execute native esbuild, PTY and extension loading after unpacking,
+and additionally exercise ACP and the native application for Desktop.
+
+### CI and publishing
+
+The `Publish` workflow uses native Ubuntu 22.04 x64, macOS 15 ARM64, macOS 15 Intel
+and Windows 2022 x64 runners. `Actions → Publish → Run workflow` builds and tests
+all packages without publishing anything. The ten installers/archives are
+available as four Actions artifacts. On a version-tag push, the final job waits
+for the full native matrix and npm publication, validates the complete set,
+adds `SHA256SUMS`, and uploads everything to a draft release. Only then review
+the release notes/signing status and click **Publish release** in GitHub.
+
+The draft is intentional: an unsigned or incomplete first build must not silently
+become the public latest version. Reruns can replace draft assets, but the release
+script refuses to overwrite published assets. Publish a new version for fixes.
+Checksums detect damaged downloads; they do not replace trusted code signatures.
+
+### Optional signing secrets
+
+Without signing secrets, macOS builds use ad-hoc signatures and Windows installers
+are unsigned. Such builds are suitable for testing but may trigger OS warnings.
+Trusted signing/notarization cannot be configured without the maintainer's keys.
+
+For macOS, configure repository Actions secrets `APPLE_CERTIFICATE` (base64 P12),
+`APPLE_CERTIFICATE_PASSWORD`, and `APPLE_SIGNING_IDENTITY` (Developer ID Application).
+For Tauri notarization also set `APPLE_ID`, `APPLE_PASSWORD` (app-specific password)
+and `APPLE_TEAM_ID`. The workflow imports the certificate into a temporary keychain,
+signs nested runtime binaries before the app, and cleans the keychain afterwards.
+The Node executable has separate JIT/native-addon entitlements. An ad-hoc signature
+is not Developer ID signing. The TUI tarball is not a notarized installer; test its
+download/quarantine UX separately before promising warning-free installation.
+
+For Windows, configure `WINDOWS_CERTIFICATE` (base64 PFX) and
+`WINDOWS_CERTIFICATE_PASSWORD`. The workflow imports it into the runner's user
+certificate store, passes its thumbprint to Tauri and removes it afterwards.
+Hardware-backed/cloud signing requires adapting that signing step to the selected
+provider; the PFX path does not claim to cover every certificate provider.
+
+Keep keys out of the repository and out of release files. Official references:
+[macOS signing](https://v2.tauri.app/distribute/sign/macos/),
+[Windows signing](https://v2.tauri.app/distribute/sign/windows/), and
+[Tauri resource bundling](https://v2.tauri.app/develop/resources/).
+
 ## Local release check
 
 ```bash
@@ -20,7 +139,7 @@ The normative CI invariants are recorded in [`specs/ci-release.md`](../specs/ci-
 The GitHub Actions release workflow has two different responsibilities and they should stay separate:
 
 - `build-and-test` runs on Ubuntu, macOS, and Windows. This is the cross-platform correctness gate: type checks, unit/integration tests, platform-specific host checks, and the Pix build belong here.
-- Package smoke tests validate the artifact a user actually installs. Run the full payload/tarball smoke test on Ubuntu, and a smaller pack/install/CLI sanity check on Windows. A separate macOS package smoke job is unnecessary unless packaging gains macOS-specific behavior.
+- npm package smoke tests run the full payload/tarball test on Ubuntu and a smaller pack/install/CLI check on Windows. Portable/Tauri release artifacts additionally run smoke tests on all four native targets.
 
 Keep CI tests deterministic across runner speed and operating systems:
 
@@ -58,7 +177,12 @@ npm run publish-npm -- 0.2.0      # exact version
 
 The command requires a clean working tree on `master`, pulls latest from `origin/master`, runs `release:check`, runs `npm version`, runs the tarball smoke test, then pushes the branch and `v*` tag. The tag workflow verifies that `package.json` matches the tag before `npm publish --access public`.
 
-Only the root `package.json` version is bumped for Pix releases. Do not bump `external/pi-tools-suite/package.json` unless publishing the suite as a separate package.
+The root `package.json` version is authoritative. Its npm `version` hook synchronizes
+ACP, Desktop, Tauri, Cargo and lockfile versions and stages them before npm creates
+the release commit/tag. `npm run release:version:check` detects drift; use
+`npm run release:version` to repair manifests after a manual root-version edit.
+Only stable `X.Y.Z` versions within MSI bounds are supported by this release path.
+Do not bump `external/pi-tools-suite/package.json` unless publishing the suite separately.
 
 ## Tarball smoke test
 
@@ -96,6 +220,14 @@ Some modules have optional runtime dependencies or host services:
 
 ## Update UX
 
+Portable TUI and packaged Desktop detect their `.pix-portable.json` marker and
+check stable GitHub Releases instead of npm. `/update`, `pix update --check`, and
+the Desktop report point to a complete replacement download. `pix update` or
+`--force` cannot modify global npm/Pi packages for these installs. Close Pix before
+replacing the complete package; sessions/settings remain in the user profile.
+Automatic binary replacement/Tauri Updater is not enabled in this first release
+pipeline. The following package-manager behavior applies only to npm installs.
+
 - `/update` inside Pix performs a non-mutating Pix update check and reports whether the global Pi package in the same package-manager prefix matches Pix's pinned Pi SDK version.
 - `pix update --check` performs the same compatibility check without a TTY and never mutates either package.
 - `pix update` first updates a package-manager installation of Pix when needed, then installs the global `@earendil-works/pi-coding-agent` at the exact version pinned by the resulting Pix package. This keeps the shared `pi-tools-suite` host ABI aligned. The next Pix startup refreshes the user extension link.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ui-extend",
-  "version": "1.0.50",
+  "version": "2.0.0",
   "description": "Pix: a workspace-first terminal UI for Pi with tabs, readable tool activity, voice input, and bundled agent tools.",
   "private": false,
   "repository": {
@@ -59,7 +59,7 @@
     "rebuild:all": "npm run build:desktop",
     "check": "npm run check:inner",
     "precheck:inner": "npm run generate-schemas --silent",
-    "check:inner": "npm run sync:sdk-pin:check --silent && tsc --noEmit && npm run test:inner",
+    "check:inner": "npm run sync:sdk-pin:check --silent && npm run release:version:check --silent && tsc --noEmit && npm run test:inner && npm run test:release",
     "test": "npm run test:inner",
     "test:inner": "node --import tsx --test \"tests/**/*.test.ts\"",
     "test:tools-suite": "npm --prefix external/pi-tools-suite test",
@@ -82,6 +82,15 @@
     "smoke-test": "bash scripts/smoke-test-package.sh",
     "smoke-test:cli": "node scripts/smoke-test-package-cli.mjs",
     "release:check": "npm run check && npm run build:pix && npm run pack:dry-run",
+    "release:version": "node scripts/release/sync-version.mjs",
+    "release:version:check": "node scripts/release/sync-version.mjs --check",
+    "version": "node scripts/release/sync-version.mjs --stage",
+    "release:prepare": "node scripts/release/prepare.mjs",
+    "release:build": "node scripts/release/bundle.mjs",
+    "release:build:desktop": "node scripts/release/build-desktop.mjs",
+    "release:smoke": "node scripts/release/smoke.mjs",
+    "release:smoke:desktop": "node scripts/release/smoke-desktop.mjs",
+    "test:release": "node --test scripts/release/test/*.test.mjs",
     "publish-npm": "bash scripts/publish.sh",
     "generate-schemas": "tsx scripts/generate-schemas.ts",
     "generate-schemas:check": "tsx scripts/generate-schemas.ts --check",