@neuroverseos/governance 0.3.4 → 0.4.1

package/dist/chunk-3S5AD4AB.js

@@ -0,0 +1,421 @@
+import {
+  GovernanceBlockedError,
+  buildEngineOptions,
+  trackPlanProgress
+} from "./chunk-5U2MQO5P.js";
+import {
+  evaluateGuard
+} from "./chunk-ZAF6JH23.js";
+import {
+  loadWorld
+} from "./chunk-I4RTIMLX.js";
+
+// src/adapters/github.ts
+var GitHubGovernanceBlockedError = class extends GovernanceBlockedError {
+  action;
+  constructor(verdict, action) {
+    super(verdict, `[NeuroVerse] GitHub action blocked: ${action.action} on ${action.repository}`);
+    this.name = "GitHubGovernanceBlockedError";
+    this.action = action;
+  }
+};
+function extractBranch(ref) {
+  if (!ref) return void 0;
+  if (ref.startsWith("refs/heads/")) return ref.slice("refs/heads/".length);
+  if (ref.startsWith("refs/tags/")) return ref.slice("refs/tags/".length);
+  return ref;
+}
+function isProtectedBranch(branch, protectedBranches) {
+  if (!branch) return false;
+  return protectedBranches.some(
+    (pb) => branch === pb || branch.startsWith(`${pb}/`)
+  );
+}
+function defaultMapAction(action, protectedBranches, restrictedActors) {
+  const branch = action.branch ?? extractBranch(action.ref);
+  const isProtected = isProtectedBranch(branch, protectedBranches);
+  const isRestricted = action.actor ? restrictedActors.some((ra) => action.actor === ra || action.actor?.endsWith("[bot]")) : false;
+  let actionCategory = "other";
+  const act = action.action.toLowerCase();
+  if (act.includes("read") || act.includes("get") || act.includes("list") || act.includes("view")) {
+    actionCategory = "read";
+  } else if (act.includes("delete") || act.includes("remove") || act.includes("close")) {
+    actionCategory = "delete";
+  } else if (act.includes("deploy") || act.includes("run") || act.includes("execute") || act.includes("merge")) {
+    actionCategory = "network";
+  } else if (act.includes("create") || act.includes("push") || act.includes("write") || act.includes("update") || act.includes("edit")) {
+    actionCategory = "write";
+  } else if (act.includes("comment") || act.includes("review") || act.includes("notify")) {
+    actionCategory = "other";
+  }
+  return {
+    intent: action.action,
+    tool: "github",
+    scope: `${action.repository}${branch ? `@${branch}` : ""}`,
+    actionCategory,
+    direction: "input",
+    args: {
+      repository: action.repository,
+      ref: action.ref,
+      branch,
+      actor: action.actor,
+      protected_branch: isProtected,
+      restricted_actor: isRestricted,
+      ...action.metadata
+    }
+  };
+}
+function defaultMapWebhook(eventType, payload) {
+  const repo = payload.repository;
+  const repoFullName = repo?.full_name ?? "unknown/unknown";
+  const sender = payload.sender;
+  const actor = sender?.login ?? void 0;
+  const webhookAction = payload.action;
+  switch (eventType) {
+    case "push": {
+      const ref = payload.ref;
+      const branch = extractBranch(ref);
+      const forced = payload.forced;
+      return {
+        action: forced ? "force_push" : `push_to_${branch ?? "branch"}`,
+        repository: repoFullName,
+        ref,
+        branch,
+        actor,
+        metadata: {
+          forced: forced ?? false,
+          commits_count: payload.commits?.length ?? 0,
+          head_commit: payload.head_commit?.id
+        }
+      };
+    }
+    case "pull_request": {
+      const pr = payload.pull_request;
+      const base = pr?.base;
+      const baseBranch = base?.ref;
+      const prNumber = pr?.number;
+      const merged = pr?.merged;
+      const labels = pr?.labels?.map((l) => l.name) ?? [];
+      let action = `pull_request_${webhookAction ?? "unknown"}`;
+      if (webhookAction === "closed" && merged) {
+        action = "merge_pull_request";
+      }
+      return {
+        action,
+        repository: repoFullName,
+        branch: baseBranch,
+        actor,
+        metadata: {
+          pr_number: prNumber,
+          labels,
+          merged: merged ?? false,
+          draft: pr?.draft ?? false,
+          webhook_action: webhookAction
+        }
+      };
+    }
+    case "release": {
+      const release = payload.release;
+      return {
+        action: `release_${webhookAction ?? "published"}`,
+        repository: repoFullName,
+        ref: release?.tag_name ? `refs/tags/${release.tag_name}` : void 0,
+        actor,
+        metadata: {
+          tag: release?.tag_name,
+          prerelease: release?.prerelease ?? false,
+          draft: release?.draft ?? false,
+          webhook_action: webhookAction
+        }
+      };
+    }
+    case "deployment":
+    case "deployment_status": {
+      const deployment = payload.deployment ?? payload;
+      return {
+        action: eventType === "deployment" ? "create_deployment" : "deployment_status_update",
+        repository: repoFullName,
+        ref: deployment.ref,
+        actor,
+        metadata: {
+          environment: deployment.environment,
+          status: payload.deployment_status?.state,
+          webhook_action: webhookAction
+        }
+      };
+    }
+    case "workflow_run": {
+      const run = payload.workflow_run;
+      return {
+        action: `workflow_${webhookAction ?? "completed"}`,
+        repository: repoFullName,
+        branch: run?.head_branch,
+        actor,
+        metadata: {
+          workflow_name: run?.name,
+          conclusion: run?.conclusion,
+          status: run?.status,
+          webhook_action: webhookAction
+        }
+      };
+    }
+    case "issues": {
+      const issue = payload.issue;
+      return {
+        action: `issue_${webhookAction ?? "opened"}`,
+        repository: repoFullName,
+        actor,
+        metadata: {
+          issue_number: issue?.number,
+          labels: issue?.labels?.map((l) => l.name) ?? [],
+          webhook_action: webhookAction
+        }
+      };
+    }
+    case "issue_comment": {
+      return {
+        action: `issue_comment_${webhookAction ?? "created"}`,
+        repository: repoFullName,
+        actor,
+        metadata: {
+          issue_number: payload.issue?.number,
+          webhook_action: webhookAction
+        }
+      };
+    }
+    case "delete": {
+      return {
+        action: `delete_${payload.ref_type ?? "ref"}`,
+        repository: repoFullName,
+        ref: payload.ref,
+        actor,
+        metadata: {
+          ref_type: payload.ref_type
+        }
+      };
+    }
+    default: {
+      return {
+        action: webhookAction ? `${eventType}_${webhookAction}` : eventType,
+        repository: repoFullName,
+        actor,
+        metadata: { webhook_action: webhookAction }
+      };
+    }
+  }
+}
+var GitHubGovernor = class {
+  world;
+  options;
+  engineOptions;
+  activePlan;
+  protectedBranches;
+  restrictedActors;
+  mapFn;
+  constructor(world, options = {}) {
+    this.world = world;
+    this.options = options;
+    this.activePlan = options.plan;
+    this.engineOptions = buildEngineOptions(options, this.activePlan);
+    this.protectedBranches = options.protectedBranches ?? ["main", "master", "production"];
+    this.restrictedActors = options.restrictedActors ?? [];
+    this.mapFn = options.mapAction ?? ((action) => defaultMapAction(action, this.protectedBranches, this.restrictedActors));
+  }
+  /**
+   * Evaluate a GitHub action against governance rules.
+   * Returns a full result with verdict, event, and the original action.
+   */
+  evaluate(action) {
+    const event = this.mapFn(action);
+    this.engineOptions.plan = this.activePlan;
+    const verdict = evaluateGuard(event, this.world, this.engineOptions);
+    this.options.onEvaluate?.(verdict, event, action);
+    if (verdict.status === "ALLOW") {
+      trackPlanProgress(event, this, this.options);
+    }
+    return { verdict, event, action };
+  }
+  /**
+   * Evaluate and enforce — throws GitHubGovernanceBlockedError on BLOCK/PAUSE.
+   * Use this as a gate before executing GitHub API calls.
+   */
+  enforce(action) {
+    const result = this.evaluate(action);
+    if (result.verdict.status === "BLOCK" || result.verdict.status === "PAUSE") {
+      throw new GitHubGovernanceBlockedError(result.verdict, action);
+    }
+    return result;
+  }
+  /**
+   * Check if pushing to a branch is allowed.
+   * Convenience method for the most common governance check.
+   */
+  canPush(repository, branch, actor) {
+    return this.evaluate({
+      action: `push_to_${branch}`,
+      repository,
+      ref: `refs/heads/${branch}`,
+      branch,
+      actor
+    }).verdict;
+  }
+  /**
+   * Check if merging a PR is allowed.
+   */
+  canMerge(repository, targetBranch, prNumber, actor, labels) {
+    return this.evaluate({
+      action: "merge_pull_request",
+      repository,
+      branch: targetBranch,
+      actor,
+      metadata: { pr_number: prNumber, labels: labels ?? [] }
+    }).verdict;
+  }
+  /**
+   * Check if creating a release is allowed.
+   */
+  canRelease(repository, tag, actor, prerelease) {
+    return this.evaluate({
+      action: "release_published",
+      repository,
+      ref: `refs/tags/${tag}`,
+      actor,
+      metadata: { tag, prerelease: prerelease ?? false }
+    }).verdict;
+  }
+  /**
+   * Check if deploying to an environment is allowed.
+   */
+  canDeploy(repository, environment, ref, actor) {
+    return this.evaluate({
+      action: "create_deployment",
+      repository,
+      ref,
+      actor,
+      metadata: { environment }
+    }).verdict;
+  }
+};
+var GitHubWebhookHandler = class {
+  governor;
+  mapWebhookFn;
+  webhookSecret;
+  constructor(world, options = {}) {
+    this.governor = new GitHubGovernor(world, options);
+    this.mapWebhookFn = options.mapWebhook ?? defaultMapWebhook;
+    this.webhookSecret = options.webhookSecret;
+  }
+  /**
+   * Evaluate a webhook payload.
+   *
+   * @param eventType - The X-GitHub-Event header value
+   * @param payload - The parsed webhook body
+   */
+  evaluate(eventType, payload) {
+    const action = this.mapWebhookFn(eventType, payload);
+    const result = this.governor.evaluate(action);
+    return {
+      verdict: result.verdict,
+      event: result.event,
+      webhookEvent: eventType,
+      webhookAction: payload.action
+    };
+  }
+  /**
+   * Evaluate and enforce — throws on BLOCK/PAUSE.
+   */
+  enforce(eventType, payload) {
+    const result = this.evaluate(eventType, payload);
+    if (result.verdict.status === "BLOCK" || result.verdict.status === "PAUSE") {
+      const action = this.mapWebhookFn(eventType, payload);
+      throw new GitHubGovernanceBlockedError(result.verdict, action);
+    }
+    return result;
+  }
+  /** Access the underlying governor for direct action evaluation. */
+  getGovernor() {
+    return this.governor;
+  }
+  /** Get the configured webhook secret (for signature verification in your server). */
+  getWebhookSecret() {
+    return this.webhookSecret;
+  }
+};
+function formatForActions(verdict) {
+  const status = verdict.status === "ALLOW" ? "allowed" : verdict.status === "BLOCK" ? "blocked" : "paused";
+  const reason = verdict.reason ?? "";
+  const ruleId = verdict.ruleId ?? "";
+  const lines = [
+    `governance_status=${status}`,
+    `verdict_status=${verdict.status}`,
+    `reason=${reason}`,
+    `rule_id=${ruleId}`
+  ].join("\n");
+  return {
+    governance_status: status,
+    verdict_status: verdict.status,
+    reason,
+    rule_id: ruleId,
+    outputLines: lines
+  };
+}
+function formatPRComment(verdict, action) {
+  const icon = verdict.status === "ALLOW" ? "\u2705" : verdict.status === "BLOCK" ? "\u{1F6AB}" : "\u23F8\uFE0F";
+  const status = verdict.status;
+  let body = `## ${icon} Governance: ${status}
+
+`;
+  body += `**Action:** \`${action.action}\`
+`;
+  body += `**Repository:** \`${action.repository}\`
+`;
+  if (action.branch) {
+    body += `**Branch:** \`${action.branch}\`
+`;
+  }
+  if (action.actor) {
+    body += `**Actor:** \`${action.actor}\`
+`;
+  }
+  body += "\n";
+  if (verdict.reason) {
+    body += `**Reason:** ${verdict.reason}
+`;
+  }
+  if (verdict.ruleId) {
+    body += `**Rule:** \`${verdict.ruleId}\`
+`;
+  }
+  if (verdict.evidence?.invariantsSatisfied < verdict.evidence?.invariantsTotal) {
+    body += `**Invariants:** ${verdict.evidence.invariantsSatisfied}/${verdict.evidence.invariantsTotal} satisfied
+`;
+  }
+  body += "\n---\n*Evaluated by [NeuroVerse Governance](https://github.com/NeuroverseOS/neuroverseos-governance)*";
+  return body;
+}
+async function createGitHubGovernor(worldPath, options) {
+  const world = await loadWorld(worldPath);
+  return new GitHubGovernor(world, options);
+}
+function createGitHubGovernorFromWorld(world, options) {
+  return new GitHubGovernor(world, options);
+}
+async function createGitHubWebhookHandler(worldPath, options) {
+  const world = await loadWorld(worldPath);
+  return new GitHubWebhookHandler(world, options);
+}
+function createGitHubWebhookHandlerFromWorld(world, options) {
+  return new GitHubWebhookHandler(world, options);
+}
+
+export {
+  GitHubGovernanceBlockedError,
+  GitHubGovernor,
+  GitHubWebhookHandler,
+  formatForActions,
+  formatPRComment,
+  createGitHubGovernor,
+  createGitHubGovernorFromWorld,
+  createGitHubWebhookHandler,
+  createGitHubWebhookHandlerFromWorld
+};

package/dist/{chunk-VXHSMA3I.js → chunk-6CV4XG3J.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-INWQHLPS.js";
 import {
   evaluateGuard
-} from "./chunk-W7LLXRGY.js";
+} from "./chunk-ZAF6JH23.js";
 
 // src/engine/intent-classifier.ts
 function buildSystemPrompt(knownIntents) {

package/dist/{chunk-BNKJPUPQ.js → chunk-A7SHG75T.js}

@@ -6,10 +6,10 @@ import {
 } from "./chunk-5U2MQO5P.js";
 import {
   evaluateGuard
-} from "./chunk-W7LLXRGY.js";
+} from "./chunk-ZAF6JH23.js";
 import {
   loadWorld
-} from "./chunk-CTZHONLA.js";
+} from "./chunk-I4RTIMLX.js";
 
 // src/adapters/openclaw.ts
 var GovernanceBlockedError2 = class extends GovernanceBlockedError {

package/dist/{chunk-U6U7EJZL.js → chunk-AV7XJJWK.js}

@@ -1,9 +1,9 @@
 import {
   evaluateGuard
-} from "./chunk-W7LLXRGY.js";
+} from "./chunk-ZAF6JH23.js";
 import {
   loadWorld
-} from "./chunk-CTZHONLA.js";
+} from "./chunk-I4RTIMLX.js";
 
 // src/runtime/govern.ts
 function actionToGuardEvent(action) {

package/dist/{chunk-ZWI3NIXK.js → chunk-CYDMUJVZ.js}

@@ -20,15 +20,25 @@ function simulateWorld(world, options = {}) {
   let collapseStep;
   let collapseRule;
   const sortedRules = [...world.rules].sort((a, b) => a.order - b.order);
+  const allEvents = options.events ?? [];
+  const eventsByStep = Array.from({ length: steps }, () => []);
+  for (let i = 0; i < allEvents.length; i++) {
+    const stepIdx = Math.min(i, steps - 1);
+    eventsByStep[stepIdx].push(allEvents[i]);
+  }
+  let totalEventsConsumed = 0;
   for (let stepNum = 1; stepNum <= steps; stepNum++) {
     if (collapsed) break;
+    const stepEvents = eventsByStep[stepNum - 1];
     const stepResult = evaluateStep(
       stepNum,
       sortedRules,
       state,
       assumptions,
-      world
+      world,
+      stepEvents
     );
+    totalEventsConsumed += stepResult.eventsApplied.length;
     simulationSteps.push(stepResult);
     if (stepResult.collapsed) {
       collapsed = true;
@@ -47,14 +57,38 @@ function simulateWorld(world, options = {}) {
     finalViability,
     collapsed,
     collapseStep,
-    collapseRule
+    collapseRule,
+    eventsConsumed: totalEventsConsumed
   };
 }
-function evaluateStep(stepNum, rules, state, assumptions, world) {
+function evaluateStep(stepNum, rules, state, assumptions, world, events = []) {
   const evaluations = [];
+  const eventApplications = [];
   let rulesFired = 0;
   let collapsed = false;
   const firedRuleIds = /* @__PURE__ */ new Set();
+  for (const evt of events) {
+    const application = {
+      eventType: evt.type,
+      rulesTriggered: [],
+      effects: []
+    };
+    for (const rule of rules) {
+      const eventTrigger = rule.triggers.find(
+        (t) => t.field === "event" && t.source === "state"
+      );
+      if (!eventTrigger) continue;
+      const matches = evaluateOperator(evt.type, eventTrigger.operator, eventTrigger.value);
+      if (!matches) continue;
+      application.rulesTriggered.push(rule.id);
+      firedRuleIds.add(rule.id);
+      for (const effect of rule.effects ?? []) {
+        const applied = applyEffect(effect, state);
+        if (applied) application.effects.push(applied);
+      }
+    }
+    eventApplications.push(application);
+  }
   for (const rule of rules) {
     if (collapsed) {
       evaluations.push({
@@ -139,6 +173,7 @@ function evaluateStep(stepNum, rules, state, assumptions, world) {
   const viability = classifyViability(state, world);
   return {
     step: stepNum,
+    eventsApplied: eventApplications,
     rulesEvaluated: evaluations,
     rulesFired,
     stateAfter: { ...state },
@@ -260,6 +295,19 @@ function renderSimulateText(result) {
   lines.push("");
   for (const step of result.steps) {
     lines.push(`STEP ${step.step}`);
+    if (step.eventsApplied && step.eventsApplied.length > 0) {
+      for (const evt of step.eventsApplied) {
+        lines.push(`  EVENT: ${evt.eventType}`);
+        if (evt.rulesTriggered.length > 0) {
+          lines.push(`    Rules triggered: ${evt.rulesTriggered.join(", ")}`);
+        }
+        for (const effect of evt.effects) {
+          const beforeStr = formatValue(effect.before);
+          const afterStr = formatValue(effect.after);
+          lines.push(`    ${effect.target}: ${beforeStr} -> ${afterStr}`);
+        }
+      }
+    }
     const fired = step.rulesEvaluated.filter((r) => r.triggered);
     const skipped = step.rulesEvaluated.filter((r) => !r.triggered && !r.excluded);
     const excluded = step.rulesEvaluated.filter((r) => r.excluded);
@@ -295,6 +343,9 @@ function renderSimulateText(result) {
     lines.push(`  ${key}: ${formatValue(value)}${marker}`);
   }
   lines.push("");
+  if (result.eventsConsumed > 0) {
+    lines.push(`EVENTS CONSUMED: ${result.eventsConsumed}`);
+  }
   lines.push(`VIABILITY: ${result.finalViability}`);
   if (result.collapsed) {
     lines.push(`COLLAPSED at step ${result.collapseStep} (rule: ${result.collapseRule})`);

package/dist/{chunk-F66BVUYB.js → chunk-DA5MHFRR.js}

@@ -1,9 +1,9 @@
+import {
+  simulateWorld
+} from "./chunk-CYDMUJVZ.js";
 import {
   validateWorld
 } from "./chunk-7P3S7MAY.js";
-import {
-  simulateWorld
-} from "./chunk-ZWI3NIXK.js";
 
 // src/engine/improve-engine.ts
 function improveWorld(world) {

package/dist/{chunk-YEKMVDWK.js → chunk-FHXXD2TI.js}

@@ -1,18 +1,18 @@
-import {
-  loadConfig
-} from "./chunk-OT6PXH54.js";
 import {
   createProvider
 } from "./chunk-INWQHLPS.js";
+import {
+  loadConfig
+} from "./chunk-OT6PXH54.js";
 import {
   validateWorld
 } from "./chunk-7P3S7MAY.js";
-import {
-  parseWorldMarkdown
-} from "./chunk-EMQDLDAF.js";
 import {
   emitWorldDefinition
-} from "./chunk-PVTQQS3Y.js";
+} from "./chunk-YPCVY4GS.js";
+import {
+  parseWorldMarkdown
+} from "./chunk-3NZMMSOW.js";
 
 // src/engine/derive-normalizer.ts
 function findSections(lines) {

package/dist/{chunk-5TPFNWRU.js → chunk-FS2UUJJO.js}

@@ -35,7 +35,7 @@ async function addGuard(worldDir, input) {
   };
   config.guards.push(guard);
   await writeFile(guardsPath, JSON.stringify(config, null, 2) + "\n");
-  const { loadWorldFromDirectory } = await import("./world-loader-Y6HMQH2D.js");
+  const { loadWorldFromDirectory } = await import("./world-loader-YTYFOP7D.js");
   const world = await loadWorldFromDirectory(worldDir);
   const report = validateWorld(world);
   return {
@@ -83,7 +83,7 @@ async function addRule(worldDir, input) {
   };
   const rulePath = join(rulesDir, `rule-${ruleNum}.json`);
   await writeFile(rulePath, JSON.stringify(rule, null, 2) + "\n");
-  const { loadWorldFromDirectory } = await import("./world-loader-Y6HMQH2D.js");
+  const { loadWorldFromDirectory } = await import("./world-loader-YTYFOP7D.js");
   const world = await loadWorldFromDirectory(worldDir);
   const report = validateWorld(world);
   return {
@@ -118,7 +118,7 @@ async function addInvariant(worldDir, input) {
   };
   config.invariants.push(invariant);
   await writeFile(invariantsPath, JSON.stringify(config, null, 2) + "\n");
-  const { loadWorldFromDirectory } = await import("./world-loader-Y6HMQH2D.js");
+  const { loadWorldFromDirectory } = await import("./world-loader-YTYFOP7D.js");
   const world = await loadWorldFromDirectory(worldDir);
   const report = validateWorld(world);
   return {

package/dist/{chunk-4FLICVVA.js → chunk-FVOGUCB6.js}

@@ -7,10 +7,10 @@ import {
 } from "./chunk-5U2MQO5P.js";
 import {
   evaluateGuard
-} from "./chunk-W7LLXRGY.js";
+} from "./chunk-ZAF6JH23.js";
 import {
   loadWorld
-} from "./chunk-CTZHONLA.js";
+} from "./chunk-I4RTIMLX.js";
 
 // src/adapters/openai.ts
 var GovernanceBlockedError2 = class extends GovernanceBlockedError {