@reventlessdev/reventless-local 3.0.0-alpha.216 → 3.0.0-alpha.218

package/CHANGELOG.md

@@ -3,6 +3,25 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 3.0.0-alpha.218 (2026-08-13)
+
+### Features
+
+* **aws:** bake the component manifest after every plugin stack is up ([2fff09a](https://github.com/ReventlessDev/reventless-core/commit/2fff09aa32b77cc8e33a65414c58c12026ca009e))
+* **local:** bake one curated surface per audience ([3be6f63](https://github.com/ReventlessDev/reventless-core/commit/3be6f63e579cef8cd213a84b6ccded773b1abc9e))
+* **local:** let a login act as one of the roles it holds ([61141ac](https://github.com/ReventlessDev/reventless-core/commit/61141ac783a71dd7f043e84e6e7732c67cfb921b))
+* **local:** point the dev shell at the manifest it bakes ([e4d0f1c](https://github.com/ReventlessDev/reventless-core/commit/e4d0f1cef70f9a9ca6d13266d72db3f38d0cc2d9))
+* **local:** serve the ui-hints file a deployment declares ([8258c85](https://github.com/ReventlessDev/reventless-core/commit/8258c858155fec760a772483f9bde208ffa57f61))
+* **local:** switch role without logging in again ([4f82348](https://github.com/ReventlessDev/reventless-core/commit/4f82348f01b9117256fc1d7208355c3654875909))
+
+
+# 3.0.0-alpha.217 (2026-08-12)
+
+### Bug Fixes
+
+* **command:** drop null arguments, and let a caller read why a payload was refused ([bfee0dc](https://github.com/ReventlessDev/reventless-core/commit/bfee0dc37755596ea8bcce1fe2cccdace7759f10))
+
+
 # 3.0.0-alpha.216 (2026-08-12)
 
 **Note:** Version bump only for package @reventlessdev/reventless-local

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-local",
-  "version": "3.0.0-alpha.216",
+  "version": "3.0.0-alpha.218",
   "description": "Local platform for Reventless (in-memory or SQLite backend, for development and testing without AWS)",
   "license": "Apache-2.0",
   "bin": {
@@ -35,18 +35,18 @@
     "sury": "11.0.0-alpha.4",
     "ws": "^8.18.0",
     "@reventlessdev/rescript-effect": "0.1.0-alpha.32",
-    "@reventlessdev/rescript-jest": "1.0.0-alpha.10",
     "@reventlessdev/rescript-graphql-yoga": "1.0.0-alpha.27",
+    "@reventlessdev/rescript-jest": "1.0.0-alpha.10",
     "@reventlessdev/rescript-mcp-sdk": "1.0.0-alpha.21",
-    "@reventlessdev/rescript-node": "2.0.0-alpha.4",
+    "@reventlessdev/rescript-node": "2.0.0-alpha.5",
+    "@reventlessdev/reventless-core": "3.0.0-alpha.230",
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.18",
-    "@reventlessdev/reventless-graphql-server": "1.0.0-alpha.76",
-    "@reventlessdev/reventless-core": "3.0.0-alpha.228",
-    "@reventlessdev/reventless-postgres": "3.0.0-alpha.92",
-    "@reventlessdev/reventless-gwt": "1.0.0-alpha.175",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.137",
-    "@reventlessdev/reventless-seed": "1.0.0-alpha.11",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.111"
+    "@reventlessdev/reventless-graphql-server": "1.0.0-alpha.78",
+    "@reventlessdev/reventless-gwt": "1.0.0-alpha.177",
+    "@reventlessdev/reventless-seed": "1.0.0-alpha.12",
+    "@reventlessdev/reventless-postgres": "3.0.0-alpha.94",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.112",
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.138"
   },
   "devDependencies": {
     "rescript": "12.3.0",

package/src/BakedManifest.res

@@ -1,72 +1,84 @@
 // Writes the curated component manifest where the local host shell serves its
-// static assets from, so `manifestUrl` discovery works in dev exactly as it does
-// in a deployment.
-//
-// Locally there is no deploy and no bucket: `reventless-host-shell` serves its
-// own `dist/` (that is where the shipped `config.json` and `ui-hints.json` come
-// from), so that is where the file goes. Rewritten on every boot, which also
-// makes it self-healing — a `pnpm install` that replaces the package directory
-// costs one restart, not a debugging session.
+// static assets from (`HostShellDist`), so `manifestUrl` discovery works in dev
+// exactly as it does in a deployment. Rewritten on every boot, which also makes
+// it self-healing — a `pnpm install` that replaces the package directory costs
+// one restart, not a debugging session.
 //
 // The curation itself lives in `ReventlessCore.Platform_BakedManifest`, shared
 // with any other platform that bakes: only the destination is local.
 
-let hostShellPackage = "@reventlessdev/reventless-host-shell"
-
 let log = ReventlessCore.Logger.fromEnv()
 
-// Resolved from the running project rather than from this framework module: the
-// bundle is a deploy input the project names in its own package.json, and a
-// framework-rooted lookup would skip that pin (the same distinction
-// `Util_Bundle.resolvePackageRoot(~fromPulumiProject)` draws on AWS).
-let hostShellDistDir = (): option<string> =>
-  try {
-    Some(
-      NodePath.dirname(
-        NodeModule.createRequire(NodeProcess.cwd() ++ "/index.js")->NodeModule.requireResolve(
-          hostShellPackage ++ "/package.json",
-        ),
-      ) ++ "/dist",
-    )
-  } catch {
-  | _ => None
-  }
-
-let defaultKey = "component-manifest.json"
-
 /**
  A declared bake writes the file or fails loudly. Both failure modes it can hit
  are the deployment's own mistake — a name that matches no component, or a shell
  package that is not installed — and both produce the same symptom if swallowed:
  a shop that renders nothing, with no line in the log saying why.
  */
+let toSelections = (
+  components: array<ReventlessInfra.Platform.bakedManifestSelection>,
+): array<ReventlessCore.Platform_BakedManifest.selection> =>
+  components->Array.map((s): ReventlessCore.Platform_BakedManifest.selection => {
+    plugin: s.plugin,
+    views: s.views,
+    commands: s.commands,
+  })
+
+/**
+ Every file this declaration produces, as (key, selections) pairs.
+
+ The default journey first, then one per declared journey. Separate from the
+ write so the whole set is reachable from a test — the same reason
+ `ShellConfig.overlay` exists apart from its write.
+ */
+let files = (
+  ~config: ReventlessInfra.Platform.bakedManifest,
+): array<(string, array<ReventlessCore.Platform_BakedManifest.selection>)> => {
+  let base = [
+    (
+      config.key->Option.getOr(ReventlessCore.Platform_BakedManifest.defaultKey),
+      toSelections(config.components),
+    ),
+  ]
+  switch config.journeys {
+  | None => base
+  | Some(journeys) =>
+    base->Array.concat(
+      journeys->Array.map(j => (
+        j.key->Option.getOr(ReventlessCore.Platform_BakedManifest.journeyKey(~group=j.group)),
+        toSelections(j.components),
+      )),
+    )
+  }
+}
+
 let emit = (
   ~structures: array<(string, Reventless.Plugin.pluginStructure)>,
   ~config: ReventlessInfra.Platform.bakedManifest,
 ) => {
-  let selections =
-    config.components->Array.map((
-      s
-    ): ReventlessCore.Platform_BakedManifest.selection => {
-      plugin: s.plugin,
-      views: s.views,
-      commands: s.commands,
-    })
-  switch ReventlessCore.Platform_BakedManifest.curate(~structures, ~selections) {
-  | Error(e) => JsError.throwWithMessage(ReventlessCore.Platform_BakedManifest.describe(e))
-  | Ok(manifest) =>
-    switch hostShellDistDir() {
-    | None =>
-      JsError.throwWithMessage(
-        `baked manifest: cannot resolve ${hostShellPackage} from ${NodeProcess.cwd()} — ` ++
-        `the local shell serves the file from that package's dist/, so declaring a bake ` ++
-        `without the package installed would write nothing and render an empty shell.`,
-      )
-    | Some(dir) =>
-      let key = config.key->Option.getOr(defaultKey)
+  let outputs = files(~config)
+  // Every file is curated before any is written. A declaration naming a
+  // component that does not exist fails the boot, and failing it halfway would
+  // leave a shell serving one audience's file and a stale copy of another's.
+  let curated = outputs->Array.map(((key, selections)) => (
+    key,
+    switch ReventlessCore.Platform_BakedManifest.curate(~structures, ~selections) {
+    | Error(e) => JsError.throwWithMessage(ReventlessCore.Platform_BakedManifest.describe(e))
+    | Ok(manifest) => manifest
+    },
+  ))
+  switch HostShellDist.dir() {
+  | None =>
+    JsError.throwWithMessage(
+      `baked manifest: cannot resolve ${HostShellDist.package} from ${NodeProcess.cwd()} — ` ++
+      `the local shell serves the file from that package's dist/, so declaring a bake ` ++
+      `without the package installed would write nothing and render an empty shell.`,
+    )
+  | Some(dir) =>
+    curated->Array.forEach(((key, manifest)) => {
       let path = NodePath.join([dir, key])
       NodeFs.writeFileSync(path, JSON.stringify(manifest, ~space=2))
-      log.info(~comp="BakedManifest", `wrote ${key} for ${selections->Array.length->Int.toString} plugin(s): ${path}`)
-    }
+      log.info(~comp="BakedManifest", `wrote ${key}: ${path}`)
+    })
   }
 }

package/src/BakedManifest.res.mjs

@@ -2,51 +2,67 @@
 
 import * as Nodefs from "node:fs";
 import * as Nodepath from "node:path";
-import * as Nodemodule from "node:module";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
 import * as Logger$ReventlessCore from "@reventlessdev/reventless-core/src/util/Logger.res.mjs";
+import * as HostShellDist$ReventlessLocal from "./HostShellDist.res.mjs";
 import * as Platform_BakedManifest$ReventlessCore from "@reventlessdev/reventless-core/src/admin/Platform_BakedManifest.res.mjs";
 
-let hostShellPackage = "@reventlessdev/reventless-host-shell";
-
 let log = Logger$ReventlessCore.fromEnv();
 
-function hostShellDistDir() {
-  try {
-    return Nodepath.dirname(Nodemodule.createRequire(process.cwd() + "/index.js").resolve(hostShellPackage + "/package.json")) + "/dist";
-  } catch (exn) {
-    return;
-  }
-}
-
-let defaultKey = "component-manifest.json";
-
-function emit(structures, config) {
-  let selections = config.components.map(s => ({
+function toSelections(components) {
+  return components.map(s => ({
     plugin: s.plugin,
     views: s.views,
     commands: s.commands
   }));
-  let e = Platform_BakedManifest$ReventlessCore.curate(structures, selections);
-  if (e.TAG !== "Ok") {
-    return Stdlib_JsError.throwWithMessage(Platform_BakedManifest$ReventlessCore.describe(e._0));
+}
+
+function files(config) {
+  let base = [[
+      Stdlib_Option.getOr(config.key, Platform_BakedManifest$ReventlessCore.defaultKey),
+      toSelections(config.components)
+    ]];
+  let journeys = config.journeys;
+  if (journeys !== undefined) {
+    return base.concat(journeys.map(j => [
+      Stdlib_Option.getOr(j.key, Platform_BakedManifest$ReventlessCore.journeyKey(j.group)),
+      toSelections(j.components)
+    ]));
+  } else {
+    return base;
   }
-  let dir = hostShellDistDir();
-  if (dir === undefined) {
-    return Stdlib_JsError.throwWithMessage(`baked manifest: cannot resolve ` + hostShellPackage + ` from ` + process.cwd() + ` — the local shell serves the file from that package's dist/, so declaring a bake without the package installed would write nothing and render an empty shell.`);
+}
+
+function emit(structures, config) {
+  let outputs = files(config);
+  let curated = outputs.map(param => {
+    let e = Platform_BakedManifest$ReventlessCore.curate(structures, param[1]);
+    let tmp;
+    tmp = e.TAG === "Ok" ? e._0 : Stdlib_JsError.throwWithMessage(Platform_BakedManifest$ReventlessCore.describe(e._0));
+    return [
+      param[0],
+      tmp
+    ];
+  });
+  let dir = HostShellDist$ReventlessLocal.dir();
+  if (dir !== undefined) {
+    curated.forEach(param => {
+      let key = param[0];
+      let path = Nodepath.join(dir, key);
+      Nodefs.writeFileSync(path, JSON.stringify(param[1], undefined, 2), "utf8");
+      log.info("BakedManifest", undefined, `wrote ` + key + `: ` + path);
+    });
+    return;
+  } else {
+    return Stdlib_JsError.throwWithMessage(`baked manifest: cannot resolve ` + HostShellDist$ReventlessLocal.$$package + ` from ` + process.cwd() + ` — the local shell serves the file from that package's dist/, so declaring a bake without the package installed would write nothing and render an empty shell.`);
   }
-  let key = Stdlib_Option.getOr(config.key, defaultKey);
-  let path = Nodepath.join(dir, key);
-  Nodefs.writeFileSync(path, JSON.stringify(e._0, undefined, 2), "utf8");
-  log.info("BakedManifest", undefined, `wrote ` + key + ` for ` + selections.length.toString() + ` plugin(s): ` + path);
 }
 
 export {
-  hostShellPackage,
   log,
-  hostShellDistDir,
-  defaultKey,
+  toSelections,
+  files,
   emit,
 }
 /* log Not a pure module */

package/src/HostShellDist.res

@@ -0,0 +1,29 @@
+// Where the local host shell serves its static assets from.
+//
+// Locally there is no deploy and no bucket: `reventless-host-shell` serves its
+// own `dist/` (that is where the shipped `config.json` and `ui-hints.json` a dev
+// sees come from), so that is where every generated asset the browser fetches
+// has to land — the baked component manifest and the `config.json` overlay
+// alike. Resolved in one place because those writers have to agree: a second
+// opinion about the directory puts a manifest where nothing reads it, and the
+// symptom is an empty shell rather than a missing file.
+//
+// Resolved from the running project rather than from this framework module: the
+// bundle is a deploy input the project names in its own package.json, and a
+// framework-rooted lookup would skip that pin (the same distinction
+// `Util_Bundle.resolvePackageRoot(~fromPulumiProject)` draws on AWS).
+
+let package = "@reventlessdev/reventless-host-shell"
+
+let dir = (): option<string> =>
+  try {
+    Some(
+      NodePath.dirname(
+        NodeModule.createRequire(NodeProcess.cwd() ++ "/index.js")->NodeModule.requireResolve(
+          package ++ "/package.json",
+        ),
+      ) ++ "/dist",
+    )
+  } catch {
+  | _ => None
+  }

package/src/HostShellDist.res.mjs

@@ -0,0 +1,20 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Nodepath from "node:path";
+import * as Nodemodule from "node:module";
+
+let $$package = "@reventlessdev/reventless-host-shell";
+
+function dir() {
+  try {
+    return Nodepath.dirname(Nodemodule.createRequire(process.cwd() + "/index.js").resolve($$package + "/package.json")) + "/dist";
+  } catch (exn) {
+    return;
+  }
+}
+
+export {
+  $$package,
+  dir,
+}
+/* node:path Not a pure module */

package/src/Platform.res

@@ -1428,28 +1428,33 @@ module MakeWithConfig = (
       }
     })
 
-  // In-memory ignores most of `~hostUiBundle` — the host shell is served by
-  // `vite dev` against the running in-process GraphQL server, not from a CDN,
-  // including `uiHintsFile` (the AWS deploy writes it as a BucketObject; local
-  // dev serves `public/ui-hints.json` directly). `bakedManifest` is the
-  // exception: it is generated content, so there is no hand-authored file for
-  // local dev to serve instead.
+  // In-memory ignores the infrastructure half of `~hostUiBundle` — the host shell
+  // is served from the installed package's own `dist/`, not from a CDN. What a
+  // deployment *says* is honoured, in the same three files the AWS deploy writes
+  // beside each other: `bakedManifest` through `BakedManifest`, `shellConfig`
+  // through `ShellConfig`, which overlays the served `config.json` the way the
+  // AWS deploy composes the one it writes, and `uiHintsFile` through `UiHints`,
+  // which replaces the served hints file the way the deploy uploads it.
   type hostUiBundleConfig = {
     assetsDir?: string,
     bundleVersion?: string,
+    // `makePlatform` serves the declared file in place of the host-shell
+    // package's own dev-mode fallback, which an undeclared platform keeps.
     uiHintsFile?: string,
-    // Honoured here, unlike the rest: `makePlatform` writes the curated manifest
-    // where the local host-shell serves its static assets from.
+    // `makePlatform` writes the curated manifest where the local host-shell
+    // serves its static assets from, and points `config.json` at it.
     bakedManifest?: ReventlessInfra.Platform.bakedManifest,
     // AWS host-ui deploy knobs — carried to satisfy the shared Platform.T
     // signature; the in-memory platform provisions no infrastructure and
     // ignores them.
     geocoderPlaceIndex?: ReventlessInfra.Platform.geocoderIndex,
     uploadBucket?: ReventlessInfra.Platform.objectStore,
-    // Same terms: the AWS deploy writes these into the config.json it hosts, and
-    // local dev has no config.json of its own to write — the host-shell package
-    // serves `public/config.json`, which is where local turns a view mode on.
+    // Still ignored: a mode is a shell *build* input locally, turned on in the
+    // host-shell package's own `public/config.json`, where the AWS deploy has to
+    // write it into the config.json it hosts.
     viewModes?: array<ReventlessInfra.Platform.viewMode>,
+    // Merged into the served `config.json` verbatim, as on AWS — the keys the
+    // shell owns and neither platform computes (`appName`, `elevatedGroups`, …).
     shellConfig?: dict<JSON.t>,
   }
   let makePlatform = (
@@ -1610,6 +1615,20 @@ module MakeWithConfig = (
     // offers, which is settled at composition and owes nothing to projection
     // catch-up. Every plugin passed to this call is connected by construction
     // locally, so there is no status or version dedup to apply.
+    //
+    // The config.json overlay is written first and synchronously: it depends on
+    // the *declaration* only, where the bake has to wait for every plugin's
+    // structure Output to land. Unconditional, unlike the bake, because it is
+    // also what restores the shipped file for a platform that has stopped
+    // declaring anything.
+    ShellConfig.emit(
+      ~bakedManifest=hostUiBundle->Option.flatMap(cfg => cfg.bakedManifest),
+      ~shellConfig=hostUiBundle->Option.flatMap(cfg => cfg.shellConfig),
+    )
+    // Unconditional for the same reason, and one file over: it is also what
+    // restores the shell package's own hints for a platform that has stopped
+    // declaring its own.
+    UiHints.emit(~uiHintsFile=hostUiBundle->Option.flatMap(cfg => cfg.uiHintsFile))
     switch hostUiBundle->Option.flatMap(cfg => cfg.bakedManifest) {
     | None => ()
     | Some(cfg) => bakeManifest(~pluginComponents=plugins, ~config=cfg)

package/src/Platform.res.mjs

@@ -18,6 +18,7 @@ import * as Logger$ReventlessCore from "@reventlessdev/reventless-core/src/util/
 import * as Plugin$ReventlessCore from "@reventlessdev/reventless-core/src/plugin/component/Plugin.res.mjs";
 import * as Message$ReventlessCore from "@reventlessdev/reventless-core/src/Message.res.mjs";
 import * as Backend$ReventlessLocal from "./adapter/Backend.res.mjs";
+import * as UiHints$ReventlessLocal from "./UiHints.res.mjs";
 import * as Component$ReventlessCore from "@reventlessdev/reventless-core/src/components/Component.res.mjs";
 import * as LocalBus$ReventlessLocal from "./adapter/LocalBus.res.mjs";
 import * as Api_Naming$ReventlessCore from "@reventlessdev/reventless-core/src/components/Api/Api_Naming.res.mjs";
@@ -27,6 +28,7 @@ import * as TestRunner$ReventlessLocal from "./test/TestRunner.res.mjs";
 import * as UiFragments$ReventlessCore from "@reventlessdev/reventless-core/src/admin/UiFragmentRegistry/StateViewSlice/UiFragments.res.mjs";
 import * as CommandTopic$ReventlessCore from "@reventlessdev/reventless-core/src/components/CommandTopic/CommandTopic.res.mjs";
 import * as EffectLogger$ReventlessCore from "@reventlessdev/reventless-core/src/util/EffectLogger.res.mjs";
+import * as ShellConfig$ReventlessLocal from "./ShellConfig.res.mjs";
 import * as BackendState$ReventlessLocal from "./adapter/BackendState.res.mjs";
 import * as ComponentType$ReventlessCore from "@reventlessdev/reventless-core/src/ComponentType.res.mjs";
 import * as SqliteDriver$ReventlessLocal from "./adapter/SqliteDriver.res.mjs";
@@ -1285,6 +1287,8 @@ function MakeWithConfig(Config) {
       adminResources: []
     });
     subscribeToPluginEvents();
+    ShellConfig$ReventlessLocal.emit(Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.bakedManifest), Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.shellConfig), undefined);
+    UiHints$ReventlessLocal.emit(Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.uiHintsFile), undefined);
     let cfg = Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.bakedManifest);
     if (cfg !== undefined) {
       bakeManifest(plugins$1, cfg);
@@ -3003,6 +3007,8 @@ function Make($star) {
       adminResources: []
     });
     subscribeToPluginEvents();
+    ShellConfig$ReventlessLocal.emit(Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.bakedManifest), Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.shellConfig), undefined);
+    UiHints$ReventlessLocal.emit(Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.uiHintsFile), undefined);
     let cfg = Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.bakedManifest);
     if (cfg !== undefined) {
       bakeManifest(plugins$1, cfg);

package/src/ShellConfig.res

@@ -0,0 +1,178 @@
+// Delivers a deployment's host-shell keys to local dev, so `config.json` says
+// the same things it says on AWS.
+//
+// On AWS the deploy owns that file outright: `Util_ShellConfig.fields` joins the
+// keys the deploy computes with the ones the deployment chose, and the result is
+// written as a `BucketObject`. Locally there is no deploy and no bucket — the
+// `config.json` a dev's browser fetches is the one `reventless-host-shell`
+// shipped in its own `dist/`. That file is therefore the *baseline* here, not
+// the output.
+//
+// Hence the copy. The first write puts the shipped file aside as
+// `config.base.json` and every write since is baseline + overlay. Overlaying the
+// previous output instead would make removal impossible: drop `bakedManifest`
+// from the platform root and yesterday's `manifestUrl` stays, pointing the shell
+// at a file nothing writes any more — an empty shop with nothing in the diff to
+// explain it. Reading a baseline makes both directions self-healing, and a
+// `pnpm install` that replaces the package directory costs one restart, because
+// the baseline is re-seeded from whatever the new package ships.
+//
+// One key is computed (`manifestUrl`, from the bake declaration — local knows
+// where it put the file); the rest are the deployment's own `shellConfig`,
+// passed through verbatim. A `shellConfig` that names a computed key fails the
+// same way it does on AWS: a passthrough cannot redirect a key the platform
+// decides, and silently resolving it either way points the shell somewhere
+// unintended.
+
+let log = ReventlessCore.Logger.fromEnv()
+
+let fileName = "config.json"
+
+// Not `config.json.base` — the shell's dist is served as a static directory, and
+// a name that keeps the `.json` extension is the one a dev can open in a browser
+// to see what the overlay started from.
+let baselineFileName = "config.base.json"
+
+let manifestUrlOf = (config: ReventlessInfra.Platform.bakedManifest): string =>
+  ReventlessCore.Platform_BakedManifest.urlForKey(config.key)
+
+// Where a caller acting as a given role discovers from. Beside `manifestUrl`
+// rather than replacing it: that key stays the default journey, which is what a
+// caller matching no declared group gets and what every existing deployment has.
+let journeyManifestsKey = "journeyManifestUrls"
+
+let computedKeys = ["manifestUrl", journeyManifestsKey]
+
+/**
+ The overlay this platform puts on top of the shipped `config.json`.
+
+ Separate from the write so the whole key set is reachable from a test, the same
+ reason `Util_ShellConfig.fields` exists apart from `deployPlatform`'s
+ `Pulumi.Output.apply` on AWS.
+ */
+let overlay = (
+  ~bakedManifest: option<ReventlessInfra.Platform.bakedManifest>,
+  ~shellConfig: option<dict<JSON.t>>,
+): dict<JSON.t> => {
+  let out = Dict.make()
+
+  bakedManifest->Option.forEach(config => {
+    out->Dict.set("manifestUrl", JSON.Encode.string(manifestUrlOf(config)))
+    // Omitted entirely when nothing is declared, so a single-audience deployment
+    // writes the same key set it always did and a shell that has never heard of
+    // journeys sees no new keys.
+    switch config.journeys {
+    | None => ()
+    | Some([]) => ()
+    | Some(journeys) =>
+      let map = Dict.make()
+      journeys->Array.forEach(j =>
+        map->Dict.set(
+          j.group,
+          JSON.Encode.string(
+            ReventlessCore.Platform_BakedManifest.urlForKey(
+              Some(
+                j.key->Option.getOr(
+                  ReventlessCore.Platform_BakedManifest.journeyKey(~group=j.group),
+                ),
+              ),
+            ),
+          ),
+        )
+      )
+      out->Dict.set(journeyManifestsKey, map->JSON.Encode.object)
+    }
+  })
+
+  shellConfig->Option.forEach(extra => {
+    let collisions = extra->Dict.keysToArray->Array.filter(k => computedKeys->Array.includes(k))
+    if collisions->Array.length > 0 {
+      JsError.throwWithMessage(
+        "host UI config.json: shellConfig sets key(s) the platform already computes — " ++
+        collisions->Array.join(", ") ++
+        ". Remove them from shellConfig; a passthrough cannot redirect a computed key.",
+      )
+    }
+    extra->Dict.forEachWithKey((v, k) => out->Dict.set(k, v))
+  })
+
+  out
+}
+
+let readObject = (~path: string, ~label: string): dict<JSON.t> =>
+  switch NodeFs.readFileSync(path)->JSON.parseOrThrow->JSON.Decode.object {
+  | Some(obj) => obj
+  | None => JsError.throwWithMessage(`host UI ${label}: ${path} is not a JSON object`)
+  | exception _ => JsError.throwWithMessage(`host UI ${label}: cannot read ${path} as JSON`)
+  }
+
+/**
+ Merge the overlay onto the shipped `config.json` in the host shell's `dist/`.
+
+ A no-op when there is nothing to say and nothing was said before — a platform
+ that declares neither a bake nor any `shellConfig` never touches the file, so
+ its dev shell is byte-identical to one built before this module existed. Once
+ either is declared the write happens or fails loudly, for the reason
+ `BakedManifest.emit` gives: both failure modes it can hit are the deployment's
+ own mistake, and both produce the same silent symptom if swallowed.
+ */
+let emit = (
+  ~bakedManifest: option<ReventlessInfra.Platform.bakedManifest>,
+  ~shellConfig: option<dict<JSON.t>>,
+  // Test seam. The baseline dance is the part of this module with state behind
+  // it — "boot twice and the second write still starts from the shipped file" is
+  // not a property a pure function can carry.
+  ~dir: option<string>=?,
+) => {
+  let overlay = overlay(~bakedManifest, ~shellConfig)
+
+  switch (
+    switch dir {
+    | Some(_) as given => given
+    | None => HostShellDist.dir()
+    }
+  ) {
+  | None =>
+    // Nothing declared and no shell installed is the ordinary case for a
+    // platform nobody points a browser at; only a declaration makes the missing
+    // package an error, and then it is the same error the bake gives.
+    if overlay->Dict.keysToArray->Array.length > 0 {
+      JsError.throwWithMessage(
+        `host UI config.json: cannot resolve ${HostShellDist.package} from ${NodeProcess.cwd()} — ` ++
+        `the local shell reads its config from that package's dist/, so declaring shell ` ++
+        `config without the package installed would write nothing and leave the shell ` ++
+        `configured as it shipped.`,
+      )
+    }
+  | Some(dir) =>
+    let path = NodePath.join([dir, fileName])
+    let baselinePath = NodePath.join([dir, baselineFileName])
+
+    // Seeded only when there is an overlay to apply. A platform that declares
+    // nothing must not leave a `config.base.json` behind for the next one to
+    // read as authoritative.
+    if !NodeFs.existsSync(baselinePath) && overlay->Dict.keysToArray->Array.length > 0 {
+      if !NodeFs.existsSync(path) {
+        JsError.throwWithMessage(
+          `host UI config.json: ${HostShellDist.package} ships no ${fileName} at ${dir} — ` ++
+          `there is no baseline to overlay, so the shell would boot with only the keys ` ++
+          `declared here and none of the ones it expects.`,
+        )
+      }
+      NodeFs.writeFileSync(baselinePath, NodeFs.readFileSync(path))
+    }
+
+    if NodeFs.existsSync(baselinePath) {
+      let merged = readObject(~path=baselinePath, ~label="config baseline")
+      overlay->Dict.forEachWithKey((v, k) => merged->Dict.set(k, v))
+      NodeFs.writeFileSync(path, JSON.stringify(merged->JSON.Encode.object, ~space=2))
+      let keys = overlay->Dict.keysToArray
+      log.info(
+        ~comp="ShellConfig",
+        keys->Array.length == 0
+          ? `restored ${fileName} from ${baselineFileName}: ${path}`
+          : `wrote ${fileName} with ${keys->Array.join(", ")}: ${path}`,
+      )
+    }
+  }
+}