@kici-dev/engine 0.0.0 → 0.1.1

package/dist/state-machine/machine.d.ts

@@ -0,0 +1,34 @@
+import type { ExecutionState, ExecutionEvent } from './types.js';
+/**
+ * Error thrown when an invalid state transition is attempted.
+ */
+export declare class InvalidTransitionError extends Error {
+    readonly state: ExecutionState;
+    readonly event: ExecutionEvent;
+    constructor(state: ExecutionState, event: ExecutionEvent);
+}
+/**
+ * Attempt a state transition. Returns the new state or throws InvalidTransitionError.
+ *
+ * Pure function - no internal state.
+ */
+export declare function transition(state: ExecutionState, event: ExecutionEvent): ExecutionState;
+/**
+ * Check whether a transition is valid without throwing.
+ *
+ * Pure function - no internal state.
+ */
+export declare function canTransition(state: ExecutionState, event: ExecutionEvent): boolean;
+/**
+ * Check whether a state is terminal (no further transitions possible).
+ *
+ * Pure function - no internal state.
+ */
+export declare function isTerminal(state: ExecutionState): boolean;
+/**
+ * Get the list of valid events for a given state.
+ *
+ * Pure function - no internal state.
+ */
+export declare function validEvents(state: ExecutionState): ExecutionEvent[];
+//# sourceMappingURL=machine.d.ts.map

package/dist/state-machine/machine.js

@@ -0,0 +1,103 @@
+import "../chunk-gOLHoazu.js";
+import { TERMINAL_STATES } from "./types.js";
+//#region src/state-machine/machine.ts
+/**
+* Runtime transition table mapping each state to its valid event->nextState pairs.
+* Terminal states have no entries (empty objects).
+*/
+const TRANSITIONS = {
+	pending: {
+		ENQUEUE: "queued",
+		CANCEL: "cancelled",
+		SKIP: "skipped",
+		HOLD: "held",
+		WAIT: "waiting"
+	},
+	queued: {
+		START: "running",
+		FAIL: "failed",
+		CANCEL: "cancelled"
+	},
+	running: {
+		SUCCEED: "success",
+		FAIL: "failed",
+		CANCEL: "cancelled",
+		CANCEL_GRACEFUL: "cancelling",
+		RECOVER: "recovering"
+	},
+	recovering: {
+		START: "running",
+		FAIL: "failed",
+		CANCEL: "cancelled"
+	},
+	cancelling: {
+		CANCEL_FORCE: "cancelled",
+		COMPLETE: "cancelled",
+		FAIL: "failed"
+	},
+	held: {
+		APPROVE: "queued",
+		REJECT: "cancelled",
+		EXPIRE: "cancelled",
+		CANCEL: "cancelled"
+	},
+	waiting: {
+		TIMER_DONE: "queued",
+		CANCEL: "cancelled"
+	},
+	success: {},
+	failed: {},
+	cancelled: {},
+	skipped: {}
+};
+/**
+* Error thrown when an invalid state transition is attempted.
+*/
+var InvalidTransitionError = class extends Error {
+	state;
+	event;
+	constructor(state, event) {
+		super(`Invalid transition: cannot apply event '${event}' in state '${state}'`);
+		this.name = "InvalidTransitionError";
+		this.state = state;
+		this.event = event;
+	}
+};
+/**
+* Attempt a state transition. Returns the new state or throws InvalidTransitionError.
+*
+* Pure function - no internal state.
+*/
+function transition(state, event) {
+	const nextState = TRANSITIONS[state][event];
+	if (nextState === void 0) throw new InvalidTransitionError(state, event);
+	return nextState;
+}
+/**
+* Check whether a transition is valid without throwing.
+*
+* Pure function - no internal state.
+*/
+function canTransition(state, event) {
+	return TRANSITIONS[state][event] !== void 0;
+}
+/**
+* Check whether a state is terminal (no further transitions possible).
+*
+* Pure function - no internal state.
+*/
+function isTerminal(state) {
+	return TERMINAL_STATES.includes(state);
+}
+/**
+* Get the list of valid events for a given state.
+*
+* Pure function - no internal state.
+*/
+function validEvents(state) {
+	return Object.keys(TRANSITIONS[state]);
+}
+//#endregion
+export { InvalidTransitionError, canTransition, isTerminal, transition, validEvents };
+
+//# sourceMappingURL=machine.js.map

package/dist/state-machine/types.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Execution states for workflow, job, and step lifecycle tracking.
+ *
+ * State flow:
+ *   pending -> queued -> running -> recovering -> running (reconnect)
+ *                    \          \               \-> failed (timeout)
+ *                     \          \               \-> cancelled
+ *                      \          \-> success
+ *                       \          \-> failed
+ *                        \          \-> cancelled (direct, no hooks)
+ *                         \          \-> cancelling (graceful, with hooks)
+ *                          \                \-> cancelled (CANCEL_FORCE or COMPLETE)
+ *                           \                \-> failed (hook failure)
+ *                            \-> failed
+ *                             \-> cancelled
+ *   pending -> skipped
+ *   pending -> cancelled
+ *   pending -> held (protection: reviewer required)
+ *   pending -> waiting (protection: wait timer)
+ *   held -> queued (approved)
+ *   held -> cancelled (rejected / expired)
+ *   waiting -> queued (timer done)
+ *   waiting -> cancelled
+ */
+export type ExecutionState = 'pending' | 'queued' | 'running' | 'recovering' | 'cancelling' | 'held' | 'waiting' | 'success' | 'failed' | 'cancelled' | 'skipped';
+/**
+ * Events that trigger state transitions.
+ */
+export type ExecutionEvent = 'ENQUEUE' | 'START' | 'SUCCEED' | 'FAIL' | 'CANCEL' | 'CANCEL_GRACEFUL' | 'CANCEL_FORCE' | 'COMPLETE' | 'SKIP' | 'RECOVER' | 'HOLD' | 'APPROVE' | 'REJECT' | 'EXPIRE' | 'WAIT' | 'TIMER_DONE';
+/**
+ * States from which no further transitions are possible.
+ */
+export declare const TERMINAL_STATES: readonly ExecutionState[];
+//# sourceMappingURL=types.d.ts.map

package/dist/state-machine/types.js

@@ -0,0 +1,15 @@
+import "../chunk-gOLHoazu.js";
+//#region src/state-machine/types.ts
+/**
+* States from which no further transitions are possible.
+*/
+const TERMINAL_STATES = [
+	"success",
+	"failed",
+	"cancelled",
+	"skipped"
+];
+//#endregion
+export { TERMINAL_STATES };
+
+//# sourceMappingURL=types.js.map

package/dist/trigger/decision-trace.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Decision trace recording for debugging trigger matching.
+ * Records every check performed during trigger evaluation.
+ */
+/**
+ * Individual trace entry for a single check.
+ */
+export interface TraceEntry {
+    /** What was checked (e.g., "branch pattern", "path filter", "event type") */
+    check: string;
+    /** The pattern/condition that was evaluated */
+    pattern: string;
+    /** The value being tested against */
+    value: string;
+    /** Whether the check passed */
+    passed: boolean;
+    /** Optional explanation */
+    reason?: string;
+}
+/**
+ * Decision trace for a workflow's trigger evaluation.
+ */
+export interface WorkflowDecision {
+    workflowName: string;
+    matched: boolean;
+    /** Which trigger matched (if any) */
+    matchedTrigger?: number;
+    /** All checks performed */
+    checks: TraceEntry[];
+    /** Summary reason */
+    summary: string;
+}
+/**
+ * Create a new trace entry.
+ */
+export declare function createTraceEntry(check: string, pattern: string, value: string, passed: boolean, reason?: string): TraceEntry;
+/**
+ * Create a workflow decision record.
+ */
+export declare function createWorkflowDecision(workflowName: string, matched: boolean, checks: TraceEntry[], matchedTrigger?: number, summary?: string): WorkflowDecision;
+//# sourceMappingURL=decision-trace.d.ts.map

package/dist/trigger/decision-trace.js

@@ -0,0 +1,30 @@
+import "../chunk-gOLHoazu.js";
+//#region src/trigger/decision-trace.ts
+/**
+* Create a new trace entry.
+*/
+function createTraceEntry(check, pattern, value, passed, reason) {
+	return {
+		check,
+		pattern,
+		value,
+		passed,
+		reason
+	};
+}
+/**
+* Create a workflow decision record.
+*/
+function createWorkflowDecision(workflowName, matched, checks, matchedTrigger, summary) {
+	return {
+		workflowName,
+		matched,
+		matchedTrigger,
+		checks,
+		summary: summary ?? (matched ? "Trigger conditions met" : "No matching trigger")
+	};
+}
+//#endregion
+export { createTraceEntry, createWorkflowDecision };
+
+//# sourceMappingURL=decision-trace.js.map

package/dist/trigger/jsonpath-matcher.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Match all JSONPath expressions in `match` against `payload`.
+ *
+ * Each key in `match` is a JSONPath expression (e.g. `$.env`).
+ * Each value is the expected match: exact value, regex string (wrapped in /.../ or /..../flags),
+ * or array of acceptable values.
+ *
+ * ALL expressions must match for the overall result to be true.
+ * An empty `match` object matches everything.
+ *
+ * @param payload - The event payload to match against
+ * @param match - Map of JSONPath expressions to expected values
+ * @returns true if all expressions match
+ */
+export declare function matchJsonPath(payload: Record<string, unknown>, match: Record<string, unknown>): boolean;
+/**
+ * Negative JSONPath filter.
+ *
+ * Returns true if NONE of the `not` expressions match against `payload`.
+ * If `not` is undefined or empty, returns true (no negative filter = pass).
+ *
+ * @param payload - The event payload to match against
+ * @param not - Map of JSONPath expressions that should NOT match
+ * @returns true if none of the expressions match
+ */
+export declare function matchJsonPathNot(payload: Record<string, unknown>, not: Record<string, unknown> | undefined): boolean;
+//# sourceMappingURL=jsonpath-matcher.d.ts.map

package/dist/trigger/jsonpath-matcher.js

@@ -0,0 +1,92 @@
+import "../chunk-gOLHoazu.js";
+import { JSONPath } from "jsonpath-plus";
+//#region src/trigger/jsonpath-matcher.ts
+/**
+* JSONPath payload matching utility for trigger evaluation.
+*
+* Evaluates JSONPath expressions against webhook/event payloads for
+* kici_event and generic_webhook trigger types.
+*
+* Uses jsonpath-plus for JSONPath evaluation.
+*/
+/**
+* Match all JSONPath expressions in `match` against `payload`.
+*
+* Each key in `match` is a JSONPath expression (e.g. `$.env`).
+* Each value is the expected match: exact value, regex string (wrapped in /.../ or /..../flags),
+* or array of acceptable values.
+*
+* ALL expressions must match for the overall result to be true.
+* An empty `match` object matches everything.
+*
+* @param payload - The event payload to match against
+* @param match - Map of JSONPath expressions to expected values
+* @returns true if all expressions match
+*/
+function matchJsonPath(payload, match) {
+	const entries = Object.entries(match);
+	if (entries.length === 0) return true;
+	for (const [path, expected] of entries) {
+		const results = JSONPath({
+			path,
+			json: payload,
+			wrap: true
+		});
+		if (results.length === 0) return false;
+		if (!matchValue(results, expected)) return false;
+	}
+	return true;
+}
+/**
+* Negative JSONPath filter.
+*
+* Returns true if NONE of the `not` expressions match against `payload`.
+* If `not` is undefined or empty, returns true (no negative filter = pass).
+*
+* @param payload - The event payload to match against
+* @param not - Map of JSONPath expressions that should NOT match
+* @returns true if none of the expressions match
+*/
+function matchJsonPathNot(payload, not) {
+	if (!not) return true;
+	const entries = Object.entries(not);
+	if (entries.length === 0) return true;
+	for (const [path, expected] of entries) {
+		const results = JSONPath({
+			path,
+			json: payload,
+			wrap: true
+		});
+		if (results.length === 0) continue;
+		if (matchValue(results, expected)) return false;
+	}
+	return true;
+}
+/**
+* Check if any element in JSONPath results matches the expected value.
+*
+* Supports:
+* - Exact value comparison (primitives)
+* - Array of acceptable values (any match = pass)
+* - Regex string matching (for string results, wrapped in /pattern/ or /pattern/flags)
+*/
+function matchValue(results, expected) {
+	if (Array.isArray(expected)) return results.some((r) => expected.some((e) => valueEquals(r, e)));
+	return results.some((r) => valueEquals(r, expected));
+}
+/**
+* Compare a single result to an expected value.
+* For string expected values, supports regex patterns wrapped in /.../ or /.../flags.
+*/
+function valueEquals(result, expected) {
+	if (typeof expected === "string" && typeof result === "string") {
+		const regexMatch = /^\/(.+)\/([gimsuy]*)$/.exec(expected);
+		if (regexMatch) return new RegExp(regexMatch[1], regexMatch[2]).test(result);
+		return result === expected;
+	}
+	return result === expected;
+}
+//#endregion
+export { matchJsonPath, matchJsonPathNot };
+
+//# sourceMappingURL=jsonpath-matcher.js.map

package/dist/trigger/matcher.d.ts

@@ -0,0 +1,29 @@
+import type { LockWorkflow, LockBranchPattern, SimulatedEvent } from './types.js';
+import { type WorkflowDecision } from './decision-trace.js';
+/**
+ * Match a branch pattern against a branch name.
+ */
+export declare function matchBranchPattern(pattern: LockBranchPattern, branch: string): boolean;
+/**
+ * Match path patterns against changed files.
+ * Patterns prefixed with ! are exclusions. Remaining patterns are inclusions.
+ * An all-negation array has implicit match-all semantics for non-excluded files.
+ */
+export declare function matchPathPatterns(paths: readonly string[], changedFiles: string[]): boolean;
+/**
+ * Match repo patterns against a source repository identifier.
+ * Patterns with ! prefix in the pattern string are exclusions.
+ * An all-negation array has implicit match-all semantics for non-excluded repos.
+ * Empty array = no filtering (matches all repos).
+ */
+export declare function matchRepoPatterns(repos: readonly LockBranchPattern[], sourceRepo: string): boolean;
+/**
+ * Match all triggers for a workflow against an event.
+ * Returns WorkflowDecision with full trace.
+ */
+export declare function matchWorkflowTriggers(workflow: LockWorkflow, event: SimulatedEvent): WorkflowDecision;
+/**
+ * Match all workflows against an event.
+ */
+export declare function matchAllWorkflows(workflows: readonly LockWorkflow[], event: SimulatedEvent): WorkflowDecision[];
+//# sourceMappingURL=matcher.d.ts.map