alchemy 0.4.0 → 0.5.0

package/src/cloudflare/worker.ts

@@ -1,14 +1,18 @@
+import * as crypto from "crypto";
 import * as fs from "fs/promises";
 import type { Context } from "../context";
 import { Bundle, type BundleProps } from "../esbuild/bundle";
 import { Resource } from "../resource";
 import { isSecret } from "../secret";
+import { getContentType } from "../util/content-type";
 import { withExponentialBackoff } from "../util/retry";
 import { slugify } from "../util/slugify";
 import { type CloudflareApi, createCloudflareApi } from "./api";
+import type { Assets } from "./assets";
 import {
   type Bindings,
   type WorkerBindingSpec,
+  isAssets,
   isDurableObjectNamespace,
 } from "./bindings";
 import type { Bound } from "./bound";
@@ -97,6 +101,11 @@ export interface WorkerProps<B extends Bindings = Bindings> {
    * Migrations to apply to the worker
    */
   migrations?: SingleStepMigration;
+
+  /**
+   * Whether to adopt the Worker if it already exists when creating
+   */
+  adopt?: boolean;
 }
 
 /**
@@ -200,6 +209,20 @@ export interface Worker<B extends Bindings = Bindings>
  *   }
  * });
  *
+ * @example
+ * // Create a worker with static assets:
+ * const staticAssets = await Assets("static", {
+ *   path: "./src/assets"
+ * });
+ *
+ * const frontendWorker = await Worker("frontend", {
+ *   name: "frontend-worker",
+ *   entrypoint: "./src/worker.ts",
+ *   bindings: {
+ *     ASSETS: staticAssets
+ *   }
+ * });
+ *
  * @see https://developers.cloudflare.com/workers/
  */
 export const Worker = Resource(
@@ -227,20 +250,49 @@ export const Worker = Resource(
       await deleteWorker(this, api, workerName);
       return this.destroy();
     } else if (this.phase === "create") {
-      await assertWorkerDoesNotExist(this, api, workerName);
+      if (!props.adopt) {
+        await assertWorkerDoesNotExist(this, api, workerName);
+      }
     }
 
     const oldBindings = await this.get<Bindings>("bindings");
 
+    // Get the script content - either from props.script, or by bundling
+    const scriptContent = props.script ?? (await bundleWorkerScript(props));
+
+    // Find any assets bindings
+    const assetsBindings: { name: string; assets: Assets }[] = [];
+    if (props.bindings) {
+      for (const [bindingName, binding] of Object.entries(props.bindings)) {
+        if (isAssets(binding)) {
+          assetsBindings.push({ name: bindingName, assets: binding });
+        }
+      }
+    }
+
+    // Upload any assets and get completion tokens
+    let assetUploadResult: AssetUploadResult | undefined;
+    if (assetsBindings.length > 0) {
+      // We'll use the first asset binding for now
+      // In the future, we might want to support multiple asset bindings
+      const assetBinding = assetsBindings[0];
+
+      // Upload the assets and get the completion token
+      assetUploadResult = await uploadAssets(
+        api,
+        workerName,
+        assetBinding.assets
+      );
+    }
+
+    // Prepare metadata with bindings
     const scriptMetadata = await prepareWorkerMetadata(
       this,
       oldBindings,
-      props
+      props,
+      assetUploadResult
     );
 
-    // Get the script content - either from props.script, or by bundling
-    const scriptContent = props.script ?? (await bundleWorkerScript(props));
-
     // Upload the worker script
     await putWorker(api, workerName, scriptContent, scriptMetadata);
 
@@ -437,12 +489,29 @@ interface WorkerMetadata {
   main_module?: string;
   body_part?: string;
   tags?: string[];
+  assets?: {
+    jwt?: string;
+    keep_assets?: boolean;
+    config?: {
+      html_handling?: "auto-trailing-slash" | "none";
+      not_found_handling?: "none" | "fall-through";
+    };
+  };
+}
+
+interface AssetUploadResult {
+  completionToken: string;
+  assetConfig?: {
+    html_handling?: "auto-trailing-slash" | "none";
+    not_found_handling?: "none" | "fall-through";
+  };
 }
 
 async function prepareWorkerMetadata<B extends Bindings>(
   ctx: Context<Worker<B>>,
   oldBindings: Bindings | undefined,
-  props: WorkerProps
+  props: WorkerProps,
+  assetUploadResult?: AssetUploadResult
 ): Promise<WorkerMetadata> {
   // Prepare metadata with bindings
   const meta: WorkerMetadata = {
@@ -461,6 +530,17 @@ async function prepareWorkerMetadata<B extends Bindings>(
     },
   };
 
+  // If we have asset upload results, add them to the metadata
+  if (assetUploadResult) {
+    meta.assets = {
+      jwt: assetUploadResult.completionToken,
+    };
+
+    if (assetUploadResult.assetConfig) {
+      meta.assets.config = assetUploadResult.assetConfig;
+    }
+  }
+
   const bindings = (props.bindings ?? {}) as Bindings;
 
   // Convert bindings to the format expected by the API
@@ -522,6 +602,11 @@ async function prepareWorkerMetadata<B extends Bindings>(
         name: bindingName,
         bucket_name: binding.name,
       });
+    } else if (isAssets(binding)) {
+      meta.bindings.push({
+        type: "assets",
+        name: bindingName,
+      });
     } else if (isSecret(binding)) {
       meta.bindings.push({
         type: "secret_text",
@@ -802,3 +887,173 @@ async function getWorkerBindings(
 
   return data.result;
 }
+
+/**
+ * Interface for a file's metadata to be uploaded
+ */
+interface FileMetadata {
+  hash: string;
+  size: number;
+}
+
+/**
+ * Response from the assets upload session API
+ */
+interface UploadSessionResponse {
+  result: {
+    jwt: string;
+    buckets: string[][];
+  };
+  success: boolean;
+  errors: any[];
+  messages: any[];
+}
+
+/**
+ * Response from the file upload API
+ */
+interface UploadResponse {
+  result: {
+    jwt: string;
+    buckets?: string[][];
+  };
+  success: boolean;
+  errors: any[];
+  messages: any[];
+}
+
+/**
+ * Uploads assets to Cloudflare and returns a completion token
+ *
+ * @param api CloudflareApi instance
+ * @param workerName Name of the worker
+ * @param assets Assets resource containing files to upload
+ * @returns Completion token for the assets upload
+ */
+async function uploadAssets(
+  api: CloudflareApi,
+  workerName: string,
+  assets: Assets
+): Promise<AssetUploadResult> {
+  // Generate the file manifest
+  const fileMetadata: Record<string, FileMetadata> = {};
+
+  // Process each file in the assets
+  for (const file of assets.files) {
+    const { hash, size } = await calculateFileMetadata(file.filePath);
+    // Use the relative path as the key, ensuring it starts with a slash
+    const key = file.path.startsWith("/") ? file.path : `/${file.path}`;
+    fileMetadata[key] = { hash, size };
+  }
+
+  // Start the upload session
+  const uploadSessionUrl = `/accounts/${api.accountId}/workers/scripts/${workerName}/assets-upload-session`;
+  const uploadSessionResponse = await api.post(
+    uploadSessionUrl,
+    JSON.stringify({ manifest: fileMetadata }),
+    {
+      headers: { "Content-Type": "application/json" },
+    }
+  );
+
+  if (!uploadSessionResponse.ok) {
+    throw new Error(
+      `Failed to start assets upload session: ${uploadSessionResponse.status} ${uploadSessionResponse.statusText}`
+    );
+  }
+
+  const sessionData =
+    (await uploadSessionResponse.json()) as UploadSessionResponse;
+
+  // If there are no buckets, assets are already uploaded or empty
+  if (!sessionData.result.buckets || sessionData.result.buckets.length === 0) {
+    return { completionToken: sessionData.result.jwt };
+  }
+
+  // Upload the files in batches as specified by the API
+  let completionToken = sessionData.result.jwt;
+  const buckets = sessionData.result.buckets;
+
+  // Process each bucket of files
+  for (const bucket of buckets) {
+    const formData = new FormData();
+
+    // Add each file in the bucket to the form
+    for (const fileHash of bucket) {
+      // Find the file with this hash
+      const file = assets.files.find((f) => {
+        const filePath = f.path.startsWith("/") ? f.path : `/${f.path}`;
+        return fileMetadata[filePath]?.hash === fileHash;
+      });
+
+      if (!file) {
+        throw new Error(`Could not find file with hash ${fileHash}`);
+      }
+
+      // Read the file content
+      const fileContent = await fs.readFile(file.filePath);
+
+      // Convert to base64 as required by the API when using base64=true
+      const base64Content = fileContent.toString("base64");
+
+      // Add the file to the form with the hash as the key and set the correct content type
+      const blob = new Blob([base64Content], {
+        type: getContentType(file.filePath),
+      });
+      formData.append(fileHash, blob, fileHash);
+    }
+
+    // Upload this batch of files
+    const uploadResponse = await api.post(
+      `/accounts/${api.accountId}/workers/assets/upload?base64=true`,
+      formData,
+      {
+        headers: {
+          Authorization: `Bearer ${completionToken}`,
+          "Content-Type": "multipart/form-data",
+        },
+      }
+    );
+
+    if (!uploadResponse.ok) {
+      throw new Error(
+        `Failed to upload asset files: ${uploadResponse.status} ${uploadResponse.statusText}`
+      );
+    }
+
+    const uploadData = (await uploadResponse.json()) as UploadResponse;
+    // Update the completion token for the next batch
+    if (uploadData.result.jwt) {
+      completionToken = uploadData.result.jwt;
+    }
+  }
+
+  // Return the final completion token
+  return {
+    completionToken,
+    assetConfig: {
+      html_handling: "auto-trailing-slash",
+    },
+  };
+}
+
+/**
+ * Calculate the SHA-256 hash and size of a file
+ *
+ * @param filePath Path to the file
+ * @returns Hash (first 32 chars of SHA-256) and size of the file
+ */
+async function calculateFileMetadata(
+  filePath: string
+): Promise<{ hash: string; size: number }> {
+  const hash = crypto.createHash("sha256");
+  const fileContent = await fs.readFile(filePath);
+
+  hash.update(fileContent);
+  const fileHash = hash.digest("hex").substring(0, 32); // First 32 chars of hash
+
+  return {
+    hash: fileHash,
+    size: fileContent.length,
+  };
+}

package/src/internal/docs/providers.ts

@@ -124,6 +124,7 @@ async function generateProviderDocs({
         reasoningEffort: "high",
       },
     },
+    freeze: true,
     temperature: 0.1,
     schema: type({
       groups: type({
@@ -156,7 +157,7 @@ async function generateProviderDocs({
       A file is considered a "Utility" if it contains utility functions that are not resources or clients.
       A file is considered a "Types" if it contains just type definitions and maybe helpers around working with those types.
 
-      The title should be simply the name of the resource's const in code (with spaces added in between each word), e.g. "Bucket" or "Function", except with spaces, e.g. "Static Site" for "const StaticSite". Maintain all other casing.
+      The title should be simply the name of the resource's const in code (with spaces added in between each word), e.g. "Bucket" or "Function", except with spaces, e.g. "StaticSite" for "const StaticSite". Maintain all other casing.
 
       // "Resource Name"
       const ResourceName = Resource(...)

package/src/os/exec.ts

@@ -0,0 +1,190 @@
+import { exec } from "child_process";
+import { promisify } from "util";
+import type { Context } from "../context";
+import { Resource } from "../resource";
+
+const execAsync = promisify(exec);
+
+/**
+ * Properties for executing a shell command
+ */
+export interface ExecProps {
+  /**
+   * The command to execute (including any arguments)
+   */
+  command: string;
+
+  /**
+   * Whether to memoize the command (only re-run if the command changes)
+   *
+   * @default false
+   */
+  memoize?: boolean;
+
+  /**
+   * Working directory for the command
+   */
+  cwd?: string;
+
+  /**
+   * Environment variables to set
+   */
+  env?: Record<string, string>;
+
+  /**
+   * Maximum buffer size for stdout and stderr (in bytes)
+   * @default 1024 * 1024 (1MB)
+   */
+  maxBuffer?: number;
+
+  /**
+   * Whether to throw an error if the command exits with a non-zero status
+   */
+  throwOnError?: boolean;
+}
+
+/**
+ * Output returned after command execution
+ */
+export interface Exec extends Resource<"os::Exec">, ExecProps {
+  /**
+   * Unique identifier for this execution
+   */
+  id: string;
+
+  /**
+   * Exit code of the command
+   */
+  exitCode: number;
+
+  /**
+   * Standard output from the command
+   */
+  stdout: string;
+
+  /**
+   * Standard error from the command
+   */
+  stderr: string;
+
+  /**
+   * Time at which the command was executed
+   */
+  executedAt: number;
+
+  /**
+   * Whether the command has completed execution
+   */
+  completed: boolean;
+}
+
+/**
+ * Execute a shell command
+ *
+ * @example
+ * // Run a simple command
+ * const result = await Exec("list-files", {
+ *   command: "ls -la"
+ * });
+ *
+ * console.log(result.stdout);
+ *
+ * @example
+ * // Run a command in a specific directory with custom environment
+ * const build = await Exec("build-project", {
+ *   command: "npm run build",
+ *   cwd: "./my-project",
+ *   env: { NODE_ENV: "production" }
+ * });
+ *
+ * @example
+ * // Run a command with a larger buffer for output
+ * const logs = await Exec("get-logs", {
+ *   command: "cat large-log-file.log",
+ *   maxBuffer: 10 * 1024 * 1024 // 10MB
+ * });
+ *
+ * @example
+ * // Run a memoized command that only re-executes when the command changes
+ * const memoizedCmd = await Exec("status-check", {
+ *   command: "git status",
+ *   memoize: true
+ * });
+ *
+ * // This won't actually run the command again if nothing has changed
+ * await Exec("status-check", {
+ *   command: "git status",
+ *   memoize: true
+ * });
+ */
+export const Exec = Resource(
+  "os::Exec",
+  {
+    alwaysUpdate: true,
+  },
+  async function (
+    this: Context<Exec>,
+    id: string,
+    props: ExecProps
+  ): Promise<Exec> {
+    if (this.phase === "delete") {
+      // Nothing to actually delete for an exec command
+      return this.destroy();
+    } else if (
+      this.phase === "update" &&
+      props.memoize &&
+      this.output?.command === props.command
+    ) {
+      // If memoize is enabled and the command hasn't changed, return the existing output
+      return this.output;
+    } else {
+      // Default values
+      let stdout = "";
+      let stderr = "";
+      let exitCode = 0;
+
+      try {
+        console.log(props.command);
+        // Execute the command
+        const result = await execAsync(props.command, {
+          cwd: props.cwd || process.cwd(),
+          env: { ...process.env, ...props.env },
+          maxBuffer: props.maxBuffer || 1024 * 1024, // Default 1MB
+        });
+
+        stdout = result.stdout;
+        console.log(stdout);
+        stderr = result.stderr;
+        exitCode = 0; // Success
+      } catch (error: any) {
+        console.log("error", error);
+        if (props.throwOnError) {
+          throw error;
+        }
+
+        // If not throwing, capture the error information
+        exitCode = error.code || 1;
+        stdout = error.stdout || "";
+        stderr = error.stderr || String(error);
+        console.log(stdout);
+        console.error(stderr);
+      }
+
+      // Return the execution result
+      return this({
+        id,
+        command: props.command,
+        cwd: props.cwd,
+        env: props.env,
+        maxBuffer: props.maxBuffer,
+        throwOnError: props.throwOnError,
+        memoize: props.memoize,
+        exitCode,
+        stdout,
+        stderr,
+        executedAt: Date.now(),
+        completed: true,
+      });
+    }
+  }
+);

package/src/os/index.ts

@@ -0,0 +1 @@
+export * from "./exec";

package/src/secret.ts

@@ -5,7 +5,7 @@
  *
  * 1. Globally when initializing the alchemy application:
  * ```ts
- * const app = alchemy("my-app", {
+ * const app = await alchemy("my-app", {
  *   password: process.env.SECRET_PASSPHRASE
  * });
  * ```
@@ -55,7 +55,7 @@ export function isSecret(binding: any): binding is Secret {
  *
  * @example
  * // Global password for all secrets
- * const app = alchemy("my-app", {
+ * const app = await alchemy("my-app", {
  *   password: process.env.SECRET_PASSPHRASE
  * });
  *

package/src/web/vitepress/vitepress.ts

@@ -190,7 +190,7 @@ export const VitepressProject = Resource(
       // import { Document } from "alchemy/docs";
       // import path from "path";
 
-      // await using _ = alchemy("alchemy.run", {
+      // const app = await alchemy("alchemy.run", {
       //   stage: "prod",
       //   phase: process.argv.includes("--destroy") ? "destroy" : "up",
       //   password: process.env.SECRET_PASSPHRASE,

package/lib/cloudflare/generate-asset-manifest.d.ts

@@ -1,2 +0,0 @@
-import type { AssetManifest, FileOption } from "./asset-manifest";
-export declare function generateAssetManifest(dir: string, fileOptions?: FileOption[]): Promise<AssetManifest>;

package/lib/cloudflare/generate-asset-manifest.js

@@ -1,68 +0,0 @@
-import crypto from "crypto";
-import { promises as fs } from "fs";
-import { glob } from "glob";
-import path from "path";
-import { getContentType } from "../util/content-type";
-export async function generateAssetManifest(dir, fileOptions = [
-    {
-        files: "**",
-        cacheControl: "max-age=0,no-cache,no-store,must-revalidate",
-    },
-    {
-        files: ["**/*.js", "**/*.css", "**/*.png", "**/*.webp"],
-        cacheControl: "max-age=31536000,public,immutable",
-    },
-]) {
-    // First, collect all file info based on fileOptions (reversed to prioritize later rules)
-    const fileInfos = [];
-    const filesProcessed = new Set();
-    // Process file options in reverse order (later rules override earlier ones)
-    // Use for...of to maintain order but allow await inside the loop
-    const reversedOptions = [...fileOptions].reverse();
-    for (const fileOption of reversedOptions) {
-        const patterns = Array.isArray(fileOption.files)
-            ? fileOption.files
-            : [fileOption.files];
-        // Get all files matching the pattern
-        const files = (await Promise.all(patterns.map(async (p) => {
-            // Use glob as async function instead of globSync
-            return glob(p, {
-                cwd: path.resolve(dir),
-                nodir: true,
-                dot: true,
-                ignore: [
-                    ".git/**",
-                    "node_modules/**",
-                    ...(typeof fileOption.ignore === "string"
-                        ? [fileOption.ignore]
-                        : (fileOption.ignore ?? [])),
-                ],
-            });
-        })))
-            .flat()
-            .filter((file) => !filesProcessed.has(file));
-        // Add files to processed set
-        for (const file of files) {
-            filesProcessed.add(file);
-            fileInfos.push({
-                file,
-                cacheControl: fileOption.cacheControl,
-                contentType: fileOption.contentType,
-            });
-        }
-    }
-    // Process all files in parallel
-    const manifestEntries = await Promise.all(fileInfos.map(async ({ file, cacheControl, contentType }) => {
-        const source = path.resolve(dir, file);
-        const content = await fs.readFile(source);
-        const hash = crypto.createHash("sha256").update(content).digest("hex");
-        return {
-            source,
-            key: file,
-            hash,
-            cacheControl,
-            contentType: contentType ?? getContentType(file),
-        };
-    }));
-    return manifestEntries;
-}

package/lib/cloudflare/static-site-router.d.ts

@@ -1,18 +0,0 @@
-export type Env = {
-    ASSETS: KVNamespace;
-    INDEX_PAGE: string;
-    ERROR_PAGE?: string;
-    /**
-     * Optional backend worker bound to this static site
-     * Used to handle requests that don't match any static files
-     */
-    BACKEND_WORKER?: Service;
-} & {
-    [key in `ROUTE_${string}`]: Service;
-} & {
-    [key in `__ROUTE_${string}`]: string;
-};
-declare const _default: {
-    fetch(request: Request, env: Env): Promise<Response>;
-};
-export default _default;