@supatype/cli 0.1.0-alpha.6 → 0.1.0-alpha.7

package/src/postgres-ctl.ts

@@ -0,0 +1,171 @@
+/**
+ * postgres-ctl — wrappers around pg_ctl, initdb, and pg_isready for managing
+ * a native Postgres installation.
+ */
+
+import { spawnSync } from "node:child_process"
+import { existsSync, mkdirSync } from "node:fs"
+import { dirname, join } from "node:path"
+
+export interface PgOptions {
+  /** Absolute path to the directory containing pg_ctl, initdb, psql, etc. */
+  pgBinDir: string
+  /** Absolute path to the Postgres data directory (PGDATA). */
+  dataDir: string
+  /** Port Postgres should listen on. */
+  port: number
+  /** Path to write the postgres log file. */
+  logPath?: string
+}
+
+/**
+ * Native Postgres bundles are built with prefix /usr/local/supatype-pg; dyld/ld
+ * must load libpq and friends from the extracted lib/ next to bin/.
+ */
+export function pgSpawnEnv(
+  pgBinDir: string,
+  platform: NodeJS.Platform = process.platform,
+): NodeJS.ProcessEnv {
+  const libDir = join(dirname(pgBinDir), "lib")
+  const env = { ...process.env } as NodeJS.ProcessEnv
+  if (platform === "darwin") {
+    const prev = env.DYLD_LIBRARY_PATH ?? ""
+    env.DYLD_LIBRARY_PATH = prev ? `${libDir}:${prev}` : libDir
+  } else if (platform === "linux") {
+    const prev = env.LD_LIBRARY_PATH ?? ""
+    env.LD_LIBRARY_PATH = prev ? `${libDir}:${prev}` : libDir
+  }
+  return env
+}
+
+// ---------------------------------------------------------------------------
+// initdb
+// ---------------------------------------------------------------------------
+
+/**
+ * Initialise a Postgres data directory.
+ * Does nothing if the data directory already contains a PG_VERSION file.
+ */
+export function initdb(opts: PgOptions): void {
+  const pgVersionFile = join(opts.dataDir, "PG_VERSION")
+  if (existsSync(pgVersionFile)) return // Already initialised.
+
+  mkdirSync(opts.dataDir, { recursive: true })
+
+  const bin = pgBin(opts.pgBinDir, "initdb")
+  const result = spawnSync(bin, ["-D", opts.dataDir, "--username", "postgres", "--auth", "trust"], {
+    stdio: "inherit",
+    encoding: "utf8",
+    env: pgSpawnEnv(opts.pgBinDir),
+  })
+
+  if (result.status !== 0) {
+    throw new Error(`initdb failed (exit ${result.status})`)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// start / stop
+// ---------------------------------------------------------------------------
+
+/**
+ * Start Postgres using pg_ctl.
+ * Returns immediately once pg_ctl has handed off to the server process.
+ */
+export function start(opts: PgOptions): void {
+  const bin = pgBin(opts.pgBinDir, "pg_ctl")
+  const logPath = opts.logPath ?? join(opts.dataDir, "postgres.log")
+
+  const args = [
+    "start",
+    "-D", opts.dataDir,
+    "-l", logPath,
+    "-o", `-p ${opts.port}`,
+    "--wait",
+  ]
+
+  const result = spawnSync(bin, args, {
+    stdio: "inherit",
+    encoding: "utf8",
+    env: pgSpawnEnv(opts.pgBinDir),
+  })
+  if (result.status !== 0) {
+    throw new Error(`pg_ctl start failed (exit ${result.status})`)
+  }
+}
+
+/**
+ * Stop Postgres using pg_ctl (fast mode).
+ */
+export function stop(opts: PgOptions): void {
+  const bin = pgBin(opts.pgBinDir, "pg_ctl")
+  const result = spawnSync(bin, ["stop", "-D", opts.dataDir, "-m", "fast", "--wait"], {
+    stdio: "inherit",
+    encoding: "utf8",
+    env: pgSpawnEnv(opts.pgBinDir),
+  })
+  // Ignore exit code — Postgres may already be stopped.
+  void result
+}
+
+// ---------------------------------------------------------------------------
+// waitReady
+// ---------------------------------------------------------------------------
+
+/**
+ * Wait until Postgres is accepting connections.
+ * Polls pg_isready every 200ms up to timeoutMs.
+ * Throws if the timeout is exceeded.
+ */
+export async function waitReady(opts: PgOptions, timeoutMs = 10_000): Promise<void> {
+  const bin = pgBin(opts.pgBinDir, "pg_isready")
+  const deadline = Date.now() + timeoutMs
+
+  while (Date.now() < deadline) {
+    const result = spawnSync(bin, ["-p", String(opts.port), "-q"], {
+      encoding: "utf8",
+      env: pgSpawnEnv(opts.pgBinDir),
+    })
+    if (result.status === 0) return
+
+    await sleep(200)
+  }
+
+  throw new Error(
+    `Postgres did not become ready within ${timeoutMs}ms on port ${opts.port}`,
+  )
+}
+
+// ---------------------------------------------------------------------------
+// Port check
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns true if a TCP listener is already bound to port on 127.0.0.1.
+ */
+export async function isPortInUse(port: number): Promise<boolean> {
+  const { createServer } = await import("node:net")
+  return new Promise((resolve) => {
+    const server = createServer()
+    server.once("error", (err: NodeJS.ErrnoException) => {
+      resolve(err.code === "EADDRINUSE")
+    })
+    server.once("listening", () => {
+      server.close(() => resolve(false))
+    })
+    server.listen(port, "127.0.0.1")
+  })
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+/** Returns the full path to a Postgres binary, appending .exe on Windows. */
+function pgBin(binDir: string, name: string): string {
+  return join(binDir, process.platform === "win32" ? `${name}.exe` : name)
+}

package/src/process-manager.ts

@@ -0,0 +1,151 @@
+/**
+ * ProcessManager — spawn a child process, write its PID, stream logs with a
+ * colored prefix, and restart on crash with exponential backoff.
+ */
+
+import { type ChildProcess, spawn } from "node:child_process"
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { unlink } from "node:fs/promises"
+import { join } from "node:path"
+
+export interface ProcessOptions {
+  /** Human-readable label (used in log prefix and PID filename). */
+  label: string
+  /** Directory to write {label}.pid to. */
+  pidDir: string
+  /** ANSI colour prefix string (e.g. "\x1b[36m"). Pass "" for no colour. */
+  colour?: string
+  /** Working directory for the spawned process. Defaults to process.cwd(). */
+  cwd?: string
+  /** Environment variables to merge with process.env. */
+  env?: Record<string, string>
+  /** Initial restart backoff in ms. Doubles each crash up to maxBackoffMs. */
+  initialBackoffMs?: number
+  /** Maximum restart backoff cap in ms. */
+  maxBackoffMs?: number
+  /** Called when the process exits cleanly (code 0). */
+  onExit?: () => void
+}
+
+const RESET = "\x1b[0m"
+
+export class ProcessManager {
+  private child: ChildProcess | null = null
+  private stopped = false
+  private backoffMs: number
+  private opts: Required<ProcessOptions>
+
+  constructor(
+    private readonly bin: string,
+    private readonly args: string[],
+    opts: ProcessOptions,
+  ) {
+    this.opts = {
+      colour: "\x1b[36m",
+      cwd: process.cwd(),
+      env: {},
+      initialBackoffMs: 1_000,
+      maxBackoffMs: 30_000,
+      onExit: () => {},
+      ...opts,
+    }
+    this.backoffMs = this.opts.initialBackoffMs
+  }
+
+  /** Start the process. Returns immediately — the process runs in the background. */
+  start(): void {
+    this.stopped = false
+    this.spawn()
+  }
+
+  /** Stop the process and clear the PID file. */
+  async stop(): Promise<void> {
+    this.stopped = true
+    if (this.child && !this.child.killed) {
+      this.child.kill("SIGTERM")
+      // Give it 5s to exit gracefully, then SIGKILL.
+      await new Promise<void>((resolve) => {
+        const timeout = setTimeout(() => {
+          this.child?.kill("SIGKILL")
+          resolve()
+        }, 5_000)
+        this.child!.once("exit", () => {
+          clearTimeout(timeout)
+          resolve()
+        })
+      })
+    }
+    await this.clearPid()
+  }
+
+  private spawn(): void {
+    if (this.stopped) return
+
+    const env = { ...process.env, ...this.opts.env } as NodeJS.ProcessEnv
+    this.child = spawn(this.bin, this.args, { env, cwd: this.opts.cwd, stdio: "pipe" })
+
+    const pid = this.child.pid
+    if (pid) this.writePid(pid)
+
+    const prefix = this.opts.colour
+      ? `${this.opts.colour}[${this.opts.label}]${RESET} `
+      : `[${this.opts.label}] `
+
+    this.child.stdout?.on("data", (chunk: Buffer) => {
+      for (const line of chunk.toString().split("\n")) {
+        if (line) process.stdout.write(prefix + line + "\n")
+      }
+    })
+
+    this.child.stderr?.on("data", (chunk: Buffer) => {
+      for (const line of chunk.toString().split("\n")) {
+        if (line) process.stderr.write(prefix + line + "\n")
+      }
+    })
+
+    this.child.once("exit", (code, signal) => {
+      if (this.stopped) return
+
+      if (code === 0) {
+        this.opts.onExit()
+        return
+      }
+
+      const reason = signal ? `signal ${signal}` : `code ${code}`
+      process.stderr.write(
+        `${prefix}process exited (${reason}), restarting in ${this.backoffMs}ms\n`,
+      )
+
+      setTimeout(() => {
+        this.backoffMs = Math.min(this.backoffMs * 2, this.opts.maxBackoffMs)
+        this.spawn()
+      }, this.backoffMs)
+    })
+  }
+
+  private writePid(pid: number): void {
+    try {
+      mkdirSync(this.opts.pidDir, { recursive: true })
+      writeFileSync(join(this.opts.pidDir, `${this.opts.label}.pid`), String(pid))
+    } catch {
+      // Non-fatal — PID tracking is best-effort.
+    }
+  }
+
+  private async clearPid(): Promise<void> {
+    try {
+      await unlink(join(this.opts.pidDir, `${this.opts.label}.pid`))
+    } catch {
+      // Ignore — file may already be gone.
+    }
+  }
+}
+
+/** Read a PID from a file (returns null if not found or stale). */
+export function readPid(pidDir: string, label: string): number | null {
+  const pidFile = join(pidDir, `${label}.pid`)
+  if (!existsSync(pidFile)) return null
+  const raw = readFileSync(pidFile, "utf8").trim()
+  const pid = Number(raw)
+  return Number.isFinite(pid) && pid > 0 ? pid : null
+}

package/src/project-config.ts

@@ -0,0 +1,353 @@
+import { existsSync } from "node:fs"
+import { resolve } from "node:path"
+import type { ComponentVersions } from "./components.js"
+
+// ---------------------------------------------------------------------------
+// Config schema (single canonical shape; loaded from supatype.config.ts)
+// ---------------------------------------------------------------------------
+
+export interface SupatypeProjectConfig {
+  supatype?: {
+    /**
+     * Base directory for Supatype project assets (schema, functions, etc).
+     * "." means the current working directory (default).
+     */
+    root?: string
+  }
+  project: {
+    /** Project name — used for per-project state dirs and logging. */
+    name: string
+    /** Cloud project reference (set by `supatype link`). */
+    ref?: string
+  }
+  database: {
+    /**
+     * Database backend.
+     * "native" = supatype manages a native Postgres binary (downloaded from CDN).
+     * "docker" = supatype runs supatype/postgres via Docker (includes all extensions).
+     */
+    provider: "native" | "docker"
+    /**
+     * Directory where Postgres stores its data files (provider=native).
+     * Defaults to ~/.supatype/projects/{name}/data when omitted.
+     */
+    data_dir?: string
+    /**
+     * Docker image to use (provider=docker).
+     * Defaults to supatype/postgres:17-latest.
+     * Override in supatype.local.config.ts for local builds.
+     */
+    image?: string
+  }
+  server: {
+    /**
+     * Server mode.
+     * "dev"        = no TLS, permissive CORS, Vite HMR proxy
+     * "standalone" = ACME TLS (Let's Encrypt)
+     * "managed"    = cloud-managed, HMAC tenant verification
+     */
+    mode: "dev" | "standalone" | "managed"
+    /** Port supatype-server listens on (default: 54321). */
+    port?: number
+    /** Port PostgREST listens on in local dev (default: 3001). */
+    postgrestPort?: number
+    /** Domain for ACME TLS certificate (mode=standalone). */
+    domain?: string
+  }
+  app: {
+    /**
+     * How the root path "/" is handled by supatype-server.
+     * "none"   = 404
+     * "static" = serve files from static_dir
+     * "proxy"  = reverse-proxy to upstream
+     */
+    mode: "none" | "static" | "proxy"
+    /** Directory to serve static files from (mode=static). */
+    static_dir?: string
+    /** Upstream URL to proxy to (mode=proxy). */
+    upstream?: string
+    /**
+     * Vite dev server base URL for HMR (`/_vite/*`) when `server.mode` is dev.
+     * Example: `http://127.0.0.1:5173`. Sets `SUPATYPE_VITE_DEV_URL` for supatype-server.
+     * When omitted, dev still falls back to `SUPATYPE_APP_UPSTREAM` for non-proxy app modes.
+     */
+    vite_dev_url?: string
+  }
+  /**
+   * Pinned binary versions per component. Use **`"local"`** with the matching **`overrides.*`**
+   * entry when testing a local build (Phase 10.7).
+   */
+  versions: ComponentVersions
+  /**
+   * Override component binaries with local build paths.
+   * Intended for supatype contributors testing local changes.
+   * Cannot be combined with a linked cloud project (`project.ref`, `.supatype/cloud.json`, or `.supatype/linked.json`; hard error in `resolveBinary`).
+   */
+  overrides?: {
+    /** Path to local engine binary. */
+    engine?: string
+    /** Path to local supatype-server binary. */
+    server?: string
+    /** Path to a directory containing a local Postgres installation. */
+    postgres_dir?: string
+    /** Path to a local deno binary. */
+    deno?: string
+    /** Path to the @supatype/studio package directory (starts Vite dev server). */
+    studio?: string
+    /** Path to a local PostgREST binary. */
+    postgrest?: string
+  }
+  email?: {
+    /**
+     * Email delivery provider.
+     * "console" = log to stdout (default for dev)
+     * "smtp"    = SMTP (set `smtp` below and/or GOTRUE_SMTP_* in `.env`)
+     * "resend"  = Resend API (requires RESEND_API_KEY, RESEND_FROM)
+     * "ses"     = AWS SES v2 (ambient credentials, requires SES_FROM)
+     */
+    provider: "console" | "smtp" | "resend" | "ses"
+    /**
+     * SMTP settings for provider=smtp (merged into process env as GOTRUE_SMTP_*).
+     * Omitted keys can still be set via `.env` / shell.
+     */
+    smtp?: {
+      host?: string
+      port?: number
+      user?: string
+      pass?: string
+      admin_email?: string
+      sender_name?: string
+    }
+    /** Resend API key (provider=resend, or set RESEND_API_KEY env var). */
+    resend_api_key?: string
+    /** From address for Resend (provider=resend, or set RESEND_FROM env var). */
+    resend_from?: string
+    /** From address for SES (provider=ses, or set SES_FROM env var). */
+    ses_from?: string
+    /**
+     * When true, `supatype dev` enables the GoTrue send-email HTTP hook pointing at this
+     * server's POST `/internal/v0hooks/send-email` (signed delivery, dev-only secret).
+     * Override `GOTRUE_HOOK_SEND_EMAIL_*` in `.env` if needed.
+     */
+    send_email_hook?: boolean
+    /**
+     * Override hook target URL when `send_email_hook` is true (e.g. HTTPS tunnel or Edge URL).
+     * Default: `http://127.0.0.1:<serverPort>/internal/v0hooks/send-email`.
+     */
+    send_email_hook_uri?: string
+    /**
+     * Standard Webhooks v1 secrets for the send-email hook (`v1,whsec_...`, pipe-separated for rotation).
+     * Default in dev: a fixed local secret; override for team-shared dev or CI.
+     */
+    send_email_hook_secrets?: string
+  }
+  storage?: {
+    /**
+     * Storage backend.
+     * "local" = files on disk (LocalStoragePath required)
+     * "s3"    = AWS S3 or compatible (ambient credentials)
+     */
+    provider: "local" | "s3"
+    /** Local directory to store objects in (provider=local). */
+    local_path?: string
+  }
+  schema?: {
+    /** Path (or glob) to the schema entry point. Defaults to "schema/index.ts". */
+    path?: string
+    /** Postgres schema name. Defaults to "public". */
+    pg_schema?: string
+  }
+  functions?: {
+    /** Path to edge functions directory, relative to `supatype.root` when not absolute. */
+    path?: string
+  }
+  output?: {
+    /** Path for generated TypeScript types. */
+    types?: string
+    /** Path for generated client helpers. */
+    client?: string
+  }
+  /**
+   * App build configuration for `supatype deploy`.
+   * Separate from `app` which controls how supatype-server serves at runtime.
+   */
+  build?: {
+    /** Framework name. Auto-detected from package.json when omitted. */
+    framework?: "nextjs" | "astro" | "vite" | "remix-spa" | "sveltekit" | "nuxt" | "static"
+    /** Path to the app directory. Defaults to cwd. */
+    directory?: string
+    /** Build command. Inferred from framework when omitted. */
+    buildCommand?: string
+    /** Build output directory. Inferred from framework when omitted. */
+    outputDirectory?: string
+    /** Enable SPA fallback routing. */
+    spa?: boolean
+    /** Environment variables injected at build time. */
+    env?: Record<string, string>
+    /** Custom response headers for the deployed static site. */
+    headers?: Record<string, string>
+  }
+  /**
+   * Optional Postgres URL for CLI commands that talk to the DB (`push`, `migrate`, …).
+   * When omitted, `DATABASE_URL` from the environment is used, then a local default DSN.
+   */
+  connection?: string
+}
+
+// ---------------------------------------------------------------------------
+// Merge + validate
+// ---------------------------------------------------------------------------
+
+/**
+ * Merge each top-level section from `override` on top of `base`.
+ * Within each section, override values win. New optional sections in override are added.
+ */
+export function mergeProjectConfig(
+  base: SupatypeProjectConfig,
+  override: Partial<SupatypeProjectConfig>,
+): SupatypeProjectConfig {
+  return {
+    ...(base.supatype !== undefined || override.supatype !== undefined
+      ? { supatype: { ...base.supatype, ...override.supatype } as NonNullable<SupatypeProjectConfig["supatype"]> }
+      : {}),
+    project: { ...base.project, ...override.project },
+    database: { ...base.database, ...override.database },
+    server: { ...base.server, ...override.server },
+    app: { ...base.app, ...override.app },
+    versions: { ...base.versions, ...override.versions },
+    ...(base.overrides !== undefined || override.overrides !== undefined
+      ? {
+          overrides: {
+            ...base.overrides,
+            ...override.overrides,
+          } as NonNullable<SupatypeProjectConfig["overrides"]>,
+        }
+      : {}),
+    ...(base.email !== undefined || override.email !== undefined
+      ? (() => {
+          const b = base.email
+          const o = override.email
+          const mergedSmtp =
+            b?.smtp !== undefined || o?.smtp !== undefined
+              ? { ...(b?.smtp ?? {}), ...(o?.smtp ?? {}) }
+              : undefined
+          return {
+            email: {
+              ...b,
+              ...o,
+              ...(mergedSmtp !== undefined ? { smtp: mergedSmtp } : {}),
+            } as NonNullable<SupatypeProjectConfig["email"]>,
+          }
+        })()
+      : {}),
+    ...(base.storage !== undefined || override.storage !== undefined
+      ? {
+          storage: {
+            ...base.storage,
+            ...override.storage,
+          } as NonNullable<SupatypeProjectConfig["storage"]>,
+        }
+      : {}),
+    ...(base.schema !== undefined || override.schema !== undefined
+      ? { schema: { ...base.schema, ...override.schema } as NonNullable<SupatypeProjectConfig["schema"]> }
+      : {}),
+    ...(base.functions !== undefined || override.functions !== undefined
+      ? { functions: { ...base.functions, ...override.functions } as NonNullable<SupatypeProjectConfig["functions"]> }
+      : {}),
+    ...(base.output !== undefined || override.output !== undefined
+      ? { output: { ...base.output, ...override.output } as NonNullable<SupatypeProjectConfig["output"]> }
+      : {}),
+    ...(base.build !== undefined || override.build !== undefined
+      ? { build: { ...base.build, ...override.build } as NonNullable<SupatypeProjectConfig["build"]> }
+      : {}),
+    ...(base.connection !== undefined || override.connection !== undefined
+      ? { connection: override.connection ?? base.connection }
+      : {}),
+  }
+}
+
+export function validateProjectConfig(raw: unknown, filename: string): SupatypeProjectConfig {
+  if (typeof raw !== "object" || raw === null) {
+    throw new Error(`${filename}: expected a config object at the root`)
+  }
+
+  const cfg = raw as Record<string, unknown>
+
+  if (!cfg["project"] || typeof (cfg["project"] as Record<string, unknown>)["name"] !== "string") {
+    throw new Error(`${filename}: project.name is required`)
+  }
+  if (!cfg["database"]) {
+    throw new Error(`${filename}: database section is required`)
+  }
+  if (!cfg["server"]) {
+    throw new Error(`${filename}: server section is required`)
+  }
+  if (!cfg["app"]) {
+    throw new Error(`${filename}: app section is required`)
+  }
+  if (!cfg["versions"]) {
+    throw new Error(`${filename}: versions section is required`)
+  }
+
+  return raw as SupatypeProjectConfig
+}
+
+/** Schema entry path (with fallback). */
+export function schemaPathFromProject(cfg: SupatypeProjectConfig, cwd: string): string {
+  return resolve(projectRootFromConfig(cfg, cwd), cfg.schema?.path ?? "schema/index.ts")
+}
+
+/** Resolve project root for schema/functions defaults. */
+export function projectRootFromConfig(cfg: SupatypeProjectConfig, cwd: string): string {
+  return resolve(cwd, cfg.supatype?.root ?? ".")
+}
+
+/** Candidate functions directories in lookup order. */
+export function functionsPathCandidatesFromProject(cfg: SupatypeProjectConfig, cwd: string): string[] {
+  const root = projectRootFromConfig(cfg, cwd)
+  if (cfg.functions?.path) {
+    return [resolve(root, cfg.functions.path)]
+  }
+  // Prefer modern default, but keep legacy fallback for compatibility.
+  return [resolve(root, "functions"), resolve(root, "supatype/functions")]
+}
+
+/** Preferred default functions path (used when creating new functions). */
+export function preferredFunctionsPathFromProject(cfg: SupatypeProjectConfig, cwd: string): string {
+  const candidates = functionsPathCandidatesFromProject(cfg, cwd)
+  for (const dir of candidates) {
+    if (existsSync(dir)) return dir
+  }
+  return candidates[0] ?? resolve(projectRootFromConfig(cfg, cwd), "functions")
+}
+
+/**
+ * Derive the supatype-server base URL from the project config.
+ * Returns undefined if the mode is "managed" (cloud controls the URL).
+ */
+export function serverBaseUrl(cfg: SupatypeProjectConfig): string | undefined {
+  const port = cfg.server.port ?? 54321
+  switch (cfg.server.mode) {
+    case "dev":
+    case "standalone":
+      return cfg.server.domain
+        ? `https://${cfg.server.domain}`
+        : `http://localhost:${port}`
+    case "managed":
+      return undefined
+  }
+}
+
+/** The local Postgres DSN derived from project name (dev default). */
+export function localDSN(cfg: SupatypeProjectConfig): string {
+  const port = 5432 // standard; per-project state dir isolates data dirs
+  return `postgres://postgres:postgres@127.0.0.1:${port}/${cfg.project.name}?sslmode=disable`
+}
+
+/**
+ * Resolve the database connection string.
+ * Prefers optional `connection` in config, then `DATABASE_URL` env, then a local default DSN.
+ */
+export function connectionString(cfg: SupatypeProjectConfig): string {
+  return cfg.connection ?? process.env["DATABASE_URL"] ?? localDSN(cfg)
+}

package/src/pull-utils.ts

@@ -11,6 +11,30 @@ export interface ColumnInfo {
   hasDefault: boolean
 }
 
+/** Engine `/introspect` column shape (see {@link IntrospectResult} in engine-client). */
+export interface IntrospectColumn {
+  name: string
+  type: string
+  nullable: boolean
+  default?: string
+  primaryKey?: boolean
+  unique?: boolean
+  references?: { table: string; column: string }
+}
+
+/** Map engine introspection JSON to {@link ColumnInfo} for {@link pgTypeToField}. */
+export function introspectColumnToColumnInfo(col: IntrospectColumn): ColumnInfo {
+  const def = col.default
+  return {
+    name: col.name,
+    pgType: col.type,
+    nullable: col.nullable,
+    isPrimary: col.primaryKey ?? false,
+    isUnique: col.unique ?? false,
+    hasDefault: def !== undefined && def !== "",
+  }
+}
+
 /** Map a Postgres column type to the corresponding field.X() call string. */
 export function pgTypeToField(col: ColumnInfo): string {
   const opts: Record<string, unknown> = { required: !col.nullable }