specrune 0.0.0-stage → 0.8.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jsfaint
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,49 @@
-# Temporary Holding Version
+# specrune
 
-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.
+SpecRune 的 npm 安装入口：一个很小的 Node 启动器，按平台拉起对应的原生 Go 二进制。
+
+```bash
+npm i -g specrune
+specrune version
+```
+
+真正的二进制放在 6 个平台包（`specrune-linux-x64`、`specrune-darwin-arm64`、`specrune-windows-x64` …）里，
+由本包的 `optionalDependencies` 精确锁定版本。npm 只安装与当前平台匹配的那一个，所以安装体积就是一个
+二进制的体积。
+
+## 运行要求
+
+- **Node.js >= 18**。
+- **只支持全局安装**（`npm i -g specrune`）。项目内安装与 `npx specrune init` 都不受支持：npx 把包装进临时 `_npx` 目录，命令退出后即被清掉，`init` 装配的宿主钩子会指向不存在的路径（`init` 在该目录下会拒绝并提示先全局安装）。
+
+## 升级
+
+二进制归 npm 管理，`specrune upgrade` 会拒绝自更新（`--check` 同样拒绝）。升级用：
+
+```bash
+npm i -g specrune@latest
+```
+
+## 可选依赖被跳过时
+
+启动器找不到平台包会直接退出并说明原因。常见情形：
+
+- `npm i -g specrune --omit=optional`
+- `npm i -g specrune --ignore-optional`
+- pnpm 的 `--no-optional` 或镜像跳过了可选依赖
+
+处置：`npm i -g specrune@latest` 重装。若该平台没有预编译包，改用
+[Releases](https://github.com/jsfaint/SpecRune/releases) 里的独立二进制。
+
+## 安装渠道
+
+启动器给子进程注入 `SPECRUNE_LAUNCHER=npm`，SpecRune 据此识别自己由 npm 安装（这类安装不应走
+`specrune upgrade` 自更新）。
+
+npm 安装不执行任何 install/postinstall 脚本，也没有额外的网络下载。
+
+## 卸载
+
+```bash
+npm uninstall -g specrune
+```

package/bin/specrune.js

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

package/lib/launcher.js

@@ -0,0 +1,210 @@
+"use strict";
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { spawn } = require("node:child_process");
+
+// 唯一平台映射表：npm 打包（stage.mjs）与启动器共用，避免两处各自维护而漂移。
+// 键是 Node 的 `${process.platform}-${process.arch}`，goos/goarch 只给打包侧用。
+const TARGETS = {
+  "linux-x64": {
+    package: "specrune-linux-x64",
+    os: "linux",
+    cpu: "x64",
+    goos: "linux",
+    goarch: "amd64",
+    binary: "bin/specrune",
+  },
+  "linux-arm64": {
+    package: "specrune-linux-arm64",
+    os: "linux",
+    cpu: "arm64",
+    goos: "linux",
+    goarch: "arm64",
+    binary: "bin/specrune",
+  },
+  "darwin-x64": {
+    package: "specrune-darwin-x64",
+    os: "darwin",
+    cpu: "x64",
+    goos: "darwin",
+    goarch: "amd64",
+    binary: "bin/specrune",
+  },
+  "darwin-arm64": {
+    package: "specrune-darwin-arm64",
+    os: "darwin",
+    cpu: "arm64",
+    goos: "darwin",
+    goarch: "arm64",
+    binary: "bin/specrune",
+  },
+  // 包名用 windows 而不是 win32：npm 会把新包名里的 `win32` 判成垃圾名并回 403
+  // "Package name triggered spam detection"（同 git-cliff 等包的遭遇）。`os` 字段
+  // 反过来必须是 Node 的平台名 win32，两者不是一回事，别顺手统一。
+  "win32-x64": {
+    package: "specrune-windows-x64",
+    os: "win32",
+    cpu: "x64",
+    goos: "windows",
+    goarch: "amd64",
+    binary: "bin/specrune.exe",
+  },
+  "win32-arm64": {
+    package: "specrune-windows-arm64",
+    os: "win32",
+    cpu: "arm64",
+    goos: "windows",
+    goarch: "arm64",
+    binary: "bin/specrune.exe",
+  },
+};
+
+// 子进程退出时要原样复现的信号。stdio 已继承，前台终端里子进程本身也会收到这些信号；
+// 父进程转发是为了覆盖「信号只发给启动器」的场景（例如 CI 只 kill 最外层 PID）。
+const FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+
+function fail(message) {
+  process.stderr.write(`specrune: ${message}\n`);
+  process.exitCode = 1;
+}
+
+function supportedTargets() {
+  return Object.keys(TARGETS).join("、");
+}
+
+function resolveTarget(platform = process.platform, arch = process.arch) {
+  return TARGETS[`${platform}-${arch}`] ?? null;
+}
+
+function resolvePackageJson(packageName, fromDir) {
+  return require.resolve(`${packageName}/package.json`, { paths: [fromDir] });
+}
+
+function injectLauncherEnv(env) {
+  return { ...env, SPECRUNE_LAUNCHER: "npm" };
+}
+
+function describeMissingPackage(target, version) {
+  return [
+    `未找到当前平台的 npm 包 ${target.package}（${target.os}-${target.cpu}）。`,
+    "",
+    "可能原因与处置：",
+    `  1. 安装时省略了可选依赖（--omit=optional / --ignore-optional / pnpm 的 --no-optional）：`,
+    `     npm i -g specrune@${version}`,
+    "  2. 包管理器或镜像跳过了可选依赖：换回官方 registry 后重新安装",
+    "  3. 该平台暂无预编译包：从 https://github.com/jsfaint/SpecRune/releases 下载独立二进制",
+  ].join("\n");
+}
+
+function describeVersionMismatch(target, launcherVersion, packageVersion) {
+  return [
+    "平台包版本与启动器不一致。",
+    `  启动器 specrune：${launcherVersion}`,
+    `  平台包 ${target.package}：${packageVersion}`,
+    "",
+    "处置：npm i -g specrune@latest 重装；若仍不一致，删除全局 node_modules 下的 specrune-* 目录后重装。",
+  ].join("\n");
+}
+
+function ensureExecutable(binPath) {
+  if (process.platform === "win32") return;
+  try {
+    fs.chmodSync(binPath, 0o755);
+  } catch {
+    // best-effort：npm 的 bin 链接通常已经恢复执行位，失败就交给 spawn 的 EACCES 报错。
+  }
+}
+
+function reRaise(signal) {
+  for (const forwarded of FORWARDED_SIGNALS) process.removeAllListeners(forwarded);
+  const number = os.constants.signals[signal];
+  // Windows 没有信号投递：process.kill(self, sig) 不触发默认动作，而是以退出码 1 强杀自己，
+  // 下面的 128+n 永远轮不到。直接设退出码，否则「按信号退出」在 Windows 上退化成 1。
+  if (process.platform !== "win32") {
+    try {
+      process.kill(process.pid, signal);
+    } catch {
+      // 信号被忽略（例如 nohup）时同样落到 128+n。
+    }
+  }
+  process.exitCode = number ? 128 + number : 1;
+}
+
+function run(binPath, args) {
+  const child = spawn(binPath, args, {
+    stdio: "inherit",
+    env: injectLauncherEnv(process.env),
+  });
+
+  for (const signal of FORWARDED_SIGNALS) {
+    process.on(signal, () => {
+      try {
+        child.kill(signal);
+      } catch {
+        // 子进程已退出时 kill 会抛 ESRCH，忽略即可。
+      }
+    });
+  }
+
+  child.on("error", (error) => {
+    fail(
+      [
+        `无法执行 ${binPath}：${error.message}`,
+        "处置：npm i -g specrune@latest 重装。",
+      ].join("\n"),
+    );
+  });
+
+  child.on("exit", (code, signal) => {
+    for (const forwarded of FORWARDED_SIGNALS) {
+      process.removeAllListeners(forwarded);
+    }
+    if (signal) {
+      reRaise(signal);
+      return;
+    }
+    process.exitCode = code ?? 1;
+  });
+}
+
+function main(argv = process.argv.slice(2)) {
+  const target = resolveTarget();
+  if (!target) {
+    fail(
+      [
+        `不支持当前平台 ${process.platform}-${process.arch}。`,
+        `支持的平台：${supportedTargets()}`,
+        "独立二进制见 https://github.com/jsfaint/SpecRune/releases",
+      ].join("\n"),
+    );
+    return;
+  }
+
+  const { version: launcherVersion } = require("../package.json");
+  let packageJsonPath;
+  try {
+    packageJsonPath = resolvePackageJson(target.package, path.join(__dirname, ".."));
+  } catch (error) {
+    if (error && error.code === "MODULE_NOT_FOUND") {
+      fail(describeMissingPackage(target, launcherVersion));
+      return;
+    }
+    fail(`解析平台包 ${target.package} 失败：${error && error.message ? error.message : error}`);
+    return;
+  }
+
+  const packageRoot = path.dirname(packageJsonPath);
+  const { version: packageVersion } = require(packageJsonPath);
+  if (packageVersion !== launcherVersion) {
+    fail(describeVersionMismatch(target, launcherVersion, packageVersion));
+    return;
+  }
+
+  const binPath = path.join(packageRoot, target.binary);
+  ensureExecutable(binPath);
+  run(binPath, argv);
+}
+
+module.exports = { TARGETS, main, resolveTarget, supportedTargets };

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "specrune",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.8.1",
+  "description": "SpecRune 命令行：规格驱动的 AI 编码工作流引擎（单二进制 Go CLI 的 npm 启动器）",
+  "bin": {
+    "specrune": "bin/specrune.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jsfaint/SpecRune.git",
+    "directory": "npm/cli"
+  },
+  "homepage": "https://github.com/jsfaint/SpecRune#readme",
+  "bugs": {
+    "url": "https://github.com/jsfaint/SpecRune/issues"
+  },
+  "license": "MIT",
+  "keywords": [
+    "spec-driven",
+    "workflow",
+    "ai-agents",
+    "cli"
+  ],
+  "optionalDependencies": {
+    "specrune-linux-x64": "0.8.1",
+    "specrune-linux-arm64": "0.8.1",
+    "specrune-darwin-x64": "0.8.1",
+    "specrune-darwin-arm64": "0.8.1",
+    "specrune-windows-x64": "0.8.1",
+    "specrune-windows-arm64": "0.8.1"
+  }
+}