postgresai 0.16.0-rc.4 → 0.16.0

package/lib/util.ts

@@ -1,134 +0,0 @@
-/**
- * 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");
-}
-
-/**
- * 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 + remediation;
-    }
-
-    // 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 + remediation;
-}
-
-export function maskSecret(secret: string): string {
-  if (!secret) return "";
-  if (secret.length <= 8) return "****";
-  if (secret.length <= 16) return `${secret.slice(0, 4)}${"*".repeat(secret.length - 8)}${secret.slice(-4)}`;
-  return `${secret.slice(0, Math.min(12, secret.length - 8))}${"*".repeat(Math.max(4, secret.length - 16))}${secret.slice(-4)}`;
-}
-
-
-export interface RootOptsLike {
-  apiBaseUrl?: string;
-  uiBaseUrl?: string;
-  storageBaseUrl?: string;
-}
-
-export interface ConfigLike {
-  baseUrl?: string | null;
-  storageBaseUrl?: string | null;
-}
-
-export interface ResolvedBaseUrls {
-  apiBaseUrl: string;
-  uiBaseUrl: string;
-  storageBaseUrl: string;
-}
-
-/**
- * Normalize a base URL by trimming a single trailing slash and validating.
- * @throws Error if the URL is invalid
- */
-export function normalizeBaseUrl(value: string): string {
-  const trimmed = (value || "").replace(/\/$/, "");
-  try {
-    // Validate
-    // eslint-disable-next-line no-new
-    new URL(trimmed);
-  } catch {
-    throw new Error(`Invalid base URL: ${value}`);
-  }
-  return trimmed;
-}
-
-/**
- * Resolve API and UI base URLs using precedence and normalize them.
- * Precedence (API): opts.apiBaseUrl → env.PGAI_API_BASE_URL → cfg.baseUrl → default
- * Precedence (UI):  opts.uiBaseUrl  → env.PGAI_UI_BASE_URL  → default
- */
-export function resolveBaseUrls(
-  opts?: RootOptsLike,
-  cfg?: ConfigLike,
-  defaults: { apiBaseUrl?: string; uiBaseUrl?: string; storageBaseUrl?: string } = {}
-): ResolvedBaseUrls {
-  const defApi = defaults.apiBaseUrl || "https://postgres.ai/api/general/";
-  const defUi = defaults.uiBaseUrl || "https://console.postgres.ai";
-  const defStorage = defaults.storageBaseUrl || "https://postgres.ai/storage";
-
-  const apiCandidate = (opts?.apiBaseUrl || process.env.PGAI_API_BASE_URL || cfg?.baseUrl || defApi) as string;
-  const uiCandidate = (opts?.uiBaseUrl || process.env.PGAI_UI_BASE_URL || defUi) as string;
-  const storageCandidate = (opts?.storageBaseUrl || process.env.PGAI_STORAGE_BASE_URL || cfg?.storageBaseUrl || defStorage) as string;
-
-  return {
-    apiBaseUrl: normalizeBaseUrl(apiCandidate),
-    uiBaseUrl: normalizeBaseUrl(uiCandidate),
-    storageBaseUrl: normalizeBaseUrl(storageCandidate),
-  };
-}

package/packages/postgres-ai/README.md

@@ -1,26 +0,0 @@
-# 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

@@ -1,27 +0,0 @@
-#!/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

@@ -1,27 +0,0 @@
-{
-  "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

@@ -1,115 +0,0 @@
-#!/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");
-}
-
-// Allowed hosts for fetch requests to prevent SSRF
-const ALLOWED_HOSTS = ["postgres.ai"];
-
-async function fetchWithTimeout(url: string, timeoutMs: number): Promise<Response> {
-  // Validate URL against allowlist to prevent SSRF
-  const parsed = new URL(url);
-  if (!ALLOWED_HOSTS.includes(parsed.hostname)) {
-    throw new Error(`Fetch blocked: host "${parsed.hostname}" is not in the allowlist`);
-  }
-
-  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

@@ -1,160 +0,0 @@
-#!/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",
-  // Dead tuples and per-table autovacuum overrides (F003)
-  "pg_dead_tuples",
-  // Bloat estimation (F004, F005)
-  "pg_table_bloat",
-  "pg_btree_bloat",
-  // I/O statistics (I001)
-  "pg_stat_io",
-];
-
-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();