@specbook/core 0.2.0 → 0.4.0

package/src/runner/run.ts

@@ -11,6 +11,7 @@ import {
   isFakerName,
   isPlainObject,
   render,
+  rootName,
 } from '../template'
 import type {
   ApiResponse,
@@ -23,7 +24,12 @@ import type {
   VarUse,
 } from '../types'
 import { describeFiles, isBlob } from './encode'
-import type { PreparedRequest, RawResponse, Transport } from './transport'
+import {
+  DEFAULT_TIMEOUT_MS,
+  type PreparedRequest,
+  type RawResponse,
+  type Transport,
+} from './transport'
 
 // ---------------- public options ----------------
 
@@ -41,12 +47,22 @@ export interface AuthProfile {
   token?: (res: ApiResponse<number, any>) => Session
   apply: { headers?: Record<string, string>; query?: Record<string, string> }
   retryOn401?: boolean
-  /** an interactive sign-in the UI can offer (authorization code with PKCE); the runner ignores it */
+  /**
+   * an interactive sign-in the UI can offer (authorization code with PKCE); the runner ignores it.
+   * `authorizationUrl`, `tokenUrl`, `openIdConnectUrl` and `clientId` may use environment variables
+   * (`'{{issuer}}/token'`).
+   */
   oauth?: OAuthSettings
 }
 
 export type RunEvent =
-  | { type: 'run:start'; id: string }
+  | {
+      type: 'run:start'
+      id: string
+      title?: string
+      kind?: 'request' | 'sequence'
+      tags?: string[]
+    }
   | { type: 'step:start'; name: string }
   | { type: 'auth:login'; profile: string }
   | { type: 'request'; name: string; request: RenderedRequest }
@@ -60,21 +76,31 @@ export type RunEvent =
 
 export interface RunOptions {
   env: string
-  /** config.vars merged with environments[env].vars. */
+  /** config.vars, then environments[env].vars, then the environment's file. */
   vars?: Record<string, unknown>
   /** Highest-precedence overrides (UI vars panel, CLI --var). */
   overrides?: Record<string, unknown>
-  /** Sequence param overrides. */
-  params?: Record<string, unknown>
+  /** Flow input values: the ones a person would set (UI controls, CLI --input). */
+  inputs?: Record<string, unknown>
   transport: Transport
   /** Resolved secret values, keyed by secret name. Not needed in the mock env. */
   secrets?: Record<string, string>
+  /**
+   * Refuse to send a request that may change data (anything but GET, HEAD and OPTIONS, a GraphQL mutation, or a request
+   * not marked `safe`). Auth logins are exempt. For runs against real environments that must not write.
+   */
+  readOnly?: boolean
+  /**
+   * A request with no `assert` of its own passes only on a 2xx response (recorded as the assertion `status is 2xx`);
+   * one with an `assert` is judged by that alone. Off, a request with no `assert` passes whatever the status.
+   */
+  implicitStatusCheck?: boolean
   /** Leave `{{secrets.*}}` placeholders in the wire request (a trusted server substitutes them). */
   deferSecrets?: boolean
   auth?: Record<string, AuthProfile>
   /** service -> default auth profile name. */
   serviceAuth?: Record<string, string>
-  /** Called at `input()` steps; omit for headless (params override > default > first option). */
+  /** Called at `input()` steps; omit for headless (inputs given > default > first option). */
   onInput?: (req: {
     name: string
     controls: ReturnType<typeof describeControls>
@@ -91,6 +117,13 @@ export interface RunOptions {
   example?: ExampleLoader
   /** Reads files named by upload fields (path relative to the example's `dir`). */
   readFile?: FileReader
+  /**
+   * How long each request waits for an answer, in milliseconds, when the request does not say (`timeoutMs` on the request
+   * wins). 0 waits for as long as it takes. Default: 30 seconds.
+   */
+  timeoutMs?: number
+  /** The `mock` environment answers with this status (the UI's "Respond with"). */
+  mockStatus?: number
 }
 
 // ---------------- internals ----------------
@@ -169,7 +202,7 @@ function usesOf(
   const out: VarUse[] = []
   for (const name of names) {
     if (isDeferred(name) || isFakerName(name)) continue
-    const key = name.split('.')[0] as string
+    const key = rootName(name)
     if (seen.has(key)) continue
     seen.add(key)
     for (let i = layers.length - 1; i >= 0; i--) {
@@ -222,8 +255,22 @@ function substitute<T>(value: T, rt: Runtime, profile?: string): T {
   return walk(value) as T
 }
 
+/** Events are masked as they are emitted: a listener (a stream, a log) must never see a secret value. */
 function emit(rt: Runtime, e: RunEvent) {
-  rt.o.onEvent?.(e)
+  rt.o.onEvent?.(rt.mask.size ? maskDeep(e, rt.mask) : e)
+}
+
+const READ_METHODS = new Set(['GET', 'HEAD', 'OPTIONS'])
+
+/** True when the request cannot change data: a read method, a GraphQL query, or one marked `safe`. */
+function isReadOnly(def: RequestDef<any, any, any>, prepared: PreparedRequest): boolean {
+  if (def.input.safe) return true
+  if (READ_METHODS.has(prepared.method)) return true
+  if (prepared.encoding === 'graphql') {
+    const body = prepared.body as { query?: unknown } | undefined
+    return typeof body?.query === 'string' && !/(^|[\s}])mutation\b/.test(body.query)
+  }
+  return false
 }
 
 function profileFor(rt: Runtime, def: RequestDef<any, any, any>): string | undefined {
@@ -289,13 +336,13 @@ async function ensureSession(
 
 /** What earlier steps and the sequence hand to a request. */
 interface Flow {
-  params: Record<string, unknown>
+  inputs: Record<string, unknown>
   captured: Record<string, unknown>
   /** capture name -> the step that produced it */
   from: Record<string, string>
 }
 
-const NO_FLOW: Flow = { params: {}, captured: {}, from: {} }
+const NO_FLOW: Flow = { inputs: {}, captured: {}, from: {} }
 
 interface ExecOut {
   result: StepResult
@@ -328,7 +375,7 @@ async function execute(
     const layers: [VarUse['source'], Record<string, unknown>][] = [
       ['config', rt.o.vars ?? {}],
       ['init', evalInit(def.input.init)],
-      ['param', flow.params],
+      ['input', flow.inputs],
       ['capture', flow.captured],
       ['override', evalInit(def.varOverrides)],
       ['override', rt.o.overrides ?? {}],
@@ -388,12 +435,12 @@ async function execute(
       encoding,
       mediaType: encoding === 'binary' ? def.op.mediaType : undefined,
       formArrays: def.op.formArrays,
-      timeoutMs: def.input.timeoutMs,
-      mockStatus: rt.o.env === 'mock' ? def.input.mock?.status : undefined,
+      timeoutMs: def.input.timeoutMs ?? rt.o.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      mockStatus: rt.o.env === 'mock' ? rt.o.mockStatus : undefined,
       mock:
         rt.o.env === 'mock'
           ? {
-              config: def.input.mock,
+              hook: def.mockHook,
               vars: scope,
               pathParams,
               rawQuery: query,
@@ -412,6 +459,10 @@ async function execute(
       profile,
     }
     emit(rt, { type: 'request', name, request: result.request })
+    if (rt.o.readOnly && kind !== 'auth' && !isReadOnly(def, prepared))
+      throw new StepError(
+        `Refusing ${prepared.method} ${def.op.path} in "${rt.o.env}": this is a --safe run, which only reads.`,
+      )
 
     const send = async () => {
       if (profile) await ensureSession(rt, profile, authResults)
@@ -458,6 +509,17 @@ async function execute(
       for (const r of a.results) {
         emit(rt, { type: r.pass ? 'assert:pass' : 'assert:fail', name, assertion: r })
       }
+    } else if (rt.o.implicitStatusCheck && kind === 'request') {
+      const pass = response.status >= 200 && response.status < 300
+      const implicit: AssertionResult = {
+        label: 'status is 2xx',
+        operator: 'status',
+        pass,
+        actual: response.status,
+        expected: '2xx',
+      }
+      result.assertions = [implicit]
+      emit(rt, { type: pass ? 'assert:pass' : 'assert:fail', name, assertion: implicit })
     }
     if (result.status === 'pass' && result.assertions.some((r) => !r.pass)) result.status = 'fail'
   } catch (e: any) {
@@ -583,7 +645,13 @@ export async function collectSecretNames(
 }
 
 function newRuntime(o: RunOptions): Runtime {
-  return { o, sessions: new Map(), inflight: new Map(), mask: new Set() }
+  // every resolved secret is masked from the start, not only once it has been substituted into a request
+  return {
+    o,
+    sessions: new Map(),
+    inflight: new Map(),
+    mask: new Set(Object.values(o.secrets ?? {})),
+  }
 }
 
 export async function runRequest(
@@ -592,10 +660,22 @@ export async function runRequest(
 ): Promise<RunResult> {
   const rt = newRuntime(o)
   const t0 = o.now?.() ?? now0()
-  emit(rt, { type: 'run:start', id: def.op.id })
+  emit(rt, {
+    type: 'run:start',
+    id: def.op.id,
+    title: def.input.name ?? def.op.id,
+    kind: 'request',
+    tags: def.input.tags,
+  })
   const name = def.input.name ?? def.op.id
   const { result, authResults } = await execute(rt, def, name, NO_FLOW)
-  return finish(rt, 'request', { id: def.op.id, title: name }, [...authResults, result], t0)
+  return finish(
+    rt,
+    'request',
+    { id: def.op.id, title: name, tags: def.input.tags },
+    [...authResults, result],
+    t0,
+  )
 }
 
 export async function runSequence(seq: Sequence<any, any>, o: RunOptions): Promise<RunResult> {
@@ -603,7 +683,13 @@ export async function runSequence(seq: Sequence<any, any>, o: RunOptions): Promi
   rt.seqAuth = seq.meta.auth
   rt.seqAssertMode = seq.meta.assertMode
   const t0 = o.now?.() ?? now0()
-  emit(rt, { type: 'run:start', id: seq.meta.id })
+  emit(rt, {
+    type: 'run:start',
+    id: seq.meta.id,
+    title: seq.meta.title,
+    kind: 'sequence',
+    tags: seq.meta.tags,
+  })
   const steps: StepResult[] = []
   const captured: Record<string, any> = {}
   const from: Record<string, string> = {}
@@ -611,12 +697,12 @@ export async function runSequence(seq: Sequence<any, any>, o: RunOptions): Promi
     Object.assign(captured, values)
     for (const k of Object.keys(values)) from[k] = step
   }
-  let params: Record<string, unknown>
+  let inputs: Record<string, unknown>
   try {
-    params = resolveControls(seq.meta.params ?? {}, o.params)
+    inputs = resolveControls(seq.meta.inputs ?? {}, o.inputs)
   } catch (e: any) {
     steps.push({
-      name: 'params',
+      name: 'inputs',
       kind: 'input',
       status: 'error',
       assertions: [],
@@ -628,7 +714,7 @@ export async function runSequence(seq: Sequence<any, any>, o: RunOptions): Promi
   }
   const vars = o.vars ?? {}
   const ctx = (): StepCtx<any, any> => ({
-    params,
+    inputs,
     captured,
     vars: { ...vars, ...(o.overrides ?? {}) },
     env: o.env,
@@ -652,7 +738,7 @@ export async function runSequence(seq: Sequence<any, any>, o: RunOptions): Promi
       if (node.kind === 'step') {
         const def = typeof node.def === 'function' ? node.def(ctx()) : node.def
         const { result, authResults } = await execute(rt, def, node.name, {
-          params,
+          inputs,
           captured,
           from,
         })
@@ -675,7 +761,7 @@ export async function runSequence(seq: Sequence<any, any>, o: RunOptions): Promi
         for (let i = 0; i < items.length; i++) {
           const def = node.def(items[i], ctx(), i)
           const { result, authResults } = await execute(rt, def, `${node.name} #${i + 1}`, {
-            params,
+            inputs,
             captured,
             from,
           })
@@ -700,9 +786,9 @@ export async function runSequence(seq: Sequence<any, any>, o: RunOptions): Promi
         emit(rt, { type: 'input:required', name: node.name, controls: described })
         const given = o.onInput
           ? await o.onInput({ name: node.name, controls: described })
-          : (o.params ?? {})
+          : (o.inputs ?? {})
         const values = resolveControls(controls, given)
-        params = { ...params, ...values }
+        inputs = { ...inputs, ...values }
         steps.push({
           name: node.name,
           kind: 'input',

package/src/runner/suite.ts

@@ -0,0 +1,122 @@
+// Running a list of requests and flows the way `specbook test` does: in order, retrying a failure, stopping at a number of
+// failures or at a global deadline. The CLI and the docs site's terminal share it, so what the page shows is what a
+// terminal does. Nothing here touches files or the process.
+
+import type { Colors } from '../reporters/color'
+import type { Sequence } from '../sequence'
+import type { RequestDef, RunResult } from '../types'
+import { type RunOptions, runRequest, runSequence } from './run'
+
+export interface SuiteTarget {
+  title: string
+  /** project file, shown in reports */
+  file?: string
+  tags: string[]
+  run: RequestDef<any, any, any> | Sequence<any, any>
+}
+
+export interface SuiteOptions {
+  /** what every run is given; `signal` is the suite's own */
+  run: Omit<RunOptions, 'signal'>
+  /** extra tries for a failing target (0 = one try) */
+  retries?: number
+  /** stop after this many failed targets */
+  bail?: number
+  /** milliseconds after which no further target starts, and a running one is aborted */
+  globalTimeoutMs?: number
+  /** called before each try, e.g. to seed faker again */
+  beforeAttempt?: () => void
+  /** called when a failing target is about to be tried again */
+  onRetry?: (target: SuiteTarget, attempt: number, allowed: number) => void
+}
+
+export interface SuiteResult {
+  results: RunResult[]
+  failures: number
+  /** targets that did not start */
+  notRun: number
+  /** why the suite stopped early; empty when it did not */
+  stopped: string
+}
+
+export async function runSuite(targets: SuiteTarget[], o: SuiteOptions): Promise<SuiteResult> {
+  const controller = new AbortController()
+  const deadline = o.globalTimeoutMs
+    ? setTimeout(() => controller.abort(), o.globalTimeoutMs)
+    : undefined
+  const results: RunResult[] = []
+  const allowed = 1 + Math.max(0, o.retries ?? 0)
+  let failures = 0
+  let notRun = 0
+  let stopped = ''
+  for (const [i, t] of targets.entries()) {
+    if (controller.signal.aborted) {
+      notRun = targets.length - i
+      stopped = `stopped: the global timeout of ${o.globalTimeoutMs}ms passed`
+      break
+    }
+    let result: RunResult | undefined
+    let attempt = 0
+    while (attempt < allowed) {
+      attempt++
+      o.beforeAttempt?.()
+      const opts = { ...o.run, signal: controller.signal }
+      result =
+        t.run.kind === 'sequence' ? await runSequence(t.run, opts) : await runRequest(t.run, opts)
+      if (result.status === 'pass' || controller.signal.aborted) break
+      if (attempt < allowed) o.onRetry?.(t, attempt + 1, allowed)
+    }
+    const final = result as RunResult
+    results.push({
+      ...final,
+      file: t.file,
+      attempts: attempt,
+      flaky: final.status === 'pass' && attempt > 1,
+      tags: final.tags.length ? final.tags : t.tags,
+    })
+    if (final.status !== 'pass') failures++
+    if (o.bail && failures >= o.bail && i < targets.length - 1) {
+      notRun = targets.length - i - 1
+      stopped = `stopped after ${failures} failed ${failures === 1 ? 'flow' : 'flows'} (--bail)`
+      break
+    }
+  }
+  if (deadline) clearTimeout(deadline)
+  return { results, failures, notRun, stopped }
+}
+
+/** The line a run opens with: the tool and version, then what is being run and where. */
+export function headerLine(
+  h: {
+    version: string
+    env: string
+    picked: number
+    total: number
+    /** `main@abc1234`, `bundle <sha> built <date>` */
+    where?: string[]
+  },
+  colors: Colors,
+): string {
+  return `${colors.bold(`specbook test ${h.version}`)}  ${colors.dim(
+    [
+      `env ${h.env}`,
+      `${h.picked}${h.picked < h.total ? `/${h.total}` : ''} tests`,
+      ...(h.where ?? []),
+    ].join('  ·  '),
+  )}\n\n`
+}
+
+/** What a retry looks like in a terminal. */
+export const retryLine = (colors: Colors, title: string, attempt: number, allowed: number) =>
+  `  ${colors.yellow('↻')} retrying ${title} (attempt ${attempt} of ${allowed})\n`
+
+/** A bundle's assertions point into the bundled file, which tells a reader nothing. */
+export function withoutLocations(results: RunResult[]): RunResult[] {
+  const strip = (steps: RunResult['steps']): RunResult['steps'] =>
+    steps.map((s) => ({
+      ...s,
+      assertions: s.assertions.map((a) => ({ ...a, location: undefined })),
+      ...(s.children ? { children: strip(s.children) } : {}),
+    }))
+  return results.map((r) => ({ ...r, steps: strip(r.steps) }))
+}

package/src/runner/transport.ts

@@ -16,11 +16,11 @@ export interface PreparedRequest {
   /** Array style per form field, from the spec's `encoding` object. */
   formArrays?: Record<string, FormArrays>
   timeoutMs?: number
-  /** Mock status the caller wants served (mock env only). */
+  /** Mock status the caller wants served, e.g. the UI's "Respond with" (mock env only). */
   mockStatus?: number
   /** In-process hints for the mock transport; never serialized or substituted. */
   mock?: {
-    config?: import('../types').MockInput<any, any>
+    hook?: import('../types').MockHook<any, any>
     vars: Record<string, unknown>
     pathParams: Record<string, unknown>
     rawQuery: Record<string, unknown>
@@ -46,6 +46,52 @@ export function buildUrl(base: string, req: PreparedRequest): string {
   return `${base.replace(/\/+$/, '')}${req.url}${q ? `?${q}` : ''}`
 }
 
+/** A config `baseUrl` may be relative (`/api/v1`): it is resolved against the page. */
+export function absoluteBase(baseUrl: string, pageHref?: string): string {
+  try {
+    return new URL(baseUrl, pageHref).toString()
+  } catch {
+    return baseUrl
+  }
+}
+
+/** How long a request waits for an answer when nothing says otherwise. */
+export const DEFAULT_TIMEOUT_MS = 30_000
+
+/** What node's fetch says in `error.cause.code`, in words a person can act on. */
+const WHY: Record<string, string> = {
+  ECONNREFUSED: 'connection refused',
+  ENOTFOUND: 'host not found',
+  EAI_AGAIN: 'host not found',
+  ECONNRESET: 'connection reset',
+  ETIMEDOUT: 'connection timed out',
+  UND_ERR_CONNECT_TIMEOUT: 'connection timed out',
+  EHOSTUNREACH: 'host unreachable',
+  ENETUNREACH: 'network unreachable',
+}
+
+/** node's bare "fetch failed" says nothing; its cause says why. A browser gives no cause, so its error is left as it is. */
+function unreachable(e: unknown, url: string): unknown {
+  const cause = (
+    e as { cause?: { code?: string; message?: string; errors?: { code?: string }[] } } | undefined
+  )?.cause
+  if (!(e instanceof TypeError) || !cause) return e
+  const code = cause.code ?? cause.errors?.find((x) => x.code)?.code
+  const tls =
+    code && /^CERT_|^ERR_TLS|SELF_SIGNED|UNABLE_TO_VERIFY/.test(code) ? 'certificate problem' : ''
+  // a reason there are words for, else the cause's own message ("bad port"), else nothing to add
+  const own = typeof cause.message === 'string' && cause.message.length <= 120 ? cause.message : ''
+  const why = (code && WHY[code]) || tls || own
+  if (!why) return e
+  let host = url
+  try {
+    host = new URL(url).host
+  } catch {
+    /* an address that is not a URL is shown as it is */
+  }
+  return new Error(`Could not reach ${host}: ${why}.`, { cause: e })
+}
+
 export interface FetchTransportOptions {
   baseUrl: (service: string) => string
   fetch?: typeof fetch
@@ -53,6 +99,8 @@ export interface FetchTransportOptions {
 
 export function createFetchTransport(opts: FetchTransportOptions): Transport {
   return async (req, signal) => {
+    // a run stopped before this request left: nothing is sent, and no 'abort' will ever be heard from a signal that has fired
+    if (signal?.aborted) throw new Error('Stopped before the API answered.')
     const f = opts.fetch ?? fetch
     const headers: Record<string, string> = { ...req.headers }
     let body: BodyInit | undefined
@@ -61,13 +109,19 @@ export function createFetchTransport(opts: FetchTransportOptions): Transport {
       body = enc.body
       if (enc.contentType) headers['content-type'] ??= enc.contentType
     }
-    if (req.mockStatus !== undefined) headers['x-specbook-mock-status'] = String(req.mockStatus)
 
     const ctl = new AbortController()
-    const timer = req.timeoutMs ? setTimeout(() => ctl.abort(), req.timeoutMs) : undefined
+    let timedOut = false
+    const timer = req.timeoutMs
+      ? setTimeout(() => {
+          timedOut = true
+          ctl.abort()
+        }, req.timeoutMs)
+      : undefined
     signal?.addEventListener('abort', () => ctl.abort())
+    const url = buildUrl(opts.baseUrl(req.service), req)
     try {
-      const res = await f(buildUrl(opts.baseUrl(req.service), req), {
+      const res = await f(url, {
         method: req.method,
         headers,
         body,
@@ -88,6 +142,12 @@ export function createFetchTransport(opts: FetchTransportOptions): Transport {
         }
       }
       return { status: res.status, headers: outHeaders, text, body: parsed }
+    } catch (e) {
+      // an abort that the request's own timeout caused says so, not "This operation was aborted"
+      if (timedOut) throw new Error(`Timed out after ${req.timeoutMs}ms: no answer from the API.`)
+      // a person pressing Stop, or the run's own deadline: say so, not "This operation was aborted"
+      if (signal?.aborted) throw new Error('Stopped before the API answered.')
+      throw unreachable(e, url)
     } finally {
       if (timer) clearTimeout(timer)
     }

package/src/secrets.ts

@@ -67,9 +67,38 @@ export async function resolveSecrets(
   return out
 }
 
-/** Masks with `***`, longest first so a secret containing another is hidden whole; values under 4 chars are skipped to avoid masking ordinary text */
+/** Secrets shorter than this are not masked: they would blank out ordinary text. */
+const MIN_MASKED = 3
+
+/**
+ * A secret as it can appear in a URL, a JSON string or a Basic-auth style base64 value, besides itself: what a server
+ * echoes back or an error message quotes is not always the raw value.
+ */
+export function maskVariants(secret: string): string[] {
+  const out = new Set<string>([secret])
+  const add = (f: () => string) => {
+    try {
+      out.add(f())
+    } catch {
+      /* not encodable: the raw value is still masked */
+    }
+  }
+  add(() => encodeURIComponent(secret))
+  add(() => encodeURI(secret))
+  add(() => JSON.stringify(secret).slice(1, -1))
+  add(() => btoa(String.fromCharCode(...new TextEncoder().encode(secret))))
+  return [...out]
+}
+
+/**
+ * Masks with `***`, longest first so a secret containing another is hidden whole. Every secret is masked in its
+ * raw, URL-encoded, JSON-escaped and base64 forms; values under 3 characters are skipped to avoid masking
+ * ordinary text.
+ */
 export function maskDeep<T>(value: T, secrets: Iterable<string>): T {
-  const list = [...secrets].filter((s) => s.length >= 4).sort((a, b) => b.length - a.length)
+  const list = [
+    ...new Set([...secrets].filter((s) => s.length >= MIN_MASKED).flatMap(maskVariants)),
+  ].sort((a, b) => b.length - a.length)
   if (list.length === 0) return value
   const maskStr = (s: string) => list.reduce((acc, v) => acc.split(v).join('***'), s)
   const walk = (v: unknown): unknown => {

package/src/sequence.ts

@@ -2,7 +2,7 @@ import type { Controls, InferControls } from './controls'
 import type { Assert, AssertMode, AuthProfileName, RequestDef } from './types'
 
 export interface StepCtx<P, C> {
-  params: P
+  inputs: P
   captured: C
   vars: Record<string, unknown>
   env: string
@@ -34,7 +34,7 @@ export interface SequenceMeta {
   tags?: string[]
   /** Heading the flow is listed under in the catalog; flows without one are under "Default". */
   group?: string
-  params?: Controls
+  inputs?: Controls
   auth?: AuthProfileName | false
   assertMode?: AssertMode
   continueOnFailure?: boolean
@@ -55,7 +55,7 @@ export interface Sequence<P = {}, C = {}> {
     name: string,
     fn: (ctx: StepCtx<P, C>, h: { assert: Assert }) => void | Promise<void>,
   ): Sequence<P, C>
-  /** Pause for user input; the chosen values merge into ctx.params. */
+  /** Pause for user input; the chosen values merge into ctx.inputs. */
   input<R extends Controls>(
     name: string,
     controls: (ctx: StepCtx<P, C>) => R,
@@ -77,7 +77,7 @@ function build(meta: SequenceMeta, nodes: readonly StepNode[]): Sequence<any, an
 }
 
 export function sequence<P extends Controls = {}>(
-  meta: Omit<SequenceMeta, 'params'> & { params?: P },
+  meta: Omit<SequenceMeta, 'inputs'> & { inputs?: P },
 ): Sequence<InferControls<P>, {}> {
   return build(meta, [])
 }