postgresai 0.12.0-beta.5 → 0.12.0-beta.7

package/bin/postgres-ai.ts

@@ -13,7 +13,7 @@ import * as readline from "readline";
 import * as http from "https";
 import { URL } from "url";
 import { startMcpServer } from "../lib/mcp-server";
-import { fetchIssues } from "../lib/issues";
+import { fetchIssues, fetchIssueComments, createIssueComment, fetchIssue } from "../lib/issues";
 import { resolveBaseUrls } from "../lib/util";
 
 const execPromise = promisify(exec);
@@ -59,14 +59,6 @@ interface PathResolution {
   instancesFile: string;
 }
 
-/**
- * Health check service
- */
-interface HealthService {
-  name: string;
-  url: string;
-}
-
 /**
  * Get configuration from various sources
  * @param opts - Command line options
@@ -90,6 +82,24 @@ function getConfig(opts: CliOptions): ConfigResult {
   return { apiKey };
 }
 
+// Human-friendly output helper: YAML for TTY by default, JSON when --json or non-TTY
+function printResult(result: unknown, json?: boolean): void {
+  if (typeof result === "string") {
+    process.stdout.write(result);
+    if (!/\n$/.test(result)) console.log();
+    return;
+  }
+  if (json || !process.stdout.isTTY) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    let text = yaml.dump(result as any);
+    if (Array.isArray(result)) {
+      text = text.replace(/\n- /g, "\n\n- ");
+    }
+    console.log(text);
+  }
+}
+
 const program = new Command();
 
 program
@@ -172,7 +182,7 @@ function checkRunningContainers(): { running: boolean; containers: string[] } {
       ["ps", "--filter", "name=grafana-with-datasources", "--filter", "name=pgwatch", "--format", "{{.Names}}"],
       { stdio: "pipe", encoding: "utf8" }
     );
-    
+
     if (result.status === 0 && result.stdout) {
       const containers = result.stdout.trim().split("\n").filter(Boolean);
       return { running: containers.length > 0, containers };
@@ -188,30 +198,53 @@ function checkRunningContainers(): { running: boolean; containers: string[] } {
  */
 async function runCompose(args: string[]): Promise<number> {
   let composeFile: string;
+  let projectDir: string;
   try {
-    ({ composeFile } = resolvePaths());
+    ({ composeFile, projectDir } = resolvePaths());
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     console.error(message);
     process.exitCode = 1;
     return 1;
   }
-  
+
   // Check if Docker daemon is running
   if (!isDockerRunning()) {
     console.error("Docker is not running. Please start Docker and try again");
     process.exitCode = 1;
     return 1;
   }
-  
+
   const cmd = getComposeCmd();
   if (!cmd) {
     console.error("docker compose not found (need docker-compose or docker compose)");
     process.exitCode = 1;
     return 1;
   }
+
+  // Read Grafana password from .pgwatch-config and pass to Docker Compose
+  const env = { ...process.env };
+  const cfgPath = path.resolve(projectDir, ".pgwatch-config");
+  if (fs.existsSync(cfgPath)) {
+    try {
+      const stats = fs.statSync(cfgPath);
+      if (!stats.isDirectory()) {
+        const content = fs.readFileSync(cfgPath, "utf8");
+        const match = content.match(/^grafana_password=([^\r\n]+)/m);
+        if (match) {
+          env.GF_SECURITY_ADMIN_PASSWORD = match[1].trim();
+        }
+      }
+    } catch (err) {
+      // If we can't read the config, continue without setting the password
+    }
+  }
+
   return new Promise<number>((resolve) => {
-    const child = spawn(cmd[0], [...cmd.slice(1), "-f", composeFile, ...args], { stdio: "inherit" });
+    const child = spawn(cmd[0], [...cmd.slice(1), "-f", composeFile, ...args], {
+      stdio: "inherit",
+      env: env
+    });
     child.on("close", (code) => resolve(code || 0));
   });
 }
@@ -226,23 +259,308 @@ const mon = program.command("mon").description("monitoring services management")
 mon
   .command("quickstart")
   .description("complete setup (generate config, start monitoring services)")
-  .option("--demo", "demo mode", false)
-  .action(async () => {
+  .option("--demo", "demo mode with sample database", false)
+  .option("--api-key <key>", "Postgres AI API key for automated report uploads")
+  .option("--db-url <url>", "PostgreSQL connection URL to monitor")
+  .option("-y, --yes", "accept all defaults and skip interactive prompts", false)
+  .action(async (opts: { demo: boolean; apiKey?: string; dbUrl?: string; yes: boolean }) => {
+    console.log("\n=================================");
+    console.log("  PostgresAI Monitoring Quickstart");
+    console.log("=================================\n");
+    console.log("This will install, configure, and start the monitoring system\n");
+
+    // Validate conflicting options
+    if (opts.demo && opts.dbUrl) {
+      console.log("⚠ Both --demo and --db-url provided. Demo mode includes its own database.");
+      console.log("⚠ The --db-url will be ignored in demo mode.\n");
+      opts.dbUrl = undefined;
+    }
+
+    if (opts.demo && opts.apiKey) {
+      console.error("✗ Cannot use --api-key with --demo mode");
+      console.error("✗ Demo mode is for testing only and does not support API key integration");
+      console.error("\nUse demo mode without API key: postgres-ai mon quickstart --demo");
+      console.error("Or use production mode with API key: postgres-ai mon quickstart --api-key=your_key");
+      process.exitCode = 1;
+      return;
+    }
+
     // Check if containers are already running
     const { running, containers } = checkRunningContainers();
     if (running) {
-      console.log(`Monitoring services are already running: ${containers.join(", ")}`);
-      console.log("Use 'postgres-ai mon restart' to restart them");
+      console.log(`⚠ Monitoring services are already running: ${containers.join(", ")}`);
+      console.log("Use 'postgres-ai mon restart' to restart them\n");
       return;
     }
-    
+
+    // Step 1: API key configuration (only in production mode)
+    if (!opts.demo) {
+      console.log("Step 1: Postgres AI API Configuration (Optional)");
+      console.log("An API key enables automatic upload of PostgreSQL reports to Postgres AI\n");
+
+      if (opts.apiKey) {
+        console.log("Using API key provided via --api-key parameter");
+        config.writeConfig({ apiKey: opts.apiKey });
+        console.log("✓ API key saved\n");
+      } else if (opts.yes) {
+        // Auto-yes mode without API key - skip API key setup
+        console.log("Auto-yes mode: no API key provided, skipping API key setup");
+        console.log("⚠ Reports will be generated locally only");
+        console.log("You can add an API key later with: postgres-ai add-key <api_key>\n");
+      } else {
+        const rl = readline.createInterface({
+          input: process.stdin,
+          output: process.stdout
+        });
+
+        const question = (prompt: string): Promise<string> =>
+          new Promise((resolve) => rl.question(prompt, resolve));
+
+        try {
+          const answer = await question("Do you have a Postgres AI API key? (Y/n): ");
+          const proceedWithApiKey = !answer || answer.toLowerCase() === "y";
+
+          if (proceedWithApiKey) {
+            while (true) {
+              const inputApiKey = await question("Enter your Postgres AI API key: ");
+              const trimmedKey = inputApiKey.trim();
+
+              if (trimmedKey) {
+                config.writeConfig({ apiKey: trimmedKey });
+                console.log("✓ API key saved\n");
+                break;
+              }
+
+              console.log("⚠ API key cannot be empty");
+              const retry = await question("Try again or skip API key setup, retry? (Y/n): ");
+              if (retry.toLowerCase() === "n") {
+                console.log("⚠ Skipping API key setup - reports will be generated locally only");
+                console.log("You can add an API key later with: postgres-ai add-key <api_key>\n");
+                break;
+              }
+            }
+          } else {
+            console.log("⚠ Skipping API key setup - reports will be generated locally only");
+            console.log("You can add an API key later with: postgres-ai add-key <api_key>\n");
+          }
+        } finally {
+          rl.close();
+        }
+      }
+    } else {
+      console.log("Step 1: Demo mode - API key configuration skipped");
+      console.log("Demo mode is for testing only and does not support API key integration\n");
+    }
+
+    // Step 2: Add PostgreSQL instance (if not demo mode)
+    if (!opts.demo) {
+      console.log("Step 2: Add PostgreSQL Instance to Monitor\n");
+
+      // Clear instances.yml in production mode (start fresh)
+      const instancesPath = path.resolve(process.cwd(), "instances.yml");
+      const emptyInstancesContent = "# PostgreSQL instances to monitor\n# Add your instances using: postgres-ai mon targets add\n\n";
+      fs.writeFileSync(instancesPath, emptyInstancesContent, "utf8");
+
+      if (opts.dbUrl) {
+        console.log("Using database URL provided via --db-url parameter");
+        console.log(`Adding PostgreSQL instance from: ${opts.dbUrl}\n`);
+
+        const match = opts.dbUrl.match(/^postgresql:\/\/[^@]+@([^:/]+)/);
+        const autoInstanceName = match ? match[1] : "db-instance";
+
+        const connStr = opts.dbUrl;
+        const m = connStr.match(/^postgresql:\/\/([^:]+):([^@]+)@([^:\/]+)(?::(\d+))?\/(.+)$/);
+
+        if (!m) {
+          console.error("✗ Invalid connection string format");
+          process.exitCode = 1;
+          return;
+        }
+
+        const host = m[3];
+        const db = m[5];
+        const instanceName = `${host}-${db}`.replace(/[^a-zA-Z0-9-]/g, "-");
+
+        const body = `- name: ${instanceName}\n  conn_str: ${connStr}\n  preset_metrics: full\n  custom_metrics:\n  is_enabled: true\n  group: default\n  custom_tags:\n    env: production\n    cluster: default\n    node_name: ${instanceName}\n    sink_type: ~sink_type~\n`;
+        fs.appendFileSync(instancesPath, body, "utf8");
+        console.log(`✓ Monitoring target '${instanceName}' added\n`);
+
+        // Test connection
+        console.log("Testing connection to the added instance...");
+        try {
+          const { Client } = require("pg");
+          const client = new Client({ connectionString: connStr });
+          await client.connect();
+          const result = await client.query("select version();");
+          console.log("✓ Connection successful");
+          console.log(`${result.rows[0].version}\n`);
+          await client.end();
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          console.error(`✗ Connection failed: ${message}\n`);
+        }
+      } else if (opts.yes) {
+        // Auto-yes mode without database URL - skip database setup
+        console.log("Auto-yes mode: no database URL provided, skipping database setup");
+        console.log("⚠ No PostgreSQL instance added");
+        console.log("You can add one later with: postgres-ai mon targets add\n");
+      } else {
+        const rl = readline.createInterface({
+          input: process.stdin,
+          output: process.stdout
+        });
+
+        const question = (prompt: string): Promise<string> =>
+          new Promise((resolve) => rl.question(prompt, resolve));
+
+        try {
+          console.log("You need to add at least one PostgreSQL instance to monitor");
+          const answer = await question("Do you want to add a PostgreSQL instance now? (Y/n): ");
+          const proceedWithInstance = !answer || answer.toLowerCase() === "y";
+
+          if (proceedWithInstance) {
+            console.log("\nYou can provide either:");
+            console.log("  1. A full connection string: postgresql://user:pass@host:port/database");
+            console.log("  2. Press Enter to skip for now\n");
+
+            const connStr = await question("Enter connection string (or press Enter to skip): ");
+
+            if (connStr.trim()) {
+              const m = connStr.match(/^postgresql:\/\/([^:]+):([^@]+)@([^:\/]+)(?::(\d+))?\/(.+)$/);
+              if (!m) {
+                console.error("✗ Invalid connection string format");
+                console.log("⚠ Continuing without adding instance\n");
+              } else {
+                const host = m[3];
+                const db = m[5];
+                const instanceName = `${host}-${db}`.replace(/[^a-zA-Z0-9-]/g, "-");
+
+                const body = `- name: ${instanceName}\n  conn_str: ${connStr}\n  preset_metrics: full\n  custom_metrics:\n  is_enabled: true\n  group: default\n  custom_tags:\n    env: production\n    cluster: default\n    node_name: ${instanceName}\n    sink_type: ~sink_type~\n`;
+                fs.appendFileSync(instancesPath, body, "utf8");
+                console.log(`✓ Monitoring target '${instanceName}' added\n`);
+
+                // Test connection
+                console.log("Testing connection to the added instance...");
+                try {
+                  const { Client } = require("pg");
+                  const client = new Client({ connectionString: connStr });
+                  await client.connect();
+                  const result = await client.query("select version();");
+                  console.log("✓ Connection successful");
+                  console.log(`${result.rows[0].version}\n`);
+                  await client.end();
+                } catch (error) {
+                  const message = error instanceof Error ? error.message : String(error);
+                  console.error(`✗ Connection failed: ${message}\n`);
+                }
+              }
+            } else {
+              console.log("⚠ No PostgreSQL instance added - you can add one later with: postgres-ai mon targets add\n");
+            }
+          } else {
+            console.log("⚠ No PostgreSQL instance added - you can add one later with: postgres-ai mon targets add\n");
+          }
+        } finally {
+          rl.close();
+        }
+      }
+    } else {
+      console.log("Step 2: Demo mode enabled - using included demo PostgreSQL database\n");
+    }
+
+    // Step 3: Update configuration
+    console.log(opts.demo ? "Step 3: Updating configuration..." : "Step 3: Updating configuration...");
     const code1 = await runCompose(["run", "--rm", "sources-generator"]);
     if (code1 !== 0) {
       process.exitCode = code1;
       return;
     }
-    const code2 = await runCompose(["up", "-d"]);
-    if (code2 !== 0) process.exitCode = code2;
+    console.log("✓ Configuration updated\n");
+
+    // Step 4: Ensure Grafana password is configured
+    console.log(opts.demo ? "Step 4: Configuring Grafana security..." : "Step 4: Configuring Grafana security...");
+    const cfgPath = path.resolve(process.cwd(), ".pgwatch-config");
+    let grafanaPassword = "";
+
+    try {
+      if (fs.existsSync(cfgPath)) {
+        const stats = fs.statSync(cfgPath);
+        if (!stats.isDirectory()) {
+          const content = fs.readFileSync(cfgPath, "utf8");
+          const match = content.match(/^grafana_password=([^\r\n]+)/m);
+          if (match) {
+            grafanaPassword = match[1].trim();
+          }
+        }
+      }
+
+      if (!grafanaPassword) {
+        console.log("Generating secure Grafana password...");
+        const { stdout: password } = await execPromise("openssl rand -base64 12 | tr -d '\n'");
+        grafanaPassword = password.trim();
+
+        let configContent = "";
+        if (fs.existsSync(cfgPath)) {
+          const stats = fs.statSync(cfgPath);
+          if (!stats.isDirectory()) {
+            configContent = fs.readFileSync(cfgPath, "utf8");
+          }
+        }
+
+        const lines = configContent.split(/\r?\n/).filter((l) => !/^grafana_password=/.test(l));
+        lines.push(`grafana_password=${grafanaPassword}`);
+        fs.writeFileSync(cfgPath, lines.filter(Boolean).join("\n") + "\n", "utf8");
+      }
+
+      console.log("✓ Grafana password configured\n");
+    } catch (error) {
+      console.log("⚠ Could not generate Grafana password automatically");
+      console.log("Using default password: demo\n");
+      grafanaPassword = "demo";
+    }
+
+    // Step 5: Start services
+    console.log(opts.demo ? "Step 5: Starting monitoring services..." : "Step 5: Starting monitoring services...");
+    const code2 = await runCompose(["up", "-d", "--force-recreate"]);
+    if (code2 !== 0) {
+      process.exitCode = code2;
+      return;
+    }
+    console.log("✓ Services started\n");
+
+    // Final summary
+    console.log("=================================");
+    console.log("  🎉 Quickstart setup completed!");
+    console.log("=================================\n");
+
+    console.log("What's running:");
+    if (opts.demo) {
+      console.log("  ✅ Demo PostgreSQL database (monitoring target)");
+    }
+    console.log("  ✅ PostgreSQL monitoring infrastructure");
+    console.log("  ✅ Grafana dashboards (with secure password)");
+    console.log("  ✅ Prometheus metrics storage");
+    console.log("  ✅ Flask API backend");
+    console.log("  ✅ Automated report generation (every 24h)");
+    console.log("  ✅ Host stats monitoring (CPU, memory, disk, I/O)\n");
+
+    if (!opts.demo) {
+      console.log("Next steps:");
+      console.log("  • Add more PostgreSQL instances: postgres-ai mon targets add");
+      console.log("  • View configured instances: postgres-ai mon targets list");
+      console.log("  • Check service health: postgres-ai mon health\n");
+    } else {
+      console.log("Demo mode next steps:");
+      console.log("  • Explore Grafana dashboards at http://localhost:3000");
+      console.log("  • Connect to demo database: postgresql://postgres:postgres@localhost:55432/target_database");
+      console.log("  • Generate some load on the demo database to see metrics\n");
+    }
+
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+    console.log("🚀 MAIN ACCESS POINT - Start here:");
+    console.log("   Grafana Dashboard: http://localhost:3000");
+    console.log(`   Login: monitor / ${grafanaPassword}`);
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");
   });
 
 mon
@@ -256,7 +574,7 @@ mon
       console.log("Use 'postgres-ai mon restart' to restart them");
       return;
     }
-    
+
     const code = await runCompose(["up", "-d"]);
     if (code !== 0) process.exitCode = code;
   });
@@ -305,42 +623,40 @@ mon
   .description("health check for monitoring services")
   .option("--wait <seconds>", "wait time in seconds for services to become healthy", parseInt, 0)
   .action(async (opts: { wait: number }) => {
-    const services: HealthService[] = [
-      { name: "Grafana", url: "http://localhost:3000/api/health" },
-      { name: "Prometheus", url: "http://localhost:59090/-/healthy" },
-      { name: "PGWatch (Postgres)", url: "http://localhost:58080/health" },
-      { name: "PGWatch (Prometheus)", url: "http://localhost:58089/health" },
+    const services = [
+      { name: "Grafana", container: "grafana-with-datasources" },
+      { name: "Prometheus", container: "sink-prometheus" },
+      { name: "PGWatch (Postgres)", container: "pgwatch-postgres" },
+      { name: "PGWatch (Prometheus)", container: "pgwatch-prometheus" },
+      { name: "Target DB", container: "target-db" },
+      { name: "Sink Postgres", container: "sink-postgres" },
     ];
-    
+
     const waitTime = opts.wait || 0;
     const maxAttempts = waitTime > 0 ? Math.ceil(waitTime / 5) : 1;
-    
+
     console.log("Checking service health...\n");
-    
+
     let allHealthy = false;
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
       if (attempt > 1) {
         console.log(`Retrying (attempt ${attempt}/${maxAttempts})...\n`);
         await new Promise(resolve => setTimeout(resolve, 5000));
       }
-      
+
       allHealthy = true;
       for (const service of services) {
         try {
-          // Use native fetch instead of requiring curl to be installed
-          const controller = new AbortController();
-          const timeoutId = setTimeout(() => controller.abort(), 5000);
-          
-          const response = await fetch(service.url, {
-            signal: controller.signal,
-            method: 'GET',
-          });
-          clearTimeout(timeoutId);
-          
-          if (response.status === 200) {
+          const { execSync } = require("child_process");
+          const status = execSync(`docker inspect -f '{{.State.Status}}' ${service.container} 2>/dev/null`, {
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe']
+          }).trim();
+
+          if (status === 'running') {
             console.log(`✓ ${service.name}: healthy`);
           } else {
-            console.log(`✗ ${service.name}: unhealthy (HTTP ${response.status})`);
+            console.log(`✗ ${service.name}: unhealthy (status: ${status})`);
             allHealthy = false;
           }
         } catch (error) {
@@ -348,12 +664,12 @@ mon
           allHealthy = false;
         }
       }
-      
+
       if (allHealthy) {
         break;
       }
     }
-    
+
     console.log("");
     if (allHealthy) {
       console.log("All services are healthy");
@@ -399,7 +715,7 @@ mon
   .description("update monitoring stack")
   .action(async () => {
     console.log("Updating PostgresAI monitoring stack...\n");
-    
+
     try {
       // Check if we're in a git repo
       const gitDir = path.resolve(process.cwd(), ".git");
@@ -408,25 +724,25 @@ mon
         process.exitCode = 1;
         return;
       }
-      
+
       // Fetch latest changes
       console.log("Fetching latest changes...");
       await execPromise("git fetch origin");
-      
+
       // Check current branch
       const { stdout: branch } = await execPromise("git rev-parse --abbrev-ref HEAD");
       const currentBranch = branch.trim();
       console.log(`Current branch: ${currentBranch}`);
-      
+
       // Pull latest changes
       console.log("Pulling latest changes...");
       const { stdout: pullOut } = await execPromise("git pull origin " + currentBranch);
       console.log(pullOut);
-      
+
       // Update Docker images
       console.log("\nUpdating Docker images...");
       const code = await runCompose(["pull"]);
-      
+
       if (code === 0) {
         console.log("\n✓ Update completed successfully");
         console.log("\nTo apply updates, restart monitoring services:");
@@ -449,32 +765,32 @@ mon
       input: process.stdin,
       output: process.stdout,
     });
-    
+
     const question = (prompt: string): Promise<string> =>
       new Promise((resolve) => rl.question(prompt, resolve));
-    
+
     try {
       if (service) {
         // Reset specific service
         console.log(`\nThis will stop '${service}', remove its volume, and restart it.`);
         console.log("All data for this service will be lost!\n");
-        
+
         const answer = await question("Continue? (y/N): ");
         if (answer.toLowerCase() !== "y") {
           console.log("Cancelled");
           rl.close();
           return;
         }
-        
+
         console.log(`\nStopping ${service}...`);
         await runCompose(["stop", service]);
-        
+
         console.log(`Removing volume for ${service}...`);
         await runCompose(["rm", "-f", "-v", service]);
-        
+
         console.log(`Restarting ${service}...`);
         const code = await runCompose(["up", "-d", service]);
-        
+
         if (code === 0) {
           console.log(`\n✓ Service '${service}' has been reset`);
         } else {
@@ -485,17 +801,17 @@ mon
         // Reset all services
         console.log("\nThis will stop all services and remove all data!");
         console.log("Volumes, networks, and containers will be deleted.\n");
-        
+
         const answer = await question("Continue? (y/N): ");
         if (answer.toLowerCase() !== "y") {
           console.log("Cancelled");
           rl.close();
           return;
         }
-        
+
         console.log("\nStopping services and removing data...");
         const downCode = await runCompose(["down", "-v"]);
-        
+
         if (downCode === 0) {
           console.log("✓ Environment reset completed - all containers and data removed");
         } else {
@@ -503,7 +819,7 @@ mon
           process.exitCode = 1;
         }
       }
-      
+
       rl.close();
     } catch (error) {
       rl.close();
@@ -517,7 +833,7 @@ mon
   .description("cleanup monitoring services artifacts")
   .action(async () => {
     console.log("Cleaning up Docker resources...\n");
-    
+
     try {
       // Remove stopped containers
       const { stdout: containers } = await execFilePromise("docker", ["ps", "-aq", "--filter", "status=exited"]);
@@ -528,19 +844,19 @@ mon
       } else {
         console.log("✓ No stopped containers to remove");
       }
-      
+
       // Remove unused volumes
       await execFilePromise("docker", ["volume", "prune", "-f"]);
       console.log("✓ Removed unused volumes");
-      
+
       // Remove unused networks
       await execFilePromise("docker", ["network", "prune", "-f"]);
       console.log("✓ Removed unused networks");
-      
+
       // Remove dangling images
       await execFilePromise("docker", ["image", "prune", "-f"]);
       console.log("✓ Removed dangling images");
-      
+
       console.log("\nCleanup completed");
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
@@ -576,11 +892,11 @@ targets
       process.exitCode = 1;
       return;
     }
-    
+
     try {
       const content = fs.readFileSync(instancesPath, "utf8");
       const instances = yaml.load(content) as Instance[] | null;
-      
+
       if (!instances || !Array.isArray(instances) || instances.length === 0) {
         console.log("No monitoring targets configured");
         console.log("");
@@ -591,10 +907,10 @@ targets
         console.log("  postgres-ai mon targets add 'postgresql://user:pass@host:5432/db' my-db");
         return;
       }
-      
+
       // Filter out disabled instances (e.g., demo placeholders)
       const filtered = instances.filter((inst) => inst.name && inst.is_enabled !== false);
-      
+
       if (filtered.length === 0) {
         console.log("No monitoring targets configured");
         console.log("");
@@ -605,7 +921,7 @@ targets
         console.log("  postgres-ai mon targets add 'postgresql://user:pass@host:5432/db' my-db");
         return;
       }
-      
+
       for (const inst of filtered) {
         console.log(`Target: ${inst.name}`);
       }
@@ -634,7 +950,7 @@ targets
     const host = m[3];
     const db = m[5];
     const instanceName = name && name.trim() ? name.trim() : `${host}-${db}`.replace(/[^a-zA-Z0-9-]/g, "-");
-    
+
     // Check if instance already exists
     try {
       if (fs.existsSync(file)) {
@@ -658,7 +974,7 @@ targets
         return;
       }
     }
-    
+
     // Add new instance
     const body = `- name: ${instanceName}\n  conn_str: ${connStr}\n  preset_metrics: full\n  custom_metrics:\n  is_enabled: true\n  group: default\n  custom_tags:\n    env: production\n    cluster: default\n    node_name: ${instanceName}\n    sink_type: ~sink_type~\n`;
     const content = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
@@ -675,25 +991,25 @@ targets
       process.exitCode = 1;
       return;
     }
-    
+
     try {
       const content = fs.readFileSync(file, "utf8");
       const instances = yaml.load(content) as Instance[] | null;
-      
+
       if (!instances || !Array.isArray(instances)) {
         console.error("Invalid instances.yml format");
         process.exitCode = 1;
         return;
       }
-      
+
       const filtered = instances.filter((inst) => inst.name !== name);
-      
+
       if (filtered.length === instances.length) {
         console.error(`Monitoring target '${name}' not found`);
         process.exitCode = 1;
         return;
       }
-      
+
       fs.writeFileSync(file, yaml.dump(filtered), "utf8");
       console.log(`Monitoring target '${name}' removed`);
     } catch (err) {
@@ -712,37 +1028,37 @@ targets
       process.exitCode = 1;
       return;
     }
-    
+
     try {
       const content = fs.readFileSync(instancesPath, "utf8");
       const instances = yaml.load(content) as Instance[] | null;
-      
+
       if (!instances || !Array.isArray(instances)) {
         console.error("Invalid instances.yml format");
         process.exitCode = 1;
         return;
       }
-      
+
       const instance = instances.find((inst) => inst.name === name);
-      
+
       if (!instance) {
         console.error(`Monitoring target '${name}' not found`);
         process.exitCode = 1;
         return;
       }
-      
+
       if (!instance.conn_str) {
         console.error(`Connection string not found for monitoring target '${name}'`);
         process.exitCode = 1;
         return;
       }
-      
+
       console.log(`Testing connection to monitoring target '${name}'...`);
-      
+
       // Use native pg client instead of requiring psql to be installed
       const { Client } = require('pg');
       const client = new Client({ connectionString: instance.conn_str });
-      
+
       try {
         await client.connect();
         const result = await client.query('select version();');
@@ -767,34 +1083,34 @@ program
   .action(async (opts: { port?: number; debug?: boolean }) => {
     const pkce = require("../lib/pkce");
     const authServer = require("../lib/auth-server");
-    
+
     console.log("Starting authentication flow...\n");
-    
+
     // Generate PKCE parameters
     const params = pkce.generatePKCEParams();
 
     const rootOpts = program.opts<CliOptions>();
     const cfg = config.readConfig();
     const { apiBaseUrl, uiBaseUrl } = resolveBaseUrls(rootOpts, cfg);
-    
+
     if (opts.debug) {
       console.log(`Debug: Resolved API base URL: ${apiBaseUrl}`);
       console.log(`Debug: Resolved UI base URL: ${uiBaseUrl}`);
     }
-    
+
     try {
       // Step 1: Start local callback server FIRST to get actual port
       console.log("Starting local callback server...");
       const requestedPort = opts.port || 0; // 0 = OS assigns available port
       const callbackServer = authServer.createCallbackServer(requestedPort, params.state, 120000); // 2 minute timeout
-      
+
       // Wait a bit for server to start and get port
       await new Promise(resolve => setTimeout(resolve, 100));
       const actualPort = callbackServer.getPort();
       const redirectUri = `http://localhost:${actualPort}/callback`;
-      
+
       console.log(`Callback server listening on port ${actualPort}`);
-      
+
       // Step 2: Initialize OAuth session on backend
       console.log("Initializing authentication session...");
       const initData = JSON.stringify({
@@ -804,15 +1120,15 @@ program
         code_challenge_method: params.codeChallengeMethod,
         redirect_uri: redirectUri,
       });
-      
+
       // Build init URL by appending to the API base path (keep /api/general)
       const initUrl = new URL(`${apiBaseUrl}/rpc/oauth_init`);
-      
+
       if (opts.debug) {
         console.log(`Debug: Trying to POST to: ${initUrl.toString()}`);
         console.log(`Debug: Request data: ${initData}`);
       }
-      
+
       const initReq = http.request(
         initUrl,
         {
@@ -828,7 +1144,7 @@ program
           res.on("end", async () => {
             if (res.statusCode !== 200) {
               console.error(`Failed to initialize auth session: ${res.statusCode}`);
-              
+
               // Check if response is HTML (common for 404 pages)
               if (data.trim().startsWith("<!") || data.trim().startsWith("<html")) {
                 console.error("Error: Received HTML response instead of JSON. This usually means:");
@@ -839,31 +1155,31 @@ program
               } else {
                 console.error(data);
               }
-              
+
               callbackServer.server.close();
               process.exit(1);
             }
-            
+
             // Step 3: Open browser
             const authUrl = `${uiBaseUrl}/cli/auth?state=${encodeURIComponent(params.state)}&code_challenge=${encodeURIComponent(params.codeChallenge)}&code_challenge_method=S256&redirect_uri=${encodeURIComponent(redirectUri)}`;
-            
+
             if (opts.debug) {
               console.log(`Debug: Auth URL: ${authUrl}`);
             }
-            
+
             console.log(`\nOpening browser for authentication...`);
             console.log(`If browser does not open automatically, visit:\n${authUrl}\n`);
-            
+
             // Open browser (cross-platform)
             const openCommand = process.platform === "darwin" ? "open" :
                                process.platform === "win32" ? "start" :
                                "xdg-open";
             spawn(openCommand, [authUrl], { detached: true, stdio: "ignore" }).unref();
-            
+
             // Step 4: Wait for callback
             console.log("Waiting for authorization...");
             console.log("(Press Ctrl+C to cancel)\n");
-            
+
             // Handle Ctrl+C gracefully
             const cancelHandler = () => {
               console.log("\n\nAuthentication cancelled by user.");
@@ -871,13 +1187,13 @@ program
               process.exit(130); // Standard exit code for SIGINT
             };
             process.on("SIGINT", cancelHandler);
-            
+
             try {
               const { code } = await callbackServer.promise;
-              
+
               // Remove the cancel handler after successful auth
               process.off("SIGINT", cancelHandler);
-              
+
               // Step 5: Exchange code for token
               console.log("\nExchanging authorization code for API token...");
               const exchangeData = JSON.stringify({
@@ -901,7 +1217,7 @@ program
                   exchangeRes.on("end", () => {
                     if (exchangeRes.statusCode !== 200) {
                       console.error(`Failed to exchange code for token: ${exchangeRes.statusCode}`);
-                      
+
                       // Check if response is HTML (common for 404 pages)
                       if (exchangeBody.trim().startsWith("<!") || exchangeBody.trim().startsWith("<html")) {
                         console.error("Error: Received HTML response instead of JSON. This usually means:");
@@ -912,23 +1228,23 @@ program
                       } else {
                         console.error(exchangeBody);
                       }
-                      
+
                       process.exit(1);
                       return;
                     }
-                    
+
                     try {
                       const result = JSON.parse(exchangeBody);
                       const apiToken = result.api_token || result?.[0]?.result?.api_token; // There is a bug with PostgREST Caching that may return an array, not single object, it's a workaround to support both cases.
                       const orgId = result.org_id || result?.[0]?.result?.org_id; // There is a bug with PostgREST Caching that may return an array, not single object, it's a workaround to support both cases.
-                      
+
                       // Step 6: Save token to config
                       config.writeConfig({
                         apiKey: apiToken,
                         baseUrl: apiBaseUrl,
                         orgId: orgId,
                       });
-                      
+
                       console.log("\nAuthentication successful!");
                       console.log(`API key saved to: ${config.getConfigPath()}`);
                       console.log(`Organization ID: ${orgId}`);
@@ -942,21 +1258,21 @@ program
                   });
                 }
               );
-              
+
               exchangeReq.on("error", (err: Error) => {
                 console.error(`Exchange request failed: ${err.message}`);
                 process.exit(1);
               });
-              
+
               exchangeReq.write(exchangeData);
               exchangeReq.end();
-              
+
             } catch (err) {
               // Remove the cancel handler in error case too
               process.off("SIGINT", cancelHandler);
-              
+
               const message = err instanceof Error ? err.message : String(err);
-              
+
               // Provide more helpful error messages
               if (message.includes("timeout")) {
                 console.error(`\nAuthentication timed out.`);
@@ -965,22 +1281,22 @@ program
               } else {
                 console.error(`\nAuthentication failed: ${message}`);
               }
-              
+
               process.exit(1);
             }
           });
         }
       );
-      
+
       initReq.on("error", (err: Error) => {
         console.error(`Failed to connect to API: ${err.message}`);
         callbackServer.server.close();
         process.exit(1);
       });
-      
+
       initReq.write(initData);
       initReq.end();
-      
+
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       console.error(`Authentication error: ${message}`);
@@ -1023,17 +1339,17 @@ program
     const hasNewConfig = fs.existsSync(newConfigPath);
     const legacyPath = path.resolve(process.cwd(), ".pgwatch-config");
     const hasLegacyConfig = fs.existsSync(legacyPath) && fs.statSync(legacyPath).isFile();
-    
+
     if (!hasNewConfig && !hasLegacyConfig) {
       console.log("No API key configured");
       return;
     }
-    
+
     // Remove from new config
     if (hasNewConfig) {
       config.deleteConfigKeys(["apiKey", "orgId"]);
     }
-    
+
     // Remove from legacy config
     if (hasLegacyConfig) {
       try {
@@ -1049,7 +1365,7 @@ program
         console.warn(`Warning: Could not update legacy config: ${err instanceof Error ? err.message : String(err)}`);
       }
     }
-    
+
     console.log("API key removed");
     console.log(`\nTo authenticate again, run: pgai auth`);
   });
@@ -1058,20 +1374,20 @@ mon
   .description("generate Grafana password for monitoring services")
   .action(async () => {
     const cfgPath = path.resolve(process.cwd(), ".pgwatch-config");
-    
+
     try {
       // Generate secure password using openssl
       const { stdout: password } = await execPromise(
         "openssl rand -base64 12 | tr -d '\n'"
       );
       const newPassword = password.trim();
-      
+
       if (!newPassword) {
         console.error("Failed to generate password");
         process.exitCode = 1;
         return;
       }
-      
+
       // Read existing config
       let configContent = "";
       if (fs.existsSync(cfgPath)) {
@@ -1082,14 +1398,14 @@ mon
           configContent = fs.readFileSync(cfgPath, "utf8");
         }
       }
-      
+
       // Update or add grafana_password
       const lines = configContent.split(/\r?\n/).filter((l) => !/^grafana_password=/.test(l));
       lines.push(`grafana_password=${newPassword}`);
-      
+
       // Write back
       fs.writeFileSync(cfgPath, lines.filter(Boolean).join("\n") + "\n", "utf8");
-      
+
       console.log("✓ New Grafana password generated and saved");
       console.log("\nNew credentials:");
       console.log("  URL:      http://localhost:3000");
@@ -1114,14 +1430,14 @@ mon
       process.exitCode = 1;
       return;
     }
-    
+
     const stats = fs.statSync(cfgPath);
     if (stats.isDirectory()) {
       console.error(".pgwatch-config is a directory, expected a file. Cannot read credentials.");
       process.exitCode = 1;
       return;
     }
-    
+
     const content = fs.readFileSync(cfgPath, "utf8");
     const lines = content.split(/\r?\n/);
     let password = "";
@@ -1144,6 +1460,24 @@ mon
     console.log("");
   });
 
+/**
+ * Interpret escape sequences in a string (e.g., \n -> newline)
+ * Note: In regex, to match literal backslash-n, we need \\n in the pattern
+ * which requires \\\\n in the JavaScript string literal
+ */
+function interpretEscapes(str: string): string {
+  // First handle double backslashes by temporarily replacing them
+  // Then handle other escapes, then restore double backslashes as single
+  return str
+    .replace(/\\\\/g, '\x00') // Temporarily mark double backslashes
+    .replace(/\\n/g, '\n') // Match literal backslash-n (\\\\n in JS string -> \\n in regex -> matches \n)
+    .replace(/\\t/g, '\t')
+    .replace(/\\r/g, '\r')
+    .replace(/\\"/g, '"')
+    .replace(/\\'/g, "'")
+    .replace(/\x00/g, '\\'); // Restore double backslashes as single
+}
+
 // Issues management
 const issues = program.command("issues").description("issues management");
 
@@ -1151,7 +1485,8 @@ issues
   .command("list")
   .description("list issues")
   .option("--debug", "enable debug output")
-  .action(async (opts: { debug?: boolean }) => {
+  .option("--json", "output raw JSON")
+  .action(async (opts: { debug?: boolean; json?: boolean }) => {
     try {
       const rootOpts = program.opts<CliOptions>();
       const cfg = config.readConfig();
@@ -1165,12 +1500,96 @@ issues
       const { apiBaseUrl } = resolveBaseUrls(rootOpts, cfg);
 
       const result = await fetchIssues({ apiKey, apiBaseUrl, debug: !!opts.debug });
-      if (typeof result === "string") {
-        process.stdout.write(result);
-        if (!/\n$/.test(result)) console.log();
-      } else {
-        console.log(JSON.stringify(result, null, 2));
+      const trimmed = Array.isArray(result)
+        ? (result as any[]).map((r) => ({
+            id: (r as any).id,
+            title: (r as any).title,
+            status: (r as any).status,
+            created_at: (r as any).created_at,
+          }))
+        : result;
+      printResult(trimmed, opts.json);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(message);
+      process.exitCode = 1;
+    }
+  });
+
+issues
+  .command("view <issueId>")
+  .description("view issue details and comments")
+  .option("--debug", "enable debug output")
+  .option("--json", "output raw JSON")
+  .action(async (issueId: string, opts: { debug?: boolean; json?: boolean }) => {
+    try {
+      const rootOpts = program.opts<CliOptions>();
+      const cfg = config.readConfig();
+      const { apiKey } = getConfig(rootOpts);
+      if (!apiKey) {
+        console.error("API key is required. Run 'pgai auth' first or set --api-key.");
+        process.exitCode = 1;
+        return;
       }
+
+      const { apiBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+
+      const issue = await fetchIssue({ apiKey, apiBaseUrl, issueId, debug: !!opts.debug });
+      if (!issue) {
+        console.error("Issue not found");
+        process.exitCode = 1;
+        return;
+      }
+
+      const comments = await fetchIssueComments({ apiKey, apiBaseUrl, issueId, debug: !!opts.debug });
+      const combined = { issue, comments };
+      printResult(combined, opts.json);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(message);
+      process.exitCode = 1;
+    }
+  });
+
+issues
+  .command("post_comment <issueId> <content>")
+  .description("post a new comment to an issue")
+  .option("--parent <uuid>", "parent comment id")
+  .option("--debug", "enable debug output")
+  .option("--json", "output raw JSON")
+  .action(async (issueId: string, content: string, opts: { parent?: string; debug?: boolean; json?: boolean }) => {
+    try {
+      // Interpret escape sequences in content (e.g., \n -> newline)
+      if (opts.debug) {
+        // eslint-disable-next-line no-console
+        console.log(`Debug: Original content: ${JSON.stringify(content)}`);
+      }
+      content = interpretEscapes(content);
+      if (opts.debug) {
+        // eslint-disable-next-line no-console
+        console.log(`Debug: Interpreted content: ${JSON.stringify(content)}`);
+      }
+
+      const rootOpts = program.opts<CliOptions>();
+      const cfg = config.readConfig();
+      const { apiKey } = getConfig(rootOpts);
+      if (!apiKey) {
+        console.error("API key is required. Run 'pgai auth' first or set --api-key.");
+        process.exitCode = 1;
+        return;
+      }
+
+      const { apiBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+
+      const result = await createIssueComment({
+        apiKey,
+        apiBaseUrl,
+        issueId,
+        content,
+        parentCommentId: opts.parent,
+        debug: !!opts.debug,
+      });
+      printResult(result, opts.json);
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       console.error(message);
@@ -1195,7 +1614,7 @@ mcp
   .description("install MCP server configuration for AI coding tool")
   .action(async (client?: string) => {
     const supportedClients = ["cursor", "claude-code", "windsurf", "codex"];
-    
+
     // If no client specified, prompt user to choose
     if (!client) {
       console.log("Available AI coding tools:");
@@ -1204,24 +1623,24 @@ mcp
       console.log("  3. Windsurf");
       console.log("  4. Codex");
       console.log("");
-      
+
       const rl = readline.createInterface({
         input: process.stdin,
         output: process.stdout
       });
-      
+
       const answer = await new Promise<string>((resolve) => {
         rl.question("Select your AI coding tool (1-4): ", resolve);
       });
       rl.close();
-      
+
       const choices: Record<string, string> = {
         "1": "cursor",
         "2": "claude-code",
         "3": "windsurf",
         "4": "codex"
       };
-      
+
       client = choices[answer.trim()];
       if (!client) {
         console.error("Invalid selection");
@@ -1229,54 +1648,90 @@ mcp
         return;
       }
     }
-    
+
     client = client.toLowerCase();
-    
+
     if (!supportedClients.includes(client)) {
       console.error(`Unsupported client: ${client}`);
       console.error(`Supported clients: ${supportedClients.join(", ")}`);
       process.exitCode = 1;
       return;
     }
-    
+
     try {
+      // Get the path to the current pgai executable
+      let pgaiPath: string;
+      try {
+        const execPath = await execPromise("which pgai");
+        pgaiPath = execPath.stdout.trim();
+      } catch {
+        // Fallback to just "pgai" if which fails
+        pgaiPath = "pgai";
+      }
+
+      // Claude Code uses its own CLI to manage MCP servers
+      if (client === "claude-code") {
+        console.log("Installing PostgresAI MCP server for Claude Code...");
+
+        try {
+          const { stdout, stderr } = await execPromise(
+            `claude mcp add -s user postgresai ${pgaiPath} mcp start`
+          );
+
+          if (stdout) console.log(stdout);
+          if (stderr) console.error(stderr);
+
+          console.log("");
+          console.log("Successfully installed PostgresAI MCP server for Claude Code");
+          console.log("");
+          console.log("Next steps:");
+          console.log("  1. Restart Claude Code to load the new configuration");
+          console.log("  2. The PostgresAI MCP server will be available as 'postgresai'");
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          console.error("Failed to install MCP server using Claude CLI");
+          console.error(message);
+          console.error("");
+          console.error("Make sure the 'claude' CLI tool is installed and in your PATH");
+          console.error("See: https://docs.anthropic.com/en/docs/build-with-claude/mcp");
+          process.exitCode = 1;
+        }
+        return;
+      }
+
+      // For other clients (Cursor, Windsurf, Codex), use JSON config editing
       const homeDir = os.homedir();
       let configPath: string;
       let configDir: string;
-      
+
       // Determine config file location based on client
       switch (client) {
         case "cursor":
           configPath = path.join(homeDir, ".cursor", "mcp.json");
           configDir = path.dirname(configPath);
           break;
-        
-        case "claude-code":
-          configPath = path.join(homeDir, ".claude-code", "mcp.json");
-          configDir = path.dirname(configPath);
-          break;
-        
+
         case "windsurf":
           configPath = path.join(homeDir, ".windsurf", "mcp.json");
           configDir = path.dirname(configPath);
           break;
-        
+
         case "codex":
           configPath = path.join(homeDir, ".codex", "mcp.json");
           configDir = path.dirname(configPath);
           break;
-        
+
         default:
           console.error(`Configuration not implemented for: ${client}`);
           process.exitCode = 1;
           return;
       }
-      
+
       // Ensure config directory exists
       if (!fs.existsSync(configDir)) {
         fs.mkdirSync(configDir, { recursive: true });
       }
-      
+
       // Read existing config or create new one
       let config: any = { mcpServers: {} };
       if (fs.existsSync(configPath)) {
@@ -1290,21 +1745,21 @@ mcp
           console.error(`Warning: Could not parse existing config, creating new one`);
         }
       }
-      
+
       // Add or update PostgresAI MCP server configuration
       config.mcpServers.postgresai = {
-        command: "pgai",
+        command: pgaiPath,
         args: ["mcp", "start"]
       };
-      
+
       // Write updated config
       fs.writeFileSync(configPath, JSON.stringify(config, null, 2), "utf8");
-      
+
       console.log(`✓ PostgresAI MCP server configured for ${client}`);
       console.log(`  Config file: ${configPath}`);
       console.log("");
       console.log("Please restart your AI coding tool to activate the MCP server");
-      
+
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       console.error(`Failed to install MCP server: ${message}`);