postgresai 0.14.0-dev.56 → 0.14.0-dev.57

package/lib/mcp-server.ts

@@ -1,6 +1,6 @@
 import pkg from "../package.json";
 import * as config from "./config";
-import { fetchIssues, fetchIssueComments, createIssueComment, fetchIssue } from "./issues";
+import { fetchIssues, fetchIssueComments, createIssueComment, fetchIssue, createIssue, updateIssue, updateIssueComment } from "./issues";
 import { resolveBaseUrls } from "./util";
 
 // MCP SDK imports - Bun handles these directly
@@ -8,27 +8,165 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 
-interface RootOptsLike {
+export interface RootOptsLike {
   apiKey?: string;
   apiBaseUrl?: string;
 }
 
+// Interpret escape sequences (e.g., \n -> newline). Input comes from JSON, but
+// we still normalize common escapes for consistency.
+export const interpretEscapes = (str: string): string =>
+  (str || "")
+    .replace(/\\n/g, "\n")
+    .replace(/\\t/g, "\t")
+    .replace(/\\r/g, "\r")
+    .replace(/\\"/g, '"')
+    .replace(/\\'/g, "'");
+
+export interface McpToolRequest {
+  params: {
+    name: string;
+    arguments?: Record<string, unknown>;
+  };
+}
+
+export interface McpToolResponse {
+  content: Array<{ type: string; text: string }>;
+  isError?: boolean;
+}
+
+/** Handle MCP tool calls - exported for testing */
+export async function handleToolCall(
+  req: McpToolRequest,
+  rootOpts?: RootOptsLike,
+  extra?: { debug?: boolean }
+): Promise<McpToolResponse> {
+  const toolName = req.params.name;
+  const args = (req.params.arguments as Record<string, unknown>) || {};
+
+  const cfg = config.readConfig();
+  const apiKey = (rootOpts?.apiKey || process.env.PGAI_API_KEY || cfg.apiKey || "").toString();
+  const { apiBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+
+  const debug = Boolean(args.debug ?? extra?.debug);
+
+  if (!apiKey) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: "API key is required. Run 'pgai auth' or set PGAI_API_KEY.",
+        },
+      ],
+      isError: true,
+    };
+  }
+
+  try {
+    if (toolName === "list_issues") {
+      const issues = await fetchIssues({ apiKey, apiBaseUrl, debug });
+      return { content: [{ type: "text", text: JSON.stringify(issues, null, 2) }] };
+    }
+
+    if (toolName === "view_issue") {
+      const issueId = String(args.issue_id || "").trim();
+      if (!issueId) {
+        return { content: [{ type: "text", text: "issue_id is required" }], isError: true };
+      }
+      const issue = await fetchIssue({ apiKey, apiBaseUrl, issueId, debug });
+      if (!issue) {
+        return { content: [{ type: "text", text: "Issue not found" }], isError: true };
+      }
+      const comments = await fetchIssueComments({ apiKey, apiBaseUrl, issueId, debug });
+      const combined = { issue, comments };
+      return { content: [{ type: "text", text: JSON.stringify(combined, null, 2) }] };
+    }
+
+    if (toolName === "post_issue_comment") {
+      const issueId = String(args.issue_id || "").trim();
+      const rawContent = String(args.content || "");
+      const parentCommentId = args.parent_comment_id ? String(args.parent_comment_id) : undefined;
+      if (!issueId) {
+        return { content: [{ type: "text", text: "issue_id is required" }], isError: true };
+      }
+      if (!rawContent) {
+        return { content: [{ type: "text", text: "content is required" }], isError: true };
+      }
+      const content = interpretEscapes(rawContent);
+      const result = await createIssueComment({ apiKey, apiBaseUrl, issueId, content, parentCommentId, debug });
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+
+    if (toolName === "create_issue") {
+      const rawTitle = String(args.title || "").trim();
+      if (!rawTitle) {
+        return { content: [{ type: "text", text: "title is required" }], isError: true };
+      }
+      const title = interpretEscapes(rawTitle);
+      const rawDescription = args.description ? String(args.description) : undefined;
+      const description = rawDescription ? interpretEscapes(rawDescription) : undefined;
+      const projectId = args.project_id !== undefined ? Number(args.project_id) : undefined;
+      const labels = Array.isArray(args.labels) ? args.labels.map(String) : undefined;
+      // Get orgId from args or fall back to config
+      const orgId = args.org_id !== undefined ? Number(args.org_id) : cfg.orgId;
+      // Note: orgId=0 is technically valid (though unlikely), so don't use falsy check
+      if (orgId === undefined || orgId === null || Number.isNaN(orgId)) {
+        return { content: [{ type: "text", text: "org_id is required. Either provide it as a parameter or run 'pgai auth' to set it in config." }], isError: true };
+      }
+      const result = await createIssue({ apiKey, apiBaseUrl, title, orgId, description, projectId, labels, debug });
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+
+    if (toolName === "update_issue") {
+      const issueId = String(args.issue_id || "").trim();
+      if (!issueId) {
+        return { content: [{ type: "text", text: "issue_id is required" }], isError: true };
+      }
+      const rawTitle = args.title !== undefined ? String(args.title) : undefined;
+      const title = rawTitle !== undefined ? interpretEscapes(rawTitle) : undefined;
+      const rawDescription = args.description !== undefined ? String(args.description) : undefined;
+      const description = rawDescription !== undefined ? interpretEscapes(rawDescription) : undefined;
+      const status = args.status !== undefined ? Number(args.status) : undefined;
+      const labels = Array.isArray(args.labels) ? args.labels.map(String) : undefined;
+      // Validate that at least one update field is provided
+      if (title === undefined && description === undefined && status === undefined && labels === undefined) {
+        return { content: [{ type: "text", text: "At least one field to update is required (title, description, status, or labels)" }], isError: true };
+      }
+      // Validate status value if provided (check for NaN and valid values)
+      if (status !== undefined && (Number.isNaN(status) || (status !== 0 && status !== 1))) {
+        return { content: [{ type: "text", text: "status must be 0 (open) or 1 (closed)" }], isError: true };
+      }
+      const result = await updateIssue({ apiKey, apiBaseUrl, issueId, title, description, status, labels, debug });
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+
+    if (toolName === "update_issue_comment") {
+      const commentId = String(args.comment_id || "").trim();
+      const rawContent = String(args.content || "");
+      if (!commentId) {
+        return { content: [{ type: "text", text: "comment_id is required" }], isError: true };
+      }
+      if (!rawContent.trim()) {
+        return { content: [{ type: "text", text: "content is required" }], isError: true };
+      }
+      const content = interpretEscapes(rawContent);
+      const result = await updateIssueComment({ apiKey, apiBaseUrl, commentId, content, debug });
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+
+    throw new Error(`Unknown tool: ${toolName}`);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { content: [{ type: "text", text: message }], isError: true };
+  }
+}
+
 export async function startMcpServer(rootOpts?: RootOptsLike, extra?: { debug?: boolean }): Promise<void> {
   const server = new Server(
     { name: "postgresai-mcp", version: pkg.version },
     { capabilities: { tools: {} } }
   );
 
-  // Interpret escape sequences (e.g., \n -> newline). Input comes from JSON, but
-  // we still normalize common escapes for consistency.
-  const interpretEscapes = (str: string): string =>
-    (str || "")
-      .replace(/\\n/g, "\n")
-      .replace(/\\t/g, "\t")
-      .replace(/\\r/g, "\r")
-      .replace(/\\"/g, '"')
-      .replace(/\\'/g, "'");
-
   server.setRequestHandler(ListToolsRequestSchema, async () => {
     return {
       tools: [
@@ -71,73 +209,69 @@ export async function startMcpServer(rootOpts?: RootOptsLike, extra?: { debug?:
             additionalProperties: false,
           },
         },
+        {
+          name: "create_issue",
+          description: "Create a new issue in PostgresAI",
+          inputSchema: {
+            type: "object",
+            properties: {
+              title: { type: "string", description: "Issue title (required)" },
+              description: { type: "string", description: "Issue description (supports \\n as newline)" },
+              org_id: { type: "number", description: "Organization ID (uses config value if not provided)" },
+              project_id: { type: "number", description: "Project ID to associate the issue with" },
+              labels: {
+                type: "array",
+                items: { type: "string" },
+                description: "Labels to apply to the issue",
+              },
+              debug: { type: "boolean", description: "Enable verbose debug logs" },
+            },
+            required: ["title"],
+            additionalProperties: false,
+          },
+        },
+        {
+          name: "update_issue",
+          description: "Update an existing issue (title, description, status, labels). Use status=1 to close, status=0 to reopen.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              issue_id: { type: "string", description: "Issue ID (UUID)" },
+              title: { type: "string", description: "New title (supports \\n as newline)" },
+              description: { type: "string", description: "New description (supports \\n as newline)" },
+              status: { type: "number", description: "Status: 0=open, 1=closed" },
+              labels: {
+                type: "array",
+                items: { type: "string" },
+                description: "Labels to set on the issue",
+              },
+              debug: { type: "boolean", description: "Enable verbose debug logs" },
+            },
+            required: ["issue_id"],
+            additionalProperties: false,
+          },
+        },
+        {
+          name: "update_issue_comment",
+          description: "Update an existing issue comment",
+          inputSchema: {
+            type: "object",
+            properties: {
+              comment_id: { type: "string", description: "Comment ID (UUID)" },
+              content: { type: "string", description: "New comment text (supports \\n as newline)" },
+              debug: { type: "boolean", description: "Enable verbose debug logs" },
+            },
+            required: ["comment_id", "content"],
+            additionalProperties: false,
+          },
+        },
       ],
     };
   });
 
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   server.setRequestHandler(CallToolRequestSchema, async (req: any) => {
-    const toolName = req.params.name;
-    const args = (req.params.arguments as Record<string, unknown>) || {};
-
-    const cfg = config.readConfig();
-    const apiKey = (rootOpts?.apiKey || process.env.PGAI_API_KEY || cfg.apiKey || "").toString();
-    const { apiBaseUrl } = resolveBaseUrls(rootOpts, cfg);
-
-    const debug = Boolean(args.debug ?? extra?.debug);
-
-    if (!apiKey) {
-      return {
-        content: [
-          {
-            type: "text",
-            text: "API key is required. Run 'pgai auth' or set PGAI_API_KEY.",
-          },
-        ],
-        isError: true,
-      };
-    }
-
-    try {
-      if (toolName === "list_issues") {
-        const issues = await fetchIssues({ apiKey, apiBaseUrl, debug });
-        return { content: [{ type: "text", text: JSON.stringify(issues, null, 2) }] };
-      }
-
-      if (toolName === "view_issue") {
-        const issueId = String(args.issue_id || "").trim();
-        if (!issueId) {
-          return { content: [{ type: "text", text: "issue_id is required" }], isError: true };
-        }
-        const issue = await fetchIssue({ apiKey, apiBaseUrl, issueId, debug });
-        if (!issue) {
-          return { content: [{ type: "text", text: "Issue not found" }], isError: true };
-        }
-        const comments = await fetchIssueComments({ apiKey, apiBaseUrl, issueId, debug });
-        const combined = { issue, comments };
-        return { content: [{ type: "text", text: JSON.stringify(combined, null, 2) }] };
-      }
-
-      if (toolName === "post_issue_comment") {
-        const issueId = String(args.issue_id || "").trim();
-        const rawContent = String(args.content || "");
-        const parentCommentId = args.parent_comment_id ? String(args.parent_comment_id) : undefined;
-        if (!issueId) {
-          return { content: [{ type: "text", text: "issue_id is required" }], isError: true };
-        }
-        if (!rawContent) {
-          return { content: [{ type: "text", text: "content is required" }], isError: true };
-        }
-        const content = interpretEscapes(rawContent);
-        const result = await createIssueComment({ apiKey, apiBaseUrl, issueId, content, parentCommentId, debug });
-        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
-      }
-
-      throw new Error(`Unknown tool: ${toolName}`);
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      return { content: [{ type: "text", text: message }], isError: true };
-    }
+    return handleToolCall(req, rootOpts, extra);
   });
 
   const transport = new StdioServerTransport();

package/lib/metrics-embedded.ts

@@ -1,6 +1,6 @@
 // AUTO-GENERATED FILE - DO NOT EDIT
 // Generated from config/pgwatch-prometheus/metrics.yml by scripts/embed-metrics.ts
-// Generated at: 2025-12-29T19:46:00.537Z
+// Generated at: 2025-12-29T21:47:36.417Z
 
 /**
  * Metric definition from metrics.yml

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postgresai",
-  "version": "0.14.0-dev.56",
+  "version": "0.14.0-dev.57",
   "description": "postgres_ai CLI",
   "license": "Apache-2.0",
   "private": false,

package/sql/05.helpers.sql

@@ -3,11 +3,17 @@
 -- operations they don't have direct permissions for.
 
 /*
- * pgai_explain_generic
+ * 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');
@@ -39,6 +45,7 @@ declare
   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;
@@ -48,6 +55,24 @@ begin
       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(
@@ -64,15 +89,14 @@ begin
       v_hypo_result.indexname, v_hypo_result.indexrelid;
   end if;
 
-  -- Build and execute explain query based on format
-  -- Output is preserved exactly as EXPLAIN returns it
+  -- Build and execute EXPLAIN query
+  -- Note: EXPLAIN is read-only (plans but doesn't execute), making this safe
   begin
     if lower(format) = 'json' then
-      v_explain_query := 'explain (verbose, settings, generic_plan, format json) ' || query;
-      execute v_explain_query into result;
+      execute 'explain (verbose, settings, generic_plan, format json) ' || v_clean_query
+        into result;
     else
-      v_explain_query := 'explain (verbose, settings, generic_plan) ' || query;
-      for v_line in execute v_explain_query loop
+      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');

package/test/init.integration.test.ts

@@ -396,4 +396,102 @@ describe.skipIf(skipTests)("integration: prepare-db", () => {
       await pg.cleanup();
     }
   });
+
+  test("explain_generic validates input and prevents SQL injection", async () => {
+    pg = await createTempPostgres();
+
+    try {
+      // Run init first
+      {
+        const r = runCliInit([pg.adminUri, "--password", "pw1", "--skip-optional-permissions"]);
+        expect(r.status).toBe(0);
+      }
+
+      const c = new Client({ connectionString: pg.adminUri });
+      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);
+        }
+
+      } finally {
+        await c.end();
+      }
+    } finally {
+      await pg.cleanup();
+    }
+  });
 });

package/test/init.test.ts

@@ -337,9 +337,81 @@ describe("CLI commands", () => {
     expect(r.stdout).toMatch(/--api-key/);
   });
 
+  test("cli: mon local-install --api-key and --db-url skip interactive prompts", () => {
+    // This test verifies that when --api-key and --db-url are provided,
+    // the CLI uses them directly without prompting for input.
+    // The command will fail later (no Docker, invalid DB), but we check
+    // that the options were parsed and used correctly.
+    const r = runCli([
+      "mon", "local-install",
+      "--api-key", "test-api-key-12345",
+      "--db-url", "postgresql://user:pass@localhost:5432/testdb"
+    ]);
+
+    // Should show that API key was provided via CLI option (not prompting)
+    expect(r.stdout).toMatch(/Using API key provided via --api-key parameter/);
+    // Should show that DB URL was provided via CLI option (not prompting)
+    expect(r.stdout).toMatch(/Using database URL provided via --db-url parameter/);
+  });
+
   test("cli: auth login --help shows --set-key option", () => {
     const r = runCli(["auth", "login", "--help"]);
     expect(r.status).toBe(0);
     expect(r.stdout).toMatch(/--set-key/);
   });
+
+  test("cli: mon local-install reads global --api-key option", () => {
+    // The fix ensures --api-key works when passed as a global option (before subcommand)
+    // Commander.js routes global options to program.opts(), not subcommand opts
+    const r = runCli([
+      "--api-key", "global-api-key-test",
+      "mon", "local-install",
+      "--db-url", "postgresql://user:pass@localhost:5432/testdb"
+    ]);
+
+    // Should detect the API key from global options
+    expect(r.stdout).toMatch(/Using API key provided via --api-key parameter/);
+  });
+
+  test("cli: mon local-install works with --api-key after subcommand", () => {
+    // Test that --api-key works when passed after the subcommand
+    // Note: Commander.js routes --api-key to global opts, the fix reads from both
+    const r = runCli([
+      "mon", "local-install",
+      "--api-key", "test-key-after-subcommand",
+      "--db-url", "postgresql://user:pass@localhost:5432/testdb"
+    ]);
+
+    // Should detect the API key regardless of position
+    expect(r.stdout).toMatch(/Using API key provided via --api-key parameter/);
+    // Verify the key was saved
+    expect(r.stdout).toMatch(/API key saved/);
+  });
+
+  test("cli: mon local-install with --yes and no --api-key skips API setup", () => {
+    // When --yes is provided without --api-key, the CLI should skip
+    // the interactive prompt and proceed without API key
+    const r = runCli([
+      "mon", "local-install",
+      "--db-url", "postgresql://user:pass@localhost:5432/testdb",
+      "--yes"
+    ]);
+
+    // Should indicate auto-yes mode without API key
+    expect(r.stdout).toMatch(/Auto-yes mode: no API key provided/);
+    expect(r.stdout).toMatch(/Reports will be generated locally only/);
+  });
+
+  test("cli: mon local-install --demo with global --api-key shows error", () => {
+    // When --demo is used with global --api-key, it should still be detected and error
+    const r = runCli([
+      "--api-key", "global-api-key-test",
+      "mon", "local-install",
+      "--demo"
+    ]);
+
+    // Should reject demo mode with API key (from global option)
+    expect(r.status).not.toBe(0);
+    expect(r.stderr).toMatch(/Cannot use --api-key with --demo mode/);
+  });
 });