master-skill 0.12.13 → 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.13",
+      "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.13",
+  "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.13",
+  "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;
 }
@@ -503,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)) {
@@ -565,6 +610,15 @@ 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/;
   // deleting or moving a generated persona by hand leaves its link pointing at
   // nothing. (`uninstall create-master` refuses while personas exist, and with

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.13",
+  "version": "0.12.14",
   "contextFileName": "GEMINI.md"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "master-skill",
-  "version": "0.12.13",
+  "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())