@executablemd/runtime 0.6.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,17 +26,29 @@
  * });
  * ```
  *
- * ## 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** — readTextFile, stat, and glob form a cohesive file-IO surface
- *   used together for component resolution and replay guards.
+ * - **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** — synchronous host metadata (env vars, platform). Kept as a
- *   context-api despite being sync because tests use `.around()` to mock
- *   platform/env for deterministic replay testing.
+ * - **Env** — the host itself: metadata (env vars, platform) plus the two
+ *   capabilities only the entrypoint can supply, `command` (how to re-invoke
+ *   this xmd) and `compile` (how this host loads a generated module). Tests
+ *   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
  *
@@ -54,16 +67,100 @@
  * ## 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 { relative, sep } from "node:path";
+import { join } from "node:path";
 import process from "node:process";
+import { realpath as fsRealpath, rename as fsRename } from "node:fs/promises";
 import { fetch as effectionFetch } from "@effectionx/fetch";
-import { readTextFile as fsReadTextFile, stat as fsStat, globToRegExp, walk } from "@effectionx/fs";
-import { exec as processExec } from "@effectionx/process";
-import { each, race, sleep } from "effection";
-import { timeout as contextualTimeout } from "./config.js";
+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, 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.
+ *
+ * Read rather than asserted: `catch` gives back `unknown`, and what arrives
+ * there is only conventionally an `ErrnoException`. Narrowing says what is
+ * actually known about the value instead of claiming a shape it may not have.
+ */
+function errorCode(error) {
+    if (typeof error !== "object" || error === null || !("code" in error)) {
+        return undefined;
+    }
+    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;
@@ -79,6 +176,97 @@ function* withTimeout(label, timeout, operation) {
         })(),
     ]));
 }
+/**
+ * A glob pattern as a matcher for relative POSIX paths.
+ *
+ * A pattern that cannot be compiled throws here — an unterminated character
+ * class is a `SyntaxError` from `RegExp` — so it surfaces from `glob` itself
+ * rather than silently matching nothing.
+ */
+function toRegExp(pattern) {
+    return globToRegExp(pattern, { extended: true, globstar: true });
+}
+/**
+ * A matcher for directories whose entire subtree an exclusion covers, when the
+ * pattern is one that can prove it.
+ *
+ * Skipping a subtree is only sound if *every* path beneath it is excluded, and
+ * matching the directory tells us nothing of the sort: `foo` does not match
+ * `foo/deep/keep.md`, and `foo/*` matches `foo/direct.md` but stops at the next
+ * separator. Testing the directory — or the directory with a trailing separator
+ * — as a proxy for "all descendants" prunes more than the pattern selects.
+ *
+ * A trailing `/**` is the form that does prove it. It compiles to
+ * `(?:[^/]*(?:/|$))*`, which matches any sequence of segments, so once the part
+ * before it matches a directory the pattern matches every path under that
+ * directory at any depth. `**` alone covers the whole tree the same way.
+ *
+ * Anything else returns `undefined` and the subtree is walked, with its files
+ * filtered one at a time. That is the conservative direction: descending a
+ * subtree whose files are all excluded costs reads, while skipping one that
+ * holds a match loses the match.
+ */
+const SUBTREE = "/**";
+function isRegExp(value) {
+    return value !== undefined;
+}
+function pruneMatcher(pattern) {
+    if (pattern === "**") {
+        return toRegExp("**");
+    }
+    if (!pattern.endsWith(SUBTREE)) {
+        return undefined;
+    }
+    return toRegExp(pattern.slice(0, -SUBTREE.length));
+}
+/**
+ * Collect matches under `directory`, whose path relative to the glob root is
+ * `prefix`.
+ *
+ * A plain recursive generator rather than `@effectionx/fs`'s `walk()`, whose
+ * producer runs in a spawned task: a `readdir` that fails there tears down the
+ * surrounding scope instead of throwing at the call site, so no caller can
+ * report it. Recursing here makes a failure `glob`'s own, and makes every
+ * directory read a cancellation point.
+ *
+ * Paths are assembled from entry names with `/`, so what patterns match is the
+ * relative POSIX path on every platform.
+ *
+ * Exclusion is decided per **candidate**: a file or symlink whose own path an
+ * exclude pattern matches is not reported, which is what makes exclusions win.
+ * A directory is not a candidate — it is never reported — so its own path is
+ * not tested against exclusions at all. The only question a directory raises is
+ * whether walking it can still produce something, and that is `pruneMatcher`'s.
+ */
+function* descend(directory, prefix, walk) {
+    for (const entry of yield* FsApi.operations.readdirDirents(directory)) {
+        const path = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+        // Before the exclusion test, because a directory is not a candidate: an
+        // exclusion matching its path says nothing about the files beneath it.
+        // A symlink to a directory takes the branches below instead — `isDirectory`
+        // is false for one — so traversal never follows it.
+        if (entry.isDirectory()) {
+            if (!walk.prune.some((re) => re.test(path))) {
+                yield* descend(join(directory, entry.name), path, walk);
+            }
+            continue;
+        }
+        if (walk.exclude.some((re) => re.test(path))) {
+            continue;
+        }
+        // A symlink is reported by its own path and never followed, so traversal
+        // stays under the root and cannot cycle.
+        if (entry.isSymbolicLink()) {
+            if (walk.include.some((re) => re.test(path))) {
+                walk.matched.push({ path, isFile: false });
+            }
+            continue;
+        }
+        if (entry.isFile() && walk.include.some((re) => re.test(path))) {
+            walk.matched.push({ path, isFile: true });
+        }
+    }
+}
 export const API = {
     /**
      * Subprocess execution.
@@ -88,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 }));
         },
     }),
     /**
@@ -125,7 +305,7 @@ export const API = {
                 };
             }
             catch (err) {
-                if (err.code === "ENOENT") {
+                if (errorCode(err) === "ENOENT") {
                     return { exists: false, isFile: false, isDirectory: false };
                 }
                 throw err;
@@ -133,27 +313,38 @@ export const API = {
         },
         *glob(options) {
             const { patterns, root, exclude = [] } = options;
-            const results = [];
-            // Convert include/exclude patterns to RegExp for matching
-            // against relative paths from root
-            const includeRegexes = patterns.map((p) => globToRegExp(p, { extended: true, globstar: true }));
-            const excludeRegexes = exclude.map((e) => globToRegExp(e, { extended: true, globstar: true }));
-            // Walk the directory tree and match relative paths
-            const stream = walk(root, {
-                includeFiles: true,
-                includeDirs: false,
-                skip: excludeRegexes.length > 0 ? excludeRegexes : undefined,
+            const matched = [];
+            yield* descend(root, "", {
+                include: patterns.map(toRegExp),
+                exclude: exclude.map(toRegExp),
+                prune: exclude.map(pruneMatcher).filter(isRegExp),
+                matched,
             });
-            for (const entry of yield* each(stream)) {
-                // Normalize to POSIX separators for consistent matching across platforms
-                const relPath = relative(root, entry.path).split(sep).join("/");
-                const matches = includeRegexes.some((re) => re.test(relPath));
-                if (matches) {
-                    results.push({ path: relPath, isFile: entry.isFile });
+            return matched;
+        },
+        *writeTextFile(path, content) {
+            yield* fsWriteTextFile(path, content);
+        },
+        *ensureDir(path) {
+            yield* fsEnsureDir(path);
+        },
+        *rename(from, to) {
+            yield* until(fsRename(from, to));
+        },
+        *remove(path, options) {
+            yield* fsRm(path, options);
+        },
+        *realpath(path) {
+            try {
+                return yield* until(fsRealpath(path));
+            }
+            catch (err) {
+                const code = errorCode(err);
+                if (code === "ENOENT" || code === "ENOTDIR") {
+                    return undefined;
                 }
-                yield* each.next();
+                throw err;
             }
-            return results;
         },
     }),
     /**
@@ -164,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,
@@ -201,27 +392,66 @@ export const API = {
                 arch: process.arch,
             };
         },
-    }),
-    /**
-     * Block compilation.
-     *
-     * Default handler throws — platform-specific middleware must be
-     * installed via `yield* API.Compiler.around(...)` before use.
-     * See `packages/core/src/deno-compiler.ts` for the Deno implementation.
-     */
-    Compiler: createApi("runtime.compiler", {
+        /**
+         * The default cannot be derived. `process.execPath` names the executable
+         * but not how it was launched — `deno run --allow-all <entry>` and
+         * `node <entry>` are not recoverable from "deno" or "node", and a
+         * compiled binary takes no entry script at all. Only the entrypoint that
+         * started this process knows.
+         */
+        // deno-lint-ignore require-yield
+        *command(_args) {
+            throw new Error("xmd command not installed — a runtime-named entrypoint must install it via API.Env.around()");
+        },
+        /**
+         * Compiling an eval block means loading a module the way this host
+         * loads modules, so the implementation belongs with the entrypoint that
+         * knows the host — beside `command`, installed in the same call.
+         */
         // deno-lint-ignore require-yield
         *compile(_source, _options) {
-            throw new Error("compiler not installed — install platform-specific middleware via API.Compiler.around()");
+            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;
+export const writeTextFile = API.Fs.operations.writeTextFile;
+export const ensureDir = API.Fs.operations.ensureDir;
+export const rename = API.Fs.operations.rename;
+export const remove = API.Fs.operations.remove;
+export const realpath = API.Fs.operations.realpath;
 export const fetch = API.Fetch.operations.fetch;
 export const env = API.Env.operations.env;
 export const cwd = API.Env.operations.cwd;
 export const platform = API.Env.operations.platform;
-export const compile = API.Compiler.operations.compile;
+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;
+}