whiteport-design-studio 0.2.2 → 0.3.0

package/tools/cli/installers/lib/ide/_base-ide.js

@@ -0,0 +1,263 @@
+const path = require('node:path');
+const fs = require('fs-extra');
+const chalk = require('chalk');
+const yaml = require('yaml');
+
+/**
+ * Base class for IDE-specific setup
+ * All IDE handlers should extend this class
+ */
+class BaseIdeSetup {
+  constructor(name, displayName = null, preferred = false) {
+    this.name = name;
+    this.displayName = displayName || name; // Human-readable name for UI
+    this.preferred = preferred; // Whether this IDE should be shown in preferred list
+    this.configDir = null; // Override in subclasses (e.g., '.windsurf/workflows/wds')
+    this.configFile = null; // Override in subclasses when detection is file-based
+    this.detectionPaths = []; // Additional paths that indicate the IDE is configured
+    this.wdsFolderName = '_bmad/wds'; // Default, can be overridden
+  }
+
+  /**
+   * Set the WDS folder name for placeholder replacement
+   * @param {string} wdsFolderName - The WDS folder name
+   */
+  setWdsFolderName(wdsFolderName) {
+    this.wdsFolderName = wdsFolderName;
+  }
+
+  /**
+   * Main setup method - must be implemented by subclasses
+   * @param {string} projectDir - Project directory
+   * @param {string} wdsDir - WDS installation directory
+   * @param {Object} options - Setup options
+   */
+  async setup(projectDir, wdsDir, options = {}) {
+    throw new Error(`setup() must be implemented by ${this.name} handler`);
+  }
+
+  /**
+   * Cleanup IDE configuration
+   * @param {string} projectDir - Project directory
+   */
+  async cleanup(projectDir) {
+    // Default implementation - can be overridden
+    if (this.configDir) {
+      const configPath = path.join(projectDir, this.configDir);
+      if (await fs.pathExists(configPath)) {
+        await fs.remove(configPath);
+        console.log(chalk.dim(`Removed ${this.name} WDS configuration`));
+      }
+    }
+  }
+
+  /**
+   * Detect whether this IDE already has configuration in the project
+   * Subclasses can override for custom logic
+   * @param {string} projectDir - Project directory
+   * @returns {boolean}
+   */
+  async detect(projectDir) {
+    const pathsToCheck = [];
+
+    if (this.configDir) {
+      pathsToCheck.push(path.join(projectDir, this.configDir));
+    }
+
+    if (this.configFile) {
+      pathsToCheck.push(path.join(projectDir, this.configFile));
+    }
+
+    if (Array.isArray(this.detectionPaths)) {
+      for (const candidate of this.detectionPaths) {
+        if (!candidate) continue;
+        const resolved = path.isAbsolute(candidate) ? candidate : path.join(projectDir, candidate);
+        pathsToCheck.push(resolved);
+      }
+    }
+
+    for (const candidate of pathsToCheck) {
+      if (await fs.pathExists(candidate)) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Get list of agents from WDS installation
+   * @param {string} wdsDir - WDS installation directory
+   * @returns {Array} List of agent files with metadata
+   */
+  async getAgents(wdsDir) {
+    const agents = [];
+    const agentsPath = path.join(wdsDir, 'agents');
+
+    if (!(await fs.pathExists(agentsPath))) {
+      return agents;
+    }
+
+    const files = await fs.readdir(agentsPath);
+
+    for (const file of files) {
+      if (!file.endsWith('.md')) continue;
+
+      const filePath = path.join(agentsPath, file);
+      const agentName = file.replace('.md', '');
+
+      // Extract metadata from agent file
+      const metadata = await this.extractAgentMetadata(filePath);
+
+      // Create slug from agent name (e.g., 'saga-analyst' -> 'saga')
+      const slug = metadata.slug || agentName.split('-')[0];
+
+      agents.push({
+        name: agentName,
+        slug: slug,
+        path: filePath,
+        relativePath: path.relative(wdsDir, filePath),
+        filename: file,
+        metadata: metadata,
+      });
+    }
+
+    return agents;
+  }
+
+  /**
+   * Extract agent metadata from compiled agent markdown file
+   * Reads YAML frontmatter or fallback to defaults
+   * @param {string} filePath - Path to agent markdown file
+   * @returns {Object} Agent metadata
+   */
+  async extractAgentMetadata(filePath) {
+    try {
+      const content = await fs.readFile(filePath, 'utf8');
+
+      // Try to extract YAML frontmatter
+      const frontmatterMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
+      if (frontmatterMatch) {
+        const frontmatter = yaml.parse(frontmatterMatch[1]);
+
+        return {
+          name: frontmatter.name || path.basename(filePath, '.md'),
+          description: frontmatter.description || frontmatter.role || '',
+          icon: frontmatter.icon || '📋',
+          slug: frontmatter.id ? path.basename(frontmatter.id, '.md').split('-')[0] : null,
+        };
+      }
+
+      // Fallback: extract from filename
+      const agentName = path.basename(filePath, '.md');
+      return {
+        name: this.formatTitle(agentName),
+        description: agentName.includes('saga') ? 'Strategic Analyst' : agentName.includes('freya') ? 'Designer' : '',
+        icon: '📋',
+        slug: agentName.split('-')[0],
+      };
+    } catch {
+      // Fallback metadata on error
+      const agentName = path.basename(filePath, '.md');
+      return {
+        name: this.formatTitle(agentName),
+        description: '',
+        icon: '📋',
+        slug: agentName.split('-')[0],
+      };
+    }
+  }
+
+  /**
+   * Format agent launcher content that references the compiled agent
+   * @param {string} agentName - Agent name (e.g., 'saga-analyst')
+   * @param {string} agentPath - Relative path to agent file (e.g., 'agents/saga-analyst.md')
+   * @returns {string} Launcher content
+   */
+  formatAgentLauncher(agentName, agentPath) {
+    const relativePath = path.relative(process.cwd(), agentPath).replaceAll('\\', '/'); // Convert Windows paths to forward slashes
+
+    return `<!-- WDS Agent Launcher -->
+<!-- This file references the compiled agent. Do not edit directly. -->
+<!-- Source: ${this.wdsFolderName}/agents/${agentName}.md -->
+
+@include(${this.wdsFolderName}/agents/${agentName}.md)
+`;
+  }
+
+  /**
+   * Process content with IDE-specific frontmatter
+   * Subclasses must override this to add IDE-specific headers
+   * @param {string} content - Launcher content
+   * @param {Object} metadata - Agent metadata
+   * @returns {string} Processed content with IDE-specific frontmatter
+   */
+  processContent(content, metadata = {}) {
+    // Default implementation - subclasses should override
+    return content;
+  }
+
+  /**
+   * Ensure directory exists
+   * @param {string} dirPath - Directory path
+   */
+  async ensureDir(dirPath) {
+    await fs.ensureDir(dirPath);
+  }
+
+  /**
+   * Write file with content (replaces _wds placeholder)
+   * @param {string} filePath - File path
+   * @param {string} content - File content
+   */
+  async writeFile(filePath, content) {
+    // Replace _wds placeholder if present
+    if (typeof content === 'string' && content.includes('_wds')) {
+      content = content.replaceAll('_wds', this.wdsFolderName);
+    }
+
+    await this.ensureDir(path.dirname(filePath));
+    await fs.writeFile(filePath, content, 'utf8');
+  }
+
+  /**
+   * Check if path exists
+   * @param {string} pathToCheck - Path to check
+   * @returns {boolean} True if path exists
+   */
+  async exists(pathToCheck) {
+    return await fs.pathExists(pathToCheck);
+  }
+
+  /**
+   * Alias for exists method
+   * @param {string} pathToCheck - Path to check
+   * @returns {boolean} True if path exists
+   */
+  async pathExists(pathToCheck) {
+    return await fs.pathExists(pathToCheck);
+  }
+
+  /**
+   * Read file content
+   * @param {string} filePath - File path
+   * @returns {string} File content
+   */
+  async readFile(filePath) {
+    return await fs.readFile(filePath, 'utf8');
+  }
+
+  /**
+   * Format name as title
+   * @param {string} name - Name to format (e.g., 'saga-analyst')
+   * @returns {string} Formatted title (e.g., 'Saga Analyst')
+   */
+  formatTitle(name) {
+    return name
+      .split('-')
+      .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+      .join(' ');
+  }
+}
+
+module.exports = { BaseIdeSetup };

package/tools/cli/installers/lib/ide/antigravity.js

@@ -0,0 +1,34 @@
+const path = require('node:path');
+const { BaseIdeSetup } = require('./_base-ide');
+
+/**
+ * Antigravity IDE setup handler for WDS
+ */
+class AntigravitySetup extends BaseIdeSetup {
+  constructor() {
+    super('antigravity', 'Antigravity', false);
+    this.configDir = '.agent/workflows/wds';
+  }
+
+  async setup(projectDir, wdsDir, options = {}) {
+    const targetDir = path.join(projectDir, this.configDir);
+    await this.ensureDir(targetDir);
+
+    const agents = await this.getAgents(wdsDir);
+    if (agents.length === 0) throw new Error('No agents found in WDS installation');
+
+    for (const agent of agents) {
+      const launcher = this.formatAgentLauncher(agent.name, agent.path);
+      // Antigravity uses no frontmatter
+      await this.writeFile(path.join(targetDir, `${agent.slug}.md`), launcher);
+    }
+
+    return { success: true, agents: agents.length };
+  }
+
+  async detect(projectDir) {
+    return await this.exists(path.join(projectDir, '.agent'));
+  }
+}
+
+module.exports = { AntigravitySetup };

package/tools/cli/installers/lib/ide/auggie.js

@@ -0,0 +1,42 @@
+const path = require('node:path');
+const { BaseIdeSetup } = require('./_base-ide');
+
+/**
+ * Auggie CLI setup handler for WDS
+ */
+class AuggieSetup extends BaseIdeSetup {
+  constructor() {
+    super('auggie', 'Auggie CLI', false);
+    this.configDir = '.augment/commands/wds';
+  }
+
+  async setup(projectDir, wdsDir, options = {}) {
+    const targetDir = path.join(projectDir, this.configDir);
+    await this.ensureDir(targetDir);
+
+    const agents = await this.getAgents(wdsDir);
+    if (agents.length === 0) throw new Error('No agents found in WDS installation');
+
+    for (const agent of agents) {
+      const launcher = this.formatAgentLauncher(agent.name, agent.path);
+      const content = this.processContent(launcher, agent.metadata);
+      await this.writeFile(path.join(targetDir, `${agent.slug}.md`), content);
+    }
+
+    return { success: true, agents: agents.length };
+  }
+
+  processContent(content, metadata = {}) {
+    return `---
+description: ${metadata.name || 'WDS Agent'} - ${metadata.description || 'Agent'}
+---
+
+${content}`;
+  }
+
+  async detect(projectDir) {
+    return await this.exists(path.join(projectDir, '.augment'));
+  }
+}
+
+module.exports = { AuggieSetup };

package/tools/cli/installers/lib/ide/claude-code.js

@@ -0,0 +1,114 @@
+const path = require('node:path');
+const { BaseIdeSetup } = require('./_base-ide');
+const chalk = require('chalk');
+
+/**
+ * Claude Code IDE setup handler for WDS
+ */
+class ClaudeCodeSetup extends BaseIdeSetup {
+  constructor() {
+    super('claude-code', 'Claude Code', true); // preferred IDE
+    this.configDir = '.claude/skills/wds';
+  }
+
+  /**
+   * Setup Claude Code IDE configuration
+   * @param {string} projectDir - Project directory
+   * @param {string} wdsDir - WDS installation directory
+   * @param {Object} options - Setup options
+   */
+  async setup(projectDir, wdsDir, options = {}) {
+    // Create .claude/skills/wds directory
+    const targetDir = path.join(projectDir, this.configDir);
+    await this.ensureDir(targetDir);
+
+    // Get all WDS agents
+    const agents = await this.getAgents(wdsDir);
+
+    if (agents.length === 0) {
+      throw new Error('No agents found in WDS installation');
+    }
+
+    // Create launcher file for each agent
+    let agentCount = 0;
+    for (const agent of agents) {
+      // Create launcher content that references the compiled agent
+      const launcher = this.formatAgentLauncher(agent.name, agent.path);
+
+      // Add Claude Code-specific YAML frontmatter
+      const content = this.processContent(launcher, agent.metadata);
+
+      // Write launcher file
+      const filePath = path.join(targetDir, `${agent.slug}.md`);
+      await this.writeFile(filePath, content);
+      agentCount++;
+    }
+
+    if (options.logger) {
+      options.logger.log(chalk.dim(`    - ${agentCount} agent(s) configured for Claude Code`));
+    }
+
+    return {
+      success: true,
+      agents: agentCount,
+    };
+  }
+
+  /**
+   * Process content with Claude Code-specific YAML frontmatter
+   * @param {string} content - Launcher content
+   * @param {Object} metadata - Agent metadata
+   * @returns {string} Processed content with Claude Code YAML frontmatter
+   */
+  processContent(content, metadata = {}) {
+    // Strip any existing frontmatter from launcher
+    const frontmatterRegex = /^---\s*\n[\s\S]*?\n---\s*\n/;
+    const contentWithoutFrontmatter = content.replace(frontmatterRegex, '');
+
+    const name = metadata.name || 'WDS Agent';
+    const description = metadata.description || 'Agent';
+
+    // Create Claude Code YAML metadata header
+    const yamlHeader = `---
+name: ${name}
+description: ${description}
+---
+
+`;
+
+    return yamlHeader + contentWithoutFrontmatter;
+  }
+
+  /**
+   * Cleanup Claude Code WDS configuration
+   * @param {string} projectDir - Project directory
+   */
+  async cleanup(projectDir) {
+    const wdsPath = path.join(projectDir, this.configDir);
+
+    if (await this.exists(wdsPath)) {
+      await this.remove(wdsPath);
+      console.log(chalk.dim(`Removed Claude Code WDS configuration`));
+    }
+  }
+
+  /**
+   * Detect if Claude Code is configured in project
+   * @param {string} projectDir - Project directory
+   * @returns {boolean}
+   */
+  async detect(projectDir) {
+    return await this.exists(path.join(projectDir, '.claude'));
+  }
+
+  /**
+   * Remove directory helper
+   * @param {string} dirPath - Directory to remove
+   */
+  async remove(dirPath) {
+    const fs = require('fs-extra');
+    await fs.remove(dirPath);
+  }
+}
+
+module.exports = { ClaudeCodeSetup };

package/tools/cli/installers/lib/ide/cline.js

@@ -0,0 +1,116 @@
+const path = require('node:path');
+const { BaseIdeSetup } = require('./_base-ide');
+const chalk = require('chalk');
+
+/**
+ * Cline IDE setup handler for WDS
+ */
+class ClineSetup extends BaseIdeSetup {
+  constructor() {
+    super('cline', 'Cline', false);
+    this.configDir = '.cline';
+  }
+
+  /**
+   * Setup Cline IDE configuration
+   * @param {string} projectDir - Project directory
+   * @param {string} wdsDir - WDS installation directory
+   * @param {Object} options - Setup options
+   */
+  async setup(projectDir, wdsDir, options = {}) {
+    // Create .cline directory
+    const targetDir = path.join(projectDir, this.configDir);
+    await this.ensureDir(targetDir);
+
+    // Get all WDS agents
+    const agents = await this.getAgents(wdsDir);
+
+    if (agents.length === 0) {
+      throw new Error('No agents found in WDS installation');
+    }
+
+    // Create launcher file for each agent
+    let agentCount = 0;
+    for (const agent of agents) {
+      // Create launcher content that references the compiled agent
+      const launcher = this.formatAgentLauncher(agent.name, agent.path);
+
+      // Add Cline-specific formatting (flat markdown, no frontmatter)
+      const content = this.processContent(launcher, agent.metadata);
+
+      // Write launcher file
+      const filePath = path.join(targetDir, `${agent.slug}.md`);
+      await this.writeFile(filePath, content);
+      agentCount++;
+    }
+
+    if (options.logger) {
+      options.logger.log(chalk.dim(`    - ${agentCount} agent(s) configured for Cline`));
+    }
+
+    return {
+      success: true,
+      agents: agentCount,
+    };
+  }
+
+  /**
+   * Process content with Cline-specific formatting
+   * Cline uses flat markdown with no frontmatter
+   * @param {string} content - Launcher content
+   * @param {Object} metadata - Agent metadata
+   * @returns {string} Processed content without frontmatter
+   */
+  processContent(content, metadata = {}) {
+    // Strip any existing frontmatter from launcher
+    const frontmatterRegex = /^---\s*\n[\s\S]*?\n---\s*\n/;
+    const contentWithoutFrontmatter = content.replace(frontmatterRegex, '');
+
+    // Add title header for Cline
+    const title = metadata.name ? `${metadata.name} - ${metadata.description}` : metadata.description || 'WDS Agent';
+
+    return `# ${title}
+
+${contentWithoutFrontmatter}`;
+  }
+
+  /**
+   * Cleanup Cline WDS configuration
+   * @param {string} projectDir - Project directory
+   */
+  async cleanup(projectDir) {
+    const wdsPath = path.join(projectDir, this.configDir);
+
+    if (await this.exists(wdsPath)) {
+      // Only remove WDS agent files, not entire .cline directory
+      const agents = ['saga.md', 'freya.md'];
+      for (const agentFile of agents) {
+        const filePath = path.join(wdsPath, agentFile);
+        if (await this.exists(filePath)) {
+          await this.removeFile(filePath);
+        }
+      }
+      console.log(chalk.dim(`Removed Cline WDS configuration`));
+    }
+  }
+
+  /**
+   * Detect if Cline is configured in project
+   * @param {string} projectDir - Project directory
+   * @returns {boolean}
+   */
+  async detect(projectDir) {
+    return await this.exists(path.join(projectDir, '.cline'));
+  }
+
+  /**
+   * Remove file helper
+   * @param {string} filePath - File to remove
+   */
+  async removeFile(filePath) {
+    const fs = require('fs-extra');
+    await fs.remove(filePath);
+  }
+}
+
+module.exports = { ClineSetup };

package/tools/cli/installers/lib/ide/codex.js

@@ -0,0 +1,43 @@
+const path = require('node:path');
+const { BaseIdeSetup } = require('./_base-ide');
+
+/**
+ * Codex IDE setup handler for WDS
+ */
+class CodexSetup extends BaseIdeSetup {
+  constructor() {
+    super('codex', 'Codex', false);
+    this.configDir = '.codex/prompts/wds';
+  }
+
+  async setup(projectDir, wdsDir, options = {}) {
+    const targetDir = path.join(projectDir, this.configDir);
+    await this.ensureDir(targetDir);
+
+    const agents = await this.getAgents(wdsDir);
+    if (agents.length === 0) throw new Error('No agents found in WDS installation');
+
+    for (const agent of agents) {
+      const launcher = this.formatAgentLauncher(agent.name, agent.path);
+      const content = this.processContent(launcher, agent.metadata);
+      await this.writeFile(path.join(targetDir, `${agent.slug}.md`), content);
+    }
+
+    return { success: true, agents: agents.length };
+  }
+
+  processContent(content, metadata = {}) {
+    return `---
+name: ${metadata.name || 'WDS Agent'}
+description: ${metadata.description || 'Agent'}
+---
+
+${content}`;
+  }
+
+  async detect(projectDir) {
+    return await this.exists(path.join(projectDir, '.codex'));
+  }
+}
+
+module.exports = { CodexSetup };

package/tools/cli/installers/lib/ide/crush.js

@@ -0,0 +1,42 @@
+const path = require('node:path');
+const { BaseIdeSetup } = require('./_base-ide');
+
+/**
+ * Crush IDE setup handler for WDS
+ */
+class CrushSetup extends BaseIdeSetup {
+  constructor() {
+    super('crush', 'Crush', false);
+    this.configDir = '.crush/commands/wds';
+  }
+
+  async setup(projectDir, wdsDir, options = {}) {
+    const targetDir = path.join(projectDir, this.configDir);
+    await this.ensureDir(targetDir);
+
+    const agents = await this.getAgents(wdsDir);
+    if (agents.length === 0) throw new Error('No agents found in WDS installation');
+
+    for (const agent of agents) {
+      const launcher = this.formatAgentLauncher(agent.name, agent.path);
+      const content = this.processContent(launcher, agent.metadata);
+      await this.writeFile(path.join(targetDir, `${agent.slug}.md`), content);
+    }
+
+    return { success: true, agents: agents.length };
+  }
+
+  processContent(content, metadata = {}) {
+    const title = metadata.name ? `${metadata.name} - ${metadata.description}` : metadata.description || 'WDS Agent';
+
+    return `# ${title}
+
+${content}`;
+  }
+
+  async detect(projectDir) {
+    return await this.exists(path.join(projectDir, '.crush'));
+  }
+}
+
+module.exports = { CrushSetup };