@workflow-manager/runner 0.1.0

package/dist/index.js

@@ -0,0 +1,413 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { parseWorkflowFile, validateWorkflow } from "./parser.js";
+import { runWorkflow } from "./engine.js";
+import { cmdAuth, cmdPublish, cmdPull, cmdRemoteInfo, cmdSearch } from "./remote/commands.js";
+import { emitRunTelemetryBestEffort } from "./remote/telemetry.js";
+const DISCOVERY_QUESTIONS = [
+    "1) What set of workflow objectives should be tracked per run (one or many)?",
+    "2) Which steps require human validation vs external validation?",
+    "3) Which approvals are mandatory and who can confirm each approval?",
+    "4) Which steps require explicit confirmation before proceeding?",
+    "5) For each step, which adapter should run it (opencode, codex, claude-code, mock)?",
+    "6) What per-step initialization is needed (context, skills, MCPs, system prompts, model)?",
+    "7) What output format should this session produce (JSON run report, markdown summary, event timeline)?",
+    "8) What retry/rollback policy should be default and where should exceptions apply?",
+];
+function usage() {
+    console.log(`wfm commands:
+  questions
+  scaffold [path] [--format markdown|json]
+  validate <workflow.md|workflow.json>
+  run <workflow.md|workflow.json> [--input input.json] [--objective "string"] [--confirm stepA,stepB:human] [--auto-confirm-all]
+  auth <login|whoami|logout> [--token <token>]
+  publish <workflow.md|workflow.json> [--slug slug] [--title title] [--description text] [--visibility public|private] [--version version] [--tag a,b] [--draft]
+  pull <owner/slug> [--version version] [--output path]
+  search [query]
+  remote info <owner/slug>
+  man`);
+}
+function getFlag(name) {
+    const idx = process.argv.indexOf(name);
+    if (idx >= 0 && idx + 1 < process.argv.length)
+        return process.argv[idx + 1];
+    return undefined;
+}
+function hasFlag(name) {
+    return process.argv.includes(name);
+}
+function cmdQuestions() {
+    console.log("Project definition questions:");
+    for (const q of DISCOVERY_QUESTIONS)
+        console.log(`- ${q}`);
+    console.log("\nExpected output of this session:");
+    console.log("- Finalized workflow file (markdown or json) with per-step objectives");
+    console.log("- Validation/approval confirmation map per step");
+    console.log("- Adapter init map (opencode/codex/claude-code with context+skills+mcps)");
+    console.log("- Runnable CLI command examples + run JSON output");
+}
+const WORKFLOW_SCAFFOLD_JSON = {
+    key: "workflow-manager-sample",
+    title: "Workflow Manager Sample",
+    description: "Workflow definition with per-step objectives and confirmations",
+    objectives: ["deliver a working implementation", "ensure validation and approvals are explicit"],
+    inputSchema: {
+        type: "object",
+        properties: {
+            ticket: { type: "string" },
+        },
+    },
+    outputSchema: {
+        type: "object",
+    },
+    defaultRetryPolicy: {
+        maxAttempts: 2,
+    },
+    steps: [
+        {
+            key: "discover",
+            kind: "task",
+            objective: "Understand requirements and constraints",
+            dependsOn: [],
+            validation: { mode: "human", required: true, autoConfirm: false },
+            taskSpec: {
+                adapterKey: "opencode",
+                init: {
+                    context: { repo: "example/repo" },
+                    skills: ["architecture", "planning"],
+                    mcps: ["mcp://github", "mcp://docs"],
+                    systemPrompts: ["Focus on architecture trade-offs"],
+                    model: "openrouter/anthropic/claude-sonnet-4",
+                },
+                payload: { mockResult: "success" },
+            },
+        },
+        {
+            key: "qa_gate",
+            kind: "approval",
+            objective: "Human product review approval",
+            dependsOn: ["discover"],
+            approvalSpec: {
+                autoApprove: false,
+                validation: { mode: "human", required: true, autoConfirm: false },
+            },
+        },
+        {
+            key: "implement",
+            kind: "task",
+            objective: "Implement agreed changes",
+            dependsOn: ["qa_gate"],
+            validation: { mode: "external", required: true, autoConfirm: false },
+            retryPolicy: { maxAttempts: 2 },
+            taskSpec: {
+                adapterKey: "codex",
+                init: {
+                    context: { language: "typescript" },
+                    skills: ["coding", "testing"],
+                    mcps: ["mcp://repo", "mcp://ci"],
+                    systemPrompts: ["Write tests with implementation"],
+                },
+                payload: { mockResult: "success" },
+            },
+        },
+        {
+            key: "hardening",
+            kind: "task",
+            objective: "Final hardening checks with Claude Code",
+            dependsOn: ["implement"],
+            validation: { mode: "external", required: true, autoConfirm: false },
+            taskSpec: {
+                adapterKey: "claude-code",
+                init: {
+                    context: { quality: "high" },
+                    skills: ["security-review", "refactoring"],
+                    mcps: ["mcp://security"],
+                    systemPrompts: ["Prioritize correctness and readability"],
+                },
+                payload: { mockResult: "success" },
+            },
+        },
+    ],
+};
+const WORKFLOW_SCAFFOLD_MARKDOWN = `---
+key: workflow-manager-sample
+title: Workflow Manager Sample
+description: Workflow definition with per-step objectives and confirmations
+objectives:
+  - deliver a working implementation
+  - ensure validation and approvals are explicit
+inputSchema:
+  type: object
+  properties:
+    ticket:
+      type: string
+outputSchema:
+  type: object
+defaultRetryPolicy:
+  maxAttempts: 2
+steps:
+  - key: discover
+    kind: task
+    objective: Understand requirements and constraints
+    dependsOn: []
+    validation:
+      mode: human
+      required: true
+      autoConfirm: false
+    taskSpec:
+      adapterKey: opencode
+      init:
+        context:
+          repo: example/repo
+        skills: [architecture, planning]
+        mcps: [mcp://github, mcp://docs]
+        systemPrompts: [Focus on architecture trade-offs]
+        model: openrouter/anthropic/claude-sonnet-4
+      payload:
+        mockResult: success
+  - key: qa_gate
+    kind: approval
+    objective: Human product review approval
+    dependsOn: [discover]
+    approvalSpec:
+      autoApprove: false
+      validation:
+        mode: human
+        required: true
+        autoConfirm: false
+  - key: implement
+    kind: task
+    objective: Implement agreed changes
+    dependsOn: [qa_gate]
+    validation:
+      mode: external
+      required: true
+      autoConfirm: false
+    retryPolicy:
+      maxAttempts: 2
+    taskSpec:
+      adapterKey: codex
+      init:
+        context:
+          language: typescript
+        skills: [coding, testing]
+        mcps: [mcp://repo, mcp://ci]
+        systemPrompts: [Write tests with implementation]
+      payload:
+        mockResult: success
+  - key: hardening
+    kind: task
+    objective: Final hardening checks with Claude Code
+    dependsOn: [implement]
+    validation:
+      mode: external
+      required: true
+      autoConfirm: false
+    taskSpec:
+      adapterKey: claude-code
+      init:
+        context:
+          quality: high
+        skills: [security-review, refactoring]
+        mcps: [mcp://security]
+        systemPrompts: [Prioritize correctness and readability]
+      payload:
+        mockResult: success
+---
+
+# Workflow Notes
+
+Edit frontmatter to configure orchestration behavior.
+`;
+function resolveScaffoldFormat(targetPath, explicitFormat) {
+    if (explicitFormat === "markdown" || explicitFormat === "json") {
+        return explicitFormat;
+    }
+    return path.extname(targetPath).toLowerCase() === ".json" ? "json" : "markdown";
+}
+function parseScaffoldArgs(args) {
+    let targetPath;
+    let format;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--format") {
+            format = args[i + 1];
+            i += 1;
+            continue;
+        }
+        if (!arg.startsWith("-") && !targetPath) {
+            targetPath = arg;
+        }
+    }
+    return { targetPath, format };
+}
+function cmdScaffold(targetPath, format) {
+    const resolvedPath = targetPath ? path.resolve(targetPath) : path.resolve("./example-workflow.md");
+    const normalizedFormat = format?.toLowerCase();
+    const resolvedFormat = resolveScaffoldFormat(resolvedPath, normalizedFormat);
+    if (normalizedFormat && resolvedFormat !== normalizedFormat) {
+        console.error(`Invalid --format value: ${format}. Use markdown or json.`);
+        return 1;
+    }
+    const template = resolvedFormat === "json"
+        ? `${JSON.stringify(WORKFLOW_SCAFFOLD_JSON, null, 2)}\n`
+        : WORKFLOW_SCAFFOLD_MARKDOWN;
+    fs.writeFileSync(resolvedPath, template, "utf-8");
+    console.log(`Scaffolded ${resolvedFormat} workflow: ${resolvedPath}`);
+    return 0;
+}
+function cmdMan() {
+    const manPagePath = path.resolve("./man/wfm.1");
+    if (!fs.existsSync(manPagePath)) {
+        console.error(`Man page not found at ${manPagePath}`);
+        return 1;
+    }
+    const result = spawnSync("man", [manPagePath], { stdio: "inherit" });
+    if (result.status === 0) {
+        return 0;
+    }
+    console.log("\n' man ' command unavailable, printing page contents:\n");
+    console.log(fs.readFileSync(manPagePath, "utf-8"));
+    return 0;
+}
+function cmdValidate(filePath) {
+    try {
+        const workflow = parseWorkflowFile(path.resolve(filePath));
+        const errors = validateWorkflow(workflow);
+        if (errors.length > 0) {
+            console.log("Validation failed:");
+            for (const e of errors)
+                console.log(`- ${e}`);
+            return 1;
+        }
+        console.log("Validation OK");
+        return 0;
+    }
+    catch (err) {
+        console.error(`Validation error: ${err.message}`);
+        return 1;
+    }
+}
+async function cmdRun(filePath) {
+    const resolvedPath = path.resolve(filePath);
+    const startedAt = Date.now();
+    let workflow;
+    try {
+        workflow = parseWorkflowFile(resolvedPath);
+        const errors = validateWorkflow(workflow);
+        if (errors.length > 0) {
+            console.error(`Invalid workflow: ${errors.join("; ")}`);
+            await emitRunTelemetryBestEffort({
+                definition: workflow,
+                sourceFilePath: resolvedPath,
+                durationMs: Date.now() - startedAt,
+                failureReason: errors.join("; "),
+            });
+            return 1;
+        }
+        const objective = getFlag("--objective");
+        const inputPath = getFlag("--input");
+        const input = inputPath ? JSON.parse(fs.readFileSync(path.resolve(inputPath), "utf-8")) : {};
+        const confirmRaw = getFlag("--confirm") ?? "";
+        const confirmations = confirmRaw
+            .split(",")
+            .map((x) => x.trim())
+            .filter(Boolean);
+        const result = runWorkflow(workflow, {
+            objective,
+            input,
+            confirmations,
+            autoConfirmAll: hasFlag("--auto-confirm-all"),
+        });
+        console.log(JSON.stringify(result, null, 2));
+        await emitRunTelemetryBestEffort({
+            definition: workflow,
+            sourceFilePath: resolvedPath,
+            durationMs: Date.now() - startedAt,
+            result,
+            failureReason: result.status === "failed" ? "run failed" : result.status === "waiting_for_approval" ? "confirmation required" : undefined,
+        });
+        return result.status === "succeeded" ? 0 : 2;
+    }
+    catch (err) {
+        console.error(`Run error: ${err.message}`);
+        if (workflow) {
+            await emitRunTelemetryBestEffort({
+                definition: workflow,
+                sourceFilePath: resolvedPath,
+                durationMs: Date.now() - startedAt,
+                failureReason: err.message,
+            });
+        }
+        return 1;
+    }
+}
+async function main() {
+    const cmd = process.argv[2];
+    if (!cmd || cmd === "-h" || cmd === "--help") {
+        usage();
+        process.exit(0);
+    }
+    if (cmd === "questions") {
+        cmdQuestions();
+        process.exit(0);
+    }
+    if (cmd === "scaffold") {
+        const { targetPath, format } = parseScaffoldArgs(process.argv.slice(3));
+        process.exit(cmdScaffold(targetPath, format));
+    }
+    if (cmd === "man") {
+        process.exit(cmdMan());
+    }
+    if (cmd === "validate") {
+        const file = process.argv[3];
+        if (!file) {
+            usage();
+            process.exit(1);
+        }
+        process.exit(cmdValidate(file));
+    }
+    if (cmd === "run") {
+        const file = process.argv[3];
+        if (!file) {
+            usage();
+            process.exit(1);
+        }
+        process.exit(await cmdRun(file));
+    }
+    if (cmd === "auth") {
+        process.exit(await cmdAuth(process.argv.slice(3)));
+    }
+    if (cmd === "search") {
+        process.exit(await cmdSearch(process.argv.slice(3)));
+    }
+    if (cmd === "publish") {
+        const file = process.argv[3];
+        if (!file) {
+            usage();
+            process.exit(1);
+        }
+        process.exit(await cmdPublish(file, process.argv.slice(4)));
+    }
+    if (cmd === "pull") {
+        const reference = process.argv[3];
+        if (!reference) {
+            usage();
+            process.exit(1);
+        }
+        process.exit(await cmdPull(reference, process.argv.slice(4)));
+    }
+    if (cmd === "remote" && process.argv[3] === "info") {
+        const reference = process.argv[4];
+        if (!reference) {
+            usage();
+            process.exit(1);
+        }
+        process.exit(await cmdRemoteInfo(reference));
+    }
+    usage();
+    process.exit(1);
+}
+void main();

package/dist/mockExecutor.d.ts

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

package/dist/mockExecutor.js

@@ -0,0 +1,110 @@
+function asRecord(value) {
+    return value && typeof value === "object" ? value : {};
+}
+function chapterOutputs(previousOutput) {
+    return Object.values(previousOutput)
+        .map((entry) => asRecord(entry))
+        .filter((entry) => typeof entry.chapterMarkdown === "string");
+}
+export function executeMockStep(step, input, attempt) {
+    const start = Date.now();
+    const payload = asRecord(step.taskSpec?.payload);
+    const mockResult = String(payload.mockResult ?? "success").toLowerCase();
+    const feedback = String(payload.feedback ?? "");
+    const make = (status, action, extraPayload = {}, feedbackReason = feedback) => ({
+        step_id: step.key,
+        execution_status: status,
+        qa_routing: {
+            action,
+            feedback_reason: feedbackReason,
+        },
+        mutated_payload: {
+            stepKey: step.key,
+            attempt,
+            objective: input.step_context.step_objective,
+            adapter: input.priming_configuration.adapter ?? "mock",
+            priming: {
+                skills: input.priming_configuration.required_skills,
+                mcps: input.priming_configuration.mcp_endpoints,
+            },
+            mockResult,
+            ...extraPayload,
+        },
+        metadata: {
+            execution_time_ms: Date.now() - start,
+            external_intervention_required: status === "YIELD_EXTERNAL",
+            intervention_details: status === "YIELD_EXTERNAL" ? { reason: "Awaiting human/external validation" } : undefined,
+        },
+    });
+    if (step.kind === "approval") {
+        const autoApprove = step.approvalSpec?.autoApprove ?? false;
+        return autoApprove ? make("SUCCESS", "PROCEED") : make("YIELD_EXTERNAL", "PROCEED");
+    }
+    if (typeof payload.storyChapter === "number") {
+        const chapterNumber = payload.storyChapter;
+        const prompt = String(input.global_context.global_state.storyRequest ?? input.global_context.primary_objective ?? "a bunny story");
+        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", {
+            chapterNumber,
+            chapterTitle: `Chapter ${chapterNumber}`,
+            paragraph,
+            chapterMarkdown: `## Chapter ${chapterNumber}\n\n${paragraph}`,
+            storyPrompt: prompt,
+        });
+    }
+    if (payload.validateStory === true) {
+        const expectedChapters = Number(payload.requiredChapters ?? 2);
+        const previousOutput = asRecord(input.step_context.previous_output);
+        const chapters = chapterOutputs(previousOutput)
+            .map((entry) => String(entry.chapterMarkdown))
+            .join("\n\n");
+        const chapterMatches = chapters.match(/^## Chapter\s+\d+/gm) ?? [];
+        const hasBunnyTheme = /bunny/i.test(chapters);
+        const isValid = chapterMatches.length === expectedChapters && hasBunnyTheme;
+        if (!isValid) {
+            return make("QA_REJECTED", "RETRY_CURRENT", {
+                expectedChapters,
+                foundChapters: chapterMatches.length,
+                hasBunnyTheme,
+                validationPassed: false,
+            }, `Story must include exactly ${expectedChapters} chapters and bunny-themed content`);
+        }
+        return make("SUCCESS", "PROCEED", {
+            expectedChapters,
+            foundChapters: chapterMatches.length,
+            hasBunnyTheme,
+            validationPassed: true,
+        });
+    }
+    if (payload.renderStoryMarkdown === true) {
+        const previousOutput = asRecord(input.step_context.previous_output);
+        const chapters = chapterOutputs(previousOutput)
+            .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 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", {
+            chapterCount: chapters.length,
+            storyMarkdown,
+        });
+    }
+    switch (mockResult) {
+        case "retry":
+            return make("QA_REJECTED", "RETRY_CURRENT");
+        case "rollback":
+            return make("QA_REJECTED", "ROLLBACK_PREVIOUS");
+        case "restart":
+            return make("QA_REJECTED", "RESTART_ALL");
+        case "yield":
+            return make("YIELD_EXTERNAL", "PROCEED");
+        case "fail":
+            return make("FAILED", "PROCEED");
+        default:
+            return make("SUCCESS", "PROCEED");
+    }
+}

package/dist/opencodeExecutor.d.ts

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