@kici-dev/sdk 0.0.0 → 0.1.1

package/dist/outputs.js

@@ -0,0 +1,180 @@
+import "./chunk-gOLHoazu.js";
+//#region src/outputs.ts
+/**
+* Well-known string property names that should delegate to Reflect rather than throwing.
+* These are accessed by built-in operations like JSON.stringify, console.log, iteration, etc.
+*/
+const WELL_KNOWN_STRING_PROPS = new Set([
+	"constructor",
+	"toString",
+	"valueOf",
+	"toJSON",
+	"then",
+	"length",
+	"nodeType",
+	"tagName",
+	"inspect",
+	"$$typeof",
+	"asymmetricMatch",
+	"_tag"
+]);
+/**
+* Module-global outputs maps. Runners inject fresh maps at execution time
+* via setStepOutputsMap() / setJobOutputsMap().
+*/
+let _stepOutputsMap = /* @__PURE__ */ new Map();
+let _jobOutputsMap = /* @__PURE__ */ new Map();
+let _stepRefMap = /* @__PURE__ */ new WeakMap();
+/**
+* Inject a fresh step outputs map for a new execution.
+* Called by workflow runners (compiler test runner, agent sandbox) before execution.
+*/
+function setStepOutputsMap(map) {
+	_stepOutputsMap = map;
+}
+/**
+* Inject a fresh job outputs map for a new execution.
+*/
+function setJobOutputsMap(map) {
+	_jobOutputsMap = map;
+}
+/**
+* Inject a fresh step-ref map for bare function -> step name resolution.
+*/
+function setStepRefMap(map) {
+	_stepRefMap = map;
+}
+/**
+* Get the current step outputs map (for runners to populate).
+*/
+function getStepOutputsMap() {
+	return _stepOutputsMap;
+}
+/**
+* Get the current job outputs map (for runners to populate).
+*/
+function getJobOutputsMap() {
+	return _jobOutputsMap;
+}
+/**
+* Get the current step ref map.
+*/
+function getStepRefMap() {
+	return _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
+*/
+function createStepOutputProxy(stepName) {
+	return new Proxy({}, {
+		get(_target, prop, receiver) {
+			if (typeof prop === "symbol") return Reflect.get(_target, prop, receiver);
+			if (WELL_KNOWN_STRING_PROPS.has(prop)) return Reflect.get(_target, prop, receiver);
+			const outputs = _stepOutputsMap.get(stepName);
+			if (!outputs) throw new Error(`Step '${stepName}' has not produced outputs yet`);
+			return outputs[prop];
+		},
+		ownKeys() {
+			const outputs = _stepOutputsMap.get(stepName);
+			if (!outputs) return [];
+			return Reflect.ownKeys(outputs);
+		},
+		has(_target, prop) {
+			const outputs = _stepOutputsMap.get(stepName);
+			if (!outputs) return false;
+			return prop in outputs;
+		},
+		getOwnPropertyDescriptor(_target, prop) {
+			const outputs = _stepOutputsMap.get(stepName);
+			if (!outputs) return void 0;
+			if (prop in outputs) return {
+				configurable: true,
+				enumerable: true,
+				value: outputs[prop]
+			};
+		}
+	});
+}
+/**
+* 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
+*/
+function createJobOutputProxy(jobName) {
+	return new Proxy({}, {
+		get(_target, prop, receiver) {
+			if (typeof prop === "symbol") return Reflect.get(_target, prop, receiver);
+			if (WELL_KNOWN_STRING_PROPS.has(prop)) return Reflect.get(_target, prop, receiver);
+			const outputs = _jobOutputsMap.get(jobName);
+			if (!outputs) throw new Error(`Job '${jobName}' has not produced outputs yet`);
+			return outputs[prop];
+		},
+		ownKeys() {
+			const outputs = _jobOutputsMap.get(jobName);
+			if (!outputs) return [];
+			return Reflect.ownKeys(outputs);
+		},
+		has(_target, prop) {
+			const outputs = _jobOutputsMap.get(jobName);
+			if (!outputs) return false;
+			return prop in outputs;
+		},
+		getOwnPropertyDescriptor(_target, prop) {
+			const outputs = _jobOutputsMap.get(jobName);
+			if (!outputs) return void 0;
+			if (prop in outputs) return {
+				configurable: true,
+				enumerable: true,
+				value: outputs[prop]
+			};
+		}
+	});
+}
+/**
+* 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
+*/
+function resolveStepOutputs(ref, outputsMap, refMap) {
+	const map = outputsMap ?? _stepOutputsMap;
+	const rMap = refMap ?? _stepRefMap;
+	let stepName;
+	if (typeof ref === "function") {
+		stepName = rMap.get(ref);
+		if (!stepName) throw new Error("Cannot resolve outputs for bare function: function not registered in step ref map");
+	} else if (ref && typeof ref === "object" && "_tag" in ref && ref._tag === "Step") stepName = ref.name;
+	else throw new Error("Invalid step reference: expected Step object or bare function");
+	const outputs = map.get(stepName);
+	if (!outputs) throw new Error(`Step '${stepName}' has not produced outputs yet`);
+	return outputs;
+}
+/**
+* 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
+*/
+function resolveJobOutputs(ref, outputsMap) {
+	const outputs = (outputsMap ?? _jobOutputsMap).get(ref.name);
+	if (!outputs) throw new Error(`Job '${ref.name}' has not produced outputs yet`);
+	return outputs;
+}
+//#endregion
+export { createJobOutputProxy, createStepOutputProxy, getJobOutputsMap, getStepOutputsMap, getStepRefMap, resolveJobOutputs, resolveStepOutputs, setJobOutputsMap, setStepOutputsMap, setStepRefMap };
+
+//# sourceMappingURL=outputs.js.map

package/dist/rules/evaluator.d.ts

@@ -0,0 +1,24 @@
+import type { Rule, RuleContext, RuleResult } from './types.js';
+/**
+ * Result of evaluating rules for a job or workflow.
+ * Contains overall pass/fail status and per-rule results.
+ */
+export interface RuleEvaluationResult {
+    allPassed: boolean;
+    results: RuleResult[];
+}
+/**
+ * Evaluate rules sequentially with fail-fast behavior.
+ *
+ * Iterates rules in order, calling each rule's check function with the provided
+ * context. Records timing and result for each evaluated rule. Stops evaluation
+ * on the first failure (remaining rules are not evaluated).
+ *
+ * @param rules - Array of Rule objects to evaluate
+ * @param context - RuleContext providing event, env, changedFiles, and $
+ * @param _label - Human-readable label for logging (e.g., job name) -- reserved for callers
+ * @param onRuleResult - Optional callback invoked after each rule evaluation
+ * @returns RuleEvaluationResult with allPassed flag and per-rule results
+ */
+export declare function evaluateRules(rules: Rule[], context: RuleContext, _label: string, onRuleResult?: (result: RuleResult) => void): Promise<RuleEvaluationResult>;
+//# sourceMappingURL=evaluator.d.ts.map

package/dist/rules/evaluator.js

@@ -0,0 +1,52 @@
+import "../chunk-gOLHoazu.js";
+import { toErrorMessage } from "@kici-dev/shared";
+//#region src/rules/evaluator.ts
+/**
+* Evaluate rules sequentially with fail-fast behavior.
+*
+* Iterates rules in order, calling each rule's check function with the provided
+* context. Records timing and result for each evaluated rule. Stops evaluation
+* on the first failure (remaining rules are not evaluated).
+*
+* @param rules - Array of Rule objects to evaluate
+* @param context - RuleContext providing event, env, changedFiles, and $
+* @param _label - Human-readable label for logging (e.g., job name) -- reserved for callers
+* @param onRuleResult - Optional callback invoked after each rule evaluation
+* @returns RuleEvaluationResult with allPassed flag and per-rule results
+*/
+async function evaluateRules(rules, context, _label, onRuleResult) {
+	const results = [];
+	let allPassed = true;
+	for (const rule of rules) {
+		const startTime = Date.now();
+		let passed = false;
+		let error;
+		try {
+			passed = await rule.check(context);
+		} catch (e) {
+			passed = false;
+			error = toErrorMessage(e);
+		}
+		const durationMs = Date.now() - startTime;
+		const result = {
+			label: rule.label,
+			passed,
+			durationMs,
+			error
+		};
+		results.push(result);
+		onRuleResult?.(result);
+		if (!passed) {
+			allPassed = false;
+			break;
+		}
+	}
+	return {
+		allPassed,
+		results
+	};
+}
+//#endregion
+export { evaluateRules };
+
+//# sourceMappingURL=evaluator.js.map

package/dist/rules/index.d.ts

@@ -0,0 +1,6 @@
+export { rule, skip } from './rule.js';
+export { evaluateRules, type RuleEvaluationResult } from './evaluator.js';
+export type { Rule, RuleCheckFn, RuleContext, RuleResult, EventPayload } from './types.js';
+export { isEventType } from '../events/event-payloads.js';
+export type { 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 '../events/event-payloads.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/rules/index.js

@@ -0,0 +1,5 @@
+import "../chunk-gOLHoazu.js";
+import { rule, skip } from "./rule.js";
+import { evaluateRules } from "./evaluator.js";
+import { isEventType } from "../events/event-payloads.js";
+export { evaluateRules, isEventType, rule, skip };

package/dist/rules/rule.d.ts

@@ -0,0 +1,34 @@
+import type { Rule, RuleCheckFn } from './types.js';
+/**
+ * Create a rule with just a label (always passes).
+ * Useful for markers that appear in the decision trace.
+ *
+ * @example
+ * const marker = rule('ci: required check');
+ */
+export declare function rule(label: string): Rule;
+/**
+ * Create a rule with a label and check function.
+ * The check function determines whether the rule passes.
+ *
+ * @example
+ * const hasFrontend = rule('skip: no frontend changes', async (ctx) => {
+ *   return ctx.changedFiles.some(f => f.startsWith('src/ui/'));
+ * });
+ */
+export declare function rule(label: string, check: RuleCheckFn): Rule;
+/**
+ * Create a rule that skips when the condition is met.
+ * Convenience wrapper around rule() that inverts the check function.
+ *
+ * When the check returns true (condition met), the rule returns false (skip).
+ * When the check returns false (condition not met), the rule returns true (run).
+ *
+ * @example
+ * // Skip when PR only contains docs changes
+ * const skipDocsOnly = skip('docs only PR', async (ctx) => {
+ *   return ctx.changedFiles.every(f => f.endsWith('.md'));
+ * });
+ */
+export declare function skip(label: string, check: RuleCheckFn): Rule;
+//# sourceMappingURL=rule.d.ts.map

package/dist/rules/rule.js

@@ -0,0 +1,37 @@
+import "../chunk-gOLHoazu.js";
+//#region src/rules/rule.ts
+/**
+* Implementation of rule() factory.
+* Creates a Rule with an optional check function (defaults to always-true).
+*/
+function rule(label, check) {
+	return {
+		_tag: "Rule",
+		label,
+		check: check ?? (() => true)
+	};
+}
+/**
+* Create a rule that skips when the condition is met.
+* Convenience wrapper around rule() that inverts the check function.
+*
+* When the check returns true (condition met), the rule returns false (skip).
+* When the check returns false (condition not met), the rule returns true (run).
+*
+* @example
+* // Skip when PR only contains docs changes
+* const skipDocsOnly = skip('docs only PR', async (ctx) => {
+*   return ctx.changedFiles.every(f => f.endsWith('.md'));
+* });
+*/
+function skip(label, check) {
+	return {
+		_tag: "Rule",
+		label,
+		check: async (ctx) => !await check(ctx)
+	};
+}
+//#endregion
+export { rule, skip };
+
+//# sourceMappingURL=rule.js.map

package/dist/rules/types.d.ts

@@ -0,0 +1,42 @@
+import type { $ as Shell } from 'zx';
+import type { EventPayload } from '../events/event-payloads.js';
+export type { EventPayload } from '../events/event-payloads.js';
+/**
+ * Context passed to rule check functions.
+ * Provides access to event data, changed files, environment, and shell execution.
+ */
+export interface RuleContext {
+    /** The triggering event payload */
+    event: EventPayload;
+    /** List of files changed in this event (e.g., PR diff) */
+    changedFiles: string[];
+    /** Environment variables */
+    env: Record<string, string | undefined>;
+    /** zx shell executor for running commands */
+    $: typeof Shell;
+}
+/**
+ * Function type for rule check functions.
+ * Can be sync or async - returns whether the rule passes.
+ */
+export type RuleCheckFn = (ctx: RuleContext) => Promise<boolean> | boolean;
+/**
+ * Rule definition returned by rule() factory.
+ * Rules are labeled conditional checks that appear in the decision trace.
+ */
+export interface Rule {
+    readonly _tag: 'Rule';
+    readonly label: string;
+    readonly check: RuleCheckFn;
+}
+/**
+ * Result of evaluating a rule (for decision trace).
+ * Records whether the rule passed and how long evaluation took.
+ */
+export interface RuleResult {
+    label: string;
+    passed: boolean;
+    durationMs: number;
+    error?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/rules/types.js

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

package/dist/secrets.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Metadata about a resolved secret -- which backend and scope provided it.
+ */
+export interface SecretMeta {
+    /** The resolved secret value. */
+    value: string;
+    /** Backend name that provided the secret (e.g., 'pg', 'openbao-stg'). */
+    backend: string;
+    /** Full prefixed scope path (e.g., 'pg:production/db'). */
+    scope: string;
+}
+/**
+ * Options for materialising one or more existing secret values as a file
+ * on-disk inside the per-step tmpdir.
+ */
+export interface SecretFileOptions {
+    /**
+     * Names of existing secret keys to concatenate (in order) into the file.
+     * Each key must resolve via `ctx.secrets.get(key)`; missing keys cause
+     * `SecretNotFoundError` to be thrown (carrying every missing key).
+     */
+    sources: string[];
+    /**
+     * Optional separator written between concatenated source values.
+     * Default: no divider (values are joined back-to-back).
+     */
+    divider?: string;
+    /**
+     * File mode to chmod the materialised file to. Default `0o600`
+     * (owner read/write only).
+     */
+    mode?: number;
+    /**
+     * Optional filename inside the per-step tmpdir. When omitted, the
+     * runtime auto-generates a unique name (`secret-1`, `secret-2`, ...).
+     */
+    name?: string;
+}
+/**
+ * Result of a `mountFile` / `exposeFile` call.
+ */
+export interface MountedFile {
+    /** Absolute path to the materialised file inside the per-step tmpdir. */
+    path: string;
+}
+/**
+ * Host-side adapter passed by the agent to back the file-mount API.
+ *
+ * The SDK owns the public surface (`mountFile` / `exposeFile`) but defers
+ * disk and `process.env` operations to the agent so the SDK stays free of
+ * any `node:fs` / `node:os` imports. Local-test mode (`kici test`) plugs
+ * in the same adapter shape against `os.tmpdir()`.
+ */
+export interface StepSecretsFileHost {
+    /**
+     * Materialise the concatenated content to a file inside the per-step
+     * tmpdir. The host is responsible for chmod + masker registration
+     * (when applicable) and for remembering the file for cleanup.
+     * Returns the absolute path on success.
+     */
+    writeMountedFile(args: {
+        content: string;
+        sources: string[];
+        mode: number;
+        name?: string;
+    }): Promise<string>;
+    /**
+     * Track an env var that was set as part of `exposeFile`, so the
+     * runtime can `delete process.env[envVar]` during `dispose()`.
+     */
+    trackExposedEnv(envVar: string): void;
+}
+/**
+ * Async accessor interface for step secrets.
+ * Secrets are never automatically injected into environment variables.
+ * Use get() to read a secret value, expose() to explicitly inject into env.
+ */
+export interface StepSecrets {
+    /** Retrieve a secret value by key. Rejects with SecretNotFoundError if not found. */
+    get(key: string): Promise<string>;
+    /** Inject a secret into the step's environment variables. Rejects if key not found. */
+    expose(key: string): Promise<void>;
+    /** Check if a secret key exists. Synchronous, never throws. */
+    has(key: string): boolean;
+    /** Retrieve metadata about a resolved secret (backend name and scope). Returns undefined if key not found. */
+    getMeta(key: string): SecretMeta | undefined;
+    /**
+     * Return every secret key available to this step, sorted alphabetically.
+     * Synchronous, never throws. Returns names only -- call `getMeta(key)` to
+     * inspect backend / scope for a specific key.
+     */
+    list(): string[];
+    /**
+     * Materialise one or more existing secrets as a tmpfile inside a
+     * per-step tmpdir. Returns the absolute file path. The file is removed
+     * automatically when the step completes (success, failure, or timeout).
+     * Rejects with `SecretNotFoundError` if any source key is missing.
+     */
+    mountFile(opts: SecretFileOptions): Promise<MountedFile>;
+    /**
+     * Sugar: call `mountFile(opts)`, then set `process.env[envVar]` to the
+     * resulting path. The env var is unset and the file is removed when
+     * the step completes.
+     */
+    exposeFile(envVar: string, opts: SecretFileOptions): Promise<MountedFile>;
+}
+/**
+ * Extended StepSecrets with access tracking.
+ * Tracks which secret keys were accessed via get() or expose() calls.
+ * Only key names are recorded -- never values.
+ */
+export interface TrackedStepSecrets extends StepSecrets {
+    /** Returns sorted array of secret key names accessed via get() or expose(). */
+    getAccessLog(): string[];
+    /**
+     * Returns sorted array of secret key names referenced via `mountFile()` /
+     * `exposeFile()`. Mounts are tracked separately from plain `get` / `expose`
+     * accesses so the orchestrator can render a distinct audit row.
+     */
+    getMountedKeys(): string[];
+    /**
+     * Returns the audit records of every mount call (in order). Used by the
+     * agent to emit `step.secret_mount` IPC events. Each record carries
+     * `{ sources, target, envVar?, kind }`. `target` is the absolute path the
+     * file was materialised to.
+     */
+    getMountRecords(): readonly StepSecretMountRecord[];
+}
+/**
+ * Kinds of secret-file materialisation operations. Surfaced as the `kind`
+ * discriminator on the IPC event so the orchestrator can distinguish a
+ * plain mount from a mount-with-env-var binding.
+ */
+export type StepSecretMountKind = 'mountFile' | 'exposeFile';
+/**
+ * Audit record for a single secret-file materialisation operation.
+ * Never contains the file content -- only the key names and the
+ * resulting path / env var.
+ */
+export interface StepSecretMountRecord {
+    /** Source secret keys (in concatenation order). */
+    sources: string[];
+    /** Absolute path the file was materialised to. */
+    target: string;
+    /** Env var set when `kind === 'exposeFile'`; otherwise undefined. */
+    envVar?: string;
+    /** Discriminator between `mountFile` and `exposeFile`. */
+    kind: StepSecretMountKind;
+}
+/**
+ * Result of {@link createStepSecrets}: the secrets surface itself plus a
+ * `dispose` callback the agent invokes from the step-loop `finally` to
+ * remove materialised files and clear any exposed env vars.
+ *
+ * `dispose` swallows its own errors -- it never throws. Failures are
+ * surfaced via the optional `onDisposeError` callback passed when the
+ * file-mount host was wired in.
+ */
+export interface StepSecretsHandle {
+    /** The secrets surface bound into `ctx.secrets`. */
+    secrets: TrackedStepSecrets;
+    /** Tear down any materialised files and unset exposed env vars. */
+    dispose: () => Promise<void>;
+}
+/**
+ * Optional wiring for the file-mount + cleanup path. When omitted, calls
+ * to `mountFile` / `exposeFile` throw -- the SDK alone cannot mount files
+ * (no `node:fs` dependency). Production wires a host implementation in
+ * the agent; local test mode wires a minimal `os.tmpdir`-backed host.
+ */
+export interface StepSecretsFileWiring {
+    /** The host adapter (see {@link StepSecretsFileHost}). */
+    host: StepSecretsFileHost;
+    /** Callback for `dispose()` errors. Receives the error for logging. */
+    onDisposeError?: (err: unknown) => void;
+    /** Tear down callback invoked by `dispose()` (removes the tmpdir, etc.). */
+    cleanup: () => Promise<void>;
+}
+/**
+ * Create a StepSecrets instance backed by a plain secrets map.
+ * The env parameter receives exposed secrets via expose().
+ * Tracks which secrets are accessed for audit/observability purposes.
+ *
+ * @param secretsMap - Flat key-value secrets map
+ * @param env - Process environment to inject exposed secrets into
+ * @param metaMap - Optional metadata map from resolveForJobWithMeta (backend + scope per key)
+ * @param fileWiring - Optional file-mount host adapter. When omitted, `mountFile`
+ *   and `exposeFile` throw -- callers that don't wire a host can still use the
+ *   string-only `get` / `expose` / `has` / `list` surface.
+ */
+export declare function createStepSecrets(secretsMap: Record<string, string>, env: Record<string, string | undefined>, metaMap?: Record<string, SecretMeta>, fileWiring?: StepSecretsFileWiring): StepSecretsHandle;
+//# sourceMappingURL=secrets.d.ts.map