@kici-dev/sdk 0.1.15 → 0.1.16

package/dist/approval.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Workflow-author API for declaring a manual approval gate at step, job, or
+ * workflow level. The author writes `requireApproval`; the compiler normalizes
+ * it into the lock file's `approval` block, and the orchestrator turns it into
+ * a held element at dispatch time.
+ */
+/** A single approver clause: any member of a team, or a specific user. */
+export type ApproverClause = {
+    team: string;
+} | {
+    user: string;
+};
+/**
+ * Declarative approval requirement.
+ *
+ * - `true` — pause for ANY org member with the approval permission.
+ * - `ApproverClause[]` — a flat AND list (all clauses must be satisfied).
+ * - object form — clauses plus an optional human `reason` and a per-gate
+ *   `timeout` (seconds) that overrides the org-default expiry.
+ */
+export type RequireApproval = true | ApproverClause[] | {
+    approvers: ApproverClause[];
+    reason?: string;
+    timeout?: number;
+};
+/** The normalized shape written into the lock file. */
+export interface NormalizedRequireApproval {
+    clauses: ApproverClause[];
+    reason?: string;
+    timeoutSeconds?: number;
+}
+/** Normalize any `RequireApproval` form into `{ clauses, reason?, timeoutSeconds? }`. */
+export declare function normalizeRequireApproval(r: RequireApproval): NormalizedRequireApproval;
+//# sourceMappingURL=approval.d.ts.map

package/dist/approval.js

@@ -0,0 +1,16 @@
+import "./chunk-gOLHoazu.js";
+//#region src/approval.ts
+/** Normalize any `RequireApproval` form into `{ clauses, reason?, timeoutSeconds? }`. */
+function normalizeRequireApproval(r) {
+	if (r === true) return { clauses: [] };
+	if (Array.isArray(r)) return { clauses: r };
+	return {
+		clauses: r.approvers,
+		reason: r.reason,
+		timeoutSeconds: r.timeout
+	};
+}
+//#endregion
+export { normalizeRequireApproval };
+
+//# sourceMappingURL=approval.js.map

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export { step } from './step.js';
 export { job } from './job.js';
 export { workflow } from './workflow.js';
+export { normalizeRequireApproval } from './approval.js';
+export type { RequireApproval, ApproverClause, NormalizedRequireApproval } from './approval.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';

package/dist/index.js

@@ -1,5 +1,6 @@
 import "./chunk-gOLHoazu.js";
 import { buildKiciApi } from "./api-types.js";
+import { normalizeRequireApproval } from "./approval.js";
 import { CacheSpecSchema, normalizeCacheSpecs } from "./cache-types.js";
 import { DYNAMIC_GROUP_TAG, dynamicGroup, isDynamicGroupRef } from "./dynamic-group.js";
 import { SecretNotFoundError } from "./errors.js";
@@ -48,4 +49,4 @@ import { defineEvent } from "./events/define-event.js";
 import "./events/index.js";
 import { WaitForTimeoutError, waitFor, waitForStep } from "./wait-for.js";
 import { z } from "zod";
-export { CacheSpecSchema, 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, normalizeCacheSpecs, 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 };
+export { CacheSpecSchema, 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, normalizeCacheSpecs, normalizeRequireApproval, 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.js

@@ -52,6 +52,7 @@ function job(nameOrOptions, maybeOptions) {
 		resources: options.resources,
 		init: options.init,
 		...options.cache !== void 0 && { cache: options.cache },
+		...options.requireApproval !== void 0 && { requireApproval: options.requireApproval },
 		result: createJobOutputProxy(name)
 	};
 }

package/dist/step.js

@@ -69,6 +69,7 @@ function step(nameOrRunOrOptions, runOrOptions) {
 		rules: options.rules,
 		onCancel: options.onCancel,
 		cleanup: options.cleanup,
+		...options.requireApproval !== void 0 && { requireApproval: options.requireApproval },
 		_sourceLocation,
 		result: createStepOutputProxy(name)
 	};

package/dist/types.d.ts

@@ -9,6 +9,7 @@ import type { HookInput } from './hooks/types.js';
 import type { KiciApi } from './api-types.js';
 import type { DynamicGroupRef } from './dynamic-group.js';
 import type { EventPayload } from './events/event-payloads.js';
+import type { RequireApproval } from './approval.js';
 export type { ResourceRequest, ResourceSpec } from '@kici-dev/engine';
 /** Source location captured at a step() call site. */
 export interface SourceLocation {
@@ -53,6 +54,8 @@ export interface Step<TResult = void> {
     readonly onCancel?: HookInput;
     /** Always runs after step (success, failure, or cancel). */
     readonly cleanup?: HookInput;
+    /** Pause for a manual human approval before this step runs. */
+    readonly requireApproval?: RequireApproval;
     /** Internal: source location captured at step() call site. Not part of public API. */
     readonly _sourceLocation?: SourceLocation;
     /**
@@ -91,6 +94,8 @@ export interface StepOptions<TResult = void> {
     onCancel?: HookInput;
     /** Always runs after step (success, failure, or cancel). */
     cleanup?: HookInput;
+    /** Pause for a manual human approval before this step runs. */
+    requireApproval?: RequireApproval;
 }
 /** Trigger type (config objects returned by pr()/push() factory functions) */
 export type Trigger = TriggerConfig;
@@ -299,6 +304,8 @@ export interface Job {
     readonly init?: GenericInitConfig | GenericInitConfig[] | false;
     /** Declarative cache: restored before steps, saved after the job on key miss. */
     readonly cache?: import('./cache-types.js').CacheInput;
+    /** Pause for a manual human approval before this job dispatches. */
+    readonly requireApproval?: RequireApproval;
     /**
      * Type-safe proxy for accessing this job's outputs.
      * For multi-step jobs: jobRef.result.stepName.field
@@ -400,6 +407,8 @@ export interface JobOptions {
     init?: GenericInitConfig | GenericInitConfig[] | false;
     /** Declarative cache: restored before steps, saved after the job on key miss. */
     cache?: import('./cache-types.js').CacheInput;
+    /** Pause for a manual human approval before this job dispatches. */
+    requireApproval?: RequireApproval;
 }
 /**
  * Private npm registry declaration. Tells the agent to authenticate against
@@ -477,6 +486,8 @@ export interface Workflow {
         readonly cancelInProgress?: boolean;
         readonly max?: number;
     };
+    /** Pause for a manual human approval before the whole workflow dispatches. */
+    readonly requireApproval?: RequireApproval;
 }
 /** Options for workflow() factory */
 export interface WorkflowOptions {
@@ -528,6 +539,8 @@ export interface WorkflowOptions {
         cancelInProgress?: boolean;
         max?: number;
     };
+    /** Pause for a manual human approval before the whole workflow dispatches. */
+    requireApproval?: RequireApproval;
 }
 export type { TriggerConfig, PrTriggerConfig, PushTriggerConfig } from './triggers/types.js';
 export type { Rule, RuleContext, RuleCheckFn, RuleResult } from './rules/types.js';

package/dist/workflow.js

@@ -75,7 +75,8 @@ function workflow(name, options) {
 		cleanup: options.cleanup,
 		onSuccess: options.onSuccess,
 		onFailure: options.onFailure,
-		concurrency: options.concurrency
+		concurrency: options.concurrency,
+		requireApproval: options.requireApproval
 	};
 }
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/sdk",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "TypeScript SDK for defining KiCI workflows. Import into `.kici/workflows/*.ts` to declare workflows, jobs, steps, triggers, rules, and matrix configurations.",
   "keywords": [
     "ci",
@@ -50,8 +50,8 @@
     "micromatch": "^4.0.8",
     "zod": "^4.3.6",
     "zx": "^8.8.5",
-    "@kici-dev/core": "0.1.15",
-    "@kici-dev/engine": "0.1.15"
+    "@kici-dev/core": "0.1.16",
+    "@kici-dev/engine": "0.1.16"
   },
   "devDependencies": {
     "@types/micromatch": "^4.0.10"

package/sbom.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "@kici-dev/sdk@0.1.15",
-  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fsdk/0.1.15/35101d65-2a7e-4b17-9adf-2a2b29322815",
+  "name": "@kici-dev/sdk@0.1.16",
+  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fsdk/0.1.16/49f54029-d7dc-48b9-ad51-af6b845b321f",
   "creationInfo": {
-    "created": "2026-06-11T03:03:30Z",
+    "created": "2026-06-12T09:41:41Z",
     "creators": [
       "Tool: kici-sbom-generator"
     ]
@@ -146,9 +146,9 @@
       "homepage": "https://ericsmekens.github.io/jsep/tree/master/packages/regex#readme"
     },
     {
-      "SPDXID": "SPDXRef-Package--kici-dev-core-0.1.15",
+      "SPDXID": "SPDXRef-Package--kici-dev-core-0.1.16",
       "name": "@kici-dev/core",
-      "versionInfo": "0.1.15",
+      "versionInfo": "0.1.16",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -159,16 +159,16 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/core@0.1.15"
+          "referenceLocator": "pkg:npm/%40kici-dev/core@0.1.16"
         }
       ],
       "description": "Light shared utilities for the KiCI stack (logging, errors, formatting, crypto, zx init, the TypeScript ESM loader hook). No server-side dependencies.",
       "homepage": "https://kici.dev"
     },
     {
-      "SPDXID": "SPDXRef-Package--kici-dev-engine-0.1.15",
+      "SPDXID": "SPDXRef-Package--kici-dev-engine-0.1.16",
       "name": "@kici-dev/engine",
-      "versionInfo": "0.1.15",
+      "versionInfo": "0.1.16",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -179,7 +179,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/engine@0.1.15"
+          "referenceLocator": "pkg:npm/%40kici-dev/engine@0.1.16"
         }
       ],
       "description": "Shared business logic for the KiCI CI/CD stack: protocol, triggers, state machine, and provider interfaces used by the Platform relay, orchestrator, and compiler.",
@@ -188,7 +188,7 @@
     {
       "SPDXID": "SPDXRef-RootPackage",
       "name": "@kici-dev/sdk",
-      "versionInfo": "0.1.15",
+      "versionInfo": "0.1.16",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -199,7 +199,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/sdk@0.1.15"
+          "referenceLocator": "pkg:npm/%40kici-dev/sdk@0.1.16"
         }
       ],
       "description": "TypeScript SDK for defining KiCI workflows. Import into `.kici/workflows/*.ts` to declare workflows, jobs, steps, triggers, rules, and matrix configurations.",
@@ -1544,58 +1544,58 @@
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.15",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.16",
       "relatedSpdxElement": "SPDXRef-Package-oxc-transform-0.128.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.15",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.16",
       "relatedSpdxElement": "SPDXRef-Package-picocolors-1.1.1",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.15",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.16",
       "relatedSpdxElement": "SPDXRef-Package-winston-daily-rotate-file-5.0.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.15",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.16",
       "relatedSpdxElement": "SPDXRef-Package-winston-3.19.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.15",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.16",
       "relatedSpdxElement": "SPDXRef-Package-zod-4.3.6",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.15",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.16",
       "relatedSpdxElement": "SPDXRef-Package-zx-8.8.5",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.15",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.16",
       "relatedSpdxElement": "SPDXRef-Package-jsonpath-plus-10.4.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.15",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.16",
       "relatedSpdxElement": "SPDXRef-Package-picomatch-4.0.4",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.15",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.16",
       "relatedSpdxElement": "SPDXRef-Package-zod-4.3.6",
       "relationshipType": "DEPENDS_ON"
     },
     {
       "spdxElementId": "SPDXRef-RootPackage",
-      "relatedSpdxElement": "SPDXRef-Package--kici-dev-core-0.1.15",
+      "relatedSpdxElement": "SPDXRef-Package--kici-dev-core-0.1.16",
       "relationshipType": "DEPENDS_ON"
     },
     {
       "spdxElementId": "SPDXRef-RootPackage",
-      "relatedSpdxElement": "SPDXRef-Package--kici-dev-engine-0.1.15",
+      "relatedSpdxElement": "SPDXRef-Package--kici-dev-engine-0.1.16",
       "relationshipType": "DEPENDS_ON"
     },
     {