agileflow 3.4.3 → 4.0.0-alpha.2

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

@@ -1,426 +0,0 @@
-/**
- * AgileFlow CLI - OpenAI Codex Installer
- *
- * Installs AgileFlow for OpenAI Codex:
- * - Agents become Codex Skills (.codex/skills/agileflow-NAME/)
- * - Commands become Codex Prompts (~/.codex/prompts/agileflow-NAME.md)
- * - AGENTS.md provides project instructions at repo root
- *
- * @see https://developers.openai.com/codex/
- * @see ADR-0002: OpenAI Codex Integration Strategy
- */
-
-const path = require('node:path');
-const os = require('node:os');
-const fs = require('fs-extra');
-const chalk = require('chalk');
-const { yaml } = require('../../../../lib/yaml-utils');
-const { BaseIdeSetup } = require('./_base-ide');
-const {
-  getFrontmatter,
-  stripFrontmatter,
-  replaceReferences,
-  IDE_REPLACEMENTS,
-} = require('../../lib/content-transformer');
-
-/**
- * OpenAI Codex setup handler
- */
-class CodexSetup extends BaseIdeSetup {
-  constructor() {
-    super('codex', 'OpenAI Codex', false);
-    // Per-repo config directory
-    this.configDir = '.codex';
-    // User-level Codex home (can be overridden by $CODEX_HOME)
-    this.codexHome = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
-  }
-
-  /**
-   * Get the Codex home directory
-   * @returns {string} Path to ~/.codex or $CODEX_HOME
-   */
-  getCodexHome() {
-    return this.codexHome;
-  }
-
-  /**
-   * Detect if OpenAI Codex is installed/configured
-   * @param {string} projectDir - Project directory
-   * @returns {Promise<boolean>}
-   */
-  async detect(projectDir) {
-    // Check if Codex home exists (user has OpenAI Codex)
-    const codexHomeExists = await this.exists(this.codexHome);
-    // Check if project has .codex/ or AGENTS.md
-    const projectCodexExists = await this.exists(path.join(projectDir, this.configDir));
-    const agentsMdExists = await this.exists(path.join(projectDir, 'AGENTS.md'));
-
-    return codexHomeExists || projectCodexExists || agentsMdExists;
-  }
-
-  /**
-   * Convert an AgileFlow agent markdown file to Codex SKILL.md format
-   * Uses content-transformer module for consistent transformations
-   * @param {string} content - Original agent markdown content
-   * @param {string} agentName - Agent name (e.g., 'database')
-   * @returns {string} Codex SKILL.md content
-   */
-  convertAgentToSkill(content, agentName) {
-    // Extract frontmatter using content-transformer
-    const frontmatter = getFrontmatter(content);
-    const description = frontmatter.description || `AgileFlow ${agentName} agent`;
-
-    // Create SKILL.md with YAML frontmatter
-    const skillFrontmatter = yaml
-      .dump({
-        name: `agileflow-${agentName}`,
-        description: description,
-        version: '1.0.0',
-      })
-      .trim();
-
-    // Remove original frontmatter from content using content-transformer
-    let bodyContent = stripFrontmatter(content);
-
-    // Add Codex-specific header
-    const codexHeader = `# AgileFlow: ${agentName.charAt(0).toUpperCase() + agentName.slice(1)} Agent
-
-> Invoke with \`$agileflow-${agentName}\` or via \`/skills\`
-
-`;
-
-    // Replace Claude-specific references using content-transformer
-    bodyContent = replaceReferences(bodyContent, IDE_REPLACEMENTS.codex);
-
-    // Replace /agileflow: prefix and all subsequent colons for Codex compatibility
-    // e.g., /agileflow:story:list → $agileflow-story-list
-    bodyContent = bodyContent.replace(/\/agileflow:([a-zA-Z0-9:_-]+)/g, (_match, rest) => {
-      return '$agileflow-' + rest.replace(/:/g, '-');
-    });
-
-    return `---
-${skillFrontmatter}
----
-
-${codexHeader}${bodyContent}`;
-  }
-
-  /**
-   * Convert an AgileFlow command markdown file to Codex prompt format
-   * Uses content-transformer module for consistent transformations
-   * @param {string} content - Original command markdown content
-   * @param {string} commandName - Command name (e.g., 'board')
-   * @returns {string} Codex prompt content
-   */
-  convertCommandToPrompt(content, commandName) {
-    // Extract description from frontmatter using content-transformer
-    const frontmatter = getFrontmatter(content);
-    const description = frontmatter.description || `AgileFlow ${commandName} command`;
-
-    // Remove original frontmatter from content using content-transformer
-    let bodyContent = stripFrontmatter(content);
-
-    // Replace Claude-specific references using content-transformer
-    bodyContent = replaceReferences(bodyContent, IDE_REPLACEMENTS.codex);
-
-    // Replace /agileflow: prefix and all subsequent colons for Codex compatibility
-    // e.g., /agileflow:story:list → $agileflow-story-list
-    bodyContent = bodyContent.replace(/\/agileflow:([a-zA-Z0-9:_-]+)/g, (_match, rest) => {
-      return '$agileflow-' + rest.replace(/:/g, '-');
-    });
-
-    // Add Codex prompt header
-    const header = `# AgileFlow: ${commandName}
-
-> ${description}
-
-## Instructions
-
-`;
-
-    // Add input placeholder at the end
-    const footer = `
-
-## Context
-
-{{input}}
-`;
-
-    return `${header}${bodyContent}${footer}`;
-  }
-
-  /**
-   * Install AgileFlow agents as Codex skills
-   * @param {string} projectDir - Project directory
-   * @param {string} agileflowDir - AgileFlow installation directory
-   * @returns {Promise<number>} Number of skills installed
-   */
-  async installSkills(projectDir, agileflowDir) {
-    const agentsSource = path.join(agileflowDir, 'agents');
-    const skillsTarget = path.join(projectDir, this.configDir, 'skills');
-
-    if (!(await this.exists(agentsSource))) {
-      return 0;
-    }
-
-    let skillCount = 0;
-    const agents = await this.scanDirectory(agentsSource, '.md');
-
-    for (const agent of agents) {
-      const content = await this.readFile(agent.path);
-      const skillContent = this.convertAgentToSkill(content, agent.name);
-
-      // Create skill directory: .codex/skills/agileflow-{name}/
-      const skillDir = path.join(skillsTarget, `agileflow-${agent.name}`);
-      await this.ensureDir(skillDir);
-
-      // Write SKILL.md
-      await this.writeFile(path.join(skillDir, 'SKILL.md'), skillContent);
-      skillCount++;
-    }
-
-    return skillCount;
-  }
-
-  /**
-   * Install AgileFlow commands as Codex prompts (user-level)
-   * @param {string} agileflowDir - AgileFlow installation directory
-   * @returns {Promise<number>} Number of prompts installed
-   */
-  async installPrompts(agileflowDir) {
-    const commandsSource = path.join(agileflowDir, 'commands');
-    const promptsTarget = path.join(this.codexHome, 'prompts');
-
-    if (!(await this.exists(commandsSource))) {
-      return 0;
-    }
-
-    await this.ensureDir(promptsTarget);
-
-    let promptCount = 0;
-    const commands = await this.scanDirectory(commandsSource, '.md');
-
-    for (const command of commands) {
-      const content = await this.readFile(command.path);
-      const promptContent = this.convertCommandToPrompt(content, command.name);
-
-      // Write prompt: ~/.codex/prompts/agileflow-{name}.md
-      const promptPath = path.join(promptsTarget, `agileflow-${command.name}.md`);
-      await this.writeFile(promptPath, promptContent);
-      promptCount++;
-    }
-
-    return promptCount;
-  }
-
-  /**
-   * Generate AGENTS.md scaffolding for the project
-   * @param {string} projectDir - Project directory
-   * @returns {Promise<boolean>} Whether AGENTS.md was created
-   */
-  async generateAgentsMd(projectDir) {
-    const agentsMdPath = path.join(projectDir, 'AGENTS.md');
-
-    // Don't overwrite existing AGENTS.md
-    if (await this.exists(agentsMdPath)) {
-      console.log(chalk.dim(`    - AGENTS.md already exists (preserved)`));
-      return false;
-    }
-
-    const content = `# AGENTS.md
-
-> Project instructions for OpenAI Codex with AgileFlow integration
-
-## Project Commands
-
-\`\`\`bash
-# Run tests
-npm test
-
-# Lint code
-npm run lint
-
-# Build project
-npm run build
-\`\`\`
-
-## Conventions
-
-- Prefer running tests before claiming success
-- Keep changes small and reviewable
-- Use AgileFlow skills when relevant (see below)
-- Check \`${this.docsFolder}/09-agents/status.json\` for current work status
-
-## When to Use AgileFlow Skills
-
-Invoke skills with \`$skill-name\` or list available skills with \`/skills\`.
-
-| Task Type | Skill to Use |
-|-----------|--------------|
-| Architecture decisions | \`$agileflow-adr-writer\` |
-| Database work | \`$agileflow-database\` |
-| API endpoints | \`$agileflow-api\` |
-| UI components | \`$agileflow-ui\` |
-| Testing | \`$agileflow-testing\` |
-| CI/CD setup | \`$agileflow-ci\` |
-| Security review | \`$agileflow-security\` |
-| Performance | \`$agileflow-performance\` |
-| Documentation | \`$agileflow-documentation\` |
-
-## AgileFlow Status
-
-- **Stories**: \`${this.docsFolder}/09-agents/status.json\`
-- **Research**: \`${this.docsFolder}/10-research/\`
-- **Decisions**: \`${this.docsFolder}/03-decisions/\`
-- **Epics**: \`${this.docsFolder}/05-epics/\`
-
-## Security Recommendations
-
-For safe operation, configure Codex with:
-
-\`\`\`toml
-# ~/.codex/config.toml
-approval_policy = "on-request"
-sandbox_mode = "workspace-write"
-\`\`\`
-
----
-
-*Generated by AgileFlow - https://github.com/projectquestorg/AgileFlow*
-`;
-
-    await this.writeFile(agentsMdPath, content);
-    return true;
-  }
-
-  /**
-   * Generate AGENTS.override.md template for subdirectories
-   * @param {string} targetDir - Directory to create override in
-   * @returns {Promise<boolean>} Whether file was created
-   */
-  async generateAgentsOverride(targetDir) {
-    const overridePath = path.join(targetDir, 'AGENTS.override.md');
-
-    // Don't overwrite existing override
-    if (await this.exists(overridePath)) {
-      return false;
-    }
-
-    const content = `# AGENTS.override.md
-
-> Override instructions for this subdirectory
-
-## Directory-Specific Context
-
-This directory contains: [describe purpose]
-
-## Additional Commands
-
-\`\`\`bash
-# Directory-specific commands here
-\`\`\`
-
-## Directory Conventions
-
-- [List any patterns specific to this directory]
-
----
-
-*This file overrides AGENTS.md for this subdirectory*
-`;
-
-    await this.writeFile(overridePath, content);
-    return true;
-  }
-
-  /**
-   * Setup OpenAI Codex configuration
-   * @param {string} projectDir - Project directory
-   * @param {string} agileflowDir - AgileFlow installation directory
-   * @param {Object} options - Setup options
-   */
-  async setup(projectDir, agileflowDir, options = {}) {
-    console.log(chalk.hex('#e8683a')(`  Setting up ${this.displayName}...`));
-
-    // Clean up old installation first
-    await this.cleanup(projectDir);
-
-    // Ensure .codex directory exists
-    await this.ensureDir(path.join(projectDir, this.configDir));
-
-    // 1. Install agents as skills (per-repo)
-    const skillCount = await this.installSkills(projectDir, agileflowDir);
-    if (skillCount > 0) {
-      console.log(chalk.dim(`    - ${skillCount} skills installed to .codex/skills/`));
-    }
-
-    // 2. Install commands as prompts (user-level)
-    const promptCount = await this.installPrompts(agileflowDir);
-    if (promptCount > 0) {
-      console.log(chalk.dim(`    - ${promptCount} prompts installed to ~/.codex/prompts/`));
-    }
-
-    // 3. Generate AGENTS.md if it doesn't exist
-    const agentsMdCreated = await this.generateAgentsMd(projectDir);
-    if (agentsMdCreated) {
-      console.log(chalk.dim(`    - AGENTS.md created at project root`));
-    }
-
-    console.log(chalk.green(`  ✓ ${this.displayName} configured`));
-    console.log(chalk.dim(`    - Skills: .codex/skills/agileflow-*/`));
-    console.log(chalk.dim(`    - Prompts: ~/.codex/prompts/agileflow-*.md`));
-    console.log(chalk.dim(`    - Instructions: AGENTS.md`));
-
-    return {
-      success: true,
-      skills: skillCount,
-      prompts: promptCount,
-      agentsMd: agentsMdCreated,
-    };
-  }
-
-  /**
-   * Cleanup Codex configuration
-   * @param {string} projectDir - Project directory
-   * @param {Object} options - Cleanup options
-   * @param {boolean} options.removeAgentsMd - Also remove AGENTS.md (requires confirmation)
-   */
-  async cleanup(projectDir, options = {}) {
-    // Clean up per-repo skills
-    const skillsDir = path.join(projectDir, this.configDir, 'skills');
-    if (await this.exists(skillsDir)) {
-      const entries = await fs.readdir(skillsDir);
-      for (const entry of entries) {
-        if (entry.startsWith('agileflow-')) {
-          await fs.remove(path.join(skillsDir, entry));
-        }
-      }
-      console.log(chalk.dim(`  Cleaned up AgileFlow skills from .codex/skills/`));
-    }
-
-    // Clean up user-level prompts
-    const promptsDir = path.join(this.codexHome, 'prompts');
-    if (await this.exists(promptsDir)) {
-      const entries = await fs.readdir(promptsDir);
-      for (const entry of entries) {
-        if (entry.startsWith('agileflow-')) {
-          await fs.remove(path.join(promptsDir, entry));
-        }
-      }
-      console.log(chalk.dim(`  Cleaned up AgileFlow prompts from ~/.codex/prompts/`));
-    }
-
-    // Optionally remove AGENTS.md if explicitly requested
-    if (options.removeAgentsMd) {
-      const agentsMdPath = path.join(projectDir, 'AGENTS.md');
-      if (await this.exists(agentsMdPath)) {
-        await fs.remove(agentsMdPath);
-        console.log(chalk.dim(`  Removed AGENTS.md`));
-      }
-    } else {
-      console.log(chalk.dim(`  Note: AGENTS.md preserved (use removeAgentsMd option to delete)`));
-    }
-  }
-}
-
-module.exports = { CodexSetup };

package/tools/cli/installers/ide/cursor.js

@@ -1,217 +0,0 @@
-/**
- * AgileFlow CLI - Cursor IDE Installer
- *
- * Installs AgileFlow commands, agents, and hooks for Cursor IDE.
- * Cursor uses:
- * - Plain Markdown files in .cursor/commands/ for slash commands
- * - Markdown files in .cursor/agents/ for subagents (with YAML frontmatter)
- * - .cursor/hooks.json for lifecycle hooks
- */
-
-const path = require('node:path');
-const fs = require('fs-extra');
-const chalk = require('chalk');
-const { BaseIdeSetup } = require('./_base-ide');
-
-/**
- * Cursor IDE setup handler
- */
-class CursorSetup extends BaseIdeSetup {
-  constructor() {
-    super('cursor', 'Cursor', false);
-    this.configDir = '.cursor';
-    this.commandsDir = 'commands';
-  }
-
-  /**
-   * Setup Cursor IDE configuration
-   * @param {string} projectDir - Project directory
-   * @param {string} agileflowDir - AgileFlow installation directory
-   * @param {Object} options - Setup options
-   */
-  async setup(projectDir, agileflowDir, options = {}) {
-    // Use standard setup for commands and agents
-    const result = await this.setupStandard(projectDir, agileflowDir, {
-      targetSubdir: this.commandsDir,
-      agileflowFolder: 'AgileFlow',
-    });
-
-    const { ideDir, agileflowTargetDir } = result;
-    const agentsSource = path.join(agileflowDir, 'agents');
-
-    // Cursor specific: Install agents as spawnable subagents (.cursor/agents/AgileFlow/)
-    // This allows Cursor's async subagent spawning feature
-    const spawnableAgentsDir = path.join(ideDir, 'agents', 'AgileFlow');
-
-    // Clean existing spawnable agents directory to prevent duplicates during update
-    if (await fs.pathExists(spawnableAgentsDir)) {
-      await fs.remove(spawnableAgentsDir);
-    }
-
-    const agentInstallResult = await this.installCommandsRecursive(
-      agentsSource,
-      spawnableAgentsDir,
-      agileflowDir,
-      false
-    );
-    console.log(chalk.dim(`    - Spawnable agents: .cursor/agents/AgileFlow/`));
-
-    // Cursor specific: Setup damage control hooks
-    await this.setupDamageControlHooks(projectDir, agileflowDir, ideDir, options);
-
-    return {
-      ...result,
-      agents: agentInstallResult.commands,
-    };
-  }
-
-  /**
-   * Setup damage control hooks for Cursor
-   * Maps Claude Code's PreToolUse hooks to Cursor's lifecycle events:
-   * - beforeShellExecution (for bash commands)
-   * - afterFileEdit (for file edits)
-   *
-   * @param {string} projectDir - Project directory
-   * @param {string} agileflowDir - AgileFlow installation directory
-   * @param {string} cursorDir - .cursor directory path
-   * @param {Object} options - Setup options
-   */
-  async setupDamageControlHooks(projectDir, agileflowDir, cursorDir, options = {}) {
-    if (options.skipDamageControl) {
-      return;
-    }
-
-    const hooksPath = path.join(cursorDir, 'hooks.json');
-    let hooks = [];
-
-    // Load existing hooks if they exist
-    if (fs.existsSync(hooksPath)) {
-      try {
-        const content = await fs.readFile(hooksPath, 'utf8');
-        hooks = JSON.parse(content);
-        if (!Array.isArray(hooks)) {
-          hooks = [];
-        }
-      } catch (e) {
-        hooks = [];
-      }
-    }
-
-    // Define damage control hooks for Cursor
-    // Cursor's hooks.json format: Array of {event, command, args, order}
-    const damageControlHooks = [
-      {
-        event: 'beforeShellExecution',
-        command: 'node',
-        args: ['$CURSOR_PROJECT_DIR/.cursor/hooks/damage-control/bash-tool-damage-control.js'],
-        order: 1,
-      },
-      {
-        event: 'afterFileEdit',
-        command: 'node',
-        args: ['$CURSOR_PROJECT_DIR/.cursor/hooks/damage-control/edit-tool-damage-control.js'],
-        order: 1,
-      },
-    ];
-
-    // Check if damage control hooks already exist and merge
-    let hasUpdates = false;
-    for (const newHook of damageControlHooks) {
-      const existingIdx = hooks.findIndex(
-        h =>
-          h.event === newHook.event &&
-          h.command === newHook.command &&
-          (h.args?.join(' ') === newHook.args?.join(' ') ||
-            (h.args && h.args.some(arg => arg.includes('damage-control'))))
-      );
-
-      if (existingIdx === -1) {
-        hooks.push(newHook);
-        hasUpdates = true;
-      }
-    }
-
-    // Only write if we have updates or if file didn't exist
-    if (hasUpdates || !fs.existsSync(hooksPath)) {
-      await fs.ensureDir(path.dirname(hooksPath));
-      await fs.writeFile(hooksPath, JSON.stringify(hooks, null, 2));
-      console.log(chalk.dim(`    - Damage control: hooks enabled`));
-    }
-
-    // Copy damage control scripts
-    await this.setupDamageControlScripts(agileflowDir, cursorDir);
-  }
-
-  /**
-   * Copy damage control scripts to .cursor/hooks/damage-control/
-   * @param {string} agileflowDir - AgileFlow installation directory
-   * @param {string} cursorDir - .cursor directory path
-   */
-  async setupDamageControlScripts(agileflowDir, cursorDir) {
-    const damageControlSource = path.join(agileflowDir, 'scripts', 'damage-control');
-    const damageControlTarget = path.join(cursorDir, 'hooks', 'damage-control');
-
-    if (!fs.existsSync(damageControlSource)) {
-      return;
-    }
-
-    await this.ensureDir(damageControlTarget);
-
-    // Copy hook scripts
-    const scripts = [
-      'bash-tool-damage-control.js',
-      'edit-tool-damage-control.js',
-      'write-tool-damage-control.js',
-    ];
-
-    for (const script of scripts) {
-      const src = path.join(damageControlSource, script);
-      const dest = path.join(damageControlTarget, script);
-      if (fs.existsSync(src)) {
-        await fs.copy(src, dest);
-      }
-    }
-
-    // Copy lib/damage-control-utils.js (required by hook scripts)
-    const libSource = path.join(agileflowDir, 'scripts', 'lib', 'damage-control-utils.js');
-    const libTarget = path.join(cursorDir, 'hooks', 'lib', 'damage-control-utils.js');
-    if (fs.existsSync(libSource)) {
-      await this.ensureDir(path.dirname(libTarget));
-      await fs.copy(libSource, libTarget);
-    }
-
-    // Copy patterns.yaml (preserve existing)
-    const patternsSource = path.join(damageControlSource, 'patterns.yaml');
-    const patternsTarget = path.join(damageControlTarget, 'patterns.yaml');
-    if (fs.existsSync(patternsSource) && !fs.existsSync(patternsTarget)) {
-      await fs.copy(patternsSource, patternsTarget);
-    }
-  }
-
-  /**
-   * Cleanup old AgileFlow installation
-   * @param {string} projectDir - Project directory
-   */
-  async cleanup(projectDir) {
-    // Remove old .cursor/rules/agileflow (deprecated)
-    const oldRulesPath = path.join(projectDir, this.configDir, 'rules', 'agileflow');
-    if (await this.exists(oldRulesPath)) {
-      await fs.remove(oldRulesPath);
-      console.log(chalk.dim(`    Removed old AgileFlow rules from ${this.displayName}`));
-    }
-
-    // Remove .cursor/commands/AgileFlow (for re-installation)
-    const commandsPath = path.join(projectDir, this.configDir, this.commandsDir, 'AgileFlow');
-    if (await this.exists(commandsPath)) {
-      await fs.remove(commandsPath);
-    }
-
-    // Remove .cursor/agents/AgileFlow (for re-installation)
-    const agentsPath = path.join(projectDir, this.configDir, 'agents', 'AgileFlow');
-    if (await this.exists(agentsPath)) {
-      await fs.remove(agentsPath);
-    }
-  }
-}
-
-module.exports = { CursorSetup };