alchemy 0.2.5 → 0.3.0

package/README.md

@@ -9,7 +9,7 @@ Resources are simple memoized async functions that can run in any JavaScript run
 ```ts
 import alchemy from "alchemy";
 
-await using _ = alchemy("cloudflare-worker");
+await using app = alchemy("cloudflare-worker");
 
 export const worker = await Worker("worker", {
   name: "my-worker",
@@ -38,8 +38,8 @@ export const worker = await Worker("worker", {
 
 # Examples
 
-- CloudFlare ViteJS Website + API Backend with Durable Objects: [examples/cloudflare-vite/](./examples/cloudflare-vite/alchemy.config.ts)
-- Deploy an AWS Lambda Function with a DynamoDB Table and IAM Role: [examples/aws-app/](./examples/aws-app/alchemy.config.ts)
+- CloudFlare ViteJS Website + API Backend with Durable Objects: [examples/cloudflare-vite/](./examples/cloudflare-vite/alchemy.run.ts)
+- Deploy an AWS Lambda Function with a DynamoDB Table and IAM Role: [examples/aws-app/](./examples/aws-app/alchemy.run.ts)
 
 # Getting Started
 

package/lib/ai/astro-file.d.ts

@@ -0,0 +1,137 @@
+import prettier from "prettier";
+import type { Context } from "../context";
+import { Resource } from "../resource";
+import type { Secret } from "../secret";
+import { type ModelConfig } from "./client";
+/**
+ * Properties for creating or updating an AstroFile
+ */
+export interface AstroFileProps {
+    /**
+     * Path to the Astro file
+     */
+    path: string;
+    /**
+     * Base URL for the OpenAI API
+     * @default 'https://api.openai.com/v1'
+     */
+    baseURL?: string;
+    /**
+     * Prompt for generating content
+     * Use alchemy template literals to include file context:
+     * @example
+     * prompt: await alchemy`
+     *   Generate an Astro component using:
+     *   ${alchemy.file("src/types.ts")}
+     * `
+     */
+    prompt: string;
+    /**
+     * System prompt for the model
+     * This is used to provide instructions to the model about how to format the response
+     * The default system prompt instructs the model to return Astro code inside ```astro fences
+     * @default "You are an Astro component generator. Create Astro components based on the user's requirements. Your response MUST include only Astro code inside ```astro fences. Do not include any other text, explanations, or multiple code blocks."
+     */
+    system?: string;
+    /**
+     * OpenAI API key to use for generating content
+     * If not provided, will use OPENAI_API_KEY environment variable
+     */
+    apiKey?: Secret;
+    /**
+     * Model configuration
+     */
+    model?: ModelConfig;
+    /**
+     * Temperature for controlling randomness in generation.
+     * Higher values (e.g., 0.8) make output more random,
+     * lower values (e.g., 0.2) make it more deterministic.
+     * @default 0.7
+     */
+    temperature?: number;
+    /**
+     * Prettier configuration to use for formatting the Astro code
+     * If not provided, will use the default Prettier configuration
+     */
+    prettierConfig?: prettier.Options;
+}
+/**
+ * An Astro file that can be created, updated, and deleted
+ */
+export interface AstroFile extends AstroFileProps, Resource<"ai::AstroFile"> {
+    /**
+     * Content of the Astro file
+     */
+    content: string;
+    /**
+     * Time at which the file was created
+     */
+    createdAt: number;
+    /**
+     * Time at which the file was last updated
+     */
+    updatedAt: number;
+}
+/**
+ * Resource for generating Astro files using AI models.
+ * Extracts Astro code from between ```astro fences, validates the response,
+ * and formats the code with Prettier.
+ *
+ * @example
+ * // Create a simple Astro component
+ * const header = await AstroFile("header", {
+ *   path: "./src/components/Header.astro",
+ *   prompt: await alchemy`
+ *     Generate an Astro header component with:
+ *     - Site logo
+ *     - Navigation menu with Home, About, Services, Contact links
+ *     - Mobile responsive design
+ *     - Dark/light mode toggle
+ *   `,
+ *   model: {
+ *     id: "gpt-4o",
+ *     provider: "openai"
+ *   }
+ * });
+ *
+ * @example
+ * // Generate an Astro page with data fetching
+ * const blogPost = await AstroFile("blog-post", {
+ *   path: "./src/pages/blog/[slug].astro",
+ *   prompt: await alchemy`
+ *     Create an Astro blog post page that:
+ *     - Uses getStaticPaths to generate pages from a CMS
+ *     - Renders markdown content
+ *     - Includes author info, publication date, and related posts
+ *     - Has social sharing buttons
+ *
+ *     Use the following types:
+ *     ${alchemy.file("src/types/Blog.ts")}
+ *   `,
+ *   temperature: 0.2,
+ *   prettierConfig: {
+ *     semi: false,
+ *     singleQuote: true,
+ *     printWidth: 120
+ *   }
+ * });
+ *
+ * @example
+ * // Generate a layout with custom system prompt
+ * const mainLayout = await AstroFile("main-layout", {
+ *   path: "./src/layouts/MainLayout.astro",
+ *   prompt: await alchemy`
+ *     Create the main layout for an Astro site that:
+ *     - Includes common head metadata and SEO optimization
+ *     - Has slots for page content, header, and footer
+ *     - Imports and uses the Header and Footer components
+ *     - Sets up viewport and responsive configurations
+ *   `,
+ *   system: "You are an expert Astro developer. Create a single Astro layout file inside ```astro fences with no additional text. Follow Astro best practices and include proper typing in the frontmatter section.",
+ *   model: {
+ *     id: "claude-3-opus-20240229",
+ *     provider: "anthropic"
+ *   }
+ * });
+ */
+export declare const AstroFile: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<AstroFile>, id: string, props: AstroFileProps) => Promise<AstroFile>);

package/lib/ai/astro-file.js

@@ -0,0 +1,173 @@
+import { generateText } from "ai";
+import fs from "node:fs/promises";
+import path from "node:path";
+import prettier from "prettier";
+import { Resource } from "../resource";
+import { ignore } from "../util/ignore";
+import { createModel } from "./client";
+/**
+ * Default system prompt for Astro file generation
+ */
+const DEFAULT_ASTRO_SYSTEM_PROMPT = "You are an Astro component generator. Create Astro components based on the user's requirements. Your response MUST include only Astro code inside ```astro fences. Do not include any other text, explanations, or multiple code blocks.";
+/**
+ * Resource for generating Astro files using AI models.
+ * Extracts Astro code from between ```astro fences, validates the response,
+ * and formats the code with Prettier.
+ *
+ * @example
+ * // Create a simple Astro component
+ * const header = await AstroFile("header", {
+ *   path: "./src/components/Header.astro",
+ *   prompt: await alchemy`
+ *     Generate an Astro header component with:
+ *     - Site logo
+ *     - Navigation menu with Home, About, Services, Contact links
+ *     - Mobile responsive design
+ *     - Dark/light mode toggle
+ *   `,
+ *   model: {
+ *     id: "gpt-4o",
+ *     provider: "openai"
+ *   }
+ * });
+ *
+ * @example
+ * // Generate an Astro page with data fetching
+ * const blogPost = await AstroFile("blog-post", {
+ *   path: "./src/pages/blog/[slug].astro",
+ *   prompt: await alchemy`
+ *     Create an Astro blog post page that:
+ *     - Uses getStaticPaths to generate pages from a CMS
+ *     - Renders markdown content
+ *     - Includes author info, publication date, and related posts
+ *     - Has social sharing buttons
+ *
+ *     Use the following types:
+ *     ${alchemy.file("src/types/Blog.ts")}
+ *   `,
+ *   temperature: 0.2,
+ *   prettierConfig: {
+ *     semi: false,
+ *     singleQuote: true,
+ *     printWidth: 120
+ *   }
+ * });
+ *
+ * @example
+ * // Generate a layout with custom system prompt
+ * const mainLayout = await AstroFile("main-layout", {
+ *   path: "./src/layouts/MainLayout.astro",
+ *   prompt: await alchemy`
+ *     Create the main layout for an Astro site that:
+ *     - Includes common head metadata and SEO optimization
+ *     - Has slots for page content, header, and footer
+ *     - Imports and uses the Header and Footer components
+ *     - Sets up viewport and responsive configurations
+ *   `,
+ *   system: "You are an expert Astro developer. Create a single Astro layout file inside ```astro fences with no additional text. Follow Astro best practices and include proper typing in the frontmatter section.",
+ *   model: {
+ *     id: "claude-3-opus-20240229",
+ *     provider: "anthropic"
+ *   }
+ * });
+ */
+export const AstroFile = Resource("ai::AstroFile", async function (id, props) {
+    // Ensure directory exists
+    await fs.mkdir(path.dirname(props.path), { recursive: true });
+    if (this.phase === "delete") {
+        try {
+            await fs.unlink(props.path);
+        }
+        catch (error) {
+            // Ignore if file doesn't exist
+            if (error.code !== "ENOENT") {
+                throw error;
+            }
+        }
+        return this.destroy();
+    }
+    // Use provided system prompt or default
+    const system = props.system || DEFAULT_ASTRO_SYSTEM_PROMPT;
+    // Generate initial content
+    const { text } = await generateText({
+        model: createModel(props),
+        prompt: props.prompt,
+        system,
+        providerOptions: props.model?.options,
+        ...(props.temperature === undefined
+            ? {}
+            : { temperature: props.temperature }),
+    });
+    // Extract and validate Astro code
+    let { code, error } = await extractAstroCode(text);
+    // Re-prompt if there are validation errors
+    if (error) {
+        const errorSystem = `${system}\n\nERROR: ${error}\n\nPlease try again and ensure your response contains exactly one Astro code block inside \`\`\`astro fences.`;
+        const { text: retryText } = await generateText({
+            model: createModel(props),
+            prompt: props.prompt,
+            system: errorSystem,
+            providerOptions: props.model?.options,
+            ...(props.temperature === undefined
+                ? {}
+                : { temperature: props.temperature }),
+        });
+        const retryResult = await extractAstroCode(retryText);
+        if (retryResult.error) {
+            throw new Error(`Failed to generate valid Astro code: ${retryResult.error}`);
+        }
+        code = retryResult.code;
+    }
+    // Format the code with Prettier
+    try {
+        // Set default parser to astro
+        const prettierOptions = {
+            parser: "astro",
+            ...props.prettierConfig,
+        };
+        // Format the code
+        code = await prettier.format(code, prettierOptions);
+    }
+    catch (error) {
+        // If Prettier formatting fails, just use the unformatted code
+        console.warn("Failed to format Astro code with Prettier:", error);
+    }
+    if (this.phase === "update" && props.path !== this.props.path) {
+        await ignore("ENOENT", () => fs.unlink(this.props.path));
+    }
+    // Write content to file
+    await fs.writeFile(props.path, code);
+    // Get file stats for timestamps
+    const stats = await fs.stat(props.path);
+    // Return the resource
+    return this({
+        ...props,
+        content: code,
+        createdAt: stats.birthtimeMs,
+        updatedAt: stats.mtimeMs,
+    });
+});
+/**
+ * Extracts Astro code from between ```astro fences
+ * Validates that exactly one Astro code block exists
+ *
+ * @param text The text to extract Astro code from
+ * @returns The extracted Astro code or error message
+ */
+async function extractAstroCode(text) {
+    const astroCodeRegex = /```astro\s*([\s\S]*?)```/g;
+    const matches = Array.from(text.matchAll(astroCodeRegex));
+    if (matches.length === 0) {
+        return {
+            code: "",
+            error: "No Astro code block found in the response. Please include your code within ```astro fences.",
+        };
+    }
+    if (matches.length > 1) {
+        return {
+            code: "",
+            error: "Multiple Astro code blocks found in the response. Please provide exactly one code block within ```astro fences.",
+        };
+    }
+    return { code: matches[0][1].trim() };
+}

package/lib/ai/client.d.ts

@@ -16,7 +16,7 @@ export interface ModelConfig {
     /**
      * Model-specific options
      */
-    options?: Record<string, unknown>;
+    options?: Record<string, any>;
 }
 /**
  * Configuration for creating an OpenAI client
@@ -40,12 +40,4 @@ export interface ClientConfig {
 /**
  * Creates an OpenAI-compatible client with the given configuration
  */
-export declare function createClient(config: ClientConfig): import("@ai-sdk/openai-compatible").OpenAICompatibleProvider<string, string, string, string>;
-/**
- * Gets the model ID from the configuration or returns the default
- */
-export declare function getModelId(config: ClientConfig): string;
-/**
- * Gets the model options from the configuration
- */
-export declare function getModelOptions(config: ClientConfig): Record<string, unknown>;
+export declare function createModel(config: ClientConfig): import("ai").LanguageModelV1;

package/lib/ai/client.js

@@ -1,29 +1,13 @@
-import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
+import { anthropic } from "@ai-sdk/anthropic";
+import { openai } from "@ai-sdk/openai";
 /**
  * Creates an OpenAI-compatible client with the given configuration
  */
-export function createClient(config) {
-    // Get API key from props or environment
-    const apiKey = config.apiKey?.unencrypted || process.env.OPENAI_API_KEY;
-    if (!apiKey) {
-        throw new Error("OpenAI API key is required");
+export function createModel(config) {
+    if (config.model?.provider === "anthropic") {
+        return anthropic(config.model?.id ?? "claude-3-7-sonnet-latest");
+    }
+    else {
+        return openai(config.model?.id ?? "gpt-4o");
     }
-    // Initialize OpenAI compatible provider
-    return createOpenAICompatible({
-        name: config.model?.provider || "openai",
-        apiKey,
-        baseURL: config.baseURL || "https://api.openai.com/v1",
-    });
-}
-/**
- * Gets the model ID from the configuration or returns the default
- */
-export function getModelId(config) {
-    return config.model?.id || "gpt-4o";
-}
-/**
- * Gets the model options from the configuration
- */
-export function getModelOptions(config) {
-    return config.model?.options || {};
 }

package/lib/ai/css-file.d.ts

@@ -0,0 +1,131 @@
+import type { Context } from "../context";
+import { Resource } from "../resource";
+import type { Secret } from "../secret";
+import { type ModelConfig } from "./client";
+/**
+ * Properties for creating or updating a CSSFile
+ */
+export interface CSSFileProps {
+    /**
+     * Path to the CSS file
+     */
+    path: string;
+    /**
+     * Base URL for the OpenAI API
+     * @default 'https://api.openai.com/v1'
+     */
+    baseURL?: string;
+    /**
+     * Prompt for generating content
+     * Use alchemy template literals to include file context:
+     * @example
+     * prompt: await alchemy`
+     *   Generate CSS styles for:
+     *   ${alchemy.file("src/components/Button.jsx")}
+     * `
+     */
+    prompt: string;
+    /**
+     * System prompt for the model
+     * This is used to provide instructions to the model about how to format the response
+     * The default system prompt instructs the model to return CSS code inside ```css fences
+     * @default "You are a CSS code generator. Create CSS code based on the user's requirements. Your response MUST include only CSS code inside ```css fences. Do not include any other text, explanations, or multiple code blocks."
+     */
+    system?: string;
+    /**
+     * OpenAI API key to use for generating content
+     * If not provided, will use OPENAI_API_KEY environment variable
+     */
+    apiKey?: Secret;
+    /**
+     * Model configuration
+     */
+    model?: ModelConfig;
+    /**
+     * Temperature for controlling randomness in generation.
+     * Higher values (e.g., 0.8) make output more random,
+     * lower values (e.g., 0.2) make it more deterministic.
+     * @default 0.7
+     */
+    temperature?: number;
+}
+/**
+ * A CSS file that can be created, updated, and deleted
+ */
+export interface CSSFile extends CSSFileProps, Resource<"ai::CSSFile"> {
+    /**
+     * Content of the CSS file
+     */
+    content: string;
+    /**
+     * Time at which the file was created
+     */
+    createdAt: number;
+    /**
+     * Time at which the file was last updated
+     */
+    updatedAt: number;
+}
+/**
+ * Resource for generating CSS files using AI models.
+ * Extracts CSS code from between ```css fences and validates the response.
+ *
+ * @example
+ * // Create styles for a website
+ * const mainStyles = await CSSFile("main-styles", {
+ *   path: "./public/css/main.css",
+ *   prompt: await alchemy`
+ *     Generate modern CSS styles for a company website with:
+ *     - Clean, minimalist design
+ *     - Primary color: #0062ff
+ *     - Secondary color: #6c757d
+ *     - Light gray background
+ *     - Responsive layout for mobile, tablet, and desktop
+ *     - Custom styles for buttons, cards, and navigation
+ *   `,
+ *   model: {
+ *     id: "gpt-4o",
+ *     provider: "openai"
+ *   }
+ * });
+ *
+ * @example
+ * // Generate CSS based on existing HTML
+ * const componentStyles = await CSSFile("component-styles", {
+ *   path: "./src/styles/component.css",
+ *   prompt: await alchemy`
+ *     Create CSS styles for this HTML component:
+ *     ${alchemy.file("src/components/Card.html")}
+ *
+ *     The styles should be:
+ *     - Modern and clean
+ *     - Include hover effects and transitions
+ *     - Support both light and dark themes
+ *     - Use CSS variables for colors and spacing
+ *   `,
+ *   temperature: 0.2
+ * });
+ *
+ * @example
+ * // Generate CSS animation with custom system prompt
+ * const animationStyles = await CSSFile("animations", {
+ *   path: "./src/styles/animations.css",
+ *   prompt: await alchemy`
+ *     Create CSS animations for:
+ *     - Fade in/out
+ *     - Slide in from different directions
+ *     - Pulse effect
+ *     - Bounce effect
+ *     - Scale in/out
+ *     - Rotate
+ *
+ *     Each animation should be reusable via class names.
+ *   `,
+ *   system: "You are an expert CSS animator. Create a single CSS file inside ```css fences with no additional text. Use modern CSS animation techniques and include vendor prefixes where needed for browser compatibility.",
+ *   model: {
+ *     id: "claude-3-opus-20240229",
+ *     provider: "anthropic"
+ *   }
+ * });
+ */
+export declare const CSSFile: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<CSSFile>, id: string, props: CSSFileProps) => Promise<CSSFile>);

package/lib/ai/css-file.js

@@ -0,0 +1,158 @@
+import { generateText } from "ai";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { Resource } from "../resource";
+import { ignore } from "../util/ignore";
+import { createModel } from "./client";
+/**
+ * Default system prompt for CSS file generation
+ */
+const DEFAULT_CSS_SYSTEM_PROMPT = "You are a CSS code generator. Create CSS code based on the user's requirements. Your response MUST include only CSS code inside ```css fences. Do not include any other text, explanations, or multiple code blocks.";
+/**
+ * Resource for generating CSS files using AI models.
+ * Extracts CSS code from between ```css fences and validates the response.
+ *
+ * @example
+ * // Create styles for a website
+ * const mainStyles = await CSSFile("main-styles", {
+ *   path: "./public/css/main.css",
+ *   prompt: await alchemy`
+ *     Generate modern CSS styles for a company website with:
+ *     - Clean, minimalist design
+ *     - Primary color: #0062ff
+ *     - Secondary color: #6c757d
+ *     - Light gray background
+ *     - Responsive layout for mobile, tablet, and desktop
+ *     - Custom styles for buttons, cards, and navigation
+ *   `,
+ *   model: {
+ *     id: "gpt-4o",
+ *     provider: "openai"
+ *   }
+ * });
+ *
+ * @example
+ * // Generate CSS based on existing HTML
+ * const componentStyles = await CSSFile("component-styles", {
+ *   path: "./src/styles/component.css",
+ *   prompt: await alchemy`
+ *     Create CSS styles for this HTML component:
+ *     ${alchemy.file("src/components/Card.html")}
+ *
+ *     The styles should be:
+ *     - Modern and clean
+ *     - Include hover effects and transitions
+ *     - Support both light and dark themes
+ *     - Use CSS variables for colors and spacing
+ *   `,
+ *   temperature: 0.2
+ * });
+ *
+ * @example
+ * // Generate CSS animation with custom system prompt
+ * const animationStyles = await CSSFile("animations", {
+ *   path: "./src/styles/animations.css",
+ *   prompt: await alchemy`
+ *     Create CSS animations for:
+ *     - Fade in/out
+ *     - Slide in from different directions
+ *     - Pulse effect
+ *     - Bounce effect
+ *     - Scale in/out
+ *     - Rotate
+ *
+ *     Each animation should be reusable via class names.
+ *   `,
+ *   system: "You are an expert CSS animator. Create a single CSS file inside ```css fences with no additional text. Use modern CSS animation techniques and include vendor prefixes where needed for browser compatibility.",
+ *   model: {
+ *     id: "claude-3-opus-20240229",
+ *     provider: "anthropic"
+ *   }
+ * });
+ */
+export const CSSFile = Resource("ai::CSSFile", async function (id, props) {
+    // Ensure directory exists
+    await fs.mkdir(path.dirname(props.path), { recursive: true });
+    if (this.phase === "delete") {
+        try {
+            await fs.unlink(props.path);
+        }
+        catch (error) {
+            // Ignore if file doesn't exist
+            if (error.code !== "ENOENT") {
+                throw error;
+            }
+        }
+        return this.destroy();
+    }
+    // Use provided system prompt or default
+    const system = props.system || DEFAULT_CSS_SYSTEM_PROMPT;
+    // Generate initial content
+    const { text } = await generateText({
+        model: createModel(props),
+        prompt: props.prompt,
+        system,
+        providerOptions: props.model?.options,
+        ...(props.temperature === undefined
+            ? {}
+            : { temperature: props.temperature }),
+    });
+    // Extract and validate CSS code
+    let { code, error } = await extractCSSCode(text);
+    // Re-prompt if there are validation errors
+    if (error) {
+        const errorSystem = `${system}\n\nERROR: ${error}\n\nPlease try again and ensure your response contains exactly one CSS code block inside \`\`\`css fences.`;
+        const { text: retryText } = await generateText({
+            model: createModel(props),
+            prompt: props.prompt,
+            system: errorSystem,
+            providerOptions: props.model?.options,
+            ...(props.temperature === undefined
+                ? {}
+                : { temperature: props.temperature }),
+        });
+        const retryResult = await extractCSSCode(retryText);
+        if (retryResult.error) {
+            throw new Error(`Failed to generate valid CSS code: ${retryResult.error}\n${retryText}`);
+        }
+        code = retryResult.code;
+    }
+    if (this.phase === "update" && props.path !== this.props.path) {
+        await ignore("ENOENT", () => fs.unlink(this.props.path));
+    }
+    // Write content to file
+    await fs.writeFile(props.path, code);
+    // Get file stats for timestamps
+    const stats = await fs.stat(props.path);
+    // Return the resource
+    return this({
+        ...props,
+        content: code,
+        createdAt: stats.birthtimeMs,
+        updatedAt: stats.mtimeMs,
+    });
+});
+/**
+ * Extracts CSS code from between ```css fences
+ * Validates that exactly one CSS code block exists
+ *
+ * @param text The text to extract CSS code from
+ * @returns The extracted CSS code or error message
+ */
+async function extractCSSCode(text) {
+    const cssCodeRegex = /```css\s*([\s\S]*?)```/g;
+    const matches = Array.from(text.matchAll(cssCodeRegex));
+    if (matches.length === 0) {
+        return {
+            code: "",
+            error: "No CSS code block found in the response. Please include your code within ```css fences.",
+        };
+    }
+    if (matches.length > 1) {
+        return {
+            code: "",
+            error: "Multiple CSS code blocks found in the response. Please provide exactly one code block within ```css fences.",
+        };
+    }
+    return { code: matches[0][1].trim() };
+}