@gobing-ai/ts-dual-workflow-engine 0.2.1

package/package.json

@@ -0,0 +1,61 @@
+{
+    "name": "@gobing-ai/ts-dual-workflow-engine",
+    "version": "0.2.1",
+    "description": "@gobing-ai/ts-dual-workflow-engine — State-machine and transition-flow workflow runtime.",
+    "keywords": [
+        "typescript",
+        "workflow",
+        "state-machine",
+        "transition-flow",
+        "dag"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/gobing-ai/ts-libs.git",
+        "directory": "packages/dual-workflow-engine"
+    },
+    "author": "Robin Min <minlongbing@gmail.com>",
+    "contributors": [
+        "Robin Min <minlongbing@gmail.com>"
+    ],
+    "type": "module",
+    "private": false,
+    "sideEffects": false,
+    "license": "Apache-2.0",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist",
+        "src",
+        "README.md"
+    ],
+    "scripts": {
+        "build": "tsc -p tsconfig.build.json && bun ../../scripts/builder.ts fix-dist-esm-extensions dist",
+        "test": "NODE_ENV=test bun test --coverage --coverage-dir=.coverage --reporter=dots",
+        "test:full": "NODE_ENV=test bun test --update-snapshots --coverage --coverage-dir=.coverage",
+        "typecheck": "tsc --noEmit",
+        "lint": "biome check . && bun run typecheck",
+        "format": "biome check . --write",
+        "check": "bun run lint && bun run test",
+        "prepublishOnly": "bun run build",
+        "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-dual-workflow-engine-v<version> && git push --tags' && exit 1"
+    },
+    "dependencies": {
+        "@gobing-ai/ts-db": "workspace:*",
+        "@gobing-ai/ts-runtime": "workspace:*",
+        "yaml": "^2.7.0",
+        "zod": "^4.1.0"
+    },
+    "devDependencies": {
+        "@types/bun": "1.3.14"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}

package/src/config.ts

@@ -0,0 +1,57 @@
+import { getFs } from '@gobing-ai/ts-runtime';
+import { parse } from 'yaml';
+import { WorkflowValidationError } from './errors';
+import { WorkflowDefSchema } from './schema';
+import type { WorkflowDef } from './types';
+
+/** Load a workflow definition from YAML or JSON text. */
+export function loadWorkflowDefFromText(text: string, source = '<inline>'): WorkflowDef {
+    const parsed = source.endsWith('.json') ? JSON.parse(text) : parse(text);
+    const result = WorkflowDefSchema.safeParse(parsed);
+    if (!result.success) {
+        throw new WorkflowValidationError(
+            `Workflow definition failed schema validation for ${source}: ${result.error.issues.map((issue) => issue.message).join('; ')}`,
+            result.error.issues,
+        );
+    }
+    validateWorkflowDef(result.data as WorkflowDef);
+    return result.data as WorkflowDef;
+}
+
+/** Load a workflow definition from a filesystem path. */
+export async function loadWorkflowDef(path: string): Promise<WorkflowDef> {
+    return loadWorkflowDefFromText(await getFs().readFile(path), path);
+}
+
+/** Validate semantic workflow invariants beyond structural Zod checks. */
+export function validateWorkflowDef(workflow: WorkflowDef): void {
+    if (workflow.kind === 'transition-flow') {
+        validateTransitionFlow(workflow);
+    } else {
+        validateStateMachine(workflow);
+    }
+}
+
+function validateStateMachine(workflow: Extract<WorkflowDef, { kind?: 'state-machine' }>): void {
+    const states = new Set(workflow.states.map((state) => state.id));
+    if (!states.has(workflow.initialState)) {
+        throw new WorkflowValidationError(`Initial state "${workflow.initialState}" is not declared`);
+    }
+    for (const transition of workflow.transitions) {
+        if (!states.has(transition.from))
+            throw new WorkflowValidationError(`Transition source "${transition.from}" is not declared`);
+        if (!states.has(transition.to))
+            throw new WorkflowValidationError(`Transition target "${transition.to}" is not declared`);
+    }
+}
+
+function validateTransitionFlow(workflow: Extract<WorkflowDef, { kind: 'transition-flow' }>): void {
+    const nodes = new Set(workflow.nodes.map((node) => node.id));
+    if (!nodes.has(workflow.initialNode)) {
+        throw new WorkflowValidationError(`Initial node "${workflow.initialNode}" is not declared`);
+    }
+    for (const edge of workflow.edges) {
+        if (!nodes.has(edge.from)) throw new WorkflowValidationError(`Edge source "${edge.from}" is not declared`);
+        if (!nodes.has(edge.to)) throw new WorkflowValidationError(`Edge target "${edge.to}" is not declared`);
+    }
+}

package/src/errors.ts

@@ -0,0 +1,29 @@
+/** Error raised when workflow definition validation fails. */
+export class WorkflowValidationError extends Error {
+    constructor(
+        message: string,
+        readonly details?: unknown,
+    ) {
+        super(message);
+        this.name = 'WorkflowValidationError';
+    }
+}
+
+/** Error raised by the state-machine driver for invalid runtime state. */
+export class FSMError extends Error {
+    constructor(
+        message: string,
+        readonly details?: unknown,
+    ) {
+        super(message);
+        this.name = 'FSMError';
+    }
+}
+
+/** Error raised when a run id collides with an existing persisted run. */
+export class RunCollisionError extends Error {
+    constructor(runId: string) {
+        super(`Workflow run "${runId}" already exists`);
+        this.name = 'RunCollisionError';
+    }
+}

package/src/host.ts

@@ -0,0 +1,100 @@
+import { NodeProcessExecutor, type ProcessExecutor } from '@gobing-ai/ts-runtime';
+import { WorkflowValidationError } from './errors';
+import type { ActionResult, ActionRunContext, ActionRunner, GuardContext, GuardRunner } from './types';
+
+/** Registry owner for workflow actions and guards. */
+export class WorkflowEngineHost {
+    private readonly actions = new Map<string, ActionRunner>();
+    private readonly guards = new Map<string, GuardRunner>();
+
+    /** Register or replace an action runner. */
+    registerAction(action: ActionRunner): this {
+        this.actions.set(action.kind, action);
+        return this;
+    }
+
+    /** Register or replace a guard runner. */
+    registerGuard(guard: GuardRunner): this {
+        this.guards.set(guard.kind, guard);
+        return this;
+    }
+
+    /** Execute a registered action. */
+    async runAction(kind: string, options: Record<string, unknown>, context: ActionRunContext): Promise<ActionResult> {
+        const action = this.actions.get(kind);
+        if (action === undefined) throw new WorkflowValidationError(`Unknown workflow action "${kind}"`);
+        return await action.execute(options, context);
+    }
+
+    /** Evaluate a registered guard. */
+    async evaluateGuard(kind: string, options: Record<string, unknown>, context: GuardContext): Promise<boolean> {
+        const guard = this.guards.get(kind);
+        if (guard === undefined) throw new WorkflowValidationError(`Unknown workflow guard "${kind}"`);
+        return await guard.evaluate(options, context);
+    }
+}
+
+/** Create a workflow host with built-in note, shell, always, and action-ok capabilities. */
+export function createDefaultWorkflowEngineHost(
+    options: { processExecutor?: ProcessExecutor } = {},
+): WorkflowEngineHost {
+    const host = new WorkflowEngineHost();
+    host.registerAction(new NoteActionRunner());
+    host.registerAction(new ShellActionRunner(options.processExecutor ?? new NodeProcessExecutor()));
+    host.registerGuard({ kind: 'always', evaluate: async () => true });
+    host.registerGuard({ kind: 'never', evaluate: async () => false });
+    host.registerGuard({
+        kind: 'action-ok',
+        evaluate: async (_options, context) => context.lastActionResult?.ok === true,
+    });
+    return host;
+}
+
+/** Built-in action that records a note in result data. */
+export class NoteActionRunner implements ActionRunner {
+    readonly kind = 'note';
+
+    /** Execute a no-op note action. */
+    async execute(options: Record<string, unknown>): Promise<ActionResult> {
+        return { ok: true, data: { message: String(options.message ?? '') } };
+    }
+}
+
+/** Built-in shell action backed by ts-runtime ProcessExecutor. */
+export class ShellActionRunner implements ActionRunner {
+    readonly kind = 'shell';
+
+    constructor(private readonly processExecutor: ProcessExecutor) {}
+
+    /** Execute a shell command with optional args and cwd. */
+    async execute(options: Record<string, unknown>, context: ActionRunContext): Promise<ActionResult> {
+        const command = stringOption(options, 'command');
+        const args = arrayOption(options, 'args');
+        const result = await this.processExecutor.run({
+            command,
+            args,
+            cwd: stringOption(options, 'cwd', context.workdir),
+            rejectOnError: false,
+            forceBuffered: true,
+        });
+        return {
+            ok: result.exitCode === 0,
+            data: { stdout: result.stdout, stderr: result.stderr, exitCode: result.exitCode },
+            ...(result.exitCode === 0 ? {} : { error: `Command "${command}" exited with ${result.exitCode}` }),
+        };
+    }
+}
+
+function stringOption(options: Record<string, unknown>, key: string, fallback?: string): string {
+    const value = options[key];
+    if (typeof value === 'string') return value;
+    if (fallback !== undefined) return fallback;
+    throw new WorkflowValidationError(`Action option "${key}" must be a string`);
+}
+
+function arrayOption(options: Record<string, unknown>, key: string): string[] {
+    const value = options[key];
+    if (value === undefined) return [];
+    if (Array.isArray(value) && value.every((entry) => typeof entry === 'string')) return value;
+    throw new WorkflowValidationError(`Action option "${key}" must be a string array`);
+}

package/src/index.ts

@@ -0,0 +1,48 @@
+export { loadWorkflowDef, loadWorkflowDefFromText, validateWorkflowDef } from './config';
+export { FSMError, RunCollisionError, WorkflowValidationError } from './errors';
+export {
+    createDefaultWorkflowEngineHost,
+    NoteActionRunner,
+    ShellActionRunner,
+    WorkflowEngineHost,
+} from './host';
+export {
+    applyWorkflowEngineSchema,
+    DbWorkflowPersistenceAdapter,
+    MemoryWorkflowPersistenceAdapter,
+} from './persistence';
+export {
+    ActionDefSchema,
+    GuardDefSchema,
+    StateMachineWorkflowDefSchema,
+    TransitionFlowWorkflowDefSchema,
+    WorkflowDefSchema,
+} from './schema';
+export { WORKFLOW_ENGINE_SCHEMA_SQL } from './schema-sql';
+export { WorkflowService } from './service';
+export { StateMachineDriver, type StateMachineDriverOptions } from './state-machine';
+export { TransitionFlowDriver, type TransitionFlowDriverOptions } from './transition-flow';
+export type {
+    ActionDef,
+    ActionResult,
+    ActionRunContext,
+    ActionRunner,
+    Env,
+    FlowEdgeDef,
+    FlowNodeDef,
+    GuardContext,
+    GuardDef,
+    GuardRunner,
+    StateDef,
+    StateMachineWorkflowDef,
+    TransitionDef,
+    TransitionFlowWorkflowDef,
+    Vars,
+    WorkflowDef,
+    WorkflowPersistenceAdapter,
+    WorkflowRunOptions,
+    WorkflowRunRecord,
+    WorkflowRunResult,
+    WorkflowStatus,
+} from './types';
+export { mergeVars, resolveTemplateString, resolveTemplates, type VariableContext } from './variables';

package/src/persistence.ts

@@ -0,0 +1,155 @@
+import type { DbAdapter } from '@gobing-ai/ts-db';
+import { RunCollisionError } from './errors';
+import { WORKFLOW_ENGINE_SCHEMA_SQL } from './schema-sql';
+import type { WorkflowPersistenceAdapter, WorkflowRunRecord, WorkflowStatus } from './types';
+
+/** Apply workflow-engine-owned schema to a database adapter. */
+export async function applyWorkflowEngineSchema(db: DbAdapter): Promise<void> {
+    for (const statement of WORKFLOW_ENGINE_SCHEMA_SQL.split(';')) {
+        const sql = statement.trim();
+        if (sql.length > 0) await db.exec(sql);
+    }
+}
+
+/** SQLite/D1-compatible workflow persistence adapter backed by ts-db. */
+export class DbWorkflowPersistenceAdapter implements WorkflowPersistenceAdapter {
+    constructor(private readonly db: DbAdapter) {}
+
+    /** Create a run row, rejecting duplicate run ids. */
+    async createRun(record: WorkflowRunRecord): Promise<void> {
+        const existing = await this.loadRun(record.id);
+        if (existing !== undefined) throw new RunCollisionError(record.id);
+        await applyWorkflowEngineSchema(this.db);
+        await this.db.run(
+            `INSERT INTO runs (id, workflow_name, mode, status, started_at, completed_at, metadata_json, created_at, updated_at)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+            record.id,
+            record.workflow_name,
+            record.mode,
+            record.status,
+            record.started_at,
+            record.completed_at,
+            record.metadata_json,
+            Date.now(),
+            Date.now(),
+        );
+    }
+
+    /** Finalize a run with terminal status and timestamp. */
+    async finalizeRun(runId: string, status: WorkflowStatus, completedAt: string): Promise<void> {
+        await this.db.run(
+            'UPDATE runs SET status = ?, completed_at = ?, updated_at = ? WHERE id = ?',
+            status,
+            completedAt,
+            Date.now(),
+            runId,
+        );
+    }
+
+    /** Save one phase/state execution record. */
+    async savePhase(runId: string, phase: string, status: WorkflowStatus): Promise<void> {
+        const now = Date.now();
+        await this.db.run(
+            `INSERT INTO phase_runs (id, run_id, phase, status, started_at, completed_at, created_at, updated_at)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+            `${runId}:phase:${phase}:${crypto.randomUUID()}`,
+            runId,
+            phase,
+            status,
+            new Date(now).toISOString(),
+            status === 'running' ? null : new Date(now).toISOString(),
+            now,
+            now,
+        );
+    }
+
+    /** Save one transition record. */
+    async saveTransition(runId: string, from: string, to: string, trigger: string | null): Promise<void> {
+        const now = Date.now();
+        await this.db.run(
+            `INSERT INTO transition_runs (id, run_id, from_state, to_state, trigger, status, created_at, updated_at)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+            `${runId}:transition:${from}:${to}:${crypto.randomUUID()}`,
+            runId,
+            from,
+            to,
+            trigger,
+            'done',
+            now,
+            now,
+        );
+    }
+
+    /** Save the latest workflow state snapshot. */
+    async saveWorkflowState(runId: string, state: string, data: Record<string, unknown>): Promise<void> {
+        const now = Date.now();
+        await this.db.run(
+            `INSERT INTO workflow_states (id, run_id, state, data_json, created_at, updated_at)
+             VALUES (?, ?, ?, ?, ?, ?)`,
+            `${runId}:state:${state}:${crypto.randomUUID()}`,
+            runId,
+            state,
+            JSON.stringify(data),
+            now,
+            now,
+        );
+    }
+
+    /** Load a single run by id. */
+    async loadRun(runId: string): Promise<WorkflowRunRecord | undefined> {
+        await applyWorkflowEngineSchema(this.db);
+        const row = await this.db.queryFirst<WorkflowRunRecord>('SELECT * FROM runs WHERE id = ?', runId);
+        return row ?? undefined;
+    }
+
+    /** List persisted workflow runs. */
+    async listRuns(): Promise<readonly WorkflowRunRecord[]> {
+        await applyWorkflowEngineSchema(this.db);
+        return await this.db.queryAll<WorkflowRunRecord>('SELECT * FROM runs ORDER BY started_at DESC');
+    }
+}
+
+/** In-memory persistence adapter for tests and embedding. */
+export class MemoryWorkflowPersistenceAdapter implements WorkflowPersistenceAdapter {
+    readonly runs = new Map<string, WorkflowRunRecord>();
+    readonly phases: Array<{ runId: string; phase: string; status: WorkflowStatus }> = [];
+    readonly transitions: Array<{ runId: string; from: string; to: string; trigger: string | null }> = [];
+    readonly states: Array<{ runId: string; state: string; data: Record<string, unknown> }> = [];
+
+    /** Create a run row, rejecting duplicate run ids. */
+    async createRun(record: WorkflowRunRecord): Promise<void> {
+        if (this.runs.has(record.id)) throw new RunCollisionError(record.id);
+        this.runs.set(record.id, record);
+    }
+
+    /** Finalize a run with terminal status and timestamp. */
+    async finalizeRun(runId: string, status: WorkflowStatus, completedAt: string): Promise<void> {
+        const run = this.runs.get(runId);
+        if (run !== undefined) this.runs.set(runId, { ...run, status, completed_at: completedAt });
+    }
+
+    /** Save one phase/state execution record. */
+    async savePhase(runId: string, phase: string, status: WorkflowStatus): Promise<void> {
+        this.phases.push({ runId, phase, status });
+    }
+
+    /** Save one transition record. */
+    async saveTransition(runId: string, from: string, to: string, trigger: string | null): Promise<void> {
+        this.transitions.push({ runId, from, to, trigger });
+    }
+
+    /** Save the latest workflow state snapshot. */
+    async saveWorkflowState(runId: string, state: string, data: Record<string, unknown>): Promise<void> {
+        this.states.push({ runId, state, data });
+    }
+
+    /** Load a single run by id. */
+    async loadRun(runId: string): Promise<WorkflowRunRecord | undefined> {
+        return this.runs.get(runId);
+    }
+
+    /** List persisted workflow runs. */
+    async listRuns(): Promise<readonly WorkflowRunRecord[]> {
+        return [...this.runs.values()];
+    }
+}

package/src/schema-sql.ts

@@ -0,0 +1,48 @@
+export const WORKFLOW_ENGINE_SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS runs (
+    id TEXT PRIMARY KEY,
+    workflow_name TEXT,
+    mode TEXT,
+    status TEXT NOT NULL,
+    agent TEXT,
+    started_at TEXT NOT NULL,
+    completed_at TEXT,
+    metadata_json TEXT NOT NULL DEFAULT '{}',
+    created_at INTEGER NOT NULL DEFAULT 0,
+    updated_at INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS phase_runs (
+    id TEXT PRIMARY KEY,
+    run_id TEXT NOT NULL,
+    phase TEXT NOT NULL,
+    status TEXT NOT NULL,
+    started_at TEXT,
+    completed_at TEXT,
+    created_at INTEGER NOT NULL DEFAULT 0,
+    updated_at INTEGER NOT NULL DEFAULT 0,
+    FOREIGN KEY (run_id) REFERENCES runs(id)
+);
+
+CREATE TABLE IF NOT EXISTS transition_runs (
+    id TEXT PRIMARY KEY,
+    run_id TEXT NOT NULL,
+    from_state TEXT NOT NULL,
+    to_state TEXT NOT NULL,
+    trigger TEXT,
+    status TEXT NOT NULL,
+    created_at INTEGER NOT NULL DEFAULT 0,
+    updated_at INTEGER NOT NULL DEFAULT 0,
+    FOREIGN KEY (run_id) REFERENCES runs(id)
+);
+
+CREATE TABLE IF NOT EXISTS workflow_states (
+    id TEXT PRIMARY KEY,
+    run_id TEXT NOT NULL,
+    state TEXT NOT NULL,
+    data_json TEXT NOT NULL,
+    created_at INTEGER NOT NULL DEFAULT 0,
+    updated_at INTEGER NOT NULL DEFAULT 0,
+    FOREIGN KEY (run_id) REFERENCES runs(id)
+);
+`.trim();

package/src/schema.ts

@@ -0,0 +1,67 @@
+import { z } from 'zod';
+
+/** Zod schema for workflow action definitions. */
+export const ActionDefSchema = z.object({
+    kind: z.string().min(1),
+    options: z.record(z.string(), z.unknown()).optional(),
+});
+
+/** Zod schema for workflow guard definitions. */
+export const GuardDefSchema = z.object({
+    kind: z.string().min(1),
+    options: z.record(z.string(), z.unknown()).optional(),
+});
+
+/** Zod schema for state-machine workflow definitions. */
+export const StateMachineWorkflowDefSchema = z.object({
+    kind: z.literal('state-machine').optional(),
+    name: z.string().min(1),
+    initialState: z.string().min(1),
+    terminalStates: z.array(z.string().min(1)).optional(),
+    iterationBound: z.number().int().positive().optional(),
+    vars: z.record(z.string(), z.string()).optional(),
+    env: z.object({ allow: z.array(z.string()).optional() }).optional(),
+    states: z.array(
+        z.object({
+            id: z.string().min(1),
+            onEnter: z.array(ActionDefSchema).optional(),
+            onExit: z.array(ActionDefSchema).optional(),
+        }),
+    ),
+    transitions: z.array(
+        z.object({
+            from: z.string().min(1),
+            to: z.string().min(1),
+            trigger: z.string().optional(),
+            guard: GuardDefSchema.optional(),
+        }),
+    ),
+});
+
+/** Zod schema for transition-flow workflow definitions. */
+export const TransitionFlowWorkflowDefSchema = z.object({
+    kind: z.literal('transition-flow'),
+    name: z.string().min(1),
+    initialNode: z.string().min(1),
+    terminalNodes: z.array(z.string().min(1)).optional(),
+    iterationBound: z.number().int().positive().optional(),
+    vars: z.record(z.string(), z.string()).optional(),
+    env: z.object({ allow: z.array(z.string()).optional() }).optional(),
+    nodes: z.array(
+        z.object({
+            id: z.string().min(1),
+            type: z.enum(['action', 'gate', 'parallel', 'decision']).optional(),
+            action: ActionDefSchema.optional(),
+        }),
+    ),
+    edges: z.array(
+        z.object({
+            from: z.string().min(1),
+            to: z.string().min(1),
+            condition: GuardDefSchema.optional(),
+        }),
+    ),
+});
+
+/** Zod schema for either supported workflow definition shape. */
+export const WorkflowDefSchema = z.union([StateMachineWorkflowDefSchema, TransitionFlowWorkflowDefSchema]);

package/src/service.ts

@@ -0,0 +1,39 @@
+import { loadWorkflowDef } from './config';
+import type { WorkflowEngineHost } from './host';
+import { StateMachineDriver } from './state-machine';
+import { TransitionFlowDriver } from './transition-flow';
+import type { WorkflowDef, WorkflowPersistenceAdapter, WorkflowRunOptions, WorkflowRunResult } from './types';
+
+/** High-level workflow service for loading, running, and listing persisted workflow runs. */
+export class WorkflowService {
+    constructor(
+        private readonly host: WorkflowEngineHost,
+        private readonly persistence: WorkflowPersistenceAdapter,
+    ) {}
+
+    /** Load a workflow file and validate it. */
+    async load(path: string): Promise<WorkflowDef> {
+        return await loadWorkflowDef(path);
+    }
+
+    /** Run an already-loaded workflow definition. */
+    async run(workflow: WorkflowDef, options: WorkflowRunOptions = {}): Promise<WorkflowRunResult> {
+        if (workflow.kind === 'transition-flow') {
+            return await new TransitionFlowDriver({ host: this.host, persistence: this.persistence }).run(
+                workflow,
+                options,
+            );
+        }
+        return await new StateMachineDriver({ host: this.host, persistence: this.persistence }).run(workflow, options);
+    }
+
+    /** Load and run a workflow file. */
+    async runFile(path: string, options: WorkflowRunOptions = {}): Promise<WorkflowRunResult> {
+        return await this.run(await this.load(path), options);
+    }
+
+    /** List persisted workflow runs. */
+    async listRuns() {
+        return await this.persistence.listRuns();
+    }
+}