@withpica/mcp-server 2.35.0 → 2.40.0

package/scripts/refresh-schema-mirror.ts

@@ -0,0 +1,182 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+/**
+ * ADR-214 — refresh schema-mirror.json against staging or prod.
+ *
+ * Connects to the configured Postgres URL (env var SUPABASE_DB_URL or
+ * DATABASE_URL) and queries pg_constraint for CHECK constraints on the
+ * tables backing Phase 1 schema resources. Parses the constraint
+ * definitions, extracts enum values, writes a deterministic JSON file at
+ * mcp-server/src/resources/schema-mirror.json.
+ *
+ * NOT run by CI — humans run this when they suspect or know that a CHECK
+ * constraint changed in production. The mirror is committed to git so PR
+ * diffs surface drift.
+ *
+ * Usage:
+ *   SUPABASE_DB_URL=postgres://... npx tsx mcp-server/scripts/refresh-schema-mirror.ts
+ *
+ * Optional dep: `pg` (added as devDependency on mcp-server).
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const MIRROR_PATH = join(
+  __dirname,
+  "..",
+  "src/resources/schema-mirror.json",
+);
+
+interface MirrorContent {
+  _generated_at: string;
+  _source: string;
+  _note: string;
+  [table: string]:
+    | string
+    | Record<string, string[]>;
+}
+
+const TABLES_TO_MIRROR: Array<{ table: string; columns: string[] }> = [
+  { table: "audio_files", columns: ["classification", "file_type"] },
+  { table: "recording_credits", columns: ["role"] },
+  { table: "recordings", columns: ["version_type"] },
+  {
+    table: "work_credits",
+    columns: ["attestation_status", "credit_type", "rights_type"],
+  },
+  { table: "works", columns: ["work_status", "work_type"] },
+];
+
+function fail(msg: string): never {
+  console.error(`[refresh-schema-mirror] ERROR: ${msg}`);
+  process.exit(1);
+}
+
+/**
+ * Parse a CHECK constraint definition string for ANY-of-array shapes.
+ * Postgres formats vary; common shapes:
+ *   CHECK ((work_type = ANY (ARRAY['song'::text, 'instrumental'::text, ...])))
+ *   CHECK ((work_type::text = ANY (ARRAY['song'::text, ...])))
+ *   CHECK (work_type IN ('song', 'instrumental', ...))
+ * Returns the literal values in source order; caller sorts for determinism.
+ */
+function parseEnumFromCheckDef(def: string): string[] | null {
+  // Match ARRAY[...] form
+  const arrayMatch = def.match(/ARRAY\[([^\]]+)\]/);
+  if (arrayMatch) {
+    const inside = arrayMatch[1];
+    const literals = [...inside.matchAll(/'([^']+)'/g)].map((m) => m[1]);
+    return literals.length > 0 ? literals : null;
+  }
+  // Match IN (...) form
+  const inMatch = def.match(/IN\s*\(([^)]+)\)/i);
+  if (inMatch) {
+    const inside = inMatch[1];
+    const literals = [...inside.matchAll(/'([^']+)'/g)].map((m) => m[1]);
+    return literals.length > 0 ? literals : null;
+  }
+  return null;
+}
+
+async function main(): Promise<void> {
+  const dbUrl = process.env.SUPABASE_DB_URL ?? process.env.DATABASE_URL;
+  if (!dbUrl) {
+    fail(
+      "SUPABASE_DB_URL (or DATABASE_URL) env var not set. Provide a Postgres connection string for staging or prod.",
+    );
+  }
+
+  // Lazy-import pg so the file type-checks even if pg isn't installed.
+  // Generator is the hot path; refresh is operator-only.
+  let Client: typeof import("pg").Client;
+  try {
+    ({ Client } = await import("pg"));
+  } catch {
+    fail(
+      "pg npm package not installed. Run: cd mcp-server && npm install --save-dev pg @types/pg",
+    );
+  }
+
+  const client = new Client({ connectionString: dbUrl });
+  await client.connect();
+
+  const out: Record<string, Record<string, string[]>> = {};
+
+  for (const { table, columns } of TABLES_TO_MIRROR) {
+    out[table] = {};
+    for (const col of columns) {
+      // Find a CHECK constraint on this column. Look for any constraint
+      // whose pg_get_constraintdef text references the column name and
+      // contains an ANY/IN enum list.
+      const result = await client.query<{ def: string }>(
+        `
+        SELECT pg_get_constraintdef(oid) AS def
+        FROM pg_constraint
+        WHERE conrelid = $1::regclass
+          AND contype = 'c'
+          AND pg_get_constraintdef(oid) ILIKE $2
+        `,
+        [`public.${table}`, `%${col}%`],
+      );
+
+      let values: string[] | null = null;
+      for (const row of result.rows) {
+        const parsed = parseEnumFromCheckDef(row.def);
+        if (parsed && parsed.length > 0) {
+          values = parsed;
+          break;
+        }
+      }
+      if (!values) {
+        console.warn(
+          `[refresh-schema-mirror] warn: no enum CHECK found for ${table}.${col}; leaving empty array`,
+        );
+        values = [];
+      }
+      out[table][col] = [...values].sort();
+    }
+  }
+
+  await client.end();
+
+  // Preserve metadata from existing mirror if present.
+  let existingNote =
+    "CHECK constraint enums for tables backing ADR-214 Phase 1 schemas. Refresh via `npx tsx mcp-server/scripts/refresh-schema-mirror.ts` against staging. Committed so PR diffs surface schema drift. See ADR-214 Decision section, Drift Prevention #3.";
+  try {
+    const prev = JSON.parse(
+      readFileSync(MIRROR_PATH, "utf-8"),
+    ) as MirrorContent;
+    if (typeof prev._note === "string") existingNote = prev._note;
+  } catch {
+    // first run — fine
+  }
+
+  const sortedTables = Object.keys(out).sort();
+  const sortedOut: Record<string, Record<string, string[]>> = {};
+  for (const t of sortedTables) {
+    const cols = Object.keys(out[t]).sort();
+    sortedOut[t] = {};
+    for (const c of cols) sortedOut[t][c] = out[t][c];
+  }
+
+  const final: MirrorContent = {
+    _generated_at: new Date().toISOString(),
+    _source: dbUrl.replace(/:[^:@]+@/, ":***@"),
+    _note: existingNote,
+    ...sortedOut,
+  };
+
+  writeFileSync(MIRROR_PATH, JSON.stringify(final, null, 2) + "\n", "utf-8");
+  console.log(
+    `[refresh-schema-mirror] wrote ${sortedTables.length} tables to ${MIRROR_PATH}`,
+  );
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/withpica/pica",
     "source": "github"
   },
-  "version": "2.35.0",
+  "version": "2.40.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@withpica/mcp-server",
-      "version": "2.35.0",
+      "version": "2.40.0",
       "transport": {
         "type": "stdio"
       }