effect-pulumi 0.1.1 → 0.2.0

package/dist/index.js

@@ -1,211 +1,470 @@
-import { Data, Effect } from 'effect';
-import * as pulumi2 from '@pulumi/pulumi';
-import { LocalWorkspace } from '@pulumi/pulumi/automation/index.js';
-
-// src/errors.ts
-var describeCause = (cause) => cause instanceof Error ? cause.message : String(cause);
+import { Data, Effect } from "effect";
+import * as pulumi from "@pulumi/pulumi";
+import { LocalWorkspace } from "@pulumi/pulumi/automation/index.js";
+//#region src/errors.ts
+const describeCause = (cause) => cause instanceof Error ? cause.message : String(cause);
+/**
+* Any synchronous failure constructing a resource (bad args, provider
+* validation, etc.), or a failure resolving an Output's promise.
+*
+* Tagged `"PulumiError"`, so it can be matched by tag rather than by
+* `instanceof`:
+*
+* @example
+* ```ts
+* program.pipe(
+*   Effect.catchTag("PulumiError", (e) => Effect.logError(e.message))
+* );
+* ```
+*/
 var PulumiError = class extends Data.TaggedError("PulumiError") {
-  /** Derived so anything reading `.message` - plain logging, test failure
-   * output, non-Effect error handling - sees the underlying failure instead
-   * of an empty string. */
-  get message() {
-    return describeCause(this.cause);
-  }
+	/** Derived so anything reading `.message` - plain logging, test failure
+	* output, non-Effect error handling - sees the underlying failure instead
+	* of an empty string. */
+	get message() {
+		return describeCause(this.cause);
+	}
 };
+/**
+* Failure from an Automation API lifecycle call (up/preview/destroy/select).
+*
+* `stage` says which call failed, which matters most in the composite
+* operations: a failed `deploy` could have died selecting the stack, applying
+* config, or running the update, and the three want different responses.
+*
+* @example
+* ```ts
+* deploy(opts).pipe(
+*   Effect.catchTag("AutomationError", (e) =>
+*     e.stage === "createOrSelectStack"
+*       ? Effect.fail(new BackendUnreachable())
+*       : Effect.logError(e.message)
+*   )
+* );
+* ```
+*/
 var AutomationError = class extends Data.TaggedError("AutomationError") {
-  /** `"<stage> failed: <cause>"` - the stage is included because the cause
-   * alone rarely says which operation produced it. */
-  get message() {
-    return `${this.stage} failed: ${describeCause(this.cause)}`;
-  }
+	/** `"<stage> failed: <cause>"` - the stage is included because the cause
+	* alone rarely says which operation produced it. */
+	get message() {
+		return `${this.stage} failed: ${describeCause(this.cause)}`;
+	}
 };
-var fromOutput = (output) => Effect.tryPromise({
-  try: () => output.promise(true),
-  catch: (cause) => new PulumiError({ cause })
+//#endregion
+//#region src/output-bridge.ts
+/**
+* Lift a single Output into an Effect.
+*
+* `withUnknowns: true` matters during `pulumi preview`, where a not-yet-created
+* resource's outputs have no value: it resolves to Pulumi's unknown sentinel
+* instead of throwing, so a program that reads outputs still previews cleanly.
+*
+* @param output - The Output to resolve.
+* @returns An Effect yielding the settled value, failing with
+* {@link PulumiError} if the underlying promise rejects.
+*
+* @example
+* ```ts
+* const bucket = yield* eaws.s3.Bucket("assets", {});
+* const id = yield* fromOutput(bucket.id); // string
+* ```
+*
+* @remarks Reading an Output only makes sense inside a running Pulumi program.
+* During `preview` the value may be the unknown sentinel rather than real data,
+* so don't branch on it to decide what to create.
+*/
+const fromOutput = (output) => Effect.tryPromise({
+	try: () => output.promise(true),
+	catch: (cause) => new PulumiError({ cause })
 });
-var fromOutputs = (outputs) => fromOutput(pulumi2.all(outputs));
-var isResourceConstructor = (value) => typeof value === "function" && (value === pulumi2.Resource || value.prototype instanceof pulumi2.Resource);
-var isComponentResourceConstructor = (Ctor) => Ctor === pulumi2.ComponentResource || Ctor.prototype instanceof pulumi2.ComponentResource;
-var isNamespace = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-var isArgsObject = (value) => isNamespace(value);
-var isPromiseLike = (value) => typeof value === "object" && value !== null && typeof value.then === "function";
-var proxyCache = /* @__PURE__ */ new WeakMap();
-var isEffect = (value) => Effect.isEffect(value);
+/**
+* Lift a record of Outputs into a single Effect of the resolved record - use
+* this right after constructing a resource to grab several fields at once.
+*
+* Resolves them together via `pulumi.all`, so it costs one await rather than
+* one per field.
+*
+* @param outputs - A record whose values are all Outputs. Interfaces work as
+* well as object literals; the constraint is self-referential rather than
+* `Record<string, Output<any>>` precisely so interface-typed bags are accepted.
+* @returns An Effect yielding the same record with each value unwrapped.
+*
+* @example
+* ```ts
+* const bucket = yield* eaws.s3.Bucket("assets", {});
+* const { id, arn } = yield* fromOutputs({ id: bucket.id, arn: bucket.arn });
+* ```
+*/
+const fromOutputs = (outputs) => fromOutput(pulumi.all(outputs));
+//#endregion
+//#region src/effectify.ts
+/**
+* effectify - auto-wrap a Pulumi provider package (e.g. @pulumi/aws,
+* @pulumi/cloudflare) so every resource constructor becomes an
+* Effect-returning factory, without the caller ever writing `Effect.sync`.
+*
+* Usage:
+*
+*   import * as aws from "@pulumi/aws";
+*   const eaws = effectify(aws);
+*
+*   const program = Effect.gen(function* () {
+*     const bucket = yield* eaws.s3.Bucket("my-bucket", { forceDestroy: true });
+*     //    ^ Effect<aws.s3.Bucket, PulumiError> - no manual wrapping
+*   });
+*
+* How it works:
+*  - Every Pulumi resource class extends `pulumi.Resource` under the hood
+*    (via CustomResource / ComponentResource). That's the runtime marker
+*    used to tell "this export is a resource constructor" apart from "this
+*    export is a namespace object" (e.g. `aws.s3`) or "this export is an
+*    invoke function" (e.g. `aws.s3.getBucket`).
+*  - Namespace objects get recursively proxied (lazily, memoized).
+*  - CustomResource constructors get wrapped so any field in their args
+*    object may *additionally* be an Effect - resolved (concurrently, they
+*    are independent by construction) before construction. This is safe
+*    because codegen guarantees CustomResource args are always
+*    Record<string, Input<T>>.
+*  - Wrapped constructors keep their static members: `Bucket.get(...)`,
+*    `Bucket.isInstance(...)` and friends forward to the original class, so
+*    the wrapped package can be the only import a program needs.
+*  - ComponentResource constructors get wrapped with no arg-lifting - args
+*    pass through exactly as declared, since component args aren't
+*    guaranteed to be Input<T>-shaped (hand-authored, may do synchronous
+*    work on a bare primitive inside the constructor).
+*  - Invoke functions (`aws.s3.getBucket`) return an Effect instead of a
+*    Promise. There is no runtime marker for "this function is async", so
+*    the wrapper calls the function and inspects the result: a thenable
+*    becomes an Effect, anything else is returned as-is. That means the
+*    invoke *starts* at the call site (see the caveat on `wrapInvokeLike`);
+*    `*Output` invoke variants return an Output, which is not thenable, so
+*    they pass through untouched - matching the type-level mapping, which
+*    only rewrites Promise-returning signatures.
+*  - Everything else (enums, plain values, non-resource classes) passes
+*    through untouched.
+*
+* Resource registration remains synchronous under the hood - Effect.try
+* runs its thunk immediately. This only removes hand-written wrapper
+* boilerplate, not Pulumi's execution model.
+*/
+const isResourceConstructor = (value) => typeof value === "function" && (value === pulumi.Resource || value.prototype instanceof pulumi.Resource);
+const isComponentResourceConstructor = (Ctor) => Ctor === pulumi.ComponentResource || Ctor.prototype instanceof pulumi.ComponentResource;
+/** Is this a namespace to recurse into? The narrowed type is only ever handed
+* to `effectifyInner`, which takes `object` - so claim exactly that and no
+* more. */
+const isNamespace = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Is this an args object whose entries we can scan for Effects? Same runtime
+* check as `isNamespace`, but a different question, so it gets the narrowing
+* that question needs: `object` would make `Object.entries` infer `any` values
+* and silently drop the `isEffect` filter's type safety. */
+const isArgsObject = (value) => isNamespace(value);
+/** Note: `pulumi.Output` is deliberately not thenable, so `*Output` invoke
+* variants fail this check and pass through unwrapped - keeping the runtime
+* behaviour aligned with the type mapping, which only rewrites
+* Promise-returning signatures. */
+const isPromiseLike = (value) => typeof value === "object" && value !== null && typeof value.then === "function";
+const proxyCache = /* @__PURE__ */ new WeakMap();
+const isEffect = (value) => Effect.isEffect(value);
 function resolveLiftedArgs(args) {
-  if (!isArgsObject(args)) {
-    return Effect.succeed(args);
-  }
-  const effectEntries = Object.entries(args).filter(([, v]) => isEffect(v));
-  if (effectEntries.length === 0) {
-    return Effect.succeed(args);
-  }
-  return Effect.map(
-    Effect.all(
-      effectEntries.map(
-        ([key, effectValue]) => Effect.map(
-          effectValue,
-          (resolved) => [key, resolved]
-        )
-      ),
-      { concurrency: "unbounded" }
-    ),
-    (resolved) => ({ ...args, ...Object.fromEntries(resolved) })
-  );
+	if (!isArgsObject(args)) return Effect.succeed(args);
+	const effectEntries = Object.entries(args).filter(([, v]) => isEffect(v));
+	if (effectEntries.length === 0) return Effect.succeed(args);
+	return Effect.map(Effect.all(effectEntries.map(([key, effectValue]) => Effect.map(effectValue, (resolved) => [key, resolved])), { concurrency: "unbounded" }), (resolved) => ({
+		...args,
+		...Object.fromEntries(resolved)
+	}));
 }
 function wrapCustomResourceCtor(Ctor) {
-  return (name, args, opts) => Effect.gen(function* () {
-    const resolvedArgs = yield* resolveLiftedArgs(args);
-    return yield* Effect.try({
-      try: () => new Ctor(name, resolvedArgs, opts),
-      catch: (cause) => new PulumiError({ cause })
-    });
-  });
+	return (name, args, opts) => Effect.gen(function* () {
+		const resolvedArgs = yield* resolveLiftedArgs(args);
+		return yield* Effect.try({
+			try: () => new Ctor(name, resolvedArgs, opts),
+			catch: (cause) => new PulumiError({ cause })
+		});
+	});
 }
 function wrapComponentResourceCtor(Ctor) {
-  return (name, args, opts) => Effect.try({
-    try: () => new Ctor(name, args, opts),
-    catch: (cause) => new PulumiError({ cause })
-  });
+	return (name, args, opts) => Effect.try({
+		try: () => new Ctor(name, args, opts),
+		catch: (cause) => new PulumiError({ cause })
+	});
 }
-var withStatics = (factory, Ctor) => new Proxy(factory, {
-  get: (target, prop, receiver) => Reflect.has(target, prop) ? Reflect.get(target, prop, receiver) : Reflect.get(Ctor, prop),
-  has: (target, prop) => Reflect.has(target, prop) || Reflect.has(Ctor, prop)
+/** Forward static members (codegen'd `get`, `isInstance`, …) from the class
+* onto the factory. The factory's own and inherited properties (`name`,
+* `length`, `call`, …) win; anything else falls through to the class, so new
+* statics keep working without being enumerated here. A bonus of forwarding
+* `prototype` is that `x instanceof wrapped` still works. */
+const withStatics = (factory, Ctor) => new Proxy(factory, {
+	get: (target, prop, receiver) => Reflect.has(target, prop) ? Reflect.get(target, prop, receiver) : Reflect.get(Ctor, prop),
+	has: (target, prop) => Reflect.has(target, prop) || Reflect.has(Ctor, prop)
 });
 function wrapResourceCtor(Ctor) {
-  const factory = isComponentResourceConstructor(Ctor) ? wrapComponentResourceCtor(Ctor) : wrapCustomResourceCtor(
-    Ctor
-  );
-  return withStatics(factory, Ctor);
+	const factory = isComponentResourceConstructor(Ctor) ? wrapComponentResourceCtor(Ctor) : wrapCustomResourceCtor(Ctor);
+	return withStatics(factory, Ctor);
 }
+/** Turn a Promise-returning invoke into an Effect-returning one, leaving
+* synchronous functions' behaviour untouched.
+*
+* A Proxy over the original function (rather than a new function) so `name`,
+* `length`, own properties and prototype all survive; only the call itself is
+* intercepted.
+*
+* Caveat, stated openly: whether a function is async is only knowable by
+* calling it, so the invoke *starts* when the factory is called - the Effect
+* resolves an already-in-flight Promise rather than deferring the call. Two
+* consequences:
+*  - `Effect.retry` re-awaits the same call instead of re-invoking. To
+*    re-invoke per attempt, wrap the call site: `Effect.suspend(() =>
+*    eaws.getAmi(args))`.
+*  - A discarded Effect must not surface as an unhandled rejection, so the
+*    rejection is pre-observed on a side branch before the Effect awaits it.
+*/
 function wrapInvokeLike(fn) {
-  return new Proxy(fn, {
-    apply(target, thisArg, args) {
-      const result = Reflect.apply(target, thisArg, args);
-      if (!isPromiseLike(result)) {
-        return result;
-      }
-      result.then(void 0, () => {
-      });
-      return Effect.tryPromise({
-        try: () => result,
-        catch: (cause) => new PulumiError({ cause })
-      });
-    }
-  });
+	return new Proxy(fn, { apply(target, thisArg, args) {
+		const result = Reflect.apply(target, thisArg, args);
+		if (!isPromiseLike(result)) return result;
+		result.then(void 0, () => {});
+		return Effect.tryPromise({
+			try: () => result,
+			catch: (cause) => new PulumiError({ cause })
+		});
+	} });
 }
-var wrapperCache = /* @__PURE__ */ new WeakMap();
+/** Wrapped constructors are cached so repeated reads of the same property
+* hand back the same function - identity checks like
+* `eaws.s3.Bucket === eaws.s3.Bucket` hold, and the `get` and
+* `getOwnPropertyDescriptor` traps agree on a property's value. */
+const wrapperCache = /* @__PURE__ */ new WeakMap();
 function effectifyValue(value) {
-  if (isResourceConstructor(value)) {
-    const cached = wrapperCache.get(value);
-    if (cached) return cached;
-    const wrapped = wrapResourceCtor(value);
-    wrapperCache.set(value, wrapped);
-    return wrapped;
-  }
-  if (typeof value === "function") {
-    const cached = wrapperCache.get(value);
-    if (cached) return cached;
-    const wrapped = wrapInvokeLike(value);
-    wrapperCache.set(value, wrapped);
-    return wrapped;
-  }
-  if (isNamespace(value)) {
-    return effectifyInner(value);
-  }
-  return value;
+	if (isResourceConstructor(value)) {
+		const cached = wrapperCache.get(value);
+		if (cached) return cached;
+		const wrapped = wrapResourceCtor(value);
+		wrapperCache.set(value, wrapped);
+		return wrapped;
+	}
+	if (typeof value === "function") {
+		const cached = wrapperCache.get(value);
+		if (cached) return cached;
+		const wrapped = wrapInvokeLike(value);
+		wrapperCache.set(value, wrapped);
+		return wrapped;
+	}
+	if (isNamespace(value)) return effectifyInner(value);
+	return value;
 }
 function effectifyInner(mod) {
-  const cached = proxyCache.get(mod);
-  if (cached) return cached;
-  const proxy = new Proxy(/* @__PURE__ */ Object.create(null), {
-    get(_target, prop) {
-      return effectifyValue(Reflect.get(mod, prop));
-    },
-    has(_target, prop) {
-      return Reflect.has(mod, prop);
-    },
-    ownKeys() {
-      return Reflect.ownKeys(mod);
-    },
-    getOwnPropertyDescriptor(_target, prop) {
-      const descriptor = Reflect.getOwnPropertyDescriptor(mod, prop);
-      if (!descriptor) return void 0;
-      return {
-        value: effectifyValue(Reflect.get(mod, prop)),
-        enumerable: descriptor.enumerable,
-        configurable: true,
-        writable: true
-      };
-    },
-    set() {
-      return false;
-    }
-  });
-  proxyCache.set(mod, proxy);
-  return proxy;
+	const cached = proxyCache.get(mod);
+	if (cached) return cached;
+	const proxy = new Proxy(Object.create(null), {
+		get(_target, prop) {
+			return effectifyValue(Reflect.get(mod, prop));
+		},
+		has(_target, prop) {
+			return Reflect.has(mod, prop);
+		},
+		ownKeys() {
+			return Reflect.ownKeys(mod);
+		},
+		getOwnPropertyDescriptor(_target, prop) {
+			const descriptor = Reflect.getOwnPropertyDescriptor(mod, prop);
+			if (!descriptor) return void 0;
+			return {
+				value: effectifyValue(Reflect.get(mod, prop)),
+				enumerable: descriptor.enumerable,
+				configurable: true,
+				writable: true
+			};
+		},
+		set() {
+			return false;
+		}
+	});
+	proxyCache.set(mod, proxy);
+	return proxy;
 }
+/**
+* Wrap a provider package (or any namespace) once, turning every resource
+* constructor into an `Effect`-returning factory and every `Promise`-returning
+* invoke into an `Effect`-returning function.
+*
+* Call this once per package at module scope and export the result - the
+* wrapper is cached, so repeated calls and repeated property reads hand back
+* the same objects, but there is no reason to re-wrap.
+*
+* @param mod - The provider package, or any namespace within one. Not mutated;
+* the result is a read-only proxy that forwards to it.
+* @returns A same-shaped view of `mod`, typed by {@link Effectify}.
+*
+* @example Constructing a resource
+* ```ts
+* import * as aws from "@pulumi/aws";
+* const eaws = effectify(aws);
+*
+* const program = Effect.gen(function* () {
+*   const bucket = yield* eaws.s3.Bucket("assets", { forceDestroy: true });
+*   return bucket.id;
+* });
+* ```
+*
+* @example Passing an Effect as an argument
+* A `CustomResource`'s args may hold Effects, which are resolved concurrently
+* before the resource is constructed:
+* ```ts
+* yield* eaws.s3.BucketObject("readme", {
+*   bucket: bucketIdEffect,
+*   content: "hello",
+* });
+* ```
+*
+* @throws Nothing. Failures surface in the returned Effect's error channel as
+* {@link PulumiError} - including synchronous throws from the constructor.
+*
+* @see {@link Effectify} for the type-level mapping.
+*/
 function effectify(mod) {
-  return effectifyInner(mod);
+	return effectifyInner(mod);
 }
-var isLocal = (opts) => "workDir" in opts;
-var createOrSelectStack = (opts) => Effect.tryPromise({
-  try: () => isLocal(opts) ? LocalWorkspace.createOrSelectStack(
-    { stackName: opts.stackName, workDir: opts.workDir },
-    opts.workspaceOptions
-  ) : LocalWorkspace.createOrSelectStack(
-    {
-      stackName: opts.stackName,
-      projectName: opts.projectName,
-      program: opts.program
-    },
-    opts.workspaceOptions
-  ),
-  catch: (cause) => new AutomationError({ stage: "createOrSelectStack", cause })
+//#endregion
+//#region src/automation.ts
+const isLocal = (opts) => "workDir" in opts;
+/** Select the stack, creating it if it does not exist, and return the handle
+* every other operation here takes.
+*
+* Creating the workspace is itself work - it may write files and shell out to
+* the CLI - so hold on to the returned `Stack` rather than re-selecting before
+* each operation. */
+const createOrSelectStack = (opts) => Effect.tryPromise({
+	try: () => isLocal(opts) ? LocalWorkspace.createOrSelectStack({
+		stackName: opts.stackName,
+		workDir: opts.workDir
+	}, opts.workspaceOptions) : LocalWorkspace.createOrSelectStack({
+		stackName: opts.stackName,
+		projectName: opts.projectName,
+		program: opts.program
+	}, opts.workspaceOptions),
+	catch: (cause) => new AutomationError({
+		stage: "createOrSelectStack",
+		cause
+	})
 });
-var setStackConfig = (stack, config) => !config || Object.keys(config).length === 0 ? Effect.void : Effect.tryPromise({
-  try: () => stack.setAllConfig(config),
-  catch: (cause) => new AutomationError({ stage: "setConfig", cause })
+/** Apply the whole config map in one `setAllConfig` call - a single CLI
+* round-trip, where per-key `setConfig` costs one `pulumi config set`
+* invocation each. */
+const setStackConfig = (stack, config) => !config || Object.keys(config).length === 0 ? Effect.void : Effect.tryPromise({
+	try: () => stack.setAllConfig(config),
+	catch: (cause) => new AutomationError({
+		stage: "setConfig",
+		cause
+	})
 });
-var previewStack = (stack, opts) => Effect.tryPromise({
-  try: () => stack.preview(opts),
-  catch: (cause) => new AutomationError({ stage: "preview", cause })
+/** Compute the plan without applying it.
+*
+* A preview is a full engine run against the provider, not a cheap check - see
+* {@link DeployOptions.preview} before pairing one with an `up`. */
+const previewStack = (stack, opts) => Effect.tryPromise({
+	try: () => stack.preview(opts),
+	catch: (cause) => new AutomationError({
+		stage: "preview",
+		cause
+	})
 });
-var upStack = (stack, opts) => Effect.tryPromise({
-  try: () => stack.up(opts),
-  catch: (cause) => new AutomationError({ stage: "up", cause })
+/** Apply the program: create, update and delete resources to match it.
+*
+* The result carries the stack's outputs and a summary; pass `onOutput` to
+* watch progress while it runs. */
+const upStack = (stack, opts) => Effect.tryPromise({
+	try: () => stack.up(opts),
+	catch: (cause) => new AutomationError({
+		stage: "up",
+		cause
+	})
 });
-var refreshStack = (stack, opts) => Effect.tryPromise({
-  try: () => stack.refresh(opts),
-  catch: (cause) => new AutomationError({ stage: "refresh", cause })
+/** Refresh the stack's state from the actual cloud resources, without
+* changing them - what to run when state may have drifted (manual console
+* edits, a crashed update) before deciding what to do about it. */
+const refreshStack = (stack, opts) => Effect.tryPromise({
+	try: () => stack.refresh(opts),
+	catch: (cause) => new AutomationError({
+		stage: "refresh",
+		cause
+	})
 });
-var stackOutputs = (stack) => Effect.tryPromise({
-  try: () => stack.outputs(),
-  catch: (cause) => new AutomationError({ stage: "outputs", cause })
+/** Read the stack's current outputs without running an update. */
+const stackOutputs = (stack) => Effect.tryPromise({
+	try: () => stack.outputs(),
+	catch: (cause) => new AutomationError({
+		stage: "outputs",
+		cause
+	})
 });
-var destroyStack = (stack, opts) => Effect.tryPromise({
-  try: () => stack.destroy(opts),
-  catch: (cause) => new AutomationError({ stage: "destroy", cause })
+/** Destroy the stack's resources. The stack itself remains registered with
+* the backend - see `removeStack` / `teardownStack` to delete it too. */
+const destroyStack = (stack, opts) => Effect.tryPromise({
+	try: () => stack.destroy(opts),
+	catch: (cause) => new AutomationError({
+		stage: "destroy",
+		cause
+	})
 });
-var removeStack = (stack, opts) => Effect.tryPromise({
-  try: () => stack.workspace.removeStack(stack.name, opts),
-  catch: (cause) => new AutomationError({ stage: "removeStack", cause })
+/** Delete the stack and its configuration and history from the backend.
+*
+* This does not destroy resources - run `destroyStack` first, or use
+* `teardownStack`. Pulumi refuses to remove a stack that still has resources
+* unless `RemoveOptions.force` is set, and forcing it orphans them: they keep
+* existing and billing with nothing tracking them. */
+const removeStack = (stack, opts) => Effect.tryPromise({
+	try: () => stack.workspace.removeStack(stack.name, opts),
+	catch: (cause) => new AutomationError({
+		stage: "removeStack",
+		cause
+	})
 });
-var teardownStack = (stack, opts) => Effect.gen(function* () {
-  const result = yield* destroyStack(stack, opts?.destroy);
-  yield* removeStack(stack, opts?.remove);
-  return result;
+/** Full teardown: destroy the resources, then delete the stack.
+*
+* `destroyStack` alone leaves an empty stack behind, so anything creating
+* stacks per-run (ephemeral environments, tests naming stacks by timestamp)
+* accumulates them in the backend. */
+const teardownStack = (stack, opts) => Effect.gen(function* () {
+	const result = yield* destroyStack(stack, opts?.destroy);
+	yield* removeStack(stack, opts?.remove);
+	return result;
 });
-var deploy = (opts) => Effect.gen(function* () {
-  const stack = yield* createOrSelectStack(opts);
-  yield* setStackConfig(stack, opts.config);
-  const preview = opts.preview ? yield* previewStack(
-    stack,
-    typeof opts.preview === "boolean" ? void 0 : opts.preview
-  ) : void 0;
-  const result = yield* upStack(stack, opts.up);
-  return { stack, result, preview };
+/**
+* Select or create the stack, apply config, optionally preview, then up.
+*
+* The common path, assembled from the primitives above. Anything more
+* involved - refreshing first, inspecting the plan before deciding, retrying a
+* stage - should compose those directly rather than grow options here.
+*
+* @param opts - Which stack, and what to do with it.
+* @returns The stack handle alongside the results, so callers can tear down
+* afterwards without re-selecting.
+*
+* @example Deploy, use the outputs, then always tear down
+* ```ts
+* Effect.scoped(
+*   Effect.gen(function* () {
+*     const { result } = yield* Effect.acquireRelease(
+*       deploy({ stackName, projectName, program, up: { onOutput } }),
+*       ({ stack }) => teardownStack(stack).pipe(Effect.ignore)
+*     );
+*     return result.outputs.bucketId?.value;
+*   })
+* );
+* ```
+*/
+const deploy = (opts) => Effect.gen(function* () {
+	const stack = yield* createOrSelectStack(opts);
+	yield* setStackConfig(stack, opts.config);
+	const preview = opts.preview ? yield* previewStack(stack, typeof opts.preview === "boolean" ? void 0 : opts.preview) : void 0;
+	return {
+		stack,
+		result: yield* upStack(stack, opts.up),
+		preview
+	};
 });
-
+//#endregion
 export { AutomationError, PulumiError, createOrSelectStack, deploy, destroyStack, effectify, fromOutput, fromOutputs, previewStack, refreshStack, removeStack, setStackConfig, stackOutputs, teardownStack, upStack };
-//# sourceMappingURL=index.js.map
+
 //# sourceMappingURL=index.js.map