specrune-opencode 0.0.0-stage → 0.9.0

package/src/install.mjs

@@ -0,0 +1,214 @@
+// specrune-opencode 安装器 adapter。
+//
+// 通用编排（参数解析、CLI 定位、状态/哈希/原子写、scope 校验、互斥检测、
+// skills 调用、install/uninstall/status 流程）在 specrune/lib/installer-core.mjs；
+// 这里只保留 OpenCode 的落点、模板与互斥探针。
+//
+// 安装位置默认全局：OpenCode 会同时发现全局与项目级插件，同一个插件两处都在
+// 会重复挂 hook。项目级安装只作为例外与回退路径保留。
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// 发布后从 specrune 依赖导入；源码仓库未执行 npm install，回退到仓库内的父包。
+// 旧版 specrune 没有 lib/installer-core.mjs：两档都解析不到时给可操作错误，
+// 不让裸 ERR_MODULE_NOT_FOUND 堆栈直接抛给用户。
+async function loadInstallerCore() {
+  try {
+    return await import("specrune/lib/installer-core.mjs");
+  } catch (err) {
+    if (!err || err.code !== "ERR_MODULE_NOT_FOUND") throw err;
+    try {
+      return await import("../../../npm/cli/lib/installer-core.mjs");
+    } catch (fallbackErr) {
+      if (!fallbackErr || fallbackErr.code !== "ERR_MODULE_NOT_FOUND") throw fallbackErr;
+      throw new Error(
+        "无法加载共享安装核心 specrune/lib/installer-core.mjs：当前 specrune 版本不含 installer-core。" +
+          "请升级 specrune 后重试（npm i -g specrune@latest）；" +
+          "若 specrune 尚未安装，请重新安装本插件。" +
+          `\n原始错误: ${err.message}`,
+      );
+    }
+  }
+}
+
+const core = await loadInstallerCore();
+const {
+  createInstaller,
+  contentHash,
+  findProjectRoot,
+  resolveWithin,
+} = core;
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(HERE, "..");
+const PKG = JSON.parse(readFileSync(join(PKG_ROOT, "package.json"), "utf8"));
+
+// protocol 是后端钩子帧协议的版本，不是产品版本。插件只检查它，产品命令可以
+// 自由演进而不打断已装插件（.specrune/spec/backend/agent-plugin-contract.md）。
+const PROTOCOL = 1;
+
+// 插件声明编写时依赖的 installer-core API 版本。必须写字面量：从核心导入
+// 会让声明永远等于当前核心，旧插件在新核心上就无法被拦下。
+const REQUIRED_CORE_VERSION = 1;
+
+// plugin.ts 里的带引号占位符。带引号替换才能整体换成 JSON 字面量，同时借
+// JSON.stringify 处理 Windows 路径的反斜杠转义。
+const BUNDLED_PLACEHOLDER = '"__SPECRUNE_BUNDLED_BIN__"';
+
+// locateBundledBinary 以本模块为锚解析平台二进制：适配器自己的依赖树决定
+// 查找起点，不能换成共享核心的位置。
+export function locateBundledBinary() {
+  return core.locateBundledBinary({ anchor: import.meta.url });
+}
+
+export { contentHash };
+
+// injectBundledBinary 把插件源里的占位符换成解析到的绝对路径。未找到时注入
+// 空串：运行时把空串视为「未注入」，继续走 npm 平台包与 PATH 档。
+export function injectBundledBinary(source, binPath) {
+  return source.replace(BUNDLED_PLACEHOLDER, JSON.stringify(binPath || ""));
+}
+
+export const PLUGIN_REL = "plugins/specrune.ts";
+const AGENTS_REL = "agents";
+const COMMANDS_SRC = "commands";
+const COMMANDS_REL = "commands/specrune";
+const GLOBAL_STATE_FILE = "specrune-install.json";
+const PROJECT_STATE_REL = ".specrune/.state/plugins/opencode.json";
+
+const USAGE = `specrune-opencode — 把 SpecRune 的 OpenCode 插件装进宿主目录
+
+用法:
+  specrune-opencode install   [--scope global|project] [--dir <路径>] [--dry-run] [--force]
+  specrune-opencode uninstall [--scope global|project] [--dir <路径>] [--dry-run] [--force]
+  specrune-opencode status    [--scope global|project] [--dir <路径>] [--json]
+
+选项:
+  --scope global|project  安装范围，默认 global
+                          global 写 ~/.config/opencode/（--dir 可覆盖配置根，便于测试）
+                          project 写 <项目根>/.opencode/
+  --dir <路径>            global 下是配置根；project 下是项目根（默认当前目录）
+  --dry-run               只打印计划，不写盘、不改状态文件
+  --force                 install 覆盖已修改的目标文件，并在检测到另一 scope 的安装时继续；
+                          uninstall 连改过的文件一起删
+  --json                  status 以机器可读 JSON 输出
+  -h, --help              显示本帮助
+
+安装同时调用自带 CLI 的 'specrune skills install --adapter opencode --scope <scope>'；
+project 模式要求目标目录已有 .specrune/（先运行 specrune init）。技能安装失败只告警，
+插件安装仍然成功。
+
+退出码: 0 成功，1 运行失败，2 用法错误。
+`;
+
+// listMarkdown 读包内一个目录的 .md，返回安装后的 POSIX 相对路径与正文。
+// 排序让安装计划与状态文件稳定：每次 install 给出不同顺序会让「这次改了什么」
+// 没法用 diff 看。
+function listMarkdown(srcDir, targetDir) {
+  const abs = join(PKG_ROOT, srcDir);
+  return readdirSync(abs)
+    .filter((name) => name.endsWith(".md"))
+    .sort()
+    .map((name) => ({
+      rel: `${targetDir}/${name}`,
+      content: readFileSync(join(abs, name), "utf8"),
+    }));
+}
+
+// templateFiles 是本次安装要落盘的全部自有文件。插件本体在 src/ 下，代理与
+// 命令按宿主发现规则分目录；命令的文件名不加 specrune- 前缀，子目录名
+// `specrune/` 已经是命令组前缀。
+//
+// 插件内容按解析到的本机二进制注入后再返回：状态哈希也随即按注入后的内容计算，
+// 否则升级时会把「注入路径变了」误判成用户改动。
+export function templateFiles(bundledBinary = locateBundledBinary()) {
+  const pluginSource = readFileSync(join(PKG_ROOT, "src", "plugin.ts"), "utf8");
+  return [
+    { rel: PLUGIN_REL, content: injectBundledBinary(pluginSource, bundledBinary) },
+    ...listMarkdown(AGENTS_REL, "agents"),
+    ...listMarkdown(COMMANDS_SRC, COMMANDS_REL),
+  ];
+}
+
+function defaultGlobalRoot() {
+  return join(homedir(), ".config", "opencode");
+}
+
+export function resolveTargets(opts) {
+  if (opts.scope === "project") {
+    const projectRoot = resolve(opts.dir || process.cwd());
+    return {
+      scope: "project",
+      projectRoot,
+      root: join(projectRoot, ".opencode"),
+      statePath: join(projectRoot, ...PROJECT_STATE_REL.split("/")),
+    };
+  }
+  // global 的 --dir 覆盖配置根：测试与隔离安装都需要一个不碰真实家目录的出口。
+  const root = opts.dir ? resolve(opts.dir) : defaultGlobalRoot();
+  return {
+    scope: "global",
+    projectRoot: null,
+    root,
+    statePath: join(root, GLOBAL_STATE_FILE),
+  };
+}
+
+// installedAt 是互斥检测的探针：插件入口、agents、commands 都算安装痕迹。
+function installedAt(root) {
+  const found = [];
+  for (const file of templateFiles("")) {
+    try {
+      if (existsSync(resolveWithin(root, file.rel))) found.push(file.rel);
+    } catch {
+      /* 越界或坏根目录，跳过 */
+    }
+  }
+  return found;
+}
+
+function otherScopeTarget(targets) {
+  if (targets.scope === "project") {
+    return { scope: "global", root: defaultGlobalRoot() };
+  }
+  const projectRoot = findProjectRoot(process.cwd());
+  return { scope: "project", root: join(projectRoot, ".opencode") };
+}
+
+function detectOtherScope(targets) {
+  const other = otherScopeTarget(targets);
+  const found = installedAt(other.root);
+  return { ...other, found, installed: found.length > 0 };
+}
+
+// 与迁移前逐字一致：测试锁的是「拒绝 + 指出另一 scope + 提示 --force」。
+function otherScopeError(other) {
+  return (
+    `specrune-opencode: 检测到 ${other.scope} scope 已有 OpenCode 安装` +
+    `（${other.found.length} 个文件，位于 ${other.root}）；继续安装会重复加载 hook。` +
+    `请先卸载: specrune-opencode uninstall --scope ${other.scope}；` +
+    `确认要并存时加 --force。\n`
+  );
+}
+
+const adapter = {
+  name: "opencode",
+  displayName: "specrune-opencode",
+  command: "specrune-opencode",
+  packageName: "specrune-opencode",
+  version: PKG.version,
+  protocol: PROTOCOL,
+  coreVersion: REQUIRED_CORE_VERSION,
+  moduleUrl: import.meta.url,
+  usage: USAGE,
+  rootLabel: "配置根",
+  resolveTargets,
+  templateFiles,
+  detectOtherScope,
+  otherScopeError,
+};
+
+export const { install, uninstall, status, parse, main } = createInstaller(adapter);
+export { adapter };