0xray 2.0.0

package/dist/postprocessor/triggers/WebhookTrigger.js

@@ -0,0 +1,211 @@
+/**
+ * Webhook Trigger for Post-Processor
+ *
+ * Provides a generic webhook server that receives events from external
+ * services (GitHub, GitLab, Bitbucket, Stripe) and routes them
+ * to the PostProcessor for execution.
+ *
+ * @version 2.0.0
+ * @since 2026-03-08
+ */
+import express from 'express';
+import crypto from 'crypto';
+import { frameworkLogger } from '../../core/framework-logger.js';
+export class WebhookTrigger {
+    postProcessor;
+    initialized = false;
+    app;
+    config;
+    constructor(postProcessor, config // Make config optional
+    ) {
+        this.postProcessor = postProcessor;
+        this.config = {
+            verifySignature: true,
+            path: '/webhooks/' + (config?.provider || 'github'),
+            events: config?.events || ['push', 'pull_request'],
+            ...config
+        };
+        this.app = express();
+    }
+    async initialize() {
+        if (this.initialized)
+            return;
+        // Setup webhook endpoint
+        this.setupWebhookEndpoint();
+        this.initialized = true;
+        frameworkLogger.log('webhook-trigger', 'initialized', 'info', {
+            provider: this.config.provider,
+            path: this.config.path,
+            events: this.config.events,
+            signatureVerification: this.config.verifySignature
+        });
+    }
+    setupWebhookEndpoint() {
+        const webhookPath = this.config.path || ('/webhooks/' + this.config.provider);
+        // Raw body parser for signature verification
+        this.app.use(express.raw({ type: 'application/json', limit: '10mb' }));
+        // Webhook endpoint
+        this.app.post(webhookPath, async (req, res) => {
+            try {
+                // Verify signature if configured
+                if (this.config.verifySignature && this.config.secret) {
+                    const signature = req.headers['x-hub-signature'] ||
+                        req.headers['x-gitlab-token'] ||
+                        req.headers['x-hub-signature-256'] ||
+                        req.headers['stripe-signature'];
+                    // CRITICAL FIX: Require signature header when verification is enabled
+                    if (!signature) {
+                        frameworkLogger.log('webhook-trigger', 'signature-verification-failed', 'info', { provider: this.config.provider, reason: 'no-signature-header' });
+                        return res.status(401).json({ error: 'Signature required' });
+                    }
+                    if (!this.verifySignature(req.body, signature)) {
+                        frameworkLogger.log('webhook-trigger', 'signature-verification-failed', 'info', { provider: this.config.provider || 'unknown', signature });
+                        return res.status(401).json({ error: 'Invalid signature' });
+                    }
+                }
+                // Parse event type
+                const eventHeader = req.headers['x-github-event'] ||
+                    req.headers['x-gitlab-event'] ||
+                    req.headers['stripe-event'];
+                const event = eventHeader ? String(eventHeader) : 'unknown';
+                // Check if event is in allowed list
+                if (this.config.events && this.config.events.length > 0 && !this.config.events.includes(event)) {
+                    frameworkLogger.log('webhook-trigger', 'event-not-allowed', 'info', { provider: this.config.provider, event, allowed: this.config.events });
+                    return res.status(200).json({ received: true, ignored: true });
+                }
+                // Parse payload
+                const payloadStr = req.body.toString('utf-8');
+                const payload = JSON.parse(payloadStr);
+                frameworkLogger.log('webhook-trigger', 'webhook-received', 'info', { provider: this.config.provider, event, payloadKeys: Object.keys(payload) });
+                // Create PostProcessor context
+                const context = {
+                    trigger: 'webhook',
+                    tool: this.config.provider || 'unknown',
+                    operation: `${this.config.provider || 'unknown'}:${event}`,
+                    commitSha: payload.after || '',
+                    repository: payload.repository?.full_name || '',
+                    branch: payload.ref?.replace('refs/heads/', '') || '',
+                    author: payload.sender?.login || '',
+                    files: this.extractFilesFromPayload(payload, event)
+                };
+                // Trigger PostProcessor
+                await this.triggerPostProcessor(context);
+                res.json({ received: true, event });
+                return;
+            }
+            catch (error) {
+                frameworkLogger.log('webhook-trigger', 'webhook-error', 'error', { provider: this.config.provider, error: error instanceof Error ? error.message : String(error) });
+                res.status(500).json({ error: 'Webhook processing failed' });
+                return;
+            }
+        });
+    }
+    verifySignature(payload, signature) {
+        if (!this.config.secret)
+            return true;
+        const { provider, secret } = this.config;
+        try {
+            switch (provider) {
+                case 'github':
+                    // GitHub HMAC signature: sha1=<hex> or sha256=<hex>
+                    const [algo, ghSignature] = signature.split('=');
+                    if (algo !== 'sha1' && algo !== 'sha256')
+                        return false;
+                    const githubHmac = crypto.createHmac(algo, secret);
+                    githubHmac.update(payload);
+                    const githubComputed = `${algo}=${githubHmac.digest('hex')}`;
+                    // SECURITY FIX: Use timingSafeEqual to prevent timing attacks
+                    try {
+                        const ghSigBuffer = Buffer.from(ghSignature || '');
+                        const ghComputedBuffer = Buffer.from(githubComputed);
+                        return crypto.timingSafeEqual(ghComputedBuffer, ghSigBuffer);
+                    }
+                    catch {
+                        return false;
+                    }
+                case 'gitlab':
+                    // GitLab X-Gitlab-Token: just a token compare
+                    const token = signature;
+                    // SECURITY FIX: Use timingSafeEqual to prevent timing attacks
+                    try {
+                        const secretBuffer = Buffer.from(secret);
+                        const tokenBuffer = Buffer.from(token || '');
+                        return crypto.timingSafeEqual(secretBuffer, tokenBuffer);
+                    }
+                    catch {
+                        return false;
+                    }
+                case 'stripe':
+                    // Stripe signature: timestamp.payload, signature (HMAC-SHA256)
+                    const parts = signature.split('.');
+                    if (parts.length !== 2)
+                        return false;
+                    const [timestamp, stripeSignature] = parts;
+                    const signedPayload = `${timestamp}.${payload.toString('utf-8')}`;
+                    const stripeHmac = crypto.createHmac('sha256', secret);
+                    stripeHmac.update(signedPayload);
+                    const stripeComputed = stripeHmac.digest('hex');
+                    // SECURITY FIX: Use timingSafeEqual to prevent timing attacks
+                    try {
+                        const stripeSigBuffer = Buffer.from(stripeSignature || '');
+                        const stripeComputedBuffer = Buffer.from(stripeComputed);
+                        return crypto.timingSafeEqual(stripeComputedBuffer, stripeSigBuffer);
+                    }
+                    catch {
+                        return false;
+                    }
+                default:
+                    return true;
+            }
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            frameworkLogger.log('webhook-trigger', 'signature-verification-error', 'error', { provider, error: errorMessage });
+            return false;
+        }
+    }
+    /**
+     * Extract files from webhook payload
+     *
+     * Different webhook providers have different payload structures.
+     * This method extracts files in a unified way.
+     */
+    extractFilesFromPayload(payload, _event) {
+        try {
+            // GitHub push event
+            const commits = payload.commits;
+            if (commits && Array.isArray(commits)) {
+                const files = new Set();
+                for (const commit of commits) {
+                    const typedCommit = commit;
+                    if (typedCommit.added && Array.isArray(typedCommit.added)) {
+                        typedCommit.added.forEach((f) => files.add(f));
+                    }
+                    if (typedCommit.modified && Array.isArray(typedCommit.modified)) {
+                        typedCommit.modified.forEach((f) => files.add(f));
+                    }
+                }
+                return Array.from(files);
+            }
+            // GitHub pull_request event
+            const pullRequest = payload.pull_request;
+            if (pullRequest && pullRequest.files) {
+                return pullRequest.files.map((f) => f.filename);
+            }
+            return [];
+        }
+        catch (error) {
+            frameworkLogger.log('webhook-trigger', 'file-extraction-failed', 'info', { provider: this.config.provider, error: error instanceof Error ? error.message : String(error) });
+            return [];
+        }
+    }
+    async triggerPostProcessor(context) {
+        await this.postProcessor.executePostProcessorLoop(context);
+    }
+    getApp() {
+        return this.app;
+    }
+    shutdown() {
+        this.initialized = false;
+    }
+}

package/dist/postprocessor/types.js

@@ -0,0 +1,4 @@
+/**
+ * Post-Processor Type Definitions
+ */
+export {};

package/dist/processors/doc-write-guard.js

@@ -0,0 +1,46 @@
+import * as fs from "fs";
+import * as path from "path";
+import { frameworkLogger } from "../core/framework-logger.js";
+const DOC_EXTENSIONS = [".md", ".mdx", ".txt"];
+const DOC_DIRS = ["docs/", "docs/reflections/", "docs/reflections/deep/"];
+export class DocWriteGuard {
+    static async append(filePath, content) {
+        if (!DocWriteGuard.isDocFile(filePath)) {
+            throw new Error(`DocWriteGuard: ${filePath} is not a doc file`);
+        }
+        if (!fs.existsSync(filePath)) {
+            throw new Error(`DocWriteGuard: ${filePath} does not exist — use createIfMissing() instead`);
+        }
+        fs.appendFileSync(filePath, content);
+        frameworkLogger.log("doc-write-guard", "append", "info", {
+            filePath,
+            contentLength: content.length,
+        });
+    }
+    static async createIfMissing(filePath, content) {
+        if (!DocWriteGuard.isDocFile(filePath)) {
+            throw new Error(`DocWriteGuard: ${filePath} is not a doc file`);
+        }
+        if (fs.existsSync(filePath)) {
+            frameworkLogger.log("doc-write-guard", "create-skipped-exists", "info", { filePath });
+            return;
+        }
+        const dir = path.dirname(filePath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.writeFileSync(filePath, content, "utf-8");
+        frameworkLogger.log("doc-write-guard", "create", "info", {
+            filePath,
+            contentLength: content.length,
+        });
+    }
+    static isDocFile(filePath) {
+        const ext = path.extname(filePath).toLowerCase();
+        return DOC_EXTENSIONS.includes(ext);
+    }
+    static isDocPath(filePath) {
+        const normalized = filePath.replace(/\\/g, "/");
+        return DOC_DIRS.some((dir) => normalized.startsWith(dir));
+    }
+}

package/dist/processors/implementations/agents-md-validation-processor.js

@@ -0,0 +1,286 @@
+/**
+ * AGENTS.md Validation Processor
+ *
+ * Pre-processor that validates AGENTS.md exists and is up-to-date before
+ * allowing commits. Integrates with 0xRay's processor pipeline.
+ *
+ * @processor_type pre
+ * @priority 90 (high - runs early)
+ * @blocking true (blocks commit if AGENTS.md is invalid)
+ *
+ * @version 1.0.0
+ * @framework 0xRay 1.3.5
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { frameworkLogger } from "../../core/framework-logger.js";
+import { DocWriteGuard } from "../doc-write-guard.js";
+export class AgentsMdValidationProcessor {
+    projectRoot;
+    agentsPath;
+    // Required sections that must exist in AGENTS.md (v1.7+ format)
+    REQUIRED_SECTIONS = [
+        "## Available Agents",
+        "## Available Skills",
+    ];
+    REQUIRED_AGENTS = [
+        "@architect",
+        "@security-auditor",
+        "@code-reviewer",
+        "@refactorer",
+        "@testing-lead",
+        "@bug-triage-specialist",
+        "@researcher",
+    ];
+    // Recommended sections that should exist
+    RECOMMENDED_SECTIONS = [
+        "## Codex",
+        "## CLI Commands",
+        "## Skills Registry",
+    ];
+    constructor(projectRoot = process.cwd()) {
+        this.projectRoot = projectRoot;
+        this.agentsPath = path.join(projectRoot, "AGENTS.md");
+    }
+    /**
+     * Main execution method - called by ProcessorManager
+     */
+    async execute(context) {
+        try {
+            // Only validate on write/edit operations
+            if (!["write", "edit", "multiedit"].includes(context.tool)) {
+                return {
+                    success: true,
+                    blocked: false,
+                    message: "AGENTS.md validation skipped (not a file modification)",
+                };
+            }
+            // Check if we're modifying AGENTS.md or any agent-related files
+            const isAgentRelated = this.isAgentRelatedChange(context);
+            // Validate AGENTS.md
+            const validation = await this.validateAgentsMd();
+            if (!validation.valid) {
+                await frameworkLogger.log("agents-md-validation-processor", "-agents-md-validation-failed-", "error", {
+                    errors: validation.errors,
+                    warnings: validation.warnings,
+                    filePath: this.agentsPath,
+                });
+                return {
+                    success: false,
+                    blocked: true,
+                    message: `AGENTS.md validation failed: ${validation.errors.join(", ")}`,
+                    result: validation,
+                };
+            }
+            // Log success
+            await frameworkLogger.log("agents-md-validation-processor", "-agents-md-validation-passed-", "info", {
+                warnings: validation.warnings,
+                isAgentRelated,
+            });
+            return {
+                success: true,
+                blocked: false,
+                message: validation.warnings.length > 0
+                    ? `AGENTS.md valid with ${validation.warnings.length} warnings`
+                    : "AGENTS.md validation passed",
+                result: validation,
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            await frameworkLogger.log("agents-md-validation-processor", "-validation-error-", "error", { message: errorMessage });
+            return {
+                success: false,
+                blocked: true,
+                message: `AGENTS.md validation error: ${errorMessage}`,
+            };
+        }
+    }
+    /**
+     * Determine if the change is agent-related
+     */
+    isAgentRelatedChange(context) {
+        const filePath = context.args?.filePath || "";
+        const agentPatterns = [
+            "AGENTS.md",
+            "opencode.json",
+            ".opencode/agent",
+            "src/agents",
+            "docs/agent",
+        ];
+        return agentPatterns.some((pattern) => filePath.includes(pattern));
+    }
+    /**
+     * Validate AGENTS.md file
+     */
+    async validateAgentsMd() {
+        const result = {
+            valid: true,
+            errors: [],
+            warnings: [],
+            fixes: [],
+        };
+        // Check 1: File exists
+        if (!fs.existsSync(this.agentsPath)) {
+            result.valid = false;
+            result.errors.push("AGENTS.md not found in project root");
+            result.fixes = result.fixes || [];
+            result.fixes.push("Create AGENTS.md using template from docs/AGENTS_TEMPLATE.md");
+            return result;
+        }
+        const content = fs.readFileSync(this.agentsPath, "utf-8");
+        // Check 2: Not empty/minimal
+        if (content.length < 500) {
+            result.valid = false;
+            result.errors.push("AGENTS.md is too short (likely incomplete)");
+        }
+        // Check 3: Required sections
+        const missingSections = this.REQUIRED_SECTIONS.filter((section) => !content.includes(section));
+        if (missingSections.length > 0) {
+            result.valid = false;
+            result.errors.push(`Missing required sections: ${missingSections.join(", ")}`);
+        }
+        // Check 4: Required agents
+        const missingAgents = this.REQUIRED_AGENTS.filter((agent) => !content.includes(agent));
+        if (missingAgents.length > 0) {
+            result.valid = false;
+            result.errors.push(`Missing agent definitions: ${missingAgents.join(", ")}`);
+        }
+        // Check 5: Version header
+        const versionMatch = content.match(/\*\*Version\*\*:\s*(\d+\.\d+\.\d+)/);
+        if (!versionMatch) {
+            result.warnings.push("No version header found in AGENTS.md");
+        }
+        // Check 6: Date freshness
+        const dateMatch = content.match(/\*\*Updated\*\*:\s*(\d{4}-\d{2}-\d{2})/);
+        if (dateMatch && dateMatch[1]) {
+            const daysOld = this.calculateDaysOld(dateMatch[1]);
+            if (daysOld > 30) {
+                result.warnings.push(`AGENTS.md is ${daysOld} days old - consider review`);
+            }
+        }
+        else {
+            result.warnings.push("No date stamp found in AGENTS.md");
+        }
+        // Check 7: Agent count (should have active autonomous agents)
+        const agentCount = (content.match(/@\[?[a-z-]+\]?/gi) || []).length;
+        if (agentCount < 5) {
+            result.warnings.push(`Only ${agentCount} agents found - verify agents table is complete`);
+        }
+        return result;
+    }
+    /**
+     * Calculate days since date
+     */
+    calculateDaysOld(dateString) {
+        const date = new Date(dateString);
+        const now = new Date();
+        return Math.ceil((now.getTime() - date.getTime()) / (1000 * 60 * 60 * 24));
+    }
+    getPackageVersion() {
+        try {
+            const pkgPath = path.join(this.projectRoot, "package.json");
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+            return pkg.version || "0.0.0";
+        }
+        catch {
+            return "0.0.0";
+        }
+    }
+    getSectionTemplate(section) {
+        const version = this.getPackageVersion();
+        const now = new Date().toISOString().split("T")[0];
+        const templates = {
+            "## Available Agents": [
+                "",
+                "## Available Agents",
+                "",
+                "| Agent | Purpose | Invoke |",
+                "|-------|---------|--------|",
+                "| `@architect` | System design & technical decisions | `@architect design this API` |",
+                "| `@code-reviewer` | Code quality & compliance review | `@code-reviewer review this code` |",
+                "| `@architect` | System design & technical decisions | `@architect design API` |",
+                "| `@security-auditor` | Vulnerability detection | `@security-auditor scan` |",
+                "| `@code-reviewer` | Quality assessment | `@code-reviewer review PR` |",
+                "| `@refactorer` | Technical debt elimination | `@refactorer optimize code` |",
+                "| `@testing-lead` | Testing strategy | `@testing-lead plan tests` |",
+                "| `@bug-triage-specialist` | Error investigation | `@bug-triage-specialist debug error` |",
+                "| `@researcher` | Codebase exploration | `@researcher find implementation` |",
+                "",
+            ].join("\n"),
+            "## Available Skills": [
+                "",
+                "## Available Skills",
+                "",
+                "StringRay ships with 30 framework skills and provides a registry of 10 curated community sources.",
+                "",
+                "```bash",
+                "npx 0xray skill:install              # Show starter packs + available sources",
+                "npx 0xray skill:install <name>       # Install from registry",
+                "npx 0xray skill:registry list        # Show all registry sources",
+                "```",
+                "",
+            ].join("\n"),
+            "## Codex": [
+                "",
+                "## Codex",
+                "",
+                `StringRay enforces Universal Development Codex (60 terms) for systematic error prevention.`,
+                "",
+            ].join("\n"),
+            "## CLI Commands": [
+                "",
+                "## CLI Commands",
+                "",
+                "```bash",
+                "npx 0xray install       # Install and configure",
+                "npx 0xray status       # Check configuration",
+                "npx 0xray health        # Health check",
+                "npx 0xray validate      # Validate installation",
+                "```",
+                "",
+            ].join("\n"),
+        };
+        return templates[section] || `\n\n${section}\n\n*(Section added by agents-md-validation-processor — ${now})*\n`;
+    }
+    async appendMissing() {
+        try {
+            if (!fs.existsSync(this.agentsPath)) {
+                return {
+                    success: false,
+                    message: "AGENTS.md not found — cannot append to nonexistent file",
+                    added: [],
+                };
+            }
+            const content = fs.readFileSync(this.agentsPath, "utf-8");
+            const missingSections = this.REQUIRED_SECTIONS.filter((s) => !content.includes(s));
+            if (missingSections.length === 0) {
+                return {
+                    success: true,
+                    message: "All required sections present",
+                    added: [],
+                };
+            }
+            const additions = missingSections
+                .map((section) => this.getSectionTemplate(section))
+                .join("\n");
+            DocWriteGuard.append(this.agentsPath, additions);
+            await frameworkLogger.log("agents-md-validation-processor", "-agents-md-sections-appended-", "info", { added: missingSections, path: this.agentsPath });
+            return {
+                success: true,
+                message: `Appended ${missingSections.length} missing sections: ${missingSections.join(", ")}`,
+                added: missingSections,
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                success: false,
+                message: `Append failed: ${errorMessage}`,
+                added: [],
+            };
+        }
+    }
+}
+// Export singleton for processor registration
+export const agentsMdValidationProcessor = new AgentsMdValidationProcessor();