@indiekitai/pg-dash 0.6.0 → 0.7.0

package/dist/cli.js

@@ -1275,6 +1275,594 @@ var init_snapshot = __esm({
   }
 });
 
+// src/server/queries/db-context.ts
+function inferBusinessIntent(tableName, columnNames) {
+  const name = tableName.toLowerCase();
+  const cols = columnNames.map((c) => c.toLowerCase());
+  const patterns = [
+    [/^(user|users?|account|accounts?|customer|customers?|member|members?)$/, "\u7528\u6237/\u4F1A\u5458\u7BA1\u7406"],
+    [/^(order|orders?|purchase|purchases?)$/, "\u8BA2\u5355/\u8D2D\u4E70\u8BB0\u5F55"],
+    [/^(product|products?|item|items?|goods?)$/, "\u5546\u54C1/\u4EA7\u54C1\u76EE\u5F55"],
+    [/^(payment|payments?|transaction|transactions?|invoice|invoices?)$/, "\u652F\u4ED8/\u4EA4\u6613\u8BB0\u5F55"],
+    [/^(session|sessions?|auth|authentication|token|tokens?)$/, "\u8BA4\u8BC1/\u4F1A\u8BDD\u7BA1\u7406"],
+    [/^(log|logs?|audit|audits?|history|histories?)$/, "\u65E5\u5FD7/\u5BA1\u8BA1\u8BB0\u5F55"],
+    [/^(config|configuration|settings?)$/, "\u914D\u7F6E/\u8BBE\u7F6E"],
+    [/^(category|categories?|tag|tags?|group|groups?)$/, "\u5206\u7C7B/\u6807\u7B7E/\u5206\u7EC4"],
+    [/^(comment|comments?|review|reviews?|feedback)$/, "\u8BC4\u8BBA/\u53CD\u9988"],
+    [/^(notification|notifications?|message|messages?)$/, "\u901A\u77E5/\u6D88\u606F"],
+    [/^(file|files?|attachment|attachments?|media)$/, "\u6587\u4EF6/\u5A92\u4F53"],
+    [/^(api[_-]?key|api[_-]?key|key|keys?|credential|credentials?)$/, "API \u5BC6\u94A5/\u51ED\u8BC1"],
+    [/^(job|jobs?|queue|queues?|task|tasks?)$/, "\u4EFB\u52A1/\u961F\u5217"],
+    [/^(subscription|subscriptions?|plan|plans?)$/, "\u8BA2\u9605/\u5957\u9910"],
+    [/^(coupon|coupons?|promo|promotion|promotions?)$/, "\u4F18\u60E0/\u4FC3\u9500"],
+    [/^(analytics?|statistic|statistics?|metric|metrics?)$/, "\u5206\u6790/\u7EDF\u8BA1"]
+  ];
+  for (const [pattern, intent] of patterns) {
+    if (pattern.test(name)) return intent;
+  }
+  const colPatterns = [
+    [/user_id|customer_id|member_id/, "\u7528\u6237\u5173\u8054"],
+    [/order_id|purchase_id/, "\u8BA2\u5355\u5173\u8054"],
+    [/product_id|item_id/, "\u5546\u54C1\u5173\u8054"],
+    [/status|state/, "\u72B6\u6001\u7BA1\u7406"],
+    [/created_at|updated_at|deleted_at/, "\u65F6\u95F4\u6233/\u8F6F\u5220\u9664"],
+    [/email|phone|address/, "\u8054\u7CFB\u4FE1\u606F"],
+    [/price|amount|total|cost/, "\u91D1\u989D/\u4EF7\u683C"],
+    [/quantity|count|qty/, "\u6570\u91CF"],
+    [/latitude|longitude|location/, "\u5730\u7406\u4F4D\u7F6E"],
+    [/ip|user_agent|browser/, "\u8BBF\u95EE\u4FE1\u606F"]
+  ];
+  const matchedColHints = colPatterns.filter(
+    ([pattern]) => cols.some((col) => pattern.test(col))
+  ).map(([, hint]) => hint);
+  if (matchedColHints.length > 0) {
+    return `\u6570\u636E\u8868 (\u53EF\u80FD\u7528\u9014: ${matchedColHints.slice(0, 2).join("\u3001")})`;
+  }
+  return "\u901A\u7528\u6570\u636E\u8868";
+}
+async function getDbContext(pool) {
+  const client = await pool.connect();
+  try {
+    const tablesResult = await client.query(`
+      SELECT
+        n.nspname AS schema,
+        c.relname AS table_name,
+        pg_size_pretty(pg_total_relation_size(c.oid)) AS total_size,
+        pg_total_relation_size(c.oid) AS total_size_bytes,
+        pg_relation_size(c.oid) AS table_size_bytes,
+        pg_indexes_size(c.oid) AS index_size_bytes,
+        s.n_live_tup AS row_count,
+        s.n_dead_tup AS dead_tuples,
+        obj_description(c.oid) AS description
+      FROM pg_class c
+      JOIN pg_namespace n ON c.relnamespace = n.oid
+      LEFT JOIN pg_stat_user_tables s ON s.relid = c.oid
+      WHERE c.relkind = 'r' AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+      ORDER BY pg_total_relation_size(c.oid) DESC
+    `);
+    const columnsResult = await client.query(`
+      SELECT
+        n.nspname AS schema,
+        c.relname AS table_name,
+        a.attname AS column_name,
+        pg_catalog.format_type(a.atttypid, a.atttypmod) AS data_type,
+        NOT a.attnotnull AS is_nullable,
+        pg_get_expr(d.adbin, d.adrelid) AS default_value,
+        col_description(a.attrelid, a.attnum) AS description,
+        a.attnum AS ordinal_position
+      FROM pg_attribute a
+      JOIN pg_class c ON a.attrelid = c.oid
+      JOIN pg_namespace n ON c.relnamespace = n.oid
+      LEFT JOIN pg_attrdef d ON a.attrelid = d.adrelid AND a.attnum = d.adnum
+      WHERE a.attnum > 0 AND NOT a.attisdropped
+        AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+      ORDER BY n.nspname, c.relname, a.attnum
+    `);
+    const pkResult = await client.query(`
+      SELECT
+        n.nspname AS schema,
+        c.relname AS table_name,
+        a.attname AS column_name
+      FROM pg_index idx
+      JOIN pg_class c ON idx.indrelid = c.oid
+      JOIN pg_namespace n ON c.relnamespace = n.oid
+      JOIN pg_attribute a ON a.attrelid = c.oid AND a.attnum = ANY(idx.indkey)
+      WHERE idx.indisprimary = true
+        AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+      ORDER BY n.nspname, c.relname, a.attnum
+    `);
+    const fkResult = await client.query(`
+      SELECT
+        n.nspname AS schema,
+        c.relname AS table_name,
+        a.attname AS column_name,
+        ref_n.nspname AS referenced_schema,
+        ref_c.relname AS referenced_table,
+        ref_a.attname AS referenced_column,
+        conname AS constraint_name
+      FROM pg_constraint con
+      JOIN pg_class c ON con.conrelid = c.oid
+      JOIN pg_namespace n ON c.relnamespace = n.oid
+      JOIN pg_attribute a ON a.attrelid = c.oid AND a.attnum = ANY(con.conkey)
+      JOIN pg_class ref_c ON con.confrelid = ref_c.oid
+      JOIN pg_namespace ref_n ON ref_c.relnamespace = ref_n.oid
+      JOIN pg_attribute ref_a ON ref_a.attrelid = ref_c.oid AND ref_a.attnum = ANY(con.confkey)
+      WHERE con.contype = 'f'
+        AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+      ORDER BY n.nspname, c.relname, con.conname
+    `);
+    const indexesResult = await client.query(`
+      SELECT
+        n.nspname AS schema,
+        t.relname AS table_name,
+        i.relname AS index_name,
+        am.amname AS index_type,
+        pg_get_indexdef(idx.indexrelid) AS definition,
+        idx.indisunique AS is_unique,
+        idx.indisprimary AS is_primary,
+        pg_relation_size(i.oid) AS size_bytes
+      FROM pg_index idx
+      JOIN pg_class i ON idx.indexrelid = i.oid
+      JOIN pg_class t ON idx.indrelid = t.oid
+      JOIN pg_namespace n ON t.relnamespace = n.oid
+      JOIN pg_am am ON i.relam = am.oid
+      WHERE n.nspname NOT IN ('pg_catalog', 'information_schema')
+      ORDER BY t.relname, i.relname
+    `);
+    const tables = tablesResult.rows;
+    const allColumns = columnsResult.rows;
+    const primaryKeys = pkResult.rows;
+    const foreignKeys = fkResult.rows;
+    const indexes = indexesResult.rows;
+    const columnsByTable = /* @__PURE__ */ new Map();
+    for (const col of allColumns) {
+      const key = `${col.schema}.${col.table_name}`;
+      if (!columnsByTable.has(key)) columnsByTable.set(key, []);
+      columnsByTable.get(key).push(col);
+    }
+    const pkByTable = /* @__PURE__ */ new Map();
+    for (const pk of primaryKeys) {
+      const key = `${pk.schema}.${pk.table_name}`;
+      if (!pkByTable.has(key)) pkByTable.set(key, []);
+      pkByTable.get(key).push(pk.column_name);
+    }
+    const fkByTable = /* @__PURE__ */ new Map();
+    for (const fk of foreignKeys) {
+      const key = `${fk.schema}.${fk.table_name}`;
+      if (!fkByTable.has(key)) fkByTable.set(key, []);
+      const fks = fkByTable.get(key);
+      if (!fks.some((existing) => existing.constraint_name === fk.constraint_name)) {
+        fks.push(fk);
+      }
+    }
+    const indexesByTable = /* @__PURE__ */ new Map();
+    for (const idx of indexes) {
+      const key = `${idx.schema}.${idx.table_name}`;
+      if (!indexesByTable.has(key)) indexesByTable.set(key, []);
+      indexesByTable.get(key).push(idx);
+    }
+    const tableSummaries = tables.map((table) => {
+      const key = `${table.schema}.${table.table_name}`;
+      const columns = columnsByTable.get(key) || [];
+      const pks = pkByTable.get(key) || [];
+      const fks = fkByTable.get(key) || [];
+      const tableIndexes = indexesByTable.get(key) || [];
+      return {
+        schema: table.schema,
+        name: table.table_name,
+        description: table.description,
+        rowCount: table.row_count || 0,
+        totalSize: table.total_size,
+        tableSizeBytes: parseInt(table.table_size_bytes) || 0,
+        indexSizeBytes: parseInt(table.index_size_bytes) || 0,
+        deadTuples: table.dead_tuples || 0,
+        businessIntent: inferBusinessIntent(
+          table.table_name,
+          columns.map((c) => c.column_name)
+        ),
+        columns: columns.map((col) => ({
+          name: col.column_name,
+          type: col.data_type,
+          nullable: col.is_nullable,
+          defaultValue: col.default_value,
+          description: col.description,
+          isPrimaryKey: pks.includes(col.column_name),
+          isForeignKey: fks.some((fk) => fk.column_name === col.column_name),
+          referencedTable: fks.find((fk) => fk.column_name === col.column_name)?.referenced_table,
+          referencedColumn: fks.find((fk) => fk.column_name === col.column_name)?.referenced_column
+        })),
+        primaryKeys: pks,
+        foreignKeys: fks.map((fk) => ({
+          column: fk.column_name,
+          references: `${fk.referenced_schema}.${fk.referenced_table}.${fk.referenced_column}`
+        })),
+        indexes: tableIndexes.map((idx) => ({
+          name: idx.index_name,
+          type: idx.index_type,
+          definition: idx.definition,
+          isUnique: idx.is_unique,
+          isPrimary: idx.is_primary,
+          sizeBytes: parseInt(idx.size_bytes) || 0
+        }))
+      };
+    });
+    const indexSummary = tables.map((table) => {
+      const key = `${table.schema}.${table.table_name}`;
+      const tableIndexes = indexesByTable.get(key) || [];
+      return {
+        table: `${table.schema}.${table.table_name}`,
+        hasIndexes: tableIndexes.length > 0,
+        indexCount: tableIndexes.length,
+        indexTypes: [...new Set(tableIndexes.map((i) => i.index_type))],
+        primaryIndex: tableIndexes.some((i) => i.is_primary),
+        uniqueIndexes: tableIndexes.filter((i) => i.is_unique).length
+      };
+    });
+    return {
+      database: {
+        schema: tables[0]?.schema || "public",
+        tableCount: tables.length,
+        totalSize: tables.reduce((sum, t) => sum + (parseInt(t.total_size_bytes) || 0), 0),
+        totalRows: tables.reduce((sum, t) => sum + (t.row_count || 0), 0)
+      },
+      tables: tableSummaries,
+      indexSummary
+    };
+  } finally {
+    client.release();
+  }
+}
+var init_db_context = __esm({
+  "src/server/queries/db-context.ts"() {
+    "use strict";
+  }
+});
+
+// src/server/llm.ts
+var llm_exports = {};
+__export(llm_exports, {
+  executeNaturalQuery: () => executeNaturalQuery,
+  explainSchemaDiff: () => explainSchemaDiff,
+  generateAISuggestions: () => generateAISuggestions,
+  getLLMConfig: () => getLLMConfig,
+  validateSQL: () => validateSQL
+});
+function getLLMConfig() {
+  const provider = process.env.PG_DASH_LLM_PROVIDER || "openai";
+  return {
+    provider,
+    apiKey: process.env.PG_DASH_LLM_API_KEY || process.env.OPENAI_API_KEY || process.env.ANTHROPIC_API_KEY || process.env.GOOGLE_API_KEY,
+    baseUrl: process.env.PG_DASH_LLM_BASE_URL,
+    model: process.env.PG_DASH_LLM_MODEL
+  };
+}
+async function buildDatabaseContext(pool) {
+  const dbContext = await getDbContext(pool);
+  const tableInfos = dbContext.tables.slice(0, 30).map((table) => {
+    const columns = table.columns.map(
+      (col) => `  - ${col.name}: ${col.type}${col.isPrimaryKey ? " (PK)" : ""}${col.isForeignKey ? ` (FK -> ${col.references?.table}.${col.references?.column})` : ""}`
+    ).join("\n");
+    return `### ${table.schema}.${table.name} (${table.rowCount || "?"} rows, ${table.totalSize || "?"})
+${columns}`;
+  }).join("\n\n");
+  return `Database Schema (top tables by size):
+${tableInfos}
+
+Generate a PostgreSQL SELECT query to answer the user's question. 
+Rules:
+1. Only generate SELECT queries - no INSERT, UPDATE, DELETE, or DDL
+2. Use proper JOINs if needed
+3. Use LIMIT to cap results at 100 rows unless user specifies otherwise
+4. Use table aliases for clarity
+5. For time-based queries, use NOW() - INTERVAL syntax
+6. Use pg_ prefix system tables only if necessary
+
+Return ONLY the SQL query, no explanations.`;
+}
+async function callLLM(config, systemPrompt, userPrompt) {
+  const { provider, apiKey, baseUrl, model } = config;
+  if (!apiKey) {
+    throw new Error(`API key not configured. Set PG_DASH_LLM_API_KEY (or OPENAI_API_KEY/ANTHROPIC_API_KEY/GOOGLE_API_KEY)`);
+  }
+  const headers = {
+    "Content-Type": "application/json"
+  };
+  let url;
+  let body;
+  switch (provider) {
+    case "openai":
+      url = (baseUrl || "https://api.openai.com/v1") + "/chat/completions";
+      headers["Authorization"] = `Bearer ${apiKey}`;
+      body = {
+        model: model || "gpt-4o-mini",
+        messages: [
+          { role: "system", content: systemPrompt },
+          { role: "user", content: userPrompt }
+        ],
+        temperature: 0
+      };
+      break;
+    case "anthropic":
+      url = (baseUrl || "https://api.anthropic.com/v1") + "/messages";
+      headers["x-api-key"] = apiKey;
+      headers["anthropic-version"] = "2023-06-01";
+      body = {
+        model: model || "claude-3-haiku-20240307",
+        system: systemPrompt,
+        messages: [{ role: "user", content: userPrompt }],
+        max_tokens: 1024
+      };
+      break;
+    case "google":
+      url = (baseUrl || "https://generativelanguage.googleapis.com/v1beta") + `/models/${model || "gemini-2.0-flash-exp"}:generateContent?key=${apiKey}`;
+      body = {
+        contents: [{ parts: [{ text: `System: ${systemPrompt}
+
+User: ${userPrompt}` }] }],
+        generationConfig: { temperature: 0 }
+      };
+      break;
+    case "ollama":
+      url = (baseUrl || "http://localhost:11434") + "/api/generate";
+      body = {
+        model: model || "llama3.2",
+        prompt: `System: ${systemPrompt}
+
+User: ${userPrompt}`,
+        stream: false
+      };
+      break;
+    default:
+      throw new Error(`Unknown LLM provider: ${provider}`);
+  }
+  const response = await fetch(url, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body)
+  });
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`LLM API error (${response.status}): ${errorText}`);
+  }
+  const data = await response.json();
+  switch (provider) {
+    case "openai":
+      return data.choices?.[0]?.message?.content?.trim() || "";
+    case "anthropic":
+      return data.content?.[0]?.text?.trim() || "";
+    case "google":
+      return data.candidates?.[0]?.content?.parts?.[0]?.text?.trim() || "";
+    case "ollama":
+      return data.response?.trim() || "";
+    default:
+      return "";
+  }
+}
+function validateSQL(sql) {
+  const trimmed = sql.trim();
+  if (!/^\s*SELECT\b/i.test(trimmed)) {
+    return { valid: false, error: "Only SELECT queries are allowed" };
+  }
+  const dangerous = [
+    /;\s*(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|GRANT|REVOKE)/i,
+    /\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|GRANT|REVOKE)\b/i,
+    /pg_terminate_backend/i,
+    /pg_cancel_backend/i,
+    /\bCOPY\b/i,
+    /\bEXPLAIN\b.*\b(SELECT|INSERT|UPDATE|DELETE)\b/i
+    // Allow EXPLAIN but wrap it
+  ];
+  for (const pattern of dangerous) {
+    if (pattern.test(trimmed)) {
+      return { valid: false, error: `Disallowed pattern in query: ${pattern.source}` };
+    }
+  }
+  let finalSql = trimmed;
+  if (!/\bLIMIT\b/i.test(trimmed)) {
+    finalSql = `${trimmed} LIMIT 100`;
+  }
+  return { valid: true, sql: finalSql };
+}
+async function executeNaturalQuery(pool, naturalQuery, config) {
+  const llmConfig = config || getLLMConfig();
+  const contextPrompt = await buildDatabaseContext(pool);
+  const fullPrompt = `${contextPrompt}
+
+User's question: ${naturalQuery}
+
+Generate the SQL query now:`;
+  let sql;
+  try {
+    sql = await callLLM(
+      llmConfig,
+      "You are a PostgreSQL expert. Generate only SELECT queries based on the schema provided.",
+      fullPrompt
+    );
+  } catch (err) {
+    return {
+      answer: "",
+      sql: "",
+      error: `LLM call failed: ${err.message}`
+    };
+  }
+  const sqlMatch = sql.match(/```sql\n?([\s\S]*?)```/) || sql.match(/```\n?([\s\S]*?)```/) || [null, sql];
+  let extractedSql = sqlMatch[1]?.trim() || sql.trim();
+  const validation = validateSQL(extractedSql);
+  if (!validation.valid) {
+    return {
+      answer: "",
+      sql: extractedSql,
+      error: `SQL validation failed: ${validation.error}`
+    };
+  }
+  extractedSql = validation.sql;
+  let result;
+  const client = await pool.connect();
+  try {
+    const queryResult = await client.query(extractedSql);
+    result = {
+      rows: queryResult.rows,
+      rowCount: queryResult.rowCount || 0,
+      columns: queryResult.fields?.map((f) => f.name) || []
+    };
+  } catch (err) {
+    return {
+      answer: "",
+      sql: extractedSql,
+      error: `SQL execution failed: ${err.message}`
+    };
+  } finally {
+    client.release();
+  }
+  let answer = "";
+  if (result.rows.length === 0) {
+    answer = "No results found for your query.";
+  } else if (result.rows.length === 1) {
+    answer = `Found 1 result: ${JSON.stringify(result.rows[0])}`;
+  } else {
+    answer = `Found ${result.rowCount} results. Showing first ${Math.min(result.rows.length, 10)}:`;
+    answer += "\n\n" + JSON.stringify(result.rows.slice(0, 10), null, 2);
+    if (result.rows.length > 10) {
+      answer += `
+
+... and ${result.rows.length - 10} more rows (limited to 100)`;
+    }
+  }
+  return {
+    answer,
+    sql: extractedSql,
+    result
+  };
+}
+async function generateAISuggestions(report, config) {
+  const llmConfig = config || getLLMConfig();
+  if (!llmConfig.apiKey) {
+    return {
+      summary: `Health Score: ${report.score}/100 (${report.grade}). ${report.issues.length} issues found.`,
+      suggestions: report.issues.map((issue) => ({
+        issue: issue.title,
+        suggestion: issue.description,
+        priority: issue.severity
+      }))
+    };
+  }
+  const issuesText = report.issues.map(
+    (i) => `- [${i.severity}] ${i.title}: ${i.description}`
+  ).join("\n");
+  const prompt = `You are a PostgreSQL database expert. Analyze this health check report and provide:
+1. A one-sentence summary of the overall database health status
+2. Prioritized fix suggestions for each issue (most critical first)
+
+Health Report:
+- Score: ${report.score}/100 (Grade: ${report.grade})
+- Issues: ${report.issues.length}
+
+Issues:
+${issuesText}
+
+Return a JSON object with this exact structure:
+{
+  "summary": "one sentence summary",
+  "suggestions": [
+    { "issue": "issue title", "suggestion": "what to do", "priority": "critical|warning|info" }
+  ]
+}
+
+Only include issues that have actionable suggestions. Prioritize by severity (critical > warning > info).`;
+  try {
+    const response = await callLLM(
+      llmConfig,
+      "You are a PostgreSQL expert. Return only valid JSON.",
+      prompt
+    );
+    const jsonMatch = response.match(/\{[\s\S]*\}/);
+    if (jsonMatch) {
+      const parsed = JSON.parse(jsonMatch[0]);
+      return {
+        summary: parsed.summary || `Health Score: ${report.score}/100 (${report.grade})`,
+        suggestions: parsed.suggestions || []
+      };
+    }
+  } catch (err) {
+    console.error("[llm] AI suggestions error:", err);
+  }
+  return {
+    summary: `Health Score: ${report.score}/100 (${report.grade}). ${report.issues.length} issues found.`,
+    suggestions: report.issues.map((issue) => ({
+      issue: issue.title,
+      suggestion: issue.description,
+      priority: issue.severity
+    }))
+  };
+}
+async function explainSchemaDiff(diff, config) {
+  const llmConfig = config || getLLMConfig();
+  if (!llmConfig.apiKey) {
+    const parts = [];
+    if (diff.schema.missingTables.length > 0) {
+      parts.push(`Missing tables: ${diff.schema.missingTables.join(", ")}`);
+    }
+    if (diff.schema.extraTables.length > 0) {
+      parts.push(`Extra tables: ${diff.schema.extraTables.join(", ")}`);
+    }
+    if (diff.schema.columnDiffs.length > 0) {
+      parts.push(`Column changes in ${diff.schema.columnDiffs.length} tables`);
+    }
+    return parts.length > 0 ? parts.join("; ") : "No schema differences found.";
+  }
+  const changes = [];
+  for (const t of diff.schema.missingTables) {
+    changes.push(`- Table '${t}' exists in source but not in target`);
+  }
+  for (const t of diff.schema.extraTables) {
+    changes.push(`- Table '${t}' exists in target but not in source`);
+  }
+  for (const cd of diff.schema.columnDiffs) {
+    for (const col of cd.missingColumns) {
+      changes.push(`- Table '${cd.table}' missing column '${col.name}' (${col.type})`);
+    }
+    for (const col of cd.extraColumns) {
+      changes.push(`- Table '${cd.table}' has extra column '${col.name}' (${col.type})`);
+    }
+    for (const td of cd.typeDiffs) {
+      changes.push(`- Table '${cd.table}' column '${td.column}' type changed: ${td.sourceType} \u2192 ${td.targetType}`);
+    }
+  }
+  const prompt = `You are a PostgreSQL database expert. Explain the business impact of these schema differences in plain English.
+Focus on what these changes likely mean for the application (e.g., "Table 'orders' added column 'status' \u2014 likely for order state tracking").
+
+Schema Differences:
+${changes.join("\n") || "No differences"}
+
+Return a natural language explanation that is:
+1. Concise but informative
+2. Focused on business impact
+3. Developer-friendly
+
+Example format:
+"Table 'orders' added column 'status' \u2014 likely for order state tracking"
+"Table 'users' missing column 'email' \u2014 may break password reset functionality"
+
+Return only the explanation, no JSON:`;
+  try {
+    const response = await callLLM(
+      llmConfig,
+      "You are a PostgreSQL expert. Provide clear, actionable explanations.",
+      prompt
+    );
+    return response.trim();
+  } catch (err) {
+    console.error("[llm] Schema diff explanation error:", err);
+    return "Unable to generate AI explanation. Review the diff manually.";
+  }
+}
+var init_llm = __esm({
+  "src/server/llm.ts"() {
+    "use strict";
+    init_db_context();
+  }
+});
+
 // src/server/migration-checker.ts
 var migration_checker_exports = {};
 __export(migration_checker_exports, {
@@ -4166,6 +4754,8 @@ var { values, positionals } = parseArgs({
     format: { type: "string", short: "f" },
     ci: { type: "boolean", default: false },
     diff: { type: "boolean", default: false },
+    "ai-suggest": { type: "boolean", default: false },
+    "ai-explain": { type: "boolean", default: false },
     "snapshot-path": { type: "string" },
     source: { type: "string" },
     target: { type: "string" },
@@ -4224,6 +4814,8 @@ Options:
   -f, --format <fmt>     Output format: text|json|md (default: text)
   --ci                   Output GitHub Actions compatible annotations
   --diff                 Compare with previous run (saves snapshot for next run)
+  --ai-suggest           Use AI to generate fix suggestions (requires LLM config)
+  --ai-explain           Use AI to explain schema diff business impact (requires LLM config)
   --snapshot-path <path> Path to snapshot file for --diff (default: ~/.pg-dash/last-check.json)
   --source <url>         Source database connection string (diff-env)
   --target <url>         Target database connection string (diff-env)
@@ -4275,9 +4867,11 @@ if (subcommand === "check" || subcommand === "health") {
   const format = values.format || "text";
   const ci = values.ci || false;
   const useDiff = values.diff || false;
+  const aiSuggest = values["ai-suggest"] || false;
   const { Pool: Pool3 } = await import("pg");
   const { getAdvisorReport: getAdvisorReport2 } = await Promise.resolve().then(() => (init_advisor(), advisor_exports));
   const { saveSnapshot: saveSnapshot2, loadSnapshot: loadSnapshot2, diffSnapshots: diffSnapshots2 } = await Promise.resolve().then(() => (init_snapshot(), snapshot_exports));
+  const { generateAISuggestions: generateAISuggestions2, getLLMConfig: getLLMConfig2 } = await Promise.resolve().then(() => (init_llm(), llm_exports));
   const os4 = await import("os");
   const pool = new Pool3({ connectionString, connectionTimeoutMillis: 1e4 });
   const checkDataDir = values["data-dir"] || path5.join(os4.homedir(), ".pg-dash");
@@ -4351,6 +4945,26 @@ if (subcommand === "check" || subcommand === "health") {
         }
         console.log("```");
       }
+      if (aiSuggest && report.issues.length > 0) {
+        console.log(`
+### \u{1F916} AI Suggestions
+`);
+        try {
+          const aiResult = await generateAISuggestions2(report, getLLMConfig2());
+          console.log(`**Summary:** ${aiResult.summary}
+`);
+          if (aiResult.suggestions.length > 0) {
+            console.log(`| Priority | Issue | Suggestion |`);
+            console.log(`|----------|-------|------------|`);
+            for (const s of aiResult.suggestions) {
+              const icon = s.priority === "critical" ? "\u{1F534}" : s.priority === "warning" ? "\u{1F7E1}" : "\u{1F535}";
+              console.log(`| ${icon} ${s.priority} | ${s.issue} | ${s.suggestion} |`);
+            }
+          }
+        } catch (err) {
+          console.log(`*AI suggestions unavailable: ${err.message}*`);
+        }
+      }
     } else if (ci) {
       for (const issue of report.issues) {
         const level = issue.severity === "critical" ? "error" : issue.severity === "warning" ? "warning" : "notice";
@@ -4368,6 +4982,23 @@ Score: ${diff.previousScore} \u2192 ${report.score} (${sign}${diff.scoreDelta})`
         console.log(`Resolved: ${diff.resolvedIssues.length} issues`);
         console.log(`New: ${diff.newIssues.length} issues`);
       }
+      if (aiSuggest && report.issues.length > 0) {
+        console.log(`
+## \u{1F916} AI Fix Suggestions
+`);
+        try {
+          const aiResult = await generateAISuggestions2(report, getLLMConfig2());
+          console.log(aiResult.summary);
+          console.log();
+          for (const s of aiResult.suggestions) {
+            const sev = s.priority === "critical" ? "error" : s.priority === "warning" ? "warning" : "notice";
+            console.log(`::${sev}::${s.issue}`);
+            console.log(`   Suggestion: ${s.suggestion}`);
+          }
+        } catch (err) {
+          console.log(`*AI suggestions unavailable*`);
+        }
+      }
     } else {
       if (diff) {
         const sign = diff.scoreDelta >= 0 ? "+" : "";
@@ -4400,6 +5031,23 @@ Score: ${diff.previousScore} \u2192 ${report.score} (${sign}${diff.scoreDelta})`
           console.log(`  ${icon} [${issue.severity}] ${issue.title}`);
         }
       }
+      if (aiSuggest && report.issues.length > 0) {
+        console.log(`
+  \u{1F916} AI Suggestions:
+`);
+        try {
+          const aiResult = await generateAISuggestions2(report, getLLMConfig2());
+          console.log(`  ${aiResult.summary}
+`);
+          for (const s of aiResult.suggestions.slice(0, 5)) {
+            const icon = s.priority === "critical" ? "\u{1F534}" : s.priority === "warning" ? "\u{1F7E1}" : "\u{1F535}";
+            console.log(`  ${icon} [${s.priority}] ${s.issue}`);
+            console.log(`     \u2192 ${s.suggestion}`);
+          }
+        } catch (err) {
+          console.log(`  *AI suggestions unavailable*`);
+        }
+      }
       console.log();
     }
     await pool.end();
@@ -4542,16 +5190,40 @@ Migration check: ${filePath}`);
   const format = values.format || "text";
   const includeHealth = values.health || false;
   const ci = values.ci || false;
+  const aiExplain = values["ai-explain"] || false;
   const { diffEnvironments: diffEnvironments2, formatTextDiff: formatTextDiff2, formatMdDiff: formatMdDiff2 } = await Promise.resolve().then(() => (init_env_differ(), env_differ_exports));
+  const { explainSchemaDiff: explainSchemaDiff2, getLLMConfig: getLLMConfig2 } = await Promise.resolve().then(() => (init_llm(), llm_exports));
   try {
     const result = await diffEnvironments2(sourceUrl, targetUrl, { includeHealth });
     if (format === "json") {
       console.log(JSON.stringify(result, null, 2));
     } else if (format === "md") {
       console.log(formatMdDiff2(result));
+      if (aiExplain) {
+        console.log(`
+## \u{1F916} AI Business Impact Analysis
+`);
+        try {
+          const explanation = await explainSchemaDiff2(result, getLLMConfig2());
+          console.log(explanation);
+        } catch (err) {
+          console.log(`*AI explanation unavailable: ${err.message}*`);
+        }
+      }
     } else {
       const text = formatTextDiff2(result);
       console.log(text);
+      if (aiExplain) {
+        console.log(`
+\u{1F916} Business Impact:
+`);
+        try {
+          const explanation = await explainSchemaDiff2(result, getLLMConfig2());
+          console.log(`  ${explanation}`);
+        } catch (err) {
+          console.log(`  *AI explanation unavailable*`);
+        }
+      }
       if (ci) {
         for (const t of result.schema.missingTables) {
           console.log(`::error::diff-env: target missing table: ${t}`);