speclock 4.5.7 → 5.0.0

package/src/mcp/server.js

@@ -43,6 +43,20 @@ import {
   isTelemetryEnabled,
   getTelemetrySummary,
   trackToolUsage,
+  addTypedLock,
+  updateTypedLockThreshold,
+  checkAllTypedConstraints,
+  CONSTRAINT_TYPES,
+  OPERATORS,
+  formatTypedLockText,
+  compileSpec,
+  compileAndApply,
+  buildGraph,
+  getOrBuildGraph,
+  getBlastRadius,
+  mapLocksToFiles,
+  getModules,
+  getCriticalPaths,
 } from "../core/engine.js";
 import { generateContext, generateContextPack } from "../core/context.js";
 import {
@@ -100,7 +114,7 @@ const PROJECT_ROOT =
   args.project || process.env.SPECLOCK_PROJECT_ROOT || process.cwd();
 
 // --- MCP Server ---
-const VERSION = "4.5.7";
+const VERSION = "5.0.0";
 const AUTHOR = "Sandeep Roy";
 
 const server = new McpServer(
@@ -1334,6 +1348,374 @@ server.tool(
   }
 );
 
+// ========================================
+// TYPED CONSTRAINTS — Autonomous Systems Governance (v5.0)
+// ========================================
+
+// Tool 32: speclock_add_typed_lock
+server.tool(
+  "speclock_add_typed_lock",
+  "Add a typed constraint lock for autonomous systems governance. Supports numerical (motor speed <= 3000 RPM), range (temperature between 20-80°C), state (forbidden transitions: EMERGENCY -> IDLE), and temporal (sensor interval <= 100ms) constraints. These are for real-time value/state checking in robotics, vehicles, trading, and medical systems.",
+  {
+    constraintType: z.enum(["numerical", "range", "state", "temporal"]).describe("Type of constraint"),
+    metric: z.string().optional().describe("Metric name (for numerical/range/temporal). E.g., 'motor_speed', 'temperature', 'sensor_interval'"),
+    operator: z.enum(["<", "<=", "==", "!=", ">=", ">"]).optional().describe("Comparison operator (for numerical/temporal)"),
+    value: z.number().optional().describe("Threshold value (for numerical/temporal)"),
+    min: z.number().optional().describe("Minimum value (for range)"),
+    max: z.number().optional().describe("Maximum value (for range)"),
+    unit: z.string().optional().describe("Unit of measurement. E.g., 'RPM', '°C', 'ms', 'km/h'"),
+    entity: z.string().optional().describe("Entity name (for state). E.g., 'robot_arm', 'vehicle', 'trading_engine'"),
+    forbidden: z.array(z.object({ from: z.string(), to: z.string() })).optional().describe("Forbidden state transitions (for state). E.g., [{ from: 'EMERGENCY', to: 'IDLE' }]"),
+    requireApproval: z.boolean().optional().describe("Whether forbidden transitions require human approval (for state)"),
+    description: z.string().optional().describe("Human-readable description (auto-generated if omitted)"),
+    tags: z.array(z.string()).optional().describe("Category tags"),
+    source: z.enum(["user", "agent"]).optional().describe("Who created this lock"),
+  },
+  async (params) => {
+    const perm = requirePermission("speclock_add_typed_lock");
+    if (!perm.allowed) return { content: [{ type: "text", text: perm.error }], isError: true };
+
+    const constraint = {
+      constraintType: params.constraintType,
+      ...(params.metric && { metric: params.metric }),
+      ...(params.operator && { operator: params.operator }),
+      ...(params.value !== undefined && { value: params.value }),
+      ...(params.min !== undefined && { min: params.min }),
+      ...(params.max !== undefined && { max: params.max }),
+      ...(params.unit && { unit: params.unit }),
+      ...(params.entity && { entity: params.entity }),
+      ...(params.forbidden && { forbidden: params.forbidden }),
+      ...(params.requireApproval !== undefined && { requireApproval: params.requireApproval }),
+    };
+
+    const result = addTypedLock(
+      PROJECT_ROOT,
+      constraint,
+      params.tags || [],
+      params.source || "user",
+      params.description
+    );
+
+    if (result.error) {
+      return { content: [{ type: "text", text: `Validation error: ${result.error}` }], isError: true };
+    }
+
+    return {
+      content: [{
+        type: "text",
+        text: `Typed lock added (${params.constraintType}):\nID: ${result.lockId}\nDescription: ${result.brain.specLock.items[0].text}\n\nThis constraint will be checked against real-time values using speclock_check_typed.`,
+      }],
+    };
+  }
+);
+
+// Tool 33: speclock_check_typed
+server.tool(
+  "speclock_check_typed",
+  "Check a proposed value or state transition against typed constraints. For numerical/range/temporal: provide metric and value. For state: provide entity, from, and to. Returns CONFLICT if the proposed value violates any typed lock.",
+  {
+    metric: z.string().optional().describe("Metric to check (matches typed locks by metric name)"),
+    entity: z.string().optional().describe("Entity to check (matches state locks by entity name)"),
+    value: z.number().optional().describe("Proposed value (for numerical/range/temporal checks)"),
+    from: z.string().optional().describe("Current state (for state transition checks)"),
+    to: z.string().optional().describe("Target state (for state transition checks)"),
+  },
+  async (params) => {
+    const perm = requirePermission("speclock_check_typed");
+    if (!perm.allowed) return { content: [{ type: "text", text: perm.error }], isError: true };
+
+    const brain = ensureInit(PROJECT_ROOT);
+    const allLocks = brain.specLock?.items || [];
+
+    const proposed = {
+      ...(params.metric && { metric: params.metric }),
+      ...(params.entity && { entity: params.entity }),
+      ...(params.value !== undefined && { value: params.value }),
+      ...(params.from && { from: params.from }),
+      ...(params.to && { to: params.to }),
+    };
+
+    const result = checkAllTypedConstraints(allLocks, proposed);
+
+    if (result.hasConflict) {
+      // Check enforcement mode
+      const enforcement = getEnforcementConfig(PROJECT_ROOT);
+      const isHardMode = enforcement.mode === "hard";
+      const topConfidence = result.conflictingLocks[0]?.confidence || 0;
+
+      const text = [
+        `CONSTRAINT VIOLATION DETECTED`,
+        ``,
+        result.analysis,
+        ``,
+        isHardMode && topConfidence >= enforcement.blockThreshold
+          ? `BLOCKED — Hard enforcement mode active. This action cannot proceed.`
+          : `Advisory — Review these violations before proceeding.`,
+      ].join("\n");
+
+      return {
+        content: [{ type: "text", text }],
+        isError: isHardMode && topConfidence >= enforcement.blockThreshold,
+      };
+    }
+
+    return {
+      content: [{ type: "text", text: result.analysis }],
+    };
+  }
+);
+
+// Tool 34: speclock_list_typed_locks
+server.tool(
+  "speclock_list_typed_locks",
+  "List all typed constraints (numerical, range, state, temporal) with their current thresholds and parameters. Shows constraints used for autonomous systems governance.",
+  {},
+  async () => {
+    const perm = requirePermission("speclock_list_typed_locks");
+    if (!perm.allowed) return { content: [{ type: "text", text: perm.error }], isError: true };
+
+    const brain = ensureInit(PROJECT_ROOT);
+    const allLocks = brain.specLock?.items || [];
+    const typedLocks = allLocks.filter(l => l.active !== false && l.constraintType);
+
+    if (typedLocks.length === 0) {
+      return {
+        content: [{
+          type: "text",
+          text: `No typed constraints found. Use speclock_add_typed_lock to add numerical, range, state, or temporal constraints.\n\nTotal text locks: ${allLocks.filter(l => l.active !== false && !l.constraintType).length}`,
+        }],
+      };
+    }
+
+    const sections = {
+      numerical: [],
+      range: [],
+      state: [],
+      temporal: [],
+    };
+
+    for (const lock of typedLocks) {
+      sections[lock.constraintType]?.push(lock);
+    }
+
+    const parts = [`## Typed Constraints (${typedLocks.length} total)`, ``];
+
+    for (const [type, locks] of Object.entries(sections)) {
+      if (locks.length === 0) continue;
+      parts.push(`### ${type.charAt(0).toUpperCase() + type.slice(1)} (${locks.length})`);
+      for (const l of locks) {
+        parts.push(`- **${l.id}**: ${l.text}`);
+        if (l.metric) parts.push(`  Metric: ${l.metric}`);
+        if (l.entity) parts.push(`  Entity: ${l.entity}`);
+        if (l.unit) parts.push(`  Unit: ${l.unit}`);
+        if (l.tags?.length) parts.push(`  Tags: ${l.tags.join(", ")}`);
+      }
+      parts.push(``);
+    }
+
+    const textLockCount = allLocks.filter(l => l.active !== false && !l.constraintType).length;
+    parts.push(`---`, `Text locks (semantic): ${textLockCount}`);
+
+    return { content: [{ type: "text", text: parts.join("\n") }] };
+  }
+);
+
+// Tool 35: speclock_update_threshold
+server.tool(
+  "speclock_update_threshold",
+  "Update a typed lock's threshold value. For numerical/temporal: update value and/or operator. For range: update min and/or max. Changes are recorded in the audit trail.",
+  {
+    lockId: z.string().describe("The lock ID to update"),
+    value: z.number().optional().describe("New threshold value (for numerical/temporal)"),
+    operator: z.enum(["<", "<=", "==", "!=", ">=", ">"]).optional().describe("New operator (for numerical/temporal)"),
+    min: z.number().optional().describe("New minimum (for range)"),
+    max: z.number().optional().describe("New maximum (for range)"),
+    forbidden: z.array(z.object({ from: z.string(), to: z.string() })).optional().describe("New forbidden transitions (for state)"),
+  },
+  async (params) => {
+    const perm = requirePermission("speclock_update_threshold");
+    if (!perm.allowed) return { content: [{ type: "text", text: perm.error }], isError: true };
+
+    const updates = {};
+    if (params.value !== undefined) updates.value = params.value;
+    if (params.operator) updates.operator = params.operator;
+    if (params.min !== undefined) updates.min = params.min;
+    if (params.max !== undefined) updates.max = params.max;
+    if (params.forbidden) updates.forbidden = params.forbidden;
+
+    const result = updateTypedLockThreshold(PROJECT_ROOT, params.lockId, updates);
+
+    if (result.error) {
+      return { content: [{ type: "text", text: `Error: ${result.error}` }], isError: true };
+    }
+
+    return {
+      content: [{
+        type: "text",
+        text: `Threshold updated for ${params.lockId}:\nOld: ${JSON.stringify(result.oldValues)}\nNew: ${JSON.stringify(result.newValues)}\nUpdated description: ${result.brain.specLock.items.find(l => l.id === params.lockId)?.text}`,
+      }],
+    };
+  }
+);
+
+// --- Spec Compiler (v5.0) ---
+
+server.tool(
+  "speclock_compile_spec",
+  "Compile natural language text (PRDs, READMEs, architecture docs, chat logs) into structured SpecLock constraints. Extracts text locks, typed locks (numerical/range/state/temporal), decisions, and notes. Set autoApply=true to automatically add extracted items to brain.json.",
+  {
+    text: z.string().describe("Natural language text to compile into constraints"),
+    autoApply: z.boolean().optional().default(false).describe("If true, automatically apply extracted constraints to brain.json"),
+  },
+  async ({ text, autoApply }) => {
+    const perm = requirePermission("speclock_compile_spec");
+    if (!perm.allowed) return { content: [{ type: "text", text: perm.error }], isError: true };
+
+    const result = autoApply
+      ? await compileAndApply(PROJECT_ROOT, text)
+      : await compileSpec(PROJECT_ROOT, text);
+
+    if (!result.success) {
+      return { content: [{ type: "text", text: `Compilation failed: ${result.error}` }], isError: true };
+    }
+
+    const lines = [
+      `Spec Compiler Results:`,
+      `  Text Locks: ${result.locks.length}`,
+      `  Typed Locks: ${result.typedLocks.length}`,
+      `  Decisions: ${result.decisions.length}`,
+      `  Notes: ${result.notes.length}`,
+    ];
+
+    if (result.locks.length > 0) {
+      lines.push(`\nExtracted Locks:`);
+      result.locks.forEach((l, i) => lines.push(`  ${i + 1}. ${l.text} [${(l.tags || []).join(", ")}]`));
+    }
+    if (result.typedLocks.length > 0) {
+      lines.push(`\nExtracted Typed Locks:`);
+      result.typedLocks.forEach((tl, i) => lines.push(`  ${i + 1}. [${tl.constraintType}] ${tl.description || tl.metric}`));
+    }
+    if (result.decisions.length > 0) {
+      lines.push(`\nExtracted Decisions:`);
+      result.decisions.forEach((d, i) => lines.push(`  ${i + 1}. ${d.text}`));
+    }
+    if (result.notes.length > 0) {
+      lines.push(`\nExtracted Notes:`);
+      result.notes.forEach((n, i) => lines.push(`  ${i + 1}. ${n.text}`));
+    }
+
+    if (autoApply && result.applied) {
+      lines.push(`\nApplied to brain.json: ${result.totalApplied} items (${result.applied.locks} locks, ${result.applied.typedLocks} typed, ${result.applied.decisions} decisions, ${result.applied.notes} notes)`);
+    }
+
+    if (result.summary) lines.push(`\nSummary: ${result.summary}`);
+
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+  }
+);
+
+// --- Code Graph (v5.0) ---
+
+server.tool(
+  "speclock_build_graph",
+  "Build or refresh the code dependency graph. Scans JS/TS/Python source files, parses imports, and builds an adjacency graph. The graph is cached in .speclock/code-graph.json and auto-rebuilds when stale (>1 hour).",
+  {},
+  async () => {
+    const perm = requirePermission("speclock_build_graph");
+    if (!perm.allowed) return { content: [{ type: "text", text: perm.error }], isError: true };
+
+    const graph = buildGraph(PROJECT_ROOT, { force: true });
+
+    const lines = [
+      `Code Graph Built:`,
+      `  Total Files: ${graph.stats.totalFiles}`,
+      `  Total Edges: ${graph.stats.totalEdges}`,
+      `  Entry Points: ${graph.stats.entryPoints.length}`,
+      `  Languages: ${Object.entries(graph.stats.languages).map(([k, v]) => `${k}(${v})`).join(", ")}`,
+    ];
+
+    if (graph.stats.entryPoints.length > 0) {
+      lines.push(`\nEntry Points:`);
+      graph.stats.entryPoints.slice(0, 10).forEach(ep => lines.push(`  - ${ep}`));
+    }
+
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+  }
+);
+
+server.tool(
+  "speclock_blast_radius",
+  "Calculate the blast radius of changing a specific file. Shows direct and transitive dependents, depth, and impact percentage. Useful for understanding the risk of modifying a file.",
+  {
+    file: z.string().describe("Relative file path to analyze (e.g., 'src/core/memory.js')"),
+  },
+  async ({ file }) => {
+    const perm = requirePermission("speclock_blast_radius");
+    if (!perm.allowed) return { content: [{ type: "text", text: perm.error }], isError: true };
+
+    const result = getBlastRadius(PROJECT_ROOT, file);
+
+    if (!result.found) {
+      return { content: [{ type: "text", text: `File not found in graph: ${file}\nTry running speclock_build_graph first.` }], isError: true };
+    }
+
+    const lines = [
+      `Blast Radius for ${file}:`,
+      `  Direct Dependents: ${result.directDependents.length}`,
+      `  Transitive Dependents: ${result.transitiveDependents.length}`,
+      `  Max Depth: ${result.depth}`,
+      `  Impact: ${result.impactPercent}% (${result.blastRadius}/${result.totalFiles} files)`,
+    ];
+
+    if (result.directDependents.length > 0) {
+      lines.push(`\nDirect Dependents:`);
+      result.directDependents.forEach(f => lines.push(`  - ${f}`));
+    }
+
+    if (result.transitiveDependents.length > result.directDependents.length) {
+      lines.push(`\nAll Affected Files:`);
+      result.transitiveDependents.forEach(f => lines.push(`  - ${f}`));
+    }
+
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+  }
+);
+
+server.tool(
+  "speclock_map_locks",
+  "Map all active locks to actual code files using the dependency graph. Shows which files each lock protects and the combined blast radius. Helps understand the structural impact of constraints.",
+  {},
+  async () => {
+    const perm = requirePermission("speclock_map_locks");
+    if (!perm.allowed) return { content: [{ type: "text", text: perm.error }], isError: true };
+
+    const mappings = mapLocksToFiles(PROJECT_ROOT);
+
+    if (mappings.length === 0) {
+      return { content: [{ type: "text", text: "No active locks to map. Add locks first." }] };
+    }
+
+    const lines = [`Lock-to-File Mappings (${mappings.length} locks):\n`];
+
+    for (const m of mappings) {
+      lines.push(`Lock: "${m.lockText}"`);
+      lines.push(`  ID: ${m.lockId}`);
+      lines.push(`  Matched Files: ${m.matchedFiles.length}`);
+      if (m.matchedFiles.length > 0) {
+        m.matchedFiles.slice(0, 10).forEach(f => lines.push(`    - ${f}`));
+        if (m.matchedFiles.length > 10) lines.push(`    ... and ${m.matchedFiles.length - 10} more`);
+      }
+      if (m.matchedModules.length > 0) {
+        lines.push(`  Modules: ${m.matchedModules.join(", ")}`);
+      }
+      lines.push(`  Blast Radius: ${m.blastRadius} files`);
+      lines.push("");
+    }
+
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+  }
+);
+
 // --- Smithery sandbox export ---
 export default function createSandboxServer() {
   return server;