alchemy 0.3.0 → 0.4.0

package/lib/ai/document.js

@@ -1,9 +1,7 @@
 import { generateText } from "ai";
-import fs from "node:fs/promises";
-import path from "node:path";
+import { StaticTextFile } from "../fs/static-text-file";
 import { Resource } from "../resource";
-import { ignore } from "../util/ignore";
-import { createModel } from "./client";
+import { createModel, withRateLimitRetry } from "./client";
 /**
  * Default system prompt for markdown document generation
  */
@@ -13,7 +11,22 @@ const DEFAULT_MD_SYSTEM_PROMPT = "You are a technical documentation writer. Crea
  * Supports powerful context handling through the alchemy template literal tag.
  *
  * @example
- * // Create a document using alchemy template literals for context
+ * // Create an in-memory document (no file created)
+ * const apiDocs = await Document("api-docs", {
+ *   title: "API Documentation",
+ *   prompt: await alchemy`
+ *     Generate API documentation based on these source files:
+ *     ${alchemy.file("src/api.ts")}
+ *     ${alchemy.file("src/types.ts")}
+ *   `,
+ *   model: {
+ *     id: "gpt-4o",
+ *     provider: "openai"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a document and write it to disk
  * const apiDocs = await Document("api-docs", {
  *   title: "API Documentation",
  *   path: "./docs/api.md",
@@ -29,6 +42,23 @@ const DEFAULT_MD_SYSTEM_PROMPT = "You are a technical documentation writer. Crea
  * });
  *
  * @example
+ * // Use message history for iterative document generation
+ * const apiDocs = await Document("api-docs", {
+ *   title: "API Documentation",
+ *   path: "./docs/api.md",
+ *   messages: [
+ *     { role: "user", content: "Create API documentation for these files" },
+ *     { role: "assistant", content: "I'll help you create API documentation. Please provide the files." },
+ *     { role: "user", content: "Here are the files: [file contents]" }
+ *   ],
+ *   system: "You are a technical documentation writer. Generate clear and concise API documentation.",
+ *   model: {
+ *     id: "gpt-4o",
+ *     provider: "openai"
+ *   }
+ * });
+ *
+ * @example
  * // Use alchemy template literals with file collections and temperature control
  * const modelDocs = await Document("models", {
  *   title: "Data Models",
@@ -61,67 +91,84 @@ const DEFAULT_MD_SYSTEM_PROMPT = "You are a technical documentation writer. Crea
  * });
  */
 export const Document = Resource("docs::Document", async function (id, props) {
-    // Ensure directory exists
-    await fs.mkdir(path.dirname(props.path), { recursive: true });
+    // Validate that either prompt or messages are provided
+    if (!props.prompt && !props.messages) {
+        throw new Error("Either prompt or messages must be provided");
+    }
+    // Handle deletion phase
     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();
     }
+    if (this.phase === "update" && props.freeze) {
+        if (props.path) {
+            const filePath = props.path;
+            const fileId = `${id}-file`;
+            await StaticTextFile(fileId, filePath, this.output.content);
+        }
+        return this(this.output);
+    }
     // Use provided system prompt or default
     const system = props.system || DEFAULT_MD_SYSTEM_PROMPT;
-    // Generate initial content
-    const { text } = await generateText({
-        model: createModel(props),
-        prompt: props.prompt,
-        system,
-        providerOptions: props.model?.options,
-        ...(props.temperature === undefined
-            ? {}
-            : // some models error if you provide it (rather than ignoring it)
-                { temperature: props.temperature }),
+    // Generate initial content with rate limit retry
+    const { text } = await withRateLimitRetry(async () => {
+        return generateText({
+            model: createModel(props),
+            ...(props.messages
+                ? { messages: props.messages }
+                : { prompt: props.prompt }),
+            system,
+            maxTokens: props.maxTokens || 8192,
+            providerOptions: props.model?.options,
+            ...(props.temperature === undefined
+                ? {}
+                : // some models error if you provide it (rather than ignoring it)
+                    { temperature: props.temperature }),
+        });
     });
     // Extract and validate markdown content
-    let { content, error } = await extractMarkdownContent(text);
+    let { content, error } = extractMarkdownContent(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 markdown document inside \`\`\`md 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 { text: retryText } = await withRateLimitRetry(async () => {
+            return generateText({
+                model: createModel(props),
+                ...(props.messages
+                    ? { messages: props.messages }
+                    : { prompt: props.prompt }),
+                system: errorSystem,
+                providerOptions: props.model?.options,
+                ...(props.temperature === undefined
+                    ? {}
+                    : { temperature: props.temperature }),
+            });
         });
-        const retryResult = await extractMarkdownContent(retryText);
+        const retryResult = extractMarkdownContent(retryText);
         if (retryResult.error) {
-            throw new Error(`Failed to generate valid markdown content: ${retryResult.error}`);
+            throw new Error(`Failed to generate valid markdown content: ${retryResult.error}\n${retryText}`);
         }
         content = retryResult.content;
     }
-    if (this.phase === "update" && props.path !== this.props.path) {
-        await ignore("ENOENT", () => fs.unlink(this.props.path));
+    // Create result object
+    const result = {
+        ...props,
+        content,
+        messages: [
+            ...(props.messages || [{ role: "user", content: props.prompt }]),
+            { role: "assistant", content },
+        ],
+        createdAt: this.output?.createdAt || Date.now(),
+        updatedAt: Date.now(),
+        title: props.title || id,
+    };
+    // Write file if path is provided
+    if (props.path) {
+        const filePath = props.path;
+        const fileId = `${id}-file`;
+        result.file = await StaticTextFile(fileId, filePath, content);
     }
-    // Write content to file
-    await fs.writeFile(props.path, content);
-    // Get file stats for timestamps
-    const stats = await fs.stat(props.path);
     // Return the resource
-    return this({
-        ...props,
-        content: content,
-        createdAt: stats.birthtimeMs,
-        updatedAt: stats.mtimeMs,
-    });
+    return this(result);
 });
 /**
  * Extracts markdown content from between ```md fences
@@ -130,20 +177,29 @@ export const Document = Resource("docs::Document", async function (id, props) {
  * @param text The text to extract markdown content from
  * @returns The extracted markdown content or error message
  */
-async function extractMarkdownContent(text) {
-    const mdCodeRegex = /```md\s*([\s\S]*?)```/g;
-    const matches = Array.from(text.matchAll(mdCodeRegex));
-    if (matches.length === 0) {
+function extractMarkdownContent(text) {
+    const lines = text.split("\n");
+    const startIdx = lines.findIndex((line) => line.trim() === "```md");
+    if (startIdx === -1) {
         return {
             content: "",
             error: "No markdown code block found in the response. Please include your markdown content within ```md fences.",
         };
     }
-    if (matches.length > 1) {
+    const rest = lines.slice(startIdx + 1);
+    const endRelativeIdx = rest
+        .map((line) => line.trim() === "```")
+        .lastIndexOf(true);
+    if (endRelativeIdx === -1) {
         return {
             content: "",
-            error: "Multiple markdown code blocks found in the response. Please provide exactly one markdown block within ```md fences.",
+            error: "Markdown block was not closed properly.",
         };
     }
-    return { content: matches[0][1].trim() };
+    const endIdx = startIdx + 1 + endRelativeIdx;
+    const content = lines
+        .slice(startIdx + 1, endIdx)
+        .join("\n")
+        .trim();
+    return { content };
 }

package/lib/ai/html-file.js

@@ -1,8 +1,6 @@
 import { generateText } from "ai";
-import fs from "node:fs/promises";
-import path from "node:path";
+import { StaticHTMLFile } from "../fs/static-html-file";
 import { Resource } from "../resource";
-import { ignore } from "../util/ignore";
 import { createModel } from "./client";
 /**
  * Default system prompt for HTML file generation
@@ -68,18 +66,8 @@ const DEFAULT_HTML_SYSTEM_PROMPT = "You are an HTML code generator. Create HTML
  * });
  */
 export const HTMLFile = Resource("ai::HTMLFile", async function (id, props) {
-    // Ensure directory exists
-    await fs.mkdir(path.dirname(props.path), { recursive: true });
+    // Handle deletion phase
     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
@@ -114,19 +102,14 @@ export const HTMLFile = Resource("ai::HTMLFile", async function (id, props) {
         }
         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);
+    // Use StaticHTMLFile to create/update the file
+    const file = await StaticHTMLFile("file", props.path, code);
     // Return the resource
     return this({
         ...props,
-        content: code,
-        createdAt: stats.birthtimeMs,
-        updatedAt: stats.mtimeMs,
+        content: file.content,
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
     });
 });
 /**

package/lib/ai/json-file.js

@@ -1,8 +1,6 @@
 import { generateObject, generateText } from "ai";
-import fs from "node:fs/promises";
-import path from "node:path";
+import { StaticJsonFile } from "../fs/static-json-file";
 import { Resource } from "../resource";
-import { ignore } from "../util/ignore";
 import { ark } from "./ark";
 import { createModel } from "./client";
 /**
@@ -77,23 +75,10 @@ const DEFAULT_JSON_SYSTEM_PROMPT = "You are a JSON generator. Create valid JSON
  * });
  */
 export const JSONFile = Resource("ai::JSONFile", async function (id, props) {
-    // Ensure directory exists
-    await fs.mkdir(path.dirname(props.path), { recursive: true });
+    // Handle deletion phase
     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
@@ -111,9 +96,9 @@ export const JSONFile = Resource("ai::JSONFile", async function (id, props) {
                 : { temperature: props.temperature }),
         });
         jsonObject = object;
-        jsonContent = pretty
-            ? JSON.stringify(jsonObject, null, indent)
-            : JSON.stringify(jsonObject);
+        // Use StaticJsonFile to create the file
+        const file = await StaticJsonFile("file", props.path, jsonObject);
+        jsonContent = file.content;
     }
     else {
         // Use fence-based extraction
@@ -149,26 +134,20 @@ export const JSONFile = Resource("ai::JSONFile", async function (id, props) {
             }
             content = retryResult.content;
         }
-        // Parse JSON
+        // Parse JSON to get the object representation
         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));
+        // Use StaticJsonFile to create the file
+        const file = await StaticJsonFile("file", props.path, jsonObject);
+        jsonContent = file.content;
     }
-    // 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,
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
     });
 });
 /**

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

@@ -1,4 +1,3 @@
-import prettier from "prettier";
 import type { Context } from "../context";
 import { Resource } from "../resource";
 import type { Secret } from "../secret";
@@ -53,7 +52,7 @@ export interface TypeScriptFileProps {
      * Prettier configuration to use for formatting the TypeScript code
      * If not provided, will use the default Prettier configuration
      */
-    prettierConfig?: prettier.Options;
+    prettierConfig?: object;
 }
 /**
  * A TypeScript file that can be created, updated, and deleted

package/lib/ai/typescript-file.js

@@ -1,9 +1,6 @@
 import { generateText } from "ai";
-import fs from "node:fs/promises";
-import path from "node:path";
-import prettier from "prettier";
+import { StaticTypeScriptFile } from "../fs/static-typescript-file";
 import { Resource } from "../resource";
-import { ignore } from "../util/ignore";
 import { createModel } from "./client";
 /**
  * Default system prompt for TypeScript file generation
@@ -75,18 +72,9 @@ const DEFAULT_TS_SYSTEM_PROMPT = "You are a TypeScript code generator. Create Ty
  * });
  */
 export const TypeScriptFile = Resource("ai::TypeScriptFile", async function (id, props) {
-    // Ensure directory exists
-    await fs.mkdir(path.dirname(props.path), { recursive: true });
+    // Handle delete phase
     if (this.phase === "delete") {
-        try {
-            await fs.unlink(props.path);
-        }
-        catch (error) {
-            // Ignore if file doesn't exist
-            if (error.code !== "ENOENT") {
-                throw error;
-            }
-        }
+        // StaticTypeScriptFile will handle the deletion
         return this.destroy();
     }
     // Use provided system prompt or default
@@ -121,33 +109,14 @@ export const TypeScriptFile = Resource("ai::TypeScriptFile", async function (id,
         }
         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);
+    // Use StaticTypeScriptFile to create/update the file
+    const file = await StaticTypeScriptFile("file", props.path, code);
     // Return the resource
     return this({
         ...props,
-        content: code,
-        createdAt: stats.birthtimeMs,
-        updatedAt: stats.mtimeMs,
+        content: file.content,
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
     });
 });
 /**

package/lib/ai/vue-file.js

@@ -1,8 +1,6 @@
 import { generateText } from "ai";
-import fs from "node:fs/promises";
-import path from "node:path";
+import { StaticVueFile } from "../fs/static-vue-file";
 import { Resource } from "../resource";
-import { ignore } from "../util/ignore";
 import { createModel } from "./client";
 /**
  * Default system prompt for Vue file generation
@@ -66,18 +64,8 @@ const DEFAULT_VUE_SYSTEM_PROMPT = "You are a Vue component generator. Create a s
  * });
  */
 export const VueFile = Resource("ai::VueFile", async function (id, props) {
-    // Ensure directory exists
-    await fs.mkdir(path.dirname(props.path), { recursive: true });
+    // Handle deletion phase
     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
@@ -112,19 +100,14 @@ export const VueFile = Resource("ai::VueFile", async function (id, props) {
         }
         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);
+    // Use StaticVueFile to create/update the file
+    const file = await StaticVueFile("file", props.path, code);
     // Return the resource
     return this({
         ...props,
-        content: code,
-        createdAt: stats.birthtimeMs,
-        updatedAt: stats.mtimeMs,
+        content: file.content,
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
     });
 });
 /**

package/lib/ai/yaml-file.js

@@ -1,8 +1,6 @@
 import { generateObject, generateText } from "ai";
-import fs from "node:fs/promises";
-import path from "node:path";
+import { StaticYamlFile } from "../fs/static-yaml-file";
 import { Resource } from "../resource";
-import { ignore } from "../util/ignore";
 import { ark } from "./ark";
 import { createModel } from "./client";
 /**
@@ -96,29 +94,10 @@ const DEFAULT_YAML_SYSTEM_PROMPT = "You are a YAML generator. Create valid YAML
  * });
  */
 export const YAMLFile = Resource("ai::YAMLFile", async function (id, props) {
-    // Ensure directory exists
-    await fs.mkdir(path.dirname(props.path), { recursive: true });
+    // Handle deletion phase
     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
@@ -136,15 +115,9 @@ export const YAMLFile = Resource("ai::YAMLFile", async function (id, props) {
                 : { 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}`);
-        }
+        // Let StaticYamlFile handle the YAML conversion
+        const file = await StaticYamlFile("file", props.path, yamlObject);
+        yamlContent = file.content;
     }
     else {
         // Use fence-based extraction
@@ -181,29 +154,20 @@ export const YAMLFile = Resource("ai::YAMLFile", async function (id, props) {
             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));
+        // 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);
     }
-    // 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,
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
     });
 });
 /**

package/lib/alchemy.d.ts

@@ -31,6 +31,10 @@ export interface Alchemy {
     scope: typeof scope;
     run: typeof run;
     destroy: typeof destroy;
+    /**
+     * Get an environment variable and error if it's not set.
+     */
+    env: typeof env;
     /**
      * Creates an encrypted secret that can be safely stored in state files.
      * Requires a password to be set either globally in the application options
@@ -146,4 +150,5 @@ declare function run<T>(...args: [id: string, fn: (this: Scope, scope: Scope) =>
     options: AlchemyOptions,
     fn: (this: Scope, scope: Scope) => Promise<T>
 ]): Promise<T>;
+export declare function env<T = string>(name: string, value?: T | undefined, error?: string): Promise<T>;
 export {};