@sapiom/orchestration-core 0.1.1 → 0.3.0

package/dist/esm/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/esm/index.js

@@ -1,15 +1,15 @@
-export { OrchestrationError } from './errors.js';
-export { GatewayClient, createClient, DEFAULT_WORKFLOWS_HOST } from './client.js';
-export { readConfig, requireConfig, writeConfig, CONFIG_FILE } from './config.js';
-export { scaffold, resolveVersions, resolveTemplate, listTemplates, DEFAULT_TEMPLATE } from './scaffold.js';
-export { check } from './check.js';
-export { link } from './link.js';
-export { deploy } from './deploy.js';
-export { run, parseJsonInput } from './run.js';
-export { inspect, listExecutions, inspectBuild } from './inspect.js';
-export { signal, parseSignalPayload } from './signal.js';
-export { assertDeployable, pushHead } from './git.js';
-export { parseStubFile, STUB_FILE_VERSION } from './local/stubs.js';
-export { runLocal, runLocalFromDir, STUBS_FILE } from './local/run-local.js';
-export { loadDefinition } from './local/load.js';
-export { LocalStubDispatcher } from './local/dispatcher.js';
+export { OrchestrationError } from "./errors.js";
+export { GatewayClient, createClient, DEFAULT_WORKFLOWS_HOST, } from "./client.js";
+export { readConfig, requireConfig, writeConfig, CONFIG_FILE, } from "./config.js";
+export { scaffold, resolveVersions, resolveTemplate, listTemplates, DEFAULT_TEMPLATE, } from "./scaffold.js";
+export { check } from "./check.js";
+export { link } from "./link.js";
+export { deploy } from "./deploy.js";
+export { run, parseJsonInput } from "./run.js";
+export { inspect, listExecutions, inspectBuild, waitForExecution, isExecutionTerminal, } from "./inspect.js";
+export { signal, parseSignalPayload } from "./signal.js";
+export { assertDeployable, pushHead } from "./git.js";
+export { parseStubFile, STUB_FILE_VERSION } from "./local/stubs.js";
+export { runLocal, runLocalFromDir, STUBS_FILE } from "./local/run-local.js";
+export { loadDefinition } from "./local/load.js";
+export { LocalStubDispatcher } from "./local/dispatcher.js";

package/dist/esm/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/esm/inspect.js

@@ -2,8 +2,44 @@ export async function inspect(opts, client) {
     const execution = await client.get(`/executions/${opts.executionId}`);
     return { execution };
 }
+const TERMINAL_STATUSES = new Set([
+    "completed",
+    "failed",
+    "cancelled",
+    "canceled",
+]);
+export 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));
+export 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);
+    }
+}
 export async function listExecutions(client) {
-    const executions = await client.get('/executions');
+    const executions = await client.get("/executions");
     return { executions };
 }
 export async function inspectBuild(opts, client) {

package/dist/esm/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/esm/local/dispatcher.js

@@ -1,6 +1,6 @@
-import { InMemoryContextStore, } from '@sapiom/orchestration';
-import { parseCorrelationId, STEP_COMPLETION_OUTCOME, } from '@sapiom/orchestration-runtime';
-import { createStubClient } from '@sapiom/tools/stub';
+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;
@@ -8,6 +8,8 @@ export class LocalStubDispatcher {
         this.core = null;
         this.signals = new Map();
         this.trace = [];
+        this.usedKeysByStep = new Map();
+        this.stubWarnings = new Set();
     }
     setCore(core) {
         this.core = core;
@@ -20,7 +22,7 @@ export 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`);
@@ -30,7 +32,17 @@ export class LocalStubDispatcher {
         const logs = [];
         const sharedStore = new InMemoryContextStore(request.shared);
         const overrides = (this.stubs.steps[request.stepName] ?? {});
-        const sapiom = 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 = createStubClient({
+            overrides,
+            signals: this.signals,
+            usedKeys,
+            warnings: this.stubWarnings,
+        });
         const ctx = {
             executionId: request.executionId,
             workflowName: request.workflowName,
@@ -53,7 +65,7 @@ export 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,
             });
@@ -71,7 +83,7 @@ export class LocalStubDispatcher {
             step: request.stepName,
             attempt: request.attempt,
             input: request.input,
-            status: 'succeeded',
+            status: "succeeded",
             output,
             directive,
             logs,
@@ -90,22 +102,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/esm/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/esm/local/run-local.js

@@ -1,22 +1,22 @@
-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');
+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'));
+        raw = JSON.parse(readFileSync(file, "utf8"));
     }
     catch (err) {
         throw new OrchestrationError({
-            code: 'STUBS_INVALID',
+            code: "STUBS_INVALID",
             message: `${STUBS_FILE} is not valid JSON.`,
             hint: err instanceof Error ? err.message : String(err),
         });
@@ -31,7 +31,11 @@ export async function runLocal(opts) {
     const dispatcher = new LocalStubDispatcher(opts.definition, stubs);
     const signals = new Map();
     dispatcher.setSignals(signals);
-    const core = new WorkflowRunnerCore({ store, dispatcher, observer: NOOP_OBSERVER });
+    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, {
@@ -41,25 +45,43 @@ export 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],
     };
 }
 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 });
+    return runLocal({
+        definition,
+        manifest,
+        input: opts.input,
+        stubs,
+        maxAttemptsPerStep: opts.maxAttemptsPerStep,
+    });
 }

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

@@ -1,31 +1,34 @@
-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';
+import { execFileSync } from "node:child_process";
+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')
+    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 path.dirname(fileURLToPath(metaUrl));
     }
     catch {
     }
-    return '';
+    return "";
 }
 const moduleDir = resolveModuleDir();
 function getTemplatesDir(override) {
-    return override ?? process.env.SAPIOM_TEMPLATES_DIR ?? path.resolve(moduleDir, '..', '..', 'templates');
+    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';
+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',
+    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`, {
@@ -34,7 +37,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;
@@ -42,8 +45,8 @@ async function latestNpmVersion(pkg) {
 }
 export 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,
@@ -62,9 +65,11 @@ export function resolveTemplate(name, templatesDir) {
     if (!existsSync(dir) || !statSync(dir).isDirectory()) {
         const available = listTemplates(templatesDir);
         throw new 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;
@@ -72,7 +77,7 @@ export function resolveTemplate(name, templatesDir) {
 function applyReplacements(file, replacements) {
     let content;
     try {
-        content = readFileSync(file, 'utf8');
+        content = readFileSync(file, "utf8");
     }
     catch {
         return;
@@ -101,7 +106,7 @@ function copyTemplate(templateDir, targetDir, replacements) {
     walk(targetDir, (file) => {
         const base = path.basename(file);
         if (DOTFILE_NAMES.has(base)) {
-            const dotted = path.join(path.dirname(file), '.' + base.slice(1));
+            const dotted = path.join(path.dirname(file), "." + base.slice(1));
             renameSync(file, dotted);
             applyReplacements(dotted, replacements);
             return;
@@ -109,13 +114,37 @@ function copyTemplate(templateDir, targetDir, replacements) {
         applyReplacements(file, replacements);
     });
 }
+function initGitRepo(dir) {
+    const tryGit = (args) => {
+        try {
+            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",
+        ]));
+}
 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',
+            code: "DIR_NOT_EMPTY",
             message: `Target directory '${targetDir}' already exists and is not empty.`,
         });
     }
@@ -128,8 +157,9 @@ export async function scaffold(opts) {
         __TOOLS_VERSION__: versions.tools,
         __ZOD_VERSION__: versions.zod,
     });
-    const devDir = path.join(targetDir, '.sapiom-dev');
+    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 };
+    writeFileSync(path.join(devDir, "stubs.json"), JSON.stringify({ version: 1, steps: {} }, null, 2) + "\n");
+    const gitInitialized = initGitRepo(targetDir);
+    return { targetDir, template, projectName, gitInitialized };
 }