@reventlessdev/reventless-seed 1.0.0-alpha.1 → 1.0.0-alpha.11

package/src/Seed_Connect.res

@@ -0,0 +1,86 @@
+// Turns endpoints plus a login function into a ready `connection`.
+//
+// A connection is what a data set seeds against: an authenticated GraphQL
+// client, the deployment's upload endpoints (empty when it serves no uploads),
+// and a human label for the target. `make` is provider-agnostic — it prompts for
+// credentials, calls the supplied `login` to obtain a bearer, and wires it onto
+// the client via `useToken`. Where the bearer comes from (a local `/login`
+// round-trip, a Cognito id token) is the caller's concern.
+
+open Seed_Types
+
+// Under route B the client mints uploads through the domain API's `Upload_Presign`
+// mutation (authenticated by the same bearer as commands), so a connection needs no
+// upload endpoint — just the authenticated client and whether uploads are skipped this
+// run (`SEED_SKIP_UPLOADS`). Which store an asset uploads into is the caller's `~store`.
+type connection = {
+  client: Seed_Client.t,
+  uploadsSkipped: bool,
+  label: string,
+}
+
+/**
+ * Prompts for credentials, calls `login` to mint a bearer, and returns a
+ * connection with that bearer already applied. `login` returns the bearer so a
+ * single `useToken` path serves every provider.
+ */
+let make = async (
+  ~label: string,
+  ~endpoint: string,
+  ~login: (~username: string, ~password: string) => promise<string>,
+  ~localDefaults: bool=false,
+): connection => {
+  // `SEED_SKIP_UPLOADS` forces the upload phase to no-op — seed domain data fast, or
+  // skip a broken/absent upload path without editing the data set. The data set reads
+  // `connection.uploadsSkipped` and reports the skip.
+  let uploadsSkipped = Seed_Upload.uploadsSkipped()
+  let (username, password) = await Seed_Prompt.credentials(~localDefaults)
+  let token = await login(~username, ~password)
+  let client = Seed_Client.make(~config={endpoint: endpoint})
+  client->Seed_Client.useToken(token)
+  {client, uploadsSkipped, label}
+}
+
+/**
+ * A login function backed by an HTTP login endpoint (the local dev
+ * `/__inmemory/login` shape: POST `{username, password}` → `{token}`). Reuses
+ * `Seed_Client.login` but hands the token back for `useToken`.
+ */
+let viaLoginEndpoint = (~loginEndpoint: string) => async (
+  ~username: string,
+  ~password: string,
+): string => {
+  let client = Seed_Client.make(
+    ~config={endpoint: loginEndpoint, loginEndpoint, username, password},
+  )
+  await Seed_Client.login(client)
+  switch Seed_Client.currentToken(client) {
+  | Some(token) => token
+  | None => throw(Failed(`login at ${loginEndpoint} returned no token`))
+  }
+}
+
+let envOr = (key: string, fallback: string): string =>
+  Seed_Prompt.envValue(key)->Option.getOr(fallback)
+
+/**
+ * A ready `connect` thunk for the local dev platform, with the localhost
+ * defaults baked in and overridable per endpoint (arg, then env var, then
+ * default). Empty input at the credential prompt falls back to `admin`/`admin`.
+ *
+ * No upload endpoint: uploads mint through the domain API's `Upload_Presign` mutation
+ * on the same `graphql` endpoint, with the store passed per asset.
+ */
+let local = (~graphql=?, ~login=?, ()): (unit => promise<connection>) => {
+  let endpoint =
+    graphql->Option.getOr(envOr("REVENTLESS_GRAPHQL_ENDPOINT", "http://localhost:4000/graphql"))
+  let loginEndpoint =
+    login->Option.getOr(envOr("REVENTLESS_LOGIN_ENDPOINT", "http://localhost:4000/__inmemory/login"))
+  () =>
+    make(
+      ~label="local",
+      ~endpoint,
+      ~login=viaLoginEndpoint(~loginEndpoint),
+      ~localDefaults=true,
+    )
+}

package/src/Seed_Connect.res.mjs

@@ -0,0 +1,62 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Seed_Types$ReventlessSeed from "./Seed_Types.res.mjs";
+import * as Seed_Client$ReventlessSeed from "./Seed_Client.res.mjs";
+import * as Seed_Prompt$ReventlessSeed from "./Seed_Prompt.res.mjs";
+import * as Seed_Upload$ReventlessSeed from "./Seed_Upload.res.mjs";
+
+async function make(label, endpoint, login, localDefaultsOpt) {
+  let localDefaults = localDefaultsOpt !== undefined ? localDefaultsOpt : false;
+  let uploadsSkipped = Seed_Upload$ReventlessSeed.uploadsSkipped();
+  let match = await Seed_Prompt$ReventlessSeed.credentials(localDefaults);
+  let token = await login(match[0], match[1]);
+  let client = Seed_Client$ReventlessSeed.make({
+    endpoint: endpoint
+  });
+  Seed_Client$ReventlessSeed.useToken(client, token);
+  return {
+    client: client,
+    uploadsSkipped: uploadsSkipped,
+    label: label
+  };
+}
+
+function viaLoginEndpoint(loginEndpoint) {
+  return async (username, password) => {
+    let client = Seed_Client$ReventlessSeed.make({
+      endpoint: loginEndpoint,
+      loginEndpoint: loginEndpoint,
+      username: username,
+      password: password
+    });
+    await Seed_Client$ReventlessSeed.login(client);
+    let token = Seed_Client$ReventlessSeed.currentToken(client);
+    if (token !== undefined) {
+      return token;
+    }
+    throw {
+      RE_EXN_ID: Seed_Types$ReventlessSeed.Failed,
+      _1: `login at ` + loginEndpoint + ` returned no token`,
+      Error: new Error()
+    };
+  };
+}
+
+function envOr(key, fallback) {
+  return Stdlib_Option.getOr(Seed_Prompt$ReventlessSeed.envValue(key), fallback);
+}
+
+function local(graphql, login, param) {
+  let endpoint = Stdlib_Option.getOr(graphql, Stdlib_Option.getOr(Seed_Prompt$ReventlessSeed.envValue("REVENTLESS_GRAPHQL_ENDPOINT"), "http://localhost:4000/graphql"));
+  let loginEndpoint = Stdlib_Option.getOr(login, Stdlib_Option.getOr(Seed_Prompt$ReventlessSeed.envValue("REVENTLESS_LOGIN_ENDPOINT"), "http://localhost:4000/__inmemory/login"));
+  return () => make("local", endpoint, viaLoginEndpoint(loginEndpoint), true);
+}
+
+export {
+  make,
+  viaLoginEndpoint,
+  envOr,
+  local,
+}
+/* Seed_Prompt-ReventlessSeed Not a pure module */

package/src/Seed_Prompt.res

@@ -0,0 +1,178 @@
+// One shared readline interface for every interactive prompt in a seed run.
+//
+// The reason this module exists: creating and closing a fresh `readline`
+// interface per prompt leaves NodeProcess.stdin paused after the first `close`, so the
+// second prompt (password after username) never fires and the run hangs. A
+// single interface, created lazily and closed exactly once, avoids that — and a
+// `muted` gate on its output lets password entry reuse the same interface
+// instead of opening a second one just to suppress the echo.
+//
+// Node bindings are declared here as typed externals; this package is
+// stdlib-only, so no `%raw`.
+
+open Seed_Types
+
+// ── Node bindings ─────────────────────────────────────────────────────────────
+
+type rl
+type rlOptions = {input: NodeProcess.stream, output: NodeProcess.stream, terminal?: bool}
+@module("node:readline") external createInterface: rlOptions => rl = "createInterface"
+@send external question: (rl, string, string => unit) => unit = "question"
+@send external closeRl: rl => unit = "close"
+@set external setWriteToOutput: (rl, string => unit) => unit = "_writeToOutput"
+
+// ── Shared interface ──────────────────────────────────────────────────────────
+
+// Created on first use, closed once via `close`. `muted` gates the echo so the
+// same interface serves both visible and hidden prompts.
+let rlRef: ref<option<rl>> = ref(None)
+let muted = ref(false)
+
+let iface = (): rl =>
+  switch rlRef.contents {
+  | Some(rl) => rl
+  | None =>
+    let rl = createInterface({input: NodeProcess.stdin, output: NodeProcess.stdout, terminal: true})
+    rl->setWriteToOutput(s =>
+      if !muted.contents {
+        NodeProcess.stdout->NodeProcess.write(s)
+      }
+    )
+    rlRef := Some(rl)
+    rl
+  }
+
+let close = (): unit =>
+  switch rlRef.contents {
+  | Some(rl) =>
+    rl->closeRl
+    rlRef := None
+    // Closing the interface is not enough: a terminal-mode readline leaves
+    // NodeProcess.stdin resumed and reffed, which keeps the event loop alive so the CLI
+    // never exits after seeding. Release it explicitly.
+    NodeProcess.stdin->NodeProcess.pause
+    NodeProcess.stdin->NodeProcess.unref
+  | None => ()
+  }
+
+// ── Env + TTY ─────────────────────────────────────────────────────────────────
+
+let envValue = (key: string): option<string> =>
+  switch NodeProcess.env->Dict.get(key) {
+  | Some(v) if v->String.trim != "" => Some(v->String.trim)
+  | _ => None
+  }
+
+let requireTty = (): unit =>
+  if !(NodeProcess.stdin->NodeProcess.isTTY->Option.getOr(false)) {
+    throw(
+      Failed(
+        "no TTY for an interactive prompt — set the documented SEED_* / REVENTLESS_DEMO_* " ++
+        "env vars to run non-interactively.",
+      ),
+    )
+  }
+
+// ── Prompts ───────────────────────────────────────────────────────────────────
+
+let ask = (query: string): promise<string> =>
+  Promise.make((resolve, _) => {
+    let rl = iface()
+    rl->question(query, answer => resolve(answer->String.trim))
+  })
+
+// Same interface, echo suppressed for the keystrokes. `question` writes the
+// prompt synchronously first (while unmuted), then muting is switched on so only
+// the typed characters are hidden — the canonical readline recipe, which keeps
+// the line editor's cursor state consistent (a manual write + empty `question`
+// left some terminals unable to read the next line).
+let askHidden = (query: string): promise<string> =>
+  Promise.make((resolve, _) => {
+    let rl = iface()
+    rl->question(query, answer => {
+      muted := false
+      NodeProcess.stdout->NodeProcess.write("\n")
+      resolve(answer)
+    })
+    muted := true
+  })
+
+/**
+ * Chooses one of `options` (a label paired with the value it selects).
+ *
+ * Auto-returns when there is a single option, so a lone data set or stack needs
+ * no keypress. `env` (e.g. `SEED_SET`) preselects by matching label or 1-based
+ * index, so CI runs without a TTY. Otherwise it prints a numbered menu.
+ */
+let select = async (
+  ~title: string,
+  ~options: array<(string, 'a)>,
+  ~env=?,
+): 'a =>
+  switch options {
+  | [(_, only)] => only
+  | _ =>
+    let fromEnv =
+      env
+      ->Option.flatMap(envValue)
+      ->Option.flatMap(v =>
+        switch options->Array.findIndex(((label, _)) => label == v) {
+        | -1 =>
+          switch Int.fromString(v) {
+          | Some(n) if n >= 1 && n <= options->Array.length => options->Array.get(n - 1)
+          | _ => None
+          }
+        | i => options->Array.get(i)
+        }
+      )
+    switch fromEnv {
+    | Some((_, value)) => value
+    | None =>
+      requireTty()
+      Console.log("")
+      Console.log(title)
+      Console.log("")
+      options->Array.forEachWithIndex(((label, _), i) =>
+        Console.log(`  ${(i + 1)->Int.toString}) ${label}`)
+      )
+      let rec pick = async (): 'a => {
+        let answer = await ask(`\nSelect [1-${(options->Array.length)->Int.toString}]: `)
+        switch Int.fromString(answer) {
+        | Some(n) if n >= 1 && n <= options->Array.length =>
+          let (_, value) = options->Array.getUnsafe(n - 1)
+          value
+        | _ =>
+          Console.log("  Not a valid choice.")
+          await pick()
+        }
+      }
+      await pick()
+    }
+  }
+
+/**
+ * Prompts for a username (visible) and password (echo muted).
+ *
+ * `REVENTLESS_DEMO_USER` / `REVENTLESS_DEMO_PASSWORD` skip the prompts. With
+ * `localDefaults`, empty input falls back to `admin`/`admin` — the dev login.
+ */
+let credentials = async (~localDefaults: bool=false): (string, string) => {
+  let username = switch envValue("REVENTLESS_DEMO_USER") {
+  | Some(u) => u
+  | None =>
+    requireTty()
+    let entered = await ask(localDefaults ? "Username [admin]: " : "Username: ")
+    entered == "" && localDefaults ? "admin" : entered
+  }
+  let password = switch envValue("REVENTLESS_DEMO_PASSWORD") {
+  | Some(p) => p
+  | None =>
+    requireTty()
+    let entered = await askHidden(localDefaults ? "Password [admin]: " : "Password: ")
+    entered == "" && localDefaults ? "admin" : entered
+  }
+  if username == "" || password == "" {
+    throw(Failed("username and password are required."))
+  }
+  (username, password)
+}

package/src/Seed_Prompt.res.mjs

@@ -0,0 +1,172 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_Int from "@rescript/runtime/lib/es6/Stdlib_Int.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Nodereadline from "node:readline";
+import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
+import * as Seed_Types$ReventlessSeed from "./Seed_Types.res.mjs";
+
+let rlRef = {
+  contents: undefined
+};
+
+let muted = {
+  contents: false
+};
+
+function iface() {
+  let rl = rlRef.contents;
+  if (rl !== undefined) {
+    return Primitive_option.valFromOption(rl);
+  }
+  let rl$1 = Nodereadline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: true
+  });
+  rl$1._writeToOutput = s => {
+    if (!muted.contents) {
+      process.stdout.write(s);
+      return;
+    }
+  };
+  rlRef.contents = Primitive_option.some(rl$1);
+  return rl$1;
+}
+
+function close() {
+  let rl = rlRef.contents;
+  if (rl !== undefined) {
+    Primitive_option.valFromOption(rl).close();
+    rlRef.contents = undefined;
+    process.stdin.pause();
+    process.stdin.unref();
+    return;
+  }
+}
+
+function envValue(key) {
+  let v = process.env[key];
+  if (v !== undefined && v.trim() !== "") {
+    return v.trim();
+  }
+}
+
+function requireTty() {
+  if (Stdlib_Option.getOr(process.stdin.isTTY, false)) {
+    return;
+  }
+  throw {
+    RE_EXN_ID: Seed_Types$ReventlessSeed.Failed,
+    _1: "no TTY for an interactive prompt — set the documented SEED_* / REVENTLESS_DEMO_* env vars to run non-interactively.",
+    Error: new Error()
+  };
+}
+
+function ask(query) {
+  return new Promise((resolve, param) => {
+    let rl = iface();
+    rl.question(query, answer => resolve(answer.trim()));
+  });
+}
+
+function askHidden(query) {
+  return new Promise((resolve, param) => {
+    let rl = iface();
+    rl.question(query, answer => {
+      muted.contents = false;
+      process.stdout.write("\n");
+      resolve(answer);
+    });
+    muted.contents = true;
+  });
+}
+
+async function select(title, options, env) {
+  if (options.length === 1) {
+    return options[0][1];
+  }
+  let fromEnv = Stdlib_Option.flatMap(Stdlib_Option.flatMap(env, envValue), v => {
+    let i = options.findIndex(param => param[0] === v);
+    if (i !== -1) {
+      return options[i];
+    }
+    let n = Stdlib_Int.fromString(v, undefined);
+    if (n !== undefined && n >= 1 && n <= options.length) {
+      return options[n - 1 | 0];
+    }
+  });
+  if (fromEnv !== undefined) {
+    return fromEnv[1];
+  }
+  requireTty();
+  console.log("");
+  console.log(title);
+  console.log("");
+  options.forEach((param, i) => {
+    console.log(`  ` + (i + 1 | 0).toString() + `) ` + param[0]);
+  });
+  let pick = async () => {
+    let answer = await ask(`\nSelect [1-` + options.length.toString() + `]: `);
+    let n = Stdlib_Int.fromString(answer, undefined);
+    if (n !== undefined) {
+      if (n >= 1 && n <= options.length) {
+        return options[n - 1 | 0][1];
+      } else {
+        console.log("  Not a valid choice.");
+        return await pick();
+      }
+    } else {
+      console.log("  Not a valid choice.");
+      return await pick();
+    }
+  };
+  return await pick();
+}
+
+async function credentials(localDefaultsOpt) {
+  let localDefaults = localDefaultsOpt !== undefined ? localDefaultsOpt : false;
+  let u = envValue("REVENTLESS_DEMO_USER");
+  let username;
+  if (u !== undefined) {
+    username = u;
+  } else {
+    requireTty();
+    let entered = await ask(localDefaults ? "Username [admin]: " : "Username: ");
+    username = entered === "" && localDefaults ? "admin" : entered;
+  }
+  let p = envValue("REVENTLESS_DEMO_PASSWORD");
+  let password;
+  if (p !== undefined) {
+    password = p;
+  } else {
+    requireTty();
+    let entered$1 = await askHidden(localDefaults ? "Password [admin]: " : "Password: ");
+    password = entered$1 === "" && localDefaults ? "admin" : entered$1;
+  }
+  if (username === "" || password === "") {
+    throw {
+      RE_EXN_ID: Seed_Types$ReventlessSeed.Failed,
+      _1: "username and password are required.",
+      Error: new Error()
+    };
+  }
+  return [
+    username,
+    password
+  ];
+}
+
+export {
+  rlRef,
+  muted,
+  iface,
+  close,
+  envValue,
+  requireTty,
+  ask,
+  askHidden,
+  select,
+  credentials,
+}
+/* node:readline Not a pure module */

package/src/Seed_Runner.res

@@ -2,11 +2,9 @@
 
 open Seed_Types
 
-@scope("process") @val external exit: int => unit = "exit"
-@scope("process") @val external env: dict<string> = "env"
 
 let envOr = (key: string, fallback: string): string =>
-  env->Dict.get(key)->Option.getOr(fallback)
+  NodeProcess.env->Dict.get(key)->Option.getOr(fallback)
 
 /** One line of progress per phase, so a slow run never looks hung. */
 let report = (line: string): unit => Console.log(`  ${line}`)
@@ -90,19 +88,52 @@ let warn = (warnings: array<string>): unit =>
     warnings->Array.forEach(w => Console.log(`  - ${w}`))
   }
 
+/**
+ * Pre-flight: refuse to seed onto a store that already holds data.
+ *
+ * The harness is a one-shot against a fresh store — a re-run would hit the
+ * domain's own duplicate rejections (`CategoryAlreadyExists`, …) and abort
+ * mid-phase. Catching it here, before any command is sent, turns that into an
+ * honest "nothing was written" startup abort instead of a misleading
+ * half-seeded one. It is the inverse of `verifyViews`: seeding refuses to start
+ * unless the store reads empty. Stops at the first non-empty probe view, so a
+ * populated store aborts after a single query.
+ */
+let assertStoreEmpty = async (client: Seed_Client.t, ~probeViews: array<string>): unit =>
+  for i in 0 to probeViews->Array.length - 1 {
+    switch probeViews->Array.get(i) {
+    | Some(name) =>
+      let count = await Seed_Client.countNodes(client, ~field=name)
+      if count > 0 {
+        throw(
+          Failed(
+            `the target store is not empty — "${name}" already holds ${count->Int.toString} row(s). Seeding is a one-shot against a fresh store; reset the store before re-running.`,
+          ),
+        )
+      }
+    | None => ()
+    }
+  }
+
 /**
  * Wraps a seed run. On failure it prints the cause and exits non-zero, saying
  * plainly that the store is now half-seeded — recovery is a reset, not a re-run.
  */
 let run = async (main: unit => promise<unit>): unit =>
-  try await main() catch {
+  try {
+    await main()
+    // Exit cleanly: HTTP keep-alive sockets (and, on the interactive path, the
+    // readline/stdin handle) can otherwise keep the event loop alive so the CLI
+    // appears to hang after a successful run.
+    NodeProcess.exit(0)
+  } catch {
   | Failed(message) =>
     Console.error("")
     Console.error("Seeding aborted — the store is now half-seeded; re-run against a")
     Console.error("fresh store once the cause below is fixed.")
     Console.error("")
     Console.error(message)
-    exit(1)
+    NodeProcess.exit(1)
   | exn =>
     Console.error("")
     Console.error("Seeding aborted with an unexpected error:")
@@ -110,5 +141,90 @@ let run = async (main: unit => promise<unit>): unit =>
     Console.error(
       exn->JsExn.fromException->Option.flatMap(JsExn.message)->Option.getOr("unknown"),
     )
-    exit(1)
+    NodeProcess.exit(1)
   }
+
+/**
+ * A named, seedable data set. `seed` owns everything domain-specific — the
+ * phases, `verifyViews`, the summary board — so the generic runner never sees
+ * domain detail. `label` is what the selection menu shows.
+ */
+type dataSet = {
+  name: string,
+  label: string,
+  seed: Seed_Connect.connection => promise<unit>,
+  // View names probed by the fresh-store guard before any command is sent; a
+  // non-empty one aborts the run at startup. Omit to skip the guard.
+  probeViews?: array<string>,
+}
+
+/**
+ * A failure before any command is sent — bad data-set selection, an
+ * unreachable/undeployed target, a login failure. Nothing was written, so this
+ * says so plainly rather than warning about a half-seeded store (which would
+ * send the user resetting a store the run never touched).
+ */
+let abortStartup = (message: string): unit => {
+  Seed_Prompt.close()
+  Console.error("")
+  Console.error("Seeding did not start — nothing was written. Fix the cause below and re-run.")
+  Console.error("")
+  Console.error(message)
+  NodeProcess.exit(1)
+}
+
+/**
+ * Top-level seed entry: choose a data set (auto when there is one, `SEED_SET`
+ * or a menu otherwise), connect, then hand the connection to the chosen set.
+ * Prompts are closed before seeding so the shared readline never lingers.
+ *
+ * Selection and connect run before any command is sent, so a failure there is
+ * reported as "did not start"; only failures inside the data set's own `seed`
+ * carry the half-seeded warning (via `run`).
+ */
+let seed = (~sets: array<dataSet>, ~connect: unit => promise<Seed_Connect.connection>): unit => {
+  let go = async () => {
+    let started = try {
+      let chosen = switch sets {
+      | [only] => only
+      | _ =>
+        switch Seed_Prompt.envValue("SEED_SET") {
+        | Some(wanted) =>
+          switch sets->Array.find(s => s.name == wanted) {
+          | Some(s) => s
+          | None =>
+            throw(
+              Failed(
+                `SEED_SET="${wanted}" matches no data set (have: ${sets
+                  ->Array.map(s => s.name)
+                  ->Array.join(", ")})`,
+              ),
+            )
+          }
+        | None =>
+          await Seed_Prompt.select(~title="Data set:", ~options=sets->Array.map(s => (s.label, s)))
+        }
+      }
+      let connection = await connect()
+      Seed_Prompt.close()
+      // Runs inside this pre-seed `try`, so refusing a non-empty store (or a
+      // failed probe query) is reported as "did not start", not "half-seeded".
+      await assertStoreEmpty(connection.client, ~probeViews=chosen.probeViews->Option.getOr([]))
+      Some((chosen, connection))
+    } catch {
+    | Failed(message) =>
+      abortStartup(message)
+      None
+    | exn =>
+      abortStartup(exn->JsExn.fromException->Option.flatMap(JsExn.message)->Option.getOr("unknown"))
+      None
+    }
+    switch started {
+    | None => () // unreachable: abortStartup has already exited
+    | Some((chosen, connection)) =>
+      heading(`Seeding "${chosen.label}" into ${connection.label}`)
+      await run(() => chosen.seed(connection))
+    }
+  }
+  go()->ignore
+}