@michaelrwalker/stagehand 0.7.0 → 0.9.0

package/skills/compensation-safety/adding-rollbacks/SKILL.md

@@ -10,7 +10,7 @@ description: >
 metadata:
   type: 'core'
   library: 'stagehand'
-  library_version: '0.5.3'
+  library_version: '0.8.0'
 sources:
   - 'miaklwalker/stagehand:docs/guides/rollbacks.md'
   - 'miaklwalker/stagehand:docs/reference/errors.md'
@@ -26,6 +26,8 @@ completed, first undone. The step that actually failed is never compensated: it
 there's nothing to undo. A rollback gets no context by default; it has to name every key it needs
 through `rollbackKeys`, which both narrows and permanently reserves them.
 
+Rollback timing, retries and scope are specified exactly in docs/guides/error-handling.md (summary: skills/errors-results/handling-results-and-errors/SKILL.md, "The failure contract"). Notably, retries do not trigger rollback and the failed step is never rolled back.
+
 ## Setup
 
 ```ts

package/skills/compensation-safety/cleaning-context/SKILL.md

@@ -5,7 +5,7 @@ description: >
 metadata:
   type: 'core'
   library: 'stagehand'
-  library_version: '0.5.3'
+  library_version: '0.8.0'
 sources:
   - 'miaklwalker/stagehand:docs/guides/cleaning-context.md'
   - 'miaklwalker/stagehand:src/script.ts'

package/skills/compensation-safety/conditional-steps/SKILL.md

@@ -8,16 +8,17 @@ description: >
 metadata:
   type: 'core'
   library: 'stagehand'
-  library_version: '0.5.3'
+  library_version: '0.8.0'
 sources:
   - 'miaklwalker/stagehand:docs/guides/phases-and-steps.md'
   - 'miaklwalker/stagehand:docs/guides/reusable-scripts.md'
+  - 'miaklwalker/stagehand:docs/guides/flags.md'
   - 'miaklwalker/stagehand:src/script.ts'
 ---
 
 # Stagehand — Conditional Steps and Phases
 
-`when` on `addStep` or `addPhase` is a function of `{ input, ctx }` (may be async) that gates whether the step, or every step in the phase, runs at all. A falsy result marks the step `"skipped"` — it never runs its handler and never runs its `rollback`.
+`when` on `addStep` or `addPhase` is a function of `{ input, ctx, flags }` (may be async) that gates whether the step, or every step in the phase, runs at all. A falsy result marks the step `"skipped"` — it never runs its handler and never runs its `rollback`.
 
 ## Setup
 
@@ -58,7 +59,7 @@ new Script<{ environment: "development" | "production" }>({ name: "deploy" })
   });
 ```
 
-`when` sees the same `{ input, ctx }` shape a handler does, so it can read anything an earlier step already put in context.
+`when` sees the same `{ input, ctx, flags }` a handler does, so it can read anything an earlier step already put in context, and any `defineFlag` value (`when: ({ flags }) => !flags.quiet`).
 
 ### Gate an entire phase
 
@@ -87,6 +88,21 @@ A falsy phase-level `when` marks every step in `"Release"` `"skipped"` in one sh
 
 `when` may return a promise; the script awaits it before deciding whether to run or skip the step (or, at phase level, the whole phase).
 
+### Need the output either way? Use `addBranch`
+
+A skipped step produces nothing, but `ctx` is still typed as though it ran. When later steps depend on the value, pick between two ways of producing it instead:
+
+```ts
+.addBranch({
+  name: "resolve commit",
+  condition: ({ flags }) => Boolean(flags.sha),
+  onTrue: ({ flags }) => ({ sha: flags.sha as string }),
+  onFalse: async () => ({ sha: await git.head() }),
+})
+```
+
+See skills/building-scripts/branching-steps/SKILL.md.
+
 ## Common Mistakes
 
 ### MEDIUM Skipped step's `clean` still runs

package/skills/errors-results/handling-results-and-errors/SKILL.md

@@ -3,25 +3,40 @@ name: 'handling-results-and-errors'
 description: >
   Covers the RunResult discriminated union returned by run(), every exported error class
   (StepFailedError, StepTimeoutError, ScriptAbortedError, RollbackFailedError, CacheShapeError,
-  SchemaValidationError), the isAbort(error) helper, and the throwOnError script option. Load this
+  SchemaValidationError, UnknownFlagError, MissingFlagValueError, PromptCancelledError,
+  PromptUnavailableError), the isAbort(error) helper, and the throwOnError script option. Load this
   for "branch correctly on a failed run," "tell a Ctrl-C cancellation apart from a real failure,"
   or "get the phase/step name a failure happened at."
 metadata:
   type: 'core'
   library: 'stagehand'
-  library_version: '0.5.3'
+  library_version: '0.8.0'
 sources:
+  - 'miaklwalker/stagehand:docs/guides/error-handling.md'
   - 'miaklwalker/stagehand:docs/guides/rollbacks.md'
   - 'miaklwalker/stagehand:docs/guides/script-options-and-result.md'
   - 'miaklwalker/stagehand:docs/reference/errors.md'
   - 'miaklwalker/stagehand:src/errors.ts'
   - 'miaklwalker/stagehand:src/script.ts'
+  - 'miaklwalker/stagehand:test/error-handling.test.ts'
 ---
 
 # Stagehand — Handling Results and Errors
 
 `run()` never throws for an ordinary step failure — it resolves to a discriminated union on `ok`. A handful of exported error classes exist for callers building their own reporting, but most of them never propagate through `run()` itself; knowing which ones do (and which don't) is the whole game.
 
+## The failure contract (read this before reasoning about rollback)
+
+- **Retries never roll back.** A failed attempt is not compensated; the handler simply re-runs against the same `input`/`ctx`. Rollback runs **once**, after the last attempt fails (or `retryIf` stops retrying).
+- **The failed step is never rolled back**, and steps after it never run (`"pending"`). Only steps that *completed* are compensated, in reverse order. Skipped and cached steps are not.
+- **Extent** is `ScriptOptions.rollback`: `"all"` (default) every completed step, `"phase"` only the failing step's phase, `"none"` nothing.
+- A **failing rollback** is recorded in `result.rollbacks` (`status: "rollback-failed"`), the rest still run, and `result.error` stays the original error.
+- A **timeout** (`StepTimeoutError`) is an ordinary failure: retried, `isAbort` false. A **cancellation** is never retried, gives `status: "aborted"`, and still compensates; a second signal abandons compensation.
+- **Not step failures** (thrown out of `run()`, nothing rolled back): `SchemaValidationError`, flag errors, and an error thrown by a `when` predicate or a mount `input` mapper. Keep those total; put fallible logic in a step or `addBranch`.
+- A step with `retry` must tolerate partial work: nothing compensates the failed attempts, so make it idempotent or clean up inside the handler before rethrowing.
+
+Full tables and the step lifecycle: docs/guides/error-handling.md.
+
 ## Setup
 
 ```ts
@@ -89,7 +104,7 @@ if (!result.ok) {
 }
 ```
 
-`isAbort(error)` returns `true` for a `ScriptAbortedError` or any `Error` named `"AbortError"` — checking `result.status === "aborted"` alongside it confirms the abort was the script's own, not an unrelated `AbortError` a handler happened to throw.
+`isAbort(error)` returns `true` for a `ScriptAbortedError`, a `PromptCancelledError` (Ctrl-C at a prompt), or any `Error` named `"AbortError"` — checking `result.status === "aborted"` alongside it confirms the abort was the script's own, not an unrelated `AbortError` a handler happened to throw.
 
 ### Use `throwOnError` when the script is one stage of a larger flow
 
@@ -157,7 +172,7 @@ try {
 }
 ```
 
-`SchemaValidationError` is always thrown directly by `run()`, before any phase executes, and is unaffected by `throwOnError` — there is no partial result to produce since nothing ran yet.
+`SchemaValidationError` is always thrown directly by `run()`, before any phase executes, and is unaffected by `throwOnError` — there is no partial result to produce since nothing ran yet. `UnknownFlagError` and `MissingFlagValueError` (bad `defineFlag` argv) behave the same way. `PromptUnavailableError`, by contrast, is thrown from inside a handler, so it arrives as an ordinary failed step.
 
 Source: docs/guides/typed-context.md; docs/reference/errors.md
 

package/skills/observability/log-placement-and-rendering/SKILL.md

@@ -5,7 +5,7 @@ description: >
 metadata:
   type: 'core'
   library: 'stagehand'
-  library_version: '0.5.3'
+  library_version: '0.8.0'
 sources:
   - 'miaklwalker/stagehand:docs/guides/handler-surface.md'
   - 'miaklwalker/stagehand:docs/guides/terminal-rendering.md'

package/skills/observability/reporting-progress/SKILL.md

@@ -5,7 +5,7 @@ description: >
 metadata:
   type: 'core'
   library: 'stagehand'
-  library_version: '0.5.3'
+  library_version: '0.8.0'
 sources:
   - 'miaklwalker/stagehand:docs/guides/handler-surface.md'
   - 'miaklwalker/stagehand:src/context.ts'
@@ -14,6 +14,8 @@ sources:
 
 # Stagehand — Reporting Progress From a Step
 
+The handler context also carries `prompt` (see skills/building-scripts/prompting-the-user/SKILL.md) and `flags` (see skills/building-scripts/command-line-flags/SKILL.md); this skill covers only the output side.
+
 Every handler receives `status`, `note`, `progress`, `task`, `tasks`, and the five log methods as part of its single context object. `rollback` gets a smaller subset — `log` (no `info`/`warn`/`error`/`success`), `status`, `note`, and `progress`, but not `task`/`tasks`.
 
 ## Setup

package/skills/reuse/reusable-routines-and-mounts/SKILL.md

@@ -7,7 +7,7 @@ description: >
 metadata:
   type: 'core'
   library: 'stagehand'
-  library_version: '0.5.3'
+  library_version: '0.8.0'
 sources:
   - 'miaklwalker/stagehand:docs/guides/reusable-scripts.md'
   - 'miaklwalker/stagehand:docs/guides/caching.md'
@@ -104,7 +104,7 @@ const result = await new Script<{ region: string }>({ name: "t" })
   .run({ region: "eu" });
 ```
 
-`input` takes a fixed value or an `{ input, ctx } => SubIn` mapper, may be async, and is resolved once per mount at the moment the mount is reached — the host no longer has to match the routine's input shape, only produce it.
+`input` takes a fixed value or an `{ input, ctx, flags } => SubIn` mapper, may be async, and is resolved once per mount at the moment the mount is reached — the host no longer has to match the routine's input shape, only produce it. `flags` is how a routine, which cannot declare flags itself, is driven by one: `use(r, { input: ({ flags }) => ({ env: flags.environment }) })`.
 
 ## Common Mistakes
 
@@ -152,7 +152,7 @@ export const pullChannel = routineFor<{ channel: string; since: string }>()(
 );
 ```
 
-A mount's input is resolved once, when the mount is reached, from either a fixed value or an `{ input, ctx } => SubIn` mapper — every `when` inside that fragment (phase- or step-level) is evaluated against the mount's resolved input, never the host's own.
+A mount's input is resolved once, when the mount is reached, from either a fixed value or an `{ input, ctx, flags } => SubIn` mapper — every `when` inside that fragment (phase- or step-level) is evaluated against the mount's resolved input, never the host's own.
 
 Source: docs/guides/reusable-scripts.md ("Giving a mount its own input"); src/script.ts use()/run() mount input resolution
 

package/skills/reuse/splitting-steps-across-files/SKILL.md

@@ -5,7 +5,7 @@ description: >
 metadata:
   type: 'core'
   library: 'stagehand'
-  library_version: '0.5.3'
+  library_version: '0.8.0'
 sources:
   - 'miaklwalker/stagehand:docs/guides/splitting-steps.md'
   - 'miaklwalker/stagehand:src/script.ts'