@girardelli/architect-agents 8.1.0

package/src/core/agent-generator/types/agent.ts

@@ -0,0 +1,65 @@
+import { StackInfo } from './stack.js';
+
+export interface AgentAuditFinding {
+  type: 'MISSING' | 'OUTDATED' | 'IMPROVEMENT' | 'OK';
+  category: string;
+  file: string;
+  description: string;
+  suggestion?: string;
+}
+
+export type AgentItemStatus = 'KEEP' | 'MODIFY' | 'CREATE' | 'DELETE';
+
+export interface AgentItem {
+  name: string;
+  status: AgentItemStatus;
+  reason?: string;
+  description?: string;
+}
+
+export interface AgentSuggestion {
+  stack: StackInfo;
+  hasExistingAgents: boolean;
+  suggestedAgents: AgentItem[];
+  suggestedRules: AgentItem[];
+  suggestedGuards: AgentItem[];
+  suggestedWorkflows: AgentItem[];
+  suggestedSkills: { name: string; source: string; description: string; status: AgentItemStatus }[];
+  audit: AgentAuditFinding[];
+  command: string;
+}
+
+export interface AgentGeneratorConfig {
+  coverageMinimum: number;
+  scoreThreshold: number;
+  language: 'pt-BR' | 'en';
+  goldenRules: string[];
+  blockers: string[];
+}
+
+export const DEFAULT_AGENT_CONFIG: AgentGeneratorConfig = {
+  coverageMinimum: 80,
+  scoreThreshold: 70,
+  language: 'pt-BR',
+  goldenRules: [
+    'Git Flow completo (branch → PR → review → merge)',
+    'Arquitetura C4 (4 níveis de documentação)',
+    'BDD antes de código',
+    'TDD — Red → Green → Refactor',
+    'Diagnóstico obrigatório antes de codar',
+    'Mockup antes de qualquer UI',
+    'Nunca decidir sozinho — perguntar ao humano',
+    'Qualidade > Velocidade',
+    'Não abrir browser, não tirar screenshot — apenas código',
+  ],
+  blockers: [
+    'console.log / print() em código de produção',
+    'TODO / FIXME / HACK sem issue vinculada',
+    'any (TypeScript) / type: ignore (Python) sem justificativa',
+    'Testes com .skip() ou @pytest.mark.skip sem motivo',
+    'Secrets, tokens ou senhas hardcoded',
+    'Push direto em main/develop',
+    'Arquivos > 500 linhas sem justificativa',
+    'Imports circulares',
+  ],
+};

package/src/core/agent-generator/types/domain.ts

@@ -0,0 +1,63 @@
+/**
+ * Detailed module information extracted from project analysis.
+ */
+export interface ModuleDetail {
+  name: string;
+  path: string;
+  files: string[];
+  fileCount: number;
+  lineCount: number;
+  description: string;
+  hasTests: boolean;
+  testFiles: string[];
+  entities: string[];
+  controllers: string[];
+  services: string[];
+  layer: string;
+}
+
+/**
+ * API endpoint detected from route/controller files.
+ */
+export interface DetectedEndpoint {
+  method: string;
+  path: string;
+  file: string;
+  handler: string;
+  hasAuth: boolean;
+  hasValidation: boolean;
+}
+
+export interface BusinessEntity {
+  name: string;
+  source: string;
+  fields: string[];
+  relationships: string[];
+  layer: 'model' | 'entity' | 'schema' | 'dto' | 'unknown';
+}
+
+export interface ComplianceRequirement {
+  name: string;
+  reason: string;
+  mandatoryChecks: string[];
+}
+
+export interface ExternalIntegration {
+  name: string;
+  type: 'api' | 'database' | 'queue' | 'storage' | 'payment' | 'auth' | 'government' | 'other';
+  detectedFrom: string;
+}
+
+/**
+ * Domain classification inferred from project analysis.
+ */
+export interface DomainInsights {
+  domain: string;
+  subDomain: string;
+  description: string;
+  businessEntities: BusinessEntity[];
+  compliance: ComplianceRequirement[];
+  integrations: ExternalIntegration[];
+  keywords: string[];
+  confidence: number;
+}

package/src/core/agent-generator/types/stack.ts

@@ -0,0 +1,38 @@
+/**
+ * Stack detection result from project analysis.
+ */
+export interface StackInfo {
+  primary: string;
+  languages: string[];
+  frameworks: string[];
+  hasBackend: boolean;
+  hasFrontend: boolean;
+  hasMobile: boolean;
+  hasDatabase: boolean;
+  testFramework: string;
+  packageManager: string;
+}
+
+/**
+ * Detected framework with version, detected from dependency files.
+ */
+export interface FrameworkInfo {
+  name: string;
+  version: string | null;
+  category: 'web' | 'orm' | 'test' | 'lint' | 'build' | 'other';
+  confidence: number;
+}
+
+/**
+ * Detected toolchain — build, test, lint, run commands.
+ */
+export interface DetectedToolchain {
+  buildCmd: string;
+  testCmd: string;
+  lintCmd: string;
+  runCmd: string;
+  coverageCmd: string;
+  installCmd: string;
+  migrateCmd: string | null;
+  depsFile: string;
+}

package/src/core/agent-generator/types/template.ts

@@ -0,0 +1,31 @@
+import { AnalysisReport } from '@girardelli/architect-core/src/core/types/core.js';
+import { RefactoringPlan } from '@girardelli/architect-core/src/core/types/rules.js';
+import { StackInfo, FrameworkInfo, DetectedToolchain } from './stack.js';
+import { DomainInsights, ModuleDetail, DetectedEndpoint } from './domain.js';
+import { AgentGeneratorConfig } from './agent.js';
+
+export interface TemplateContext {
+  report: AnalysisReport;
+  plan: RefactoringPlan;
+  stack: StackInfo;
+  projectName: string;
+  stackLabel: string;
+  config: AgentGeneratorConfig;
+}
+
+export interface EnrichedTemplateContext extends TemplateContext {
+  domain: DomainInsights;
+  modules: ModuleDetail[];
+  endpoints: DetectedEndpoint[];
+  untestedModules: string[];
+  criticalPaths: string[]; // files with highest coupling
+  projectDepth: 'small' | 'medium' | 'large' | 'enterprise'; // drives template verbosity
+  /** Detected frameworks with versions */
+  detectedFrameworks: FrameworkInfo[];
+  /** Primary web framework (e.g., 'FastAPI', 'NestJS', 'Django') */
+  primaryFramework: FrameworkInfo | null;
+  /** Detected toolchain commands */
+  toolchain: DetectedToolchain;
+  /** Real project structure pattern detected */
+  projectStructure: 'clean-architecture' | 'mvc' | 'modular' | 'flat' | 'monorepo' | 'unknown';
+}

package/src/core/agent-runtime/ai-provider.ts

@@ -0,0 +1,178 @@
+/**
+ * AI Provider Factory
+ * Zero-dependency, lightweight adapter for multiple LLM endpoints.
+ */
+
+export interface AIProvider {
+  /**
+   * Translates an explicit AI prompt along with the existing file content
+   * into a newly unified source code string.
+   */
+  executeRefactoringPrompt(fileContent: string, prompt: string): Promise<string>;
+}
+
+export class OpenAIProvider implements AIProvider {
+  private apiKey: string;
+  private model: string;
+  private apiUrl: string;
+
+  constructor(apiKey: string, model: string = 'gpt-4o', apiUrl = 'https://api.openai.com/v1/chat/completions') {
+    this.apiKey = apiKey;
+    this.model = model;
+    this.apiUrl = apiUrl;
+  }
+
+  async executeRefactoringPrompt(fileContent: string, prompt: string): Promise<string> {
+    const systemPrompt = `You are a strict, top-tier Software Architect AI modifying code.
+Return ONLY the fully rewritten source code. Never use markdown code blocks (\`\`\`).
+Do NOT include explanations or prefix/suffix text. Your complete response must be purely the new raw code content.`;
+
+    const userMessage = `${prompt}\n\nCurrent file content:\n\n${fileContent}`;
+
+    const response = await fetch(this.apiUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${this.apiKey}`,
+      },
+      body: JSON.stringify({
+        model: this.model,
+        messages: [
+          { role: 'system', content: systemPrompt },
+          { role: 'user', content: userMessage },
+        ],
+        temperature: 0.1,
+      }),
+    });
+
+    if (!response.ok) {
+      const err = await response.text();
+      throw new Error(`OpenAI API Error (${response.status}): ${err}`);
+    }
+
+    const data: any = await response.json();
+    let newCode = data.choices[0].message.content.trim();
+    
+    // Safety check just in case LLM injected markdown blocks
+    if (newCode.startsWith('```') && newCode.endsWith('```')) {
+      const lines = newCode.split('\n');
+      lines.shift(); // Remove first line (```language)
+      lines.pop(); // Remove last line (```)
+      newCode = lines.join('\n');
+    }
+    
+    return newCode;
+  }
+}
+
+export class AnthropicProvider implements AIProvider {
+  private apiKey: string;
+  private model: string;
+
+  constructor(apiKey: string, model: string = 'claude-3-7-sonnet-20250219') {
+    this.apiKey = apiKey;
+    this.model = model;
+  }
+
+  async executeRefactoringPrompt(fileContent: string, prompt: string): Promise<string> {
+    const systemPrompt = `You are a strict Software Architect AI modifying code. Return ONLY the fully rewritten source code. Never use markdown code blocks (\`\`\`). Do NOT include any conversational text.`;
+    const userMessage = `${prompt}\n\n<current_file>\n${fileContent}\n</current_file>`;
+
+    const response = await fetch('https://api.anthropic.com/v1/messages', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-api-key': this.apiKey,
+        'anthropic-version': '2023-06-01',
+      },
+      body: JSON.stringify({
+        model: this.model,
+        system: systemPrompt,
+        messages: [{ role: 'user', content: userMessage }],
+        max_tokens: 8192,
+        temperature: 0.1,
+      }),
+    });
+
+    if (!response.ok) {
+      const err = await response.text();
+      throw new Error(`Anthropic API Error (${response.status}): ${err}`);
+    }
+
+    const data: any = await response.json();
+    let newCode = data.content[0].text.trim();
+    if (newCode.startsWith('```') && newCode.endsWith('```')) {
+      const lines = newCode.split('\n');
+      lines.shift(); lines.pop();
+      newCode = lines.join('\n');
+    }
+    return newCode;
+  }
+}
+
+export class GeminiProvider implements AIProvider {
+  private apiKey: string;
+  private model: string;
+
+  constructor(apiKey: string, model: string = 'gemini-2.5-flash') {
+    this.apiKey = apiKey;
+    this.model = model;
+  }
+
+  async executeRefactoringPrompt(fileContent: string, prompt: string): Promise<string> {
+    const url = `https://generativelanguage.googleapis.com/v1beta/models/${this.model}:generateContent?key=${this.apiKey}`;
+    
+    const systemPrompt = 'You are a strict Software Architect AI modifying code. Return ONLY the fully rewritten source code without markdown formatting or conversational filler.';
+    
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        systemInstruction: { parts: [{ text: systemPrompt }] },
+        contents: [
+          { role: 'user', parts: [{ text: `${prompt}\n\nFile Content:\n\n${fileContent}` }] }
+        ],
+        generationConfig: { temperature: 0.1 }
+      }),
+    });
+
+    if (!response.ok) {
+      const err = await response.text();
+      throw new Error(`Gemini API Error (${response.status}): ${err}`);
+    }
+
+    const data: any = await response.json();
+    const candidate = data.candidates?.[0]?.content?.parts?.[0]?.text || '';
+    let newCode = candidate.trim();
+    
+    if (newCode.startsWith('```') && newCode.endsWith('```')) {
+      const lines = newCode.split('\n');
+      lines.shift(); lines.pop();
+      newCode = lines.join('\n');
+    }
+    return newCode;
+  }
+}
+
+export class ModelProviderFactory {
+  static createProvider(): AIProvider {
+    if (process.env.ANTHROPIC_API_KEY) {
+      return new AnthropicProvider(process.env.ANTHROPIC_API_KEY);
+    }
+    
+    if (process.env.OPENAI_API_KEY) {
+      // Allow overriding API URL for OpenAI compatibles (e.g. DeepSeek, Groq, local LMStudio)
+      const model = process.env.OPENAI_MODEL_NAME || 'gpt-4o';
+      const apiUrl = process.env.OPENAI_BASE_URL 
+        ? `${process.env.OPENAI_BASE_URL.replace(/\/$/, '')}/chat/completions`
+        : undefined;
+      return new OpenAIProvider(process.env.OPENAI_API_KEY, model, apiUrl);
+    }
+
+    if (process.env.GEMINI_API_KEY) {
+      return new GeminiProvider(process.env.GEMINI_API_KEY);
+    }
+    
+    throw new Error('No AI API Key found in environment variables. Define OPENAI_API_KEY, ANTHROPIC_API_KEY, or GEMINI_API_KEY to execute AI-based refactoring.');
+  }
+}

package/src/core/agent-runtime/executor.ts

@@ -0,0 +1,148 @@
+import { writeFileSync, mkdirSync, readFileSync, renameSync, unlinkSync, existsSync } from 'fs';
+import { dirname } from 'path';
+import { execSync } from 'child_process';
+import { RefactoringPlan, RefactorStep, FileOperation } from '@girardelli/architect-core/src/core/types/rules.js';
+import { HumanGate } from './human-gate.js';
+import { ModelProviderFactory } from './ai-provider.js';
+
+export class AgentExecutor {
+  private gate: HumanGate;
+    // @ts-ignore - Audit cleanup unused variable
+  private autoMode: boolean;
+
+  constructor(autoMode: boolean = false) {
+    this.autoMode = autoMode;
+    this.gate = new HumanGate(autoMode);
+  }
+
+  /**
+   * Main entrypoint for Agent Runtime.
+   */
+  async executePlan(plan: RefactoringPlan) {
+    console.log(`\n\x1b[35m=== 🤖 Architect Autonomous Agent ===\x1b[0m`);
+    console.log(`Loaded Refactoring Plan: ${plan.steps.length} procedural steps.\n`);
+
+    // 1. Mandatory Git Flow Branching
+    this.ensureProtectiveBranch();
+
+    // 2. Load AI Provider if needed
+    const needsAI = plan.steps.some((s) => !!s.aiPrompt);
+    let aiProvider = null;
+    if (needsAI) {
+      try {
+        aiProvider = ModelProviderFactory.createProvider();
+        console.log(`\x1b[32m[AI Engine Ready]\x1b[0m Linked to external LLM provider.\n`);
+      } catch (e: any) {
+        console.warn(`\x1b[33m[AI Warning]\x1b[0m Could not connect AI Provider (` + e.message + `). Steps requiring AI will be skipped.\n`);
+      }
+    }
+
+    // 3. Execution Loop
+    for (const step of plan.steps) {
+      const approved = await this.gate.requestApproval(step);
+      
+      if (!approved) {
+        console.log(`\x1b[90mSkipping step #${step.id}...\x1b[0m\n`);
+        continue;
+      }
+
+      console.log(`\n\x1b[36mExecuting Step #${step.id}...\x1b[0m`);
+      let successCount = 0;
+
+      for (const op of step.operations) {
+        try {
+          await this.executeOperation(op, step.aiPrompt, aiProvider);
+          successCount++;
+        } catch (e: any) {
+          console.error(`\x1b[31mFailed to execute operation on ${op.path}:\x1b[0m ${e.message}`);
+        }
+      }
+
+      // 4. Atomic Commit per Step
+      if (successCount > 0) {
+        this.commitStep(step);
+      }
+    }
+
+    this.gate.close();
+    console.log(`\n\x1b[32m=== ✅ Autonomous Execution Complete ===\x1b[0m`);
+    console.log(`Changes are safed in the current feature branch. Review, test, and push to remote!`);
+  }
+
+  private async executeOperation(op: FileOperation, aiPrompt?: string, aiProvider?: any) {
+    const targetPath = op.path;
+
+    if (op.type === 'CREATE') {
+      if (op.content) {
+        mkdirSync(dirname(targetPath), { recursive: true });
+        writeFileSync(targetPath, op.content, 'utf8');
+        console.log(`  \x1b[32m✔ Created:\x1b[0m ${targetPath}`);
+      }
+    } 
+    else if (op.type === 'MOVE' && op.newPath) {
+      if (existsSync(targetPath)) {
+        mkdirSync(dirname(op.newPath), { recursive: true });
+        renameSync(targetPath, op.newPath);
+        console.log(`  \x1b[34m✔ Moved:\x1b[0m ${targetPath} -> ${op.newPath}`);
+      }
+    }
+    else if (op.type === 'DELETE') {
+      if (existsSync(targetPath)) {
+        unlinkSync(targetPath);
+        console.log(`  \x1b[31m✔ Deleted:\x1b[0m ${targetPath}`);
+      }
+    }
+    else if (op.type === 'MODIFY') {
+      if (!existsSync(targetPath)) {
+        throw new Error(`Target file ${targetPath} does not exist`);
+      }
+
+      const currentContent = readFileSync(targetPath, 'utf8');
+
+      if (aiPrompt) {
+        if (!aiProvider) throw new Error('AI Provider not configured, cannot execute prompt');
+        console.log(`  \x1b[35m✨ AI Generating structure for ${targetPath}...\x1b[0m`);
+        
+        const newContent = await aiProvider.executeRefactoringPrompt(currentContent, aiPrompt);
+        writeFileSync(targetPath, newContent, 'utf8');
+        console.log(`  \x1b[33m✔ AI Re-wrote:\x1b[0m ${targetPath}`);
+      } else if (op.content) {
+        // Fallback or exact replacement
+        writeFileSync(targetPath, op.content, 'utf8');
+        console.log(`  \x1b[33m✔ Modified:\x1b[0m ${targetPath}`);
+      }
+    }
+  }
+
+  private ensureProtectiveBranch() {
+    if (process.env.NODE_ENV === 'test') return;
+    try {
+      const currentBranch = execSync('git rev-parse --abbrev-ref HEAD').toString().trim();
+      const needsNewBranch = ['main', 'master', 'develop'].includes(currentBranch);
+
+      if (needsNewBranch) {
+        const ts = new Date().getTime();
+        const branchName = `feature/architect-refactor-${ts}`;
+        console.log(`\x1b[36m[Git Flow]\x1b[0m Currently on '${currentBranch}'. Creating protective branch \x1b[33m${branchName}\x1b[0m...`);
+        execSync(`git checkout -b ${branchName}`);
+      } else {
+        console.log(`\x1b[32m[Git Flow]\x1b[0m Continuing firmly on non-base branch '${currentBranch}'.`);
+      }
+    } catch (e) {
+      console.warn(`\x1b[33m[Warning]\x1b[0m Git repository not detected or git command failed. Proceeding without branch protection.`);
+    }
+  }
+
+  private commitStep(step: RefactorStep) {
+    if (process.env.NODE_ENV === 'test') return;
+    try {
+      execSync('git add .');
+      const msg = `refactor(architect): apply rule ${step.rule}\n\nAuto-applied by Architect Agent.\nMotivation: ${step.title}`;
+      execSync(`git commit -m "${msg}"`);
+      console.log(`  \x1b[32m✔ Git Commit Saved: ${step.rule}\x1b[0m\n`);
+    } catch (e) {
+      // Might happen if there were no actual changes (e.g. content was identical)
+      console.log(`  \x1b[90m(No git changes detected for this step)\x1b[0m\n`);
+    }
+  }
+}

package/src/core/agent-runtime/human-gate.ts

@@ -0,0 +1,69 @@
+import * as readline from 'readline/promises';
+import { stdin as input, stdout as output } from 'process';
+import { RefactorStep, FileOperation } from '@girardelli/architect-core/src/core/types/rules.js';
+import { logger } from '@girardelli/architect-core/src/infrastructure/logger.js';
+
+export class HumanGate {
+  private rl: readline.Interface | null = null;
+  private autoMode: boolean;
+
+  constructor(autoMode: boolean = false) {
+    this.autoMode = autoMode;
+  }
+
+  /**
+   * Request manual approval before applying a refactoring step.
+   * If autoMode is true, it always auto-approves.
+   */
+  async requestApproval(step: RefactorStep): Promise<boolean> {
+    logger.info(`\n\x1b[36m[Architect Agent]\x1b[0m Evaluating Refactor Step \x1b[33m#${step.id}: ${step.title}\x1b[0m`);
+    logger.info(`\x1b[90mRationale: ${step.rationale}\x1b[0m\n`);
+    
+    for (const op of step.operations) {
+      this.printOperation(op, !!step.aiPrompt);
+    }
+    
+    if (this.autoMode) {
+      logger.info(`\n\x1b[32m[Auto-Mode Enabled]\x1b[0m Automatically applying changes...`);
+      return true;
+    }
+
+    if (!this.rl) {
+      this.rl = readline.createInterface({ input, output });
+    }
+
+    const answer = await this.rl.question(`\n⚠️  Do you approve executing these structural changes? [y/N]: `);
+    return answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes';
+  }
+
+  /**
+   * Prints the planned operation visually
+   */
+  private printOperation(op: FileOperation, hasAiPrompt: boolean) {
+    let color = '';
+    let label = '';
+    
+    switch(op.type) {
+      case 'CREATE': color = '\x1b[32m'; label = '✚ CREATE'; break; // Green
+      case 'MODIFY': color = '\x1b[33m'; label = '✎ MODIFY'; break; // Yellow
+      case 'DELETE': color = '\x1b[31m'; label = '✖ DELETE'; break; // Red
+      case 'MOVE':   color = '\x1b[34m'; label = '➡ MOVE  '; break; // Blue
+    }
+    
+    logger.info(`  ${color}${label}\x1b[0m ${op.path}`);
+    if (op.newPath) {
+      logger.info(`    \x1b[90m↳ Target: ${op.newPath}\x1b[0m`);
+    }
+    logger.info(`    \x1b[90mDetails: ${op.description}\x1b[0m`);
+    if (hasAiPrompt && op.type === 'MODIFY') {
+      logger.info(`    \x1b[35m✨ AI Operation:\x1b[0m Requires LLM Execution.`);
+    }
+  }
+
+  close() {
+    if (this.rl) {
+      this.rl.close();
+      this.rl = null;
+    }
+  }
+}