@sapiom/orchestration-core 0.1.1

package/dist/cjs/link.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.link = link;
+const errors_js_1 = require("./errors.js");
+async function link(opts, client) {
+    const list = await client.get('/definitions');
+    let def = list.find((d) => d.name === opts.name || d.slug === opts.name);
+    if (!def) {
+        if (!opts.create) {
+            throw new errors_js_1.OrchestrationError({
+                code: 'NOT_FOUND',
+                message: `No orchestration named '${opts.name}'.`,
+                hint: 'Create it with { create: true }, or pass the name of an existing one.',
+            });
+        }
+        def = await client.post('/definitions', { name: opts.name });
+    }
+    return { definitionId: def.id, name: def.name };
+}

package/dist/cjs/local/dispatcher.d.ts

@@ -0,0 +1,35 @@
+import { type NextStepDirective, type OrchestrationDefinition } from '@sapiom/orchestration';
+import { type StepDispatcher, type StepDispatchRequest, type WorkflowRunnerCore } from '@sapiom/orchestration-runtime';
+import type { StubFile } from './stubs.js';
+export interface LogEntry {
+    level: 'info' | 'warn' | 'error' | 'debug';
+    msg: string;
+    meta?: Record<string, unknown>;
+}
+export interface LocalStepTrace {
+    step: string;
+    attempt: number;
+    input: unknown;
+    status: 'succeeded' | 'threw';
+    output?: unknown;
+    directive?: NextStepDirective;
+    error?: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    logs: LogEntry[];
+}
+export declare class LocalStubDispatcher implements StepDispatcher {
+    private readonly definition;
+    private readonly stubs;
+    private core;
+    private maxAttemptsPerStep;
+    private signals;
+    readonly trace: LocalStepTrace[];
+    constructor(definition: OrchestrationDefinition, stubs: StubFile);
+    setCore(core: WorkflowRunnerCore): void;
+    setMaxAttempts(max: number): void;
+    setSignals(signals: Map<string, unknown>): void;
+    dispatch(request: StepDispatchRequest): Promise<void>;
+}

package/dist/cjs/local/dispatcher.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalStubDispatcher = void 0;
+const orchestration_1 = require("@sapiom/orchestration");
+const orchestration_runtime_1 = require("@sapiom/orchestration-runtime");
+const stub_1 = require("@sapiom/tools/stub");
+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 = (0, orchestration_runtime_1.parseCorrelationId)(request.correlationId);
+        if (!parsed)
+            throw new Error(`LocalStubDispatcher: malformed correlationId '${request.correlationId}'`);
+        const logs = [];
+        const sharedStore = new orchestration_1.InMemoryContextStore(request.shared);
+        const overrides = (this.stubs.steps[request.stepName] ?? {});
+        const sapiom = (0, stub_1.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: orchestration_runtime_1.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: orchestration_runtime_1.STEP_COMPLETION_OUTCOME.RESULT,
+            result: { output, directive: wire },
+            shared: sharedStore.snapshot(),
+        };
+        await this.core.completeDispatchedStep(payload, parsed, this.maxAttemptsPerStep);
+    }
+}
+exports.LocalStubDispatcher = LocalStubDispatcher;
+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/cjs/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/cjs/local/load.js

@@ -0,0 +1,102 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadDefinition = loadDefinition;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = __importDefault(require("node:path"));
+const orchestration_1 = require("@sapiom/orchestration");
+const esbuild = __importStar(require("esbuild"));
+const errors_js_1 = require("../errors.js");
+const LOCAL_SDK_VERSION = '0.0.0-local';
+async function loadDefinition(sourceDir) {
+    const entryFile = node_path_1.default.join(sourceDir, 'index.ts');
+    if (!(0, node_fs_1.existsSync)(entryFile)) {
+        throw new errors_js_1.OrchestrationError({
+            code: 'NO_ENTRY',
+            message: `No index.ts found in ${sourceDir}.`,
+            hint: 'Run this from an orchestration project, or pass its directory.',
+        });
+    }
+    const tmp = (0, node_fs_1.mkdtempSync)(node_path_1.default.join((0, node_os_1.tmpdir)(), 'sapiom-run-'));
+    const bundlePath = node_path_1.default.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 errors_js_1.OrchestrationError({
+                code: 'BUNDLE_FAILED',
+                message: 'Failed to bundle the orchestration.',
+                hint: err instanceof Error ? err.message : String(err),
+            });
+        }
+        const mod = await Promise.resolve(`${`file://${bundlePath}?t=${Date.now()}`}`).then(s => __importStar(require(s)));
+        const defs = Object.values(mod).filter(orchestration_1.isOrchestrationDefinition);
+        if (defs.length === 0) {
+            throw new errors_js_1.OrchestrationError({
+                code: 'NO_DEFINITION',
+                message: 'No orchestration was exported from index.ts.',
+                hint: 'Export the result of defineOrchestration({ … }).',
+            });
+        }
+        if (defs.length > 1) {
+            throw new errors_js_1.OrchestrationError({
+                code: 'MULTIPLE_DEFINITIONS',
+                message: 'index.ts exports more than one orchestration.',
+                hint: 'Export exactly one defineOrchestration({ … }) result.',
+            });
+        }
+        const definition = defs[0];
+        const sha256 = (0, node_crypto_1.createHash)('sha256').update((0, node_fs_1.readFileSync)(bundlePath)).digest('hex');
+        const manifest = orchestration_1.workflowManifestSchema.parse((0, orchestration_1.buildManifest)(definition, { sdkVersion: LOCAL_SDK_VERSION, artifact: { sha256, entryFile: 'definition.mjs' } }));
+        return { definition, manifest };
+    }
+    finally {
+        (0, node_fs_1.rmSync)(tmp, { recursive: true, force: true });
+    }
+}

package/dist/cjs/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/cjs/local/run-local.js

@@ -0,0 +1,73 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STUBS_FILE = void 0;
+exports.runLocal = runLocal;
+exports.runLocalFromDir = runLocalFromDir;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const orchestration_runtime_1 = require("@sapiom/orchestration-runtime");
+const errors_js_1 = require("../errors.js");
+const dispatcher_js_1 = require("./dispatcher.js");
+const load_js_1 = require("./load.js");
+const stubs_js_1 = require("./stubs.js");
+exports.STUBS_FILE = node_path_1.default.join('.sapiom-dev', 'stubs.json');
+function loadStubsFile(sourceDir) {
+    const file = node_path_1.default.join(sourceDir, exports.STUBS_FILE);
+    if (!(0, node_fs_1.existsSync)(file))
+        return undefined;
+    let raw;
+    try {
+        raw = JSON.parse((0, node_fs_1.readFileSync)(file, 'utf8'));
+    }
+    catch (err) {
+        throw new errors_js_1.OrchestrationError({
+            code: 'STUBS_INVALID',
+            message: `${exports.STUBS_FILE} is not valid JSON.`,
+            hint: err instanceof Error ? err.message : String(err),
+        });
+    }
+    return (0, stubs_js_1.parseStubFile)(raw);
+}
+const MAX_ADVANCES = 1000;
+async function runLocal(opts) {
+    const stubs = opts.stubs ?? { version: 1, steps: {} };
+    const max = opts.maxAttemptsPerStep ?? orchestration_runtime_1.DEFAULT_MAX_ATTEMPTS_PER_STEP;
+    const store = new orchestration_runtime_1.InMemoryExecutionStore();
+    const dispatcher = new dispatcher_js_1.LocalStubDispatcher(opts.definition, stubs);
+    const signals = new Map();
+    dispatcher.setSignals(signals);
+    const core = new orchestration_runtime_1.WorkflowRunnerCore({ store, dispatcher, observer: orchestration_runtime_1.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,
+    };
+}
+async function runLocalFromDir(opts) {
+    const { definition, manifest } = await (0, load_js_1.loadDefinition)(opts.sourceDir);
+    const stubs = opts.stubs ?? loadStubsFile(opts.sourceDir);
+    return runLocal({ definition, manifest, input: opts.input, stubs, maxAttemptsPerStep: opts.maxAttemptsPerStep });
+}

package/dist/cjs/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/cjs/local/stubs.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STUB_FILE_VERSION = void 0;
+exports.parseStubFile = parseStubFile;
+const errors_js_1 = require("../errors.js");
+exports.STUB_FILE_VERSION = 1;
+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 ?? exports.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 errors_js_1.OrchestrationError({
+        code: 'STUBS_INVALID',
+        message: `Invalid stub file: ${detail}`,
+        hint: 'Expected { "version": 1, "steps": { "<step>": { "<capability.path>": <response> | [<response>] } } }.',
+    });
+}

package/dist/cjs/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/cjs/run.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.run = run;
+exports.parseJsonInput = parseJsonInput;
+const errors_js_1 = require("./errors.js");
+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 errors_js_1.OrchestrationError({
+            code: 'RUN_NO_ID',
+            message: 'The execution was started but no execution id was returned.',
+        });
+    }
+    return { executionId, raw: res };
+}
+function parseJsonInput(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new errors_js_1.OrchestrationError({
+            code: 'BAD_INPUT',
+            message: 'Input is not valid JSON.',
+            hint: 'Pass a valid JSON string, e.g. \'{"key":"value"}\'',
+        });
+    }
+}

package/dist/cjs/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/cjs/scaffold.js

@@ -0,0 +1,145 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_TEMPLATE = void 0;
+exports.resolveVersions = resolveVersions;
+exports.listTemplates = listTemplates;
+exports.resolveTemplate = resolveTemplate;
+exports.scaffold = scaffold;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const node_url_1 = require("node:url");
+const errors_js_1 = require("./errors.js");
+function resolveModuleDir() {
+    if (typeof __dirname !== 'undefined')
+        return __dirname;
+    try {
+        const metaUrl = eval('import.meta.url');
+        if (typeof metaUrl === 'string')
+            return node_path_1.default.dirname((0, node_url_1.fileURLToPath)(metaUrl));
+    }
+    catch {
+    }
+    return '';
+}
+const moduleDir = resolveModuleDir();
+function getTemplatesDir(override) {
+    return override ?? process.env.SAPIOM_TEMPLATES_DIR ?? node_path_1.default.resolve(moduleDir, '..', '..', 'templates');
+}
+exports.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;
+    }
+}
+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,
+    };
+}
+function listTemplates(templatesDir) {
+    const root = getTemplatesDir(templatesDir);
+    if (!(0, node_fs_1.existsSync)(root))
+        return [];
+    return (0, node_fs_1.readdirSync)(root).filter((name) => (0, node_fs_1.statSync)(node_path_1.default.join(root, name)).isDirectory());
+}
+function resolveTemplate(name, templatesDir) {
+    const dir = node_path_1.default.join(getTemplatesDir(templatesDir), name);
+    if (!(0, node_fs_1.existsSync)(dir) || !(0, node_fs_1.statSync)(dir).isDirectory()) {
+        const available = listTemplates(templatesDir);
+        throw new errors_js_1.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 = (0, node_fs_1.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)
+        (0, node_fs_1.writeFileSync)(file, content);
+}
+function walk(dir, onFile) {
+    for (const entry of (0, node_fs_1.readdirSync)(dir)) {
+        const full = node_path_1.default.join(dir, entry);
+        if ((0, node_fs_1.statSync)(full).isDirectory())
+            walk(full, onFile);
+        else
+            onFile(full);
+    }
+}
+function copyTemplate(templateDir, targetDir, replacements) {
+    (0, node_fs_1.cpSync)(templateDir, targetDir, { recursive: true });
+    walk(targetDir, (file) => {
+        const base = node_path_1.default.basename(file);
+        if (DOTFILE_NAMES.has(base)) {
+            const dotted = node_path_1.default.join(node_path_1.default.dirname(file), '.' + base.slice(1));
+            (0, node_fs_1.renameSync)(file, dotted);
+            applyReplacements(dotted, replacements);
+            return;
+        }
+        applyReplacements(file, replacements);
+    });
+}
+async function scaffold(opts) {
+    const { targetDir } = opts;
+    const template = opts.template ?? exports.DEFAULT_TEMPLATE;
+    const projectName = opts.projectName ?? node_path_1.default.basename(targetDir);
+    if ((0, node_fs_1.existsSync)(targetDir) && (0, node_fs_1.readdirSync)(targetDir).length > 0) {
+        throw new errors_js_1.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());
+    (0, node_fs_1.mkdirSync)(targetDir, { recursive: true });
+    copyTemplate(templateDir, targetDir, {
+        __PROJECT_NAME__: projectName,
+        __ORCHESTRATION_VERSION__: versions.orchestration,
+        __TOOLS_VERSION__: versions.tools,
+        __ZOD_VERSION__: versions.zod,
+    });
+    const devDir = node_path_1.default.join(targetDir, '.sapiom-dev');
+    (0, node_fs_1.mkdirSync)(devDir, { recursive: true });
+    (0, node_fs_1.writeFileSync)(node_path_1.default.join(devDir, 'stubs.json'), JSON.stringify({ version: 1, steps: {} }, null, 2) + '\n');
+    return { targetDir, template, projectName };
+}

package/dist/cjs/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/cjs/signal.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.signal = signal;
+exports.parseSignalPayload = parseSignalPayload;
+const errors_js_1 = require("./errors.js");
+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 };
+}
+function parseSignalPayload(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new errors_js_1.OrchestrationError({
+            code: 'BAD_PAYLOAD',
+            message: 'Signal payload is not valid JSON.',
+        });
+    }
+}