@olivervea/pipelines 2.0.0-beta.25 → 2.0.0-beta.27

package/README.md

@@ -201,6 +201,7 @@ import deployScript from "./scripts/deploy.sh" with { type: "file" };
 export const deployBeta = implement(step({ name: "deploy-beta", /* … */ }), async ({ artifact }, ctx) => {
   await ctx.sh(deployScript, { env: { IMAGE_TAR: await ctx.files.fetch(artifact.image), CHART_DIR: await ctx.files.fetch(artifact.chart) } });
   await ctx.retry({ attempts: 5, delaySeconds: 5 }, () => ctx.http.expectOk("https://pipelines-beta.ovea.pro/api/health"));
+  ctx.link("https://pipelines-beta.ovea.pro", "beta");                             // shown on the step card and in pl run get
   return { release: "olve-pipelines", version: artifact.version, url: "https://pipelines-beta.ovea.pro" };   // or ctx.skip("reason")
 });
 ```
@@ -324,6 +325,8 @@ It retries network errors, 5xx, 408 and 429. It always verifies `sha256`.
 { "status": "failed",    "error": { "kind": "handler" | "input" | "output", "message": "…" } }
 ```
 
+Any of the three may carry `"links": [{ "url": "https://…", "label": "…" }]`, what the handler passed to `ctx.link` (absolute http(s) URLs of at most 2048 characters, labels of at most 100, at most 10). The key is left out when there are none. The server refuses an envelope whose links break these limits.
+
 For `map-trigger`, `output` is the pipeline input after it has been parsed by the input model, so defaults are applied. Validate it again server-side.
 
 ### Exit codes

package/package.json

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

package/src/build/build.ts

@@ -6,7 +6,7 @@ import { sha256File } from '../util/hash.ts';
 import type { HarnessInfo } from '../util/code-hash.ts';
 import { writeTarZst } from '../util/tar.ts';
 import { MANIFEST_BEGIN, MANIFEST_END, uploadFile } from '../harness/result.ts';
-import { GLIBC_INTERP, MUSL_INTERP, readInterpreter } from './elf.ts';
+import { loaderProblem } from './elf.ts';
 import { codeHash } from './hashes.ts';
 import { harnessInfo, loadProject, relPosix, type Project } from './project.ts';
 
@@ -112,14 +112,9 @@ export async function build(dir: string, opts: BuildOptions): Promise<BuildResul
     `olve-build: compiled ${target} in ${((performance.now() - t1) / 1000).toFixed(2)}s`,
   );
 
-  // 2. loader check: the harness launches the binary through /olve/lib/<loader>; a musl binary
-  //    (e.g. compiled on alpine, where bun-linux-x64 silently yields musl) would not start.
-  const expected = target === 'bun-linux-x64' ? GLIBC_INTERP : MUSL_INTERP;
-  const interp = readInterpreter(binary);
-  if (interp !== expected)
-    throw new BuildError(
-      `compiled binary has PT_INTERP ${interp ?? '(none)'}, expected ${expected} — compile on a glibc Bun image (oven/bun:<version>-slim), not alpine`,
-    );
+  // 2. loader check: on alpine, bun-linux-x64 silently yields a musl binary, which would not start.
+  const problem = loaderProblem(binary, target);
+  if (problem) throw new BuildError(problem);
 
   // 3. describe (runs the real binary: the manifest is exactly what the step pods will see)
   const d = Bun.spawnSync([binary, 'describe'], {

package/src/build/elf.ts

@@ -34,3 +34,11 @@ export function readInterpreter(path: string): string | null {
     closeSync(fd);
   }
 }
+
+/** Why `binary` won't start through `target`'s loader (the harness runs it via /olve/lib/<loader>), or undefined. */
+export function loaderProblem(binary: string, target: string): string | undefined {
+  const expected = target === 'bun-linux-x64' ? GLIBC_INTERP : MUSL_INTERP;
+  const interp = readInterpreter(binary);
+  if (interp === expected) return undefined;
+  return `compiled binary has PT_INTERP ${interp ?? '(none)'}, expected ${expected} — compile on a glibc Bun image (oven/bun:<version>-slim), not alpine`;
+}

package/src/ctx/files.ts

@@ -37,6 +37,8 @@ export interface FilesDeps {
   root: string;
   signal: AbortSignal;
   log: (message: string, fields?: Record<string, unknown>) => void;
+  /** Backoff between download retries (default: real sleep). */
+  sleep?: (ms: number) => Promise<void>;
 }
 
 function checkName(name: string, what: string): void {
@@ -122,6 +124,7 @@ async function download(
   headers: Record<string, string>,
   signal: AbortSignal,
   log: FilesDeps['log'],
+  sleep: (ms: number) => Promise<void>,
 ): Promise<void> {
   const attempts = 4;
   for (let i = 1; ; i++) {
@@ -143,13 +146,14 @@ async function download(
         attempt: i,
         error: (e as Error).message,
       });
-      await Bun.sleep(1000 * 2 ** (i - 1));
+      await sleep(1000 * 2 ** (i - 1));
     }
   }
 }
 
 export function createFetch(deps: FilesDeps) {
   const cache = new Map<string, string>();
+  const sleep = deps.sleep ?? ((ms: number) => Bun.sleep(ms));
   return async (input: FileRef): Promise<string> => {
     const parsed = fileRefSchema.safeParse(input);
     if (!parsed.success)
@@ -181,7 +185,8 @@ export function createFetch(deps: FilesDeps) {
     const baseUrl = process.env[ENV.filesBaseUrl];
     if (own && existsSync(join(deps.workFiles, obj)))
       copyFileSync(join(deps.workFiles, obj), objFile);
-    else if (urls[key]) await download(urls[key], objFile, {}, deps.signal, deps.log);
+    else if (urls[key])
+      await download(urls[key], objFile, {}, deps.signal, deps.log, sleep);
     else if (
       localDir &&
       existsSync(
@@ -201,6 +206,7 @@ export function createFetch(deps: FilesDeps) {
         token ? { authorization: `Bearer ${token}` } : {},
         deps.signal,
         deps.log,
+        sleep,
       );
     } else {
       throw new Error(

package/src/ctx/index.ts

@@ -1,6 +1,7 @@
 import { mkdirSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { skipped } from '../core/handlers.ts';
+import { createLinks } from './links.ts';
 import type { Secret } from '../core/secrets.ts';
 import { createFetch, createOutput, redactUrl } from './files.ts';
 import { createSh } from './sh.ts';
@@ -89,9 +90,25 @@ export function createHttp(signal: AbortSignal): Http {
   };
 }
 
+/** Waits `ms`, or rejects at once when the step is cancelled. */
+function cancellableSleep(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise<void>((res, rej) => {
+    const t = setTimeout(() => {
+      signal.removeEventListener('abort', onAbort);
+      res();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(t);
+      rej(new Error('retry cancelled: the step was cancelled'));
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
 export function createRetry(
   signal: AbortSignal,
   log: (m: string, f?: Record<string, unknown>) => void,
+  sleep: (ms: number, signal: AbortSignal) => Promise<void> = cancellableSleep,
 ) {
   return async <T>(
     opts: RetryOptions,
@@ -110,17 +127,7 @@ export function createRetry(
           of: opts.attempts,
           error: (e as Error)?.message ?? String(e),
         });
-        await new Promise<void>((res, rej) => {
-          const t = setTimeout(() => {
-            signal.removeEventListener('abort', onAbort);
-            res();
-          }, delay);
-          const onAbort = () => {
-            clearTimeout(t);
-            rej(new Error('retry cancelled: the step was cancelled'));
-          };
-          signal.addEventListener('abort', onAbort, { once: true });
-        });
+        await sleep(delay, signal);
         delay *= opts.backoff ?? 1;
       }
     }
@@ -159,6 +166,7 @@ export function createCtx(o: CtxOptions): Ctx {
     run: Object.freeze({ ...o.run }),
     tmpDir: o.paths.tmp,
     skip: skipped,
+    link: createLinks().link,
     inputUrl: (step, input) => {
       const name = typeof step === 'string' ? step : step.name;
       const url = o.callbackUrls?.[`${name}/${input}`];

package/src/ctx/links.ts

@@ -0,0 +1,30 @@
+export interface StepLink {
+  url: string;
+  label?: string;
+}
+
+export const MAX_LINKS = 10;
+export const MAX_LINK_URL = 2048;
+export const MAX_LINK_LABEL = 100;
+
+/** `ctx.link`, collecting into `links`. */
+export function createLinks(): {
+  links: StepLink[];
+  link: (url: string, label?: string) => void;
+} {
+  const links: StepLink[] = [];
+  const link = (url: string, label?: string) => {
+    if (typeof url !== 'string' || !/^https?:\/\/[^/\s]/i.test(url) || !URL.canParse(url))
+      throw new Error(`ctx.link: '${String(url)}' is not an absolute http or https URL`);
+    if (url.length > MAX_LINK_URL)
+      throw new Error(`ctx.link: the URL is longer than ${MAX_LINK_URL} characters`);
+    if (label !== undefined && typeof label !== 'string')
+      throw new Error('ctx.link: the label must be a string');
+    if (label !== undefined && label.length > MAX_LINK_LABEL)
+      throw new Error(`ctx.link: the label is longer than ${MAX_LINK_LABEL} characters`);
+    if (links.length >= MAX_LINKS)
+      throw new Error(`ctx.link: a step can add at most ${MAX_LINKS} links`);
+    links.push(label ? { url, label } : { url });
+  };
+  return { links, link };
+}

package/src/ctx/types.ts

@@ -111,6 +111,11 @@ export interface Ctx<Sec extends string = string, Cfg extends AnyConfigEntry = n
   readonly run: RunInfo;
   /** A writable scratch directory (`$OLVE_DIR/tmp`; images like kaniko have no /tmp). */
   readonly tmpDir: string;
+  /**
+   * Link to what the step made or deployed (a site, a release, an image), shown with the attempt in the
+   * UI and `pl run get`. Absolute http(s) URL; at most 10 per attempt.
+   */
+  link(url: string, label?: string): void;
   /** Runtime escape hatch: produce no output. Prefer `when` blocks. */
   skip(reason: string): Skipped;
   /**

package/src/describe/describe.ts

@@ -806,7 +806,7 @@ export function describePipeline(pipeline: unknown, opts: DescribeOptions): Mani
 export const manifestText = (m: ManifestT): string => canonicalJson(m);
 
 /**
- * The schemas at `path` inside an entry's schema: every union branch that has the field, except where
+ * The schemas at `path` inside an entry's schema (through properties and records): every union branch that has the field, except where
  * `kase` (`<entry>.<path>.<discriminator>=<value>`) narrows a union to one branch.
  */
 export function subSchemas(
@@ -848,6 +848,8 @@ export function subSchemas(
     const props = o.properties as Record<string, JsonSchema> | undefined;
     if (props && Object.hasOwn(props, rest[0]!))
       return walk(props[rest[0]!], rest.slice(1), `${here}.${rest[0]}`);
+    if (o.additionalProperties && typeof o.additionalProperties === 'object')
+      return walk(o.additionalProperties, rest.slice(1), `${here}.${rest[0]}`);
     return [];
   };
   return walk(schema, path, entry);

package/src/describe/mapper-source.ts

@@ -131,8 +131,8 @@ function tokenize(src: string): Tok[] {
       i = e + 2;
       continue;
     }
-    if (c === '`') throw new MapperError('mapper uses a template string');
-    if (c === '"' || c === "'") {
+    // Bun prints a string constant holding a newline or both quote kinds as a template literal.
+    if (c === '"' || c === "'" || c === '`') {
       let j = i + 1;
       let v = '';
       for (;;) {
@@ -140,6 +140,8 @@ function tokenize(src: string): Tok[] {
           throw new MapperError('mapper source has an unterminated string');
         const d = src[j]!;
         if (d === c) break;
+        if (c === '`' && d === '$' && src[j + 1] === '{')
+          throw new MapperError('mapper uses a template string');
         if (d === '\\') {
           v += src.slice(j, j + 2);
           j += 2;

package/src/harness/execute.ts

@@ -6,15 +6,17 @@ import { isSkipped } from '../core/handlers.ts';
 import type { AnyStep } from '../core/steps.ts';
 import type { Ctx, RunInfo } from '../ctx/types.ts';
 import { objectPath } from '../ctx/files.ts';
+import { createLinks, type StepLink } from '../ctx/links.ts';
 import { sha256File } from '../util/hash.ts';
 import { EXIT } from './exit.ts';
 import { validateConfig, validateInput, validateOutput } from './validate.ts';
 
 export type FailureKind = 'handler' | 'input' | 'output';
-export type Envelope =
+export type Envelope = (
   | { status: 'succeeded'; output: unknown }
   | { status: 'skipped'; reason: string }
-  | { status: 'failed'; error: { kind: FailureKind; message: string } };
+  | { status: 'failed'; error: { kind: FailureKind; message: string } }
+) & { links?: StepLink[] };
 
 export interface Execution {
   envelope: Envelope;
@@ -85,7 +87,14 @@ export async function executeStep(args: {
       exitCode: EXIT.inputInvalid,
     };
   }
-  const ctx: Ctx = { ...args.ctx, config: Object.freeze(config.value) as Ctx['config'] };
+  const collected = createLinks();
+  const ctx: Ctx = {
+    ...args.ctx,
+    config: Object.freeze(config.value) as Ctx['config'],
+    link: collected.link,
+  };
+  const withLinks = (e: Envelope): Envelope =>
+    collected.links.length ? { ...e, links: [...collected.links] } : e;
 
   let value: unknown;
   try {
@@ -98,14 +107,17 @@ export async function executeStep(args: {
     log(message);
     if (e instanceof Error && e.stack && !cancelled) log(e.stack);
     return {
-      envelope: { status: 'failed', error: { kind: 'handler', message } },
+      envelope: withLinks({ status: 'failed', error: { kind: 'handler', message } }),
       exitCode: cancelled ?? EXIT.handlerFailed,
     };
   }
 
   if (isSkipped(value)) {
     log(`step '${step.name}' skipped: ${value.reason}`);
-    return { envelope: { status: 'skipped', reason: value.reason }, exitCode: EXIT.ok };
+    return {
+      envelope: withLinks({ status: 'skipped', reason: value.reason }),
+      exitCode: EXIT.ok,
+    };
   }
   const out = validateOutput(step, value);
   const problems = out.ok
@@ -115,9 +127,12 @@ export async function executeStep(args: {
     const message = `step '${step.name}': returned value does not match ${step.output?.name ?? 'its (absent) output model'}:\n  ${problems.join('\n  ')}`;
     log(message);
     return {
-      envelope: { status: 'failed', error: { kind: 'output', message } },
+      envelope: withLinks({ status: 'failed', error: { kind: 'output', message } }),
       exitCode: EXIT.outputInvalid,
     };
   }
-  return { envelope: { status: 'succeeded', output: out.value }, exitCode: EXIT.ok };
+  return {
+    envelope: withLinks({ status: 'succeeded', output: out.value }),
+    exitCode: EXIT.ok,
+  };
 }

package/src/harness/index.ts

@@ -2,7 +2,6 @@
 export {
   runHarness,
   defaultIO,
-  allSteps,
   resolveStepFunction,
   type HarnessConfig,
   type HarnessIO,

package/src/harness/main.ts

@@ -56,12 +56,6 @@ export const defaultIO: HarnessIO = {
 const USAGE =
   'usage: step describe [--sentinels] | step run <step> | step map-trigger <trigger>';
 
-export function allSteps(data: PipelineData): AnyStep[] {
-  const out: AnyStep[] = [];
-  for (const { step } of stepsWithCases(data)) if (!out.includes(step)) out.push(step);
-  return out;
-}
-
 /** Every step with the `select` case conditions (`<ref>.<discriminator>=<value>`) it sits in. */
 export function stepsWithCases(data: PipelineData): { step: AnyStep; cases: string[] }[] {
   const out: { step: AnyStep; cases: string[] }[] = [];

package/src/harness/result.ts

@@ -53,10 +53,15 @@ export async function uploadFile(
   url: string,
   file: string,
   log: (line: string) => void,
-  opts: { attempts?: number; baseDelayMs?: number } = {},
+  opts: {
+    attempts?: number;
+    baseDelayMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+  } = {},
 ): Promise<void> {
   const attempts = opts.attempts ?? 5;
   const base = opts.baseDelayMs ?? 1000;
+  const sleep = opts.sleep ?? ((ms: number) => Bun.sleep(ms));
   for (let i = 1; ; i++) {
     let status = 0;
     let detail: string;
@@ -73,7 +78,7 @@ export async function uploadFile(
     if (!transient || i >= attempts)
       throw new Error(`upload to ${redactUrl(url)} failed: ${detail}`);
     log(`upload to ${redactUrl(url)} failed (${detail}); retry ${i}/${attempts - 1}`);
-    await Bun.sleep(base * 2 ** (i - 1));
+    await sleep(base * 2 ** (i - 1));
   }
 }
 

package/src/index.ts

@@ -77,6 +77,7 @@ export type {
   RetryOptions,
   OutputFileOptions,
 } from './ctx/types.ts';
+export type { StepLink } from './ctx/links.ts';
 export type { Ref, Mappable, MapperResult } from './builder/refs.ts';
 export {
   pipeline,

package/src/library/compose-deploy.ts

@@ -20,6 +20,7 @@ export interface ComposeTargetValue {
   service: string;
   token: { secret: string };
   healthUrl?: string | undefined;
+  link?: string | undefined;
 }
 
 /** What the deployer answers to `POST /v1/deploy`. */
@@ -103,6 +104,7 @@ export function composeDeploy<const N extends string, const K extends string>(
       );
     if (target.healthUrl)
       await httpHealthCheck(ctx, target.healthUrl, { attempts: 12, delaySeconds: 5 });
+    if (target.link) ctx.link(target.link);
     ctx.log('deployed', {
       service: target.service,
       image: ref,

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

@@ -113,6 +113,8 @@ export interface HelmDeployOverSshDef<
   helmWait?: boolean;
   /** `helm upgrade --atomic`: wait like `helmWait`, and roll back when the upgrade fails. Default false. */
   atomic?: boolean;
+  /** Public URL of what the release serves; the step links to it after a successful deploy. */
+  link?: Configurable<string>;
   /** After the rollouts, GET this URL until it returns 2xx (`httpHealthCheck`: 5 × 5 s unless given), or fail the step. */
   healthUrl?:
     | Configurable<string>
@@ -407,6 +409,7 @@ function helmDeployOverSshLiteral(
     values: def.values ?? [],
     set: def.set ?? {},
     healthUrl: def.healthUrl,
+    link: def.link,
   };
 
   const contract = step({
@@ -436,6 +439,7 @@ function helmDeployOverSshLiteral(
       ...(def.dependencies ? { dependencies: true } : {}),
       ...(def.atomic ? { atomic: true } : def.helmWait ? { helmWait: true } : {}),
       ...(def.healthUrl !== undefined ? { healthUrl: def.healthUrl } : {}),
+      ...(def.link !== undefined ? { link: def.link } : {}),
     },
   });
   return implement(contract, async (stepInput, ctx: Ctx) => {
@@ -449,6 +453,7 @@ function helmDeployOverSshLiteral(
       namespace: string;
       values: string[];
       set: Record<string, string>;
+      link?: string;
       healthUrl?:
         | string
         | ({ url: string } & Pick<HttpHealthCheckOptions, 'attempts' | 'delaySeconds'>);
@@ -495,6 +500,7 @@ function helmDeployOverSshLiteral(
         attempts: health.attempts,
         delaySeconds: health.delaySeconds,
       });
+    if (d.link) ctx.link(d.link);
     return {
       release: d.release,
       namespace: d.namespace,

package/src/library/helm-deploy.ts

@@ -53,6 +53,12 @@ function targetVariants<const E extends z.ZodRawShape, const K extends string>(
       .describe(
         'Base URL step pods reach the release at (health checks, smoke tests); default http://<release>.<namespace>.svc.cluster.local.',
       ),
+    link: z
+      .string()
+      .optional()
+      .describe(
+        'Public URL of what the target serves (a site, an API); the deploy step links to it.',
+      ),
     ...(o.extend ?? ({} as E)),
   };
   const inCluster = z.object({
@@ -86,6 +92,12 @@ function targetVariants<const E extends z.ZodRawShape, const K extends string>(
       .describe(
         "Checked by the step after the deployer's own health check, when the step can reach it.",
       ),
+    link: z
+      .string()
+      .optional()
+      .describe(
+        'Public URL of what the target serves (a site, an API); the deploy step links to it.',
+      ),
     ...(o.extend ?? ({} as E)),
   });
   const none = z.object({
@@ -156,6 +168,7 @@ interface TargetCommon {
   values: readonly string[];
   set: Readonly<Record<string, string>>;
   url?: string | undefined;
+  link?: string | undefined;
 }
 /** A resolved `kind: inCluster` target. */
 export type InClusterTargetValue = TargetCommon & { kind: 'inCluster' };
@@ -472,6 +485,7 @@ function targetDeploy(
         attempts: 12,
         delaySeconds: 5,
       });
+    if (target.link) ctx.link(target.link);
     const main = flags[0];
     return {
       release,

package/src/library/models.ts

@@ -54,7 +54,7 @@ export const HelmRelease = model(
 export const FailedStep = z.object({
   step: z.string(),
   attempt: z.number().int(),
-  /** `<pipeline id>#<run>/<step>@<attempt>` (spec §5.5). */
+  /** `<pipeline id>#<run>/<step>@<attempt>`. */
   address: z.string(),
   /** The attempt's failure reason (handler error, exit code, timeout, …). */
   reason: z.string(),
@@ -74,7 +74,7 @@ export const FailureContext = model(
     run: z.object({
       id: z.string(),
       number: z.number().int(),
-      /** `<pipeline id>#<run>` (spec §5.5). */
+      /** `<pipeline id>#<run>`. */
       address: z.string(),
       /** The run's derived version, `yyyy.MM.dd.<run>`. */
       versionStamp: z.string(),

package/src/testing/index.ts

@@ -14,6 +14,7 @@ import type {
 } from '../core/steps.ts';
 import { createCtx } from '../ctx/index.ts';
 import type { Ctx, RunInfo } from '../ctx/types.ts';
+import type { StepLink } from '../ctx/links.ts';
 import { executeStep, type FailureKind, type StepFunction } from '../harness/execute.ts';
 import { sha256Hex } from '../util/hash.ts';
 
@@ -39,6 +40,8 @@ export type TestResult<S extends AnyStep> = {
   filesDir: string;
   logs: string[];
   exitCode: number;
+  /** What the handler passed to `ctx.link`; absent when nothing. */
+  links?: StepLink[];
 } & (
   | { status: 'succeeded'; output: OutputValue<S> }
   | { status: 'skipped'; reason: string }

package/src/util/tar.ts

@@ -20,7 +20,6 @@ import { createGzip } from 'node:zlib';
 
 export type TarEntry =
   | { path: string; type: 'file'; mode: number; source: string }
-  | { path: string; type: 'bytes'; mode: number; data: Uint8Array }
   | { path: string; type: 'dir'; mode: number }
   | { path: string; type: 'symlink'; target: string };
 
@@ -88,7 +87,6 @@ export function writeTar(out: string, entries: readonly TarEntry[]): void {
       const link = e.type === 'symlink' ? e.target : '';
       let size = 0;
       if (e.type === 'file') size = lstatSync(e.source).size;
-      else if (e.type === 'bytes') size = e.data.length;
       const pax: string[] = [];
       if (enc.encode(name).length > 100) pax.push(paxRecord('path', name));
       if (enc.encode(link).length > 100) pax.push(paxRecord('linkpath', link));
@@ -104,10 +102,7 @@ export function writeTar(out: string, entries: readonly TarEntry[]): void {
       write(
         header(shortName, size, mode, flag, link.length > 100 ? link.slice(0, 99) : link),
       );
-      if (e.type === 'bytes') {
-        write(e.data);
-        pad(size);
-      } else if (e.type === 'file') {
+      if (e.type === 'file') {
         const src = openSync(e.source, 'r');
         try {
           const buf = new Uint8Array(1 << 20);