cckit 0.1.0__py3-none-any.whl

cckit/doctor.py

@@ -0,0 +1,185 @@
+"""cckit doctor —— 只诊断不自动修,每项给出可复制修复命令。
+
+检查项覆盖 Docs/04 的 doctor 表:uv 在 PATH、悬空 link、link 指向与 registry
+一致、env 完整+解释器可执行、系统依赖、disableSkillShellExecution、清单预算、
+同名冲突。这些大多是"不检查就 debug 一整天"的静默失效。
+--fix 只处理明确安全的项:清理悬空 link、重建损坏的 python env。
+"""
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+from . import config, env as env_mod, link, manifest, registry, state
+from .errors import CckitError
+
+
+@dataclass
+class Finding:
+    check: str
+    status: str  # ok | warn | error
+    message: str
+    fix: str | None = None
+
+
+def run(fix: bool = False) -> list[Finding]:
+    findings: list[Finding] = []
+
+    # 1. uv 是否在 PATH
+    if shutil.which("uv"):
+        findings.append(Finding("uv", "ok", "uv 在 PATH 中"))
+    else:
+        findings.append(Finding(
+            "uv", "error", "找不到 uv,无法建 env",
+            "安装 uv: https://docs.astral.sh/uv/getting-started/installation/"))
+
+    findings += _check_links()
+    findings += _check_envs()
+    findings += _check_system_deps()
+    findings += _check_shell_execution()
+    findings += _check_budget()
+    findings += _check_name_conflicts()
+
+    if fix:
+        _apply_fixes(findings)
+
+    return findings
+
+
+def _check_links() -> list[Finding]:
+    findings: list[Finding] = []
+    # 复用 state 的作用域/link 解析,不自己扫目录(避免两套扫描逻辑漂移)
+    for _, d in state.scope_skills_dirs():
+        if not d.is_dir():
+            continue
+        for entry in d.iterdir():
+            if link.is_dangling(entry):
+                findings.append(Finding(
+                    "link", "error", f"悬空链接: {entry}(目标已消失)",
+                    f"清理:`cckit doctor --fix` 或手动删除 {entry}"))
+            elif link.is_link(entry):
+                target = entry.resolve()
+                kit = state.resolve_managed_kit(target)
+                if kit:
+                    rec = registry.get_kit(kit)
+                    rec_store = rec.get("store") if rec else None
+                    if rec_store and Path(rec_store) != target.parent:
+                        findings.append(Finding(
+                            "link", "warn",
+                            f"link {entry} 指向 {target},与 registry 记录 {rec_store} 不一致(手工改动导致漂移)",
+                            f"重建:`cckit remove {kit}` 后重新 add"))
+    return findings
+
+
+def _check_envs() -> list[Finding]:
+    findings: list[Finding] = []
+    for kit, info in registry.load().get("kits", {}).items():
+        for sk in info.get("skills", []):
+            for runtime, env_dir in (sk.get("envs") or {}).items():
+                label = f"{kit}/{sk['name']} [{runtime}]"
+                if env_mod.check_env(Path(env_dir), runtime):
+                    findings.append(Finding("env", "ok", f"{label} env 完整"))
+                else:
+                    findings.append(Finding(
+                        "env", "error", f"{label} env 缺失或解释器不可执行",
+                        f"重建:`cckit doctor --fix` 或 `cckit remove {kit}` 后重新 add"))
+    return findings
+
+
+def _check_system_deps() -> list[Finding]:
+    findings: list[Finding] = []
+    platform = config.platform_name()
+    for kit, info in registry.load().get("kits", {}).items():
+        mf = Path(info.get("store", "")) / "cckit.yaml"
+        if not mf.is_file():
+            continue
+        data = manifest.load(mf)
+        for dep in (data.get("requires") or {}).get("system", []):
+            bin_ = dep["bin"]
+            if shutil.which(bin_):
+                findings.append(Finding("system", "ok", f"{bin_} 可用({kit})"))
+            else:
+                hint = (dep.get("hint") or {}).get(platform)
+                findings.append(Finding(
+                    "system", "warn", f"{bin_} 缺失({kit})",
+                    hint or f"请手动安装 {bin_}"))
+    return findings
+
+
+def _check_shell_execution() -> list[Finding]:
+    findings: list[Finding] = []
+    for scope, label in (("global", "全局"), ("project", "项目")):
+        try:
+            settings = state.read_settings(scope)
+        except CckitError:
+            continue
+        if settings.get("disableSkillShellExecution"):
+            findings.append(Finding(
+                "settings", "error",
+                f"{label} settings 开启了 disableSkillShellExecution,"
+                f"所有带脚本 skill 会静默失效",
+                f"把 {label} settings.json 的 disableSkillShellExecution 改为 false 或删除"))
+    return findings
+
+
+def _check_budget() -> list[Finding]:
+    used, limit = state.budget()
+    if used > limit:
+        return [Finding(
+            "budget", "error",
+            f"清单预算超限: {used} / {limit} 字符,description 会被静默丢弃",
+            "把不常用 skill 降为 name-only:`cckit name-only <skill>`")]
+    return [Finding("budget", "ok", f"清单预算: {used} / {limit} 字符")]
+
+
+def _check_name_conflicts() -> list[Finding]:
+    findings: list[Finding] = []
+    # 复用 state.list_skills 的扫描结果,不自己枚举目录
+    by_name: dict[str, set[tuple[str, str | None]]] = {}
+    for s in state.list_skills(None):
+        if s.state == "installed":
+            continue  # 没 link 不被扫描,不参与覆盖
+        by_name.setdefault(s.name, set()).add((s.scope, s.kit))
+    for name, identities in sorted(by_name.items()):
+        g = {kit for scope, kit in identities if scope == "global"}
+        p = {kit for scope, kit in identities if scope == "project"}
+        if not g or not p:
+            continue
+        # 同一个 managed kit 的 skill 同时出现在全局与项目作用域 = D-15 的
+        # "全局 skill 按项目覆盖",不是同名冲突;同名冲突必须来自不同来源。
+        if g == p and len(g) == 1 and None not in g:
+            continue
+        findings.append(Finding(
+            "conflict", "warn",
+            f"同名 skill {name!r} 同时存在全局与项目,全局会覆盖项目版",
+            f"二选一:`cckit disable {name}`(全局)或 `cckit disable {name} --project`"))
+    return findings
+
+
+def _apply_fixes(findings: list[Finding]) -> None:
+    """只做明确安全的修复:清理悬空 link、重建损坏的 python/node env。"""
+    for _, d in state.scope_skills_dirs():
+        if not d.is_dir():
+            continue
+        for entry in d.iterdir():
+            if link.is_dangling(entry):
+                link.remove(entry)
+
+    for kit, info in registry.load().get("kits", {}).items():
+        mf = Path(info.get("store", "")) / "cckit.yaml"
+        if not mf.is_file():
+            continue
+        data = manifest.load(mf)
+        requires = data.get("requires") or {}
+        py_file = (requires.get("python") or {}).get("file")
+        node_file = (requires.get("node") or {}).get("file")
+        req = Path(info.get("store", "")) / py_file if py_file else None
+        pkg = Path(info.get("store", "")) / node_file if node_file else None
+        constraint = (requires.get("runtime") or {}).get("python")
+        for sk in info.get("skills", []):
+            for runtime, env_dir in (sk.get("envs") or {}).items():
+                if runtime == "python" and not env_mod.check_env(Path(env_dir), "python"):
+                    env_mod.create_python_env(Path(env_dir), constraint, req)
+                elif runtime == "node" and not env_mod.check_env(Path(env_dir), "node"):
+                    env_mod.create_node_env(Path(env_dir), pkg)

cckit/env.py

@@ -0,0 +1,54 @@
+"""skill 运行环境:uv venv 创建与依赖安装、解释器解析。
+
+平台差异(venv 布局:Windows Scripts/ vs POSIX bin/)只在这里出现,
+上层只问"这个 skill 的解释器在哪",不关心平台。
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+from .errors import CckitError
+
+
+def python_interpreter(env_dir: Path) -> Path:
+    """venv 内 python 解释器路径。Windows 在 Scripts/,POSIX 在 bin/。"""
+    if os.name == "nt":
+        return env_dir / "Scripts" / "python.exe"
+    return env_dir / "bin" / "python"
+
+
+def create_python_env(env_dir: Path, python_constraint: str | None = None,
+                      requirements: Path | None = None) -> None:
+    """uv venv 建环境,并按 requirements.txt 装依赖(uv pip install)。"""
+    env_dir.parent.mkdir(parents=True, exist_ok=True)
+    cmd = ["uv", "venv", str(env_dir)]
+    if python_constraint:
+        cmd += ["--python", python_constraint]
+    subprocess.run(cmd, check=True)
+    if requirements and requirements.is_file():
+        interp = python_interpreter(env_dir)
+        subprocess.run(
+            ["uv", "pip", "install", "-r", str(requirements), "--python", str(interp)],
+            check=True,
+        )
+
+
+def create_node_env(env_dir: Path, package_json: Path | None = None) -> None:
+    """Node 环境:把 package.json 拷进 env 目录再 npm install。"""
+    env_dir.mkdir(parents=True, exist_ok=True)
+    if package_json and package_json.is_file():
+        shutil.copy(package_json, env_dir / "package.json")
+        subprocess.run(["npm", "install", "--prefix", str(env_dir)], check=True)
+
+
+def check_env(env_dir: Path, runtime: str) -> bool:
+    """env 是否完整且解释器可执行。"""
+    if runtime == "python":
+        p = python_interpreter(env_dir)
+        return p.is_file() and os.access(p, os.X_OK)
+    if runtime == "node":
+        return (env_dir / "node_modules").is_dir()
+    return False

cckit/errors.py

@@ -0,0 +1,10 @@
+"""cckit 的受检错误。
+
+所有面向用户的错误都应是 CckitError(或其子类),cli.main 捕获它打印
+"错误: ..." 并返回非零退出码,而不是把堆栈甩给用户。
+"""
+from __future__ import annotations
+
+
+class CckitError(Exception):
+    """cckit 的受检错误:可安全展示给用户,无需堆栈。"""

cckit/exec.py

@@ -0,0 +1,104 @@
+"""cckit exec —— skill 脚本的统一入口。
+
+定位 skill/env、解析解释器、注入 CCKIT_SKILL_DIR / CCKIT_KIT_DIR /
+CCKIT_ENV_DIR 与 manifest env 变量、记录用量(追加 ~/.cckit/usage.jsonl,
+天然并发安全)、cwd 保持调用方 cwd。scripts 未在 manifest 声明的路径拒绝执行。
+"""
+from __future__ import annotations
+
+import datetime
+import json
+import os
+import subprocess
+from pathlib import Path
+
+from . import config, env as env_mod, manifest, registry
+from .errors import CckitError
+
+
+class ExecError(CckitError):
+    """exec 失败。"""
+
+
+def _runtime_for_script(script_path: Path) -> str:
+    """脚本扩展名 → runtime。.py → python;.js/.mjs → node。"""
+    ext = script_path.suffix.lower()
+    if ext == ".py":
+        return "python"
+    if ext in (".js", ".mjs"):
+        return "node"
+    raise ExecError(f"不支持的脚本类型 {script_path.name}(v0.1 仅支持 .py/.js/.mjs)")
+
+
+def run(skill: str, script: str, args: list[str], scope: str = "global") -> int:
+    # 按作用域定位:同名 skill 全局/项目各装一份时,靠 scope 消歧。
+    kit_name, skill_info = registry.find_skill(skill, scope)
+    kit_info = registry.get_kit(kit_name)
+
+    store = Path(kit_info["store"])
+    data = manifest.load(store / "cckit.yaml")
+    skill_def = next((s for s in data.get("skills", []) if s["name"] == skill), None)
+    if skill_def is None:
+        raise ExecError(f"skill {skill!r} 不在 kit {kit_name} 的 skills[] 中")
+
+    # 脚本白名单:未在 manifest scripts[] 声明的路径拒绝执行
+    whitelist = set(skill_def.get("scripts") or [])
+    if script not in whitelist:
+        raise ExecError(f"脚本 {script!r} 未在 manifest 的 scripts[] 中声明,拒绝执行")
+
+    skill_dir = (store / skill).resolve()
+    script_path = (skill_dir / script).resolve()
+    if not script_path.is_file():
+        raise ExecError(f"脚本不存在: {script_path}")
+    if not script_path.is_relative_to(skill_dir):
+        raise ExecError(f"脚本路径越出 skill 目录,拒绝执行: {script}")
+
+    # 按脚本扩展名选 runtime,再取对应 env(一个 skill 可同时有 python 与 node)
+    runtime = _runtime_for_script(script_path)
+    envs = skill_info.get("envs") or {}
+    env_dir = Path(envs[runtime]) if envs.get(runtime) else None
+    if env_dir is None or not env_mod.check_env(env_dir, runtime):
+        raise ExecError(f"skill {skill!r} 的 {runtime} env 缺失或损坏,请运行 `cckit doctor`")
+    interp = str(env_mod.python_interpreter(env_dir)) if runtime == "python" else "node"
+
+    # 注入环境变量
+    env = os.environ.copy()
+    env["CCKIT_SKILL_DIR"] = str(skill_dir)
+    env["CCKIT_KIT_DIR"] = str(store)
+    env["CCKIT_ENV_DIR"] = str(env_dir)
+    if runtime == "node":
+        # node_modules 装在 env 目录下,require() 需要 NODE_PATH 才找得到
+        env["NODE_PATH"] = str(env_dir / "node_modules")
+    for var in data.get("env", []):
+        name = var.get("name")
+        if not name:
+            continue
+        if name in os.environ:
+            env[name] = os.environ[name]
+        elif var.get("required"):
+            raise ExecError(
+                f"缺少必需的 manifest 环境变量 {name!r}({var.get('description', '')})")
+
+    _record_usage(skill, kit_name, script, runtime)
+
+    # cwd 保持调用方 cwd(不 chdir),相对路径正常解析。
+    cmd = [interp, str(script_path), *args]
+    try:
+        proc = subprocess.run(cmd, env=env)
+    except FileNotFoundError as e:
+        raise ExecError(f"无法执行 {interp}: {e}")
+    return proc.returncode
+
+
+def _record_usage(skill: str, kit: str, script: str, runtime: str) -> None:
+    path = config.usage_log_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    rec = {
+        "ts": datetime.datetime.now(datetime.timezone.utc).isoformat(),
+        "skill": skill,
+        "kit": kit,
+        "script": script,
+        "runtime": runtime,
+    }
+    with open(path, "a", encoding="utf-8") as f:
+        f.write(json.dumps(rec, ensure_ascii=False) + "\n")