postgresai 0.16.0-rc.0 → 0.16.0-rc.2

package/lib/aas-onboard.ts

@@ -0,0 +1,251 @@
+/**
+ * Hands-off AAS auto-onboarding for `mon local-install` (platform-all #338).
+ *
+ * After the monitoring stack is up and the instance is adopted, the CLI arms
+ * AAS collection without an operator step:
+ *   1. mint a `pgai-aas-collect` Grafana Viewer service-account token on the
+ *      LOCAL Grafana (the CLI holds the admin password),
+ *   2. resolve the numeric Prometheus datasource id,
+ *   3. read the (cluster, node_name) labels straight from the pgwatch target
+ *      config the CLI itself wrote (buildInstance's custom_tags) — no live
+ *      series query, so no waiters>0 timing dependency,
+ *   4. hand all of it to the platform via the API-token RPC
+ *      v1.monitoring_instance_aas_register, which encrypts the token and stores
+ *      the AAS state keys (it makes no outbound Grafana call of its own).
+ *
+ * Best-effort, exactly like registerMonitoringInstance: never throws, returns a
+ * result the caller logs. The plaintext SA token only ever lives in locals.
+ */
+
+import { loadInstances } from "./instances";
+import { resolveBaseUrls } from "./util";
+
+const SA_NAME = "pgai-aas-collect";
+
+/** Local Grafana base URL (published on the monitoring host). Overridable for tests/odd setups. */
+function grafanaBaseUrl(): string {
+  return (process.env.PGAI_GRAFANA_LOCAL_URL || "http://localhost:3000").replace(/\/+$/, "");
+}
+
+function grafanaAdminUser(): string {
+  // The monitoring stack's compose hardcodes the Grafana admin user to
+  // "monitor" (GF_SECURITY_ADMIN_USER: monitor), so default to that rather than
+  // Grafana's stock "admin" — otherwise AAS arming logs in as the wrong user
+  // and every datasource lookup 401s. An explicit env override still wins.
+  return process.env.GF_SECURITY_ADMIN_USER || "monitor";
+}
+
+/** Parse a vcpus input (flag/env) to a non-negative integer; 0 = "unknown" fallback. */
+export function parseVcpus(raw: string | number | undefined | null): number {
+  if (raw === undefined || raw === null || raw === "") return 0;
+  const n = typeof raw === "number" ? raw : parseInt(String(raw).trim(), 10);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : 0;
+}
+
+/**
+ * Read the single enabled target's (cluster, node_name) from the pgwatch
+ * instances file. Returns null when it can't be determined unambiguously
+ * (0 or >1 enabled targets) — AAS onboards exactly one (cluster, node) pair.
+ */
+export function resolveAasLabels(instancesPath: string): { cluster: string; node: string } | null {
+  let instances;
+  try {
+    instances = loadInstances(instancesPath);
+  } catch {
+    return null;
+  }
+  const enabled = instances.filter((i) => i.is_enabled !== false);
+  if (enabled.length !== 1) return null;
+  const tags = (enabled[0].custom_tags || {}) as Record<string, unknown>;
+  const cluster = typeof tags.cluster === "string" && tags.cluster ? tags.cluster : "default";
+  const node = typeof tags.node_name === "string" && tags.node_name ? tags.node_name : enabled[0].name;
+  if (!cluster || !node) return null;
+  return { cluster, node };
+}
+
+async function grafanaApi(
+  method: string,
+  pathPart: string,
+  adminPassword: string,
+  body?: unknown
+): Promise<Response> {
+  const auth = Buffer.from(`${grafanaAdminUser()}:${adminPassword}`).toString("base64");
+  return fetch(`${grafanaBaseUrl()}${pathPart}`, {
+    method,
+    headers: { "Content-Type": "application/json", Authorization: `Basic ${auth}` },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+}
+
+/**
+ * Find-or-create the pgai-aas-collect Viewer service account on the local
+ * Grafana and mint a fresh glsa_ token. Returns the token or null on any failure.
+ *
+ * We deliberately do NOT prune prior tokens: deleting them here is racy — a
+ * concurrent or repeated install could delete the token the platform currently
+ * holds (stored encrypted), silently 401-ing collection until the next register.
+ * The unique mint name already avoids 409s, and orphaned Viewer tokens are
+ * benign; token hygiene is left to a separate, non-racy mechanism.
+ */
+export async function mintAasServiceAccountToken(
+  adminPassword: string,
+  debug = false
+): Promise<string | null> {
+  const log = (m: string) => debug && console.error(`Debug: AAS SA mint: ${m}`);
+  try {
+    let saId: number | null = null;
+
+    const search = await grafanaApi("GET", `/api/serviceaccounts/search?query=${SA_NAME}`, adminPassword);
+    if (search.ok) {
+      const data = (await search.json().catch(() => null)) as { serviceAccounts?: Array<{ id?: unknown; name?: unknown }> } | null;
+      const found = (data?.serviceAccounts || []).find((s) => s.name === SA_NAME);
+      if (found && typeof found.id === "number") saId = found.id;
+    }
+
+    if (saId == null) {
+      const created = await grafanaApi("POST", "/api/serviceaccounts", adminPassword, { name: SA_NAME, role: "Viewer" });
+      if (!created.ok) {
+        log(`create SA failed: HTTP ${created.status}`);
+        return null;
+      }
+      const cj = (await created.json().catch(() => null)) as { id?: unknown } | null;
+      if (typeof cj?.id !== "number") return null;
+      saId = cj.id;
+    }
+
+    // Unique token name avoids a 409 on a pre-existing name (no prune needed).
+    const mint = await grafanaApi("POST", `/api/serviceaccounts/${saId}/tokens`, adminPassword, {
+      name: `aas-collect-${Date.now()}`,
+      role: "Viewer",
+    });
+    if (!mint.ok) {
+      log(`mint token failed: HTTP ${mint.status}`);
+      return null;
+    }
+    const mj = (await mint.json().catch(() => null)) as { key?: unknown } | null;
+    return typeof mj?.key === "string" ? mj.key : null;
+  } catch (err) {
+    log((err as Error).message);
+    return null;
+  }
+}
+
+/**
+ * Resolve the single Prometheus-typed datasource's numeric id on the local
+ * Grafana. The monitoring stack's VictoriaMetrics datasource is type
+ * "prometheus" (VM speaks PromQL), and the stack registers exactly one such
+ * datasource — the same one the collector queries. 0 / API-not-ready → null
+ * (a provisioning transient — the readiness loop retries); >1 → "ambiguous"
+ * (a permanent misconfiguration — the loop stops at once), matching
+ * v1.aas_onboard's >1 skip.
+ */
+export async function resolveDatasourceId(adminPassword: string, debug = false): Promise<number | "ambiguous" | null> {
+  try {
+    const res = await grafanaApi("GET", "/api/datasources", adminPassword);
+    if (!res.ok) return null;
+    const list = (await res.json().catch(() => [])) as Array<{ id?: unknown; type?: unknown }>;
+    const prom = list.filter((d) => d.type === "prometheus");
+    if (prom.length > 1) {
+      // >1 is a permanent misconfiguration, not a provisioning transient: the
+      // datasource count only grows as Grafana provisions, so retrying can never
+      // resolve it. Signal a definitive skip so the readiness loop bails at once.
+      if (debug) console.error(`Debug: AAS: ${prom.length} prometheus datasources (ambiguous); not retrying`);
+      return "ambiguous";
+    }
+    if (prom.length === 0) {
+      if (debug) console.error(`Debug: AAS: no prometheus datasource resolvable yet`);
+      return null;
+    }
+    return typeof prom[0].id === "number" ? prom[0].id : null;
+  } catch {
+    return null;
+  }
+}
+
+export interface AasRegisterResult {
+  ok: boolean;
+  reason?: string;
+}
+
+/**
+ * Arm hands-off AAS collection for an adopted monitoring instance. Best-effort:
+ * never throws; returns {ok:false, reason} on any failure so the caller can log
+ * a non-fatal warning. Mirrors registerMonitoringInstance's API-call shape.
+ */
+export async function registerAasCollection(
+  apiKey: string,
+  instanceId: string,
+  opts: {
+    grafanaPassword: string;
+    instancesPath: string;
+    vcpus: number;
+    apiBaseUrl?: string;
+    debug?: boolean;
+    fetchImpl?: typeof fetch;
+    // Grafana-readiness polling for the datasource lookup (Grafana has just
+    // been started by `compose up`). Defaults: 20 attempts × 3s.
+    datasourceMaxAttempts?: number;
+    datasourceRetryDelayMs?: number;
+  }
+): Promise<AasRegisterResult> {
+  const debug = !!opts.debug;
+  try {
+    if (!apiKey || !instanceId) return { ok: false, reason: "missing api key or instance id" };
+
+    const labels = resolveAasLabels(opts.instancesPath);
+    if (!labels) return { ok: false, reason: "could not determine a single (cluster, node_name) target" };
+
+    // Grafana was just started by `compose up`; it needs time to create its
+    // admin user, provision datasources, and serve its API. Querying too early
+    // makes the datasource lookup fail transiently, so poll until it resolves
+    // (best-effort, capped — the install never blocks on this).
+    const maxAttempts = opts.datasourceMaxAttempts ?? 20;
+    const retryDelayMs = opts.datasourceRetryDelayMs ?? 3000;
+    let datasourceId: number | null = null;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      const resolved = await resolveDatasourceId(opts.grafanaPassword, debug);
+      if (typeof resolved === "number") { datasourceId = resolved; break; }
+      // "ambiguous" (>1 prometheus datasource) is permanent — retrying can't fix
+      // it, so stop polling immediately instead of waiting out the whole budget.
+      if (resolved === "ambiguous") break;
+      if (attempt < maxAttempts) {
+        if (debug) console.error(`Debug: AAS: datasource not resolvable yet (attempt ${attempt}/${maxAttempts}); waiting for Grafana…`);
+        await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
+      }
+    }
+    if (datasourceId == null) return { ok: false, reason: "could not resolve the Prometheus datasource id" };
+
+    const saToken = await mintAasServiceAccountToken(opts.grafanaPassword, debug);
+    if (!saToken) return { ok: false, reason: "could not mint a Grafana service-account token" };
+
+    const { apiBaseUrl } = resolveBaseUrls({ apiBaseUrl: opts.apiBaseUrl });
+    const url = `${apiBaseUrl}/rpc/monitoring_instance_aas_register`;
+    const doFetch = opts.fetchImpl || fetch;
+    if (debug) console.error(`Debug: AAS: POST ${url} (cluster=${labels.cluster}, node=${labels.node}, vcpus=${opts.vcpus}, ds=${datasourceId})`);
+
+    const res = await doFetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        api_token: apiKey,
+        instance_id: instanceId,
+        sa_token: saToken,
+        cluster_name: labels.cluster,
+        node_name: labels.node,
+        vcpus: opts.vcpus,
+        datasource_id: datasourceId,
+      }),
+    });
+    if (!res.ok) {
+      // Log status only — never the response body: a platform could echo the
+      // request payload (incl. sa_token) in an error body, which must not reach
+      // the user's debug log.
+      if (debug) console.error(`Debug: AAS register failed: HTTP ${res.status}`);
+      return { ok: false, reason: `platform returned HTTP ${res.status}` };
+    }
+    return { ok: true };
+  } catch (err) {
+    if (debug) console.error(`Debug: AAS register error: ${(err as Error).message}`);
+    return { ok: false, reason: (err as Error).message };
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postgresai",
-  "version": "0.16.0-rc.0",
+  "version": "0.16.0-rc.2",
   "description": "postgres_ai CLI",
   "license": "Apache-2.0",
   "private": false,

package/test/aas-onboard.test.ts

@@ -0,0 +1,301 @@
+import { describe, test, expect, beforeEach, afterEach, spyOn } from "bun:test";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { addInstanceToFile, buildInstance } from "../lib/instances";
+import {
+  parseVcpus,
+  resolveAasLabels,
+  registerAasCollection,
+} from "../lib/aas-onboard";
+
+/** Minimal Response-like stub for mocking fetch. */
+function res(ok: boolean, status: number, jsonBody: unknown, textBody = ""): Response {
+  return {
+    ok,
+    status,
+    json: async () => jsonBody,
+    text: async () => textBody,
+  } as unknown as Response;
+}
+
+describe("parseVcpus", () => {
+  test("non-positive / junk → 0 (the 'unknown' fallback)", () => {
+    expect(parseVcpus(undefined)).toBe(0);
+    expect(parseVcpus(null)).toBe(0);
+    expect(parseVcpus("")).toBe(0);
+    expect(parseVcpus("0")).toBe(0);
+    expect(parseVcpus("-4")).toBe(0);
+    expect(parseVcpus("abc")).toBe(0);
+  });
+  test("positive values → integer", () => {
+    expect(parseVcpus("16")).toBe(16);
+    expect(parseVcpus(8)).toBe(8);
+    expect(parseVcpus("12.9")).toBe(12);
+    expect(parseVcpus("  4 ")).toBe(4);
+  });
+});
+
+describe("resolveAasLabels", () => {
+  let dir: string;
+  let file: string;
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), "aas-labels-"));
+    file = path.join(dir, "instances.yml");
+  });
+  afterEach(() => fs.rmSync(dir, { recursive: true, force: true }));
+
+  test("single enabled target → its (cluster, node_name) from custom_tags", () => {
+    addInstanceToFile(file, buildInstance("appdb", "postgresql://u@h:5432/db"));
+    expect(resolveAasLabels(file)).toEqual({ cluster: "default", node: "appdb" });
+  });
+
+  test("no targets → null", () => {
+    fs.writeFileSync(file, "# empty\n");
+    expect(resolveAasLabels(file)).toBeNull();
+  });
+
+  test("more than one enabled target → null (cannot disambiguate)", () => {
+    addInstanceToFile(file, buildInstance("a", "postgresql://u@h:5432/a"));
+    addInstanceToFile(file, buildInstance("b", "postgresql://u@h:5432/b"));
+    expect(resolveAasLabels(file)).toBeNull();
+  });
+
+  test("missing file → null (no throw)", () => {
+    expect(resolveAasLabels(path.join(dir, "nope.yml"))).toBeNull();
+  });
+});
+
+describe("registerAasCollection", () => {
+  let dir: string;
+  let instancesPath: string;
+  let fetchSpy: ReturnType<typeof spyOn>;
+  let calls: Array<{ url: string; method: string; body?: string }>;
+
+  // Route a fetch by URL+method to canned Grafana/RPC responses. Options let a
+  // test exercise the existing-SA branch, datasource ambiguity, a keyless mint,
+  // and RPC success/failure.
+  function installFetch(opts: {
+    rpc?: { ok: boolean; status: number; text?: string };
+    existingSa?: boolean; // search finds an existing pgai-aas-collect SA
+    prometheusCount?: number; // # of prometheus-typed datasources (default 1)
+    mintKey?: string | null; // token .key; null => mint returns no key
+  } = {}) {
+    const rpc = opts.rpc ?? { ok: true, status: 200 };
+    const existingSa = opts.existingSa ?? false;
+    const promCount = opts.prometheusCount ?? 1;
+    const mintKey = opts.mintKey === undefined ? "glsa_mock_token_xyz" : opts.mintKey;
+    calls = [];
+    fetchSpy = spyOn(globalThis, "fetch").mockImplementation((async (input: unknown, init?: { method?: string; body?: string }) => {
+      const url = String(input);
+      const method = (init?.method || "GET").toUpperCase();
+      calls.push({ url, method, body: init?.body });
+      if (url.includes("/api/serviceaccounts/search"))
+        return res(true, 200, existingSa ? { serviceAccounts: [{ id: 99, name: "pgai-aas-collect" }] } : { serviceAccounts: [] });
+      if (url.match(/\/tokens$/) && method === "POST") return res(true, 200, mintKey === null ? {} : { key: mintKey });
+      if (url.endsWith("/api/serviceaccounts") && method === "POST") return res(true, 201, { id: 42, name: "pgai-aas-collect" });
+      if (url.includes("/api/datasources")) {
+        const dss: Array<Record<string, unknown>> = [];
+        for (let i = 0; i < promCount; i++) dss.push({ id: 8 + i, uid: `prom${i}`, type: "prometheus" });
+        dss.push({ id: 3, uid: "loki1", type: "loki" });
+        return res(true, 200, dss);
+      }
+      if (url.includes("/rpc/monitoring_instance_aas_register")) return res(rpc.ok, rpc.status, {}, rpc.text || "");
+      return res(false, 404, {});
+    }) as unknown as typeof fetch);
+  }
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), "aas-reg-"));
+    instancesPath = path.join(dir, "instances.yml");
+    addInstanceToFile(instancesPath, buildInstance("appdb", "postgresql://u@h:5432/db"));
+  });
+  afterEach(() => {
+    fetchSpy?.mockRestore();
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("happy path: mints SA, resolves datasource, POSTs the RPC with the right body", async () => {
+    installFetch();
+    const r = await registerAasCollection("apikey-1", "inst-123", {
+      grafanaPassword: "pw",
+      instancesPath,
+      vcpus: 16,
+      apiBaseUrl: "https://api.test",
+    });
+    expect(r.ok).toBe(true);
+
+    const rpc = calls.find((c) => c.url.includes("/rpc/monitoring_instance_aas_register"));
+    expect(rpc).toBeDefined();
+    expect(rpc!.url).toBe("https://api.test/rpc/monitoring_instance_aas_register");
+    const body = JSON.parse(rpc!.body!);
+    expect(body).toMatchObject({
+      api_token: "apikey-1",
+      instance_id: "inst-123",
+      sa_token: "glsa_mock_token_xyz",
+      cluster_name: "default",
+      node_name: "appdb",
+      vcpus: 16,
+      datasource_id: 8, // the prometheus one, not loki
+    });
+    // a fresh SA was created (search found none) and a token minted on its id.
+    expect(calls.some((c) => c.url.endsWith("/api/serviceaccounts") && c.method === "POST")).toBe(true);
+    expect(calls.some((c) => c.url.match(/\/serviceaccounts\/42\/tokens$/) && c.method === "POST")).toBe(true);
+  });
+
+  test("platform error → ok:false, reason carries the status (best-effort, no throw)", async () => {
+    installFetch({ rpc: { ok: false, status: 403, text: "forbidden" } });
+    const r = await registerAasCollection("apikey-1", "inst-123", {
+      grafanaPassword: "pw",
+      instancesPath,
+      vcpus: 16,
+      apiBaseUrl: "https://api.test",
+    });
+    expect(r.ok).toBe(false);
+    expect(r.reason).toContain("403");
+  });
+
+  test("no resolvable target → ok:false and NO outbound calls (labels checked first)", async () => {
+    installFetch();
+    const empty = path.join(dir, "empty.yml");
+    fs.writeFileSync(empty, "# none\n");
+    const r = await registerAasCollection("apikey-1", "inst-123", {
+      grafanaPassword: "pw",
+      instancesPath: empty,
+      vcpus: 16,
+      apiBaseUrl: "https://api.test",
+    });
+    expect(r.ok).toBe(false);
+    expect(r.reason).toContain("cluster");
+    expect(calls.length).toBe(0); // bailed before any HTTP
+  });
+
+  test("missing api key / instance id → ok:false, no calls", async () => {
+    installFetch();
+    const r = await registerAasCollection("", "inst-123", {
+      grafanaPassword: "pw",
+      instancesPath,
+      vcpus: 0,
+      apiBaseUrl: "https://api.test",
+    });
+    expect(r.ok).toBe(false);
+    expect(calls.length).toBe(0);
+  });
+
+  test("existing service account is reused (no create), token minted on its id", async () => {
+    installFetch({ existingSa: true });
+    const r = await registerAasCollection("apikey-1", "inst-123", {
+      grafanaPassword: "pw", instancesPath, vcpus: 8, apiBaseUrl: "https://api.test",
+    });
+    expect(r.ok).toBe(true);
+    expect(calls.some((c) => c.url.endsWith("/api/serviceaccounts") && c.method === "POST")).toBe(false);
+    expect(calls.some((c) => c.url.match(/\/serviceaccounts\/99\/tokens$/) && c.method === "POST")).toBe(true);
+  });
+
+  test("absent or ambiguous (>1) prometheus datasource → ok:false, no RPC call", async () => {
+    for (const n of [0, 2]) {
+      fetchSpy?.mockRestore();
+      installFetch({ prometheusCount: n });
+      const r = await registerAasCollection("apikey-1", "inst-123", {
+        grafanaPassword: "pw", instancesPath, vcpus: 8, apiBaseUrl: "https://api.test",
+        // 0/>1 is a definitive skip; cap the readiness retry so the test stays fast.
+        datasourceMaxAttempts: 2, datasourceRetryDelayMs: 0,
+      });
+      expect(r.ok).toBe(false);
+      expect(r.reason).toContain("datasource");
+      expect(calls.some((c) => c.url.includes("/rpc/monitoring_instance_aas_register"))).toBe(false);
+    }
+  });
+
+  test("polls the datasource until Grafana is ready, then registers", async () => {
+    // Grafana isn't ready on the first probes (no prometheus datasource yet),
+    // then it provisions — the readiness retry must keep going and then succeed.
+    let dsProbes = 0;
+    calls = [];
+    fetchSpy = spyOn(globalThis, "fetch").mockImplementation((async (input: unknown, init?: { method?: string; body?: string }) => {
+      const url = String(input);
+      const method = (init?.method || "GET").toUpperCase();
+      calls.push({ url, method, body: init?.body });
+      if (url.includes("/api/serviceaccounts/search")) return res(true, 200, { serviceAccounts: [] });
+      if (url.match(/\/tokens$/) && method === "POST") return res(true, 200, { key: "glsa_mock" });
+      if (url.endsWith("/api/serviceaccounts") && method === "POST") return res(true, 201, { id: 42 });
+      if (url.includes("/api/datasources")) {
+        dsProbes++;
+        return dsProbes < 3
+          ? res(true, 200, [{ id: 3, type: "loki" }]) // not ready yet
+          : res(true, 200, [{ id: 8, type: "prometheus" }, { id: 3, type: "loki" }]);
+      }
+      if (url.includes("/rpc/monitoring_instance_aas_register")) return res(true, 200, {});
+      return res(false, 404, {});
+    }) as unknown as typeof fetch);
+
+    const r = await registerAasCollection("apikey-1", "inst-123", {
+      grafanaPassword: "pw", instancesPath, vcpus: 8, apiBaseUrl: "https://api.test",
+      datasourceMaxAttempts: 6, datasourceRetryDelayMs: 0,
+    });
+    expect(r.ok).toBe(true);
+    expect(dsProbes).toBeGreaterThanOrEqual(3); // kept polling past the not-ready probes
+    const rpc = calls.find((c) => c.url.includes("/rpc/monitoring_instance_aas_register"));
+    expect(rpc).toBeDefined();
+    expect(JSON.parse(rpc!.body!).datasource_id).toBe(8);
+  });
+
+  test(">1 prometheus datasource is a definitive skip: one probe, no retry", async () => {
+    // The >1 case is permanent (the datasource count only grows), so the
+    // readiness loop must bail after a single probe, not burn its whole budget.
+    let dsProbes = 0;
+    calls = [];
+    fetchSpy = spyOn(globalThis, "fetch").mockImplementation((async (input: unknown, init?: { method?: string; body?: string }) => {
+      const url = String(input);
+      const method = (init?.method || "GET").toUpperCase();
+      calls.push({ url, method, body: init?.body });
+      if (url.includes("/api/datasources")) {
+        dsProbes++;
+        return res(true, 200, [{ id: 8, type: "prometheus" }, { id: 9, type: "prometheus" }, { id: 3, type: "loki" }]);
+      }
+      return res(false, 404, {});
+    }) as unknown as typeof fetch);
+
+    const r = await registerAasCollection("apikey-1", "inst-123", {
+      grafanaPassword: "pw", instancesPath, vcpus: 8, apiBaseUrl: "https://api.test",
+      datasourceMaxAttempts: 5, datasourceRetryDelayMs: 0,
+    });
+    expect(r.ok).toBe(false);
+    expect(r.reason).toContain("datasource");
+    expect(dsProbes).toBe(1); // bailed after one probe; did NOT retry 5x
+    expect(calls.some((c) => c.url.includes("/rpc/monitoring_instance_aas_register"))).toBe(false);
+  });
+
+  test("never-ready datasource: polls exactly maxAttempts times, then ok:false", async () => {
+    // Bounds the readiness loop: a never-appearing datasource must probe exactly
+    // maxAttempts times (N probes, N-1 sleeps) and then give up — not loop forever.
+    let dsProbes = 0;
+    calls = [];
+    fetchSpy = spyOn(globalThis, "fetch").mockImplementation((async (input: unknown, init?: { method?: string; body?: string }) => {
+      const url = String(input);
+      const method = (init?.method || "GET").toUpperCase();
+      calls.push({ url, method, body: init?.body });
+      if (url.includes("/api/datasources")) { dsProbes++; return res(true, 200, [{ id: 3, type: "loki" }]); } // never a prometheus
+      return res(false, 404, {});
+    }) as unknown as typeof fetch);
+
+    const r = await registerAasCollection("apikey-1", "inst-123", {
+      grafanaPassword: "pw", instancesPath, vcpus: 8, apiBaseUrl: "https://api.test",
+      datasourceMaxAttempts: 3, datasourceRetryDelayMs: 0,
+    });
+    expect(r.ok).toBe(false);
+    expect(r.reason).toContain("datasource");
+    expect(dsProbes).toBe(3); // bounded: exactly maxAttempts probes
+    expect(calls.some((c) => c.url.includes("/rpc/monitoring_instance_aas_register"))).toBe(false);
+  });
+
+  test("mint returning no key → ok:false, no RPC call", async () => {
+    installFetch({ mintKey: null });
+    const r = await registerAasCollection("apikey-1", "inst-123", {
+      grafanaPassword: "pw", instancesPath, vcpus: 8, apiBaseUrl: "https://api.test",
+    });
+    expect(r.ok).toBe(false);
+    expect(r.reason).toContain("service-account token");
+    expect(calls.some((c) => c.url.includes("/rpc/monitoring_instance_aas_register"))).toBe(false);
+  });
+});

package/test/monitoring.test.ts

@@ -19,6 +19,7 @@ import {
 import {
   registerMonitoringInstance,
   resolveAdoptedProject,
+  planMonitoringRegistration,
 } from "../bin/postgres-ai";
 
 /**
@@ -241,12 +242,13 @@ describe("registerMonitoringInstance", () => {
   });
 
   // Issue platform-all#311: console-provisioned installs pass instance_id so
-  // the platform adopts the provisioned instance instead of self-registering
-  // a duplicate under an auto-created "postgres-ai-monitoring" project.
+  // the platform adopts the provisioned instance and returns its real project
+  // — the CLI sends NO project_name on the adopt path (the hardcoded
+  // "postgres-ai-monitoring" default was removed).
   test("includes instance_id in body when adopting a provisioned instance", async () => {
     const instanceId = "019eb300-3f2a-7a75-b54d-4f10572b25b8";
 
-    await registerMonitoringInstance("key", "postgres-ai-monitoring", opts({ instanceId }));
+    await registerMonitoringInstance("key", undefined, opts({ instanceId }));
 
     const body = JSON.parse(fetchCalls[0].options.body as string);
     expect(body.instance_id).toBe(instanceId);
@@ -255,6 +257,22 @@ describe("registerMonitoringInstance", () => {
     expect(headers["instance-id"]).toBeUndefined();
   });
 
+  test("omits project_name from the body when undefined (adopt path)", async () => {
+    await registerMonitoringInstance("key", undefined, opts({ instanceId: "i" }));
+
+    const body = JSON.parse(fetchCalls[0].options.body as string);
+    // The adopt path sends no name; the platform returns the real project.
+    expect("project_name" in body).toBe(false);
+    expect(body.api_token).toBe("key");
+  });
+
+  test("omits project_name from the body when empty/whitespace", async () => {
+    await registerMonitoringInstance("key", "   ", opts({ instanceId: "i" }));
+
+    const body = JSON.parse(fetchCalls[0].options.body as string);
+    expect("project_name" in body).toBe(false);
+  });
+
   test("omits instance_id from the body for legacy self-registration", async () => {
     await registerMonitoringInstance("key", "my-project", opts());
 
@@ -262,6 +280,8 @@ describe("registerMonitoringInstance", () => {
     // PostgREST matches the 3-arg function via its default — the key must be
     // ABSENT (not null) so legacy CLIs and the new one hit the same overload.
     expect("instance_id" in body).toBe(false);
+    // A real project name still rides in the body for legacy registration.
+    expect(body.project_name).toBe("my-project");
   });
 
   test("a 200 with {project_id, project_name} returns a populated result", async () => {
@@ -323,6 +343,37 @@ describe("registerMonitoringInstance", () => {
   });
 });
 
+describe("planMonitoringRegistration — mon local-install registration decision", () => {
+  test("instance id present → adopt, no project name required", () => {
+    const plan = planMonitoringRegistration({ instanceId: "i-123" });
+    expect(plan.kind).toBe("adopt");
+    expect(plan.projectName).toBeUndefined();
+  });
+
+  test("instance id present + project → adopt, carries the trimmed name", () => {
+    const plan = planMonitoringRegistration({ instanceId: "i-123", project: "  prod-db  " });
+    expect(plan.kind).toBe("adopt");
+    expect(plan.projectName).toBe("prod-db");
+  });
+
+  test("no instance id + no project → error-missing-project (exit 1 path)", () => {
+    const plan = planMonitoringRegistration({});
+    expect(plan.kind).toBe("error-missing-project");
+    expect(plan.projectName).toBeUndefined();
+  });
+
+  test("no instance id + empty/whitespace project → error-missing-project", () => {
+    expect(planMonitoringRegistration({ project: "" }).kind).toBe("error-missing-project");
+    expect(planMonitoringRegistration({ project: "   " }).kind).toBe("error-missing-project");
+  });
+
+  test("no instance id + real project → legacy self-register with the trimmed name", () => {
+    const plan = planMonitoringRegistration({ project: "  my-project  " });
+    expect(plan.kind).toBe("self-register");
+    expect(plan.projectName).toBe("my-project");
+  });
+});
+
 describe("resolveAdoptedProject — what gets persisted to .pgwatch-config", () => {
   test("prefers the numeric project_id over the name (survives renames)", () => {
     expect(resolveAdoptedProject({ projectId: 42, projectName: "prod-db" })).toBe("42");