pi-ui-extend 2.0.0 → 2.0.1

package/README.md

@@ -134,6 +134,11 @@ 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.
+Portable TUI installs can later update themselves with `pix update`: the command
+downloads the matching GitHub Release archive, verifies `SHA256SUMS`, smoke-tests
+the staged runtime, and replaces the installation after the updater exits.
+Packaged Desktop checks the signed Tauri update feed on startup and offers an
+Update/Restart flow in the app; development builds do not run that updater.
 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)

package/dist/app/cli/portable-update-helper.d.ts

@@ -0,0 +1,11 @@
+export type PortableUpdateSwap = {
+    parentPid: number;
+    installRoot: string;
+    stagedRoot: string;
+    backupRoot: string;
+    helperRoot: string;
+    nodeRelativePath: string;
+};
+export declare function waitForProcessExit(pid: number, timeoutMs?: number): Promise<void>;
+export declare function swapPortableInstall(swap: PortableUpdateSwap): Promise<void>;
+export declare function runPortableUpdateHelper(configPath: string): Promise<void>;

package/dist/app/cli/portable-update-helper.js

@@ -0,0 +1,94 @@
+import { readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+function processExists(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error instanceof Error && "code" in error && error.code === "EPERM";
+    }
+}
+export async function waitForProcessExit(pid, timeoutMs = 120_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (processExists(pid)) {
+        if (Date.now() >= deadline)
+            throw new Error(`Timed out waiting for Pix process ${pid} to exit`);
+        await new Promise((resolvePromise) => setTimeout(resolvePromise, 100));
+    }
+}
+function validateSwapPaths(swap) {
+    if (!Number.isSafeInteger(swap.parentPid) || swap.parentPid <= 0)
+        throw new Error("Invalid updater parent PID");
+    const installRoot = resolve(swap.installRoot);
+    const stagedRoot = resolve(swap.stagedRoot);
+    const backupRoot = resolve(swap.backupRoot);
+    if (dirname(stagedRoot) !== dirname(installRoot) || dirname(backupRoot) !== dirname(installRoot)) {
+        throw new Error("Updater staging and backup directories must be siblings of the installation");
+    }
+    if (installRoot === stagedRoot || installRoot === backupRoot || stagedRoot === backupRoot) {
+        throw new Error("Updater paths must be distinct");
+    }
+    if (!/^runtime[\\/]node(?:\.exe)?$/u.test(swap.nodeRelativePath))
+        throw new Error("Invalid bundled Node path");
+}
+export async function swapPortableInstall(swap) {
+    validateSwapPaths(swap);
+    await rm(swap.backupRoot, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+    await rename(swap.installRoot, swap.backupRoot);
+    try {
+        await rename(swap.stagedRoot, swap.installRoot);
+    }
+    catch (error) {
+        try {
+            await rename(swap.backupRoot, swap.installRoot);
+        }
+        catch (rollbackError) {
+            throw new AggregateError([error, rollbackError], "Pix update failed and rollback could not restore the previous installation");
+        }
+        throw error;
+    }
+    await rm(swap.backupRoot, { recursive: true, force: true, maxRetries: 20, retryDelay: 100 });
+}
+function scheduleHelperCleanup(swap) {
+    const node = join(swap.installRoot, swap.nodeRelativePath);
+    const code = [
+        "const { rmSync } = require('node:fs');",
+        `setTimeout(() => { try { rmSync(${JSON.stringify(swap.helperRoot)}, { recursive: true, force: true, maxRetries: 20, retryDelay: 100 }); } catch {} }, 250);`,
+    ].join("\n");
+    try {
+        spawn(node, ["-e", code], {
+            cwd: dirname(swap.installRoot),
+            detached: true,
+            stdio: "ignore",
+            windowsHide: true,
+        }).unref();
+    }
+    catch {
+        // A successful install is more important than cleaning the temporary helper.
+    }
+}
+export async function runPortableUpdateHelper(configPath) {
+    const swap = JSON.parse(await readFile(configPath, "utf8"));
+    validateSwapPaths(swap);
+    await waitForProcessExit(swap.parentPid);
+    // Give a Windows .cmd launcher that was waiting on the Node child a chance to
+    // return before renaming its directory. The helper itself runs outside it.
+    await new Promise((resolvePromise) => setTimeout(resolvePromise, 250));
+    try {
+        await swapPortableInstall(swap);
+        scheduleHelperCleanup(swap);
+    }
+    catch (error) {
+        await writeFile(join(swap.helperRoot, "update-error.txt"), `${error instanceof Error ? error.stack ?? error.message : String(error)}\n`).catch(() => undefined);
+        throw error;
+    }
+}
+if (process.argv[1] && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))) {
+    const configPath = process.argv[2];
+    if (!configPath)
+        throw new Error("Missing portable updater helper config path");
+    await runPortableUpdateHelper(configPath);
+}

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

@@ -0,0 +1,14 @@
+import { type GitHubReleaseAsset, type StableGitHubRelease } from "./release-update.js";
+export type PortableUpdateResult = {
+    version: string;
+    assetName: string;
+};
+export declare function portableTuiAssetName(version: string, target: string): string;
+export declare function parseSha256Sums(text: string, assetName: string): string;
+export declare function portableReleaseAssets(release: StableGitHubRelease, target: string): {
+    archive: GitHubReleaseAsset;
+    checksums: GitHubReleaseAsset;
+};
+export declare function safeZipEntryPath(root: string, name: string): string;
+export declare function validateStagedPortableTui(root: string, version: string, target: string): Promise<void>;
+export declare function schedulePortableTuiUpdate(packageRoot: string, currentVersion: string, timeoutMs?: number): Promise<PortableUpdateResult>;

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

@@ -0,0 +1,299 @@
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { createReadStream, createWriteStream } from "node:fs";
+import { chmod, copyFile, cp, lstat, mkdir, mkdtemp, readFile, readlink, realpath, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { Transform } from "node:stream";
+import { fileURLToPath } from "node:url";
+import { x as extractTar } from "tar";
+import * as yauzl from "yauzl";
+import { fetchLatestStableRelease, PIX_RELEASE_TARGETS, readReleaseInstallInfo, } from "./release-update.js";
+const MAX_ARCHIVE_BYTES = 1024 * 1024 * 1024;
+const MAX_CHECKSUM_BYTES = 4 * 1024 * 1024;
+export function portableTuiAssetName(version, target) {
+    if (!/^\d+\.\d+\.\d+$/u.test(version))
+        throw new Error(`Invalid release version: ${version}`);
+    if (!PIX_RELEASE_TARGETS.includes(target))
+        throw new Error(`Invalid release target: ${target}`);
+    return `pix-tui-${version}-${target}.${target.startsWith("windows-") ? "zip" : "tar.gz"}`;
+}
+export function parseSha256Sums(text, assetName) {
+    const matches = text.split(/\r?\n/u).flatMap((line) => {
+        const match = /^([a-f0-9]{64})\s+\*?(.+)$/u.exec(line);
+        return match?.[2] === assetName ? [match[1]] : [];
+    });
+    if (matches.length !== 1)
+        throw new Error(`Missing or ambiguous SHA256SUMS entry for ${assetName}`);
+    return matches[0];
+}
+export function portableReleaseAssets(release, target) {
+    const archiveName = portableTuiAssetName(release.version, target);
+    const exact = (name) => {
+        const matches = release.assets.filter((asset) => asset.name === name);
+        if (matches.length !== 1)
+            throw new Error(`Release ${release.tag} must contain exactly one ${name}`);
+        return matches[0];
+    };
+    return { archive: exact(archiveName), checksums: exact("SHA256SUMS") };
+}
+async function download(url, destination, limit, expectedSize) {
+    if (expectedSize !== undefined && expectedSize > limit)
+        throw new Error(`Release asset exceeds ${limit} bytes`);
+    const response = await fetch(url, {
+        headers: { accept: "application/octet-stream", "User-Agent": "pix-portable-updater" },
+        signal: AbortSignal.timeout(5 * 60_000),
+    });
+    if (!response.ok || !response.body)
+        throw new Error(`Release asset download failed (${response.status})`);
+    let received = 0;
+    const limiter = new Transform({
+        transform(chunk, _encoding, callback) {
+            received += chunk.length;
+            if (received > limit)
+                callback(new Error(`Release asset exceeds ${limit} bytes`));
+            else
+                callback(null, chunk);
+        },
+    });
+    await pipeline(response.body, limiter, createWriteStream(destination, { flags: "wx" }));
+    if (expectedSize !== undefined && received !== expectedSize)
+        throw new Error(`Release asset size mismatch: expected ${expectedSize}, got ${received}`);
+}
+async function sha256(path) {
+    const hash = createHash("sha256");
+    for await (const chunk of createReadStream(path))
+        hash.update(chunk);
+    return hash.digest("hex");
+}
+export function safeZipEntryPath(root, name) {
+    if (!name || name.includes("\0") || name.includes("\\") || name.startsWith("/") || /^[A-Za-z]:/u.test(name)) {
+        throw new Error(`Unsafe ZIP entry: ${name}`);
+    }
+    const parts = name.split("/").filter(Boolean);
+    if (parts.some((part) => part === "." || part === ".."))
+        throw new Error(`Unsafe ZIP entry: ${name}`);
+    const path = resolve(root, ...parts);
+    const rel = relative(root, path);
+    if (!rel || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+        if (name.endsWith("/") && !rel)
+            return root;
+        throw new Error(`Unsafe ZIP entry: ${name}`);
+    }
+    return path;
+}
+function zipMode(entry) {
+    return (entry.externalFileAttributes >>> 16) & 0xffff;
+}
+async function extractZip(archive, destination) {
+    const zip = await new Promise((resolvePromise, reject) => {
+        yauzl.open(archive, { lazyEntries: true, strictFileNames: true, validateEntrySizes: true }, (error, value) => {
+            if (error)
+                reject(error);
+            else
+                resolvePromise(value);
+        });
+    });
+    await new Promise((resolvePromise, reject) => {
+        let settled = false;
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            zip.close();
+            error ? reject(error) : resolvePromise();
+        };
+        zip.on("error", finish);
+        zip.on("end", () => finish());
+        zip.on("entry", (entry) => {
+            void (async () => {
+                const path = safeZipEntryPath(destination, entry.fileName);
+                const mode = zipMode(entry);
+                const kind = mode & 0o170000;
+                if (kind === 0o120000)
+                    throw new Error(`ZIP symlinks are not allowed in Pix portable updates: ${entry.fileName}`);
+                if (entry.fileName.endsWith("/")) {
+                    await mkdir(path, { recursive: true });
+                    zip.readEntry();
+                    return;
+                }
+                if (kind !== 0 && kind !== 0o100000)
+                    throw new Error(`Unsupported ZIP entry type: ${entry.fileName}`);
+                await mkdir(dirname(path), { recursive: true });
+                const stream = await new Promise((resolveStream, rejectStream) => {
+                    zip.openReadStream(entry, (error, value) => error ? rejectStream(error) : resolveStream(value));
+                });
+                await pipeline(stream, createWriteStream(path, { flags: "wx", mode: mode & 0o777 || 0o644 }));
+                zip.readEntry();
+            })().catch(finish);
+        });
+        zip.readEntry();
+    });
+}
+function inside(root, path) {
+    const rel = relative(root, path);
+    return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+async function validatePortableLinks(root, directory = root) {
+    const { readdir } = await import("node:fs/promises");
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+        const path = join(directory, entry.name);
+        const stat = await lstat(path);
+        if (stat.isSymbolicLink()) {
+            const destination = resolve(dirname(path), await readlink(path));
+            if (!inside(root, destination) || !inside(root, await realpath(destination)))
+                throw new Error(`Portable update contains an external link: ${relative(root, path)}`);
+        }
+        else if (stat.isDirectory()) {
+            await validatePortableLinks(root, path);
+        }
+    }
+}
+export async function validateStagedPortableTui(root, version, target) {
+    const manifest = JSON.parse(await readFile(join(root, "release.json"), "utf8"));
+    if (manifest.format !== 2 || manifest.variant !== "tui" || manifest.version !== version || manifest.target !== target) {
+        throw new Error("Downloaded Pix release manifest does not match the requested TUI update");
+    }
+    const marker = JSON.parse(await readFile(join(root, "app/.pix-portable.json"), "utf8"));
+    if (marker.variant !== "tui" || marker.version !== version || marker.target !== target)
+        throw new Error("Downloaded Pix portable marker is inconsistent");
+    for (const path of ["app/package.json", "app/bin/pix.mjs", "verify.mjs", process.platform === "win32" ? "runtime/node.exe" : "runtime/node"]) {
+        const stat = await lstat(join(root, path));
+        if (!stat.isFile())
+            throw new Error(`Downloaded Pix release is missing ${path}`);
+    }
+    await validatePortableLinks(root);
+}
+function verificationEnvironment(home, runtime) {
+    const allowed = Object.fromEntries(Object.entries(process.env).filter(([key, value]) => value !== undefined
+        && /^(SystemRoot|WINDIR|ComSpec|PATHEXT|TEMP|TMP|TMPDIR|LANG|LC_.*|TERM|COLORTERM|DISPLAY|WAYLAND_DISPLAY|DBUS_SESSION_BUS_ADDRESS|XDG_RUNTIME_DIR|SHELL|USER|USERNAME|LOGNAME|ProgramFiles|ProgramW6432|ProgramFiles\(x86\))$/iu.test(key)));
+    return {
+        ...allowed,
+        HOME: home,
+        USERPROFILE: home,
+        APPDATA: join(home, "AppData/Roaming"),
+        LOCALAPPDATA: join(home, "AppData/Local"),
+        XDG_CONFIG_HOME: join(home, ".config"),
+        XDG_CACHE_HOME: join(home, ".cache"),
+        PI_CODING_AGENT_DIR: join(home, ".pi/agent"),
+        PI_OFFLINE: "1",
+        PIX_RELEASE_SMOKE: "1",
+        PIX_SKIP_VERSION_CHECK: "1",
+        PIX_ACP_LOG: "error",
+        PATH: [runtime, process.env.PATH ?? ""].filter(Boolean).join(delimiter),
+    };
+}
+async function verifyStagedPortableTui(root, scratch) {
+    const runtime = join(root, "runtime");
+    const node = join(runtime, process.platform === "win32" ? "node.exe" : "node");
+    const home = join(scratch, "verify-home");
+    const cwd = join(scratch, "verify-workspace");
+    await mkdir(home, { recursive: true });
+    await mkdir(cwd, { recursive: true });
+    await new Promise((resolvePromise, reject) => {
+        const child = spawn(node, [join(root, "verify.mjs")], {
+            cwd,
+            env: verificationEnvironment(home, runtime),
+            stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true,
+        });
+        let output = "";
+        const timer = setTimeout(() => child.kill(), 120_000);
+        child.stdout.setEncoding("utf8").on("data", (chunk) => output = (output + chunk).slice(-32_000));
+        child.stderr.setEncoding("utf8").on("data", (chunk) => output = (output + chunk).slice(-32_000));
+        child.once("error", reject);
+        child.once("close", (code, signal) => {
+            clearTimeout(timer);
+            if (code === 0 && /PIX_RELEASE_RUNTIME_OK/u.test(output))
+                resolvePromise();
+            else
+                reject(new Error(`Downloaded Pix verification failed (${signal ?? code}): ${output}`));
+        });
+    });
+}
+async function extractArchive(archive, destination) {
+    await mkdir(destination, { recursive: true });
+    if (archive.endsWith(".zip"))
+        await extractZip(archive, destination);
+    else
+        await extractTar({ file: archive, cwd: destination, strict: true, preservePaths: false });
+}
+export async function schedulePortableTuiUpdate(packageRoot, currentVersion, timeoutMs = 10_000) {
+    const install = readReleaseInstallInfo(packageRoot);
+    if (!install)
+        throw new Error("Portable release marker is missing or invalid; automatic update is disabled");
+    if (install.variant !== "tui")
+        throw new Error("This is a Desktop installation; use the native Desktop updater");
+    const release = await fetchLatestStableRelease(currentVersion, timeoutMs);
+    if (!release)
+        throw new Error("No stable GitHub Release is available");
+    const { archive: asset, checksums } = portableReleaseAssets(release, install.target);
+    const scratch = await mkdtemp(join(tmpdir(), "pix portable update "));
+    let helperRoot;
+    let stagedSibling;
+    try {
+        const archive = join(scratch, asset.name);
+        const checksumFile = join(scratch, "SHA256SUMS");
+        await Promise.all([
+            download(asset.url, archive, MAX_ARCHIVE_BYTES, asset.size),
+            download(checksums.url, checksumFile, MAX_CHECKSUM_BYTES, checksums.size),
+        ]);
+        const expected = parseSha256Sums(await readFile(checksumFile, "utf8"), asset.name);
+        const actual = await sha256(archive);
+        if (actual !== expected)
+            throw new Error(`Downloaded Pix checksum mismatch for ${asset.name}`);
+        const extraction = join(scratch, "extracted");
+        await extractArchive(archive, extraction);
+        const staged = join(extraction, "pix");
+        await validateStagedPortableTui(staged, release.version, install.target);
+        await verifyStagedPortableTui(staged, scratch);
+        const realPackageRoot = await realpath(packageRoot);
+        const installRoot = dirname(realPackageRoot);
+        if (inside(installRoot, resolve(process.cwd()))) {
+            throw new Error("Run `pix update` from outside the Pix installation directory so it can be replaced safely after exit");
+        }
+        const parent = dirname(installRoot);
+        const suffix = `${process.pid}-${Date.now()}`;
+        stagedSibling = join(parent, `.${basename(installRoot)}.update-${suffix}`);
+        const backupRoot = join(parent, `.${basename(installRoot)}.backup-${suffix}`);
+        await rm(stagedSibling, { recursive: true, force: true });
+        await cp(staged, stagedSibling, { recursive: true, verbatimSymlinks: true });
+        await validateStagedPortableTui(stagedSibling, release.version, install.target);
+        helperRoot = await mkdtemp(join(tmpdir(), "pix updater helper "));
+        const nodeRelativePath = process.platform === "win32" ? "runtime/node.exe" : "runtime/node";
+        const helperNode = join(helperRoot, process.platform === "win32" ? "node.exe" : "node");
+        const helperScript = join(helperRoot, "portable-update-helper.js");
+        const helperConfig = join(helperRoot, "update.json");
+        await copyFile(join(installRoot, nodeRelativePath), helperNode);
+        if (process.platform !== "win32")
+            await chmod(helperNode, 0o755);
+        await copyFile(fileURLToPath(new URL("./portable-update-helper.js", import.meta.url)), helperScript);
+        const swap = {
+            parentPid: process.pid,
+            installRoot,
+            stagedRoot: stagedSibling,
+            backupRoot,
+            helperRoot,
+            nodeRelativePath,
+        };
+        await writeFile(helperConfig, `${JSON.stringify(swap)}\n`, { mode: 0o600 });
+        const child = spawn(helperNode, [helperScript, helperConfig], {
+            cwd: helperRoot,
+            detached: true,
+            stdio: "ignore",
+            windowsHide: true,
+        });
+        child.unref();
+        stagedSibling = undefined;
+        helperRoot = undefined;
+        return { version: release.version, assetName: asset.name };
+    }
+    finally {
+        await rm(scratch, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+        if (stagedSibling)
+            await rm(stagedSibling, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+        if (helperRoot)
+            await rm(helperRoot, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+    }
+}

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

@@ -1,4 +1,24 @@
 export declare const PIX_RELEASES_URL = "https://github.com/dnaroid/pix/releases/latest";
+export declare const PIX_RELEASES_API_URL = "https://api.github.com/repos/dnaroid/pix/releases/latest";
+export declare const PIX_RELEASE_TARGETS: readonly ["linux-x64", "macos-arm64", "macos-x64", "windows-x64"];
+export type ReleaseInstallVariant = "tui" | "desktop";
+export type ReleaseInstallInfo = {
+    version: string;
+    target: string;
+    variant: ReleaseInstallVariant;
+};
+export type GitHubReleaseAsset = {
+    name: string;
+    url: string;
+    size?: number;
+};
+export type StableGitHubRelease = {
+    tag: string;
+    version: string;
+    assets: GitHubReleaseAsset[];
+};
 export declare function isReleaseInstall(packageRoot: string): boolean;
+export declare function readReleaseInstallInfo(packageRoot: string): ReleaseInstallInfo | undefined;
 export declare function fetchLatestReleaseVersion(_packageName: string, currentVersion: string, timeoutMs: number): Promise<string | undefined>;
-export declare function releaseUpdateHint(): string;
+export declare function fetchLatestStableRelease(currentVersion: string, timeoutMs: number): Promise<StableGitHubRelease | undefined>;
+export declare function releaseUpdateHint(packageRoot?: string): string;

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

@@ -1,12 +1,35 @@
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 export const PIX_RELEASES_URL = "https://github.com/dnaroid/pix/releases/latest";
+export const PIX_RELEASES_API_URL = "https://api.github.com/repos/dnaroid/pix/releases/latest";
+export const PIX_RELEASE_TARGETS = ["linux-x64", "macos-arm64", "macos-x64", "windows-x64"];
 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 function readReleaseInstallInfo(packageRoot) {
+    const marker = join(packageRoot, ".pix-portable.json");
+    if (!existsSync(marker))
+        return undefined;
+    try {
+        const data = JSON.parse(readFileSync(marker, "utf8"));
+        if (data.format !== 2 || typeof data.version !== "string" || !/^\d+\.\d+\.\d+$/u.test(data.version))
+            return undefined;
+        if (typeof data.target !== "string" || !PIX_RELEASE_TARGETS.includes(data.target))
+            return undefined;
+        if (data.variant !== "tui" && data.variant !== "desktop")
+            return undefined;
+        return { version: data.version, target: data.target, variant: data.variant };
+    }
+    catch {
+        return undefined;
+    }
+}
 export async function fetchLatestReleaseVersion(_packageName, currentVersion, timeoutMs) {
-    const response = await fetch("https://api.github.com/repos/dnaroid/pix/releases/latest", {
+    return (await fetchLatestStableRelease(currentVersion, timeoutMs))?.version;
+}
+export async function fetchLatestStableRelease(currentVersion, timeoutMs) {
+    const response = await fetch(PIX_RELEASES_API_URL, {
         headers: { accept: "application/vnd.github+json", "User-Agent": `pix/${currentVersion}` },
         signal: AbortSignal.timeout(timeoutMs),
     });
@@ -17,9 +40,29 @@ export async function fetchLatestReleaseVersion(_packageName, currentVersion, ti
     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;
+    if (typeof data.tag_name !== "string" || !/^v\d+\.\d+\.\d+$/u.test(data.tag_name))
+        return undefined;
+    const assets = Array.isArray(data.assets) ? data.assets.flatMap((entry) => {
+        if (typeof entry !== "object" || entry === null)
+            return [];
+        const asset = entry;
+        if (typeof asset.name !== "string" || typeof asset.browser_download_url !== "string")
+            return [];
+        return [{
+                name: asset.name,
+                url: asset.browser_download_url,
+                ...(typeof asset.size === "number" && Number.isSafeInteger(asset.size) && asset.size >= 0 ? { size: asset.size } : {}),
+            }];
+    }) : [];
+    return { tag: data.tag_name, version: data.tag_name.slice(1), assets };
 }
-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.`;
+export function releaseUpdateHint(packageRoot) {
+    const install = packageRoot ? readReleaseInstallInfo(packageRoot) : undefined;
+    if (install?.variant === "tui") {
+        return "Run `pix update` from a terminal to download, verify, and stage the matching portable release. Pix replaces its installation after the updater process exits; settings and sessions remain in your user profile.";
+    }
+    if (install?.variant === "desktop") {
+        return "Use the Pix Desktop update notification to download, verify, install, and restart the native application. The bundled backend does not mutate npm or portable files.";
+    }
+    return `Download the complete package for your OS/CPU from ${PIX_RELEASES_URL}. The release marker is damaged or too old for safe self-update, so automatic replacement is disabled.`;
 }

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

@@ -1,7 +1,9 @@
+import { schedulePortableTuiUpdate } from "./portable-update.js";
 export { isReleaseInstall } from "./release-update.js";
 type PixUpdateTestDeps = {
     checkPixUpdate: typeof checkPixUpdate;
     runCommand: typeof runCommand;
+    schedulePortableTuiUpdate: typeof schedulePortableTuiUpdate;
 };
 export declare function setPixUpdateTestDeps(overrides?: Partial<PixUpdateTestDeps>): void;
 export type PixUpdateCliOptions = {

package/dist/app/cli/update.js

@@ -3,7 +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";
+import { fetchLatestReleaseVersion, isReleaseInstall, readReleaseInstallInfo, releaseUpdateHint } from "./release-update.js";
+import { schedulePortableTuiUpdate } from "./portable-update.js";
 export { isReleaseInstall } from "./release-update.js";
 const DEFAULT_UPDATE_TIMEOUT_MS = 10_000;
 const NPM_REGISTRY_URL = "https://registry.npmjs.org";
@@ -11,6 +12,7 @@ const PI_PACKAGE_NAME = "@earendil-works/pi-coding-agent";
 const defaultPixUpdateDeps = {
     checkPixUpdate,
     runCommand,
+    schedulePortableTuiUpdate,
 };
 let pixUpdateDeps = defaultPixUpdateDeps;
 export function setPixUpdateTestDeps(overrides) {
@@ -19,15 +21,16 @@ export function setPixUpdateTestDeps(overrides) {
 export function pixUpdateUsage() {
     return `Usage: pix update [--check] [--force]
 
-Check for or install the latest published Pix package and synchronize the global Pi CLI.
+Check for or install the latest Pix release for this installation channel.
 
 Options:
   --check    Only check Pix and global Pi; do not install anything
   --force    Reinstall Pix and its matching global Pi version
   -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.
+Inside the TUI, /update performs the same non-mutating check. Run pix update in a shell to apply a portable TUI update.
+Portable TUI releases are downloaded, checksum-verified, smoke-tested, and atomically replaced after the updater exits.
+Desktop releases update through the native Pix Desktop updater. --force never changes global packages for release 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.`;
 }
@@ -156,9 +159,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}`,
+        const install = readReleaseInstallInfo(result.packageRoot);
+        return [`Pix update (${install?.variant === "desktop" ? "Desktop" : "portable TUI"} GitHub Release)`, `current: ${result.packageName} v${result.currentVersion}`,
             ...(result.latestVersion ? [`latest: ${result.latestVersion}`] : []),
-            `status: ${result.status}${result.reason ? ` (${result.reason})` : ""}`, releaseUpdateHint()].join("\n");
+            `status: ${result.status === "newer" ? "update available" : result.status === "current" ? "up to date" : result.status}${result.reason ? ` (${result.reason})` : ""}`,
+            releaseUpdateHint(result.packageRoot)].join("\n");
     }
     const lines = [
         "Pix update",
@@ -281,8 +286,33 @@ 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;
+        // Release installs are replaced as a unit. Even --force must never modify global packages.
+        if (options.checkOnly)
+            return check.status !== "unknown" && check.status !== "unavailable" ? 0 : 1;
+        const install = readReleaseInstallInfo(check.packageRoot);
+        if (!install) {
+            console.error("Pix cannot safely self-update because its portable release marker is invalid. Download a fresh package from GitHub Releases.");
+            return 1;
+        }
+        if (install.variant === "desktop") {
+            console.error("This Pix backend belongs to Pix Desktop. Use the native Desktop update notification instead of the CLI updater.");
+            return 1;
+        }
+        if (check.status === "current" && !options.force)
+            return 0;
+        if (["skipped", "unknown", "unavailable"].includes(check.status) && !options.force)
+            return 1;
+        try {
+            const update = await pixUpdateDeps.schedulePortableTuiUpdate(check.packageRoot, check.currentVersion);
+            console.log(`Downloaded and verified Pix ${update.version} (${update.assetName}).`);
+            console.log("The portable installation will be replaced atomically after this updater process exits. Start `pix` again after the command returns.");
+            return 0;
+        }
+        catch (error) {
+            console.error(`Portable Pix update failed before replacement: ${error instanceof Error ? error.message : String(error)}`);
+            console.error("The current installation was left unchanged.");
+            return 1;
+        }
     }
     let globalPiCheck = checkGlobalPiInstall(check.packageRoot);
     console.log(`\n${formatGlobalPiCheck(globalPiCheck)}`);

package/docs/release.md

@@ -54,6 +54,25 @@ Pix/ACP/dependency change. `release:smoke` and `release:smoke:desktop` rerun che
 against already built artifacts. These harnesses create temporary user profiles;
 do not invoke `verify.mjs` or the native diagnostic directly with your real HOME.
 
+Desktop release builds also require the Tauri updater signing private key. CI
+reads it from the `TAURI_SIGNING_PRIVATE_KEY` repository secret. A local release
+can provide that environment variable or `TAURI_SIGNING_PRIVATE_KEY_PATH`; the
+release helper also recognizes the ignored local path
+`.artifacts/release-signing/pix-updater.key`. Never commit the private key, and
+keep a durable secure backup: existing Desktop installations cannot accept future
+updates signed by an unrelated replacement key.
+
+For this repository the key pair has already been generated locally and the
+public half is embedded in the release config. Configure Actions with the same
+private key before pushing an updater-enabled release tag:
+
+```bash
+gh secret set TAURI_SIGNING_PRIVATE_KEY < .artifacts/release-signing/pix-updater.key
+```
+
+Do not generate a replacement key merely because the CI secret is missing; that
+would strand clients that already trust the committed public key.
+
 ### Package contents and size checks
 
 The TUI archive includes Pix and its Node runtime, **not ACP**. The Desktop
@@ -94,6 +113,9 @@ The draft is intentional: an unsigned or incomplete first build must not silentl
 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.
+The final release also contains signed Tauri updater artifacts plus `latest.json`;
+the latter is generated only after all four native jobs have supplied the exact
+expected asset set.
 
 ### Optional signing secrets
 
@@ -121,6 +143,14 @@ Keep keys out of the repository and out of release files. Official references:
 [Windows signing](https://v2.tauri.app/distribute/sign/windows/), and
 [Tauri resource bundling](https://v2.tauri.app/develop/resources/).
 
+Tauri updater signing is independent from those OS identities. Configure
+`TAURI_SIGNING_PRIVATE_KEY` with the private minisign-compatible key whose public
+half is embedded in `tauri.release.conf.json`. The release matrix emits `.sig`
+files for Windows NSIS/Linux AppImage and signed `.app.tar.gz` updater bundles for
+both macOS architectures. `latest.json` maps the four Tauri targets to those
+files. OS code-signing warnings may still occur when Developer ID/Authenticode
+credentials are absent even though the updater signature itself is valid.
+
 ## Local release check
 
 ```bash
@@ -221,12 +251,21 @@ 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.
+check stable GitHub Releases instead of npm. `/update` and `pix update --check`
+are non-mutating checks. For a portable TUI install, `pix update` downloads the
+exact OS/CPU archive and `SHA256SUMS`, verifies the digest, validates and smoke
+tests the staged runtime, then schedules a sibling-directory swap after the
+updater process exits. The swap keeps a rollback backup until the new tree takes
+the original path. A damaged marker disables automatic replacement rather than
+falling back to npm.
+
+Packaged Desktop uses Tauri Updater instead of the backend CLI. Production builds
+check `latest.json` at startup and show an Update banner when a newer signed
+version exists. Clicking Update downloads/verifies/installs it with progress;
+macOS/Linux then offer Restart, while Windows lets the passive installer handle
+the restart path. Development builds do not perform this check. Desktop and TUI
+release updates never mutate global npm/Pi packages. 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ui-extend",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Pix: a workspace-first terminal UI for Pi with tabs, readable tool activity, voice input, and bundled agent tools.",
   "private": false,
   "repository": {
@@ -107,12 +107,15 @@
     "@xterm/headless": "^6.0.0",
     "grok-mermaid": "0.2.2",
     "jsonc-parser": "3.3.1",
+    "tar": "^7.5.22",
     "typebox": "1.1.38",
     "vscode-jsonrpc": "^8.2.1",
-    "vscode-languageserver-protocol": "^3.17.5"
+    "vscode-languageserver-protocol": "^3.17.5",
+    "yauzl": "^3.4.0"
   },
   "devDependencies": {
     "@types/node": "24.12.4",
+    "@types/yauzl": "^2.10.3",
     "playwright": "1.62.1",
     "tsx": "4.22.1",
     "typescript": "5.9.3"