@steinscheng/zhaotongkuan 0.8.0

package/LICENSE.txt

@@ -0,0 +1,5 @@
+Copyright (c) 2026 找同款. All rights reserved.
+
+This software is proprietary and confidential. No permission is granted to
+copy, redistribute, sublicense, sell, publish, reverse engineer, or use this
+software except under a written license issued by the copyright holder.

package/README.md

@@ -0,0 +1,23 @@
+# @steinscheng/zhaotongkuan
+
+这是「找同款」的轻量安装引导器，不包含业务源码、激活码、渠道凭据或用户数据。它会获取与版本对应的 GitHub Release，校验整个 ZIP 的 SHA-256，然后以参数数组调用发行包内的确定性安装器。
+
+```bash
+npx @steinscheng/zhaotongkuan@latest install --start --json
+```
+
+私有 GitHub Release 会优先使用已登录的 `gh` CLI 下载；引导器不读取、保存或输出 GitHub Token。也可以安装发行方通过其他可信渠道交付的本地 ZIP：
+
+```bash
+npx @steinscheng/zhaotongkuan@latest install \
+  --archive "/absolute/path/to/zhaotongkuan.zip" \
+  --expected-sha256 "<trusted 64-character sha256>" \
+  --start \
+  --json
+```
+
+必须由发行方通过独立可信渠道提供 `--expected-sha256`。不要从和 ZIP 同一个未验证页面临时复制哈希。
+
+需要 macOS 或 Linux（x64/arm64）、Node.js 18.18+ 和 Python 3.10+。第一阶段使用 Python 运行已审计的安装事务；引导器不会安装系统级 Python、FFmpeg 或 Codex。当前发行包依赖 POSIX 启动脚本，不声明 Windows 支持。
+
+若机器同时保留系统旧版 Python 和新版 Python，可用 `--python /absolute/path/to/python3` 显式指定；macOS 引导器也会检查 Homebrew 的标准安装位置。

package/bin/zhaotongkuan.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { main } from "../src/cli.js";
+
+process.exitCode = await main(process.argv.slice(2));

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@steinscheng/zhaotongkuan",
+  "version": "0.8.0",
+  "description": "Small, verifiable installer bootstrap for the Zhaotongkuan Codex plugin",
+  "type": "module",
+  "bin": {
+    "zhaotongkuan": "bin/zhaotongkuan.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE.txt"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "pack:check": "npm pack --dry-run --json"
+  },
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "license": "SEE LICENSE IN LICENSE.txt",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/SchengSteins/zhaotongkuan.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/cli.js

@@ -0,0 +1,446 @@
+import { createHash } from "node:crypto";
+import { createReadStream, createWriteStream, existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { copyFile, lstat, mkdir, realpath } from "node:fs/promises";
+import { get as httpsGet } from "node:https";
+import { tmpdir } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const CHANNEL_PATH = join(PACKAGE_ROOT, "src", "release-channel.json");
+const EXTRACTOR_PATH = join(PACKAGE_ROOT, "src", "extract_installer.py");
+const PACKAGE_JSON = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8"));
+const SENSITIVE_KEY = /^(?:access_?token|authorization|cookie|credential|device_?id|license_?code|password|private_?key|refresh_?token|secret|session)$/iu;
+
+export const MAX_ARCHIVE_BYTES = 512 * 1024 * 1024;
+export const ALLOWED_DOWNLOAD_HOSTS = new Set([
+  "github.com",
+  "objects.githubusercontent.com",
+  "release-assets.githubusercontent.com",
+]);
+
+export class BootstrapError extends Error {
+  constructor(message, code = "install_failed") {
+    super(message);
+    this.name = "BootstrapError";
+    this.code = code;
+  }
+}
+
+function cleanText(value, label) {
+  const text = String(value ?? "");
+  if (!text || /[\0\r\n]/u.test(text)) {
+    throw new BootstrapError(`${label} is empty or contains control characters`, "invalid_argument");
+  }
+  return text;
+}
+
+export function normalizeTarget(platform = process.platform, arch = process.arch) {
+  const platforms = { darwin: "darwin", linux: "linux" };
+  const architectures = { x64: "amd64", arm64: "arm64" };
+  if (!platforms[platform] || !architectures[arch]) {
+    throw new BootstrapError(`unsupported platform: ${platform}/${arch}`, "unsupported_platform");
+  }
+  return { platform: platforms[platform], arch: architectures[arch] };
+}
+
+export function validateSha256(value) {
+  const digest = String(value ?? "").trim().toLowerCase();
+  if (!/^[0-9a-f]{64}$/u.test(digest)) {
+    throw new BootstrapError("expected SHA-256 must be 64 hexadecimal characters", "invalid_checksum");
+  }
+  return digest;
+}
+
+export async function sha256File(path) {
+  const digest = createHash("sha256");
+  let size = 0;
+  for await (const chunk of createReadStream(path)) {
+    size += chunk.length;
+    if (size > MAX_ARCHIVE_BYTES) {
+      throw new BootstrapError("release archive exceeds the size limit", "archive_too_large");
+    }
+    digest.update(chunk);
+  }
+  return digest.digest("hex");
+}
+
+export async function verifyArchive(path, expectedSha256) {
+  const expected = validateSha256(expectedSha256);
+  const actual = await sha256File(path);
+  if (actual !== expected) {
+    throw new BootstrapError("release archive SHA-256 does not match the trusted value", "checksum_mismatch");
+  }
+  return actual;
+}
+
+export function parseArgs(argv) {
+  const result = {
+    command: "",
+    json: false,
+    dryRun: false,
+    start: false,
+    archive: "",
+    expectedSha256: "",
+    version: "",
+    python: "",
+    dataDir: "",
+    installRoot: "",
+    codexBin: "",
+    marketplaceName: "",
+    port: "",
+  };
+  const values = [...argv];
+  if (values[0] && !values[0].startsWith("-")) result.command = values.shift();
+  const valueFlags = new Map([
+    ["--archive", "archive"],
+    ["--archive-url", "archive"],
+    ["--expected-sha256", "expectedSha256"],
+    ["--version", "version"],
+    ["--python", "python"],
+    ["--data-dir", "dataDir"],
+    ["--install-root", "installRoot"],
+    ["--codex-bin", "codexBin"],
+    ["--marketplace-name", "marketplaceName"],
+    ["--port", "port"],
+  ]);
+  for (let index = 0; index < values.length; index += 1) {
+    const flag = values[index];
+    if (flag === "--json") result.json = true;
+    else if (flag === "--dry-run") result.dryRun = true;
+    else if (flag === "--start") result.start = true;
+    else if (flag === "--help" || flag === "-h") result.command = "help";
+    else if (flag === "--bootstrap-version") result.command = "version";
+    else if (valueFlags.has(flag)) {
+      const next = values[index + 1];
+      if (next === undefined) throw new BootstrapError(`${flag} requires a value`, "invalid_argument");
+      result[valueFlags.get(flag)] = cleanText(next, flag);
+      index += 1;
+    } else {
+      throw new BootstrapError(`unknown argument: ${flag}`, "invalid_argument");
+    }
+  }
+  return result;
+}
+
+export function loadChannel() {
+  const channel = JSON.parse(readFileSync(CHANNEL_PATH, "utf8"));
+  if (channel.schema_version !== 1 || !channel.repository || !channel.version) {
+    throw new BootstrapError("bundled release channel is invalid", "invalid_release_channel");
+  }
+  return channel;
+}
+
+export function resolveRelease(options, channel = loadChannel(), target = normalizeTarget()) {
+  const version = options.version || channel.version;
+  const artifact = channel.artifacts?.[`${target.platform}-${target.arch}`] ?? channel.artifacts?.any;
+  if (!artifact || !artifact.url || !artifact.sha256) {
+    throw new BootstrapError(`no release artifact for ${target.platform}/${target.arch}`, "unsupported_platform");
+  }
+  if (options.version && options.version !== channel.version && !artifact.url.includes("{version}")) {
+    throw new BootstrapError("the bundled channel does not provide a template for the requested version", "invalid_release_channel");
+  }
+  const archive = options.archive || artifact.url.replaceAll("{version}", version);
+  const expectedSha256 = options.expectedSha256 || artifact.sha256;
+  if (options.archive && !options.expectedSha256) {
+    throw new BootstrapError("--archive requires --expected-sha256 from a trusted channel", "missing_checksum");
+  }
+  return {
+    repository: cleanText(channel.repository, "repository"),
+    version: cleanText(version, "version"),
+    archive: cleanText(archive, "archive"),
+    expectedSha256: validateSha256(expectedSha256),
+    target,
+  };
+}
+
+export function githubReleaseCoordinates(rawUrl, expectedRepository) {
+  let parsed;
+  try {
+    parsed = new URL(rawUrl);
+  } catch {
+    return null;
+  }
+  if (
+    parsed.protocol !== "https:" ||
+    parsed.hostname !== "github.com" ||
+    parsed.username ||
+    parsed.password ||
+    parsed.search ||
+    parsed.hash
+  ) return null;
+  const parts = parsed.pathname.split("/").filter(Boolean).map(decodeURIComponent);
+  if (parts.length !== 6 || parts[2] !== "releases" || parts[3] !== "download") return null;
+  const repository = `${parts[0]}/${parts[1]}`;
+  if (repository.toLowerCase() !== expectedRepository.toLowerCase()) return null;
+  const tag = parts[4];
+  const asset = parts.slice(5).join("/");
+  if (!/^v?[0-9A-Za-z][0-9A-Za-z.+_-]*$/u.test(tag) || asset.includes("/") || asset.startsWith("-")) {
+    return null;
+  }
+  return { repository, tag, asset };
+}
+
+export function executableWorks(command) {
+  const probe = spawnSync(command, ["--version"], {
+    shell: false,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: 10_000,
+  });
+  if (probe.error || probe.status !== 0) return false;
+  const output = `${String(probe.stdout || "")}\n${String(probe.stderr || "")}`;
+  const match = output.match(/Python\s+(\d+)\.(\d+)/u);
+  return Boolean(match) && (Number(match[1]) > 3 || (Number(match[1]) === 3 && Number(match[2]) >= 10));
+}
+
+export function findPython(preferred = "", candidates) {
+  const values = candidates ?? [
+    preferred,
+    process.env.PYTHON_BIN,
+    "python3",
+    "/opt/homebrew/bin/python3",
+    "/usr/local/bin/python3",
+    "/usr/bin/python3",
+    "python",
+  ];
+  for (const value of values) {
+    if (!value) continue;
+    const candidate = String(value);
+    if (/[\0\r\n]/u.test(candidate)) continue;
+    if (executableWorks(candidate)) return candidate;
+  }
+  throw new BootstrapError("Python 3.10+ was not found; install Python and retry", "python_missing");
+}
+
+function runGhDownload(coordinates, destination) {
+  const gh = spawnSync("gh", [
+    "release", "download", coordinates.tag,
+    "--repo", coordinates.repository,
+    "--pattern", coordinates.asset,
+    "--dir", dirname(destination),
+    "--clobber",
+  ], {
+    shell: false,
+    stdio: "ignore",
+    timeout: 180_000,
+  });
+  const downloaded = join(dirname(destination), coordinates.asset);
+  if (!gh.error && gh.status === 0 && existsSync(downloaded)) return downloaded;
+  return "";
+}
+
+function allowedHttpsUrl(rawUrl) {
+  const parsed = new URL(rawUrl);
+  if (parsed.protocol !== "https:" || !ALLOWED_DOWNLOAD_HOSTS.has(parsed.hostname)) {
+    throw new BootstrapError(`download host is not allowed: ${parsed.hostname || parsed.protocol}`, "download_denied");
+  }
+  return parsed;
+}
+
+function downloadHttps(rawUrl, destination, redirects = 0) {
+  const parsed = allowedHttpsUrl(rawUrl);
+  if (redirects > 3) return Promise.reject(new BootstrapError("too many release redirects", "download_failed"));
+  return new Promise((resolvePromise, rejectPromise) => {
+    const request = httpsGet(parsed, { headers: { "user-agent": `zhaotongkuan-bootstrap/${PACKAGE_JSON.version}` } }, (response) => {
+      const status = response.statusCode ?? 0;
+      if (status >= 300 && status < 400 && response.headers.location) {
+        response.resume();
+        let redirected;
+        try {
+          redirected = new URL(response.headers.location, parsed).toString();
+          allowedHttpsUrl(redirected);
+        } catch (error) {
+          rejectPromise(error);
+          return;
+        }
+        downloadHttps(redirected, destination, redirects + 1).then(resolvePromise, rejectPromise);
+        return;
+      }
+      if (status !== 200) {
+        response.resume();
+        rejectPromise(new BootstrapError(`release download returned HTTP ${status}`, "download_failed"));
+        return;
+      }
+      let size = 0;
+      const output = createWriteStream(destination, { flags: "wx", mode: 0o600 });
+      response.on("data", (chunk) => {
+        size += chunk.length;
+        if (size > MAX_ARCHIVE_BYTES) request.destroy(new BootstrapError("release archive exceeds the size limit", "archive_too_large"));
+      });
+      response.pipe(output);
+      output.on("finish", () => output.close(() => resolvePromise(destination)));
+      output.on("error", rejectPromise);
+      response.on("error", rejectPromise);
+    });
+    request.setTimeout(120_000, () => request.destroy(new BootstrapError("release download timed out", "download_failed")));
+    request.on("error", rejectPromise);
+  });
+}
+
+export async function acquireArchive(source, destination, repository) {
+  if (source.startsWith("file://")) {
+    const local = fileURLToPath(new URL(source));
+    const info = await lstat(local);
+    if (!info.isFile() || info.isSymbolicLink()) {
+      throw new BootstrapError("local release archive must be a regular non-symlink file", "archive_invalid");
+    }
+    await copyFile(await realpath(local), destination);
+    return destination;
+  }
+  if (isAbsolute(source) || source.startsWith(".") || existsSync(source)) {
+    const local = resolve(source);
+    const info = await lstat(local);
+    if (!info.isFile() || info.isSymbolicLink()) {
+      throw new BootstrapError("local release archive must be a regular non-symlink file", "archive_invalid");
+    }
+    await copyFile(await realpath(local), destination);
+    return destination;
+  }
+  const coordinates = githubReleaseCoordinates(source, repository);
+  if (!coordinates) {
+    throw new BootstrapError("initial HTTPS URL must be an exact release asset from the configured GitHub repository", "download_denied");
+  }
+  const downloaded = runGhDownload(coordinates, destination);
+  if (downloaded) return downloaded;
+  return downloadHttps(source, destination);
+}
+
+export function installerArgv(options, release, archivePath, installerPath) {
+  const argv = [
+    installerPath,
+    "--archive", archivePath,
+    "--expected-sha256", release.expectedSha256,
+    "--json",
+  ];
+  if (options.dryRun) argv.push("--dry-run");
+  if (options.start) argv.push("--start");
+  const mappings = [
+    [options.dataDir, "--data-dir"],
+    [options.installRoot, "--install-root"],
+    [options.codexBin, "--codex-bin"],
+    [options.marketplaceName, "--marketplace-name"],
+    [options.port, "--port"],
+  ];
+  for (const [value, flag] of mappings) if (value) argv.push(flag, value);
+  return argv;
+}
+
+function parseInstallerJson(stdout) {
+  const text = String(stdout ?? "").trim();
+  try {
+    const result = JSON.parse(text);
+    if (!result || typeof result !== "object" || Array.isArray(result)) throw new Error("not an object");
+    return result;
+  } catch {
+    throw new BootstrapError("deterministic installer did not return its JSON contract", "installer_contract_error");
+  }
+}
+
+export function sanitizeForJson(value, key = "", depth = 0) {
+  if (SENSITIVE_KEY.test(key)) return "[redacted]";
+  if (depth > 12) return "[truncated]";
+  if (Array.isArray(value)) return value.slice(0, 500).map((item) => sanitizeForJson(item, "", depth + 1));
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).slice(0, 500).map(([childKey, childValue]) => [
+        childKey,
+        sanitizeForJson(childValue, childKey, depth + 1),
+      ]),
+    );
+  }
+  if (typeof value === "string") {
+    return value
+      .replace(/https:\/\/[^\s"'<>]+/giu, (raw) => {
+        try {
+          const url = new URL(raw);
+          return `${url.protocol}//${url.hostname}${url.pathname}${url.search ? "?[redacted]" : ""}`;
+        } catch {
+          return "[redacted-url]";
+        }
+      })
+      .replace(/((?:access_?token|authorization|cookie|password|secret|signature|token)=)[^\s&]+/giu, "$1[redacted]");
+  }
+  return value;
+}
+
+function help() {
+  return `Usage:\n  npx @steinscheng/zhaotongkuan@latest install [options]\n\nSupported hosts:\n  macOS or Linux on x64/arm64\n\nOptions:\n  --archive <path-or-https-url>  Install an explicit release archive\n  --expected-sha256 <digest>     Trusted SHA-256 (required with --archive)\n  --dry-run                      Validate without writing\n  --start                        Start and health-check the service\n  --data-dir <path>              Preserve business data outside the program\n  --install-root <path>          Override managed program directory\n  --codex-bin <path>             Use an explicit Codex CLI\n  --python <path>                Use an explicit Python 3.10+ executable\n  --json                         Emit one JSON object\n`;
+}
+
+function emitError(error, jsonMode) {
+  const rawMessage = String(error?.message || error || "installation failed").replace(/[\r\n]+/gu, " ").slice(0, 1000);
+  const message = sanitizeForJson(rawMessage);
+  if (jsonMode) {
+    process.stdout.write(`${JSON.stringify({
+      schema_version: 1,
+      ok: false,
+      error: error?.code || "install_failed",
+      message,
+      manual_actions: [{ code: "resolve_install_error", message: "Resolve the reported issue and rerun the same install command." }],
+    })}\n`);
+  } else {
+    process.stderr.write(`Installation failed: ${message}\n`);
+  }
+}
+
+export async function main(argv) {
+  let options = { json: argv.includes("--json") };
+  let temporary = "";
+  try {
+    options = parseArgs(argv);
+    if (options.command === "help" || !options.command) {
+      process.stdout.write(help());
+      return 0;
+    }
+    if (options.command === "version") {
+      process.stdout.write(`${PACKAGE_JSON.version}\n`);
+      return 0;
+    }
+    if (options.command !== "install") throw new BootstrapError(`unknown command: ${options.command}`, "invalid_argument");
+
+    const release = resolveRelease(options);
+    const python = findPython(options.python);
+    temporary = mkdtempSync(join(tmpdir(), "zhaotongkuan-bootstrap-"));
+    await mkdir(temporary, { recursive: true });
+    const archiveDestination = join(temporary, basename(new URL(release.archive, "file:///").pathname) || "release.zip");
+    const archivePath = await acquireArchive(release.archive, archiveDestination, release.repository);
+    await verifyArchive(archivePath, release.expectedSha256);
+
+    const installerPath = join(temporary, "agent_install.py");
+    const extracted = spawnSync(python, [EXTRACTOR_PATH, archivePath, installerPath], {
+      shell: false,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 30_000,
+    });
+    if (extracted.error || extracted.status !== 0) {
+      throw new BootstrapError("could not read the deterministic installer from the verified release", "archive_invalid");
+    }
+    const child = spawnSync(python, installerArgv(options, release, archivePath, installerPath), {
+      shell: false,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 30 * 60_000,
+    });
+    if (child.error) throw new BootstrapError(`installer process failed: ${child.error.message}`, "installer_failed");
+    const result = sanitizeForJson(parseInstallerJson(child.stdout));
+    const output = {
+      ...result,
+      bootstrap: {
+        version: PACKAGE_JSON.version,
+        release_version: release.version,
+        target: `${release.target.platform}-${release.target.arch}`,
+        checksum_verified: true,
+      },
+    };
+    process.stdout.write(`${JSON.stringify(output)}\n`);
+    return child.status === 0 && result.ok === true ? 0 : (child.status || 1);
+  } catch (error) {
+    emitError(error, Boolean(options.json));
+    return 1;
+  } finally {
+    if (temporary) rmSync(temporary, { recursive: true, force: true });
+  }
+}

package/src/extract_installer.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+"""Extract one fixed, size-limited installer member from a verified release ZIP."""
+
+from __future__ import annotations
+
+import os
+import stat
+import sys
+import zipfile
+from pathlib import Path
+
+
+EXPECTED_MEMBER = "zhaotongkuan/scripts/agent_install.py"
+MAX_INSTALLER_BYTES = 2 * 1024 * 1024
+
+
+def fail(message: str) -> None:
+    print(message, file=sys.stderr)
+    raise SystemExit(1)
+
+
+def main() -> None:
+    if len(sys.argv) != 3:
+        fail("expected archive and destination arguments")
+    archive = Path(sys.argv[1])
+    destination = Path(sys.argv[2])
+    if destination.exists() or destination.is_symlink():
+        fail("installer destination already exists")
+    try:
+        with zipfile.ZipFile(archive, "r") as release:
+            matches = [item for item in release.infolist() if item.filename == EXPECTED_MEMBER]
+            if len(matches) != 1:
+                fail("release must contain exactly one fixed installer member")
+            member = matches[0]
+            mode = (member.external_attr >> 16) & 0xFFFF
+            if member.is_dir() or stat.S_ISLNK(mode) or member.flag_bits & 0x1:
+                fail("release installer member is not a plain unencrypted file")
+            if member.file_size <= 0 or member.file_size > MAX_INSTALLER_BYTES:
+                fail("release installer member has an invalid size")
+            destination.parent.mkdir(parents=True, exist_ok=True)
+            written = 0
+            with release.open(member, "r") as source, destination.open("xb") as target:
+                while True:
+                    chunk = source.read(64 * 1024)
+                    if not chunk:
+                        break
+                    written += len(chunk)
+                    if written > MAX_INSTALLER_BYTES:
+                        fail("release installer member exceeds the size limit")
+                    target.write(chunk)
+            if written != member.file_size:
+                fail("release installer member size does not match its ZIP record")
+        os.chmod(destination, 0o700)
+    except (OSError, zipfile.BadZipFile, zipfile.LargeZipFile) as error:
+        fail(f"cannot read verified release ZIP: {error}")
+
+
+if __name__ == "__main__":
+    main()

package/src/release-channel.json

@@ -0,0 +1,11 @@
+{
+  "schema_version": 1,
+  "repository": "SchengSteins/zhaotongkuan",
+  "version": "0.8.0",
+  "artifacts": {
+    "any": {
+      "url": "https://github.com/SchengSteins/zhaotongkuan/releases/download/v0.8.0/zhaotongkuan-0.8.0.zip",
+      "sha256": "4bee7fcb5a24facbaa8d943ce8a41a6e900464de9f371bd06a545bc4aae14ad5"
+    }
+  }
+}