@dypai-ai/mcp 1.4.5 → 1.5.0

package/src/tools/manage-database.js

@@ -0,0 +1,546 @@
+/**
+ * manage_database — one tool for all DB ops that aren't simple single-statement SQL.
+ *
+ * Consolidates what used to be three separate tools (`run_migration`,
+ * `introspect`, `execute_script`) into a single discriminated-union tool,
+ * matching the `manage_users` / `manage_roles` / `manage_drafts` pattern
+ * the rest of the catalog already uses.
+ *
+ * Operations:
+ *   apply_migration       Apply a versioned .sql file with tracking + idempotency
+ *   list_migrations       List rows from system.applied_migrations
+ *   introspect_schema     List tables, views, functions in a schema
+ *   introspect_table      Full table detail: columns, PK, FKs, indexes, triggers, RLS
+ *   introspect_function   Function(s) with signatures + body
+ *   execute_script        Multi-statement transactional SQL (for one-off non-migration scripts)
+ *
+ * Why not individual tools:
+ *   - Catalog density. Each extra tool taxes the agent's planning — it has
+ *     to read descriptions, decide which fits, and remember edge cases.
+ *   - Semantic cohesion. All of these are "schema-level / structural DB
+ *     operations beyond a single SQL statement". They belong together.
+ *   - Future-proof. `list_migrations`, `revert_migration`, `diff_schema`
+ *     etc. slot in as new operations without bloating the catalog.
+ *
+ * execute_sql stays as its own tool because it's the hot path (called in
+ * ~80% of sessions) and forcing `operation:"query"` every time is friction.
+ */
+
+import { readFile, access } from "fs/promises"
+import { createHash } from "crypto"
+import { basename, extname, isAbsolute } from "path"
+import { proxyToolCall } from "./proxy.js"
+import { validateSql, formatValidationError } from "./sql-guard.js"
+import { resolveAndGuard } from "./sync/path-resolver.js"
+import { maybeRefreshSchemaAfterExecuteSql } from "./sql-side-effects.js"
+
+// Refresh local dypai/schema.sql if the SQL we just executed changed the
+// public schema. No-ops silently when no local dypai/ folder is found.
+async function maybeRefreshSchema(project_id, sql, result) {
+  try {
+    const refresh = await maybeRefreshSchemaAfterExecuteSql({ project_id, sql }, result)
+    if (refresh.refreshed) return { schema_refreshed: true, schema_path: refresh.path }
+    if (refresh.error)    return { schema_refresh_warning: refresh.error }
+  } catch {
+    // Never let schema.sql bookkeeping break the actual DB operation.
+  }
+  return {}
+}
+
+// ─── helpers ────────────────────────────────────────────────────────────────
+
+function sha256(s) {
+  return createHash("sha256").update(s).digest("hex")
+}
+
+function countStatements(sql) {
+  if (!sql) return 0
+  let s = sql
+    .replace(/--[^\n]*/g, "")
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/\$([A-Za-z_][A-Za-z0-9_]*)?\$[\s\S]*?\$\1\$/g, "''")
+    .replace(/'(?:''|[^'])*'/g, "''")
+  return s.split(";").map(x => x.trim()).filter(Boolean).length
+}
+
+function normalizeName(file) {
+  return basename(file, extname(file)) || file
+}
+
+async function pathExists(p) {
+  try { await access(p); return true } catch { return false }
+}
+
+function parseTableName(name) {
+  const m = String(name).trim().match(/^([a-zA-Z_][\w$]*)(?:\.([a-zA-Z_][\w$]*))?$/)
+  if (!m) return null
+  return m[2]
+    ? { schema: m[1], table: m[2] }
+    : { schema: "public", table: m[1] }
+}
+
+function parseFunctionName(name) {
+  const s = String(name).trim()
+  const sigM = s.match(/^([^(]+)\((.*)\)$/)
+  const ident = sigM ? sigM[1].trim() : s
+  const sig   = sigM ? sigM[2].trim() : null
+  const m = ident.match(/^([a-zA-Z_][\w$]*)(?:\.([a-zA-Z_][\w$]*))?$/)
+  if (!m) return null
+  return m[2]
+    ? { schema: m[1], func: m[2], signature: sig }
+    : { schema: "public", func: m[1], signature: sig }
+}
+
+async function runSelect(project_id, sql) {
+  const v = validateSql(sql, { allowSelectOnly: true })
+  if (!v.ok) throw new Error(`manage_database: ${formatValidationError(v)}`)
+  const args = project_id ? { project_id, sql } : { sql }
+  const res = await proxyToolCall("execute_sql", args)
+  return Array.isArray(res?.rows) ? res.rows : (Array.isArray(res) ? res : [])
+}
+
+// ─── apply_migration ────────────────────────────────────────────────────────
+//
+// Thin client: reads the file, computes checksum, hands the body +
+// metadata to the cloud `apply_migration` tool. The cloud handles the
+// transaction, the guard, the tracking INSERT, and all idempotency checks.
+
+async function applyMigration({ project_id, migration_file, dry_run, timeout_seconds }) {
+  if (!migration_file || typeof migration_file !== "string") {
+    return { success: false, error: "migration_file is required (string path)." }
+  }
+
+  let resolved
+  if (isAbsolute(migration_file)) {
+    resolved = { ok: true, path: migration_file, source: "absolute" }
+  } else {
+    resolved = resolveAndGuard(migration_file, {
+      project_id,
+      tool: "manage_database",
+      arg_name: "migration_file",
+    })
+    if (!resolved.ok) return resolved.error
+  }
+  const filePath = resolved.path
+
+  if (!(await pathExists(filePath))) {
+    return {
+      success: false,
+      error: `Migration file not found: ${filePath}`,
+      hint: "Create dypai/migrations/<NNNN>_<description>.sql and pass that path.",
+    }
+  }
+
+  const body = await readFile(filePath, "utf8")
+  if (!body.trim()) return { success: false, error: "Migration file is empty." }
+
+  // Early local validation — cleaner error than a network roundtrip just to
+  // get the same message back.
+  const v = validateSql(body)
+  if (!v.ok) {
+    return {
+      success: false,
+      error: formatValidationError(v),
+      resolved_path: filePath,
+    }
+  }
+
+  const name = normalizeName(filePath)
+  const checksum = sha256(body)
+  const statements = countStatements(body)
+
+  if (dry_run) {
+    return {
+      success: true,
+      status: "dry_run",
+      name,
+      checksum,
+      statements,
+      resolved_path: filePath,
+      body_preview: body.length > 400 ? `${body.slice(0, 400)}…` : body,
+      hint: "Call again with dry_run:false to apply.",
+    }
+  }
+
+  const args = { name, body, checksum, statements }
+  if (project_id)        args.project_id = project_id
+  if (timeout_seconds)   args.timeout_seconds = timeout_seconds
+
+  try {
+    const res = await proxyToolCall("apply_migration", args)
+    const base = {
+      success: res?.status === "applied" || res?.status === "skipped",
+      status: res?.status ?? "unknown",
+      name,
+      checksum,
+      statements,
+      resolved_path: filePath,
+      duration_ms: res?.duration_ms,
+      applied_at: res?.applied_at,
+      applied_by: res?.applied_by,
+      reason: res?.reason,
+      error: res?.error,
+      hint: res?.hint,
+      previous_checksum: res?.previous_checksum,
+      current_checksum: res?.current_checksum,
+      message:
+        res?.status === "applied"
+          ? `Migration '${name}' applied (${statements} statement${statements === 1 ? "" : "s"}).`
+          : res?.status === "skipped"
+            ? `Migration '${name}' already applied.`
+            : undefined,
+    }
+    const refreshInfo =
+      res?.status === "applied" ? await maybeRefreshSchema(project_id, body, res) : {}
+    return { ...base, ...refreshInfo }
+  } catch (e) {
+    return {
+      success: false,
+      status: "failed",
+      name,
+      resolved_path: filePath,
+      error: e.message,
+    }
+  }
+}
+
+// ─── list_migrations ────────────────────────────────────────────────────────
+
+async function listMigrations({ project_id, limit = 50 }) {
+  const safeLimit = Math.min(Math.max(Number(limit) || 50, 1), 500)
+  const sql = `SELECT name, checksum, statements, applied_at, applied_by
+               FROM system.applied_migrations
+               ORDER BY applied_at DESC
+               LIMIT ${safeLimit}`
+  try {
+    const rows = await runSelect(project_id, sql)
+    return { success: true, total: rows.length, migrations: rows }
+  } catch (e) {
+    // Likely cause: system.applied_migrations not provisioned yet on this
+    // project. Surface cleanly rather than raw PG error.
+    if (/applied_migrations.*does not exist/i.test(e.message || "")) {
+      return {
+        success: true,
+        total: 0,
+        migrations: [],
+        hint:
+          "system.applied_migrations doesn't exist on this project's DB. " +
+          "Run sync_schema against the project or wait for the next provisioning cycle.",
+      }
+    }
+    return { success: false, error: e.message }
+  }
+}
+
+// ─── introspect_schema ──────────────────────────────────────────────────────
+
+async function introspectSchema({ project_id, name }) {
+  const parsed = parseTableName(name)
+  if (!parsed) return { success: false, error: `Invalid schema name: ${name}` }
+  const s = parsed.schema.replace(/'/g, "''")
+
+  const [tables, views, functions] = await Promise.all([
+    runSelect(project_id, `SELECT tablename AS name FROM pg_catalog.pg_tables WHERE schemaname='${s}' ORDER BY tablename`),
+    runSelect(project_id, `SELECT viewname  AS name FROM pg_catalog.pg_views  WHERE schemaname='${s}' ORDER BY viewname`),
+    runSelect(project_id, `
+      SELECT p.proname AS name,
+             pg_catalog.pg_get_function_identity_arguments(p.oid) AS args,
+             pg_catalog.pg_get_function_result(p.oid) AS returns
+      FROM pg_catalog.pg_proc p
+      JOIN pg_catalog.pg_namespace n ON n.oid = p.pronamespace
+      WHERE n.nspname = '${s}' AND p.prokind IN ('f','p')
+      ORDER BY p.proname, args
+    `),
+  ])
+
+  return {
+    success: true,
+    schema: parsed.schema,
+    tables: tables.map(r => r.name),
+    views: views.map(r => r.name),
+    functions: functions.map(r => ({ name: r.name, args: r.args, returns: r.returns })),
+  }
+}
+
+// ─── introspect_table ───────────────────────────────────────────────────────
+
+async function introspectTable({ project_id, name }) {
+  const parsed = parseTableName(name)
+  if (!parsed) return { success: false, error: `Invalid table name: ${name}` }
+  const s = parsed.schema.replace(/'/g, "''")
+  const t = parsed.table.replace(/'/g, "''")
+
+  const [columns, pk, fks, indexes, triggers, rls, rowcount] = await Promise.all([
+    runSelect(project_id, `
+      SELECT column_name, data_type, is_nullable,
+             column_default, character_maximum_length, udt_name
+      FROM information_schema.columns
+      WHERE table_schema='${s}' AND table_name='${t}'
+      ORDER BY ordinal_position
+    `),
+    runSelect(project_id, `
+      SELECT kcu.column_name
+      FROM information_schema.table_constraints tc
+      JOIN information_schema.key_column_usage kcu
+        ON kcu.constraint_name=tc.constraint_name AND kcu.table_schema=tc.table_schema
+      WHERE tc.table_schema='${s}' AND tc.table_name='${t}'
+        AND tc.constraint_type='PRIMARY KEY'
+      ORDER BY kcu.ordinal_position
+    `),
+    runSelect(project_id, `
+      SELECT kcu.column_name,
+             ccu.table_schema AS foreign_schema,
+             ccu.table_name   AS foreign_table,
+             ccu.column_name  AS foreign_column,
+             rc.update_rule, rc.delete_rule
+      FROM information_schema.table_constraints tc
+      JOIN information_schema.key_column_usage kcu
+        ON kcu.constraint_name=tc.constraint_name AND kcu.table_schema=tc.table_schema
+      JOIN information_schema.referential_constraints rc
+        ON rc.constraint_name=tc.constraint_name AND rc.constraint_schema=tc.table_schema
+      JOIN information_schema.constraint_column_usage ccu
+        ON ccu.constraint_name=tc.constraint_name AND ccu.table_schema=tc.table_schema
+      WHERE tc.table_schema='${s}' AND tc.table_name='${t}' AND tc.constraint_type='FOREIGN KEY'
+      ORDER BY kcu.ordinal_position
+    `),
+    runSelect(project_id, `
+      SELECT indexname AS name, indexdef AS definition
+      FROM pg_catalog.pg_indexes
+      WHERE schemaname='${s}' AND tablename='${t}'
+      ORDER BY indexname
+    `),
+    runSelect(project_id, `
+      SELECT trigger_name AS name, event_manipulation AS event,
+             action_timing AS timing, action_statement AS body
+      FROM information_schema.triggers
+      WHERE event_object_schema='${s}' AND event_object_table='${t}'
+      ORDER BY trigger_name
+    `),
+    runSelect(project_id, `
+      SELECT polname AS name, polcmd AS command,
+             pg_catalog.pg_get_expr(polqual, polrelid) AS using_expr,
+             pg_catalog.pg_get_expr(polwithcheck, polrelid) AS check_expr,
+             (SELECT relrowsecurity FROM pg_catalog.pg_class c
+                WHERE c.relname='${t}'
+                  AND c.relnamespace=(SELECT oid FROM pg_catalog.pg_namespace WHERE nspname='${s}')) AS rls_enabled
+      FROM pg_catalog.pg_policy p
+      JOIN pg_catalog.pg_class c ON c.oid=p.polrelid
+      JOIN pg_catalog.pg_namespace n ON n.oid=c.relnamespace
+      WHERE n.nspname='${s}' AND c.relname='${t}'
+      ORDER BY polname
+    `),
+    runSelect(project_id, `
+      SELECT reltuples::bigint AS approximate_rows
+      FROM pg_catalog.pg_class c
+      JOIN pg_catalog.pg_namespace n ON n.oid=c.relnamespace
+      WHERE n.nspname='${s}' AND c.relname='${t}'
+      LIMIT 1
+    `),
+  ])
+
+  const exists = columns.length > 0
+  return {
+    success: exists,
+    schema: parsed.schema,
+    table: parsed.table,
+    exists,
+    approximate_rows: rowcount[0]?.approximate_rows ?? null,
+    columns,
+    primary_key: pk.map(r => r.column_name),
+    foreign_keys: fks,
+    indexes,
+    triggers,
+    row_level_security: {
+      enabled: rls[0]?.rls_enabled === true,
+      policies: rls,
+    },
+    error: exists ? undefined : `Table ${parsed.schema}.${parsed.table} does not exist.`,
+  }
+}
+
+// ─── introspect_function ────────────────────────────────────────────────────
+
+async function introspectFunction({ project_id, name }) {
+  const parsed = parseFunctionName(name)
+  if (!parsed) return { success: false, error: `Invalid function name: ${name}` }
+  const s = parsed.schema.replace(/'/g, "''")
+  const f = parsed.func.replace(/'/g, "''")
+
+  let overloads = await runSelect(project_id, `
+    SELECT p.oid,
+           p.proname AS name,
+           pg_catalog.pg_get_function_identity_arguments(p.oid) AS args,
+           pg_catalog.pg_get_function_result(p.oid) AS returns,
+           p.prokind,
+           l.lanname AS language,
+           p.prosecdef AS security_definer,
+           p.provolatile AS volatile_flag,
+           pg_catalog.pg_get_functiondef(p.oid) AS definition
+    FROM pg_catalog.pg_proc p
+    JOIN pg_catalog.pg_namespace n ON n.oid = p.pronamespace
+    JOIN pg_catalog.pg_language l  ON l.oid = p.prolang
+    WHERE n.nspname='${s}' AND p.proname='${f}' AND p.prokind IN ('f','p')
+    ORDER BY args
+  `)
+
+  if (parsed.signature != null) {
+    const norm = sig => sig.replace(/\s+/g, "").toLowerCase()
+    const wanted = norm(parsed.signature)
+    overloads = overloads.filter(o => norm(o.args) === wanted)
+  }
+
+  if (!overloads.length) {
+    return {
+      success: false,
+      schema: parsed.schema,
+      name: parsed.func,
+      error: parsed.signature
+        ? `No function ${parsed.schema}.${parsed.func}(${parsed.signature}) — signature not found.`
+        : `No function ${parsed.schema}.${parsed.func} exists.`,
+      hint: "Use operation='introspect_schema' to list functions.",
+    }
+  }
+
+  return {
+    success: true,
+    schema: parsed.schema,
+    name: parsed.func,
+    requested_signature: parsed.signature ?? null,
+    overloads: overloads.map(o => ({
+      signature: `${parsed.schema}.${parsed.func}(${o.args})`,
+      args: o.args,
+      returns: o.returns,
+      kind: o.prokind === "p" ? "procedure" : "function",
+      language: o.language,
+      security_definer: o.security_definer,
+      volatile: o.volatile_flag === "i" ? "immutable" : o.volatile_flag === "s" ? "stable" : "volatile",
+      definition: o.definition,
+    })),
+  }
+}
+
+// ─── execute_script ─────────────────────────────────────────────────────────
+
+async function executeScript({ project_id, sql, timeout_seconds }) {
+  if (!sql || typeof sql !== "string") {
+    return { success: false, error: "sql is required (string)." }
+  }
+  const v = validateSql(sql)
+  if (!v.ok) return { success: false, error: formatValidationError(v) }
+
+  const args = { sql }
+  if (project_id)      args.project_id = project_id
+  if (timeout_seconds) args.timeout_seconds = timeout_seconds
+  try {
+    const res = await proxyToolCall("execute_script", args)
+    const refreshInfo = await maybeRefreshSchema(project_id, sql, res)
+    return { success: true, ...res, ...refreshInfo }
+  } catch (e) {
+    return { success: false, error: e.message }
+  }
+}
+
+// ─── tool definition ────────────────────────────────────────────────────────
+
+export const manageDatabaseTool = {
+  name: "manage_database",
+  description:
+    "Database operations beyond a single SQL statement. Use `execute_sql` for " +
+    "ad-hoc single-statement queries; this tool covers migrations, introspection, " +
+    "and multi-statement transactional scripts.\n\n" +
+    "Operations:\n" +
+    "- apply_migration:    Apply dypai/migrations/<file>.sql with tracking + idempotency.\n" +
+    "                      Same file twice → no-op. Modified file → checksum_mismatch.\n" +
+    "- list_migrations:    Show rows from system.applied_migrations (what has been applied, when, by whom).\n" +
+    "- introspect_schema:  List tables, views, functions in a schema.\n" +
+    "- introspect_table:   Full detail: columns, PK, FKs, indexes, triggers, RLS, approx rows.\n" +
+    "- introspect_function: Function(s) with signatures + body. Overloads disambiguated by signature.\n" +
+    "- execute_script:     Multi-statement SQL in a single transaction. For one-off non-migration scripts;\n" +
+    "                      prefer apply_migration for anything you want versioned.\n\n" +
+    "All operations respect the SQL guard: writes to auth/storage/system/pg_* are blocked; SELECTs are allowed.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      project_id: {
+        type: "string",
+        description: "Project UUID. Optional if your token is project-scoped.",
+      },
+      operation: {
+        type: "string",
+        enum: [
+          "apply_migration",
+          "list_migrations",
+          "introspect_schema",
+          "introspect_table",
+          "introspect_function",
+          "execute_script",
+        ],
+        description: "Which operation to run.",
+      },
+      // apply_migration
+      migration_file: {
+        type: "string",
+        description:
+          "apply_migration only. Path to the .sql file, absolute preferred. " +
+          "Relative paths are resolved via env vars (CLAUDE_PROJECT_DIR, WORKSPACE_FOLDER_PATHS) and project markers.",
+      },
+      dry_run: {
+        type: "boolean",
+        description: "apply_migration only. Validate + preview without executing. Default false.",
+        default: false,
+      },
+      // introspect_*
+      name: {
+        type: "string",
+        description:
+          "Identifier for introspect_* operations. " +
+          "schema='public' | table='public.orders' | function='public.foo' or 'public.foo(uuid,text)'.",
+      },
+      // execute_script
+      sql: {
+        type: "string",
+        description: "execute_script only. Multi-statement SQL to run in one transaction.",
+      },
+      // shared
+      timeout_seconds: {
+        type: "integer",
+        description: "apply_migration / execute_script: per-statement timeout (default 300, max 1800).",
+      },
+      limit: {
+        type: "integer",
+        description: "list_migrations only. Max rows returned (default 50, max 500).",
+      },
+    },
+    required: ["operation"],
+    allOf: [
+      { if: { properties: { operation: { const: "apply_migration" } }, required: ["operation"] },
+        then: { required: ["migration_file"] } },
+      { if: { properties: { operation: { const: "introspect_schema" } }, required: ["operation"] },
+        then: { required: ["name"] } },
+      { if: { properties: { operation: { const: "introspect_table" } }, required: ["operation"] },
+        then: { required: ["name"] } },
+      { if: { properties: { operation: { const: "introspect_function" } }, required: ["operation"] },
+        then: { required: ["name"] } },
+      { if: { properties: { operation: { const: "execute_script" } }, required: ["operation"] },
+        then: { required: ["sql"] } },
+    ],
+  },
+
+  async execute(args = {}) {
+    const { operation } = args
+    switch (operation) {
+      case "apply_migration":     return applyMigration(args)
+      case "list_migrations":     return listMigrations(args)
+      case "introspect_schema":   return introspectSchema(args)
+      case "introspect_table":    return introspectTable(args)
+      case "introspect_function": return introspectFunction(args)
+      case "execute_script":      return executeScript(args)
+      default:
+        return {
+          success: false,
+          error: `Unknown operation: ${operation}`,
+          hint: "Valid operations: apply_migration, list_migrations, introspect_schema, introspect_table, introspect_function, execute_script.",
+        }
+    }
+  },
+}