pisper 0.5.30-linux-x64.0 → 0.5.30

package/README.en.md

@@ -0,0 +1,61 @@
+# Pisper TUI Command Reference
+
+[Project home](https://ling-kong-ran.github.io/pisper/) · [GitHub repository](https://github.com/ling-kong-ran/pisper) · [中文](./README.md)
+
+Argument notation: `<argument>` is required; `[argument]` is optional.
+
+## CLI Commands
+
+| Command | Explanation |
+| :--- | :--- |
+| `pisper` | Start the TUI in the current directory with a new empty conversation. History is not resumed automatically. |
+| `pisper --cwd <directory>` | Start the TUI with a new empty conversation in the specified directory. |
+| `pisper resume` | Open the conversation picker across all workspaces. If no history exists, report it and exit. |
+| `pisper resume --cwd <directory>` | Open the conversation picker from a specified launch directory. A resumed conversation keeps its own saved working directory. |
+| `pisper doctor` | Diagnose Sidecar startup, Runtime authentication, capability catalogs, and the latest conversation directory. |
+| `pisper doctor --cwd <directory>` | Run diagnostics with the specified launch workspace. |
+| `pisper web` | Install or use the Web frontend and open its authenticated local settings page in the default browser. Keep the process running while using the page. |
+| `pisper web --cwd <directory>` | Start the Runtime for a specified directory and open the Web settings page. |
+| `pisper help [COMMAND]` | Show global help. `pisper help web` shows help for the Web subcommand. |
+| `pisper -h` / `pisper --help` | Show command help without starting the Runtime. |
+| `pisper -V` / `pisper --version` | Print the installed TUI version. |
+| `pisper update --check` | Check an npm-installed Pisper for updates without installing them. |
+| `pisper update` | Update an npm-installed Pisper through the active npm registry and verify the components again. |
+
+## Environment Variables
+
+| Variable | Description |
+| :--- | :--- |
+| `PISPER_TUI_MOUSE=1` | Enable mouse wheel scrolling in the transcript; note that mouse capture replaces the terminal's native text selection. |
+| `PISPER_TUI_REDUCED_MOTION=1` | Disable the typewriter reveal and status animations (streaming text appears immediately); useful on low-end terminals and SSH sessions. |
+
+## Slash Commands
+
+| Command | Explanation |
+| :--- | :--- |
+| `/init` | Analyze the current project and create or improve `AGENTS.md` at the project root. Existing useful guidance is preserved, and no other project files are changed. |
+| `/new` | Create an empty conversation in the TUI launch directory. Unavailable during an Agent run. |
+| `/sessions` | Open the conversation picker across all directories. Switching is unavailable during an Agent run. |
+| `/dir <directory>` | Change the active conversation's working directory. Relative paths resolve from its current directory. Unavailable during an Agent run. |
+| `/changes` | Open Git or SVN changes. In that view, `R` refreshes, `C` commits, `P` pushes Git, and pressing `V` twice reverts. SVN has no Push operation. |
+| `/changes commit <message>` | Commit the current Git or SVN changes with an explicit message. |
+| `/chat` | Return to the Chat message stream from another view. |
+| `/model` | Open the model picker and switch the active conversation model. Only configured Provider models are listed. Unavailable during an Agent run. |
+| `/thinking` | Refresh and select thinking levels supported by the active model. Unavailable during an Agent run. |
+| `/provider [id]` | Edit a Provider's protocol, effective Base URL, and masked API key. Pass `id` to open a known Provider directly. |
+| `/apikey [id]` | Compatibility alias for `/provider`. |
+| `/web` | Open the authenticated local settings page in the default browser using the installed Web frontend. |
+| `/compact` | Summarize older context immediately. Available only for idle conversations with enough history. |
+| `/attach` | Open the attachment picker rooted at the active conversation directory. |
+| `/mode` | Show the active execution mode and accepted values. The mode can also change during an Agent run. |
+| `/mode approval-required` | Ask before writes, Shell commands, and high-risk tools. |
+| `/mode workspace-write` | Auto-approve workspace edits and routine commands. |
+| `/mode full-access` | Allow local files, network access, and Shell commands as the current operating-system user. |
+| `/quit` | Exit the TUI. |
+
+## Tool and Skill Commands
+
+| Form | Explanation |
+| :--- | :--- |
+| `/<tool> [request]` | Request a Runtime Tool, for example `/read README.md`, `/bash npm test`, or `/web_search Pisper`. The Agent still generates arguments and calls the Tool; the active execution mode and Tool settings remain enforced. |
+| `/skill:<name> [request]` | Request an enabled Skill, for example `/skill:docs-search find signing requirements`. Runtime resources load on demand, and Tools invoked by the Skill follow the same permission chain. |

package/README.md

@@ -1,61 +1,61 @@
-# Pisper TUI Command Reference
+# Pisper TUI 命令参考
 
-[Project home](https://ling-kong-ran.github.io/pisper/) · [GitHub repository](https://github.com/ling-kong-ran/pisper) · [中文](./README.md)
+[项目主页](https://ling-kong-ran.github.io/pisper/) · [GitHub 仓库](https://github.com/ling-kong-ran/pisper) · [English](./README.en.md)
 
-Argument notation: `<argument>` is required; `[argument]` is optional.
+参数约定：`<参数>` 必填，`[参数]` 可选。
 
-## CLI Commands
+## CLI 命令
 
-| Command | Explanation |
+| 命令 | 解释 |
 | :--- | :--- |
-| `pisper` | Start the TUI in the current directory with a new empty conversation. History is not resumed automatically. |
-| `pisper --cwd <directory>` | Start the TUI with a new empty conversation in the specified directory. |
-| `pisper resume` | Open the conversation picker across all workspaces. If no history exists, report it and exit. |
-| `pisper resume --cwd <directory>` | Open the conversation picker from a specified launch directory. A resumed conversation keeps its own saved working directory. |
-| `pisper doctor` | Diagnose Sidecar startup, Runtime authentication, capability catalogs, and the latest conversation directory. |
-| `pisper doctor --cwd <directory>` | Run diagnostics with the specified launch workspace. |
-| `pisper web` | Install or use the Web frontend and open its authenticated local settings page in the default browser. Keep the process running while using the page. |
-| `pisper web --cwd <directory>` | Start the Runtime for a specified directory and open the Web settings page. |
-| `pisper help [COMMAND]` | Show global help. `pisper help web` shows help for the Web subcommand. |
-| `pisper -h` / `pisper --help` | Show command help without starting the Runtime. |
-| `pisper -V` / `pisper --version` | Print the installed TUI version. |
-| `pisper update --check` | Check an npm-installed Pisper for updates without installing them. |
-| `pisper update` | Update an npm-installed Pisper through the active npm registry and verify the components again. |
-
-## Environment Variables
-
-| Variable | Description |
+| `pisper` | 在当前目录启动 TUI，并创建一个空会话；不会自动恢复历史会话。 |
+| `pisper --cwd <目录>` | 使用指定目录启动 TUI 并创建空会话。 |
+| `pisper resume` | 打开跨工作目录的历史会话选择器；没有历史会话时提示后退出。 |
+| `pisper resume --cwd <目录>` | 从指定启动目录进入历史会话选择器；恢复后仍使用会话自身保存的工作目录。 |
+| `pisper doctor` | 检查 Sidecar、Runtime 鉴权、能力目录与最近会话目录，并输出诊断信息。 |
+| `pisper doctor --cwd <目录>` | 以指定目录作为启动工作区执行诊断。 |
+| `pisper web` | 安装或使用 Web 前端，并在默认浏览器打开本机认证配置页；命令运行期间需保持进程存活。 |
+| `pisper web --cwd <目录>` | 以指定目录启动 Runtime 并打开 Web 配置页。 |
+| `pisper help [COMMAND]` | 显示全局帮助；`pisper help web` 显示 Web 子命令帮助。 |
+| `pisper -h` / `pisper --help` | 显示命令帮助，不启动 Runtime。 |
+| `pisper -V` / `pisper --version` | 显示已安装的 TUI 版本。 |
+| `pisper update --check` | 检查 npm 安装的 Pisper 是否有更新，不执行安装。 |
+| `pisper update` | 使用当前 npm registry 更新 npm 安装的 Pisper，并重新校验组件。 |
+
+## 环境变量
+
+| 变量 | 解释 |
 | :--- | :--- |
-| `PISPER_TUI_MOUSE=1` | Enable mouse wheel scrolling in the transcript; note that mouse capture replaces the terminal's native text selection. |
-| `PISPER_TUI_REDUCED_MOTION=1` | Disable the typewriter reveal and status animations (streaming text appears immediately); useful on low-end terminals and SSH sessions. |
+| `PISPER_TUI_MOUSE=1` | 启用鼠标滚轮滚动聊天记录；注意鼠标捕获会接管终端原生文本选择。 |
+| `PISPER_TUI_REDUCED_MOTION=1` | 关闭打字机逐字显现与状态动画（流式文本立即完整显示），适合低配终端与 SSH 会话。 |
 
-## Slash Commands
+## Slash Command
 
-| Command | Explanation |
+| 命令 | 解释 |
 | :--- | :--- |
-| `/init` | Analyze the current project and create or improve `AGENTS.md` at the project root. Existing useful guidance is preserved, and no other project files are changed. |
-| `/new` | Create an empty conversation in the TUI launch directory. Unavailable during an Agent run. |
-| `/sessions` | Open the conversation picker across all directories. Switching is unavailable during an Agent run. |
-| `/dir <directory>` | Change the active conversation's working directory. Relative paths resolve from its current directory. Unavailable during an Agent run. |
-| `/changes` | Open Git or SVN changes. In that view, `R` refreshes, `C` commits, `P` pushes Git, and pressing `V` twice reverts. SVN has no Push operation. |
-| `/changes commit <message>` | Commit the current Git or SVN changes with an explicit message. |
-| `/chat` | Return to the Chat message stream from another view. |
-| `/model` | Open the model picker and switch the active conversation model. Only configured Provider models are listed. Unavailable during an Agent run. |
-| `/thinking` | Refresh and select thinking levels supported by the active model. Unavailable during an Agent run. |
-| `/provider [id]` | Edit a Provider's protocol, effective Base URL, and masked API key. Pass `id` to open a known Provider directly. |
-| `/apikey [id]` | Compatibility alias for `/provider`. |
-| `/web` | Open the authenticated local settings page in the default browser using the installed Web frontend. |
-| `/compact` | Summarize older context immediately. Available only for idle conversations with enough history. |
-| `/attach` | Open the attachment picker rooted at the active conversation directory. |
-| `/mode` | Show the active execution mode and accepted values. The mode can also change during an Agent run. |
-| `/mode approval-required` | Ask before writes, Shell commands, and high-risk tools. |
-| `/mode workspace-write` | Auto-approve workspace edits and routine commands. |
-| `/mode full-access` | Allow local files, network access, and Shell commands as the current operating-system user. |
-| `/quit` | Exit the TUI. |
-
-## Tool and Skill Commands
-
-| Form | Explanation |
+| `/init` | 分析当前项目并创建或完善项目根目录的 `AGENTS.md`；保留已有有效说明，不修改其他项目文件。 |
+| `/new` | 在 TUI 启动目录创建空会话；Agent 运行期间不可执行。 |
+| `/sessions` | 打开跨所有目录的历史会话选择器；Agent 运行期间不可切换会话。 |
+| `/dir <目录>` | 修改当前会话的工作目录；相对路径以当前会话目录为基准，Agent 运行期间不可修改。 |
+| `/changes` | 打开 Git 或 SVN 改动视图。视图内 `R` 刷新、`C` 提交、`P` 推送 Git、连续两次 `V` 撤销；SVN 不提供 Push。 |
+| `/changes commit <message>` | 使用指定提交信息提交当前 Git 或 SVN 工作区改动。 |
+| `/chat` | 从其他视图返回 Chat 消息流。 |
+| `/model` | 打开模型选择器并切换当前会话模型；只列出已配置 Provider 的模型，Agent 运行期间不可切换。 |
+| `/thinking` | 刷新并选择当前模型支持的思考等级；Agent 运行期间不可切换。 |
+| `/provider [id]` | 编辑 Provider 协议、当前生效 Base URL 与掩码 API Key；传入 `id` 可直达指定 Provider。 |
+| `/apikey [id]` | `/provider` 的兼容别名。 |
+| `/web` | 使用已安装的 Web 前端，在默认浏览器打开本机认证配置页。 |
+| `/compact` | 立即摘要较早上下文；仅适用于有足够历史且当前空闲的会话。 |
+| `/attach` | 打开当前会话目录的附件选择器。 |
+| `/mode` | 显示当前执行模式及可用值；Agent 运行期间也可调整。 |
+| `/mode approval-required` | 写入、Shell 和高风险工具执行前请求授权。 |
+| `/mode workspace-write` | 自动批准工作区修改和常规命令。 |
+| `/mode full-access` | 允许以当前系统用户权限访问本机文件、网络与 Shell。 |
+| `/quit` | 退出 TUI。 |
+
+## Tool 与 Skill 命令
+
+| 形式 | 解释 |
 | :--- | :--- |
-| `/<tool> [request]` | Request a Runtime Tool, for example `/read README.md`, `/bash npm test`, or `/web_search Pisper`. The Agent still generates arguments and calls the Tool; the active execution mode and Tool settings remain enforced. |
-| `/skill:<name> [request]` | Request an enabled Skill, for example `/skill:docs-search find signing requirements`. Runtime resources load on demand, and Tools invoked by the Skill follow the same permission chain. |
+| `/<tool> [请求]` | 请求 Runtime Tool，例如 `/read README.md`、`/bash npm test` 或 `/web_search Pisper`。Agent 仍负责生成参数并调用 Tool，当前执行模式与 Tool 开关继续生效。 |
+| `/skill:<name> [请求]` | 请求已启用 Skill，例如 `/skill:docs-search 查找签名要求`。Runtime 按需加载 Skill 资源，其中触发的 Tool 继续经过同一权限链。 |

package/bin/pisper.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+import { ensurePisperInstallation } from '../lib/install.mjs'
+import { handleNpmHelp, handleNpmUpdate } from '../lib/npm-update.mjs'
+
+const frontendRoot = fileURLToPath(new URL('../web', import.meta.url))
+
+try {
+  const arguments_ = process.argv.slice(2)
+  if (!handleNpmHelp(arguments_) && !(await handleNpmUpdate(arguments_))) {
+    const installation = await ensurePisperInstallation()
+    const child = spawn(installation.executable, arguments_, {
+      env: {
+        ...process.env,
+        PISPER_APP_ROOT: installation.appRoot,
+        PISPER_DISTRIBUTION: 'npm',
+        PISPER_FRONTEND_ROOT: frontendRoot,
+        PISPER_RUNTIME_NODE: process.execPath,
+      },
+      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,392 @@
+import { execFile } from 'node:child_process'
+import { chmod, mkdir, open, readFile, rename, rm, stat, writeFile } from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import process from 'node:process'
+import { promisify } from 'node:util'
+import { fileURLToPath } from 'node:url'
+import { PublicKey, Signature } from '@threema/wasm-minisign-verify'
+import { x as extractTar } from 'tar'
+import { npmPlatformAlias, npmPlatformTarget, npmPlatformVersion } from './npm-platform.mjs'
+import {
+  componentsRoot,
+  executableName,
+  releaseArchitecture,
+  releasePlatform,
+  supportedTarget,
+} from './platform.mjs'
+
+const execFileAsync = promisify(execFile)
+const require = createRequire(import.meta.url)
+const packageRoot = fileURLToPath(new URL('..', import.meta.url))
+const packageManifest = JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8'))
+const tuiVersion = packageManifest.pisper?.tuiVersion
+const runtimeVersion = packageManifest.pisper?.runtimeVersion
+const MAX_ARCHIVE_BYTES = 128 * 1024 * 1024
+const INSTALL_WAIT_MS = 600_000
+const LEGACY_LOCK_GRACE_MS = 300_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`)
+  }
+}
+
+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 = process.platform, arch = process.arch) {
+  const target = supportedTarget(platform, arch)
+  const label = component === 'tui' ? 'TUI_Component' : 'Runtime_Node'
+  return `Pisper_${label}_${version}_${target}.tar.gz`
+}
+
+export function releaseAsset(
+  version = tuiVersion,
+  platform = process.platform,
+  arch = process.arch,
+) {
+  return componentAsset('tui', version, platform, arch)
+}
+
+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 'sidecar-runtime/runtime/sidecar.mjs'
+}
+
+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 installedComponent(component, version, destination) {
+  const executable = await validateComponent(component, version, destination)
+  return executable ? { version, destination, executable } : null
+}
+
+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)
+    return installedComponent(component, pointer.version, destination)
+  } catch (error) {
+    if (error?.code === 'ENOENT' || error instanceof SyntaxError) return null
+    throw error
+  }
+}
+
+async function resolvePlatformBundle() {
+  const target = npmPlatformTarget()
+  const alias = npmPlatformAlias()
+  let manifestPath
+  try {
+    manifestPath = require.resolve(`${alias}/package.json`)
+  } catch (error) {
+    throw new Error(
+      `the npm platform package ${alias} is missing; reinstall pisper without --omit=optional`,
+      { cause: error },
+    )
+  }
+  const manifest = JSON.parse(await readFile(manifestPath, 'utf8'))
+  const metadata = manifest.pisperBundle
+  const expectedVersion = npmPlatformVersion(packageManifest.version)
+  if (
+    manifest.name !== 'pisper' ||
+    manifest.version !== expectedVersion ||
+    metadata?.target !== target.release ||
+    metadata?.tuiVersion !== tuiVersion ||
+    metadata?.runtimeVersion !== runtimeVersion
+  ) {
+    throw new Error(
+      `npm platform package ${alias} does not match pisper@${packageManifest.version}`,
+    )
+  }
+  return dirname(manifestPath)
+}
+
+async function readBundledAsset(bundleRoot, component, version) {
+  const asset = componentAsset(component, version)
+  const archivePath = join(bundleRoot, 'components', component, asset)
+  const signaturePath = `${archivePath}.sig`
+  let size
+  try {
+    size = (await stat(archivePath)).size
+  } catch (error) {
+    throw new Error(`npm platform package is missing ${component} archive ${asset}`, {
+      cause: error,
+    })
+  }
+  if (size <= 0 || size > MAX_ARCHIVE_BYTES) {
+    throw new Error(`npm platform package contains an invalid ${component} archive size: ${size}`)
+  }
+  const [archive, signature] = await Promise.all([readFile(archivePath), readFile(signaturePath)])
+  return { archive, signature }
+}
+
+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()
+  }
+}
+
+function nativeTarCommand() {
+  if (process.platform === 'win32') {
+    return join(
+      process.env.SystemRoot || process.env.WINDIR || 'C:\\Windows',
+      'System32',
+      'tar.exe',
+    )
+  }
+  if (process.platform === 'darwin') return '/usr/bin/tar'
+  return 'tar'
+}
+
+async function extractWithNodeTar(archivePath, extractionRoot) {
+  await extractTar({
+    cwd: extractionRoot,
+    file: archivePath,
+    preservePaths: false,
+    strict: true,
+    strip: 1,
+    filter: (_path, entry) => entry.type === 'File' || entry.type === 'Directory',
+  })
+}
+
+export async function extractComponentArchive(
+  archivePath,
+  extractionRoot,
+  tarCommand = nativeTarCommand(),
+) {
+  try {
+    await execFileAsync(
+      tarCommand,
+      ['-xzf', archivePath, '-C', extractionRoot, '--strip-components=1'],
+      { windowsHide: true },
+    )
+  } catch {
+    await rm(extractionRoot, { recursive: true, force: true })
+    await mkdir(extractionRoot, { recursive: true })
+    await extractWithNodeTar(archivePath, extractionRoot)
+  }
+}
+
+async function wait(milliseconds) {
+  await new Promise((resolve) => setTimeout(resolve, milliseconds))
+}
+
+async function installerLockIsActive(lockPath) {
+  try {
+    const [raw, details] = await Promise.all([readFile(lockPath, 'utf8'), stat(lockPath)])
+    const age = Math.max(0, Date.now() - details.mtimeMs)
+    if (age >= INSTALL_WAIT_MS) return false
+
+    let metadata
+    try {
+      metadata = JSON.parse(raw)
+    } catch {
+      // Older installers created empty locks. Give a live legacy install time to finish.
+      return age < LEGACY_LOCK_GRACE_MS
+    }
+    if (!Number.isSafeInteger(metadata?.pid) || metadata.pid <= 0) {
+      return age < LEGACY_LOCK_GRACE_MS
+    }
+    try {
+      process.kill(metadata.pid, 0)
+      return true
+    } catch (error) {
+      if (error?.code === 'ESRCH') return false
+      if (error?.code === 'EPERM') return true
+      throw error
+    }
+  } catch (error) {
+    if (error?.code === 'ENOENT') return false
+    throw error
+  }
+}
+
+export async function acquireInstallLock(lockPath, validate) {
+  const deadline = Date.now() + INSTALL_WAIT_MS
+  while (true) {
+    try {
+      const lock = await open(lockPath, 'wx')
+      try {
+        await lock.writeFile(`${JSON.stringify({ pid: process.pid, createdAt: Date.now() })}\n`)
+        return lock
+      } catch (error) {
+        await lock.close()
+        await rm(lockPath, { force: true })
+        throw error
+      }
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error
+      if (await validate()) return null
+      if (!(await installerLockIsActive(lockPath))) {
+        try {
+          await rm(lockPath, { force: true })
+          continue
+        } catch (removeError) {
+          if (!['EACCES', 'EBUSY', 'EPERM'].includes(removeError?.code)) throw removeError
+        }
+      }
+      if (Date.now() >= deadline) {
+        throw new Error('timed out waiting for another Pisper installer')
+      }
+      await wait(250)
+    }
+  }
+}
+
+async function installComponent({ root, bundleRoot, component, version, destination }) {
+  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 acquireInstallLock(lockPath, validate)
+  if (!lock) return { version, destination, executable: await validate() }
+
+  const staging = `${destination}.tmp-${process.pid}-${Date.now()}`
+  // Renaming a tree with paths over MAX_PATH fails on Windows even though tar can extract it.
+  const extractionRoot = process.platform === 'win32' ? destination : staging
+  const archivePath = `${staging}.tar.gz`
+  try {
+    const existing = await validate()
+    if (existing) return { version, destination, executable: existing }
+
+    console.log(`pisper: installing ${component} ${version} from the npm platform package`)
+    await mkdir(dirname(destination), { recursive: true })
+    await rm(extractionRoot, { recursive: true, force: true })
+    await mkdir(extractionRoot, { recursive: true })
+    const { archive, signature } = await readBundledAsset(bundleRoot, component, version)
+    console.log(`pisper: verifying ${component} ${version} signature`)
+    await verifyArchive(component, archive, signature)
+    console.log(`pisper: extracting ${component} ${version}`)
+    await writeFile(archivePath, archive, { mode: 0o600 })
+    await extractComponentArchive(archivePath, extractionRoot)
+    if (process.platform !== 'win32') {
+      await chmod(join(extractionRoot, commandName(component)), 0o755)
+    }
+    const stagedExecutable = await validateComponent(component, version, extractionRoot)
+    if (!stagedExecutable) {
+      throw new Error(`bundled ${component} archive has an invalid package layout`)
+    }
+    if (extractionRoot !== destination) {
+      await rm(destination, { recursive: true, force: true })
+      await rename(staging, destination)
+    }
+    console.log(`pisper: ${component} ${version} is ready`)
+    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, 'npm-runtime', 'versions', runtimeVersion)
+  const [tui, runtime] = await Promise.all([
+    resolveCurrentComponent(root, 'tui', tuiVersion).then(
+      (current) => current || installedComponent('tui', tuiVersion, npmTuiDestination),
+    ),
+    installedComponent('runtime', runtimeVersion, runtimeDestination),
+  ])
+  if (tui && runtime) {
+    return {
+      executable: tui.executable,
+      appRoot: join(runtime.destination, 'sidecar-runtime'),
+    }
+  }
+
+  const bundleRoot = await resolvePlatformBundle()
+  const [installedTui, installedRuntime] = await Promise.all([
+    tui ||
+      installComponent({
+        root,
+        bundleRoot,
+        component: 'tui',
+        version: tuiVersion,
+        destination: npmTuiDestination,
+      }),
+    runtime ||
+      installComponent({
+        root,
+        bundleRoot,
+        component: 'runtime',
+        version: runtimeVersion,
+        destination: runtimeDestination,
+      }),
+  ])
+  return {
+    executable: installedTui.executable,
+    appRoot: join(installedRuntime.destination, 'sidecar-runtime'),
+  }
+}
+
+export async function ensurePisperExecutable() {
+  return (await ensurePisperInstallation()).executable
+}

package/lib/npm-platform.mjs

@@ -0,0 +1,41 @@
+import process from 'node:process'
+
+export const NPM_PLATFORM_TARGETS = Object.freeze([
+  Object.freeze({ platform: 'win32', arch: 'x64', release: 'windows_x86_64', slug: 'win32-x64' }),
+  Object.freeze({ platform: 'darwin', arch: 'x64', release: 'darwin_x86_64', slug: 'darwin-x64' }),
+  Object.freeze({
+    platform: 'darwin',
+    arch: 'arm64',
+    release: 'darwin_aarch64',
+    slug: 'darwin-arm64',
+  }),
+  Object.freeze({ platform: 'linux', arch: 'x64', release: 'linux_x86_64', slug: 'linux-x64' }),
+])
+
+export function npmPlatformTarget(platform = process.platform, arch = process.arch) {
+  const target = NPM_PLATFORM_TARGETS.find(
+    (candidate) => candidate.platform === platform && candidate.arch === arch,
+  )
+  if (!target) throw new Error(`Pisper does not publish an npm package for ${platform}-${arch}`)
+  return target
+}
+
+export function npmPlatformAlias(platform = process.platform, arch = process.arch) {
+  return `pisper-binary-${npmPlatformTarget(platform, arch).slug}`
+}
+
+export function npmPlatformVersion(version, platform = process.platform, arch = process.arch) {
+  if (!/^\d+\.\d+\.\d+$/.test(version || '')) {
+    throw new Error(`invalid Pisper npm version: ${version}`)
+  }
+  return `${version}-${npmPlatformTarget(platform, arch).slug}.0`
+}
+
+export function npmPlatformOptionalDependencies(version) {
+  return Object.fromEntries(
+    NPM_PLATFORM_TARGETS.map(({ platform, arch }) => [
+      npmPlatformAlias(platform, arch),
+      `npm:pisper@${npmPlatformVersion(version, platform, arch)}`,
+    ]),
+  )
+}