prr-kit 1.0.0

package/tools/cli/lib/agent/compiler.js

@@ -0,0 +1,123 @@
+/**
+ * Agent Compiler — transforms agent YAML to compiled XML/Markdown format
+ * Compiles agent YAML files to XML/Markdown launcher format
+ */
+
+const yaml = require('yaml');
+const { processAgentYaml, extractInstallConfig, stripInstallConfig, getDefaultValues } = require('./template-engine');
+const { escapeXml } = require('../xml-utils');
+
+function buildFrontmatter(metadata, agentName) {
+  const name = agentName || metadata.name || 'agent';
+  const description = metadata.title || 'PR Review Agent';
+  const noLauncher = metadata.no_launcher ? '\nno-launcher: true' : '';
+  return `---\nname: "${name.replaceAll('-', ' ')}"\ndescription: "${description}"${noLauncher}\n---\n\nYou must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.\n\n`;
+}
+
+function buildPersonaXml(persona) {
+  if (!persona) return '';
+  let xml = '  <persona>\n';
+  if (persona.role) xml += `    <role>${escapeXml(persona.role.trim().replaceAll(/\s+/g, ' '))}</role>\n`;
+  if (persona.identity) xml += `    <identity>${escapeXml(persona.identity.trim().replaceAll(/\s+/g, ' '))}</identity>\n`;
+  if (persona.communication_style) xml += `    <communication_style>${escapeXml(persona.communication_style.trim().replaceAll(/\s+/g, ' '))}</communication_style>\n`;
+  if (persona.principles) {
+    const text = Array.isArray(persona.principles)
+      ? persona.principles.join(' ')
+      : persona.principles.trim().replaceAll(/\n+/g, ' ');
+    xml += `    <principles>${escapeXml(text)}</principles>\n`;
+  }
+  xml += '  </persona>\n';
+  return xml;
+}
+
+function buildMemoriesXml(memories) {
+  if (!memories || memories.length === 0) return '';
+  let xml = '  <memories>\n';
+  for (const m of memories) xml += `    <memory>${escapeXml(String(m))}</memory>\n`;
+  xml += '  </memories>\n';
+  return xml;
+}
+
+function buildMenuXml(menuItems) {
+  let xml = '  <menu>\n';
+  xml += `    <item cmd="MH or fuzzy match on menu or help">[MH] Redisplay Menu Help</item>\n`;
+  xml += `    <item cmd="CH or fuzzy match on chat">[CH] Chat with the Reviewer about anything</item>\n`;
+
+  if (menuItems && menuItems.length > 0) {
+    for (const item of menuItems) {
+      if (!item.trigger) continue;
+      const attrs = [`cmd="${item.trigger}"`];
+      if (item.workflow) attrs.push(`workflow="${item.workflow}"`);
+      if (item.exec) attrs.push(`exec="${item.exec}"`);
+      if (item.action) attrs.push(`action="${item.action}"`);
+      xml += `    <item ${attrs.join(' ')}>${escapeXml(item.description || '')}</item>\n`;
+    }
+  }
+
+  xml += `    <item cmd="PM or fuzzy match on party-mode" exec="{project-root}/_prr/core/workflows/party-mode/workflow.md">[PM] Start Party Mode (multi-reviewer discussion)</item>\n`;
+  xml += `    <item cmd="DA or fuzzy match on exit, leave, goodbye or dismiss agent">[DA] Dismiss Reviewer</item>\n`;
+  xml += '  </menu>\n';
+  return xml;
+}
+
+function buildActivationXml(meta) {
+  return `  <activation>
+    <step>Greet the user by name if known, introduce yourself as ${meta.name || 'PR Reviewer'} (${meta.title || 'Code Reviewer'})</step>
+    <step>Display your menu using numbered list format</step>
+    <step>Wait for user to select an option</step>
+    <step>Load and execute the corresponding workflow or task</step>
+  </activation>\n`;
+}
+
+async function compileToXml(agentYaml, agentName = '') {
+  const agent = agentYaml.agent;
+  const meta = agent.metadata;
+
+  let xml = buildFrontmatter(meta, agentName || meta.name);
+  xml += '```xml\n';
+
+  const agentAttrs = [
+    `id="${meta.id || ''}"`,
+    `name="${meta.name || ''}"`,
+    `title="${meta.title || ''}"`,
+    `icon="${meta.icon || '🔍'}"`,
+  ];
+  if (meta.capabilities) agentAttrs.push(`capabilities="${escapeXml(meta.capabilities)}"`);
+
+  xml += `<agent ${agentAttrs.join(' ')}>\n`;
+  xml += buildActivationXml(meta);
+
+  if (agent.critical_actions && agent.critical_actions.length > 0) {
+    xml += '  <critical_actions>\n';
+    for (const action of agent.critical_actions) {
+      xml += `    <action>${escapeXml(action)}</action>\n`;
+    }
+    xml += '  </critical_actions>\n';
+  }
+
+  xml += buildPersonaXml(agent.persona);
+  if (agent.memories && agent.memories.length > 0) xml += buildMemoriesXml(agent.memories);
+  xml += buildMenuXml(agent.menu || []);
+  xml += '</agent>\n```\n';
+
+  return xml;
+}
+
+async function compileAgent(yamlContent, answers = {}, agentName = '', targetPath = '') {
+  let agentYaml = yaml.parse(yamlContent);
+
+  const installConfig = extractInstallConfig(agentYaml);
+  let finalAnswers = answers;
+  if (installConfig) {
+    const defaults = getDefaultValues(installConfig);
+    finalAnswers = { ...defaults, ...answers };
+  }
+
+  const processedYaml = processAgentYaml(agentYaml, finalAnswers);
+  const cleanYaml = stripInstallConfig(processedYaml);
+  const xml = await compileToXml(cleanYaml, agentName, targetPath);
+
+  return { xml, metadata: cleanYaml.agent.metadata, processedYaml: cleanYaml };
+}
+
+module.exports = { compileAgent, compileToXml, buildFrontmatter, buildPersonaXml, buildMenuXml, escapeXml };

package/tools/cli/lib/agent/template-engine.js

@@ -0,0 +1,73 @@
+/**
+ * Template Engine — processes agent YAML with variable substitution
+ * Handles variable substitution for agent YAML configuration
+ */
+
+/**
+ * Recursively replace {variable} placeholders in strings/objects/arrays
+ * @param {any} value - Value to process
+ * @param {Object} vars - Variable map
+ * @returns {any} Processed value
+ */
+function replacePlaceholders(value, vars) {
+  if (typeof value === 'string') {
+    return value.replaceAll(/\{(\w+)\}/g, (match, key) => {
+      return Object.prototype.hasOwnProperty.call(vars, key) ? vars[key] : match;
+    });
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => replacePlaceholders(item, vars));
+  }
+  if (value && typeof value === 'object') {
+    const result = {};
+    for (const [k, v] of Object.entries(value)) {
+      result[k] = replacePlaceholders(v, vars);
+    }
+    return result;
+  }
+  return value;
+}
+
+/**
+ * Extract install_config section from agent YAML
+ */
+function extractInstallConfig(agentYaml) {
+  return agentYaml.install_config || null;
+}
+
+/**
+ * Strip install_config from processed YAML
+ */
+function stripInstallConfig(agentYaml) {
+  const { install_config, ...rest } = agentYaml;
+  return rest;
+}
+
+/**
+ * Get default values from install_config questions
+ */
+function getDefaultValues(installConfig) {
+  const defaults = {};
+  if (!installConfig || !installConfig.questions) return defaults;
+  for (const q of installConfig.questions) {
+    if (q.id && q.default !== undefined) {
+      defaults[q.id] = q.default;
+    }
+  }
+  return defaults;
+}
+
+/**
+ * Process agent YAML with variable substitution
+ */
+function processAgentYaml(agentYaml, answers = {}) {
+  return replacePlaceholders(agentYaml, answers);
+}
+
+module.exports = {
+  processAgentYaml,
+  extractInstallConfig,
+  stripInstallConfig,
+  getDefaultValues,
+  replacePlaceholders,
+};

package/tools/cli/lib/cli-utils.js

@@ -0,0 +1,32 @@
+/**
+ * CLI utilities — common helper functions
+ */
+const path = require('node:path');
+
+/**
+ * Resolve a directory path: use provided path or cwd
+ */
+function resolveDirectory(dir) {
+  if (!dir) return process.cwd();
+  return path.resolve(dir);
+}
+
+/**
+ * Parse comma-separated string into array of trimmed non-empty values
+ */
+function parseList(str) {
+  if (!str) return [];
+  return str
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Get OS username as default fallback
+ */
+function getSystemUsername() {
+  return process.env.USERNAME || process.env.USER || 'Reviewer';
+}
+
+module.exports = { resolveDirectory, parseList, getSystemUsername };

package/tools/cli/lib/prompts.js

@@ -0,0 +1,15 @@
+/**
+ * Prompts — wrapper around @clack/prompts for consistent CLI output
+ */
+const clack = require('@clack/prompts');
+
+const log = {
+  info: async (msg) => clack.log.info(msg),
+  success: async (msg) => clack.log.success(msg),
+  warn: async (msg) => clack.log.warn(msg),
+  error: async (msg) => clack.log.error(msg),
+  message: async (msg) => clack.log.message(msg),
+  step: async (msg) => clack.log.step(msg),
+};
+
+module.exports = { ...clack, log };

package/tools/cli/lib/ui.js

@@ -0,0 +1,132 @@
+/**
+ * UI — Interactive prompts for installation
+ * Interactive CLI UI for PR Review installer
+ */
+const clack = require('@clack/prompts');
+const path = require('node:path');
+const { parseList, resolveDirectory, getSystemUsername } = require('./cli-utils');
+const { Detector } = require('../installers/lib/core/detector');
+const { IdeManager } = require('../installers/lib/ide/manager');
+
+const detector = new Detector();
+const ideManager = new IdeManager();
+
+class UI {
+  /**
+   * Prompt user through the full install configuration
+   * @param {Object} cliOptions - Parsed CLI options
+   * @returns {Object} config object for Installer
+   */
+  async promptInstall(cliOptions) {
+    await ideManager.ensureInitialized();
+
+    clack.intro('PR Review — AI-driven Code Review Framework');
+
+    const projectDir = resolveDirectory(cliOptions.directory);
+    const dirName = path.basename(projectDir);
+
+    // Check for existing installation
+    const existing = await detector.detect(projectDir);
+    let actionType = cliOptions.action || null;
+
+    if (existing.installed && !actionType) {
+      if (cliOptions.yes) {
+        actionType = 'update';
+      } else {
+        actionType = await clack.select({
+          message: `PR Review v${existing.version} is already installed. What would you like to do?`,
+          options: [
+            { value: 'update', label: 'Full Update — reinstall all modules' },
+            { value: 'quick-update', label: 'Quick Update — refresh files, keep settings' },
+            { value: 'cancel', label: 'Cancel' },
+          ],
+        });
+        if (clack.isCancel(actionType)) return { actionType: 'cancel' };
+      }
+    } else if (!actionType) {
+      actionType = 'install';
+    }
+
+    if (actionType === 'cancel') return { actionType: 'cancel' };
+    if (actionType === 'quick-update') {
+      return { actionType: 'quick-update', projectDir, existing };
+    }
+
+    // Collect core config
+    const userName = cliOptions.userName
+      || (!cliOptions.yes && await this._ask('What should reviewers call you?', getSystemUsername()))
+      || getSystemUsername();
+
+    const communicationLanguage = cliOptions.communicationLanguage
+      || (!cliOptions.yes && await this._ask('Language for reviewer agents?', 'English'))
+      || 'English';
+
+    const outputFolder = cliOptions.outputFolder
+      || (!cliOptions.yes && await this._ask('Output folder (relative to project root)?', '_prr-output'))
+      || '_prr-output';
+
+    // PRR module config
+    const targetRepo = cliOptions.targetRepo
+      || (!cliOptions.yes && await this._ask('Path to the git repo to review?', '.'))
+      || '.';
+
+    const githubRepo = cliOptions.githubRepo
+      || (!cliOptions.yes && await this._ask('GitHub repo for posting comments? (owner/repo, blank to skip)', ''))
+      || '';
+
+    // Modules (default: prr)
+    const modulesInput = cliOptions.modules
+      ? parseList(cliOptions.modules)
+      : ['prr'];
+
+    // IDEs
+    let selectedIdes = cliOptions.tools === 'none'
+      ? []
+      : cliOptions.tools
+        ? parseList(cliOptions.tools)
+        : null;
+
+    if (selectedIdes === null && !cliOptions.yes) {
+      const availableIdes = ideManager.getAvailableIdes();
+      const choices = await clack.multiselect({
+        message: 'Which IDEs should PR Review be configured for?',
+        options: availableIdes.map((ide) => ({
+          value: ide.value,
+          label: ide.name,
+          hint: ide.preferred ? 'recommended' : undefined,
+        })),
+        required: false,
+      });
+      selectedIdes = clack.isCancel(choices) ? [] : choices;
+    } else if (selectedIdes === null) {
+      selectedIdes = ideManager.getPreferredIdes().map((ide) => ide.value);
+    }
+
+    clack.outro('Configuration complete — starting installation...');
+
+    return {
+      actionType,
+      projectDir,
+      userName,
+      communicationLanguage,
+      outputFolder,
+      targetRepo,
+      githubRepo,
+      selectedModules: modulesInput,
+      selectedIdes,
+      existing,
+    };
+  }
+
+  async _ask(message, defaultValue) {
+    const result = await clack.text({
+      message,
+      placeholder: defaultValue,
+      defaultValue,
+    });
+    if (clack.isCancel(result)) return defaultValue;
+    return result || defaultValue;
+  }
+}
+
+module.exports = { UI };

package/tools/cli/lib/xml-utils.js

@@ -0,0 +1,24 @@
+/**
+ * XML utilities — escape/unescape for agent XML generation
+ */
+function escapeXml(str) {
+  if (typeof str !== 'string') return String(str ?? '');
+  return str
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&apos;');
+}
+
+function unescapeXml(str) {
+  if (typeof str !== 'string') return str;
+  return str
+    .replaceAll('&apos;', "'")
+    .replaceAll('&quot;', '"')
+    .replaceAll('&gt;', '>')
+    .replaceAll('&lt;', '<')
+    .replaceAll('&amp;', '&');
+}
+
+module.exports = { escapeXml, unescapeXml };

package/tools/cli/prr-cli.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * PR Review CLI — Main entry point
+ * Usage: node tools/cli/prr-cli.js <command> [options]
+ */
+
+const { program } = require('commander');
+const path = require('node:path');
+const fs = require('node:fs');
+
+const packageJson = require('../../package.json');
+
+// Dynamically load all command modules from commands/
+const commandsPath = path.join(__dirname, 'commands');
+const commandFiles = fs.readdirSync(commandsPath).filter((f) => f.endsWith('.js'));
+
+for (const file of commandFiles) {
+  const cmd = require(path.join(commandsPath, file));
+
+  const command = program
+    .command(cmd.command)
+    .description(cmd.description);
+
+  for (const option of cmd.options || []) {
+    command.option(...option);
+  }
+
+  command.action(cmd.action);
+}
+
+program
+  .name('pr-review')
+  .version(packageJson.version)
+  .description('PR Review Framework — AI-driven code review agent system');
+
+program.parse(process.argv);

package/tools/prr-npx-wrapper.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * PR Review NPX wrapper
+ * Entry point for `npx pr-review` usage
+ */
+require('./cli/prr-cli.js');