@kici-dev/compiler 0.1.25 → 0.1.27

package/dist/local-plane/trusted-routing.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Route a `kici run --local --trusted` run onto the plane's trusted label set
+ * by appending a routing label to every job's `runsOn` in the workdir lock the
+ * plane orchestrator reads.
+ *
+ * The orchestrator resolves each job's target agent from the lock's `runsOn`
+ * selectors (subset match + smallest-set-wins in the scaler label matcher).
+ * A default run leaves `runsOn` untouched, so a `runsOn: ['default']` job lands
+ * on the sandboxed `['default']` label set — byte-identical to a non-trusted
+ * run. `--trusted` appends the non-reserved `self-hosted` label, which only the
+ * trusted `['default','self-hosted']` label set carries, forcing every job onto
+ * the trusted profile.
+ *
+ * This is routing-by-label to a PRE-CONFIGURED trusted scaler label set — the
+ * `KICI_TRUSTED_ENV` value lives only in that label set's env (the plane's own
+ * config), never on a dispatch payload. The lock patch adds a label
+ * requirement, not the trusted flag itself.
+ */
+/** Handle to restore the lock to its pre-patch bytes. */
+export interface RunsOnLabelInjection {
+    /** Rewrite the original bytes captured before the patch. */
+    restore: () => void;
+}
+/**
+ * Append an exact-match `runsOn` selector for `label` to every job in the lock
+ * at `lockPath`, unless the job already requires it. Returns a `restore()` that
+ * rewrites the original file bytes (call it in a `finally` — for an in-place run
+ * it un-dirties the developer's tree; for an isolated run the throwaway clone is
+ * removed anyway).
+ */
+export declare function injectRunsOnLabel(lockPath: string, label: string): RunsOnLabelInjection;
+//# sourceMappingURL=trusted-routing.d.ts.map

package/dist/local-plane/trusted-routing.js

@@ -0,0 +1,47 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import fs from "node:fs";
+//#region src/local-plane/trusted-routing.ts
+/**
+* Route a `kici run --local --trusted` run onto the plane's trusted label set
+* by appending a routing label to every job's `runsOn` in the workdir lock the
+* plane orchestrator reads.
+*
+* The orchestrator resolves each job's target agent from the lock's `runsOn`
+* selectors (subset match + smallest-set-wins in the scaler label matcher).
+* A default run leaves `runsOn` untouched, so a `runsOn: ['default']` job lands
+* on the sandboxed `['default']` label set — byte-identical to a non-trusted
+* run. `--trusted` appends the non-reserved `self-hosted` label, which only the
+* trusted `['default','self-hosted']` label set carries, forcing every job onto
+* the trusted profile.
+*
+* This is routing-by-label to a PRE-CONFIGURED trusted scaler label set — the
+* `KICI_TRUSTED_ENV` value lives only in that label set's env (the plane's own
+* config), never on a dispatch payload. The lock patch adds a label
+* requirement, not the trusted flag itself.
+*/
+/**
+* Append an exact-match `runsOn` selector for `label` to every job in the lock
+* at `lockPath`, unless the job already requires it. Returns a `restore()` that
+* rewrites the original file bytes (call it in a `finally` — for an in-place run
+* it un-dirties the developer's tree; for an isolated run the throwaway clone is
+* removed anyway).
+*/
+function injectRunsOnLabel(lockPath, label) {
+	const original = fs.readFileSync(lockPath, "utf-8");
+	const lock = JSON.parse(original);
+	for (const workflow of lock.workflows ?? []) for (const job of workflow.jobs ?? []) {
+		const runsOn = job.runsOn ??= [];
+		if (!runsOn.some((m) => m.kind === "exact" && m.value === label)) runsOn.push({
+			kind: "exact",
+			value: label
+		});
+	}
+	fs.writeFileSync(lockPath, JSON.stringify(lock, null, 2) + "\n");
+	return { restore: () => {
+		fs.writeFileSync(lockPath, original);
+	} };
+}
+//#endregion
+export { injectRunsOnLabel };
+
+//# sourceMappingURL=trusted-routing.js.map

package/dist/lockfile/generator.js

@@ -485,12 +485,12 @@ function validateRunsOn(runsOn, jobName) {
 	if (overlap.length > 0) throw new Error(`Job "${jobName}": labels and exclude overlap on [${overlap.join(", ")}]. A label cannot be both required and excluded.`);
 }
 /**
-* Transform one environment reference (static name or function) into a lock
+* Transform one context reference (static name or function) into a lock
 * `{ value, dynamic }` entry. A function element is analyzed for purity: a pure
 * function becomes an inline expression resolvable at two-phase eval; an impure
 * one carries only the `dynamic` flag (the agent runs an init job to resolve it).
 */
-function transformEnvironmentRef(ref, jobName) {
+function transformContextRef(ref, jobName) {
 	if (typeof ref === "function") {
 		const fnSource = ref.toString();
 		const purity = analyzePurity(fnSource);
@@ -501,7 +501,7 @@ function transformEnvironmentRef(ref, jobName) {
 			},
 			dynamic: true
 		};
-		console.warn(`[kici] Job "${jobName}": environment function is not pure (${purity.reason}). An init job will be required, adding ~5-10s delay.`);
+		console.warn(`[kici] Job "${jobName}": context function is not pure (${purity.reason}). An init job will be required, adding ~5-10s delay.`);
 		return {
 			value: "",
 			dynamic: true
@@ -522,9 +522,9 @@ function transformJob(job, configPath, index, gitRoot, uuidToName) {
 	if (job.maxParallel !== void 0 && job.maxParallel < 1) throw new Error(`job '${job.name}': maxParallel must be >= 1`);
 	if (!(job.matrix !== void 0 || job.runsOnAll !== void 0) && (job.maxParallel !== void 0 || job.failFast !== void 0)) console.warn(`[kici] job '${job.name}': maxParallel/failFast are ignored without matrix or runsOnAll (no fan-out to bound)`);
 	if (job.runsOn !== void 0) validateRunsOn(job.runsOn, job.name);
-	const environmentFields = {};
-	const envRefs = job.environments ?? (job.environment !== void 0 ? [job.environment] : void 0);
-	if (envRefs !== void 0 && envRefs.length > 0) environmentFields.environments = envRefs.map((ref) => transformEnvironmentRef(ref, job.name));
+	const contextFields = {};
+	const contextRefs = job.contexts ?? (job.context !== void 0 ? [job.context] : void 0);
+	if (contextRefs !== void 0 && contextRefs.length > 0) contextFields.contexts = contextRefs.map((ref) => transformContextRef(ref, job.name));
 	const envFields = {};
 	if (job.env !== void 0) {
 		if (typeof job.env === "function") {
@@ -576,7 +576,7 @@ function transformJob(job, configPath, index, gitRoot, uuidToName) {
 		...job.checkout !== void 0 && { checkout: job.checkout },
 		...job.cache !== void 0 && { cache: normalizeCacheSpecs(job.cache) },
 		...job.container !== void 0 && { container: job.container },
-		...environmentFields,
+		...contextFields,
 		...envFields,
 		...concurrencyFields,
 		...job.onCancel !== void 0 && { hasOnCancel: true },

package/dist/remote/dashboard-client.d.ts

@@ -36,18 +36,18 @@ export interface RegistrationsListFilters {
     repoIdentifier?: string;
 }
 /**
- * A secret context (environment) as surfaced to the developer CLI's
+ * A secret context (context) as surfaced to the developer CLI's
  * `secrets list` / `types` commands. The orchestrator returns the per-env
  * secret key names (never values) when `includeSecrets` is requested.
  */
-declare const environmentContextSchema: z.ZodObject<{
+declare const contextContextSchema: z.ZodObject<{
     name: z.ZodString;
     enabled: z.ZodBoolean;
     allowLocalExecution: z.ZodBoolean;
     secretKeys: z.ZodDefault<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
-/** A secret context (environment) returned by {@link DashboardClient.listEnvironments}. */
-export type EnvironmentContext = z.infer<typeof environmentContextSchema>;
+/** A secret context (context) returned by {@link DashboardClient.listContexts}. */
+export type ContextContext = z.infer<typeof contextContextSchema>;
 export declare class DashboardClient {
     private readonly endpoint;
     private readonly token;
@@ -80,13 +80,13 @@ export declare class DashboardClient {
     /** List the org's permanently registered workflows (GET /registrations). */
     listRegistrations(filters?: RegistrationsListFilters): Promise<RegistrationsListResult>;
     /**
-     * List the org's environments as secret contexts (GET /environments).
+     * List the org's contexts as secret contexts (GET /contexts).
      *
-     * Pass `includeSecrets` to have the orchestrator attach each environment's
+     * Pass `includeSecrets` to have the orchestrator attach each context's
      * reachable secret key names (never values). Used by `kici secrets list`
      * and `kici types`.
      */
-    listEnvironments(includeSecrets?: boolean): Promise<EnvironmentContext[]>;
+    listContexts(includeSecrets?: boolean): Promise<ContextContext[]>;
 }
 export {};
 //# sourceMappingURL=dashboard-client.d.ts.map

package/dist/remote/dashboard-client.js

@@ -29,17 +29,17 @@ const registrationsListSchema = z.object({
 	registryUpdatedAt: z.string()
 });
 /**
-* A secret context (environment) as surfaced to the developer CLI's
+* A secret context (context) as surfaced to the developer CLI's
 * `secrets list` / `types` commands. The orchestrator returns the per-env
 * secret key names (never values) when `includeSecrets` is requested.
 */
-const environmentContextSchema = z.object({
+const contextContextSchema = z.object({
 	name: z.string(),
 	enabled: z.boolean(),
 	allowLocalExecution: z.boolean(),
 	secretKeys: z.array(z.string()).default([])
 });
-const environmentsListSchema = z.object({ environments: z.array(environmentContextSchema).default([]) });
+const contextsListSchema = z.object({ contexts: z.array(contextContextSchema).default([]) });
 const STATUS_ERROR_MAP = {
 	401: ["unauthorized", "Authentication failed. Run `kici login` to re-authenticate."],
 	403: ["forbidden", "Access denied."],
@@ -151,15 +151,15 @@ var DashboardClient = class DashboardClient {
 		return registrationsListSchema.parse(await this.getJson(`/registrations${suffix}`));
 	}
 	/**
-	* List the org's environments as secret contexts (GET /environments).
+	* List the org's contexts as secret contexts (GET /contexts).
 	*
-	* Pass `includeSecrets` to have the orchestrator attach each environment's
+	* Pass `includeSecrets` to have the orchestrator attach each context's
 	* reachable secret key names (never values). Used by `kici secrets list`
 	* and `kici types`.
 	*/
-	async listEnvironments(includeSecrets = false) {
+	async listContexts(includeSecrets = false) {
 		const suffix = includeSecrets ? "?includeSecrets=true" : "";
-		return environmentsListSchema.parse(await this.getJson(`/environments${suffix}`)).environments;
+		return contextsListSchema.parse(await this.getJson(`/contexts${suffix}`)).contexts;
 	}
 };
 //#endregion

package/dist/remote/platform-client.d.ts

@@ -94,7 +94,7 @@ export interface PlatformTriggerResponse {
     status: 'accepted' | 'rejected';
     reason?: string;
     jobIds?: string[];
-    /** User-visible warnings on acceptance (e.g. skipped non-test bound environments). */
+    /** User-visible warnings on acceptance (e.g. skipped non-test bound contexts). */
     warnings?: string[];
 }
 export interface PlatformRunStatusResponse {

package/dist/remote/secret-loader.d.ts

@@ -0,0 +1,18 @@
+import type { ParsedSecrets } from '../test-runner/secrets-file.js';
+/**
+ * Load secrets from multiple sources with merge precedence.
+ *
+ * Merge order (lowest to highest priority):
+ * 1. .kici/.secrets (INI-style, backward compat)
+ * 2. .kici/.env.local (dotenv format)
+ * 3. .kici/secrets.yaml (YAML with context scopes, merged flat)
+ * 4. --env KEY=VALUE CLI flags
+ *
+ * Note: process.env is NOT merged here -- it's handled at step-context level.
+ *
+ * @param kiciDir - Path to the .kici directory
+ * @param envFlags - Optional --env KEY=VALUE flag values
+ * @returns Merged secrets with correct precedence
+ */
+export declare function loadLocalSecrets(kiciDir: string, envFlags?: string[]): Promise<ParsedSecrets>;
+//# sourceMappingURL=secret-loader.d.ts.map

package/dist/{local-executor → remote}/secret-loader.js

@@ -3,7 +3,7 @@ import { loadSecretsFile } from "../test-runner/secrets-file.js";
 import path from "node:path";
 import { readFile } from "node:fs/promises";
 import { parse } from "yaml";
-//#region src/local-executor/secret-loader.ts
+//#region src/remote/secret-loader.ts
 /**
 * Parse a dotenv-style file (.env.local) into flat key-value pairs.
 * Lines starting with # are comments. Blank lines are ignored.
@@ -24,8 +24,8 @@ function parseDotenv(content) {
 }
 /**
 * Parse a secrets.yaml file.
-* Expected format: top-level keys are environment names, values are key-value maps.
-* For local execution, all environments are merged flat (no environment resolution).
+* Expected format: top-level keys are context names, values are key-value maps.
+* For local execution, all contexts are merged flat (no context resolution).
 */
 function parseSecretsYaml(content) {
 	const parsed = parse(content);
@@ -66,7 +66,7 @@ async function readFileOrNull(filePath) {
 * Merge order (lowest to highest priority):
 * 1. .kici/.secrets (INI-style, backward compat)
 * 2. .kici/.env.local (dotenv format)
-* 3. .kici/secrets.yaml (YAML with environment scopes, merged flat)
+* 3. .kici/secrets.yaml (YAML with context scopes, merged flat)
 * 4. --env KEY=VALUE CLI flags
 *
 * Note: process.env is NOT merged here -- it's handled at step-context level.

package/dist/remote/secret-upload.d.ts

@@ -6,7 +6,7 @@
  */
 export declare function parseContextFlags(flags: string[] | undefined): Record<string, Record<string, string>>;
 /**
- * Load the developer's local secrets (same sources as `kici run local`: the
+ * Load the developer's local secrets (same sources as `kici run --local`: the
  * `.kici` secret files plus `--env` flat flags) and `--context` namespaced
  * flags, and encrypt them to the orchestrator's per-upload X25519 public key.
  * `--context` values override `.kici/.secrets` file contexts for the same key.

package/dist/remote/secret-upload.js

@@ -1,5 +1,5 @@
 import "../rolldown-runtime-ClRpJifh.js";
-import { loadLocalSecrets } from "../local-executor/secret-loader.js";
+import { loadLocalSecrets } from "./secret-loader.js";
 import { encryptJson } from "@kici-dev/core";
 //#region src/remote/secret-upload.ts
 /**
@@ -25,7 +25,7 @@ function parseContextFlags(flags) {
 	return contexts;
 }
 /**
-* Load the developer's local secrets (same sources as `kici run local`: the
+* Load the developer's local secrets (same sources as `kici run --local`: the
 * `.kici` secret files plus `--env` flat flags) and `--context` namespaced
 * flags, and encrypt them to the orchestrator's per-upload X25519 public key.
 * `--context` values override `.kici/.secrets` file contexts for the same key.

package/dist/remote/uploader.d.ts

@@ -82,7 +82,7 @@ export interface OverlaySelection {
  * When `fullWorkingTree` is set (the `kici run remote` path), the entire
  * `.git` directory is additively included so the extracted overlay is a real
  * git repository on the agent — workflow steps that shell out to git then work
- * exactly as they do under `kici run local`. The `.git` files are added after
+ * exactly as they do under `kici run --local`. The `.git` files are added after
  * `.kiciignore` filtering (git internals are never subject to working-tree
  * ignore globs).
  *

package/dist/remote/uploader.js

@@ -44,7 +44,7 @@ function isGitDirPath(relPath) {
 * clone on the agent — we enumerate the directory explicitly. Including the
 * whole `.git` directory (objects, refs, HEAD, index, config, packed-refs)
 * makes the extracted overlay a real git repository, so workflow steps that
-* shell out to git work exactly as they do under `kici run local`.
+* shell out to git work exactly as they do under `kici run --local`.
 */
 async function collectGitDirFiles(repoRoot) {
 	const gitRoot = path.join(repoRoot, ".git");
@@ -94,7 +94,7 @@ async function loadKiciIgnore(kiciIgnorePath) {
 * When `fullWorkingTree` is set (the `kici run remote` path), the entire
 * `.git` directory is additively included so the extracted overlay is a real
 * git repository on the agent — workflow steps that shell out to git then work
-* exactly as they do under `kici run local`. The `.git` files are added after
+* exactly as they do under `kici run --local`. The `.git` files are added after
 * `.kiciignore` filtering (git internals are never subject to working-tree
 * ignore globs).
 *

package/dist/templates/agents-md.d.ts

@@ -4,5 +4,5 @@
  * picked up by Claude Code, Cursor, Aider, and other coding agents that scan
  * the working tree for an authoring context file.
  */
-export declare const agentsMdTemplate = "# KiCI workflow authoring guide\n\nThis project uses KiCI \u2014 a TypeScript-native CI/CD workflow engine \u2014 instead\nof YAML-based CI. Workflows live in `.kici/workflows/*.ts`, are compiled\ninto a portable lock file, and executed by self-hosted agents.\n\n## Where the API surface lives\n\n- Public SDK types: `node_modules/@kici-dev/sdk/dist/index.d.ts` \u2014 read this\n  for the canonical signatures of `workflow`, `job`, `step`, `pr`,\n  `push`, `schedule`, `matrix`, `rule`, `dynamicJob`, etc.\n- Bundled offline reference for coding agents: `kici docs llm` prints the\n  full markdown documentation bundle to stdout. `kici docs llm --index`\n  prints just the curated link index (llms.txt format).\n- Online docs:\n  - <https://kici.dev/docs/> \u2014 published docs site.\n  - <https://kici.dev/llms.txt> \u2014 curated index for LLM consumers.\n  - <https://kici.dev/llms-full.txt> \u2014 full markdown bundle.\n  - Key pages: `user/sdk-reference`, `user/workflow-patterns`,\n    `user/testing-guide`, `user/hooks`, `user/secrets`.\n\n## The five core patterns\n\n1. **Push trigger** \u2014 `on: push({ branches: 'main' })`. Pair with `paths`\n   to scope to subtrees.\n\n   ```ts\n   import { workflow, job, step, push } from '@kici-dev/sdk';\n\n   export default workflow('build', {\n     on: push({ branches: 'main' }),\n     jobs: [\n       job('build', {\n         runsOn: 'kici:os:linux',\n         steps: [step('install', async ({ $ }) => { await $`pnpm install`; })],\n       }),\n     ],\n   });\n   ```\n\n   `kici:os:linux` targets any agent reporting that OS \u2014 every agent\n   self-reports `kici:os:` / `kici:arch:` / `kici:host:`. Use a custom label\n   (e.g. `'gpu'`, `'prod-pool'`) to target a specific agent pool your scaler\n   defines.\n\n2. **PR + matrix** \u2014 `pr({ target: 'main' })` plus a matrix over node\n   versions. The matrix expands at dispatch time.\n\n   ```ts\n   import { workflow, job, step, pr, matrix } from '@kici-dev/sdk';\n\n   export default workflow('test-matrix', {\n     on: pr({ target: 'main' }),\n     jobs: [\n       job('test', {\n         runsOn: 'kici:os:linux',\n         strategy: { matrix: matrix({ node: ['20', '22', '24'] }) },\n         steps: [\n           step('test', async ({ $, matrix }) => {\n             await $`node --version`;\n             await $`pnpm install`;\n             await $`pnpm test`;\n             return { node: matrix.node };\n           }),\n         ],\n       }),\n     ],\n   });\n   ```\n\n3. **Lifecycle hooks** \u2014 `onFailure` / `onSuccess` / `onCancel` on a\n   job or workflow run after the main steps in their own scope.\n\n4. **Secrets** \u2014 declared scopes resolve at dispatch:\n\n   ```ts\n   step('deploy', async ({ $, secrets }) => {\n     await $`./scripts/deploy.sh`.env({ DEPLOY_TOKEN: secrets.production.DEPLOY_TOKEN });\n   });\n   ```\n\n   Run `kici secrets list` to enumerate the contexts available for testing.\n\n5. **Dynamic jobs** \u2014 `dynamicJob` and `dynamicGroup` build the DAG at\n   runtime from a step's outputs. Don't try to compute job names at top level;\n   the lock file would be wrong.\n\n## Anti-patterns\n\n- **Do NOT write `.yml` / `.yaml` CI files** \u2014 KiCI replaces that entire\n  layer. There is no compatibility shim.\n- **Do NOT `import` from any `@kici-dev/*` package's `/dist/...`\n  subpath** \u2014 those are not part of the public API and break across versions.\n  Import from the package root.\n- **Do NOT `await` outside step bodies.** The top-level workflow file is\n  loaded by the compiler synchronously; async I/O at module scope means the\n  lock file emits before it resolves and the workflow appears empty.\n- **Do NOT mutate shared variables between jobs.** Each job runs in its own\n  agent process. Use `needs` + step outputs to thread values.\n- **Do NOT hand-edit `kici.lock.json`.** Regenerate it via `kici compile`.\n\n## Local commands a coding agent should run\n\n| Command                         | Purpose                                     |\n| ------------------------------- | ------------------------------------------- |\n| `pnpm kici compile --check`     | Validate workflow source without writing.   |\n| `pnpm kici preview pr:open --debug` | Preview which workflows match an event.   |\n| `pnpm kici run local push`      | Execute workflows locally with no orchestrator. |\n| `pnpm kici docs llm`            | Print the full LLM documentation bundle.    |\n| `pnpm kici docs llm --index`    | Print the curated link index.               |\n\nIf `pnpm kici` isn't in scripts, fall back to `npx kici`.\n\n## Loop\n\n1. Read the SDK types from `node_modules/@kici-dev/sdk/dist/index.d.ts`.\n2. Pipe `kici docs llm` into the agent's context if it doesn't already have\n   the full bundle.\n3. Edit a workflow under `.kici/workflows/`.\n4. Run `kici compile --check` (zero exit means valid).\n5. Run `kici preview <event>` to preview matching.\n6. Run `kici run local <event>` to execute locally before pushing.\n";
+export declare const agentsMdTemplate = "# KiCI workflow authoring guide\n\nThis project uses KiCI \u2014 a TypeScript-native CI/CD workflow engine \u2014 instead\nof YAML-based CI. Workflows live in `.kici/workflows/*.ts`, are compiled\ninto a portable lock file, and executed by self-hosted agents.\n\n## Where the API surface lives\n\n- Public SDK types: `node_modules/@kici-dev/sdk/dist/index.d.ts` \u2014 read this\n  for the canonical signatures of `workflow`, `job`, `step`, `pr`,\n  `push`, `schedule`, `matrix`, `rule`, `dynamicJob`, etc.\n- Bundled offline reference for coding agents: `kici docs llm` prints the\n  full markdown documentation bundle to stdout. `kici docs llm --index`\n  prints just the curated link index (llms.txt format).\n- Online docs:\n  - <https://kici.dev/docs/> \u2014 published docs site.\n  - <https://kici.dev/llms.txt> \u2014 curated index for LLM consumers.\n  - <https://kici.dev/llms-full.txt> \u2014 full markdown bundle.\n  - Key pages: `user/sdk-reference`, `user/workflow-patterns`,\n    `user/testing-guide`, `user/hooks`, `user/secrets`.\n\n## The five core patterns\n\n1. **Push trigger** \u2014 `on: push({ branches: 'main' })`. Pair with `paths`\n   to scope to subtrees.\n\n   ```ts\n   import { workflow, job, step, push } from '@kici-dev/sdk';\n\n   export default workflow('build', {\n     on: push({ branches: 'main' }),\n     jobs: [\n       job('build', {\n         runsOn: 'kici:os:linux',\n         steps: [step('install', async ({ $ }) => { await $`pnpm install`; })],\n       }),\n     ],\n   });\n   ```\n\n   `kici:os:linux` targets any agent reporting that OS \u2014 every agent\n   self-reports `kici:os:` / `kici:arch:` / `kici:host:`. Use a custom label\n   (e.g. `'gpu'`, `'prod-pool'`) to target a specific agent pool your scaler\n   defines.\n\n2. **PR + matrix** \u2014 `pr({ target: 'main' })` plus a matrix over node\n   versions. The matrix expands at dispatch time.\n\n   ```ts\n   import { workflow, job, step, pr, matrix } from '@kici-dev/sdk';\n\n   export default workflow('test-matrix', {\n     on: pr({ target: 'main' }),\n     jobs: [\n       job('test', {\n         runsOn: 'kici:os:linux',\n         strategy: { matrix: matrix({ node: ['20', '22', '24'] }) },\n         steps: [\n           step('test', async ({ $, matrix }) => {\n             await $`node --version`;\n             await $`pnpm install`;\n             await $`pnpm test`;\n             return { node: matrix.node };\n           }),\n         ],\n       }),\n     ],\n   });\n   ```\n\n3. **Lifecycle hooks** \u2014 `onFailure` / `onSuccess` / `onCancel` on a\n   job or workflow run after the main steps in their own scope.\n\n4. **Secrets** \u2014 declared scopes resolve at dispatch:\n\n   ```ts\n   step('deploy', async ({ $, secrets }) => {\n     await $`./scripts/deploy.sh`.env({ DEPLOY_TOKEN: secrets.production.DEPLOY_TOKEN });\n   });\n   ```\n\n   Run `kici secrets list` to enumerate the contexts available for testing.\n\n5. **Dynamic jobs** \u2014 `dynamicJob` and `dynamicGroup` build the DAG at\n   runtime from a step's outputs. Don't try to compute job names at top level;\n   the lock file would be wrong.\n\n## Anti-patterns\n\n- **Do NOT write `.yml` / `.yaml` CI files** \u2014 KiCI replaces that entire\n  layer. There is no compatibility shim.\n- **Do NOT `import` from any `@kici-dev/*` package's `/dist/...`\n  subpath** \u2014 those are not part of the public API and break across versions.\n  Import from the package root.\n- **Do NOT `await` outside step bodies.** The top-level workflow file is\n  loaded by the compiler synchronously; async I/O at module scope means the\n  lock file emits before it resolves and the workflow appears empty.\n- **Do NOT mutate shared variables between jobs.** Each job runs in its own\n  agent process. Use `needs` + step outputs to thread values.\n- **Do NOT hand-edit `kici.lock.json`.** Regenerate it via `kici compile`.\n\n## Local commands a coding agent should run\n\n| Command                         | Purpose                                     |\n| ------------------------------- | ------------------------------------------- |\n| `pnpm kici compile --check`     | Validate workflow source without writing.   |\n| `pnpm kici preview pr:open --debug` | Preview which workflows match an event.   |\n| `pnpm kici run push --local`    | Execute a workflow locally (this machine as an ephemeral agent). |\n| `pnpm kici docs llm`            | Print the full LLM documentation bundle.    |\n| `pnpm kici docs llm --index`    | Print the curated link index.               |\n\nIf `pnpm kici` isn't in scripts, fall back to `npx kici`.\n\n## Loop\n\n1. Read the SDK types from `node_modules/@kici-dev/sdk/dist/index.d.ts`.\n2. Pipe `kici docs llm` into the agent's context if it doesn't already have\n   the full bundle.\n3. Edit a workflow under `.kici/workflows/`.\n4. Run `kici compile --check` (zero exit means valid).\n5. Run `kici preview <event>` to preview matching.\n6. Run `kici run <event> --local` to execute locally before pushing.\n";
 //# sourceMappingURL=agents-md.d.ts.map

package/dist/templates/agents-md.js

@@ -113,7 +113,7 @@ into a portable lock file, and executed by self-hosted agents.
 | ------------------------------- | ------------------------------------------- |
 | \`pnpm kici compile --check\`     | Validate workflow source without writing.   |
 | \`pnpm kici preview pr:open --debug\` | Preview which workflows match an event.   |
-| \`pnpm kici run local push\`      | Execute workflows locally with no orchestrator. |
+| \`pnpm kici run push --local\`    | Execute a workflow locally (this machine as an ephemeral agent). |
 | \`pnpm kici docs llm\`            | Print the full LLM documentation bundle.    |
 | \`pnpm kici docs llm --index\`    | Print the curated link index.               |
 
@@ -127,7 +127,7 @@ If \`pnpm kici\` isn't in scripts, fall back to \`npx kici\`.
 3. Edit a workflow under \`.kici/workflows/\`.
 4. Run \`kici compile --check\` (zero exit means valid).
 5. Run \`kici preview <event>\` to preview matching.
-6. Run \`kici run local <event>\` to execute locally before pushing.
+6. Run \`kici run <event> --local\` to execute locally before pushing.
 `;
 //#endregion
 export { agentsMdTemplate };

package/dist/templates/package-json.js

@@ -1,6 +1,6 @@
 import "../rolldown-runtime-ClRpJifh.js";
 //#region src/templates/package-json.ts
-const sdkVersion = "0.1.25";
+const sdkVersion = "0.1.27";
 /**
 * Generate package.json content for .kici/ directory
 *

package/dist/test-runner/job-executor.js

@@ -2,7 +2,7 @@ import "../rolldown-runtime-ClRpJifh.js";
 import { formatter } from "./output-formatter.js";
 import { createStepContext } from "./step-context.js";
 import { createRuleContext, evaluateRules as evaluateRulesWithFormatting } from "./rule-evaluator.js";
-import { localRunsOnString } from "../local-executor/runs-on-display.js";
+import { localRunsOnString } from "./runs-on-display.js";
 import { pathToFileURL } from "node:url";
 import path from "node:path";
 import pc from "picocolors";

package/dist/test-runner/runs-on-display.d.ts

@@ -0,0 +1,9 @@
+import type { RunsOn } from '@kici-dev/sdk';
+/**
+ * Render a job's `runsOn` to the comma-joined label string the local/test
+ * runners surface as `ctx.job.runsOn`. A `runsOnAll` job has no `runsOn` —
+ * locally it runs once on this machine, so we surface the marker `'runsOnAll'`.
+ * RegExp selectors render via their `/source/flags` literal.
+ */
+export declare function localRunsOnString(runsOn: RunsOn | undefined): string;
+//# sourceMappingURL=runs-on-display.d.ts.map

package/dist/{local-executor → test-runner}/runs-on-display.js

@@ -1,5 +1,5 @@
 import "../rolldown-runtime-ClRpJifh.js";
-//#region src/local-executor/runs-on-display.ts
+//#region src/test-runner/runs-on-display.ts
 /** Render one selector element (string label or RegExp) for the local display string. */
 function runsOnElementString(el) {
 	return el instanceof RegExp ? el.toString() : el;

package/dist/test-runner/step-context.d.ts

@@ -11,5 +11,5 @@ import type { StepContext, WorkflowInfo, JobInfo, MatrixValues } from '@kici-dev
 export declare function createStepContext(workflowInfo: WorkflowInfo, jobInfo: JobInfo, repoRoot: string, inputs?: Record<string, unknown>, matrix?: MatrixValues, testSecrets?: {
     flat: Record<string, string>;
     contexts: Record<string, Record<string, string>>;
-}, environment?: string, rawPayload?: Record<string, unknown>, provider?: string, dispatchInputs?: Readonly<Record<string, string | number | boolean | null>>, signal?: AbortSignal): StepContext;
+}, context?: string, rawPayload?: Record<string, unknown>, provider?: string, dispatchInputs?: Readonly<Record<string, string | number | boolean | null>>, signal?: AbortSignal): StepContext;
 //# sourceMappingURL=step-context.d.ts.map

package/dist/test-runner/step-context.js

@@ -42,7 +42,7 @@ function createTestLogger(jobName) {
 * `ctx.$` would inherit `process.cwd()` — i.e. wherever the user invoked
 * `kici` — which silently breaks any step that uses relative paths.
 */
-function createStepContext(workflowInfo, jobInfo, repoRoot, inputs = {}, matrix, testSecrets, environment, rawPayload, provider, dispatchInputs = {}, signal = new AbortController().signal) {
+function createStepContext(workflowInfo, jobInfo, repoRoot, inputs = {}, matrix, testSecrets, context, rawPayload, provider, dispatchInputs = {}, signal = new AbortController().signal) {
 	const flat = testSecrets?.flat ?? {};
 	const namespacedSecrets = testSecrets?.contexts ?? {};
 	const mergedFlat = { ...flat };
@@ -116,7 +116,7 @@ function createStepContext(workflowInfo, jobInfo, repoRoot, inputs = {}, matrix,
 		job: jobInfo,
 		matrix,
 		isTestRun: false,
-		environment,
+		context,
 		...rawPayload && { rawPayload },
 		...provider && { provider },
 		secrets: secretsHandle.secrets,

package/dist/types.d.ts

@@ -28,7 +28,7 @@ export interface LockApproval {
     readonly when: 'always' | 'drift';
 }
 /** Schema version - re-exported from engine as single source of truth */
-export declare const SCHEMA_VERSION: 29;
+export declare const SCHEMA_VERSION: 30;
 /**
  * Source file reference with meaningful path.
  * Format: file is relative path from git root, export uses hash syntax.
@@ -441,11 +441,11 @@ export interface LockJob {
         env?: Record<string, string>;
     };
     /**
-     * Deployment environments in merge order. Each entry is a static name or inline
+     * Bound contexts in merge order. Each entry is a static name or inline
      * expression (pure function); `dynamic` is set when it is a function resolved at
      * two-phase eval. Later entries override earlier ones on name collisions.
      */
-    readonly environments?: ReadonlyArray<{
+    readonly contexts?: ReadonlyArray<{
         value: string | LockInlineValue;
         dynamic: boolean;
     }>;
@@ -517,12 +517,12 @@ export type LockJobOrFactory = LockJob | LockDynamicJobFn;
 /**
  * Private npm registry declaration in the lock file.
  * Carries URL/scope/secret-reference but NOT the resolved token — the orchestrator
- * resolves the token at dispatch via the per-environment secretResolver path.
+ * resolves the token at dispatch via the per-context secretResolver path.
  */
 export interface LockRegistry {
     readonly url: string;
     readonly scope?: string;
-    /** Qualified secret reference: `<environment>:<secret-name>`. */
+    /** Qualified secret reference: `<context>:<secret-name>`. */
     readonly tokenSecret: string;
     readonly alwaysAuth?: boolean;
 }
@@ -554,7 +554,7 @@ export interface LockWorkflow {
      */
     readonly registries?: readonly LockRegistry[];
     /**
-     * Extra qualified secret refs (`<environment>:<secret-name>`) to project as env vars
+     * Extra qualified secret refs (`<context>:<secret-name>`) to project as env vars
      * on the install subprocess for use with a customer-committed `.kici/.npmrc`.
      */
     readonly installEnv?: readonly string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/compiler",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "description": "Compiler and CLI for KiCI workflows. Compiles `.kici/workflows/*.ts` to a `kici.lock.json` file consumed by the orchestrator and agents, and runs workflows locally or against a remote orchestrator.",
   "keywords": [
     "ci",
@@ -49,6 +49,7 @@
     "@inquirer/prompts": "^8.5.2",
     "chokidar": "^5.0.0",
     "commander": "^15.0.0",
+    "embedded-postgres": "18.4.0-beta.17",
     "fast-glob": "^3.3.3",
     "open": "^11.0.0",
     "picocolors": "^1.1.1",
@@ -60,11 +61,13 @@
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
     "zx": "^8.8.5",
-    "@kici-dev/core": "0.1.25",
-    "@kici-dev/engine": "0.1.25"
+    "@kici-dev/orchestrator": "0.1.27",
+    "@kici-dev/core": "0.1.27",
+    "@kici-dev/agent": "0.1.27",
+    "@kici-dev/engine": "0.1.27"
   },
   "peerDependencies": {
-    "@kici-dev/sdk": "0.1.25"
+    "@kici-dev/sdk": "0.1.27"
   },
   "devDependencies": {
     "@types/proper-lockfile": "^4.1.4"