alchemy 0.2.5 → 0.3.0

package/lib/ai/typescript-file.js

@@ -0,0 +1,176 @@
+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 TypeScript file generation
+ */
+const DEFAULT_TS_SYSTEM_PROMPT = "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.";
+/**
+ * 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 const TypeScriptFile = Resource("ai::TypeScriptFile", 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_TS_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 TypeScript code
+    let { code, error } = await extractTypeScriptCode(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 TypeScript code block inside \`\`\`ts 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 extractTypeScriptCode(retryText);
+        if (retryResult.error) {
+            throw new Error(`Failed to generate valid TypeScript code: ${retryResult.error}`);
+        }
+        code = retryResult.code;
+    }
+    // Format the code with Prettier
+    try {
+        // Set default parser to typescript
+        const prettierOptions = {
+            parser: "typescript",
+            ...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 TypeScript 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 TypeScript code from between ```ts fences
+ * Validates that exactly one TypeScript code block exists
+ *
+ * @param text The text to extract TypeScript code from
+ * @returns The extracted TypeScript code or error message
+ */
+async function extractTypeScriptCode(text) {
+    const tsCodeRegex = /```ts\s*([\s\S]*?)```/g;
+    const matches = Array.from(text.matchAll(tsCodeRegex));
+    if (matches.length === 0) {
+        return {
+            code: "",
+            error: "No TypeScript code block found in the response. Please include your code within ```ts fences.",
+        };
+    }
+    if (matches.length > 1) {
+        return {
+            code: "",
+            error: "Multiple TypeScript code blocks found in the response. Please provide exactly one code block within ```ts fences.",
+        };
+    }
+    return { code: matches[0][1].trim() };
+}

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

@@ -0,0 +1,126 @@
+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 VueFile
+ */
+export interface VueFileProps {
+    /**
+     * Path to the Vue 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 Vue component using:
+     *   ${alchemy.file("src/api.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 a single Vue component inside ```vue fences
+     * @default "You are a Vue component generator. Create a single Vue component based on the user's requirements. Your response MUST include only a single Vue component inside ```vue 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 Vue file that can be created, updated, and deleted
+ */
+export interface VueFile extends VueFileProps, Resource<"ai::VueFile"> {
+    /**
+     * Content of the Vue 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 Vue files using AI models.
+ * Extracts Vue code from between ```vue fences and validates the response.
+ *
+ * @example
+ * // Create a simple Vue component
+ * const button = await VueFile("button-component", {
+ *   path: "./src/components/Button.vue",
+ *   prompt: await alchemy`
+ *     Generate a customizable button Vue component with:
+ *     - Primary, secondary, and outline variants
+ *     - Small, medium, and large sizes
+ *     - Loading state with spinner
+ *     - Disabled state
+ *   `,
+ *   model: {
+ *     id: "gpt-4o",
+ *     provider: "openai"
+ *   }
+ * });
+ *
+ * @example
+ * // Generate a Vue component using existing files as reference
+ * const userCard = await VueFile("user-card", {
+ *   path: "./src/components/UserCard.vue",
+ *   prompt: await alchemy`
+ *     Create a UserCard Vue component that displays user information.
+ *     Follow the styling patterns from:
+ *     ${alchemy.file("src/components/Card.vue")}
+ *
+ *     Use the user type from:
+ *     ${alchemy.file("src/types/User.ts")}
+ *   `,
+ *   temperature: 0.2
+ * });
+ *
+ * @example
+ * // Generate a complex form component with validation and custom system prompt
+ * const form = await VueFile("registration-form", {
+ *   path: "./src/components/RegistrationForm.vue",
+ *   prompt: await alchemy`
+ *     Generate a registration form Vue component with:
+ *     - Email, password, and confirm password fields
+ *     - Form validation using Vuelidate or similar
+ *     - Error messages for each field
+ *     - Submit handler that emits form data
+ *
+ *     Follow these style guidelines:
+ *     ${alchemy.file("src/styles/guidelines.md")}
+ *   `,
+ *   system: "You are an expert Vue component creator specializing in form components with validation. Create a single Vue component inside ```vue fences with no additional text.",
+ *   model: {
+ *     id: "claude-3-opus-20240229",
+ *     provider: "anthropic"
+ *   }
+ * });
+ */
+export declare const VueFile: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<VueFile>, id: string, props: VueFileProps) => Promise<VueFile>);

package/lib/ai/vue-file.js

@@ -0,0 +1,153 @@
+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 Vue file generation
+ */
+const DEFAULT_VUE_SYSTEM_PROMPT = "You are a Vue component generator. Create a single Vue component based on the user's requirements. Your response MUST include only a single Vue component inside ```vue fences. Do not include any other text, explanations, or multiple code blocks.";
+/**
+ * Resource for generating Vue files using AI models.
+ * Extracts Vue code from between ```vue fences and validates the response.
+ *
+ * @example
+ * // Create a simple Vue component
+ * const button = await VueFile("button-component", {
+ *   path: "./src/components/Button.vue",
+ *   prompt: await alchemy`
+ *     Generate a customizable button Vue component with:
+ *     - Primary, secondary, and outline variants
+ *     - Small, medium, and large sizes
+ *     - Loading state with spinner
+ *     - Disabled state
+ *   `,
+ *   model: {
+ *     id: "gpt-4o",
+ *     provider: "openai"
+ *   }
+ * });
+ *
+ * @example
+ * // Generate a Vue component using existing files as reference
+ * const userCard = await VueFile("user-card", {
+ *   path: "./src/components/UserCard.vue",
+ *   prompt: await alchemy`
+ *     Create a UserCard Vue component that displays user information.
+ *     Follow the styling patterns from:
+ *     ${alchemy.file("src/components/Card.vue")}
+ *
+ *     Use the user type from:
+ *     ${alchemy.file("src/types/User.ts")}
+ *   `,
+ *   temperature: 0.2
+ * });
+ *
+ * @example
+ * // Generate a complex form component with validation and custom system prompt
+ * const form = await VueFile("registration-form", {
+ *   path: "./src/components/RegistrationForm.vue",
+ *   prompt: await alchemy`
+ *     Generate a registration form Vue component with:
+ *     - Email, password, and confirm password fields
+ *     - Form validation using Vuelidate or similar
+ *     - Error messages for each field
+ *     - Submit handler that emits form data
+ *
+ *     Follow these style guidelines:
+ *     ${alchemy.file("src/styles/guidelines.md")}
+ *   `,
+ *   system: "You are an expert Vue component creator specializing in form components with validation. Create a single Vue component inside ```vue fences with no additional text.",
+ *   model: {
+ *     id: "claude-3-opus-20240229",
+ *     provider: "anthropic"
+ *   }
+ * });
+ */
+export const VueFile = Resource("ai::VueFile", 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_VUE_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 Vue code
+    let { code, error } = await extractVueCode(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 Vue component inside \`\`\`vue 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 extractVueCode(retryText);
+        if (retryResult.error) {
+            throw new Error(`Failed to generate valid Vue 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 Vue code from between ```vue fences
+ * Validates that exactly one Vue code block exists
+ *
+ * @param text The text to extract Vue code from
+ * @returns The extracted Vue code or error message
+ */
+async function extractVueCode(text) {
+    const vueCodeRegex = /```vue\s*([\s\S]*?)```/g;
+    const matches = Array.from(text.matchAll(vueCodeRegex));
+    if (matches.length === 0) {
+        return {
+            code: "",
+            error: "No Vue code block found in the response. Please include your code within ```vue fences.",
+        };
+    }
+    if (matches.length > 1) {
+        return {
+            code: "",
+            error: "Multiple Vue code blocks found in the response. Please provide exactly one code block within ```vue fences.",
+        };
+    }
+    return { code: matches[0][1].trim() };
+}

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

@@ -0,0 +1,169 @@
+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 YAMLFile
+ */
+export interface YAMLFileProps<T extends Type<any, any> | undefined = undefined> {
+    /**
+     * Path to the YAML file
+     */
+    path: string;
+    /**
+     * Optional ArkType schema to validate and structure the generated YAML
+     * When provided, the resource will use generateObject with schema validation
+     * When not provided, it will extract YAML from between ```yaml 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 YAML configuration for:
+     *   ${alchemy.file("src/serverless.js")}
+     * `
+     */
+    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;
+}
+/**
+ * A YAML file that can be created, updated, and deleted
+ */
+export interface YAMLFile<T = any> extends Omit<YAMLFileProps, "schema">, Resource<"ai::YAMLFile"> {
+    /**
+     * Content of the YAML file as a string
+     */
+    content: string;
+    /**
+     * Parsed YAML object
+     */
+    yaml: T;
+    /**
+     * Schema used to validate the YAML (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 YAML files using AI models.
+ * Can operate in two modes:
+ * 1. With schema: Uses generateObject with type validation, then converts to YAML
+ * 2. Without schema: Extracts YAML from between ```yaml fences
+ *
+ * @example
+ * // Generate a serverless configuration file
+ * const serverlessConfig = await YAMLFile("serverless-config", {
+ *   path: "./serverless.yml",
+ *   prompt: await alchemy`
+ *     Generate a serverless.yml configuration for an AWS Lambda API with:
+ *     - A service name "user-api"
+ *     - Node.js 16.x runtime
+ *     - Three functions: createUser, getUser, and listUsers
+ *     - API Gateway endpoints for each function
+ *     - DynamoDB table for users
+ *     - IAM permissions for DynamoDB access
+ *   `,
+ *   model: {
+ *     id: "gpt-4o",
+ *     provider: "openai"
+ *   }
+ * });
+ *
+ * @example
+ * // Generate YAML with schema validation
+ * import { type } from "arktype";
+ *
+ * const k8sConfigSchema = type({
+ *   apiVersion: "string",
+ *   kind: "string",
+ *   metadata: {
+ *     name: "string",
+ *     namespace: "string?",
+ *     labels: "Record<string, string>?"
+ *   },
+ *   spec: {
+ *     replicas: "number",
+ *     selector: {
+ *       matchLabels: "Record<string, string>"
+ *     },
+ *     template: {
+ *       metadata: {
+ *         labels: "Record<string, string>"
+ *       },
+ *       spec: {
+ *         containers: [{
+ *           name: "string",
+ *           image: "string",
+ *           ports: [{
+ *             containerPort: "number"
+ *           }]
+ *         }]
+ *       }
+ *     }
+ *   }
+ * });
+ *
+ * const deployment = await YAMLFile("k8s-deployment", {
+ *   path: "./kubernetes/deployment.yaml",
+ *   schema: k8sConfigSchema,
+ *   prompt: "Generate a Kubernetes deployment for a web application named 'frontend' with 3 replicas using the nginx:latest image and exposing port 80",
+ *   temperature: 0.2
+ * });
+ *
+ * @example
+ * // Generate GitHub Actions workflow with custom system prompt
+ * const workflow = await YAMLFile("github-workflow", {
+ *   path: "./.github/workflows/ci.yml",
+ *   prompt: await alchemy`
+ *     Create a GitHub Actions workflow for a Node.js project that:
+ *     - Runs on push to main and pull requests
+ *     - Sets up Node.js 18
+ *     - Installs dependencies with npm
+ *     - Runs linting and tests
+ *     - Builds the project
+ *     - Deploys to GitHub Pages on success (main branch only)
+ *   `,
+ *   system: "You are a DevOps expert specializing in GitHub Actions workflows. Create a single YAML file inside ```yaml fences with no additional text. Follow GitHub Actions best practices and use proper YAML syntax.",
+ *   model: {
+ *     id: "claude-3-opus-20240229",
+ *     provider: "anthropic"
+ *   }
+ * });
+ */
+export declare const YAMLFile: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | (<const T extends Type<any, any> | undefined = undefined>(this: Context<YAMLFile<T extends Type<any, any> ? type.infer<T> : any>>, id: string, props: YAMLFileProps<T>) => Promise<YAMLFile<T extends Type<any, any> ? type.infer<T> : any>>);