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

package/docs/quickstart.md

@@ -0,0 +1,147 @@
+---
+title: "Quickstart"
+description: "Stand up the Node host, run a command and read a file through it, then wrap it in the capability kernel and watch a symlink escape get refused."
+sidebar:
+  order: 2
+---
+
+This quickstart runs one program against the Node host twice: once raw, and
+once behind the capability kernel with a workspace root. By the end you will
+have seen the bundle do real work and refuse a real escape, and you will know
+which layer is responsible for each.
+
+## Prerequisites
+
+- Node.js 26.4.0 or later, on a POSIX host.
+- The `smithers-jj-export` helper. From a source checkout, run
+  `cargo build --locked --release -p smithers-ffi --bin smithers-jj-export`.
+- `jj` 0.39.0 or newer on `PATH`. Check with `jj --version`. Every complete
+  `NodeHost` layer checks jj at construction, including this quickstart's
+  filesystem and process examples. For applications that do not need jj, see
+  [Individual services without jj](./installation.md#individual-services-without-jj).
+- `@smthrs/platform-node`, [`@smthrs/kernel`](/api/kernel), and their `effect`
+  peers resolvable from the file you are about to write.
+  [Installation](./installation.md) has the workspace form.
+
+## Run a command through the raw host
+
+Create `quickstart.ts`. `NodeHost.layer` provides all five host tags, so a
+program that asks for `ChildProcessSpawner` gets Effect's Node 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 runCommand = Effect.gen(function*() {
+  const spawner = yield* ChildProcessSpawner
+  return yield* spawner.string(ChildProcess.make("printf", ["hello from node"]))
+})
+
+console.log(await Effect.runPromise(Effect.provide(runCommand, NodeHost.layer)))
+```
+
+```text
+hello from node
+```
+
+Nothing here is a Smithers wrapper. `ChildProcess` and `ChildProcessSpawner`
+are Effect's own tags; this package supplies the implementation and nothing
+else. A wall-clock budget is `Effect.timeout` around the effect, and
+cancelling a command is fiber interruption.
+
+## Build a workspace with an escape in it
+
+The filesystem is where this bundle differs from Effect's Node adapter, so give
+it something to refuse. Create a workspace directory with one ordinary file
+inside it, and one symlink pointing at a file outside it:
+
+```ts
+import { mkdirSync, mkdtempSync, symlinkSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+
+const container = mkdtempSync(join(tmpdir(), "platform-node-quickstart-"))
+const workspace = join(container, "workspace")
+const secret = join(container, "secret.txt")
+
+mkdirSync(workspace)
+writeFileSync(join(workspace, "inside.txt"), "confined\n")
+writeFileSync(secret, "outside\n")
+symlinkSync(secret, join(workspace, "escape.txt"))
+```
+
+## Compose the guarded host
+
+`HostServices.layer` from [`@smthrs/kernel`](/api/kernel) decorates every one
+of the five tags with a capability check. It needs the workspace root that
+bounds the filesystem, and a grant store that answers the permission
+questions. For this local trial, use the allow-all store, so that the only
+thing left refusing anything is the confinement itself. `GrantStore.layerNoop`
+is a seam for tests and boot paths, not a production policy; a real host
+answers with rules, as
+[Write a capability policy](https://kernel.smithers.sh/guides/write-a-capability-policy/)
+shows:
+
+```ts
+import * as GrantStore from "@smthrs/kernel/GrantStore"
+import * as HostServices from "@smthrs/kernel/HostServices"
+import * as Workspace from "@smthrs/kernel/Workspace"
+import * as Layer from "effect/Layer"
+
+const guarded = HostServices.layer.pipe(
+  Layer.provide(NodeHost.layer),
+  Layer.provide(Workspace.layer(workspace)),
+  Layer.provide(GrantStore.layerNoop)
+)
+```
+
+## Read both files
+
+Read the ordinary file, then read through the symlink and keep the failure
+instead of the success:
+
+```ts
+import * as FileSystem from "effect/FileSystem"
+
+const readBoth = Effect.gen(function*() {
+  const fs = yield* FileSystem.FileSystem
+  const inside = yield* fs.readFileString(join(workspace, "inside.txt"))
+  const refusal = yield* Effect.flip(fs.readFileString(join(workspace, "escape.txt")))
+  return { inside: inside.trim(), refusedWith: refusal.reason._tag }
+})
+
+console.log(await Effect.runPromise(Effect.provide(readBoth, guarded)))
+```
+
+```text
+{ inside: 'confined', refusedWith: 'PermissionDenied' }
+```
+
+## What just happened
+
+The first read walked the workspace with directory descriptors and opened a
+regular file. The second read reached a symlink, and the walk refuses to
+traverse one, so the operation failed with a typed `PermissionDenied` before
+anything outside the workspace was opened. The grant store allowed both reads:
+the refusal came from the descriptor-relative walk, not from a permission rule.
+
+That is the property the bundle exists for. A path check followed by a
+path-based open leaves a window in which the path can be swapped; performing
+the operation relative to a pinned descriptor closes it. See
+[The descriptor-relative filesystem](./concepts/descriptor-relative-filesystem.md)
+for how the helper does it and what else it refuses.
+
+## Next steps
+
+- [Contain child processes](./guides/contain-child-processes.md): give every
+  spawned process a kill deadline and a durable record, so a crashed host
+  leaves nothing running.
+- [Configure the filesystem helper](./guides/configure-the-filesystem-helper.md):
+  point at a different helper, and set the ceilings that bound a wide
+  fan-out.
+- [The host bundle](./concepts/host-bundle.md): the five tags, the four layers,
+  and what the bundle deliberately does not provide.
+- [Troubleshooting](./troubleshooting.md): what to do when every filesystem
+  call fails closed.

package/docs/troubleshooting.md

@@ -0,0 +1,130 @@
+---
+title: "Troubleshooting"
+description: "The failures this Node bundle reports: filesystem refusals from the atomic helper, liveness verdicts that look wrong, reaper outcomes that will not retire a record, and Windows behaviour."
+---
+
+The failures here come from three places: the atomic filesystem helper, the
+host liveness probe, and the process reaper. Each answers deliberately, and
+several answers that look like bugs are the safe choice.
+
+## A filesystem call fails with `ENOTSUP`
+
+**Symptom.** An atomic operation fails with:
+
+```text
+atomic operation is unsupported
+```
+
+**Cause.** The helper was asked for an operation it does not implement. Every
+operation is named explicitly, so an unrecognized one is refused rather than
+approximated.
+
+**Fix.** Use one of the supported operations. If you reached this through a
+higher-level API, the operation name in the error identifies which call needs
+a different route.
+
+## A glob fails with `EFBIG`
+
+**Symptom.**
+
+```text
+glob result exceeds the response limit
+```
+
+**Cause.** The match set was larger than the helper's response limit. The
+limit is enforced while matches accumulate, not after, so a runaway pattern
+fails fast instead of buffering without bound.
+
+**Fix.** Narrow the pattern, or root it at a deeper directory. See
+[match files with a glob pattern](./guides/match-files-with-glob.md).
+
+## Every filesystem call fails on Windows
+
+**Cause.** This is intended. Windows is an unsupported platform, and
+`AtomicFileSystem` fails every filesystem call closed there rather than
+half-working.
+
+**Fix.** Run the durable engine on a supported platform. There is no flag to
+enable a partial Windows path: a filesystem that confines some operations and
+not others is worse than one that says it confines none.
+
+## A run's owner reads as alive when the process is gone
+
+**Cause.** The liveness probe fails safe. Only `ESRCH` from a signal-0 probe
+counts as gone. `EPERM` means the pid exists and belongs to another user,
+which is still a live owner. A throw carrying no code at all, including a
+thrown string or `null`, is an answer nobody gave, and so also reads as alive.
+
+This matters because the engine consults the probe before taking a run whose
+recorded owner it is not: a wrong `true` strands a run, and a wrong `false`
+runs it twice. Stranding is the cheaper mistake, so ambiguity resolves to
+alive.
+
+**Fix.** Nothing here is broken. If a run is genuinely stranded, retire the
+owner record rather than weakening the probe. See
+[answer whether a run owner is alive](./guides/answer-run-ownership.md).
+
+## The liveness probes disagree on a foreign host
+
+**Cause.** Both probes use the same `ESRCH`-only death rule.
+`EPERM`, `EINVAL`, and unknown signal errors preserve liveness.
+For a valid same-host pid, signal errors do not distinguish the probes.
+
+`HostLiveness.isAlive` compares the owner's host with its configured `hostId`
+and reports foreign owners as alive. `Ownership.sameHostPidProbe` compares
+with `context.claimant.hostId` and returns `false` for a foreign owner without
+probing its pid. The engine consults it after lease expiry, and the store
+verifies that expiry before allowing a steal.
+
+**Fix.** Choose the cross-host policy deliberately. `HostLiveness.isAlive`
+leaves foreign-host recovery to an operator or another liveness source;
+`sameHostPidProbe` lets the expired lease govern reclaiming foreign-host runs.
+`HostLiveness.isAlive` ignores the context argument the sibling reads. See
+[answer whether a run owner is alive](./guides/answer-run-ownership.md).
+
+## The reaper answers `failed` and keeps the record
+
+**Cause.** `failed` means the signal was refused and the record must be tried
+again later. The reaper refuses a target rather than signalling something it
+cannot prove it owns. On POSIX it refuses when:
+
+- the record has no process group (`no-group`)
+- the pid or pgid is not a safe integer, or is `1` or lower
+- the pgid does not equal the pid, so the record does not name a group leader
+- the target is this process's own pid or group, or the owner's
+
+**Fix.** Read the record. A record failing the group-leader check was written
+by something that did not spawn through the contained spawner, and reaping it
+would signal a group this host does not own. See
+[contain child processes](./guides/contain-child-processes.md).
+
+## The reaper answers `unknown` rather than `dead`
+
+**Cause.** `unknown` is not `dead`. `ESRCH` is the only answer that means
+gone; a pid this host may not signal answers `EPERM`, and that is not
+evidence of death.
+
+**Fix.** Treat `unknown` as "ask again". Retiring on `unknown` would drop a
+record describing a live process.
+
+## A pid start-time lookup is `unavailable` rather than `gone`
+
+**Cause.** The three negative answers are distinct because they authorize
+different decisions. `gone` is evidence: the pid does not exist, so the record
+describes nothing and is retired unsignalled. `unavailable` is the absence of
+evidence: `ps` is missing, unanswerable, or printed something unrecognized.
+
+**Fix.** Only `gone` may retire a record. `unavailable` must not, or a host
+without `ps` would retire every record it holds.
+
+## Reaping on Windows is weaker
+
+**Cause.** Windows has no process groups and no `lstart`, so two guards cannot
+be answered: the identity check falls back to boot-time comparison alone, and
+there is no own-group refusal to make. The path runs
+`%SystemRoot%\System32\taskkill.exe /T /F` by pid, by absolute path with an
+inert working directory, so a `taskkill.exe` planted in the host's directory
+never runs.
+
+**Fix.** Nothing, and do not rely on it. Windows is unsupported; this path is
+best-effort so that a win32 record is not silently retired as if reaped.

package/package.json

@@ -1,6 +1,205 @@
 {
   "name": "@smthrs/platform-node",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "type": "module",
+  "version": "1.0.0-rc.3",
+  "license": "MIT",
+  "smthrs": {
+    "group": "engine",
+    "privateEffectAdapters": [
+      "@effect/platform-node",
+      "@effect/platform-node-shared"
+    ]
+  },
+  "description": "Node.js Host bundle for flows: Effect's Node platform services composed into the closed Host surface",
+  "homepage": "https://github.com/smithersai/smithers",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/smithersai/smithers.git",
+    "directory": "packages/smithers/flows/platform-node"
+  },
+  "bugs": {
+    "url": "https://github.com/smithersai/smithers/issues"
+  },
+  "tags": [
+    "typescript",
+    "effect",
+    "node",
+    "platform"
+  ],
+  "keywords": [
+    "typescript",
+    "effect",
+    "node",
+    "platform"
+  ],
+  "engines": {
+    "node": ">=26.4.0"
+  },
+  "sideEffects": [],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./internal/*": null,
+    "./*/index": null,
+    "./AtomicFileSystem": {
+      "import": {
+        "types": "./dist/esm/AtomicFileSystem.d.ts",
+        "default": "./dist/esm/AtomicFileSystem.js"
+      },
+      "require": {
+        "types": "./dist/cjs/AtomicFileSystem.d.ts",
+        "default": "./dist/cjs/AtomicFileSystem.js"
+      }
+    },
+    "./EgressHttpClient": {
+      "import": {
+        "types": "./dist/esm/EgressHttpClient.d.ts",
+        "default": "./dist/esm/EgressHttpClient.js"
+      },
+      "require": {
+        "types": "./dist/cjs/EgressHttpClient.d.ts",
+        "default": "./dist/cjs/EgressHttpClient.js"
+      }
+    },
+    "./HostLiveness": {
+      "import": {
+        "types": "./dist/esm/HostLiveness.d.ts",
+        "default": "./dist/esm/HostLiveness.js"
+      },
+      "require": {
+        "types": "./dist/cjs/HostLiveness.d.ts",
+        "default": "./dist/cjs/HostLiveness.js"
+      }
+    },
+    "./NodeHost": {
+      "import": {
+        "types": "./dist/esm/NodeHost.d.ts",
+        "default": "./dist/esm/NodeHost.js"
+      },
+      "require": {
+        "types": "./dist/cjs/NodeHost.d.ts",
+        "default": "./dist/cjs/NodeHost.js"
+      }
+    },
+    "./ProcessReaper": {
+      "import": {
+        "types": "./dist/esm/ProcessReaper.d.ts",
+        "default": "./dist/esm/ProcessReaper.js"
+      },
+      "require": {
+        "types": "./dist/cjs/ProcessReaper.d.ts",
+        "default": "./dist/cjs/ProcessReaper.js"
+      }
+    },
+    "./index": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./ScopedProcess": {
+      "import": {
+        "types": "./dist/esm/ScopedProcess.d.ts",
+        "default": "./dist/esm/ScopedProcess.js"
+      },
+      "require": {
+        "types": "./dist/cjs/ScopedProcess.d.ts",
+        "default": "./dist/cjs/ScopedProcess.js"
+      }
+    },
+    "./ProcessConfinement": {
+      "import": {
+        "types": "./dist/esm/ProcessConfinement.d.ts",
+        "default": "./dist/esm/ProcessConfinement.js"
+      },
+      "require": {
+        "types": "./dist/cjs/ProcessConfinement.d.ts",
+        "default": "./dist/cjs/ProcessConfinement.js"
+      }
+    },
+    "./ProcessSandbox": {
+      "import": {
+        "types": "./dist/esm/ProcessSandbox.d.ts",
+        "default": "./dist/esm/ProcessSandbox.js"
+      },
+      "require": {
+        "types": "./dist/cjs/ProcessSandbox.d.ts",
+        "default": "./dist/cjs/ProcessSandbox.js"
+      }
+    }
+  },
+  "files": [
+    "bin/**",
+    "src/**/*.ts",
+    "dist/**/*.js",
+    "dist/**/*.js.map",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
+    "dist/**/package.json",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md",
+    "dist/vendor/**",
+    "docs/"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "tag": "next"
+  },
+  "dependencies": {
+    "@smthrs/jj": "1.0.0-rc.3",
+    "@smthrs/kernel": "1.0.0-rc.3",
+    "undici": "8.10.2",
+    "redis": "6.2.1",
+    "@types/ws": "8.18.1",
+    "ws": "8.21.3"
+  },
+  "peerDependencies": {
+    "effect": "4.0.0-rc.115"
+  },
+  "devDependencies": {
+    "@effect/language-service": "0.87.2",
+    "@effect/platform-node": "4.0.0-rc.115",
+    "@effect/platform-node-shared": "4.0.0-rc.115",
+    "@effect/vitest": "4.0.0-rc.115",
+    "@eslint/js": "9.39.5",
+    "@smthrs/journal": "1.0.0-rc.3",
+    "@types/node": "26.4.1",
+    "@vitest/coverage-v8": "5.0.0",
+    "dprint": "0.57.1",
+    "effect": "4.0.0-rc.115",
+    "esbuild": "0.28.2",
+    "eslint": "9.39.5",
+    "eslint-import-resolver-typescript": "4.4.5",
+    "eslint-plugin-import": "2.32.0",
+    "eslint-plugin-jsdoc": "64.3.4",
+    "eslint-plugin-unicorn": "65.0.0",
+    "madge": "8.0.0",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.69.0",
+    "vitest": "5.0.0"
+  },
+  "scripts": {
+    "lint": "eslint src --max-warnings=0 && dprint check",
+    "format": "dprint fmt",
+    "build": "node scripts/build.mjs",
+    "check": "tsc -b tsconfig.json && tsc -p tsconfig.test.json --noEmit",
+    "circular": "node scripts/circular.mjs",
+    "test": "vitest",
+    "coverage": "vitest --coverage"
+  }
 }