0xray 4.0.13 → 4.0.14

package/dist/postprocessor/integration.js

@@ -0,0 +1,194 @@
+/**
+ * 0xRay Integration Layer
+ *
+ * Provides generic connectors for integrating 0xRay's PostProcessor
+ * with external applications and frameworks.
+ *
+ * This is framework-agnostic - works with Express, Fastify, Koa, etc.
+ *
+ * @since 2026-03-08
+ */
+export { WebhookTrigger } from './triggers/WebhookTrigger.js';
+export { APITrigger } from './triggers/APITrigger.js';
+/**
+ * Generic 0xRay integration for any external application
+ *
+ * Provides:
+ * - Webhook receivers (GitHub, GitLab, Bitbucket, Stripe)
+ * - REST API triggers (manual trigger, retry, status)
+ * - Framework-agnostic (works with Express, Fastify, Koa, etc.)
+ *
+ * @example
+ * ```typescript
+ * import { createXrayIntegration } from '0xray/integration';
+ *
+ * const postProcessor = new PostProcessor(stateManager);
+ * const integration = createXrayIntegration(postProcessor);
+ *
+ * // Get Express app for mounting
+ * app.use('/webhooks', integration.getWebhookApp());
+ * app.use('/api/post-process', integration.getAPIApp());
+ *
+ * // Or get raw routers for Fastify/Koa
+ * const webhookRouter = integration.getWebhookRouter();
+ * const apiRouter = integration.getAPIRouter();
+ * ```
+ */
+export class XrayIntegration {
+    postProcessor;
+    webhookTrigger = null;
+    apiTrigger = null;
+    constructor(postProcessor) {
+        this.postProcessor = postProcessor;
+    }
+    /**
+     * Initialize all triggers with default configuration
+     *
+     * @param config - Optional configuration for triggers
+     */
+    async initialize(config) {
+        const { WebhookTrigger } = await import('./triggers/WebhookTrigger.js');
+        const { APITrigger } = await import('./triggers/APITrigger.js');
+        // Initialize webhook trigger with default GitHub config
+        this.webhookTrigger = new WebhookTrigger(this.postProcessor, {
+            provider: 'github',
+            events: ['push', 'pull_request'],
+            path: '/webhooks/github',
+            verifySignature: true,
+            ...config?.webhook
+        });
+        await this.webhookTrigger.initialize();
+        // Initialize API trigger with default config
+        this.apiTrigger = new APITrigger(this.postProcessor, {
+            enabled: true,
+            path: '/api/post-process',
+            ...config?.api
+        });
+        await this.apiTrigger.initialize();
+    }
+    /**
+     * Get webhook app for framework-specific mounting
+     *
+     * Returns an Express Application. For other frameworks,
+     * use getWebhookRouter() to get the router instance.
+     *
+     * @example
+     * ```typescript
+     * // Express
+     * app.use('/webhooks', integration.getWebhookApp());
+     *
+     * // Fastify
+     * await fastify.register(integration.getWebhookRouter(), { prefix: '/webhooks' });
+     *
+     * // Koa
+     * app.use(integration.getWebhookRouter().routes());
+     * ```
+     */
+    getWebhookApp() {
+        return this.webhookTrigger?.getApp() ?? null;
+    }
+    /**
+     * Get webhook router (raw Express router)
+     *
+     * Useful for frameworks that need the router instance directly
+     * rather than the full Express app.
+     */
+    getWebhookRouter() {
+        return this.webhookTrigger?.getApp() ?? null;
+    }
+    /**
+     * Get API trigger app for framework-specific mounting
+     *
+     * @example
+     * ```typescript
+     * // Express
+     * app.use('/api/post-process', integration.getAPIApp());
+     *
+     * // Fastify
+     * await fastify.register(integration.getAPIRouter(), { prefix: '/api/post-process' });
+     * ```
+     */
+    getAPIApp() {
+        return this.apiTrigger?.getApp() ?? null;
+    }
+    /**
+     * Get API trigger router (raw Express router)
+     *
+     * Useful for frameworks that need the router instance directly.
+     */
+    getAPIRouter() {
+        return this.apiTrigger?.getApp() ?? null;
+    }
+    /**
+     * Manually trigger PostProcessor via API
+     *
+     * Convenience method for programmatic triggering without
+     * going through the HTTP endpoint.
+     *
+     * @example
+     * ```typescript
+     * await integration.trigger({
+     *   tool: 'test',
+     *   operation: 'run',
+     *   reason: 'Manual test trigger'
+     * });
+     * ```
+     */
+    async trigger(options) {
+        const context = {
+            commitSha: `manual-${Date.now()}`,
+            repository: '',
+            branch: '',
+            author: 'manual',
+            files: [],
+            trigger: 'manual',
+            tool: options.tool,
+            operation: options.operation,
+            ...(options.filePath !== undefined ? { filePath: options.filePath } : {}),
+            ...(options.directory !== undefined ? { directory: options.directory } : {}),
+        };
+        await this.postProcessor.executePostProcessorLoop(context);
+    }
+    /**
+     * Shutdown all triggers
+     */
+    async shutdown() {
+        if (this.webhookTrigger) {
+            this.webhookTrigger.shutdown();
+        }
+        if (this.apiTrigger) {
+            this.apiTrigger.shutdown();
+        }
+    }
+}
+/**
+ * Factory function for easy integration setup
+ *
+ * @example
+ * ```typescript
+ * import { createXrayIntegration } from '0xray/integration';
+ *
+ * // With default configuration
+ * const integration = createXrayIntegration(postProcessor);
+ * await integration.initialize();
+ *
+ * // With custom configuration
+ * const integration = createXrayIntegration(postProcessor);
+ * await integration.initialize({
+ *   webhook: {
+ *     provider: 'gitlab',
+ *     secret: process.env.GITLAB_WEBHOOK_SECRET,
+ *     events: ['push', 'merge_request'],
+ *     path: '/webhooks/gitlab'
+ *   },
+ *   api: {
+ *     path: '/api/stray-trigger',
+ *     apiKey: process.env.API_KEY
+ *   }
+ * });
+ * ```
+ */
+export function createXrayIntegration(postProcessor) {
+    return new XrayIntegration(postProcessor);
+}
+// Backward compat aliases

package/dist/postprocessor/metamorphosis/SelfProposalEngine.d.ts

@@ -0,0 +1,87 @@
+/**
+ * SelfProposalEngine — Phase 2.2
+ *
+ * Concrete MetamorphosisEngine that reads activity.log, parses structured
+ * log entries, detects semantic patterns, generates governance proposals
+ * (type: 'metamorphosis'), and submits them through the full 3-agent +
+ * Dynamo governance pipeline.
+ *
+ * Safety constraints:
+ * - Max proposals per hour (default 1, configurable)
+ * - Circuit breaker: after N consecutive failures, halt for cooldown (default 3/24h)
+ * - Only proposes changes to whitelisted targets
+ * - All proposals go through full governance with metamorphosisThreshold (default 0.7)
+ * - Detection thresholds are configurable (not hard-coded)
+ *
+ * Coupling note: currently triggered by PostProcessor.onPhase(). A future
+ * refactor should extract log-reading into a dedicated LogReader that can
+ * run on its own schedule or fs.watch, decoupling from PostProcessor lifecycle.
+ */
+import type { MetamorphosisEngine, MetamorphosisProposal } from '../../types/metamorphosis.js';
+export interface SelfProposalConfig {
+    maxProposalsPerHour?: number;
+    circuitBreakerThreshold?: number;
+    circuitBreakerCooldownHours?: number;
+    activityLogPath?: string;
+    whitelistedTargets?: string[];
+    /** Number of recent log lines to analyze (default: 100) */
+    maxLogLines?: number;
+    /** Minimum error entries to trigger an error-handling proposal (default: 5) */
+    errorThreshold?: number;
+    /** Minimum warning entries to trigger a monitoring proposal (default: 10) */
+    warningThreshold?: number;
+    /** Minimum governance rejections of same type to trigger a pattern proposal (default: 3) */
+    governanceRejectionThreshold?: number;
+    /** Minimum confidence for generated proposals (default: 0.7) */
+    proposalConfidence?: number;
+    /** Metamorphosis score threshold for approval (default: 0.7) */
+    metamorphosisThreshold?: number;
+    /** Project root for resolving whitelisted target paths (default: process.cwd()) */
+    projectRoot?: string;
+}
+export interface SelfEvolutionMetrics {
+    totalProposals: number;
+    recentProposals: number;
+    consecutiveFailures: number;
+    circuitBreakerActive: boolean;
+    circuitBreakerUntil: number;
+    successRate: number;
+}
+export declare class SelfProposalEngine implements MetamorphosisEngine {
+    readonly name = "self-proposal";
+    private config;
+    private proposalHistory;
+    private consecutiveFailures;
+    private circuitBreakerUntil;
+    constructor(config?: SelfProposalConfig);
+    onPhase(phase: string, context: unknown): Promise<void>;
+    onProposal(proposal: MetamorphosisProposal): Promise<void>;
+    private isCircuitBreakerActive;
+    private isRateLimited;
+    getMetrics(): SelfEvolutionMetrics;
+    private evaluateAndPropose;
+    /**
+     * Detect actionable patterns from parsed activity log entries.
+     * Uses structured parsing instead of raw string matching to handle
+     * the actual xray log format:
+     *   ISO_TIMESTAMP [jobId] [traceId.spanId] [component] action - STATUS | {details}
+     */
+    detectPatterns(entries: string[]): MetamorphosisProposal[];
+    /**
+     * Apply an approved self-evolution proposal by recording the change
+     * in a state file within the first matching whitelisted target directory.
+     * Returns true if the change was written and verified, false otherwise.
+     */
+    private applySelfProposal;
+    private submitProposal;
+    /**
+     * Post-apply audit for Term 72 (Self-Evolution Traceability).
+     * For 0xray-tagged proposals (framework self-evolution), asserts that
+     * frameworkLogger entries exist with full provenance:
+     *   - source proposal ID
+     *   - governance vote results / finalDecision / averageConfidence
+     *   - metamorphosisScore
+     * Logs the audit outcome via frameworkLogger.
+     */
+    private audit0xrayProposalTraceability;
+}