fix(cli): append 'postgresai auth' remediation hint to 401 errors

Sarumyan · Sarumyan · commit 6415233425bf · 2026-06-12T16:11:25.000Z
diff --git a/cli/lib/util.ts b/cli/lib/util.ts
@@ -22,19 +22,27 @@ function isHtmlContent(text: string): boolean {
   return trimmed.startsWith("<!DOCTYPE") || trimmed.startsWith("<html") || trimmed.startsWith("<HTML");
 }
 
+/**
+ * Remediation hint appended to 401 errors so both humans and AI agents
+ * (MCP tool callers) know how to recover from an invalid/stale API key.
+ */
+const AUTH_REMEDIATION_HINT = "Run 'postgresai auth' to (re)authenticate, or set/update PGAI_API_KEY.";
+
 /**
  * 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`.
  */
 export function formatHttpError(operation: string, status: number, responseBody?: string): string {
   const statusMessage = HTTP_STATUS_MESSAGES[status] || "Request failed";
   let errMsg = `${operation}: HTTP ${status} - ${statusMessage}`;
+  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;
+      return errMsg + remediation;
     }
 
     // Try to parse as JSON for structured error info
@@ -56,7 +64,7 @@ export function formatHttpError(operation: string, status: number, responseBody?
     }
   }
 
-  return errMsg;
+  return errMsg + remediation;
 }
 
 export function maskSecret(secret: string): string {
@@ -124,4 +132,3 @@ export function resolveBaseUrls(
     storageBaseUrl: normalizeBaseUrl(storageCandidate),
   };
 }
-
diff --git a/cli/test/mcp-server.test.ts b/cli/test/mcp-server.test.ts
@@ -238,6 +238,8 @@ describe("MCP Server", () => {
 
       expect(response.isError).toBe(true);
       expect(getResponseText(response)).toContain("401");
+      // Agent-facing remediation: invalid key must point at re-auth, not dead-end
+      expect(getResponseText(response)).toContain("Run 'postgresai auth'");
 
       readConfigSpy.mockRestore();
     });
@@ -1678,6 +1680,8 @@ describe("MCP Server", () => {
 
       expect(response.isError).toBe(true);
       expect(getResponseText(response)).toContain("401");
+      // Agent-facing remediation: invalid key must point at re-auth, not dead-end
+      expect(getResponseText(response)).toContain("Run 'postgresai auth'");
 
       readConfigSpy.mockRestore();
     });
diff --git a/cli/test/util.test.ts b/cli/test/util.test.ts
@@ -0,0 +1,44 @@
+import { describe, expect, test } from "bun:test";
+
+import { formatHttpError } from "../lib/util";
+
+describe("formatHttpError", () => {
+  test("appends auth remediation hint on 401 with JSON body", () => {
+    const msg = formatHttpError(
+      "Failed to fetch issues",
+      401,
+      '{"hint": "Please check validity of token", "details": "Invalid token"}'
+    );
+
+    expect(msg).toContain("HTTP 401");
+    expect(msg).toContain("Run 'postgresai auth'");
+    expect(msg).toContain("PGAI_API_KEY");
+  });
+
+  test("appends auth remediation hint on 401 with HTML body (early-return path)", () => {
+    const msg = formatHttpError("Failed to fetch issues", 401, "<html><body>Unauthorized</body></html>");
+
+    expect(msg).toContain("HTTP 401");
+    expect(msg).toContain("Run 'postgresai auth'");
+  });
+
+  test("appends auth remediation hint on 401 without body", () => {
+    const msg = formatHttpError("Failed to fetch issues", 401);
+
+    expect(msg).toContain("Run 'postgresai auth'");
+  });
+
+  test("does not append auth hint for non-401 statuses", () => {
+    expect(formatHttpError("Failed to fetch issues", 403, '{"message": "denied"}')).not.toContain(
+      "Run 'postgresai auth'"
+    );
+    expect(formatHttpError("Failed to fetch issues", 500)).not.toContain("Run 'postgresai auth'");
+  });
+
+  test("keeps structured JSON error details before the hint", () => {
+    const msg = formatHttpError("Failed to fetch issues", 401, '{"message": "Invalid token"}');
+
+    expect(msg.indexOf("Invalid token")).toBeGreaterThan(-1);
+    expect(msg.indexOf("Invalid token")).toBeLessThan(msg.indexOf("Run 'postgresai auth'"));
+  });
+});
