@smthrs/platform-bun 1.0.0-rc.6 → 1.0.0-rc.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +6 -9
  2. package/docs/README.md +10 -7
  3. package/docs/guides/configure-the-filesystem-helper.md +14 -10
  4. package/docs/guides/contain-child-processes.md +5 -4
  5. package/docs/installation.md +21 -21
  6. package/docs/quickstart.md +4 -3
  7. package/docs/troubleshooting.md +6 -3
  8. package/package.json +6 -6
package/README.md CHANGED
@@ -22,7 +22,9 @@ package is that object for a process running on Bun.
22
22
 
23
23
  ## Install
24
24
 
25
- Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
25
+ ```bash
26
+ bun add @smthrs/platform-bun@1.0.0-rc.8 effect
27
+ ```
26
28
 
27
29
  `@smthrs/platform-node` and `effect` are required peers, as `package.json`
28
30
  declares them, with `effect` in the range `^4.0.4`. Package managers that
@@ -30,14 +32,9 @@ resolve required peers install both automatically. `@effect/platform-bun`,
30
32
  `@effect/platform-node` and `@effect/platform-node-shared` are bundled
31
33
  privately, built from `effect@4.0.4`.
32
34
 
33
- The filesystem slot spawns the `smithers-jj-export` native helper. From a
34
- source checkout, build it with:
35
-
36
- ```sh
37
- cargo build --locked --release -p smithers-ffi --bin smithers-jj-export
38
- ```
39
-
40
- Elsewhere, set `SMITHERS_WORKSPACE_JJ_EXPORT_BINARY` to its absolute path, or
35
+ The filesystem slot spawns the `smithers-jj-export` native helper, which
36
+ `@smthrs/platform-node` ships for macOS, Linux, and Windows. To use another
37
+ helper, set `SMITHERS_WORKSPACE_JJ_EXPORT_BINARY` to its absolute path, or
41
38
  build the layer with `BunFileSystem.layerWith({ executable })`. `PATH` is never
42
39
  searched. Windows is unsupported.
43
40
 
package/docs/README.md CHANGED
@@ -37,13 +37,16 @@ is Effect's Node spawner re-exported; contained POSIX variants use
37
37
 
38
38
  ## Install
39
39
 
40
- Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
40
+ ```bash
41
+ bun add @smthrs/platform-bun@1.0.0-rc.8 effect
42
+ ```
41
43
 
42
44
  `effect` is a required peer in the range `^4.0.4`. `@effect/platform-bun` is
43
- bundled privately, built from `effect@4.0.4`. The filesystem slot
44
- also needs the `smithers-jj-export` helper, and every complete bundle needs
45
- jj 0.39.0 or later because it probes jj while the layer is built.
46
- [Installation](./installation.md) covers all three and the import forms.
45
+ bundled privately, built from `effect@4.0.4`. The filesystem slot runs the
46
+ `smithers-jj-export` helper that the required peer `@smthrs/platform-node`
47
+ ships, and every complete bundle needs jj 0.39.0 or later because it probes jj
48
+ while the layer is built. [Installation](./installation.md) covers all three
49
+ and the import forms.
47
50
 
48
51
  ## Run a command and a file operation through the host
49
52
 
@@ -107,8 +110,8 @@ that runs them is yours, and this package when that program runs on Bun.
107
110
 
108
111
  ## Where to go next
109
112
 
110
- - [Installation](./installation.md): the peer dependency, the
111
- `smithers-jj-export` helper, the supported runtimes, and the import forms.
113
+ - [Installation](./installation.md): the install line, the peer dependencies,
114
+ the `smithers-jj-export` helper, the supported runtimes, and the import forms.
112
115
  - [Quickstart](./quickstart.md): the program above, run twice, the second time
113
116
  with containment on and a child visible in the ledger.
114
117
  - [The Host surface on Bun](./concepts/host-surface.md): what each of the five
package/docs/guides/configure-the-filesystem-helper.md CHANGED
@@ -9,20 +9,17 @@ the `smithers-jj-export` helper the adapter spawns, which is what makes the
9
9
  operation descriptor-relative and no-follow: a symlink swapped in after
10
10
  authorization cannot redirect it somewhere else.
11
11
 
12
- The adapter uses the first of `executable`, `SMITHERS_WORKSPACE_JJ_EXPORT_BINARY`,
13
- the package's `bin/<platform>-<arch>/smithers-jj-export`, a source checkout's
12
+ The required peer `@smthrs/platform-node` ships the helper for macOS (arm64,
13
+ x64), Linux (arm64, x64), and Windows (x64), so an npm or Bun install needs no
14
+ configuration. The adapter uses the first of `executable`,
15
+ `SMITHERS_WORKSPACE_JJ_EXPORT_BINARY`, that package's
16
+ `bin/<platform>-<arch>/smithers-jj-export`, a source checkout's
14
17
  `target/release` or `target/debug` build, and
15
18
  `/usr/local/bin/smithers-jj-export`. It never searches `PATH`.
16
19
 
17
- ## Build or name the helper
20
+ ## Name another helper
18
21
 
19
- In a source checkout:
20
-
21
- ```bash
22
- cargo build --locked --release -p smithers-ffi --bin smithers-jj-export
23
- ```
24
-
25
- Anywhere else, set the absolute path:
22
+ To run a different helper, set the absolute path:
26
23
 
27
24
  ```bash
28
25
  export SMITHERS_WORKSPACE_JJ_EXPORT_BINARY=/opt/smithers/bin/smithers-jj-export
@@ -40,6 +37,13 @@ The executable is re-validated on every request rather than read once when the
40
37
  layer is built, because the file a path names can be replaced while the host
41
38
  runs.
42
39
 
40
+ A source checkout of the Smithers repository has no packaged helper; build one
41
+ there with:
42
+
43
+ ```bash
44
+ cargo build --locked --release -p smithers-ffi --bin smithers-jj-export
45
+ ```
46
+
43
47
  ## Use it as the whole host's filesystem slot
44
48
 
45
49
  `BunHost.layer` builds its filesystem slot from `BunFileSystem.layer`, which
package/docs/guides/contain-child-processes.md CHANGED
@@ -136,10 +136,11 @@ results are cached per resolved absolute executable path and runner, with a
136
136
  separate cache for each spawner instance.
137
137
 
138
138
  Every aggregate host waits up to 5000 ms for the startup probe, then interrupts
139
- it and awaits process cleanup. The typed `JjError` has `method: "version"`,
140
- `code: "unknown"`, `cause.code: "ETIMEDOUT"`, and the executable path in its
141
- command and message. Cleanup can add the contained spawner's shutdown grace
142
- period to the startup budget. Raw hosts close the probe's pipes and kill its
139
+ it and awaits process cleanup. A probe that misses this budget, or that the
140
+ spawner was too busy to start in time, is retried once. A second timeout fails
141
+ with a typed `JjError` that has `method: "version"`, `code: "unknown"`,
142
+ `cause.code: "ETIMEDOUT"`, and the executable path in its command and message.
143
+ Cleanup can add the contained spawner's shutdown grace period to each attempt. Raw hosts close the probe's pipes and kill its
143
144
  direct child; they do not add a ledger entry.
144
145
 
145
146
  Override the budget per host layer through the shared Node and Bun adapter:
package/docs/installation.md CHANGED
@@ -1,30 +1,31 @@
1
1
  ---
2
2
  title: "Installation"
3
- description: "Install @smthrs/platform-bun, its required peers, the smithers-jj-export helper the filesystem slot needs, the jj executable every complete bundle probes at startup, and the import forms for each entry point."
3
+ description: "Install @smthrs/platform-bun from npm with its required peers, the smithers-jj-export helper @smthrs/platform-node ships for the filesystem slot, the jj executable every complete bundle probes at startup, and the import forms for each entry point."
4
4
  sidebar:
5
5
  order: 1
6
6
  ---
7
7
 
8
8
  ## Install the package and its peers
9
9
 
10
- Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
10
+ The package is on npm under the `next` tag, which carries the 1.0 release
11
+ candidates. Install the current candidate with Bun:
11
12
 
12
- Version 1.0.0-rc.0 is not on npm yet. Until it is published, take the package
13
- from [the repository](https://github.com/smithersai/smithers); the rest of this
14
- page applies either way.
13
+ ```bash
14
+ bun add @smthrs/platform-bun@1.0.0-rc.8 effect
15
+ ```
15
16
 
16
17
  The manifest declares two required peers, neither optional:
17
18
 
18
- | Peer | Version | Why |
19
- | ----------------------- | ------------ | --------------------------------------------------------- |
20
- | `effect` | `^4.0.4` | The runtime every service tag belongs to. |
21
- | `@smthrs/platform-node` | `1.0.0-rc.0` | The atomic filesystem slot and the containment machinery. |
19
+ | Peer | Version | Why |
20
+ | ----------------------- | ------------------------------ | --------------------------------------------------------- |
21
+ | `effect` | `^4.0.4` | The runtime every service tag belongs to. |
22
+ | `@smthrs/platform-node` | exactly this package's version | The atomic filesystem slot and the containment machinery. |
22
23
 
23
- Package managers that resolve required peers install both automatically.
24
- Install one `effect` in that range so the host shares one Effect runtime.
25
- `@effect/platform-bun`, `@effect/platform-node` and
26
- `@effect/platform-node-shared` are bundled privately, built from
27
- `effect@4.0.4`.
24
+ Bun installs required peers, so the line above also installs
25
+ `@smthrs/platform-node` at the matching version. Install one `effect` in the
26
+ peer range so the host shares one Effect runtime. `@effect/platform-bun`,
27
+ `@effect/platform-node` and `@effect/platform-node-shared` are bundled
28
+ privately, built from `effect@4.0.4`, so your project installs none of them.
28
29
 
29
30
  ## Supported runtimes
30
31
 
@@ -34,19 +35,18 @@ Bun 1.4.0 or later, and Node.js 26.4.0 or later. Both are declared in
34
35
  [Runtime parity with Node](./concepts/runtime-parity.md) for what that does and
35
36
  does not buy you.
36
37
 
37
- ## Install the filesystem helper
38
+ ## The filesystem helper
38
39
 
39
40
  The filesystem slot is `@smthrs/platform-node`'s `AtomicFileSystem`, which
40
41
  carries the kernel's atomic host extension. That extension does not run
41
42
  in-process: it executes each guarded path operation through the
42
43
  `smithers-jj-export` helper so the operation is descriptor-relative and
43
- no-follow. From a source checkout, build it with:
44
-
45
- ```bash
46
- cargo build --locked --release -p smithers-ffi --bin smithers-jj-export
47
- ```
44
+ no-follow.
48
45
 
49
- Elsewhere, set `SMITHERS_WORKSPACE_JJ_EXPORT_BINARY` to its absolute path; see
46
+ `@smthrs/platform-node` ships the helper prebuilt for macOS (arm64, x64), Linux
47
+ (arm64, x64), and Windows (x64), so installing the package installs it; there
48
+ is nothing to build. `SMITHERS_WORKSPACE_JJ_EXPORT_BINARY` only overrides the
49
+ packaged helper with another absolute path; see
50
50
  [Configure the filesystem helper](./guides/configure-the-filesystem-helper.md).
51
51
 
52
52
  Windows is unsupported for this slot.
package/docs/quickstart.md CHANGED
@@ -13,15 +13,16 @@ appear in, and disappear from, the process ledger.
13
13
  ## Prerequisites
14
14
 
15
15
  - Bun 1.4.0 or later, or Node.js 26.4.0 or later.
16
- - The `smithers-jj-export` helper. See
17
- [Installation](./installation.md#install-the-filesystem-helper).
16
+ - A project with the package installed:
17
+ `bun add @smthrs/platform-bun@1.0.0-rc.8 effect`. That also installs the
18
+ required peer `@smthrs/platform-node`, which ships the `smithers-jj-export`
19
+ helper the filesystem slot runs. See [Installation](./installation.md).
18
20
  - [Jujutsu](https://jj-vcs.github.io) at jj 0.39.0 or later on `PATH`. Confirm
19
21
  it with `jj --version`. Neither program below touches `Jj`, but every
20
22
  complete bundle probes jj while the layer is built and fails with `JjError`
21
23
  before the program body runs when it is missing. See
22
24
  [Installation](./installation.md) for `SMITHERS_JJ_PATH` and for composing
23
25
  service layers without jj.
24
- - A package with the dependencies installed. Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
25
26
 
26
27
  ## Run a file operation and a command
27
28
 
package/docs/troubleshooting.md CHANGED
@@ -63,9 +63,12 @@ the one it was told to spawn is missing or not executable. The guard fails close
63
63
  operation, because a path-based fallback is exactly the symlink race the
64
64
  extension exists to prevent.
65
65
 
66
- **Fix.** Run `cargo build --locked --release -p smithers-ffi --bin smithers-jj-export`
67
- in a source checkout, or set `SMITHERS_WORKSPACE_JJ_EXPORT_BINARY` to an
68
- absolute helper path. See
66
+ **Fix.** Install `@smthrs/platform-node`, the required peer that ships the
67
+ helper for macOS, Linux, and Windows, at this package's version. If
68
+ `SMITHERS_WORKSPACE_JJ_EXPORT_BINARY` is set, it overrides the packaged helper:
69
+ point it at an executable helper or unset it. A source checkout of the
70
+ repository has no packaged helper; build one there with
71
+ `cargo build --locked --release -p smithers-ffi --bin smithers-jj-export`. See
69
72
  [Configure the filesystem helper](./guides/configure-the-filesystem-helper.md).
70
73
 
71
74
  This failure is unguarded-path-safe: it appears only under
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@smthrs/platform-bun",
3
3
  "type": "module",
4
- "version": "1.0.0-rc.6",
4
+ "version": "1.0.0-rc.8",
5
5
  "license": "MIT",
6
6
  "smthrs": {
7
7
  "group": "engine",
@@ -102,15 +102,15 @@
102
102
  "tag": "next"
103
103
  },
104
104
  "dependencies": {
105
- "@smthrs/jj": "1.0.0-rc.6",
106
- "@smthrs/kernel": "1.0.0-rc.6",
105
+ "@smthrs/jj": "1.0.0-rc.8",
106
+ "@smthrs/kernel": "1.0.0-rc.8",
107
107
  "undici": "8.11.2",
108
108
  "redis": "6.2.1",
109
109
  "@types/ws": "8.18.2",
110
110
  "ws": "8.22.0"
111
111
  },
112
112
  "peerDependencies": {
113
- "@smthrs/platform-node": "1.0.0-rc.6",
113
+ "@smthrs/platform-node": "1.0.0-rc.8",
114
114
  "effect": "^4.0.4"
115
115
  },
116
116
  "devDependencies": {
@@ -120,7 +120,7 @@
120
120
  "@effect/platform-node-shared": "4.0.4",
121
121
  "@effect/vitest": "4.0.4",
122
122
  "@eslint/js": "9.39.5",
123
- "@smthrs/platform-node": "1.0.0-rc.6",
123
+ "@smthrs/platform-node": "1.0.0-rc.8",
124
124
  "@types/node": "26.4.1",
125
125
  "@vitest/coverage-v8": "5.0.0",
126
126
  "dprint": "0.57.1",
@@ -135,7 +135,7 @@
135
135
  "typescript": "5.9.3",
136
136
  "typescript-eslint": "8.69.0",
137
137
  "vitest": "5.0.0",
138
- "@smthrs/artifacts": "1.0.0-rc.6"
138
+ "@smthrs/artifacts": "1.0.0-rc.8"
139
139
  },
140
140
  "scripts": {
141
141
  "lint": "eslint src --max-warnings=0 && dprint check",