@agile-vibe-coding/avc 0.1.1 → 0.3.1

package/cli/kanban-server-manager.js

@@ -0,0 +1,227 @@
+import { exec, execSync } 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 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

@@ -1,5 +1,7 @@
 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); }
@@ -7,7 +9,9 @@ export class ClaudeProvider extends LLMProvider {
   _createClient() {
     const apiKey = process.env.ANTHROPIC_API_KEY;
     if (!apiKey) throw new Error('ANTHROPIC_API_KEY not set. Add it to your .env file.');
-    return new Anthropic({ apiKey });
+    // 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) {
@@ -22,6 +26,151 @@ export class ClaudeProvider extends LLMProvider {
     }
 
     const response = await this._client.messages.create(params);
+    this._trackTokens(response.usage);
     return response.content[0].text;
   }
+
+  async generateJSON(prompt, agentInstructions = null, cachedContext = null) {
+    if (!this._client) {
+      this._client = this._createClient();
+    }
+
+    // Use model-specific maximum tokens
+    const maxTokens = getMaxTokensForModel(this.model);
+
+    const JSON_SYSTEM = 'You are a helpful assistant that always returns valid JSON. Your response must be a valid JSON object or array, nothing else.';
+
+    let systemParam;
+    let userContent;
+
+    if (cachedContext) {
+      // Structured content blocks: cache_control on agentInstructions (system) and
+      // cachedContext (first user block) — both stay stable across multiple calls
+      // in the same ceremony, hitting the 5-min cache on subsequent validators.
+      systemParam = agentInstructions
+        ? [
+            { type: 'text', text: JSON_SYSTEM },
+            { type: 'text', text: agentInstructions, cache_control: { type: 'ephemeral' } },
+          ]
+        : [{ type: 'text', text: JSON_SYSTEM }];
+
+      userContent = [
+        { type: 'text', text: cachedContext, cache_control: { type: 'ephemeral' } },
+        { type: 'text', text: prompt },
+      ];
+    } else {
+      systemParam = JSON_SYSTEM;
+      userContent = agentInstructions ? `${agentInstructions}\n\n${prompt}` : prompt;
+    }
+
+    const requestParams = {
+      model: this.model,
+      max_tokens: maxTokens,
+      system: systemParam,
+      messages: [{ role: 'user', content: userContent }],
+    };
+
+    const fullPrompt = agentInstructions ? `${agentInstructions}\n\n${prompt}` : prompt;
+
+    const _t0Json = Date.now();
+    const response = await this._withRetry(
+      () => this._client.messages.create(requestParams),
+      'JSON generation (Claude)'
+    );
+
+    const content = response.content[0].text;
+    this._trackTokens(response.usage, {
+      prompt: fullPrompt,
+      agentInstructions: agentInstructions ?? null,
+      response: content,
+      elapsed: Date.now() - _t0Json,
+    });
+
+    // Extract JSON from response (handle markdown code blocks and preamble text)
+    let jsonStr = content.trim();
+
+    // Strip markdown code fences if the response starts with one
+    if (jsonStr.startsWith('```')) {
+      jsonStr = jsonStr.replace(/^```(?:json)?\s*\n?/, '');
+      jsonStr = jsonStr.replace(/\n?\s*```\s*$/, '');
+      jsonStr = jsonStr.trim();
+    }
+
+    // If model added reasoning preamble before JSON, find the first { or [ and extract from there.
+    // This handles Claude responses like "I'll analyze...\n\n```json\n{...}\n```" or "Here is the JSON:\n{...}"
+    if (!jsonStr.startsWith('{') && !jsonStr.startsWith('[')) {
+      const firstBrace = jsonStr.indexOf('{');
+      const firstBracket = jsonStr.indexOf('[');
+      const jsonStart = firstBrace === -1 ? firstBracket
+                      : firstBracket === -1 ? firstBrace
+                      : Math.min(firstBrace, firstBracket);
+      if (jsonStart > 0) {
+        // Also strip trailing markdown fences that may follow the JSON block
+        jsonStr = jsonStr.slice(jsonStart).replace(/\n?\s*```\s*$/, '').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, cachedContext = null) {
+    if (!this._client) {
+      this._client = this._createClient();
+    }
+
+    // Use model-specific maximum tokens
+    const maxTokens = getMaxTokensForModel(this.model);
+
+    let systemParam;
+    let userContent;
+
+    if (cachedContext) {
+      systemParam = agentInstructions
+        ? [
+            { type: 'text', text: agentInstructions, cache_control: { type: 'ephemeral' } },
+          ]
+        : undefined;
+      userContent = [
+        { type: 'text', text: cachedContext, cache_control: { type: 'ephemeral' } },
+        { type: 'text', text: prompt },
+      ];
+    } else {
+      userContent = agentInstructions ? `${agentInstructions}\n\n${prompt}` : prompt;
+    }
+
+    const requestParams = {
+      model: this.model,
+      max_tokens: maxTokens,
+      messages: [{ role: 'user', content: userContent }],
+    };
+    if (systemParam) requestParams.system = systemParam;
+
+    const fullPrompt = agentInstructions ? `${agentInstructions}\n\n${prompt}` : prompt;
+
+    const _t0Text = Date.now();
+    const response = await this._withRetry(
+      () => this._client.messages.create(requestParams),
+      'Text generation (Claude)'
+    );
+
+    const text = response.content[0].text;
+    this._trackTokens(response.usage, {
+      prompt: fullPrompt,
+      agentInstructions: agentInstructions ?? null,
+      response: text,
+      elapsed: Date.now() - _t0Text,
+    });
+    return text;
+  }
 }

package/cli/llm-gemini.js

@@ -1,5 +1,7 @@
 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); }
@@ -25,6 +27,113 @@ export class GeminiProvider extends LLMProvider {
     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, cachedContext = 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
+      }
+    };
+
+    // When cachedContext is provided (e.g. project rootContextMd), set it as the
+    // systemInstruction — Gemini's implicit caching targets system instructions and
+    // stable prefix content, giving a best-effort discount with no extra setup.
+    if (cachedContext) {
+      params.systemInstruction = cachedContext;
+    }
+
+    const _t0Json = Date.now();
+    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).');
+    }
+
+    const content = response.text;
+    this._trackTokens(response.usageMetadata, {
+      prompt: fullPrompt,
+      agentInstructions: agentInstructions ?? null,
+      response: content,
+      elapsed: Date.now() - _t0Json,
+    });
+
+    // 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, cachedContext = 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
+      }
+    };
+
+    if (cachedContext) {
+      params.systemInstruction = cachedContext;
+    }
+
+    const _t0Text = Date.now();
+    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).');
+    }
+
+    const text = response.text;
+    this._trackTokens(response.usageMetadata, {
+      prompt: fullPrompt,
+      agentInstructions: agentInstructions ?? null,
+      response: text,
+      elapsed: Date.now() - _t0Text,
+    });
+    return text;
+  }
 }