@shivaedev/supervisor 0.0.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.2.0 - 2026-11-03
+
+### Added
+
+- Supervise local application processes in per-attempt Effect scopes, with readiness deadlines, captured stdout and stderr, capped exponential restart backoff, and graceful shutdown that escalates to SIGKILL.
+- Decode JSON readiness handshakes, compose dependency start order in application Effects, and observe current readiness and typed failures through native Effect values.
+
+## 0.1.0 - 2026-11-03
+
+### Added
+
+- Publish a package skeleton with no API yet.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ShivaeDev
+
+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,88 @@
 # @shivaedev/supervisor
 
-This name is reserved for an upcoming package in [ShivaeDev Platform](https://github.com/ShivaeDev/platform). Real releases start above 0.0.0.
+Own an application's local processes with the same Effect scopes that own the application. Wait for readiness, restart crashed children with backoff, and stop them when their scope closes.
+
+## Why you want this
+
+A desktop shell or development host should not need its own process supervisor. Express startup order in application code, then let each process live inside a scope:
+
+```ts
+const application = Effect.scoped(
+	Effect.gen(function* () {
+		const database = yield* supervise(startDatabase, { name: "postgres" });
+		const server = yield* supervise(startServer(database.ready), { name: "server" });
+		yield* supervise(startRunner(server.ready), { name: "runner" });
+		yield* Effect.never;
+	}),
+);
+```
+
+Each `start` is a scoped Effect. `supervise` returns after that process is ready, so the next line can use its readiness data.
+
+## Using it
+
+### Process ownership
+
+`supervise(start, options)` evaluates `start` in a fresh scope for each attempt. The returned process supplies a PID, a readiness Effect and an exit Effect. An unexpected exit closes that attempt's scope, waits for backoff, and starts another attempt. Closing the caller's scope interrupts supervision and releases every attempt it owns.
+
+The application expresses dependencies by awaiting one supervisor before starting the next. It also chooses whether a later dependency restart should restart its dependents; the package does not infer a dependency graph.
+
+### Spawn a process and read its readiness signal
+
+The process adapter uses Effect's `ChildProcessSpawner`. Supply its implementation at the application boundary:
+
+```ts
+import { NodeServices } from "@effect/platform-node";
+import { Effect, Schema } from "effect";
+import { spawn } from "@shivaedev/supervisor/adapters/spawn.ts";
+import { jsonReadiness } from "@shivaedev/supervisor/readiness.ts";
+import { supervise } from "@shivaedev/supervisor/supervisor.ts";
+
+const serve = Effect.scoped(
+	Effect.gen(function* () {
+		const server = yield* supervise(
+			spawn({
+				command: "node",
+				args: ["server.js"],
+				readiness: jsonReadiness(Schema.Struct({ port: Schema.Int })),
+				onOutput: ({ source, text }) => Effect.logInfo(text).pipe(Effect.annotateLogs({ source })),
+			}),
+			{
+				name: "server",
+				readinessTimeout: "30 seconds",
+				backoff: { initial: "500 millis", maximum: "5 seconds" },
+			},
+		);
+		yield* Effect.logInfo(`Listening on ${server.ready.port}`);
+		yield* server.await;
+	}),
+).pipe(Effect.provide(NodeServices.layer));
+```
+
+The first stdout line is a JSON readiness message, such as `{"port":3000}`. The decoder preserves Schema failures and reports `ReadinessMissing` if stdout ends without a line. Both stdout and stderr are captured as lines, including readiness and later output. `onOutput` receives each line; its default writes Effect logs with the PID and source.
+
+A custom `readiness` function consumes the stdout line Stream and returns an Effect with application readiness data. Use `withoutReadiness` from the same readiness module for a child that is ready as soon as it is spawned. The adapter keeps draining its output.
+
+The adapter accepts `cwd`, environment overrides in `env`, and a `stopTimeout` that defaults to five seconds. Scope cleanup sends SIGTERM and escalates to SIGKILL through the process spawner when the child does not exit. Choose the spawner implementation at your application's boundary.
+
+### Observe supervision and failures
+
+The returned `ready` value comes from the first successful handshake. `state` is a native `SubscriptionRef`: its `ready` state carries the current PID and readiness value; `backoff` carries the restart count, delay in milliseconds and native `Exit` from the previous attempt. Backoff doubles after each exit up to the configured maximum. The defaults are 500 milliseconds and five seconds.
+
+Startup fails with the original acquisition or readiness failure, `ReadinessTimeout`, or `ProcessExited` when the child exits successfully before readiness. Signal termination remains a native platform failure during startup; after readiness it is an unexpected exit and triggers a restart. A failed acquisition or readiness check on a replacement stops supervision, sets the `failed` state with its native Cause, and fails `await` in the typed error channel. `await` otherwise runs until interrupted. Interruption stays interruption and never triggers a restart.
+
+### API and installation
+
+Import names from their defining modules:
+
+- `supervisor.ts`: `supervise`, `SupervisorOptions`, `ProcessState`.
+- `Process.ts`: the `Process` port for another scoped process adapter.
+- `adapters/spawn.ts`: `spawn`, `SpawnOptions`, `Output`.
+- `readiness.ts`: `jsonReadiness`, `withoutReadiness`, `ReadinessMissing`.
+- `ReadinessTimeout.ts` and `ProcessExited.ts`: typed startup failures.
+
+```sh
+pnpm add @shivaedev/supervisor effect @effect/platform-node
+```
+
+The package needs Node.js 24 or later. The bundled adapter uses native process signals; process-tree cleanup follows the supplied spawner's platform semantics.

package/dist/Process.d.ts

@@ -0,0 +1,7 @@
+import type { Effect } from "effect";
+export interface Process<A, E> {
+    readonly exited: Effect.Effect<number, E>;
+    readonly pid: number;
+    readonly ready: Effect.Effect<A, E>;
+}
+//# sourceMappingURL=Process.d.ts.map

package/dist/Process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Process.d.ts","sourceRoot":"","sources":["../src/Process.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAErC,MAAM,WAAW,OAAO,CAAC,CAAC,EAAE,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAC1C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CACpC"}

package/dist/Process.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Process.js.map

package/dist/Process.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Process.js","sourceRoot":"","sources":["../src/Process.ts"],"names":[],"mappings":""}

package/dist/ProcessExited.d.ts

@@ -0,0 +1,9 @@
+import { Schema } from "effect";
+declare const ProcessExited_base: Schema.Class<ProcessExited, Schema.TaggedStruct<"ProcessExited", {
+    readonly code: Schema.Number;
+    readonly name: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class ProcessExited extends ProcessExited_base {
+}
+export {};
+//# sourceMappingURL=ProcessExited.d.ts.map

package/dist/ProcessExited.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProcessExited.d.ts","sourceRoot":"","sources":["../src/ProcessExited.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;;;;;AAEhC,qBAAa,aAAc,SAAQ,kBAGjC;CAAG"}

package/dist/ProcessExited.js

@@ -0,0 +1,7 @@
+import { Schema } from "effect";
+export class ProcessExited extends Schema.TaggedError()("ProcessExited", {
+    code: Schema.Number,
+    name: Schema.String,
+}) {
+}
+//# sourceMappingURL=ProcessExited.js.map

package/dist/ProcessExited.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProcessExited.js","sourceRoot":"","sources":["../src/ProcessExited.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,MAAM,OAAO,aAAc,SAAQ,MAAM,CAAC,WAAW,EAAiB,CAAC,eAAe,EAAE;IACvF,IAAI,EAAE,MAAM,CAAC,MAAM;IACnB,IAAI,EAAE,MAAM,CAAC,MAAM;CACnB,CAAC;CAAG"}

package/dist/ReadinessTimeout.d.ts

@@ -0,0 +1,8 @@
+import { Schema } from "effect";
+declare const ReadinessTimeout_base: Schema.Class<ReadinessTimeout, Schema.TaggedStruct<"ReadinessTimeout", {
+    readonly name: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class ReadinessTimeout extends ReadinessTimeout_base {
+}
+export {};
+//# sourceMappingURL=ReadinessTimeout.d.ts.map

package/dist/ReadinessTimeout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReadinessTimeout.d.ts","sourceRoot":"","sources":["../src/ReadinessTimeout.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;;;;AAEhC,qBAAa,gBAAiB,SAAQ,qBAEpC;CAAG"}

package/dist/ReadinessTimeout.js

@@ -0,0 +1,6 @@
+import { Schema } from "effect";
+export class ReadinessTimeout extends Schema.TaggedError()("ReadinessTimeout", {
+    name: Schema.String,
+}) {
+}
+//# sourceMappingURL=ReadinessTimeout.js.map

package/dist/ReadinessTimeout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReadinessTimeout.js","sourceRoot":"","sources":["../src/ReadinessTimeout.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,MAAM,OAAO,gBAAiB,SAAQ,MAAM,CAAC,WAAW,EAAoB,CAAC,kBAAkB,EAAE;IAChG,IAAI,EAAE,MAAM,CAAC,MAAM;CACnB,CAAC;CAAG"}

package/dist/adapters/spawn.d.ts

@@ -0,0 +1,18 @@
+import { type Duration, Effect, type PlatformError, Scope, Stream } from "effect";
+import { type ChildProcessSpawner } from "effect/process";
+import type { Process } from "#Process.ts";
+export interface Output {
+    readonly source: "stdout" | "stderr";
+    readonly text: string;
+}
+export interface SpawnOptions<A, E, R> {
+    readonly args?: readonly string[];
+    readonly command: string;
+    readonly cwd?: string;
+    readonly env?: Readonly<Record<string, string>>;
+    readonly onOutput?: (output: Output) => Effect.Effect<void>;
+    readonly readiness: (stdout: Stream.Stream<string, PlatformError.PlatformError>) => Effect.Effect<A, E, R>;
+    readonly stopTimeout?: Duration.Input;
+}
+export declare const spawn: <A, E, R>(options: SpawnOptions<A, E, R>) => Effect.Effect<Process<A, E | PlatformError.PlatformError>, PlatformError.PlatformError, R | ChildProcessSpawner.ChildProcessSpawner | Scope.Scope>;
+//# sourceMappingURL=spawn.d.ts.map

package/dist/adapters/spawn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn.d.ts","sourceRoot":"","sources":["../../src/adapters/spawn.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,QAAQ,EAAE,MAAM,EAAe,KAAK,aAAa,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACzG,OAAO,EAAgB,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,MAAM,WAAW,MAAM;IACtB,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AACD,MAAM,WAAW,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IACpC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAChD,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC5D,QAAQ,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,aAAa,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3G,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,KAAK,CAAC;CACtC;AACD,eAAO,MAAM,KAAK,GAA4C,CAAC,EAAE,CAAC,EAAE,CAAC,uLAiDnE,CAAC"}

package/dist/adapters/spawn.js

@@ -0,0 +1,36 @@
+import { Deferred, Effect, Exit, Fiber, Scope, Stream } from "effect";
+import { ChildProcess } from "effect/process";
+export const spawn = Effect.fn("Supervisor.spawn")(function* (options) {
+    const processScope = yield* Scope.fork(yield* Effect.scope);
+    const child = yield* ChildProcess.make(options.command, options.args ?? [], {
+        cwd: options.cwd,
+        env: options.env,
+        extendEnv: true,
+        forceKillAfter: options.stopTimeout ?? "5 seconds",
+        killSignal: "SIGTERM",
+        stderr: "pipe",
+        stdin: "ignore",
+        stdout: "pipe",
+    }).pipe(Scope.provide(processScope));
+    function record(source) {
+        return (text) => options.onOutput?.({ source, text }) ?? Effect.logInfo(text).pipe(Effect.annotateLogs({ pid: child.pid, source }));
+    }
+    const [logs, readiness] = yield* child.stdout.pipe(Stream.decodeText(), Stream.splitLines, Stream.broadcastN({ capacity: 16, n: 2 }));
+    const output = yield* Effect.forkScoped(Effect.all([Stream.runForEach(logs, record("stdout")), child.stderr.pipe(Stream.decodeText(), Stream.splitLines, Stream.runForEach(record("stderr")))], { concurrency: "unbounded", discard: true }));
+    const ready = yield* Deferred.make();
+    const readinessWorker = yield* Effect.forkScoped(Effect.scoped(Effect.gen(function* () {
+        const pull = yield* Stream.toPull(readiness);
+        return yield* options.readiness(Stream.fromPull(Effect.succeed(pull)));
+    })).pipe(Effect.onExit((exit) => Deferred.done(ready, exit))));
+    yield* Effect.addFinalizer(() => Effect.gen(function* () {
+        yield* Fiber.interrupt(readinessWorker);
+        yield* Scope.close(processScope, Exit.void);
+        yield* Fiber.join(output);
+    }).pipe(Effect.orDie));
+    return {
+        exited: child.exitCode,
+        pid: Number(child.pid),
+        ready: Deferred.await(ready).pipe(Effect.raceFirst(Fiber.join(output).pipe(Effect.andThen(Effect.never)))),
+    };
+});
+//# sourceMappingURL=spawn.js.map

package/dist/adapters/spawn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn.js","sourceRoot":"","sources":["../../src/adapters/spawn.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAiB,MAAM,EAAE,IAAI,EAAE,KAAK,EAAsB,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACzG,OAAO,EAAE,YAAY,EAA4B,MAAM,gBAAgB,CAAC;AAexE,MAAM,CAAC,MAAM,KAAK,GAAG,MAAM,CAAC,EAAE,CAAC,kBAAkB,CAAC,CAAC,QAAQ,CAAC,EAC3D,OAA8B;IAM9B,MAAM,YAAY,GAAG,KAAK,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5D,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,IAAI,EAAE,EAAE;QAC3E,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,SAAS,EAAE,IAAI;QACf,cAAc,EAAE,OAAO,CAAC,WAAW,IAAI,WAAW;QAClD,UAAU,EAAE,SAAS;QACrB,MAAM,EAAE,MAAM;QACd,KAAK,EAAE,QAAQ;QACf,MAAM,EAAE,MAAM;KACd,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC;IACrC,SAAS,MAAM,CAAC,MAAwB;QACvC,OAAO,CAAC,IAAY,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;IAC7I,CAAC;IACD,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,GAAG,KAAK,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACtI,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,UAAU,CACtC,MAAM,CAAC,GAAG,CACT,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAC3I,EAAE,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,CAC3C,CACD,CAAC;IACF,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAQ,CAAC;IAC3C,MAAM,eAAe,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,UAAU,CAC/C,MAAM,CAAC,MAAM,CACZ,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;QACnB,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAC7C,OAAO,KAAK,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACxE,CAAC,CAAC,CACF,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,CAC3D,CAAC;IACF,KAAK,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,EAAE,CAC/B,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;QACnB,KAAK,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,eAAe,CAAC,CAAC;QACxC,KAAK,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,YAAY,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5C,KAAK,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC3B,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CACrB,CAAC;IACF,OAAO;QACN,MAAM,EAAE,KAAK,CAAC,QAAQ;QACtB,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC;QACtB,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;KAC1G,CAAC;AACH,CAAC,CAAC,CAAC"}

package/dist/readiness.d.ts

@@ -0,0 +1,8 @@
+import { Effect, type PlatformError, Schema, Stream } from "effect";
+declare const ReadinessMissing_base: Schema.Class<ReadinessMissing, Schema.TaggedStruct<"ReadinessMissing", {}>, import("effect/Cause").YieldableError>;
+export declare class ReadinessMissing extends ReadinessMissing_base {
+}
+export declare function jsonReadiness<TSchema extends Schema.Constraint>(schema: TSchema): (stdout: Stream.Stream<string, PlatformError.PlatformError>) => Effect.Effect<TSchema["Type"], PlatformError.PlatformError | ReadinessMissing | Schema.SchemaError, TSchema["DecodingServices"]>;
+export declare const withoutReadiness: (stdout: Stream.Stream<string, PlatformError.PlatformError, never>) => Effect.Effect<void, never, import("effect/Scope").Scope>;
+export {};
+//# sourceMappingURL=readiness.d.ts.map

package/dist/readiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.d.ts","sourceRoot":"","sources":["../src/readiness.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAU,KAAK,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;;AAC5E,qBAAa,gBAAiB,SAAQ,qBAA8D;CAAG;AACvG,wBAAgB,aAAa,CAAC,OAAO,SAAS,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,YAC/D,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,aAAa,CAAC,sIAYlE;AACD,eAAO,MAAM,gBAAgB,iIAE3B,CAAC"}

package/dist/readiness.js

@@ -0,0 +1,15 @@
+import { Effect, Option, Schema, Stream } from "effect";
+export class ReadinessMissing extends Schema.TaggedError()("ReadinessMissing", {}) {
+}
+export function jsonReadiness(schema) {
+    return (stdout) => stdout.pipe(Stream.runHead, Effect.flatMap((line) => Effect.gen(function* () {
+        if (Option.isNone(line)) {
+            return yield* Effect.fail(new ReadinessMissing({}));
+        }
+        return yield* Schema.decodeUnknownEffect(Schema.fromJsonString(schema))(line.value);
+    })));
+}
+export const withoutReadiness = Effect.fnUntraced(function* (stdout) {
+    yield* Effect.forkScoped(Stream.runDrain(stdout));
+});
+//# sourceMappingURL=readiness.js.map

package/dist/readiness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.js","sourceRoot":"","sources":["../src/readiness.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAsB,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC5E,MAAM,OAAO,gBAAiB,SAAQ,MAAM,CAAC,WAAW,EAAoB,CAAC,kBAAkB,EAAE,EAAE,CAAC;CAAG;AACvG,MAAM,UAAU,aAAa,CAAoC,MAAe;IAC/E,OAAO,CAAC,MAA0D,EAAE,EAAE,CACrE,MAAM,CAAC,IAAI,CACV,MAAM,CAAC,OAAO,EACd,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CACvB,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;QACnB,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;YACzB,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,gBAAgB,CAAC,EAAE,CAAC,CAAC,CAAC;QACrD,CAAC;QACD,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,mBAAmB,CAAC,MAAM,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACrF,CAAC,CAAC,CACF,CACD,CAAC;AACJ,CAAC;AACD,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,MAA0D;IACtH,KAAK,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;AACnD,CAAC,CAAC,CAAC"}

package/dist/supervisor.d.ts

@@ -0,0 +1,35 @@
+import { Cause, Duration, Effect, Exit, type Scope, SubscriptionRef } from "effect";
+import type { Process } from "#Process.ts";
+import { ProcessExited } from "#ProcessExited.ts";
+import { ReadinessTimeout } from "#ReadinessTimeout.ts";
+export interface SupervisorOptions {
+    readonly backoff?: {
+        readonly initial: Duration.Input;
+        readonly maximum: Duration.Input;
+    };
+    readonly name: string;
+    readonly readinessTimeout?: Duration.Input;
+}
+export type ProcessState<A, E> = {
+    readonly status: "starting";
+    readonly restarts: number;
+} | {
+    readonly status: "ready";
+    readonly restarts: number;
+    readonly pid: number;
+    readonly value: A;
+} | {
+    readonly status: "backoff";
+    readonly restarts: number;
+    readonly delay: number;
+    readonly exit: Exit.Exit<number, E>;
+} | {
+    readonly status: "failed";
+    readonly cause: Cause.Cause<E>;
+};
+export declare const supervise: <A, E, TStartError, R>(start: Effect.Effect<Process<A, E>, TStartError, R | Scope.Scope>, options: SupervisorOptions) => Effect.Effect<{
+    await: Effect.Effect<never, E | TStartError | ProcessExited | ReadinessTimeout, never>;
+    ready: A;
+    state: SubscriptionRef.SubscriptionRef<ProcessState<A, E | TStartError | ProcessExited | ReadinessTimeout>>;
+}, E | TStartError | ProcessExited | ReadinessTimeout, Scope.Scope | Exclude<R, Scope.Scope>>;
+//# sourceMappingURL=supervisor.d.ts.map

package/dist/supervisor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor.d.ts","sourceRoot":"","sources":["../src/supervisor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAY,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAS,KAAK,KAAK,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AACrG,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAA;KAAE,CAAC;IAC1F,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,QAAQ,CAAC,KAAK,CAAC;CAC3C;AAED,MAAM,MAAM,YAAY,CAAC,CAAC,EAAE,CAAC,IAC1B;IAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC1D;IAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAChG;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA;CAAE,GACtH;IAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;CAAE,CAAC;AAEjE,eAAO,MAAM,SAAS,GAAgD,CAAC,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC;;;;6FA6CxF,CAAC"}

package/dist/supervisor.js

@@ -0,0 +1,39 @@
+import { Cause, Deferred, Duration, Effect, Exit, Fiber, SubscriptionRef } from "effect";
+import { ProcessExited } from "#ProcessExited.ts";
+import { ReadinessTimeout } from "#ReadinessTimeout.ts";
+export const supervise = Effect.fn("Supervisor.supervise")(function* (start, options) {
+    const first = yield* Deferred.make();
+    const state = yield* SubscriptionRef.make({ restarts: 0, status: "starting" });
+    const initial = Duration.toMillis(Duration.fromInputUnsafe(options.backoff?.initial ?? "500 millis"));
+    const maximum = Duration.toMillis(Duration.fromInputUnsafe(options.backoff?.maximum ?? "5 seconds"));
+    const attempt = Effect.fnUntraced(function* (restarts) {
+        yield* SubscriptionRef.set(state, { restarts, status: "starting" });
+        const child = yield* start;
+        const value = yield* child.ready.pipe(Effect.raceFirst(child.exited.pipe(Effect.flatMap((code) => Effect.fail(new ProcessExited({ code, name: options.name }))))), Effect.timeoutOrElse({
+            duration: options.readinessTimeout ?? "30 seconds",
+            orElse: () => Effect.fail(new ReadinessTimeout({ name: options.name })),
+        }));
+        yield* SubscriptionRef.set(state, { pid: child.pid, restarts, status: "ready", value });
+        yield* Deferred.succeed(first, value);
+        const exit = yield* Effect.exit(child.exited);
+        if (Exit.isFailure(exit) && Cause.hasInterrupts(exit.cause)) {
+            return yield* Effect.failCause(exit.cause);
+        }
+        return exit;
+    });
+    const watch = Effect.gen(function* () {
+        let restarts = 0;
+        let delay = Math.min(initial, maximum);
+        for (;;) {
+            const exit = yield* Effect.scoped(attempt(restarts));
+            restarts += 1;
+            yield* SubscriptionRef.set(state, { delay, exit, restarts, status: "backoff" });
+            yield* Effect.sleep(delay);
+            delay = Math.min(delay * 2, maximum);
+        }
+    });
+    const worker = yield* Effect.forkScoped(watch.pipe(Effect.onError((cause) => SubscriptionRef.set(state, { cause, status: "failed" })), Effect.onExit((exit) => Deferred.done(first, exit))));
+    const value = yield* Deferred.await(first).pipe(Effect.onError(() => Fiber.interrupt(worker)));
+    return { await: Fiber.join(worker), ready: value, state };
+});
+//# sourceMappingURL=supervisor.js.map

package/dist/supervisor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor.js","sourceRoot":"","sources":["../src/supervisor.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,12 +1,70 @@
 {
   "name": "@shivaedev/supervisor",
-  "version": "0.0.0",
-  "description": "Name reserved for an upcoming ShivaeDev Platform package.",
-  "license": "MIT",
+  "version": "0.2.0",
+  "description": "Scoped local process supervision for Effect applications",
+  "homepage": "https://github.com/ShivaeDev/platform/tree/main/packages/supervisor#readme",
+  "bugs": {
+    "url": "https://github.com/ShivaeDev/platform/issues"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShivaeDev/platform.git",
     "directory": "packages/supervisor"
   },
-  "homepage": "https://github.com/ShivaeDev/platform/tree/main/packages/supervisor#readme"
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "imports": {
+    "#test/*": "./src/test-support/*",
+    "#*.ts": {
+      "source": "./src/*.ts",
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  },
+  "exports": {
+    "./*.ts": {
+      "source": "./src/*.ts",
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.spec.ts",
+    "!src/**/test-support",
+    "CHANGELOG.md",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@effect/platform-node": "4.0.6",
+    "@shivaedev/quality": "0.58.0",
+    "@shivaedev/test-story": "0.37.0",
+    "@types/node": "24.19.2",
+    "effect": "4.0.6",
+    "typescript": "7.0.2",
+    "vitest": "5.0.5"
+  },
+  "peerDependencies": {
+    "effect": "4.0.6"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "quality": {
+    "runtime": "server"
+  },
+  "scripts": {
+    "build": "node --eval \"import('node:fs').then(({ rmSync }) => rmSync('dist', { force: true, recursive: true }))\" && tsc --project tsconfig.build.json",
+    "ready": "pnpm typecheck && pnpm test && pnpm build",
+    "test": "vitest run --configLoader native",
+    "typecheck": "tsc --noEmit"
+  }
 }

package/src/Process.ts

@@ -0,0 +1,7 @@
+import type { Effect } from "effect";
+
+export interface Process<A, E> {
+	readonly exited: Effect.Effect<number, E>;
+	readonly pid: number;
+	readonly ready: Effect.Effect<A, E>;
+}

package/src/ProcessExited.ts

@@ -0,0 +1,6 @@
+import { Schema } from "effect";
+
+export class ProcessExited extends Schema.TaggedError<ProcessExited>()("ProcessExited", {
+	code: Schema.Number,
+	name: Schema.String,
+}) {}

package/src/ReadinessTimeout.ts

@@ -0,0 +1,5 @@
+import { Schema } from "effect";
+
+export class ReadinessTimeout extends Schema.TaggedError<ReadinessTimeout>()("ReadinessTimeout", {
+	name: Schema.String,
+}) {}

package/src/adapters/spawn.ts

@@ -0,0 +1,66 @@
+import { Deferred, type Duration, Effect, Exit, Fiber, type PlatformError, Scope, Stream } from "effect";
+import { ChildProcess, type ChildProcessSpawner } from "effect/process";
+import type { Process } from "#Process.ts";
+export interface Output {
+	readonly source: "stdout" | "stderr";
+	readonly text: string;
+}
+export interface SpawnOptions<A, E, R> {
+	readonly args?: readonly string[];
+	readonly command: string;
+	readonly cwd?: string;
+	readonly env?: Readonly<Record<string, string>>;
+	readonly onOutput?: (output: Output) => Effect.Effect<void>;
+	readonly readiness: (stdout: Stream.Stream<string, PlatformError.PlatformError>) => Effect.Effect<A, E, R>;
+	readonly stopTimeout?: Duration.Input;
+}
+export const spawn = Effect.fn("Supervisor.spawn")(function* <A, E, R>(
+	options: SpawnOptions<A, E, R>,
+): Effect.fn.Return<
+	Process<A, E | PlatformError.PlatformError>,
+	PlatformError.PlatformError,
+	R | Scope.Scope | ChildProcessSpawner.ChildProcessSpawner
+> {
+	const processScope = yield* Scope.fork(yield* Effect.scope);
+	const child = yield* ChildProcess.make(options.command, options.args ?? [], {
+		cwd: options.cwd,
+		env: options.env,
+		extendEnv: true,
+		forceKillAfter: options.stopTimeout ?? "5 seconds",
+		killSignal: "SIGTERM",
+		stderr: "pipe",
+		stdin: "ignore",
+		stdout: "pipe",
+	}).pipe(Scope.provide(processScope));
+	function record(source: Output["source"]) {
+		return (text: string) => options.onOutput?.({ source, text }) ?? Effect.logInfo(text).pipe(Effect.annotateLogs({ pid: child.pid, source }));
+	}
+	const [logs, readiness] = yield* child.stdout.pipe(Stream.decodeText(), Stream.splitLines, Stream.broadcastN({ capacity: 16, n: 2 }));
+	const output = yield* Effect.forkScoped(
+		Effect.all(
+			[Stream.runForEach(logs, record("stdout")), child.stderr.pipe(Stream.decodeText(), Stream.splitLines, Stream.runForEach(record("stderr")))],
+			{ concurrency: "unbounded", discard: true },
+		),
+	);
+	const ready = yield* Deferred.make<A, E>();
+	const readinessWorker = yield* Effect.forkScoped(
+		Effect.scoped(
+			Effect.gen(function* () {
+				const pull = yield* Stream.toPull(readiness);
+				return yield* options.readiness(Stream.fromPull(Effect.succeed(pull)));
+			}),
+		).pipe(Effect.onExit((exit) => Deferred.done(ready, exit))),
+	);
+	yield* Effect.addFinalizer(() =>
+		Effect.gen(function* () {
+			yield* Fiber.interrupt(readinessWorker);
+			yield* Scope.close(processScope, Exit.void);
+			yield* Fiber.join(output);
+		}).pipe(Effect.orDie),
+	);
+	return {
+		exited: child.exitCode,
+		pid: Number(child.pid),
+		ready: Deferred.await(ready).pipe(Effect.raceFirst(Fiber.join(output).pipe(Effect.andThen(Effect.never)))),
+	};
+});

package/src/readiness.ts

@@ -0,0 +1,19 @@
+import { Effect, Option, type PlatformError, Schema, Stream } from "effect";
+export class ReadinessMissing extends Schema.TaggedError<ReadinessMissing>()("ReadinessMissing", {}) {}
+export function jsonReadiness<TSchema extends Schema.Constraint>(schema: TSchema) {
+	return (stdout: Stream.Stream<string, PlatformError.PlatformError>) =>
+		stdout.pipe(
+			Stream.runHead,
+			Effect.flatMap((line) =>
+				Effect.gen(function* () {
+					if (Option.isNone(line)) {
+						return yield* Effect.fail(new ReadinessMissing({}));
+					}
+					return yield* Schema.decodeUnknownEffect(Schema.fromJsonString(schema))(line.value);
+				}),
+			),
+		);
+}
+export const withoutReadiness = Effect.fnUntraced(function* (stdout: Stream.Stream<string, PlatformError.PlatformError>) {
+	yield* Effect.forkScoped(Stream.runDrain(stdout));
+});

package/src/supervisor.ts

@@ -0,0 +1,63 @@
+import { Cause, Deferred, Duration, Effect, Exit, Fiber, type Scope, SubscriptionRef } from "effect";
+import type { Process } from "#Process.ts";
+import { ProcessExited } from "#ProcessExited.ts";
+import { ReadinessTimeout } from "#ReadinessTimeout.ts";
+
+export interface SupervisorOptions {
+	readonly backoff?: { readonly initial: Duration.Input; readonly maximum: Duration.Input };
+	readonly name: string;
+	readonly readinessTimeout?: Duration.Input;
+}
+
+export type ProcessState<A, E> =
+	| { readonly status: "starting"; readonly restarts: number }
+	| { readonly status: "ready"; readonly restarts: number; readonly pid: number; readonly value: A }
+	| { readonly status: "backoff"; readonly restarts: number; readonly delay: number; readonly exit: Exit.Exit<number, E> }
+	| { readonly status: "failed"; readonly cause: Cause.Cause<E> };
+
+export const supervise = Effect.fn("Supervisor.supervise")(function* <A, E, TStartError, R>(
+	start: Effect.Effect<Process<A, E>, TStartError, R | Scope.Scope>,
+	options: SupervisorOptions,
+) {
+	const first = yield* Deferred.make<A, E | TStartError | ReadinessTimeout | ProcessExited>();
+	const state = yield* SubscriptionRef.make<ProcessState<A, E | TStartError | ReadinessTimeout | ProcessExited>>({ restarts: 0, status: "starting" });
+	const initial = Duration.toMillis(Duration.fromInputUnsafe(options.backoff?.initial ?? "500 millis"));
+	const maximum = Duration.toMillis(Duration.fromInputUnsafe(options.backoff?.maximum ?? "5 seconds"));
+	const attempt = Effect.fnUntraced(function* (restarts: number) {
+		yield* SubscriptionRef.set(state, { restarts, status: "starting" });
+		const child = yield* start;
+		const value = yield* child.ready.pipe(
+			Effect.raceFirst(child.exited.pipe(Effect.flatMap((code) => Effect.fail(new ProcessExited({ code, name: options.name }))))),
+			Effect.timeoutOrElse({
+				duration: options.readinessTimeout ?? "30 seconds",
+				orElse: () => Effect.fail(new ReadinessTimeout({ name: options.name })),
+			}),
+		);
+		yield* SubscriptionRef.set(state, { pid: child.pid, restarts, status: "ready", value });
+		yield* Deferred.succeed(first, value);
+		const exit = yield* Effect.exit(child.exited);
+		if (Exit.isFailure(exit) && Cause.hasInterrupts(exit.cause)) {
+			return yield* Effect.failCause(exit.cause);
+		}
+		return exit;
+	});
+	const watch = Effect.gen(function* () {
+		let restarts = 0;
+		let delay = Math.min(initial, maximum);
+		for (;;) {
+			const exit = yield* Effect.scoped(attempt(restarts));
+			restarts += 1;
+			yield* SubscriptionRef.set(state, { delay, exit, restarts, status: "backoff" });
+			yield* Effect.sleep(delay);
+			delay = Math.min(delay * 2, maximum);
+		}
+	});
+	const worker = yield* Effect.forkScoped(
+		watch.pipe(
+			Effect.onError((cause) => SubscriptionRef.set(state, { cause, status: "failed" })),
+			Effect.onExit((exit) => Deferred.done(first, exit)),
+		),
+	);
+	const value = yield* Deferred.await(first).pipe(Effect.onError(() => Fiber.interrupt(worker)));
+	return { await: Fiber.join(worker), ready: value, state };
+});