@olivervea/pipelines 2.0.0-beta.2 → 2.0.0-beta.6

package/src/builder/pipeline.ts

@@ -8,6 +8,7 @@ import type { IsUnion, OrError, Simplify } from "../core/types.ts";
 import type { Optional } from "../core/models.ts";
 import type { FailureContext } from "../library/models.ts";
 import type { MapperResult, Ref } from "./refs.ts";
+import { isConfigRef, narrowConfigRef, unionAt, type ConfigNode, type ConfigRef, type DiscriminatorOf, type VariantOf } from "../core/config.ts";
 
 // ─── Availability (builder state, type level) ────────────────────────────────────────────────
 
@@ -96,6 +97,29 @@ type OutputsOf<E extends readonly unknown[], Maybe extends boolean> = {
 };
 type MakeMaybe<X extends AvailMap> = { [K in keyof X]: Slot<X[K]["model"], X[K]["value"], true> };
 
+// ─── select (branching on config) ────────────────────────────────────────────────────────────
+
+type KeysOfUnion<T> = T extends unknown ? keyof T : never;
+type SlotIn<B, K extends PropertyKey> = B extends { [P in K]: infer X extends Slot } ? X : never;
+/** A case function: the pipeline so far, and the select's reference narrowed to the case's variant. */
+export type SelectCase<In extends AnyModel, A extends AvailMap, R> = (p: Pipeline<In, A>, ref: R) => Pipeline<In, AvailMap>;
+export type SelectCases<In extends AnyModel, A extends AvailMap, U, D extends string> = {
+  readonly [V in Extract<U[D & keyof U], string>]: SelectCase<In, A, ConfigNode<VariantOf<U, D, V>>>;
+};
+type CaseAvail<C> = { [K in keyof C]: C[K] extends (...args: never[]) => Pipeline<AnyModel, infer B> ? B : never }[keyof C];
+/**
+ * After a select: a step every case has is as available as in its cases (one case always runs);
+ * a step only some cases have is maybe-available.
+ */
+export type AfterSelect<A extends AvailMap, B> = Simplify<
+  A &
+    { [K in Exclude<keyof B, keyof A>]: Slot<SlotIn<B, K>["model"], SlotIn<B, K>["value"], SlotIn<B, K>["maybe"]> } &
+    { [K in Exclude<KeysOfUnion<B>, keyof B | keyof A>]: Slot<SlotIn<B, K>["model"], SlotIn<B, K>["value"], true> }
+>;
+type SelectOnError<U> = [DiscriminatorOf<U>] extends [never]
+  ? "❌ select needs a reference to a discriminated union in config (z.discriminatedUnion)"
+  : IsUnion<DiscriminatorOf<U>> extends true ? "❌ the union has more than one literal field; select can't tell which is the discriminator" : never;
+
 // ─── Conditions / triggers ───────────────────────────────────────────────────────────────────
 
 type IsLiteralLike<T> = [T] extends [string | number | boolean]
@@ -134,7 +158,8 @@ export interface StageStepNode {
 }
 export type StageNode =
   | { readonly kind: "stage"; readonly steps: readonly StageStepNode[] }
-  | { readonly kind: "when"; readonly cond: Readonly<Record<string, unknown>>; readonly nodes: readonly StageNode[] };
+  | { readonly kind: "when"; readonly cond: Readonly<Record<string, unknown>>; readonly nodes: readonly StageNode[] }
+  | { readonly kind: "select"; readonly on: ConfigRef; readonly cases: Readonly<Record<string, readonly StageNode[]>> };
 
 export type TriggerNode =
   | { readonly kind: "push"; readonly name: string; readonly map: (event: unknown) => unknown }
@@ -178,6 +203,11 @@ export function isPipeline(p: unknown): boolean {
 
 // ─── Pipeline builder ────────────────────────────────────────────────────────────────────────
 
+// Builder calls record into shared data and hand back a fresh handle; a handle that was already
+// extended no longer matches its type (it would claim fewer stages than the data has), so reuse is a problem.
+const extended = new WeakSet<object>();
+const ReusedProblem = "a pipeline value was extended twice: chain the calls (pipeline({...}).stage(a).stage(b)) instead of reusing an earlier value";
+
 export interface PipelineDef<In extends AnyModel> {
   /** Display name. */
   name: string;
@@ -203,10 +233,19 @@ export class Pipeline<In extends AnyModel, A extends AvailMap> {
     };
   }
 
+  private next(): never {
+    const data = this[PIPELINE];
+    if (extended.has(this) && !data.problems.includes(ReusedProblem)) data.problems.push(ReusedProblem);
+    extended.add(this);
+    const handle = Object.create(Object.getPrototypeOf(this)) as Pipeline<In, A>;
+    (handle as { [PIPELINE]: PipelineData })[PIPELINE] = data;
+    return handle as never;
+  }
+
   /** Map a GitHub push to the pipeline input (`z.input` view). Runs as code in a `map-trigger` Job per event. */
   onPush<R extends InferInput<In>>(map: (event: PushEvent) => Exact<R, InferInput<In>>): this {
     this[PIPELINE].triggers.push({ kind: "push", name: "push", map: map as (event: unknown) => unknown });
-    return this;
+    return this.next();
   }
 
   /**
@@ -235,7 +274,7 @@ export class Pipeline<In extends AnyModel, A extends AvailMap> {
       intervalSeconds: cfg.intervalSeconds,
       map: map as (value: string) => unknown,
     });
-    return this;
+    return this.next();
   }
 
   /**
@@ -247,7 +286,7 @@ export class Pipeline<In extends AnyModel, A extends AvailMap> {
     map: (event: WebhookEvent) => Exact<R, InferInput<In>> | null,
   ): this {
     this[PIPELINE].triggers.push({ kind: "webhook", name: cfg.name, verify: cfg.verify, map: map as (event: WebhookEvent) => unknown });
-    return this;
+    return this.next();
   }
 
   /**
@@ -272,7 +311,7 @@ export class Pipeline<In extends AnyModel, A extends AvailMap> {
     });
     if (entries.length === 0) data.problems.push("empty stage");
     data.nodes.push({ kind: "stage", steps });
-    return this;
+    return this.next();
   }
 
   /** Declarative condition on literal-like pipeline-input fields. Outputs produced inside become maybe-available after. */
@@ -280,9 +319,38 @@ export class Pipeline<In extends AnyModel, A extends AvailMap> {
     const data = this[PIPELINE];
     const inner = new Pipeline<In, A>({ name: data.name, input: data.input as In }, data);
     const returned = block(inner);
-    if (returned !== (inner as unknown)) data.problems.push("a when block must return the pipeline it was given (p => p.stage(...))");
+    if (!isPipeline(returned) || pipelineData(returned) !== inner[PIPELINE])
+      data.problems.push("a when block must return the pipeline it was given (p => p.stage(...))");
     data.nodes.push({ kind: "when", cond: { ...(cond as object) }, nodes: inner[PIPELINE].nodes });
-    return this as never;
+    return this.next();
+  }
+
+  /**
+   * Branch on config: `on` references a discriminated union in a config entry, and each case gets the
+   * pipeline and `on` narrowed to its variant. Exactly one case runs, chosen by the run's config
+   * snapshot (not by run input; that is `when`). The same step name may appear in several cases.
+   */
+  select<U, const C extends SelectCases<In, A, U, DiscriminatorOf<U>>>(
+    on: ConfigRef<U> & ([SelectOnError<U>] extends [never] ? unknown : SelectOnError<U>),
+    cases: C & { readonly [K in Exclude<keyof C, keyof SelectCases<In, A, U, DiscriminatorOf<U>>>]: `❌ '${K & string}' is not a case of this select` },
+  ): Pipeline<In, AfterSelect<A, CaseAvail<C>>> {
+    const data = this[PIPELINE];
+    const recorded: Record<string, StageNode[]> = {};
+    const union = isConfigRef(on) ? unionAt(on) : undefined;
+    if (!union) data.problems.push("select: the first argument must reference a z.discriminatedUnion in a config entry");
+    for (const [value, fn] of Object.entries(cases as Record<string, unknown>)) {
+      if (typeof fn !== "function") {
+        data.problems.push(`select: case '${value}' is not a function`);
+        continue;
+      }
+      const inner = new Pipeline<In, A>({ name: data.name, input: data.input as In }, data);
+      const returned = (fn as (p: unknown, ref: unknown) => unknown)(inner, union ? narrowConfigRef(on, union.discriminator, value) : on);
+      if (!isPipeline(returned) || pipelineData(returned) !== inner[PIPELINE])
+        data.problems.push(`select: case '${value}' must return the pipeline it was given ((p, ref) => p.stage(...))`);
+      recorded[value] = inner[PIPELINE].nodes;
+    }
+    data.nodes.push({ kind: "select", on, cases: recorded });
+    return this.next();
   }
 
   /** Run `handler` (a step whose inputs are all FailureContext) when one of `steps` (default: any) fails. Untracked, best-effort. */
@@ -292,10 +360,10 @@ export class Pipeline<In extends AnyModel, A extends AvailMap> {
         ? unknown
         : "❌ a failure handler's inputs must all be FailureContext"),
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    opts?: { steps?: readonly Step<StepNames<A>, any, any, any>[] },
+    opts?: { steps?: readonly Step<StepNames<A>, any, any, any, any>[] },
   ): this {
     this[PIPELINE].failureHandlers.push({ step: handler as AnyStep, steps: opts?.steps ? [...(opts.steps as readonly AnyStep[])] : null });
-    return this;
+    return this.next();
   }
 }
 

package/src/core/config-refs.ts

@@ -0,0 +1,77 @@
+// Config references inside library-step definitions: collected (the step receives their entries),
+// recorded in the manifest as `{"$config": "<entry>.<path>"}`, and resolved from ctx.config at run time.
+import { configRefPath, configRefTarget, isConfigRef, type AnyConfigEntry, type ConfigRef } from "./config.ts";
+
+/** `T` with every config reference replaced by the type of its value. */
+export type Resolved<T> = T extends ConfigRef<infer U>
+  ? U
+  : T extends readonly (infer E)[]
+    ? Resolved<E>[]
+    : T extends (...args: never[]) => unknown
+      ? T
+      : T extends object
+        ? { [K in keyof T]: Resolved<T[K]> }
+        : T;
+
+/** Manifest key of a recorded config reference. */
+export const CONFIG_REF_KEY = "$config";
+/** Beside it on a reference narrowed by a `select` case: the case's condition, `<ref>.<discriminator>=<value>`. */
+export const CONFIG_CASE_KEY = "$case";
+
+function isPlain(v: unknown): v is Record<string, unknown> {
+  if (typeof v !== "object" || v === null || Array.isArray(v)) return false;
+  const proto = Object.getPrototypeOf(v);
+  return proto === Object.prototype || proto === null;
+}
+
+/** Every config entry referenced anywhere in `v` (plain objects and arrays only), by name. */
+export function configRefsIn(v: unknown, into = new Map<string, AnyConfigEntry>()): AnyConfigEntry[] {
+  if (isConfigRef(v)) {
+    const { entry } = configRefTarget(v);
+    if (!into.has(entry.name)) into.set(entry.name, entry);
+  } else if (Array.isArray(v)) for (const x of v) configRefsIn(x, into);
+  else if (isPlain(v)) for (const x of Object.values(v)) configRefsIn(x, into);
+  return [...into.values()];
+}
+
+/** `v` as manifest JSON: references become `{"$config": "target.beta.host"}`; literal keys starting with `$` are reserved. */
+export function recordConfigRefs(v: unknown): unknown {
+  if (isConfigRef(v)) {
+    const { path, case: kase } = configRefTarget(v);
+    for (const seg of path) if (seg === "" || seg.includes(".")) throw new Error(`config reference '${configRefPath(v)}': field names must not be empty or contain '.'`);
+    return { [CONFIG_REF_KEY]: configRefPath(v), ...(kase ? { [CONFIG_CASE_KEY]: kase } : {}) };
+  }
+  if (Array.isArray(v)) return v.map(recordConfigRefs);
+  if (isPlain(v)) {
+    const out: Record<string, unknown> = {};
+    for (const [k, x] of Object.entries(v)) {
+      if (k.startsWith("$")) throw new Error(`key '${k}': keys starting with '$' are reserved`);
+      out[k] = recordConfigRefs(x);
+    }
+    return out;
+  }
+  return v;
+}
+
+/** `v` with every reference replaced by its value in `config` (the step's parsed config entries). */
+export function resolveConfigRefs<T>(v: T, config: Readonly<Record<string, unknown>>): Resolved<T> {
+  if (isConfigRef(v)) {
+    const { entry, path } = configRefTarget(v);
+    if (!Object.hasOwn(config, entry.name)) throw new Error(`config entry '${entry.name}' was not delivered to the step`);
+    let cur: unknown = config[entry.name];
+    for (const seg of path) cur = cur !== null && typeof cur === "object" ? (cur as Record<string, unknown>)[seg] : undefined;
+    return cur as Resolved<T>;
+  }
+  if (Array.isArray(v)) return v.map((x) => resolveConfigRefs(x, config)) as Resolved<T>;
+  if (isPlain(v)) {
+    const out: Record<string, unknown> = {};
+    for (const [k, x] of Object.entries(v)) out[k] = resolveConfigRefs(x, config);
+    return out as Resolved<T>;
+  }
+  return v as Resolved<T>;
+}
+
+/** Literal `v` (no reference inside), so define-time checks can run on it. */
+export function isLiteral(v: unknown): boolean {
+  return configRefsIn(v).length === 0;
+}

package/src/core/config.ts

@@ -0,0 +1,147 @@
+import { z } from "zod";
+import type { Secret } from "./secrets.ts";
+
+const CONFIG_REF = Symbol.for("olve.configRef");
+declare const VALUE: unique symbol;
+
+interface RefTarget {
+  readonly entry: AnyConfigEntry;
+  readonly path: readonly string[];
+  /** Set on a reference narrowed by a `select` case: `<ref>.<discriminator>=<value>`. */
+  readonly case?: string;
+}
+
+/**
+ * A typed reference to a config value (`TARGET.beta.host`), accepted by library steps in place of a
+ * literal. It is recorded in the manifest as `{"$config": "target.beta.host"}` and resolved from the
+ * run's config when the step runs; the step receives the entry automatically.
+ */
+export interface ConfigRef<T = unknown> {
+  readonly [CONFIG_REF]: RefTarget;
+  readonly [VALUE]?: T;
+}
+
+/** A literal or a reference to a config value of the same type. */
+export type Configurable<T> = T | ConfigRef<T>;
+
+type Fields<T> = T extends readonly unknown[] ? never : T extends object ? T : never;
+type Children<T> = [Fields<NonNullable<T>>] extends [never]
+  ? {}
+  : { readonly [K in keyof Fields<NonNullable<T>> & string]-?: ConfigNode<Fields<NonNullable<T>>[K] | (undefined extends T ? undefined : never)> };
+/** A reference to a config value, and to each of its fields. */
+export type ConfigNode<T> = ConfigRef<T> & Children<T>;
+
+/** Fields of an entry that are its own properties; reach config fields with these names through `$`. */
+export type ReservedConfigField = "kind" | "name" | "description" | "schema" | "$";
+
+/** A named, typed value stored on the instance (one YAML document per pipeline), declared by the steps that use it. */
+export interface ConfigEntryBase<N extends string = string, S extends z.ZodType = z.ZodType> {
+  readonly kind: "config";
+  readonly name: N;
+  readonly description: string;
+  readonly schema: S;
+}
+export type ConfigEntry<N extends string = string, S extends z.ZodType = z.ZodType> = ConfigEntryBase<N, S> &
+  ConfigRef<z.output<S>> &
+  Omit<Children<z.output<S>>, ReservedConfigField> & { readonly $: ConfigNode<z.output<S>> };
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyConfigEntry = ConfigEntryBase<string, any>;
+
+/** Config names are YAML keys: camelCase identifiers. */
+export const CONFIG_NAME = /^[a-z][a-zA-Z0-9]*$/;
+
+const NOT_REFS = new Set<PropertyKey>(["then", "toJSON", "constructor", "valueOf", "toString", "asymmetricMatch", "$$typeof", "nodeType"]);
+
+function node(entry: AnyConfigEntry, path: readonly string[], kase?: string): unknown {
+  const target = Object.freeze({ [CONFIG_REF]: Object.freeze({ entry, path, ...(kase ? { case: kase } : {}) }) });
+  return new Proxy(target, {
+    get(t, prop) {
+      if (prop === CONFIG_REF) return t[CONFIG_REF];
+      if (typeof prop === "symbol" || NOT_REFS.has(prop)) return undefined;
+      return node(entry, [...path, prop], kase);
+    },
+  });
+}
+
+/** `ref` narrowed to the union member whose `discriminator` is `value` (a `select` case). */
+export function narrowConfigRef(ref: ConfigRef, discriminator: string, value: string): unknown {
+  const { entry, path } = ref[CONFIG_REF];
+  return node(entry, path, `${[entry.name, ...path].join(".")}.${discriminator}=${value}`);
+}
+
+export function config<const N extends string, S extends z.ZodType>(name: N, description: string, schema: S): ConfigEntry<N, S> {
+  const ref = { entry: undefined as unknown as AnyConfigEntry, path: [] as readonly string[] };
+  const target = Object.freeze({ kind: "config" as const, name, description, schema, [CONFIG_REF]: ref });
+  const entry: unknown = new Proxy(target, {
+    get(t, prop) {
+      if (prop in t) return t[prop as keyof typeof t];
+      if (typeof prop === "symbol" || NOT_REFS.has(prop)) return undefined;
+      if (prop === "$") return node(entry as AnyConfigEntry, []);
+      return node(entry as AnyConfigEntry, [prop]);
+    },
+  });
+  ref.entry = entry as AnyConfigEntry;
+  Object.freeze(ref);
+  return entry as ConfigEntry<N, S>;
+}
+
+export function isConfigEntry(v: unknown): v is AnyConfigEntry {
+  return typeof v === "object" && v !== null && (v as { kind?: unknown }).kind === "config" && (v as { schema?: unknown }).schema instanceof z.ZodType;
+}
+
+export function isConfigRef(v: unknown): v is ConfigRef {
+  return typeof v === "object" && v !== null && (v as Record<symbol, unknown>)[CONFIG_REF] !== undefined;
+}
+
+/** The entry and field path a reference points at, and the `select` case it was narrowed by. */
+export function configRefTarget(ref: ConfigRef): { entry: AnyConfigEntry; path: readonly string[]; case?: string } {
+  return ref[CONFIG_REF];
+}
+
+/** `target.beta.host` */
+export function configRefPath(ref: ConfigRef): string {
+  const { entry, path } = configRefTarget(ref);
+  return [entry.name, ...path].join(".");
+}
+
+export const SECRET_REF_KIND = "secretRef";
+
+/** A config field that names a secret: `{ secret: NAME }` in YAML. The value never enters the config. */
+export function secretRef<const N extends string>(s: Secret<N>) {
+  return z.strictObject({ secret: z.literal(s.name) }).meta({ "x-olve-kind": SECRET_REF_KIND });
+}
+
+/** `ctx.config`: exactly the entries a step declares, after parsing (defaults applied). */
+export type ConfigValues<C extends AnyConfigEntry> = { readonly [E in C as E["name"]]: z.output<E["schema"]> };
+
+// ─── select: branching on a config union ────────────────────────────────────────────────────
+
+type IsLiteralString<T> = [T] extends [string] ? (string extends T ? false : true) : false;
+/** The fields of union `U` whose type is a string literal in every member: its discriminator(s). */
+export type DiscriminatorOf<U> = { [K in keyof U & string]-?: IsLiteralString<U[K]> extends true ? K : never }[keyof U & string];
+/** The member of `U` whose discriminator `D` is `V`. */
+export type VariantOf<U, D extends string, V> = Extract<U, { readonly [K in D]: V }>;
+
+function unwrap(schema: z.ZodType): z.ZodType {
+  let s = schema as unknown as { _zod: { def: { innerType?: z.ZodType } } };
+  for (let i = 0; i < 16 && s._zod.def.innerType; i++) s = s._zod.def.innerType as never;
+  return s as unknown as z.ZodType;
+}
+
+/**
+ * The discriminated union a reference points at: its discriminator and, per value, nothing else.
+ * Undefined when the referenced value is not a `z.discriminatedUnion`.
+ */
+export function unionAt(ref: ConfigRef): { discriminator: string; values: string[] } | undefined {
+  const { entry, path } = configRefTarget(ref);
+  let s = unwrap(entry.schema as z.ZodType) as unknown as { _zod: { def: Record<string, unknown> } };
+  for (const seg of path) {
+    const shape = s._zod.def.shape as Record<string, z.ZodType> | undefined;
+    if (!shape || !(seg in shape)) return undefined;
+    s = unwrap(shape[seg]!) as never;
+  }
+  const def = s._zod.def as { discriminator?: string; options?: { _zod: { propValues?: Record<string, Set<unknown>> } }[] };
+  if (typeof def.discriminator !== "string" || !Array.isArray(def.options)) return undefined;
+  const values = def.options.flatMap((o) => [...(o._zod.propValues?.[def.discriminator!] ?? [])]).filter((v): v is string => typeof v === "string");
+  return { discriminator: def.discriminator, values };
+}

package/src/core/handlers.ts

@@ -1,6 +1,6 @@
 import { IMPLEMENTATION, SKIPPED, type SkippedBrand } from "./brands.ts";
 import type { Ctx } from "../ctx/types.ts";
-import type { AnyStep, LibraryStep, OutputValue, SecretsOf, StepInput } from "./steps.ts";
+import type { AnyStep, ConfigOf, LibraryStep, OutputValue, SecretsOf, StepInput } from "./steps.ts";
 import type { Awaitable } from "./types.ts";
 
 /** Returned by `ctx.skip(reason)`: the step produced no output on purpose. */
@@ -16,7 +16,7 @@ export function isSkipped(v: unknown): v is Skipped {
 }
 
 export type HandlerResult<S extends AnyStep> = OutputValue<S> | Skipped;
-export type Handler<S extends AnyStep> = (input: StepInput<S["input"]>, ctx: Ctx<SecretsOf<S>>) => Awaitable<HandlerResult<S>>;
+export type Handler<S extends AnyStep> = (input: StepInput<S["input"]>, ctx: Ctx<SecretsOf<S>, ConfigOf<S>>) => Awaitable<HandlerResult<S>>;
 
 export interface Implementation<S extends AnyStep = AnyStep> {
   readonly step: S;
@@ -34,7 +34,7 @@ type NoExtraFields<R, T> = R extends Skipped | void
  */
 export function implement<S extends AnyStep, R extends HandlerResult<S>>(
   step: S & (S extends LibraryStep ? "❌ library steps already carry their implementation" : unknown),
-  handler: (input: StepInput<S["input"]>, ctx: Ctx<SecretsOf<S>>) => Awaitable<R & NoExtraFields<R, OutputValue<S>>>,
+  handler: (input: StepInput<S["input"]>, ctx: Ctx<SecretsOf<S>, ConfigOf<S>>) => Awaitable<R & NoExtraFields<R, OutputValue<S>>>,
 ): Implementation<S> {
   return Object.freeze({ [IMPLEMENTATION]: true, step, handler: handler as unknown as Handler<S> }) as Implementation<S>;
 }

package/src/core/steps.ts

@@ -1,6 +1,8 @@
 import type { z } from "zod";
 import { STEP, type StepBrand } from "./brands.ts";
 import type { AnyModel, Infer, Optional } from "./models.ts";
+import type { AnyConfigEntry } from "./config.ts";
+import { configRefsIn } from "./config-refs.ts";
 import type { Secret } from "./secrets.ts";
 import type { Simplify } from "./types.ts";
 
@@ -17,13 +19,14 @@ export type InferEntry<E> =
 export type StepInput<I> = Simplify<{ -readonly [K in keyof I]: InferEntry<I[K]> }>;
 
 /** `custom` steps have a handler file; the others are library steps implemented by the SDK. */
-export type StepKind = "custom" | "script" | "gitHubSource" | "imageBuild" | "helmDeployOverSsh";
+export type StepKind = "custom" | "script" | "gitHubSource" | "imageBuild" | "helmDeployOverSsh" | "helmDeployInCluster" | "composeDeploy";
 
 export interface Step<
   N extends string = string,
   I extends InputSpec = InputSpec,
   O extends AnyModel | null = AnyModel | null,
   Sec extends string = string,
+  Cfg extends AnyConfigEntry = never,
 > {
   readonly [StepBrand]: true;
   readonly kind: StepKind;
@@ -33,8 +36,12 @@ export interface Step<
   readonly input: I;
   readonly output: O;
   readonly secrets: readonly Secret<Sec>[];
+  /** Config entries the step receives as `ctx.config`. */
+  readonly config: readonly Cfg[];
   readonly timeoutSeconds?: number;
   readonly retries?: number;
+  /** The step pod gets the instance's step ServiceAccount token (`Kubernetes:StepServiceAccount`). */
+  readonly clusterAccess?: boolean;
   /** Library steps carry their own implementation and config. */
   readonly builtin?: LibraryImplementation;
 }
@@ -47,10 +54,12 @@ export interface LibraryImplementation {
 }
 export type LibraryStep = { readonly builtin: LibraryImplementation };
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type AnyStep = Step<string, any, AnyModel | null, any>;
+export type AnyStep = Step<string, any, AnyModel | null, any, any>;
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type SecretsOf<S> = S extends Step<any, any, any, infer Sec> ? Sec : never;
+export type SecretsOf<S> = S extends Step<any, any, any, infer Sec, any> ? Sec : never;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ConfigOf<S> = S extends Step<any, any, any, any, infer C> ? C : never;
 export type OutputValue<S extends AnyStep> = S["output"] extends AnyModel ? Infer<S["output"]> : void;
 
 /** Step names must be literals (identity, duplicate detection and mapper keys depend on it). */
@@ -61,7 +70,7 @@ export const STEP_NAME = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
 /** Names that cannot be steps: `input` is the pipeline input's root in mappings. */
 export const RESERVED_STEP_NAMES: readonly string[] = ["input"];
 
-export interface StepDef<N extends string, I extends InputSpec, O extends AnyModel | null, Sec extends readonly Secret[]> {
+export interface StepDef<N extends string, I extends InputSpec, O extends AnyModel | null, Sec extends readonly Secret[], Cfg extends readonly AnyConfigEntry[] = []> {
   name: LiteralName<N>;
   /** What the step does, shown in the UI. Required; may be empty. */
   description: string;
@@ -70,12 +79,23 @@ export interface StepDef<N extends string, I extends InputSpec, O extends AnyMod
   input?: I;
   output?: O;
   secrets?: Sec;
+  /** Config entries delivered as `ctx.config` (typed to exactly these). */
+  config?: Cfg;
   timeoutSeconds?: number;
   /** Automatic retries (an idempotency claim). Default 0. */
   retries?: number;
+  /**
+   * Ask for a Kubernetes API token in the step pod: the instance's step ServiceAccount
+   * (`Kubernetes:StepServiceAccount`), if it grants one. Default false (no token).
+   */
+  clusterAccess?: boolean;
 }
 
-export function makeStep(kind: StepKind, def: Record<string, unknown>, builtin?: LibraryImplementation): AnyStep {
+/** `configFrom`: a library step's definition; the config entries it references are added to the step's `config`. */
+export function makeStep(kind: StepKind, def: Record<string, unknown>, builtin?: LibraryImplementation, configFrom?: unknown): AnyStep {
+  const config = new Map<string, AnyConfigEntry>();
+  for (const e of (def.config as readonly AnyConfigEntry[] | undefined) ?? []) if (!config.has(e.name)) config.set(e.name, e);
+  configRefsIn(configFrom, config);
   const s = {
     [STEP]: true,
     kind,
@@ -85,8 +105,10 @@ export function makeStep(kind: StepKind, def: Record<string, unknown>, builtin?:
     input: Object.freeze({ ...((def.input as object | undefined) ?? {}) }),
     output: def.output ?? null,
     secrets: Object.freeze([...((def.secrets as readonly Secret[] | undefined) ?? [])]),
+    config: Object.freeze([...config.values()]),
     ...(def.timeoutSeconds !== undefined ? { timeoutSeconds: def.timeoutSeconds } : {}),
     ...(def.retries !== undefined ? { retries: def.retries } : {}),
+    ...(def.clusterAccess === true ? { clusterAccess: true } : {}),
     ...(builtin ? { builtin } : {}),
   };
   return Object.freeze(s) as unknown as AnyStep;
@@ -102,6 +124,7 @@ export function step<
   const I extends InputSpec = {},
   O extends AnyModel | null = null,
   const Sec extends readonly Secret[] = [],
->(def: StepDef<N, I, O, Sec>): Step<N, I, O, Sec[number]["name"]> {
+  const Cfg extends readonly AnyConfigEntry[] = [],
+>(def: StepDef<N, I, O, Sec, Cfg>): Step<N, I, O, Sec[number]["name"], Cfg[number]> {
   return makeStep("custom", def as never) as never;
 }

package/src/ctx/index.ts

@@ -12,6 +12,8 @@ export interface CtxOptions {
   secrets: readonly Secret[];
   /** Secret values that take precedence over the environment (tests). */
   secretValues?: Readonly<Record<string, string>>;
+  /** Parsed config entries of the step (`ctx.config`). */
+  config?: Readonly<Record<string, unknown>>;
   paths: { root: string; workFiles: string; tmp: string };
   signal: AbortSignal;
   /** Where log lines go (default stderr). */
@@ -102,6 +104,7 @@ export function createCtx(o: CtxOptions): Ctx {
   const filesDeps = { run: o.run, workFiles: o.paths.workFiles, tmpDir: o.paths.tmp, root: o.paths.root, signal: o.signal, log };
   return {
     secrets: createSecrets(o.secrets, o.secretValues) as Ctx["secrets"],
+    config: Object.freeze({ ...o.config }) as Ctx["config"],
     sh,
     exec,
     readText: async (p) => readFileSync(resolve(p), "utf8"),

package/src/ctx/sh.ts

@@ -85,7 +85,8 @@ export function createSh(deps: ShDeps): { sh: Sh; exec: (argv: readonly string[]
     const scriptPath = typeof cmd === "object" ? cmd.script : isEmbeddedScript(cmd) ? cmd : undefined;
     if (scriptPath === undefined) {
       const shell = detectShell(deps.shellCandidates);
-      return { argv: [shell, "-c", cmd as string], what: `command \`${truncate(cmd as string)}\`` };
+      // `sh -c cmd sh a b`: the args are $1, $2… of the command.
+      return { argv: [shell, "-c", cmd as string, "sh", ...args], what: `command \`${truncate(cmd as string)}\`` };
     }
     const file = materialize(scriptPath);
     const first = readFileSync(file, "utf8").split("\n", 1)[0] ?? "";

package/src/ctx/types.ts

@@ -1,5 +1,6 @@
 import type { Skipped } from "../core/handlers.ts";
 import type { FileRef } from "../core/models.ts";
+import type { AnyConfigEntry, ConfigValues } from "../core/config.ts";
 import type { DeclaredSecrets } from "../core/secrets.ts";
 
 /** Facts about the current execution, from the service (see README "Environment"). */
@@ -79,9 +80,11 @@ export interface OutputFileOptions {
   name?: string;
 }
 
-export interface Ctx<Sec extends string = string> {
+export interface Ctx<Sec extends string = string, Cfg extends AnyConfigEntry = never> {
   /** Exactly the secrets the step declares, read from the environment. */
   readonly secrets: DeclaredSecrets<Sec>;
+  /** Exactly the config entries the step declares, from the run's config snapshot (defaults applied). */
+  readonly config: ConfigValues<Cfg>;
   readonly sh: Sh;
   /** Run a binary directly, without a shell (works in shell-less images). Rejects on non-zero exit. */
   exec(argv: readonly string[], opts?: ExecOptions): Promise<void>;