@ai-12345678/reservoir-sampling-cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,130 @@
-# Temporary Holding Version
+# reservoir
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+基于 Go 的流式蓄水池抽样命令行工具。使用 Algorithm R，按输入行的位置等概率、无放回抽样；使用 `crypto/rand.Int` 生成无模偏差的随机下标。
+
+npm 包名为 **`@ai-12345678/reservoir-sampling-cli`**（公开 scope 包），安装后的命令名为 **`reservoir`**。
+
+## 安装与使用
+
+发布到 npm 后安装：
+
+```bash
+npm install -g @ai-12345678/reservoir-sampling-cli
+reservoir -n 100 < input.txt > sample.txt
+reservoir --version
+```
+
+临时运行：
+
+```bash
+npx --yes --package @ai-12345678/reservoir-sampling-cli reservoir -n 100 < input.txt
+```
+
+首次 npm 授权尚未完成时，可以从本仓库 [Releases](https://github.com/ai-12345678/reservoir/releases) 下载 `reservoir-sampling-cli-0.1.0.tgz`，直接安装：
+
+```bash
+npm install -g --ignore-scripts ./reservoir-sampling-cli-0.1.0.tgz
+reservoir -n 100 < input.txt
+```
+
+也可以下载对应平台的原生 `.tar.gz`，解压后直接执行 `./reservoir -n 100 < input.txt`；原生方式不需要 Node.js。
+
+| 平台 | npm 内部目录 | GitHub Release 原生文件 |
+| --- | --- | --- |
+| Linux AMD64 | `vendor/linux-x64/` | `reservoir_<版本>_linux_amd64.tar.gz` |
+| macOS Apple Silicon | `vendor/darwin-arm64/` | `reservoir_<版本>_darwin_arm64.tar.gz` |
+| macOS Intel | `vendor/darwin-x64/` | `reservoir_<版本>_darwin_amd64.tar.gz` |
+
+npm 启动器需要 Node.js 22.14 或更高版本，根据当前 Node.js 进程的平台/架构选择二进制。当前发布工具链固定为 Go 1.27.3；macOS 原生二进制要求 macOS 13 或更新系统。Linux ARM64、Windows 暂不支持。
+
+## 输入输出约定
+
+- 输入从 stdin 读取，`-n` 默认是 1，且必须为正整数。
+- 输入不足 n 行时，输出所有输入行；空输入成功退出且不输出内容。
+- 空行参与抽样；重复文本代表不同记录，结果不做去重。
+- CRLF/LF 被解析为行分隔，输出统一使用 LF；最后一行没有换行符也会参与抽样。
+- 输出为蓄水池槽位顺序，不保证保持原始顺序或均匀洗牌。
+- 扫描缓冲上限是 10 MiB，包含换行等开销；超长行报错退出，不输出残缺抽样结果。
+- 字符串仅在实际入池时复制；内存随保留样本总字节数增长，不缓存整个输入。
+- stdout 只写样本或显式请求的版本；诊断写 stderr。退出码：0 成功、1 读取/随机源/输出失败、2 参数错误。
+
+## 本地开发
+
+需要 Go 1.27.3、Node.js 22.14+，无第三方运行时依赖。
+
+```bash
+go test ./...
+go vet ./...
+npm run build
+npm test
+node bin/reservoir.cjs -n 2 < input.txt
+```
+
+构建和验证完整发行包：
+
+```bash
+npm run build:all
+npm run pack:verify
+node scripts/smoke-package.mjs
+npm run release:assets
+```
+
+`build:all` 关闭 cgo，生成三种平台的二进制并写入包版本、Git 提交信息。`pack:verify` 检查二进制格式、平台、可执行权限及 npm 文件清单。安装时不运行下载或编译脚本；`--ignore-scripts` 可正常使用。
+
+## GitHub Actions 与 Release
+
+- `ci.yml`：PR 和手动触发，执行 Go 测试、CLI 集成测试及三个原生运行环境的 npm 安装测试。
+- `release.yml`：推送 `main`、推送 `v*` 标签或手动触发，执行同一套构建验证。
+- `build.yml`：复用的构建工作流。Linux 上交叉编译三份二进制，打包同一个 npm tarball，然后在 Linux x64、macOS arm64、macOS x64 上安装并执行它。
+- 新版本在测试全部通过后创建 GitHub Release，并上传三份原生压缩包、npm tarball 和 `SHA256SUMS`。
+- `main` 中的 `package.json.version` 出现新版本时，工作流会为测试过的提交创建对应的 `v<版本>` 标签。已有 Release 及资产不会被覆盖。
+- 同一版本的所有平台使用同一个源码提交。推送标签时，标签与 `package.json.version` 必须一致；当前工作流只发布稳定的 `x.y.z` 版本。
+
+日常发版：修改代码、增加 `package.json.version`（并同步 `package-lock.json`），提交到 `main` 即可；也可使用 `npm version patch` 后推送提交和标签。
+
+仓库目前是私有仓库，Releases 访问遵循 GitHub 仓库权限。npm 公开包的可见性独立于源码仓库可见性；工作流不修改仓库可见性。
+
+## npm 首次授权及自动发布
+
+GitHub 账号不会自动拥有 npm 权限。完成以下一次性初始化后，后续版本可以全自动发布到 npm 公共 registry。
+
+### 1. 首次发布
+
+先注册/登录 npm 账号、验证邮箱并完成 npm 要求的双因素认证。从通过测试的 GitHub Release 下载 npm tarball，然后执行：
+
+```bash
+npm login --registry=https://registry.npmjs.org/
+npm publish ./reservoir-sampling-cli-0.1.0.tgz --access public --registry=https://registry.npmjs.org/
+```
+
+包名 `reservoir-sampling-cli` 必须可用，或当前 npm 账号已经拥有该包的发布权限。如果首次发布时名称被占用，请修改 `package.json.name`、锁文件及本文安装命令，并发布新版本。
+
+### 2. 设置 npm Trusted Publisher
+
+进入 npm 的 `reservoir-sampling-cli` 包设置，在 Trusted Publishing 中添加 GitHub Actions：
+
+| 设置 | 值 |
+| --- | --- |
+| Organization or user | `ai-12345678` |
+| Repository | `reservoir` |
+| Workflow filename | `release.yml`（不含目录） |
+| Environment | 留空 |
+| Allowed actions | 允许直接执行 `npm publish` |
+
+`package.json.repository.url` 已配置为本 GitHub 仓库。发布使用 GitHub 托管 runner、Node.js 24、npm 11.21.0 和 `id-token: write`，无需配置 `NPM_TOKEN`。私有源码仓库的发布不会生成 npm provenance。
+
+### 3. 启用自动发布
+
+在 GitHub 仓库 **Settings → Secrets and variables → Actions → Variables** 中添加：
+
+```text
+NPM_PUBLISH_ENABLED=true
+```
+
+下一次发布新版本时，`release.yml` 会在 GitHub Release 完成后，校验并直接发布同一份 npm tarball。npm 授权尚未就绪时，这个步骤保持跳过，GitHub Release 构建和下载不受影响。
+
+新建 Trusted Publisher 需要在 48 小时内成功发布一次完成验证。初始化时可先手动发布 `0.1.0`，配置 Trusted Publisher 后立即将版本增加为 `0.1.1` 并推送到 main，验证自动发布。若配置过期，需要在 npm 端重新创建。
+
+如果某版本的 GitHub Release 已成功、npm 发布失败，修复账号设置后，可以手动运行 `release.yml`，填写已有标签重试；它会下载该 Release 原有的 npm tarball，不会覆盖原资产。已经发布成功的同名 npm 版本不能覆盖，请增加版本号。
+
+参考：[npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers/)。

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,35 @@
+# Third-party notices
+
+The native executables include the Go runtime and standard library.
+Their license is reproduced below. This notice does not change the license
+of the reservoir project itself.
+
+## Go
+
+Copyright 2009 The Go Authors.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+   * Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+   * Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the
+distribution.
+   * Neither the name of Google LLC nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/bin/reservoir.cjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+"use strict";
+require("../lib/cli.cjs").main();

package/lib/cli.cjs

@@ -0,0 +1,47 @@
+"use strict";
+
+const { accessSync, constants } = require("node:fs");
+const { spawn } = require("node:child_process");
+const { constants: osConstants } = require("node:os");
+const { binaryPath } = require("./platforms.cjs");
+
+function main(args = process.argv.slice(2)) {
+  let executable;
+  try {
+    executable = binaryPath();
+    accessSync(executable, constants.X_OK);
+  } catch (error) {
+    console.error(`reservoir: ${error.message}`);
+    console.error("Reinstall the npm package, or run npm run build in a source checkout.");
+    process.exitCode = 1;
+    return;
+  }
+
+  const child = spawn(executable, args, { stdio: "inherit", shell: false });
+  const handlers = new Map();
+  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+    const handler = () => child.kill(signal);
+    handlers.set(signal, handler);
+    process.on(signal, handler);
+  }
+  let failed = false;
+  child.once("error", (error) => {
+    failed = true;
+    console.error(`reservoir: cannot run native executable: ${error.message}`);
+  });
+  child.once("close", (code, signal) => {
+    for (const [name, handler] of handlers) process.removeListener(name, handler);
+    if (failed) {
+      process.exitCode = 1;
+    } else if (signal) {
+      // Preserve signal termination. SIGPIPE is ignored by Node by default,
+      // so also set the conventional exit code as a fallback.
+      process.exitCode = 128 + (osConstants.signals[signal] || 1);
+      process.kill(process.pid, signal);
+    } else {
+      process.exitCode = code ?? 1;
+    }
+  });
+}
+
+module.exports = { main };

package/lib/platforms.cjs

@@ -0,0 +1,19 @@
+"use strict";
+
+const path = require("node:path");
+
+const targets = Object.freeze({
+  "linux-x64": { goos: "linux", goarch: "amd64", machine: 62 },
+  "darwin-arm64": { goos: "darwin", goarch: "arm64", machine: 0x0100000c },
+  "darwin-x64": { goos: "darwin", goarch: "amd64", machine: 0x01000007 },
+});
+
+function binaryPath(platform = process.platform, arch = process.arch) {
+  const key = `${platform}-${arch}`;
+  if (!Object.hasOwn(targets, key)) {
+    throw new Error(`unsupported platform ${key}; supported: ${Object.keys(targets).join(", ")}`);
+  }
+  return path.join(__dirname, "..", "vendor", key, "reservoir");
+}
+
+module.exports = { targets, binaryPath };

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@ai-12345678/reservoir-sampling-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Streaming reservoir sampling CLI powered by a native Go executable",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ai-12345678/reservoir.git"
+  },
+  "bin": {
+    "reservoir": "bin/reservoir.cjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "vendor/",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "engines": {
+    "node": ">=22.14.0"
+  },
+  "os": [
+    "linux",
+    "darwin"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "build:all": "node scripts/build.mjs --all",
+    "test": "node --test test/*.test.cjs",
+    "pack:verify": "node scripts/verify-package.mjs",
+    "release:assets": "node scripts/release-assets.mjs",
+    "prepack": "node scripts/check-binaries.mjs"
+  },
+  "keywords": [
+    "reservoir",
+    "sampling",
+    "cli",
+    "stream"
+  ]
+}