postgresai 0.14.0-beta.3 → 0.14.0-dev.11

package/README.md

@@ -10,13 +10,11 @@ Command-line interface for PostgresAI monitoring and database management.
 npm install -g postgresai
 ```
 
-Or install the latest beta release explicitly:
+Or install the latest alpha release explicitly:
 ```bash
-npm install -g postgresai@beta
+npm install -g postgresai@alpha
 ```
 
-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
@@ -29,24 +27,11 @@ brew install postgresai
 
 ## Usage
 
-The `postgresai` package provides two command aliases (prefer `postgresai`):
+The CLI provides three command aliases:
 ```bash
 postgres-ai --help
 postgresai --help
-```
-
-You can also run it without installing via `npx`:
-
-```bash
-npx postgresai --help
-```
-
-### Optional shorthand: `pgai`
-
-If you want `npx pgai ...` as a shorthand for `npx postgresai ...`, install the separate `pgai` wrapper package:
-
-```bash
-npx pgai --help
+pgai --help  # short alias
 ```
 
 ## init (create monitoring user in Postgres)
@@ -93,18 +78,10 @@ To see what SQL would be executed (passwords redacted by default):
 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):
+To print SQL and exit without applying anything:
 
 ```bash
-npx postgresai init postgresql://admin@host:5432/dbname --reset-password --password 'new_password'
+npx postgresai init postgresql://admin@host:5432/dbname --dry-run
 ```
 
 ## Quick start
@@ -113,7 +90,7 @@ npx postgresai init postgresql://admin@host:5432/dbname --reset-password --passw
 
 Authenticate via browser to obtain API key:
 ```bash
-postgresai auth
+pgai auth
 ```
 
 This will:
@@ -195,7 +172,7 @@ postgres-ai mon shell <service>                # Open shell to monitoring servic
 ### MCP server (`mcp` group)
 
 ```bash
-postgresai mcp start                 # Start MCP stdio server exposing tools
+pgai mcp start                 # Start MCP stdio server exposing tools
 ```
 
 Cursor configuration example (Settings → MCP):
@@ -204,7 +181,7 @@ Cursor configuration example (Settings → MCP):
 {
   "mcpServers": {
     "PostgresAI": {
-      "command": "postgresai",
+      "command": "pgai",
       "args": ["mcp", "start"],
       "env": {
         "PGAI_API_BASE_URL": "https://postgres.ai/api/general/"
@@ -215,16 +192,16 @@ Cursor configuration example (Settings → MCP):
 ```
 
 Tools exposed:
-- list_issues: returns the same JSON as `postgresai issues list`.
+- list_issues: returns the same JSON as `pgai 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
-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
+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
 # Options:
 #   --parent <uuid>  Parent comment ID (for replies)
 #   --debug          Enable debug output
@@ -238,13 +215,13 @@ By default, issues commands print human-friendly YAML when writing to a terminal
 - Use `--json` to force JSON output:
 
 ```bash
-postgresai issues list --json | jq '.[] | {id, title}'
+pgai 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
-postgresai issues view <issueId> > issue.json
+pgai issues view <issueId> > issue.json
 ```
 
 #### Grafana management
@@ -308,7 +285,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
-postgresai auth --debug
+pgai auth --debug
 ```
 
 Windows PowerShell:
@@ -316,13 +293,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"
-postgresai auth --debug
+pgai auth --debug
 ```
 
 Via CLI options (overrides env):
 
 ```bash
-postgresai auth --debug \
+pgai 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,11 +12,10 @@ 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";
+import { applyInitPlan, buildInitPlan, resolveAdminConnection, resolveMonitoringPassword } from "../lib/init";
 
 const execPromise = promisify(exec);
 const execFilePromise = promisify(execFile);
@@ -127,13 +126,13 @@ program
   .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("--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("--print-sql", "Print SQL plan before applying (does not exit; use --dry-run to exit)", 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)
+  .option("--dry-run", "Print SQL steps and exit without applying changes", false)
   .addHelpText(
     "after",
     [
@@ -151,22 +150,8 @@ program
       "  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",
+      "  postgresai init <conn> --dry-run",
     ].join("\n")
   )
   .action(async (conn: string | undefined, opts: {
@@ -179,58 +164,11 @@ program
     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 redactPasswords = (sql: string): string => redactPasswordsInSql(sql);
-
-    // Offline mode: allow printing SQL without providing/using an admin connection.
-    // Useful for audits/reviews; caller can provide -d/PGDATABASE.
-    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.
-        // Printed SQL always redacts secrets.
-        const monPassword =
-          (opts.password ?? process.env.PGAI_MON_PASSWORD ?? "<redacted>").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");
-        console.log("Note: passwords are redacted in the printed SQL output.");
-        return;
-      }
-    }
-
+    dryRun?: boolean;
+  }) => {
     let adminConn;
     try {
       adminConn = resolveAdminConnection({
@@ -246,12 +184,7 @@ program
       });
     } 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 });
-      }
+      console.error(`✗ ${msg}`);
       process.exitCode = 1;
       return;
     }
@@ -262,43 +195,26 @@ program
     console.log(`Monitoring user: ${opts.monitoringUser}`);
     console.log(`Optional permissions: ${includeOptionalPermissions ? "enabled" : "skipped"}`);
 
+    const shouldPrintSql = !!opts.printSql || !!opts.dryRun;
+
     // Use native pg client instead of requiring psql to be installed
-    let client: Client | undefined;
+    const { Client } = require("pg");
+    const client = new Client(adminConn.clientConfig);
+
     try {
-      client = new Client(adminConn.clientConfig);
       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;
+
       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({
@@ -310,13 +226,7 @@ program
         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(`Generated password for monitoring user ${opts.monitoringUser}: ${monPassword}`);
             console.log("Store it securely (or rerun with --password / PGAI_MON_PASSWORD to set your own).");
           } else {
             console.error(
@@ -346,26 +256,36 @@ program
         monitoringUser: opts.monitoringUser,
         monitoringPassword: monPassword,
         includeOptionalPermissions,
+        roleExists,
       });
 
-      const effectivePlan = opts.resetPassword
-        ? { ...plan, steps: plan.steps.filter((s) => s.name === "01.role") }
-        : plan;
-
       if (shouldPrintSql) {
+        const redact = !opts.showSecrets;
+        const redactPasswords = (sql: string): string => {
+          if (!redact) return sql;
+          // Replace PASSWORD '<literal>' (handles doubled quotes inside).
+          return sql.replace(/password\s+'(?:''|[^'])*'/gi, "password '<redacted>'");
+        };
+
         console.log("\n--- SQL plan ---");
-        for (const step of effectivePlan.steps) {
+        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");
-              console.log("Note: passwords are redacted in the printed SQL output.");
+        if (redact) {
+          console.log("Note: passwords are redacted in the printed SQL (use --show-secrets to print them).");
+        }
+      }
+
+      if (opts.dryRun) {
+        console.log("✓ dry-run completed (no changes were applied)");
         return;
       }
 
-      const { applied, skippedOptional } = await applyInitPlan({ client, plan: effectivePlan });
+      const { applied, skippedOptional } = await applyInitPlan({ client, plan });
 
-      console.log(opts.resetPassword ? "✓ init password reset completed" : "✓ init completed");
+      console.log("✓ 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}`);
@@ -387,54 +307,38 @@ program
       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}`);
-      }
+      console.error(`✗ init failed: ${message}`);
       if (errAny && typeof errAny === "object") {
         if (typeof errAny.code === "string" && errAny.code) {
-          console.error(`  Code: ${errAny.code}`);
+          console.error(`Error code: ${errAny.code}`);
         }
         if (typeof errAny.detail === "string" && errAny.detail) {
-          console.error(`  Detail: ${errAny.detail}`);
+          console.error(`Detail: ${errAny.detail}`);
         }
         if (typeof errAny.hint === "string" && errAny.hint) {
-          console.error(`  Hint: ${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");
+          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");
+          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");
+          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");
+          console.error("Hint: connection timed out; check network/firewall rules.");
         }
       }
       process.exitCode = 1;
     } finally {
-      if (client) {
-        try {
-          await client.end();
-        } catch {
-          // ignore
-        }
+      try {
+        await client.end();
+      } catch {
+        // ignore
       }
     }
   });