@heyinkeji/cli 0.2.0

package/README.md

@@ -0,0 +1,45 @@
+# @heyinkeji/cli
+
+合因 Go CLI 的 npm 安装器。发布到 npmjs 后，用户可执行：
+
+```sh
+npm install -g @heyinkeji/cli
+heyincli version
+heyincli --help
+```
+
+需要 Node.js 22 或更高版本。支持 Windows、macOS、Linux 的 amd64（Node.js 中叫 x64）和 arm64。Windows 的 npm 命令入口为 `heyincli.cmd`，在普通终端中可直接执行 `heyincli`。
+
+安装时通过 HTTPS 下载与 npm 包版本相同的 Go 二进制，例如：
+
+```text
+https://heyin-public.oss-cn-beijing.aliyuncs.com/heyin-golang-cli/v0.2.0/darwin-arm64/heyincli
+```
+
+下载域名在 `package.json` 的 `heyin.downloadBaseUrl` 配置。二进制保存在已安装包的 `vendor/` 中，Windows 保存为 `heyincli.exe`，macOS/Linux 设置执行权限。Node 入口透传参数、标准输入输出、环境变量、工作目录及退出码，不需要用户安装 Go。安装过程需要访问该 OSS 地址，失败会返回非零状态；禁用安装脚本会导致二进制未安装，需开启安装脚本后重新安装。
+
+## 开发与验证
+
+在 `installer/` 中运行：
+
+```sh
+npm ci
+npm test
+npm audit
+npm pack
+```
+
+源码目录的依赖安装不会下载二进制；`npm test` 编译 TypeScript 并执行本地 HTTPS 服务与进程测试（测试证书通过 OpenSSL 生成）。`npm pack` 会检查 npm 版本与 `../cmd/root.go` 的 `Version` 一致，再编译。产物仅包含 JavaScript 安装器、命令入口、说明和包配置，不携带六个平台的二进制或开发依赖。
+
+## 发布
+
+1. 同步 `package.json`、`package-lock.json` 的 npm 版本和 `cmd/root.go` 中的 CLI 版本；例如修改 Go 版本后运行 `npm version 0.2.0 --no-git-tag-version`。
+2. 在 GitLab **Settings → CI/CD → Variables** 配置 `NPM_TOKEN`，环境范围为 `npm-release`，启用 Masked/Hidden。生产令牌启用 Protected，并在受保护分支或标签运行流水线。
+3. 测试、版本检查和六个平台构建通过后，手动运行 `publish_oss`。
+4. OSS 发布成功后，`publish_npm` 自动执行 `npm ci`、`npm test` 和 `npm publish --access public`。发布钩子会校验版本并编译安装器。
+
+使用具备 `@heyinkeji/cli` 发布权限的 npmjs granular access token；首次发布时需有在 `@heyinkeji` scope 创建包的权限。非交互发布需允许 Bypass 2FA，参考 [npm CI/CD 认证说明](https://docs.npmjs.com/using-private-packages-in-a-ci-cd-workflow/)。认证配置仅写入临时文件，退出时清理，不放入 npm 包。
+
+npm 发布失败时重试同一流水线的 `publish_npm`，无需重新上传 OSS；新流水线会被已存在的 OSS 发布标记阻止。npm 不允许覆盖已发布的同名同版本包，若该版本已成功发布，应先核对 npmjs 状态。也可在本地登录 npmjs 后执行 `npm publish --access public`。
+
+安装器采用与 [xparse-cli](https://www.npmjs.com/package/xparse-cli) 和 [@wecom/cli](https://www.npmjs.com/package/@wecom/cli) 类似的 Node 命令入口；平台产物由本项目已有的 OSS 分发。安装钩子与打包钩子遵循 [npm 生命周期](https://docs.npmjs.com/cli/v11/using-npm/scripts/)。

package/dist/cli.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { constants } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { resolveTarget } from './platform.js';
+try {
+    const target = resolveTarget(process.platform, process.arch);
+    const binary = fileURLToPath(new URL(`../vendor/${target.binaryName}`, import.meta.url));
+    const result = spawnSync(binary, process.argv.slice(2), { stdio: 'inherit', windowsHide: false });
+    if (result.error)
+        throw new Error(`无法启动 heyincli，请重新安装：npm install -g @heyinkeji/cli。${result.error.message}`);
+    process.exitCode = result.status ?? (result.signal ? 128 + constants.signals[result.signal] : 1);
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+}

package/dist/download.js

@@ -0,0 +1,44 @@
+import { get } from 'node:https';
+import { createWriteStream } from 'node:fs';
+import { chmod, mkdir, mkdtemp, rename, rm, stat } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+async function response(url, options, signal, redirects = 0) {
+    if (url.protocol !== 'https:' || url.username || url.password)
+        throw new Error('下载和重定向仅允许无凭据的 HTTPS 地址。');
+    const res = await new Promise((resolve, reject) => {
+        const req = (options.request ?? get)(url, { signal }, resolve);
+        req.on('error', reject);
+    });
+    if ([301, 302, 303, 307, 308].includes(res.statusCode ?? 0)) {
+        res.destroy();
+        if (!res.headers.location || redirects >= 5)
+            throw new Error('下载重定向无效或次数过多。');
+        return response(new URL(res.headers.location, url), options, signal, redirects + 1);
+    }
+    if (res.statusCode !== 200) {
+        res.destroy();
+        throw new Error(`下载失败：HTTP ${res.statusCode}，请确认对应 CLI 版本已发布。`);
+    }
+    return res;
+}
+export async function downloadBinary(url, destination, options = {}) {
+    await mkdir(dirname(destination), { recursive: true });
+    const temporary = await mkdtemp(join(dirname(destination), '.download-'));
+    const partial = join(temporary, 'heyincli');
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? 120_000);
+    try {
+        const res = await response(url, options, controller.signal);
+        await pipeline(res, createWriteStream(partial, { flags: 'wx', mode: 0o700 }), { signal: controller.signal });
+        if ((await stat(partial)).size === 0)
+            throw new Error('下载内容为空。');
+        await chmod(partial, 0o755);
+        await rename(partial, destination);
+    }
+    finally {
+        controller.abort();
+        clearTimeout(timer);
+        await rm(temporary, { recursive: true, force: true });
+    }
+}

package/dist/install.js

@@ -0,0 +1,16 @@
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { resolveTarget, downloadUrl } from './platform.js';
+import { downloadBinary } from './download.js';
+try {
+    const { version, heyin } = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+    const target = resolveTarget(process.platform, process.arch);
+    const url = downloadUrl(heyin.downloadBaseUrl, version, target);
+    const destination = fileURLToPath(new URL(`../vendor/${target.binaryName}`, import.meta.url));
+    console.error(`正在安装 heyincli ${version} (${target.directory})…`);
+    await downloadBinary(url, destination);
+}
+catch (error) {
+    console.error(`heyincli 安装失败：${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+}

package/dist/platform.js

@@ -0,0 +1,17 @@
+export function resolveTarget(platform, arch) {
+    const system = { win32: 'windows', darwin: 'darwin', linux: 'linux' }[platform];
+    const cpu = { x64: 'amd64', arm64: 'arm64' }[arch];
+    if (!system || !cpu)
+        throw new Error(`不支持的平台：${platform}-${arch}，仅支持 Windows/macOS/Linux 的 x64、arm64。`);
+    return { directory: `${system}-${cpu}`, binaryName: platform === 'win32' ? 'heyincli.exe' : 'heyincli' };
+}
+export function downloadUrl(baseUrl, version, target) {
+    const url = new URL(baseUrl);
+    if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash) {
+        throw new Error('下载地址必须是无凭据、查询参数和片段的 HTTPS 地址。');
+    }
+    if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version))
+        throw new Error('CLI 版本格式无效。');
+    url.pathname = `${url.pathname.replace(/\/$/, '')}/heyin-golang-cli/v${version}/${target.directory}/heyincli`;
+    return url;
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@heyinkeji/cli",
+  "version": "0.2.0",
+  "description": "合因平台命令行工具 heyincli 的安装器",
+  "type": "module",
+  "bin": {
+    "heyincli": "dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "scripts/postinstall.mjs"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "postinstall": "node scripts/postinstall.mjs",
+    "prepack": "node scripts/check-release.mjs && npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.1",
+    "typescript": "7.0.2"
+  },
+  "heyin": {
+    "downloadBaseUrl": "https://heyin-public.oss-cn-beijing.aliyuncs.com"
+  }
+}

package/scripts/postinstall.mjs

@@ -0,0 +1,6 @@
+import { existsSync } from 'node:fs';
+
+// 源码检出先安装开发依赖，再编译；npm 包内始终包含编译后的入口。
+if (!existsSync(new URL('../src/install.ts', import.meta.url))) {
+  await import('../dist/install.js');
+}