speclock 4.5.6 → 5.0.0

package/README.md

@@ -8,13 +8,15 @@
   <a href="https://www.npmjs.com/package/speclock"><img src="https://img.shields.io/npm/v/speclock.svg?style=flat-square&color=4F46E5" alt="npm version" /></a>
   <a href="https://www.npmjs.com/package/speclock"><img src="https://img.shields.io/npm/dm/speclock.svg?style=flat-square&color=22C55E" alt="npm downloads" /></a>
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="MIT License" /></a>
-  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-31_tools-green.svg?style=flat-square" alt="MCP 31 tools" /></a>
+  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-39_tools-green.svg?style=flat-square" alt="MCP 39 tools" /></a>
 </p>
 
 <p align="center">
   <a href="https://sgroy10.github.io/speclock/">Website</a> · <a href="https://www.npmjs.com/package/speclock">npm</a> · <a href="https://smithery.ai/servers/sgroy10/speclock">Smithery</a> · <a href="https://github.com/sgroy10/speclock">GitHub</a>
 </p>
 
+<p align="center"><strong>Developed by <a href="https://github.com/sgroy10">Sandeep Roy</a></strong> · Free &amp; Open Source (MIT License)</p>
+
 ---
 
 ```
@@ -30,7 +32,7 @@ AI:     ⚠️  BLOCKED — violates lock "Never touch the auth system"
         Should I find another approach?
 ```
 
-**60 test suites. 100% detection. 0% false positives. Gemini Flash hybrid for universal domain coverage.**
+**940 tests. 99.4% pass rate. 0 false positives across 13 suites. Gemini Flash hybrid, Spec Compiler, Code Graph, Typed Constraints, Python SDK, ROS2 integration.**
 
 ---
 
@@ -109,7 +111,7 @@ Same config — add to `.cursor/mcp.json` or equivalent.
 |---|:---:|:---:|:---:|:---:|
 | Remembers context | Yes | Yes | Manual | **Yes** |
 | **Blocks the AI from breaking things** | No | No | No | **Yes** |
-| **Semantic conflict detection** | No | No | No | **100% detection, 0% FP** |
+| **Semantic conflict detection** | No | No | No | **98% detection, 0% FP** |
 | **Tamper-proof audit trail** | No | No | No | **HMAC-SHA256 chain** |
 | **Hard enforcement (AI cannot proceed)** | No | No | No | **Yes** |
 | **SOC 2 / HIPAA compliance exports** | No | No | No | **Yes** |
@@ -134,7 +136,7 @@ Not keyword matching — **real semantic analysis** with Gemini Flash hybrid for
 <tr><td>Dilution attacks</td><td>100%</td><td>Violation buried in multi-part request</td></tr>
 <tr><td>Compound sentences</td><td>100%</td><td>"Update UI and also drop users table"</td></tr>
 <tr><td>Synonym substitution</td><td>100%</td><td>"Sunset the API" = remove the API</td></tr>
-<tr><td>Payment brand names</td><td>100%</td><td>"Add Razorpay" vs "Never change payment gateway"</td></tr>
+<tr><td>Payment brand names (11 gateways)</td><td>100%</td><td>"Add Razorpay" / "Implement PayU" vs "Must use Stripe"</td></tr>
 <tr><td>Salary/payroll cross-vocab</td><td>100%</td><td>"Optimize salary" vs "Payroll records locked"</td></tr>
 <tr><td>Safety system bypass</td><td>100%</td><td>"Disable safety interlock" = bypass safety</td></tr>
 <tr><td>Unknown domains (via Gemini)</td><td>100%</td><td>Gaming, biotech, aerospace, music, legal</td></tr>
@@ -235,7 +237,109 @@ Import and export policies between projects. Share constraint templates across y
 
 ---
 
-## 31 MCP Tools
+## Spec Compiler (v5.0)
+
+Paste a PRD, README, or architecture doc — SpecLock extracts all constraints automatically:
+
+```
+Input:  "We're building a fintech app. Use React and FastAPI.
+         Never touch the auth module. Response time must stay
+         under 200ms. Payments go through Stripe."
+
+Output: 2 text locks:
+          - "Never touch the auth module"
+          - "Payments go through Stripe — don't change provider"
+        1 typed lock:
+          - response_time_ms <= 200 (numerical)
+        2 decisions:
+          - "Use React for frontend"
+          - "Use FastAPI for backend"
+```
+
+Uses Gemini Flash by default ($0.01 per 1000 compilations). No API key needed for core SpecLock — only the compiler uses LLM. Falls back gracefully if no key is set.
+
+---
+
+## Code Graph (v5.0)
+
+Live dependency graph of your codebase. Parses JS/TS/Python imports.
+
+```
+$ speclock blast-radius src/core/memory.js
+
+Direct Dependents:  8 files
+Transitive Impact:  14 files (33% of codebase)
+Max Depth:          4 hops
+```
+
+**Lock-to-file mapping:** Lock "Never modify auth" → automatically maps to `src/api/auth.js`, `src/middleware/auth.js`, `src/utils/jwt.js`. No configuration needed.
+
+**Module detection:** Groups files into logical modules, tracks inter-module dependencies, identifies critical paths.
+
+---
+
+## Typed Constraints (v5.0)
+
+Real-time value and state checking for autonomous systems, IoT, robotics:
+
+```javascript
+// Numerical: speed must be <= 2.0 m/s
+{ constraintType: "numerical", metric: "speed_mps", operator: "<=", value: 2.0 }
+
+// Range: temperature must stay between 20-25°C
+{ constraintType: "range", metric: "temperature_c", min: 20, max: 25 }
+
+// State: never go from armed → disarmed without approval
+{ constraintType: "state", metric: "system_mode", forbidden: [{ from: "armed", to: "disarmed" }] }
+
+// Temporal: heartbeat must occur every 30 seconds
+{ constraintType: "temporal", metric: "heartbeat_s", operator: "<=", value: 30 }
+```
+
+---
+
+## Python SDK & ROS2 (v5.0)
+
+```bash
+pip install speclock-sdk
+```
+
+```python
+from speclock import ConstraintChecker
+checker = ConstraintChecker(constraints)
+result = checker.check({"metric": "speed_mps", "value": 3.5})
+# → violation: speed exceeds 2.0 m/s limit
+```
+
+**ROS2 Guardian Node:** Real-time constraint enforcement for robots. Subscribes to sensor topics, checks constraints at configurable rate, publishes violations, triggers emergency stop.
+
+---
+
+## REST API v2 (v5.0)
+
+Real-time constraint checking for autonomous systems:
+
+```bash
+# Single check
+POST /api/v2/check-typed    { metric, value, entity }
+
+# Batch check (up to 100)
+POST /api/v2/check-batch    { checks: [...] }
+
+# SSE streaming (real-time violations)
+GET  /api/v2/stream
+
+# Spec Compiler
+POST /api/v2/compiler/compile  { text, autoApply }
+
+# Code Graph
+GET  /api/v2/graph/blast-radius?file=src/core/memory.js
+GET  /api/v2/graph/lock-map
+```
+
+---
+
+## 39 MCP Tools
 
 <details>
 <summary><b>Memory</b> — goal, locks, decisions, notes, deploy facts</summary>
@@ -308,6 +412,30 @@ Import and export policies between projects. Share constraint templates across y
 
 </details>
 
+<details>
+<summary><b>Typed Constraints</b> — numerical, range, state, temporal (v5.0)</summary>
+
+| Tool | What it does |
+|------|-------------|
+| `speclock_add_typed_lock` | Add typed constraint (numerical/range/state/temporal) |
+| `speclock_check_typed` | Check proposed values against typed constraints |
+| `speclock_list_typed_locks` | List all typed constraints |
+| `speclock_update_threshold` | Update typed lock thresholds |
+
+</details>
+
+<details>
+<summary><b>Spec Compiler & Code Graph</b> — NL→constraints, dependency analysis (v5.0)</summary>
+
+| Tool | What it does |
+|------|-------------|
+| `speclock_compile_spec` | Compile natural language into structured constraints |
+| `speclock_build_graph` | Build/refresh code dependency graph |
+| `speclock_blast_radius` | Calculate blast radius of file changes |
+| `speclock_map_locks` | Map locks to actual code files |
+
+</details>
+
 ---
 
 ## CLI
@@ -380,13 +508,13 @@ The AI opens the file and sees:
 │     AI Tool (Claude Code, Cursor, Bolt.new...)    │
 └────────────┬──────────────────┬──────────────────┘
              │                  │
-   MCP Protocol (31 tools)    npm File-Based
+   MCP Protocol (39 tools)    npm File-Based
              │              (SPECLOCK.md + CLI)
              │                  │
 ┌────────────▼──────────────────▼──────────────────┐
 │            SpecLock Core Engine                    │
 │                                                    │
-│  Semantic Engine ─── 55 synonym groups             │
+│  Semantic Engine ─── 65+ synonym groups            │
 │  HMAC Audit ──────── SHA-256 hash chain            │
 │  Enforcer ────────── advisory / hard block         │
 │  Auth + RBAC ─────── 4 roles, API keys             │
@@ -426,15 +554,26 @@ The AI opens the file and sees:
 
 ## Test Results
 
-| Suite | Tests | Pass Rate |
-|-------|------:|----------:|
-| Direct Mode (heuristic) | 17 | 100% |
-| Payment/Salary Domain | 18 | 100% |
-| Gemini Hybrid (8 domains) | 16 | 100% |
-| Proxy API Endpoint | 9 | 100% |
-| **Total** | **60** | **100%** |
-
-Tested across: fintech, e-commerce, IoT, healthcare, SaaS, gaming, biotech, aerospace, music, legal, payments, payroll. Zero false positives on UI/cosmetic actions.
+| Suite | Tests | Pass Rate | What it covers |
+|-------|------:|----------:|----------------|
+| Adversarial Conflict | 61 | 100% | Euphemisms, temporal evasion, compound sentences |
+| Typed Constraints | 61 | 100% | Numerical, range, state, temporal validation |
+| Phase 4 (Multi-domain) | 91 | 100% | Fintech, e-commerce, IoT, healthcare, SaaS |
+| John (Indie Dev Journey) | 86 | 100% | 8-session Bolt.new build with 5 locks |
+| Sam (Enterprise HIPAA) | 124 | 100% | HIPAA locks, PHI, encryption, RBAC |
+| Auth & Crypto | 114 | 100% | API keys, RBAC, AES-256 encryption |
+| Audit Chain | 35 | 100% | HMAC-SHA256 chain integrity |
+| Enforcement | 40 | 100% | Hard/advisory mode, overrides |
+| Compliance Export | 50 | 100% | SOC 2, HIPAA, CSV formats |
+| REST API v2 | 28 | 100% | Typed constraint endpoints, SSE |
+| Spec Compiler | 24 | 100% | NL→constraints parsing, auto-apply |
+| Code Graph | 33 | 100% | Import parsing, blast radius, lock mapping |
+| Python SDK | 62 | 100% | pip install, constraint checking |
+| ROS2 Guardian | 26 | 100% | Robot safety constraint enforcement |
+| Real-World Testers | 105 | 95% | 5 developers, 30+ locks, diverse domains |
+| **Total** | **940** | **99.4%** | **13 suites, 15 domains** |
+
+Tested across: fintech, e-commerce, IoT, healthcare, SaaS, gaming, biotech, aerospace, payments, payroll, robotics, autonomous systems. All 11 Indian payment gateways detected. Zero false positives on UI/cosmetic actions.
 
 ---
 
@@ -472,4 +611,4 @@ Built by **[Sandeep Roy](https://github.com/sgroy10)**
 
 ---
 
-<p align="center"><i>v4.5.6 — 600+ tests, 31 MCP tools, 0 false positives, Gemini hybrid. Because remembering isn't enough.</i></p>
+<p align="center"><i>v5.0.0 — 940 tests, 99.4% pass rate, 39 MCP tools, Spec Compiler, Code Graph, Typed Constraints, Python SDK, ROS2, REST API v2. Because remembering isn't enough.</i></p>

package/package.json

@@ -2,9 +2,9 @@
 
   "name": "speclock",
 
-  "version": "4.5.6",
+  "version": "5.0.0",
 
-  "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.",
+  "description": "AI Constraint Engine for autonomous systems governance. Spec Compiler (NL→constraints), Code Graph (blast radius, lock-to-file mapping), Typed constraints (numerical, range, state, temporal), REST API v2, Python SDK, ROS2 integration. 39 MCP tools, Gemini LLM hybrid, HMAC audit chain, RBAC, encryption, SOC 2/HIPAA compliance.",
 
   "type": "module",
 

package/src/cli/index.js

@@ -117,7 +117,7 @@ function refreshContext(root) {
 
 function printHelp() {
   console.log(`
-SpecLock v4.5.6 — AI Constraint Engine (Gemini LLM + Policy-as-Code + SSO + Dashboard + Telemetry + Auth + RBAC + Encryption)
+SpecLock v5.0.0 — AI Constraint Engine (Spec Compiler + Code Graph + Typed Constraints + Python SDK + ROS2 + REST API v2 + Gemini LLM + Policy-as-Code + Auth + RBAC + Encryption)
 Developed by Sandeep Roy (github.com/sgroy10)
 
 Usage: speclock <command> [options]