speclock 4.5.6 → 5.0.0

package/src/core/llm-checker.js

@@ -8,6 +8,7 @@
 // ===================================================================
 
 import { readBrain } from "./storage.js";
+import { getConfig, callLLM } from "./llm-provider.js";
 
 // --- In-memory LRU cache ---
 const CACHE_MAX = 200;
@@ -37,44 +38,6 @@ function cacheSet(key, value) {
   cache.set(key, { value, ts: Date.now() });
 }
 
-// --- Configuration ---
-
-function getConfig(root) {
-  // Priority: explicit SPECLOCK key > provider-specific keys > brain.json
-  const apiKey =
-    process.env.SPECLOCK_LLM_KEY ||
-    process.env.GEMINI_API_KEY ||
-    process.env.GOOGLE_API_KEY ||
-    process.env.OPENAI_API_KEY ||
-    process.env.ANTHROPIC_API_KEY;
-
-  // Auto-detect provider from which env var is set
-  const provider =
-    process.env.SPECLOCK_LLM_PROVIDER ||
-    (process.env.SPECLOCK_LLM_KEY ? "gemini" : null) ||
-    (process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY ? "gemini" : null) ||
-    (process.env.OPENAI_API_KEY ? "openai" : null) ||
-    (process.env.ANTHROPIC_API_KEY ? "anthropic" : null) ||
-    "gemini"; // default to gemini (cheapest, free tier)
-
-  if (apiKey) {
-    return { apiKey, provider };
-  }
-
-  // Check brain.json for LLM config
-  try {
-    const brain = readBrain(root);
-    if (brain?.facts?.llm) {
-      return {
-        apiKey: brain.facts.llm.apiKey,
-        provider: brain.facts.llm.provider || "gemini",
-      };
-    }
-  } catch (_) {}
-
-  return null;
-}
-
 // --- System prompt ---
 
 const SYSTEM_PROMPT = `You are a security constraint checker for SpecLock, an AI constraint engine.
@@ -104,111 +67,6 @@ Respond with ONLY valid JSON (no markdown, no explanation):
   "analysis": "one-line summary"
 }`;
 
-// --- API callers ---
-
-async function callOpenAI(apiKey, userPrompt) {
-  const resp = await fetch("https://api.openai.com/v1/chat/completions", {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      "Authorization": `Bearer ${apiKey}`,
-    },
-    body: JSON.stringify({
-      model: "gpt-4o-mini",
-      messages: [
-        { role: "system", content: SYSTEM_PROMPT },
-        { role: "user", content: userPrompt },
-      ],
-      temperature: 0.1,
-      max_tokens: 1000,
-    }),
-  });
-
-  if (!resp.ok) return null;
-  const data = await resp.json();
-  const content = data.choices?.[0]?.message?.content;
-  if (!content) return null;
-
-  try {
-    return JSON.parse(content);
-  } catch (_) {
-    // Try to extract JSON from markdown code block
-    const match = content.match(/```(?:json)?\s*([\s\S]*?)```/);
-    if (match) return JSON.parse(match[1]);
-    return null;
-  }
-}
-
-async function callAnthropic(apiKey, userPrompt) {
-  const resp = await fetch("https://api.anthropic.com/v1/messages", {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      "x-api-key": apiKey,
-      "anthropic-version": "2023-06-01",
-    },
-    body: JSON.stringify({
-      model: "claude-sonnet-4-20250514",
-      max_tokens: 1000,
-      system: SYSTEM_PROMPT,
-      messages: [
-        { role: "user", content: userPrompt },
-      ],
-    }),
-  });
-
-  if (!resp.ok) return null;
-  const data = await resp.json();
-  const content = data.content?.[0]?.text;
-  if (!content) return null;
-
-  try {
-    return JSON.parse(content);
-  } catch (_) {
-    const match = content.match(/```(?:json)?\s*([\s\S]*?)```/);
-    if (match) return JSON.parse(match[1]);
-    return null;
-  }
-}
-
-async function callGemini(apiKey, userPrompt) {
-  const resp = await fetch(
-    `https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key=${apiKey}`,
-    {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        contents: [
-          {
-            parts: [
-              { text: SYSTEM_PROMPT + "\n\n" + userPrompt },
-            ],
-          },
-        ],
-        generationConfig: {
-          temperature: 0.1,
-          maxOutputTokens: 1000,
-        },
-      }),
-      signal: AbortSignal.timeout(3000), // 3s timeout for Gemini calls
-    }
-  );
-
-  if (!resp.ok) return null;
-  const data = await resp.json();
-  const content = data.candidates?.[0]?.content?.parts?.[0]?.text;
-  if (!content) return null;
-
-  try {
-    return JSON.parse(content);
-  } catch (_) {
-    // Try to extract JSON from markdown code block
-    const match = content.match(/```(?:json)?\s*([\s\S]*?)```/);
-    if (match) return JSON.parse(match[1]);
-    return null;
-  }
-}
-
 // --- Main export ---
 
 /**
@@ -249,19 +107,8 @@ export async function llmCheckConflict(root, proposedAction, activeLocks) {
   const lockList = activeLocks.map((l, i) => `${i + 1}. "${l.text}"`).join("\n");
   const userPrompt = `Active SpecLocks:\n${lockList}\n\nProposed Action: "${proposedAction}"\n\nDoes this action conflict with any lock?`;
 
-  // Call LLM
-  let llmResult = null;
-  try {
-    if (config.provider === "gemini") {
-      llmResult = await callGemini(config.apiKey, userPrompt);
-    } else if (config.provider === "anthropic") {
-      llmResult = await callAnthropic(config.apiKey, userPrompt);
-    } else {
-      llmResult = await callOpenAI(config.apiKey, userPrompt);
-    }
-  } catch (_) {
-    return null;
-  }
+  // Call LLM via shared provider
+  const llmResult = await callLLM(root, SYSTEM_PROMPT, userPrompt, { timeout: 3000 });
 
   if (!llmResult) return null;
 

package/src/core/llm-provider.js

@@ -0,0 +1,208 @@
+// ===================================================================
+// SpecLock LLM Provider — Shared LLM Calling Utilities
+// Supports Gemini, OpenAI, and Anthropic APIs.
+// Zero mandatory dependencies — uses built-in fetch().
+// Falls back gracefully if no API key is configured.
+//
+// Developed by Sandeep Roy (https://github.com/sgroy10)
+// ===================================================================
+
+import { readBrain } from "./storage.js";
+
+// --- Configuration ---
+
+/**
+ * Get LLM configuration (API key + provider).
+ * Priority: explicit SPECLOCK key > provider-specific env vars > brain.json
+ * @param {string} root - Project root path
+ * @returns {{ apiKey: string, provider: string } | null}
+ */
+export function getConfig(root) {
+  const apiKey =
+    process.env.SPECLOCK_LLM_KEY ||
+    process.env.GEMINI_API_KEY ||
+    process.env.GOOGLE_API_KEY ||
+    process.env.OPENAI_API_KEY ||
+    process.env.ANTHROPIC_API_KEY;
+
+  const provider =
+    process.env.SPECLOCK_LLM_PROVIDER ||
+    (process.env.SPECLOCK_LLM_KEY ? "gemini" : null) ||
+    (process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY ? "gemini" : null) ||
+    (process.env.OPENAI_API_KEY ? "openai" : null) ||
+    (process.env.ANTHROPIC_API_KEY ? "anthropic" : null) ||
+    "gemini";
+
+  if (apiKey) {
+    return { apiKey, provider };
+  }
+
+  // Check brain.json for LLM config
+  try {
+    const brain = readBrain(root);
+    if (brain?.facts?.llm) {
+      return {
+        apiKey: brain.facts.llm.apiKey,
+        provider: brain.facts.llm.provider || "gemini",
+      };
+    }
+  } catch (_) {}
+
+  return null;
+}
+
+// --- API callers ---
+
+/**
+ * Call OpenAI API.
+ * @param {string} apiKey
+ * @param {string} systemPrompt
+ * @param {string} userPrompt
+ * @param {{ timeout?: number, maxTokens?: number }} options
+ * @returns {Promise<Object|null>}
+ */
+export async function callOpenAI(apiKey, systemPrompt, userPrompt, options = {}) {
+  const { timeout = 5000, maxTokens = 1000 } = options;
+  const resp = await fetch("https://api.openai.com/v1/chat/completions", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "Authorization": `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify({
+      model: "gpt-4o-mini",
+      messages: [
+        { role: "system", content: systemPrompt },
+        { role: "user", content: userPrompt },
+      ],
+      temperature: 0.1,
+      max_tokens: maxTokens,
+    }),
+    signal: AbortSignal.timeout(timeout),
+  });
+
+  if (!resp.ok) return null;
+  const data = await resp.json();
+  const content = data.choices?.[0]?.message?.content;
+  return parseJsonResponse(content);
+}
+
+/**
+ * Call Anthropic API.
+ * @param {string} apiKey
+ * @param {string} systemPrompt
+ * @param {string} userPrompt
+ * @param {{ timeout?: number, maxTokens?: number }} options
+ * @returns {Promise<Object|null>}
+ */
+export async function callAnthropic(apiKey, systemPrompt, userPrompt, options = {}) {
+  const { timeout = 5000, maxTokens = 1000 } = options;
+  const resp = await fetch("https://api.anthropic.com/v1/messages", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-api-key": apiKey,
+      "anthropic-version": "2023-06-01",
+    },
+    body: JSON.stringify({
+      model: "claude-sonnet-4-20250514",
+      max_tokens: maxTokens,
+      system: systemPrompt,
+      messages: [
+        { role: "user", content: userPrompt },
+      ],
+    }),
+    signal: AbortSignal.timeout(timeout),
+  });
+
+  if (!resp.ok) return null;
+  const data = await resp.json();
+  const content = data.content?.[0]?.text;
+  return parseJsonResponse(content);
+}
+
+/**
+ * Call Gemini API.
+ * @param {string} apiKey
+ * @param {string} systemPrompt
+ * @param {string} userPrompt
+ * @param {{ timeout?: number, maxTokens?: number }} options
+ * @returns {Promise<Object|null>}
+ */
+export async function callGemini(apiKey, systemPrompt, userPrompt, options = {}) {
+  const { timeout = 3000, maxTokens = 1000 } = options;
+  const resp = await fetch(
+    `https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key=${apiKey}`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        contents: [
+          {
+            parts: [
+              { text: systemPrompt + "\n\n" + userPrompt },
+            ],
+          },
+        ],
+        generationConfig: {
+          temperature: 0.1,
+          maxOutputTokens: maxTokens,
+        },
+      }),
+      signal: AbortSignal.timeout(timeout),
+    }
+  );
+
+  if (!resp.ok) return null;
+  const data = await resp.json();
+  const content = data.candidates?.[0]?.content?.parts?.[0]?.text;
+  return parseJsonResponse(content);
+}
+
+/**
+ * Call the configured LLM provider.
+ * @param {string} root - Project root (for config lookup)
+ * @param {string} systemPrompt
+ * @param {string} userPrompt
+ * @param {{ timeout?: number, maxTokens?: number }} options
+ * @returns {Promise<Object|null>}
+ */
+export async function callLLM(root, systemPrompt, userPrompt, options = {}) {
+  const config = getConfig(root);
+  if (!config) return null;
+
+  try {
+    if (config.provider === "gemini") {
+      return await callGemini(config.apiKey, systemPrompt, userPrompt, options);
+    } else if (config.provider === "anthropic") {
+      return await callAnthropic(config.apiKey, systemPrompt, userPrompt, options);
+    } else {
+      return await callOpenAI(config.apiKey, systemPrompt, userPrompt, options);
+    }
+  } catch (_) {
+    return null;
+  }
+}
+
+// --- JSON response parser ---
+
+/**
+ * Parse a JSON response from an LLM, handling markdown code blocks.
+ * @param {string} content - Raw LLM response text
+ * @returns {Object|null}
+ */
+export function parseJsonResponse(content) {
+  if (!content) return null;
+  try {
+    return JSON.parse(content);
+  } catch (_) {
+    // Try to extract JSON from markdown code block
+    const match = content.match(/```(?:json)?\s*([\s\S]*?)```/);
+    if (match) {
+      try {
+        return JSON.parse(match[1]);
+      } catch (_) {}
+    }
+    return null;
+  }
+}

package/src/core/memory.js

@@ -22,6 +22,7 @@ import {
 import { hasGit, getHead, getDefaultBranch } from "./git.js";
 import { ensureAuditKeyGitignored } from "./audit.js";
 import { normalizeLock } from "./lock-author.js";
+import { validateTypedLock, formatTypedLockText } from "./typed-constraints.js";
 
 // --- Internal helpers ---
 
@@ -173,6 +174,120 @@ export function addNote(root, text, pinned = true) {
   return { brain, noteId };
 }
 
+/**
+ * Add a typed constraint lock (numerical, range, state, temporal).
+ * These are for autonomous systems governance — real-time value/state checking.
+ * Existing text locks use addLock() and are unaffected.
+ *
+ * @param {string} root - Project root
+ * @param {Object} constraint - Typed constraint definition:
+ *   { constraintType, metric?, operator?, value?, min?, max?, entity?, forbidden?, unit?, requireApproval? }
+ * @param {string[]} tags - Category tags
+ * @param {string} source - "user" or "agent"
+ * @param {string} description - Human-readable description (optional, auto-generated if missing)
+ */
+export function addTypedLock(root, constraint, tags, source, description) {
+  const validation = validateTypedLock(constraint);
+  if (!validation.valid) {
+    return { brain: null, lockId: null, error: validation.error };
+  }
+
+  const brain = ensureInit(root);
+  const lockId = newId("lock");
+  const text = description || formatTypedLockText(constraint);
+
+  brain.specLock.items.unshift({
+    id: lockId,
+    text,
+    constraintType: constraint.constraintType,
+    // Type-specific fields
+    ...(constraint.metric && { metric: constraint.metric }),
+    ...(constraint.operator && { operator: constraint.operator }),
+    ...(constraint.value !== undefined && { value: constraint.value }),
+    ...(constraint.min !== undefined && { min: constraint.min }),
+    ...(constraint.max !== undefined && { max: constraint.max }),
+    ...(constraint.unit && { unit: constraint.unit }),
+    ...(constraint.entity && { entity: constraint.entity }),
+    ...(constraint.forbidden && { forbidden: constraint.forbidden }),
+    ...(constraint.requireApproval !== undefined && { requireApproval: constraint.requireApproval }),
+    createdAt: nowIso(),
+    source: source || "user",
+    tags: tags || [],
+    active: true,
+  });
+
+  const eventId = newId("evt");
+  const event = {
+    eventId,
+    type: "lock_added",
+    at: nowIso(),
+    files: [],
+    summary: `Typed lock added (${constraint.constraintType}): ${text.substring(0, 80)}`,
+    patchPath: "",
+  };
+  recordEvent(root, brain, event);
+  return { brain, lockId, constraintType: constraint.constraintType };
+}
+
+/**
+ * Update a typed lock's threshold value (for numerical/range/temporal).
+ * Records the change in audit trail.
+ */
+export function updateTypedLockThreshold(root, lockId, updates) {
+  const brain = ensureInit(root);
+  const lock = brain.specLock.items.find((l) => l.id === lockId);
+
+  if (!lock) {
+    return { brain: null, error: `Lock not found: ${lockId}` };
+  }
+  if (!lock.constraintType) {
+    return { brain: null, error: `Lock ${lockId} is a text lock, not a typed constraint` };
+  }
+
+  const oldValues = {};
+
+  // Update allowed fields based on constraint type
+  if (lock.constraintType === "numerical" || lock.constraintType === "temporal") {
+    if (updates.value !== undefined) {
+      oldValues.value = lock.value;
+      lock.value = updates.value;
+    }
+    if (updates.operator) {
+      oldValues.operator = lock.operator;
+      lock.operator = updates.operator;
+    }
+  } else if (lock.constraintType === "range") {
+    if (updates.min !== undefined) {
+      oldValues.min = lock.min;
+      lock.min = updates.min;
+    }
+    if (updates.max !== undefined) {
+      oldValues.max = lock.max;
+      lock.max = updates.max;
+    }
+  } else if (lock.constraintType === "state") {
+    if (updates.forbidden) {
+      oldValues.forbidden = lock.forbidden;
+      lock.forbidden = updates.forbidden;
+    }
+  }
+
+  // Regenerate text description
+  lock.text = formatTypedLockText(lock);
+
+  const eventId = newId("evt");
+  const event = {
+    eventId,
+    type: "lock_updated",
+    at: nowIso(),
+    files: [],
+    summary: `Typed lock ${lockId} threshold updated: ${JSON.stringify(oldValues)} -> ${JSON.stringify(updates)}`,
+    patchPath: "",
+  };
+  recordEvent(root, brain, event);
+  return { brain, lockId, oldValues, newValues: updates };
+}
+
 export function updateDeployFacts(root, payload) {
   const brain = ensureInit(root);
   const deploy = brain.facts.deploy;