postgresai 0.16.0-rc.1 → 0.16.0-rc.3

package/sql/06.helpers.sql

@@ -2,126 +2,6 @@
 -- These functions use SECURITY DEFINER to allow the monitoring user to perform
 -- operations they don't have direct permissions for.
 
-/*
- * explain_generic
- *
- * Function to get generic explain plans with optional HypoPG index testing.
- * Requires: PostgreSQL 16+ (for generic_plan option), HypoPG extension (optional).
- *
- * Security notes:
- * - EXPLAIN without ANALYZE is read-only (plans but doesn't execute the query)
- * - PostgreSQL's EXPLAIN only accepts a single statement (primary protection)
- * - Input validation uses a simple heuristic to detect multiple statements
- *   (Note: may reject valid queries containing semicolons in string literals)
- *
- * Usage examples:
- *   -- Basic generic plan
- *   select postgres_ai.explain_generic('select * from users where id = $1');
- *
- *   -- JSON format
- *   select postgres_ai.explain_generic('select * from users where id = $1', 'json');
- *
- *   -- Test a hypothetical index
- *   select postgres_ai.explain_generic(
- *     'select * from users where email = $1',
- *     'text',
- *     'create index on users (email)'
- *   );
- */
-create or replace function postgres_ai.explain_generic(
-  in query text,
-  in format text default 'text',
-  in hypopg_index text default null,
-  out result text
-)
-language plpgsql
-security definer
-set search_path = pg_catalog, public
-as $$
-declare
-  v_line record;
-  v_lines text[] := '{}';
-  v_explain_query text;
-  v_hypo_result record;
-  v_version int;
-  v_hypopg_available boolean;
-  v_clean_query text;
-begin
-  -- Check PostgreSQL version (generic_plan requires 16+)
-  select current_setting('server_version_num')::int into v_version;
-
-  if v_version < 160000 then
-    raise exception 'generic_plan requires PostgreSQL 16+, current version: %',
-      current_setting('server_version');
-  end if;
-
-  -- Input validation: reject empty queries
-  if query is null or trim(query) = '' then
-    raise exception 'query cannot be empty';
-  end if;
-
-  -- Input validation: detect multiple statements (defense-in-depth)
-  -- Note: This is a simple heuristic - EXPLAIN itself only accepts single statements
-  -- Limitation: Queries with semicolons inside string literals will be rejected
-  v_clean_query := trim(query);
-  if v_clean_query like '%;%' then
-    -- Strip trailing semicolon if present (common user convenience)
-    v_clean_query := regexp_replace(v_clean_query, ';\s*$', '');
-    -- If there's still a semicolon, reject (likely multiple statements or semicolon in string)
-    if v_clean_query like '%;%' then
-      raise exception 'query contains semicolon (multiple statements not allowed; note: semicolons in string literals are also not supported)';
-    end if;
-  end if;
-
-  -- Check if HypoPG extension is available
-  if hypopg_index is not null then
-    select exists(
-      select 1 from pg_extension where extname = 'hypopg'
-    ) into v_hypopg_available;
-
-    if not v_hypopg_available then
-      raise exception 'HypoPG extension is required for hypothetical index testing but is not installed';
-    end if;
-
-    -- Create hypothetical index
-    select * into v_hypo_result from hypopg_create_index(hypopg_index);
-    raise notice 'Created hypothetical index: % (oid: %)',
-      v_hypo_result.indexname, v_hypo_result.indexrelid;
-  end if;
-
-  -- Build and execute EXPLAIN query
-  -- Note: EXPLAIN is read-only (plans but doesn't execute), making this safe
-  begin
-    if lower(format) = 'json' then
-      execute 'explain (verbose, settings, generic_plan, format json) ' || v_clean_query
-        into result;
-    else
-      for v_line in execute 'explain (verbose, settings, generic_plan) ' || v_clean_query loop
-        v_lines := array_append(v_lines, v_line."QUERY PLAN");
-      end loop;
-      result := array_to_string(v_lines, e'\n');
-    end if;
-  exception when others then
-    -- Clean up hypothetical index before re-raising
-    if hypopg_index is not null then
-      perform hypopg_reset();
-    end if;
-    raise;
-  end;
-
-  -- Clean up hypothetical index
-  if hypopg_index is not null then
-    perform hypopg_reset();
-  end if;
-end;
-$$;
-
-comment on function postgres_ai.explain_generic(text, text, text) is
-  'Returns generic EXPLAIN plan with optional HypoPG index testing (requires PG16+)';
-
--- Grant execute to the monitoring user
-grant execute on function postgres_ai.explain_generic(text, text, text) to {{ROLE_IDENT}};
-
 /*
  * table_describe
  *
@@ -435,5 +315,3 @@ comment on function postgres_ai.table_describe(text) is
   'Returns comprehensive table information in compact text format for LLM analysis';
 
 grant execute on function postgres_ai.table_describe(text) to {{ROLE_IDENT}};
-
-

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/init.integration.test.ts

@@ -407,12 +407,14 @@ describe.skipIf(skipTests)("integration: prepare-db", () => {
     }
   }, { timeout: TEST_TIMEOUT });
 
-  // 60s timeout for PostgreSQL startup + multiple SQL queries in slow CI
-  test("explain_generic validates input and prevents SQL injection", async () => {
+  // Security regression for #387: explain_generic was a SECURITY DEFINER helper that
+  // ran caller-supplied SQL through EXPLAIN. The planner folds IMMUTABLE/STABLE functions
+  // at plan time in the definer's (superuser) context, making it an RCE/data-exfil vector.
+  // It has been removed; prepare-db must NOT create it.
+  test("explain_generic is not created by prepare-db (RCE helper removed, #387)", async () => {
     pg = await createTempPostgres();
 
     try {
-      // Run init first
       {
         const r = runCliInit([pg.adminUri, "--password", "pw1", "--skip-optional-permissions"]);
         expect(r.status).toBe(0);
@@ -422,82 +424,10 @@ describe.skipIf(skipTests)("integration: prepare-db", () => {
       await c.connect();
 
       try {
-        // Check PostgreSQL version - generic_plan requires 16+
-        const versionRes = await c.query("show server_version_num");
-        const version = parseInt(versionRes.rows[0].server_version_num, 10);
-
-        if (version < 160000) {
-          // Skip this test on older PostgreSQL versions
-          console.log("Skipping explain_generic tests: requires PostgreSQL 16+");
-          return;
-        }
-
-        // Test 1: Empty query should be rejected
-        await expect(
-          c.query("select postgres_ai.explain_generic('')")
-        ).rejects.toThrow(/query cannot be empty/);
-
-        // Test 2: Null query should be rejected
-        await expect(
-          c.query("select postgres_ai.explain_generic(null)")
-        ).rejects.toThrow(/query cannot be empty/);
-
-        // Test 3: Multiple statements (semicolon in middle) should be rejected
-        await expect(
-          c.query("select postgres_ai.explain_generic('select 1; select 2')")
-        ).rejects.toThrow(/semicolon|multiple statements/i);
-
-        // Test 4: Trailing semicolon should be stripped and work
-        {
-          const res = await c.query("select postgres_ai.explain_generic('select 1;') as result");
-          expect(res.rows[0].result).toBeTruthy();
-          expect(res.rows[0].result).toMatch(/Result/i);
-        }
-
-        // Test 5: Valid query should work
-        {
-          const res = await c.query("select postgres_ai.explain_generic('select $1::int', 'text') as result");
-          expect(res.rows[0].result).toBeTruthy();
-        }
-
-        // Test 6: JSON format should work
-        {
-          const res = await c.query("select postgres_ai.explain_generic('select 1', 'json') as result");
-          const plan = JSON.parse(res.rows[0].result);
-          expect(Array.isArray(plan)).toBe(true);
-          expect(plan[0].Plan).toBeTruthy();
-        }
-
-        // Test 7: Whitespace-only query should be rejected
-        await expect(
-          c.query("select postgres_ai.explain_generic('   ')")
-        ).rejects.toThrow(/query cannot be empty/);
-
-        // Test 8: Semicolon in string literal is rejected (documented limitation)
-        // Note: This is a known limitation - the simple heuristic cannot parse SQL strings
-        await expect(
-          c.query("select postgres_ai.explain_generic('select ''hello;world''')")
-        ).rejects.toThrow(/semicolon/i);
-
-        // Test 9: SQL comments should work (no semicolons)
-        {
-          const res = await c.query("select postgres_ai.explain_generic('select 1 -- comment') as result");
-          expect(res.rows[0].result).toBeTruthy();
-        }
-
-        // Test 10: Escaped quotes should work (no semicolons)
-        {
-          const res = await c.query("select postgres_ai.explain_generic('select ''test''''s value''') as result");
-          expect(res.rows[0].result).toBeTruthy();
-        }
-
-        // Test 11: Case-insensitive format parameter
-        {
-          const res = await c.query("select postgres_ai.explain_generic('select 1', 'JSON') as result");
-          const plan = JSON.parse(res.rows[0].result);
-          expect(Array.isArray(plan)).toBe(true);
-        }
-
+        const res = await c.query(
+          "select count(*)::int as n from pg_proc where proname = 'explain_generic' and pronamespace = (select oid from pg_namespace where nspname = 'postgres_ai')"
+        );
+        expect(res.rows[0].n).toBe(0);
       } finally {
         await c.end();
       }

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");