postgresai 0.16.0-dev.6 → 0.16.0-dev.8

package/bin/postgres-ai.ts

@@ -5647,6 +5647,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

@@ -13331,33 +13331,38 @@ function isHtmlContent2(text) {
   const trimmed = text.trim();
   return trimmed.startsWith("<!DOCTYPE") || trimmed.startsWith("<html") || trimmed.startsWith("<HTML");
 }
-function formatHttpError2(operation, status, responseBody) {
-  const statusMessage = HTTP_STATUS_MESSAGES2[status] || "Request failed";
-  let errMsg = `${operation}: HTTP ${status} - ${statusMessage}`;
+function formatHttpError2(operation, status, responseBody, statusText) {
+  const generic = HTTP_STATUS_MESSAGES2[status] || "Request failed";
   const remediation = status === 401 ? `
 ${AUTH_REMEDIATION_HINT2}` : "";
-  if (responseBody) {
-    if (isHtmlContent2(responseBody)) {
-      return errMsg + remediation;
-    }
+  let bodyMessage;
+  let bodyDetails;
+  if (responseBody && !isHtmlContent2(responseBody)) {
     try {
       const errObj = JSON.parse(responseBody);
-      const message = errObj.message || errObj.error || errObj.detail;
-      if (message && typeof message === "string") {
-        errMsg += `
-${message}`;
-      } else {
-        errMsg += `
-${JSON.stringify(errObj, null, 2)}`;
+      const message = errObj.message ?? errObj.error;
+      if (typeof message === "string" && message.trim().length > 0) {
+        bodyMessage = message.trim();
+      }
+      const details = errObj.details ?? errObj.detail;
+      if (typeof details === "string" && details.trim().length > 0) {
+        bodyDetails = details.trim();
       }
     } catch {
       const trimmed = responseBody.trim();
       if (trimmed.length > 0 && trimmed.length < 500) {
-        errMsg += `
-${trimmed}`;
+        bodyDetails = trimmed;
       }
     }
   }
+  const trimmedReason = statusText?.trim();
+  const reasonPhrase = trimmedReason && trimmedReason !== STANDARD_REASON_PHRASES2[status] && trimmedReason !== generic ? trimmedReason : undefined;
+  const headline = bodyMessage ?? reasonPhrase ?? generic;
+  let errMsg = `${operation}: HTTP ${status} - ${headline}`;
+  if (bodyDetails && bodyDetails !== headline) {
+    errMsg += `
+${bodyDetails}`;
+  }
   return errMsg + remediation;
 }
 function maskSecret2(secret) {
@@ -13391,7 +13396,7 @@ function resolveBaseUrls2(opts, cfg, defaults2 = {}) {
     storageBaseUrl: normalizeBaseUrl2(storageCandidate)
   };
 }
-var HTTP_STATUS_MESSAGES2, AUTH_REMEDIATION_HINT2 = "Run 'postgresai auth' to (re)authenticate, or set/update PGAI_API_KEY.";
+var HTTP_STATUS_MESSAGES2, AUTH_REMEDIATION_HINT2 = "Run 'postgresai auth' to (re)authenticate, or set/update PGAI_API_KEY.", STANDARD_REASON_PHRASES2;
 var init_util = __esm(() => {
   HTTP_STATUS_MESSAGES2 = {
     400: "Bad Request",
@@ -13405,6 +13410,20 @@ var init_util = __esm(() => {
     503: "Service Unavailable - server temporarily unavailable",
     504: "Gateway Timeout - server temporarily unavailable"
   };
+  STANDARD_REASON_PHRASES2 = {
+    400: "Bad Request",
+    401: "Unauthorized",
+    403: "Forbidden",
+    404: "Not Found",
+    408: "Request Timeout",
+    409: "Conflict",
+    413: "Payload Too Large",
+    429: "Too Many Requests",
+    500: "Internal Server Error",
+    502: "Bad Gateway",
+    503: "Service Unavailable",
+    504: "Gateway Timeout"
+  };
 });
 
 // node_modules/commander/esm.mjs
@@ -13425,7 +13444,7 @@ var {
 // package.json
 var package_default = {
   name: "postgresai",
-  version: "0.16.0-dev.6",
+  version: "0.16.0-dev.8",
   description: "postgres_ai CLI",
   license: "Apache-2.0",
   private: false,
@@ -16256,7 +16275,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.6";
+var version = "0.16.0-dev.8";
 var package_default2 = {
   name: "postgresai",
   version,
@@ -16398,33 +16417,52 @@ function isHtmlContent(text) {
   return trimmed.startsWith("<!DOCTYPE") || trimmed.startsWith("<html") || trimmed.startsWith("<HTML");
 }
 var AUTH_REMEDIATION_HINT = "Run 'postgresai auth' to (re)authenticate, or set/update PGAI_API_KEY.";
-function formatHttpError(operation, status, responseBody) {
-  const statusMessage = HTTP_STATUS_MESSAGES[status] || "Request failed";
-  let errMsg = `${operation}: HTTP ${status} - ${statusMessage}`;
+var STANDARD_REASON_PHRASES = {
+  400: "Bad Request",
+  401: "Unauthorized",
+  403: "Forbidden",
+  404: "Not Found",
+  408: "Request Timeout",
+  409: "Conflict",
+  413: "Payload Too Large",
+  429: "Too Many Requests",
+  500: "Internal Server Error",
+  502: "Bad Gateway",
+  503: "Service Unavailable",
+  504: "Gateway Timeout"
+};
+function formatHttpError(operation, status, responseBody, statusText) {
+  const generic = HTTP_STATUS_MESSAGES[status] || "Request failed";
   const remediation = status === 401 ? `
 ${AUTH_REMEDIATION_HINT}` : "";
-  if (responseBody) {
-    if (isHtmlContent(responseBody)) {
-      return errMsg + remediation;
-    }
+  let bodyMessage;
+  let bodyDetails;
+  if (responseBody && !isHtmlContent(responseBody)) {
     try {
       const errObj = JSON.parse(responseBody);
-      const message = errObj.message || errObj.error || errObj.detail;
-      if (message && typeof message === "string") {
-        errMsg += `
-${message}`;
-      } else {
-        errMsg += `
-${JSON.stringify(errObj, null, 2)}`;
+      const message = errObj.message ?? errObj.error;
+      if (typeof message === "string" && message.trim().length > 0) {
+        bodyMessage = message.trim();
+      }
+      const details = errObj.details ?? errObj.detail;
+      if (typeof details === "string" && details.trim().length > 0) {
+        bodyDetails = details.trim();
       }
     } catch {
       const trimmed = responseBody.trim();
       if (trimmed.length > 0 && trimmed.length < 500) {
-        errMsg += `
-${trimmed}`;
+        bodyDetails = trimmed;
       }
     }
   }
+  const trimmedReason = statusText?.trim();
+  const reasonPhrase = trimmedReason && trimmedReason !== STANDARD_REASON_PHRASES[status] && trimmedReason !== generic ? trimmedReason : undefined;
+  const headline = bodyMessage ?? reasonPhrase ?? generic;
+  let errMsg = `${operation}: HTTP ${status} - ${headline}`;
+  if (bodyDetails && bodyDetails !== headline) {
+    errMsg += `
+${bodyDetails}`;
+  }
   return errMsg + remediation;
 }
 function maskSecret(secret) {
@@ -17330,7 +17368,7 @@ async function callRpc(params) {
     console.error(`Debug: Response body: ${text}`);
   }
   if (!response.ok) {
-    throw new Error(formatHttpError(operation, response.status, text));
+    throw new Error(formatHttpError(operation, response.status, text, response.statusText));
   }
   try {
     return JSON.parse(text);
@@ -17655,7 +17693,7 @@ async function callDblabApi(params) {
     console.error(`Debug: Response body: ${text}`);
   }
   if (!response.ok) {
-    throw new Error(formatHttpError(operation, response.status, text));
+    throw new Error(formatHttpError(operation, response.status, text, response.statusText));
   }
   if (text.trim() === "") {
     return null;
@@ -26982,7 +27020,7 @@ async function callRpc2(params) {
     console.error(`Debug: Response body: ${text}`);
   }
   if (!response.ok) {
-    throw new Error(formatHttpError(operation, response.status, text));
+    throw new Error(formatHttpError(operation, response.status, text, response.statusText));
   }
   try {
     return JSON.parse(text);
@@ -27393,7 +27431,7 @@ async function callDblabApi2(params) {
     console.error(`Debug: Response body: ${text}`);
   }
   if (!response.ok) {
-    throw new Error(formatHttpError(operation, response.status, text));
+    throw new Error(formatHttpError(operation, response.status, text, response.statusText));
   }
   if (text.trim() === "") {
     return null;
@@ -39818,6 +39856,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

@@ -196,8 +196,10 @@ async function callDblabApi<T>(params: DblabApiCallParams): Promise<T> {
 
   if (!response.ok) {
     // PostgREST maps custom `PTxyz` sqlstates to HTTP status `xyz`, so a missing
-    // `joe:admin` scope on a destructive verb surfaces here as HTTP 403.
-    throw new Error(formatHttpError(operation, response.status, text));
+    // `joe:admin` scope on a destructive verb surfaces here as HTTP 403. The
+    // RPC's user-facing message rides in the HTTP reason phrase (statusText),
+    // not the JSON body — pass it through.
+    throw new Error(formatHttpError(operation, response.status, text, response.statusText));
   }
 
   // Some DBLab actions (reset/destroy) reply with an empty body on success.

package/lib/joe.ts

@@ -177,9 +177,10 @@ async function callRpc<T>(params: RpcCallParams): Promise<T> {
 
   if (!response.ok) {
     // PostgREST maps a custom `PTxyz` sqlstate to HTTP status `xyz`, so PT403 →
-    // HTTP 403, PT404 → 404, PT429 → 429, etc. formatHttpError surfaces the JSON
-    // `message` (e.g. the "AI features disabled for this org" text for AC36).
-    throw new Error(formatHttpError(operation, response.status, text));
+    // HTTP 403, PT404 → 404, PT429 → 429, etc. The RPC's user-facing message
+    // (e.g. the "AI features disabled for this org" text for AC36) rides in the
+    // HTTP reason phrase (statusText), not the JSON body — pass it through.
+    throw new Error(formatHttpError(operation, response.status, text, response.statusText));
   }
 
   try {

package/lib/util.ts

@@ -28,42 +28,91 @@ function isHtmlContent(text: string): boolean {
  */
 const AUTH_REMEDIATION_HINT = "Run 'postgresai auth' to (re)authenticate, or set/update PGAI_API_KEY.";
 
+/**
+ * Standard HTTP reason phrases we should NOT treat as a server-authored
+ * message: when the reason phrase equals the stock text for the status, it
+ * carries no extra information, so we prefer the friendlier generic label.
+ */
+const STANDARD_REASON_PHRASES: Record<number, string> = {
+  400: "Bad Request",
+  401: "Unauthorized",
+  403: "Forbidden",
+  404: "Not Found",
+  408: "Request Timeout",
+  409: "Conflict",
+  413: "Payload Too Large",
+  429: "Too Many Requests",
+  500: "Internal Server Error",
+  502: "Bad Gateway",
+  503: "Service Unavailable",
+  504: "Gateway Timeout",
+};
+
 /**
  * Format an HTTP error response into a clean, developer-friendly message.
  * Handles HTML error pages (e.g., from Cloudflare) by showing just the status code and message.
  * For 401 responses, appends a remediation hint pointing at `postgresai auth`.
+ *
+ * The platform's PostgREST layer uses the `PTxyz` custom-status convention:
+ * a raised `PT403`/`PT404`/… maps to the HTTP status and delivers the RPC's
+ * user-facing message in the HTTP **reason phrase** (`response.statusText`),
+ * NOT the JSON body — the body carries only `hint`/`details` (no `message`).
+ * So callers pass `statusText` and it is preferred over the built-in generic
+ * label. Headline precedence: JSON body `message` → custom reason phrase →
+ * generic label; the JSON `details` (plural, PostgREST's spelling) is shown as
+ * a supplementary line.
  */
-export function formatHttpError(operation: string, status: number, responseBody?: string): string {
-  const statusMessage = HTTP_STATUS_MESSAGES[status] || "Request failed";
-  let errMsg = `${operation}: HTTP ${status} - ${statusMessage}`;
+export function formatHttpError(
+  operation: string,
+  status: number,
+  responseBody?: string,
+  statusText?: string
+): string {
+  const generic = HTTP_STATUS_MESSAGES[status] || "Request failed";
   const remediation = status === 401 ? `\n${AUTH_REMEDIATION_HINT}` : "";
 
-  if (responseBody) {
-    // If it's HTML (like Cloudflare error pages), don't dump the raw HTML
-    if (isHtmlContent(responseBody)) {
-      // Just use the status message, don't append HTML
-      return errMsg + remediation;
-    }
+  let bodyMessage: string | undefined;
+  let bodyDetails: string | undefined;
 
-    // Try to parse as JSON for structured error info
+  if (responseBody && !isHtmlContent(responseBody)) {
+    // If it's HTML (like Cloudflare error pages), we fall through with no
+    // parsed fields and never dump the raw HTML.
     try {
       const errObj = JSON.parse(responseBody);
-      // Extract common error message fields
-      const message = errObj.message || errObj.error || errObj.detail;
-      if (message && typeof message === "string") {
-        errMsg += `\n${message}`;
-      } else {
-        errMsg += `\n${JSON.stringify(errObj, null, 2)}`;
+      const message = errObj.message ?? errObj.error;
+      if (typeof message === "string" && message.trim().length > 0) {
+        bodyMessage = message.trim();
+      }
+      // PostgREST spells it `details` (plural); accept `detail` too.
+      const details = errObj.details ?? errObj.detail;
+      if (typeof details === "string" && details.trim().length > 0) {
+        bodyDetails = details.trim();
       }
     } catch {
-      // Plain text error - append it if it's short and useful
+      // Plain text error - treat it as the details line if short and useful.
       const trimmed = responseBody.trim();
       if (trimmed.length > 0 && trimmed.length < 500) {
-        errMsg += `\n${trimmed}`;
+        bodyDetails = trimmed;
       }
     }
   }
 
+  // A custom reason phrase (PTxyz message) is meaningful only when it differs
+  // from the stock HTTP reason phrase for this status.
+  const trimmedReason = statusText?.trim();
+  const reasonPhrase =
+    trimmedReason &&
+    trimmedReason !== STANDARD_REASON_PHRASES[status] &&
+    trimmedReason !== generic
+      ? trimmedReason
+      : undefined;
+
+  const headline = bodyMessage ?? reasonPhrase ?? generic;
+  let errMsg = `${operation}: HTTP ${status} - ${headline}`;
+  if (bodyDetails && bodyDetails !== headline) {
+    errMsg += `\n${bodyDetails}`;
+  }
+
   return errMsg + remediation;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postgresai",
-  "version": "0.16.0-dev.6",
+  "version": "0.16.0-dev.8",
   "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 {

package/test/util.test.ts

@@ -41,4 +41,39 @@ describe("formatHttpError", () => {
     expect(msg.indexOf("Invalid token")).toBeGreaterThan(-1);
     expect(msg.indexOf("Invalid token")).toBeLessThan(msg.indexOf("Run 'postgresai auth'"));
   });
+
+  // PostgREST v9's PTxyz custom-status convention carries the RPC's user-facing
+  // `message` in the HTTP reason phrase (statusText); the JSON body holds only
+  // `hint`/`details` (no `message`/`code`). The formatter must surface the
+  // reason phrase as the headline instead of a hardcoded generic label, and
+  // still show the `details` (plural) line.
+  test("surfaces the PostgREST PTxyz reason-phrase message, not a generic label", () => {
+    const msg = formatHttpError(
+      "Failed to submit plan command",
+      403,
+      '{"hint":null,"details":"The LLM-facing Joe surface is gated on the organization\'s ai_enabled setting."}',
+      "AI features disabled for this org — enable in AI Assistant Settings"
+    );
+
+    expect(msg).toContain("HTTP 403");
+    expect(msg).toContain("AI features disabled for this org — enable in AI Assistant Settings");
+    // the real reason must not be masked by the hardcoded generic label
+    expect(msg).not.toContain("Forbidden - access denied");
+    // the supplementary `details` (plural) line is still shown
+    expect(msg).toContain("gated on the organization's ai_enabled setting");
+    // and we never dump the raw JSON object
+    expect(msg).not.toContain('"hint"');
+  });
+
+  test("prefers a JSON body `message` over the reason phrase when both exist", () => {
+    const msg = formatHttpError("op", 400, '{"message":"real message","details":"more"}', "Bad Request");
+    expect(msg).toContain("real message");
+    expect(msg).toContain("more");
+  });
+
+  test("falls back to the generic label for a standard (non-custom) reason phrase", () => {
+    // a bare standard reason phrase must not replace the friendlier generic label
+    const msg = formatHttpError("op", 403, undefined, "Forbidden");
+    expect(msg).toContain("Forbidden - access denied");
+  });
 });