deepdebug-local-agent 0.3.1 → 0.3.3

package/.dockerignore

@@ -20,5 +20,6 @@ __tests__
 .idea/deepdebug-local-agent.iml
 .idea/modules.xml
 node_modules/
+package-lock.json
 src/.DS_Store
 src/analyzers/

package/bin/install.js

@@ -0,0 +1,282 @@
+#!/usr/bin/env node
+
+/**
+ * deepdebug-local-agent CLI
+ *
+ * Usage:
+ *   npx deepdebug-local-agent install   — installs and starts the agent as a service
+ *   npx deepdebug-local-agent start     — starts the agent
+ *   npx deepdebug-local-agent stop      — stops the agent
+ *   npx deepdebug-local-agent status    — shows agent status
+ *   npx deepdebug-local-agent run       — runs the agent in the foreground (dev mode)
+ */
+
+import { execSync, spawn } from 'child_process';
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import os from 'os';
+import readline from 'readline';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const ROOT_DIR = join(__dirname, '..');
+
+const CONFIG_DIR = join(os.homedir(), '.deepdebug');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+const DEFAULT_PORT = 5055;
+const DEFAULT_GATEWAY = 'https://gateway.insptech.pt';
+const AGENT_NAME = 'deepdebug-agent';
+
+const BLUE   = '\x1b[34m';
+const GREEN  = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const RED    = '\x1b[31m';
+const BOLD   = '\x1b[1m';
+const RESET  = '\x1b[0m';
+
+const log  = (msg) => console.log(`${BLUE}[DeepDebug]${RESET} ${msg}`);
+const ok   = (msg) => console.log(`${GREEN}✓${RESET} ${msg}`);
+const warn = (msg) => console.log(`${YELLOW}⚠${RESET}  ${msg}`);
+const err  = (msg) => console.log(`${RED}✗${RESET} ${msg}`);
+const bold = (msg) => `${BOLD}${msg}${RESET}`;
+
+function printBanner() {
+    console.log('');
+    console.log(`${BLUE}${BOLD}╔═══════════════════════════════════════╗${RESET}`);
+    console.log(`${BLUE}${BOLD}║      Insptech AI — DeepDebug Agent    ║${RESET}`);
+    console.log(`${BLUE}${BOLD}║         deepdebug-local-agent         ║${RESET}`);
+    console.log(`${BLUE}${BOLD}╚═══════════════════════════════════════╝${RESET}`);
+    console.log('');
+}
+
+function ask(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise(resolve => rl.question(question, ans => { rl.close(); resolve(ans.trim()); }));
+}
+
+function loadConfig() {
+    try {
+        if (existsSync(CONFIG_FILE)) {
+            return JSON.parse(readFileSync(CONFIG_FILE, 'utf8'));
+        }
+    } catch {}
+    return {};
+}
+
+function saveConfig(cfg) {
+    if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true });
+    writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2), 'utf8');
+}
+
+function checkNodeVersion() {
+    const major = parseInt(process.version.slice(1).split('.')[0]);
+    if (major < 18) {
+        err(`Node.js ${process.version} detected. Version 18 or higher is required.`);
+        err('Download: https://nodejs.org');
+        process.exit(1);
+    }
+    ok(`Node.js ${process.version} detected`);
+}
+
+function getServerScript() {
+    // Try common locations
+    const candidates = [
+        join(ROOT_DIR, 'server.js'),
+        join(ROOT_DIR, 'src', 'server.js'),
+    ];
+    for (const c of candidates) {
+        if (existsSync(c)) return c;
+    }
+    // Fallback: server.js next to bin/
+    return join(ROOT_DIR, 'server.js');
+}
+
+// ─── Platform detection ───────────────────────────────────────────────────────
+
+const platform = os.platform(); // 'win32' | 'darwin' | 'linux'
+
+function getPidFile() {
+    return join(CONFIG_DIR, 'agent.pid');
+}
+
+function readPid() {
+    try {
+        const pid = parseInt(readFileSync(getPidFile(), 'utf8').trim());
+        return isNaN(pid) ? null : pid;
+    } catch { return null; }
+}
+
+function isRunning(pid) {
+    try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+// ─── Commands ─────────────────────────────────────────────────────────────────
+
+async function cmdInstall() {
+    printBanner();
+    log('Starting installation...');
+    console.log('');
+
+    checkNodeVersion();
+
+    // Read or create config
+    let cfg = loadConfig();
+
+    // Prompt for API Key if not set
+    if (!cfg.apiKey) {
+        console.log(`${YELLOW}You need an API Key from the Insptech AI platform.${RESET}`);
+        console.log(`Open ${bold('https://app.insptech.pt')} → Settings → Agent → Generate API Key`);
+        console.log('');
+        const key = await ask('  Enter your API Key: ');
+        if (!key || key.length < 10) {
+            err('Invalid API Key. Installation aborted.');
+            process.exit(1);
+        }
+        cfg.apiKey = key;
+    } else {
+        ok('API Key already configured');
+    }
+
+    if (!cfg.gatewayUrl) cfg.gatewayUrl = DEFAULT_GATEWAY;
+    if (!cfg.port)       cfg.port = DEFAULT_PORT;
+
+    saveConfig(cfg);
+    ok(`Configuration saved to ${CONFIG_FILE}`);
+
+    // Install npm dependencies if needed
+    const nodeModules = join(ROOT_DIR, 'node_modules');
+    if (!existsSync(nodeModules)) {
+        log('Installing dependencies...');
+        try {
+            execSync('npm install --production', { cwd: ROOT_DIR, stdio: 'inherit' });
+            ok('Dependencies installed');
+        } catch (e) {
+            warn('Could not install dependencies automatically. Run: npm install');
+        }
+    } else {
+        ok('Dependencies already installed');
+    }
+
+    console.log('');
+
+    // Start the agent
+    await cmdStart(cfg);
+
+    console.log('');
+    ok(bold('Agent registered successfully'));
+    console.log('');
+    log(`Health check: ${bold(`http://localhost:${cfg.port}/health`)}`);
+    log(`Platform:     ${bold('https://app.insptech.pt')}`);
+    console.log('');
+}
+
+async function cmdStart(cfg) {
+    cfg = cfg || loadConfig();
+
+    const pid = readPid();
+    if (pid && isRunning(pid)) {
+        ok(`Agent is already running (PID ${pid})`);
+        return;
+    }
+
+    const serverScript = getServerScript();
+    if (!existsSync(serverScript)) {
+        err(`Server script not found: ${serverScript}`);
+        process.exit(1);
+    }
+
+    log(`Starting agent on port ${cfg.port || DEFAULT_PORT}...`);
+
+    const env = {
+        ...process.env,
+        NODE_ENV: 'production',
+        PORT: String(cfg.port || DEFAULT_PORT),
+        DEEPDEBUG_API_KEY: cfg.apiKey || '',
+        GATEWAY_URL: cfg.gatewayUrl || DEFAULT_GATEWAY,
+    };
+
+    const child = spawn(process.execPath, [serverScript], {
+        env,
+        detached: true,
+        stdio: 'ignore',
+        cwd: ROOT_DIR,
+    });
+
+    child.unref();
+
+    // Save PID
+    if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true });
+    writeFileSync(getPidFile(), String(child.pid), 'utf8');
+
+    // Wait a moment and verify
+    await new Promise(r => setTimeout(r, 1500));
+
+    if (isRunning(child.pid)) {
+        ok(`Agent started (PID ${child.pid})`);
+    } else {
+        warn('Agent may have failed to start. Check logs or run in foreground: npx deepdebug-local-agent run');
+    }
+}
+
+function cmdStop() {
+    const pid = readPid();
+    if (!pid) { warn('No PID file found. Agent may not be running.'); return; }
+    if (!isRunning(pid)) { warn(`No process with PID ${pid}. Agent is not running.`); return; }
+    try {
+        process.kill(pid, 'SIGTERM');
+        ok(`Agent stopped (PID ${pid})`);
+    } catch (e) {
+        err(`Failed to stop agent: ${e.message}`);
+    }
+}
+
+function cmdStatus() {
+    const cfg = loadConfig();
+    const pid = readPid();
+    const port = cfg.port || DEFAULT_PORT;
+    console.log('');
+    console.log(`${BOLD}DeepDebug Local Agent — Status${RESET}`);
+    console.log('─'.repeat(40));
+    if (pid && isRunning(pid)) {
+        console.log(`  Process : ${GREEN}Running${RESET} (PID ${pid})`);
+    } else {
+        console.log(`  Process : ${RED}Not running${RESET}`);
+    }
+    console.log(`  Port    : ${port}`);
+    console.log(`  Config  : ${CONFIG_FILE}`);
+    console.log(`  Gateway : ${cfg.gatewayUrl || DEFAULT_GATEWAY}`);
+    console.log(`  Health  : http://localhost:${port}/health`);
+    console.log('');
+}
+
+function cmdRun() {
+    // Foreground mode — useful for debugging
+    const cfg = loadConfig();
+    const serverScript = getServerScript();
+    const env = {
+        ...process.env,
+        NODE_ENV: 'development',
+        PORT: String(cfg.port || DEFAULT_PORT),
+        DEEPDEBUG_API_KEY: cfg.apiKey || '',
+        GATEWAY_URL: cfg.gatewayUrl || DEFAULT_GATEWAY,
+    };
+    log(`Running in foreground on port ${cfg.port || DEFAULT_PORT} (Ctrl+C to stop)...`);
+    const child = spawn(process.execPath, [serverScript], { env, stdio: 'inherit', cwd: ROOT_DIR });
+    child.on('exit', code => process.exit(code || 0));
+}
+
+// ─── Entry point ──────────────────────────────────────────────────────────────
+
+const command = process.argv[2] || 'install';
+
+switch (command) {
+    case 'install': cmdInstall().catch(e => { err(e.message); process.exit(1); }); break;
+    case 'start':   cmdStart().catch(e => { err(e.message); process.exit(1); });   break;
+    case 'stop':    cmdStop();    break;
+    case 'status':  cmdStatus();  break;
+    case 'run':     cmdRun();     break;
+    default:
+        console.log(`Usage: npx deepdebug-local-agent [install|start|stop|status|run]`);
+        process.exit(1);
+}

package/package.json

@@ -1,12 +1,23 @@
 {
   "name": "deepdebug-local-agent",
-  "version": "0.3.1",
+  "version": "0.3.3",
+  "description": "Insptech AI — DeepDebug Local Agent. Autonomous code debugging agent for production environments.",
   "type": "module",
-  "main": "src/server.js",
+  "main": "server.js",
+  "bin": {
+    "deepdebug-local-agent": "./bin/install.js"
+  },
   "scripts": {
-    "start": "node src/server.js",
-    "dev": "NODE_ENV=development node src/server.js",
-    "mcp": "node src/mcp-server.js"
+    "start": "node server.js",
+    "dev": "NODE_ENV=development node server.js",
+    "mcp": "node mcp-server.js"
+  },
+  "keywords": ["deepdebug", "insptech", "debugging", "ai", "autonomous", "agent"],
+  "author": "Insptech AI <contacto@insptech.pt>",
+  "license": "UNLICENSED",
+  "homepage": "https://deepdebug.ai",
+  "engines": {
+    "node": ">=18.0.0"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
@@ -19,4 +30,4 @@
     "strip-ansi": "^7.1.0",
     "unidiff": "^1.0.2"
   }
-}
+}

package/src/git/base-git-provider.js

@@ -22,7 +22,7 @@ export class BaseGitProvider {
     // ==========================================
 
     /**
-     * Identificador único do provider
+     * Identificador único do provider
      * @returns {string} Ex: 'github', 'gitlab', 'bitbucket'
      */
     getId() {
@@ -30,7 +30,7 @@ export class BaseGitProvider {
     }
 
     /**
-     * Nome amigável do provider
+     * Nome amigável do provider
      * @returns {string} Ex: 'GitHub', 'GitLab', 'Bitbucket'
      */
     getName() {
@@ -78,7 +78,7 @@ export class BaseGitProvider {
     }
 
     /**
-     * Valida se o token ainda é válido
+     * Valida se o token ainda é válido
      * @returns {Promise<boolean>}
      */
     async validateToken() {
@@ -90,7 +90,7 @@ export class BaseGitProvider {
     // ==========================================
 
     /**
-     * Obtém informações do usuário autenticado
+     * Obtém informações do usuário autenticado
      * @returns {Promise<UserInfo>}
      */
     async getCurrentUser() {
@@ -102,7 +102,7 @@ export class BaseGitProvider {
     // ==========================================
 
     /**
-     * Lista repositórios do usuário
+     * Lista repositórios do usuário
      * @param {object} options - { page, perPage, sort }
      * @returns {Promise<Repository[]>}
      */
@@ -111,7 +111,7 @@ export class BaseGitProvider {
     }
 
     /**
-     * Obtém informações de um repositório
+     * Obtém informações de um repositório
      * @param {string} owner - Owner do repo
      * @param {string} repo - Nome do repo
      * @returns {Promise<Repository>}
@@ -121,7 +121,7 @@ export class BaseGitProvider {
     }
 
     /**
-     * Clona um repositório
+     * Clona um repositório
      * @param {string} owner - Owner do repo
      * @param {string} repo - Nome do repo
      * @param {string} destPath - Caminho de destino
@@ -137,7 +137,7 @@ export class BaseGitProvider {
     // ==========================================
 
     /**
-     * Lista branches do repositório
+     * Lista branches do repositório
      * @param {string} owner - Owner do repo
      * @param {string} repo - Nome do repo
      * @returns {Promise<Branch[]>}
@@ -159,7 +159,7 @@ export class BaseGitProvider {
     }
 
     /**
-     * Obtém informações de uma branch
+     * Obtém informações de uma branch
      * @param {string} owner - Owner do repo
      * @param {string} repo - Nome do repo
      * @param {string} branch - Nome da branch
@@ -186,12 +186,12 @@ export class BaseGitProvider {
     }
 
     /**
-     * Cria um commit com mudanças
+     * Cria um commit com mudanças
      * @param {string} owner - Owner do repo
      * @param {string} repo - Nome do repo
      * @param {string} branch - Nome da branch
      * @param {string} message - Mensagem do commit
-     * @param {FileChange[]} changes - Lista de mudanças
+     * @param {FileChange[]} changes - Lista de mudanças
      * @returns {Promise<Commit>}
      */
     async createCommit(owner, repo, branch, message, changes) {
@@ -203,7 +203,7 @@ export class BaseGitProvider {
     // ==========================================
 
     /**
-     * Obtém conteúdo de um arquivo
+     * Obtém conteúdo de um arquivo
      * @param {string} owner - Owner do repo
      * @param {string} repo - Nome do repo
      * @param {string} path - Caminho do arquivo
@@ -219,7 +219,7 @@ export class BaseGitProvider {
      * @param {string} owner - Owner do repo
      * @param {string} repo - Nome do repo
      * @param {string} path - Caminho do arquivo
-     * @param {string} content - Conteúdo (base64 ou texto)
+     * @param {string} content - Conteúdo (base64 ou texto)
      * @param {string} message - Mensagem do commit
      * @param {string} branch - Branch
      * @param {string} sha - SHA atual (para update)
@@ -256,16 +256,136 @@ export class BaseGitProvider {
     }
 
     /**
-     * Obtém informações de um pull request
+     * Obtém informações de um pull request
      * @param {string} owner - Owner do repo
      * @param {string} repo - Nome do repo
-     * @param {number} prNumber - Número do PR
+     * @param {number} prNumber - Número do PR
      * @returns {Promise<PullRequest>}
      */
     async getPullRequest(owner, repo, prNumber) {
         throw new Error('Method getPullRequest() must be implemented');
     }
 
+    // ==========================================
+    // PULL REQUEST COMMENTS / REVIEWS
+    // ==========================================
+
+    /**
+     * Lista comentários de um pull request
+     * @param {string} owner - Owner do repo
+     * @param {string} repo - Nome do repo
+     * @param {number} prNumber - Número do PR
+     * @param {object} options - { page, perPage }
+     * @returns {Promise<PRComment[]>}
+     */
+    async listPRComments(owner, repo, prNumber, options = {}) {
+        throw new Error('Method listPRComments() must be implemented');
+    }
+
+    /**
+     * Lista apenas comentários de review (inline no código)
+     * @param {string} owner - Owner do repo
+     * @param {string} repo - Nome do repo
+     * @param {number} prNumber - Número do PR
+     * @param {object} options - { page, perPage }
+     * @returns {Promise<PRReviewComment[]>}
+     */
+    async listPRReviewComments(owner, repo, prNumber, options = {}) {
+        throw new Error('Method listPRReviewComments() must be implemented');
+    }
+
+    /**
+     * Obtém um comentário específico
+     * @param {string} owner - Owner do repo
+     * @param {string} repo - Nome do repo
+     * @param {number} prNumber - Número do PR
+     * @param {string|number} commentId - ID do comentário
+     * @returns {Promise<PRComment>}
+     */
+    async getPRComment(owner, repo, prNumber, commentId) {
+        throw new Error('Method getPRComment() must be implemented');
+    }
+
+    /**
+     * Adiciona um comentário geral ao PR
+     * @param {string} owner - Owner do repo
+     * @param {string} repo - Nome do repo
+     * @param {number} prNumber - Número do PR
+     * @param {string} body - Conteúdo do comentário
+     * @returns {Promise<PRComment>}
+     */
+    async addPRComment(owner, repo, prNumber, body) {
+        throw new Error('Method addPRComment() must be implemented');
+    }
+
+    /**
+     * Adiciona um comentário inline no código (review comment)
+     * @param {string} owner - Owner do repo
+     * @param {string} repo - Nome do repo
+     * @param {number} prNumber - Número do PR
+     * @param {object} comment - { body, path, line, side, commitId }
+     * @returns {Promise<PRReviewComment>}
+     */
+    async addPRReviewComment(owner, repo, prNumber, comment) {
+        throw new Error('Method addPRReviewComment() must be implemented');
+    }
+
+    /**
+     * Responde a um comentário existente (thread reply)
+     * @param {string} owner - Owner do repo
+     * @param {string} repo - Nome do repo
+     * @param {number} prNumber - Número do PR
+     * @param {string|number} commentId - ID do comentário pai
+     * @param {string} body - Conteúdo da resposta
+     * @returns {Promise<PRComment>}
+     */
+    async replyToPRComment(owner, repo, prNumber, commentId, body) {
+        throw new Error('Method replyToPRComment() must be implemented');
+    }
+
+    /**
+     * Marca um comentário/thread como resolvido
+     * @param {string} owner - Owner do repo
+     * @param {string} repo - Nome do repo
+     * @param {number} prNumber - Número do PR
+     * @param {string|number} commentId - ID do comentário/thread
+     * @returns {Promise<{ resolved: boolean }>}
+     */
+    async resolvePRComment(owner, repo, prNumber, commentId) {
+        throw new Error('Method resolvePRComment() must be implemented');
+    }
+
+    /**
+     * Marca um comentário/thread como não resolvido
+     * @param {string} owner - Owner do repo
+     * @param {string} repo - Nome do repo
+     * @param {number} prNumber - Número do PR
+     * @param {string|number} commentId - ID do comentário/thread
+     * @returns {Promise<{ resolved: boolean }>}
+     */
+    async unresolvePRComment(owner, repo, prNumber, commentId) {
+        throw new Error('Method unresolvePRComment() must be implemented');
+    }
+
+    /**
+     * Lista comentários não resolvidos de um PR
+     * Convenience method - filtra listPRComments + listPRReviewComments
+     * @param {string} owner - Owner do repo
+     * @param {string} repo - Nome do repo
+     * @param {number} prNumber - Número do PR
+     * @returns {Promise<PRComment[]>}
+     */
+    async listUnresolvedPRComments(owner, repo, prNumber) {
+        // Default implementation: subclasses can override for better performance
+        const [general, review] = await Promise.all([
+            this.listPRComments(owner, repo, prNumber).catch(() => []),
+            this.listPRReviewComments(owner, repo, prNumber).catch(() => [])
+        ]);
+
+        const all = [...general, ...review];
+        return all.filter(c => c.resolved === false || c.resolved === undefined);
+    }
+
     // ==========================================
     // WEBHOOKS
     // ==========================================
@@ -286,7 +406,7 @@ export class BaseGitProvider {
     // ==========================================
 
     /**
-     * Constrói URL de clone
+     * Constrói URL de clone
      * @param {string} owner - Owner do repo
      * @param {string} repo - Nome do repo
      * @param {boolean} useHttps - Usar HTTPS (default) ou SSH
@@ -297,8 +417,8 @@ export class BaseGitProvider {
     }
 
     /**
-     * Parsea URL de repositório para extrair owner e repo
-     * @param {string} url - URL do repositório
+     * Parsea URL de repositório para extrair owner e repo
+     * @param {string} url - URL do repositório
      * @returns {{ owner: string, repo: string }}
      */
     parseRepositoryUrl(url) {
@@ -381,4 +501,35 @@ export class BaseGitProvider {
  * @property {string} htmlUrl
  */
 
+/**
+ * @typedef {object} PRComment
+ * @property {string|number} id
+ * @property {string} body
+ * @property {string} authorUsername
+ * @property {string} authorName
+ * @property {string} createdAt
+ * @property {string} updatedAt
+ * @property {string} htmlUrl
+ * @property {boolean} [resolved]
+ * @property {string} [type] - 'general' | 'review' | 'inline'
+ */
+
+/**
+ * @typedef {object} PRReviewComment
+ * @property {string|number} id
+ * @property {string} body
+ * @property {string} path - File path the comment is on
+ * @property {number} [line] - Line number
+ * @property {string} [side] - 'LEFT' | 'RIGHT'
+ * @property {string} [commitId] - Commit SHA the comment refers to
+ * @property {string} authorUsername
+ * @property {string} authorName
+ * @property {string} createdAt
+ * @property {string} updatedAt
+ * @property {string} htmlUrl
+ * @property {boolean} [resolved]
+ * @property {string|number} [threadId] - Thread/conversation ID for grouping
+ * @property {string|number} [inReplyToId] - Parent comment ID if this is a reply
+ */
+
 export default BaseGitProvider;