postgresai 0.12.0-beta.6 → 0.14.0-beta.1

package/bin/postgres-ai.ts

@@ -12,9 +12,11 @@ import { promisify } from "util";
 import * as readline from "readline";
 import * as http from "https";
 import { URL } from "url";
+import { Client } from "pg";
 import { startMcpServer } from "../lib/mcp-server";
-import { fetchIssues } from "../lib/issues";
+import { fetchIssues, fetchIssueComments, createIssueComment, fetchIssue } from "../lib/issues";
 import { resolveBaseUrls } from "../lib/util";
+import { applyInitPlan, buildInitPlan, resolveAdminConnection, resolveMonitoringPassword, verifyInitSetup } from "../lib/init";
 
 const execPromise = promisify(exec);
 const execFilePromise = promisify(execFile);
@@ -59,14 +61,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 +84,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
@@ -106,6 +118,339 @@ program
     "UI base URL for browser routes (overrides PGAI_UI_BASE_URL)"
   );
 
+program
+  .command("init [conn]")
+  .description("Create a monitoring user and grant all required permissions (idempotent)")
+  .option("--db-url <url>", "PostgreSQL connection URL (admin) to run the setup against (deprecated; pass it as positional arg)")
+  .option("-h, --host <host>", "PostgreSQL host (psql-like)")
+  .option("-p, --port <port>", "PostgreSQL port (psql-like)")
+  .option("-U, --username <username>", "PostgreSQL user (psql-like)")
+  .option("-d, --dbname <dbname>", "PostgreSQL database name (psql-like)")
+  .option("--admin-password <password>", "Admin connection password (otherwise uses PGPASSWORD if set)")
+  .option("--monitoring-user <name>", "Monitoring role name to create/update", "postgres_ai_mon")
+  .option("--password <password>", "Monitoring role password (overrides PGAI_MON_PASSWORD)")
+  .option("--skip-optional-permissions", "Skip optional permissions (RDS/self-managed extras)", false)
+  .option("--verify", "Verify that monitoring role/permissions are in place (no changes)", false)
+  .option("--reset-password", "Reset monitoring role password only (no other changes)", false)
+  .option("--print-sql", "Print SQL plan and exit (no changes applied)", false)
+  .option("--show-secrets", "When printing SQL, do not redact secrets (DANGEROUS)", false)
+  .option("--print-password", "Print generated monitoring password (DANGEROUS in CI logs)", false)
+  .addHelpText(
+    "after",
+    [
+      "",
+      "Examples:",
+      "  postgresai init postgresql://admin@host:5432/dbname",
+      "  postgresai init \"dbname=dbname host=host user=admin\"",
+      "  postgresai init -h host -p 5432 -U admin -d dbname",
+      "",
+      "Admin password:",
+      "  --admin-password <password>   or  PGPASSWORD=... (libpq standard)",
+      "",
+      "Monitoring password:",
+      "  --password <password>         or  PGAI_MON_PASSWORD=...  (otherwise auto-generated)",
+      "  If auto-generated, it is printed only on TTY by default.",
+      "  To print it in non-interactive mode: --print-password",
+      "",
+      "Inspect SQL without applying changes:",
+      "  postgresai init <conn> --print-sql",
+      "",
+      "Verify setup (no changes):",
+      "  postgresai init <conn> --verify",
+      "",
+      "Reset monitoring password only:",
+      "  postgresai init <conn> --reset-password --password '...'",
+      "",
+      "Offline SQL plan (no DB connection):",
+      "  postgresai init --print-sql -d dbname --password '...' --show-secrets",
+    ].join("\n")
+  )
+  .action(async (conn: string | undefined, opts: {
+    dbUrl?: string;
+    host?: string;
+    port?: string;
+    username?: string;
+    dbname?: string;
+    adminPassword?: string;
+    monitoringUser: string;
+    password?: string;
+    skipOptionalPermissions?: boolean;
+    verify?: boolean;
+    resetPassword?: boolean;
+    printSql?: boolean;
+    showSecrets?: boolean;
+    printPassword?: boolean;
+  }, cmd: Command) => {
+    if (opts.verify && opts.resetPassword) {
+      console.error("✗ Provide only one of --verify or --reset-password");
+      process.exitCode = 1;
+      return;
+    }
+    if (opts.verify && opts.printSql) {
+      console.error("✗ --verify cannot be combined with --print-sql");
+      process.exitCode = 1;
+      return;
+    }
+
+    const shouldPrintSql = !!opts.printSql;
+    const shouldRedactSecrets = !opts.showSecrets;
+    const redactPasswords = (sql: string): string => {
+      if (!shouldRedactSecrets) return sql;
+      // Replace PASSWORD '<literal>' (handles doubled quotes inside).
+      return sql.replace(/password\s+'(?:''|[^'])*'/gi, "password '<redacted>'");
+    };
+
+    // Offline mode: allow printing SQL without providing/using an admin connection.
+    // Useful for audits/reviews; caller can provide -d/PGDATABASE and an explicit monitoring password.
+    if (!conn && !opts.dbUrl && !opts.host && !opts.port && !opts.username && !opts.adminPassword) {
+      if (shouldPrintSql) {
+        const database = (opts.dbname ?? process.env.PGDATABASE ?? "postgres").trim();
+        const includeOptionalPermissions = !opts.skipOptionalPermissions;
+
+        // Use explicit password/env if provided; otherwise use a placeholder (will be redacted unless --show-secrets).
+        const monPassword =
+          (opts.password ?? process.env.PGAI_MON_PASSWORD ?? "CHANGE_ME").toString();
+
+        const plan = await buildInitPlan({
+          database,
+          monitoringUser: opts.monitoringUser,
+          monitoringPassword: monPassword,
+          includeOptionalPermissions,
+          roleExists: undefined,
+        });
+
+        console.log("\n--- SQL plan (offline; not connected) ---");
+        console.log(`-- database: ${database}`);
+        console.log(`-- monitoring user: ${opts.monitoringUser}`);
+        console.log(`-- optional permissions: ${includeOptionalPermissions ? "enabled" : "skipped"}`);
+        for (const step of plan.steps) {
+          console.log(`\n-- ${step.name}${step.optional ? " (optional)" : ""}`);
+          console.log(redactPasswords(step.sql));
+        }
+        console.log("\n--- end SQL plan ---\n");
+        if (shouldRedactSecrets) {
+          console.log("Note: passwords are redacted in the printed SQL (use --show-secrets to print them).");
+        }
+        return;
+      }
+    }
+
+    let adminConn;
+    try {
+      adminConn = resolveAdminConnection({
+        conn,
+        dbUrlFlag: opts.dbUrl,
+        // Allow libpq standard env vars as implicit defaults (common UX).
+        host: opts.host ?? process.env.PGHOST,
+        port: opts.port ?? process.env.PGPORT,
+        username: opts.username ?? process.env.PGUSER,
+        dbname: opts.dbname ?? process.env.PGDATABASE,
+        adminPassword: opts.adminPassword,
+        envPassword: process.env.PGPASSWORD,
+      });
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      console.error(`✗ ${msg}`);
+      // When connection details are missing, show full init help (options + examples).
+      if (typeof msg === "string" && msg.startsWith("Connection is required.")) {
+        console.error("");
+        cmd.outputHelp({ error: true });
+      }
+      process.exitCode = 1;
+      return;
+    }
+
+    const includeOptionalPermissions = !opts.skipOptionalPermissions;
+
+    console.log(`Connecting to: ${adminConn.display}`);
+    console.log(`Monitoring user: ${opts.monitoringUser}`);
+    console.log(`Optional permissions: ${includeOptionalPermissions ? "enabled" : "skipped"}`);
+
+    // Use native pg client instead of requiring psql to be installed
+    const client = new Client(adminConn.clientConfig);
+
+    try {
+      await client.connect();
+
+      const roleRes = await client.query("select 1 from pg_catalog.pg_roles where rolname = $1", [
+        opts.monitoringUser,
+      ]);
+      const roleExists = (roleRes.rowCount ?? 0) > 0;
+
+      const dbRes = await client.query("select current_database() as db");
+      const database = dbRes.rows?.[0]?.db;
+      if (typeof database !== "string" || !database) {
+        throw new Error("Failed to resolve current database name");
+      }
+
+      if (opts.verify) {
+        const v = await verifyInitSetup({
+          client,
+          database,
+          monitoringUser: opts.monitoringUser,
+          includeOptionalPermissions,
+        });
+        if (v.ok) {
+          console.log("✓ init verify: OK");
+          if (v.missingOptional.length > 0) {
+            console.log("⚠ Optional items missing:");
+            for (const m of v.missingOptional) console.log(`- ${m}`);
+          }
+          return;
+        }
+        console.error("✗ init verify failed: missing required items");
+        for (const m of v.missingRequired) console.error(`- ${m}`);
+        if (v.missingOptional.length > 0) {
+          console.error("Optional items missing:");
+          for (const m of v.missingOptional) console.error(`- ${m}`);
+        }
+        process.exitCode = 1;
+        return;
+      }
+
+      let monPassword: string;
+      try {
+        const resolved = await resolveMonitoringPassword({
+          passwordFlag: opts.password,
+          passwordEnv: process.env.PGAI_MON_PASSWORD,
+          monitoringUser: opts.monitoringUser,
+        });
+        monPassword = resolved.password;
+        if (resolved.generated) {
+          const canPrint = process.stdout.isTTY || !!opts.printPassword;
+          if (canPrint) {
+            console.log("");
+            console.log(`Generated monitoring password for ${opts.monitoringUser} (copy/paste):`);
+            console.log(`PGAI_MON_PASSWORD=${monPassword}`);
+            console.log("");
+            console.log("Store it securely (or rerun with --password / PGAI_MON_PASSWORD to set your own).");
+          } else {
+            console.error(
+              [
+                `✗ Monitoring password was auto-generated for ${opts.monitoringUser} but not printed in non-interactive mode.`,
+                "",
+                "Provide it explicitly:",
+                "  --password <password>   or   PGAI_MON_PASSWORD=...",
+                "",
+                "Or (NOT recommended) print the generated password:",
+                "  --print-password",
+              ].join("\n")
+            );
+            process.exitCode = 1;
+            return;
+          }
+        }
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        console.error(`✗ ${msg}`);
+        process.exitCode = 1;
+        return;
+      }
+
+      const plan = await buildInitPlan({
+        database,
+        monitoringUser: opts.monitoringUser,
+        monitoringPassword: monPassword,
+        includeOptionalPermissions,
+        roleExists,
+      });
+
+      const effectivePlan = opts.resetPassword
+        ? { ...plan, steps: plan.steps.filter((s) => s.name === "01.role") }
+        : plan;
+
+      if (shouldPrintSql) {
+        console.log("\n--- SQL plan ---");
+        for (const step of effectivePlan.steps) {
+          console.log(`\n-- ${step.name}${step.optional ? " (optional)" : ""}`);
+          console.log(redactPasswords(step.sql));
+        }
+        console.log("\n--- end SQL plan ---\n");
+        if (shouldRedactSecrets) {
+          console.log("Note: passwords are redacted in the printed SQL (use --show-secrets to print them).");
+        }
+        return;
+      }
+
+      const { applied, skippedOptional } = await applyInitPlan({ client, plan: effectivePlan });
+
+      console.log(opts.resetPassword ? "✓ init password reset completed" : "✓ init completed");
+      if (skippedOptional.length > 0) {
+        console.log("⚠ Some optional steps were skipped (not supported or insufficient privileges):");
+        for (const s of skippedOptional) console.log(`- ${s}`);
+      }
+      // Keep output compact but still useful
+      if (process.stdout.isTTY) {
+        console.log(`Applied ${applied.length} steps`);
+      }
+    } catch (error) {
+      const errAny = error as any;
+      let message = "";
+      if (error instanceof Error && error.message) {
+        message = error.message;
+      } else if (errAny && typeof errAny === "object" && typeof errAny.message === "string" && errAny.message) {
+        message = errAny.message;
+      } else {
+        message = String(error);
+      }
+      if (!message || message === "[object Object]") {
+        message = "Unknown error";
+      }
+      console.error(`✗ init failed: ${message}`);
+      // If this was a plan step failure, surface the step name explicitly to help users diagnose quickly.
+      const stepMatch =
+        typeof message === "string" ? message.match(/Failed at step "([^"]+)":/i) : null;
+      const failedStep = stepMatch?.[1];
+      if (failedStep) {
+        console.error(`Step: ${failedStep}`);
+      }
+      if (errAny && typeof errAny === "object") {
+        if (typeof errAny.code === "string" && errAny.code) {
+          console.error(`Error code: ${errAny.code}`);
+        }
+        if (typeof errAny.detail === "string" && errAny.detail) {
+          console.error(`Detail: ${errAny.detail}`);
+        }
+        if (typeof errAny.hint === "string" && errAny.hint) {
+          console.error(`Hint: ${errAny.hint}`);
+        }
+      }
+      if (errAny && typeof errAny === "object" && typeof errAny.code === "string") {
+        if (errAny.code === "42501") {
+          console.error("");
+          console.error("Permission error: your admin connection is not allowed to complete the setup.");
+          if (failedStep === "01.role") {
+            console.error("What failed: create/update the monitoring role (needs CREATEROLE or superuser).");
+          } else if (failedStep === "02.permissions") {
+            console.error("What failed: grant required permissions / create view / set role search_path.");
+          }
+          console.error("How to fix:");
+          console.error("- Connect as a superuser (or a role with CREATEROLE and sufficient GRANT privileges).");
+          console.error("- On managed Postgres, use the provider's admin/master user.");
+          console.error("Tip: run with --print-sql to review the exact SQL plan.");
+          console.error("");
+          console.error("Hint: connect as a superuser (or a role with CREATEROLE and sufficient GRANT privileges).");
+        }
+        if (errAny.code === "ECONNREFUSED") {
+          console.error("Hint: check host/port and ensure Postgres is reachable from this machine.");
+        }
+        if (errAny.code === "ENOTFOUND") {
+          console.error("Hint: DNS resolution failed; double-check the host name.");
+        }
+        if (errAny.code === "ETIMEDOUT") {
+          console.error("Hint: connection timed out; check network/firewall rules.");
+        }
+      }
+      process.exitCode = 1;
+    } finally {
+      try {
+        await client.end();
+      } catch {
+        // ignore
+      }
+    }
+  });
+
 /**
  * Stub function for not implemented commands
  */
@@ -249,23 +594,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
@@ -328,11 +958,13 @@ 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;
@@ -350,20 +982,16 @@ mon
       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 { execSync } = require("child_process");
+          const status = execSync(`docker inspect -f '{{.State.Status}}' ${service.container} 2>/dev/null`, {
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe']
+          }).trim();
 
-          const response = await fetch(service.url, {
-            signal: controller.signal,
-            method: 'GET',
-          });
-          clearTimeout(timeoutId);
-
-          if (response.status === 200) {
+          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) {
@@ -1167,6 +1795,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");
 
@@ -1174,7 +1820,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();
@@ -1188,12 +1835,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);