@kici-dev/sdk 0.0.0 → 0.1.1

package/dist/events/event-payloads.d.ts

@@ -0,0 +1,396 @@
+/**
+ * Typed event payload discriminated union for rule authors.
+ *
+ * Provides autocomplete when narrowing on `ctx.event.type` in rule functions.
+ * Each variant carries partial GitHub payload types for the most commonly
+ * accessed fields. The index signature on each payload interface allows
+ * accessing fields not explicitly typed (they resolve to `unknown`).
+ *
+ * The runtime shape mirrors SimulatedEvent from @kici-dev/engine — these types
+ * are the user-facing view of the same data. Keep them in sync when adding new
+ * event types or SimulatedEvent fields.
+ */
+/** Partial GitHub repository object. */
+export interface GitHubRepository {
+    full_name: string;
+    default_branch: string;
+    name?: string;
+    owner?: {
+        login: string;
+        [key: string]: unknown;
+    };
+    private?: boolean;
+    [key: string]: unknown;
+}
+/** Partial GitHub user/sender object. */
+export interface GitHubUser {
+    login: string;
+    id?: number;
+    [key: string]: unknown;
+}
+/** Partial GitHub pull request object. */
+export interface GitHubPullRequest {
+    number: number;
+    draft?: boolean;
+    title?: string;
+    body?: string;
+    state?: string;
+    merged?: boolean;
+    head: {
+        ref: string;
+        sha: string;
+        repo?: {
+            full_name: string;
+            [key: string]: unknown;
+        };
+        [key: string]: unknown;
+    };
+    base: {
+        ref: string;
+        repo?: {
+            full_name: string;
+            [key: string]: unknown;
+        };
+        [key: string]: unknown;
+    };
+    user?: GitHubUser;
+    labels?: Array<{
+        name: string;
+        [key: string]: unknown;
+    }>;
+    [key: string]: unknown;
+}
+/** Partial GitHub commit object (from push events). */
+export interface GitHubCommit {
+    id: string;
+    message: string;
+    author?: {
+        name?: string;
+        email?: string;
+        username?: string;
+        [key: string]: unknown;
+    };
+    timestamp?: string;
+    added?: string[];
+    removed?: string[];
+    modified?: string[];
+    [key: string]: unknown;
+}
+/** Partial GitHub comment object (issue_comment events). */
+export interface GitHubComment {
+    id: number;
+    body: string;
+    user: GitHubUser;
+    [key: string]: unknown;
+}
+/** Partial GitHub review object. */
+export interface GitHubReview {
+    id: number;
+    state: string;
+    body?: string;
+    user: GitHubUser;
+    [key: string]: unknown;
+}
+/** Partial GitHub release object. */
+export interface GitHubRelease {
+    id: number;
+    tag_name: string;
+    name?: string;
+    body?: string;
+    draft?: boolean;
+    prerelease?: boolean;
+    target_commitish?: string;
+    [key: string]: unknown;
+}
+/** Base fields present on all event payloads. */
+export interface EventBase {
+    /** Normalized event type discriminant. */
+    type: string;
+    /** Sub-action (e.g. 'opened', 'created', 'submitted'). */
+    action?: string;
+    /** Target branch (push target, PR base, or default branch). */
+    targetBranch?: string;
+    /** Source branch (PR head branch). Only set for PR-like events. */
+    sourceBranch?: string;
+    /** Provider that originated this event. */
+    provider?: string;
+    /** Whether this PR comes from a fork. Only set for PR-like events. */
+    isForkPR?: boolean;
+    /** Base branch ref for PR events. */
+    baseBranch?: string;
+    /** Sender username from the webhook payload. */
+    senderUsername?: string;
+    /** Repository identifier (e.g. "owner/repo"). */
+    sourceRepo?: string;
+    /** Files changed in this event (for path filtering). */
+    changedFiles?: string[];
+    /** Raw webhook payload from the provider. May be absent in flattened event forms. */
+    payload?: Record<string, unknown>;
+    /** Index signature for backward compatibility — untyped fields resolve to unknown. */
+    [key: string]: unknown;
+}
+/** Pull request event payload. */
+export interface PullRequestEventPayload extends EventBase {
+    type: 'pull_request';
+    action: string;
+    payload: {
+        action: string;
+        number: number;
+        pull_request: GitHubPullRequest;
+        repository: GitHubRepository;
+        sender: GitHubUser;
+        [key: string]: unknown;
+    };
+}
+/** Push event payload. */
+export interface PushEventPayload extends EventBase {
+    type: 'push';
+    payload: {
+        ref: string;
+        after: string;
+        before: string;
+        head_commit?: GitHubCommit;
+        commits?: GitHubCommit[];
+        repository: GitHubRepository;
+        sender?: GitHubUser;
+        forced?: boolean;
+        [key: string]: unknown;
+    };
+}
+/** Tag push event payload. */
+export interface TagEventPayload extends EventBase {
+    type: 'tag';
+    payload: {
+        ref: string;
+        after: string;
+        repository: GitHubRepository;
+        sender?: GitHubUser;
+        [key: string]: unknown;
+    };
+}
+/** Issue/PR comment event payload. */
+export interface CommentEventPayload extends EventBase {
+    type: 'comment';
+    action: string;
+    payload: {
+        action: string;
+        comment: GitHubComment;
+        issue?: {
+            number: number;
+            title?: string;
+            pull_request?: unknown;
+            [key: string]: unknown;
+        };
+        repository: GitHubRepository;
+        sender: GitHubUser;
+        [key: string]: unknown;
+    };
+}
+/** Pull request review event payload. */
+export interface ReviewEventPayload extends EventBase {
+    type: 'review';
+    action: string;
+    payload: {
+        action: string;
+        review: GitHubReview;
+        pull_request: GitHubPullRequest;
+        repository: GitHubRepository;
+        sender: GitHubUser;
+        [key: string]: unknown;
+    };
+}
+/** Pull request review comment event payload. */
+export interface ReviewCommentEventPayload extends EventBase {
+    type: 'review_comment';
+    action: string;
+    payload: {
+        action: string;
+        comment: GitHubComment;
+        pull_request: GitHubPullRequest;
+        repository: GitHubRepository;
+        sender: GitHubUser;
+        [key: string]: unknown;
+    };
+}
+/** Release event payload. */
+export interface ReleaseEventPayload extends EventBase {
+    type: 'release';
+    action: string;
+    payload: {
+        action: string;
+        release: GitHubRelease;
+        repository: GitHubRepository;
+        sender: GitHubUser;
+        [key: string]: unknown;
+    };
+}
+/** Repository dispatch event payload. */
+export interface DispatchEventPayload extends EventBase {
+    type: 'dispatch';
+    payload: {
+        action: string;
+        client_payload?: Record<string, unknown>;
+        repository: GitHubRepository;
+        sender?: GitHubUser;
+        [key: string]: unknown;
+    };
+}
+/** Branch/tag create event payload. */
+export interface CreateEventPayload extends EventBase {
+    type: 'create';
+    payload: {
+        ref: string;
+        ref_type: string;
+        repository: GitHubRepository;
+        sender: GitHubUser;
+        [key: string]: unknown;
+    };
+}
+/** Branch/tag delete event payload. */
+export interface DeleteEventPayload extends EventBase {
+    type: 'delete';
+    payload: {
+        ref: string;
+        ref_type: string;
+        repository: GitHubRepository;
+        sender: GitHubUser;
+        [key: string]: unknown;
+    };
+}
+/** Commit status event payload. */
+export interface StatusEventPayload extends EventBase {
+    type: 'status';
+    payload: {
+        state: string;
+        sha: string;
+        context: string;
+        description?: string;
+        target_url?: string;
+        branches?: Array<{
+            name: string;
+            [key: string]: unknown;
+        }>;
+        repository: GitHubRepository;
+        sender: GitHubUser;
+        [key: string]: unknown;
+    };
+}
+/** Workflow run event payload. */
+export interface WorkflowRunEventPayload extends EventBase {
+    type: 'workflow_run';
+    action: string;
+    payload: {
+        action: string;
+        workflow_run: {
+            head_branch: string;
+            name: string;
+            conclusion?: string;
+            status?: string;
+            [key: string]: unknown;
+        };
+        repository: GitHubRepository;
+        sender: GitHubUser;
+        [key: string]: unknown;
+    };
+}
+/** Fork event payload. */
+export interface ForkEventPayload extends EventBase {
+    type: 'fork';
+    payload: {
+        forkee: {
+            full_name: string;
+            [key: string]: unknown;
+        };
+        repository: GitHubRepository;
+        sender: GitHubUser;
+        [key: string]: unknown;
+    };
+}
+/** Star event payload. */
+export interface StarEventPayload extends EventBase {
+    type: 'star';
+    action: string;
+    payload: {
+        action: string;
+        repository: GitHubRepository;
+        sender: GitHubUser;
+        [key: string]: unknown;
+    };
+}
+/** Watch event payload. */
+export interface WatchEventPayload extends EventBase {
+    type: 'watch';
+    action: string;
+    payload: {
+        action: string;
+        repository: GitHubRepository;
+        sender: GitHubUser;
+        [key: string]: unknown;
+    };
+}
+/** Webhook trigger event payload. */
+export interface WebhookEventPayload extends EventBase {
+    type: 'webhook';
+}
+/** Custom KiCI event payload (emitted via ctx.emit). */
+export interface KiciEventPayload extends EventBase {
+    type: 'kici_event';
+}
+/** Workflow complete internal event payload. */
+export interface WorkflowCompleteEventPayload extends EventBase {
+    type: 'workflow_complete';
+}
+/** Job complete internal event payload. */
+export interface JobCompleteEventPayload extends EventBase {
+    type: 'job_complete';
+}
+/** Generic webhook event payload. */
+export interface GenericWebhookEventPayload extends EventBase {
+    type: 'generic_webhook';
+}
+/** Schedule (cron) event payload. */
+export interface ScheduleEventPayload extends EventBase {
+    type: 'schedule';
+}
+/** Lifecycle event payload. */
+export interface LifecycleEventPayload extends EventBase {
+    type: 'lifecycle';
+}
+/** Re-run event payload. */
+export interface RerunEventPayload extends EventBase {
+    type: 'rerun';
+}
+/** Manual schedule event payload. */
+export interface ManualScheduleEventPayload extends EventBase {
+    type: 'manual_schedule';
+}
+/** Fallback for unknown/future event types. */
+export interface UnknownEventPayload extends EventBase {
+    type: string;
+}
+/**
+ * Typed event payload — discriminated union over the `type` field.
+ *
+ * Narrow with `if (ctx.event.type === 'pull_request')` to get autocomplete
+ * on provider-specific fields like `ctx.event.payload.pull_request.draft`.
+ *
+ * For unrecognized event types, falls back to {@link UnknownEventPayload}
+ * which retains the index signature for backward-compatible property access.
+ */
+export type EventPayload = PullRequestEventPayload | PushEventPayload | TagEventPayload | CommentEventPayload | ReviewEventPayload | ReviewCommentEventPayload | ReleaseEventPayload | DispatchEventPayload | CreateEventPayload | DeleteEventPayload | StatusEventPayload | WorkflowRunEventPayload | ForkEventPayload | StarEventPayload | WatchEventPayload | WebhookEventPayload | KiciEventPayload | WorkflowCompleteEventPayload | JobCompleteEventPayload | GenericWebhookEventPayload | ScheduleEventPayload | LifecycleEventPayload | RerunEventPayload | ManualScheduleEventPayload | UnknownEventPayload;
+/**
+ * Narrow an EventPayload to a specific event type.
+ *
+ * @example
+ * ```ts
+ * rule('only-draft-prs', (ctx) => {
+ *   if (!isEventType(ctx.event, 'pull_request')) return false;
+ *   // ctx.event is now PullRequestEventPayload
+ *   return ctx.event.payload.pull_request.draft === true;
+ * });
+ * ```
+ */
+export declare function isEventType<T extends EventPayload['type']>(event: EventPayload, type: T): event is Extract<EventPayload, {
+    type: T;
+}>;
+//# sourceMappingURL=event-payloads.d.ts.map

package/dist/events/event-payloads.js

@@ -0,0 +1,21 @@
+import "../chunk-gOLHoazu.js";
+//#region src/events/event-payloads.ts
+/**
+* Narrow an EventPayload to a specific event type.
+*
+* @example
+* ```ts
+* rule('only-draft-prs', (ctx) => {
+*   if (!isEventType(ctx.event, 'pull_request')) return false;
+*   // ctx.event is now PullRequestEventPayload
+*   return ctx.event.payload.pull_request.draft === true;
+* });
+* ```
+*/
+function isEventType(event, type) {
+	return event.type === type;
+}
+//#endregion
+export { isEventType };
+
+//# sourceMappingURL=event-payloads.js.map

package/dist/events/index.d.ts

@@ -0,0 +1,6 @@
+export { defineEvent } from './define-event.js';
+export type { EventDefinition } from './define-event.js';
+export type { EventEmitOptions } from './types.js';
+export { isEventType } from './event-payloads.js';
+export type { EventPayload, EventBase } from './event-payloads.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/events/index.js

@@ -0,0 +1,4 @@
+import "../chunk-gOLHoazu.js";
+import { isEventType } from "./event-payloads.js";
+import { defineEvent } from "./define-event.js";
+export { defineEvent, isEventType };

package/dist/events/types.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Types for the event emission system.
+ */
+/**
+ * Options for event emission via ctx.emit().
+ */
+export interface EventEmitOptions {
+    /** Target specific repos for cross-repo event delivery. */
+    target?: {
+        repos?: string[];
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/events/types.js

@@ -0,0 +1,2 @@
+import "../chunk-gOLHoazu.js";
+export {};

package/dist/fixture.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Fixture factory for defining test event replicas.
+ *
+ * Fixtures declare which trigger event to simulate when running
+ * `kici test <name>`. They are event replicas (not assertions) --
+ * pass/fail is determined by the pipeline execution.
+ */
+import type { TriggerConfig } from './triggers/types.js';
+/** Options for configuring a test fixture */
+export interface FixtureOptions {
+    /** The trigger event to simulate (reuses existing SDK trigger types) */
+    event: TriggerConfig;
+    /** Override branch name (defaults to git-detected) */
+    branch?: string;
+    /** Override commit SHA (defaults to HEAD) */
+    sha?: string;
+    /** Override repository (defaults to git-detected) */
+    repo?: string;
+    /** For PR events, override PR number */
+    pr?: number;
+    /** Secret context mappings: { localName: 'remote-context-name' } */
+    secrets?: Record<string, string>;
+    /** If set, bypass trigger matching and run this workflow directly */
+    workflowName?: string;
+}
+/** Resolved fixture definition */
+export interface Fixture {
+    /** Unique fixture ID used in `kici test <name>` */
+    readonly id: string;
+    /** Fixture options (plain object or async factory function) */
+    readonly options: FixtureOptions | (() => FixtureOptions | Promise<FixtureOptions>);
+}
+/**
+ * Create a test fixture definition.
+ *
+ * @param id - Unique fixture ID (no whitespace allowed, used in `kici test <name>`)
+ * @param options - Fixture configuration or async factory function
+ * @returns Frozen fixture definition
+ *
+ * @example
+ * ```ts
+ * import { fixture, push } from '@kici-dev/sdk';
+ *
+ * export const pushMain = fixture('push-main', {
+ *   event: push({ branches: ['main'] }),
+ * });
+ * ```
+ */
+export declare function fixture(id: string, options: FixtureOptions | (() => FixtureOptions | Promise<FixtureOptions>)): Fixture;
+//# sourceMappingURL=fixture.d.ts.map

package/dist/fixture.js

@@ -0,0 +1,35 @@
+import "./chunk-gOLHoazu.js";
+//#region src/fixture.ts
+/**
+* Create a test fixture definition.
+*
+* @param id - Unique fixture ID (no whitespace allowed, used in `kici test <name>`)
+* @param options - Fixture configuration or async factory function
+* @returns Frozen fixture definition
+*
+* @example
+* ```ts
+* import { fixture, push } from '@kici-dev/sdk';
+*
+* export const pushMain = fixture('push-main', {
+*   event: push({ branches: ['main'] }),
+* });
+* ```
+*/
+function fixture(id, options) {
+	if (!id || id.length === 0) throw new Error("Fixture ID must be a non-empty string");
+	if (/\s/.test(id)) throw new Error(`Fixture ID must not contain whitespace: "${id}"`);
+	if (typeof options === "function") return Object.freeze({
+		id,
+		options
+	});
+	const frozenOptions = Object.freeze(options);
+	return Object.freeze({
+		id,
+		options: frozenOptions
+	});
+}
+//#endregion
+export { fixture };
+
+//# sourceMappingURL=fixture.js.map

package/dist/hooks/index.d.ts

@@ -0,0 +1,33 @@
+import type { HookConfig, HookInput } from './types.js';
+/**
+ * Create an onCancel hook config.
+ * Runs when the job/step is cancelled.
+ */
+export declare function onCancel(input: HookInput): HookConfig;
+/**
+ * Create a cleanup hook config.
+ * Always runs after job/step completion (success, failure, or cancel).
+ */
+export declare function cleanup(input: HookInput): HookConfig;
+/**
+ * Create an onSuccess hook config.
+ * Runs when the job/workflow succeeds.
+ */
+export declare function onSuccess(input: HookInput): HookConfig;
+/**
+ * Create an onFailure hook config.
+ * Runs when the job/workflow fails.
+ */
+export declare function onFailure(input: HookInput): HookConfig;
+/**
+ * Create a beforeStep hook config.
+ * Runs before each step in the job.
+ */
+export declare function beforeStep(input: HookInput): HookConfig;
+/**
+ * Create an afterStep hook config.
+ * Runs after each step in the job.
+ */
+export declare function afterStep(input: HookInput): HookConfig;
+export type { HookConfig, HookFn, HookInput, HookContext, OutcomeMetadata } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.js

@@ -0,0 +1,94 @@
+import "../chunk-gOLHoazu.js";
+//#region src/hooks/index.ts
+/**
+* Normalize HookInput to extract run function and optional timeout.
+*/
+function normalizeInput(input) {
+	if (typeof input === "function") return { run: input };
+	return {
+		run: input.run,
+		timeout: input.timeout
+	};
+}
+/**
+* Create an onCancel hook config.
+* Runs when the job/step is cancelled.
+*/
+function onCancel(input) {
+	const { run, timeout } = normalizeInput(input);
+	return {
+		name: "onCancel",
+		type: "onCancel",
+		run,
+		timeout
+	};
+}
+/**
+* Create a cleanup hook config.
+* Always runs after job/step completion (success, failure, or cancel).
+*/
+function cleanup(input) {
+	const { run, timeout } = normalizeInput(input);
+	return {
+		name: "cleanup",
+		type: "cleanup",
+		run,
+		timeout
+	};
+}
+/**
+* Create an onSuccess hook config.
+* Runs when the job/workflow succeeds.
+*/
+function onSuccess(input) {
+	const { run, timeout } = normalizeInput(input);
+	return {
+		name: "onSuccess",
+		type: "onSuccess",
+		run,
+		timeout
+	};
+}
+/**
+* Create an onFailure hook config.
+* Runs when the job/workflow fails.
+*/
+function onFailure(input) {
+	const { run, timeout } = normalizeInput(input);
+	return {
+		name: "onFailure",
+		type: "onFailure",
+		run,
+		timeout
+	};
+}
+/**
+* Create a beforeStep hook config.
+* Runs before each step in the job.
+*/
+function beforeStep(input) {
+	const { run, timeout } = normalizeInput(input);
+	return {
+		name: "beforeStep",
+		type: "beforeStep",
+		run,
+		timeout
+	};
+}
+/**
+* Create an afterStep hook config.
+* Runs after each step in the job.
+*/
+function afterStep(input) {
+	const { run, timeout } = normalizeInput(input);
+	return {
+		name: "afterStep",
+		type: "afterStep",
+		run,
+		timeout
+	};
+}
+//#endregion
+export { afterStep, beforeStep, cleanup, onCancel, onFailure, onSuccess };
+
+//# sourceMappingURL=index.js.map

package/dist/hooks/types.d.ts

@@ -0,0 +1,35 @@
+import type { StepContext } from '../context.js';
+/**
+ * Metadata about the job/workflow outcome, available to hooks.
+ */
+export interface OutcomeMetadata {
+    status: 'cancelled' | 'success' | 'failed';
+    reason?: string;
+    failedStep?: string;
+    stepOutputs: Record<string, unknown>;
+    duration: number;
+}
+/** Context passed to hook functions -- extends StepContext with outcome info. */
+export type HookContext = StepContext & {
+    outcome: OutcomeMetadata;
+};
+/** Hook function signature. Receives HookContext and returns void. */
+export type HookFn = (ctx: HookContext) => Promise<void>;
+/**
+ * Resolved hook configuration (used internally after normalization).
+ */
+export interface HookConfig {
+    name: string;
+    type: 'onCancel' | 'cleanup' | 'onSuccess' | 'onFailure' | 'beforeStep' | 'afterStep';
+    run: HookFn;
+    timeout?: number;
+}
+/**
+ * Hook input accepted by SDK interfaces.
+ * Either a bare function or an object with run function and optional timeout.
+ */
+export type HookInput = HookFn | {
+    run: HookFn;
+    timeout?: number;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/hooks/types.js

@@ -0,0 +1,2 @@
+import "../chunk-gOLHoazu.js";
+export {};