@executablemd/runtime 0.6.0 → 0.8.0

package/esm/test/stubs.js

@@ -19,13 +19,34 @@
  * });
  * ```
  */
+import { Stdio } from "@effectionx/process";
 import { API } from "../apis.js";
+import { SERVICE_HOSTNAME } from "../service.js";
+/** Install a provider-neutral scoped service attachment stub. */
+export function* useStubService(endpoint) {
+    if (endpoint.hostname !== SERVICE_HOSTNAME) {
+        throw new Error("stub service endpoint must use 127.0.0.1");
+    }
+    if (!Number.isInteger(endpoint.port) || endpoint.port < 1 || endpoint.port > 65_535) {
+        throw new Error("stub service endpoint port must be an integer from 1 through 65535");
+    }
+    const exact = Object.freeze({ hostname: SERVICE_HOSTNAME, port: endpoint.port });
+    yield* API.Service.around({
+        // deno-lint-ignore require-yield
+        *start() {
+            return { endpoint: exact };
+        },
+    });
+}
 /**
  * Install an in-memory filesystem stub.
  *
  * - `readTextFile` returns content from the `files` map; throws ENOENT for missing keys.
  * - `stat` returns `{ exists: true, isFile: true }` for keys in the map.
  * - `glob` throws (not stubbed). Install `API.Fs.around()` directly if needed.
+ * - the writing half — `writeTextFile`, `ensureDir`, `rename`, `remove`, and
+ *   `realpath` — is not stubbed and reaches the real filesystem. A test that
+ *   exercises a document writing files wants a real temporary directory.
  *
  * The `files` object is captured **by reference** — mutating it between
  * operations changes what `readTextFile`/`stat` see. This is useful for
@@ -54,15 +75,20 @@ export function* useStubFs(files) {
  *
  * Recognizes `bash -c "echo ..."` and returns the echo'd text as stdout.
  * All other commands return the script text as stdout with exit code 0.
+ *
+ * It answers like a real child: the text is written to the stdio chain as it
+ * "arrives", so whatever encloses the call sees it the way it would see a
+ * child's, and it is retained in the outcome only when the caller asked
+ * for retention. A stub that always returned strings would let a document
+ * render output the contract says was already displayed.
  */
 export function* useEchoExec() {
     yield* API.Process.around({
         *exec([options], _next) {
             const script = (options.command[2] ?? "").trim();
-            if (script.startsWith("echo ")) {
-                return { exitCode: 0, stdout: script.slice(5) + "\n", stderr: "" };
-            }
-            return { exitCode: 0, stdout: script + "\n", stderr: "" };
+            const text = script.startsWith("echo ") ? script.slice(5) + "\n" : script + "\n";
+            yield* Stdio.operations.stdout(encoder.encode(text));
+            return retained(options, { exitCode: 0, stdout: text, stderr: "" });
         },
     });
 }
@@ -73,8 +99,17 @@ export function* useEchoExec() {
  */
 export function* useFailingExec(exitCode, stderr = "command failed") {
     yield* API.Process.around({
-        *exec(_args, _next) {
-            return { exitCode, stdout: "", stderr };
+        *exec([options], _next) {
+            yield* Stdio.operations.stderr(encoder.encode(stderr));
+            return retained(options, { exitCode, stdout: "", stderr });
         },
     });
 }
+const encoder = new TextEncoder();
+/** What the caller asked to keep, so a stub cannot retain more than a call would. */
+function retained(options, outcome) {
+    if (options.retain === false) {
+        return { exitCode: outcome.exitCode, stdout: undefined, stderr: undefined };
+    }
+    return outcome;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@executablemd/runtime",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Runtime host APIs for executable.md documents.",
   "homepage": "https://executable.md",
   "repository": {
@@ -20,6 +20,12 @@
         "default": "./esm/mod.js"
       }
     },
+    "./files": {
+      "import": {
+        "types": "./types/files.d.ts",
+        "default": "./esm/files.js"
+      }
+    },
     "./test": {
       "import": {
         "types": "./types/test/mod.d.ts",
@@ -30,11 +36,11 @@
   "scripts": {},
   "dependencies": {
     "@effectionx/context-api": "0.6.0",
-    "@effectionx/fetch": "0.2.0",
+    "@effectionx/fetch": "0.2.1",
     "@effectionx/fs": "0.3.0",
-    "@effectionx/node": "0.2.4",
     "@effectionx/process": "0.8.1",
-    "effection": "4.1.0-alpha.10"
+    "effection": "4.1.0",
+    "@effectionx/node": "0.2.4"
   },
   "_generatedBy": "dnt@dev"
 }

package/types/apis.d.ts

@@ -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,10 +67,13 @@
  * ## 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 { type Api } from "@effectionx/context-api";
 import type { Operation } from "effection";
+import { Files } from "./files.js";
+import { Service } from "./service.js";
 /**
  * Result of a `stat` call.
  *
@@ -90,21 +106,54 @@ export interface RuntimeFetchResponse {
     /** Read the response body as text. */
     text(): Operation<string>;
 }
+/**
+ * What a finished child process reports.
+ *
+ * `stdout` and `stderr` are the text a caller asked to be retained. A caller
+ * that asked for none gets `undefined` rather than an empty string: nothing was
+ * accumulated, and "no output" and "not retained" are different answers.
+ */
+export interface ProcessOutcome {
+    exitCode: number;
+    stdout: string | undefined;
+    stderr: string | undefined;
+}
+export interface ProcessExecOptions {
+    command: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    timeout?: number;
+    /**
+     * Retain the child's output in the outcome. Default `true`.
+     *
+     * Retention is the caller's explicit choice, never an inference: a run that
+     * keeps no diagnostic record asks for `false` and the text is forwarded to
+     * whatever is displaying it without ever being accumulated here.
+     */
+    retain?: boolean;
+}
 interface ProcessHandler {
-    exec(options: {
-        command: string[];
-        cwd?: string;
-        env?: Record<string, string>;
-        timeout?: number;
-    }): Operation<{
-        exitCode: number;
-        stdout: string;
-        stderr: string;
-    }>;
+    exec(options: ProcessExecOptions): Operation<ProcessOutcome>;
 }
 interface FsHandler {
     readTextFile(path: string): Operation<string>;
     stat(path: string): Operation<StatResult>;
+    /**
+     * Files and symbolic links beneath `root` whose path relative to it matches
+     * `patterns` and matches none of `exclude`. Paths come back relative and
+     * POSIX-separated, which is what both pattern lists are matched against, so a
+     * caller's patterns mean the same thing on every platform.
+     *
+     * Exclusion is per candidate: an entry is dropped when its own relative path
+     * matches. Directories are not candidates and are not reported, so an
+     * exclusion matching a directory does not remove what is beneath it — only a
+     * pattern ending in `/**`, which provably covers every descendant, lets the
+     * subtree be skipped rather than walked and filtered.
+     *
+     * Symbolic links are reported but never followed: a link's own path can
+     * match, and a link to a directory is not descended into. Traversal
+     * therefore stays inside `root` and cannot cycle.
+     */
     glob(options: {
         patterns: string[];
         root: string;
@@ -113,6 +162,20 @@ interface FsHandler {
         path: string;
         isFile: boolean;
     }>>;
+    writeTextFile(path: string, content: string): Operation<void>;
+    ensureDir(path: string): Operation<void>;
+    rename(from: string, to: string): Operation<void>;
+    remove(path: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): Operation<void>;
+    /**
+     * The canonical path, with every symlink resolved, or `undefined` when the
+     * path does not exist. Like `stat`, "it isn't there" is an answer rather
+     * than a failure — a caller resolving a path it is about to create asks
+     * about ancestors that may legitimately be missing.
+     */
+    realpath(path: string): Operation<string | undefined>;
 }
 interface FetchHandler {
     fetch(input: string, init?: {
@@ -122,6 +185,12 @@ interface FetchHandler {
         timeout?: number;
     }): Operation<RuntimeFetchResponse>;
 }
+/**
+ * A compiled eval block accepts the document binding environment and returns
+ * an Operation. Current compilers implement it with generated `function*`
+ * modules, but callers do not depend on that representation.
+ */
+export type EvalBlock = (env: Record<string, unknown>) => Operation<unknown>;
 interface EnvHandler {
     cwd(): Operation<string>;
     env(name: string): Operation<string | undefined>;
@@ -129,26 +198,75 @@ interface EnvHandler {
         os: string;
         arch: string;
     }>;
-}
-interface CompilerHandler {
+    command(args?: string[]): Operation<string[]>;
     compile(source: string, options?: {
         imports: string[];
-    }): Operation<(env: Record<string, unknown>) => Generator<unknown, unknown, unknown>>;
+    }): Operation<EvalBlock>;
 }
 export declare const API: {
     Process: Api<ProcessHandler>;
     Fs: Api<FsHandler>;
+    Files: typeof Files;
     Fetch: Api<FetchHandler>;
     Env: Api<EnvHandler>;
-    Compiler: Api<CompilerHandler>;
+    Service: typeof Service;
 };
-export declare const exec: typeof API.Process.operations.exec;
+/**
+ * Run a child process.
+ *
+ * A caller that says nothing about retention keeps the output, which is what
+ * every caller with something to read wants and what callers have always had.
+ * Asking for `retain: false` keeps the exit status alone, and the overloads say
+ * so: there is no string to read on that path, and the type refuses to pretend
+ * otherwise. Core, which decides retention per block, calls the Api operation
+ * directly and handles both.
+ */
+export declare function exec(options: ProcessExecOptions & {
+    retain: false;
+}): Operation<{
+    exitCode: number;
+    stdout: undefined;
+    stderr: undefined;
+}>;
+export declare function exec(options: ProcessExecOptions & {
+    retain?: true;
+}): Operation<{
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}>;
 export declare const readTextFile: typeof API.Fs.operations.readTextFile;
 export declare const stat: typeof API.Fs.operations.stat;
 export declare const glob: typeof API.Fs.operations.glob;
+export declare const writeTextFile: typeof API.Fs.operations.writeTextFile;
+export declare const ensureDir: typeof API.Fs.operations.ensureDir;
+export declare const rename: typeof API.Fs.operations.rename;
+export declare const remove: typeof API.Fs.operations.remove;
+export declare const realpath: typeof API.Fs.operations.realpath;
 export declare const fetch: typeof API.Fetch.operations.fetch;
 export declare const env: typeof API.Env.operations.env;
 export declare const cwd: typeof API.Env.operations.cwd;
 export declare const platform: typeof API.Env.operations.platform;
-export declare const compile: typeof API.Compiler.operations.compile;
+export declare const command: typeof API.Env.operations.command;
+export declare const compile: typeof 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 declare function useQuietProcessOutput(): Operation<void>;
 export {};

package/types/config.d.ts

@@ -1,24 +1,42 @@
 /**
  * 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 { type Api } from "@effectionx/context-api";
 import type { Operation } from "effection";
 export interface ConfigApi {
-    /** Shared timeout in milliseconds. */
-    timeout: number;
+    /** Deadline for the entire run, in milliseconds; undefined for none. */
+    timeout: number | undefined;
+    /** Default timeout for each exec block, in milliseconds; undefined for none. */
+    timeoutExec: number | undefined;
+    /** Default timeout for each Fetch, in milliseconds; undefined for none. */
+    timeoutFetch: number | undefined;
 }
 export declare const Config: Api<ConfigApi>;
-/**
- * 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.
- */
-export declare const timeout: Operation<number>;
+/** The validated run deadline. Read by the run boundary and nothing else. */
+export declare const timeout: Operation<number | undefined>;
+/** The validated default timeout for an exec block. */
+export declare const timeoutExec: Operation<number | undefined>;
+/** The validated default timeout for a Fetch. */
+export declare const timeoutFetch: Operation<number | undefined>;

package/types/duration.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+/** Milliseconds, or `undefined` when `text` is not a duration. */
+export declare function asDuration(text: string): number | undefined;
+/** What a rejected duration says, with `label` naming where it was written. */
+export declare function durationError(label: string, text: string): Error;
+/** Milliseconds. Throws when `text` is not a duration this grammar accepts. */
+export declare function parseDuration(text: string, label: string): number;