@indiekitai/pg-toolkit 0.1.0

package/README.md

@@ -0,0 +1,128 @@
+# @indiekitai/pg-toolkit
+
+Unified CLI for all IndieKit PostgreSQL tools. One command, all PG tools.
+
+## Install
+
+```bash
+npm install -g @indiekitai/pg-toolkit
+# or
+npx @indiekitai/pg-toolkit <command>
+```
+
+## Commands
+
+### `inspect` — Schema inspection
+
+```bash
+# Full schema dump
+pg-toolkit inspect postgresql://localhost/mydb
+
+# Filter to specific objects
+pg-toolkit inspect --tables postgresql://localhost/mydb
+pg-toolkit inspect --views --functions postgresql://localhost/mydb
+pg-toolkit inspect --enums --types postgresql://localhost/mydb
+
+# Summary counts
+pg-toolkit inspect --summary postgresql://localhost/mydb
+```
+
+Filters: `--tables`, `--views`, `--functions`, `--indexes`, `--sequences`, `--enums`, `--extensions`, `--triggers`, `--constraints`, `--schemas`, `--privileges`, `--types`, `--domains`, `--collations`, `--rls`
+
+### `diff` — Schema diff & migration SQL
+
+```bash
+# Generate migration SQL
+pg-toolkit diff postgresql://localhost/old postgresql://localhost/new
+
+# Safe mode (no DROP statements)
+pg-toolkit diff --safe postgresql://localhost/old postgresql://localhost/new
+
+# JSON output
+pg-toolkit diff --json postgresql://localhost/old postgresql://localhost/new
+
+# Pipe directly to psql
+pg-toolkit diff postgres://localhost/old postgres://localhost/new | psql postgres://localhost/old
+```
+
+### `top` — Activity monitor
+
+```bash
+# Interactive TUI
+pg-toolkit top postgresql://localhost/mydb
+
+# Custom refresh rate, hide idle
+pg-toolkit top --refresh 1 --no-idle postgresql://localhost/mydb
+
+# Single snapshot as JSON
+pg-toolkit top --snapshot --json postgresql://localhost/mydb
+```
+
+### `health` — Health checks
+
+```bash
+pg-toolkit health postgresql://localhost/mydb
+```
+
+Delegates to `pg-health` (must be installed separately via `pip install pg-health`).
+
+### `types` — TypeScript type generation
+
+```bash
+pg-toolkit types postgresql://localhost/mydb
+```
+
+Delegates to `pg2ts` (must be installed separately).
+
+### `mcp` — Unified MCP server
+
+Start a single MCP server that combines all PG tools:
+
+```bash
+pg-toolkit mcp
+```
+
+MCP config for AI agents:
+
+```json
+{
+  "mcpServers": {
+    "pg-toolkit": {
+      "command": "npx",
+      "args": ["@indiekitai/pg-toolkit", "mcp"],
+      "env": { "DATABASE_URL": "postgresql://localhost/mydb" }
+    }
+  }
+}
+```
+
+Available MCP tools:
+- `inspect_schema` — Inspect database schema
+- `diff_schemas` — Compare two databases
+- `pg_activity` — Get activity snapshot
+
+## Programmatic API
+
+```typescript
+import { inspect, diff, PgMonitor } from '@indiekitai/pg-toolkit';
+
+// Inspect
+const schema = await inspect('postgresql://localhost/mydb');
+
+// Diff
+const result = await diff(fromUrl, toUrl, { safe: true });
+
+// Monitor
+const monitor = new PgMonitor({ connectionString: '...', snapshot: true, json: true });
+```
+
+## Packages
+
+This toolkit wraps:
+- [@indiekitai/pg-inspect](https://github.com/indiekitai/pg-inspect) — Schema inspection
+- [@indiekitai/pg-diff](https://github.com/indiekitai/pg-diff) — Schema diff
+- [@indiekitai/pg-top](https://github.com/indiekitai/pg-top) — Activity monitor
+
+## License
+
+MIT

package/dist/analyze.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+import "./chunk-K3NQKI34.js";
+
+// src/analyze.ts
+var EAV_ENTITY_PATTERNS = /^(entity|item|record|submission|object|resource|parent)[_]?id$/i;
+var EAV_KEY_PATTERNS = /^(key|name|attribute|field|property|type|kind|label)[_]?(name|key|id)?$/i;
+var EAV_VALUE_PATTERNS = /^(value|data|content|payload|text)$/i;
+function detectEav(tableName, columns) {
+  const colNames = columns.map((c) => c.columnName);
+  const entityCol = colNames.find((c) => EAV_ENTITY_PATTERNS.test(c));
+  const keyCol = colNames.find((c) => EAV_KEY_PATTERNS.test(c));
+  const valueCol = colNames.find((c) => EAV_VALUE_PATTERNS.test(c));
+  if (entityCol && keyCol && valueCol) {
+    return {
+      type: "eav_pattern",
+      severity: "high",
+      table: tableName,
+      description: `Table "${tableName}" looks like an EAV table (entity=${entityCol}, key=${keyCol}, value=${valueCol}). Querying parent + this table typically causes N+1.`,
+      suggestion: `Use CTE + JSON_AGG to aggregate rows by "${entityCol}" in a single query.`,
+      sql: `WITH aggregated AS (
+  SELECT
+    "${entityCol}",
+    JSON_AGG(JSON_BUILD_OBJECT('${keyCol}', "${keyCol}", '${valueCol}', "${valueCol}")) AS attrs
+  FROM "${tableName}"
+  GROUP BY "${entityCol}"
+)
+SELECT p.*, COALESCE(a.attrs, '[]'::json) AS attrs
+FROM <parent_table> p
+LEFT JOIN aggregated a ON a."${entityCol}" = p.id;`
+    };
+  }
+  return null;
+}
+function detectNPlus1FromFks(fks) {
+  const parentToChildren = /* @__PURE__ */ new Map();
+  for (const fk of fks) {
+    const list = parentToChildren.get(fk.parentTable) || [];
+    list.push(fk);
+    parentToChildren.set(fk.parentTable, list);
+  }
+  const warnings = [];
+  for (const [parentTable, children] of parentToChildren) {
+    for (const fk of children) {
+      if (fk.childTable === parentTable) continue;
+      warnings.push({
+        type: "n_plus_1_risk",
+        severity: "medium",
+        table: fk.childTable,
+        parentTable,
+        description: `"${fk.childTable}".${fk.childColumn} \u2192 "${parentTable}".${fk.parentColumn}. Loading ${parentTable} list + ${fk.childTable} details per row = N+1.`,
+        suggestion: `Use CTE + JSON_AGG to pre-aggregate "${fk.childTable}" rows per "${fk.childColumn}".`,
+        sql: `WITH child_agg AS (
+  SELECT "${fk.childColumn}", JSON_AGG(t.*) AS children
+  FROM "${fk.childTable}" t
+  GROUP BY "${fk.childColumn}"
+)
+SELECT p.*, COALESCE(c.children, '[]'::json) AS ${fk.childTable}
+FROM "${parentTable}" p
+LEFT JOIN child_agg c ON c."${fk.childColumn}" = p."${fk.parentColumn}";`
+      });
+    }
+    const uniqueChildren = new Set(children.map((c) => c.childTable));
+    if (uniqueChildren.size > 2) {
+      warnings.push({
+        type: "multi_fk_parent",
+        severity: "low",
+        table: parentTable,
+        description: `"${parentTable}" has ${uniqueChildren.size} child tables referencing it. Loading all children per row compounds N+1.`,
+        suggestion: `Consider multiple CTEs in a single query to fetch all child data at once.`
+      });
+    }
+  }
+  return warnings;
+}
+async function analyze(connectionString) {
+  const pg = await import("pg");
+  const Pool = pg.default?.Pool || pg.Pool;
+  const pool = new Pool({ connectionString });
+  try {
+    const dbResult = await pool.query("SELECT current_database() AS db");
+    const database = dbResult.rows[0].db;
+    const colResult = await pool.query(`
+      SELECT table_name, column_name, data_type, is_nullable = 'YES' AS is_nullable
+      FROM information_schema.columns
+      WHERE table_schema = 'public'
+      ORDER BY table_name, ordinal_position
+    `);
+    const columnsByTable = /* @__PURE__ */ new Map();
+    for (const row of colResult.rows) {
+      const list = columnsByTable.get(row.table_name) || [];
+      list.push({
+        tableName: row.table_name,
+        columnName: row.column_name,
+        dataType: row.data_type,
+        isNullable: row.is_nullable
+      });
+      columnsByTable.set(row.table_name, list);
+    }
+    const fkResult = await pool.query(`
+      SELECT
+        tc.constraint_name,
+        tc.table_name AS child_table,
+        kcu.column_name AS child_column,
+        ccu.table_name AS parent_table,
+        ccu.column_name AS parent_column
+      FROM information_schema.table_constraints tc
+      JOIN information_schema.key_column_usage kcu
+        ON tc.constraint_name = kcu.constraint_name AND tc.table_schema = kcu.table_schema
+      JOIN information_schema.constraint_column_usage ccu
+        ON tc.constraint_name = ccu.constraint_name AND tc.table_schema = ccu.table_schema
+      WHERE tc.constraint_type = 'FOREIGN KEY' AND tc.table_schema = 'public'
+    `);
+    const fks = fkResult.rows.map((r) => ({
+      constraintName: r.constraint_name,
+      childTable: r.child_table,
+      childColumn: r.child_column,
+      parentTable: r.parent_table,
+      parentColumn: r.parent_column
+    }));
+    const warnings = [];
+    for (const [tableName, columns] of columnsByTable) {
+      const eav = detectEav(tableName, columns);
+      if (eav) warnings.push(eav);
+    }
+    warnings.push(...detectNPlus1FromFks(fks));
+    const severityOrder = { high: 0, medium: 1, low: 2 };
+    warnings.sort((a, b) => severityOrder[a.severity] - severityOrder[b.severity]);
+    return {
+      database,
+      analyzedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      tablesScanned: columnsByTable.size,
+      warnings
+    };
+  } finally {
+    await pool.end();
+  }
+}
+function formatAnalyzeResult(result, json) {
+  if (json) return JSON.stringify(result, null, 2);
+  const lines = [];
+  lines.push(`\u{1F50D} N+1 Analysis for "${result.database}"`);
+  lines.push(`   Scanned ${result.tablesScanned} tables at ${result.analyzedAt}`);
+  lines.push("");
+  if (result.warnings.length === 0) {
+    lines.push("\u2705 No N+1 patterns detected.");
+    return lines.join("\n");
+  }
+  lines.push(`\u26A0\uFE0F  Found ${result.warnings.length} potential issue(s):
+`);
+  const severityIcon = { high: "\u{1F534}", medium: "\u{1F7E1}", low: "\u{1F535}" };
+  for (const w of result.warnings) {
+    lines.push(`${severityIcon[w.severity]} [${w.severity.toUpperCase()}] ${w.type}`);
+    lines.push(`   ${w.description}`);
+    lines.push(`   \u{1F4A1} ${w.suggestion}`);
+    if (w.sql) {
+      lines.push("   \u{1F4DD} Suggested SQL:");
+      for (const sqlLine of w.sql.split("\n")) {
+        lines.push(`      ${sqlLine}`);
+      }
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+export {
+  analyze,
+  formatAnalyzeResult
+};

package/dist/chunk-K3NQKI34.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+export {
+  __export
+};

package/dist/cli.js

@@ -0,0 +1,270 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { inspect } from "@indiekitai/pg-inspect";
+import { diff } from "@indiekitai/pg-diff";
+import { PgMonitor } from "@indiekitai/pg-top";
+import { execFileSync } from "child_process";
+var VERSION = "0.1.0";
+var HELP = `
+pg-toolkit v${VERSION} \u2014 Unified PostgreSQL toolkit
+
+Usage:
+  pg-toolkit <command> [options] [connection-string...]
+
+Commands:
+  inspect   Inspect database schema (tables, views, functions, etc.)
+  diff      Compare two database schemas and generate migration SQL
+  top       Real-time activity monitor (like top for Postgres)
+  analyze   Detect N+1 query patterns and suggest CTE + JSON_AGG optimizations
+  health    Run health checks (requires pg-health)
+  types     Generate TypeScript types from schema (requires pg2ts)
+  mcp       Start unified MCP server
+
+Run 'pg-toolkit <command> --help' for command-specific help.
+`.trim();
+function getConnStr(args) {
+  const url = args.find((a) => !a.startsWith("-"));
+  return url || process.env.DATABASE_URL || "";
+}
+function die(msg) {
+  console.error("Error: " + msg);
+  process.exit(1);
+}
+function mapToObj(map) {
+  const obj = {};
+  for (const [k, v] of map) obj[k] = serialize(v);
+  return obj;
+}
+function serialize(val) {
+  if (val instanceof Map) return mapToObj(val);
+  if (Array.isArray(val)) return val.map(serialize);
+  if (val && typeof val === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(val)) {
+      if (typeof v === "function" || k.startsWith("_")) continue;
+      out[k] = serialize(v);
+    }
+    return out;
+  }
+  return val;
+}
+var INSPECT_FILTERS = [
+  "tables",
+  "views",
+  "functions",
+  "indexes",
+  "sequences",
+  "enums",
+  "extensions",
+  "triggers",
+  "constraints",
+  "schemas",
+  "privileges",
+  "types",
+  "domains",
+  "collations",
+  "rls"
+];
+async function cmdInspect(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(`pg-toolkit inspect \u2014 Inspect PostgreSQL schema
+
+Usage: pg-toolkit inspect [options] <connection-string>
+
+Options:
+  --tables, --views, --functions, --indexes, --sequences,
+  --enums, --extensions, --triggers, --constraints, --schemas,
+  --privileges, --types, --domains, --collations, --rls
+      Filter to specific object types
+
+  --summary    Show summary counts only
+  --json       JSON output (default)`);
+    return;
+  }
+  const connStr = getConnStr(args);
+  if (!connStr) die("Connection string required. Usage: pg-toolkit inspect <connection-string>");
+  const result = await inspect(connStr);
+  const filters = INSPECT_FILTERS.filter((f) => args.includes(`--${f}`));
+  const summary = args.includes("--summary");
+  if (summary) {
+    const counts = {};
+    for (const key of Object.keys(result)) {
+      const val = result[key];
+      if (val instanceof Map) counts[key] = val.size;
+      else if (Array.isArray(val)) counts[key] = val.length;
+    }
+    console.log(JSON.stringify(counts, null, 2));
+    return;
+  }
+  if (filters.length > 0) {
+    const out = {};
+    for (const f of filters) {
+      const val = result[f];
+      if (val) out[f] = serialize(val);
+    }
+    console.log(JSON.stringify(out, null, 2));
+  } else {
+    console.log(JSON.stringify(serialize(result), null, 2));
+  }
+}
+async function cmdDiff(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(`pg-toolkit diff \u2014 Compare two PostgreSQL schemas
+
+Usage: pg-toolkit diff [options] <from_url> <to_url>
+
+Options:
+  --json       JSON output (machine-readable)
+  --safe       Omit DROP statements`);
+    return;
+  }
+  const urls = args.filter((a) => !a.startsWith("-"));
+  if (urls.length < 2) die("Two connection strings required. Usage: pg-toolkit diff <from_url> <to_url>");
+  const jsonMode = args.includes("--json");
+  const safe = args.includes("--safe");
+  const ignoreExtVersions = args.includes("--ignore-extension-versions");
+  const result = await diff(urls[0], urls[1], { safe, ignoreExtensionVersions: ignoreExtVersions });
+  if (jsonMode) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    if (result.sql) {
+      console.log(result.sql);
+    } else {
+      console.log("No differences found.");
+    }
+  }
+}
+async function cmdTop(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(`pg-toolkit top \u2014 Real-time PostgreSQL activity monitor
+
+Usage: pg-toolkit top [options] <connection-string>
+
+Options:
+  --refresh <seconds>   Refresh interval (default: 2)
+  --no-idle             Hide idle connections
+  --snapshot            Single snapshot, then exit
+  --json                Output as JSON (with --snapshot)`);
+    return;
+  }
+  const connStr = getConnStr(args);
+  if (!connStr) die("Connection string required. Usage: pg-toolkit top <connection-string>");
+  let refreshInterval = 2;
+  let noIdle = false;
+  let snapshot = false;
+  let json = false;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--refresh" && args[i + 1]) refreshInterval = Number(args[++i]);
+    else if (args[i] === "--no-idle") noIdle = true;
+    else if (args[i] === "--snapshot") snapshot = true;
+    else if (args[i] === "--json") json = true;
+  }
+  const monitor = new PgMonitor({
+    connectionString: connStr,
+    refreshInterval,
+    noIdle,
+    snapshot,
+    json
+  });
+  await monitor.start();
+}
+function cmdHealth(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(`pg-toolkit health \u2014 PostgreSQL health checks (delegates to pg-health)
+
+Usage: pg-toolkit health <connection-string>
+
+Requires pg-health to be installed (pip install pg-health or available in PATH).`);
+    return;
+  }
+  const connStr = getConnStr(args);
+  if (!connStr) die("Connection string required.");
+  try {
+    execFileSync("pg-health", [connStr], { stdio: "inherit" });
+  } catch {
+    console.error("pg-health not found. Install it: pip install pg-health");
+    process.exit(1);
+  }
+}
+function cmdTypes(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(`pg-toolkit types \u2014 Generate TypeScript types from PostgreSQL schema
+
+Usage: pg-toolkit types <connection-string>
+
+Requires pg2ts to be installed and available in PATH.`);
+    return;
+  }
+  const connStr = getConnStr(args);
+  if (!connStr) die("Connection string required.");
+  try {
+    execFileSync("pg2ts", [connStr], { stdio: "inherit" });
+  } catch {
+    console.error("pg2ts not found. Install it or check PATH.");
+    process.exit(1);
+  }
+}
+async function cmdAnalyze(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(`pg-toolkit analyze \u2014 Detect N+1 query patterns and suggest optimizations
+
+Usage: pg-toolkit analyze [options] <connection-string>
+
+Options:
+  --json       JSON output (default: human-readable)
+
+Scans table structures and foreign keys to detect:
+  - EAV (Entity-Attribute-Value) pattern tables
+  - Many-to-one relationships prone to N+1
+  - Tables with multiple child tables
+
+Suggests CTE + JSON_AGG rewrites for each finding.`);
+    return;
+  }
+  const connStr = getConnStr(args);
+  if (!connStr) die("Connection string required. Usage: pg-toolkit analyze <connection-string>");
+  const { analyze, formatAnalyzeResult } = await import("./analyze.js");
+  const result = await analyze(connStr);
+  const jsonMode = args.includes("--json");
+  console.log(formatAnalyzeResult(result, jsonMode));
+}
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+  const rest = args.slice(1);
+  if (!command || command === "--help" || command === "-h") {
+    console.log(HELP);
+    return;
+  }
+  if (command === "--version" || command === "-v") {
+    console.log(VERSION);
+    return;
+  }
+  switch (command) {
+    case "inspect":
+      return cmdInspect(rest);
+    case "diff":
+      return cmdDiff(rest);
+    case "top":
+      return cmdTop(rest);
+    case "analyze":
+      return cmdAnalyze(rest);
+    case "health":
+      return cmdHealth(rest);
+    case "types":
+      return cmdTypes(rest);
+    case "mcp": {
+      const { startMcpServer } = await import("./mcp.js");
+      return startMcpServer();
+    }
+    default:
+      console.error(`Unknown command: ${command}`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}
+main().catch((err) => {
+  console.error(err.message || err);
+  process.exit(1);
+});