@rosenfan/matrix 0.1.1 → 0.1.3

package/src/matt.js

@@ -1,45 +1,45 @@
-import { execFileSync } from "node:child_process";
-import fs from "node:fs";
-import path from "node:path";
-import { PLATFORMS, MATT_SKILLS } from "./catalog.js";
-
-export function buildProcessInvocation({ command, args, platform = process.platform, nodeExecutable = process.execPath, npmCliPath }) {
-  if (platform !== "win32" || command !== "npx") return { executable: command, args, shell: false };
-  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.");
-  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 };
-}
-
-export function defaultProcessRunner({ command, args, cwd, timeout }) {
-  const invocation = buildProcessInvocation({ command, args });
-  return execFileSync(invocation.executable, invocation.args, { cwd, stdio: "inherit", timeout, shell: invocation.shell });
-}
-
-export function createMattAdapter({ run = defaultProcessRunner } = {}) {
-  return {
-    installMissing({ projectRoot, platforms, skills = MATT_SKILLS, global = false, timeout = 300_000 }) {
-      const attempted = [];
-      try {
-        for (const platform of platforms) {
-          const args = ["--yes", "skills@latest", "add", "mattpocock/skills", "--yes", "--agent", PLATFORMS[platform].skillsCliAgent];
-          for (const skill of skills) args.push("--skill", skill);
-          if (global) args.push("--global");
-          run({ command: "npx", args, cwd: projectRoot, timeout });
-          attempted.push(platform);
-        }
-        return { ok: true, code: "OK", attempted };
-      } catch (error) {
-        return {
-          ok: false,
-          code: "MATT_INSTALL_FAILED",
-          attempted,
-          message: error.message,
-          recovery: "Run matrix init --with-mattpocock after resolving the skills CLI error."
-        };
-      }
-    }
-  };
-}
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { PLATFORMS, MATT_SKILLS } from "./catalog.js";
+
+export function buildProcessInvocation({ command, args, platform = process.platform, nodeExecutable = process.execPath, npmCliPath }) {
+  if (platform !== "win32" || command !== "npx") return { executable: command, args, shell: false };
+  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.");
+  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 };
+}
+
+export function defaultProcessRunner({ command, args, cwd, timeout }) {
+  const invocation = buildProcessInvocation({ command, args });
+  return execFileSync(invocation.executable, invocation.args, { cwd, stdio: "inherit", timeout, shell: invocation.shell });
+}
+
+export function createMattAdapter({ run = defaultProcessRunner } = {}) {
+  return {
+    installMissing({ projectRoot, platforms, skills = MATT_SKILLS, global = false, timeout = 300_000 }) {
+      const attempted = [];
+      try {
+        for (const platform of platforms) {
+          const args = ["--yes", "skills@latest", "add", "mattpocock/skills", "--yes", "--agent", PLATFORMS[platform].skillsCliAgent];
+          for (const skill of skills) args.push("--skill", skill);
+          if (global) args.push("--global");
+          run({ command: "npx", args, cwd: projectRoot, timeout });
+          attempted.push(platform);
+        }
+        return { ok: true, code: "OK", attempted };
+      } catch (error) {
+        return {
+          ok: false,
+          code: "MATT_INSTALL_FAILED",
+          attempted,
+          message: error.message,
+          recovery: "Run matrix init --with-mattpocock after resolving the skills CLI error."
+        };
+      }
+    }
+  };
+}

package/src/messages.js

@@ -1,33 +1,33 @@
-export const messages = {
-  en: {
-    title: "Evidence-driven workflow for Matt Pocock's agent skills",
-    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",
-    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",
-    dryRunComplete: "Dry run complete.", 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.", mattInherited: "Matt skills are satisfied by the global installation."
-  },
-  "zh-CN": {
-    manifestMissing: "当前安装范围没有 Matrix 安装清单。", transactionPending: "发现中断的 Matrix 安装事务。请再次运行 matrix init 后再应用新计划。", runtimeMissing: "缺少随附的 Matrix runtime。", brokenLink: "检测到断开的 Matrix 链接。", mattInherited: "Matt skills 由全局安装提供。",
-    languageQuestion: "语言", scopeQuestion: "安装范围", platformsQuestion: "要配置的平台",
-    mattQuestion: "是否安装缺失的 Matt Pocock skills？", replaceQuestion: "现有 Matrix 文件无法确认由 Matrix 管理。是否备份并替换？",
-    yes: "是", no: "否", stateMissing: "未安装", stateMatching: "已是最新", stateComplete: "完整", stateUserModified: "已被用户修改", statePartial: "不完整", stateOutdated: "可更新",
-    actionInstall: "安装", actionKeep: "保留", actionBackupReplace: "备份并替换", actionRepair: "修复", actionBlocked: "需要确认",
-    dryRunComplete: "预览完成。",
-    title: "面向 Matt Pocock Agent Skills 的证据驱动工作流",
-    recommended: "推荐配置", apply: "开始安装", customize: "自定义", cancel: "取消",
-    project: "项目（当前目录）", global: "全局（所有项目）",
-    copy: "复制（推荐）", symlink: "符号链接（高级）",
-    matrix: "Matrix", matt: "Matt Pocock skills", installed: "已安装", ready: "Matrix 已就绪。",
-    noPlatform: "未检测到已验证的平台。请选择 Claude Code、Codex，或两者。",
-    preview: "计划变更", confirm: "确认应用这些变更？", doctor: "安装诊断"
-  }
-};
-
-export function text(language, key) { return messages[language]?.[key] ?? messages.en[key] ?? key; }
+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 (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",
+    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",
+    dryRunComplete: "Dry run complete.", 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.", mattInherited: "Matt skills are satisfied by the global installation."
+  },
+  "zh-CN": {
+    manifestMissing: "当前安装范围没有 Matrix 安装清单。", transactionPending: "发现中断的 Matrix 安装事务。请再次运行 matrix init 后再应用新计划。", runtimeMissing: "缺少随附的 Matrix runtime。", brokenLink: "检测到断开的 Matrix 链接。", mattInherited: "Matt skills 由全局安装提供。",
+    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 编排的证据驱动工作流",
+    recommended: "推荐配置", apply: "开始安装", customize: "自定义", cancel: "取消",
+    project: "项目（当前目录）", global: "全局（所有项目）",
+    copy: "复制（推荐）", symlink: "符号链接（高级）",
+    matrix: "Matrix", matt: "Matt Pocock skills", installed: "已安装", ready: "Matrix 已就绪。",
+    noPlatform: "未检测到已验证的平台。请选择 Claude Code、Codex，或两者。",
+    preview: "计划变更", confirm: "确认应用这些变更？", doctor: "安装诊断"
+  }
+};
+
+export function text(language, key) { return messages[language]?.[key] ?? messages.en[key] ?? key; }

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

@@ -1,89 +1,89 @@
-import readline from "node:readline";
-import { stdin, stdout } from "node:process";
-
-const codes = { cyan: "\u001b[96m", blue: "\u001b[94m", green: "\u001b[92m", yellow: "\u001b[93m", magenta: "\u001b[95m", dim: "\u001b[2m", reset: "\u001b[0m" };
-const pause = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
-const logo = String.raw`███╗   ███╗ █████╗ ████████╗██████╗ ██╗██╗  ██╗
-████╗ ████║██╔══██╗╚══██╔══╝██╔══██╗██║╚██╗██╔╝
-██╔████╔██║███████║   ██║   ██████╔╝██║ ╚███╔╝
-██║╚██╔╝██║██╔══██║   ██║   ██╔══██╗██║ ██╔██╗
-██║ ╚═╝ ██║██║  ██║   ██║   ██║  ██║██║██╔╝ ██╗
-╚═╝     ╚═╝╚═╝  ╚═╝   ╚═╝   ╚═╝  ╚═╝╚═╝╚═╝  ╚═╝`;
-const bannerLines = 9;
-
-function cancelled() {
-  const error = new Error("Cancelled.");
-  error.code = "CANCELLED";
-  return error;
-}
-
-export function createUi({ color = stdout.isTTY, animate = true } = {}) {
-  const paint = (name, value) => color ? `${codes[name]}${value}${codes.reset}` : value;
-  const shouldAnimate = animate && color && stdout.isTTY;
-  const writeFrame = (stage, status, clearPrevious = false) => {
-    if (clearPrevious) stdout.write(`\u001b[${bannerLines}A`);
-    stdout.write("\u001b[2K" + paint("green", `[ MATRIX BOOT // ${status} ]`) + "\n");
-    for (const line of logo.split("\n")) {
-      const reveal = Math.floor(line.length * stage);
-      const stable = line.slice(0, reveal);
-      const interference = stage === 1 ? "" : "#@%/\\|~".repeat(Math.ceil((line.length - reveal) / 7)).slice(0, line.length - reveal);
-      stdout.write("\u001b[2K" + paint(stage < 0.7 ? "green" : "cyan", stable + interference) + "\n");
-    }
-    stdout.write("\u001b[2K" + paint("yellow", `    ${Math.round(stage * 100)}%  ${status}`) + "\n\n");
-  };
-  return {
-    async banner() {
-      if (shouldAnimate) {
-        const sequence = [
-          [0.04, "SIGNAL LOST", 260],
-          [0.28, "MAGNETIC INTERFERENCE", 320],
-          [0.62, "NEURAL LINK FORMING", 360],
-          [1, "SIGNAL LOCKED", 420]
-        ];
-        stdout.write("\u001b[?25l");
-        try {
-          for (let index = 0; index < sequence.length; index += 1) {
-            const [stage, status, duration] = sequence[index];
-            writeFrame(stage, status, index > 0);
-            await pause(duration);
-          }
-        } finally {
-          stdout.write("\u001b[?25h");
-        }
-        stdout.write(`\u001b[${bannerLines}A`);
-      }
-      console.log(paint("cyan", logo));
-      console.log(paint("yellow", "Evidence-driven workflow for Matt Pocock's agent skills"));
-      console.log();
-    },
-    info(message) { console.log(`${paint("blue", "> ")} ${message}`); },
-    success(message) { console.log(`${paint("green", "OK")} ${message}`); },
-    warn(message) { console.log(`${paint("yellow", "!")} ${message}`); },
-    muted(message) { console.log(paint("dim", message)); },
-    async select(question, choices, initial = 0) {
-      if (!stdin.isTTY || !stdout.isTTY) return choices[initial].value;
-      let selected = initial;
-      readline.emitKeypressEvents(stdin); const wasRaw = stdin.isRaw; stdin.setRawMode(true); stdin.resume(); stdout.write(`? ${question}\n`);
-      const render = (clear = false) => { if (clear) stdout.write(`\u001b[${choices.length}A`); choices.forEach((choice, index) => { stdout.write("\u001b[2K"); stdout.write(`${index === selected ? paint("blue", ">") : " "} ${index === selected ? paint("blue", choice.label) : choice.label}\n`); }); };
-      render();
-      return new Promise((resolve, reject) => {
-        const cleanup = () => { stdin.off("keypress", onKeypress); stdin.setRawMode(Boolean(wasRaw)); stdin.pause(); };
-        const onKeypress = (_value, key = {}) => { if (key.ctrl && key.name === "c") { cleanup(); reject(cancelled()); } else if (["up", "k"].includes(key.name)) { selected = (selected - 1 + choices.length) % choices.length; render(true); } else if (["down", "j"].includes(key.name)) { selected = (selected + 1) % choices.length; render(true); } else if (key.name === "return") { cleanup(); resolve(choices[selected].value); } };
-        stdin.on("keypress", onKeypress);
-      });
-    },
-    async selectMany(question, choices) {
-      if (!stdin.isTTY || !stdout.isTTY) return choices.map((choice) => choice.value);
-      let selected = 0; const checked = new Set(choices.map((choice) => choice.value));
-      readline.emitKeypressEvents(stdin); const wasRaw = stdin.isRaw; stdin.setRawMode(true); stdin.resume(); stdout.write(`? ${question}\n`);
-      const render = (clear = false) => { if (clear) stdout.write(`\u001b[${choices.length}A`); choices.forEach((choice, index) => { stdout.write("\u001b[2K"); const marker = checked.has(choice.value) ? "[x]" : "[ ]"; stdout.write(`${index === selected ? paint("blue", ">") : " "} ${marker} ${index === selected ? paint("blue", choice.label) : choice.label}\n`); }); };
-      render();
-      return new Promise((resolve, reject) => {
-        const cleanup = () => { stdin.off("keypress", onKeypress); stdin.setRawMode(Boolean(wasRaw)); stdin.pause(); };
-        const onKeypress = (_value, key = {}) => { if (key.ctrl && key.name === "c") { cleanup(); reject(cancelled()); } else if (["up", "k"].includes(key.name)) { selected = (selected - 1 + choices.length) % choices.length; render(true); } else if (["down", "j"].includes(key.name)) { selected = (selected + 1) % choices.length; render(true); } else if (key.name === "space") { const value = choices[selected].value; checked.has(value) ? checked.delete(value) : checked.add(value); render(true); } else if (key.name === "return") { cleanup(); resolve(choices.filter((choice) => checked.has(choice.value)).map((choice) => choice.value)); } };
-        stdin.on("keypress", onKeypress);
-      });
-    },
-    async confirm(question, defaultValue = true, labels = { yes: "Yes", no: "No" }) { return this.select(question, [{ label: defaultValue ? labels.yes : labels.no, value: defaultValue }, { label: defaultValue ? labels.no : labels.yes, value: !defaultValue }]); }
-  };
-}
+import readline from "node:readline";
+import { stdin, stdout } from "node:process";
+
+const codes = { cyan: "\u001b[96m", blue: "\u001b[94m", green: "\u001b[92m", yellow: "\u001b[93m", magenta: "\u001b[95m", dim: "\u001b[2m", reset: "\u001b[0m" };
+const pause = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+const logo = String.raw`███╗   ███╗ █████╗ ████████╗██████╗ ██╗██╗  ██╗
+████╗ ████║██╔══██╗╚══██╔══╝██╔══██╗██║╚██╗██╔╝
+██╔████╔██║███████║   ██║   ██████╔╝██║ ╚███╔╝
+██║╚██╔╝██║██╔══██║   ██║   ██╔══██╗██║ ██╔██╗
+██║ ╚═╝ ██║██║  ██║   ██║   ██║  ██║██║██╔╝ ██╗
+╚═╝     ╚═╝╚═╝  ╚═╝   ╚═╝   ╚═╝  ╚═╝╚═╝╚═╝  ╚═╝`;
+const bannerLines = 9;
+
+function cancelled() {
+  const error = new Error("Cancelled.");
+  error.code = "CANCELLED";
+  return error;
+}
+
+export function createUi({ color = stdout.isTTY, animate = true } = {}) {
+  const paint = (name, value) => color ? `${codes[name]}${value}${codes.reset}` : value;
+  const shouldAnimate = animate && color && stdout.isTTY;
+  const writeFrame = (stage, status, clearPrevious = false) => {
+    if (clearPrevious) stdout.write(`\u001b[${bannerLines}A`);
+    stdout.write("\u001b[2K" + paint("green", `[ MATRIX BOOT // ${status} ]`) + "\n");
+    for (const line of logo.split("\n")) {
+      const reveal = Math.floor(line.length * stage);
+      const stable = line.slice(0, reveal);
+      const interference = stage === 1 ? "" : "#@%/\\|~".repeat(Math.ceil((line.length - reveal) / 7)).slice(0, line.length - reveal);
+      stdout.write("\u001b[2K" + paint(stage < 0.7 ? "green" : "cyan", stable + interference) + "\n");
+    }
+    stdout.write("\u001b[2K" + paint("yellow", `    ${Math.round(stage * 100)}%  ${status}`) + "\n\n");
+  };
+  return {
+    async banner() {
+      if (shouldAnimate) {
+        const sequence = [
+          [0.04, "SIGNAL LOST", 260],
+          [0.28, "MAGNETIC INTERFERENCE", 320],
+          [0.62, "NEURAL LINK FORMING", 360],
+          [1, "SIGNAL LOCKED", 420]
+        ];
+        stdout.write("\u001b[?25l");
+        try {
+          for (let index = 0; index < sequence.length; index += 1) {
+            const [stage, status, duration] = sequence[index];
+            writeFrame(stage, status, index > 0);
+            await pause(duration);
+          }
+        } finally {
+          stdout.write("\u001b[?25h");
+        }
+        stdout.write(`\u001b[${bannerLines}A`);
+      }
+      console.log(paint("cyan", logo));
+      console.log(paint("yellow", "Evidence-driven workflow with Prim and Arch orchestration"));
+      console.log();
+    },
+    info(message) { console.log(`${paint("blue", "> ")} ${message}`); },
+    success(message) { console.log(`${paint("green", "OK")} ${message}`); },
+    warn(message) { console.log(`${paint("yellow", "!")} ${message}`); },
+    muted(message) { console.log(paint("dim", message)); },
+    async select(question, choices, initial = 0) {
+      if (!stdin.isTTY || !stdout.isTTY) return choices[initial].value;
+      let selected = initial;
+      readline.emitKeypressEvents(stdin); const wasRaw = stdin.isRaw; stdin.setRawMode(true); stdin.resume(); stdout.write(`? ${question}\n`);
+      const render = (clear = false) => { if (clear) stdout.write(`\u001b[${choices.length}A`); choices.forEach((choice, index) => { stdout.write("\u001b[2K"); stdout.write(`${index === selected ? paint("blue", ">") : " "} ${index === selected ? paint("blue", choice.label) : choice.label}\n`); }); };
+      render();
+      return new Promise((resolve, reject) => {
+        const cleanup = () => { stdin.off("keypress", onKeypress); stdin.setRawMode(Boolean(wasRaw)); stdin.pause(); };
+        const onKeypress = (_value, key = {}) => { if (key.ctrl && key.name === "c") { cleanup(); reject(cancelled()); } else if (["up", "k"].includes(key.name)) { selected = (selected - 1 + choices.length) % choices.length; render(true); } else if (["down", "j"].includes(key.name)) { selected = (selected + 1) % choices.length; render(true); } else if (key.name === "return") { cleanup(); resolve(choices[selected].value); } };
+        stdin.on("keypress", onKeypress);
+      });
+    },
+    async selectMany(question, choices) {
+      if (!stdin.isTTY || !stdout.isTTY) return choices.map((choice) => choice.value);
+      let selected = 0; const checked = new Set(choices.map((choice) => choice.value));
+      readline.emitKeypressEvents(stdin); const wasRaw = stdin.isRaw; stdin.setRawMode(true); stdin.resume(); stdout.write(`? ${question}\n`);
+      const render = (clear = false) => { if (clear) stdout.write(`\u001b[${choices.length}A`); choices.forEach((choice, index) => { stdout.write("\u001b[2K"); const marker = checked.has(choice.value) ? "[x]" : "[ ]"; stdout.write(`${index === selected ? paint("blue", ">") : " "} ${marker} ${index === selected ? paint("blue", choice.label) : choice.label}\n`); }); };
+      render();
+      return new Promise((resolve, reject) => {
+        const cleanup = () => { stdin.off("keypress", onKeypress); stdin.setRawMode(Boolean(wasRaw)); stdin.pause(); };
+        const onKeypress = (_value, key = {}) => { if (key.ctrl && key.name === "c") { cleanup(); reject(cancelled()); } else if (["up", "k"].includes(key.name)) { selected = (selected - 1 + choices.length) % choices.length; render(true); } else if (["down", "j"].includes(key.name)) { selected = (selected + 1) % choices.length; render(true); } else if (key.name === "space") { const value = choices[selected].value; checked.has(value) ? checked.delete(value) : checked.add(value); render(true); } else if (key.name === "return") { cleanup(); resolve(choices.filter((choice) => checked.has(choice.value)).map((choice) => choice.value)); } };
+        stdin.on("keypress", onKeypress);
+      });
+    },
+    async confirm(question, defaultValue = true, labels = { yes: "Yes", no: "No" }) { return this.select(question, [{ label: defaultValue ? labels.yes : labels.no, value: defaultValue }, { label: defaultValue ? labels.no : labels.yes, value: !defaultValue }]); }
+  };
+}