praxis-sec 1.0.0

package/cli/utils/pdf-generator.js

@@ -0,0 +1,94 @@
+/**
+ * PDF Generator
+ * ==============
+ *
+ * Zero-dependency PDF generation via Chrome/Chromium headless mode.
+ * Falls back to generating a print-optimized HTML file if Chrome is not found.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { execFileSync } from 'child_process';
+
+/**
+ * Well-known Chrome/Chromium paths by platform.
+ */
+function findChrome() {
+  const candidates = process.platform === 'win32'
+    ? [
+        process.env.CHROME_PATH,
+        'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+        'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+        process.env.LOCALAPPDATA && path.join(process.env.LOCALAPPDATA, 'Google\\Chrome\\Application\\chrome.exe'),
+      ]
+    : process.platform === 'darwin'
+    ? [
+        process.env.CHROME_PATH,
+        '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+        '/Applications/Chromium.app/Contents/MacOS/Chromium',
+      ]
+    : [
+        process.env.CHROME_PATH,
+        '/usr/bin/google-chrome',
+        '/usr/bin/google-chrome-stable',
+        '/usr/bin/chromium',
+        '/usr/bin/chromium-browser',
+        '/snap/bin/chromium',
+      ];
+
+  for (const c of candidates) {
+    if (c && fs.existsSync(c)) return c;
+  }
+  return null;
+}
+
+/**
+ * Check if Chrome is available.
+ */
+export function isChromeAvailable() {
+  return findChrome() !== null;
+}
+
+/**
+ * Generate PDF from an HTML file using Chrome headless.
+ * Returns the output path, or null if Chrome is not available.
+ */
+export function generatePDF(htmlPath, outputPath) {
+  const chrome = findChrome();
+  if (!chrome) return null;
+
+  try {
+    const args = [
+      '--headless',
+      '--disable-gpu',
+      '--no-sandbox',
+      `--print-to-pdf=${outputPath}`,
+      '--print-to-pdf-no-header',
+      htmlPath,
+    ];
+    execFileSync(chrome, args, { timeout: 30000, stdio: 'pipe' }); // praxis-ignore — execFileSync with fixed chrome binary path; no user input in command
+    return outputPath;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Generate a print-optimized HTML file as PDF fallback.
+ */
+export function generatePrintHTML(htmlPath, outputPath) {
+  let html = fs.readFileSync(htmlPath, 'utf-8');
+  // Add print-optimized styles
+  const printCSS = `
+<style media="print">
+  body { background: #fff !important; color: #1e293b !important; }
+  .score-card, .stat, .summary-card, .toc { background: #f8fafc !important; border: 1px solid #e2e8f0 !important; }
+  table, th, td { border: 1px solid #e2e8f0 !important; }
+  code { background: #f1f5f9 !important; color: #0f172a !important; }
+  pre { background: #f1f5f9 !important; }
+  a { color: #0369a1 !important; }
+</style>`;
+  html = html.replace('</head>', printCSS + '\n</head>');
+  fs.writeFileSync(outputPath, html);
+  return outputPath;
+}

package/cli/utils/plugin-loader.js

@@ -0,0 +1,364 @@
+/**
+ * Plugin Loader — Custom Agent Plugin System
+ * ============================================
+ *
+ * Allows users to drop custom security agents into `.praxis/agents/` and
+ * have them automatically loaded and run alongside the built-in agents.
+ *
+ * HOW IT WORKS:
+ *   1. On startup, loadPlugins(rootPath) scans `.praxis/agents/*.js`
+ *   2. Each file must export a default class that extends BaseAgent
+ *   3. Validated plugins are instantiated and returned for registration
+ *   4. buildOrchestrator() calls loadPlugins() and registers the results
+ *
+ * PLUGIN CONTRACT:
+ *   A valid plugin must:
+ *   - Export a default class (ES module)
+ *   - Extend BaseAgent (from praxis's agent framework)
+ *   - Implement `async analyze(context)` returning an array of findings
+ *   - Set `this.name` and `this.category` in the constructor
+ *
+ * EXAMPLE PLUGIN:
+ *
+ *   // .praxis/agents/my-rule.js
+ *   import { BaseAgent, createFinding } from 'praxis';
+ *
+ *   export default class MyCustomRule extends BaseAgent {
+ *     constructor() {
+ *       super();
+ *       this.name     = 'MyCustomRule';
+ *       this.category = 'custom';
+ *     }
+ *
+ *     async analyze({ rootPath, files }) {
+ *       const findings = [];
+ *       for (const file of files) {
+ *         const content = fs.readFileSync(file, 'utf-8');
+ *         if (content.includes('eval(')) { // praxis-ignore — JSDoc example, not real eval
+ *           findings.push(createFinding({
+ *             rule:        'CUSTOM_EVAL',
+ *             severity:    'high',
+ *             title:       'Dangerous eval() usage', // praxis-ignore — JSDoc string literal
+ *             description: 'eval() can execute arbitrary code', // praxis-ignore — JSDoc string literal
+ *             file,
+ *             remediation: 'Replace eval() with safer alternatives', // praxis-ignore — JSDoc string literal
+ *           }));
+ *         }
+ *       }
+ *       return findings;
+ *     }
+ *   }
+ *
+ * PLUGIN ISOLATION:
+ *   Plugins run in the same process but each agent gets its own timeout (30s).
+ *   A crashing or hanging plugin does not affect other agents.
+ *
+ * SECURITY NOTE:
+ *   Plugins are arbitrary code executed from the local filesystem. Never install
+ *   plugins from untrusted sources. praxis will warn if plugins are detected.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { pathToFileURL } from 'url';
+import { BaseAgent, createFinding } from '../agents/base-agent.js';
+
+const PLUGIN_DIR = '.praxis/agents';
+
+/**
+ * Load custom agent plugins from .praxis/agents/*.js
+ *
+ * @param {string} rootPath — project root directory
+ * @param {object} options  — { verbose, quiet }
+ * @returns {Promise<object[]>} — array of instantiated agent objects
+ */
+export async function loadPlugins(rootPath, options = {}) {
+  const pluginDir = path.join(rootPath, PLUGIN_DIR);
+
+  if (!fs.existsSync(pluginDir)) return [];
+
+  let files;
+  try {
+    files = fs.readdirSync(pluginDir)
+      .filter(f => f.endsWith('.js') || f.endsWith('.mjs'))
+      .map(f => path.join(pluginDir, f));
+  } catch {
+    return [];
+  }
+
+  if (files.length === 0) return [];
+
+  if (!options.quiet) {
+    console.log(`  Loading ${files.length} plugin(s) from ${PLUGIN_DIR}...`);
+  }
+
+  // Expose the agent framework to plugins regardless of how praxis was
+  // launched (source tree or installed package) — plugins read this first.
+  globalThis.__praxisAgentFramework = { BaseAgent, createFinding };
+
+  const plugins = [];
+
+  for (const filePath of files) {
+    try {
+      const fileUrl = pathToFileURL(filePath).href;
+      const mod     = await import(fileUrl);
+      const PluginClass = mod.default;
+
+      if (typeof PluginClass !== 'function') {
+        if (options.verbose) console.warn(`  [plugin] ${path.basename(filePath)}: no default export class`);
+        continue;
+      }
+
+      // Validate the plugin before instantiation
+      const validation = validatePlugin(PluginClass, filePath);
+      if (!validation.valid) {
+        console.warn(`  [plugin] ${path.basename(filePath)} skipped: ${validation.reason}`);
+        continue;
+      }
+
+      const instance = new PluginClass();
+
+      // Ensure required fields are set after construction
+      if (!instance.name) {
+        instance.name = path.basename(filePath, '.js');
+      }
+      if (!instance.category) {
+        instance.category = 'custom';
+      }
+
+      // Sandbox the analyze method to restrict file system access and block shell executions
+      const originalAnalyze = instance.analyze;
+      instance.analyze = async function(context) {
+        const child_process = await import('child_process');
+        
+        const originalReadFileSync = fs.readFileSync;
+        const originalWriteFileSync = fs.writeFileSync;
+        const originalReadFile = fs.readFile;
+        const originalWriteFile = fs.writeFile;
+        const originalPromisesReadFile = fs.promises?.readFile;
+        const originalPromisesWriteFile = fs.promises?.writeFile;
+        const originalExec = child_process.exec;
+        const originalExecSync = child_process.execSync;
+        const originalSpawn = child_process.spawn;
+        const originalSpawnSync = child_process.spawnSync;
+        
+        const isSafePath = (p) => {
+          if (!p) return false;
+          try {
+            const resolved = path.resolve(context.rootPath, String(p));
+            return resolved.startsWith(path.resolve(context.rootPath));
+          } catch {
+            return false;
+          }
+        };
+        
+        fs.readFileSync = (p, ...args) => {
+          if (!isSafePath(p)) throw new Error(`Access denied (sandbox): read outside workspace path ${p}`);
+          return originalReadFileSync(p, ...args);
+        };
+        fs.writeFileSync = (p, ...args) => {
+          if (!isSafePath(p)) throw new Error(`Access denied (sandbox): write outside workspace path ${p}`);
+          return originalWriteFileSync(p, ...args);
+        };
+        fs.readFile = (p, ...args) => {
+          if (!isSafePath(p)) throw new Error(`Access denied (sandbox): read outside workspace path ${p}`);
+          return originalReadFile(p, ...args);
+        };
+        fs.writeFile = (p, ...args) => {
+          if (!isSafePath(p)) throw new Error(`Access denied (sandbox): write outside workspace path ${p}`);
+          return originalWriteFile(p, ...args);
+        };
+        if (fs.promises) {
+          fs.promises.readFile = async (p, ...args) => {
+            if (!isSafePath(p)) throw new Error(`Access denied (sandbox): read outside workspace path ${p}`);
+            return originalPromisesReadFile(p, ...args);
+          };
+          fs.promises.writeFile = async (p, ...args) => {
+            if (!isSafePath(p)) throw new Error(`Access denied (sandbox): write outside workspace path ${p}`);
+            return originalPromisesWriteFile(p, ...args);
+          };
+        }
+        
+        // Best-effort lockdown: ESM module namespaces are immutable, so this
+        // only takes effect where child_process exposes mutable bindings.
+        // The fs path guard above still applies in all cases.
+        try {
+          child_process.exec = () => { throw new Error('Access denied (sandbox): exec not allowed in plugins'); };
+          child_process.execSync = () => { throw new Error('Access denied (sandbox): execSync not allowed in plugins'); };
+          child_process.spawn = () => { throw new Error('Access denied (sandbox): spawn not allowed in plugins'); };
+          child_process.spawnSync = () => { throw new Error('Access denied (sandbox): spawnSync not allowed in plugins'); };
+        } catch { /* immutable ESM namespace */ }
+        
+        try {
+          return await originalAnalyze.call(this, context);
+        } finally {
+          fs.readFileSync = originalReadFileSync;
+          fs.writeFileSync = originalWriteFileSync;
+          fs.readFile = originalReadFile;
+          fs.writeFile = originalWriteFile;
+          if (fs.promises) {
+            fs.promises.readFile = originalPromisesReadFile;
+            fs.promises.writeFile = originalPromisesWriteFile;
+          }
+          try {
+            child_process.exec = originalExec;
+            child_process.execSync = originalExecSync;
+            child_process.spawn = originalSpawn;
+            child_process.spawnSync = originalSpawnSync;
+          } catch { /* immutable ESM namespace */ }
+        }
+      };
+
+      plugins.push(instance);
+
+      if (!options.quiet) {
+        console.log(`  [plugin] Loaded: ${instance.name} (${instance.category})`);
+      }
+    } catch (err) {
+      console.warn(`  [plugin] Failed to load ${path.basename(filePath)}: ${err.message}`);
+    }
+  }
+
+  return plugins;
+}
+
+/**
+ * Validate a plugin class before instantiation.
+ * Does static checks only — does not instantiate.
+ */
+function validatePlugin(PluginClass, filePath) {
+  const name = path.basename(filePath);
+
+  if (typeof PluginClass !== 'function') {
+    return { valid: false, reason: 'default export is not a class/function' };
+  }
+
+  // Check prototype has analyze() — the required method
+  const proto = PluginClass.prototype;
+  if (typeof proto?.analyze !== 'function') {
+    return { valid: false, reason: 'class does not implement analyze()' };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * List available plugins without loading them.
+ * Used by `praxis doctor` and `praxis plugins list`.
+ */
+export function listPluginFiles(rootPath) {
+  const pluginDir = path.join(rootPath, PLUGIN_DIR);
+  if (!fs.existsSync(pluginDir)) return [];
+
+  try {
+    return fs.readdirSync(pluginDir)
+      .filter(f => f.endsWith('.js') || f.endsWith('.mjs'))
+      .map(f => ({
+        name: path.basename(f, '.js'),
+        path: path.join(pluginDir, f),
+        size: fs.statSync(path.join(pluginDir, f)).size,
+      }));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Scaffold a new plugin file in .praxis/agents/
+ */
+export function scaffoldPlugin(rootPath, pluginName) {
+  const pluginDir = path.join(rootPath, PLUGIN_DIR);
+  if (!fs.existsSync(pluginDir)) {
+    fs.mkdirSync(pluginDir, { recursive: true });
+  }
+
+  const safeName  = pluginName.replace(/[^a-zA-Z0-9_-]/g, '-');
+  const className = safeName.replace(/-([a-z])/g, (_, c) => c.toUpperCase()).replace(/^[a-z]/, c => c.toUpperCase());
+  const filePath  = path.join(pluginDir, `${safeName}.js`);
+
+  if (fs.existsSync(filePath)) {
+    throw new Error(`Plugin already exists: ${filePath}`);
+  }
+
+  const template = `/**
+ * Custom Praxis Agent: ${className}
+ *
+ * Drop this file in .praxis/agents/ to have it run automatically
+ * as part of every \`praxis audit\` or \`praxis watch --deep\`.
+ *
+ * The \`analyze(context)\` method receives:
+ *   context.rootPath   — absolute path to the project root
+ *   context.files      — array of absolute file paths to scan
+ *   context.recon      — recon data (frameworks, databases, auth patterns)
+ *   context.options    — CLI options passed to the scan
+ *
+ * Return an array of findings using \`createFinding()\`.
+ */
+
+import fs from 'fs';
+
+// BaseAgent and createFinding are injected by the plugin loader at runtime.
+// Fallbacks cover standalone use: the installed package, then source layout.
+let BaseAgent, createFinding;
+if (globalThis.__praxisAgentFramework) {
+  ({ BaseAgent, createFinding } = globalThis.__praxisAgentFramework);
+} else {
+  try {
+    ({ BaseAgent, createFinding } = await import('praxis'));
+  } catch {
+    ({ BaseAgent, createFinding } = await import('praxis/cli/index.js'));
+  }
+}
+
+export default class ${className} extends BaseAgent {
+  constructor() {
+    super();
+    this.name     = '${className}';
+    this.category = 'custom'; // or: secrets | injection | auth | config | api | llm
+  }
+
+  async analyze({ rootPath, files = [], recon, options }) {
+    const findings = [];
+
+    for (const file of files) {
+      // Skip files you don't care about
+      if (!/\\.(js|ts|jsx|tsx|py|rb|go|java)$/.test(file)) continue;
+
+      let content;
+      try {
+        content = fs.readFileSync(file, 'utf-8');
+      } catch {
+        continue;
+      }
+
+      const lines = content.split('\\n');
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (/praxis-ignore/i.test(line)) continue; // respect suppression comments
+
+        // Example: flag dangerous eval calls // praxis-ignore
+        if (/\\beval\\s*\\(/.test(line)) { // praxis-ignore — template example in plugin scaffold, not real eval
+          findings.push(createFinding({
+            rule:        '${safeName.toUpperCase().replace(/-/g, '_')}',
+            severity:    'high',          // critical | high | medium | low
+            title:       'Example finding from ${className}',
+            description: 'Describe the security risk here.',
+            file,
+            line:        i + 1,
+            matched:     line.trim().slice(0, 100),
+            category:    this.category,
+            remediation: 'Describe the fix here.',
+            confidence:  'medium',        // high | medium | low
+          }));
+        }
+      }
+    }
+
+    return findings;
+  }
+}
+`;
+
+  fs.writeFileSync(filePath, template, 'utf-8');
+  return filePath;
+}

package/cli/utils/rule-import.js

@@ -0,0 +1,228 @@
+/**
+ * Portable rule import — the inverse of the export (P-IMP-060).
+ * ============================================================================
+ *
+ * Deliberately scoped, and the scope matters:
+ *
+ *   ACCEPTS  pattern rules — the same records the export produces, which map 1:1 onto
+ *            what Praxis can execute.
+ *   REJECTS  anything else, with a stated reason, rather than importing it in a
+ *            degraded form. Notably: AST/taint semantics, probe-corpus rules and
+ *            entropy heuristics cannot be expressed as a static pattern, so a bundle
+ *            claiming to carry them is told so rather than quietly losing them.
+ *
+ * This is NOT a general Semgrep parser. Praxis has no YAML runtime dependency (five
+ * runtime deps, none a YAML parser), so the canonical round-trip format is the JSON
+ * written alongside the Semgrep YAML. Handing it Semgrep YAML gets a clear error
+ * explaining the supported path instead of a silent failure.
+ *
+ * What it produces is a real, runnable Praxis plugin, so an imported rule participates
+ * in real scans rather than sitting inert on disk.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Loads a portable bundle.
+ *
+ * @param {string} file  Path to `praxis-rules.json` (canonical) — Semgrep YAML is
+ *                       rejected with an explanation.
+ * @returns {{ok: true, accepted: object[], rejected: object[], meta: object}
+ *          | {ok: false, error: string}}
+ */
+export function loadPortableBundle(file) {
+  if (!file || typeof file !== 'string') {
+    return { ok: false, error: 'a bundle path is required' };
+  }
+  const ext = path.extname(file).toLowerCase();
+  if (ext === '.yaml' || ext === '.yml') {
+    return {
+      ok: false,
+      error:
+        'Semgrep YAML is an export format, not an import format. Praxis has no YAML ' +
+        'runtime dependency; import praxis-rules.json (written alongside the YAML) instead.',
+    };
+  }
+  if (ext !== '.json') {
+    return { ok: false, error: `unsupported bundle extension "${ext}" (expected .json)` };
+  }
+
+  let data;
+  try {
+    data = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (err) {
+    return { ok: false, error: `could not read bundle: ${err.message}` };
+  }
+
+  if (!data || !Array.isArray(data.rules)) {
+    return { ok: false, error: 'bundle has no `rules` array' };
+  }
+
+  const accepted = [];
+  const rejected = [];
+
+  for (const r of data.rules) {
+    if (!r || typeof r !== 'object') {
+      rejected.push({ id: r?.id ?? null, reason: 'not an object' });
+      continue;
+    }
+    if (typeof r.id !== 'string' || !r.id) {
+      rejected.push({ id: null, reason: 'missing id' });
+      continue;
+    }
+    if (typeof r.pattern !== 'string' || !r.pattern) {
+      rejected.push({
+        id: r.id,
+        reason: 'no portable pattern — AST/taint, probe-corpus and entropy rules cannot be expressed as a static pattern',
+      });
+      continue;
+    }
+
+    // Praxis executes JavaScript regexes, so convert the PCRE2 form back before use.
+    const { pattern: jsPattern, flags } = toJsPattern(r.pattern);
+    try {
+      // eslint-disable-next-line no-new
+      new RegExp(jsPattern, flags);
+    } catch (err) {
+      rejected.push({ id: r.id, reason: `pattern does not compile in JavaScript: ${err.message}` });
+      continue;
+    }
+
+    accepted.push({
+      id: r.id,
+      title: r.title || r.id,
+      severity: String(r.severity || 'medium').toLowerCase(),
+      description: r.description || r.title || r.id,
+      fix: r.fix || null,
+      cwe: r.cwe || null,
+      owasp: r.owasp || null,
+      jsPattern,
+      jsFlags: flags,
+      origin: r.origin || 'imported',
+    });
+  }
+
+  return {
+    ok: true,
+    accepted,
+    rejected,
+    meta: {
+      source: file,
+      total: data.rules.length,
+      generator: data.generator || null,
+      praxisVersion: data.praxisVersion || null,
+      praxisOnlyLayers: data.praxisOnlyLayers || [],
+    },
+  };
+}
+
+/**
+ * Converts a PCRE2 portable pattern back into JavaScript form.
+ *
+ * Returns `{ pattern, flags }`. The inline flag groups are NOT simply stripped: doing so
+ * would silently turn every case-insensitive rule into a case-sensitive one. They are
+ * translated into JavaScript's flag position (`i`, `m`, `s`), which JavaScript supports.
+ * `x` (extended/free-spacing) has no JavaScript equivalent and is reported.
+ */
+export function toJsPattern(portablePattern) {
+  let flags = '';
+  let s = String(portablePattern);
+
+  s = s.replace(/^(?:\(\?([imsx]+)\))+/, (_m, group) => {
+    for (const f of group) {
+      if ('ims'.includes(f) && !flags.includes(f)) flags += f;
+    }
+    return '';
+  });
+
+  // PCRE2 \x{...} -> JS \u{...}
+  s = s.replace(/\\x\{([0-9a-fA-F]+)\}/g, '\\u{$1}');
+
+  // Semgrep matches every occurrence; JavaScript needs the global flag to iterate.
+  if (!flags.includes('g')) flags += 'g';
+
+  return { pattern: s, flags };
+}
+
+/**
+ * Emits a runnable Praxis plugin for the accepted rules.
+ *
+ * Uses the same plugin contract as `plugin-loader` (`.praxis/agents/*.js`), so
+ * imported rules participate in real scans instead of sitting inert.
+ */
+export function renderPlugin(accepted, { name = 'PortableRules' } = {}) {
+  const className = `${name.replace(/[^A-Za-z0-9]/g, '')}Agent`;
+  // Resolve at generation time so the emitted plugin has no unresolved placeholders.
+  // Mirrors plugin-loader: prefer the installed package, fall back to the source tree.
+  const packageRoot = (() => {
+    try {
+      return JSON.parse(fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).name || 'praxis';
+    } catch {
+      return 'praxis';
+    }
+  })();
+  // `scanFileWithPatterns` requires a real RegExp object (it advances `lastIndex`),
+  // so the rules are emitted as constructed expressions rather than strings. Emitting
+  // the pattern as a bare string yields "Cannot create property 'lastIndex' on string".
+  // Built as JS source rather than JSON.stringify'd, because the regex must be code.
+  const q = (v) => JSON.stringify(v === undefined || v === null ? '' : String(v));
+  const rulesSource = accepted.map(r =>
+    `  { rule: ${q(r.id)}, title: ${q(r.title)}, regex: new RegExp(${q(r.jsPattern)}, ${q(r.jsFlags)}),` +
+    ` severity: ${q(r.severity)}, description: ${q(r.description)}, fix: ${q(r.fix)},` +
+    ` cwe: ${q(r.cwe)}, owasp: ${q(r.owasp)} }`
+  ).join(',\n');
+
+  return `/**
+ * Portable rules imported by \`praxis rules import\`.
+ *
+ * ${accepted.length} pattern rule(s) loaded from a Praxis portable bundle.
+ * Dropped in .praxis/agents/, this participates in every \`praxis audit\`.
+ *
+ * Regenerate with:  praxis rules import <bundle.json> --write-plugin .praxis/agents
+ *
+ * Scope: pattern rules only. AST/taint analysis, the prompt-injection probe corpus
+ * and entropy heuristics are NOT importable — they are not static patterns.
+ */
+
+// BaseAgent and createFinding are injected by the plugin loader at runtime.
+let BaseAgent, createFinding;
+if (globalThis.__praxisAgentFramework) {
+  ({ BaseAgent, createFinding } = globalThis.__praxisAgentFramework);
+} else {
+  try {
+    ({ BaseAgent, createFinding } = await import('${packageRoot}')); // praxis-ignore AGENT_ESCALATED_PERMISSIONS — generated plugin importing the Praxis framework; same lines as plugin-loader.js
+  } catch {
+    ({ BaseAgent, createFinding } = await import('${packageRoot}/cli/index.js')); // praxis-ignore AGENT_ESCALATED_PERMISSIONS — generated plugin importing the Praxis framework; same lines as plugin-loader.js
+  }
+}
+
+const RULES = [
+${rulesSource}
+];
+
+export default class ${className} extends BaseAgent {
+  constructor() {
+    super('${className}', 'Portable rules imported from a Praxis rule bundle', 'custom');
+    this.category = 'custom';
+  }
+
+  async analyze({ files = [] }) {
+    const findings = [];
+    for (const file of files) {
+      const results = this.scanFileWithPatterns(file, RULES);
+      findings.push(...results);
+    }
+    return findings;
+  }
+}
+`;
+}
+
+/** Writes the plugin into a directory, creating it if needed. */
+export function writePlugin(accepted, dir, opts = {}) {
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, 'portable-rules.js');
+  fs.writeFileSync(file, renderPlugin(accepted, opts), 'utf8');
+  return file;
+}