@executablemd/runtime 0.11.0 → 0.12.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

@@ -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 " +
@@ -51,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() {
@@ -60,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);
@@ -117,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" });
 }
 /**
@@ -141,8 +156,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 +166,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 +211,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 +233,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 +254,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(() => {
@@ -311,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.11.0",
+  "version": "0.12.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",
@@ -38,9 +44,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/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

@@ -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.
  *
@@ -55,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 {
@@ -66,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;
@@ -86,6 +104,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.
@@ -100,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";