@supatype/cli 0.3.1 → 0.3.3

package/src/schema-ast-v2.ts

@@ -227,6 +227,15 @@ export interface ExtractedSchemaAstV2 {
   }
 }
 
+/**
+ * The Postgres type each field kind maps to, as published in the AST.
+ *
+ * A contract, not a hint: consumers generate parsers and casts from it. `money` and `decimal` said
+ * `TEXT` here while the engine creates `NUMERIC(19,4)` and `NUMERIC`, so anyone reading this wrote
+ * code that rejected every value the column returns. The engine's own `default_pg_type` agreed
+ * with the mistake for `money`, and was already right for `decimal`, which is what made it look
+ * considered.
+ */
 const DEFAULT_DB_BY_KIND: Partial<Record<FieldKind, Partial<DbFieldAnnotations>>> = {
   text: { pgType: "TEXT" },
   richText: { pgType: "JSONB" },
@@ -244,17 +253,17 @@ const DEFAULT_DB_BY_KIND: Partial<Record<FieldKind, Partial<DbFieldAnnotations>>
   slug: { pgType: "TEXT" },
   enum: { pgType: "TEXT" },
   json: { pgType: "JSONB" },
-  decimal: { pgType: "TEXT" },
+  decimal: { pgType: "NUMERIC" },
   bytes: { pgType: "BYTEA" },
   serial: { pgType: "SERIAL" },
   bigSerial: { pgType: "BIGSERIAL" },
-  money: { pgType: "TEXT" },
-  ip: { pgType: "TEXT" },
-  cidr: { pgType: "TEXT" },
-  macaddr: { pgType: "TEXT" },
-  xml: { pgType: "TEXT" },
-  tsQuery: { pgType: "TEXT" },
-  tsVector: { pgType: "TEXT" },
+  money: { pgType: "NUMERIC(19,4)" },
+  ip: { pgType: "INET" },
+  cidr: { pgType: "CIDR" },
+  macaddr: { pgType: "MACADDR" },
+  xml: { pgType: "XML" },
+  tsQuery: { pgType: "TSQUERY" },
+  tsVector: { pgType: "TSVECTOR" },
   color: { pgType: "TEXT" },
   array: { pgType: "ARRAY" },
   image: { pgType: "JSONB" },

package/src/seed-connection.ts

@@ -0,0 +1,146 @@
+/**
+ * Which database a seed run targets, and how that was decided.
+ *
+ * Its own file so the failure is testable without spawning anything. The failure is the
+ * point: the old seed template carried a hardcoded fallback DSN, so a project with no
+ * `.env` did not fail, it silently tried `localhost:5432` with a guessed password and
+ * reported a connection error that named none of the things it had looked at. Someone
+ * reading that has no way to tell "I have not set DATABASE_URL" from "the stack is not
+ * running".
+ *
+ * So every source is recorded whether it was found or not, and the error prints the lot.
+ */
+
+import { existsSync } from "node:fs"
+import { join } from "node:path"
+import { readEnvFile } from "./env-file.js"
+import {
+  externalDatabaseUrl,
+  localDSN,
+  projectRootFromConfig,
+  type SupatypeProjectConfig,
+} from "./project-config.js"
+
+/** One place a connection string could have come from. */
+export interface DsnSource {
+  /** How it would be described to the person running the command. */
+  name: string
+  /** What was found there, or why nothing was. */
+  detail: string
+  found: boolean
+}
+
+export interface ResolvedDsn {
+  dsn: string
+  /** The `name` of the source it came from. */
+  source: string
+  /** Every source, in the order they were considered. */
+  tried: readonly DsnSource[]
+}
+
+/** Nothing named a database, with every source tried. */
+export class DsnNotFound extends Error {
+  constructor(readonly tried: readonly DsnSource[]) {
+    super(
+      `No database connection string for this seed run.\n${tried
+        .map((source) => `  ${source.found ? "found" : "not set"}  ${source.name}: ${source.detail}`)
+        .join("\n")}`,
+    )
+    this.name = "DsnNotFound"
+  }
+}
+
+export interface ResolveOptions {
+  /** `--connection`, which beats everything because it was typed just now. */
+  connection?: string | undefined
+  /**
+   * Whether to fall back to the DSN derived from the project name.
+   *
+   * True for a project whose database Supatype manages, where the derived value is right by
+   * construction. A project pointed at someone else's Postgres has no such default, and
+   * inventing one would send the seed to a database nobody named.
+   */
+  allowDerived?: boolean
+}
+
+/**
+ * Resolve the DSN, in the order the rest of the CLI already uses.
+ *
+ * `.env` is loaded first but ranks below a real environment variable, which is how every
+ * other dotenv reader behaves and how Compose resolves the same names.
+ */
+export function resolveSeedDsn(
+  cwd: string,
+  config: SupatypeProjectConfig,
+  options: ResolveOptions = {},
+): ResolvedDsn {
+  const root = projectRootFromConfig(config, cwd)
+  const envPath = join(root, ".env")
+  const fromFile = readEnvFile(root)
+  const tried: DsnSource[] = []
+
+  const candidate = (name: string, value: string | undefined, absent: string): string | undefined => {
+    const trimmed = value?.trim()
+    if (trimmed !== undefined && trimmed.length > 0) {
+      tried.push({ name, detail: redact(trimmed), found: true })
+      return trimmed
+    }
+    tried.push({ name, detail: absent, found: false })
+    return undefined
+  }
+
+  const flag = candidate("--connection", options.connection, "not passed")
+  if (flag !== undefined) return { dsn: flag, source: "--connection", tried }
+
+  // Ahead of the rest on purpose: a stated external database is the whole stack's database,
+  // and seeding somewhere else while the services read from here would look like data loss.
+  const external = candidate(
+    "database.external.url in supatype.config.ts",
+    externalDatabaseUrl(config),
+    "not declared",
+  )
+  if (external !== undefined) {
+    return { dsn: external, source: "database.external.url in supatype.config.ts", tried }
+  }
+
+  const declared = candidate("connection in supatype.config.ts", config.connection, "not declared")
+  if (declared !== undefined) {
+    return { dsn: declared, source: "connection in supatype.config.ts", tried }
+  }
+
+  const fromEnv = candidate("DATABASE_URL in the environment", process.env["DATABASE_URL"], "not set")
+  if (fromEnv !== undefined) {
+    return { dsn: fromEnv, source: "DATABASE_URL in the environment", tried }
+  }
+
+  const fileLabel = `DATABASE_URL in ${envPath}`
+  const fileValue = candidate(
+    fileLabel,
+    fromFile["DATABASE_URL"],
+    existsSync(envPath) ? "the file has no DATABASE_URL" : "no .env file",
+  )
+  if (fileValue !== undefined) return { dsn: fileValue, source: fileLabel, tried }
+
+  if (options.allowDerived === true) {
+    const derived = localDSN(config)
+    tried.push({ name: "the project's own local database", detail: redact(derived), found: true })
+    return { dsn: derived, source: "the project's own local database", tried }
+  }
+  tried.push({
+    name: "the project's own local database",
+    detail: "this project points at a database it does not manage, so there is no default",
+    found: false,
+  })
+
+  throw new DsnNotFound(tried)
+}
+
+/**
+ * A connection string with its password removed.
+ *
+ * Every one of these reaches a terminal, and often a CI log. Printing a DSN to explain where
+ * it came from should not be how a password ends up somewhere it is kept.
+ */
+export function redact(dsn: string): string {
+  return dsn.replace(/(:\/\/[^:/@]+:)[^@]*(@)/, "$1***$2")
+}

package/src/seed-ir.ts

@@ -0,0 +1,311 @@
+/**
+ * Collect a seed's builder calls into an IR document.
+ *
+ * The only genuinely new file in the CLI half of this: everything else is rewiring. What it
+ * does is narrow. It records calls in the order they were made, encodes each value into the
+ * shape the engine reads, and hands back a document. It resolves nothing, orders nothing,
+ * validates nothing and connects to nothing, because the engine does all four and doing any
+ * of them twice is how the two ends come to disagree.
+ *
+ * **Labels are assigned lazily.** A `create` becomes a referenceable operation only when
+ * something actually reads a property off what it returned. Assigning one to every operation
+ * would put an `id` in the IR for rows nobody points at, which is noise in a document people
+ * read and diff.
+ */
+
+import type {
+  DefaultExpr,
+  ModelApi,
+  ModelManifest,
+  NumericValue,
+  Operand,
+  Predicate,
+  RefValue,
+  SeedCondition,
+  SeedConditionInput,
+  SeedData,
+  SeedDb,
+  SeedIr,
+  SeedOperation,
+  SeedValue,
+} from "./seed.js"
+
+/** A model's own name and the facts the encoder needs about its columns. */
+export type Manifest = Readonly<Record<string, ModelManifest>>
+
+/** What a collector hands back once the seed has run. */
+export interface CollectedIr {
+  ir: SeedIr
+  /** The document as the engine will read it, which is what the ledger hashes. */
+  json: string
+}
+
+/** One operation, still mutable while the seed is running. */
+interface Pending {
+  operation: SeedOperation
+  /** Set the first time something reads a property off this operation's result. */
+  label?: string
+}
+
+export class SeedCollector {
+  private readonly manifest: Manifest
+  private readonly byModel: Map<string, ModelManifest>
+  /** The block currently being collected into: the document, or a `$if` body. */
+  private readonly stack: SeedOperation[][] = []
+  private readonly root: SeedOperation[] = []
+  private labels = 0
+
+  constructor(
+    private readonly fingerprint: string,
+    manifest: Manifest,
+  ) {
+    this.manifest = manifest
+    this.byModel = new Map(Object.values(manifest).map((entry) => [entry.model, entry]))
+    this.stack.push(this.root)
+  }
+
+  /** The `db` a seed's default export is handed. */
+  db(): SeedDb {
+    const api: Record<string, unknown> = {}
+    for (const [accessor, entry] of Object.entries(this.manifest)) {
+      api[accessor] = this.modelApi(entry)
+    }
+    api["$if"] = (condition: SeedConditionInput, body: () => void): void => {
+      this.group(condition, body)
+    }
+    api["$sql"] = (text: string, params?: readonly SeedValue[]): void => {
+      // Always present, even when empty: the engine defaults it either way, and a document
+      // whose shape changes with its contents is harder to read and to diff.
+      this.push({ op: "sql", text, params: params === undefined ? [] : [...params] })
+    }
+    return api as SeedDb
+  }
+
+  /** The document, with every label that was actually used written in. */
+  finish(): CollectedIr {
+    const ir: SeedIr = {
+      irVersion: 1,
+      schemaFingerprint: this.fingerprint,
+      operations: this.root,
+    }
+    return { ir, json: JSON.stringify(ir, null, 2) }
+  }
+
+  // --- Operations ---
+
+  private modelApi(entry: ModelManifest): ModelApi<SeedData, SeedData, Record<string, RefValue>> {
+    return {
+      create: (data, options) => {
+        const pending: Pending = {
+          operation: { op: "create", model: entry.model, data: this.encodeRow(entry, data) },
+        }
+        if (options?.id !== undefined) this.name(pending, options.id)
+        this.push(pending.operation)
+        return this.reference(pending)
+      },
+
+      createMany: (rows) => {
+        this.push({
+          op: "createMany",
+          model: entry.model,
+          rows: rows.map((row) => this.encodeRow(entry, row)),
+        })
+      },
+
+      upsert: ({ where, data, id }) => {
+        const pending: Pending = {
+          operation: {
+            op: "upsert",
+            model: entry.model,
+            where: this.encodeRow(entry, where),
+            data: this.encodeRow(entry, data),
+          },
+        }
+        if (id !== undefined) this.name(pending, id)
+        this.push(pending.operation)
+        return this.reference(pending)
+      },
+    }
+  }
+
+  private group(condition: SeedConditionInput, body: () => void): void {
+    const operations: SeedOperation[] = []
+    this.stack.push(operations)
+    try {
+      body()
+    } finally {
+      // Popped in a `finally` so a seed that throws inside a `$if` does not leave every
+      // later operation collecting into a block that is never emitted.
+      this.stack.pop()
+    }
+    this.push({ op: "group", if: encodeCondition(condition), operations })
+  }
+
+  private push(operation: SeedOperation): void {
+    const block = this.stack[this.stack.length - 1]
+    if (block === undefined) throw new Error("the seed collector lost its block")
+    block.push(operation)
+  }
+
+  // --- References ---
+
+  private name(pending: Pending, label?: string): string {
+    if (pending.label !== undefined) return pending.label
+    this.labels += 1
+    pending.label = label ?? `op${this.labels}`
+    const operation = pending.operation
+    if (operation.op === "create" || operation.op === "upsert") {
+      operation.id = pending.label
+    }
+    return pending.label
+  }
+
+  /**
+   * What an operation hands back.
+   *
+   * A proxy rather than a plain object, because the columns a seed may reference are the
+   * model's columns and building one property per column per row would cost more than the
+   * seed itself. Reading a property is also what tells the collector this operation needs a
+   * label at all.
+   */
+  private reference(pending: Pending): Record<string, RefValue> {
+    return new Proxy({} as Record<string, RefValue>, {
+      get: (_target, property): RefValue | undefined => {
+        // A proxy gets asked about `then` when it is awaited or resolved, and about
+        // symbols by anything that inspects it. Answering with a reference would make a
+        // seed that awaits a builder call hang on a thenable that never settles.
+        if (typeof property !== "string" || property === "then") return undefined
+        return { $ref: `${this.name(pending)}.${property}` }
+      },
+    })
+  }
+
+  // --- Values ---
+
+  private encodeRow(entry: ModelManifest, row: SeedData): SeedData {
+    const out: SeedData = {}
+    for (const [key, value] of Object.entries(row)) {
+      if (value === undefined) continue
+      out[key] = this.encode(entry, key, value)
+    }
+    return out
+  }
+
+  private encode(entry: ModelManifest, key: string, value: SeedValue): SeedValue {
+    if (isPassThrough(value)) return value
+
+    const relation = entry.relations[key]
+    if (relation !== undefined) {
+      const nested = this.nested(relation.target, value)
+      if (nested !== undefined) return nested
+    }
+
+    if (value instanceof Date) return value.toISOString()
+    if (typeof value === "bigint") return (value as bigint).toString()
+
+    // The column's kind decides the encoding, and only the manifest knows it: a decimal
+    // sent as a JSON number round-trips through a double and stops being the value the
+    // column holds.
+    if (typeof value === "number" && entry.numeric.includes(key)) {
+      return { $numeric: String(value) } satisfies NumericValue
+    }
+    if (typeof value === "string" && entry.numeric.includes(key)) {
+      return { $numeric: value } satisfies NumericValue
+    }
+
+    if (Array.isArray(value)) return value.map((item) => this.encodeLoose(item))
+    return value
+  }
+
+  /**
+   * A relation's input, with its rows encoded against the model they will be written to.
+   *
+   * Returns `undefined` when the value is not one of the relation shapes, so an ordinary
+   * value on a field that happens to share a relation's name is left alone.
+   */
+  private nested(target: string, value: SeedValue): SeedValue | undefined {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined
+    const shape = value as Record<string, unknown>
+    const entry = this.byModel.get(target)
+
+    if ("connect" in shape) {
+      const where = shape["connect"]
+      if (entry === undefined || where === null || typeof where !== "object") return undefined
+      return { connect: this.encodeRow(entry, where as SeedData) }
+    }
+    if ("create" in shape) {
+      const rows = toRows(shape["create"])
+      if (entry === undefined || rows === undefined) return undefined
+      return { create: rows.map((row) => this.encodeRow(entry, row)) }
+    }
+    if ("createMany" in shape) {
+      const rows = toRows(shape["createMany"])
+      if (entry === undefined || rows === undefined) return undefined
+      return { createMany: rows.map((row) => this.encodeRow(entry, row)) }
+    }
+    return undefined
+  }
+
+  /** A value with no column to consult, such as an element of an array. */
+  private encodeLoose(value: SeedValue): SeedValue {
+    if (isPassThrough(value)) return value
+    if (value instanceof Date) return value.toISOString()
+    if (typeof value === "bigint") return (value as bigint).toString()
+    if (Array.isArray(value)) return value.map((item) => this.encodeLoose(item))
+    return value
+  }
+}
+
+/**
+ * A `hasOne` nests one row and a `hasMany` nests several; the IR carries a list either way.
+ *
+ * Normalised here rather than in the generated builder, so six more generators do not each
+ * have to remember it.
+ */
+function toRows(value: unknown): SeedData[] | undefined {
+  if (Array.isArray(value)) return value as SeedData[]
+  if (value !== null && typeof value === "object") return [value as SeedData]
+  return undefined
+}
+
+/**
+ * Values that are already in the shape the engine reads.
+ *
+ * `expr.now()` is literally `{ kind: "now" }` and a reference is literally `{ $ref: ... }`,
+ * so encoding them again would wrap an operand in a decimal or walk into a proxy.
+ */
+function isPassThrough(value: SeedValue): boolean {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false
+  const shape = value as Record<string, unknown>
+  return (
+    "$ref" in shape ||
+    "$numeric" in shape ||
+    "$default" in shape ||
+    typeof shape["kind"] === "string"
+  )
+}
+
+/** The surface a seed writes, in the shape the IR carries. */
+export function encodeCondition(condition: SeedConditionInput): SeedCondition {
+  if ("environment" in condition) {
+    return { kind: "environment", name: condition.environment }
+  }
+  if ("exists" in condition) {
+    return scoped("exists", condition.exists)
+  }
+  return scoped("notExists", condition.notExists)
+}
+
+function scoped(
+  kind: "exists" | "notExists",
+  target: { model: string; where?: Predicate },
+): SeedCondition {
+  return {
+    kind,
+    model: target.model,
+    ...(target.where !== undefined ? { where: target.where } : {}),
+  }
+}
+
+/** Re-exported for the runner, which has no reason to know these came from `seed.ts`. */
+export type { DefaultExpr, Operand, RefValue, SeedIr, SeedOperation, SeedValue }

package/src/seed-runner.ts

@@ -0,0 +1,109 @@
+/**
+ * Run one seed module and take the document it described.
+ *
+ * In a child process, through tsx, which is how this CLI already evaluates a project's
+ * TypeScript. Two reasons beyond consistency: a seed is the user's code and should not share
+ * a process with the tool running it, and the same route works for the standalone binary,
+ * which interprets TypeScript itself rather than resolving tsx from a `node_modules` it does
+ * not have.
+ *
+ * The document comes back through a file rather than stdout, because a seed is allowed to
+ * print. Mixing its output into the channel carrying the document would mean a `log()` call
+ * could corrupt the IR.
+ */
+
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { pathToFileURL } from "node:url"
+import { evalTsSnippet } from "./tsx-runner.js"
+import type { SeedConfig, SeedIr } from "./seed.js"
+
+/** What a seed module turned out to be. */
+export type Collected =
+  | {
+      shape: "collected"
+      ir: SeedIr
+      config: SeedConfig
+    }
+  | {
+      /**
+       * The old contract: no default export, so importing it did the work.
+       *
+       * Every existing project is this shape and keeps working. Nothing here removes it.
+       */
+      shape: "legacy"
+    }
+
+export interface CollectOptions {
+  cwd: string
+  /** The generated builder, for the manifest and the schema fingerprint. */
+  builderPath: string
+  environment?: string | undefined
+}
+
+export class SeedCollectionFailed extends Error {
+  constructor(
+    readonly file: string,
+    readonly output: string,
+  ) {
+    super(`${file} failed while it was being read:\n${output}`)
+    this.name = "SeedCollectionFailed"
+  }
+}
+
+/** Import `file`, run its default export against a collector, and return what it described. */
+export function collectSeed(file: string, options: CollectOptions): { result: Collected; stdout: string } {
+  const scratch = mkdtempSync(join(tmpdir(), "supatype-seed-"))
+  const outPath = join(scratch, "ir.json")
+
+  try {
+    const run = evalTsSnippet(snippet(file, outPath, options), { cwd: options.cwd })
+    if (run.exitCode !== 0 || !existsSync(outPath)) {
+      throw new SeedCollectionFailed(file, [run.stdout, run.stderr].filter(Boolean).join("\n").trim())
+    }
+    const result = JSON.parse(readFileSync(outPath, "utf8")) as Collected
+    return { result, stdout: run.stdout }
+  } finally {
+    rmSync(scratch, { recursive: true, force: true })
+  }
+}
+
+/**
+ * The program that runs in the child.
+ *
+ * Every path is interpolated as a JSON string rather than pasted in, because a Windows path
+ * is full of backslashes and a project directory is allowed to contain a quote.
+ */
+function snippet(file: string, outPath: string, options: CollectOptions): string {
+  const url = (path: string): string => JSON.stringify(pathToFileURL(path).href)
+  return `
+import { writeFileSync } from "node:fs"
+import { SeedCollector } from "./seed-ir.js"
+import { expr } from "./seed.js"
+
+const builder = await import(${url(options.builderPath)})
+const module = await import(${url(file)})
+
+if (typeof module.default !== "function") {
+  // Importing it is what ran it, which is the old contract working exactly as it did.
+  writeFileSync(${JSON.stringify(outPath)}, JSON.stringify({ shape: "legacy" }))
+} else {
+  const collector = new SeedCollector(builder.schemaFingerprint, builder.seedModels)
+  await module.default({
+    db: collector.db(),
+    expr,
+    log: (message) => { console.log(message) },
+    environment: ${options.environment === undefined ? "undefined" : JSON.stringify(options.environment)},
+  })
+  writeFileSync(
+    ${JSON.stringify(outPath)},
+    JSON.stringify({
+      shape: "collected",
+      ir: collector.finish().ir,
+      config: module.config ?? {},
+    }),
+  )
+}
+`
+}