alchemy 0.92.2 → 0.93.0

package/src/cloudflare/bindings.ts

@@ -5,6 +5,8 @@
  */
 import type { Secret } from "../secret.ts";
 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 { Assets } from "./assets.ts";
 import type { Bound } from "./bound.ts";
@@ -49,6 +51,8 @@ export declare namespace Bindings {
  */
 export type Binding =
   | Ai
+  | AiSearch
+  | AiSearchNamespace
   | Assets
   | Container
   | CloudflareSecret
@@ -120,6 +124,8 @@ export function Json<const T>(value: T): Json<T> {
  */
 export type WorkerBindingSpec =
   | WorkerBindingAI
+  | WorkerBindingAiSearch
+  | WorkerBindingAiSearchNamespace
   | WorkerBindingAnalyticsEngine
   | WorkerBindingAssets
   | WorkerBindingBrowserRendering
@@ -161,6 +167,33 @@ export interface WorkerBindingAI {
   type: "ai";
 }
 
+/**
+ * AI Search single instance binding type.
+ * Binds directly to one specific AI Search instance (always scoped to default namespace).
+ */
+export interface WorkerBindingAiSearch {
+  /** The name of the binding */
+  name: string;
+  /** Type identifier for AI Search single instance binding */
+  type: "ai_search";
+  /** The AI Search instance name */
+  instance_name: string;
+}
+
+/**
+ * AI Search namespace binding type.
+ * Scoped to a user-defined namespace of AI Search instances.
+ * Grants full access (CRUD + search + chat) to all instances within the namespace.
+ */
+export interface WorkerBindingAiSearchNamespace {
+  /** The name of the binding */
+  name: string;
+  /** Type identifier for AI Search namespace binding */
+  type: "ai_search_namespace";
+  /** The namespace name */
+  namespace: string;
+}
+
 /**
  * Analytics Engine binding type
  */

package/src/cloudflare/bound.ts

@@ -1,6 +1,9 @@
+/// <reference types="@cloudflare/workers-types" />
 import type { Pipeline } from "cloudflare:pipelines";
 import type { Secret } from "../secret.ts";
 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 { Assets } from "./assets.ts";
 import type { Binding, Json, Self } from "./bindings.ts";
@@ -9,6 +12,7 @@ import type { R2Bucket as _R2Bucket } from "./bucket.ts";
 import type { Container as _Container } from "./container.ts";
 import type { D1Database as _D1Database } from "./d1-database.ts";
 import type { DurableObjectNamespace as _DurableObjectNamespace } from "./durable-object-namespace.ts";
+import type { EmailSender as _EmailSender } from "./email-sender.ts";
 import type { HyperdriveRef } from "./hyperdrive-ref.ts";
 import type { Hyperdrive as _Hyperdrive } from "./hyperdrive.ts";
 import type { Images as _Images } from "./images.ts";
@@ -18,7 +22,6 @@ import type { RateLimit as _RateLimit } from "./rate-limit.ts";
 import type { SecretKey } from "./secret-key.ts";
 import type { SecretRef as CloudflareSecretRef } from "./secret-ref.ts";
 import type { Secret as CloudflareSecret } from "./secret.ts";
-import type { EmailSender as _EmailSender } from "./email-sender.ts";
 import type { VectorizeIndex as _VectorizeIndex } from "./vectorize-index.ts";
 import type { VersionMetadata as _VersionMetadata } from "./version-metadata.ts";
 import type { VpcService as _VpcService } from "./vpc-service.ts";
@@ -39,78 +42,88 @@ type BoundWorker<
   >]: Rpc.Provider<RPC, "fetch" | "connect">[property];
 };
 
-export type Bound<T extends Binding> =
-  T extends _DurableObjectNamespace<infer O>
-    ? DurableObjectNamespace<O & Rpc.DurableObjectBranded>
-    : T extends { type: "kv_namespace" }
-      ? KVNamespace
-      : T extends WorkerStub<infer RPC>
-        ? BoundWorker<RPC>
-        : T extends _Worker<any, infer RPC> | WorkerRef<infer RPC>
+// NOTE: AiSearch / AiSearchNamespace MUST come FIRST in this conditional
+// chain, before any structural discriminator like `{ type: "kv_namespace" }`.
+// `AiSearch.type` is the data-source type (`"r2" | "web-crawler"`), NOT a
+// binding-type discriminator — so we match by *resource-type import* via the
+// `_AiSearch` / `_AiSearchNamespace` aliases (underscore-prefixed to avoid
+// colliding with the identically-named Cloudflare runtime classes on the
+// right-hand side of the conditional).
+export type Bound<T extends Binding> = T extends _AiSearch
+  ? AiSearchInstance
+  : T extends _AiSearchNamespace
+    ? AiSearchNamespace
+    : T extends _DurableObjectNamespace<infer O>
+      ? DurableObjectNamespace<O & Rpc.DurableObjectBranded>
+      : T extends { type: "kv_namespace" }
+        ? KVNamespace
+        : T extends WorkerStub<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
-                                                ? Fetcher
-                                                : 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
-                                                                >
-                                                              ? DurableObjectNamespace<
-                                                                  Obj &
-                                                                    Rpc.DurableObjectBranded
+          : 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
+                                                  ? Fetcher
+                                                  : 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 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/container.ts

@@ -1,30 +1,35 @@
 import type { Context } from "../context.ts";
-import { Image, type ImageProps } from "../docker/image.ts";
+import { DockerApi } from "../docker/api.ts";
+import {
+  Image,
+  type DockerBuildOptions,
+  type ImageProps,
+} from "../docker/image.ts";
+import type { RemoteImage } from "../docker/remote-image.ts";
 import { Resource } from "../resource.ts";
 import { Scope } from "../scope.ts";
 import { secret } from "../secret.ts";
 import {
+  createCloudflareApi,
   type CloudflareApi,
   type CloudflareApiOptions,
-  createCloudflareApi,
 } from "./api.ts";
 
 /**
- * Properties for creating a Container binding or ContainerApplication
- *
- * Extends ImageProps for Docker image configuration and CloudflareApiOptions
- * for Cloudflare API authentication.
+ * Common properties shared between build and image container configurations
  */
-export interface ContainerProps
-  extends
-    Omit<ImageProps, "registry" | "skipPush">,
-    Partial<CloudflareApiOptions> {
+interface ContainerPropsBase extends Partial<CloudflareApiOptions> {
   /**
    * The class name for the container binding.
    * This is used to identify the container class in Worker bindings.
    */
   className: string;
 
+  /**
+   * Tag for the image (e.g., "latest")
+   */
+  tag?: string;
+
   /**
    * Maximum number of container instances that can be running.
    * Controls horizontal scaling limits.
@@ -92,6 +97,75 @@ export interface ContainerProps
   rollout?: ContainerApplicationRollout;
 }
 
+/**
+ * Container configuration using an existing image reference
+ */
+interface ContainerPropsWithImage extends ContainerPropsBase {
+  /**
+   * Name for the container application.
+   *
+   * @default ${app}-${stage}-${id}
+   */
+  name?: string;
+
+  /**
+   * Image name or reference (e.g., "nginx:alpine")
+   *
+   * Use this when you want to deploy an existing image rather than building one.
+   * Cannot be used together with `build`.
+   */
+  image: string | Image | RemoteImage;
+
+  build?: never;
+}
+
+/**
+ * Container configuration that builds a Docker image
+ */
+interface ContainerPropsWithBuild extends ContainerPropsBase {
+  /**
+   * Name for the container application and image repository.
+   *
+   * @default ${app}-${stage}-${id}
+   */
+  name?: string;
+
+  /**
+   * Build configuration for the Docker image.
+   *
+   * Use this when you want to build an image from a Dockerfile.
+   * Cannot be used together with `image`.
+   */
+  build: DockerBuildOptions;
+
+  image?: never;
+}
+
+/**
+ * Properties for creating a Container binding or ContainerApplication
+ *
+ * Either provide `image` to use an existing image, or `build` to build from a Dockerfile.
+ * These options are mutually exclusive.
+ *
+ * @example
+ * // Using an existing image
+ * const container = await Container("my-container", {
+ *   className: "MyContainer",
+ *   image: "nginx:alpine"
+ * });
+ *
+ * @example
+ * // Building from a Dockerfile
+ * const container = await Container("my-container", {
+ *   className: "MyContainer",
+ *   build: {
+ *     context: "./app",
+ *     dockerfile: "Dockerfile"
+ *   }
+ * });
+ */
+export type ContainerProps = ContainerPropsWithImage | ContainerPropsWithBuild;
+
 /**
  * Instance types for Cloudflare Container deployments.
  *
@@ -202,10 +276,60 @@ export type Container<T = any> = {
   __phantom?: T;
 };
 
+/**
+ * Normalize an image reference for Cloudflare Container deployments.
+ *
+ * Follows wrangler's resolveImageName logic:
+ * - Short names like "myapp:v1" → "registry.cloudflare.com/{accountId}/myapp:v1"
+ * - CF registry without accountId like "registry.cloudflare.com/myapp:v1" → adds accountId
+ * - External registries like "docker.io/nginx:1.25" → pass through unchanged
+ */
+export function resolveImageName(accountId: string, image: string): string {
+  const cfRegistry = getCloudflareContainerRegistry();
+
+  // Check if image has a registry prefix (contains a dot in the first segment)
+  const segments = image.split("/");
+  const hasRegistryPrefix = segments.length > 1 && segments[0].includes(".");
+
+  if (!hasRegistryPrefix) {
+    // Short name like "myapp:v1" → add CF registry + accountId
+    return `${cfRegistry}/${accountId}/${image}`;
+  }
+
+  if (image.startsWith(`${cfRegistry}/`)) {
+    // CF registry image - check if accountId is present
+    const afterRegistry = image.slice(`${cfRegistry}/`.length);
+    const segments = afterRegistry.split("/");
+
+    // If only one segment (e.g., "myapp:tag"), add accountId
+    // If first segment doesn't look like an accountId (32 hex chars), add it
+    if (segments.length === 1) {
+      return `${cfRegistry}/${accountId}/${afterRegistry}`;
+    }
+
+    // Check if first segment is the accountId (32 hex chars)
+    const possibleAccountId = segments[0];
+    const isAccountId = /^[a-f0-9]{32}$/.test(possibleAccountId);
+
+    if (!isAccountId) {
+      // First segment is not an accountId, prepend it
+      return `${cfRegistry}/${accountId}/${afterRegistry}`;
+    }
+  }
+
+  // External registry or already fully-qualified CF registry → pass through
+  return image;
+}
+
 export async function Container<T>(
   id: string,
   props: ContainerProps,
 ): Promise<Container<T>> {
+  // Validate that build and image are mutually exclusive
+  if (props.build && props.image) {
+    throw new Error("Container: specify either `build` or `image`, not both.");
+  }
+
   const scope = Scope.current;
   const name = props.name ?? scope.createPhysicalName(id);
   const tag =
@@ -230,6 +354,100 @@ export async function Container<T>(
   };
 
   const isDev = scope.local && !props.dev?.remote;
+
+  // Prebuilt image path: use as-is, no Docker pull/push
+  // This matches wrangler's behavior where registry URIs are passed directly
+  // to the Cloudflare API without any local Docker operations
+  if (props.image && !props.build) {
+    const rawImageRef =
+      typeof props.image === "string" ? props.image : props.image.imageRef;
+
+    if (isDev) {
+      // For local dev with prebuilt images, we need to pull and re-tag
+      const dockerApi = new DockerApi();
+      const devImageRef = `cloudflare-dev/${name}:${tag}`;
+
+      if (isCloudflareRegistryLink(rawImageRef)) {
+        // For CF registry images, authenticate before pulling
+        const api = await createCloudflareApi(props);
+        const credentials = await getContainerCredentials(api);
+        const cfRegistry = getCloudflareContainerRegistry();
+
+        await dockerApi.login(
+          cfRegistry,
+          credentials.username || credentials.user!,
+          credentials.password,
+        );
+
+        try {
+          // CF Containers run on linux/amd64, so we need to pull that platform
+          await dockerApi.pullImage(rawImageRef, { platform: "linux/amd64" });
+          await dockerApi.tagImage(rawImageRef, devImageRef);
+        } finally {
+          await dockerApi.logout(cfRegistry);
+        }
+
+        return {
+          ...output,
+          image: {
+            kind: "Image",
+            name: `cloudflare-dev/${name}`,
+            imageRef: devImageRef,
+            tag,
+            builtAt: Date.now(),
+            build: undefined,
+          },
+        };
+      }
+
+      // For external registry images in dev mode, pull and re-tag for Miniflare
+      const image = await Image(id, {
+        image: props.image,
+        tag,
+      });
+
+      await dockerApi.tagImage(image.imageRef, devImageRef);
+
+      return {
+        ...output,
+        image: {
+          ...image,
+          name: `cloudflare-dev/${name}`,
+          imageRef: devImageRef,
+        },
+      };
+    }
+
+    // Non-dev mode: normalize the image reference and use directly
+    const api = await createCloudflareApi(props);
+    const imageRef = resolveImageName(api.accountId, rawImageRef);
+
+    // Extract name and tag from the resolved reference
+    const [refWithoutDigest] = imageRef.split("@");
+    const lastColonIndex = refWithoutDigest.lastIndexOf(":");
+    const namePart =
+      lastColonIndex > -1
+        ? refWithoutDigest.slice(0, lastColonIndex)
+        : refWithoutDigest;
+    const tagPart =
+      lastColonIndex > -1 ? refWithoutDigest.slice(lastColonIndex + 1) : tag;
+
+    const image: Image = {
+      kind: "Image",
+      name: namePart,
+      imageRef,
+      tag: tagPart,
+      builtAt: Date.now(),
+      build: undefined,
+    };
+
+    return {
+      ...output,
+      image,
+    };
+  }
+
+  // Build path: build locally and push to Cloudflare registry
   if (isDev) {
     const image = await Image(id, {
       ...props,
@@ -264,7 +482,6 @@ export async function Container<T>(
           platform: "linux/amd64",
           context: process.cwd(),
         },
-    image: props.image,
     registry: {
       server: "registry.cloudflare.com",
       username: credentials.username || credentials.user!,

package/src/cloudflare/index.ts

@@ -4,6 +4,7 @@ export * from "./account-api-token.ts";
 export * from "./account-id.ts";
 export * from "./ai-crawler.ts";
 export * from "./ai-gateway.ts";
+export * from "./ai-search-namespace.ts";
 export * from "./ai-search-token.ts";
 export * from "./ai-search.ts";
 export * from "./ai.ts";

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

@@ -4,6 +4,8 @@ import { assertNever } from "../../util/assert-never.ts";
 import { reservePort } from "../../util/find-open-port.ts";
 import type { HTTPServer } from "../../util/http.ts";
 import { logger } from "../../util/logger.ts";
+import { isAiSearchNamespace } from "../ai-search-namespace.ts";
+import { isAiSearch } from "../ai-search.ts";
 import type { CloudflareApi } from "../api.ts";
 import type {
   Binding,
@@ -38,6 +40,8 @@ type RemoteBinding =
       {
         type:
           | "ai"
+          | "ai_search"
+          | "ai_search_namespace"
           | "browser"
           | "dispatch_namespace"
           | "mtls_certificate"
@@ -90,6 +94,29 @@ export const buildWorkerOptions = async (
       (options.bindings ??= {})[key] = binding;
       continue;
     }
+    if (isAiSearch(binding)) {
+      // AI Search instance bindings are not supported natively by Miniflare;
+      // proxy them to the deployed instance (same mechanism used by `ai`,
+      // `vectorize`, etc.). Instance bindings are always scoped to the
+      // default namespace on the CF side, so the namespace need not be
+      // surfaced in the remote-proxy metadata.
+      remoteBindings.push({
+        type: "ai_search",
+        name: key,
+        instance_name: binding.name,
+        raw: true,
+      });
+      continue;
+    }
+    if (isAiSearchNamespace(binding)) {
+      remoteBindings.push({
+        type: "ai_search_namespace",
+        name: key,
+        namespace: binding.namespace,
+        raw: true,
+      });
+      continue;
+    }
     if (binding.type === "cloudflare::Worker::Self") {
       (options.serviceBindings ??= {})[key] = miniflare.kCurrentWorker;
       continue;
@@ -527,6 +554,18 @@ export const buildWorkerOptions = async (
             remoteProxyConnectionString: remoteProxy.connectionString,
           };
           break;
+        case "ai_search":
+          (options.aiSearchInstances ??= {})[binding.name] = {
+            instance_name: binding.instance_name,
+            remoteProxyConnectionString: remoteProxy.connectionString,
+          };
+          break;
+        case "ai_search_namespace":
+          (options.aiSearchNamespaces ??= {})[binding.name] = {
+            namespace: binding.namespace,
+            remoteProxyConnectionString: remoteProxy.connectionString,
+          };
+          break;
         default: {
           assertNever(binding);
         }

package/src/cloudflare/worker-metadata.ts

@@ -2,6 +2,8 @@ import { assertNever } from "../util/assert-never.ts";
 import { camelToSnakeObjectDeep } from "../util/camel-to-snake.ts";
 import { logger } from "../util/logger.ts";
 import { memoize } from "../util/memoize.ts";
+import { isAiSearchNamespace } from "./ai-search-namespace.ts";
+import { isAiSearch } from "./ai-search.ts";
 import { extractCloudflareResult } from "./api-response.ts";
 import type { CloudflareApi } from "./api.ts";
 import type {
@@ -418,7 +420,29 @@ export async function prepareWorkerMetadata(
   for (const [bindingName, binding] of Object.entries(bindings)) {
     // Create a copy of the binding to avoid modifying the original
 
-    if (typeof binding === "string") {
+    if (isAiSearch(binding)) {
+      // Single-instance bindings (ai_search) are always scoped to the `default` namespace.
+      if (binding.namespace !== undefined && binding.namespace !== "default") {
+        throw new Error(
+          `Worker binding "${bindingName}" uses a single-instance AiSearch binding (type: "ai_search"), ` +
+            `but the bound AiSearch instance "${binding.name}" is in namespace "${binding.namespace}". ` +
+            `Single-instance bindings only support the "default" namespace.\n` +
+            `Fix: either (1) create the AiSearch without a custom namespace, or ` +
+            `(2) bind the enclosing AiSearchNamespace and use \`env.${bindingName}.get("${binding.name}")\`.`,
+        );
+      }
+      meta.bindings.push({
+        type: "ai_search",
+        name: bindingName,
+        instance_name: binding.name,
+      });
+    } else if (isAiSearchNamespace(binding)) {
+      meta.bindings.push({
+        type: "ai_search_namespace",
+        name: bindingName,
+        namespace: binding.namespace,
+      });
+    } else if (typeof binding === "string") {
       meta.bindings.push({
         type: "plain_text",
         name: bindingName,