coconet 0.4.0

package/README.md

@@ -0,0 +1,32 @@
+# npm Launcher and Setup Wrapper
+
+本目录发布未加 scope 的 `coconet` npm 包。默认入口是：
+
+```bash
+npm install --global coconet
+coconet version
+```
+
+npm 在自己已经可执行的全局 bin 目录安装一个稳定 POSIX shell 启动器。启动器读取包版本和 `${XDG_DATA_HOME:-$HOME/.local/share}/coconet/current/manifest.json`：版本匹配时直接 `exec` 原生 Runtime；缺失或不匹配时调用该 npm 包的 `coconet-setup`，安装成功后在同一终端继续执行用户原参数。Node 只参与首次安装和升级，不成为日常父进程，也不需要再把 `~/.local/bin` 加入 `PATH`。
+
+Bootstrap 在 npm 包与目标 Runtime 同版本时使用 `--no-bin-link`，只原子切换版本化 `current`，不会覆盖 npm 管理的 `coconet`。归档直装仍可创建 `${XDG_BIN_HOME:-$HOME/.local/bin}/coconet`。`coconet-setup` 是显式恢复、本地候选和高级参数入口，不是正常安装后的必做步骤。包同时暴露两个 bin，因此不把 `npx coconet` 的单-bin 推断作为正式交互或发布门禁；不要把本包加入业务仓库 dependency。
+
+| 文件 | 职责 |
+|---|---|
+| `bin/coconet` | 解析 npm 包与当前 Runtime 版本，按需启动 setup，并以原参数 `exec` 匹配 Runtime。 |
+| `cli.mjs` | 下载、安全解压、临时目录清理与 Bootstrap 进程编排。 |
+| `core.mjs` | 平台映射、制品命名、参数、checksum 和 archive path 契约。 |
+| `cli.test.mjs` | 覆盖严格 umask、启动器匹配 / 缺失 / 升级 / 取消 / 失败状态，以及同一 Shell 的临时全局安装。 |
+| `core.test.mjs` | 覆盖支持矩阵、参数映射、checksum、路径逃逸与本地文件校验。 |
+| `package.json` / `package-lock.json` | npm 身份、双 bin、Node 基线、固定 tar 依赖与可重现安装。 |
+| `release-manifest.json` | 固定 npm 同版本、`xfey/coconet` 精确 Tag 与四个平台 Client SHA-256；内部版本保持空映射。 |
+
+包装层根据 macOS / Linux 与 `amd64` / `arm64` 选择制品，通过 HTTPS 下载或读取用户明确提供的本地 archive 与 checksum，验证 SHA-256，拒绝不安全 tar 条目和 mode，再执行同版本 Bootstrap。本地 artifact 同样经过文件类型、archive checksum、安全 tar 条目和 bundle Manifest 四层校验。包装层不会连接仓库或上传 Session。
+
+源码包始终设置 `private: true`；内部清单的 archive 映射为空，默认安装会在网络请求前安全拒绝，内部候选必须显式提供同一候选目录的 `--artifact` / `--checksum`。公共构建在隔离 staging 中同步 npm 与双 Plugin 的稳定版本并写入四个平台 hash；macOS notarization 和 GitHub assets 回归通过后，才允许 `npm publish <tgz> --access public --auth-type=web`。
+
+四个平台 Client archive 合计约 186 MB，而每位用户只需要约 44–49 MB 的当前平台内容，因此 npm 保持薄入口，`xfey/coconet` GitHub Release 承载 Client、独立 Server、checksum 和手动下载。
+
+Coconet 不读取或迁移旧产品的 npm launcher、Runtime 根或用户状态。候选安装必须使用全新 HOME / XDG / npm prefix 验证直接安装路径。
+
+代码、依赖、参数或下载边界变化时必须同步更新本文档、Bootstrap、验证记录和锁文件。

package/bin/coconet

@@ -0,0 +1,91 @@
+#!/bin/sh
+
+# Keep the npm command stable while the native Runtime remains versioned under
+# the user's Coconet data root. Node is used only when setup or an upgrade is
+# required; successful daily commands replace this process with the Runtime.
+
+launcher=$0
+link_depth=0
+while [ -L "$launcher" ]; do
+  link_depth=$((link_depth + 1))
+  if [ "$link_depth" -gt 16 ]; then
+    printf '%s\n' "coconet: the npm launcher contains too many symbolic links" >&2
+    exit 1
+  fi
+  launcher_directory=$(CDPATH= cd -P "$(dirname "$launcher")" 2>/dev/null && pwd) || {
+    printf '%s\n' "coconet: could not resolve the npm launcher directory" >&2
+    exit 1
+  }
+  link_target=$(readlink "$launcher") || {
+    printf '%s\n' "coconet: could not resolve the npm launcher link" >&2
+    exit 1
+  }
+  case $link_target in
+    /*) launcher=$link_target ;;
+    *) launcher=$launcher_directory/$link_target ;;
+  esac
+done
+
+launcher_directory=$(CDPATH= cd -P "$(dirname "$launcher")" 2>/dev/null && pwd) || {
+  printf '%s\n' "coconet: could not resolve the npm package directory" >&2
+  exit 1
+}
+package_root=$(dirname "$launcher_directory")
+package_json=$package_root/package.json
+setup_command=$package_root/cli.mjs
+
+if [ ! -f "$package_json" ] || [ ! -x "$setup_command" ]; then
+  printf '%s\n' "coconet: the npm installation is incomplete; reinstall the global coconet package" >&2
+  exit 1
+fi
+
+package_version=$(LC_ALL=C sed -n 's/^[[:space:]]*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$package_json" | LC_ALL=C sed -n '1p')
+if [ -z "$package_version" ]; then
+  printf '%s\n' "coconet: could not read the npm package version" >&2
+  exit 1
+fi
+
+if [ -n "${XDG_DATA_HOME:-}" ]; then
+  data_root=$XDG_DATA_HOME
+elif [ -n "${HOME:-}" ]; then
+  data_root=$HOME/.local/share
+else
+  printf '%s\n' "coconet: HOME or XDG_DATA_HOME is required" >&2
+  exit 1
+fi
+
+install_root=$data_root/coconet
+runtime=$install_root/current/bin/coconet
+runtime_manifest=$install_root/current/manifest.json
+
+runtime_version() {
+  if [ ! -f "$runtime_manifest" ]; then
+    return 1
+  fi
+  LC_ALL=C sed -n 's/^[[:space:]]*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$runtime_manifest" | LC_ALL=C sed -n '1p'
+}
+
+installed_version=$(runtime_version 2>/dev/null || true)
+if [ -x "$runtime" ] && [ "$installed_version" = "$package_version" ]; then
+  exec "$runtime" "$@"
+fi
+
+if [ -n "$installed_version" ]; then
+  printf 'Coconet Runtime %s does not match npm package %s; starting setup.\n' "$installed_version" "$package_version"
+else
+  printf 'Coconet Runtime %s is not installed; starting setup.\n' "$package_version"
+fi
+
+"$setup_command"
+setup_status=$?
+if [ "$setup_status" -ne 0 ]; then
+  exit "$setup_status"
+fi
+
+installed_version=$(runtime_version 2>/dev/null || true)
+if [ ! -x "$runtime" ] || [ "$installed_version" != "$package_version" ]; then
+  printf '%s\n' "coconet: setup finished without activating the expected Runtime" >&2
+  exit 1
+fi
+
+exec "$runtime" "$@"

package/cli.mjs

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+
+import { createReadStream, createWriteStream } from "node:fs";
+import { chmod, lstat, mkdir, mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { spawn } from "node:child_process";
+import * as tar from "tar";
+
+import {
+  bundleName,
+  isSafeArchiveEntry,
+  parseChecksum,
+  parseInstallOptions,
+  releaseBaseURL,
+  releaseChecksum,
+  resolveTarget,
+  verifySHA256,
+} from "./core.mjs";
+
+const packageMetadata = JSON.parse(await readFile(new URL("./package.json", import.meta.url), "utf8"));
+const packageVersion = packageMetadata.version;
+const releaseManifest = JSON.parse(
+  await readFile(new URL("./release-manifest.json", import.meta.url), "utf8"),
+);
+const maximumArchiveBytes = 512 * 1024 * 1024;
+
+async function main() {
+  const arguments_ = process.argv.slice(2);
+  if (arguments_.length === 1 && ["version", "--version", "-v"].includes(arguments_[0])) {
+    process.stdout.write(`coconet ${packageVersion}\n`);
+    return 0;
+  }
+  let options;
+  try {
+    options = parseInstallOptions(arguments_, packageVersion);
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    printUsage();
+    return 2;
+  }
+  if (options.help) {
+    printUsage(process.stdout);
+    return 0;
+  }
+
+  const target = resolveTarget();
+  const rootName = bundleName(options.release, target);
+  const archiveName = `${rootName}.tar.gz`;
+  const temporaryRoot = await mkdtemp(join(tmpdir(), "coconet-installer-"));
+  try {
+    const archivePath = join(temporaryRoot, archiveName);
+    let expected;
+    if (options.artifact) {
+      const checksumPath = join(temporaryRoot, `${archiveName}.sha256`);
+      await copyVerifiedInput(resolve(options.artifact), archivePath, maximumArchiveBytes);
+      await copyVerifiedInput(resolve(options.checksum), checksumPath, 16 * 1024);
+      expected = parseChecksum(await readFile(checksumPath, "utf8"), archiveName);
+    } else {
+      expected = releaseChecksum(releaseManifest, options.release, target);
+      const baseURL = options.baseURL || releaseBaseURL(releaseManifest, options.release);
+      await downloadFile(new URL(archiveName, baseURL), archivePath, maximumArchiveBytes);
+    }
+    await verifySHA256(archivePath, expected);
+
+    const extractedRoot = join(temporaryRoot, "extracted");
+    await mkdir(extractedRoot, { mode: 0o700 });
+    const archiveModes = [];
+    await tar.x({
+      file: archivePath,
+      cwd: extractedRoot,
+      strict: true,
+      preservePaths: false,
+      chmod: true,
+      processUmask: 0,
+      umask: 0,
+      filter(path, entry) {
+        if (!isSafeArchiveEntry(path, entry.type, rootName)) {
+          throw new Error(`Coconet archive contains unsafe entry ${path}`);
+        }
+        archiveModes.push(validatedArchiveMode(path, entry.type, entry.mode, rootName));
+        return true;
+      },
+    });
+    await restoreArchiveModes(extractedRoot, archiveModes);
+    const bundleRoot = join(extractedRoot, rootName);
+    await requireRegularFile(join(bundleRoot, "manifest.json"));
+    const bootstrap = join(bundleRoot, "bin", "coconet-bootstrap");
+    await requireRegularFile(bootstrap);
+    return await runBootstrap(bootstrap, [
+      ...options.bootstrapArguments,
+      "--bundle",
+      bundleRoot,
+    ]);
+  } finally {
+    await rm(temporaryRoot, { recursive: true, force: true });
+  }
+}
+
+function validatedArchiveMode(path, type, value, rootName) {
+  const normalizedPath = path.endsWith("/") ? path.slice(0, -1) : path;
+  const mode = Number(value);
+  const accepted = Number.isInteger(mode) && mode >= 0 && mode <= 0o777
+    && (type === "File"
+    ? mode === 0o644 || mode === 0o755
+    : mode === (normalizedPath === rootName ? 0o700 : 0o755));
+  if (!accepted) {
+    throw new Error(`Coconet archive contains unsafe mode for ${path}`);
+  }
+  return { path: normalizedPath, type, mode };
+}
+
+async function restoreArchiveModes(extractedRoot, entries) {
+  // File creation always applies the caller's process umask, even when tar's
+  // chmod option is enabled. The archive is hash-pinned and every mode above
+  // is allow-listed, so restore files first and directories deepest-first.
+  const ordered = [...entries].sort((left, right) => {
+    if (left.type !== right.type) return left.type === "File" ? -1 : 1;
+    return right.path.split("/").length - left.path.split("/").length;
+  });
+  for (const entry of ordered) {
+    await chmod(join(extractedRoot, entry.path), entry.mode);
+  }
+}
+
+async function copyVerifiedInput(source, destination, maximumBytes) {
+  const info = await lstat(source);
+  if (!info.isFile() || info.isSymbolicLink() || info.size > maximumBytes) {
+    throw new Error(`Coconet setup input is not an accepted regular file: ${basename(source)}`);
+  }
+  await pipeline(
+    createReadStream(source),
+    createSizeGuard(maximumBytes),
+    createWriteStream(destination, { mode: 0o600 }),
+  );
+}
+
+async function downloadFile(url, destination, maximumBytes) {
+  if (url.protocol !== "https:") {
+    throw new Error("remote Coconet releases require HTTPS");
+  }
+  const response = await fetch(url, { redirect: "follow", signal: AbortSignal.timeout(60_000) });
+  if (!response.ok || !response.body) {
+    throw new Error(`failed to download ${url.href}: HTTP ${response.status}`);
+  }
+  if (new URL(response.url).protocol !== "https:") {
+    throw new Error("Coconet release download redirected away from HTTPS");
+  }
+  await pipeline(
+    Readable.fromWeb(response.body),
+    createSizeGuard(maximumBytes),
+    createWriteStream(destination, { mode: 0o600 }),
+  );
+}
+
+function createSizeGuard(maximumBytes) {
+  let bytes = 0;
+  return new Transform({
+    transform(chunk, _encoding, callback) {
+      bytes += chunk.length;
+      if (bytes > maximumBytes) {
+        callback(new Error("Coconet setup download exceeds the allowed size"));
+        return;
+      }
+      callback(null, chunk);
+    },
+  });
+}
+
+async function requireRegularFile(path) {
+  const info = await lstat(path);
+  if (!info.isFile() || info.isSymbolicLink()) {
+    throw new Error("Coconet archive omitted a required regular file");
+  }
+}
+
+function runBootstrap(command, arguments_) {
+  return new Promise((resolveExit, reject) => {
+    const child = spawn(command, arguments_, { stdio: "inherit", env: process.env });
+    child.once("error", reject);
+    child.once("exit", (code, signal) => {
+      if (signal) {
+        reject(new Error(`coconet-bootstrap terminated by ${signal}`));
+        return;
+      }
+      resolveExit(code ?? 1);
+    });
+  });
+}
+
+function printUsage(output = process.stderr) {
+  output.write(
+    "usage: coconet-setup [install] [--release VERSION] [--base-url HTTPS_URL | --artifact FILE --checksum FILE] [--yes] [--json] [--root DIR] [--bin-dir DIR] [--codex-command CMD] [--claude-command CMD]\n",
+  );
+}
+
+try {
+  process.exitCode = await main();
+} catch (error) {
+  process.stderr.write(`${error.message}\n`);
+  process.exitCode = 1;
+}

package/core.mjs

@@ -0,0 +1,184 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { posix } from "node:path";
+
+const safeReleaseValue = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+export function resolveTarget(platform = process.platform, architecture = process.arch) {
+  const systems = { darwin: "darwin", linux: "linux" };
+  const architectures = { x64: "amd64", arm64: "arm64", amd64: "amd64" };
+  const targetOS = systems[platform];
+  const targetArchitecture = architectures[architecture];
+  if (!targetOS || !targetArchitecture) {
+    throw new Error(`Coconet does not support ${platform}/${architecture}`);
+  }
+  return { os: targetOS, architecture: targetArchitecture };
+}
+
+export function bundleName(version, target) {
+  if (
+    !safeReleaseValue.test(version) ||
+    !safeReleaseValue.test(target.os) ||
+    !safeReleaseValue.test(target.architecture)
+  ) {
+    throw new Error("bundle version or platform is invalid");
+  }
+  return `coconet-${version}-${target.os}-${target.architecture}`;
+}
+
+export function parseChecksum(content, archiveName) {
+  const lines = content
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .filter(Boolean);
+  if (lines.length !== 1) {
+    throw new Error("checksum file must contain exactly one entry");
+  }
+  const match = /^([0-9a-fA-F]{64})\s+\*?(.+)$/u.exec(lines[0]);
+  if (!match || match[2] !== archiveName) {
+    throw new Error("checksum file does not match the selected archive");
+  }
+  return match[1].toLowerCase();
+}
+
+export function releaseChecksum(manifest, version, target) {
+  if (
+    manifest?.schema_version !== 2 ||
+    manifest.version !== version ||
+    typeof manifest.archives !== "object" ||
+    manifest.archives === null ||
+    Array.isArray(manifest.archives)
+  ) {
+    throw new Error("bundled release checksum manifest is invalid or does not match the release");
+  }
+  const archiveName = `${bundleName(version, target)}.tar.gz`;
+  const checksum = manifest.archives[archiveName];
+  if (typeof checksum !== "string" || !/^[0-9a-f]{64}$/u.test(checksum)) {
+    throw new Error(`bundled release checksum is unavailable for ${archiveName}`);
+  }
+  return checksum;
+}
+
+export function releaseBaseURL(manifest, version) {
+  if (
+    manifest?.schema_version !== 2 ||
+    manifest.version !== version ||
+    !isGitHubRepository(manifest.repository) ||
+    manifest.release_tag !== `v${version}`
+  ) {
+    throw new Error("bundled release location is invalid or does not match the release");
+  }
+  return `https://github.com/${manifest.repository}/releases/download/${manifest.release_tag}/`;
+}
+
+function isGitHubRepository(value) {
+  if (typeof value !== "string") return false;
+  const parts = value.split("/");
+  return parts.length === 2 && parts.every((part) => (
+    part !== "." && part !== ".." &&
+    /^[A-Za-z0-9](?:[A-Za-z0-9_.-]{0,98}[A-Za-z0-9])?$/u.test(part)
+  ));
+}
+
+export async function verifySHA256(path, expected) {
+  const hash = createHash("sha256");
+  for await (const chunk of createReadStream(path)) {
+    hash.update(chunk);
+  }
+  const actual = hash.digest("hex");
+  if (actual !== expected.toLowerCase()) {
+    throw new Error("Coconet archive SHA-256 mismatch");
+  }
+  return actual;
+}
+
+export function isSafeArchiveEntry(path, type, expectedRoot) {
+  if (type !== "File" && type !== "Directory") {
+    return false;
+  }
+  if (!path || path.includes("\\") || path.includes("\0") || path.startsWith("/")) {
+    return false;
+  }
+  const normalized = path.endsWith("/") ? path.slice(0, -1) : path;
+  if (!normalized || posix.normalize(normalized) !== normalized) {
+    return false;
+  }
+  const parts = normalized.split("/");
+  if (parts.some((part) => part === "" || part === "." || part === "..")) {
+    return false;
+  }
+  return normalized === expectedRoot || normalized.startsWith(`${expectedRoot}/`);
+}
+
+export function parseInstallOptions(arguments_, packageVersion) {
+  const options = {
+    release: packageVersion,
+    baseURL: "",
+    artifact: "",
+    checksum: "",
+    bootstrapArguments: ["install"],
+    help: false,
+  };
+  const args = [...arguments_];
+  if (args[0] === "install") {
+    args.shift();
+  }
+  const values = new Map([
+    ["--release", "release"],
+    ["--base-url", "baseURL"],
+    ["--artifact", "artifact"],
+    ["--checksum", "checksum"],
+  ]);
+  const forwardedValues = new Set([
+    "--root",
+    "--bin-dir",
+    "--codex-command",
+    "--claude-command",
+  ]);
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (argument === "--help" || argument === "-h") {
+      options.help = true;
+      continue;
+    }
+    if (argument === "--yes" || argument === "--json") {
+      options.bootstrapArguments.push(argument);
+      continue;
+    }
+    const value = args[index + 1];
+    if (!value || value.startsWith("--")) {
+      throw new Error(`missing value for ${argument}`);
+    }
+    if (values.has(argument)) {
+      options[values.get(argument)] = value;
+      index += 1;
+      continue;
+    }
+    if (forwardedValues.has(argument)) {
+      options.bootstrapArguments.push(argument, value);
+      index += 1;
+      continue;
+    }
+    throw new Error(`unknown setup argument ${argument}`);
+  }
+  if (!safeReleaseValue.test(options.release)) {
+    throw new Error("release version is invalid");
+  }
+  if (Boolean(options.artifact) !== Boolean(options.checksum)) {
+    throw new Error("--artifact and --checksum must be provided together");
+  }
+  if (!options.artifact && options.baseURL) {
+    const baseURL = new URL(options.baseURL);
+    if (baseURL.protocol !== "https:") {
+      throw new Error("remote Coconet releases require HTTPS");
+    }
+    options.baseURL = baseURL.href.endsWith("/") ? baseURL.href : `${baseURL.href}/`;
+  }
+  if (options.bootstrapArguments.includes("--json") && !options.bootstrapArguments.includes("--yes")) {
+    throw new Error("--json requires --yes");
+  }
+  if (options.release === packageVersion) {
+    options.bootstrapArguments.splice(1, 0, "--no-bin-link");
+  }
+  return options;
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "coconet",
+  "version": "0.4.0",
+  "description": "Install the verified Coconet runtime and Agent plugins for the current user.",
+  "type": "module",
+  "bin": {
+    "coconet": "./bin/coconet",
+    "coconet-setup": "./cli.mjs"
+  },
+  "files": [
+    "README.md",
+    "bin/coconet",
+    "cli.mjs",
+    "core.mjs",
+    "release-manifest.json"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test core.test.mjs cli.test.mjs"
+  },
+  "dependencies": {
+    "tar": "7.5.22"
+  },
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xfey/coconet.git"
+  },
+  "homepage": "https://github.com/xfey/coconet#readme",
+  "bugs": {
+    "url": "https://github.com/xfey/coconet/issues"
+  }
+}

package/release-manifest.json

@@ -0,0 +1,12 @@
+{
+  "schema_version": 2,
+  "version": "0.4.0",
+  "repository": "xfey/coconet",
+  "release_tag": "v0.4.0",
+  "archives": {
+    "coconet-0.4.0-darwin-amd64.tar.gz": "692f37097b6ee7e84d60a1f68f5ccbace1a2c0fcb557be1d91b3418b02a16737",
+    "coconet-0.4.0-darwin-arm64.tar.gz": "3dfca82538a89b9cd84be60e79305fa630208333c8f545882f3ee02d6e8ea548",
+    "coconet-0.4.0-linux-amd64.tar.gz": "bb157a2804fdedc13174b6726002f3c7301c4d1ac16550e9d64b74de08897640",
+    "coconet-0.4.0-linux-arm64.tar.gz": "d629c9e15b82456bfc2d0a7774f4ed3d07b6c3236708afa1edaca14b873d00f2"
+  }
+}