@michaelrwalker/stagehand 0.5.3 → 0.6.0

package/skills/building-scripts/getting-started/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: 'getting-started'
+description: >
+  Build a complete Stagehand script end to end — Script constructor, addPhase/addStep, a handler
+  that widens the typed context, a rollback, and reading the RunResult. Load this first for any
+  "write my first script" or "turn this async function chain into Stagehand" request.
+metadata:
+  type: 'lifecycle'
+  library: 'stagehand'
+  library_version: '0.5.3'
+sources:
+  - 'miaklwalker/stagehand:README.md'
+  - 'miaklwalker/stagehand:docs/quick-start.md'
+  - 'miaklwalker/stagehand:docs/guides/script-options-and-result.md'
+  - 'miaklwalker/stagehand:docs/guides/cleaning-context.md'
+  - 'miaklwalker/stagehand:src/script.ts'
+  - 'miaklwalker/stagehand:src/types.ts'
+---
+
+# Stagehand — Getting Started
+
+A script is a `Script<Input>` built by chaining `addPhase`/`addStep`. Each step's handler reads
+`input` and the typed `ctx` accumulated so far, and whatever it returns is merged into `ctx` for
+every later step. `run()` never throws by default — it resolves to a discriminated `RunResult`.
+
+## 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, status }) => {
+      status("querying git");
+      return { sha: await resolveSha(input.service) };
+    },
+  })
+  .addPhase("Release")
+  .addStep({
+    name: "upload artifact",
+    handler: async ({ ctx }) => {
+      // ctx.sha is typed here — produced by the previous step
+      return { uploadId: await upload(ctx.sha) };
+    },
+    rollbackKeys: ["sha"],
+    rollback: async ({ ctx, output }) => {
+      await cdn.delete(output.uploadId, ctx.sha);
+    },
+  });
+
+const result = await deploy.run({ service: "api" });
+
+if (result.ok) {
+  console.log(`released ${result.ctx.uploadId} from ${result.ctx.sha}`);
+} else {
+  console.error(`failed at ${result.failedAt?.phase} › ${result.failedAt?.step}`);
+  console.error(result.error);
+  process.exitCode = 1;
+}
+```
+
+## Core Patterns
+
+### Grouping steps into phases
+
+```ts
+new Script<{ id: string }>({ name: "provision" })
+  .addPhase("Fetch")
+  .addStep({
+    name: "load user",
+    handler: async ({ input }) => ({ user: await db.user(input.id) }),
+  })
+  .addPhase("Provision")
+  .addStep({
+    name: "create tenant",
+    handler: async ({ ctx }) => ({ tenantId: await api.create(ctx.user.org) }),
+  });
+```
+
+`addPhase` opens a new phase; every `addStep` that follows lands in it until the next `addPhase`.
+
+### Context accumulates purely from what a handler returns
+
+```ts
+new Script<{ id: string }>()
+  .addStep({ handler: () => ({ token: "x" }) }) // Ctx = { token: string }
+  .addStep({ handler: ({ ctx }) => ({ n: ctx.token.length }) });
+// Ctx = { token: string; n: number }
+```
+
+No generic is written by hand — each handler's return value widens `Ctx` for every step after it,
+and a handler that returns nothing leaves it unchanged.
+
+### Compensating a mutation with rollback and rollbackKeys
+
+```ts
+new Script<{ accountId: string; amount: number }>({ name: "charge" })
+  .addStep({ name: "read input", handler: ({ input }) => ({ ...input }) })
+  .addStep({
+    name: "reserve funds",
+    handler: async ({ ctx }) => ({ reservationId: await reserve(ctx.accountId, ctx.amount) }),
+    rollbackKeys: ["accountId", "reservationId"],
+    rollback: async ({ ctx }) => {
+      // ctx is { accountId: string; reservationId: string } — and nothing else
+      await release(ctx.accountId, ctx.reservationId);
+    },
+  })
+  .addStep({
+    name: "charge card",
+    handler: () => {
+      throw new Error("payment gateway timeout");
+    },
+  });
+```
+
+Only steps that already succeeded get compensated, in reverse order, when a later step throws;
+`rollbackKeys` narrows what the rollback's `ctx` contains to exactly those keys.
+
+### Naming a script with the bare-string shorthand
+
+```ts
+const validate = new Script("validate") // shorthand for { name: "validate" }
+  .addStep({ name: "check input", handler: ({ input }) => ({ ok: true }) });
+```
+
+Reach for the object form (`{ name, description, rollback, throwOnError, ... }`) once you need
+anything beyond the name.
+
+## Common Mistakes
+
+### CRITICAL Wrapping run() in try/catch expecting it to throw
+
+Wrong:
+```ts
+try {
+  const result = await deploy.run(input);
+  console.log("deployed", result.ctx.releaseId);
+} catch (e) {
+  console.error(e);
+}
+```
+
+Correct:
+```ts
+const result = await deploy.run(input);
+if (!result.ok) {
+  console.error(result.error);
+  process.exitCode = 1;
+  return;
+}
+console.log("deployed", result.ctx.releaseId);
+```
+
+`run()` resolves to `{ ok: false, ... }` by default; nothing throws unless `throwOnError` is set, so the try/catch never fires and a failed run is silently treated as if it succeeded.
+
+Source: docs/guides/script-options-and-result.md; src/script.ts run()
+
+### MEDIUM Mutating ctx directly instead of returning new keys
+
+Wrong:
+```ts
+handler: ({ ctx }) => {
+  ctx.total = ctx.total + 1; // "works" locally, breaks caching/rollback
+};
+```
+
+Correct:
+```ts
+handler: ({ ctx }) => ({ total: ctx.total + 1 });
+```
+
+`ctx` is the same live object every handler shares, 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 never gets cached and is invisible to any rollback that asks for it.
+
+Source: src/script.ts (const ctx = {} as Ctx & Record<string, unknown>; merge() only applied to handler output); docs/guides/cleaning-context.md
+
+### HIGH Returning a bare value from a handler instead of an object
+
+Wrong:
+```ts
+handler: () => {
+  const value = "me";
+  return value; // compile error — Out must be object | void
+};
+```
+
+Correct:
+```ts
+handler: () => {
+  const value = "me";
+  return { name: value };
+};
+```
+
+A handler must resolve to `object | void` because whatever it returns is merged into `ctx` by key; TypeScript rejects a bare return at compile time (`Out extends object | void`), but reaching for `return value` out of habit still costs an extra iteration.
+
+Source: src/types.ts StepDef.handler / src/script.ts addStep<Out extends object | void>(...)
+
+### HIGH Tension: Simple first draft vs. rollbackKeys reservation permanence
+
+The simplest script has no `rollbackKeys` and no `clean` conflicts, but adding a rollback later to harden a working script permanently reserves whatever keys it names via `rollbackKeys`. Agents optimizing for this skill's goal tend to bolt a rollback onto a working script without revisiting existing `clean` calls elsewhere because they don't account for cleaning-context's key-reservation rule, which then throws `StepDefinitionError` at build time and reads as an unrelated regression.
+
+See also: skills/compensation-safety/adding-rollbacks/SKILL.md, skills/compensation-safety/cleaning-context/SKILL.md § Common Mistakes
+
+See also: skills/errors-results/handling-results-and-errors/SKILL.md — the very first script already needs correct RunResult handling; run() resolving instead of throwing is the single most consequential thing to get right early.

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)