@executablemd/runtime 0.7.0 → 0.8.0

package/esm/apis.js

@@ -1,7 +1,8 @@
 /**
  * Runtime Context APIs — platform I/O operations with pluggable middleware.
  *
- * Five domain-specific context APIs built on `@effectionx/context-api`.
+ * Five host-backed domain APIs plus the provider-neutral Service Api, built on
+ * `@effectionx/context-api`.
  * Each API provides default Node.js implementations. Use `.around()` to
  * install middleware (mocking, instrumentation, sandboxing) scoped to the
  * current Effection scope.
@@ -25,14 +26,19 @@
  * });
  * ```
  *
- * ## Why four separate APIs?
+ * ## Why separate APIs?
  *
  * - **Process** — subprocess lifecycle has its own cancellation semantics
  *   (killing processes on scope teardown). Middleware targets exec only.
- * - **Fs** — reading, writing, and inspecting files form a cohesive file-IO
- *   surface used together for component resolution, replay guards, and the
- *   `<File>` component. Middleware installed here sees a document's own file
- *   access on the same terms as the engine's.
+ * - **Fs** — the low-level host file surface: reading, writing, and inspecting
+ *   paths the engine itself resolves, for component lookup, replay guards, and
+ *   the root document. It is the host adapter's own dependency, not the
+ *   boundary a document's paths cross.
+ * - **Files** — document filesystem access, in whole semantic operations
+ *   (`files.ts`). `<File>`, `<Glob>`, and `<TempDir>` speak only this Api, so
+ *   the same document means the same thing whether its paths resolve in the
+ *   caller's filesystem or in a run-owned logical one. Its terminal handler
+ *   throws: an uninstalled provider must not silently reach the host.
  * - **Fetch** — HTTP has distinct timeout/body/abort semantics. Merging
  *   with Fs or Process would blur cancellation boundaries.
  * - **Env** — the host itself: metadata (env vars, platform) plus the two
@@ -41,6 +47,8 @@
  *   use `.around()` to mock platform/env for deterministic replay; an
  *   entrypoint installs its `command` and `compile` with `{ at: "min" }` so
  *   ordinary middleware can wrap them.
+ * - **Service** — scoped service attachment. Its terminal handler requires an
+ *   explicit host provider and never detects or imports a runtime.
  *
  * ## Middleware
  *
@@ -59,7 +67,8 @@
  * ## Test stubs
  *
  * Common stubs are provided by `@executablemd/runtime/test`:
- * `useStubFs(files)`, `useEchoExec()`, `useFailingExec(code, stderr)`.
+ * `useStubFs(files)`, `useEchoExec()`, `useFailingExec(code, stderr)`,
+ * `useStubService(endpoint)`.
  */
 import { createApi } from "@effectionx/context-api";
 import { join } from "node:path";
@@ -67,9 +76,11 @@ import process from "node:process";
 import { realpath as fsRealpath, rename as fsRename } from "node:fs/promises";
 import { fetch as effectionFetch } from "@effectionx/fetch";
 import { ensureDir as fsEnsureDir, FsApi, globToRegExp, readTextFile as fsReadTextFile, rm as fsRm, stat as fsStat, writeTextFile as fsWriteTextFile, } from "@effectionx/fs";
-import { exec as processExec } from "@effectionx/process";
-import { race, sleep, until } from "effection";
-import { timeout as contextualTimeout } from "./config.js";
+import { exec as processExec, Stdio } from "@effectionx/process";
+import { race, scoped, sleep, until } from "effection";
+import { timeoutFetch as contextualFetchTimeout } from "./config.js";
+import { Files } from "./files.js";
+import { Service } from "./service.js";
 /**
  * The `errno` string a failed filesystem call carries, when it carries one.
  *
@@ -84,6 +95,72 @@ function errorCode(error) {
     const { code } = error;
     return typeof code === "string" ? code : undefined;
 }
+/**
+ * Record what this call receives, from before the child exists.
+ *
+ * Installed on the stdio chain before acquisition, so a chunk forwarded while
+ * the child is being started is received like any other. What arrives here is
+ * what enclosing middleware forwarded: a host that transforms, redacts,
+ * redirects, or consumes output upstream of this call is trusted preprocessing,
+ * and its result is what a caller is told the command produced.
+ *
+ * What this does not promise is the tail. The record is read when the `Process`
+ * operation settles, and that can happen before the pumps have finished, so
+ * this claims no pump-complete delivery (effectionx #244).
+ */
+function* retaining() {
+    let stdout = "";
+    let stderr = "";
+    // One decoder per channel: a code point split across chunks belongs to the
+    // channel that split it, and sharing decoder state would let one channel
+    // corrupt the other's partial character.
+    const fromStdout = new TextDecoder();
+    const fromStderr = new TextDecoder();
+    yield* Stdio.around({
+        *stdout([bytes], next) {
+            stdout += fromStdout.decode(bytes, { stream: true });
+            return yield* next(bytes);
+        },
+        *stderr([bytes], next) {
+            stderr += fromStderr.decode(bytes, { stream: true });
+            return yield* next(bytes);
+        },
+    });
+    // Flushed once, when the caller reads — that is, when the `Process` operation
+    // settles. `Process.join()` may settle before the pumps and their middleware
+    // finish, so a tail written as they settle may never have reached the
+    // handlers above; effectionx #244 owns that.
+    return {
+        stdout: () => stdout + fromStdout.decode(),
+        stderr: () => stderr + fromStderr.decode(),
+    };
+}
+/**
+ * Run one child to completion and report what the caller asked to keep.
+ *
+ * Forwarding and retention are separate paths through the same process: the
+ * `Stdio` chain displays every chunk whatever this decides, and a transient run
+ * subscribes to nothing, so a command that writes a gigabyte costs a gigabyte
+ * of nothing.
+ */
+function* run(options) {
+    return yield* scoped(function* () {
+        // Before acquisition, so a chunk written while the child is being started
+        // is retained rather than raced for.
+        const kept = options.retain ? yield* retaining() : undefined;
+        const child = yield* processExec(options.command, {
+            arguments: options.args,
+            cwd: options.cwd,
+            env: options.env,
+        });
+        const status = yield* child.join();
+        return {
+            exitCode: status.code ?? 1,
+            stdout: kept?.stdout(),
+            stderr: kept?.stderr(),
+        };
+    });
+}
 function* withTimeout(label, timeout, operation) {
     if (timeout === undefined) {
         return yield* operation;
@@ -199,22 +276,14 @@ export const API = {
      */
     Process: createApi("runtime.process", {
         *exec(options) {
-            const { command, cwd, env, timeout } = options;
+            const { command, cwd, env, timeout, retain = true } = options;
             const [cmd, ...args] = command;
             if (!cmd) {
                 throw new Error("exec: command array must not be empty");
             }
-            const effectiveTimeout = timeout ?? (yield* contextualTimeout);
-            const result = yield* withTimeout(`exec(${cmd})`, effectiveTimeout, processExec(cmd, {
-                arguments: args,
-                cwd,
-                env,
-            }).join());
-            return {
-                exitCode: result.code ?? 1,
-                stdout: result.stdout,
-                stderr: result.stderr,
-            };
+            // No contextual fallback: what bounds an exec block is resolved where the
+            // block is, and arrives here as this option (spec §Config).
+            return yield* withTimeout(`exec(${cmd})`, timeout, run({ command: cmd, args, cwd, env, retain }));
         },
     }),
     /**
@@ -286,7 +355,7 @@ export const API = {
      */
     Fetch: createApi("runtime.fetch", {
         *fetch(input, init) {
-            const timeout = init?.timeout ?? (yield* contextualTimeout);
+            const timeout = init?.timeout ?? (yield* contextualFetchTimeout);
             const response = yield* withTimeout(`fetch(${input})`, timeout, effectionFetch(input, {
                 method: init?.method,
                 headers: init?.headers,
@@ -344,8 +413,12 @@ export const API = {
             throw new Error("compiler not installed — install platform-specific middleware via API.Env.around()");
         },
     }),
+    Files,
+    Service,
 };
-export const exec = API.Process.operations.exec;
+export function exec(options) {
+    return API.Process.operations.exec(options);
+}
 export const readTextFile = API.Fs.operations.readTextFile;
 export const stat = API.Fs.operations.stat;
 export const glob = API.Fs.operations.glob;
@@ -360,3 +433,25 @@ export const cwd = API.Env.operations.cwd;
 export const platform = API.Env.operations.platform;
 export const command = API.Env.operations.command;
 export const compile = API.Env.operations.compile;
+/**
+ * Discard the standard output of subprocesses started in this scope.
+ *
+ * For a caller whose subprocess output is an *answer* rather than something to
+ * show: a command whose stdout is parsed and returned would otherwise also
+ * print itself into whatever the process was rendering. `stderr` is left alone,
+ * because that is where a failing command explains itself and a diagnostic is
+ * worth seeing.
+ *
+ * It lives here because reaching the process Api's stdio directly is host
+ * behavior, and modules held to the runtime-neutral boundary may not import a
+ * host process module of their own.
+ *
+ * Installed at the display boundary, where the host's own writer sits: not
+ * showing something and not knowing it are different, and a caller that asked
+ * for the answer must still be given it. Anything upstream — this adapter's
+ * retention, a document's capture, a run's record — reads the bytes first and
+ * only the host is left out.
+ */
+export function useQuietProcessOutput() {
+    return Stdio.around({ *stdout() { } }, { at: "min" });
+}

package/esm/config.js

@@ -1,29 +1,58 @@
 /**
  * Config Api — shared execution configuration with pluggable middleware.
  *
- * Supplies the contextual timeout in milliseconds. Process, Fetch, and
- * Agent operations read it when a call does not provide an explicit
- * timeout. Override it for a scope with:
+ * Three timeouts, three owners, no defaults:
+ *
+ * - `timeout` is the deadline for the whole run — preparation and execution
+ *   together — and only the outer run boundary consumes it.
+ * - `timeoutExec` is what each exec block gets, and only exec blocks and the
+ *   built-in `timeout` modifier consume it.
+ * - `timeoutFetch` is what each Fetch gets, and only Fetch consumes it.
+ *
+ * `undefined` means no timeout, and it is what every field starts as. An
+ * operation nobody bounded runs until it finishes or the run's own deadline
+ * cancels it; a general "shared timeout" that quietly bounded processes,
+ * requests, prompts, and services alike is what this replaces. Override a
+ * field for a scope with:
  *
  * ```typescript
- * yield* Config.around({ timeout: () => 30_000 }, { at: "min" });
+ * yield* Config.around({ timeoutExec: () => 30_000 }, { at: "min" });
  * ```
+ *
+ * Installing at `min` is what lets a nested override win: a block's own
+ * `timeout=` outranks the value the command line established for the run.
+ * Omitting a field inherits the enclosing value rather than clearing it.
  */
 import { createApi } from "@effectionx/context-api";
 export const Config = createApi("Config", {
-    timeout: 120_000,
+    timeout: undefined,
+    timeoutExec: undefined,
+    timeoutFetch: undefined,
 });
 /**
- * The validated contextual timeout. Always a positive, finite number of
- * milliseconds — a middleware-supplied value that is not valid fails loudly
- * here rather than silently disabling or corrupting timeouts downstream.
+ * A configured duration is milliseconds or nothing. Anything else fails here,
+ * before the operation it was meant to bound starts, rather than disabling or
+ * corrupting the bound downstream.
  */
-export const timeout = {
-    *[Symbol.iterator]() {
-        const value = yield* Config.operations.timeout;
-        if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
-            throw new Error(`Config timeout must be a positive, finite number of milliseconds, got ${String(value)}`);
-        }
-        return value;
-    },
-};
+function validate(name, value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        throw new Error(`Config ${name} must be a positive, finite number of milliseconds, got ${String(value)}`);
+    }
+    return value;
+}
+function validated(name, source) {
+    return {
+        *[Symbol.iterator]() {
+            return validate(name, yield* source);
+        },
+    };
+}
+/** The validated run deadline. Read by the run boundary and nothing else. */
+export const timeout = validated("timeout", Config.operations.timeout);
+/** The validated default timeout for an exec block. */
+export const timeoutExec = validated("timeoutExec", Config.operations.timeoutExec);
+/** The validated default timeout for a Fetch. */
+export const timeoutFetch = validated("timeoutFetch", Config.operations.timeoutFetch);

package/esm/duration.js

@@ -0,0 +1,44 @@
+/**
+ * The duration grammar, in one place.
+ *
+ * Every timeout a caller or a document writes is spelled the same way: the
+ * three CLI options, and the `timeout=` modifier a block declares. A duration
+ * is a positive whole number with a unit — `500ms`, `30s`, `5min`, `20min` —
+ * or bare digits, which are milliseconds.
+ *
+ * Nothing here substitutes a value. An empty, zero, negative, or malformed
+ * duration is refused where it was written, because the alternative is a run
+ * bounded by a number nobody asked for.
+ */
+const DURATION = /^(\d+)(ms|s|min|m)?$/;
+const MULTIPLIER = {
+    ms: 1,
+    s: 1_000,
+    m: 60_000,
+    min: 60_000,
+};
+/** Milliseconds, or `undefined` when `text` is not a duration. */
+export function asDuration(text) {
+    const match = DURATION.exec(text.trim());
+    if (match === null) {
+        return undefined;
+    }
+    const [, digits = "", unit = "ms"] = match;
+    const value = Number(digits) * (MULTIPLIER[unit] ?? 1);
+    if (!Number.isFinite(value) || value <= 0) {
+        return undefined;
+    }
+    return value;
+}
+/** What a rejected duration says, with `label` naming where it was written. */
+export function durationError(label, text) {
+    return new Error(`${label} must be a duration like 500ms, 30s, or 5min, got ${JSON.stringify(text)}`);
+}
+/** Milliseconds. Throws when `text` is not a duration this grammar accepts. */
+export function parseDuration(text, label) {
+    const value = asDuration(text);
+    if (value === undefined) {
+        throw durationError(label, text);
+    }
+    return value;
+}