@olivervea/pipelines 2.0.0-beta.26 → 2.0.0-beta.28

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.28",
   "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/describe/config-schema.ts

@@ -0,0 +1,98 @@
+import { SECRET_REF_KIND } from '../core/config.ts';
+import { CONFIG_CASE_KEY, CONFIG_REF_KEY } from '../core/config-refs.ts';
+import type { JsonSchema } from './schemas.ts';
+
+/**
+ * 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(
+  schema: unknown,
+  path: readonly string[],
+  kase: string | undefined,
+  entry: string,
+): unknown[] {
+  let narrow: { at: string; discriminator: string; value: string } | undefined;
+  if (kase) {
+    const eq = kase.lastIndexOf('=');
+    const left = kase.slice(0, eq);
+    const dot = left.lastIndexOf('.');
+    narrow = {
+      at: left.slice(0, dot),
+      discriminator: left.slice(dot + 1),
+      value: kase.slice(eq + 1),
+    };
+  }
+  const walk = (node: unknown, rest: readonly string[], here: string): unknown[] => {
+    if (node === null || typeof node !== 'object') return [];
+    const o = node as JsonSchema;
+    const branches = (o.oneOf ?? o.anyOf) as JsonSchema[] | undefined;
+    if (Array.isArray(branches)) {
+      const chosen =
+        narrow && narrow.at === here
+          ? branches.filter(
+              (b) =>
+                (
+                  (b.properties as Record<string, JsonSchema> | undefined)?.[
+                    narrow!.discriminator
+                  ] as JsonSchema | undefined
+                )?.const === narrow!.value,
+            )
+          : branches;
+      return chosen.flatMap((b) => walk(b, rest, here));
+    }
+    if (rest.length === 0) return [node];
+    const props = o.properties as Record<string, JsonSchema> | undefined;
+    if (props && Object.hasOwn(props, rest[0]!))
+      return walk(props[rest[0]!], rest.slice(1), `${here}.${rest[0]}`);
+    if (o.additionalProperties && typeof o.additionalProperties === 'object')
+      return walk(o.additionalProperties, rest.slice(1), `${here}.${rest[0]}`);
+    return [];
+  };
+  return walk(schema, path, entry);
+}
+
+/** Secret names of every secretRef inside a config entry's JSON Schema. */
+export function secretRefsOf(schema: unknown): string[] {
+  const out = new Set<string>();
+  const walk = (v: unknown) => {
+    if (Array.isArray(v)) return v.forEach(walk);
+    if (v === null || typeof v !== 'object') return;
+    const o = v as JsonSchema;
+    if (o['x-olve-kind'] === SECRET_REF_KIND) {
+      const name = (o.properties as { secret?: { const?: unknown } } | undefined)?.secret
+        ?.const;
+      if (typeof name === 'string') out.add(name);
+    }
+    Object.values(o).forEach(walk);
+  };
+  walk(schema);
+  return [...out].sort();
+}
+
+/** The `{"$config": "<entry>.<path>"[, "$case": …]}` references in a step's recorded settings. */
+export function recordedConfigRefs(
+  v: unknown,
+  out: { ref: string; case?: string }[] = [],
+): { ref: string; case?: string }[] {
+  if (Array.isArray(v)) v.forEach((x) => recordedConfigRefs(x, out));
+  else if (v !== null && typeof v === 'object') {
+    const o = v as Record<string, unknown>;
+    const keys = Object.keys(o).sort();
+    const isRef =
+      typeof o[CONFIG_REF_KEY] === 'string' &&
+      (keys.length === 1
+        ? keys[0] === CONFIG_REF_KEY
+        : keys.length === 2 &&
+          keys[0] === CONFIG_CASE_KEY &&
+          keys[1] === CONFIG_REF_KEY &&
+          typeof o[CONFIG_CASE_KEY] === 'string');
+    if (isRef)
+      out.push({
+        ref: o[CONFIG_REF_KEY] as string,
+        ...(keys.length === 2 ? { case: o[CONFIG_CASE_KEY] as string } : {}),
+      });
+    else Object.values(o).forEach((x) => recordedConfigRefs(x, out));
+  }
+  return out;
+}

package/src/describe/context.ts

@@ -0,0 +1,182 @@
+import { z } from 'zod';
+import { CONFIG_NAME, isConfigEntry } from '../core/config.ts';
+import { MODEL_NAME, type AnyModel } from '../core/models.ts';
+import { SECRET_NAME, type Secret } from '../core/secrets.ts';
+import { RESERVED_STEP_NAMES, STEP_NAME, type AnyStep } from '../core/steps.ts';
+import { canonicalize } from '../util/canonical.ts';
+import { secretRefsOf } from './config-schema.ts';
+import type { ManifestT, ModelSchemasT } from './manifest-schema.ts';
+import { schemaViews, type JsonSchema } from './schemas.ts';
+
+/** Root name used in failure-handler mappings (the service supplies FailureContext under it). */
+export const FAILURE_ROOT = 'failure';
+const RESERVED = new Set([...RESERVED_STEP_NAMES, FAILURE_ROOT]);
+
+/** What a step can read at a point of the pipeline: its output model, and whether it may have been skipped. */
+export interface Avail {
+  model: string | null;
+  maybe: boolean;
+}
+
+/** A select case a step sits in: which select (numbered in describe order), which value, and its condition text. */
+export interface CaseOf {
+  select: number;
+  value: string;
+  cond: string;
+}
+
+interface ConfigUse {
+  description: string;
+  required: boolean;
+  schema: JsonSchema;
+  key: string;
+  secretRefs: string[];
+}
+
+// Two places are mutually exclusive when they sit in different cases of the same select.
+const exclusive = (a: readonly CaseOf[], b: readonly CaseOf[]) =>
+  a.some((x) => b.some((y) => y.select === x.select && y.value !== x.value));
+
+const byName = ([a]: [string, unknown], [b]: [string, unknown]) =>
+  a < b ? -1 : a > b ? 1 : 0;
+
+/** The problems found so far and the models, secrets, config entries and step names the pipeline uses. */
+export class DescribeContext {
+  readonly problems: string[];
+  readonly models = new Map<string, { schemas: ModelSchemasT; key: string }>();
+  readonly secrets = new Map<string, string>();
+  readonly configs = new Map<string, ConfigUse>();
+  readonly steps = new Map<string, AnyStep>();
+  private readonly placements = new Map<
+    string,
+    { step: AnyStep; cases: readonly CaseOf[] }[]
+  >();
+  private selects = 0;
+
+  constructor(problems: readonly string[]) {
+    this.problems = [...problems];
+  }
+
+  nextSelectId(): number {
+    return ++this.selects;
+  }
+
+  useModel(m: AnyModel, at: string): string {
+    const problems = this.problems;
+    if (!MODEL_NAME.test(m.name))
+      problems.push(`${at}: model name '${m.name}' must match ${MODEL_NAME}`);
+    let schemas: ModelSchemasT;
+    try {
+      schemas = schemaViews(m.schema);
+    } catch (e) {
+      problems.push(
+        `${at}: model '${m.name}' is not representable as JSON Schema (${(e as Error).message})`,
+      );
+      return m.name;
+    }
+    const key = JSON.stringify(schemas);
+    const prev = this.models.get(m.name);
+    if (!prev) this.models.set(m.name, { schemas, key });
+    else if (prev.key !== key)
+      problems.push(
+        `two different schemas are registered under the model name '${m.name}' (one schema per model name)`,
+      );
+    return m.name;
+  }
+
+  outputViewOf(modelName: string | null): JsonSchema | undefined {
+    return modelName ? this.models.get(modelName)?.schemas.output : undefined;
+  }
+
+  useSecret(s: Secret, at: string): string {
+    if (!SECRET_NAME.test(s.name))
+      this.problems.push(`${at}: secret name '${s.name}' must match ${SECRET_NAME}`);
+    const prev = this.secrets.get(s.name);
+    if (prev === undefined) this.secrets.set(s.name, s.description);
+    else if (prev !== s.description)
+      this.problems.push(
+        `secret '${s.name}' is declared twice with different descriptions`,
+      );
+    return s.name;
+  }
+
+  useConfig(e: unknown, at: string): string | undefined {
+    const problems = this.problems;
+    if (!isConfigEntry(e))
+      return void problems.push(
+        `${at}: config entries must be config("name", "description", schema)`,
+      );
+    if (!CONFIG_NAME.test(e.name))
+      problems.push(`${at}: config name '${e.name}' must match ${CONFIG_NAME}`);
+    let schema: JsonSchema;
+    try {
+      schema = z.toJSONSchema(e.schema, {
+        io: 'input',
+        target: 'draft-2020-12',
+      }) as JsonSchema;
+      delete schema.$schema;
+      schema = canonicalize(schema) as JsonSchema;
+    } catch (err) {
+      problems.push(
+        `${at}: config '${e.name}' is not representable as JSON Schema (${(err as Error).message})`,
+      );
+      return e.name;
+    }
+    const key = JSON.stringify([e.description, schema]);
+    const prev = this.configs.get(e.name);
+    if (!prev)
+      this.configs.set(e.name, {
+        description: e.description,
+        required: !e.schema.safeParse(undefined).success,
+        schema,
+        key,
+        secretRefs: secretRefsOf(schema),
+      });
+    else if (prev.key !== key)
+      problems.push(
+        `two different config entries are named '${e.name}' (one description and schema per config name)`,
+      );
+    return e.name;
+  }
+
+  registerStep(s: AnyStep, where: string, cases: readonly CaseOf[] = []): void {
+    const problems = this.problems;
+    if (typeof s.name !== 'string' || !STEP_NAME.test(s.name))
+      problems.push(
+        `${where}: step name '${String(s.name)}' must be lower-case kebab (${STEP_NAME})`,
+      );
+    if (RESERVED.has(s.name))
+      problems.push(`${where}: '${s.name}' is reserved and cannot be a step name`);
+    const prev = this.placements.get(s.name) ?? [];
+    if (prev.some((p) => !exclusive(p.cases, cases)))
+      problems.push(`duplicate step name '${s.name}'`);
+    else if (prev.some((p) => (p.step.output?.name ?? null) !== (s.output?.name ?? null)))
+      problems.push(
+        `step '${s.name}': its select cases must give it the same output model`,
+      );
+    this.placements.set(s.name, [...prev, { step: s, cases }]);
+    if (!this.steps.has(s.name)) this.steps.set(s.name, s);
+  }
+
+  modelsSection(): ManifestT['models'] {
+    return Object.fromEntries([...this.models].map(([k, v]) => [k, v.schemas]));
+  }
+
+  secretsSection(): ManifestT['secrets'] {
+    return [...this.secrets]
+      .sort(byName)
+      .map(([name, description]) => ({ name, description }));
+  }
+
+  configSection(): Pick<ManifestT, 'config'> {
+    if (!this.configs.size) return {};
+    return {
+      config: [...this.configs].sort(byName).map(([name, c]) => ({
+        name,
+        description: c.description,
+        required: c.required,
+        schema: c.schema,
+      })),
+    };
+  }
+}