postgresai 0.12.0-beta.7 → 0.14.0-beta.2

package/README.md

@@ -10,11 +10,13 @@ Command-line interface for PostgresAI monitoring and database management.
 npm install -g postgresai
 ```
 
-Or install the latest alpha release explicitly:
+Or install the latest beta release explicitly:
 ```bash
-npm install -g postgresai@alpha
+npm install -g postgresai@beta
 ```
 
+Note: in this repository, `cli/package.json` uses a placeholder version (`0.0.0-dev.0`). The real published version is set by the git tag in CI when publishing to npm.
+
 ### From Homebrew (macOS)
 
 ```bash
@@ -31,7 +33,70 @@ The CLI provides three command aliases:
 ```bash
 postgres-ai --help
 postgresai --help
-pgai --help  # short alias
+```
+
+You can also run it without installing via `npx`:
+
+```bash
+npx postgresai --help
+```
+
+## init (create monitoring user in Postgres)
+
+This command creates (or updates) the `postgres_ai_mon` user and grants the permissions described in the root `README.md` (it is idempotent).
+
+Run without installing (positional connection string):
+
+```bash
+npx postgresai init postgresql://admin@host:5432/dbname
+```
+
+It also accepts libpq “conninfo” syntax:
+
+```bash
+npx postgresai init "dbname=dbname host=host user=admin"
+```
+
+And psql-like options:
+
+```bash
+npx postgresai init -h host -p 5432 -U admin -d dbname
+```
+
+Password input options (in priority order):
+- `--password <password>`
+- `PGAI_MON_PASSWORD` environment variable
+- if not provided: a strong password is generated automatically
+
+By default, the generated password is printed **only in interactive (TTY) mode**. In non-interactive mode, you must either provide the password explicitly, or opt-in to printing it:
+- `--print-password` (dangerous in CI logs)
+
+Optional permissions (RDS/self-managed extras from the root `README.md`) are enabled by default. To skip them:
+
+```bash
+npx postgresai init postgresql://admin@host:5432/dbname --skip-optional-permissions
+```
+
+### Print SQL / dry run
+
+To see what SQL would be executed (passwords redacted by default):
+
+```bash
+npx postgresai init postgresql://admin@host:5432/dbname --print-sql
+```
+
+### Verify and password reset
+
+Verify that everything is configured as expected (no changes):
+
+```bash
+npx postgresai init postgresql://admin@host:5432/dbname --verify
+```
+
+Reset monitoring user password only (no other changes):
+
+```bash
+npx postgresai init postgresql://admin@host:5432/dbname --reset-password --password 'new_password'
 ```
 
 ## Quick start
@@ -40,7 +105,7 @@ pgai --help  # short alias
 
 Authenticate via browser to obtain API key:
 ```bash
-pgai auth
+postgresai auth
 ```
 
 This will:
@@ -122,7 +187,7 @@ postgres-ai mon shell <service>                # Open shell to monitoring servic
 ### MCP server (`mcp` group)
 
 ```bash
-pgai mcp start                 # Start MCP stdio server exposing tools
+postgresai mcp start                 # Start MCP stdio server exposing tools
 ```
 
 Cursor configuration example (Settings → MCP):
@@ -131,7 +196,7 @@ Cursor configuration example (Settings → MCP):
 {
   "mcpServers": {
     "PostgresAI": {
-      "command": "pgai",
+      "command": "postgresai",
       "args": ["mcp", "start"],
       "env": {
         "PGAI_API_BASE_URL": "https://postgres.ai/api/general/"
@@ -142,16 +207,16 @@ Cursor configuration example (Settings → MCP):
 ```
 
 Tools exposed:
-- list_issues: returns the same JSON as `pgai issues list`.
+- list_issues: returns the same JSON as `postgresai issues list`.
 - view_issue: view a single issue with its comments (args: { issue_id, debug? })
 - post_issue_comment: post a comment (args: { issue_id, content, parent_comment_id?, debug? })
 
 ### Issues management (`issues` group)
 
 ```bash
-pgai issues list                                  # List issues (shows: id, title, status, created_at)
-pgai issues view <issueId>                        # View issue details and comments
-pgai issues post_comment <issueId> <content>      # Post a comment to an issue
+postgresai issues list                                  # List issues (shows: id, title, status, created_at)
+postgresai issues view <issueId>                        # View issue details and comments
+postgresai issues post_comment <issueId> <content>      # Post a comment to an issue
 # Options:
 #   --parent <uuid>  Parent comment ID (for replies)
 #   --debug          Enable debug output
@@ -165,13 +230,13 @@ By default, issues commands print human-friendly YAML when writing to a terminal
 - Use `--json` to force JSON output:
 
 ```bash
-pgai issues list --json | jq '.[] | {id, title}'
+postgresai issues list --json | jq '.[] | {id, title}'
 ```
 
 - Rely on auto-detection: when stdout is not a TTY (e.g., piped or redirected), output is JSON automatically:
 
 ```bash
-pgai issues view <issueId> > issue.json
+postgresai issues view <issueId> > issue.json
 ```
 
 #### Grafana management
@@ -235,7 +300,7 @@ Linux/macOS (bash/zsh):
 ```bash
 export PGAI_API_BASE_URL=https://v2.postgres.ai/api/general/
 export PGAI_UI_BASE_URL=https://console-dev.postgres.ai
-pgai auth --debug
+postgresai auth --debug
 ```
 
 Windows PowerShell:
@@ -243,13 +308,13 @@ Windows PowerShell:
 ```powershell
 $env:PGAI_API_BASE_URL = "https://v2.postgres.ai/api/general/"
 $env:PGAI_UI_BASE_URL = "https://console-dev.postgres.ai"
-pgai auth --debug
+postgresai auth --debug
 ```
 
 Via CLI options (overrides env):
 
 ```bash
-pgai auth --debug \
+postgresai auth --debug \
   --api-base-url https://v2.postgres.ai/api/general/ \
   --ui-base-url https://console-dev.postgres.ai
 ```

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, fetchIssueComments, createIssueComment, fetchIssue } from "../lib/issues";
 import { resolveBaseUrls } from "../lib/util";
+import { applyInitPlan, buildInitPlan, DEFAULT_MONITORING_USER, redactPasswordsInSql, resolveAdminConnection, resolveMonitoringPassword, verifyInitSetup } from "../lib/init";
 
 const execPromise = promisify(exec);
 const execFilePromise = promisify(execFile);
@@ -116,6 +118,337 @@ 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", DEFAULT_MONITORING_USER)
+  .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",
+      "",
+      "Environment variables (libpq standard):",
+      "  PGHOST, PGPORT, PGUSER, PGDATABASE  — connection defaults",
+      "  PGPASSWORD                          — admin password",
+      "  PGAI_MON_PASSWORD                   — monitoring 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 redactPasswordsInSql(sql);
+    };
+
+    // 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,
+        });
+
+        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(`Error: init: ${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
+    let client: Client | undefined;
+    try {
+      client = new Client(adminConn.clientConfig);
+      await client.connect();
+
+      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) {
+            // Print secrets to stderr to reduce the chance they end up in piped stdout logs.
+            const shellSafe = monPassword.replace(/'/g, "'\\''");
+            console.error("");
+            console.error(`Generated monitoring password for ${opts.monitoringUser} (copy/paste):`);
+            // Quote for shell copy/paste safety.
+            console.error(`PGAI_MON_PASSWORD='${shellSafe}'`);
+            console.error("");
+            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,
+      });
+
+      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(`Error: init: ${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(`  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") {
+          if (failedStep === "01.role") {
+            console.error("  Context: role creation/update requires CREATEROLE or superuser");
+          } else if (failedStep === "02.permissions") {
+            console.error("  Context: grants/view/search_path require sufficient GRANT/DDL privileges");
+          }
+          console.error("  Fix: connect as a superuser (or a role with CREATEROLE and sufficient GRANT privileges)");
+          console.error("  Fix: on managed Postgres, use the provider's admin/master user");
+          console.error("  Tip: run with --print-sql to review the exact SQL plan");
+        }
+        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 {
+      if (client) {
+        try {
+          await client.end();
+        } catch {
+          // ignore
+        }
+      }
+    }
+  });
+
 /**
  * Stub function for not implemented commands
  */