@supatype/cli 0.1.4 → 0.1.6

package/src/realtime-launch.ts

@@ -0,0 +1,52 @@
+import { existsSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import { ensureBinary } from "./ensure-binary.js"
+import type { SupatypeProjectConfig } from "./project-config.js"
+
+export interface RealtimeLaunchSpec {
+  bin: string
+  args: string[]
+}
+
+const CLI_PKG_DIR = dirname(fileURLToPath(import.meta.url))
+
+/** Monorepo contributor fallback: packages/realtime/dist/index.js relative to CLI package. */
+function monorepoRealtimeEntry(): string | null {
+  const candidate = resolve(CLI_PKG_DIR, "../../realtime/dist/index.js")
+  return existsSync(candidate) ? candidate : null
+}
+
+/**
+ * Resolve how to spawn supatype-realtime for native dev.
+ * Order: overrides.realtime → CDN binary → node + monorepo dist.
+ */
+export async function resolveRealtimeLaunch(
+  config: SupatypeProjectConfig,
+  cwd: string,
+): Promise<RealtimeLaunchSpec> {
+  const override = config.overrides?.realtime?.trim()
+  if (override) {
+    const resolved = resolve(cwd, override)
+    if (!existsSync(resolved)) {
+      throw new Error(`[overrides] realtime path does not exist: ${resolved}`)
+    }
+    if (resolved.endsWith(".js") || resolved.endsWith(".mjs") || resolved.endsWith(".cjs")) {
+      return { bin: process.execPath, args: [resolved] }
+    }
+    return { bin: resolved, args: [] }
+  }
+
+  try {
+    const bin = await ensureBinary("realtime", config)
+    return { bin, args: [] }
+  } catch {
+    const entry = monorepoRealtimeEntry()
+    if (entry) {
+      return { bin: process.execPath, args: [entry] }
+    }
+    throw new Error(
+      "realtime binary not available — run `supatype update` or set overrides.realtime in supatype.config.ts",
+    )
+  }
+}

package/src/required-host-components.ts

@@ -23,7 +23,7 @@ export function requiredHostComponents(
     return ["engine"]
   }
 
-  const components: Component[] = ["engine", "server", "postgres"]
+  const components: Component[] = ["engine", "server", "postgres", "realtime"]
   const hasFunctions = functionsPathCandidatesFromProject(config, cwd).some((dir) =>
     existsSync(dir),
   )

package/src/route-manifest.ts

@@ -0,0 +1,17 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs"
+
+/** Merge fields into `.supatype/manifest.json` (creates file if missing). */
+export function patchRouteManifest(
+  manifestPath: string,
+  patch: Record<string, unknown>,
+): void {
+  let manifest: Record<string, unknown> = {}
+  if (existsSync(manifestPath)) {
+    try {
+      manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as Record<string, unknown>
+    } catch {
+      manifest = {}
+    }
+  }
+  writeFileSync(manifestPath, `${JSON.stringify({ ...manifest, ...patch }, null, 2)}\n`, "utf8")
+}

package/src/schema-push-lock.ts

@@ -0,0 +1,131 @@
+/**
+ * Advisory lock held while compose schema push runs so realtime can skip WAL
+ * decoding without stopping the realtime process (self-host safe).
+ *
+ * Must stay in sync with:
+ *   - packages/realtime/src/schema-push-lock.ts
+ *   - supatype-schema-engine (pg_advisory_xact_lock on the same keys)
+ */
+
+import { existsSync } from "node:fs"
+import { resolve } from "node:path"
+import { spawn, spawnSync, type ChildProcess } from "node:child_process"
+import type { SelfHostComposePaths } from "./self-host-compose.js"
+import { readEnvValue } from "./env-file.js"
+
+export const SCHEMA_PUSH_LOCK_CLASSID = 872014
+export const SCHEMA_PUSH_LOCK_OBJID = 1
+
+function composeBaseArgs(
+  paths: SelfHostComposePaths,
+  cwd: string,
+  composeProject: string,
+): string[] {
+  const envFile = resolve(cwd, ".env")
+  const args = ["compose", "-p", composeProject, "--project-directory", cwd, "-f", paths.composePath]
+  if (existsSync(envFile)) args.push("--env-file", envFile)
+  return args
+}
+
+function dbExecArgs(
+  paths: SelfHostComposePaths,
+  cwd: string,
+  composeProject: string,
+  psqlArgs: string[],
+): string[] {
+  const pass = readEnvValue(cwd, "POSTGRES_PASSWORD", "postgres")
+  const user = readEnvValue(cwd, "POSTGRES_USER", "supatype_admin")
+  const db = readEnvValue(cwd, "POSTGRES_DB", "supatype")
+  return [
+    ...composeBaseArgs(paths, cwd, composeProject),
+    "exec",
+    "-T",
+    "-e",
+    `PGPASSWORD=${pass}`,
+    "db",
+    "psql",
+    "-U",
+    user,
+    "-d",
+    db,
+    "-v",
+    "ON_ERROR_STOP=1",
+    ...psqlArgs,
+  ]
+}
+
+function schemaPushLockIsHeld(
+  paths: SelfHostComposePaths,
+  cwd: string,
+  composeProject: string,
+): boolean {
+  const args = dbExecArgs(paths, cwd, composeProject, [
+    "-tAc",
+    `SELECT EXISTS (
+       SELECT 1 FROM pg_locks
+       WHERE locktype = 'advisory'
+         AND classid = ${SCHEMA_PUSH_LOCK_CLASSID}
+         AND objid = ${SCHEMA_PUSH_LOCK_OBJID}
+         AND granted
+     )`,
+  ])
+  const result = spawnSync("docker", args, { cwd, encoding: "utf8" })
+  return result.status === 0 && result.stdout.trim() === "t"
+}
+
+/**
+ * Hold a session advisory lock for the duration of `fn` via a background
+ * `psql` inside the compose db container. Killing the holder releases the lock.
+ */
+export async function withComposeSchemaPushLock<T>(
+  paths: SelfHostComposePaths,
+  cwd: string,
+  composeProject: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const holdSql =
+    `SELECT pg_advisory_lock(${SCHEMA_PUSH_LOCK_CLASSID}, ${SCHEMA_PUSH_LOCK_OBJID});` +
+    ` SELECT pg_sleep(86400);`
+  const args = dbExecArgs(paths, cwd, composeProject, ["-c", holdSql])
+
+  let stderrBuf = ""
+  const holder: ChildProcess = spawn("docker", args, {
+    cwd,
+    stdio: ["ignore", "pipe", "pipe"],
+  })
+  holder.stderr?.on("data", (chunk: Buffer) => {
+    stderrBuf += chunk.toString()
+  })
+
+  const deadline = Date.now() + 30_000
+  while (Date.now() < deadline) {
+    if (holder.exitCode !== null) {
+      const err = stderrBuf.trim() || "lock holder exited"
+      throw new Error(`[supatype] Failed to acquire schema-push advisory lock: ${err}`)
+    }
+    if (schemaPushLockIsHeld(paths, cwd, composeProject)) break
+    await new Promise((r) => setTimeout(r, 200))
+  }
+  if (!schemaPushLockIsHeld(paths, cwd, composeProject)) {
+    holder.kill("SIGTERM")
+    throw new Error("[supatype] Timed out waiting for schema-push advisory lock")
+  }
+
+  try {
+    return await fn()
+  } finally {
+    if (holder.exitCode === null) {
+      holder.kill("SIGTERM")
+      await new Promise<void>((resolveDone) => {
+        const t = setTimeout(() => {
+          holder.kill("SIGKILL")
+          resolveDone()
+        }, 3000)
+        holder.once("exit", () => {
+          clearTimeout(t)
+          resolveDone()
+        })
+      })
+    }
+  }
+}

package/src/self-host-compose.ts

@@ -383,6 +383,20 @@ ${dbPorts}    volumes:
       db:
         condition: service_healthy
 
+  realtime:
+    image: \${SUPATYPE_REALTIME_IMAGE:-supatype/realtime:latest}
+    expose:
+      - "4000"
+    environment:
+      PORT: "4000"
+      DATABASE_URL: "postgresql://\${POSTGRES_USER:-supatype_admin}:\${POSTGRES_PASSWORD:-postgres}@db:5432/\${POSTGRES_DB:-supatype}"
+      JWT_SECRET: \${JWT_SECRET:-super-secret-jwt-token-change-in-production}
+      SLOT_NAME: supatype_realtime
+      PUBLICATION_NAME: supatype_realtime_pub
+    depends_on:
+      db:
+        condition: service_healthy
+
   control-plane:
     image: \${SUPATYPE_CONTROL_PLANE_IMAGE:-supatype/control-plane:latest}
     expose:
@@ -423,6 +437,7 @@ ${serverPorts}    volumes:
       SUPATYPE_SQL_DATABASE_URL: "postgresql://\${POSTGRES_USER:-supatype_admin}:\${POSTGRES_PASSWORD:-postgres}@db:5432/\${POSTGRES_DB:-supatype}"
       SUPATYPE_DENO_FUNCTIONS_DIR: /project/functions
       SUPATYPE_FUNCTIONS_WORKER_URL: http://functions-worker:8001
+      SUPATYPE_REALTIME_URL: http://realtime:4000
       SUPATYPE_CONTROL_PLANE_URL: http://control-plane:8080
       SUPATYPE_VALKEY_ADDR: valkey:6379
 ${appEnv}
@@ -452,6 +467,8 @@ ${devLocal ? "      STUDIO_OPEN_DEV: \"1\"\n" : ""}
         condition: service_started
       functions-worker:
         condition: service_started
+      realtime:
+        condition: service_started
       control-plane:
         condition: service_started
 
@@ -502,6 +519,7 @@ function ensureComposeManifest(cwd: string): void {
     postgrest_url: "http://postgrest:3000",
     storage_url: "http://storage:5000",
     realtime_enabled: true,
+    realtime_url: "http://realtime:4000",
     functions_enabled: false,
   }
   writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8")

package/src/type-extractor.ts

@@ -22,6 +22,7 @@ import {
   type ExtractedSchemaAstV2,
   type ExtractedStorageBucketAst,
   type FieldAstV2,
+  type KernelFieldFacts,
   type ParsedField,
 } from "./schema-ast-v2.js"
 
@@ -410,6 +411,7 @@ function parseFieldType(
     fieldDefault: undefined as string | number | boolean | null | undefined,
     localized: false,
     notLocalized: false,
+    checkConstraint: undefined as string | undefined,
   }
 
   const resolving = new Set<string>()
@@ -481,11 +483,46 @@ function parseFieldType(
         current = valueArg ?? current
         continue
       }
-      case "MaxLength":
-      case "MinLength":
-      case "Between":
+      case "MaxLength": {
+        const max = parseNumericTypeArg(current.typeArguments?.[1], sourceFile)
+        if (max !== undefined) {
+          flags.checkConstraint = mergeCheckConstraint(
+            flags.checkConstraint,
+            `char_length("{name}") <= ${max}`,
+          )
+        }
+        current = current.typeArguments?.[0] ?? current
+        continue
+      }
+      case "MinLength": {
+        const min = parseNumericTypeArg(current.typeArguments?.[1], sourceFile)
+        if (min !== undefined) {
+          flags.checkConstraint = mergeCheckConstraint(
+            flags.checkConstraint,
+            `char_length("{name}") >= ${min}`,
+          )
+        }
+        current = current.typeArguments?.[0] ?? current
+        continue
+      }
+      case "Between": {
+        const min = parseNumericTypeArg(current.typeArguments?.[1], sourceFile)
+        const max = parseNumericTypeArg(current.typeArguments?.[2], sourceFile)
+        if (min !== undefined) {
+          flags.checkConstraint = mergeCheckConstraint(
+            flags.checkConstraint,
+            `"{name}"::numeric >= ${min}`,
+          )
+        }
+        if (max !== undefined) {
+          flags.checkConstraint = mergeCheckConstraint(
+            flags.checkConstraint,
+            `"{name}"::numeric <= ${max}`,
+          )
+        }
         current = current.typeArguments?.[0] ?? current
         continue
+      }
       case "Localized":
         flags.localized = true
         current = current.typeArguments?.[0] ?? current
@@ -494,36 +531,68 @@ function parseFieldType(
         flags.notLocalized = true
         current = current.typeArguments?.[0] ?? current
         continue
-      case "RelatedTo":
+      case "RelatedTo": {
         flags.relationCardinality = "one"
         flags.relationTarget = relationTargetFromTypeArg(current.typeArguments?.[0], sourceFile)
+        const relOpts = parseRelationOptions(current.typeArguments?.[1], sourceFile)
         // `target` must match `ModelAst.name` to satisfy validator resolution.
         // FK column follows the field name (two relations to the same model need distinct columns).
         return emitField({
           kind: "relation",
-          kernel: { cardinality: "belongsTo", target: flags.relationTarget! },
+          kernel: {
+            cardinality: "belongsTo",
+            target: flags.relationTarget!,
+            ...relationOptionsKernel(relOpts),
+          },
           db: { foreignKey: relationForeignKeyFromField(fieldName) },
           platform: flags.editorReadOnly ? { readOnly: true } : {},
         })
-      case "HasOne":
+      }
+      case "HasOne": {
         flags.relationCardinality = "one"
-        flags.relationTarget = current.typeArguments?.[0]?.getText(sourceFile).replace(/\W/g, "") ?? "unknown"
+        flags.relationTarget = relationTargetFromTypeArg(current.typeArguments?.[0], sourceFile)
+        const relOpts = parseRelationOptions(current.typeArguments?.[1], sourceFile)
+        return emitField({
+          kind: "relation",
+          kernel: {
+            cardinality: "hasOne",
+            target: flags.relationTarget,
+            ...relationOptionsKernel(relOpts),
+          },
+          db: {},
+          platform: flags.editorReadOnly ? { readOnly: true } : {},
+        })
+      }
+      case "HasMany": {
+        flags.relationCardinality = "many"
+        flags.relationTarget = relationTargetFromTypeArg(current.typeArguments?.[0], sourceFile)
+        const relOpts = parseRelationOptions(current.typeArguments?.[1], sourceFile)
         return emitField({
           kind: "relation",
-          kernel: { cardinality: "hasOne", target: flags.relationTarget },
+          kernel: {
+            cardinality: "hasMany",
+            target: flags.relationTarget,
+            ...relationOptionsKernel(relOpts),
+          },
           db: {},
           platform: flags.editorReadOnly ? { readOnly: true } : {},
         })
-      case "HasMany":
-      case "ManyToMany":
+      }
+      case "ManyToMany": {
         flags.relationCardinality = "many"
-        flags.relationTarget = current.typeArguments?.[0]?.getText(sourceFile).replace(/\W/g, "") ?? "unknown"
+        flags.relationTarget = relationTargetFromTypeArg(current.typeArguments?.[0], sourceFile)
+        const relOpts = parseRelationOptions(current.typeArguments?.[1], sourceFile)
         return emitField({
           kind: "relation",
-          kernel: { cardinality: "hasMany", target: flags.relationTarget },
+          kernel: {
+            cardinality: "manyToMany",
+            target: flags.relationTarget,
+            ...relationOptionsKernel(relOpts),
+          },
           db: {},
           platform: flags.editorReadOnly ? { readOnly: true } : {},
         })
+      }
       default: {
         const resolved = tryResolveTypeReference(current, sourceFile, resolveCtx, { fieldName, resolving })
         if (resolved) {
@@ -642,6 +711,13 @@ function parseFieldType(
     parsed = { ...parsed, kernel }
   }
 
+  if (flags.checkConstraint !== undefined) {
+    parsed = {
+      ...parsed,
+      kernel: { ...parsed.kernel, check: flags.checkConstraint },
+    }
+  }
+
   return emitField(finalizeParsedField(parsed, flags, context))
 }
 
@@ -1534,7 +1610,7 @@ function parseModelIndexes(
   const indexes: unknown[] = []
   for (const element of indexesProp.type.elements) {
     if (!ts.isTypeLiteralNode(element)) continue
-    const indexDef: Record<string, unknown> = { using: "btree" }
+    const indexDef: Record<string, unknown> = { using: "btree", unique: false }
     for (const member of element.members) {
       if (!ts.isPropertySignature(member) || !member.type) continue
       const key = getPropertyName(member.name)
@@ -1628,6 +1704,73 @@ function parseAccessRule(typeNode: ts.TypeNode, sourceFile: ts.SourceFile): Reco
   }
 }
 
+interface ParsedRelationOptions {
+  required?: boolean
+  onDelete?: string
+  onUpdate?: string
+  through?: string
+}
+
+function parseRelationOptions(
+  optsArg: ts.TypeNode | undefined,
+  sourceFile: ts.SourceFile,
+): ParsedRelationOptions {
+  const out: ParsedRelationOptions = {}
+  if (!optsArg || !ts.isTypeLiteralNode(optsArg)) return out
+
+  for (const member of optsArg.members) {
+    if (!ts.isPropertySignature(member) || !member.name || !member.type) continue
+    const key = getPropertyName(member.name)
+    if (!key) continue
+
+    if (key === "required" && isBooleanLiteralType(member.type, true)) {
+      out.required = true
+      continue
+    }
+
+    if (
+      (key === "onDelete" || key === "onUpdate" || key === "through") &&
+      ts.isLiteralTypeNode(member.type) &&
+      ts.isStringLiteral(member.type.literal)
+    ) {
+      out[key] = member.type.literal.text
+    }
+  }
+
+  return out
+}
+
+function relationOptionsKernel(
+  opts: ParsedRelationOptions,
+): Pick<KernelFieldFacts, "required" | "onDelete" | "onUpdate" | "through"> {
+  return {
+    ...(opts.required === true && { required: true }),
+    ...(opts.onDelete !== undefined && { onDelete: opts.onDelete }),
+    ...(opts.onUpdate !== undefined && { onUpdate: opts.onUpdate }),
+    ...(opts.through !== undefined && { through: opts.through }),
+  }
+}
+
+function parseNumericTypeArg(typeArg: ts.TypeNode | undefined, sourceFile: ts.SourceFile): number | undefined {
+  if (!typeArg) return undefined
+  if (ts.isLiteralTypeNode(typeArg) && ts.isNumericLiteral(typeArg.literal)) {
+    const value = Number(typeArg.literal.text)
+    return Number.isFinite(value) ? value : undefined
+  }
+  if (ts.isLiteralTypeNode(typeArg) && ts.isStringLiteral(typeArg.literal)) {
+    const value = Number(typeArg.literal.text)
+    return Number.isFinite(value) ? value : undefined
+  }
+  const raw = typeArg.getText(sourceFile).trim()
+  const value = Number(raw)
+  return Number.isFinite(value) ? value : undefined
+}
+
+function mergeCheckConstraint(existing: string | undefined, next: string): string {
+  if (!existing) return next
+  return `(${existing}) AND (${next})`
+}
+
 function relationTargetFromTypeArg(typeArg: ts.TypeNode | undefined, sourceFile: ts.SourceFile): string {
   if (!typeArg) return "unknown"
   const raw = typeArg.getText(sourceFile).replace(/\s/g, "")

package/tests/augmentation-generator.test.ts

@@ -5,18 +5,58 @@ describe("generateClientAugmentation", () => {
   it("emits deterministic output independent of model order", () => {
     const astA = {
       models: [
-        { tableName: "post", fields: { title: { kind: "text", required: true } } },
-        { tableName: "comment", fields: { body: { kind: "text", required: true } } },
+        {
+          name: "Post",
+          fields: { title: { kind: "text", required: true } },
+          annotations: { db: { tableName: "post", indexes: [] } },
+        },
+        {
+          name: "Comment",
+          fields: { body: { kind: "text", required: true } },
+          annotations: { db: { tableName: "comment", indexes: [] } },
+        },
       ],
     }
     const astB = {
       models: [
-        { tableName: "comment", fields: { body: { kind: "text", required: true } } },
-        { tableName: "post", fields: { title: { kind: "text", required: true } } },
+        {
+          name: "Comment",
+          fields: { body: { kind: "text", required: true } },
+          annotations: { db: { tableName: "comment", indexes: [] } },
+        },
+        {
+          name: "Post",
+          fields: { title: { kind: "text", required: true } },
+          annotations: { db: { tableName: "post", indexes: [] } },
+        },
       ],
     }
 
     expect(generateClientAugmentation(astA)).toEqual(generateClientAugmentation(astB))
+    expect(generateClientAugmentation(astA)).toContain("post:")
+    expect(generateClientAugmentation(astA)).toContain("comment:")
+  })
+
+  it("resolves tableName from AST v2 annotations.db.tableName", () => {
+    const ast = {
+      models: [
+        {
+          name: "Profile",
+          fields: { id: { kind: "uuid", required: true } },
+          annotations: { db: { tableName: "profile", indexes: [] } },
+        },
+      ],
+    }
+    const out = generateClientAugmentation(ast)
+    expect(out).toContain("profile:")
+    expect(out).not.toContain("undefined:")
+  })
+
+  it("falls back to snake_case model name when tableName is missing", () => {
+    const ast = {
+      models: [{ name: "Profile", fields: { id: { kind: "uuid", required: true } } }],
+    }
+    expect(generateClientAugmentation(ast)).toContain("profile:")
   })
 
   it("marks Insert fields optional when serverGenerated or default is set", () => {

package/tests/realtime-launch.test.ts

@@ -0,0 +1,25 @@
+import { mkdtempSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { describe, expect, it } from "vitest"
+import { resolveRealtimeLaunch } from "../src/realtime-launch.js"
+import type { SupatypeProjectConfig } from "../src/project-config.js"
+
+describe("resolveRealtimeLaunch", () => {
+  it("uses overrides.realtime .js entry via node", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "supatype-rt-launch-"))
+    try {
+      const entry = join(dir, "fake-realtime.js")
+      const { writeFileSync } = await import("node:fs")
+      writeFileSync(entry, "export {}\n")
+      const config = {
+        overrides: { realtime: entry },
+      } as SupatypeProjectConfig
+      const spec = await resolveRealtimeLaunch(config, dir)
+      expect(spec.bin).toBe(process.execPath)
+      expect(spec.args).toEqual([entry])
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+})

package/tests/required-host-components.test.ts

@@ -33,6 +33,7 @@ describe("requiredHostComponents", () => {
       "engine",
       "server",
       "postgres",
+      "realtime",
     ])
     rmSync(dir, { recursive: true, force: true })
   })
@@ -44,6 +45,7 @@ describe("requiredHostComponents", () => {
       "engine",
       "server",
       "postgres",
+      "realtime",
       "deno",
     ])
     rmSync(dir, { recursive: true, force: true })

package/tests/route-manifest.test.ts

@@ -0,0 +1,29 @@
+import { mkdtempSync, readFileSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { describe, expect, it } from "vitest"
+import { patchRouteManifest } from "../src/route-manifest.js"
+
+describe("patchRouteManifest", () => {
+  it("merges realtime fields into existing manifest", () => {
+    const dir = mkdtempSync(join(tmpdir(), "supatype-manifest-"))
+    const path = join(dir, "manifest.json")
+    try {
+      patchRouteManifest(path, { realtime_enabled: true, realtime_url: "http://127.0.0.1:4000" })
+      const parsed = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>
+      expect(parsed).toMatchObject({
+        realtime_enabled: true,
+        realtime_url: "http://127.0.0.1:4000",
+      })
+      patchRouteManifest(path, { schema: "public" })
+      const again = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>
+      expect(again).toMatchObject({
+        schema: "public",
+        realtime_enabled: true,
+        realtime_url: "http://127.0.0.1:4000",
+      })
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+})