@reventlessdev/reventless-local 3.0.0-alpha.220 → 3.0.0-alpha.222

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 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.222 (2026-08-14)
+
+### Features
+
+* **core:** one contract for which refusal a platform gave ([7705c13](https://github.com/ReventlessDev/reventless-core/commit/7705c13ec63f41a3a659bc98cfb45b880fd5b222))
+
+
+# 3.0.0-alpha.221 (2026-08-14)
+
+### Features
+
+* **local:** let the seed tools address a platform, not a guessed file ([98862ad](https://github.com/ReventlessDev/reventless-core/commit/98862adaa4111f605553e4a78bc52a8a488a4ef3))
+* **local:** tell an unentitled caller apart from an unidentified one ([69c4fab](https://github.com/ReventlessDev/reventless-core/commit/69c4fabc522cff60b00cebc64c5428f5084ce82b))
+
+
 # 3.0.0-alpha.220 (2026-08-13)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-local",
-  "version": "3.0.0-alpha.220",
+  "version": "3.0.0-alpha.222",
   "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-graphql-yoga": "1.0.0-alpha.27",
-    "@reventlessdev/rescript-mcp-sdk": "1.0.0-alpha.21",
     "@reventlessdev/rescript-jest": "1.0.0-alpha.10",
-    "@reventlessdev/rescript-node": "2.0.0-alpha.5",
-    "@reventlessdev/reventless-core": "3.0.0-alpha.232",
+    "@reventlessdev/rescript-mcp-sdk": "1.0.0-alpha.21",
+    "@reventlessdev/rescript-node": "2.0.0-alpha.6",
+    "@reventlessdev/rescript-graphql-yoga": "1.0.0-alpha.27",
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.19",
-    "@reventlessdev/reventless-graphql-server": "1.0.0-alpha.80",
-    "@reventlessdev/reventless-gwt": "1.0.0-alpha.179",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.139",
-    "@reventlessdev/reventless-postgres": "3.0.0-alpha.96",
-    "@reventlessdev/reventless-seed": "1.0.0-alpha.12",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.112"
+    "@reventlessdev/reventless-core": "3.0.0-alpha.234",
+    "@reventlessdev/reventless-graphql-server": "1.0.0-alpha.82",
+    "@reventlessdev/reventless-gwt": "1.0.0-alpha.181",
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.141",
+    "@reventlessdev/reventless-postgres": "3.0.0-alpha.98",
+    "@reventlessdev/reventless-seed": "1.0.0-alpha.13",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.113"
   },
   "devDependencies": {
     "rescript": "12.3.0",

package/src/LocalPlatformRegistry.res

@@ -0,0 +1,189 @@
+// Where the local platforms running on this machine say who they are.
+//
+// A platform's store is otherwise invisible from outside its own process, so
+// every tool that wants to act on "the" store — `seed`, `seed:reset`, a `sqlite3`
+// poke — has to guess from its own environment. The guess is right exactly while
+// there is one platform and wrong exactly when there are two, which is the case
+// the tools exist for: a hand-started `pnpm run serve` on `local.db` beside the
+// VS Code runner's child on `runner.db`, same app, same directory. Both then
+// report success against different databases — a reset that empties an unserved
+// store, and a seed that refuses because the served one is full.
+//
+// So a platform publishes itself instead: one JSON entry per run, next to the
+// store it opened, removed on the way out. `LocalSeedTarget` turns that into the
+// answer to "which platform do you mean".
+//
+// ── Why one file per port ──────────────────────────────────────────────────
+//
+// The pair that broke is two platforms of the SAME app in the SAME package
+// directory, which is precisely what a single `platform.json` cannot represent.
+// The domain port is what already distinguishes them (`REVENTLESS_DOMAIN_PORT`,
+// added so the runner could start one child per app without colliding), so it
+// names the file.
+//
+// ── Why the path is absolute ───────────────────────────────────────────────
+//
+// `./.reventless/local.db` names a different file in every app. Relative to the
+// writer's cwd it is unambiguous and outside it means nothing, so the entry
+// carries the path `BackendState` resolved, not the env string it came from.
+
+@schema
+type store = {
+  // "sqlite" | "memory" | "postgres" — what a reader can DO with this platform's
+  // store, not which module implements it. A `:memory:` SQLite file reports
+  // "memory": it has nothing on disk to open, which is the only distinction a
+  // tool acting from outside can act on.
+  kind: string,
+  // Some only for a store this machine can open by name.
+  path: option<string>,
+}
+
+@schema
+type entry = {
+  app: string,
+  port: int,
+  pid: int,
+  endpoint: string,
+  loginEndpoint: string,
+  store: store,
+  startedAt: string,
+}
+
+// `~cwd` is the directory the platform was started from, which is where its
+// `.reventless/` already lives. Threaded rather than read at each use so the
+// tests can exercise a registry without moving the whole process.
+let runningDir = (~cwd=NodeProcess.cwd(), ()): string =>
+  NodePath.join([cwd, ".reventless", "running"])
+
+let entryPath = (~port: int, ~cwd=NodeProcess.cwd()): string =>
+  NodePath.join([runningDir(~cwd, ()), `${port->Int.toString}.json`])
+
+// The package this platform was started from, for the prompt line. Two platforms
+// of one app are told apart by port; the name is there for the case where they
+// are different apps and the port alone reads as an arbitrary number.
+let appName = (~cwd=NodeProcess.cwd(), ()): string => {
+  let manifest = NodePath.join([cwd, "package.json"])
+  let fromManifest = if NodeFs.existsSync(manifest) {
+    try {
+      manifest
+      ->NodeFs.readFileSync
+      ->JSON.parseOrThrow
+      ->JSON.Decode.object
+      ->Option.flatMap(d => d->Dict.get("name"))
+      ->Option.flatMap(JSON.Decode.string)
+    } catch {
+    | _ => None
+    }
+  } else {
+    None
+  }
+  fromManifest->Option.getOr(NodePath.basename(cwd))
+}
+
+let removeQuietly = (path: string): unit =>
+  try NodeFs.unlinkSync(path) catch {
+  | _ => ()
+  }
+
+/** Whether a process is still there. Signal `0` performs no signalling — it only
+    runs the permission and existence checks and throws when either fails.
+
+    Liveness by pid rather than by probing the endpoint keeps this synchronous,
+    and prunes a wedged platform that holds its port but would never answer. */
+let alive = (pid: int): bool =>
+  try {
+    NodeProcess.kill(pid, 0)
+    true
+  } catch {
+  | _ => false
+  }
+
+let readEntry = (path: string): option<entry> =>
+  try Some(path->NodeFs.readFileSync->JSON.parseOrThrow->S.parseJsonOrThrow(entrySchema)) catch {
+  | _ => None
+  }
+
+/** Every platform currently running in this directory, oldest port first.
+
+    Removal on exit is best-effort — a `kill -9` leaves the entry behind — so
+    staleness is settled here, on read: an entry whose process is gone is deleted
+    rather than reported. A reader that trusted the file would offer a platform
+    nothing is serving, which is the failure this module exists to remove. */
+let list = (~cwd=NodeProcess.cwd(), ()): array<entry> => {
+  let dir = runningDir(~cwd, ())
+  if !NodeFs.existsSync(dir) {
+    []
+  } else {
+    let files = try NodeFs.readdirSync(dir, {withFileTypes: true}) catch {
+    | _ => []
+    }
+    files
+    ->Array.filter(d => d->NodeFs.isFile && d->NodeFs.direntName->String.endsWith(".json"))
+    ->Array.filterMap(d => {
+      let path = NodePath.join([dir, d->NodeFs.direntName])
+      switch readEntry(path) {
+      | Some(entry) if alive(entry.pid) => Some(entry)
+      | _ =>
+        removeQuietly(path)
+        None
+      }
+    })
+    ->Array.toSorted((a, b) => Int.compare(a.port, b.port))
+  }
+}
+
+/** Writes one entry and hands back the path it wrote, without touching the
+    process. Split from {!register} so a test can populate a registry without
+    installing exit handlers in the test runner. */
+let write = (
+  ~port: int,
+  ~endpoint: string,
+  ~loginEndpoint: string,
+  ~store: store,
+  ~pid: int=NodeProcess.pid,
+  ~cwd: string=NodeProcess.cwd(),
+): string => {
+  let path = entryPath(~port, ~cwd)
+  let entry = {
+    app: appName(~cwd, ()),
+    port,
+    pid,
+    endpoint,
+    loginEndpoint,
+    store,
+    startedAt: Date.make()->Date.toISOString,
+  }
+  try {
+    NodeFs.mkdirSync(runningDir(~cwd, ()), {recursive: true})
+    NodeFs.writeFileSync(
+      path,
+      entry->S.reverseConvertToJsonOrThrow(entrySchema)->JSON.stringify(~space=2),
+    )
+  } catch {
+  // A platform that cannot announce itself must still serve. The tools fall back
+  // to their endpoint default, which is what they did before this existed.
+  | _ => ()
+  }
+  path
+}
+
+/** Publishes this process, and arranges for it to stop being published.
+
+    Both shutdown paths are covered because they are not the same event: `exit`
+    fires with the process already committed to leaving and may only do
+    synchronous work, while `SIGINT`/`SIGTERM` fire before that decision — and
+    registering a signal handler at all is what suppresses Node's default exit,
+    so each one has to leave explicitly (128 + signal number, as a shell reports
+    it). */
+let register = (~port: int, ~endpoint: string, ~loginEndpoint: string, ~store: store): unit => {
+  let path = write(~port, ~endpoint, ~loginEndpoint, ~store)
+  NodeProcess.onExit(_ => removeQuietly(path))
+  NodeProcess.onSignal(#SIGINT, () => {
+    removeQuietly(path)
+    NodeProcess.exit(130)
+  })
+  NodeProcess.onSignal(#SIGTERM, () => {
+    removeQuietly(path)
+    NodeProcess.exit(143)
+  })
+}

package/src/LocalPlatformRegistry.res.mjs

@@ -0,0 +1,162 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+import * as Nodefs from "node:fs";
+import * as Nodepath from "node:path";
+import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+import * as Primitive_int from "@rescript/runtime/lib/es6/Primitive_int.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+
+let storeSchema = S.schema(s => ({
+  kind: s.m(S.string),
+  path: s.m(S.option(S.string))
+}));
+
+let entrySchema = S.schema(s => ({
+  app: s.m(S.string),
+  port: s.m(S.int),
+  pid: s.m(S.int),
+  endpoint: s.m(S.string),
+  loginEndpoint: s.m(S.string),
+  store: s.m(storeSchema),
+  startedAt: s.m(S.string)
+}));
+
+function runningDir(cwdOpt, param) {
+  let cwd = cwdOpt !== undefined ? cwdOpt : process.cwd();
+  return Nodepath.join(cwd, ".reventless", "running");
+}
+
+function entryPath(port, cwdOpt) {
+  let cwd = cwdOpt !== undefined ? cwdOpt : process.cwd();
+  return Nodepath.join(runningDir(cwd, undefined), port.toString() + `.json`);
+}
+
+function appName(cwdOpt, param) {
+  let cwd = cwdOpt !== undefined ? cwdOpt : process.cwd();
+  let manifest = Nodepath.join(cwd, "package.json");
+  let fromManifest;
+  if (Nodefs.existsSync(manifest)) {
+    try {
+      fromManifest = Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(JSON.parse(Nodefs.readFileSync(manifest, "utf8"))), d => d["name"]), Stdlib_JSON.Decode.string);
+    } catch (exn) {
+      fromManifest = undefined;
+    }
+  } else {
+    fromManifest = undefined;
+  }
+  return Stdlib_Option.getOr(fromManifest, Nodepath.basename(cwd));
+}
+
+function removeQuietly(path) {
+  try {
+    Nodefs.unlinkSync(path);
+    return;
+  } catch (exn) {
+    return;
+  }
+}
+
+function alive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (exn) {
+    return false;
+  }
+}
+
+function readEntry(path) {
+  try {
+    return S.parseJsonOrThrow(JSON.parse(Nodefs.readFileSync(path, "utf8")), entrySchema);
+  } catch (exn) {
+    return;
+  }
+}
+
+function list(cwdOpt, param) {
+  let cwd = cwdOpt !== undefined ? cwdOpt : process.cwd();
+  let dir = runningDir(cwd, undefined);
+  if (!Nodefs.existsSync(dir)) {
+    return [];
+  }
+  let files;
+  try {
+    files = Nodefs.readdirSync(dir, {
+      withFileTypes: true
+    });
+  } catch (exn) {
+    files = [];
+  }
+  return Stdlib_Array.filterMap(files.filter(d => {
+    if (d.isFile()) {
+      return d.name.endsWith(".json");
+    } else {
+      return false;
+    }
+  }), d => {
+    let path = Nodepath.join(dir, d.name);
+    let entry = readEntry(path);
+    if (entry !== undefined && alive(entry.pid)) {
+      return entry;
+    } else {
+      removeQuietly(path);
+      return;
+    }
+  }).toSorted((a, b) => Primitive_int.compare(a.port, b.port));
+}
+
+function write(port, endpoint, loginEndpoint, store, pidOpt, cwdOpt) {
+  let pid = pidOpt !== undefined ? pidOpt : process.pid;
+  let cwd = cwdOpt !== undefined ? cwdOpt : process.cwd();
+  let path = entryPath(port, cwd);
+  let entry_app = appName(cwd, undefined);
+  let entry_startedAt = new Date().toISOString();
+  let entry = {
+    app: entry_app,
+    port: port,
+    pid: pid,
+    endpoint: endpoint,
+    loginEndpoint: loginEndpoint,
+    store: store,
+    startedAt: entry_startedAt
+  };
+  try {
+    Nodefs.mkdirSync(runningDir(cwd, undefined), {
+      recursive: true
+    });
+    Nodefs.writeFileSync(path, JSON.stringify(S.reverseConvertToJsonOrThrow(entry, entrySchema), undefined, 2), "utf8");
+  } catch (exn) {
+    
+  }
+  return path;
+}
+
+function register(port, endpoint, loginEndpoint, store) {
+  let path = write(port, endpoint, loginEndpoint, store, undefined, undefined);
+  process.on("exit", param => removeQuietly(path));
+  process.on("SIGINT", () => {
+    removeQuietly(path);
+    process.exit(130);
+  });
+  process.on("SIGTERM", () => {
+    removeQuietly(path);
+    process.exit(143);
+  });
+}
+
+export {
+  storeSchema,
+  entrySchema,
+  runningDir,
+  entryPath,
+  appName,
+  removeQuietly,
+  alive,
+  readEntry,
+  list,
+  write,
+  register,
+}
+/* storeSchema Not a pure module */

package/src/LocalSeedTarget.res

@@ -0,0 +1,177 @@
+// Which running platform `seed` and `seed:reset` are aimed at.
+//
+// The two are supposed to be inverses, and they were resolving their target by
+// different means: `seed` addressed an ENDPOINT (`REVENTLESS_GRAPHQL_ENDPOINT`,
+// defaulting to :4000), `seed:reset` opened a FILE (`REVENTLESS_LOCAL_BACKEND`,
+// defaulting to ./.reventless/local.db). With two platforms up — a hand-started
+// one and the VS Code runner's child — they answered about different databases
+// and both reported success: "Nothing to do." followed by "the target store is
+// not empty".
+//
+// One selector for both fixes that by construction. The endpoint identifies the
+// platform (parallel platforms already differ by port); the platform names its
+// store (`LocalPlatformRegistry`). Nothing is inferred from the tool's own
+// environment except the deliberate override.
+
+open ReventlessSeed
+
+type origin =
+  | // A platform that is up and said so.
+  Running(LocalPlatformRegistry.entry)
+  | // `REVENTLESS_GRAPHQL_ENDPOINT` was set: the operator named a target, so no
+  // discovery runs and no prompt appears.
+  EnvOverride
+  | // Nothing is registered here. The endpoint default is still tried, so a
+  // platform from a build without the registry keeps working.
+  NoneRunning
+
+type t = {endpoint: string, loginEndpoint: string, origin: origin}
+
+let defaultEndpoint = "http://localhost:4000/graphql"
+
+// The login route sits on the same server as the GraphQL one, so deriving it
+// from the endpoint is what keeps a `REVENTLESS_GRAPHQL_ENDPOINT` pointing at
+// :4010 from logging in against :4000 — a mismatch that used to require setting
+// both variables to avoid, and silently seeded through the wrong door when only
+// one was set. An explicit `REVENTLESS_LOGIN_ENDPOINT` still wins.
+let loginFor = (endpoint: string): string =>
+  switch endpoint->String.indexOf("://") {
+  | -1 => endpoint
+  | i =>
+    let afterScheme = i + 3
+    switch endpoint->String.indexOfFrom("/", afterScheme) {
+    | -1 => endpoint
+    | slash => endpoint->String.slice(~start=0, ~end=slash)
+    } ++ "/__inmemory/login"
+  }
+
+let relativeIfInside = (path: string): string => {
+  let cwd = NodeProcess.cwd()
+  path->String.startsWith(cwd ++ NodePath.sep)
+    ? path->String.slice(~start=(cwd ++ NodePath.sep)->String.length)
+    : path
+}
+
+let storeLabel = (store: LocalPlatformRegistry.store): string =>
+  switch (store.kind, store.path) {
+  | ("sqlite", Some(path)) => `sqlite ${relativeIfInside(path)}`
+  | (kind, _) => kind
+  }
+
+// The scope is dropped from the app name for the menu only — `@scope/app-local`
+// is the same width in every row and carries none of the distinction.
+let shortAppName = (app: string): string =>
+  switch app->String.indexOf("/") {
+  | -1 => app
+  | i => app->String.slice(~start=i + 1)
+  }
+
+let entryLabel = (e: LocalPlatformRegistry.entry): string =>
+  `:${e.port->Int.toString}  ${e.app->shortAppName}  ${e.store->storeLabel}`
+
+/** Resolves the platform this run acts on.
+
+    Precedence — explicit target, then the running platforms, then the historical
+    default:
+
+    1. `REVENTLESS_GRAPHQL_ENDPOINT` — named a target, so it is used verbatim.
+    2. one platform registered — it, with no prompt.
+    3. several — a menu, preselectable with `SEED_PLATFORM` (port or menu index)
+       so a run without a TTY is not stuck.
+    4. none — the :4000 default, so this stays backwards compatible with a
+       platform started from a build that does not register itself. */
+let select = async (): t => {
+  switch Seed.Prompt.envValue("REVENTLESS_GRAPHQL_ENDPOINT") {
+  | Some(endpoint) => {
+      endpoint,
+      loginEndpoint: Seed.Prompt.envValue("REVENTLESS_LOGIN_ENDPOINT")->Option.getOr(
+        endpoint->loginFor,
+      ),
+      origin: EnvOverride,
+    }
+  | None =>
+    let running = LocalPlatformRegistry.list()
+    // Matched on the port rather than through `select`'s own `~env`, which
+    // compares against the whole rendered label — `SEED_PLATFORM=4000` is the
+    // form an operator would write, and no label will ever equal it.
+    let preselected =
+      Seed.Prompt.envValue("SEED_PLATFORM")->Option.flatMap(v =>
+        running->Array.find(e => e.port->Int.toString == v)
+      )
+    let chosen = switch (preselected, running) {
+    | (Some(entry), _) => Some(entry)
+    | (None, []) => None
+    | (None, entries) =>
+      Some(
+        await Seed.Prompt.select(
+          ~title="Platform:",
+          ~options=entries->Array.map(e => (e->entryLabel, e)),
+          ~env="SEED_PLATFORM",
+        ),
+      )
+    }
+    switch chosen {
+    | Some(entry) => {
+        endpoint: entry.endpoint,
+        loginEndpoint: entry.loginEndpoint,
+        origin: Running(entry),
+      }
+    | None => {
+        endpoint: defaultEndpoint,
+        loginEndpoint: defaultEndpoint->loginFor,
+        origin: NoneRunning,
+      }
+    }
+  }
+}
+
+/** Says which platform was picked, before anything is written or deleted.
+
+    Printed even when there was no choice to make: the single-platform case is
+    the one that produced a reset and a seed acting on different stores, and one
+    line naming the endpoint and the store is what makes that visible. */
+let announce = (t: t): unit =>
+  switch t.origin {
+  | Running(entry) =>
+    Console.log(`→ ${entry.endpoint}  ·  ${entry.store->storeLabel}  (${entry.app->shortAppName})`)
+  | EnvOverride => Console.log(`→ ${t.endpoint}  (REVENTLESS_GRAPHQL_ENDPOINT)`)
+  | NoneRunning =>
+    Console.log(`→ ${t.endpoint}  (no local platform registered here — trying the default)`)
+  }
+
+/** The store the selected platform opened: `Some(path)` only for one this
+    machine can open by name. `None` carries the reason, already phrased for the
+    operator, because "no path" has three different meanings and a tool that
+    collapsed them would tell an in-memory platform to check its disk. */
+let storePath = (t: t): result<string, string> =>
+  switch t.origin {
+  | Running({store: {kind: "sqlite", path: Some(path)}}) => Ok(path)
+  | Running({store: {kind: "memory"}, endpoint}) =>
+    Error(`the platform at ${endpoint} keeps its store in memory; restart it to empty it.`)
+  | Running({store: {kind: "postgres"}, endpoint}) =>
+    Error(
+      `the platform at ${endpoint} is backed by Postgres, which keeps its event logs off this machine. Reset it against the database.`,
+    )
+  | Running({store: {kind}, endpoint}) =>
+    Error(`the platform at ${endpoint} reports an unknown store kind "${kind}".`)
+  | EnvOverride =>
+    Error(
+      `REVENTLESS_GRAPHQL_ENDPOINT names ${t.endpoint}, which does not say which store that platform opened. Set REVENTLESS_LOCAL_BACKEND to the store file, or unset REVENTLESS_GRAPHQL_ENDPOINT to pick a running platform.`,
+    )
+  | NoneRunning =>
+    Error(
+      "no local platform is running here. Start one, or set REVENTLESS_LOCAL_BACKEND to reset a store directly.",
+    )
+  }
+
+/** A `Seed.Runner.seed`-shaped `~connect` that targets the selected platform.
+
+    `~connect` is already a thunk, so the selection — prompt included — happens
+    when seeding starts rather than at module load, and `Seed_Connect.local`
+    stays untouched: it takes the endpoints, it does not go looking for them. */
+let connect = (): (unit => promise<Seed.Connect.connection>) =>
+  async () => {
+    let target = await select()
+    target->announce
+    await Seed.Connect.local(~graphql=target.endpoint, ~login=target.loginEndpoint, ())()
+  }