alchemy 0.2.5 → 0.3.0

package/lib/ai/html-file.js

@@ -0,0 +1,155 @@
+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 HTML file generation
+ */
+const DEFAULT_HTML_SYSTEM_PROMPT = "You are an HTML code generator. Create HTML code based on the user's requirements. Your response MUST include only HTML code inside ```html fences. Do not include any other text, explanations, or multiple code blocks.";
+/**
+ * Resource for generating HTML files using AI models.
+ * Extracts HTML code from between ```html fences and validates the response.
+ *
+ * @example
+ * // Create a simple landing page
+ * const landingPage = await HTMLFile("landing-page", {
+ *   path: "./public/index.html",
+ *   prompt: await alchemy`
+ *     Generate a modern landing page for a SaaS product with:
+ *     - Hero section with headline and call-to-action
+ *     - Features section with 3 key features
+ *     - Pricing section with 3 tiers
+ *     - Testimonials section with 2 customer quotes
+ *     - Contact form and footer
+ *   `,
+ *   model: {
+ *     id: "gpt-4o",
+ *     provider: "openai"
+ *   }
+ * });
+ *
+ * @example
+ * // Generate an HTML email template
+ * const emailTemplate = await HTMLFile("welcome-email", {
+ *   path: "./emails/welcome.html",
+ *   prompt: await alchemy`
+ *     Create an HTML email template for welcoming new users to our platform.
+ *     The email should include:
+ *     - Company logo and branding
+ *     - Personalized welcome message (use {{name}} placeholder)
+ *     - Three steps to get started
+ *     - Support contact information
+ *     - Unsubscribe footer
+ *
+ *     Make sure it's responsive and works in all major email clients.
+ *   `,
+ *   temperature: 0.2
+ * });
+ *
+ * @example
+ * // Generate an HTML component with custom system prompt
+ * const navComponent = await HTMLFile("navigation", {
+ *   path: "./components/nav.html",
+ *   prompt: await alchemy`
+ *     Create a responsive navigation component with:
+ *     - Logo in the left corner
+ *     - Navigation links: Home, Products, Services, About, Contact
+ *     - Mobile hamburger menu that expands/collapses
+ *     - Login/signup buttons on the right side
+ *     - Dark/light mode toggle
+ *   `,
+ *   system: "You are an expert HTML/CSS developer specializing in responsive components. Create a single HTML file inside ```html fences with no additional text. Use modern HTML5 semantic elements and inline CSS if needed.",
+ *   model: {
+ *     id: "claude-3-opus-20240229",
+ *     provider: "anthropic"
+ *   }
+ * });
+ */
+export const HTMLFile = Resource("ai::HTMLFile", 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_HTML_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 HTML code
+    let { code, error } = await extractHTMLCode(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 HTML code block inside \`\`\`html 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 extractHTMLCode(retryText);
+        if (retryResult.error) {
+            throw new Error(`Failed to generate valid HTML code: ${retryResult.error}`);
+        }
+        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 HTML code from between ```html fences
+ * Validates that exactly one HTML code block exists
+ *
+ * @param text The text to extract HTML code from
+ * @returns The extracted HTML code or error message
+ */
+async function extractHTMLCode(text) {
+    const htmlCodeRegex = /```html\s*([\s\S]*?)```/g;
+    const matches = Array.from(text.matchAll(htmlCodeRegex));
+    if (matches.length === 0) {
+        return {
+            code: "",
+            error: "No HTML code block found in the response. Please include your code within ```html fences.",
+        };
+    }
+    if (matches.length > 1) {
+        return {
+            code: "",
+            error: "Multiple HTML code blocks found in the response. Please provide exactly one code block within ```html fences.",
+        };
+    }
+    return { code: matches[0][1].trim() };
+}

package/lib/ai/index.d.ts

@@ -1,3 +1,10 @@
 export * from "./ark";
+export * from "./astro-file";
+export * from "./css-file";
 export * from "./data";
 export * from "./document";
+export * from "./html-file";
+export * from "./json-file";
+export * from "./typescript-file";
+export * from "./vue-file";
+export * from "./yaml-file";

package/lib/ai/index.js

@@ -1,3 +1,10 @@
 export * from "./ark";
+export * from "./astro-file";
+export * from "./css-file";
 export * from "./data";
 export * from "./document";
+export * from "./html-file";
+export * from "./json-file";
+export * from "./typescript-file";
+export * from "./vue-file";
+export * from "./yaml-file";

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

@@ -0,0 +1,160 @@
+import type { JsonSchema, Type, type } from "arktype";
+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 JSONFile
+ */
+export interface JSONFileProps<T extends Type<any, any> | undefined = undefined> {
+    /**
+     * Path to the JSON file
+     */
+    path: string;
+    /**
+     * Optional ArkType schema to validate and structure the generated JSON
+     * When provided, the resource will use generateObject with schema validation
+     * When not provided, it will extract JSON from between ```json fences
+     */
+    schema?: T;
+    /**
+     * 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 a JSON configuration for:
+     *   ${alchemy.file("src/config.ts")}
+     * `
+     */
+    prompt: string;
+    /**
+     * System prompt for the model
+     * This is used to provide instructions to the model about how to format the response
+     * @default Depends on whether schema is provided
+     */
+    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;
+    /**
+     * Whether to pretty-print the JSON with indentation
+     * @default true
+     */
+    pretty?: boolean;
+    /**
+     * Number of spaces to use for indentation when pretty-printing
+     * @default 2
+     */
+    indent?: number;
+}
+/**
+ * A JSON file that can be created, updated, and deleted
+ */
+export interface JSONFile<T = any> extends Omit<JSONFileProps, "schema">, Resource<"ai::JSONFile"> {
+    /**
+     * Content of the JSON file as a string
+     */
+    content: string;
+    /**
+     * Parsed JSON object
+     */
+    json: T;
+    /**
+     * Schema used to validate the JSON (if provided)
+     */
+    schema?: JsonSchema;
+    /**
+     * Time at which the file was created
+     */
+    createdAt: number;
+    /**
+     * Time at which the file was last updated
+     */
+    updatedAt: number;
+}
+/**
+ * Resource for generating JSON files using AI models.
+ * Can operate in two modes:
+ * 1. With schema: Uses generateObject with type validation
+ * 2. Without schema: Extracts JSON from between ```json fences
+ *
+ * @example
+ * // Generate a configuration file with freeform JSON
+ * const config = await JSONFile("app-config", {
+ *   path: "./config/app.json",
+ *   prompt: await alchemy`
+ *     Generate a configuration for a web application with:
+ *     - Server settings (port, host, timeout)
+ *     - Database connection details (redact any passwords)
+ *     - Logging configuration
+ *     - Feature flags
+ *   `,
+ *   model: {
+ *     id: "gpt-4o",
+ *     provider: "openai"
+ *   }
+ * });
+ *
+ * @example
+ * // Generate JSON with schema validation
+ * import { type } from "arktype";
+ *
+ * const userSchema = type({
+ *   users: [{
+ *     id: "string",
+ *     name: "string",
+ *     email: "string",
+ *     role: "'admin' | 'user' | 'guest'",
+ *     permissions: "string[]",
+ *     active: "boolean"
+ *   }]
+ * });
+ *
+ * const userData = await JSONFile("user-data", {
+ *   path: "./data/users.json",
+ *   schema: userSchema,
+ *   prompt: "Generate sample user data for an application with various roles and permissions",
+ *   temperature: 0.2
+ * });
+ *
+ * // Type-safe access to the generated data
+ * console.log(userData.json.users[0].role); // Typed as 'admin' | 'user' | 'guest'
+ *
+ * @example
+ * // Generate API mock data with custom system prompt
+ * const apiMock = await JSONFile("api-mock", {
+ *   path: "./mocks/products-api.json",
+ *   prompt: await alchemy`
+ *     Create mock data for a product catalog API response with:
+ *     - 10 products with different categories
+ *     - Each product should have id, name, price, category, inventory, and image_url
+ *     - Include pagination metadata (total, page, limit)
+ *   `,
+ *   system: "You are an API design expert. Create realistic mock JSON data that follows REST API best practices. Your response must be valid JSON inside ```json fences.",
+ *   model: {
+ *     id: "claude-3-opus-20240229",
+ *     provider: "anthropic"
+ *   },
+ *   pretty: true,
+ *   indent: 4
+ * });
+ */
+export declare const JSONFile: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | (<const T extends Type<any, any> | undefined = undefined>(this: Context<JSONFile<T extends Type<any, any> ? type.infer<T> : any>>, id: string, props: JSONFileProps<T>) => Promise<JSONFile<T extends Type<any, any> ? type.infer<T> : any>>);

package/lib/ai/json-file.js

@@ -0,0 +1,208 @@
+import { generateObject, generateText } from "ai";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { Resource } from "../resource";
+import { ignore } from "../util/ignore";
+import { ark } from "./ark";
+import { createModel } from "./client";
+/**
+ * Default system prompt for JSON file generation without schema
+ */
+const DEFAULT_JSON_SYSTEM_PROMPT = "You are a JSON generator. Create valid JSON based on the user's requirements. Your response MUST include only JSON inside ```json fences. Do not include any other text, explanations, or multiple code blocks.";
+/**
+ * Resource for generating JSON files using AI models.
+ * Can operate in two modes:
+ * 1. With schema: Uses generateObject with type validation
+ * 2. Without schema: Extracts JSON from between ```json fences
+ *
+ * @example
+ * // Generate a configuration file with freeform JSON
+ * const config = await JSONFile("app-config", {
+ *   path: "./config/app.json",
+ *   prompt: await alchemy`
+ *     Generate a configuration for a web application with:
+ *     - Server settings (port, host, timeout)
+ *     - Database connection details (redact any passwords)
+ *     - Logging configuration
+ *     - Feature flags
+ *   `,
+ *   model: {
+ *     id: "gpt-4o",
+ *     provider: "openai"
+ *   }
+ * });
+ *
+ * @example
+ * // Generate JSON with schema validation
+ * import { type } from "arktype";
+ *
+ * const userSchema = type({
+ *   users: [{
+ *     id: "string",
+ *     name: "string",
+ *     email: "string",
+ *     role: "'admin' | 'user' | 'guest'",
+ *     permissions: "string[]",
+ *     active: "boolean"
+ *   }]
+ * });
+ *
+ * const userData = await JSONFile("user-data", {
+ *   path: "./data/users.json",
+ *   schema: userSchema,
+ *   prompt: "Generate sample user data for an application with various roles and permissions",
+ *   temperature: 0.2
+ * });
+ *
+ * // Type-safe access to the generated data
+ * console.log(userData.json.users[0].role); // Typed as 'admin' | 'user' | 'guest'
+ *
+ * @example
+ * // Generate API mock data with custom system prompt
+ * const apiMock = await JSONFile("api-mock", {
+ *   path: "./mocks/products-api.json",
+ *   prompt: await alchemy`
+ *     Create mock data for a product catalog API response with:
+ *     - 10 products with different categories
+ *     - Each product should have id, name, price, category, inventory, and image_url
+ *     - Include pagination metadata (total, page, limit)
+ *   `,
+ *   system: "You are an API design expert. Create realistic mock JSON data that follows REST API best practices. Your response must be valid JSON inside ```json fences.",
+ *   model: {
+ *     id: "claude-3-opus-20240229",
+ *     provider: "anthropic"
+ *   },
+ *   pretty: true,
+ *   indent: 4
+ * });
+ */
+export const JSONFile = Resource("ai::JSONFile", 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();
+    }
+    // Determine if we should use pretty printing
+    const pretty = props.pretty !== false;
+    const indent = props.indent ?? 2;
+    let jsonContent;
+    let jsonObject;
+    // Check if schema is provided
+    if (props.schema) {
+        // Use schema-based generation
+        const { object } = await generateObject({
+            model: createModel(props),
+            schema: ark.schema(props.schema),
+            providerOptions: props.model?.options,
+            system: props.system ||
+                "Generate a valid JSON object based on the provided requirements.",
+            prompt: props.prompt,
+            ...(props.temperature === undefined
+                ? {}
+                : { temperature: props.temperature }),
+        });
+        jsonObject = object;
+        jsonContent = pretty
+            ? JSON.stringify(jsonObject, null, indent)
+            : JSON.stringify(jsonObject);
+    }
+    else {
+        // Use fence-based extraction
+        // Use provided system prompt or default
+        const system = props.system || DEFAULT_JSON_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 JSON content
+        let { content, error } = await extractJSONContent(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 valid JSON block inside \`\`\`json 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 extractJSONContent(retryText);
+            if (retryResult.error) {
+                throw new Error(`Failed to generate valid JSON: ${retryResult.error}`);
+            }
+            content = retryResult.content;
+        }
+        // Parse JSON
+        jsonObject = JSON.parse(content);
+        // Format with or without indentation based on pretty option
+        jsonContent = pretty ? JSON.stringify(jsonObject, null, indent) : content;
+    }
+    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, jsonContent);
+    // Get file stats for timestamps
+    const stats = await fs.stat(props.path);
+    // Return the resource
+    return this({
+        ...props,
+        schema: props.schema,
+        content: jsonContent,
+        json: jsonObject,
+        createdAt: stats.birthtimeMs,
+        updatedAt: stats.mtimeMs,
+    });
+});
+/**
+ * Extracts JSON content from between ```json fences
+ * Validates that exactly one JSON code block exists
+ *
+ * @param text The text to extract JSON from
+ * @returns The extracted JSON or error message
+ */
+async function extractJSONContent(text) {
+    const jsonCodeRegex = /```json\s*([\s\S]*?)```/g;
+    const matches = Array.from(text.matchAll(jsonCodeRegex));
+    if (matches.length === 0) {
+        return {
+            content: "",
+            error: "No JSON code block found in the response. Please include your JSON within ```json fences.",
+        };
+    }
+    if (matches.length > 1) {
+        return {
+            content: "",
+            error: "Multiple JSON code blocks found in the response. Please provide exactly one JSON block within ```json fences.",
+        };
+    }
+    const content = matches[0][1].trim();
+    // Validate JSON can be parsed
+    try {
+        JSON.parse(content);
+        return { content };
+    }
+    catch (e) {
+        return {
+            content: "",
+            error: `Invalid JSON: ${e.message}. Please provide valid JSON syntax.`,
+        };
+    }
+}

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

@@ -0,0 +1,140 @@
+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 a TypeScriptFile
+ */
+export interface TypeScriptFileProps {
+    /**
+     * Path to the TypeScript 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 a TypeScript utility function 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 TypeScript code inside ```ts fences
+     * @default "You are a TypeScript code generator. Create TypeScript code based on the user's requirements. Your response MUST include only TypeScript code inside ```ts 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 TypeScript code
+     * If not provided, will use the default Prettier configuration
+     */
+    prettierConfig?: prettier.Options;
+}
+/**
+ * A TypeScript file that can be created, updated, and deleted
+ */
+export interface TypeScriptFile extends TypeScriptFileProps, Resource<"ai::TypeScriptFile"> {
+    /**
+     * Content of the TypeScript 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 TypeScript files using AI models.
+ * Extracts TypeScript code from between ```ts fences, validates the response,
+ * and formats the code with Prettier.
+ *
+ * @example
+ * // Create a utility function
+ * const utils = await TypeScriptFile("string-utils", {
+ *   path: "./src/utils/string-utils.ts",
+ *   prompt: await alchemy`
+ *     Generate TypeScript utility functions for string manipulation:
+ *     - Capitalize first letter
+ *     - Truncate with ellipsis
+ *     - Convert to camelCase and kebab-case
+ *     - Remove special characters
+ *   `,
+ *   model: {
+ *     id: "gpt-4o",
+ *     provider: "openai"
+ *   }
+ * });
+ *
+ * @example
+ * // Generate a TypeScript class with custom formatting
+ * const userService = await TypeScriptFile("user-service", {
+ *   path: "./src/services/UserService.ts",
+ *   prompt: await alchemy`
+ *     Create a UserService class that handles user authentication and profile management.
+ *     The service should use the User type from:
+ *     ${alchemy.file("src/types/User.ts")}
+ *
+ *     Include methods for:
+ *     - login(email, password)
+ *     - register(user)
+ *     - updateProfile(userId, profileData)
+ *     - deleteAccount(userId)
+ *   `,
+ *   temperature: 0.2,
+ *   prettierConfig: {
+ *     semi: false,
+ *     singleQuote: true,
+ *     printWidth: 120
+ *   }
+ * });
+ *
+ * @example
+ * // Generate a React hook with custom system prompt
+ * const useFormHook = await TypeScriptFile("use-form", {
+ *   path: "./src/hooks/useForm.ts",
+ *   prompt: await alchemy`
+ *     Create a custom React hook called useForm that handles form state, validation, and submission.
+ *     It should support:
+ *     - Initial values
+ *     - Validation rules
+ *     - Field errors
+ *     - Form submission with loading state
+ *     - Reset functionality
+ *   `,
+ *   system: "You are an expert React developer specializing in TypeScript hooks. Create a single TypeScript file inside ```ts fences with no additional text. Follow React best practices and include proper typing.",
+ *   model: {
+ *     id: "claude-3-opus-20240229",
+ *     provider: "anthropic"
+ *   }
+ * });
+ */
+export declare const TypeScriptFile: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<TypeScriptFile>, id: string, props: TypeScriptFileProps) => Promise<TypeScriptFile>);