@executablemd/runtime 0.12.0 → 0.13.1

package/esm/api.js

@@ -0,0 +1,22 @@
+/**
+ * @module
+ *
+ * The consumer API of `@executablemd/runtime`: the shared execution
+ * configuration a Plugin, a component package or a host reads.
+ *
+ * `Config` is the same Api the engine and the CLI already install and read;
+ * this entrypoint is where a consumer imports it from, so a package depending
+ * on runtime reaches its configuration without importing the whole host
+ * surface. The root export keeps every one of these names.
+ *
+ * ```ts
+ * import { verbose } from "@executablemd/runtime/api";
+ *
+ * if (yield* verbose) {
+ *   // render the detail a quiet run leaves out
+ * }
+ * ```
+ */
+import "./_dnt.polyfills.js";
+export { Config, timeout, timeoutExec, timeoutFetch, verbose } from "./config.js";
+export { asDuration, durationError, parseDuration } from "./duration.js";

package/esm/config.js

@@ -26,7 +26,7 @@
  * `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
+ * is. It bounds nothing, opens nothing and decides no permission: 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.

package/esm/files.js

@@ -20,7 +20,7 @@
  *
  * `checkFilePath` is the one exception, and it is deliberately weak: pure path
  * arithmetic, no filesystem access, and nothing usable comes back — no path, no
- * handle, no authority token. `<File>`'s write form calls it to decide whether
+ * handle, no capability token. `<File>`'s write form calls it to decide whether
  * its children may expand at all, and the later `writeTextFile` repeats the
  * same admission from the same authored path. A check that was skipped,
  * replaced, or answered by another provider therefore authorizes nothing.

package/esm/launcher.js

@@ -52,6 +52,10 @@ export const NativeLauncher = createApi("runtime.nativeLauncher", {
     *launch(_request) {
         throw new NativeLauncherUnavailableError();
     },
+    // deno-lint-ignore require-yield
+    *notify(_text) {
+        throw new NativeLauncherUnavailableError();
+    },
 });
 /** Hold the foreground-terminal lease for the calling scope. */
 export function reserveTerminal() {
@@ -61,6 +65,10 @@ export function reserveTerminal() {
 export function flushOutput() {
     return NativeLauncher.operations.flush();
 }
+/** Say one thing to whoever is at the terminal this launch reserved. */
+export function notifyTerminal(text) {
+    return NativeLauncher.operations.notify(text);
+}
 /** Run one native UI as a foreground child and report how it ended. */
 export function nativeLaunch(request) {
     return NativeLauncher.operations.launch(request);
@@ -118,6 +126,12 @@ export function* installForegroundLauncher(options = {}) {
         *launch([request]) {
             return yield* runForeground(request);
         },
+        *notify([text]) {
+            // Written and drained, not queued: the next thing to reach this
+            // terminal may be a child drawing over it.
+            process.stdout.write(`${text}\n`);
+            yield* drainStream(process.stdout);
+        },
     }, { at: "min" });
 }
 /**
@@ -329,6 +343,10 @@ export function* installControlledLauncher(options = {}) {
         *flush() {
             options.onFlush?.();
         },
+        // deno-lint-ignore require-yield
+        *notify([text]) {
+            options.onNotify?.(text);
+        },
         *launch([request]) {
             options.record?.(request);
             if (options.wait) {

package/esm/mod.js

@@ -18,7 +18,7 @@
  *   (`cwd`, `env`, `platform`, `command`, `compile`)
  * - `API.Service` — scoped attached service startup (`startService`)
  * - `NativeLauncher` — handing one native agent UI the foreground terminal
- *   (`reserveTerminal`, `flushOutput`, `nativeLaunch`)
+ *   (`reserveTerminal`, `flushOutput`, `notifyTerminal`, `nativeLaunch`)
  * - `Config` — shared execution config (`timeout`, `timeoutExec`, `timeoutFetch`,
  *   `verbose`)
  *
@@ -32,7 +32,7 @@ export { Service, SERVICE_HOSTNAME, SERVICE_READY_PREFIX, ServiceProcessExitBefo
 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";
+export { flushOutput, installControlledLauncher, installForegroundLauncher, NATIVE_LAUNCHER_UNAVAILABLE, NativeLauncher, NativeLauncherUnavailableError, nativeLaunch, NO_TERMINAL, notifyTerminal, reserveTerminal, } from "./launcher.js";
 export { hostFilesHandler, useHostFiles } from "./host-files.js";
 export { AgentSessionBusy, agentSessionKeyDigest, AgentSessionRecoveryRequired, parseAgentSessionOwnership, serializeAgentSessionOwnership, } from "./agent-session-coordinator.js";
 export { createDenoAgentSessionCoordinator, hasDenoAgentSessionCoordinator, } from "./deno-agent-session-coordinator.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@executablemd/runtime",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "description": "Runtime host APIs for executable.md documents.",
   "homepage": "https://executable.md",
   "repository": {
@@ -20,6 +20,12 @@
         "default": "./esm/mod.js"
       }
     },
+    "./api": {
+      "import": {
+        "types": "./types/api.d.ts",
+        "default": "./esm/api.js"
+      }
+    },
     "./files": {
       "import": {
         "types": "./types/files.d.ts",

package/types/api.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @module
+ *
+ * The consumer API of `@executablemd/runtime`: the shared execution
+ * configuration a Plugin, a component package or a host reads.
+ *
+ * `Config` is the same Api the engine and the CLI already install and read;
+ * this entrypoint is where a consumer imports it from, so a package depending
+ * on runtime reaches its configuration without importing the whole host
+ * surface. The root export keeps every one of these names.
+ *
+ * ```ts
+ * import { verbose } from "@executablemd/runtime/api";
+ *
+ * if (yield* verbose) {
+ *   // render the detail a quiet run leaves out
+ * }
+ * ```
+ */
+import "./_dnt.polyfills.js";
+export { Config, timeout, timeoutExec, timeoutFetch, verbose } from "./config.js";
+export type { ConfigApi } from "./config.js";
+export { asDuration, durationError, parseDuration } from "./duration.js";

package/types/config.d.ts

@@ -26,7 +26,7 @@
  * `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
+ * is. It bounds nothing, opens nothing and decides no permission: 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.

package/types/files.d.ts

@@ -20,7 +20,7 @@
  *
  * `checkFilePath` is the one exception, and it is deliberately weak: pure path
  * arithmetic, no filesystem access, and nothing usable comes back — no path, no
- * handle, no authority token. `<File>`'s write form calls it to decide whether
+ * handle, no capability token. `<File>`'s write form calls it to decide whether
  * its children may expand at all, and the later `writeTextFile` repeats the
  * same admission from the same authored path. A check that was skipped,
  * replaced, or answered by another provider therefore authorizes nothing.
@@ -172,10 +172,14 @@ export type FilesDeniableOperation = "temporary-directory";
 /**
  * Which contract a provider broke.
  *
- * `authority` — the identity authorizing access is stale, foreign, or gone.
+ * `authority` — the identity permitting access is stale, foreign, or gone.
  * `savepoint` — a nested transaction could not be rolled back or released.
  * `protocol` — a handler threw, or returned data no consumer can trust.
  * `teardown` — cleanup failed while the scope was already unwinding.
+ *
+ * `authority` keeps that spelling because it is a serialized value: it crosses
+ * loaded copies and reaches parsers that match it byte for byte, so renaming it
+ * would break categorization rather than describe it better.
  */
 export type FilesInvariantCategory = "authority" | "savepoint" | "protocol" | "teardown";
 /**

package/types/launcher.d.ts

@@ -56,6 +56,21 @@ export interface NativeLauncherHandler {
     reserve(): Operation<void>;
     flush(): Operation<void>;
     launch(request: NativeLaunchRequest): Operation<NativeLaunchOutcome>;
+    /**
+     * Show the person one line about the launch itself, on the terminal this
+     * launch reserved.
+     *
+     * Not document output. What a launch has to say — that a turn is about to be
+     * spent in their name, what it answered, what it cost — is addressed to
+     * whoever is sitting there, and it belongs on the screen the native UI is
+     * about to open on rather than in the document's captured text, where a
+     * `<File>` would keep it and a replay would print it again.
+     *
+     * It goes through the launcher for the same reason `flush` does: this is the
+     * only thing that knows which terminal a given launch owns, so the root's
+     * launch writes to the root terminal.
+     */
+    notify(text: string): Operation<void>;
 }
 export declare const NATIVE_LAUNCHER_UNAVAILABLE: string;
 export declare class NativeLauncherUnavailableError extends Error {
@@ -67,6 +82,8 @@ export declare const NativeLauncher: Api<NativeLauncherHandler>;
 export declare function reserveTerminal(): Operation<void>;
 /** Give the reader everything the document has produced so far. */
 export declare function flushOutput(): Operation<void>;
+/** Say one thing to whoever is at the terminal this launch reserved. */
+export declare function notifyTerminal(text: string): Operation<void>;
 /** Run one native UI as a foreground child and report how it ended. */
 export declare function nativeLaunch(request: NativeLaunchRequest): Operation<NativeLaunchOutcome>;
 export declare const NO_TERMINAL: string;
@@ -119,6 +136,8 @@ export interface ControlledLauncherOptions {
     wait?: (request: NativeLaunchRequest) => Operation<void>;
     onReserve?: () => void;
     onFlush?: () => void;
+    /** Each line the launch addressed to the terminal, in the order it said them. */
+    onNotify?: (text: string) => void;
 }
 export declare function installControlledLauncher(options?: ControlledLauncherOptions): Operation<void>;
 export {};

package/types/mod.d.ts

@@ -18,7 +18,7 @@
  *   (`cwd`, `env`, `platform`, `command`, `compile`)
  * - `API.Service` — scoped attached service startup (`startService`)
  * - `NativeLauncher` — handing one native agent UI the foreground terminal
- *   (`reserveTerminal`, `flushOutput`, `nativeLaunch`)
+ *   (`reserveTerminal`, `flushOutput`, `notifyTerminal`, `nativeLaunch`)
  * - `Config` — shared execution config (`timeout`, `timeoutExec`, `timeoutFetch`,
  *   `verbose`)
  *
@@ -37,7 +37,7 @@ 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 { flushOutput, installControlledLauncher, installForegroundLauncher, NATIVE_LAUNCHER_UNAVAILABLE, NativeLauncher, NativeLauncherUnavailableError, nativeLaunch, NO_TERMINAL, reserveTerminal, } from "./launcher.js";
+export { flushOutput, installControlledLauncher, installForegroundLauncher, NATIVE_LAUNCHER_UNAVAILABLE, NativeLauncher, NativeLauncherUnavailableError, nativeLaunch, NO_TERMINAL, notifyTerminal, reserveTerminal, } from "./launcher.js";
 export type { ControlledLauncherOptions, NativeLauncherHandler, NativeLaunchOutcome, NativeLaunchRequest, } from "./launcher.js";
 export { hostFilesHandler, useHostFiles } from "./host-files.js";
 export type { HostFilesEvent, HostFilesObserver, HostFilesOptions } from "./host-files.js";