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

package/README.md

@@ -1,6 +1,6 @@
 # @olivervea/pipelines
 
-The [Olve.Pipelines](https://github.com/OliverVea/Olve.Pipelines) v2 SDK, imported as `@olve/pipelines`. It has four parts:
+The [Olve.Pipelines](https://github.com/OliverVea/Olve.Pipelines) v2 SDK. It has four parts:
 
 - the **authoring API**: models, steps, handlers and the typed pipeline builder;
 - the **step harness**: the runtime compiled into each pipeline's single executable (`describe`, `run`, `map-trigger`);
@@ -12,14 +12,14 @@ The manifest format is in [`manifest.schema.json`](manifest.schema.json), genera
 
 ```
 sdk/
-  src/index.ts            authoring API (`@olve/pipelines`)
+  src/index.ts            authoring API (`@olivervea/pipelines`)
   src/core/               models, secrets, steps, implement()
   src/builder/            pipeline builder (types + runtime records), Ref<T>
   src/library/            library steps (script, gitHubSource, imageBuild, helmDeployOverSsh), their exported helpers (httpHealthCheck) and SDK models
   src/describe/           describe: manifest, checks, mapper recording + source analysis, manifest schema
-  src/harness/            harness CLI modes, env contract, envelope, result upload (`@olve/pipelines/harness`)
+  src/harness/            harness CLI modes, env contract, envelope, result upload (`@olivervea/pipelines/harness`)
   src/ctx/                the ctx handed to handlers
-  src/testing/            testHandler (`@olve/pipelines/testing`)
+  src/testing/            testHandler (`@olivervea/pipelines/testing`)
   src/build/              olve-build
   src/dev/                olve-dev
   examples/self-deploy/   fixture pipeline (the self-deploy shape) used by the tests
@@ -30,13 +30,12 @@ sdk/
 
 ## Install
 
-The package is `@olivervea/pipelines` on npm; pipelines import it as `@olve/pipelines` through an alias
-in the pipeline directory's `package.json`:
+The package is `@olivervea/pipelines` on npm; a pipeline directory's `package.json` depends on it by that name:
 
 ```json
 {
   "type": "module",
-  "dependencies": { "@olve/pipelines": "npm:@olivervea/pipelines@2.0.0-beta.1" },
+  "dependencies": { "@olivervea/pipelines": "2.0.0-beta.3" },
   "devDependencies": { "@types/bun": "1.4.3", "typescript": "7.0.2" }
 }
 ```
@@ -47,11 +46,9 @@ bunx olve-dev describe .
 bunx olve-build . --out .olve/out
 ```
 
-- Keep the alias name: `olve-build` generates imports of `@olve/pipelines/harness`, so an unaliased
-  `@olivervea/pipelines` dependency does not build.
 - The package ships TypeScript sources (Bun runs them directly; `harness.sdkHash` hashes them), so the
   same version gives the same `sdkHash` and handler hashes from npm or from `file:../sdk`.
-- Inside this repo, `.pipelines/` and `.pipelines-test/` use `"@olve/pipelines": "file:../sdk"`.
+- Inside this repo, `.pipelines/` and `.pipelines-test/` use `"@olivervea/pipelines": "file:../sdk"`.
 
 ### Releases
 
@@ -67,7 +64,7 @@ A pipeline directory (the binding path, `.pipelines/` by default) looks like thi
 ```
 models.ts                 data models                         (contract file)
 pipeline.ts               steps + `export default pipeline(…)` (contract file)
-handlers/<step-name>.ts   one per custom step: `export default implement(step, fn)`
+handlers/*.ts             one per custom step: `export default implement(step, fn)` (pairs by the step, not the file name)
 handlers/lib/…            shared helpers (not handlers)
 scripts/*.sh              embedded with `import s from "../scripts/x.sh" with { type: "file" }`
 ```
@@ -77,7 +74,7 @@ Contract files hold contracts only. Describe evaluates them without loading hand
 ### Models, secrets, steps
 
 ```ts
-import { model, z, fileRef, optional, secret, step, steps, Source } from "@olve/pipelines";
+import { model, z, fileRef, optional, secret, step, steps, Source } from "@olivervea/pipelines";
 
 export const BuildArtifact = model("BuildArtifact", z.object({
   version: z.string(),
@@ -123,28 +120,38 @@ In the output JSON, an object of the form `{"$file": "<path>"}` or `{"$dir": "<p
 
 ### Library steps
 
-Library steps carry their own implementation and image; they take typed config and use the SDK models `Source`, `BuiltImage` and `HelmRelease`. The set grows from real use: a step or an option exists because a pipeline uses it.
+Library steps carry their own implementation and image; they take typed config and use the SDK models `Source`, `BuiltImage`, `PushedImage` and `HelmRelease`. The set grows from real use: a step or an option exists because a pipeline uses it.
 
 | Step | Image | Input → output | Config |
 |---|---|---|---|
 | `steps.script` | yours | yours | `script` (embedded), `env` (see above) |
 | `steps.gitHubSource` | `alpine:3.22` (work happens in the harness) | `{ repo: "owner/name", sha }` (plain schemas: needs a mapper) → `Source` | `token?: Secret` (sent as `Authorization: Bearer`; becomes the step's secret) |
-| `steps.imageBuild` | `gcr.io/kaniko-project/executor:debug` | `{ source: Source }` → `BuiltImage { repository, tag, digest, tar }` | `repository` (image name; tag = run version, `-attempt<n>` on reruns), `cacheRepo?` (kaniko layer cache), `registryMap?` (kaniko `--registry-map`: registry → mirror prefix; default: the homelab pull-through caches, `{}` = off), `stallTimeoutSeconds?` (default 300, 0 = off), `retries?` (default 2) |
-| `steps.helmDeployOverSsh` | `alpine:3.22` (+ `apk add openssh-client` at run time) | `{ source: Source, image: BuiltImage }` → `HelmRelease { release, namespace, image }` | `host` (`user@host`), `sshKey: Secret`, `release`, `namespace`, `chart` (dir in the source), `values?` (chart-relative `-f`), `set?`, `healthUrl?` |
+| `steps.imageBuild` | `gcr.io/kaniko-project/executor:debug` | `{ source: Source }` → `BuiltImage { repository, tag, digest, tar }`; with `push`: `PushedImage { repository, tag, digest }` | `repository` (image name; tag = run version, `-attempt<n>` on reruns), `context?` (dir in the source tree; default the root), `dockerfile?` (relative to the context; default `Dockerfile`), `push?` (push to `repository` instead of a tarball), `contentTag?` (with `push`: tag `src-<context hash>`, skip when the registry has it), `cacheRepo?` (kaniko layer cache), `registryMap?` (kaniko `--registry-map`: registry → mirror prefix; default: the homelab pull-through caches, `{}` = off), `stallTimeoutSeconds?` (default 300, 0 = off), `retries?` (default 2) |
+| `steps.helmDeployOverSsh` | `alpine:3.22` (+ `apk add openssh-client` at run time) | `{ source: Source, <key>: BuiltImage }` per `images` (`PushedImage` with `fromRegistry`) → `HelmRelease { release, namespace, image }` (`image`: the first image) | `host` (`user@host`), `sshKey: Secret`, `release`, `namespace`, `chart` (dir in the source), `values?` (chart-relative `-f`), `set?`, `images?` (input key → values prefix; default `{ image: "image" }`), `fromRegistry?`, `deployments?` (default `[release]`), `rolloutTimeoutSeconds?` (default 120), `healthUrl?` (URL or `{ url, attempts?, delaySeconds? }`) |
 
 - `gitHubSource` downloads `https://api.github.com/repos/<repo>/tarball/<sha>` (retrying 5xx), strips the top-level directory and outputs it as `tree`.
-- `imageBuild` copies the tree to `/kaniko/build-context` (kaniko wipes other directories between multi-stage builds), builds `Dockerfile` at the tree root with `--no-push --tar-path --digest-file`, and outputs the tarball. `repository` in the output is fully qualified the way a runtime names a loaded image (`x` → `docker.io/library/x`). A **stall watchdog** kills kaniko when it prints nothing for `stallTimeoutSeconds` (a base-image pull can stall on an idle connection at "Unpacking rootfs", and kaniko has no read timeout), failing the attempt; `retries` then starts a fresh attempt. The retry is deliberately a new pod, never a second kaniko in the same container: kaniko unpacks the base image over the container root and does not clean up when killed.
+- `imageBuild` copies the tree to `/kaniko/build-context` (kaniko wipes other directories between multi-stage builds), builds `--context=/kaniko/build-context[/<context>] --dockerfile=<that>/<dockerfile>` with `--no-push --tar-path --digest-file`, and outputs the tarball. A missing context or Dockerfile fails the step before kaniko starts. `repository` in the output is fully qualified the way a runtime names a loaded image (`x` → `docker.io/library/x`). A **stall watchdog** kills kaniko when it prints nothing for `stallTimeoutSeconds` (a base-image pull can stall on an idle connection at "Unpacking rootfs", and kaniko has no read timeout), failing the attempt; `retries` then starts a fresh attempt. The retry is deliberately a new pod, never a second kaniko in the same container: kaniko unpacks the base image over the container root and does not clean up when killed.
 - **Caches never block a build.** `registryMap` defaults to the homelab pull-through caches (`DEFAULT_REGISTRY_MAP`: `mcr.microsoft.com` → `mcr-cache.ovea.pro`, `index.docker.io` → `hub-cache.ovea.pro`; kaniko under gVisor stalls pulling from mcr.microsoft.com directly). A map you pass replaces the default; `{}` turns mapping off. Before kaniko starts, every mirror host and the `cacheRepo` registry gets a 5 s `GET https://<host>/v2/` (200 or 401 = up); one that doesn't answer is dropped with a log line (`mcr-cache.ovea.pro unreachable; pulling from mcr.microsoft.com directly`, or no `--cache` for the layer cache). After that, kaniko itself copes: it falls back to the original registry when a mirror can't serve an image's manifest (`RetrieveRemoteImage`; `--skip-default-registry-fallback` is never set), a layer-cache lookup error is a cache miss, a cache push error is a warning, and `--skip-push-permission-check` stops its startup check of the cache repo from exiting. A cache that dies mid-download (after the manifest came from it) fails or stalls the attempt; `retries` starts a fresh one, which probes again.
-- `helmDeployOverSsh` streams the image tar into the host's **k3s** containerd (`nerdctl --address /run/k3s/containerd/containerd.sock --namespace k8s.io load`), copies the chart to `/tmp/<release>-helm-<namespace>`, runs `helm upgrade --install` from inside it (values, then `set`, then `image.repository`/`image.tag`/`image.pullPolicy=Never`, which always win), waits for `kubectl rollout status deploy/<release>`, and with `healthUrl` polls it (5 × 5 s) from the harness.
+- **Registry mode** (`push: true`, for images too big for the step's ~1 GiB scratch space and Garage): kaniko runs without `--no-push`/`--tar-path`, pushes to `repository` (it must start with a registry host; pushes are anonymous) and the output is a `PushedImage` with the digest from `--digest-file`. With `contentTag`, the tag is `src-` + the first 12 hex of the sha256 of the context directory's deterministic tar (the bytes `ctx.output.dir` would write), computed from the fetched tree; an anonymous `HEAD https://<host>/v2/<path>/manifests/<tag>` that answers a `Docker-Content-Digest` skips kaniko and outputs that digest.
+- `helmDeployOverSsh` gets each image into the host's **k3s** containerd: a `BuiltImage` tar is streamed in (`nerdctl --address /run/k3s/containerd/containerd.sock --namespace k8s.io load`), a `PushedImage` (`fromRegistry`) is pulled there (`… pull -q`, so the rollout doesn't wait on the pull). It copies the chart to `/tmp/<release>-helm-<namespace>`, runs `helm upgrade --install` from inside it (values, then `set`, then per image `<prefix>.repository`/`.tag`/`.pullPolicy` — `Never` for tarballs, `IfNotPresent` for registry images — which always win), waits for `kubectl rollout status` of each of `deployments` in order (`deploy/<name>` for a bare name), and with `healthUrl` polls it (5 × 5 s unless given) from the harness. Several images (one chart, two Deployments):
+
+  ```ts
+  steps.helmDeployOverSsh({ name: "deploy-beta", description: "", host: "oliver@bulwark-m2", sshKey: SSH_PRIVATE_KEY,
+    release: "olve-slimerepublics", namespace: "apps-beta", chart: "helm",
+    images: { server: "image", web: "web.image" }, deployments: ["olve-slimerepublics-server", "olve-slimerepublics-web"] });
+  ```
 
 **Helpers.** General functions the library steps are built on, exported for custom handlers:
 
 | Helper | What it does |
 |---|---|
 | `httpHealthCheck(ctx, url, { attempts?, delaySeconds?, headers? })` | GETs `url` until it returns 2xx (redirects followed), retrying network errors and non-2xx statuses; defaults 5 attempts, 5 s apart (v1's deploy-beta loop). Throws the last error when the attempts run out. Runs in the harness, so the image needs no curl. `helmDeployOverSsh`'s `healthUrl` uses it. |
+| `serviceUrl(release)` | `http://<release>.<namespace>.svc.cluster.local` for a `HelmRelease` (charts that name the Service after the release). |
+| `checkSpa(ctx, url)` | `GET <url>/` must reference an `/assets/*.js` bundle (Vite's layout) and the bundle must be served as JavaScript; returns `{ html, bundle }` for app-specific checks. |
+| `sshSession(ctx, { host, key })` | Installs openssh-client (apk), writes the key to `<tmpDir>/ssh/id` (trailing newline, mode 600; host key not verified) and returns `{ run(remote), text(remote), copy(local, remote), shell(remote) }`; `shell` is the quoted ssh command for pipes (`ctx.sh(`printf '%s' "$V" \| ${s.shell("kubectl apply -f -")}`)`). `helmDeployOverSsh` uses it. `shq(s)` is the POSIX quoting it uses. |
 
 ```ts
-import { httpHealthCheck, implement } from "@olve/pipelines";
+import { httpHealthCheck, implement } from "@olivervea/pipelines";
 export default implement(smoke, async (_, ctx) => { await httpHealthCheck(ctx, "http://app.ns.svc.cluster.local/api/health", { attempts: 10 }); });
 ```
 
@@ -152,7 +159,7 @@ export default implement(smoke, async (_, ctx) => { await httpHealthCheck(ctx, "
 
 ```ts
 // handlers/deploy-beta.ts
-import { implement } from "@olve/pipelines";
+import { implement } from "@olivervea/pipelines";
 import { deployBeta } from "../pipeline";
 import deployScript from "../scripts/deploy.sh" with { type: "file" };
 
@@ -165,7 +172,7 @@ export default implement(deployBeta, async ({ artifact }, ctx) => {
 
 | `ctx.` | |
 |---|---|
-| `sh(cmd \| script, { env, cwd, args })`, `sh.text(…)` | Runs a command string, or an embedded script, through the image's shell. The script is copied to `$OLVE_DIR/tmp/scripts/` first. The shell is the first of `/bin/sh`, `/busybox/sh`, `/bin/bash` that exists; a shell-less image gets a clear `ShellNotFoundError`. A script's shebang is honoured when its interpreter exists. A string counts as an embedded script when it is a `/$bunfs/…` path, or an absolute path to an existing `*.sh` or `*.bash` file. Pass `{ script }` to force script mode. A non-zero exit throws a `CommandError` that carries `exitCode`. |
+| `sh(cmd \| script, { env, cwd, args })`, `sh.text(…)` | Runs a command string, or an embedded script, through the image's shell. The script is copied to `$OLVE_DIR/tmp/scripts/` first. The shell is the first of `/bin/sh`, `/busybox/sh`, `/bin/bash` that exists; a shell-less image gets a clear `ShellNotFoundError`. A script's shebang is honoured when its interpreter exists. A string counts as an embedded script when it is a `/$bunfs/…` path, or an absolute path to an existing `*.sh` or `*.bash` file. Pass `{ script }` to force script mode. `args` are the script's arguments, or `$1`, `$2`… of a command string. A non-zero exit throws a `CommandError` that carries `exitCode`. |
 | `exec([argv…], { env, cwd, idleTimeoutSeconds })` | Runs a binary directly, with no shell (works on distroless). `idleTimeoutSeconds` (also on `sh`) is an inactivity watchdog: no stdout/stderr output for that long → SIGTERM, SIGKILL 10 s later, and a `CommandStalledError`. |
 | `readText(path)`, `readJson(path)` | Paths are relative to the cwd. |
 | `files.fetch(ref)` | Downloads a file reference and verifies its sha256. Directory refs are extracted. Returns a local path. |
@@ -204,7 +211,7 @@ export default pipeline({ name: "Olve.Pipelines", description: "…", input: M.D
 ### Testing handlers
 
 ```ts
-import { testHandler, testFileRef } from "@olve/pipelines/testing";
+import { testHandler, testFileRef } from "@olivervea/pipelines/testing";
 import deployBeta from "../handlers/deploy-beta";
 
 const r = await testHandler(deployBeta, { artifact }, { secrets: { SSH_PRIVATE_KEY: "k" }, ctx: { http: fakeHttp }, run: { number: 412 } });
@@ -235,7 +242,7 @@ This section is everything the C# side needs in order to run the binary.
 
 | Path | Who | What |
 |---|---|---|
-| `input.json` | service (via olve-init) | **run**: a JSON object with exactly the step's input keys, built from the manifest's `input` mappings. Leave out a key whose ref root step was skipped; this is allowed only for `optional` inputs. Unknown keys → exit 65. **map-trigger push**: the GitHub push payload. **map-trigger poll**: `{"value": "<extracted value as string>"}`. |
+| `input.json` | service (via olve-init) | **run**: a JSON object with exactly the step's input keys, built from the manifest's `input` mappings. Leave out a key whose ref root step was skipped; this is allowed only for `optional` inputs. Unknown keys → exit 65. **map-trigger push**: `{"ref": "refs/heads/<branch>", "after": "<sha>", "repository": {"full_name": "<owner>/<repo>"}}` (`PushEvent`). **map-trigger poll**: `{"value": "<extracted value as string>"}`. **map-trigger webhook**: `{"headers": {…}, "body": …}` (`WebhookEvent`). |
 | `work/output.json` | harness | The envelope. Any stale copy is deleted at start, and the new file is written atomically. |
 | `work/files/<object path>` | harness | Output files and directory tars (see "File references"). |
 | `tmp/` | harness | Scratch space. Point `TMPDIR` here. |
@@ -330,7 +337,7 @@ Exact format: [`manifest.schema.json`](manifest.schema.json) (JSON Schema 2020-1
   An object whose only key is `ref` (with a string value) or `const` is a tag. Describe never emits a nested object with exactly that key set. Model-matched inputs are emitted already resolved (`{"ref": "build"}`).
 - **`inputTypes`** declares each input key: `{model, optional}`, or `{schema: {output, input?}}` for a plain schema.
 - **`handlerHash`** is the step's implementation identity. A step version can be computed from image + `inputTypes`/model versions + `output` model version + `secrets` + `input` mappings + `handlerHash`. Stage placement, `when` and the step's `description` are not part of it.
-  - Custom steps: `sha256(canonical {bundle, harness})`. `bundle` hashes the handler bundled on its own, with `pipeline.ts`, `models.ts` and `@olve/pipelines` external. It is tree-shaken and includes embedded scripts, so it changes only when that handler's code (or code it uses) changes.
+  - Custom steps: `sha256(canonical {bundle, harness})`. `bundle` hashes the handler bundled on its own, with `pipeline.ts`, `models.ts` and `@olivervea/pipelines` external. It is tree-shaken and includes embedded scripts, so it changes only when that handler's code (or code it uses) changes.
   - Library steps: `sha256(canonical {library: kind, config, harness})`.
   - Because `harness` is part of both hashes, a Bun or SDK bump changes every handler.
 - **`stages`** is an array whose items are either `{steps: [Step…]}` (parallel, with a barrier) or `{when: {field: [values]}, stages: [...]}`.
@@ -360,7 +367,7 @@ olve-build <pipelineDir> --out <dir> [--target bun-linux-x64|bun-linux-x64-musl]
 olve-build <pipelineDir> --hash-only          # print handler hashes (diagnostics)
 ```
 
-1. Hash every `handlers/*.ts` (see `handlerHash`).
+1. Pair each `handlers/*.ts` with the step its `implement(step, …)` names, and hash it (see `handlerHash`).
 2. Generate `<pipelineDir>/.olve/gen/handlers.ts` (a registry of literal `import()` paths, plus hashes and harness info) and `entry.ts`. Add `.olve/` to `.gitignore`.
 3. Run `bun build --compile --target=bun-linux-x64 --no-compile-autoload-dotenv --no-compile-autoload-bunfig --bytecode --format=esm` → `<out>/step`. The output is never minified, because mapper source analysis needs real source.
 4. Check that `PT_INTERP` is `/lib64/ld-linux-x86-64.so.2`. On alpine, Bun silently produces a musl binary; the check fails it.
@@ -378,9 +385,9 @@ bun install --frozen-lockfile
 bunx olve-build .pipelines --out /work/out --upload-url "$STEP_PUT_URL" --sentinels
 ```
 
-From npm (the alias), nothing else is needed. A local `file:`/`link:` dependency (`"@olve/pipelines": "file:../sdk"`, as Olve.Pipelines' own `.pipelines/` does) resolves to its **source directory**, not the copy in `node_modules`, so its own dependencies must be installed there too: the build Job runs `bun install --frozen-lockfile --production` in every local dependency of the binding's `package.json` that is inside the repo, before building.
+From npm, nothing else is needed. A local `file:`/`link:` dependency (`"@olivervea/pipelines": "file:../sdk"`, as Olve.Pipelines' own `.pipelines/` does) resolves to its **source directory**, not the copy in `node_modules`, so its own dependencies must be installed there too: the build Job runs `bun install --frozen-lockfile --production` in every local dependency of the binding's `package.json` that is inside the repo, before building.
 
-The repo depends on the SDK as a normal package. It resolves through `exports` (`@olve/pipelines`, `@olve/pipelines/harness`, `@olve/pipelines/testing`), and the tests cover this with a `file:` install. `bun` must be on `PATH`, because the bins use `#!/usr/bin/env bun`. A consumer `tsconfig.json` has to include the dot-directory explicitly (`"include": [".pipelines/**/*.ts"]`), and should exclude `.pipelines/.olve`.
+The repo depends on the SDK as a normal package. It resolves through `exports` (`@olivervea/pipelines`, `@olivervea/pipelines/harness`, `@olivervea/pipelines/testing`), and the tests cover this with a `file:` install. `bun` must be on `PATH`, because the bins use `#!/usr/bin/env bun`. A consumer `tsconfig.json` has to include the dot-directory explicitly (`"include": [".pipelines/**/*.ts"]`), and should exclude `.pipelines/.olve`.
 
 How the service runs it (reconcile, `BuildJobBuilder`): one Job per (pipeline, config commit), named `olve-build-<pipeline12>-<sha12>`. The repo tarball comes from `codeload.github.com/<repo>/tar.gz/<sha>` anonymously (public repos), or from the GitHub API tarball endpoint with the binding's credentials key from the pipeline Secret. The binary is PUT to `versions/<pipeline>/builds/<sha>/step.tar.gz`, and a version added from that build keeps this key as its `BinaryKey`. The in-repo fixture `.pipelines-test/` (bound on v2 beta) uses exactly this layout.
 

package/manifest.schema.json

@@ -92,7 +92,7 @@
               "type": "string"
             },
             "sdk": {
-              "description": "@olve/pipelines package version.",
+              "description": "@olivervea/pipelines package version.",
               "type": "string"
             },
             "sdkHash": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olivervea/pipelines",
-  "version": "2.0.0-beta.2",
+  "version": "2.0.0-beta.3",
   "description": "Olve.Pipelines v2 SDK: typed pipeline authoring, the step harness, and the build tool.",
   "type": "module",
   "license": "MIT",

package/src/build/build.ts

@@ -48,7 +48,7 @@ export function generateEntry(project: Project, hashes: Record<string, string>,
   writeFileSync(
     join(gen, "handlers.ts"),
     `// GENERATED by olve-build — do not edit.\n` +
-      `import type { HandlerRegistry, HarnessInfo } from "@olve/pipelines/harness";\n\n` +
+      `import type { HandlerRegistry, HarnessInfo } from "@olivervea/pipelines/harness";\n\n` +
       `export const handlers: HandlerRegistry = {\n${registry}\n};\n\n` +
       `export const handlerHashes: Record<string, string> = ${JSON.stringify(hashes, null, 2)};\n\n` +
       `export const harness: HarnessInfo = ${JSON.stringify(harness, null, 2)};\n`,
@@ -58,7 +58,7 @@ export function generateEntry(project: Project, hashes: Record<string, string>,
     entry,
     `// GENERATED by olve-build — do not edit. Entry point of the step binary.\n` +
       `import pipeline from ${JSON.stringify(relPosix(gen, project.pipelineFile))};\n` +
-      `import { runHarness } from "@olve/pipelines/harness";\n` +
+      `import { runHarness } from "@olivervea/pipelines/harness";\n` +
       `import { handlers, handlerHashes, harness } from "./handlers.ts";\n\n` +
       `process.exit(await runHarness({ pipeline, handlers, handlerHashes, harness }, process.argv.slice(2)));\n`,
   );
@@ -69,7 +69,7 @@ export async function build(dir: string, opts: BuildOptions): Promise<BuildResul
   const log = opts.log ?? ((l: string) => process.stderr.write(l + "\n"));
   const stdout = opts.stdout ?? (async (t: string) => void (await Bun.write(Bun.stdout, t)));
   const target = opts.target ?? "bun-linux-x64";
-  const project = loadProject(dir);
+  const project = await loadProject(dir);
   const out = resolve(opts.out);
   mkdirSync(out, { recursive: true });
   const harness = harnessInfo();

package/src/build/cli.ts

@@ -32,7 +32,7 @@ async function main(): Promise<number> {
   const dir = positionals[0]!;
   try {
     if (values["hash-only"]) {
-      const h = await handlerHashes(loadProject(dir), harnessInfo());
+      const h = await handlerHashes(await loadProject(dir), harnessInfo());
       await Bun.write(Bun.stdout, canonicalJson({ harness: harnessInfo(), handlers: h }));
       return 0;
     }

package/src/build/hashes.ts

@@ -22,7 +22,7 @@ function externals(project: Project): BunPlugin {
   return {
     name: "olve-handler-hash-externals",
     setup(b) {
-      b.onResolve({ filter: /^@olve\/pipelines(\/.*)?$/ }, (args) => ({ path: args.path, external: true }));
+      b.onResolve({ filter: /^@olivervea\/pipelines(\/.*)?$/ }, (args) => ({ path: args.path, external: true }));
       b.onResolve({ filter: /^\.{1,2}\// }, (args) => {
         const base = resolve(dirname(args.importer), args.path);
         for (const cand of [base, `${base}.ts`, join(base, "index.ts")]) if (contracts.has(cand)) return { path: args.path, external: true };

package/src/build/project.ts

@@ -1,6 +1,7 @@
 // Layout of a pipeline directory and the identity of the SDK building it.
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
+import { isImplementation } from "../core/handlers.ts";
 import { sha256Hex } from "../util/hash.ts";
 import type { HarnessInfo } from "../util/handler-hash.ts";
 
@@ -11,7 +12,7 @@ export interface Project {
   pipelineFile: string;
   /** Contract files (excluded from handler bundles): pipeline.ts, models.ts. */
   contractFiles: string[];
-  /** step name → absolute handler file, sorted by name. */
+  /** step name → absolute handler file, sorted by step name. The step is the one the file's `implement(step, …)` names. */
   handlers: [string, string][];
 }
 
@@ -19,20 +20,40 @@ export class ProjectError extends Error {
   override name = "ProjectError";
 }
 
-export function loadProject(dirArg: string): Project {
+export async function loadProject(dirArg: string): Promise<Project> {
   const dir = resolve(dirArg);
   if (!existsSync(dir) || !statSync(dir).isDirectory()) throw new ProjectError(`${dirArg} is not a directory`);
   const pipelineFile = join(dir, "pipeline.ts");
   if (!existsSync(pipelineFile)) throw new ProjectError(`${join(dirArg, "pipeline.ts")} not found (it must default-export pipeline({...}))`);
   const contractFiles = ["pipeline.ts", "models.ts"].map((f) => join(dir, f)).filter((f) => existsSync(f));
   const hdir = join(dir, "handlers");
-  const handlers: [string, string][] = existsSync(hdir)
+  const files = existsSync(hdir)
     ? readdirSync(hdir)
         .filter((f) => f.endsWith(".ts") && !f.endsWith(".test.ts") && !f.endsWith(".d.ts") && statSync(join(hdir, f)).isFile())
         .sort()
-        .map((f) => [f.slice(0, -3), join(hdir, f)])
     : [];
-  return { dir, pipelineFile, contractFiles, handlers };
+  return { dir, pipelineFile, contractFiles, handlers: await resolveHandlers(hdir, files) };
+}
+
+/** Pairs each handler file with the step its default export implements (file names don't matter). */
+async function resolveHandlers(hdir: string, files: string[]): Promise<[string, string][]> {
+  const byStep = new Map<string, string>();
+  for (const f of files) {
+    const file = join(hdir, f);
+    let impl: unknown;
+    try {
+      impl = ((await import(file)) as { default?: unknown }).default;
+    } catch (e) {
+      throw new ProjectError(`handlers/${f} failed to load: ${(e as Error)?.message ?? String(e)}`);
+    }
+    if (!isImplementation(impl))
+      throw new ProjectError(`handlers/${f} must default-export implement(<step>, …); put shared code in a subfolder such as handlers/lib/`);
+    const step = (impl.step as { name: string }).name;
+    const other = byStep.get(step);
+    if (other) throw new ProjectError(`handlers/${other.slice(hdir.length + 1)} and handlers/${f} both implement step '${step}'`);
+    byStep.set(step, file);
+  }
+  return [...byStep].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
 }
 
 function listFiles(dir: string): string[] {

package/src/builder/pipeline.ts

@@ -178,6 +178,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 +208,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 +249,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 +261,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 +286,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 +294,10 @@ 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();
   }
 
   /** Run `handler` (a step whose inputs are all FailureContext) when one of `steps` (default: any) fails. Untracked, best-effort. */
@@ -295,7 +310,7 @@ export class Pipeline<In extends AnyModel, A extends AvailMap> {
     opts?: { steps?: readonly Step<StepNames<A>, 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/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/describe/describe.ts

@@ -20,7 +20,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>>;
@@ -198,7 +198,7 @@ export function describePipeline(pipeline: unknown, opts: DescribeOptions): Mani
     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) {
@@ -329,11 +329,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 ──

package/src/describe/manifest-schema.ts

@@ -117,7 +117,7 @@ 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."),

package/src/dev/cli.ts

@@ -17,7 +17,7 @@ const USAGE = `usage: olve-dev describe <dir> [--sentinels]
        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();

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

@@ -77,17 +77,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;
 }
 

package/src/index.ts

@@ -1,5 +1,5 @@
 /// <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";
@@ -9,4 +9,4 @@ export { implement, type Implementation, type Handler, type HandlerResult, type
 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 HelmDeployOverSshDef, httpHealthCheck, type HttpHealthCheckOptions, sshSession, shq, type SshSession, serviceUrl, checkSpa } from "./library/index.ts";

package/src/library/checks.ts

@@ -0,0 +1,23 @@
+// Checks for deployed apps, used from custom test handlers.
+import type { Ctx } from "../ctx/types.ts";
+
+/** The in-cluster URL of a release's Service, assuming the chart names it after the release. */
+export function serviceUrl(release: { release: string; namespace: string }): string {
+  return `http://${release.release}.${release.namespace}.svc.cluster.local`;
+}
+
+/**
+ * Checks `url` serves a single-page app: `GET <url>/` references a `/assets/*.js` bundle (Vite's
+ * layout), and the bundle is served as JavaScript. Returns the page, for app-specific checks.
+ */
+export async function checkSpa(ctx: Pick<Ctx, "http" | "log">, url: string): Promise<{ html: string; bundle: string }> {
+  const base = url.replace(/\/$/, "");
+  const html = await (await ctx.http.expectOk(`${base}/`)).text();
+  const bundle = html.match(/src="(\/assets\/[^"]+\.js)"/)?.[1];
+  if (bundle === undefined) throw new Error(`${base}/ does not reference an /assets/*.js bundle`);
+  const js = await ctx.http.expectOk(`${base}${bundle}`);
+  await js.body?.cancel().catch(() => {});
+  if (!(js.headers.get("content-type")?.includes("javascript") ?? false)) throw new Error(`${base}${bundle} is not served as JavaScript`);
+  ctx.log("SPA served", { url: base, bundle });
+  return { html, bundle };
+}

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

@@ -1,16 +1,20 @@
-// steps.helmDeployOverSsh — import a built image into a k3s host's containerd and helm-upgrade a
-// release there, over SSH; optionally verify an HTTP health endpoint afterwards.
+// steps.helmDeployOverSsh — get built images onto a k3s host and helm-upgrade a release there, over
+// SSH; optionally verify an HTTP health endpoint afterwards.
 //
 // Ported from v1's olve-lib.sh (olve_ssh_host, olve_image_import, olve_helm_deploy) and
 // deploy-beta.sh (rollout wait + health loop); the footguns are kept as comments below.
-import { chmodSync, existsSync, mkdirSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, statSync } from "node:fs";
 import { join } from "node:path";
 import type { Ctx } from "../ctx/types.ts";
 import type { FileRef } from "../core/models.ts";
 import type { Secret } from "../core/secrets.ts";
 import { makeStep, type LibraryStep, type LiteralName, type Step } from "../core/steps.ts";
-import { httpHealthCheck } from "./http-health.ts";
-import { BuiltImage, HelmRelease, Source } from "./models.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";
+
+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";
@@ -20,13 +24,18 @@ export const HELM_DEPLOY_IMAGE = "alpine:3.22";
  * the k3s instance's `k8s.io` namespace (otherwise pods fail with ErrImageNeverPull).
  */
 export const K3S_IMAGE_IMPORT = "sudo nerdctl --address /run/k3s/containerd/containerd.sock --namespace k8s.io load";
+/** Registry images are pulled the same way before the rollout, so the rollout doesn't wait on the pull. */
+export const K3S_IMAGE_PULL = "sudo nerdctl --address /run/k3s/containerd/containerd.sock --namespace k8s.io pull -q";
 
-const ROLLOUT_TIMEOUT = "120s";
+export const DEFAULT_ROLLOUT_TIMEOUT_SECONDS = 120;
 
-const input = { source: Source, image: BuiltImage };
-export type HelmDeployOverSshInput = typeof input;
+type DefaultImages = { readonly image: "image" };
+type ImageModel<R extends boolean> = R extends true ? typeof PushedImage : typeof BuiltImage;
+export type HelmDeployOverSshInput<Im extends Record<string, string> = DefaultImages, R extends boolean = false> = Simplify<
+  { readonly source: typeof Source } & { readonly [K in keyof Im]: ImageModel<R> }
+>;
 
-export interface HelmDeployOverSshDef<N extends string, K extends string> {
+export interface HelmDeployOverSshDef<N extends string, K extends string, Im extends Record<string, string> = DefaultImages, R extends boolean = false> {
   name: LiteralName<N>;
   /** What the step does, shown in the UI. Required; may be empty. */
   description: string;
@@ -34,7 +43,7 @@ export interface HelmDeployOverSshDef<N extends string, K extends string> {
   host: string;
   /** Private key for `host`. */
   sshKey: Secret<K>;
-  /** Helm release name; the chart's Deployment is expected to be named the same (rollout wait). */
+  /** Helm release name. */
   release: string;
   namespace: string;
   /** Chart directory inside the source tree, e.g. `helm`. */
@@ -42,19 +51,36 @@ export interface HelmDeployOverSshDef<N extends string, K extends string> {
   /** Values files, relative to the chart directory (`-f`, in order). */
   values?: readonly string[];
   /**
-   * Chart-specific `--set` flags (e.g. `{ "slo.enabled": "false" }`). The image flags are added by
-   * the step and always win: `image.repository`, `image.tag`, `image.pullPolicy=Never`.
+   * Chart-specific `--set` flags (e.g. `{ "ingress.enabled": "false" }`). The image flags are added by
+   * the step and always win: `<prefix>.repository`, `<prefix>.tag`, `<prefix>.pullPolicy`.
    */
   set?: Readonly<Record<string, string>>;
-  /** After the rollout, GET this URL until it returns 2xx, 5 × 5 s (`httpHealthCheck`), or fail the step. */
-  healthUrl?: string;
+  /**
+   * 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" }`.
+   */
+  images?: Im & { readonly source?: never };
+  /**
+   * The images are `PushedImage`s from a registry (`imageBuild` with `push`): pulled on the host
+   * first, then `pullPolicy=IfNotPresent`. Default: `BuiltImage` tarballs, imported on the host, then
+   * `pullPolicy=Never`.
+   */
+  fromRegistry?: R & (boolean extends R ? "❌ fromRegistry must be a literal true or false (use `as const` on a shared config object)" : unknown);
+  /** Rollouts to wait for, in order: `deploy/<name>` for a bare name. Default: the release name. */
+  deployments?: readonly string[];
+  /** Per rollout (`kubectl rollout status --timeout`). Default 120. */
+  rolloutTimeoutSeconds?: number;
+  /** After the rollouts, GET this URL until it returns 2xx (`httpHealthCheck`: 5 × 5 s unless given), or fail the step. */
+  healthUrl?: string | ({ url: string } & Pick<HttpHealthCheckOptions, "attempts" | "delaySeconds">);
   timeoutSeconds?: number;
 }
 
-const SAFE = /^[A-Za-z0-9_\/.:=@%+,-]+$/;
-/** POSIX shell quoting (safe words are left bare, so logs stay readable). */
-export function shq(s: string): string {
-  return SAFE.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`;
+export interface HelmImageFlags {
+  prefix: string;
+  repository: string;
+  tag: string;
+  pullPolicy: "Never" | "IfNotPresent";
 }
 
 /** Remote `helm upgrade --install`, run from inside the copied chart directory. */
@@ -64,18 +90,18 @@ export function helmUpgradeCommand(o: {
   namespace: string;
   values: readonly string[];
   set: Readonly<Record<string, string>>;
-  repository: string;
-  tag: string;
+  images: readonly HelmImageFlags[];
 }): string {
   // Chart-relative values paths (`-f values-beta.yaml`) resolve because helm runs from inside the
-  // copied chart dir. Extra flags come before the image flags, so the image overrides win. The image
-  // is local to the node (imported above), never pulled: pullPolicy=Never.
+  // copied chart dir. Extra flags come before the image flags, so the image overrides win.
   const flags = [
     ...o.values.flatMap((v) => ["-f", v]),
     ...Object.entries(o.set).flatMap(([k, v]) => ["--set", `${k}=${v}`]),
-    "--set", `image.repository=${o.repository}`,
-    "--set", `image.tag=${o.tag}`,
-    "--set", "image.pullPolicy=Never",
+    ...o.images.flatMap((i) => [
+      "--set", `${i.prefix}.repository=${i.repository}`,
+      "--set", `${i.prefix}.tag=${i.tag}`,
+      "--set", `${i.prefix}.pullPolicy=${i.pullPolicy}`,
+    ]),
   ];
   return [
     `cd ${shq(o.remoteChart)}`,
@@ -85,15 +111,31 @@ export function helmUpgradeCommand(o: {
 }
 
 /**
- * Deploys `image` with the Helm chart at `<source>/<chart>` on a k3s host over SSH:
- * stream the image tar into the host's k3s containerd, copy the chart, `helm upgrade --install`,
- * wait for `deploy/<release>` to roll out, then (with `healthUrl`) poll the health endpoint.
+ * Deploys images with the Helm chart at `<source>/<chart>` on a k3s host over SSH: get each image
+ * into the host's k3s containerd (stream a tarball in, or pull from the registry), copy the chart,
+ * `helm upgrade --install`, wait for each rollout, then (with `healthUrl`) poll the health endpoint.
  */
-export function helmDeployOverSsh<const N extends string, const K extends string>(
-  def: HelmDeployOverSshDef<N, K>,
-): Step<N, HelmDeployOverSshInput, typeof HelmRelease, K> & LibraryStep {
+export function helmDeployOverSsh<
+  const N extends string,
+  const K extends string,
+  const Im extends Record<string, string> = DefaultImages,
+  const R extends boolean = false,
+>(def: HelmDeployOverSshDef<N, K, Im, R>): Step<N, HelmDeployOverSshInput<Im, R>, typeof HelmRelease, K> & LibraryStep {
   const values = def.values ?? [];
   const set = def.set ?? {};
+  const images: Record<string, string> = def.images ?? { image: "image" };
+  const imageEntries = Object.entries(images);
+  const fromRegistry = def.fromRegistry === true;
+  const deployments = def.deployments ?? [def.release];
+  const rolloutTimeout = def.rolloutTimeoutSeconds ?? DEFAULT_ROLLOUT_TIMEOUT_SECONDS;
+  const health = typeof def.healthUrl === "string" ? { url: def.healthUrl } : def.healthUrl;
+  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 (deployments.length === 0) throw new Error(`helmDeployOverSsh '${def.name}': deployments must not be empty`);
+  const imageModel = fromRegistry ? PushedImage : BuiltImage;
+  const input = { source: Source, ...Object.fromEntries(imageEntries.map(([key]) => [key, imageModel])) };
+  const isDefaultImages = imageEntries.length === 1 && images.image === "image";
+
   return makeStep(
     "helmDeployOverSsh",
     { name: def.name, description: def.description, image: HELM_DEPLOY_IMAGE, input, output: HelmRelease, secrets: [def.sshKey], timeoutSeconds: def.timeoutSeconds },
@@ -106,45 +148,48 @@ export function helmDeployOverSsh<const N extends string, const K extends string
         chart: def.chart,
         values: [...values],
         set: { ...set },
-        ...(def.healthUrl ? { healthUrl: def.healthUrl } : {}),
+        ...(isDefaultImages ? {} : { images: { ...images } }),
+        ...(fromRegistry ? { fromRegistry: true } : {}),
+        ...(def.deployments ? { deployments: [...def.deployments] } : {}),
+        ...(def.rolloutTimeoutSeconds !== undefined ? { rolloutTimeoutSeconds: def.rolloutTimeoutSeconds } : {}),
+        ...(def.healthUrl !== undefined ? { healthUrl: typeof def.healthUrl === "string" ? def.healthUrl : { ...def.healthUrl } } : {}),
       }),
-      async run(
-        { source, image }: { source: { tree: FileRef }; image: { repository: string; tag: string; tar: FileRef } },
-        ctx: Ctx,
-      ) {
-        const tree = await ctx.files.fetch(source.tree);
+      async run(input: Record<string, { repository: string; tag: string; tar?: FileRef }> & { source: { tree: FileRef } }, ctx: Ctx) {
+        const tree = await ctx.files.fetch(input.source.tree);
         const chartDir = join(tree, def.chart);
         if (!existsSync(chartDir) || !statSync(chartDir).isDirectory()) throw new Error(`chart directory '${def.chart}' not found in the source tree`);
-        const imageTar = await ctx.files.fetch(image.tar);
-
-        // SSH setup. The key file needs a trailing newline (OpenSSH rejects the key otherwise) and
-        // mode 600. The host key is not verified (as in v1): the host is reached over the tailnet.
-        await ctx.exec(["apk", "add", "--no-cache", "openssh-client"]);
-        const sshDir = join(ctx.tmpDir, "ssh");
-        mkdirSync(sshDir, { recursive: true, mode: 0o700 });
-        const keyFile = join(sshDir, "id");
-        const key = ctx.secrets[def.sshKey.name]!;
-        writeFileSync(keyFile, key.endsWith("\n") ? key : key + "\n", { mode: 0o600 });
-        chmodSync(keyFile, 0o600);
-        const opts = ["-i", keyFile, "-o", "StrictHostKeyChecking=no", "-o", "UserKnownHostsFile=/dev/null", "-o", "LogLevel=ERROR", "-o", "BatchMode=yes"];
-        const ssh = (remote: string) => ctx.exec(["ssh", ...opts, def.host, remote]);
 
-        const ref = `${image.repository}:${image.tag}`;
-        ctx.log("importing image", { image: ref, host: def.host });
-        // Streamed over ssh's stdin (ctx.exec has none, hence the shell redirect).
-        await ctx.sh(["ssh", ...opts, def.host, K3S_IMAGE_IMPORT].map(shq).join(" ") + ` < ${shq(imageTar)}`);
+        const ssh = await sshSession(ctx, { host: def.host, key: ctx.secrets[def.sshKey.name]! });
+        const flags: HelmImageFlags[] = [];
+        for (const [key, prefix] of imageEntries) {
+          const image = input[key]!;
+          const ref = `${image.repository}:${image.tag}`;
+          if (fromRegistry) {
+            ctx.log("pulling image", { image: ref, host: def.host });
+            await ssh.run(`${K3S_IMAGE_PULL} ${shq(ref)}`);
+          } else {
+            const tar = await ctx.files.fetch(image.tar!);
+            ctx.log("importing image", { image: ref, host: def.host });
+            // Streamed over ssh's stdin (ctx.exec has none, hence the shell redirect).
+            await ctx.sh(`${ssh.shell(K3S_IMAGE_IMPORT)} < ${shq(tar)}`);
+          }
+          flags.push({ prefix, repository: image.repository, tag: image.tag, pullPolicy: fromRegistry ? "IfNotPresent" : "Never" });
+        }
 
         const remoteChart = `/tmp/${def.release}-helm-${def.namespace}`;
-        ctx.log("helm upgrade", { release: def.release, namespace: def.namespace, image: ref });
-        await ssh(`rm -rf ${shq(remoteChart)}`);
-        await ctx.exec(["scp", ...opts, "-r", chartDir, `${def.host}:${remoteChart}`]);
-        await ssh(helmUpgradeCommand({ remoteChart, release: def.release, namespace: def.namespace, values, set, repository: image.repository, tag: image.tag }));
+        ctx.log("helm upgrade", { release: def.release, namespace: def.namespace, images: flags.map((f) => `${f.repository}:${f.tag}`).join(" ") });
+        await ssh.run(`rm -rf ${shq(remoteChart)}`);
+        await ssh.copy(chartDir, remoteChart);
+        await ssh.run(helmUpgradeCommand({ remoteChart, release: def.release, namespace: def.namespace, values, set, images: flags }));
 
-        ctx.log("waiting for rollout", { deployment: def.release });
-        await ssh(`kubectl -n ${shq(def.namespace)} rollout status ${shq(`deploy/${def.release}`)} --timeout=${ROLLOUT_TIMEOUT}`);
+        for (const d of deployments) {
+          const target = d.includes("/") ? d : `deploy/${d}`;
+          ctx.log("waiting for rollout", { deployment: target });
+          await ssh.run(`kubectl -n ${shq(def.namespace)} rollout status ${shq(target)} --timeout=${rolloutTimeout}s`);
+        }
 
-        if (def.healthUrl) await httpHealthCheck(ctx, def.healthUrl);
-        return { release: def.release, namespace: def.namespace, image: ref };
+        if (health) await httpHealthCheck(ctx, health.url, { attempts: health.attempts, delaySeconds: health.delaySeconds });
+        return { release: def.release, namespace: def.namespace, image: `${flags[0]!.repository}:${flags[0]!.tag}` };
       },
     },
   ) as never;

package/src/library/image-build.ts

@@ -1,13 +1,14 @@
-// steps.imageBuild — build a container image from a `Source` with kaniko, to an image tarball.
-//
-// No registry push: the tarball travels as a file ref and a deploy step imports it on the host.
+// steps.imageBuild — build a container image from a `Source` with kaniko: to an image tarball that
+// travels as a file ref (a deploy imports it on the host), or pushed to a registry (`push: true`).
 // Ported from v1's olve-lib.sh (olve_kaniko_build + build.sh's layer cache); footguns kept below.
-import { mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync } from "node:fs";
 import { join } from "node:path";
 import type { Ctx, RunInfo } from "../ctx/types.ts";
 import type { FileRef } from "../core/models.ts";
 import { makeStep, type LibraryStep, type LiteralName, type Step } from "../core/steps.ts";
-import { BuiltImage, Source } from "./models.ts";
+import { sha256File } from "../util/hash.ts";
+import { dirEntries, writeTar } from "../util/tar.ts";
+import { BuiltImage, PushedImage, Source } from "./models.ts";
 
 /** kaniko's debug image (it has a busybox shell for debugging; the executor itself needs none). */
 export const KANIKO_IMAGE = "gcr.io/kaniko-project/executor:debug";
@@ -26,8 +27,15 @@ export interface ImageBuildDef<N extends string> {
   name: LiteralName<N>;
   /** What the step does, shown in the UI. Required; may be empty. */
   description: string;
-  /** Image name, e.g. `olve-pipelines-v2`. The tag is the run's version (see `imageTag`). */
+  /**
+   * Image name, e.g. `olve-pipelines-v2`; with `push`, the registry repository to push to
+   * (`registry.ovea.pro/app/api`). The tag is the run's version (see `imageTag`) unless `contentTag`.
+   */
   repository: string;
+  /** Build context: a directory of the source tree (default: the root). */
+  context?: string;
+  /** Dockerfile path, relative to the context (default `Dockerfile`). */
+  dockerfile?: string;
   /**
    * Registry repository for kaniko's layer cache (`--cache=true --cache-repo=…`), so unchanged
    * layers (restore, apt, npm, …) are reused. kaniko pushes cache layers even with `--no-push`.
@@ -56,6 +64,25 @@ export interface ImageBuildDef<N extends string> {
   retries?: number;
 }
 
+/** Tarball mode (default): output `BuiltImage` with the image tar as a file. */
+export interface ImageBuildTarballDef<N extends string> extends ImageBuildDef<N> {
+  push?: false;
+  contentTag?: never;
+}
+
+/**
+ * Registry mode: push to `repository` and output `PushedImage`, for images too big to travel as a
+ * tarball (the step's scratch space is ~1 GiB).
+ */
+export interface ImageBuildPushDef<N extends string> extends ImageBuildDef<N> {
+  push: true;
+  /**
+   * Tag the image `src-<hash>`, the hash of the build context's content, and skip the build when the
+   * registry already has that tag: the image is rebuilt only when its context changes.
+   */
+  contentTag?: boolean;
+}
+
 /**
  * Default `registryMap`: pull-through caches for mcr.microsoft.com and Docker Hub. kaniko under gVisor
  * can stall forever pulling from mcr.microsoft.com directly.
@@ -132,28 +159,91 @@ export function qualifyRepository(repository: string): string {
   return `docker.io/${repository}`;
 }
 
+/** A relative path inside the source tree (no `..`, not absolute). */
+function checkRelative(what: string, path: string): string {
+  const clean = path.replace(/^\.\/+/, "").replace(/\/+$/, "");
+  if (clean.startsWith("/") || clean.split("/").includes("..")) throw new Error(`imageBuild ${what} '${path}' must be a relative path inside the source tree`);
+  return clean === "." ? "" : clean;
+}
+
+/** The `src-<12 hex>` tag of a directory: the sha256 of its deterministic tar (as `ctx.output.dir` writes it). */
+export function contentTagOf(dir: string, tmpDir: string): string {
+  mkdirSync(tmpDir, { recursive: true });
+  const work = mkdtempSync(join(tmpDir, "content-tag-"));
+  try {
+    const tar = join(work, "context.tar");
+    writeTar(tar, dirEntries(dir));
+    return `src-${sha256File(tar).slice(0, 12)}`;
+  } finally {
+    rmSync(work, { recursive: true, force: true });
+  }
+}
+
+const MANIFEST_TYPES = [
+  "application/vnd.oci.image.index.v1+json",
+  "application/vnd.oci.image.manifest.v1+json",
+  "application/vnd.docker.distribution.manifest.list.v2+json",
+  "application/vnd.docker.distribution.manifest.v2+json",
+].join(", ");
+
+/** The digest of `repository:tag` in its registry (anonymous `HEAD …/manifests/<tag>`), or undefined if it has none. */
+export async function registryDigest(http: Ctx["http"], repository: string, tag: string): Promise<string | undefined> {
+  const [host, ...path] = repository.split("/");
+  const res = await http.fetch(`https://${host}/v2/${path.join("/")}/manifests/${tag}`, { method: "HEAD", headers: { Accept: MANIFEST_TYPES } });
+  await res.body?.cancel().catch(() => {});
+  if (res.status === 404) return undefined;
+  if (!res.ok) throw new Error(`registry lookup of ${repository}:${tag} answered HTTP ${res.status}`);
+  const digest = res.headers.get("docker-content-digest") ?? "";
+  return /^sha256:[0-9a-f]{64}$/.test(digest) ? digest : undefined;
+}
+
 /**
- * Builds `<source>/Dockerfile` with the source root as context, using kaniko, into an image tarball.
- * Output: `BuiltImage { repository, tag, digest, tar }`.
+ * Builds an image with kaniko from `<context>/<dockerfile>` in the source tree (default: `Dockerfile`
+ * at the root). Default: into an image tarball, output `BuiltImage { repository, tag, digest, tar }`.
+ * With `push: true`: pushed to `repository`, output `PushedImage { repository, tag, digest }`.
  */
-export function imageBuild<const N extends string>(def: ImageBuildDef<N>): Step<N, ImageBuildInput, typeof BuiltImage, never> & LibraryStep {
+export function imageBuild<const N extends string>(def: ImageBuildTarballDef<N>): Step<N, ImageBuildInput, typeof BuiltImage, never> & LibraryStep;
+export function imageBuild<const N extends string>(def: ImageBuildPushDef<N>): Step<N, ImageBuildInput, typeof PushedImage, never> & LibraryStep;
+export function imageBuild<const N extends string>(def: ImageBuildTarballDef<N> | ImageBuildPushDef<N>): AnyImageBuild {
   const registryMap = def.registryMap ?? DEFAULT_REGISTRY_MAP;
   const mapped = Object.keys(registryMap).length > 0;
+  const push = def.push === true;
+  const contentTag = push && def.contentTag === true;
+  const context = checkRelative("context", def.context ?? "");
+  const dockerfile = checkRelative("dockerfile", def.dockerfile ?? "Dockerfile");
+  if (push && !/[.:]|^localhost$/.test(def.repository.split("/")[0]!)) throw new Error(`imageBuild '${def.name}': push needs a repository with a registry host, got '${def.repository}'`);
   return makeStep(
     "imageBuild",
-    { name: def.name, description: def.description, image: KANIKO_IMAGE, input, output: BuiltImage, secrets: [], timeoutSeconds: def.timeoutSeconds, retries: def.retries ?? DEFAULT_RETRIES },
+    { name: def.name, description: def.description, image: KANIKO_IMAGE, input, output: push ? PushedImage : BuiltImage, secrets: [], timeoutSeconds: def.timeoutSeconds, retries: def.retries ?? DEFAULT_RETRIES },
     {
       manifestConfig: () => ({
         repository: def.repository,
+        ...(context ? { context } : {}),
+        ...(dockerfile !== "Dockerfile" ? { dockerfile } : {}),
+        ...(push ? { push: true } : {}),
+        ...(contentTag ? { contentTag: true } : {}),
         ...(def.cacheRepo ? { cacheRepo: def.cacheRepo } : {}),
         ...(mapped ? { registryMap: { ...registryMap } } : {}),
       }),
       async run({ source }: { source: { tree: FileRef } }, ctx: Ctx) {
-        const tag = imageTag(ctx.run);
-        const caches = await reachableCaches(ctx, { registryMap, cacheRepo: def.cacheRepo });
         const tree = await ctx.files.fetch(source.tree);
+        const contextDir = context ? join(tree, context) : tree;
+        if (!existsSync(contextDir) || !statSync(contextDir).isDirectory()) throw new Error(`build context '${context}' not found in the source tree`);
+        if (!existsSync(join(contextDir, dockerfile))) throw new Error(`${dockerfile} not found in the build context${context ? ` '${context}'` : ""}`);
+
+        const tag = contentTag ? contentTagOf(contextDir, ctx.tmpDir) : imageTag(ctx.run);
+        if (contentTag) {
+          const digest = await registryDigest(ctx.http, def.repository, tag);
+          if (digest) {
+            ctx.log("image already in the registry", { image: `${def.repository}:${tag}`, digest });
+            return { repository: def.repository, tag, digest };
+          }
+        }
+
+        const caches = await reachableCaches(ctx, { registryMap, cacheRepo: def.cacheRepo });
         await ctx.exec(["mkdir", "-p", KANIKO_CONTEXT]);
         await ctx.exec(["cp", "-r", `${tree}/.`, KANIKO_CONTEXT]);
+        const kanikoContext = context ? `${KANIKO_CONTEXT}/${context}` : KANIKO_CONTEXT;
 
         // Outputs go to the harness's scratch dir (/olve/tmp, an emptyDir mount kaniko leaves alone;
         // kaniko images have no /tmp), then into the step's files.
@@ -161,16 +251,16 @@ export function imageBuild<const N extends string>(def: ImageBuildDef<N>): Step<
         const out = mkdtempSync(join(ctx.tmpDir, "image-build-"));
         const tarPath = join(out, "image.tar");
         const digestPath = join(out, "digest");
+        const output = push ? [] : ["--no-push", `--tar-path=${tarPath}`];
         // No --single-snapshot: it is incompatible with multi-stage Dockerfiles whose later stages need
         // the build context intact. --skip-push-permission-check: with --no-push kaniko otherwise checks
         // the cache repo at startup and exits if it is down; later cache lookup and push errors are
         // only warnings.
         await ctx.exec([
           "/kaniko/executor",
-          `--context=${KANIKO_CONTEXT}`,
-          `--dockerfile=${KANIKO_CONTEXT}/Dockerfile`,
-          "--no-push",
-          `--tar-path=${tarPath}`,
+          `--context=${kanikoContext}`,
+          `--dockerfile=${kanikoContext}/${dockerfile}`,
+          ...output,
           `--digest-file=${digestPath}`,
           `--destination=${def.repository}:${tag}`,
           ...(caches.cacheRepo ? ["--cache=true", `--cache-repo=${caches.cacheRepo}`, "--skip-push-permission-check"] : []),
@@ -184,6 +274,10 @@ export function imageBuild<const N extends string>(def: ImageBuildDef<N>): Step<
           throw new Error(`kaniko did not write the image digest to ${digestPath}`);
         }
         if (!/^sha256:[0-9a-f]{64}$/.test(digest)) throw new Error(`kaniko wrote an unexpected digest: '${digest}'`);
+        if (push) {
+          ctx.log("image pushed", { image: `${def.repository}:${tag}`, digest });
+          return { repository: def.repository, tag, digest };
+        }
         const tar = await ctx.output.file(tarPath, { name: "image.tar" });
         rmSync(tarPath); // the copy in the step's files is the one that counts; don't hold the image twice in /olve
         ctx.log("image built", { image: `${def.repository}:${tag}`, digest });
@@ -192,3 +286,5 @@ export function imageBuild<const N extends string>(def: ImageBuildDef<N>): Step<
     },
   ) as never;
 }
+
+type AnyImageBuild = Step<string, ImageBuildInput, typeof BuiltImage | typeof PushedImage, never> & LibraryStep;

package/src/library/index.ts

@@ -3,11 +3,13 @@ import { helmDeployOverSsh } from "./helm-deploy-ssh.ts";
 import { imageBuild } from "./image-build.ts";
 import { script } from "./script.ts";
 
-export { Source, BuiltImage, HelmRelease, FailureContext } from "./models.ts";
+export { Source, BuiltImage, PushedImage, HelmRelease, FailureContext } from "./models.ts";
 export { inputEnvName, type RunValue, type ScriptDef } from "./script.ts";
 export type { GitHubSourceDef } from "./github-source.ts";
-export type { ImageBuildDef } from "./image-build.ts";
+export type { ImageBuildDef, ImageBuildTarballDef, ImageBuildPushDef } from "./image-build.ts";
 export type { HelmDeployOverSshDef } from "./helm-deploy-ssh.ts";
+export { sshSession, shq, type SshSession } from "./ssh.ts";
+export { serviceUrl, checkSpa } from "./checks.ts";
 export { httpHealthCheck, HTTP_HEALTH_DEFAULTS, type HttpHealthCheckOptions } from "./http-health.ts";
 
 /** SDK-provided steps (step + handler pairs with typed config). */

package/src/library/models.ts

@@ -14,6 +14,15 @@ export const BuiltImage = model(
   z.object({ repository: z.string(), tag: z.string(), digest: z.string(), tar: fileRef() }),
 );
 
+/**
+ * A container image pushed to a registry by a step (`imageBuild` with `push: true`), pulled from there
+ * by the deploy. `repository` includes the registry host.
+ */
+export const PushedImage = model(
+  "PushedImage",
+  z.object({ repository: z.string(), tag: z.string(), digest: z.string() }),
+);
+
 /** A Helm release that was installed or upgraded. */
 export const HelmRelease = model(
   "HelmRelease",

package/src/library/ssh.ts

@@ -0,0 +1,45 @@
+// sshSession — run commands on a host over SSH from a handler (alpine image: installs openssh-client).
+import { chmodSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Ctx } from "../ctx/types.ts";
+
+const SAFE = /^[A-Za-z0-9_\/.:=@%+,-]+$/;
+/** POSIX shell quoting (safe words are left bare, so logs stay readable). */
+export function shq(s: string): string {
+  return SAFE.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`;
+}
+
+export interface SshSession {
+  readonly host: string;
+  /** Runs a remote command; a non-zero exit throws. */
+  run(remote: string): Promise<void>;
+  /** Runs a remote command and returns its stdout. */
+  text(remote: string): Promise<string>;
+  /** `scp -r` a local file or directory to a remote path. */
+  copy(local: string, remote: string): Promise<void>;
+  /** The ssh invocation as a shell command, for pipes and redirects: `ctx.sh(`${s.shell("cat > f")} < ${file}`)`. */
+  shell(remote: string): string;
+}
+
+/**
+ * Opens an SSH "session" to `host` (`user@host`) with a private key: installs openssh-client (apk),
+ * writes the key to `<tmpDir>/ssh/id`. The host key is not verified: hosts are reached over the tailnet.
+ */
+export async function sshSession(ctx: Pick<Ctx, "exec" | "sh" | "tmpDir">, opts: { host: string; key: string }): Promise<SshSession> {
+  await ctx.exec(["apk", "add", "--no-cache", "openssh-client"]);
+  const dir = join(ctx.tmpDir, "ssh");
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const keyFile = join(dir, "id");
+  // OpenSSH rejects a key without a trailing newline.
+  writeFileSync(keyFile, opts.key.endsWith("\n") ? opts.key : opts.key + "\n", { mode: 0o600 });
+  chmodSync(keyFile, 0o600);
+  const sshOpts = ["-i", keyFile, "-o", "StrictHostKeyChecking=no", "-o", "UserKnownHostsFile=/dev/null", "-o", "LogLevel=ERROR", "-o", "BatchMode=yes"];
+  const argv = (remote: string) => ["ssh", ...sshOpts, opts.host, remote];
+  return {
+    host: opts.host,
+    run: (remote) => ctx.exec(argv(remote)),
+    text: (remote) => ctx.sh.text(argv(remote).map(shq).join(" ")),
+    copy: (local, remote) => ctx.exec(["scp", ...sshOpts, "-r", local, `${opts.host}:${remote}`]),
+    shell: (remote) => argv(remote).map(shq).join(" "),
+  };
+}

package/src/testing/index.ts

@@ -1,4 +1,4 @@
-// @olve/pipelines/testing — run a handler under `bun test` through the real harness path
+// @olivervea/pipelines/testing — run a handler under `bun test` through the real harness path
 // (validate input → handler → strict output validation), with a real ctx you can override.
 import { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";

package/src/util/handler-hash.ts

@@ -5,7 +5,7 @@ import { sha256Hex } from "./hash.ts";
 export interface HarnessInfo {
   /** Bun version (runtime compiled into the binary). */
   bun: string;
-  /** @olve/pipelines package version. */
+  /** @olivervea/pipelines package version. */
   sdk: string;
   /** `sha256:` hash over the SDK runtime sources and the zod version. */
   sdkHash: string;