@neuroverseos/governance 0.4.0 → 0.4.2

package/dist/index.cjs

@@ -949,6 +949,9 @@ __export(index_exports, {
   DERIVE_EXIT_CODES: () => DERIVE_EXIT_CODES,
   FileAuditLogger: () => FileAuditLogger,
   GUARD_EXIT_CODES: () => GUARD_EXIT_CODES,
+  GitHubGovernanceBlockedError: () => GitHubGovernanceBlockedError,
+  GitHubGovernor: () => GitHubGovernor,
+  GitHubWebhookHandler: () => GitHubWebhookHandler,
   McpGovernanceServer: () => McpGovernanceServer,
   ModelAdapter: () => ModelAdapter,
   PLAN_EXIT_CODES: () => PLAN_EXIT_CODES,
@@ -968,6 +971,10 @@ __export(index_exports, {
   classifyIntent: () => classifyIntent,
   classifyIntentWithAI: () => classifyIntentWithAI,
   createAgentState: () => createAgentState,
+  createGitHubGovernor: () => createGitHubGovernor,
+  createGitHubGovernorFromWorld: () => createGitHubGovernorFromWorld,
+  createGitHubWebhookHandler: () => createGitHubWebhookHandler,
+  createGitHubWebhookHandlerFromWorld: () => createGitHubWebhookHandlerFromWorld,
   createGovernanceEngine: () => createGovernanceEngine,
   createGovernor: () => createGovernor,
   deriveWorld: () => deriveWorld,
@@ -982,6 +989,8 @@ __export(index_exports, {
   explainWorld: () => explainWorld,
   extractContentFields: () => extractContentFields,
   extractWorldMarkdown: () => extractWorldMarkdown,
+  formatForActions: () => formatForActions,
+  formatPRComment: () => formatPRComment,
   formatVerdict: () => formatVerdict,
   formatVerdictOneLine: () => formatVerdictOneLine,
   generateAdaptationNarrative: () => generateAdaptationNarrative,
@@ -7803,6 +7812,440 @@ function round(n, decimals = 3) {
   return Math.round(n * factor) / factor;
 }
 
+// src/adapters/github.ts
+init_world_loader();
+
+// src/adapters/shared.ts
+var GovernanceBlockedError = class extends Error {
+  verdict;
+  constructor(verdict, message) {
+    super(message ?? `[NeuroVerse] BLOCKED: ${verdict.reason ?? verdict.ruleId ?? "governance rule"}`);
+    this.name = "GovernanceBlockedError";
+    this.verdict = verdict;
+  }
+};
+function trackPlanProgress(event, state, callbacks) {
+  if (!state.activePlan) return;
+  const planVerdict = evaluatePlan(event, state.activePlan);
+  if (planVerdict.matchedStep) {
+    const advResult = advancePlan(state.activePlan, planVerdict.matchedStep);
+    if (advResult.success && advResult.plan) {
+      state.activePlan = advResult.plan;
+      state.engineOptions.plan = state.activePlan;
+    }
+    const progress = getPlanProgress(state.activePlan);
+    callbacks.onPlanProgress?.(progress);
+    if (progress.completed === progress.total) {
+      callbacks.onPlanComplete?.();
+    }
+  }
+}
+function buildEngineOptions(options, plan) {
+  return {
+    trace: options.trace ?? false,
+    level: options.level,
+    plan: plan ?? options.plan
+  };
+}
+
+// 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);
+}
+
 // src/engine/api.ts
 init_world_loader();
 function handleHealthCheck() {
@@ -7879,6 +8322,9 @@ function handleCreateCapsule(body) {
   DERIVE_EXIT_CODES,
   FileAuditLogger,
   GUARD_EXIT_CODES,
+  GitHubGovernanceBlockedError,
+  GitHubGovernor,
+  GitHubWebhookHandler,
   McpGovernanceServer,
   ModelAdapter,
   PLAN_EXIT_CODES,
@@ -7898,6 +8344,10 @@ function handleCreateCapsule(body) {
   classifyIntent,
   classifyIntentWithAI,
   createAgentState,
+  createGitHubGovernor,
+  createGitHubGovernorFromWorld,
+  createGitHubWebhookHandler,
+  createGitHubWebhookHandlerFromWorld,
   createGovernanceEngine,
   createGovernor,
   deriveWorld,
@@ -7912,6 +8362,8 @@ function handleCreateCapsule(body) {
   explainWorld,
   extractContentFields,
   extractWorldMarkdown,
+  formatForActions,
+  formatPRComment,
   formatVerdict,
   formatVerdictOneLine,
   generateAdaptationNarrative,