@evolu/nodejs 3.0.0-next.3 → 3.0.1

package/dist/src/local-first/Relay.d.ts

@@ -5,10 +5,10 @@ export interface NodeJsRelayConfig extends RelayConfig {
     readonly port?: number;
 }
 export type RelayDeps = CreateSqliteDriverDep & RandomDep & TimingSafeEqualDep;
-/** Dependencies for {@link startRelay} using better-sqlite3. */
+/** Dependencies for {@link createRelay} using better-sqlite3. */
 export declare const createRelayDeps: () => RelayDeps;
 /**
- * Starts an Evolu relay server using Node.js.
+ * Creates an Evolu Relay server resource using Node.js.
  *
  * Use {@link createRelayDeps} to create dependencies for better-sqlite3, or
  * provide a custom SQLite driver implementation.
@@ -29,27 +29,20 @@ export declare const createRelayDeps: () => RelayDeps;
  *
  * const deps = { ...createRelayDeps(), console };
  *
- * await using run = createRun(deps);
- * await using disposer = new AsyncDisposableStack();
+ * await runMain(deps)(
+ *   createRelay({
+ *     port: 4000,
  *
- * disposer.use(
- *   await run.orThrow(
- *     startRelay({
- *       port: 4000,
+ *     // Note: Relay requires URL in format ws://host:port?ownerId=<ownerId>
+ *     // isOwnerAllowed: (_ownerId, { signal: _signal }) => true,
  *
- *       // Note: Relay requires URL in format ws://host:port?ownerId=<ownerId>
- *       // isOwnerAllowed: (_ownerId, { signal: _signal }) => true,
- *
- *       isOwnerWithinQuota: (_ownerId, requiredBytes) => {
- *         const maxBytes = 1024 * 1024; // 1MB
- *         return requiredBytes <= maxBytes;
- *       },
- *     }),
- *   ),
+ *     isOwnerWithinQuota: (_ownerId, requiredBytes) => {
+ *       const maxBytes = 1024 * 1024; // 1MB
+ *       return requiredBytes <= maxBytes;
+ *     },
+ *   }),
  * );
- *
- * await run.deps.shutdown;
  * ```
  */
-export declare const startRelay: ({ port, name, isOwnerAllowed, isOwnerWithinQuota, }: NodeJsRelayConfig) => Task<Relay, never, RelayDeps>;
+export declare const createRelay: ({ port, name, isOwnerAllowed, isOwnerWithinQuota, }: NodeJsRelayConfig) => Task<Relay, never, RelayDeps>;
 //# sourceMappingURL=Relay.d.ts.map

package/dist/src/local-first/Relay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Relay.d.ts","sourceRoot":"","sources":["../../../src/local-first/Relay.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,qBAAqB,EAI1B,KAAK,SAAS,EACd,KAAK,IAAI,EACT,KAAK,kBAAkB,EAExB,MAAM,eAAe,CAAC;AACvB,OAAO,EAQL,KAAK,KAAK,EACV,KAAK,WAAW,EACjB,MAAM,2BAA2B,CAAC;AAQnC,MAAM,WAAW,iBAAkB,SAAQ,WAAW;IACpD,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,SAAS,GAAG,qBAAqB,GAAG,SAAS,GAAG,kBAAkB,CAAC;AAE/E,gEAAgE;AAChE,eAAO,MAAM,eAAe,QAAO,SAIjC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,eAAO,MAAM,UAAU,GACpB,qDAKE,iBAAiB,KAAG,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,CA8MlD,CAAC"}
+{"version":3,"file":"Relay.d.ts","sourceRoot":"","sources":["../../../src/local-first/Relay.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,qBAAqB,EAK1B,KAAK,SAAS,EACd,KAAK,IAAI,EACT,KAAK,kBAAkB,EAGxB,MAAM,eAAe,CAAC;AACvB,OAAO,EAQL,KAAK,KAAK,EACV,KAAK,WAAW,EACjB,MAAM,2BAA2B,CAAC;AAQnC,MAAM,WAAW,iBAAkB,SAAQ,WAAW;IACpD,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,SAAS,GAAG,qBAAqB,GAAG,SAAS,GAAG,kBAAkB,CAAC;AAE/E,iEAAiE;AACjE,eAAO,MAAM,eAAe,QAAO,SAIjC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,WAAW,wDAMnB,iBAAiB,KAAG,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,CAgNlD,CAAC"}

package/dist/src/local-first/Relay.js

@@ -50,7 +50,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     var e = new Error(message);
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
-import { AbortError, assert, callback, createRandom, createRelation, createSqlite, Name, ok, OwnerId, Uint8Array, } from "@evolu/common";
+import { assert, createRandom, createRelation, createSqlite, daemon, Name, ok, OwnerId, tryAsync, Uint8Array, } from "@evolu/common";
 import { applyProtocolMessageAsRelay, createBaseSqliteStorageTables, createRelaySqliteStorage, createRelayStorageTables, defaultProtocolMessageMaxSize, parseOwnerIdFromOwnerWebSocketTransportUrl, } from "@evolu/common/local-first";
 import { once } from "events";
 import { existsSync } from "fs";
@@ -58,14 +58,14 @@ import { createServer } from "http";
 import { WebSocket, WebSocketServer } from "ws";
 import { createTimingSafeEqual } from "../Crypto.js";
 import { createBetterSqliteDriver } from "../Sqlite.js";
-/** Dependencies for {@link startRelay} using better-sqlite3. */
+/** Dependencies for {@link createRelay} using better-sqlite3. */
 export const createRelayDeps = () => ({
     createSqliteDriver: createBetterSqliteDriver,
     random: createRandom(),
     timingSafeEqual: createTimingSafeEqual(),
 });
 /**
- * Starts an Evolu relay server using Node.js.
+ * Creates an Evolu Relay server resource using Node.js.
  *
  * Use {@link createRelayDeps} to create dependencies for better-sqlite3, or
  * provide a custom SQLite driver implementation.
@@ -86,38 +86,28 @@ export const createRelayDeps = () => ({
  *
  * const deps = { ...createRelayDeps(), console };
  *
- * await using run = createRun(deps);
- * await using disposer = new AsyncDisposableStack();
+ * await runMain(deps)(
+ *   createRelay({
+ *     port: 4000,
  *
- * disposer.use(
- *   await run.orThrow(
- *     startRelay({
- *       port: 4000,
+ *     // Note: Relay requires URL in format ws://host:port?ownerId=<ownerId>
+ *     // isOwnerAllowed: (_ownerId, { signal: _signal }) => true,
  *
- *       // Note: Relay requires URL in format ws://host:port?ownerId=<ownerId>
- *       // isOwnerAllowed: (_ownerId, { signal: _signal }) => true,
- *
- *       isOwnerWithinQuota: (_ownerId, requiredBytes) => {
- *         const maxBytes = 1024 * 1024; // 1MB
- *         return requiredBytes <= maxBytes;
- *       },
- *     }),
- *   ),
+ *     isOwnerWithinQuota: (_ownerId, requiredBytes) => {
+ *       const maxBytes = 1024 * 1024; // 1MB
+ *       return requiredBytes <= maxBytes;
+ *     },
+ *   }),
  * );
- *
- * await run.deps.shutdown;
  * ```
  */
-export const startRelay = ({ port = 443, name = Name.orThrow("evolu-relay"), isOwnerAllowed, isOwnerWithinQuota, }) => async (run) => {
+export const createRelay = ({ port = 443, name = Name.orThrow("evolu-relay"), isOwnerAllowed, isOwnerWithinQuota, }) => async (run) => {
     const env_1 = { stack: [], error: void 0, hasError: false };
     try {
         const disposer = __addDisposableResource(env_1, new AsyncDisposableStack(), true);
         const console = run.deps.console.child("relay");
-        disposer.defer(() => {
-            console.info("Shutdown complete");
-        });
         const dbFileExists = existsSync(`${name}.db`);
-        const sqlite = disposer.use(await run.orThrow(createSqlite(name)));
+        const sqlite = disposer.use(await run.ok(createSqlite(name)));
         const deps = { ...run.deps, sqlite };
         if (!dbFileExists) {
             createBaseSqliteStorageTables(deps);
@@ -137,12 +127,8 @@ export const startRelay = ({ port = 443, name = Name.orThrow("evolu-relay"), isO
             });
         }));
         const ownerSocketRelation = createRelation();
-        const relayRun = disposer.use(run.create({
-            ...run.deps,
-            storage: createRelaySqliteStorage(deps)({
-                isOwnerWithinQuota,
-            }),
-        }));
+        const storage = createRelaySqliteStorage(deps)({ isOwnerWithinQuota });
+        const relayRun = disposer.use(run.create({ storage }));
         server.on("upgrade", (request, socket, head) => {
             socket.on("error", console.debug);
             const completeUpgrade = () => {
@@ -170,24 +156,30 @@ export const startRelay = ({ port = 443, name = Name.orThrow("evolu-relay"), isO
                 respondAndDestroy(400);
                 return;
             }
-            const authorizationFiber = relayRun(callback(({ ok, err, signal }) => {
-                void Promise.try(() => isOwnerAllowed(ownerId, { signal })).then(ok, err);
-            }));
+            const authorizationFiber = relayRun.abortable(
+            // Use daemon because authorization can call an external service that
+            // ignores abort. The daemon runs in the root Run, so aborting the
+            // current Run does not make its Fiber wait for the service Promise to
+            // settle.
+            daemon(async (run) => await tryAsync(() => isOwnerAllowed(ownerId, { signal: run.signal }), (error) => ({ type: "OwnerAuthorizationError", error }))));
             const abortAuthorization = () => {
-                authorizationFiber.abort("WebSocket upgrade request socket closed");
+                authorizationFiber.abort({
+                    type: "WebSocketUpgradeSocketClosed",
+                });
             };
             socket.once("close", abortAuthorization);
             socket.once("error", abortAuthorization);
-            void authorizationFiber.then((result) => {
+            void (async () => {
+                const result = await authorizationFiber;
                 socket.removeListener("close", abortAuthorization);
                 socket.removeListener("error", abortAuthorization);
                 if (!result.ok) {
-                    if (!AbortError.is(result.error)) {
-                        console.error("isOwnerAllowed failed", ownerId, result.error);
-                        respondAndDestroy(503);
+                    if (result.error.type === "AbortError") {
+                        socket.destroy();
                         return;
                     }
-                    socket.destroy();
+                    console.error(result.error.error);
+                    respondAndDestroy(503);
                     return;
                 }
                 if (!result.value) {
@@ -196,7 +188,7 @@ export const startRelay = ({ port = 443, name = Name.orThrow("evolu-relay"), isO
                     return;
                 }
                 completeUpgrade();
-            });
+            })();
         });
         wss.on("connection", (ws) => {
             console.debug("on connection", wss.clients.size);
@@ -222,8 +214,10 @@ export const startRelay = ({ port = 443, name = Name.orThrow("evolu-relay"), isO
                 if (!Uint8Array.is(message))
                     return;
                 void (async () => {
-                    const response = await relayRun(applyProtocolMessageAsRelay(message, options));
+                    const response = await relayRun.abortable(applyProtocolMessageAsRelay(message, options));
                     if (!response.ok) {
+                        if (response.error.type === "AbortError")
+                            return;
                         console.error(response);
                         return;
                     }
@@ -236,7 +230,6 @@ export const startRelay = ({ port = 443, name = Name.orThrow("evolu-relay"), isO
             });
         });
         disposer.defer(() => {
-            console.info("Shutting down...");
             for (const client of wss.clients) {
                 if (client.readyState === WebSocket.OPEN) {
                     client.close(1000, "Evolu Relay shutting down");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evolu/nodejs",
-  "version": "3.0.0-next.3",
+  "version": "3.0.1",
   "description": "Evolu for Node.js",
   "author": "Daniel Steigerwald <daniel@steigerwald.cz>",
   "license": "MIT",
@@ -19,6 +19,18 @@
       "types": "./dist/src/index.d.ts",
       "import": "./dist/src/index.js",
       "default": "./dist/src/index.js"
+    },
+    "./TestBundle": {
+      "types": "./dist/src/TestBundle.d.ts",
+      "import": "./dist/src/TestBundle.js",
+      "default": "./dist/src/TestBundle.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "TestBundle": [
+        "./dist/src/TestBundle.d.ts"
+      ]
     }
   },
   "files": [
@@ -27,19 +39,31 @@
     "README.md"
   ],
   "dependencies": {
-    "better-sqlite3": "^12.6.2",
+    "better-sqlite3": "^12.11.1",
     "ws": "^8.19.0"
   },
   "devDependencies": {
-    "@types/better-sqlite3": "^7.6.13",
+    "@types/better-sqlite3": "^9.6.0",
     "@types/node": "^24.10.9",
     "@types/ws": "^8.18.1",
-    "typescript": "^6",
-    "@evolu/common": "8.0.0-next.5",
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "vite": "^8.2.0",
+    "webpack": "^5.109.2",
+    "@evolu/common": "8.1.0",
     "@evolu/typescript-config": "0.0.2"
   },
   "peerDependencies": {
-    "@evolu/common": "^8.0.0-next.0"
+    "@evolu/common": "^8.0.0",
+    "vite": ">=8.0.0",
+    "webpack": ">=5.108.4"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    },
+    "webpack": {
+      "optional": true
+    }
   },
   "engines": {
     "node": ">=24.0.0"

package/src/Cli.ts

@@ -0,0 +1,78 @@
+/**
+ * Abort-aware CLI process utilities.
+ *
+ * @module
+ */
+
+import { callback, err, ok, type Task, type Typed } from "@evolu/common";
+import { spawn as nodeSpawn } from "node:child_process";
+
+/** Runs a command with inherited stdio. */
+export type Spawn = (
+  file: string,
+  args: ReadonlyArray<string>,
+  options?: {
+    readonly cwd?: string | URL;
+  },
+) => Task<void, SpawnError>;
+
+/** Failure to start a command or an unsuccessful command exit. */
+export interface SpawnError extends Typed<"SpawnError"> {
+  readonly command: string;
+  readonly exitCode: number | null;
+  readonly signal: NodeJS.Signals | null;
+  readonly message: string;
+}
+
+/** Dependency wrapper for {@link spawn}. */
+export interface SpawnDep {
+  readonly spawn: Spawn;
+}
+
+/**
+ * Runs a command with inherited stdio and aborts it with the current Run.
+ *
+ * A zero exit code succeeds. A start failure, non-zero exit code, or signal
+ * exit returns {@link SpawnError}.
+ */
+export const spawn: Spawn = (file, args, { cwd } = {}) => {
+  const command = [file, ...args].join(" ");
+
+  return callback(({ run, resolve }) => {
+    const child = nodeSpawn(file, args, {
+      cwd,
+      signal: run.signal,
+      stdio: "inherit",
+    });
+
+    child.once("error", (error) => {
+      if (run.signal.aborted) return;
+      resolve(
+        err({
+          type: "SpawnError",
+          command,
+          exitCode: null,
+          signal: null,
+          message: `Failed to start ${command}: ${error.message}`,
+        }),
+      );
+    });
+    child.once("close", (exitCode, signal) => {
+      if (run.signal.aborted) return;
+      resolve(
+        exitCode === 0
+          ? ok()
+          : err({
+              type: "SpawnError",
+              command,
+              exitCode,
+              signal,
+              message:
+                signal == null
+                  ? `${command} exited with code ${exitCode}.`
+                  : `${command} exited from ${signal}.`,
+            }),
+      );
+    });
+  });
+};

package/src/Platform.ts

@@ -0,0 +1,20 @@
+/**
+ * Node.js platform utilities.
+ *
+ * @module
+ */
+
+import { PositiveInt } from "@evolu/common";
+import { availableParallelism as nodeAvailableParallelism } from "node:os";
+
+/** Returns the recommended amount of parallelism available to this process. */
+export type AvailableParallelism = () => PositiveInt;
+
+/** Dependency wrapper for {@link availableParallelism}. */
+export interface AvailableParallelismDep {
+  readonly availableParallelism: AvailableParallelism;
+}
+
+/** Returns the recommended amount of parallelism available to this process. */
+export const availableParallelism: AvailableParallelism = () =>
+  PositiveInt.orThrow(nodeAvailableParallelism());

package/src/Sqlite.ts

@@ -1,6 +1,6 @@
 import {
+  constVoid,
   createPreparedStatementsCache,
-  lazyVoid,
   ok,
   type CreateSqliteDriver,
   type SqliteRow,
@@ -30,7 +30,7 @@ export const createBetterSqliteDriver: CreateSqliteDriver =
         (sql) => db.prepare(sql),
         // Not needed.
         // https://github.com/WiseLibs/better-sqlite3/blob/master/docs/api.md#class-statement
-        lazyVoid,
+        constVoid,
       ),
     );
 

package/src/Task.ts

@@ -5,89 +5,198 @@
  */
 
 import {
-  createRun as createCommonRun,
-  createUnknownError,
-  type CreateRun,
+  createConsole,
+  createRun,
+  isDisposable,
+  ok,
+  waitForAbort,
+  type ConsoleDep,
+  type ReportDefectDep,
+  type Resource,
   type Run,
-  type RunDefaultDeps,
+  type RunCustomDeps,
+  type Task,
+  type Typed,
 } from "@evolu/common";
 
 /**
- * A promise that resolves when a termination signal is received.
+ * An abort requested by a Node.js termination signal.
  *
- * Resolves on `SIGINT` (Ctrl-C), `SIGTERM` (OS/k8s/Docker termination),
- * `SIGHUP` (console close/terminal disconnect), or `SIGBREAK` (Windows
- * Ctrl-Break).
- *
- * @group Node.js Run
+ * @group Node.js Task
  */
-export type Shutdown = Promise<void>;
+export interface NodeSignalAbortReason extends Typed<"NodeSignalAbortReason"> {
+  readonly signal: NodeSignal;
+}
+
+/** A Node.js termination signal handled by {@link runMain}. */
+export type NodeSignal = "SIGINT" | "SIGTERM" | "SIGBREAK";
+
+/** Process lifecycle behavior for {@link runMain}. */
+export type RunMainMode = "service" | "command";
 
-export interface ShutdownDep {
-  readonly shutdown: Shutdown;
+/** Options for {@link runMain}. */
+export interface RunMainOptions {
+  /**
+   * How termination signals affect the process exit status.
+   *
+   * Services treat a gracefully handled signal as a successful shutdown.
+   * Commands use the conventional `128 + signal number` exit status unless a
+   * reported defect has already set a failure status.
+   *
+   * @default "service"
+   */
+  readonly mode?: RunMainMode;
 }
 
 /**
- * Creates {@link Run} for Node.js with global error handling and graceful
- * shutdown.
+ * Runs the main Task as the Node.js program lifecycle.
+ *
+ * Creates one root {@link Run} and aborts it on:
+ *
+ * - `SIGINT`: Ctrl-C on all platforms.
+ * - `SIGTERM`: OS, service, Docker, or Kubernetes termination on Unix.
+ * - `SIGBREAK`: Ctrl-Break on Windows.
+ *
+ * The first signal logs shutdown progress, aborts the root Run, and waits for
+ * the main Task and structured cleanup to finish. A subsequent signal exits
+ * immediately with its conventional signal status, abandoning cleanup. A signal
+ * received during final cleanup still applies signal shutdown behavior.
  *
- * Registers `uncaughtException` and `unhandledRejection` handlers that log
- * errors and initiate graceful shutdown. Adds a `shutdown` promise to deps that
- * resolves on termination signals (`SIGINT`, `SIGTERM`, `SIGHUP`). Handlers are
- * removed when the Run is disposed.
+ * A main Task returning {@link Resource} keeps the program running until a
+ * termination signal and is disposed during shutdown. A main Task returning
+ * `void` completes the program immediately. A Resource result transfers
+ * ownership of a live resource that must remain valid after its creating Task
+ * settles.
  *
- * ### Example
+ * Service mode treats graceful signal shutdown as successful. Command mode
+ * preserves conventional signal exit statuses. Every defect reported through
+ * `reportDefect`, including an observer defect that does not abort the Run,
+ * sets `process.exitCode` to 1. The default reporter logs to the configured
+ * Evolu console.
+ *
+ * Escaped uncaught exceptions and unhandled rejections remain under Node.js
+ * native reporting and termination.
+ *
+ * ### Service Example
  *
  * ```ts
- * const deps = { ...createRelayDeps(), console };
+ * const deps = { ...createRelayDeps(), console: createConsole() };
  *
- * await using run = createRun(deps);
- * await using disposer = new AsyncDisposableStack();
+ * await runMain(deps)(createRelay({ port: 4000 }));
+ * ```
  *
- * disposer.use(await run.orThrow(startRelay({ port: 4000 })));
+ * A Task returning `void` can keep a service alive explicitly when no Resource
+ * owns its lifetime:
  *
- * await run.deps.shutdown;
+ * ```ts
+ * await runMain(deps)(async (run) => {
+ *   void run(processMessages);
+ *   return await run(waitForAbort);
+ * });
  * ```
  *
- * @group Node.js Run
+ * ### Command Example
+ *
+ * ```ts
+ * await runMain(command, { mode: "command" });
+ * ```
+ *
+ * @group Node.js Task
  */
-export const createRun: CreateRun<RunDefaultDeps & ShutdownDep> = <D>(
-  deps?: D,
-): Run<RunDefaultDeps & ShutdownDep & D> => {
-  const { promise: shutdown, resolve: resolveShutdown } =
-    Promise.withResolvers<void>();
-
-  const run = createCommonRun({ ...deps, shutdown } as D & ShutdownDep);
-
-  const console = run.deps.console.child("global");
-
-  const handleError = (source: string) => (error: unknown) => {
-    console.error(source, createUnknownError(error));
-    process.exitCode = 1;
-
-    // Resolve shutdown so `await run.deps.shutdown` unblocks
-    // and allows the stack to be disposed.
-    resolveShutdown();
-  };
-
-  const handleUncaughtException = handleError("uncaughtException");
-  const handleUnhandledRejection = handleError("unhandledRejection");
-
-  process.on("uncaughtException", handleUncaughtException);
-  process.on("unhandledRejection", handleUnhandledRejection);
-  process.on("SIGINT", resolveShutdown); // Ctrl-C (all platforms)
-  process.on("SIGTERM", resolveShutdown); // OS/k8s/Docker termination (Unix)
-  process.on("SIGHUP", resolveShutdown); // Console close (Windows), terminal disconnect (Unix)
-  process.on("SIGBREAK", resolveShutdown); // Ctrl-Break (Windows)
-
-  run.onAbort(() => {
-    process.off("uncaughtException", handleUncaughtException);
-    process.off("unhandledRejection", handleUnhandledRejection);
-    process.off("SIGINT", resolveShutdown);
-    process.off("SIGTERM", resolveShutdown);
-    process.off("SIGHUP", resolveShutdown);
-    process.off("SIGBREAK", resolveShutdown);
+export function runMain<T extends void | Resource>(
+  main: Task<T>,
+  options?: RunMainOptions,
+): Promise<void>;
+/** With custom dependencies. */
+export function runMain<D extends object>(
+  deps: RunCustomDeps<D>,
+  options?: RunMainOptions,
+): <T extends void | Resource>(main: Task<T, never, D>) => Promise<void>;
+export function runMain<T extends void | Resource, D extends object>(
+  mainOrDeps: Task<T> | RunCustomDeps<D>,
+  { mode = "service" }: RunMainOptions = {},
+):
+  | Promise<void>
+  | (<R extends void | Resource>(main: Task<R, never, D>) => Promise<void>) {
+  return typeof mainOrDeps === "function"
+    ? runMainInternal(mainOrDeps, {}, mode)
+    : (main) => runMainInternal(main, mainOrDeps, mode);
+}
+
+const commandExitCodeBySignal: Readonly<Record<NodeSignal, number>> = {
+  SIGINT: 130,
+  SIGTERM: 143,
+  SIGBREAK: 149,
+};
+
+const runMainInternal = async <T extends void | Resource, D extends object>(
+  main: Task<T, never, D>,
+  deps: RunCustomDeps<D> & Partial<ConsoleDep & ReportDefectDep>,
+  mode: RunMainMode,
+): Promise<void> => {
+  const console = deps.console ?? createConsole();
+  const mainConsole = console.child("main");
+
+  let defectReported = false as boolean;
+  let receivedSignal = null as NodeSignal | null;
+
+  await using disposer = new AsyncDisposableStack();
+  const run = disposer.use(
+    createRun<D>({
+      ...deps,
+      console,
+      reportDefect: (reported) => {
+        defectReported = true;
+        process.exitCode = 1;
+        if (deps.reportDefect) deps.reportDefect(reported);
+        else console.error(reported);
+      },
+    }),
+  );
+
+  (["SIGINT", "SIGTERM", "SIGBREAK"] as const).forEach((signal) => {
+    const handleSignal = (): void => {
+      if (receivedSignal !== null) {
+        mainConsole.warn("Forcing shutdown...");
+        process.exit(commandExitCodeBySignal[signal]);
+        return;
+      }
+
+      receivedSignal = signal;
+      mainConsole.info("Shutting down...");
+      run.abort({ type: "NodeSignalAbortReason", signal });
+    };
+
+    process.on(signal, handleSignal);
+    run.defer(() => {
+      process.off(signal, handleSignal);
+    });
   });
 
-  return run;
+  try {
+    await run(async (run) => {
+      const resource = await run.ok(main);
+      if (!isDisposable(resource)) return ok();
+
+      await using _resource = resource;
+      return await run(waitForAbort);
+    });
+  } catch {
+    // Aborts are control flow; defects are already handled by reportDefect.
+  }
+
+  // Move ownership out of the await-using setup safety net so an already
+  // reported finalizer defect can be suppressed during explicit disposal.
+  try {
+    await disposer.move().disposeAsync();
+  } catch {
+    // Finalizer defects are already handled by reportDefect.
+  }
+
+  if (receivedSignal !== null) {
+    if (defectReported) mainConsole.warn("Shutdown finished with errors");
+    else mainConsole.info("Shutdown complete");
+    if (mode === "command")
+      process.exitCode ??= commandExitCodeBySignal[receivedSignal];
+  }
 };