@michaelrwalker/stagehand 0.5.3 → 0.6.1

package/skills/building-scripts/structuring-phases-and-steps/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: 'structuring-phases-and-steps'
+description: >
+  addPhase/addStep mechanics (flat and callback form), the implicit "Main" phase created on the first addStep, step and phase naming/uniqueness rules and DuplicateNameError, per-step retry/timeoutMs, and outline() for inspecting a script's declared structure without running it. Load this for "group these steps into phases," "retry a flaky step," "add a timeout to a step," or "inspect a script's structure without running it."
+metadata:
+  type: 'core'
+  library: 'stagehand'
+  library_version: '0.5.3'
+sources:
+  - 'miaklwalker/stagehand:docs/guides/phases-and-steps.md'
+  - 'miaklwalker/stagehand:docs/guides/script-options-and-result.md'
+  - 'miaklwalker/stagehand:docs/guides/reusable-scripts.md'
+  - 'miaklwalker/stagehand:docs/reference/errors.md'
+  - 'miaklwalker/stagehand:docs/reference/script.md'
+  - 'miaklwalker/stagehand:src/script.ts'
+---
+
+# Stagehand — Structuring Phases and Steps
+
+A script is built by chaining `addPhase` and `addStep` on a `Script` instance; each call returns a re-typed `Script`, so the chain itself is the script's outline. Phase boundaries are not cosmetic — they scope rollback (`rollback: "phase"`) and identify cache slots (`"phase"` for a cached phase, `"phase::step"` for a cached step).
+
+## Setup
+
+```ts
+import { Script } from "@michaelrwalker/stagehand";
+
+interface Input {
+  service: string;
+}
+
+const deploy = new Script<Input>({ name: "deploy" })
+  .addPhase("Validation")
+  .addStep({
+    name: "resolve commit",
+    handler: async ({ input }) => ({ sha: await Promise.resolve(`${input.service}-sha`) }),
+  })
+  .addPhase("Release")
+  .addStep({
+    name: "shift traffic",
+    handler: async ({ ctx }) => ({ released: ctx.sha }),
+  });
+
+const result = await deploy.run({ service: "checkout" });
+```
+
+## Core Patterns
+
+### Group steps into phases (flat and callback form)
+
+```ts
+new Script<{ n: number }>({ name: "t" })
+  .addPhase("A", (script) =>
+    script
+      .addStep({ name: "double", handler: ({ input }) => ({ doubled: input.n * 2 }) })
+      .addStep({ name: "label", handler: ({ ctx }) => ({ label: `n=${ctx.doubled}` }) }),
+  )
+  .addPhase("B")
+  .addStep({ name: "use", handler: ({ ctx }) => ({ echo: ctx.label }) });
+```
+
+The callback form groups a phase's steps visually while preserving the same type flow as the flat form; the two are interchangeable.
+
+### Retry with backoff and veto specific errors
+
+```ts
+.addStep({
+  name: "publish",
+  retry: {
+    attempts: 4,
+    delayMs: (attempt) => attempt * 200,
+    retryIf: (error) => !/^4\d\d/.test((error as Error).message),
+  },
+  handler: async ({ attempt, warn }) => {
+    if (attempt > 1) warn(`retrying (attempt ${attempt})`);
+    await publish();
+  },
+})
+```
+
+`attempts` is the total number of tries including the first; `delayMs` runs between failed attempts, and `retryIf` can veto a retry for an error that will never succeed by retrying (a 401, for instance).
+
+### Time out a step
+
+```ts
+.addStep({
+  name: "publish",
+  timeoutMs: 30_000,
+  handler: async ({ signal }) => publishWithSignal(signal),
+})
+```
+
+`timeoutMs` aborts the step's `signal` once elapsed, surfacing as `StepTimeoutError`; a timeout counts as a failed attempt, subject to the same `retryIf` if `retry` is also set.
+
+### Inspect a script's structure without running it
+
+```ts
+deploy.outline();
+// [
+//   { phase: "Validation", steps: ["resolve commit"] },
+//   { phase: "Release", steps: ["shift traffic"] },
+// ]
+```
+
+`outline()` reports every declared phase and its step names, in order, without executing any handler.
+
+## Common Mistakes
+
+### MEDIUM Reusing a step name within the same phase
+
+Wrong:
+```ts
+.addStep({ name: "validate", handler: checkA })
+.addStep({ name: "validate", handler: checkB })  // DuplicateNameError
+```
+
+Correct:
+```ts
+.addStep({ name: "validate input", handler: checkA })
+.addStep({ name: "validate permissions", handler: checkB })
+```
+
+A step name must be unique within its own phase, since a step's cache slot is `"phase::step"`; the same name in two different phases is fine, but a duplicate inside one phase throws `DuplicateNameError` at build time, before `run()` is ever called.
+
+Source: src/script.ts addStep() DuplicateNameError check; docs/reference/errors.md
+
+### MEDIUM Never calling addPhase, then relying on rollback: "phase"
+
+Wrong:
+```ts
+new Script({ name: "t", rollback: "phase" })
+  .addStep(stepA).addStep(stepB).addStep(stepC);
+// rollback: "phase" here behaves exactly like "all" — one phase, "Main"
+```
+
+Correct:
+```ts
+new Script({ name: "t", rollback: "phase" })
+  .addPhase("Prepare").addStep(stepA)
+  .addPhase("Commit").addStep(stepB).addStep(stepC);
+```
+
+`addStep` creates an implicit `"Main"` phase the first time it is called if `addPhase` was never used, so with every step in that one phase, `rollback: "phase"` and `rollback: "all"` unwind identically.
+
+Source: src/script.ts currentPhase() implicit "Main"; docs/guides/phases-and-steps.md
+
+### HIGH Chaining .addStep() directly after .use() without opening a new phase
+
+Wrong:
+```ts
+new Script({ name: "t" })
+  .use(pullChannel)
+  .addStep({ name: "sneaky", handler: () => ({}) });
+// StepDefinitionError: Cannot add a step after use()
+```
+
+Correct:
+```ts
+new Script({ name: "t" })
+  .use(pullChannel)
+  .addPhase("Report")
+  .addStep({ name: "summarize", handler: ({ ctx }) => ({}) });
+```
+
+A routine owns whole phases, so the last phase spliced in by `use()` belongs to the fragment, and a bare `addStep` right after it is refused at build time even though the fluent chain reads naturally.
+
+Source: src/script.ts currentPhase() StepDefinitionError; docs/guides/reusable-scripts.md
+
+### MEDIUM Wrapping the whole script in one giant step or phase instead of decomposing the work
+
+Wrong:
+```ts
+new Script<Input>({ name: "deploy" })
+  .addStep({
+    name: "deploy",
+    handler: async ({ input }) => {
+      const sha = await resolveSha(input.ref);
+      const artifact = await compile();
+      const uploadId = await upload(artifact);
+      await shiftTraffic(uploadId);
+      return { uploadId };
+    },
+  });
+```
+
+Correct:
+```ts
+new Script<Input>({ name: "deploy" })
+  .addPhase("Validation").addStep({ name: "resolve commit", handler: async ({ input }) => ({ sha: await resolveSha(input.ref) }) })
+  .addPhase("Build").addStep({ name: "compile bundle", handler: async () => ({ artifact: await compile() }) })
+  .addPhase("Release")
+  .addStep({ name: "upload artifact", handler: async ({ ctx }) => ({ uploadId: await upload(ctx.artifact) }), rollbackKeys: ["uploadId"], rollback: async ({ output }) => cleanup(output.uploadId) })
+  .addStep({ name: "shift traffic", handler: async ({ ctx }) => { await shiftTraffic(ctx.uploadId); return {}; } });
+```
+
+The value of phases and steps — incremental typed context, phase-scoped rollback, per-step retry/caching/observability — only shows up when the work is actually split along its natural boundaries; one opaque step gets none of it: no per-stage rollback, no per-stage cache, and a phase tree that renders as a single spinner instead of legible progress.
+
+Source: maintainer interview ("not breaking things into distinct enough stages... writing a whole script around the framework instead of using the framework to write the whole script")

package/skills/building-scripts/typed-context-and-input/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: 'typed-context-and-input'
+description: >
+  Covers how a Script's Ctx type parameter accumulates purely from addStep handler
+  return types (no hand-written generics), the input-vs-ctx distinction (input is
+  fixed for the run, ctx grows step by step), and defineInput for validating run()
+  input against any Standard Schema library (Zod, Valibot, ArkType, Effect Schema).
+  Load this for "validate my script's input," "why is this key missing from ctx,"
+  or "should I read input.x or ctx.x here."
+metadata:
+  type: 'core'
+  library: 'stagehand'
+  library_version: '0.5.3'
+sources:
+  - 'miaklwalker/stagehand:docs/guides/typed-context.md'
+  - 'miaklwalker/stagehand:docs/reference/errors.md'
+  - 'miaklwalker/stagehand:docs/reference/script.md'
+  - 'miaklwalker/stagehand:src/script.ts'
+  - 'miaklwalker/stagehand:src/types.ts'
+---
+
+# Stagehand — The Typed Context and Validated Input
+
+`Ctx`, the second type parameter on `Script`, starts as `{}` and widens every
+time `addStep` sees a handler that returns an object. Nothing about `Ctx` is
+ever written by hand — it is inferred purely from handler return types.
+
+## Setup
+
+```ts
+import { Script } from "@michaelrwalker/stagehand";
+import { z } from "zod";
+
+const deploy = new Script({ name: "deploy" })
+  .defineInput(z.object({ service: z.string() }))
+  .addStep({
+    name: "resolve commit",
+    handler: async ({ input }) => ({ sha: await git.head(input.service) }),
+    //                     ^ input.service: string
+  })
+  .addStep({
+    name: "build",
+    handler: ({ ctx }) => ({ artifact: `${ctx.sha}.tar.gz` }),
+    //                ^ ctx.sha: string, from the previous step
+  });
+
+const result = await deploy.run({ service: "api" });
+```
+
+## Core Patterns
+
+### Context widens automatically from return values
+
+```ts
+new Script({ name: "pipeline" })
+  .addStep({ name: "one", handler: () => ({ token: "x" }) })
+  // Ctx = { token: string }
+  .addStep({ name: "two", handler: ({ ctx }) => ({ n: ctx.token.length }) });
+  // Ctx = { token: string; n: number }
+```
+
+Each `ctx` parameter is typed as everything every earlier step produced (minus
+anything cleaned). A handler that returns nothing (`void`/`undefined`) leaves
+`Ctx` unchanged; returning a key that already exists overwrites it, both at
+the type level and at runtime, using `Object.assign` semantics.
+
+### Reading `input` vs `ctx`
+
+```ts
+new Script({ name: "sync" })
+  .defineInput(z.object({ tenantId: z.string() }))
+  .addStep({
+    name: "fetch",
+    // input.tenantId is fixed for the whole run
+    // ctx starts empty here, since no earlier step has run
+    handler: async ({ input }) => ({ rows: await fetchRows(input.tenantId) }),
+  })
+  .addStep({
+    name: "summarize",
+    // ctx.rows is available now; input.tenantId still is too
+    handler: ({ input, ctx }) => ({
+      summary: `${input.tenantId}: ${ctx.rows.length} rows`,
+    }),
+  });
+```
+
+`input` never changes shape mid-script (unless the step belongs to a mounted
+routine with its own mapped input). `ctx` grows step by step — that is the
+whole reason it carries the accumulating type parameter and `input` does not.
+
+### Validating `run()` input with any Standard Schema library
+
+```ts
+import { z } from "zod";
+import { SchemaValidationError } from "@michaelrwalker/stagehand";
+
+const deploy = new Script({ name: "deploy" })
+  .defineInput(z.object({ service: z.string() }));
+
+try {
+  const result = await deploy.run({ service: "api" });
+} catch (error) {
+  if (error instanceof SchemaValidationError) {
+    // error.issues: ReadonlyArray<StandardSchemaV1.Issue>
+    console.error(error.message); // "service: Required" etc., joined with "; "
+  } else {
+    throw error;
+  }
+}
+```
+
+`defineInput` accepts any [Standard Schema](https://standardschema.dev)
+validator (Zod, Valibot, ArkType, Effect Schema, or hand-rolled) and infers
+`In` from its output type. Validation runs before any phase executes.
+
+## Common Mistakes
+
+### HIGH Mutating ctx directly instead of returning new keys
+
+Wrong:
+```ts
+.addStep({
+  name: "increment",
+  handler: ({ ctx }) => {
+    ctx.total = ctx.total + 1; // "works" locally, breaks caching/rollback
+  },
+})
+```
+
+Correct:
+```ts
+.addStep({
+  name: "increment",
+  handler: ({ ctx }) => ({ total: ctx.total + 1 }),
+})
+```
+
+`ctx` is the same live object every handler shares, so a stray assignment does not throw — but only a handler's *return value* is folded into a cached phase's delta and into a rollback's `rollbackKeys` pick, so a directly-mutated key is silently never cached and invisible to any rollback that asks for it.
+
+Source: src/script.ts (merge() applied only to handler output); docs/guides/cleaning-context.md
+
+### MEDIUM Calling defineInput after addStep/addPhase, expecting it to retype earlier steps
+
+Wrong:
+```ts
+new Script({ name: "t" })
+  .addStep({ name: "one", handler: ({ input }) => ({}) }) // sees old In
+  .defineInput(z.object({ service: z.string() }));
+```
+
+Correct:
+```ts
+new Script({ name: "t" })
+  .defineInput(z.object({ service: z.string() }))
+  .addStep({ name: "one", handler: ({ input }) => ({}) }); // input.service: string
+```
+
+`defineInput` returns a re-typed `Script`; it does not retroactively change steps already added, which still see the old `In` — it must be called first, immediately after construction.
+
+Source: docs/guides/typed-context.md; src/script.ts defineInput()
+
+### HIGH Assuming a failed defineInput validation shows up in RunResult
+
+Wrong:
+```ts
+const result = await deploy.run(rawInput);
+if (!result.ok) { /* never reached on bad input — it throws instead */ }
+```
+
+Correct:
+```ts
+try {
+  const result = await deploy.run(rawInput);
+} catch (error) {
+  if (error instanceof SchemaValidationError) console.error(error.issues);
+  else throw error;
+}
+```
+
+`SchemaValidationError` is always thrown directly by `run()`, never returned as `{ ok: false }`, and is unaffected by `throwOnError` — there is no partial result to produce since no phase executed.
+
+Source: docs/guides/typed-context.md; docs/reference/errors.md
+
+See also: skills/compensation-safety/cleaning-context/SKILL.md — mutating ctx directly instead of returning it from a handler is the same "context is not just a plain mutable object" mental model both skills depend on.
+
+## References
+
+- [Context type utilities reference](references/context-type-utilities.md)

package/skills/building-scripts/typed-context-and-input/references/context-type-utilities.md

@@ -0,0 +1,121 @@
+# Context type utilities
+
+These are the type-level helpers Stagehand uses internally to compute `Ctx`,
+`RollbackContext`, and `WithStepFor` chains. All of them run automatically as
+part of `addStep`, `defineInput`, and `stepFor` — a script author almost never
+imports or writes them directly. They're documented here for the rare case of
+debugging a confusing inferred type, or hand-writing a step definition outside
+`addStep` (e.g. a shared library file) where the composed context needs to be
+spelled out explicitly.
+
+## `Prettify<T>`
+
+```ts
+export type Prettify<T> = { [K in keyof T]: T[K] } & {};
+```
+
+Flattens an intersection type (`Omit<Ctx, K> & Out`) into a single object type
+so editor hovers show a real shape (`{ a: string; b: number }`) instead of a
+chain of `&` operators. Applied automatically everywhere a context type is
+constructed — `result.ctx`, a step's `ctx` parameter, `RollbackData` — so
+there's nothing to opt into. Reach for it directly only when hand-writing a
+type alias for a shared step's context and the hover in your editor is showing
+an unreadable intersection.
+
+## `Merge<Ctx, Out>`
+
+```ts
+export type Merge<Ctx, Out> = [Out] extends [void]
+  ? Ctx
+  : [Out] extends [undefined]
+    ? Ctx
+    : Prettify<Omit<Ctx, keyof Out> & Out>;
+```
+
+Computes the context after a step contributes `Out`: later keys win over
+earlier ones of the same name (`Omit<Ctx, keyof Out> & Out`), and a handler
+that returns `void` or `undefined` leaves `Ctx` completely untouched. This is
+the type-level mirror of the runtime `Object.assign`-based merge in
+`src/script.ts`. It is the core of how every `addStep` call widens `Ctx`, and
+also underlies `WithStepFor` (see below). Almost never written by hand —
+inference through `addStep` produces it automatically.
+
+## `Cleaned<Ctx, Keys>`
+
+```ts
+export type Cleaned<Ctx, Keys extends PropertyKey> = Prettify<Omit<Ctx, Keys>>;
+```
+
+What a step's `clean` field leaves behind for every later step: `Keys` are
+dropped from both the runtime context and the type. This is what makes a
+cleaned key a genuine compile error to reach for afterward, not just a
+runtime `undefined`. Computed automatically wherever `clean` is used; there's
+no reason to reference `Cleaned` directly unless writing tooling that
+inspects a script's declared clean keys.
+
+## `RollbackData<Ctx, Keys>`
+
+```ts
+export type RollbackData<Ctx, Keys extends readonly PropertyKey[]> = Pick<
+  Ctx,
+  Extract<Keys[number], keyof Ctx>
+>;
+```
+
+The slice of context a `rollback` function actually receives: exactly the
+keys named in that step's `rollbackKeys`, and nothing else. With no keys
+declared, this resolves to `{}` — a rollback has to explicitly ask for what
+it needs via `rollbackKeys`; it cannot see the full `Ctx`. `addStep` uses this
+(wrapped in `Prettify`) to type the `ctx` parameter of `RollbackContext`. You
+would only reference `RollbackData` directly when writing a rollback handler
+outside `addStep` and need to spell out its parameter type by hand.
+
+## `WithStepFor<Step, Rest>`
+
+```ts
+export type WithStepFor<
+  Step extends { handler: (context: never) => unknown },
+  Rest extends object = {},
+> = Step extends { handler: (context: never) => infer Out }
+  ? Merge<Rest, Awaited<Out>>
+  : never;
+```
+
+Computes the context a *later* step sees, given an earlier step (declared
+with `stepFor`) and whatever else is already there (`Rest`). This is the one
+utility from this file developers reach for directly on a regular basis — it
+is the mechanism behind [Splitting Steps Across Files](../../../reuse/splitting-steps-across-files/SKILL.md):
+
+```ts
+export const logIntoDb = stepFor<Input>()({
+  name: "log into db",
+  handler: async () => ({ conn: await connect() }),
+});
+
+export const loadRules = stepFor<
+  Input,
+  WithStepFor<typeof logIntoDb, { conditions: Array<{ name: string }> }>
+>()({
+  name: "load rules",
+  //     ctx.conn — from the step; ctx.conditions — from the rest
+  handler: ({ ctx }) => ({ rules: ctx.conn.query(ctx.conditions) }),
+});
+```
+
+It nests for chains of steps, without a separate variadic form:
+
+```ts
+WithStepFor<typeof second, WithStepFor<typeof first, { conditions: string[] }>>
+```
+
+Read inside out: start with `{ conditions: string[] }`, add what `first`
+returns, then what `second` returns. That's also the precedence — on a name
+collision the outermost step wins, matching the way a later step's return
+value shadows an earlier key at runtime. Order the nesting to match the order
+the steps actually run in, or the type and the runtime disagree.
+
+`WithStepFor` only reads the step's *output* — its own `Ctx` requirement
+against `Rest` is not checked here; that check still happens when the step
+definition is passed to `addStep` on a real script. A step returning nothing
+leaves `Rest` untouched, and an `async` handler's return is awaited first
+(`Awaited<Out>`), so both fall out without a special case.