universal-dev-standards 4.1.0 → 5.0.0-beta.10

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', 'agents');
+  if (existsSync(bundledPath)) {
+    return bundledPath;
+  }
+  // Development environment fallback
+  return join(CLI_ROOT, '..', 'skills', '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
+};

package/src/utils/config-loader.js

@@ -0,0 +1,47 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import yaml from 'js-yaml';
+
+export class ConfigLoader {
+  constructor(cwd = process.cwd()) {
+    this.cwd = cwd;
+    this.globalPath = path.join(os.homedir(), '.udsrc');
+    this.projectPath = path.join(this.cwd, '.uds', 'config.yaml');
+  }
+
+  /**
+   * Load global configuration from ~/.udsrc
+   * @returns {Object}
+   */
+  loadGlobal() {
+    return this._loadFile(this.globalPath);
+  }
+
+  /**
+   * Load project configuration from ./.uds/config.yaml
+   * @returns {Object}
+   */
+  loadProject() {
+    return this._loadFile(this.projectPath);
+  }
+
+  /**
+   * Internal helper to load and parse YAML/JSON
+   * @private
+   */
+  _loadFile(filePath) {
+    if (!fs.existsSync(filePath)) {
+      return {};
+    }
+
+    try {
+      const content = fs.readFileSync(filePath, 'utf8');
+      // js-yaml handles both JSON and YAML
+      return yaml.load(content) || {};
+    } catch (error) {
+      console.warn(`Warning: Failed to load config at ${filePath}: ${error.message}`);
+      return {};
+    }
+  }
+}

package/src/utils/config-manager.js

@@ -0,0 +1,108 @@
+import { ConfigLoader } from './config-loader.js';
+import { ConfigMerger } from './config-merger.js';
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+
+export class ConfigManager {
+  constructor(cwd = process.cwd()) {
+    this.loader = new ConfigLoader(cwd);
+    this.config = {};
+    this.initialized = false;
+  }
+
+  /**
+   * Initialize and merge all configurations
+   */
+  init() {
+    const globalConfig = this.loader.loadGlobal();
+    const projectConfig = this.loader.loadProject();
+
+    // Built-in defaults
+    const defaults = {
+      ui: {
+        language: 'en',
+        emoji: true
+      },
+      hitl: {
+        threshold: 2
+      },
+      'vibe-coding': {
+        enabled: false
+      }
+    };
+
+    // Merge: Defaults <- Global <- Project
+    this.config = ConfigMerger.merge(defaults, globalConfig);
+    this.config = ConfigMerger.merge(this.config, projectConfig);
+    
+    this.initialized = true;
+    return this.config;
+  }
+
+  /**
+   * Get a configuration value using dot notation
+   * @param {string} keyPath - e.g. 'ui.language'
+   * @param {*} defaultValue
+   */
+  get(keyPath, defaultValue) {
+    if (!this.initialized) this.init();
+
+    const parts = keyPath.split('.');
+    let current = this.config;
+
+    for (const part of parts) {
+      if (current === null || typeof current !== 'object' || !(part in current)) {
+        return defaultValue;
+      }
+      current = current[part];
+    }
+
+    return current !== undefined ? current : defaultValue;
+  }
+
+  /**
+   * Set a configuration value and persist to disk
+   * @param {string} keyPath 
+   * @param {*} value 
+   * @param {string} scope - 'global' or 'project'
+   */
+  set(keyPath, value, scope = 'project') {
+    if (!this.initialized) this.init();
+
+    const parts = keyPath.split('.');
+    const filePath = scope === 'global' ? this.loader.globalPath : this.loader.projectPath;
+    
+    // Load existing file content to preserve other settings
+    let fileContent = {};
+    if (fs.existsSync(filePath)) {
+      try {
+        fileContent = yaml.load(fs.readFileSync(filePath, 'utf8')) || {};
+      } catch (e) {
+        fileContent = {};
+      }
+    }
+
+    // Update value in fileContent object
+    let current = fileContent;
+    for (let i = 0; i < parts.length - 1; i++) {
+      const part = parts[i];
+      if (!(part in current)) current[part] = {};
+      current = current[part];
+    }
+    current[parts[parts.length - 1]] = value;
+
+    // Persist to disk
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(filePath, yaml.dump(fileContent), 'utf8');
+
+    // Re-initialize to update in-memory config
+    this.init();
+  }
+}
+
+// Singleton instance for the CLI
+export const config = new ConfigManager();

package/src/utils/config-merger.js

@@ -0,0 +1,47 @@
+/**
+ * Configuration Merger for UDS
+ * Handles deep merging of configuration objects with support for special strategies.
+ */
+
+export class ConfigMerger {
+  /**
+   * Deep merge two objects.
+   * @param {Object} base - The base object (lower priority)
+   * @param {Object} override - The override object (higher priority)
+   * @returns {Object} - The merged object
+   */
+  static merge(base, override) {
+    if (!base) return override || {};
+    if (!override) return base || {};
+
+    const result = { ...base };
+
+    for (const key in override) {
+      const value = override[key];
+
+      // Handle arrays
+      if (Array.isArray(value)) {
+        // Special strategy: $append
+        if (value.length > 0 && typeof value[0] === 'object' && value[0].$append) {
+          const itemsToAppend = value[0].$append;
+          result[key] = Array.isArray(base[key]) ? [...base[key], ...itemsToAppend] : itemsToAppend;
+        } else {
+          // Default: Replace array
+          result[key] = value;
+        }
+        continue;
+      }
+
+      // Handle nested objects
+      if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+        result[key] = this.merge(base[key] || {}, value);
+        continue;
+      }
+
+      // Handle primitives
+      result[key] = value;
+    }
+
+    return result;
+  }
+}