pi-ui-extend 1.0.50 → 2.0.1

package/README.md

@@ -123,8 +123,31 @@ 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.
+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)
+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/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

@@ -0,0 +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 fetchLatestStableRelease(currentVersion: string, timeoutMs: number): Promise<StableGitHubRelease | undefined>;
+export declare function releaseUpdateHint(packageRoot?: string): string;

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

@@ -0,0 +1,68 @@
+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) {
+    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),
+    });
+    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;
+    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(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,6 +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 = {
@@ -59,4 +62,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,12 +3,16 @@ 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, 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";
 const PI_PACKAGE_NAME = "@earendil-works/pi-coding-agent";
 const defaultPixUpdateDeps = {
     checkPixUpdate,
     runCommand,
+    schedulePortableTuiUpdate,
 };
 let pixUpdateDeps = defaultPixUpdateDeps;
 export function setPixUpdateTestDeps(overrides) {
@@ -17,14 +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.
+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.`;
 }
@@ -54,7 +60,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 +141,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 +158,13 @@ async function checkPackageUpdate(packageInfo, options) {
     }
 }
 export function formatPixUpdateCheck(result) {
+    if (isReleaseInstall(result.packageRoot)) {
+        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 === "newer" ? "update available" : result.status === "current" ? "up to date" : result.status}${result.reason ? ` (${result.reason})` : ""}`,
+            releaseUpdateHint(result.packageRoot)].join("\n");
+    }
     const lines = [
         "Pix update",
         `current: ${result.packageName} v${result.currentVersion}`,
@@ -204,6 +219,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 +248,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 +285,35 @@ export async function runPixUpdateCli(argv = process.argv.slice(2)) {
     }
     const check = await pixUpdateDeps.checkPixUpdate();
     console.log(formatPixUpdateCheck(check));
+    if (isReleaseInstall(check.packageRoot)) {
+        // 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)}`);
     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,155 @@
 
 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.
+
+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
+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.
+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
+
+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/).
+
+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
@@ -20,7 +169,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 +207,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 +250,23 @@ 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` 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.
 - `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.1",
   "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",
@@ -98,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"