alchemy 0.4.1 → 0.5.0

package/src/alchemy.ts

@@ -22,7 +22,7 @@ export const alchemy: Alchemy = _alchemy as any;
  *
  * @example
  * // Create an application scope with stage and secret handling
- * const app = alchemy("github:alchemy", {
+ * const app = await alchemy("github:alchemy", {
  *   stage: "prod",
  *   phase: "up",
  *   // Required for encrypting/decrypting secrets
@@ -57,13 +57,13 @@ export interface Alchemy {
    * Used to create and manage resources with proper secret handling.
    *
    * @example
-   * const app = alchemy("my-app", {
+   * const app = await alchemy("my-app", {
    *   stage: "prod",
    *   // Required for encrypting/decrypting secrets
    *   password: process.env.SECRET_PASSPHRASE
    * });
    */
-  (...parameters: Parameters<typeof scope>): ReturnType<typeof scope>;
+  (...parameters: Parameters<typeof scope>): Promise<Scope>;
   /**
    * Template literal tag that supports file interpolation for documentation.
    * Automatically formats the content and appends file contents as code blocks.
@@ -88,11 +88,11 @@ export interface Alchemy {
  * Implementation of the alchemy function that handles both application scoping
  * and template string interpolation.
  */
-function _alchemy(
+async function _alchemy(
   ...args:
     | [template: TemplateStringsArray, ...values: any[]]
     | [appName: string, options?: Omit<AlchemyOptions, "appName">]
-): any {
+): Promise<Scope | string | never> {
   if (typeof args[0] === "string") {
     const [appName, options] = args as [string, AlchemyOptions?];
     const root = scope(undefined, {
@@ -101,9 +101,8 @@ function _alchemy(
       stage: options?.stage,
     });
     if (options?.phase === "destroy") {
-      return destroy(root).finally(() => {
-        process.exit(0);
-      });
+      await destroy(root);
+      return process.exit(0);
     }
     return root;
   } else {
@@ -114,106 +113,104 @@ function _alchemy(
       : 0;
     const indent = " ".repeat(leadingSpaces);
 
-    return (async () => {
-      const { isFileCollection, isFileRef } = await import("./fs");
+    const { isFileCollection, isFileRef } = await import("./fs");
 
-      const appendices: Record<string, string> = {};
+    const appendices: Record<string, string> = {};
 
-      const stringValues = await Promise.all(
-        values.map(async function resolve(value): Promise<string> {
-          if (typeof value === "string") {
-            return indent + value;
-          } else if (value === null) {
-            return "null";
-          } else if (value === undefined) {
-            return "undefined";
-          } else if (
-            typeof value === "number" ||
-            typeof value === "boolean" ||
-            typeof value === "bigint"
-          ) {
-            return value.toString();
-          } else if (value instanceof Promise) {
-            return resolve(await value);
-          } else if (isFileRef(value)) {
-            if (!(value.path in appendices)) {
-              appendices[value.path] = await fs.readFile(value.path, "utf-8");
-            }
+    const stringValues = await Promise.all(
+      values.map(async function resolve(value): Promise<string> {
+        if (typeof value === "string") {
+          return indent + value;
+        } else if (value === null) {
+          return "null";
+        } else if (value === undefined) {
+          return "undefined";
+        } else if (
+          typeof value === "number" ||
+          typeof value === "boolean" ||
+          typeof value === "bigint"
+        ) {
+          return value.toString();
+        } else if (value instanceof Promise) {
+          return resolve(await value);
+        } else if (isFileRef(value)) {
+          if (!(value.path in appendices)) {
+            appendices[value.path] = await fs.readFile(value.path, "utf-8");
+          }
+          return `[${path.basename(value.path)}](${value.path})`;
+        } else if (isFileCollection(value)) {
+          return Object.entries(value.files)
+            .map(([filePath, content]) => {
+              appendices[filePath] = content;
+              return `[${path.basename(filePath)}](${filePath})`;
+            })
+            .join("\n\n");
+        } else if (Array.isArray(value)) {
+          return (
+            await Promise.all(
+              value.map(async (value, i) => `${i}. ${await resolve(value)}`)
+            )
+          ).join("\n");
+        } else if (
+          typeof value === "object" &&
+          typeof value.path === "string"
+        ) {
+          if (typeof value.content === "string") {
+            appendices[value.path] = value.content;
             return `[${path.basename(value.path)}](${value.path})`;
-          } else if (isFileCollection(value)) {
-            return Object.entries(value.files)
-              .map(([filePath, content]) => {
-                appendices[filePath] = content;
-                return `[${path.basename(filePath)}](${filePath})`;
-              })
-              .join("\n\n");
-          } else if (Array.isArray(value)) {
-            return (
-              await Promise.all(
-                value.map(async (value, i) => `${i}. ${await resolve(value)}`)
-              )
-            ).join("\n");
-          } else if (
-            typeof value === "object" &&
-            typeof value.path === "string"
-          ) {
-            if (typeof value.content === "string") {
-              appendices[value.path] = value.content;
-              return `[${path.basename(value.path)}](${value.path})`;
-            } else {
-              appendices[value.path] = await fs.readFile(value.path, "utf-8");
-              return `[${path.basename(value.path)}](${value.path})`;
-            }
-          } else if (typeof value === "object") {
-            return (
-              await Promise.all(
-                Object.entries(value).map(async ([key, value]) => {
-                  return `* ${key}: ${await resolve(value)}`;
-                })
-              )
-            ).join("\n");
           } else {
-            // TODO: support other types
-            console.log(value);
-            throw new Error(`Unsupported value type: ${value}`);
+            appendices[value.path] = await fs.readFile(value.path, "utf-8");
+            return `[${path.basename(value.path)}](${value.path})`;
           }
-        })
-      );
-
-      // Construct the string template by joining template parts with interpolated values
-      const lines = template
-        .map((part) =>
-          part
-            .split("\n")
-            .map((line) =>
-              line.startsWith(indent) ? line.slice(indent.length) : line
+        } else if (typeof value === "object") {
+          return (
+            await Promise.all(
+              Object.entries(value).map(async ([key, value]) => {
+                return `* ${key}: ${await resolve(value)}`;
+              })
             )
-            .join("\n")
-        )
-        .flatMap((part, i) =>
-          i < stringValues.length ? [part, stringValues[i] ?? ""] : [part]
-        )
-        .join("")
-        .split("\n");
+          ).join("\n");
+        } else {
+          // TODO: support other types
+          console.log(value);
+          throw new Error(`Unsupported value type: ${value}`);
+        }
+      })
+    );
 
-      // Collect and sort appendices by file path
-      return [
-        // format the user prompt and trim the first line if it's empty
-        lines.length > 1 && lines[0].replaceAll(" ", "").length === 0
-          ? lines.slice(1).join("\n")
-          : lines.join("\n"),
+    // Construct the string template by joining template parts with interpolated values
+    const lines = template
+      .map((part) =>
+        part
+          .split("\n")
+          .map((line) =>
+            line.startsWith(indent) ? line.slice(indent.length) : line
+          )
+          .join("\n")
+      )
+      .flatMap((part, i) =>
+        i < stringValues.length ? [part, stringValues[i] ?? ""] : [part]
+      )
+      .join("")
+      .split("\n");
 
-        // sort appendices by path and include at the end of the prompt
-        Object.entries(appendices)
-          .sort(([a], [b]) => a.localeCompare(b))
-          .map(([filePath, content]) => {
-            const extension = path.extname(filePath).slice(1);
-            const codeTag = extension ? extension : "";
-            return `// ${filePath}\n\`\`\`${codeTag}\n${content}\n\`\`\``;
-          })
-          .join("\n\n"),
-      ].join("\n");
-    })();
+    // Collect and sort appendices by file path
+    return [
+      // format the user prompt and trim the first line if it's empty
+      lines.length > 1 && lines[0].replaceAll(" ", "").length === 0
+        ? lines.slice(1).join("\n")
+        : lines.join("\n"),
+
+      // sort appendices by path and include at the end of the prompt
+      Object.entries(appendices)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([filePath, content]) => {
+          const extension = path.extname(filePath).slice(1);
+          const codeTag = extension ? extension : "";
+          return `// ${filePath}\n\`\`\`${codeTag}\n${content}\n\`\`\``;
+        })
+        .join("\n\n"),
+    ].join("\n");
   }
 }
 _alchemy.destroy = destroy;

package/src/cloudflare/assets.ts

@@ -86,6 +86,9 @@ export interface AssetFile {
  */
 export const Assets = Resource(
   "cloudflare::Asset",
+  {
+    alwaysUpdate: true,
+  },
   async function (
     this: Context<Assets>,
     id: string,

package/src/cloudflare/bound.ts

@@ -1,4 +1,5 @@
 import type { Secret } from "../secret";
+import type { Assets } from "./assets";
 import type { Binding } from "./bindings";
 import type { R2Bucket as _R2Bucket } from "./bucket";
 import type { DurableObjectNamespace as _DurableObjectNamespace } from "./durable-object-namespace";
@@ -15,4 +16,6 @@ export type Bound<T extends Binding> = T extends _DurableObjectNamespace
         ? R2Bucket
         : T extends Secret
           ? string
-          : never;
+          : T extends Assets
+            ? Service
+            : Service;

package/src/cloudflare/custom-domain.ts

@@ -64,8 +64,7 @@ export interface CustomDomain
 
 /**
  * Configure custom domain for a Cloudflare Worker using the Cloudflare Custom Domains API
- * This attaches a worker (either a standard Worker or the one backing a StaticSite)
- * to a specific hostname within a zone.
+ * This attaches a worker to a specific hostname within a zone.
  *
  * @example
  * // Bind a domain to a standard Cloudflare Worker
@@ -80,19 +79,6 @@ export interface CustomDomain
  *   workerName: apiWorker.name // Use the name from the Worker resource
  * });
  *
- * @example
- * // Bind a domain to a Cloudflare Static Site
- * const mySite = await StaticSite("landing-page", {
- *   name: "my-landing-page-site", // This becomes the underlying worker name
- *   dir: "./dist/landing-page"
- * });
- *
- * const siteDomain = await CustomDomain("site-domain-binding", {
- *   name: "www.example.com",
- *   zoneId: "YOUR_ZONE_ID", // Replace with actual Zone ID
- *   workerName: mySite.name // Use the name from the StaticSite resource
- * });
- *
  * @see https://developers.cloudflare.com/api/resources/workers/subresources/domains/
  */
 export const CustomDomain = Resource(

package/src/cloudflare/index.ts

@@ -9,7 +9,6 @@ export * from "./durable-object-namespace";
 export * from "./kv-namespace";
 export * from "./permission-groups";
 export * from "./r2-rest-state-store";
-export * from "./static-site";
 export * from "./worker";
 export * from "./wrangler.json";
 export * from "./zone";

package/src/cloudflare/worker.ts

@@ -101,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;
 }
 
 /**
@@ -245,7 +250,9 @@ 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");

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;