pisper 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kongran Ling and Pisper contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,216 @@
+<p align="right"><a href="./README.md">简体中文</a> · <strong>English</strong></p>
+
+<a id="top"></a>
+
+<p align="center">
+  <img src="docs/brand/pisper-logo.svg" width="112" alt="Pisper project logo" />
+</p>
+
+<h1 align="center">Pisper</h1>
+
+<p align="center"><strong>A multi-Agent workspace powered by Pi</strong></p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Node.js-17141F?style=flat-square&logo=nodedotjs&logoColor=F59E0B" alt="Node.js" />
+  <img src="https://img.shields.io/badge/TypeScript-17141F?style=flat-square&logo=typescript&logoColor=F59E0B" alt="TypeScript" />
+  <img src="https://img.shields.io/badge/React-17141F?style=flat-square&logo=react&logoColor=F59E0B" alt="React" />
+  <img src="https://img.shields.io/badge/Tauri-17141F?style=flat-square&logo=tauri&logoColor=F59E0B" alt="Tauri" />
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-F59E0B?style=flat-square" alt="MIT License" /></a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/ling-kong-ran/pisper/releases/latest">
+    <img src="https://img.shields.io/badge/Download%20Desktop-Windows%20%7C%20macOS%20%7C%20Linux-F59E0B?style=for-the-badge&logo=github&logoColor=17141F" alt="Download Pisper desktop" />
+  </a>
+</p>
+
+<a id="sponsors"></a>
+
+## ❤️ Sponsors
+
+Thanks to the following partners for supporting the Pisper community. If you'd like to appear here too, feel free to reach out via [Issues](https://github.com/ling-kong-ran/pisper/issues).
+
+<details open>
+<summary>View sponsors</summary>
+
+<table>
+<tr>
+<td width="180" align="center">
+  <a href="https://matrix.000328.xyz/sign-up?aff=ZPeH"><strong>Matrix</strong></a>
+</td>
+<td>
+Thanks to <a href="https://matrix.000328.xyz/sign-up?aff=ZPeH">Matrix</a> for supporting the Pisper community. Registering through <a href="https://matrix.000328.xyz/sign-up?aff=ZPeH">this link</a> may generate referral revenue for the project.
+</td>
+</tr>
+</table>
+
+> Sponsor links contain a referral parameter. Sponsor content is not targeted using conversations, workspaces, providers, models, or API configuration, and Pisper does not send that data to sponsors. The public configuration for the in-app sponsor placement is maintained in [`docs/sponsors.json`](./docs/sponsors.json).
+
+</details>
+
+<p align="center">
+  <a href="#overview">Overview</a> ·
+  <a href="https://ling-kong-ran.github.io/pisper/">Project Site</a> ·
+  <a href="#features">Features</a> ·
+  <a href="#data-safety">Data Safety</a> ·
+  <a href="#desktop-pet">Desktop Pet</a> ·
+  <a href="#install">Install</a> ·
+  <a href="#tui">Terminal Client</a> ·
+  <a href="#development">Development</a> ·
+  <a href="#sponsors">Sponsors</a> ·
+  <a href="#license">License</a>
+</p>
+
+---
+
+<a id="overview"></a>
+
+## Overview
+
+Pisper is a desktop and terminal client built on [Pi Coding Agent](https://github.com/earendil-works/pi/tree/main/packages/coding-agent), with multiple sessions, Tools, Skills, MCP, automation, and per-session permissions.
+
+See the [Pisper project site](https://ling-kong-ran.github.io/pisper/) for the product overview and interface preview.
+
+### Get Started in Three Steps
+
+1. [Download the desktop app](https://github.com/ling-kong-ran/pisper/releases/latest) (Windows / macOS / Linux, no Node.js required)
+2. Configure any model provider with an API key
+3. Create a session and start working in parallel
+
+<a id="features"></a>
+
+## Features
+
+- **Multiple sessions:** independent models, context, workspaces, and permissions with Dock splits and layout restoration.
+- **Tools, Skills, and MCP:** manage capabilities and call permissions in one place.
+- **Subagents:** run temporary tasks in isolated contexts and return results to the parent session.
+- **Memory and multimodal input:** retrieve project memory and process images, documents, and code.
+- **Automation and channels:** schedules, visual workflows, Feishu, and personal Weixin.
+- **Desktop and terminal:** Tauri desktop app and Ratatui TUI.
+- **Permission controls:** `Read only / Full access` execution modes, one-shot approval, and credential isolation.
+
+<a id="data-safety"></a>
+
+## Data Safety & Privacy
+
+Pisper is local-first and does not provide a Pisper cloud service that hosts or relays your conversations. Sessions, memory, workflows, schedules, usage, and connection settings are stored under `~/.pisper/agent` by default. Set `PISPER_AGENT_DIR` to move this data root.
+
+- **Protected local service:** the desktop Runtime listens on `127.0.0.1` by default and uses a random bootstrap token, an `HttpOnly` / `SameSite=Strict` cookie, and Origin checks for write requests. Pi telemetry is disabled by default.
+- **Known-secret redaction:** known formats such as API keys, Bearer/JWT values, common access tokens, private keys, and database connection strings are replaced before memory persistence, secondary model-based memory extraction, and display boundaries including errors, MCP configuration, and approval summaries. Redacted values appear as `[REDACTED SECRET]` or `***`.
+- **Credential isolation:** Provider credentials, MCP headers/environment variables, and channel credentials stay in local configuration and are not echoed to the Agent through normal configuration APIs. The host Shell tool also removes common credential and Shell-injection environment variables.
+- **Controllable memory:** automatically inferred conversation memories remain pending and cannot affect recall until confirmed. You can reject candidates, delete individual memories, or delete sessions; deletion removes the associated content and retrieval data.
+- **Explicit outbound boundaries:** regular prompts, attachments, and tool results are not globally rewritten or anonymized. Model calls send the required context directly to your configured Provider. Remote MCP, Web search, image/video generation, and messaging channels send their corresponding requests to those third parties only when enabled and used. Model-based memory extraction and semantic summaries apply the known-format redaction above before calling the active Provider.
+
+> **Important boundary:** redaction is defense in depth against accidental disclosure of common credential formats. It is not complete DLP, a sandbox, or end-to-end encryption, and it cannot recognize every sensitive value in free-form text. Provider and channel credentials currently live in the local Agent data directory rather than an operating-system keychain. Protect that directory and its backups, review prompts, files, and tool arguments before sending, and follow the privacy policy of each configured third party.
+
+<a id="desktop-pet"></a>
+
+## Desktop Pet
+
+Pisper supports [Petdex](https://petdex.dev)-compatible pets. Install and manage them under **Settings → Desktop pet**. See [`docs/petdex-integration.md`](./docs/petdex-integration.md).
+
+<a id="install"></a>
+
+## Install
+
+### Desktop (Recommended)
+
+Download a Windows, macOS, or Linux installer from [GitHub Releases](https://github.com/ling-kong-ran/pisper/releases/latest). It works out of the box — no separate Node.js install is required.
+
+#### If macOS Refuses to Open Pisper
+
+Pisper is not currently notarized by Apple. Confirm that it came from the official Releases page, then select **Open Anyway** in **System Settings → Privacy & Security**. If that option is unavailable, run:
+
+```bash
+sudo xattr -rd com.apple.quarantine /Applications/Pisper.app
+```
+
+Use this command only for Pisper downloaded from the official Releases page and placed in `/Applications`.
+
+#### If the Linux AppImage Does Not Start
+
+```bash
+chmod +x Pisper_*_linux_x86_64.AppImage
+./Pisper_*_linux_x86_64.AppImage
+```
+
+If FUSE is missing, install `libfuse2` or `libfuse2t64`, or use the `.deb` package:
+
+```bash
+sudo apt install ./Pisper-*-linux-amd64.deb
+```
+
+### Component Updates
+
+**Settings → Updates** in the desktop app is the unified update entry point. A single **Check for updates** action checks the Desktop package, TUI client, and Runtime together. Install controls appear only for components with a newer version, so a small component update does not require downloading the full desktop installer. Each component uses an independent signed Release channel. Runtime updates take effect after restarting the app, and Pisper falls back to the versions bundled with the desktop package if an installed component is unavailable or fails to start.
+
+<a id="tui"></a>
+
+### Terminal Client (TUI)
+
+With Node.js 20+, you can install the Pisper CLI through npm:
+
+```bash
+npm install -g pisper
+pisper
+```
+
+After installing the desktop app, you can also install the `pisper` command from **Settings → Terminal**. The first installation remains explicit; after later desktop updates restart Pisper, it automatically refreshes this managed terminal client:
+
+```bash
+pisper          # start a new conversation
+pisper resume   # resume from an interactive list across all workspaces
+pisper doctor   # diagnose the runtime
+```
+
+See the **[Pisper TUI user guide](./src-tui/README.en.md)** for installation, commands, keyboard controls, attachments, execution modes, and approvals.
+
+### Run from Source
+
+Requires Node.js 20+, npm, and at least one model provider with an API key.
+
+```bash
+git clone https://github.com/ling-kong-ran/pisper.git
+cd pisper
+npm install
+npm run dev
+```
+
+Desktop development and packaging:
+
+```bash
+npm run desktop:webview:dev
+npm run desktop:webview:build
+```
+
+Data is stored under `~/.pisper/agent` by default. Set `PISPER_AGENT_DIR` to use another location.
+
+<a id="development"></a>
+
+## Development
+
+Main stack: React, TypeScript, Tauri, Rust, Node SEA, and Pi Coding Agent.
+
+```bash
+npm run check
+npm test
+npm run build
+```
+
+[Issues](https://github.com/ling-kong-ran/pisper/issues) and [pull requests](https://github.com/ling-kong-ran/pisper/pulls) are welcome. Do not commit API keys, bot credentials, or personal data from `~/.pisper/agent`.
+
+<a id="license"></a>
+
+## License
+
+Pisper is released under the [MIT License](./LICENSE). Third-party dependencies and community resources retain their own licenses.
+
+## Acknowledgments
+
+Thanks to [Pi Coding Agent](https://github.com/earendil-works/pi/tree/main/packages/coding-agent), [Petdex](https://petdex.dev), and the open-source software used by this project.
+
+Contributors:
+
+- [@mik-myp](https://github.com/mik-myp) — Frontend TypeScript architecture, shadcn/ui / AI Elements, Zustand, and i18n refactor ([#1](https://github.com/ling-kong-ran/pisper/pull/1))
+
+<p align="right"><a href="#top">Back to top ↑</a></p>

package/README.md

@@ -0,0 +1,216 @@
+<p align="right"><strong>简体中文</strong> · <a href="./README.en.md">English</a></p>
+
+<a id="top"></a>
+
+<p align="center">
+  <img src="docs/brand/pisper-logo.svg" width="112" alt="Pisper 项目标志" />
+</p>
+
+<h1 align="center">Pisper</h1>
+
+<p align="center"><strong>Pi 驱动的多 Agent 工作台</strong></p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Node.js-17141F?style=flat-square&logo=nodedotjs&logoColor=F59E0B" alt="Node.js" />
+  <img src="https://img.shields.io/badge/TypeScript-17141F?style=flat-square&logo=typescript&logoColor=F59E0B" alt="TypeScript" />
+  <img src="https://img.shields.io/badge/React-17141F?style=flat-square&logo=react&logoColor=F59E0B" alt="React" />
+  <img src="https://img.shields.io/badge/Tauri-17141F?style=flat-square&logo=tauri&logoColor=F59E0B" alt="Tauri" />
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-F59E0B?style=flat-square" alt="MIT License" /></a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/ling-kong-ran/pisper/releases/latest">
+    <img src="https://img.shields.io/badge/下载桌面版-Windows%20%7C%20macOS%20%7C%20Linux-F59E0B?style=for-the-badge&logo=github&logoColor=17141F" alt="下载 Pisper 桌面版" />
+  </a>
+</p>
+
+<a id="sponsors"></a>
+
+## ❤️ 赞助
+
+感谢以下合作伙伴对 Pisper 社区的支持。如果你也希望出现在这里，欢迎通过 [Issue](https://github.com/ling-kong-ran/pisper/issues) 联系我们。
+
+<details open>
+<summary>查看赞助商</summary>
+
+<table>
+<tr>
+<td width="180" align="center">
+  <a href="https://matrix.000328.xyz/sign-up?aff=ZPeH"><strong>Matrix</strong></a>
+</td>
+<td>
+感谢 <a href="https://matrix.000328.xyz/sign-up?aff=ZPeH">Matrix</a> 对 Pisper 社区的支持。通过<a href="https://matrix.000328.xyz/sign-up?aff=ZPeH">此链接</a>注册，可能为 Pisper 项目带来推广收益。
+</td>
+</tr>
+</table>
+
+> 赞助链接包含推广参数。Pisper 的赞助内容不会使用会话、工作区、Provider、模型或 API 配置进行定向，也不会向赞助商发送这些数据。客户端赞助位的公开配置维护在 [`docs/sponsors.json`](./docs/sponsors.json)。
+
+</details>
+
+<p align="center">
+  <a href="#overview">简介</a> ·
+  <a href="https://ling-kong-ran.github.io/pisper/">项目主页</a> ·
+  <a href="#features">功能</a> ·
+  <a href="#data-safety">数据安全</a> ·
+  <a href="#desktop-pet">桌面宠物</a> ·
+  <a href="#install">安装</a> ·
+  <a href="#tui">终端客户端</a> ·
+  <a href="#development">开发</a> ·
+  <a href="#sponsors">赞助</a> ·
+  <a href="#license">许可</a>
+</p>
+
+---
+
+<a id="overview"></a>
+
+## 简介
+
+Pisper 是基于 [Pi Coding Agent](https://github.com/earendil-works/pi/tree/main/packages/coding-agent) 的桌面与终端客户端，支持多会话、工具、Skills、MCP、自动化和会话级权限。
+
+产品介绍与界面预览：[Pisper 项目主页](https://ling-kong-ran.github.io/pisper/)。
+
+### 三步上手
+
+1. [下载桌面版](https://github.com/ling-kong-ran/pisper/releases/latest)（Windows / macOS / Linux）
+2. 配置任意一个模型 Provider 与 API Key
+3. 新建会话，开始并行工作
+
+<a id="features"></a>
+
+## 功能
+
+- **多会话**：独立模型、上下文、工作目录和权限，支持 Dock 分屏与布局恢复。
+- **Tools、Skills 与 MCP**：统一管理能力和调用权限。
+- **Subagent**：在隔离上下文中执行临时任务，完成后将结果返回父会话。
+- **记忆与多模态**：检索项目记忆，处理图片、文档和代码。
+- **自动化与渠道**：定时任务、可视化工作流、飞书和个人微信。
+- **桌面与终端**：提供 Tauri 桌面端和 Ratatui TUI。
+- **权限控制**：支持 `只读 / 完全访问` 两种执行模式，并提供单次审批和凭据隔离。
+
+<a id="data-safety"></a>
+
+## 数据安全与隐私
+
+Pisper 是本地优先应用，不提供用于托管或中转会话的 Pisper 云服务。会话、记忆、工作流、日程、用量和连接配置默认保存在本机 `~/.pisper/agent`；可通过 `PISPER_AGENT_DIR` 更改位置。
+
+- **本地服务保护**：桌面 Runtime 默认只监听 `127.0.0.1`，使用随机启动 Token、`HttpOnly` / `SameSite=Strict` Cookie 和写请求 Origin 校验；Pi 遥测默认关闭。
+- **已知敏感信息脱敏**：API Key、Bearer/JWT、常见访问令牌、私钥和数据库连接串等已知格式，会在记忆落盘、记忆二次模型提取，以及错误、MCP 配置和审批摘要等展示边界进入前被替换。脱敏后的内容使用 `[REDACTED SECRET]` 或 `***` 标记。
+- **凭据隔离**：Provider 凭据、MCP Header/环境变量和渠道凭据保存在本机配置中，不通过普通配置接口回显给 Agent；宿主 Shell 工具也会移除常见凭据环境变量和 Shell 注入变量。
+- **记忆可控**：自动推断的会话记忆先进入待确认区，未确认前不参与召回；用户可以拒绝候选、删除单条记忆或删除会话，删除操作会清除对应正文与检索数据。
+- **外发边界明确**：普通 Prompt、附件、工具结果不会被全局改写或匿名化。调用模型时，必要上下文会直接发送到你配置的 Provider；启用远程 MCP、Web 搜索、图像/视频生成或消息渠道时，相应请求也会发送给该第三方。记忆提取和语义摘要如使用模型，会先执行上述已知格式脱敏，再调用当前 Provider。
+
+> **重要边界：** 脱敏是降低常见凭据意外泄露风险的纵深防护，不是完整的 DLP、沙箱或端到端加密，也无法识别所有自由文本中的敏感数据。Provider 和渠道凭据目前保存在本机 Agent 数据目录，而不是操作系统钥匙串；请保护该目录与备份，并在发送前检查 Prompt、文件和工具参数，同时遵守所选第三方的隐私政策。
+
+<a id="desktop-pet"></a>
+
+## 桌面宠物
+
+Pisper 支持 [Petdex](https://petdex.dev) 兼容宠物，可在 **设置 → 桌面宠物** 中安装和管理。详见 [`docs/petdex-integration.md`](./docs/petdex-integration.md)。
+
+<a id="install"></a>
+
+## 安装
+
+### 桌面版（推荐）
+
+前往 [GitHub Releases](https://github.com/ling-kong-ran/pisper/releases/latest) 下载 Windows、macOS 或 Linux 安装包，开箱即用，无需额外安装 Node.js。
+
+#### macOS 无法打开
+
+Pisper 当前尚未经过 Apple 公证。请确认应用来自官方 Releases，并优先在 **系统设置 → 隐私与安全性** 中选择 **仍要打开**。若没有该选项，可执行：
+
+```bash
+sudo xattr -rd com.apple.quarantine /Applications/Pisper.app
+```
+
+请仅对从官方 Releases 下载并放入 `/Applications` 的应用使用此命令。
+
+#### Linux AppImage 无法启动
+
+```bash
+chmod +x Pisper_*_linux_x86_64.AppImage
+./Pisper_*_linux_x86_64.AppImage
+```
+
+缺少 FUSE 时安装 `libfuse2` 或 `libfuse2t64`，也可改用 `.deb`：
+
+```bash
+sudo apt install ./Pisper-*-linux-amd64.deb
+```
+
+### 分块更新
+
+桌面端的 **设置 → 更新** 是统一更新入口。点击一次 **检查更新** 会同时检查 Desktop、TUI 客户端和 Runtime；只有发现新版本的组件才会显示安装操作，因此小范围更新不必重新下载完整桌面安装包。三个组件使用独立的签名 Release 通道，Runtime 更新在重启应用后生效；独立组件不可用或启动失败时，Pisper 会继续使用桌面安装包内置的版本。
+
+<a id="tui"></a>
+
+### 终端客户端（TUI）
+
+使用 Node.js 20+ 时，也可通过 npm 安装 Pisper CLI：
+
+```bash
+npm install -g pisper
+pisper
+```
+
+安装桌面版后，也可以在 **设置 → 终端** 中安装 `pisper` 命令。首次安装由你主动确认；之后桌面应用更新并重启时，Pisper 会自动刷新这份已托管的终端客户端：
+
+```bash
+pisper          # 新建会话
+pisper resume   # 从所有工作目录的交互列表中恢复会话
+pisper doctor   # 诊断运行环境
+```
+
+安装、命令、快捷键、附件、执行模式和审批说明见 **[Pisper TUI 使用指南](./src-tui/README.md)**。
+
+### 从源码运行
+
+需要 Node.js 20+、npm，以及至少一个模型 Provider 与 API Key。
+
+```bash
+git clone https://github.com/ling-kong-ran/pisper.git
+cd pisper
+npm install
+npm run dev
+```
+
+桌面开发与打包：
+
+```bash
+npm run desktop:webview:dev
+npm run desktop:webview:build
+```
+
+数据默认保存在 `~/.pisper/agent`，可通过 `PISPER_AGENT_DIR` 修改。
+
+<a id="development"></a>
+
+## 开发
+
+主要技术栈：React、TypeScript、Tauri、Rust、Node SEA 与 Pi Coding Agent。
+
+```bash
+npm run check
+npm test
+npm run build
+```
+
+欢迎提交 [Issue](https://github.com/ling-kong-ran/pisper/issues) 与 [Pull Request](https://github.com/ling-kong-ran/pisper/pulls)。请勿提交 API Key、机器人凭据，或 `~/.pisper/agent` 中的个人数据。
+
+<a id="license"></a>
+
+## 许可
+
+Pisper 采用 [MIT License](./LICENSE)。第三方依赖和社区资源遵循各自许可证。
+
+## 致谢
+
+感谢 [Pi Coding Agent](https://github.com/earendil-works/pi/tree/main/packages/coding-agent)、[Petdex](https://petdex.dev) 及本项目使用的开源软件。
+
+贡献者：
+
+- [@mik-myp](https://github.com/mik-myp) — 前端 TypeScript 架构、shadcn/ui / AI Elements、Zustand 与 i18n 重构（[#1](https://github.com/ling-kong-ran/pisper/pull/1)）
+
+<p align="right"><a href="#top">返回顶部 ↑</a></p>

package/bin/pisper.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process'
+import process from 'node:process'
+import { ensurePisperInstallation } from '../lib/install.mjs'
+
+try {
+  const installation = await ensurePisperInstallation()
+  const child = spawn(installation.executable, process.argv.slice(2), {
+    env: {
+      ...process.env,
+      PISPER_APP_ROOT: installation.appRoot,
+      PISPER_DISTRIBUTION: 'npm',
+      PISPER_SIDECAR_PATH: installation.sidecar,
+    },
+    stdio: 'inherit',
+    windowsHide: false,
+  })
+
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+    process.on(signal, () => {
+      if (!child.killed) child.kill(signal)
+    })
+  }
+
+  child.once('error', (error) => {
+    console.error(`pisper: failed to start the terminal client: ${error.message}`)
+    process.exitCode = 1
+  })
+  child.once('exit', (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal)
+      return
+    }
+    process.exitCode = code ?? 1
+  })
+} catch (error) {
+  console.error(`pisper: ${error instanceof Error ? error.message : String(error)}`)
+  process.exitCode = 1
+}

package/lib/install.mjs

@@ -0,0 +1,301 @@
+import { chmod, mkdir, open, readFile, rename, rm, stat, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+import { PublicKey, Signature } from '@threema/wasm-minisign-verify'
+import { x as extractTar } from 'tar'
+import {
+  componentsRoot,
+  executableName,
+  releaseArchitecture,
+  releasePlatform,
+  supportedTarget,
+} from './platform.mjs'
+
+const packageRoot = fileURLToPath(new URL('..', import.meta.url))
+const packageManifest = JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8'))
+const repository = packageManifest.pisper?.repository
+const tuiVersion = packageManifest.pisper?.tuiVersion
+const runtimeVersion = packageManifest.pisper?.runtimeVersion
+const MAX_ARCHIVE_BYTES = 128 * 1024 * 1024
+const INSTALL_WAIT_MS = 600_000
+
+for (const [label, value] of [
+  ['TUI', tuiVersion],
+  ['Runtime', runtimeVersion],
+]) {
+  if (!/^\d+\.\d+\.\d+$/.test(value || '')) {
+    throw new Error(`pisper package metadata does not contain a valid ${label} version`)
+  }
+}
+if (!/^[\w.-]+\/[\w.-]+$/.test(repository || '')) {
+  throw new Error('pisper package metadata does not contain a valid repository')
+}
+
+function decodeWrapped(value) {
+  const trimmed = String(value).trim()
+  if (trimmed.startsWith('untrusted comment:')) return trimmed
+  if (!/^[A-Za-z0-9+/=\r\n]+$/.test(trimmed)) return trimmed
+  const decoded = Buffer.from(trimmed.replace(/\s/g, ''), 'base64').toString('utf8').trim()
+  return decoded.startsWith('untrusted comment:') ? decoded : trimmed
+}
+
+function componentAsset(component, version, platform, arch) {
+  const target = supportedTarget(platform, arch)
+  const label = component === 'tui' ? 'TUI_Component' : 'Runtime'
+  return `Pisper_${label}_${version}_${target}.tar.gz`
+}
+
+function componentUrls({ component, version, platform, arch, baseUrl }) {
+  const asset = componentAsset(component, version, platform, arch)
+  const root = baseUrl
+    ? String(baseUrl).replace(/\/$/, '')
+    : `https://github.com/${repository}/releases/download/${component}-v${version}`
+  return { archive: `${root}/${asset}`, signature: `${root}/${asset}.sig` }
+}
+
+export function releaseAsset(
+  version = tuiVersion,
+  platform = process.platform,
+  arch = process.arch,
+) {
+  return componentAsset('tui', version, platform, arch)
+}
+
+export function releaseAssetUrls({
+  version = tuiVersion,
+  platform = process.platform,
+  arch = process.arch,
+  baseUrl = process.env.PISPER_CLI_DOWNLOAD_BASE_URL,
+} = {}) {
+  return componentUrls({ component: 'tui', version, platform, arch, baseUrl })
+}
+
+function compareVersions(left, right) {
+  const a = left.split('.').map(Number)
+  const b = right.split('.').map(Number)
+  for (let index = 0; index < 3; index += 1) {
+    if (a[index] !== b[index]) return a[index] - b[index]
+  }
+  return 0
+}
+
+async function isFile(path) {
+  try {
+    return (await stat(path)).isFile()
+  } catch (error) {
+    if (error?.code === 'ENOENT') return false
+    throw error
+  }
+}
+
+function commandName(component) {
+  if (component === 'tui') return executableName()
+  return process.platform === 'win32' ? 'pisper-sidecar.exe' : 'pisper-sidecar'
+}
+
+async function validateComponent(component, version, destination) {
+  const executable = join(destination, commandName(component))
+  if (!(await isFile(executable))) return ''
+  if (
+    component === 'runtime' &&
+    !(await isFile(join(destination, 'sidecar-runtime', 'package.json')))
+  ) {
+    return ''
+  }
+  try {
+    const manifest = JSON.parse(await readFile(join(destination, 'manifest.json'), 'utf8'))
+    if (
+      manifest.version !== version ||
+      manifest.platform !== releasePlatform() ||
+      manifest.arch !== releaseArchitecture() ||
+      manifest.command !== commandName(component)
+    ) {
+      return ''
+    }
+  } catch {
+    return ''
+  }
+  return executable
+}
+
+async function resolveCurrentComponent(root, component, minimumVersion) {
+  try {
+    const pointer = JSON.parse(await readFile(join(root, component, 'current.json'), 'utf8'))
+    if (!/^\d+\.\d+\.\d+$/.test(pointer.version || '')) return null
+    if (compareVersions(pointer.version, minimumVersion) < 0) return null
+    const destination = join(root, component, 'versions', pointer.version)
+    const executable = await validateComponent(component, pointer.version, destination)
+    return executable ? { version: pointer.version, destination, executable } : null
+  } catch (error) {
+    if (error?.code === 'ENOENT' || error instanceof SyntaxError) return null
+    throw error
+  }
+}
+
+async function download(url) {
+  const response = await fetch(url, {
+    headers: { 'User-Agent': `pisper/${packageManifest.version}` },
+    redirect: 'follow',
+    signal: AbortSignal.timeout(600_000),
+  })
+  if (!response.ok) throw new Error(`download failed with HTTP ${response.status}: ${url}`)
+  const declaredSize = Number(response.headers.get('content-length') || 0)
+  if (declaredSize > MAX_ARCHIVE_BYTES) {
+    throw new Error(`download is larger than ${MAX_ARCHIVE_BYTES} bytes`)
+  }
+  const bytes = Buffer.from(await response.arrayBuffer())
+  if (bytes.length === 0) throw new Error(`downloaded an empty file: ${url}`)
+  if (bytes.length > MAX_ARCHIVE_BYTES) {
+    throw new Error(`download is larger than ${MAX_ARCHIVE_BYTES} bytes`)
+  }
+  return bytes
+}
+
+async function verifyArchive(component, archive, signatureBytes) {
+  const publicKeyText = await readFile(join(packageRoot, 'updater.pubkey'), 'utf8')
+  const publicKey = PublicKey.decode(decodeWrapped(publicKeyText))
+  const signature = Signature.decode(decodeWrapped(signatureBytes.toString('utf8')))
+  try {
+    if (!publicKey.verify(archive, signature)) {
+      throw new Error('signature verification returned false')
+    }
+  } catch (error) {
+    throw new Error(`${component} archive signature verification failed: ${error.message}`, {
+      cause: error,
+    })
+  } finally {
+    signature.free()
+    publicKey.free()
+  }
+}
+
+async function wait(milliseconds) {
+  await new Promise((resolve) => setTimeout(resolve, milliseconds))
+}
+
+async function acquireLock(lockPath, validate) {
+  const deadline = Date.now() + INSTALL_WAIT_MS
+  while (true) {
+    try {
+      return await open(lockPath, 'wx')
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error
+      if (await validate()) return null
+      if (Date.now() >= deadline) {
+        throw new Error('timed out waiting for another Pisper installer')
+      }
+      await wait(250)
+    }
+  }
+}
+
+async function activateComponent(root, component, version) {
+  const componentRoot = join(root, component)
+  const pointer = join(componentRoot, 'current.json')
+  const temporary = join(componentRoot, `current.json.tmp-${process.pid}`)
+  await mkdir(componentRoot, { recursive: true })
+  await writeFile(temporary, `${JSON.stringify({ version }, null, 2)}\n`, 'utf8')
+  await rm(pointer, { force: true })
+  await rename(temporary, pointer)
+}
+
+async function installComponent({ root, component, version, destination, activate = false }) {
+  const lockRoot = join(root, 'npm')
+  await mkdir(lockRoot, { recursive: true })
+  const lockPath = join(lockRoot, `${component}-install.lock`)
+  const validate = () => validateComponent(component, version, destination)
+  const lock = await acquireLock(lockPath, validate)
+  if (!lock) {
+    if (activate) await activateComponent(root, component, version)
+    return { version, destination, executable: await validate() }
+  }
+
+  const staging = `${destination}.tmp-${process.pid}-${Date.now()}`
+  const archivePath = `${staging}.tar.gz`
+  try {
+    const existing = await validate()
+    if (existing) {
+      if (activate) await activateComponent(root, component, version)
+      return { version, destination, executable: existing }
+    }
+    await rm(staging, { recursive: true, force: true })
+    await mkdir(staging, { recursive: true })
+    const urls = componentUrls({
+      component,
+      version,
+      platform: process.platform,
+      arch: process.arch,
+      baseUrl: process.env.PISPER_CLI_DOWNLOAD_BASE_URL,
+    })
+    const [archive, signature] = await Promise.all([
+      download(urls.archive),
+      download(urls.signature),
+    ])
+    await verifyArchive(component, archive, signature)
+    await writeFile(archivePath, archive, { mode: 0o600 })
+    await extractTar({
+      cwd: staging,
+      file: archivePath,
+      preservePaths: false,
+      strict: true,
+      strip: 1,
+      filter: (_path, entry) => entry.type === 'File' || entry.type === 'Directory',
+    })
+    if (process.platform !== 'win32') await chmod(join(staging, commandName(component)), 0o755)
+    const stagedExecutable = await validateComponent(component, version, staging)
+    if (!stagedExecutable) {
+      throw new Error(`downloaded ${component} archive has an invalid package layout`)
+    }
+    await mkdir(dirname(destination), { recursive: true })
+    await rm(destination, { recursive: true, force: true })
+    await rename(staging, destination)
+    if (activate) await activateComponent(root, component, version)
+    return { version, destination, executable: join(destination, commandName(component)) }
+  } finally {
+    await lock.close()
+    await Promise.all([
+      rm(lockPath, { force: true }),
+      rm(staging, { recursive: true, force: true }),
+      rm(archivePath, { force: true }),
+    ])
+  }
+}
+
+export async function ensurePisperInstallation() {
+  const root = componentsRoot()
+  const npmTuiDestination = join(root, 'npm', 'versions', tuiVersion)
+  const runtimeDestination = join(root, 'runtime', 'versions', runtimeVersion)
+  const [tui, runtime] = await Promise.all([
+    resolveCurrentComponent(root, 'tui', tuiVersion).then(
+      (current) =>
+        current ||
+        installComponent({
+          root,
+          component: 'tui',
+          version: tuiVersion,
+          destination: npmTuiDestination,
+        }),
+    ),
+    resolveCurrentComponent(root, 'runtime', runtimeVersion).then(
+      (current) =>
+        current ||
+        installComponent({
+          root,
+          component: 'runtime',
+          version: runtimeVersion,
+          destination: runtimeDestination,
+          activate: true,
+        }),
+    ),
+  ])
+  return {
+    executable: tui.executable,
+    sidecar: runtime.executable,
+    appRoot: join(runtime.destination, 'sidecar-runtime'),
+  }
+}
+
+export async function ensurePisperExecutable() {
+  return (await ensurePisperInstallation()).executable
+}

package/lib/platform.mjs

@@ -0,0 +1,43 @@
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import process from 'node:process'
+
+export function releasePlatform(platform = process.platform) {
+  if (platform === 'win32') return 'windows'
+  if (platform === 'darwin') return 'darwin'
+  if (platform === 'linux') return 'linux'
+  throw new Error(`unsupported operating system: ${platform}`)
+}
+
+export function releaseArchitecture(arch = process.arch) {
+  if (arch === 'x64') return 'x86_64'
+  if (arch === 'arm64') return 'aarch64'
+  throw new Error(`unsupported CPU architecture: ${arch}`)
+}
+
+export function supportedTarget(platform = process.platform, arch = process.arch) {
+  const target = `${releasePlatform(platform)}_${releaseArchitecture(arch)}`
+  const supported = new Set(['windows_x86_64', 'darwin_x86_64', 'darwin_aarch64', 'linux_x86_64'])
+  if (!supported.has(target)) {
+    throw new Error(`Pisper does not publish a TUI package for ${target}`)
+  }
+  return target
+}
+
+export function executableName(platform = process.platform) {
+  return platform === 'win32' ? 'pisper.exe' : 'pisper'
+}
+
+export function localDataDirectory(platform = process.platform, env = process.env) {
+  if (env.PISPER_NPM_INSTALL_DIR) return env.PISPER_NPM_INSTALL_DIR
+  if (platform === 'win32') {
+    if (!env.LOCALAPPDATA) throw new Error('LOCALAPPDATA is unavailable')
+    return env.LOCALAPPDATA
+  }
+  if (platform === 'darwin') return join(homedir(), 'Library', 'Application Support')
+  return env.XDG_DATA_HOME || join(homedir(), '.local', 'share')
+}
+
+export function componentsRoot(platform = process.platform, env = process.env) {
+  return join(localDataDirectory(platform, env), 'com.lingkongran.pisper', 'components')
+}

package/lib/postinstall.mjs

@@ -0,0 +1,15 @@
+import process from 'node:process'
+import { ensurePisperInstallation } from './install.mjs'
+
+if (process.env.PISPER_CLI_SKIP_INSTALL !== '1') {
+  try {
+    const installation = await ensurePisperInstallation()
+    console.log(`pisper: installed the signed Pisper terminal client at ${installation.executable}`)
+  } catch (error) {
+    console.warn(
+      `pisper: deferred terminal client download until the first pisper command: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    )
+  }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "pisper",
+  "version": "0.0.1",
+  "description": "Pisper CLI.",
+  "license": "MIT",
+  "author": {
+    "name": "ling-kong-ran",
+    "email": "65328093+ling-kong-ran@users.noreply.github.com",
+    "url": "https://github.com/ling-kong-ran"
+  },
+  "type": "module",
+  "homepage": "https://github.com/ling-kong-ran/pisper#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ling-kong-ran/pisper.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ling-kong-ran/pisper/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "pisper": "bin/pisper.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "updater.pubkey",
+    "README.md",
+    "README.en.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "postinstall": "node lib/postinstall.mjs"
+  },
+  "dependencies": {
+    "@threema/wasm-minisign-verify": "0.1.3",
+    "tar": "7.5.22"
+  },
+  "pisper": {
+    "repository": "ling-kong-ran/pisper",
+    "tuiVersion": "0.4.28",
+    "runtimeVersion": "0.4.29"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/updater.pubkey

@@ -0,0 +1 @@
+dW50cnVzdGVkIGNvbW1lbnQ6IG1pbmlzaWduIHB1YmxpYyBrZXk6IEYwRTUzMkExNjAyRUNGQTQKUldTa3p5NWdvVExsOEQ5TElOa3BVcUxZQ2I1RlNieHJHeFQ3YVdqeTRMK0VKS2dWSlZsMXRNazQK