speclock 4.3.1 → 4.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "speclock",
-  "version": "4.3.1",
+  "version": "4.3.3",
   "description": "AI constraint engine with Gemini LLM universal detection, Policy-as-Code DSL, OAuth/OIDC SSO, admin dashboard, telemetry, API key auth, RBAC, AES-256-GCM encryption, hard enforcement, semantic pre-commit, HMAC audit chain, SOC 2/HIPAA compliance. Cross-platform: MCP + direct API. 31 MCP tools + CLI. Enterprise platform.",
   "type": "module",
   "main": "src/mcp/server.js",

package/src/cli/index.js

@@ -116,7 +116,7 @@ function refreshContext(root) {
 
 function printHelp() {
   console.log(`
-SpecLock v4.3.1 — AI Constraint Engine (Gemini LLM + Policy-as-Code + SSO + Dashboard + Telemetry + Auth + RBAC + Encryption)
+SpecLock v4.3.3 — AI Constraint Engine (Gemini LLM + Policy-as-Code + SSO + Dashboard + Telemetry + Auth + RBAC + Encryption)
 Developed by Sandeep Roy (github.com/sgroy10)
 
 Usage: speclock <command> [options]

package/src/core/compliance.js

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

package/src/core/conflict.js

@@ -204,12 +204,69 @@ export function checkConflict(rootOrAction, proposedActionOrLock) {
   return result;
 }
 
+/**
+ * Default proxy URL for npm-install users who don't have their own LLM API key.
+ * The Railway-hosted SpecLock server provides Gemini LLM checking via /api/check.
+ * Disable with SPECLOCK_NO_PROXY=true. Override with SPECLOCK_PROXY_URL.
+ */
+const DEFAULT_PROXY_URL = "https://speclock-mcp-production.up.railway.app/api/check";
+
+/**
+ * Call the Railway proxy for LLM-powered conflict checking.
+ * Used when no local LLM API key is available.
+ * @returns {Object|null} Proxy result or null on failure
+ */
+async function callProxy(actionText, lockTexts) {
+  if (process.env.SPECLOCK_NO_PROXY === "true") return null;
+  const proxyUrl = process.env.SPECLOCK_PROXY_URL || DEFAULT_PROXY_URL;
+
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 10000); // 10s timeout
+
+    const resp = await fetch(proxyUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ action: actionText, locks: lockTexts }),
+      signal: controller.signal,
+    });
+    clearTimeout(timeout);
+
+    if (!resp.ok) return null;
+    const data = await resp.json();
+
+    if (!data || typeof data.hasConflict !== "boolean") return null;
+
+    // Convert proxy response to internal format
+    const conflicts = (data.conflicts || []).map((c) => ({
+      id: "proxy",
+      text: c.lockText,
+      matchedKeywords: [],
+      confidence: c.confidence,
+      level: c.level || "MEDIUM",
+      reasons: c.reasons || [],
+    }));
+
+    return {
+      hasConflict: data.hasConflict,
+      conflictingLocks: conflicts,
+      analysis: data.hasConflict
+        ? `${conflicts.length} conflict(s) detected via proxy (${data.source}).`
+        : `Proxy verified as safe (${data.source}). No conflicts.`,
+    };
+  } catch (_) {
+    // Proxy unavailable — graceful degradation
+    return null;
+  }
+}
+
 /**
  * Async conflict check with LLM fallback for grey-zone cases.
  * Supports both brain mode and direct mode (same as checkConflict).
  * Strategy: Run heuristic first (fast, free, offline).
  *   - Score > 70% on ALL conflicts → trust heuristic (skip LLM)
  *   - Everything else → call LLM for universal domain coverage
+ *   - If no local LLM key → call Railway proxy for Gemini coverage
  */
 export async function checkConflictAsync(rootOrAction, proposedActionOrLock) {
   // 1. Always run the fast heuristic first (handles both brain + direct mode)
@@ -224,12 +281,9 @@ export async function checkConflictAsync(rootOrAction, proposedActionOrLock) {
     return heuristicResult;
   }
 
-  // 3. Call LLM for everything else — including score 0.
-  // Score 0 means "heuristic vocabulary doesn't cover this domain",
-  // which is EXACTLY when an LLM (which knows every domain) adds value.
+  // 3. Try local LLM first (if user has their own API key)
   try {
     const { llmCheckConflict } = await import("./llm-checker.js");
-    // In direct mode, build activeLocks from the lock text(s) passed directly
     let llmResult;
     if (isDirect) {
       const lockTexts = Array.isArray(proposedActionOrLock)
@@ -246,45 +300,77 @@ export async function checkConflictAsync(rootOrAction, proposedActionOrLock) {
     }
 
     if (llmResult) {
-      // Keep HIGH heuristic conflicts (>70%) — they're already certain
-      const highConfidence = heuristicResult.conflictingLocks.filter(
-        (c) => c.confidence > 70
-      );
-      const llmConflicts = llmResult.conflictingLocks || [];
-      const merged = [...highConfidence, ...llmConflicts];
-
-      // Deduplicate by lock text, keeping the higher-confidence entry
-      const byText = new Map();
-      for (const c of merged) {
-        const existing = byText.get(c.text);
-        if (!existing || c.confidence > existing.confidence) {
-          byText.set(c.text, c);
-        }
-      }
-      const unique = [...byText.values()];
-
-      if (unique.length === 0) {
-        return {
-          hasConflict: false,
-          conflictingLocks: [],
-          analysis: `Heuristic had partial signal, LLM verified as safe. No conflicts.`,
-        };
-      }
+      return mergeLLMResult(heuristicResult, llmResult);
+    }
+  } catch (_) {
+    // Local LLM not available
+  }
 
-      unique.sort((a, b) => b.confidence - a.confidence);
-      return {
-        hasConflict: true,
-        conflictingLocks: unique,
-        analysis: `${unique.length} conflict(s) confirmed (${highConfidence.length} heuristic + ${llmConflicts.length} LLM-verified).`,
-      };
+  // 4. No local LLM → call Railway proxy for Gemini coverage
+  try {
+    let lockTexts;
+    if (isDirect) {
+      lockTexts = Array.isArray(proposedActionOrLock)
+        ? proposedActionOrLock
+        : [proposedActionOrLock];
+    } else {
+      // Brain mode: extract lock texts from brain
+      const brain = ensureInit(rootOrAction);
+      const activeLocks = (brain.specLock?.items || []).filter((l) => l.active !== false);
+      lockTexts = activeLocks.map((l) => l.text);
+    }
+
+    const actionText = isDirect ? rootOrAction : proposedActionOrLock;
+    if (lockTexts.length > 0) {
+      const proxyResult = await callProxy(actionText, lockTexts);
+      if (proxyResult) {
+        return mergeLLMResult(heuristicResult, proxyResult);
+      }
     }
   } catch (_) {
-    // LLM not available — return heuristic result as-is
+    // Proxy unavailable — graceful degradation
   }
 
   return heuristicResult;
 }
 
+/**
+ * Merge heuristic result with LLM/proxy result.
+ * Keeps HIGH heuristic conflicts + all LLM conflicts, deduplicates, takes MAX.
+ */
+function mergeLLMResult(heuristicResult, llmResult) {
+  const highConfidence = heuristicResult.conflictingLocks.filter(
+    (c) => c.confidence > 70
+  );
+  const llmConflicts = llmResult.conflictingLocks || [];
+  const merged = [...highConfidence, ...llmConflicts];
+
+  // Deduplicate by lock text, keeping the higher-confidence entry
+  const byText = new Map();
+  for (const c of merged) {
+    const existing = byText.get(c.text);
+    if (!existing || c.confidence > existing.confidence) {
+      byText.set(c.text, c);
+    }
+  }
+  const unique = [...byText.values()];
+
+  if (unique.length === 0) {
+    return {
+      hasConflict: false,
+      conflictingLocks: [],
+      analysis: `Heuristic had partial signal, LLM verified as safe. No conflicts.`,
+    };
+  }
+
+  unique.sort((a, b) => b.confidence - a.confidence);
+  return {
+    hasConflict: true,
+    conflictingLocks: unique,
+    analysis: `${unique.length} conflict(s) confirmed (${highConfidence.length} heuristic + ${llmConflicts.length} LLM-verified).`,
+  };
+}
+
 export function suggestLocks(root) {
   const brain = ensureInit(root);
   const suggestions = [];

package/src/core/telemetry.js

@@ -257,7 +257,7 @@ export async function flushToRemote(root) {
   // Build anonymized payload
   const payload = {
     instanceId: summary.instanceId,
-    version: "4.3.1",
+    version: "4.3.3",
     totalCalls: summary.totalCalls,
     avgResponseMs: summary.avgResponseMs,
     conflicts: summary.conflicts,

package/src/dashboard/index.html

@@ -89,7 +89,7 @@
 <div class="header">
   <div>
     <h1><span>SpecLock</span> Dashboard</h1>
-    <div class="meta">v4.3.1 &mdash; AI Constraint Engine</div>
+    <div class="meta">v4.3.3 &mdash; AI Constraint Engine</div>
   </div>
   <div style="display:flex;align-items:center;gap:12px;">
     <span id="health-badge" class="status-badge healthy">Loading...</span>
@@ -182,7 +182,7 @@
 </div>
 
 <div style="text-align:center;padding:24px;color:var(--muted);font-size:12px;">
-  SpecLock v4.3.1 &mdash; Developed by Sandeep Roy &mdash; <a href="https://github.com/sgroy10/speclock" style="color:var(--accent)">GitHub</a>
+  SpecLock v4.3.3 &mdash; Developed by Sandeep Roy &mdash; <a href="https://github.com/sgroy10/speclock" style="color:var(--accent)">GitHub</a>
 </div>
 
 <script>

package/src/mcp/http-server.js

@@ -91,7 +91,7 @@ import { fileURLToPath } from "url";
 import _path from "path";
 
 const PROJECT_ROOT = process.env.SPECLOCK_PROJECT_ROOT || process.cwd();
-const VERSION = "4.3.1";
+const VERSION = "4.3.3";
 const AUTHOR = "Sandeep Roy";
 const START_TIME = Date.now();
 
@@ -201,7 +201,7 @@ function createSpecLockServer() {
   server.tool("speclock_add_lock", "Add a non-negotiable constraint (SpecLock).", { text: z.string().min(1).describe("The constraint text"), tags: z.array(z.string()).default([]).describe("Category tags"), source: z.enum(["user", "agent"]).default("agent").describe("Who created this lock") }, async ({ text, tags, source }) => {
     ensureInit(PROJECT_ROOT);
     const lock = addLock(PROJECT_ROOT, text, tags, source);
-    return { content: [{ type: "text", text: `Lock added [${lock.id}]: ${text}` }] };
+    return { content: [{ type: "text", text: `Lock added [${lock.lockId}]: ${text}` }] };
   });
 
   // Tool 5: speclock_remove_lock
@@ -215,7 +215,7 @@ function createSpecLockServer() {
   server.tool("speclock_add_decision", "Record an architectural or design decision.", { text: z.string().min(1).describe("The decision text"), tags: z.array(z.string()).default([]), source: z.enum(["user", "agent"]).default("agent") }, async ({ text, tags, source }) => {
     ensureInit(PROJECT_ROOT);
     const d = addDecision(PROJECT_ROOT, text, tags, source);
-    return { content: [{ type: "text", text: `Decision recorded [${d.id}]: ${text}` }] };
+    return { content: [{ type: "text", text: `Decision recorded [${d.decId}]: ${text}` }] };
   });
 
   // Tool 7: speclock_add_note
@@ -656,6 +656,110 @@ app.delete("/mcp", async (req, res) => {
   res.writeHead(405).end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32000, message: "Method not allowed." }, id: null }));
 });
 
+// ========================================
+// PUBLIC PROXY API (v4.3 — for npm-install users)
+// Allows npm-install users to get Gemini LLM coverage without
+// needing their own API key. Heuristic runs locally, grey-zone
+// cases are proxied here for LLM verification.
+// ========================================
+
+app.post("/api/check", async (req, res) => {
+  setCorsHeaders(res);
+
+  // Rate limiting
+  const clientIp = req.headers["x-forwarded-for"]?.split(",")[0]?.trim() || req.socket?.remoteAddress || "unknown";
+  if (!checkRateLimit(clientIp)) {
+    return res.status(429).json({ error: "Rate limit exceeded. Try again later." });
+  }
+
+  const { action, locks } = req.body || {};
+  if (!action || typeof action !== "string") {
+    return res.status(400).json({ error: "Missing required field: action (string)" });
+  }
+  if (!locks || !Array.isArray(locks) || locks.length === 0) {
+    return res.status(400).json({ error: "Missing required field: locks (non-empty array of strings)" });
+  }
+  if (locks.length > 50) {
+    return res.status(400).json({ error: "Too many locks (max 50)" });
+  }
+
+  try {
+    // Build lock objects for the LLM checker
+    const activeLocks = locks.map((text, i) => ({
+      id: `proxy-${i}`,
+      text: String(text),
+      active: true,
+    }));
+
+    // Run heuristic first (same as local)
+    const { analyzeConflict } = await import("../core/semantics.js");
+    const heuristicConflicts = [];
+    for (const lock of activeLocks) {
+      const result = analyzeConflict(action, lock.text);
+      if (result.isConflict) {
+        heuristicConflicts.push({
+          lockText: lock.text,
+          confidence: result.confidence,
+          level: result.level,
+          reasons: result.reasons,
+          source: "heuristic",
+        });
+      }
+    }
+
+    // If all heuristic conflicts are HIGH (>70%), return immediately
+    if (heuristicConflicts.length > 0 && heuristicConflicts.every(c => c.confidence > 70)) {
+      return res.json({
+        hasConflict: true,
+        conflicts: heuristicConflicts,
+        source: "heuristic",
+      });
+    }
+
+    // Call LLM for full coverage
+    const { llmCheckConflict } = await import("../core/llm-checker.js");
+    const llmResult = await llmCheckConflict(null, action, activeLocks);
+
+    if (llmResult) {
+      // Merge: keep HIGH heuristic + all LLM conflicts
+      const highHeuristic = heuristicConflicts.filter(c => c.confidence > 70);
+      const llmConflicts = (llmResult.conflictingLocks || []).map(c => ({
+        lockText: c.text,
+        confidence: c.confidence,
+        level: c.level,
+        reasons: c.reasons || [],
+        source: "gemini",
+      }));
+      const merged = [...highHeuristic, ...llmConflicts];
+
+      // Deduplicate by lock text
+      const byText = new Map();
+      for (const c of merged) {
+        const existing = byText.get(c.lockText);
+        if (!existing || c.confidence > existing.confidence) {
+          byText.set(c.lockText, c);
+        }
+      }
+      const unique = [...byText.values()];
+
+      return res.json({
+        hasConflict: unique.length > 0,
+        conflicts: unique,
+        source: unique.some(c => c.source === "gemini") ? "hybrid" : "heuristic",
+      });
+    }
+
+    // LLM unavailable — return heuristic result
+    return res.json({
+      hasConflict: heuristicConflicts.length > 0,
+      conflicts: heuristicConflicts,
+      source: "heuristic-only",
+    });
+  } catch (err) {
+    return res.status(500).json({ error: `Check failed: ${err.message}` });
+  }
+});
+
 // Health check endpoint (enhanced for enterprise)
 app.get("/health", (req, res) => {
   setCorsHeaders(res);

package/src/mcp/server.js

@@ -100,7 +100,7 @@ const PROJECT_ROOT =
   args.project || process.env.SPECLOCK_PROJECT_ROOT || process.cwd();
 
 // --- MCP Server ---
-const VERSION = "4.3.1";
+const VERSION = "4.3.3";
 const AUTHOR = "Sandeep Roy";
 
 const server = new McpServer(