@tacuchi/agent-workflow-cli 4.2.0 → 4.5.0

package/dist/application/plugin-doctor-service.js

@@ -12,6 +12,11 @@
 //
 // `exported_skills` se lee de `.claude-plugin/plugin.json:exportedSkills` o
 // de un --exports-file JSON.
+//
+// Estructura interna (post-session011 G2 refactor):
+// `runPluginDoctor` orquesta 8 helpers self-contained, cada uno con
+// complexity <= 15. Cada helper retorna `{...result, findings}` y el orchestrator
+// agrega los findings al final.
 import { spawnSync } from "node:child_process";
 import { extname, join, relative, resolve, sep } from "node:path";
 const SESSION_SPECIFIC_MARKERS = [
@@ -27,459 +32,538 @@ export async function runPluginDoctor(fs, env, paths, runtime, input) {
         ? resolve(input.pluginRoot.startsWith("/") ? input.pluginRoot : join(cwd, input.pluginRoot))
         : cwd;
     const flow = input.flow ?? "core";
-    const inputPluginVersion = input.pluginVersion ?? null;
     const compatRange = input.compatRange ?? null;
     const skillsDir = join(pluginRoot, "skills");
     const readmePath = join(pluginRoot, "README.md");
+    const skillsResult = await checkSkillsFrontmatter(skillsDir, fs);
+    const readmeResult = await checkReadmeSync(readmePath, skillsResult.skillsCount, fs);
+    const fdFindings = await checkFrontendDesignGeneralization(skillsDir, pluginRoot, fs);
+    const manifestsResult = await parseManifests(pluginRoot, fs, input.pluginVersion ?? null);
+    const isSinglePathContract = isContractVersionAtLeast(manifestsResult.manifestQtcContractVersion, 6, 3);
+    const pluginVersion = manifestsResult.canonicalVersion ?? "unknown";
+    const pluginName = input.pluginName ?? manifestsResult.manifestPluginName ?? `${paths.namespace}-${flow}`;
+    const legacyResult = await checkLegacyMarkers(paths, flow, pluginVersion, compatRange, isSinglePathContract, fs);
+    const hooksResult = await parseHooks(pluginRoot, fs);
+    const mcpResult = await validateMcp(pluginRoot, runtime, env, fs);
+    const exportedResult = await validateExportedSkills(skillsDir, pluginRoot, input.exportsFile, pluginName, skillsResult.skillsInfo, fs);
+    const findings = [
+        ...skillsResult.findings,
+        ...readmeResult.findings,
+        ...fdFindings,
+        ...manifestsResult.findings,
+        ...legacyResult.findings,
+        ...hooksResult.findings,
+        ...mcpResult.findings,
+        ...exportedResult.findings,
+    ];
+    const hasError = findings.some((f) => f.level === "error");
+    const hasWarn = findings.some((f) => f.level === "warn");
+    const status = hasError ? "error" : hasWarn ? "warn" : "ok";
+    return {
+        data: {
+            status,
+            plugin: pluginName,
+            plugin_root: pluginRoot,
+            plugin_version: pluginVersion,
+            qtc_core_installed: legacyResult.qtcCoreInstalled,
+            compat_range: compatRange,
+            compat_ok: legacyResult.compatOk,
+            python_version: legacyResult.pythonVersion,
+            skills_count: skillsResult.skillsCount,
+            readme_count_expected: readmeResult.readmeCountExpected,
+            readme_count_match: readmeResult.readmeCountMatch,
+            manifests: manifestsResult.manifestsInfo,
+            installed_marker: legacyResult.installedMarker,
+            hooks: hooksResult.hooksInfo,
+            mcp: mcpResult.mcpInfo,
+            skills: skillsResult.skillsInfo,
+            exported_skills: exportedResult.exportedInfo,
+            findings,
+        },
+        hasError,
+    };
+}
+async function checkSkillsFrontmatter(skillsDir, fs) {
     const findings = [];
     const skillsInfo = [];
-    // 1. Skills frontmatter.
-    const skillDirs = [];
-    if (await fs.exists(skillsDir)) {
-        const entries = await fs.list(skillsDir);
-        for (const entry of entries) {
-            if (entry.type !== "dir")
-                continue;
-            const skillMd = join(entry.path, "SKILL.md");
-            if (await fs.exists(skillMd))
-                skillDirs.push(entry.path);
-        }
-        skillDirs.sort((a, b) => a.localeCompare(b));
-    }
-    const skillsCount = skillDirs.length;
+    const skillDirs = await collectSkillDirs(skillsDir, fs);
     for (const sd of skillDirs) {
         const skillMd = join(sd, "SKILL.md");
         const dirName = sd.split(sep).pop() ?? "";
-        let content;
-        try {
-            content = await fs.readText(skillMd);
-        }
-        catch (e) {
-            findings.push({ level: "error", file: skillMd, msg: `cannot read: ${e.message}` });
-            skillsInfo.push({ dir: dirName, name: null, version: null });
-            continue;
-        }
-        const lines = content.split(/\r?\n/);
-        if (lines.length === 0 || (lines[0] ?? "").trim() !== "---") {
-            findings.push({ level: "error", file: skillMd, msg: "missing frontmatter opening ---" });
+        const parsed = await parseSkillFile(skillMd, fs);
+        if (parsed.error) {
+            findings.push({ level: "error", file: skillMd, msg: parsed.error });
             skillsInfo.push({ dir: dirName, name: null, version: null });
             continue;
         }
-        let endIdx = -1;
-        for (let i = 1; i < lines.length; i++) {
-            if ((lines[i] ?? "").trim() === "---") {
-                endIdx = i;
-                break;
-            }
-        }
-        if (endIdx === -1) {
-            findings.push({ level: "error", file: skillMd, msg: "missing frontmatter closing ---" });
-            skillsInfo.push({ dir: dirName, name: null, version: null });
+        validateSkillFrontmatter(skillMd, dirName, parsed.frontmatter, findings);
+        skillsInfo.push({
+            dir: dirName,
+            name: parsed.frontmatter.name ?? null,
+            version: parsed.frontmatter.version ?? null,
+        });
+    }
+    return { skillsCount: skillDirs.length, skillsInfo, findings };
+}
+async function collectSkillDirs(skillsDir, fs) {
+    const out = [];
+    if (!(await fs.exists(skillsDir)))
+        return out;
+    const entries = await fs.list(skillsDir);
+    for (const entry of entries) {
+        if (entry.type !== "dir")
             continue;
-        }
-        const fm = {};
-        for (let i = 1; i < endIdx; i++) {
-            const m = (lines[i] ?? "").match(/^(\w+):\s*(.+)$/);
-            if (m?.[1] && m[2] !== undefined)
-                fm[m[1]] = m[2].trim();
-        }
-        const name = fm.name ?? null;
-        const version = fm.version ?? null;
-        const description = fm.description ?? null;
-        if (!name) {
-            findings.push({ level: "error", file: skillMd, msg: "missing 'name' in frontmatter" });
-        }
-        else if (name !== dirName) {
-            findings.push({
-                level: "warn",
-                file: skillMd,
-                msg: `frontmatter name '${name}' differs from directory '${dirName}'`,
-            });
-        }
-        if (!description) {
-            findings.push({ level: "error", file: skillMd, msg: "missing 'description' in frontmatter" });
-        }
-        if (!version) {
-            findings.push({ level: "warn", file: skillMd, msg: "missing 'version' in frontmatter" });
-        }
-        else if (!/^\d+\.\d+\.\d+$/.test(version)) {
-            findings.push({
-                level: "warn",
-                file: skillMd,
-                msg: `version '${version}' not semver-compatible`,
-            });
-        }
-        skillsInfo.push({ dir: dirName, name, version });
+        const skillMd = join(entry.path, "SKILL.md");
+        if (await fs.exists(skillMd))
+            out.push(entry.path);
     }
-    // 2. README sync check.
-    let readmeCountExpected = null;
-    let readmeCountMatch = null;
-    if (await fs.exists(readmePath)) {
-        try {
-            const readmeText = await fs.readText(readmePath);
-            const m = readmeText.match(/\*\*Skills\*\*\s*\((\d+)/);
-            if (m?.[1]) {
-                readmeCountExpected = Number.parseInt(m[1], 10);
-                readmeCountMatch = readmeCountExpected === skillsCount;
-                if (!readmeCountMatch) {
-                    findings.push({
-                        level: "warn",
-                        file: "README.md",
-                        msg: `Skills count mismatch: README claims ${readmeCountExpected}, actual ${skillsCount}`,
-                    });
-                }
-            }
-        }
-        catch (e) {
-            findings.push({
-                level: "warn",
-                file: "README.md",
-                msg: `cannot read: ${e.message}`,
-            });
+    out.sort((a, b) => a.localeCompare(b));
+    return out;
+}
+async function parseSkillFile(skillMd, fs) {
+    let content;
+    try {
+        content = await fs.readText(skillMd);
+    }
+    catch (e) {
+        return { frontmatter: {}, error: `cannot read: ${e.message}` };
+    }
+    const lines = content.split(/\r?\n/);
+    if (lines.length === 0 || (lines[0] ?? "").trim() !== "---") {
+        return { frontmatter: {}, error: "missing frontmatter opening ---" };
+    }
+    let endIdx = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if ((lines[i] ?? "").trim() === "---") {
+            endIdx = i;
+            break;
         }
     }
-    else {
+    if (endIdx === -1) {
+        return { frontmatter: {}, error: "missing frontmatter closing ---" };
+    }
+    const fm = {};
+    for (let i = 1; i < endIdx; i++) {
+        const m = (lines[i] ?? "").match(/^(\w+):\s*(.+)$/);
+        if (m?.[1] && m[2] !== undefined)
+            fm[m[1]] = m[2].trim();
+    }
+    return { frontmatter: fm, error: null };
+}
+function validateSkillFrontmatter(skillMd, dirName, fm, findings) {
+    const { name, version, description } = fm;
+    if (!name) {
+        findings.push({ level: "error", file: skillMd, msg: "missing 'name' in frontmatter" });
+    }
+    else if (name !== dirName) {
+        findings.push({
+            level: "warn",
+            file: skillMd,
+            msg: `frontmatter name '${name}' differs from directory '${dirName}'`,
+        });
+    }
+    if (!description) {
+        findings.push({ level: "error", file: skillMd, msg: "missing 'description' in frontmatter" });
+    }
+    if (!version) {
+        findings.push({ level: "warn", file: skillMd, msg: "missing 'version' in frontmatter" });
+    }
+    else if (!/^\d+\.\d+\.\d+$/.test(version)) {
+        findings.push({
+            level: "warn",
+            file: skillMd,
+            msg: `version '${version}' not semver-compatible`,
+        });
+    }
+}
+async function checkReadmeSync(readmePath, skillsCount, fs) {
+    const findings = [];
+    if (!(await fs.exists(readmePath))) {
         findings.push({ level: "warn", file: "README.md", msg: "README.md not found at plugin root" });
+        return { readmeCountExpected: null, readmeCountMatch: null, findings };
     }
-    // 3. frontend-design generalization.
+    let readmeText;
+    try {
+        readmeText = await fs.readText(readmePath);
+    }
+    catch (e) {
+        findings.push({
+            level: "warn",
+            file: "README.md",
+            msg: `cannot read: ${e.message}`,
+        });
+        return { readmeCountExpected: null, readmeCountMatch: null, findings };
+    }
+    const m = readmeText.match(/\*\*Skills\*\*\s*\((\d+)/);
+    if (!m?.[1]) {
+        return { readmeCountExpected: null, readmeCountMatch: null, findings };
+    }
+    const readmeCountExpected = Number.parseInt(m[1], 10);
+    const readmeCountMatch = readmeCountExpected === skillsCount;
+    if (!readmeCountMatch) {
+        findings.push({
+            level: "warn",
+            file: "README.md",
+            msg: `Skills count mismatch: README claims ${readmeCountExpected}, actual ${skillsCount}`,
+        });
+    }
+    return { readmeCountExpected, readmeCountMatch, findings };
+}
+// ---------- 3. Frontend-design generalization ----------
+async function checkFrontendDesignGeneralization(skillsDir, pluginRoot, fs) {
+    const findings = [];
     const fdDir = join(skillsDir, "frontend-design");
-    if ((await fs.exists(skillsDir)) && (await fs.exists(fdDir))) {
-        const mdFiles = await collectMarkdownFiles(fs, fdDir);
-        mdFiles.sort((a, b) => a.localeCompare(b));
-        for (const mdFile of mdFiles) {
-            let text;
-            try {
-                text = await fs.readText(mdFile);
-            }
-            catch {
-                continue;
-            }
-            for (const marker of SESSION_SPECIFIC_MARKERS) {
-                if (text.includes(marker)) {
-                    const rel = relative(pluginRoot, mdFile).split(sep).join("/");
-                    findings.push({
-                        level: "error",
-                        file: rel,
-                        msg: `contains session-specific name '${marker}' (frontend-design must stay generalized)`,
-                    });
-                }
-            }
+    if (!(await fs.exists(skillsDir)) || !(await fs.exists(fdDir)))
+        return findings;
+    const mdFiles = await collectMarkdownFiles(fs, fdDir);
+    mdFiles.sort((a, b) => a.localeCompare(b));
+    for (const mdFile of mdFiles) {
+        let text;
+        try {
+            text = await fs.readText(mdFile);
         }
+        catch {
+            continue;
+        }
+        scanForSessionMarkers(text, mdFile, pluginRoot, findings);
+    }
+    return findings;
+}
+function scanForSessionMarkers(text, mdFile, pluginRoot, findings) {
+    for (const marker of SESSION_SPECIFIC_MARKERS) {
+        if (!text.includes(marker))
+            continue;
+        const rel = relative(pluginRoot, mdFile).split(sep).join("/");
+        findings.push({
+            level: "error",
+            file: rel,
+            msg: `contains session-specific name '${marker}' (frontend-design must stay generalized)`,
+        });
     }
-    // 4. Manifest version drift + qtcContractVersion gate.
+}
+async function parseManifests(pluginRoot, fs, inputPluginVersion) {
+    const findings = [];
     const manifestsInfo = {};
-    let manifestQtcContractVersion = null;
     let canonicalVersion = inputPluginVersion;
     let manifestPluginName = null;
+    let manifestQtcContractVersion = null;
     for (const relPath of [".claude-plugin/plugin.json", ".codex-plugin/plugin.json"]) {
-        const manifestPath = join(pluginRoot, relPath);
-        if (!(await fs.exists(manifestPath))) {
-            findings.push({ level: "warn", file: relPath, msg: "manifest missing" });
-            manifestsInfo[relPath] = null;
-            continue;
-        }
-        let raw;
-        try {
-            raw = await fs.readText(manifestPath);
-        }
-        catch (e) {
-            findings.push({
-                level: "error",
-                file: relPath,
-                msg: `invalid JSON: ${e.message}`,
-            });
-            manifestsInfo[relPath] = null;
-            continue;
-        }
-        let data;
-        try {
-            data = JSON.parse(raw);
-        }
-        catch (e) {
-            findings.push({
-                level: "error",
-                file: relPath,
-                msg: `invalid JSON: ${e.message}`,
-            });
-            manifestsInfo[relPath] = null;
+        const parsed = await parseManifestFile(join(pluginRoot, relPath), relPath, fs);
+        manifestsInfo[relPath] = parsed.version;
+        findings.push(...parsed.findings);
+        if (parsed.parseError)
             continue;
+        if (manifestPluginName === null && parsed.name !== null) {
+            manifestPluginName = parsed.name;
         }
-        const manifestVersion = isRecord(data) && typeof data.version === "string" ? data.version : null;
-        manifestsInfo[relPath] = manifestVersion;
-        if (manifestPluginName === null &&
-            isRecord(data) &&
-            typeof data.name === "string" &&
-            data.name.length > 0) {
-            manifestPluginName = data.name;
-        }
-        if (canonicalVersion === null && manifestVersion !== null) {
-            canonicalVersion = manifestVersion;
+        if (canonicalVersion === null && parsed.version !== null) {
+            canonicalVersion = parsed.version;
         }
-        else if (canonicalVersion !== null && manifestVersion !== canonicalVersion) {
+        else if (canonicalVersion !== null &&
+            parsed.version !== null &&
+            parsed.version !== canonicalVersion) {
             findings.push({
                 level: "error",
                 file: relPath,
-                msg: `version drift: manifest=${manifestVersion} vs declared=${canonicalVersion}`,
+                msg: `version drift: manifest=${parsed.version} vs declared=${canonicalVersion}`,
             });
         }
-        if (manifestQtcContractVersion === null &&
-            isRecord(data) &&
-            typeof data.qtcContractVersion === "string") {
-            manifestQtcContractVersion = data.qtcContractVersion;
+        if (manifestQtcContractVersion === null && parsed.qtcContractVersion !== null) {
+            manifestQtcContractVersion = parsed.qtcContractVersion;
         }
     }
-    const pluginVersion = canonicalVersion ?? "unknown";
-    const pluginName = input.pluginName ?? manifestPluginName ?? `${paths.namespace}-${flow}`;
-    // Si el manifest declara qtcContractVersion >= 6.3, el plugin opera en
-    // single-path y no debe chequearse la presencia de artefactos legacy.
-    const isSinglePathContract = isContractVersionAtLeast(manifestQtcContractVersion, 6, 3);
-    // 5/5b — checks legacy de era dual-path. Solo el marker de plugin version y
-    // el marker de core-lib se siguen revisando para detectar instalaciones rotas
-    // en plugins viejos. Los scripts Python se eliminaron por completo.
+    return {
+        manifestsInfo,
+        canonicalVersion,
+        manifestPluginName,
+        manifestQtcContractVersion,
+        findings,
+    };
+}
+async function parseManifestFile(manifestPath, relPath, fs) {
+    const findings = [];
+    if (!(await fs.exists(manifestPath))) {
+        findings.push({ level: "warn", file: relPath, msg: "manifest missing" });
+        return { version: null, name: null, qtcContractVersion: null, parseError: true, findings };
+    }
+    let raw;
+    try {
+        raw = await fs.readText(manifestPath);
+    }
+    catch (e) {
+        findings.push({
+            level: "error",
+            file: relPath,
+            msg: `invalid JSON: ${e.message}`,
+        });
+        return { version: null, name: null, qtcContractVersion: null, parseError: true, findings };
+    }
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch (e) {
+        findings.push({
+            level: "error",
+            file: relPath,
+            msg: `invalid JSON: ${e.message}`,
+        });
+        return { version: null, name: null, qtcContractVersion: null, parseError: true, findings };
+    }
+    if (!isRecord(data)) {
+        return { version: null, name: null, qtcContractVersion: null, parseError: false, findings };
+    }
+    return {
+        version: typeof data.version === "string" ? data.version : null,
+        name: typeof data.name === "string" && data.name.length > 0 ? data.name : null,
+        qtcContractVersion: typeof data.qtcContractVersion === "string" ? data.qtcContractVersion : null,
+        parseError: false,
+        findings,
+    };
+}
+async function checkLegacyMarkers(paths, flow, pluginVersion, compatRange, isSinglePathContract, fs) {
+    const findings = [];
+    if (isSinglePathContract) {
+        return {
+            installedMarker: null,
+            qtcCoreInstalled: null,
+            compatOk: null,
+            pythonVersion: null,
+            findings,
+        };
+    }
+    const installedMarker = await readPluginVersionMarker(paths, flow, pluginVersion, fs, findings);
+    const coreLibMarker = paths.userCoreLibMarker();
+    const qtcCoreInstalled = await readMarkerText(coreLibMarker, fs);
+    const compatOk = compatRange
+        ? evaluateCompat(qtcCoreInstalled, compatRange, coreLibMarker, findings)
+        : null;
+    const pythonVersion = checkPythonVersion(findings);
+    return { installedMarker, qtcCoreInstalled, compatOk, pythonVersion, findings };
+}
+async function readPluginVersionMarker(paths, flow, pluginVersion, fs, findings) {
+    const markerFile = paths.userPluginVersionFile(flow);
+    if (!(await fs.exists(markerFile)))
+        return null;
     let installedMarker = null;
-    let qtcCoreInstalled = null;
-    let compatOk = null;
-    if (!isSinglePathContract) {
-        // 5. Marker file (~/.<ns>/<flow>/.plugin-version) — solo legacy.
-        const markerFile = paths.userPluginVersionFile(flow);
-        if (await fs.exists(markerFile)) {
-            try {
-                const raw = (await fs.readText(markerFile)).trim();
-                installedMarker = raw.length > 0 ? raw : null;
-            }
-            catch (e) {
-                findings.push({
-                    level: "warn",
-                    file: markerFile,
-                    msg: `cannot read marker: ${e.message}`,
-                });
-            }
-            if (installedMarker && installedMarker !== pluginVersion) {
-                findings.push({
-                    level: "warn",
-                    file: markerFile,
-                    msg: `installed plugin v${installedMarker} differs from declared v${pluginVersion} — reinstall/re-sync`,
-                });
-            }
-        }
-        // 5b. core lib install state + compat range — solo legacy.
-        const coreLibMarker = paths.userCoreLibMarker();
-        if (await fs.exists(coreLibMarker)) {
-            try {
-                const raw = (await fs.readText(coreLibMarker)).trim();
-                qtcCoreInstalled = raw.length > 0 ? raw : null;
-            }
-            catch {
-                // ignore
-            }
-        }
-        if (compatRange) {
-            compatOk = evaluateCompat(qtcCoreInstalled, compatRange, coreLibMarker, findings);
-        }
+    try {
+        const raw = (await fs.readText(markerFile)).trim();
+        installedMarker = raw.length > 0 ? raw : null;
     }
-    // 7. Hooks JSON.
+    catch (e) {
+        findings.push({
+            level: "warn",
+            file: markerFile,
+            msg: `cannot read marker: ${e.message}`,
+        });
+    }
+    if (installedMarker && installedMarker !== pluginVersion) {
+        findings.push({
+            level: "warn",
+            file: markerFile,
+            msg: `installed plugin v${installedMarker} differs from declared v${pluginVersion} — reinstall/re-sync`,
+        });
+    }
+    return installedMarker;
+}
+async function readMarkerText(markerFile, fs) {
+    if (!(await fs.exists(markerFile)))
+        return null;
+    try {
+        const raw = (await fs.readText(markerFile)).trim();
+        return raw.length > 0 ? raw : null;
+    }
+    catch {
+        return null;
+    }
+}
+function checkPythonVersion(findings) {
+    const pythonVersion = detectPythonVersion();
+    if (!pythonVersion)
+        return null;
+    const m = pythonVersion.match(/^(\d+)\.(\d+)/);
+    if (!m?.[1] || !m[2])
+        return pythonVersion;
+    const major = Number.parseInt(m[1], 10);
+    const minor = Number.parseInt(m[2], 10);
+    if (major < 3 || (major === 3 && minor < 8)) {
+        findings.push({
+            level: "warn",
+            file: "python",
+            msg: `python ${pythonVersion} is too old; recommend 3.8+`,
+        });
+    }
+    return pythonVersion;
+}
+async function parseHooks(pluginRoot, fs) {
+    const findings = [];
     const hooksInfo = {};
     for (const relPath of ["hooks/hooks.json", "codex-hooks/hooks.json"]) {
-        const hookPath = join(pluginRoot, relPath);
-        if (!(await fs.exists(hookPath))) {
-            findings.push({ level: "warn", file: relPath, msg: "hooks file missing" });
-            hooksInfo[relPath] = null;
-            continue;
-        }
-        let raw;
-        try {
-            raw = await fs.readText(hookPath);
-        }
-        catch (e) {
-            findings.push({
-                level: "error",
-                file: relPath,
-                msg: `invalid JSON: ${e.message}`,
-            });
-            hooksInfo[relPath] = null;
-            continue;
-        }
-        let data;
-        try {
-            data = JSON.parse(raw);
-        }
-        catch (e) {
-            findings.push({
-                level: "error",
-                file: relPath,
-                msg: `invalid JSON: ${e.message}`,
-            });
-            hooksInfo[relPath] = null;
-            continue;
-        }
-        if (!isRecord(data) || !("hooks" in data) || !isRecord(data.hooks)) {
-            findings.push({
-                level: "warn",
-                file: relPath,
-                msg: "hooks JSON missing top-level 'hooks' key",
-            });
-            hooksInfo[relPath] = "invalid-structure";
-        }
-        else {
-            hooksInfo[relPath] = Object.keys(data.hooks).sort();
-        }
+        const result = await parseHookFile(join(pluginRoot, relPath), relPath, fs);
+        hooksInfo[relPath] = result.value;
+        findings.push(...result.findings);
+    }
+    return { hooksInfo, findings };
+}
+async function parseHookFile(hookPath, relPath, fs) {
+    const findings = [];
+    if (!(await fs.exists(hookPath))) {
+        findings.push({ level: "warn", file: relPath, msg: "hooks file missing" });
+        return { value: null, findings };
+    }
+    let raw;
+    try {
+        raw = await fs.readText(hookPath);
+    }
+    catch (e) {
+        findings.push({
+            level: "error",
+            file: relPath,
+            msg: `invalid JSON: ${e.message}`,
+        });
+        return { value: null, findings };
     }
-    // 8. MCP — servidores esperados leídos del runtime config (Phase 3).
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch (e) {
+        findings.push({
+            level: "error",
+            file: relPath,
+            msg: `invalid JSON: ${e.message}`,
+        });
+        return { value: null, findings };
+    }
+    if (!isRecord(data) || !("hooks" in data) || !isRecord(data.hooks)) {
+        findings.push({
+            level: "warn",
+            file: relPath,
+            msg: "hooks JSON missing top-level 'hooks' key",
+        });
+        return { value: "invalid-structure", findings };
+    }
+    return { value: Object.keys(data.hooks).sort(), findings };
+}
+async function validateMcp(pluginRoot, runtime, env, fs) {
+    const findings = [];
     const mcpInfo = {};
     const mcpPath = join(pluginRoot, ".mcp.json");
     const expectedMcpServers = runtime.expectedMcpServers ?? [];
-    if (expectedMcpServers.length > 0 && (await fs.exists(mcpPath))) {
-        let mcpData = null;
-        try {
-            mcpData = JSON.parse(await fs.readText(mcpPath));
-        }
-        catch (e) {
-            findings.push({
-                level: "error",
-                file: ".mcp.json",
-                msg: `invalid JSON: ${e.message}`,
-            });
-        }
-        if (mcpData !== null && isRecord(mcpData)) {
-            const servers = isRecord(mcpData.mcpServers) ? mcpData.mcpServers : {};
-            for (const exp of expectedMcpServers) {
-                const server = servers[exp];
-                if (server === undefined) {
-                    findings.push({
-                        level: "warn",
-                        file: ".mcp.json",
-                        msg: `expected server '${exp}' not configured`,
-                    });
-                    mcpInfo[exp] = "missing";
-                    continue;
-                }
-                const dsnRaw = isRecord(server) && isRecord(server.env) && typeof server.env.DSN === "string"
-                    ? server.env.DSN
-                    : "";
-                const m = dsnRaw.match(/^\$\{(\w+)\}$/);
-                if (m?.[1]) {
-                    const envVar = m[1];
-                    const envSet = Boolean(env.get(envVar));
-                    mcpInfo[exp] = { dsn_env: envVar, env_set: envSet };
-                    if (!envSet) {
-                        findings.push({
-                            level: "warn",
-                            file: ".mcp.json",
-                            msg: `env var ${envVar} not set (required by mcp server '${exp}')`,
-                        });
-                    }
-                }
-                else {
-                    mcpInfo[exp] = { dsn_env: null, env_set: null };
-                }
-            }
-        }
+    if (expectedMcpServers.length === 0 || !(await fs.exists(mcpPath))) {
+        return { mcpInfo, findings };
     }
-    // 9. Python version — solo legacy. En single-path no existe runtime Python.
-    let pythonVersion = null;
-    if (!isSinglePathContract) {
-        pythonVersion = detectPythonVersion();
-        if (pythonVersion) {
-            const m = pythonVersion.match(/^(\d+)\.(\d+)/);
-            if (m?.[1] && m[2]) {
-                const major = Number.parseInt(m[1], 10);
-                const minor = Number.parseInt(m[2], 10);
-                if (major < 3 || (major === 3 && minor < 8)) {
-                    findings.push({
-                        level: "warn",
-                        file: "python",
-                        msg: `python ${pythonVersion} is too old; recommend 3.8+`,
-                    });
-                }
-            }
-        }
+    let mcpData = null;
+    try {
+        mcpData = JSON.parse(await fs.readText(mcpPath));
+    }
+    catch (e) {
+        findings.push({
+            level: "error",
+            file: ".mcp.json",
+            msg: `invalid JSON: ${e.message}`,
+        });
+        return { mcpInfo, findings };
+    }
+    if (!isRecord(mcpData))
+        return { mcpInfo, findings };
+    const servers = isRecord(mcpData.mcpServers) ? mcpData.mcpServers : {};
+    for (const exp of expectedMcpServers) {
+        const server = servers[exp];
+        mcpInfo[exp] = validateMcpServer(server, exp, env, findings);
+    }
+    return { mcpInfo, findings };
+}
+function validateMcpServer(server, exp, env, findings) {
+    if (server === undefined) {
+        findings.push({
+            level: "warn",
+            file: ".mcp.json",
+            msg: `expected server '${exp}' not configured`,
+        });
+        return "missing";
     }
-    // 10. Exported skills.
+    const dsnRaw = isRecord(server) && isRecord(server.env) && typeof server.env.DSN === "string"
+        ? server.env.DSN
+        : "";
+    const m = dsnRaw.match(/^\$\{(\w+)\}$/);
+    if (!m?.[1])
+        return { dsn_env: null, env_set: null };
+    const envVar = m[1];
+    const envSet = Boolean(env.get(envVar));
+    if (!envSet) {
+        findings.push({
+            level: "warn",
+            file: ".mcp.json",
+            msg: `env var ${envVar} not set (required by mcp server '${exp}')`,
+        });
+    }
+    return { dsn_env: envVar, env_set: envSet };
+}
+async function validateExportedSkills(skillsDir, pluginRoot, exportsFile, pluginName, skillsInfo, fs) {
+    const findings = [];
     const exportedInfo = [];
-    const exportedSkills = await loadExportedSkills(fs, pluginRoot, input.exportsFile, pluginName);
-    const skillsByName = new Map();
+    const exportedSkills = await loadExportedSkills(fs, pluginRoot, exportsFile, pluginName);
+    const skillsByDirName = new Map();
     for (const s of skillsInfo) {
         if (s.name)
-            skillsByName.set(s.dir, s);
+            skillsByDirName.set(s.dir, s);
     }
+    const skillsDirExists = await fs.exists(skillsDir);
     for (const exp of exportedSkills) {
-        const expSkillName = exp.skill;
-        const record = {
-            namespace: exp.namespace,
-            version_declared: exp.version ?? null,
-            since: exp.since ?? null,
-            exists_in_disk: false,
-            frontmatter_ok: false,
-        };
-        if (await fs.exists(skillsDir)) {
-            const target = join(skillsDir, expSkillName);
-            const targetSkill = join(target, "SKILL.md");
-            if (await fs.exists(targetSkill)) {
-                record.exists_in_disk = true;
-                const diskSkill = skillsByName.get(expSkillName);
-                if (diskSkill?.name && diskSkill.version) {
-                    record.frontmatter_ok = true;
-                    record.version_in_skill = diskSkill.version;
-                    if (diskSkill.version && exp.version && diskSkill.version !== exp.version) {
-                        findings.push({
-                            level: "warn",
-                            file: `skills/${expSkillName}/SKILL.md`,
-                            msg: `exported skill version drift: registry declares ${exp.version}, SKILL.md frontmatter declares ${diskSkill.version}`,
-                        });
-                    }
-                }
-                else {
-                    findings.push({
-                        level: "error",
-                        file: `skills/${expSkillName}/SKILL.md`,
-                        msg: "exported skill SKILL.md missing required frontmatter (name + version)",
-                    });
-                }
-            }
-            else {
-                findings.push({
-                    level: "error",
-                    file: `skills/${expSkillName}/SKILL.md`,
-                    msg: `exported skill '${exp.namespace}' registered but not found in plugin's skills/ directory — fix the register_exported_skill call or add the SKILL.md`,
-                });
-            }
-        }
-        else {
-            findings.push({
-                level: "error",
-                file: "skills/",
-                msg: `exported skill '${exp.namespace}' registered but plugin has no skills/ directory`,
-            });
-        }
+        const record = await validateSingleExportedSkill(exp, skillsDir, skillsDirExists, skillsByDirName, fs, findings);
         exportedInfo.push(record);
     }
-    const hasError = findings.some((f) => f.level === "error");
-    const hasWarn = findings.some((f) => f.level === "warn");
-    const status = hasError ? "error" : hasWarn ? "warn" : "ok";
-    return {
-        data: {
-            status,
-            plugin: pluginName,
-            plugin_root: pluginRoot,
-            plugin_version: pluginVersion,
-            qtc_core_installed: qtcCoreInstalled,
-            compat_range: compatRange,
-            compat_ok: compatOk,
-            python_version: pythonVersion,
-            skills_count: skillsCount,
-            readme_count_expected: readmeCountExpected,
-            readme_count_match: readmeCountMatch,
-            manifests: manifestsInfo,
-            installed_marker: installedMarker,
-            hooks: hooksInfo,
-            mcp: mcpInfo,
-            skills: skillsInfo,
-            exported_skills: exportedInfo,
-            findings,
-        },
-        hasError,
+    return { exportedInfo, findings };
+}
+async function validateSingleExportedSkill(exp, skillsDir, skillsDirExists, skillsByDirName, fs, findings) {
+    const expSkillName = exp.skill;
+    const record = {
+        namespace: exp.namespace,
+        version_declared: exp.version ?? null,
+        since: exp.since ?? null,
+        exists_in_disk: false,
+        frontmatter_ok: false,
     };
+    if (!skillsDirExists) {
+        findings.push({
+            level: "error",
+            file: "skills/",
+            msg: `exported skill '${exp.namespace}' registered but plugin has no skills/ directory`,
+        });
+        return record;
+    }
+    const targetSkill = join(skillsDir, expSkillName, "SKILL.md");
+    if (!(await fs.exists(targetSkill))) {
+        findings.push({
+            level: "error",
+            file: `skills/${expSkillName}/SKILL.md`,
+            msg: `exported skill '${exp.namespace}' registered but not found in plugin's skills/ directory — fix the register_exported_skill call or add the SKILL.md`,
+        });
+        return record;
+    }
+    record.exists_in_disk = true;
+    const diskSkill = skillsByDirName.get(expSkillName);
+    if (!diskSkill?.name || !diskSkill.version) {
+        findings.push({
+            level: "error",
+            file: `skills/${expSkillName}/SKILL.md`,
+            msg: "exported skill SKILL.md missing required frontmatter (name + version)",
+        });
+        return record;
+    }
+    record.frontmatter_ok = true;
+    record.version_in_skill = diskSkill.version;
+    if (exp.version && diskSkill.version !== exp.version) {
+        findings.push({
+            level: "warn",
+            file: `skills/${expSkillName}/SKILL.md`,
+            msg: `exported skill version drift: registry declares ${exp.version}, SKILL.md frontmatter declares ${diskSkill.version}`,
+        });
+    }
+    return record;
 }
+// ---------- compat range evaluation (unchanged) ----------
 function evaluateCompat(qtcCoreInstalled, compatRange, coreLibMarker, findings) {
     if (!qtcCoreInstalled) {
         findings.push({
@@ -507,56 +591,68 @@ function evaluateCompat(qtcCoreInstalled, compatRange, coreLibMarker, findings)
     return compatOk;
 }
 async function loadExportedSkills(fs, pluginRoot, exportsFile, pluginName) {
-    const sources = [];
-    if (exportsFile) {
-        if (await fs.exists(exportsFile)) {
-            try {
-                sources.push(JSON.parse(await fs.readText(exportsFile)));
-            }
-            catch {
-                // ignore
-            }
-        }
+    const sources = exportsFile
+        ? await readExportsFromCustomFile(fs, exportsFile)
+        : await readExportsFromClaudeManifest(fs, pluginRoot);
+    return parseExportedSkillEntries(sources, pluginName);
+}
+async function readExportsFromCustomFile(fs, exportsFile) {
+    if (!(await fs.exists(exportsFile)))
+        return [];
+    try {
+        return [JSON.parse(await fs.readText(exportsFile))];
     }
-    else {
-        const claudeManifest = join(pluginRoot, ".claude-plugin", "plugin.json");
-        if (await fs.exists(claudeManifest)) {
-            try {
-                const data = JSON.parse(await fs.readText(claudeManifest));
-                if (isRecord(data) && Array.isArray(data.exportedSkills)) {
-                    sources.push(data.exportedSkills);
-                }
-            }
-            catch {
-                // ignore
-            }
+    catch {
+        return [];
+    }
+}
+async function readExportsFromClaudeManifest(fs, pluginRoot) {
+    const claudeManifest = join(pluginRoot, ".claude-plugin", "plugin.json");
+    if (!(await fs.exists(claudeManifest)))
+        return [];
+    try {
+        const data = JSON.parse(await fs.readText(claudeManifest));
+        if (isRecord(data) && Array.isArray(data.exportedSkills)) {
+            return [data.exportedSkills];
         }
     }
+    catch {
+        // ignore
+    }
+    return [];
+}
+function parseExportedSkillEntries(sources, pluginName) {
     const out = [];
     for (const src of sources) {
         if (!Array.isArray(src))
             continue;
         for (const item of src) {
-            if (!isRecord(item))
-                continue;
-            const skill = typeof item.skill === "string" ? item.skill : null;
-            if (!skill)
-                continue;
-            const plugin = typeof item.plugin === "string" && item.plugin.length > 0 ? item.plugin : pluginName;
-            const namespace = typeof item.namespace === "string" && item.namespace.length > 0
-                ? item.namespace
-                : `${plugin}:${skill}`;
-            out.push({
-                plugin,
-                skill,
-                namespace,
-                version: typeof item.version === "string" ? item.version : null,
-                since: typeof item.since === "string" ? item.since : null,
-            });
+            const entry = parseExportedSkillItem(item, pluginName);
+            if (entry)
+                out.push(entry);
         }
     }
     return out;
 }
+function parseExportedSkillItem(item, pluginName) {
+    if (!isRecord(item))
+        return null;
+    const skill = typeof item.skill === "string" ? item.skill : null;
+    if (!skill)
+        return null;
+    const plugin = typeof item.plugin === "string" && item.plugin.length > 0 ? item.plugin : pluginName;
+    const namespace = typeof item.namespace === "string" && item.namespace.length > 0
+        ? item.namespace
+        : `${plugin}:${skill}`;
+    return {
+        plugin,
+        skill,
+        namespace,
+        version: typeof item.version === "string" ? item.version : null,
+        since: typeof item.since === "string" ? item.since : null,
+    };
+}
+// ---------- low-level utilities (unchanged) ----------
 async function collectMarkdownFiles(fs, dir) {
     const out = [];
     const stack = [dir];