@tiens.nguyen/gu-cli 1.0.884 → 1.0.886

package/skill-install.mjs

@@ -0,0 +1,563 @@
+#!/usr/bin/env node
+/**
+ * INSTALL A PACKED SKILL (#281) — the other half of /skill-pack (skill-package.mjs).
+ *
+ * This one file is BOTH gu's installer (/skill-install imports it) AND the install.mjs that ships
+ * inside every package, so a machine without gu can still run `node install.mjs`. It must stay
+ * self-contained: Node 18+ built-ins only, no imports from the rest of gu.
+ *
+ * A package (a zip, or the same files unzipped):
+ *   <name>/install.mjs     this file
+ *   <name>/skill.json      the manifest (below)
+ *   <name>/skill/…         the skill's folder: SKILL.md and whatever sits next to it
+ *   <name>/runtime/…       optional — the code its MCP servers and hooks run (lived outside the
+ *                          skill folder on the machine it was packed on)
+ *
+ *   skill.json = { format: 1, name, description, python?: { requirements: "requirements.txt" },
+ *                  mcpServers?: { <server>: { command, args, env } },
+ *                  hooks?: { <Claude event>: [ { matcher, hooks: [ { type, command, args, timeout } ] } ] },
+ *                  env?: [names asked for at install], notes?: [ … ] }
+ *
+ * Paths in the manifest and in the packed text files are placeholders, filled in here:
+ *   {{SKILL}}    the skill's folder (one per tool: ~/.gonext/skills/<name>, ~/.claude/skills/<name>)
+ *   {{RUNTIME}}  <base>/skill-runtime/<name>, <base> = ~/.gonext if gu is a target, else ~/.claude
+ *   {{PYTHON}}   the runtime's own venv python (built here from requirements.txt), else python3
+ *   {{HOME}}     the home folder;  {{ENV:NAME}}  NAME from the terminal's environment (never packed)
+ *
+ * Hooks are written in Claude Code's vocabulary. Claude gets them as they are, in
+ * ~/.claude/settings.json; gu gets them under its own event names with dialect "claude", so gu
+ * speaks Claude's input format to the same script (gu_hooks.py). A hook from an older install of
+ * the same script (same path inside the runtime) is replaced, not doubled.
+ *
+ * Nothing is overwritten without a copy: a skill folder, runtime or settings file that changes is
+ * first copied to <base>/skill-backups/<name>-<time>/. A config file that is not valid JSON is
+ * refused, never "repaired".
+ */
+import { spawnSync } from "node:child_process";
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { inflateRawSync } from "node:zlib";
+
+export const FORMAT = 1;
+export const MANIFEST = "skill.json";
+export const NAME_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+export const TARGETS = ["gu", "claude"];
+/** Claude Code's hook events → gu's moments (hooks-config.mjs has the same table). */
+export const CLAUDE_TO_GU = { SessionStart: "onStart", UserPromptSubmit: "onAsk", PostToolUse: "onToolDone", Stop: "onTurnEnd" };
+/** Claude Code events gu has no moment for: installed for Claude Code only (#284). */
+export const CLAUDE_ONLY_EVENTS = ["SessionEnd", "PreCompact"];
+
+const isObj = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+const slash = (p) => String(p).replace(/\\/g, "/");
+
+// ---- zip (read) --------------------------------------------------------------------------------
+
+const CRC_TABLE = (() => {
+  const t = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    t[n] = c >>> 0;
+  }
+  return t;
+})();
+export function crc32(buf) {
+  let c = 0xffffffff;
+  for (let i = 0; i < buf.length; i++) c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+/** A path inside a package: relative, forward slashes, no "..", nothing absolute. */
+export function safeRel(p) {
+  const s = slash(p).replace(/^\.\//, "");
+  if (!s || s.startsWith("/") || /^[A-Za-z]:/.test(s) || s.split("/").some((x) => x === ".." || x === "")) return null;
+  return s;
+}
+
+/** A zip's files → Map<path, { data, mode }>. Folders are left out; a damaged entry throws. */
+export function readZip(buf) {
+  let end = -1;
+  for (let i = buf.length - 22; i >= Math.max(0, buf.length - 22 - 65535); i--) {
+    if (buf.readUInt32LE(i) === 0x06054b50) {
+      end = i;
+      break;
+    }
+  }
+  if (end < 0) throw new Error("not a zip file");
+  const count = buf.readUInt16LE(end + 10);
+  let at = buf.readUInt32LE(end + 16);
+  const files = new Map();
+  for (let n = 0; n < count; n++) {
+    if (buf.readUInt32LE(at) !== 0x02014b50) throw new Error("the zip's file list is damaged");
+    const method = buf.readUInt16LE(at + 10);
+    const crc = buf.readUInt32LE(at + 16);
+    const size = buf.readUInt32LE(at + 20);
+    const nameLen = buf.readUInt16LE(at + 28);
+    const extraLen = buf.readUInt16LE(at + 30);
+    const commentLen = buf.readUInt16LE(at + 32);
+    const attrs = buf.readUInt32LE(at + 38);
+    const local = buf.readUInt32LE(at + 42);
+    const name = buf.toString("utf8", at + 46, at + 46 + nameLen);
+    at += 46 + nameLen + extraLen + commentLen;
+    if (name.endsWith("/")) continue;
+    const rel = safeRel(name);
+    if (!rel) throw new Error(`the zip has an unsafe path: ${name}`);
+    const start = local + 30 + buf.readUInt16LE(local + 26) + buf.readUInt16LE(local + 28);
+    const packed = buf.subarray(start, start + size);
+    const data = method === 8 ? inflateRawSync(packed) : method === 0 ? Buffer.from(packed) : null;
+    if (!data) throw new Error(`${name}: compression method ${method} is not supported`);
+    if (crc32(data) !== crc) throw new Error(`${name} is damaged (CRC mismatch)`);
+    files.set(rel, { data, mode: (attrs >>> 16) & 0o777 });
+  }
+  return files;
+}
+
+function readTree(dir, base = dir, out = new Map()) {
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) readTree(p, base, out);
+    else if (e.isFile()) out.set(slash(p.slice(base.length + 1)), { data: readFileSync(p), mode: statSync(p).mode & 0o777 });
+  }
+  return out;
+}
+
+// ---- the package -------------------------------------------------------------------------------
+
+/** Check a manifest; → list of problems (empty = fine). */
+export function manifestProblems(m) {
+  const out = [];
+  if (!isObj(m)) return ["skill.json is not a JSON object"];
+  if (m.format !== FORMAT) out.push(`skill.json format ${m.format} — this installer reads format ${FORMAT}`);
+  if (!NAME_RE.test(String(m.name ?? ""))) out.push(`"${m.name}" is not a valid skill name`);
+  if (m.mcpServers !== undefined && !isObj(m.mcpServers)) out.push("mcpServers must be an object");
+  for (const [k, v] of Object.entries(isObj(m.mcpServers) ? m.mcpServers : {})) {
+    if (!/^[A-Za-z0-9_-]{1,64}$/.test(k)) out.push(`MCP server name "${k}" is not valid`);
+    if (!isObj(v) || !String(v.command ?? "").trim()) out.push(`MCP server "${k}" has no command`);
+  }
+  if (m.hooks !== undefined && !isObj(m.hooks)) out.push("hooks must be an object");
+  for (const ev of Object.keys(isObj(m.hooks) ? m.hooks : {})) {
+    if (!(ev in CLAUDE_TO_GU) && !CLAUDE_ONLY_EVENTS.includes(ev)) out.push(`hook event "${ev}" is not one this installer knows (${[...Object.keys(CLAUDE_TO_GU), ...CLAUDE_ONLY_EVENTS].join(", ")})`);
+  }
+  if (m.python !== undefined && !(isObj(m.python) && safeRel(m.python.requirements ?? ""))) out.push("python.requirements must name a file in runtime/");
+  return out;
+}
+
+/**
+ * A package from a zip or a folder → { manifest, skill: Map, runtime: Map }. Accepts the folder
+ * itself or a zip whose files sit under one top folder (as /skill-pack writes them).
+ */
+export function loadPackage(src) {
+  const st = statSync(src);
+  let files = st.isDirectory() ? readTree(src) : readZip(readFileSync(src));
+  if (!files.has(MANIFEST)) {
+    const tops = new Set([...files.keys()].map((k) => k.split("/")[0]));
+    const top = tops.size === 1 ? [...tops][0] : null;
+    if (!top || !files.has(`${top}/${MANIFEST}`)) throw new Error(`no ${MANIFEST} in ${src} — is it a gu skill package?`);
+    files = new Map([...files].map(([k, v]) => [k.slice(top.length + 1), v]));
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(files.get(MANIFEST).data.toString("utf8"));
+  } catch (e) {
+    throw new Error(`${MANIFEST} is not valid JSON (${e.message})`);
+  }
+  const problems = manifestProblems(manifest);
+  if (problems.length) throw new Error(problems.join("; "));
+  const part = (prefix) => new Map([...files].filter(([k]) => k.startsWith(prefix)).map(([k, v]) => [k.slice(prefix.length), v]));
+  const skill = part("skill/");
+  if (!skill.has("SKILL.md")) throw new Error("the package has no skill/SKILL.md");
+  const runtime = part("runtime/");
+  if (manifest.python && !runtime.has(manifest.python.requirements)) throw new Error(`runtime/${manifest.python.requirements} is missing`);
+  return { manifest, skill, runtime };
+}
+
+// ---- placeholders ------------------------------------------------------------------------------
+
+/** Fill {{SKILL}} {{RUNTIME}} {{PYTHON}} {{HOME}} {{ENV:X}} in one string. */
+export function fill(s, vars) {
+  return String(s).replace(/\{\{(SKILL|RUNTIME|PYTHON|HOME|ENV:([A-Za-z_][A-Za-z0-9_]*))\}\}/g, (all, k, env) =>
+    env ? (vars.env?.[env] ?? "") : vars[k.toLowerCase()] ?? all
+  );
+}
+const isText = (buf) => !buf.subarray(0, 8192).includes(0);
+/** Text files get placeholders filled with forward-slash paths (safe inside Python/JS strings on Windows too). */
+function fillFile(f, vars) {
+  if (!isText(f.data)) return f.data;
+  const text = f.data.toString("utf8");
+  if (!text.includes("{{")) return f.data;
+  const v = { ...vars, skill: slash(vars.skill), runtime: slash(vars.runtime), python: slash(vars.python), home: slash(vars.home) };
+  return Buffer.from(fill(text, v), "utf8");
+}
+const fillDeep = (v, vars) =>
+  typeof v === "string" ? fill(v, vars) : Array.isArray(v) ? v.map((x) => fillDeep(x, vars)) : isObj(v) ? Object.fromEntries(Object.entries(v).map(([k, x]) => [k, fillDeep(x, vars)])) : v;
+
+/** Every {{ENV:X}} the manifest uses. */
+export function envNames(manifest) {
+  const names = new Set(Array.isArray(manifest.env) ? manifest.env.map(String) : []);
+  for (const m of JSON.stringify(manifest).matchAll(/\{\{ENV:([A-Za-z_][A-Za-z0-9_]*)\}\}/g)) names.add(m[1]);
+  return [...names];
+}
+
+// ---- config files ------------------------------------------------------------------------------
+
+function readJsonFile(file) {
+  if (!existsSync(file)) return { data: {} };
+  try {
+    const data = JSON.parse(readFileSync(file, "utf8") || "{}");
+    return isObj(data) ? { data } : { error: "not a JSON object" };
+  } catch (e) {
+    return { error: `not valid JSON (${e.message})` };
+  }
+}
+function writeJsonFile(file, data) {
+  mkdirSync(dirname(file), { recursive: true });
+  let mode = 0o600;
+  try {
+    mode = statSync(file).mode & 0o777;
+  } catch {
+    /* new file: private */
+  }
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, JSON.stringify(data, null, 2) + "\n", { encoding: "utf8", mode });
+  renameSync(tmp, file);
+}
+const sameJson = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+/** The path a hook runs, inside its package: "hooks/memory_hook.py" for "{{RUNTIME}}/hooks/memory_hook.py". */
+function hookKey(h) {
+  for (const a of [h.command, ...(Array.isArray(h.args) ? h.args : [])]) {
+    const m = String(a).match(/\{\{(?:RUNTIME|SKILL)\}\}[\\/](.+)$/);
+    if (m) return slash(m[1]);
+  }
+  return null;
+}
+/** Does an installed hook run the same script (by its path inside the runtime/skill)? */
+function runsSame(installed, key) {
+  if (!key) return false;
+  return [installed.command, ...(Array.isArray(installed.args) ? installed.args : [])].some((a) => slash(a).endsWith("/" + key));
+}
+
+/**
+ * Add `groups` under `event` in a hooks object: an installed group running the same script is
+ * replaced (an older install, maybe from another folder); an identical one is left alone.
+ * → { hooks, replaced: [paths], added: n }
+ */
+export function mergeHooks(existing, event, groups, extra = {}) {
+  const hooks = isObj(existing) ? structuredClone(existing) : {};
+  const list = Array.isArray(hooks[event]) ? hooks[event] : [];
+  const replaced = [];
+  let added = 0;
+  for (const g of groups) {
+    const want = { matcher: g.matcher ?? "", hooks: g.hooks, ...extra };
+    if (list.some((x) => sameJson(x, want))) continue;
+    const keys = (g.keys ?? []).filter(Boolean);
+    for (let i = list.length - 1; i >= 0; i--) {
+      const hs = Array.isArray(list[i]?.hooks) ? list[i].hooks : [];
+      if (hs.length && hs.every((h) => keys.some((k) => runsSame(h, k)))) {
+        replaced.push(...hs.map((h) => [h.command, ...(h.args ?? [])].join(" ")));
+        list.splice(i, 1);
+      }
+    }
+    list.push(want);
+    added++;
+  }
+  hooks[event] = list;
+  return { hooks, replaced, added };
+}
+
+// ---- the plan ----------------------------------------------------------------------------------
+
+const venvPython = (dir, platform) => (platform === "win32" ? join(dir, ".venv", "Scripts", "python.exe") : join(dir, ".venv", "bin", "python"));
+
+function sameTree(files, dir, vars) {
+  if (!existsSync(dir)) return false;
+  let have;
+  try {
+    have = readTree(dir);
+  } catch {
+    return false;
+  }
+  for (const [k, f] of files) if (!have.has(k) || !have.get(k).data.equals(fillFile(f, vars))) return false;
+  return true;
+}
+
+/**
+ * What installing `pkg` would do → a plan for applyInstall and for showing the user. `targets`
+ * left out = every tool that is on this machine (its folder exists).
+ */
+export function planInstall(pkg, { home = homedir(), targets, platform = process.platform, env = process.env } = {}) {
+  const { manifest: m } = pkg;
+  const name = m.name;
+  const found = TARGETS.filter((t) => existsSync(join(home, t === "gu" ? ".gonext" : ".claude")));
+  const use = targets?.length ? targets : found;
+  if (!use.length) throw new Error("neither gu (~/.gonext) nor Claude Code (~/.claude) is set up here — pass --gu or --claude");
+  const base = join(home, use.includes("gu") ? ".gonext" : ".claude");
+  const runtime = join(base, "skill-runtime", name);
+  // platform-ok: only for a package whose command is {{PYTHON}} with no venv — "python" on Windows (not the Store stub's name).
+  const python = m.python ? venvPython(runtime, platform) : platform === "win32" ? "python" : "python3";
+  const envValues = {};
+  const missingEnv = [];
+  for (const k of envNames(m)) {
+    if (env[k]) envValues[k] = env[k];
+    else missingEnv.push(k);
+  }
+  const warnings = [];
+  const items = [];
+  const runtimeVars = { skill: join(home, ".gonext", "skills", name), runtime, python, home, env: envValues };
+  const runtimeStatus = !pkg.runtime.size ? "same" : sameTree(pkg.runtime, runtime, runtimeVars) ? "same" : existsSync(runtime) ? "differs" : "new";
+  if (pkg.runtime.size) items.push({ kind: "runtime", to: runtime, status: runtimeStatus, files: pkg.runtime.size });
+  // The venv is (re)built when it is missing or the runtime (so maybe requirements.txt) changed.
+  if (m.python) items.push({ kind: "python", to: runtime, requirements: m.python.requirements, status: runtimeStatus === "same" && existsSync(python) ? "same" : "new" });
+  for (const t of use) {
+    const dot = t === "gu" ? ".gonext" : ".claude";
+    const skillDir = join(home, dot, "skills", name);
+    const vars = { skill: skillDir, runtime, python, home, env: envValues };
+    items.push({ kind: "skill", target: t, to: skillDir, vars, status: sameTree(pkg.skill, skillDir, vars) ? "same" : existsSync(skillDir) ? "differs" : "new" });
+
+    const servers = isObj(m.mcpServers) ? m.mcpServers : {};
+    if (Object.keys(servers).length) {
+      const file = t === "gu" ? join(home, ".gonext", "mcp.json") : join(home, ".claude.json");
+      const cur = readJsonFile(file);
+      if (cur.error) warnings.push(`${file} is ${cur.error} — its MCP servers are left alone`);
+      for (const [sname, entry] of Object.entries(servers)) {
+        const want = fillDeep({ command: entry.command, args: entry.args ?? [], ...(isObj(entry.env) && Object.keys(entry.env).length ? { env: entry.env } : {}) }, vars);
+        if (t === "claude") want.type = "stdio";
+        const have = cur.data?.mcpServers?.[sname];
+        items.push({ kind: "server", target: t, name: sname, file, entry: want, blocked: !!cur.error, status: !have ? "new" : sameJson(have, want) ? "same" : "differs" });
+      }
+    }
+
+    const hookDefs = isObj(m.hooks) ? m.hooks : {};
+    if (Object.keys(hookDefs).length) {
+      const file = join(home, dot, "settings.json");
+      const cur = readJsonFile(file);
+      if (cur.error) warnings.push(`${file} is ${cur.error} — no hooks are added to it`);
+      let hooks = cur.data?.hooks ?? {};
+      const replaced = [];
+      let added = 0;
+      const events = [];
+      for (const [ev, groups] of Object.entries(hookDefs)) {
+        if (t === "gu" && !(ev in CLAUDE_TO_GU)) continue; // a Claude-only event: gu never fires it
+        events.push(ev);
+        const filled = (Array.isArray(groups) ? groups : []).map((g) => ({
+          matcher: g.matcher ?? "",
+          hooks: fillDeep(g.hooks ?? [], vars),
+          keys: (g.hooks ?? []).map(hookKey),
+        }));
+        const r = mergeHooks(hooks, t === "gu" ? CLAUDE_TO_GU[ev] : ev, filled, t === "gu" ? { dialect: "claude" } : {});
+        hooks = r.hooks;
+        replaced.push(...r.replaced);
+        added += r.added;
+      }
+      items.push({ kind: "hooks", target: t, file, hooks, events, replaced, blocked: !!cur.error, status: added ? (replaced.length ? "differs" : "new") : "same" });
+    }
+  }
+  return { name, manifest: m, pkg, home, base, runtime, python, targets: use, items, missingEnv, warnings, notes: Array.isArray(m.notes) ? m.notes.map(String) : [] };
+}
+
+// ---- doing it ----------------------------------------------------------------------------------
+
+function writeFiles(dir, files, vars) {
+  for (const [rel, f] of files) {
+    const p = join(dir, ...rel.split("/"));
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, fillFile(f, vars));
+    if (f.mode & 0o111) chmodSync(p, f.mode | 0o600);
+  }
+}
+function copyTree(from, to, skip = new Set()) {
+  mkdirSync(to, { recursive: true });
+  for (const e of readdirSync(from, { withFileTypes: true })) {
+    if (skip.has(e.name)) continue;
+    const a = join(from, e.name), b = join(to, e.name);
+    if (e.isDirectory()) copyTree(a, b);
+    else if (e.isFile()) copyFileSync(a, b);
+  }
+}
+
+/** A Python 3.9+ on this machine → [command, ...args] or null. Windows' Store stub fails the check. */
+export function findPython({ platform = process.platform, run = spawnSync } = {}) {
+  // platform-ok: this IS the resolver — install.mjs ships alone and cannot import platform-tools.mjs. Each candidate is run and version-checked, so the Store stub fails.
+  const tries = platform === "win32" ? [["py", "-3"], ["python"], ["python3"]] : [["python3"], ["python"]];
+  for (const [cmd, ...args] of tries) {
+    const r = run(cmd, [...args, "-c", "import sys; print('%d.%d' % sys.version_info[:2])"], { encoding: "utf8" });
+    const v = String(r.stdout ?? "").trim().match(/^(\d+)\.(\d+)$/);
+    if (r.status === 0 && v && (+v[1] > 3 || (+v[1] === 3 && +v[2] >= 9))) return [cmd, ...args];
+  }
+  return null;
+}
+
+/**
+ * Carry out a plan. `say(line)` reports progress. → { done: [lines], errors: [lines], backups }.
+ * Order: runtime, its venv, then each tool's skill, MCP servers and hooks. A failed venv stops
+ * before anything points at it.
+ */
+export function applyInstall(plan, { say = () => {}, run = spawnSync, now = new Date() } = {}) {
+  const done = [];
+  const errors = [];
+  const stamp = now.toISOString().replace(/[:.]/g, "-");
+  const backupDir = join(plan.base, "skill-backups", `${plan.name}-${stamp}`);
+  let backedUp = false;
+  const backup = (p, label) => {
+    if (!existsSync(p)) return;
+    const dest = join(backupDir, label);
+    mkdirSync(dirname(dest), { recursive: true });
+    if (statSync(p).isDirectory()) copyTree(p, dest, new Set([".venv", "__pycache__"]));
+    else copyFileSync(p, dest);
+    backedUp = true;
+  };
+
+  for (const it of plan.items) {
+    try {
+      if (it.kind === "runtime" && it.status !== "same") {
+        backup(it.to, "runtime");
+        writeFiles(it.to, plan.pkg.runtime, { skill: join(plan.home, ".gonext", "skills", plan.name), runtime: plan.runtime, python: plan.python, home: plan.home, env: {} });
+        done.push(`runtime → ${it.to}`);
+      } else if (it.kind === "python" && it.status !== "same") {
+        const py = findPython({ run });
+        if (!py) throw new Error("Python 3.9 or newer is needed for this skill and none was found (install it, then run this again)");
+        if (!existsSync(plan.python)) {
+          say(`  making a Python venv in ${join(it.to, ".venv")} …`);
+          const v = run(py[0], [...py.slice(1), "-m", "venv", join(it.to, ".venv")], { encoding: "utf8" });
+          if (v.status !== 0) {
+            const why = String(v.stderr || v.stdout || "").trim().split("\n").pop();
+            throw new Error(`couldn't make the venv: ${why}${process.platform === "linux" ? " (on Ubuntu: sudo apt install python3-venv)" : ""}`);
+          }
+        }
+        say(`  installing ${it.requirements} …`);
+        const p = run(plan.python, ["-m", "pip", "install", "--quiet", "--disable-pip-version-check", "-r", join(it.to, it.requirements)], { encoding: "utf8" });
+        if (p.status !== 0) throw new Error(`pip install failed: ${String(p.stderr || p.stdout || "").trim().split("\n").slice(-2).join(" ")}`);
+        done.push(`Python packages from ${it.requirements}`);
+      } else if (it.kind === "skill" && it.status !== "same") {
+        backup(it.to, `${it.target}-skill`);
+        writeFiles(it.to, plan.pkg.skill, it.vars);
+        done.push(`${it.target}: skill → ${it.to}`);
+      } else if (it.kind === "server" && it.status !== "same" && !it.blocked) {
+        const cur = readJsonFile(it.file);
+        if (cur.error) throw new Error(`${it.file} is ${cur.error}`);
+        if (it.status === "differs") backup(it.file, `${it.target}-${it.file.split(/[\\/]/).pop()}`);
+        const data = cur.data;
+        data.mcpServers = isObj(data.mcpServers) ? data.mcpServers : {};
+        data.mcpServers[it.name] = it.entry;
+        writeJsonFile(it.file, data);
+        done.push(`${it.target}: MCP server ${it.name} → ${it.file}`);
+      } else if (it.kind === "hooks" && it.status !== "same" && !it.blocked) {
+        const cur = readJsonFile(it.file);
+        if (cur.error) throw new Error(`${it.file} is ${cur.error}`);
+        backup(it.file, `${it.target}-settings.json`);
+        writeJsonFile(it.file, { ...cur.data, hooks: it.hooks });
+        done.push(`${it.target}: hooks (${it.events.join(", ")}) → ${it.file}`);
+      }
+    } catch (e) {
+      errors.push(`${it.kind}${it.target ? ` (${it.target})` : ""}: ${e.message}`);
+      if (it.kind === "runtime" || it.kind === "python") break; // the rest would point at a broken runtime
+    }
+  }
+  return { done, errors, backups: backedUp ? backupDir : null };
+}
+
+/** What to do after installing, for the tools that got it. */
+export const nextStep = (plan) =>
+  plan.targets.length === 2 ? "Start a new gu or Claude Code session to use it." : plan.targets[0] === "gu" ? "Start a new gu session (/reset) to use it." : "Start a new Claude Code session to use it.";
+
+/** Would applyInstall change anything? */
+export const planHasWork = (plan) => plan.items.some((i) => i.status && i.status !== "same" && !i.blocked);
+
+// ---- describing a plan (shared by the CLI and gu) ----------------------------------------------
+
+/** The plan as lines of text. `tilde` shortens paths. */
+export function describePlan(plan, tilde = (p) => p) {
+  const word = { new: "new", same: "already there", differs: "replaces what is there (backed up)" };
+  const out = [`${plan.name} — for ${plan.targets.map((t) => (t === "gu" ? "gu" : "Claude Code")).join(" and ")}`];
+  for (const it of plan.items) {
+    if (it.kind === "runtime") out.push(`  runtime (${it.files} files) → ${tilde(it.to)}  ${word[it.status]}`);
+    if (it.kind === "python") out.push(`  Python venv in the runtime, packages from ${it.requirements}  ${it.status === "same" ? word.same : "built here"}`);
+    if (it.kind === "skill") out.push(`  ${it.target}: skill → ${tilde(it.to)}  ${word[it.status]}`);
+    if (it.kind === "server") out.push(`  ${it.target}: MCP server ${it.name} → ${tilde(it.file)}  ${it.blocked ? "SKIPPED (file is broken)" : word[it.status]}`);
+    if (it.kind === "hooks") {
+      out.push(`  ${it.target}: hooks ${it.events.join(", ")} → ${tilde(it.file)}  ${it.blocked ? "SKIPPED (file is broken)" : it.status === "same" ? word.same : "added"}`);
+      for (const r of it.replaced) out.push(`    replaces an older copy: ${tilde(r)}`);
+    }
+  }
+  for (const k of plan.missingEnv) out.push(`  ! ${k} is not set here — set it and install again`);
+  for (const w of plan.warnings) out.push(`  ! ${w}`);
+  for (const n of plan.notes) out.push(`  note: ${n}`);
+  return out;
+}
+
+// ---- run as a script: node install.mjs ---------------------------------------------------------
+
+async function main(argv) {
+  const has = (f) => argv.includes(f);
+  const at = argv.indexOf("--home");
+  const home = at >= 0 ? argv[at + 1] : homedir();
+  const src = argv.find((a, i) => !a.startsWith("--") && argv[i - 1] !== "--home") ?? dirname(fileURLToPath(import.meta.url));
+  if (has("--help") || has("-h")) {
+    console.log("node install.mjs [package] [--gu] [--claude] [--home <dir>] [--dry-run] [--yes]\n  Installs a gu skill package. With neither --gu nor --claude, installs for every tool that is set up here.");
+    return 0;
+  }
+  if (Number(process.versions.node.split(".")[0]) < 18) {
+    console.error(`Node.js 18 or newer is needed (this is ${process.version}).`);
+    return 1;
+  }
+  const targets = TARGETS.filter((t) => has(`--${t}`));
+  let plan;
+  try {
+    plan = planInstall(loadPackage(resolve(src)), { home, targets });
+  } catch (e) {
+    console.error(`Not installed: ${e.message}`);
+    return 1;
+  }
+  const tilde = (p) => String(p).split(home).join("~");
+  console.log(describePlan(plan, tilde).join("\n"));
+  const todo = planHasWork(plan);
+  if (!todo) {
+    console.log("\nNothing to do — it is already installed.");
+    return 0;
+  }
+  if (has("--dry-run")) {
+    console.log("\n--dry-run: nothing was written.");
+    return 0;
+  }
+  if (!has("--yes")) {
+    if (!process.stdin.isTTY) {
+      console.error("\nAdd --yes to install without asking.");
+      return 1;
+    }
+    const { createInterface } = await import("node:readline/promises");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const a = (await rl.question("\nInstall? [y/N] ")).trim().toLowerCase();
+    rl.close();
+    if (a !== "y" && a !== "yes") {
+      console.log("Cancelled — nothing written.");
+      return 0;
+    }
+  }
+  const r = applyInstall(plan, { say: (l) => console.log(l) });
+  for (const d of r.done) console.log(`✓ ${tilde(d)}`);
+  for (const e of r.errors) console.error(`✗ ${e}`);
+  if (r.backups) console.log(`Old copies: ${tilde(r.backups)}`);
+  if (!r.errors.length) console.log(`Done. ${nextStep(plan)}`);
+  return r.errors.length ? 1 : 0;
+}
+
+/** Run directly (node install.mjs), not imported? Compared as REAL paths: a folder reached
+ * through a symlink (macOS /var → /private/var) must still count, or the installer silently
+ * does nothing. */
+export function isMainModule(argv1, url = import.meta.url) {
+  if (!argv1) return false;
+  const real = (p) => {
+    try {
+      return realpathSync(p);
+    } catch {
+      return resolve(p);
+    }
+  };
+  return real(resolve(argv1)) === real(fileURLToPath(url));
+}
+
+if (isMainModule(process.argv[1])) {
+  main(process.argv.slice(2)).then((code) => process.exit(code));
+}