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

package/src/describe/describe.ts

@@ -1,6 +1,9 @@
 // `describe`: evaluates the contracts (models + pipeline, never handlers) into the manifest and runs
 // every describe-time check. All problems are collected and reported together.
 import { z } from "zod";
+import { CONFIG_NAME, isConfigEntry, SECRET_REF_KIND } from "../core/config.ts";
+import { CONFIG_CASE_KEY, CONFIG_REF_KEY } from "../core/config-refs.ts";
+import { configRefPath, configRefTarget, isConfigRef, unionAt } from "../core/config.ts";
 import { isModel, isOptional, MODEL_NAME, type AnyModel } from "../core/models.ts";
 import { SECRET_NAME, type Secret } from "../core/secrets.ts";
 import { RESERVED_STEP_NAMES, STEP_NAME, isStep, type AnyStep } from "../core/steps.ts";
@@ -20,7 +23,7 @@ export class DescribeError extends Error {
 }
 
 export interface DescribeOptions {
-  /** Step names that have a handler file (`handlers/<name>.ts`). */
+  /** Step names that have a handler (a `handlers/*.ts` default-exporting `implement(step, …)`). */
   handlerNames: Iterable<string>;
   /** Step name → handler hash (from the build; includes the harness identity). */
   handlerHashes: Readonly<Record<string, string>>;
@@ -127,14 +130,46 @@ export function describePipeline(pipeline: unknown, opts: DescribeOptions): Mani
     return s.name;
   };
 
+  // ── config entries ──
+  const configs = new Map<string, { description: string; required: boolean; schema: JsonSchema; key: string; secretRefs: string[] }>();
+  const useConfig = (e: unknown, at: string): string | undefined => {
+    if (!isConfigEntry(e)) return void problems.push(`${at}: config entries must be config("name", "description", schema)`);
+    if (!CONFIG_NAME.test(e.name)) problems.push(`${at}: config name '${e.name}' must match ${CONFIG_NAME}`);
+    let schema: JsonSchema;
+    try {
+      schema = z.toJSONSchema(e.schema, { io: "input", target: "draft-2020-12" }) as JsonSchema;
+      delete schema.$schema;
+      schema = canonicalize(schema) as JsonSchema;
+    } catch (err) {
+      problems.push(`${at}: config '${e.name}' is not representable as JSON Schema (${(err as Error).message})`);
+      return e.name;
+    }
+    const key = JSON.stringify([e.description, schema]);
+    const prev = configs.get(e.name);
+    if (!prev) configs.set(e.name, { description: e.description, required: !e.schema.safeParse(undefined).success, schema, key, secretRefs: secretRefsOf(schema) });
+    else if (prev.key !== key) problems.push(`two different config entries are named '${e.name}' (one description and schema per config name)`);
+    return e.name;
+  };
+
   // ── step identity ──
   const steps = new Map<string, AnyStep>();
-  const registerStep = (s: AnyStep, where: string) => {
+  const placements = new Map<string, { step: AnyStep; cases: readonly CaseOf[] }[]>();
+  // Two places are mutually exclusive when they sit in different cases of the same select.
+  const exclusive = (a: readonly CaseOf[], b: readonly CaseOf[]) => a.some((x) => b.some((y) => y.select === x.select && y.value !== x.value));
+  const registerStep = (s: AnyStep, where: string, cases: readonly CaseOf[] = []) => {
     if (typeof s.name !== "string" || !STEP_NAME.test(s.name))
       problems.push(`${where}: step name '${String(s.name)}' must be lower-case kebab (${STEP_NAME})`);
     if (RESERVED.has(s.name)) problems.push(`${where}: '${s.name}' is reserved and cannot be a step name`);
-    if (steps.has(s.name)) problems.push(`duplicate step name '${s.name}'`);
-    steps.set(s.name, s);
+    const prev = placements.get(s.name) ?? [];
+    if (prev.some((p) => !exclusive(p.cases, cases))) problems.push(`duplicate step name '${s.name}'`);
+    else if (prev.length) {
+      if (prev.some((p) => p.step !== s && p.step.kind === "custom" && s.kind === "custom"))
+        problems.push(`step '${s.name}': two different custom steps share the name across select cases; handlers pair by name, so use one step or different names`);
+      if (prev.some((p) => (p.step.output?.name ?? null) !== (s.output?.name ?? null)))
+        problems.push(`step '${s.name}': its select cases must give it the same output model`);
+    }
+    placements.set(s.name, [...prev, { step: s, cases }]);
+    if (!steps.has(s.name)) steps.set(s.name, s);
   };
 
   const inputModel = data.input;
@@ -144,7 +179,7 @@ export function describePipeline(pipeline: unknown, opts: DescribeOptions): Mani
   const outputViewOf = (modelName: string | null): JsonSchema | undefined => (modelName ? models.get(modelName)?.schemas.output : undefined);
 
   // ── one step ──
-  const describeStep = (node: StageStepNode, avail: Map<string, Avail>, failureHandler: boolean): StepDescriptorT => {
+  const describeStep = (node: StageStepNode, avail: Map<string, Avail>, failureHandler: boolean, cases: readonly CaseOf[] = []): StepDescriptorT => {
     const s = node.step;
     const at = `step '${s.name}'`;
     if (typeof s.image !== "string" || s.image.trim() === "") problems.push(`${at}: image must be a non-empty string`);
@@ -194,11 +229,30 @@ export function describePipeline(pipeline: unknown, opts: DescribeOptions): Mani
       }
     }
 
+    for (const key of Object.keys(s.input as Record<string, unknown>))
+      if (key.startsWith("$")) problems.push(`${at}: input '${key}': keys starting with '$' are reserved`);
     const secretNames = s.secrets.map((x) => useSecret(x, at)).sort();
+    const configNames = [...new Set((s.config ?? []).map((c) => useConfig(c, at)).filter((n): n is string => n !== undefined))].sort();
+    // A library step that references parts of an entry needs the secrets those parts name; any other
+    // step receiving an entry needs every secret the entry names.
+    let refs: { ref: string; case?: string }[] = [];
+    try {
+      refs = s.builtin ? recordedConfigRefs(s.builtin.manifestConfig()) : [];
+    } catch {
+      // reported with the library configuration below
+    }
+    for (const name of configNames) {
+      const into = refs.filter((r) => r.ref.split(".")[0] === name);
+      const needed = into.length === 0
+        ? configs.get(name)?.secretRefs ?? []
+        : [...new Set(into.flatMap((r) => secretRefsOf(subSchemas(configs.get(name)?.schema, r.ref.split(".").slice(1), r.case, name))))].sort();
+      for (const ref of needed)
+        if (!secretNames.includes(ref)) problems.push(`${at}: config '${name}' references secret '${ref}' (secretRef), so the step must declare it in secrets`);
+    }
     let handlerHash: string;
     let config: Record<string, unknown> | undefined;
     if (s.kind === "custom") {
-      if (!handlerNames.has(s.name)) problems.push(`${at} has no handler (expected handlers/${s.name}.ts default-exporting implement(${camel(s.name)}, …))`);
+      if (!handlerNames.has(s.name)) problems.push(`${at} has no handler (add a handlers/*.ts default-exporting implement(${camel(s.name)}, …))`);
       handlerHash = opts.handlerHashes[s.name] ?? "";
       if (handlerNames.has(s.name) && !handlerHash) problems.push(`${at}: no handler hash was computed`);
     } else if (s.builtin) {
@@ -208,6 +262,13 @@ export function describePipeline(pipeline: unknown, opts: DescribeOptions): Mani
         problems.push(`${at}: invalid ${s.kind} configuration (${(e as Error).message})`);
         config = {};
       }
+      for (const { ref, case: kase } of recordedConfigRefs(config)) {
+        const [entry, ...path] = ref.split(".") as [string, ...string[]];
+        if (kase !== undefined && !cases.some((c) => c.cond === kase))
+          problems.push(`${at}: config reference '${ref}' is narrowed to the select case '${kase}' and can only be used inside it`);
+        if (!configNames.includes(entry)) problems.push(`${at}: config reference '${ref}': the step does not receive config entry '${entry}'`);
+        else if (!resolveField(configs.get(entry)?.schema, path)) problems.push(`${at}: config reference '${ref}': config '${entry}' has no field '${path.join(".")}'`);
+      }
       handlerHash = libraryHandlerHash(s.kind, config, opts.harness);
     } else {
       problems.push(`${at}: library step of kind '${s.kind}' has no implementation`);
@@ -230,7 +291,10 @@ export function describePipeline(pipeline: unknown, opts: DescribeOptions): Mani
       ...(s.timeoutSeconds !== undefined ? { timeoutSeconds: s.timeoutSeconds } : {}),
       ...(s.retries !== undefined ? { retries: s.retries } : {}),
       ...(config !== undefined ? { config: config as Record<string, z.core.util.JSONType> } : {}),
+      ...(configNames.length ? { configEntries: configNames } : {}),
+      ...(s.clusterAccess === true ? { clusterAccess: true as const } : {}),
     };
+    if (s.clusterAccess !== undefined && typeof s.clusterAccess !== "boolean") problems.push(`${at}: clusterAccess must be a boolean`);
     if (s.output && !isModel(s.output)) problems.push(`${at}: output must be a model`);
     return out;
   };
@@ -275,17 +339,22 @@ export function describePipeline(pipeline: unknown, opts: DescribeOptions): Mani
   };
 
   // ── stages ──
-  const walk = (nodes: readonly StageNode[], avail: Map<string, Avail>): Stage[] => {
+  let selects = 0;
+  const walk = (nodes: readonly StageNode[], avail: Map<string, Avail>, cases: readonly CaseOf[] = []): Stage[] => {
     const out: Stage[] = [];
     for (const n of nodes) {
+      if (n.kind === "select") {
+        out.push(describeSelect(n, avail, cases, ++selects));
+        continue;
+      }
       if (n.kind === "stage") {
         const descs = n.steps.map((ss) => {
           if (!isStep(ss.step)) {
             problems.push("a stage entry is not a step");
             return undefined;
           }
-          registerStep(ss.step, "stage");
-          return describeStep(ss, avail, false);
+          registerStep(ss.step, "stage", cases);
+          return describeStep(ss, avail, false, cases);
         }).filter((d): d is StepDescriptorT => d !== undefined);
         // Outputs become available only after the barrier (same-stage siblings can't see each other).
         for (const ss of n.steps) if (isStep(ss.step)) avail.set(ss.step.name, { model: ss.step.output?.name ?? null, maybe: false });
@@ -305,13 +374,43 @@ export function describePipeline(pipeline: unknown, opts: DescribeOptions): Mani
           when[field] = values;
         }
         const inner = new Map(avail);
-        const stages = walk(n.nodes, inner);
+        const stages = walk(n.nodes, inner, cases);
         for (const [name, a] of inner) if (!avail.has(name)) avail.set(name, { model: a.model, maybe: true });
         out.push({ when, stages });
       }
     }
     return out;
   };
+  const describeSelect = (n: Extract<StageNode, { kind: "select" }>, avail: Map<string, Avail>, cases: readonly CaseOf[], id: number): Stage => {
+    if (!isConfigRef(n.on)) {
+      problems.push("select: the first argument must be a config reference");
+      return { select: "", discriminator: "", cases: {} };
+    }
+    const ref = configRefPath(n.on);
+    const { entry, case: kase } = configRefTarget(n.on);
+    useConfig(entry, `select '${ref}'`);
+    if (kase !== undefined && !cases.some((c) => c.cond === kase))
+      problems.push(`select '${ref}': the reference is narrowed to the case '${kase}' and can only be used inside it`);
+    const union = unionAt(n.on);
+    if (!union) problems.push(`select '${ref}': it must reference a z.discriminatedUnion in config '${entry.name}'`);
+    else {
+      for (const v of union.values) if (!Object.hasOwn(n.cases, v)) problems.push(`select '${ref}': no case for ${union.discriminator} '${v}'`);
+      for (const v of Object.keys(n.cases)) if (!union.values.includes(v)) problems.push(`select '${ref}': '${v}' is not a value of ${union.discriminator} (${union.values.join(", ")})`);
+    }
+    const discriminator = union?.discriminator ?? "";
+    const branches = Object.entries(n.cases).map(([value, nodes]) => {
+      const inner = new Map(avail);
+      const stages = walk(nodes, inner, [...cases, { select: id, value, cond: `${ref}.${discriminator}=${value}` }]);
+      return { value, inner, stages };
+    });
+    // A step every case has is as available as in its cases; one only some cases have is maybe-available.
+    const added = new Set(branches.flatMap((b) => [...b.inner.keys()].filter((k) => !avail.has(k))));
+    for (const name of added) {
+      const present = branches.map((b) => b.inner.get(name)).filter((a): a is Avail => a !== undefined);
+      avail.set(name, { model: present[0]!.model, maybe: present.length < branches.length || present.some((a) => a.maybe) });
+    }
+    return { select: ref, discriminator, cases: Object.fromEntries(branches.map((b) => [b.value, b.stages])) };
+  };
   const stages = walk(data.nodes, new Map([["input", { model: inputModel.name, maybe: false }]]));
 
   // ── failure handlers ──
@@ -329,11 +428,11 @@ export function describePipeline(pipeline: unknown, opts: DescribeOptions): Mani
     return { step: describeStep({ step: fh.step }, new Map(), true), steps: scope };
   }).filter((x) => x !== undefined);
 
-  // ── handler files without a step ──
+  // ── handlers without a step ──
   for (const h of handlerNames) {
     const s = steps.get(h);
-    if (!s) problems.push(`handlers/${h}.ts does not match any step of the pipeline`);
-    else if (s.kind !== "custom") problems.push(`handlers/${h}.ts: '${h}' is a library step (${s.kind}) and must not have a handler file`);
+    if (!s) problems.push(`a handler implements step '${h}', which is not in the pipeline`);
+    else if (s.kind !== "custom") problems.push(`a handler implements '${h}', a library step (${s.kind}) that carries its own implementation`);
   }
 
   // ── triggers ──
@@ -369,6 +468,13 @@ export function describePipeline(pipeline: unknown, opts: DescribeOptions): Mani
     harness: opts.harness,
     models: Object.fromEntries([...models].map(([k, v]) => [k, v.schemas])),
     secrets: [...secrets].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([name, description]) => ({ name, description })),
+    ...(configs.size
+      ? {
+          config: [...configs]
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([name, c]) => ({ name, description: c.description, required: c.required, schema: c.schema })),
+        }
+      : {}),
     triggers,
     stages,
     failureHandlers,
@@ -381,6 +487,74 @@ export function describePipeline(pipeline: unknown, opts: DescribeOptions): Mani
 /** Canonical manifest text (what `describe` prints and the service hashes). */
 export const manifestText = (m: ManifestT): string => canonicalJson(m);
 
+/**
+ * The schemas at `path` inside an entry's schema: every union branch that has the field, except where
+ * `kase` (`<entry>.<path>.<discriminator>=<value>`) narrows a union to one branch.
+ */
+export function subSchemas(schema: unknown, path: readonly string[], kase: string | undefined, entry: string): unknown[] {
+  let narrow: { at: string; discriminator: string; value: string } | undefined;
+  if (kase) {
+    const eq = kase.lastIndexOf("=");
+    const left = kase.slice(0, eq);
+    const dot = left.lastIndexOf(".");
+    narrow = { at: left.slice(0, dot), discriminator: left.slice(dot + 1), value: kase.slice(eq + 1) };
+  }
+  const walk = (node: unknown, rest: readonly string[], here: string): unknown[] => {
+    if (node === null || typeof node !== "object") return [];
+    const o = node as JsonSchema;
+    const branches = (o.oneOf ?? o.anyOf) as JsonSchema[] | undefined;
+    if (Array.isArray(branches)) {
+      const chosen = narrow && narrow.at === here
+        ? branches.filter((b) => ((b.properties as Record<string, JsonSchema> | undefined)?.[narrow!.discriminator] as JsonSchema | undefined)?.const === narrow!.value)
+        : branches;
+      return chosen.flatMap((b) => walk(b, rest, here));
+    }
+    if (rest.length === 0) return [node];
+    const props = o.properties as Record<string, JsonSchema> | undefined;
+    if (props && Object.hasOwn(props, rest[0]!)) return walk(props[rest[0]!], rest.slice(1), `${here}.${rest[0]}`);
+    return [];
+  };
+  return walk(schema, path, entry);
+}
+
+/** Secret names of every secretRef inside a config entry's JSON Schema. */
+export function secretRefsOf(schema: unknown): string[] {
+  const out = new Set<string>();
+  const walk = (v: unknown) => {
+    if (Array.isArray(v)) return v.forEach(walk);
+    if (v === null || typeof v !== "object") return;
+    const o = v as JsonSchema;
+    if (o["x-olve-kind"] === SECRET_REF_KIND) {
+      const name = (o.properties as { secret?: { const?: unknown } } | undefined)?.secret?.const;
+      if (typeof name === "string") out.add(name);
+    }
+    Object.values(o).forEach(walk);
+  };
+  walk(schema);
+  return [...out].sort();
+}
+
+/** The `{"$config": "<entry>.<path>"[, "$case": …]}` references in a library step's recorded configuration. */
+export function recordedConfigRefs(v: unknown, out: { ref: string; case?: string }[] = []): { ref: string; case?: string }[] {
+  if (Array.isArray(v)) v.forEach((x) => recordedConfigRefs(x, out));
+  else if (v !== null && typeof v === "object") {
+    const o = v as Record<string, unknown>;
+    const keys = Object.keys(o).sort();
+    const isRef = typeof o[CONFIG_REF_KEY] === "string"
+      && (keys.length === 1 ? keys[0] === CONFIG_REF_KEY : keys.length === 2 && keys[0] === CONFIG_CASE_KEY && keys[1] === CONFIG_REF_KEY && typeof o[CONFIG_CASE_KEY] === "string");
+    if (isRef) out.push({ ref: o[CONFIG_REF_KEY] as string, ...(keys.length === 2 ? { case: o[CONFIG_CASE_KEY] as string } : {}) });
+    else Object.values(o).forEach((x) => recordedConfigRefs(x, out));
+  }
+  return out;
+}
+
+/** A select case a step sits in: which select (numbered in describe order), which value, and its condition text. */
+interface CaseOf {
+  select: number;
+  value: string;
+  cond: string;
+}
+
 function camel(name: string): string {
   return name.replace(/-([a-z0-9])/g, (_, c: string) => c.toUpperCase());
 }

package/src/describe/manifest-schema.ts

@@ -7,6 +7,7 @@ export const API_VERSION = "2.0";
 const stepName = z.string().regex(/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/).describe("Step name: lower-case kebab, 1-63 chars. The step's identity.");
 const modelName = z.string().regex(/^[A-Za-z][A-Za-z0-9_]*$/).describe("Model name (key of `models`).");
 const secretName = z.string().regex(/^[A-Z_][A-Z0-9_]*$/).describe("Secret name; also the env var name in the step container.");
+const configName = z.string().regex(/^[a-z][a-zA-Z0-9]*$/).describe("Config entry name; a key of the pipeline's config document.");
 const hash = z.string().regex(/^sha256:[0-9a-f]{64}$/);
 const Json = z.json().meta({ id: "Json", description: "Any JSON value." });
 const jsonSchema = z.record(z.string(), z.unknown()).describe("A JSON Schema (draft 2020-12) object, canonical (sorted keys, no $schema).");
@@ -50,7 +51,7 @@ export const StepDescriptor = z
   .strictObject({
     name: stepName,
     description: z.string().describe("What the step does, shown in the UI (may be empty)."),
-    kind: z.enum(["custom", "script", "gitHubSource", "imageBuild", "helmDeployOverSsh"]).describe("'custom' = handlers/<name>.ts; others are SDK library steps."),
+    kind: z.string().min(1).describe("'custom' = handlers/<name>.ts; others are SDK library steps. A label: the service accepts any kind."),
     image: z.string().min(1).describe("Container image the step runs in."),
     inputTypes: z.record(z.string(), InputType).describe("Declared input entries, keyed like input.json."),
     input: z.record(z.string(), Mapping).describe("How the service assembles input.json: one mapping per input key (same keys as inputTypes)."),
@@ -59,11 +60,25 @@ export const StepDescriptor = z
     handlerHash: hash.describe("Implementation identity: handler bundle (contract files excluded) + harness (bun + sdkHash); for library steps kind + config + harness."),
     timeoutSeconds: z.number().int().positive().optional(),
     retries: z.number().int().nonnegative().optional(),
-    config: z.record(z.string(), Json).optional().describe("Library-step configuration (display only; already covered by handlerHash)."),
+    config: z
+      .record(z.string(), Json)
+      .optional()
+      .describe("Library-step configuration (display only; already covered by handlerHash). A config reference is recorded as {\"$config\": \"<entry>.<field>…\"}; the entry is in configEntries."),
+    configEntries: z
+      .array(configName)
+      .optional()
+      .describe("Config entries the step receives (sorted; omitted when none). The service delivers them in input.json under '$config'."),
+    clusterAccess: z
+      .literal(true)
+      .optional()
+      .describe("The step pod gets the instance's step ServiceAccount token (Kubernetes:StepServiceAccount), if the instance grants one. Omitted = no token."),
   })
   .meta({ id: "Step" });
 
-export type Stage = { steps: z.infer<typeof StepDescriptor>[] } | { when: Record<string, (string | number | boolean)[]>; stages: Stage[] };
+export type Stage =
+  | { steps: z.infer<typeof StepDescriptor>[] }
+  | { when: Record<string, (string | number | boolean)[]>; stages: Stage[] }
+  | { select: string; discriminator: string; cases: Record<string, Stage[]> };
 export const Stage: z.ZodType<Stage> = z
   .union([
     z.strictObject({ steps: z.array(StepDescriptor).min(1).describe("Steps run in parallel; the stage is a barrier.") }),
@@ -73,6 +88,13 @@ export const Stage: z.ZodType<Stage> = z
       ),
       stages: z.array(z.lazy(() => Stage)),
     }),
+    z.strictObject({
+      select: z.string().min(1).describe("Config reference (`<entry>.<field>…`) to a discriminated union; the run's config snapshot picks the case."),
+      discriminator: z.string().min(1).describe("The union's literal field whose value names the case."),
+      cases: z
+        .record(z.string(), z.array(z.lazy(() => Stage)))
+        .describe("Discriminator value → stages. Exactly one case runs; a step name may repeat across cases, nowhere else."),
+    }),
   ])
   .meta({ id: "Stage" });
 
@@ -117,12 +139,23 @@ export const Manifest = z
     harness: z
       .strictObject({
         bun: z.string().describe("Bun runtime version compiled into the binary."),
-        sdk: z.string().describe("@olve/pipelines package version."),
+        sdk: z.string().describe("@olivervea/pipelines package version."),
         sdkHash: hash.describe("Hash of the SDK runtime sources + zod version."),
       })
       .describe("Harness identity. Already folded into every handlerHash."),
     models: z.record(modelName, ModelSchemas).describe("Every model referenced by the pipeline (input, step inputs/outputs)."),
     secrets: z.array(z.strictObject({ name: secretName, description: z.string() })).describe("All declared secrets (steps + poll triggers), sorted by name."),
+    config: z
+      .array(
+        z.strictObject({
+          name: configName,
+          description: z.string(),
+          required: z.boolean().describe("False when the schema accepts a missing value (optional, or a default)."),
+          schema: jsonSchema.describe("z.input view: validates the config document's value for this entry (defaults listed)."),
+        }),
+      )
+      .optional()
+      .describe("Config entries used by steps, sorted by name (omitted when none). Fields of kind secretRef ({secret: NAME}) name a secret."),
     triggers: z.array(Trigger),
     stages: z.array(Stage),
     failureHandlers: z.array(

package/src/dev/cli.ts

@@ -1,10 +1,10 @@
 #!/usr/bin/env bun
 // olve-dev — run a pipeline from source through the same harness path as the compiled binary.
 //   olve-dev describe <dir> [--sentinels]
-//   olve-dev run <dir> <step> [--input-file f] [--olve-dir d] [--secret NAME=value]...
+//   olve-dev run <dir> <step> [--input-file f] [--config-file f] [--olve-dir d] [--secret NAME=value]...
 //   olve-dev map-trigger <dir> <trigger> --event-file f [--olve-dir d]
 // $OLVE_DIR defaults to <dir>/.olve; outputs land in <dir>/.olve/work/.
-import { copyFileSync, mkdirSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { runHarness, type HarnessConfig } from "../harness/main.ts";
@@ -13,11 +13,11 @@ import { handlerHashes } from "../build/hashes.ts";
 import { harnessInfo, loadProject, ProjectError } from "../build/project.ts";
 
 const USAGE = `usage: olve-dev describe <dir> [--sentinels]
-       olve-dev run <dir> <step> [--input-file f] [--olve-dir d] [--secret NAME=value]...
+       olve-dev run <dir> <step> [--input-file f] [--config-file f] [--olve-dir d] [--secret NAME=value]...
        olve-dev map-trigger <dir> <trigger> --event-file f [--olve-dir d]`;
 
 export async function devConfig(dir: string, withHashes: boolean): Promise<HarnessConfig> {
-  const project = loadProject(dir);
+  const project = await loadProject(dir);
   const mod = (await import(project.pipelineFile)) as { default?: unknown };
   if (!mod.default) throw new ProjectError(`${project.pipelineFile} has no default export (export default pipeline({...})...)`);
   const harness = harnessInfo();
@@ -38,6 +38,7 @@ export async function devMain(argv: string[]): Promise<number> {
       allowPositionals: true,
       options: {
         "input-file": { type: "string" },
+        "config-file": { type: "string" },
         "event-file": { type: "string" },
         "olve-dir": { type: "string" },
         secret: { type: "string", multiple: true },
@@ -68,6 +69,12 @@ export async function devMain(argv: string[]): Promise<number> {
     }
     const file = mode === "run" ? values["input-file"] : values["event-file"];
     if (file) copyFileSync(resolve(file), join(olveDir, "input.json"));
+    if (mode === "run" && values["config-file"]) {
+      const inputFile = join(olveDir, "input.json");
+      const input = (existsSync(inputFile) ? JSON.parse(readFileSync(inputFile, "utf8")) : {}) as Record<string, unknown>;
+      input.$config = JSON.parse(readFileSync(resolve(values["config-file"]), "utf8"));
+      writeFileSync(inputFile, JSON.stringify(input));
+    }
     else if (mode === "map-trigger") return console.error("--event-file is required"), EXIT.usage;
     return await runHarness(await devConfig(dir, false), [mode, name]);
   } catch (e) {

package/src/harness/execute.ts

@@ -8,7 +8,7 @@ import type { Ctx, RunInfo } from "../ctx/types.ts";
 import { objectPath } from "../ctx/files.ts";
 import { sha256File } from "../util/hash.ts";
 import { EXIT } from "./exit.ts";
-import { validateInput, validateOutput } from "./validate.ts";
+import { validateConfig, validateInput, validateOutput } from "./validate.ts";
 
 export type FailureKind = "handler" | "input" | "output";
 export type Envelope =
@@ -58,13 +58,16 @@ export async function executeStep(args: {
   workFiles: string;
   log: (line: string) => void;
 }): Promise<Execution> {
-  const { step, ctx, log } = args;
+  const { step, log } = args;
   const input = validateInput(step, args.rawInput);
-  if (!input.ok) {
-    const message = `step '${step.name}': input does not match the step's inputs:\n  ${input.issues.join("\n  ")}`;
+  const config = validateConfig(step, args.rawInput);
+  if (!input.ok || !config.ok) {
+    const issues = [...(input.ok ? [] : input.issues), ...(config.ok ? [] : config.issues)];
+    const message = `step '${step.name}': input does not match the step's inputs:\n  ${issues.join("\n  ")}`;
     log(message);
     return { envelope: { status: "failed", error: { kind: "input", message } }, exitCode: EXIT.inputInvalid };
   }
+  const ctx: Ctx = { ...args.ctx, config: Object.freeze(config.value) as Ctx["config"] };
 
   let value: unknown;
   try {

package/src/harness/index.ts

@@ -1,4 +1,4 @@
-// @olve/pipelines/harness — the runtime the build tool compiles into the step binary.
+// @olivervea/pipelines/harness — the runtime the build tool compiles into the step binary.
 export { runHarness, defaultIO, allSteps, resolveStepFunction, type HarnessConfig, type HandlerRegistry, type HarnessIO } from "./main.ts";
 export { EXIT } from "./exit.ts";
 export { ENV, paths, runInfoFromEnv } from "./env.ts";

package/src/harness/main.ts

@@ -5,6 +5,7 @@
 import { mkdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { isImplementation } from "../core/handlers.ts";
+import { configRefPath, isConfigRef, unionAt } from "../core/config.ts";
 import type { AnyStep } from "../core/steps.ts";
 import type { WebhookEvent } from "../core/webhooks.ts";
 import { pipelineData, type PipelineData, type StageNode } from "../builder/pipeline.ts";
@@ -46,14 +47,43 @@ const USAGE = "usage: step describe [--sentinels] | step run <step> | step map-t
 
 export function allSteps(data: PipelineData): AnyStep[] {
   const out: AnyStep[] = [];
-  const walk = (nodes: readonly StageNode[]) => {
-    for (const n of nodes) n.kind === "stage" ? out.push(...n.steps.map((s) => s.step)) : walk(n.nodes);
+  for (const { step } of stepsWithCases(data)) if (!out.includes(step)) out.push(step);
+  return out;
+}
+
+/** Every step with the `select` case conditions (`<ref>.<discriminator>=<value>`) it sits in. */
+export function stepsWithCases(data: PipelineData): { step: AnyStep; cases: string[] }[] {
+  const out: { step: AnyStep; cases: string[] }[] = [];
+  const walk = (nodes: readonly StageNode[], cases: string[]) => {
+    for (const n of nodes) {
+      if (n.kind === "stage") out.push(...n.steps.map((s) => ({ step: s.step, cases })));
+      else if (n.kind === "when") walk(n.nodes, cases);
+      else {
+        const union = isConfigRef(n.on) ? unionAt(n.on) : undefined;
+        for (const [value, inner] of Object.entries(n.cases))
+          walk(inner, union ? [...cases, `${configRefPath(n.on)}.${union.discriminator}=${value}`] : cases);
+      }
+    }
   };
-  walk(data.nodes);
-  for (const fh of data.failureHandlers) if (!out.includes(fh.step)) out.push(fh.step);
+  walk(data.nodes, []);
+  for (const fh of data.failureHandlers) out.push({ step: fh.step, cases: [] });
   return out;
 }
 
+/** The step `run <name>` executes: the only one so named, or the one in the cases the service selected (`OLVE_CASES`). */
+export function findStep(data: PipelineData, name: string, selected: readonly string[]): AnyStep | string {
+  const candidates = stepsWithCases(data).filter((c) => c.step.name === name);
+  const distinct = candidates.filter((c, i) => candidates.findIndex((d) => d.step === c.step) === i);
+  if (distinct.length === 0) return `unknown step '${name}'`;
+  if (distinct.length === 1) return distinct[0]!.step;
+  const chosen = distinct.filter((c) => c.cases.every((k) => selected.includes(k)));
+  if (chosen.length === 1) return chosen[0]!.step;
+  return `step '${name}' is in several select cases; ${ENV_CASES} must name the selected one (got ${JSON.stringify(selected)})`;
+}
+
+/** The select case conditions of the step being run (JSON array), set by the service for steps inside a select. */
+export const ENV_CASES = "OLVE_CASES";
+
 /** Installs SIGTERM/SIGINT handlers that abort the returned signal (PID 1 ignores signals without them). */
 export function cancellation(): { signal: AbortSignal; dispose(): void } {
   const ac = new AbortController();
@@ -77,17 +107,17 @@ export async function resolveStepFunction(step: AnyStep, handlers: HandlerRegist
     return step.builtin.run as StepFunction;
   }
   const load = handlers[step.name];
-  if (!load) return `step '${step.name}' has no handler (expected handlers/${step.name}.ts)`;
+  if (!load) return `step '${step.name}' has no handler`;
   let mod: { default: unknown };
   try {
     mod = await load();
   } catch (e) {
-    return `handlers/${step.name}.ts failed to load: ${(e as Error)?.stack ?? String(e)}`;
+    return `the handler of step '${step.name}' failed to load: ${(e as Error)?.stack ?? String(e)}`;
   }
   const impl = mod.default;
-  if (!isImplementation(impl)) return `handlers/${step.name}.ts must default-export implement(<step '${step.name}'>, …)`;
+  if (!isImplementation(impl)) return `the handler of step '${step.name}' must default-export implement(<step '${step.name}'>, …)`;
   if (impl.step !== step)
-    return `handlers/${step.name}.ts implements step '${(impl.step as AnyStep)?.name}', not '${step.name}' (the default export must be implement(<the '${step.name}' step from pipeline.ts>, …))`;
+    return `the handler of step '${step.name}' implements a different step object (it must be implement(<the '${step.name}' step from pipeline.ts>, …))`;
   return impl.handler as unknown as StepFunction;
 }
 
@@ -136,8 +166,8 @@ async function describeMode(cfg: HarnessConfig, args: string[], io: HarnessIO):
 async function runMode(cfg: HarnessConfig, name: string | undefined, io: HarnessIO): Promise<number> {
   if (!name) return io.stderr(USAGE), EXIT.usage;
   const data = pipelineData(cfg.pipeline);
-  const step = allSteps(data).find((s) => s.name === name);
-  if (!step) return io.stderr(`unknown step '${name}'`), EXIT.usage;
+  const step = findStep(data, name, selectedCases());
+  if (typeof step === "string") return io.stderr(step), EXIT.usage;
   const fn = await resolveStepFunction(step, cfg.handlers);
   if (typeof fn === "string") return io.stderr(fn), EXIT.configInvalid;
 
@@ -230,3 +260,12 @@ export async function runHarness(cfg: HarnessConfig, argv: readonly string[], io
 }
 
 export { formatIssues, formatLog };
+
+function selectedCases(): string[] {
+  try {
+    const v = JSON.parse(process.env[ENV_CASES] ?? "[]") as unknown;
+    return Array.isArray(v) ? v.filter((x): x is string => typeof x === "string") : [];
+  } catch {
+    return [];
+  }
+}

package/src/harness/validate.ts

@@ -44,13 +44,31 @@ function entrySchema(e: unknown): z.ZodType {
   return e as z.ZodType;
 }
 
+/** Reserved input.json key holding the step's config entries (written by the service). */
+export const CONFIG_KEY = "$config";
+
+/** Parses `$config` with each declared entry's schema (defaults applied). Undeclared entries are ignored. */
+export function validateConfig(step: AnyStep, raw: unknown): Validation<Record<string, unknown>> {
+  const given = isPlainObject(raw) ? raw[CONFIG_KEY] : undefined;
+  if (given !== undefined && !isPlainObject(given)) return { ok: false, issues: [`input.${CONFIG_KEY} must be an object keyed by config entry names`] };
+  const issues: string[] = [];
+  const out: Record<string, unknown> = {};
+  for (const e of step.config ?? []) {
+    const value = given?.[e.name];
+    const r = e.schema.safeParse(value);
+    if (!r.success) issues.push(...formatIssues(r.error, `config.${e.name}`).map((i) => (value === undefined ? `${i} (config entry '${e.name}' is not set)` : i)));
+    else if (r.data !== undefined) out[e.name] = r.data;
+  }
+  return issues.length ? { ok: false, issues } : { ok: true, value: out };
+}
+
 /** Validates input.json against the step's input entries. Unknown top-level keys are rejected; nested values are parsed (unknown nested keys stripped). */
 export function validateInput(step: AnyStep, raw: unknown): Validation<Record<string, unknown>> {
   if (!isPlainObject(raw)) return { ok: false, issues: ["input.json must be a JSON object keyed by the step's input names"] };
   const issues: string[] = [];
   const out: Record<string, unknown> = {};
   const declared = step.input as Record<string, unknown>;
-  for (const k of Object.keys(raw)) if (!Object.hasOwn(declared, k)) issues.push(`input.${k}: not an input of step '${step.name}'`);
+  for (const k of Object.keys(raw)) if (k !== CONFIG_KEY && !Object.hasOwn(declared, k)) issues.push(`input.${k}: not an input of step '${step.name}'`);
   for (const [k, e] of Object.entries(declared)) {
     if (!Object.hasOwn(raw, k)) {
       if (isOptional(e)) continue;

package/src/index.ts

@@ -1,12 +1,13 @@
 /// <reference path="./assets.d.ts" />
-// @olve/pipelines — authoring API (contracts, handlers, pipeline builder).
+// @olivervea/pipelines — authoring API (contracts, handlers, pipeline builder).
 export { z } from "zod";
 export { model, fileRef, optional, type Model, type AnyModel, type Infer, type InferInput, type Plain, type FileRef, type Optional } from "./core/models.ts";
 export { secret, type Secret, type DeclaredSecrets } from "./core/secrets.ts";
+export { config, secretRef, type ConfigEntry, type AnyConfigEntry, type ConfigValues, type ConfigRef, type ConfigNode, type Configurable, type DiscriminatorOf, type VariantOf } from "./core/config.ts";
 export { hmacSha256, githubSignature, bearer, type WebhookVerify, type WebhookEvent } from "./core/webhooks.ts";
-export { step, type Step, type AnyStep, type StepDef, type StepInput, type StepKind, type InputEntry, type InputSpec, type LibraryStep, type OutputValue } from "./core/steps.ts";
+export { step, type Step, type AnyStep, type StepDef, type StepInput, type StepKind, type ConfigOf, type InputEntry, type InputSpec, type LibraryStep, type OutputValue } from "./core/steps.ts";
 export { implement, type Implementation, type Handler, type HandlerResult, type Skipped } from "./core/handlers.ts";
 export type { Ctx, RunInfo, Sh, ShOptions, ExecOptions, Http, HttpInit, RetryOptions, OutputFileOptions } from "./ctx/types.ts";
 export type { Ref, Mappable, MapperResult } from "./builder/refs.ts";
 export { pipeline, Pipeline, type PipelineDef, type InRefs, type InitialAvail, type WhenCond, type PushEvent, type StageEntry, type CheckStage, type MapperFn } from "./builder/pipeline.ts";
-export { steps, Source, BuiltImage, HelmRelease, FailureContext, type RunValue, type ScriptDef, type GitHubSourceDef, type ImageBuildDef, type HelmDeployOverSshDef, httpHealthCheck, type HttpHealthCheckOptions } from "./library/index.ts";
+export { steps, Source, BuiltImage, PushedImage, HelmRelease, FailureContext, type RunValue, type ScriptDef, type GitHubSourceDef, type ImageBuildDef, type ImageBuildTarballDef, type ImageBuildPushDef, type RegistryAuth, type HelmDeployOverSshDef, helmTarget, deployTarget, type ComposeTargetValue, type HelmDeployInClusterDef, type HelmDeploySshTargetDef, type HelmTargetValue, type InClusterTargetValue, type SshTargetValue, registryTag, registryDigest, type RegistryAuthConfig, type RegistryAccess, npmDistTag, npmHasVersion, httpHealthCheck, type HttpHealthCheckOptions, sshSession, shq, type SshSession, serviceUrl, checkSpa } from "./library/index.ts";