speclock 5.5.3 → 5.5.5

package/src/core/auth.js

@@ -1,3 +1,11 @@
+// ============================================================
+// SPECLOCK-GUARD — DO NOT MODIFY THIS FILE
+// LOCKED: NEVER modify auth files
+// THIS FILE IS LOCKED. DO NOT EDIT, CHANGE, OR REWRITE ANY PART OF IT.
+// The user must say "unlock" before this file can be changed.
+// A question is NOT permission. Asking about features is NOT permission.
+// ONLY "unlock" or "remove the lock" is permission to edit this file.
+// ============================================================
 /**
  * SpecLock API Key Authentication
  * Provides API key generation, validation, rotation, and revocation.

package/src/core/compliance.js

@@ -9,7 +9,7 @@
 import { readBrain, readEvents } from "./storage.js";
 import { verifyAuditChain } from "./audit.js";
 
-const VERSION = "5.5.3";
+const VERSION = "5.5.5";
 
 // PHI-related keywords for HIPAA filtering
 const PHI_KEYWORDS = [

package/src/core/enforcer.js

@@ -29,10 +29,16 @@ import { analyzeConflict } from "./semantics.js";
 
 /**
  * Get enforcement config from brain, with defaults.
+ *
+ * Default mode is "advisory" (warn only). Users opt in to hard blocking
+ * with `speclock protect --strict`, `speclock enforce hard`, the --strict
+ * flag on audit commands, or SPECLOCK_STRICT=1 env var. The investor audit
+ * found hard-block-by-default caused uninstalls within an hour due to the
+ * heuristic false-positive rate on things like "Refactor login page".
  */
 export function getEnforcementConfig(brain) {
   const defaults = {
-    mode: "advisory",       // "advisory" | "hard"
+    mode: "advisory",       // "advisory" (warn — default) | "hard" (block)
     blockThreshold: 70,     // minimum confidence % to block in hard mode
     allowOverride: true,    // whether overrides are permitted
     escalationLimit: 3,     // overrides before auto-note

package/src/core/guardian.js

@@ -16,9 +16,46 @@ import { installHook, isHookInstalled } from "./hooks.js";
 import { syncRules } from "./rules-sync.js";
 import { generateContext } from "./context.js";
 
+// --- Starter CLAUDE.md for greenfield projects ---
+
+const STARTER_CLAUDE_MD = `# Project Rules
+
+These rules are enforced by SpecLock — your AI coding assistant will respect them.
+
+## Database & Storage
+- NEVER delete user data without explicit confirmation
+- NEVER modify production database schema without migration
+
+## Authentication & Security
+- NEVER modify authentication files without security review
+- NEVER commit secrets, API keys, or credentials
+- NEVER disable security checks "temporarily"
+
+## Code Quality
+- ALWAYS write tests for new features
+- NEVER push directly to main branch
+- NEVER skip code review on critical paths
+
+## Edit these rules to match your project. Add your own with:
+##   speclock add-lock "Your rule here"
+`;
+
+/**
+ * Create a starter CLAUDE.md with safe defaults for greenfield projects.
+ * Used when `protect` is called on a project with no existing rule files.
+ */
+export function createStarterClaudeMd(root) {
+  const filePath = path.join(root, "CLAUDE.md");
+  if (fs.existsSync(filePath)) {
+    return { created: false, path: filePath, reason: "already exists" };
+  }
+  fs.writeFileSync(filePath, STARTER_CLAUDE_MD);
+  return { created: true, path: filePath };
+}
+
 // --- Rule file discovery ---
 
-const RULE_FILES = [
+export const RULE_FILES = [
   { file: ".cursorrules", tool: "Cursor" },
   { file: ".cursor/rules/rules.mdc", tool: "Cursor (MDC)" },
   { file: "CLAUDE.md", tool: "Claude Code" },
@@ -209,13 +246,29 @@ export function protect(root, options = {}) {
     hookStatus: "",
     synced: [],
     errors: [],
+    starterCreated: false,
+    starterPath: null,
+    strict: options.strict === true,
   };
 
   // 1. Init
   const brain = ensureInit(root);
 
   // 2. Discover
-  const ruleFiles = discoverRuleFiles(root);
+  let ruleFiles = discoverRuleFiles(root);
+
+  // 2b. Greenfield support: if no rule files found, auto-create a starter
+  // CLAUDE.md with safe defaults (unless explicitly disabled).
+  if (ruleFiles.length === 0 && !options.skipStarter) {
+    const starter = createStarterClaudeMd(root);
+    if (starter.created) {
+      report.starterCreated = true;
+      report.starterPath = "CLAUDE.md";
+      // Re-run discovery so the flow continues normally with the new file.
+      ruleFiles = discoverRuleFiles(root);
+    }
+  }
+
   report.discovered = ruleFiles.map((f) => ({
     file: f.file,
     tool: f.tool,
@@ -321,13 +374,20 @@ export function formatProtectReport(report) {
   lines.push("  " + "=".repeat(50));
   lines.push("");
 
+  // Starter CLAUDE.md was auto-created (greenfield support)
+  if (report.starterCreated) {
+    lines.push("  No rule files found.");
+    lines.push(`  [+] Created starter CLAUDE.md with safe defaults — edit it to match your project.`);
+    lines.push("");
+  }
+
   // Discovered files
   if (report.discovered.length > 0) {
     lines.push("  Rule files found:");
     for (const f of report.discovered) {
       lines.push(`    [+] ${f.file} (${f.tool}, ${f.lines} lines)`);
     }
-  } else {
+  } else if (!report.starterCreated) {
     lines.push("  [!] No rule files found.");
   }
   lines.push("");
@@ -375,8 +435,21 @@ export function formatProtectReport(report) {
   // Final message
   const total = report.added.locks + report.added.skipped;
   if (total > 0) {
-    lines.push("  Your rules are now ENFORCED, not just suggested.");
-    lines.push("  AI agents that violate constraints will be blocked.");
+    if (report.strict) {
+      lines.push("  Your rules are now ENFORCED (strict mode).");
+      lines.push("  Commits that violate constraints will be BLOCKED.");
+    } else {
+      lines.push("  Your rules are now TRACKED (warning mode — default).");
+      lines.push("  Violations will be printed loudly, but commits will NOT be blocked.");
+      lines.push("  Opt in to hard enforcement any time with: speclock protect --strict");
+    }
+  }
+
+  // Greenfield guidance — tell the user to edit the starter file
+  if (report.starterCreated) {
+    lines.push("");
+    lines.push("  Next: edit CLAUDE.md to add project-specific rules, then run:");
+    lines.push('    speclock check "your action here"');
   }
   lines.push("");
 

package/src/core/hooks.js

@@ -8,11 +8,14 @@ const HOOK_MARKER = "# SPECLOCK-HOOK";
 
 const HOOK_SCRIPT = `#!/bin/sh
 ${HOOK_MARKER} — Do not remove this line
-# SpecLock pre-commit hook: checks staged files against active locks
+# SpecLock pre-commit hook: runs semantic audit of staged diff + commit message
+# against active locks. Unlike the legacy 'audit' subcommand, this one feeds
+# the actual diff content AND the commit message through the semantic conflict
+# engine — the same one used by 'speclock check'.
 # Install: npx speclock hook install
 # Remove:  npx speclock hook remove
 
-npx speclock audit
+npx speclock audit-semantic --pre-commit
 exit $?
 `;
 

package/src/core/lock-author.js

@@ -1,3 +1,11 @@
+// ============================================================
+// SPECLOCK-GUARD — DO NOT MODIFY THIS FILE
+// LOCKED: NEVER modify auth files
+// THIS FILE IS LOCKED. DO NOT EDIT, CHANGE, OR REWRITE ANY PART OF IT.
+// The user must say "unlock" before this file can be changed.
+// A question is NOT permission. Asking about features is NOT permission.
+// ONLY "unlock" or "remove the lock" is permission to edit this file.
+// ============================================================
 // ===================================================================
 // SpecLock Smart Lock Authoring Engine
 // Auto-rewrites user locks to prevent verb contamination.

package/src/core/mcp-install.js

@@ -0,0 +1,484 @@
+/**
+ * SpecLock MCP Autoinstaller
+ * One-command installer: wires SpecLock as an MCP server into any AI client.
+ *
+ * Usage (CLI):
+ *   speclock mcp install <client>     — claude-code|cursor|windsurf|cline|codex|all
+ *   speclock mcp uninstall <client>
+ *
+ * The investor audit found the biggest manual friction was users having to
+ * hand-edit JSON to wire up SpecLock as an MCP server. This module removes
+ * that friction entirely — one command, any supported client, any OS.
+ *
+ * Developed by Sandeep Roy (https://github.com/sgroy10)
+ */
+
+import fs from "fs";
+import path from "path";
+import os from "os";
+
+// The stanza we inject. Kept in one place so every client stays in sync.
+export const SPECLOCK_MCP_STANZA = {
+  command: "npx",
+  args: ["-y", "speclock", "serve"],
+};
+
+export const SUPPORTED_CLIENTS = [
+  "claude-code",
+  "cursor",
+  "windsurf",
+  "cline",
+  "codex",
+  "all",
+];
+
+/**
+ * Resolve the config file locations for a given client on the current OS.
+ * Returns { primary, project } where each is { path, format }.
+ * format is "json" | "toml" | "vscode-json".
+ *
+ * - primary  = global/user-level config (always attempted)
+ * - project  = project-scoped config (only written if --project flag used)
+ */
+export function getClientConfigPaths(client, projectRoot = process.cwd()) {
+  const home = os.homedir();
+  const platform = process.platform; // "win32" | "darwin" | "linux"
+
+  switch (client) {
+    case "claude-code": {
+      return {
+        primary: {
+          path: path.join(home, ".claude", "mcp.json"),
+          format: "json",
+          label: "Claude Code",
+        },
+        project: {
+          path: path.join(projectRoot, ".mcp.json"),
+          format: "json",
+          label: "Claude Code (project)",
+        },
+      };
+    }
+
+    case "cursor": {
+      return {
+        primary: {
+          path: path.join(home, ".cursor", "mcp.json"),
+          format: "json",
+          label: "Cursor",
+        },
+        project: {
+          path: path.join(projectRoot, ".cursor", "mcp.json"),
+          format: "json",
+          label: "Cursor (project)",
+        },
+      };
+    }
+
+    case "windsurf": {
+      return {
+        primary: {
+          path: path.join(home, ".codeium", "windsurf", "mcp_config.json"),
+          format: "json",
+          label: "Windsurf",
+        },
+        project: null,
+      };
+    }
+
+    case "cline": {
+      // Cline lives inside VS Code User settings.json.
+      let settingsPath;
+      if (platform === "win32") {
+        settingsPath = path.join(
+          process.env.APPDATA || path.join(home, "AppData", "Roaming"),
+          "Code",
+          "User",
+          "settings.json"
+        );
+      } else if (platform === "darwin") {
+        settingsPath = path.join(
+          home,
+          "Library",
+          "Application Support",
+          "Code",
+          "User",
+          "settings.json"
+        );
+      } else {
+        settingsPath = path.join(home, ".config", "Code", "User", "settings.json");
+      }
+      return {
+        primary: {
+          path: settingsPath,
+          format: "vscode-json",
+          label: "Cline (VS Code settings)",
+        },
+        project: null,
+      };
+    }
+
+    case "codex": {
+      return {
+        primary: {
+          path: path.join(home, ".codex", "config.toml"),
+          format: "toml",
+          label: "Codex",
+        },
+        project: null,
+      };
+    }
+
+    default:
+      throw new Error(
+        `Unknown client "${client}". Supported: ${SUPPORTED_CLIENTS.join(", ")}`
+      );
+  }
+}
+
+// --- JSON helpers ---
+
+function readJsonSafe(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    const raw = fs.readFileSync(filePath, "utf-8").trim();
+    if (!raw) return {};
+    return JSON.parse(raw);
+  } catch (e) {
+    throw new Error(`Could not parse JSON at ${filePath}: ${e.message}`);
+  }
+}
+
+function writeJson(filePath, data) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n", "utf-8");
+}
+
+/**
+ * Merge speclock into a plain JSON config that uses "mcpServers".
+ * Preserves all other servers and top-level keys.
+ */
+function injectJson(config) {
+  const next = { ...(config || {}) };
+  if (!next.mcpServers || typeof next.mcpServers !== "object") {
+    next.mcpServers = {};
+  }
+  next.mcpServers = {
+    ...next.mcpServers,
+    speclock: { ...SPECLOCK_MCP_STANZA },
+  };
+  return next;
+}
+
+function removeJson(config) {
+  if (!config || typeof config !== "object") return { changed: false, config };
+  if (!config.mcpServers || !config.mcpServers.speclock) {
+    return { changed: false, config };
+  }
+  const next = { ...config, mcpServers: { ...config.mcpServers } };
+  delete next.mcpServers.speclock;
+  return { changed: true, config: next };
+}
+
+/**
+ * VS Code settings.json uses JSONC (comments + trailing commas).
+ * We do a best-effort: if parse fails, we fall back to a safe string rewrite
+ * that touches only the "cline.mcpServers" block.
+ */
+function injectVsCodeJson(filePath) {
+  const exists = fs.existsSync(filePath);
+  let parsed = null;
+  let raw = "";
+
+  if (exists) {
+    raw = fs.readFileSync(filePath, "utf-8");
+    try {
+      // Try a lenient parse: strip line/block comments and trailing commas.
+      const stripped = raw
+        .replace(/\/\*[\s\S]*?\*\//g, "")
+        .replace(/(^|[^:])\/\/.*$/gm, "$1")
+        .replace(/,(\s*[}\]])/g, "$1");
+      parsed = stripped.trim() ? JSON.parse(stripped) : {};
+    } catch {
+      parsed = null; // fall back to string append below
+    }
+  }
+
+  if (parsed !== null) {
+    const next = { ...parsed };
+    // Cline reads either "cline.mcpServers" or "mcpServers". We write the
+    // Cline-specific key to avoid clashing with other VS Code extensions.
+    const existing = next["cline.mcpServers"] || {};
+    next["cline.mcpServers"] = {
+      ...existing,
+      speclock: { ...SPECLOCK_MCP_STANZA },
+    };
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(next, null, 2) + "\n", "utf-8");
+    return { mode: "parsed" };
+  }
+
+  // Fallback: file has comments or odd formatting. Append a marker block.
+  // This is safe: VS Code's JSONC parser accepts duplicate keys (last wins)
+  // but to avoid corruption we just warn the user instead of rewriting.
+  throw new Error(
+    `Could not safely parse VS Code settings at ${filePath}. ` +
+      `Please add this manually:\n` +
+      `  "cline.mcpServers": { "speclock": ${JSON.stringify(
+        SPECLOCK_MCP_STANZA
+      )} }`
+  );
+}
+
+function removeVsCodeJson(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return { changed: false };
+  }
+  const raw = fs.readFileSync(filePath, "utf-8");
+  let parsed;
+  try {
+    const stripped = raw
+      .replace(/\/\*[\s\S]*?\*\//g, "")
+      .replace(/(^|[^:])\/\/.*$/gm, "$1")
+      .replace(/,(\s*[}\]])/g, "$1");
+    parsed = stripped.trim() ? JSON.parse(stripped) : {};
+  } catch {
+    throw new Error(
+      `Could not safely parse VS Code settings at ${filePath}. ` +
+        `Please remove "speclock" from "cline.mcpServers" manually.`
+    );
+  }
+  const block = parsed["cline.mcpServers"];
+  if (!block || !block.speclock) return { changed: false };
+  const next = { ...parsed, "cline.mcpServers": { ...block } };
+  delete next["cline.mcpServers"].speclock;
+  fs.writeFileSync(filePath, JSON.stringify(next, null, 2) + "\n", "utf-8");
+  return { changed: true };
+}
+
+// --- TOML helpers (Codex ~/.codex/config.toml) ---
+//
+// Codex uses an extremely small TOML dialect for MCP servers:
+//   [mcp_servers.speclock]
+//   command = "npx"
+//   args = ["-y", "speclock", "serve"]
+//
+// We do NOT pull in a TOML parser dependency. We implement a targeted
+// inject/remove that leaves other [mcp_servers.*] tables untouched.
+
+const CODEX_STANZA = [
+  "",
+  "[mcp_servers.speclock]",
+  'command = "npx"',
+  'args = ["-y", "speclock", "serve"]',
+  "",
+].join("\n");
+
+function injectToml(filePath) {
+  let existing = "";
+  if (fs.existsSync(filePath)) {
+    existing = fs.readFileSync(filePath, "utf-8");
+    if (existing.includes("[mcp_servers.speclock]")) {
+      return { changed: false, reason: "already present" };
+    }
+  } else {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  }
+  const trimmed = existing.replace(/\s+$/, "");
+  const next = (trimmed ? trimmed + "\n" : "") + CODEX_STANZA;
+  fs.writeFileSync(filePath, next, "utf-8");
+  return { changed: true };
+}
+
+function removeToml(filePath) {
+  if (!fs.existsSync(filePath)) return { changed: false };
+  const raw = fs.readFileSync(filePath, "utf-8");
+  if (!raw.includes("[mcp_servers.speclock]")) {
+    return { changed: false };
+  }
+  // Remove the [mcp_servers.speclock] block up to the next [section] or EOF.
+  const cleaned = raw.replace(
+    /\n?\[mcp_servers\.speclock\][\s\S]*?(?=\n\[|\n*$)/,
+    ""
+  );
+  fs.writeFileSync(filePath, cleaned.replace(/\s+$/, "") + "\n", "utf-8");
+  return { changed: true };
+}
+
+// --- Public API ---
+
+/**
+ * Install SpecLock MCP server into a single client.
+ * Returns { client, writes: [{ path, status, label }], errors: [] }.
+ */
+export function installForClient(client, projectRoot = process.cwd(), options = {}) {
+  const includeProject = options.includeProject !== false; // default: yes
+  const result = { client, writes: [], errors: [] };
+
+  let paths;
+  try {
+    paths = getClientConfigPaths(client, projectRoot);
+  } catch (e) {
+    result.errors.push(e.message);
+    return result;
+  }
+
+  const targets = [paths.primary];
+  if (includeProject && paths.project) targets.push(paths.project);
+
+  for (const target of targets) {
+    if (!target) continue;
+    try {
+      let status;
+      if (target.format === "json") {
+        const current = readJsonSafe(target.path) || {};
+        const next = injectJson(current);
+        writeJson(target.path, next);
+        status = "installed";
+      } else if (target.format === "vscode-json") {
+        const out = injectVsCodeJson(target.path);
+        status = out.mode === "parsed" ? "installed" : "installed";
+      } else if (target.format === "toml") {
+        const out = injectToml(target.path);
+        status = out.changed ? "installed" : "already present";
+      } else {
+        throw new Error(`Unsupported format: ${target.format}`);
+      }
+
+      result.writes.push({
+        path: target.path,
+        status,
+        label: target.label,
+      });
+    } catch (e) {
+      result.errors.push(`${target.label}: ${e.message}`);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Uninstall SpecLock MCP server from a single client.
+ */
+export function uninstallForClient(client, projectRoot = process.cwd(), options = {}) {
+  const includeProject = options.includeProject !== false;
+  const result = { client, writes: [], errors: [] };
+
+  let paths;
+  try {
+    paths = getClientConfigPaths(client, projectRoot);
+  } catch (e) {
+    result.errors.push(e.message);
+    return result;
+  }
+
+  const targets = [paths.primary];
+  if (includeProject && paths.project) targets.push(paths.project);
+
+  for (const target of targets) {
+    if (!target) continue;
+    if (!fs.existsSync(target.path)) {
+      result.writes.push({
+        path: target.path,
+        status: "not installed",
+        label: target.label,
+      });
+      continue;
+    }
+
+    try {
+      let changed = false;
+      if (target.format === "json") {
+        const current = readJsonSafe(target.path) || {};
+        const out = removeJson(current);
+        if (out.changed) {
+          writeJson(target.path, out.config);
+          changed = true;
+        }
+      } else if (target.format === "vscode-json") {
+        const out = removeVsCodeJson(target.path);
+        changed = out.changed;
+      } else if (target.format === "toml") {
+        const out = removeToml(target.path);
+        changed = out.changed;
+      }
+
+      result.writes.push({
+        path: target.path,
+        status: changed ? "removed" : "not installed",
+        label: target.label,
+      });
+    } catch (e) {
+      result.errors.push(`${target.label}: ${e.message}`);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Install across all supported clients at once.
+ */
+export function installAll(projectRoot = process.cwd(), options = {}) {
+  const clients = SUPPORTED_CLIENTS.filter((c) => c !== "all");
+  const results = [];
+  for (const c of clients) {
+    results.push(installForClient(c, projectRoot, options));
+  }
+  return results;
+}
+
+export function uninstallAll(projectRoot = process.cwd(), options = {}) {
+  const clients = SUPPORTED_CLIENTS.filter((c) => c !== "all");
+  const results = [];
+  for (const c of clients) {
+    results.push(uninstallForClient(c, projectRoot, options));
+  }
+  return results;
+}
+
+/**
+ * Format an install/uninstall result for console output.
+ */
+export function formatResult(result, action = "install") {
+  const lines = [];
+  const hasErrors = result.errors && result.errors.length > 0;
+  const verb = action === "install" ? "added to" : "removed from";
+
+  for (const w of result.writes) {
+    if (w.status === "installed") {
+      lines.push(`  [OK] SpecLock ${verb} ${w.label} config at: ${w.path}`);
+    } else if (w.status === "removed") {
+      lines.push(`  [OK] SpecLock ${verb} ${w.label} config at: ${w.path}`);
+    } else if (w.status === "already present") {
+      lines.push(`  [--] SpecLock already present in ${w.label}: ${w.path}`);
+    } else if (w.status === "not installed") {
+      lines.push(`  [--] SpecLock not present in ${w.label}: ${w.path}`);
+    } else {
+      lines.push(`  [??] ${w.label}: ${w.status} — ${w.path}`);
+    }
+  }
+
+  if (hasErrors) {
+    for (const e of result.errors) {
+      lines.push(`  [!!] ${e}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Next-steps hint shown after a successful install.
+ */
+export function nextStepsFor(client) {
+  const hints = {
+    "claude-code": "Restart Claude Code to activate SpecLock.",
+    cursor: "Restart Cursor (Cmd/Ctrl+Shift+P → Reload Window) to activate SpecLock.",
+    windsurf: "Restart Windsurf to activate SpecLock.",
+    cline: "Reload VS Code (Cmd/Ctrl+Shift+P → Developer: Reload Window) to activate SpecLock in Cline.",
+    codex: "Restart Codex CLI to activate SpecLock.",
+  };
+  return hints[client] || "Restart your AI client to activate SpecLock.";
+}