erne-universal 0.10.0 → 0.10.2

package/dashboard/lib/agents-config.js

@@ -17,6 +17,8 @@ const AGENT_DEFINITIONS = [
   { name: 'senior-developer', room: 'development' },
   { name: 'feature-builder', room: 'development' },
   { name: 'pipeline-orchestrator', room: 'conference' },
+  { name: 'visual-debugger', room: 'testing' },
+  { name: 'documentation-generator', room: 'review' },
 ];
 
 const AGENT_ORDER = [
@@ -25,6 +27,7 @@ const AGENT_ORDER = [
   'code-reviewer', 'upgrade-assistant',
   'tdd-guide', 'performance-profiler',
   'pipeline-orchestrator',
+  'visual-debugger', 'documentation-generator',
 ];
 
 module.exports = { AGENT_ORDER, AGENT_DEFINITIONS };

package/dashboard/server.js

@@ -214,6 +214,17 @@ const handleEvent = (event) => {
     return { ok: true };
   }
 
+  // Visual debug events — log and store
+  if (type && type.startsWith('visual-debug:')) {
+    const now = new Date().toISOString();
+    if (agent && agentState[agent]) {
+      agentState[agent].lastEvent = now;
+      addHistoryEntry(agent, { type, task: task || null, timestamp: now });
+      persistHistory();
+    }
+    return { ok: true };
+  }
+
   // Worker events — update worker state and broadcast
   if (type && type.startsWith('worker:')) {
     const now = new Date().toISOString();
@@ -739,7 +750,8 @@ wss.on('connection', (ws) => {
     // Validate event shape before processing
     if (!data || typeof data !== 'object' || typeof data.type !== 'string') return;
     const VALID_TYPES = ['agent:start', 'agent:complete', 'planning:start', 'planning:end', 'audit:complete',
-      'worker:start', 'worker:poll', 'worker:task-start', 'worker:task-complete', 'worker:idle'];
+      'worker:start', 'worker:poll', 'worker:task-start', 'worker:task-complete', 'worker:idle',
+      'visual-debug:screenshot', 'visual-debug:fix', 'visual-debug:compare'];
     if (!VALID_TYPES.includes(data.type)) return;
 
     const result = handleEvent(data);

package/lib/doctor.js

@@ -139,12 +139,25 @@ async function autoFix(cwd, findings) {
   const tsFinding = findings.find(f => f.title && f.title.includes('strict mode'));
   if (tsFinding && fs.existsSync(tsconfigPath)) {
     try {
-      const tsconfig = JSON.parse(fs.readFileSync(tsconfigPath, 'utf8'));
-      if (!tsconfig.compilerOptions) tsconfig.compilerOptions = {};
-      tsconfig.compilerOptions.strict = true;
-      fs.writeFileSync(tsconfigPath, JSON.stringify(tsconfig, null, 2) + '\n');
-      fixes.push('Enabled TypeScript strict mode');
-    } catch { /* skip invalid tsconfig */ }
+      const raw = fs.readFileSync(tsconfigPath, 'utf8');
+      let tsconfig;
+      try {
+        tsconfig = JSON.parse(raw);
+      } catch {
+        // tsconfig.json may contain comments (JSON5) — skip auto-fix
+        fixes.push('Skipped strict mode: tsconfig.json contains comments (edit manually)');
+        return fixes;
+      }
+      // If tsconfig extends a base config, the base likely already sets strict
+      if (tsconfig.extends) {
+        fixes.push('Skipped strict mode: tsconfig.json extends a base config that may already include strict');
+      } else {
+        if (!tsconfig.compilerOptions) tsconfig.compilerOptions = {};
+        tsconfig.compilerOptions.strict = true;
+        fs.writeFileSync(tsconfigPath, JSON.stringify(tsconfig, null, 2) + '\n');
+        fixes.push('Enabled TypeScript strict mode');
+      }
+    } catch { /* skip unreadable tsconfig */ }
   }
 
   return fixes;

package/lib/generate.js

@@ -161,9 +161,26 @@ function determineRuleLayers(detection, cwd) {
 // ─── Helper: mergeHookProfile ──────────────────────────────────────────────────
 
 function mergeHookProfile(masterHooks, profileHooks, profileName) {
-  const enabledEvents = profileHooks.enabledEvents || [];
-  const result = {};
+  // masterHooks can be either:
+  //   - flat array format: { hooks: [...] }
+  //   - event-keyed format: { PreToolUse: [...], PostToolUse: [...], _meta: {...} }
+  if (Array.isArray(masterHooks.hooks)) {
+    // Flat array format — filter by profile, then group by event
+    const filtered = masterHooks.hooks.filter(hook => {
+      const hookProfiles = hook.profiles || ['minimal', 'standard', 'strict'];
+      return hookProfiles.includes(profileName);
+    });
+    const result = { _meta: { activeProfile: profileName } };
+    for (const hook of filtered) {
+      const event = hook.event;
+      if (!result[event]) result[event] = [];
+      result[event].push(hook);
+    }
+    return result;
+  }
 
+  // Event-keyed format (legacy path)
+  const result = {};
   for (const [event, hooks] of Object.entries(masterHooks)) {
     if (event === '_meta') {
       result._meta = { ...masterHooks._meta, activeProfile: profileName };
@@ -293,14 +310,26 @@ function generateConfig(erneRoot, targetDir, detection, profile, mcpSelections)
   }
 
   // 6. Apply hook profile
+  // Write to .claude/hooks.json (NOT .claude/hooks/hooks.json) — Claude Code reads from .claude/hooks.json
   const masterHooksPath = path.join(erneRoot, 'hooks', 'hooks.json');
   const profileHooksPath = path.join(erneRoot, 'hooks', 'profiles', `${profile}.json`);
   if (fs.existsSync(masterHooksPath) && fs.existsSync(profileHooksPath)) {
     const masterHooks = JSON.parse(fs.readFileSync(masterHooksPath, 'utf8'));
     const profileHooks = JSON.parse(fs.readFileSync(profileHooksPath, 'utf8'));
     const merged = mergeHookProfile(masterHooks, profileHooks, profile);
-    const destHooksPath = path.join(targetDir, 'hooks', 'hooks.json');
-    fs.mkdirSync(path.dirname(destHooksPath), { recursive: true });
+
+    // Rewrite hook commands to use node_modules path so they resolve from user's project root
+    const pkgRelPrefix = 'node_modules/erne-universal/scripts/hooks/run-with-flags.js';
+    for (const [event, hooks] of Object.entries(merged)) {
+      if (event === '_meta' || !Array.isArray(hooks)) continue;
+      for (const hook of hooks) {
+        if (hook.command && hook.command.includes('scripts/hooks/run-with-flags.js')) {
+          hook.command = hook.command.replace('scripts/hooks/run-with-flags.js', pkgRelPrefix);
+        }
+      }
+    }
+
+    const destHooksPath = path.join(targetDir, 'hooks.json');
     fs.writeFileSync(destHooksPath, JSON.stringify(merged, null, 2));
   }
 

package/lib/worker.js

@@ -23,7 +23,11 @@ module.exports = async function worker() {
 
   // 1. Load config
   const fullPath = path.resolve(configPath);
-  const config = loadConfig(fullPath);
+  const { config, error: configError } = loadConfig(fullPath);
+  if (configError) {
+    console.error('  Config error: ' + configError);
+    process.exit(1);
+  }
   const validation = validateConfig(config);
   if (!validation.valid) {
     console.error('  Config errors:');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "erne-universal",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "description": "Complete AI coding agent harness for React Native and Expo development",
   "keywords": [
     "react-native",
@@ -38,6 +38,8 @@
     "scripts/",
     "examples/",
     "schemas/",
+    "worker/",
+    "worker.example.json",
     "docs/getting-started.md",
     "docs/agents.md",
     "docs/commands.md",

package/scripts/hooks/audit-refresh.js

@@ -23,7 +23,10 @@ try {
   if (age < TWENTY_FOUR_HOURS) process.exit(0);
 
   // Refresh scan (JSON only, skip dep health for speed)
-  const { runScan } = require('../../lib/audit-scanner');
+  let runScan;
+  try { runScan = require('erne-universal/lib/audit-scanner').runScan; } catch {
+    try { runScan = require('../../lib/audit-scanner').runScan; } catch { process.exit(0); }
+  }
   const auditData = runScan(cwd, { skipDepHealth: true, maxFiles: 500 });
 
   const docsDir = path.join(cwd, 'erne-docs');

package/scripts/hooks/run-with-flags.js

@@ -109,7 +109,7 @@ if (process.env.ERNE_DASHBOARD_PORT || process.env.ERNE_HOOK_CHAIN) {
     });
     const req = http.request({
       hostname: '127.0.0.1', port,
-      path: '/api/context/event',
+      path: '/api/events',
       method: 'POST',
       headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) },
       timeout: 300

package/worker/agent-router.js

@@ -0,0 +1,183 @@
+'use strict';
+
+/**
+ * Agent definitions with priority and keyword triggers.
+ * Higher priority wins when multiple agents match.
+ */
+const AGENTS = [
+  {
+    name: 'performance-profiler',
+    priority: 10,
+    keywords: ['perf', 'slow', 'fps', 'jank', 'memory', 'lag', 'freeze', 'stutter', 'bundle size', 'memory leak', 'frame drop', 'battery drain', 'cpu usage', 'tti', 'startup time'],
+  },
+  {
+    name: 'expo-config-resolver',
+    priority: 10,
+    keywords: ['build', 'crash', 'metro', 'config', 'pod install', 'gradle', 'xcode', "won't start", 'build error', 'build failed', 'module not found', 'red screen', 'white screen', 'blank screen', 'eas build', 'prebuild', 'app.json', 'app.config'],
+  },
+  {
+    name: 'native-bridge-builder',
+    priority: 10,
+    keywords: ['native', 'swift', 'kotlin', 'bridge', 'turbo module', 'jsi', 'fabric', 'native module', 'expo module', 'objective-c', 'codegen', 'nitro'],
+  },
+  {
+    name: 'upgrade-assistant',
+    priority: 10,
+    keywords: ['upgrade', 'migration', 'breaking', 'expo sdk', 'react native version', 'deprecated', 'breaking change', 'peer dependency', 'outdated'],
+  },
+  {
+    name: 'documentation-generator',
+    priority: 10,
+    keywords: ['docs', 'documentation', 'write docs', 'readme', 'jsdoc', 'api docs'],
+  },
+  {
+    name: 'tdd-guide',
+    priority: 8,
+    keywords: ['test', 'tdd', 'coverage', 'jest', 'detox', 'failing test', 'unit test', 'snapshot test', 'integration test', 'e2e', 'mock', 'fixture'],
+  },
+  {
+    name: 'code-reviewer',
+    priority: 8,
+    keywords: ['review', 'refactor', 'quality', 'tech debt', 'dead code', 'clean up', 'code smell', 'anti-pattern', 'readability', 'maintainability', 'dry', 'solid'],
+  },
+  {
+    name: 'visual-debugger',
+    priority: 5,
+    keywords: ['visual', 'ui bug', 'layout', 'spacing', 'alignment', 'overflow', 'cut off', 'overlapping', 'not centered', 'wrong font', 'wrong colors', 'dark mode', 'safe area', 'image'],
+  },
+  {
+    name: 'ui-designer',
+    priority: 5,
+    keywords: ['component', 'button', 'modal', 'screen', 'animation', 'design system', 'theme', 'icon', 'gesture', 'bottom sheet', 'drawer', 'header', 'card', 'skeleton', 'loading', 'toast', 'tab'],
+  },
+  {
+    name: 'architect',
+    priority: 5,
+    keywords: ['architecture', 'design', 'plan', 'data flow', 'structure', 'system design', 'folder structure', 'state management', 'navigation structure', 'decompose', 'separation of concerns'],
+  },
+  {
+    name: 'senior-developer',
+    priority: 3,
+    keywords: [],
+  },
+  {
+    name: 'feature-builder',
+    priority: 1,
+    keywords: [],
+  },
+];
+
+const FALLBACK_AGENT = 'feature-builder';
+
+/**
+ * Combine ticket title, description, and labels into a single searchable string.
+ */
+function buildSearchText(ticket) {
+  const parts = [];
+  if (ticket.title) parts.push(ticket.title);
+  if (ticket.description) parts.push(ticket.description);
+  if (Array.isArray(ticket.labels)) {
+    parts.push(ticket.labels.join(' '));
+  }
+  return parts.join(' ').toLowerCase();
+}
+
+/**
+ * Score a single agent against the search text.
+ * Returns the number of keyword matches multiplied by the agent's priority.
+ */
+function scoreAgent(agent, searchText) {
+  if (agent.keywords.length === 0) return 0;
+
+  let matches = 0;
+  for (const keyword of agent.keywords) {
+    if (searchText.includes(keyword)) {
+      matches++;
+    }
+  }
+
+  return matches * agent.priority;
+}
+
+/**
+ * Apply bonus scoring from audit data.
+ * If the ticket mentions a file found in deadCode or high-severity findings,
+ * boost the code-reviewer score.
+ */
+function applyAuditBonus(scores, ticket, auditData) {
+  if (!auditData) return;
+
+  const searchText = buildSearchText(ticket);
+
+  // Check dead code references
+  if (Array.isArray(auditData.deadCode)) {
+    for (const entry of auditData.deadCode) {
+      const file = typeof entry === 'string' ? entry : (entry.file || '');
+      if (file && searchText.includes(file.toLowerCase())) {
+        scores['code-reviewer'] = (scores['code-reviewer'] || 0) + 10;
+        break;
+      }
+    }
+  }
+
+  // Check high-severity findings
+  if (Array.isArray(auditData.findings)) {
+    for (const finding of auditData.findings) {
+      const severity = finding.severity || '';
+      const file = finding.file || '';
+      if (severity === 'high' && file && searchText.includes(file.toLowerCase())) {
+        scores['code-reviewer'] = (scores['code-reviewer'] || 0) + 10;
+        break;
+      }
+    }
+  }
+}
+
+/**
+ * Route a ticket to the best-matching ERNE agent.
+ *
+ * @param {object} ticket - { title, description, labels[], type }
+ * @param {object} [auditData] - Parsed audit-data.json (deadCode[], findings[])
+ * @param {object} [config] - Worker config (unused for now, reserved for overrides)
+ * @returns {string} The agent name to handle this ticket
+ */
+function routeTicketToAgent(ticket, auditData, config) {
+  if (!ticket || typeof ticket !== 'object') return FALLBACK_AGENT;
+
+  const searchText = buildSearchText(ticket);
+
+  // Senior-developer triggers on task type
+  const isSeniorType = ticket.type === 'advice' || ticket.type === 'opinion' || ticket.type === 'question';
+
+  // Score each agent
+  const scores = {};
+  for (const agent of AGENTS) {
+    const score = scoreAgent(agent, searchText);
+    if (score > 0) {
+      scores[agent.name] = score;
+    }
+  }
+
+  // Senior-developer type bonus
+  if (isSeniorType) {
+    scores['senior-developer'] = (scores['senior-developer'] || 0) + 3;
+  }
+
+  // Audit data bonuses
+  applyAuditBonus(scores, ticket, auditData);
+
+  // Find the winner
+  let bestAgent = FALLBACK_AGENT;
+  let bestScore = 0;
+
+  for (const [name, score] of Object.entries(scores)) {
+    if (score > bestScore) {
+      bestScore = score;
+      bestAgent = name;
+    }
+  }
+
+  return bestAgent;
+}
+
+module.exports = { routeTicketToAgent };

package/worker/confidence-scorer.js

@@ -0,0 +1,92 @@
+'use strict';
+
+const COMPLEX_LABELS = ['architecture', 'breaking', 'migration', 'refactor-large'];
+
+/**
+ * Calculate a confidence score for how safely a ticket can be auto-resolved.
+ * @param {object} ticket
+ * @param {object} auditData
+ * @param {object} context - { affectedFiles: string[], knownFiles: string[] }
+ * @returns {{ score: number, level: string, factors: Array<{ factor: string, impact: number }> }}
+ */
+function calculateConfidence(ticket, auditData, context) {
+  const factors = [];
+  let score = 100;
+
+  // --- Description length ---
+  const desc = (ticket && ticket.description) || '';
+  if (desc.length < 50) {
+    factors.push({ factor: 'Short description (< 50 chars)', impact: -20 });
+    score -= 20;
+  }
+  if (desc.length > 200) {
+    factors.push({ factor: 'Detailed description (> 200 chars)', impact: 5 });
+    score += 5;
+  }
+
+  // --- Affected files ---
+  const affected = (context && context.affectedFiles) || [];
+  const fileCount = affected.length;
+
+  if (fileCount === 0) {
+    factors.push({ factor: 'No affected files identified', impact: -15 });
+    score -= 15;
+  } else if (fileCount > 20) {
+    factors.push({ factor: `Very high file count (${fileCount} > 20)`, impact: -30 });
+    score -= 30;
+  } else if (fileCount > 10) {
+    factors.push({ factor: `High file count (${fileCount} > 10)`, impact: -20 });
+    score -= 20;
+  }
+
+  // --- Ticket type ---
+  const type = (ticket && ticket.type || '').toLowerCase();
+  if (type === 'bug') {
+    factors.push({ factor: 'Bug ticket type', impact: -10 });
+    score -= 10;
+  } else if (type === 'story') {
+    factors.push({ factor: 'Story ticket type', impact: -15 });
+    score -= 15;
+  }
+
+  // --- Known files ---
+  const knownFiles = (context && context.knownFiles) || [];
+  if (fileCount > 0 && knownFiles.length > 0) {
+    const allKnown = affected.every((f) => knownFiles.includes(f));
+    const noneKnown = affected.every((f) => !knownFiles.includes(f));
+
+    if (allKnown) {
+      factors.push({ factor: 'All affected files known in audit', impact: 10 });
+      score += 10;
+    } else if (noneKnown) {
+      factors.push({ factor: 'No affected files known in audit', impact: -20 });
+      score -= 20;
+    }
+  } else if (fileCount > 0 && knownFiles.length === 0) {
+    factors.push({ factor: 'No affected files known in audit', impact: -20 });
+    score -= 20;
+  }
+
+  // --- Complex labels ---
+  const labels = (ticket && ticket.labels || []).map((l) => String(l).toLowerCase());
+  const hasComplex = labels.some((l) => COMPLEX_LABELS.includes(l));
+  if (hasComplex) {
+    const matched = labels.filter((l) => COMPLEX_LABELS.includes(l)).join(', ');
+    factors.push({ factor: `Complex label(s): ${matched}`, impact: -25 });
+    score -= 25;
+  }
+
+  // --- Clamp ---
+  score = Math.max(0, Math.min(100, score));
+
+  // --- Level ---
+  let level;
+  if (score >= 80) level = 'high';
+  else if (score >= 50) level = 'medium';
+  else if (score >= 30) level = 'low';
+  else level = 'too-complex';
+
+  return { score, level, factors };
+}
+
+module.exports = { calculateConfidence };

package/worker/config.js

@@ -0,0 +1,98 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULTS = {
+  executor: {
+    timeout_seconds: 600,
+  },
+  erne: {
+    hook_profile: 'standard',
+  },
+  provider: {
+    poll_interval_seconds: 60,
+  },
+};
+
+const PROVIDER_ENV_KEYS = {
+  linear: 'LINEAR_API_KEY',
+  jira: 'JIRA_API_TOKEN',
+  github: 'GITHUB_TOKEN',
+  clickup: 'CLICKUP_API_TOKEN',
+  gitlab: 'GITLAB_TOKEN',
+};
+
+/**
+ * Load a JSON config file and merge with defaults.
+ */
+function loadConfig(configPath) {
+  if (!configPath || typeof configPath !== 'string') {
+    return { config: null, error: 'Config path is required' };
+  }
+
+  const resolved = path.resolve(configPath);
+  if (!fs.existsSync(resolved)) {
+    return { config: null, error: `Config file not found: ${resolved}` };
+  }
+
+  let raw;
+  try {
+    raw = fs.readFileSync(resolved, 'utf8');
+  } catch (err) {
+    return { config: null, error: `Failed to read config: ${err.message}` };
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    return { config: null, error: `Invalid JSON in config: ${err.message}` };
+  }
+
+  // Merge defaults
+  const config = Object.assign({}, parsed);
+  config.executor = Object.assign({}, DEFAULTS.executor, parsed.executor);
+  config.erne = Object.assign({}, DEFAULTS.erne, parsed.erne);
+  config.provider = Object.assign({}, DEFAULTS.provider, parsed.provider);
+
+  return { config, error: null };
+}
+
+/**
+ * Validate a loaded config object.
+ */
+function validateConfig(config) {
+  const errors = [];
+
+  if (!config || typeof config !== 'object') {
+    return { valid: false, errors: ['Config must be an object'] };
+  }
+
+  // Required: provider.type
+  if (!config.provider || !config.provider.type) {
+    errors.push('provider.type is required (linear|jira|github|clickup|gitlab)');
+  } else {
+    const validTypes = ['linear', 'jira', 'github', 'clickup', 'gitlab'];
+    if (!validTypes.includes(config.provider.type)) {
+      errors.push(`provider.type must be one of: ${validTypes.join(', ')}`);
+    } else {
+      // Check env var for provider
+      const envKey = PROVIDER_ENV_KEYS[config.provider.type];
+      if (envKey && !process.env[envKey]) {
+        errors.push(`Environment variable ${envKey} is required for provider "${config.provider.type}"`);
+      }
+    }
+  }
+
+  // Required: repo.path
+  if (!config.repo || !config.repo.path) {
+    errors.push('repo.path is required');
+  } else if (!fs.existsSync(config.repo.path)) {
+    errors.push(`repo.path does not exist: ${config.repo.path}`);
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+module.exports = { loadConfig, validateConfig };

package/worker/context-resolver.js

@@ -0,0 +1,33 @@
+'use strict';
+
+/**
+ * Resolve context for a ticket — affected files and known files from audit data.
+ *
+ * @param {object} ticket
+ * @param {object} [auditData]
+ * @param {object} [stackInfo]
+ * @returns {{ affectedFiles: string[], knownFiles: string[] }}
+ */
+function resolveContext(ticket, auditData, stackInfo) {
+  const affectedFiles = [];
+  const knownFiles = [];
+
+  // Extract file references from description
+  const desc = (ticket && ticket.description) || '';
+  const fileRe = /(?:^|\s)([\w./-]+\.\w{1,5})(?:\s|$|,|:)/g;
+  let match;
+  while ((match = fileRe.exec(desc)) !== null) {
+    affectedFiles.push(match[1]);
+  }
+
+  // Gather known files from audit data
+  if (auditData && Array.isArray(auditData.files)) {
+    for (const f of auditData.files) {
+      knownFiles.push(typeof f === 'string' ? f : f.file || '');
+    }
+  }
+
+  return { affectedFiles, knownFiles };
+}
+
+module.exports = { resolveContext };

package/worker/dashboard-events.js

@@ -0,0 +1,48 @@
+'use strict';
+
+const http = require('http');
+
+const DASHBOARD_PORT = parseInt(process.env.ERNE_DASHBOARD_PORT || '3333', 10);
+
+/**
+ * Fire-and-forget POST to the ERNE dashboard events endpoint.
+ *
+ * Valid types:
+ *   worker:start, worker:poll, worker:task-start, worker:task-complete,
+ *   worker:idle, worker:ticket-rejected, worker:confidence-scored,
+ *   worker:tests-run, worker:health-delta
+ *
+ * Catches ALL errors silently — never blocks the caller.
+ *
+ * @param {string} type - Event type
+ * @param {object} [data] - Additional event data
+ */
+function publishDashboardEvent(type, data) {
+  try {
+    const payload = JSON.stringify({ type, ...(data || {}) });
+
+    const req = http.request(
+      {
+        hostname: '127.0.0.1',
+        port: DASHBOARD_PORT,
+        path: '/api/events',
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Content-Length': Buffer.byteLength(payload),
+        },
+        timeout: 2000,
+      },
+      () => { /* response ignored */ }
+    );
+
+    req.on('error', () => { /* silent */ });
+    req.on('timeout', () => { req.destroy(); });
+    req.write(payload);
+    req.end();
+  } catch {
+    // Never throw — fire-and-forget
+  }
+}
+
+module.exports = { publishDashboardEvent };