@kici-dev/compiler 0.0.0 → 0.1.2

package/dist/llm-context/llms.txt

@@ -0,0 +1,61 @@
+# KiCI
+
+> KiCI is a TypeScript-native CI/CD workflow engine. Workflows are defined in TypeScript (not YAML), compiled into a portable lock file, and executed by self-hosted agents. The docs below cover the SDK, the CLI, workflow patterns, and the runtime architecture an LLM coding agent needs in order to author and test KiCI workflows.
+
+The full markdown bundle of every page indexed here is available at https://kici.dev/llms-full.txt.
+
+## Getting started
+
+- [User guide](https://kici.dev/docs/user/): Writing and testing CI/CD workflows in TypeScript
+- [Getting started with KiCI](https://kici.dev/docs/user/getting-started/): Install the SDK, write your first workflow, compile and test locally
+
+## Workflow patterns
+
+- [Basic workflow patterns](https://kici.dev/docs/user/patterns/basic/): Basic CI, PR-only / push-only filters, multiple triggers, manual-only workflows
+- [Conditionals & matrix patterns](https://kici.dev/docs/user/patterns/conditionals-matrix/): Conditional execution with rules, matrix builds (static + dynamic), dynamic job generation
+- [Integration patterns](https://kici.dev/docs/user/patterns/integrations/): Workflow chaining, generic webhooks, Stripe, self-hosted git forges, plain GitHub repos
+- [Pattern reference](https://kici.dev/docs/user/patterns/reference/): Step context, examples repository, GitHub check run output — cross-cutting reference for all patterns
+- [Scheduling & event patterns](https://kici.dev/docs/user/patterns/scheduling-and-events/): Nightly cron, workflow-complete-triggered deploys, custom event chaining
+
+## SDK reference
+
+- [SDK reference: core](https://kici.dev/docs/user/sdk/core/): Factory functions (workflow, job, step) and authoring patterns: needs, output chaining, dynamic groups
+- [SDK reference: idempotent](https://kici.dev/docs/user/sdk/idempotent/): Idempotent helpers for declarative check / apply patterns inside workflow steps
+- [SDK reference: rules, matrix, dynamic jobs](https://kici.dev/docs/user/sdk/rules-matrix-dynamic/): rule(), skip(), matrix builds (static + dynamic), and dynamicJob / dynamicGroup
+- [SDK reference: runtime](https://kici.dev/docs/user/sdk/runtime/): Types index, StepContext, secrets, fixtures
+- [SDK reference: triggers](https://kici.dev/docs/user/sdk/triggers/): GitHub event triggers, kiciEvent, workflowComplete, jobComplete, genericWebhook, schedule, lifecycle
+- [SDK reference: validation & events](https://kici.dev/docs/user/sdk/validation-events/): validateDag(), event definitions, and event emission
+- [SDK reference: waitFor](https://kici.dev/docs/user/sdk/wait-for/): Polling helpers for steps that pause until an external condition becomes true
+- [SDK reference](https://kici.dev/docs/user/sdk-reference/): Complete API reference for @kici-dev/sdk -- workflows, jobs, steps, triggers, rules, matrix, validation, runtime
+
+## CLI and authoring
+
+- [CLI authentication](https://kici.dev/docs/user/cli-auth/): Authenticate the KiCI CLI with browser OAuth, device flow, or API key paste
+- [CLI reference](https://kici.dev/docs/user/cli-reference/): All CLI commands: compile, run (local/remote), test, login, logout, org, status, cancel, secrets, types, fixture, init, hook, endpoints, workflows, docs, admin
+- [Lifecycle hooks](https://kici.dev/docs/user/hooks/): SDK hook API for cancel, cleanup, success, failure, and step-level callbacks
+- [Lock file and workflow drift](https://kici.dev/docs/user/lock-file-and-drift/): Keep the lock file in sync with your workflow source and avoid drift
+- [Testing guide](https://kici.dev/docs/user/testing-guide/): Running remote test fixtures with kici run remote
+- [Workflow patterns](https://kici.dev/docs/user/workflow-patterns/): Common patterns: monorepo builds, conditional jobs, dynamic matrices, generic webhooks, scheduling
+
+## Workflow features
+
+- [Concurrency groups](https://kici.dev/docs/user/concurrency/): Control parallel execution with auto-cancel and queue modes
+- [Dashboard](https://kici.dev/docs/user/dashboard/)
+- [Dynamic values](https://kici.dev/docs/user/dynamic-values/)
+- [Environment variables](https://kici.dev/docs/user/env-vars/): KICI_* environment variable reference for the CLI
+- [Environments](https://kici.dev/docs/user/environments/): Configure deployment environments with variables, secrets, and protection rules
+- [Event system](https://kici.dev/docs/user/events/): How KiCI's event model works -- event types, the registration model, event matching, and circuit breaker protection
+- [Global workflows](https://kici.dev/docs/user/global-workflows/): Cross-repo workflows that run on events from any repo in the same org
+- [Private npm registries](https://kici.dev/docs/user/private-registries/): Authenticate `npm install` against private registries (CodeArtifact, GitHub Packages, Verdaccio, …) from a workflow's `.kici/package.json`
+- [Secrets](https://kici.dev/docs/user/secrets/): How to access secrets in KiCI workflow steps
+
+## Providers
+
+- [GitHub App provider](https://kici.dev/docs/user/providers/github/): Connect KiCI to GitHub via a GitHub App — full Checks API, installation-token clones, and cross-org dispatch
+- [Universal-git provider](https://kici.dev/docs/user/providers/universal-git/): Connect Forgejo, Gitea, Gogs, GitLab, or plain GitHub via webhook + PAT or SSH deploy key
+
+## Architecture overview
+
+- [Data flows](https://kici.dev/docs/architecture/data-flows/): End-to-end data flows through the KiCI three-tier architecture
+- [Design decisions](https://kici.dev/docs/architecture/design-decisions/): Why KiCI's architecture is shaped the way it is
+- [Architecture overview](https://kici.dev/docs/architecture/overview/): Three-tier relay model, package structure, and component responsibilities

package/dist/local-executor/dag-scheduler.d.ts

@@ -0,0 +1,44 @@
+/**
+ * DAG-based parallel job scheduler with concurrency control and fail-fast.
+ *
+ * Generic scheduler that takes nodes with dependency relationships and
+ * executes them via callbacks, respecting concurrency limits and
+ * providing abort signals for fail-fast cancellation.
+ */
+export interface DagNode {
+    name: string;
+    needs: string[];
+}
+interface DagExecutionCallbacks<T> {
+    execute: (name: string, signal: AbortSignal) => Promise<T>;
+    isSuccess: (result: T) => boolean;
+}
+interface DagOptions {
+    maxConcurrency: number;
+    failFast: boolean;
+}
+interface DagResult<T> {
+    results: Map<string, T>;
+    skipped: string[];
+    cancelled: string[];
+    status: 'success' | 'failure';
+}
+/**
+ * Execute a DAG of nodes with bounded concurrency and fail-fast support.
+ *
+ * Algorithm:
+ * 1. Detect cycles
+ * 2. Initialize ready queue with zero-dependency nodes
+ * 3. Event loop: launch ready nodes up to concurrency limit,
+ *    await first completion, update state, repeat
+ * 4. On failure: if failFast, abort all running and skip pending;
+ *    if keep-going, only skip transitive dependents
+ */
+export declare function executeDag<T>(nodes: DagNode[], callbacks: DagExecutionCallbacks<T>, options: DagOptions): Promise<DagResult<T>>;
+/**
+ * Given a list of DAG nodes and a target job name, return the target
+ * plus all transitive dependencies in topological order.
+ */
+export declare function resolveJobFilter(nodes: DagNode[], targetName: string): DagNode[];
+export {};
+//# sourceMappingURL=dag-scheduler.d.ts.map

package/dist/local-executor/dag-scheduler.js

@@ -0,0 +1,183 @@
+import "../chunk-gOLHoazu.js";
+//#region src/local-executor/dag-scheduler.ts
+/**
+* Detect cycles using Kahn's algorithm.
+* Returns true if a cycle exists.
+*/
+function detectCycle(nodes) {
+	const inDegree = /* @__PURE__ */ new Map();
+	for (const n of nodes) {
+		if (!inDegree.has(n.name)) inDegree.set(n.name, 0);
+		for (const dep of n.needs) {
+			inDegree.set(n.name, (inDegree.get(n.name) ?? 0) + 1);
+			if (!inDegree.has(dep)) inDegree.set(dep, 0);
+		}
+	}
+	const queue = [];
+	for (const [name, deg] of inDegree) if (deg === 0) queue.push(name);
+	let processed = 0;
+	while (queue.length > 0) {
+		const name = queue.shift();
+		processed++;
+		for (const n of nodes) if (n.needs.includes(name)) {
+			const newDeg = inDegree.get(n.name) - 1;
+			inDegree.set(n.name, newDeg);
+			if (newDeg === 0) queue.push(n.name);
+		}
+	}
+	return processed < nodes.length;
+}
+/**
+* Execute a DAG of nodes with bounded concurrency and fail-fast support.
+*
+* Algorithm:
+* 1. Detect cycles
+* 2. Initialize ready queue with zero-dependency nodes
+* 3. Event loop: launch ready nodes up to concurrency limit,
+*    await first completion, update state, repeat
+* 4. On failure: if failFast, abort all running and skip pending;
+*    if keep-going, only skip transitive dependents
+*/
+async function executeDag(nodes, callbacks, options) {
+	if (nodes.length === 0) return {
+		results: /* @__PURE__ */ new Map(),
+		skipped: [],
+		cancelled: [],
+		status: "success"
+	};
+	if (detectCycle(nodes)) throw new Error("Circular dependency detected in job graph");
+	const nodeMap = new Map(nodes.map((n) => [n.name, n]));
+	const results = /* @__PURE__ */ new Map();
+	const skipped = [];
+	const cancelled = [];
+	const failedNames = /* @__PURE__ */ new Set();
+	const pending = new Set(nodes.map((n) => n.name));
+	const running = /* @__PURE__ */ new Map();
+	let hasFailure = false;
+	let abortAll = false;
+	/**
+	* Check if a node is ready to execute:
+	* all dependencies completed successfully.
+	*/
+	function isReady(name) {
+		return nodeMap.get(name).needs.every((dep) => results.has(dep) && callbacks.isSuccess(results.get(dep)));
+	}
+	/**
+	* Check if a node should be skipped because a dependency failed.
+	*/
+	function shouldSkip(name) {
+		return nodeMap.get(name).needs.some((dep) => failedNames.has(dep) || skipped.includes(dep) || cancelled.includes(dep));
+	}
+	while (pending.size > 0 || running.size > 0) {
+		if (abortAll) {
+			for (const name of pending) skipped.push(name);
+			pending.clear();
+			if (running.size > 0) {
+				const entries = [...running.entries()];
+				const settled = await Promise.allSettled(entries.map(([, v]) => v.promise));
+				for (let i = 0; i < entries.length; i++) {
+					const [name] = entries[i];
+					const s = settled[i];
+					if (s.status === "fulfilled") {
+						results.set(name, s.value);
+						if (!callbacks.isSuccess(s.value)) cancelled.push(name);
+					} else cancelled.push(name);
+					running.delete(name);
+				}
+			}
+			break;
+		}
+		let skipChanged = true;
+		while (skipChanged) {
+			skipChanged = false;
+			const toSkip = [];
+			for (const name of pending) if (shouldSkip(name)) toSkip.push(name);
+			for (const name of toSkip) {
+				pending.delete(name);
+				skipped.push(name);
+				skipChanged = true;
+			}
+		}
+		const readyNodes = [];
+		for (const name of pending) {
+			if (running.size + readyNodes.length >= options.maxConcurrency) break;
+			if (isReady(name)) readyNodes.push(name);
+		}
+		for (const name of readyNodes) {
+			pending.delete(name);
+			const controller = new AbortController();
+			const promise = callbacks.execute(name, controller.signal);
+			running.set(name, {
+				promise,
+				controller
+			});
+		}
+		if (running.size === 0) break;
+		const wrappedPromises = [...running.entries()].map(async ([name, { promise }]) => {
+			return {
+				name,
+				result: await promise
+			};
+		});
+		for (const p of wrappedPromises) p.catch(() => {});
+		const { name: completedName, result: completedResult } = await Promise.race(wrappedPromises);
+		running.delete(completedName);
+		results.set(completedName, completedResult);
+		if (!callbacks.isSuccess(completedResult)) {
+			hasFailure = true;
+			failedNames.add(completedName);
+			if (options.failFast) {
+				for (const [, { controller }] of running) controller.abort();
+				abortAll = true;
+			}
+		}
+	}
+	return {
+		results,
+		skipped,
+		cancelled,
+		status: hasFailure || skipped.length > 0 || cancelled.length > 0 ? "failure" : "success"
+	};
+}
+/**
+* Given a list of DAG nodes and a target job name, return the target
+* plus all transitive dependencies in topological order.
+*/
+function resolveJobFilter(nodes, targetName) {
+	const nodeMap = new Map(nodes.map((n) => [n.name, n]));
+	if (!nodeMap.has(targetName)) return [];
+	const needed = /* @__PURE__ */ new Set();
+	const queue = [targetName];
+	while (queue.length > 0) {
+		const name = queue.shift();
+		if (needed.has(name)) continue;
+		needed.add(name);
+		const node = nodeMap.get(name);
+		if (node) {
+			for (const dep of node.needs) if (!needed.has(dep)) queue.push(dep);
+		}
+	}
+	const subset = nodes.filter((n) => needed.has(n.name));
+	const inDegree = /* @__PURE__ */ new Map();
+	for (const n of subset) {
+		if (!inDegree.has(n.name)) inDegree.set(n.name, 0);
+		for (const dep of n.needs) if (needed.has(dep)) inDegree.set(n.name, (inDegree.get(n.name) ?? 0) + 1);
+	}
+	const result = [];
+	const topoQueue = [];
+	for (const [name, deg] of inDegree) if (deg === 0) topoQueue.push(name);
+	while (topoQueue.length > 0) {
+		const name = topoQueue.shift();
+		result.push(nodeMap.get(name));
+		for (const n of subset) if (n.needs.includes(name) && needed.has(n.name)) {
+			const newDeg = inDegree.get(n.name) - 1;
+			inDegree.set(n.name, newDeg);
+			if (newDeg === 0) topoQueue.push(n.name);
+		}
+	}
+	return result;
+}
+//#endregion
+export { executeDag, resolveJobFilter };
+
+//# sourceMappingURL=dag-scheduler.js.map

package/dist/local-executor/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Public API: executeLocal() orchestrating compile, match, resolve, schedule, report.
+ *
+ * Pipeline:
+ * 1. Compile workflows from .kici/ sources
+ * 2. Load workflows (discover runtime modules)
+ * 3. Load secrets from local files
+ * 4. Build event payload from git state + CLI overrides
+ * 5. Match triggers to find active workflows
+ * 6. Apply --workflow and --job filters
+ * 7. Resolve jobs (matrix expansion, dynamic evaluation)
+ * 8. Execute via DAG scheduler with concurrency control
+ * 9. Return success/failure
+ */
+import type { RunLocalOptions } from './types.js';
+/**
+ * Execute workflows locally -- the full compile-match-resolve-execute pipeline.
+ *
+ * @param options - CLI options from `kici run local`
+ * @returns true if all workflows succeeded, false otherwise
+ */
+export declare function executeLocal(options: RunLocalOptions): Promise<boolean>;
+//# sourceMappingURL=index.d.ts.map

package/dist/local-executor/index.js

@@ -0,0 +1,309 @@
+import "../chunk-gOLHoazu.js";
+import { discoverWorkflows, resolveKiciDir } from "../execution/executor.js";
+import "../execution/index.js";
+import { transformTriggers } from "../lockfile/generator.js";
+import { compileCommand } from "../commands/compile.js";
+import { executeDag, resolveJobFilter } from "./dag-scheduler.js";
+import { loadLocalSecrets } from "./secret-loader.js";
+import { generateEventPayload } from "./payload-generator.js";
+import { executeResolvedJob, resolveJobs } from "./job-runner.js";
+import { displayLocalSummary, formatLocalJsonResult, formatLocalJunitResult } from "./output-streamer.js";
+import { PickerCancelledError, runPicker } from "./picker.js";
+import { ConcurrencyKeyEvaluationError, acquireWorkflowLock } from "./workflow-lock.js";
+import pc from "picocolors";
+import { writeFile } from "node:fs/promises";
+import { logger } from "@kici-dev/shared";
+import { matchAllWorkflows } from "@kici-dev/engine";
+import os from "node:os";
+//#region src/local-executor/index.ts
+/**
+* Public API: executeLocal() orchestrating compile, match, resolve, schedule, report.
+*
+* Pipeline:
+* 1. Compile workflows from .kici/ sources
+* 2. Load workflows (discover runtime modules)
+* 3. Load secrets from local files
+* 4. Build event payload from git state + CLI overrides
+* 5. Match triggers to find active workflows
+* 6. Apply --workflow and --job filters
+* 7. Resolve jobs (matrix expansion, dynamic evaluation)
+* 8. Execute via DAG scheduler with concurrency control
+* 9. Return success/failure
+*/
+/**
+* Convert SDK workflows to lock-file-like structure for trigger matching.
+* Simplified version of the one in test.ts -- only needs trigger info.
+*/
+function workflowsToLockFormat(workflows) {
+	return workflows.map((w) => ({
+		name: w.name,
+		contentHash: "",
+		compileSchemaVersion: 0,
+		triggers: transformTriggers(w.on),
+		jobs: w.jobs.map((j, i) => {
+			if (typeof j === "function") return {
+				_type: "dynamic",
+				source: {
+					file: "",
+					index: i
+				}
+			};
+			return {
+				_type: "static",
+				name: j.name,
+				runsOn: j.runsOn,
+				needs: j.needs?.map((n) => typeof n === "string" ? n : n.name) ?? [],
+				steps: j.steps.map((s) => {
+					if (typeof s === "function") return {
+						name: "",
+						hasOutputs: false
+					};
+					return {
+						name: s.name,
+						hasOutputs: !!s.outputs
+					};
+				})
+			};
+		}),
+		rules: w.rules?.map((r, i) => ({
+			_type: "dynamic",
+			label: r.label,
+			source: {
+				file: "",
+				index: i
+			}
+		}))
+	}));
+}
+/**
+* Derive `groupCtx.branch` for the workflow concurrency `group` callback.
+* Mirrors the agent's semantics (`request.branch ?? request.ref`) so a
+* `group({ branch })` function works identically locally and remotely.
+*/
+function deriveBranchForGroupCtx(event) {
+	if (event.targetBranch) return event.targetBranch;
+	if (event.sourceBranch) return event.sourceBranch;
+	const ref = event.payload?.ref;
+	if (typeof ref === "string") {
+		const m = /^refs\/heads\/(.+)$/.exec(ref);
+		if (m) return m[1];
+	}
+	return "";
+}
+/**
+* Execute one matched workflow under its concurrency lock (if any).
+*
+* Returns the result and a flag indicating whether it should count towards
+* `allSucceeded`. Returns `null` when the workflow was filtered out (e.g. by
+* `--job` removing every node).
+*/
+async function runOneMatchedWorkflow(workflow, ctx) {
+	const { options, isQuiet, event, secrets, kiciDir, concurrency, failFast } = ctx;
+	if (!isQuiet) logger.info(`\n${pc.bold("Running workflow:")} ${workflow.name}\n`);
+	let lockHandle = null;
+	try {
+		lockHandle = await acquireWorkflowLock({
+			workflowName: workflow.name,
+			workflow,
+			event: event.payload,
+			branch: deriveBranchForGroupCtx(event),
+			debug: options.debug
+		});
+	} catch (err) {
+		if (err instanceof ConcurrencyKeyEvaluationError) {
+			logger.error(pc.red(`Concurrency group evaluation failed for workflow "${workflow.name}": ${err.cause?.message ?? err.message}`));
+			return {
+				result: {
+					name: workflow.name,
+					status: "failure",
+					jobs: [],
+					durationMs: 0
+				},
+				succeeded: false
+			};
+		}
+		throw err;
+	}
+	try {
+		return await runWorkflowBody(workflow, ctx, options, secrets, kiciDir, concurrency, failFast);
+	} finally {
+		await lockHandle?.release();
+	}
+}
+/**
+* The actual DAG-execution body for one workflow. Split out so
+* {@link runOneMatchedWorkflow} can wrap it in a lock acquire/release.
+*/
+async function runWorkflowBody(workflow, ctx, options, secrets, kiciDir, concurrency, failFast) {
+	const { event } = ctx;
+	const resolvedJobs = await resolveJobs(workflow, event);
+	let dagNodes = resolvedJobs.map((r) => ({
+		name: r.expandedName,
+		needs: r.resolvedNeeds
+	}));
+	if (options.job) {
+		dagNodes = resolveJobFilter(dagNodes, options.job);
+		if (dagNodes.length === 0) return null;
+	}
+	const resolvedJobMap = new Map(resolvedJobs.map((r) => [r.expandedName, r]));
+	const dagNodeNames = new Set(dagNodes.map((n) => n.name));
+	const filteredResolvedJobs = resolvedJobs.filter((r) => dagNodeNames.has(r.expandedName));
+	const jobOutputsMap = /* @__PURE__ */ new Map();
+	const startTime = Date.now();
+	const dagResult = await executeDag(dagNodes, {
+		execute: async (name, signal) => {
+			const resolved = resolvedJobMap.get(name);
+			if (!resolved) return {
+				name,
+				status: "failure",
+				durationMs: 0,
+				steps: [],
+				error: /* @__PURE__ */ new Error(`Job "${name}" not found in resolved jobs`)
+			};
+			return executeResolvedJob(resolved, {
+				workflowName: workflow.name,
+				event,
+				secrets,
+				kiciDir,
+				jobOutputsMap,
+				signal
+			});
+		},
+		isSuccess: (result) => result.status === "success" || result.status === "skipped"
+	}, {
+		maxConcurrency: concurrency,
+		failFast
+	});
+	const durationMs = Date.now() - startTime;
+	const jobResults = [];
+	for (const rj of filteredResolvedJobs) {
+		const result = dagResult.results.get(rj.expandedName);
+		if (result) jobResults.push({
+			...result,
+			matrixValues: Object.keys(rj.matrixValues).length > 0 ? rj.matrixValues : void 0
+		});
+		else if (dagResult.skipped.includes(rj.expandedName)) jobResults.push({
+			name: rj.expandedName,
+			status: "skipped",
+			durationMs: 0,
+			steps: [],
+			matrixValues: Object.keys(rj.matrixValues).length > 0 ? rj.matrixValues : void 0
+		});
+		else if (dagResult.cancelled.includes(rj.expandedName)) jobResults.push({
+			name: rj.expandedName,
+			status: "cancelled",
+			durationMs: 0,
+			steps: [],
+			cancelled: true,
+			matrixValues: Object.keys(rj.matrixValues).length > 0 ? rj.matrixValues : void 0
+		});
+	}
+	return {
+		result: {
+			name: workflow.name,
+			status: dagResult.status === "success" ? "success" : "failure",
+			jobs: jobResults,
+			durationMs
+		},
+		succeeded: dagResult.status === "success"
+	};
+}
+/**
+* Execute workflows locally -- the full compile-match-resolve-execute pipeline.
+*
+* @param options - CLI options from `kici run local`
+* @returns true if all workflows succeeded, false otherwise
+*/
+async function executeLocal(options) {
+	const kiciDir = resolveKiciDir(options.kiciDir);
+	if (!await compileCommand({
+		kiciDir,
+		check: false,
+		verbose: options.debug ?? false
+	})) {
+		process.exitCode = 2;
+		return false;
+	}
+	const { workflows: workflowsWithSource } = await discoverWorkflows(kiciDir);
+	const workflows = workflowsWithSource.map((w) => w.workflow);
+	if (workflows.length === 0) {
+		logger.info(pc.yellow("No workflows found"));
+		return true;
+	}
+	if (options.pick) try {
+		const picked = await runPicker(workflows, { filterEvent: options.event });
+		options = {
+			...options,
+			event: picked.event,
+			workflow: picked.workflow
+		};
+	} catch (err) {
+		if (err instanceof PickerCancelledError) {
+			logger.info(pc.yellow(err.message));
+			return true;
+		}
+		throw err;
+	}
+	if (!options.event) {
+		logger.error(pc.red("Missing event argument. Pass an event (e.g. \"push\") or use --pick to select one."));
+		process.exitCode = 2;
+		return false;
+	}
+	const secrets = await loadLocalSecrets(kiciDir, options.env);
+	const event = await generateEventPayload(options.event, options);
+	const decisions = matchAllWorkflows(workflowsToLockFormat(workflows), event);
+	let matchedWorkflows = workflows.filter((_, i) => decisions[i]?.matched);
+	if (matchedWorkflows.length === 0) {
+		logger.info(pc.gray("No workflows matched the event"));
+		return true;
+	}
+	if (options.workflow) {
+		matchedWorkflows = matchedWorkflows.filter((w) => w.name === options.workflow);
+		if (matchedWorkflows.length === 0) {
+			logger.info(pc.yellow(`No workflow named "${options.workflow}" matched the event`));
+			return true;
+		}
+	}
+	const isQuiet = Boolean(options.quiet || options.json);
+	const concurrency = options.concurrency ?? getDefaultConcurrency();
+	const failFast = !options.keepGoing;
+	let allSucceeded = true;
+	const workflowResults = [];
+	const ctx = {
+		options,
+		isQuiet,
+		event,
+		secrets,
+		kiciDir,
+		concurrency,
+		failFast
+	};
+	for (const workflow of matchedWorkflows) {
+		const outcome = await runOneMatchedWorkflow(workflow, ctx);
+		if (outcome === null) continue;
+		workflowResults.push(outcome.result);
+		if (!outcome.succeeded) allSucceeded = false;
+	}
+	if (options.json) console.log(formatLocalJsonResult(workflowResults));
+	else if (options.junit) {
+		const junitXml = formatLocalJunitResult(workflowResults);
+		await writeFile(options.junit, junitXml);
+		if (!isQuiet) logger.info(pc.green(`JUnit XML written to ${options.junit}`));
+	}
+	if (!isQuiet) displayLocalSummary(workflowResults);
+	return allSucceeded;
+}
+/**
+* Get default concurrency based on available CPU parallelism.
+*/
+function getDefaultConcurrency() {
+	try {
+		return os.availableParallelism();
+	} catch {
+		return os.cpus().length || 4;
+	}
+}
+//#endregion
+export { executeLocal };
+
+//# sourceMappingURL=index.js.map

package/dist/local-executor/job-runner.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Job resolution (matrix/dynamic) and single-job execution with step context.
+ *
+ * Handles:
+ * - Static job resolution
+ * - Matrix expansion into multiple ResolvedJob instances
+ * - Dynamic job function evaluation
+ * - Single-job step-by-step execution with rules, abort, and output chaining
+ */
+import type { Workflow, OutputsMap } from '@kici-dev/sdk';
+import type { SimulatedEvent } from '@kici-dev/engine';
+import type { ParsedSecrets } from '../test-runner/secrets-file.js';
+import type { ResolvedJob, LocalJobResult } from './types.js';
+/**
+ * Context passed to executeResolvedJob for single-job execution.
+ */
+interface JobExecutionContext {
+    workflowName: string;
+    event: SimulatedEvent;
+    secrets: ParsedSecrets;
+    kiciDir: string;
+    jobOutputsMap: OutputsMap;
+    signal: AbortSignal;
+}
+/**
+ * Resolve all jobs in a workflow, expanding matrix jobs and evaluating dynamic jobs.
+ *
+ * - Static jobs: create ResolvedJob with name, needs, job reference
+ * - Matrix jobs: use expandMatrix() from SDK, create one ResolvedJob per combination
+ * - Dynamic job functions: evaluate the function, recursively resolve results
+ * - Fan-in: if a job needs a matrix-expanded job, it needs ALL instances
+ */
+export declare function resolveJobs(workflow: Workflow, event: SimulatedEvent): Promise<ResolvedJob[]>;
+/**
+ * Execute a single resolved job: evaluate rules, run steps sequentially,
+ * check abort signal between steps, collect outputs.
+ */
+export declare function executeResolvedJob(resolvedJob: ResolvedJob, context: JobExecutionContext): Promise<LocalJobResult>;
+export {};
+//# sourceMappingURL=job-runner.d.ts.map