@neuroverseos/governance 0.5.0 → 0.6.0

package/dist/adapters/github.d.cts

@@ -0,0 +1,225 @@
+import { G as GuardVerdict, a as GuardEvent, b as GuardEngineOptions, P as PlanDefinition, c as PlanProgress } from '../guard-contract-ddiIPlOg.cjs';
+import { WorldDefinition } from '../types.cjs';
+import { G as GovernanceBlockedError } from '../shared-PpalGKxc.cjs';
+
+/**
+ * NeuroVerse Adapter — GitHub
+ *
+ * Governance middleware for GitHub-driven workflows. Evaluates GitHub events
+ * (PRs, issues, comments, pushes, releases, workflow runs) against world rules
+ * before allowing actions to proceed.
+ *
+ * Two modes:
+ *   1. Webhook mode — receives GitHub webhook payloads, evaluates, returns verdict
+ *   2. Action mode — wraps Octokit/GitHub API calls with governance checks
+ *
+ * Usage (Webhook):
+ *   import { createGitHubWebhookHandler } from 'neuroverse-governance/adapters/github';
+ *
+ *   const handler = await createGitHubWebhookHandler('./world/');
+ *   app.post('/webhook', async (req, res) => {
+ *     const verdict = handler.evaluate(req.headers['x-github-event'], req.body);
+ *     if (verdict.status === 'BLOCK') return res.status(403).json({ blocked: true });
+ *     // proceed with webhook processing...
+ *   });
+ *
+ * Usage (Action):
+ *   import { createGitHubGovernor } from 'neuroverse-governance/adapters/github';
+ *
+ *   const gov = await createGitHubGovernor('./world/');
+ *
+ *   // Before merging a PR:
+ *   const verdict = gov.evaluate({
+ *     action: 'merge_pull_request',
+ *     repository: 'myorg/myrepo',
+ *     ref: 'refs/heads/main',
+ *     actor: 'dependabot[bot]',
+ *     metadata: { pr_number: 42, labels: ['auto-merge'] },
+ *   });
+ *
+ *   if (verdict.status === 'ALLOW') await octokit.pulls.merge(...);
+ */
+
+/** GitHub webhook event names the adapter understands. */
+type GitHubWebhookEvent = 'push' | 'pull_request' | 'pull_request_review' | 'issues' | 'issue_comment' | 'release' | 'workflow_run' | 'workflow_dispatch' | 'check_run' | 'check_suite' | 'deployment' | 'deployment_status' | 'create' | 'delete' | 'fork' | 'member' | 'repository' | 'status' | string;
+/** A structured GitHub action to evaluate against governance. */
+interface GitHubAction {
+    /** What the actor wants to do (e.g., 'merge_pull_request', 'push_to_main', 'create_release'). */
+    action: string;
+    /** Full repository name (e.g., 'myorg/myrepo'). */
+    repository: string;
+    /** Git ref involved (e.g., 'refs/heads/main', 'refs/tags/v1.0.0'). */
+    ref?: string;
+    /** GitHub username or bot performing the action. */
+    actor?: string;
+    /** Branch being targeted (extracted from ref or PR base). */
+    branch?: string;
+    /** Additional context for guard evaluation. */
+    metadata?: Record<string, unknown>;
+}
+/** Result of evaluating a GitHub action. */
+interface GitHubGovernanceResult {
+    /** The guard verdict. */
+    verdict: GuardVerdict;
+    /** The GuardEvent that was evaluated (for audit/logging). */
+    event: GuardEvent;
+    /** The original action that triggered evaluation. */
+    action: GitHubAction;
+}
+/** Result of evaluating a webhook payload. */
+interface WebhookGovernanceResult {
+    /** The guard verdict. */
+    verdict: GuardVerdict;
+    /** The GuardEvent that was evaluated. */
+    event: GuardEvent;
+    /** The webhook event type. */
+    webhookEvent: string;
+    /** The webhook action (e.g., 'opened', 'closed', 'merged'). */
+    webhookAction?: string;
+}
+interface GitHubGovernorOptions {
+    /** Include full evaluation trace in verdicts. Default: false. */
+    trace?: boolean;
+    /** Enforcement level override. */
+    level?: 'basic' | 'standard' | 'strict';
+    /** Called for every evaluation (logging/audit hook). */
+    onEvaluate?: (verdict: GuardVerdict, event: GuardEvent, action: GitHubAction) => void;
+    /** Custom mapping from GitHubAction to GuardEvent. */
+    mapAction?: (action: GitHubAction) => GuardEvent;
+    /** Active plan overlay for task-scoped governance. */
+    plan?: PlanDefinition;
+    /** Called when plan progress changes. */
+    onPlanProgress?: (progress: PlanProgress) => void;
+    /** Called when all plan steps are completed. */
+    onPlanComplete?: () => void;
+    /** Protected branches that require strict governance. Default: ['main', 'master', 'production']. */
+    protectedBranches?: string[];
+    /** Actors (bots, users) with restricted permissions. */
+    restrictedActors?: string[];
+}
+interface WebhookHandlerOptions extends GitHubGovernorOptions {
+    /** Webhook secret for signature verification (HMAC-SHA256). */
+    webhookSecret?: string;
+    /** Custom mapping from webhook payload to GitHubAction. */
+    mapWebhook?: (eventType: string, payload: Record<string, unknown>) => GitHubAction;
+}
+declare class GitHubGovernanceBlockedError extends GovernanceBlockedError {
+    readonly action: GitHubAction;
+    constructor(verdict: GuardVerdict, action: GitHubAction);
+}
+/**
+ * Evaluates GitHub actions against a NeuroVerse world.
+ * Use this when you're making GitHub API calls and want governance
+ * to approve/block them before execution.
+ */
+declare class GitHubGovernor {
+    private world;
+    private options;
+    engineOptions: GuardEngineOptions;
+    activePlan?: PlanDefinition;
+    private protectedBranches;
+    private restrictedActors;
+    private mapFn;
+    constructor(world: WorldDefinition, options?: GitHubGovernorOptions);
+    /**
+     * Evaluate a GitHub action against governance rules.
+     * Returns a full result with verdict, event, and the original action.
+     */
+    evaluate(action: GitHubAction): GitHubGovernanceResult;
+    /**
+     * Evaluate and enforce — throws GitHubGovernanceBlockedError on BLOCK/PAUSE.
+     * Use this as a gate before executing GitHub API calls.
+     */
+    enforce(action: GitHubAction): GitHubGovernanceResult;
+    /**
+     * Check if pushing to a branch is allowed.
+     * Convenience method for the most common governance check.
+     */
+    canPush(repository: string, branch: string, actor?: string): GuardVerdict;
+    /**
+     * Check if merging a PR is allowed.
+     */
+    canMerge(repository: string, targetBranch: string, prNumber: number, actor?: string, labels?: string[]): GuardVerdict;
+    /**
+     * Check if creating a release is allowed.
+     */
+    canRelease(repository: string, tag: string, actor?: string, prerelease?: boolean): GuardVerdict;
+    /**
+     * Check if deploying to an environment is allowed.
+     */
+    canDeploy(repository: string, environment: string, ref?: string, actor?: string): GuardVerdict;
+}
+/**
+ * Evaluates incoming GitHub webhook payloads against a NeuroVerse world.
+ * Use this in your webhook endpoint to govern repository events.
+ */
+declare class GitHubWebhookHandler {
+    private governor;
+    private mapWebhookFn;
+    private webhookSecret?;
+    constructor(world: WorldDefinition, options?: WebhookHandlerOptions);
+    /**
+     * Evaluate a webhook payload.
+     *
+     * @param eventType - The X-GitHub-Event header value
+     * @param payload - The parsed webhook body
+     */
+    evaluate(eventType: string, payload: Record<string, unknown>): WebhookGovernanceResult;
+    /**
+     * Evaluate and enforce — throws on BLOCK/PAUSE.
+     */
+    enforce(eventType: string, payload: Record<string, unknown>): WebhookGovernanceResult;
+    /** Access the underlying governor for direct action evaluation. */
+    getGovernor(): GitHubGovernor;
+    /** Get the configured webhook secret (for signature verification in your server). */
+    getWebhookSecret(): string | undefined;
+}
+/**
+ * Guard evaluation result formatted for GitHub Actions output.
+ * Set step outputs and write to $GITHUB_OUTPUT.
+ */
+interface ActionsOutput {
+    /** 'allowed' or 'blocked' or 'paused' — for use in step conditions */
+    governance_status: string;
+    /** The full verdict status */
+    verdict_status: string;
+    /** Reason for block/pause (empty string if allowed) */
+    reason: string;
+    /** Matched rule ID (empty string if none) */
+    rule_id: string;
+    /** Formatted as GITHUB_OUTPUT lines */
+    outputLines: string;
+}
+/**
+ * Format a verdict for GitHub Actions step outputs.
+ * Write the .outputLines to $GITHUB_OUTPUT in your action.
+ *
+ * Usage in a GitHub Action:
+ *   const result = governor.evaluate(action);
+ *   const output = formatForActions(result.verdict);
+ *   fs.appendFileSync(process.env.GITHUB_OUTPUT!, output.outputLines);
+ */
+declare function formatForActions(verdict: GuardVerdict): ActionsOutput;
+/**
+ * Create a PR comment body from a governance verdict.
+ * Useful for posting governance status as a PR comment.
+ */
+declare function formatPRComment(verdict: GuardVerdict, action: GitHubAction): string;
+/**
+ * Create a GitHub Governor from a world path.
+ */
+declare function createGitHubGovernor(worldPath: string, options?: GitHubGovernorOptions): Promise<GitHubGovernor>;
+/**
+ * Create a GitHub Governor from a pre-loaded world.
+ */
+declare function createGitHubGovernorFromWorld(world: WorldDefinition, options?: GitHubGovernorOptions): GitHubGovernor;
+/**
+ * Create a GitHub Webhook Handler from a world path.
+ */
+declare function createGitHubWebhookHandler(worldPath: string, options?: WebhookHandlerOptions): Promise<GitHubWebhookHandler>;
+/**
+ * Create a GitHub Webhook Handler from a pre-loaded world.
+ */
+declare function createGitHubWebhookHandlerFromWorld(world: WorldDefinition, options?: WebhookHandlerOptions): GitHubWebhookHandler;
+
+export { type ActionsOutput, type GitHubAction, GitHubGovernanceBlockedError, type GitHubGovernanceResult, GitHubGovernor, type GitHubGovernorOptions, type GitHubWebhookEvent, GitHubWebhookHandler, type WebhookGovernanceResult, type WebhookHandlerOptions, createGitHubGovernor, createGitHubGovernorFromWorld, createGitHubWebhookHandler, createGitHubWebhookHandlerFromWorld, formatForActions, formatPRComment };

package/dist/adapters/github.d.ts

@@ -0,0 +1,225 @@
+import { G as GuardVerdict, a as GuardEvent, b as GuardEngineOptions, P as PlanDefinition, c as PlanProgress } from '../guard-contract-q6HJAq3Q.js';
+import { WorldDefinition } from '../types.js';
+import { G as GovernanceBlockedError } from '../shared-DAzdfWtU.js';
+
+/**
+ * NeuroVerse Adapter — GitHub
+ *
+ * Governance middleware for GitHub-driven workflows. Evaluates GitHub events
+ * (PRs, issues, comments, pushes, releases, workflow runs) against world rules
+ * before allowing actions to proceed.
+ *
+ * Two modes:
+ *   1. Webhook mode — receives GitHub webhook payloads, evaluates, returns verdict
+ *   2. Action mode — wraps Octokit/GitHub API calls with governance checks
+ *
+ * Usage (Webhook):
+ *   import { createGitHubWebhookHandler } from 'neuroverse-governance/adapters/github';
+ *
+ *   const handler = await createGitHubWebhookHandler('./world/');
+ *   app.post('/webhook', async (req, res) => {
+ *     const verdict = handler.evaluate(req.headers['x-github-event'], req.body);
+ *     if (verdict.status === 'BLOCK') return res.status(403).json({ blocked: true });
+ *     // proceed with webhook processing...
+ *   });
+ *
+ * Usage (Action):
+ *   import { createGitHubGovernor } from 'neuroverse-governance/adapters/github';
+ *
+ *   const gov = await createGitHubGovernor('./world/');
+ *
+ *   // Before merging a PR:
+ *   const verdict = gov.evaluate({
+ *     action: 'merge_pull_request',
+ *     repository: 'myorg/myrepo',
+ *     ref: 'refs/heads/main',
+ *     actor: 'dependabot[bot]',
+ *     metadata: { pr_number: 42, labels: ['auto-merge'] },
+ *   });
+ *
+ *   if (verdict.status === 'ALLOW') await octokit.pulls.merge(...);
+ */
+
+/** GitHub webhook event names the adapter understands. */
+type GitHubWebhookEvent = 'push' | 'pull_request' | 'pull_request_review' | 'issues' | 'issue_comment' | 'release' | 'workflow_run' | 'workflow_dispatch' | 'check_run' | 'check_suite' | 'deployment' | 'deployment_status' | 'create' | 'delete' | 'fork' | 'member' | 'repository' | 'status' | string;
+/** A structured GitHub action to evaluate against governance. */
+interface GitHubAction {
+    /** What the actor wants to do (e.g., 'merge_pull_request', 'push_to_main', 'create_release'). */
+    action: string;
+    /** Full repository name (e.g., 'myorg/myrepo'). */
+    repository: string;
+    /** Git ref involved (e.g., 'refs/heads/main', 'refs/tags/v1.0.0'). */
+    ref?: string;
+    /** GitHub username or bot performing the action. */
+    actor?: string;
+    /** Branch being targeted (extracted from ref or PR base). */
+    branch?: string;
+    /** Additional context for guard evaluation. */
+    metadata?: Record<string, unknown>;
+}
+/** Result of evaluating a GitHub action. */
+interface GitHubGovernanceResult {
+    /** The guard verdict. */
+    verdict: GuardVerdict;
+    /** The GuardEvent that was evaluated (for audit/logging). */
+    event: GuardEvent;
+    /** The original action that triggered evaluation. */
+    action: GitHubAction;
+}
+/** Result of evaluating a webhook payload. */
+interface WebhookGovernanceResult {
+    /** The guard verdict. */
+    verdict: GuardVerdict;
+    /** The GuardEvent that was evaluated. */
+    event: GuardEvent;
+    /** The webhook event type. */
+    webhookEvent: string;
+    /** The webhook action (e.g., 'opened', 'closed', 'merged'). */
+    webhookAction?: string;
+}
+interface GitHubGovernorOptions {
+    /** Include full evaluation trace in verdicts. Default: false. */
+    trace?: boolean;
+    /** Enforcement level override. */
+    level?: 'basic' | 'standard' | 'strict';
+    /** Called for every evaluation (logging/audit hook). */
+    onEvaluate?: (verdict: GuardVerdict, event: GuardEvent, action: GitHubAction) => void;
+    /** Custom mapping from GitHubAction to GuardEvent. */
+    mapAction?: (action: GitHubAction) => GuardEvent;
+    /** Active plan overlay for task-scoped governance. */
+    plan?: PlanDefinition;
+    /** Called when plan progress changes. */
+    onPlanProgress?: (progress: PlanProgress) => void;
+    /** Called when all plan steps are completed. */
+    onPlanComplete?: () => void;
+    /** Protected branches that require strict governance. Default: ['main', 'master', 'production']. */
+    protectedBranches?: string[];
+    /** Actors (bots, users) with restricted permissions. */
+    restrictedActors?: string[];
+}
+interface WebhookHandlerOptions extends GitHubGovernorOptions {
+    /** Webhook secret for signature verification (HMAC-SHA256). */
+    webhookSecret?: string;
+    /** Custom mapping from webhook payload to GitHubAction. */
+    mapWebhook?: (eventType: string, payload: Record<string, unknown>) => GitHubAction;
+}
+declare class GitHubGovernanceBlockedError extends GovernanceBlockedError {
+    readonly action: GitHubAction;
+    constructor(verdict: GuardVerdict, action: GitHubAction);
+}
+/**
+ * Evaluates GitHub actions against a NeuroVerse world.
+ * Use this when you're making GitHub API calls and want governance
+ * to approve/block them before execution.
+ */
+declare class GitHubGovernor {
+    private world;
+    private options;
+    engineOptions: GuardEngineOptions;
+    activePlan?: PlanDefinition;
+    private protectedBranches;
+    private restrictedActors;
+    private mapFn;
+    constructor(world: WorldDefinition, options?: GitHubGovernorOptions);
+    /**
+     * Evaluate a GitHub action against governance rules.
+     * Returns a full result with verdict, event, and the original action.
+     */
+    evaluate(action: GitHubAction): GitHubGovernanceResult;
+    /**
+     * Evaluate and enforce — throws GitHubGovernanceBlockedError on BLOCK/PAUSE.
+     * Use this as a gate before executing GitHub API calls.
+     */
+    enforce(action: GitHubAction): GitHubGovernanceResult;
+    /**
+     * Check if pushing to a branch is allowed.
+     * Convenience method for the most common governance check.
+     */
+    canPush(repository: string, branch: string, actor?: string): GuardVerdict;
+    /**
+     * Check if merging a PR is allowed.
+     */
+    canMerge(repository: string, targetBranch: string, prNumber: number, actor?: string, labels?: string[]): GuardVerdict;
+    /**
+     * Check if creating a release is allowed.
+     */
+    canRelease(repository: string, tag: string, actor?: string, prerelease?: boolean): GuardVerdict;
+    /**
+     * Check if deploying to an environment is allowed.
+     */
+    canDeploy(repository: string, environment: string, ref?: string, actor?: string): GuardVerdict;
+}
+/**
+ * Evaluates incoming GitHub webhook payloads against a NeuroVerse world.
+ * Use this in your webhook endpoint to govern repository events.
+ */
+declare class GitHubWebhookHandler {
+    private governor;
+    private mapWebhookFn;
+    private webhookSecret?;
+    constructor(world: WorldDefinition, options?: WebhookHandlerOptions);
+    /**
+     * Evaluate a webhook payload.
+     *
+     * @param eventType - The X-GitHub-Event header value
+     * @param payload - The parsed webhook body
+     */
+    evaluate(eventType: string, payload: Record<string, unknown>): WebhookGovernanceResult;
+    /**
+     * Evaluate and enforce — throws on BLOCK/PAUSE.
+     */
+    enforce(eventType: string, payload: Record<string, unknown>): WebhookGovernanceResult;
+    /** Access the underlying governor for direct action evaluation. */
+    getGovernor(): GitHubGovernor;
+    /** Get the configured webhook secret (for signature verification in your server). */
+    getWebhookSecret(): string | undefined;
+}
+/**
+ * Guard evaluation result formatted for GitHub Actions output.
+ * Set step outputs and write to $GITHUB_OUTPUT.
+ */
+interface ActionsOutput {
+    /** 'allowed' or 'blocked' or 'paused' — for use in step conditions */
+    governance_status: string;
+    /** The full verdict status */
+    verdict_status: string;
+    /** Reason for block/pause (empty string if allowed) */
+    reason: string;
+    /** Matched rule ID (empty string if none) */
+    rule_id: string;
+    /** Formatted as GITHUB_OUTPUT lines */
+    outputLines: string;
+}
+/**
+ * Format a verdict for GitHub Actions step outputs.
+ * Write the .outputLines to $GITHUB_OUTPUT in your action.
+ *
+ * Usage in a GitHub Action:
+ *   const result = governor.evaluate(action);
+ *   const output = formatForActions(result.verdict);
+ *   fs.appendFileSync(process.env.GITHUB_OUTPUT!, output.outputLines);
+ */
+declare function formatForActions(verdict: GuardVerdict): ActionsOutput;
+/**
+ * Create a PR comment body from a governance verdict.
+ * Useful for posting governance status as a PR comment.
+ */
+declare function formatPRComment(verdict: GuardVerdict, action: GitHubAction): string;
+/**
+ * Create a GitHub Governor from a world path.
+ */
+declare function createGitHubGovernor(worldPath: string, options?: GitHubGovernorOptions): Promise<GitHubGovernor>;
+/**
+ * Create a GitHub Governor from a pre-loaded world.
+ */
+declare function createGitHubGovernorFromWorld(world: WorldDefinition, options?: GitHubGovernorOptions): GitHubGovernor;
+/**
+ * Create a GitHub Webhook Handler from a world path.
+ */
+declare function createGitHubWebhookHandler(worldPath: string, options?: WebhookHandlerOptions): Promise<GitHubWebhookHandler>;
+/**
+ * Create a GitHub Webhook Handler from a pre-loaded world.
+ */
+declare function createGitHubWebhookHandlerFromWorld(world: WorldDefinition, options?: WebhookHandlerOptions): GitHubWebhookHandler;
+
+export { type ActionsOutput, type GitHubAction, GitHubGovernanceBlockedError, type GitHubGovernanceResult, GitHubGovernor, type GitHubGovernorOptions, type GitHubWebhookEvent, GitHubWebhookHandler, type WebhookGovernanceResult, type WebhookHandlerOptions, createGitHubGovernor, createGitHubGovernorFromWorld, createGitHubWebhookHandler, createGitHubWebhookHandlerFromWorld, formatForActions, formatPRComment };

package/dist/adapters/github.js

@@ -0,0 +1,27 @@
+import {
+  GitHubGovernanceBlockedError,
+  GitHubGovernor,
+  GitHubWebhookHandler,
+  createGitHubGovernor,
+  createGitHubGovernorFromWorld,
+  createGitHubWebhookHandler,
+  createGitHubWebhookHandlerFromWorld,
+  formatForActions,
+  formatPRComment
+} from "../chunk-A2UZTLRV.js";
+import "../chunk-5U2MQO5P.js";
+import "../chunk-I4RTIMLX.js";
+import "../chunk-ZAF6JH23.js";
+import "../chunk-QLPTHTVB.js";
+import "../chunk-QWGCMQQD.js";
+export {
+  GitHubGovernanceBlockedError,
+  GitHubGovernor,
+  GitHubWebhookHandler,
+  createGitHubGovernor,
+  createGitHubGovernorFromWorld,
+  createGitHubWebhookHandler,
+  createGitHubWebhookHandlerFromWorld,
+  formatForActions,
+  formatPRComment
+};