alchemy 0.2.5 → 0.3.0

package/src/ai/yaml-file.ts

@@ -0,0 +1,368 @@
+import { generateObject, generateText } from "ai";
+import type { JsonSchema, Type, type } from "arktype";
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { Context } from "../context";
+import { Resource } from "../resource";
+import type { Secret } from "../secret";
+import { ignore } from "../util/ignore";
+import { ark } from "./ark";
+import { type ModelConfig, createModel } 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;
+}
+
+/**
+ * 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 <
+  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>
+> {
+  // Ensure directory exists
+  await fs.mkdir(path.dirname(props.path), { recursive: true });
+
+  if (this.phase === "delete") {
+    try {
+      await fs.unlink(props.path);
+    } catch (error: any) {
+      // 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: typeof import("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: string;
+  let yamlObject: any;
+
+  // Check if schema is provided
+  if (props.schema) {
+    // Use schema-based generation
+    const { object } = await generateObject({
+      model: createModel(props),
+      schema: ark.schema<type.infer<typeof props.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 as 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 as 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: string,
+): Promise<{ content: string; error?: string }> {
+  // 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/src/apply.ts

@@ -119,7 +119,6 @@ export async function apply<Out extends Resource>(
     const output = await alchemy.run(resource.ID, async () =>
       provider.handler.bind(ctx)(resource.ID, props),
     );
-
     if (!quiet) {
       console.log(
         `${phase === "create" ? "Created" : "Updated"}: "${resource.FQN}"`,

package/src/cloudflare/dns.ts

@@ -0,0 +1,344 @@
+import type { Context } from "../context";
+import type {
+  DnsRecord as BaseDnsRecord,
+  DnsRecordType,
+  DnsRecordWithMetadata,
+} from "../dns/record";
+import { Resource } from "../resource";
+import { type CloudflareApi, createCloudflareApi } from "./api";
+import type { CloudflareResponse } from "./response";
+
+/**
+ * Cloudflare DNS Record response format
+ */
+interface CloudflareDnsRecord {
+  id: string;
+  type: string;
+  name: string;
+  content: string;
+  proxiable: boolean;
+  proxied: boolean;
+  ttl: number;
+  locked: boolean;
+  zone_id: string;
+  zone_name: string;
+  created_on: string;
+  modified_on: string;
+  data?: Record<string, unknown>;
+  priority?: number;
+  comment?: string;
+  tags?: string[];
+}
+
+/**
+ * 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 const DnsRecords = Resource(
+  "cloudflare::DnsRecords",
+  async function (
+    this: Context<DnsRecords>,
+    id: string,
+    props: DnsRecordsProps,
+  ): Promise<DnsRecords> {
+    // 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;
+      },
+      {} as Record<string, DnsRecordProps>,
+    );
+
+    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()) as CloudflareResponse<
+          CloudflareDnsRecord[]
+        >;
+        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: CloudflareApi,
+  zoneId: string,
+  record: DnsRecordProps,
+  existingId?: string,
+): Promise<DnsRecord> {
+  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()) as any).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()) as CloudflareResponse<CloudflareDnsRecord>;
+  return convertCloudflareRecord(result.result, zoneId);
+}
+
+/**
+ * Get the record payload for create/update operations
+ */
+function getRecordPayload(record: DnsRecordProps) {
+  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: CloudflareDnsRecord,
+  zoneId: string,
+): DnsRecord {
+  return {
+    id: record.id,
+    name: record.name,
+    type: record.type as DnsRecordProps["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,
+  };
+}