@executablemd/runtime 0.6.0 → 0.7.0

package/esm/apis.js

@@ -29,13 +29,18 @@
  *
  * - **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** — 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.
  * - **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.
  *
  * ## Middleware
  *
@@ -57,13 +62,28 @@
  * `useStubFs(files)`, `useEchoExec()`, `useFailingExec(code, stderr)`.
  */
 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 { 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 { each, race, sleep } from "effection";
+import { race, sleep, until } from "effection";
 import { timeout as contextualTimeout } from "./config.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;
+}
 function* withTimeout(label, timeout, operation) {
     if (timeout === undefined) {
         return yield* operation;
@@ -79,6 +99,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.
@@ -125,7 +236,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 +244,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;
         },
     }),
     /**
@@ -201,18 +323,25 @@ 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()");
         },
     }),
 };
@@ -220,8 +349,14 @@ 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 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;

package/esm/mod.js

@@ -7,16 +7,18 @@
  *
  * Six domain APIs:
  * - `API.Process` — subprocess execution (`exec`)
- * - `API.Fs` — filesystem (`readTextFile`, `stat`, `glob`)
+ * - `API.Fs` — filesystem (`readTextFile`, `writeTextFile`, `stat`, `glob`,
+ *   `realpath`, `ensureDir`, `rename`, `remove`)
  * - `API.Fetch` — HTTP requests (`fetch`)
- * - `API.Env` — environment variables and platform info (`cwd`, `env`, `platform`)
- * - `API.Compiler` — block compilation (`compile`)
+ * - `API.Env` — the host: variables, platform info, the command that invokes
+ *   this xmd, and eval-block compilation
+ *   (`cwd`, `env`, `platform`, `command`, `compile`)
  * - `Config` — shared execution config (`timeout`)
  *
  * 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 { exec, readTextFile, writeTextFile, stat, glob, realpath, ensureDir, rename, remove, fetch, cwd, env, platform, command, compile, } from "./apis.js";
 export { findFreePort } from "./find-free-port.js";
 export { Config, timeout } from "./config.js";

package/esm/test/stubs.js

@@ -26,6 +26,9 @@ import { API } from "../apis.js";
  * - `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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@executablemd/runtime",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Runtime host APIs for executable.md documents.",
   "homepage": "https://executable.md",
   "repository": {

package/types/apis.d.ts

@@ -29,13 +29,18 @@
  *
  * - **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** — 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.
  * - **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.
  *
  * ## Middleware
  *
@@ -105,6 +110,22 @@ interface ProcessHandler {
 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 +134,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 +157,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 +170,30 @@ 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>;
     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 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;
 export {};

package/types/mod.d.ts

@@ -7,18 +7,20 @@
  *
  * Six domain APIs:
  * - `API.Process` — subprocess execution (`exec`)
- * - `API.Fs` — filesystem (`readTextFile`, `stat`, `glob`)
+ * - `API.Fs` — filesystem (`readTextFile`, `writeTextFile`, `stat`, `glob`,
+ *   `realpath`, `ensureDir`, `rename`, `remove`)
  * - `API.Fetch` — HTTP requests (`fetch`)
- * - `API.Env` — environment variables and platform info (`cwd`, `env`, `platform`)
- * - `API.Compiler` — block compilation (`compile`)
+ * - `API.Env` — the host: variables, platform info, the command that invokes
+ *   this xmd, and eval-block compilation
+ *   (`cwd`, `env`, `platform`, `command`, `compile`)
  * - `Config` — shared execution config (`timeout`)
  *
  * 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 { exec, readTextFile, writeTextFile, stat, glob, realpath, ensureDir, rename, remove, fetch, cwd, env, platform, command, compile, } from "./apis.js";
+export type { EvalBlock, ResponseHeaders, RuntimeFetchResponse, StatResult } from "./apis.js";
 export { findFreePort } from "./find-free-port.js";
 export { Config, timeout } from "./config.js";
 export type { ConfigApi } from "./config.js";

package/types/test/stubs.d.ts

@@ -26,6 +26,9 @@ import type { Operation } from "effection";
  * - `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