alchemy 0.2.5 → 0.3.1

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>>);

package/lib/ai/yaml-file.js

@@ -0,0 +1,200 @@
+import { generateObject, generateText } from "ai";
+import { StaticYamlFile } from "../fs/static-yaml-file";
+import { Resource } from "../resource";
+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) {
+    // Handle deletion phase
+    if (this.phase === "delete") {
+        return this.destroy();
+    }
+    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;
+        // Let StaticYamlFile handle the YAML conversion
+        const file = await StaticYamlFile("file", props.path, yamlObject);
+        yamlContent = file.content;
+    }
+    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;
+        // Create the file with the string content
+        const file = await StaticYamlFile("file", props.path, yamlContent);
+        // We need to parse the YAML to get the object representation
+        const yaml = await import("yaml");
+        yamlObject = yaml.parse(yamlContent);
+    }
+    // Return the resource
+    return this({
+        ...props,
+        schema: props.schema,
+        content: yamlContent,
+        yaml: yamlObject,
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+    });
+});
+/**
+ * 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/alchemy.js

@@ -33,6 +33,17 @@ function _alchemy(...args) {
                 if (typeof value === "string") {
                     return indent + value;
                 }
+                else if (value === null) {
+                    return "null";
+                }
+                else if (value === undefined) {
+                    return "undefined";
+                }
+                else if (typeof value === "number" ||
+                    typeof value === "boolean" ||
+                    typeof value === "bigint") {
+                    return value.toString();
+                }
                 else if (value instanceof Promise) {
                     return resolve(await value);
                 }
@@ -55,7 +66,8 @@ function _alchemy(...args) {
                 }
                 else {
                     // TODO: support other types
-                    throw new Error(`Unsupported value type: ${JSON.stringify(value)}`);
+                    console.log(value);
+                    throw new Error(`Unsupported value type: ${value}`);
                 }
             }));
             // Construct the string template by joining template parts with interpolated values
@@ -104,7 +116,10 @@ _alchemy.secret = secret;
  *   apiKey: alchemy.secret(process.env.API_KEY)
  * });
  */
-function scope(id, options) {
+function scope(id, options
+// TODO: maybe we want to allow using _ = await alchemy.scope(import.meta)
+// | [meta: ImportMeta]
+) {
     const scope = new Scope({
         ...options,
         appName: options?.appName,

package/lib/apply.js

@@ -46,7 +46,7 @@ export async function apply(resource, props, options) {
             }), null, 2);
             if (oldProps === newProps && alwaysUpdate !== true) {
                 if (!quiet) {
-                    console.log(`Skip:    "${resource.FQN}" (no changes)`);
+                    // console.log(`Skip:    "${resource.FQN}" (no changes)`);
                 }
                 return state.output;
             }

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,
+    };
+}