@workflow-manager/runner 0.1.0

package/README.md

@@ -0,0 +1,196 @@
+# workflow-manager
+
+CLI runner for in-memory and Markdown/JSON workflow orchestration.
+
+## What it does
+
+- Parses workflow definitions from Markdown frontmatter or JSON
+- Validates structure, dependencies, adapters, and validation modes
+- Executes workflow steps with deterministic run state transitions
+- Emits a full event timeline and JSON run result
+- Records authenticated CLI run telemetry for success, failure, and workflow effectiveness
+- Publishes and pulls shared workflows from the remote registry
+
+## Architecture
+
+- `src/index.ts`: CLI commands (`questions`, `scaffold`, `validate`, `run`)
+- `src/parser.ts`: parsing + validation
+- `src/engine.ts`: execution loop, confirmations, retries, rollback/restart
+- `src/mockExecutor.ts`: mock step executor for simulation
+- `src/events.ts`: event sequencing/logging
+- `src/types.ts`: contracts and status enums
+- `apps/remote-registry/`: React + Vite remote registry app
+- `supabase/`: migrations, local stack config, and Edge Functions
+- `doc/`: VitePress documentation site
+- `skills/`: agent skills shipped inside the main npm package for TanStack Intent and compatible loaders
+
+## Quick start
+
+```bash
+bun install
+bun run build
+bun link
+
+wfm scaffold ./example-workflow.md
+wfm validate ./example-workflow.md
+wfm run ./example-workflow.md --auto-confirm-all
+
+# JSON workflow support
+wfm scaffold ./example-workflow.json --format json
+wfm validate ./example-workflow.json
+wfm run ./example-workflow.json --auto-confirm-all
+
+# Remote registry
+wfm auth login --token <token>
+wfm search bunny
+wfm publish ./example-workflow.json --visibility public --tag storytelling,example
+wfm pull alice/remote-bunny --output ./remote-bunny.json
+```
+
+## Build
+
+```bash
+bun run build
+bun test
+```
+
+Build a standalone Bun binary:
+
+```bash
+bun run build:bin
+```
+
+Build all release binaries locally:
+
+```bash
+bun run build:bin:all
+```
+
+## Testing
+
+Run unit tests:
+
+```bash
+bun run test:unit
+```
+
+Run the story workflow e2e tests (JSON and Markdown fixtures):
+
+```bash
+bun run test:e2e
+```
+
+The e2e suite also runs an `opencode` adapter variant for both JSON and Markdown workflows and asserts adapter routing in run events.
+
+Run real OpenCode adapter e2e (requires `opencode` CLI installed):
+
+```bash
+bun run test:e2e:real
+```
+
+The real adapter test is opt-in and triggered by `WORKFLOW_MANAGER_REAL_OPENCODE=1`.
+
+Run full test suite:
+
+```bash
+bun test
+```
+
+Documentation site:
+
+```bash
+bun run docs:dev
+bun run docs:build
+bun run docs:preview
+```
+
+Docs are now treated as a manual Netlify release flow. Build `doc/.vitepress/dist` locally and deploy it manually when needed.
+
+Remote registry app:
+
+```bash
+bun run remote-registry:dev
+bun run remote-registry:build
+```
+
+`workflow-manager-ui` is the Netlify auto-release target. The root `netlify.toml` now builds `apps/remote-registry/` so connected Netlify Git deploys can produce preview deploys for PRs and production deploys from merges to `main`.
+
+Manual help:
+
+```bash
+wfm man
+```
+
+Remote registry commands:
+
+```bash
+wfm auth whoami
+wfm auth logout
+wfm remote info alice/remote-bunny
+```
+
+## Agent skills
+
+The published `@workflow-manager/runner` npm package now ships the CLI runner and the bundled agent skills together.
+
+- bundled skill: `skills/workflow-manager-cli/SKILL.md`
+- discovery keyword: `tanstack-intent`
+- install flow: install `@workflow-manager/runner`, then run `npx @tanstack/intent@latest list` and `npx @tanstack/intent@latest install`
+
+Example usage:
+
+```bash
+npm install @workflow-manager/runner
+npx @tanstack/intent@latest list
+npx @tanstack/intent@latest install
+```
+
+See `skills/README.md` for the packaged skill layout, TanStack Intent integration, and release checks.
+
+The deployed registry dashboard also supports browser-based token creation, workflow publishing, and creator analytics.
+
+Current dashboard capabilities include:
+
+- creator workflow analytics
+- analytics refresh and trend views
+- authenticated CLI run telemetry insights
+- token list and revoke controls
+- browser-based workflow publishing for JSON and Markdown sources
+- workflow metadata and version management
+
+## Contribution
+
+- Keep workflow contracts backward-compatible when possible (`src/types.ts`)
+- Update docs under `doc/` when changing schema or runtime behavior
+- Add or update tests in `tests/` when touching parser or engine logic
+
+Netlify auto-release is configured for the UI in `netlify.toml`:
+
+- base directory: `apps/remote-registry`
+- build command: `bun run build`
+- publish directory: `dist`
+- PRs: Deploy Previews
+- `main`: Production deploys for `workflow-manager-ui`
+
+The docs site is no longer the auto-release target and should be deployed manually.
+
+## Release
+
+- Push a semantic tag like `v0.2.0` to trigger the GitHub Actions release workflow.
+- Publish the root npm package when you want the CLI runner and `skills/` bundle to ship together.
+- The workflow runs tests and build, then compiles binaries for:
+  - macOS arm64: `wfm-macos-arm64`
+  - Linux x64: `wfm-linux-x64`
+  - Windows x64: `wfm-windows-x64.exe`
+- Assets are attached to the GitHub Release for that tag.
+
+## Documentation
+
+VitePress docs are in `doc/` and focus on:
+
+- how the workflow manager works
+- runtime architecture
+- workflow schema
+- practical workflow examples and implementation patterns
+- CLI manual help usage
+- remote registry architecture, agents, and milestones

package/dist/engine.d.ts

@@ -0,0 +1,2 @@
+import type { RunOptions, RunResult, WorkflowDefinition } from "./types.js";
+export declare function runWorkflow(definition: WorkflowDefinition, options?: RunOptions): RunResult;

package/dist/engine.js

@@ -0,0 +1,217 @@
+import { randomUUID } from "node:crypto";
+import { EventLog } from "./events.js";
+import { executeMockStep } from "./mockExecutor.js";
+import { executeOpencodeStep, shouldUseRealOpencode } from "./opencodeExecutor.js";
+function nodeType(step) {
+    if (step.kind === "approval")
+        return "HUMAN";
+    if (step.kind === "system")
+        return "SYSTEM";
+    return "AGENT";
+}
+function stepObjective(step, workflowObjective) {
+    return step.objective ?? `${workflowObjective} :: ${step.key}`;
+}
+function requiresValidation(step) {
+    if (step.approvalSpec?.validation?.required)
+        return step.approvalSpec.validation.mode ?? "human";
+    if (step.validation?.required)
+        return step.validation.mode ?? "human";
+    if (step.kind === "approval")
+        return step.approvalSpec?.validation?.mode ?? "human";
+    return step.validation?.mode ?? "none";
+}
+function canConfirm(step, options, output) {
+    const mode = requiresValidation(step);
+    if (mode === "none" && output.execution_status !== "YIELD_EXTERNAL")
+        return { ok: true };
+    if (options.autoConfirmAll)
+        return { ok: true };
+    const list = new Set(options.confirmations ?? []);
+    const modeToken = `${step.key}:${mode}`;
+    if (list.has(step.key) || list.has(modeToken))
+        return { ok: true };
+    const autoConfirm = step.validation?.autoConfirm ?? step.approvalSpec?.validation?.autoConfirm ?? false;
+    if (autoConfirm)
+        return { ok: true };
+    return { ok: false, reason: `Missing confirmation for ${step.key} (${mode})` };
+}
+function executeStep(step, input, attempt) {
+    const adapterKey = step.taskSpec?.adapterKey ?? "mock";
+    if (adapterKey === "opencode" && shouldUseRealOpencode(step)) {
+        return executeOpencodeStep(step, input, attempt);
+    }
+    return executeMockStep(step, input, attempt);
+}
+export function runWorkflow(definition, options) {
+    const runId = randomUUID();
+    const actor = options?.actor ?? "cli";
+    const primaryObjective = options?.objective ?? definition.title;
+    const workflowObjectives = definition.objectives ?? [];
+    const globalState = { ...(options?.input ?? {}) };
+    const eventLog = new EventLog();
+    let runStatus = "queued";
+    const stepRuns = new Map();
+    for (const step of definition.steps) {
+        stepRuns.set(step.key, {
+            stepKey: step.key,
+            status: "pending",
+            attempt: 0,
+            confirmed: false,
+        });
+    }
+    eventLog.push(runId, "run.created", { workflowKey: definition.key }, undefined, actor);
+    runStatus = "running";
+    eventLog.push(runId, "run.started", { objective: primaryObjective, objectives: workflowObjectives }, undefined, actor);
+    let index = 0;
+    let guard = 0;
+    const maxSteps = Math.max(definition.steps.length * 30, 30);
+    while (index < definition.steps.length) {
+        guard += 1;
+        if (guard > maxSteps) {
+            runStatus = "failed";
+            eventLog.push(runId, "run.failed", { reason: "Execution guard exceeded" });
+            break;
+        }
+        const step = definition.steps[index];
+        const stepRun = stepRuns.get(step.key);
+        if (!stepRun)
+            throw new Error(`Missing step run for ${step.key}`);
+        const dependencies = step.dependsOn ?? [];
+        const depsComplete = dependencies.every((depKey) => stepRuns.get(depKey)?.status === "succeeded");
+        if (!depsComplete) {
+            runStatus = "failed";
+            eventLog.push(runId, "run.failed", { reason: `Dependencies not satisfied for ${step.key}` }, step.key);
+            break;
+        }
+        stepRun.status = "runnable";
+        eventLog.push(runId, "step.runnable", { stepKey: step.key }, step.key);
+        stepRun.status = "running";
+        stepRun.attempt += 1;
+        eventLog.push(runId, "step.claimed", { attempt: stepRun.attempt }, step.key);
+        eventLog.push(runId, "step.execution_started", { attempt: stepRun.attempt }, step.key);
+        const previousOutput = {};
+        for (const dep of dependencies) {
+            previousOutput[dep] = stepRuns.get(dep)?.output ?? null;
+        }
+        const inputEnvelope = {
+            global_context: {
+                workflow_id: runId,
+                primary_objective: primaryObjective,
+                workflow_objectives: workflowObjectives,
+                global_state: globalState,
+            },
+            step_context: {
+                step_id: step.key,
+                step_objective: stepObjective(step, primaryObjective),
+                previous_output: previousOutput,
+                assigned_node_type: nodeType(step),
+            },
+            priming_configuration: {
+                required_skills: step.taskSpec?.init?.skills ?? [],
+                mcp_endpoints: step.taskSpec?.init?.mcps ?? [],
+                system_prompts: step.taskSpec?.init?.systemPrompts ?? [],
+                context: step.taskSpec?.init?.context,
+                adapter: step.taskSpec?.adapterKey ?? "mock",
+                model: step.taskSpec?.init?.model,
+            },
+        };
+        const output = executeStep(step, inputEnvelope, stepRun.attempt);
+        eventLog.push(runId, "step.execution_finished", {
+            status: output.execution_status,
+            action: output.qa_routing.action,
+            adapter: step.taskSpec?.adapterKey ?? "mock",
+            init: {
+                skills: step.taskSpec?.init?.skills ?? [],
+                mcps: step.taskSpec?.init?.mcps ?? [],
+                context: step.taskSpec?.init?.context ?? {},
+            },
+        }, step.key);
+        const confirmation = canConfirm(step, options ?? {}, output);
+        if (!confirmation.ok) {
+            stepRun.status = "waiting_for_approval";
+            runStatus = "waiting_for_approval";
+            eventLog.push(runId, "step.waiting_for_approval", { reason: confirmation.reason, validation: requiresValidation(step) }, step.key);
+            eventLog.push(runId, "run.waiting_for_approval", { reason: "confirmation required" }, step.key, actor);
+            break;
+        }
+        stepRun.confirmed = true;
+        eventLog.push(runId, "step.confirmed", { by: actor, validation: requiresValidation(step) }, step.key, actor);
+        if (output.execution_status === "YIELD_EXTERNAL") {
+            stepRun.status = "waiting_for_approval";
+            runStatus = "waiting_for_approval";
+            eventLog.push(runId, "step.waiting_for_approval", { reason: "external intervention" }, step.key);
+            eventLog.push(runId, "approval.resolved", { decision: "approved" }, step.key, actor);
+            stepRun.status = "succeeded";
+            runStatus = "running";
+            stepRun.output = output.mutated_payload;
+            globalState[step.key] = output.mutated_payload;
+            index += 1;
+            continue;
+        }
+        if (output.execution_status === "FAILED") {
+            stepRun.status = "failed";
+            runStatus = "failed";
+            eventLog.push(runId, "run.failed", { stepKey: step.key, reason: "step failed" }, step.key);
+            break;
+        }
+        if (output.execution_status === "QA_REJECTED") {
+            const retryMax = step.retryPolicy?.maxAttempts ?? definition.defaultRetryPolicy?.maxAttempts ?? 1;
+            if (output.qa_routing.action === "RETRY_CURRENT") {
+                if (stepRun.attempt < retryMax) {
+                    stepRun.status = "pending";
+                    eventLog.push(runId, "step.retried", { stepKey: step.key, attempt: stepRun.attempt + 1 }, step.key);
+                    continue;
+                }
+                stepRun.status = "failed";
+                runStatus = "failed";
+                eventLog.push(runId, "run.failed", { stepKey: step.key, reason: "max retry exceeded" }, step.key);
+                break;
+            }
+            if (output.qa_routing.action === "ROLLBACK_PREVIOUS") {
+                if (index === 0) {
+                    stepRun.status = "failed";
+                    runStatus = "failed";
+                    eventLog.push(runId, "run.failed", { stepKey: step.key, reason: "cannot rollback before first step" }, step.key);
+                    break;
+                }
+                const prevStep = definition.steps[index - 1];
+                const prevRun = stepRuns.get(prevStep.key);
+                prevRun.status = "pending";
+                prevRun.confirmed = false;
+                eventLog.push(runId, "step.retried", { stepKey: prevStep.key, via: step.key }, prevStep.key);
+                stepRun.status = "pending";
+                stepRun.confirmed = false;
+                index -= 1;
+                continue;
+            }
+            if (output.qa_routing.action === "RESTART_ALL") {
+                for (const s of definition.steps) {
+                    const sr = stepRuns.get(s.key);
+                    sr.status = "pending";
+                    sr.attempt = 0;
+                    sr.confirmed = false;
+                    delete sr.output;
+                }
+                eventLog.push(runId, "step.retried", { mode: "restart_all", triggeredBy: step.key }, step.key);
+                index = 0;
+                continue;
+            }
+        }
+        stepRun.status = "succeeded";
+        stepRun.output = output.mutated_payload;
+        globalState[step.key] = output.mutated_payload;
+        index += 1;
+    }
+    if (runStatus === "running") {
+        runStatus = "succeeded";
+        eventLog.push(runId, "run.completed", { steps: definition.steps.length }, undefined, actor);
+    }
+    return {
+        runId,
+        status: runStatus,
+        outputs: globalState,
+        stepRuns: definition.steps.map((s) => stepRuns.get(s.key)),
+        events: eventLog.all(),
+    };
+}

package/dist/events.d.ts

@@ -0,0 +1,7 @@
+import type { RunEvent } from "./types.js";
+export declare class EventLog {
+    private sequence;
+    private events;
+    push(runId: string, type: RunEvent["type"], payload?: Record<string, unknown>, stepRunId?: string, actor?: string): void;
+    all(): RunEvent[];
+}

package/dist/events.js

@@ -0,0 +1,21 @@
+import { randomUUID } from "node:crypto";
+export class EventLog {
+    sequence = 0;
+    events = [];
+    push(runId, type, payload = {}, stepRunId, actor = "system") {
+        this.sequence += 1;
+        this.events.push({
+            id: randomUUID(),
+            runId,
+            stepRunId,
+            type,
+            sequenceNumber: this.sequence,
+            occurredAt: new Date().toISOString(),
+            actor,
+            payload,
+        });
+    }
+    all() {
+        return [...this.events];
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};