@executablemd/runtime 0.10.2 → 0.11.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/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.11.0",
   "description": "Runtime host APIs for executable.md documents.",
   "homepage": "https://executable.md",
   "repository": {

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/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";