@michaelrwalker/stagehand 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Walker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,277 @@
+# stagehand
+
+A fully typesafe, saga-style script framework for TypeScript, with a live terminal UI.
+
+- **Scripts** are a collection of **phases**.
+- **Phases** are a collection of **steps**.
+- **Steps** have a `handler` and an optional `rollback` that fires when a *later* step fails.
+- Whatever a handler returns is merged into a **typed context** that every later step can read.
+- Zero runtime dependencies. Live rendering on a TTY, plain line output in CI.
+
+```ts
+const result = await new Script<{ service: string }>({ name: "deploy" })
+  .addPhase("Validation")
+  .addStep({
+    name: "resolve commit",
+    handler: async ({ input, status }) => {
+      status("querying git");
+      return { sha: await git.head(input.service) };
+    },
+  })
+  .addPhase("Release")
+  .addStep({
+    name: "upload artifact",
+    handler: async ({ ctx, progress }) => {
+      const bar = progress({ total: 100, label: "uploading" });
+      //          ^ ctx.sha is typed here
+      return { uploadId: await upload(ctx.sha, bar) };
+    },
+    rollback: async ({ output }) => cdn.delete(output.uploadId),
+    //                  ^ typed as { uploadId: string }
+  })
+  .run({ service: "api" });
+
+if (result.ok) result.ctx.uploadId; // string
+```
+
+## The terminal
+
+```
+  ▌ deploy
+  ▌ Build, upload and release a service
+
+  ✔ Validation                                                             739ms
+     ✔ resolve commit                                                      222ms
+     ✔ check permissions                                                   517ms
+
+  ⠸ Build                                                                   17.7s
+     ✔ install dependencies                                                 14.4s
+     ⠸ compile bundle  › transform                                           3.3s
+       ▕██████████████░░░░░░░░░░▏  58%  412/710  src/router.ts
+       ✔ typecheck
+       ⠸ transform
+       ○ minify
+       ○ write manifest
+
+  ○ Release
+     ○ upload artifact
+     ○ shift traffic
+```
+
+On failure:
+
+```
+  ─────────────────────────────────────────────────────────────────────────────
+  ✖ Failed at Release › shift traffic after 21.4s
+    health check failed: 3/5 pods unhealthy
+  ↺ Rolled back 2 steps
+```
+
+Run `npm run example` and `npm run example:fail` to see both live.
+
+## Type flow
+
+The context type parameter is inferred and never written by hand. Each `addStep`
+whose handler returns an object widens it:
+
+```ts
+new Script<{ id: string }>()      // Ctx = {}
+  .addStep({ handler: () => ({ token: "x" }) })      // Ctx = { token: string }
+  .addStep({ handler: ({ ctx }) => ({ n: ctx.token.length }) })
+                                  // Ctx = { token: string; n: number }
+```
+
+Reaching for a key a previous step did not produce is a compile error, as is
+reading the wrong shape in a `rollback`. A handler that returns nothing leaves
+the context unchanged.
+
+## Rollback semantics
+
+When a step fails, every step that already **succeeded** is compensated in
+reverse order. The step that failed is not compensated — it never completed.
+
+| `rollback` option | behaviour |
+| --- | --- |
+| `"all"` (default) | unwind every completed step in the script |
+| `"phase"` | unwind only the phase that failed |
+| `"none"` | leave state as-is |
+
+A rollback that throws is recorded in `result.rollbacks` and surfaced in the
+summary; it never masks the original error, and the remaining rollbacks still
+run.
+
+## The handler surface
+
+Every handler receives one object:
+
+| | |
+| --- | --- |
+| `input` | the value passed to `run()` |
+| `ctx` | everything earlier steps produced, fully typed |
+| `signal` | aborts on timeout, Ctrl-C, or an external signal |
+| `attempt` | 1-based, useful with `retry` |
+| `log` / `info` / `warn` / `error` / `success` | permanent lines above the live frame |
+| `status(text)` | transient one-liner beside the step |
+| `progress({ total, label })` | a progress bar → `update` / `increment` / `setTotal` / `done` |
+| `task(label)` | one nested checklist item → `succeed` / `fail` / `skip` |
+| `tasks([...] as const)` | a whole checklist, keyed for typed lookup |
+
+`rollback` receives the same, plus `output` (that step's own return value) and
+`error` (what triggered the unwind).
+
+## Step options
+
+```ts
+.addStep({
+  name: "publish",
+  description: "push the tag",
+  when: ({ input, ctx }) => input.env === "production",
+  retry: { attempts: 3, delayMs: (attempt) => attempt * 250, retryIf: isTransient },
+  timeoutMs: 30_000,
+  handler,
+  rollback,
+})
+```
+
+`when` returning false marks the step **skipped** — its rollback never runs.
+Phases accept `when` too, which skips all their steps.
+
+## Script options
+
+```ts
+new Script<Input>({
+  name: "deploy",
+  description: "Build, upload and release a service",
+  rollback: "all",       // "all" | "phase" | "none"
+  throwOnError: false,   // true to throw instead of returning ok: false
+  plain: undefined,      // force the CI renderer; default auto-detects a TTY
+  silent: false,
+  handleSignals: true,   // Ctrl-C aborts and compensates; a second one gives up
+})
+```
+
+## Result
+
+```ts
+type RunResult<Ctx> =
+  | { ok: true;  status: "success"; ctx: Ctx; durationMs: number; steps: StepReport[] }
+  | { ok: false; status: "failed" | "aborted"; error: unknown;
+      failedAt: { phase: string; step: string } | null;
+      ctx: Partial<Ctx>;            // what did get produced
+      durationMs: number; steps: StepReport[]; rollbacks: RollbackReport[] }
+```
+
+## Splitting steps across files
+
+`stepFor` binds the input and context a step expects while keeping inference:
+
+```ts
+export const verifyId = stepFor<Input, { user: User }>()({
+  name: "verify id",
+  handler: async ({ ctx }) => ({ verified: ctx.user.id }),
+});
+```
+
+## Scripts
+
+```
+npm run build       # emit dist/
+npm test            # node:test suite
+npm run typecheck   # library + examples + tests + scripts
+npm run example     # the happy path, live
+npm run example:fail
+npm run release     # dry run of the publish pipeline
+```
+
+## TypeScript layout
+
+One config per directory, because editors resolve a file's config by finding
+the nearest `tsconfig.json` — a non-standard filename like `tsconfig.foo.json`
+is invisible to them, so the IDE and the CLI disagree.
+
+| Config | Covers | Why it differs |
+| --- | --- | --- |
+| `tsconfig.json` | `src` | The library. `noEmit`, strict. |
+| `tsconfig.build.json` | `src` | The only config that emits `dist/`. |
+| `examples/tsconfig.json` | `examples` | Imports the built `dist/`. |
+| `test/tsconfig.json` | `test` | Same. |
+| `scripts/tsconfig.json` | `scripts` | Adds `allowImportingTsExtensions`. |
+
+Only `scripts/` needs that last flag. Node's type stripping does not rewrite
+import extensions, so a script importing a sibling script must write
+`./exec.ts` rather than `./exec.js`. The flag cannot go in the root config:
+`tsconfig.build.json` extends it and sets `noEmit: false`, and TypeScript
+rejects `allowImportingTsExtensions` unless `noEmit` or `emitDeclarationOnly`
+is set (TS5096).
+
+## The release pipeline
+
+`scripts/release.ts` builds and publishes this package, and is itself written
+with this framework — the pipeline is the integration test.
+
+```
+npm run release                              # dry run; mutates nothing
+npm run release -- --simulate-failure        # rehearse the rollback path
+npm run release -- --publish                 # for real
+npm run release -- --publish --bump minor
+npm run release -- --publish --version 1.0.0 --tag next
+```
+
+| Phase | Steps |
+| --- | --- |
+| Preflight | read manifest · authenticate npm · inspect git · resolve version · check registry |
+| Verify | typecheck · run tests |
+| Package | write version · clean dist · build · verify artifacts · audit tarball |
+| Publish | tag release · push tag · publish to npm |
+
+Three steps compensate, and the ordering is deliberate — `publish to npm` is
+last, so a failure anywhere *before* it unwinds everything and nothing reaches
+the registry:
+
+| Step | Rollback |
+| --- | --- |
+| `write version` | restore the previous version in package.json |
+| `clean dist` | rebuild from source |
+| `tag release` | delete the local tag |
+| `push tag` | delete the remote tag |
+| `publish to npm` | `npm deprecate` — a published version cannot be recalled |
+
+`--simulate-failure` performs the local mutations and then fails at the publish
+step. Nothing leaves the machine, and you get to watch the unwind:
+
+```
+  ✖ publish to npm  0ms  simulated publish failure (--simulate-failure)
+    ▲ deleted local tag v0.2.0
+    ▲ dist rebuilt from source
+    ▲ package.json version restored to 0.1.0
+
+  ✖ Failed at Publish › publish to npm after 8.1s
+  ↺ Rolled back 3 steps
+```
+
+Other things it checks: a scoped package without `publishConfig.access`
+(`"public"`) would be published as restricted, so preflight refuses; the tarball
+is audited path-by-path against an allowlist so `src/` can never leak; and the
+version is checked against the registry before any work is done.
+
+## Rendering notes
+
+The live renderer repaints an in-place region and writes logs permanently above
+it. It falls back to line-per-event output when stdout is not a TTY, when
+`NO_COLOR` is set, or when `TERM=dumb` — so CI logs stay greppable.
+
+**The frame is always made to fit the viewport**, and this is load-bearing
+rather than cosmetic. Repainting works by moving the cursor up N lines, so a
+frame taller than the terminal scrolls its own anchor off screen and each
+repaint appends a copy instead of overwriting. `renderBody` applies four
+progressively stronger reductions until the frame fits:
+
+1. everything, in full;
+2. finished phases collapse to a one-line summary;
+3. only the running phase keeps its steps, and drops detail lines;
+4. the running phase's steps are windowed around the one executing.
+
+The executing step is never windowed out, and long lines are truncated rather
+than wrapped. A terminal resize invalidates the recorded geometry, so the
+renderer abandons the old region and redraws below it. The closing frame is
+exempt — nothing repaints after it, so it keeps every step.

package/dist/context.d.ts

@@ -0,0 +1,11 @@
+import type { StepState } from "./state.js";
+import type { Renderer } from "./ui/renderer.js";
+import type { RollbackContext, StepContext } from "./types.js";
+export interface ContextDeps {
+    renderer: Renderer;
+    step: StepState;
+    phaseName: string;
+}
+export declare function createStepContext<In, Ctx>(deps: ContextDeps, input: In, ctx: Ctx, signal: AbortSignal, attempt: number): StepContext<In, Ctx>;
+export declare function createRollbackContext<In, Ctx, Out>(deps: ContextDeps, input: In, ctx: Ctx, output: Out, error: unknown, signal: AbortSignal): RollbackContext<In, Ctx, Out>;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,SAAS,EAAa,MAAM,YAAY,CAAC;AACtE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEjD,OAAO,KAAK,EAEV,eAAe,EACf,WAAW,EAGZ,MAAM,YAAY,CAAC;AA6FpB,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,GAAG,EACvC,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,EAAE,EACT,GAAG,EAAE,GAAG,EACR,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,MAAM,GACd,WAAW,CAAC,EAAE,EAAE,GAAG,CAAC,CAwBtB;AAED,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,EAChD,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,EAAE,EACT,GAAG,EAAE,GAAG,EACR,MAAM,EAAE,GAAG,EACX,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,WAAW,GAClB,eAAe,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,CAiB/B"}

package/dist/context.js

@@ -0,0 +1,123 @@
+function clamp(value, min, max) {
+    return Math.max(min, Math.min(max, value));
+}
+function createProgress(step, renderer, options) {
+    const bar = {
+        total: Math.max(0, options.total),
+        value: clamp(options.value ?? 0, 0, Math.max(0, options.total)),
+        complete: false,
+    };
+    if (options.label !== undefined)
+        bar.label = options.label;
+    step.progress = bar;
+    renderer.refresh();
+    return {
+        get value() {
+            return bar.value;
+        },
+        get total() {
+            return bar.total;
+        },
+        update(value, label) {
+            bar.value = clamp(value, 0, bar.total);
+            if (label !== undefined)
+                bar.label = label;
+            renderer.refresh();
+        },
+        increment(by = 1) {
+            bar.value = clamp(bar.value + by, 0, bar.total);
+            renderer.refresh();
+        },
+        setTotal(total) {
+            bar.total = Math.max(0, total);
+            bar.value = clamp(bar.value, 0, bar.total);
+            renderer.refresh();
+        },
+        setLabel(label) {
+            bar.label = label;
+            renderer.refresh();
+        },
+        done() {
+            bar.value = bar.total;
+            bar.complete = true;
+            renderer.refresh();
+        },
+    };
+}
+function handleFor(task, renderer) {
+    const set = (status, text) => {
+        if (text !== undefined)
+            task.label = text;
+        task.status = status;
+        renderer.refresh();
+    };
+    return {
+        start: (text) => set("running", text),
+        label: (text) => set(task.status, text),
+        succeed: (text) => set("done", text),
+        fail: (text) => set("failed", text),
+        skip: (text) => set("skipped", text),
+    };
+}
+function createTask(step, renderer, label) {
+    const task = { label, status: "running" };
+    step.tasks.push(task);
+    renderer.refresh();
+    return handleFor(task, renderer);
+}
+function createTaskList(step, renderer, labels) {
+    const map = {};
+    for (const label of labels) {
+        const task = { label, status: "pending" };
+        step.tasks.push(task);
+        map[label] = handleFor(task, renderer);
+    }
+    renderer.refresh();
+    return {
+        tasks: map,
+        get: (key) => map[key],
+    };
+}
+export function createStepContext(deps, input, ctx, signal, attempt) {
+    const { renderer, step, phaseName } = deps;
+    const emit = (level) => (message) => renderer.log({ level, message });
+    return {
+        input,
+        ctx,
+        signal,
+        attempt,
+        phase: phaseName,
+        step: step.name,
+        log: emit("log"),
+        info: emit("info"),
+        warn: emit("warn"),
+        error: emit("error"),
+        success: emit("success"),
+        status(message) {
+            step.statusText = message;
+            renderer.refresh();
+        },
+        progress: (options) => createProgress(step, renderer, options),
+        task: (label) => createTask(step, renderer, label),
+        tasks: (labels) => createTaskList(step, renderer, labels),
+    };
+}
+export function createRollbackContext(deps, input, ctx, output, error, signal) {
+    const { renderer, step, phaseName } = deps;
+    return {
+        input,
+        ctx,
+        output,
+        error,
+        signal,
+        phase: phaseName,
+        step: step.name,
+        log: (message) => renderer.log({ level: "warn", message }),
+        status(message) {
+            step.statusText = message;
+            renderer.refresh();
+        },
+        progress: (options) => createProgress(step, renderer, options),
+    };
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,26 @@
+/** A step's handler threw. `cause` holds whatever it actually threw. */
+export declare class StepFailedError extends Error {
+    readonly phase: string;
+    readonly step: string;
+    readonly attempts: number;
+    constructor(phase: string, step: string, attempts: number, cause: unknown);
+}
+export declare class StepTimeoutError extends Error {
+    readonly step: string;
+    readonly timeoutMs: number;
+    constructor(step: string, timeoutMs: number);
+}
+/** The run was cancelled — Ctrl-C, SIGTERM, or a caller-supplied signal. */
+export declare class ScriptAbortedError extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+/** A compensation handler itself threw; the original failure is in `cause`. */
+export declare class RollbackFailedError extends Error {
+    readonly phase: string;
+    readonly step: string;
+    readonly rollbackError: unknown;
+    constructor(phase: string, step: string, rollbackError: unknown, cause: unknown);
+}
+export declare function isAbort(error: unknown): boolean;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAO1E;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAM5C;AAED,4EAA4E;AAC5E,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,MAAM,EAAE,MAAM;CAK3B;AAED,+EAA+E;AAC/E,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;gBAEpB,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO;CAOhF;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAK/C"}

package/dist/errors.js

@@ -0,0 +1,50 @@
+/** A step's handler threw. `cause` holds whatever it actually threw. */
+export class StepFailedError extends Error {
+    phase;
+    step;
+    attempts;
+    constructor(phase, step, attempts, cause) {
+        super(`Step "${step}" in phase "${phase}" failed`, { cause });
+        this.name = "StepFailedError";
+        this.phase = phase;
+        this.step = step;
+        this.attempts = attempts;
+    }
+}
+export class StepTimeoutError extends Error {
+    step;
+    timeoutMs;
+    constructor(step, timeoutMs) {
+        super(`Step "${step}" timed out after ${timeoutMs}ms`);
+        this.name = "StepTimeoutError";
+        this.step = step;
+        this.timeoutMs = timeoutMs;
+    }
+}
+/** The run was cancelled — Ctrl-C, SIGTERM, or a caller-supplied signal. */
+export class ScriptAbortedError extends Error {
+    reason;
+    constructor(reason) {
+        super(`Script aborted (${reason})`);
+        this.name = "ScriptAbortedError";
+        this.reason = reason;
+    }
+}
+/** A compensation handler itself threw; the original failure is in `cause`. */
+export class RollbackFailedError extends Error {
+    phase;
+    step;
+    rollbackError;
+    constructor(phase, step, rollbackError, cause) {
+        super(`Rollback for "${step}" in phase "${phase}" failed`, { cause });
+        this.name = "RollbackFailedError";
+        this.phase = phase;
+        this.step = step;
+        this.rollbackError = rollbackError;
+    }
+}
+export function isAbort(error) {
+    return (error instanceof ScriptAbortedError ||
+        (error instanceof Error && error.name === "AbortError"));
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAC/B,KAAK,CAAS;IACd,IAAI,CAAS;IACb,QAAQ,CAAS;IAE1B,YAAY,KAAa,EAAE,IAAY,EAAE,QAAgB,EAAE,KAAc;QACvE,KAAK,CAAC,SAAS,IAAI,eAAe,KAAK,UAAU,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QAC9D,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAED,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAChC,IAAI,CAAS;IACb,SAAS,CAAS;IAE3B,YAAY,IAAY,EAAE,SAAiB;QACzC,KAAK,CAAC,SAAS,IAAI,qBAAqB,SAAS,IAAI,CAAC,CAAC;QACvD,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF;AAED,4EAA4E;AAC5E,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAClC,MAAM,CAAS;IAExB,YAAY,MAAc;QACxB,KAAK,CAAC,mBAAmB,MAAM,GAAG,CAAC,CAAC;QACpC,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED,+EAA+E;AAC/E,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IACnC,KAAK,CAAS;IACd,IAAI,CAAS;IACb,aAAa,CAAU;IAEhC,YAAY,KAAa,EAAE,IAAY,EAAE,aAAsB,EAAE,KAAc;QAC7E,KAAK,CAAC,iBAAiB,IAAI,eAAe,KAAK,UAAU,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QACtE,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;IACrC,CAAC;CACF;AAED,MAAM,UAAU,OAAO,CAAC,KAAc;IACpC,OAAO,CACL,KAAK,YAAY,kBAAkB;QACnC,CAAC,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC,CACxD,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { Script, script, stepFor, type RunOptions } from "./script.js";
+export { RollbackFailedError, ScriptAbortedError, StepFailedError, StepTimeoutError, isAbort, } from "./errors.js";
+export type { Awaitable, Merge, PhaseOptions, PhaseStatus, Prettify, ProgressHandle, RetryPolicy, RollbackContext, RollbackReport, RunResult, RunStatus, ScriptOptions, StepContext, StepDef, StepReport, StepStatus, TaskHandle, TaskListHandle, } from "./types.js";
+export { formatDuration } from "./state.js";
+export { setColorEnabled, isColorEnabled } from "./ui/ansi.js";
+export { palette, symbols } from "./ui/theme.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAEvE,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,OAAO,GACR,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,SAAS,EACT,KAAK,EACL,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,cAAc,EACd,WAAW,EACX,eAAe,EACf,cAAc,EACd,SAAS,EACT,SAAS,EACT,aAAa,EACb,WAAW,EACX,OAAO,EACP,UAAU,EACV,UAAU,EACV,UAAU,EACV,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { Script, script, stepFor } from "./script.js";
+export { RollbackFailedError, ScriptAbortedError, StepFailedError, StepTimeoutError, isAbort, } from "./errors.js";
+export { formatDuration } from "./state.js";
+export { setColorEnabled, isColorEnabled } from "./ui/ansi.js";
+export { palette, symbols } from "./ui/theme.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAmB,MAAM,aAAa,CAAC;AAEvE,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,OAAO,GACR,MAAM,aAAa,CAAC;AAuBrB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC"}

package/dist/script.d.ts

@@ -0,0 +1,75 @@
+import type { Merge, PhaseOptions, RunResult, ScriptOptions, StepDef } from "./types.js";
+export interface RunOptions {
+    /** Cancel the run from the outside. */
+    signal?: AbortSignal;
+}
+/**
+ * A saga-style script: phases of steps, each step optionally compensating when
+ * a later step fails.
+ *
+ * The second type parameter is inferred, never written by hand — every
+ * `addStep` whose handler returns an object widens it, so later handlers see
+ * everything earlier ones produced.
+ *
+ * ```ts
+ * const result = await new Script<{ userId: string }>("provision")
+ *   .addPhase("Validation")
+ *   .addStep({
+ *     name: "load user",
+ *     handler: async ({ input }) => ({ user: await db.user(input.userId) }),
+ *   })
+ *   .addPhase("Provision")
+ *   .addStep({
+ *     name: "create tenant",
+ *     handler: async ({ ctx }) => ({ tenantId: await api.create(ctx.user.org) }),
+ *     rollback: async ({ output }) => api.destroy(output.tenantId),
+ *   })
+ *   .run({ userId: "u_1" });
+ * ```
+ */
+export declare class Script<In = void, Ctx extends object = {}> {
+    private readonly options;
+    private readonly definition;
+    constructor(options?: ScriptOptions | string);
+    /** Open a new phase. Subsequent `addStep` calls land in it. */
+    addPhase(name: string, options?: PhaseOptions<In, Ctx>): Script<In, Ctx>;
+    /** Open a phase and populate it inside a callback, keeping the type flow. */
+    addPhase<Next extends object>(name: string, build: (script: Script<In, Ctx>) => Script<In, Next>): Script<In, Next>;
+    addPhase<Next extends object>(name: string, options: PhaseOptions<In, Ctx>, build: (script: Script<In, Ctx>) => Script<In, Next>): Script<In, Next>;
+    /**
+     * Append a step to the current phase. Whatever the handler resolves to is
+     * merged into the context and becomes visible to every later step.
+     */
+    addStep<Out extends object | void>(def: StepDef<In, Ctx, Out>): Script<In, Merge<Ctx, Out>>;
+    /** Every step name, in execution order — handy for tests and docs. */
+    outline(): Array<{
+        phase: string;
+        steps: string[];
+    }>;
+    private currentPhase;
+    run(input: In, runOptions?: RunOptions): Promise<RunResult<Ctx>>;
+    /** Retry + timeout wrapper around a single handler invocation. */
+    private executeStep;
+    /** Compensate completed steps in reverse order. */
+    private unwind;
+    /**
+     * Wire up cancellation. The first interrupt stops the run and lets
+     * compensation proceed; a second one abandons compensation too.
+     */
+    private attachCancellation;
+}
+/**
+ * Define a step in its own module while keeping full inference. Bind the input
+ * and the context the step expects, then pass the definition to `addStep`.
+ *
+ * ```ts
+ * export const verifyId = stepFor<Input, { user: User }>()({
+ *   name: "verify id",
+ *   handler: async ({ ctx }) => ({ verified: ctx.user.id }),
+ * });
+ * ```
+ */
+export declare function stepFor<In, Ctx extends object = {}>(): <Out extends object | void>(def: StepDef<In, Ctx, Out>) => StepDef<In, Ctx, Out>;
+/** Convenience factory so callers can skip `new`. */
+export declare function script<In = void>(options?: ScriptOptions | string): Script<In, {}>;
+//# sourceMappingURL=script.d.ts.map

package/dist/script.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"script.d.ts","sourceRoot":"","sources":["../src/script.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,KAAK,EACL,YAAY,EAIZ,SAAS,EACT,aAAa,EACb,OAAO,EAER,MAAM,YAAY,CAAC;AAqBpB,MAAM,WAAW,UAAU;IACzB,uCAAuC;IACvC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,MAAM,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,SAAS,MAAM,GAAG,EAAE;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyB;gBAExC,OAAO,GAAE,aAAa,GAAG,MAAW;IAIhD,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,CAAC,EAAE,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,EAAE,EAAE,GAAG,CAAC;IACxE,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,SAAS,MAAM,EAC1B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,GAAG,CAAC,KAAK,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,GACnD,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC;IACnB,QAAQ,CAAC,IAAI,SAAS,MAAM,EAC1B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,YAAY,CAAC,EAAE,EAAE,GAAG,CAAC,EAC9B,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,GAAG,CAAC,KAAK,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,GACnD,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC;IAqBnB;;;OAGG;IACH,OAAO,CAAC,GAAG,SAAS,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAK3F,sEAAsE;IACtE,OAAO,IAAI,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAOpD,OAAO,CAAC,YAAY;IAYd,GAAG,CAAC,KAAK,EAAE,EAAE,EAAE,UAAU,GAAE,UAAe,GAAG,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IAkL1E,kEAAkE;YACpD,WAAW;IA8DzB,mDAAmD;YACrC,MAAM;IAsDpB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;CA+B3B;AA6CD;;;;;;;;;;GAUG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,GAAG,SAAS,MAAM,GAAG,EAAE,MACzC,GAAG,SAAS,MAAM,GAAG,IAAI,EAAE,KAAK,OAAO,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,KAAG,OAAO,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,CACtF;AAED,qDAAqD;AACrD,wBAAgB,MAAM,CAAC,EAAE,GAAG,IAAI,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,GAAG,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,CAElF"}