alchemy 0.93.11 → 0.94.0

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "alchemy",
-  "version": "0.93.11",
+  "version": "0.94.0",
   "homepage": "https://alchemy.run",
   "license": "Apache-2.0",
   "author": "Sam Goodwin <sam@alchemy.run>",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/alchemy-run/alchemy.git",
+    "url": "git+https://github.com/alchemy-run/alchemy-async.git",
     "directory": "alchemy"
   },
   "bin": {
@@ -179,7 +179,7 @@
   "dependencies": {
     "@aws-sdk/credential-providers": "^3.0.0",
     "@cloudflare/unenv-preset": "2.7.7",
-    "@cloudflare/workers-types": "^4.20260602.1",
+    "@cloudflare/workers-types": "^5.20260708.1",
     "@iarna/toml": "^2.2.5",
     "@octokit/rest": "^21.1.1",
     "@smithy/node-config-provider": "^4.0.0",
@@ -195,7 +195,7 @@
     "glob": "^10.0.0",
     "jszip": "^3.0.0",
     "libsodium-wrappers": "^0.8.0",
-    "miniflare": "4.20260424.0",
+    "miniflare": "4.20260708.1",
     "neverthrow": "^8.2.0",
     "open": "^10.1.2",
     "openapi-types": "^12.1.3",

package/src/aws/control/client.ts

@@ -3,6 +3,7 @@ import { loadConfig } from "@smithy/node-config-provider";
 import { AwsClient } from "aws4fetch";
 import { logger } from "../../util/logger.ts";
 import { safeFetch } from "../../util/safe-fetch.ts";
+import { awsEndpoint } from "../utils.ts";
 import {
   AlreadyExistsError,
   CloudControlError,
@@ -355,7 +356,7 @@ export class CloudControlClient {
     while (true) {
       try {
         const args = [
-          `https://cloudcontrolapi.${this.region}.amazonaws.com/?Action=${action}&Version=2021-09-30`,
+          `${awsEndpoint("cloudcontrolapi", this.region)}/?Action=${action}&Version=2021-09-30`,
           {
             method: "POST",
             headers: {

package/src/aws/control/resource.ts

@@ -6,7 +6,11 @@ import {
   type Provider,
 } from "../../resource.ts";
 import { logger } from "../../util/logger.ts";
-import { createCloudControlClient, type ProgressEvent } from "./client.ts";
+import {
+  createCloudControlClient,
+  type CloudControlClient,
+  type ProgressEvent,
+} from "./client.ts";
 import {
   AlreadyExistsError,
   ConcurrentOperationError,
@@ -297,8 +301,20 @@ async function CloudControlLifecycle(
       props.typeName,
       this.output.id,
     );
+    if (!currentResource) {
+      // The physical resource no longer exists (deleted or detached out-of-band),
+      // so there is nothing to patch. Falling through to UpdateResource would fail
+      // on types with no update support (e.g. AWS::EC2::VolumeAttachment, whose
+      // properties are all Immutable). Recreate via replacement instead. Force the
+      // replacement (delete-before-create) because the old resource is already gone
+      // (delete tolerates NotFoundError) and a deferred delete would destroy the
+      // new resource if it reuses the same identifier (e.g. an unchanged BucketName).
+      logger.log(
+        `Resource ${id} no longer exists (empty read-back on update), requiring replacement`,
+      );
+      return this.replace(true);
+    }
     if (
-      currentResource &&
       hasImmutablePropertyChanges(
         props.typeName,
         currentResource,
@@ -328,10 +344,12 @@ async function CloudControlLifecycle(
       );
     } catch (error) {
       if (error instanceof AlreadyExistsError && props.adopt) {
-        const resource = (await client.getResource(
+        const resource = await getResourceForAdoption(
+          client,
           props.typeName,
-          error.progressEvent.Identifier!,
-        ))!;
+          error.progressEvent.Identifier,
+          error,
+        );
 
         response = await updateResourceWithPatch(
           client,
@@ -357,10 +375,11 @@ async function CloudControlLifecycle(
           const concurrentResult = await client.poll(error.requestToken);
 
           // The concurrent operation succeeded, now adopt the resource
-          const resource = (await client.getResource(
+          const resource = await getResourceForAdoption(
+            client,
             props.typeName,
-            concurrentResult.Identifier!,
-          ))!;
+            concurrentResult.Identifier,
+          );
 
           // Apply our desired state as a patch to the existing resource
           response = await updateResourceWithPatch(
@@ -401,6 +420,46 @@ async function CloudControlLifecycle(
   };
 }
 
+/**
+ * Read back a resource that Cloud Control reported as already existing so it
+ * can be adopted. The read-back is retried briefly because some services are
+ * eventually consistent between the create conflict and GetResource.
+ *
+ * If the resource still cannot be read back, adoption is impossible — most
+ * commonly the name is taken in a globally shared namespace but not visible
+ * in this account (e.g. an S3 bucket owned by another AWS account, or a
+ * recently deleted name still held by the service). Cloud Control reports
+ * both as AlreadyExists, so fail with an actionable error instead of letting
+ * `undefined` flow into the patch computation.
+ */
+async function getResourceForAdoption(
+  client: CloudControlClient,
+  typeName: string,
+  identifier: string | undefined,
+  cause?: Error,
+): Promise<Record<string, any>> {
+  if (identifier) {
+    let delay = 500;
+    for (let attempt = 0; attempt < 5; attempt++) {
+      if (attempt > 0) {
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        delay *= 2;
+      }
+      const resource = await client.getResource(typeName, identifier);
+      if (resource !== undefined) {
+        return resource;
+      }
+    }
+  }
+  throw new Error(
+    `Resource ${typeName} "${identifier}" already exists but could not be read back for adoption. ` +
+      "It may belong to a different AWS account (e.g. S3 bucket names are globally unique), " +
+      "exist in a different region, or its name may still be reserved by a recent deletion. " +
+      "Choose a different name or wait for the name to become available.",
+    { cause },
+  );
+}
+
 async function updateResourceWithPatch(
   client: any,
   typeName: string,

package/src/aws/ec2/utils.ts

@@ -6,7 +6,7 @@ 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";
+import { awsEndpoint, getRegion } from "../utils.ts";
 
 /**
  * Shared EC2 utilities for all EC2 resources
@@ -100,8 +100,10 @@ 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 {
-      // Use the client's region instead of the global region
-      const url = `https://ec2.${client.region}.amazonaws.com/`;
+      // Use the client's region instead of the global region.
+      // Honour AWS_ENDPOINT_URL / AWS_ENDPOINT_URL_EC2 for emulators
+      // (LocalStack, moto, etc.) — matches AWS SDK v3 behaviour.
+      const url = `${awsEndpoint("ec2", client.region ?? "us-east-1")}/`;
 
       const body = new URLSearchParams({
         Action: action,

package/src/aws/utils.ts

@@ -14,13 +14,29 @@ export const getRegion: Provider<string> = loadConfig({
   default: "us-east-1",
 });
 
+/**
+ * Resolve the endpoint URL for an aws4fetch service request, honouring the
+ * same `AWS_ENDPOINT_URL_<SERVICE>` / `AWS_ENDPOINT_URL` env vars as the AWS
+ * SDK / CLI so aws4fetch-based resources can be pointed at LocalStack, moto,
+ * or any other emulator.
+ */
+export function awsEndpoint(service: string, region: string): string {
+  return (
+    process.env[
+      `AWS_ENDPOINT_URL_${service.toUpperCase().replace(/-/g, "_")}`
+    ] ??
+    process.env.AWS_ENDPOINT_URL ??
+    `https://${service}.${region}.amazonaws.com`
+  ).replace(/\/+$/, "");
+}
+
 /**
  * AWS Service Configuration
  */
 export interface AwsServiceConfig {
   service: string;
   version: string;
-  endpoint: (region: string) => string;
+  endpoint?: (region: string) => string;
 }
 
 /**
@@ -63,7 +79,9 @@ export function getAwsApiCaller<T = any>(
       for (let attempt = 1; attempt <= 2; attempt++) {
         try {
           const region = await getRegion();
-          const url = config.endpoint(region);
+          const url = config.endpoint
+            ? config.endpoint(region)
+            : `${awsEndpoint(config.service, region)}/`;
 
           const body = new URLSearchParams({
             Action: action,

package/src/cloudflare/artifacts.ts

@@ -0,0 +1,69 @@
+/**
+ * Properties for creating an Artifacts binding.
+ *
+ * Artifacts namespaces are created implicitly by Cloudflare when the first
+ * repository is created in the namespace, so this binding does not provision
+ * or delete a namespace resource.
+ */
+export interface ArtifactsProps {
+  /**
+   * Artifacts namespace name.
+   */
+  namespace: string;
+
+  dev?: {
+    /**
+     * Whether to run the Artifacts binding remotely in local development.
+     *
+     * Artifacts do not have a local emulator, so generated Wrangler config
+     * defaults this binding to remote mode.
+     *
+     * @default true
+     */
+    remote?: boolean;
+  };
+}
+
+/**
+ * Cloudflare Artifacts binding.
+ *
+ * Artifacts namespaces are implicit containers for repositories. Use this
+ * helper to bind a Worker to a namespace; repository lifecycle should be
+ * managed through the Artifacts runtime API, REST API, or Git endpoint.
+ *
+ * @example
+ * ```ts
+ * import { Artifacts, Worker } from "alchemy/cloudflare";
+ *
+ * await Worker("site-editor", {
+ *   entrypoint: "./src/worker.ts",
+ *   bindings: {
+ *     SITE_ARTIFACTS: Artifacts({ namespace: "my-sites" }),
+ *   },
+ * });
+ * ```
+ *
+ * @see https://developers.cloudflare.com/artifacts/
+ */
+export interface Artifacts {
+  type: "artifacts";
+  namespace: string;
+  dev?: {
+    remote?: boolean;
+  };
+}
+
+export function Artifacts(props: string | ArtifactsProps): Artifacts {
+  if (typeof props === "string") {
+    return {
+      type: "artifacts",
+      namespace: props,
+    };
+  }
+
+  return {
+    type: "artifacts",
+    namespace: props.namespace,
+    dev: props.dev,
+  };
+}

package/src/cloudflare/bindings.ts

@@ -8,6 +8,7 @@ import type { Ai } from "./ai.ts";
 import type { AiSearchNamespace } from "./ai-search-namespace.ts";
 import type { AiSearch } from "./ai-search.ts";
 import type { AnalyticsEngineDataset } from "./analytics-engine.ts";
+import type { Artifacts } from "./artifacts.ts";
 import type { Assets } from "./assets.ts";
 import type { Bound } from "./bound.ts";
 import type { BrowserRendering } from "./browser-rendering.ts";
@@ -54,6 +55,7 @@ export type Binding =
   | AiSearch
   | AiSearchNamespace
   | Assets
+  | Artifacts
   | Container
   | CloudflareSecret
   | CloudflareSecretRef
@@ -127,6 +129,7 @@ export type WorkerBindingSpec =
   | WorkerBindingAiSearch
   | WorkerBindingAiSearchNamespace
   | WorkerBindingAnalyticsEngine
+  | WorkerBindingArtifacts
   | WorkerBindingAssets
   | WorkerBindingBrowserRendering
   | WorkerBindingD1
@@ -206,6 +209,18 @@ export interface WorkerBindingAnalyticsEngine {
   dataset: string;
 }
 
+/**
+ * Artifacts binding type
+ */
+export interface WorkerBindingArtifacts {
+  /** The name of the binding */
+  name: string;
+  /** Type identifier for Artifacts binding */
+  type: "artifacts";
+  /** Artifacts namespace name */
+  namespace: string;
+}
+
 /**
  * Assets binding type
  */
@@ -295,8 +310,8 @@ export interface WorkerBindingJson {
   name: string;
   /** Type identifier for JSON binding */
   type: "json";
-  /** JSON value */
-  json: string;
+  /** JSON value, sent raw (not stringified) so the runtime injects native types */
+  json: unknown;
 }
 
 /**

package/src/cloudflare/bound.ts

@@ -5,6 +5,7 @@ import type { Ai as _Ai } from "./ai.ts";
 import type { AiSearchNamespace as _AiSearchNamespace } from "./ai-search-namespace.ts";
 import type { AiSearch as _AiSearch } from "./ai-search.ts";
 import type { AnalyticsEngineDataset as _AnalyticsEngineDataset } from "./analytics-engine.ts";
+import type { Artifacts as _Artifacts } from "./artifacts.ts";
 import type { Assets } from "./assets.ts";
 import type { Binding, Json, Self } from "./bindings.ts";
 import type { BrowserRendering } from "./browser-rendering.ts";
@@ -61,69 +62,71 @@ export type Bound<T extends Binding> = T extends _AiSearch
           ? BoundWorker<RPC>
           : T extends _Worker<any, infer RPC> | WorkerRef<infer RPC>
             ? BoundWorker<RPC>
-            : T extends { type: "service" }
-              ? Service
-              : T extends _R2Bucket
-                ? R2Bucket
-                : T extends _Hyperdrive | HyperdriveRef
-                  ? Hyperdrive
-                  : T extends Secret
-                    ? string
-                    : T extends CloudflareSecret | CloudflareSecretRef
-                      ? SecretsStoreSecret
-                      : T extends _EmailSender
-                        ? SendEmail
-                        : T extends SecretKey
-                          ? CryptoKey
-                          : T extends Assets
-                            ? Service
-                            : T extends _Workflow<infer P>
-                              ? Workflow<P>
-                              : T extends _D1Database
-                                ? D1Database
-                                : T extends DispatchNamespace
-                                  ? DispatchNamespace
-                                  : T extends _WorkerLoader
-                                    ? WorkerLoader
-                                    : T extends _VectorizeIndex
-                                      ? VectorizeIndex
-                                      : T extends _Queue<infer Body>
-                                        ? Queue<Body>
-                                        : T extends _AnalyticsEngineDataset
-                                          ? AnalyticsEngineDataset
-                                          : T extends _Pipeline<infer R>
-                                            ? Pipeline<R>
-                                            : T extends _RateLimit
-                                              ? RateLimit
-                                              : T extends string
-                                                ? T
-                                                : T extends BrowserRendering
-                                                  ? BrowserRun
-                                                  : T extends _Ai<infer M>
-                                                    ? Ai<M>
-                                                    : T extends _Images
-                                                      ? ImagesBinding
-                                                      : T extends _VersionMetadata
-                                                        ? WorkerVersionMetadata
-                                                        : T extends
-                                                              | _Worker.DevDomain
-                                                              | _Worker.DevUrl
-                                                          ? string
-                                                          : T extends Self
-                                                            ? Service
-                                                            : T extends Json<
-                                                                  infer T
-                                                                >
-                                                              ? T
-                                                              : T extends _Container<
-                                                                    infer Obj
+            : T extends _Artifacts
+              ? Artifacts
+              : T extends { type: "service" }
+                ? Service
+                : T extends _R2Bucket
+                  ? R2Bucket
+                  : T extends _Hyperdrive | HyperdriveRef
+                    ? Hyperdrive
+                    : T extends Secret
+                      ? string
+                      : T extends CloudflareSecret | CloudflareSecretRef
+                        ? SecretsStoreSecret
+                        : T extends _EmailSender
+                          ? SendEmail
+                          : T extends SecretKey
+                            ? CryptoKey
+                            : T extends Assets
+                              ? Service
+                              : T extends _Workflow<infer P>
+                                ? Workflow<P>
+                                : T extends _D1Database
+                                  ? D1Database
+                                  : T extends DispatchNamespace
+                                    ? DispatchNamespace
+                                    : T extends _WorkerLoader
+                                      ? WorkerLoader
+                                      : T extends _VectorizeIndex
+                                        ? VectorizeIndex
+                                        : T extends _Queue<infer Body>
+                                          ? Queue<Body>
+                                          : T extends _AnalyticsEngineDataset
+                                            ? AnalyticsEngineDataset
+                                            : T extends _Pipeline<infer R>
+                                              ? Pipeline<R>
+                                              : T extends _RateLimit
+                                                ? RateLimit
+                                                : T extends string
+                                                  ? T
+                                                  : T extends BrowserRendering
+                                                    ? BrowserRun
+                                                    : T extends _Ai<infer M>
+                                                      ? Ai<M>
+                                                      : T extends _Images
+                                                        ? ImagesBinding
+                                                        : T extends _VersionMetadata
+                                                          ? WorkerVersionMetadata
+                                                          : T extends
+                                                                | _Worker.DevDomain
+                                                                | _Worker.DevUrl
+                                                            ? string
+                                                            : T extends Self
+                                                              ? Service
+                                                              : T extends Json<
+                                                                    infer T
                                                                   >
-                                                                ? DurableObjectNamespace<
-                                                                    Obj &
-                                                                      Rpc.DurableObjectBranded
-                                                                  >
-                                                                : T extends _VpcService
-                                                                  ? Fetcher
-                                                                  : T extends undefined
-                                                                    ? undefined
-                                                                    : Service;
+                                                                ? T
+                                                                : T extends _Container<
+                                                                      infer Obj
+                                                                    >
+                                                                  ? DurableObjectNamespace<
+                                                                      Obj &
+                                                                        Rpc.DurableObjectBranded
+                                                                    >
+                                                                  : T extends _VpcService
+                                                                    ? Fetcher
+                                                                    : T extends undefined
+                                                                      ? undefined
+                                                                      : Service;

package/src/cloudflare/bucket-custom-domain.ts

@@ -142,17 +142,24 @@ export const R2BucketCustomDomain = Resource(
           props.jurisdiction,
           payload,
         ).catch(async (error) => {
-          if (
-            error instanceof CloudflareApiError &&
-            error.status === 409 &&
-            adopt
-          ) {
-            return await updateBucketCustomDomain(
+          if (error instanceof CloudflareApiError && error.status === 409) {
+            const existing = await getBucketCustomDomain(
               api,
               props.bucketName,
+              payload.domain,
               props.jurisdiction,
-              payload,
             );
+            if (existing && customDomainMatches(existing, payload)) {
+              return;
+            }
+            if (adopt) {
+              return await updateBucketCustomDomain(
+                api,
+                props.bucketName,
+                props.jurisdiction,
+                payload,
+              );
+            }
           }
           throw error;
         });
@@ -190,6 +197,25 @@ export const R2BucketCustomDomain = Resource(
   },
 );
 
+function customDomainMatches(
+  existing: R2BucketCustomDomain,
+  payload: R2BucketCustomDomain,
+) {
+  return (
+    existing.domain === payload.domain &&
+    existing.zoneId === payload.zoneId &&
+    existing.enabled === payload.enabled &&
+    (existing.minTLS ?? undefined) === (payload.minTLS ?? undefined) &&
+    arraysEqual(existing.ciphers, payload.ciphers)
+  );
+}
+
+function arraysEqual(a: string[] | undefined, b: string[] | undefined) {
+  if (a === b) return true;
+  if (!a || !b || a.length !== b.length) return false;
+  return a.every((v, i) => v === b[i]);
+}
+
 async function createBucketCustomDomain(
   api: CloudflareApi,
   bucket: string,

package/src/cloudflare/d1-database.ts

@@ -307,11 +307,21 @@ const _D1Database = Resource(
 
     if (local) {
       if (props.migrationsFiles?.length || props.importFiles?.length) {
+        const localMigrationsFiles = props.migrationsDir
+          ? await listSqlFiles(props.migrationsDir)
+          : [];
+        const localImportFiles = props.importFiles?.length
+          ? await Promise.all(
+              props.importFiles.map((file) =>
+                readSqlFile(this.scope.rootDir, file.id),
+              ),
+            )
+          : [];
         await applyLocalD1Migrations({
           databaseId: dev.id,
           migrationsTable: props.migrationsTable ?? DEFAULT_MIGRATIONS_TABLE,
-          migrations: props.migrationsFiles ?? [],
-          imports: props.importFiles ?? [],
+          migrations: localMigrationsFiles,
+          imports: localImportFiles,
           rootDir: this.scope.rootDir,
         });
       }

package/src/cloudflare/hyperdrive.ts

@@ -47,6 +47,11 @@ export interface HyperdrivePublicOrigin {
    */
   scheme?: "postgres" | "mysql";
 
+  /**
+   * Connection query string, without the leading "?"
+   */
+  query?: string;
+
   /**
    * Database user
    */
@@ -90,6 +95,11 @@ export interface HyperdriveOriginWithAccess {
    */
   scheme?: "postgres" | "mysql";
 
+  /**
+   * Connection query string, without the leading "?"
+   */
+  query?: string;
+
   /**
    * Database user
    */
@@ -610,6 +620,7 @@ export const normalizeHyperdriveOrigin = (
       host: url.hostname,
       port: normalizePort(scheme, url.port),
       database: url.pathname.slice(1),
+      query: url.search?.slice(1) ?? "",
     };
   }
   const scheme = normalizeScheme(origin.scheme);
@@ -623,6 +634,7 @@ export const normalizeHyperdriveOrigin = (
     }),
     scheme,
     port: normalizePort(scheme, origin.port),
+    query: origin.query ?? "",
   };
 };
 
@@ -660,6 +672,6 @@ const toConnectionString = (
     "password" in origin ? origin.password : origin.access_client_secret,
   );
   return new Secret(
-    `${origin.scheme}://${origin.user}:${password}@${origin.host}:${origin.port}/${origin.database}`,
+    `${origin.scheme}://${origin.user}:${password}@${origin.host}:${origin.port}/${origin.database}${origin.query ? `?${origin.query}` : ""}`,
   );
 };

package/src/cloudflare/index.ts

@@ -20,6 +20,7 @@ export * from "./api-gateway-operation.ts";
 export * from "./api-schema.ts";
 export * from "./api-shield.ts";
 export * from "./api.ts";
+export * from "./artifacts.ts";
 export * from "./assets.ts";
 export * from "./astro/astro.ts";
 export * from "./bindings.ts";

package/src/cloudflare/miniflare/build-worker-options.ts

@@ -167,6 +167,11 @@ export const buildWorkerOptions = async (
         };
         break;
       }
+      case "artifacts": {
+        throw new Error(
+          "Artifacts bindings are not supported in Alchemy local dev yet. Deploy the Worker or use generated Wrangler config with remote Artifacts bindings.",
+        );
+      }
       case "assets": {
         options.assets = {
           binding: key,

package/src/cloudflare/miniflare/miniflare-worker-proxy.ts

@@ -249,7 +249,9 @@ const writeMiniflareResponseToNode = (
   });
 
   if (res.body) {
-    Readable.fromWeb(res.body).pipe(out, { end: true });
+    const body = Readable.fromWeb(res.body);
+    body.on("error", () => out.destroy());
+    body.pipe(out, { end: true });
   } else {
     out.end();
   }