agentsys 5.0.0

package/scripts/expand-templates.js

@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+/**
+ * Expand Agent Template Snippets
+ *
+ * Reads agent .md files, finds TEMPLATE markers, loads shared snippets
+ * from templates/agent-snippets/, substitutes variables, and injects
+ * expanded content between markers.
+ *
+ * Usage:
+ *   node scripts/expand-templates.js           Expand and write
+ *   node scripts/expand-templates.js --check   Validate freshness (exit 1 if stale)
+ *   node scripts/expand-templates.js --dry-run Show what would change without writing
+ *
+ * Exit codes:
+ *   0 - Success (or up-to-date in --check mode)
+ *   1 - Stale templates detected (--check mode) or error
+ *
+ * @author Avi Fenesh
+ * @license MIT
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT_DIR = path.join(__dirname, '..');
+const SNIPPETS_DIR = path.join(ROOT_DIR, 'templates', 'agent-snippets');
+
+// ---------------------------------------------------------------------------
+// Snippet loading and variable substitution
+// ---------------------------------------------------------------------------
+
+/**
+ * Load a snippet file from templates/agent-snippets/.
+ *
+ * @param {string} name - Snippet name (without .md extension)
+ * @returns {string} Snippet content
+ */
+function loadSnippet(name) {
+  if (name.includes('..') || name.includes('/') || name.includes('\\')) {
+    throw new Error(`Invalid snippet name: ${name}`);
+  }
+  const snippetPath = path.join(SNIPPETS_DIR, `${name}.md`);
+  if (!fs.existsSync(snippetPath)) {
+    throw new Error(`Snippet not found: ${name}`);
+  }
+  return fs.readFileSync(snippetPath, 'utf8');
+}
+
+/**
+ * Replace all {{key}} placeholders in a template with provided values.
+ *
+ * @param {string} template - Template content with {{var}} placeholders
+ * @param {Object} vars - Key-value pairs for substitution
+ * @param {string} snippetName - Snippet name (for error messages)
+ * @returns {string} Template with all variables substituted
+ */
+function substituteVars(template, vars, snippetName) {
+  // Single-pass replacement avoids recursive expansion if values contain {{...}}
+  const result = template.replace(/\{\{(\w+)\}\}/g, (match, key) => {
+    return Object.prototype.hasOwnProperty.call(vars, key) ? vars[key] : match;
+  });
+
+  // Check for any remaining unsubstituted variables
+  const remaining = result.match(/\{\{(\w+)\}\}/);
+  if (remaining) {
+    throw new Error(`Missing variable {{${remaining[1]}}} in snippet ${snippetName}`);
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Marker expansion
+// ---------------------------------------------------------------------------
+
+/**
+ * Find and expand all TEMPLATE markers in file content.
+ *
+ * @param {string} content - Full file content
+ * @returns {string} Content with all TEMPLATE markers expanded
+ */
+function expandMarkers(content) {
+  const markerRegex = /<!-- TEMPLATE: (\S+)\s+({.*?})\s*-->/g;
+  let result = content;
+  let match;
+
+  // Collect all markers first (to avoid regex state issues during replacement)
+  const markers = [];
+  while ((match = markerRegex.exec(content)) !== null) {
+    markers.push({
+      fullMatch: match[0],
+      snippetName: match[1],
+      varsJson: match[2],
+      index: match.index
+    });
+  }
+
+  // Process markers in reverse order to preserve indices
+  for (let i = markers.length - 1; i >= 0; i--) {
+    const marker = markers[i];
+
+    // Parse JSON variables
+    let vars;
+    try {
+      vars = JSON.parse(marker.varsJson);
+    } catch {
+      throw new Error(`Invalid JSON in TEMPLATE marker: ${marker.fullMatch}`);
+    }
+
+    // Find the closing marker after this opening marker
+    const openEnd = marker.index + marker.fullMatch.length;
+    const closeMarker = '<!-- /TEMPLATE -->';
+    const closeIdx = result.indexOf(closeMarker, openEnd);
+    if (closeIdx === -1) {
+      throw new Error(`Missing closing <!-- /TEMPLATE --> marker after: ${marker.fullMatch}`);
+    }
+
+    // Load snippet and substitute variables
+    const snippet = loadSnippet(marker.snippetName);
+    const expanded = substituteVars(snippet, vars, marker.snippetName);
+
+    // Replace content between markers (keep markers, replace inner content)
+    const before = result.substring(0, openEnd);
+    const after = result.substring(closeIdx);
+    result = before + '\n' + expanded + after;
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// File discovery and computation
+// ---------------------------------------------------------------------------
+
+/**
+ * Scan all agent .md files for TEMPLATE markers and compute expansions.
+ *
+ * @returns {{ staleFiles: string[], expandedMap: Map<string, string> }}
+ *   staleFiles: relative paths of files needing expansion
+ *   expandedMap: map of absolute path -> expanded content (for stale files only)
+ */
+function computeExpansions() {
+  const staleFiles = [];
+  const expandedMap = new Map();
+  const pluginsDir = path.join(ROOT_DIR, 'plugins');
+
+  if (!fs.existsSync(pluginsDir)) return { staleFiles, expandedMap };
+
+  const plugins = fs.readdirSync(pluginsDir).filter(d => {
+    return fs.lstatSync(path.join(pluginsDir, d)).isDirectory();
+  });
+
+  for (const plugin of plugins) {
+    const agentsDir = path.join(pluginsDir, plugin, 'agents');
+    if (!fs.existsSync(agentsDir)) continue;
+
+    const files = fs.readdirSync(agentsDir).filter(f => f.endsWith('.md'));
+    for (const file of files) {
+      const filePath = path.join(agentsDir, file);
+      const content = fs.readFileSync(filePath, 'utf8');
+
+      // Skip files without TEMPLATE markers
+      if (!content.includes('<!-- TEMPLATE:')) continue;
+
+      const expanded = expandMarkers(content);
+      if (expanded !== content) {
+        const relPath = path.relative(ROOT_DIR, filePath);
+        staleFiles.push(relPath);
+        expandedMap.set(filePath, expanded);
+      }
+    }
+  }
+
+  return { staleFiles, expandedMap };
+}
+
+// ---------------------------------------------------------------------------
+// Main orchestrator
+// ---------------------------------------------------------------------------
+
+/**
+ * Run template expansion.
+ *
+ * @param {string[]} args - CLI arguments
+ * @returns {{ changed: boolean, files: string[] } | number} Result object or exit code (--check mode)
+ */
+function main(args) {
+  args = args || [];
+  const checkMode = args.includes('--check');
+  const dryRun = args.includes('--dry-run');
+
+  const { staleFiles, expandedMap } = computeExpansions();
+
+  if (checkMode) {
+    if (staleFiles.length > 0) {
+      console.log(`[ERROR] Stale templates detected in ${staleFiles.length} file(s):`);
+      for (const f of staleFiles) {
+        console.log(`  - ${f}`);
+      }
+      console.log('\nRun: node scripts/expand-templates.js');
+      return 1;
+    }
+    return 0;
+  }
+
+  if (staleFiles.length === 0) {
+    if (!dryRun) {
+      console.log('[OK] All templates up to date');
+    }
+    return { changed: false, files: [] };
+  }
+
+  // Write expanded content (already computed by computeExpansions)
+  for (const [filePath, expanded] of expandedMap) {
+    const relPath = path.relative(ROOT_DIR, filePath);
+
+    if (dryRun) {
+      console.log(`[CHANGE] Would update: ${relPath}`);
+    } else {
+      fs.writeFileSync(filePath, expanded, 'utf8');
+      console.log(`[OK] Updated: ${relPath}`);
+    }
+  }
+
+  if (!dryRun) {
+    console.log(`\n[OK] ${staleFiles.length} file(s) updated`);
+  }
+
+  return { changed: staleFiles.length > 0, files: staleFiles };
+}
+
+/**
+ * Check if expanded templates are fresh. For preflight integration.
+ *
+ * @returns {{ status: string, message: string, staleFiles: string[] }}
+ */
+function checkFreshness() {
+  const { staleFiles } = computeExpansions();  // expandedMap intentionally unused here
+
+  if (staleFiles.length === 0) {
+    return {
+      status: 'fresh',
+      message: 'All agent templates are up to date',
+      staleFiles: []
+    };
+  }
+
+  return {
+    status: 'stale',
+    message: `${staleFiles.length} file(s) have stale template expansions`,
+    staleFiles
+  };
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry point
+// ---------------------------------------------------------------------------
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const result = main(args);
+
+  // In --check mode, main returns an exit code number
+  if (typeof result === 'number') {
+    process.exit(result);
+  }
+}
+
+module.exports = { main, checkFreshness };

package/scripts/gen-adapters.js

@@ -0,0 +1,323 @@
+#!/usr/bin/env node
+/**
+ * Generate Platform Adapters from Canonical Plugin Definitions
+ *
+ * Reads plugin source files and generates adapter files for OpenCode and
+ * Codex platforms. The generated files are committed to the repo so that
+ * install scripts can reference pre-built adapters instead of transforming
+ * at install time.
+ *
+ * Usage:
+ *   node scripts/gen-adapters.js           Write generated adapter files
+ *   node scripts/gen-adapters.js --check   Validate freshness (exit 1 if stale)
+ *   node scripts/gen-adapters.js --dry-run Show what would change without writing
+ *
+ * Exit codes:
+ *   0 - Success (or up-to-date in --check mode)
+ *   1 - Stale adapters detected (--check mode) or write error
+ *
+ * @author Avi Fenesh
+ * @license MIT
+ */
+
+const fs = require('fs');
+const path = require('path');
+const discovery = require(path.join(__dirname, '..', 'lib', 'discovery'));
+const transforms = require(path.join(__dirname, '..', 'lib', 'adapter-transforms'));
+
+const ROOT_DIR = path.join(__dirname, '..');
+const ADAPTERS_DIR = path.join(ROOT_DIR, 'adapters');
+
+// Auto-generated header for all adapter files
+const GENERATED_HEADER = '<!-- AUTO-GENERATED by scripts/gen-adapters.js - DO NOT EDIT -->\n';
+
+// Codex uses a placeholder since it doesn't have runtime PLUGIN_ROOT
+const CODEX_PLUGIN_ROOT_PLACEHOLDER = '{{PLUGIN_INSTALL_PATH}}';
+
+// Normalize path separators to forward slashes for cross-platform consistency
+function normalizePath(p) {
+  return p.replace(/\\/g, '/');
+}
+
+function computeAdapters() {
+  discovery.invalidateCache();
+
+  const files = new Map();
+
+  const plugins = discovery.discoverPlugins(ROOT_DIR);
+  const commandMappings = discovery.getCommandMappings(ROOT_DIR);
+  const codexSkillMappings = discovery.getCodexSkillMappings(ROOT_DIR);
+
+  for (const [target, plugin, source] of commandMappings) {
+    const srcPath = path.join(ROOT_DIR, 'plugins', plugin, 'commands', source);
+    if (!fs.existsSync(srcPath)) continue;
+
+    let content = fs.readFileSync(srcPath, 'utf8');
+    content = transforms.transformBodyForOpenCode(content, ROOT_DIR);
+    content = transforms.transformCommandFrontmatterForOpenCode(content);
+
+    const relPath = normalizePath(path.join('adapters', 'opencode', 'commands', target));
+    files.set(relPath, GENERATED_HEADER + content);
+  }
+
+  for (const pluginName of plugins) {
+    const srcAgentsDir = path.join(ROOT_DIR, 'plugins', pluginName, 'agents');
+    if (!fs.existsSync(srcAgentsDir)) continue;
+
+    const agentFiles = fs.readdirSync(srcAgentsDir).filter(f => f.endsWith('.md'));
+    for (const agentFile of agentFiles) {
+      const srcPath = path.join(srcAgentsDir, agentFile);
+      let content = fs.readFileSync(srcPath, 'utf8');
+
+      content = transforms.transformBodyForOpenCode(content, ROOT_DIR);
+      content = transforms.transformAgentFrontmatterForOpenCode(content, { stripModels: true });
+
+      const relPath = normalizePath(path.join('adapters', 'opencode', 'agents', agentFile));
+      files.set(relPath, GENERATED_HEADER + content);
+    }
+  }
+
+  for (const pluginName of plugins) {
+    const srcSkillsDir = path.join(ROOT_DIR, 'plugins', pluginName, 'skills');
+    if (!fs.existsSync(srcSkillsDir)) continue;
+
+    const skillDirs = fs.readdirSync(srcSkillsDir, { withFileTypes: true })
+      .filter(d => d.isDirectory());
+    for (const skillDir of skillDirs) {
+      const skillName = skillDir.name;
+      const srcSkillPath = path.join(srcSkillsDir, skillName, 'SKILL.md');
+      if (!fs.existsSync(srcSkillPath)) continue;
+
+      let content = fs.readFileSync(srcSkillPath, 'utf8');
+      content = transforms.transformSkillBodyForOpenCode(content, ROOT_DIR);
+
+      const relPath = normalizePath(path.join('adapters', 'opencode', 'skills', skillName, 'SKILL.md'));
+      files.set(relPath, GENERATED_HEADER + content);
+    }
+  }
+
+  const emptyDescSkills = [];
+  for (const [skillName, plugin, sourceFile, description] of codexSkillMappings) {
+    if (!description) {
+      emptyDescSkills.push(skillName);
+    }
+    const srcPath = path.join(ROOT_DIR, 'plugins', plugin, 'commands', sourceFile);
+    if (!fs.existsSync(srcPath)) continue;
+
+    let content = fs.readFileSync(srcPath, 'utf8');
+    content = transforms.transformForCodex(content, {
+      skillName,
+      description,
+      pluginInstallPath: CODEX_PLUGIN_ROOT_PLACEHOLDER
+    });
+
+    const relPath = normalizePath(path.join('adapters', 'codex', 'skills', skillName, 'SKILL.md'));
+    files.set(relPath, GENERATED_HEADER + content);
+  }
+
+  if (emptyDescSkills.length > 0) {
+    console.error(`[ERROR] Codex skills with empty description: ${emptyDescSkills.join(', ')}`);
+    console.error('  Add a description (or codex-description) to the source command frontmatter.');
+    process.exit(1);
+  }
+
+  const staleFiles = [];
+  for (const [relPath, newContent] of files) {
+    const absPath = path.resolve(ROOT_DIR, relPath);
+    if (!absPath.startsWith(path.join(ROOT_DIR, 'adapters'))) {
+      throw new Error('Path traversal detected: ' + relPath);
+    }
+    if (!fs.existsSync(absPath)) {
+      staleFiles.push(relPath);
+      continue;
+    }
+    const current = fs.readFileSync(absPath, 'utf8');
+    if (current !== newContent) {
+      staleFiles.push(relPath);
+    }
+  }
+
+  // Check for orphaned adapter files
+  const orphanedFiles = findOrphanedAdapters(files);
+
+  return { files, staleFiles, orphanedFiles };
+}
+
+/**
+ * Find orphaned adapter files that exist on disk but have no corresponding source
+ * @param {Map<string, string>} generatedFiles - Map of generated file paths
+ * @returns {string[]} Array of relative paths to orphaned files
+ */
+function findOrphanedAdapters(generatedFiles) {
+  const orphans = [];
+  // Hand-maintained files that should not be treated as orphans
+  const EXCLUDED_FILES = new Set(['README.md', 'install.sh']);
+
+  function scanDirectory(dir, relativeBase) {
+    if (!fs.existsSync(dir)) return;
+
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const absPath = path.join(dir, entry.name);
+      const relPath = normalizePath(path.join(relativeBase, entry.name));
+
+      if (entry.isDirectory()) {
+        scanDirectory(absPath, relPath);
+      } else if (entry.isFile() && entry.name.endsWith('.md') && !EXCLUDED_FILES.has(entry.name)) {
+        if (!generatedFiles.has(relPath)) {
+          orphans.push(relPath);
+        }
+      }
+    }
+  }
+
+  // Scan opencode/ and codex/ subdirectories
+  for (const subdir of ['opencode', 'codex']) {
+    const dir = path.join(ADAPTERS_DIR, subdir);
+    const relativeBase = normalizePath(path.join('adapters', subdir));
+    scanDirectory(dir, relativeBase);
+  }
+
+  return orphans;
+}
+
+function main(args) {
+  args = args || [];
+  const checkMode = args.includes('--check');
+  const dryRun = args.includes('--dry-run');
+
+  const { files, staleFiles, orphanedFiles } = computeAdapters();
+
+  if (checkMode) {
+    const hasStale = staleFiles.length > 0;
+    const hasOrphans = orphanedFiles.length > 0;
+
+    if (hasStale) {
+      console.log(`[ERROR] Stale adapters detected in ${staleFiles.length} file(s):`);
+      for (const f of staleFiles) {
+        console.log(`  - ${f}`);
+      }
+    }
+
+    if (hasOrphans) {
+      console.log(`[ERROR] Orphaned adapter files detected in ${orphanedFiles.length} file(s):`);
+      for (const f of orphanedFiles) {
+        console.log(`  - ${f}`);
+      }
+    }
+
+    if (hasStale || hasOrphans) {
+      console.log('\nRun: node scripts/gen-adapters.js');
+      return 1;
+    }
+    return 0;
+  }
+
+  if (!dryRun) {
+    console.log(`[OK] Generating adapters: ${files.size} files across OpenCode and Codex`);
+  }
+
+  const changedFiles = [];
+
+  for (const [relPath, content] of files) {
+    const absPath = path.resolve(ROOT_DIR, relPath);
+    if (!absPath.startsWith(path.join(ROOT_DIR, 'adapters'))) {
+      throw new Error('Path traversal detected: ' + relPath);
+    }
+    const dir = path.dirname(absPath);
+
+    // Check if file needs updating
+    let needsUpdate = true;
+    if (fs.existsSync(absPath)) {
+      const current = fs.readFileSync(absPath, 'utf8');
+      if (current === content) {
+        needsUpdate = false;
+      }
+    }
+
+    if (needsUpdate) {
+      changedFiles.push(relPath);
+
+      if (dryRun) {
+        console.log(`[CHANGE] Would write: ${relPath}`);
+      } else {
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(absPath, content, 'utf8');
+      }
+    }
+  }
+
+  // Handle orphaned files
+  const deletedFiles = [];
+  for (const relPath of orphanedFiles) {
+    const absPath = path.resolve(ROOT_DIR, relPath);
+    if (!absPath.startsWith(path.join(ROOT_DIR, 'adapters'))) {
+      throw new Error('Path traversal detected: ' + relPath);
+    }
+
+    deletedFiles.push(relPath);
+
+    if (dryRun) {
+      console.log(`[DELETE] Would delete orphan: ${relPath}`);
+    } else {
+      fs.unlinkSync(absPath);
+    }
+  }
+
+  if (!dryRun) {
+    if (changedFiles.length > 0) {
+      console.log(`[OK] ${changedFiles.length} file(s) updated`);
+      for (const f of changedFiles) {
+        console.log(`  - ${f}`);
+      }
+    }
+    if (deletedFiles.length > 0) {
+      console.log(`[OK] ${deletedFiles.length} orphaned file(s) deleted`);
+      for (const f of deletedFiles) {
+        console.log(`  - ${f}`);
+      }
+    }
+    if (changedFiles.length === 0 && deletedFiles.length === 0) {
+      console.log('[OK] All adapters up to date');
+    }
+  }
+
+  return {
+    changed: changedFiles.length > 0 || deletedFiles.length > 0,
+    files: changedFiles,
+    deleted: deletedFiles
+  };
+}
+
+function checkFreshness() {
+  const { staleFiles, orphanedFiles } = computeAdapters();
+
+  if (staleFiles.length === 0 && orphanedFiles.length === 0) {
+    return {
+      status: 'fresh',
+      message: 'All generated adapters are up to date',
+      staleFiles: [],
+      orphanedFiles: []
+    };
+  }
+
+  const totalIssues = staleFiles.length + orphanedFiles.length;
+  return {
+    status: 'stale',
+    message: `${staleFiles.length} adapter file(s) are stale, ${orphanedFiles.length} orphaned`,
+    staleFiles,
+    orphanedFiles
+  };
+}
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const result = main(args);
+
+  // In --check mode, main returns an exit code number
+  if (typeof result === 'number') {
+    process.exit(result);
+  }
+}
+
+module.exports = { main, checkFreshness, computeAdapters, findOrphanedAdapters, GENERATED_HEADER };