@kici-dev/sdk 0.4.0 → 0.6.0

package/dist/rules/context.js

@@ -1,23 +1,8 @@
 import "../rolldown-runtime-ClRpJifh.js";
+import { ChangedFilesUnavailableError, defineChangedFilesGetter, eventTypeOf } from "./changed-files.js";
 import { $ } from "zx";
 //#region src/rules/context.ts
 /**
-* Thrown when a rule reads `ctx.changedFiles` but the diff is not available
-* (`changedFilesStatus !== 'fetched'`). `evaluateRules` re-throws this rather
-* than folding it into a `passed=false` skip, so the job fails loudly instead
-* of silently mis-evaluating a path-based gate.
-*/
-var ChangedFilesUnavailableError = class extends Error {
-	changedFilesStatus;
-	eventType;
-	constructor(status, eventType) {
-		super(`ctx.changedFiles is not available (status: ${status}` + (eventType ? `, event: ${eventType}` : "") + "). Changed files are only defined for push / pull_request events with a computable diff. Guard with ctx.changedFilesStatus before accessing, e.g. `if (ctx.changedFilesStatus !== 'fetched') return true`.");
-		this.name = "ChangedFilesUnavailableError";
-		this.changedFilesStatus = status;
-		this.eventType = eventType;
-	}
-};
-/**
 * Build a RuleContext. `changedFiles` is exposed as a getter: it returns the
 * list when `changedFilesStatus === 'fetched'`, otherwise it throws
 * `ChangedFilesUnavailableError`. This is the single construction site for a
@@ -25,23 +10,20 @@ var ChangedFilesUnavailableError = class extends Error {
 */
 function createRuleContext(input) {
 	const status = input.changedFilesStatus ?? "fetched";
-	const files = input.changedFiles ?? [];
-	const eventType = typeof input.event.type === "string" ? input.event.type : void 0;
 	const base = {
 		event: input.event,
 		changedFilesStatus: status,
 		env: input.env ?? {},
 		dispatchInputs: input.dispatchInputs ?? {},
 		...input.fanout && { fanout: input.fanout },
+		...input.sourceRepo && { sourceRepo: input.sourceRepo },
+		...input.workflowRepo && { workflowRepo: input.workflowRepo },
 		$
 	};
-	Object.defineProperty(base, "changedFiles", {
-		enumerable: true,
-		configurable: true,
-		get() {
-			if (status !== "fetched") throw new ChangedFilesUnavailableError(status, eventType);
-			return files;
-		}
+	defineChangedFilesGetter(base, {
+		files: input.changedFiles ?? [],
+		status,
+		eventType: eventTypeOf(input.event)
 	});
 	return base;
 }

package/dist/rules/evaluator.js

@@ -1,5 +1,6 @@
 import "../rolldown-runtime-ClRpJifh.js";
-import { ChangedFilesUnavailableError } from "./context.js";
+import { ChangedFilesUnavailableError } from "./changed-files.js";
+import "./context.js";
 import { toErrorMessage } from "@kici-dev/core";
 //#region src/rules/evaluator.ts
 /**

package/dist/rules/index.js

@@ -1,6 +1,7 @@
 import "../rolldown-runtime-ClRpJifh.js";
+import { ChangedFilesUnavailableError } from "./changed-files.js";
 import { onlyOnFanoutIndex, onlyOnFirstHost, onlyOnLastHost, rule, skip } from "./rule.js";
-import { ChangedFilesUnavailableError, createRuleContext } from "./context.js";
+import { createRuleContext } from "./context.js";
 import { evaluateRules } from "./evaluator.js";
 import { isEventType } from "../events/event-payloads.js";
 export { ChangedFilesUnavailableError, createRuleContext, evaluateRules, isEventType, onlyOnFanoutIndex, onlyOnFirstHost, onlyOnLastHost, rule, skip };

package/dist/rules/types.d.ts

@@ -1,6 +1,7 @@
 import type { $ as Shell } from 'zx';
 import type { EventPayload } from '../events/event-payloads.js';
 import type { FanoutPosition } from '../fanout-context.js';
+import type { RepoInfo } from '../context.js';
 export type { EventPayload } from '../events/event-payloads.js';
 /**
  * Context passed to rule check functions.
@@ -21,6 +22,14 @@ export interface RuleContext {
     changedFiles: string[];
     /** Availability of `changedFiles` (see `changedFiles`). */
     changedFilesStatus: import('@kici-dev/engine').ChangedFilesStatus;
+    /**
+     * The repo whose event triggered this run. Present for a global workflow and
+     * for any evaluation that runs with a checkout; undefined otherwise.
+     * Read through `.path`; never embed it in a job name (see FilterContext).
+     */
+    sourceRepo?: RepoInfo;
+    /** The repo that registered the workflow. Identical to `sourceRepo` outside a global workflow. */
+    workflowRepo?: RepoInfo;
     /** Environment variables */
     env: Record<string, string | undefined>;
     /** Operator-supplied, validated + coerced workflow-dispatch inputs. Empty when none declared. */

package/dist/testing/step-context.js

@@ -2,8 +2,8 @@ import "../rolldown-runtime-ClRpJifh.js";
 import { resolveJobOutputs, resolveStepOutputs } from "../outputs.js";
 import { createStepSecrets } from "../secrets.js";
 import { isEventDefinition } from "../events/define-event.js";
-import { initZx } from "@kici-dev/core";
 import { $ } from "zx";
+import { initZx } from "@kici-dev/core";
 import { chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
@@ -218,13 +218,15 @@ function createTestStepContext(options = {}) {
 				get: () => Promise.resolve(null)
 			},
 			oidc: { token: () => Promise.reject(/* @__PURE__ */ new Error("ctx.kici.oidc.token() is not available in a test step context")) },
+			git: { github: { getToken: () => Promise.reject(/* @__PURE__ */ new Error("ctx.kici.git.github.getToken() is not available in a test step context")) } },
 			host: { requestReboot: () => Promise.reject(/* @__PURE__ */ new Error("ctx.kici.host.requestReboot() is not available in a test step context")) },
 			bootstrap: {
 				ensureInitRunner: () => Promise.reject(/* @__PURE__ */ new Error("ctx.kici.bootstrap.ensureInitRunner() is not available in a test step context")),
 				preBootSend: () => Promise.reject(/* @__PURE__ */ new Error("ctx.kici.bootstrap.preBootSend() is not available in a test step context")),
 				agentVersionStatus: () => Promise.reject(/* @__PURE__ */ new Error("ctx.kici.bootstrap.agentVersionStatus() is not available in a test step context")),
 				restageAgent: () => Promise.reject(/* @__PURE__ */ new Error("ctx.kici.bootstrap.restageAgent() is not available in a test step context"))
-			}
+			},
+			scaler: { claimAgentCredentials: () => Promise.reject(/* @__PURE__ */ new Error("ctx.kici.scaler.claimAgentCredentials() is not available in a test step context")) }
 		},
 		cache: {
 			restore: async () => ({ hit: false }),

package/dist/triggers/pr.js

@@ -38,6 +38,8 @@ function pr(config) {
 		sourceBranches: Object.freeze([...sourceBranches]),
 		paths: Object.freeze([...paths]),
 		repos: Object.freeze([...repos]),
+		...config?.requires !== void 0 && { requires: Object.freeze([...config.requires]) },
+		...config?.commitMessage !== void 0 && { commitMessage: config.commitMessage },
 		...config?.description !== void 0 && { description: config.description }
 	};
 	return Object.freeze(result);

package/dist/triggers/push.js

@@ -38,6 +38,8 @@ function push(config) {
 		tags: Object.freeze([...tags]),
 		paths: Object.freeze([...paths]),
 		repos: Object.freeze([...repos]),
+		...config?.requires !== void 0 && { requires: Object.freeze([...config.requires]) },
+		...config?.commitMessage !== void 0 && { commitMessage: config.commitMessage },
 		...config?.description !== void 0 && { description: config.description }
 	};
 	return Object.freeze(result);

package/dist/triggers/tag.js

@@ -21,6 +21,8 @@ function tag(config) {
 		_tag: "TagTrigger",
 		patterns: Object.freeze([...patterns]),
 		repos: Object.freeze([...repos]),
+		...config?.requires !== void 0 && { requires: Object.freeze([...config.requires]) },
+		...config?.commitMessage !== void 0 && { commitMessage: config.commitMessage },
 		...config?.description !== void 0 && { description: config.description }
 	};
 	return Object.freeze(result);

package/dist/triggers/types.d.ts

@@ -3,6 +3,8 @@
  * Supports both glob patterns and regex patterns for branch/path matching.
  */
 import type { z } from 'zod';
+import type { ContentRequirement, TextMatch } from '@kici-dev/engine';
+export type { ContentRequirement, ContentFormat, TextMatch } from '@kici-dev/engine';
 /**
  * A declared map of typed workflow-dispatch inputs: `{ name: ZodSchema }`.
  * Each schema must fall within the closed dispatch-input subset (extracted by
@@ -44,6 +46,10 @@ export interface PrTriggerConfig {
     readonly sourceBranches: readonly BranchPattern[];
     readonly paths: readonly string[];
     readonly repos: readonly BranchPattern[];
+    /** Declarative static content filter over source files at the event ref (AND-ed). */
+    readonly requires?: readonly ContentRequirement[];
+    /** Declarative static filter over the event's commit message / PR title+body. */
+    readonly commitMessage?: TextMatch;
     readonly description?: string;
 }
 /**
@@ -55,6 +61,10 @@ export interface PushTriggerConfig {
     readonly tags: readonly BranchPattern[];
     readonly paths: readonly string[];
     readonly repos: readonly BranchPattern[];
+    /** Declarative static content filter over source files at the event ref (AND-ed). */
+    readonly requires?: readonly ContentRequirement[];
+    /** Declarative static filter over the event's commit message / PR title+body. */
+    readonly commitMessage?: TextMatch;
     readonly description?: string;
 }
 /**
@@ -64,6 +74,10 @@ export interface TagTriggerConfig {
     readonly _tag: 'TagTrigger';
     readonly patterns: readonly BranchPattern[];
     readonly repos: readonly BranchPattern[];
+    /** Declarative static content filter over source files at the event ref (AND-ed). */
+    readonly requires?: readonly ContentRequirement[];
+    /** Declarative static filter over the event's commit message / PR title+body. */
+    readonly commitMessage?: TextMatch;
     readonly description?: string;
 }
 /**
@@ -72,6 +86,10 @@ export interface TagTriggerConfig {
 export interface TagConfigInput {
     readonly patterns?: string | RegExp | (string | RegExp)[];
     readonly repos?: string | RegExp | (string | RegExp)[];
+    /** Declarative static content filter over source files at the event ref (AND-ed). */
+    readonly requires?: readonly ContentRequirement[];
+    /** Declarative static filter over the event's commit message / PR title+body. */
+    readonly commitMessage?: TextMatch;
     readonly description?: string;
 }
 export type CommentAction = 'created' | 'edited' | 'deleted';
@@ -558,6 +576,10 @@ export interface PrConfigInput {
     readonly source?: string | RegExp | (string | RegExp)[];
     readonly paths?: string[];
     readonly repos?: string | RegExp | (string | RegExp)[];
+    /** Declarative static content filter over source files at the event ref (AND-ed). */
+    readonly requires?: readonly ContentRequirement[];
+    /** Declarative static filter over the event's commit message / PR title+body. */
+    readonly commitMessage?: TextMatch;
     readonly description?: string;
 }
 /**
@@ -569,6 +591,10 @@ export interface PushConfigInput {
     readonly tags?: string | RegExp | (string | RegExp)[];
     readonly paths?: string[];
     readonly repos?: string | RegExp | (string | RegExp)[];
+    /** Declarative static content filter over source files at the event ref (AND-ed). */
+    readonly requires?: readonly ContentRequirement[];
+    /** Declarative static filter over the event's commit message / PR title+body. */
+    readonly commitMessage?: TextMatch;
     readonly description?: string;
 }
 /**

package/dist/types.d.ts

@@ -1,8 +1,10 @@
 import type { z } from 'zod';
 import type { $ as Shell } from 'zx';
 import type { RetryBackoff } from '@kici-dev/core';
+import type { GitCredentialMap, ContainerRegistryAuth } from './git-types.js';
 import type { ResourceRequest, RunsOnAllInput, OnUnreachableMode, NeedsWhen, ExecutionJobStatus } from '@kici-dev/engine';
-import type { StepContext, Logger } from './context.js';
+import type { StepContext, Logger, RepoInfo } from './context.js';
+import type { FilterFn } from './filter.js';
 import type { SingleNeedEntry, NeedsContext } from './needs-context.js';
 import type { TriggerConfig } from './triggers/types.js';
 import type { Rule } from './rules/types.js';
@@ -308,6 +310,14 @@ export interface DynamicJobContext {
     env: Record<string, string | undefined>;
     /** Typed KiCI API — orchestrator queries over WS (e.g., kici.infrastructure.list()) */
     kici: KiciApi;
+    /**
+     * The repo whose event triggered this run. Present for a global workflow and
+     * for any evaluation that runs with a checkout; undefined otherwise.
+     * Read through `.path`; never embed it in a job name (see FilterContext).
+     */
+    sourceRepo?: RepoInfo;
+    /** The repo that registered the workflow. Identical to `sourceRepo` outside a global workflow. */
+    workflowRepo?: RepoInfo;
 }
 /**
  * Async function that generates jobs dynamically at runtime.
@@ -397,10 +407,43 @@ export { DYNAMIC_JOB_NEEDS_TAG };
  * When set, all steps run inside the specified container.
  */
 export interface ContainerConfig {
-    /** Docker image name (e.g., 'node:20-alpine') */
-    image: string;
+    /**
+     * Docker image name (e.g., 'node:20-alpine'). Mutually exclusive with
+     * `dockerfile`; exactly one of the two is required.
+     */
+    image?: string;
+    /**
+     * Repo-relative path to a Dockerfile the agent builds before the job runs.
+     * Mutually exclusive with `image`.
+     *
+     * The build runs on the agent host, NOT inside the job's hardened sandbox.
+     * See the container-jobs documentation for the trust model and the
+     * untrusted-ref rule.
+     */
+    dockerfile?: string;
+    /**
+     * Repo-relative build context. Defaults to the repository root.
+     * Meaningful only with `dockerfile`.
+     */
+    context?: string;
+    /** Build stage to stop at (`--target`). Meaningful only with `dockerfile`. */
+    target?: string;
+    /**
+     * Build arguments. Meaningful only with `dockerfile`.
+     *
+     * Plain strings only, deliberately: a build argument is recorded in the
+     * image's history, so a secret placed here is readable by anyone who can
+     * inspect the image. Pass a secret to a step instead.
+     */
+    args?: Record<string, string>;
     /** Additional environment variables for the container */
     env?: Record<string, string>;
+    /**
+     * Private-registry credentials. With `image` they pull that image; with
+     * `dockerfile` they pull the Dockerfile's own `FROM` base — and must name
+     * the registry, because there is no image reference to derive it from.
+     */
+    auth?: ContainerRegistryAuth;
 }
 /**
  * Per-job sandbox escape hatch for container-sandbox jobs (a job with a
@@ -565,6 +608,13 @@ export interface Job<TOutputs = Record<string, unknown>, TName extends string =
     readonly maxParallel?: number;
     /** Halt the fan-out on first child failure, skipping the remainder. Default `false`. */
     readonly failFast?: boolean;
+    /**
+     * Invoke the source repo's opt-in workflows and gate on them. Mutually
+     * exclusive with `steps` / `run` — an invoke job never runs step code on an
+     * agent; it fans out into one proxy node per triggered run. Built by
+     * `invokeSource()`.
+     */
+    readonly invoke?: import('./invoke.js').InvokeConfig;
     readonly steps: readonly StepInput[];
     readonly needs?: ReadonlyArray<Job | string | DynamicGroupRef | {
         name: string;
@@ -585,6 +635,17 @@ export interface Job<TOutputs = Record<string, unknown>, TName extends string =
     readonly exclude?: MatrixExclude[];
     /** When false, agent skips git clone (default: true). Useful for deploy/notify jobs. */
     readonly checkout?: boolean;
+    /**
+     * Named git credentials available to every step in this job.
+     *
+     * Values are **secret names**, resolved from the secrets backend — never
+     * secret material. `default` is used whenever a call names no credential;
+     * any other key is referenced by name, e.g.
+     * `kici.git.clone({ repo, credential: 'forge' })`.
+     *
+     * Omit entirely and the source credential applies, which is all a read needs.
+     */
+    readonly gitCredentials?: GitCredentialMap;
     /** Docker image for job execution. All steps run inside the container. */
     readonly container?: string | ContainerConfig;
     /** Per-job sandbox escape hatch (container jobs only); granted within the operator allow-list. */
@@ -700,6 +761,13 @@ export interface JobOptions {
      * of sibling outcomes). Applies to both matrix and `runsOnAll` fan-out.
      */
     failFast?: boolean;
+    /**
+     * Invoke the source repo's opt-in workflows and gate on them. Mutually
+     * exclusive with `steps` / `run` — an invoke job never runs step code on an
+     * agent; it fans out into one proxy node per triggered run. Built by
+     * `invokeSource()`.
+     */
+    invoke?: import('./invoke.js').InvokeConfig;
     /**
      * Steps to execute in this job. Accepts Step objects and bare async functions.
      * Mutually exclusive with `run`.
@@ -740,6 +808,17 @@ export interface JobOptions {
     exclude?: MatrixExclude[];
     /** When false, agent skips git clone (default: true). Useful for deploy/notify jobs. */
     checkout?: boolean;
+    /**
+     * Named git credentials available to every step in this job.
+     *
+     * Values are **secret names**, resolved from the secrets backend — never
+     * secret material. `default` is used whenever a call names no credential;
+     * any other key is referenced by name, e.g.
+     * `kici.git.clone({ repo, credential: 'forge' })`.
+     *
+     * Omit entirely and the source credential applies, which is all a read needs.
+     */
+    gitCredentials?: GitCredentialMap;
     /**
      * Docker image for job execution.
      * Simple string form for image name, object form for additional config.
@@ -845,6 +924,23 @@ export interface Workflow {
     readonly on?: TriggerConfig[];
     /** Rules for conditional execution */
     readonly rules?: Rule[];
+    /**
+     * Pre-dispatch predicate deciding whether this workflow applies to the event's
+     * source repo. A `false` result suppresses the workflow's jobs — none is
+     * dispatched, and none is reported as skipped.
+     *
+     * An organization-wide workflow is evaluated once per (event × workflow repo)
+     * before any run row is created, so a `false` verdict produces no run. A
+     * same-repo workflow is evaluated once per job and once per job generator,
+     * after the run row exists — so a run is recorded showing the evaluation and
+     * none of the workflow's own jobs. Because it runs once per job there, the
+     * predicate must be cheap, side-effect free, and deterministic; see `FilterFn`.
+     *
+     * One same-repo exception: a job **held for approval** or **rejected by a
+     * context rule** is not filtered at all. The hold or the rule is its gate, so
+     * an approved job dispatches with no filter verdict having been taken.
+     */
+    readonly filter?: FilterFn;
     /** Optional description */
     readonly description?: string;
     /**
@@ -899,6 +995,26 @@ export interface WorkflowOptions {
     on?: Trigger | Trigger[];
     /** Rules that must pass for workflow to execute */
     rules?: Rule[];
+    /**
+     * Pre-dispatch predicate deciding whether this workflow applies to the event's
+     * source repo. Runs on an evaluating agent with the tree(s) on disk, and a
+     * `false` result suppresses the workflow's jobs — none is dispatched, and none
+     * is reported as skipped.
+     *
+     * An organization-wide workflow is evaluated once per (event × workflow repo)
+     * before any run row is created, so a `false` verdict produces no run. A
+     * same-repo workflow is evaluated once per job and once per job generator,
+     * after the run row exists — so a run is recorded showing the evaluation and
+     * none of the workflow's own jobs. Because it runs once per job there, the
+     * predicate must be cheap, side-effect free, and deterministic; see `FilterFn`.
+     *
+     * One same-repo exception: a job **held for approval** or **rejected by a
+     * context rule** is not filtered at all. The hold or the rule is its gate, so
+     * an approved job dispatches with no filter verdict having been taken.
+     *
+     * See `FilterContext` for what it receives and what it deliberately does not.
+     */
+    filter?: FilterFn;
     /** Optional description for documentation */
     description?: string;
     /**

package/dist/workflow.js

@@ -60,12 +60,14 @@ function workflow(name, options) {
 	if (options.installEnv) {
 		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})`);
 	}
+	if (options.filter !== void 0 && typeof options.filter !== "function") throw new Error(`workflow('${name}'): filter must be a function (got: ${typeof options.filter})`);
 	return {
 		_tag: "Workflow",
 		name,
 		jobs: options.jobs,
 		on: normalizeTriggers(options.on),
 		rules: options.rules,
+		filter: options.filter,
 		description: options.description,
 		hashFiles: options.hashFiles,
 		registries: options.registries,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/sdk",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "TypeScript SDK for defining KiCI workflows. Import into `.kici/workflows/*.ts` to declare workflows, jobs, steps, triggers, rules, and matrix configurations.",
   "keywords": [
     "ci",
@@ -52,10 +52,11 @@
   },
   "dependencies": {
     "micromatch": "^4.0.8",
+    "yaml": "^2.9.0",
     "zod": "^4.4.3",
     "zx": "^8.8.5",
-    "@kici-dev/core": "0.4.0",
-    "@kici-dev/engine": "0.4.0"
+    "@kici-dev/core": "0.6.0",
+    "@kici-dev/engine": "0.6.0"
   },
   "devDependencies": {
     "@types/micromatch": "^4.0.10"