claudecode-linter 2.1.148 → 2.1.150

package/dist/formatters/human.js

@@ -1,4 +1,5 @@
 import pc from "picocolors";
+import { sanitizeForTerminal } from "../utils/terminal.js";
 const SEVERITY_ICONS = {
     error: pc.red("error"),
     warning: pc.yellow("warn "),
@@ -16,12 +17,12 @@ export function formatHuman(results, quiet) {
         if (filtered.length === 0)
             continue;
         lines.push("");
-        lines.push(pc.underline(result.file));
+        lines.push(pc.underline(sanitizeForTerminal(result.file)));
         for (const d of filtered) {
             const loc = d.line
                 ? pc.dim(`:${d.line}${d.column ? `:${d.column}` : ""}`)
                 : "";
-            lines.push(`  ${SEVERITY_ICONS[d.severity]}  ${d.message}  ${pc.dim(d.rule)}${loc}`);
+            lines.push(`  ${SEVERITY_ICONS[d.severity]}  ${sanitizeForTerminal(d.message)}  ${pc.dim(d.rule)}${loc}`);
             if (d.severity === "error")
                 errorCount++;
             else if (d.severity === "warning")

package/dist/index.js

@@ -1,10 +1,13 @@
 #!/usr/bin/env node
-import { readFileSync, writeFileSync, copyFileSync, existsSync } from "node:fs";
+import { readFileSync, writeFileSync, copyFileSync, existsSync, statSync, } from "node:fs";
 import { resolve, relative, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import sade from "sade";
 import pc from "picocolors";
 import { loadConfig, mergeCliRules } from "./config.js";
+import { assetCandidates } from "./utils/asset-path.js";
+import { writeBlockedReason } from "./utils/safe-write.js";
+import { sanitizeForTerminal } from "./utils/terminal.js";
 import { discoverArtifacts, detectArtifactTypes } from "./discovery.js";
 import { formatHuman } from "./formatters/human.js";
 import { formatJson } from "./formatters/json.js";
@@ -71,6 +74,12 @@ const ALL_RULES = [
     ...MONITORS_JSON_RULES,
     ...MISPLACED_FILE_RULES,
 ];
+/**
+ * Hard cap on artifact file size. Real Claude Code artifacts are KB-scale;
+ * this only exists to reject pathological / malicious inputs (e.g. a
+ * multi-gigabyte file crafted to exhaust memory).
+ */
+const MAX_ARTIFACT_BYTES = 5 * 1024 * 1024;
 function simpleDiff(oldContent, newContent, filePath) {
     if (oldContent === newContent)
         return "";
@@ -106,7 +115,21 @@ function simpleDiff(oldContent, newContent, filePath) {
     }
     return lines.join("\n");
 }
-const pkgVersion = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8")).version;
+function readPkgVersion() {
+    // package.json ships beside dist/ (Node) or beside the executable
+    // (bun-compiled single-executable). Try every candidate; fall back to
+    // "0.0.0" if none resolve (e.g. an unexpected layout) rather than crashing.
+    for (const p of assetCandidates(import.meta.url, ["..", "package.json"])) {
+        try {
+            return JSON.parse(readFileSync(p, "utf8")).version;
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    return "0.0.0";
+}
+const pkgVersion = readPkgVersion();
 sade("claudecode-linter", true)
     .version(pkgVersion)
     .describe("Linter for Claude Code plugin artifacts")
@@ -133,9 +156,11 @@ sade("claudecode-linter", true)
     const fixDryRun = !!opts["fix-dry-run"];
     try {
         if (opts.init !== undefined) {
-            const __filename = fileURLToPath(import.meta.url);
-            const pkgDir = dirname(dirname(__filename));
-            const defaultsFile = join(pkgDir, ".claudecode-lint.defaults.yaml");
+            const defaultsFile = assetCandidates(import.meta.url, [
+                "..",
+                ".claudecode-lint.defaults.yaml",
+            ]).find((p) => existsSync(p)) ??
+                join(dirname(dirname(fileURLToPath(import.meta.url))), ".claudecode-lint.defaults.yaml");
             const targetDir = typeof opts.init === "string" ? resolve(opts.init) : process.cwd();
             const targetFile = join(targetDir, ".claudecode-lint.yaml");
             if (existsSync(targetFile)) {
@@ -197,10 +222,33 @@ sade("claudecode-linter", true)
                 ignore: ignorePatterns,
             });
             if (artifacts.length === 0) {
-                process.stderr.write(pc.yellow(`No plugin artifacts found in ${targetPath}\n`));
+                process.stderr.write(pc.yellow(`No plugin artifacts found in ${sanitizeForTerminal(targetPath)}\n`));
                 continue;
             }
+            // All --fix / --format writes for this target must stay inside
+            // rootDir. If targetPath is a file, rootDir is its parent dir.
+            const resolvedTarget = resolve(targetPath);
+            let rootDir = resolvedTarget;
+            try {
+                if (!statSync(resolvedTarget).isDirectory()) {
+                    rootDir = dirname(resolvedTarget);
+                }
+            }
+            catch {
+                rootDir = dirname(resolvedTarget);
+            }
             for (const artifact of artifacts) {
+                let sizeBytes;
+                try {
+                    sizeBytes = statSync(artifact.filePath).size;
+                }
+                catch {
+                    sizeBytes = 0;
+                }
+                if (sizeBytes > MAX_ARTIFACT_BYTES) {
+                    process.stderr.write(pc.yellow(`Skipping ${sanitizeForTerminal(artifact.filePath)}: file exceeds ${MAX_ARTIFACT_BYTES}-byte limit (${sizeBytes} bytes)\n`));
+                    continue;
+                }
                 let content = readFileSync(artifact.filePath, "utf-8");
                 const relPath = relative(process.cwd(), artifact.filePath);
                 if (opts.format) {
@@ -208,8 +256,14 @@ sade("claudecode-linter", true)
                     if (fixer) {
                         const fixedContent = await fixer.fix(artifact.filePath, content, config);
                         if (fixedContent !== content) {
-                            writeFileSync(artifact.filePath, fixedContent);
-                            formatted.push(relPath);
+                            const blocked = writeBlockedReason(artifact.filePath, rootDir);
+                            if (blocked) {
+                                process.stderr.write(pc.red(`Refusing to write ${sanitizeForTerminal(artifact.filePath)}: ${blocked}\n`));
+                            }
+                            else {
+                                writeFileSync(artifact.filePath, fixedContent);
+                                formatted.push(relPath);
+                            }
                         }
                     }
                     continue;
@@ -221,9 +275,15 @@ sade("claudecode-linter", true)
                     if (fixer) {
                         const fixedContent = await fixer.fix(artifact.filePath, content, config);
                         if (fixedContent !== content) {
-                            writeFileSync(artifact.filePath, fixedContent);
-                            content = fixedContent;
-                            fixed = 1;
+                            const blocked = writeBlockedReason(artifact.filePath, rootDir);
+                            if (blocked) {
+                                process.stderr.write(pc.red(`Refusing to write ${sanitizeForTerminal(artifact.filePath)}: ${blocked}\n`));
+                            }
+                            else {
+                                writeFileSync(artifact.filePath, fixedContent);
+                                content = fixedContent;
+                                fixed = 1;
+                            }
                         }
                     }
                 }
@@ -233,7 +293,7 @@ sade("claudecode-linter", true)
                         const fixedContent = await fixer.fix(artifact.filePath, content, config);
                         if (fixedContent !== content) {
                             const diff = simpleDiff(content, fixedContent, artifact.filePath);
-                            process.stdout.write(diff + "\n");
+                            process.stdout.write(sanitizeForTerminal(diff) + "\n");
                         }
                     }
                 }

package/dist/linters/agent-md.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { AGENT_MODELS, AGENT_COLORS, TOOLS, PLUGIN_SUBAGENT_BLOCKED_TOOLS, } from "../contracts.js";
+import { AGENT_MODELS, AGENT_COLORS, TOOLS, PERMISSION_MODES, PLUGIN_SUBAGENT_BLOCKED_TOOLS, } from "../contracts.js";
+import { invalidEffortReason } from "../utils/effort.js";
 import { formatAjvError, loadAgentFrontmatterSchema, summarizeErrors, } from "../plugin-schema.js";
 import { isRuleEnabled, getRuleSeverity } from "../types.js";
 import { parseFrontmatter } from "../utils/frontmatter.js";
@@ -65,6 +66,9 @@ const RULES = [
     { id: "agent-md/description-routing-guidance", defaultSeverity: "warning" },
     { id: "agent-md/model-required", defaultSeverity: "error" },
     { id: "agent-md/model-valid", defaultSeverity: "warning" },
+    { id: "agent-md/permission-mode-valid", defaultSeverity: "warning" },
+    { id: "agent-md/effort-valid", defaultSeverity: "warning" },
+    { id: "agent-md/max-turns-valid", defaultSeverity: "warning" },
     { id: "agent-md/color-required", defaultSeverity: "warning" },
     { id: "agent-md/color-valid", defaultSeverity: "warning" },
     { id: "agent-md/system-prompt-present", defaultSeverity: "error" },
@@ -158,6 +162,30 @@ export const agentMdLinter = {
             !fm.data.model.startsWith("claude-")) {
             push(diag(config, filePath, "agent-md/model-valid", "warning", `"model" must be one of: ${[...AGENT_MODELS].join(", ")} or a versioned claude-* model ID (got "${fm.data.model}")`));
         }
+        // permissionMode — typed as a permissive scalar by the Zod schema;
+        // at runtime only the PERMISSION_MODES values take effect.
+        if ("permissionMode" in fm.data) {
+            const pm = fm.data.permissionMode;
+            if (typeof pm !== "string" || !PERMISSION_MODES.has(pm)) {
+                push(diag(config, filePath, "agent-md/permission-mode-valid", "warning", `"permissionMode" must be one of: ${[...PERMISSION_MODES].join(", ")} (got ${JSON.stringify(pm)})`));
+            }
+        }
+        // effort — Zod types it as a permissive scalar; the field's describe()
+        // string restricts it to a named level or an integer.
+        if ("effort" in fm.data) {
+            const reason = invalidEffortReason(fm.data.effort);
+            if (reason) {
+                push(diag(config, filePath, "agent-md/effort-valid", "warning", reason));
+            }
+        }
+        // maxTurns — Zod accepts a string / float; only a positive integer
+        // is a meaningful turn budget.
+        if ("maxTurns" in fm.data) {
+            const mt = fm.data.maxTurns;
+            if (typeof mt !== "number" || !Number.isInteger(mt) || mt <= 0) {
+                push(diag(config, filePath, "agent-md/max-turns-valid", "warning", `"maxTurns" must be a positive integer (got ${JSON.stringify(mt)})`));
+            }
+        }
         // color
         if (!("color" in fm.data) || typeof fm.data.color !== "string") {
             push(diag(config, filePath, "agent-md/color-required", "warning", '"color" is required in frontmatter'));

package/dist/linters/command-md.js

@@ -1,12 +1,17 @@
-import { TOOLS } from "../contracts.js";
+import { AGENT_MODELS, TOOLS } from "../contracts.js";
 import { formatAjvError, loadCommandFrontmatterSchema, summarizeErrors, } from "../plugin-schema.js";
 import { isRuleEnabled, getRuleSeverity } from "../types.js";
+import { invalidEffortReason } from "../utils/effort.js";
 import { parseFrontmatter } from "../utils/frontmatter.js";
 import { artifactLabel, classifyUnknownFrontmatterKey, } from "../utils/frontmatter-keys.js";
 const RULES = [
     { id: "command-md/valid-frontmatter", defaultSeverity: "error" },
     { id: "command-md/schema-valid", defaultSeverity: "error" },
     { id: "command-md/description-required", defaultSeverity: "error" },
+    { id: "command-md/name-format", defaultSeverity: "warning" },
+    { id: "command-md/model-valid", defaultSeverity: "warning" },
+    { id: "command-md/effort-valid", defaultSeverity: "warning" },
+    { id: "command-md/frontmatter-field-type", defaultSeverity: "warning" },
     { id: "command-md/allowed-tools-valid", defaultSeverity: "warning" },
     { id: "command-md/body-present", defaultSeverity: "warning" },
     { id: "command-md/no-unknown-frontmatter", defaultSeverity: "info" },
@@ -57,6 +62,37 @@ export const commandMdLinter = {
         if (!("description" in fm.data) || typeof fm.data.description !== "string") {
             push(diag(config, filePath, "command-md/description-required", "error", "\"description\" is required in frontmatter"));
         }
+        // name — optional display-name override. Zod types it as a permissive
+        // scalar; if present it must be a non-empty string.
+        if ("name" in fm.data) {
+            const name = fm.data.name;
+            if (typeof name !== "string" || name.trim() === "") {
+                push(diag(config, filePath, "command-md/name-format", "warning", `"name" must be a non-empty string (got ${JSON.stringify(name)})`));
+            }
+        }
+        // model — Zod types it as a permissive scalar; accept a named alias or a
+        // versioned claude-* model id. Mirrors agent-md/model-valid.
+        if ("model" in fm.data && typeof fm.data.model === "string") {
+            const model = fm.data.model;
+            if (!AGENT_MODELS.has(model) && !model.startsWith("claude-")) {
+                push(diag(config, filePath, "command-md/model-valid", "warning", `"model" must be one of: ${[...AGENT_MODELS].join(", ")} or a versioned claude-* model ID (got "${model}")`));
+            }
+        }
+        // effort — Zod types it as a permissive scalar; the field's describe()
+        // string restricts it to a named level or an integer.
+        if ("effort" in fm.data) {
+            const reason = invalidEffortReason(fm.data.effort);
+            if (reason) {
+                push(diag(config, filePath, "command-md/effort-valid", "warning", reason));
+            }
+        }
+        // boolean fields — the Zod schema accepts the string "true"; only a real
+        // boolean behaves as expected.
+        for (const field of ["disable-model-invocation", "user-invocable"]) {
+            if (field in fm.data && typeof fm.data[field] !== "boolean") {
+                push(diag(config, filePath, "command-md/frontmatter-field-type", "warning", `"${field}" must be a boolean (got ${JSON.stringify(fm.data[field])})`));
+            }
+        }
         // allowed-tools
         if ("allowed-tools" in fm.data) {
             const tools = fm.data["allowed-tools"];

package/dist/linters/hooks-json.js

@@ -1,7 +1,9 @@
 import { HOOK_EVENTS, HOOK_TYPES, PROMPT_EVENTS } from "../contracts.js";
+import { formatAjvError, loadHooksJsonSchema, summarizeErrors, } from "../plugin-schema.js";
 import { isRuleEnabled, getRuleSeverity } from "../types.js";
 const RULES = [
     { id: "hooks-json/valid-json", defaultSeverity: "error" },
+    { id: "hooks-json/schema-valid", defaultSeverity: "error" },
     { id: "hooks-json/root-hooks-key", defaultSeverity: "error" },
     { id: "hooks-json/valid-event-names", defaultSeverity: "error" },
     { id: "hooks-json/hook-type-required", defaultSeverity: "error" },
@@ -52,6 +54,28 @@ export const hooksJsonLinter = {
             push(diag(config, filePath, "hooks-json/valid-json", "error", "hooks.json must be a JSON object"));
             return diagnostics;
         }
+        // schema-valid — structural validation against the JSON Schema
+        // auto-extracted from Claude Code's hooks-config Zod validator (the
+        // hook-event → matcher-array map, each matcher holding a discriminated
+        // union of hook definitions). The hand-written rules below add
+        // Claude-Code-specific advice the schema can't express (hardcoded-path
+        // warnings, prompt-event-support hints, …). The extracted schema is
+        // intentionally permissive about unknown hook fields (Claude Code's hook
+        // objects are not .strict()). Skipped silently if the schema bundle isn't
+        // shipped with this install.
+        if (isRuleEnabled(config, "hooks-json/schema-valid")) {
+            const compiled = loadHooksJsonSchema();
+            if (compiled) {
+                const ok = compiled.validate(parsed);
+                if (!ok && compiled.validate.errors) {
+                    for (const err of summarizeErrors(compiled.validate.errors)) {
+                        const firstSeg = err.instancePath.split("/").filter(Boolean)[0];
+                        const p = firstSeg ? findKeyPosition(content, firstSeg) : undefined;
+                        push(diag(config, filePath, "hooks-json/schema-valid", "error", formatAjvError(err), p?.line, p?.column));
+                    }
+                }
+            }
+        }
         const root = parsed;
         // root "hooks" key
         if (!("hooks" in root) || typeof root.hooks !== "object" || root.hooks === null) {

package/dist/linters/mcp-json.js

@@ -1,5 +1,6 @@
 import { basename } from "node:path";
 import { MCP_SERVER_FIELDS } from "../contracts.js";
+import { formatAjvError, loadMcpJsonSchema, summarizeErrors, } from "../plugin-schema.js";
 import { isRuleEnabled, getRuleSeverity } from "../types.js";
 import { isKebabCase } from "../utils/kebab-case.js";
 // Valid `type` values for a URL-based HTTP MCP server. Claude Code v2.1.146
@@ -9,6 +10,7 @@ const HTTP_TRANSPORT_TYPES = new Set(["http", "streamable-http"]);
 const RULES = [
     { id: "mcp-json/scope-file-name", defaultSeverity: "warning" },
     { id: "mcp-json/valid-json", defaultSeverity: "error" },
+    { id: "mcp-json/schema-valid", defaultSeverity: "error" },
     { id: "mcp-json/servers-required", defaultSeverity: "error" },
     { id: "mcp-json/servers-object", defaultSeverity: "error" },
     { id: "mcp-json/server-name-kebab", defaultSeverity: "info" },
@@ -73,6 +75,28 @@ export const mcpJsonLinter = {
             push(diag(config, filePath, "mcp-json/valid-json", "error", "mcp.json must be a JSON object"));
             return diagnostics;
         }
+        // schema-valid — structural validation against the JSON Schema
+        // auto-extracted from Claude Code's .mcp.json Zod validator (the
+        // `mcpServers` record of discriminated transport configs). The hand-written
+        // rules below add Claude-Code-specific advice the schema can't express
+        // (kebab-case names, ${CLAUDE_PLUGIN_ROOT} hints, …). The extracted schema
+        // is intentionally permissive about unknown server fields (Claude Code's
+        // server union is not .strict()), so those are NOT reported here —
+        // mcp-json/no-unknown-server-fields handles them. Skipped silently if the
+        // schema bundle isn't shipped with this install.
+        if (isRuleEnabled(config, "mcp-json/schema-valid")) {
+            const compiled = loadMcpJsonSchema();
+            if (compiled) {
+                const ok = compiled.validate(parsed);
+                if (!ok && compiled.validate.errors) {
+                    for (const err of summarizeErrors(compiled.validate.errors)) {
+                        const firstSeg = err.instancePath.split("/").filter(Boolean)[0];
+                        const p = firstSeg ? findKeyPosition(content, firstSeg) : undefined;
+                        push(diag(config, filePath, "mcp-json/schema-valid", "error", formatAjvError(err), p?.line, p?.column));
+                    }
+                }
+            }
+        }
         // mcpServers required
         if (!("mcpServers" in parsed)) {
             push(diag(config, filePath, "mcp-json/servers-required", "error", "\"mcpServers\" field is required"));

package/dist/linters/skill-md.js

@@ -1,5 +1,7 @@
+import { AGENT_MODELS, TOOLS } from "../contracts.js";
 import { formatAjvError, loadSkillFrontmatterSchema, summarizeErrors, } from "../plugin-schema.js";
 import { isRuleEnabled, getRuleSeverity } from "../types.js";
+import { invalidEffortReason } from "../utils/effort.js";
 import { parseFrontmatter } from "../utils/frontmatter.js";
 import { artifactLabel, classifyUnknownFrontmatterKey, } from "../utils/frontmatter-keys.js";
 import { isKebabCase } from "../utils/kebab-case.js";
@@ -13,6 +15,10 @@ const RULES = [
     { id: "skill-md/description-max-length", defaultSeverity: "error" },
     { id: "skill-md/description-no-angle-brackets", defaultSeverity: "error" },
     { id: "skill-md/description-trigger-phrases", defaultSeverity: "warning" },
+    { id: "skill-md/model-valid", defaultSeverity: "warning" },
+    { id: "skill-md/effort-valid", defaultSeverity: "warning" },
+    { id: "skill-md/allowed-tools-valid", defaultSeverity: "warning" },
+    { id: "skill-md/frontmatter-field-type", defaultSeverity: "warning" },
     { id: "skill-md/no-unknown-frontmatter", defaultSeverity: "info" },
     { id: "skill-md/body-word-count", defaultSeverity: "info" },
     { id: "skill-md/body-has-headers", defaultSeverity: "info" },
@@ -151,6 +157,41 @@ export const skillMdLinter = {
                     "(e.g., \"Use when…\", \"Trigger on…\", \"when the user asks to…\", or an imperative verb)"));
             }
         }
+        // model — Zod types it as a permissive scalar; accept a named alias or a
+        // versioned claude-* model id. Mirrors agent-md/model-valid.
+        if ("model" in fm.data && typeof fm.data.model === "string") {
+            const model = fm.data.model;
+            if (!AGENT_MODELS.has(model) && !model.startsWith("claude-")) {
+                push(diag(config, filePath, "skill-md/model-valid", "warning", `"model" must be one of: ${[...AGENT_MODELS].join(", ")} or a versioned claude-* model ID (got "${model}")`));
+            }
+        }
+        // effort — Zod types it as a permissive scalar; the field's describe()
+        // string restricts it to a named level or an integer.
+        if ("effort" in fm.data) {
+            const reason = invalidEffortReason(fm.data.effort);
+            if (reason) {
+                push(diag(config, filePath, "skill-md/effort-valid", "warning", reason));
+            }
+        }
+        // allowed-tools — validate built-in tool names. mcp__* patterns are
+        // dynamic (resolved at runtime); accept them. Mirrors command-md.
+        if ("allowed-tools" in fm.data) {
+            const tools = fm.data["allowed-tools"];
+            if (Array.isArray(tools)) {
+                for (const t of tools) {
+                    if (typeof t === "string" && !t.startsWith("mcp__") && !TOOLS.has(t)) {
+                        push(diag(config, filePath, "skill-md/allowed-tools-valid", "warning", `Unknown tool "${t}" in allowed-tools`));
+                    }
+                }
+            }
+        }
+        // boolean fields — the Zod schema accepts the string "true"; only a real
+        // boolean behaves as expected.
+        for (const field of ["disable-model-invocation", "user-invocable"]) {
+            if (field in fm.data && typeof fm.data[field] !== "boolean") {
+                push(diag(config, filePath, "skill-md/frontmatter-field-type", "warning", `"${field}" must be a boolean (got ${JSON.stringify(fm.data[field])})`));
+            }
+        }
         // Frontmatter keys: only flag cross-artifact misplacement. A key that is
         // valid for a *different* markdown artifact (e.g. agent's "effort" on a
         // skill) gets an info; a key valid for no artifact stays silent.

package/dist/plugin-schema.js

@@ -8,11 +8,10 @@
  * resolver if the file is being run from an alternate layout (e.g. monorepo).
  */
 import { readFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
 import { Ajv2020 } from "ajv/dist/2020.js";
 // biome-ignore lint/style/useImportType: runtime import; types only.
 import * as addFormatsNs from "ajv-formats";
+import { assetCandidates } from "./utils/asset-path.js";
 // ajv-formats ships as CJS with a default function export. Under Node16
 // ESM resolution we have to reach in for `.default`.
 const addFormats = addFormatsNs.default;
@@ -29,10 +28,9 @@ function getAjv() {
 function loadCompiledSchema(fileName) {
     if (compiledCache.has(fileName))
         return compiledCache.get(fileName) ?? null;
-    const here = dirname(fileURLToPath(import.meta.url));
     const candidates = [
-        resolve(here, "..", "contracts", fileName),
-        resolve(here, "..", "..", "contracts", fileName),
+        ...assetCandidates(import.meta.url, ["..", "contracts", fileName]),
+        ...assetCandidates(import.meta.url, ["..", "..", "contracts", fileName]),
     ];
     let raw = null;
     for (const p of candidates) {
@@ -52,6 +50,7 @@ function loadCompiledSchema(fileName) {
     const compiled = {
         validate: getAjv().compile(wrapped.schema),
         extractedFromVersion: wrapped.extractedFromClaudeCodeVersion,
+        knownFields: new Set(Object.keys(wrapped.schema.properties ?? {})),
     };
     compiledCache.set(fileName, compiled);
     return compiled;
@@ -65,6 +64,12 @@ export function loadMonitorsSchema() {
 export function loadSettingsSchema() {
     return loadCompiledSchema("settings.schema.json");
 }
+export function loadMcpJsonSchema() {
+    return loadCompiledSchema("mcp.schema.json");
+}
+export function loadHooksJsonSchema() {
+    return loadCompiledSchema("hooks.schema.json");
+}
 export function loadSkillFrontmatterSchema() {
     return loadCompiledSchema("skill-frontmatter.schema.json");
 }
@@ -77,10 +82,14 @@ export function loadCommandFrontmatterSchema() {
 export function loadPluginSchema() {
     if (cached)
         return cached;
-    const here = dirname(fileURLToPath(import.meta.url));
     const candidates = [
-        resolve(here, "..", "contracts", "plugin.schema.json"),
-        resolve(here, "..", "..", "contracts", "plugin.schema.json"),
+        ...assetCandidates(import.meta.url, ["..", "contracts", "plugin.schema.json"]),
+        ...assetCandidates(import.meta.url, [
+            "..",
+            "..",
+            "contracts",
+            "plugin.schema.json",
+        ]),
     ];
     let raw = null;
     for (const p of candidates) {

package/dist/utils/asset-path.js

@@ -0,0 +1,56 @@
+/**
+ * Resolve runtime assets (contracts/*.schema.json, .claudecode-lint.defaults.yaml,
+ * package.json) that ship alongside the package on disk.
+ *
+ * Normally these are found relative to `import.meta.url` — the location of the
+ * compiled `.js` file inside `dist/`. That works for the Node build and for the
+ * published npm package.
+ *
+ * Inside a `bun build --compile` single-executable, `import.meta.url` points
+ * into Bun's virtual embedded filesystem (`/$bunfs/...`), so disk reads of
+ * sibling assets fail. To support that variant, we ALSO emit candidates
+ * relative to `process.execPath` (the real on-disk path of the running
+ * executable). The compiled-binary image ships `contracts/` and
+ * `.claudecode-lint.defaults.yaml` next to the executable, so those fallback
+ * candidates resolve there.
+ *
+ * For the Node runtime, the `process.execPath`-relative candidates simply point
+ * at the `node` binary's directory and won't match — harmless extra lookups
+ * appended AFTER the existing ones, so Node resolution is byte-for-byte
+ * unchanged.
+ */
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Build a list of candidate paths for an asset shipped with the package.
+ *
+ * @param importMetaUrl  `import.meta.url` of the calling module.
+ * @param segments       Path segments, relative to a base directory, that
+ *                        locate the asset (e.g. `["..", "contracts", "x.json"]`
+ *                        for a module under `dist/`).
+ * @returns Ordered candidate paths: `import.meta.url`-relative first (existing
+ *          behavior), then `process.execPath`-relative fallbacks.
+ */
+export function assetCandidates(importMetaUrl, segments) {
+    const candidates = [];
+    // 1. import.meta.url-relative — the existing, primary resolution.
+    const here = dirname(fileURLToPath(importMetaUrl));
+    candidates.push(resolve(here, ...segments));
+    // 2. process.execPath-relative fallbacks for the compiled single-executable.
+    //    The binary lives next to `contracts/` and the defaults YAML, so we try
+    //    both the executable's own directory and one level up (mirroring the
+    //    dist/ -> package-root step the segments encode).
+    try {
+        const execDir = dirname(process.execPath);
+        // Drop leading ".." segments: assets sit directly beside the executable.
+        const beside = segments.filter((s) => s !== "..");
+        candidates.push(resolve(execDir, ...beside));
+        candidates.push(resolve(execDir, ...segments));
+    }
+    catch {
+        // process.execPath unavailable — ignore.
+    }
+    // De-duplicate while preserving order.
+    return [...new Set(candidates)];
+}
+//# sourceMappingURL=asset-path.js.map

package/dist/utils/effort.js

@@ -0,0 +1,29 @@
+import { EFFORT_LEVELS } from "../contracts.js";
+/**
+ * Validate a frontmatter `effort` value against the Claude Code contract.
+ *
+ * Claude Code's frontmatter Zod schema types `effort` as a permissive scalar
+ * (`anyOf[string,number,boolean,null]`), but the field's own `.describe()`
+ * string in the bundle reads:
+ *   "Thinking effort for the model: `low`, `medium`, `high`, `max`, or an integer."
+ *
+ * So a valid `effort` is either one of the named levels (EFFORT_LEVELS) or an
+ * integer. Anything else — a non-integer number, a boolean, an unknown string,
+ * null — is reported. Returns a human-readable reason when invalid, or null
+ * when the value is acceptable.
+ */
+export function invalidEffortReason(value) {
+    const valid = [...EFFORT_LEVELS].join(", ");
+    if (typeof value === "string") {
+        if (EFFORT_LEVELS.has(value))
+            return null;
+        return `"effort" string must be one of: ${valid} (got "${value}")`;
+    }
+    if (typeof value === "number") {
+        if (Number.isInteger(value))
+            return null;
+        return `"effort" number must be an integer (got ${value})`;
+    }
+    return `"effort" must be one of: ${valid}, or an integer (got ${JSON.stringify(value)})`;
+}
+//# sourceMappingURL=effort.js.map

package/dist/utils/frontmatter-keys.js

@@ -1,9 +1,38 @@
 import { SKILL_FRONTMATTER, AGENT_FRONTMATTER, COMMAND_FRONTMATTER, } from "../contracts.js";
-const KEY_SETS = {
+import { loadSkillFrontmatterSchema, loadAgentFrontmatterSchema, loadCommandFrontmatterSchema, } from "../plugin-schema.js";
+// Census-extraction sets (scripts/extract-contracts.ts). Used only as a
+// fallback when the auto-extracted frontmatter schema is unavailable — the
+// census extractor lags the schema walker (e.g. it was missing `effort`).
+const CENSUS_FALLBACK = {
     skill: SKILL_FRONTMATTER,
     agent: AGENT_FRONTMATTER,
     command: COMMAND_FRONTMATTER,
 };
+const SCHEMA_LOADERS = {
+    skill: loadSkillFrontmatterSchema,
+    agent: loadAgentFrontmatterSchema,
+    command: loadCommandFrontmatterSchema,
+};
+const keyCache = new Map();
+/**
+ * Known frontmatter keys for an artifact — the union of the auto-extracted
+ * schema's property names (authoritative, complete, kept in sync with Claude
+ * Code's Zod) and the census-contract set. Union rather than schema-only so a
+ * key known to *either* extraction is never mis-flagged: `no-unknown-
+ * frontmatter` is advisory and a false positive is the only real harm.
+ */
+function knownKeys(kind) {
+    const cached = keyCache.get(kind);
+    if (cached)
+        return cached;
+    const merged = new Set(CENSUS_FALLBACK[kind]);
+    const schema = SCHEMA_LOADERS[kind]();
+    if (schema)
+        for (const k of schema.knownFields)
+            merged.add(k);
+    keyCache.set(kind, merged);
+    return merged;
+}
 const ARTIFACT_LABEL = {
     skill: "skill",
     agent: "agent",
@@ -18,13 +47,13 @@ const ARTIFACT_LABEL = {
  */
 export function classifyUnknownFrontmatterKey(key, self, extraKnown = new Set()) {
     // Known for the current artifact — not unknown at all.
-    if (KEY_SETS[self].has(key) || extraKnown.has(key))
+    if (knownKeys(self).has(key) || extraKnown.has(key))
         return null;
     // Valid for some *other* markdown artifact → misplacement.
     for (const kind of ["skill", "agent", "command"]) {
         if (kind === self)
             continue;
-        if (KEY_SETS[kind].has(key)) {
+        if (knownKeys(kind).has(key)) {
             return { kind: "owned-by-other", owner: kind };
         }
     }

package/dist/utils/frontmatter.js

@@ -32,7 +32,7 @@ export function parseFrontmatter(content) {
     const body = lines.slice(closingIndex + 1).join("\n");
     const bodyStartLine = closingIndex + 2; // 1-based
     try {
-        const data = parseYaml(frontmatterRaw);
+        const data = parseYaml(frontmatterRaw, { maxAliasCount: 100 });
         if (typeof data !== "object" || data === null || Array.isArray(data)) {
             return {
                 data: {},