@workflow-manager/runner 0.1.0

package/dist/remote/config.js

@@ -0,0 +1,39 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+function configRoot() {
+    const override = process.env.WORKFLOW_MANAGER_CONFIG_DIR;
+    if (override) {
+        return override;
+    }
+    if (process.platform === "win32") {
+        return path.join(process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming"), "workflow-manager");
+    }
+    return path.join(os.homedir(), ".config", "workflow-manager");
+}
+export function configFilePath() {
+    return path.join(configRoot(), "config.json");
+}
+export function loadRemoteConfig() {
+    const filePath = configFilePath();
+    if (!fs.existsSync(filePath)) {
+        return {};
+    }
+    const raw = fs.readFileSync(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    return typeof parsed === "object" && parsed ? parsed : {};
+}
+export function saveRemoteConfig(config) {
+    const filePath = configFilePath();
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, `${JSON.stringify(config, null, 2)}\n`, "utf-8");
+}
+export function clearRemoteConfig() {
+    const filePath = configFilePath();
+    if (fs.existsSync(filePath)) {
+        fs.rmSync(filePath);
+    }
+}
+export function resolveAuthToken() {
+    return process.env.WORKFLOW_MANAGER_TOKEN ?? loadRemoteConfig().token;
+}

package/dist/remote/telemetry.d.ts

@@ -0,0 +1,12 @@
+import type { RunResult, WorkflowDefinition } from "../types.js";
+import { type RunTelemetryPayload } from "./api.js";
+interface RunTelemetryOptions {
+    definition: WorkflowDefinition;
+    sourceFilePath: string;
+    durationMs: number;
+    result?: RunResult;
+    failureReason?: string;
+}
+export declare function buildRunTelemetryPayload(options: RunTelemetryOptions): RunTelemetryPayload;
+export declare function emitRunTelemetryBestEffort(options: RunTelemetryOptions): Promise<void>;
+export {};

package/dist/remote/telemetry.js

@@ -0,0 +1,69 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveAuthToken } from "./config.js";
+import { trackRunTelemetry } from "./api.js";
+function workflowSourceFormat(filePath) {
+    return path.extname(filePath).toLowerCase() === ".json" ? "json" : "markdown";
+}
+function cliVersion() {
+    try {
+        const packagePath = path.resolve(process.cwd(), "package.json");
+        const parsed = JSON.parse(fs.readFileSync(packagePath, "utf-8"));
+        return typeof parsed.version === "string" ? parsed.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function buildRunTelemetryPayload(options) {
+    const { definition, sourceFilePath, durationMs, result, failureReason } = options;
+    const stepRuns = result?.stepRuns ?? [];
+    const succeededSteps = stepRuns.filter((step) => step.status === "succeeded").length;
+    const failedSteps = stepRuns.filter((step) => step.status === "failed").length;
+    const waitingSteps = stepRuns.filter((step) => step.status === "waiting_for_approval").length;
+    const cancelledSteps = stepRuns.filter((step) => step.status === "cancelled").length;
+    const retriedSteps = stepRuns.reduce((sum, step) => sum + Math.max(step.attempt - 1, 0), 0);
+    const totalSteps = definition.steps.length;
+    const successRatio = totalSteps === 0 ? 0 : succeededSteps / totalSteps;
+    const retryPenalty = totalSteps === 0 ? 0 : Math.min(retriedSteps / totalSteps, 1) * 20;
+    const waitingPenalty = waitingSteps > 0 ? 15 : 0;
+    const failurePenalty = failedSteps > 0 ? 35 : 0;
+    const effectivenessScore = Math.max(0, Math.min(100, Math.round(successRatio * 100 - retryPenalty - waitingPenalty - failurePenalty)));
+    const terminalState = (result?.status ?? "failed");
+    return {
+        workflowKey: definition.key,
+        workflowTitle: definition.title,
+        runId: result?.runId ?? `failed-preflight:${definition.key}`,
+        terminalState,
+        totalSteps,
+        succeededSteps,
+        failedSteps,
+        waitingSteps,
+        cancelledSteps,
+        retriedSteps,
+        eventCount: result?.events.length ?? 0,
+        durationMs,
+        effectivenessScore,
+        outputKeys: Object.keys(result?.outputs ?? {}),
+        sourceName: path.basename(sourceFilePath),
+        sourceFormat: workflowSourceFormat(sourceFilePath),
+        cliVersion: cliVersion(),
+        failureReason: failureReason ?? (terminalState === "failed" ? "run failed" : null),
+        metadata: {
+            workflowObjectives: definition.objectives ?? [],
+            stepKeys: definition.steps.map((step) => step.key),
+            outputCount: Object.keys(result?.outputs ?? {}).length,
+        },
+    };
+}
+export async function emitRunTelemetryBestEffort(options) {
+    if (!resolveAuthToken()) {
+        return;
+    }
+    try {
+        await trackRunTelemetry(buildRunTelemetryPayload(options));
+    }
+    catch (error) {
+        console.warn(`Telemetry warning: ${error.message}`);
+    }
+}

package/dist/remote/types.d.ts

@@ -0,0 +1,7 @@
+export interface RemoteProfileSummary {
+    userId: string;
+    username: string | null;
+    displayName: string | null;
+    authMethod: string;
+    scopes: string[];
+}

package/dist/remote/types.js

@@ -0,0 +1 @@
+export {};

package/dist/types.d.ts

@@ -0,0 +1,122 @@
+export type WorkflowRunStatus = "queued" | "running" | "waiting_for_approval" | "paused" | "succeeded" | "failed" | "cancelled";
+export type StepRunStatus = "pending" | "runnable" | "running" | "waiting_for_approval" | "succeeded" | "failed" | "cancelled";
+export type StepKind = "task" | "approval" | "system";
+export type NodeType = "AGENT" | "HUMAN" | "SYSTEM";
+export type ExecutionStatus = "SUCCESS" | "QA_REJECTED" | "YIELD_EXTERNAL" | "FAILED";
+export type QaAction = "PROCEED" | "RETRY_CURRENT" | "ROLLBACK_PREVIOUS" | "RESTART_ALL";
+export type ValidationMode = "none" | "human" | "external";
+export type AdapterKey = "mock" | "opencode" | "codex" | "claude-code";
+export interface RetryPolicy {
+    maxAttempts?: number;
+}
+export interface ValidationSpec {
+    mode?: ValidationMode;
+    required?: boolean;
+    autoConfirm?: boolean;
+    confirmerPolicy?: string;
+}
+export interface TaskInitConfig {
+    context?: Record<string, unknown> | string;
+    skills?: string[];
+    mcps?: string[];
+    systemPrompts?: string[];
+    model?: string;
+}
+export interface StepDefinition {
+    key: string;
+    kind: StepKind;
+    title?: string;
+    objective?: string;
+    dependsOn?: string[];
+    timeoutSec?: number;
+    retryPolicy?: RetryPolicy;
+    validation?: ValidationSpec;
+    taskSpec?: {
+        adapterKey?: AdapterKey;
+        capabilityRequirements?: string[];
+        init?: TaskInitConfig;
+        payload?: Record<string, unknown>;
+    };
+    approvalSpec?: {
+        approverPolicy?: string;
+        autoApprove?: boolean;
+        validation?: ValidationSpec;
+    };
+}
+export interface WorkflowDefinition {
+    key: string;
+    title: string;
+    description?: string;
+    objectives?: string[];
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    defaultRetryPolicy?: RetryPolicy;
+    steps: StepDefinition[];
+}
+export interface InputEnvelope {
+    global_context: {
+        workflow_id: string;
+        primary_objective: string;
+        workflow_objectives: string[];
+        global_state: Record<string, unknown>;
+    };
+    step_context: {
+        step_id: string;
+        step_objective: string;
+        previous_output: Record<string, unknown>;
+        assigned_node_type: NodeType;
+    };
+    priming_configuration: {
+        required_skills: string[];
+        mcp_endpoints: string[];
+        system_prompts: string[];
+        context?: Record<string, unknown> | string;
+        adapter?: AdapterKey;
+        model?: string;
+    };
+}
+export interface OutputEnvelope {
+    step_id: string;
+    execution_status: ExecutionStatus;
+    qa_routing: {
+        action: QaAction;
+        feedback_reason: string;
+    };
+    mutated_payload: Record<string, unknown>;
+    metadata: {
+        execution_time_ms: number;
+        external_intervention_required: boolean;
+        intervention_details?: Record<string, unknown>;
+    };
+}
+export interface StepRun {
+    stepKey: string;
+    status: StepRunStatus;
+    attempt: number;
+    confirmed: boolean;
+    output?: Record<string, unknown>;
+}
+export interface RunResult {
+    runId: string;
+    status: WorkflowRunStatus;
+    outputs: Record<string, unknown>;
+    stepRuns: StepRun[];
+    events: RunEvent[];
+}
+export interface RunOptions {
+    objective?: string;
+    input?: Record<string, unknown>;
+    actor?: string;
+    confirmations?: string[];
+    autoConfirmAll?: boolean;
+}
+export interface RunEvent {
+    id: string;
+    runId: string;
+    stepRunId?: string;
+    type: "run.created" | "run.started" | "run.waiting_for_approval" | "step.runnable" | "step.claimed" | "step.execution_started" | "step.execution_finished" | "step.waiting_for_approval" | "approval.resolved" | "step.retried" | "step.confirmed" | "run.completed" | "run.failed" | "run.cancelled";
+    sequenceNumber: number;
+    occurredAt: string;
+    actor: string;
+    payload: Record<string, unknown>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/man/wfm.1

@@ -0,0 +1,96 @@
+.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 questions
+Print discovery questions used to design a workflow.
+.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]
+Run the workflow and print a JSON result with events and per-step outputs.
+.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.
+.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
+.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/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@workflow-manager/runner",
+  "version": "0.1.0",
+  "description": "CLI runner for in-memory and markdown workflow orchestration using ATEP-like envelopes",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "wfm": "dist/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist/",
+    "man/",
+    "skills/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "build:bin": "bun build ./src/index.ts --compile --outfile ./dist/wfm",
+    "build:bin:macos": "bun build ./src/index.ts --compile --target bun-darwin-arm64 --outfile ./dist/wfm-macos-arm64",
+    "build:bin:linux": "bun build ./src/index.ts --compile --target bun-linux-x64 --outfile ./dist/wfm-linux-x64",
+    "build:bin:windows": "bun build ./src/index.ts --compile --target bun-windows-x64 --outfile ./dist/wfm-windows-x64.exe",
+    "build:bin:all": "bun run build:bin:macos && bun run build:bin:linux && bun run build:bin:windows",
+    "man": "man ./man/wfm.1",
+    "test:unit": "bun test tests/parser.test.ts tests/engine.test.ts tests/mockExecutor.test.ts tests/opencodeExecutor.test.ts tests/remote.test.ts tests/run-telemetry.test.ts tests/supabase-functions.test.ts tests/supabase-ops.test.ts tests/remote-registry-app.test.ts",
+    "test:e2e": "bun test tests/story-workflow.e2e.test.ts tests/opencode-real.e2e.test.ts",
+    "test:e2e:real": "WORKFLOW_MANAGER_REAL_OPENCODE=1 bun test tests/opencode-real.e2e.test.ts",
+    "test": "bun test",
+    "dev": "bun run ./src/index.ts",
+    "package:check": "npm pack --dry-run",
+    "prepack": "bun run build",
+    "supabase:start": "supabase start",
+    "supabase:stop": "supabase stop",
+    "supabase:status": "supabase status",
+    "supabase:db:reset": "supabase db reset",
+    "supabase:functions:deploy": "supabase functions deploy create-cli-token --project-ref whairnylpdvxxgbygbzu --use-api --no-verify-jwt && supabase functions deploy auth-whoami --project-ref whairnylpdvxxgbygbzu --use-api --no-verify-jwt && supabase functions deploy list-cli-tokens --project-ref whairnylpdvxxgbygbzu --use-api --no-verify-jwt && supabase functions deploy manage-workflow --project-ref whairnylpdvxxgbygbzu --use-api --no-verify-jwt && supabase functions deploy refresh-workflow-stats --project-ref whairnylpdvxxgbygbzu --use-api --no-verify-jwt && supabase functions deploy revoke-cli-token --project-ref whairnylpdvxxgbygbzu --use-api --no-verify-jwt && supabase functions deploy publish-workflow --project-ref whairnylpdvxxgbygbzu --use-api --no-verify-jwt && supabase functions deploy pull-workflow --project-ref whairnylpdvxxgbygbzu --use-api --no-verify-jwt && supabase functions deploy search-workflows --project-ref whairnylpdvxxgbygbzu --use-api --no-verify-jwt && supabase functions deploy workflow-analytics --project-ref whairnylpdvxxgbygbzu --use-api --no-verify-jwt && supabase functions deploy track-run-telemetry --project-ref whairnylpdvxxgbygbzu --use-api --no-verify-jwt && supabase functions deploy workflow-run-insights --project-ref whairnylpdvxxgbygbzu --use-api --no-verify-jwt",
+    "remote-registry:dev": "bun --cwd apps/remote-registry dev",
+    "remote-registry:build": "bun --cwd apps/remote-registry build",
+    "docs:dev": "vitepress dev doc",
+    "docs:build": "vitepress build doc",
+    "docs:preview": "vitepress preview doc"
+  },
+  "keywords": [
+    "workflow",
+    "orchestration",
+    "cli",
+    "atep",
+    "agent-skills",
+    "claude-code",
+    "opencode",
+    "tanstack-intent"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "gray-matter": "^4.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "bun-types": "^1.3.0",
+    "typescript": "^5.9.2",
+    "vitepress": "^1.5.0"
+  }
+}

package/skills/README.md

@@ -0,0 +1,63 @@
+# workflow-manager skills
+
+`@workflow-manager/runner` now ships its TanStack Intent-compatible skills in the main npm package.
+
+The first bundled skill is `workflow-manager-cli`, which teaches agents how to:
+
+- design workflow definitions
+- scaffold Markdown or JSON workflows
+- validate and run workflows safely
+- authenticate against the remote registry
+- publish, search, and pull shared workflows
+
+## Install
+
+Install the main package in the project where you want the CLI and skill available:
+
+```bash
+npm install @workflow-manager/runner
+```
+
+Then use TanStack Intent to discover and map the shipped skill into your agent configuration:
+
+```bash
+npx @tanstack/intent@latest list
+npx @tanstack/intent@latest install
+```
+
+Intent writes task-to-skill mappings into `AGENTS.md`-style config files and points them at the installed package path under `node_modules/@workflow-manager/runner/skills/...`.
+
+## Packaged skill
+
+- skill path: `skills/workflow-manager-cli/SKILL.md`
+- package keyword: `tanstack-intent`
+- published with: the root `@workflow-manager/runner` npm package
+
+## Local development
+
+From the repository root:
+
+```bash
+npm pack --dry-run
+ls skills/workflow-manager-cli
+```
+
+## Publish
+
+Publish from the repository root so the CLI runner and `skills/` ship together:
+
+```bash
+npm publish
+```
+
+Before publishing, verify the package contents:
+
+```bash
+npm pack --dry-run
+```
+
+## Package layout
+
+- `skills/workflow-manager-cli/SKILL.md`: TanStack Intent skill entrypoint
+- `skills/workflow-manager-cli/README.md`: local notes for contributors
+- `package.json`: package metadata, published files, and `tanstack-intent` keyword

package/skills/workflow-manager-cli/README.md

@@ -0,0 +1,11 @@
+# workflow-manager-cli skill
+
+This skill ships inside the root `@workflow-manager/runner` npm package.
+
+It is designed for TanStack Intent discovery and should stay aligned with the CLI behavior documented in:
+
+- `README.md`
+- `src/index.ts`
+- `src/parser.ts`
+- `src/engine.ts`
+- `src/remote/commands.ts`

package/skills/workflow-manager-cli/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: @workflow-manager/runner/cli
+description: >
+  Load this skill when working with the wfm CLI from @workflow-manager/runner, authoring or
+  validating workflow definitions, configuring step skills and adapters, or
+  publishing workflows to the remote registry. Covers questions, scaffold,
+  validate, run, auth, publish, pull, search, and remote info.
+type: core
+library: @workflow-manager/runner
+library_version: "0.1.0"
+sources:
+  - "navio/workflow-manager:README.md"
+  - "navio/workflow-manager:src/index.ts"
+  - "navio/workflow-manager:src/parser.ts"
+  - "navio/workflow-manager:src/engine.ts"
+  - "navio/workflow-manager:src/remote/commands.ts"
+---
+
+# wfm CLI
+
+Use this skill when you need to create or operate `workflow-manager` workflows from the terminal with `wfm`.
+
+## When to use this skill
+
+Use it when the user wants to:
+
+- scaffold a new workflow definition
+- validate or run a workflow file
+- configure approvals, retry policy, or adapter initialization
+- publish a workflow to the remote registry
+- search for or pull a shared workflow
+- understand the difference between Markdown and JSON workflow formats
+
+## Core workflow
+
+Use this sequence unless the user asks for a narrower task:
+
+1. Discover the workflow intent with `wfm questions`
+2. Scaffold a starter file with `wfm scaffold`
+3. Edit the workflow definition
+4. Validate the file with `wfm validate`
+5. Execute it with `wfm run`
+6. If needed, authenticate and publish with the remote registry commands
+
+## Local workflow commands
+
+```bash
+wfm questions
+
+wfm scaffold ./example-workflow.md
+wfm scaffold ./example-workflow.json --format json
+
+wfm validate ./example-workflow.md
+wfm validate ./example-workflow.json
+
+wfm run ./example-workflow.md --confirm discover,qa_gate:human
+wfm run ./example-workflow.json --auto-confirm-all
+```
+
+## Remote registry commands
+
+```bash
+wfm auth login --token <token>
+wfm auth whoami
+wfm auth logout
+
+wfm search bunny
+wfm remote info alice/remote-bunny
+wfm publish ./example-workflow.json --visibility public --tag storytelling,example
+wfm pull alice/remote-bunny --output ./remote-bunny.json
+```
+
+## Skill guidance
+
+- Prefer `validate` before `run` or `publish`
+- Keep `runWorkflow(...)` behavior registry-agnostic; registry operations belong in the CLI remote commands
+- Use Markdown workflows when the user wants editable frontmatter plus notes
+- Use JSON workflows when the user wants machine-generated or strongly structured files
+- Use `--auto-confirm-all` only when the workflow is intentionally non-interactive
+- When publishing, preserve the source format the user authored
+
+## Workflow authoring checklist
+
+- Set stable `key` and `title` values
+- Define clear step `objective` text
+- Add `dependsOn` relationships explicitly
+- Set validation mode per step (`none`, `human`, `external`)
+- Configure adapter initialization under `taskSpec.init`
+- Use stable step keys because tests and docs may refer to them
+
+## Adapter and validation notes
+
+- Supported adapters include `mock`, `opencode`, `codex`, and `claude-code`
+- Human approvals should stay explicit in workflow definitions
+- External validation should be deterministic where possible
+- Use the mock adapter for fast tests and scaffolding flows
+
+## Recommended project references
+
+- `src/index.ts`: CLI command entrypoint
+- `src/parser.ts`: Markdown and JSON parsing plus validation
+- `src/engine.ts`: orchestration loop
+- `src/remote/commands.ts`: auth, publish, pull, search, and remote info commands
+- `tests/`: unit and e2e coverage for workflow behavior
+
+## Typical troubleshooting
+
+- If validation fails, inspect the reported schema or dependency error before running again
+- If `publish` fails, confirm the user is logged in with `wfm auth whoami`
+- If remote calls fail in the browser, verify the remote registry app has valid Supabase `VITE_*` environment variables
+- If a real adapter test fails, confirm the underlying external CLI is installed and available on `PATH`