@sapiom/orchestration-core 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # @sapiom/orchestration-core
 
+## 0.3.0
+
+### Minor Changes
+
+- e17b2d1: `scaffold` now initializes a git repository with an initial commit, so a freshly scaffolded project is immediately deployable (deploy requires a repo with at least one commit). Best-effort: if `git` is unavailable the project is left uninitialized. `ScaffoldResult` gains `gitInitialized`.
+
+  Adds `waitForExecution` (and `isExecutionTerminal`) to poll an execution until it reaches a terminal state, settles on a pause that needs a signal, or a wait budget elapses — so callers don't hand-roll a poll loop. The `sapiom_dev_orchestrations_inspect` MCP tool gains opt-in `wait` / `maxWaitSeconds` options that use it and return `done` / `waiting` / `hint`; a non-blocking inspect of a still-running execution now also hints to use `wait`.
+
+  Fixes `sapiom_dev_orchestrations_link`: omitting `name` no longer sends an empty name (which the gateway rejected). It now defaults to the orchestration's name read from `index.ts` (matching `defineOrchestration({ name })`), and returns a clear error if no name is available.
+
+### Patch Changes
+
+- e17b2d1: **BREAKING (`@sapiom/tools`):** align the coding-run resume payload with the shape a resumed step actually receives. `CodingResultPayload` now carries `executionEnvironment: { type, id } | null` instead of `sandbox: { name, workspaceRoot }`. Re-attach a resumed run's sandbox with `ctx.sapiom.sandboxes.attach(result.executionEnvironment.id)` (for a `blaxel_sandbox`).
+
+  Adds `codingResultSchema` (runtime validation of the resume payload), `toResumePayload`, `ExecutionEnvironmentRef`, and `EXECUTION_ENVIRONMENT_BLAXEL_SANDBOX`. The stub client now emits the same payload shape a resumed step receives, so a step written against the local loop runs identically once deployed.
+
+  The `coding-pause` template and its guidance are updated to the new shape.
+
+- Updated dependencies [e17b2d1]
+  - @sapiom/tools@0.4.0
+  - @sapiom/orchestration@0.1.8
+
+## 0.2.0
+
+### Minor Changes
+
+- 704c9ac: Make the local development loop (`run_local`) production-faithful and trustworthy for the dispatch/pause pattern (`agent.coding.launch` + `pauseUntilSignal`).
+
+  - Stub capability handles now survive JSON serialization, so a paused/resumed coding workflow runs end-to-end locally instead of failing with an opaque `'sandbox.toJSON' is not a method or field` error.
+  - The payload a paused step resumes with is delivered as plain JSON — the same shape production sends over the wire — so authors re-attach handles by name (`sandboxes.attach(...)`) locally exactly as they would in prod.
+  - `@sapiom/tools` exports `CodingResultPayload`: the shape a step resumed from `pauseUntilSignal(codingHandle, …)` receives, so resumed steps can be annotated instead of hand-rolling the type.
+  - Stubbing a handle-returning capability with plain JSON no longer strips the handle's instance methods (e.g. `repo.pushFromSandbox`), and `repositories.list` stubs are coerced and shape-checked.
+  - A dispatched `launch()` accepts the `agent.coding.launch` stub key as well as the shared `agent.coding.run` (ordered candidate resolution), so the stub key matching the call the author wrote takes effect.
+  - `run_local` now reports `unusedStubs` (a supplied key that matched no call) and `stubWarnings` (a key that matched but carried the wrong shape), surfacing stubs that silently didn't take effect; the MCP `run_local` also serializes its result defensively.
+  - New `coding-pause` scaffold template for the launch + pause + resume pattern, and AGENTS docs documenting the resume-input contract, list stub item shape, failure-branch stubbing, and step determinism under replay.
+
+### Patch Changes
+
+- Updated dependencies [704c9ac]
+  - @sapiom/tools@0.3.0
+  - @sapiom/orchestration@0.1.7
+
 ## 0.1.1
 
 ### Patch Changes

package/dist/cjs/index.d.ts

@@ -1,29 +1,29 @@
-export { OrchestrationError } from './errors.js';
-export type { StructuredError } from './errors.js';
-export { GatewayClient, createClient, DEFAULT_WORKFLOWS_HOST } from './client.js';
-export type { ClientOptions, GatewayErrorBody } from './client.js';
-export { readConfig, requireConfig, writeConfig, CONFIG_FILE } from './config.js';
-export type { SapiomConfig } from './config.js';
-export { scaffold, resolveVersions, resolveTemplate, listTemplates, DEFAULT_TEMPLATE } from './scaffold.js';
-export type { ScaffoldOptions, ScaffoldResult, ResolvedVersions } from './scaffold.js';
-export { check } from './check.js';
-export type { CheckOptions, CheckResult } from './check.js';
-export { link } from './link.js';
-export type { LinkOptions, LinkResult, DefinitionSummary } from './link.js';
-export { deploy } from './deploy.js';
-export type { DeployOptions, DeployResult } from './deploy.js';
-export { run, parseJsonInput } from './run.js';
-export type { RunOptions, RunResult } from './run.js';
-export { inspect, listExecutions, inspectBuild } from './inspect.js';
-export type { InspectOptions, InspectResult, ListExecutionsResult, InspectBuildOptions, InspectBuildResult, ExecutionDetail, StepRecord, BuildDetail, } from './inspect.js';
-export { signal, parseSignalPayload } from './signal.js';
-export type { SignalOptions, SignalResult } from './signal.js';
-export { assertDeployable, pushHead } from './git.js';
-export { parseStubFile, STUB_FILE_VERSION } from './local/stubs.js';
-export type { StubFile, StepStubs, StubResponse } from './local/stubs.js';
-export { runLocal, runLocalFromDir, STUBS_FILE } from './local/run-local.js';
-export type { RunLocalOptions, LocalRunResult, LocalRunOutcome } from './local/run-local.js';
-export { loadDefinition } from './local/load.js';
-export type { LoadedDefinition } from './local/load.js';
-export { LocalStubDispatcher } from './local/dispatcher.js';
-export type { LocalStepTrace, LogEntry } from './local/dispatcher.js';
+export { OrchestrationError } from "./errors.js";
+export type { StructuredError } from "./errors.js";
+export { GatewayClient, createClient, DEFAULT_WORKFLOWS_HOST, } from "./client.js";
+export type { ClientOptions, GatewayErrorBody } from "./client.js";
+export { readConfig, requireConfig, writeConfig, CONFIG_FILE, } from "./config.js";
+export type { SapiomConfig } from "./config.js";
+export { scaffold, resolveVersions, resolveTemplate, listTemplates, DEFAULT_TEMPLATE, } from "./scaffold.js";
+export type { ScaffoldOptions, ScaffoldResult, ResolvedVersions, } from "./scaffold.js";
+export { check } from "./check.js";
+export type { CheckOptions, CheckResult } from "./check.js";
+export { link } from "./link.js";
+export type { LinkOptions, LinkResult, DefinitionSummary } from "./link.js";
+export { deploy } from "./deploy.js";
+export type { DeployOptions, DeployResult } from "./deploy.js";
+export { run, parseJsonInput } from "./run.js";
+export type { RunOptions, RunResult } from "./run.js";
+export { inspect, listExecutions, inspectBuild, waitForExecution, isExecutionTerminal, } from "./inspect.js";
+export type { InspectOptions, InspectResult, ListExecutionsResult, InspectBuildOptions, InspectBuildResult, ExecutionDetail, StepRecord, BuildDetail, WaitForExecutionOptions, WaitForExecutionResult, WaitStopReason, } from "./inspect.js";
+export { signal, parseSignalPayload } from "./signal.js";
+export type { SignalOptions, SignalResult } from "./signal.js";
+export { assertDeployable, pushHead } from "./git.js";
+export { parseStubFile, STUB_FILE_VERSION } from "./local/stubs.js";
+export type { StubFile, StepStubs, StubResponse } from "./local/stubs.js";
+export { runLocal, runLocalFromDir, STUBS_FILE } from "./local/run-local.js";
+export type { RunLocalOptions, LocalRunResult, LocalRunOutcome, } from "./local/run-local.js";
+export { loadDefinition } from "./local/load.js";
+export type { LoadedDefinition } from "./local/load.js";
+export { LocalStubDispatcher } from "./local/dispatcher.js";
+export type { LocalStepTrace, LogEntry } from "./local/dispatcher.js";

package/dist/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LocalStubDispatcher = exports.loadDefinition = exports.STUBS_FILE = exports.runLocalFromDir = exports.runLocal = exports.STUB_FILE_VERSION = exports.parseStubFile = exports.pushHead = exports.assertDeployable = exports.parseSignalPayload = exports.signal = exports.inspectBuild = exports.listExecutions = exports.inspect = exports.parseJsonInput = exports.run = exports.deploy = exports.link = exports.check = exports.DEFAULT_TEMPLATE = exports.listTemplates = exports.resolveTemplate = exports.resolveVersions = exports.scaffold = exports.CONFIG_FILE = exports.writeConfig = exports.requireConfig = exports.readConfig = exports.DEFAULT_WORKFLOWS_HOST = exports.createClient = exports.GatewayClient = exports.OrchestrationError = void 0;
+exports.LocalStubDispatcher = exports.loadDefinition = exports.STUBS_FILE = exports.runLocalFromDir = exports.runLocal = exports.STUB_FILE_VERSION = exports.parseStubFile = exports.pushHead = exports.assertDeployable = exports.parseSignalPayload = exports.signal = exports.isExecutionTerminal = exports.waitForExecution = exports.inspectBuild = exports.listExecutions = exports.inspect = exports.parseJsonInput = exports.run = exports.deploy = exports.link = exports.check = exports.DEFAULT_TEMPLATE = exports.listTemplates = exports.resolveTemplate = exports.resolveVersions = exports.scaffold = exports.CONFIG_FILE = exports.writeConfig = exports.requireConfig = exports.readConfig = exports.DEFAULT_WORKFLOWS_HOST = exports.createClient = exports.GatewayClient = exports.OrchestrationError = void 0;
 var errors_js_1 = require("./errors.js");
 Object.defineProperty(exports, "OrchestrationError", { enumerable: true, get: function () { return errors_js_1.OrchestrationError; } });
 var client_js_1 = require("./client.js");
@@ -31,6 +31,8 @@ var inspect_js_1 = require("./inspect.js");
 Object.defineProperty(exports, "inspect", { enumerable: true, get: function () { return inspect_js_1.inspect; } });
 Object.defineProperty(exports, "listExecutions", { enumerable: true, get: function () { return inspect_js_1.listExecutions; } });
 Object.defineProperty(exports, "inspectBuild", { enumerable: true, get: function () { return inspect_js_1.inspectBuild; } });
+Object.defineProperty(exports, "waitForExecution", { enumerable: true, get: function () { return inspect_js_1.waitForExecution; } });
+Object.defineProperty(exports, "isExecutionTerminal", { enumerable: true, get: function () { return inspect_js_1.isExecutionTerminal; } });
 var signal_js_1 = require("./signal.js");
 Object.defineProperty(exports, "signal", { enumerable: true, get: function () { return signal_js_1.signal; } });
 Object.defineProperty(exports, "parseSignalPayload", { enumerable: true, get: function () { return signal_js_1.parseSignalPayload; } });

package/dist/cjs/inspect.d.ts

@@ -1,4 +1,4 @@
-import { GatewayClient } from './client.js';
+import { GatewayClient } from "./client.js";
 export interface StepRecord {
     stepName: string;
     attempt: number;
@@ -12,6 +12,7 @@ export interface ExecutionDetail {
     id: string;
     status: string;
     currentStep?: string | null;
+    pausedSignalName?: string | null;
     error?: unknown;
     steps?: StepRecord[];
 }
@@ -27,6 +28,22 @@ export interface InspectResult {
     execution: ExecutionDetail;
 }
 export declare function inspect(opts: InspectOptions, client: GatewayClient): Promise<InspectResult>;
+export declare function isExecutionTerminal(status: string): boolean;
+export type WaitStopReason = "terminal" | "needs-signal" | "timeout";
+export interface WaitForExecutionOptions {
+    executionId: string;
+    maxWaitMs?: number;
+    pollMs?: number;
+    autoResumeSignals?: string[];
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}
+export interface WaitForExecutionResult {
+    execution: ExecutionDetail;
+    reason: WaitStopReason;
+    done: boolean;
+}
+export declare function waitForExecution(opts: WaitForExecutionOptions, client: GatewayClient): Promise<WaitForExecutionResult>;
 export interface ListExecutionsResult {
     executions: ExecutionDetail[];
 }

package/dist/cjs/inspect.js

@@ -1,14 +1,52 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.inspect = inspect;
+exports.isExecutionTerminal = isExecutionTerminal;
+exports.waitForExecution = waitForExecution;
 exports.listExecutions = listExecutions;
 exports.inspectBuild = inspectBuild;
 async function inspect(opts, client) {
     const execution = await client.get(`/executions/${opts.executionId}`);
     return { execution };
 }
+const TERMINAL_STATUSES = new Set([
+    "completed",
+    "failed",
+    "cancelled",
+    "canceled",
+]);
+function isExecutionTerminal(status) {
+    return TERMINAL_STATUSES.has(status);
+}
+const AUTO_RESUME_PAUSE_SIGNALS = ["agent.coding.result"];
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function waitForExecution(opts, client) {
+    const maxWaitMs = opts.maxWaitMs ?? 45000;
+    const autoResume = opts.autoResumeSignals ?? AUTO_RESUME_PAUSE_SIGNALS;
+    const sleep = opts.sleep ?? defaultSleep;
+    const now = opts.now ?? Date.now;
+    const deadline = now() + maxWaitMs;
+    let interval = opts.pollMs ?? 1000;
+    for (;;) {
+        const { execution } = await inspect({ executionId: opts.executionId }, client);
+        if (isExecutionTerminal(execution.status)) {
+            return { execution, reason: "terminal", done: true };
+        }
+        if (execution.status === "paused") {
+            const signal = execution.pausedSignalName ?? null;
+            if (!signal || !autoResume.includes(signal)) {
+                return { execution, reason: "needs-signal", done: false };
+            }
+        }
+        const remaining = deadline - now();
+        if (remaining <= 0)
+            return { execution, reason: "timeout", done: false };
+        await sleep(Math.min(interval, remaining));
+        interval = Math.min(interval * 1.5, 5000);
+    }
+}
 async function listExecutions(client) {
-    const executions = await client.get('/executions');
+    const executions = await client.get("/executions");
     return { executions };
 }
 async function inspectBuild(opts, client) {

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

@@ -1,8 +1,8 @@
-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';
+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';
+    level: "info" | "warn" | "error" | "debug";
     msg: string;
     meta?: Record<string, unknown>;
 }
@@ -10,7 +10,7 @@ export interface LocalStepTrace {
     step: string;
     attempt: number;
     input: unknown;
-    status: 'succeeded' | 'threw';
+    status: "succeeded" | "threw";
     output?: unknown;
     directive?: NextStepDirective;
     error?: {
@@ -27,6 +27,8 @@ export declare class LocalStubDispatcher implements StepDispatcher {
     private maxAttemptsPerStep;
     private signals;
     readonly trace: LocalStepTrace[];
+    readonly usedKeysByStep: Map<string, Set<string>>;
+    readonly stubWarnings: Set<string>;
     constructor(definition: OrchestrationDefinition, stubs: StubFile);
     setCore(core: WorkflowRunnerCore): void;
     setMaxAttempts(max: number): void;

package/dist/cjs/local/dispatcher.js

@@ -11,6 +11,8 @@ class LocalStubDispatcher {
         this.core = null;
         this.signals = new Map();
         this.trace = [];
+        this.usedKeysByStep = new Map();
+        this.stubWarnings = new Set();
     }
     setCore(core) {
         this.core = core;
@@ -23,7 +25,7 @@ class LocalStubDispatcher {
     }
     async dispatch(request) {
         if (!this.core)
-            throw new Error('LocalStubDispatcher: setCore() was not called');
+            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`);
@@ -33,7 +35,17 @@ class LocalStubDispatcher {
         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 });
+        let usedKeys = this.usedKeysByStep.get(request.stepName);
+        if (!usedKeys) {
+            usedKeys = new Set();
+            this.usedKeysByStep.set(request.stepName, usedKeys);
+        }
+        const sapiom = (0, stub_1.createStubClient)({
+            overrides,
+            signals: this.signals,
+            usedKeys,
+            warnings: this.stubWarnings,
+        });
         const ctx = {
             executionId: request.executionId,
             workflowName: request.workflowName,
@@ -56,7 +68,7 @@ class LocalStubDispatcher {
                 step: request.stepName,
                 attempt: request.attempt,
                 input: request.input,
-                status: 'threw',
+                status: "threw",
                 error: { name: e.name, message: e.message, stack: e.stack },
                 logs,
             });
@@ -74,7 +86,7 @@ class LocalStubDispatcher {
             step: request.stepName,
             attempt: request.attempt,
             input: request.input,
-            status: 'succeeded',
+            status: "succeeded",
             output,
             directive,
             logs,
@@ -94,22 +106,44 @@ 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') };
+    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':
+        case "continue":
+            return {
+                output: d.input,
+                wire: { kind: "continue", stepName: d.stepName, input: d.input },
+            };
+        case "terminate":
             return {
                 output: d.output,
-                wire: { kind: 'pause_until_signal', signal: d.signal, timeoutMs: d.timeoutMs, resumeStep: d.resumeStep },
+                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 },
             };
-        case 'retry':
-            return { output: undefined, wire: { kind: 'retry', delayMs: d.delayMs, reason: d.reason } };
     }
 }

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

@@ -1,6 +1,6 @@
-import type { OrchestrationDefinition, WorkflowManifest } from '@sapiom/orchestration';
-import { type LocalStepTrace } from './dispatcher.js';
-import { type StubFile } from './stubs.js';
+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;
@@ -9,13 +9,19 @@ export interface RunLocalOptions {
     stubs?: StubFile;
     maxAttemptsPerStep?: number;
 }
-export type LocalRunOutcome = 'completed' | 'failed' | 'paused' | 'running';
+export type LocalRunOutcome = "completed" | "failed" | "paused" | "running";
+export interface UnusedStub {
+    step: string;
+    key: string;
+}
 export interface LocalRunResult {
     outcome: LocalRunOutcome;
     executionId: string;
     output?: unknown;
     error?: unknown;
     steps: LocalStepTrace[];
+    unusedStubs: UnusedStub[];
+    stubWarnings: string[];
 }
 export declare function runLocal(opts: RunLocalOptions): Promise<LocalRunResult>;
 export declare function runLocalFromDir(opts: {

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

@@ -13,18 +13,18 @@ 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');
+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'));
+        raw = JSON.parse((0, node_fs_1.readFileSync)(file, "utf8"));
     }
     catch (err) {
         throw new errors_js_1.OrchestrationError({
-            code: 'STUBS_INVALID',
+            code: "STUBS_INVALID",
             message: `${exports.STUBS_FILE} is not valid JSON.`,
             hint: err instanceof Error ? err.message : String(err),
         });
@@ -39,7 +39,11 @@ async function runLocal(opts) {
     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 });
+    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, {
@@ -49,25 +53,43 @@ async function runLocal(opts) {
     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')
+        if (!row ||
+            row.status === "completed" ||
+            row.status === "failed" ||
+            row.status === "cancelled")
             break;
-        if (row.status === 'paused') {
-            const payload = signals.get(row.pausedSignalCorrelationId ?? '') ?? {};
+        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');
+    const outcome = final?.status === "cancelled" ? "failed" : (final?.status ?? "running");
+    const unusedStubs = [];
+    for (const [step, used] of dispatcher.usedKeysByStep) {
+        for (const key of Object.keys(stubs.steps[step] ?? {})) {
+            if (!used.has(key))
+                unusedStubs.push({ step, key });
+        }
+    }
     return {
         outcome,
         executionId,
         output: final?.output,
         error: final?.error,
         steps: dispatcher.trace,
+        unusedStubs,
+        stubWarnings: [...dispatcher.stubWarnings],
     };
 }
 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 });
+    return runLocal({
+        definition,
+        manifest,
+        input: opts.input,
+        stubs,
+        maxAttemptsPerStep: opts.maxAttemptsPerStep,
+    });
 }

package/dist/cjs/scaffold.d.ts

@@ -18,5 +18,6 @@ export interface ScaffoldResult {
     targetDir: string;
     template: string;
     projectName: string;
+    gitInitialized: boolean;
 }
 export declare function scaffold(opts: ScaffoldOptions): Promise<ScaffoldResult>;

package/dist/cjs/scaffold.js

@@ -8,34 +8,37 @@ exports.resolveVersions = resolveVersions;
 exports.listTemplates = listTemplates;
 exports.resolveTemplate = resolveTemplate;
 exports.scaffold = scaffold;
+const node_child_process_1 = require("node:child_process");
 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')
+    if (typeof __dirname !== "undefined")
         return __dirname;
     try {
-        const metaUrl = eval('import.meta.url');
-        if (typeof metaUrl === 'string')
+        const metaUrl = eval("import.meta.url");
+        if (typeof metaUrl === "string")
             return node_path_1.default.dirname((0, node_url_1.fileURLToPath)(metaUrl));
     }
     catch {
     }
-    return '';
+    return "";
 }
 const moduleDir = resolveModuleDir();
 function getTemplatesDir(override) {
-    return override ?? process.env.SAPIOM_TEMPLATES_DIR ?? node_path_1.default.resolve(moduleDir, '..', '..', 'templates');
+    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';
+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',
+    orchestration: "0.1.1",
+    tools: "0.1.1",
 };
-const ZOD_VERSION = '3.25.76';
+const ZOD_VERSION = "3.25.76";
 async function latestNpmVersion(pkg) {
     try {
         const res = await fetch(`${REGISTRY}/${encodeURIComponent(pkg)}/latest`, {
@@ -44,7 +47,7 @@ async function latestNpmVersion(pkg) {
         if (!res.ok)
             return null;
         const json = (await res.json());
-        return typeof json.version === 'string' ? json.version : null;
+        return typeof json.version === "string" ? json.version : null;
     }
     catch {
         return null;
@@ -52,8 +55,8 @@ async function latestNpmVersion(pkg) {
 }
 async function resolveVersions() {
     const [orchestration, tools] = await Promise.all([
-        latestNpmVersion('@sapiom/orchestration'),
-        latestNpmVersion('@sapiom/tools'),
+        latestNpmVersion("@sapiom/orchestration"),
+        latestNpmVersion("@sapiom/tools"),
     ]);
     return {
         orchestration: orchestration ?? VERSION_FALLBACK.orchestration,
@@ -72,9 +75,11 @@ function resolveTemplate(name, templatesDir) {
     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',
+            code: "UNKNOWN_TEMPLATE",
             message: `Unknown template '${name}'.` +
-                (available.length ? ` Available: ${available.join(', ')}.` : ' No templates are bundled.'),
+                (available.length
+                    ? ` Available: ${available.join(", ")}.`
+                    : " No templates are bundled."),
         });
     }
     return dir;
@@ -82,7 +87,7 @@ function resolveTemplate(name, templatesDir) {
 function applyReplacements(file, replacements) {
     let content;
     try {
-        content = (0, node_fs_1.readFileSync)(file, 'utf8');
+        content = (0, node_fs_1.readFileSync)(file, "utf8");
     }
     catch {
         return;
@@ -111,7 +116,7 @@ function copyTemplate(templateDir, targetDir, replacements) {
     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));
+            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;
@@ -119,13 +124,37 @@ function copyTemplate(templateDir, targetDir, replacements) {
         applyReplacements(file, replacements);
     });
 }
+function initGitRepo(dir) {
+    const tryGit = (args) => {
+        try {
+            (0, node_child_process_1.execFileSync)("git", args, { cwd: dir, stdio: "ignore" });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    if (!tryGit(["init"]))
+        return false;
+    tryGit(["add", "-A"]);
+    return (tryGit(["commit", "-m", "Initial commit"]) ||
+        tryGit([
+            "-c",
+            "user.name=Sapiom",
+            "-c",
+            "user.email=noreply@sapiom.ai",
+            "commit",
+            "-m",
+            "Initial commit",
+        ]));
+}
 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',
+            code: "DIR_NOT_EMPTY",
             message: `Target directory '${targetDir}' already exists and is not empty.`,
         });
     }
@@ -138,8 +167,9 @@ async function scaffold(opts) {
         __TOOLS_VERSION__: versions.tools,
         __ZOD_VERSION__: versions.zod,
     });
-    const devDir = node_path_1.default.join(targetDir, '.sapiom-dev');
+    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 };
+    (0, node_fs_1.writeFileSync)(node_path_1.default.join(devDir, "stubs.json"), JSON.stringify({ version: 1, steps: {} }, null, 2) + "\n");
+    const gitInitialized = initGitRepo(targetDir);
+    return { targetDir, template, projectName, gitInitialized };
 }