@kici-dev/sdk 0.0.0 → 0.1.1

package/dist/idempotent.d.ts

@@ -0,0 +1,71 @@
+/**
+ * SDK idempotency helpers for workflow authors.
+ *
+ * Workflows run unattended on agents — no operator at the prompt, no
+ * dry-run flag to flip. The helpers in this file expose the same
+ * check/apply discipline as the shared primitive but with a workflow
+ * shape:
+ *
+ * - apply on drift unconditionally (no confirm, no dryRun).
+ * - optional whenInSync() callback to surface the already-satisfied
+ *   resource when check() reports no drift (e.g. fetch an existing
+ *   resource id when a create-if-missing was already done).
+ * - typed return values threaded through both branches via the
+ *   discriminated IdempotentResult union.
+ *
+ * Two entry points:
+ *
+ * - `idempotent(options)` — generic helper callable from any step,
+ *   hook, or bare async function. Returns the discriminated result.
+ * - `idempotentStep(name, options)` — factory returning an SDK `Step`
+ *   whose run function executes `idempotent(...)` and propagates ctx.log
+ *   into the runner's status sink.
+ */
+import type { Step } from './types.js';
+export interface IdempotentOptions<TDrift, TInSync = void, TApplied = void> {
+    /** Optional name surfaced in status lines and error messages. */
+    name?: string;
+    /** Read-only inspection. Returns drift if apply() would change state,
+     *  or null if the system is already in the desired state. */
+    check: () => Promise<TDrift | null>;
+    /** Brings the system to the desired state. Its return value is
+     *  surfaced as `result` on the 'applied' outcome. */
+    apply: (drift: TDrift) => Promise<TApplied>;
+    /** Runs when check() returns null. Use to fetch the already-satisfied
+     *  resource. Its return value is surfaced as `result` on the
+     *  'skipped' outcome. */
+    whenInSync?: () => Promise<TInSync>;
+    /** Multi-line description of what apply() would do. Defaults to a
+     *  JSON dump of the drift value. */
+    summarize?: (drift: TDrift) => string;
+    /** Sink for status lines. Defaults to console.log. */
+    log?: (line: string) => void;
+}
+/**
+ * The result of an SDK idempotent invocation. The runner always applies
+ * on drift (no interactive confirm, no dryRun) so the only possible
+ * outcomes are 'skipped' (check returned null) and 'applied' (check
+ * returned drift; apply ran).
+ */
+export type IdempotentResult<TDrift, TInSync = void, TApplied = void> = {
+    outcome: 'skipped';
+    drift: null;
+    result: TInSync;
+} | {
+    outcome: 'applied';
+    drift: TDrift;
+    result: TApplied;
+};
+/**
+ * Generic idempotent helper for use inside any step, hook, or bare
+ * async function. Resolves to a discriminated result indicating whether
+ * the system was already in sync or apply() ran.
+ */
+export declare function idempotent<TDrift, TInSync = void, TApplied = void>(opts: IdempotentOptions<TDrift, TInSync, TApplied>): Promise<IdempotentResult<TDrift, TInSync, TApplied>>;
+/**
+ * Factory returning an SDK Step whose run function executes
+ * `idempotent(...)`. Status lines are routed through `ctx.log.info`.
+ * The step's typed return value is the IdempotentResult union.
+ */
+export declare function idempotentStep<TDrift, TInSync = void, TApplied = void>(name: string, opts: Omit<IdempotentOptions<TDrift, TInSync, TApplied>, 'name' | 'log'>): Step<IdempotentResult<TDrift, TInSync, TApplied>>;
+//# sourceMappingURL=idempotent.d.ts.map

package/dist/idempotent.js

@@ -0,0 +1,77 @@
+import "./chunk-gOLHoazu.js";
+import { step } from "./step.js";
+import { runIdempotentStep } from "@kici-dev/shared/idempotency";
+//#region src/idempotent.ts
+/**
+* SDK idempotency helpers for workflow authors.
+*
+* Workflows run unattended on agents — no operator at the prompt, no
+* dry-run flag to flip. The helpers in this file expose the same
+* check/apply discipline as the shared primitive but with a workflow
+* shape:
+*
+* - apply on drift unconditionally (no confirm, no dryRun).
+* - optional whenInSync() callback to surface the already-satisfied
+*   resource when check() reports no drift (e.g. fetch an existing
+*   resource id when a create-if-missing was already done).
+* - typed return values threaded through both branches via the
+*   discriminated IdempotentResult union.
+*
+* Two entry points:
+*
+* - `idempotent(options)` — generic helper callable from any step,
+*   hook, or bare async function. Returns the discriminated result.
+* - `idempotentStep(name, options)` — factory returning an SDK `Step`
+*   whose run function executes `idempotent(...)` and propagates ctx.log
+*   into the runner's status sink.
+*/
+const DEFAULT_NAME = "idempotent";
+/**
+* Generic idempotent helper for use inside any step, hook, or bare
+* async function. Resolves to a discriminated result indicating whether
+* the system was already in sync or apply() ran.
+*/
+async function idempotent(opts) {
+	const name = opts.name ?? DEFAULT_NAME;
+	const summarize = opts.summarize ?? ((drift) => JSON.stringify(drift, null, 2));
+	const sharedResult = await runIdempotentStep({
+		name,
+		check: opts.check,
+		apply: opts.apply,
+		summarize,
+		whenInSync: opts.whenInSync
+	}, {
+		yes: true,
+		log: opts.log
+	});
+	if (sharedResult.outcome === "skipped") return {
+		outcome: "skipped",
+		drift: null,
+		result: sharedResult.result
+	};
+	if (sharedResult.outcome === "applied") return {
+		outcome: "applied",
+		drift: sharedResult.drift,
+		result: sharedResult.result
+	};
+	throw new Error(`idempotent(${name}): unreachable outcome '${sharedResult.outcome}'`);
+}
+/**
+* Factory returning an SDK Step whose run function executes
+* `idempotent(...)`. Status lines are routed through `ctx.log.info`.
+* The step's typed return value is the IdempotentResult union.
+*/
+function idempotentStep(name, opts) {
+	return step(name, { run: async (ctx) => idempotent({
+		name,
+		check: opts.check,
+		apply: opts.apply,
+		whenInSync: opts.whenInSync,
+		summarize: opts.summarize,
+		log: (line) => ctx.log.info(line)
+	}) });
+}
+//#endregion
+export { idempotent, idempotentStep };
+
+//# sourceMappingURL=idempotent.js.map

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+export { step } from './step.js';
+export { job } from './job.js';
+export { workflow } from './workflow.js';
+export { pr, push, tag, comment, review, reviewComment, release, dispatch, create, delete as delete, status, workflowRun, fork, star, watch, webhook, kiciEvent, workflowComplete, jobComplete, genericWebhook, schedule, lifecycle, } from './triggers/index.js';
+export type { TriggerConfig, PrTriggerConfig, PushTriggerConfig, TagTriggerConfig, CommentTriggerConfig, ReviewTriggerConfig, ReviewCommentTriggerConfig, ReleaseTriggerConfig, DispatchTriggerConfig, CreateTriggerConfig, DeleteTriggerConfig, StatusTriggerConfig, WorkflowRunTriggerConfig, ForkTriggerConfig, StarTriggerConfig, WatchTriggerConfig, WebhookTriggerConfig, BranchPattern, BodyMatchPattern, PrEvent, PushEvent, PrConfigInput, PushConfigInput, TagConfigInput, CommentConfigInput, CommentAction, CommentSource, ReviewConfigInput, ReviewAction, ReviewState, ReviewCommentConfigInput, ReviewCommentAction, ReleaseConfigInput, ReleaseAction, DispatchConfigInput, CreateConfigInput, DeleteConfigInput, RefType, StatusConfigInput, StatusState, WorkflowRunConfigInput, WorkflowRunAction, ForkConfigInput, StarConfigInput, StarAction, WatchConfigInput, WatchAction, WebhookConfigInput, KiciEventConfigInput, KiciEventTriggerConfig, WorkflowCompleteConfigInput, WorkflowCompleteTriggerConfig, WorkflowCompleteStatus, JobCompleteConfigInput, JobCompleteTriggerConfig, JobCompleteStatus, GenericWebhookConfigInput, GenericWebhookTriggerConfig, GenericWebhookAuthMethod, GenericWebhookHmacAuth, GenericWebhookApiKeyAuth, GenericWebhookAuth, ScheduleConfigInput, ScheduleTriggerConfig, LifecycleEvent, LifecycleConfigInput, LifecycleTriggerConfig, } from './triggers/index.js';
+export { onCancel, cleanup, onSuccess, onFailure, beforeStep, afterStep } from './hooks/index.js';
+export type { HookConfig, HookFn, HookInput, HookContext, OutcomeMetadata } from './hooks/index.js';
+export { rule, skip } from './rules/index.js';
+export { evaluateRules } from './rules/index.js';
+export { isEventType } from './rules/index.js';
+export type { Rule, RuleContext, RuleCheckFn, RuleResult, EventPayload, RuleEvaluationResult, EventBase, PullRequestEventPayload, PushEventPayload, TagEventPayload, CommentEventPayload, ReviewEventPayload, ReviewCommentEventPayload, ReleaseEventPayload, DispatchEventPayload, CreateEventPayload, DeleteEventPayload, StatusEventPayload, WorkflowRunEventPayload, ForkEventPayload, StarEventPayload, WatchEventPayload, WebhookEventPayload, KiciEventPayload, WorkflowCompleteEventPayload, JobCompleteEventPayload, GenericWebhookEventPayload, ScheduleEventPayload, LifecycleEventPayload, GitHubRepository, GitHubUser, GitHubPullRequest, GitHubCommit, GitHubComment, GitHubReview, GitHubRelease, } from './rules/index.js';
+export { validateDag } from './validation/index.js';
+export type { DagNode, DagValidationResult } from './validation/index.js';
+export type { SourceLocation, OutputProxy, Step, StepOptions, StepRunFn, BareStepFn, StepInput, OutputSchema, InferOutputs, Job, JobOptions, ContainerConfig, RunsOnSelector, RunsOn, Workflow, WorkflowOptions, Registry, Trigger, DynamicJobFn, DynamicJobContext, JobOrFactory, } from './types.js';
+export { isDynamicJobFn, dynamicJob, getDynamicJobGroup, DYNAMIC_JOB_GROUP_TAG } from './types.js';
+export type { TaggedDynamicJobFn } from './types.js';
+export { dynamicGroup, isDynamicGroupRef, DYNAMIC_GROUP_TAG } from './dynamic-group.js';
+export type { DynamicGroupRef } from './dynamic-group.js';
+export type { StepContext, Logger, WorkflowInfo, JobInfo, RepoInfo, StepSecretsTyped, KnownSecretKeys, } from './context.js';
+export { buildKiciApi } from './api-types.js';
+export type { KiciApi, KiciApiTransport, InfrastructureApi, InfrastructureListResult, } from './api-types.js';
+export { SecretNotFoundError } from './errors.js';
+export { createStepSecrets } from './secrets.js';
+export type { StepSecrets, TrackedStepSecrets, SecretMeta, SecretFileOptions, MountedFile, StepSecretsFileHost, StepSecretsFileWiring, StepSecretsHandle, StepSecretMountKind, StepSecretMountRecord, } from './secrets.js';
+export { createStepOutputProxy, createJobOutputProxy, resolveStepOutputs, resolveJobOutputs, setStepOutputsMap, setJobOutputsMap, setStepRefMap, getStepOutputsMap, getJobOutputsMap, getStepRefMap, } from './outputs.js';
+export type { OutputsMap, StepRefMap } from './outputs.js';
+export type { StaticMatrixArray, StaticMatrixObject, DynamicMatrixFn, DynamicMatrixContext, Matrix, MatrixInclude, MatrixExclude, MatrixValues, } from './matrix/index.js';
+export { isStaticArray, isStaticObject, isDynamicFunction } from './matrix/index.js';
+export { expandMatrix, applyIncludeExclude } from './matrix/index.js';
+export { defineEvent } from './events/index.js';
+export type { EventDefinition } from './events/index.js';
+export type { EventEmitOptions } from './events/index.js';
+export { fixture } from './fixture.js';
+export type { Fixture, FixtureOptions } from './fixture.js';
+export { idempotent, idempotentStep } from './idempotent.js';
+export type { IdempotentOptions, IdempotentResult } from './idempotent.js';
+export { waitFor, waitForStep, WaitForTimeoutError } from './wait-for.js';
+export type { WaitForOptions, WaitForResult } from './wait-for.js';
+export { z } from 'zod';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,50 @@
+import "./chunk-gOLHoazu.js";
+import { buildKiciApi } from "./api-types.js";
+import { DYNAMIC_GROUP_TAG, dynamicGroup, isDynamicGroupRef } from "./dynamic-group.js";
+import { SecretNotFoundError } from "./errors.js";
+import { fixture } from "./fixture.js";
+import { createJobOutputProxy, createStepOutputProxy, getJobOutputsMap, getStepOutputsMap, getStepRefMap, resolveJobOutputs, resolveStepOutputs, setJobOutputsMap, setStepOutputsMap, setStepRefMap } from "./outputs.js";
+import { step } from "./step.js";
+import { idempotent, idempotentStep } from "./idempotent.js";
+import { job } from "./job.js";
+import { workflow } from "./workflow.js";
+import { pr } from "./triggers/pr.js";
+import { push } from "./triggers/push.js";
+import { tag } from "./triggers/tag.js";
+import { comment } from "./triggers/comment.js";
+import { review } from "./triggers/review.js";
+import { reviewComment } from "./triggers/review-comment.js";
+import { release } from "./triggers/release.js";
+import { dispatch } from "./triggers/dispatch.js";
+import { create } from "./triggers/create.js";
+import { del } from "./triggers/delete.js";
+import { status } from "./triggers/status.js";
+import { workflowRun } from "./triggers/workflow-run.js";
+import { fork } from "./triggers/fork.js";
+import { star } from "./triggers/star.js";
+import { watch } from "./triggers/watch.js";
+import { webhook } from "./triggers/webhook.js";
+import { kiciEvent } from "./triggers/kici-event.js";
+import { workflowComplete } from "./triggers/workflow-complete.js";
+import { jobComplete } from "./triggers/job-complete.js";
+import { genericWebhook } from "./triggers/generic-webhook.js";
+import { schedule } from "./triggers/schedule.js";
+import { lifecycle } from "./triggers/lifecycle.js";
+import "./triggers/index.js";
+import { afterStep, beforeStep, cleanup, onCancel, onFailure, onSuccess } from "./hooks/index.js";
+import { rule, skip } from "./rules/rule.js";
+import { evaluateRules } from "./rules/evaluator.js";
+import { isEventType } from "./events/event-payloads.js";
+import "./rules/index.js";
+import { validateDag } from "./validation/dag.js";
+import "./validation/index.js";
+import { DYNAMIC_JOB_GROUP_TAG, dynamicJob, getDynamicJobGroup, isDynamicJobFn } from "./types.js";
+import { createStepSecrets } from "./secrets.js";
+import { isDynamicFunction, isStaticArray, isStaticObject } from "./matrix/types.js";
+import { applyIncludeExclude, expandMatrix } from "./matrix/expand.js";
+import "./matrix/index.js";
+import { defineEvent } from "./events/define-event.js";
+import "./events/index.js";
+import { WaitForTimeoutError, waitFor, waitForStep } from "./wait-for.js";
+import { z } from "zod";
+export { DYNAMIC_GROUP_TAG, DYNAMIC_JOB_GROUP_TAG, SecretNotFoundError, WaitForTimeoutError, afterStep, applyIncludeExclude, beforeStep, buildKiciApi, cleanup, comment, create, createJobOutputProxy, createStepOutputProxy, createStepSecrets, defineEvent, del as delete, dispatch, dynamicGroup, dynamicJob, evaluateRules, expandMatrix, fixture, fork, genericWebhook, getDynamicJobGroup, getJobOutputsMap, getStepOutputsMap, getStepRefMap, idempotent, idempotentStep, isDynamicFunction, isDynamicGroupRef, isDynamicJobFn, isEventType, isStaticArray, isStaticObject, job, jobComplete, kiciEvent, lifecycle, onCancel, onFailure, onSuccess, pr, push, release, resolveJobOutputs, resolveStepOutputs, review, reviewComment, rule, schedule, setJobOutputsMap, setStepOutputsMap, setStepRefMap, skip, star, status, step, tag, validateDag, waitFor, waitForStep, watch, webhook, workflow, workflowComplete, workflowRun, z };

package/dist/job.d.ts

@@ -0,0 +1,31 @@
+import type { Job, JobOptions } from './types.js';
+/**
+ * Create a job with an explicit name.
+ *
+ * @example
+ * const build = job('build', {
+ *   runsOn: 'linux',
+ *   steps: [checkout, install, compile],
+ * });
+ *
+ * @example
+ * // With rules and description
+ * const build = job('build', {
+ *   runsOn: 'linux',
+ *   steps: [checkout, install, compile],
+ *   rules: [rule('env: CI')],
+ *   description: 'Build the project',
+ * });
+ */
+export declare function job(name: string, options: JobOptions): Job;
+/**
+ * Create a job with auto-generated ID.
+ *
+ * @example
+ * const build = job({
+ *   runsOn: 'linux',
+ *   steps: [checkout, install],
+ * });
+ */
+export declare function job(options: JobOptions): Job;
+//# sourceMappingURL=job.d.ts.map

package/dist/job.js

@@ -0,0 +1,46 @@
+import "./chunk-gOLHoazu.js";
+import { createJobOutputProxy } from "./outputs.js";
+import { randomUUID } from "node:crypto";
+//#region src/job.ts
+/**
+* Implementation of job() factory.
+*/
+function job(nameOrOptions, maybeOptions) {
+	const name = typeof nameOrOptions === "string" ? nameOrOptions : randomUUID();
+	const options = typeof nameOrOptions === "string" ? maybeOptions : nameOrOptions;
+	let steps = options.steps ?? [];
+	if (options.run) {
+		if (options.steps && options.steps.length > 0) throw new Error("job() cannot have both \"run\" and \"steps\" -- use one or the other");
+		steps = [options.run];
+	}
+	return {
+		_tag: "Job",
+		name,
+		runsOn: options.runsOn,
+		steps,
+		needs: options.needs,
+		rules: options.rules,
+		description: options.description,
+		matrix: options.matrix,
+		include: options.include,
+		exclude: options.exclude,
+		checkout: options.checkout,
+		container: options.container,
+		environment: options.environment,
+		env: options.env,
+		concurrencyGroup: options.concurrencyGroup,
+		onCancel: options.onCancel,
+		cleanup: options.cleanup,
+		onSuccess: options.onSuccess,
+		onFailure: options.onFailure,
+		beforeStep: options.beforeStep,
+		afterStep: options.afterStep,
+		gracePeriod: options.gracePeriod,
+		resources: options.resources,
+		result: createJobOutputProxy(name)
+	};
+}
+//#endregion
+export { job };
+
+//# sourceMappingURL=job.js.map

package/dist/matrix/expand.d.ts

@@ -0,0 +1,32 @@
+import type { StaticMatrixArray, StaticMatrixObject, MatrixInclude, MatrixExclude, MatrixValues } from './types.js';
+/**
+ * Expand single-dimension matrix (array form) to MatrixValues array.
+ * Each value becomes {value: string}.
+ */
+export declare function expandSingleDimension(matrix: StaticMatrixArray): MatrixValues[];
+/**
+ * Expand multi-dimensional matrix (object form) to MatrixValues array.
+ * Uses fast-cartesian to compute cartesian product of all dimensions.
+ * Dimension names are sorted for deterministic output.
+ */
+export declare function expandMultiDimension(matrix: StaticMatrixObject): MatrixValues[];
+/**
+ * Unified expand function that dispatches to single or multi-dimensional expansion.
+ */
+export declare function expandMatrix(matrix: StaticMatrixArray | StaticMatrixObject): MatrixValues[];
+/**
+ * Apply include/exclude modifications to expanded matrix combinations.
+ * Per CONTEXT.md: exclude first (remove matching), then include (add new).
+ *
+ * Exclude matches if ALL specified dimensions match.
+ * Include adds new combinations if they don't already exist.
+ */
+export declare function applyIncludeExclude(expanded: MatrixValues[], include?: MatrixInclude[], exclude?: MatrixExclude[]): MatrixValues[];
+/**
+ * Generate job name from base job name and matrix values.
+ * Per CONTEXT.md bracket notation:
+ * - Single dimension: job[value]
+ * - Multi-dimensional: job[dim:val,dim:val] (sorted keys for determinism)
+ */
+export declare function generateJobName(baseJobName: string, matrixValues: MatrixValues): string;
+//# sourceMappingURL=expand.d.ts.map

package/dist/matrix/expand.js

@@ -0,0 +1,77 @@
+import "../chunk-gOLHoazu.js";
+import fastCartesian from "fast-cartesian";
+//#region src/matrix/expand.ts
+/**
+* Expand single-dimension matrix (array form) to MatrixValues array.
+* Each value becomes {value: string}.
+*/
+function expandSingleDimension(matrix) {
+	return matrix.map((value) => ({ value }));
+}
+/**
+* Expand multi-dimensional matrix (object form) to MatrixValues array.
+* Uses fast-cartesian to compute cartesian product of all dimensions.
+* Dimension names are sorted for deterministic output.
+*/
+function expandMultiDimension(matrix) {
+	const dimensions = Object.entries(matrix);
+	if (dimensions.length === 0) return [];
+	dimensions.sort((a, b) => a[0].localeCompare(b[0]));
+	const names = dimensions.map(([name]) => name);
+	return fastCartesian(dimensions.map(([, values]) => values)).map((combo) => {
+		const result = {};
+		names.forEach((name, idx) => {
+			result[name] = combo[idx];
+		});
+		return result;
+	});
+}
+/**
+* Unified expand function that dispatches to single or multi-dimensional expansion.
+*/
+function expandMatrix(matrix) {
+	if (Array.isArray(matrix)) return expandSingleDimension(matrix);
+	return expandMultiDimension(matrix);
+}
+/**
+* Apply include/exclude modifications to expanded matrix combinations.
+* Per CONTEXT.md: exclude first (remove matching), then include (add new).
+*
+* Exclude matches if ALL specified dimensions match.
+* Include adds new combinations if they don't already exist.
+*/
+function applyIncludeExclude(expanded, include, exclude) {
+	let result = [...expanded];
+	if (exclude && exclude.length > 0) result = result.filter((combo) => {
+		return !exclude.some((excl) => {
+			const exclEntries = Object.entries(excl);
+			if (exclEntries.length === 0) return false;
+			return exclEntries.every(([key, value]) => combo[key] === value);
+		});
+	});
+	if (include && include.length > 0) for (const incl of include) {
+		const inclKeys = Object.keys(incl);
+		if (inclKeys.length === 0) continue;
+		if (!result.some((combo) => {
+			const comboKeys = Object.keys(combo);
+			if (inclKeys.length !== comboKeys.length) return false;
+			return inclKeys.every((key) => combo[key] === incl[key]);
+		})) result.push(incl);
+	}
+	return result;
+}
+/**
+* Generate job name from base job name and matrix values.
+* Per CONTEXT.md bracket notation:
+* - Single dimension: job[value]
+* - Multi-dimensional: job[dim:val,dim:val] (sorted keys for determinism)
+*/
+function generateJobName(baseJobName, matrixValues) {
+	const keys = Object.keys(matrixValues).filter((k) => matrixValues[k] !== void 0);
+	if (keys.length === 1 && keys[0] === "value") return `${baseJobName}[${matrixValues.value}]`;
+	return `${baseJobName}[${keys.sort().map((key) => `${key}:${matrixValues[key]}`).join(",")}]`;
+}
+//#endregion
+export { applyIncludeExclude, expandMatrix, expandMultiDimension, expandSingleDimension, generateJobName };
+
+//# sourceMappingURL=expand.js.map

package/dist/matrix/index.d.ts

@@ -0,0 +1,4 @@
+export type { StaticMatrixArray, StaticMatrixObject, DynamicMatrixFn, DynamicMatrixContext, Matrix, MatrixInclude, MatrixExclude, MatrixValues, } from './types.js';
+export { isStaticArray, isStaticObject, isDynamicFunction } from './types.js';
+export { expandMatrix, applyIncludeExclude } from './expand.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/matrix/index.js

@@ -0,0 +1,4 @@
+import "../chunk-gOLHoazu.js";
+import { isDynamicFunction, isStaticArray, isStaticObject } from "./types.js";
+import { applyIncludeExclude, expandMatrix } from "./expand.js";
+export { applyIncludeExclude, expandMatrix, isDynamicFunction, isStaticArray, isStaticObject };

package/dist/matrix/types.d.ts

@@ -0,0 +1,60 @@
+import type { $ as Shell } from 'zx';
+import type { Logger } from '../context.js';
+/** Single-dimension static matrix: array of values */
+export type StaticMatrixArray = string[];
+/** Multi-dimensional static matrix: named dimensions with values */
+export type StaticMatrixObject = Record<string, string[]>;
+/**
+ * Context passed to dynamic matrix functions.
+ * Uses destructured form: async ({$, ctx, log, env}) => values
+ */
+export interface DynamicMatrixContext {
+    /** zx shell executor for running commands */
+    $: typeof Shell;
+    /** Event context and workflow metadata */
+    ctx: {
+        workflow: {
+            name: string;
+        };
+        job: {
+            name: string;
+            runsOn: string | string[] | {
+                labels: string | string[];
+                exclude?: string | string[];
+            };
+        };
+    };
+    /** Structured logger */
+    log: Logger;
+    /** Environment variables */
+    env: Record<string, string | undefined>;
+}
+/**
+ * Async function that computes matrix values dynamically.
+ * Signature: async ({$, ctx, log, env}) => values
+ */
+export type DynamicMatrixFn = (context: DynamicMatrixContext) => Promise<StaticMatrixArray | StaticMatrixObject>;
+/** Union type for all matrix forms */
+export type Matrix = StaticMatrixArray | StaticMatrixObject | DynamicMatrixFn;
+/** Include entries for adding specific matrix combinations */
+export type MatrixInclude = Record<string, string>;
+/** Exclude entries for removing specific matrix combinations */
+export type MatrixExclude = Record<string, string>;
+/**
+ * Matrix values as exposed to steps.
+ * Single-dimension: {value: 'linux'}
+ * Multi-dimensional: {os: 'linux', node: '18'}
+ */
+export interface MatrixValues {
+    /** Single-dimension: the value */
+    value?: string;
+    /** Multi-dimensional: named properties */
+    [dimension: string]: string | undefined;
+}
+/** Type guard for static array matrices */
+export declare function isStaticArray(m: Matrix): m is StaticMatrixArray;
+/** Type guard for static object matrices */
+export declare function isStaticObject(m: Matrix): m is StaticMatrixObject;
+/** Type guard for dynamic function matrices */
+export declare function isDynamicFunction(m: Matrix): m is DynamicMatrixFn;
+//# sourceMappingURL=types.d.ts.map

package/dist/matrix/types.js

@@ -0,0 +1,18 @@
+import "../chunk-gOLHoazu.js";
+//#region src/matrix/types.ts
+/** Type guard for static array matrices */
+function isStaticArray(m) {
+	return Array.isArray(m);
+}
+/** Type guard for static object matrices */
+function isStaticObject(m) {
+	return m !== null && typeof m === "object" && !Array.isArray(m);
+}
+/** Type guard for dynamic function matrices */
+function isDynamicFunction(m) {
+	return typeof m === "function";
+}
+//#endregion
+export { isDynamicFunction, isStaticArray, isStaticObject };
+
+//# sourceMappingURL=types.js.map

package/dist/outputs.d.ts

@@ -0,0 +1,86 @@
+import type { OutputProxy } from './types.js';
+/**
+ * Shared mutable map that steps write their outputs to and proxies read from.
+ * Keys are step/job names, values are the outputs records.
+ */
+export type OutputsMap = Map<string, Record<string, unknown>>;
+/**
+ * WeakMap for mapping bare function references to step names.
+ * Populated when the job normalizes bare functions into internal Step objects.
+ */
+export type StepRefMap = WeakMap<Function, string>;
+/**
+ * Structural type for step references used in resolveStepOutputs.
+ * Avoids circular dependency with types.ts.
+ */
+interface StepLike {
+    readonly _tag: 'Step';
+    readonly name: string;
+}
+/**
+ * Inject a fresh step outputs map for a new execution.
+ * Called by workflow runners (compiler test runner, agent sandbox) before execution.
+ */
+export declare function setStepOutputsMap(map: OutputsMap): void;
+/**
+ * Inject a fresh job outputs map for a new execution.
+ */
+export declare function setJobOutputsMap(map: OutputsMap): void;
+/**
+ * Inject a fresh step-ref map for bare function -> step name resolution.
+ */
+export declare function setStepRefMap(map: StepRefMap): void;
+/**
+ * Get the current step outputs map (for runners to populate).
+ */
+export declare function getStepOutputsMap(): OutputsMap;
+/**
+ * Get the current job outputs map (for runners to populate).
+ */
+export declare function getJobOutputsMap(): OutputsMap;
+/**
+ * Get the current step ref map.
+ */
+export declare function getStepRefMap(): StepRefMap;
+/**
+ * Create a Proxy over step outputs that resolves property access lazily
+ * against the module-global step outputs map.
+ *
+ * @param stepName - The name of the step whose outputs to proxy
+ * @returns A Proxy that resolves property access at runtime
+ */
+export declare function createStepOutputProxy<T>(stepName: string): OutputProxy<T>;
+/**
+ * Create a Proxy over job outputs that resolves property access lazily
+ * against the module-global job outputs map.
+ *
+ * For multi-step jobs: job.result.stepName.field
+ * For single-step (run shorthand) jobs: job.result.field
+ *
+ * @param jobName - The name of the job whose outputs to proxy
+ * @returns A Proxy that resolves property access at runtime
+ */
+export declare function createJobOutputProxy(jobName: string): OutputProxy<any>;
+/**
+ * Resolve step outputs by step reference (Step object or bare function).
+ * Used by ctx.outputsOf() implementation.
+ *
+ * @param ref - Step object (with _tag: 'Step') or bare function reference
+ * @param outputsMap - The outputs map to resolve against (defaults to module-global)
+ * @param refMap - The ref map for bare function -> name resolution (defaults to module-global)
+ * @returns The step's outputs
+ */
+export declare function resolveStepOutputs<T>(ref: StepLike | Function, outputsMap?: OutputsMap, refMap?: StepRefMap): T;
+/**
+ * Resolve job outputs by job reference.
+ * Used by ctx.jobOutputs() implementation.
+ *
+ * @param ref - Job object reference (needs .name property)
+ * @param outputsMap - The outputs map to resolve against (defaults to module-global)
+ * @returns The job's outputs
+ */
+export declare function resolveJobOutputs(ref: {
+    name: string;
+}, outputsMap?: OutputsMap): Record<string, unknown>;
+export {};
+//# sourceMappingURL=outputs.d.ts.map