@wrongstack/plugins 0.281.3 → 0.282.0

package/dist/dependency-vulnerability-gate.js

@@ -0,0 +1,308 @@
+import { execFileSync } from 'child_process';
+import { existsSync } from 'fs';
+
+// src/dependency-vulnerability-gate/index.ts
+var API_VERSION = "^0.1.10";
+var state = {
+  invocations: 0,
+  installsSeen: 0,
+  auditsRun: 0,
+  blocks: 0,
+  warns: 0,
+  errors: 0,
+  lastResult: null,
+  hookUnregister: null
+};
+var DEFAULTS = {
+  enabled: true,
+  severityThreshold: "high",
+  block: true,
+  timeoutMs: 12e4
+};
+var SEVERITY_RANK = {
+  info: 0,
+  low: 1,
+  moderate: 2,
+  high: 3,
+  critical: 4
+};
+function readConfig(raw) {
+  if (!raw || typeof raw !== "object") return { ...DEFAULTS };
+  const r = raw;
+  const threshold = typeof r["severityThreshold"] === "string" && ["low", "moderate", "high", "critical"].includes(r["severityThreshold"]) ? r["severityThreshold"] : DEFAULTS.severityThreshold;
+  return {
+    enabled: r["enabled"] !== false,
+    severityThreshold: threshold,
+    block: r["block"] !== false,
+    timeoutMs: typeof r["timeoutMs"] === "number" && r["timeoutMs"] > 0 ? r["timeoutMs"] : DEFAULTS.timeoutMs
+  };
+}
+function collectSeverities(out, severity) {
+  const key = severity.toLowerCase();
+  out.counts[key] = (out.counts[key] ?? 0) + 1;
+  out.total += 1;
+  if (SEVERITY_RANK[key] != null) {
+    const currentMax = out.maxSeverity;
+    if (currentMax === null || SEVERITY_RANK[key] > (SEVERITY_RANK[currentMax] ?? 0)) {
+      out.maxSeverity = key;
+    }
+  }
+}
+function parseAuditJson(jsonString) {
+  let parsed;
+  try {
+    parsed = JSON.parse(jsonString);
+  } catch {
+    return null;
+  }
+  const out = { maxSeverity: null, counts: {}, total: 0 };
+  if (parsed && typeof parsed === "object") {
+    const vulnerabilities = parsed["vulnerabilities"];
+    if (vulnerabilities && typeof vulnerabilities === "object" && !Array.isArray(vulnerabilities)) {
+      for (const entry of Object.values(vulnerabilities)) {
+        if (entry && typeof entry === "object") {
+          const severity = entry["severity"];
+          if (typeof severity === "string") {
+            collectSeverities(out, severity);
+          }
+        }
+      }
+    }
+    if (out.total === 0) {
+      const metadata = parsed["metadata"];
+      const metaVulns = metadata && typeof metadata === "object" ? metadata["vulnerabilities"] : void 0;
+      if (metaVulns && typeof metaVulns === "object") {
+        for (const [key, value] of Object.entries(metaVulns)) {
+          const count = typeof value === "number" ? value : 0;
+          if (count > 0 && SEVERITY_RANK[key] != null) {
+            out.counts[key] = (out.counts[key] ?? 0) + count;
+            out.total += count;
+            const currentMax = out.maxSeverity;
+            if (currentMax === null || SEVERITY_RANK[key] > (SEVERITY_RANK[currentMax] ?? 0)) {
+              out.maxSeverity = key;
+            }
+          }
+        }
+      }
+    }
+  }
+  if (Array.isArray(parsed)) {
+    for (const entry of parsed) {
+      if (entry && typeof entry === "object") {
+        const severity = entry["severity"];
+        if (typeof severity === "string") {
+          collectSeverities(out, severity);
+        }
+      }
+    }
+  }
+  return out;
+}
+function exceedsThreshold(report, threshold) {
+  if (report.maxSeverity === null) return false;
+  const thresholdRank = SEVERITY_RANK[threshold];
+  const maxRank = SEVERITY_RANK[report.maxSeverity];
+  if (thresholdRank == null || maxRank == null) return false;
+  return maxRank >= thresholdRank;
+}
+var INSTALL_RE = /\b(?:npm\s+(?:install|i)|pnpm\s+add|yarn\s+add)\b/i;
+function isInstallCommand(input) {
+  if (input.toolName === "install") return true;
+  if (input.toolName !== "bash" && input.toolName !== "exec") return false;
+  const ti = input.toolInput ?? {};
+  const command = typeof ti["command"] === "string" ? ti["command"] : "";
+  return INSTALL_RE.test(command);
+}
+function detectManager() {
+  return existsSync("pnpm-lock.yaml") ? "pnpm" : "npm";
+}
+function runAudit(cfg) {
+  const manager = detectManager();
+  const start = Date.now();
+  let stdout = "";
+  try {
+    stdout = execFileSync(manager, ["audit", "--json"], {
+      encoding: "utf-8",
+      timeout: cfg.timeoutMs,
+      cwd: process.cwd(),
+      stdio: ["pipe", "pipe", "pipe"],
+      shell: false
+    });
+  } catch (err) {
+    const e = err;
+    if (e.killed) return null;
+    stdout = e.stdout ?? "";
+  }
+  const report = parseAuditJson(stdout);
+  if (!report) return null;
+  return { manager, report, durationMs: Date.now() - start };
+}
+var plugin = {
+  name: "dependency-vulnerability-gate",
+  version: "0.1.0",
+  description: "PostToolUse hook that runs npm/pnpm audit after dependency installs and blocks or warns on vulnerabilities above a severity threshold",
+  apiVersion: API_VERSION,
+  capabilities: { tools: true, hooks: true },
+  defaultConfig: { ...DEFAULTS },
+  configSchema: {
+    type: "object",
+    properties: {
+      enabled: {
+        type: "boolean",
+        default: true,
+        description: "Master switch."
+      },
+      severityThreshold: {
+        type: "string",
+        enum: ["low", "moderate", "high", "critical"],
+        default: "high",
+        description: "Minimum severity that triggers a block or warning."
+      },
+      block: {
+        type: "boolean",
+        default: true,
+        description: "true = block the install when threshold is exceeded; false = inject warning context."
+      },
+      timeoutMs: {
+        type: "number",
+        minimum: 5e3,
+        default: 12e4,
+        description: "Audit process timeout in milliseconds."
+      }
+    }
+  },
+  setup(api) {
+    state.invocations = 0;
+    state.installsSeen = 0;
+    state.auditsRun = 0;
+    state.blocks = 0;
+    state.warns = 0;
+    state.errors = 0;
+    state.lastResult = null;
+    if (state.hookUnregister) {
+      try {
+        state.hookUnregister();
+      } catch {
+      }
+      state.hookUnregister = null;
+    }
+    const cfg = readConfig(api.config.extensions?.["dependency-vulnerability-gate"]);
+    const hook = (input) => {
+      if (!cfg.enabled) return;
+      state.invocations += 1;
+      if (input.toolResult?.isError) return;
+      if (!isInstallCommand(input)) return;
+      state.installsSeen += 1;
+      api.metrics.counter("installs_seen");
+      const result = runAudit(cfg);
+      if (!result) {
+        state.errors += 1;
+        return;
+      }
+      state.auditsRun += 1;
+      state.lastResult = {
+        manager: result.manager,
+        exceeded: exceedsThreshold(result.report, cfg.severityThreshold),
+        maxSeverity: result.report.maxSeverity,
+        counts: result.report.counts,
+        durationMs: result.durationMs,
+        when: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      if (!exceedsThreshold(result.report, cfg.severityThreshold)) {
+        return;
+      }
+      const countsText = Object.entries(result.report.counts).filter(([, count]) => count > 0).map(([sev, count]) => `${sev}: ${count}`).join(", ");
+      const message = `
+\u26A0\uFE0F dependency-vulnerability-gate: ${result.manager} audit found vulnerabilities at or above the configured threshold (${cfg.severityThreshold}).
+  Max severity: ${result.report.maxSeverity}
+  Counts: ${countsText || "unknown"}
+Review the audit output or adjust the dependency choice.`;
+      if (cfg.block) {
+        state.blocks += 1;
+        api.metrics.counter("blocks");
+        return {
+          decision: "block",
+          reason: message
+        };
+      }
+      state.warns += 1;
+      api.metrics.counter("warns");
+      return { additionalContext: message };
+    };
+    state.hookUnregister = api.registerHook("PostToolUse", "install|bash|exec", hook);
+    api.tools.register({
+      name: "dependency_audit_status",
+      description: "Reports dependency-vulnerability-gate state: threshold, block mode, and per-session counters.",
+      inputSchema: { type: "object", properties: {} },
+      permission: "auto",
+      category: "Diagnostics",
+      mutating: false,
+      async execute() {
+        return {
+          ok: true,
+          enabled: cfg.enabled,
+          severityThreshold: cfg.severityThreshold,
+          block: cfg.block,
+          timeoutMs: cfg.timeoutMs,
+          counters: {
+            invocations: state.invocations,
+            installsSeen: state.installsSeen,
+            auditsRun: state.auditsRun,
+            blocks: state.blocks,
+            warns: state.warns,
+            errors: state.errors
+          },
+          lastResult: state.lastResult
+        };
+      }
+    });
+    api.log.info("dependency-vulnerability-gate plugin loaded", {
+      version: "0.1.0",
+      severityThreshold: cfg.severityThreshold,
+      block: cfg.block
+    });
+  },
+  teardown(api) {
+    if (state.hookUnregister) {
+      try {
+        state.hookUnregister();
+      } catch {
+      }
+      state.hookUnregister = null;
+    }
+    const final = {
+      invocations: state.invocations,
+      installsSeen: state.installsSeen,
+      auditsRun: state.auditsRun,
+      blocks: state.blocks,
+      warns: state.warns,
+      errors: state.errors
+    };
+    state.invocations = 0;
+    state.installsSeen = 0;
+    state.auditsRun = 0;
+    state.blocks = 0;
+    state.warns = 0;
+    state.errors = 0;
+    state.lastResult = null;
+    api.log.info("dependency-vulnerability-gate: teardown complete", { final });
+  },
+  async health() {
+    return {
+      ok: true,
+      message: state.lastResult ? `dependency-vulnerability-gate: ${state.auditsRun} audit(s), last ${state.lastResult.exceeded ? "EXCEEDED" : "clean"} (${state.lastResult.maxSeverity})` : `dependency-vulnerability-gate: ${state.installsSeen} install(s) seen, ${state.auditsRun} audit(s)`,
+      counters: {
+        invocations: state.invocations,
+        installsSeen: state.installsSeen,
+        auditsRun: state.auditsRun,
+        blocks: state.blocks,
+        warns: state.warns,
+        errors: state.errors
+      },
+      lastResult: state.lastResult
+    };
+  }
+};
+var dependency_vulnerability_gate_default = plugin;
+
+export { dependency_vulnerability_gate_default as default };

package/dist/diff-summary.js

@@ -1,13 +1,28 @@
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
+import { isAbsolute, resolve, relative } from 'path';
 
 // src/diff-summary/index.ts
 var API_VERSION = "^0.1.10";
+function withinProject(p) {
+  if (typeof p !== "string" || p.length === 0 || p.length > 4096) return false;
+  const root = process.cwd();
+  const resolved = isAbsolute(p) ? resolve(p) : resolve(root, p);
+  const rel = relative(root, resolved);
+  if (rel === "" || rel === ".") return true;
+  if (rel.startsWith("..")) return false;
+  if (isAbsolute(rel)) return false;
+  return true;
+}
 var state = {
   invocationCount: 0,
   /** Times a diff was successfully generated and injected. */
   injectedCount: 0,
   /** Times git diff failed (not a repo, untracked, etc.). */
   fallbackCount: 0,
+  /** Times the per-path throttle fired (no git diff was spawned). */
+  throttledCount: 0,
+  /** Times the content hash matched the last injection (no git diff). */
+  duplicateContentCount: 0,
   /** Hook handle for teardown. */
   hookUnregister: null,
   /** Last diff summary — surfaced by health() + status tool. */
@@ -17,7 +32,9 @@ var DEFAULTS = {
   maxLines: 50,
   showStat: true,
   mode: "diff",
-  includeContext: 3
+  includeContext: 3,
+  minIntervalMs: 1e3,
+  enableContentHashCache: true
 };
 function readConfig(raw) {
   if (!raw || typeof raw !== "object") return { ...DEFAULTS };
@@ -26,9 +43,20 @@ function readConfig(raw) {
     maxLines: typeof r["maxLines"] === "number" && r["maxLines"] > 0 ? r["maxLines"] : DEFAULTS.maxLines,
     showStat: r["showStat"] !== false,
     mode: r["mode"] === "stat" ? "stat" : r["mode"] === "off" ? "off" : "diff",
-    includeContext: typeof r["includeContext"] === "number" && r["includeContext"] >= 0 ? r["includeContext"] : DEFAULTS.includeContext
+    includeContext: typeof r["includeContext"] === "number" && r["includeContext"] >= 0 ? r["includeContext"] : DEFAULTS.includeContext,
+    minIntervalMs: typeof r["minIntervalMs"] === "number" && r["minIntervalMs"] >= 0 ? Math.floor(r["minIntervalMs"]) : DEFAULTS.minIntervalMs,
+    enableContentHashCache: r["enableContentHashCache"] !== false
   };
 }
+function contentHash(s) {
+  const cap = Math.min(s.length, 65536);
+  let h = 5381;
+  for (let i = 0; i < cap; i++) {
+    h = (h << 5) + h + s.charCodeAt(i) | 0;
+  }
+  return h >>> 0;
+}
+var pathMemo = /* @__PURE__ */ new Map();
 function getGitDiff(filePath, contextLines, cwd) {
   const opts = {
     encoding: "utf-8",
@@ -38,7 +66,7 @@ function getGitDiff(filePath, contextLines, cwd) {
   };
   let isTracked = false;
   try {
-    execSync(`git ls-files --error-unmatch "${filePath}"`, opts);
+    execFileSync("git", ["ls-files", "--error-unmatch", "--", filePath], opts);
     isTracked = true;
   } catch {
     isTracked = false;
@@ -47,10 +75,14 @@ function getGitDiff(filePath, contextLines, cwd) {
     let rawDiff;
     const contextFlag = `-U${contextLines}`;
     if (isTracked) {
-      rawDiff = execSync(`git diff ${contextFlag} -- "${filePath}"`, opts);
+      rawDiff = execFileSync("git", ["diff", contextFlag, "--", filePath], opts);
     } else {
       try {
-        rawDiff = execSync(`git diff --no-index ${contextFlag} /dev/null "${filePath}"`, opts);
+        rawDiff = execFileSync(
+          "git",
+          ["diff", "--no-index", contextFlag, "/dev/null", filePath],
+          opts
+        );
       } catch (err) {
         const e = err;
         rawDiff = e.stdout ?? "";
@@ -121,6 +153,17 @@ var plugin = {
         minimum: 0,
         default: 3,
         description: "Context lines around each change (git -U<N>). 0 = compact (no surrounding lines), 3 = git default, higher = more orientation."
+      },
+      minIntervalMs: {
+        type: "number",
+        minimum: 0,
+        default: 1e3,
+        description: "Per-path throttle: minimum interval (ms) between two diff-summary injections for the same file. Skips `git diff` when the model re-touches a file within the window. Set to 0 to disable."
+      },
+      enableContentHashCache: {
+        type: "boolean",
+        default: true,
+        description: 'When true, fingerprints the PostToolUse payload content and skips `git diff` when the hash matches the previously injected hash for the same path. Catches "edit retry" loops.'
       }
     }
   },
@@ -128,8 +171,11 @@ var plugin = {
     state.invocationCount = 0;
     state.injectedCount = 0;
     state.fallbackCount = 0;
+    state.throttledCount = 0;
+    state.duplicateContentCount = 0;
     state.hookUnregister = null;
     state.lastSummary = null;
+    pathMemo.clear();
     const cfg = readConfig(api.config.extensions?.["diff-summary"]);
     const cwd = typeof process.cwd === "function" ? process.cwd() : void 0;
     const hook = (input) => {
@@ -140,6 +186,25 @@ var plugin = {
       const filePath = inp["path"];
       if (!filePath || typeof filePath !== "string") return;
       state.invocationCount += 1;
+      if (!withinProject(filePath)) {
+        state.fallbackCount += 1;
+        return;
+      }
+      const toolInputForHash = toolName === "edit" ? inp["new_string"] ?? "" : toolName === "write" ? inp["content"] ?? "" : "";
+      const now = Date.now();
+      const memo = pathMemo.get(filePath);
+      if (memo) {
+        if (cfg.minIntervalMs > 0 && now - memo.lastInjectedAt < cfg.minIntervalMs) {
+          state.throttledCount = (state.throttledCount ?? 0) + 1;
+          api.metrics.counter("throttled");
+          return;
+        }
+        if (cfg.enableContentHashCache && typeof toolInputForHash === "string" && contentHash(toolInputForHash) === memo.hash) {
+          state.duplicateContentCount = (state.duplicateContentCount ?? 0) + 1;
+          api.metrics.counter("duplicate_content");
+          return;
+        }
+      }
       const result = getGitDiff(filePath, cfg.includeContext, cwd);
       if (!result) {
         state.fallbackCount += 1;
@@ -156,6 +221,17 @@ var plugin = {
         removed: result.removed,
         when: (/* @__PURE__ */ new Date()).toISOString()
       };
+      if (cfg.enableContentHashCache && typeof toolInputForHash === "string") {
+        pathMemo.set(filePath, {
+          hash: contentHash(toolInputForHash),
+          lastInjectedAt: now
+        });
+      } else if (cfg.minIntervalMs > 0) {
+        pathMemo.set(filePath, {
+          hash: 0,
+          lastInjectedAt: now
+        });
+      }
       let summary;
       if (cfg.mode === "stat") {
         summary = buildStatSummary(filePath, result);
@@ -183,10 +259,14 @@ var plugin = {
           maxLines: cfg.maxLines,
           showStat: cfg.showStat,
           includeContext: cfg.includeContext,
+          minIntervalMs: cfg.minIntervalMs,
+          enableContentHashCache: cfg.enableContentHashCache,
           counters: {
             invocations: state.invocationCount,
             injected: state.injectedCount,
-            fallbacks: state.fallbackCount
+            fallbacks: state.fallbackCount,
+            throttled: state.throttledCount,
+            duplicateContent: state.duplicateContentCount
           },
           lastSummary: state.lastSummary
         };
@@ -209,22 +289,29 @@ var plugin = {
     const final = {
       invocations: state.invocationCount,
       injected: state.injectedCount,
-      fallbacks: state.fallbackCount
+      fallbacks: state.fallbackCount,
+      throttled: state.throttledCount,
+      duplicateContent: state.duplicateContentCount
     };
     state.invocationCount = 0;
     state.injectedCount = 0;
     state.fallbackCount = 0;
+    state.throttledCount = 0;
+    state.duplicateContentCount = 0;
     state.lastSummary = null;
+    pathMemo.clear();
     api.log.info("diff-summary: teardown complete", { final });
   },
   async health() {
     return {
       ok: true,
-      message: state.lastSummary === null ? `diff-summary: ${state.invocationCount} invocation(s), ${state.injectedCount} injected` : `diff-summary: last ${state.lastSummary.tool} on ${state.lastSummary.path} (+${state.lastSummary.added} -${state.lastSummary.removed}) at ${state.lastSummary.when}`,
+      message: state.lastSummary === null ? `diff-summary: ${state.invocationCount} invocation(s), ${state.injectedCount} injected, ${state.throttledCount} throttled, ${state.duplicateContentCount} dup-content` : `diff-summary: last ${state.lastSummary.tool} on ${state.lastSummary.path} (+${state.lastSummary.added} -${state.lastSummary.removed}) at ${state.lastSummary.when}`,
       counters: {
         invocations: state.invocationCount,
         injected: state.injectedCount,
-        fallbacks: state.fallbackCount
+        fallbacks: state.fallbackCount,
+        throttled: state.throttledCount,
+        duplicateContent: state.duplicateContentCount
       },
       lastSummary: state.lastSummary
     };

package/dist/doc-sync-guard.d.ts

@@ -0,0 +1,33 @@
+import { Plugin } from '@wrongstack/core';
+
+/**
+ * doc-sync-guard plugin — warns when documentation is edited without
+ * referencing recently changed public source files.
+ *
+ * Tracks public source files changed by `write` or `edit`. When a README or
+ * docs file is written, checks whether the recently changed source files are
+ * mentioned and injects an `additionalContext` warning if any are missing.
+ *
+ * Tools registered:
+ * - doc_sync_status : Show tracked changed files and counters.
+ *
+ * Hooks registered:
+ * - PostToolUse with matcher `write|edit`.
+ *
+ * Config (`config.extensions['doc-sync-guard']`):
+ *
+ * ```jsonc
+ * {
+ *   "enabled": true,
+ *   "sourceExtensions": [".ts", ".tsx", ".js", ".jsx", ".mts", ".cts"],
+ *   "docNames": ["README.md", "README", "CONTRIBUTING.md", "CHANGELOG.md"],
+ *   "maxTrackedFiles": 20
+ * }
+ * ```
+ *
+ * @public
+ */
+
+declare const plugin: Plugin;
+
+export { plugin as default };