@kici-dev/sdk 0.1.26 → 0.2.0

package/dist/types.d.ts

@@ -3,6 +3,7 @@ import type { $ as Shell } from 'zx';
 import type { RetryBackoff } from '@kici-dev/core';
 import type { ResourceRequest, RunsOnAllInput, OnUnreachableMode, NeedsWhen, ExecutionJobStatus } from '@kici-dev/engine';
 import type { StepContext, Logger } from './context.js';
+import type { SingleNeedEntry, NeedsContext } from './needs-context.js';
 import type { TriggerConfig } from './triggers/types.js';
 import type { Rule } from './rules/types.js';
 import type { Matrix, MatrixInclude, MatrixExclude } from './matrix/types.js';
@@ -33,6 +34,78 @@ export interface SourceLocation {
 export type OutputProxy<T> = {
     readonly [K in keyof T]: T[K];
 };
+/** Collapse a union of object types into their intersection (`{a} | {b}` -> `{a} & {b}`). */
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/**
+ * A single step's contribution to its job's merged output map. A named,
+ * non-void step contributes `{ [name]: result }`; an id-less step (empty name)
+ * or a void step contributes nothing; a bare function / parallel group in the
+ * steps array contributes nothing. Used by {@link InferJobOutputsFromSteps}.
+ */
+type StepOutputEntry<TStep> = TStep extends Step<infer TResult, infer TName> ? TName extends '' ? object : [TResult] extends [void] ? object : {
+    readonly [K in TName]: TResult;
+} : object;
+/**
+ * Merge every named, non-void step's outputs into the job's nested output map,
+ * keyed by step name — reproducing the runtime shape `jobRef.result.<step>.<field>`
+ * for a multi-step job. When no step contributes a name (all id-less or void),
+ * falls back to the loose `Record<string, unknown>` so untyped code keeps
+ * compiling. The `run:` shorthand does NOT go through this helper: it infers a
+ * flat shape from the run function's return type at the `job()` overload.
+ */
+export type InferJobOutputsFromSteps<TSteps extends readonly unknown[]> = UnionToIntersection<{
+    [I in keyof TSteps]: StepOutputEntry<TSteps[I]>;
+}[number]> extends infer M ? keyof M extends never ? Record<string, unknown> : {
+    readonly [K in keyof M]: M[K];
+} : never;
+/**
+ * One `needs` tuple element's contribution to the typed `ctx.needs` map. A job
+ * reference with a literal name, or a `'name'` string / `{ name }` object,
+ * contributes `{ [name]: SingleNeedEntry<T> }` (outputs typed for a job ref,
+ * loose for a string/name); a name-less job, a group ref, or a `{ group }`
+ * entry contributes nothing typed (they fall back to the loose map).
+ */
+type NeedFromTupleEntry<E> = E extends Job<infer TOut, infer TName> ? string extends TName ? object : TName extends '' ? object : {
+    readonly [K in TName]: SingleNeedEntry<TOut>;
+} : E extends string ? string extends E ? object : {
+    readonly [K in E]: SingleNeedEntry<Record<string, unknown>>;
+} : E extends {
+    name: infer N;
+} ? N extends string ? string extends N ? object : {
+    readonly [K in N]: SingleNeedEntry<Record<string, unknown>>;
+} : object : object;
+/**
+ * True when at least one `needs` tuple element cannot be keyed (a group ref, a
+ * `{ group }` entry, or a name-less job) — i.e. its {@link NeedFromTupleEntry}
+ * contributes no key. Such an element would be silently dropped from a strict
+ * closed map, so its presence forces the loose fallback.
+ */
+type HasUnkeyableNeed<TNeeds extends readonly unknown[]> = true extends {
+    [I in keyof TNeeds]: keyof NeedFromTupleEntry<TNeeds[I]> extends never ? true : false;
+}[number] ? true : false;
+/**
+ * Derive the typed `ctx.needs` map from a job's `needs` tuple. The strict, closed
+ * map (keyed by upstream name — job references carry their inferred outputs,
+ * string / `{ name }` entries key loose) is produced ONLY when every entry is
+ * keyable, so reading an undeclared need is a compile error. If any entry cannot
+ * be keyed (a group reference, a `{ group }` entry, or a name-less job), the whole
+ * map falls back to the loose {@link NeedsContext} — the group's key stays
+ * accessible and no valid read regresses to a type error.
+ */
+export type NeedsFromTuple<TNeeds extends readonly unknown[]> = HasUnkeyableNeed<TNeeds> extends true ? NeedsContext : UnionToIntersection<{
+    [I in keyof TNeeds]: NeedFromTupleEntry<TNeeds[I]>;
+}[number]> extends infer M ? keyof M extends never ? NeedsContext : {
+    readonly [K in keyof M]: M[K];
+} : never;
+/**
+ * The step/run context with its `needs` narrowed to the typed map derived from
+ * the enclosing job's `needs` tuple. Used as the contextual type of the `run:`
+ * shorthand so `ctx.needs.<job>.result.<field>` is checked. `needs` is required
+ * here (a job with declared needs always has them at runtime).
+ */
+export type StepContextWithNeeds<TNeeds extends readonly unknown[]> = Omit<StepContext, 'needs'> & {
+    needs: NeedsFromTuple<TNeeds>;
+};
 /** Output schema type - record of Zod types */
 export type OutputSchema = Record<string, z.ZodTypeAny>;
 /** Infer the output type from an output schema */
@@ -43,10 +116,15 @@ export type InferOutputs<T extends OutputSchema> = z.infer<z.ZodObject<T>>;
  * TResult is the inferred return type of the run function (defaults to void for backward compat).
  * The optional `outputs` field holds a Zod schema for runtime validation but does NOT drive the generic.
  */
-export interface Step<TResult = void> {
+export interface Step<TResult = void, TName extends string = string> {
     readonly _tag: 'Step';
-    /** Step name. Empty string for id-less steps (compiler assigns counter IDs). */
-    readonly name: string;
+    /**
+     * Step name, carried as a literal type. Empty string (`''`) for id-less steps
+     * (the compiler assigns counter IDs at lock generation). The literal name is
+     * what lets a named step contribute a typed key to its job's merged output map
+     * (see {@link InferJobOutputsFromSteps}).
+     */
+    readonly name: TName;
     /** Optional Zod schema for runtime output validation. */
     readonly outputs?: OutputSchema;
     readonly run: (ctx: StepContext, drift?: any) => Promise<TResult>;
@@ -324,6 +402,29 @@ export interface ContainerConfig {
     /** Additional environment variables for the container */
     env?: Record<string, string>;
 }
+/**
+ * Per-job sandbox escape hatch for container-sandbox jobs (a job with a
+ * `container:` image). Requests are granted only within the operator's
+ * allow-list (`sandboxAllowedCapabilities` / `sandboxAllowHostNetwork`); a
+ * request for anything not allow-listed FAILS the run at dispatch with a reason
+ * naming the offending capability or knob — never a silent downgrade.
+ */
+export interface SandboxOptions {
+    /**
+     * Extra Linux capabilities to add back over the hardened `CapDrop:['ALL']`
+     * baseline (e.g. `['NET_ADMIN']`). Each requested capability must be
+     * allow-listed by the operator via `sandboxAllowedCapabilities`. Unknown
+     * capability names are rejected at author time.
+     */
+    capabilities?: string[];
+    /**
+     * Container network posture. `'host'` shares the host network namespace and
+     * is the escalation — it requires the operator to enable
+     * `sandboxAllowHostNetwork`. `'none'` (loopback-only) and `'default'` (bridge)
+     * are always allowed (they do not escalate).
+     */
+    network?: 'default' | 'none' | 'host';
+}
 /**
  * Generic per-job initialization config. Runs a hand-written command after the
  * repo is cloned and before the job's steps execute, so a repo-declared
@@ -424,10 +525,25 @@ export type RunsOnPick = 'deterministic' | 'any';
  * for portable pool targeting. Users still cannot *set* `kici:` labels on agents.
  */
 export type RunsOn = string | RegExp | (string | RegExp)[] | RunsOnSelector;
-/** Job definition returned by job() factory */
-export interface Job {
+/**
+ * Job definition returned by job() factory.
+ *
+ * `TOutputs` is the job's inferred output shape, threaded onto `result` so
+ * cross-job reads (`jobRef.result.<step>.<field>`) are type-checked. It is
+ * inferred by {@link InferJobOutputsFromSteps} for a `steps:` job (nested by
+ * step name) or from the run function's return type for a `run:` shorthand job
+ * (flat), with an explicit override available (`job<T>(...)`). Defaults to the
+ * loose `Record<string, unknown>` so a bare `Job` and untyped code keep
+ * compiling.
+ *
+ * `TName` is the job's name carried as a literal (from the `job('name', …)`
+ * argument), which lets a typed `needs: [jobRef]` key the reference under its
+ * name in `ctx.needs`. Name-less jobs (auto-generated id) keep the loose
+ * `string` default.
+ */
+export interface Job<TOutputs = Record<string, unknown>, TName extends string = string> {
     readonly _tag: 'Job';
-    readonly name: string;
+    readonly name: TName;
     /** Single-agent targeting. Mutually exclusive with `runsOnAll`. */
     readonly runsOn?: RunsOn;
     /**
@@ -471,18 +587,20 @@ 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>);
+    /** Per-job sandbox escape hatch (container jobs only); granted within the operator allow-list. */
+    readonly sandbox?: SandboxOptions;
+    /** 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;
@@ -530,9 +648,18 @@ export interface Job {
      * Type-safe proxy for accessing this job's outputs.
      * For multi-step jobs: jobRef.result.stepName.field
      * For single-step (run shorthand) jobs: jobRef.result.field
-     * At runtime, resolves against the shared job outputs map populated by the workflow runner.
-     */
-    readonly result: OutputProxy<any>;
+     * At runtime, resolves against the shared job outputs map populated by the
+     * workflow runner.
+     *
+     * The `[TOutputs] extends [void]` guard mirrors `Step.result` so a void
+     * run-shorthand job resolves `result` to `never` — which keeps `Job<void>`
+     * assignable to `JobOrFactory` (`never` is assignable to
+     * `OutputProxy<Record<string, unknown>>`). The tuple wrap is deliberate and
+     * non-distributive: it must not distribute over a union output map. Do not
+     * "align" this with `Step.result`'s naked form — that would reintroduce
+     * distribution over unions.
+     */
+    readonly result: [TOutputs] extends [void] ? never : OutputProxy<TOutputs>;
 }
 /** Options for job() factory */
 export interface JobOptions {
@@ -619,18 +746,24 @@ 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>);
     /**
-     * Deployment environments for this job, in merge order (later entries override
-     * earlier on name collisions). Mutually exclusive with `environment`. Each entry
+     * Per-job sandbox escape hatch (container jobs only). Request extra Linux
+     * capabilities / host networking; granted only within the operator's
+     * `org_settings` allow-list, else the run fails loudly at dispatch.
+     */
+    sandbox?: SandboxOptions;
+    /** 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>);
+    /**
+     * 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 +812,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 +825,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 +854,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 +908,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/validation/dag.js

@@ -51,12 +51,20 @@ function validateDag(nodes) {
 		}
 	}
 	if (sortedOrder.length !== nodes.length) {
-		const cycleNodes = [];
-		for (const [id, degree] of inDegree) if (degree > 0) cycleNodes.push(id);
+		const residual = /* @__PURE__ */ new Set();
+		for (const [id, degree] of inDegree) if (degree > 0) residual.add(id);
+		let changed = true;
+		while (changed) {
+			changed = false;
+			for (const id of residual) if (!(adjacencyList.get(id) ?? []).some((target) => residual.has(target))) {
+				residual.delete(id);
+				changed = true;
+			}
+		}
 		return {
 			valid: false,
 			error: "cycle",
-			nodesInCycle: cycleNodes
+			nodesInCycle: [...residual]
 		};
 	}
 	return {

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.26",
+  "version": "0.2.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",
@@ -43,21 +43,26 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js",
+      "default": "./dist/testing/index.js"
     }
   },
   "dependencies": {
     "micromatch": "^4.0.8",
     "zod": "^4.4.3",
     "zx": "^8.8.5",
-    "@kici-dev/core": "0.1.26",
-    "@kici-dev/engine": "0.1.26"
+    "@kici-dev/core": "0.2.0",
+    "@kici-dev/engine": "0.2.0"
   },
   "devDependencies": {
     "@types/micromatch": "^4.0.10"
   },
   "scripts": {
-    "build": "node ../../scripts/build-ts.mjs && tsc --emitDeclarationOnly",
-    "typecheck": "tsc --noEmit",
+    "build": "node ../../scripts/build-ts.mjs && tsgo --emitDeclarationOnly",
+    "typecheck": "tsgo --noEmit",
     "test": "vitest run",
     "test:watch": "vitest"
   }