@agile-vibe-coding/avc 0.1.0 → 0.2.3

package/cli/kanban-server-manager.js

@@ -0,0 +1,228 @@
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import path from 'path';
+import fs from 'fs';
+import net from 'net';
+import http from 'http';
+
+const execAsync = promisify(exec);
+
+/**
+ * Kanban Server Manager
+ * Manages lifecycle of the AVC Kanban Board server
+ */
+export class KanbanServerManager {
+  constructor(projectRoot = process.cwd()) {
+    this.projectRoot = projectRoot;
+    this.avcDir = path.join(projectRoot, '.avc');
+    this.avcProjectPath = path.join(this.avcDir, 'project');
+  }
+
+  /**
+   * Check if .avc/project directory exists
+   */
+  hasWorkItems() {
+    return fs.existsSync(this.avcProjectPath);
+  }
+
+  /**
+   * Get kanban server port from avc.json config
+   * Returns default port 4174 if not configured
+   */
+  getPort() {
+    const configPath = path.join(this.avcDir, 'avc.json');
+
+    if (!fs.existsSync(configPath)) {
+      return 4174; // Default port
+    }
+
+    try {
+      const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      return config.settings?.kanban?.port || 4174;
+    } catch (error) {
+      console.warn(`Could not read port from avc.json: ${error.message}`);
+      return 4174;
+    }
+  }
+
+  /**
+   * Check if a port is in use
+   * @param {number} port - Port number to check
+   * @returns {Promise<boolean>} - True if port is in use
+   */
+  async isPortInUse(port) {
+    return new Promise((resolve) => {
+      const server = net.createServer();
+
+      server.once('error', (err) => {
+        if (err.code === 'EADDRINUSE') {
+          resolve(true); // Port is in use
+        } else {
+          resolve(false);
+        }
+      });
+
+      server.once('listening', () => {
+        server.close();
+        resolve(false); // Port is available
+      });
+
+      server.listen(port, '127.0.0.1');
+    });
+  }
+
+  /**
+   * Check if the server on this port is the AVC Kanban Board
+   * Makes HTTP request to /api/health and checks for AVC kanban response
+   * @param {number} port - Port number to check
+   * @returns {Promise<boolean>} - True if it's confirmed to be AVC kanban server
+   */
+  async isKanbanServer(port) {
+    return new Promise((resolve) => {
+      const req = http.get(`http://localhost:${port}/api/health`, {
+        timeout: 2000,
+      }, (res) => {
+        let data = '';
+
+        res.on('data', (chunk) => {
+          data += chunk;
+        });
+
+        res.on('end', () => {
+          try {
+            const json = JSON.parse(data);
+            // Check if it's our AVC kanban server
+            const isKanban = json.projectRoot === this.projectRoot;
+            resolve(isKanban);
+          } catch {
+            resolve(false);
+          }
+        });
+      });
+
+      req.on('error', () => {
+        resolve(false); // Can't connect or verify
+      });
+
+      req.on('timeout', () => {
+        req.destroy();
+        resolve(false);
+      });
+    });
+  }
+
+  /**
+   * Find which process is using a port
+   * Works cross-platform (Linux, macOS, Windows)
+   * @param {number} port - Port number to check
+   * @returns {Promise<{pid: number, command: string} | null>} - Process info or null if not found
+   */
+  async findProcessUsingPort(port) {
+    try {
+      let command;
+      let parseOutput;
+
+      if (process.platform === 'win32') {
+        // Windows: netstat -ano | findstr :PORT
+        command = `netstat -ano | findstr :${port}`;
+        parseOutput = (output) => {
+          const lines = output.split('\n');
+          for (const line of lines) {
+            if (
+              line.includes(`0.0.0.0:${port}`) ||
+              line.includes(`127.0.0.1:${port}`) ||
+              line.includes(`[::]:${port}`)
+            ) {
+              const parts = line.trim().split(/\s+/);
+              const pid = parseInt(parts[parts.length - 1]);
+              if (pid && !isNaN(pid)) {
+                return { pid, command: 'Unknown' };
+              }
+            }
+          }
+          return null;
+        };
+      } else {
+        // Linux/macOS: lsof -i :PORT
+        command = `lsof -i :${port} -t -sTCP:LISTEN`;
+        parseOutput = (output) => {
+          const pid = parseInt(output.trim());
+          if (pid && !isNaN(pid)) {
+            // Try to get process name
+            try {
+              const { execSync } = require('child_process');
+              const psOutput = execSync(`ps -p ${pid} -o comm=`, { encoding: 'utf8' });
+              return { pid, command: psOutput.trim() };
+            } catch {
+              return { pid, command: 'Unknown' };
+            }
+          }
+          return null;
+        };
+      }
+
+      const { stdout } = await execAsync(command);
+      return parseOutput(stdout);
+    } catch (error) {
+      // Command failed (no process found) or permission error
+      return null;
+    }
+  }
+
+  /**
+   * Kill a process by PID
+   * @param {number} pid - Process ID to kill
+   * @returns {Promise<boolean>} - True if kill succeeded
+   */
+  async killProcess(pid) {
+    try {
+      if (process.platform === 'win32') {
+        await execAsync(`taskkill /F /PID ${pid}`);
+      } else {
+        await execAsync(`kill -9 ${pid}`);
+      }
+      return true;
+    } catch (error) {
+      console.error(`Failed to kill process ${pid}:`, error.message);
+      return false;
+    }
+  }
+
+  /**
+   * Get the frontend dev server URL (Vite)
+   * @returns {string} Frontend URL
+   */
+  getFrontendUrl() {
+    const config = this.getConfig();
+    const frontendPort = config.settings?.kanban?.frontendPort || 5173;
+    return `http://localhost:${frontendPort}`;
+  }
+
+  /**
+   * Get the backend API server URL
+   * @returns {string} Backend URL
+   */
+  getBackendUrl() {
+    const port = this.getPort();
+    return `http://localhost:${port}`;
+  }
+
+  /**
+   * Get AVC configuration
+   * @returns {object} Configuration object
+   */
+  getConfig() {
+    const configPath = path.join(this.avcDir, 'avc.json');
+
+    if (!fs.existsSync(configPath)) {
+      return { settings: {} };
+    }
+
+    try {
+      return JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    } catch (error) {
+      console.warn(`Could not read avc.json: ${error.message}`);
+      return { settings: {} };
+    }
+  }
+}

package/cli/llm-claude.js

@@ -0,0 +1,109 @@
+import Anthropic from '@anthropic-ai/sdk';
+import { jsonrepair } from 'jsonrepair';
+import { LLMProvider } from './llm-provider.js';
+import { getMaxTokensForModel } from './llm-token-limits.js';
+
+export class ClaudeProvider extends LLMProvider {
+  constructor(model) { super('claude', model); }
+
+  _createClient() {
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) throw new Error('ANTHROPIC_API_KEY not set. Add it to your .env file.');
+    // 5-minute timeout per request; SDK retries disabled so our retryWithBackoff
+    // handles all retries with full logging visibility.
+    return new Anthropic({ apiKey, timeout: 5 * 60 * 1000, maxRetries: 0 });
+  }
+
+  async _callProvider(prompt, maxTokens, systemInstructions) {
+    const params = {
+      model: this.model,
+      max_tokens: maxTokens,
+      messages: [{ role: 'user', content: prompt }]
+    };
+
+    if (systemInstructions) {
+      params.system = systemInstructions;
+    }
+
+    const response = await this._client.messages.create(params);
+    this._trackTokens(response.usage);
+    return response.content[0].text;
+  }
+
+  async generateJSON(prompt, agentInstructions = null) {
+    if (!this._client) {
+      this._client = this._createClient();
+    }
+
+    const fullPrompt = agentInstructions ? `${agentInstructions}\n\n${prompt}` : prompt;
+
+    // Use model-specific maximum tokens
+    const maxTokens = getMaxTokensForModel(this.model);
+
+    const response = await this._withRetry(
+      () => this._client.messages.create({
+        model: this.model,
+        max_tokens: maxTokens,
+        messages: [{
+          role: 'user',
+          content: fullPrompt
+        }],
+        system: 'You are a helpful assistant that always returns valid JSON. Your response must be a valid JSON object or array, nothing else.'
+      }),
+      'JSON generation (Claude)'
+    );
+
+    this._trackTokens(response.usage);
+    const content = response.content[0].text;
+
+    // Extract JSON from response (handle markdown code blocks)
+    // Strip markdown code fences if present (more robust)
+    let jsonStr = content.trim();
+    if (jsonStr.startsWith('```')) {
+      // Remove opening fence (```json or ```)
+      jsonStr = jsonStr.replace(/^```(?:json)?\s*\n?/, '');
+      // Remove closing fence
+      jsonStr = jsonStr.replace(/\n?\s*```\s*$/, '');
+      jsonStr = jsonStr.trim();
+    }
+
+    try {
+      return JSON.parse(jsonStr);
+    } catch (firstError) {
+      // Only attempt repair when the content looks like JSON (starts with { or [)
+      // — avoids silently accepting completely non-JSON responses
+      if (jsonStr.startsWith('{') || jsonStr.startsWith('[')) {
+        try {
+          return JSON.parse(jsonrepair(jsonStr));
+        } catch { /* fall through to throw */ }
+      }
+      throw new Error(`Failed to parse JSON response: ${firstError.message}\n\nResponse was:\n${content}`);
+    }
+  }
+
+  async generateText(prompt, agentInstructions = null) {
+    if (!this._client) {
+      this._client = this._createClient();
+    }
+
+    const fullPrompt = agentInstructions ? `${agentInstructions}\n\n${prompt}` : prompt;
+
+    // Use model-specific maximum tokens
+    const maxTokens = getMaxTokensForModel(this.model);
+
+    const response = await this._withRetry(
+      () => this._client.messages.create({
+        model: this.model,
+        max_tokens: maxTokens,
+        messages: [{
+          role: 'user',
+          content: fullPrompt
+        }]
+      }),
+      'Text generation (Claude)'
+    );
+
+    this._trackTokens(response.usage);
+    return response.content[0].text;
+  }
+}

package/cli/llm-gemini.js

@@ -0,0 +1,115 @@
+import { GoogleGenAI } from '@google/genai';
+import { jsonrepair } from 'jsonrepair';
+import { LLMProvider } from './llm-provider.js';
+import { getMaxTokensForModel } from './llm-token-limits.js';
+
+export class GeminiProvider extends LLMProvider {
+  constructor(model = 'gemini-2.5-flash') { super('gemini', model); }
+
+  _createClient() {
+    const apiKey = process.env.GEMINI_API_KEY;
+    if (!apiKey) throw new Error('GEMINI_API_KEY not set. Add it to your .env file.');
+    return new GoogleGenAI({ apiKey });
+  }
+
+  async _callProvider(prompt, maxTokens, systemInstructions) {
+    const params = {
+      model: this.model,
+      contents: prompt,
+      generationConfig: { maxOutputTokens: maxTokens }
+    };
+
+    if (systemInstructions) {
+      params.systemInstruction = systemInstructions;
+    }
+
+    const response = await this._client.models.generateContent(params);
+    if (!response.text) {
+      throw new Error('Gemini returned no text (possible safety filter block).');
+    }
+    this._trackTokens(response.usageMetadata);
+    return response.text;
+  }
+
+  async generateJSON(prompt, agentInstructions = null) {
+    if (!this._client) {
+      this._client = this._createClient();
+    }
+
+    const fullPrompt = agentInstructions ? `${agentInstructions}\n\n${prompt}` : prompt;
+
+    // Use model-specific maximum tokens
+    const maxTokens = getMaxTokensForModel(this.model);
+
+    const params = {
+      model: this.model,
+      contents: fullPrompt,
+      generationConfig: {
+        responseMimeType: 'application/json',  // Gemini's native JSON mode
+        maxOutputTokens: maxTokens
+      }
+    };
+
+    const response = await this._withRetry(
+      () => this._client.models.generateContent(params),
+      'JSON generation (Gemini)'
+    );
+    if (!response.text) {
+      throw new Error('Gemini returned no text (possible safety filter block).');
+    }
+
+    this._trackTokens(response.usageMetadata);
+    const content = response.text;
+
+    // Strip markdown code fences if present (more robust)
+    let jsonStr = content.trim();
+    if (jsonStr.startsWith('```')) {
+      // Remove opening fence (```json or ```)
+      jsonStr = jsonStr.replace(/^```(?:json)?\s*\n?/, '');
+      // Remove closing fence
+      jsonStr = jsonStr.replace(/\n?\s*```\s*$/, '');
+      jsonStr = jsonStr.trim();
+    }
+
+    try {
+      return JSON.parse(jsonStr);
+    } catch (firstError) {
+      if (jsonStr.startsWith('{') || jsonStr.startsWith('[')) {
+        try {
+          return JSON.parse(jsonrepair(jsonStr));
+        } catch { /* fall through to throw */ }
+      }
+      throw new Error(`Failed to parse JSON response: ${firstError.message}\n\nResponse was:\n${content}`);
+    }
+  }
+
+  async generateText(prompt, agentInstructions = null) {
+    if (!this._client) {
+      this._client = this._createClient();
+    }
+
+    const fullPrompt = agentInstructions ? `${agentInstructions}\n\n${prompt}` : prompt;
+
+    // Use model-specific maximum tokens
+    const maxTokens = getMaxTokensForModel(this.model);
+
+    const params = {
+      model: this.model,
+      contents: fullPrompt,
+      generationConfig: {
+        maxOutputTokens: maxTokens
+      }
+    };
+
+    const response = await this._withRetry(
+      () => this._client.models.generateContent(params),
+      'Text generation (Gemini)'
+    );
+    if (!response.text) {
+      throw new Error('Gemini returned no text (possible safety filter block).');
+    }
+
+    this._trackTokens(response.usageMetadata);
+    return response.text;
+  }
+}

package/cli/llm-mock.js

@@ -0,0 +1,233 @@
+/**
+ * MockLLMProvider — instant canned responses for E2E testing.
+ * Activated when AVC_LLM_MOCK=1 is set in the environment.
+ *
+ * Detects what kind of response to return by inspecting the prompt text.
+ */
+export class MockLLMProvider {
+  constructor() {
+    this.providerName = 'mock';
+    this.model = 'mock-model';
+    this.tokenUsage = { inputTokens: 0, outputTokens: 0, totalCalls: 0 };
+  }
+
+  async validateApiKey() {
+    return { valid: true };
+  }
+
+  getTokenUsage() {
+    return {
+      inputTokens: this.tokenUsage.inputTokens,
+      outputTokens: this.tokenUsage.outputTokens,
+      totalTokens: this.tokenUsage.inputTokens + this.tokenUsage.outputTokens,
+      totalCalls: this.tokenUsage.totalCalls,
+      estimatedCost: 0,
+      provider: 'mock',
+      model: 'mock-model'
+    };
+  }
+
+  _track(prompt = '') {
+    this.tokenUsage.inputTokens += Math.ceil(prompt.length / 4);
+    this.tokenUsage.outputTokens += 50;
+    this.tokenUsage.totalCalls++;
+  }
+
+  /** generateJSON — detect call type from agent instructions (most reliable discriminator) */
+  async generateJSON(prompt, agentInstructions = null) {
+    this._track(prompt);
+
+    const p = (prompt || '').toLowerCase();
+    // Use agent instructions filename/content as the primary discriminator — it's
+    // more reliable than prompt text which can contain overlapping keywords.
+    const agent = (agentInstructions || '').toLowerCase();
+
+    // Validation calls (validator-documentation.md / validator-context.md)
+    // validator-documentation.md contains "validationStatus" and "overallScore" as output fields
+    if (agent.includes('validationstatus') || agent.includes('overallscore') ||
+        p.includes('validate the following')) {
+      return {
+        validationStatus: 'acceptable',
+        overallScore: 90,
+        issues: [],
+        contentIssues: [],
+        structuralIssues: [],
+        applicationFlowGaps: [],
+        strengths: ['Well-structured document (mock validation)'],
+        improvementPriorities: [],
+        readyForPublication: true,
+        readyForUse: true
+      };
+    }
+
+    // Database recommendation (database-recommender.md)
+    // database-recommender.md uniquely contains "hasDatabaseNeeds" as an output field
+    if (agent.includes('hasdatabaseneeds') || p.includes('determine if it needs a database')) {
+      return {
+        hasDatabaseNeeds: true,
+        comparison: {
+          sqlOption: {
+            database: 'PostgreSQL',
+            specificVersion: 'PostgreSQL 16',
+            bestFor: 'Relational data with ACID guarantees',
+            strengths: ['Strong consistency', 'Rich query language', 'Mature ecosystem'],
+            weaknesses: ['Schema migrations required'],
+            estimatedCosts: { monthly: '$0 (local Docker)' }
+          },
+          nosqlOption: {
+            database: 'MongoDB',
+            specificVersion: 'MongoDB 7',
+            bestFor: 'Flexible document storage',
+            strengths: ['Schema flexibility', 'Easy horizontal scaling'],
+            weaknesses: ['Eventual consistency by default'],
+            estimatedCosts: { monthly: '$0 (local Docker)' }
+          },
+          keyMetrics: {
+            estimatedReadWriteRatio: '70/30',
+            expectedThroughput: 'Low-medium (< 1000 req/s)',
+            dataComplexity: 'Medium — relational entities with joins'
+          }
+        },
+        recommendation: 'sql',
+        confidence: 85,
+        reasoning: 'Mock: task management apps benefit from relational integrity'
+      };
+    }
+
+    // Architecture recommendations (architecture-recommender.md)
+    // architecture-recommender.md uniquely contains "requiresCloudProvider" as an output field
+    if (agent.includes('requirescloudprovider') || p.includes('recommend 3-5') || p.includes('deployment architectures')) {
+      return {
+        architectures: [
+          {
+            name: 'Local Hybrid Stack',
+            description: 'Express.js/FastAPI backend on localhost with PostgreSQL in Docker',
+            requiresCloudProvider: false,
+            bestFor: 'Experienced developers who want fast debugging with database isolation',
+            migrationPath: {
+              targetCloud: 'AWS ECS / Azure Container Apps / GCP Cloud Run',
+              steps: [
+                'Containerize backend with Docker',
+                'Push images to ECR/ACR/GCR',
+                'Deploy to container orchestration service'
+              ]
+            }
+          },
+          {
+            name: 'Full Docker Compose',
+            description: 'All services in Docker Compose — database, backend, and frontend',
+            requiresCloudProvider: false,
+            bestFor: 'Teams who want identical environments across all machines',
+            migrationPath: {
+              targetCloud: 'AWS ECS / GCP Cloud Run',
+              steps: ['Convert docker-compose.yml to ECS task definitions', 'Set up managed database']
+            }
+          }
+        ]
+      };
+    }
+
+    // Question prefilling (question-prefiller.md)
+    // question-prefiller.md uniquely contains "TARGET_USERS" as an output field
+    if (agent.includes('target_users') || p.includes('target_users')) {
+      return {
+        TARGET_USERS: 'Developers and project teams managing software development tasks',
+        DEPLOYMENT_TARGET: 'Local development environment using Docker Compose; ready to migrate to AWS ECS or Azure Container Apps for production',
+        TECHNICAL_CONSIDERATIONS: 'Node.js/Express.js or FastAPI backend, React 18 + Vite frontend, PostgreSQL 16 in Docker for local development with production migration path',
+        SECURITY_AND_COMPLIANCE_REQUIREMENTS: 'JWT authentication with refresh tokens, bcrypt password hashing, HTTPS in production, standard OWASP security practices'
+      };
+    }
+
+    // Context generation (project-context-generator.md)
+    // project-context-generator.md uniquely contains "contextMarkdown" as an output field
+    if (agent.includes('contextmarkdown') || agent.includes('context generator')) {
+      const mockContext = `# Project Context
+
+**Mission:** Build a test task manager app
+**Architecture:** Local Hybrid Stack
+**Database:** PostgreSQL 16
+**Tech Stack:** Node.js, Express.js, React 18, Vite
+**Deployment:** Local Docker Compose → AWS ECS
+`;
+      return {
+        contextMarkdown: mockContext,
+        tokenCount: Math.ceil(mockContext.length / 4),
+        withinBudget: true
+      };
+    }
+
+    // Generic fallback
+    return { result: 'Mock JSON response', success: true };
+  }
+
+  /** generate — return a mock sponsor-call document */
+  async generate(prompt, maxTokens = 256, systemInstructions = null) {
+    this._track(prompt);
+
+    const p = (prompt || '').toLowerCase();
+
+    // Document generation
+    if (p.includes('sponsor') || p.includes('project brief') || p.includes('enhance')) {
+      return `# Sponsor Call — Test Task Manager
+
+## Mission Statement
+Build a test task manager app to help teams manage development tasks efficiently.
+
+## Initial Scope & Key Features
+MVP with task creation and basic authentication.
+
+## Target Users
+Developers and project teams managing software development tasks.
+
+## Deployment Target
+Local development environment with Docker Compose. Ready to migrate to AWS ECS when needed.
+
+## Technical Considerations
+Node.js/Express.js backend, React 18 + Vite frontend, PostgreSQL 16 in Docker.
+
+## Security & Compliance
+JWT authentication with refresh tokens, bcrypt password hashing, HTTPS in production.
+
+## Architecture
+Local Hybrid Stack: backend on localhost, database in Docker for isolation.
+
+---
+*Generated by AVC mock provider for E2E testing*
+`;
+    }
+
+    // Improvement pass (iterative validation improve step)
+    if (p.includes('improve') || p.includes('enhancement')) {
+      return `# Sponsor Call — Test Task Manager (Improved)
+
+## Mission Statement
+Build a comprehensive test task manager app for development teams.
+
+## Initial Scope & Key Features
+MVP with task creation, assignment, and basic JWT authentication.
+
+## Target Users
+Software development teams and individual developers.
+
+## Deployment Target
+Local development with Docker Compose, production on AWS ECS.
+
+## Technical Considerations
+Express.js/Node.js backend, React 18 frontend, PostgreSQL 16 in Docker container.
+
+## Security & Compliance
+JWT + bcrypt authentication, OWASP security practices.
+
+---
+*Improved by AVC mock provider for E2E testing*
+`;
+    }
+
+    return 'Mock text response from AVC E2E mock provider.';
+  }
+
+  /** generateText — alias for generate (used by migration guide generator) */
+  async generateText(prompt, agentInstructions = null) {
+    return this.generate(prompt, 4096, agentInstructions);
+  }
+}