@smthrs/platform-node 0.0.0-stage → 1.0.0-rc.3

package/dist/vendor/platform-node-shared.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @since 4.0.0
+ */
+/**
+ * @since 4.0.0
+ */
+export * as NodeChildProcessSpawner from "./node-shared/NodeChildProcessSpawner.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeClusterSocket from "./node-shared/NodeClusterSocket.ts";
+/**
+ * @since 1.0.0
+ */
+export * as NodeCrypto from "./node-shared/NodeCrypto.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeFileSystem from "./node-shared/NodeFileSystem.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeHttpCompression from "./node-shared/NodeHttpCompression.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodePath from "./node-shared/NodePath.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeRuntime from "./node-shared/NodeRuntime.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeSink from "./node-shared/NodeSink.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeSocket from "./node-shared/NodeSocket.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeSocketServer from "./node-shared/NodeSocketServer.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeStdio from "./node-shared/NodeStdio.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeStream from "./node-shared/NodeStream.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeTerminal from "./node-shared/NodeTerminal.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/vendor/platform-node-shared.js

@@ -0,0 +1,58 @@
+import "./chunk-M7CLUILA.js";
+import {
+  NodeRuntime_exports
+} from "./chunk-LEUPYT3Q.js";
+import {
+  NodeStdio_exports
+} from "./chunk-B3FZ67QU.js";
+import {
+  NodeTerminal_exports
+} from "./chunk-TXKLEBBL.js";
+import {
+  NodePath_exports
+} from "./chunk-54RLBMTZ.js";
+import {
+  NodeChildProcessSpawner_exports
+} from "./chunk-QPLDT6A6.js";
+import "./chunk-EGBNVEEW.js";
+import {
+  NodeClusterSocket_exports
+} from "./chunk-Y35ZAO5U.js";
+import {
+  NodeSocketServer_exports
+} from "./chunk-DWSHTSVX.js";
+import {
+  NodeSocket_exports
+} from "./chunk-JJ24ARBQ.js";
+import {
+  NodeCrypto_exports
+} from "./chunk-UFH5UUZK.js";
+import {
+  NodeHttpCompression_exports
+} from "./chunk-3GR5VZ2M.js";
+import {
+  NodeFileSystem_exports
+} from "./chunk-BKTBUBQY.js";
+import "./chunk-42QKY6T6.js";
+import {
+  NodeStream_exports
+} from "./chunk-XH4U3JSV.js";
+import {
+  NodeSink_exports
+} from "./chunk-OXNGN5H7.js";
+import "./chunk-MLKGABMK.js";
+export {
+  NodeChildProcessSpawner_exports as NodeChildProcessSpawner,
+  NodeClusterSocket_exports as NodeClusterSocket,
+  NodeCrypto_exports as NodeCrypto,
+  NodeFileSystem_exports as NodeFileSystem,
+  NodeHttpCompression_exports as NodeHttpCompression,
+  NodePath_exports as NodePath,
+  NodeRuntime_exports as NodeRuntime,
+  NodeSink_exports as NodeSink,
+  NodeSocket_exports as NodeSocket,
+  NodeSocketServer_exports as NodeSocketServer,
+  NodeStdio_exports as NodeStdio,
+  NodeStream_exports as NodeStream,
+  NodeTerminal_exports as NodeTerminal
+};

package/dist/vendor/platform-node.d.ts

@@ -0,0 +1,100 @@
+/**
+ * @since 4.0.0
+ */
+/**
+ * @since 4.0.0
+ */
+export * as NodeChildProcessSpawner from "./node/NodeChildProcessSpawner.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeClusterHttp from "./node/NodeClusterHttp.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeClusterSocket from "./node/NodeClusterSocket.ts";
+/**
+ * @since 1.0.0
+ */
+export * as NodeCrypto from "./node/NodeCrypto.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeFileSystem from "./node/NodeFileSystem.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeHttpClient from "./node/NodeHttpClient.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeHttpIncomingMessage from "./node/NodeHttpIncomingMessage.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeHttpPlatform from "./node/NodeHttpPlatform.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeHttpServer from "./node/NodeHttpServer.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeHttpServerRequest from "./node/NodeHttpServerRequest.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeMultipart from "./node/NodeMultipart.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeMultipartParser from "./node/NodeMultipartParser.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodePath from "./node/NodePath.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeRedis from "./node/NodeRedis.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeRuntime from "./node/NodeRuntime.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeServices from "./node/NodeServices.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeSink from "./node/NodeSink.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeSocket from "./node/NodeSocket.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeSocketServer from "./node/NodeSocketServer.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeStdio from "./node/NodeStdio.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeStream from "./node/NodeStream.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeTerminal from "./node/NodeTerminal.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeWorker from "./node/NodeWorker.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeWorkerRunner from "./node/NodeWorkerRunner.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/vendor/platform-node.js

@@ -0,0 +1,115 @@
+import "./chunk-ZJMRMY57.js";
+import {
+  NodeSocketServer_exports
+} from "./chunk-6ME2W7TF.js";
+import {
+  NodeWorker_exports
+} from "./chunk-JG5TTWPT.js";
+import {
+  NodeWorkerRunner_exports
+} from "./chunk-DVOAHXPG.js";
+import {
+  NodeHttpServerRequest_exports
+} from "./chunk-MBSKBQ5D.js";
+import {
+  NodeRedis_exports
+} from "./chunk-NBVRTDTV.js";
+import {
+  NodeRuntime_exports
+} from "./chunk-EZWY45HP.js";
+import "./chunk-LEUPYT3Q.js";
+import {
+  NodeClusterHttp_exports
+} from "./chunk-RO2R4MJH.js";
+import {
+  NodeHttpServer_exports
+} from "./chunk-SIR62W3Y.js";
+import {
+  NodeSocket_exports
+} from "./chunk-5ZMHBXIK.js";
+import {
+  NodeMultipart_exports
+} from "./chunk-GXCHI7BM.js";
+import {
+  NodeMultipartParser_exports
+} from "./chunk-2Y7WC4KU.js";
+import {
+  NodeServices_exports
+} from "./chunk-AMQKOQNT.js";
+import {
+  NodeStdio_exports
+} from "./chunk-KUUXSID7.js";
+import "./chunk-B3FZ67QU.js";
+import {
+  NodeTerminal_exports
+} from "./chunk-XDKNKFBW.js";
+import "./chunk-TXKLEBBL.js";
+import {
+  NodePath_exports
+} from "./chunk-TFIKFFSC.js";
+import "./chunk-54RLBMTZ.js";
+import {
+  NodeChildProcessSpawner_exports
+} from "./chunk-QYBKAIA6.js";
+import "./chunk-QPLDT6A6.js";
+import "./chunk-EGBNVEEW.js";
+import {
+  NodeClusterSocket_exports
+} from "./chunk-FNZOJHSV.js";
+import "./chunk-Y35ZAO5U.js";
+import "./chunk-DWSHTSVX.js";
+import "./chunk-JJ24ARBQ.js";
+import {
+  NodeCrypto_exports
+} from "./chunk-VZBDV3TV.js";
+import "./chunk-UFH5UUZK.js";
+import {
+  NodeHttpClient_exports
+} from "./chunk-KOZMM5PZ.js";
+import {
+  NodeSink_exports
+} from "./chunk-IIJ52ZU6.js";
+import {
+  NodeHttpIncomingMessage_exports
+} from "./chunk-J7A4CZDO.js";
+import {
+  NodeHttpPlatform_exports
+} from "./chunk-VANKHF46.js";
+import "./chunk-3GR5VZ2M.js";
+import {
+  NodeFileSystem_exports
+} from "./chunk-M32LDTW7.js";
+import "./chunk-BKTBUBQY.js";
+import "./chunk-42QKY6T6.js";
+import {
+  NodeStream_exports
+} from "./chunk-DS7GF46S.js";
+import "./chunk-XH4U3JSV.js";
+import "./chunk-OXNGN5H7.js";
+import "./chunk-MLKGABMK.js";
+export {
+  NodeChildProcessSpawner_exports as NodeChildProcessSpawner,
+  NodeClusterHttp_exports as NodeClusterHttp,
+  NodeClusterSocket_exports as NodeClusterSocket,
+  NodeCrypto_exports as NodeCrypto,
+  NodeFileSystem_exports as NodeFileSystem,
+  NodeHttpClient_exports as NodeHttpClient,
+  NodeHttpIncomingMessage_exports as NodeHttpIncomingMessage,
+  NodeHttpPlatform_exports as NodeHttpPlatform,
+  NodeHttpServer_exports as NodeHttpServer,
+  NodeHttpServerRequest_exports as NodeHttpServerRequest,
+  NodeMultipart_exports as NodeMultipart,
+  NodeMultipartParser_exports as NodeMultipartParser,
+  NodePath_exports as NodePath,
+  NodeRedis_exports as NodeRedis,
+  NodeRuntime_exports as NodeRuntime,
+  NodeServices_exports as NodeServices,
+  NodeSink_exports as NodeSink,
+  NodeSocket_exports as NodeSocket,
+  NodeSocketServer_exports as NodeSocketServer,
+  NodeStdio_exports as NodeStdio,
+  NodeStream_exports as NodeStream,
+  NodeTerminal_exports as NodeTerminal,
+  NodeWorker_exports as NodeWorker,
+  NodeWorkerRunner_exports as NodeWorkerRunner
+};

package/docs/README.md

@@ -0,0 +1,129 @@
+---
+title: "@smthrs/platform-node"
+description: "The Node.js host bundle for Smithers flows: Effect's Node platform services plus a filesystem a symlink cannot redirect, child processes a crashed host does not abandon, and a run-owner liveness probe."
+---
+
+`@smthrs/platform-node` provides the five services a program on Node.js runs
+its side effects through: a filesystem, a path helper, a child-process spawner,
+a [Jujutsu](https://jj-vcs.github.io/jj/) adapter, and an HTTP client. One
+layer, `NodeHost.layer`, provides all five.
+
+That set is the host surface of [Smithers](https://smithers.sh/docs/installation/), a durable
+engine for long-running agent work whose packages carry the `@smthrs` scope.
+This package is the Node.js machine a Smithers flow runs on, and it is usable
+on its own by any Effect program that wants the same guarantees.
+
+## Availability
+
+`@smthrs/platform-node` is not on npm at 1.0.0-rc.0. Its source lives in the
+[smithers repository](https://github.com/smithersai/smithers), and
+[Installation](./installation.md) covers how to depend on it from a checkout
+and which `effect` version it pins.
+
+## What it solves
+
+Effect already ships Node implementations of most of those services, and this
+package uses them where they fit. Three guarantees are not ones a
+general-purpose adapter makes, so this package implements them itself.
+
+**A filesystem a symlink cannot redirect.** A permission check names a path,
+and a path-based operation resolves that path again when it runs. Anything with
+write access to the directory can swap a component for a symlink in between, so
+the operation authorized for one file performs on another. `AtomicFileSystem`
+closes that window: it opens the workspace root once, walks each component with
+`O_NOFOLLOW`, and performs the final syscall relative to a pinned directory
+descriptor, which names an inode rather than a name.
+
+**Child processes a crashed host does not leave behind.** A host killed
+outright runs no finalizer, so the agents and builds it started keep running
+with nobody left to signal them. `NodeHost.layerContained` gives every child a
+`SIGTERM`-then-`SIGKILL` deadline and a durable ledger record, and sweeps the
+records a previous incarnation abandoned while the layer is built. The POSIX
+supervisor keeps ownership after a natural target exit and requests cleanup
+when its private parent connection closes. Cleanup must be verified before a
+record retires.
+
+**An honest answer about whether a run's owner is still alive.**
+`HostLiveness.isAlive` is the probe a durable engine consults before it takes a
+run some other process recorded itself as owning. Both ways of being wrong cost
+something, so the rule resolves ambiguity toward alive: stranding a run is
+cheaper than running it twice.
+
+## Run something through the host
+
+Provide `NodeHost.layer` to any program that asks for a host service. This one
+asks for the spawner:
+
+```ts
+import { NodeHost } from "@smthrs/platform-node"
+import * as Effect from "effect/Effect"
+import * as ChildProcess from "effect/unstable/process/ChildProcess"
+import { ChildProcessSpawner } from "effect/unstable/process/ChildProcessSpawner"
+
+const program = Effect.gen(function*() {
+  const spawner = yield* ChildProcessSpawner
+  return yield* spawner.string(ChildProcess.make("git", ["status", "--short"]))
+})
+
+console.log(await Effect.runPromise(Effect.provide(program, NodeHost.layer)))
+```
+
+`ChildProcess` and `ChildProcessSpawner` are Effect's own tags. There is no
+Smithers wrapper around either: a wall-clock budget is `Effect.timeout` around
+the effect, and cancelling a command is fiber interruption. The same layer also
+provided the `FileSystem`, `Path`, `Jj`, and `HttpClient` that program did not
+ask for, and the filesystem in it is the confined one described earlier. The
+[quickstart](./quickstart.md) runs a program that reads a file through it and
+watches a symlink escape get refused.
+
+Running this bundle needs Node.js 26.4.0 or later and the `smithers-jj-export`
+helper, which `AtomicFileSystem` uses for the descriptor-relative syscalls Node
+does not expose. [Installation](./installation.md) covers the requirement,
+where it fails when it is missing, how to point at a different helper, and the
+Effect peers your project pins.
+
+## How this relates to @smthrs/flows
+
+[`@smthrs/flows`](/api/flows) is the single dependency that carries the whole
+Smithers durable flow engine: flows, actions, the journal, and the runtime that
+replays a crashed run from where it stopped. It deliberately does not
+re-export any `@smthrs/platform-*` package, for the same reason `effect`'s own
+index does not re-export `@effect/platform-node`: the program that runs picks
+its platform, not the library it depends on. So a Node program installs
+`@smthrs/flows` for the engine and this package for the machine underneath it.
+
+Once both are installed, `@smthrs/flows`' `NodeRuntime` module builds the whole
+durable composition from one options object, and what it composes from here is
+`NodeHost.layerContainedAt` plus `HostLiveness.isAlive`. Read this site when
+you want to know what those layers guarantee, configure the filesystem helper,
+or diagnose a refusal. Reach for this package on its own when you want the host
+services without the engine.
+
+Above both sits the `smithers` command-line tool,
+[`@smthrs/cli`](/api/cli), which runs flows without you composing anything.
+For a different runtime, the sibling bundles are
+[`@smthrs/platform-bun`](/api/platform-bun) and
+[`@smthrs/platform-browser`](/api/platform-browser).
+[`@smthrs/kernel`](/api/kernel) owns the closed list of five host tags and
+wraps each one with the capability check that makes the confinement above
+enforceable.
+
+## Where to go next
+
+- [Installation](./installation.md): peers, host prerequisites, import forms,
+  and what a capability-checked composition adds.
+- [Quickstart](./quickstart.md): run a command, then read a file through the
+  guarded host and watch an escape refused.
+- [The host bundle](./concepts/host-bundle.md): the five tags, the four layers,
+  and what this package deliberately does not provide.
+- [The descriptor-relative filesystem](./concepts/descriptor-relative-filesystem.md):
+  how the confinement works and what each call costs.
+- [Process containment](./concepts/process-containment.md): incarnations, the
+  ledger, and every guard checked before a reap.
+- [API reference](./api.md): every export, layer, and option.
+- [Troubleshooting](./troubleshooting.md): the refusals this bundle reports and
+  which of them are the safe answer.
+
+The host exports `implementationIds` for its five service slots. Its rooted
+factories reject invalid roots before constructing a layer, using the host's
+own error with code `invalid_repository_root`.