@girardelli/architect 1.3.0 → 2.1.0

package/src/html-reporter.ts

@@ -1,11 +1,12 @@
-import { AnalysisReport, AntiPattern } from './types.js';
+import { AnalysisReport, AntiPattern, RefactoringPlan, RefactorStep } from './types.js';
+import { AgentSuggestion } from './agent-generator.js';
 
 /**
  * Generates premium visual HTML reports from AnalysisReport.
  * Features: D3.js force graph, bubble charts, radar chart, animated counters.
  */
 export class HtmlReportGenerator {
-  generateHtml(report: AnalysisReport): string {
+  generateHtml(report: AnalysisReport, plan?: RefactoringPlan, agentSuggestion?: AgentSuggestion): string {
     const grouped = this.groupAntiPatterns(report.antiPatterns);
     const sugGrouped = this.groupSuggestions(report.suggestions);
 
@@ -29,6 +30,8 @@ ${this.renderHeader(report)}
   ${this.renderAntiPatternBubbles(report, grouped)}
   ${this.renderAntiPatterns(report, grouped)}
   ${this.renderSuggestions(sugGrouped)}
+  ${plan ? this.renderRefactoringPlan(plan) : ''}
+  ${agentSuggestion ? this.renderAgentSuggestions(agentSuggestion) : ''}
 </div>
 ${this.renderFooter()}
 ${this.getScripts(report)}
@@ -388,11 +391,160 @@ ${this.getScripts(report)}
   private renderFooter(): string {
     return `
 <div class="footer">
-  <p>Generated by <a href="https://github.com/camilooscargbaptista/architect">🏗️ Architect</a> — AI-powered architecture analysis</p>
+  <p>Generated by <a href="https://github.com/camilooscargbaptista/architect">🏗️ Architect v2.0</a> — AI-powered architecture analysis + refactoring engine</p>
   <p>By <strong>Camilo Girardelli</strong> · <a href="https://www.girardellitecnologia.com">Girardelli Tecnologia</a></p>
 </div>`;
   }
 
+  // ── Refactoring Plan Section ──
+
+  private opColor(type: string): string {
+    switch (type) {
+      case 'CREATE': return '#22c55e';
+      case 'MOVE': return '#3b82f6';
+      case 'MODIFY': return '#f59e0b';
+      case 'DELETE': return '#ef4444';
+      default: return '#64748b';
+    }
+  }
+
+  private opIcon(type: string): string {
+    switch (type) {
+      case 'CREATE': return '➕';
+      case 'MOVE': return '📦';
+      case 'MODIFY': return '✏️';
+      case 'DELETE': return '🗑️';
+      default: return '📄';
+    }
+  }
+
+  private renderRefactoringPlan(plan: RefactoringPlan): string {
+    if (plan.steps.length === 0) {
+      return `
+<h2 class="section-title">✅ Refactoring Plan</h2>
+<div class="card success-card">
+  <p>No refactoring needed! Your architecture is already in great shape.</p>
+</div>`;
+    }
+
+    const improvement = plan.estimatedScoreAfter.overall - plan.currentScore.overall;
+
+    const metrics = Object.keys(plan.currentScore.breakdown) as Array<keyof typeof plan.currentScore.breakdown>;
+    const bars = metrics.map(metric => {
+      const before = plan.currentScore.breakdown[metric];
+      const after = plan.estimatedScoreAfter.breakdown[metric] ?? before;
+      const diff = after - before;
+      return `
+      <div class="comparison-row">
+        <div class="refactor-metric-name">${metric}</div>
+        <div class="refactor-metric-bars">
+          <div class="rbar-before" style="width: ${before}%; background: ${this.scoreColor(before)}40"><span>${before}</span></div>
+          <div class="rbar-after" style="width: ${after}%; background: ${this.scoreColor(after)}"><span>${after}</span></div>
+        </div>
+        <div class="refactor-metric-diff" style="color: ${diff > 0 ? '#22c55e' : '#64748b'}">
+          ${diff > 0 ? `+${diff}` : diff === 0 ? '—' : String(diff)}
+        </div>
+      </div>`;
+    }).join('');
+
+    const stepsHtml = plan.steps.map(step => this.renderRefactorStep(step)).join('');
+
+    const criticalCount = plan.steps.filter(s => s.priority === 'CRITICAL').length;
+    const highCount = plan.steps.filter(s => s.priority === 'HIGH').length;
+    const mediumCount = plan.steps.filter(s => s.priority === 'MEDIUM').length;
+    const lowCount = plan.steps.filter(s => s.priority === 'LOW').length;
+
+    return `
+<h2 class="section-title">🔧 Refactoring Plan</h2>
+
+<div class="card refactor-score">
+  <div class="refactor-score-pair">
+    <div class="rscore-box">
+      <div class="rscore-num" style="color: ${this.scoreColor(plan.currentScore.overall)}">${plan.currentScore.overall}</div>
+      <div class="rscore-label">Current</div>
+    </div>
+    <div class="rscore-arrow">
+      <svg width="60" height="30" viewBox="0 0 60 30">
+        <path d="M5 15 L45 15 M40 8 L48 15 L40 22" stroke="#818cf8" stroke-width="2.5" fill="none"/>
+      </svg>
+    </div>
+    <div class="rscore-box">
+      <div class="rscore-num" style="color: ${this.scoreColor(plan.estimatedScoreAfter.overall)}">${plan.estimatedScoreAfter.overall}</div>
+      <div class="rscore-label">Estimated</div>
+    </div>
+    <div class="rscore-improvement" style="color: #22c55e">+${improvement} pts</div>
+  </div>
+  <div class="refactor-bars-section">
+    <div class="refactor-legend">
+      <span class="rlegend-tag rbefore">Before</span>
+      <span class="rlegend-tag rafter">After</span>
+    </div>
+    ${bars}
+  </div>
+</div>
+
+<div class="refactor-stats-row">
+  <div class="rstat">${plan.steps.length} steps</div>
+  <div class="rstat">${plan.totalOperations} operations</div>
+  <div class="rstat">Tier 1: ${plan.tier1Steps}</div>
+  <div class="rstat">Tier 2: ${plan.tier2Steps}</div>
+</div>
+
+<div class="priority-bar">
+  ${criticalCount ? `<div class="prio-seg prio-critical" style="flex: ${criticalCount}">🔴 ${criticalCount}</div>` : ''}
+  ${highCount ? `<div class="prio-seg prio-high" style="flex: ${highCount}">🟠 ${highCount}</div>` : ''}
+  ${mediumCount ? `<div class="prio-seg prio-medium" style="flex: ${mediumCount}">🔵 ${mediumCount}</div>` : ''}
+  ${lowCount ? `<div class="prio-seg prio-low" style="flex: ${lowCount}">🟢 ${lowCount}</div>` : ''}
+</div>
+
+<div class="refactor-roadmap">
+  ${stepsHtml}
+</div>`;
+  }
+
+  private renderRefactorStep(step: RefactorStep): string {
+    const operationsHtml = step.operations.map(op => `
+      <div class="rop">
+        <span class="rop-icon">${this.opIcon(op.type)}</span>
+        <span class="rop-badge" style="background: ${this.opColor(op.type)}20; color: ${this.opColor(op.type)}; border: 1px solid ${this.opColor(op.type)}40">${op.type}</span>
+        <code class="rop-path">${this.escapeHtml(op.path)}</code>
+        ${op.newPath ? `<span class="rop-arrow">→</span> <code class="rop-path">${this.escapeHtml(op.newPath)}</code>` : ''}
+        <div class="rop-desc">${this.escapeHtml(op.description)}</div>
+      </div>
+    `).join('');
+
+    const impactHtml = step.scoreImpact.map(i =>
+      `<span class="rimpact-tag">${i.metric}: ${i.before}→${i.after} <strong>+${i.after - i.before}</strong></span>`
+    ).join('');
+
+    return `
+<div class="rstep-card">
+  <div class="rstep-header">
+    <div class="rstep-number">${step.id}</div>
+    <div class="rstep-info">
+      <div class="rstep-title-row">
+        <h3>${this.escapeHtml(step.title)}</h3>
+        <span class="severity-badge severity-${step.priority}">${step.priority}</span>
+        <span class="tier-badge">Tier ${step.tier}</span>
+      </div>
+      <p class="rstep-desc">${this.escapeHtml(step.description)}</p>
+      <details class="rstep-details">
+        <summary>📖 Why?</summary>
+        <p class="rstep-rationale">${this.escapeHtml(step.rationale)}</p>
+      </details>
+    </div>
+  </div>
+  <div class="rstep-ops">
+    <h4>📋 Operations (${step.operations.length})</h4>
+    ${operationsHtml}
+  </div>
+  <div class="rstep-impact">
+    <h4>📈 Score Impact</h4>
+    <div class="rimpact-tags">${impactHtml}</div>
+  </div>
+</div>`;
+  }
+
   /**
    * All JavaScript for D3.js visualizations, animated counters, and radar chart
    */
@@ -516,7 +668,7 @@ function animateCounter(el, target) {
 
   const container = document.getElementById('dep-graph');
   const width = container.clientWidth || 800;
-  const height = Math.max(400, nodes.length * 25);
+  const height = 450;
   container.style.height = height + 'px';
 
   const layerColors = {
@@ -537,9 +689,11 @@ function animateCounter(el, target) {
     .attr('fill', '#475569');
 
   const simulation = d3.forceSimulation(nodes)
-    .force('link', d3.forceLink(links).id(d => d.id).distance(80))
-    .force('charge', d3.forceManyBody().strength(-200))
+    .force('link', d3.forceLink(links).id(d => d.id).distance(60))
+    .force('charge', d3.forceManyBody().strength(-150))
     .force('center', d3.forceCenter(width / 2, height / 2))
+    .force('x', d3.forceX(width / 2).strength(0.1))
+    .force('y', d3.forceY(height / 2).strength(0.1))
     .force('collision', d3.forceCollide().radius(d => Math.max(d.connections * 3 + 12, 15)));
 
   const link = svg.append('g')
@@ -574,6 +728,13 @@ function animateCounter(el, target) {
     .text(d => d.id + '\\nConnections: ' + d.connections + '\\nLayer: ' + d.layer);
 
   simulation.on('tick', () => {
+    // Clamp nodes to stay within SVG bounds
+    nodes.forEach(d => {
+      const r = Math.max(d.connections * 3 + 6, 8) + 10;
+      d.x = Math.max(r, Math.min(width - r, d.x));
+      d.y = Math.max(r, Math.min(height - r, d.y));
+    });
+
     link
       .attr('x1', d => d.source.x).attr('y1', d => d.source.y)
       .attr('x2', d => d.target.x).attr('y2', d => d.target.y);
@@ -648,6 +809,245 @@ function animateCounter(el, target) {
 <\/script>`;
   }
 
+
+  private renderAgentSuggestions(s: AgentSuggestion): string {
+    const roleIcon = (name: string): string => {
+      if (name.includes('ORCHESTRATOR')) return '\u{1F3AD}';
+      if (name.includes('BACKEND') || name.includes('FRONTEND') || name.includes('DATABASE') || name.includes('FLUTTER')) return '\u{1F4BB}';
+      if (name.includes('SECURITY')) return '\u{1F6E1}\uFE0F';
+      if (name.includes('QA')) return '\u{1F9EA}';
+      if (name.includes('TECH-DEBT')) return '\u{1F4CA}';
+      return '\u{1F916}';
+    };
+
+    const roleLabel = (name: string): string => {
+      if (name.includes('ORCHESTRATOR')) return 'coordination';
+      if (name.includes('SECURITY')) return 'protection';
+      if (name.includes('QA')) return 'quality';
+      if (name.includes('TECH-DEBT')) return 'governance';
+      return 'development';
+    };
+
+    const roleColor = (name: string): string => {
+      if (name.includes('ORCHESTRATOR')) return '#c084fc';
+      if (name.includes('SECURITY')) return '#f87171';
+      if (name.includes('QA')) return '#34d399';
+      if (name.includes('TECH-DEBT')) return '#fbbf24';
+      return '#60a5fa';
+    };
+
+    const agentCards = s.suggestedAgents.map(a =>
+      `<label class="agent-toggle-card" data-category="agents" data-name="${a}">
+        <input type="checkbox" class="agent-check" checked data-type="agents" data-item="${a}">
+        <div class="agent-toggle-inner">
+          <div class="agent-toggle-icon">${roleIcon(a)}</div>
+          <div class="agent-toggle-info">
+            <span class="agent-toggle-name">${a}</span>
+            <span class="agent-toggle-role" style="color:${roleColor(a)}">${roleLabel(a)}</span>
+          </div>
+          <div class="agent-toggle-check">\u2713</div>
+        </div>
+      </label>`
+    ).join('\n');
+
+    const ruleCards = s.suggestedRules.map(r =>
+      `<label class="agent-toggle-card mini" data-category="rules">
+        <input type="checkbox" class="agent-check" checked data-type="rules" data-item="${r}">
+        <div class="agent-toggle-inner">
+          <span class="agent-toggle-icon">\u{1F4CF}</span>
+          <span class="agent-toggle-name">${r}.md</span>
+          <div class="agent-toggle-check">\u2713</div>
+        </div>
+      </label>`
+    ).join('\n');
+
+    const guardCards = s.suggestedGuards.map(g =>
+      `<label class="agent-toggle-card mini" data-category="guards">
+        <input type="checkbox" class="agent-check" checked data-type="guards" data-item="${g}">
+        <div class="agent-toggle-inner">
+          <span class="agent-toggle-icon">\u{1F6E1}\uFE0F</span>
+          <span class="agent-toggle-name">${g}.md</span>
+          <div class="agent-toggle-check">\u2713</div>
+        </div>
+      </label>`
+    ).join('\n');
+
+    const workflowCards = s.suggestedWorkflows.map(w =>
+      `<label class="agent-toggle-card mini" data-category="workflows">
+        <input type="checkbox" class="agent-check" checked data-type="workflows" data-item="${w}">
+        <div class="agent-toggle-inner">
+          <span class="agent-toggle-icon">\u26A1</span>
+          <span class="agent-toggle-name">${w}.md</span>
+          <div class="agent-toggle-check">\u2713</div>
+        </div>
+      </label>`
+    ).join('\n');
+
+    const skillCards = s.suggestedSkills.map(sk =>
+      `<label class="agent-toggle-card" data-category="skills">
+        <input type="checkbox" class="agent-check" checked data-type="skills" data-item="${sk.source}">
+        <div class="agent-toggle-inner">
+          <span class="agent-toggle-icon">\u{1F9E0}</span>
+          <div class="agent-toggle-info">
+            <span class="agent-toggle-name">${sk.name}</span>
+            <span class="agent-toggle-role" style="color:#34d399">${sk.description}</span>
+          </div>
+          <div class="agent-toggle-check">\u2713</div>
+        </div>
+      </label>`
+    ).join('\n');
+
+    const auditSection = s.audit.filter(f => f.type !== 'OK').length > 0 ? `
+    <div class="agent-audit-section">
+      <h3 class="agent-section-subtitle">\u{1F50D} Audit Findings</h3>
+      <div class="agent-audit-grid">
+        ${s.audit.filter(f => f.type !== 'OK').map(f => {
+          const icon = f.type === 'MISSING' ? '\u274C' : f.type === 'IMPROVEMENT' ? '\u{1F4A1}' : '\u26A0\uFE0F';
+          const cls = f.type === 'MISSING' ? 'audit-missing' : 'audit-improvement';
+          return `<div class="agent-audit-item ${cls}">
+            <span class="audit-icon">${icon}</span>
+            <div class="audit-content">
+              <span class="audit-desc">${f.description}</span>
+              ${f.suggestion ? `<span class="audit-suggestion">\u2192 ${f.suggestion}</span>` : ''}
+            </div>
+          </div>`;
+        }).join('\n')}
+      </div>
+    </div>` : '';
+
+    const stackPills = [
+      `\u{1F527} ${s.stack.primary}`,
+      `\u{1F4E6} ${s.stack.frameworks.length > 0 ? s.stack.frameworks.join(', ') : 'No framework'}`,
+      s.hasExistingAgents ? '\u{1F4C1} Existing .agent/' : '\u{1F4C1} New .agent/',
+      [s.stack.hasBackend ? '\u{1F519} Backend' : '', s.stack.hasFrontend ? '\u{1F5A5}\uFE0F Frontend' : '', s.stack.hasMobile ? '\u{1F4F1} Mobile' : '', s.stack.hasDatabase ? '\u{1F5C4}\uFE0F DB' : ''].filter(Boolean).join('\n      ')
+    ];
+
+    const totalItems = s.suggestedAgents.length + s.suggestedRules.length + s.suggestedGuards.length + s.suggestedWorkflows.length + s.suggestedSkills.length;
+
+    return `
+<h2 class="section-title">\u{1F916} Agent System (Suggested)</h2>
+
+<div class="card agent-system-card">
+  <div class="agent-stack-banner">
+    ${stackPills.map(p => `<div class="stack-pill">${p}</div>`).join('\n    ')}
+  </div>
+
+  <div class="agent-controls">
+    <button class="agent-ctrl-btn" onclick="toggleAll(true)">\u2705 Select All</button>
+    <button class="agent-ctrl-btn" onclick="toggleAll(false)">\u2B1C Select None</button>
+    <span class="agent-count-label"><span id="agentSelectedCount">${totalItems}</span> selected</span>
+  </div>
+
+  <h3 class="agent-section-subtitle">\u{1F916} Agents</h3>
+  <div class="agent-toggle-grid">
+    ${agentCards}
+  </div>
+
+  <div class="agent-extras-grid">
+    <div>
+      <h3 class="agent-section-subtitle">\u{1F4CF} Rules</h3>
+      <div class="agent-toggle-list">${ruleCards}</div>
+    </div>
+    <div>
+      <h3 class="agent-section-subtitle">\u{1F6E1}\uFE0F Guards</h3>
+      <div class="agent-toggle-list">${guardCards}</div>
+    </div>
+    <div>
+      <h3 class="agent-section-subtitle">\u26A1 Workflows</h3>
+      <div class="agent-toggle-list">${workflowCards}</div>
+    </div>
+  </div>
+
+  <h3 class="agent-section-subtitle">\u{1F9E0} Skills <span style="font-size:0.7rem;color:#94a3b8;font-weight:400">from skills.sh</span></h3>
+  <div class="agent-toggle-grid">
+    ${skillCards}
+  </div>
+
+  ${auditSection}
+
+  <div class="agent-command-box">
+    <div class="agent-command-header">
+      <span>\u{1F4A1} Command to generate selected items:</span>
+      <button class="agent-copy-btn" onclick="copyAgentCommand()">
+        <span id="copyIcon">\u{1F4CB}</span> Copy
+      </button>
+    </div>
+    <code id="agentCommandOutput" class="agent-command-code">${s.command}</code>
+  </div>
+</div>
+
+<style>
+  .agent-system-card { padding: 1.5rem; }
+  .agent-stack-banner { display: flex; gap: 0.5rem; flex-wrap: wrap; margin-bottom: 1.5rem; }
+  .stack-pill { background: #1e293b; border: 1px solid #334155; border-radius: 99px; padding: 0.4rem 1rem; font-size: 0.8rem; color: #94a3b8; white-space: pre-line; }
+  .agent-controls { display: flex; align-items: center; gap: 0.75rem; margin-bottom: 1.5rem; }
+  .agent-ctrl-btn { background: #1e293b; border: 1px solid #334155; color: #e2e8f0; padding: 0.4rem 1rem; border-radius: 8px; font-size: 0.8rem; cursor: pointer; transition: all 0.2s; }
+  .agent-ctrl-btn:hover { background: #334155; }
+  .agent-count-label { color: #94a3b8; font-size: 0.85rem; margin-left: auto; }
+  #agentSelectedCount { color: #c084fc; font-weight: 700; }
+  .agent-section-subtitle { color: #e2e8f0; font-size: 1.05rem; font-weight: 700; margin: 1.25rem 0 0.75rem; }
+  .agent-toggle-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(260px, 1fr)); gap: 0.75rem; }
+  .agent-toggle-card { cursor: pointer; transition: all 0.3s; }
+  .agent-toggle-card input { display: none; }
+  .agent-toggle-inner { display: flex; align-items: center; gap: 0.75rem; background: #1e293b; border: 2px solid #334155; border-radius: 12px; padding: 0.75rem 1rem; transition: all 0.3s; }
+  .agent-toggle-card input:checked + .agent-toggle-inner { border-color: #818cf8; background: #1e1b4b; }
+  .agent-toggle-icon { font-size: 1.3rem; flex-shrink: 0; }
+  .agent-toggle-info { flex: 1; min-width: 0; }
+  .agent-toggle-name { display: block; color: #e2e8f0; font-weight: 600; font-size: 0.85rem; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+  .agent-toggle-role { display: block; font-size: 0.7rem; margin-top: 0.15rem; }
+  .agent-toggle-check { color: #334155; font-size: 1rem; flex-shrink: 0; transition: color 0.3s; }
+  .agent-toggle-card input:checked + .agent-toggle-inner .agent-toggle-check { color: #818cf8; }
+  .agent-toggle-card.mini .agent-toggle-inner { padding: 0.5rem 0.75rem; border-radius: 8px; }
+  .agent-extras-grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 1rem; margin-top: 0.5rem; }
+  @media (max-width: 768px) { .agent-extras-grid { grid-template-columns: 1fr; } }
+  .agent-toggle-list { display: flex; flex-direction: column; gap: 0.5rem; }
+  .agent-audit-section { margin-top: 1.5rem; }
+  .agent-audit-grid { display: flex; flex-direction: column; gap: 0.5rem; }
+  .agent-audit-item { display: flex; gap: 0.75rem; align-items: flex-start; background: #1e293b; padding: 0.75rem 1rem; border-radius: 8px; }
+  .agent-audit-item.audit-missing { border-left: 3px solid #ef4444; }
+  .agent-audit-item.audit-improvement { border-left: 3px solid #fbbf24; }
+  .audit-icon { font-size: 1rem; flex-shrink: 0; margin-top: 2px; }
+  .audit-content { display: flex; flex-direction: column; gap: 0.25rem; }
+  .audit-desc { color: #e2e8f0; font-size: 0.85rem; }
+  .audit-suggestion { color: #94a3b8; font-size: 0.8rem; font-style: italic; }
+  .agent-command-box { margin-top: 1.5rem; background: #0f172a; border-radius: 12px; border: 1px solid #334155; overflow: hidden; }
+  .agent-command-header { display: flex; justify-content: space-between; align-items: center; padding: 0.75rem 1rem; background: #1e293b; font-size: 0.8rem; color: #94a3b8; }
+  .agent-copy-btn { background: #c084fc; color: #0f172a; border: none; border-radius: 6px; padding: 0.4rem 0.8rem; cursor: pointer; font-size: 0.75rem; font-weight: 600; transition: all 0.2s; }
+  .agent-copy-btn:hover { background: #a855f7; transform: scale(1.05); }
+  .agent-command-code { display: block; padding: 1rem; color: #c084fc; font-size: 0.85rem; word-break: break-all; font-family: 'Fira Code', monospace; }
+</style>
+
+<script>
+(function() {
+  var basePath = ${JSON.stringify(s.command.replace('architect agents ', ''))};
+  var totalItems = ${totalItems};
+  function updateCommand() {
+    var checks = document.querySelectorAll('.agent-check');
+    var selected = { agents: [], rules: [], guards: [], workflows: [], skills: [] };
+    var count = 0;
+    checks.forEach(function(cb) { if (cb.checked) { selected[cb.dataset.type].push(cb.dataset.item); count++; } });
+    document.getElementById('agentSelectedCount').textContent = count;
+    var cmd;
+    if (count === totalItems) { cmd = 'architect agents ' + basePath; }
+    else if (count === 0) { cmd = '# No items selected'; }
+    else {
+      var parts = ['architect agents ' + basePath];
+      if (selected.agents.length > 0) parts.push('--agents ' + selected.agents.join(','));
+      if (selected.rules.length > 0) parts.push('--rules ' + selected.rules.join(','));
+      if (selected.guards.length > 0) parts.push('--guards ' + selected.guards.join(','));
+      if (selected.workflows.length > 0) parts.push('--workflows ' + selected.workflows.join(','));
+      if (selected.skills.length > 0) parts.push('&& ' + selected.skills.map(function(sk){ return 'npx skills add ' + sk; }).join(' && '));
+      cmd = parts.join(' ');
+    }
+    document.getElementById('agentCommandOutput').textContent = cmd;
+  }
+  document.querySelectorAll('.agent-check').forEach(function(cb) { cb.addEventListener('change', updateCommand); });
+  window.toggleAll = function(state) { document.querySelectorAll('.agent-check').forEach(function(cb) { cb.checked = state; }); updateCommand(); };
+  window.copyAgentCommand = function() { var cmd = document.getElementById('agentCommandOutput').textContent; navigator.clipboard.writeText(cmd).then(function() { var btn = document.getElementById('copyIcon'); btn.textContent = '\u2705'; setTimeout(function() { btn.textContent = '\ud83d\udccb'; }, 2000); }); };
+})();
+<\/script>`;
+  }
+
   private getStyles(): string {
     return `<style>
   @import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700;800;900&display=swap');
@@ -810,12 +1210,102 @@ function animateCounter(el, target) {
   .footer a { color: #818cf8; text-decoration: none; }
   .footer a:hover { text-decoration: underline; }
 
+  /* ── Refactoring Plan ── */
+  .refactor-score { padding: 2rem; }
+  .refactor-score-pair {
+    display: flex; align-items: center; justify-content: center; gap: 1.5rem;
+    margin-bottom: 2rem; flex-wrap: wrap;
+  }
+  .rscore-box { text-align: center; }
+  .rscore-num { font-size: 3rem; font-weight: 900; line-height: 1; }
+  .rscore-label { font-size: 0.8rem; color: #94a3b8; text-transform: uppercase; letter-spacing: 1px; }
+  .rscore-improvement { font-size: 1.3rem; font-weight: 700; }
+
+  .refactor-legend { display: flex; gap: 1rem; margin-bottom: 0.5rem; }
+  .rlegend-tag { font-size: 0.75rem; padding: 0.2rem 0.6rem; border-radius: 6px; }
+  .rlegend-tag.rbefore { background: rgba(255,255,255,0.05); color: #94a3b8; }
+  .rlegend-tag.rafter { background: rgba(129,140,248,0.2); color: #818cf8; }
+
+  .refactor-metric-name { width: 100px; font-size: 0.8rem; text-transform: uppercase; color: #94a3b8; font-weight: 600; }
+  .refactor-metric-bars { flex: 1; position: relative; height: 30px; }
+  .rbar-before, .rbar-after {
+    position: absolute; left: 0; height: 14px; border-radius: 4px;
+    display: flex; align-items: center; padding-left: 6px;
+    font-size: 0.7rem; font-weight: 600;
+  }
+  .rbar-before { top: 0; }
+  .rbar-after { top: 15px; }
+  .refactor-metric-diff { width: 50px; text-align: right; font-weight: 700; font-size: 0.85rem; }
+
+  .refactor-stats-row {
+    display: flex; gap: 1rem; margin-bottom: 1rem; flex-wrap: wrap;
+  }
+  .rstat {
+    background: #1e293b; border: 1px solid #334155; border-radius: 99px;
+    padding: 0.4rem 1rem; font-size: 0.85rem; color: #94a3b8; font-weight: 500;
+  }
+
+  .priority-bar {
+    display: flex; border-radius: 12px; overflow: hidden; height: 32px; margin-bottom: 2rem;
+  }
+  .prio-seg {
+    display: flex; align-items: center; justify-content: center;
+    font-size: 0.75rem; font-weight: 600;
+  }
+  .prio-critical { background: #ef444430; color: #ef4444; }
+  .prio-high { background: #f59e0b30; color: #f59e0b; }
+  .prio-medium { background: #3b82f630; color: #60a5fa; }
+  .prio-low { background: #22c55e30; color: #22c55e; }
+
+  .refactor-roadmap { display: flex; flex-direction: column; gap: 1rem; }
+  .rstep-card {
+    background: #1e293b; border-radius: 16px; border: 1px solid #334155;
+    padding: 1.5rem; transition: border-color 0.2s;
+  }
+  .rstep-card:hover { border-color: #818cf8; }
+  .rstep-header { display: flex; gap: 1rem; margin-bottom: 1rem; }
+  .rstep-number {
+    width: 40px; height: 40px; border-radius: 50%;
+    background: linear-gradient(135deg, #818cf8, #c084fc);
+    display: flex; align-items: center; justify-content: center;
+    font-weight: 800; font-size: 1rem; color: white; flex-shrink: 0;
+  }
+  .rstep-info { flex: 1; }
+  .rstep-title-row { display: flex; align-items: center; gap: 0.5rem; flex-wrap: wrap; }
+  .rstep-title-row h3 { font-size: 1.1rem; font-weight: 700; }
+  .rstep-desc { color: #94a3b8; font-size: 0.9rem; margin-top: 0.3rem; }
+  .tier-badge {
+    background: #818cf815; color: #818cf8; border: 1px solid #818cf830;
+    padding: 0.15rem 0.5rem; border-radius: 99px; font-size: 0.65rem; font-weight: 600;
+  }
+  .rstep-details { margin-top: 0.5rem; }
+  .rstep-details summary { cursor: pointer; color: #818cf8; font-size: 0.85rem; font-weight: 500; }
+  .rstep-rationale { color: #64748b; font-size: 0.85rem; margin-top: 0.3rem; font-style: italic; }
+
+  .rstep-ops { margin-top: 1rem; padding-top: 1rem; border-top: 1px solid #334155; }
+  .rstep-ops h4 { font-size: 0.85rem; color: #94a3b8; margin-bottom: 0.5rem; }
+  .rop { display: flex; align-items: flex-start; gap: 0.5rem; margin-bottom: 0.5rem; flex-wrap: wrap; }
+  .rop-icon { font-size: 0.9rem; }
+  .rop-badge { padding: 0.1rem 0.4rem; border-radius: 6px; font-size: 0.65rem; font-weight: 700; }
+  .rop-path { background: #0f172a; padding: 1px 6px; border-radius: 4px; font-size: 0.8rem; color: #c084fc; }
+  .rop-arrow { color: #818cf8; font-weight: 700; }
+  .rop-desc { width: 100%; color: #64748b; font-size: 0.8rem; padding-left: 1.8rem; }
+
+  .rstep-impact { margin-top: 0.5rem; }
+  .rstep-impact h4 { font-size: 0.85rem; color: #94a3b8; margin-bottom: 0.3rem; }
+  .rimpact-tags { display: flex; gap: 0.5rem; flex-wrap: wrap; }
+  .rimpact-tag {
+    background: #22c55e10; color: #22c55e; border: 1px solid #22c55e30;
+    padding: 0.2rem 0.6rem; border-radius: 8px; font-size: 0.75rem; font-weight: 500;
+  }
+
   /* ── Responsive ── */
   @media (max-width: 768px) {
     .score-hero { flex-direction: column; gap: 1.5rem; }
     .score-breakdown { grid-template-columns: 1fr; }
     .header h1 { font-size: 1.8rem; }
     .container { padding: 1rem; }
+    .refactor-score-pair { flex-direction: column; }
   }
 
   /* ── Print ── */

package/src/index.ts

@@ -5,12 +5,15 @@ import { ArchitectureScorer } from './scorer.js';
 import { DiagramGenerator } from './diagram.js';
 import { ReportGenerator } from './reporter.js';
 import { HtmlReportGenerator } from './html-reporter.js';
+import { RefactorEngine } from './refactor-engine.js';
+import { AgentGenerator, AgentSuggestion } from './agent-generator.js';
 import { ConfigLoader } from './config.js';
-import { AnalysisReport } from './types.js';
+import { AnalysisReport, RefactoringPlan } from './types.js';
 import { relative } from 'path';
 
 export interface ArchitectCommand {
   analyze: (path: string) => Promise<AnalysisReport>;
+  refactor: (report: AnalysisReport, projectPath: string) => RefactoringPlan;
   diagram: (path: string) => Promise<string>;
   score: (path: string) => Promise<{ overall: number; breakdown: Record<string, number> }>;
   antiPatterns: (path: string) => Promise<Array<{ name: string; severity: string; description: string }>>;
@@ -82,6 +85,40 @@ class Architect implements ArchitectCommand {
     return this.relativizePaths(report, projectPath);
   }
 
+  /**
+   * Generate a refactoring plan from an analysis report.
+   * Uses Tier 1 (rule engine) and Tier 2 (AST) transforms.
+   */
+  refactor(report: AnalysisReport, projectPath: string): RefactoringPlan {
+    const engine = new RefactorEngine();
+    return engine.analyze(report, projectPath);
+  }
+
+  /**
+   * Generate or audit .agent/ directory for a project.
+   */
+  agents(
+    report: AnalysisReport,
+    plan: RefactoringPlan,
+    projectPath: string,
+    outputDir?: string
+  ): { generated: string[]; audit: Array<{ type: string; category: string; file: string; description: string; suggestion?: string }> } {
+    const generator = new AgentGenerator();
+    return generator.generate(report, plan, projectPath, outputDir);
+  }
+
+  /**
+   * Suggest agents without writing files — dry-run for unified report.
+   */
+  suggestAgents(
+    report: AnalysisReport,
+    plan: RefactoringPlan,
+    projectPath: string,
+  ): AgentSuggestion {
+    const generator = new AgentGenerator();
+    return generator.suggest(report, plan, projectPath);
+  }
+
   private relativizePaths(report: AnalysisReport, basePath: string): AnalysisReport {
     const rel = (p: string): string => {
       if (p.startsWith('/') || p.startsWith('\\')) {
@@ -268,6 +305,7 @@ export {
   DiagramGenerator,
   ReportGenerator,
   HtmlReportGenerator,
+  AgentGenerator,
   ConfigLoader,
 };