@yawlabs/ctxlint 0.15.1 → 0.16.0

package/.pre-commit-hooks.yaml

@@ -4,7 +4,7 @@
   # Version-pinned so a checkout at `rev: vX.Y.Z` runs exactly that release
   # of ctxlint — matches the pinning done by `ctxlint init`. release.sh keeps
   # this in sync with package.json on each bump.
-  entry: npx @yawlabs/ctxlint@0.15.1 --strict
+  entry: npx @yawlabs/ctxlint@0.16.0 --strict
   language: node
   always_run: true
   pass_filenames: false

package/MCP_CONFIG_LINT_SPEC.md

@@ -16,7 +16,7 @@ This specification defines a standard set of lint rules for validating MCP serve
 
 The specification includes:
 - A complete reference of MCP config file locations, formats, and client-specific behaviors
-- 28 lint rules organized into 8 categories with defined severities
+- 29 lint rules organized into 8 categories with defined severities
 - A machine-readable rule catalog ([`mcp-config-lint-rules.json`](./mcp-config-lint-rules.json))
 - Auto-fix definitions for rules that support automated correction
 
@@ -199,7 +199,7 @@ Without this wrapper, the subprocess fails to spawn. This is the most common Win
 
 ## 2. Lint Rules
 
-28 rules organized into 8 categories. Each rule has a unique ID, severity level, trigger condition, and message template.
+29 rules organized into 8 categories. Each rule has a unique ID, severity level, trigger condition, and message template.
 
 Severity levels:
 - **error** — the config is broken or has a security issue. Should fail CI.
@@ -226,19 +226,22 @@ Validates that the config file is well-formed JSON with the correct structure fo
 
 ### 2.2 mcp-security — hardcoded secrets
 
-Detects secrets committed to version control in MCP config files. The three secret rules (`hardcoded-bearer`, `hardcoded-api-key`, `secret-in-url`) only flag issues in git-tracked files — an untracked config leaks nothing to teammates. `mcp-security/http-no-tls` is a transport concern, independent of version control, and fires regardless of git tracking.
+Detects secrets committed to version control in MCP config files. The three secret rules (`hardcoded-bearer`, `hardcoded-api-key`, `secret-in-url`) only flag issues in git-tracked files — an untracked config leaks nothing to teammates. `mcp-security/http-no-tls` is a transport concern, independent of version control, and fires regardless of git tracking. When the tracked status cannot be determined at all (git unavailable or failing, as opposed to a determined "untracked"), the linter says so via `mcp-security/secret-scan-skipped` instead of silently passing a possibly-tracked file.
 
 | Rule ID | Severity | Trigger | Message |
 |---|---|---|---|
 | `mcp-security/hardcoded-bearer` | error | `Authorization` header contains a literal Bearer token (not an env var reference) in a git-tracked file | `Server "{name}" has a hardcoded Bearer token in a git-tracked file` |
 | `mcp-security/hardcoded-api-key` | error | Header or env value matches known API key patterns (or the high-entropy heuristic below) in a git-tracked file | `Server "{name}" has a hardcoded API key in a git-tracked file` |
 | `mcp-security/secret-in-url` | error | URL contains query params that look like secrets (`?key=`, `?token=`, `?api_key=`) in a git-tracked file | `Server "{name}" has a secret in the URL query string` |
+| `mcp-security/secret-scan-skipped` | info | Git-tracked status could not be determined (git unavailable/failing — not merely untracked), so the three git-gated secret rules were skipped | `Could not determine git-tracked status of {file}; hardcoded-secret rules were skipped` |
 | `mcp-security/http-no-tls` | warning | URL uses `http://` for a non-loopback target (loopback = `localhost`, `[::1]`, `127.0.0.0/8`) | `Server "{name}" uses HTTP without TLS` |
 
 **Known API key patterns:**
 ```
 sk-ant-[A-Za-z0-9_-]{20,}      # Anthropic
-sk-(proj-)?[A-Za-z0-9_-]{20,}  # OpenAI (classic or project-scoped) / generic
+sk-proj-[A-Za-z0-9_-]{20,}     # OpenAI project-scoped
+sk-[a-zA-Z0-9]{20,}            # OpenAI classic / generic (alphanumeric-only:
+                               # [-_] would swallow kebab-case identifiers)
 ghp_[a-zA-Z0-9]{36}            # GitHub personal access token
 ghu_[a-zA-Z0-9]{36}            # GitHub user token
 github_pat_[a-zA-Z0-9_]{80,}   # GitHub fine-grained PAT

package/README.md

@@ -514,7 +514,7 @@ ctxlint is the reference implementation of four open specifications for linting
 | Spec                                                           | What it covers                                                                                                                                                                                                                            |
 | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **[AI Context File Linting Spec](./CONTEXT_LINT_SPEC.md)**     | 39 rules for validating context files (CLAUDE.md, .cursorrules, AGENTS.md, etc.) across 16 clients. Covers file formats, frontmatter schemas, path/command validation, staleness, token budgets, redundancy, and contradictions.          |
-| **[MCP Config Linting Spec](./MCP_CONFIG_LINT_SPEC.md)**       | 28 rules for validating MCP server configs (.mcp.json, .cursor/mcp.json, .vscode/mcp.json, etc.) across 8 clients. Covers schema validation, hardcoded secrets, env var syntax, deprecated transports, and cross-file consistency.        |
+| **[MCP Config Linting Spec](./MCP_CONFIG_LINT_SPEC.md)**       | 29 rules for validating MCP server configs (.mcp.json, .cursor/mcp.json, .vscode/mcp.json, etc.) across 8 clients. Covers schema validation, hardcoded secrets, env var syntax, deprecated transports, and cross-file consistency.        |
 | **[Agent Session Linting Spec](./AGENT_SESSION_LINT_SPEC.md)** | 8 rules for auditing agent session data (history, memory) across 8 agents. Covers cross-project secret consistency, config drift, stale memory, and loop detection.                                                                       |
 | **[Agent Skill Linting Spec](./AGENT_SKILL_LINT_SPEC.md)**     | 5 rules for auditing Claude Code skill (`SKILL.md`) and agent (`.md`) definitions under `~/.claude`. Covers frontmatter presence, broken refs, trigger-phrase collisions, orphaned skills, and dead tool restrictions. (v1, experimental) |
 

package/dist/index.js

@@ -41087,7 +41087,7 @@ async function parseMcpConfig(file2, projectRoot, scope) {
   const content = readFileContent(file2.absolutePath);
   const client = detectClient(file2.relativePath);
   const expectedRootKey = client === "vscode" ? "servers" : "mcpServers";
-  const isGitTracked = await checkGitTracked(file2.absolutePath, projectRoot);
+  const gitTracked = await checkGitTracked(file2.absolutePath, projectRoot);
   const result = {
     filePath: file2.absolutePath,
     relativePath: file2.relativePath,
@@ -41098,7 +41098,8 @@ async function parseMcpConfig(file2, projectRoot, scope) {
     servers: [],
     parseErrors: [],
     content,
-    isGitTracked
+    isGitTracked: gitTracked === "tracked",
+    ...gitTracked === "unknown" ? { gitTrackedUnknown: true } : {}
   };
   let parsed;
   try {
@@ -41283,13 +41284,18 @@ function decodeJsonKey(raw) {
     return raw;
   }
 }
+function classifyGitTrackedError(message) {
+  if (/did not match any file/i.test(message)) return "untracked";
+  if (/not a git repository/i.test(message)) return "untracked";
+  return "unknown";
+}
 async function checkGitTracked(filePath, projectRoot) {
   try {
     const git = getGit(projectRoot);
     const result = await git.raw(["ls-files", "--error-unmatch", filePath]);
-    return result.trim().length > 0;
-  } catch {
-    return false;
+    return result.trim().length > 0 ? "tracked" : "untracked";
+  } catch (err) {
+    return classifyGitTrackedError(err instanceof Error ? err.message : String(err));
   }
 }
 var init_mcp_parser = __esm({
@@ -44110,7 +44116,7 @@ function validateWindsurfRule(file2) {
       ruleId: "frontmatter/missing",
       line: 1,
       message: "Windsurf rule file has no frontmatter",
-      suggestion: "Add YAML frontmatter with a trigger field (always_on, glob, manual, model)"
+      suggestion: `Add YAML frontmatter with a trigger field (${VALID_WINDSURF_TRIGGERS.join(", ")})`
     });
     return issues;
   }
@@ -44301,6 +44307,16 @@ async function checkMcpSecurity(config2, _projectRoot) {
   const issues = [];
   if (config2.parseErrors.length > 0) return issues;
   const checkSecrets = config2.isGitTracked;
+  if (!checkSecrets && config2.gitTrackedUnknown) {
+    issues.push({
+      severity: "info",
+      check: "mcp-security",
+      ruleId: "mcp-security/secret-scan-skipped",
+      line: 1,
+      message: `Could not determine git-tracked status of ${config2.relativePath}; hardcoded-secret rules were skipped`,
+      suggestion: "Verify git is available and the file is not tracked, or re-run inside the repository"
+    });
+  }
   for (const server2 of config2.servers) {
     if (checkSecrets && server2.headers) {
       for (const [headerName, headerValue] of Object.entries(server2.headers)) {
@@ -46885,7 +46901,7 @@ import { readFileSync as readFileSync7 } from "node:fs";
 import { resolve as resolve13, dirname as dirname6 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 function loadVersion() {
-  if (true) return "0.15.1";
+  if (true) return "0.16.0";
   const __dir = dirname6(fileURLToPath2(import.meta.url));
   const pkgPath = resolve13(__dir, "../package.json");
   const pkg = JSON.parse(readFileSync7(pkgPath, "utf-8"));

package/mcp-config-lint-rules.json

@@ -206,6 +206,19 @@
       ],
       "stability": "stable"
     },
+    {
+      "id": "mcp-security/secret-scan-skipped",
+      "category": "mcp-security",
+      "severity": "info",
+      "description": "Git-tracked status of the config file could not be determined, so the git-gated secret rules were skipped without an answer.",
+      "trigger": "git ls-files fails for a reason other than \"untracked\" or \"not a repository\" (git unavailable, permissions, timeout). A determined \"untracked\" does not fire this rule.",
+      "message": "Could not determine git-tracked status of {file}; hardcoded-secret rules were skipped",
+      "fixable": false,
+      "clients": [
+        "all"
+      ],
+      "stability": "experimental"
+    },
     {
       "id": "mcp-security/http-no-tls",
       "category": "mcp-security",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/ctxlint",
-  "version": "0.15.1",
+  "version": "0.16.0",
   "mcpName": "io.github.YawLabs/ctxlint",
   "description": "Lint your AI agent context files, MCP server configs, and session data against your actual codebase",
   "bin": {