@executablemd/cli 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Taras Mankovski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/esm/cli.js

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+/**
+ * CLI — run an executable markdown document.
+ *
+ * Usage:
+ *   xmd run <document.md> [options]
+ *   xmd <document.md> [options]        (run is the default command)
+ *
+ * Examples:
+ *   xmd run core/examples/hello-world.md
+ *   xmd core/examples/hello-world.md --verbose
+ *   xmd run core/examples/hello-world.md --journal events.jsonl
+ */
+import { main, exit, spawn, each, createSignal, until } from "effection";
+import { InMemoryStream, } from "@executablemd/durable-streams";
+import { forEach } from "@effectionx/stream-helpers";
+import { open } from "node:fs/promises";
+import { inspect } from "node:util";
+import process from "node:process";
+import { program, object, field, cli, commands } from "configliere";
+import { z } from "zod";
+import { runDocument, useNormalizedOutput, useTerminalOutput } from "@executablemd/core";
+import { FileStream } from "./file-stream.js";
+// ---------------------------------------------------------------------------
+// Workaround: field.default exists at runtime but is missing from the .d.ts
+// ---------------------------------------------------------------------------
+const defaults = (value) => (mods) => ({ ...mods, default: value });
+// ---------------------------------------------------------------------------
+// Program schema
+// ---------------------------------------------------------------------------
+const runConfig = object({
+    docPath: {
+        description: "markdown document to execute",
+        ...field(z.string(), cli.argument()),
+    },
+    componentDir: {
+        description: "component search directory",
+        ...field(z.array(z.string()), defaults(["components", "."]), field.array()),
+    },
+    verbose: {
+        description: "log journal entries to stderr",
+        aliases: ["-V"],
+        ...field(z.boolean(), defaults(false)),
+    },
+    journal: {
+        description: "write a diagnostic JSONL trace (path must not exist)",
+        aliases: ["-j"],
+        ...field(z.string().optional()),
+    },
+    raw: {
+        description: "output raw markdown without normalization or terminal formatting",
+        ...field(z.boolean(), defaults(false)),
+    },
+});
+const xmd = program({
+    name: "xmd",
+    version: "0.2.0",
+    config: commands({ run: runConfig }, { default: "run" }),
+});
+// ---------------------------------------------------------------------------
+// Journal entry formatting
+// ---------------------------------------------------------------------------
+const pretty = (value) => inspect(value, {
+    colors: true,
+    compact: true,
+    breakLength: Infinity,
+    depth: 2,
+    maxStringLength: 200,
+});
+function formatYieldResult(event) {
+    const { result, description } = event;
+    if (result.status !== "ok" || result.value === undefined)
+        return "";
+    const v = result.value;
+    switch (description.type) {
+        case "import_component":
+            return " " + pretty({ path: v.path });
+        case "eval":
+            return " " + pretty(v.value ?? {});
+        case "exec":
+            return " " + pretty({ exitCode: v.exitCode, stdout: v.stdout, stderr: v.stderr });
+        default:
+            return " " + pretty(v);
+    }
+}
+function summarizeEvent(event) {
+    if (event.type === "yield") {
+        const desc = event.description;
+        const status = event.result.status;
+        const detail = status === "err" && "error" in event.result
+            ? ` (${event.result.error.message})`
+            : formatYieldResult(event);
+        return `[yield] ${desc.type}:${desc.name} → ${status}${detail}`;
+    }
+    const status = event.result.status;
+    const detail = status === "err" && "error" in event.result ? ` (${event.result.error.message})` : "";
+    return `[close] ${event.coroutineId} → ${status}${detail}`;
+}
+// ---------------------------------------------------------------------------
+// Document runner
+// ---------------------------------------------------------------------------
+function* createJournalFile(filePath) {
+    let handle;
+    try {
+        handle = yield* until(open(filePath, "wx"));
+    }
+    catch (error) {
+        const isExistingFile = error instanceof Error &&
+            (("code" in error && error.code === "EEXIST") || error.message.startsWith("EEXIST:"));
+        if (isExistingFile) {
+            throw new Error(`Journal trace already exists: ${filePath}. Remove it or choose another path.`, { cause: error });
+        }
+        throw error;
+    }
+    yield* until(handle.close());
+}
+function* run(config) {
+    const { docPath, componentDir, verbose, journal, raw } = config;
+    // Every CLI invocation starts from an empty stream. --journal writes
+    // current-run diagnostics only; existing traces are never loaded.
+    let stream;
+    if (journal) {
+        yield* createJournalFile(journal);
+        stream = new FileStream(journal);
+    }
+    else {
+        stream = new InMemoryStream();
+    }
+    // Wire --verbose observability via Signal.
+    // FileStream.onAppend fires after each persist; the signal fans out
+    // to the stderr writer below. Persistence is handled by FileStream
+    // itself — the signal is purely for observability.
+    const signal = verbose ? createSignal() : undefined;
+    if (signal && stream instanceof FileStream) {
+        stream.onAppend = (event) => signal.send(event);
+    }
+    else if (signal && stream instanceof InMemoryStream) {
+        stream.onAppend = (event) => signal.send(event);
+    }
+    // Spawn verbose stderr writer
+    const writer = signal
+        ? yield* spawn(function* () {
+            for (const event of yield* each(signal)) {
+                console.error(summarizeEvent(event));
+                yield* each.next();
+            }
+        })
+        : spawn(function* () { });
+    // ---------------------------------------------------------------------------
+    // Output middleware (spec §9).
+    //
+    // Middleware is installed on the DocumentOutput Api via Api.around() before
+    // runDocument is called. runDocument owns the channel internally —
+    // the CLI just installs transformations and consumes the returned stream.
+    // ---------------------------------------------------------------------------
+    if (!raw) {
+        yield* useNormalizedOutput();
+    }
+    if (process.stdout.isTTY && !raw) {
+        yield* useTerminalOutput();
+    }
+    // Run the document — returns a DocumentExecution.
+    // yield* execution waits for completion. execution.output streams chunks.
+    const execution = yield* runDocument({
+        docPath,
+        stream,
+        componentDirs: componentDir,
+    });
+    // Consume the output stream with forEach.
+    // Interactive TTY: write each chunk as it arrives.
+    // Piped: collect and write the full output at the end.
+    const fullOutput = yield* forEach(function* (chunk) {
+        if (process.stdout.isTTY) {
+            process.stdout.write(chunk);
+        }
+    }, execution.output);
+    // When piped (not TTY), write the full output at the end.
+    if (!process.stdout.isTTY) {
+        process.stdout.write(fullOutput);
+    }
+    // Close the signal so the writer drains remaining events and exits.
+    if (signal) {
+        signal.close();
+        yield* writer;
+    }
+}
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+await main(function* (args) {
+    const parser = xmd.createParser({ args });
+    switch (parser.type) {
+        case "help":
+            console.log(parser.print());
+            yield* exit(0);
+            break;
+        case "version":
+            console.log(parser.print());
+            yield* exit(0);
+            break;
+        case "main": {
+            const parsed = parser.parse();
+            if (!parsed.ok) {
+                console.error(parsed.error.message);
+                yield* exit(1);
+                break;
+            }
+            switch (parsed.value.name) {
+                case "run":
+                    yield* run(parsed.value.config);
+                    break;
+            }
+        }
+    }
+});

package/esm/file-stream.js

@@ -0,0 +1,24 @@
+import { until } from "effection";
+import { appendFile } from "node:fs/promises";
+function cloneEvent(event) {
+    return structuredClone(event);
+}
+export class FileStream {
+    events;
+    filePath;
+    onAppend = null;
+    constructor(filePath) {
+        this.filePath = filePath;
+        this.events = [];
+    }
+    // deno-lint-ignore require-yield
+    *readAll() {
+        return this.events.map(cloneEvent);
+    }
+    *append(event) {
+        const cloned = cloneEvent(event);
+        yield* until(appendFile(this.filePath, JSON.stringify(cloned) + "\n"));
+        this.events.push(cloned);
+        this.onAppend?.(cloneEvent(cloned));
+    }
+}

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@executablemd/cli",
+  "version": "0.2.0",
+  "description": "The xmd command-line interface for executable.md.",
+  "homepage": "https://executable.md",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taras/executable.md.git"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/taras/executable.md/issues"
+  },
+  "scripts": {},
+  "bin": {
+    "xmd": "./esm/cli.js"
+  },
+  "dependencies": {
+    "@effectionx/stream-helpers": "0.8.3",
+    "@executablemd/core": "^0.2.0",
+    "@executablemd/durable-streams": "^0.2.0",
+    "configliere": "^0.2.3",
+    "effection": "4.1.0-alpha.7",
+    "zod": "^4.3.6"
+  },
+  "_generatedBy": "dnt@dev"
+}

package/types/cli.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * CLI — run an executable markdown document.
+ *
+ * Usage:
+ *   xmd run <document.md> [options]
+ *   xmd <document.md> [options]        (run is the default command)
+ *
+ * Examples:
+ *   xmd run core/examples/hello-world.md
+ *   xmd core/examples/hello-world.md --verbose
+ *   xmd run core/examples/hello-world.md --journal events.jsonl
+ */
+export {};

package/types/file-stream.d.ts

@@ -0,0 +1,10 @@
+import type { Operation } from "effection";
+import type { DurableStream, DurableEvent } from "@executablemd/durable-streams";
+export declare class FileStream implements DurableStream {
+    private events;
+    private filePath;
+    onAppend: ((event: DurableEvent) => void) | null;
+    constructor(filePath: string);
+    readAll(): Operation<DurableEvent[]>;
+    append(event: DurableEvent): Operation<void>;
+}