@tiens.nguyen/gu-cli 1.0.883 → 1.0.885

package/skill-package.mjs

@@ -0,0 +1,455 @@
+/**
+ * PACK A SKILL FOR ANOTHER MACHINE (#281) — /skill-pack <name>.
+ *
+ * A skill is often more than its SKILL.md: an MCP server it calls, hooks that run on every turn,
+ * and the code both of those run, which may live outside the skill folder (the session-memory
+ * skill keeps its code in ~/.claude/memory and its venv inside that). This file finds all of it on
+ * this machine and writes one zip that skill-install.mjs (shipped inside as install.mjs) puts back
+ * on any machine, for gu and/or Claude Code.
+ *
+ * What it finds, for the skill folder S (gu's or Claude's, yours or this project's):
+ *   MCP servers  in ~/.gonext/mcp.json and ~/.claude.json whose command/args point inside S or the
+ *                runtime, or that SKILL.md names
+ *   the runtime  R = the folder the skill's outside files share: absolute paths SKILL.md names
+ *                plus the servers' files (or --runtime <dir>). Refused when that is too broad
+ *                (home, ~/.claude, ~/.gonext) or too big
+ *   hooks        in ~/.claude/settings.json and ~/.gonext/settings.json whose files are in S or R
+ *   Python       a command that is R's own venv python becomes {{PYTHON}}; R/requirements.txt is
+ *                then required — the venv itself is never packed, the new machine builds its own
+ *
+ * What it never packs: venvs, node_modules, .git, caches, .env files, databases (.db/.sqlite —
+ * a project's memory stays with the project), .claude-memory folders. MCP server and hook env
+ * values that look secret (by name or shape) become {{ENV:NAME}}, read on the new machine from its
+ * terminal. Every packed text file is scanned for secret shapes; one hit refuses the pack.
+ *
+ * Paths: S → {{SKILL}}, R → {{RUNTIME}}, R's venv python → {{PYTHON}}, then home → {{HOME}}, in
+ * every text file and every server/hook entry. A path still outside all of those is a warning.
+ */
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { deflateRawSync } from "node:zlib";
+import { scanSkillsDir } from "./skills.mjs";
+import { CLAUDE_ONLY_EVENTS, CLAUDE_TO_GU, crc32, FORMAT, MANIFEST, manifestProblems } from "./skill-install.mjs";
+
+export const LIMITS = { files: 2000, bytes: 25 * 1024 * 1024 };
+const SKIP_DIRS = new Set([".venv", "venv", "env", "node_modules", ".git", "__pycache__", ".claude-memory", ".pytest_cache", ".mypy_cache", ".ruff_cache"]);
+const SKIP_FILE = (n) => n === ".DS_Store" || /\.(pyc|pyo|db|sqlite3?|db-wal|db-shm|db-journal|log)$/i.test(n) || n === ".env" || n.startsWith(".env.");
+// platform-ok: names recognised in a packed command, never run here.
+const INTERPRETERS = new Set(["node", "python", "python3", "npx", "uv", "uvx", "bun", "deno", "bash", "sh", "pwsh", "powershell"]);
+const GU_TO_CLAUDE = Object.fromEntries(Object.entries(CLAUDE_TO_GU).map(([c, g]) => [g, c]));
+const isObj = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+
+/** Secret shapes (a subset of api/scripts/scan-bundle.mjs plus the common API-key forms). */
+export const SECRET_SHAPES = [
+  { kind: "a private key (PEM)", re: /-----BEGIN [A-Z ]*PRIVATE KEY-----/g },
+  { kind: "an AWS access key id", re: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g, unless: (m) => /0{5,}|EXAMPLE/.test(m) },
+  { kind: "a signed gu token", re: /\bgu1\.[A-Za-z0-9_-]{40,}\.[A-Za-z0-9_-]{40,}/g },
+  { kind: "an API key (sk-…)", re: /\bsk-(?:ant-|proj-)?[A-Za-z0-9_-]{24,}/g },
+  { kind: "a GitHub token", re: /\bgh[pousr]_[A-Za-z0-9]{30,}/g },
+  { kind: "a Slack token", re: /\bxox[abprs]-[A-Za-z0-9-]{10,}/g },
+  { kind: "a Google API key", re: /\bAIza[0-9A-Za-z_-]{35}\b/g },
+  {
+    kind: "a database address with a password",
+    re: /\b(?:mongodb(?:\+srv)?|postgres(?:ql)?|mysql|redis):\/\/[^\s"'`/:@${}]+:[^\s"'`@${}]+@[^\s"'`/]+/g,
+    unless: (m) => /@(127\.0\.0\.1|localhost|host|example\.com|\[::1\])(:|\/|$)/.test(m),
+  },
+];
+/** Findings in one text → [{ line, kind }], never the value. */
+export function scanSecrets(text) {
+  const t = String(text ?? "");
+  const out = [];
+  for (const s of SECRET_SHAPES) {
+    for (const m of t.matchAll(s.re)) {
+      if (s.unless?.(m[0])) continue;
+      out.push({ line: t.slice(0, m.index).split("\n").length, kind: s.kind });
+    }
+  }
+  return out;
+}
+const SECRET_NAME = /KEY|TOKEN|SECRET|PASS|AUTH|CRED|PRIVATE|COOKIE|SESSION/i;
+
+// ---- reading this machine ----------------------------------------------------------------------
+
+function readJson(file) {
+  try {
+    const d = JSON.parse(readFileSync(file, "utf8"));
+    return isObj(d) ? d : {};
+  } catch {
+    return {};
+  }
+}
+const inside = (p, dir) => {
+  const a = resolve(p), b = resolve(dir);
+  return a === b || a.startsWith(b.endsWith(sep) ? b : b + sep);
+};
+const isText = (buf) => !buf.subarray(0, 8192).includes(0);
+const expand = (p, home) => (p.startsWith("~/") || p === "~" ? join(home, p.slice(2)) : p);
+
+/** Every file under dir that is packed → { files: Map<rel, {data, mode}>, skipped: [rel] }. */
+export function packTree(dir) {
+  const files = new Map();
+  const skipped = [];
+  let bytes = 0;
+  const walk = (d) => {
+    for (const e of readdirSync(d, { withFileTypes: true })) {
+      const p = join(d, e.name);
+      const rel = p.slice(dir.length + 1).split(sep).join("/");
+      if (e.isDirectory()) {
+        if (SKIP_DIRS.has(e.name)) skipped.push(rel + "/");
+        else walk(p);
+      } else if (e.isFile()) {
+        if (SKIP_FILE(e.name)) {
+          if (e.name !== ".DS_Store" && !e.name.endsWith(".pyc")) skipped.push(rel);
+          continue;
+        }
+        const st = statSync(p);
+        bytes += st.size;
+        if (files.size >= LIMITS.files || bytes > LIMITS.bytes) {
+          throw new Error(`${dir} is too big to pack (over ${LIMITS.files} files or ${LIMITS.bytes / 1024 / 1024} MB)`);
+        }
+        files.set(rel, { data: readFileSync(p), mode: st.mode & 0o777 });
+      }
+    }
+  };
+  walk(dir);
+  return { files, skipped };
+}
+
+/** The skill named `name` → { name, dir, source, scope } | null. This project's first, then yours; gu's, then Claude's. */
+export function findSkill(name, { cwd = process.cwd(), home = homedir() } = {}) {
+  const want = String(name).replace(/^\//, "");
+  const dirs = [];
+  for (const source of ["gu", "claude"]) {
+    const dot = source === "gu" ? ".gonext" : ".claude";
+    if (cwd && resolve(cwd) !== resolve(home)) dirs.push({ dir: join(cwd, dot, "skills"), source, scope: "project" });
+    dirs.push({ dir: join(home, dot, "skills"), source, scope: "user" });
+  }
+  for (const d of dirs) {
+    const hit = scanSkillsDir(d.dir, d.scope).skills.find((s) => s.name === want || s.dir.split(/[\\/]/).pop() === want);
+    if (hit) return { name: hit.name, description: hit.description, dir: hit.dir, source: d.source, scope: d.scope };
+  }
+  return null;
+}
+
+/** Absolute paths that exist, named in a text (/abs/…, ~/…, C:\…). */
+export function pathsIn(text, home) {
+  const out = new Set();
+  const re = /(?:~\/|\/(?:Users|home|opt|usr|var|srv|root)\/|[A-Za-z]:\\)[^\s"'`)<>\]|,;]*/g;
+  for (const m of String(text).matchAll(re)) {
+    let p = expand(m[0].replace(/[.:]+$/, ""), home);
+    // Walk up to the longest prefix that exists (a doc may name a file that is made later).
+    while (p && !existsSync(p) && dirname(p) !== p) p = dirname(p);
+    if (p && existsSync(p) && isAbsolute(p)) out.add(resolve(p));
+  }
+  return [...out];
+}
+
+function commonDir(paths) {
+  if (!paths.length) return null;
+  let parts = resolve(paths[0]).split(sep);
+  for (const p of paths.slice(1)) {
+    const q = resolve(p).split(sep);
+    let i = 0;
+    while (i < parts.length && i < q.length && parts[i] === q[i]) i++;
+    parts = parts.slice(0, i);
+  }
+  return parts.join(sep) || sep;
+}
+
+/** Is this folder too broad to be one skill's runtime? */
+function tooBroad(dir, home) {
+  const d = resolve(dir);
+  return [home, join(home, ".claude"), join(home, ".gonext"), join(home, ".config"), dirname(home), sep].some((x) => resolve(x) === d) || inside(home, d);
+}
+
+const refsOf = (entry, home) =>
+  [entry.command, ...(Array.isArray(entry.args) ? entry.args : [])]
+    .map((a) => String(a ?? ""))
+    .filter((a) => isAbsolute(a) || a.startsWith("~/"))
+    .map((a) => resolve(expand(a, home)));
+
+// ---- the plan ----------------------------------------------------------------------------------
+
+/**
+ * Everything /skill-pack would write → { manifest, skill, runtime, found, warnings, secrets, skipped }.
+ * Throws when the skill is missing or the runtime cannot be told apart from your home folder.
+ */
+export function planSkillPack(name, { cwd = process.cwd(), home = homedir(), runtime: runtimeOpt, platform = process.platform } = {}) {
+  const sk = findSkill(name, { cwd, home });
+  if (!sk) throw new Error(`no skill named "${name}" in ./.gonext/skills, ~/.gonext/skills, ./.claude/skills or ~/.claude/skills`);
+  const warnings = [];
+  const skillTree = packTree(sk.dir);
+  const md = skillTree.files.get("SKILL.md").data.toString("utf8");
+
+  // MCP servers everywhere this machine keeps them.
+  const servers = [];
+  const guMcp = readJson(join(home, ".gonext", "mcp.json"));
+  const claude = readJson(join(home, ".claude.json"));
+  const proj = isObj(claude.projects) ? claude.projects[resolve(cwd)] : null;
+  for (const [where, obj] of [["~/.gonext/mcp.json", guMcp.mcpServers], ["~/.claude.json", claude.mcpServers], ["~/.claude.json (this folder)", proj?.mcpServers], ["./.mcp.json", readJson(join(cwd, ".mcp.json")).mcpServers]]) {
+    for (const [n, e] of Object.entries(isObj(obj) ? obj : {})) if (isObj(e) && e.command) servers.push({ name: n, entry: e, where });
+  }
+  const named = (n) => new RegExp(`(^|[^A-Za-z0-9_-])${n.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}([^A-Za-z0-9_-]|$)`).test(md);
+
+  // The runtime: what the skill's outside files have in common.
+  const mdPaths = pathsIn(md, home).filter((p) => !inside(p, sk.dir));
+  const firstServers = servers.filter((s) => refsOf(s.entry, home).some((p) => inside(p, sk.dir)) || named(s.name));
+  let runtime = runtimeOpt ? resolve(expand(runtimeOpt, home)) : null;
+  if (!runtime) {
+    const outside = [...mdPaths, ...firstServers.flatMap((s) => refsOf(s.entry, home).filter((p) => existsSync(p) && !inside(p, sk.dir)))];
+    const dirs = outside.map((p) => (statSync(p).isDirectory() ? p : dirname(p)));
+    // A venv's python names its runtime by where the venv sits, not by bin/.
+    const roots = dirs.map((d) => d.replace(new RegExp(`[\\\\/](?:\\.venv|venv)[\\\\/](?:bin|Scripts)$`), ""));
+    runtime = commonDir(roots);
+  }
+  if (runtime && !existsSync(runtime)) throw new Error(`--runtime ${runtime} does not exist`);
+  if (runtime && tooBroad(runtime, home)) {
+    throw new Error(`the skill's outside files only have ${runtime} in common — too broad to pack. Point at the right folder: /skill-pack ${sk.name} --runtime <dir>`);
+  }
+  if (runtime && inside(runtime, sk.dir)) runtime = null; // all inside the skill folder: nothing extra
+
+  const linked = (entry) => refsOf(entry, home).some((p) => inside(p, sk.dir) || (runtime && inside(p, runtime)));
+  const useServers = servers.filter((s) => linked(s.entry) || named(s.name));
+  const dup = new Map();
+  for (const s of useServers) {
+    if (dup.has(s.name) && JSON.stringify(dup.get(s.name).entry) !== JSON.stringify(s.entry)) warnings.push(`MCP server ${s.name} is set up differently in ${dup.get(s.name).where} and ${s.where} — packed the one in ${dup.get(s.name).where}`);
+    if (!dup.has(s.name)) dup.set(s.name, s);
+  }
+  // A server SKILL.md names that is set up nowhere here: say so, never invent one.
+  for (const m of md.matchAll(/`([a-z0-9][a-z0-9_-]{2,63})`\s+MCP server|MCP server\s+`([a-z0-9][a-z0-9_-]{2,63})`/gi)) {
+    const n = m[1] || m[2];
+    if (!dup.has(n)) warnings.push(`SKILL.md names the MCP server "${n}", which is not set up on this machine — it is not in the package`);
+  }
+
+  // Hooks: Claude's settings (Claude vocabulary) and gu's (gu vocabulary, or dialect "claude").
+  const hooks = {};
+  const hookFrom = [];
+  const addHook = (claudeEvent, group, where) => {
+    const hs = (Array.isArray(group.hooks) ? group.hooks : []).filter((h) => isObj(h) && (h.type ?? "command") === "command" && h.command);
+    if (!hs.length || !hs.every((h) => linked(h))) return;
+    const g = { matcher: String(group.matcher ?? ""), hooks: hs.map((h) => ({ type: "command", command: h.command, ...(h.args ? { args: h.args } : {}), ...(h.timeout ? { timeout: h.timeout } : {}), ...(isObj(h.env) ? { env: h.env } : {}) })) };
+    const list = (hooks[claudeEvent] ??= []);
+    if (!list.some((x) => JSON.stringify(x) === JSON.stringify(g))) {
+      list.push(g);
+      hookFrom.push(`${claudeEvent} (${where})`);
+    }
+  };
+  const claudeSettings = readJson(join(home, ".claude", "settings.json"));
+  for (const [ev, groups] of Object.entries(isObj(claudeSettings.hooks) ? claudeSettings.hooks : {})) {
+    if (!(ev in CLAUDE_TO_GU) && !CLAUDE_ONLY_EVENTS.includes(ev)) {
+      if ((Array.isArray(groups) ? groups : []).some((g) => (g.hooks ?? []).some((h) => linked(h)))) warnings.push(`a ${ev} hook belongs to this skill, but no installer handles ${ev} — not packed`);
+      continue;
+    }
+    for (const g of Array.isArray(groups) ? groups : []) addHook(ev, g, "Claude Code");
+  }
+  const guSettings = readJson(join(home, ".gonext", "settings.json"));
+  for (const [ev, groups] of Object.entries(isObj(guSettings.hooks) ? guSettings.hooks : {})) {
+    for (const g of Array.isArray(groups) ? groups : []) {
+      if (!GU_TO_CLAUDE[ev]) continue;
+      if (g.dialect !== "claude") {
+        if ((g.hooks ?? []).some((h) => linked(h))) warnings.push(`gu's ${ev} hook for this skill speaks gu's own input format — not packed (only Claude-format hooks run in both tools)`);
+        continue;
+      }
+      addHook(GU_TO_CLAUDE[ev], g, "gu");
+    }
+  }
+
+  // Python: a command that is the runtime's own venv python.
+  let python = null;
+  let venvPy = null;
+  const isVenvPy = (c) => runtime && inside(c, runtime) && /[\\/](?:\.venv|venv)[\\/](?:bin[\\/]python[0-9.]*|Scripts[\\/]python(?:\.exe)?)$/.test(c);
+  for (const e of [...[...dup.values()].map((s) => s.entry), ...Object.values(hooks).flat().flatMap((g) => g.hooks)]) {
+    const c = String(e.command);
+    if (isAbsolute(c) && isVenvPy(c)) venvPy = c;
+  }
+  const runtimeTree = runtime ? packTree(runtime) : { files: new Map(), skipped: [] };
+  if (venvPy) {
+    if (!runtimeTree.files.has("requirements.txt")) throw new Error(`${venvPy} is a venv, but ${runtime} has no requirements.txt to rebuild it from — add one (pip freeze > requirements.txt) and pack again`);
+    python = { requirements: "requirements.txt" };
+  }
+
+  // Path → placeholder, longest first.
+  const subs = [];
+  const addSub = (from, to) => {
+    if (!from) return;
+    subs.push([from, to]);
+    if (from.startsWith(home + sep)) subs.push(["~" + from.slice(home.length).split(sep).join("/"), to]);
+  };
+  if (venvPy) addSub(venvPy, "{{PYTHON}}");
+  addSub(sk.dir, "{{SKILL}}");
+  if (runtime) addSub(runtime, "{{RUNTIME}}");
+  subs.push([home, "{{HOME}}"]);
+  subs.sort((a, b) => b[0].length - a[0].length);
+  const rewrite = (s) => {
+    let t = String(s);
+    for (const [from, to] of subs) t = t.split(from).join(to);
+    return t;
+  };
+  const env = new Set();
+  const cleanEntry = (e, label) => {
+    let command = String(e.command);
+    if (isAbsolute(command) && !(runtime && inside(command, runtime)) && !inside(command, sk.dir)) {
+      const base = command.split(/[\\/]/).pop().replace(/\.exe$/i, "");
+      if (INTERPRETERS.has(base.replace(/[0-9.]+$/, "")) || INTERPRETERS.has(base)) command = base;
+      else warnings.push(`${label} runs ${command}, which the other machine may not have`);
+    }
+    const out = { command: rewrite(command), args: (Array.isArray(e.args) ? e.args : []).map((a) => rewrite(a)) };
+    if (isObj(e.env)) {
+      out.env = {};
+      for (const [k, v] of Object.entries(e.env)) {
+        if (SECRET_NAME.test(k) || scanSecrets(String(v)).length) {
+          out.env[k] = `{{ENV:${k}}}`;
+          env.add(k);
+        } else out.env[k] = rewrite(v);
+      }
+    }
+    for (const a of [out.command, ...out.args]) {
+      if ((isAbsolute(a) || a.startsWith("~/")) && !a.startsWith("{{")) warnings.push(`${label} names ${a}, which is outside the skill and its runtime — it may not exist on the other machine`);
+    }
+    return out;
+  };
+  const mcpServers = Object.fromEntries([...dup.values()].map((s) => [s.name, cleanEntry(s.entry, `MCP server ${s.name}`)]));
+  const outHooks = Object.fromEntries(
+    Object.entries(hooks).map(([ev, groups]) => [ev, groups.map((g) => ({ matcher: g.matcher, hooks: g.hooks.map((h) => ({ type: "command", ...cleanEntry(h, `the ${ev} hook`), ...(h.timeout ? { timeout: h.timeout } : {}) })) }))])
+  );
+
+  // Rewrite and scan every text file.
+  const secrets = [];
+  const finish = (tree, prefix) => {
+    const out = new Map();
+    for (const [rel, f] of tree.files) {
+      if (!isText(f.data)) {
+        out.set(rel, f);
+        continue;
+      }
+      const text = rewrite(f.data.toString("utf8"));
+      for (const s of scanSecrets(text)) secrets.push({ file: `${prefix}/${rel}`, ...s });
+      out.set(rel, { data: Buffer.from(text, "utf8"), mode: f.mode });
+    }
+    return out;
+  };
+  const skill = finish(skillTree, "skill");
+  const runtimeFiles = finish(runtimeTree, "runtime");
+
+  const manifest = {
+    format: FORMAT,
+    name: sk.name,
+    description: sk.description,
+    packedAt: new Date().toISOString().slice(0, 10),
+    from: sk.source === "gu" ? "gu" : "Claude Code",
+    ...(python ? { python } : {}),
+    ...(Object.keys(mcpServers).length ? { mcpServers } : {}),
+    ...(Object.keys(outHooks).length ? { hooks: outHooks } : {}),
+    ...(env.size ? { env: [...env] } : {}),
+  };
+  const problems = manifestProblems(manifest);
+  if (problems.length) throw new Error(problems.join("; "));
+  return {
+    manifest,
+    skill,
+    runtime: runtimeFiles,
+    found: { skillDir: sk.dir, source: sk.source, scope: sk.scope, runtimeDir: runtime, servers: [...dup.values()].map((s) => `${s.name} (${s.where})`), hooks: hookFrom, python: !!python },
+    warnings: [...new Set(warnings)],
+    secrets,
+    skipped: [...skillTree.skipped.map((s) => `skill/${s}`), ...runtimeTree.skipped.map((s) => `runtime/${s}`)],
+  };
+}
+
+// ---- the zip -----------------------------------------------------------------------------------
+
+const DOS_TIME = 0; // 00:00:00
+const DOS_DATE = ((2026 - 1980) << 9) | (1 << 5) | 1; // fixed: the same skill packs to the same bytes
+
+/** Map<path, {data, mode}> → zip bytes (deflated; unix modes kept). */
+export function writeZip(files) {
+  const locals = [];
+  const central = [];
+  let offset = 0;
+  for (const [name, f] of [...files].sort(([a], [b]) => a.localeCompare(b))) {
+    const nameBuf = Buffer.from(name, "utf8");
+    const packed = deflateRawSync(f.data, { level: 9 });
+    const crc = crc32(f.data);
+    const h = Buffer.alloc(30);
+    h.writeUInt32LE(0x04034b50, 0);
+    h.writeUInt16LE(20, 4);
+    h.writeUInt16LE(0x0800, 6); // utf-8 names
+    h.writeUInt16LE(8, 8);
+    h.writeUInt16LE(DOS_TIME, 10);
+    h.writeUInt16LE(DOS_DATE, 12);
+    h.writeUInt32LE(crc, 14);
+    h.writeUInt32LE(packed.length, 18);
+    h.writeUInt32LE(f.data.length, 22);
+    h.writeUInt16LE(nameBuf.length, 26);
+    locals.push(h, nameBuf, packed);
+    const c = Buffer.alloc(46);
+    c.writeUInt32LE(0x02014b50, 0);
+    c.writeUInt16LE((3 << 8) | 20, 4); // made on unix: external attrs carry the mode
+    c.writeUInt16LE(20, 6);
+    c.writeUInt16LE(0x0800, 8);
+    c.writeUInt16LE(8, 10);
+    c.writeUInt16LE(DOS_TIME, 12);
+    c.writeUInt16LE(DOS_DATE, 14);
+    c.writeUInt32LE(crc, 16);
+    c.writeUInt32LE(packed.length, 20);
+    c.writeUInt32LE(f.data.length, 24);
+    c.writeUInt16LE(nameBuf.length, 28);
+    c.writeUInt32LE((((f.mode || 0o644) | 0o100000) << 16) >>> 0, 38);
+    c.writeUInt32LE(offset, 42);
+    central.push(c, nameBuf);
+    offset += 30 + nameBuf.length + packed.length;
+  }
+  const cd = Buffer.concat(central);
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(0x06054b50, 0);
+  end.writeUInt16LE(files.size, 8);
+  end.writeUInt16LE(files.size, 10);
+  end.writeUInt32LE(cd.length, 12);
+  end.writeUInt32LE(offset, 16);
+  return Buffer.concat([...locals, cd, end]);
+}
+
+/** A zip entry's name: "/" always, whatever this machine uses (the zip format says so). */
+const zipPath = (...parts) => parts.join("/");
+
+/** The README that rides in the zip. */
+export function readmeFor(manifest) {
+  const n = manifest.name;
+  return [
+    `${n} — a skill packed by gu`,
+    "",
+    manifest.description,
+    "",
+    "Install (Node.js 18+; Python 3.9+ too if the skill uses Python):",
+    `  in gu:            /skill-install ${n}.zip`,
+    `  without gu:       unzip ${n}.zip && node ${zipPath(n, "install.mjs")}`,
+    "",
+    "It installs for gu (~/.gonext) and Claude Code (~/.claude), whichever is set up on the machine;",
+    "--gu or --claude picks one, --dry-run shows the plan without writing anything.",
+    ...(manifest.env?.length ? ["", `Set these in the terminal first (they were not packed): ${manifest.env.join(", ")}`] : []),
+    "",
+  ].join("\n");
+}
+
+/** The whole package as zip entries under one top folder. */
+export function packageFiles(plan) {
+  const n = plan.manifest.name;
+  const files = new Map();
+  const installer = readFileSync(join(dirname(fileURLToPath(import.meta.url)), "skill-install.mjs"));
+  files.set(zipPath(n, "install.mjs"), { data: installer, mode: 0o755 });
+  files.set(zipPath(n, MANIFEST), { data: Buffer.from(JSON.stringify(plan.manifest, null, 2) + "\n"), mode: 0o644 });
+  files.set(zipPath(n, "README.txt"), { data: Buffer.from(readmeFor(plan.manifest)), mode: 0o644 });
+  for (const [rel, f] of plan.skill) files.set(zipPath(n, "skill", rel), f);
+  for (const [rel, f] of plan.runtime) files.set(zipPath(n, "runtime", rel), f);
+  return files;
+}
+
+/** Write the zip → { file, bytes, count }. Refuses while the plan has secret findings. */
+export function writeSkillPack(plan, outFile) {
+  if (plan.secrets.length) throw new Error(`secret-looking text in ${plan.secrets.map((s) => `${s.file}:${s.line}`).join(", ")} — remove it and pack again`);
+  const files = packageFiles(plan);
+  const zip = writeZip(files);
+  writeFileSync(outFile, zip);
+  return { file: outFile, bytes: zip.length, count: files.size };
+}