@manukyalo/scopelock 2.0.0 → 2.1.0

package/README.md

@@ -8,53 +8,32 @@ npm install -g @manukyalo/scopelock
 
 `scopelock` solves a specific, well-documented problem: AI coding agents frequently exhibit scope creep — modifying files outside the intended change — and lack persistent project memory across sessions.
 
----
+`scopelock` acts as a physical guardrail (via a pre-commit hook) and an architectural memory bank (via the context block) to keep agents strictly confined to their authorized scope.
 
-## Companion Skill
+## Features
 
-`skills/scope-enforcement/SKILL.md` is a structured 3-checkpoint workflow for AI agents that enforces scopelock boundaries across every phase of a session. Load it into: **Antigravity**, **Claude Code**, **Gemini CLI**, **Cursor**, **Kiro**.
-
----
-
-## The Problem
-
-You ask an AI agent to fix the login button. It also refactors your auth middleware, updates 3 unrelated components, and breaks a working API route. You had no pre-commit guardrail to stop it.
-
-`scopelock` enforces scope at two levels:
-
-| Protection | What it stops |
-|------------|--------------|
-| **File-level** | Agent modifies any file marked `locked` |
-| **Function-level** | Agent modifies lines inside a locked function body, even if the surrounding file is `active` |
+- **File-level locks**: Run `scopelock lock src/auth.ts` to make the file read-only for agents.
+- **Function-level locks**: Don't want to lock the whole file? Lock specific AST functions so agents can only edit adjacent code.
+- **Dependency Lockdown**: Zero-trust dependency management. Automatically locks `package.json` and other dependency manifests on init to prevent silent dependency drift.
+- **Secret Sentinel**: A hard-blocking pre-commit scanner that physically prevents agents from committing AWS keys, Stripe tokens, or `.env` leaks.
+- **Zero dependencies**: Written in pure Node.js. Install it anywhere without bloating your `node_modules`.
 
 ---
 
 ## Commands
 
-### `scopelock init`
-Scan the repo and generate `.scopelock.json`. Automatically ignores `node_modules`, `.git`, `.next`, `dist`, `build`, `out`, `coverage`, and other build artifacts.
-
 ```bash
-scopelock init
+  scopelock init                           Scan repo and generate .scopelock.json
+  scopelock lock <file>[:<func>] [reason]  Lock a file or a specific function
+  scopelock unlock <file>[:<func>] <reason> Unlock (reason is mandatory)
+  scopelock allow-secret <file> <reason>   Bypass Secret Sentinel for a specific file
+  scopelock context [task]                 Generate AI context block for a task
+  scopelock check                          Check git diff for scope violations and secret leaks
+  scopelock status                         Show manifest summary
 ```
 
-### `scopelock status`
-Print a human-readable summary of the manifest.
-
-```bash
-scopelock status
-
-# 📋  scopelock status
-#
-#   🔒  locked    — 3 file(s), 2 function(s)
-#   ✏️   active    — 1 file(s)
-#   ⬜  unscoped  — 98 file(s)
-#
-# Locked files:
-#   src/lib/supabase.ts
-#   src/middleware.ts
-#     └── middleware() [locked]
-```
+### `scopelock init`
+Scan the repo and generate `.scopelock.json`. Automatically ignores `node_modules`, `.git`, `.next`, `dist`, `build`, `out`, `coverage`, and other build artifacts.
 
 ### `scopelock lock <file>[:<function>] [reason]`
 Lock a whole file or a specific named function.
@@ -74,8 +53,15 @@ Unlock a file or function. Reason is mandatory and logged.
 scopelock unlock src/auth/token.ts:validateToken "fixing JWT expiry edge case"
 ```
 
+### `scopelock allow-secret <file> <reason>`
+Bypass the Secret Sentinel hard-block for a specific file (e.g., when intentionally committing a mock test key).
+
+```bash
+scopelock allow-secret test/run.js "this is a mock stripe key for testing"
+```
+
 ### `scopelock check`
-Two-tier scope violation check against `git diff HEAD`. Exits non-zero on violations.
+Two-tier scope violation check against `git diff HEAD`. Exits non-zero on violations or secret leaks. Wire this up as a `pre-commit` hook.
 
 ```bash
 scopelock check
@@ -85,57 +71,27 @@ scopelock check
 Output a token-efficient AI context block with all locks clearly flagged.
 
 ```bash
-scopelock context "Fix the broken checkout flow" | clip
+scopelock context "Update the login page"
 ```
-
----
-
-## Pre-commit Hook
-
-```bash
-echo '#!/bin/sh
-scopelock check' > .git/hooks/pre-commit
-chmod +x .git/hooks/pre-commit
 ```
+[SCOPE CONTEXT]
+Task: Update the login page
 
-Once wired, no agent or developer can commit a scope violation.
-
----
-
-## File Statuses
-
-| Status | Meaning |
-|--------|---------|
-| `unscoped` | Not yet classified |
-| `locked` | Stable — do not modify without an explicit `scopelock unlock` |
-| `active` | In scope for the current task |
-
----
-
-## Language Support for Function-level Locking
+Status:
+  🔒 locked   — 1 file(s)
+  ✏️ active   — 0 file(s)
+  ⬜ unscoped — 14 file(s)
 
-| Language | Extensions |
-|----------|-----------|
-| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` |
-| TypeScript | `.ts`, `.tsx` |
-| Python | `.py` |
+Locked files:
+  src/lib/supabase.ts
+```
 
-All other file types fall back to file-level locking automatically.
+## Agent Skill
 
----
+`scopelock` includes a native Agent Skill. 
+If you use an agent framework (like Antigravity or Cline) that supports Markdown skills, point it to `skills/scope-enforcement/SKILL.md` to automatically teach the agent how to use `scopelock` safely.
 
-## Commit `.scopelock.json`
+## Data Model
+All state is stored in `.scopelock.json` at the root of your repo.
 
 The manifest is project state, not a personal config. Commit it so your whole team — and all their AI agents — share the same scope boundaries.
-
----
-
-## Zero Dependencies
-
-Built entirely on Node.js built-ins (`fs`, `path`, `child_process`). No runtime dependencies.
-
----
-
-## License
-
-MIT

package/bin/scopelock.js

@@ -61,6 +61,17 @@ switch (command) {
     manifest.status();
     break;
 
+  case 'allow-secret': {
+    const target = args[0];
+    const reason = args.slice(1).join(' ');
+    if (!target || !reason) {
+      console.error('Usage: scopelock allow-secret <file> <reason>');
+      process.exit(1);
+    }
+    manifest.allowSecret(target, reason);
+    break;
+  }
+
   default:
     console.log(`
 scopelock — Anti-hallucination scope locking for AI coding agents.
@@ -69,10 +80,12 @@ Usage:
   scopelock init                           Scan repo and generate .scopelock.json
   scopelock lock <file>[:<func>] [reason]  Lock a file or a specific function
   scopelock unlock <file>[:<func>] <reason> Unlock (reason is mandatory)
+  scopelock allow-secret <file> <reason>   Bypass Secret Sentinel for a specific file
   scopelock context [task]                 Generate AI context block for a task
-  scopelock check                          Check git diff for scope violations
+  scopelock check                          Check git diff for scope violations and secret leaks
   scopelock status                         Show manifest summary
 
+
 Examples:
   scopelock lock src/auth.ts
   scopelock lock src/auth.ts:validateToken "stable — do not touch"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manukyalo/scopelock",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Anti-hallucination scope locking for AI coding agents.",
   "main": "bin/scopelock.js",
   "bin": {

package/src/diff.js

@@ -17,7 +17,7 @@ const HUNK_HEADER_RE = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/;
 
 /**
  * @param {string} filePath
- * @returns {Set<number>}  1-indexed line numbers that changed in the new file.
+ * @returns {Map<number, string>}  1-indexed line numbers -> line content that changed in the new file.
  */
 function getChangedLines(filePath) {
   let diffOutput;
@@ -31,9 +31,9 @@ function getChangedLines(filePath) {
     return new Set();
   }
 
-  if (!diffOutput.trim()) return new Set();
+  if (!diffOutput.trim()) return new Map();
 
-  const changedLines = new Set();
+  const changedLines = new Map();
   const lines        = diffOutput.split('\n');
   let   currentLine  = 0;
 
@@ -51,7 +51,8 @@ function getChangedLines(filePath) {
 
     if (line.startsWith('+')) {
       // Added/changed line in the new file
-      changedLines.add(currentLine);
+      // Strip the leading '+' before saving the content
+      changedLines.set(currentLine, line.substring(1));
       currentLine++;
     } else if (line.startsWith('-')) {
       // Deleted line — does NOT advance the new-file line counter

package/src/git.js

@@ -19,6 +19,7 @@ const { execSync }      = require('child_process');
 const { getManifest }   = require('./manifest');
 const { getChangedLines } = require('./diff');
 const { extractFunctions } = require('./parser');
+const { detectSecret }  = require('./secrets');
 
 function check() {
   const manifest = getManifest();
@@ -51,6 +52,27 @@ function check() {
     const normalizedFile = file.replace(/\\/g, '/');
     const entry          = manifest.files[normalizedFile];
 
+    const changedLines = getChangedLines(normalizedFile);
+
+    // ── Tier 0: Secret Sentinel ─────────────────────────────────────────────
+    if (changedLines.size > 0) {
+      // Check if this file has explicitly allowed secrets
+      const hasOverride = manifest.allowedSecrets && manifest.allowedSecrets[normalizedFile];
+      if (!hasOverride) {
+        for (const [lineNum, content] of changedLines.entries()) {
+          const secretType = detectSecret(content);
+          if (secretType) {
+            violations.push({
+              type: 'secret',
+              file: normalizedFile,
+              message: `SECRET LEAK [${secretType}] detected in '${normalizedFile}' on line ${lineNum}.`,
+            });
+            break; // One secret violation per file is enough
+          }
+        }
+      }
+    }
+
     // ── Tier 1: File-level lock ─────────────────────────────────────────────
     if (entry && entry.status === 'locked') {
       violations.push({
@@ -70,10 +92,6 @@ function check() {
 
     if (lockedFunctions.length === 0) continue;
 
-    // Get the line numbers that changed in this specific file
-    const changedLines = getChangedLines(normalizedFile);
-    if (changedLines.size === 0) continue;
-
     // Re-extract function boundaries from the current on-disk file
     const currentFunctions = extractFunctions(normalizedFile);
 
@@ -91,7 +109,7 @@ function check() {
       }
 
       // Check if any changed line falls within the function's boundaries
-      for (const line of changedLines) {
+      for (const line of changedLines.keys()) {
         if (line >= fn.startLine && line <= fn.endLine) {
           violations.push({
             type: 'function',

package/src/manifest.js

@@ -71,18 +71,29 @@ function saveManifest(data) {
   fs.writeFileSync(MANIFEST_FILE, JSON.stringify(data, null, 2));
 }
 
+const DEPENDENCY_MANIFESTS = new Set([
+  'package.json', 'package-lock.json', 'yarn.lock', 'pnpm-lock.yaml',
+  'requirements.txt', 'Pipfile', 'Pipfile.lock', 'poetry.lock',
+  'Cargo.toml', 'Cargo.lock', 'go.mod', 'go.sum'
+]);
+
 // Ensure a file entry exists in the manifest, creating it if needed.
 function ensureFileEntry(manifest, relativePath) {
   if (!manifest.files[relativePath]) {
-    manifest.files[relativePath] = { status: 'unscoped', functions: {}, history: [] };
+    // Auto-lock dependency manifests
+    const isDep = DEPENDENCY_MANIFESTS.has(path.basename(relativePath));
+    manifest.files[relativePath] = { 
+      status: isDep ? 'locked' : 'unscoped', 
+      functions: {}, 
+      history: isDep ? [{ timestamp: new Date().toISOString(), action: 'locked', reason: 'auto-locked dependency manifest' }] : []
+    };
   }
   if (!manifest.files[relativePath].functions) {
     manifest.files[relativePath].functions = {};
   }
 }
 
-// ─── Commands ─────────────────────────────────────────────────────────────────
-
+// Ensure entry exists for 'init' function
 function init() {
   if (fs.existsSync(MANIFEST_FILE)) {
     console.log(`.scopelock.json already exists. Use 'scopelock status' to view it.`);
@@ -90,13 +101,13 @@ function init() {
   }
 
   const files    = walkDir('.');
-  const manifest = { version: VERSION, files: {} };
+  const manifest = { version: VERSION, files: {}, allowedSecrets: {} };
   let   count    = 0;
 
   for (const f of files) {
     const relativePath = path.relative('.', f).replace(/\\/g, '/');
     if (relativePath === MANIFEST_FILE) continue;
-    manifest.files[relativePath] = { status: 'unscoped', functions: {}, history: [] };
+    ensureFileEntry(manifest, relativePath);
     count++;
   }
 
@@ -256,4 +267,31 @@ function status() {
   console.log('');
 }
 
-module.exports = { init, lock, unlock, status, getManifest, saveManifest };
+/**
+ * Allow a secret to be committed in a specific file.
+ *
+ * @param {string} file  "<file>"
+ * @param {string} reason  Mandatory reason string.
+ */
+function allowSecret(file, reason) {
+  const relativePath = file.replace(/\\/g, '/');
+  const manifest = getManifest();
+  
+  if (!manifest.allowedSecrets) {
+    manifest.allowedSecrets = {};
+  }
+  
+  if (!manifest.allowedSecrets[relativePath]) {
+    manifest.allowedSecrets[relativePath] = [];
+  }
+  
+  manifest.allowedSecrets[relativePath].push({
+    timestamp: new Date().toISOString(),
+    reason
+  });
+  
+  saveManifest(manifest);
+  console.log(`⚠️  Secret Sentinel bypassed for ${relativePath}. Reason: ${reason}`);
+}
+
+module.exports = { init, lock, unlock, allowSecret, status, getManifest, saveManifest };

package/src/secrets.js

@@ -0,0 +1,31 @@
+'use strict';
+
+/**
+ * src/secrets.js
+ *
+ * Scans strings for high-risk secrets.
+ * Returns an array of detected secret types.
+ */
+
+const SECRET_PATTERNS = {
+  'AWS Access Key': /(?:A3T[A-Z0-9]|AKIA|AGPA|AIDA|AROA|AIPA|ANPA|ANVA|ASIA)[A-Z0-9]{16}/,
+  'Stripe Secret Key': /sk_(?:live|test)_[0-9a-zA-Z]{24}/,
+  'GitHub Token': /gh[pousr]_[A-Za-z0-9_]{36,}/,
+  'Slack Token': /xox[baprs]-[0-9]{12}-[0-9]{12}-[a-zA-Z0-9]{24}/,
+  'Generic API Key / Secret': /(?:api[_-]?key|secret|token|password)[\s]*[=:]\s*["'][a-zA-Z0-9_\-]{16,}["']/i
+};
+
+/**
+ * @param {string} lineContent
+ * @returns {string|null} The name of the secret type detected, or null.
+ */
+function detectSecret(lineContent) {
+  for (const [name, regex] of Object.entries(SECRET_PATTERNS)) {
+    if (regex.test(lineContent)) {
+      return name;
+    }
+  }
+  return null;
+}
+
+module.exports = { detectSecret };

package/test/run.js

@@ -59,6 +59,7 @@ function workInProgress() {
 `.trimStart());
 
 fs.writeFileSync('readme.txt', 'Initial readme content.\n');
+fs.writeFileSync('package.json', '{"name":"test"}\n'); // Dummy package manifest
 run('git add .');
 run('git commit -m "initial"');
 
@@ -70,29 +71,43 @@ assert(fs.existsSync('.scopelock.json'), '.scopelock.json was created');
 const manifest = JSON.parse(fs.readFileSync('.scopelock.json', 'utf8'));
 assert(manifest.version === 2, 'Manifest is V2 schema');
 assert(manifest.files['app.js'] !== undefined, 'app.js is tracked');
-assert(manifest.files['readme.txt'] !== undefined, 'readme.txt is tracked');
 
-console.log('\n--- Test 2: scopelock status ---');
+console.log('\n--- Test 2: Dependency auto-lock (Dependency Lockdown) ---');
+assert(manifest.files['package.json'].status === 'locked', 'package.json is automatically locked on init');
+
+console.log('\n--- Test 3: scopelock status ---');
 const statusOut = run(`${CLI} status`);
 assert(statusOut.includes('unscoped'), 'status shows unscoped files');
 
-console.log('\n--- Test 3: File-level lock ---');
+console.log('\n--- Test 4: File-level lock ---');
 run(`${CLI} lock readme.txt "stable documentation"`);
 const m2 = JSON.parse(fs.readFileSync('.scopelock.json', 'utf8'));
 assert(m2.files['readme.txt'].status === 'locked', 'readme.txt is locked');
 
-console.log('\n--- Test 4: File-level violation detection ---');
+console.log('\n--- Test 5: File-level violation detection ---');
 fs.appendFileSync('readme.txt', 'AI hallucinated this line.\n');
 const violation1 = run(`${CLI} check`, true);
 assert(violation1.includes('VIOLATION'), 'check detects locked file modification');
 
-console.log('\n--- Test 5: File-level unlock clears violation ---');
+console.log('\n--- Test 6: File-level unlock clears violation ---');
 run(`${CLI} unlock readme.txt "intentional update to docs"`);
 const check1 = run(`${CLI} check`);
 assert(check1.includes('passed'), 'check passes after unlock');
 run('git restore readme.txt'); // clean up
 
-console.log('\n--- Test 6: Function-level lock ---');
+console.log('\n--- Test 7: Secret Sentinel detection ---');
+fs.appendFileSync('readme.txt', 'const stripe_key = "sk_test_12345abcdeABCDE12345abcd";\n');
+const secretViolation = run(`${CLI} check`, true);
+assert(secretViolation.includes('SECRET LEAK'), 'check detects leaked stripe key');
+assert(secretViolation.includes('Stripe Secret Key'), 'check identifies secret type');
+
+console.log('\n--- Test 8: Secret Sentinel bypass (allow-secret) ---');
+run(`${CLI} allow-secret readme.txt "it is a mock key for tests"`);
+const secretCheck = run(`${CLI} check`);
+assert(secretCheck.includes('passed'), 'allow-secret successfully bypasses secret sentinel');
+run('git restore readme.txt'); // clean up
+
+console.log('\n--- Test 9: Function-level lock ---');
 run(`${CLI} lock app.js:stableFunc "tested, production-ready"`);
 const m3 = JSON.parse(fs.readFileSync('.scopelock.json', 'utf8'));
 assert(
@@ -100,7 +115,7 @@ assert(
   'stableFunc is function-locked'
 );
 
-console.log('\n--- Test 7: Change OUTSIDE locked function — no violation ---');
+console.log('\n--- Test 10: Change OUTSIDE locked function — no violation ---');
 // Modify workInProgress (line 6-8), stableFunc is locked (lines 1-3)
 fs.writeFileSync('app.js', `
 function stableFunc() {
@@ -114,7 +129,7 @@ function workInProgress() {
 const check2 = run(`${CLI} check`);
 assert(check2.includes('passed'), 'change outside locked function does not trigger violation');
 
-console.log('\n--- Test 8: Change INSIDE locked function — violation ---');
+console.log('\n--- Test 11: Change INSIDE locked function — violation ---');
 fs.writeFileSync('app.js', `
 function stableFunc() {
   return 'I have been hallucinated';
@@ -128,19 +143,19 @@ const violation2 = run(`${CLI} check`, true);
 assert(violation2.includes('VIOLATION'), 'change inside locked function triggers violation');
 assert(violation2.includes('stableFunc'), 'violation names the locked function');
 
-console.log('\n--- Test 9: Function unlock clears function-level violation ---');
+console.log('\n--- Test 12: Function unlock clears function-level violation ---');
 run(`${CLI} unlock app.js:stableFunc "need to update return value for new API"`);
 const check3 = run(`${CLI} check`);
 assert(check3.includes('passed'), 'check passes after function unlock');
 
-console.log('\n--- Test 10: Lock unknown function fails gracefully ---');
+console.log('\n--- Test 13: Lock unknown function fails gracefully ---');
 const badLock = run(`${CLI} lock app.js:doesNotExist "testing"`, true);
 assert(badLock.includes('not found'), 'locking unknown function fails with clear message');
 
-console.log('\n--- Test 11: scopelock context output ---');
+console.log('\n--- Test 14: scopelock context output ---');
 const ctx = run(`${CLI} context "update the WIP function"`);
 assert(ctx.includes('SCOPE CONTEXT'), 'context output contains header');
 
 // ─── Done ─────────────────────────────────────────────────────────────────────
 
-console.log('\n✅  All 11 tests passed.\n');
+console.log('\n✅  All 14 tests passed.\n');