@reventlessdev/reventless-seed 1.0.0-alpha.2 → 1.0.0-alpha.20

package/lib/bs/src/Seed_Users.res

@@ -0,0 +1,80 @@
+// The dev accounts a seed run can log in as, read from `.reventless/users.yaml`.
+//
+// Both platforms keep that file beside the package the seed runs from: locally
+// the in-memory auth adapter loads it at startup, and on AWS it is the record of
+// what was created in the Cognito pool. Either way it already holds the
+// credentials an operator would otherwise retype, so the credential prompt
+// offers its entries instead of asking for a password nobody remembers.
+//
+// Absence is normal and silent — the caller falls back to asking. Nothing here
+// throws: a missing, unreadable or malformed file yields no accounts.
+
+@module("yaml") external parseYaml: string => JSON.t = "parse"
+
+/** One account: what to log in as, and what to send with it. */
+type user = {username: string, password: string, groups: array<string>}
+
+let asString = (json: JSON.t): option<string> =>
+  switch json {
+  | String(s) => Some(s)
+  | _ => None
+  }
+
+let userOf = (json: JSON.t): option<user> =>
+  switch json {
+  | Object(obj) =>
+    switch (
+      obj->Dict.get("username")->Option.flatMap(asString),
+      obj->Dict.get("password")->Option.flatMap(asString),
+    ) {
+    | (Some(username), Some(password)) =>
+      let groups = switch obj->Dict.get("groups") {
+      | Some(JSON.Array(items)) => items->Array.filterMap(asString)
+      | _ => []
+      }
+      Some({username, password, groups})
+    | _ => None
+    }
+  | _ => None
+  }
+
+/**
+ * The accounts a users.yaml document defines, in the order it defines them —
+ * the order is what makes "the first one" a stable default.
+ *
+ * An entry without both a username and a password is skipped rather than
+ * rejected: the file is hand-maintained, and one incomplete entry should not
+ * cost the operator the rest of the list.
+ */
+let parseString = (yamlText: string): array<user> => {
+  let doc = try parseYaml(yamlText) catch {
+  | _ => JSON.Null
+  }
+  switch doc {
+  | Array(items) => items->Array.filterMap(userOf)
+  | _ => []
+  }
+}
+
+/** Where the file lives for the platform being seeded — the seed runs from that
+    package's directory, which is the same cwd the local auth adapter reads. */
+let defaultPath = (): string => NodePath.join([NodeProcess.cwd(), ".reventless", "users.yaml"])
+
+/**
+ * The accounts on disk, with the path they came from. `None` when there is no
+ * readable file with at least one usable account, which the caller reads as
+ * "ask for credentials instead".
+ */
+let load = (~path: option<string>=?): option<(string, array<user>)> => {
+  let file = path->Option.getOr(defaultPath())
+  let users = try {
+    NodeFs.existsSync(file) ? parseString(NodeFs.readFileSync(file)) : []
+  } catch {
+  | _ => []
+  }
+  users->Array.length == 0 ? None : Some((file, users))
+}
+
+/** Menu label: the username, plus whatever groups the file records for it. */
+let label = (u: user): string =>
+  u.groups->Array.length == 0 ? u.username : `${u.username}  [${u.groups->Array.join(", ")}]`

package/lib/bs/src/Seed_Users.res.mjs

@@ -0,0 +1,90 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Yaml from "yaml";
+import * as Nodefs from "node:fs";
+import * as Nodepath from "node:path";
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+
+function asString(json) {
+  if (typeof json === "string") {
+    return json;
+  }
+}
+
+function userOf(json) {
+  if (typeof json !== "object" || json === null || Array.isArray(json)) {
+    return;
+  }
+  let match = Stdlib_Option.flatMap(json["username"], asString);
+  let match$1 = Stdlib_Option.flatMap(json["password"], asString);
+  if (match === undefined) {
+    return;
+  }
+  if (match$1 === undefined) {
+    return;
+  }
+  let match$2 = json["groups"];
+  let groups = match$2 !== undefined ? (
+      Array.isArray(match$2) ? Stdlib_Array.filterMap(match$2, asString) : []
+    ) : [];
+  return {
+    username: match,
+    password: match$1,
+    groups: groups
+  };
+}
+
+function parseString(yamlText) {
+  let doc;
+  try {
+    doc = Yaml.parse(yamlText);
+  } catch (exn) {
+    doc = null;
+  }
+  if (Array.isArray(doc)) {
+    return Stdlib_Array.filterMap(doc, userOf);
+  } else {
+    return [];
+  }
+}
+
+function defaultPath() {
+  return Nodepath.join(process.cwd(), ".reventless", "users.yaml");
+}
+
+function load(path) {
+  let file = Stdlib_Option.getOr(path, defaultPath());
+  let users;
+  try {
+    users = Nodefs.existsSync(file) ? parseString(Nodefs.readFileSync(file, "utf8")) : [];
+  } catch (exn) {
+    users = [];
+  }
+  if (users.length === 0) {
+    return;
+  } else {
+    return [
+      file,
+      users
+    ];
+  }
+}
+
+function label(u) {
+  if (u.groups.length === 0) {
+    return u.username;
+  } else {
+    return u.username + `  [` + u.groups.join(", ") + `]`;
+  }
+}
+
+export {
+  asString,
+  userOf,
+  parseString,
+  defaultPath,
+  load,
+  label,
+}
+/* yaml Not a pure module */

package/lib/bs/tests/Seed_ClientTest.res

@@ -0,0 +1,157 @@
+open JestGlobals
+
+// A seed issues hundreds of commands against runtimes a preceding reset left
+// cold, so the endpoint faulting on one of them is a normal event rather than an
+// exceptional one. Before the retry, a single `InternalFailure` in that batch
+// aborted the run and left a half-seeded store that could only be recovered by a
+// full wipe and a re-run — for a request that would have succeeded on being
+// asked again.
+//
+// What makes the retry safe is the classifier, so that is what these pin. A
+// fault on the endpoint's side carries no information about the document and is
+// worth resending; anything that is an *answer* — a validation error, an unknown
+// field, a refused token — comes back identical however many times it is asked,
+// and resending it only delays the failure the operator needs to see.
+
+let errors = entries => JSON.Encode.array(entries->Array.map(JSON.Encode.object))
+
+let errorOfType = errorType =>
+  Dict.fromArray([("errorType", JSON.Encode.string(errorType))])
+
+describe("Seed_Client.isTransient:", () => {
+  testSync("resends a fault on the endpoint's own side", () =>
+    ["InternalFailure", "ServiceUnavailable", "Throttling", "TooManyRequestsException"]
+    ->Array.forEach(t =>
+      expect(Seed_Client.isTransient(errors([errorOfType(t)])))->toBe(true)
+    )
+  )
+
+  // The exact payload the seed aborted on.
+  testSync("resends the shape AppSync actually returned", () => {
+    let payload = JSON.parseOrThrow(`[{"errorType":"InternalFailure","message":"An internal failure occurred."}]`)
+    expect(Seed_Client.isTransient(payload))->toBe(true)
+  })
+
+  testSync("fails fast on an error that is an answer", () =>
+    ["ValidationException", "Unauthorized", "FieldUndefined"]->Array.forEach(t =>
+      expect(Seed_Client.isTransient(errors([errorOfType(t)])))->toBe(false)
+    )
+  )
+
+  // A real error sitting alongside a transient one still means the request was
+  // wrong, and resending it cannot make it right.
+  testSync("refuses to resend a batch that mixes a real error in", () =>
+    expect(
+      Seed_Client.isTransient(
+        errors([errorOfType("InternalFailure"), errorOfType("ValidationException")]),
+      ),
+    )->toBe(false)
+  )
+
+  // `Array.every` is vacuously true on an empty array, which would turn "the
+  // endpoint said errors but named none" into an endless resend.
+  testSync("treats an empty or untyped error list as final", () => {
+    expect(Seed_Client.isTransient(errors([])))->toBe(false)
+    expect(Seed_Client.isTransient(errors([Dict.fromArray([("message", JSON.Encode.string("boom"))])])))
+    ->toBe(false)
+    expect(Seed_Client.isTransient(JSON.Encode.null))->toBe(false)
+  })
+})
+
+// An account's listed groups are not what authorizes it — the token's are. Both
+// platforms narrow a token to the single role the caller last chose, so a seed
+// can log in as an account the user list shows as `[Admin, Shopper]` and present
+// a token carrying `Shopper` alone. The refusal that follows names the field and
+// not the caller, and the account list cannot explain it either. These pin the
+// reading-back that turns that into a sentence.
+
+let b64url = payload =>
+  payload
+  ->NodeBuffer.fromStringUtf8
+  ->NodeBuffer.toStringBase64Url
+
+let jwt = claims =>
+  `header.${b64url(JSON.stringify(JSON.Encode.object(Dict.fromArray(claims))))}.signature`
+
+let localToken = claims =>
+  `${b64url(JSON.stringify(JSON.Encode.object(Dict.fromArray(claims))))}.signature`
+
+let strings = values => JSON.Encode.array(values->Array.map(JSON.Encode.string))
+
+let clientWith = token => {
+  let c = Seed_Client.make(~config={endpoint: "http://example.invalid/graphql"})
+  c->Seed_Client.useToken(token)
+  c
+}
+
+describe("Seed_Client.effectiveGroups:", () => {
+  // A Cognito id token carries its payload in the second segment, a local dev
+  // token in the first. Neither platform should have to announce which it is.
+  testSync("reads the payload wherever the provider put it", () => {
+    expect(
+      clientWith(jwt([("cognito:groups", strings(["Admin", "Shopper"]))]))->Seed_Client.effectiveGroups,
+    )->toEqual(Some(["Admin", "Shopper"]))
+    expect(
+      clientWith(localToken([("groups", strings(["Merchandiser"]))]))->Seed_Client.effectiveGroups,
+    )->toEqual(Some(["Merchandiser"]))
+  })
+
+  // An opaque bearer is not an error — it just means this can add nothing, and
+  // the failure reports what it always did.
+  testSync("says nothing about a token it cannot read", () => {
+    expect(clientWith("not-a-token")->Seed_Client.effectiveGroups)->toEqual(None)
+    expect(
+      Seed_Client.make(~config={endpoint: "http://example.invalid/graphql"})
+      ->Seed_Client.effectiveGroups,
+    )->toEqual(None)
+  })
+})
+
+describe("Seed_Client.identitySummary:", () => {
+  // The case that cost the debugging: eligible in the user list, refused by the
+  // token. Naming what it was narrowed FROM is what points at the role switch.
+  testSync("names the membership a narrowed token gave up", () =>
+    expect(
+      clientWith(
+        jwt([
+          ("cognito:groups", strings(["Shopper"])),
+          ("availableRoles", JSON.Encode.string("Admin,Shopper")),
+        ]),
+      )->Seed_Client.identitySummary,
+    )->toEqual(Some("Shopper — narrowed to this role from Admin, Shopper"))
+  )
+
+  // An ordinary login is not narrowed and has nothing to explain.
+  testSync("stays quiet about an unnarrowed token", () =>
+    expect(
+      clientWith(jwt([("cognito:groups", strings(["Admin", "Shopper"]))]))
+      ->Seed_Client.identitySummary,
+    )->toEqual(Some("Admin, Shopper"))
+  )
+
+  // A token granting nothing reads as a sentence rather than an empty string.
+  testSync("says so when the token carries no groups at all", () =>
+    expect(
+      clientWith(jwt([("cognito:groups", strings([]))]))->Seed_Client.identitySummary,
+    )->toEqual(Some("no groups"))
+  )
+})
+
+describe("Seed_Client.isDenied:", () => {
+  // AppSync types it; the local server carries it in the message.
+  testSync("recognises a refusal in either platform's vocabulary", () => {
+    expect(Seed_Client.isDenied(errors([errorOfType("Unauthorized")])))->toBe(true)
+    expect(
+      Seed_Client.isDenied(
+        errors([Dict.fromArray([("message", JSON.Encode.string("Not Authorized to access X"))])]),
+      ),
+    )->toBe(true)
+  })
+
+  // Attaching an identity to an unrelated failure would point the reader at the
+  // wrong thing.
+  testSync("leaves every other failure alone", () => {
+    expect(Seed_Client.isDenied(errors([errorOfType("ValidationException")])))->toBe(false)
+    expect(Seed_Client.isDenied(errors([])))->toBe(false)
+  })
+})

package/lib/bs/tests/Seed_ClientTest.res.mjs

@@ -0,0 +1,167 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Seed_Client$ReventlessSeed from "../src/Seed_Client.res.mjs";
+
+function errors(entries) {
+  return entries.map(prim => prim);
+}
+
+function errorOfType(errorType) {
+  return Object.fromEntries([[
+      "errorType",
+      errorType
+    ]]);
+}
+
+globalThis.describe("Seed_Client.isTransient:", () => {
+  globalThis.test("resends a fault on the endpoint's own side", () => {
+    [
+      "InternalFailure",
+      "ServiceUnavailable",
+      "Throttling",
+      "TooManyRequestsException"
+    ].forEach(t => {
+      let entries = [errorOfType(t)];
+      globalThis.expect(Seed_Client$ReventlessSeed.isTransient(entries.map(prim => prim))).toBe(true);
+    });
+  });
+  globalThis.test("resends the shape AppSync actually returned", () => {
+    let payload = JSON.parse(`[{"errorType":"InternalFailure","message":"An internal failure occurred."}]`);
+    globalThis.expect(Seed_Client$ReventlessSeed.isTransient(payload)).toBe(true);
+  });
+  globalThis.test("fails fast on an error that is an answer", () => {
+    [
+      "ValidationException",
+      "Unauthorized",
+      "FieldUndefined"
+    ].forEach(t => {
+      let entries = [errorOfType(t)];
+      globalThis.expect(Seed_Client$ReventlessSeed.isTransient(entries.map(prim => prim))).toBe(false);
+    });
+  });
+  globalThis.test("refuses to resend a batch that mixes a real error in", () => {
+    let entries = [
+      errorOfType("InternalFailure"),
+      errorOfType("ValidationException")
+    ];
+    globalThis.expect(Seed_Client$ReventlessSeed.isTransient(entries.map(prim => prim))).toBe(false);
+  });
+  globalThis.test("treats an empty or untyped error list as final", () => {
+    globalThis.expect(Seed_Client$ReventlessSeed.isTransient([].map(prim => prim))).toBe(false);
+    let entries = [Object.fromEntries([[
+          "message",
+          "boom"
+        ]])];
+    globalThis.expect(Seed_Client$ReventlessSeed.isTransient(entries.map(prim => prim))).toBe(false);
+    globalThis.expect(Seed_Client$ReventlessSeed.isTransient(null)).toBe(false);
+  });
+});
+
+function b64url(payload) {
+  return Buffer.from(payload, "utf8").toString("base64url");
+}
+
+function jwt(claims) {
+  let payload = JSON.stringify(Object.fromEntries(claims));
+  return `header.` + Buffer.from(payload, "utf8").toString("base64url") + `.signature`;
+}
+
+function localToken(claims) {
+  let payload = JSON.stringify(Object.fromEntries(claims));
+  return Buffer.from(payload, "utf8").toString("base64url") + `.signature`;
+}
+
+function strings(values) {
+  return values.map(prim => prim);
+}
+
+function clientWith(token) {
+  let c = Seed_Client$ReventlessSeed.make({
+    endpoint: "http://example.invalid/graphql"
+  });
+  Seed_Client$ReventlessSeed.useToken(c, token);
+  return c;
+}
+
+globalThis.describe("Seed_Client.effectiveGroups:", () => {
+  globalThis.test("reads the payload wherever the provider put it", () => {
+    globalThis.expect(Seed_Client$ReventlessSeed.effectiveGroups(clientWith(jwt([[
+        "cognito:groups",
+        [
+          "Admin",
+          "Shopper"
+        ].map(prim => prim)
+      ]])))).toEqual([
+      "Admin",
+      "Shopper"
+    ]);
+    globalThis.expect(Seed_Client$ReventlessSeed.effectiveGroups(clientWith(localToken([[
+        "groups",
+        ["Merchandiser"].map(prim => prim)
+      ]])))).toEqual(["Merchandiser"]);
+  });
+  globalThis.test("says nothing about a token it cannot read", () => {
+    globalThis.expect(Seed_Client$ReventlessSeed.effectiveGroups(clientWith("not-a-token"))).toEqual(undefined);
+    globalThis.expect(Seed_Client$ReventlessSeed.effectiveGroups(Seed_Client$ReventlessSeed.make({
+      endpoint: "http://example.invalid/graphql"
+    }))).toEqual(undefined);
+  });
+});
+
+globalThis.describe("Seed_Client.identitySummary:", () => {
+  globalThis.test("names the membership a narrowed token gave up", () => {
+    globalThis.expect(Seed_Client$ReventlessSeed.identitySummary(clientWith(jwt([
+      [
+        "cognito:groups",
+        ["Shopper"].map(prim => prim)
+      ],
+      [
+        "availableRoles",
+        "Admin,Shopper"
+      ]
+    ])))).toEqual("Shopper — narrowed to this role from Admin, Shopper");
+  });
+  globalThis.test("stays quiet about an unnarrowed token", () => {
+    globalThis.expect(Seed_Client$ReventlessSeed.identitySummary(clientWith(jwt([[
+        "cognito:groups",
+        [
+          "Admin",
+          "Shopper"
+        ].map(prim => prim)
+      ]])))).toEqual("Admin, Shopper");
+  });
+  globalThis.test("says so when the token carries no groups at all", () => {
+    globalThis.expect(Seed_Client$ReventlessSeed.identitySummary(clientWith(jwt([[
+        "cognito:groups",
+        [].map(prim => prim)
+      ]])))).toEqual("no groups");
+  });
+});
+
+globalThis.describe("Seed_Client.isDenied:", () => {
+  globalThis.test("recognises a refusal in either platform's vocabulary", () => {
+    let entries = [errorOfType("Unauthorized")];
+    globalThis.expect(Seed_Client$ReventlessSeed.isDenied(entries.map(prim => prim))).toBe(true);
+    let entries$1 = [Object.fromEntries([[
+          "message",
+          "Not Authorized to access X"
+        ]])];
+    globalThis.expect(Seed_Client$ReventlessSeed.isDenied(entries$1.map(prim => prim))).toBe(true);
+  });
+  globalThis.test("leaves every other failure alone", () => {
+    let entries = [errorOfType("ValidationException")];
+    globalThis.expect(Seed_Client$ReventlessSeed.isDenied(entries.map(prim => prim))).toBe(false);
+    globalThis.expect(Seed_Client$ReventlessSeed.isDenied([].map(prim => prim))).toBe(false);
+  });
+});
+
+export {
+  errors,
+  errorOfType,
+  b64url,
+  jwt,
+  localToken,
+  strings,
+  clientWith,
+}
+/*  Not a pure module */

package/lib/bs/tests/Seed_PromptTest.res

@@ -0,0 +1,59 @@
+open JestGlobals
+
+// `isAffirmative` is the one vocabulary for "yes", shared by a typed `[y/N]`
+// reply and by the env var that stands in for it on a run with no terminal.
+//
+// It exists because those two drifted: the prompt took `y`, the env var took
+// only the literals `1` and `yes`, and every other value — `y` included, and an
+// explicit `no` with it — fell through to the interactive branch, which throws
+// when there is no TTY. So the variable that exists to make the tool
+// non-interactive had two spellings that worked and a crash for the rest.
+//
+// The suite is written around the shape of that bug rather than around the
+// function: what must confirm, what must decline, and — the case that actually
+// broke CI — that declining is a normal answer and not a fall-through.
+
+describe("Seed_Prompt.isAffirmative:", () => {
+  testSync("takes the three spellings of yes", () => {
+    ["y", "yes", "1"]->Array.forEach(v =>
+      expect(Seed_Prompt.isAffirmative(v))->Expect.toBe(true)
+    )
+  })
+
+  // A prompt that prints `[y/N]` invites a capital as readily as a lowercase
+  // one, and an env var set by hand is written however the hand felt.
+  testSync("ignores case, so Y and YES answer as y does", () => {
+    ["Y", "Yes", "YES"]->Array.forEach(v =>
+      expect(Seed_Prompt.isAffirmative(v))->Expect.toBe(true)
+    )
+  })
+
+  testSync("ignores surrounding space", () => {
+    [" y", "y ", "  yes  "]->Array.forEach(v =>
+      expect(Seed_Prompt.isAffirmative(v))->Expect.toBe(true)
+    )
+  })
+
+  // The half that matters most: every one of these is an ANSWER, and the caller
+  // reads it as "no". None may be mistaken for "nothing was said", which is what
+  // sent the old code to a prompt it could not open.
+  testSync("declines every spelling of no, capital N included", () => {
+    ["n", "N", "no", "No", "NO"]->Array.forEach(v =>
+      expect(Seed_Prompt.isAffirmative(v))->Expect.toBe(false)
+    )
+  })
+
+  testSync("declines anything it does not recognise", () => {
+    ["", "  ", "0", "true", "yep", "y.", "yesplease", "affirmative"]->Array.forEach(v =>
+      expect(Seed_Prompt.isAffirmative(v))->Expect.toBe(false)
+    )
+  })
+
+  // `true` is deliberately absent from the vocabulary above. Named here so that
+  // adding it is a decision someone takes against a failing test rather than a
+  // kindness someone slips in: the prompt this stands in for asks `[y/N]`, and a
+  // reply nobody would type at that prompt should not work around it either.
+  testSync("does not quietly grow a fourth spelling", () => {
+    expect(Seed_Prompt.isAffirmative("true"))->Expect.toBe(false)
+  })
+})

package/lib/bs/tests/Seed_PromptTest.res.mjs

@@ -0,0 +1,63 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Seed_Prompt$ReventlessSeed from "../src/Seed_Prompt.res.mjs";
+
+globalThis.describe("Seed_Prompt.isAffirmative:", () => {
+  globalThis.test("takes the three spellings of yes", () => {
+    [
+      "y",
+      "yes",
+      "1"
+    ].forEach(v => {
+      globalThis.expect(Seed_Prompt$ReventlessSeed.isAffirmative(v)).toBe(true);
+    });
+  });
+  globalThis.test("ignores case, so Y and YES answer as y does", () => {
+    [
+      "Y",
+      "Yes",
+      "YES"
+    ].forEach(v => {
+      globalThis.expect(Seed_Prompt$ReventlessSeed.isAffirmative(v)).toBe(true);
+    });
+  });
+  globalThis.test("ignores surrounding space", () => {
+    [
+      " y",
+      "y ",
+      "  yes  "
+    ].forEach(v => {
+      globalThis.expect(Seed_Prompt$ReventlessSeed.isAffirmative(v)).toBe(true);
+    });
+  });
+  globalThis.test("declines every spelling of no, capital N included", () => {
+    [
+      "n",
+      "N",
+      "no",
+      "No",
+      "NO"
+    ].forEach(v => {
+      globalThis.expect(Seed_Prompt$ReventlessSeed.isAffirmative(v)).toBe(false);
+    });
+  });
+  globalThis.test("declines anything it does not recognise", () => {
+    [
+      "",
+      "  ",
+      "0",
+      "true",
+      "yep",
+      "y.",
+      "yesplease",
+      "affirmative"
+    ].forEach(v => {
+      globalThis.expect(Seed_Prompt$ReventlessSeed.isAffirmative(v)).toBe(false);
+    });
+  });
+  globalThis.test("does not quietly grow a fourth spelling", () => {
+    globalThis.expect(Seed_Prompt$ReventlessSeed.isAffirmative("true")).toBe(false);
+  });
+});
+
+/*  Not a pure module */