postgresai 0.14.0-dev.56 → 0.14.0-dev.58

package/dist/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/dist/sql/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/lib/config.ts

@@ -56,10 +56,10 @@ export function readConfig(): Config {
     try {
       const content = fs.readFileSync(userConfigPath, "utf8");
       const parsed = JSON.parse(content);
-      config.apiKey = parsed.apiKey || null;
-      config.baseUrl = parsed.baseUrl || null;
-      config.orgId = parsed.orgId || null;
-      config.defaultProject = parsed.defaultProject || null;
+      config.apiKey = parsed.apiKey ?? null;
+      config.baseUrl = parsed.baseUrl ?? null;
+      config.orgId = parsed.orgId ?? null;
+      config.defaultProject = parsed.defaultProject ?? null;
       return config;
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);

package/lib/issues.ts

@@ -1,5 +1,16 @@
 import { formatHttpError, maskSecret, normalizeBaseUrl } from "./util";
 
+/**
+ * Issue status constants.
+ * Used in updateIssue to change issue state.
+ */
+export const IssueStatus = {
+  /** Issue is open and active */
+  OPEN: 0,
+  /** Issue is closed/resolved */
+  CLOSED: 1,
+} as const;
+
 export interface IssueActionItem {
   id: string;
   issue_id: string;
@@ -69,6 +80,7 @@ export async function fetchIssues(params: FetchIssuesParams): Promise<IssueListI
     "access-token": apiKey,
     "Prefer": "return=representation",
     "Content-Type": "application/json",
+    "Connection": "close",
   };
 
   if (debug) {
@@ -126,6 +138,7 @@ export async function fetchIssueComments(params: FetchIssueCommentsParams): Prom
     "access-token": apiKey,
     "Prefer": "return=representation",
     "Content-Type": "application/json",
+    "Connection": "close",
   };
 
   if (debug) {
@@ -185,6 +198,7 @@ export async function fetchIssue(params: FetchIssueParams): Promise<IssueDetail
     "access-token": apiKey,
     "Prefer": "return=representation",
     "Content-Type": "application/json",
+    "Connection": "close",
   };
 
   if (debug) {
@@ -223,6 +237,112 @@ export async function fetchIssue(params: FetchIssueParams): Promise<IssueDetail
   }
 }
 
+export interface CreateIssueParams {
+  apiKey: string;
+  apiBaseUrl: string;
+  title: string;
+  orgId: number;
+  description?: string;
+  projectId?: number;
+  labels?: string[];
+  debug?: boolean;
+}
+
+export interface CreatedIssue {
+  id: string;
+  title: string;
+  description: string | null;
+  created_at: string;
+  status: number;
+  project_id: number | null;
+  labels: string[] | null;
+}
+
+/**
+ * Create a new issue in the PostgresAI platform.
+ *
+ * @param params - The parameters for creating an issue
+ * @param params.apiKey - API key for authentication
+ * @param params.apiBaseUrl - Base URL for the API
+ * @param params.title - Issue title (required)
+ * @param params.orgId - Organization ID (required)
+ * @param params.description - Optional issue description
+ * @param params.projectId - Optional project ID to associate with
+ * @param params.labels - Optional array of label strings
+ * @param params.debug - Enable debug logging
+ * @returns The created issue object
+ * @throws Error if API key, title, or orgId is missing, or if the API call fails
+ */
+export async function createIssue(params: CreateIssueParams): Promise<CreatedIssue> {
+  const { apiKey, apiBaseUrl, title, orgId, description, projectId, labels, debug } = params;
+  if (!apiKey) {
+    throw new Error("API key is required");
+  }
+  if (!title) {
+    throw new Error("title is required");
+  }
+  if (typeof orgId !== "number") {
+    throw new Error("orgId is required");
+  }
+
+  const base = normalizeBaseUrl(apiBaseUrl);
+  const url = new URL(`${base}/rpc/issue_create`);
+
+  const bodyObj: Record<string, unknown> = {
+    title: title,
+    org_id: orgId,
+  };
+  if (description !== undefined) {
+    bodyObj.description = description;
+  }
+  if (projectId !== undefined) {
+    bodyObj.project_id = projectId;
+  }
+  if (labels && labels.length > 0) {
+    bodyObj.labels = labels;
+  }
+  const body = JSON.stringify(bodyObj);
+
+  const headers: Record<string, string> = {
+    "access-token": apiKey,
+    "Prefer": "return=representation",
+    "Content-Type": "application/json",
+    "Connection": "close",
+  };
+
+  if (debug) {
+    const debugHeaders: Record<string, string> = { ...headers, "access-token": maskSecret(apiKey) };
+    console.log(`Debug: Resolved API base URL: ${base}`);
+    console.log(`Debug: POST URL: ${url.toString()}`);
+    console.log(`Debug: Auth scheme: access-token`);
+    console.log(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+    console.log(`Debug: Request body: ${body}`);
+  }
+
+  const response = await fetch(url.toString(), {
+    method: "POST",
+    headers,
+    body,
+  });
+
+  if (debug) {
+    console.log(`Debug: Response status: ${response.status}`);
+    console.log(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
+  }
+
+  const data = await response.text();
+
+  if (response.ok) {
+    try {
+      return JSON.parse(data) as CreatedIssue;
+    } catch {
+      throw new Error(`Failed to parse create issue response: ${data}`);
+    }
+  } else {
+    throw new Error(formatHttpError("Failed to create issue", response.status, data));
+  }
+}
+
 export interface CreateIssueCommentParams {
   apiKey: string;
   apiBaseUrl: string;
@@ -260,6 +380,7 @@ export async function createIssueComment(params: CreateIssueCommentParams): Prom
     "access-token": apiKey,
     "Prefer": "return=representation",
     "Content-Type": "application/json",
+    "Connection": "close",
   };
 
   if (debug) {
@@ -294,3 +415,200 @@ export async function createIssueComment(params: CreateIssueCommentParams): Prom
     throw new Error(formatHttpError("Failed to create issue comment", response.status, data));
   }
 }
+
+export interface UpdateIssueParams {
+  apiKey: string;
+  apiBaseUrl: string;
+  issueId: string;
+  title?: string;
+  description?: string;
+  status?: number;
+  labels?: string[];
+  debug?: boolean;
+}
+
+export interface UpdatedIssue {
+  id: string;
+  title: string;
+  description: string | null;
+  status: number;
+  updated_at: string;
+  labels: string[] | null;
+}
+
+/**
+ * Update an existing issue in the PostgresAI platform.
+ *
+ * @param params - The parameters for updating an issue
+ * @param params.apiKey - API key for authentication
+ * @param params.apiBaseUrl - Base URL for the API
+ * @param params.issueId - ID of the issue to update (required)
+ * @param params.title - New title (optional)
+ * @param params.description - New description (optional)
+ * @param params.status - New status: 0 = open, 1 = closed (optional)
+ * @param params.labels - New labels array (optional, replaces existing)
+ * @param params.debug - Enable debug logging
+ * @returns The updated issue object
+ * @throws Error if API key or issueId is missing, if no fields to update are provided, or if the API call fails
+ */
+export async function updateIssue(params: UpdateIssueParams): Promise<UpdatedIssue> {
+  const { apiKey, apiBaseUrl, issueId, title, description, status, labels, debug } = params;
+  if (!apiKey) {
+    throw new Error("API key is required");
+  }
+  if (!issueId) {
+    throw new Error("issueId is required");
+  }
+  if (title === undefined && description === undefined && status === undefined && labels === undefined) {
+    throw new Error("At least one field to update is required (title, description, status, or labels)");
+  }
+
+  const base = normalizeBaseUrl(apiBaseUrl);
+  const url = new URL(`${base}/rpc/issue_update`);
+
+  // Prod RPC expects p_* argument names (see OpenAPI at /api/general/).
+  const bodyObj: Record<string, unknown> = {
+    p_id: issueId,
+  };
+  if (title !== undefined) {
+    bodyObj.p_title = title;
+  }
+  if (description !== undefined) {
+    bodyObj.p_description = description;
+  }
+  if (status !== undefined) {
+    bodyObj.p_status = status;
+  }
+  if (labels !== undefined) {
+    bodyObj.p_labels = labels;
+  }
+  const body = JSON.stringify(bodyObj);
+
+  const headers: Record<string, string> = {
+    "access-token": apiKey,
+    "Prefer": "return=representation",
+    "Content-Type": "application/json",
+    "Connection": "close",
+  };
+
+  if (debug) {
+    const debugHeaders: Record<string, string> = { ...headers, "access-token": maskSecret(apiKey) };
+    console.log(`Debug: Resolved API base URL: ${base}`);
+    console.log(`Debug: POST URL: ${url.toString()}`);
+    console.log(`Debug: Auth scheme: access-token`);
+    console.log(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+    console.log(`Debug: Request body: ${body}`);
+  }
+
+  const response = await fetch(url.toString(), {
+    method: "POST",
+    headers,
+    body,
+  });
+
+  if (debug) {
+    console.log(`Debug: Response status: ${response.status}`);
+    console.log(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
+  }
+
+  const data = await response.text();
+
+  if (response.ok) {
+    try {
+      return JSON.parse(data) as UpdatedIssue;
+    } catch {
+      throw new Error(`Failed to parse update issue response: ${data}`);
+    }
+  } else {
+    throw new Error(formatHttpError("Failed to update issue", response.status, data));
+  }
+}
+
+export interface UpdateIssueCommentParams {
+  apiKey: string;
+  apiBaseUrl: string;
+  commentId: string;
+  content: string;
+  debug?: boolean;
+}
+
+export interface UpdatedIssueComment {
+  id: string;
+  issue_id: string;
+  content: string;
+  updated_at: string;
+}
+
+/**
+ * Update an existing issue comment in the PostgresAI platform.
+ *
+ * @param params - The parameters for updating a comment
+ * @param params.apiKey - API key for authentication
+ * @param params.apiBaseUrl - Base URL for the API
+ * @param params.commentId - ID of the comment to update (required)
+ * @param params.content - New comment content (required)
+ * @param params.debug - Enable debug logging
+ * @returns The updated comment object
+ * @throws Error if API key, commentId, or content is missing, or if the API call fails
+ */
+export async function updateIssueComment(params: UpdateIssueCommentParams): Promise<UpdatedIssueComment> {
+  const { apiKey, apiBaseUrl, commentId, content, debug } = params;
+  if (!apiKey) {
+    throw new Error("API key is required");
+  }
+  if (!commentId) {
+    throw new Error("commentId is required");
+  }
+  if (!content) {
+    throw new Error("content is required");
+  }
+
+  const base = normalizeBaseUrl(apiBaseUrl);
+  const url = new URL(`${base}/rpc/issue_comment_update`);
+
+  const bodyObj: Record<string, unknown> = {
+    // Prod RPC expects p_* argument names (see OpenAPI at /api/general/).
+    p_id: commentId,
+    p_content: content,
+  };
+  const body = JSON.stringify(bodyObj);
+
+  const headers: Record<string, string> = {
+    "access-token": apiKey,
+    "Prefer": "return=representation",
+    "Content-Type": "application/json",
+    "Connection": "close",
+  };
+
+  if (debug) {
+    const debugHeaders: Record<string, string> = { ...headers, "access-token": maskSecret(apiKey) };
+    console.log(`Debug: Resolved API base URL: ${base}`);
+    console.log(`Debug: POST URL: ${url.toString()}`);
+    console.log(`Debug: Auth scheme: access-token`);
+    console.log(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+    console.log(`Debug: Request body: ${body}`);
+  }
+
+  const response = await fetch(url.toString(), {
+    method: "POST",
+    headers,
+    body,
+  });
+
+  if (debug) {
+    console.log(`Debug: Response status: ${response.status}`);
+    console.log(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
+  }
+
+  const data = await response.text();
+
+  if (response.ok) {
+    try {
+      return JSON.parse(data) as UpdatedIssueComment;
+    } catch {
+      throw new Error(`Failed to parse update comment response: ${data}`);
+    }
+  } else {
+    throw new Error(formatHttpError("Failed to update issue comment", response.status, data));
+  }
+}