prr-kit 1.0.0

package/tools/cli/installers/lib/core/manifest-generator.js

@@ -0,0 +1,172 @@
+/**
+ * Manifest Generator — scans installed modules and generates CSV manifests
+ */
+const path = require('node:path');
+const fs = require('fs-extra');
+const yaml = require('yaml');
+const { glob } = require('glob');
+
+class ManifestGenerator {
+  constructor() {
+    this.workflows = [];
+    this.agents = [];
+    this.tasks = [];
+    this.prrDir = null;
+  }
+
+  async generateManifests(prrDir, selectedModules, options = {}) {
+    const cfgDir = path.join(prrDir, '_config');
+    await fs.ensureDir(cfgDir);
+
+    this.prrDir = prrDir;
+
+    const allModules = [...new Set(['core', ...selectedModules])];
+
+    await this.collectWorkflows(allModules);
+    await this.collectAgents(allModules);
+    await this.collectTasks(allModules);
+
+    await this.writeWorkflowManifest(cfgDir);
+    await this.writeAgentManifest(cfgDir);
+    await this.writeTaskManifest(cfgDir);
+
+    return {
+      workflows: this.workflows.length,
+      agents: this.agents.length,
+      tasks: this.tasks.length,
+    };
+  }
+
+  async collectWorkflows(modules) {
+    this.workflows = [];
+    for (const mod of modules) {
+      const workflowsPath = path.join(this.prrDir, mod, 'workflows');
+      if (!(await fs.pathExists(workflowsPath))) continue;
+
+      const files = await glob('**/workflow{.md,.yaml}', { cwd: workflowsPath });
+      for (const file of files) {
+        const fullPath = path.join(workflowsPath, file);
+        const info = await this.parseWorkflowFile(fullPath, mod, file);
+        if (info) this.workflows.push(info);
+      }
+    }
+  }
+
+  async parseWorkflowFile(filePath, moduleName, relPath) {
+    try {
+      const content = await fs.readFile(filePath, 'utf8');
+      let name = path.basename(path.dirname(relPath));
+      let description = '';
+
+      if (filePath.endsWith('.yaml')) {
+        const data = yaml.parse(content);
+        name = data.name || name;
+        description = data.description || '';
+      } else {
+        // Parse markdown frontmatter
+        const match = content.match(/^---\n([\s\S]*?)\n---/);
+        if (match) {
+          try {
+            const fm = yaml.parse(match[1]);
+            name = fm.name || name;
+            description = fm.description || '';
+          } catch { /* ignore */ }
+        }
+      }
+
+      return {
+        module: moduleName,
+        name,
+        description,
+        path: path.join('_prr', moduleName, 'workflows', relPath).replaceAll('\\', '/'),
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  async collectAgents(modules) {
+    this.agents = [];
+    for (const mod of modules) {
+      const agentsPath = path.join(this.prrDir, mod, 'agents');
+      if (!(await fs.pathExists(agentsPath))) continue;
+
+      const files = await glob('**/*.md', { cwd: agentsPath });
+      for (const file of files) {
+        const fullPath = path.join(agentsPath, file);
+        const info = await this.parseAgentFile(fullPath, mod, file);
+        if (info) this.agents.push(info);
+      }
+    }
+  }
+
+  async parseAgentFile(filePath, moduleName, relPath) {
+    try {
+      const content = await fs.readFile(filePath, 'utf8');
+      // Extract XML agent attributes
+      const nameMatch = content.match(/name="([^"]+)"/);
+      const titleMatch = content.match(/title="([^"]+)"/);
+      const iconMatch = content.match(/icon="([^"]+)"/);
+      const capMatch = content.match(/capabilities="([^"]+)"/);
+
+      return {
+        module: moduleName,
+        name: nameMatch?.[1] || path.basename(relPath, '.md'),
+        title: titleMatch?.[1] || '',
+        icon: iconMatch?.[1] || '🔍',
+        capabilities: capMatch?.[1] || '',
+        path: path.join('_prr', moduleName, 'agents', relPath).replaceAll('\\', '/'),
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  async collectTasks(modules) {
+    this.tasks = [];
+    for (const mod of modules) {
+      const tasksPath = path.join(this.prrDir, mod, 'tasks');
+      if (!(await fs.pathExists(tasksPath))) continue;
+
+      const files = await glob('**/*.{md,xml}', { cwd: tasksPath });
+      for (const file of files) {
+        this.tasks.push({
+          module: mod,
+          name: path.basename(file, path.extname(file)),
+          path: path.join('_prr', mod, 'tasks', file).replaceAll('\\', '/'),
+        });
+      }
+    }
+  }
+
+  cleanForCSV(text) {
+    if (!text) return '';
+    return text.trim().replaceAll(/\s+/g, ' ').replaceAll('"', '""');
+  }
+
+  async writeWorkflowManifest(cfgDir) {
+    const rows = ['module,name,description,path'];
+    for (const w of this.workflows) {
+      rows.push(`"${this.cleanForCSV(w.module)}","${this.cleanForCSV(w.name)}","${this.cleanForCSV(w.description)}","${this.cleanForCSV(w.path)}"`);
+    }
+    await fs.writeFile(path.join(cfgDir, 'workflow-manifest.csv'), rows.join('\n') + '\n', 'utf8');
+  }
+
+  async writeAgentManifest(cfgDir) {
+    const rows = ['module,name,title,icon,capabilities,path'];
+    for (const a of this.agents) {
+      rows.push(`"${this.cleanForCSV(a.module)}","${this.cleanForCSV(a.name)}","${this.cleanForCSV(a.title)}","${this.cleanForCSV(a.icon)}","${this.cleanForCSV(a.capabilities)}","${this.cleanForCSV(a.path)}"`);
+    }
+    await fs.writeFile(path.join(cfgDir, 'agent-manifest.csv'), rows.join('\n') + '\n', 'utf8');
+  }
+
+  async writeTaskManifest(cfgDir) {
+    const rows = ['module,name,path'];
+    for (const t of this.tasks) {
+      rows.push(`"${this.cleanForCSV(t.module)}","${this.cleanForCSV(t.name)}","${this.cleanForCSV(t.path)}"`);
+    }
+    await fs.writeFile(path.join(cfgDir, 'task-manifest.csv'), rows.join('\n') + '\n', 'utf8');
+  }
+}
+
+module.exports = { ManifestGenerator };

package/tools/cli/installers/lib/core/manifest.js

@@ -0,0 +1,62 @@
+/**
+ * Manifest — read/write installation manifest.yaml
+ */
+const path = require('node:path');
+const fs = require('fs-extra');
+const yaml = require('yaml');
+
+const packageJson = require('../../../../../package.json');
+
+class Manifest {
+  async create(prrDir, data) {
+    const manifestPath = path.join(prrDir, '_config', 'manifest.yaml');
+    await fs.ensureDir(path.dirname(manifestPath));
+
+    const version = data.version || packageJson.version;
+    const now = data.installDate || new Date().toISOString();
+
+    const moduleDetails = (data.modules || []).map((name) => ({
+      name,
+      version,
+      installDate: now,
+      lastUpdated: now,
+      source: 'built-in',
+    }));
+
+    const manifestData = {
+      installation: {
+        version,
+        installDate: now,
+        lastUpdated: now,
+      },
+      modules: moduleDetails,
+      ides: data.ides || [],
+    };
+
+    const content = yaml.stringify(manifestData, { indent: 2, lineWidth: 0 });
+    await fs.writeFile(manifestPath, content, 'utf8');
+    return { success: true, path: manifestPath };
+  }
+
+  async read(prrDir) {
+    const manifestPath = path.join(prrDir, '_config', 'manifest.yaml');
+    if (!(await fs.pathExists(manifestPath))) return null;
+
+    try {
+      const content = await fs.readFile(manifestPath, 'utf8');
+      const data = yaml.parse(content);
+      const modules = (data.modules || []).map((m) => (typeof m === 'string' ? m : m.name));
+      return {
+        version: data.installation?.version,
+        installDate: data.installation?.installDate,
+        lastUpdated: data.installation?.lastUpdated,
+        modules,
+        ides: data.ides || [],
+      };
+    } catch {
+      return null;
+    }
+  }
+}
+
+module.exports = { Manifest };

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

@@ -0,0 +1,36 @@
+/**
+ * Base IDE Setup — abstract class for IDE handlers
+ */
+const fs = require('fs-extra');
+const { PRR_FOLDER_NAME } = require('./shared/path-utils');
+
+class BaseIdeSetup {
+  constructor(name, displayName, preferred = false) {
+    this.name = name;
+    this.displayName = displayName;
+    this.preferred = preferred;
+    this.prrFolderName = PRR_FOLDER_NAME;
+  }
+
+  setPrrFolderName(name) {
+    this.prrFolderName = name;
+  }
+
+  async ensureDir(dirPath) {
+    await fs.ensureDir(dirPath);
+  }
+
+  async setup(projectDir, prrDir, options = {}) {
+    throw new Error(`setup() not implemented for IDE: ${this.name}`);
+  }
+
+  async cleanup(projectDir, options = {}) {
+    // Default: no-op; subclasses override to remove IDE-specific files
+  }
+
+  async detect(projectDir) {
+    return false;
+  }
+}
+
+module.exports = { BaseIdeSetup };

package/tools/cli/installers/lib/ide/_config-driven.js

@@ -0,0 +1,167 @@
+/**
+ * Config-Driven IDE Setup — handles standard IDE installation patterns
+ * based on platform-codes.yaml configuration
+ */
+const path = require('node:path');
+const fs = require('fs-extra');
+const { BaseIdeSetup } = require('./_base-ide');
+const { glob } = require('glob');
+
+class ConfigDrivenIdeSetup extends BaseIdeSetup {
+  constructor(platformCode, platformConfig) {
+    super(platformCode, platformConfig.name, platformConfig.preferred || false);
+    this.platformConfig = platformConfig;
+    this.installerConfig = platformConfig.installer || null;
+  }
+
+  async setup(projectDir, prrDir, options = {}) {
+    if (!this.installerConfig) return { success: false, reason: 'no-config' };
+
+    await this.cleanup(projectDir, options);
+
+    const { target_dir, template_type } = this.installerConfig;
+    const targetPath = path.join(projectDir, target_dir);
+    await this.ensureDir(targetPath);
+
+    const results = { agents: 0, workflows: 0 };
+    const installedFiles = [];
+    const selectedModules = options.selectedModules || ['prr'];
+    const allModules = ['core', ...selectedModules.filter((m) => m !== 'core')];
+
+    // Install agent launchers
+    for (const mod of allModules) {
+      const agentsDir = path.join(prrDir, mod, 'agents');
+      if (!(await fs.pathExists(agentsDir))) continue;
+
+      const agentFiles = await glob('**/*.md', { cwd: agentsDir });
+      for (const agentFile of agentFiles) {
+        const agentPath = path.join(agentsDir, agentFile);
+        const agentContent = await fs.readFile(agentPath, 'utf8');
+
+        // Extract name and description from frontmatter
+        const nameMatch = agentContent.match(/^name:\s*["']?([^"'\n]+)["']?/m);
+        const descMatch = agentContent.match(/^description:\s*["']?([^"'\n]+)["']?/m);
+
+        // Skip agents marked as internal (no-launcher)
+        if (/^no-launcher:\s*true/m.test(agentContent)) continue;
+
+        const agentName = nameMatch?.[1]?.trim() || path.basename(agentFile, '.md');
+        const agentDesc = descMatch?.[1]?.trim() || `${agentName} reviewer`;
+        const relAgentPath = `${mod}/agents/${agentFile}`.replaceAll('\\', '/');
+
+        const launcherContent = this.generateAgentLauncher(agentName, agentDesc, relAgentPath, template_type);
+        // Use agent basename directly — e.g. prr-master.md → /prr-master
+        const launcherFileName = `${path.basename(agentFile, '.md')}.md`;
+        await fs.writeFile(path.join(targetPath, launcherFileName), launcherContent, 'utf8');
+        installedFiles.push(launcherFileName);
+        results.agents++;
+      }
+    }
+
+    // Install workflow launchers
+    for (const mod of allModules) {
+      const workflowsDir = path.join(prrDir, mod, 'workflows');
+      if (!(await fs.pathExists(workflowsDir))) continue;
+
+      const workflowFiles = await glob('**/workflow{.md,.yaml}', { cwd: workflowsDir });
+      for (const wfFile of workflowFiles) {
+        const wfPath = path.join(workflowsDir, wfFile);
+        const wfContent = await fs.readFile(wfPath, 'utf8');
+
+        let wfName = path.basename(path.dirname(wfFile));
+        let wfDesc = '';
+
+        if (wfFile.endsWith('.yaml')) {
+          const yaml = require('yaml');
+          try {
+            const data = yaml.parse(wfContent);
+            wfName = data.name || wfName;
+            wfDesc = data.description || '';
+          } catch { /* ignore */ }
+        } else {
+          const normalized = wfContent.replace(/\r\n/g, '\n');
+          const fmMatch = normalized.match(/^---\n([\s\S]*?)\n---/);
+          if (fmMatch) {
+            try {
+              const yaml = require('yaml');
+              const fm = yaml.parse(fmMatch[1]);
+              wfName = fm.name || wfName;
+              wfDesc = fm.description || '';
+            } catch { /* ignore */ }
+          }
+        }
+
+        const relWfPath = `${mod}/workflows/${wfFile}`.replaceAll('\\', '/');
+        const launcherContent = this.generateWorkflowLauncher(wfName, wfDesc, relWfPath, template_type);
+
+        // Use leaf directory name prefixed with prr- — e.g. prr-select-pr.md → /prr-select-pr
+        const dirParts = path.dirname(wfFile).split(path.sep).filter(Boolean);
+        const leafDir = dirParts.at(-1) || wfName;
+        const launcherFileName = `prr-${leafDir}.md`;
+        await fs.writeFile(path.join(targetPath, launcherFileName), launcherContent, 'utf8');
+        installedFiles.push(launcherFileName);
+        results.workflows++;
+      }
+    }
+
+    // Write manifest so cleanup knows exactly which files to remove
+    await fs.writeFile(
+      path.join(targetPath, '.prr-installed.json'),
+      JSON.stringify(installedFiles, null, 2),
+      'utf8'
+    );
+
+    return { success: true, results };
+  }
+
+  generateAgentLauncher(name, description, agentRelPath, templateType) {
+    const template = this.loadTemplate(`${templateType}-agent`) || this.loadTemplate('default-agent');
+    return template
+      .replaceAll('{{name}}', name)
+      .replaceAll('{{description}}', description)
+      .replaceAll('{{path}}', agentRelPath)
+      .replaceAll('{{prrFolderName}}', this.prrFolderName);
+  }
+
+  generateWorkflowLauncher(name, description, wfRelPath, templateType) {
+    const template = this.loadTemplate(`${templateType}-workflow`) || this.loadTemplate('default-workflow');
+    return template
+      .replaceAll('{{name}}', name)
+      .replaceAll('{{description}}', description)
+      .replaceAll('{{path}}', wfRelPath)
+      .replaceAll('{{prrFolderName}}', this.prrFolderName);
+  }
+
+  loadTemplate(templateName) {
+    const templatePath = path.join(__dirname, 'templates', 'combined', `${templateName}.md`);
+    try {
+      return require('fs-extra').readFileSync(templatePath, 'utf8');
+    } catch {
+      return null;
+    }
+  }
+
+  async cleanup(projectDir, options = {}) {
+    if (!this.installerConfig?.target_dir) return;
+    const targetPath = path.join(projectDir, this.installerConfig.target_dir);
+    if (!(await fs.pathExists(targetPath))) return;
+
+    const manifestPath = path.join(targetPath, '.prr-installed.json');
+    if (await fs.pathExists(manifestPath)) {
+      // Remove exactly the files recorded during the last install
+      const installedFiles = JSON.parse(await fs.readFile(manifestPath, 'utf8'));
+      for (const file of installedFiles) {
+        await fs.remove(path.join(targetPath, file));
+      }
+      await fs.remove(manifestPath);
+    } else {
+      // Fallback for installations before manifest tracking was added
+      const files = await glob('prr-*.md', { cwd: targetPath });
+      for (const file of files) {
+        await fs.remove(path.join(targetPath, file));
+      }
+    }
+  }
+}
+
+module.exports = { ConfigDrivenIdeSetup };

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

@@ -0,0 +1,97 @@
+/**
+ * IDE Manager — dynamically loads and manages IDE handlers
+ */
+const path = require('node:path');
+const fs = require('fs-extra');
+const yaml = require('yaml');
+const { PRR_FOLDER_NAME } = require('./shared/path-utils');
+
+class IdeManager {
+  constructor() {
+    this.handlers = new Map();
+    this._initialized = false;
+    this.prrFolderName = PRR_FOLDER_NAME;
+  }
+
+  setPrrFolderName(name) {
+    this.prrFolderName = name;
+    for (const handler of this.handlers.values()) {
+      if (typeof handler.setPrrFolderName === 'function') {
+        handler.setPrrFolderName(name);
+      }
+    }
+  }
+
+  async ensureInitialized() {
+    if (!this._initialized) {
+      await this.loadHandlers();
+      this._initialized = true;
+    }
+  }
+
+  async loadHandlers() {
+    const platformCodesPath = path.join(__dirname, 'platform-codes.yaml');
+    const content = await fs.readFile(platformCodesPath, 'utf8');
+    const config = yaml.parse(content);
+
+    const { ConfigDrivenIdeSetup } = require('./_config-driven');
+
+    for (const [code, info] of Object.entries(config.platforms || {})) {
+      if (!info.installer) continue;
+      const handler = new ConfigDrivenIdeSetup(code, info);
+      handler.setPrrFolderName(this.prrFolderName);
+      this.handlers.set(code, handler);
+    }
+  }
+
+  getAvailableIdes() {
+    const ides = [];
+    for (const [key, handler] of this.handlers) {
+      ides.push({
+        value: key,
+        name: handler.displayName || handler.name || key,
+        preferred: handler.preferred || false,
+      });
+    }
+    return ides.sort((a, b) => {
+      if (a.preferred && !b.preferred) return -1;
+      if (!a.preferred && b.preferred) return 1;
+      return a.name.localeCompare(b.name);
+    });
+  }
+
+  getPreferredIdes() {
+    return this.getAvailableIdes().filter((i) => i.preferred);
+  }
+
+  async setup(ideName, projectDir, prrDir, options = {}) {
+    await this.ensureInitialized();
+    const handler = this.handlers.get(ideName.toLowerCase());
+    if (!handler) return { success: false, ide: ideName, error: 'unsupported IDE' };
+
+    try {
+      const result = await handler.setup(projectDir, prrDir, options);
+      let detail = '';
+      if (result && result.results) {
+        const parts = [];
+        if (result.results.agents > 0) parts.push(`${result.results.agents} agents`);
+        if (result.results.workflows > 0) parts.push(`${result.results.workflows} workflows`);
+        detail = parts.join(', ');
+      }
+      return { success: true, ide: ideName, detail };
+    } catch (error) {
+      return { success: false, ide: ideName, error: error.message };
+    }
+  }
+
+  async cleanup(projectDir, options = {}) {
+    await this.ensureInitialized();
+    for (const handler of this.handlers.values()) {
+      try {
+        await handler.cleanup(projectDir, options);
+      } catch { /* ignore */ }
+    }
+  }
+}
+
+module.exports = { IdeManager };

package/tools/cli/installers/lib/ide/platform-codes.yaml

@@ -0,0 +1,76 @@
+# PR Review Platform Codes Configuration
+# IDE/tool registry — defines where to install agent/workflow launchers
+
+platforms:
+  claude-code:
+    name: "Claude Code"
+    preferred: true
+    category: cli
+    description: "Anthropic's official CLI for Claude"
+    installer:
+      target_dir: .claude/commands
+      template_type: default
+
+  cursor:
+    name: "Cursor"
+    preferred: true
+    category: ide
+    description: "AI-first code editor"
+    installer:
+      target_dir: .cursor/commands
+      template_type: default
+
+  windsurf:
+    name: "Windsurf"
+    preferred: true
+    category: ide
+    description: "AI-powered IDE with cascade flows"
+    installer:
+      target_dir: .windsurf/workflows
+      template_type: windsurf
+
+  cline:
+    name: "Cline"
+    preferred: false
+    category: ide
+    description: "AI coding assistant"
+    installer:
+      target_dir: .clinerules/workflows
+      template_type: windsurf
+
+  roo:
+    name: "Roo Cline"
+    preferred: false
+    category: ide
+    description: "Enhanced Cline fork"
+    installer:
+      target_dir: .roo/commands
+      template_type: default
+
+  gemini:
+    name: "Gemini CLI"
+    preferred: false
+    category: cli
+    description: "Google's CLI for Gemini"
+    installer:
+      target_dir: .gemini/commands
+      template_type: default
+
+  kiro:
+    name: "Kiro"
+    preferred: false
+    category: ide
+    description: "Amazon's AI-powered IDE"
+    installer:
+      target_dir: .kiro/steering
+      template_type: default
+
+categories:
+  ide:
+    name: "Integrated Development Environment"
+  cli:
+    name: "Command Line Interface"
+
+conventions:
+  code_format: "lowercase-kebab-case"
+  name_format: "Title Case"

package/tools/cli/installers/lib/ide/shared/path-utils.js

@@ -0,0 +1,11 @@
+const PRR_FOLDER_NAME = '_prr';
+
+function toColonPath(p) {
+  return p.replaceAll('/', ':').replaceAll('\\', ':');
+}
+
+function toDashPath(p) {
+  return p.replaceAll('/', '-').replaceAll('\\', '-').replaceAll('.', '-');
+}
+
+module.exports = { PRR_FOLDER_NAME, toColonPath, toDashPath };

package/tools/cli/installers/lib/ide/templates/combined/default-agent.md

@@ -0,0 +1,16 @@
+---
+name: '{{name}}'
+description: '{{description}}'
+disable-model-invocation: true
+---
+
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+<agent-activation CRITICAL="TRUE">
+1. LOAD the FULL agent file from {project-root}/_prr/{{path}}
+2. READ its entire contents - this contains the complete agent persona, menu, and instructions
+3. FOLLOW every step in the <activation> section precisely
+4. DISPLAY the welcome/greeting as instructed
+5. PRESENT the numbered menu
+6. WAIT for user input before proceeding
+</agent-activation>

package/tools/cli/installers/lib/ide/templates/combined/default-workflow.md

@@ -0,0 +1,7 @@
+---
+name: '{{name}}'
+description: '{{description}}'
+disable-model-invocation: true
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @{project-root}/{{prrFolderName}}/{{path}}, READ its entire contents and follow its directions exactly!

package/tools/cli/installers/lib/ide/templates/combined/windsurf-workflow.md

@@ -0,0 +1,5 @@
+---
+description: '{{description}}'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @{project-root}/{{prrFolderName}}/{{path}}, READ its entire contents and follow its directions exactly!