@kici-dev/sdk 0.1.16 → 0.1.18

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 import type { z } from 'zod';
 import type { $ as Shell } from 'zx';
-import type { ResourceRequest } from '@kici-dev/engine';
+import type { ResourceRequest, RunsOnAllInput, OnUnreachableMode } from '@kici-dev/engine';
 import type { StepContext, Logger } from './context.js';
 import type { TriggerConfig } from './triggers/types.js';
 import type { Rule } from './rules/types.js';
@@ -10,7 +10,7 @@ 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';
+export type { ResourceRequest, ResourceSpec, RunsOnAllInput, OnUnreachableMode, } from '@kici-dev/engine';
 /** Source location captured at a step() call site. */
 export interface SourceLocation {
     readonly file: string;
@@ -108,13 +108,16 @@ export type Trigger = TriggerConfig;
  * the re-evaluation must produce a job with the same name and the same steps.
  *
  * - `ctx.event` is deterministic — frozen from the original webhook payload.
+ * - `ctx.needs` is deterministic — a snapshot of upstream outputs frozen at first
+ *   eval and replayed unchanged on re-eval, like `ctx.event`. Present only on
+ *   result-aware generators created via `dynamicJob(group, { needs, generate })`.
  * - `$`, `env`, and `kici` can return different results between eval and re-eval
  *   (different agent, different time, different infrastructure state).
  *
- * **Guidance:** derive job names and structure from `ctx.event` data whenever
- * possible. If you use `kici.infrastructure.list()` or shell commands to
- * determine job names, be aware that changes between eval and re-eval will
- * cause a non-determinism warning (or failure if a job disappears).
+ * **Guidance:** derive job names and structure from `ctx.event` / `ctx.needs`
+ * data whenever possible. If you use `kici.infrastructure.list()` or shell
+ * commands to determine job names, be aware that changes between eval and re-eval
+ * will cause a non-determinism warning (or failure if a job disappears).
  */
 export interface DynamicJobContext {
     /** zx shell executor for running commands */
@@ -126,6 +129,12 @@ export interface DynamicJobContext {
         };
         /** Normalized event envelope that triggered this run. */
         event?: EventPayload;
+        /**
+         * Frozen outputs of declared upstream needs (result-aware generators only).
+         * Single-job needs expose `ctx.needs.<job>.result.<field>`; group needs
+         * expose an ordered array of `{ name, result }`.
+         */
+        needs?: import('./needs-context.js').NeedsContext;
     };
     /** Structured logger */
     log: Logger;
@@ -167,16 +176,56 @@ export interface TaggedDynamicJobFn extends DynamicJobFn {
  * Tag a DynamicJobFn with a group name for cross-domain needs.
  * Static jobs can then depend on this group via `needs: [dynamicGroup('name')]`.
  *
+ * Two forms:
+ * - **Function form** (event-only): `dynamicJob('shards', async ({ ctx }) => [...])`.
+ *   Dispatched at webhook time; deterministic from `ctx.event` alone.
+ * - **Options form** (result-aware): `dynamicJob('reports', { needs, generate })`.
+ *   Deferred until every job/group in `needs` completes, then `generate` is
+ *   evaluated with the upstreams' frozen outputs available as `ctx.needs`.
+ *
  * @param groupName - The group name (must match what static jobs reference)
- * @param fn - The dynamic job generator function
+ * @param fnOrConfig - The generator function, or a result-aware `{ needs, generate }` config
  */
-export declare function dynamicJob(groupName: string, fn: DynamicJobFn): TaggedDynamicJobFn;
+export declare function dynamicJob(groupName: string, fnOrConfig: DynamicJobFn | ResultAwareDynamicJobConfig): TaggedDynamicJobFn;
 /**
  * Get the group name from a DynamicJobFn, if it was tagged with dynamicJob().
  * Returns undefined for untagged functions.
  */
 export declare function getDynamicJobGroup(fn: DynamicJobFn): string | undefined;
 export { DYNAMIC_JOB_GROUP_TAG };
+declare const DYNAMIC_JOB_NEEDS_TAG: unique symbol;
+/**
+ * One declared upstream edge for a result-aware generator.
+ * Same shape as the elements of {@link JobOptions.needs}.
+ */
+export type DynamicJobNeed = Job | string | DynamicGroupRef | {
+    name: string;
+    ifFailed?: 'skip' | 'run';
+} | {
+    group: string;
+    ifFailed?: 'skip' | 'run';
+};
+/**
+ * Options-object form of {@link dynamicJob}: a result-aware generator that is
+ * deferred until its declared `needs` complete, then evaluated with their frozen
+ * outputs available as `ctx.needs`.
+ */
+export interface ResultAwareDynamicJobConfig {
+    /** Upstream jobs/groups whose outputs the generator reads via `ctx.needs`. */
+    needs: ReadonlyArray<DynamicJobNeed>;
+    /** The generator. Receives `ctx.needs` resolved from the frozen upstream snapshot. */
+    generate: DynamicJobFn;
+}
+/** A {@link DynamicJobFn} tagged with declared needs (result-aware). */
+export interface ResultAwareDynamicJobFn extends TaggedDynamicJobFn {
+    readonly [DYNAMIC_JOB_NEEDS_TAG]: ReadonlyArray<DynamicJobNeed>;
+}
+/**
+ * Read the declared needs from a result-aware generator.
+ * Returns undefined for event-only generators (the function form of dynamicJob).
+ */
+export declare function getDynamicJobNeeds(fn: DynamicJobFn): ReadonlyArray<DynamicJobNeed> | undefined;
+export { DYNAMIC_JOB_NEEDS_TAG };
 /**
  * Container configuration for job execution.
  * When set, all steps run inside the specified container.
@@ -210,34 +259,86 @@ export interface GenericInitConfig {
     /** Static environment variables available to the command. */
     env?: Record<string, string>;
 }
+/**
+ * Overrides for the `mise` init preset. The preset supplies the `run` command;
+ * these tune the same fields a hand-written {@link GenericInitConfig} exposes,
+ * minus `run`.
+ */
+export interface MiseInitConfig {
+    /** Cache spec for mise's data dir. Omit -> content-derived default; `false` -> no cache. */
+    cache?: import('./cache-types.js').CacheSpec | false;
+    /** Max wall-clock for the mise init command in ms. Defaults to 600000. */
+    timeout?: number;
+    /** Static environment variables available to the mise command. */
+    env?: Record<string, string>;
+    /** Shell used to run the mise command. Defaults to the OS template's shell. */
+    shell?: string;
+}
+/** A typed toolchain preset: zero-config string or an object with overrides. */
+export type InitPreset = 'mise' | {
+    mise: MiseInitConfig;
+};
+/** One init directive: a hand-written generic config or a typed preset. */
+export type InitItem = GenericInitConfig | InitPreset;
+/**
+ * Per-job init configuration:
+ * - a single {@link InitItem} (generic config or preset),
+ * - an ordered array of items (run in order),
+ * - `'auto'` — detect the toolchain from committed files (mise.toml / .tool-versions),
+ * - `false` — explicit opt-out.
+ *
+ * An unset `init` is also "no init". `'auto'` is a scalar only — never an array element.
+ */
+export type InitConfig = InitItem | InitItem[] | 'auto' | false;
 /**
  * Structured runsOn selector with required and excluded labels.
  * Used when jobs need to target specific agents while excluding others.
  *
- * **Reserved namespace:** Labels with the `kici:` prefix are reserved for internal use
- * (e.g., `kici:role:builder`, `kici:role:init-runner`). User-supplied labels starting with
- * `kici:` will be rejected at compile time and agent startup.
+ * **Targeting `kici:` labels:** `runsOn` may target any agent label, including the
+ * `kici:`-namespaced auto-labels (e.g. `kici:os:linux`, `kici:arch:arm64`,
+ * `kici:host:<name>`). Targeting is a requirement on candidate agents, never a grant.
+ * Note that `kici:scaler:<name>` / `kici:agent:<backend>` are deployment-specific names,
+ * so targeting them couples a workflow to one orchestrator's configuration. Users still
+ * cannot *set* `kici:` labels on agents — that namespace is reserved for the scaler and
+ * the agent's self-reported platform facts.
  */
 export interface RunsOnSelector {
-    labels: string | string[];
-    exclude?: string | string[];
+    labels: string | RegExp | (string | RegExp)[];
+    exclude?: string | RegExp | (string | RegExp)[];
 }
 /**
  * Polymorphic runsOn type: string shorthand, array shorthand, or full selector object.
- * - `'linux'` — single label shorthand
- * - `['linux', 'docker']` — multi-label shorthand
- * - `{ labels: ['linux', 'docker'], exclude: ['gpu'] }` — full selector with exclusions
+ * - `'kici:os:linux'` — single label shorthand (targets any linux agent)
+ * - `['kici:os:linux', 'gpu']` — multi-label shorthand (all must match)
+ * - `{ labels: ['kici:os:linux'], exclude: ['kici:host:box-01'] }` — full selector
  *
- * **Reserved namespace:** Labels with the `kici:` prefix are reserved for internal use
- * (e.g., `kici:role:builder`, `kici:role:init-runner`). User-supplied labels starting with
- * `kici:` will be rejected at compile time and agent startup.
+ * A plain string is matched exactly; a string containing glob metachars (`*?[]{}`) is a
+ * glob; a `RegExp` is a regex. Patterns are validated for ReDoS at compile time.
+ *
+ * **Targeting `kici:` labels:** `runsOn` may target any agent label, including the
+ * `kici:`-namespaced auto-labels (`kici:os:`, `kici:arch:`, `kici:host:`, `kici:agent:`,
+ * `kici:scaler:`, `kici:role:`). Targeting is a requirement on candidate agents, never a
+ * grant. `kici:scaler:` / `kici:agent:` are deployment-specific, so prefer custom labels
+ * for portable pool targeting. Users still cannot *set* `kici:` labels on agents.
  */
-export type RunsOn = string | string[] | RunsOnSelector;
+export type RunsOn = string | RegExp | (string | RegExp)[] | RunsOnSelector;
 /** Job definition returned by job() factory */
 export interface Job {
     readonly _tag: 'Job';
     readonly name: string;
-    readonly runsOn: RunsOn;
+    /** Single-agent targeting. Mutually exclusive with `runsOnAll`. */
+    readonly runsOn?: RunsOn;
+    /**
+     * Host fan-out: run one pinned execution per roster host matching the predicate.
+     * Mutually exclusive with `runsOn`.
+     */
+    readonly runsOnAll?: RunsOnAllInput;
+    /** Failure policy for unreachable durable hosts when using `runsOnAll`. */
+    readonly onUnreachable?: OnUnreachableMode;
+    /** Fan-out concurrency width (sliding window; `1` = serial). Applies to matrix and `runsOnAll`. */
+    readonly maxParallel?: number;
+    /** Halt the fan-out on first child failure, skipping the remainder. Default `false`. */
+    readonly failFast?: boolean;
     readonly steps: readonly StepInput[];
     readonly needs?: ReadonlyArray<Job | string | DynamicGroupRef | {
         name: string;
@@ -298,10 +399,12 @@ export interface Job {
     readonly resources?: ResourceRequest;
     /**
      * Per-job initialization. Runs after clone, before steps.
-     * - A `GenericInitConfig` (or array, run in order) provisions a toolchain.
-     * - `false` is an explicit opt-out (reserved for the future auto-detect layer).
+     * - A `GenericInitConfig` or typed preset (`'mise'` / `{ mise }`), single or
+     *   in an ordered array, provisions a toolchain.
+     * - `'auto'` detects the toolchain from committed files (mise.toml / .tool-versions).
+     * - `false` is an explicit opt-out (an unset `init` is also "no init").
      */
-    readonly init?: GenericInitConfig | GenericInitConfig[] | false;
+    readonly init?: InitConfig;
     /** 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. */
@@ -316,7 +419,36 @@ export interface Job {
 }
 /** Options for job() factory */
 export interface JobOptions {
-    runsOn: RunsOn;
+    /** Single-agent targeting. Mutually exclusive with `runsOnAll`. */
+    runsOn?: RunsOn;
+    /**
+     * Host fan-out: run one pinned execution per roster host matching the predicate.
+     * The author writes a label string (`'role:web'`), an array with `!`-prefixed
+     * excludes (`['kici:os:linux', 'role:db', '!kici:host:db-01']`), or the
+     * structured `{ include: [{ all: [...] }], exclude?: [...] }` form.
+     * Mutually exclusive with `runsOn`.
+     */
+    runsOnAll?: RunsOnAllInput;
+    /**
+     * Failure policy for unreachable durable hosts when using `runsOnAll`:
+     * `'skip'` omits them, `'fail'` fails the run, `'hold'` (default) queues a
+     * pinned child and waits. Only meaningful alongside `runsOnAll`.
+     */
+    onUnreachable?: OnUnreachableMode;
+    /**
+     * Fan-out concurrency width: the maximum number of fan-out children (matrix
+     * combinations or `runsOnAll` hosts) that run at once. A sliding window —
+     * each child that reaches a terminal state releases the next held sibling.
+     * `1` = strictly serial (rolling). Applies to both matrix and `runsOnAll`
+     * fan-out; ignored on a non-fan-out job. Must be `>= 1`.
+     */
+    maxParallel?: number;
+    /**
+     * Halt the fan-out on the first child failure: stop releasing new children
+     * and skip the ones still held. Default `false` (every child runs regardless
+     * of sibling outcomes). Applies to both matrix and `runsOnAll` fan-out.
+     */
+    failFast?: boolean;
     /**
      * Steps to execute in this job. Accepts Step objects and bare async functions.
      * Mutually exclusive with `run`.
@@ -401,10 +533,12 @@ export interface JobOptions {
     resources?: ResourceRequest;
     /**
      * Per-job initialization. Runs after clone, before steps.
-     * - A `GenericInitConfig` (or array, run in order) provisions a toolchain.
-     * - `false` is an explicit opt-out (reserved for the future auto-detect layer).
+     * - A `GenericInitConfig` or typed preset (`'mise'` / `{ mise }`), single or
+     *   in an ordered array, provisions a toolchain.
+     * - `'auto'` detects the toolchain from committed files (mise.toml / .tool-versions).
+     * - `false` is an explicit opt-out (an unset `init` is also "no init").
      */
-    init?: GenericInitConfig | GenericInitConfig[] | false;
+    init?: InitConfig;
     /** 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. */

package/dist/types.js

@@ -1,4 +1,4 @@
-import "./chunk-gOLHoazu.js";
+import "./chunk-BTugEXQM.js";
 //#region src/types.ts
 /**
 * Type guard to check if a JobOrFactory is a dynamic job generator.
@@ -11,15 +11,27 @@ const DYNAMIC_JOB_GROUP_TAG = Symbol.for("kici:dynamicJobGroup");
 * Tag a DynamicJobFn with a group name for cross-domain needs.
 * Static jobs can then depend on this group via `needs: [dynamicGroup('name')]`.
 *
+* Two forms:
+* - **Function form** (event-only): `dynamicJob('shards', async ({ ctx }) => [...])`.
+*   Dispatched at webhook time; deterministic from `ctx.event` alone.
+* - **Options form** (result-aware): `dynamicJob('reports', { needs, generate })`.
+*   Deferred until every job/group in `needs` completes, then `generate` is
+*   evaluated with the upstreams' frozen outputs available as `ctx.needs`.
+*
 * @param groupName - The group name (must match what static jobs reference)
-* @param fn - The dynamic job generator function
+* @param fnOrConfig - The generator function, or a result-aware `{ needs, generate }` config
 */
-function dynamicJob(groupName, fn) {
-	const tagged = fn;
+function dynamicJob(groupName, fnOrConfig) {
+	const isConfig = typeof fnOrConfig !== "function";
+	const tagged = isConfig ? fnOrConfig.generate : fnOrConfig;
 	Object.defineProperty(tagged, DYNAMIC_JOB_GROUP_TAG, {
 		value: groupName,
 		enumerable: false
 	});
+	if (isConfig) Object.defineProperty(tagged, DYNAMIC_JOB_NEEDS_TAG, {
+		value: fnOrConfig.needs,
+		enumerable: false
+	});
 	return tagged;
 }
 /**
@@ -29,7 +41,15 @@ function dynamicJob(groupName, fn) {
 function getDynamicJobGroup(fn) {
 	return fn[DYNAMIC_JOB_GROUP_TAG];
 }
+const DYNAMIC_JOB_NEEDS_TAG = Symbol.for("kici:dynamicJobNeeds");
+/**
+* Read the declared needs from a result-aware generator.
+* Returns undefined for event-only generators (the function form of dynamicJob).
+*/
+function getDynamicJobNeeds(fn) {
+	return fn[DYNAMIC_JOB_NEEDS_TAG];
+}
 //#endregion
-export { DYNAMIC_JOB_GROUP_TAG, dynamicJob, getDynamicJobGroup, isDynamicJobFn };
+export { DYNAMIC_JOB_GROUP_TAG, DYNAMIC_JOB_NEEDS_TAG, dynamicJob, getDynamicJobGroup, getDynamicJobNeeds, isDynamicJobFn };
 
 //# sourceMappingURL=types.js.map

package/dist/validation/dag.js

@@ -1,4 +1,4 @@
-import "../chunk-gOLHoazu.js";
+import "../chunk-BTugEXQM.js";
 //#region src/validation/dag.ts
 /**
 * Validate a DAG for common issues: self-references, missing dependencies, and cycles.

package/dist/validation/index.js

@@ -1,3 +1,3 @@
-import "../chunk-gOLHoazu.js";
+import "../chunk-BTugEXQM.js";
 import { validateDag } from "./dag.js";
 export { validateDag };

package/dist/wait-for.js

@@ -1,4 +1,4 @@
-import "./chunk-gOLHoazu.js";
+import "./chunk-BTugEXQM.js";
 import { step } from "./step.js";
 //#region src/wait-for.ts
 /**

package/dist/workflow.js

@@ -1,4 +1,4 @@
-import "./chunk-gOLHoazu.js";
+import "./chunk-BTugEXQM.js";
 //#region src/workflow.ts
 /**
 * Normalize triggers to array.

package/package.json

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