@reventlessdev/rescript-node 2.0.0-alpha.1 → 2.0.0-alpha.10

package/CHANGELOG.md

@@ -3,6 +3,70 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 2.0.0-alpha.10 (2026-09-08)
+
+### Features
+
+* **seed:** a run says which identity its token carries, not which one it asked for ([063da61](https://github.com/ReventlessDev/reventless-core/commit/063da6110a2d89333bd3d99f4c7cb1bc579d78f0))
+
+
+# 2.0.0-alpha.9 (2026-09-04)
+
+### Features
+
+* **local:** serve the event tap over a socket, on by default ([1babf96](https://github.com/ReventlessDev/reventless-core/commit/1babf960f032805418e3ac8f25d03ceb3dcd8d20))
+
+
+# 2.0.0-alpha.8 (2026-08-18)
+
+### Features
+
+* **core:** read a command's lifecycle guard off the GWT corpus, and check [@transition](https://github.com/transition) against it ([057c898](https://github.com/ReventlessDev/reventless-core/commit/057c898761917bd6fc5eb9ac6867c8125709eab4))
+
+
+# 2.0.0-alpha.7 (2026-08-15)
+
+### Features
+
+* **local:** serve ui-hints.json edits without restarting the platform ([b29b104](https://github.com/ReventlessDev/reventless-core/commit/b29b1044f31f620071423c618486daef9692c614))
+
+
+# 2.0.0-alpha.6 (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))
+
+
+# 2.0.0-alpha.5 (2026-08-13)
+
+### Features
+
+* **rescript:** bind import.meta so no module reaches for %raw ([c7bd00c](https://github.com/ReventlessDev/reventless-core/commit/c7bd00c0d49ca06cb26a0891a85921219eb87b12))
+
+
+# 2.0.0-alpha.4 (2026-08-11)
+
+**Note:** Version bump only for package @reventlessdev/rescript-node
+
+
+
+
+
+# 2.0.0-alpha.3 (2026-08-09)
+
+### Features
+
+* **core,aws:** bundle a runtime extension's companion packages, guard imports at deploy ([e975175](https://github.com/ReventlessDev/reventless-core/commit/e9751758f51582a8e46db362219f725bb5f1bcde))
+
+
+# 2.0.0-alpha.2 (2026-08-05)
+
+### Features
+
+* **local:** persist the object store beside the SQLite database ([f37e4a1](https://github.com/ReventlessDev/reventless-core/commit/f37e4a1ad3191a97f14f3db7e2ead0e2b27b46c2))
+
+
 # 2.0.0-alpha.1 (2026-08-02)
 
 ### Features

package/README.md

@@ -34,9 +34,252 @@ Add it to your `rescript.json` dependencies:
 
 | Module | Binds |
 |---|---|
+| `NodeBuffer` | the global `Buffer` |
+| `NodeChildProcess` | `node:child_process` |
+| `NodeCrypto` | `node:crypto` |
+| `NodeFs` | `node:fs`, plus `node:fs/promises` as `NodeFs.Promises` |
+| `NodeImportMeta` | `import.meta` |
+| `NodeModule` | `node:module` |
+| `NodeOs` | `node:os` |
+| `NodePath` | `node:path` |
+| `NodeProcess` | the `process` global |
 | `NodeStreams` | `node:stream`, plus the stream-shaped parts of `node:fs` and `node:readline` |
+| `NodeUrl` | `node:url` |
 | `NodeZlib` | `node:zlib` |
 
+Every module specifier is `node:`-prefixed. Bare `"fs"` is what bundlers alias to a browser polyfill
+shim, and this repository bundles Lambda code archives; `node:fs` is unambiguous to Node and to every
+bundler.
+
+Coverage is demand-driven: these bind what the Reventless packages actually call, not the whole of
+each Node module. Where a Node API has an encoding or option argument that is only ever passed one
+way here, the binding bakes it in rather than accepting it — `NodeFs.readFileSync` is UTF-8 by
+construction, so no call site can pass `"utf-8"` and get a different, silently wrong, encoding.
+
+---
+
+## `NodeBuffer`
+
+`t` aliases `Uint8Array.t` rather than being abstract: a Node `Buffer` *is* a `Uint8Array` subclass,
+so stream chunks, `NodeFs.readFileSyncBuffer` results and `NodeFs.writeFileSyncBuffer` arguments are
+all the same values and flow between those calls without a cast.
+
+```rescript
+type t = Uint8Array.t
+
+let concat: array<t> => t              // assemble a body from its `data` chunks
+let fromStringUtf8: string => t
+let toStringUtf8: t => string
+```
+
+---
+
+## `NodeChildProcess`
+
+```rescript
+type execOptions = {cwd?: string, encoding?: string, env?: dict<string>, stdio?: array<string>, maxBuffer?: int}
+
+let execSync: (string, execOptions) => string
+let execFileSync: (string, array<string>, execOptions) => string
+
+type childProcess
+type spawnOptions = {cwd?: string, env?: dict<string>, stdio?: array<string>}
+
+let spawn: (string, array<string>, spawnOptions) => childProcess
+let exitCode: childProcess => Nullable.t<int>
+let kill: (childProcess, string) => bool
+```
+
+Prefer `execFileSync` over `execSync`: it takes the arguments as an array rather than interpolating
+them into a shell string, so an argument containing shell metacharacters stays one argument.
+
+`spawn` returns while the child is still alive, which is the reason to reach for it over
+`execFileSync`. `exitCode` is `null` until the child exits — the one honest way to ask "is it still
+alive?" without holding an event listener, so a caller polling for readiness can tell a slow start
+from a process that already died. `kill` returns whether the signal was delivered; `false` means the
+process was already gone, which is not an error.
+
+`spawnOptions.env` **replaces** the child's environment rather than extending it. Pass a copy of
+`NodeProcess.env` with the additions applied when the child still needs `PATH` and friends.
+
+---
+
+## `NodeCrypto`
+
+```rescript
+type buffer                            // abstract: only ever re-keyed or stringified
+let bufferToString: (buffer, string) => string
+
+type hash
+let createHash: string => hash
+let hashUpdate: (hash, string) => hash
+let hashUpdateBuffer: (hash, Uint8Array.t) => hash
+let hashDigest: (hash, string) => string
+let sha256Hex: string => string        // SHA-256 of a UTF-8 string, hex-encoded
+
+type hmac
+let createHmac: (string, string) => hmac
+let createHmacFromBuffer: (string, buffer) => hmac
+let hmacUpdate: (hmac, string) => hmac
+let hmacDigest: (hmac, string) => string
+let hmacDigestBuffer: hmac => buffer
+
+let randomBytes: int => buffer
+let randomUUID: unit => string
+```
+
+`sha256Hex` is the content hash content-addressed stores key their objects on (`sha256/<hash>`): the
+same bytes always yield the same digest, so an upload is idempotent and deduplicating.
+`createHmacFromBuffer` is the chained form — each round of an AWS SigV4 signing key takes the
+previous round's raw digest as its key.
+
+---
+
+## `NodeFs`
+
+```rescript
+let existsSync: string => bool
+let realpathSync: string => string
+
+let readFileSync: string => string           // UTF-8 baked in
+let readFileSyncBuffer: string => Uint8Array.t
+let writeFileSync: (string, string) => unit  // UTF-8 baked in
+let writeFileSyncBuffer: (string, Uint8Array.t) => unit
+
+type dirent
+let isDirectory: dirent => bool
+let isFile: dirent => bool
+let direntName: dirent => string
+
+type readdirOptions = {withFileTypes: bool}
+type mkdirOptions = {recursive?: bool}
+type rmOptions = {recursive?: bool, force?: bool}
+type cpOptions = {recursive?: bool}
+
+let readdirSync: (string, readdirOptions) => array<dirent>
+let mkdirSync: (string, mkdirOptions) => unit
+let mkdtempSync: string => string
+let unlinkSync: string => unit
+let rmSync: (string, rmOptions) => unit
+let cpSync: (string, string, cpOptions) => unit
+
+module Promises = {
+  let writeFile: (string, string) => promise<unit>
+  let mkdir: (string, mkdirOptions) => promise<Nullable.t<string>>
+  let rm: (string, rmOptions) => promise<unit>
+}
+```
+
+The `*Buffer` variants are the same Node calls without an encoding, which is what makes Node return
+raw bytes rather than a decoded string. `Promises` is a separate module because `node:fs/promises` is
+a separate specifier — not a wrapper this package adds over the sync calls.
+
+---
+
+## `NodeImportMeta`
+
+```rescript
+let url: string       // import.meta.url
+let dirname: string   // import.meta.dirname
+let filename: string  // import.meta.filename
+```
+
+These resolve to the location of the module that *reads* them, which is what makes binding a
+per-module value in a shared package sound at all: `@val` externals are inlined at the use site
+rather than re-exported by this one. The corollary is that there are no helpers here — a function
+defined in this module would report *this* file's location, so compute from the values at the call
+site instead.
+
+```rescript
+// The file sitting next to the module that asks for it.
+let hintsFile = NodePath.resolve([NodeImportMeta.dirname, "../ui-hints.json"])
+```
+
+`dirname` and `filename` are Node's own additions to `import.meta` and are defined only for `file:`
+URLs; a bundler that rewrites modules to CommonJS drops them. `url` is the portable form and the one
+to reach for when either could apply.
+
+---
+
+## `NodeModule`
+
+```rescript
+type require
+let createRequire: string => require
+let requireResolve: (require, string) => string
+let builtinModules: array<string>
+```
+
+`createRequire` is how an ESM module gets at CommonJS resolution, which is what `require.resolve` is
+wanted for: locating a dependency's on-disk path without importing it. `builtinModules` lists Node's
+built-ins, both bare and `node:`-only entries such as `node:test`, plus subpath forms like
+`fs/promises`.
+
+---
+
+## `NodeOs`
+
+```rescript
+let tmpdir: unit => string
+```
+
+---
+
+## `NodePath`
+
+```rescript
+let join: array<string> => string      // variadic
+let resolve: array<string> => string   // variadic
+let dirname: string => string
+let basename: string => string
+let relative: (string, string) => string
+let sep: string
+```
+
+`join` and `resolve` are variadic, a strict superset of the two-argument forms they replace, so no
+call site loses expressiveness. A two-argument `join` and a variadic one are not duplicates — they
+are different functions with the same name, and which one a call site got used to depend on which
+inline binding block it happened to sit near.
+
+---
+
+## `NodeProcess`
+
+```rescript
+let argv: array<string>
+let env: dict<string>
+let cwd: unit => string
+let chdir: string => unit
+let exit: int => unit
+
+type stream
+let stdin: stream
+let stdout: stream
+let write: (stream, string) => unit
+let pause: stream => unit
+let unref: stream => unit
+let isTTY: stream => option<bool>
+```
+
+`process` is a global rather than a module specifier, so these are `@val` bindings under
+`@scope("process")`.
+
+`isTTY` is `option<bool>`, not `bool`: Node sets it to `true` on an interactive stream and leaves it
+**undefined** otherwise — it is never `false`. A `bool`-typed binding reads that undefined as a valid
+`false`, which happens to work and is still lying about the value.
+
+---
+
+## `NodeUrl`
+
+```rescript
+let fileURLToPath: string => string
+let pathToFileURL: string => {"href": string}
+```
+
+Only the two path/URL converters. The `URL` class itself is a WHATWG global rather than a `node:`
+import, so it belongs to `rescript-web`, not here.
+
 ---
 
 ## `NodeStreams`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/rescript-node",
-  "version": "2.0.0-alpha.1",
+  "version": "2.0.0-alpha.10",
   "description": "ReScript bindings for the Node.js standard library",
   "license": "Apache-2.0",
   "devDependencies": {

package/rescript.json

@@ -15,9 +15,11 @@
       "dir": "src",
       "subdirs": true,
       "public": [
+        "NodeBuffer",
         "NodeChildProcess",
         "NodeCrypto",
         "NodeFs",
+        "NodeImportMeta",
         "NodeModule",
         "NodeOs",
         "NodePath",

package/src/NodeBuffer.res

@@ -0,0 +1,30 @@
+/** Bindings for Node's global [`Buffer`](https://nodejs.org/api/buffer.html).
+
+    `t` aliases `Uint8Array.t` rather than being abstract: a Node `Buffer` *is* a
+    `Uint8Array` subclass, so the bytes a stream hands over, the bytes
+    {!NodeFs.readFileSyncBuffer} returns, and the bytes {!NodeFs.writeFileSyncBuffer}
+    takes are all the same values. Aliasing lets them flow between those calls
+    without a cast that would exist only to satisfy the type checker. */
+type t = Uint8Array.t
+
+/** Joins byte chunks into one buffer — how a request body is assembled from the
+    chunks its `data` events deliver. */
+@val @scope("Buffer")
+external concat: array<t> => t = "concat"
+
+/** Bakes the encoding in for the same reason {!NodeFs.readFileSync} does: the
+    `(string, string)` form permits a different, silently wrong, encoding name. */
+@val @scope("Buffer")
+external fromStringUtf8: (string, @as("utf8") _) => t = "from"
+
+/** Base64url, the alphabet a bearer token's segments are encoded in. Decoding
+    never throws — a segment that is not base64url yields whatever bytes it can,
+    so callers judge the result by whether it parses. */
+@val @scope("Buffer")
+external fromStringBase64Url: (string, @as("base64url") _) => t = "from"
+
+@send
+external toStringUtf8: (t, @as("utf8") _) => string = "toString"
+
+@send
+external toStringBase64Url: (t, @as("base64url") _) => string = "toString"

package/src/NodeBuffer.res.mjs

@@ -0,0 +1,2 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+/* This output is empty. Its source's type definitions, externals and/or unused code got optimized away. */

package/src/NodeChildProcess.res

@@ -16,3 +16,32 @@ external execSync: (string, execOptions) => string = "execSync"
     string, so an argument containing shell metacharacters stays one argument. */
 @module("node:child_process")
 external execFileSync: (string, array<string>, execOptions) => string = "execFileSync"
+
+/** A running child process. Unlike the `*Sync` calls above, `spawn` returns
+    while the child is still alive, so the caller keeps working alongside it —
+    which is the whole reason to reach for this over `execFileSync`. */
+type childProcess
+
+type spawnOptions = {
+  cwd?: string,
+  /** Replaces the child's environment entirely rather than extending it. Pass
+      a copy of `NodeProcess.env` with the additions applied when the child
+      still needs PATH and friends. */
+  env?: dict<string>,
+  /** Per-descriptor disposition: `"ignore"`, `"inherit"`, or `"pipe"`, in
+      stdin/stdout/stderr order. */
+  stdio?: array<string>,
+}
+
+@module("node:child_process")
+external spawn: (string, array<string>, spawnOptions) => childProcess = "spawn"
+
+/** `null` while the child is running, its exit code once it has exited. The
+    one honest way to ask "is it still alive?" without holding an event
+    listener — a caller polling for readiness checks this to tell a slow start
+    from a process that already died. */
+@get external exitCode: childProcess => Nullable.t<int> = "exitCode"
+
+/** Signal the child. Returns whether the signal was delivered — `false` once
+    the process is already gone, which is not an error. */
+@send external kill: (childProcess, string) => bool = "kill"

package/src/NodeFs.res

@@ -17,6 +17,15 @@ external existsSync: string => bool = "existsSync"
 @module("node:fs")
 external realpathSync: string => string = "realpathSync"
 
+/** Set a file's access and modification times, in seconds since the epoch.
+
+    The reason this exists here rather than as a shell-out to `touch`: a build
+    whose compiler caches on source mtime cannot be made to re-run a side effect
+    of compilation — emitting a sidecar, say — by any argument passed to it. The
+    input has to look newer. */
+@module("node:fs")
+external utimesSync: (string, float, float) => unit = "utimesSync"
+
 // ── Reading ──────────────────────────────────────────────────────────────────
 
 @module("node:fs")
@@ -32,6 +41,40 @@ external readFileSyncBuffer: string => Uint8Array.t = "readFileSync"
 @module("node:fs")
 external writeFileSync: (string, string, @as("utf8") _) => unit = "writeFileSync"
 
+/** The byte-oriented companion to {!writeFileSync}, mirroring
+    {!readFileSyncBuffer}: no encoding to bake in, because the payload is
+    already bytes. */
+@module("node:fs")
+external writeFileSyncBuffer: (string, Uint8Array.t) => unit = "writeFileSync"
+
+// ── Watching ─────────────────────────────────────────────────────────────────
+
+/** A handle from {!watch}. Held so it can be closed, and so it can be `unref`ed
+    — an active watcher keeps the event loop alive, which turns a stray watch in
+    a test into a run that never exits. */
+type watcher
+
+/** Stop watching. */
+@send external watcherClose: watcher => unit = "close"
+
+/** Take the watcher off the event loop's reference count, so it never by itself
+    keeps the process running. Returns the same watcher, as Node does. */
+@send external watcherUnref: watcher => watcher = "unref"
+
+/** [`fs.watch`](https://nodejs.org/api/fs.html#fswatchfilename-options-listener).
+
+    The listener takes the event type (`"rename"` or `"change"`) and the
+    basename, which Node may report as null on some platforms — hence
+    `Nullable.t`.
+
+    **Watch the directory, not the file**, when the file is one an editor
+    writes: a save that replaces rather than rewrites (write-temp-then-rename,
+    which is how most editors save atomically) gives the path a new inode, and a
+    watcher registered on the old one goes silent with no error. Watching the
+    containing directory and filtering on the basename survives that. */
+@module("node:fs")
+external watch: (string, (string, Nullable.t<string>) => unit) => watcher = "watch"
+
 // ── Directories ──────────────────────────────────────────────────────────────
 
 type dirent

package/src/NodeImportMeta.res

@@ -0,0 +1,20 @@
+/** Bindings for [`import.meta`](https://nodejs.org/api/esm.html#importmeta).
+
+    `@val` externals are inlined at the use site rather than re-exported by this
+    module, so each of these resolves to the location of the module that *reads*
+    it — which is the only reason binding a per-module value from a shared
+    package is sound. Reading one through a wrapper function defined here would
+    return this file's location instead, so there are no helpers below.
+
+    `dirname` and `filename` are Node's own additions and are defined only for
+    `file:` URLs; a bundler that rewrites modules to CommonJS drops them. `url`
+    is the portable form and the one to reach for when either could apply. */
+
+@val @scope(("import", "meta"))
+external url: string = "url"
+
+@val @scope(("import", "meta"))
+external dirname: string = "dirname"
+
+@val @scope(("import", "meta"))
+external filename: string = "filename"

package/src/NodeImportMeta.res.mjs

@@ -0,0 +1,2 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+/* This output is empty. Its source's type definitions, externals and/or unused code got optimized away. */

package/src/NodeModule.res

@@ -10,3 +10,8 @@ type require
 external createRequire: string => require = "createRequire"
 
 @send external requireResolve: (require, string) => string = "resolve"
+
+/** The names of Node's built-in modules (both bare and some `node:`-only
+    entries like `node:test`), plus subpath forms such as `fs/promises`. */
+@module("node:module")
+external builtinModules: array<string> = "builtinModules"

package/src/NodeNet.res

@@ -0,0 +1,45 @@
+/** Bindings for [`node:net`](https://nodejs.org/api/net.html) — TCP servers and
+    the sockets they accept. */
+
+type socket
+type server
+
+/** A connected client. `write` returns the backpressure flag, which a caller
+    that only ever sends short lines can ignore. */
+@send external write: (socket, string) => bool = "write"
+@send external destroySocket: socket => unit = "destroy"
+
+/** `setEncoding` makes the `data` frames arrive as strings rather than Buffers,
+    which is what a line-oriented consumer wants. */
+@send external setEncoding: (socket, string) => unit = "setEncoding"
+
+@send external onSocketData: (socket, @as("data") _, string => unit) => unit = "on"
+@send external onSocketClose: (socket, @as("close") _, unit => unit) => unit = "on"
+
+/** A socket that errors is gone; without a listener the error is thrown and
+    takes the process with it, so every accepted socket needs one. */
+@send external onSocketError: (socket, @as("error") _, JsExn.t => unit) => unit = "on"
+
+/** `keepAlive` is deliberately absent: a caller that wants it sets it per
+    socket, and defaulting it changes the behaviour of every consumer. */
+@module("node:net")
+external createServer: (socket => unit) => server = "createServer"
+
+/** Binding to an explicit host is what keeps a server off every interface —
+    pass `"127.0.0.1"` for loopback-only. */
+@send external listen: (server, int, string, unit => unit) => unit = "listen"
+
+@send external onServerError: (server, @as("error") _, JsExn.t => unit) => unit = "on"
+@send external closeServer: (server, unit => unit) => unit = "close"
+
+/** The port actually bound — the only way to learn it after listening on `0`.
+    `Nullable`, because a server that is not listening reports `null`. */
+@send external address: server => Nullable.t<{"port": int}> = "address"
+
+/** Lets the process exit while the server is still listening — a diagnostic
+    listener must not be the reason a CLI hangs at the end of its work. */
+@send external unref: server => unit = "unref"
+
+/** Connect to a listening server. The callback fires once the connection is up. */
+@module("node:net")
+external connect: (int, string, unit => unit) => socket = "createConnection"

package/src/NodeNet.res.mjs

@@ -0,0 +1,2 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+/* This output is empty. Its source's type definitions, externals and/or unused code got optimized away. */

package/src/NodeProcess.res

@@ -21,6 +21,30 @@ external chdir: string => unit = "chdir"
 @val @scope("process")
 external exit: int => unit = "exit"
 
+@val @scope("process")
+external pid: int = "pid"
+
+/** Signalling another process — or, with signal `0`, asking whether it is still
+    there without disturbing it. Throws when the pid is gone (`ESRCH`) or not
+    ours to signal (`EPERM`), so a liveness check is a `try`. */
+@val @scope("process")
+external kill: (int, int) => unit = "kill"
+
+/** `process.on` for the two shutdown paths a CLI has to clean up on.
+
+    Split into an `exit` binding and a signal binding because the handlers are
+    not interchangeable: `exit` fires with the exit code and may only do
+    synchronous work, while a signal handler receives the signal name and fires
+    *before* the process is committed to leaving — code that registers one and
+    expects the other's timing gets a cleanup that never runs. Signals are a
+    polyvariant so a typo is a compile error rather than a handler that is never
+    called. */
+@val @scope("process")
+external onExit: (@as("exit") _, int => unit) => unit = "on"
+
+@val @scope("process")
+external onSignal: ([#SIGINT | #SIGTERM | #SIGHUP], unit => unit) => unit = "on"
+
 /** The standard streams. `write`, `isTTY`, `pause` and `unref` are what the
     interactive prompts in this repository reach for; the type is abstract so it
     can also be handed to `readline.createInterface`. */