@olivervea/pipelines 2.0.0-beta.13 → 2.0.0-beta.14

package/README.md

@@ -74,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 "@olivervea/pipelines";
+import { model, z, fileRef, optional, external, secret, step, steps, Source } from "@olivervea/pipelines";
 
 export const BuildArtifact = model("BuildArtifact", z.object({
   version: z.string(),
@@ -87,7 +87,7 @@ export const deployBeta = step({
   name: "deploy-beta",                         // identity: lower-case kebab, ≤ 63 chars
   description: "Deploys to beta.",             // required (may be ""); shown in the UI, not versioned
   image: "alpine:latest",                      // any image; the harness brings its own runtime
-  input: { artifact: BuildArtifact },          // model | optional(model) | plain zod schema
+  input: { artifact: BuildArtifact },          // model | optional(model) | plain zod schema | external(model, …)
   output: BetaDeployment,                      // a model, or omitted (no output)
   secrets: [SSH_PRIVATE_KEY],                  // only these are mounted; ctx.secrets is typed to them
   timeoutSeconds: 900,                         // optional
@@ -103,6 +103,7 @@ Rules:
 - **Trigger mappers** produce `z.input`, so fields with defaults may be left out. **Handlers, mapper refs and `when`** see `z.output`.
 - A **plain-schema input** has no model to match on, so the step needs a mapper.
 - **`optional(M)`** means "maybe skipped": `M` must still have an earlier producer.
+- **`external(M, { title, description?, from? })`** is answered from outside the run (`from`: `person()`, the default). It needs no producer and no mapper entry; the step waits until it is answered, then the value (validated against `M`) is in its input like any other. Failure handlers can't have one.
 
 ### Config
 
@@ -383,6 +384,7 @@ Exact format: [`manifest.schema.json`](manifest.schema.json) (JSON Schema 2020-1
   - a nested object of mappings.
 
   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"}`).
+- **Step `externalInputs`** (when present) maps each external input key to `{model, title, description, from: [{kind: "person"}]}`. Those keys are not in `input` or `inputTypes`; the service merges the answers into `input.json`.
 - **`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` + `configEntries` (and those entries' schemas) + `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 `@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.

package/manifest.schema.json

@@ -401,6 +401,56 @@
           "description": "What the step does, shown in the UI (may be empty).",
           "type": "string"
         },
+        "externalInputs": {
+          "additionalProperties": {
+            "additionalProperties": false,
+            "properties": {
+              "description": {
+                "type": "string"
+              },
+              "from": {
+                "description": "Who or what may answer.",
+                "items": {
+                  "additionalProperties": false,
+                  "properties": {
+                    "kind": {
+                      "const": "person",
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "kind"
+                  ],
+                  "type": "object"
+                },
+                "minItems": 1,
+                "type": "array"
+              },
+              "model": {
+                "description": "The value is validated against this model's input view.",
+                "pattern": "^[A-Za-z][A-Za-z0-9_]*$",
+                "type": "string"
+              },
+              "title": {
+                "description": "What is asked, shown to whoever answers.",
+                "minLength": 1,
+                "type": "string"
+              }
+            },
+            "required": [
+              "model",
+              "title",
+              "description",
+              "from"
+            ],
+            "type": "object"
+          },
+          "description": "Inputs answered from outside the run (omitted when none): the step waits until every one has a value, which the service writes into input.json under its key.",
+          "propertyNames": {
+            "type": "string"
+          },
+          "type": "object"
+        },
         "handlerHash": {
           "description": "Implementation identity: handler bundle (contract files excluded) + harness (bun + sdkHash); for a step that carries its implementation kind + config + harness + the hash of the code of its kind.",
           "pattern": "^sha256:[0-9a-f]{64}$",

package/package.json

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

package/src/builder/pipeline.ts

@@ -6,6 +6,7 @@ import { isStep } from "../core/steps.ts";
 import type { WebhookEvent, WebhookVerify } from "../core/webhooks.ts";
 import type { IsUnion, OrError, Simplify } from "../core/types.ts";
 import type { Optional } from "../core/models.ts";
+import type { External } from "../core/external.ts";
 import type { FailureContext } from "../library/models.ts";
 import type { MapperResult, Ref } from "./refs.ts";
 import { isConfigRef, narrowConfigRef, unionAt, type ConfigNode, type ConfigRef, type DiscriminatorOf, type VariantOf } from "../core/config.ts";
@@ -33,7 +34,8 @@ type DefiniteProducersOf<A extends AvailMap, MN> = {
 }[keyof A];
 
 type EntryError<SN extends string, Key extends string, E, A extends AvailMap> =
-  E extends Optional<infer M>
+  E extends External ? never
+  : E extends Optional<infer M>
     ? [ProducersOf<A, M["name"]>] extends [never]
       ? `❌ ${M["name"]} (input '${Key}' of step '${SN}') is not available at this stage`
       : IsUnion<ProducersOf<A, M["name"]>> extends true

package/src/builder/refs.ts

@@ -1,5 +1,6 @@
 import type { RefBrand } from "../core/brands.ts";
 import type { AnyStep, InferEntry } from "../core/steps.ts";
+import type { External } from "../core/external.ts";
 import type { Primitive } from "../core/types.ts";
 
 /**
@@ -23,4 +24,7 @@ export type Mappable<T> =
         ? never
         : { [K in keyof T]: Mappable<T[K]> } & { readonly [RefBrand]?: never }); // a Ref of another model can't sneak in structurally
 
-export type MapperResult<S extends AnyStep> = { [K in keyof S["input"]]: Mappable<InferEntry<S["input"][K]>> };
+/** What a mapper provides: every input except the external ones, which come from outside the run. */
+export type MapperResult<S extends AnyStep> = {
+  [K in keyof S["input"] as S["input"][K] extends External ? never : K]: Mappable<InferEntry<S["input"][K]>>;
+};

package/src/core/external.ts

@@ -0,0 +1,43 @@
+import { isModel, type AnyModel } from "./models.ts";
+
+/** Who or what may supply an external input's value. */
+export type ExternalSource = { readonly kind: "person" };
+
+/** A signed-in user answers, in the UI or with `pl input`. */
+export function person(): ExternalSource {
+  return Object.freeze({ kind: "person" as const });
+}
+
+/**
+ * A step input whose value comes from outside the run. The step waits until it is answered (the value is
+ * validated against `model`), then runs with the value in its input like any other.
+ */
+export interface External<M extends AnyModel = AnyModel> {
+  readonly kind: "external";
+  readonly model: M;
+  readonly title: string;
+  readonly description: string;
+  readonly from: readonly ExternalSource[];
+}
+
+export interface ExternalOptions {
+  /** What is asked, shown to whoever answers. */
+  title: string;
+  description?: string;
+  /** Who may answer (default: a person). */
+  from?: readonly ExternalSource[];
+}
+
+export function external<M extends AnyModel>(model: M, options: ExternalOptions): External<M> {
+  return Object.freeze({
+    kind: "external" as const,
+    model,
+    title: options.title,
+    description: options.description ?? "",
+    from: Object.freeze([...(options.from ?? [person()])]),
+  });
+}
+
+export function isExternal(v: unknown): v is External {
+  return typeof v === "object" && v !== null && (v as { kind?: unknown }).kind === "external" && isModel((v as { model?: unknown }).model);
+}

package/src/core/steps.ts

@@ -2,17 +2,22 @@ import type { z } from "zod";
 import { ORIGIN, STEP, type StepBrand } from "./brands.ts";
 import { callerFile } from "./origin.ts";
 import type { AnyModel, Infer, Optional } from "./models.ts";
+import type { External } from "./external.ts";
 import type { AnyConfigEntry } from "./config.ts";
 import { configRefsIn } from "./config-refs.ts";
 import type { Secret } from "./secrets.ts";
 import type { Simplify } from "./types.ts";
 
-/** A step input entry: a model (matchable by model), `optional(model)`, or a plain zod schema (mapper required). */
-export type InputEntry = AnyModel | Optional | z.ZodType;
+/**
+ * A step input entry: a model (matchable by model), `optional(model)`, a plain zod schema (mapper required),
+ * or `external(model, …)`, answered from outside the run.
+ */
+export type InputEntry = AnyModel | Optional | External | z.ZodType;
 export type InputSpec = { readonly [key: string]: InputEntry };
 
 export type InferEntry<E> =
   E extends Optional<infer M> ? Infer<M> | undefined
+  : E extends External<infer M> ? Infer<M>
   : E extends AnyModel ? Infer<E>
   : E extends z.ZodType ? z.output<E>
   : never;

package/src/describe/describe.ts

@@ -5,6 +5,7 @@ import { CONFIG_NAME, isConfigEntry, SECRET_REF_KIND } from "../core/config.ts";
 import { CONFIG_CASE_KEY, CONFIG_REF_KEY } from "../core/config-refs.ts";
 import { configRefPath, configRefTarget, isConfigRef, unionAt } from "../core/config.ts";
 import { isModel, isOptional, MODEL_NAME, type AnyModel } from "../core/models.ts";
+import { isExternal } from "../core/external.ts";
 import { SECRET_NAME, type Secret } from "../core/secrets.ts";
 import { RESERVED_STEP_NAMES, STEP_NAME, isStep, type AnyStep } from "../core/steps.ts";
 import { isImplementation } from "../core/handlers.ts";
@@ -189,7 +190,21 @@ export function describePipeline(pipeline: unknown, opts: DescribeOptions): Mani
     if (typeof s.image !== "string" || s.image.trim() === "") problems.push(`${at}: image must be a non-empty string`);
 
     const inputTypes: StepDescriptorT["inputTypes"] = {};
-    const entries = Object.entries(s.input as Record<string, unknown>);
+    const externalInputs: NonNullable<StepDescriptorT["externalInputs"]> = {};
+    const allEntries = Object.entries(s.input as Record<string, unknown>);
+    for (const [key, e] of allEntries) {
+      if (!isExternal(e)) continue;
+      if (failureHandler) problems.push(`${at}: failure handlers run unattended and cannot wait for input ('${key}')`);
+      if (typeof e.title !== "string" || e.title.trim() === "") problems.push(`${at} external input '${key}': title must not be empty`);
+      if (e.from.length === 0) problems.push(`${at} external input '${key}': from must list at least one source`);
+      externalInputs[key] = {
+        model: useModel(e.model, `${at} external input '${key}'`),
+        title: e.title,
+        description: e.description,
+        from: e.from.map((f) => ({ kind: f.kind })),
+      };
+    }
+    const entries = allEntries.filter(([, e]) => !isExternal(e));
     for (const [key, e] of entries) {
       if (isOptional(e)) inputTypes[key] = { model: useModel(e.model, `${at} input '${key}'`), optional: true };
       else if (isModel(e)) inputTypes[key] = { model: useModel(e, `${at} input '${key}'`), optional: false };
@@ -298,6 +313,7 @@ export function describePipeline(pipeline: unknown, opts: DescribeOptions): Mani
       ...(settings !== undefined ? { config: settings as Record<string, z.core.util.JSONType> } : {}),
       ...(configNames.length ? { configEntries: configNames } : {}),
       ...(s.clusterAccess === true ? { clusterAccess: true as const } : {}),
+      ...(Object.keys(externalInputs).length ? { externalInputs } : {}),
     };
     if (s.clusterAccess !== undefined && typeof s.clusterAccess !== "boolean") problems.push(`${at}: clusterAccess must be a boolean`);
     if (s.output && !isModel(s.output)) problems.push(`${at}: output must be a model`);
@@ -321,7 +337,7 @@ export function describePipeline(pipeline: unknown, opts: DescribeOptions): Mani
       else problems.push(`${at}: mapper threw: ${(e as Error)?.message ?? String(e)}`);
       return {};
     }
-    const declared = s.input as Record<string, unknown>;
+    const declared = Object.fromEntries(Object.entries(s.input as Record<string, unknown>).filter(([, e]) => !isExternal(e)));
     for (const k of Object.keys(declared)) if (!(k in recorded)) problems.push(`${at}: mapper does not provide input '${k}'`);
     for (const k of Object.keys(recorded)) if (!(k in declared)) problems.push(`${at}: mapper provides '${k}', which is not an input of the step`);
     for (const [k, m] of Object.entries(recorded)) checkMapping(`${at} input '${k}'`, m, avail, isOptional(declared[k]), true);

package/src/describe/manifest-schema.ts

@@ -72,6 +72,18 @@ export const StepDescriptor = z
       .literal(true)
       .optional()
       .describe("The step pod gets the instance's step ServiceAccount token (Kubernetes:StepServiceAccount), if the instance grants one. Omitted = no token."),
+    externalInputs: z
+      .record(
+        z.string(),
+        z.strictObject({
+          model: modelName.describe("The value is validated against this model's input view."),
+          title: z.string().min(1).describe("What is asked, shown to whoever answers."),
+          description: z.string(),
+          from: z.array(z.strictObject({ kind: z.literal("person") })).min(1).describe("Who or what may answer."),
+        }),
+      )
+      .optional()
+      .describe("Inputs answered from outside the run (omitted when none): the step waits until every one has a value, which the service writes into input.json under its key."),
   })
   .meta({ id: "Step" });
 

package/src/harness/validate.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { isModel, isOptional } from "../core/models.ts";
+import { isExternal } from "../core/external.ts";
 import type { AnyStep } from "../core/steps.ts";
 
 export type Validation<T> = { ok: true; value: T } | { ok: false; issues: string[] };
@@ -39,7 +40,7 @@ export function parseStrict(schema: z.ZodType, value: unknown, prefix: string):
 }
 
 function entrySchema(e: unknown): z.ZodType {
-  if (isOptional(e)) return e.model.schema;
+  if (isOptional(e) || isExternal(e)) return e.model.schema;
   if (isModel(e)) return e.schema;
   return e as z.ZodType;
 }

package/src/index.ts

@@ -6,6 +6,7 @@ export { secret, type Secret, type DeclaredSecrets } from "./core/secrets.ts";
 export { config, secretRef, isConfigRef, type ConfigEntry, type AnyConfigEntry, type ConfigValues, type ConfigRef, type ConfigNode, type Configurable, type DiscriminatorOf, type VariantOf } from "./core/config.ts";
 export { hmacSha256, githubSignature, bearer, type WebhookVerify, type WebhookEvent } from "./core/webhooks.ts";
 export { resolveConfigRefs, isLiteral, type Resolved } from "./core/config-refs.ts";
+export { external, person, type External, type ExternalOptions, type ExternalSource } from "./core/external.ts";
 export { step, type Step, type AnyStep, type StepDef, type StepInput, type StepKind, type ConfigOf, type InputEntry, type InputSpec, type LiteralName, type OutputValue } from "./core/steps.ts";
 export type { Simplify } from "./core/types.ts";
 export { implement, type Implementation, type Handler, type HandlerResult, type Skipped } from "./core/handlers.ts";