supaschema 0.1.0-rc.1

package/benchmarks/tools/compare-report.mjs

@@ -0,0 +1,90 @@
+export function skippedResult(adapter, fixture, reason) {
+  return {
+    adapter: adapter.id,
+    fixture: fixture.name,
+    mode: adapter.mode,
+    outputFormat: adapter.output,
+    reason,
+    skipped: true,
+  };
+}
+
+export function unsupportedResult(adapter, fixture, reason) {
+  return {
+    adapter: adapter.id,
+    fixture: fixture.name,
+    mode: adapter.mode,
+    outputFormat: adapter.output,
+    reason,
+    skipped: false,
+    unsupported: true,
+  };
+}
+
+export function failedResult(adapter, fixture, warmup, iteration, error) {
+  const message = errorMessage(error);
+  return {
+    adapter: adapter.id,
+    appliesOnce: false,
+    appliesTwice: false,
+    attempts: 0,
+    commandFailed: true,
+    elapsedMs: 0,
+    exitCode: 1,
+    fixture: fixture.name,
+    matchesTargetAfterFirstApply: false,
+    matchesTargetAfterSecondApply: false,
+    matchesTargetFingerprint: false,
+    mode: adapter.mode,
+    outputBytes: 0,
+    outputFormat: adapter.output,
+    skipped: false,
+    stderrBytes: Buffer.byteLength(message),
+    stderrPreview: preview(redactSecrets(message)),
+    timedOut: false,
+    totalElapsedMs: 0,
+    verificationReason: message,
+    warmup,
+    iteration,
+  };
+}
+
+export function combineExecutions(executions) {
+  const latest = executions.at(-1) ?? {
+    exitCode: 1,
+    stderr: "command was not executed",
+    stdout: "",
+    timedOut: false,
+  };
+  return {
+    ...latest,
+    stderr: executions
+      .map((item, index) =>
+        index === 0 ? item.stderr : `--- retry ${index + 1} ---\n${item.stderr}`,
+      )
+      .filter(Boolean)
+      .join("\n"),
+    timedOut: executions.some((item) => item.timedOut),
+  };
+}
+
+export function preview(value) {
+  const trimmed = value.trim();
+  return trimmed ? trimmed.slice(0, 500) : undefined;
+}
+
+export function redactSecrets(value) {
+  return value.replace(/([a-z][a-z0-9+.-]*:\/\/)([^:@/\s]+):([^@/\s]+)@/gi, "$1***:***@");
+}
+
+export function summary(payload) {
+  const runnable = payload.results.filter((item) => !item.skipped && !item.unsupported);
+  const skipped = payload.results.filter((item) => item.skipped);
+  const unsupported = payload.results.filter((item) => item.unsupported);
+  const failed = runnable.filter((item) => item.commandFailed ?? item.exitCode !== 0);
+  return `comparison benchmark: ${runnable.length} runs, ${unsupported.length} unsupported, ${skipped.length} skips, ${failed.length} command failures`;
+}
+
+export function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}

package/benchmarks/tools/compare-supabase.mjs

@@ -0,0 +1,67 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { createServer } from "node:net";
+import { join } from "node:path";
+
+let portCursor = Number(process.env.SUPASCHEMA_COMPARE_PORT_BASE ?? 55_400);
+
+export async function prepareSupabaseWorkdir(context, adapter, iteration) {
+  if (!adapter.id.startsWith("supabase-")) {
+    return;
+  }
+  const [dbPort, shadowPort] = await availablePortPair();
+  const supabaseDirectory = join(context.runRoot, "supabase");
+  const projectId = stableProjectId(context.fixture.name, adapter.id, iteration);
+  await mkdir(supabaseDirectory, { recursive: true });
+  await writeFile(
+    join(supabaseDirectory, "config.toml"),
+    `project_id = "${projectId}"
+
+[db]
+port = ${dbPort}
+shadow_port = ${shadowPort}
+major_version = 17
+`,
+    "utf8",
+  );
+  context.supabaseConfig = {
+    dbPort,
+    projectId,
+    shadowPort,
+  };
+}
+
+async function availablePortPair() {
+  const first = await availablePort(portCursor);
+  const second = await availablePort(first + 1);
+  portCursor = second + 1;
+  return [first, second];
+}
+
+async function availablePort(start) {
+  for (let port = start; port < 65_535; port += 1) {
+    if (await isPortAvailable(port)) {
+      return port;
+    }
+  }
+  throw new Error(`could not find an available local port from ${start}`);
+}
+
+function isPortAvailable(port) {
+  return new Promise((resolvePort) => {
+    const server = createServer();
+    server.unref();
+    server.on("error", () => resolvePort(false));
+    server.listen({ host: "127.0.0.1", port }, () => {
+      server.close(() => resolvePort(true));
+    });
+  });
+}
+
+function stableProjectId(fixtureName, adapterId, iteration) {
+  const source = `${fixtureName}:${adapterId}:${iteration}:${process.pid}`;
+  let hash = 0;
+  for (const character of source) {
+    hash = (hash * 31 + character.charCodeAt(0)) >>> 0;
+  }
+  return `supaschema-${hash.toString(36)}`;
+}

package/benchmarks/tools/registry.js

@@ -0,0 +1,266 @@
+import { access, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const root = resolve(here, "../..");
+const localSupabaseBinary = resolve(root, "node_modules/.bin/supabase");
+
+export const adapters = [
+  {
+    binary: process.execPath,
+    id: "supaschema-file",
+    mode: "source-file diff",
+    output: "sql",
+    requiresDatabase: false,
+    async command(context) {
+      return {
+        args: [
+          resolve(root, "dist/cli.js"),
+          ...(context.supaschemaConfigPath ? ["--config", context.supaschemaConfigPath] : []),
+          "--quiet",
+          "diff",
+          "--from",
+          `dump:${context.fromSqlPath}`,
+          "--to",
+          `dump:${context.toSqlPath}`,
+          "--out",
+          "stdout",
+        ],
+        command: process.execPath,
+      };
+    },
+  },
+  {
+    binary: process.execPath,
+    id: "supaschema-db",
+    mode: "live-catalog diff",
+    output: "sql",
+    requiresDatabase: true,
+    async command(context) {
+      return {
+        args: [
+          resolve(root, "dist/cli.js"),
+          ...(context.supaschemaConfigPath ? ["--config", context.supaschemaConfigPath] : []),
+          "--quiet",
+          "diff",
+          "--from",
+          `database:${context.fromDatabaseUrl}`,
+          "--to",
+          `database:${context.toDatabaseUrl}`,
+          "--out",
+          "stdout",
+        ],
+        command: process.execPath,
+      };
+    },
+  },
+  {
+    binary: process.execPath,
+    id: "supaschema-workflow",
+    mode: "full workflow: diff + migration + TS types + Zod validators",
+    output: "sql",
+    requiresDatabase: false,
+    async command(context) {
+      const typesFile = join(context.runRoot, "database.types.ts");
+      const zodFile = join(context.runRoot, "database.zod.ts");
+      await writeFile(typesFile, "", "utf8");
+      await writeFile(zodFile, "", "utf8");
+      const configPath = join(context.runRoot, "supaschema.workflow.config.json");
+      await writeFile(
+        configPath,
+        `${JSON.stringify({
+          ...(context.supaschemaAdapter ? { adapter: context.supaschemaAdapter } : {}),
+          typesFile,
+          zodFile,
+        })}\n`,
+        "utf8",
+      );
+      const spec = {
+        diff: {
+          args: [
+            resolve(root, "dist/cli.js"),
+            "--config",
+            configPath,
+            "--quiet",
+            "diff",
+            "--from",
+            `dump:${context.fromSqlPath}`,
+            "--to",
+            `dump:${context.toSqlPath}`,
+            "--out",
+            context.outputPath,
+          ],
+          command: process.execPath,
+        },
+        migrationPath: context.outputPath,
+      };
+      const specPath = join(context.runRoot, "workflow.json");
+      await writeFile(specPath, `${JSON.stringify(spec)}\n`, "utf8");
+      return {
+        args: [resolve(here, "run-workflow.mjs"), specPath],
+        command: process.execPath,
+      };
+    },
+  },
+  supabaseAdapter("supabase-default"),
+  supabaseAdapter("supabase-migra", "--use-migra"),
+  supabaseAdapter("supabase-pg-delta", "--use-pg-delta"),
+  supabaseAdapter("supabase-pg-schema", "--use-pg-schema"),
+  supabaseAdapter("supabase-pgadmin", "--use-pgadmin"),
+  supabaseWorkflowAdapter("supabase-default-workflow"),
+  supabaseWorkflowAdapter("supabase-migra-workflow", "--use-migra"),
+  supabaseWorkflowAdapter("supabase-pg-delta-workflow", "--use-pg-delta"),
+  supabaseWorkflowAdapter("supabase-pg-schema-workflow", "--use-pg-schema"),
+  supabaseWorkflowAdapter("supabase-pgadmin-workflow", "--use-pgadmin"),
+];
+
+export async function adapterAvailability(adapter) {
+  const binary = adapter.resolveBinary ? await adapter.resolveBinary() : adapter.binary;
+  if (binary === process.execPath) {
+    return { available: true };
+  }
+  if (binary.includes("/")) {
+    try {
+      await access(binary);
+      return { available: true };
+    } catch {
+      return { available: false, reason: `binary "${binary}" was not found` };
+    }
+  }
+  const found = await findOnPath(binary);
+  if (found) {
+    return { available: true };
+  }
+  return { available: false, reason: `binary "${binary}" was not found on PATH` };
+}
+
+async function findOnPath(binary) {
+  const path = process.env.PATH ?? "";
+  for (const segment of path.split(":")) {
+    if (!segment) {
+      continue;
+    }
+    const candidate = resolve(segment, binary);
+    try {
+      await access(candidate);
+      return candidate;
+    } catch {
+      // Continue scanning PATH.
+    }
+  }
+  return undefined;
+}
+
+async function resolveSupabaseBinary() {
+  try {
+    await access(localSupabaseBinary);
+    return localSupabaseBinary;
+  } catch {
+    return "supabase";
+  }
+}
+
+function supabaseWorkflowAdapter(id, engineFlag) {
+  return {
+    binary: "supabase",
+    id,
+    maxAttempts: 3,
+    mode: "full workflow: db diff + apply + gen types",
+    output: "sql",
+    requiresDatabase: true,
+    resolveBinary: resolveSupabaseBinary,
+    retryDelayMs: 2_000,
+    retryOnFailure(execution) {
+      return (
+        execution.stderr.includes("Address already in use") &&
+        !execution.stderr.includes("workflow: applying migration")
+      );
+    },
+    async command(context) {
+      const supabaseBinary = await resolveSupabaseBinary();
+      const schemas = context.schemas ?? ["app"];
+      const diffArgs = [
+        "--workdir",
+        context.runRoot,
+        "db",
+        "diff",
+        "--from",
+        context.fromDatabaseUrl,
+        "--to",
+        context.toDatabaseUrl,
+        "--schema",
+        schemas.join(","),
+        "--output",
+        context.outputPath,
+      ];
+      if (engineFlag) {
+        diffArgs.push(engineFlag);
+      }
+      const spec = {
+        applyDatabaseUrl: context.fromDatabaseUrl,
+        diff: { args: diffArgs, command: supabaseBinary },
+        genTypes: {
+          args: [
+            "--workdir",
+            context.runRoot,
+            "gen",
+            "types",
+            "--lang=typescript",
+            "--db-url",
+            context.fromDatabaseUrl,
+            ...schemas.flatMap((schema) => ["--schema", schema]),
+          ],
+          command: supabaseBinary,
+          outPath: join(context.runRoot, "database.types.ts"),
+        },
+        migrationPath: context.outputPath,
+      };
+      const specPath = join(context.runRoot, "workflow.json");
+      await writeFile(specPath, `${JSON.stringify(spec)}\n`, "utf8");
+      return {
+        args: [resolve(here, "run-workflow.mjs"), specPath],
+        command: process.execPath,
+      };
+    },
+  };
+}
+
+function supabaseAdapter(id, engineFlag) {
+  return {
+    binary: "supabase",
+    id,
+    maxAttempts: 3,
+    mode: engineFlag ? `Supabase db diff ${engineFlag}` : "Supabase db diff default",
+    output: "sql",
+    requiresDatabase: true,
+    resolveBinary: resolveSupabaseBinary,
+    retryDelayMs: 2_000,
+    retryOnFailure(execution) {
+      return execution.stderr.includes("Address already in use");
+    },
+    async command(context) {
+      const args = [
+        "--workdir",
+        context.runRoot,
+        "db",
+        "diff",
+        "--from",
+        context.fromDatabaseUrl,
+        "--to",
+        context.toDatabaseUrl,
+        "--schema",
+        (context.schemas ?? ["app"]).join(","),
+        "--output",
+        context.outputPath,
+      ];
+      if (engineFlag) {
+        args.push(engineFlag);
+      }
+      return {
+        args,
+        command: await resolveSupabaseBinary(),
+      };
+    },
+  };
+}

package/benchmarks/tools/run-workflow.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { readFile, writeFile } from "node:fs/promises";
+import { applyMigrationSql } from "./compare-db.mjs";
+
+const specPath = process.argv[2];
+if (!specPath) {
+  process.stderr.write("usage: run-workflow.mjs <workflow-spec.json>\n");
+  process.exit(64);
+}
+const spec = JSON.parse(await readFile(specPath, "utf8"));
+
+const diff = await run(spec.diff);
+if (diff.exitCode !== 0) {
+  process.stderr.write(`workflow diff failed (exit ${diff.exitCode})\n`);
+  process.exit(diff.exitCode || 1);
+}
+
+if (spec.applyDatabaseUrl) {
+  const migrationSql = await readFile(spec.migrationPath, "utf8");
+  if (migrationSql.trim()) {
+    process.stderr.write("workflow: applying migration\n");
+    await applyMigrationSql(spec.applyDatabaseUrl, migrationSql);
+  }
+}
+
+if (spec.genTypes) {
+  const genTypes = await run(spec.genTypes);
+  if (genTypes.exitCode !== 0) {
+    process.stderr.write(`workflow gen types failed (exit ${genTypes.exitCode})\n`);
+    process.exit(genTypes.exitCode || 1);
+  }
+  await writeFile(spec.genTypes.outPath, genTypes.stdout, "utf8");
+}
+
+function run(step) {
+  return new Promise((resolveRun, rejectRun) => {
+    const child = spawn(step.command, step.args, {
+      detached: process.platform !== "win32",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    const killChild = (signal) => {
+      if (process.platform !== "win32" && child.pid) {
+        try {
+          process.kill(-child.pid, signal);
+          return;
+        } catch {
+          child.kill(signal);
+          return;
+        }
+      }
+      child.kill(signal);
+    };
+    const onTerm = () => killChild("SIGTERM");
+    const onInt = () => killChild("SIGINT");
+    process.on("SIGTERM", onTerm);
+    process.on("SIGINT", onInt);
+    let stdout = "";
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.setEncoding("utf8");
+    child.stderr.on("data", (chunk) => {
+      process.stderr.write(chunk);
+    });
+    const finish = (handler) => (value) => {
+      process.removeListener("SIGTERM", onTerm);
+      process.removeListener("SIGINT", onInt);
+      handler(value);
+    };
+    child.on("error", finish(rejectRun));
+    child.on("close", (exitCode) => {
+      finish(resolveRun)({ exitCode: exitCode ?? 1, stdout });
+    });
+  });
+}

package/bin/postinstall.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+// Install-time notice only: point the consumer at `supaschema init` rather
+// than writing into their project. A package postinstall that writes files
+// is flagged by supply-chain scanners, so scaffolding stays an explicit
+// step. Never prints inside supaschema's own checkout; never fails install.
+import { existsSync } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const target = resolve(process.env.INIT_CWD ?? process.cwd());
+
+try {
+  if (target === packageRoot || target.startsWith(packageRoot + sep)) {
+    process.exit(0);
+  }
+  const existing = ["supaschema.config.json", "supaschema.config.mjs", "supaschema.config.js"];
+  if (existing.some((name) => existsSync(join(target, name)))) {
+    process.exit(0);
+  }
+  process.stdout.write(
+    "supaschema: run `npx supaschema init` to scaffold supaschema.config.json\n",
+  );
+} catch {
+  process.exit(0);
+}

package/bin/supaschema

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/cli.js";