feat: add simulate CLI subcommand + dispatcher router (v0.1.2)

Author: repoforge-dev

README.md

@@ -35,7 +35,7 @@ npx authority-layer doctor
 ```
 
 ```
-AuthorityLayer Doctor  authority-layer@0.1.1
+AuthorityLayer Doctor  authority-layer@0.1.2
 
   ✔  Node.js version >= 18                  pass
   ✔  crypto module (sha256)                 pass
@@ -46,6 +46,14 @@ AuthorityLayer Doctor  authority-layer@0.1.1
 All checks passed. AuthorityLayer is ready.
 ```
 
+Try a simulated enforcement run:
+
+```bash
+npx authority-layer simulate
+```
+
+Runs a canned agent loop that intentionally exceeds the budget cap — so you can see AuthorityLayer halt execution and verify the event chain without writing any code.
+
 ---
 
 ## Minimal Integration

packages/core/package.json

@@ -1,22 +1,23 @@
 {
   "name": "authority-layer",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Hard execution and budget limits for autonomous agents — enforced locally.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist"
   ],
   "bin": {
-    "authority-layer": "dist/doctor.js"
+    "authority-layer": "dist/cli.js"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "dev": "tsc -p tsconfig.json --watch",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "validate": "tsc -p tsconfig.json && node dist/index.js",
     "example": "node ../../examples/run.js",
-    "doctor": "node dist/doctor.js",
+    "doctor": "node dist/cli.js doctor",
+    "simulate": "node dist/cli.js simulate",
     "prepublishOnly": "npm run build && npm run typecheck"
   },
   "keywords": [

packages/core/src/cli.ts

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+// ─────────────────────────────────────────────────────────────────────────────
+// authority-layer CLI dispatcher
+//
+// Routes subcommands to their implementations.
+// All new subcommands should be added here.
+//
+// Usage:
+//   npx authority-layer doctor
+//   npx authority-layer simulate
+// ─────────────────────────────────────────────────────────────────────────────
+
+const RESET = "\x1b[0m";
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const CYAN = "\x1b[1;36m";
+const YELLOW = "\x1b[1;33m";
+
+const subcommand = process.argv[2];
+
+switch (subcommand) {
+    case "doctor": {
+        // Doctor runs its own top-level logic — require the compiled file directly
+        require("./doctor");
+        break;
+    }
+
+    case "simulate": {
+        const { runSimulate } = require("./cli/simulate") as { runSimulate: () => Promise<void> };
+        runSimulate().catch((err: unknown) => {
+            console.error(err);
+            process.exit(1);
+        });
+        break;
+    }
+
+    default: {
+        const pkg = require("../package.json") as { name: string; version: string };
+        console.log(`\n${BOLD}${pkg.name}${RESET}  ${DIM}v${pkg.version}${RESET}\n`);
+        console.log("Usage:\n");
+        console.log(`  ${CYAN}authority-layer doctor${RESET}    ${DIM}Run environment checks${RESET}`);
+        console.log(`  ${CYAN}authority-layer simulate${RESET}  ${DIM}Run a live enforcement simulation${RESET}`);
+        console.log();
+        if (subcommand) {
+            console.log(`${YELLOW}Unknown command: ${subcommand}${RESET}\n`);
+            process.exit(1);
+        }
+        process.exit(0);
+    }
+}

packages/core/src/cli/simulate.ts

@@ -0,0 +1,82 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// authority-layer simulate
+//
+// Runs a short simulated agent execution that intentionally exceeds the
+// budget cap so developers can see enforcement halt output without writing
+// any code.
+//
+// Usage:
+//   npx authority-layer simulate
+// ─────────────────────────────────────────────────────────────────────────────
+
+import { AuthorityLayer } from "../AuthorityLayer";
+import { EnforcementHalt } from "../EnforcementHalt";
+
+const RESET = "\x1b[0m";
+const GREEN = "\x1b[1;32m";
+const RED = "\x1b[1;31m";
+const YELLOW = "\x1b[1;33m";
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+
+export async function runSimulate(): Promise<void> {
+    console.log(`\n${BOLD}AuthorityLayer Simulation${RESET}`);
+    console.log(`${DIM}Demonstrating runtime enforcement.${RESET}\n`);
+
+    const authority = new AuthorityLayer({
+        budget: { dailyUSD: 0.05 },
+        loopGuard: { maxToolCallsPerRun: 10 },
+        toolThrottle: { maxCallsPerMinute: 100 },
+    });
+
+    console.log(`${DIM}Config: $0.05 budget cap · 10 calls/run max · 100 calls/min${RESET}\n`);
+    console.log("Starting simulated agent run...\n");
+
+    let callCount = 0;
+
+    try {
+        await authority.wrap(async () => {
+            // 7 calls × $0.01 = $0.07 — exceeds the $0.05 cap after call 6
+            for (let i = 1; i <= 7; i++) {
+                callCount++;
+                await authority.tool("llm.chat", async () => "LLM response");
+                console.log(`  Tool call #${i}  ${DIM}llm.chat${RESET}`);
+                authority.recordSpend(0.01);
+            }
+        });
+    } catch (err) {
+        if (err instanceof EnforcementHalt) {
+            console.log(`\n${RED}${BOLD}⛔ Execution halted by AuthorityLayer${RESET}\n`);
+            const h = err.enforcement;
+            const display = {
+                status: h.status,
+                reason: h.reason,
+                limit: Math.round(h.limit * 100) / 100,
+                spent: Math.round(h.spent * 100) / 100,
+                event_id: h.event_id,
+            };
+            console.log(YELLOW + JSON.stringify(display, null, 2) + RESET);
+        } else {
+            throw err;
+        }
+    }
+
+    // ── Integrity check ───────────────────────────────────────────────────────
+
+    const valid = authority.verifyChain();
+    const chain = authority.getChain();
+
+    console.log(`\n${DIM}─── Event chain ${"─".repeat(44)}${RESET}`);
+    for (const event of chain) {
+        const ts = new Date(event.timestamp).toISOString().slice(11, 23);
+        console.log(`  ${DIM}[${ts}]${RESET}  ${event.type.padEnd(20)}  ${DIM}${event.event_id}${RESET}`);
+    }
+
+    console.log();
+    if (valid) {
+        console.log(`Event chain integrity: ${GREEN}${BOLD}VERIFIED${RESET}`);
+    } else {
+        console.log(`Event chain integrity: ${RED}${BOLD}TAMPERED${RESET}`);
+    }
+    console.log(`Total events: ${chain.length}\n`);
+}