postgresai 0.14.0-dev.13 → 0.14.0-dev.15

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
@@ -34,6 +36,13 @@ postgresai --help
 pgai --help  # short alias
 ```
 
+You can also run it without installing via `npx`:
+
+```bash
+npx postgresai --help
+npx pgai --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).
@@ -42,6 +51,7 @@ Run without installing (positional connection string):
 
 ```bash
 npx postgresai init postgresql://admin@host:5432/dbname
+npx pgai init postgresql://admin@host:5432/dbname
 ```
 
 It also accepts libpq “conninfo” syntax:

package/bin/postgres-ai.ts

@@ -16,7 +16,7 @@ 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, resolveAdminConnection, resolveMonitoringPassword, verifyInitSetup } from "../lib/init";
+import { applyInitPlan, buildInitPlan, DEFAULT_MONITORING_USER, redactPasswordsInSql, resolveAdminConnection, resolveMonitoringPassword, verifyInitSetup } from "../lib/init";
 
 const execPromise = promisify(exec);
 const execFilePromise = promisify(execFile);
@@ -127,7 +127,7 @@ 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", "postgres_ai_mon")
+  .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)
@@ -152,6 +152,11 @@ 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",
       "",
@@ -197,7 +202,7 @@ program
     const redactPasswords = (sql: string): string => {
       if (!shouldRedactSecrets) return sql;
       // Replace PASSWORD '<literal>' (handles doubled quotes inside).
-      return sql.replace(/password\s+'(?:''|[^'])*'/gi, "password '<redacted>'");
+      return redactPasswordsInSql(sql);
     };
 
     // Offline mode: allow printing SQL without providing/using an admin connection.
@@ -216,7 +221,6 @@ program
           monitoringUser: opts.monitoringUser,
           monitoringPassword: monPassword,
           includeOptionalPermissions,
-          roleExists: undefined,
         });
 
         console.log("\n--- SQL plan (offline; not connected) ---");
@@ -250,7 +254,7 @@ program
       });
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e);
-      console.error(`✗ ${msg}`);
+      console.error(`Error: ${msg}`);
       // When connection details are missing, show full init help (options + examples).
       if (typeof msg === "string" && msg.startsWith("Connection is required.")) {
         console.error("");
@@ -267,16 +271,11 @@ program
     console.log(`Optional permissions: ${includeOptionalPermissions ? "enabled" : "skipped"}`);
 
     // Use native pg client instead of requiring psql to be installed
-    const client = new Client(adminConn.clientConfig);
-
+    let client: Client | undefined;
     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) > 0;
-
       const dbRes = await client.query("select current_database() as db");
       const database = dbRes.rows?.[0]?.db;
       if (typeof database !== "string" || !database) {
@@ -319,7 +318,12 @@ program
         if (resolved.generated) {
           const canPrint = process.stdout.isTTY || !!opts.printPassword;
           if (canPrint) {
-            console.log(`Generated password for monitoring user ${opts.monitoringUser}: ${monPassword}`);
+            // Print secrets to stderr to reduce the chance they end up in piped stdout logs.
+            console.error("");
+            console.error(`Generated monitoring password for ${opts.monitoringUser} (copy/paste):`);
+            // Quote for shell copy/paste safety.
+            console.error(`PGAI_MON_PASSWORD='${monPassword}'`);
+            console.error("");
             console.log("Store it securely (or rerun with --password / PGAI_MON_PASSWORD to set your own).");
           } else {
             console.error(
@@ -349,7 +353,6 @@ program
         monitoringUser: opts.monitoringUser,
         monitoringPassword: monPassword,
         includeOptionalPermissions,
-        roleExists,
       });
 
       const effectivePlan = opts.resetPassword
@@ -393,38 +396,54 @@ program
       if (!message || message === "[object Object]") {
         message = "Unknown error";
       }
-      console.error(`✗ init failed: ${message}`);
+      console.error(`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}`);
+          console.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") {
-          console.error("Hint: connect as a superuser (or a role with CREATEROLE and sufficient GRANT privileges).");
+          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.");
+          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 {
-      try {
-        await client.end();
-      } catch {
-        // ignore
+      if (client) {
+        try {
+          await client.end();
+        } catch {
+          // ignore
+        }
       }
     }
   });

package/dist/bin/postgres-ai.js

@@ -109,7 +109,7 @@ 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", "postgres_ai_mon")
+    .option("--monitoring-user <name>", "Monitoring role name to create/update", init_1.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)
@@ -132,6 +132,11 @@ 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",
     "",
@@ -161,7 +166,7 @@ program
         if (!shouldRedactSecrets)
             return sql;
         // Replace PASSWORD '<literal>' (handles doubled quotes inside).
-        return sql.replace(/password\s+'(?:''|[^'])*'/gi, "password '<redacted>'");
+        return (0, init_1.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.
@@ -176,7 +181,6 @@ program
                 monitoringUser: opts.monitoringUser,
                 monitoringPassword: monPassword,
                 includeOptionalPermissions,
-                roleExists: undefined,
             });
             console.log("\n--- SQL plan (offline; not connected) ---");
             console.log(`-- database: ${database}`);
@@ -209,7 +213,7 @@ program
     }
     catch (e) {
         const msg = e instanceof Error ? e.message : String(e);
-        console.error(`✗ ${msg}`);
+        console.error(`Error: ${msg}`);
         // When connection details are missing, show full init help (options + examples).
         if (typeof msg === "string" && msg.startsWith("Connection is required.")) {
             console.error("");
@@ -223,13 +227,10 @@ program
     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 pg_1.Client(adminConn.clientConfig);
+    let client;
     try {
+        client = new pg_1.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) > 0;
         const dbRes = await client.query("select current_database() as db");
         const database = dbRes.rows?.[0]?.db;
         if (typeof database !== "string" || !database) {
@@ -273,7 +274,12 @@ program
             if (resolved.generated) {
                 const canPrint = process.stdout.isTTY || !!opts.printPassword;
                 if (canPrint) {
-                    console.log(`Generated password for monitoring user ${opts.monitoringUser}: ${monPassword}`);
+                    // Print secrets to stderr to reduce the chance they end up in piped stdout logs.
+                    console.error("");
+                    console.error(`Generated monitoring password for ${opts.monitoringUser} (copy/paste):`);
+                    // Quote for shell copy/paste safety.
+                    console.error(`PGAI_MON_PASSWORD='${monPassword}'`);
+                    console.error("");
                     console.log("Store it securely (or rerun with --password / PGAI_MON_PASSWORD to set your own).");
                 }
                 else {
@@ -302,7 +308,6 @@ program
             monitoringUser: opts.monitoringUser,
             monitoringPassword: monPassword,
             includeOptionalPermissions,
-            roleExists,
         });
         const effectivePlan = opts.resetPassword
             ? { ...plan, steps: plan.steps.filter((s) => s.name === "01.role") }
@@ -346,40 +351,56 @@ program
         if (!message || message === "[object Object]") {
             message = "Unknown error";
         }
-        console.error(`✗ init failed: ${message}`);
+        console.error(`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}`);
+                console.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") {
-                console.error("Hint: connect as a superuser (or a role with CREATEROLE and sufficient GRANT privileges).");
+                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.");
+                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 {
-        try {
-            await client.end();
-        }
-        catch {
-            // ignore
+        if (client) {
+            try {
+                await client.end();
+            }
+            catch {
+                // ignore
+            }
         }
     }
 });