alchemy 0.61.0 → 0.62.0

package/lib/util/idempotent-spawn.js

@@ -1,17 +1,17 @@
-import find from "find-process";
 import { spawn } from "node:child_process";
 import fs from "node:fs";
 import fsp from "node:fs/promises";
 import path from "node:path";
+import { AsyncMutex } from "./mutex.js";
 /**
  * Idempotently ensure a long-lived child is running with stdout/stderr -> files,
  * and mirror those logs to THIS process's console with persisted offsets.
  *
  * Use: await ensureLoggedChildAndMirror({ cmd: "vite dev" })
  */
-export async function idempotentSpawn({ cmd, cwd, stateFile = "state.json", overlapBytes = 0, resume = false, log = "log.txt", processName, extract, isSameProcess, quiet = false, }) {
+export async function idempotentSpawn({ cmd, cwd, env, stateFile = "state.json", overlapBytes = 0, resume = false, log = "log.txt", processName, extract, isSameProcess, quiet = false, }) {
     if (!processName && !isSameProcess) {
-        throw new Error("Either processName or isSameProcess must be provided to resume a process");
+        processName = cmd.split(" ")[0];
     }
     const outPath = log;
     await Promise.all([
@@ -20,10 +20,18 @@ export async function idempotentSpawn({ cmd, cwd, stateFile = "state.json", over
     ]);
     const { promise: extracted, resolve: resolveExtracted } = Promise.withResolvers();
     if (!extract) {
-        console.warn("No extract function provided, will not return a value. This is probably a bug.");
         resolveExtracted(undefined);
     }
-    // ------------------------ helpers ------------------------
+    await ensureChildRunning();
+    const write = quiet
+        ? () => false
+        : (buf) => process.stdout.write(buf);
+    // Start followers (stdout/stderr) and mirror to this process
+    await followFilePersisted(outPath, {
+        stateKey: `${path.resolve(outPath)}::stdout`,
+        write,
+    });
+    return extracted;
     function isPidAlive(pid) {
         if (!pid || Number.isNaN(pid))
             return false;
@@ -56,7 +64,7 @@ export async function idempotentSpawn({ cmd, cwd, stateFile = "state.json", over
             shell: true,
             cwd,
             stdio: ["ignore", out.fd, out.fd], // stdout/stderr -> files (OS-level)
-            env: process.env,
+            env,
             detached: false,
         });
         // Child now owns dup'd fds; close our handles.
@@ -76,12 +84,15 @@ export async function idempotentSpawn({ cmd, cwd, stateFile = "state.json", over
             if (await isSameProcess?.(pid))
                 return pid;
             if (processName) {
+                const { default: find } = await import("find-process");
                 const processes = await find("pid", pid);
                 if (processes.length > 1) {
                     console.warn(`Found multiple processes with PID ${pid}, using the first one`);
                 }
                 if (processes.length > 0) {
-                    return processes[0].name.startsWith(processName);
+                    if (processes[0].name.startsWith(processName)) {
+                        return pid;
+                    }
                 }
             }
         }
@@ -93,7 +104,9 @@ export async function idempotentSpawn({ cmd, cwd, stateFile = "state.json", over
         return (await spawnLoggedChild()).pid;
     }
     // Follow a file from persisted offset and mirror to a sink (stdout/stderr)
-    async function followFilePersisted(logPath, { write = (buf) => process.stdout.write(buf), chunkSize = 64 * 1024, tickMs = 100, }) {
+    async function followFilePersisted(logPath, { write, chunkSize = 64 * 1024,
+    // tickMs = 100,
+     }) {
         logPath = path.resolve(logPath);
         let state = (await readJson(stateFile)) ?? {};
         let fh = await fsp.open(logPath, "r");
@@ -108,62 +121,21 @@ export async function idempotentSpawn({ cmd, cwd, stateFile = "state.json", over
             ? Math.max(0, Math.min(st.size, state.offset - overlapBytes))
             : st.size;
         let closed = false;
-        async function persist() {
-            try {
-                const cur = await fh.stat();
-                state = {
-                    ...state,
-                    offset,
-                    ino: Number(cur.ino ?? ino),
-                    dev: Number(cur.dev ?? dev),
-                    size: cur.size,
-                    mtimeMs: cur.mtimeMs,
-                };
-                await writeJsonAtomic(stateFile, state);
-            }
-            catch {
-                // If the file vanished mid-rotation, we'll catch up on the next event.
-            }
-        }
-        async function drain() {
-            while (true) {
-                const cur = await fh.stat().catch(() => null);
-                if (!cur)
-                    break;
-                if (cur.size < offset)
-                    offset = 0; // truncated
-                if (offset > 0 && extract) {
-                    // read from start to offset
-                    const fullBuffer = Buffer.allocUnsafe(offset);
-                    await fh.read({
-                        position: 0,
-                        buffer: fullBuffer,
-                        length: offset,
-                    });
-                    const content = fullBuffer.toString("utf8");
-                    const lines = content.split("\n");
-                    for (const line of lines) {
-                        const extracted = extract(line);
-                        if (extracted) {
-                            resolveExtracted(extracted);
-                            break;
-                        }
-                    }
-                }
-                const toRead = Math.min(chunkSize, cur.size - offset);
-                if (toRead <= 0)
-                    break;
-                const { bytesRead, buffer } = await fh.read({
-                    position: offset,
-                    buffer: Buffer.allocUnsafe(toRead),
-                    length: toRead,
-                });
-                if (!bytesRead)
-                    break;
-                offset += bytesRead;
-                write(buffer.subarray(0, bytesRead));
-            }
-            await persist();
+        const drainMutex = new AsyncMutex();
+        // we read the log file and stream in chunks, not lines
+        // so we need to keep track of the remainder of the last line
+        let remainder;
+        // if we are resuming, then re-parse the log lines to extract the value
+        if (offset > 0) {
+            // read from start to offset
+            const fullBuffer = Buffer.allocUnsafe(offset);
+            await fh.read({
+                position: 0,
+                buffer: fullBuffer,
+                length: offset,
+            });
+            const content = fullBuffer.toString("utf8");
+            parse(content);
         }
         await drain();
         const watcher = fs.watch(logPath, async () => {
@@ -199,20 +171,67 @@ export async function idempotentSpawn({ cmd, cwd, stateFile = "state.json", over
             await fh.close().catch(() => { });
             await persist();
         };
+        async function persist() {
+            try {
+                const cur = await fh.stat();
+                state = {
+                    ...state,
+                    offset,
+                    ino: Number(cur.ino ?? ino),
+                    dev: Number(cur.dev ?? dev),
+                    size: cur.size,
+                    mtimeMs: cur.mtimeMs,
+                };
+                await writeJsonAtomic(stateFile, state);
+            }
+            catch {
+                // If the file vanished mid-rotation, we'll catch up on the next event.
+            }
+        }
+        function parse(content) {
+            const lines = content.split("\n");
+            if (extract) {
+                if (lines.length > 0) {
+                    remainder = lines[lines.length - 1];
+                }
+                // parse all lines except the last one (which may be a partial line)
+                for (const line of lines.slice(0, -1)) {
+                    const extracted = extract(line);
+                    if (extracted) {
+                        resolveExtracted(extracted);
+                        break;
+                    }
+                }
+            }
+        }
+        function drain() {
+            return drainMutex.lock(async () => {
+                while (true) {
+                    const cur = await fh.stat().catch(() => null);
+                    if (!cur)
+                        break;
+                    if (cur.size < offset)
+                        offset = 0; // truncated
+                    const toRead = Math.min(chunkSize, cur.size - offset);
+                    if (toRead <= 0)
+                        break;
+                    const { bytesRead, buffer } = await fh.read({
+                        position: offset,
+                        buffer: Buffer.allocUnsafe(toRead),
+                        length: toRead,
+                    });
+                    if (!bytesRead)
+                        break;
+                    const chunk = buffer.subarray(0, bytesRead);
+                    // write the newly read content to the stream
+                    write(chunk);
+                    // parse the previous remainder and the new chunk
+                    parse(`${remainder || ""}${chunk.toString("utf8")}`);
+                    offset += bytesRead;
+                }
+                await persist();
+            });
+        }
     }
-    // ------------------------ main flow ------------------------
-    await ensureChildRunning();
-    if (!quiet) {
-        const write = quiet
-            ? () => false
-            : (buf) => process.stdout.write(buf);
-        // Start followers (stdout/stderr) and mirror to this process
-        await followFilePersisted(outPath, {
-            stateKey: `${path.resolve(outPath)}::stdout`,
-            write,
-        });
-    }
-    // Return a stopper for this instance's mirroring (child keeps running)
-    return extracted;
 }
 //# sourceMappingURL=idempotent-spawn.js.map

package/lib/util/idempotent-spawn.js.map

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

package/lib/util/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./safe-fetch.ts";
+//# sourceMappingURL=index.d.ts.map

package/lib/util/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/util/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC"}

package/lib/util/index.js

@@ -0,0 +1,2 @@
+export * from "./safe-fetch.js";
+//# sourceMappingURL=index.js.map

package/lib/util/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/util/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC"}

package/lib/util/safe-fetch.d.ts

@@ -1,2 +1,26 @@
 export declare function safeFetch(url: string | URL | Request, options?: RequestInit, retries?: number): Promise<Response>;
+/**
+ * Fetch with exponential backoff retry logic for 404 responses, expecting 200 OK.
+ * This is a convenience wrapper around fetchAndExpectStatus with expectedStatus=200.
+ *
+ * @param input URL or Request object
+ * @param init RequestInit options
+ * @param maxAttempts Maximum number of retry attempts (default: 10)
+ * @param maxWaitTime Maximum total wait time in milliseconds (default: 30000)
+ * @returns The successful Response
+ */
+export declare function fetchAndExpectOK(input: string | URL | Request, init?: RequestInit, maxAttempts?: number, maxWaitTime?: number): Promise<Response>;
+/**
+ * Fetch and expect a specific status code with retry logic.
+ * Cloudflare's control plane is eventually consistent, so resources may
+ * return 404 immediately after creation before becoming available.
+ *
+ * @param input URL or Request object
+ * @param init RequestInit options
+ * @param expectedStatus Expected HTTP status code (default: 200)
+ * @param maxAttempts Maximum number of retry attempts (default: 10)
+ * @param maxWaitTime Maximum total wait time in milliseconds (default: 30000)
+ * @returns The successful Response
+ */
+export declare function fetchAndExpectStatus(input: string | URL | Request, init?: RequestInit, expectedStatus?: number, maxAttempts?: number, maxWaitTime?: number): Promise<Response>;
 //# sourceMappingURL=safe-fetch.d.ts.map

package/lib/util/safe-fetch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"safe-fetch.d.ts","sourceRoot":"","sources":["../../src/util/safe-fetch.ts"],"names":[],"mappings":"AAGA,wBAAsB,SAAS,CAC7B,GAAG,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,EAC3B,OAAO,GAAE,WAAgB,EACzB,OAAO,SAAK,qBAyBb"}
+{"version":3,"file":"safe-fetch.d.ts","sourceRoot":"","sources":["../../src/util/safe-fetch.ts"],"names":[],"mappings":"AAGA,wBAAsB,SAAS,CAC7B,GAAG,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,EAC3B,OAAO,GAAE,WAAgB,EACzB,OAAO,SAAK,qBAyBb;AAyCD;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,EAC7B,IAAI,CAAC,EAAE,WAAW,EAClB,WAAW,SAAK,EAChB,WAAW,SAAQ,GAClB,OAAO,CAAC,QAAQ,CAAC,CAEnB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,EAC7B,IAAI,CAAC,EAAE,WAAW,EAClB,cAAc,SAAM,EACpB,WAAW,SAAK,EAChB,WAAW,SAAQ,GAClB,OAAO,CAAC,QAAQ,CAAC,CA2EnB"}

package/lib/util/safe-fetch.js

@@ -52,4 +52,76 @@ async function dispatcher() {
     }
     return agent.value;
 }
+/**
+ * Fetch with exponential backoff retry logic for 404 responses, expecting 200 OK.
+ * This is a convenience wrapper around fetchAndExpectStatus with expectedStatus=200.
+ *
+ * @param input URL or Request object
+ * @param init RequestInit options
+ * @param maxAttempts Maximum number of retry attempts (default: 10)
+ * @param maxWaitTime Maximum total wait time in milliseconds (default: 30000)
+ * @returns The successful Response
+ */
+export async function fetchAndExpectOK(input, init, maxAttempts = 10, maxWaitTime = 30000) {
+    return fetchAndExpectStatus(input, init, 200, maxAttempts, maxWaitTime);
+}
+/**
+ * Fetch and expect a specific status code with retry logic.
+ * Cloudflare's control plane is eventually consistent, so resources may
+ * return 404 immediately after creation before becoming available.
+ *
+ * @param input URL or Request object
+ * @param init RequestInit options
+ * @param expectedStatus Expected HTTP status code (default: 200)
+ * @param maxAttempts Maximum number of retry attempts (default: 10)
+ * @param maxWaitTime Maximum total wait time in milliseconds (default: 30000)
+ * @returns The successful Response
+ */
+export async function fetchAndExpectStatus(input, init, expectedStatus = 200, maxAttempts = 20, maxWaitTime = 30000) {
+    let attempt = 0;
+    let lastError;
+    while (attempt < maxAttempts) {
+        try {
+            const response = await safeFetch(input, init);
+            // If we get the expected status, return it
+            if (response.status === expectedStatus) {
+                return response;
+            }
+            // If we get a 500, 404 when expecting something else, retry with backoff
+            if (response.status >= 500 ||
+                (response.status === 404 && expectedStatus !== 404)) {
+                attempt++;
+                if (attempt >= maxAttempts) {
+                    throw new Error(`Expected status ${expectedStatus} but got 404 after ${maxAttempts} attempts. This may indicate eventual consistency issues.`);
+                }
+                const backoffTime = Math.min(attempt * 1500, maxWaitTime / maxAttempts);
+                console.log(`Expected status ${expectedStatus} but got 404, retrying in ${backoffTime}ms (attempt ${attempt}/${maxAttempts})...`);
+                await new Promise((resolve) => setTimeout(resolve, backoffTime));
+                continue;
+            }
+            // For other status codes, throw immediately
+            throw new Error(`Expected status ${expectedStatus} but got ${response.status}: ${response.statusText}`);
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                lastError = error;
+                // If it's not an HTTP error, retry with backoff
+                if (!error.message.startsWith("Expected status") &&
+                    !error.message.startsWith("HTTP ")) {
+                    attempt++;
+                    if (attempt >= maxAttempts) {
+                        break;
+                    }
+                    const backoffTime = Math.min(attempt * 1500, maxWaitTime / maxAttempts);
+                    console.log(`Network error, retrying in ${backoffTime}ms (attempt ${attempt}/${maxAttempts}): ${error.message}`);
+                    await new Promise((resolve) => setTimeout(resolve, backoffTime));
+                    continue;
+                }
+            }
+            // For status code mismatches, throw immediately
+            throw error;
+        }
+    }
+    throw lastError || new Error(`Failed after ${maxAttempts} attempts`);
+}
 //# sourceMappingURL=safe-fetch.js.map

package/lib/util/safe-fetch.js.map

@@ -1 +1 @@
-{"version":3,"file":"safe-fetch.js","sourceRoot":"","sources":["../../src/util/safe-fetch.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,GAA2B,EAC3B,UAAuB,EAAE,EACzB,OAAO,GAAG,EAAE;IAEZ,IAAI,SAAc,CAAC;IACnB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC;QACpD,IAAI,CAAC;YACH,OAAO,MAAM,KAAK,CAAC,GAAG,EAAE;gBACtB,GAAG,OAAO;gBACV,oEAAoE;gBACpE,UAAU,EAAE,MAAM,UAAU,EAAE;aAChB,CAAC,CAAC;QACpB,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAClB,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YACxB,SAAS,GAAG,GAAG,CAAC;YAChB,MAAM,WAAW,GACf,uBAAuB,CAAC,GAAG,CAAC,IAAI,uBAAuB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YAErE,IAAI,CAAC,WAAW,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;gBACxC,MAAM,GAAG,CAAC;YACZ,CAAC;YAED,MAAM,CAAC,IAAI,CAAC,SAAS,OAAO,IAAI,OAAO,QAAQ,GAAG,KAAK,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;YACnE,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,sBAAsB;QAChF,CAAC;IACH,CAAC;IACD,MAAM,SAAS,CAAC;AAClB,CAAC;AAED,SAAS,uBAAuB,CAAC,GAAQ;IACvC,OAAO,CACL,GAAG,EAAE,IAAI,KAAK,gBAAgB;QAC9B,GAAG,EAAE,IAAI,KAAK,YAAY;QAC1B,GAAG,EAAE,IAAI,KAAK,yBAAyB;QACvC,GAAG,EAAE,IAAI,KAAK,OAAO;QACrB,GAAG,EAAE,IAAI,KAAK,YAAY,CAC3B,CAAC;AACJ,CAAC;AAED,IAAI,KAIS,CAAC;AAEd,KAAK,UAAU,UAAU;IACvB,IAAI,KAAK,EAAE,CAAC;QACV,OAAO,KAAK,CAAC,KAAK,CAAC;IACrB,CAAC;IACD,IAAI,CAAC;QACH,uCAAuC;QACvC,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC;QAEzC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,gEAAgE;YAChE,KAAK,GAAG;gBACN,KAAK,EAAE,IAAI,KAAK,CAAC;oBACf,UAAU,EAAE,CAAC,EAAE,gDAAgD;oBAC/D,2DAA2D;iBAC5D,CAAC;aACH,CAAC;QACJ,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,KAAK,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IAC/B,CAAC;IACD,OAAO,KAAK,CAAC,KAAK,CAAC;AACrB,CAAC"}
+{"version":3,"file":"safe-fetch.js","sourceRoot":"","sources":["../../src/util/safe-fetch.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alchemy",
-  "version": "0.61.0",
+  "version": "0.62.0",
   "license": "Apache-2.0",
   "author": "Sam Goodwin <sam@alchemy.run>",
   "homepage": "https://alchemy.run",
@@ -149,6 +149,10 @@
       "bun": "./src/state/index.ts",
       "import": "./lib/state/index.js"
     },
+    "./util": {
+      "bun": "./src/util/index.ts",
+      "import": "./lib/util/index.js"
+    },
     "./web/astro": {
       "bun": "./src/web/astro.ts",
       "import": "./lib/web/astro.js"
@@ -168,7 +172,7 @@
   },
   "dependencies": {
     "@aws-sdk/credential-providers": "^3.0.0",
-    "@cloudflare/unenv-preset": "^2.4.0",
+    "@cloudflare/unenv-preset": "^2.6.1",
     "@cloudflare/workers-shared": "^0.17.5",
     "@iarna/toml": "^2.2.5",
     "@smithy/node-config-provider": "^4.0.0",
@@ -182,8 +186,8 @@
     "fast-xml-parser": "^5.2.5",
     "find-process": "^2.0.0",
     "glob": "^10.0.0",
+    "picocolors": "^1.1.1",
     "jszip": "^3.0.0",
-    "kleur": "^4.1.5",
     "libsodium-wrappers": "^0.7.15",
     "miniflare": "^4.20250712.0",
     "neverthrow": "^8.2.0",
@@ -192,7 +196,7 @@
     "pathe": "^2.0.3",
     "signal-exit": "^4.1.0",
     "turndown": "^7.0.0",
-    "unenv": "2.0.0-rc.15",
+    "unenv": "2.0.0-rc.19",
     "ws": "^8.18.3",
     "yaml": "^2.0.0"
   },
@@ -260,7 +264,6 @@
     "nitro-cloudflare-dev": "^0.2.2",
     "nitropack": "^2.12.4",
     "openpgp": "^6.1.0",
-    "picocolors": "^1.1.1",
     "prettier": "^3.5.3",
     "rwsdk": "^0.1.28",
     "trpc-cli": "^0.10.2",

package/src/alchemy.ts

@@ -15,7 +15,7 @@ import {
   type PendingResource,
 } from "./resource.ts";
 import { isRuntime } from "./runtime/global.ts";
-import { DEFAULT_STAGE, Scope } from "./scope.ts";
+import { DEFAULT_STAGE, Scope, type ProviderCredentials } from "./scope.ts";
 import { secret } from "./secret.ts";
 import type { StateStoreType } from "./state.ts";
 import type { LoggerApi } from "./util/cli.ts";
@@ -420,7 +420,7 @@ export interface ScopeOptions extends AlchemyOptions {
   enter: boolean;
 }
 
-export interface RunOptions extends AlchemyOptions {
+export interface RunOptions extends AlchemyOptions, ProviderCredentials {
   /**
    * @default false
    */

package/src/aws/client-props.ts

@@ -0,0 +1,156 @@
+import type { Secret } from "../secret.ts";
+
+/**
+ * AWS client properties for credential configuration.
+ *
+ * This interface defines the properties that can be used to configure AWS credentials
+ * at different levels of your application. It supports the three-tier credential resolution
+ * system (global → scope → resource) and enables multi-account and multi-region deployments.
+ *
+ * These properties can be specified at:
+ * 1. Resource level - directly in resource creation parameters
+ * 2. Scope level - in alchemy.run() options with `aws` property
+ * 3. Global level - through environment variables (AWS_REGION, AWS_PROFILE, etc.)
+ *
+ * The credential resolution follows a precedence order where resource-level credentials
+ * override scope-level credentials, which override global environment variables.
+ *
+ * @example
+ * ```typescript
+ * // Resource-level credential overrides
+ * const vpc = await Vpc("main-vpc", {
+ *   cidrBlock: "10.0.0.0/16",
+ *   region: "us-west-2",      // Override region
+ *   profile: "production",    // Override profile
+ *   tags: { Name: "main-vpc" }
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Scope-level credential configuration
+ * await alchemy.run("production", {
+ *   aws: {
+ *     region: "us-west-2",
+ *     profile: "production",
+ *   }
+ * }, async () => {
+ *   // Resources created here will use the scope credentials by default
+ *   const vpc = await Vpc("main-vpc", {
+ *     cidrBlock: "10.0.0.0/16"
+ *   });
+ * });
+ * ```
+ */
+export interface AwsClientProps {
+  /**
+   * AWS access key ID for authentication.
+   *
+   * This corresponds to the AWS_ACCESS_KEY_ID environment variable.
+   * When provided at the resource or scope level, it overrides the environment variable.
+   */
+  accessKeyId?: Secret<string>;
+
+  /**
+   * AWS secret access key for authentication.
+   *
+   * This corresponds to the AWS_SECRET_ACCESS_KEY environment variable.
+   * When provided at the resource or scope level, it overrides the environment variable.
+   */
+  secretAccessKey?: Secret<string>;
+
+  /**
+   * AWS session token for temporary credentials.
+   *
+   * This corresponds to the AWS_SESSION_TOKEN environment variable.
+   * Used with temporary credentials from STS or when assuming a role.
+   */
+  sessionToken?: Secret<string>;
+
+  /**
+   * AWS region to use for API calls.
+   *
+   * This corresponds to the AWS_REGION or AWS_DEFAULT_REGION environment variables.
+   * When provided at the resource or scope level, it overrides the environment variables.
+   *
+   * @example
+   * ```typescript
+   * // Resource in a specific region
+   * const euVpc = await Vpc("eu-vpc", {
+   *   cidrBlock: "10.0.0.0/16",
+   *   region: "eu-west-1",
+   *   tags: { Name: "eu-vpc" }
+   * });
+   * ```
+   */
+  region?: string;
+
+  /**
+   * AWS profile name to use from credentials file.
+   *
+   * This corresponds to the AWS_PROFILE environment variable.
+   * Profiles are defined in ~/.aws/credentials or ~/.aws/config files.
+   *
+   * @example
+   * ```typescript
+   * // Resource using a specific profile
+   * const prodVpc = await Vpc("prod-vpc", {
+   *   cidrBlock: "10.0.0.0/16",
+   *   profile: "production-account",
+   *   tags: { Name: "prod-vpc" }
+   * });
+   * ```
+   */
+  profile?: string;
+
+  /**
+   * AWS role ARN to assume for authentication.
+   *
+   * This corresponds to the AWS_ROLE_ARN environment variable.
+   * Used for cross-account access or for assuming roles with specific permissions.
+   *
+   * @example
+   * ```typescript
+   * // Resource using role assumption
+   * const crossAccountVpc = await Vpc("cross-account-vpc", {
+   *   cidrBlock: "10.0.0.0/16",
+   *   roleArn: "arn:aws:iam::123456789012:role/DeploymentRole",
+   *   roleSessionName: "alchemy-deployment",
+   *   tags: { Name: "cross-account-vpc" }
+   * });
+   * ```
+   */
+  roleArn?: string;
+
+  /**
+   * External ID to use when assuming a role.
+   *
+   * This corresponds to the AWS_EXTERNAL_ID environment variable.
+   * Used as an additional security measure when assuming roles across accounts.
+   */
+  externalId?: string;
+
+  /**
+   * Session name to use when assuming a role.
+   *
+   * This corresponds to the AWS_ROLE_SESSION_NAME environment variable.
+   * Helps identify who/what is using the assumed role in AWS CloudTrail logs.
+   */
+  roleSessionName?: string;
+}
+/**
+ * AWS scope extensions - adds AWS credential support to scope options.
+ * This uses TypeScript module augmentation to extend the ProviderCredentials interface.
+ * Since ScopeOptions and RunOptions both extend ProviderCredentials,
+ * they automatically inherit these properties.
+ */
+declare module "../scope.ts" {
+  interface ProviderCredentials {
+    /**
+     * AWS credentials configuration for this scope.
+     * All AWS resources created within this scope will inherit these credentials
+     * unless overridden at the resource level.
+     */
+    aws?: AwsClientProps;
+  }
+}