prr-kit 1.0.0

package/src/prr/workflows/quick/workflow.md

@@ -0,0 +1,244 @@
+---
+name: quick
+description: "Full PR review pipeline in one command: select → describe → review → report"
+main_config: '{project-root}/_prr/prr/config.yaml'
+---
+
+# Quick Review — Full Pipeline
+
+**Goal:** Run the complete PR review pipeline end-to-end with minimal interruptions.
+Only pause for user input when selecting the branch. Everything else runs automatically.
+
+## INITIALIZATION
+
+Load config from {main_config}: `user_name`, `communication_language`, `target_repo`, `review_output`, `project_context`.
+
+Set `date` = today's date (YYYY-MM-DD).
+
+If `project_context` file exists at `{review_output}/project-context.yaml`, load it silently.
+If it does not exist, notify: "⚠️ No project context found — run [CP] Collect Project Context first for better reviews. Continuing without it."
+
+---
+
+## PHASE 1 — SELECT PR
+*Execute steps 1a–1b automatically. Pause only at 1c.*
+
+### 1a. Fetch latest
+```bash
+git -C {target_repo} fetch origin --prune
+```
+Show: `✓ Fetched latest from remote`
+
+### 1b. List open PRs (primary) + recent branches (secondary)
+
+**Primary — GitHub PRs** (if `{github_repo}` is configured):
+```bash
+gh pr list --repo {github_repo} --state open \
+  --json number,title,headRefName,baseRefName,author,createdAt,isDraft --limit 20
+```
+Display as a table: `#N | title | head → base | author | age`
+
+**Secondary — recent branches** (always):
+```bash
+git -C {target_repo} branch -r --sort=-committerdate \
+  --format="%(refname:short) | %(objectname:short) | %(committerdate:relative) | %(contents:subject)" \
+  | head -15
+```
+
+### 1c. Select PR ← **ONLY USER INPUT IN THIS WORKFLOW**
+
+**If `{github_repo}` is configured** — ask:
+> Select a PR to review:
+> Enter PR number (e.g. `44`) or branch name (e.g. `feature/my-feature`):
+
+Wait for response.
+
+**If PR number entered:**
+```bash
+gh pr view {pr_number} --repo {github_repo} \
+  --json number,title,headRefName,baseRefName,author,headRefOid
+```
+Set `target_branch` = `headRefName`, `base_branch` = `baseRefName` ← **exact from GitHub, not assumed**.
+Set `pr_head_sha` = `headRefOid`.
+
+**If branch name entered:**
+Check if a PR exists for it via `gh pr list --head {branch}`.
+If yes: use PR's `baseRefName`. If no: detect `origin/main` or `origin/master`.
+
+---
+
+**If `{github_repo}` is NOT configured** — ask two separate questions:
+
+First, display EXACTLY:
+```
+🎯 Head branch (the branch to review)?
+
+   You can:
+     • Enter a number from the list  (e.g., 1)
+     • Type the branch name directly  (e.g., feature/my-feature)
+```
+Wait for response. Set `target_branch` = input.
+
+Then display EXACTLY:
+```
+🎯 Base branch (what to diff against)?
+
+   You can:
+     • Press Enter to use the default  [main]
+     • Type the branch name directly   (e.g., develop)
+```
+Wait for response. If empty → detect `origin/main` or `origin/master`.
+Set `base_branch` = input or detected default.
+Set `diff_range` = `{base_branch}...{target_branch}`.
+
+### 1d. Load diff
+```bash
+# If PR number available (preferred):
+gh pr diff {pr_number} --repo {github_repo}
+
+# Otherwise:
+git -C {target_repo} diff {base_branch}...{target_branch} --stat
+git -C {target_repo} diff {base_branch}...{target_branch}
+```
+Store diff in memory. Count files changed, lines added/removed.
+
+### 1e. Save PR context
+Write `{review_output}/current-pr-context.yaml`:
+```yaml
+target_branch: "{target_branch}"
+base_branch: "{base_branch}"
+date: "{date}"
+```
+
+Show summary:
+```
+✓ PR selected: {target_branch}
+  Files changed: X | +Y / -Z lines
+```
+
+---
+
+## PHASE 2 — DESCRIBE PR
+*Execute automatically, no user input.*
+
+### 2a. Classify PR type
+Analyze the diff and classify as one of: `bugfix` | `feature` | `refactor` | `docs` | `test` | `chore` | `hotfix`
+
+### 2b. Generate walkthrough
+For each changed file, write a 1-2 sentence summary of what changed and why.
+Group by: new files | modified files | deleted files | renamed files.
+
+### 2c. Output description
+Print to screen:
+```
+## PR Description
+
+**Type:** {pr_type}
+**Branch:** {target_branch}
+**Summary:** {2-3 sentence overall summary}
+
+### Files Changed
+{walkthrough table}
+```
+
+---
+
+## PHASE 3 — REVIEW
+*Execute all review types automatically, one by one.*
+
+For each review, read the corresponding instructions file and apply it to `{pr_diff}`.
+
+### 3a. General Review
+Load and follow: `{project-root}/_prr/prr/workflows/3-review/general-review/instructions.xml`
+
+Collect findings as `{general_findings}`.
+Print section header: `## 👁️ General Review`
+
+### 3b. Security Review
+Load and follow: `{project-root}/_prr/prr/workflows/3-review/security-review/instructions.xml`
+
+Collect findings as `{security_findings}`.
+Print section header: `## 🔒 Security Review`
+
+### 3c. Performance Review
+Load and follow: `{project-root}/_prr/prr/workflows/3-review/performance-review/instructions.xml`
+
+Collect findings as `{performance_findings}`.
+Print section header: `## ⚡ Performance Review`
+
+### 3d. Architecture Review
+Load and follow: `{project-root}/_prr/prr/workflows/3-review/architecture-review/instructions.xml`
+
+Collect findings as `{architecture_findings}`.
+Print section header: `## 🏗️ Architecture Review`
+
+---
+
+## PHASE 4 — GENERATE REPORT
+*Execute automatically.*
+
+Compile all findings from phases 3a–3d.
+
+Sort by severity: 🔴 Blockers first → 🟡 Warnings → 🟢 Suggestions → 📌 Questions.
+
+Count totals:
+- `{blocker_count}` = number of 🔴 findings
+- `{warning_count}` = number of 🟡 findings
+- `{suggestion_count}` = number of 🟢 findings
+
+Generate report filename: `review-{target_branch_slug}-{date}.md`
+where `{target_branch_slug}` = branch name with `/` replaced by `-`.
+
+Write report to: `{review_output}/review-{target_branch_slug}-{date}.md`
+
+Report format:
+```markdown
+# PR Review: {target_branch}
+**Date:** {date} | **Reviewer:** AI Review Framework
+**Type:** {pr_type} | **Files:** X | **Lines:** +Y/-Z
+
+## Executive Summary
+{2-3 sentence overall quality assessment}
+
+**Totals:** 🔴 {blocker_count} blockers | 🟡 {warning_count} warnings | 🟢 {suggestion_count} suggestions
+
+## Blockers 🔴
+{all blocker findings}
+
+## Warnings 🟡
+{all warning findings}
+
+## Suggestions 🟢
+{all suggestion findings}
+
+## Questions 📌
+{all questions}
+
+## Files Reviewed
+{file list}
+```
+
+---
+
+## PHASE 5 — DONE
+
+Print completion summary:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ Quick Review Complete
+
+Branch:  {target_branch}
+Report:  {review_output}/review-{target_branch_slug}-{date}.md
+
+🔴 Blockers:    {blocker_count}
+🟡 Warnings:    {warning_count}
+🟢 Suggestions: {suggestion_count}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Then ask:
+> Post these findings as inline comments to GitHub? (requires `gh` CLI and `github_repo` configured)
+> Type **PC** to post, or **Enter** to finish.
+
+If user types `PC`, load and follow: `{project-root}/_prr/prr/workflows/6-report/post-comments/workflow.md`
+Otherwise, end session.

package/tools/cli/commands/install.js

@@ -0,0 +1,66 @@
+const { Installer } = require('../installers/lib/core/installer');
+const { UI } = require('../lib/ui');
+const prompts = require('../lib/prompts');
+
+const installer = new Installer();
+const ui = new UI();
+
+module.exports = {
+  command: 'install',
+  description: 'Install PR Review agents and workflows into your project',
+  options: [
+    ['-d, --debug', 'Enable debug output for manifest generation'],
+    ['--directory <path>', 'Installation directory (default: current directory)'],
+    ['--modules <modules>', 'Comma-separated list of module IDs to install (e.g., "prr")'],
+    ['--tools <tools>', 'Comma-separated list of IDE IDs to configure (e.g., "claude-code,cursor"). Use "none" to skip.'],
+    ['--action <type>', 'Action type: install, update, or quick-update'],
+    ['--user-name <name>', 'Name for agents to use'],
+    ['--communication-language <lang>', 'Language for agent communication (default: English)'],
+    ['--output-folder <path>', 'Output folder relative to project root (default: _prr-output)'],
+    ['--target-repo <path>', 'Path to git repository to review (default: .)'],
+    ['--github-repo <owner/repo>', 'GitHub repository for posting comments (optional)'],
+    ['-y, --yes', 'Accept all defaults and skip prompts'],
+  ],
+  action: async (options) => {
+    try {
+      if (options.debug) {
+        process.env.PRR_DEBUG_MANIFEST = 'true';
+        await prompts.log.info('Debug mode enabled');
+      }
+
+      const config = await ui.promptInstall(options);
+
+      if (config.actionType === 'cancel') {
+        await prompts.log.warn('Installation cancelled.');
+        process.exit(0);
+      }
+
+      if (config.actionType === 'quick-update') {
+        const result = await installer.quickUpdate(config);
+        await prompts.log.success('Quick update complete!');
+        await prompts.log.info(`Updated ${result.moduleCount} modules (${result.modules.join(', ')})`);
+        process.exit(0);
+      }
+
+      const result = await installer.install(config);
+
+      if (result && result.cancelled) {
+        process.exit(0);
+      }
+
+      if (result && result.success) {
+        process.exit(0);
+      }
+    } catch (error) {
+      if (error.fullMessage) {
+        await prompts.log.error(error.fullMessage);
+      } else {
+        await prompts.log.error(`Installation failed: ${error.message}`);
+      }
+      if (error.stack && process.env.PRR_DEBUG_MANIFEST) {
+        await prompts.log.message(error.stack);
+      }
+      process.exit(1);
+    }
+  },
+};

package/tools/cli/commands/status.js

@@ -0,0 +1,36 @@
+const { Installer } = require('../installers/lib/core/installer');
+const prompts = require('../lib/prompts');
+
+const installer = new Installer();
+
+module.exports = {
+  command: 'status',
+  description: 'Show current PR Review installation status',
+  options: [
+    ['--directory <path>', 'Project directory (default: current directory)'],
+  ],
+  action: async (options) => {
+    try {
+      const projectDir = options.directory
+        ? require('node:path').resolve(options.directory)
+        : process.cwd();
+
+      const status = await installer.status(projectDir);
+
+      if (!status.installed) {
+        await prompts.log.warn('PR Review is not installed in this directory.');
+        await prompts.log.info('Run `npx pr-review install` to get started.');
+        process.exit(0);
+      }
+
+      await prompts.log.success(`PR Review v${status.version} installed`);
+      await prompts.log.info(`Modules: ${status.modules.join(', ')}`);
+      await prompts.log.info(`IDEs configured: ${status.ides.join(', ') || 'none'}`);
+      await prompts.log.info(`Install date: ${status.installDate}`);
+      process.exit(0);
+    } catch (error) {
+      await prompts.log.error(`Status check failed: ${error.message}`);
+      process.exit(1);
+    }
+  },
+};

package/tools/cli/commands/uninstall.js

@@ -0,0 +1,38 @@
+const { Installer } = require('../installers/lib/core/installer');
+const prompts = require('../lib/prompts');
+
+const installer = new Installer();
+
+module.exports = {
+  command: 'uninstall',
+  description: 'Remove PR Review installation from a project',
+  options: [
+    ['--directory <path>', 'Project directory (default: current directory)'],
+    ['-y, --yes', 'Skip confirmation prompt'],
+  ],
+  action: async (options) => {
+    try {
+      const projectDir = options.directory
+        ? require('node:path').resolve(options.directory)
+        : process.cwd();
+
+      if (!options.yes) {
+        const { confirm } = require('@clack/prompts');
+        const ok = await confirm({
+          message: `Remove PR Review from ${projectDir}?`,
+        });
+        if (!ok) {
+          await prompts.log.warn('Uninstall cancelled.');
+          process.exit(0);
+        }
+      }
+
+      await installer.uninstall(projectDir);
+      await prompts.log.success('PR Review uninstalled successfully.');
+      process.exit(0);
+    } catch (error) {
+      await prompts.log.error(`Uninstall failed: ${error.message}`);
+      process.exit(1);
+    }
+  },
+};

package/tools/cli/installers/lib/core/config-collector.js

@@ -0,0 +1,47 @@
+/**
+ * Config Collector — writes config.yaml files for each module
+ */
+const path = require('node:path');
+const fs = require('fs-extra');
+const yaml = require('yaml');
+
+class ConfigCollector {
+  /**
+   * Write module config files based on user answers
+   * @param {string} prrDir - _prr directory path
+   * @param {Object} config - User-provided config values
+   */
+  async writeConfigs(prrDir, config) {
+    // Core config
+    const coreConfigPath = path.join(prrDir, 'core', 'config.yaml');
+    await fs.ensureDir(path.dirname(coreConfigPath));
+
+    const coreConfig = {
+      user_name: config.userName || 'Reviewer',
+      communication_language: config.communicationLanguage || 'English',
+      output_folder: config.outputFolder || '_prr-output',
+    };
+    await fs.writeFile(coreConfigPath, yaml.stringify(coreConfig, { indent: 2 }), 'utf8');
+
+    // PRR module config
+    if (config.selectedModules && config.selectedModules.includes('prr')) {
+      const prrConfigPath = path.join(prrDir, 'prr', 'config.yaml');
+      await fs.ensureDir(path.dirname(prrConfigPath));
+
+      const outputFolderAbs = path.join(config.projectDir, config.outputFolder || '_prr-output');
+      const reviewOutput = path.join(outputFolderAbs, 'reviews').replaceAll('\\', '/');
+
+      const prrConfig = {
+        ...coreConfig,
+        project_name: config.projectName || path.basename(config.projectDir),
+        target_repo: config.targetRepo || '.',
+        platform: config.platform || 'auto',
+        platform_repo: config.platformRepo || config.githubRepo || '',
+        review_output: reviewOutput,
+      };
+      await fs.writeFile(prrConfigPath, yaml.stringify(prrConfig, { indent: 2 }), 'utf8');
+    }
+  }
+}
+
+module.exports = { ConfigCollector };

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

@@ -0,0 +1,46 @@
+/**
+ * Detector — detects existing PR Review installations
+ */
+const path = require('node:path');
+const fs = require('fs-extra');
+const yaml = require('yaml');
+
+const PRR_FOLDER_NAME = '_prr';
+
+class Detector {
+  /**
+   * Check if PR Review is installed in the given directory
+   * @param {string} projectDir
+   * @returns {Object} { installed, version, modules, prrDir }
+   */
+  async detect(projectDir) {
+    const prrDir = path.join(projectDir, PRR_FOLDER_NAME);
+
+    if (!(await fs.pathExists(prrDir))) {
+      return { installed: false, prrDir };
+    }
+
+    const manifestPath = path.join(prrDir, '_config', 'manifest.yaml');
+    if (!(await fs.pathExists(manifestPath))) {
+      return { installed: false, prrDir };
+    }
+
+    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 {
+        installed: true,
+        version: data.installation?.version || 'unknown',
+        installDate: data.installation?.installDate,
+        modules,
+        ides: data.ides || [],
+        prrDir,
+      };
+    } catch {
+      return { installed: false, prrDir };
+    }
+  }
+}
+
+module.exports = { Detector, PRR_FOLDER_NAME };

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

@@ -0,0 +1,162 @@
+/**
+ * Installer — main installation orchestrator
+ * Main installation orchestrator for PR Review Framework
+ */
+const path = require('node:path');
+const fs = require('fs-extra');
+const { Manifest } = require('./manifest');
+const { ManifestGenerator } = require('./manifest-generator');
+const { ConfigCollector } = require('./config-collector');
+const { Detector, PRR_FOLDER_NAME } = require('./detector');
+const { IdeManager } = require('../ide/manager');
+const { compileAgent } = require('../../../lib/agent/compiler');
+const prompts = require('../../../lib/prompts');
+const packageJson = require('../../../../../package.json');
+
+const SRC_DIR = path.join(__dirname, '..', '..', '..', '..', '..', 'src');
+const TEXT_EXTENSIONS = new Set(['.md', '.yaml', '.yml', '.txt', '.json', '.js', '.csv', '.xml', '.toml']);
+
+class Installer {
+  constructor() {
+    this.manifest = new Manifest();
+    this.manifestGenerator = new ManifestGenerator();
+    this.configCollector = new ConfigCollector();
+    this.detector = new Detector();
+    this.ideManager = new IdeManager();
+  }
+
+  async install(config) {
+    const { projectDir, selectedModules = ['prr'], selectedIdes = [], actionType = 'install' } = config;
+
+    await this.ideManager.ensureInitialized();
+
+    const prrDir = path.join(projectDir, PRR_FOLDER_NAME);
+    await fs.ensureDir(prrDir);
+
+    await prompts.log.step(`Installing PR Review to ${projectDir}...`);
+
+    // Copy module files from src/
+    const modulesToInstall = ['core', ...selectedModules.filter((m) => m !== 'core')];
+    for (const mod of modulesToInstall) {
+      const srcModDir = path.join(SRC_DIR, mod === 'core' ? 'core' : mod);
+      const dstModDir = path.join(prrDir, mod);
+
+      if (!(await fs.pathExists(srcModDir))) {
+        await prompts.log.warn(`Module '${mod}' not found in src/ — skipping`);
+        continue;
+      }
+
+      await fs.remove(dstModDir);
+      await this.copyModuleFiles(srcModDir, dstModDir);
+      await prompts.log.info(`  ✓ Module '${mod}' installed`);
+    }
+
+    // Compile agents (YAML → XML/MD)
+    await this.compileModuleAgents(prrDir, modulesToInstall);
+
+    // Write config files
+    await this.configCollector.writeConfigs(prrDir, config);
+    await prompts.log.info('  ✓ Configuration written');
+
+    // Create output directories
+    const outputFolderAbs = path.join(projectDir, config.outputFolder || '_prr-output');
+    await fs.ensureDir(path.join(outputFolderAbs, 'reviews'));
+    await prompts.log.info('  ✓ Output directories created');
+
+    // Generate manifests
+    const cfgDir = path.join(prrDir, '_config');
+    await fs.ensureDir(cfgDir);
+    await this.manifestGenerator.generateManifests(prrDir, selectedModules);
+    await this.manifest.create(prrDir, {
+      version: packageJson.version,
+      modules: modulesToInstall,
+      ides: selectedIdes,
+    });
+    await prompts.log.info('  ✓ Manifests generated');
+
+    // Configure IDEs
+    for (const ide of selectedIdes) {
+      const result = await this.ideManager.setup(ide, projectDir, prrDir, { selectedModules: modulesToInstall });
+      if (result.success) {
+        await prompts.log.info(`  ✓ ${ide} configured (${result.detail || 'done'})`);
+      }
+    }
+
+    await prompts.log.success('PR Review installed successfully!');
+    await prompts.log.info('Open your AI IDE and use the reviewer agents to start reviewing PRs.');
+
+    return { success: true };
+  }
+
+  async copyModuleFiles(srcDir, dstDir) {
+    await fs.ensureDir(dstDir);
+    const entries = await fs.readdir(srcDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const srcPath = path.join(srcDir, entry.name);
+      const dstPath = path.join(dstDir, entry.name);
+
+      if (entry.isDirectory()) {
+        await this.copyModuleFiles(srcPath, dstPath);
+      } else {
+        const ext = path.extname(entry.name).toLowerCase();
+        if (TEXT_EXTENSIONS.has(ext)) {
+          const content = await fs.readFile(srcPath, 'utf8');
+          await fs.ensureDir(path.dirname(dstPath));
+          await fs.writeFile(dstPath, content, 'utf8');
+        } else {
+          await fs.copy(srcPath, dstPath, { overwrite: true });
+        }
+      }
+    }
+  }
+
+  async compileModuleAgents(prrDir, modules) {
+    for (const mod of modules) {
+      const agentsYamlDir = path.join(prrDir, mod, 'agents');
+      if (!(await fs.pathExists(agentsYamlDir))) continue;
+
+      const files = await fs.readdir(agentsYamlDir);
+      for (const file of files) {
+        if (!file.endsWith('.agent.yaml')) continue;
+
+        const yamlPath = path.join(agentsYamlDir, file);
+        const baseName = file.replace('.agent.yaml', '');
+        const outputPath = path.join(agentsYamlDir, `${baseName}.md`);
+
+        try {
+          const yamlContent = await fs.readFile(yamlPath, 'utf8');
+          const { xml } = await compileAgent(yamlContent, {}, baseName, `_prr/${mod}/agents/${baseName}.md`);
+          await fs.writeFile(outputPath, xml, 'utf8');
+        } catch (err) {
+          await prompts.log.warn(`  Warning: Could not compile agent ${file}: ${err.message}`);
+        }
+      }
+    }
+  }
+
+  async uninstall(projectDir) {
+    const prrDir = path.join(projectDir, PRR_FOLDER_NAME);
+    if (await fs.pathExists(prrDir)) {
+      await fs.remove(prrDir);
+    }
+    // Also clean IDE configurations
+    await this.ideManager.ensureInitialized();
+    await this.ideManager.cleanup(projectDir);
+  }
+
+  async quickUpdate(config) {
+    const { projectDir } = config;
+    const existing = await this.detector.detect(projectDir);
+    if (!existing.installed) {
+      throw new Error('PR Review is not installed in this directory.');
+    }
+    return this.install({ ...config, selectedModules: existing.modules, selectedIdes: existing.ides });
+  }
+
+  async status(projectDir) {
+    return this.detector.detect(projectDir);
+  }
+}
+
+module.exports = { Installer };