alchemy 0.4.0 → 0.5.0

package/lib/cloudflare/worker.js

@@ -1,11 +1,13 @@
+import * as crypto from "crypto";
 import * as fs from "fs/promises";
 import { Bundle } 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 { createCloudflareApi } from "./api";
-import { isDurableObjectNamespace, } from "./bindings";
+import { isAssets, isDurableObjectNamespace, } from "./bindings";
 import { isKVNamespace } from "./kv-namespace";
 /**
  * A Cloudflare Worker is a serverless function that can be deployed to the Cloudflare network.
@@ -68,6 +70,20 @@ import { isKVNamespace } from "./kv-namespace";
  *   }
  * });
  *
+ * @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("cloudflare::Worker", {
@@ -86,12 +102,33 @@ export const Worker = Resource("cloudflare::Worker", {
         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");
-    const scriptMetadata = await prepareWorkerMetadata(this, oldBindings, props);
     // Get the script content - either from props.script, or by bundling
     const scriptContent = props.script ?? (await bundleWorkerScript(props));
+    // Find any assets bindings
+    const assetsBindings = [];
+    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;
+    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, assetUploadResult);
     // Upload the worker script
     await putWorker(api, workerName, scriptContent, scriptMetadata);
     // TODO: it is less than ideal that this can fail, resulting in state problem
@@ -206,7 +243,7 @@ class NotFoundError extends Error {
         this.name = "NotFoundError";
     }
 }
-async function prepareWorkerMetadata(ctx, oldBindings, props) {
+async function prepareWorkerMetadata(ctx, oldBindings, props, assetUploadResult) {
     // Prepare metadata with bindings
     const meta = {
         bindings: [],
@@ -223,6 +260,15 @@ async function prepareWorkerMetadata(ctx, oldBindings, props) {
             new_sqlite_classes: props.migrations?.new_sqlite_classes ?? [],
         },
     };
+    // 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 ?? {});
     // Convert bindings to the format expected by the API
     for (const [bindingName, binding] of Object.entries(bindings)) {
@@ -284,6 +330,12 @@ async function prepareWorkerMetadata(ctx, oldBindings, props) {
                 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",
@@ -468,3 +520,100 @@ async function getWorkerBindings(api, workerName, environment = "production") {
     const data = await response.json();
     return data.result;
 }
+/**
+ * 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, workerName, assets) {
+    // Generate the file manifest
+    const 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());
+    // 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());
+        // 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) {
+    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/lib/internal/docs/providers.js

@@ -55,6 +55,7 @@ async function generateProviderDocs({ provider, outDir, parallel, }) {
                 reasoningEffort: "high",
             },
         },
+        freeze: true,
         temperature: 0.1,
         schema: type({
             groups: type({
@@ -81,7 +82,7 @@ async function generateProviderDocs({ provider, outDir, parallel, }) {
       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/lib/os/exec.d.ts

@@ -0,0 +1,103 @@
+import type { Context } from "../context";
+import { Resource } from "../resource";
+/**
+ * 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 declare const Exec: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<Exec>, id: string, props: ExecProps) => Promise<Exec>);

package/lib/os/exec.js

@@ -0,0 +1,103 @@
+import { exec } from "child_process";
+import { promisify } from "util";
+import { Resource } from "../resource";
+const execAsync = promisify(exec);
+/**
+ * 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 (id, props) {
+    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) {
+            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/lib/os/index.d.ts

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

package/lib/os/index.js

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

package/lib/secret.d.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
  * });
  * ```
@@ -49,7 +49,7 @@ export declare 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/lib/secret.js

@@ -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
  * });
  * ```
@@ -54,7 +54,7 @@ export function isSecret(binding) {
  *
  * @example
  * // Global password for all secrets
- * const app = alchemy("my-app", {
+ * const app = await alchemy("my-app", {
  *   password: process.env.SECRET_PASSPHRASE
  * });
  *

package/lib/web/vitepress/vitepress.js

@@ -76,7 +76,7 @@ export const VitepressProject = Resource("project::VitepressProject", {
         // import { Folder } from "alchemy/fs";
         // 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alchemy",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "module": "./lib/index.js",
   "scripts": {
@@ -18,6 +18,7 @@
     "./esbuild": "./lib/esbuild/index.js",
     "./fs": "./lib/fs/index.js",
     "./github": "./lib/github/index.js",
+    "./os": "./lib/os/index.js",
     "./shadcn": "./lib/shadcn/index.js",
     "./stripe": "./lib/stripe/index.js",
     "./test/bun": "./lib/test/bun.js",

package/src/ai/data.ts

@@ -63,6 +63,12 @@ export interface DataProps<T extends Type<any, any>> {
    * Model configuration
    */
   model?: ModelConfig;
+
+  /**
+   * Whether to freeze the generated object
+   * @default false
+   */
+  freeze?: boolean;
 }
 
 /**
@@ -171,6 +177,10 @@ export const Data = Resource("ai::Object", async function <
     throw new Error("Either prompt or messages must be provided");
   }
 
+  if (this.phase === "update" && props.freeze) {
+    return this(this.output);
+  }
+
   // Create messages array if only prompt is provided
   const messages = props.messages || [{ role: "user", content: props.prompt! }];