@warlock.js/process 0.0.0-stage → 5.33.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog — @warlock.js/process
+
+## 5.33.0 - 2026-10-19
+
+### Added
+
+- Add application-owned process supervision with random environment tokens, PID/start-time registry identity, safe group stops, label filtering, boot recovery and shutdown cleanup.
+- Expose streamed worker handles, exit reasons and peak memory; lazily load optional `node-pty` for terminals.
+- Support macOS without custom native code: parse `ps` start time under `LC_ALL=C TZ=UTC` and verify the inherited random environment token through a live Node launch guardian.
+- Support Windows with PowerShell/CIM creation identity, the guardian's inherited token, PID-only `taskkill /T /F` tree stops, tree working-set polling, timeouts, recovery and optional node-pty/ConPTY terminals. Job Objects remain a future improvement.
+- Make platform command construction, parsing and launch plans pure and observation injectable for Linux-hosted macOS/Windows specs; reject truly unsupported operating systems with `UnsupportedProcessPlatformError`.
+- Attempt Linux cgroup v2 before user code executes, with inherited rlimit/RSS fallback; document softer macOS rlimit/tree RSS and Windows tree RSS enforcement, guardian memory overhead and POSIX-only CPU limits.
+- Integrate `warlock add process` and a read-only devtools process panel.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Hassan Zohdy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,60 @@
-# Temporary Holding Version
+# @warlock.js/process
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+App-owned child process supervision for Linux, macOS and Windows. Ownership uses a random
+environment token, PID, OS start time and a private registry. Stops target verified POSIX process groups or a Windows PID tree; commands are
+never used for identity matching.
+
+```sh
+npx warlock add process
+```
+
+```ts
+import { supervisor } from "@warlock.js/process";
+
+const processes = supervisor({
+  owner: "example-app",
+  registry: "storage/processes/registry.json",
+  defaults: { timeoutMs: 30_000, memoryBytes: 512 * 1024 * 1024 },
+});
+await processes.recover();
+const worker = await processes.spawn({
+  kind: "worker",
+  command: process.execPath,
+  args: ["-e", 'console.log("ready")'],
+  labels: { room: "demo" },
+});
+worker.stdout.pipe(process.stdout);
+worker.stderr.pipe(process.stderr);
+console.log(await worker.exited);
+await processes.stopAll();
+```
+
+Public methods: `spawn`, `spawnPty`, `list`, `stop`, `stopPid`, `recover`,
+`stopAll`. Handles provide streams, `exited` (reason, exit code, signal, peak
+memory) and idempotent `stop`. Unowned PIDs throw `ProcessNotOwnedError`.
+
+| Platform | Identity and enforcement                                                                                                    |
+| -------- | --------------------------------------------------------------------------------------------------------------------------- |
+| Linux    | `/proc` start ticks + boot ID + environment token; cgroup v2 → inherited rlimit/RSS fallback.                               |
+| macOS    | `ps` start time (`LC_ALL=C TZ=UTC`) + environment token; inherited CPU/data rlimits and tree RSS polling.                   |
+| Windows  | PowerShell/CIM creation time + environment token; `taskkill /PID <pid> /T /F` and tree working-set polling (`rss-polling`). |
+
+macOS and Windows memory caps are softer than Linux cgroups: polling can miss
+peaks and overshoot. No custom native code or identity-helper setup is required.
+On these platforms the handle PID belongs to a small Node guardian that launches
+the workload after registry persistence. It proves its inherited environment
+token through a live local socket/named pipe; polling includes guardian overhead
+and descendants. Recovery uses the same PID/start-time/token verification.
+Windows needs Windows PowerShell with CIM available. `cpuSeconds` is POSIX-only;
+`virtualMemoryBytes` is Linux-only. Timeouts work on all three platforms.
+Windows stops force the entire PID tree immediately; Job Objects are a future
+improvement for hard containment and memory caps.
+`spawnPty` lazily imports optional peer `node-pty`, including Windows/ConPTY.
+
+Use a separate registry per app instance and consume output streams. Recovery
+adopts only identities selected by `keep`; by default it stops verified orphans.
+`stopAll` permanently closes the supervisor. The installer wires recovery on
+startup, shutdown cleanup and a read-only devtools Processes panel.
+
+See [the complete documentation](https://warlock.js.org/v/latest/process/) for
+platform limits, delegation, PID reuse limitations, recovery and terminal APIs.