pulumi-sandbox 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * pulumi-sandbox — local development sandboxes as code.
+ *
+ * Write a plain Pulumi inline program describing the infrastructure your
+ * application needs on a developer machine; this library supplies everything
+ * around it: a self-contained local backend, per-developer stack isolation,
+ * a complete lifecycle command line, recovery from half-dead environments,
+ * and the helpers that turn resolved outputs into environment files.
+ */
+export { sandbox, createSandbox, Sandbox, DEFAULT_PASSPHRASE } from "./sandbox.js";
+export type { SandboxOptions, SandboxProgram, SandboxOutputs, SandboxContext, SandboxCommand, SandboxCommandContext, } from "./sandbox.js";
+export { LIFECYCLE_ACTIONS, ACTION_DESCRIPTIONS, isLifecycleAction } from "./actions.js";
+export type { LifecycleAction } from "./actions.js";
+export { fileBackendUrl, resolveDirectories, ensureDirectories } from "./backend.js";
+export type { SandboxDirectories } from "./backend.js";
+export { resolveDevId, parseEnvFile, readEnvFile, booleanFlag, DEV_ID_VARIABLE, DEFAULT_DEV_ID, } from "./identity.js";
+export type { DevIdOptions } from "./identity.js";
+export { EnvironmentFile } from "./environment-file.js";
+export type { EnvironmentValue, EnvironmentValues } from "./environment-file.js";
+export { deepResolve } from "./outputs.js";
+export type { DeepResolved } from "./outputs.js";
+export { waitForHttp, readyWhenHttp } from "./readiness.js";
+export type { HttpProbeOptions, ReadyWhenHttpOptions } from "./readiness.js";
+export { findGitRoot } from "./git.js";
+export { purgeProviderFromState, removeProviderFromDeployment } from "./state-surgery.js";
+export type { ProviderPurge } from "./state-surgery.js";
+export { SandboxError, SandboxConfigurationError, SandboxLockError, EnvironmentFileError } from "./errors.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;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACnF,YAAY,EACV,cAAc,EACd,cAAc,EACd,cAAc,EACd,cAAc,EACd,cAAc,EACd,qBAAqB,GACtB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACzF,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACrF,YAAY,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,WAAW,EACX,eAAe,EACf,cAAc,GACf,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAEjF,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC5D,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE7E,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEvC,OAAO,EAAE,sBAAsB,EAAE,4BAA4B,EAAE,MAAM,oBAAoB,CAAC;AAC1F,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,EAAE,YAAY,EAAE,yBAAyB,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * pulumi-sandbox — local development sandboxes as code.
+ *
+ * Write a plain Pulumi inline program describing the infrastructure your
+ * application needs on a developer machine; this library supplies everything
+ * around it: a self-contained local backend, per-developer stack isolation,
+ * a complete lifecycle command line, recovery from half-dead environments,
+ * and the helpers that turn resolved outputs into environment files.
+ */
+export { sandbox, createSandbox, Sandbox, DEFAULT_PASSPHRASE } from "./sandbox.js";
+export { LIFECYCLE_ACTIONS, ACTION_DESCRIPTIONS, isLifecycleAction } from "./actions.js";
+export { fileBackendUrl, resolveDirectories, ensureDirectories } from "./backend.js";
+export { resolveDevId, parseEnvFile, readEnvFile, booleanFlag, DEV_ID_VARIABLE, DEFAULT_DEV_ID, } from "./identity.js";
+export { EnvironmentFile } from "./environment-file.js";
+export { deepResolve } from "./outputs.js";
+export { waitForHttp, readyWhenHttp } from "./readiness.js";
+export { findGitRoot } from "./git.js";
+export { purgeProviderFromState, removeProviderFromDeployment } from "./state-surgery.js";
+export { SandboxError, SandboxConfigurationError, SandboxLockError, EnvironmentFileError } from "./errors.js";

package/dist/interactive.d.ts

@@ -0,0 +1,15 @@
+import { type LifecycleAction } from "./actions.js";
+/** What the interactive menu needs from the sandbox driving it. */
+export interface InteractiveHost {
+    run(action: LifecycleAction): Promise<void>;
+    /** Renders a failed action without ending the session. */
+    reportFailure(error: unknown): void;
+}
+/**
+ * A small menu over the lifecycle actions, used when the sandbox is invoked
+ * without an action. Failed actions are reported and the menu returns, so a
+ * developer can run `cancel` right after a lock error or retry a `create`
+ * without restarting the process.
+ */
+export declare function runInteractiveMenu(host: InteractiveHost): Promise<void>;
+//# sourceMappingURL=interactive.d.ts.map

package/dist/interactive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interactive.d.ts","sourceRoot":"","sources":["../src/interactive.ts"],"names":[],"mappings":"AACA,OAAO,EAA6D,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAG/G,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,0DAA0D;IAC1D,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CACrC;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAoC7E"}

package/dist/interactive.js

@@ -0,0 +1,45 @@
+import readline from "node:readline/promises";
+import { ACTION_DESCRIPTIONS, LIFECYCLE_ACTIONS, isLifecycleAction } from "./actions.js";
+import { bold, cyan, dim, warn } from "./terminal.js";
+/**
+ * A small menu over the lifecycle actions, used when the sandbox is invoked
+ * without an action. Failed actions are reported and the menu returns, so a
+ * developer can run `cancel` right after a lock error or retry a `create`
+ * without restarting the process.
+ */
+export async function runInteractiveMenu(host) {
+    const input = readline.createInterface({ input: process.stdin, output: process.stdout });
+    // End-of-input (Ctrl+D, a closed pipe) must end the menu, not leave the
+    // pending question unsettled forever.
+    const closed = new Promise((resolve) => {
+        input.once("close", () => resolve("exit"));
+    });
+    try {
+        while (true) {
+            process.stdout.write("\n");
+            LIFECYCLE_ACTIONS.forEach((action, index) => {
+                process.stdout.write(`  ${cyan(String(index + 1))}  ${bold(action.padEnd(8))} ${dim(ACTION_DESCRIPTIONS[action])}\n`);
+            });
+            process.stdout.write(`  ${cyan("0")}  ${bold("exit".padEnd(8))} ${dim("Leave the menu")}\n\n`);
+            const answer = (await Promise.race([input.question(`${cyan("›")} action: `), closed])).trim().toLowerCase();
+            if (answer === "0" || answer === "exit" || answer === "quit" || answer === "q") {
+                return;
+            }
+            const byNumber = /^[0-9]+$/.test(answer) ? LIFECYCLE_ACTIONS[Number(answer) - 1] : undefined;
+            const action = byNumber ?? (isLifecycleAction(answer) ? answer : undefined);
+            if (action === undefined) {
+                warn(`"${answer}" is not an action — pick a number or name from the list.`);
+                continue;
+            }
+            try {
+                await host.run(action);
+            }
+            catch (error) {
+                host.reportFailure(error);
+            }
+        }
+    }
+    finally {
+        input.close();
+    }
+}

package/dist/lifecycle.d.ts

@@ -0,0 +1,41 @@
+import { automation } from "@pulumi/pulumi";
+/** Everything the lifecycle operations need to act on a stack. */
+export interface StackHost {
+    stack: automation.Stack;
+    stackName: string;
+    /**
+     * Names of provider resources whose backing service runs in a container
+     * this sandbox manages — see {@link purgeProviderFromState} for why these
+     * need special treatment.
+     */
+    containerHostedProviders: readonly string[];
+}
+/**
+ * Creates or updates the stack with a single `up --refresh`: one operation
+ * reconciles state with reality (containers killed by hand drop out) and
+ * applies the program.
+ *
+ * There is deliberately no separate pre-refresh: refresh initializes every
+ * provider in state, so a container-hosted provider whose container is gone
+ * would abort the run before the update gets a chance to recreate it. If the
+ * combined operation still fails, the container-hosted providers are purged
+ * from state and the update retried once — after the purge, refresh only
+ * sees providers it can reach, and the program re-registers the purged
+ * resources against the freshly created container.
+ */
+export declare function createStack(host: StackHost): Promise<void>;
+/**
+ * Destroys the stack. Container-hosted providers are purged from state
+ * first, so the destroy plan never asks an unreachable service to delete
+ * resources its own container teardown wipes physically; `refresh: true`
+ * then reconciles whatever survives the purge against reality before
+ * deleting it.
+ */
+export declare function destroyStack(host: StackHost): Promise<void>;
+/** Previews what {@link createStack} would change, with a full diff. */
+export declare function previewStack(host: StackHost): Promise<void>;
+/** Releases a stuck state lock left behind by an interrupted operation. */
+export declare function cancelStack(host: StackHost): Promise<void>;
+/** Prints the stack outputs as a JSON object. */
+export declare function printOutputs(host: StackHost): Promise<void>;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAK5C,kEAAkE;AAClE,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,UAAU,CAAC,KAAK,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,wBAAwB,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7C;AASD;;;;;;;;;;;;GAYG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBhE;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAcjE;AAED,wEAAwE;AACxE,wBAAsB,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAQjE;AAED,2EAA2E;AAC3E,wBAAsB,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAGhE;AAED,iDAAiD;AACjD,wBAAsB,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAIjE"}

package/dist/lifecycle.js

@@ -0,0 +1,110 @@
+import { automation } from "@pulumi/pulumi";
+import { SandboxLockError } from "./errors.js";
+import { purgeProviderFromState } from "./state-surgery.js";
+import { colorMode, detail, step, warn } from "./terminal.js";
+function streamOptions() {
+    return {
+        onOutput: (data) => process.stdout.write(data),
+        color: colorMode(),
+    };
+}
+/**
+ * Creates or updates the stack with a single `up --refresh`: one operation
+ * reconciles state with reality (containers killed by hand drop out) and
+ * applies the program.
+ *
+ * There is deliberately no separate pre-refresh: refresh initializes every
+ * provider in state, so a container-hosted provider whose container is gone
+ * would abort the run before the update gets a chance to recreate it. If the
+ * combined operation still fails, the container-hosted providers are purged
+ * from state and the update retried once — after the purge, refresh only
+ * sees providers it can reach, and the program re-registers the purged
+ * resources against the freshly created container.
+ */
+export async function createStack(host) {
+    step("Refreshing and updating the stack");
+    try {
+        await host.stack.up({ ...streamOptions(), refresh: true });
+    }
+    catch (error) {
+        rethrowLockError(error, host.stackName);
+        if (host.containerHostedProviders.length === 0) {
+            throw error;
+        }
+        warn("The update failed; assuming a container-hosted service is gone, purging its state, and retrying once.");
+        try {
+            await purgeContainerHostedProviders(host);
+        }
+        catch (purgeError) {
+            rethrowLockError(purgeError, host.stackName);
+            throw purgeError;
+        }
+        try {
+            await host.stack.up({ ...streamOptions(), refresh: true });
+        }
+        catch (retryError) {
+            rethrowLockError(retryError, host.stackName);
+            throw retryError;
+        }
+    }
+}
+/**
+ * Destroys the stack. Container-hosted providers are purged from state
+ * first, so the destroy plan never asks an unreachable service to delete
+ * resources its own container teardown wipes physically; `refresh: true`
+ * then reconciles whatever survives the purge against reality before
+ * deleting it.
+ */
+export async function destroyStack(host) {
+    try {
+        await purgeContainerHostedProviders(host);
+    }
+    catch (error) {
+        rethrowLockError(error, host.stackName);
+        throw error;
+    }
+    step("Refreshing and destroying the stack");
+    try {
+        await host.stack.destroy({ ...streamOptions(), refresh: true });
+    }
+    catch (error) {
+        rethrowLockError(error, host.stackName);
+        throw error;
+    }
+}
+/** Previews what {@link createStack} would change, with a full diff. */
+export async function previewStack(host) {
+    step("Previewing changes");
+    try {
+        await host.stack.preview({ ...streamOptions(), diff: true });
+    }
+    catch (error) {
+        rethrowLockError(error, host.stackName);
+        throw error;
+    }
+}
+/** Releases a stuck state lock left behind by an interrupted operation. */
+export async function cancelStack(host) {
+    step("Releasing the state lock");
+    await host.stack.cancel();
+}
+/** Prints the stack outputs as a JSON object. */
+export async function printOutputs(host) {
+    const outputs = await host.stack.outputs();
+    const plain = Object.fromEntries(Object.entries(outputs).map(([key, output]) => [key, output.value]));
+    process.stdout.write(`${JSON.stringify(plain, undefined, 2)}\n`);
+}
+async function purgeContainerHostedProviders(host) {
+    for (const providerName of host.containerHostedProviders) {
+        const purge = await purgeProviderFromState(host.stack, providerName);
+        const removed = purge.removedResources + purge.removedPendingOperations;
+        if (removed > 0) {
+            detail(`Purged ${removed} state entries tied to provider "${providerName}".`);
+        }
+    }
+}
+function rethrowLockError(error, stackName) {
+    if (error instanceof automation.ConcurrentUpdateError) {
+        throw new SandboxLockError(stackName);
+    }
+}

package/dist/outputs.d.ts

@@ -0,0 +1,30 @@
+import * as pulumi from "@pulumi/pulumi";
+/** The shape of `T` after every nested Pulumi output and promise has resolved. */
+export type DeepResolved<T> = T extends pulumi.Output<infer U> ? DeepResolved<U> : T extends Promise<infer U> ? DeepResolved<U> : T extends ReadonlyArray<infer E> ? DeepResolved<E>[] : T extends object ? {
+    [K in keyof T]: DeepResolved<T[K]>;
+} : T;
+/**
+ * Resolves every Pulumi output nested anywhere inside a plain value — arrays,
+ * objects, and promises included — into a single output of the fully
+ * concrete shape.
+ *
+ * This is the bridge between resource graphs and host-side side effects:
+ * collect generated credentials, ports, and endpoints into one structure,
+ * deep-resolve it, and render environment files or developer artifacts in a
+ * single `apply`:
+ *
+ * ```typescript
+ * deepResolve({ clientSecret: client.clientSecret, port: 5432 }).apply((resolved) => {
+ *   env.add(resolved);
+ *   env.write("application/.env.local");
+ * });
+ * ```
+ *
+ * The value must be plain data: primitives, arrays, plain objects, promises,
+ * and outputs, nested arbitrarily. Class instances and circular references
+ * are rejected with an error naming the offending path — Pulumi's output
+ * machinery would otherwise silently flatten an instance into a plain bag
+ * of properties.
+ */
+export declare function deepResolve<T>(value: T): pulumi.Output<DeepResolved<T>>;
+//# sourceMappingURL=outputs.d.ts.map

package/dist/outputs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outputs.d.ts","sourceRoot":"","sources":["../src/outputs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,gBAAgB,CAAC;AAGzC,kFAAkF;AAClF,MAAM,MAAM,YAAY,CAAC,CAAC,IACxB,CAAC,SAAS,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAC5B,YAAY,CAAC,CAAC,CAAC,GACf,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,CAAC,GACxB,YAAY,CAAC,CAAC,CAAC,GACf,CAAC,SAAS,aAAa,CAAC,MAAM,CAAC,CAAC,GAC9B,YAAY,CAAC,CAAC,CAAC,EAAE,GACjB,CAAC,SAAS,MAAM,GACd;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GACtC,CAAC,CAAC;AAEd;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAEvE"}

package/dist/outputs.js

@@ -0,0 +1,65 @@
+import * as pulumi from "@pulumi/pulumi";
+import { SandboxError } from "./errors.js";
+/**
+ * Resolves every Pulumi output nested anywhere inside a plain value — arrays,
+ * objects, and promises included — into a single output of the fully
+ * concrete shape.
+ *
+ * This is the bridge between resource graphs and host-side side effects:
+ * collect generated credentials, ports, and endpoints into one structure,
+ * deep-resolve it, and render environment files or developer artifacts in a
+ * single `apply`:
+ *
+ * ```typescript
+ * deepResolve({ clientSecret: client.clientSecret, port: 5432 }).apply((resolved) => {
+ *   env.add(resolved);
+ *   env.write("application/.env.local");
+ * });
+ * ```
+ *
+ * The value must be plain data: primitives, arrays, plain objects, promises,
+ * and outputs, nested arbitrarily. Class instances and circular references
+ * are rejected with an error naming the offending path — Pulumi's output
+ * machinery would otherwise silently flatten an instance into a plain bag
+ * of properties.
+ */
+export function deepResolve(value) {
+    return pulumi.output(resolveUnknown(value, "value", new WeakSet()));
+}
+function resolveUnknown(value, path, visiting) {
+    if (pulumi.Output.isInstance(value) || value instanceof Promise) {
+        return pulumi.output(value).apply((inner) => resolveUnknown(inner, path, visiting));
+    }
+    if (Array.isArray(value)) {
+        enterValue(value, path, visiting);
+        const resolved = pulumi.all(value.map((entry, index) => resolveUnknown(entry, `${path}[${index}]`, visiting)));
+        visiting.delete(value);
+        return resolved;
+    }
+    if (typeof value === "object" && value !== null) {
+        if (!isPlainObject(value)) {
+            throw new SandboxError(`deepResolve only accepts plain data, but ${path} is an instance of ${value.constructor?.name ?? "an unknown class"}.`);
+        }
+        enterValue(value, path, visiting);
+        const resolved = {};
+        for (const [key, entry] of Object.entries(value)) {
+            resolved[key] = resolveUnknown(entry, `${path}.${key}`, visiting);
+        }
+        visiting.delete(value);
+        return pulumi.all(resolved);
+    }
+    if (typeof value === "function") {
+        throw new SandboxError(`deepResolve only accepts plain data, but ${path} is a function.`);
+    }
+    return value;
+}
+function enterValue(value, path, visiting) {
+    if (visiting.has(value)) {
+        throw new SandboxError(`deepResolve found a circular reference at ${path}.`);
+    }
+    visiting.add(value);
+}
+function isPlainObject(value) {
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}

package/dist/readiness.d.ts

@@ -0,0 +1,57 @@
+import * as pulumi from "@pulumi/pulumi";
+export interface HttpProbeOptions {
+    /** Give up after this long. Default: 180 seconds. */
+    timeoutMs?: number | undefined;
+    /** Pause between attempts. Default: 2 seconds. */
+    intervalMs?: number | undefined;
+    /**
+     * What counts as ready. `"any-response"` (the default) accepts every HTTP
+     * status — including errors like 403 — because a status line proves the
+     * server is up, which is all a boot probe needs. `"ok"` additionally
+     * requires a 2xx status.
+     */
+    expect?: "any-response" | "ok" | undefined;
+}
+/**
+ * Polls an HTTP endpoint until it responds, the configured expectation is
+ * met, or the timeout elapses. Returns whether the endpoint became ready.
+ *
+ * Deliberately never throws: on timeout it logs a warning and returns
+ * `false`, so lifecycle flows that race a disappearing container (destroy,
+ * refresh) degrade to a warning instead of wedging the run. The component
+ * that actually depends on the endpoint will surface the real connection
+ * error at its own layer.
+ */
+export declare function waitForHttp(url: string, options?: HttpProbeOptions): Promise<boolean>;
+export interface ReadyWhenHttpOptions extends HttpProbeOptions {
+    /**
+     * Runs once the probe succeeds — the place for imperative post-boot
+     * configuration (a `docker exec` against the freshly started container,
+     * for example). Skipped when the probe times out. Note that the readiness
+     * chain re-executes on every update that resolves the gate, so this
+     * callback must be idempotent.
+     */
+    onReady?: (() => void | Promise<void>) | undefined;
+}
+/**
+ * An output that resolves to `url` once the endpoint behind it responds,
+ * gated on another resource being scheduled first — typically the container
+ * that serves the endpoint:
+ *
+ * ```typescript
+ * const adminUrl = readyWhenHttp(keycloakContainer.id, "http://localhost:20080");
+ * new keycloak.Provider("keycloak", { url: adminUrl, ... });
+ * ```
+ *
+ * Anything consuming the returned output (a provider, a dependent resource)
+ * is therefore held back until the service has actually booted. The polling
+ * happens in a plain `apply` closure — nothing is serialized into Pulumi
+ * state — and the output always resolves to `url`, even on timeout, to keep
+ * the graph healthy during destroy and refresh.
+ *
+ * Dry runs are exempt: during a preview the output resolves immediately,
+ * without probing and without `onReady` — a preview must neither stall on a
+ * stopped container nor execute side effects.
+ */
+export declare function readyWhenHttp(gate: pulumi.Input<unknown>, url: string, options?: ReadyWhenHttpOptions): pulumi.Output<string>;
+//# sourceMappingURL=readiness.d.ts.map

package/dist/readiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.d.ts","sourceRoot":"","sources":["../src/readiness.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,gBAAgB,CAAC;AAGzC,MAAM,WAAW,gBAAgB;IAC/B,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,kDAAkD;IAClD,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,CAAC;CAC5C;AAKD;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,OAAO,CAAC,CAoB/F;AAED,MAAM,WAAW,oBAAqB,SAAQ,gBAAgB;IAC5D;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,CAAC;CACpD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,EAC3B,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,oBAAyB,GACjC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAWvB"}

package/dist/readiness.js

@@ -0,0 +1,66 @@
+import * as pulumi from "@pulumi/pulumi";
+import { warn } from "./terminal.js";
+const DEFAULT_TIMEOUT_MS = 180_000;
+const DEFAULT_INTERVAL_MS = 2_000;
+/**
+ * Polls an HTTP endpoint until it responds, the configured expectation is
+ * met, or the timeout elapses. Returns whether the endpoint became ready.
+ *
+ * Deliberately never throws: on timeout it logs a warning and returns
+ * `false`, so lifecycle flows that race a disappearing container (destroy,
+ * refresh) degrade to a warning instead of wedging the run. The component
+ * that actually depends on the endpoint will surface the real connection
+ * error at its own layer.
+ */
+export async function waitForHttp(url, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
+    const expect = options.expect ?? "any-response";
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            const response = await fetch(url, { signal: AbortSignal.timeout(Math.min(intervalMs * 5, 10_000)) });
+            if (expect === "any-response" || response.ok) {
+                return true;
+            }
+        }
+        catch {
+            // Connection refused or timed out — the server is still booting.
+        }
+        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+    warn(`${url} did not respond within ${Math.round(timeoutMs / 1000)}s; continuing anyway.`);
+    return false;
+}
+/**
+ * An output that resolves to `url` once the endpoint behind it responds,
+ * gated on another resource being scheduled first — typically the container
+ * that serves the endpoint:
+ *
+ * ```typescript
+ * const adminUrl = readyWhenHttp(keycloakContainer.id, "http://localhost:20080");
+ * new keycloak.Provider("keycloak", { url: adminUrl, ... });
+ * ```
+ *
+ * Anything consuming the returned output (a provider, a dependent resource)
+ * is therefore held back until the service has actually booted. The polling
+ * happens in a plain `apply` closure — nothing is serialized into Pulumi
+ * state — and the output always resolves to `url`, even on timeout, to keep
+ * the graph healthy during destroy and refresh.
+ *
+ * Dry runs are exempt: during a preview the output resolves immediately,
+ * without probing and without `onReady` — a preview must neither stall on a
+ * stopped container nor execute side effects.
+ */
+export function readyWhenHttp(gate, url, options = {}) {
+    return pulumi.output(gate).apply(async () => {
+        if (pulumi.runtime.isDryRun()) {
+            return url;
+        }
+        const ready = await waitForHttp(url, options);
+        if (ready && options.onReady) {
+            await options.onReady();
+        }
+        return url;
+    });
+}