@kici-dev/sdk 0.1.25 → 0.1.27

package/dist/context.d.ts

@@ -37,7 +37,7 @@ export interface AgentInfo {
 /**
  * Outputs of a matrix job as seen by a downstream `needs:` consumer.
  * A downstream that consumes a matrix upstream receives this envelope instead of
- * a flat outputs object, identically under `kici run local` and the remote path.
+ * a flat outputs object, identically under `kici run --local` and the remote path.
  */
 export interface MatrixJobOutputs<T = Record<string, unknown>> {
     /** Keyed by the combination suffix (the text inside `(...)` of the child name). */
@@ -160,7 +160,7 @@ export interface StepContext<TInputs = Record<string, unknown>> {
     /**
      * Raw webhook payload from the git provider.
      * Contains the full, unmodified payload as received from the webhook.
-     * In local preview/run mode (`kici preview` / `kici run local`), contains the simulated payload.
+     * In local preview/run mode (`kici preview` / `kici run --local`), contains the simulated payload.
      * Use this for provider-specific data not covered by normalized fields.
      */
     rawPayload?: Record<string, unknown>;
@@ -189,13 +189,13 @@ export interface StepContext<TInputs = Record<string, unknown>> {
      */
     sourceRepo?: RepoInfo;
     /**
-     * The resolved deployment environment name for this job.
-     * Set when the job declares an `environment` property.
-     * Undefined for jobs without an environment.
+     * The resolved context name for this job.
+     * Set when the job declares a `context` property.
+     * Undefined for jobs without a context.
      */
-    environment?: string;
+    context?: string;
     /**
-     * Secrets resolved for this job's environment.
+     * Secrets resolved for this job's context.
      * Use ctx.secrets.get('KEY') to retrieve a value asynchronously.
      * Use ctx.secrets.expose('KEY') to inject into process.env explicitly.
      * Use ctx.secrets.has('KEY') to check existence synchronously.
@@ -239,7 +239,7 @@ export interface StepContext<TInputs = Record<string, unknown>> {
      * For a plain upstream this returns the job's collected outputs (step-keyed
      * for multi-step, flat for run shorthand). For a **matrix** upstream it returns
      * a {@link MatrixJobOutputs} envelope `{ byMatrix, merged }` keyed by the
-     * combination suffix — identical under `kici run local` and the remote path.
+     * combination suffix — identical under `kici run --local` and the remote path.
      * Use {@link isMatrixJobOutputs} (or `'byMatrix' in result`) to discriminate.
      *
      * @example

package/dist/idempotent.d.ts

@@ -95,8 +95,8 @@ export interface CheckStepOptions<TDrift, TInSync = void, TApplied = void> exten
  *
  * It desugars to the `step()` check facet
  * (`run: (ctx, drift) => apply(ctx, drift)`), so it inherits the agent
- * step-loop and local-executor check-mode drive for free — no engine, agent,
- * orchestrator, or lockfile change.
+ * step-loop check-mode drive for free — no engine, agent, orchestrator, or
+ * lockfile change.
  */
 export declare function checkStep<TDrift, TInSync = void, TApplied = void>(name: string, options: CheckStepOptions<TDrift, TInSync, TApplied>): Step<TApplied | TInSync>;
 //# sourceMappingURL=idempotent.d.ts.map

package/dist/idempotent.js

@@ -79,8 +79,8 @@ function idempotentStep(name, opts) {
 *
 * It desugars to the `step()` check facet
 * (`run: (ctx, drift) => apply(ctx, drift)`), so it inherits the agent
-* step-loop and local-executor check-mode drive for free — no engine, agent,
-* orchestrator, or lockfile change.
+* step-loop check-mode drive for free — no engine, agent, orchestrator, or
+* lockfile change.
 */
 function checkStep(name, options) {
 	return step(name, {

package/dist/job.js

@@ -32,9 +32,9 @@ function job(nameOrOptions, maybeOptions) {
 		steps = [options.run];
 	}
 	validateInit(options.init, name);
-	const firstEnv = options.environments?.[0];
-	const concurrencyGroup = options.concurrencyGroup ?? (typeof firstEnv === "string" ? firstEnv : void 0);
-	if (options.environment !== void 0 && options.environments !== void 0) throw new Error(`job('${name}'): environment and environments are mutually exclusive — use one`);
+	const firstContext = options.contexts?.[0];
+	const concurrencyGroup = options.concurrencyGroup ?? (typeof firstContext === "string" ? firstContext : void 0);
+	if (options.context !== void 0 && options.contexts !== void 0) throw new Error(`job('${name}'): context and contexts are mutually exclusive — use one`);
 	if (options.runsOn !== void 0 && options.runsOnAll !== void 0) throw new Error(`job('${name}'): runsOn and runsOnAll are mutually exclusive`);
 	if (options.runsOn === void 0 && options.runsOnAll === void 0) throw new Error(`job('${name}'): one of runsOn or runsOnAll is required`);
 	if (options.onUnreachable !== void 0 && options.runsOnAll === void 0) console.warn(`[kici] job('${name}'): onUnreachable is ignored without runsOnAll`);
@@ -57,8 +57,8 @@ function job(nameOrOptions, maybeOptions) {
 		exclude: options.exclude,
 		checkout: options.checkout,
 		container: options.container,
-		environment: options.environment,
-		environments: options.environments,
+		context: options.context,
+		contexts: options.contexts,
 		env: options.env,
 		concurrencyGroup,
 		onCancel: options.onCancel,

package/dist/secrets.d.ts

@@ -48,7 +48,7 @@ export interface MountedFile {
  *
  * 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 preview/run mode (`kici preview` / `kici run local`) plugs
+ * any `node:fs` / `node:os` imports. Local preview/run mode (`kici preview` / `kici run --local`) plugs
  * in the same adapter shape against `os.tmpdir()`.
  */
 export interface StepSecretsFileHost {

package/dist/types.d.ts

@@ -471,18 +471,18 @@ export interface Job {
     readonly checkout?: boolean;
     /** Docker image for job execution. All steps run inside the container. */
     readonly container?: string | ContainerConfig;
-    /** Deployment environment for this job. String for static, or a function of the normalized event envelope for dynamic (resolved at orchestrator two-phase eval). */
-    readonly environment?: string | ((event: EventPayload) => string | Promise<string>);
+    /** Bound context for this job. String for static, or a function of the normalized event envelope for dynamic (resolved at orchestrator two-phase eval). */
+    readonly context?: string | ((event: EventPayload) => string | Promise<string>);
     /**
-     * Deployment environments for this job, in merge order (later entries override
-     * earlier on name collisions). Mutually exclusive with `environment`. Each entry
+     * Bound contexts for this job, in merge order (later entries override
+     * earlier on name collisions). Mutually exclusive with `context`. Each entry
      * is a static name or a function of the event (dynamic, resolved per element at
      * two-phase eval).
      */
-    readonly environments?: readonly (string | ((event: EventPayload) => string | Promise<string>))[];
+    readonly contexts?: readonly (string | ((event: EventPayload) => string | Promise<string>))[];
     /** Environment variables. Static object or a function of the normalized event envelope (resolved at orchestrator two-phase eval). */
     readonly env?: Record<string, string> | ((event: EventPayload) => Record<string, string> | Promise<Record<string, string>>);
-    /** Concurrency group name. Defaults to the first bound environment's name if not set. String or a function of the normalized event envelope. */
+    /** Concurrency group name. Defaults to the first bound context's name if not set. String or a function of the normalized event envelope. */
     readonly concurrencyGroup?: string | ((event: EventPayload) => string | Promise<string>);
     /** Runs on cancellation. */
     readonly onCancel?: HookInput;
@@ -619,18 +619,18 @@ export interface JobOptions {
      * When set, all steps run inside the container.
      */
     container?: string | ContainerConfig;
-    /** Deployment environment for this job. String for static, or a function of the normalized event envelope for dynamic (resolved at orchestrator two-phase eval). */
-    environment?: string | ((event: EventPayload) => string | Promise<string>);
+    /** Bound context for this job. String for static, or a function of the normalized event envelope for dynamic (resolved at orchestrator two-phase eval). */
+    context?: string | ((event: EventPayload) => string | Promise<string>);
     /**
-     * Deployment environments for this job, in merge order (later entries override
-     * earlier on name collisions). Mutually exclusive with `environment`. Each entry
+     * Bound contexts for this job, in merge order (later entries override
+     * earlier on name collisions). Mutually exclusive with `context`. Each entry
      * is a static name or a function of the event (dynamic, resolved per element at
      * two-phase eval).
      */
-    environments?: (string | ((event: EventPayload) => string | Promise<string>))[];
+    contexts?: (string | ((event: EventPayload) => string | Promise<string>))[];
     /** Environment variables. Static object or a function of the normalized event envelope (resolved at orchestrator two-phase eval). */
     env?: Record<string, string> | ((event: EventPayload) => Record<string, string> | Promise<Record<string, string>>);
-    /** Concurrency group name. Defaults to the first bound environment's name if not set. String or a function of the normalized event envelope. */
+    /** Concurrency group name. Defaults to the first bound context's name if not set. String or a function of the normalized event envelope. */
     concurrencyGroup?: string | ((event: EventPayload) => string | Promise<string>);
     /** Runs on cancellation. */
     onCancel?: HookInput;
@@ -679,8 +679,8 @@ export interface JobOptions {
  * Private npm registry declaration. Tells the agent to authenticate against
  * a private package registry before running `npm install`.
  *
- * `tokenSecret` uses qualified `<environment>:<secret-name>` syntax — the
- * orchestrator resolves the secret from the named environment's scoped secret
+ * `tokenSecret` uses qualified `<context>:<secret-name>` syntax — the
+ * orchestrator resolves the secret from the named context's scoped secret
  * store at dispatch time. Example: `tokenSecret: 'production:NPM_TOKEN'`.
  */
 export interface Registry {
@@ -692,8 +692,8 @@ export interface Registry {
      */
     readonly scope?: string;
     /**
-     * Qualified secret reference of the form `<environment>:<secret-name>`.
-     * The orchestrator resolves it at dispatch via `secretResolver.resolveForJob(orgId, environment)`.
+     * Qualified secret reference of the form `<context>:<secret-name>`.
+     * The orchestrator resolves it at dispatch via `secretResolver.resolveForJob(orgId, context)`.
      */
     readonly tokenSecret: string;
     /** Whether to require auth on every request (rendered as `always-auth=true` in `.npmrc`). Defaults to `true`. */
@@ -721,14 +721,14 @@ export interface Workflow {
     readonly hashFiles?: string[];
     /**
      * Private npm registries the agent should authenticate against before `npm install`.
-     * Each registry's `tokenSecret` uses qualified `<environment>:<secret-name>` syntax.
+     * Each registry's `tokenSecret` uses qualified `<context>:<secret-name>` syntax.
      */
     readonly registries?: readonly Registry[];
     /**
      * Extra secrets to project as environment variables on the install subprocess.
      * Used together with a customer-committed `.kici/.npmrc` containing `${VAR}` placeholders.
-     * Each entry uses qualified `<environment>:<secret-name>` syntax; the resolved value is
-     * exposed to the install subprocess under the `<secret-name>` key (the environment
+     * Each entry uses qualified `<context>:<secret-name>` syntax; the resolved value is
+     * exposed to the install subprocess under the `<secret-name>` key (the context
      * prefix is stripped for the env-var name).
      */
     readonly installEnv?: readonly string[];
@@ -775,13 +775,13 @@ export interface WorkflowOptions {
     hashFiles?: string[];
     /**
      * Private npm registries the agent should authenticate against before `npm install`.
-     * Each registry's `tokenSecret` uses qualified `<environment>:<secret-name>` syntax.
+     * Each registry's `tokenSecret` uses qualified `<context>:<secret-name>` syntax.
      */
     registries?: Registry[];
     /**
      * Extra secrets to project as environment variables on the install subprocess.
      * Used together with a customer-committed `.kici/.npmrc` containing `${VAR}` placeholders.
-     * Each entry uses qualified `<environment>:<secret-name>` syntax; the resolved value is
+     * Each entry uses qualified `<context>:<secret-name>` syntax; the resolved value is
      * exposed to the install subprocess under the `<secret-name>` key.
      */
     installEnv?: string[];

package/dist/workflow.js

@@ -27,7 +27,7 @@ function normalizeTriggers(on) {
 * });
 */
 /**
-* Validates a `<environment>:<secret-name>` qualified secret reference.
+* Validates a `<context>:<secret-name>` qualified secret reference.
 * Both halves must be non-empty and free of additional colons.
 */
 function isQualifiedSecretRef(value) {
@@ -47,7 +47,7 @@ function workflow(name, options) {
 			} 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 (!isQualifiedSecretRef(reg.tokenSecret)) throw new Error(`workflow('${name}'): registries[${i}].tokenSecret must use qualified <context>:<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})`);
@@ -58,7 +58,7 @@ function workflow(name, options) {
 		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})`);
+		for (const [i, ref] of options.installEnv.entries()) if (!isQualifiedSecretRef(ref)) throw new Error(`workflow('${name}'): installEnv[${i}] must use qualified <context>:<secret-name> syntax (got: ${ref})`);
 	}
 	return {
 		_tag: "Workflow",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/sdk",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "description": "TypeScript SDK for defining KiCI workflows. Import into `.kici/workflows/*.ts` to declare workflows, jobs, steps, triggers, rules, and matrix configurations.",
   "keywords": [
     "ci",
@@ -49,8 +49,8 @@
     "micromatch": "^4.0.8",
     "zod": "^4.4.3",
     "zx": "^8.8.5",
-    "@kici-dev/core": "0.1.25",
-    "@kici-dev/engine": "0.1.25"
+    "@kici-dev/engine": "0.1.27",
+    "@kici-dev/core": "0.1.27"
   },
   "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.25",
-  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fsdk/0.1.25/28cc15a9-6a0e-47f1-956b-685f5211df15",
+  "name": "@kici-dev/sdk@0.1.27",
+  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fsdk/0.1.27/8f9f4abb-dbda-4186-914a-0f3730db25a2",
   "creationInfo": {
-    "created": "2026-07-05T08:32:31Z",
+    "created": "2026-07-10T06:04:01Z",
     "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.25",
+      "SPDXID": "SPDXRef-Package--kici-dev-core-0.1.27",
       "name": "@kici-dev/core",
-      "versionInfo": "0.1.25",
+      "versionInfo": "0.1.27",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -159,16 +159,16 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/core@0.1.25"
+          "referenceLocator": "pkg:npm/%40kici-dev/core@0.1.27"
         }
       ],
       "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.25",
+      "SPDXID": "SPDXRef-Package--kici-dev-engine-0.1.27",
       "name": "@kici-dev/engine",
-      "versionInfo": "0.1.25",
+      "versionInfo": "0.1.27",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -179,7 +179,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/engine@0.1.25"
+          "referenceLocator": "pkg:npm/%40kici-dev/engine@0.1.27"
         }
       ],
       "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.25",
+      "versionInfo": "0.1.27",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -199,7 +199,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/sdk@0.1.25"
+          "referenceLocator": "pkg:npm/%40kici-dev/sdk@0.1.27"
         }
       ],
       "description": "TypeScript SDK for defining KiCI workflows. Import into `.kici/workflows/*.ts` to declare workflows, jobs, steps, triggers, rules, and matrix configurations.",
@@ -1584,68 +1584,68 @@
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.25",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.27",
       "relatedSpdxElement": "SPDXRef-Package-oxc-transform-0.135.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.25",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.27",
       "relatedSpdxElement": "SPDXRef-Package-picocolors-1.1.1",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.25",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.27",
       "relatedSpdxElement": "SPDXRef-Package-winston-daily-rotate-file-5.0.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.25",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.27",
       "relatedSpdxElement": "SPDXRef-Package-winston-3.19.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.25",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.27",
       "relatedSpdxElement": "SPDXRef-Package-zod-4.4.3",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.25",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.27",
       "relatedSpdxElement": "SPDXRef-Package-zx-8.8.5",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.25",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.27",
       "relatedSpdxElement": "SPDXRef-Package-jose-6.2.3",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.25",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.27",
       "relatedSpdxElement": "SPDXRef-Package-jsonpath-plus-10.4.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.25",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.27",
       "relatedSpdxElement": "SPDXRef-Package-picomatch-4.0.4",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.25",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.27",
       "relatedSpdxElement": "SPDXRef-Package-safe-regex-2.1.1",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.25",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.27",
       "relatedSpdxElement": "SPDXRef-Package-zod-4.4.3",
       "relationshipType": "DEPENDS_ON"
     },
     {
       "spdxElementId": "SPDXRef-RootPackage",
-      "relatedSpdxElement": "SPDXRef-Package--kici-dev-core-0.1.25",
+      "relatedSpdxElement": "SPDXRef-Package--kici-dev-core-0.1.27",
       "relationshipType": "DEPENDS_ON"
     },
     {
       "spdxElementId": "SPDXRef-RootPackage",
-      "relatedSpdxElement": "SPDXRef-Package--kici-dev-engine-0.1.25",
+      "relatedSpdxElement": "SPDXRef-Package--kici-dev-engine-0.1.27",
       "relationshipType": "DEPENDS_ON"
     },
     {