postgresai 0.16.0-dev.7 → 0.16.0-dev.9

package/bin/postgres-ai.ts

@@ -5619,13 +5619,18 @@ withJoeOptions(
     .command("terminate <pid>")
     .description("pg_terminate_backend(pid) on the clone")
 ).action(async (pid: string, opts: JoeCliOpts) => {
-  const pidNum = parseInt(pid, 10);
-  if (Number.isNaN(pidNum)) {
+  // A pid must be a bare non-negative integer. parseInt() silently accepts
+  // trailing garbage ("12x"→12), a sign ("-5"→-5), decimals ("1.5"→1) and hex
+  // ("0x10"→0) — any of which would submit a terminate against the WRONG
+  // backend pid. Require a fully-numeric token so a mistyped pid is a clean,
+  // typed rejection that never reaches the submit rpc.
+  const pidStr = (pid ?? "").trim();
+  if (!/^[0-9]+$/.test(pidStr)) {
     console.error("pid must be a number");
     process.exitCode = 1;
     return;
   }
-  await runJoeCli("terminate", null, { pid: pidNum }, opts);
+  await runJoeCli("terminate", null, { pid: parseInt(pidStr, 10) }, opts);
 });
 
 withJoeOptions(
@@ -5647,6 +5652,22 @@ withJoeOptions(
   await runJoeCli("describe", null, args, opts);
 });
 
+// history search is roadmapped for M1b; the search backend is not deployed yet.
+// Ship a recognized subcommand so the documented `pgai joe history …` example
+// degrades cleanly (an informative "not yet available" line + exit 1) instead of
+// Commander's generic "unknown command 'history'". Wire it to the rpc when M1b lands.
+withJoeOptions(
+  joe
+    .command("history <terms>")
+    .description("search prior Joe analyses, metadata-only (M1b — not yet available)")
+).action(async (_terms: string, _opts: JoeCliOpts) => {
+  console.error(
+    "Joe history search is not available yet — it is planned for M1b. " +
+      "No history-search backend is deployed; this command is a placeholder until then.",
+  );
+  process.exitCode = 1;
+});
+
 // Org-level discovery — a general postgresai command, NOT a Joe endpoint (SPEC §6).
 program
   .command("projects")

package/dist/bin/postgres-ai.js

@@ -13325,7 +13325,8 @@ __export(exports_util2, {
   resolveBaseUrls: () => resolveBaseUrls2,
   normalizeBaseUrl: () => normalizeBaseUrl2,
   maskSecret: () => maskSecret2,
-  formatHttpError: () => formatHttpError2
+  formatHttpError: () => formatHttpError2,
+  describeFetchError: () => describeFetchError2
 });
 function isHtmlContent2(text) {
   const trimmed = text.trim();
@@ -13365,6 +13366,11 @@ ${bodyDetails}`;
   }
   return errMsg + remediation;
 }
+function describeFetchError2(operation, url, err) {
+  const cause = err?.cause;
+  const detail = cause?.code || cause?.message || (err instanceof Error && err.message ? err.message : String(err));
+  return `${operation}: could not reach ${url} (${detail})`;
+}
 function maskSecret2(secret) {
   if (!secret)
     return "";
@@ -13444,7 +13450,7 @@ var {
 // package.json
 var package_default = {
   name: "postgresai",
-  version: "0.16.0-dev.7",
+  version: "0.16.0-dev.9",
   description: "postgres_ai CLI",
   license: "Apache-2.0",
   private: false,
@@ -16275,7 +16281,7 @@ var Result = import_lib.default.Result;
 var TypeOverrides = import_lib.default.TypeOverrides;
 var defaults = import_lib.default.defaults;
 // package.json
-var version = "0.16.0-dev.7";
+var version = "0.16.0-dev.9";
 var package_default2 = {
   name: "postgresai",
   version,
@@ -16465,6 +16471,11 @@ ${bodyDetails}`;
   }
   return errMsg + remediation;
 }
+function describeFetchError(operation, url, err) {
+  const cause = err?.cause;
+  const detail = cause?.code || cause?.message || (err instanceof Error && err.message ? err.message : String(err));
+  return `${operation}: could not reach ${url} (${detail})`;
+}
 function maskSecret(secret) {
   if (!secret)
     return "";
@@ -17357,11 +17368,16 @@ async function callRpc(params) {
     console.error(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
     console.error(`Debug: Request body: ${payload}`);
   }
-  const response = await fetch(url.toString(), {
-    method: "POST",
-    headers,
-    body: payload
-  });
+  let response;
+  try {
+    response = await fetch(url.toString(), {
+      method: "POST",
+      headers,
+      body: payload
+    });
+  } catch (err) {
+    throw new Error(describeFetchError(operation, base, err));
+  }
   const text = await response.text();
   if (debug) {
     console.error(`Debug: Response status: ${response.status}`);
@@ -17686,7 +17702,12 @@ async function callDblabApi(params) {
     console.error(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
     console.error(`Debug: Request body: ${body}`);
   }
-  const response = await fetch(url.toString(), { method: "POST", headers, body });
+  let response;
+  try {
+    response = await fetch(url.toString(), { method: "POST", headers, body });
+  } catch (err) {
+    throw new Error(describeFetchError(operation, base, err));
+  }
   const text = await response.text();
   if (debug) {
     console.error(`Debug: Response status: ${response.status}`);
@@ -27009,11 +27030,16 @@ async function callRpc2(params) {
     console.error(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
     console.error(`Debug: Request body: ${payload}`);
   }
-  const response = await fetch(url.toString(), {
-    method: "POST",
-    headers,
-    body: payload
-  });
+  let response;
+  try {
+    response = await fetch(url.toString(), {
+      method: "POST",
+      headers,
+      body: payload
+    });
+  } catch (err) {
+    throw new Error(describeFetchError(operation, base, err));
+  }
   const text = await response.text();
   if (debug) {
     console.error(`Debug: Response status: ${response.status}`);
@@ -27424,7 +27450,12 @@ async function callDblabApi2(params) {
     console.error(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
     console.error(`Debug: Request body: ${body}`);
   }
-  const response = await fetch(url.toString(), { method: "POST", headers, body });
+  let response;
+  try {
+    response = await fetch(url.toString(), { method: "POST", headers, body });
+  } catch (err) {
+    throw new Error(describeFetchError(operation, base, err));
+  }
   const text = await response.text();
   if (debug) {
     console.error(`Debug: Response status: ${response.status}`);
@@ -39839,13 +39870,13 @@ withJoeOptions(joe.command("activity").description("running-activity snapshot (p
   await runJoeCli("activity", null, null, opts);
 });
 withJoeOptions(joe.command("terminate <pid>").description("pg_terminate_backend(pid) on the clone")).action(async (pid, opts) => {
-  const pidNum = parseInt(pid, 10);
-  if (Number.isNaN(pidNum)) {
+  const pidStr = (pid ?? "").trim();
+  if (!/^[0-9]+$/.test(pidStr)) {
     console.error("pid must be a number");
     process.exitCode = 1;
     return;
   }
-  await runJoeCli("terminate", null, { pid: pidNum }, opts);
+  await runJoeCli("terminate", null, { pid: parseInt(pidStr, 10) }, opts);
 });
 withJoeOptions(joe.command("reset").description("reset/recreate the session's thin clone")).action(async (opts) => {
   await runJoeCli("reset", null, null, opts);
@@ -39856,6 +39887,10 @@ withJoeOptions(joe.command("describe <object>").description("\\d-family schema/r
     args.variant = opts.variant;
   await runJoeCli("describe", null, args, opts);
 });
+withJoeOptions(joe.command("history <terms>").description("search prior Joe analyses, metadata-only (M1b \u2014 not yet available)")).action(async (_terms, _opts) => {
+  console.error("Joe history search is not available yet \u2014 it is planned for M1b. " + "No history-search backend is deployed; this command is a placeholder until then.");
+  process.exitCode = 1;
+});
 program2.command("projects").description("list the org's projects (shows which have Joe ready) \u2014 org-level, not a Joe endpoint").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (opts) => {
   try {
     const rootOpts = program2.opts();

package/lib/dblab.ts

@@ -23,7 +23,7 @@
  * read/create verbs by `joe:plan` — a `PT403` surfaces as an HTTP 403 here.
  */
 
-import { formatHttpError, maskSecret, normalizeBaseUrl } from "./util";
+import { formatHttpError, maskSecret, normalizeBaseUrl, describeFetchError } from "./util";
 import { listProjects, type ProjectListItem } from "./joe";
 
 // ---------------------------------------------------------------------------
@@ -186,7 +186,14 @@ async function callDblabApi<T>(params: DblabApiCallParams): Promise<T> {
     console.error(`Debug: Request body: ${body}`);
   }
 
-  const response = await fetch(url.toString(), { method: "POST", headers, body });
+  let response: Response;
+  try {
+    response = await fetch(url.toString(), { method: "POST", headers, body });
+  } catch (err) {
+    // Transport failure (connection refused, DNS, TLS, bad host/port) — surface
+    // the real cause + URL rather than undici's opaque "fetch failed".
+    throw new Error(describeFetchError(operation, base, err));
+  }
   const text = await response.text();
 
   if (debug) {

package/lib/joe.ts

@@ -1,7 +1,7 @@
 import * as fs from "fs";
 import * as path from "path";
 import * as crypto from "node:crypto";
-import { formatHttpError, maskSecret, normalizeBaseUrl } from "./util";
+import { formatHttpError, maskSecret, normalizeBaseUrl, describeFetchError } from "./util";
 import * as config from "./config";
 
 /**
@@ -162,11 +162,19 @@ async function callRpc<T>(params: RpcCallParams): Promise<T> {
     console.error(`Debug: Request body: ${payload}`);
   }
 
-  const response = await fetch(url.toString(), {
-    method: "POST",
-    headers,
-    body: payload,
-  });
+  let response: Response;
+  try {
+    response = await fetch(url.toString(), {
+      method: "POST",
+      headers,
+      body: payload,
+    });
+  } catch (err) {
+    // A transport failure (connection refused, DNS, TLS, bad host/port) never
+    // reaches `response.ok`; undici throws with the real reason in `err.cause`.
+    // Surface it — a bare "fetch failed" hides which URL/why. See util.describeFetchError.
+    throw new Error(describeFetchError(operation, base, err));
+  }
 
   const text = await response.text();
 

package/lib/util.ts

@@ -116,6 +116,23 @@ export function formatHttpError(
   return errMsg + remediation;
 }
 
+/**
+ * Turn a low-level `fetch` failure into an actionable message. Node's fetch
+ * (undici) throws a `TypeError('fetch failed')` and stashes the real cause
+ * (`ECONNREFUSED`, DNS failure, `bad port`, TLS error, …) in `err.cause` — the
+ * opaque top-level message on its own tells the user nothing. This surfaces the
+ * cause and the URL that could not be reached, e.g.
+ *   "Failed to list projects: could not reach http://127.0.0.1:1 (ECONNREFUSED)"
+ */
+export function describeFetchError(operation: string, url: string, err: unknown): string {
+  const cause = (err as { cause?: { code?: string; message?: string } } | null | undefined)?.cause;
+  const detail =
+    cause?.code ||
+    cause?.message ||
+    (err instanceof Error && err.message ? err.message : String(err));
+  return `${operation}: could not reach ${url} (${detail})`;
+}
+
 export function maskSecret(secret: string): string {
   if (!secret) return "";
   if (secret.length <= 8) return "****";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postgresai",
-  "version": "0.16.0-dev.7",
+  "version": "0.16.0-dev.9",
   "description": "postgres_ai CLI",
   "license": "Apache-2.0",
   "private": false,

package/test/joe.cli.test.ts

@@ -141,11 +141,23 @@ describe("CLI Joe command surface (grouped under `pgai joe …`)", () => {
     const r = runCli(["joe", "--help"], isolatedEnv());
     expect(r.status).toBe(0);
     const out = `${r.stdout}\n${r.stderr}`;
-    for (const verb of ["plan", "explain", "exec", "hypo", "activity", "terminate", "reset", "describe", "result", "status"]) {
+    for (const verb of ["plan", "explain", "exec", "hypo", "activity", "terminate", "reset", "describe", "result", "status", "history"]) {
       expect(out).toContain(verb);
     }
   });
 
+  test("pgai joe history (M1b) is recognized and degrades cleanly", () => {
+    // The brief's §2 documents `pgai joe history "users email" --project 12`, but the
+    // history-search backend is M1b/not built. The command must be recognized (NOT a
+    // Commander "unknown command") and exit 1 with an informative pending message.
+    const r = runCli(["joe", "history", "users email", "--project", "12"], isolatedEnv({ PGAI_API_KEY: "k" }));
+    expect(r.status).toBe(1);
+    const out = `${r.stdout}\n${r.stderr}`;
+    expect(out).toContain("not available yet");
+    expect(out).toContain("M1b");
+    expect(out).not.toContain("unknown command");
+  });
+
   test("pgai projects prints the brief's table", async () => {
     const api = startFakeApi();
     try {
@@ -279,6 +291,26 @@ describe("CLI Joe command surface (grouped under `pgai joe …`)", () => {
     }
   });
 
+  test("joe terminate rejects a non-numeric / trailing-garbage pid (no submit)", async () => {
+    // A pid must be a bare non-negative integer. parseInt() would silently accept
+    // "12x"→12, "-5"→-5, "1.5"→1 and submit a WRONG pg_terminate_backend target.
+    // Those must be a clean, typed rejection that never reaches the submit rpc.
+    const api = startFakeApi();
+    try {
+      for (const bad of ["12x", "abc", "1.5", "0x10", "  "]) {
+        const r = await runCliAsync(
+          ["joe", "terminate", bad, "--project", "12"],
+          isolatedEnv({ PGAI_API_KEY: "k", PGAI_API_BASE_URL: api.baseUrl })
+        );
+        expect(r.status).toBe(1);
+        expect(`${r.stdout}\n${r.stderr}`).toContain("pid must be a number");
+      }
+      expect(api.requests.some((x) => x.pathname.endsWith("/rpc/joe_command_submit"))).toBe(false);
+    } finally {
+      api.stop();
+    }
+  });
+
   test("joe describe maps args.object (and --variant)", async () => {
     const api = startFakeApi();
     try {

package/test/util.test.ts

@@ -1,6 +1,31 @@
 import { describe, expect, test } from "bun:test";
 
-import { formatHttpError } from "../lib/util";
+import { formatHttpError, describeFetchError } from "../lib/util";
+
+describe("describeFetchError", () => {
+  test("surfaces the connection cause + url instead of a bare 'fetch failed'", () => {
+    // Node's fetch (undici) throws TypeError('fetch failed') and stashes the real
+    // reason (ECONNREFUSED etc.) in err.cause — the CLI must surface it, not the
+    // opaque top-level message.
+    const err = Object.assign(new TypeError("fetch failed"), {
+      cause: { code: "ECONNREFUSED", message: "connect ECONNREFUSED 127.0.0.1:1" },
+    });
+    const msg = describeFetchError("Failed to list projects", "http://127.0.0.1:1", err);
+    expect(msg).toContain("Failed to list projects");
+    expect(msg).toContain("could not reach http://127.0.0.1:1");
+    expect(msg).toContain("ECONNREFUSED");
+    expect(msg).not.toBe("fetch failed");
+  });
+
+  test("falls back to cause.message, then to the error message", () => {
+    const withMsg = Object.assign(new TypeError("fetch failed"), {
+      cause: { message: "bad port" },
+    });
+    expect(describeFetchError("op", "http://h:1", withMsg)).toContain("bad port");
+    const bare = new Error("boom");
+    expect(describeFetchError("op", "http://h", bare)).toContain("boom");
+  });
+});
 
 describe("formatHttpError", () => {
   test("appends auth remediation hint on 401 with JSON body", () => {