@reventlessdev/reventless-spec 3.0.0-alpha.124 → 3.0.0-alpha.126

package/src/generator/TraitManifestCli.res

@@ -0,0 +1,138 @@
+// Derive a trait's listing metadata from the trait itself.
+//
+// Usage: trait-manifest <trait-package> --out <file>
+//
+// The old design had a hand-written `trait.yaml`. Everything in it is already a
+// fact somewhere typed, so this reads those facts instead: identity from the
+// package, needs from the value the trait exports, and the config surface from
+// the emitter's own sury schema.
+//
+// Nothing here knows a trait's vocabulary. Both modules are resolved by the name
+// the trait is given and dynamically imported, exactly as `graft-trait` reaches a
+// scaffold — so `reventless-spec` still depends on no trait.
+
+@val external dynImport: string => promise<'a> = "import"
+
+type scaffoldExports = {configSchema: S.t<unknown>}
+type traitExports = {capabilityNeeds: array<CapabilityNeed.t>}
+
+let fail = (message: string) => {
+  Console.error("trait-manifest: " ++ message)
+  NodeProcess.exit(1)
+}
+
+let usage = `Usage: trait-manifest <trait-package> --out <file>
+
+  <trait-package>  the installed trait, e.g. @reventlessdev/trait-attachments
+  --out            where to write the manifest
+
+  Everything is read from the trait: identity from its package.json, capability
+  needs from the value it exports, the config surface from its emitter's schema.
+  There is nothing to hand-write and nothing to keep in step.`
+
+/** `@scope/trait-address-geocoding` → `AddressGeocoding`. The same derivation
+    `graft-trait` and `certify-trait` do, for the same reason: a trait's module
+    names follow from its package name, so nothing has to be configured. */
+let moduleBase = (traitPackage: string) =>
+  traitPackage
+  ->String.split("/")
+  ->Array.last
+  ->Option.getOr("")
+  ->String.replace("trait-", "")
+  ->String.split("-")
+  ->Array.map(part =>
+    part->String.charAt(0)->String.toUpperCase ++
+      part->String.slice(~start=1, ~end=part->String.length)
+  )
+  ->Array.join("")
+
+let resolveFrom = (specifier: string) =>
+  try Some(
+    NodeModule.createRequire(NodeProcess.cwd() ++ "/index.js")->NodeModule.requireResolve(specifier),
+  ) catch {
+  | _ => None
+  }
+
+let readPackageField = (packageJson: JSON.t, field: string, fallback: string) =>
+  packageJson
+  ->JSON.Decode.object
+  ->Option.flatMap(o => o->Dict.get(field))
+  ->Option.flatMap(JSON.Decode.string)
+  ->Option.getOr(fallback)
+
+let main = async () => {
+  let argv = NodeProcess.argv->Array.slice(~start=2, ~end=NodeProcess.argv->Array.length)
+  let flag = key =>
+    switch argv->Array.indexOf("--" ++ key) {
+    | -1 => None
+    | i => argv->Array.get(i + 1)
+    }
+
+  switch (argv->Array.get(0), flag("out")) {
+  | (None, _) | (Some(""), _) | (Some("--help"), _) | (Some("-h"), _) => {
+      Console.log(usage)
+      NodeProcess.exit(argv->Array.length == 0 ? 1 : 0)
+    }
+  | (Some(_), None) => fail("--out is required.\n\n" ++ usage)
+  | (Some(traitPackage), Some(out)) => {
+      let base = moduleBase(traitPackage)
+
+      let packageJson = switch resolveFrom(`${traitPackage}/package.json`) {
+      | None =>
+        fail(
+          `${traitPackage} is not installed here. A manifest is derived from the trait, so ` ++
+          `the trait has to be resolvable.`,
+        )
+        JSON.Encode.null
+      | Some(path) => NodeFs.readFileSync(path)->JSON.parseOrThrow
+      }
+
+      // The trait's entry module, for what it needs. Absent is refused rather
+      // than defaulted to `[]`: "needs nothing" and "nobody said" are different
+      // claims, and a listing that could not tell them apart would quietly
+      // publish the second as the first.
+      let traitModule: traitExports = switch resolveFrom(`${traitPackage}/src/${base}.res.mjs`) {
+      | None =>
+        fail(
+          `${traitPackage} exports no ${base} module, so its capability needs cannot be read.\n` ++
+          `  A trait states them as a value — an empty array if it brokers nothing — because ` ++
+          `an unstated need fails silently at run time.`,
+        )
+        %raw(`undefined`)
+      | Some(path) => await dynImport(NodeUrl.pathToFileURL(path)["href"])
+      }
+
+      // The emitter is optional: a trait whose graft is all patches has nothing
+      // to write, and says so here rather than by failing when someone tries.
+      let scaffold: option<scaffoldExports> = switch resolveFrom(
+        `${traitPackage}/src/${base}_Scaffold.res.mjs`,
+      ) {
+      | None => None
+      | Some(path) => Some(await dynImport(NodeUrl.pathToFileURL(path)["href"]))
+      }
+
+      let manifest: TraitManifest.t = {
+        trait: readPackageField(packageJson, "name", traitPackage),
+        version: readPackageField(packageJson, "version", "0.0.0"),
+        description: readPackageField(packageJson, "description", ""),
+        license: readPackageField(packageJson, "license", ""),
+        capabilities: traitModule.capabilityNeeds->Array.map(CapabilityNeed.toString),
+        config: switch scaffold {
+        | Some({configSchema}) => TraitManifest.configFieldsOf(configSchema)
+        | None => []
+        },
+        scaffolded: scaffold->Option.isSome,
+      }
+
+      NodeFs.writeFileSync(out, manifest->TraitManifest.render)
+      Console.log(
+        `trait-manifest: ${manifest.trait}@${manifest.version} — ` ++
+        `${(manifest.capabilities->Array.length)->Int.toString} capabilit(ies), ` ++
+        `${(manifest.config->Array.length)->Int.toString} config field(s)`,
+      )
+      Console.log(`Wrote: ${out}`)
+    }
+  }
+}
+
+main()->Promise.ignore

package/src/generator/TraitManifestCli.res.mjs

@@ -0,0 +1,105 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Nodefs from "node:fs";
+import * as Nodeurl from "node:url";
+import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
+import * as Nodemodule from "node:module";
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as TraitManifest$Reventless from "../components/TraitManifest.res.mjs";
+import * as CapabilityNeed$Reventless from "../semantic/CapabilityNeed.res.mjs";
+
+function fail(message) {
+  console.error("trait-manifest: " + message);
+  process.exit(1);
+}
+
+let usage = `Usage: trait-manifest <trait-package> --out <file>
+
+  <trait-package>  the installed trait, e.g. @reventlessdev/trait-attachments
+  --out            where to write the manifest
+
+  Everything is read from the trait: identity from its package.json, capability
+  needs from the value it exports, the config surface from its emitter's schema.
+  There is nothing to hand-write and nothing to keep in step.`;
+
+function moduleBase(traitPackage) {
+  return Stdlib_Option.getOr(Stdlib_Array.last(traitPackage.split("/")), "").replace("trait-", "").split("-").map(part => part.charAt(0).toUpperCase() + part.slice(1, part.length)).join("");
+}
+
+function resolveFrom(specifier) {
+  try {
+    return Nodemodule.createRequire(process.cwd() + "/index.js").resolve(specifier);
+  } catch (exn) {
+    return;
+  }
+}
+
+function readPackageField(packageJson, field, fallback) {
+  return Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(packageJson), o => o[field]), Stdlib_JSON.Decode.string), fallback);
+}
+
+async function main() {
+  let argv = process.argv.slice(2, process.argv.length);
+  let flag = key => {
+    let i = argv.indexOf("--" + key);
+    if (i !== -1) {
+      return argv[i + 1 | 0];
+    }
+  };
+  let match = argv[0];
+  let match$1 = flag("out");
+  if (match !== undefined) {
+    switch (match) {
+      case "" :
+      case "--help" :
+      case "-h" :
+        break;
+      default:
+        if (match$1 === undefined) {
+          return fail("--out is required.\n\n" + usage);
+        }
+        let base = moduleBase(match);
+        let path = resolveFrom(match + `/package.json`);
+        let packageJson = path !== undefined ? JSON.parse(Nodefs.readFileSync(path, "utf8")) : (fail(match + ` is not installed here. A manifest is derived from the trait, so the trait has to be resolvable.`), null);
+        let path$1 = resolveFrom(match + `/src/` + base + `.res.mjs`);
+        let traitModule = path$1 !== undefined ? await import(Nodeurl.pathToFileURL(path$1).href) : (fail(match + ` exports no ` + base + ` module, so its capability needs cannot be read.\n  A trait states them as a value — an empty array if it brokers nothing — because an unstated need fails silently at run time.`), undefined);
+        let path$2 = resolveFrom(match + `/src/` + base + `_Scaffold.res.mjs`);
+        let scaffold = path$2 !== undefined ? await import(Nodeurl.pathToFileURL(path$2).href) : undefined;
+        let manifest_trait = readPackageField(packageJson, "name", match);
+        let manifest_version = readPackageField(packageJson, "version", "0.0.0");
+        let manifest_description = readPackageField(packageJson, "description", "");
+        let manifest_license = readPackageField(packageJson, "license", "");
+        let manifest_capabilities = traitModule.capabilityNeeds.map(CapabilityNeed$Reventless.toString);
+        let manifest_config = scaffold !== undefined ? TraitManifest$Reventless.configFieldsOf(scaffold.configSchema) : [];
+        let manifest_scaffolded = Stdlib_Option.isSome(scaffold);
+        let manifest = {
+          trait: manifest_trait,
+          version: manifest_version,
+          description: manifest_description,
+          license: manifest_license,
+          capabilities: manifest_capabilities,
+          config: manifest_config,
+          scaffolded: manifest_scaffolded
+        };
+        Nodefs.writeFileSync(match$1, TraitManifest$Reventless.render(manifest), "utf8");
+        console.log(`trait-manifest: ` + manifest_trait + `@` + manifest_version + ` — ` + (manifest_capabilities.length.toString() + ` capabilit(ies), `) + (manifest_config.length.toString() + ` config field(s)`));
+        console.log(`Wrote: ` + match$1);
+        return;
+    }
+  }
+  console.log(usage);
+  process.exit(argv.length === 0 ? 1 : 0);
+}
+
+main();
+
+export {
+  fail,
+  usage,
+  moduleBase,
+  resolveFrom,
+  readPackageField,
+  main,
+}
+/*  Not a pure module */

package/src/semantic/Capabilities.res

@@ -5,9 +5,9 @@ A plugin is provider-agnostic: it depends on `reventless-spec`, never on
 `reventless-aws`, so it cannot name Amazon Location — and it should not want to.
 What it can do is receive a function that geocodes, and let whoever assembled the
 runtime decide what is on the other end. The same capability a client reaches
-through a GraphQL field, plugin code reaches through here; the object store
-already works this way, with `Upload_Presign` on one side and an injected
-`Offload.resolve(~fetch)` on the other.
+through a GraphQL field, plugin code reaches through here. (The object store has
+only the client half so far — `Upload_Presign`; `Offload.resolve(~fetch)` has no
+injected caller yet, and the accessor for it belongs in this record.)
 
 Injected rather than looked up, and required rather than optional, because the
 alternative is a slot filled at cold start that nothing enforces: ES modules
@@ -24,6 +24,9 @@ leaves every `translate` reading `capabilities.geocode` untouched.
 type t = {
   /** Turn an address into ranked candidates. See `Geocoding.search`. */
   geocode: Geocoding.search,
+  /** Send a message to a person, and say which channels this deployment can
+      attempt at all. See `Messaging.provider`. */
+  messaging: Messaging.provider,
 }
 
 /**
@@ -40,4 +43,17 @@ a blank.
 */
 let none: t = {
   geocode: async (~text as _) => Error(Unavailable("no geocoder is configured for this platform")),
+  // `channels: []` and a retryable `send` say two different true things, and both
+  // are needed. The empty list is what a deploy gate reads and what a preference
+  // centre renders — offering a channel nothing can deliver on would collect a
+  // subscription that never arrives. The send stays `Unavailable` rather than
+  // `UnsupportedChannel` because a caller that got this far is looking at a
+  // deployment gap, not at a fact about the recipient, and abandoning the message
+  // would record the second.
+  messaging: {
+    channels: [],
+    send: async (~recipient as _, ~message as _) => Error(
+      Unavailable("no messaging provider is configured for this platform"),
+    ),
+  },
 }

package/src/semantic/Capabilities.res.mjs

@@ -1,16 +1,32 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
 
-let none = {
-  geocode: async param => ({
+async function none_geocode(param) {
+  return {
     TAG: "Error",
     _0: {
       TAG: "Unavailable",
       _0: "no geocoder is configured for this platform"
     }
+  };
+}
+
+let none_messaging = {
+  channels: [],
+  send: async (param, param$1) => ({
+    TAG: "Error",
+    _0: {
+      TAG: "Unavailable",
+      _0: "no messaging provider is configured for this platform"
+    }
   })
 };
 
+let none = {
+  geocode: none_geocode,
+  messaging: none_messaging
+};
+
 export {
   none,
 }

package/src/semantic/CapabilityNeed.res

@@ -0,0 +1,81 @@
+/**
+A platform capability a component declares it needs, in the plugin's own
+vocabulary.
+
+`Capabilities.t` is what a slice is *handed*; this is what it says it will
+reach for. The two are separate because they are read at different times: the
+record is injected at run time, the declaration is read at build time by
+`emit-capabilities` and at deploy time by the coverage gate, neither of which
+can run a `translate`.
+
+**Object stores are not here.** A store need is already declared by the field
+that carries `@storageRef`, travels as `pluginStructure.requiredStores`, and is
+identified by `(plugin, store)` rather than by a capability alone. This type
+carries the needs that no field can express.
+
+A real variant, so a trait exports its need as a value the compiler checks
+rather than a string a README repeats.
+*/
+type t =
+  | Geocoding
+  | /** Sending a message to a person, reached through `Capabilities.messaging`.
+        One need however many channels the platform provisions — which channels
+        those are is a runtime answer the provider publishes, not a second
+        declaration, because a plugin that named `Sms` would fail a deploy it
+        could have run on email. */
+  Messaging
+
+/** The spelling carried in `pluginStructure` and in `capabilities.json`.
+    Persisted structures hold strings, not enum members, so a plugin built
+    against a newer framework still decodes in an older reader. */
+let toString = (need: t): string =>
+  switch need {
+  | Geocoding => "Geocoding"
+  | Messaging => "Messaging"
+  }
+
+/** The inverse, for readers of a persisted structure or a committed manifest.
+    `None` for a capability this build does not know — a newer plugin's need is
+    reported as unrecognised, never silently dropped into a known arm. */
+let fromString = (name: string): option<t> =>
+  switch name {
+  | "Geocoding" => Some(Geocoding)
+  | "Messaging" => Some(Messaging)
+  | _ => None
+  }
+
+/** One declared need the deployment does not provision, with the component that
+    declared it — a deploy refusal has to name what to go and look at. */
+type unmet = {need: t, component: string}
+
+/**
+Declared capability needs a platform does not provision.
+
+`declared` is `pluginStructure.requiredCapabilities` as persisted: `(capability,
+component)` pairs whose capability is a string, because a structure is replayed
+from an event log. A name this build does not recognise is **skipped** — it
+belongs to a newer framework, and refusing a deploy over a capability this code
+cannot evaluate would be a guess dressed as a check.
+
+Only what was declared. A plugin that declares nothing is unaffected: an
+unprovisioned capability it never named degrades exactly as it always has, which
+is the modelled outcome for a deployment that simply does not have one.
+*/
+let unmet = (~declared: array<(string, string)>, ~provisioned: array<t>): array<unmet> =>
+  declared->Array.filterMap((((capability, component))) =>
+    switch fromString(capability) {
+    | Some(need) if !(provisioned->Array.includes(need)) => Some({need, component})
+    | _ => None
+    }
+  )
+
+/** The refusal text: what is missing, who asked for it, and what silently happens
+    if it is not provisioned — the symptom is a wrong verdict, never an error. */
+let unmetMessage = (unmet: array<unmet>): string =>
+  `Plugin declares capabilit(ies) the platform does not provision: ` ++
+  `${unmet
+    ->Array.map(u => `${toString(u.need)} (${u.component})`)
+    ->Array.join(", ")}.\n` ++
+  `  Provision them in the platform stack and redeploy the platform first.\n` ++
+  `  Without it every call answers Unavailable, the slice exhausts its retries, and a ` ++
+  `permanent verdict is recorded against data that is fine — no error anywhere.`

package/src/semantic/CapabilityNeed.res.mjs

@@ -0,0 +1,46 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+
+function toString(need) {
+  if (need === "Geocoding") {
+    return "Geocoding";
+  } else {
+    return "Messaging";
+  }
+}
+
+function fromString(name) {
+  switch (name) {
+    case "Geocoding" :
+      return "Geocoding";
+    case "Messaging" :
+      return "Messaging";
+    default:
+      return;
+  }
+}
+
+function unmet(declared, provisioned) {
+  return Stdlib_Array.filterMap(declared, param => {
+    let need = fromString(param[0]);
+    if (need !== undefined && !provisioned.includes(need)) {
+      return {
+        need: need,
+        component: param[1]
+      };
+    }
+  });
+}
+
+function unmetMessage(unmet) {
+  return `Plugin declares capabilit(ies) the platform does not provision: ` + (unmet.map(u => toString(u.need) + ` (` + u.component + `)`).join(", ") + `.\n`) + `  Provision them in the platform stack and redeploy the platform first.\n  Without it every call answers Unavailable, the slice exhausts its retries, and a permanent verdict is recorded against data that is fine — no error anywhere.`;
+}
+
+export {
+  toString,
+  fromString,
+  unmet,
+  unmetMessage,
+}
+/* No side effect */

package/src/semantic/Messaging.res

@@ -0,0 +1,127 @@
+/**
+Sending a message to a person, and deciding whether to try again.
+
+The transport is provider-specific and lives with its provider. What is here is
+provider-neutral: who a message can be addressed to, what a send can answer, the
+retry rule — decided once, so no transport invents its own.
+
+## One value carries the channel and the address
+
+A `(channel, address)` pair can be built wrong: `Sms` beside an email address
+compiles and fails at the provider. `recipient` fuses them, so the wrong pair
+does not exist, and the channel is read back off the value that carries it.
+*/
+
+/** A delivery route. The selector a recipient chooses per notification kind, and
+    the granularity a platform provisions at. */
+type channel =
+  | Email
+  | Sms
+  | Push
+
+/** An addressed recipient: the channel and the address it needs, inseparable.
+    Each address is the branded scalar for its channel, so an unparseable one is
+    refused where it is built rather than by the provider. */
+type recipient =
+  | ToEmail(Email.t)
+  | ToSms(Phone.t)
+  | /** The token the device registered with the push service. Opaque and
+        provider-shaped — unlike an address, nobody else has a grammar for it. */
+  ToPush({deviceToken: string})
+
+/** The channel a recipient is addressed on. */
+let channelOf = (recipient: recipient): channel =>
+  switch recipient {
+  | ToEmail(_) => Email
+  | ToSms(_) => Sms
+  | ToPush(_) => Push
+  }
+
+/** The channel's name, for a message a human reads and for a preference key. */
+let channelToString = (channel: channel): string =>
+  switch channel {
+  | Email => "Email"
+  | Sms => "Sms"
+  | Push => "Push"
+  }
+
+/**
+What to say.
+
+`subject` is carried for the channels that have one — an email header, a push
+notification's title — and ignored by those that do not. Optional rather than an
+empty string, so "this message has no subject" and "its subject is blank" stay
+distinguishable.
+*/
+type message = {subject?: string, body: string}
+
+/** The provider accepted the message. `ref` is its own id for it — what a
+    support conversation about a missing message is conducted with, and the only
+    thing a caller can record that the provider will recognise. */
+type receipt = {ref: string}
+
+/**
+Why a send produced no receipt.
+
+Three constructors because the retry decision turns on the distinction, and
+getting it wrong is expensive in both directions: retrying a refused address
+burns the budget on an outcome that will not change, and abandoning a transient
+outage writes off a message that would have gone.
+*/
+type failure =
+  | /** The provider could not be reached, or refused the call. Retry. */
+  Unavailable(string)
+  | /** This deployment provisions nothing for this channel. Do not retry — no
+        number of attempts provisions one. */
+  UnsupportedChannel(channel)
+  | /** The provider answered and will not take this message: an address it
+        rejects, a recipient it suppresses. Do not retry. */
+  Refused(string)
+
+/** The retry rule, stated once. Everything that sweeps a failed send derives
+    from it rather than re-reading the constructors. */
+let retriable = (failure: failure): bool =>
+  switch failure {
+  | Unavailable(_) => true
+  | UnsupportedChannel(_)
+  | Refused(_) => false
+  }
+
+/** A reason for a human, for a caller that records the outcome rather than
+    acting on it. */
+let failureReason = (failure: failure): string =>
+  switch failure {
+  | Unavailable(reason) => reason
+  | UnsupportedChannel(channel) =>
+    `this deployment provisions no ${channel->channelToString} channel`
+  | Refused(reason) => reason
+  }
+
+/**
+The port a caller reaches a messaging provider through, so swapping the
+implementation is a change of supplier rather than of call site.
+*/
+type send = (~recipient: recipient, ~message: message) => promise<result<receipt, failure>>
+
+/**
+The capability as a slice receives it: what can be attempted, and how.
+
+`channels` is here because a recipient cannot be offered a choice the deployment
+cannot honour. A platform provisions email only, or email and SMS; a preference
+centre that listed all three would collect a subscription every send then answers
+`UnsupportedChannel` for. Published rather than inferred from a failed send,
+because discovering a channel by failing on it costs a real message.
+
+Empty means no channel at all — the shape `none` takes, and the one a deploy-time
+gate exists to catch before it ships.
+*/
+type provider = {
+  channels: array<channel>,
+  send: send,
+}
+
+/** Whether this provider can attempt a recipient's channel at all. The check a
+    caller makes before spending a send, and the same rule the provider applies
+    internally, so the two cannot disagree. */
+let supports = (provider: provider, ~recipient: recipient): bool =>
+  provider.channels->Array.includes(recipient->channelOf)

package/src/semantic/Messaging.res.mjs

@@ -0,0 +1,57 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+
+function channelOf(recipient) {
+  switch (recipient.TAG) {
+    case "ToEmail" :
+      return "Email";
+    case "ToSms" :
+      return "Sms";
+    case "ToPush" :
+      return "Push";
+  }
+}
+
+function channelToString(channel) {
+  switch (channel) {
+    case "Email" :
+      return "Email";
+    case "Sms" :
+      return "Sms";
+    case "Push" :
+      return "Push";
+  }
+}
+
+function retriable(failure) {
+  switch (failure.TAG) {
+    case "Unavailable" :
+      return true;
+    case "UnsupportedChannel" :
+    case "Refused" :
+      return false;
+  }
+}
+
+function failureReason(failure) {
+  switch (failure.TAG) {
+    case "UnsupportedChannel" :
+      return `this deployment provisions no ` + channelToString(failure._0) + ` channel`;
+    case "Unavailable" :
+    case "Refused" :
+      return failure._0;
+  }
+}
+
+function supports(provider, recipient) {
+  return provider.channels.includes(channelOf(recipient));
+}
+
+export {
+  channelOf,
+  channelToString,
+  retriable,
+  failureReason,
+  supports,
+}
+/* No side effect */