@kici-dev/sdk 0.0.0 → 0.1.1

package/dist/validation/dag.js

@@ -0,0 +1,70 @@
+import "../chunk-gOLHoazu.js";
+//#region src/validation/dag.ts
+/**
+* Validate a DAG for common issues: self-references, missing dependencies, and cycles.
+*
+* Validation order:
+* 1. Check for self-references (node depends on itself)
+* 2. Check for missing dependencies (depends on non-existent node)
+* 3. Check for cycles using Kahn's algorithm
+*
+* @param nodes - Array of DAG nodes to validate
+* @returns Validation result with error details or sorted order
+*/
+function validateDag(nodes) {
+	if (nodes.length === 0) return {
+		valid: true,
+		sortedOrder: []
+	};
+	const nodeIds = new Set(nodes.map((n) => n.id));
+	for (const node of nodes) if (node.needs.includes(node.id)) return {
+		valid: false,
+		error: "self-reference",
+		nodeId: node.id
+	};
+	for (const node of nodes) for (const dep of node.needs) if (!nodeIds.has(dep)) return {
+		valid: false,
+		error: "missing-dependency",
+		nodeId: node.id,
+		missingDep: dep
+	};
+	const adjacencyList = /* @__PURE__ */ new Map();
+	const inDegree = /* @__PURE__ */ new Map();
+	for (const node of nodes) {
+		adjacencyList.set(node.id, []);
+		inDegree.set(node.id, 0);
+	}
+	for (const node of nodes) for (const dep of node.needs) {
+		adjacencyList.get(dep).push(node.id);
+		inDegree.set(node.id, (inDegree.get(node.id) ?? 0) + 1);
+	}
+	const queue = [];
+	for (const [id, degree] of inDegree) if (degree === 0) queue.push(id);
+	const sortedOrder = [];
+	while (queue.length > 0) {
+		const current = queue.shift();
+		sortedOrder.push(current);
+		for (const neighbor of adjacencyList.get(current) ?? []) {
+			const newDegree = (inDegree.get(neighbor) ?? 0) - 1;
+			inDegree.set(neighbor, newDegree);
+			if (newDegree === 0) queue.push(neighbor);
+		}
+	}
+	if (sortedOrder.length !== nodes.length) {
+		const cycleNodes = [];
+		for (const [id, degree] of inDegree) if (degree > 0) cycleNodes.push(id);
+		return {
+			valid: false,
+			error: "cycle",
+			nodesInCycle: cycleNodes
+		};
+	}
+	return {
+		valid: true,
+		sortedOrder
+	};
+}
+//#endregion
+export { validateDag };
+
+//# sourceMappingURL=dag.js.map

package/dist/validation/index.d.ts

@@ -0,0 +1,3 @@
+export { validateDag } from './dag.js';
+export type { DagNode, DagValidationResult } from './dag.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/validation/index.js

@@ -0,0 +1,3 @@
+import "../chunk-gOLHoazu.js";
+import { validateDag } from "./dag.js";
+export { validateDag };

package/dist/wait-for.d.ts

@@ -0,0 +1,109 @@
+/**
+ * SDK wait-for helpers for workflow authors.
+ *
+ * Workflows often need to pause until an external condition becomes
+ * true — a resource finishes provisioning, a file appears on disk, an
+ * HTTP endpoint returns a healthy response, an external job reaches a
+ * terminal state. The helpers in this file express that pattern with
+ * the same shape as `idempotent` / `idempotentStep`:
+ *
+ * - `check()` returns the resolved value when the condition is met, or
+ *   `null` to keep polling.
+ * - Optional `onSuccess(value)` runs once after the wait succeeds; its
+ *   return value becomes the step result.
+ * - Optional `onTimeout({ elapsedMs, attempts })` runs if the deadline
+ *   is exceeded; its return value becomes the step result. If absent,
+ *   the helper throws a typed `WaitForTimeoutError` so the step fails.
+ * - Errors thrown by `check()` are swallowed by default (matching the
+ *   "poll-until-healthy" pattern). Opt out via `swallowErrors: false`.
+ *
+ * Cancellation: the helper has no `AbortSignal` plumbing. A `check()`
+ * that takes longer than `intervalMs` is not aborted mid-flight; the
+ * loop only inspects the deadline at the top of each iteration. The
+ * step's own `timeout` field is the hard kill.
+ *
+ * Two entry points:
+ *
+ * - `waitFor(options)` — generic helper callable from any step, hook,
+ *   or bare async function. Resolves to the discriminated result.
+ * - `waitForStep(name, options)` — factory returning an SDK `Step`
+ *   whose run function executes `waitFor(...)` and propagates status
+ *   lines into `ctx.log.info`.
+ */
+import type { Step } from './types.js';
+export interface WaitForOptions<TValue, TSuccess = void, TTimeout = void> {
+    /** Optional name surfaced in status lines and the timeout error. */
+    name?: string;
+    /** Polled inspection. Return the resolved value when the condition
+     *  is met, or `null` to keep polling. */
+    check: () => Promise<TValue | null>;
+    /** Time between successive `check()` invocations, in milliseconds.
+     *  Defaults to 2000. */
+    intervalMs?: number;
+    /** Total time budget for the wait, in milliseconds. Defaults to
+     *  60000. The deadline is inspected at the top of each iteration. */
+    timeoutMs?: number;
+    /** Time to wait before the first `check()` invocation, in
+     *  milliseconds. Defaults to 0. */
+    initialDelayMs?: number;
+    /** Optional success action. Runs once after `check()` returns a
+     *  non-null value. Its return value is surfaced as `result` on the
+     *  'succeeded' outcome. */
+    onSuccess?: (value: TValue) => Promise<TSuccess>;
+    /** Optional timeout action. Runs when the deadline is exceeded. Its
+     *  return value is surfaced as `result` on the 'timed-out' outcome.
+     *  When omitted, the helper throws a `WaitForTimeoutError` instead. */
+    onTimeout?: (info: {
+        elapsedMs: number;
+        attempts: number;
+    }) => Promise<TTimeout>;
+    /** When `true` (default), errors thrown by `check()` are logged and
+     *  swallowed so polling continues. When `false`, the first error
+     *  propagates out of the helper. */
+    swallowErrors?: boolean;
+    /** Sink for status lines. Defaults to console.log. */
+    log?: (line: string) => void;
+}
+/**
+ * The discriminated result of a `waitFor` invocation. Narrow on
+ * `outcome` to read the correct branch.
+ */
+export type WaitForResult<TValue, TSuccess = void, TTimeout = void> = {
+    outcome: 'succeeded';
+    value: TValue;
+    elapsedMs: number;
+    attempts: number;
+    result: TSuccess;
+} | {
+    outcome: 'timed-out';
+    elapsedMs: number;
+    attempts: number;
+    result: TTimeout;
+};
+/**
+ * Thrown by `waitFor` when the deadline is exceeded and no
+ * `onTimeout` callback was supplied. The instance fields expose the
+ * wait stats so callers can branch on them in a catch block.
+ */
+export declare class WaitForTimeoutError extends Error {
+    /** The step name supplied via `WaitForOptions.name` (or 'waitFor'). */
+    readonly stepName: string;
+    /** Wall-clock duration of the wait, in milliseconds. */
+    readonly elapsedMs: number;
+    /** Number of `check()` invocations that ran before the timeout. */
+    readonly attempts: number;
+    constructor(stepName: string, elapsedMs: number, attempts: number);
+}
+/**
+ * Generic wait-for helper for use inside any step, hook, or bare
+ * async function. Polls `check()` on a fixed interval until it returns
+ * a non-null value or the deadline is exceeded.
+ */
+export declare function waitFor<TValue, TSuccess = void, TTimeout = void>(opts: WaitForOptions<TValue, TSuccess, TTimeout>): Promise<WaitForResult<TValue, TSuccess, TTimeout>>;
+/**
+ * Factory returning an SDK Step whose run function executes
+ * `waitFor(...)`. Status lines are routed through `ctx.log.info`.
+ * The step's typed return value is the WaitForResult union.
+ */
+export declare function waitForStep<TValue, TSuccess = void, TTimeout = void>(name: string, opts: Omit<WaitForOptions<TValue, TSuccess, TTimeout>, 'name' | 'log'>): Step<WaitForResult<TValue, TSuccess, TTimeout>>;
+//# sourceMappingURL=wait-for.d.ts.map

package/dist/wait-for.js

@@ -0,0 +1,144 @@
+import "./chunk-gOLHoazu.js";
+import { step } from "./step.js";
+//#region src/wait-for.ts
+/**
+* SDK wait-for helpers for workflow authors.
+*
+* Workflows often need to pause until an external condition becomes
+* true — a resource finishes provisioning, a file appears on disk, an
+* HTTP endpoint returns a healthy response, an external job reaches a
+* terminal state. The helpers in this file express that pattern with
+* the same shape as `idempotent` / `idempotentStep`:
+*
+* - `check()` returns the resolved value when the condition is met, or
+*   `null` to keep polling.
+* - Optional `onSuccess(value)` runs once after the wait succeeds; its
+*   return value becomes the step result.
+* - Optional `onTimeout({ elapsedMs, attempts })` runs if the deadline
+*   is exceeded; its return value becomes the step result. If absent,
+*   the helper throws a typed `WaitForTimeoutError` so the step fails.
+* - Errors thrown by `check()` are swallowed by default (matching the
+*   "poll-until-healthy" pattern). Opt out via `swallowErrors: false`.
+*
+* Cancellation: the helper has no `AbortSignal` plumbing. A `check()`
+* that takes longer than `intervalMs` is not aborted mid-flight; the
+* loop only inspects the deadline at the top of each iteration. The
+* step's own `timeout` field is the hard kill.
+*
+* Two entry points:
+*
+* - `waitFor(options)` — generic helper callable from any step, hook,
+*   or bare async function. Resolves to the discriminated result.
+* - `waitForStep(name, options)` — factory returning an SDK `Step`
+*   whose run function executes `waitFor(...)` and propagates status
+*   lines into `ctx.log.info`.
+*/
+/**
+* Thrown by `waitFor` when the deadline is exceeded and no
+* `onTimeout` callback was supplied. The instance fields expose the
+* wait stats so callers can branch on them in a catch block.
+*/
+var WaitForTimeoutError = class extends Error {
+	/** The step name supplied via `WaitForOptions.name` (or 'waitFor'). */
+	stepName;
+	/** Wall-clock duration of the wait, in milliseconds. */
+	elapsedMs;
+	/** Number of `check()` invocations that ran before the timeout. */
+	attempts;
+	constructor(stepName, elapsedMs, attempts) {
+		super(`${stepName}: timed out after ${elapsedMs}ms (attempts=${attempts})`);
+		this.name = "WaitForTimeoutError";
+		this.stepName = stepName;
+		this.elapsedMs = elapsedMs;
+		this.attempts = attempts;
+	}
+};
+const DEFAULT_NAME = "waitFor";
+const DEFAULT_INTERVAL_MS = 2e3;
+const DEFAULT_TIMEOUT_MS = 6e4;
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function runCheckOnce(check, swallowErrors, log, name, attempt) {
+	try {
+		return { value: await check() };
+	} catch (err) {
+		if (!swallowErrors) throw err;
+		log(`! ${name} — attempt ${attempt} error swallowed: ${err instanceof Error ? err.message : String(err)}`);
+		return { value: null };
+	}
+}
+/**
+* Generic wait-for helper for use inside any step, hook, or bare
+* async function. Polls `check()` on a fixed interval until it returns
+* a non-null value or the deadline is exceeded.
+*/
+async function waitFor(opts) {
+	const name = opts.name ?? DEFAULT_NAME;
+	const intervalMs = opts.intervalMs ?? DEFAULT_INTERVAL_MS;
+	const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const initialDelayMs = opts.initialDelayMs ?? 0;
+	const swallowErrors = opts.swallowErrors ?? true;
+	const log = opts.log ?? ((line) => console.log(line));
+	log(`→ ${name} — waiting (timeout=${timeoutMs}ms, interval=${intervalMs}ms)`);
+	const startedAt = Date.now();
+	const deadline = startedAt + timeoutMs;
+	if (initialDelayMs > 0) await sleep(initialDelayMs);
+	let attempts = 0;
+	while (Date.now() < deadline) {
+		attempts += 1;
+		const { value } = await runCheckOnce(opts.check, swallowErrors, log, name, attempts);
+		if (value !== null) {
+			const elapsedMs = Date.now() - startedAt;
+			log(`✓ ${name} — succeeded after ${elapsedMs}ms (attempts=${attempts})`);
+			const result = opts.onSuccess ? await opts.onSuccess(value) : void 0;
+			return {
+				outcome: "succeeded",
+				value,
+				elapsedMs,
+				attempts,
+				result
+			};
+		}
+		const remaining = deadline - Date.now();
+		if (remaining <= 0) break;
+		await sleep(Math.min(intervalMs, remaining));
+	}
+	const elapsedMs = Date.now() - startedAt;
+	log(`✗ ${name} — timed out after ${elapsedMs}ms (attempts=${attempts})`);
+	if (opts.onTimeout) {
+		const result = await opts.onTimeout({
+			elapsedMs,
+			attempts
+		});
+		return {
+			outcome: "timed-out",
+			elapsedMs,
+			attempts,
+			result
+		};
+	}
+	throw new WaitForTimeoutError(name, elapsedMs, attempts);
+}
+/**
+* Factory returning an SDK Step whose run function executes
+* `waitFor(...)`. Status lines are routed through `ctx.log.info`.
+* The step's typed return value is the WaitForResult union.
+*/
+function waitForStep(name, opts) {
+	return step(name, { run: async (ctx) => waitFor({
+		name,
+		check: opts.check,
+		intervalMs: opts.intervalMs,
+		timeoutMs: opts.timeoutMs,
+		initialDelayMs: opts.initialDelayMs,
+		onSuccess: opts.onSuccess,
+		onTimeout: opts.onTimeout,
+		swallowErrors: opts.swallowErrors,
+		log: (line) => ctx.log.info(line)
+	}) });
+}
+//#endregion
+export { WaitForTimeoutError, waitFor, waitForStep };
+
+//# sourceMappingURL=wait-for.js.map

package/dist/workflow.d.ts

@@ -0,0 +1,3 @@
+import type { Workflow, WorkflowOptions } from './types.js';
+export declare function workflow(name: string, options: WorkflowOptions): Workflow;
+//# sourceMappingURL=workflow.d.ts.map

package/dist/workflow.js

@@ -0,0 +1,83 @@
+import "./chunk-gOLHoazu.js";
+//#region src/workflow.ts
+/**
+* Normalize triggers to array.
+* Handles single trigger config or array of trigger configs.
+*/
+function normalizeTriggers(on) {
+	if (!on) return void 0;
+	return Array.isArray(on) ? on : [on];
+}
+/**
+* Create a workflow containing jobs.
+*
+* @example
+* // Simple workflow
+* export default workflow('ci', {
+*   jobs: [build, test, deploy],
+* });
+*
+* @example
+* // Workflow with triggers and rules
+* export default workflow('ci', {
+*   on: [pr({ target: 'main' }), push({ branches: 'main' })],
+*   jobs: [build, test, deploy],
+*   rules: [rule('has src changes')],
+*   description: 'Main CI pipeline',
+* });
+*/
+/**
+* Validates a `<environment>:<secret-name>` qualified secret reference.
+* Both halves must be non-empty and free of additional colons.
+*/
+function isQualifiedSecretRef(value) {
+	const idx = value.indexOf(":");
+	if (idx <= 0 || idx >= value.length - 1) return false;
+	const env = value.slice(0, idx);
+	const name = value.slice(idx + 1);
+	return env.length > 0 && name.length > 0 && !name.includes(":");
+}
+function workflow(name, options) {
+	if (options.registries) {
+		const seenScopes = /* @__PURE__ */ new Set();
+		let defaultCount = 0;
+		for (const [i, reg] of options.registries.entries()) {
+			try {
+				new URL(reg.url);
+			} catch {
+				throw new Error(`workflow('${name}'): registries[${i}].url is not a valid URL: ${reg.url}`);
+			}
+			if (!isQualifiedSecretRef(reg.tokenSecret)) throw new Error(`workflow('${name}'): registries[${i}].tokenSecret must use qualified <environment>:<secret-name> syntax (got: ${reg.tokenSecret})`);
+			if (reg.scope === void 0) defaultCount += 1;
+			else {
+				if (!/^@[a-z0-9][a-z0-9-]*$/i.test(reg.scope)) throw new Error(`workflow('${name}'): registries[${i}].scope must match @<package-scope> (got: ${reg.scope})`);
+				if (seenScopes.has(reg.scope)) throw new Error(`workflow('${name}'): registries declares scope ${reg.scope} more than once`);
+				seenScopes.add(reg.scope);
+			}
+		}
+		if (defaultCount > 1) throw new Error(`workflow('${name}'): at most one registries entry may omit \`scope\` (default registry); got ${defaultCount}`);
+	}
+	if (options.installEnv) {
+		for (const [i, ref] of options.installEnv.entries()) if (!isQualifiedSecretRef(ref)) throw new Error(`workflow('${name}'): installEnv[${i}] must use qualified <environment>:<secret-name> syntax (got: ${ref})`);
+	}
+	return {
+		_tag: "Workflow",
+		name,
+		jobs: options.jobs,
+		on: normalizeTriggers(options.on),
+		rules: options.rules,
+		description: options.description,
+		hashFiles: options.hashFiles,
+		registries: options.registries,
+		installEnv: options.installEnv,
+		onCancel: options.onCancel,
+		cleanup: options.cleanup,
+		onSuccess: options.onSuccess,
+		onFailure: options.onFailure,
+		concurrency: options.concurrency
+	};
+}
+//#endregion
+export { workflow };
+
+//# sourceMappingURL=workflow.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/sdk",
-  "version": "0.0.0",
+  "version": "0.1.1",
   "description": "TypeScript SDK for defining KiCI workflows. Import into `.kici/workflows/*.ts` to declare workflows, jobs, steps, triggers, rules, and matrix configurations.",
   "keywords": [
     "kici",
@@ -9,7 +9,9 @@
     "ci-cd",
     "typescript",
     "workflows",
-    "devops"
+    "devops",
+    "sdk",
+    "dsl"
   ],
   "homepage": "https://kici.dev",
   "author": {
@@ -17,9 +19,44 @@
     "email": "hello@kici.dev"
   },
   "license": "Apache-2.0",
-  "main": "index.js",
+  "engines": {
+    "node": ">=24"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "sbom.spdx.json"
+  ],
   "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-ts.mjs && tsc --emitDeclarationOnly",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npx tsx ../../hack/generate-sbom.ts --package packages/sdk --name @kici-dev/sdk"
+  },
+  "dependencies": {
+    "@kici-dev/engine": "workspace:*",
+    "@kici-dev/shared": "workspace:*",
+    "fast-cartesian": "^9.0.1",
+    "micromatch": "^4.0.8",
+    "zod": "^4.3.6",
+    "zx": "^8.8.5"
+  },
+  "devDependencies": {
+    "@types/micromatch": "^4.0.10"
   }
 }