docguard-cli 0.30.0 → 0.30.1

package/README.md

@@ -13,6 +13,8 @@
 [![Node.js](https://img.shields.io/badge/Node.js-18%2B-green)](https://nodejs.org)
 [![Runtime deps](https://img.shields.io/badge/runtime_deps-1_(pinned)-green)](package.json)
 [![Spec Kit Extension](https://img.shields.io/badge/Spec_Kit-Extension-blueviolet)](https://github.com/github/spec-kit)
+[![Glama](https://glama.ai/mcp/servers/raccioly/docguard/badges/score.svg)](https://glama.ai/mcp/servers/raccioly/docguard)
+[![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-0a7ea4)](https://registry.modelcontextprotocol.io/)
 
 ---
 

package/cli/commands/mcp.mjs

@@ -53,25 +53,40 @@ const PROJECT_DIR_PROP = {
   },
 };
 
+// Every DocGuard MCP tool is READ-ONLY: it inspects local project files and
+// never writes, mutates, or reaches the network. These MCP tool hints let
+// clients (and directory scanners like Glama) surface that safety to users.
+const READONLY_ANNOTATIONS = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false,
+};
+
 const TOOLS = [
   {
     name: 'docguard_guard',
+    title: 'Guard docs against code',
     description: 'Run every enabled DocGuard validator against the project\'s canonical docs. Returns the full guard JSON contract: status (PASS/WARN/FAIL), structured findings with stable codes and suggestions, nextStep, doc coverage map, semantic-claim count, and per-validator results.',
     inputSchema: {
       type: 'object',
       properties: { ...PROJECT_DIR_PROP },
     },
+    annotations: READONLY_ANNOTATIONS,
   },
   {
     name: 'docguard_score',
+    title: 'CDD maturity score',
     description: 'Compute the project\'s CDD maturity score (0-100) with letter grade and per-category breakdown.',
     inputSchema: {
       type: 'object',
       properties: { ...PROJECT_DIR_PROP },
     },
+    annotations: READONLY_ANNOTATIONS,
   },
   {
     name: 'docguard_explain',
+    title: 'Explain a finding code',
     description: 'Explain a stable DocGuard finding code (e.g. STR001, ENV003): what it means, which validator emits it, and the inline suppression to use if it\'s a confirmed false positive.',
     inputSchema: {
       type: 'object',
@@ -83,22 +98,27 @@ const TOOLS = [
       },
       required: ['code'],
     },
+    annotations: READONLY_ANNOTATIONS,
   },
   {
     name: 'docguard_verify_claims',
+    title: 'Extract claims to verify',
     description: 'Extract the semantic claims in the project\'s canonical docs — documented numbers, limits, and enums — as a verification task list. Deterministic discovery, LLM judgment — the caller verifies each claim against the code.',
     inputSchema: {
       type: 'object',
       properties: { ...PROJECT_DIR_PROP },
     },
+    annotations: READONLY_ANNOTATIONS,
   },
   {
     name: 'docguard_diagnose',
+    title: 'Diagnose what to fix',
     description: 'Run guard and return only what needs fixing: failing/warning validators with their messages, structured findings, and suggested next actions — shaped for an agent to act on.',
     inputSchema: {
       type: 'object',
       properties: { ...PROJECT_DIR_PROP },
     },
+    annotations: READONLY_ANNOTATIONS,
   },
 ];
 

package/cli/commands/score.mjs

@@ -5,7 +5,7 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname } from 'node:path';
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import { c, docHasSection } from '../shared.mjs';
 import { validateSecurity } from '../validators/security.mjs';
 import { runGuardInternal } from './guard.mjs';
@@ -1039,11 +1039,16 @@ function estimateDocTax(projectDir, config, scores) {
   // Estimate code churn (commits in last 30 days)
   let recentCommits = 0;
   try {
-    const output = execSync('git log --oneline --since="30 days ago" 2>/dev/null | wc -l', {
+    // execFileSync (argv array) + count in JS — avoids the shell `| wc -l` pipe,
+    // which isn't portable to Windows (no `wc`) and needs a shell at all. Same
+    // pattern freshness.mjs already uses for commit counting.
+    const output = execFileSync('git', ['log', '--oneline', '--since=30 days ago'], {
       cwd: projectDir,
       encoding: 'utf-8',
-    }).trim();
-    recentCommits = parseInt(output, 10) || 0;
+      stdio: ['pipe', 'pipe', 'ignore'],
+      maxBuffer: 1024 * 1024 * 5,
+    });
+    recentCommits = output.trim() ? output.trim().split('\n').length : 0;
   } catch {
     recentCommits = 10; // Default assumption
   }

package/cli/commands/setup.mjs

@@ -21,7 +21,6 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from
 import { resolve, dirname, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createInterface } from 'node:readline';
-import { execSync } from 'node:child_process';
 import { c, CURRENT_SCHEMA_VERSION } from '../shared.mjs';
 import { ensureSkills, detectAgentMode, isSpecKitInitialized, getDetectedAgent } from '../ensure-skills.mjs';
 
@@ -70,18 +69,6 @@ function detectProjectType(dir) {
   return 'unknown';
 }
 
-// ── CLI Detection ───────────────────────────────────────────────────────
-
-function isCliAvailable(name) {
-  try {
-    const cmd = process.platform === 'win32' ? `where ${name}` : `which ${name}`;
-    execSync(`${cmd} 2>/dev/null`, { encoding: 'utf-8', timeout: 3000 });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 function detectAgentDirs(projectDir) {
   const agentDirs = [
     { name: 'GitHub Copilot', dir: '.github', commandsPath: '.github/commands' },

package/cli/shared-git.mjs

@@ -167,7 +167,14 @@ export function getHooksDir(dir) {
     ).trim();
     // --git-path returns a path relative to `dir` (cwd) or an absolute path;
     // resolve() handles both.
-    if (out) return resolve(dir, out);
+    //
+    // Guard `/dev/null`: when `core.hooksPath` is set to /dev/null (a common
+    // "disable all hooks" convention — and what Jules's sandbox VM does),
+    // git returns the literal `/dev/null`. resolve()-ing it and then writing
+    // `<hooksDir>/pre-commit` gives `ENOTDIR: /dev/null/pre-commit`. Treat it
+    // as "no usable hooks dir" and fall through to the `.git/hooks` check so
+    // hook install/list still works in that environment. (bug-200)
+    if (out && out !== '/dev/null') return resolve(dir, out);
   } catch {
     // git unavailable or not a repo — fall through to the literal-path check.
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docguard-cli",
-  "version": "0.30.0",
+  "version": "0.30.1",
   "description": "The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation.",
   "type": "module",
   "bin": {