0xray 3.4.2 → 3.4.3

package/dist/postprocessor/PostProcessor.d.ts

@@ -0,0 +1,107 @@
+/**
+ * 0xRay Post-Processor - Core Infrastructure
+ *
+ * Automated CI/CD loop orchestration: commit → push → monitor → fix → redeploy → monitor
+ * Provides systematic error prevention and deployment automation.
+ *
+ * @since 2026-01-13
+ */
+import { XrayStateManager } from "../state/state-manager.js";
+import { SessionMonitor } from "../session/session-monitor.js";
+import { PostProcessorConfig, PostProcessorResult, PostProcessorContext } from "./types.js";
+export declare class PostProcessor {
+    private stateManager;
+    private sessionMonitor;
+    private config;
+    private monitoringEngine;
+    private failureAnalysisEngine;
+    private autoFixEngine;
+    private fixValidator;
+    private reportValidator;
+    private regressionAnalysisService;
+    private redeployCoordinator;
+    private escalationEngine;
+    private successHandler;
+    private triggers;
+    constructor(stateManager: XrayStateManager, sessionMonitor?: SessionMonitor | null, config?: Partial<PostProcessorConfig>);
+    /**
+     * Generate automated framework report if conditions are met
+     */
+    private generateFrameworkReport;
+    /**
+     * Validate generated reports for hidden issues
+     */
+    private validateGeneratedReport;
+    /**
+     * Clean up old reports based on retention policy
+     */
+    private cleanupOldReports;
+    /**
+     * Analyze code changes to provide meaningful context to processors
+     * FIX: Issue #1 - Pass actual code analysis to processors
+     */
+    private analyzeCodeChanges;
+    /**
+     * Load processor configuration from features.json
+     * FIX: Issue #2 - Make processor registration configurable
+     */
+    private loadProcessorConfig;
+    /**
+     * Initialize the post-processor system
+     */
+    initialize(): Promise<void>;
+    /**
+     * Validate architectural compliance against codex rules
+     */
+    private validateArchitecturalCompliance;
+    private checkSystemIntegrity;
+    private checkIntegrationTesting;
+    private checkPathResolution;
+    private checkFeatureCompleteness;
+    /**
+     * Rule 50: Path Analysis Guidelines Enforcement
+     * Ensures AIs follow path resolution guidelines for all write/edit operations
+     * Covers all 3 types of path violations from PATH_RESOLUTION_ANALYSIS.md
+     */
+    private checkPathAnalysisGuidelines;
+    /**
+     * Execute the complete post-processor loop
+     */
+    executePostProcessorLoop(context: PostProcessorContext): Promise<PostProcessorResult>;
+    /**
+     * Execute the monitoring loop until success or max attempts
+     */
+    private executeMonitoringLoop;
+    /**
+     * Redeploy after applying fixes using the RedeployCoordinator
+     */
+    private redeployWithFixes;
+    /**
+     * Attempt to apply automatic fixes
+     */
+    private attemptAutoFix;
+    /**
+     * Escalate to manual intervention
+     */
+    private escalateToManualIntervention;
+    /**
+     * Wait before retry with exponential backoff
+     */
+    private waitBeforeRetry;
+    /**
+     * Get post-processor status
+     */
+    getStatus(): Promise<any>;
+    /**
+     * Call appropriate agent/skill to fix architectural compliance violations
+     */
+    private callAgentForArchitecturalFix;
+    /**
+     * Calculate complexity score for automated report triggering
+     */
+    private calculateComplexityScore;
+    /**
+     * Revalidate after agent fix attempt
+     */
+    private revalidateAfterFix;
+}

package/dist/postprocessor/analysis/CodeChangeAnalyzer.d.ts

@@ -0,0 +1,11 @@
+import { PostProcessorContext } from "../types.js";
+export declare class CodeChangeAnalyzer {
+    analyzeCodeChanges(context: PostProcessorContext): Promise<{
+        operation: "commit";
+        files: string[];
+        newCode: Map<string, string>;
+        existingCode: Map<string, string>;
+        tests: string[];
+        dependencies: string[];
+    }>;
+}

package/dist/postprocessor/analysis/FailureAnalysisEngine.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Failure Analysis Engine for Post-Processor
+ */
+import { FailureAnalysis, MonitoringResult } from "../types.js";
+export declare class FailureAnalysisEngine {
+    constructor();
+    /**
+     * Analyze CI/CD failure and determine root cause
+     */
+    analyzeFailure(monitoringResult: MonitoringResult): Promise<FailureAnalysis>;
+    /**
+     * Classify the type of failure based on monitoring results
+     */
+    private classifyFailure;
+    /**
+     * Assess the severity of the failure
+     */
+    private assessSeverity;
+    /**
+     * Calculate confidence in the analysis
+     */
+    private calculateConfidence;
+    /**
+     * Determine the root cause of the failure
+     */
+    private determineRootCause;
+    /**
+     * Generate recommended actions for the failure
+     */
+    private generateRecommendedActions;
+    /**
+     * Generate suggested fixes for the failure
+     */
+    private generateSuggestedFixes;
+    /**
+     * Initialize analysis patterns and rules
+     */
+    private initializeAnalysisPatterns;
+}

package/dist/postprocessor/autofix/AutoFixEngine.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Auto-Fix Engine for Post-Processor
+ */
+import { FixResult, FailureAnalysis, PostProcessorContext } from "../types.js";
+export interface AppliedFixRecord {
+    type: string;
+    files: string[];
+    description: string;
+    timestamp: Date;
+    appliedChanges: string[];
+}
+export declare class AutoFixEngine {
+    private confidenceThreshold;
+    private appliedFixes;
+    constructor(confidenceThreshold?: number);
+    /**
+     * Attempt to automatically apply fixes for a failure
+     */
+    applyFixes(analysis: FailureAnalysis, context: PostProcessorContext): Promise<FixResult>;
+    /**
+     * Apply a single suggested fix
+     */
+    private applySingleFix;
+    /**
+     * Apply dependency updates
+     */
+    private applyDependencyUpdate;
+    /**
+     * Apply automatic code fixes
+     */
+    private applyCodeFix;
+    /**
+     * Apply test regeneration fixes
+     */
+    private applyTestRegeneration;
+    /**
+     * Validate that applied fixes resolve the issue
+     */
+    validateFixes(fixes: AppliedFixRecord[], originalFailure: FailureAnalysis, context: PostProcessorContext): Promise<boolean>;
+    /**
+     * Rollback applied fixes if validation fails
+     */
+    rollbackFixes(fixes: AppliedFixRecord[]): Promise<void>;
+    /**
+     * Get the list of applied fixes
+     */
+    getAppliedFixes(): AppliedFixRecord[];
+}

package/dist/postprocessor/autofix/FixValidator.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Fix Validator for Post-Processor Auto-Fix System
+ *
+ * Validates applied fixes and provides rollback functionality.
+ */
+import { FailureAnalysis, PostProcessorContext } from "../types.js";
+export interface AppliedFix {
+    type: string;
+    files: string[];
+    description: string;
+    timestamp: Date;
+    rollbackData?: any;
+}
+export declare class FixValidator {
+    /**
+     * Validate that applied fixes resolve the original issue
+     */
+    validateFixes(appliedFixes: AppliedFix[], analysis: FailureAnalysis, context: PostProcessorContext): Promise<boolean>;
+    /**
+     * Rollback applied fixes
+     */
+    rollbackFixes(appliedFixes: AppliedFix[]): Promise<void>;
+}

package/dist/postprocessor/config/ProcessorConfigLoader.d.ts

@@ -0,0 +1,44 @@
+export declare class ProcessorConfigLoader {
+    loadProcessorConfig(): Promise<{
+        preValidate?: {
+            enabled?: boolean;
+        };
+        codexCompliance?: {
+            enabled?: boolean;
+        };
+        testAutoCreation?: {
+            enabled?: boolean;
+        };
+        versionCompliance?: {
+            enabled?: boolean;
+        };
+        errorBoundary?: {
+            enabled?: boolean;
+        };
+        agentsMdValidation?: {
+            enabled?: boolean;
+        };
+        stateValidation?: {
+            enabled?: boolean;
+        };
+        post_processors?: {
+            enabled?: boolean;
+            priority_order?: string[];
+        };
+        storytellingTrigger?: {
+            enabled?: boolean;
+        };
+        sessionSummary?: {
+            enabled?: boolean;
+        };
+        testExecution?: {
+            enabled?: boolean;
+        };
+        regressionTesting?: {
+            enabled?: boolean;
+        };
+        inferenceImprovement?: {
+            enabled?: boolean;
+        };
+    }>;
+}

package/dist/postprocessor/config.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Post-Processor Configuration
+ */
+import { PostProcessorConfig } from "./types.js";
+export declare const defaultConfig: PostProcessorConfig;
+export declare function validateConfig(config: Partial<PostProcessorConfig>): PostProcessorConfig;

package/dist/postprocessor/escalation/EscalationEngine.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Escalation Engine for Post-Processor
+ * Handles incident reporting, manual intervention triggers, and alerting
+ */
+import { PostProcessorContext, EscalationResult, IncidentReport, MonitoringResult } from "../types.js";
+export interface EscalationConfig {
+    manualInterventionThreshold: number;
+    rollbackThreshold: number;
+    emergencyThreshold: number;
+    alertChannels: string[];
+    incidentReporting: boolean;
+    reportingEndpoints?: ReportingEndpoint[];
+}
+export interface ReportingEndpoint {
+    name: string;
+    url: string;
+    type: "webhook" | "pagerduty" | "slack" | "email" | "custom";
+    enabled: boolean;
+    priorityThreshold?: "low" | "medium" | "high" | "critical";
+    headers?: Record<string, string>;
+}
+export interface AlertMessage {
+    level: "info" | "warning" | "error" | "critical";
+    title: string;
+    message: string;
+    context: PostProcessorContext;
+    metadata?: Record<string, unknown>;
+}
+export interface IncidentReportPayload {
+    incident: IncidentReport;
+    formattedMessage: string;
+    affectedSystems: string[];
+    recommendedActions: string[];
+}
+export declare class EscalationEngine {
+    private config;
+    private incidents;
+    private reportingHistory;
+    constructor(config?: Partial<EscalationConfig>);
+    /**
+     * Evaluate if escalation is needed based on failure context
+     */
+    evaluateEscalation(context: PostProcessorContext, attempts: number, error: string, monitoringResults: MonitoringResult[]): Promise<EscalationResult | null>;
+    /**
+     * Create a detailed incident report
+     */
+    private createIncidentReport;
+    /**
+     * Report incident to configured external systems
+     */
+    private reportIncidentToExternalSystems;
+    /**
+     * Send incident to a specific endpoint
+     */
+    private sendToEndpoint;
+    /**
+     * Build incident payload for reporting
+     */
+    private buildIncidentPayload;
+    /**
+     * Format incident message for external systems
+     */
+    private formatIncidentMessage;
+    /**
+     * Get recommended actions based on severity
+     */
+    private getRecommendedActions;
+    /**
+     * Send to Slack webhook
+     */
+    private sendToSlack;
+    /**
+     * Send to PagerDuty
+     */
+    private sendToPagerDuty;
+    /**
+     * Send generic webhook
+     */
+    private sendWebhook;
+    /**
+     * Send email notification (placeholder - would need SMTP configuration)
+     */
+    private sendEmail;
+    /**
+     * Get color for severity level (for Slack attachments)
+     */
+    private getSeverityColor;
+    /**
+     * Get reporting history
+     */
+    getReportingHistory(): ReadonlyArray<{
+        incidentId: string;
+        endpoint: string;
+        success: boolean;
+        timestamp: number;
+        response?: string;
+    }>;
+    /**
+     * Clear reporting history
+     */
+    clearReportingHistory(): void;
+    /**
+     * Add reporting endpoint dynamically
+     */
+    addReportingEndpoint(endpoint: ReportingEndpoint): void;
+    /**
+     * Remove reporting endpoint
+     */
+    removeReportingEndpoint(name: string): boolean;
+    /**
+     * Get configured reporting endpoints
+     */
+    getReportingEndpoints(): ReportingEndpoint[];
+    /**
+     * Send alerts through configured channels
+     */
+    private sendAlerts;
+    /**
+     * Send alert to specific channel
+     */
+    private sendAlertToChannel;
+    /**
+     * Get emoji for alert level
+     */
+    private getAlertEmoji;
+    /**
+     * Map escalation level to severity
+     */
+    private mapLevelToSeverity;
+    /**
+     * Map escalation level to alert level
+     */
+    private mapLevelToAlertLevel;
+    /**
+     * Get incident report by ID
+     */
+    getIncidentReport(incidentId: string): IncidentReport | undefined;
+    /**
+     * Get all active incidents
+     */
+    getActiveIncidents(): IncidentReport[];
+    /**
+     * Resolve an incident
+     */
+    resolveIncident(incidentId: string, resolution: string): boolean;
+    /**
+     * Get escalation statistics
+     */
+    getStats(): {
+        totalIncidents: number;
+        activeIncidents: number;
+        escalationsByLevel: Record<string, number>;
+    };
+}

package/dist/postprocessor/integration.d.ts

@@ -0,0 +1,156 @@
+/**
+ * 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
+ */
+import express from "express";
+import { PostProcessor } from './PostProcessor.js';
+import type { WebhookConfig } from './triggers/WebhookTrigger.js';
+import type { APIConfig } from './triggers/APITrigger.js';
+export { WebhookTrigger } from './triggers/WebhookTrigger.js';
+export { APITrigger } from './triggers/APITrigger.js';
+export type { WebhookConfig, WebhookEvent } from './triggers/WebhookTrigger.js';
+export type { APIConfig, APIRequest } 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 declare class XrayIntegration {
+    private postProcessor;
+    private webhookTrigger;
+    private apiTrigger;
+    constructor(postProcessor: PostProcessor);
+    /**
+     * Initialize all triggers with default configuration
+     *
+     * @param config - Optional configuration for triggers
+     */
+    initialize(config?: {
+        webhook?: Partial<WebhookConfig>;
+        api?: Partial<APIConfig>;
+    }): Promise<void>;
+    /**
+     * 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(): express.Application | null;
+    /**
+     * Get webhook router (raw Express router)
+     *
+     * Useful for frameworks that need the router instance directly
+     * rather than the full Express app.
+     */
+    getWebhookRouter(): express.Router | 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(): express.Application | null;
+    /**
+     * Get API trigger router (raw Express router)
+     *
+     * Useful for frameworks that need the router instance directly.
+     */
+    getAPIRouter(): express.Router | 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'
+     * });
+     * ```
+     */
+    trigger(options: {
+        tool: string;
+        operation: string;
+        filePath?: string;
+        directory?: string;
+        reason?: string;
+    }): Promise<void>;
+    /**
+     * Shutdown all triggers
+     */
+    shutdown(): Promise<void>;
+}
+/**
+ * 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 declare function createXrayIntegration(postProcessor: PostProcessor): XrayIntegration;

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;
+}

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

@@ -0,0 +1,2 @@
+export { type MetamorphosisEngine, type MetamorphosisProposal } from '../../types/metamorphosis.js';
+export { SelfProposalEngine, type SelfProposalConfig } from './SelfProposalEngine.js';