@workflow-manager/runner 0.1.0 → 0.3.0

package/dist/manPage.js

@@ -0,0 +1,147 @@
+export const MAN_PAGE_SOURCE = `.TH WFM 1 "April 2026" "@workflow-manager/runner" "User Commands"
+.SH NAME
+wfm \\- run markdown or json workflows from the CLI
+.SH SYNOPSIS
+.B wfm
+.I command
+[options]
+.SH DESCRIPTION
+wfm parses a workflow definition file, validates it, and executes
+it with deterministic in-memory orchestration.
+
+Workflow files can be Markdown with YAML frontmatter or JSON.
+.SH COMMANDS
+.TP
+.B doctor [workflow.md|workflow.json] [--json]
+Inspect host adapter setup, LLM access keys, and current adapter implementation status. When a workflow path is provided, also validate schema and runtime requirements without executing steps.
+.TP
+.B agent [path] [--force]
+Create WFM-focused agent rules. The default path is ./AGENTS.md. Existing files are not overwritten unless --force is passed.
+.TP
+.B scaffold [path] [--format markdown|json]
+Create a starter workflow file. Format defaults to markdown unless the output
+path ends in .json.
+.TP
+.B validate <workflow.md|workflow.json>
+Validate workflow structure and report schema errors.
+.TP
+.B run <workflow.md|workflow.json> [--input input.json] [--objective text] [--confirm list] [--auto-confirm-all] [--port number] [--verbose] [--json]
+Run the workflow with live CLI progress and optional JSON output.
+.TP
+.B approve [--url value] [--token value] [--run-id value] [--step value] [--actor value] [--note text]
+Approve the current waiting runner step through the local attach API.
+.TP
+.B resume [--url value] [--token value] [--run-id value] [--step value] [--actor value] [--note text]
+Alias for approve, intended for external resume flows.
+.TP
+.B cancel [--url value] [--token value] [--run-id value] [--step value] [--actor value] [--note text]
+Cancel the current waiting runner step through the local attach API.
+.TP
+.B auth <login|whoami|logout> [--token value]
+Manage remote registry authentication for CLI publish and pull flows.
+.TP
+.B publish <workflow.md|workflow.json> [--slug slug] [--title text] [--description text] [--visibility public|private] [--version label] [--tag a,b] [--draft]
+Publish a validated local workflow to the remote registry.
+.TP
+.B pull <owner/slug> [--version label] [--output path]
+Download a remote workflow and write it to a local file.
+.TP
+.B search [query]
+Search public workflows from the remote registry.
+.TP
+.B remote info <owner/slug>
+Show metadata and source information for a remote workflow.
+.TP
+.B man
+Open this man page.
+.SH RUN OPTIONS
+.TP
+.B --input <path>
+JSON file merged into global workflow input state.
+.TP
+.B --objective <text>
+Override the default run objective.
+.TP
+.B --confirm <stepA,stepB:human,...>
+Provide explicit confirmations for steps that require validation.
+.TP
+.B --auto-confirm-all
+Bypass confirmation gating for all steps.
+.TP
+.B --port <number>
+Bind the local attach API to a specific port. If omitted, the OS assigns a free port on 127.0.0.1.
+.TP
+.B --verbose
+Stream per-step agent output and execution updates to stderr while the workflow runs.
+.TP
+.B --json
+Print the final run result as JSON on stdout while keeping live progress on stderr.
+.TP
+Human approval steps in an interactive terminal show an inline review prompt so they can be approved or cancelled without a separate HTTP client.
+.TP
+.B --url <value>
+Runner attach API base URL for approve, resume, or cancel commands.
+.TP
+.B --token <value>
+Runner attach API bearer token for approve, resume, or cancel commands.
+.TP
+.B --run-id <value>
+Runner id to control. If omitted, the CLI reads it from /session.
+.TP
+.B --step <value>
+Optional step key when controlling a specific waiting step.
+.TP
+.B --actor <value>
+Actor name recorded in approval audit events.
+.TP
+.B --note <text>
+Optional approval or cancellation note recorded in the event payload.
+.SH EXAMPLES
+.TP
+Validate markdown workflow:
+.B wfm validate ./example-workflow.md
+.TP
+Validate json workflow:
+.B wfm validate ./example-workflow.json
+.TP
+Scaffold json workflow file:
+.B wfm scaffold ./new-workflow.json --format json
+.TP
+Authenticate with a CLI token:
+.B wfm auth login --token wm_exampletoken
+.TP
+Publish a workflow:
+.B wfm publish ./example-workflow.json --visibility public --tag example,automation
+.TP
+Pull a remote workflow:
+.B wfm pull alice/remote-bunny --output ./remote-bunny.json
+.TP
+Search the remote registry:
+.B wfm search bunny
+.TP
+Run with explicit confirmations:
+.B wfm run ./example-workflow.json --confirm discover:human,qa_gate:human
+.TP
+Inspect host setup:
+.B wfm doctor
+.TP
+Check a workflow before running it:
+.B wfm doctor ./example-workflow.json
+.TP
+Create agent rules:
+.B wfm agent ./AGENTS.md
+.SH FILES
+.TP
+.B man/wfm.1
+The manual page source shipped with this repository.
+.SH EXIT STATUS
+.TP
+.B 0
+Successful command execution.
+.TP
+.B 1
+Validation or runtime error.
+.TP
+.B 2
+Run completed in non-success terminal status.
+`;

package/dist/mockExecutor.d.ts

@@ -1,2 +1,2 @@
-import type { InputEnvelope, OutputEnvelope, StepDefinition } from "./types.js";
-export declare function executeMockStep(step: StepDefinition, input: InputEnvelope, attempt: number): OutputEnvelope;
+import type { InputEnvelope, OutputEnvelope, StepDefinition, StepExecutionHooks } from "./types.js";
+export declare function executeMockStep(step: StepDefinition, input: InputEnvelope, attempt: number, hooks?: StepExecutionHooks): Promise<OutputEnvelope>;

package/dist/mockExecutor.js

@@ -6,11 +6,39 @@ function chapterOutputs(previousOutput) {
         .map((entry) => asRecord(entry))
         .filter((entry) => typeof entry.chapterMarkdown === "string");
 }
-export function executeMockStep(step, input, attempt) {
+function asStringList(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.map((entry) => String(entry));
+}
+async function emitStreamChunks(hooks, stream, chunks, delayMs) {
+    if (chunks.length === 0) {
+        return;
+    }
+    const emit = stream === "stdout" ? hooks?.onStdout : hooks?.onStderr;
+    for (const chunk of chunks) {
+        emit?.(chunk);
+        if (delayMs > 0) {
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+        }
+    }
+}
+export async function executeMockStep(step, input, attempt, hooks) {
     const start = Date.now();
     const payload = asRecord(step.taskSpec?.payload);
+    const delayMs = Number(payload.delayMs ?? 0);
+    const chunkDelayMs = Number(payload.chunkDelayMs ?? 0);
     const mockResult = String(payload.mockResult ?? "success").toLowerCase();
     const feedback = String(payload.feedback ?? "");
+    const stdoutChunks = asStringList(payload.stdoutChunks);
+    const stderrChunks = asStringList(payload.stderrChunks);
+    hooks?.onStarted?.({ adapter: input.priming_configuration.adapter ?? "mock" });
+    await emitStreamChunks(hooks, "stdout", stdoutChunks, Number.isFinite(chunkDelayMs) ? Math.max(0, Math.floor(chunkDelayMs)) : 0);
+    await emitStreamChunks(hooks, "stderr", stderrChunks, Number.isFinite(chunkDelayMs) ? Math.max(0, Math.floor(chunkDelayMs)) : 0);
+    if (Number.isFinite(delayMs) && delayMs > 0) {
+        await new Promise((resolve) => setTimeout(resolve, Math.floor(delayMs)));
+    }
     const make = (status, action, extraPayload = {}, feedbackReason = feedback) => ({
         step_id: step.key,
         execution_status: status,
@@ -38,7 +66,9 @@ export function executeMockStep(step, input, attempt) {
     });
     if (step.kind === "approval") {
         const autoApprove = step.approvalSpec?.autoApprove ?? false;
-        return autoApprove ? make("SUCCESS", "PROCEED") : make("YIELD_EXTERNAL", "PROCEED");
+        const result = autoApprove ? make("SUCCESS", "PROCEED") : make("YIELD_EXTERNAL", "PROCEED");
+        hooks?.onFinished?.({ executionStatus: result.execution_status });
+        return result;
     }
     if (typeof payload.storyChapter === "number") {
         const chapterNumber = payload.storyChapter;
@@ -46,13 +76,15 @@ export function executeMockStep(step, input, attempt) {
         const paragraph = chapterNumber === 1
             ? `A curious bunny set out at sunrise to solve the puzzle in ${prompt}.`
             : `By sunset, the bunny used what it learned to finish ${prompt} with courage and kindness.`;
-        return make("SUCCESS", "PROCEED", {
+        const result = make("SUCCESS", "PROCEED", {
             chapterNumber,
             chapterTitle: `Chapter ${chapterNumber}`,
             paragraph,
             chapterMarkdown: `## Chapter ${chapterNumber}\n\n${paragraph}`,
             storyPrompt: prompt,
         });
+        hooks?.onFinished?.({ executionStatus: result.execution_status });
+        return result;
     }
     if (payload.validateStory === true) {
         const expectedChapters = Number(payload.requiredChapters ?? 2);
@@ -64,19 +96,23 @@ export function executeMockStep(step, input, attempt) {
         const hasBunnyTheme = /bunny/i.test(chapters);
         const isValid = chapterMatches.length === expectedChapters && hasBunnyTheme;
         if (!isValid) {
-            return make("QA_REJECTED", "RETRY_CURRENT", {
+            const result = make("QA_REJECTED", "RETRY_CURRENT", {
                 expectedChapters,
                 foundChapters: chapterMatches.length,
                 hasBunnyTheme,
                 validationPassed: false,
             }, `Story must include exactly ${expectedChapters} chapters and bunny-themed content`);
+            hooks?.onFinished?.({ executionStatus: result.execution_status });
+            return result;
         }
-        return make("SUCCESS", "PROCEED", {
+        const result = make("SUCCESS", "PROCEED", {
             expectedChapters,
             foundChapters: chapterMatches.length,
             hasBunnyTheme,
             validationPassed: true,
         });
+        hooks?.onFinished?.({ executionStatus: result.execution_status });
+        return result;
     }
     if (payload.renderStoryMarkdown === true) {
         const previousOutput = asRecord(input.step_context.previous_output);
@@ -84,27 +120,40 @@ export function executeMockStep(step, input, attempt) {
             .sort((a, b) => Number(a.chapterNumber ?? 0) - Number(b.chapterNumber ?? 0))
             .map((entry) => String(entry.chapterMarkdown));
         if (chapters.length === 0) {
-            return make("QA_REJECTED", "RETRY_CURRENT", { chapterCount: 0 }, "No chapters available to render");
+            const result = make("QA_REJECTED", "RETRY_CURRENT", { chapterCount: 0 }, "No chapters available to render");
+            hooks?.onFinished?.({ executionStatus: result.execution_status });
+            return result;
         }
         const title = String(payload.storyTitle ?? input.global_context.global_state.storyRequest ?? "Bunny Story");
         const storyMarkdown = `# ${title}\n\n${chapters.join("\n\n")}`;
-        return make("SUCCESS", "PROCEED", {
+        const result = make("SUCCESS", "PROCEED", {
             chapterCount: chapters.length,
             storyMarkdown,
         });
+        hooks?.onFinished?.({ executionStatus: result.execution_status });
+        return result;
     }
+    let result;
     switch (mockResult) {
         case "retry":
-            return make("QA_REJECTED", "RETRY_CURRENT");
+            result = make("QA_REJECTED", "RETRY_CURRENT");
+            break;
         case "rollback":
-            return make("QA_REJECTED", "ROLLBACK_PREVIOUS");
+            result = make("QA_REJECTED", "ROLLBACK_PREVIOUS");
+            break;
         case "restart":
-            return make("QA_REJECTED", "RESTART_ALL");
+            result = make("QA_REJECTED", "RESTART_ALL");
+            break;
         case "yield":
-            return make("YIELD_EXTERNAL", "PROCEED");
+            result = make("YIELD_EXTERNAL", "PROCEED");
+            break;
         case "fail":
-            return make("FAILED", "PROCEED");
+            result = make("FAILED", "PROCEED");
+            break;
         default:
-            return make("SUCCESS", "PROCEED");
+            result = make("SUCCESS", "PROCEED");
+            break;
     }
+    hooks?.onFinished?.({ executionStatus: result.execution_status });
+    return result;
 }

package/dist/opencodeExecutor.d.ts

@@ -1,3 +1,3 @@
-import type { InputEnvelope, OutputEnvelope, StepDefinition } from "./types.js";
+import type { InputEnvelope, OutputEnvelope, StepDefinition, StepExecutionHooks } from "./types.js";
 export declare function shouldUseRealOpencode(step: StepDefinition): boolean;
-export declare function executeOpencodeStep(step: StepDefinition, input: InputEnvelope, attempt: number): OutputEnvelope;
+export declare function executeOpencodeStep(step: StepDefinition, input: InputEnvelope, attempt: number, hooks?: StepExecutionHooks): Promise<OutputEnvelope>;

package/dist/opencodeExecutor.js

@@ -1,4 +1,4 @@
-import { spawnSync } from "node:child_process";
+import { spawn } from "node:child_process";
 function asRecord(value) {
     return value && typeof value === "object" ? value : {};
 }
@@ -13,145 +13,19 @@ export function shouldUseRealOpencode(step) {
     const payload = asRecord(step.taskSpec?.payload);
     return payload.useRealAdapter === true && payload.opencodeSmokeTest === true;
 }
-export function executeOpencodeStep(step, input, attempt) {
+export function executeOpencodeStep(step, input, attempt, hooks) {
     const startedAt = Date.now();
     const payload = asRecord(step.taskSpec?.payload);
     const opencodeArgs = Array.isArray(payload.opencodeArgs)
         ? payload.opencodeArgs.map((arg) => String(arg))
         : ["--version"];
     const timeoutMs = normalizeTimeout(payload.timeoutMs, 15000);
-    let child;
-    try {
-        child = spawnSync("opencode", opencodeArgs, {
-            encoding: "utf-8",
-            timeout: timeoutMs,
-        });
-    }
-    catch (err) {
-        return {
-            step_id: step.key,
-            execution_status: "FAILED",
-            qa_routing: {
-                action: "PROCEED",
-                feedback_reason: err.message,
-            },
-            mutated_payload: {
-                stepKey: step.key,
-                attempt,
-                adapter: input.priming_configuration.adapter ?? "opencode",
-                realOpencode: true,
-                command: "opencode",
-                args: opencodeArgs,
-                timeoutMs,
-            },
-            metadata: {
-                execution_time_ms: Date.now() - startedAt,
-                external_intervention_required: false,
-            },
-        };
-    }
-    const stdout = child.stdout ?? "";
-    const stderr = child.stderr ?? "";
-    const status = typeof child.status === "number" ? child.status : 1;
-    const output = `${stdout}\n${stderr}`;
-    const expectContains = payload.expectContains ? String(payload.expectContains) : undefined;
-    const expectPattern = payload.expectPattern ? String(payload.expectPattern) : undefined;
-    const containsExpected = expectContains
-        ? output.toLowerCase().includes(expectContains.toLowerCase())
-        : true;
-    let matchesPattern = true;
-    if (expectPattern) {
-        try {
-            matchesPattern = new RegExp(expectPattern).test(output);
-        }
-        catch (err) {
-            return {
-                step_id: step.key,
-                execution_status: "FAILED",
-                qa_routing: {
-                    action: "PROCEED",
-                    feedback_reason: `Invalid expectPattern regex: ${err.message}`,
-                },
-                mutated_payload: {
-                    stepKey: step.key,
-                    attempt,
-                    adapter: input.priming_configuration.adapter ?? "opencode",
-                    realOpencode: true,
-                    command: "opencode",
-                    args: opencodeArgs,
-                    exitStatus: status,
-                    stdout,
-                    stderr,
-                    expectPattern,
-                },
-                metadata: {
-                    execution_time_ms: Date.now() - startedAt,
-                    external_intervention_required: false,
-                },
-            };
-        }
-    }
-    if (child.error || status !== 0) {
-        return {
-            step_id: step.key,
-            execution_status: "FAILED",
-            qa_routing: {
-                action: "PROCEED",
-                feedback_reason: child.error?.message ?? `opencode exited with status ${status}`,
-            },
-            mutated_payload: {
-                stepKey: step.key,
-                attempt,
-                adapter: input.priming_configuration.adapter ?? "opencode",
-                realOpencode: true,
-                command: "opencode",
-                args: opencodeArgs,
-                exitStatus: status,
-                stdout,
-                stderr,
-            },
-            metadata: {
-                execution_time_ms: Date.now() - startedAt,
-                external_intervention_required: false,
-            },
-        };
-    }
-    if (!containsExpected || !matchesPattern) {
-        const feedback = !containsExpected
-            ? `Output did not contain expected token: ${expectContains}`
-            : `Output did not match expected pattern: ${expectPattern}`;
-        return {
-            step_id: step.key,
-            execution_status: "QA_REJECTED",
-            qa_routing: {
-                action: "RETRY_CURRENT",
-                feedback_reason: feedback,
-            },
-            mutated_payload: {
-                stepKey: step.key,
-                attempt,
-                adapter: input.priming_configuration.adapter ?? "opencode",
-                realOpencode: true,
-                command: "opencode",
-                args: opencodeArgs,
-                exitStatus: status,
-                stdout,
-                stderr,
-                containsExpected,
-                matchesPattern,
-            },
-            metadata: {
-                execution_time_ms: Date.now() - startedAt,
-                external_intervention_required: false,
-            },
-        };
-    }
-    return {
+    const makeResult = (status, feedbackReason, extra = {}, action = "PROCEED") => ({
         step_id: step.key,
-        execution_status: "SUCCESS",
+        execution_status: status,
         qa_routing: {
-            action: "PROCEED",
-            feedback_reason: "",
+            action,
+            feedback_reason: feedbackReason,
         },
         mutated_payload: {
             stepKey: step.key,
@@ -160,15 +34,104 @@ export function executeOpencodeStep(step, input, attempt) {
             realOpencode: true,
             command: "opencode",
             args: opencodeArgs,
-            exitStatus: status,
-            stdout,
-            stderr,
-            containsExpected,
-            matchesPattern,
+            ...extra,
         },
         metadata: {
             execution_time_ms: Date.now() - startedAt,
             external_intervention_required: false,
         },
-    };
+    });
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = spawn("opencode", opencodeArgs, {
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+        }
+        catch (err) {
+            const result = makeResult("FAILED", err.message, { timeoutMs });
+            hooks?.onFinished?.({ executionStatus: result.execution_status });
+            resolve(result);
+            return;
+        }
+        hooks?.onStarted?.({ command: "opencode", args: opencodeArgs, timeoutMs });
+        const outChunks = [];
+        const errChunks = [];
+        child.stdout?.setEncoding("utf-8");
+        child.stderr?.setEncoding("utf-8");
+        child.stdout?.on("data", (chunk) => {
+            outChunks.push(chunk);
+            hooks?.onStdout?.(chunk);
+        });
+        child.stderr?.on("data", (chunk) => {
+            errChunks.push(chunk);
+            hooks?.onStderr?.(chunk);
+        });
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGTERM");
+            const stdout = outChunks.join("");
+            const stderr = errChunks.join("");
+            const result = makeResult("FAILED", `timed out after ${timeoutMs}ms`, { timeoutMs, stdout, stderr });
+            hooks?.onFinished?.({ executionStatus: result.execution_status, exitStatus: null, timedOut: true });
+            resolve(result);
+        }, timeoutMs);
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            if (timedOut) {
+                return;
+            }
+            const stdout = outChunks.join("");
+            const stderr = errChunks.join("");
+            const result = makeResult("FAILED", err.message, { timeoutMs, stdout, stderr });
+            hooks?.onFinished?.({ executionStatus: result.execution_status });
+            resolve(result);
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            if (timedOut) {
+                return;
+            }
+            const stdout = outChunks.join("");
+            const stderr = errChunks.join("");
+            const exitStatus = code ?? 1;
+            const output = `${stdout}\n${stderr}`;
+            const expectContains = payload.expectContains ? String(payload.expectContains) : undefined;
+            const expectPattern = payload.expectPattern ? String(payload.expectPattern) : undefined;
+            const containsExpected = expectContains
+                ? output.toLowerCase().includes(expectContains.toLowerCase())
+                : true;
+            let matchesPattern = true;
+            if (expectPattern) {
+                try {
+                    matchesPattern = new RegExp(expectPattern).test(output);
+                }
+                catch (err) {
+                    const result = makeResult("FAILED", `Invalid expectPattern regex: ${err.message}`, { exitStatus, stdout, stderr, expectPattern });
+                    hooks?.onFinished?.({ executionStatus: result.execution_status, exitStatus });
+                    resolve(result);
+                    return;
+                }
+            }
+            if (exitStatus !== 0) {
+                const result = makeResult("FAILED", `opencode exited with status ${exitStatus}`, { exitStatus, stdout, stderr });
+                hooks?.onFinished?.({ executionStatus: result.execution_status, exitStatus });
+                resolve(result);
+                return;
+            }
+            if (!containsExpected || !matchesPattern) {
+                const feedback = !containsExpected
+                    ? `Output did not contain expected token: ${expectContains}`
+                    : `Output did not match expected pattern: ${expectPattern}`;
+                const result = makeResult("QA_REJECTED", feedback, { exitStatus, stdout, stderr, containsExpected, matchesPattern }, "RETRY_CURRENT");
+                hooks?.onFinished?.({ executionStatus: result.execution_status, exitStatus });
+                resolve(result);
+                return;
+            }
+            const result = makeResult("SUCCESS", "", { exitStatus, stdout, stderr, containsExpected, matchesPattern });
+            hooks?.onFinished?.({ executionStatus: result.execution_status, exitStatus });
+            resolve(result);
+        });
+    });
 }