@supatype/cli 0.3.2 → 0.3.3

package/src/engine-client.ts

@@ -149,6 +149,7 @@ export async function engineHealth(): Promise<boolean> {
  *   /introspect  → engine introspect
  *   /validate    → engine validate
  *   /admin       → engine admin (admin-config JSON on stdout)
+ *   /seed        → engine seed (result document JSON on stdout)
  */
 export async function engineRequest<T = unknown>(
   endpoint: string,
@@ -171,6 +172,19 @@ export async function engineRequest<T = unknown>(
     writeFileSync(gzPath, Buffer.from(body["schema_sources_gz_base64"], "base64"))
     cleanup.push(gzPath)
   }
+  // One file per seed document. The engine takes `--ir` once per document rather than one
+  // combined blob, so a failure can name the file it was in.
+  const irPaths: string[] = []
+  const documents = body["ir_documents"]
+  if (Array.isArray(documents)) {
+    documents.forEach((document, index) => {
+      const irPath = join(tmpDir, `ir-${Date.now()}-${index}.json`)
+      writeFileSync(irPath, typeof document === "string" ? document : JSON.stringify(document))
+      cleanup.push(irPath)
+      irPaths.push(irPath)
+    })
+  }
+
   if (body["schema_sources_manifest"] !== undefined) {
     manifestPath = join(tmpDir, `manifest-${Date.now()}.json`)
     writeFileSync(manifestPath, JSON.stringify(body["schema_sources_manifest"]))
@@ -180,6 +194,7 @@ export async function engineRequest<T = unknown>(
   const args = endpointToArgs(endpoint, body, reqFile, {
     ...(gzPath !== undefined ? { gzPath } : {}),
     ...(manifestPath !== undefined ? { manifestPath } : {}),
+    ...(irPaths.length > 0 ? { irPaths } : {}),
   })
 
   const result = spawnSync(bin, args, {
@@ -191,7 +206,16 @@ export async function engineRequest<T = unknown>(
     try { unlinkSync(f) } catch { /* ignore */ }
   }
 
-  if (result.status !== 0) {
+  // A failed seed is an answer, not a crash.
+  //
+  // `engine seed` exits 1 when the seed itself failed and prints the result document on
+  // stdout: which file, what it wrote before it stopped, and the error in the schema's own
+  // terms. Treating a non-zero exit as "no output" threw all of that away and reported
+  // `Engine /seed failed (exit 1): (no output)`, which is worse than the raw Postgres error
+  // it replaced. Anything without a document to read still throws.
+  const reportsFailureAsData = endpoint === "/seed" && (result.stdout?.trim().length ?? 0) > 0
+
+  if (result.status !== 0 && !reportsFailureAsData) {
     const stderr = result.stderr?.trim() || "(no output)"
     throw new EngineError(
       `Engine ${endpoint} failed (exit ${result.status}): ${stderr}`,
@@ -221,7 +245,7 @@ function endpointToArgs(
   endpoint: string,
   body: Record<string, unknown>,
   reqFile: string,
-  sources?: { gzPath?: string; manifestPath?: string },
+  sources?: { gzPath?: string; manifestPath?: string; irPaths?: string[] },
 ): string[] {
   const dbUrl = (body["database_url"] as string | undefined) ?? ""
   const schema = (body["schema"] as string | undefined) ?? "public"
@@ -259,7 +283,32 @@ function endpointToArgs(
 
     case "/generate": {
       const lang = (body["lang"] as string | undefined) ?? "typescript"
-      return ["generate", "--input", reqFile, "--lang", lang]
+      const artifact = (body["artifact"] as string | undefined) ?? "types"
+      return ["generate", "--input", reqFile, "--lang", lang, "--artifact", artifact]
+    }
+
+    case "/seed": {
+      // `--status` reads the ledger and needs no schema, so it does not take `--input`:
+      // passing one would make the command fail on a project whose schema has moved on.
+      if (body["status"] === true) {
+        return ["seed", "--database-url", dbUrl, "--status"]
+      }
+      const documents = (sources?.irPaths ?? []).flatMap((path) => ["--ir", path])
+      const environment =
+        typeof body["environment"] === "string" ? ["--environment", body["environment"]] : []
+      return [
+        "seed",
+        "--input",
+        reqFile,
+        ...documents,
+        "--database-url",
+        dbUrl,
+        "--schema",
+        schema,
+        ...environment,
+        ...(body["atomic"] === true ? ["--atomic"] : []),
+        ...(body["run_once"] === true ? ["--run-once"] : []),
+      ]
     }
 
     case "/introspect":

package/src/engine-floor.ts

@@ -36,6 +36,27 @@ export const ENGINE_MIN_FOR_BOUNDS = "0.2.0"
  */
 export const ENGINE_MIN_FOR_VERSIONS = "0.3.0"
 
+/**
+ * First engine release that normalises a rich text column's contents (schema-engine v0.4.0).
+ *
+ * Silent in the same way `versions` is, and for a reason worth naming. The generated types accept
+ * a plain string on the way in and promise a Lexical document on the way out, and a trigger is
+ * what makes the second half true for every writer. An older engine emits no trigger and rejects
+ * nothing, so the string is stored exactly as it was written and every later read returns
+ * something the types say cannot happen.
+ */
+export const ENGINE_MIN_FOR_RICHTEXT_TRIGGER = "0.4.0"
+
+/**
+ * First engine release that has a `seed` subcommand (schema-engine v0.4.0).
+ *
+ * Unconditional, where everything else in this file is conditional on the schema. There is no way
+ * to write a seed that does not need the subcommand, so there is nothing to read the project for
+ * and nothing to point at. An older engine answers the request with a usage error about an
+ * unrecognised argument, which names no part of the project and reads like a broken install.
+ */
+export const ENGINE_MIN_FOR_SEED = "0.4.0"
+
 /**
  * Compare two dotted versions numerically. Returns <0, 0 or >0.
  *
@@ -89,6 +110,17 @@ export function boundsRequiringHelpers(ast: ExtractedSchemaAstV2): string[] {
   return [...fieldsWithBounds(ast.models), ...modelsWithConstraints(ast.models)]
 }
 
+/** Rich text fields, which need a trigger only a new enough engine emits. */
+export function fieldsNeedingRichTextTrigger(ast: ExtractedSchemaAstV2): string[] {
+  const found: string[] = []
+  for (const model of ast.models) {
+    for (const [fieldName, field] of Object.entries(model.fields)) {
+      if (field.kind === "richText") found.push(`${model.name}.${fieldName}`)
+    }
+  }
+  return found
+}
+
 /** Models declaring `versions`, which needs a whole layer only a new enough engine emits. */
 export function modelsRequiringVersions(ast: ExtractedSchemaAstV2): string[] {
   return ast.models
@@ -134,6 +166,17 @@ const ENGINE_REQUIREMENTS: EngineRequirement[] = [
       `push reports success and you get a model with no history, no drafts and an editor that ` +
       `saves into nothing. That silence is the reason this refuses.`,
   },
+  {
+    since: ENGINE_MIN_FOR_RICHTEXT_TRIGGER,
+    declaredBy: fieldsNeedingRichTextTrigger,
+    feature: "rich text columns",
+    consequence:
+      `Only engine ${ENGINE_MIN_FOR_RICHTEXT_TRIGGER}+ emits the trigger that turns a plain ` +
+      `string written into one of these columns into a Lexical document. The generated types ` +
+      `accept a string on the way in and promise a document on the way out, and the trigger is ` +
+      `the only thing that makes the second half true. Without it the string is stored as it ` +
+      `was written and a later read returns what the types say is impossible.`,
+  },
 ]
 
 /**
@@ -142,13 +185,37 @@ const ENGINE_REQUIREMENTS: EngineRequirement[] = [
  * Takes the pin from `versions.engine`, or undefined when unpinned. See the note above on why
  * that is the right source rather than the binary's own `--version`.
  */
+/**
+ * Whether a pin can be compared at all.
+ *
+ * Unpinned resolves to latest, and `local` points at a build whose version the config does not
+ * know. Neither can be compared, and neither is the case that breaks.
+ */
+function comparable(pin: string | undefined): pin is string {
+  return pin !== undefined && pin !== "local"
+}
+
+/**
+ * The parts every refusal here shares: what is needed, and what to do about it.
+ *
+ * One builder rather than one per check, because the remedy is the only part of this message
+ * anyone acts on, and a second copy is a second place for it to go stale.
+ */
+function refusal(parts: { needs: string; since: string; pinned: string; body: string }): string {
+  return (
+    `${parts.needs}, which needs schema-engine ${parts.since} or newer, and this project ` +
+    `pins ${parts.pinned}.\n\n` +
+    `${parts.body}\n\n` +
+    `Raise or remove the pin in supatype.config.ts:\n` +
+    `  versions: { engine: "${parts.since}" }   // or omit it to track latest`
+  )
+}
+
 export function assertEngineSupportsSchema(
   ast: ExtractedSchemaAstV2,
   pinnedEngineVersion: string | undefined,
 ): void {
-  // Unpinned resolves to latest, and `local` points at a build whose version the config does not
-  // know. Neither can be compared, and neither is the case that breaks.
-  if (pinnedEngineVersion === undefined || pinnedEngineVersion === "local") return
+  if (!comparable(pinnedEngineVersion)) return
 
   for (const requirement of ENGINE_REQUIREMENTS) {
     if (compareVersions(pinnedEngineVersion, requirement.since) >= 0) continue
@@ -159,12 +226,36 @@ export function assertEngineSupportsSchema(
     const shown = needed.slice(0, 3).join(", ")
     const more = needed.length > 3 ? `, and ${needed.length - 3} more` : ""
     throw new Error(
-      `This schema declares ${requirement.feature}, which needs schema-engine ` +
-        `${requirement.since} or newer, and this project pins ${pinnedEngineVersion}.\n\n` +
-        `  Declared on: ${shown}${more}\n\n` +
-        `${requirement.consequence}\n\n` +
-        `Raise or remove the pin in supatype.config.ts:\n` +
-        `  versions: { engine: "${requirement.since}" }   // or omit it to track latest`,
+      refusal({
+        needs: `This schema declares ${requirement.feature}`,
+        since: requirement.since,
+        pinned: pinnedEngineVersion,
+        body: `  Declared on: ${shown}${more}\n\n${requirement.consequence}`,
+      }),
     )
   }
 }
+
+/**
+ * Why the pinned engine cannot run a seed, or undefined when it can.
+ *
+ * Returns rather than throws, because the seed command answers in exit codes and this is a `2`:
+ * the run could not start, alongside a missing builder or an unreachable database, rather than a
+ * `1` where the seed itself was wrong.
+ */
+export function seedUnsupportedByPinnedEngine(
+  pinnedEngineVersion: string | undefined,
+): string | undefined {
+  if (!comparable(pinnedEngineVersion)) return undefined
+  if (compareVersions(pinnedEngineVersion, ENGINE_MIN_FOR_SEED) >= 0) return undefined
+
+  return refusal({
+    needs: "Seeding is done by the engine",
+    since: ENGINE_MIN_FOR_SEED,
+    pinned: pinnedEngineVersion,
+    body:
+      `An engine older than ${ENGINE_MIN_FOR_SEED} has no \`seed\` subcommand. It would answer ` +
+      `this run with a usage error about an unrecognised argument, which names nothing about ` +
+      `your project and reads like a broken install.`,
+  })
+}

package/src/gitignore.ts

@@ -24,6 +24,13 @@ const SUPATYPE_IGNORED_PATHS = [
   "supatype.local.config.ts",
   "supatype.local.config.js",
   "supatype.local.config.mjs",
+  // Generated from schema/index.ts by `supatype generate`, which needs no database and no
+  // running stack, so a clone can always rebuild it. Listed here rather than only in the
+  // `init` template so projects that already exist pick it up too.
+  //
+  // The default path. A project that moves `output.client` moves this with it, and would
+  // need its own line: there is no pattern that follows a value from the config file.
+  "supatype/generated/seed.ts",
 ] as const
 
 /** The paths above, for a scaffold that composes its own `.gitignore` around them. */

package/src/hooks-generator.ts

@@ -83,12 +83,18 @@ export function generateHooksModule(ast: unknown): string | null {
 //   })
 
 /**
- * Lexical editor state as JSON, or the plain string accepted for seeds and defaults.
+ * Lexical editor state as JSON.
  *
  * Structural rather than imported: the precise \`SerializedEditorState\` lives in
  * \`@supatype/types/lexical\`, which a Deno function has no way to resolve.
+ *
+ * A hook writing to a rich text column may hand back a plain string instead; a trigger
+ * normalises it into one of these, so what a later read returns is always the document.
  */
-export type RichTextValue = { readonly root: { readonly children: readonly unknown[] } } | string
+export type RichTextValue = { readonly root: { readonly children: readonly unknown[] } }
+
+/** A stored file, and the bucket it went to. */
+export type StorageReference = { readonly bucket: string; readonly path: string }
 
 export interface HookTables {
 ${tableEntries}
@@ -412,11 +418,20 @@ function json(body: unknown, status: number): Response {
  * column emitted a module that failed to compile in the user's editor. Caught by compiling the
  * generated file in a test rather than by a reader reporting it.
  */
+/**
+ * The shared type names, as a Deno module can spell them.
+ *
+ * `RichText` resolves through `@supatype/types/lexical`, which a Deno function has no way to
+ * reach, so the module declares a structural stand-in and the generated rows point at that.
+ * `StorageReference` needs no import and is declared here as itself.
+ */
 function denoSafe(source: string): string {
-  return source.replaceAll(
-    'import("@supatype/types/lexical").SerializedEditorState',
-    "RichTextValue",
-  )
+  return source
+    .replaceAll("RichText", "RichTextValue")
+    .replaceAll(
+      'import("@supatype/types/lexical").SerializedEditorState',
+      "RichTextValue",
+    )
 }
 
 /** Re-indent a generated type literal so the emitted file reads as if it were written by hand. */

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")
+}