0xray 2.0.0

package/scripts/node/prepare-consumer.cjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+
+/**
+ * xray Consumer Preparation Script (technical)
+ * Transforms development paths back to consumer paths before publishing
+ * Part of xray v2 shipping package (plain identity).
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+// Structured logging shim (fwLogger discipline for script context)
+function structuredLog(component, action, status, details) {
+  const ts = new Date().toISOString();
+  const detailsPart = details ? ` | ${JSON.stringify(details)}` : '';
+  console.log(`${ts} [${component}] ${action} - ${String(status).toUpperCase()}${detailsPart}`);
+}
+
+structuredLog('prepare-consumer', 'Transforming development paths back to consumer paths', 'info');
+
+// Get the package root (where this script is located)
+// Script is in scripts/node/, so package root is two levels up
+const packageRoot = path.join(__dirname, "..", "..");
+
+
+function updatePathsInFile(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) {
+      structuredLog('prepare-consumer', `File not found: ${filePath}`, 'warning');
+      return;
+    }
+
+    let content = fs.readFileSync(filePath, 'utf-8');
+    let updated = false;
+
+    // Transform development paths back to consumer paths (plain xray; legacy @0xray/xray removed)
+    // Only transform if it's not already a consumer path
+    if (content.includes('dist/plugin/mcps/') && !content.includes('node_modules/xray/dist/plugin/mcps/')) {
+      content = content.replace(
+        /dist\/plugin\/mcps\//g,
+        'node_modules/xray/dist/plugin/mcps/'
+      );
+      updated = true;
+    }
+
+    // Transform plugin paths back to consumer format (only the relative dev paths)
+    if (content.includes('../../../dist/plugin/')) {
+      content = content.replace(
+        /\.\.\/\.\.\/\.\.\/dist\/plugin\//g,
+        'node_modules/xray/dist/plugin/'
+      );
+      updated = true;
+    }
+
+    if (updated) {
+      fs.writeFileSync(filePath, content);
+      structuredLog('prepare-consumer', `Updated paths in ${path.relative(packageRoot, filePath)}`, 'success');
+    } else {
+      structuredLog('prepare-consumer', `No development paths found in ${path.relative(packageRoot, filePath)}`, 'info');
+    }
+  } catch (error) {
+    console.warn(`⚠️ Could not update paths in ${filePath}:`, error.message);
+  }
+}
+
+// Files to update for consumer preparation
+// Config loaded from opencode.json in project root
+const filesToUpdate = [
+  "opencode.json"
+];
+
+structuredLog('prepare-consumer', 'Processing configuration files', 'info');
+filesToUpdate.forEach(filePath => {
+  const fullPath = path.join(packageRoot, filePath);
+  if (fs.existsSync(fullPath)) {
+    updatePathsInFile(fullPath);
+  } else {
+    structuredLog('prepare-consumer', `Skipping ${filePath} (not found)`, 'info');
+  }
+});
+
+// Add .js extensions to dist/ folder imports for ES module compatibility
+function addJsExtensionsToDist() {
+  structuredLog('prepare-consumer', 'Adding .js extensions to dist/ folder imports', 'info');
+  
+  const distPath = path.join(packageRoot, "dist");
+  
+  if (!fs.existsSync(distPath)) {
+    structuredLog('prepare-consumer', 'dist/ folder not found. Run npm run build first.', 'warning');
+    return;
+  }
+  
+  let modifiedCount = 0;
+  
+  function processFile(filePath) {
+    try {
+      let content = fs.readFileSync(filePath, 'utf-8');
+      const originalContent = content;
+      
+      // Add .js extension to relative imports that don't have it
+      // Match: from "../path/module" but not from "../path/module.js"
+      content = content.replace(/from "(\.[./][^"]+)";/g, (match, importPath) => {
+        // Skip if already has .js extension
+        if (importPath.endsWith('.js')) return match;
+        // Skip if it's a directory import (ends with /)
+        if (importPath.endsWith('/')) return match;
+        // Add .js extension
+        return `from "${importPath}.js";`;
+      });
+      
+      if (content !== originalContent) {
+        fs.writeFileSync(filePath, content);
+        modifiedCount++;
+        structuredLog('prepare-consumer', `Fixed: ${path.relative(distPath, filePath)}`, 'success');
+      }
+    } catch (error) {
+      structuredLog('prepare-consumer', `Error processing ${filePath}: ${error.message}`, 'error');
+    }
+  }
+  
+  function walkDir(dir) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      
+      if (entry.isDirectory()) {
+        walkDir(fullPath);
+      } else if (entry.name.endsWith('.js')) {
+        processFile(fullPath);
+      }
+    }
+  }
+  
+  walkDir(distPath);
+  structuredLog('prepare-consumer', `Added .js extensions to ${modifiedCount} files in dist/`, 'success');
+}
+
+// Run the dist transformation
+addJsExtensionsToDist();
+
+structuredLog('prepare-consumer', 'xray v2 Consumer Preparation: Complete!', 'success');
+structuredLog('prepare-consumer', 'Package is now ready for consumer installation (plain xray technical identity).', 'info');

package/scripts/node/reflection-processor.cjs

@@ -0,0 +1,213 @@
+/**
+ * Reflection Post-Processor
+ * 
+ * Extracts patterns, code, and lessons from reflections
+ * Feeds them to the kernel and learning engine
+ * 
+ * Run after any reflection is saved:
+ *   node scripts/node/reflection-processor.js
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const REFLECTIONS_DIR = './docs/reflections';
+
+// Extract patterns mentioned in reflection
+function extractPatterns(content) {
+  const patterns = [];
+  
+  // Common pattern references
+  const patternKeywords = [
+    'kernel', 'routing', 'learning', 'pattern', 'emergence',
+    'feedback', 'loop', 'pipeline', 'delegate', 'agent',
+    'confidence', 'inference', 'detection', 'assumption'
+  ];
+  
+  for (const keyword of patternKeywords) {
+    const regex = new RegExp(keyword, 'gi');
+    const matches = content.match(regex);
+    if (matches && matches.length > 2) {
+      patterns.push(keyword);
+    }
+  }
+  
+  return [...new Set(patterns)];
+}
+
+// Extract code blocks for potential reuse
+function extractCodeBlocks(content) {
+  const codeBlocks = [];
+  const regex = /```(?:typescript|javascript|bash|json)?\n([\s\S]*?)```/g;
+  let match;
+  
+  while ((match = regex.exec(content)) !== null) {
+    codeBlocks.push(match[1].trim());
+  }
+  
+  return codeBlocks;
+}
+
+// Extract lessons (from "Deep Lessons" or "Key Learnings" sections)
+function extractLessons(content) {
+  const lessons = [];
+  
+  // Look for lesson-like content
+  const lessonPatterns = [
+    /### Lesson \d+: ([^\n]+)/g,
+    /Ah-Ha Moment:? ([^\n]+)/g,
+    /Deep Learning:? ([^\n]+)/g,
+    /Key lesson:? ([^\n]+)/g,
+  ];
+  
+  for (const pattern of lessonPatterns) {
+    const matches = content.match(pattern);
+    if (matches) {
+      lessons.push(...matches.slice(0, 5));
+    }
+  }
+  
+  return lessons.slice(0, 10);
+}
+
+// Extract executive summary
+function extractExecutiveSummary(content) {
+  const match = content.match(/### 1\. Executive Summary\n+([^\n#]+)/i);
+  if (match) {
+    return match[1].trim().slice(0, 200);
+  }
+  return '';
+}
+
+// Process a single reflection
+function processReflection(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const stats = fs.statSync(filePath);
+  
+  return {
+    file: path.basename(filePath),
+    date: stats.mtime.toISOString().split('T')[0],
+    executiveSummary: extractExecutiveSummary(content),
+    patterns: extractPatterns(content),
+    lessons: extractLessons(content),
+    codeSnippets: extractCodeBlocks(content)
+  };
+}
+
+// Generate kernel pattern suggestion from reflection
+function generatePatternSuggestion(metadata) {
+  if (metadata.patterns.length === 0) return '';
+  
+  const patterns = metadata.patterns.join(', ');
+  return `
+/**
+ * Pattern extracted from reflection: ${metadata.file}
+ * Date: ${metadata.date}
+ * 
+ * Executive Summary: ${metadata.executiveSummary}
+ * 
+ * Patterns detected: ${patterns}
+ * Lessons: ${metadata.lessons.length}
+ * Code examples: ${metadata.codeSnippets.length}
+ */
+`;
+}
+
+// Main processor
+function main() {
+  console.log('🔄 Reflection Post-Processor');
+  console.log('============================');
+  console.log('');
+  
+  // Get all reflection files
+  if (!fs.existsSync(REFLECTIONS_DIR)) {
+    console.log('❌ Reflections directory not found');
+    process.exit(1);
+  }
+  
+  const files = fs.readdirSync(REFLECTIONS_DIR)
+    .filter(f => f.endsWith('.md') && !f.startsWith('TEMPLATE'))
+    .map(f => path.join(REFLECTIONS_DIR, f));
+  
+  console.log(`📚 Found ${files.length} reflections to process`);
+  console.log('');
+  
+  // Process each reflection
+  const allMetadata = [];
+  
+  for (const file of files) {
+    try {
+      const metadata = processReflection(file);
+      if (metadata) {
+        allMetadata.push(metadata);
+        console.log(`✅ ${metadata.file}`);
+        console.log(`   Patterns: ${metadata.patterns.join(', ') || 'none'}`);
+        console.log(`   Lessons: ${metadata.lessons.length}`);
+        console.log(`   Code: ${metadata.codeSnippets.length} snippets`);
+      }
+    } catch (e) {
+      console.log(`❌ Failed: ${path.basename(file)} - ${e}`);
+    }
+  }
+  
+  console.log('');
+  console.log('📊 SUMMARY');
+  console.log('==========');
+  
+  // Aggregate statistics
+  const allPatterns = allMetadata.flatMap(m => m.patterns);
+  const patternCounts = allPatterns.reduce((acc, p) => {
+    acc[p] = (acc[p] || 0) + 1;
+    return acc;
+  }, {});
+  
+  console.log('Pattern frequency:');
+  Object.entries(patternCounts)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 10)
+    .forEach(([p, count]) => {
+      console.log(`  ${p}: ${count}`);
+    });
+  
+  console.log('');
+  console.log(`Total lessons extracted: ${allMetadata.reduce((sum, m) => sum + m.lessons.length, 0)}`);
+  console.log(`Total code snippets: ${allMetadata.reduce((sum, m) => sum + m.codeSnippets.length, 0)}`);
+  
+  // Generate suggestions file
+  console.log('');
+  console.log('💾 Writing pattern suggestions...');
+  
+  const suggestions = allMetadata
+    .filter(m => m.patterns.length > 0)
+    .map(m => generatePatternSuggestion(m))
+    .join('\n');
+  
+  const outputPath = path.join(REFLECTIONS_DIR, 'reflection-pattern-suggestions.md');
+  fs.writeFileSync(outputPath, `# Pattern Suggestions from Reflections
+  
+Generated: ${new Date().toISOString()}
+
+${suggestions || 'No patterns detected in current reflections.'}
+
+---
+
+## How to Use
+
+1. Review patterns detected above
+2. Add valid patterns to src/core/kernel-patterns.ts
+3. Run tests to verify integration
+4. Reflections → Kernel → Patterns → Learning
+
+This is how the kernel grows from institutional knowledge.
+`);
+
+  console.log(`✅ Written to ${outputPath}`);
+  console.log('');
+  console.log('🎯 Next Steps:');
+  console.log('   1. Review: cat docs/reflections/reflection-pattern-suggestions.md');
+  console.log('   2. Add patterns: Edit src/core/kernel-patterns.ts');
+  console.log('   3. Test: npm test');
+  console.log('   4. Commit: git add -A && git commit -m "docs: patterns from reflections"');
+}
+
+main();

package/scripts/node/reflection-validate.sh

@@ -0,0 +1,194 @@
+#!/bin/bash
+#
+# reflection-validate.sh
+# Validates reflection follows v3.0 template requirements
+# Run before committing ANY significant change
+#
+# Usage: ./scripts/node/reflection-validate.sh <path-to-reflection.md>
+
+set -e
+
+REFLECTION_FILE="$1"
+
+if [ -z "$REFLECTION_FILE" ]; then
+    echo "Usage: ./scripts/node/reflection-validate.sh <path-to-reflection.md>"
+    exit 1
+fi
+
+if [ ! -f "$REFLECTION_FILE" ]; then
+    echo "❌ Error: File not found: $REFLECTION_FILE"
+    exit 1
+fi
+
+echo "🔍 Validating reflection: $REFLECTION_FILE"
+echo "=========================================="
+echo ""
+
+ERRORS=0
+WARNINGS=0
+
+# ==========================================
+# PART A: PERSONAL GROWTH (Required)
+# ==========================================
+
+echo "📋 PART A: PERSONAL GROWTH"
+echo "----------------------------"
+
+# 1. Executive Summary
+echo -n "1. Executive Summary: "
+if grep -q "^## .*Executive Summary\|^### .*Executive Summary" "$REFLECTION_FILE"; then
+    echo "✅ Found"
+else
+    echo "❌ Missing - required for quick scanning"
+    ((ERRORS++))
+fi
+
+# 2. The Dichotomy - What Was/Is/Should Be
+echo -n "2. The Dichotomy: "
+if grep -q "What Was\|What Is\|What Should Be" "$REFLECTION_FILE"; then
+    echo "✅ Found"
+    
+    # Check for INNER DIALOGUE
+    echo -n "   INNER DIALOGUE: "
+    if grep -q "INNER DIALOGUE" "$REFLECTION_FILE"; then
+        echo "✅ Found"
+    else
+        echo "❌ Missing - critical for depth"
+        ((ERRORS++))
+    fi
+else
+    echo "❌ Missing - core structure"
+    ((ERRORS++))
+fi
+
+# 3. Counterfactual Thinking
+echo -n "3. Counterfactual Thinking: "
+if grep -q -i "counterfactual\|would have\|What Would Have" "$REFLECTION_FILE"; then
+    echo "✅ Found"
+else
+    echo "❌ Missing - required for depth"
+    ((ERRORS++))
+fi
+
+# 4. Personal Journey
+echo -n "4. Personal Journey: "
+if grep -q -i "My Struggle\|My Triumph\|Personal Journey" "$REFLECTION_FILE"; then
+    echo "✅ Found"
+else
+    echo "❌ Missing - humanizes technical narrative"
+    ((ERRORS++))
+fi
+
+# 5. Master's Wisdom
+echo -n "5. Master's Wisdom: "
+if grep -q -i "Master.*Wisdom\|Who Saved\|What They Knew" "$REFLECTION_FILE"; then
+    echo "✅ Found"
+else
+    echo "❌ Missing - acknowledges learning from others"
+    ((ERRORS++))
+fi
+
+# ==========================================
+# PART B: TECHNICAL (Required)
+# ==========================================
+
+echo ""
+echo "💻 PART B: TECHNICAL"
+echo "---------------------"
+
+# 6. What Changed with Code
+echo -n "6. Code Examples: "
+CODE_BLOCKS=$(grep -c '^\`\`\`' "$REFLECTION_FILE")
+if [ "$CODE_BLOCKS" -ge 2 ]; then
+    echo "✅ Found ($CODE_BLOCKS code blocks)"
+else
+    echo "❌ Missing - must show before/after code"
+    ((ERRORS++))
+fi
+
+# 7. Architecture Impact (ASCII)
+echo -n "7. ASCII Diagrams: "
+if grep -q '^\`\`\`' "$REFLECTION_FILE" && grep -q "┌\|└\|─\|│" "$REFLECTION_FILE"; then
+    echo "✅ Found"
+else
+    echo "⚠️  Missing - ASCII diagrams help visualize"
+    ((WARNINGS++))
+fi
+
+# 8. Key Files Modified (table)
+echo -n "8. Files Modified Table: "
+if grep -q "| File |" "$REFLECTION_FILE"; then
+    echo "✅ Found"
+else
+    echo "⚠️  Missing - table helps track changes"
+    ((WARNINGS++))
+fi
+
+# 9. Test Evidence
+echo -n "9. Test Evidence: "
+if grep -q "✅\|passed\|success\|Test Files" "$REFLECTION_FILE"; then
+    echo "✅ Found"
+else
+    echo "⚠️  Missing - actual test output validates changes"
+    ((WARNINGS++))
+fi
+
+# 10. What Still Doesn't Work
+echo -n "10. What Still Doesn't Work: "
+if grep -q -i "doesn't work\|still broken\|not resolved\|needs further" "$REFLECTION_FILE"; then
+    echo "✅ Found (honest)"
+else
+    echo "⚠️  Missing - honesty builds trust"
+    ((WARNINGS++))
+fi
+
+# 11. For Future AI
+echo -n "11. For Future AI: "
+if grep -q -i "Future AI\|continue this work\|how to" "$REFLECTION_FILE"; then
+    echo "✅ Found"
+else
+    echo "⚠️  Missing - institutional knowledge for future"
+    ((WARNINGS++))
+fi
+
+# ==========================================
+# VALIDATION SUMMARY
+# ==========================================
+
+echo ""
+echo "=========================================="
+echo "📊 VALIDATION SUMMARY"
+echo "=========================================="
+echo "Errors: $ERRORS"
+echo "Warnings: $WARNINGS"
+echo ""
+
+# Check for depth indicators
+DEPTH_SCORE=0
+
+if grep -q "INNER DIALOGUE" "$REFLECTION_FILE"; then ((DEPTH_SCORE++)); fi
+if grep -q -i "counterfactual\|would have" "$REFLECTION_FILE"; then ((DEPTH_SCORE++)); fi
+if grep -q -i "struggle\|frustration\|emotion\|feeling" "$REFLECTION_FILE"; then ((DEPTH_SCORE++)); fi
+if grep -q "Master.*Wisdom" "$REFLECTION_FILE"; then ((DEPTH_SCORE++)); fi
+if grep -q "code" "$REFLECTION_FILE" && grep -q '^\`\`\`' "$REFLECTION_FILE"; then ((DEPTH_SCORE++)); fi
+
+echo "Depth Score: $DEPTH_SCORE/5"
+
+if [ $ERRORS -eq 0 ] && [ $WARNINGS -lt 3 ]; then
+    echo ""
+    echo "✅ REFLECTION VALIDATED"
+    echo "Ready for commit."
+    exit 0
+elif [ $ERRORS -eq 0 ]; then
+    echo ""
+    echo "⚠️  VALIDATED with warnings"
+    echo "Consider addressing warnings for better quality."
+    exit 0
+else
+    echo ""
+    echo "❌ VALIDATION FAILED"
+    echo "Fix the errors above before committing."
+    echo ""
+    echo "📖 Template: docs/reflections/TEMPLATE_v3.md"
+    exit 1
+fi

package/scripts/node/release-tweet.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+
+/**
+ * Release Tweet Template Reference
+ *
+ * Format guide: tweets/FORMAT.md
+ * Tweet output: tweets/v{VERSION}.md
+ *
+ * The release script (scripts/node/release.mjs) auto-generates
+ * a tweet template after publishing. Fill in the blanks using
+ * the format guide in tweets/FORMAT.md.
+ *
+ * Quick format:
+ *   🎉 xray v{VERSION} is LIVE - {THEME}!
+ *   {EMOJI} {5 consumer-facing bullets}
+ *   npm install xray@latest
+ *   What xray is: {positioning}
+ *   #xray #AIOps #DevTools #SelfHealing #NPM
+ */
+
+console.log(`
+🐦 Tweet Reference
+=================
+
+Format guide: tweets/FORMAT.md
+Output:       tweets/v{VERSION}.md
+
+After release, the script creates a template. Fill in:
+  1. {THEME} - 2-4 word summary of this release
+  2. {EMOJI} {feature} - 5 bullets with role markers
+  3. {positioning} - one sentence: what it does for the user
+
+Emoji role markers:
+  ✅ verified    🔧 fix         ✨ feature
+  🛡️ guardrail   📦 package     🧪 testing
+  📚 docs
+
+Full examples in tweets/FORMAT.md
+`);