@executablemd/runtime 0.10.2 → 0.12.0

package/esm/config.js

@@ -22,12 +22,21 @@
  * 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.
+ *
+ * `verbose` is the fourth field and is not a timeout. It says whether the
+ * scope reading it renders verbose-only content, it is `false` until something
+ * says otherwise, and it is installed and overridden exactly the way a timeout
+ * is. It bounds nothing, opens nothing and decides nothing about authority: a
+ * component reads it to choose between rendering its content and rendering
+ * nothing, and the host's own presentation — the journal, the event echo, the
+ * testing report — is decided by the command line rather than by this field.
  */
 import { createApi } from "@effectionx/context-api";
 export const Config = createApi("Config", {
     timeout: undefined,
     timeoutExec: undefined,
     timeoutFetch: undefined,
+    verbose: false,
 });
 /**
  * A configured duration is milliseconds or nothing. Anything else fails here,
@@ -56,3 +65,21 @@ export const timeout = validated("timeout", Config.operations.timeout);
 export const timeoutExec = validated("timeoutExec", Config.operations.timeoutExec);
 /** The validated default timeout for a Fetch. */
 export const timeoutFetch = validated("timeoutFetch", Config.operations.timeoutFetch);
+/**
+ * The validated verbosity of the reading scope.
+ *
+ * There is no "absent" verbosity the way there is an absent timeout: a scope
+ * either renders verbose-only content or it does not. Anything that is not a
+ * boolean — what an untyped JavaScript consumer can still install — fails
+ * here, where the reader asked, rather than being read as truthiness by
+ * whichever component asked first.
+ */
+export const verbose = {
+    *[Symbol.iterator]() {
+        const configured = yield* Config.operations.verbose;
+        if (typeof configured !== "boolean") {
+            throw new Error(`Config verbose must be a boolean, got ${String(configured)}`);
+        }
+        return configured;
+    },
+};

package/esm/files.js

@@ -83,6 +83,7 @@ const OPERATIONS = [
     "check-file-path",
     "read",
     "delete",
+    "ensure-directory",
     "glob",
     "temporary-directory",
 ];
@@ -556,6 +557,10 @@ export const Files = createApi("executablemd.runtime.files", {
         throw new FilesProviderUnavailableError();
     },
     // deno-lint-ignore require-yield
+    *ensureDirectory(_input) {
+        throw new FilesProviderUnavailableError();
+    },
+    // deno-lint-ignore require-yield
     *globFiles(_input) {
         throw new FilesProviderUnavailableError();
     },

package/esm/host-files.js

@@ -238,6 +238,43 @@ function* removalDestination(input) {
         return { reason: reasonOf(error) };
     }
 }
+/**
+ * The directory a `<Dir>` names, which is the one target that may be absolute.
+ *
+ * Every other operation here refuses an absolute path outright, because a
+ * document that writes one is naming a place outside the work it was given.
+ * `<Dir>` is the established exception: an absolute `path` has always been used
+ * as written, and this operation exists to serve that component. So an absolute
+ * target is taken as it stands and is not measured against the working
+ * directory — there is no base it was ever relative to.
+ *
+ * A relative target keeps the ordinary rules: resolved against `cwd`, with both
+ * sides canonical, so a working directory reached through a symlink is not read
+ * as an escape and a `..` that genuinely leaves still is.
+ *
+ * The final segment is resolved along with the rest. A directory that already
+ * exists behind a symlink is the directory it points at, and entering it is
+ * what the document asked for.
+ */
+function* directoryDestination(input) {
+    try {
+        if (isAbsolute(input.path)) {
+            return { path: yield* resolveExisting(input.path) };
+        }
+        if (!within(input.cwd, resolve(input.cwd, input.path))) {
+            return { reason: "lexical-escape" };
+        }
+        const base = (yield* API.Fs.operations.realpath(input.cwd)) ?? input.cwd;
+        const path = yield* resolveExisting(resolve(input.cwd, input.path));
+        if (!within(base, path)) {
+            return { reason: "resolved-escape" };
+        }
+        return { path };
+    }
+    catch (error) {
+        return { reason: reasonOf(error) };
+    }
+}
 function nonWriteFailure(operation, phase, reason) {
     return Err(filesFailure({ operation, phase, reason }));
 }
@@ -472,6 +509,57 @@ export function hostFilesHandler(options = {}) {
         }
         return Ok(undefined);
     }
+    /**
+     * Make the named path a directory, creating what is missing.
+     *
+     * Three answers, and the order between them is the contract. An existing
+     * directory is success without touching it: nothing is replaced, cleared or
+     * written, because the document asked for the directory to exist and it does.
+     * An existing entry that is not a directory is a refusal — a file where a
+     * directory was asked for is a mistake to report, never a thing to remove.
+     * Anything else is created, recursively, along with every missing parent.
+     *
+     * The target is classified before creation is attempted so the refusal for a
+     * non-directory target is decided here rather than left to whatever the
+     * platform's `mkdir -p` happens to say. An intermediate non-directory is the
+     * platform's to report, and `ENOTDIR` already carries it into the shared
+     * vocabulary — so both refusals arrive as `not-directory` and neither carries
+     * a host path or a platform message.
+     *
+     * Creation is direct and persists. There is no rollback and no teardown
+     * removal: a later failure of the content that runs inside this directory
+     * says nothing about whether the directory should exist.
+     */
+    function* ensureDirectory(input) {
+        if (input.path.length === 0) {
+            return nonWriteFailure("ensure-directory", "lexical", "empty-path");
+        }
+        const target = yield* directoryDestination(input);
+        if ("reason" in target) {
+            return nonWriteFailure("ensure-directory", "resolution", target.reason);
+        }
+        notify(observe, { operation: "ensure-directory", phase: "target" });
+        try {
+            const info = yield* API.Fs.operations.stat(target.path);
+            if (info.exists && !info.isDirectory) {
+                return nonWriteFailure("ensure-directory", "target", "not-directory");
+            }
+            if (info.exists) {
+                return Ok(undefined);
+            }
+        }
+        catch (error) {
+            return nonWriteFailure("ensure-directory", "target", reasonOf(error));
+        }
+        notify(observe, { operation: "ensure-directory", phase: "access" });
+        try {
+            yield* API.Fs.operations.ensureDir(target.path);
+        }
+        catch (error) {
+            return nonWriteFailure("ensure-directory", "access", reasonOf(error));
+        }
+        return Ok(undefined);
+    }
     /**
      * The regular files under `cwd` that `include` selects and `exclude` does not.
      *
@@ -550,7 +638,15 @@ export function hostFilesHandler(options = {}) {
             yield* provide(Ok(canonical));
         });
     }
-    return { checkFilePath, readTextFile, writeTextFile, deleteFile, globFiles, temporaryDirectory };
+    return {
+        checkFilePath,
+        readTextFile,
+        writeTextFile,
+        deleteFile,
+        ensureDirectory,
+        globFiles,
+        temporaryDirectory,
+    };
 }
 /**
  * Remove a temporary directory as its scope ends.
@@ -612,6 +708,9 @@ export function useHostFiles(options = {}) {
         *deleteFile([input]) {
             return yield* handler.deleteFile(input);
         },
+        *ensureDirectory([input]) {
+            return yield* handler.ensureDirectory(input);
+        },
         *globFiles([input]) {
             return yield* handler.globFiles(input);
         },

package/esm/launcher.js

@@ -27,7 +27,8 @@
  * document help and inspection free of any of this.
  */
 import { createApi } from "@effectionx/context-api";
-import { ensure, race, resource, scoped, until, withResolvers } from "effection";
+import { ensure, race, resource, scoped, until } from "effection";
+import { once } from "@effectionx/node/events";
 import { spawn as spawnChild } from "node:child_process";
 import process from "node:process";
 export const NATIVE_LAUNCHER_UNAVAILABLE = "no native launcher is installed — this host does not hand a native agent UI " +
@@ -141,8 +142,6 @@ function runForeground(request) {
         if (command === undefined) {
             throw new Error("native launch: command must not be empty");
         }
-        const settled = withResolvers();
-        const failed = withResolvers();
         let child;
         // Interrupt, then insist. A cancelled document may not continue — or
         // finish tearing down — while a child still holds the terminal, so this
@@ -153,28 +152,42 @@ function runForeground(request) {
         // `inherit` is the whole point: the child reads this terminal and draws on
         // it directly, so nothing between it and the person using it can buffer,
         // reorder, capture or journal what passes.
-        child = spawnChild(command, args, {
+        const started = spawnChild(command, args, {
             cwd: request.cwd,
             env: request.env,
             stdio: "inherit",
         });
-        child.once("error", (error) => failed.reject(error));
-        child.once("exit", (code, signal) => {
-            const outcome = {};
-            if (code !== null) {
-                outcome.exitCode = code;
-            }
-            if (signal !== null) {
-                outcome.signal = signal;
-            }
-            settled.resolve(outcome);
-        });
-        return yield* race([settled.operation, failed.operation]);
+        child = started;
+        // Raced inline, in the same synchronous run as the spawn, so both arms are
+        // attached before the child can report anything — a spawned race attaches
+        // a turn later. Whichever loses is halted, which is what detaches it.
+        return yield* race([
+            (function* () {
+                const [code, signal] = yield* once(started, "exit");
+                const outcome = {};
+                if (code !== null) {
+                    outcome.exitCode = code;
+                }
+                if (signal !== null) {
+                    outcome.signal = signal;
+                }
+                return outcome;
+            })(),
+            (function* () {
+                const [error] = yield* once(started, "error");
+                throw error;
+            })(),
+        ]);
     });
 }
 /**
  * End one foreground child and wait for it to be gone.
  *
+ * Exported for `packages/runtime/tests/native-launcher.test.ts` and not from
+ * `mod.ts`: the listener this installs belongs to a bounded Promise, and the
+ * only way to observe that it is released on every settlement path is to hold
+ * the child.
+ *
  * Deliberately one promise rather than an Effection race: this runs while the
  * scope is already being dismantled, and the cheapest correct thing to do
  * there is to wait on the process's own events instead of starting more
@@ -184,7 +197,7 @@ function runForeground(request) {
  * is spent — a native UI holding the terminal is not something a cancelled run
  * can afford to wait on indefinitely.
  */
-function reap(child) {
+export function reap(child) {
     const pid = child.pid;
     if (pid === undefined || child.exitCode !== null || child.signalCode !== null) {
         return Promise.resolve();
@@ -206,6 +219,10 @@ function reap(child) {
             clearInterval(poll);
             clearTimeout(escalation);
             clearTimeout(deadline);
+            // The one funnel every settlement goes through — the exit event, the
+            // reachability poll, the escalation deadline, and the refusal that
+            // rejects — so the handler comes off however this ends.
+            child.off("exit", onExit);
             // Deno's `node:child_process` stops reporting a child's exit once a
             // signal that child ignored has been delivered, and holds the runtime
             // open on the handle it will now never settle. Dropping the reference is
@@ -223,7 +240,8 @@ function reap(child) {
             }
             resolve();
         };
-        child.once("exit", () => done());
+        const onExit = () => done();
+        child.on("exit", onExit);
         // Reachability rather than the exit event, because that is the fact this
         // has to establish and the event is not dependable across runtimes here.
         const poll = setInterval(() => {

package/esm/mod.js

@@ -19,7 +19,8 @@
  * - `API.Service` — scoped attached service startup (`startService`)
  * - `NativeLauncher` — handing one native agent UI the foreground terminal
  *   (`reserveTerminal`, `flushOutput`, `nativeLaunch`)
- * - `Config` — shared execution config (`timeout`, `timeoutExec`, `timeoutFetch`)
+ * - `Config` — shared execution config (`timeout`, `timeoutExec`, `timeoutFetch`,
+ *   `verbose`)
  *
  * See `apis.ts` for architecture rationale.
  * See `@executablemd/runtime/test` for composable test stubs.
@@ -28,7 +29,7 @@ import "./_dnt.polyfills.js";
 export { API } from "./apis.js";
 export { exec, readTextFile, writeTextFile, stat, lstat, readDirectory, glob, realpath, ensureDir, rename, remove, fetch, cwd, env, platform, command, compile, useQuietProcessOutput, } from "./apis.js";
 export { Service, SERVICE_HOSTNAME, SERVICE_READY_PREFIX, ServiceProcessExitBeforeReadyError, ServiceProtocolDuplicateError, ServiceProtocolHostnameMismatchError, ServiceProtocolIncompatibleError, ServiceProtocolMalformedError, ServiceProtocolTokenMismatchError, ServiceProviderError, ServiceStartupTimeoutError, ServiceTeardownError, ServiceUnexpectedExitError, parseServiceReadyRecord, startService, } from "./service.js";
-export { Config, timeout, timeoutExec, timeoutFetch } from "./config.js";
+export { Config, timeout, timeoutExec, timeoutFetch, verbose } from "./config.js";
 export { asDuration, durationError, parseDuration } from "./duration.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 { flushOutput, installControlledLauncher, installForegroundLauncher, NATIVE_LAUNCHER_UNAVAILABLE, NativeLauncher, NativeLauncherUnavailableError, nativeLaunch, NO_TERMINAL, reserveTerminal, } from "./launcher.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@executablemd/runtime",
-  "version": "0.10.2",
+  "version": "0.12.0",
   "description": "Runtime host APIs for executable.md documents.",
   "homepage": "https://executable.md",
   "repository": {
@@ -38,9 +38,9 @@
     "@effectionx/context-api": "0.6.0",
     "@effectionx/fetch": "0.2.1",
     "@effectionx/fs": "0.3.0",
+    "@effectionx/node": "0.2.5",
     "@effectionx/process": "0.8.1",
-    "effection": "4.1.0",
-    "@effectionx/node": "0.2.4"
+    "effection": "4.1.0"
   },
   "_generatedBy": "dnt@dev"
 }

package/types/config.d.ts

@@ -22,6 +22,14 @@
  * 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.
+ *
+ * `verbose` is the fourth field and is not a timeout. It says whether the
+ * scope reading it renders verbose-only content, it is `false` until something
+ * says otherwise, and it is installed and overridden exactly the way a timeout
+ * is. It bounds nothing, opens nothing and decides nothing about authority: a
+ * component reads it to choose between rendering its content and rendering
+ * nothing, and the host's own presentation — the journal, the event echo, the
+ * testing report — is decided by the command line rather than by this field.
  */
 import { type Api } from "@effectionx/context-api";
 import type { Operation } from "effection";
@@ -32,6 +40,8 @@ export interface ConfigApi {
     timeoutExec: number | undefined;
     /** Default timeout for each Fetch, in milliseconds; undefined for none. */
     timeoutFetch: number | undefined;
+    /** Whether this scope renders verbose-only content; false for none. */
+    verbose: boolean;
 }
 export declare const Config: Api<ConfigApi>;
 /** The validated run deadline. Read by the run boundary and nothing else. */
@@ -40,3 +50,13 @@ export declare const timeout: Operation<number | undefined>;
 export declare const timeoutExec: Operation<number | undefined>;
 /** The validated default timeout for a Fetch. */
 export declare const timeoutFetch: Operation<number | undefined>;
+/**
+ * The validated verbosity of the reading scope.
+ *
+ * There is no "absent" verbosity the way there is an absent timeout: a scope
+ * either renders verbose-only content or it does not. Anything that is not a
+ * boolean — what an untyped JavaScript consumer can still install — fails
+ * here, where the reader asked, rather than being read as truthiness by
+ * whichever component asked first.
+ */
+export declare const verbose: Operation<boolean>;

package/types/files.d.ts

@@ -68,7 +68,7 @@ export declare const FILES_WRITE_SUCCESS = "executablemd.runtime.files-write-suc
  */
 export type FilesReason = "empty-path" | "absolute-path" | "lexical-escape" | "resolved-escape" | "missing" | "directory" | "special-file" | "not-directory" | "permission-denied" | "read-only" | "too-many-symlinks" | "path-too-long" | "no-space" | "quota-exhausted" | "cross-device" | "busy" | "too-many-open-files" | "directory-not-empty" | "invalid-pattern" | "operation-failed";
 /** The operations whose failure carries no commit outcome. */
-export type FilesOperation = "check-file-path" | "read" | "delete" | "glob" | "temporary-directory";
+export type FilesOperation = "check-file-path" | "read" | "delete" | "ensure-directory" | "glob" | "temporary-directory";
 /** Where a non-write operation stopped. */
 export type FilesPhase = "lexical" | "resolution" | "target" | "access" | "pattern" | "traversal" | "acquire";
 /** Where a write stopped, which is what decides what may be said about the target. */
@@ -145,6 +145,20 @@ export interface FilesHandler {
      * that same success.
      */
     deleteFile(input: FilePathInput): Operation<Result<void>>;
+    /**
+     * Make this path name a directory, and answer with nothing.
+     *
+     * Recursively creates the target and any missing parent. An existing
+     * directory is already the answer, so it succeeds without replacing it,
+     * clearing it or touching what is in it; a file or another non-directory, at
+     * the target or anywhere on the way to it, is a refusal.
+     *
+     * Mandatory like the rest, and Unit for the same reason `deleteFile` is: a
+     * document that asked for a directory to exist has been answered by its
+     * existence. Nothing comes back to branch on — no path, no handle, and no
+     * word on whether this call is what created it.
+     */
+    ensureDirectory(input: FilePathInput): Operation<Result<void>>;
     /** Sorted, deduplicated, POSIX-separated paths of the regular files that match. */
     globFiles(input: GlobInput): Operation<Result<string[]>>;
     /**

package/types/host-files.d.ts

@@ -74,7 +74,7 @@ import type { FilesHandler } from "./files.js";
  * observable rather than merely stated.
  */
 export interface HostFilesEvent {
-    readonly operation: "read" | "write" | "delete" | "glob";
+    readonly operation: "read" | "write" | "delete" | "ensure-directory" | "glob";
     readonly phase: "target" | "access" | "parents" | "temporary" | "commit" | "cleanup" | "read-dir";
 }
 /** Synchronous, so nothing can run between the observation and the call it precedes. */

package/types/launcher.d.ts

@@ -28,6 +28,7 @@
  */
 import { type Api } from "@effectionx/context-api";
 import type { Operation } from "effection";
+import type { ChildProcess } from "node:child_process";
 /**
  * What a provider asks the host to run.
  *
@@ -86,6 +87,24 @@ interface ForegroundLauncherOptions {
  * own its exit status, or continue after the UI closes.
  */
 export declare function installForegroundLauncher(options?: ForegroundLauncherOptions): Operation<void>;
+/**
+ * End one foreground child and wait for it to be gone.
+ *
+ * Exported for `packages/runtime/tests/native-launcher.test.ts` and not from
+ * `mod.ts`: the listener this installs belongs to a bounded Promise, and the
+ * only way to observe that it is released on every settlement path is to hold
+ * the child.
+ *
+ * Deliberately one promise rather than an Effection race: this runs while the
+ * scope is already being dismantled, and the cheapest correct thing to do
+ * there is to wait on the process's own events instead of starting more
+ * structured work beside them.
+ *
+ * A child that ignores the interrupt is killed outright once the grace period
+ * is spent — a native UI holding the terminal is not something a cancelled run
+ * can afford to wait on indefinitely.
+ */
+export declare function reap(child: ChildProcess): Promise<void>;
 /**
  * A launcher a host installs when it has no terminal to give away, and no
  * intention of starting a native UI.

package/types/mod.d.ts

@@ -19,7 +19,8 @@
  * - `API.Service` — scoped attached service startup (`startService`)
  * - `NativeLauncher` — handing one native agent UI the foreground terminal
  *   (`reserveTerminal`, `flushOutput`, `nativeLaunch`)
- * - `Config` — shared execution config (`timeout`, `timeoutExec`, `timeoutFetch`)
+ * - `Config` — shared execution config (`timeout`, `timeoutExec`, `timeoutFetch`,
+ *   `verbose`)
  *
  * See `apis.ts` for architecture rationale.
  * See `@executablemd/runtime/test` for composable test stubs.
@@ -30,7 +31,7 @@ export { exec, readTextFile, writeTextFile, stat, lstat, readDirectory, glob, re
 export type { DirectoryEntry, EvalBlock, FetchInit, FetchOperation, LinkStatResult, ResponseHeaders, RuntimeFetchResponse, StatResult, } from "./apis.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 { Config, timeout, timeoutExec, timeoutFetch, verbose } from "./config.js";
 export type { ConfigApi } from "./config.js";
 export { asDuration, durationError, parseDuration } from "./duration.js";
 export type { ProcessExecOptions, ProcessOutcome } from "./apis.js";