@watchlight/sdk 0.4.0 → 0.5.0

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+"use strict";
+// The `watchlight` command for the Node/TypeScript lane.
+//
+//   npx watchlight policy test <suite.json>
+//
+// Runs a policy test suite (golden fixtures → expected Allow/Deny/NeedsApproval)
+// against the DE engine and exits non-zero if any fixture fails — drop it into
+// CI to gate a policy change before it can gate a real action. The suite file is
+//
+//   { "policyFile": "watchlight.policy.json",       // and/or inline "policies"
+//     "tests": [ { "name": "...", "action": "book",
+//                  "context": { "amount": 200, "limit": 500 },
+//                  "expect": "Allow" } ] }
+//
+// The dashboard lives in the Python package (`watchlight dev`); this Node CLI is
+// scoped to policy testing.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const path = __importStar(require("node:path"));
+const index_1 = require("./index");
+const policytest_1 = require("./policytest");
+const USAGE = `watchlight — Watchlight Developer Edition (Node)
+
+usage:
+  watchlight policy test <suite.json>   run policy fixtures, exit 1 on failure
+
+suite.json:
+  { "policyFile": "watchlight.policy.json",
+    "policies":   [ { "name": "...", "code": "permit(...);" } ],
+    "tests":      [ { "name": "under limit", "action": "book",
+                      "principal": "User::\\"alice\\"", "resource": "trip/42",
+                      "context": { "amount": 200, "limit": 500 },
+                      "expect": "Allow" } ] }
+`;
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const green = (s) => (useColor ? `\x1b[32m${s}\x1b[0m` : s);
+const red = (s) => (useColor ? `\x1b[31m${s}\x1b[0m` : s);
+const dim = (s) => (useColor ? `\x1b[2m${s}\x1b[0m` : s);
+function printReport(file, report) {
+    console.log(`watchlight policy test — ${file}\n`);
+    for (const r of report.results) {
+        if (r.ok) {
+            console.log(`  ${green("✓")} ${r.name} ${dim("→ " + r.actual)}`);
+        }
+        else {
+            const why = r.reason ? dim(`  (${r.reason})`) : "";
+            console.log(`  ${red("✗")} ${r.name} ${red(`— expected ${r.expected}, got ${r.actual}`)}${why}`);
+        }
+    }
+    const summary = `${report.passed} passed, ${report.failed} failed (${report.total} total)`;
+    console.log("\n" + (report.failed ? red(summary) : green(summary)));
+}
+async function policyTest(file) {
+    if (!file) {
+        console.error("watchlight policy test: missing <suite.json>\n");
+        console.error(USAGE);
+        return 2;
+    }
+    let suite;
+    try {
+        suite = (0, policytest_1.loadTestSuite)(file);
+    }
+    catch (e) {
+        console.error(`watchlight: could not read suite '${file}': ${e.message}`);
+        return 2;
+    }
+    // Fresh, policy-free governor (fail-closed); load only what the suite declares.
+    // No audit is written — `test()` uses the engine's decision core directly.
+    const gov = new index_1.Watchlight({ agent: "policy-test" });
+    if (suite.policyFile) {
+        gov.load(path.resolve(path.dirname(file), suite.policyFile));
+    }
+    for (const p of suite.policies ?? [])
+        gov.allow(p.code, p.name);
+    if (!suite.tests || suite.tests.length === 0) {
+        console.error(`watchlight: suite '${file}' has no tests`);
+        return 2;
+    }
+    let report;
+    try {
+        report = await gov.test(suite.tests);
+    }
+    catch (e) {
+        // malformed fixture (missing action/expect)
+        console.error(`watchlight: ${e.message}`);
+        return 2;
+    }
+    printReport(file, report);
+    return report.failed > 0 ? 1 : 0;
+}
+async function main(argv) {
+    const [cmd, sub, ...rest] = argv;
+    if (cmd === "policy" && sub === "test")
+        return policyTest(rest[0]);
+    if (cmd === "--help" || cmd === "-h" || cmd === undefined) {
+        console.log(USAGE);
+        return 0;
+    }
+    console.error(`watchlight: unknown command '${[cmd, sub].filter(Boolean).join(" ")}'\n`);
+    console.error(USAGE);
+    return 2;
+}
+main(process.argv.slice(2))
+    .then((code) => process.exit(code))
+    .catch((e) => {
+    console.error(`watchlight: ${e?.message ?? e}`);
+    process.exit(1);
+});

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { Scope } from "./attenuation";
 import { type SanitizeOptions, type SanitizeResult } from "./sanitize";
+import { type PolicyTestCase, type PolicyTestReport } from "./policytest";
 export { Scope, DE_MAX_DEPTH, AttenuationDenied, DevEditionCeiling } from "./attenuation";
 export { governedHooks } from "./claude-agent";
 export type { GovernedHooksOptions, GovernedHooksResult } from "./claude-agent";
@@ -9,6 +10,8 @@ export { sanitize, SanitizeError, DETECTOR_VERSION } from "./sanitize";
 export type { PiiType, RedactMode, SanitizeOptions, SanitizeReport, SanitizeResult, } from "./sanitize";
 export type { GovernanceBackend, Decision, AuthorizeRequest } from "./backend";
 export { InProcessBackend, NetworkedBackend } from "./backend";
+export { runPolicyTests, loadTestSuite } from "./policytest";
+export type { PolicyTestCase, PolicyTestReport, PolicyTestResult, PolicyTestSuite, } from "./policytest";
 /** Raised when the policy engine refuses a governed tool call (fail-closed). */
 export declare class Denied extends Error {
     readonly tool: string;
@@ -156,6 +159,24 @@ export declare class Watchlight {
         /** A token from {@link mintApproval} (after human confirmation). */
         approval?: string;
     }): Promise<AuthorizeResult>;
+    /**
+     * The pure decision core behind {@link authorize}: run the engine, apply the
+     * approval-token downgrade, and compute the three-state verdict — WITHOUT
+     * writing to the audit trail. Used by {@link authorize} (which then audits)
+     * and by {@link test} (which must not pollute the trail with fixture runs).
+     */
+    private _decide;
+    /**
+     * Run a list of policy fixtures against the loaded policies and report which
+     * pass — a golden-test harness for CI, so a policy change is verified before
+     * it gates real actions. Each case asserts the expected verdict
+     * (`Allow` / `Deny` / `NeedsApproval`) for a `(principal, action, resource,
+     * context)`; set `approved: true` to mint a valid approval token and assert
+     * the human-confirmed downgrade. Does NOT write to the audit trail. A verdict
+     * mismatch is a failed result (inspect `report.failed` and assert on it in
+     * your test runner); a malformed fixture missing `action`/`expect` throws.
+     */
+    test(cases: readonly PolicyTestCase[]): Promise<PolicyTestReport>;
     /**
      * Mint a single-use approval token for a specific `(principal, action,
      * resource)`, to pass to {@link authorize} after a human confirms a

package/dist/policytest.d.ts

@@ -0,0 +1,80 @@
+/** A single policy fixture: an input and the verdict it must produce. */
+export interface PolicyTestCase {
+    /** Human-readable label (defaults to `"<action> on <resource>"`). */
+    name?: string;
+    /** The intent / action being authorized (Cedar `action == Action::"<action>"`). */
+    action: string;
+    /** Acting principal, e.g. `User::"alice"`. Defaults to the governor's agent. */
+    principal?: string;
+    /** Cedar resource entity. Defaults to `"resource"`. */
+    resource?: string;
+    /** Attributes exposed to Cedar `context.*`. */
+    context?: Record<string, unknown>;
+    /** Mint a valid single-use approval token for this case and assert the
+     *  human-confirmed downgrade (turns a `NeedsApproval` into `Allow`). */
+    approved?: boolean;
+    /** The verdict this case must produce. Case-insensitive. */
+    expect: "Allow" | "Deny" | "NeedsApproval";
+}
+/** The outcome of one fixture. */
+export interface PolicyTestResult {
+    name: string;
+    expected: "Allow" | "Deny" | "NeedsApproval";
+    actual: "Allow" | "Deny" | "NeedsApproval";
+    ok: boolean;
+    /** Engine reason — surfaced to explain an unexpected verdict. */
+    reason: string;
+}
+/** The aggregate report. `failed === 0` means the suite passed. */
+export interface PolicyTestReport {
+    total: number;
+    passed: number;
+    failed: number;
+    results: PolicyTestResult[];
+}
+/** A suite file: inline policies and/or a policy file, plus the fixtures. */
+export interface PolicyTestSuite {
+    /** Inline Cedar policies. */
+    policies?: {
+        name?: string;
+        code: string;
+    }[];
+    /** Path to a `watchlight.policy.json` (resolved relative to the suite file). */
+    policyFile?: string;
+    /** The fixtures to run. */
+    tests: PolicyTestCase[];
+}
+type Verdict = "Allow" | "Deny" | "NeedsApproval";
+/** The pure decision function the harness drives — the same core `authorize`
+ *  uses, minus the audit write. */
+export type DecideFn = (req: {
+    action: string;
+    principal?: string;
+    resource?: string;
+    context?: Record<string, unknown>;
+    approval?: string;
+}) => Promise<{
+    decision: Verdict;
+    reason: string;
+}>;
+/** Mints a single-use approval token bound to a challenge — used when a fixture
+ *  sets `approved: true` to exercise the human-confirmed path. */
+export type MintFn = (challenge: {
+    action: string;
+    principal?: string;
+    resource?: string;
+}) => string;
+/**
+ * Run policy fixtures through a decision function and report pass/fail. A
+ * verdict mismatch is recorded as a failed result rather than thrown — inspect
+ * {@link PolicyTestReport.failed}. A fixture missing a required key (`action` or
+ * `expect`) is a malformed suite and throws.
+ */
+export declare function runPolicyTests(decide: DecideFn, mint: MintFn, cases: readonly PolicyTestCase[]): Promise<PolicyTestReport>;
+/**
+ * Load a suite file. Accepts `{ policies?, policyFile? | policy_file?, tests }`
+ * (a bare array of tests is also accepted). Throws on malformed JSON so a broken
+ * suite fails the CI step rather than silently passing.
+ */
+export declare function loadTestSuite(file: string): PolicyTestSuite;
+export {};

package/dist/policytest.js

@@ -0,0 +1,123 @@
+"use strict";
+// Policy test harness — golden tests for DE policies.
+//
+// A policy is the only thing standing between an agent and a real action, so it
+// deserves the same unit-testing discipline as the code around it. This module
+// runs a list of fixtures against the loaded policies and reports which pass:
+// each case asserts the expected verdict (Allow / Deny / NeedsApproval) for a
+// `(principal, action, resource, context)`. It contains ZERO decision logic —
+// every verdict comes from the engine, via the same decision core `authorize`
+// uses — and it never writes to the audit trail, so CI runs leave no residue.
+//
+//   import { govern } from "@watchlight/sdk";
+//   govern.load("watchlight.policy.json");
+//   const r = await govern.test([
+//     { name: "under limit allows", action: "book",
+//       context: { amount: 200, limit: 500, refundable: true }, expect: "Allow" },
+//   ]);
+//   if (r.failed) throw new Error(`${r.failed} policy tests failed`);
+//
+// Or from CI, with the `watchlight` CLI:  npx watchlight policy test suite.json
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runPolicyTests = runPolicyTests;
+exports.loadTestSuite = loadTestSuite;
+const fs = __importStar(require("node:fs"));
+/** Normalize a caller-supplied verdict string to the canonical spelling.
+ *  Anything unrecognized is returned verbatim so a typo fails loudly. */
+function normalizeVerdict(v) {
+    const s = String(v ?? "").trim().toLowerCase();
+    if (s === "allow" || s === "permit")
+        return "Allow";
+    if (s === "deny")
+        return "Deny";
+    if (s === "needsapproval" || s === "needs_approval" || s === "approve" || s === "approval")
+        return "NeedsApproval";
+    return v ?? "Deny";
+}
+/**
+ * Run policy fixtures through a decision function and report pass/fail. A
+ * verdict mismatch is recorded as a failed result rather than thrown — inspect
+ * {@link PolicyTestReport.failed}. A fixture missing a required key (`action` or
+ * `expect`) is a malformed suite and throws.
+ */
+async function runPolicyTests(decide, mint, cases) {
+    const results = [];
+    let index = 0;
+    for (const c of cases) {
+        for (const required of ["action", "expect"]) {
+            if (c[required] === undefined) {
+                throw new Error(`fixture ${index} (${c.name ?? "?"}): missing required key '${required}'`);
+            }
+        }
+        index += 1;
+        const expected = normalizeVerdict(c.expect);
+        const approval = c.approved
+            ? mint({ action: c.action, principal: c.principal, resource: c.resource })
+            : undefined;
+        const d = await decide({
+            action: c.action,
+            principal: c.principal,
+            resource: c.resource,
+            context: c.context,
+            approval,
+        });
+        const actual = normalizeVerdict(d.decision);
+        results.push({
+            name: c.name ?? `${c.action} on ${c.resource ?? "resource"}`,
+            expected,
+            actual,
+            ok: actual === expected,
+            reason: d.reason ?? "",
+        });
+    }
+    const passed = results.filter((r) => r.ok).length;
+    return { total: results.length, passed, failed: results.length - passed, results };
+}
+/**
+ * Load a suite file. Accepts `{ policies?, policyFile? | policy_file?, tests }`
+ * (a bare array of tests is also accepted). Throws on malformed JSON so a broken
+ * suite fails the CI step rather than silently passing.
+ */
+function loadTestSuite(file) {
+    const data = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (Array.isArray(data))
+        return { tests: data };
+    return {
+        policies: data.policies,
+        policyFile: data.policyFile ?? data.policy_file,
+        tests: data.tests ?? data.cases ?? [],
+    };
+}

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@watchlight/sdk",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Watchlight Developer Edition govern glue for Node/TypeScript — declare intent, govern a tool with a fail-closed in-process policy decision, and get a value-free audit trail. Glue over @watchlight/engine; zero decision logic in JS.",
   "type": "commonjs",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "watchlight": "./dist/cli.js"
+  },
   "files": [
     "dist",
     "LICENSE",
@@ -15,7 +18,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && for t in govern claude-agent graduation langchain sanitize action-gate; do node test/$t.test.mjs || exit 1; done",
+    "test": "npm run build && for t in govern claude-agent graduation langchain sanitize action-gate policytest; do node test/$t.test.mjs || exit 1; done",
     "prepublishOnly": "npm run build"
   },
   "keywords": [