openclaw-node-harness 2.0.3 → 2.1.0

package/lib/role-loader.js

@@ -0,0 +1,292 @@
+/**
+ * role-loader.js — Load, validate, and format role profiles for mesh tasks.
+ *
+ * Role profiles define:
+ *   - responsibilities: what the agent SHOULD do (prompt injection)
+ *   - must_not: what the agent must NOT do (prompt + post-validation)
+ *   - framework: structured thinking scaffold (prompt injection)
+ *   - required_outputs: post-completion structural validation
+ *   - forbidden_patterns: post-completion negative validation
+ *   - scope_paths: default scope if task doesn't specify one
+ *   - escalation: failure routing map
+ *
+ * Roles live in config/roles/*.yaml (shipped) and ~/.openclaw/roles/ (user).
+ * Uses js-yaml for parsing (already a dependency via plan-templates).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+// ── Role Loading ─────────────────────────────────────
+
+/**
+ * Load a single role profile from a YAML file.
+ */
+function loadRole(rolePath) {
+  const content = fs.readFileSync(rolePath, 'utf-8');
+  const role = yaml.load(content);
+  if (!role.id) role.id = path.basename(rolePath, '.yaml');
+  return role;
+}
+
+/**
+ * Find and load a role by ID, searching user dir first then shipped config.
+ * @param {string} roleId — e.g. "solidity-dev"
+ * @param {string[]} searchDirs — directories to search (first match wins)
+ * @returns {object|null} — role profile or null if not found
+ */
+function findRole(roleId, searchDirs) {
+  for (const dir of searchDirs) {
+    for (const ext of ['.yaml', '.yml']) {
+      const candidate = path.join(dir, `${roleId}${ext}`);
+      if (fs.existsSync(candidate)) {
+        try {
+          return loadRole(candidate);
+        } catch (err) {
+          console.error(`[role-loader] Failed to load ${candidate}: ${err.message}`);
+        }
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * List all available roles across search directories.
+ * @returns {Array<{id, name, description, file}>}
+ */
+function listRoles(searchDirs) {
+  const seen = new Set();
+  const roles = [];
+
+  for (const dir of searchDirs) {
+    if (!fs.existsSync(dir)) continue;
+    const files = fs.readdirSync(dir).filter(f => f.endsWith('.yaml') || f.endsWith('.yml'));
+    for (const file of files) {
+      try {
+        const role = loadRole(path.join(dir, file));
+        if (!seen.has(role.id)) {
+          seen.add(role.id);
+          roles.push({
+            id: role.id,
+            name: role.name || role.id,
+            description: role.description || '',
+            file,
+          });
+        }
+      } catch { /* skip malformed */ }
+    }
+  }
+
+  return roles;
+}
+
+// ── Role Validation ──────────────────────────────────
+
+/**
+ * Validate a role profile for structural correctness.
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+function validateRole(role) {
+  const errors = [];
+  if (!role.id) errors.push('Missing role id');
+  if (role.responsibilities && !Array.isArray(role.responsibilities)) {
+    errors.push('responsibilities must be an array');
+  }
+  if (role.must_not && !Array.isArray(role.must_not)) {
+    errors.push('must_not must be an array');
+  }
+  if (role.required_outputs && !Array.isArray(role.required_outputs)) {
+    errors.push('required_outputs must be an array');
+  }
+  if (role.forbidden_patterns && !Array.isArray(role.forbidden_patterns)) {
+    errors.push('forbidden_patterns must be an array');
+  }
+  if (role.escalation && typeof role.escalation !== 'object') {
+    errors.push('escalation must be an object');
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+// ── Prompt Formatting ────────────────────────────────
+
+/**
+ * Format a role profile into markdown for prompt injection.
+ * Injected between Scope and Instructions in the agent prompt.
+ * LLM-agnostic: standard markdown that any LLM can consume.
+ */
+function formatRoleForPrompt(role) {
+  if (!role) return '';
+  const parts = [];
+
+  parts.push(`## Role: ${role.name || role.id}`);
+  parts.push('');
+
+  if (role.responsibilities && role.responsibilities.length > 0) {
+    parts.push('### Responsibilities');
+    for (const r of role.responsibilities) {
+      parts.push(`- ${r}`);
+    }
+    parts.push('');
+  }
+
+  if (role.must_not && role.must_not.length > 0) {
+    parts.push('### Boundaries (Must NOT Do)');
+    for (const m of role.must_not) {
+      parts.push(`- ❌ ${m}`);
+    }
+    parts.push('');
+  }
+
+  if (role.framework) {
+    parts.push(`### Framework: ${role.framework.name}`);
+    parts.push(role.framework.prompt);
+    parts.push('');
+  }
+
+  return parts.join('\n');
+}
+
+// ── Post-Completion Validation ───────────────────────
+
+/**
+ * Validate task output against role's required_outputs.
+ * @param {object} role — role profile
+ * @param {string[]} outputFiles — files created/modified by the task
+ * @param {string} worktreePath — path to task worktree
+ * @returns {{ passed: boolean, failures: Array<{type, description, detail}> }}
+ */
+function validateRequiredOutputs(role, outputFiles, worktreePath) {
+  if (!role || !role.required_outputs) return { passed: true, failures: [] };
+
+  const failures = [];
+
+  for (const req of role.required_outputs) {
+    if (req.type === 'file_match') {
+      // Check if any output file matches the pattern
+      const { globMatch } = require('./rule-loader');
+      const matched = outputFiles.some(f => globMatch(req.pattern, f));
+      if (!matched) {
+        failures.push({
+          type: 'file_match',
+          description: req.description,
+          detail: `No output file matches pattern: ${req.pattern}`,
+        });
+      }
+    } else if (req.type === 'content_check') {
+      // Check if files matching pattern contain required content
+      const { globMatch } = require('./rule-loader');
+      const matchingFiles = outputFiles.filter(f => globMatch(req.pattern, f));
+      if (matchingFiles.length > 0 && worktreePath) {
+        let found = false;
+        for (const file of matchingFiles) {
+          try {
+            const content = fs.readFileSync(path.join(worktreePath, file), 'utf-8');
+            if (content.includes(req.check)) {
+              found = true;
+              break;
+            }
+          } catch { /* file not readable */ }
+        }
+        if (!found) {
+          failures.push({
+            type: 'content_check',
+            description: req.description,
+            detail: `Required content "${req.check}" not found in ${req.pattern} files`,
+          });
+        }
+      }
+    }
+  }
+
+  return { passed: failures.length === 0, failures };
+}
+
+/**
+ * Check output against role's forbidden_patterns.
+ * @param {object} role — role profile
+ * @param {string[]} outputFiles — files created/modified
+ * @param {string} worktreePath — path to task worktree
+ * @returns {{ passed: boolean, violations: Array<{pattern, in, description, file, match}> }}
+ */
+function checkForbiddenPatterns(role, outputFiles, worktreePath) {
+  if (!role || !role.forbidden_patterns) return { passed: true, violations: [] };
+
+  const { globMatch } = require('./rule-loader');
+  const violations = [];
+
+  for (const fp of role.forbidden_patterns) {
+    const regex = new RegExp(fp.pattern, 'gm');
+    const scopeFiles = fp.in
+      ? outputFiles.filter(f => globMatch(fp.in, f))
+      : outputFiles;
+
+    for (const file of scopeFiles) {
+      if (!worktreePath) continue;
+      try {
+        const content = fs.readFileSync(path.join(worktreePath, file), 'utf-8');
+        const matches = content.match(regex);
+        if (matches) {
+          violations.push({
+            pattern: fp.pattern,
+            in: fp.in,
+            description: fp.description,
+            file,
+            match: matches[0].slice(0, 100),
+          });
+        }
+      } catch { /* skip unreadable */ }
+    }
+  }
+
+  return { passed: violations.length === 0, violations };
+}
+
+/**
+ * Find the best-matching role for a set of task scope paths.
+ * Matches scope paths against each role's scope_paths field.
+ * Returns the role with the most scope path matches, or null.
+ */
+function findRoleByScope(scopePaths, searchDirs) {
+  if (!scopePaths || scopePaths.length === 0) return null;
+
+  const { globMatch } = require('./rule-loader');
+  const allRoles = listRoles(searchDirs);
+  let bestRole = null;
+  let bestScore = 0;
+
+  for (const roleSummary of allRoles) {
+    const role = findRole(roleSummary.id, searchDirs);
+    if (!role || !role.scope_paths) continue;
+
+    // Score: how many of the task's scope paths match this role's scope_paths?
+    let score = 0;
+    for (const taskPath of scopePaths) {
+      for (const rolePattern of role.scope_paths) {
+        if (globMatch(rolePattern, taskPath)) {
+          score++;
+          break; // one match per task path is enough
+        }
+      }
+    }
+
+    if (score > bestScore) {
+      bestScore = score;
+      bestRole = role;
+    }
+  }
+
+  return bestRole;
+}
+
+module.exports = {
+  loadRole,
+  findRole,
+  findRoleByScope,
+  listRoles,
+  validateRole,
+  formatRoleForPrompt,
+  validateRequiredOutputs,
+  checkForbiddenPatterns,
+};

package/lib/rule-loader.js

@@ -0,0 +1,358 @@
+/**
+ * rule-loader.js — Load, match, and format path-scoped coding rules.
+ *
+ * Rules live in .openclaw/rules/ as markdown files with YAML frontmatter.
+ * This module is pure Node.js with zero external dependencies — importable
+ * by mesh-agent, install scripts, and any LLM adapter.
+ *
+ * Rule format:
+ *   ---
+ *   id: security
+ *   tier: universal          # universal | framework | project
+ *   paths: ["**\/*"]         # glob patterns for file matching
+ *   detect: null             # framework auto-activation signals
+ *   priority: 100            # higher wins on conflict
+ *   tags: ["security"]
+ *   ---
+ *   # Rule body in markdown
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ── Tier Precedence (higher = wins) ────────────────
+const TIER_WEIGHT = {
+  universal: 0,
+  framework: 10,
+  project: 20,
+};
+
+// ── Max chars for rule injection into prompts ──────
+const MAX_RULES_CHARS = 4000;
+
+// ── Frontmatter Parser (zero-dep) ──────────────────
+
+/**
+ * Parse YAML frontmatter from a markdown file.
+ * Handles: strings, arrays (inline [...] and block - items), numbers, booleans, null.
+ */
+function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return { data: {}, body: content };
+
+  const yaml = match[1];
+  const body = content.slice(match[0].length).trim();
+  const data = {};
+
+  const lines = yaml.split('\n');
+  let currentKey = null;
+  let currentArray = null;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    // Block array item: "  - value"
+    if (trimmed.startsWith('- ') && currentKey && currentArray) {
+      currentArray.push(parseValue(trimmed.slice(2).trim()));
+      continue;
+    }
+
+    // Key-value pair
+    const kvMatch = trimmed.match(/^(\w[\w-]*):\s*(.*)/);
+    if (!kvMatch) continue;
+
+    // Save previous array if pending
+    if (currentKey && currentArray) {
+      data[currentKey] = currentArray;
+      currentArray = null;
+    }
+
+    const [, key, rawVal] = kvMatch;
+    currentKey = key;
+
+    if (rawVal === '' || rawVal === undefined) {
+      // Could be start of block array
+      currentArray = [];
+      continue;
+    }
+
+    // Inline array: ["a", "b"]
+    if (rawVal.startsWith('[')) {
+      try {
+        data[key] = JSON.parse(rawVal);
+      } catch {
+        data[key] = rawVal.slice(1, -1).split(',').map(s => s.trim().replace(/^["']|["']$/g, ''));
+      }
+      currentArray = null;
+      continue;
+    }
+
+    data[key] = parseValue(rawVal);
+    currentArray = null;
+  }
+
+  // Flush last pending array
+  if (currentKey && currentArray) {
+    data[currentKey] = currentArray;
+  }
+
+  return { data, body };
+}
+
+function parseValue(val) {
+  if (val === 'null' || val === '~') return null;
+  if (val === 'true') return true;
+  if (val === 'false') return false;
+  if (/^-?\d+$/.test(val)) return parseInt(val, 10);
+  if (/^-?\d+\.\d+$/.test(val)) return parseFloat(val);
+  return val.replace(/^["']|["']$/g, '');
+}
+
+// ── Glob Matching (zero-dep) ───────────────────────
+
+/**
+ * Match a file path against a glob pattern.
+ * Supports: *, **, ?, {a,b}
+ */
+function globMatch(pattern, filepath) {
+  // Normalize separators
+  const p = pattern.replace(/\\/g, '/');
+  const f = filepath.replace(/\\/g, '/');
+
+  // Convert glob to regex
+  let regex = '';
+  let i = 0;
+  while (i < p.length) {
+    const ch = p[i];
+    if (ch === '*') {
+      if (p[i + 1] === '*') {
+        // ** matches any number of path segments
+        if (p[i + 2] === '/') {
+          regex += '(?:.+/)?';
+          i += 3;
+        } else {
+          regex += '.*';
+          i += 2;
+        }
+      } else {
+        // * matches anything except /
+        regex += '[^/]*';
+        i++;
+      }
+    } else if (ch === '?') {
+      regex += '[^/]';
+      i++;
+    } else if (ch === '{') {
+      const end = p.indexOf('}', i);
+      if (end === -1) { regex += '\\{'; i++; continue; }
+      const alts = p.slice(i + 1, end).split(',').map(s => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+      regex += `(?:${alts.join('|')})`;
+      i = end + 1;
+    } else {
+      regex += ch.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      i++;
+    }
+  }
+
+  return new RegExp(`^${regex}$`).test(f);
+}
+
+// ── Core API ───────────────────────────────────────
+
+/**
+ * Load all rule files from a directory.
+ * Returns array of { id, tier, paths, detect, priority, tags, body, file }.
+ */
+function loadAllRules(rulesDir) {
+  if (!fs.existsSync(rulesDir)) return [];
+
+  const files = fs.readdirSync(rulesDir).filter(f => f.endsWith('.md'));
+  const rules = [];
+
+  for (const file of files) {
+    try {
+      const content = fs.readFileSync(path.join(rulesDir, file), 'utf-8');
+      const { data, body } = parseFrontmatter(content);
+
+      rules.push({
+        id: data.id || path.basename(file, '.md'),
+        tier: data.tier || 'universal',
+        paths: Array.isArray(data.paths) ? data.paths : ['**/*'],
+        detect: data.detect || null,
+        priority: parseInt(data.priority) || 50,
+        tags: Array.isArray(data.tags) ? data.tags : [],
+        body: body,
+        file: file,
+      });
+    } catch (err) {
+      // Skip malformed rule files silently
+      console.error(`[rule-loader] Skipped ${file}: ${err.message}`);
+    }
+  }
+
+  return rules;
+}
+
+/**
+ * Match rules against a set of scope paths.
+ * Returns rules sorted by: tier precedence (project > framework > universal),
+ * then priority (higher first).
+ */
+function matchRules(rules, scopePaths) {
+  if (!scopePaths || scopePaths.length === 0) return [];
+
+  const matched = rules.filter(rule => {
+    return rule.paths.some(pattern =>
+      scopePaths.some(scopePath => globMatch(pattern, scopePath))
+    );
+  });
+
+  // Sort: tier weight desc, then priority desc
+  matched.sort((a, b) => {
+    const tierDiff = (TIER_WEIGHT[b.tier] || 0) - (TIER_WEIGHT[a.tier] || 0);
+    if (tierDiff !== 0) return tierDiff;
+    return (b.priority || 0) - (a.priority || 0);
+  });
+
+  return matched;
+}
+
+/**
+ * Format matched rules into a markdown block for prompt injection.
+ * Respects MAX_RULES_CHARS to avoid bloating prompts.
+ */
+function formatRulesForPrompt(matchedRules) {
+  if (!matchedRules || matchedRules.length === 0) return '';
+
+  const parts = ['## Coding Standards', ''];
+  let totalChars = parts[0].length;
+
+  for (const rule of matchedRules) {
+    const header = `### ${rule.id} (${rule.tier})`;
+    const section = `${header}\n${rule.body}`;
+
+    if (totalChars + section.length > MAX_RULES_CHARS) {
+      parts.push(`\n_[${matchedRules.length - parts.length + 2} more rules truncated — scope narrower to see all]_`);
+      break;
+    }
+
+    parts.push(section);
+    parts.push('');
+    totalChars += section.length;
+  }
+
+  return parts.join('\n');
+}
+
+/**
+ * Detect frameworks present in a project directory.
+ * Returns array of framework identifiers (e.g., ['solidity', 'typescript']).
+ */
+function detectFrameworks(projectDir) {
+  const detected = [];
+
+  // Check package.json dependencies
+  const pkgPath = path.join(projectDir, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+      const allDeps = {
+        ...(pkg.dependencies || {}),
+        ...(pkg.devDependencies || {}),
+      };
+
+      // Framework detection heuristics
+      if (allDeps.hardhat || allDeps['@nomicfoundation/hardhat-toolbox']) detected.push('solidity');
+      if (allDeps.react || allDeps['react-dom']) detected.push('react');
+      if (allDeps.next) detected.push('nextjs');
+      if (allDeps.vue) detected.push('vue');
+      if (allDeps.express || allDeps.fastify || allDeps.koa) detected.push('node-server');
+    } catch { /* skip malformed package.json */ }
+  }
+
+  // Check config files
+  const configChecks = [
+    ['tsconfig.json', 'typescript'],
+    ['foundry.toml', 'solidity'],
+    ['hardhat.config.js', 'solidity'],
+    ['hardhat.config.ts', 'solidity'],
+    ['Cargo.toml', 'rust'],
+    ['go.mod', 'golang'],
+    ['pyproject.toml', 'python'],
+    ['requirements.txt', 'python'],
+    ['Gemfile', 'ruby'],
+  ];
+
+  for (const [file, framework] of configChecks) {
+    if (fs.existsSync(path.join(projectDir, file)) && !detected.includes(framework)) {
+      detected.push(framework);
+    }
+  }
+
+  // Check directories
+  const dirChecks = [
+    ['ProjectSettings', 'unity'],           // Unity project
+    ['Assets', 'unity'],                     // Unity assets
+    ['.godot', 'godot'],                     // Godot
+    ['ios', 'ios'],                          // iOS project
+    ['android', 'android'],                  // Android project
+  ];
+
+  for (const [dir, framework] of dirChecks) {
+    if (fs.existsSync(path.join(projectDir, dir)) && !detected.includes(framework)) {
+      detected.push(framework);
+    }
+  }
+
+  return detected;
+}
+
+// Map config file patterns to the framework IDs that detectFrameworks() returns
+const DETECT_SIGNAL_TO_FRAMEWORK = {
+  'hardhat.config.js': 'solidity',
+  'hardhat.config.ts': 'solidity',
+  'foundry.toml': 'solidity',
+  'tsconfig.json': 'typescript',
+  'Cargo.toml': 'rust',
+  'go.mod': 'golang',
+  'pyproject.toml': 'python',
+  'requirements.txt': 'python',
+  'Gemfile': 'ruby',
+  'ProjectSettings/ProjectVersion.txt': 'unity',
+};
+
+/**
+ * Filter framework-tier rules to only those matching detected frameworks.
+ * Rules with detect: null are always included.
+ * Rules with detect: ["hardhat.config.js", "foundry.toml"] are included if
+ * any detect signal resolves to a detected framework ID.
+ */
+function activateFrameworkRules(rules, detectedFrameworks) {
+  return rules.filter(rule => {
+    if (rule.tier !== 'framework') return true; // non-framework rules pass through
+    if (!rule.detect) return true;              // no detect = always active
+
+    const signals = Array.isArray(rule.detect) ? rule.detect : [rule.detect];
+    return signals.some(signal => {
+      // Direct framework ID match (e.g., detect: ["solidity"])
+      if (detectedFrameworks.includes(signal)) return true;
+      // Config file → framework ID resolution (e.g., "hardhat.config.js" → "solidity")
+      const resolvedFw = DETECT_SIGNAL_TO_FRAMEWORK[signal];
+      if (resolvedFw && detectedFrameworks.includes(resolvedFw)) return true;
+      return false;
+    });
+  });
+}
+
+module.exports = {
+  loadAllRules,
+  matchRules,
+  formatRulesForPrompt,
+  detectFrameworks,
+  activateFrameworkRules,
+  globMatch,
+  parseFrontmatter,
+  TIER_WEIGHT,
+  MAX_RULES_CHARS,
+};