@supatype/cli 0.3.2 → 0.3.3

package/src/augmentation-generator.ts

@@ -38,21 +38,44 @@ function fieldServerGenerated(meta: Record<string, unknown>): boolean {
 
 export function generateClientAugmentation(ast: unknown): string {
   const parsed = ast as AstShape
-  const models = [...(parsed.models ?? [])]
-    .map((model) => ({ model, tableName: resolveTableName(model) }))
-    .sort((a, b) => a.tableName.localeCompare(b.tableName))
+  // In the order the schema declares them. The AST preserves that order, and it is the order
+  // the author reads their own schema in.
+  const models = [...(parsed.models ?? [])].map((model) => ({
+    model,
+    tableName: resolveTableName(model),
+  }))
+
+  const kinds = new Set<string>()
+  for (const { model } of models) {
+    for (const meta of Object.values(model.fields ?? {})) {
+      if (typeof meta["kind"] === "string") kinds.add(meta["kind"])
+    }
+  }
 
   const lines: string[] = []
   lines.push("// Generated by supatype CLI, do not edit manually.")
   lines.push("")
+  if (kinds.has("richText")) {
+    lines.push("import type { SerializedEditorState } from \"@supatype/types/lexical\"")
+    lines.push("")
+    lines.push("export type RichText = SerializedEditorState")
+    lines.push("")
+  }
+  if (kinds.has("image") || kinds.has("file")) {
+    lines.push("export type StorageReference = {")
+    lines.push("  bucket: string")
+    lines.push("  path: string")
+    lines.push("}")
+    lines.push("")
+  }
   lines.push("declare module \"@supatype/client\" {")
   lines.push("  interface SupatypeModels {")
 
   for (const { model, tableName } of models) {
     lines.push(`    ${quoteKey(tableName)}: {`)
-    lines.push(`      Row: ${generateRowType(model.fields)}`)
-    lines.push(`      Insert: ${generateInsertType(model.fields)}`)
-    lines.push(`      Update: ${generateUpdateType(model.fields)}`)
+    lines.push(`      Row: ${indent(generateRowType(model.fields), 6)}`)
+    lines.push(`      Insert: ${indent(generateInsertType(model.fields), 6)}`)
+    lines.push(`      Update: ${indent(generateUpdateType(model.fields), 6)}`)
     lines.push("    }")
   }
 
@@ -65,6 +88,15 @@ export function generateClientAugmentation(ast: unknown): string {
   return lines.join("\n")
 }
 
+/** Place a generated object body inside the block that holds it. */
+function indent(source: string, spaces: number): string {
+  const pad = " ".repeat(spaces)
+  return source
+    .split("\n")
+    .map((line, i) => (i === 0 ? line : `${pad}${line}`))
+    .join("\n")
+}
+
 function toSnakeCase(name: string): string {
   return name.replace(/([A-Z])/g, "_$1").replace(/^_/, "").toLowerCase()
 }
@@ -110,7 +142,6 @@ function columnsOf(
     .filter((entry): entry is { column: string; ts: string; meta: Record<string, unknown> } =>
       entry !== null,
     )
-    .sort((a, b) => a.column.localeCompare(b.column))
 }
 
 export function generateRowType(fields: Record<string, Record<string, unknown>>): string {
@@ -120,8 +151,30 @@ export function generateRowType(fields: Record<string, Record<string, unknown>>)
   return `{\n${body}\n}`
 }
 
+/**
+ * What a column accepts on the way in, where that is wider than what it returns.
+ *
+ * A rich text column holds a Lexical document, and the engine emits a trigger that normalises a
+ * plain string into one on insert and update. So writing prose is a string and reading it is
+ * always a document, and this is the only place the three shapes differ by more than
+ * optionality. Flattening them back would either demand hand-built Lexical JSON from every
+ * caller, or claim a read might return a string, which after the trigger it cannot.
+ */
+function widenForWrites(ts: string, meta: Record<string, unknown>): string {
+  // Rebuilt rather than edited. The widening has to land on the value the trigger normalises,
+  // and for a localized column that is each locale's value, not the map holding them. Splicing
+  // ` | string` into the finished string put it outside the locale wrapper, which said a bare
+  // string was a valid write to the column; the trigger would then store it as a single document
+  // where a locale map belongs, and the Row type says that cannot happen.
+  return meta["kind"] === "richText" ? toTsType(meta, true) : ts
+}
+
 function insertColumnOptionalOnInsert(meta: Record<string, unknown>): boolean {
-  return meta["default"] !== undefined || fieldServerGenerated(meta)
+  // `slug` has neither a declared default nor a `serverGenerated` flag, but the engine emits
+  // a trigger that fills it, which is the same thing from an insert's point of view.
+  return (
+    meta["default"] !== undefined || fieldServerGenerated(meta) || meta["kind"] === "slug"
+  )
 }
 
 export function generateInsertType(fields: Record<string, Record<string, unknown>>): string {
@@ -130,7 +183,7 @@ export function generateInsertType(fields: Record<string, Record<string, unknown
   const body = columns
     .map(({ column, ts, meta }) => {
       const required = meta["required"] === true && !insertColumnOptionalOnInsert(meta)
-      return `  ${quoteKey(column)}${required ? "" : "?"}: ${ts}`
+      return `  ${quoteKey(column)}${required ? "" : "?"}: ${widenForWrites(ts, meta)}`
     })
     .join("\n")
   return `{\n${body}\n}`
@@ -139,11 +192,13 @@ export function generateInsertType(fields: Record<string, Record<string, unknown
 export function generateUpdateType(fields: Record<string, Record<string, unknown>>): string {
   const columns = columnsOf(fields)
   if (columns.length === 0) return "Record<string, unknown>"
-  const body = columns.map(({ column, ts }) => `  ${quoteKey(column)}?: ${ts}`).join("\n")
+  const body = columns
+    .map(({ column, ts, meta }) => `  ${quoteKey(column)}?: ${widenForWrites(ts, meta)}`)
+    .join("\n")
   return `{\n${body}\n}`
 }
 
-function toTsType(meta: Record<string, unknown>): string {
+function toTsType(meta: Record<string, unknown>, prose = false): string {
   const kind = typeof meta["kind"] === "string" ? meta["kind"] : "json"
   const required = meta["required"] === true
   const base = (() => {
@@ -194,9 +249,9 @@ function toTsType(meta: Record<string, unknown>): string {
       // derived at read time instead.
       case "image":
       case "file":
-        return "{ bucket: string; path: string }"
+        return "StorageReference"
       case "richText":
-        return "(import(\"@supatype/types/lexical\").SerializedEditorState | string)"
+        return "RichText"
       case "enum": {
         const values = Array.isArray(meta["values"]) ? meta["values"] as unknown[] : []
         const quoted = values
@@ -211,7 +266,11 @@ function toTsType(meta: Record<string, unknown>): string {
   // A localized column is JSONB holding a locale map, `{"en": ..., "fr": ...}`, not the bare
   // value. `page.title` is exactly this and was typed `string`, so calling a string method on it
   // compiled and then failed against real data.
-  const shaped = meta["localized"] === true ? `{ [locale: string]: ${base} }` : base
+  // Prose, which a trigger normalises into a document on the way in. Applied to the element,
+  // before the locale wrapper goes on, so a localized column reads `{ [locale: string]: RichText
+  // | string }` rather than claiming the whole map could be a string.
+  const written = prose && meta["kind"] === "richText" ? `${base} | string` : base
+  const shaped = meta["localized"] === true ? `{ [locale: string]: ${written} }` : written
   return required ? shaped : `${shaped} | null`
 }
 

package/src/cli-version-embedded.ts

@@ -9,4 +9,4 @@
 // Annotated `string`, not left to inference: once a release stamps a value here, the
 // inferred literal type makes the `!== ""` test in cliPackageVersion() a compile error
 // (TS2367, no overlap), so the build would only fail during a release.
-export const EMBEDDED_CLI_VERSION: string = "0.3.2"
+export const EMBEDDED_CLI_VERSION: string = "0.3.3"

package/src/commands/generate.ts

@@ -2,7 +2,11 @@ import type { Command } from "commander"
 import { loadConfig, loadSchemaAst } from "../config.js"
 import { hooksPathFromProject, schemaPathFromProject } from "../project-config.js"
 import { writeHooksModule } from "../model-hooks.js"
-import { writeGeneratedTypes } from "../type-generation.js"
+import {
+  DEFAULT_CLIENT_PATH,
+  DEFAULT_TYPES_PATH,
+  writeGeneratedTypes,
+} from "../type-generation.js"
 import { error, info } from "../ui/messages.js"
 
 export function registerGenerate(program: Command): void {
@@ -14,8 +18,8 @@ export function registerGenerate(program: Command): void {
       const cwd = process.cwd()
       const config = loadConfig(cwd)
       const schemaPath = schemaPathFromProject(config, cwd)
-      const outputTypesPath = config.output?.types ?? "types/database.ts"
-      const outputClientPath = config.output?.client ?? "supatype/generated/index.d.ts"
+      const outputTypesPath = config.output?.types ?? DEFAULT_TYPES_PATH
+      const outputClientPath = config.output?.client ?? DEFAULT_CLIENT_PATH
 
       info("Loading schema...")
       const ast = loadSchemaAst(schemaPath, cwd)

package/src/commands/init.ts

@@ -812,7 +812,12 @@ function packageJsonTemplate(opts: ScaffoldOptions, deps: InitDependencyVersions
   const scripts: string[] = [
     `    "dev": "supatype dev"`,
     `    "push": "supatype push"`,
-    `    "seed": "tsx seed.ts"`,
+    `    "seed": "supatype seed"`,
+    // The generated seed builder is gitignored, so a fresh clone has to produce it before
+    // anything can import it. `generate` is fully offline, which is the condition that makes
+    // gitignoring generated code reasonable rather than a trap; without this hook it would be
+    // one, and the failure would be a missing module rather than anything naming the remedy.
+    `    "prepare": "supatype generate"`,
   ]
   if (opts.app.viteDevUrl) {
     scripts.push(`    "vite": "vite"`)
@@ -1347,28 +1352,33 @@ S3_SECRET_KEY=`
 }
 
 function seedTemplate(projectName: string): string {
-  return `import { sql } from "@supatype/cli/seed"
-
-// Connect using DATABASE_URL from environment
-const db = sql(
-  process.env["DATABASE_URL"] ??
-    "postgresql://supatype_admin:postgres@localhost:5432/${projectName}",
-)
-
-async function seed() {
-  console.log("Seeding ${projectName}...")
-
-  // TODO: insert seed data
-  // await db\`INSERT INTO profile (id, display_name) VALUES ('...', 'Admin')\`
+  return `import type { SeedContext } from "@supatype/cli/seed"
+
+/**
+ * Seed data for ${projectName}. Run it with \`supatype seed\`.
+ *
+ * The calls below are collected rather than executed. They are ordered by their foreign keys,
+ * batched into as few statements as they allow, and applied in one transaction: so there is no
+ * connection to open, no ordering to work out by hand, and a failure leaves nothing behind.
+ *
+ * Usually written as \`{ db, expr, log }\`; taken whole here so the example can stay commented.
+ */
+export default async function seed(ctx: SeedContext) {
+  ctx.log("seeding ${projectName}")
+
+  // \`upsert\` is the one to reach for. Seeds get re-run, and naming the row by a key it already
+  // has is what makes that safe, without an id pasted in from somewhere.
+  //
+  // ctx.db.profile.upsert({
+  //   where: { id: "00000000-0000-4000-8000-000000000001" },
+  //   data: { display_name: "Admin" },
+  // })
 
-  await db.end()
-  console.log("Done.")
+  // Times the database works out, so a fixture calendar is still ahead of whenever an
+  // environment is seeded rather than fixed to whenever this file was written:
+  //
+  //   starts_at: ctx.expr.startOf("day", { days: 30, hours: 9 })
 }
-
-seed().catch((e) => {
-  console.error(e)
-  process.exit(1)
-})
 `
 }
 

package/src/commands/seed.ts

@@ -1,15 +1,33 @@
+/**
+ * `supatype seed`: find the seed files, collect what they describe, hand it to the engine.
+ *
+ * Discovery and the Cloud guard are what this command already did. The rest is new only in
+ * that it collects rather than executes: no connection handling, no SQL, no transaction, no
+ * error mapping, because those are the engine's now and six more language runners should not
+ * each reimplement them and disagree.
+ *
+ * Both module shapes are supported. A default-exported function is the new contract and is
+ * handed a context; a module with no default export is the old one, which does its work on
+ * import and is told so by name. Nothing here removes the old shape.
+ */
+
 import type { Command } from "commander"
 import { existsSync, readdirSync } from "node:fs"
-import { join, resolve } from "node:path"
-import { isLinkedToCloudProject } from "../binary-cache.js"
-import { loadConfig } from "../config.js"
-import { projectRootFromConfig } from "../project-config.js"
-import { runTsFile } from "../tsx-runner.js"
-import { error, info } from "../ui/messages.js"
+import { join, relative, resolve, sep } from "node:path"
+import { isLinkedToCloudProject, pinnedVersion } from "../binary-cache.js"
+import { loadConfig, loadSchemaAst, type SupatypeConfig } from "../config.js"
+import { engineRequest, ensureEngine } from "../engine-client.js"
+import { seedUnsupportedByPinnedEngine } from "../engine-floor.js"
+import { pgSchema, projectRootFromConfig, schemaPathFromProject } from "../project-config.js"
+import { DsnNotFound, redact, resolveSeedDsn } from "../seed-connection.js"
+import { collectSeed, SeedCollectionFailed } from "../seed-runner.js"
+import { seedBuilderPathWithDefaults } from "../type-generation.js"
+import type { SeedConfig, SeedIr } from "../seed.js"
+import { error, info, success, warn } from "../ui/messages.js"
 
 const SEED_EXT = /\.(ts|mts|tsx)$/
 
-/** Seed entries under `seeds/`, sorted by filename (Phase 10.6 C19). */
+/** Seed entries under `seeds/`, sorted by filename. */
 export function discoverSeedsDir(cwd: string, seedsDir: string): string[] {
   if (!existsSync(seedsDir)) return []
   const names = readdirSync(seedsDir).filter((n) => SEED_EXT.test(n))
@@ -17,6 +35,21 @@ export function discoverSeedsDir(cwd: string, seedsDir: string): string[] {
   return names.map((n) => join(seedsDir, n))
 }
 
+/** One file's worth of collected IR, with what that file asked for. */
+interface Prepared {
+  file: string
+  document: SeedIr
+  config: SeedConfig
+}
+
+export interface SeedFlags {
+  force: boolean
+  atomic: boolean
+  status: boolean
+  connection?: string
+  environment?: string
+}
+
 export function registerSeed(program: Command): void {
   program
     .command("seed [file]")
@@ -28,42 +61,259 @@ export function registerSeed(program: Command): void {
       "Allow running when the project is linked to Supatype Cloud (dangerous)",
       false,
     )
-    .action(async (file: string | undefined, opts: { force: boolean }) => {
-      const cwd = process.cwd()
-      const config = loadConfig(cwd)
-      if (isLinkedToCloudProject(cwd, config) && !opts.force) {
-        error(
-          "This project is linked to Supatype Cloud. Refusing to run seeds locally.\n" +
-            "  Pass --force only if you intend to target this linked project (advanced).",
-        )
-        process.exit(1)
-      }
-
-      const root = projectRootFromConfig(config, cwd)
-      const seedsDir = join(root, "seeds")
-
-      let paths: string[]
-      if (file !== undefined && file.trim() !== "") {
-        paths = [resolve(cwd, file)]
-      } else {
-        paths = discoverSeedsDir(cwd, seedsDir)
-        if (paths.length === 0) {
-          paths = [resolve(root, "seed.ts")]
-        }
-      }
-
-      const missing = paths.filter((p) => !existsSync(p))
-      if (missing.length > 0) {
-        error(`Seed file(s) not found:\n  ${missing.join("\n  ")}`)
-        process.exit(1)
-      }
-
-      for (const seedFile of paths) {
-        info(`Running ${seedFile}...`)
-        const result = runTsFile(seedFile, { cwd, stdio: "inherit" })
-        if (result.exitCode !== 0) {
-          process.exit(result.exitCode)
-        }
-      }
+    .option("--atomic", "Run every seed file in one transaction", false)
+    .option("--status", "Show what has been applied, and what has changed since", false)
+    .option("--connection <dsn>", "Database to seed, instead of the resolved one")
+    .option("--environment <name>", "Environment name, for an `environment` condition")
+    .action(async (file: string | undefined, opts: SeedFlags) => {
+      const code = await runSeed(file, opts)
+      if (code !== 0) process.exit(code)
+    })
+}
+
+/**
+ * Separated from the action so the exit code is a value rather than a side effect.
+ *
+ * `0` applied, `1` a seed failed, `2` the run could not start. The split is what lets CI
+ * retry one and not the other.
+ */
+export async function runSeed(file: string | undefined, opts: SeedFlags): Promise<number> {
+  const cwd = process.cwd()
+  const config = loadConfig(cwd)
+
+  if (isLinkedToCloudProject(cwd, config) && !opts.force) {
+    error(
+      "This project is linked to Supatype Cloud. Refusing to run seeds locally.\n" +
+        "  Pass --force only if you intend to target this linked project (advanced).",
+    )
+    return 2
+  }
+
+  // Before the connection is resolved and before a builder is looked for: an engine that cannot
+  // seed makes both of those pointless, and the pin is the cheapest thing here to read.
+  const tooOld = seedUnsupportedByPinnedEngine(pinnedVersion("engine", config))
+  if (tooOld !== undefined) {
+    error(tooOld)
+    return 2
+  }
+
+  let dsn: string
+  try {
+    dsn = resolveSeedDsn(cwd, config, {
+      connection: opts.connection,
+      allowDerived: true,
+    }).dsn
+  } catch (e) {
+    error(e instanceof DsnNotFound ? e.message : String(e))
+    return 2
+  }
+
+  await ensureEngine()
+  if (opts.status) return await reportStatus(dsn)
+
+  const paths = seedPaths(file, cwd, config)
+  const missing = paths.filter((p) => !existsSync(p))
+  if (missing.length > 0) {
+    error(`Seed file(s) not found:\n  ${missing.join("\n  ")}`)
+    return 2
+  }
+
+  const builderPath = locateBuilder(cwd, config)
+  if (builderPath === undefined) return 2
+
+  const prepared: Prepared[] = []
+  for (const path of paths) {
+    const label = toPosix(relative(cwd, path))
+    let collected
+    try {
+      collected = collectSeed(path, {
+        cwd,
+        builderPath,
+        environment: opts.environment,
+      })
+    } catch (e) {
+      error(e instanceof SeedCollectionFailed ? e.message : String(e))
+      return 1
+    }
+
+    if (collected.stdout.trim().length > 0) {
+      for (const line of collected.stdout.trimEnd().split(/\r?\n/)) info(`  ${label}: ${line}`)
+    }
+    if (collected.result.shape === "legacy") {
+      warn(
+        `${label} has no default export, so it ran on import.\n` +
+          "  Export a default function to have its writes collected, ordered and applied in one transaction.",
+      )
+      continue
+    }
+    prepared.push({
+      file: label,
+      document: collected.result.ir,
+      config: collected.result.config,
     })
+  }
+
+  if (prepared.length === 0) {
+    info("No seed operations to apply.")
+    return 0
+  }
+
+  return await apply(prepared, { cwd, config, dsn, opts })
+}
+
+// --- Discovery ---
+
+function seedPaths(file: string | undefined, cwd: string, config: SupatypeConfig): string[] {
+  if (file !== undefined && file.trim() !== "") return [resolve(cwd, file)]
+  const root = projectRootFromConfig(config, cwd)
+  const fromDir = discoverSeedsDir(cwd, join(root, "seeds"))
+  return fromDir.length > 0 ? fromDir : [resolve(root, "seed.ts")]
+}
+
+/**
+ * The generated builder, which the runtime needs for the manifest and the fingerprint.
+ *
+ * Absent is a setup problem with a one-line remedy rather than a crash: the builder is
+ * gitignored by design, so a fresh clone that has not run `generate` is the ordinary case.
+ */
+function locateBuilder(cwd: string, config: SupatypeConfig): string | undefined {
+  const relativePath = seedBuilderPathWithDefaults(config.output)
+  const path = resolve(cwd, relativePath)
+  if (!existsSync(path)) {
+    error(
+      `The generated seed builder is missing: ${toPosix(relativePath)}\n` +
+        "  Run `supatype generate`. It needs no database and no running stack.",
+    )
+    return undefined
+  }
+  return path
+}
+
+// --- Applying ---
+
+interface ApplyOptions {
+  cwd: string
+  config: SupatypeConfig
+  dsn: string
+  opts: SeedFlags
+}
+
+async function apply(prepared: Prepared[], options: ApplyOptions): Promise<number> {
+  const { cwd, config, dsn, opts } = options
+  const ast = loadSchemaAst(schemaPathFromProject(config, cwd), cwd)
+
+  // The engine takes one `--run-once` for the run, so a file asking for it decides for all
+  // of them. Said out loud rather than generalised silently, because the difference is
+  // whether work someone expected to happen happens.
+  const askedRunOnce = prepared.filter((one) => one.config.runOnce === true)
+  if (askedRunOnce.length > 0 && askedRunOnce.length !== prepared.length) {
+    warn(
+      "Some seed files declare `runOnce` and others do not, and the run takes one setting.\n" +
+        `  Applying it to all of them, because ${askedRunOnce
+          .map((one) => one.file)
+          .join(", ")} asked for it.`,
+    )
+  }
+
+  const result = await engineRequest<SeedResult>("/seed", {
+    ast,
+    ir_documents: prepared.map((one) => JSON.stringify({ ...one.document, file: one.file })),
+    database_url: dsn,
+    schema: pgSchema(config),
+    atomic: opts.atomic,
+    run_once: askedRunOnce.length > 0,
+    ...(opts.environment !== undefined ? { environment: opts.environment } : {}),
+  })
+
+  return report(result, prepared.length, dsn)
+}
+
+interface SeedResult {
+  ok: boolean
+  atomic?: boolean
+  files?: Array<{
+    file: string
+    status: string
+    written?: Record<string, number>
+    skippedGroups?: string[]
+  }>
+  error?: {
+    kind: string
+    message?: string
+    remedy?: string | null
+    file?: string
+    path?: string
+  }
+}
+
+/**
+ * Print what happened to every file, then the outcome.
+ *
+ * Every file, not just the one that failed: without `--atomic` a failure in the third of
+ * five leaves the first two committed, and a report that mentioned only the failure would
+ * leave the reader to guess at the rest.
+ */
+function report(result: SeedResult, count: number, dsn: string): number {
+  for (const file of result.files ?? []) {
+    const rows = Object.entries(file.written ?? {})
+      .map(([model, written]) => `${model} ${written}`)
+      .join(", ")
+    info(`  ${file.file.padEnd(32)} ${file.status}${rows.length > 0 ? `  (${rows})` : ""}`)
+    for (const skipped of file.skippedGroups ?? []) {
+      info(`    condition was false, skipped: ${skipped}`)
+    }
+  }
+
+  if (result.ok) {
+    success(`Seeded ${count} file(s) into ${redact(dsn)}.`)
+    return 0
+  }
+
+  const failure = result.error
+  if (failure === undefined) {
+    error("The seed failed, and the engine said nothing about why.")
+    return 1
+  }
+
+  const where = [failure.file, failure.path].filter((part) => part !== undefined && part !== "")
+  error(
+    (failure.message ?? failure.kind) +
+      (where.length > 0 ? `\n  at ${where.join(" ")}` : "") +
+      (failure.remedy !== undefined && failure.remedy !== null ? `\n  ${failure.remedy}` : ""),
+  )
+  // Nothing ran because nothing could: the environment, not the seed.
+  return failure.kind === "connection" || failure.kind === "document" ? 2 : 1
+}
+
+async function reportStatus(dsn: string): Promise<number> {
+  interface StatusEntry {
+    file: string
+    appliedAt: string
+    status: string
+    durationMs: number
+    drifted: boolean
+  }
+  const result = await engineRequest<{ files?: StatusEntry[] }>("/seed", {
+    database_url: dsn,
+    status: true,
+  })
+
+  const files = result.files ?? []
+  if (files.length === 0) {
+    info(`No seeds have been applied to ${redact(dsn)}.`)
+    return 0
+  }
+
+  for (const entry of files) {
+    info(
+      `  ${entry.file.padEnd(32)} ${entry.status.padEnd(12)} ${entry.appliedAt}  ` +
+        `${entry.durationMs}ms${entry.drifted ? "  changed since it was applied" : ""}`,
+    )
+  }
+  return 0
+}
+
+/** Reported with forward slashes, so the message reads the same on every platform. */
+function toPosix(path: string): string {
+  return path.split(sep).join("/")
 }