@michaelrwalker/stagehand 0.6.0 → 0.7.0

package/dist/context.d.ts

@@ -8,6 +8,8 @@ export interface ContextDeps {
     phaseName: string;
     /** Backs `context.cache`; slots declared before the current step. */
     cache: CacheHandle<Record<string, unknown>>;
+    /** Backs `context.flags`; parsed once from argv before any phase runs. */
+    flags: Record<string, unknown>;
 }
 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>;

package/dist/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAA2B,SAAS,EAAa,MAAM,YAAY,CAAC;AAChF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,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;IAClB,qEAAqE;IACrE,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC7C;AASD,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,CA4BtB;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,CAmB/B"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAA2B,SAAS,EAAa,MAAM,YAAY,CAAC;AAEhF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAGV,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;IAClB,qEAAqE;IACrE,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC5C,0EAA0E;IAC1E,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAgCD,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,CA8BtB;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,CAoB/B"}

package/dist/context.js

@@ -1,3 +1,5 @@
+import { ScriptAbortedError } from "./errors.js";
+import { promptConfirm, promptMultiselect, promptSelect, promptText } from "./ui/prompt.js";
 function clamp(value, min, max) {
     return Math.max(min, Math.min(max, value));
 }
@@ -86,8 +88,31 @@ function annotate(step, renderer, message) {
         step.note = message;
     renderer.refresh();
 }
+/**
+ * Suspends the live frame around each call so a prompt owns the terminal,
+ * then hands it back — resolve or reject, cancelled or not.
+ */
+function createPrompt(renderer, signal) {
+    const wrap = async (run) => {
+        if (signal.aborted)
+            throw signal.reason ?? new ScriptAbortedError("cancelled");
+        renderer.suspend();
+        try {
+            return await run(signal);
+        }
+        finally {
+            renderer.resume();
+        }
+    };
+    return {
+        text: (options) => wrap((s) => promptText(options, s)),
+        confirm: (options) => wrap((s) => promptConfirm(options, s)),
+        select: (options) => wrap((s) => promptSelect(options, s)),
+        multiselect: (options) => wrap((s) => promptMultiselect(options, s)),
+    };
+}
 export function createStepContext(deps, input, ctx, signal, attempt) {
-    const { renderer, step, phaseName, cache } = deps;
+    const { renderer, step, phaseName, cache, flags } = deps;
     // `step` is a routing hint: renderers that place logs on the step itself
     // (rather than the scrollback) need to know which one.
     const emit = (level) => (message) => renderer.log({ level, message }, step);
@@ -97,6 +122,7 @@ export function createStepContext(deps, input, ctx, signal, attempt) {
         signal,
         attempt,
         cache,
+        flags,
         phase: phaseName,
         step: step.name,
         log: emit("log"),
@@ -112,10 +138,11 @@ export function createStepContext(deps, input, ctx, signal, attempt) {
         progress: (options) => createProgress(step, renderer, options),
         task: (label) => createTask(step, renderer, label),
         tasks: (labels) => createTaskList(step, renderer, labels),
+        prompt: createPrompt(renderer, signal),
     };
 }
 export function createRollbackContext(deps, input, ctx, output, error, signal) {
-    const { renderer, step, phaseName, cache } = deps;
+    const { renderer, step, phaseName, cache, flags } = deps;
     return {
         input,
         ctx,
@@ -123,6 +150,7 @@ export function createRollbackContext(deps, input, ctx, output, error, signal) {
         error,
         signal,
         cache,
+        flags,
         phase: phaseName,
         step: step.name,
         log: (message) => renderer.log({ level: "warn", message }, step),

package/dist/context.js.map

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

package/dist/errors.d.ts

@@ -23,9 +23,9 @@ export declare class StepDefinitionError extends Error {
  * failure — so it is refused up front.
  */
 export declare class DuplicateNameError extends Error {
-    readonly kind: "phase" | "step";
+    readonly kind: "phase" | "step" | "flag";
     readonly duplicate: string;
-    constructor(kind: "phase" | "step", duplicate: string, message: string);
+    constructor(kind: "phase" | "step" | "flag", duplicate: string, message: string);
 }
 /**
  * A cached value was read for a field it does not have.
@@ -65,5 +65,32 @@ export declare class RollbackFailedError extends Error {
     readonly rollbackError: unknown;
     constructor(phase: string, step: string, rollbackError: unknown, cause: unknown);
 }
+/**
+ * `run()` saw `--foo` or `-f` on the command line, but no `defineFlag` call
+ * named it. Thrown before any phase executes, the same as a bad `defineInput`
+ * schema — parsing happens once, up front.
+ */
+export declare class UnknownFlagError extends Error {
+    readonly flag: string;
+    constructor(flag: string, known: readonly string[]);
+}
+/** A non-boolean flag was given with nothing after it — `--env` with no value. */
+export declare class MissingFlagValueError extends Error {
+    readonly flag: string;
+    constructor(flag: string);
+}
+/** A `context.prompt` call was cancelled — Ctrl-C while waiting on input. */
+export declare class PromptCancelledError extends Error {
+    constructor();
+}
+/**
+ * A step called `context.prompt` but stdin isn't an interactive terminal —
+ * CI, a pipe, a non-TTY subprocess — and the prompt declared no `default` to
+ * fall back to. Thrown instead of hanging on a stream nothing will ever
+ * write to.
+ */
+export declare class PromptUnavailableError extends Error {
+    constructor(message: string);
+}
 export declare function isAbort(error: unknown): boolean;
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,oFAAoF;AACpF,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;gBAE3C,MAAM,EAAE,aAAa,CAAC,gBAAgB,CAAC,KAAK,CAAC;CAgB1D;AAED;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C;AAED;;;;;;;;GAQG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,IAAI,EAAE,OAAO,GAAG,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAMvE;AAED;;;;;;;;GAQG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAWvC;AAED,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"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,oFAAoF;AACpF,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;gBAE3C,MAAM,EAAE,aAAa,CAAC,gBAAgB,CAAC,KAAK,CAAC;CAgB1D;AAED;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C;AAED;;;;;;;;GAQG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAMhF;AAED;;;;;;;;GAQG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAWvC;AAED,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;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE;CAQnD;AAED,kFAAkF;AAClF,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM;CAKzB;AAED,6EAA6E;AAC7E,qBAAa,oBAAqB,SAAQ,KAAK;;CAK9C;AAED;;;;;GAKG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAM/C"}

package/dist/errors.js

@@ -113,8 +113,51 @@ export class RollbackFailedError extends Error {
         this.rollbackError = rollbackError;
     }
 }
+/**
+ * `run()` saw `--foo` or `-f` on the command line, but no `defineFlag` call
+ * named it. Thrown before any phase executes, the same as a bad `defineInput`
+ * schema — parsing happens once, up front.
+ */
+export class UnknownFlagError extends Error {
+    flag;
+    constructor(flag, known) {
+        super(`Unknown flag "${flag}". ` +
+            (known.length > 0 ? `Declared flags: ${known.join(", ")}.` : "This script declares no flags."));
+        this.name = "UnknownFlagError";
+        this.flag = flag;
+    }
+}
+/** A non-boolean flag was given with nothing after it — `--env` with no value. */
+export class MissingFlagValueError extends Error {
+    flag;
+    constructor(flag) {
+        super(`Flag "${flag}" expects a value ("${flag} <value>" or "${flag}=<value>"), but none was given.`);
+        this.name = "MissingFlagValueError";
+        this.flag = flag;
+    }
+}
+/** A `context.prompt` call was cancelled — Ctrl-C while waiting on input. */
+export class PromptCancelledError extends Error {
+    constructor() {
+        super("Prompt cancelled");
+        this.name = "PromptCancelledError";
+    }
+}
+/**
+ * A step called `context.prompt` but stdin isn't an interactive terminal —
+ * CI, a pipe, a non-TTY subprocess — and the prompt declared no `default` to
+ * fall back to. Thrown instead of hanging on a stream nothing will ever
+ * write to.
+ */
+export class PromptUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PromptUnavailableError";
+    }
+}
 export function isAbort(error) {
     return (error instanceof ScriptAbortedError ||
+        error instanceof PromptCancelledError ||
         (error instanceof Error && error.name === "AbortError"));
 }
 //# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/flags.d.ts

@@ -0,0 +1,30 @@
+/** Recorded by `defineFlag`; type-erased, the same way step/phase defs are. */
+export interface FlagDef {
+    name: string;
+    long: string;
+    short?: string;
+    description?: string;
+    boolean: boolean;
+    hasDefault: boolean;
+    default: unknown;
+}
+/** `"dryRun"` -> `"dry-run"`. Already-kebab input passes through unchanged. */
+export declare function kebabCase(name: string): string;
+/**
+ * Parses `argv` (already stripped of the node binary and script path — i.e.
+ * `process.argv.slice(2)`) against the flags a script declared.
+ *
+ * `--flag value`, `--flag=value`, and `-f value` are all understood. A
+ * boolean flag never consumes the next token: its bare presence is `true`
+ * (`--flag=false` is honoured too, for the rare case of overriding a
+ * `default: true`).
+ *
+ * Every other token — anything not starting with `-`, or a bare `-` — is a
+ * positional argument and is silently ignored; this parser only cares about
+ * the flags it was told to look for.
+ *
+ * @throws {UnknownFlagError} for a `--foo`/`-f` this script never declared.
+ * @throws {MissingFlagValueError} for a non-boolean flag with nothing after it.
+ */
+export declare function parseFlags(argv: readonly string[], defs: readonly FlagDef[]): Record<string, unknown>;
+//# sourceMappingURL=flags.d.ts.map

package/dist/flags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flags.d.ts","sourceRoot":"","sources":["../src/flags.ts"],"names":[],"mappings":"AAMA,+EAA+E;AAC/E,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,+EAA+E;AAC/E,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAuDrG"}

package/dist/flags.js

@@ -0,0 +1,79 @@
+/**
+ * Command-line flag parsing for `Script.defineFlag` / `context.flags`.
+ * No dependency — a whitelist-driven pass over argv, nothing more.
+ */
+import { MissingFlagValueError, UnknownFlagError } from "./errors.js";
+/** `"dryRun"` -> `"dry-run"`. Already-kebab input passes through unchanged. */
+export function kebabCase(name) {
+    return name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+/**
+ * Parses `argv` (already stripped of the node binary and script path — i.e.
+ * `process.argv.slice(2)`) against the flags a script declared.
+ *
+ * `--flag value`, `--flag=value`, and `-f value` are all understood. A
+ * boolean flag never consumes the next token: its bare presence is `true`
+ * (`--flag=false` is honoured too, for the rare case of overriding a
+ * `default: true`).
+ *
+ * Every other token — anything not starting with `-`, or a bare `-` — is a
+ * positional argument and is silently ignored; this parser only cares about
+ * the flags it was told to look for.
+ *
+ * @throws {UnknownFlagError} for a `--foo`/`-f` this script never declared.
+ * @throws {MissingFlagValueError} for a non-boolean flag with nothing after it.
+ */
+export function parseFlags(argv, defs) {
+    const byLong = new Map(defs.map((def) => [def.long, def]));
+    const byShort = new Map(defs.filter((def) => def.short !== undefined).map((def) => [def.short, def]));
+    const result = {};
+    for (const def of defs) {
+        if (def.hasDefault)
+            result[def.name] = def.default;
+        else if (def.boolean)
+            result[def.name] = false;
+    }
+    let i = 0;
+    while (i < argv.length) {
+        const token = argv[i];
+        i += 1;
+        let def;
+        let inlineValue;
+        let label;
+        if (token.startsWith("--")) {
+            const body = token.slice(2);
+            const eq = body.indexOf("=");
+            const key = eq === -1 ? body : body.slice(0, eq);
+            inlineValue = eq === -1 ? undefined : body.slice(eq + 1);
+            label = `--${key}`;
+            def = byLong.get(key);
+            if (!def)
+                throw new UnknownFlagError(label, [...byLong.keys()].map((long) => `--${long}`));
+        }
+        else if (token.startsWith("-") && token.length > 1) {
+            const key = token.slice(1);
+            label = `-${key}`;
+            def = byShort.get(key);
+            if (!def)
+                throw new UnknownFlagError(label, [...byShort.keys()].map((short) => `-${short}`));
+        }
+        else {
+            continue;
+        }
+        if (def.boolean) {
+            result[def.name] = inlineValue === undefined ? true : inlineValue !== "false";
+            continue;
+        }
+        if (inlineValue !== undefined) {
+            result[def.name] = inlineValue;
+            continue;
+        }
+        const next = argv[i];
+        if (next === undefined)
+            throw new MissingFlagValueError(label);
+        result[def.name] = next;
+        i += 1;
+    }
+    return result;
+}
+//# sourceMappingURL=flags.js.map

package/dist/flags.js.map

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

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { Script, script, stepFor, routineFor, type CachedPhaseOptions, type ClosedPhase, type Commit, type MountInput, type MountOptions, type Mounted, type OpenPhase, type Routine, type RunOptions, } from "./script.js";
 export { fileStore, memoryStore } from "./cache.js";
-export { CacheShapeError, DuplicateNameError, RollbackFailedError, SchemaValidationError, ScriptAbortedError, StepDefinitionError, StepFailedError, StepTimeoutError, isAbort, } from "./errors.js";
-export type { Awaitable, CacheHandle, CacheMode, CacheOptions, CacheSource, CacheStore, CachedEntry, CleanField, Cleaned, LogPlacement, Merge, PhaseOptions, PhaseStatus, Prettify, ProgressHandle, RetryPolicy, RollbackContext, RollbackData, RollbackReport, RunResult, RunStatus, ScriptOptions, SlotValue, StaleContext, StepContext, StepDef, StepReport, StepStatus, TaskHandle, TaskListHandle, UnknownSlots, WithStepFor, } from "./types.js";
+export { CacheShapeError, DuplicateNameError, MissingFlagValueError, PromptCancelledError, PromptUnavailableError, RollbackFailedError, SchemaValidationError, ScriptAbortedError, StepDefinitionError, StepFailedError, StepTimeoutError, UnknownFlagError, isAbort, } from "./errors.js";
+export type { Awaitable, BaseFlagOptions, BooleanFlagOptions, CacheHandle, CacheMode, CacheOptions, CacheSource, CacheStore, CachedEntry, CleanField, Cleaned, ConfirmPromptOptions, LogPlacement, Merge, MultiSelectPromptOptions, PhaseOptions, PhaseStatus, Prettify, ProgressHandle, PromptChoice, PromptHandle, RetryPolicy, RollbackContext, RollbackData, RollbackReport, RunResult, RunStatus, ScriptOptions, SelectPromptOptions, SlotValue, StaleContext, StepContext, StepDef, InheritedKeyStepDef, StepReport, StepStatus, StringFlagOptions, TaskHandle, TaskListHandle, TextPromptOptions, UnknownFlags, UnknownSlots, WithStepFor, } from "./types.js";
 export { formatDuration } from "./state.js";
 export { setColorEnabled, isColorEnabled } from "./ui/ansi.js";
 export { palette, symbols } from "./ui/theme.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,MAAM,EACN,OAAO,EACP,UAAU,EACV,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,KAAK,MAAM,EACX,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,OAAO,EACZ,KAAK,SAAS,EACd,KAAK,OAAO,EACZ,KAAK,UAAU,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAChB,OAAO,GACR,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,SAAS,EACT,WAAW,EACX,SAAS,EACT,YAAY,EACZ,WAAW,EACX,UAAU,EACV,WAAW,EACX,UAAU,EACV,OAAO,EACP,YAAY,EACZ,KAAK,EACL,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,cAAc,EACd,WAAW,EACX,eAAe,EACf,YAAY,EACZ,cAAc,EACd,SAAS,EACT,SAAS,EACT,aAAa,EACb,SAAS,EACT,YAAY,EACZ,WAAW,EACX,OAAO,EACP,UAAU,EACV,UAAU,EACV,UAAU,EACV,cAAc,EACd,YAAY,EACZ,WAAW,GACZ,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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,MAAM,EACN,OAAO,EACP,UAAU,EACV,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,KAAK,MAAM,EACX,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,OAAO,EACZ,KAAK,SAAS,EACd,KAAK,OAAO,EACZ,KAAK,UAAU,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,EACtB,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,OAAO,GACR,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,SAAS,EACT,eAAe,EACf,kBAAkB,EAClB,WAAW,EACX,SAAS,EACT,YAAY,EACZ,WAAW,EACX,UAAU,EACV,WAAW,EACX,UAAU,EACV,OAAO,EACP,oBAAoB,EACpB,YAAY,EACZ,KAAK,EACL,wBAAwB,EACxB,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,eAAe,EACf,YAAY,EACZ,cAAc,EACd,SAAS,EACT,SAAS,EACT,aAAa,EACb,mBAAmB,EACnB,SAAS,EACT,YAAY,EACZ,WAAW,EACX,OAAO,EACP,mBAAmB,EACnB,UAAU,EACV,UAAU,EACV,iBAAiB,EACjB,UAAU,EACV,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,WAAW,GACZ,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

@@ -1,6 +1,6 @@
 export { Script, script, stepFor, routineFor, } from "./script.js";
 export { fileStore, memoryStore } from "./cache.js";
-export { CacheShapeError, DuplicateNameError, RollbackFailedError, SchemaValidationError, ScriptAbortedError, StepDefinitionError, StepFailedError, StepTimeoutError, isAbort, } from "./errors.js";
+export { CacheShapeError, DuplicateNameError, MissingFlagValueError, PromptCancelledError, PromptUnavailableError, RollbackFailedError, SchemaValidationError, ScriptAbortedError, StepDefinitionError, StepFailedError, StepTimeoutError, UnknownFlagError, isAbort, } from "./errors.js";
 export { formatDuration } from "./state.js";
 export { setColorEnabled, isColorEnabled } from "./ui/ansi.js";
 export { palette, symbols } from "./ui/theme.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,MAAM,EACN,OAAO,EACP,UAAU,GAUX,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAChB,OAAO,GACR,MAAM,aAAa,CAAC;AAqCrB,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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,MAAM,EACN,OAAO,EACP,UAAU,GAUX,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,EACtB,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,OAAO,GACR,MAAM,aAAa,CAAC;AAgDrB,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

@@ -1,5 +1,5 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
-import type { Awaitable, CacheMode, CacheSource, CleanField, Cleaned, Merge, PhaseOptions, RunResult, ScriptOptions, SlotValue, StepDef, UnknownSlots } from "./types.js";
+import type { Awaitable, BooleanFlagOptions, CacheMode, CacheSource, CleanField, Cleaned, Merge, PhaseOptions, RunResult, ScriptOptions, SlotValue, StepDef, StringFlagOptions, UnknownFlags, UnknownSlots, InheritedKeyStepDef } from "./types.js";
 /**
  * Keys for the phantom markers on {@link Script} and {@link Routine}. Exported
  * only because declaration emit has to name them; there is no runtime value
@@ -98,6 +98,12 @@ export interface RunOptions {
      * to control caching without touching the script.
      */
     cache?: CacheMode;
+    /**
+     * Argv to parse `defineFlag`'s flags out of. Default `process.argv.slice(2)`
+     * — override it in a test, or when this script is one subcommand of a
+     * larger CLI that has already sliced its own argv apart.
+     */
+    argv?: readonly string[];
 }
 /**
  * A saga-style script: phases of steps, each step optionally compensating when
@@ -126,7 +132,7 @@ export interface RunOptions {
  * The third parameter is inferred too: it collects the keys steps reserved
  * through `rollbackKeys`, which is how `clean` knows what it may not remove.
  */
-export declare class Script<In = void, Ctx extends object = {}, Reserved extends PropertyKey = never, Slots = {}, Open extends OpenPhase = ClosedPhase> {
+export declare class Script<In = void, Ctx extends object = {}, Reserved extends PropertyKey = never, Slots = {}, Open extends OpenPhase = ClosedPhase, Flags extends object = {}> {
     /**
      * Phantom, erased at compile time. `run` is a *method*, so its parameter
      * compares bivariantly and `In` would otherwise carry no safety across two
@@ -142,6 +148,10 @@ export declare class Script<In = void, Ctx extends object = {}, Reserved extends
     /** False right after `use()`, so a bare `addStep` cannot land in a fragment. */
     private openPhase;
     private _schema;
+    private readonly flagDefs;
+    private readonly flagNames;
+    private readonly flagLongs;
+    private readonly flagShorts;
     constructor(options?: ScriptOptions | string);
     /**
      * Provide a [Standard Schema](https://standardschema.dev) describing the run
@@ -163,9 +173,46 @@ export declare class Script<In = void, Ctx extends object = {}, Reserved extends
      *   });
      * ```
      */
-    defineInput<TSchema>(schema: StandardSchemaV1<unknown, TSchema>): Script<TSchema, Ctx, Reserved>;
+    defineInput<TSchema>(schema: StandardSchemaV1<unknown, TSchema>): Script<TSchema, Ctx, Reserved, {}, ClosedPhase, Flags>;
     /** Validate `input` against the schema from `defineInput`, if any. */
     private validateInput;
+    /**
+     * Declare a flag this script reads off the command line. `name` is both the
+     * property `context.flags` exposes it under and — kebab-cased — the default
+     * long `--` form; `short` adds a single-letter `-` alias, and `long`
+     * overrides the derived one when it should read differently from `name`.
+     *
+     * A `boolean: true` flag is present or absent (`myScript --force`) and
+     * always resolves to a `boolean`, defaulting to `false` unless
+     * `default: true`. Anything else is a string: `myScript --env prod` or
+     * `myScript -e prod`, resolving to `string` when a `default` is given, or
+     * `string | undefined` otherwise. Values are parsed from `process.argv`
+     * (or `run(input, { argv })`) once, before any phase executes.
+     *
+     * ```ts
+     * new Script({ name: "deploy" })
+     *   .defineFlag({ name: "environment", long: "env", short: "e", default: "staging" })
+     *   .defineFlag({ name: "force", short: "f", boolean: true })
+     *   .addStep({
+     *     name: "deploy",
+     *     // flags.environment: string, flags.force: boolean
+     *     handler: async ({ flags }) => { ... },
+     *   });
+     * ```
+     *
+     * @throws {DuplicateNameError} if `name`, the resolved long flag, or `short`
+     * is already used by another flag on this script.
+     */
+    defineFlag<const Name extends string>(options: BooleanFlagOptions<Name>): Script<In, Ctx, Reserved, Slots, Open, Flags & Record<Name, boolean>>;
+    defineFlag<const Name extends string, const Default extends string | undefined = undefined>(options: StringFlagOptions<Name, Default>): Script<In, Ctx, Reserved, Slots, Open, Flags & Record<Name, Default extends string ? string : string | undefined>>;
+    /**
+     * Flag identities have to be unique the same way phase and step names do —
+     * `name` is the property key on `context.flags`, and the long/short forms
+     * are what argv is matched against.
+     */
+    private claimFlagIdentity;
+    /** Parse `argv` against this script's declared flags — `{}` when none are. */
+    private resolveFlags;
     /**
      * Open a cached phase. Its name becomes a slot addressable through
      * `context.cache` in every step declared after it — typed as the phase's own
@@ -176,36 +223,43 @@ export declare class Script<In = void, Ctx extends object = {}, Reserved extends
         phase: Name;
         schema: Value;
         delta: {};
-    }>;
+    }, Flags>;
     /** Open a new phase. Subsequent `addStep` calls land in it. */
     addPhase<const Name extends string>(name: Name, options?: PhaseOptions<In, Ctx>): Script<In, Ctx, Reserved, Commit<Slots, Open>, {
         name: never;
         phase: Name;
         schema: unknown;
         delta: {};
-    }>;
+    }, Flags>;
     /** Open a phase and populate it inside a callback, keeping the type flow. */
-    addPhase<Next extends object, NextReserved extends PropertyKey, NextSlots, NextOpen extends OpenPhase>(name: string, build: (script: Script<In, Ctx, Reserved, Commit<Slots, Open>, ClosedPhase>) => Script<In, Next, NextReserved, NextSlots, NextOpen>): Script<In, Next, NextReserved, NextSlots, NextOpen>;
-    addPhase<Next extends object, NextReserved extends PropertyKey, NextSlots, NextOpen extends OpenPhase>(name: string, options: PhaseOptions<In, Ctx>, build: (script: Script<In, Ctx, Reserved, Commit<Slots, Open>, ClosedPhase>) => Script<In, Next, NextReserved, NextSlots, NextOpen>): Script<In, Next, NextReserved, NextSlots, NextOpen>;
+    addPhase<Next extends object, NextReserved extends PropertyKey, NextSlots, NextOpen extends OpenPhase, NextFlags extends object>(name: string, build: (script: Script<In, Ctx, Reserved, Commit<Slots, Open>, ClosedPhase, Flags>) => Script<In, Next, NextReserved, NextSlots, NextOpen, NextFlags>): Script<In, Next, NextReserved, NextSlots, NextOpen, NextFlags>;
+    addPhase<Next extends object, NextReserved extends PropertyKey, NextSlots, NextOpen extends OpenPhase, NextFlags extends object>(name: string, options: PhaseOptions<In, Ctx>, build: (script: Script<In, Ctx, Reserved, Commit<Slots, Open>, ClosedPhase, Flags>) => Script<In, Next, NextReserved, NextSlots, NextOpen, NextFlags>): Script<In, Next, NextReserved, NextSlots, NextOpen, NextFlags>;
     /**
      * Append a step to the current phase. Whatever the handler resolves to is
      * merged into the context and becomes visible to every later step; whatever
      * it lists in `clean` is dropped from both.
      *
-     * @throws {StepDefinitionError} if `clean` names a key reserved by some
-     * step's `rollbackKeys`.
-     */
-    /**
-     * A step that caches. It contributes its own slot, `phase::step`, holding
+     * There are four signatures, along two independent splits.
+     *
+     * A step that caches contributes its own slot, `phase::step`, holding
      * exactly what the handler returns — addressable through `context.cache` in
-     * every step declared after it.
+     * every step declared after it. That is split from the plain form rather
+     * than inferred from the presence of `cache`: an optional property cannot be
+     * told apart from its own default, so a single signature always resolved to
+     * "no cache" and quietly dropped the slot.
+     *
+     * Crossed with that, each form is tried first as an
+     * {@link InheritedKeyStepDef} — `rollbackKeys` naming only keys the context
+     * already has — which is what keeps the handler as the sole inference site
+     * for `Out`. A step naming one of its own output keys fails that signature's
+     * `RollbackKeys` constraint in inference's first pass and falls through to
+     * the general {@link StepDef} form below.
      *
-     * Split from the plain form rather than inferring the presence of `cache`:
-     * an optional property cannot be told apart from its own default, so a
-     * single signature always resolved to "no cache" and quietly dropped the
-     * slot.
+     * @throws {StepDefinitionError} if `clean` names a key reserved by some
+     * step's `rollbackKeys`.
      */
-    addStep<Out extends object | void, const Name extends string, const RollbackKeys extends readonly PropertyKey[] = readonly [], const CleanKeys extends readonly PropertyKey[] = readonly []>(def: Omit<StepDef<In, Ctx, Out, RollbackKeys, Slots>, "name"> & CleanField<Ctx, Reserved, CleanKeys> & {
+    /** Cached, `rollbackKeys` inherited. See {@link InheritedKeyStepDef}. */
+    addStep<Out extends object | void = void, const Name extends string = string, const RollbackKeys extends readonly (keyof Ctx)[] = readonly [], const CleanKeys extends readonly PropertyKey[] = readonly []>(def: Omit<InheritedKeyStepDef<In, Ctx, Out, RollbackKeys, Slots, Flags>, "name"> & CleanField<Ctx, Reserved, CleanKeys> & {
         name: Name;
         cache: CacheSource<In, Ctx>;
     }): Script<In, Cleaned<Merge<Ctx, Out>, CleanKeys[number]>, Reserved | RollbackKeys[number], Slots & Record<`${Open["phase"]}::${Name}`, Out>, {
@@ -213,21 +267,31 @@ export declare class Script<In = void, Ctx extends object = {}, Reserved extends
         phase: Open["phase"];
         schema: Open["schema"];
         delta: Cleaned<Merge<Open["delta"], Out>, CleanKeys[number]>;
-    }>;
-    /**
-     * Append a step to the current phase. Whatever the handler resolves to is
-     * merged into the context and becomes visible to every later step; whatever
-     * it lists in `clean` is dropped from both.
-     *
-     * @throws {StepDefinitionError} if `clean` names a key reserved by some
-     * step's `rollbackKeys`.
-     */
-    addStep<Out extends object | void, const RollbackKeys extends readonly PropertyKey[] = readonly [], const CleanKeys extends readonly PropertyKey[] = readonly []>(def: StepDef<In, Ctx, Out, RollbackKeys, Slots> & CleanField<Ctx, Reserved, CleanKeys>): Script<In, Cleaned<Merge<Ctx, Out>, CleanKeys[number]>, Reserved | RollbackKeys[number], Slots, {
+    }, Flags>;
+    /** Plain, `rollbackKeys` inherited. See {@link InheritedKeyStepDef}. */
+    addStep<Out extends object | void = void, const RollbackKeys extends readonly (keyof Ctx)[] = readonly [], const CleanKeys extends readonly PropertyKey[] = readonly []>(def: InheritedKeyStepDef<In, Ctx, Out, RollbackKeys, Slots, Flags> & CleanField<Ctx, Reserved, CleanKeys>): Script<In, Cleaned<Merge<Ctx, Out>, CleanKeys[number]>, Reserved | RollbackKeys[number], Slots, {
         name: Open["name"];
         phase: Open["phase"];
         schema: Open["schema"];
         delta: Cleaned<Merge<Open["delta"], Out>, CleanKeys[number]>;
-    }>;
+    }, Flags>;
+    /** Cached, general form. See {@link StepDef}. */
+    addStep<Out extends object | void, const Name extends string, const RollbackKeys extends readonly PropertyKey[] = readonly [], const CleanKeys extends readonly PropertyKey[] = readonly []>(def: Omit<StepDef<In, Ctx, Out, RollbackKeys, Slots, Flags>, "name"> & CleanField<Ctx, Reserved, CleanKeys> & {
+        name: Name;
+        cache: CacheSource<In, Ctx>;
+    }): Script<In, Cleaned<Merge<Ctx, Out>, CleanKeys[number]>, Reserved | RollbackKeys[number], Slots & Record<`${Open["phase"]}::${Name}`, Out>, {
+        name: Open["name"];
+        phase: Open["phase"];
+        schema: Open["schema"];
+        delta: Cleaned<Merge<Open["delta"], Out>, CleanKeys[number]>;
+    }, Flags>;
+    /** Plain, general form. See {@link StepDef}. */
+    addStep<Out extends object | void, const RollbackKeys extends readonly PropertyKey[] = readonly [], const CleanKeys extends readonly PropertyKey[] = readonly []>(def: StepDef<In, Ctx, Out, RollbackKeys, Slots, Flags> & CleanField<Ctx, Reserved, CleanKeys>): Script<In, Cleaned<Merge<Ctx, Out>, CleanKeys[number]>, Reserved | RollbackKeys[number], Slots, {
+        name: Open["name"];
+        phase: Open["phase"];
+        schema: Open["schema"];
+        delta: Cleaned<Merge<Open["delta"], Out>, CleanKeys[number]>;
+    }, Flags>;
     /**
      * Splice a reusable fragment into this script. Its phases land here in
      * order, and everything it produced is merged into the context — so the
@@ -257,17 +321,17 @@ export declare class Script<In = void, Ctx extends object = {}, Reserved extends
     use<SubIn, Out extends object, R extends PropertyKey, RS, const As extends string | undefined = undefined>(routine: Routine<SubIn, Ctx, Out, R, RS>, options: {
         as?: As;
         input: MountInput<In, Ctx, SubIn>;
-    }): Script<In, Merge<Ctx, Out>, Reserved | R, Commit<Slots, Open> & Mounted<As, RS>, ClosedPhase>;
-    use<SubIn, Out extends object, R extends PropertyKey, SS, SO extends OpenPhase, const As extends string | undefined = undefined>(script: Script<SubIn, Out, R, SS, SO>, options: {
+    }): Script<In, Merge<Ctx, Out>, Reserved | R, Commit<Slots, Open> & Mounted<As, RS>, ClosedPhase, Flags>;
+    use<SubIn, Out extends object, R extends PropertyKey, SS, SO extends OpenPhase, MF extends object, const As extends string | undefined = undefined>(script: Script<SubIn, Out, R, SS, SO, MF>, options: {
         as?: As;
         input: MountInput<In, Ctx, SubIn>;
-    }): Script<In, Merge<Ctx, Out>, Reserved | R, Commit<Slots, Open> & Mounted<As, Commit<SS, SO>>, ClosedPhase>;
-    use<Out extends object, R extends PropertyKey, SS, SO extends OpenPhase, const As extends string | undefined = undefined>(script: Script<In, Out, R, SS, SO>, options?: {
+    }): Script<In, Merge<Ctx, Out>, Reserved | R, Commit<Slots, Open> & Mounted<As, Commit<SS, SO>>, ClosedPhase, Flags>;
+    use<Out extends object, R extends PropertyKey, SS, SO extends OpenPhase, MF extends object, const As extends string | undefined = undefined>(script: Script<In, Out, R, SS, SO, MF>, options?: {
         as?: As;
-    }): Script<In, Merge<Ctx, Out>, Reserved | R, Commit<Slots, Open> & Mounted<As, Commit<SS, SO>>, ClosedPhase>;
+    }): Script<In, Merge<Ctx, Out>, Reserved | R, Commit<Slots, Open> & Mounted<As, Commit<SS, SO>>, ClosedPhase, Flags>;
     use<Out extends object, R extends PropertyKey, RS, const As extends string | undefined = undefined>(routine: Routine<In, Ctx, Out, R, RS>, options?: {
         as?: As;
-    }): Script<In, Merge<Ctx, Out>, Reserved | R, Commit<Slots, Open> & Mounted<As, RS>, ClosedPhase>;
+    }): Script<In, Merge<Ctx, Out>, Reserved | R, Commit<Slots, Open> & Mounted<As, RS>, ClosedPhase, Flags>;
     /** Every step name, in execution order — handy for tests and docs. */
     outline(): Array<{
         phase: string;
@@ -306,7 +370,10 @@ export declare class Script<In = void, Ctx extends object = {}, Reserved extends
  * `rollbackKeys` works the same here, and the keys it names stay reserved once
  * the step is handed to `addStep`.
  */
-export declare function stepFor<In, Ctx extends object = {}, Slots = UnknownSlots>(): <Out extends object | void, const RollbackKeys extends readonly PropertyKey[] = readonly []>(def: StepDef<In, Ctx, Out, RollbackKeys, Slots>) => StepDef<In, Ctx, Out, RollbackKeys, Slots>;
+export declare function stepFor<In, Ctx extends object = {}, Slots = UnknownSlots, Flags = UnknownFlags>(): {
+    <Out extends object | void = void, const RollbackKeys extends readonly (keyof Ctx)[] = readonly []>(def: InheritedKeyStepDef<In, Ctx, Out, RollbackKeys, Slots, Flags>): StepDef<In, Ctx, Out, RollbackKeys, Slots, Flags>;
+    <Out extends object | void, const RollbackKeys extends readonly PropertyKey[] = readonly []>(def: StepDef<In, Ctx, Out, RollbackKeys, Slots, Flags>): StepDef<In, Ctx, Out, RollbackKeys, Slots, Flags>;
+};
 /**
  * Declare phases and steps away from any particular script, then mount them
  * with {@link Script.use}.