@executablemd/runtime 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Taras Mankovski
+
+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/esm/apis.js

@@ -0,0 +1,237 @@
+/**
+ * Runtime Context APIs — platform I/O operations with pluggable middleware.
+ *
+ * Five domain-specific context APIs 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.
+ *
+ * ## Architecture
+ *
+ * Import operation functions for normal calls, and use `API` only when
+ * installing middleware with `.around()`:
+ *
+ * ```typescript
+ * import { readTextFile, stat, API } from "@executablemd/runtime";
+ *
+ * // normal calls
+ * const file = yield* readTextFile("doc.md");
+ *
+ * // middleware
+ * yield* API.Fs.around({
+ *   *readTextFile([path], next) {
+ *     return yield* next(path);
+ *   },
+ * });
+ * ```
+ *
+ * ## Why four 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.
+ * - **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.
+ *
+ * ## Middleware
+ *
+ * ```typescript
+ * yield* API.Fs.around({
+ *   *readTextFile([path], next) {
+ *     return "mocked content";
+ *   },
+ * });
+ * ```
+ *
+ * Middleware is **scoped** — it only affects operations within the
+ * current Effection scope and its children. Install before calling
+ * `runDocument()` or `durableRun()`.
+ *
+ * ## Test stubs
+ *
+ * Common stubs are provided by `@executablemd/runtime/test`:
+ * `useStubFs(files)`, `useEchoExec()`, `useFailingExec(code, stderr)`.
+ */
+import { createApi } from "@effectionx/context-api";
+import { relative, sep } from "node:path";
+import process from "node:process";
+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";
+// ---------------------------------------------------------------------------
+// Private helpers
+// ---------------------------------------------------------------------------
+function* withTimeout(label, timeout, operation) {
+    if (timeout === undefined) {
+        return yield* operation;
+    }
+    if (!Number.isFinite(timeout) || timeout < 0) {
+        throw new Error(`${label}: timeout must be a non-negative finite number`);
+    }
+    return (yield* race([
+        operation,
+        (function* () {
+            yield* sleep(timeout);
+            throw new Error(`${label} timed out after ${timeout}ms`);
+        })(),
+    ]));
+}
+// ---------------------------------------------------------------------------
+// Context APIs
+// ---------------------------------------------------------------------------
+export const API = {
+    /**
+     * Subprocess execution.
+     *
+     * Default implementation uses `@effectionx/process`.
+     * Cancellation kills the process via Effection scope teardown.
+     */
+    Process: createApi("runtime.process", {
+        *exec(options) {
+            const { command, cwd, env, timeout } = options;
+            const [cmd, ...args] = command;
+            if (!cmd) {
+                throw new Error("exec: command array must not be empty");
+            }
+            const result = yield* withTimeout(`exec(${cmd})`, timeout, processExec(cmd, {
+                arguments: args,
+                cwd,
+                env,
+            }).join());
+            return {
+                exitCode: result.code ?? 1,
+                stdout: result.stdout,
+                stderr: result.stderr,
+            };
+        },
+    }),
+    /**
+     * Filesystem operations.
+     *
+     * Default implementation uses `@effectionx/fs`.
+     */
+    Fs: createApi("runtime.fs", {
+        *readTextFile(path) {
+            return yield* fsReadTextFile(path);
+        },
+        *stat(path) {
+            try {
+                const s = yield* fsStat(path);
+                return {
+                    exists: true,
+                    isFile: s.isFile(),
+                    isDirectory: s.isDirectory(),
+                };
+            }
+            catch (err) {
+                if (err.code === "ENOENT") {
+                    return { exists: false, isFile: false, isDirectory: false };
+                }
+                throw err;
+            }
+        },
+        *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,
+            });
+            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 });
+                }
+                yield* each.next();
+            }
+            return results;
+        },
+    }),
+    /**
+     * HTTP requests.
+     *
+     * Default implementation uses `@effectionx/fetch`.
+     * Cancellation aborts the request via Effection scope teardown.
+     */
+    Fetch: createApi("runtime.fetch", {
+        *fetch(input, init) {
+            const timeout = init?.timeout;
+            const response = yield* withTimeout(`fetch(${input})`, timeout, effectionFetch(input, {
+                method: init?.method,
+                headers: init?.headers,
+                body: init?.body,
+            }));
+            return {
+                status: response.status,
+                headers: response.headers,
+                *text() {
+                    return yield* withTimeout(`fetch(${input}).text()`, timeout, response.text());
+                },
+            };
+        },
+    }),
+    /**
+     * Environment variables and platform information.
+     *
+     * These are synchronous lookups wrapped as Operations to satisfy
+     * context-api handler constraints.
+     */
+    Env: createApi("runtime.env", {
+        // deno-lint-ignore require-yield
+        *cwd() {
+            return process.cwd();
+        },
+        // deno-lint-ignore require-yield
+        *env(name) {
+            return process.env[name];
+        },
+        // deno-lint-ignore require-yield
+        *platform() {
+            return {
+                os: process.platform,
+                arch: process.arch,
+            };
+        },
+    }),
+    /**
+     * Block compilation.
+     *
+     * Default handler throws — platform-specific middleware must be
+     * installed via `yield* API.Compiler.around(...)` before use.
+     * See `core/src/deno-compiler.ts` for the Deno implementation.
+     */
+    Compiler: createApi("runtime.compiler", {
+        // deno-lint-ignore require-yield
+        *compile(_source, _options) {
+            throw new Error("compiler not installed — install platform-specific middleware via API.Compiler.around()");
+        },
+    }),
+};
+// ---------------------------------------------------------------------------
+// Convenience operation exports
+//
+// Use these for normal operation calls. Use API.* only when installing
+// middleware with .around().
+// ---------------------------------------------------------------------------
+export const exec = API.Process.operations.exec;
+export const readTextFile = API.Fs.operations.readTextFile;
+export const stat = API.Fs.operations.stat;
+export const glob = API.Fs.operations.glob;
+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;

package/esm/find-free-port.js

@@ -0,0 +1,33 @@
+/**
+ * findFreePort — find an available TCP port using the OS.
+ */
+import { race } from "effection";
+import { once } from "@effectionx/node";
+import { createServer } from "node:net";
+/**
+ * Find an available TCP port by binding to port 0 and reading the
+ * OS-assigned port number.
+ */
+export function* findFreePort() {
+    const server = createServer();
+    const listening = once(server, "listening");
+    const error = once(server, "error");
+    server.listen(0);
+    try {
+        const rethrowError = {
+            *[Symbol.iterator]() {
+                const [err] = yield* error;
+                throw err;
+            },
+        };
+        yield* race([listening, rethrowError]);
+        const addr = server.address();
+        if (!addr || typeof addr !== "object") {
+            throw new Error("findFreePort: unexpected address format");
+        }
+        return addr.port;
+    }
+    finally {
+        server.close();
+    }
+}

package/esm/mod.js

@@ -0,0 +1,20 @@
+/**
+ * @module
+ * Runtime Context APIs for executable markdown.
+ *
+ * `API` is available for middleware (`.around()`).
+ * For normal calls, import operations directly.
+ *
+ * Six domain APIs:
+ * - `API.Process` — subprocess execution (`exec`)
+ * - `API.Fs` — filesystem (`readTextFile`, `stat`, `glob`)
+ * - `API.Fetch` — HTTP requests (`fetch`)
+ * - `API.Env` — environment variables and platform info (`cwd`, `env`, `platform`)
+ * - `API.Compiler` — block compilation (`compile`)
+ *
+ * See `apis.ts` for architecture rationale.
+ * See `@executablemd/runtime/test` for composable test stubs.
+ */
+export { API } from "./apis.js";
+export { exec, readTextFile, stat, glob, fetch, cwd, env, platform, compile } from "./apis.js";
+export { findFreePort } from "./find-free-port.js";

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/esm/test/mod.js

@@ -0,0 +1,10 @@
+/**
+ * @module
+ * Test helpers for executable markdown runtime.
+ *
+ * Composable stubs for runtime context APIs:
+ * - `useStubFs(files)` — in-memory filesystem
+ * - `useEchoExec()` — simple echo-based exec
+ * - `useFailingExec(exitCode, stderr)` — always-failing exec
+ */
+export { useStubFs, useEchoExec, useFailingExec } from "./stubs.js";

package/esm/test/stubs.js

@@ -0,0 +1,80 @@
+/**
+ * Composable test stubs for runtime context APIs.
+ *
+ * These helpers install `around()` middleware on the runtime context APIs
+ * to replace real I/O with in-memory implementations. They are scoped to
+ * the current Effection scope — call them before `runDocument()` or
+ * `durableRun()` in your test body.
+ *
+ * @example
+ * ```typescript
+ * import { useStubFs, useEchoExec } from "@executablemd/runtime/test";
+ *
+ * it("runs a document with stubbed I/O", function* () {
+ *   yield* useStubFs({ "doc.md": "# Hello\n" });
+ *   yield* useEchoExec();
+ *
+ *   const execution = yield* runDocument({ docPath: "doc.md", stream });
+ *   const output = yield* execution;
+ * });
+ * ```
+ */
+import { API } from "../apis.js";
+/**
+ * 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 `files` object is captured **by reference** — mutating it between
+ * operations changes what `readTextFile`/`stat` see. This is useful for
+ * testing file changes between runs.
+ */
+export function* useStubFs(files) {
+    yield* API.Fs.around({
+        *readTextFile([path], _next) {
+            const content = files[path];
+            if (content === undefined) {
+                throw new Error(`ENOENT: no such file: ${path}`);
+            }
+            return content;
+        },
+        *stat([path], _next) {
+            const exists = path in files;
+            return { exists, isFile: exists, isDirectory: false };
+        },
+        *glob(_args, _next) {
+            throw new Error("glob not stubbed");
+        },
+    });
+}
+/**
+ * Install a simple exec stub that handles `echo` commands.
+ *
+ * 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.
+ */
+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: "" };
+        },
+    });
+}
+/**
+ * Install an exec stub that always returns the given exit code and stderr.
+ *
+ * Useful for testing error handling paths.
+ */
+export function* useFailingExec(exitCode, stderr = "command failed") {
+    yield* API.Process.around({
+        *exec(_args, _next) {
+            return { exitCode, stdout: "", stderr };
+        },
+    });
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@executablemd/runtime",
+  "version": "0.2.0",
+  "description": "Runtime host APIs for executable.md documents.",
+  "homepage": "https://executable.md",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taras/executable.md.git"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/taras/executable.md/issues"
+  },
+  "module": "./esm/mod.js",
+  "types": "./types/mod.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./types/mod.d.ts",
+        "default": "./esm/mod.js"
+      }
+    },
+    "./test": {
+      "import": {
+        "types": "./types/test/mod.d.ts",
+        "default": "./esm/test/mod.js"
+      }
+    }
+  },
+  "scripts": {},
+  "dependencies": {
+    "@effectionx/context-api": "0.6.0",
+    "@effectionx/fetch": "0.2.0",
+    "@effectionx/fs": "0.3.0",
+    "@effectionx/node": "0.2.4",
+    "@effectionx/process": "0.8.1",
+    "effection": "4.1.0-alpha.7"
+  },
+  "_generatedBy": "dnt@dev"
+}

package/types/apis.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Runtime Context APIs — platform I/O operations with pluggable middleware.
+ *
+ * Five domain-specific context APIs 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.
+ *
+ * ## Architecture
+ *
+ * Import operation functions for normal calls, and use `API` only when
+ * installing middleware with `.around()`:
+ *
+ * ```typescript
+ * import { readTextFile, stat, API } from "@executablemd/runtime";
+ *
+ * // normal calls
+ * const file = yield* readTextFile("doc.md");
+ *
+ * // middleware
+ * yield* API.Fs.around({
+ *   *readTextFile([path], next) {
+ *     return yield* next(path);
+ *   },
+ * });
+ * ```
+ *
+ * ## Why four 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.
+ * - **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.
+ *
+ * ## Middleware
+ *
+ * ```typescript
+ * yield* API.Fs.around({
+ *   *readTextFile([path], next) {
+ *     return "mocked content";
+ *   },
+ * });
+ * ```
+ *
+ * Middleware is **scoped** — it only affects operations within the
+ * current Effection scope and its children. Install before calling
+ * `runDocument()` or `durableRun()`.
+ *
+ * ## Test stubs
+ *
+ * Common stubs are provided by `@executablemd/runtime/test`:
+ * `useStubFs(files)`, `useEchoExec()`, `useFailingExec(code, stderr)`.
+ */
+import { type Api } from "@effectionx/context-api";
+import type { Operation } from "effection";
+/**
+ * Result of a `stat` call.
+ *
+ * For missing paths `stat` returns `{ exists: false, isFile: false, isDirectory: false }`
+ * instead of throwing — "does this exist?" has "no" as a valid answer.
+ */
+export interface StatResult {
+    exists: boolean;
+    isFile: boolean;
+    isDirectory: boolean;
+}
+/**
+ * Minimal response headers interface.
+ *
+ * Uses a minimal interface instead of the global `Headers` type to avoid
+ * requiring DOM lib types in tsconfig.
+ */
+export interface ResponseHeaders {
+    get(key: string): string | null;
+}
+/**
+ * Response shape returned by the fetch context API.
+ *
+ * Both the response object and `text()` are Operation-native — no Promises
+ * cross the interface boundary.
+ */
+export interface RuntimeFetchResponse {
+    status: number;
+    headers: ResponseHeaders;
+    /** Read the response body as text. */
+    text(): Operation<string>;
+}
+interface ProcessHandler {
+    exec(options: {
+        command: string[];
+        cwd?: string;
+        env?: Record<string, string>;
+        timeout?: number;
+    }): Operation<{
+        exitCode: number;
+        stdout: string;
+        stderr: string;
+    }>;
+}
+interface FsHandler {
+    readTextFile(path: string): Operation<string>;
+    stat(path: string): Operation<StatResult>;
+    glob(options: {
+        patterns: string[];
+        root: string;
+        exclude?: string[];
+    }): Operation<Array<{
+        path: string;
+        isFile: boolean;
+    }>>;
+}
+interface FetchHandler {
+    fetch(input: string, init?: {
+        method?: string;
+        headers?: Record<string, string>;
+        body?: string;
+        timeout?: number;
+    }): Operation<RuntimeFetchResponse>;
+}
+interface EnvHandler {
+    cwd(): Operation<string>;
+    env(name: string): Operation<string | undefined>;
+    platform(): Operation<{
+        os: string;
+        arch: string;
+    }>;
+}
+interface CompilerHandler {
+    compile(source: string, options?: {
+        imports: string[];
+    }): Operation<(env: Record<string, unknown>) => Generator<unknown, unknown, unknown>>;
+}
+export declare const API: {
+    Process: Api<ProcessHandler>;
+    Fs: Api<FsHandler>;
+    Fetch: Api<FetchHandler>;
+    Env: Api<EnvHandler>;
+    Compiler: Api<CompilerHandler>;
+};
+export declare const exec: typeof API.Process.operations.exec;
+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 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 {};

package/types/find-free-port.d.ts

@@ -0,0 +1,9 @@
+/**
+ * findFreePort — find an available TCP port using the OS.
+ */
+import type { Operation } from "effection";
+/**
+ * Find an available TCP port by binding to port 0 and reading the
+ * OS-assigned port number.
+ */
+export declare function findFreePort(): Operation<number>;

package/types/mod.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @module
+ * Runtime Context APIs for executable markdown.
+ *
+ * `API` is available for middleware (`.around()`).
+ * For normal calls, import operations directly.
+ *
+ * Six domain APIs:
+ * - `API.Process` — subprocess execution (`exec`)
+ * - `API.Fs` — filesystem (`readTextFile`, `stat`, `glob`)
+ * - `API.Fetch` — HTTP requests (`fetch`)
+ * - `API.Env` — environment variables and platform info (`cwd`, `env`, `platform`)
+ * - `API.Compiler` — block compilation (`compile`)
+ *
+ * See `apis.ts` for architecture rationale.
+ * See `@executablemd/runtime/test` for composable test stubs.
+ */
+export { API } from "./apis.js";
+export { exec, readTextFile, stat, glob, fetch, cwd, env, platform, compile } from "./apis.js";
+export type { ResponseHeaders, RuntimeFetchResponse, StatResult } from "./apis.js";
+export { findFreePort } from "./find-free-port.js";

package/types/test/mod.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @module
+ * Test helpers for executable markdown runtime.
+ *
+ * Composable stubs for runtime context APIs:
+ * - `useStubFs(files)` — in-memory filesystem
+ * - `useEchoExec()` — simple echo-based exec
+ * - `useFailingExec(exitCode, stderr)` — always-failing exec
+ */
+export { useStubFs, useEchoExec, useFailingExec } from "./stubs.js";

package/types/test/stubs.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Composable test stubs for runtime context APIs.
+ *
+ * These helpers install `around()` middleware on the runtime context APIs
+ * to replace real I/O with in-memory implementations. They are scoped to
+ * the current Effection scope — call them before `runDocument()` or
+ * `durableRun()` in your test body.
+ *
+ * @example
+ * ```typescript
+ * import { useStubFs, useEchoExec } from "@executablemd/runtime/test";
+ *
+ * it("runs a document with stubbed I/O", function* () {
+ *   yield* useStubFs({ "doc.md": "# Hello\n" });
+ *   yield* useEchoExec();
+ *
+ *   const execution = yield* runDocument({ docPath: "doc.md", stream });
+ *   const output = yield* execution;
+ * });
+ * ```
+ */
+import type { Operation } from "effection";
+/**
+ * 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 `files` object is captured **by reference** — mutating it between
+ * operations changes what `readTextFile`/`stat` see. This is useful for
+ * testing file changes between runs.
+ */
+export declare function useStubFs(files: Record<string, string>): Operation<void>;
+/**
+ * Install a simple exec stub that handles `echo` commands.
+ *
+ * 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.
+ */
+export declare function useEchoExec(): Operation<void>;
+/**
+ * Install an exec stub that always returns the given exit code and stderr.
+ *
+ * Useful for testing error handling paths.
+ */
+export declare function useFailingExec(exitCode: number, stderr?: string): Operation<void>;