universal-dev-standards 4.1.0 → 4.2.0

package/src/utils/agent-adapter.js

@@ -0,0 +1,320 @@
+/**
+ * Agent Adapter
+ *
+ * Provides cross-tool adaptation for AGENT.md definitions.
+ * Adapts agents for different execution modes based on AI tool capabilities.
+ *
+ * @version 1.0.0
+ */
+
+import { supportsTask, supportsAgents, getAgentConfig } from '../config/ai-agent-paths.js';
+
+/**
+ * Execution modes for agents
+ */
+export const ExecutionMode = {
+  TASK: 'task',         // Use Task tool to spawn independent subagent (Claude Code, OpenCode)
+  INLINE: 'inline',     // Inject agent content as context prefix (Cursor, Windsurf, etc.)
+  MANUAL: 'manual'      // Generate manual instructions (unsupported tools)
+};
+
+/**
+ * Determine the execution mode for an agent on a specific AI tool
+ * @param {string} aiTool - AI tool identifier
+ * @returns {string} Execution mode
+ */
+export function getExecutionMode(aiTool) {
+  if (supportsTask(aiTool)) {
+    return ExecutionMode.TASK;
+  }
+  if (supportsAgents(aiTool)) {
+    return ExecutionMode.INLINE;
+  }
+  return ExecutionMode.MANUAL;
+}
+
+/**
+ * Adapt agent configuration for a specific AI tool
+ * @param {Object} agentConfig - Parsed agent configuration
+ * @param {string} aiTool - Target AI tool identifier
+ * @returns {Object} Adapted configuration
+ */
+export function adaptAgentForTool(agentConfig, aiTool) {
+  const mode = getExecutionMode(aiTool);
+
+  switch (mode) {
+    case ExecutionMode.TASK:
+      return adaptForTaskMode(agentConfig, aiTool);
+    case ExecutionMode.INLINE:
+      return adaptForInlineMode(agentConfig, aiTool);
+    case ExecutionMode.MANUAL:
+      return adaptForManualMode(agentConfig, aiTool);
+    default:
+      return { mode: ExecutionMode.MANUAL, error: `Unknown mode for ${aiTool}` };
+  }
+}
+
+/**
+ * Adapt agent for Task tool execution mode
+ * @param {Object} agentConfig - Agent configuration
+ * @param {string} aiTool - AI tool identifier
+ * @returns {Object} Task mode configuration
+ */
+function adaptForTaskMode(agentConfig, aiTool) {
+  const taskConfig = {
+    subagent_type: agentConfig.name || 'general-purpose',
+    description: truncateDescription(agentConfig.description),
+    model: agentConfig.model || 'sonnet',
+  };
+
+  // Map allowed/disallowed tools to Task tool format
+  if (agentConfig['allowed-tools']) {
+    taskConfig.allowedTools = parseToolList(agentConfig['allowed-tools']);
+  }
+  if (agentConfig['disallowed-tools']) {
+    taskConfig.disallowedTools = parseToolList(agentConfig['disallowed-tools']);
+  }
+
+  // Add skill dependencies as context
+  if (agentConfig.skills && agentConfig.skills.length > 0) {
+    taskConfig.skillDependencies = agentConfig.skills;
+  }
+
+  return {
+    mode: ExecutionMode.TASK,
+    aiTool,
+    taskConfig,
+    triggers: agentConfig.triggers || {}
+  };
+}
+
+/**
+ * Adapt agent for inline context injection mode
+ * @param {Object} agentConfig - Agent configuration
+ * @param {string} aiTool - AI tool identifier
+ * @returns {Object} Inline mode configuration
+ */
+function adaptForInlineMode(agentConfig, aiTool) {
+  // Generate context prefix for tools that don't support Task tool
+  const contextPrefix = generateInlineContextPrefix(agentConfig);
+
+  return {
+    mode: ExecutionMode.INLINE,
+    aiTool,
+    contextPrefix,
+    triggers: agentConfig.triggers || {},
+    note: 'This tool does not support subagent execution. Agent will be injected as context.'
+  };
+}
+
+/**
+ * Adapt agent for manual instruction mode
+ * @param {Object} agentConfig - Agent configuration
+ * @param {string} aiTool - AI tool identifier
+ * @returns {Object} Manual mode configuration
+ */
+function adaptForManualMode(agentConfig, aiTool) {
+  const instructions = generateManualInstructions(agentConfig);
+
+  return {
+    mode: ExecutionMode.MANUAL,
+    aiTool,
+    instructions,
+    note: 'This tool does not support agents. Use these instructions manually.'
+  };
+}
+
+/**
+ * Generate inline context prefix for injection mode
+ * @param {Object} agentConfig - Agent configuration
+ * @returns {string} Context prefix
+ */
+function generateInlineContextPrefix(agentConfig) {
+  const lines = [
+    `<!-- UDS Agent: ${agentConfig.name} -->`,
+    `<!-- Role: ${agentConfig.role || 'specialist'} -->`,
+    ''
+  ];
+
+  if (agentConfig.expertise && agentConfig.expertise.length > 0) {
+    lines.push(`## Agent Expertise: ${agentConfig.expertise.join(', ')}`);
+    lines.push('');
+  }
+
+  if (agentConfig.description) {
+    lines.push('## Agent Purpose');
+    lines.push(cleanDescription(agentConfig.description));
+    lines.push('');
+  }
+
+  // Add tool permission hints
+  if (agentConfig['allowed-tools']) {
+    const tools = parseToolList(agentConfig['allowed-tools']);
+    lines.push(`## Allowed Operations: ${tools.join(', ')}`);
+  }
+  if (agentConfig['disallowed-tools']) {
+    const tools = parseToolList(agentConfig['disallowed-tools']);
+    lines.push(`## Restricted Operations: ${tools.join(', ')}`);
+  }
+
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * Generate manual instructions for unsupported tools
+ * @param {Object} agentConfig - Agent configuration
+ * @returns {string} Manual instructions
+ */
+function generateManualInstructions(agentConfig) {
+  const lines = [
+    `# ${agentConfig.name} Agent Instructions`,
+    '',
+    '## How to Use This Agent Manually',
+    '',
+    '1. Copy the agent content below into your AI assistant\'s context',
+    '2. Provide your task after the agent instructions',
+    '3. The AI will act according to the agent\'s role and expertise',
+    '',
+    '## Agent Information',
+    '',
+    `- **Name**: ${agentConfig.name}`,
+    `- **Role**: ${agentConfig.role || 'specialist'}`,
+  ];
+
+  if (agentConfig.expertise) {
+    lines.push(`- **Expertise**: ${agentConfig.expertise.join(', ')}`);
+  }
+
+  if (agentConfig.description) {
+    lines.push('');
+    lines.push('## Purpose');
+    lines.push(cleanDescription(agentConfig.description));
+  }
+
+  if (agentConfig.triggers && agentConfig.triggers.keywords) {
+    lines.push('');
+    lines.push('## Trigger Keywords');
+    lines.push(`Use this agent when: ${agentConfig.triggers.keywords.join(', ')}`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Parse tool list from various formats
+ * @param {string|string[]} tools - Tool list
+ * @returns {string[]} Normalized tool list
+ */
+function parseToolList(tools) {
+  if (Array.isArray(tools)) {
+    return tools;
+  }
+  if (typeof tools === 'string') {
+    // Handle comma-separated or bracket-enclosed format
+    return tools
+      .replace(/^\[|\]$/g, '')
+      .split(',')
+      .map(t => t.trim())
+      .filter(t => t.length > 0);
+  }
+  return [];
+}
+
+/**
+ * Truncate description for Task tool (short description)
+ * @param {string} description - Full description
+ * @returns {string} Truncated description (max 50 chars)
+ */
+function truncateDescription(description) {
+  if (!description) return 'UDS Agent';
+  const cleaned = cleanDescription(description);
+  const firstLine = cleaned.split('\n')[0].trim();
+  if (firstLine.length <= 50) return firstLine;
+  return firstLine.substring(0, 47) + '...';
+}
+
+/**
+ * Clean description text
+ * @param {string} description - Description text
+ * @returns {string} Cleaned description
+ */
+function cleanDescription(description) {
+  if (!description) return '';
+  return description
+    .replace(/^\|?\s*/, '')  // Remove leading pipe and spaces (YAML multiline)
+    .replace(/\s+/g, ' ')     // Normalize whitespace
+    .trim();
+}
+
+/**
+ * Get all supported AI tools and their execution modes
+ * @returns {Object[]} Array of tool info objects
+ */
+export function getAllToolsWithModes() {
+  const tools = [
+    'claude-code', 'opencode', 'cursor', 'cline',
+    'roo-code', 'codex', 'copilot', 'windsurf', 'gemini-cli'
+  ];
+
+  return tools.map(tool => {
+    const config = getAgentConfig(tool);
+    return {
+      id: tool,
+      name: config?.name || tool,
+      mode: getExecutionMode(tool),
+      supportsTask: supportsTask(tool),
+      supportsAgents: supportsAgents(tool)
+    };
+  });
+}
+
+/**
+ * Check if an agent is compatible with a specific AI tool
+ * @param {Object} agentConfig - Agent configuration
+ * @param {string} aiTool - AI tool identifier
+ * @returns {Object} Compatibility info
+ */
+export function checkAgentToolCompatibility(agentConfig, aiTool) {
+  const mode = getExecutionMode(aiTool);
+
+  const result = {
+    compatible: true,
+    mode,
+    warnings: [],
+    features: {
+      taskExecution: mode === ExecutionMode.TASK,
+      toolPermissions: mode === ExecutionMode.TASK,
+      skillDependencies: mode === ExecutionMode.TASK,
+      triggers: true
+    }
+  };
+
+  // Check tool permissions compatibility
+  if (agentConfig['allowed-tools'] && mode !== ExecutionMode.TASK) {
+    result.warnings.push('Tool permissions will be ignored (inline/manual mode)');
+  }
+
+  // Check model preference compatibility
+  if (agentConfig.model && mode !== ExecutionMode.TASK) {
+    result.warnings.push('Model preference will be ignored (inline/manual mode)');
+  }
+
+  // Check skill dependencies
+  if (agentConfig.skills && agentConfig.skills.length > 0 && mode !== ExecutionMode.TASK) {
+    result.warnings.push('Skill dependencies require manual loading (inline/manual mode)');
+  }
+
+  return result;
+}
+
+export default {
+  ExecutionMode,
+  getExecutionMode,
+  adaptAgentForTool,
+  getAllToolsWithModes,
+  checkAgentToolCompatibility
+};

package/src/utils/agents-installer.js

@@ -0,0 +1,393 @@
+/**
+ * Agents Installer
+ *
+ * Provides installation and management of AGENT.md definitions
+ * across all supported AI coding assistants.
+ *
+ * @version 1.0.0
+ */
+
+import { mkdirSync, writeFileSync, existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { dirname, join, basename } from 'path';
+import { fileURLToPath } from 'url';
+import {
+  getAgentConfig,
+  getAgentsDirForAgent,
+  supportsAgents
+} from '../config/ai-agent-paths.js';
+import { computeFileHash } from './hasher.js';
+
+// Get the CLI package root directory
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const CLI_ROOT = join(__dirname, '..', '..');
+const BUNDLED_DIR = join(CLI_ROOT, 'bundled');
+
+/**
+ * Get the Agents source directory.
+ * Prioritizes bundled directory (npm install), falls back to development path.
+ * @returns {string} Path to agents source directory
+ */
+function getAgentsSourceDir() {
+  const bundledPath = join(BUNDLED_DIR, 'skills', 'claude-code', 'agents');
+  if (existsSync(bundledPath)) {
+    return bundledPath;
+  }
+  // Development environment fallback
+  return join(CLI_ROOT, '..', 'skills', 'claude-code', 'agents');
+}
+
+const AGENTS_LOCAL_DIR = getAgentsSourceDir();
+
+/**
+ * Get list of available agent names from local directory
+ * @returns {string[]} Array of agent names (without .md extension)
+ */
+export function getAvailableAgentNames() {
+  if (!existsSync(AGENTS_LOCAL_DIR)) {
+    return [];
+  }
+
+  const NON_AGENT_ITEMS = ['README.md', '.DS_Store', '.manifest.json'];
+
+  try {
+    return readdirSync(AGENTS_LOCAL_DIR)
+      .filter(file => {
+        if (NON_AGENT_ITEMS.includes(file)) return false;
+        if (!file.endsWith('.md')) return false;
+        const itemPath = join(AGENTS_LOCAL_DIR, file);
+        return statSync(itemPath).isFile();
+      })
+      .map(file => basename(file, '.md'));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Get agent definition content
+ * @param {string} agentName - Agent name (without .md)
+ * @returns {string|null} Agent content or null if not found
+ */
+export function getAgentContent(agentName) {
+  const sourcePath = join(AGENTS_LOCAL_DIR, `${agentName}.md`);
+  if (!existsSync(sourcePath)) {
+    return null;
+  }
+  return readFileSync(sourcePath, 'utf-8');
+}
+
+/**
+ * Parse agent frontmatter to extract metadata
+ * @param {string} content - Agent file content
+ * @returns {Object} Parsed frontmatter fields
+ */
+export function parseAgentFrontmatter(content) {
+  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!frontmatterMatch) {
+    return {};
+  }
+
+  const frontmatter = {};
+  const lines = frontmatterMatch[1].split('\n');
+
+  for (const line of lines) {
+    const match = line.match(/^(\w[\w-]*):\s*(.+)$/);
+    if (match) {
+      const [, key, value] = match;
+      // Handle arrays (simple case)
+      if (value.startsWith('[') && value.endsWith(']')) {
+        frontmatter[key] = value.slice(1, -1).split(',').map(s => s.trim().replace(/"/g, ''));
+      } else {
+        frontmatter[key] = value.trim();
+      }
+    }
+  }
+
+  return frontmatter;
+}
+
+/**
+ * Install agents for a specific AI tool
+ * @param {string} agent - AI tool identifier (e.g., 'claude-code', 'opencode')
+ * @param {string} level - 'user' or 'project'
+ * @param {string[]} agentNames - Array of agent names to install (null = all)
+ * @param {string} projectPath - Project root path (required for project level)
+ * @returns {Object} Installation result
+ */
+export async function installAgentsForTool(agent, level, agentNames = null, projectPath = null) {
+  const config = getAgentConfig(agent);
+  if (!config || !supportsAgents(agent)) {
+    return {
+      success: false,
+      agent,
+      level,
+      error: `AI tool '${agent}' does not support agents installation`,
+      installed: [],
+      errors: []
+    };
+  }
+
+  // Get target directory
+  const targetDir = getAgentsDirForAgent(agent, level, projectPath);
+  if (!targetDir) {
+    return {
+      success: false,
+      agent,
+      level,
+      error: `Could not determine target directory for ${agent} at ${level} level`,
+      installed: [],
+      errors: []
+    };
+  }
+
+  // Ensure target directory exists
+  if (!existsSync(targetDir)) {
+    mkdirSync(targetDir, { recursive: true });
+  }
+
+  // Get agents to install
+  const availableAgents = getAvailableAgentNames();
+  const toInstall = agentNames || availableAgents;
+
+  const results = {
+    success: true,
+    agent,
+    level,
+    targetDir,
+    installed: [],
+    errors: [],
+    fileHashes: {}
+  };
+
+  for (const agentName of toInstall) {
+    const result = installSingleAgent(agentName, targetDir, agent);
+    if (result.success) {
+      results.installed.push(agentName);
+    } else {
+      results.errors.push({ agent: agentName, error: result.error });
+      results.success = false;
+    }
+  }
+
+  // Write manifest
+  if (results.installed.length > 0) {
+    writeAgentsManifest(agent, level, targetDir, results.installed);
+
+    // Compute file hashes for tracking
+    const now = new Date().toISOString();
+    for (const agentName of results.installed) {
+      const filePath = join(targetDir, `${agentName}.md`);
+      const hashInfo = computeFileHash(filePath);
+      if (hashInfo) {
+        results.fileHashes[`${agent}/${agentName}.md`] = {
+          ...hashInfo,
+          installedAt: now
+        };
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Install a single agent to target directory
+ * @param {string} agentName - Agent name (without .md)
+ * @param {string} targetDir - Target directory
+ * @param {string} aiTool - AI tool identifier (for potential transformation)
+ * @returns {Object} Result
+ */
+function installSingleAgent(agentName, targetDir, aiTool) {
+  const sourcePath = join(AGENTS_LOCAL_DIR, `${agentName}.md`);
+  const targetPath = join(targetDir, `${agentName}.md`);
+
+  if (!existsSync(sourcePath)) {
+    return {
+      success: false,
+      agent: agentName,
+      error: `Agent not found: ${agentName}`
+    };
+  }
+
+  try {
+    let content = readFileSync(sourcePath, 'utf-8');
+
+    // Transform content if needed for specific AI tools
+    content = transformAgentForTool(content, agentName, aiTool);
+
+    writeFileSync(targetPath, content);
+    return { success: true, agent: agentName, path: targetPath };
+  } catch (error) {
+    return {
+      success: false,
+      agent: agentName,
+      error: error.message
+    };
+  }
+}
+
+/**
+ * Transform agent content for a specific AI tool if needed
+ * @param {string} content - Original agent content
+ * @param {string} agentName - Agent name
+ * @param {string} aiTool - AI tool identifier
+ * @returns {string} Transformed content
+ */
+function transformAgentForTool(content, agentName, aiTool) {
+  // Claude Code and OpenCode use the same format (supports Task tool)
+  if (aiTool === 'claude-code' || aiTool === 'opencode' || aiTool === 'roo-code') {
+    return content;
+  }
+
+  // For tools that don't support Task tool, add inline mode header
+  // This helps the tool understand to inject the agent as context
+  const inlineModeHeader = `<!-- UDS Agent: ${agentName} -->
+<!-- Execution Mode: inline (inject as context) -->
+
+`;
+
+  // Check if content already has the header
+  if (content.includes('<!-- UDS Agent:')) {
+    return content;
+  }
+
+  return inlineModeHeader + content;
+}
+
+/**
+ * Write agents manifest
+ * @param {string} aiTool - AI tool identifier
+ * @param {string} level - 'user' or 'project'
+ * @param {string} targetDir - Target directory
+ * @param {string[]} agents - List of installed agents
+ */
+function writeAgentsManifest(aiTool, level, targetDir, agents) {
+  const manifestPath = join(targetDir, '.manifest.json');
+  const { version } = JSON.parse(
+    readFileSync(join(CLI_ROOT, 'package.json'), 'utf-8')
+  );
+
+  const manifest = {
+    version,
+    source: 'universal-dev-standards',
+    type: 'agents',
+    aiTool,
+    level,
+    agents,
+    installedDate: new Date().toISOString().split('T')[0]
+  };
+
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+}
+
+/**
+ * Get installed agents info for an AI tool
+ * @param {string} aiTool - AI tool identifier
+ * @param {string} level - 'user' or 'project'
+ * @param {string} projectPath - Project root path (required for project level)
+ * @returns {Object|null} Installed agents info or null
+ */
+export function getInstalledAgentsForTool(aiTool, level = 'project', projectPath = null) {
+  const targetDir = getAgentsDirForAgent(aiTool, level, projectPath);
+  if (!targetDir || !existsSync(targetDir)) {
+    return null;
+  }
+
+  const manifestPath = join(targetDir, '.manifest.json');
+
+  // Count agent files
+  let agentFiles = [];
+  try {
+    agentFiles = readdirSync(targetDir)
+      .filter(f => f.endsWith('.md') && f !== 'README.md');
+  } catch {
+    return null;
+  }
+
+  if (agentFiles.length === 0) {
+    return null;
+  }
+
+  const getAgentName = (filename) => basename(filename, '.md');
+
+  if (!existsSync(manifestPath)) {
+    return {
+      installed: true,
+      count: agentFiles.length,
+      agents: agentFiles.map(getAgentName),
+      version: null,
+      aiTool,
+      level,
+      path: targetDir
+    };
+  }
+
+  try {
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+    return {
+      installed: true,
+      count: agentFiles.length,
+      agents: manifest.agents || agentFiles.map(getAgentName),
+      version: manifest.version || null,
+      aiTool,
+      level,
+      path: targetDir,
+      installedDate: manifest.installedDate || null
+    };
+  } catch {
+    return {
+      installed: true,
+      count: agentFiles.length,
+      agents: agentFiles.map(getAgentName),
+      version: null,
+      aiTool,
+      level,
+      path: targetDir
+    };
+  }
+}
+
+/**
+ * Install agents to multiple AI tools at once
+ * @param {Array<{agent: string, level: string}>} installations - Array of installation targets
+ * @param {string[]} agentNames - Agents to install (null = all)
+ * @param {string} projectPath - Project root path
+ * @returns {Object} Combined results
+ */
+export async function installAgentsToMultipleTools(installations, agentNames = null, projectPath = null) {
+  const results = {
+    success: true,
+    installations: [],
+    totalInstalled: 0,
+    totalErrors: 0,
+    allFileHashes: {}
+  };
+
+  for (const { agent, level } of installations) {
+    const result = await installAgentsForTool(agent, level, agentNames, projectPath);
+    results.installations.push(result);
+
+    if (!result.success) {
+      results.success = false;
+    }
+    results.totalInstalled += result.installed.length;
+    results.totalErrors += result.errors.length;
+
+    // Merge file hashes from this installation
+    if (result.fileHashes) {
+      Object.assign(results.allFileHashes, result.fileHashes);
+    }
+  }
+
+  return results;
+}
+
+export default {
+  installAgentsForTool,
+  getInstalledAgentsForTool,
+  installAgentsToMultipleTools,
+  getAvailableAgentNames,
+  getAgentContent,
+  parseAgentFrontmatter
+};