@olivervea/pipelines 2.0.0-beta.7 → 2.0.0-beta.8

package/src/describe/describe.ts

@@ -7,6 +7,8 @@ import { configRefPath, configRefTarget, isConfigRef, unionAt } from "../core/co
 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";
+import { isImplementation } from "../core/handlers.ts";
+import { recordConfigRefs } from "../core/config-refs.ts";
 import { pipelineData, type MapperFunction, type StageNode, type StageStepNode } from "../builder/pipeline.ts";
 import { FailureContext } from "../library/models.ts";
 import { canonicalize, canonicalJson } from "../util/canonical.ts";
@@ -27,6 +29,8 @@ export interface DescribeOptions {
   handlerNames: Iterable<string>;
   /** Step name → handler hash (from the build; includes the harness identity). */
   handlerHashes: Readonly<Record<string, string>>;
+  /** Kind → hash of the code that implements the steps of that kind which carry their implementation (from the build). */
+  kindHashes?: Readonly<Record<string, string>>;
   harness: HarnessInfo;
 }
 
@@ -163,8 +167,8 @@ export function describePipeline(pipeline: unknown, opts: DescribeOptions): Mani
     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 !== s && !isImplementation(p.step) && !isImplementation(s)))
+        problems.push(`step '${s.name}': two different steps with handler files 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`);
     }
@@ -233,14 +237,20 @@ export function describePipeline(pipeline: unknown, opts: DescribeOptions): Mani
       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
+    const carried = isImplementation(s);
+    let settings: Record<string, unknown> | undefined;
+    let settingsProblem: string | undefined;
+    if (s.settings !== undefined || carried) {
+      try {
+        settings = canonicalize(recordConfigRefs(s.settings ?? {})) as Record<string, unknown>;
+      } catch (e) {
+        settingsProblem = (e as Error).message;
+        settings = {};
+      }
     }
+    const refs = settings ? recordedConfigRefs(settings) : [];
+    // A step whose settings reference parts of an entry needs the secrets those parts name; any other
+    // step receiving an entry needs every secret the entry names.
     for (const name of configNames) {
       const into = refs.filter((r) => r.ref.split(".")[0] === name);
       const needed = into.length === 0
@@ -250,29 +260,24 @@ export function describePipeline(pipeline: unknown, opts: DescribeOptions): Mani
         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 (settingsProblem !== undefined) problems.push(`${at}: invalid ${s.kind} settings (${settingsProblem})`);
+    if (typeof s.kind !== "string" || s.kind === "") problems.push(`${at}: kind must be a non-empty string`);
+    if (carried && s.kind === "custom") problems.push(`${at} carries its implementation, so it needs a kind (step({ kind: "…", … })); a step with kind custom has its handler in handlers/`);
+    for (const { ref, case: kase } of refs) {
+      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(".")}'`);
+    }
+    if (carried) {
+      const code = opts.kindHashes?.[s.kind];
+      if (opts.kindHashes && !code) problems.push(`${at}: no hash was computed for the code of kind '${s.kind}'`);
+      handlerHash = libraryHandlerHash(s.kind, settings, opts.harness, code);
+    } else {
       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) {
-      try {
-        config = canonicalize(s.builtin.manifestConfig()) as Record<string, unknown>;
-      } catch (e) {
-        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`);
-      handlerHash = "";
     }
     if (typeof s.description !== "string") problems.push(`${at}: description must be a string (it may be empty)`);
     if (s.timeoutSeconds !== undefined && !(Number.isInteger(s.timeoutSeconds) && s.timeoutSeconds > 0)) problems.push(`${at}: timeoutSeconds must be a positive integer`);
@@ -290,7 +295,7 @@ export function describePipeline(pipeline: unknown, opts: DescribeOptions): Mani
       handlerHash: handlerHash || "sha256:" + "0".repeat(64),
       ...(s.timeoutSeconds !== undefined ? { timeoutSeconds: s.timeoutSeconds } : {}),
       ...(s.retries !== undefined ? { retries: s.retries } : {}),
-      ...(config !== undefined ? { config: config as Record<string, z.core.util.JSONType> } : {}),
+      ...(settings !== undefined ? { config: settings as Record<string, z.core.util.JSONType> } : {}),
       ...(configNames.length ? { configEntries: configNames } : {}),
       ...(s.clusterAccess === true ? { clusterAccess: true as const } : {}),
     };
@@ -432,7 +437,7 @@ export function describePipeline(pipeline: unknown, opts: DescribeOptions): Mani
   for (const h of handlerNames) {
     const s = steps.get(h);
     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`);
+    else if (isImplementation(s)) problems.push(`a handler implements '${h}', a ${s.kind} step that carries its own implementation`);
   }
 
   // ── triggers ──
@@ -534,7 +539,7 @@ export function secretRefsOf(schema: unknown): string[] {
   return [...out].sort();
 }
 
-/** The `{"$config": "<entry>.<path>"[, "$case": …]}` references in a library step's recorded configuration. */
+/** The `{"$config": "<entry>.<path>"[, "$case": …]}` references in a step's recorded settings. */
 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") {

package/src/describe/manifest-schema.ts

@@ -51,19 +51,19 @@ export const StepDescriptor = z
   .strictObject({
     name: stepName,
     description: z.string().describe("What the step does, shown in the UI (may be empty)."),
-    kind: z.string().min(1).describe("'custom' = handlers/<name>.ts; others are SDK library steps. A label: the service accepts any kind."),
+    kind: z.string().min(1).describe("'custom' = the handler is a handlers/*.ts file; any other kind is a step that carries its implementation (an SDK or package step). 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)."),
     output: modelName.nullable().describe("Output model, or null if the step produces no output."),
     secrets: z.array(secretName).describe("Declared secrets (sorted). Mount exactly these, as env vars of the same name."),
-    handlerHash: hash.describe("Implementation identity: handler bundle (contract files excluded) + harness (bun + sdkHash); for library steps kind + config + harness."),
+    handlerHash: hash.describe("Implementation identity: handler bundle (contract files excluded) + harness (bun + sdkHash); for a step that carries its implementation kind + config + harness + the hash of the code of its kind."),
     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). A config reference is recorded as {\"$config\": \"<entry>.<field>…\"}; the entry is in configEntries."),
+      .describe("The step's settings (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()

package/src/dev/cli.ts

@@ -9,8 +9,8 @@ import { join, resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { runHarness, type HarnessConfig } from "../harness/main.ts";
 import { EXIT } from "../harness/exit.ts";
-import { handlerHashes } from "../build/hashes.ts";
-import { harnessInfo, loadProject, ProjectError } from "../build/project.ts";
+import { handlerHashes, kindHashes } from "../build/hashes.ts";
+import { harnessInfo, loadPipeline, loadProject, ProjectError } from "../build/project.ts";
 
 const USAGE = `usage: olve-dev describe <dir> [--sentinels]
        olve-dev run <dir> <step> [--input-file f] [--config-file f] [--olve-dir d] [--secret NAME=value]...
@@ -18,14 +18,14 @@ const USAGE = `usage: olve-dev describe <dir> [--sentinels]
 
 export async function devConfig(dir: string, withHashes: boolean): Promise<HarnessConfig> {
   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 pipeline = await loadPipeline(project);
   const harness = harnessInfo();
   const hashes = withHashes ? await handlerHashes(project, harness) : {};
   return {
-    pipeline: mod.default,
+    pipeline,
     handlers: Object.fromEntries(project.handlers.map(([name, file]) => [name, () => import(file) as Promise<{ default: unknown }>])),
     handlerHashes: Object.fromEntries(Object.entries(hashes).map(([k, v]) => [k, v.handlerHash])),
+    ...(withHashes ? { kindHashes: await kindHashes(project, pipeline) } : {}),
     harness,
   };
 }

package/src/harness/main.ts

@@ -26,6 +26,8 @@ export interface HarnessConfig {
   pipeline: unknown;
   handlers: HandlerRegistry;
   handlerHashes: Readonly<Record<string, string>>;
+  /** Kind → hash of the code of the steps of that kind that carry their implementation. */
+  kindHashes?: Readonly<Record<string, string>>;
   harness: HarnessInfo;
 }
 
@@ -100,12 +102,9 @@ export function cancellation(): { signal: AbortSignal; dispose(): void } {
   };
 }
 
-/** Resolves the function that implements `step` (library or handler module). */
+/** Resolves the function that implements `step` (carried by the step, or a handler module). */
 export async function resolveStepFunction(step: AnyStep, handlers: HandlerRegistry): Promise<StepFunction | string> {
-  if (step.kind !== "custom") {
-    if (!step.builtin) return `library step '${step.name}' (${step.kind}) has no implementation`;
-    return step.builtin.run as StepFunction;
-  }
+  if (isImplementation(step)) return step.handler as unknown as StepFunction;
   const load = handlers[step.name];
   if (!load) return `step '${step.name}' has no handler`;
   let mod: { default: unknown };
@@ -151,7 +150,7 @@ function readJson(path: string): { ok: true; value: unknown } | { ok: false; mes
 async function describeMode(cfg: HarnessConfig, args: string[], io: HarnessIO): Promise<number> {
   const sentinels = args.includes("--sentinels");
   try {
-    const text = manifestText(describePipeline(cfg.pipeline, { handlerNames: Object.keys(cfg.handlers), handlerHashes: cfg.handlerHashes, harness: cfg.harness }));
+    const text = manifestText(describePipeline(cfg.pipeline, { handlerNames: Object.keys(cfg.handlers), handlerHashes: cfg.handlerHashes, kindHashes: cfg.kindHashes, harness: cfg.harness }));
     await io.stdout(sentinels ? `${MANIFEST_BEGIN}\n${text}${MANIFEST_END}\n` : text);
     return EXIT.ok;
   } catch (e) {

package/src/index.ts

@@ -3,11 +3,13 @@
 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 { config, secretRef, isConfigRef, 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 ConfigOf, type InputEntry, type InputSpec, type LibraryStep, type OutputValue } from "./core/steps.ts";
+export { resolveConfigRefs, isLiteral, type Resolved } from "./core/config-refs.ts";
+export { step, type Step, type AnyStep, type StepDef, type StepInput, type StepKind, type ConfigOf, type InputEntry, type InputSpec, type LiteralName, type OutputValue } from "./core/steps.ts";
+export type { Simplify } from "./core/types.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, 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";
+export { steps, Source, BuiltImage, PushedImage, HelmRelease, FailureContext, type GitHubSourceDef, type ImageBuildDef, type ImageBuildTarballDef, type ImageBuildPushDef, type RegistryAuth, type RegistryAuthConfig, type HelmDeployOverSshDef, helmTarget, deployTarget, type DeployTargetOptions, type ComposeDeployDef, type ComposeTargetValue, type HelmDeployInClusterDef, type HelmDeploySshTargetDef, type HelmTargetDeployDef, type HelmTargetValue, type InClusterTargetValue, type SshTargetValue, httpHealthCheck, type HttpHealthCheckOptions, sshSession, type SshSession, serviceUrl, checkSpa } from "./library/index.ts";

package/src/library/compose-deploy.ts

@@ -3,9 +3,10 @@
 // and is fixed there, behind a versioned HTTP API, without editing pipelines.
 import type { Ctx } from "../ctx/types.ts";
 import type { Configurable } from "../core/config.ts";
-import { recordConfigRefs, resolveConfigRefs } from "../core/config-refs.ts";
+import { resolveConfigRefs } from "../core/config-refs.ts";
+import { implement, type Implementation } from "../core/handlers.ts";
 import type { Secret } from "../core/secrets.ts";
-import { makeStep, type LibraryStep, type LiteralName, type Step } from "../core/steps.ts";
+import { step, type LiteralName, type Step } from "../core/steps.ts";
 import { httpHealthCheck } from "./http-health.ts";
 import { HelmRelease, PushedImage } from "./models.ts";
 
@@ -53,41 +54,43 @@ const input = { image: PushedImage };
  */
 export function composeDeploy<const N extends string, const K extends string>(
   def: ComposeDeployDef<N, K>,
-): Step<N, typeof input, typeof HelmRelease, K> & LibraryStep {
-  const configurable = { target: def.target };
-  return makeStep(
-    "composeDeploy",
-    { name: def.name, description: def.description, image: COMPOSE_DEPLOY_IMAGE, input, output: HelmRelease, secrets: [def.token], timeoutSeconds: def.timeoutSeconds },
-    {
-      manifestConfig: () => ({ target: recordConfigRefs(def.target), token: def.token.name }),
-      async run({ image }: { image: { repository: string; digest: string } }, ctx: Ctx) {
-        const { target } = resolveConfigRefs(configurable, ctx.config ?? {}) as { target: ComposeTargetValue };
-        if (target?.kind !== "compose") throw new Error(`composeDeploy '${def.name}': the target is kind '${String(target?.kind)}', not 'compose'`);
-        if (target.token.secret !== def.token.name) throw new Error(`composeDeploy '${def.name}': the target's token names secret ${target.token.secret}, but the step declares ${def.token.name}`);
-        const token = (ctx.secrets as Record<string, string>)[def.token.name];
-        const ref = `${image.repository}@${image.digest}`;
-        const url = `${target.deployerUrl.replace(/\/+$/, "")}/v1/deploy`;
-        ctx.log("deploying", { service: target.service, image: ref, deployer: target.deployerUrl });
-        const res = await ctx.http.fetch(url, {
-          method: "POST",
-          headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
-          body: JSON.stringify({ service: target.service, image: ref }),
-        });
-        const text = await res.text();
-        let result: ComposeDeployResult | undefined;
-        try {
-          result = JSON.parse(text) as ComposeDeployResult;
-        } catch {
-          // reported below
-        }
-        for (const line of result?.log ?? []) ctx.log(`deployer: ${line}`);
-        if (!res.ok || result?.status !== "deployed")
-          throw new Error(`the deployer answered HTTP ${res.status}: ${result ? `${result.status}${result.message ? `: ${result.message}` : ""}` : text.slice(0, 300)}`);
-        if (target.healthUrl) await httpHealthCheck(ctx, target.healthUrl, { attempts: 12, delaySeconds: 5 });
-        ctx.log("deployed", { service: target.service, image: ref, previous: result.previousImage ?? "-" });
-        return { release: target.service, namespace: "compose", image: ref };
-      },
-    },
-    configurable,
-  ) as never;
+): Implementation<Step<N, typeof input, typeof HelmRelease, K>> {
+  const contract = step({
+    name: def.name,
+    description: def.description,
+    kind: "composeDeploy",
+    image: COMPOSE_DEPLOY_IMAGE,
+    input,
+    output: HelmRelease,
+    secrets: [def.token],
+    timeoutSeconds: def.timeoutSeconds,
+    settings: { target: def.target, token: def.token.name },
+  });
+  return implement(contract, async ({ image }, ctx: Ctx) => {
+    const target = resolveConfigRefs(def.target, ctx.config ?? {}) as ComposeTargetValue;
+    if (target?.kind !== "compose") throw new Error(`composeDeploy '${def.name}': the target is kind '${String(target?.kind)}', not 'compose'`);
+    if (target.token.secret !== def.token.name) throw new Error(`composeDeploy '${def.name}': the target's token names secret ${target.token.secret}, but the step declares ${def.token.name}`);
+    const token = (ctx.secrets as Record<string, string>)[def.token.name];
+    const ref = `${image.repository}@${image.digest}`;
+    const url = `${target.deployerUrl.replace(/\/+$/, "")}/v1/deploy`;
+    ctx.log("deploying", { service: target.service, image: ref, deployer: target.deployerUrl });
+    const res = await ctx.http.fetch(url, {
+      method: "POST",
+      headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+      body: JSON.stringify({ service: target.service, image: ref }),
+    });
+    const text = await res.text();
+    let result: ComposeDeployResult | undefined;
+    try {
+      result = JSON.parse(text) as ComposeDeployResult;
+    } catch {
+      // reported below
+    }
+    for (const line of result?.log ?? []) ctx.log(`deployer: ${line}`);
+    if (!res.ok || result?.status !== "deployed")
+      throw new Error(`the deployer answered HTTP ${res.status}: ${result ? `${result.status}${result.message ? `: ${result.message}` : ""}` : text.slice(0, 300)}`);
+    if (target.healthUrl) await httpHealthCheck(ctx, target.healthUrl, { attempts: 12, delaySeconds: 5 });
+    ctx.log("deployed", { service: target.service, image: ref, previous: result.previousImage ?? "-" });
+    return { release: target.service, namespace: "compose", image: ref };
+  }) as never;
 }

package/src/library/github-source.ts

@@ -8,8 +8,9 @@ import { z } from "zod";
 import type { Ctx } from "../ctx/types.ts";
 import type { Secret } from "../core/secrets.ts";
 import type { Configurable } from "../core/config.ts";
-import { recordConfigRefs, resolveConfigRefs } from "../core/config-refs.ts";
-import { makeStep, type LibraryStep, type LiteralName, type Step } from "../core/steps.ts";
+import { resolveConfigRefs } from "../core/config-refs.ts";
+import { implement, type Implementation } from "../core/handlers.ts";
+import { step, type LiteralName, type Step } from "../core/steps.ts";
 import { extractTar } from "../util/tar.ts";
 import { Source } from "./models.ts";
 
@@ -52,45 +53,48 @@ export const gitHubTarballUrl = (repo: string, sha: string, apiUrl = GITHUB_API_
  */
 export function gitHubSource<const N extends string, const T extends string = never>(
   def: GitHubSourceDef<N, T>,
-): Step<N, GitHubSourceInput, typeof Source, T> & LibraryStep {
-  return makeStep(
-    "gitHubSource",
-    { name: def.name, description: def.description, image: GITHUB_SOURCE_IMAGE, input, output: Source, secrets: def.token ? [def.token] : [], timeoutSeconds: def.timeoutSeconds },
-    {
-      manifestConfig: () => ({ ...(def.token ? { token: def.token.name } : {}), ...(def.apiUrl !== undefined ? { apiUrl: recordConfigRefs(def.apiUrl) } : {}) }),
-      async run({ repo, sha }: { repo: string; sha: string }, ctx: Ctx) {
-        const headers: Record<string, string> = { accept: "application/vnd.github+json", "user-agent": "olve-pipelines" };
-        const token = def.token ? optionalSecret(ctx, def.token.name) : "";
-        if (token) headers.authorization = `Bearer ${token}`;
-        else if (def.token) ctx.log(`${def.token.name} is not set: fetching anonymously (public repositories only)`);
-        const url = gitHubTarballUrl(repo, sha, resolveConfigRefs(def.apiUrl, ctx.config ?? {}) ?? GITHUB_API_URL);
-        mkdirSync(ctx.tmpDir, { recursive: true });
-        const dir = mkdtempSync(join(ctx.tmpDir, "github-source-"));
-        const archive = join(dir, "repo.tar.gz");
+): Implementation<Step<N, GitHubSourceInput, typeof Source, T>> {
+  const contract = step({
+    name: def.name,
+    description: def.description,
+    kind: "gitHubSource",
+    image: GITHUB_SOURCE_IMAGE,
+    input,
+    output: Source,
+    secrets: def.token ? [def.token] : [],
+    timeoutSeconds: def.timeoutSeconds,
+    settings: { ...(def.token ? { token: def.token.name } : {}), ...(def.apiUrl !== undefined ? { apiUrl: def.apiUrl } : {}) },
+  });
+  return implement(contract, async ({ repo, sha }, ctx: Ctx) => {
+    const headers: Record<string, string> = { accept: "application/vnd.github+json", "user-agent": "olve-pipelines" };
+    const token = def.token ? optionalSecret(ctx, def.token.name) : "";
+    if (token) headers.authorization = `Bearer ${token}`;
+    else if (def.token) ctx.log(`${def.token.name} is not set: fetching anonymously (public repositories only)`);
+    const url = gitHubTarballUrl(repo, sha, resolveConfigRefs(def.apiUrl, ctx.config ?? {}) ?? GITHUB_API_URL);
+    mkdirSync(ctx.tmpDir, { recursive: true });
+    const dir = mkdtempSync(join(ctx.tmpDir, "github-source-"));
+    const archive = join(dir, "repo.tar.gz");
 
-        ctx.log("fetching source", { repo, sha });
-        // Retries network errors and 5xx; a 4xx (bad sha, no access) fails at once.
-        const status = await ctx.retry({ attempts: 4, delaySeconds: 2, backoff: 2 }, async () => {
-          const res = await ctx.http.fetch(url, { headers });
-          if (res.status >= 500) throw new Error(`HTTP ${res.status} from ${url}`);
-          if (res.ok) await Bun.write(archive, res);
-          return res.status;
-        });
-        if (status < 200 || status >= 300) {
-          throw new Error(`cannot fetch ${repo}@${sha}: HTTP ${status} from ${url}${def.token ? "" : " (no token configured: a private repository needs one)"}`);
-        }
+    ctx.log("fetching source", { repo, sha });
+    // Retries network errors and 5xx; a 4xx (bad sha, no access) fails at once.
+    const status = await ctx.retry({ attempts: 4, delaySeconds: 2, backoff: 2 }, async () => {
+      const res = await ctx.http.fetch(url, { headers });
+      if (res.status >= 500) throw new Error(`HTTP ${res.status} from ${url}`);
+      if (res.ok) await Bun.write(archive, res);
+      return res.status;
+    });
+    if (status < 200 || status >= 300) {
+      throw new Error(`cannot fetch ${repo}@${sha}: HTTP ${status} from ${url}${def.token ? "" : " (no token configured: a private repository needs one)"}`);
+    }
 
-        const extracted = join(dir, "x");
-        mkdirSync(extracted);
-        await extractTar(archive, extracted);
-        // GitHub tarballs hold one top-level directory, plus a pax_global_header entry (the commit id)
-        // that some extractors materialise as a file.
-        const roots = readdirSync(extracted).filter((e) => e !== "pax_global_header" && statSync(join(extracted, e)).isDirectory());
-        if (roots.length !== 1) throw new Error(`unexpected tarball layout for ${repo}@${sha}: top-level entries ${JSON.stringify(readdirSync(extracted))}`);
-        const tree = await ctx.output.dir(join(extracted, roots[0]!), { name: "tree" });
-        return { repo, sha, tree };
-      },
-    },
-    { apiUrl: def.apiUrl },
-  ) as never;
+    const extracted = join(dir, "x");
+    mkdirSync(extracted);
+    await extractTar(archive, extracted);
+    // GitHub tarballs hold one top-level directory, plus a pax_global_header entry (the commit id)
+    // that some extractors materialise as a file.
+    const roots = readdirSync(extracted).filter((e) => e !== "pax_global_header" && statSync(join(extracted, e)).isDirectory());
+    if (roots.length !== 1) throw new Error(`unexpected tarball layout for ${repo}@${sha}: top-level entries ${JSON.stringify(readdirSync(extracted))}`);
+    const tree = await ctx.output.dir(join(extracted, roots[0]!), { name: "tree" });
+    return { repo, sha, tree };
+  }) as never;
 }

package/src/library/helm-deploy-ssh.ts

@@ -9,16 +9,15 @@ import type { Ctx } from "../ctx/types.ts";
 import type { FileRef } from "../core/models.ts";
 import type { Secret } from "../core/secrets.ts";
 import type { Configurable } from "../core/config.ts";
-import { recordConfigRefs, resolveConfigRefs } from "../core/config-refs.ts";
-import { makeStep, type LibraryStep, type LiteralName, type Step } from "../core/steps.ts";
+import { resolveConfigRefs } from "../core/config-refs.ts";
+import { implement, type Implementation } from "../core/handlers.ts";
+import { step, type LiteralName, type Step } from "../core/steps.ts";
 import type { Simplify } from "../core/types.ts";
 import { httpHealthCheck, type HttpHealthCheckOptions } from "./http-health.ts";
 import { BuiltImage, HelmRelease, PushedImage, Source } from "./models.ts";
 import { shq, sshSession } from "./ssh.ts";
 import { helmDeployOverSshTarget, type HelmDeploySshTargetDef, type HelmTargetDeployInput } from "./helm-deploy.ts";
 
-export { shq } from "./ssh.ts";
-
 /** Alpine: `apk add openssh-client` at run time gives ssh/scp (the health check runs in the harness). */
 export const HELM_DEPLOY_IMAGE = "alpine:3.22";
 
@@ -71,7 +70,7 @@ export interface HelmDeployOverSshDef<
   /**
    * The images to deploy: step input key → the chart's values prefix for that image. Each input is a
    * `BuiltImage` (or `PushedImage` with `fromRegistry`). Default `{ image: "image" }`; several images
-   * need a mapper, e.g. `{ server: "image", web: "web.image" }`.
+   * need a mapper, e.g. `{ server: "image", web: "web.image" }`. `{}` deploys the chart alone.
    */
   images?: Im & { readonly source?: never };
   /**
@@ -87,7 +86,7 @@ export interface HelmDeployOverSshDef<
    * next to tarball `images`.
    */
   imageRefs?: Rf & { readonly source?: never };
-  /** Rollouts to wait for, in order: `deploy/<name>` for a bare name. Default: the release name. */
+  /** Rollouts to wait for, in order: `deploy/<name>` for a bare name. Default: the release name, or none without images. */
   deployments?: readonly string[];
   /** Per rollout (`kubectl rollout status --timeout`). Default 120. */
   rolloutTimeoutSeconds?: number;
@@ -221,26 +220,25 @@ export function helmDeployOverSsh<
   const K extends string,
   const Im extends Record<string, string> = DefaultImages,
   const Rf extends Record<string, string> = {},
->(def: HelmDeploySshTargetDef<N, K, Im, Rf>): Step<N, HelmTargetDeployInput<Im, Rf>, typeof HelmRelease, K> & LibraryStep;
+>(def: HelmDeploySshTargetDef<N, K, Im, Rf>): Implementation<Step<N, HelmTargetDeployInput<Im, Rf>, typeof HelmRelease, K>>;
 export function helmDeployOverSsh<
   const N extends string,
   const K extends string,
   const Im extends Record<string, string> = DefaultImages,
   const R extends boolean = false,
   const Rf extends Record<string, string> = {},
->(def: HelmDeployOverSshDef<N, K, Im, R, Rf>): Step<N, HelmDeployOverSshInput<Im, R, Rf>, typeof HelmRelease, K> & LibraryStep;
+>(def: HelmDeployOverSshDef<N, K, Im, R, Rf>): Implementation<Step<N, HelmDeployOverSshInput<Im, R, Rf>, typeof HelmRelease, K>>;
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function helmDeployOverSsh(def: any): Step & LibraryStep {
+export function helmDeployOverSsh(def: any): any {
   return "target" in def ? helmDeployOverSshTarget(def) : helmDeployOverSshLiteral(def);
 }
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-function helmDeployOverSshLiteral(def: HelmDeployOverSshDef<string, string, any, boolean, any>): Step & LibraryStep {
+function helmDeployOverSshLiteral(def: HelmDeployOverSshDef<string, string, any, boolean, any>): Implementation {
   const images: Record<string, string> = def.images ?? { image: "image" };
   const imageEntries = Object.entries(images);
   const fromRegistry = def.fromRegistry === true;
   const rolloutTimeout = def.rolloutTimeoutSeconds ?? DEFAULT_ROLLOUT_TIMEOUT_SECONDS;
-  if (imageEntries.length === 0) throw new Error(`helmDeployOverSsh '${def.name}': images must not be empty`);
   if ("source" in images) throw new Error(`helmDeployOverSsh '${def.name}': 'source' can't be an image input`);
   if (def.deployments?.length === 0) throw new Error(`helmDeployOverSsh '${def.name}': deployments must not be empty`);
   const imageRefs: Record<string, string> = def.imageRefs ?? {};
@@ -256,49 +254,53 @@ function helmDeployOverSshLiteral(def: HelmDeployOverSshDef<string, string, any,
   const isDefaultImages = imageEntries.length === 1 && images.image === "image";
   const configurable = { host: def.host, release: def.release, namespace: def.namespace, values: def.values ?? [], set: def.set ?? {}, healthUrl: def.healthUrl };
 
-  return makeStep(
-    "helmDeployOverSsh",
-    { name: def.name, description: def.description, image: HELM_DEPLOY_IMAGE, input, output: HelmRelease, secrets: [def.sshKey], timeoutSeconds: def.timeoutSeconds },
-    {
-      manifestConfig: () => ({
-        host: recordConfigRefs(def.host),
-        sshKey: def.sshKey.name,
-        release: recordConfigRefs(def.release),
-        namespace: recordConfigRefs(def.namespace),
-        chart: def.chart,
-        values: recordConfigRefs(configurable.values),
-        set: recordConfigRefs(configurable.set),
-        ...(isDefaultImages ? {} : { images: { ...images } }),
-        ...(fromRegistry ? { fromRegistry: true } : {}),
-        ...(refEntries.length > 0 ? { imageRefs: { ...imageRefs } } : {}),
-        ...(def.deployments ? { deployments: [...def.deployments] } : {}),
-        ...(def.rolloutTimeoutSeconds !== undefined ? { rolloutTimeoutSeconds: def.rolloutTimeoutSeconds } : {}),
-        ...(def.healthUrl !== undefined ? { healthUrl: recordConfigRefs(def.healthUrl) } : {}),
-      }),
-      async run(input: Record<string, { repository: string; tag: string; digest: string; tar?: FileRef }> & { source: { tree: FileRef } }, ctx: Ctx) {
-        const d = resolveConfigRefs(configurable, ctx.config ?? {}) as {
-          host: string; release: string; namespace: string; values: string[]; set: Record<string, string>;
-          healthUrl?: string | ({ url: string } & Pick<HttpHealthCheckOptions, "attempts" | "delaySeconds">);
-        };
-        const chartDir = chartDirectory(await ctx.files.fetch(input.source.tree), def.chart);
-        const hostImages: HostImage[] = [];
-        const flags: HelmImageFlags[] = [];
-        for (const [key, prefix] of imageEntries) {
-          const image = input[key]!;
-          hostImages.push({ repository: image.repository, tag: image.tag, ...(fromRegistry ? {} : { tar: await ctx.files.fetch(image.tar!) }) });
-          flags.push({ prefix, repository: image.repository, tag: image.tag, pullPolicy: fromRegistry ? "IfNotPresent" : "Never" });
-        }
-        const refs: HelmImageRefFlags[] = refEntries.map(([key, prefix]) => ({ prefix, repository: input[key]!.repository, tag: input[key]!.tag, digest: input[key]!.digest }));
-        await deployOverSsh(ctx, {
-          host: d.host, key: ctx.secrets[def.sshKey.name]!, chartDir, release: d.release, namespace: d.namespace, hostImages,
-          flags: { values: d.values, set: d.set, images: flags, imageRefs: refs },
-          deployments: def.deployments ?? [d.release], rolloutTimeoutSeconds: rolloutTimeout,
-        });
-        const health = typeof d.healthUrl === "string" ? { url: d.healthUrl } : d.healthUrl;
-        if (health) await httpHealthCheck(ctx, health.url, { attempts: health.attempts, delaySeconds: health.delaySeconds });
-        return { release: d.release, namespace: d.namespace, image: `${flags[0]!.repository}:${flags[0]!.tag}` };
-      },
+  const contract = step({
+    name: def.name,
+    description: def.description,
+    kind: "helmDeployOverSsh",
+    image: HELM_DEPLOY_IMAGE,
+    input,
+    output: HelmRelease,
+    secrets: [def.sshKey],
+    timeoutSeconds: def.timeoutSeconds,
+    settings: {
+      host: def.host,
+      sshKey: def.sshKey.name,
+      release: def.release,
+      namespace: def.namespace,
+      chart: def.chart,
+      values: configurable.values,
+      set: configurable.set,
+      ...(isDefaultImages ? {} : { images: { ...images } }),
+      ...(fromRegistry ? { fromRegistry: true } : {}),
+      ...(refEntries.length > 0 ? { imageRefs: { ...imageRefs } } : {}),
+      ...(def.deployments ? { deployments: [...def.deployments] } : {}),
+      ...(def.rolloutTimeoutSeconds !== undefined ? { rolloutTimeoutSeconds: def.rolloutTimeoutSeconds } : {}),
+      ...(def.healthUrl !== undefined ? { healthUrl: def.healthUrl } : {}),
     },
-    configurable,
-  ) as never;
+  });
+  return implement(contract, async (stepInput, ctx: Ctx) => {
+    const input = stepInput as unknown as Record<string, { repository: string; tag: string; digest: string; tar?: FileRef }> & { source: { tree: FileRef } };
+    const d = resolveConfigRefs(configurable, ctx.config ?? {}) as {
+      host: string; release: string; namespace: string; values: string[]; set: Record<string, string>;
+      healthUrl?: string | ({ url: string } & Pick<HttpHealthCheckOptions, "attempts" | "delaySeconds">);
+    };
+    const chartDir = chartDirectory(await ctx.files.fetch(input.source.tree), def.chart);
+    const hostImages: HostImage[] = [];
+    const flags: HelmImageFlags[] = [];
+    for (const [key, prefix] of imageEntries) {
+      const image = input[key]!;
+      hostImages.push({ repository: image.repository, tag: image.tag, ...(fromRegistry ? {} : { tar: await ctx.files.fetch(image.tar!) }) });
+      flags.push({ prefix, repository: image.repository, tag: image.tag, pullPolicy: fromRegistry ? "IfNotPresent" : "Never" });
+    }
+    const refs: HelmImageRefFlags[] = refEntries.map(([key, prefix]) => ({ prefix, repository: input[key]!.repository, tag: input[key]!.tag, digest: input[key]!.digest }));
+    await deployOverSsh(ctx, {
+      host: d.host, key: ctx.secrets[def.sshKey.name]!, chartDir, release: d.release, namespace: d.namespace, hostImages,
+      flags: { values: d.values, set: d.set, images: flags, imageRefs: refs },
+      deployments: def.deployments ?? (imageEntries.length ? [d.release] : []), rolloutTimeoutSeconds: rolloutTimeout,
+    });
+    const health = typeof d.healthUrl === "string" ? { url: d.healthUrl } : d.healthUrl;
+    if (health) await httpHealthCheck(ctx, health.url, { attempts: health.attempts, delaySeconds: health.delaySeconds });
+    return { release: d.release, namespace: d.namespace, ...(flags[0] ? { image: `${flags[0].repository}:${flags[0].tag}` } : {}) };
+  }) as never;
 }