@executablemd/runtime 0.7.0 → 0.8.1

package/types/host-files.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The host `API.Files` provider — document filesystem access in the caller's
+ * own filesystem.
+ *
+ * This is what `xmd run` installs. A document's relative path is resolved
+ * against the contextual working directory and used as an ordinary host path,
+ * so a document can hand a file to a tool the caller already has. Everything
+ * below is built on the low-level `API.Fs`, which is deliberate: a host that
+ * already wraps `API.Fs` to observe or sandbox the engine's own file access
+ * keeps seeing a document's access on the same terms.
+ *
+ * ## What containment means here
+ *
+ * Access is confined to the contextual directory, judged against the filesystem
+ * as this adapter observes it. An empty path, an absolute path, and a lexical
+ * `..` escape are refused without touching the filesystem at all; a symlink
+ * leading out is refused once resolution can see it.
+ *
+ * That is sound **while the host pathname namespace is stable**, and every
+ * guarantee here is stated on that basis. It is not a sandbox. Another process
+ * can replace a directory, symlink, junction, or reparse point between the
+ * moment this adapter observes a path and the moment it uses one, and nothing
+ * available on the shipped runtimes closes that window without a native
+ * dependency. What is contained is the document's own children — the case a
+ * document controls — because resolution is deferred until after they run.
+ *
+ * ## Writes
+ *
+ * A write goes through a sibling temporary file and a rename. The rename is the
+ * commit point: everything before it can fail or be cancelled with the previous
+ * file untouched, and once it begins the target holds the complete old file or
+ * the complete new one, never a partial write. It is a commit rather than a
+ * transaction — a rename that returned is not undone by a later cancellation.
+ * The temporary also closes the one hole resolution cannot: a dangling symlink
+ * has nothing to resolve, and `rename` replaces the link rather than following
+ * it wherever it points.
+ *
+ * ## What crosses the boundary
+ *
+ * Nothing from a caught platform error. An errno code *selects* a
+ * `FilesReason`, and the reason is all the consumer receives — no message, no
+ * code, no resolved path, no temporary path, and no symlink target. A platform
+ * error names the path it failed on, and for a write that path can be a
+ * temporary the document never chose.
+ */
+import type { Operation } from "effection";
+import type { FilesHandler } from "./files.js";
+/**
+ * A private step a host operation is about to take.
+ *
+ * Test-only. Production entrypoints install the adapter without one, so this is
+ * neither global state nor a capability: an observer can watch, and the point of
+ * watching is to replace part of the tree between an observation and the call
+ * that follows it, which is how the stable-namespace limitation is made
+ * observable rather than merely stated.
+ */
+export interface HostFilesEvent {
+    readonly operation: "read" | "write" | "glob";
+    readonly phase: "target" | "access" | "parents" | "temporary" | "commit" | "cleanup" | "read-dir";
+}
+/** Synchronous, so nothing can run between the observation and the call it precedes. */
+export type HostFilesObserver = (event: HostFilesEvent) => void;
+export interface HostFilesOptions {
+    readonly observe?: HostFilesObserver;
+}
+/**
+ * Build a host provider.
+ *
+ * Exported so a test can drive one operation directly; entrypoints install it
+ * with {@link useHostFiles}.
+ */
+export declare function hostFilesHandler(options?: HostFilesOptions): FilesHandler;
+/**
+ * Install the host provider beneath ordinary middleware.
+ *
+ * `at: "min"` is what lets a host wrap document filesystem access without
+ * replacing it — middleware installed later sees these operations and can
+ * delegate to them.
+ */
+export declare function useHostFiles(options?: HostFilesOptions): Operation<void>;

package/types/mod.d.ts

@@ -5,22 +5,32 @@
  * `API` is available for middleware (`.around()`).
  * For normal calls, import operations directly.
  *
- * Six domain APIs:
+ * Seven domain APIs:
  * - `API.Process` — subprocess execution (`exec`)
- * - `API.Fs` — filesystem (`readTextFile`, `writeTextFile`, `stat`, `glob`,
- *   `realpath`, `ensureDir`, `rename`, `remove`)
+ * - `API.Fs` — the low-level host filesystem (`readTextFile`, `writeTextFile`,
+ *   `stat`, `glob`, `realpath`, `ensureDir`, `rename`, `remove`)
+ * - `API.Files` — document filesystem access as whole semantic operations,
+ *   with no host default. `useHostFiles()` installs the host provider.
  * - `API.Fetch` — HTTP requests (`fetch`)
  * - `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`)
+ * - `API.Service` — scoped attached service startup (`startService`)
+ * - `Config` — shared execution config (`timeout`, `timeoutExec`, `timeoutFetch`)
  *
  * See `apis.ts` for architecture rationale.
  * See `@executablemd/runtime/test` for composable test stubs.
  */
 export { API } from "./apis.js";
-export { exec, readTextFile, writeTextFile, stat, glob, realpath, ensureDir, rename, remove, fetch, cwd, env, platform, command, compile, } from "./apis.js";
+export { exec, readTextFile, writeTextFile, stat, glob, realpath, ensureDir, rename, remove, fetch, cwd, env, platform, command, compile, useQuietProcessOutput, } 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 { Service, SERVICE_HOSTNAME, SERVICE_READY_PREFIX, ServiceProcessExitBeforeReadyError, ServiceProtocolDuplicateError, ServiceProtocolHostnameMismatchError, ServiceProtocolIncompatibleError, ServiceProtocolMalformedError, ServiceProtocolTokenMismatchError, ServiceProviderError, ServiceStartupTimeoutError, ServiceTeardownError, ServiceUnexpectedExitError, parseServiceReadyRecord, startService, } from "./service.js";
+export type { ServiceEndpoint, ServiceHandler, ServiceAttachment, ServiceStartOptions, } from "./service.js";
+export { Config, timeout, timeoutExec, timeoutFetch } from "./config.js";
 export type { ConfigApi } from "./config.js";
+export { asDuration, durationError, parseDuration } from "./duration.js";
+export type { ProcessExecOptions, ProcessOutcome } from "./apis.js";
+export { asFilesFatal, FILES_ERROR, FILES_ERROR_MESSAGE, FILES_FATAL, FILES_INVARIANT_MESSAGE, FILES_OPERATION_DENIED_MESSAGE, FILES_PROVIDER_UNAVAILABLE_MESSAGE, FILES_WRITE_SUCCESS, Files, FilesError, FilesInvariantError, FilesOperationDeniedError, FilesProviderUnavailableError, fileWriteFailure, fileWriteSuccess, filesFailure, isFilesFatal, parseFilesPhase, parseFilesReason, parseFileWriteFailure, parseFileWritePhase, parseFileWriteSuccess, parseFilesFailure, parseFilesFatal, } from "./files.js";
+export type { FilePathInput, FilesDeniableOperation, FilesErrorData, FilesFailureData, FilesFatalData, FilesFatalFailure, FilesHandler, FilesInvariantCategory, FilesOperation, FilesPhase, FilesReason, FileWriteFailureData, FileWriteInput, FileWritePhase, FileWriteSuccess, FileWriteTarget, GlobInput, } from "./files.js";
+export { hostFilesHandler, useHostFiles } from "./host-files.js";
+export type { HostFilesEvent, HostFilesObserver, HostFilesOptions } from "./host-files.js";

package/types/service.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Provider-neutral attached-service lifecycle.
+ *
+ * The shared runtime owns the XMD service handshake shape and validation. A
+ * runtime-named host adapter supplies process startup through `API.Service`
+ * middleware.
+ */
+import { type Api, type Operations } from "@effectionx/context-api";
+import type { Operation } from "effection";
+export declare const SERVICE_READY_PREFIX = "XMD_SERVICE_READY:";
+export declare const SERVICE_HOSTNAME = "127.0.0.1";
+export interface ServiceEndpoint {
+    readonly hostname: string;
+    readonly port: number;
+}
+export interface ServiceStartOptions {
+    readonly command: string;
+    readonly cwd?: string;
+    readonly startupTimeout?: number;
+}
+export interface ServiceAttachment {
+    readonly endpoint: Readonly<ServiceEndpoint>;
+}
+export interface ServiceHandler {
+    start(options: ServiceStartOptions): Operation<ServiceAttachment>;
+}
+export declare class ServiceProviderError extends Error {
+    name: string;
+    constructor();
+}
+export declare class ServiceProtocolMalformedError extends Error {
+    name: string;
+    constructor();
+}
+export declare class ServiceProtocolIncompatibleError extends Error {
+    name: string;
+    constructor();
+}
+export declare class ServiceProtocolTokenMismatchError extends Error {
+    name: string;
+    constructor();
+}
+export declare class ServiceProtocolHostnameMismatchError extends Error {
+    name: string;
+    constructor();
+}
+export declare class ServiceProtocolDuplicateError extends Error {
+    name: string;
+    constructor();
+}
+export declare class ServiceStartupTimeoutError extends Error {
+    name: string;
+    constructor(timeout: number);
+}
+interface ServiceExitStatus {
+    readonly code?: number;
+    readonly signal?: string;
+}
+export declare class ServiceProcessExitBeforeReadyError extends Error {
+    name: string;
+    constructor(status: ServiceExitStatus);
+}
+export declare class ServiceUnexpectedExitError extends Error {
+    name: string;
+    constructor(status: ServiceExitStatus);
+}
+export declare class ServiceTeardownError extends Error {
+    name: string;
+    constructor(options?: {
+        cause?: unknown;
+    });
+}
+/** Parse and authenticate one prefix-stripped v1 handshake payload. */
+export declare function parseServiceReadyRecord(payload: string, expectedToken: string): ServiceEndpoint;
+export declare const Service: Api<ServiceHandler>;
+export declare const startService: Operations<ServiceHandler>["start"];
+export {};

package/types/test/mod.d.ts

@@ -6,5 +6,6 @@
  * - `useStubFs(files)` — in-memory filesystem
  * - `useEchoExec()` — simple echo-based exec
  * - `useFailingExec(exitCode, stderr)` — always-failing exec
+ * - `useStubService(endpoint)` — scoped provider-neutral service attachment
  */
-export { useStubFs, useEchoExec, useFailingExec } from "./stubs.js";
+export { useStubFs, useEchoExec, useFailingExec, useStubService } from "./stubs.js";

package/types/test/stubs.d.ts

@@ -20,6 +20,9 @@
  * ```
  */
 import type { Operation } from "effection";
+import type { ServiceEndpoint } from "../service.js";
+/** Install a provider-neutral scoped service attachment stub. */
+export declare function useStubService(endpoint: ServiceEndpoint): Operation<void>;
 /**
  * Install an in-memory filesystem stub.
  *
@@ -40,6 +43,12 @@ export declare function useStubFs(files: Record<string, string>): Operation<void
  *
  * 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 declare function useEchoExec(): Operation<void>;
 /**

package/esm/find-free-port.js

@@ -1,33 +0,0 @@
-/**
- * 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/types/find-free-port.d.ts

@@ -1,9 +0,0 @@
-/**
- * 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>;