@rosenfan/matrix 0.1.4 → 0.1.6

package/src/messages.js

@@ -1,37 +1,46 @@
-export const messages = {
-  en: {
-    title: "Evidence-driven workflow with Prim and Arch orchestration",
-    recommended: "Recommended setup", apply: "Apply", customize: "Customize", cancel: "Cancel",
+export const messages = {
+  en: {
+    title: "Evidence-driven workflow with Prim and Arch orchestration",
+    recommended: "Recommended setup", apply: "Apply", customize: "Customize", cancel: "Cancel",
     project: "Project (current directory)", global: "Global Matrix Skills",
-    copy: "Copy (recommended)", symlink: "Symlink (advanced)",
-    matrix: "Matrix", matt: "Matt Pocock skills", installed: "installed", ready: "Matrix is ready.",
-    noPlatform: "No verified platform was detected. Select Claude Code, Codex, or both.",
-    preview: "Planned changes", confirm: "Apply these changes?", doctor: "Installation diagnosis",
-    languageQuestion: "Language", scopeQuestion: "Installation scope", platformsQuestion: "Platforms", orchestrationQuestion: "Default orchestration",
+    copy: "Copy (recommended)", symlink: "Symlink (advanced)",
+    matrix: "Matrix", matt: "Matt Pocock skills", installed: "installed", ready: "Matrix is ready.",
+    noPlatform: "No verified platform was detected. Select Claude Code, Codex, or both.",
+    preview: "Planned changes", confirm: "Apply these changes?", doctor: "Installation diagnosis",
+    languageQuestion: "Language", scopeQuestion: "Installation scope", platformsQuestion: "Platforms", orchestrationQuestion: "Default orchestration",
+    orchestrationArchDetail: "Orchestrates the installed Matt Skills cohort (requires Matt Skills).", orchestrationPrimDetail: "Uses Matrix's own capabilities only (no Matt dependency).",
+    readyHint: "Type $matrix followed by your request in {platform} to start the evidence-driven workflow.",
     mattQuestion: "Install or reconcile the supported Matt Pocock release in this project?", replaceQuestion: "Existing Matrix files are not proven managed. Back up and replace?",
     mattReplaceQuestion: "Matt Skills contain local or unreadable content. Back them up and replace them with the supported release?",
+    mattRepairQuestion: "Matt Skills are {state}. Re-pull the supported release ({release}) now?",
+    updateScopeQuestion: "Update scope", updateScopeCurrent: "Current project only", updateScopeAll: "All indexed projects",
     yes: "Yes", no: "No", stateMissing: "missing", stateMatching: "up to date", stateComplete: "complete", stateUserModified: "user-modified", statePartial: "partial", stateOutdated: "outdated", stateSafeUpdate: "safe update", stateAdoptable: "adoptable", stateUnreadable: "unreadable", stateCompatible: "compatible", stateUpdateRequired: "update required", stateUnsupportedNewer: "unsupported newer", stateUnverified: "unverified", stateUnknown: "unknown",
-    actionInstall: "install", actionKeep: "keep", actionBackupReplace: "back up and replace", actionRepair: "repair", actionBlocked: "requires approval",
+    actionInstall: "install", actionKeep: "keep", actionBackupReplace: "back up and replace", actionRepair: "repair", actionBlocked: "requires approval",
     dryRunComplete: "Dry run complete.", defaultOrchestration: "Default orchestration", mattCompatibilityStatus: "Matt {release}: {status}",
     manifestMissing: "No Matrix installation manifest was found for this scope.", transactionPending: "An interrupted Matrix transaction is awaiting recovery. Run matrix init again before applying a new plan.", runtimeMissing: "Bundled Matrix runtime is missing.", brokenLink: "Broken Matrix link detected.", mattGlobalIgnored: "global Matt Skills are present but ignored by the project compatibility contract.", mattSetupHint: "Matt {release} is installed for this project. Optionally run $setup-matt-pocock-skills once to configure its user-owned integrations.",
     matrixModifiedDiagnostic: "{platform}: existing Matrix assets are not proven managed.", mattModifiedDiagnostic: "{platform}: Matt Skills contain local or unreadable content that requires separate replacement approval.", archIncompleteDiagnostic: "Arch requires the exact reviewed cohort and trusted project receipt. Retry with --with-mattpocock.", matrixStateDiagnostic: "{platform}: Matrix is {state}.", mattStateDiagnostic: "{platform}: Matt Pocock skills are {state}.", codexLegacyDiagnostic: "Codex legacy .codex/skills was detected; Matrix will not write there.", unmanagedExtraDiagnostic: "{platform}: unmanaged extra Skills are preserved and will not be invoked: {skills}."
-  },
-  "zh-CN": {
+  },
+  "zh-CN": {
     manifestMissing: "当前安装范围没有 Matrix 安装清单。", transactionPending: "发现中断的 Matrix 安装事务。请再次运行 matrix init 后再应用新计划。", runtimeMissing: "缺少随附的 Matrix runtime。", brokenLink: "检测到断开的 Matrix 链接。", mattGlobalIgnored: "检测到全局 Matt Skills，但项目兼容性契约不会采用它们。", mattSetupHint: "已为当前项目安装 Matt {release}。如需配置由用户拥有的集成，可显式运行一次 $setup-matt-pocock-skills。",
-    languageQuestion: "语言", scopeQuestion: "安装范围", platformsQuestion: "要配置的平台", orchestrationQuestion: "默认编排模式",
+    languageQuestion: "语言", scopeQuestion: "安装范围", platformsQuestion: "要配置的平台", orchestrationQuestion: "默认编排模式",
+    orchestrationArchDetail: "编排项目内已安装的 Matt Skills 集合（需先安装 Matt）。",
+    orchestrationPrimDetail: "仅使用 Matrix 自带能力，不依赖 Matt Skills。",
+    readyHint: "在 {platform} 中输入 `$matrix` 加你的请求，即可启动证据驱动工作流。",
     mattQuestion: "是否在当前项目安装或核对 Matrix 支持的 Matt Pocock Release？", replaceQuestion: "现有 Matrix 文件无法确认由 Matrix 管理。是否备份并替换？", mattReplaceQuestion: "Matt Skills 存在本地修改或不可读内容。是否先备份，再替换为受支持的 Release？",
+    mattRepairQuestion: "Matt Skills {state}。是否立即重新拉取受支持的 release（{release}）？",
+    updateScopeQuestion: "更新范围", updateScopeCurrent: "仅当前项目", updateScopeAll: "全部已索引项目",
     yes: "是", no: "否", stateMissing: "未安装", stateMatching: "已是最新", stateComplete: "完整", stateUserModified: "已被用户修改", statePartial: "不完整", stateOutdated: "可更新", stateSafeUpdate: "可安全更新", stateAdoptable: "可接管", stateUnreadable: "不可读", stateCompatible: "兼容", stateUpdateRequired: "需要更新", stateUnsupportedNewer: "版本过新且不受支持", stateUnverified: "未验证", stateUnknown: "未知",
-    actionInstall: "安装", actionKeep: "保留", actionBackupReplace: "备份并替换", actionRepair: "修复", actionBlocked: "需要确认",
+    actionInstall: "安装", actionKeep: "保留", actionBackupReplace: "备份并替换", actionRepair: "修复", actionBlocked: "需要确认",
     dryRunComplete: "预览完成。", defaultOrchestration: "默认编排", mattCompatibilityStatus: "Matt {release}：{status}",
-    title: "提供 Prim 与 Arch 编排的证据驱动工作流",
-    recommended: "推荐配置", apply: "开始安装", customize: "自定义", cancel: "取消",
+    title: "提供 Prim 与 Arch 编排的证据驱动工作流",
+    recommended: "推荐配置", apply: "开始安装", customize: "自定义", cancel: "取消",
     project: "项目（当前目录）", global: "全局 Matrix Skills",
-    copy: "复制（推荐）", symlink: "符号链接（高级）",
-    matrix: "Matrix", matt: "Matt Pocock skills", installed: "已安装", ready: "Matrix 已就绪。",
-    noPlatform: "未检测到已验证的平台。请选择 Claude Code、Codex，或两者。",
+    copy: "复制（推荐）", symlink: "符号链接（高级）",
+    matrix: "Matrix", matt: "Matt Pocock skills", installed: "已安装", ready: "Matrix 已就绪。",
+    noPlatform: "未检测到已验证的平台。请选择 Claude Code、Codex，或两者。",
     preview: "计划变更", confirm: "确认应用这些变更？", doctor: "安装诊断",
     matrixModifiedDiagnostic: "{platform}：现有 Matrix 资产无法确认由 Matrix 管理。", mattModifiedDiagnostic: "{platform}：Matt Skills 存在本地修改或不可读内容，需要单独授权替换。", archIncompleteDiagnostic: "Arch 需要精确匹配已审查集合和可信项目 receipt。请使用 --with-mattpocock 重试。", matrixStateDiagnostic: "{platform}：Matrix 状态为 {state}。", mattStateDiagnostic: "{platform}：Matt Pocock Skills 状态为 {state}。", codexLegacyDiagnostic: "检测到 Codex 旧版 .codex/skills；Matrix 不会写入该目录。", unmanagedExtraDiagnostic: "{platform}：将保留但不会调用这些非托管附加 Skills：{skills}。"
-  }
-};
-
-export function text(language, key) { return messages[language]?.[key] ?? messages.en[key] ?? key; }
+  }
+};
+
+export function text(language, key) { return messages[language]?.[key] ?? messages.en[key] ?? key; }

package/src/npm-invocation.js

@@ -0,0 +1,23 @@
+import fs from "node:fs";
+import path from "node:path";
+
+// Windows CreateProcess cannot launch npm.cmd, so npm/npx must run as
+// `node <npm-cli.js> ...`. Resolution order: explicit path, npm_execpath,
+// the npm bundled beside the running Node. Non-Windows returns the command
+// unchanged so every caller keeps its POSIX behavior.
+export function resolveNpmCli({ platform = process.platform, nodeExecutable = process.execPath, npmCliPath } = {}) {
+  if (platform !== "win32") return null;
+  const candidates = [npmCliPath, process.env.npm_execpath, path.join(path.dirname(nodeExecutable), "node_modules", "npm", "bin", "npm-cli.js")].filter(Boolean);
+  const cli = candidates.find((candidate) => npmCliPath || fs.existsSync(candidate));
+  if (!cli) throw new Error("npm CLI was not found beside the Node runtime. Install the package manually with `npm i -g <package>` or reinstall Node.js so its bundled npm is present.");
+  return cli;
+}
+
+export function buildNpmProcessInvocation({ command, args, platform = process.platform, nodeExecutable = process.execPath, npmCliPath }) {
+  if (platform !== "win32" || (command !== "npm" && command !== "npx")) return { executable: command, args, shell: false };
+  const cli = resolveNpmCli({ platform, nodeExecutable, npmCliPath });
+  if (command === "npm") return { executable: nodeExecutable, args: [cli, ...args], shell: false };
+  const [yes, packageSpec, ...commandArgs] = args;
+  if (yes !== "--yes" || !packageSpec) throw new Error("Windows npx invocation must use fixed npm exec arguments.");
+  return { executable: nodeExecutable, args: [cli, "exec", yes, packageSpec, "--", ...commandArgs], shell: false };
+}

package/src/project-index.js

@@ -0,0 +1,43 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const projectsIndexPath = (home = os.homedir()) => path.join(home, ".matrix", "projects.json");
+
+function writeAtomically(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`);
+  fs.renameSync(temporary, file);
+}
+
+export function readProjectsIndex({ home = os.homedir() } = {}) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(projectsIndexPath(home), "utf8"));
+    if (!Array.isArray(parsed)) return { ok: false, code: "PROJECTS_INDEX_CORRUPT", projects: [] };
+    const projects = parsed.filter((entry) => entry && typeof entry.path === "string");
+    return { ok: true, projects };
+  } catch (error) {
+    if (error.code === "ENOENT") return { ok: true, projects: [] };
+    return { ok: false, code: "PROJECTS_INDEX_CORRUPT", projects: [] };
+  }
+}
+
+export function registerProject({ projectRoot, scope, platforms, language, home = os.homedir() } = {}) {
+  const resolved = path.resolve(projectRoot);
+  const { ok, projects } = readProjectsIndex({ home });
+  const next = (ok ? projects : []).filter((entry) => entry.path !== resolved);
+  next.unshift({ path: resolved, scope, platforms, language, updatedAt: new Date().toISOString().replace(/\.\d{3}Z$/, "Z") });
+  writeAtomically(projectsIndexPath(home), next);
+  return { ok: true, projects: next };
+}
+
+export function pruneProject({ projectRoot, home = os.homedir() } = {}) {
+  const resolved = path.resolve(projectRoot);
+  const { ok, projects } = readProjectsIndex({ home });
+  if (!ok) return { ok: false, removed: null };
+  const removed = projects.find((entry) => entry.path === resolved) ?? null;
+  if (!removed) return { ok: true, removed: null };
+  writeAtomically(projectsIndexPath(home), projects.filter((entry) => entry.path !== resolved));
+  return { ok: true, removed };
+}

package/src/runtime-resolver.js

@@ -1,76 +1,76 @@
-import fs from "node:fs";
-import path from "node:path";
-import { MATRIX_VERSION, PLATFORMS, hashDirectory, releaseCatalog } from "./catalog.js";
-
-function readJson(file) {
-  try { return JSON.parse(fs.readFileSync(file, "utf8")); } catch { return null; }
-}
-
-function installationScope(projectRoot) {
-  try {
-    const line = fs.readFileSync(path.join(projectRoot, ".matrix", "config.yaml"), "utf8").split(/\r?\n/).find((value) => value.startsWith("installation_scope:"));
-    return line?.split(":").slice(1).join(":").trim() === "global" ? "global" : "project";
-  } catch { return "project"; }
-}
-
-function runtimeCommand(runtime) {
-  const quoted = process.platform === "win32" ? `"${runtime}"` : `'${runtime.replaceAll("'", "'\\''")}'`;
-  return `node ${quoted}`;
-}
-
-export function resolveProjectRuntime({ projectRoot = process.cwd() } = {}) {
-  const root = path.resolve(projectRoot);
-  const manifest = readJson(path.join(root, ".matrix", "installation.json"));
-  if (!manifest) return installationScope(root) === "global"
-    ? { ok: true, code: "GLOBAL_INSTALLATION", runtime: null }
-    : { ok: true, code: "PROJECT_INSTALLATION_ABSENT", runtime: null };
-  const candidates = [];
-  let currentCatalog = null;
-  let catalogUnavailable = false;
-  try { currentCatalog = releaseCatalog(manifest.language ?? "en"); } catch { catalogUnavailable = true; }
-  for (const platform of ["codex", "claude-code"]) {
-    const expected = manifest.platforms?.[platform]?.skills?.matrix?.hash;
-    if (!expected) continue;
-    const matrixRoot = path.join(PLATFORMS[platform].skillRoot(root), "matrix");
-    const runtime = path.join(matrixRoot, "scripts", "matrix-runtime.mjs");
-    if (!fs.existsSync(runtime)) { candidates.push({ platform, matrixRoot, runtime, reason: "missing" }); continue; }
-    try {
-      const actual = hashDirectory(matrixRoot);
-      if (actual === expected) {
-        if (manifest.catalogVersion !== MATRIX_VERSION) {
-          const catalogVersion = manifest.catalogVersion ?? null;
-          return {
-            ok: false,
-            code: catalogVersion ? "PROJECT_RUNTIME_VERSION_MISMATCH" : "PROJECT_RUNTIME_VERSION_UNKNOWN",
-            message: catalogVersion
-              ? `The project Matrix Runtime is ${catalogVersion}, while this launcher is ${MATRIX_VERSION}. The project remains authoritative, but a different-release Runtime requires explicit invocation.`
-              : `The project Matrix Runtime has no release identity. The project remains authoritative, but an unidentified Runtime requires explicit invocation.`,
-            platform,
-            runtime,
-            catalogVersion,
-            launcherVersion: MATRIX_VERSION,
-            recovery_command: runtimeCommand(runtime)
-          };
-        }
-        if (catalogUnavailable
-          || manifest.catalogDigest !== currentCatalog.digest || expected !== currentCatalog.skills.matrix) {
-          return {
-            ok: false,
-            code: "PROJECT_RUNTIME_RELEASE_MISMATCH",
-            message: `The project Matrix Runtime claims ${MATRIX_VERSION} but does not match that release catalog. Run matrix update.`,
-            platform,
-            runtime,
-            catalogVersion: manifest.catalogVersion,
-            expected: currentCatalog?.skills.matrix ?? null,
-            actual
-          };
-        }
-        return { ok: true, code: "PROJECT_RUNTIME", platform, runtime, catalogVersion: manifest.catalogVersion };
-      }
-      candidates.push({ platform, matrixRoot, runtime, reason: "modified" });
-    } catch { candidates.push({ platform, matrixRoot, runtime, reason: "unreadable" }); }
-  }
-  return candidates.length
-    ? { ok: false, code: "PROJECT_RUNTIME_UNTRUSTED", message: "The project Matrix Runtime does not match its installation manifest.", findings: candidates }
-    : { ok: true, code: "PROJECT_RUNTIME_ABSENT", runtime: null };
-}
+import fs from "node:fs";
+import path from "node:path";
+import { MATRIX_VERSION, PLATFORMS, hashDirectory, releaseCatalog } from "./catalog.js";
+
+function readJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, "utf8")); } catch { return null; }
+}
+
+function installationScope(projectRoot) {
+  try {
+    const line = fs.readFileSync(path.join(projectRoot, ".matrix", "config.yaml"), "utf8").split(/\r?\n/).find((value) => value.startsWith("installation_scope:"));
+    return line?.split(":").slice(1).join(":").trim() === "global" ? "global" : "project";
+  } catch { return "project"; }
+}
+
+function runtimeCommand(runtime) {
+  const quoted = process.platform === "win32" ? `"${runtime}"` : `'${runtime.replaceAll("'", "'\\''")}'`;
+  return `node ${quoted}`;
+}
+
+export function resolveProjectRuntime({ projectRoot = process.cwd() } = {}) {
+  const root = path.resolve(projectRoot);
+  const manifest = readJson(path.join(root, ".matrix", "installation.json"));
+  if (!manifest) return installationScope(root) === "global"
+    ? { ok: true, code: "GLOBAL_INSTALLATION", runtime: null }
+    : { ok: true, code: "PROJECT_INSTALLATION_ABSENT", runtime: null };
+  const candidates = [];
+  let currentCatalog = null;
+  let catalogUnavailable = false;
+  try { currentCatalog = releaseCatalog(manifest.language ?? "en"); } catch { catalogUnavailable = true; }
+  for (const platform of ["codex", "claude-code"]) {
+    const expected = manifest.platforms?.[platform]?.skills?.matrix?.hash;
+    if (!expected) continue;
+    const matrixRoot = path.join(PLATFORMS[platform].skillRoot(root), "matrix");
+    const runtime = path.join(matrixRoot, "scripts", "matrix-runtime.mjs");
+    if (!fs.existsSync(runtime)) { candidates.push({ platform, matrixRoot, runtime, reason: "missing" }); continue; }
+    try {
+      const actual = hashDirectory(matrixRoot);
+      if (actual === expected) {
+        if (manifest.catalogVersion !== MATRIX_VERSION) {
+          const catalogVersion = manifest.catalogVersion ?? null;
+          return {
+            ok: false,
+            code: catalogVersion ? "PROJECT_RUNTIME_VERSION_MISMATCH" : "PROJECT_RUNTIME_VERSION_UNKNOWN",
+            message: catalogVersion
+              ? `The project Matrix Runtime is ${catalogVersion}, while this launcher is ${MATRIX_VERSION}. The project remains authoritative, but a different-release Runtime requires explicit invocation.`
+              : `The project Matrix Runtime has no release identity. The project remains authoritative, but an unidentified Runtime requires explicit invocation.`,
+            platform,
+            runtime,
+            catalogVersion,
+            launcherVersion: MATRIX_VERSION,
+            recovery_command: runtimeCommand(runtime)
+          };
+        }
+        if (catalogUnavailable
+          || manifest.catalogDigest !== currentCatalog.digest || expected !== currentCatalog.skills.matrix) {
+          return {
+            ok: false,
+            code: "PROJECT_RUNTIME_RELEASE_MISMATCH",
+            message: `The project Matrix Runtime claims ${MATRIX_VERSION} but does not match that release catalog. Run matrix update.`,
+            platform,
+            runtime,
+            catalogVersion: manifest.catalogVersion,
+            expected: currentCatalog?.skills.matrix ?? null,
+            actual
+          };
+        }
+        return { ok: true, code: "PROJECT_RUNTIME", platform, runtime, catalogVersion: manifest.catalogVersion };
+      }
+      candidates.push({ platform, matrixRoot, runtime, reason: "modified" });
+    } catch { candidates.push({ platform, matrixRoot, runtime, reason: "unreadable" }); }
+  }
+  return candidates.length
+    ? { ok: false, code: "PROJECT_RUNTIME_UNTRUSTED", message: "The project Matrix Runtime does not match its installation manifest.", findings: candidates }
+    : { ok: true, code: "PROJECT_RUNTIME_ABSENT", runtime: null };
+}

package/src/self-update.js

@@ -1,81 +1,88 @@
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { spawnSync } from "node:child_process";
-
-export const PACKAGE_NAME = "@rosenfan/matrix";
-const REGISTRY = "https://registry.npmjs.org/@rosenfan%2fmatrix/latest";
-
-function parse(version) {
-  const match = String(version ?? "").match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
-  return match ? { numeric: match.slice(1, 4).map(Number), prerelease: match[4] ?? null } : null;
-}
-
-export function compareVersions(left, right) {
-  const a = parse(left); const b = parse(right);
-  if (!a || !b) return null;
-  for (let index = 0; index < 3; index += 1) if (a.numeric[index] !== b.numeric[index]) return a.numeric[index] - b.numeric[index];
-  if (a.prerelease === b.prerelease) return 0;
-  if (a.prerelease === null) return 1;
-  if (b.prerelease === null) return -1;
-  return a.prerelease.localeCompare(b.prerelease, undefined, { numeric: true });
-}
-
-export async function latestVersion(fetchImpl = fetch) {
-  const response = await fetchImpl(REGISTRY, { headers: { accept: "application/json" } });
-  if (!response.ok) throw new Error(`registry returned ${response.status}`);
-  const body = await response.json();
-  if (!parse(body.version)) throw new Error("registry returned an invalid version");
-  return body.version;
-}
-
-function run(command, args, options = {}) {
-  const result = spawnSync(command, args, { encoding: "utf8", ...options });
-  return { ok: !result.error && result.status === 0, status: result.status, error: result.error?.message, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
-}
-
-export function validateCandidate(packageRoot, expectedVersion) {
-  const manifestFile = path.join(packageRoot, "package.json");
-  try {
-    const manifest = JSON.parse(fs.readFileSync(manifestFile, "utf8"));
-    if (manifest.name !== PACKAGE_NAME || manifest.version !== expectedVersion) return { ok: false, reason: "candidate package identity mismatch" };
-    for (const directory of [".claude/skills", "assets/skills-zh-CN", "src", "bin"]) if (!fs.existsSync(path.join(packageRoot, directory))) return { ok: false, reason: `candidate missing ${directory}` };
-    for (const languageRoot of [path.join(packageRoot, ".claude", "skills"), path.join(packageRoot, "assets", "skills-zh-CN")]) if (!fs.existsSync(path.join(languageRoot, "matrix", "SKILL.md"))) return { ok: false, reason: "candidate Matrix assets are incomplete" };
-    for (const args of [["--version"], ["--help"], ["workflow", "doctor", "--json"]]) {
-      const result = run(process.execPath, [path.join(packageRoot, "bin", "matrix.js"), ...args], { cwd: os.tmpdir() });
-      if (!result.ok) return { ok: false, reason: `candidate command failed: matrix ${args.join(" ")}` };
-    }
-    return { ok: true };
-  } catch (error) { return { ok: false, reason: error.message }; }
-}
-
-export function npmGlobalRoot() {
-  const result = run("npm", ["root", "-g"]);
-  if (!result.ok) throw new Error(result.error ?? result.stderr.trim() ?? "npm root -g failed");
-  return result.stdout.trim();
-}
-
-export function validateRegistryCandidate(version) {
-  const temporary = fs.mkdtempSync(path.join(os.tmpdir(), "matrix-update-"));
-  try {
-    const install = run("npm", ["install", "--prefix", temporary, "--ignore-scripts", "--no-save", "--package-lock=false", `${PACKAGE_NAME}@${version}`], { cwd: temporary });
-    if (!install.ok) return { ok: false, reason: install.error ?? install.stderr.trim() ?? "candidate installation failed" };
-    return validateCandidate(path.join(temporary, "node_modules", "@rosenfan", "matrix"), version);
-  } finally { fs.rmSync(temporary, { recursive: true, force: true }); }
-}
-
-export function installGlobal(version) {
-  const result = run("npm", ["install", "--global", `${PACKAGE_NAME}@${version}`]);
-  return result.ok ? { ok: true } : { ok: false, reason: result.error ?? result.stderr.trim() ?? "npm install failed" };
-}
-
-export function selfUpdate(currentVersion, targetVersion) {
-  const candidate = validateRegistryCandidate(targetVersion);
-  if (!candidate.ok) return candidate;
-  const install = installGlobal(targetVersion);
-  if (install.ok) return install;
-  const rollback = installGlobal(currentVersion);
-  return { ok: false, reason: `${install.reason}; ${rollback.ok ? `restored ${currentVersion}` : `rollback failed: ${rollback.reason}`}` };
-}
-
-export function globalBinPath() { return path.join(npmGlobalRoot(), "@rosenfan", "matrix", "bin", "matrix.js"); }
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { buildNpmProcessInvocation } from "./npm-invocation.js";
+
+export const PACKAGE_NAME = "@rosenfan/matrix";
+const REGISTRY = "https://registry.npmjs.org/@rosenfan%2fmatrix/latest";
+
+function parse(version) {
+  const match = String(version ?? "").match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
+  return match ? { numeric: match.slice(1, 4).map(Number), prerelease: match[4] ?? null } : null;
+}
+
+export function compareVersions(left, right) {
+  const a = parse(left); const b = parse(right);
+  if (!a || !b) return null;
+  for (let index = 0; index < 3; index += 1) if (a.numeric[index] !== b.numeric[index]) return a.numeric[index] - b.numeric[index];
+  if (a.prerelease === b.prerelease) return 0;
+  if (a.prerelease === null) return 1;
+  if (b.prerelease === null) return -1;
+  return a.prerelease.localeCompare(b.prerelease, undefined, { numeric: true });
+}
+
+export async function latestVersion(fetchImpl = fetch) {
+  const response = await fetchImpl(REGISTRY, { headers: { accept: "application/json" } });
+  if (!response.ok) throw new Error(`registry returned ${response.status}`);
+  const body = await response.json();
+  if (!parse(body.version)) throw new Error("registry returned an invalid version");
+  return body.version;
+}
+
+function run(command, args, options = {}) {
+  let invocation;
+  try {
+    invocation = buildNpmProcessInvocation({ command, args });
+  } catch (error) {
+    return { ok: false, status: null, error: error.message, stdout: "", stderr: "" };
+  }
+  const result = spawnSync(invocation.executable, invocation.args, { encoding: "utf8", ...options });
+  return { ok: !result.error && result.status === 0, status: result.status, error: result.error?.message, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
+}
+
+export function validateCandidate(packageRoot, expectedVersion) {
+  const manifestFile = path.join(packageRoot, "package.json");
+  try {
+    const manifest = JSON.parse(fs.readFileSync(manifestFile, "utf8"));
+    if (manifest.name !== PACKAGE_NAME || manifest.version !== expectedVersion) return { ok: false, reason: "candidate package identity mismatch" };
+    for (const directory of ["assets/skills", "assets/skills-zh-CN", "src", "bin"]) if (!fs.existsSync(path.join(packageRoot, directory))) return { ok: false, reason: `candidate missing ${directory}` };
+    for (const languageRoot of [path.join(packageRoot, "assets", "skills"), path.join(packageRoot, "assets", "skills-zh-CN")]) if (!fs.existsSync(path.join(languageRoot, "matrix", "SKILL.md"))) return { ok: false, reason: "candidate Matrix assets are incomplete" };
+    for (const args of [["--version"], ["--help"], ["workflow", "doctor", "--json"]]) {
+      const result = run(process.execPath, [path.join(packageRoot, "bin", "matrix.js"), ...args], { cwd: os.tmpdir() });
+      if (!result.ok) return { ok: false, reason: `candidate command failed: matrix ${args.join(" ")}` };
+    }
+    return { ok: true };
+  } catch (error) { return { ok: false, reason: error.message }; }
+}
+
+export function npmGlobalRoot() {
+  const result = run("npm", ["root", "-g"]);
+  if (!result.ok) throw new Error(result.error ?? result.stderr.trim() ?? "npm root -g failed");
+  return result.stdout.trim();
+}
+
+export function validateRegistryCandidate(version) {
+  const temporary = fs.mkdtempSync(path.join(os.tmpdir(), "matrix-update-"));
+  try {
+    const install = run("npm", ["install", "--prefix", temporary, "--ignore-scripts", "--no-save", "--package-lock=false", `${PACKAGE_NAME}@${version}`], { cwd: temporary });
+    if (!install.ok) return { ok: false, reason: install.error ?? install.stderr.trim() ?? "candidate installation failed" };
+    return validateCandidate(path.join(temporary, "node_modules", "@rosenfan", "matrix"), version);
+  } finally { fs.rmSync(temporary, { recursive: true, force: true }); }
+}
+
+export function installGlobal(version) {
+  const result = run("npm", ["install", "--global", `${PACKAGE_NAME}@${version}`]);
+  return result.ok ? { ok: true } : { ok: false, reason: result.error ?? result.stderr.trim() ?? "npm install failed" };
+}
+
+export function selfUpdate(currentVersion, targetVersion) {
+  const candidate = validateRegistryCandidate(targetVersion);
+  if (!candidate.ok) return candidate;
+  const install = installGlobal(targetVersion);
+  if (install.ok) return install;
+  const rollback = installGlobal(currentVersion);
+  return { ok: false, reason: `${install.reason}; ${rollback.ok ? `restored ${currentVersion}` : `rollback failed: ${rollback.reason}`}` };
+}
+
+export function globalBinPath() { return path.join(npmGlobalRoot(), "@rosenfan", "matrix", "bin", "matrix.js"); }