alchemy 0.2.5 → 0.3.0

package/lib/ai/yaml-file.js

@@ -0,0 +1,236 @@
+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 YAML file generation without schema
+ */
+const DEFAULT_YAML_SYSTEM_PROMPT = "You are a YAML generator. Create valid YAML based on the user's requirements. Your response MUST include only YAML inside ```yaml fences. Do not include any other text, explanations, or multiple code blocks. Use standard YAML syntax with proper indentation. Use quotes around strings that contain special characters when necessary.";
+/**
+ * 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 const YAMLFile = Resource("ai::YAMLFile", 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();
+    }
+    // Dynamic import js-yaml to avoid dependency issues
+    // This allows the code to work even if js-yaml is not installed
+    let yaml;
+    try {
+        yaml = await import("yaml");
+    }
+    catch (err) {
+        throw new Error("The 'yaml' package is required for the YAMLFile resource. Please install it with: bun add yaml");
+    }
+    let yamlContent;
+    let yamlObject;
+    // 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 object based on the provided requirements.",
+            prompt: props.prompt,
+            ...(props.temperature === undefined
+                ? {}
+                : { temperature: props.temperature }),
+        });
+        yamlObject = object;
+        // Convert object to YAML
+        try {
+            yamlContent = yaml.stringify(yamlObject, {
+                indent: 2,
+            });
+        }
+        catch (error) {
+            throw new Error(`Failed to convert object to YAML: ${error.message}`);
+        }
+    }
+    else {
+        // Use fence-based extraction
+        // Use provided system prompt or default
+        const system = props.system || DEFAULT_YAML_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 YAML content
+        let { content, error } = await extractYAMLContent(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 YAML block inside \`\`\`yaml 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 extractYAMLContent(retryText);
+            if (retryResult.error) {
+                throw new Error(`Failed to generate valid YAML: ${retryResult.error}`);
+            }
+            content = retryResult.content;
+        }
+        yamlContent = content;
+        // Parse YAML to validate and get object representation
+        try {
+            yamlObject = yaml.parse(yamlContent);
+        }
+        catch (error) {
+            throw new Error(`Failed to parse YAML: ${error.message}`);
+        }
+    }
+    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, yamlContent);
+    // Get file stats for timestamps
+    const stats = await fs.stat(props.path);
+    // Return the resource
+    return this({
+        ...props,
+        schema: props.schema,
+        content: yamlContent,
+        yaml: yamlObject,
+        createdAt: stats.birthtimeMs,
+        updatedAt: stats.mtimeMs,
+    });
+});
+/**
+ * Extracts YAML content from between ```yaml fences
+ * Validates that exactly one YAML code block exists
+ *
+ * @param text The text to extract YAML from
+ * @returns The extracted YAML or error message
+ */
+async function extractYAMLContent(text) {
+    // Check for yaml or yml fence blocks
+    const yamlCodeRegex = /```(yaml|yml)\s*([\s\S]*?)```/g;
+    const matches = Array.from(text.matchAll(yamlCodeRegex));
+    if (matches.length === 0) {
+        return {
+            content: "",
+            error: "No YAML code block found in the response. Please include your YAML within ```yaml fences.",
+        };
+    }
+    if (matches.length > 1) {
+        return {
+            content: "",
+            error: "Multiple YAML code blocks found in the response. Please provide exactly one YAML block within ```yaml fences.",
+        };
+    }
+    const content = matches[0][2].trim();
+    // We don't validate YAML parsing here because js-yaml might not be available
+    // Validation will happen at usage time if needed
+    return { content };
+}

package/lib/cloudflare/dns.d.ts

@@ -0,0 +1,88 @@
+import type { Context } from "../context";
+import type { DnsRecord as BaseDnsRecord, DnsRecordType, DnsRecordWithMetadata } from "../dns/record";
+import { Resource } from "../resource";
+/**
+ * Properties for a DNS record
+ */
+export interface DnsRecordProps extends Omit<BaseDnsRecord, "type"> {
+    /**
+     * Record type (A, AAAA, CNAME, etc.)
+     */
+    type: DnsRecordType;
+}
+/**
+ * Output returned after DNS record creation/update
+ */
+export interface DnsRecord extends DnsRecordWithMetadata {
+}
+/**
+ * Properties for managing multiple DNS records
+ */
+export interface DnsRecordsProps {
+    /**
+     * Zone ID or domain name where records will be created
+     */
+    zoneId: string;
+    /**
+     * Array of DNS records to manage
+     */
+    records: DnsRecordProps[];
+}
+/**
+ * Output returned after DNS records creation/update
+ */
+export interface DnsRecords extends Resource<"cloudflare::DnsRecords"> {
+    /**
+     * Zone ID where records are created
+     */
+    zoneId: string;
+    /**
+     * Array of created/updated DNS records
+     */
+    records: DnsRecord[];
+}
+/**
+ * Manages a batch of DNS records in a Cloudflare zone.
+ * Supports creating, updating, and deleting multiple records at once.
+ *
+ * @example
+ * // Create multiple A and CNAME records
+ * const dnsRecords = await DnsRecords("example.com-dns", {
+ *   zone: "example.com",
+ *   records: [
+ *     {
+ *       name: "www.example.com",
+ *       type: "A",
+ *       content: "192.0.2.1",
+ *       proxied: true
+ *     },
+ *     {
+ *       name: "blog.example.com",
+ *       type: "CNAME",
+ *       content: "www.example.com",
+ *       proxied: true
+ *     }
+ *   ]
+ * });
+ *
+ * @example
+ * // Create MX records for email routing
+ * const emailRecords = await DnsRecords("example.com-email", {
+ *   zone: "example.com",
+ *   records: [
+ *     {
+ *       name: "example.com",
+ *       type: "MX",
+ *       content: "aspmx.l.google.com",
+ *       priority: 1
+ *     },
+ *     {
+ *       name: "example.com",
+ *       type: "MX",
+ *       content: "alt1.aspmx.l.google.com",
+ *       priority: 5
+ *     }
+ *   ]
+ * });
+ */
+export declare const DnsRecords: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<DnsRecords>, id: string, props: DnsRecordsProps) => Promise<DnsRecords>);

package/lib/cloudflare/dns.js

@@ -0,0 +1,192 @@
+import { Resource } from "../resource";
+import { createCloudflareApi } from "./api";
+/**
+ * Manages a batch of DNS records in a Cloudflare zone.
+ * Supports creating, updating, and deleting multiple records at once.
+ *
+ * @example
+ * // Create multiple A and CNAME records
+ * const dnsRecords = await DnsRecords("example.com-dns", {
+ *   zone: "example.com",
+ *   records: [
+ *     {
+ *       name: "www.example.com",
+ *       type: "A",
+ *       content: "192.0.2.1",
+ *       proxied: true
+ *     },
+ *     {
+ *       name: "blog.example.com",
+ *       type: "CNAME",
+ *       content: "www.example.com",
+ *       proxied: true
+ *     }
+ *   ]
+ * });
+ *
+ * @example
+ * // Create MX records for email routing
+ * const emailRecords = await DnsRecords("example.com-email", {
+ *   zone: "example.com",
+ *   records: [
+ *     {
+ *       name: "example.com",
+ *       type: "MX",
+ *       content: "aspmx.l.google.com",
+ *       priority: 1
+ *     },
+ *     {
+ *       name: "example.com",
+ *       type: "MX",
+ *       content: "alt1.aspmx.l.google.com",
+ *       priority: 5
+ *     }
+ *   ]
+ * });
+ */
+export const DnsRecords = Resource("cloudflare::DnsRecords", async function (id, props) {
+    // Create Cloudflare API client
+    const api = await createCloudflareApi();
+    // Get zone ID if domain name was provided
+    const zoneId = props.zoneId;
+    if (this.phase === "delete") {
+        if (this.output?.records) {
+            // Delete all existing records
+            await Promise.all(this.output.records.map(async (record) => {
+                try {
+                    const response = await api.delete(`/zones/${zoneId}/dns_records/${record.id}`);
+                    if (!response.ok && response.status !== 404) {
+                        console.error(`Failed to delete DNS record ${record.name}: ${response.statusText}`);
+                    }
+                }
+                catch (error) {
+                    console.error(`Error deleting DNS record ${record.name}:`, error);
+                }
+            }));
+        }
+        return this.destroy();
+    }
+    if (this.phase === "update" && this.output?.records) {
+        // Get current records to compare with desired state
+        const currentRecords = this.output.records;
+        const desiredRecords = props.records;
+        // Find records to delete (exist in current but not in desired)
+        const recordsToDelete = currentRecords.filter((current) => !desiredRecords.some((desired) => desired.name === current.name && desired.type === current.type));
+        // Delete orphaned records
+        await Promise.all(recordsToDelete.map(async (record) => {
+            try {
+                const response = await api.delete(`/zones/${zoneId}/dns_records/${record.id}`);
+                if (!response.ok && response.status !== 404) {
+                    console.error(`Failed to delete DNS record ${record.name}: ${response.statusText}`);
+                }
+            }
+            catch (error) {
+                console.error(`Error deleting DNS record ${record.name}:`, error);
+            }
+        }));
+        // Update or create records
+        const updatedRecords = await Promise.all(desiredRecords.map(async (desired) => {
+            // Find matching existing record
+            const existing = currentRecords.find((current) => current.name === desired.name && current.type === desired.type);
+            if (existing) {
+                // Update if content or other properties changed
+                if (existing.content !== desired.content ||
+                    existing.ttl !== (desired.ttl || 1) ||
+                    existing.proxied !== (desired.proxied || false) ||
+                    existing.priority !== desired.priority ||
+                    existing.comment !== desired.comment) {
+                    return createOrUpdateRecord(api, zoneId, desired, existing.id);
+                }
+                return existing;
+            }
+            else {
+                // Create new record
+                return createOrUpdateRecord(api, zoneId, desired);
+            }
+        }));
+        return this({
+            zoneId,
+            records: updatedRecords,
+        });
+    }
+    // Create new records
+    const uniqueRecords = props.records.reduce((acc, record) => {
+        const key = `${record.name}-${record.type}`;
+        acc[key] = record;
+        return acc;
+    }, {});
+    const createdRecords = await Promise.all(Object.values(uniqueRecords).map(async (record) => {
+        // First check if record exists
+        const listResponse = await api.get(`/zones/${zoneId}/dns_records?type=${record.type}&name=${record.name}`);
+        if (!listResponse.ok) {
+            throw new Error(`Failed to check existing DNS records: ${listResponse.statusText}`);
+        }
+        const listResult = (await listResponse.json());
+        const existingRecord = listResult.result[0];
+        return createOrUpdateRecord(api, zoneId, record, existingRecord?.id);
+    }));
+    return this({
+        zoneId,
+        records: createdRecords,
+    });
+});
+/**
+ * Create or update a DNS record
+ */
+async function createOrUpdateRecord(api, zoneId, record, existingId) {
+    const payload = getRecordPayload(record);
+    const response = await (existingId
+        ? api.put(`/zones/${zoneId}/dns_records/${existingId}`, payload)
+        : api.post(`/zones/${zoneId}/dns_records`, payload));
+    if (!response.ok) {
+        const errorBody = await response.text();
+        // If it's an update operation and the record doesn't exist, fall back to creation
+        if (existingId && response.status === 404) {
+            try {
+                const createResponse = await api.post(`/zones/${zoneId}/dns_records`, payload);
+                if (createResponse.ok) {
+                    return convertCloudflareRecord((await createResponse.json()).result, zoneId);
+                }
+            }
+            catch (err) {
+                // Fall through to the original error
+            }
+        }
+        throw new Error(`Failed to ${existingId ? "update" : "create"} DNS record ${record.name}: ${response.statusText}\nResponse: ${errorBody}`);
+    }
+    const result = (await response.json());
+    return convertCloudflareRecord(result.result, zoneId);
+}
+/**
+ * Get the record payload for create/update operations
+ */
+function getRecordPayload(record) {
+    return {
+        type: record.type,
+        name: record.name,
+        content: record.content,
+        ttl: record.ttl || 1,
+        proxied: record.proxied || false,
+        priority: record.priority,
+        comment: record.comment,
+    };
+}
+/**
+ * Convert a Cloudflare DNS record response to our DnsRecord type
+ */
+function convertCloudflareRecord(record, zoneId) {
+    return {
+        id: record.id,
+        name: record.name,
+        type: record.type,
+        content: record.content,
+        ttl: record.ttl,
+        proxied: record.proxied,
+        priority: record.priority,
+        comment: record.comment,
+        tags: record.tags,
+        createdAt: new Date(record.created_on).getTime(),
+        modifiedAt: new Date(record.modified_on).getTime(),
+        zoneId,
+    };
+}

package/lib/cloudflare/index.d.ts

@@ -1,8 +1,9 @@
 export * from "./bindings";
 export * from "./bucket";
+export * from "./dns";
 export * from "./durable-object-namespace";
 export * from "./kv-namespace";
-export * from "./state";
+export * from "./r2-rest-state-store";
 export * from "./static-site";
 export * from "./worker";
 export * from "./wrangler.json";

package/lib/cloudflare/index.js

@@ -1,8 +1,9 @@
 export * from "./bindings";
 export * from "./bucket";
+export * from "./dns";
 export * from "./durable-object-namespace";
 export * from "./kv-namespace";
-export * from "./state";
+export * from "./r2-rest-state-store";
 export * from "./static-site";
 export * from "./worker";
 export * from "./wrangler.json";

package/lib/cloudflare/r2-rest-state-store.d.ts

@@ -0,0 +1,125 @@
+import type { Scope } from "../scope";
+import type { State, StateStore } from "../state";
+/**
+ * Options for CloudflareR2StateStore
+ */
+export interface CloudflareR2StateStoreOptions {
+    /**
+     * The prefix to use for object keys in the R2 bucket
+     * This allows multiple state stores to use the same R2 bucket
+     */
+    prefix?: string;
+    /**
+     * The R2 bucket name to use
+     * Required - the bucket must already exist
+     */
+    bucketName: string;
+    /**
+     * API key to use (overrides CLOUDFLARE_API_KEY env var)
+     */
+    apiKey?: string;
+    /**
+     * Account ID to use (overrides CLOUDFLARE_ACCOUNT_ID env var)
+     */
+    accountId?: string;
+    /**
+     * Email to use with API Key authentication (overrides CLOUDFLARE_EMAIL env var)
+     */
+    email?: string;
+}
+/**
+ * State store implementation using Cloudflare R2 API
+ * Uses R2 for immediate consistency compared to KV's eventual consistency
+ */
+export declare class R2RestStateStore implements StateStore {
+    readonly scope: Scope;
+    private api;
+    private prefix;
+    private bucketName;
+    private apiKey;
+    private accountId;
+    private email;
+    private initialized;
+    /**
+     * Create a new CloudflareR2StateStore
+     *
+     * @param scope The scope this store belongs to
+     * @param options Options for the state store
+     */
+    constructor(scope: Scope, options: CloudflareR2StateStoreOptions);
+    /**
+     * Initialize the R2 client
+     */
+    init(): Promise<void>;
+    /**
+     * R2 buckets cannot be deleted programmatically via this method
+     */
+    deinit(): Promise<void>;
+    /**
+     * List all resources in the state store
+     */
+    list(): Promise<string[]>;
+    /**
+     * Count the number of items in the state store
+     */
+    count(): Promise<number>;
+    /**
+     * Get a state by key
+     *
+     * @param key The key to look up
+     * @returns The state or undefined if not found
+     */
+    get(key: string): Promise<State | undefined>;
+    /**
+     * Get multiple states by their keys
+     *
+     * @param ids Array of keys to fetch
+     * @returns Record mapping keys to their states
+     */
+    getBatch(ids: string[]): Promise<Record<string, State>>;
+    /**
+     * Get all states in the store
+     *
+     * @returns Record mapping all keys to their states
+     */
+    all(): Promise<Record<string, State>>;
+    /**
+     * Set a state for a key
+     *
+     * @param key The key to set
+     * @param value The state to store
+     */
+    set(key: string, value: State): Promise<void>;
+    /**
+     * Delete a state by key
+     *
+     * @param key The key to delete
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Convert key for storage by replacing slashes with colons
+     * since R2 treats slashes as directory separators
+     *
+     * @param key The original key
+     * @returns Key with slashes replaced by colons
+     */
+    private convertKeyForStorage;
+    /**
+     * Convert key from storage by replacing colons with slashes
+     *
+     * @param key The storage key
+     * @returns Key with colons replaced by slashes
+     */
+    private convertKeyFromStorage;
+    /**
+     * Get the full object key for storage
+     *
+     * @param key The original key
+     * @returns The key with prefix for use in the R2 bucket
+     */
+    private getObjectKey;
+    /**
+     * Ensure the store is initialized before operations
+     */
+    private ensureInitialized;
+}