@sapiom/orchestration-core 0.1.1

package/dist/esm/local/dispatcher.js

@@ -0,0 +1,111 @@
+import { InMemoryContextStore, } from '@sapiom/orchestration';
+import { parseCorrelationId, STEP_COMPLETION_OUTCOME, } from '@sapiom/orchestration-runtime';
+import { createStubClient } from '@sapiom/tools/stub';
+export class LocalStubDispatcher {
+    constructor(definition, stubs) {
+        this.definition = definition;
+        this.stubs = stubs;
+        this.core = null;
+        this.signals = new Map();
+        this.trace = [];
+    }
+    setCore(core) {
+        this.core = core;
+    }
+    setMaxAttempts(max) {
+        this.maxAttemptsPerStep = max;
+    }
+    setSignals(signals) {
+        this.signals = signals;
+    }
+    async dispatch(request) {
+        if (!this.core)
+            throw new Error('LocalStubDispatcher: setCore() was not called');
+        const step = this.definition.steps[request.stepName];
+        if (!step)
+            throw new Error(`LocalStubDispatcher: no step '${request.stepName}' in the definition`);
+        const parsed = parseCorrelationId(request.correlationId);
+        if (!parsed)
+            throw new Error(`LocalStubDispatcher: malformed correlationId '${request.correlationId}'`);
+        const logs = [];
+        const sharedStore = new InMemoryContextStore(request.shared);
+        const overrides = (this.stubs.steps[request.stepName] ?? {});
+        const sapiom = createStubClient({ overrides, signals: this.signals });
+        const ctx = {
+            executionId: request.executionId,
+            workflowName: request.workflowName,
+            organizationId: request.organizationId,
+            tenantId: request.tenantId,
+            input: request.workflowInput,
+            shared: sharedStore,
+            history: [],
+            attempts: request.attempt,
+            logger: makeLogger(logs),
+            sapiom,
+        };
+        let directive;
+        try {
+            directive = await step.run(request.input, ctx);
+        }
+        catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err));
+            this.trace.push({
+                step: request.stepName,
+                attempt: request.attempt,
+                input: request.input,
+                status: 'threw',
+                error: { name: e.name, message: e.message, stack: e.stack },
+                logs,
+            });
+            await this.core.completeDispatchedStep({
+                protocol: 1,
+                correlationId: request.correlationId,
+                outcome: STEP_COMPLETION_OUTCOME.THREW,
+                error: { name: e.name, message: e.message, stack: e.stack },
+                shared: sharedStore.snapshot(),
+            }, parsed, this.maxAttemptsPerStep);
+            return;
+        }
+        const { output, wire } = splitDirective(directive);
+        this.trace.push({
+            step: request.stepName,
+            attempt: request.attempt,
+            input: request.input,
+            status: 'succeeded',
+            output,
+            directive,
+            logs,
+        });
+        const payload = {
+            protocol: 1,
+            correlationId: request.correlationId,
+            outcome: STEP_COMPLETION_OUTCOME.RESULT,
+            result: { output, directive: wire },
+            shared: sharedStore.snapshot(),
+        };
+        await this.core.completeDispatchedStep(payload, parsed, this.maxAttemptsPerStep);
+    }
+}
+function makeLogger(sink) {
+    const at = (level) => (msg, meta) => {
+        sink.push({ level, msg, ...(meta ? { meta } : {}) });
+    };
+    return { info: at('info'), warn: at('warn'), error: at('error'), debug: at('debug') };
+}
+function splitDirective(d) {
+    switch (d.kind) {
+        case 'continue':
+            return { output: d.input, wire: { kind: 'continue', stepName: d.stepName, input: d.input } };
+        case 'terminate':
+            return { output: d.output, wire: { kind: 'terminate', reason: d.reason } };
+        case 'fail':
+            return { output: d.output, wire: { kind: 'fail', reason: d.reason } };
+        case 'pause_until_signal':
+            return {
+                output: d.output,
+                wire: { kind: 'pause_until_signal', signal: d.signal, timeoutMs: d.timeoutMs, resumeStep: d.resumeStep },
+            };
+        case 'retry':
+            return { output: undefined, wire: { kind: 'retry', delayMs: d.delayMs, reason: d.reason } };
+    }
+}

package/dist/esm/local/load.d.ts

@@ -0,0 +1,6 @@
+import { type OrchestrationDefinition, type WorkflowManifest } from '@sapiom/orchestration';
+export interface LoadedDefinition {
+    definition: OrchestrationDefinition;
+    manifest: WorkflowManifest;
+}
+export declare function loadDefinition(sourceDir: string): Promise<LoadedDefinition>;

package/dist/esm/local/load.js

@@ -0,0 +1,63 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { buildManifest, isOrchestrationDefinition, workflowManifestSchema, } from '@sapiom/orchestration';
+import * as esbuild from 'esbuild';
+import { OrchestrationError } from '../errors.js';
+const LOCAL_SDK_VERSION = '0.0.0-local';
+export async function loadDefinition(sourceDir) {
+    const entryFile = path.join(sourceDir, 'index.ts');
+    if (!existsSync(entryFile)) {
+        throw new OrchestrationError({
+            code: 'NO_ENTRY',
+            message: `No index.ts found in ${sourceDir}.`,
+            hint: 'Run this from an orchestration project, or pass its directory.',
+        });
+    }
+    const tmp = mkdtempSync(path.join(tmpdir(), 'sapiom-run-'));
+    const bundlePath = path.join(tmp, 'definition.mjs');
+    try {
+        try {
+            await esbuild.build({
+                entryPoints: [entryFile],
+                outfile: bundlePath,
+                bundle: true,
+                platform: 'node',
+                target: 'node20',
+                format: 'esm',
+                logLevel: 'silent',
+            });
+        }
+        catch (err) {
+            throw new OrchestrationError({
+                code: 'BUNDLE_FAILED',
+                message: 'Failed to bundle the orchestration.',
+                hint: err instanceof Error ? err.message : String(err),
+            });
+        }
+        const mod = await import(`file://${bundlePath}?t=${Date.now()}`);
+        const defs = Object.values(mod).filter(isOrchestrationDefinition);
+        if (defs.length === 0) {
+            throw new OrchestrationError({
+                code: 'NO_DEFINITION',
+                message: 'No orchestration was exported from index.ts.',
+                hint: 'Export the result of defineOrchestration({ … }).',
+            });
+        }
+        if (defs.length > 1) {
+            throw new OrchestrationError({
+                code: 'MULTIPLE_DEFINITIONS',
+                message: 'index.ts exports more than one orchestration.',
+                hint: 'Export exactly one defineOrchestration({ … }) result.',
+            });
+        }
+        const definition = defs[0];
+        const sha256 = createHash('sha256').update(readFileSync(bundlePath)).digest('hex');
+        const manifest = workflowManifestSchema.parse(buildManifest(definition, { sdkVersion: LOCAL_SDK_VERSION, artifact: { sha256, entryFile: 'definition.mjs' } }));
+        return { definition, manifest };
+    }
+    finally {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+}

package/dist/esm/local/run-local.d.ts

@@ -0,0 +1,26 @@
+import type { OrchestrationDefinition, WorkflowManifest } from '@sapiom/orchestration';
+import { type LocalStepTrace } from './dispatcher.js';
+import { type StubFile } from './stubs.js';
+export declare const STUBS_FILE: string;
+export interface RunLocalOptions {
+    definition: OrchestrationDefinition;
+    manifest: WorkflowManifest;
+    input?: unknown;
+    stubs?: StubFile;
+    maxAttemptsPerStep?: number;
+}
+export type LocalRunOutcome = 'completed' | 'failed' | 'paused' | 'running';
+export interface LocalRunResult {
+    outcome: LocalRunOutcome;
+    executionId: string;
+    output?: unknown;
+    error?: unknown;
+    steps: LocalStepTrace[];
+}
+export declare function runLocal(opts: RunLocalOptions): Promise<LocalRunResult>;
+export declare function runLocalFromDir(opts: {
+    sourceDir: string;
+    input?: unknown;
+    stubs?: StubFile;
+    maxAttemptsPerStep?: number;
+}): Promise<LocalRunResult>;

package/dist/esm/local/run-local.js

@@ -0,0 +1,65 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { DEFAULT_MAX_ATTEMPTS_PER_STEP, InMemoryExecutionStore, NOOP_OBSERVER, WorkflowRunnerCore, } from '@sapiom/orchestration-runtime';
+import { OrchestrationError } from '../errors.js';
+import { LocalStubDispatcher } from './dispatcher.js';
+import { loadDefinition } from './load.js';
+import { parseStubFile } from './stubs.js';
+export const STUBS_FILE = path.join('.sapiom-dev', 'stubs.json');
+function loadStubsFile(sourceDir) {
+    const file = path.join(sourceDir, STUBS_FILE);
+    if (!existsSync(file))
+        return undefined;
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (err) {
+        throw new OrchestrationError({
+            code: 'STUBS_INVALID',
+            message: `${STUBS_FILE} is not valid JSON.`,
+            hint: err instanceof Error ? err.message : String(err),
+        });
+    }
+    return parseStubFile(raw);
+}
+const MAX_ADVANCES = 1000;
+export async function runLocal(opts) {
+    const stubs = opts.stubs ?? { version: 1, steps: {} };
+    const max = opts.maxAttemptsPerStep ?? DEFAULT_MAX_ATTEMPTS_PER_STEP;
+    const store = new InMemoryExecutionStore();
+    const dispatcher = new LocalStubDispatcher(opts.definition, stubs);
+    const signals = new Map();
+    dispatcher.setSignals(signals);
+    const core = new WorkflowRunnerCore({ store, dispatcher, observer: NOOP_OBSERVER });
+    dispatcher.setCore(core);
+    dispatcher.setMaxAttempts(max);
+    const executionId = await core.createExecution(opts.definition.name, opts.definition.entry, opts.input, {
+        manifest: opts.manifest,
+    });
+    let guard = 0;
+    while (guard++ < MAX_ADVANCES) {
+        await core.advance(executionId, max);
+        const row = await store.loadExecution(executionId);
+        if (!row || row.status === 'completed' || row.status === 'failed' || row.status === 'cancelled')
+            break;
+        if (row.status === 'paused') {
+            const payload = signals.get(row.pausedSignalCorrelationId ?? '') ?? {};
+            await core.resetForResume(executionId, { fromStepInput: payload });
+        }
+    }
+    const final = await store.loadExecution(executionId);
+    const outcome = final?.status === 'cancelled' ? 'failed' : (final?.status ?? 'running');
+    return {
+        outcome,
+        executionId,
+        output: final?.output,
+        error: final?.error,
+        steps: dispatcher.trace,
+    };
+}
+export async function runLocalFromDir(opts) {
+    const { definition, manifest } = await loadDefinition(opts.sourceDir);
+    const stubs = opts.stubs ?? loadStubsFile(opts.sourceDir);
+    return runLocal({ definition, manifest, input: opts.input, stubs, maxAttemptsPerStep: opts.maxAttemptsPerStep });
+}

package/dist/esm/local/stubs.d.ts

@@ -0,0 +1,8 @@
+export declare const STUB_FILE_VERSION = 1;
+export type StubResponse = unknown;
+export type StepStubs = Record<string, StubResponse | StubResponse[]>;
+export interface StubFile {
+    version: number;
+    steps: Record<string, StepStubs>;
+}
+export declare function parseStubFile(raw: unknown): StubFile;

package/dist/esm/local/stubs.js

@@ -0,0 +1,31 @@
+import { OrchestrationError } from '../errors.js';
+export const STUB_FILE_VERSION = 1;
+export function parseStubFile(raw) {
+    if (raw == null || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw invalid('the stub file must be a JSON object.');
+    }
+    const obj = raw;
+    const version = obj.version ?? STUB_FILE_VERSION;
+    if (typeof version !== 'number') {
+        throw invalid('`version` must be a number.');
+    }
+    const stepsRaw = obj.steps ?? {};
+    if (stepsRaw == null || typeof stepsRaw !== 'object' || Array.isArray(stepsRaw)) {
+        throw invalid('`steps` must be an object keyed by step name.');
+    }
+    const steps = {};
+    for (const [stepName, stepStubs] of Object.entries(stepsRaw)) {
+        if (stepStubs == null || typeof stepStubs !== 'object' || Array.isArray(stepStubs)) {
+            throw invalid(`steps.${stepName} must be an object keyed by capability path.`);
+        }
+        steps[stepName] = stepStubs;
+    }
+    return { version, steps };
+}
+function invalid(detail) {
+    return new OrchestrationError({
+        code: 'STUBS_INVALID',
+        message: `Invalid stub file: ${detail}`,
+        hint: 'Expected { "version": 1, "steps": { "<step>": { "<capability.path>": <response> | [<response>] } } }.',
+    });
+}

package/dist/esm/package.json

@@ -0,0 +1 @@
+{"type": "module"}

package/dist/esm/run.d.ts

@@ -0,0 +1,11 @@
+import { GatewayClient } from './client.js';
+export interface RunOptions {
+    definitionId: string;
+    input?: unknown;
+}
+export interface RunResult {
+    executionId: string;
+    raw: Record<string, unknown>;
+}
+export declare function run(opts: RunOptions, client: GatewayClient): Promise<RunResult>;
+export declare function parseJsonInput(raw: string): unknown;

package/dist/esm/run.js

@@ -0,0 +1,25 @@
+import { OrchestrationError } from './errors.js';
+export async function run(opts, client) {
+    const { definitionId, input = {} } = opts;
+    const res = await client.post('/executions', { definitionId, input });
+    const executionId = res.executionId ?? res.id;
+    if (!executionId) {
+        throw new OrchestrationError({
+            code: 'RUN_NO_ID',
+            message: 'The execution was started but no execution id was returned.',
+        });
+    }
+    return { executionId, raw: res };
+}
+export function parseJsonInput(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new OrchestrationError({
+            code: 'BAD_INPUT',
+            message: 'Input is not valid JSON.',
+            hint: 'Pass a valid JSON string, e.g. \'{"key":"value"}\'',
+        });
+    }
+}

package/dist/esm/scaffold.d.ts

@@ -0,0 +1,22 @@
+export declare const DEFAULT_TEMPLATE = "default";
+export interface ResolvedVersions {
+    orchestration: string;
+    tools: string;
+    zod: string;
+}
+export declare function resolveVersions(): Promise<ResolvedVersions>;
+export declare function listTemplates(templatesDir?: string): string[];
+export declare function resolveTemplate(name: string, templatesDir?: string): string;
+export interface ScaffoldOptions {
+    targetDir: string;
+    template?: string;
+    projectName?: string;
+    templatesDir?: string;
+    versions?: ResolvedVersions;
+}
+export interface ScaffoldResult {
+    targetDir: string;
+    template: string;
+    projectName: string;
+}
+export declare function scaffold(opts: ScaffoldOptions): Promise<ScaffoldResult>;

package/dist/esm/scaffold.js

@@ -0,0 +1,135 @@
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { OrchestrationError } from './errors.js';
+function resolveModuleDir() {
+    if (typeof __dirname !== 'undefined')
+        return __dirname;
+    try {
+        const metaUrl = eval('import.meta.url');
+        if (typeof metaUrl === 'string')
+            return path.dirname(fileURLToPath(metaUrl));
+    }
+    catch {
+    }
+    return '';
+}
+const moduleDir = resolveModuleDir();
+function getTemplatesDir(override) {
+    return override ?? process.env.SAPIOM_TEMPLATES_DIR ?? path.resolve(moduleDir, '..', '..', 'templates');
+}
+export const DEFAULT_TEMPLATE = 'default';
+const DOTFILE_NAMES = new Set(['_gitignore', '_npmrc']);
+const REGISTRY = 'https://registry.npmjs.org';
+const VERSION_FALLBACK = {
+    orchestration: '0.1.1',
+    tools: '0.1.1',
+};
+const ZOD_VERSION = '3.25.76';
+async function latestNpmVersion(pkg) {
+    try {
+        const res = await fetch(`${REGISTRY}/${encodeURIComponent(pkg)}/latest`, {
+            signal: AbortSignal.timeout(5000),
+        });
+        if (!res.ok)
+            return null;
+        const json = (await res.json());
+        return typeof json.version === 'string' ? json.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function resolveVersions() {
+    const [orchestration, tools] = await Promise.all([
+        latestNpmVersion('@sapiom/orchestration'),
+        latestNpmVersion('@sapiom/tools'),
+    ]);
+    return {
+        orchestration: orchestration ?? VERSION_FALLBACK.orchestration,
+        tools: tools ?? VERSION_FALLBACK.tools,
+        zod: ZOD_VERSION,
+    };
+}
+export function listTemplates(templatesDir) {
+    const root = getTemplatesDir(templatesDir);
+    if (!existsSync(root))
+        return [];
+    return readdirSync(root).filter((name) => statSync(path.join(root, name)).isDirectory());
+}
+export function resolveTemplate(name, templatesDir) {
+    const dir = path.join(getTemplatesDir(templatesDir), name);
+    if (!existsSync(dir) || !statSync(dir).isDirectory()) {
+        const available = listTemplates(templatesDir);
+        throw new OrchestrationError({
+            code: 'UNKNOWN_TEMPLATE',
+            message: `Unknown template '${name}'.` +
+                (available.length ? ` Available: ${available.join(', ')}.` : ' No templates are bundled.'),
+        });
+    }
+    return dir;
+}
+function applyReplacements(file, replacements) {
+    let content;
+    try {
+        content = readFileSync(file, 'utf8');
+    }
+    catch {
+        return;
+    }
+    let changed = false;
+    for (const [token, value] of Object.entries(replacements)) {
+        if (content.includes(token)) {
+            content = content.split(token).join(value);
+            changed = true;
+        }
+    }
+    if (changed)
+        writeFileSync(file, content);
+}
+function walk(dir, onFile) {
+    for (const entry of readdirSync(dir)) {
+        const full = path.join(dir, entry);
+        if (statSync(full).isDirectory())
+            walk(full, onFile);
+        else
+            onFile(full);
+    }
+}
+function copyTemplate(templateDir, targetDir, replacements) {
+    cpSync(templateDir, targetDir, { recursive: true });
+    walk(targetDir, (file) => {
+        const base = path.basename(file);
+        if (DOTFILE_NAMES.has(base)) {
+            const dotted = path.join(path.dirname(file), '.' + base.slice(1));
+            renameSync(file, dotted);
+            applyReplacements(dotted, replacements);
+            return;
+        }
+        applyReplacements(file, replacements);
+    });
+}
+export async function scaffold(opts) {
+    const { targetDir } = opts;
+    const template = opts.template ?? DEFAULT_TEMPLATE;
+    const projectName = opts.projectName ?? path.basename(targetDir);
+    if (existsSync(targetDir) && readdirSync(targetDir).length > 0) {
+        throw new OrchestrationError({
+            code: 'DIR_NOT_EMPTY',
+            message: `Target directory '${targetDir}' already exists and is not empty.`,
+        });
+    }
+    const templateDir = resolveTemplate(template, opts.templatesDir);
+    const versions = opts.versions ?? (await resolveVersions());
+    mkdirSync(targetDir, { recursive: true });
+    copyTemplate(templateDir, targetDir, {
+        __PROJECT_NAME__: projectName,
+        __ORCHESTRATION_VERSION__: versions.orchestration,
+        __TOOLS_VERSION__: versions.tools,
+        __ZOD_VERSION__: versions.zod,
+    });
+    const devDir = path.join(targetDir, '.sapiom-dev');
+    mkdirSync(devDir, { recursive: true });
+    writeFileSync(path.join(devDir, 'stubs.json'), JSON.stringify({ version: 1, steps: {} }, null, 2) + '\n');
+    return { targetDir, template, projectName };
+}

package/dist/esm/signal.d.ts

@@ -0,0 +1,12 @@
+import { GatewayClient } from './client.js';
+export interface SignalOptions {
+    executionId: string;
+    name: string;
+    correlationId: string;
+    payload?: unknown;
+}
+export interface SignalResult {
+    matched: number;
+}
+export declare function signal(opts: SignalOptions, client: GatewayClient): Promise<SignalResult>;
+export declare function parseSignalPayload(raw: string): unknown;

package/dist/esm/signal.js

@@ -0,0 +1,20 @@
+import { OrchestrationError } from './errors.js';
+export async function signal(opts, client) {
+    const res = await client.post(`/executions/${opts.executionId}/signals`, {
+        name: opts.name,
+        correlationId: opts.correlationId,
+        payload: opts.payload,
+    });
+    return { matched: res.matched ?? 0 };
+}
+export function parseSignalPayload(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new OrchestrationError({
+            code: 'BAD_PAYLOAD',
+            message: 'Signal payload is not valid JSON.',
+        });
+    }
+}