postgresai 0.15.0-rc.8 → 0.16.0-rc.0

package/README.md

@@ -203,8 +203,11 @@ postgresai mon health [--wait <sec>]  # Check monitoring services health
 - `--demo` - Demo mode with sample database (testing only, cannot use with --api-key)
 - `--api-key <key>` - Postgres AI API key for automated report uploads
 - `--db-url <url>` - PostgreSQL connection URL to monitor (format: `postgresql://user:pass@host:port/db`)
+- `--instance-id <uuid>` - Adopt a console-provisioned monitoring instance (also via the `PGAI_INSTANCE_ID` env var)
 - `-y, --yes` - Accept all defaults and skip interactive prompts
 
+When `--instance-id <uuid>` (or `PGAI_INSTANCE_ID`) is set, `local-install` forwards the id to the platform, which **adopts** the already-provisioned monitoring instance instead of self-registering a duplicate under an auto-created `postgres-ai-monitoring` project. The CLI then persists the adopted instance's real project to `.pgwatch-config`, so checkup reports upload alongside the rest of that instance's health data. Adoption is awaited (with one automatic retry); if it fails, the CLI warns and reports fall back to the default project until you re-run `local-install`. Without the flag, the legacy self-registration path is byte-for-byte unchanged.
+
 `local-install` writes `.env` in the monitoring directory. It preserves existing `REPLICATOR_PASSWORD` and `VM_AUTH_*` values or generates new random ones when missing; `VM_AUTH_USERNAME` defaults to `vmauth` when absent. The replication password is used by the demo PostgreSQL standby replication user, and the VM auth credentials are required before Docker Compose can provision Grafana datasources. If you run `docker compose` directly or maintain `.env` yourself, set both VM auth values before upgrading. For rotation, run `VM_AUTH_PASSWORD="$(openssl rand -base64 18)" ./scripts/rotate-vm-auth.sh` from the monitoring directory so `.env`, `sink-prometheus`, and `grafana` update together.
 
 #### Monitoring target databases (`mon targets` subgroup)

package/bin/postgres-ai.ts

@@ -24,7 +24,7 @@ import { createInterface } from "readline";
 import * as childProcess from "child_process";
 import { REPORT_GENERATORS, CHECK_INFO, generateAllReports } from "../lib/checkup";
 import { getCheckupEntry } from "../lib/checkup-dictionary";
-import { createCheckupReport, uploadCheckupReportJson, convertCheckupReportJsonToMarkdown, RpcError, formatRpcErrorForDisplay, withRetry } from "../lib/checkup-api";
+import { createCheckupReport, uploadCheckupReportJson, convertCheckupReportJsonToMarkdown, RpcError, formatRpcErrorForDisplay, withRetry, verifyApiKey } from "../lib/checkup-api";
 import { generateCheckSummary } from "../lib/checkup-summary";
 import {
   type Instance,
@@ -334,7 +334,13 @@ function prepareUploadConfig(
       console.error("Tip: run 'postgresai auth' or pass --api-key / set PGAI_API_KEY");
       return null; // Signal to exit
     }
-    return undefined; // Skip upload silently
+    // No credentials and upload not explicitly requested: fall back to
+    // local-only mode, but say so prominently — skipping the upload silently
+    // hides the fact that results never reach the Console.
+    console.error("Notice: no API key configured — results will NOT be uploaded to PostgresAI.");
+    console.error("        To upload: run 'postgresai auth login' or pass --api-key / set PGAI_API_KEY.");
+    console.error("        To run locally without this notice, pass --no-upload.");
+    return undefined; // Skip upload, run checks locally
   }
 
   const cfg = config.readConfig();
@@ -2076,6 +2082,30 @@ program
     const projectWasGenerated = uploadResult?.projectWasGenerated ?? false;
     shouldUpload = !!uploadCfg;
 
+    // Preflight: validate the configured API key with a cheap authenticated
+    // call BEFORE connecting / running checks, so an invalid or expired token
+    // fails in seconds instead of after minutes of wasted work (previously the
+    // upload at the very end of the run was the first authenticated call).
+    // Only a definitive 401/403 stops the run; a transient pre-flight failure
+    // (network error, timeout, 5xx) warns and continues — the upload may still
+    // succeed.
+    if (uploadCfg) {
+      const verification = await verifyApiKey({
+        apiKey: uploadCfg.apiKey,
+        apiBaseUrl: uploadCfg.apiBaseUrl,
+      });
+      if (verification.status === "invalid") {
+        console.error(`Error: the configured API key was rejected by the PostgresAI API (HTTP ${verification.statusCode})`);
+        console.error("Tip: run 'postgresai auth login' to re-authenticate, or pass a valid --api-key / set PGAI_API_KEY");
+        console.error("Tip: pass --no-upload to run checks locally without uploading");
+        process.exitCode = 1;
+        return;
+      }
+      if (verification.status === "unknown") {
+        console.error(`Warning: could not verify API key before running checks (${verification.detail}); continuing — upload will still be attempted`);
+      }
+    }
+
     // Connect and run checks
     const adminConn = resolveAdminConnection({
       conn,
@@ -2388,54 +2418,136 @@ function checkRunningContainers(): { running: boolean; containers: string[] } {
   }
 }
 
+/** Parsed result of v1.monitoring_instance_register. */
+interface MonitoringRegistration {
+  instanceId?: string;
+  projectId?: number;
+  projectName?: string;
+  created?: boolean;
+}
+
 /**
- * Register monitoring instance with the API (non-blocking).
- * Returns immediately, logs result in background.
+ * Register the monitoring instance with the API.
+ *
+ * Two modes (issue platform-all#311):
+ * - With `instanceId` (console-provisioned installs; passed via
+ *   `--instance-id` / PGAI_INSTANCE_ID, wired from the provisioning flow
+ *   through SI/ansible): the platform ADOPTS the existing provisioned
+ *   instance instead of self-registering a duplicate under an auto-created
+ *   "postgres-ai-monitoring" project. The returned project_name is what the
+ *   reporter must upload to, so callers should await the result and persist
+ *   it. One automatic retry, since a lost adoption splits the health matrix
+ *   across two projects.
+ * - Without it: legacy self-registration by project name.
+ *
+ * Never throws — registration is best-effort; returns null on failure.
  */
-function registerMonitoringInstance(
+async function registerMonitoringInstance(
   apiKey: string,
   projectName: string,
-  opts?: { apiBaseUrl?: string; debug?: boolean }
-): void {
+  opts?: { apiBaseUrl?: string; debug?: boolean; instanceId?: string; retries?: number; retryDelayMs?: number }
+): Promise<MonitoringRegistration | null> {
   const { apiBaseUrl } = resolveBaseUrls(opts);
   const url = `${apiBaseUrl}/rpc/monitoring_instance_register`;
   const debug = opts?.debug;
+  const instanceId = opts?.instanceId;
+  const retries = opts?.retries ?? (instanceId ? 1 : 0);
+  // Brief backoff before a retry so a transient 5xx / connection blip gets a
+  // moment to recover; skipped before the first attempt. Tests pass 0.
+  const retryDelayMs = opts?.retryDelayMs ?? 400;
 
   if (debug) {
     console.error(`\nDebug: Registering monitoring instance...`);
     console.error(`Debug: POST ${url}`);
-    console.error(`Debug: project_name=${projectName}`);
+    console.error(`Debug: project_name=${projectName}${instanceId ? ` instance_id=${instanceId}` : ""}`);
   }
 
-  // Fire and forget - don't block the main flow
-  fetch(url, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-    },
-    body: JSON.stringify({
-      api_token: apiKey,
-      project_name: projectName,
-    }),
-  })
-    .then(async (res) => {
+  const requestBody: Record<string, string> = {
+    api_token: apiKey,
+    project_name: projectName,
+  };
+  if (instanceId) {
+    requestBody.instance_id = instanceId;
+  }
+
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    if (attempt > 0 && retryDelayMs > 0) {
+      await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
+    }
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(requestBody),
+      });
       const body = await res.text().catch(() => "");
       if (!res.ok) {
         if (debug) {
           console.error(`Debug: Monitoring registration failed: HTTP ${res.status}`);
           console.error(`Debug: Response: ${body}`);
         }
-        return;
+        continue;
       }
       if (debug) {
         console.error(`Debug: Monitoring registration response: ${body}`);
       }
-    })
-    .catch((err) => {
+      try {
+        const parsed = JSON.parse(body) as {
+          instance_id?: unknown;
+          project_id?: unknown;
+          project_name?: unknown;
+          created?: unknown;
+        };
+        // Runtime-check each field: the `as` cast above is compile-time only,
+        // and a spoofed/older platform could return mistyped values. In
+        // particular `project_id` must be a real number before we trust it
+        // over the (string) project_name in the persistence decision below.
+        return {
+          instanceId: typeof parsed.instance_id === "string" ? parsed.instance_id : undefined,
+          projectId: typeof parsed.project_id === "number" ? parsed.project_id : undefined,
+          projectName: typeof parsed.project_name === "string" ? parsed.project_name : undefined,
+          created: typeof parsed.created === "boolean" ? parsed.created : undefined,
+        };
+      } catch {
+        return {};
+      }
+    } catch (err) {
       if (debug) {
-        console.error(`Debug: Monitoring registration error: ${err.message}`);
+        console.error(`Debug: Monitoring registration error: ${(err as Error).message}`);
       }
-    });
+    }
+  }
+  return null;
+}
+
+/**
+ * Decide what to persist as `.pgwatch-config`'s `project_name` from an
+ * adoption response, or `null` if the response carries no usable project.
+ *
+ * Pure (no I/O) so the branch logic is unit-testable.
+ *
+ * - Prefers the numeric `project_id`: `checkup_report_create` resolves
+ *   "project" as id-or-name, and the id survives project renames (a name
+ *   match would miss after a rename and silently re-create the old name as a
+ *   fresh project). `project_id === 0` is still a valid id and is honored.
+ * - Falls back to `project_name`, but only when it's a safe single-line token.
+ *   The value is server-supplied and written verbatim into a `key=value`
+ *   config file; a name containing `\r`, `\n`, or `=` could inject extra
+ *   config keys (config-file injection, CWE-93/74). Reject those rather than
+ *   risk it — over a trusted first-party endpoint this should never fire.
+ */
+const PROJECT_NAME_RE = /^[A-Za-z0-9._-]+$/;
+function resolveAdoptedProject(reg: MonitoringRegistration | null): string | null {
+  if (!reg) return null;
+  if (typeof reg.projectId === "number" && Number.isFinite(reg.projectId)) {
+    return String(reg.projectId);
+  }
+  if (typeof reg.projectName === "string" && PROJECT_NAME_RE.test(reg.projectName)) {
+    return reg.projectName;
+  }
+  return null;
 }
 
 /**
@@ -2596,8 +2708,12 @@ mon
   .option("--db-url <url>", "PostgreSQL connection URL to monitor")
   .option("--tag <tag>", "Docker image tag to use (e.g., 0.14.0, 0.14.0-dev.33)")
   .option("--project <name>", "Docker Compose project name (default: postgres_ai)")
+  .option(
+    "--instance-id <uuid>",
+    "adopt a console-provisioned monitoring instance instead of self-registering a new one (set automatically by the provisioning flow; PGAI_INSTANCE_ID env also works)"
+  )
   .option("-y, --yes", "accept all defaults and skip interactive prompts", false)
-  .action(async (opts: { demo: boolean; apiKey?: string; dbUrl?: string; tag?: string; project?: string; yes: boolean }) => {
+  .action(async (opts: { demo: boolean; apiKey?: string; dbUrl?: string; tag?: string; project?: string; instanceId?: string; yes: boolean }) => {
     // Get apiKey from global program options (--api-key is defined globally)
     // This is needed because Commander.js routes --api-key to the global option, not the subcommand's option
     const globalOpts = program.opts<CliOptions>();
@@ -3009,13 +3125,49 @@ mon
     }
     console.log("✓ Services started\n");
 
-    // Register monitoring instance with API (non-blocking, only if API key is configured)
+    // Register monitoring instance with API (only if API key is configured).
+    // Console-provisioned installs pass --instance-id (or PGAI_INSTANCE_ID):
+    // the platform then ADOPTS the provisioned instance and tells us its real
+    // project, which the reporter must upload to — so that path is awaited
+    // and persisted; the legacy self-registration stays fire-and-forget
+    // (issue platform-all#311).
     if (apiKey && !opts.demo) {
       const projectName = opts.project || "postgres-ai-monitoring";
-      registerMonitoringInstance(apiKey, projectName, {
-        apiBaseUrl: globalOpts.apiBaseUrl,
-        debug: !!process.env.DEBUG,
-      });
+      const instanceId = opts.instanceId || process.env.PGAI_INSTANCE_ID;
+      if (instanceId) {
+        const reg = await registerMonitoringInstance(apiKey, projectName, {
+          apiBaseUrl: globalOpts.apiBaseUrl,
+          debug: !!process.env.DEBUG,
+          instanceId,
+        });
+        const adoptedProject = resolveAdoptedProject(reg);
+        if (adoptedProject != null) {
+          // Point the reporter at the adopted instance's project so checkup
+          // uploads land next to the rest of this instance's health data.
+          updatePgwatchConfig(path.resolve(projectDir, ".pgwatch-config"), {
+            project_name: adoptedProject,
+          });
+          // `created` distinguishes a fresh self-registration from adopting an
+          // existing provisioned row; with an instance_id we expect adoption.
+          const verb = reg?.created ? "Registered" : "Adopted";
+          console.log(`✓ ${verb} monitoring instance (project: ${adoptedProject})\n`);
+        } else if (reg) {
+          // Request succeeded but carried no usable project field — don't claim
+          // adoption, but don't report a hard failure either (no re-run needed).
+          console.error(
+            `⚠ Adopted provisioned instance ${instanceId} but the platform returned no project — reports will use project '${projectName}'`
+          );
+        } else {
+          console.error(
+            `⚠ Could not adopt provisioned instance ${instanceId} — reports will use project '${projectName}' until 'postgresai mon local-install' is re-run`
+          );
+        }
+      } else {
+        void registerMonitoringInstance(apiKey, projectName, {
+          apiBaseUrl: globalOpts.apiBaseUrl,
+          debug: !!process.env.DEBUG,
+        });
+      }
     }
 
     // Final summary
@@ -5309,3 +5461,4 @@ if (import.meta.main) {
 // Exported for unit tests (the CLI surface above is unaffected; these are the
 // same functions used by the `mon` commands).
 export { refreshBundledComposeIfStale, readDeployedTag, isValidComposeYaml };
+export { registerMonitoringInstance, resolveAdoptedProject, type MonitoringRegistration };