@ziniao-open/cli 0.1.0-beta.100

package/README.md

@@ -0,0 +1,130 @@
+# ziniao-cli
+
+紫鸟开放平台命令行工具，为开发者和 AI Agent 提供统一的接口调用入口。
+
+支持服务端 OpenAPI 和本地浏览器 Bridge（ZClaw）两套接口体系，使用统一的 apiKey 认证。
+
+## 安装
+
+```bash
+npm install -g @ziniao-open/cli
+```
+
+紫鸟客户端自带的 `ziniao` CLI 需要同步到 AppCache 并加入 PATH。执行 `npm install -g @ziniao-open/cli` 时会自动尝试同步；安装紫鸟客户端后，也可以手动执行以下命令：
+
+```bash
+source "$(npm root -g)/@ziniao-open/cli/scripts/setup-ziniao-cli.sh"
+```
+
+Windows PowerShell 执行：
+
+```powershell
+. "$(npm root -g)\@ziniao-open\cli\scripts\setup-ziniao-cli.ps1"
+```
+
+也可以在安装后手动修复：
+
+```bash
+ziniao-cli doctor fix-path
+```
+
+遍历当前 PATH 并清理正式目录之外的 `ziniao.exe` 文件（默认只预览）：
+
+```powershell
+& "$(npm root -g)\@ziniao-open\cli\scripts\remove-ziniao-cli-shims.ps1"
+& "$(npm root -g)\@ziniao-open\cli\scripts\remove-ziniao-cli-shims.ps1" -Apply
+```
+
+macOS/Linux：
+
+```bash
+"$(npm root -g)/@ziniao-open/cli/scripts/remove-ziniao-cli-shims.sh"
+"$(npm root -g)/@ziniao-open/cli/scripts/remove-ziniao-cli-shims.sh" --apply
+```
+
+脚本只探测 `ziniao.app` / `ziniao` 的安装目录；Windows 会优先查询卸载注册表中 `DisplayIcon` 包含 `ziniao.exe` 的条目，再从本体目录的 `resources/app.asar.unpacked/envkit/cli` 查找 CLI。Windows 使用 `%APPDATA%\ziniaobrowser\cli`，macOS 使用 `~/Library/Application Support/ziniaobrowser/cli`，Linux 使用 `${XDG_CONFIG_HOME:-~/.config}/ziniaobrowser/cli`，在目标目录缺少 CLI 或文件内容发生变化时同步最新文件，并注册当前用户 PATH。找不到源文件时只提示并继续，不阻断 PATH 配置。若安装目录无法自动探测，可设置 `ZINIAO_INSTALL_DIR`；若目标位置不同，可设置 `ZINIAO_APP_CACHE_DIR`。
+Windows 同时会把找到的紫鸟本体绝对路径写入 `%APPDATA%\ziniaobrowser\gui-path`，供 CLI 定位桌面客户端。
+macOS/Linux 也会在找到桌面本体时写入对应的 `gui-path`（macOS 为 `~/Library/Application Support/ziniaobrowser/gui-path`，Linux 为 `${XDG_CONFIG_HOME:-~/.config}/ziniaobrowser/gui-path`）。
+
+安装时会自动下载当前平台对应的预编译二进制（支持 macOS / Linux / Windows × amd64 / arm64），并做 SHA-256 校验。
+
+## 快速开始
+
+```bash
+# 1. 初始化配置（首次使用必做，会引导你写入 apiKey）
+ziniao-cli config init
+
+# 2. 通用 API 调用（覆盖紫鸟开放平台全部接口）
+ziniao-cli api /superbrowser/rest/v1/erp/department/list
+
+# 3. 快捷命令（高频操作的封装）
+ziniao-cli staff list --format table
+ziniao-cli store list
+ziniao-cli department list
+
+# 4. 环境自检
+ziniao-cli doctor
+
+# 5. 查看所有命令
+ziniao-cli --help
+```
+
+## 命令概览
+
+| 类别 | 命令 | 说明 |
+|------|------|------|
+| 基础 | `config` | apiKey 等配置初始化与查看 |
+| 基础 | `doctor` | 环境自检（认证、网络、ZClaw 桥可用性） |
+| 基础 | `completion` | 生成 shell 自动补全 |
+| 通用 | `api <path>` | 调用任意紫鸟 OpenAPI 路径 |
+| 桥接 | `zclaw` | 本地浏览器 Bridge（页面操作、店铺管理等） |
+| 快捷 | `staff` / `store` / `account` / `department` / `role` / `device` / `page` / `automation` | 高频业务操作的封装 |
+
+完整列表见 `ziniao-cli --help`。
+
+## 本地 dev/prod 打包与切换
+
+在仓库根目录执行以下命令，可分别生成本地测试环境包和本地正式环境包：
+
+```bash
+make package-dev
+make package-prod
+```
+
+两个命令都会生成本地多平台 snapshot 包。版本基于最近的发布 tag，并使用本机递增计数器：最近 tag 为 `v1.0.7` 时，依次生成 `1.0.7-dev-1`、`1.0.7-dev-2`、`1.0.7-dev-3`。
+
+计数器保存在 `~/.ziniao-cli/dev-build-counter`；当最近 tag 变化时计数从 `1` 重新开始。可通过 `ZINIAO_CLI_DEV_COUNTER_FILE` 指定其他计数器路径，便于 CI 或测试隔离。产物写入 `dist/`，该命令只打包，不发布。
+
+`package-dev` 内置测试环境 `https://test-sbappstoreapi.ziniao.com` 与 `https://test-open.ziniao.com`，默认使用独立配置目录 `~/.ziniao-cli-dev/`，本地二进制写入 `~/.ziniao-cli-dev/bin/ziniao-cli`。
+
+`package-prod` 内置正式环境 `https://sbappstoreapi.ziniao.com` 与 `https://open.ziniao.com`，默认使用独立配置目录 `~/.ziniao-cli-prod/`，本地二进制写入 `~/.ziniao-cli-prod/bin/ziniao-cli`。
+
+仓库内的 `scripts/ziniao-cli-use` 提供统一切换入口；如果你已将该脚本加入 PATH，可直接执行：
+
+```bash
+ziniao-cli-use dev
+ziniao-cli-use prod
+ziniao-cli-use online
+```
+
+- `ziniao-cli-use dev`：切换到 `~/.ziniao-cli-dev/bin/ziniao-cli`
+- `ziniao-cli-use prod`：切换到 `~/.ziniao-cli-prod/bin/ziniao-cli`
+- `ziniao-cli-use online`：切换回 npm 安装的线上版 `ziniao-cli`，继续使用默认线上配置目录 `~/.ziniao-cli/`
+
+`make package-dev` 与 `make package-prod` 只会更新各自隔离的本地输出路径，不会改写仓库根目录的 `./ziniao-cli`。如果你需要仓库根目录的开发测试二进制，继续使用 `make build`。
+
+dev、本地 prod、online 三套 CLI 默认分别使用 `~/.ziniao-cli-dev/`、`~/.ziniao-cli-prod/`、`~/.ziniao-cli/`，API Key 和配置互不读取。首次运行某个本地环境前，执行 `ziniao-cli config init` 即可在对应目录完成初始化。
+
+## AI Agent Skills
+
+仓库提供 12 个开箱即用的 AI Agent Skill：访问策略、账号、部门、设备、OpenAPI 探索、页面、角色、共享基础、Skill 创建、员工、店铺和批量账号授权。
+
+安装 Skill：
+
+```bash
+ziniao-cli skills install
+```
+
+备选：`npx skills add ziniao-open/skills -y -g`
+
+详见 [ziniao-skills](https://github.com/ziniao-open/skills)。

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@ziniao-open/cli",
+  "version": "0.1.0-beta.100",
+  "description": "紫鸟开放平台命令行工具，为开发者和 AI Agent 提供统一的接口调用入口。",
+  "license": "UNLICENSED",
+  "bin": {
+    "ziniao-cli": "scripts/run.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/install.js",
+    "pack:local": "npm pack"
+  },
+  "files": [
+    "scripts/install.js",
+    "scripts/run.js",
+    "scripts/setup-ziniao-cli.sh",
+    "scripts/setup-ziniao-cli.ps1",
+    "scripts/remove-ziniao-cli-shims.ps1",
+    "scripts/remove-ziniao-cli-shims.sh"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "ziniaoCli": {
+    "downloadBaseUrl": "https://ziniao-open-test.s3.cn-northwest-1.amazonaws.com.cn/ziniao-cli/releases",
+    "binaryName": "ziniao-cli",
+    "archivePrefix": "ziniao-cli"
+  }
+}

package/scripts/install.js

@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+/**
+ * Postinstall hook: download the platform-matching ziniao-cli binary from S3.
+ *
+ * Skip paths (in priority order):
+ *   1. SKIP_ZINIAO_CLI_INSTALL=1            -> skip everything (CI / monorepo installs)
+ *   2. ZINIAO_CLI_BINARY=/path/to/binary    -> copy from local path (dev/release-rehearsal)
+ *   3. bin/ziniao-cli(.exe) already present -> reuse it (avoid re-download on rebuild)
+ *   4. package.json version === "0.0.0"     -> developer install in this repo itself
+ *
+ * Network path:
+ *   - Read downloadBaseUrl from package.json.ziniaoCli.downloadBaseUrl
+ *     (overridable via ZINIAO_CLI_DOWNLOAD_BASE env var).
+ *   - Download:  {base}/v{version}/checksums.txt
+ *                {base}/v{version}/{archivePrefix}-{version}-{goos}-{goarch}.{ext}
+ *   - Verify SHA-256 against checksums.txt.
+ *   - Extract via system `tar` (Windows 10+ ships bsdtar capable of .zip and .tar.gz).
+ */
+
+const {
+  chmodSync,
+  copyFileSync,
+  createWriteStream,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  unlinkSync,
+} = require("node:fs");
+const { basename, dirname, join } = require("node:path");
+const { tmpdir } = require("node:os");
+const { spawnSync } = require("node:child_process");
+const { createHash } = require("node:crypto");
+const https = require("node:https");
+const http = require("node:http");
+const { URL } = require("node:url");
+
+const PKG = require("../package.json");
+const REPO_ROOT = join(__dirname, "..");
+const BIN_DIR = join(REPO_ROOT, "bin");
+const IS_WIN = process.platform === "win32";
+const BINARY_NAME = IS_WIN ? "ziniao-cli.exe" : "ziniao-cli";
+const TARGET_PATH = join(BIN_DIR, BINARY_NAME);
+
+const cfg = PKG.ziniaoCli || {};
+const DOWNLOAD_BASE = (process.env.ZINIAO_CLI_DOWNLOAD_BASE || cfg.downloadBaseUrl || "").replace(/\/+$/, "");
+const ARCHIVE_PREFIX = cfg.archivePrefix || "ziniao-cli";
+
+const PLATFORM_MAP = { darwin: "darwin", linux: "linux", win32: "windows" };
+const ARCH_MAP = { x64: "amd64", arm64: "arm64" };
+
+function log(msg) {
+  console.log(`[ziniao-cli/install] ${msg}`);
+}
+function warn(msg) {
+  console.warn(`[ziniao-cli/install] ${msg}`);
+}
+function fail(msg) {
+  console.error(`[ziniao-cli/install] ${msg}`);
+  process.exit(1);
+}
+
+function ensureBinDir() {
+  mkdirSync(BIN_DIR, { recursive: true });
+}
+
+function makeExecutable(file) {
+  if (!IS_WIN) {
+    chmodSync(file, 0o755);
+  }
+}
+
+function copyFromEnv() {
+  const src = process.env.ZINIAO_CLI_BINARY;
+  if (!src) return false;
+  if (!existsSync(src) || !statSync(src).isFile()) {
+    fail(`ZINIAO_CLI_BINARY does not point to a file: ${src}`);
+  }
+  ensureBinDir();
+  copyFileSync(src, TARGET_PATH);
+  makeExecutable(TARGET_PATH);
+  log(`installed from local binary ${basename(src)}`);
+  return true;
+}
+
+function detectTarget() {
+  const goos = PLATFORM_MAP[process.platform];
+  const goarch = ARCH_MAP[process.arch];
+  if (!goos || !goarch) {
+    fail(`unsupported platform: ${process.platform}-${process.arch}`);
+  }
+  const ext = goos === "windows" ? "zip" : "tar.gz";
+  return { goos, goarch, ext };
+}
+
+function getRedirected(url, onResponse, redirects = 0) {
+  if (redirects > 5) {
+    return onResponse(new Error(`too many redirects: ${url}`));
+  }
+  const lib = url.startsWith("https:") ? https : http;
+  const req = lib.get(url, (res) => {
+    if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+      const next = new URL(res.headers.location, url).toString();
+      res.resume();
+      return getRedirected(next, onResponse, redirects + 1);
+    }
+    if (res.statusCode !== 200) {
+      res.resume();
+      return onResponse(new Error(`HTTP ${res.statusCode} for ${url}`));
+    }
+    onResponse(null, res);
+  });
+  req.on("error", (err) => onResponse(err));
+  req.setTimeout(60_000, () => req.destroy(new Error(`download timed out: ${url}`)));
+}
+
+function downloadToString(url) {
+  return new Promise((resolve, reject) => {
+    getRedirected(url, (err, res) => {
+      if (err) return reject(err);
+      const chunks = [];
+      res.on("data", (c) => chunks.push(c));
+      res.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+      res.on("error", reject);
+    });
+  });
+}
+
+function downloadToFile(url, dest) {
+  return new Promise((resolve, reject) => {
+    getRedirected(url, (err, res) => {
+      if (err) return reject(err);
+      const hash = createHash("sha256");
+      const out = createWriteStream(dest);
+      res.on("data", (c) => hash.update(c));
+      res.pipe(out);
+      out.on("finish", () => out.close(() => resolve(hash.digest("hex"))));
+      out.on("error", reject);
+      res.on("error", reject);
+    });
+  });
+}
+
+function parseChecksums(text) {
+  const map = new Map();
+  for (const line of text.split(/\r?\n/)) {
+    const m = line.trim().match(/^([0-9a-f]{64})\s+\*?(\S+)$/i);
+    if (m) map.set(m[2], m[1].toLowerCase());
+  }
+  return map;
+}
+
+function extract(archivePath, destDir) {
+  if (process.platform === "win32" && archivePath.endsWith(".zip")) {
+    const ps = spawnSync("powershell.exe", [
+      "-NoProfile", "-NonInteractive", "-Command",
+      `Expand-Archive -LiteralPath '${archivePath}' -DestinationPath '${destDir}' -Force`
+    ], { stdio: "inherit" });
+    if (!ps.error && ps.status === 0) return;
+  }
+  let tarCmd = "tar";
+  if (process.platform === "win32") {
+    const sysRoot = process.env.SystemRoot || "C:\\Windows";
+    const candidates = [
+      join(sysRoot, "Sysnative", "tar.exe"),
+      join(sysRoot, "System32", "tar.exe"),
+    ];
+    for (const p of candidates) {
+      if (existsSync(p)) {
+        tarCmd = p;
+        break;
+      }
+    }
+  }
+  const res = spawnSync(tarCmd, ["-xf", archivePath, "-C", destDir], { stdio: "inherit" });
+  if (res.error) {
+    fail(`failed to execute tar: ${res.error.message}. Tar is required (preinstalled on Win10+/macOS/Linux).`);
+  }
+  if (res.status !== 0) {
+    fail(`tar exited with code ${res.status}`);
+  }
+}
+
+function findBinaryIn(dir, name) {
+  const fs = require("node:fs");
+  const stack = [dir];
+  while (stack.length) {
+    const cur = stack.pop();
+    for (const entry of fs.readdirSync(cur, { withFileTypes: true })) {
+      const p = join(cur, entry.name);
+      if (entry.isDirectory()) stack.push(p);
+      else if (entry.isFile() && entry.name === name) return p;
+    }
+  }
+  return null;
+}
+
+function runDesktopCliSetup() {
+  const scriptName = IS_WIN ? "setup-ziniao-cli.ps1" : "setup-ziniao-cli.sh";
+  const scriptPath = join(__dirname, scriptName);
+  if (!existsSync(scriptPath)) {
+    warn(`desktop CLI PATH setup script is missing: ${scriptPath}`);
+    return;
+  }
+
+  const result = IS_WIN
+    ? spawnSync("powershell.exe", [
+        "-NoProfile",
+        "-NonInteractive",
+        "-ExecutionPolicy",
+        "Bypass",
+        "-File",
+        scriptPath,
+      ], { stdio: "inherit" })
+    : spawnSync("sh", [scriptPath], { stdio: "inherit" });
+  if (result.error) {
+    warn(`desktop CLI PATH setup skipped: ${result.error.message}`);
+  } else if (result.status !== 0) {
+    warn(`desktop CLI PATH setup exited with code ${result.status}`);
+  }
+}
+
+async function downloadAndInstall() {
+  const version = PKG.version;
+  if (!DOWNLOAD_BASE) {
+    fail(
+      "ziniaoCli.downloadBaseUrl is not configured. Set it in package.json or " +
+        "export ZINIAO_CLI_DOWNLOAD_BASE before installing."
+    );
+  }
+
+  const { goos, goarch, ext } = detectTarget();
+  const archiveName = `${ARCHIVE_PREFIX}-${version}-${goos}-${goarch}.${ext}`;
+  const baseDir = `${DOWNLOAD_BASE}/v${version}`;
+  const archiveUrl = `${baseDir}/${archiveName}`;
+  const checksumUrl = `${baseDir}/checksums.txt`;
+
+  log(`downloading ${archiveUrl}`);
+  const work = mkdtempSync(join(tmpdir(), "ziniao-cli-"));
+  const archivePath = join(work, archiveName);
+
+  let checksums;
+  try {
+    checksums = parseChecksums(await downloadToString(checksumUrl));
+  } catch (err) {
+    fail(`failed to fetch checksums.txt: ${err.message}`);
+  }
+  const expected = checksums.get(archiveName);
+  if (!expected) {
+    fail(`checksums.txt does not contain an entry for ${archiveName}`);
+  }
+
+  let actual;
+  try {
+    actual = await downloadToFile(archiveUrl, archivePath);
+  } catch (err) {
+    fail(`failed to download ${archiveUrl}: ${err.message}`);
+  }
+  if (actual !== expected) {
+    fail(`SHA-256 mismatch for ${archiveName} (expected ${expected}, got ${actual})`);
+  }
+  log("SHA-256 verified");
+
+  extract(archivePath, work);
+  const extracted = findBinaryIn(work, BINARY_NAME);
+  if (!extracted) {
+    fail(`binary ${BINARY_NAME} not found in archive ${archiveName}`);
+  }
+
+  ensureBinDir();
+  copyFileSync(extracted, TARGET_PATH);
+  makeExecutable(TARGET_PATH);
+
+  try {
+    rmSync(work, { recursive: true, force: true });
+  } catch {
+    /* best effort */
+  }
+
+  log(`installed ${BINARY_NAME} -> ${TARGET_PATH}`);
+}
+
+async function main() {
+  if (process.env.SKIP_ZINIAO_CLI_INSTALL === "1") {
+    log("SKIP_ZINIAO_CLI_INSTALL=1 set, skipping binary install");
+    return;
+  }
+
+  if (PKG.version === "0.0.0") {
+    warn("package.json version is 0.0.0; skipping binary install (developer mode).");
+    warn("Set ZINIAO_CLI_BINARY=/path/to/binary or run `make build` to use a local build.");
+  } else if (existsSync(TARGET_PATH)) {
+    makeExecutable(TARGET_PATH);
+    log(`binary already present at ${TARGET_PATH}, skipping download`);
+  } else if (copyFromEnv()) {
+    // Local binary installed.
+  } else {
+    await downloadAndInstall();
+  }
+
+  runDesktopCliSetup();
+}
+
+main().catch((err) => fail(err.stack || err.message || String(err)));

package/scripts/remove-ziniao-cli-shims.ps1

@@ -0,0 +1,43 @@
+# Find and optionally remove ziniao.exe shims created in PATH directories.
+# Run without -Apply first to preview the files that would be removed.
+
+[CmdletBinding(SupportsShouldProcess)]
+param(
+  [switch]$Apply
+)
+
+$ErrorActionPreference = "Stop"
+
+function Write-Log([string]$Message) {
+  Write-Output "[ziniao-cli-shims] $Message"
+}
+
+$targetDir = Join-Path $env:APPDATA "ziniaobrowser\cli"
+$candidates = @()
+foreach ($pathEntry in @($env:Path -split ";" | Where-Object { $_ })) {
+  $directory = $pathEntry.TrimEnd('\')
+  if (-not $directory -or $directory -ieq $targetDir.TrimEnd('\')) { continue }
+  $shimPath = Join-Path $directory "ziniao.exe"
+  if (-not (Test-Path -LiteralPath $shimPath -PathType Leaf)) { continue }
+  $candidates += $shimPath
+}
+
+if (-not $candidates) {
+  Write-Log "No ziniao.exe shims found in PATH directories."
+  exit 0
+}
+
+foreach ($candidate in ($candidates | Select-Object -Unique)) {
+  if (-not $Apply) {
+    Write-Log "Would remove: $candidate"
+    continue
+  }
+  if ($PSCmdlet.ShouldProcess($candidate, "Remove CLI shim")) {
+    Remove-Item -LiteralPath $candidate -Force
+    Write-Log "Removed: $candidate"
+  }
+}
+
+if (-not $Apply) {
+  Write-Log "Preview only. Re-run with -Apply to remove these files."
+}

package/scripts/remove-ziniao-cli-shims.sh

@@ -0,0 +1,52 @@
+#!/bin/sh
+# Find and optionally remove ziniao shims created in PATH directories.
+# Run without --apply first to preview the files that would be removed.
+
+apply=0
+if [ "${1:-}" = "--apply" ]; then
+  apply=1
+elif [ -n "${1:-}" ]; then
+  printf '%s\n' "[ziniao-cli-shims] ERROR: unsupported option: $1" >&2
+  exit 2
+fi
+
+log() { printf '%s\n' "[ziniao-cli-shims] $*"; }
+
+home_dir="${HOME:?HOME is not set}"
+platform="$(uname -s 2>/dev/null || printf 'unknown')"
+case "$platform" in
+  Darwin) default_dir="$home_dir/Library/Application Support/ziniaobrowser/cli" ;;
+  Linux) default_dir="${XDG_CONFIG_HOME:-$home_dir/.config}/ziniaobrowser/cli" ;;
+  *)
+    log "ERROR: unsupported operating system: $platform"
+    exit 1
+    ;;
+esac
+
+target_dir="${ZINIAO_APP_CACHE_DIR:-${default_dir%/cli}}/cli"
+found=0
+old_ifs="$IFS"
+IFS=:
+for path_entry in ${PATH:-}; do
+  IFS="$old_ifs"
+  directory="${path_entry%/}"
+  [ -n "$directory" ] || continue
+  [ "$directory" = "${target_dir%/}" ] && continue
+  shim_path="$directory/ziniao"
+  [ -e "$shim_path" ] || [ -L "$shim_path" ] || continue
+  found=1
+  if [ "$apply" -eq 1 ]; then
+    rm -f -- "$shim_path"
+    log "Removed: $shim_path"
+  else
+    log "Would remove: $shim_path"
+  fi
+  IFS=:
+done
+IFS="$old_ifs"
+
+if [ "$found" -eq 0 ]; then
+  log "No ziniao shims found in PATH directories."
+elif [ "$apply" -eq 0 ]; then
+  log "Preview only. Re-run with --apply to remove these files."
+fi

package/scripts/run.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+const { existsSync } = require("node:fs");
+const { join } = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const binaryName = process.platform === "win32" ? "ziniao-cli.exe" : "ziniao-cli";
+const binaryPath = join(__dirname, "..", "bin", binaryName);
+
+if (!existsSync(binaryPath)) {
+  console.error(
+    [
+      `ziniao-cli binary not found at ${binaryPath}.`,
+      "For local package testing, set ZINIAO_CLI_BINARY to a built binary before npm install.",
+      "Example: $env:ZINIAO_CLI_BINARY = 'C:\\\\path\\\\to\\\\ziniao-cli.exe'",
+    ].join("\n")
+  );
+  process.exit(1);
+}
+
+const result = spawnSync(binaryPath, process.argv.slice(2), {
+  stdio: "inherit",
+  windowsHide: false,
+});
+
+if (result.error) {
+  console.error(result.error.message);
+  process.exit(1);
+}
+
+process.exit(result.status ?? 0);

package/scripts/setup-ziniao-cli.ps1

@@ -0,0 +1,179 @@
+# Synchronize the Ziniao desktop CLI into the per-user AppCache and register
+# that directory in the current user's PATH.
+#
+# Use `. .\scripts\setup-ziniao-cli.ps1` to refresh the current PowerShell.
+# A normal invocation persists PATH but cannot modify its parent PowerShell.
+
+$ErrorActionPreference = "Stop"
+$isDotSourced = $MyInvocation.InvocationName -eq "."
+
+function Write-Log([string]$Message) {
+  Write-Output "[ziniao-cli-path] $Message"
+}
+
+$arch = if ([Environment]::Is64BitOperatingSystem) {
+  if ($env:PROCESSOR_ARCHITEW6432) { $env:PROCESSOR_ARCHITEW6432 } else { $env:PROCESSOR_ARCHITECTURE }
+} else { $env:PROCESSOR_ARCHITECTURE }
+switch ($arch.ToLowerInvariant()) {
+  "amd64" { $archDir = "x64" }
+  "x86_64" { $archDir = "x64" }
+  "arm64" { $archDir = "arm64" }
+  default { throw "Unsupported CPU architecture: $arch" }
+}
+
+$sourceName = "ziniao.exe"
+$sourceRelative = Join-Path "envkit\cli\win32\$archDir" $sourceName
+$resourceRoot = "resources\app.asar.unpacked"
+
+$sourcePath = $null
+$guiExecutablePath = $null
+$checkedSourcePaths = @()
+if ($env:ZINIAO_CLI_SOURCE -and (Test-Path -LiteralPath $env:ZINIAO_CLI_SOURCE -PathType Leaf)) {
+  $sourcePath = $env:ZINIAO_CLI_SOURCE
+}
+if (-not $sourcePath -and $env:ZINIAO_INSTALL_DIR) {
+  $candidate = Join-Path $env:ZINIAO_INSTALL_DIR "$resourceRoot\$sourceRelative"
+  $checkedSourcePaths += $candidate
+  if (Test-Path -LiteralPath $candidate -PathType Leaf) {
+    $sourcePath = $candidate
+  }
+}
+if (-not $sourcePath) {
+  $uninstallKeys = @(
+    "HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall\*",
+    "HKLM:\Software\Microsoft\Windows\CurrentVersion\Uninstall\*",
+    "HKLM:\Software\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\*"
+  )
+  $uninstallEntries = Get-ItemProperty $uninstallKeys -ErrorAction SilentlyContinue |
+    Where-Object { $_.DisplayIcon -and $_.DisplayIcon -match "ziniao\.exe" }
+  foreach ($entry in $uninstallEntries) {
+    $displayIcon = ([string]$entry.DisplayIcon).Trim()
+    if ($displayIcon -match '^\s*"([^"]+\.exe)"') {
+      $executablePath = $matches[1]
+    } elseif ($displayIcon -match '^\s*(.*?\.exe)(?:,\d+)?(?:\s|$)') {
+      $executablePath = $matches[1]
+    } else {
+      continue
+    }
+    if (-not (Test-Path -LiteralPath $executablePath -PathType Leaf)) { continue }
+    $guiExecutablePath = $executablePath
+    $installDir = Split-Path -Parent $executablePath
+    $candidate = Join-Path $installDir "$resourceRoot\$sourceRelative"
+    $checkedSourcePaths += $candidate
+    if (Test-Path -LiteralPath $candidate -PathType Leaf) {
+      $sourcePath = $candidate
+      Write-Log "Found the Ziniao installation from the uninstall registry: $installDir"
+      break
+    }
+  }
+}
+if ($env:ZINIAO_APP_CACHE_DIR) {
+  $appCacheDir = $env:ZINIAO_APP_CACHE_DIR
+} else {
+  # The Windows GUI installs its CLI under %APPDATA%\ziniaobrowser\cli.
+  $appCacheDir = Join-Path $env:APPDATA "ziniaobrowser"
+}
+
+$targetDir = Join-Path $appCacheDir "cli"
+$targetPath = Join-Path $targetDir $sourceName
+New-Item -ItemType Directory -Path $targetDir -Force | Out-Null
+
+if ($guiExecutablePath) {
+  $guiPathFile = Join-Path $env:APPDATA "ziniaobrowser\gui-path"
+  try {
+    New-Item -ItemType Directory -Path (Split-Path -Parent $guiPathFile) -Force | Out-Null
+    [System.IO.File]::WriteAllText(
+      $guiPathFile,
+      "$guiExecutablePath$([Environment]::NewLine)",
+      [System.Text.Encoding]::ASCII
+    )
+    Write-Log "Wrote GUI path hint: $guiPathFile"
+  } catch {
+    Write-Log "WARN: Could not write GUI path hint: $($_.Exception.Message)"
+  }
+}
+
+function Get-FileSha256([string]$Path) {
+  $sha256 = [System.Security.Cryptography.SHA256]::Create()
+  $stream = [System.IO.File]::OpenRead($Path)
+  try {
+    return ([BitConverter]::ToString($sha256.ComputeHash($stream))).Replace("-", "")
+  } finally {
+    $stream.Dispose()
+    $sha256.Dispose()
+  }
+}
+
+if (-not $sourcePath) {
+  foreach ($checkedPath in ($checkedSourcePaths | Select-Object -Unique)) {
+    Write-Log "Checked CLI source path: $checkedPath"
+  }
+  if (Test-Path -LiteralPath $targetPath -PathType Leaf) {
+    Write-Log "CLI source was not found in the install directory; keeping the existing AppCache CLI: $targetPath"
+  } else {
+    Write-Log "WARN: ${sourceName} was not found in the install directory; skipping copy. Set `$env:ZINIAO_INSTALL_DIR or `$env:ZINIAO_CLI_SOURCE to override."
+  }
+} else {
+  $needsCopy = -not (Test-Path -LiteralPath $targetPath -PathType Leaf)
+  if (-not $needsCopy) {
+    $needsCopy = (Get-FileSha256 $sourcePath) -ne (Get-FileSha256 $targetPath)
+  }
+  if ($needsCopy) {
+    Copy-Item -LiteralPath $sourcePath -Destination $targetPath -Force
+    Write-Log "Synced CLI: $sourcePath -> $targetPath"
+  } else {
+    Write-Log "AppCache CLI is up to date: $targetPath"
+  }
+}
+
+function Install-PathShim {
+  if (-not (Test-Path -LiteralPath $targetPath -PathType Leaf)) { return }
+  $windowsAppsDir = Join-Path $env:LOCALAPPDATA "Microsoft\WindowsApps"
+  foreach ($pathEntry in @($env:Path -split ";" | Where-Object { $_ })) {
+    $normalizedPath = $pathEntry.TrimEnd('\')
+    if ($normalizedPath -ieq $windowsAppsDir.TrimEnd('\') -and (Test-Path -LiteralPath $windowsAppsDir -PathType Container)) {
+      $shimPath = Join-Path $windowsAppsDir $sourceName
+      if (-not (Test-Path -LiteralPath $shimPath)) {
+        try {
+          Copy-Item -LiteralPath $targetPath -Destination $shimPath -ErrorAction Stop
+          $script:shimInstalled = $true
+          Write-Log "Created the CLI shim in WindowsApps: $shimPath"
+        } catch {
+          Write-Log "WARN: Could not create the CLI shim in WindowsApps: $($_.Exception.Message)"
+        }
+      } else {
+        Write-Log "WindowsApps already contains a file named $sourceName; leaving it unchanged"
+      }
+      return
+    }
+    if ($normalizedPath -ieq $targetDir.TrimEnd('\')) {
+      $script:shimInstalled = $true
+      Write-Log "The current PATH already contains the AppCache CLI directory: $targetDir"
+      return
+    }
+  }
+  Write-Log "The AppCache CLI directory is not on the current PATH; no shim was created in another directory."
+}
+
+$shimInstalled = $false
+Install-PathShim
+
+$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
+$entries = @($userPath -split ";" | Where-Object { $_ })
+if (-not ($entries | Where-Object { $_.TrimEnd('\') -ieq $targetDir.TrimEnd('\') })) {
+  [Environment]::SetEnvironmentVariable("Path", (($entries + $targetDir) -join ";"), "User")
+  Write-Log "Added to the user PATH: $targetDir"
+}
+
+$currentEntries = @($env:Path -split ";" | Where-Object { $_ })
+if (-not ($currentEntries | Where-Object { $_.TrimEnd('\') -ieq $targetDir.TrimEnd('\') })) {
+  $env:Path = "$targetDir;$env:Path"
+}
+if ($shimInstalled) {
+  Write-Log "The CLI is already available on the current PATH; this PowerShell session needs no PATH refresh"
+} elseif ($isDotSourced) {
+  Write-Log "The current PowerShell PATH was refreshed"
+} else {
+  Write-Log "The current process PATH was refreshed; dot-source this script in the parent PowerShell or reopen the terminal"
+}
+Write-Log "Verification command: Get-Command ziniao"

package/scripts/setup-ziniao-cli.sh

@@ -0,0 +1,212 @@
+#!/bin/sh
+# Synchronize the Ziniao desktop CLI into the per-user AppCache and register
+# that directory in the current user's shell PATH.
+#
+# Use `source scripts/setup-ziniao-cli.sh` when the current shell should be
+# refreshed immediately. A normal execution can persist PATH but cannot modify
+# its parent shell.
+
+log() { printf '%s\n' "[ziniao-cli-path] $*"; }
+fail() { printf '%s\n' "[ziniao-cli-path] ERROR: $*" >&2; return 1 2>/dev/null || exit 1; }
+
+is_sourced=0
+if [ -n "${BASH_VERSION:-}" ]; then
+  [ "${BASH_SOURCE[0]:-$0}" != "$0" ] && is_sourced=1
+elif [ -n "${ZSH_EVAL_CONTEXT:-}" ]; then
+  case "$ZSH_EVAL_CONTEXT" in
+    *:file) is_sourced=1 ;;
+  esac
+fi
+
+if [ "$is_sourced" -eq 0 ]; then
+  set -eu
+fi
+
+platform="$(uname -s 2>/dev/null || printf 'unknown')"
+machine="$(uname -m 2>/dev/null || printf 'unknown')"
+
+case "$platform" in
+  Darwin) platform_dir="darwin"; source_name="ziniao"; ;;
+  Linux) platform_dir="linux"; source_name="ziniao"; ;;
+  MINGW*|MSYS*|CYGWIN*)
+    fail "Windows shell detected; use PowerShell: scripts/setup-ziniao-cli.ps1"
+    return 1 2>/dev/null || exit 1
+    ;;
+  *) fail "Unsupported operating system: $platform"; return 1 2>/dev/null || exit 1 ;;
+esac
+
+case "$machine" in
+  arm64|aarch64) arch_dir="arm64" ;;
+  x86_64|amd64) arch_dir="x64" ;;
+  *) fail "Unsupported CPU architecture: $machine"; return 1 2>/dev/null || exit 1 ;;
+esac
+
+home_dir="${HOME:?HOME is not set}"
+
+find_source() {
+  if [ -n "${ZINIAO_CLI_SOURCE:-}" ] && [ -f "$ZINIAO_CLI_SOURCE" ]; then
+    printf '%s\n' "$ZINIAO_CLI_SOURCE"
+    return 0
+  fi
+
+  for candidate_arch in "$arch_dir" x64 arm64; do
+    source_rel="envkit/cli/$platform_dir/$candidate_arch/$source_name"
+    if [ -n "${ZINIAO_INSTALL_DIR:-}" ]; then
+      candidate="$ZINIAO_INSTALL_DIR/$source_rel"
+      if [ -f "$candidate" ]; then
+        printf '%s\n' "$candidate"
+        return 0
+      fi
+    fi
+
+    for install_root in \
+      "/Applications/ziniao.app/Contents/Resources/app.asar.unpacked" \
+      "$home_dir/Applications/ziniao.app/Contents/Resources/app.asar.unpacked" \
+      "$home_dir/Library/Application Support/ziniaobrowser/app.asar.unpacked" \
+      "/opt/ziniao/resources/app.asar.unpacked"; do
+      candidate="$install_root/$source_rel"
+      if [ -f "$candidate" ]; then
+        printf '%s\n' "$candidate"
+        return 0
+      fi
+    done
+  done
+  return 1
+}
+
+log_source_candidates() {
+  [ -n "${ZINIAO_CLI_SOURCE:-}" ] && log "Checked CLI source path: $ZINIAO_CLI_SOURCE"
+  for candidate_arch in "$arch_dir" x64 arm64; do
+    source_rel="envkit/cli/$platform_dir/$candidate_arch/$source_name"
+    [ -n "${ZINIAO_INSTALL_DIR:-}" ] && log "Checked CLI source path: $ZINIAO_INSTALL_DIR/$source_rel"
+    for install_root in \
+      "/Applications/ziniao.app/Contents/Resources/app.asar.unpacked" \
+      "$home_dir/Applications/ziniao.app/Contents/Resources/app.asar.unpacked" \
+      "$home_dir/Library/Application Support/ziniaobrowser/app.asar.unpacked" \
+      "/opt/ziniao/resources/app.asar.unpacked"; do
+      log "Checked CLI source path: $install_root/$source_rel"
+    done
+  done
+}
+
+find_gui_executable() {
+  case "$platform_dir" in
+    darwin)
+      for candidate in \
+        "/Applications/ziniao.app/Contents/MacOS/ziniaobrowser" \
+        "/Applications/ziniao.app/Contents/MacOS/ziniao" \
+        "$home_dir/Applications/ziniao.app/Contents/MacOS/ziniaobrowser" \
+        "$home_dir/Applications/ziniao.app/Contents/MacOS/ziniao"; do
+        [ -f "$candidate" ] && { printf '%s\n' "$candidate"; return 0; }
+      done
+      ;;
+    linux)
+      for candidate in \
+        "/opt/ziniao/ziniaobrowser" \
+        "/opt/ziniao/ziniao" \
+        "/usr/lib/ziniaobrowser/ziniaobrowser" \
+        "/usr/lib/ziniaobrowser/ziniao"; do
+        [ -f "$candidate" ] && { printf '%s\n' "$candidate"; return 0; }
+      done
+      ;;
+  esac
+  return 1
+}
+
+if [ -n "${ZINIAO_APP_CACHE_DIR:-}" ]; then
+  target_dir="$ZINIAO_APP_CACHE_DIR/cli"
+else
+  case "$platform_dir" in
+    darwin) target_dir="$home_dir/Library/Application Support/ziniaobrowser/cli" ;;
+    *) target_dir="${XDG_CONFIG_HOME:-$home_dir/.config}/ziniaobrowser/cli" ;;
+  esac
+fi
+
+source_path="$(find_source || true)"
+gui_executable_path="$(find_gui_executable || true)"
+target_path="$target_dir/$source_name"
+mkdir -p "$target_dir"
+
+if [ -n "$source_path" ]; then
+  log "CLI source path: $source_path"
+else
+  log_source_candidates
+fi
+
+if [ -n "$gui_executable_path" ]; then
+  case "$platform_dir" in
+    darwin) gui_path_file="$home_dir/Library/Application Support/ziniaobrowser/gui-path" ;;
+    *)
+      xdg_config_home="${XDG_CONFIG_HOME:-$home_dir/.config}"
+      gui_path_file="$xdg_config_home/ziniaobrowser/gui-path"
+      ;;
+  esac
+  if mkdir -p "$(dirname "$gui_path_file")" && printf '%s\n' "$gui_executable_path" > "$gui_path_file"; then
+    log "Wrote GUI path hint: $gui_path_file"
+  else
+    log "WARN: Could not write GUI path hint: $gui_path_file"
+  fi
+fi
+if [ -z "$source_path" ]; then
+  if [ -f "$target_path" ]; then
+    log "CLI source was not found in the install directory; keeping the existing AppCache CLI: $target_path"
+  else
+    log "WARN: ${source_name} was not found in the install directory; skipping copy. Set ZINIAO_INSTALL_DIR or ZINIAO_CLI_SOURCE to override."
+  fi
+elif [ ! -f "$target_path" ] || ! cmp -s "$source_path" "$target_path"; then
+  cp "$source_path" "$target_path"
+  chmod 755 "$target_path"
+  log "Synced CLI: $source_path -> $target_path"
+else
+  log "AppCache CLI is up to date: $target_path"
+fi
+
+shim_installed=0
+install_path_shim() {
+  [ -f "$target_path" ] || return 0
+  case ":${PATH:-}:" in
+    *:"$target_dir":*)
+      shim_installed=1
+      log "The current PATH already contains the AppCache CLI directory: $target_dir"
+      ;;
+    *)
+      log "The AppCache CLI directory is not on the current PATH; no shim will be created elsewhere: $target_dir"
+      ;;
+  esac
+}
+
+install_path_shim
+
+export PATH="$target_dir${PATH:+:$PATH}"
+
+profile=""
+case "${SHELL:-}" in
+  */zsh) profile="$home_dir/.zshrc" ;;
+  */bash) profile="$home_dir/.bashrc" ;;
+esac
+if [ -z "$profile" ]; then
+  case "$platform_dir" in
+    darwin) profile="$home_dir/.zshrc" ;;
+    *) profile="$home_dir/.profile" ;;
+  esac
+fi
+
+marker="# ziniao-cli: AppCache CLI PATH"
+path_line="export PATH=\"$target_dir:\$PATH\""
+if ! grep -Fqx "$marker" "$profile" 2>/dev/null; then
+  mkdir -p "$(dirname "$profile")"
+  printf '\n%s\n' "$marker" >> "$profile"
+  log "Added to shell profile: $profile"
+fi
+if ! grep -Fqx "$path_line" "$profile" 2>/dev/null; then
+  printf '%s\n' "$path_line" >> "$profile"
+fi
+
+if [ "$shim_installed" -eq 1 ]; then
+  log "The CLI is already on the current PATH; this terminal needs no PATH refresh"
+elif [ "$is_sourced" -eq 1 ]; then
+  log "The current shell PATH was refreshed"
+else
+  log "The current process PATH was refreshed; source \"$profile\" in the parent terminal"
+fi
+log "Verification command: command -v $source_name"