postgresai 0.14.0-dev.8 → 0.14.0-dev.81

package/lib/util.ts

@@ -1,3 +1,64 @@
+/**
+ * Map of HTTP status codes to human-friendly messages.
+ */
+const HTTP_STATUS_MESSAGES: Record<number, string> = {
+  400: "Bad Request",
+  401: "Unauthorized - check your API key",
+  403: "Forbidden - access denied",
+  404: "Not Found",
+  408: "Request Timeout",
+  429: "Too Many Requests - rate limited",
+  500: "Internal Server Error",
+  502: "Bad Gateway - server temporarily unavailable",
+  503: "Service Unavailable - server temporarily unavailable",
+  504: "Gateway Timeout - server temporarily unavailable",
+};
+
+/**
+ * Check if a string looks like HTML content.
+ */
+function isHtmlContent(text: string): boolean {
+  const trimmed = text.trim();
+  return trimmed.startsWith("<!DOCTYPE") || trimmed.startsWith("<html") || trimmed.startsWith("<HTML");
+}
+
+/**
+ * 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.
+ */
+export function formatHttpError(operation: string, status: number, responseBody?: string): string {
+  const statusMessage = HTTP_STATUS_MESSAGES[status] || "Request failed";
+  let errMsg = `${operation}: HTTP ${status} - ${statusMessage}`;
+
+  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;
+    }
+
+    // Try to parse as JSON for structured error info
+    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)}`;
+      }
+    } catch {
+      // Plain text error - append it if it's short and useful
+      const trimmed = responseBody.trim();
+      if (trimmed.length > 0 && trimmed.length < 500) {
+        errMsg += `\n${trimmed}`;
+      }
+    }
+  }
+
+  return errMsg;
+}
+
 export function maskSecret(secret: string): string {
   if (!secret) return "";
   if (secret.length <= 8) return "****";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "postgresai",
-  "version": "0.14.0-dev.8",
-  "description": "postgres_ai CLI (Node.js)",
+  "version": "0.14.0-dev.81",
+  "description": "postgres_ai CLI",
   "license": "Apache-2.0",
   "private": false,
   "repository": {
@@ -13,20 +13,30 @@
     "url": "https://gitlab.com/postgres-ai/postgres_ai/-/issues"
   },
   "bin": {
-    "postgres-ai": "./dist/bin/postgres-ai.js",
     "postgresai": "./dist/bin/postgres-ai.js",
     "pgai": "./dist/bin/postgres-ai.js"
   },
-  "type": "commonjs",
+  "exports": {
+    ".": "./dist/bin/postgres-ai.js",
+    "./cli": "./dist/bin/postgres-ai.js"
+  },
+  "type": "module",
   "engines": {
     "node": ">=18"
   },
   "scripts": {
-    "build": "tsc",
-    "prepare": "npm run build",
-    "start": "node ./dist/bin/postgres-ai.js --help",
-    "dev": "tsc --watch",
-    "test": "npm run build && node --test test/*.test.cjs"
+    "embed-metrics": "bun run scripts/embed-metrics.ts",
+    "embed-checkup-dictionary": "bun run scripts/embed-checkup-dictionary.ts",
+    "embed-all": "bun run embed-metrics && bun run embed-checkup-dictionary",
+    "build": "bun run embed-all && bun build ./bin/postgres-ai.ts --outdir ./dist/bin --target node && node -e \"const fs=require('fs');const f='./dist/bin/postgres-ai.js';fs.writeFileSync(f,fs.readFileSync(f,'utf8').replace('#!/usr/bin/env bun','#!/usr/bin/env node'))\" && cp -r ./sql ./dist/sql",
+    "prepublishOnly": "npm run build",
+    "start": "bun ./bin/postgres-ai.ts --help",
+    "start:node": "node ./dist/bin/postgres-ai.js --help",
+    "dev": "bun run embed-all && bun --watch ./bin/postgres-ai.ts",
+    "test": "bun run embed-all && bun test",
+    "test:fast": "bun run embed-all && bun test",
+    "test:coverage": "bun run embed-all && bun test --coverage && echo 'Coverage report: cli/coverage/lcov-report/index.html'",
+    "typecheck": "bun run embed-all && bunx tsc --noEmit"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.20.2",
@@ -35,9 +45,11 @@
     "pg": "^8.16.3"
   },
   "devDependencies": {
+    "@types/bun": "^1.1.14",
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "^18.19.0",
     "@types/pg": "^8.15.6",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
     "typescript": "^5.3.3"
   },
   "publishConfig": {

package/packages/postgres-ai/README.md

@@ -0,0 +1,26 @@
+# postgres-ai
+
+This is a wrapper package for [postgresai](https://www.npmjs.com/package/postgresai).
+
+## Prefer installing postgresai directly
+
+```bash
+npm install -g postgresai
+```
+
+This gives you two commands:
+- `postgresai` — canonical, discoverable
+- `pgai` — short and convenient
+
+## Why this package exists
+
+This package exists for discoverability on npm. If you search for "postgres-ai", you'll find this package which depends on and forwards to `postgresai`.
+
+Installing this package (`npm install -g postgres-ai`) will install both packages, giving you all three command aliases:
+- `postgres-ai` (from this package)
+- `postgresai` (from the main package)
+- `pgai` (from the main package)
+
+## Documentation
+
+See the main package for full documentation: https://www.npmjs.com/package/postgresai

package/packages/postgres-ai/bin/postgres-ai.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * postgres-ai wrapper - forwards all commands to postgresai CLI
+ * 
+ * This package exists for discoverability. For direct installation,
+ * prefer: npm install -g postgresai
+ */
+const { spawn } = require('child_process');
+
+// Find postgresai binary from the dependency
+// Uses the "cli" export defined in postgresai's package.json
+const postgresaiBin = require.resolve('postgresai/cli');
+
+// Forward all arguments to postgresai
+const child = spawn(process.execPath, [postgresaiBin, ...process.argv.slice(2)], {
+  stdio: 'inherit',
+  env: process.env,
+});
+
+child.on('close', (code) => {
+  process.exit(code ?? 0);
+});
+
+child.on('error', (err) => {
+  console.error(`Failed to start postgresai: ${err.message}`);
+  process.exit(1);
+});

package/packages/postgres-ai/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "postgres-ai",
+  "version": "0.0.0-dev.0",
+  "description": "PostgresAI CLI (wrapper package - prefer installing postgresai directly)",
+  "license": "Apache-2.0",
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/postgres-ai/postgres_ai.git"
+  },
+  "homepage": "https://gitlab.com/postgres-ai/postgres_ai",
+  "bugs": {
+    "url": "https://gitlab.com/postgres-ai/postgres_ai/-/issues"
+  },
+  "bin": {
+    "postgres-ai": "./bin/postgres-ai.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "postgresai": ">=0.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/embed-checkup-dictionary.ts

@@ -0,0 +1,106 @@
+#!/usr/bin/env bun
+/**
+ * Build script to fetch checkup dictionary from API and embed it.
+ *
+ * This script fetches from https://postgres.ai/api/general/checkup_dictionary
+ * and generates cli/lib/checkup-dictionary-embedded.ts with the data embedded.
+ *
+ * The generated file is NOT committed to git - it's regenerated at build time.
+ *
+ * Usage: bun run scripts/embed-checkup-dictionary.ts
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+
+// API endpoint - always available without auth
+const DICTIONARY_URL = "https://postgres.ai/api/general/checkup_dictionary";
+
+// Output path relative to cli/ directory
+const CLI_DIR = path.resolve(__dirname, "..");
+const OUTPUT_PATH = path.resolve(CLI_DIR, "lib/checkup-dictionary-embedded.ts");
+
+// Request timeout (10 seconds)
+const FETCH_TIMEOUT_MS = 10_000;
+
+interface CheckupDictionaryEntry {
+  code: string;
+  title: string;
+  description: string;
+  category: string;
+  sort_order: number | null;
+  is_system_report: boolean;
+}
+
+function generateTypeScript(data: CheckupDictionaryEntry[], sourceUrl: string): string {
+  const lines: string[] = [
+    "// AUTO-GENERATED FILE - DO NOT EDIT",
+    `// Generated from: ${sourceUrl}`,
+    `// Generated at: ${new Date().toISOString()}`,
+    "// To regenerate: bun run embed-checkup-dictionary",
+    "",
+    'import { CheckupDictionaryEntry } from "./checkup-dictionary";',
+    "",
+    "/**",
+    " * Embedded checkup dictionary data fetched from API at build time.",
+    " * Contains all available checkup report codes, titles, and metadata.",
+    " */",
+    `export const CHECKUP_DICTIONARY_DATA: CheckupDictionaryEntry[] = ${JSON.stringify(data, null, 2)};`,
+    "",
+  ];
+  return lines.join("\n");
+}
+
+async function fetchWithTimeout(url: string, timeoutMs: number): Promise<Response> {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetch(url, { signal: controller.signal });
+    return response;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+async function main() {
+  console.log(`Fetching checkup dictionary from: ${DICTIONARY_URL}`);
+
+  try {
+    const response = await fetchWithTimeout(DICTIONARY_URL, FETCH_TIMEOUT_MS);
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    const data: CheckupDictionaryEntry[] = await response.json();
+
+    if (!Array.isArray(data)) {
+      throw new Error("Expected array response from API");
+    }
+
+    // Validate entries have required fields
+    for (const entry of data) {
+      if (!entry.code || !entry.title) {
+        throw new Error(`Invalid entry missing code or title: ${JSON.stringify(entry)}`);
+      }
+    }
+
+    const tsCode = generateTypeScript(data, DICTIONARY_URL);
+    fs.writeFileSync(OUTPUT_PATH, tsCode, "utf8");
+
+    console.log(`Generated: ${OUTPUT_PATH}`);
+    console.log(`Dictionary contains ${data.length} entries`);
+  } catch (err) {
+    const errorMsg = err instanceof Error ? err.message : String(err);
+    console.warn(`Warning: Failed to fetch checkup dictionary: ${errorMsg}`);
+    console.warn("Generating empty dictionary as fallback");
+
+    // Generate empty dictionary to allow build to proceed
+    const fallbackTs = generateTypeScript([], `N/A (fetch failed: ${errorMsg})`);
+    fs.writeFileSync(OUTPUT_PATH, fallbackTs, "utf8");
+    console.log(`Generated fallback dictionary at ${OUTPUT_PATH}`);
+  }
+}
+
+main();

package/scripts/embed-metrics.ts

@@ -0,0 +1,154 @@
+#!/usr/bin/env bun
+/**
+ * Build script to embed metrics.yml into the CLI bundle.
+ * 
+ * This script reads config/pgwatch-prometheus/metrics.yml and generates
+ * cli/lib/metrics-embedded.ts with the metrics data embedded as TypeScript.
+ * 
+ * The generated file is NOT committed to git - it's regenerated at build time.
+ * 
+ * Usage: bun run scripts/embed-metrics.ts
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import * as yaml from "js-yaml";
+
+// Resolve paths relative to cli/ directory
+const CLI_DIR = path.resolve(__dirname, "..");
+const METRICS_YML_PATH = path.resolve(CLI_DIR, "../config/pgwatch-prometheus/metrics.yml");
+const OUTPUT_PATH = path.resolve(CLI_DIR, "lib/metrics-embedded.ts");
+
+interface MetricDefinition {
+  description?: string;
+  // YAML parses numeric keys (e.g., 11:, 14:) as numbers, representing PG major versions
+  sqls: Record<number, string>;
+  gauges?: string[];
+  statement_timeout_seconds?: number;
+  is_instance_level?: boolean;
+  node_status?: string;
+}
+
+interface MetricsYml {
+  metrics: Record<string, MetricDefinition>;
+}
+
+// Metrics needed for express mode reports
+const REQUIRED_METRICS = [
+  // Settings and version (A002, A003, A007, A013)
+  "settings",
+  // Database stats (A004)
+  "db_stats",
+  "db_size",
+  // Index health (H001, H002, H004)
+  "pg_invalid_indexes",
+  "unused_indexes",
+  "redundant_indexes",
+  // Stats reset info (H002)
+  "stats_reset",
+];
+
+function main() {
+  console.log(`Reading metrics from: ${METRICS_YML_PATH}`);
+  
+  if (!fs.existsSync(METRICS_YML_PATH)) {
+    console.error(`ERROR: metrics.yml not found at ${METRICS_YML_PATH}`);
+    process.exit(1);
+  }
+
+  const yamlContent = fs.readFileSync(METRICS_YML_PATH, "utf8");
+  const parsed = yaml.load(yamlContent) as MetricsYml;
+
+  if (!parsed.metrics) {
+    console.error("ERROR: No 'metrics' section found in metrics.yml");
+    process.exit(1);
+  }
+
+  // Extract only required metrics
+  const extractedMetrics: Record<string, MetricDefinition> = {};
+  const missingMetrics: string[] = [];
+
+  for (const metricName of REQUIRED_METRICS) {
+    if (parsed.metrics[metricName]) {
+      extractedMetrics[metricName] = parsed.metrics[metricName];
+    } else {
+      missingMetrics.push(metricName);
+    }
+  }
+
+  if (missingMetrics.length > 0) {
+    console.error(`ERROR: Missing required metrics: ${missingMetrics.join(", ")}`);
+    process.exit(1);
+  }
+
+  // Generate TypeScript code
+  const tsCode = generateTypeScript(extractedMetrics);
+
+  // Write output
+  fs.writeFileSync(OUTPUT_PATH, tsCode, "utf8");
+  console.log(`Generated: ${OUTPUT_PATH}`);
+  console.log(`Embedded ${Object.keys(extractedMetrics).length} metrics`);
+}
+
+function generateTypeScript(metrics: Record<string, MetricDefinition>): string {
+  const lines: string[] = [
+    "// AUTO-GENERATED FILE - DO NOT EDIT",
+    "// Generated from config/pgwatch-prometheus/metrics.yml by scripts/embed-metrics.ts",
+    `// Generated at: ${new Date().toISOString()}`,
+    "",
+    "/**",
+    " * Metric definition from metrics.yml",
+    " */",
+    "export interface MetricDefinition {",
+    "  description?: string;",
+    "  sqls: Record<number, string>;  // PG major version -> SQL query",
+    "  gauges?: string[];",
+    "  statement_timeout_seconds?: number;",
+    "}",
+    "",
+    "/**",
+    " * Embedded metrics for express mode reports.",
+    " * Only includes metrics required for CLI checkup reports.",
+    " */",
+    "export const METRICS: Record<string, MetricDefinition> = {",
+  ];
+
+  for (const [name, metric] of Object.entries(metrics)) {
+    lines.push(`  ${JSON.stringify(name)}: {`);
+    
+    if (metric.description) {
+      // Escape description for TypeScript string
+      const desc = metric.description.trim().replace(/\n/g, " ").replace(/\s+/g, " ");
+      lines.push(`    description: ${JSON.stringify(desc)},`);
+    }
+
+    // sqls keys are PG major versions (numbers in YAML, but Object.entries returns strings)
+    lines.push("    sqls: {");
+    for (const [versionKey, sql] of Object.entries(metric.sqls)) {
+      // YAML numeric keys may be parsed as numbers or strings depending on context;
+      // explicitly convert to ensure consistent numeric keys in output
+      const versionNum = typeof versionKey === "number" ? versionKey : parseInt(versionKey, 10);
+      // Use JSON.stringify for robust escaping of all special characters
+      lines.push(`      ${versionNum}: ${JSON.stringify(sql)},`);
+    }
+    lines.push("    },");
+
+    if (metric.gauges) {
+      lines.push(`    gauges: ${JSON.stringify(metric.gauges)},`);
+    }
+
+    if (metric.statement_timeout_seconds !== undefined) {
+      lines.push(`    statement_timeout_seconds: ${metric.statement_timeout_seconds},`);
+    }
+
+    lines.push("  },");
+  }
+
+  lines.push("};");
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+main();
+

package/sql/01.role.sql

@@ -0,0 +1,16 @@
+-- Role creation / password update (template-filled by cli/lib/init.ts)
+--
+-- Always uses a race-safe pattern (create if missing, then always alter to set the password):
+--   do $$ begin
+--     if not exists (select 1 from pg_catalog.pg_roles where rolname = '...') then
+--       begin
+--         create user "..." with password '...';
+--       exception when duplicate_object then
+--         null;
+--       end;
+--     end if;
+--     alter user "..." with password '...';
+--   end $$;
+{{ROLE_STMT}}
+
+

package/sql/02.extensions.sql

@@ -0,0 +1,8 @@
+-- Extensions required for postgres_ai monitoring
+
+-- Enable pg_stat_statements for query performance monitoring
+-- Note: Uses IF NOT EXISTS because extension may already be installed.
+-- We do NOT drop this extension in unprepare-db since it may have been pre-existing.
+create extension if not exists pg_stat_statements;
+
+

package/sql/03.permissions.sql

@@ -0,0 +1,38 @@
+-- Required permissions for postgres_ai monitoring user (template-filled by cli/lib/init.ts)
+
+-- Allow connect
+grant connect on database {{DB_IDENT}} to {{ROLE_IDENT}};
+
+-- Standard monitoring privileges
+grant pg_monitor to {{ROLE_IDENT}};
+grant select on pg_catalog.pg_index to {{ROLE_IDENT}};
+
+-- Create postgres_ai schema for our objects
+-- Using IF NOT EXISTS for idempotency - prepare-db can be run multiple times
+create schema if not exists postgres_ai;
+grant usage on schema postgres_ai to {{ROLE_IDENT}};
+
+-- For bloat analysis: expose pg_statistic via a view
+create or replace view postgres_ai.pg_statistic as
+select
+    n.nspname as schemaname,
+    c.relname as tablename,
+    a.attname,
+    s.stanullfrac as null_frac,
+    s.stawidth as avg_width,
+    false as inherited
+from pg_catalog.pg_statistic s
+join pg_catalog.pg_class c on c.oid = s.starelid
+join pg_catalog.pg_namespace n on n.oid = c.relnamespace
+join pg_catalog.pg_attribute a on a.attrelid = s.starelid and a.attnum = s.staattnum
+where a.attnum > 0 and not a.attisdropped;
+
+grant select on postgres_ai.pg_statistic to {{ROLE_IDENT}};
+
+-- Hardened clusters sometimes revoke PUBLIC on schema public
+grant usage on schema public to {{ROLE_IDENT}};
+
+-- Keep search_path predictable; postgres_ai first so our objects are found
+alter user {{ROLE_IDENT}} set search_path = postgres_ai, "$user", public, pg_catalog;
+
+

package/sql/04.optional_rds.sql

@@ -0,0 +1,6 @@
+-- Optional permissions for RDS Postgres / Aurora (best effort)
+
+create extension if not exists rds_tools;
+grant execute on function rds_tools.pg_ls_multixactdir() to {{ROLE_IDENT}};
+
+

package/sql/05.optional_self_managed.sql

@@ -0,0 +1,8 @@
+-- Optional permissions for self-managed Postgres (best effort)
+
+grant execute on function pg_catalog.pg_stat_file(text) to {{ROLE_IDENT}};
+grant execute on function pg_catalog.pg_stat_file(text, boolean) to {{ROLE_IDENT}};
+grant execute on function pg_catalog.pg_ls_dir(text) to {{ROLE_IDENT}};
+grant execute on function pg_catalog.pg_ls_dir(text, boolean, boolean) to {{ROLE_IDENT}};
+
+