master-skill 0.12.12 → 0.12.14

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "master-skill",
       "description": "FoJin-powered Buddhist AI persona framework — source-grounded, boundary-aware, fidelity-tested, runtime-ready. 15 prebuilt masters across 印度/汉传/藏传/南传 plus compare, debate, and curriculum meta-skills.",
-      "version": "0.12.12",
+      "version": "0.12.14",
       "source": "./",
       "author": {
         "name": "xr843",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "master-skill",
   "description": "FoJin-powered Buddhist AI persona framework — source-grounded, boundary-aware, fidelity-tested, runtime-ready. 15 prebuilt masters across 印度/汉传/藏传/南传 plus compare, debate, and curriculum meta-skills.",
-  "version": "0.12.12",
+  "version": "0.12.14",
   "author": {
     "name": "xr843",
     "email": "xr843@users.noreply.github.com"

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "master-skill",
   "displayName": "Master Skill",
   "description": "FoJin-powered Buddhist AI persona framework — source-grounded, boundary-aware, fidelity-tested, runtime-ready. 15 prebuilt masters across 印度/汉传/藏传/南传.",
-  "version": "0.12.12",
+  "version": "0.12.14",
   "author": {
     "name": "xr843",
     "email": "xr843@users.noreply.github.com"

package/SKILL.md

@@ -5,13 +5,11 @@ argument-hint: <法师名称>
 version: 1.0.0
 user-invocable: true
 allowed-tools:
-  - Bash
   - Read
-  - Write
-  - Edit
   - Glob
   - Grep
-  - WebFetch
+  - Bash(python3 ${CLAUDE_SKILL_DIR}/tools/*)
+  - Bash(python3 "${CLAUDE_SKILL_DIR}/tools/*)
 ---
 
 # Master-skill — 佛教法师教学角色生成器
@@ -64,6 +62,10 @@ allowed-tools:
 
 ## 主流程（生成新法师）
 
+### Step 0：检查运行环境
+
+先运行 `python3 "${CLAUDE_SKILL_DIR}/tools/check_deps.py"`。生成器的每个工具启动时都要导入 `requests`、`pyyaml`、`pypinyin`，缺任何一个都会直接报 `ModuleNotFoundError`，连离线步骤也跑不了。退出码非 0 时停下，把它打印的安装方法原样告诉用户（系统 Python 拒绝 pip 时改用虚拟环境）；**不要擅自安装**，那会改动用户的环境。
+
 ### Step 1：信息录入
 
 加载 `${CLAUDE_SKILL_DIR}/prompts/intake.md`，3 问模式收集：①法师名称（FoJin KG 自动匹配） ②关注方面（教义/修行/讲解/全部） ③语言偏好（按传承默认）。

package/bin/cli.mjs

@@ -4,6 +4,7 @@ import fs from "fs";
 import path from "path";
 import os from "os";
 import { fileURLToPath } from "url";
+import { spawnSync } from "child_process";
 
 // fileURLToPath (not new URL().pathname) — on Windows the URL pathname is
 // "/C:/…", which fs cannot resolve, so every command saw an empty prebuilt/.
@@ -151,6 +152,14 @@ function cpR(src, dest) {
   for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
     const s = path.join(src, entry.name);
     const d = path.join(dest, entry.name);
+    // The package ships no links. One in the source is left over from running
+    // the clone instructions' `ln -sf` twice, which — with the target already a
+    // link to a directory — creates prebuilt/<skill>/<skill> pointing at its own
+    // parent. copyFileSync on it threw EISDIR and the install crashed.
+    if (entry.isSymbolicLink()) {
+      console.error(`  (skipped link ${s} — not part of the package)`);
+      continue;
+    }
     if (entry.isDirectory()) cpR(s, d);
     else fs.copyFileSync(s, d);
   }
@@ -365,6 +374,35 @@ function resolveMasterDir(input) {
 
 // Returns the number of failures so main can set a non-zero exit code —
 // scripted callers must be able to tell a typo from a clean install.
+// create-master's tools import requests, pyyaml and pypinyin at startup and exit
+// with ModuleNotFoundError without them. tools/check_deps.py (standard library
+// only) reports which are missing and how to install them.
+function pythonBin() {
+  return process.env.PYTHON || (process.platform === "win32" ? "python" : "python3");
+}
+
+function generatorDependencies(generatorDir) {
+  const script = path.join(generatorDir, "tools", "check_deps.py");
+  if (!fs.existsSync(script)) return null;
+  const result = spawnSync(pythonBin(), [script, "--json"], { encoding: "utf8", timeout: 30000 });
+  if (result.error) {
+    return { ok: false, pythonMissing: true, message: `${pythonBin()} was not found; create-master needs Python 3.9+` };
+  }
+  try {
+    const report = JSON.parse(result.stdout);
+    if (report.ok) return { ok: true };
+    const what = report.python_too_old
+      ? `Python ${report.python} is older than 3.9`
+      : `missing Python package(s) ${report.missing.join(", ")}`;
+    return {
+      ok: false,
+      message: `create-master: ${what} — run: ${pythonBin()} "${script}" for install steps`,
+    };
+  } catch {
+    return { ok: false, message: `create-master: could not check Python dependencies (${(result.stderr || "").trim()})` };
+  }
+}
+
 function cmdInstall(names) {
   fs.mkdirSync(SKILLS_DIR, { recursive: true });
   let failed = 0;
@@ -382,8 +420,10 @@ function cmdInstall(names) {
     }
     const src = path.join(PACKAGE_ROOT, skill.source);
     const dest = path.join(SKILLS_DIR, skill.install_dir);
+    let deps = null;
     if (skill.kind === "generator") {
       replaceGeneratorInstall(skill, src, dest);
+      deps = generatorDependencies(dest);
     } else {
       // Clear any previous install first: files renamed or removed upstream
       // must not linger as stale skill content under ~/.claude/skills/.
@@ -391,6 +431,7 @@ function cmdInstall(names) {
       cpR(src, dest);
     }
     console.log(`  ✓ ${name} → ${dest}`);
+    if (deps && !deps.ok) console.log(`    ! ${deps.message}`);
   }
   return failed;
 }
@@ -405,7 +446,40 @@ function cmdInstallAll(label = "Installing") {
   return cmdInstall(all);
 }
 
-function cmdUninstall(names) {
+// Directories under create-master/masters/ — personas the user generated. `update`
+// carries them across (replaceGeneratorInstall); `uninstall` must not quietly
+// delete them either.
+function generatedPersonas(generatorDir) {
+  const mastersDir = path.join(generatorDir, "masters");
+  if (!fs.existsSync(mastersDir)) return [];
+  return fs
+    .readdirSync(mastersDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+}
+
+// Links in the skills directory that `master_builder.py --register` made into
+// this generator's masters/. Resolved with realpath so a Windows junction is
+// recognised as well as a symlink.
+function registrationsInto(generatorDir) {
+  const mastersDir = path.join(generatorDir, "masters");
+  if (!fs.existsSync(mastersDir) || !fs.existsSync(SKILLS_DIR)) return [];
+  const realMasters = fs.realpathSync(mastersDir);
+  return fs
+    .readdirSync(SKILLS_DIR, { withFileTypes: true })
+    .filter((entry) => entry.isSymbolicLink())
+    .map((entry) => path.join(SKILLS_DIR, entry.name))
+    .filter((link) => {
+      try {
+        return fs.realpathSync(link).startsWith(realMasters + path.sep);
+      } catch {
+        return false;
+      }
+    });
+}
+
+function cmdUninstall(names, { force = false } = {}) {
   let failed = 0;
   for (const name of names) {
     if (!isSafeName(name)) {
@@ -429,6 +503,26 @@ function cmdUninstall(names) {
       failed++;
       continue;
     }
+    if (skill.kind === "generator") {
+      // Until 2026-09-17 this removed the whole directory, masters/ included:
+      // every persona the user had generated was deleted with "✓ removed" and
+      // exit 0, and the links registered for them were left pointing at nothing.
+      const generated = generatedPersonas(dest);
+      if (generated.length && !force) {
+        console.log(
+          `  ✗ ${name} — holds ${generated.length} persona(s) you generated: ${generated.join(", ")}`
+        );
+        console.log(
+          `    Uninstalling deletes ${path.join(dest, "masters")}. Move it somewhere safe first, or rerun with --force.`
+        );
+        failed++;
+        continue;
+      }
+      for (const link of registrationsInto(dest)) {
+        fs.unlinkSync(link);
+        console.log(`  ✓ ${path.basename(link)} link removed (${link})`);
+      }
+    }
     fs.rmSync(dest, { recursive: true, force: true });
     console.log(`  ✓ ${name} removed (${dest})`);
   }
@@ -450,6 +544,10 @@ function expectedInstallFiles(skill) {
   const walk = (rel) => {
     const abs = path.join(src, rel);
     if (!fs.existsSync(abs)) return;
+    // Same rule as cpR: install skips links, so they are not expected files.
+    // Following a self-referencing one walked the loop to the OS link limit and
+    // reported hundreds of phantom missing files.
+    if (fs.lstatSync(abs).isSymbolicLink()) return;
     if (fs.statSync(abs).isDirectory()) {
       if (path.basename(abs) === "__pycache__") return;
       for (const entry of fs.readdirSync(abs)) {
@@ -512,8 +610,19 @@ function installedProblems() {
     }
   }
 
+  const generator = CATALOG.skills.find((skill) => skill.kind === "generator");
+  const generatorDir = generator && path.join(SKILLS_DIR, generator.install_dir);
+  if (generatorDir && fs.existsSync(path.join(generatorDir, "SKILL.md"))) {
+    const deps = generatorDependencies(generatorDir);
+    if (deps && !deps.ok) {
+      problems.push({ code: "generator-dependencies", name: generator.name, message: deps.message });
+    }
+  }
+
   // Personas registered by create-master are links into create-master/masters/;
-  // uninstalling the generator leaves them pointing at nothing.
+  // deleting or moving a generated persona by hand leaves its link pointing at
+  // nothing. (`uninstall create-master` refuses while personas exist, and with
+  // --force removes their links itself.)
   if (fs.existsSync(SKILLS_DIR)) {
     for (const entry of fs.readdirSync(SKILLS_DIR, { withFileTypes: true })) {
       if (!entry.isSymbolicLink()) continue;
@@ -909,6 +1018,8 @@ Usage:
   master-skill doctor              Check local install and runtime paths
   master-skill doctor --json       Print diagnostics as JSON
   master-skill uninstall <name...> Remove installed skills
+  master-skill uninstall create-master --force
+                                   Also delete the personas you generated (refused otherwise)
   master-skill --version           Print version
   master-skill --help              Show this help
 
@@ -936,7 +1047,8 @@ Examples:
 if (CATALOG) {
   const args = process.argv.slice(2);
   const json = args.includes("--json");
-  const positionalArgs = args.filter((arg) => arg !== "--json");
+  const force = args.includes("--force");
+  const positionalArgs = args.filter((arg) => arg !== "--json" && arg !== "--force");
   const cmd = positionalArgs[0];
 
   if (!cmd || cmd === "--help" || cmd === "-h") {
@@ -977,7 +1089,7 @@ if (CATALOG) {
       console.log("Usage: master-skill uninstall <name...>");
       process.exitCode = 1;
     } else {
-      if (cmdUninstall(rest) > 0) process.exitCode = 1;
+      if (cmdUninstall(rest, { force }) > 0) process.exitCode = 1;
     }
   } else {
     console.log(`Unknown command: ${cmd}\nRun master-skill --help for usage.`);

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "master-skill",
   "description": "FoJin-powered Buddhist AI persona framework — source-grounded, boundary-aware, fidelity-tested, runtime-ready. 15 prebuilt masters across 印度/汉传/藏传/南传.",
-  "version": "0.12.12",
+  "version": "0.12.14",
   "contextFileName": "GEMINI.md"
 }

package/hooks/session-start

@@ -61,7 +61,8 @@ emit_modes_only() {
     if [ -n "${CURSOR_PLUGIN_ROOT:-}" ]; then
         printf '{"additional_context": %s}\n' "$MODES_JSON"
     elif [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -z "${COPILOT_CLI:-}" ]; then
-        printf '{"hookSpecificOutput": {"additionalContext": %s}}\n' "$MODES_JSON"
+        # hookEventName is required; without it Claude Code rejects the payload.
+        printf '{"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": %s}}\n' "$MODES_JSON"
     else
         printf '{"additionalContext": %s}\n' "$MODES_JSON"
     fi

package/hooks/session_start.py

@@ -136,7 +136,17 @@ def wrap_for_host(context: str, env: dict) -> dict:
     if env.get("CURSOR_PLUGIN_ROOT"):
         return {"additional_context": context}
     if env.get("CLAUDE_PLUGIN_ROOT") and not env.get("COPILOT_CLI"):
-        return {"hookSpecificOutput": {"additionalContext": context}}
+        # `hookEventName` is required. Without it Claude Code 2.1.273 rejects the
+        # whole payload — "Hook JSON output validation failed — hookSpecificOutput
+        # is missing required field hookEventName" — shows that error at every
+        # session start, and injects nothing. Measured 2026-09-17 in an isolated
+        # plugin install; the transcript recorded `hook_non_blocking_error`.
+        return {
+            "hookSpecificOutput": {
+                "hookEventName": "SessionStart",
+                "additionalContext": context,
+            }
+        }
     return {"additionalContext": context}
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "master-skill",
-  "version": "0.12.12",
+  "version": "0.12.14",
   "type": "module",
   "description": "FoJin-powered Buddhist AI persona framework — source-grounded, boundary-aware, fidelity-tested, runtime-ready. 15 pre-built masters across 印度 / 汉传 / 藏传 / 南传, plus /compare-masters, /master-debate, and /master-curriculum.",
   "bin": {

package/tools/check_deps.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+"""Check the Python packages create-master's tools import at startup.
+
+Every generator tool imports `fojin_bridge` (which imports `requests`) or
+`skill_writer` (which imports `yaml` and `pypinyin`) at module level. Without those
+packages each one exits with `ModuleNotFoundError` before doing anything — even
+`master_builder.py --offline-smoke`, which never touches the network. Measured
+2026-09-17 in a clean venv: `rag_query.py`, `sutra_collector.py` and
+`master_builder.py` all failed that way.
+
+Nothing told an npx user to install them. The only mention was the clone guide's
+`pip install -r requirements.txt`, and on recent Debian, Ubuntu and Homebrew Pythons
+that command is itself refused as an externally-managed environment (PEP 668).
+
+Standard library only, so it runs where the tools cannot.
+
+Usage:
+    python3 tools/check_deps.py          # exit 1 and print how to install if missing
+    python3 tools/check_deps.py --json
+"""
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import json
+import platform
+import sys
+from pathlib import Path
+
+# import name -> distribution name in requirements.txt
+REQUIRED = {"requests": "requests", "yaml": "pyyaml", "pypinyin": "pypinyin"}
+MIN_PYTHON = (3, 9)
+REQUIREMENTS = Path(__file__).resolve().parent.parent / "requirements.txt"
+
+
+def missing(find_spec=importlib.util.find_spec) -> list[str]:
+    """Distributions whose import name cannot be found."""
+    return [dist for module, dist in REQUIRED.items() if find_spec(module) is None]
+
+
+def guidance(missing_dists: list[str], requirements: Path = REQUIREMENTS) -> str:
+    venv_python = (
+        r"%USERPROFILE%\.venvs\master-skill\Scripts\python"
+        if sys.platform == "win32"
+        else "~/.venvs/master-skill/bin/python"
+    )
+    return "\n".join(
+        [
+            "create-master needs Python packages that are not installed: "
+            + ", ".join(missing_dists),
+            "",
+            f'  python3 -m pip install -r "{requirements}"',
+            "",
+            'If pip refuses with "externally-managed-environment" (PEP 668), use a virtual environment:',
+            "",
+            "  python3 -m venv ~/.venvs/master-skill",
+            f'  {venv_python} -m pip install -r "{requirements}"',
+            "",
+            "and start Claude Code with that environment active, so that `python3` is its interpreter.",
+        ]
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--json", action="store_true", help="print a JSON result")
+    args = parser.parse_args(argv)
+
+    too_old = sys.version_info < MIN_PYTHON
+    absent = missing()
+    ok = not absent and not too_old
+    if args.json:
+        print(
+            json.dumps(
+                {
+                    "ok": ok,
+                    "python": platform.python_version(),
+                    "python_too_old": too_old,
+                    "missing": absent,
+                    "requirements": str(REQUIREMENTS),
+                }
+            )
+        )
+    elif ok:
+        print(f"OK: Python {platform.python_version()} with {', '.join(REQUIRED.values())}")
+    else:
+        if too_old:
+            print(f"create-master needs Python {'.'.join(map(str, MIN_PYTHON))}+; this is {platform.python_version()}.")
+        if absent:
+            print(guidance(absent))
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())