alchemy 0.61.0 → 0.62.0

package/src/aws/ec2/subnet.ts

@@ -9,6 +9,7 @@ import {
   type TimeoutConfig,
   waitForResourceState,
 } from "../../util/timeout.ts";
+import type { AwsClientProps } from "../client-props.ts";
 import { retry } from "../retry.ts";
 import { callEC2Api, createEC2Client } from "./utils.ts";
 import type { Vpc } from "./vpc.ts";
@@ -16,7 +17,7 @@ import type { Vpc } from "./vpc.ts";
 /**
  * Properties for creating or updating a Subnet
  */
-export interface SubnetProps {
+export interface SubnetProps extends AwsClientProps {
   /**
    * The VPC to create the subnet in
    */
@@ -164,14 +165,15 @@ async function waitForSubnetDeleted(
  * AWS Subnet Resource
  *
  * Creates and manages subnets within a VPC. Subnets are used to segment
- * your VPC into smaller networks for organizing resources.
+ * your VPC into smaller networks for organizing resources. Supports AWS
+ * credential overrides for multi-account and cross-region deployments.
  *
  * @example
  * // Create a public subnet for web servers
  * const publicSubnet = await Subnet("public-subnet", {
  *   vpc: myVpc,
  *   cidrBlock: "10.0.1.0/24",
- *   availabilityZone: process.env.AWS_REGION ? `${process.env.AWS_REGION}a` : "us-east-1a",
+ *   availabilityZone: `${process.env.AWS_REGION}a` || "us-east-1a",
  *   mapPublicIpOnLaunch: true,
  *   tags: {
  *     Name: "public-subnet",
@@ -203,6 +205,62 @@ async function waitForSubnetDeleted(
  *     delayMs: 500
  *   }
  * });
+ *
+ * @example
+ * // Create a subnet with AWS credential overrides for cross-account deployment
+ * const crossAccountSubnet = await Subnet("cross-account-subnet", {
+ *   vpc: myVpc,
+ *   cidrBlock: "10.1.1.0/24",
+ *   availabilityZone: "us-east-1a",
+ *   region: "us-east-1",
+ *   profile: "production-account",
+ *   mapPublicIpOnLaunch: true,
+ *   tags: {
+ *     Name: "cross-account-subnet",
+ *     Account: "production"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a subnet in a different region with explicit credentials
+ * const multiRegionSubnet = await Subnet("multi-region-subnet", {
+ *   vpc: "vpc-12345678", // VPC ID from different region
+ *   cidrBlock: "10.2.1.0/24",
+ *   availabilityZone: "eu-west-1a",
+ *   region: "eu-west-1",
+ *   accessKeyId: alchemy.secret("AKIA..."),
+ *   secretAccessKey: alchemy.secret("..."),
+ *   mapPublicIpOnLaunch: false,
+ *   tags: {
+ *     Name: "eu-subnet",
+ *     Region: "europe"
+ *   }
+ * });
+ *
+ * @example
+ * // Using scope-level credentials with resource-level overrides
+ * await alchemy.run("multi-account", {
+ *   aws: {
+ *     region: "us-west-2",
+ *     profile: "staging"
+ *   }
+ * }, async () => {
+ *   // This subnet uses staging credentials from scope
+ *   const stagingSubnet = await Subnet("staging-subnet", {
+ *     vpc: stagingVpc,
+ *     cidrBlock: "10.0.1.0/24",
+ *     availabilityZone: "us-west-2a"
+ *   });
+ *
+ *   // This subnet overrides to use production credentials
+ *   const prodSubnet = await Subnet("prod-subnet", {
+ *     vpc: prodVpc,
+ *     cidrBlock: "10.1.1.0/24",
+ *     availabilityZone: "us-east-1a",
+ *     profile: "production",
+ *     region: "us-east-1"
+ *   });
+ * });
  */
 export const Subnet = Resource(
   "aws::Subnet",
@@ -211,7 +269,8 @@ export const Subnet = Resource(
     _id: string,
     props: SubnetProps,
   ): Promise<Subnet> {
-    const client = await createEC2Client();
+    // Create EC2 client with credential resolution handled internally
+    const client = await createEC2Client(props);
     const vpcId = typeof props.vpc === "string" ? props.vpc : props.vpc.vpcId;
 
     // Validate timeout config early, but use default for deletion if invalid

package/src/aws/ec2/utils.ts

@@ -1,7 +1,11 @@
 import { fromNodeProviderChain } from "@aws-sdk/credential-providers";
 import { AwsClient } from "aws4fetch";
+import { alchemy } from "../../alchemy.ts";
+import { Secret } from "../../secret.ts";
 import { logger } from "../../util/logger.ts";
 import { flattenParams } from "../../util/params.ts";
+import type { AwsClientProps } from "../client-props.ts";
+import { resolveAwsCredentials } from "../credentials.ts";
 import { getRegion } from "../utils.ts";
 
 /**
@@ -9,19 +13,81 @@ import { getRegion } from "../utils.ts";
  */
 
 /**
- * Create an AWS EC2 client
+ * Create an AWS EC2 client with credential resolution from props
+ *
+ * This function handles the complete credential resolution process internally,
+ * merging global, scope, and resource-level credentials according to the
+ * established precedence hierarchy.
+ *
+ * @param props - AWS client properties that may include credential overrides
+ * @returns Promise<AwsClient> - Configured AWS client for EC2 operations
  */
-export async function createEC2Client(): Promise<AwsClient> {
-  const credentials = await fromNodeProviderChain()();
-  const region = await getRegion();
+export async function createEC2Client(
+  props?: AwsClientProps,
+): Promise<AwsClient> {
+  // Resolve credentials from all sources (global, scope, resource)
+  const credentials = await resolveAwsCredentials(props);
+  let awsCredentials: AwsClientProps;
+  let region: string;
+
+  if (credentials && (credentials.accessKeyId || credentials.secretAccessKey)) {
+    // Use provided credentials directly (unwrap secrets for AWS SDK)
+    awsCredentials = {
+      accessKeyId: credentials.accessKeyId,
+      secretAccessKey: credentials.secretAccessKey,
+      sessionToken: credentials.sessionToken,
+    };
+  } else if (credentials?.profile) {
+    // Use profile-based credentials if profile is specified
+    try {
+      const profileCredentials = await fromNodeProviderChain({
+        profile: credentials.profile,
+      })();
+      awsCredentials = {
+        accessKeyId: alchemy.secret(profileCredentials.accessKeyId),
+        secretAccessKey: alchemy.secret(profileCredentials.secretAccessKey),
+        sessionToken: alchemy.secret(profileCredentials.sessionToken),
+      };
+    } catch (error) {
+      logger.log(
+        `Error loading credentials from profile ${credentials.profile}:`,
+        error,
+      );
+      // Fall back to default credentials
+      awsCredentials = await loadAwsPropsFromCredentialChain();
+    }
+  } else {
+    // Fall back to AWS SDK credential chain
+    awsCredentials = await loadAwsPropsFromCredentialChain();
+  }
+
+  // Use region from resolved credentials or fall back to getRegion()
+  if (credentials?.region) {
+    region = credentials.region;
+  } else {
+    region = await getRegion();
+  }
 
   return new AwsClient({
-    ...credentials,
+    ...awsCredentials,
+    accessKeyId: Secret.unwrap(awsCredentials.accessKeyId)!,
+    secretAccessKey: Secret.unwrap(awsCredentials.secretAccessKey)!,
+    sessionToken: Secret.unwrap(awsCredentials.sessionToken) || undefined,
     service: "ec2",
     region,
   });
 }
 
+async function loadAwsPropsFromCredentialChain(): Promise<AwsClientProps> {
+  const defaultCredentialsRaw = await fromNodeProviderChain()();
+  return {
+    ...defaultCredentialsRaw,
+    accessKeyId: alchemy.secret(defaultCredentialsRaw.accessKeyId),
+    secretAccessKey: alchemy.secret(defaultCredentialsRaw.secretAccessKey),
+    sessionToken: alchemy.secret(defaultCredentialsRaw.sessionToken),
+  };
+}
+
 /**
  * Make an EC2 API call with custom response parser
  */
@@ -34,8 +100,8 @@ export async function callEC2Api<T>(
   // Try the API call, and retry once with fresh credentials on auth failure
   for (let attempt = 1; attempt <= 2; attempt++) {
     try {
-      const region = await getRegion();
-      const url = `https://ec2.${region}.amazonaws.com/`;
+      // Use the client's region instead of the global region
+      const url = `https://ec2.${client.region}.amazonaws.com/`;
 
       const body = new URLSearchParams({
         Action: action,

package/src/aws/ec2/vpc.ts

@@ -9,12 +9,13 @@ import {
   type TimeoutConfig,
   waitForResourceState,
 } from "../../util/timeout.ts";
+import type { AwsClientProps } from "../client-props.ts";
 import { callEC2Api, createEC2Client } from "./utils.ts";
 
 /**
  * Properties for creating or updating a VPC
  */
-export interface VpcProps {
+export interface VpcProps extends AwsClientProps {
   /**
    * The IPv4 network range for the VPC, in CIDR notation
    * @example "10.0.0.0/16"
@@ -148,7 +149,8 @@ export interface Vpc extends Resource<"aws::Vpc">, VpcProps {
  * AWS VPC (Virtual Private Cloud) Resource
  *
  * Creates and manages Amazon VPC instances with configurable CIDR blocks,
- * DNS settings, and instance tenancy options.
+ * DNS settings, and instance tenancy options. Supports AWS credential overrides
+ * for multi-account and cross-region deployments.
  *
  * @example
  * // Create a basic VPC with default settings
@@ -188,6 +190,52 @@ export interface Vpc extends Resource<"aws::Vpc">, VpcProps {
  *     Type: "isolated"
  *   }
  * });
+ *
+ * @example
+ * // Create a VPC with AWS credential overrides for cross-account deployment
+ * const crossAccountVpc = await Vpc("cross-account-vpc", {
+ *   cidrBlock: "10.1.0.0/16",
+ *   region: "us-east-1",
+ *   profile: "production-account",
+ *   tags: {
+ *     Name: "cross-account-vpc",
+ *     Account: "production"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a VPC in a different region with explicit credentials
+ * const multiRegionVpc = await Vpc("multi-region-vpc", {
+ *   cidrBlock: "10.2.0.0/16",
+ *   region: "eu-west-1",
+ *   accessKeyId: alchemy.secret("AKIA..."),
+ *   secretAccessKey: alchemy.secret("..."),
+ *   tags: {
+ *     Name: "eu-vpc",
+ *     Region: "europe"
+ *   }
+ * });
+ *
+ * @example
+ * // Using scope-level credentials with resource-level overrides
+ * await alchemy.run("multi-account", {
+ *   aws: {
+ *     region: "us-west-2",
+ *     profile: "staging"
+ *   }
+ * }, async () => {
+ *   // This VPC uses staging credentials from scope
+ *   const stagingVpc = await Vpc("staging-vpc", {
+ *     cidrBlock: "10.0.0.0/16"
+ *   });
+ *
+ *   // This VPC overrides to use production credentials
+ *   const prodVpc = await Vpc("prod-vpc", {
+ *     cidrBlock: "10.1.0.0/16",
+ *     profile: "production",
+ *     region: "us-east-1"
+ *   });
+ * });
  */
 export const Vpc = Resource(
   "aws::Vpc",
@@ -196,7 +244,8 @@ export const Vpc = Resource(
     _id: string,
     props: VpcProps,
   ): Promise<Vpc> {
-    const client = await createEC2Client();
+    // Create EC2 client with credential resolution handled internally
+    const client = await createEC2Client(props);
     const timeoutConfig = mergeTimeoutConfig(VPC_TIMEOUT, props.timeout);
 
     if (this.phase === "delete") {

package/src/aws/index.ts

@@ -1,5 +1,7 @@
 export * from "./account-id.ts";
 export * from "./bucket.ts";
+export * from "./client-props.ts";
+export * from "./credentials.ts";
 export * from "./function.ts";
 export * from "./policy-attachment.ts";
 export * from "./policy.ts";

package/src/cloudflare/api-response.ts

@@ -102,8 +102,8 @@ export async function extractCloudflareResult<T>(
   label: string,
   promise: Promise<Response>,
 ): Promise<T> {
-  const response = await promise.catch(() => {
-    throw new Error(`Failed to ${label}: Failed to fetch`);
+  const response = await promise.catch((cause) => {
+    throw new Error(`Failed to ${label}: Failed to fetch`, { cause });
   });
   const json = (await response.json().catch(() => {
     throw new Error(

package/src/cloudflare/api.ts

@@ -63,6 +63,10 @@ const cloudflareApiCache: Record<string, CloudflareApi> = {};
 export async function createCloudflareApi(
   options: Partial<CloudflareApiOptions> | InternalCloudflareApiOptions = {},
 ): Promise<CloudflareApi> {
+  // TODO: Implement scope-level credential resolution similar to AWS
+  // This function should check for scope.providerCredentials.cloudflare
+  // and merge those credentials with the provided options, following
+  // the same three-tier resolution pattern: global → scope → resource
   const cacheKey = computeCacheKey(options);
   if (cloudflareApiCache[cacheKey]) {
     return cloudflareApiCache[cacheKey];
@@ -251,3 +255,22 @@ class TooManyRequestsError extends Error {
 }
 
 class ForbiddenError extends Error {}
+/**
+ * Cloudflare scope extensions - adds Cloudflare 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.
+ *
+ * NOTE: These scope credentials are not currently being used by createCloudflareApi.
+ * See TODO above in createCloudflareApi function for implementation needed.
+ */
+declare module "../scope.ts" {
+  interface ProviderCredentials {
+    /**
+     * Cloudflare credentials configuration for this scope.
+     * All Cloudflare resources created within this scope will inherit these credentials
+     * unless overridden at the resource level.
+     */
+    cloudflare?: CloudflareApiOptions;
+  }
+}

package/src/cloudflare/assets.ts

@@ -1,5 +1,5 @@
 import * as fs from "node:fs/promises";
-import * as path from "node:path";
+import * as path from "pathe";
 import type { Context } from "../context.ts";
 import { Resource } from "../resource.ts";
 import { getContentType } from "../util/content-type.ts";
@@ -118,11 +118,10 @@ export const Assets = Resource(
     // Create asset file objects
     const files: AssetFile[] = filesList.map((filePath) => {
       const relativePath = path.relative(props.path, filePath);
-      const normalizedPath = relativePath.split(path.sep).join("/"); // Ensure forward slashes for URLs
 
       return {
-        path: normalizedPath,
-        filePath,
+        path: path.normalize(relativePath),
+        filePath: path.normalize(filePath),
         contentType: getContentType(filePath) ?? "application/null",
       };
     });

package/src/cloudflare/bucket.ts

@@ -478,36 +478,40 @@ async function emptyBucket(
   bucketName: string,
   props: BucketProps,
 ) {
-  let batch: Promise<unknown>[] = [];
-  for await (const key of listObjects(api, bucketName, props)) {
-    batch.push(
-      extractCloudflareResult(
-        `delete R2 object "${key}"`,
+  let cursor: string | undefined;
+  while (true) {
+    const result = await listObjects(api, bucketName, props, cursor);
+    if (result.keys.length) {
+      // Another undocumented API! But it lets us delete multiple objects at once instead of one by one.
+      await extractCloudflareResult(
+        `delete ${result.keys.length} objects from bucket "${bucketName}"`,
         api.delete(
-          `/accounts/${api.accountId}/r2/buckets/${bucketName}/objects/${key}`,
-          { headers: withJurisdiction(props) },
+          `/accounts/${api.accountId}/r2/buckets/${bucketName}/objects`,
+          {
+            headers: withJurisdiction(props),
+            method: "DELETE",
+            body: JSON.stringify(result.keys),
+          },
         ),
-      ),
-    );
-    if (batch.length >= 10) {
-      // this is an arbitary batch size, open to feedback
-      await Promise.all(batch);
-      batch = [];
+      );
+      if (result.cursor) {
+        cursor = result.cursor;
+        continue;
+      }
     }
+    break;
   }
-  await Promise.all(batch);
 }
 
 /**
- * Returns an async iterable of all object keys in a bucket,
- * handling pagination automatically.
+ * Lists objects in a bucket.
  */
-export async function* listObjects(
+export async function listObjects(
   api: CloudflareApi,
   bucketName: string,
   props: { jurisdiction?: string },
   cursor?: string,
-): AsyncGenerator<string> {
+) {
   const params = new URLSearchParams({
     per_page: "1000",
   });
@@ -531,7 +535,7 @@ export async function* listObjects(
   if (!json.success) {
     // 10006 indicates that the bucket does not exist, so there are no objects to list
     if (json.errors.some((e) => e.code === 10006)) {
-      return;
+      return { keys: [], cursor: undefined };
     }
     throw new CloudflareApiError(
       `Failed to list objects in bucket "${bucketName}": ${json.errors.map((e) => `- [${e.code}] ${e.message}${e.documentation_url ? ` (${e.documentation_url})` : ""}`).join("\n")}`,
@@ -539,12 +543,10 @@ export async function* listObjects(
       json.errors,
     );
   }
-  for (const object of json.result) {
-    yield object.key;
-  }
-  if (json.result_info?.is_truncated && json.result_info.cursor) {
-    yield* listObjects(api, bucketName, props, json.result_info.cursor);
-  }
+  return {
+    keys: json.result.map((object) => object.key),
+    cursor: json.result_info?.cursor,
+  };
 }
 
 /**

package/src/cloudflare/bundle/plugin-compat-warning.ts

@@ -1,7 +1,7 @@
 import type { Plugin, PluginBuild } from "esbuild";
-import kleur from "kleur";
 import module from "node:module";
 import path from "node:path";
+import pc from "picocolors";
 import { logger } from "../../util/logger.ts";
 
 const NODE_REGEX = new RegExp(
@@ -54,13 +54,13 @@ export function esbuildPluginCompatWarning(mode: "als" | null): Plugin {
         if (packages.size > 0) {
           const formattedImports = Array.from(packages)
             .sort()
-            .map((imp) => kleur.yellow(imp))
+            .map((imp) => pc.yellow(imp))
             .join(", ");
 
           logger.warn(
             [
-              `Detected Node.js imports (${formattedImports}) but ${kleur.red("nodejs_compat")} compatibility flag is not set. `,
-              `Add ${kleur.blue("nodejs_compat")} to your compatibility flags and ensure compatibilityDate >= 2024-09-23. Imported from:`,
+              `Detected Node.js imports (${formattedImports}) but ${pc.red("nodejs_compat")} compatibility flag is not set. `,
+              `Add ${pc.blue("nodejs_compat")} to your compatibility flags and ensure compatibilityDate >= 2024-09-23. Imported from:`,
               formatImporters(
                 nodeImporters,
                 build.initialOptions.absWorkingDir ?? process.cwd(),
@@ -72,8 +72,8 @@ export function esbuildPluginCompatWarning(mode: "als" | null): Plugin {
         if (alsImporters.size > 0 && !mode) {
           logger.warn(
             [
-              `Detected import of ${kleur.yellow("node:async_hooks")} but ${kleur.red("nodejs_als")} compatibility flag is not set. `,
-              `Add ${kleur.blue("nodejs_als")} or ${kleur.blue("nodejs_compat")} to your compatibility flags. Imported from:`,
+              `Detected import of ${pc.yellow("node:async_hooks")} but ${pc.red("nodejs_als")} compatibility flag is not set. `,
+              `Add ${pc.blue("nodejs_als")} or ${pc.blue("nodejs_compat")} to your compatibility flags. Imported from:`,
               formatImporters(
                 alsImporters,
                 build.initialOptions.absWorkingDir ?? process.cwd(),
@@ -89,6 +89,6 @@ export function esbuildPluginCompatWarning(mode: "als" | null): Plugin {
 function formatImporters(importers: Set<string>, cwd: string) {
   return Array.from(importers)
     .sort()
-    .map((imp) => `- ${kleur.yellow(path.relative(cwd, imp))}`)
+    .map((imp) => `- ${pc.yellow(path.relative(cwd, imp))}`)
     .join("\n");
 }

package/src/cloudflare/cloudflare-env-proxy.ts

@@ -41,10 +41,10 @@ export const getPlatformProxyOptions = (
     ...input,
     configPath: validateConfigPath(input.configPath ?? DEFAULT_CONFIG_PATH),
     persist,
-    experimental: input.experimental ?? {
+    experimental: (input as any).experimental ?? {
       remoteBindings: true,
     },
-  };
+  } as any;
 };
 
 const warned = new Set<string>();

package/src/cloudflare/kv-namespace.ts

@@ -100,41 +100,40 @@ export function isKVNamespace(resource: Resource): resource is KVNamespace {
 /**
  * Output returned after KV Namespace creation/update
  */
-export interface KVNamespace
-  extends Resource<"cloudflare::KVNamespace">,
-    Omit<KVNamespaceProps, "delete" | "dev"> {
-  type: "kv_namespace";
-  /**
-   * The ID of the namespace
-   */
-  namespaceId: string;
-
-  /**
-   * Time at which the namespace was created
-   */
-  createdAt: number;
+export type KVNamespace = Resource<"cloudflare::KVNamespace"> &
+  Omit<KVNamespaceProps, "delete" | "dev"> & {
+    type: "kv_namespace";
+    /**
+     * The ID of the namespace
+     */
+    namespaceId: string;
 
-  /**
-   * Time at which the namespace was last modified
-   */
-  modifiedAt: number;
+    /**
+     * Time at which the namespace was created
+     */
+    createdAt: number;
 
-  /**
-   * Development mode properties
-   * @internal
-   */
-  dev: {
     /**
-     * The ID of the KV namespace in development mode
+     * Time at which the namespace was last modified
      */
-    id: string;
+    modifiedAt: number;
 
     /**
-     * Whether the KV namespace is running remotely
+     * Development mode properties
+     * @internal
      */
-    remote: boolean;
+    dev: {
+      /**
+       * The ID of the KV namespace in development mode
+       */
+      id: string;
+
+      /**
+       * Whether the KV namespace is running remotely
+       */
+      remote: boolean;
+    };
   };
-}
 
 /**
  * A Cloudflare KV Namespace is a key-value store that can be used to store data for your application.

package/src/cloudflare/oauth.ts

@@ -1,4 +1,4 @@
-import kleur from "kleur";
+import envPaths from "env-paths";
 import { err, ok, okAsync, ResultAsync } from "neverthrow";
 import assert from "node:assert";
 import crypto from "node:crypto";
@@ -6,7 +6,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import open from "open";
-import envPaths from "env-paths";
+import pc from "picocolors";
 import { HTTPServer } from "../util/http.ts";
 import { memoize } from "../util/memoize.ts";
 import {
@@ -133,7 +133,7 @@ export const wranglerLogin = (
     [
       "Opening browser to authorize with Cloudflare...",
       "",
-      kleur.gray(
+      pc.gray(
         "If you are not automatically redirected, please open the following URL in your browser:",
       ),
       challenge.url,