@rosenfan/matrix 0.1.2 → 0.1.3

package/src/distribution.js

@@ -2,38 +2,47 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import {
-  MATRIX_SKILLS, MATT_SKILLS, UNMANAGED_MATT_SKILLS, PLATFORM_IDS, PLATFORMS, hashDirectory,
-  installationRoot, manifestPath, releaseCatalog, scopeBase, sourceSkillsRoot, workflowRuntimeSource, workflowTransactionSource
-} from "./catalog.js";
+import {
+  MATRIX_SKILLS, MATT_SKILLS, UNMANAGED_MATT_SKILLS, PLATFORM_IDS, PLATFORMS, hashDirectory,
+  installationRoot, manifestPath, releaseCatalog, scopeBase, sourceSkillsRoot, workflowRuntimeSource, workflowTransactionSource
+} from "./catalog.js";
 import { createMattAdapter } from "./matt.js";
 import { text } from "./messages.js";
 
-const VERSION = 2;
+const VERSION = 2;
 const digest = (value) => crypto.createHash("sha256").update(JSON.stringify(value)).digest("hex");
 const exists = (value) => fs.existsSync(value);
 const pathExists = (value) => { try { fs.lstatSync(value); return true; } catch { return false; } };
 const nowStamp = () => new Date().toISOString().replace(/[:.]/g, "-");
-const transactionPath = (intent) => path.join(installationRoot(intent.scope, intent.projectRoot, intent.home), "transaction.json");
-const configPath = (intent) => path.join(intent.projectRoot, ".matrix", "config.yaml");
+const transactionPath = (intent) => path.join(installationRoot(intent.scope, intent.projectRoot, intent.home), "transaction.json");
+const configPath = (intent) => path.join(intent.projectRoot, ".matrix", "config.yaml");
 const writeJson = (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);
 };
-const readJson = (file) => { try { return JSON.parse(fs.readFileSync(file, "utf8")); } catch { return null; } };
-const readConfig = (file) => {
-  try {
-    return Object.fromEntries(fs.readFileSync(file, "utf8").split(/\r?\n/).filter((line) => line.includes(":") && !line.startsWith(" ")).map((line) => {
-      const [key, ...value] = line.split(":");
-      return [key.trim(), value.join(":").trim()];
-    }));
-  } catch { return {}; }
-};
-const configContent = (existing, defaultOrchestration, scope) => {
-  const autoTransition = existing.auto_transition === "false" ? "false" : "true";
-  return `schema: matrix/config/v1\nauto_transition: ${autoTransition}\ndefault_orchestration: ${defaultOrchestration}\ninstallation_scope: ${scope}\n`;
+const readJson = (file) => { try { return JSON.parse(fs.readFileSync(file, "utf8")); } catch { return null; } };
+const readConfig = (file) => {
+  try {
+    return Object.fromEntries(fs.readFileSync(file, "utf8").split(/\r?\n/).filter((line) => line.includes(":") && !line.startsWith(" ")).map((line) => {
+      const [key, ...value] = line.split(":");
+      return [key.trim(), value.join(":").trim()];
+    }));
+  } catch { return {}; }
+};
+const configContent = (existing, defaultOrchestration, scope, language) => {
+  const values = {
+    ...existing,
+    schema: "matrix/config/v1",
+    auto_transition: existing.auto_transition === "false" ? "false" : "true",
+    default_orchestration: defaultOrchestration,
+    installation_scope: scope,
+    language
+  };
+  const preferred = ["schema", "auto_transition", "default_orchestration", "installation_scope", "language"];
+  const keys = [...preferred, ...Object.keys(values).filter((key) => !preferred.includes(key)).sort()];
+  return `${keys.map((key) => `${key}: ${values[key]}`).join("\n")}\n`;
 };
 const removeEntry = (value) => { if (pathExists(value)) fs.rmSync(value, { recursive: true, force: true }); };
 const removeStaging = (stagingRoot) => {
@@ -50,7 +59,29 @@ const compareVersions = (left, right) => {
 const skillPresent = (root, skill) => exists(path.join(root, skill, "SKILL.md"));
 const isBrokenLink = (value) => { try { return fs.lstatSync(value).isSymbolicLink() && !exists(value); } catch { return false; } };
 
-function readManifest(intent) { return readJson(manifestPath(intent.scope, intent.projectRoot, intent.home)); }
+function readManifest(intent) { return readJson(manifestPath(intent.scope, intent.projectRoot, intent.home)); }
+
+export function installedIntent({ projectRoot = process.cwd(), home = os.homedir() } = {}) {
+  const resolvedProjectRoot = path.resolve(projectRoot);
+  const config = readConfig(path.join(resolvedProjectRoot, ".matrix", "config.yaml"));
+  const scope = config.installation_scope === "global" ? "global" : "project";
+  const manifest = readJson(manifestPath(scope, resolvedProjectRoot, home));
+  const platforms = Object.keys(manifest?.platforms ?? {}).filter((id) => PLATFORM_IDS.includes(id));
+  if (!manifest || !platforms.length) return { ok: false, code: "MANIFEST_MISSING", scope, config };
+  const language = ["en", "zh-CN"].includes(manifest.language) ? manifest.language : (["en", "zh-CN"].includes(config.language) ? config.language : "en");
+  const defaultOrchestration = ["prim", "arch"].includes(manifest.orchestration?.default) ? manifest.orchestration.default : "prim";
+  const matt = manifest.orchestration?.available?.includes("arch") ? "missing" : "none";
+  return {
+    ok: true,
+    intent: {
+      projectRoot: resolvedProjectRoot, home, scope, platforms, language,
+      mode: ["copy", "symlink"].includes(manifest.mode) ? manifest.mode : "copy",
+      matt, defaultOrchestration, nonInteractive: true, matrixPolicy: "safe", dryRun: false
+    },
+    manifest,
+    config
+  };
+}
 
 function detectPlatforms(projectRoot, scope, home) {
   const bases = [scopeBase(scope, projectRoot, home)];
@@ -58,19 +89,19 @@ function detectPlatforms(projectRoot, scope, home) {
   return PLATFORM_IDS.filter((id) => bases.some((base) => exists(PLATFORMS[id].skillRoot(base))));
 }
 
-function normalizeIntent(raw) {
+function normalizeIntent(raw) {
   const scope = raw.scope ?? "project";
   const platforms = [...new Set(raw.platforms ?? [])];
   if (!["project", "global"].includes(scope)) return { error: "INVALID_INTENT", detail: "scope" };
   if (!["copy", "symlink"].includes(raw.mode ?? "copy")) return { error: "INVALID_INTENT", detail: "mode" };
-  if (!["en", "zh-CN"].includes(raw.language ?? "en")) return { error: "INVALID_INTENT", detail: "language" };
-  if (raw.defaultOrchestration != null && !["prim", "arch"].includes(raw.defaultOrchestration)) return { error: "INVALID_INTENT", detail: "default-orchestration" };
+  if (!["en", "zh-CN"].includes(raw.language ?? "en")) return { error: "INVALID_INTENT", detail: "language" };
+  if (raw.defaultOrchestration != null && !["prim", "arch"].includes(raw.defaultOrchestration)) return { error: "INVALID_INTENT", detail: "default-orchestration" };
   if (platforms.some((id) => !PLATFORM_IDS.includes(id))) return { error: "UNVERIFIED_PLATFORM" };
   return { projectRoot: path.resolve(raw.projectRoot ?? process.cwd()), home: raw.home ?? os.homedir(), scope, platforms,
-    language: raw.language ?? "en", mode: raw.mode ?? "copy", matrixPolicy: raw.matrixPolicy ?? "safe",
-    matt: raw.matt ?? "none", defaultOrchestration: raw.defaultOrchestration ?? null,
-    nonInteractive: Boolean(raw.nonInteractive), dryRun: Boolean(raw.dryRun) };
-}
+    language: raw.language ?? "en", mode: raw.mode ?? "copy", matrixPolicy: raw.matrixPolicy ?? "safe",
+    matt: raw.matt ?? "none", defaultOrchestration: raw.defaultOrchestration ?? null,
+    nonInteractive: Boolean(raw.nonInteractive), dryRun: Boolean(raw.dryRun) };
+}
 
 function observePlatform(intent, catalog, manifest, platformId) {
   const platform = PLATFORMS[platformId]; const base = scopeBase(intent.scope, intent.projectRoot, intent.home);
@@ -90,18 +121,18 @@ function observePlatform(intent, catalog, manifest, platformId) {
     : states.has("missing") && states.size === 1 ? "missing" : states.has("newer") ? "newer"
       : states.has("damaged") ? "damaged" : states.has("outdated-unchanged") ? "outdated-unchanged" : "partial";
   const globalRoot = platform.skillRoot(intent.home);
-  const mattPresent = MATT_SKILLS.filter((skill) => skillPresent(root, skill));
-  const globalMatt = intent.scope === "project" ? MATT_SKILLS.filter((skill) => skillPresent(globalRoot, skill)) : [];
-  const availableMatt = new Set([...mattPresent, ...globalMatt]); const missing = MATT_SKILLS.filter((skill) => !availableMatt.has(skill));
-  const inherited = globalMatt.filter((skill) => !mattPresent.includes(skill)).length;
-  const managedSkills = Object.fromEntries([...availableMatt].map((skill) => {
-    const target = mattPresent.includes(skill) ? path.join(root, skill) : path.join(globalRoot, skill);
-    return [skill, { root: target, hash: hashDirectory(target) }];
-  }));
-  const unmanaged = UNMANAGED_MATT_SKILLS.filter((skill) => skillPresent(root, skill) || (intent.scope === "project" && skillPresent(globalRoot, skill)));
-  return { id: platformId, name: platform.name, root, skills, matrix, matt: { present: mattPresent.length, missing, total: MATT_SKILLS.length, inherited,
-    state: availableMatt.size === MATT_SKILLS.length ? "complete" : availableMatt.size ? "partial" : "missing", skills: managedSkills, unmanaged } };
-}
+  const mattPresent = MATT_SKILLS.filter((skill) => skillPresent(root, skill));
+  const globalMatt = intent.scope === "project" ? MATT_SKILLS.filter((skill) => skillPresent(globalRoot, skill)) : [];
+  const availableMatt = new Set([...mattPresent, ...globalMatt]); const missing = MATT_SKILLS.filter((skill) => !availableMatt.has(skill));
+  const inherited = globalMatt.filter((skill) => !mattPresent.includes(skill)).length;
+  const managedSkills = Object.fromEntries([...availableMatt].map((skill) => {
+    const target = mattPresent.includes(skill) ? path.join(root, skill) : path.join(globalRoot, skill);
+    return [skill, { root: target, hash: hashDirectory(target) }];
+  }));
+  const unmanaged = UNMANAGED_MATT_SKILLS.filter((skill) => skillPresent(root, skill) || (intent.scope === "project" && skillPresent(globalRoot, skill)));
+  return { id: platformId, name: platform.name, root, skills, matrix, matt: { present: mattPresent.length, missing, total: MATT_SKILLS.length, inherited,
+    state: availableMatt.size === MATT_SKILLS.length ? "complete" : availableMatt.size ? "partial" : "missing", skills: managedSkills, unmanaged } };
+}
 
 function actionFor(observation, policy) {
   if (observation.matrix === "matching" || observation.matrix === "newer") return "keep";
@@ -111,60 +142,60 @@ function actionFor(observation, policy) {
   return "repair";
 }
 
-export function recoverPendingTransaction(intent) {
-  const file = transactionPath(intent); const journal = readJson(file);
-  if (!journal) return { ok: true, recovered: false };
-  const restoreMetadata = (entry) => {
-    if (!entry) return;
-    if (entry.backup && pathExists(entry.backup)) {
-      removeEntry(entry.path);
-      fs.mkdirSync(path.dirname(entry.path), { recursive: true });
-      fs.renameSync(entry.backup, entry.path);
-    } else if (entry.written && !entry.existed) removeEntry(entry.path);
-  };
-  try {
-    if (journal.state === "committed") {
-      removeStaging(journal.stagingRoot);
-      for (const operation of journal.operations ?? []) removeEntry(operation.backup);
-      removeEntry(journal.manifest?.backup); removeEntry(journal.config?.backup); removeEntry(file);
-      return { ok: true, recovered: true, receipt: `Finalized completed Matrix transaction ${journal.id}.` };
+export function recoverPendingTransaction(intent) {
+  const file = transactionPath(intent); const journal = readJson(file);
+  if (!journal) return { ok: true, recovered: false };
+  const restoreMetadata = (entry) => {
+    if (!entry) return;
+    if (entry.backup && pathExists(entry.backup)) {
+      removeEntry(entry.path);
+      fs.mkdirSync(path.dirname(entry.path), { recursive: true });
+      fs.renameSync(entry.backup, entry.path);
+    } else if (entry.written && !entry.existed) removeEntry(entry.path);
+  };
+  try {
+    if (journal.state === "committed") {
+      removeStaging(journal.stagingRoot);
+      for (const operation of journal.operations ?? []) removeEntry(operation.backup);
+      removeEntry(journal.manifest?.backup); removeEntry(journal.config?.backup); removeEntry(file);
+      return { ok: true, recovered: true, receipt: `Finalized completed Matrix transaction ${journal.id}.` };
     }
     for (const operation of [...(journal.operations ?? [])].reverse()) {
       if (operation.status !== "pending") removeEntry(operation.target);
       if (operation.backup && pathExists(operation.backup)) { fs.mkdirSync(path.dirname(operation.target), { recursive: true }); fs.renameSync(operation.backup, operation.target); }
     }
-    restoreMetadata(journal.config);
-    restoreMetadata(journal.manifest);
+    restoreMetadata(journal.config);
+    restoreMetadata(journal.manifest);
     removeStaging(journal.stagingRoot); removeEntry(file);
     return { ok: true, recovered: true, receipt: `Recovered interrupted Matrix transaction ${journal.id}.` };
   } catch (error) { return { ok: false, code: "RECOVERY_REQUIRED", recovery: `Keep ${file} and restore the paths recorded there before retrying.`, error: error.message }; }
 }
 
 export function createDistribution({ failAt, mattAdapter = createMattAdapter() } = {}) {
-  const evaluate = (rawIntent) => {
-    const intent = normalizeIntent(rawIntent); const language = intent.language ?? rawIntent.language ?? "en";
-    if (intent.error) return { ok: false, code: intent.error, diagnostics: [{ code: intent.error, message: text(language, "noPlatform") }] };
-    if (!intent.platforms.length) { const detected = detectPlatforms(intent.projectRoot, intent.scope, intent.home); if (!detected.length) return { ok: false, code: "INPUT_REQUIRED", diagnostics: [{ code: "INPUT_REQUIRED", message: text(language, "noPlatform") }] }; intent.platforms = detected; }
-    let catalog; try { catalog = releaseCatalog(intent.language); } catch (error) { return { ok: false, code: "PACKAGE_INCOMPLETE", intent, diagnostics: [{ code: "PACKAGE_INCOMPLETE", message: error.message }] }; }
-    const manifest = readManifest(intent);
-    intent.platforms = [...new Set([...Object.keys(manifest?.platforms ?? {}), ...intent.platforms])];
-    const observations = intent.platforms.map((id) => observePlatform(intent, catalog, manifest, id));
-    const existingConfig = readConfig(configPath(intent));
-    const existingDefault = ["prim", "arch"].includes(existingConfig.default_orchestration) ? existingConfig.default_orchestration
-      : ["prim", "arch"].includes(manifest?.orchestration?.default) ? manifest.orchestration.default : null;
-    intent.defaultOrchestration = intent.defaultOrchestration ?? existingDefault ?? (intent.matt === "missing" && intent.nonInteractive ? "arch" : "prim");
-    const actions = observations.map((item) => ({ platform: item.id, matrix: actionFor(item, intent.matrixPolicy), matt: item.matt.state === "complete" || intent.matt === "none" ? { kind: "keep", skills: [] } : { kind: "install-missing", skills: item.matt.missing } }));
-    const blocked = actions.filter((item) => item.matrix === "blocked");
-    const archMustRemainAvailable = manifest?.orchestration?.available?.includes("arch") || intent.defaultOrchestration === "arch";
-    const incompleteWithoutInstall = archMustRemainAvailable && actions.some((item, index) => observations[index].matt.state !== "complete" && item.matt.kind !== "install-missing");
-    const plan = { version: VERSION, intent, catalogDigest: catalog.digest, manifestPath: manifestPath(intent.scope, intent.projectRoot, intent.home), configPath: configPath(intent), actions, observations, preconditionDigest: digest(observations) };
-    plan.seal = digest({ intent, catalogDigest: plan.catalogDigest, actions, preconditionDigest: plan.preconditionDigest });
-    const code = blocked.length ? "USER_MODIFIED_BLOCKED" : incompleteWithoutInstall ? "ARCH_INSTALLATION_INCOMPLETE" : "OK";
-    return { ok: code === "OK", code, intent, observations, actions, plan, diagnostics: [
-      ...blocked.map((item) => ({ code: "USER_MODIFIED_BLOCKED", platform: item.platform, message: `${item.platform}: existing Matrix assets are not proven managed.` })),
-      ...(incompleteWithoutInstall ? [{ code: "ARCH_INSTALLATION_INCOMPLETE", message: "Arch requires the complete managed cohort on every configured platform. Retry with --with-mattpocock." }] : [])
-    ], summary: `${text(intent.language, "preview")}: ${actions.map((item) => `${item.platform}: ${item.matrix}`).join(", ")}` };
-  };
+  const evaluate = (rawIntent) => {
+    const intent = normalizeIntent(rawIntent); const language = intent.language ?? rawIntent.language ?? "en";
+    if (intent.error) return { ok: false, code: intent.error, diagnostics: [{ code: intent.error, message: text(language, "noPlatform") }] };
+    if (!intent.platforms.length) { const detected = detectPlatforms(intent.projectRoot, intent.scope, intent.home); if (!detected.length) return { ok: false, code: "INPUT_REQUIRED", diagnostics: [{ code: "INPUT_REQUIRED", message: text(language, "noPlatform") }] }; intent.platforms = detected; }
+    let catalog; try { catalog = releaseCatalog(intent.language); } catch (error) { return { ok: false, code: "PACKAGE_INCOMPLETE", intent, diagnostics: [{ code: "PACKAGE_INCOMPLETE", message: error.message }] }; }
+    const manifest = readManifest(intent);
+    intent.platforms = [...new Set([...Object.keys(manifest?.platforms ?? {}), ...intent.platforms])];
+    const observations = intent.platforms.map((id) => observePlatform(intent, catalog, manifest, id));
+    const existingConfig = readConfig(configPath(intent));
+    const existingDefault = ["prim", "arch"].includes(existingConfig.default_orchestration) ? existingConfig.default_orchestration
+      : ["prim", "arch"].includes(manifest?.orchestration?.default) ? manifest.orchestration.default : null;
+    intent.defaultOrchestration = intent.defaultOrchestration ?? existingDefault ?? (intent.matt === "missing" && intent.nonInteractive ? "arch" : "prim");
+    const actions = observations.map((item) => ({ platform: item.id, matrix: actionFor(item, intent.matrixPolicy), matt: item.matt.state === "complete" || intent.matt === "none" ? { kind: "keep", skills: [] } : { kind: "install-missing", skills: item.matt.missing } }));
+    const blocked = actions.filter((item) => item.matrix === "blocked");
+    const archMustRemainAvailable = manifest?.orchestration?.available?.includes("arch") || intent.defaultOrchestration === "arch";
+    const incompleteWithoutInstall = archMustRemainAvailable && actions.some((item, index) => observations[index].matt.state !== "complete" && item.matt.kind !== "install-missing");
+    const plan = { version: VERSION, intent, catalogDigest: catalog.digest, manifestPath: manifestPath(intent.scope, intent.projectRoot, intent.home), configPath: configPath(intent), actions, observations, preconditionDigest: digest(observations) };
+    plan.seal = digest({ intent, catalogDigest: plan.catalogDigest, actions, preconditionDigest: plan.preconditionDigest });
+    const code = blocked.length ? "USER_MODIFIED_BLOCKED" : incompleteWithoutInstall ? "ARCH_INSTALLATION_INCOMPLETE" : "OK";
+    return { ok: code === "OK", code, intent, observations, actions, plan, diagnostics: [
+      ...blocked.map((item) => ({ code: "USER_MODIFIED_BLOCKED", platform: item.platform, message: `${item.platform}: existing Matrix assets are not proven managed.` })),
+      ...(incompleteWithoutInstall ? [{ code: "ARCH_INSTALLATION_INCOMPLETE", message: "Arch requires the complete managed cohort on every configured platform. Retry with --with-mattpocock." }] : [])
+    ], summary: `${text(intent.language, "preview")}: ${actions.map((item) => `${item.platform}: ${item.matrix}`).join(", ")}` };
+  };
 
   return { evaluate,
     diagnose(rawIntent) {
@@ -175,13 +206,13 @@ export function createDistribution({ failAt, mattAdapter = createMattAdapter() }
       for (const observation of evaluation.observations ?? []) {
         diagnostics.push({ code: `MATRIX_${observation.matrix.toUpperCase().replaceAll("-", "_")}`, platform: observation.id, message: `${observation.name}: Matrix is ${observation.matrix}.` });
         const matrixRoot = path.join(observation.root, "matrix");
-        if (pathExists(matrixRoot) && (!exists(matrixRoot) || !exists(path.join(matrixRoot, "scripts", "matrix-runtime.mjs")) || !exists(path.join(matrixRoot, "scripts", "workflow-transaction.js")))) diagnostics.push({ code: "RUNTIME_MISSING", platform: observation.id, message: `${observation.name}: ${text(evaluation.intent.language, "runtimeMissing")}` });
+        if (pathExists(matrixRoot) && (!exists(matrixRoot) || !exists(path.join(matrixRoot, "scripts", "matrix-runtime.mjs")) || !exists(path.join(matrixRoot, "scripts", "workflow-transaction.js")))) diagnostics.push({ code: "RUNTIME_MISSING", platform: observation.id, message: `${observation.name}: ${text(evaluation.intent.language, "runtimeMissing")}` });
         for (const skill of observation.skills.filter((entry) => isBrokenLink(entry.target))) diagnostics.push({ code: "BROKEN_LINK", platform: observation.id, path: skill.target, message: `${observation.name}: ${text(evaluation.intent.language, "brokenLink")} ${skill.target}` });
         if (observation.id === "codex" && PLATFORMS.codex.legacyRoots(scopeBase(evaluation.intent.scope, evaluation.intent.projectRoot, evaluation.intent.home)).some(exists)) diagnostics.push({ code: "CODEX_LEGACY_DETECTED", platform: observation.id, message: "Codex legacy .codex/skills was detected; Matrix will not write there." });
-        diagnostics.push({ code: `MATT_${observation.matt.state.toUpperCase()}`, platform: observation.id, message: `${observation.name}: Matt Pocock skills are ${observation.matt.state}.` });
-        if (observation.matt.inherited) diagnostics.push({ code: "MATT_INHERITED", platform: observation.id, message: `${observation.name}: ${observation.matt.inherited} ${text(evaluation.intent.language, "mattInherited")}` });
-        if (observation.matt.unmanaged.length) diagnostics.push({ code: "ARCH_UNMANAGED_EXTRA", platform: observation.id, skills: observation.matt.unmanaged, message: `${observation.name}: unmanaged extra Skills are preserved and will not be invoked: ${observation.matt.unmanaged.join(", ")}.` });
-      }
+        diagnostics.push({ code: `MATT_${observation.matt.state.toUpperCase()}`, platform: observation.id, message: `${observation.name}: Matt Pocock skills are ${observation.matt.state}.` });
+        if (observation.matt.inherited) diagnostics.push({ code: "MATT_INHERITED", platform: observation.id, message: `${observation.name}: ${observation.matt.inherited} ${text(evaluation.intent.language, "mattInherited")}` });
+        if (observation.matt.unmanaged.length) diagnostics.push({ code: "ARCH_UNMANAGED_EXTRA", platform: observation.id, skills: observation.matt.unmanaged, message: `${observation.name}: unmanaged extra Skills are preserved and will not be invoked: ${observation.matt.unmanaged.join(", ")}.` });
+      }
       return { ...evaluation, diagnosis: diagnostics };
     },
     commit(plan) {
@@ -191,13 +222,13 @@ export function createDistribution({ failAt, mattAdapter = createMattAdapter() }
       if (!refreshed.plan || refreshed.plan.preconditionDigest !== plan.preconditionDigest || refreshed.plan.catalogDigest !== plan.catalogDigest) return { ok: false, code: "PLAN_STALE" };
       if (!refreshed.ok) return { ok: false, code: refreshed.code, diagnostics: refreshed.diagnostics };
       if (plan.intent.dryRun) return { ok: true, code: "DRY_RUN", actions: plan.actions };
-      const root = installationRoot(plan.intent.scope, plan.intent.projectRoot, plan.intent.home); const id = nowStamp(); const stagingRoot = path.join(root, "staging", id); const journalFile = transactionPath(plan.intent);
-      const journal = {
-        id, state: "in-progress", stagingRoot,
-        manifest: { path: plan.manifestPath, existed: pathExists(plan.manifestPath), backup: null, written: false },
-        config: { path: plan.configPath, existed: pathExists(plan.configPath), backup: null, written: false },
-        operations: []
-      };
+      const root = installationRoot(plan.intent.scope, plan.intent.projectRoot, plan.intent.home); const id = nowStamp(); const stagingRoot = path.join(root, "staging", id); const journalFile = transactionPath(plan.intent);
+      const journal = {
+        id, state: "in-progress", stagingRoot,
+        manifest: { path: plan.manifestPath, existed: pathExists(plan.manifestPath), backup: null, written: false },
+        config: { path: plan.configPath, existed: pathExists(plan.configPath), backup: null, written: false },
+        operations: []
+      };
       for (const item of refreshed.observations) if (plan.actions.find((entry) => entry.platform === item.id).matrix !== "keep") for (const skill of MATRIX_SKILLS) journal.operations.push({ target: path.join(item.root, skill), backup: null, status: "pending" });
       const persist = () => writeJson(journalFile, journal);
       try {
@@ -205,7 +236,7 @@ export function createDistribution({ failAt, mattAdapter = createMattAdapter() }
         for (const item of refreshed.observations) {
           if (plan.actions.find((entry) => entry.platform === item.id).matrix === "keep") continue;
           const platformStage = path.join(stagingRoot, item.id);
-          for (const skill of MATRIX_SKILLS) { const staged = path.join(platformStage, skill); fs.mkdirSync(path.dirname(staged), { recursive: true }); fs.cpSync(path.join(catalog.root, skill), staged, { recursive: true }); fs.mkdirSync(path.join(staged, "scripts"), { recursive: true }); fs.copyFileSync(workflowRuntimeSource(), path.join(staged, "scripts", "matrix-runtime.mjs")); fs.copyFileSync(workflowTransactionSource(), path.join(staged, "scripts", "workflow-transaction.js")); if (skill === "matrix") for (const filename of ["matrix_state.py", "matrix_claude.py"]) fs.copyFileSync(path.join(sourceSkillsRoot("en"), "matrix", "scripts", filename), path.join(staged, "scripts", filename)); if (!exists(path.join(staged, "SKILL.md"))) throw new Error(`Stage validation failed: ${item.id}/${skill}`); }
+          for (const skill of MATRIX_SKILLS) { const staged = path.join(platformStage, skill); fs.mkdirSync(path.dirname(staged), { recursive: true }); fs.cpSync(path.join(catalog.root, skill), staged, { recursive: true }); fs.mkdirSync(path.join(staged, "scripts"), { recursive: true }); fs.copyFileSync(workflowRuntimeSource(), path.join(staged, "scripts", "matrix-runtime.mjs")); fs.copyFileSync(workflowTransactionSource(), path.join(staged, "scripts", "workflow-transaction.js")); if (skill === "matrix") for (const filename of ["matrix_state.py", "matrix_claude.py"]) fs.copyFileSync(path.join(sourceSkillsRoot("en"), "matrix", "scripts", filename), path.join(staged, "scripts", filename)); if (!exists(path.join(staged, "SKILL.md"))) throw new Error(`Stage validation failed: ${item.id}/${skill}`); }
           stagedPlatforms.set(item.id, platformStage);
         }
         failAt?.("after-stage"); let operationIndex = 0;
@@ -222,34 +253,34 @@ export function createDistribution({ failAt, mattAdapter = createMattAdapter() }
             operation.status = "committed"; persist(); failAt?.("after-commit", { platform: item.id, skill });
           }
         }
-        const mattActions = plan.actions.filter((item) => item.matt.kind === "install-missing"); const mattResults = [];
-        for (const action of mattActions) { const result = mattAdapter.installMissing({ projectRoot: plan.intent.projectRoot, platforms: [action.platform], skills: action.matt.skills, global: plan.intent.scope === "global" }); mattResults.push({ platform: action.platform, ...result }); }
-        const postObservations = plan.intent.platforms.map((platform) => observePlatform(plan.intent, catalog, readManifest(plan.intent), platform));
-        const archRequired = plan.intent.defaultOrchestration === "arch" || readManifest(plan.intent)?.orchestration?.available?.includes("arch");
-        const incomplete = archRequired || mattActions.length ? postObservations.filter((item) => item.matt.state !== "complete") : [];
-        const backups = journal.operations.filter((item) => item.backup).map((item) => ({ target: item.target, backup: item.backup }));
-        if (mattResults.some((item) => !item.ok) || incomplete.length) {
-          const restored = recoverPendingTransaction(plan.intent);
-          return { ok: true, code: "PARTIAL", committed: [], backups: [], recovery: "The platform was not added. Repair the Arch Skill installation and rerun matrix init --with-mattpocock.", matt: mattResults, recoveryReceipt: restored.receipt ?? recovery.receipt };
-        }
-        if (journal.manifest.existed) { journal.manifest.backup = path.join(root, "backups", id, "installation.json"); persist(); fs.mkdirSync(path.dirname(journal.manifest.backup), { recursive: true }); fs.renameSync(plan.manifestPath, journal.manifest.backup); }
-        if (journal.config.existed) { journal.config.backup = path.join(root, "backups", id, "config.yaml"); persist(); fs.mkdirSync(path.dirname(journal.config.backup), { recursive: true }); fs.renameSync(plan.configPath, journal.config.backup); }
-        const records = Object.fromEntries(postObservations.map((item) => [item.id, {
-          root: item.root,
-          skills: Object.fromEntries(MATRIX_SKILLS.map((skill) => [skill, { hash: hashDirectory(path.join(item.root, skill)) }])),
-          matt: { state: item.matt.state, skills: item.matt.skills }
-        }]));
-        const available = postObservations.every((item) => item.matt.state === "complete") ? ["prim", "arch"] : ["prim"];
-        const previousConfig = readConfig(journal.config.backup ?? plan.configPath);
-        fs.mkdirSync(path.dirname(plan.configPath), { recursive: true });
-        fs.writeFileSync(plan.configPath, configContent(previousConfig, plan.intent.defaultOrchestration, plan.intent.scope)); journal.config.written = true; persist();
-        writeJson(plan.manifestPath, {
-          version: VERSION, catalogVersion: catalog.version, language: plan.intent.language, mode: plan.intent.mode, scope: plan.intent.scope,
-          catalogDigest: catalog.digest, orchestration: { default: plan.intent.defaultOrchestration, available }, platforms: records
-        });
-        journal.manifest.written = true; persist(); failAt?.("after-manifest"); journal.state = "committed"; persist();
-        removeStaging(stagingRoot); removeEntry(journal.manifest.backup); removeEntry(journal.config.backup); removeEntry(journalFile);
-        return { ok: true, code: "OK", committed: journal.operations.map((item) => item.target), backups, matt: mattResults, recoveryReceipt: recovery.receipt };
+        const mattActions = plan.actions.filter((item) => item.matt.kind === "install-missing"); const mattResults = [];
+        for (const action of mattActions) { const result = mattAdapter.installMissing({ projectRoot: plan.intent.projectRoot, platforms: [action.platform], skills: action.matt.skills, global: plan.intent.scope === "global" }); mattResults.push({ platform: action.platform, ...result }); }
+        const postObservations = plan.intent.platforms.map((platform) => observePlatform(plan.intent, catalog, readManifest(plan.intent), platform));
+        const archRequired = plan.intent.defaultOrchestration === "arch" || readManifest(plan.intent)?.orchestration?.available?.includes("arch");
+        const incomplete = archRequired || mattActions.length ? postObservations.filter((item) => item.matt.state !== "complete") : [];
+        const backups = journal.operations.filter((item) => item.backup).map((item) => ({ target: item.target, backup: item.backup }));
+        if (mattResults.some((item) => !item.ok) || incomplete.length) {
+          const restored = recoverPendingTransaction(plan.intent);
+          return { ok: true, code: "PARTIAL", committed: [], backups: [], recovery: "The platform was not added. Repair the Arch Skill installation and rerun matrix init --with-mattpocock.", matt: mattResults, recoveryReceipt: restored.receipt ?? recovery.receipt };
+        }
+        if (journal.manifest.existed) { journal.manifest.backup = path.join(root, "backups", id, "installation.json"); persist(); fs.mkdirSync(path.dirname(journal.manifest.backup), { recursive: true }); fs.renameSync(plan.manifestPath, journal.manifest.backup); }
+        if (journal.config.existed) { journal.config.backup = path.join(root, "backups", id, "config.yaml"); persist(); fs.mkdirSync(path.dirname(journal.config.backup), { recursive: true }); fs.renameSync(plan.configPath, journal.config.backup); }
+        const records = Object.fromEntries(postObservations.map((item) => [item.id, {
+          root: item.root,
+          skills: Object.fromEntries(MATRIX_SKILLS.map((skill) => [skill, { hash: hashDirectory(path.join(item.root, skill)) }])),
+          matt: { state: item.matt.state, skills: item.matt.skills }
+        }]));
+        const available = postObservations.every((item) => item.matt.state === "complete") ? ["prim", "arch"] : ["prim"];
+        const previousConfig = readConfig(journal.config.backup ?? plan.configPath);
+        fs.mkdirSync(path.dirname(plan.configPath), { recursive: true });
+        fs.writeFileSync(plan.configPath, configContent(previousConfig, plan.intent.defaultOrchestration, plan.intent.scope, plan.intent.language)); journal.config.written = true; persist();
+        writeJson(plan.manifestPath, {
+          version: VERSION, catalogVersion: catalog.version, language: plan.intent.language, mode: plan.intent.mode, scope: plan.intent.scope,
+          catalogDigest: catalog.digest, orchestration: { default: plan.intent.defaultOrchestration, available }, platforms: records
+        });
+        journal.manifest.written = true; persist(); failAt?.("after-manifest"); journal.state = "committed"; persist();
+        removeStaging(stagingRoot); removeEntry(journal.manifest.backup); removeEntry(journal.config.backup); removeEntry(journalFile);
+        return { ok: true, code: "OK", committed: journal.operations.map((item) => item.target), backups, matt: mattResults, recoveryReceipt: recovery.receipt };
       } catch (error) { const restored = recoverPendingTransaction(plan.intent); return { ok: false, code: "MATRIX_COMMIT_FAILED", error: error.message, recovery: restored.ok ? "Matrix targets and installation manifest were restored." : restored.recovery }; }
     }
   };

package/src/messages.js

@@ -1,13 +1,13 @@
 export const messages = {
   en: {
-    title: "Evidence-driven workflow with Prim and Arch orchestration",
+    title: "Evidence-driven workflow with Prim and Arch orchestration",
     recommended: "Recommended setup", apply: "Apply", customize: "Customize", cancel: "Cancel",
     project: "Project (current directory)", global: "Global (all projects)",
     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",
+    languageQuestion: "Language", scopeQuestion: "Installation scope", platformsQuestion: "Platforms", orchestrationQuestion: "Default orchestration",
     mattQuestion: "Install missing Matt Pocock skills?", replaceQuestion: "Existing Matrix files are not proven managed. Back up and replace?",
     yes: "Yes", no: "No", stateMissing: "missing", stateMatching: "up to date", stateComplete: "complete", stateUserModified: "user-modified", statePartial: "partial", stateOutdated: "outdated",
     actionInstall: "install", actionKeep: "keep", actionBackupReplace: "back up and replace", actionRepair: "repair", actionBlocked: "requires approval",
@@ -15,12 +15,12 @@ export const messages = {
   },
   "zh-CN": {
     manifestMissing: "当前安装范围没有 Matrix 安装清单。", transactionPending: "发现中断的 Matrix 安装事务。请再次运行 matrix init 后再应用新计划。", runtimeMissing: "缺少随附的 Matrix runtime。", brokenLink: "检测到断开的 Matrix 链接。", mattInherited: "Matt skills 由全局安装提供。",
-    languageQuestion: "语言", scopeQuestion: "安装范围", platformsQuestion: "要配置的平台", orchestrationQuestion: "默认编排模式",
+    languageQuestion: "语言", scopeQuestion: "安装范围", platformsQuestion: "要配置的平台", orchestrationQuestion: "默认编排模式",
     mattQuestion: "是否安装缺失的 Matt Pocock skills？", replaceQuestion: "现有 Matrix 文件无法确认由 Matrix 管理。是否备份并替换？",
     yes: "是", no: "否", stateMissing: "未安装", stateMatching: "已是最新", stateComplete: "完整", stateUserModified: "已被用户修改", statePartial: "不完整", stateOutdated: "可更新",
     actionInstall: "安装", actionKeep: "保留", actionBackupReplace: "备份并替换", actionRepair: "修复", actionBlocked: "需要确认",
     dryRunComplete: "预览完成。",
-    title: "提供 Prim 与 Arch 编排的证据驱动工作流",
+    title: "提供 Prim 与 Arch 编排的证据驱动工作流",
     recommended: "推荐配置", apply: "开始安装", customize: "自定义", cancel: "取消",
     project: "项目（当前目录）", global: "全局（所有项目）",
     copy: "复制（推荐）", symlink: "符号链接（高级）",

package/src/self-update.js

@@ -0,0 +1,81 @@
+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"); }

package/src/ui.js

@@ -53,7 +53,7 @@ export function createUi({ color = stdout.isTTY, animate = true } = {}) {
         stdout.write(`\u001b[${bannerLines}A`);
       }
       console.log(paint("cyan", logo));
-      console.log(paint("yellow", "Evidence-driven workflow with Prim and Arch orchestration"));
+      console.log(paint("yellow", "Evidence-driven workflow with Prim and Arch orchestration"));
       console.log();
     },
     info(message) { console.log(`${paint("blue", "> ")} ${message}`); },