@earendil-works/pi-env 0.0.0-stage → 1.0.4

package/dist/watch.js

@@ -0,0 +1,134 @@
+import { FileError } from "@earendil-works/pi-durable/env";
+import { isConnectionLost } from "./connection.js";
+import { toFileError } from "./errors.js";
+const RECONNECT_FIRST_MS = 1000;
+const RECONNECT_MAX_MS = 30_000;
+/**
+ * A watcher running in the daemon (Durable's `NodeFileWatcher` next to the files). When the connection is lost, it is
+ * opened again once the connection can be started again, and reports `overflow`: changes in between were not seen.
+ */
+export class RemoteWatcher {
+    #connection;
+    #targets;
+    #onChange;
+    #options;
+    #mode = "native";
+    #closed = false;
+    #controller;
+    #request;
+    #wake;
+    constructor(connection, targets, onChange, options) {
+        this.#connection = connection;
+        this.#targets = targets;
+        this.#onChange = onChange;
+        this.#options = options;
+    }
+    /** Watch `targets` (resolved paths); fails like `NodeFileWatcher.open` if coverage cannot be established. */
+    static async open(connection, targets, onChange, options = {}) {
+        const watcher = new RemoteWatcher(connection, targets, onChange, options);
+        await watcher.#start();
+        return watcher;
+    }
+    get mode() {
+        return this.#mode;
+    }
+    async close(_context) {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#wake?.();
+        this.#controller?.abort();
+        await this.#request;
+    }
+    #deliver(change) {
+        if (this.#closed)
+            return;
+        try {
+            this.#onChange(change);
+        }
+        catch {
+            // A throwing callback must not stop watching.
+        }
+    }
+    /** Open the daemon's watcher; resolves once it reports coverage. */
+    #start() {
+        return new Promise((resolve, reject) => {
+            let ready = false;
+            const controller = new AbortController();
+            this.#controller = controller;
+            const request = this.#connection.request("watch", {
+                targets: this.#targets.map((target) => ({
+                    path: target.path,
+                    recursive: target.recursive === true,
+                    exclude: { hidden: target.exclude?.hidden === true, names: [...(target.exclude?.names ?? [])] },
+                })),
+                ...this.#options,
+            }, {
+                signal: controller.signal,
+                onEvent: (event) => {
+                    if (event.kind === "ready") {
+                        ready = true;
+                        this.#mode = event.mode === "polling" ? "polling" : "native";
+                        resolve();
+                    }
+                    else if (event.kind === "change") {
+                        if (event.mode === "polling")
+                            this.#mode = "polling";
+                        if (event.overflow === true)
+                            this.#deliver({ overflow: true });
+                        else
+                            this.#deliver({ paths: event.paths });
+                    }
+                    else if (event.kind === "error") {
+                        const code = event.code === "permission_denied" ? "permission_denied" : "invalid";
+                        this.#deliver({ error: new FileError(code, String(event.message)) });
+                        this.#closed = true;
+                    }
+                },
+            });
+            this.#request = request.then(() => { }, (error) => {
+                if (!ready) {
+                    reject(error);
+                    return;
+                }
+                if (this.#closed)
+                    return;
+                if (isConnectionLost(error)) {
+                    void this.#reconnect();
+                    return;
+                }
+                this.#deliver({ error: toFileError(error) });
+                this.#closed = true;
+            });
+        });
+    }
+    async #reconnect() {
+        for (let delay = RECONNECT_FIRST_MS; !this.#closed; delay = Math.min(delay * 2, RECONNECT_MAX_MS)) {
+            await new Promise((resolve) => {
+                const timer = setTimeout(resolve, delay);
+                timer.unref();
+                this.#wake = () => {
+                    clearTimeout(timer);
+                    resolve();
+                };
+            });
+            this.#wake = undefined;
+            if (this.#closed)
+                return;
+            try {
+                await this.#start();
+                // Changes while disconnected were not seen.
+                this.#deliver({ overflow: true });
+                return;
+            }
+            catch (error) {
+                if (isConnectionLost(error))
+                    continue;
+                this.#deliver({ error: toFileError(error) });
+                this.#closed = true;
+                return;
+            }
+        }
+    }
+}
+//# sourceMappingURL=watch.js.map

package/dist/watch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.js","sourceRoot":"","sources":["../src/watch.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Context } from \"@earendil-works/chord\";\nimport { FileError, type FileWatcher, type WatchChange, type WatchTarget } from \"@earendil-works/pi-durable/env\";\nimport { type Connection, isConnectionLost } from \"./connection.ts\";\nimport { toFileError } from \"./errors.ts\";\n\n/** How the daemon watches, like `NodeExecutionEnv`'s `NodeWatchOptions`. */\nexport interface RemoteWatchOptions {\n\t/** Force a mode; by default Windows and file systems that do not report remote changes poll. */\n\tmode?: \"native\" | \"polling\";\n\t/** Interval between snapshots in `polling` mode; default 2000 ms. */\n\tpollIntervalMs?: number;\n\t/** Most directories one watcher covers; default 10,000. */\n\tmaxDirectories?: number;\n}\n\nconst RECONNECT_FIRST_MS = 1000;\nconst RECONNECT_MAX_MS = 30_000;\n\n/**\n * A watcher running in the daemon (Durable's `NodeFileWatcher` next to the files). When the connection is lost, it is\n * opened again once the connection can be started again, and reports `overflow`: changes in between were not seen.\n */\nexport class RemoteWatcher implements FileWatcher {\n\treadonly #connection: Connection;\n\treadonly #targets: readonly WatchTarget[];\n\treadonly #onChange: (change: WatchChange) => void;\n\treadonly #options: RemoteWatchOptions;\n\t#mode: \"native\" | \"polling\" = \"native\";\n\t#closed = false;\n\t#controller: AbortController | undefined;\n\t#request: Promise<void> | undefined;\n\t#wake: (() => void) | undefined;\n\n\tprivate constructor(\n\t\tconnection: Connection,\n\t\ttargets: readonly WatchTarget[],\n\t\tonChange: (change: WatchChange) => void,\n\t\toptions: RemoteWatchOptions,\n\t) {\n\t\tthis.#connection = connection;\n\t\tthis.#targets = targets;\n\t\tthis.#onChange = onChange;\n\t\tthis.#options = options;\n\t}\n\n\t/** Watch `targets` (resolved paths); fails like `NodeFileWatcher.open` if coverage cannot be established. */\n\tstatic async open(\n\t\tconnection: Connection,\n\t\ttargets: readonly WatchTarget[],\n\t\tonChange: (change: WatchChange) => void,\n\t\toptions: RemoteWatchOptions = {},\n\t): Promise<RemoteWatcher> {\n\t\tconst watcher = new RemoteWatcher(connection, targets, onChange, options);\n\t\tawait watcher.#start();\n\t\treturn watcher;\n\t}\n\n\tget mode(): \"native\" | \"polling\" {\n\t\treturn this.#mode;\n\t}\n\n\tasync close(_context: Context): Promise<void> {\n\t\tif (this.#closed) return;\n\t\tthis.#closed = true;\n\t\tthis.#wake?.();\n\t\tthis.#controller?.abort();\n\t\tawait this.#request;\n\t}\n\n\t#deliver(change: WatchChange): void {\n\t\tif (this.#closed) return;\n\t\ttry {\n\t\t\tthis.#onChange(change);\n\t\t} catch {\n\t\t\t// A throwing callback must not stop watching.\n\t\t}\n\t}\n\n\t/** Open the daemon's watcher; resolves once it reports coverage. */\n\t#start(): Promise<void> {\n\t\treturn new Promise((resolve, reject) => {\n\t\t\tlet ready = false;\n\t\t\tconst controller = new AbortController();\n\t\t\tthis.#controller = controller;\n\t\t\tconst request = this.#connection.request(\n\t\t\t\t\"watch\",\n\t\t\t\t{\n\t\t\t\t\ttargets: this.#targets.map((target) => ({\n\t\t\t\t\t\tpath: target.path,\n\t\t\t\t\t\trecursive: target.recursive === true,\n\t\t\t\t\t\texclude: { hidden: target.exclude?.hidden === true, names: [...(target.exclude?.names ?? [])] },\n\t\t\t\t\t})),\n\t\t\t\t\t...this.#options,\n\t\t\t\t},\n\t\t\t\t{\n\t\t\t\t\tsignal: controller.signal,\n\t\t\t\t\tonEvent: (event) => {\n\t\t\t\t\t\tif (event.kind === \"ready\") {\n\t\t\t\t\t\t\tready = true;\n\t\t\t\t\t\t\tthis.#mode = event.mode === \"polling\" ? \"polling\" : \"native\";\n\t\t\t\t\t\t\tresolve();\n\t\t\t\t\t\t} else if (event.kind === \"change\") {\n\t\t\t\t\t\t\tif (event.mode === \"polling\") this.#mode = \"polling\";\n\t\t\t\t\t\t\tif (event.overflow === true) this.#deliver({ overflow: true });\n\t\t\t\t\t\t\telse this.#deliver({ paths: event.paths as string[] });\n\t\t\t\t\t\t} else if (event.kind === \"error\") {\n\t\t\t\t\t\t\tconst code = event.code === \"permission_denied\" ? \"permission_denied\" : \"invalid\";\n\t\t\t\t\t\t\tthis.#deliver({ error: new FileError(code, String(event.message)) });\n\t\t\t\t\t\t\tthis.#closed = true;\n\t\t\t\t\t\t}\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t);\n\t\t\tthis.#request = request.then(\n\t\t\t\t() => {},\n\t\t\t\t(error: unknown) => {\n\t\t\t\t\tif (!ready) {\n\t\t\t\t\t\treject(error);\n\t\t\t\t\t\treturn;\n\t\t\t\t\t}\n\t\t\t\t\tif (this.#closed) return;\n\t\t\t\t\tif (isConnectionLost(error)) {\n\t\t\t\t\t\tvoid this.#reconnect();\n\t\t\t\t\t\treturn;\n\t\t\t\t\t}\n\t\t\t\t\tthis.#deliver({ error: toFileError(error) });\n\t\t\t\t\tthis.#closed = true;\n\t\t\t\t},\n\t\t\t);\n\t\t});\n\t}\n\n\tasync #reconnect(): Promise<void> {\n\t\tfor (let delay = RECONNECT_FIRST_MS; !this.#closed; delay = Math.min(delay * 2, RECONNECT_MAX_MS)) {\n\t\t\tawait new Promise<void>((resolve) => {\n\t\t\t\tconst timer = setTimeout(resolve, delay);\n\t\t\t\ttimer.unref();\n\t\t\t\tthis.#wake = () => {\n\t\t\t\t\tclearTimeout(timer);\n\t\t\t\t\tresolve();\n\t\t\t\t};\n\t\t\t});\n\t\t\tthis.#wake = undefined;\n\t\t\tif (this.#closed) return;\n\t\t\ttry {\n\t\t\t\tawait this.#start();\n\t\t\t\t// Changes while disconnected were not seen.\n\t\t\t\tthis.#deliver({ overflow: true });\n\t\t\t\treturn;\n\t\t\t} catch (error) {\n\t\t\t\tif (isConnectionLost(error)) continue;\n\t\t\t\tthis.#deliver({ error: toFileError(error) });\n\t\t\t\tthis.#closed = true;\n\t\t\t\treturn;\n\t\t\t}\n\t\t}\n\t}\n}\n"]}

package/docs/protocol.md

@@ -0,0 +1,114 @@
+# pi-env wire protocol
+
+Version 1. The client starts `pi-env serve --token <hex>` (over `ssh`, or directly in tests) and talks to it over the
+process's stdin and stdout. stderr is diagnostic text for logs only.
+
+## Sync
+
+Shell startup files may print to stdout before the daemon runs. The daemon's first output is the line
+`PI-ENV <token>\n`, with the token from its command line. The client discards everything before that line. After it,
+stdout carries only frames.
+
+## Frames
+
+Every frame, in both directions:
+
+```text
+u32 length      bytes after this field
+u8  type
+u32 id          request id; 0 for frames that belong to no request
+u32 jsonLength
+json            UTF-8 JSON object, jsonLength bytes
+bytes           raw payload, the remaining length - 9 - jsonLength bytes
+```
+
+All integers are big-endian. A frame is at most 16 MiB; larger transfers are split by the client. A request whose JSON
+does not parse gets an `EINVAL` error; framing errors end the connection.
+
+| type | name | direction | meaning |
+|---|---|---|---|
+| 1 | request | client → daemon | `json.op` names the operation |
+| 2 | result | daemon → client | success of request `id`; the request is finished |
+| 3 | error | daemon → client | failure of request `id`; the request is finished |
+| 4 | event | daemon → client | progress of a running request (`exec` output, `watch` changes), not finishing it |
+| 5 | cancel | client → daemon | cancel request `id`; see below |
+| 6 | ping | both | liveness; the receiver ignores it |
+
+Errors are `{ code, message, syscall?, path? }`. `code` is a Node-style error code (`ENOENT`, `EISDIR`,
+`ERR_FS_EISDIR`, ...) or one of the execution codes `shell_unavailable`, `spawn_error`, `timeout`, `aborted`, `unknown`.
+Messages are diagnostic; only codes are part of the contract.
+
+Paths are absolute JSON strings; the client resolves relative paths, `~` and `file://` URLs before sending. Strings are
+sent well-formed (lone surrogates become U+FFFD) and encoded as UTF-8, as Node encodes string paths and arguments. File
+contents and output travel as raw payload bytes.
+
+## Cancellation
+
+A cancel names one request. The daemon registers each request before running it, so a cancel sent right after its
+request is never lost. `exec` kills the command's process group and finishes with `aborted`; `{ mode: "kill" }` kills
+without aborting, so the command finishes with the killed process's status, as `cleanup()` does. `scanLines` stops
+between chunks with `aborted`. `watch` stops and finishes with `{}`. Other operations are short and finish normally.
+
+## Scheduling
+
+File operations run on a fixed pool of worker threads; `exec` and `watch` run on their own threads. Chunk writes to one
+handle run in arrival order. Results, errors, pings and `watch` events are sent before queued command output, and
+results with payloads above 64 KiB queue behind output too, so a slow link delays bulk data, not replies. Output of a
+command without an output window waits while more than 4 MiB of output is unsent, which slows the command as a full
+pipe would.
+
+## Liveness
+
+Each side sends `ping` every 5 seconds. The daemon kills every process group it started and exits after 30 seconds
+without receiving any bytes, or when stdin ends. A dropped connection therefore stops remote commands. The client
+fails requests of a lost connection with `{ code: "unknown", lost: true }` and starts a new daemon on the next request;
+handles belong to the daemon that opened them, so requests on them fail instead of reaching the new one.
+
+## Operations
+
+`hello { protocol }` → `{ protocol, version, os, arch, home, tmpdir, cwd, driveCwds, pid }`. The first request.
+`version` is the npm package version the daemon shipped with; `os` and `arch` are Rust's `std::env::consts` values;
+`tmpdir` follows the remote Node's `os.tmpdir()` rules; `cwd` and `driveCwds` (Windows' `=C:` variables) are what
+Node's `path.resolve` falls back to for drive-relative paths.
+
+File operations take `{ path }` (and the listed fields) and return `{}` unless noted:
+
+| op | fields | result |
+|---|---|---|
+| `lstat` | | `info` |
+| `realpath` | | `{ path }` |
+| `write` | `append`, `parents?` (default true), `keep?`, payload | creates missing parents like Node's recursive `mkdir`, opens like `writeFile` (`w`) or `appendFile` (`a`), writes the payload; with `keep`, `{ handle }` for `writeChunk` |
+| `writeChunk` | `handle`, payload | appends to a kept write handle; after a failed chunk, later chunks fail with `EBADF` |
+| `truncate` | `size` | |
+| `fsync` | | |
+| `rename` | `to` | |
+| `mkdir` | `recursive` | |
+| `rm` | `recursive`, `force` | Node `fs.rm` semantics |
+| `mkdtemp` | (`path` is the prefix) | `{ path }` |
+| `open` | `noFollow`, `mode?` | `{ handle, info }` for `openBinaryReader`: nonblocking, regular files only. With `mode: "read"`, Node's `open(path, "r")` of any file, blocking: `{ handle, stat }` or `{ handle, statError }` |
+| `pread` | `handle`, `offset?`, `length` | payload; without `offset`, one read at the current position |
+| `fstat` | `handle` | `info` |
+| `scanLines` | `handle`, `startLine`, `endLine?` | `LineScan` |
+| `opendir` | | `{ handle }` |
+| `readdir` | `handle`, `max` | `{ entries, done }` |
+| `close` | `handle` | |
+
+`info` is `{ name, kind, size, mtimeSec, mtimeNsec, dev, ino }` with `kind` one of `file`, `directory`, `symlink`, `other`.
+`readdir` entries are `{ name, raw?, info }` or `{ name, raw?, error }` when the entry's `lstat` failed. Names are
+decoded as UTF-8 with replacement characters, and lstat'ed under that name, as Node does; `raw` holds the original
+bytes of a name that is not valid UTF-8, for sorting. Handles are numbers, valid until `close` or the end of the
+connection; opening more than 4096 fails with `EMFILE`.
+
+`exec { command | argv, cwd, env, inheritEnv, shellPath?, timeoutMs?, spill?, window? }` runs a shell string or an
+argv array. While it runs, `event` frames `{ kind: "output", stream, skipped? }` carry decoded output text as UTF-8
+payload. With `window { maxBytes, maxLines, minIntervalMs, bytesPerSecond }`, output is coalesced and paced like the
+caller's commits, at most one output frame per command is unsent, and output followed by more than the window is
+replaced by `skipped { bytes, newlines, endsWithNewline }` on the next event, which carries all output after it
+(`ShellOutputInfo.skipped`). The result is `{ exitCode, spillPath? }`; failures are errors with codes `timeout` or
+`aborted` (carrying `spillPath`), `shell_unavailable`, `spawn_error`, or `unknown` (spill failure).
+
+`watch { targets, mode?, pollIntervalMs?, maxDirectories? }` runs Durable's `NodeFileWatcher` in the daemon. `targets`
+are `{ path, recursive, exclude: { hidden, names } }`. Once coverage is established, an event `{ kind: "ready", mode }`
+follows; then `{ kind: "change", paths }` or `{ kind: "change", overflow: true, mode: "polling" }` (native watching
+failed), or `{ kind: "error", code, message }`, after which nothing follows. The request lasts until cancelled.
+Failing to establish coverage is an error of the request.

package/docs/semantics.md

@@ -0,0 +1,65 @@
+# Semantics
+
+The reference is Durable's `NodeExecutionEnv` (`packages/durable/src/env/node.ts`) on the remote machine. Durable's
+env conformance suite and `test/differential.test.ts` check each rule below.
+
+## Split of work
+
+| Concern | Where |
+|---|---|
+| Path resolution: `~` (remote home), `file://`, relative to `cwd`; on Windows drive-relative paths against the remote's working directories | client, the remote system's `path` rules |
+| Abort checkpoints of each method | client, as `NodeExecutionEnv` |
+| Error code mapping (`ENOENT` → `not_found`, ...) | client, as `NodeExecutionEnv`'s `toFileError` |
+| `readFile`'s read sizes, size limit and decoding (`StringDecoder`, byte-order mark kept) over the daemon's `open(path, "r")` | client |
+| `writeFile` in 512 KiB writes with an abort check before each; `appendFile` without checks | client, over one open file |
+| Line reader | client, positional reads and Durable's `StreamDecoder` |
+| Watching: snapshots, native events, polling | daemon, a port of Durable's `NodeFileWatcher` |
+| Timeout validation, result precedence (callback error, timeout, abort, spill failure, exit code) | client |
+| System calls, processes, spill files, line scans | daemon |
+| Command output decoding: per stream, WHATWG UTF-8, only a leading byte-order mark dropped | daemon (`encoding_rs`) |
+
+## Rules the standard libraries do not follow
+
+- Recursive `mkdir`: an existing directory is fine, an existing file fails with `EEXIST`, a file in the way of a parent
+  fails with `ENOTDIR`. Writes create missing parents this way.
+- `rm`: a missing path fails unless `force`; a directory without `recursive` fails with `ERR_FS_EISDIR`
+  (`FileError` code `unknown`).
+- `mkdtemp`: `mkdtemp(3)` of `<tmpdir>/<prefix>XXXXXX`; the prefix is joined with POSIX `path.join`, so `../x` works.
+- `tmpdir`: `TMPDIR`, `TMP`, `TEMP`, then `/tmp` (Termux: `$PREFIX/tmp`), trailing slash removed.
+- `listDir`: names in byte order, like libuv's `scandir`; fails if any entry cannot be lstat'ed. `openDirReader` keeps
+  directory order, skips entries removed meanwhile, and fills each page after skipping. Names that are not UTF-8 are
+  decoded with replacement characters and lstat'ed under that name, so they fail with `ENOENT` as in Node.
+- `openBinaryReader`: nonblocking open; directories fail with `is_directory`, other non-regular files with `invalid`;
+  `noFollow` refuses a final symbolic link (`O_NOFOLLOW`).
+- `readBinaryFile`, `readTextFile` and `openTextLineReader` open any file like `open(path, "r")`: `/dev/null` reads
+  empty, a FIFO blocks until it has a writer, and a directory fails when read (a line reader at `readLine`). A regular
+  file is read up to its size at open; other files to their end.
+- `readBinaryFile` returns a `Buffer`, reader reads a plain `Uint8Array`, as Node does.
+- Windows: error codes are libuv's translations; `rm` of a symbolic link or junction to a directory removes the link;
+  creating a file where a directory exists fails with `EISDIR`; modification times before 1970 are negative.
+
+## Commands
+
+- A string runs through the shell: a configured `shellPath` that does not exist (following links) fails with
+  `shell_unavailable`; otherwise `/bin/bash`, `which bash`, then `sh`, with `-c`. An argv array runs its program
+  directly; on Windows it is searched like libuv does (working directory, then `PATH`, adding `.com` and `.exe`), and
+  batch files are refused.
+- The working directory must exist (`spawn_error`).
+- Environment: with `inheritEnv` (default), the daemon's environment, then `shellEnv`, then `env`; without it, only
+  `env`.
+- Each command gets a new session (process group), default signal dispositions and an empty signal mask. Timeout,
+  abort and `cleanup()` kill the group with `SIGKILL`.
+- After the process exits, output is still collected until both pipes end, or 100 ms pass without output; the timeout
+  still applies meanwhile. The pipes are closed when the command settles, even if a descendant keeps them open.
+- An abort settles as `aborted`; `cleanup()` kills without aborting, so the command settles with exit code 137.
+- A process killed by a signal reports `128 + signal`.
+- Spill: once the output crosses `spill.afterBytes` or `spill.afterLines` (counted over raw chunks in arrival order, as
+  Node counts), the complete raw output goes to `pi-output-<uuid>.log` in a fresh `tmp-` directory.
+
+## Watching
+
+- The daemon runs Durable's `NodeFileWatcher` next to the files: native events (inotify, FSEvents) only trigger a
+  debounced rescan, and changes are the difference between snapshots plus the event paths. Reads are not events.
+- Windows and network or FUSE file systems poll, as `NodeExecutionEnv` does; running out of native watches switches to
+  polling and reports `overflow`.
+- When the connection is lost, the client opens the watcher again once a new daemon starts and reports `overflow`.

package/package.json

@@ -1,6 +1,55 @@
 {
-  "name": "@earendil-works/pi-env",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@earendil-works/pi-env",
+	"version": "1.0.4",
+	"description": "Remote execution environments for Pi Durable: a small daemon deployed over SSH and its ExecutionEnv client",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"source": "./src/index.ts",
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		}
+	},
+	"sideEffects": false,
+	"files": [
+		"dist",
+		"bin",
+		"docs",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"scripts": {
+		"clean": "shx rm -rf dist",
+		"build": "tsc -p tsconfig.build.json",
+		"build:daemon": "cargo build --manifest-path daemon/Cargo.toml --locked",
+		"test": "vitest --run",
+		"prepublishOnly": "npm run clean && npm run build"
+	},
+	"keywords": [
+		"durable-execution",
+		"agents",
+		"ssh",
+		"remote"
+	],
+	"author": "Earendil Works",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/earendil-works/pi.git",
+		"directory": "packages/env"
+	},
+	"engines": {
+		"node": ">=22.19.0"
+	},
+	"dependencies": {
+		"@earendil-works/chord": "^1.0.4",
+		"@earendil-works/pi-durable": "^1.0.4"
+	},
+	"devDependencies": {
+		"shx": "0.4.0",
+		"vitest": "4.1.11"
+	}
+}