postgresai 0.14.0-dev.10 → 0.14.0-dev.12

package/README.md

@@ -59,7 +59,10 @@ 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 and printed once
+- 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:
 
@@ -75,10 +78,18 @@ To see what SQL would be executed (passwords redacted by default):
 npx postgresai init postgresql://admin@host:5432/dbname --print-sql
 ```
 
-To print SQL and exit without applying anything:
+### 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 --dry-run
+npx postgresai init postgresql://admin@host:5432/dbname --reset-password --password 'new_password'
 ```
 
 ## Quick start

package/bin/postgres-ai.ts

@@ -12,10 +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, resolveAdminConnection, resolveMonitoringPassword } from "../lib/init";
+import { applyInitPlan, buildInitPlan, resolveAdminConnection, resolveMonitoringPassword, verifyInitSetup } from "../lib/init";
 
 const execPromise = promisify(exec);
 const execFilePromise = promisify(execFile);
@@ -129,9 +130,41 @@ program
   .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("--print-sql", "Print SQL steps before applying (passwords redacted by default)", 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("--dry-run", "Print SQL steps and exit without applying changes", 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;
@@ -142,19 +175,76 @@ program
     monitoringUser: string;
     password?: string;
     skipOptionalPermissions?: boolean;
+    verify?: boolean;
+    resetPassword?: boolean;
     printSql?: boolean;
     showSecrets?: boolean;
-    dryRun?: boolean;
+    printPassword?: boolean;
   }) => {
+    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,
-        host: opts.host,
-        port: opts.port,
-        username: opts.username,
-        dbname: opts.dbname,
+        // 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,
       });
@@ -171,10 +261,7 @@ 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
-    const { Client } = require("pg");
     const client = new Client(adminConn.clientConfig);
 
     try {
@@ -183,7 +270,7 @@ program
       const roleRes = await client.query("select 1 from pg_catalog.pg_roles where rolname = $1", [
         opts.monitoringUser,
       ]);
-      const roleExists = roleRes.rowCount > 0;
+      const roleExists = (roleRes.rowCount ?? 0) > 0;
 
       const dbRes = await client.query("select current_database() as db");
       const database = dbRes.rows?.[0]?.db;
@@ -191,6 +278,31 @@ program
         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({
@@ -200,8 +312,25 @@ program
         });
         monPassword = resolved.password;
         if (resolved.generated) {
-          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).");
+          const canPrint = process.stdout.isTTY || !!opts.printPassword;
+          if (canPrint) {
+            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(
+              [
+                `✗ 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);
@@ -218,33 +347,26 @@ program
         roleExists,
       });
 
-      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>'");
-        };
+      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 plan.steps) {
+        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 (redact) {
+        if (shouldRedactSecrets) {
           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 });
+      const { applied, skippedOptional } = await applyInitPlan({ client, plan: effectivePlan });
 
-      console.log("✓ init completed");
+      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}`);
@@ -282,6 +404,15 @@ program
         if (errAny.code === "42501") {
           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 {

package/dist/bin/postgres-ai.js

@@ -46,6 +46,7 @@ const util_1 = require("util");
 const readline = __importStar(require("readline"));
 const http = __importStar(require("https"));
 const url_1 = require("url");
+const pg_1 = require("pg");
 const mcp_server_1 = require("../lib/mcp-server");
 const issues_1 = require("../lib/issues");
 const util_2 = require("../lib/util");
@@ -111,19 +112,97 @@ program
     .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("--print-sql", "Print SQL steps before applying (passwords redacted by default)", 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("--dry-run", "Print SQL steps and exit without applying changes", 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, opts) => {
+    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) => {
+        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 (0, init_1.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 = (0, init_1.resolveAdminConnection)({
             conn,
             dbUrlFlag: opts.dbUrl,
-            host: opts.host,
-            port: opts.port,
-            username: opts.username,
-            dbname: opts.dbname,
+            // 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,
         });
@@ -138,21 +217,46 @@ program
     console.log(`Connecting to: ${adminConn.display}`);
     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
-    const { Client } = require("pg");
-    const client = new Client(adminConn.clientConfig);
+    const client = new pg_1.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;
+        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 (0, init_1.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;
         try {
             const resolved = await (0, init_1.resolveMonitoringPassword)({
@@ -162,8 +266,24 @@ program
             });
             monPassword = resolved.password;
             if (resolved.generated) {
-                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).");
+                const canPrint = process.stdout.isTTY || !!opts.printPassword;
+                if (canPrint) {
+                    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([
+                        `✗ 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) {
@@ -179,30 +299,23 @@ program
             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) => {
-                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 plan.steps) {
+            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 (redact) {
+            if (shouldRedactSecrets) {
                 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 (0, init_1.applyInitPlan)({ client, plan });
-        console.log("✓ init completed");
+        const { applied, skippedOptional } = await (0, init_1.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)
@@ -244,6 +357,15 @@ program
             if (errAny.code === "42501") {
                 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;
     }