@olivervea/pipelines 2.0.0-beta.26 → 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.26",
+  "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/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';
@@ -165,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/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/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 }