alchemy 0.2.5 → 0.3.1

package/lib/internal/providers.js

@@ -0,0 +1,172 @@
+import { type } from "arktype";
+import fs from "fs/promises";
+import path from "path";
+import { Data, Document } from "../ai";
+import { alchemy } from "../alchemy";
+import { Folder } from "../fs";
+export async function AlchemyProviderDocs({ srcDir, outDir, filter, }) {
+    outDir = typeof outDir === "string" ? outDir : outDir.path;
+    const exclude = [
+        "util",
+        "test",
+        "vitepress",
+        "vite",
+        "shadcn",
+        "internal",
+        "web",
+    ];
+    // Get all folders in the alchemy/src directory
+    let providers = (await fs.readdir(srcDir, {
+        withFileTypes: true,
+    }))
+        .filter((dirent) => dirent.isDirectory() && !exclude.includes(dirent.name))
+        .map((dirent) => path.join(dirent.parentPath, dirent.name));
+    // For each provider, list all files
+    if (filter === false) {
+        return [];
+    }
+    else if (typeof filter === "number") {
+        providers = providers.slice(0, filter);
+    }
+    return await Promise.all(providers.map(async (provider) => {
+        const providerName = path.basename(provider);
+        const files = (await fs.readdir(path.resolve(provider), {
+            withFileTypes: true,
+        }))
+            .filter((dirent) => dirent.isFile())
+            .map((dirent) => path.relative(process.cwd(), path.resolve(provider, dirent.name)))
+            .filter((file) => file.endsWith(".ts") && !file.endsWith("index.ts"));
+        const { object: { groups }, } = await Data(`docs/${providerName}`, {
+            model: {
+                id: "o3-mini",
+                provider: "openai",
+                options: {
+                    reasoningEffort: "high",
+                },
+            },
+            temperature: 0.1,
+            schema: type({
+                groups: type({
+                    title: type("string").describe("The title of the group, should be the Resource Name exactly as it's defined in code (const ResourceName translates to 'Resource Name') without spaces, e.g. Bucket or Static Site."),
+                    filename: type("string").describe("The filename of the Resource's Document, e.g. bucket.md or static-site.md"),
+                    category: type("'Resource'|'Client'|'Utility'|'Types'").describe("The classification of the Resource's Document, one of: Resource, Client, Utility, or Types."),
+                }).array(),
+            }),
+            system: await alchemy `
+          You are a technical writer tasked with identifying the distinct documents that need to be written for a document group (folder) in a documentation site.
+          You will be provided with a list of documents and instructions on how to classify them.
+          Each document has a title, file name, and category.
+        `,
+            prompt: await alchemy `
+          Identify and classify the documents that need to be written for the '${provider}' Service's Alchemy Resources.
+          For background knowledge on Alchemy, see ${alchemy.file("./README.md")}.
+          For background knowledge on the structure of an Alchemy Resource, see ${alchemy.file("./.cursorrules")}.
+
+          The ${provider} Service has the following resources:
+          ${alchemy.files(files)}
+
+          A file is considered a "Resource" if it contains a const <ResourceName> = Resource(...) call or if it is a function that calls a Resource function, e.g. const TypeScriptFile = () => File(...).
+          A file is considered a "Client" if it exposes a wrapper around creating a SDK client or fetch.
+          A file is considered a "Utility" if it contains utility functions that are not resources or clients.
+          A file is considered a "Types" if it contains just type definitions and maybe helpers around working with those types.
+
+          The title should be simply the name of the resource's const in code (with spaces added in between each word), e.g. "Bucket" or "Function", except with spaces, e.g. "Static Site" for "const StaticSite". Maintain all other casing.
+
+          // "Resource Name"
+          const ResourceName = Resource(...)
+        `,
+        });
+        // console.log(groups);
+        const providerDocsDir = (await Folder(path.join(outDir, providerName)))
+            .path;
+        const documents = await Promise.allSettled(groups
+            .filter((g) => g.category === "Resource")
+            .map(async (g) => Document(`docs/${providerName}/${g.title}`, {
+            title: g.title,
+            path: path.join(providerDocsDir, `${g.filename.replace(".ts", "").replace(".md", "")}.md`),
+            model: {
+                id: "claude-3-5-sonnet-latest",
+                provider: "anthropic",
+                // options: {
+                //   reasoningEffort: "high",
+                // },
+            },
+            prompt: await alchemy `
+                You are a technical writer writing API documentation for an Alchemy IaC Resource.
+                See ${alchemy.file("./README.md")} to understand the overview of Alchemy.
+                See ${alchemy.file("./.cursorrules")} to better understand the structure and convention of an Alchemy Resource.
+
+                Relevant files for the ${providerName} Service:
+                ${alchemy.files(files)}
+                
+                Write concise documentation for the "${g.title}" Resource.
+
+                > [!CAUTION]
+                > Avoid the temptation to over explain or over describe. Focus on concise, simple, high value snippets. One heading and 0-1 descriptions per snippet.
+                
+                > [!TIP]
+                > Make sure the examples follow a natural progression from the minimal example to logical next steps of how the Resource might be used.
+
+                Each document must follow the following format:
+                
+                # ${g.title}
+
+                (simple description with an external link to the provider's website)
+                e.g.
+                The Efs component lets you add [Amazon Elastic File System (EFS)](https://docs.aws.amazon.com/efs/latest/ug/whatisefs.html) to your app.
+
+                # Minimal Example
+
+                (brief 1-2 sentences of what it does)
+
+                \`\`\`ts
+                import { ${g.title.replaceAll(" ", "")} } from "alchemy/${providerName}";
+
+                (example)
+                \`\`\`
+
+
+                # Create the ${g.title}
+
+                \`\`\`ts
+                import { ${g.title.replaceAll(" ", "")} } from "alchemy/${providerName}";
+
+                (example)
+                \`\`\`
+
+                ${providerName === "cloudflare"
+                ? await alchemy `# Bind to a Worker
+                (if it is a Cloudflare Resource)
+
+                \`\`\`ts
+                import { Worker, ${g.title.replaceAll(" ", "")} } from "alchemy/${providerName}";
+
+                const myResource = await ${g.title.replaceAll(" ", "")}("my-resource", {
+                  // ...
+                });
+
+                await Worker("my-worker", {
+                  name: "my-worker",
+                  script: "console.log('Hello, world!')",
+                  bindings: {
+                    myResource,
+                  },
+                });
+                \`\`\``
+                : ""}
+              `,
+        })));
+        // Unwrap all documents, fail if any rejected
+        const results = await Promise.all(documents.map((r) => {
+            if (r.status === "rejected") {
+                throw r.reason;
+            }
+            return r.value;
+        }));
+        return {
+            dir: providerDocsDir,
+            provider: providerName,
+            documents: results,
+        };
+    }));
+}

package/lib/internal/tutorial.d.ts

@@ -0,0 +1,104 @@
+import type { CoreMessage } from "ai";
+import { Document } from "../ai";
+import type { ModelConfig } from "../ai/client";
+import type { Context } from "../context";
+import type { Folder } from "../fs";
+import { Resource } from "../resource";
+/**
+ * Properties for creating or updating a Tutorial
+ */
+export interface TutorialProps {
+    /**
+     * The output directory for the tutorial document.
+     */
+    path: string | Folder;
+    /**
+     * The title of the tutorial.
+     */
+    title: string;
+    /**
+     * The prompt to use for generating the tutorial.
+     * This should include specific details about the tool or framework.
+     */
+    prompt: string;
+    /**
+     * Optional difficulty level for the tutorial.
+     * Defaults to "beginner".
+     */
+    difficulty?: "beginner" | "intermediate" | "advanced";
+    /**
+     * Optional estimated time to complete the tutorial in minutes.
+     * Defaults to 30.
+     */
+    estimatedTime?: number;
+    /**
+     * Optional model configuration for generating the tutorial.
+     * Defaults to Claude 3.5 Sonnet.
+     */
+    model?: ModelConfig;
+    /**
+     * Maximum number of review iterations.
+     * Defaults to 3.
+     */
+    maxIterations?: number;
+    /**
+     * Initial message history for the conversation.
+     * If not provided, a new conversation will be started.
+     */
+    messages?: CoreMessage[];
+}
+/**
+ * Output returned after Tutorial creation/update
+ */
+export interface Tutorial extends TutorialProps, Resource<"docs::Tutorial"> {
+    /**
+     * The Document resource
+     */
+    document: Document;
+    /**
+     * The content of the tutorial
+     */
+    content: string;
+    /**
+     * Message history from the conversation.
+     */
+    messages: CoreMessage[];
+    /**
+     * Time at which the tutorial was created
+     */
+    createdAt: number;
+    /**
+     * Time at which the tutorial was last updated
+     */
+    updatedAt: number;
+}
+/**
+ * Creates a tutorial document with iterative review and improvement
+ *
+ * @example
+ * // Create a basic tutorial
+ * const tutorial = await Tutorial("getting-started", {
+ *   path: "docs/tutorials/getting-started",
+ *   title: "Getting Started with Alchemy",
+ *   prompt: "Create a tutorial for getting started with the Alchemy framework",
+ *   difficulty: "beginner",
+ *   estimatedTime: 30
+ * });
+ *
+ * @example
+ * // Create an advanced tutorial with custom model and continue from existing messages
+ * const advancedTutorial = await Tutorial("advanced-features", {
+ *   path: "docs/tutorials/advanced-features",
+ *   title: "Advanced Alchemy Features",
+ *   prompt: "Create a tutorial covering advanced features of the Alchemy framework",
+ *   difficulty: "advanced",
+ *   estimatedTime: 60,
+ *   model: {
+ *     id: "claude-3-7-sonnet-latest",
+ *     provider: "anthropic"
+ *   },
+ *   maxIterations: 5,
+ *   messages: basicTutorial.messages
+ * });
+ */
+export declare const Tutorial: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<Tutorial>, id: string, props: TutorialProps) => Promise<Tutorial>);

package/lib/internal/tutorial.js

@@ -0,0 +1,251 @@
+import { Approve, Document, Review } from "../ai";
+import { alchemy } from "../alchemy";
+import { Resource } from "../resource";
+/**
+ * Creates a tutorial document with iterative review and improvement
+ *
+ * @example
+ * // Create a basic tutorial
+ * const tutorial = await Tutorial("getting-started", {
+ *   path: "docs/tutorials/getting-started",
+ *   title: "Getting Started with Alchemy",
+ *   prompt: "Create a tutorial for getting started with the Alchemy framework",
+ *   difficulty: "beginner",
+ *   estimatedTime: 30
+ * });
+ *
+ * @example
+ * // Create an advanced tutorial with custom model and continue from existing messages
+ * const advancedTutorial = await Tutorial("advanced-features", {
+ *   path: "docs/tutorials/advanced-features",
+ *   title: "Advanced Alchemy Features",
+ *   prompt: "Create a tutorial covering advanced features of the Alchemy framework",
+ *   difficulty: "advanced",
+ *   estimatedTime: 60,
+ *   model: {
+ *     id: "claude-3-7-sonnet-latest",
+ *     provider: "anthropic"
+ *   },
+ *   maxIterations: 5,
+ *   messages: basicTutorial.messages
+ * });
+ */
+export const Tutorial = Resource("docs::Tutorial", async function (id, props) {
+    const { path: outFile, title, prompt, difficulty = "beginner", estimatedTime = 30, model = {
+        id: "claude-3-5-sonnet-latest",
+        provider: "anthropic",
+    }, maxIterations = 3, messages: initialMessages = [], } = props;
+    console.log(`Tutorial: Starting creation of "${title}" (ID: ${id})`);
+    // Handle deletion phase
+    if (this.phase === "delete") {
+        console.log(`Tutorial: Deleting tutorial "${title}" (ID: ${id})`);
+        return this.destroy();
+    }
+    // System prompts
+    const docSystemPrompt = `You are a technical writer creating a comprehensive tutorial.
+    
+    Your task is to create a detailed tutorial about ${title} with difficulty level: ${difficulty} and estimated time to complete: ${estimatedTime} minutes.
+    
+    The tutorial should take users from zero knowledge to a working understanding of the tool or framework.
+    
+    The tutorial should be structured as follows:
+    
+    # ${title}
+    
+    ## Overview
+    
+    (Provide a brief introduction to the tool/framework, its purpose, and what users will learn in this tutorial)
+    
+    ## Prerequisites
+    
+    (List any prerequisites, tools, or knowledge required before starting the tutorial)
+    
+    ## Setup
+    
+    ### Installation
+    
+    \`\`\`bash
+    # Installation commands
+    \`\`\`
+    
+    ### Configuration
+    
+    (Explain any necessary configuration steps)
+    
+    \`\`\`bash
+    # Configuration commands or code
+    \`\`\`
+    
+    ## Step 1: [First Step Title]
+    
+    (Explain the first step in detail)
+    
+    \`\`\`bash
+    # Commands or code for the first step
+    \`\`\`
+    
+    (Explain what the code does and why it's important)
+    
+    ## Step 2: [Second Step Title]
+    
+    (Explain the second step in detail)
+    
+    \`\`\`bash
+    # Commands or code for the second step
+    \`\`\`
+    
+    (Explain what the code does and why it's important)
+    
+    ## Step 3: [Third Step Title]
+    
+    (Explain the third step in detail)
+    
+    \`\`\`bash
+    # Commands or code for the third step
+    \`\`\`
+    
+    (Explain what the code does and why it's important)
+    
+    ## Step 4: [Fourth Step Title]
+    
+    (Explain the fourth step in detail)
+    
+    \`\`\`bash
+    # Commands or code for the fourth step
+    \`\`\`
+    
+    (Explain what the code does and why it's important)
+    
+    ## Step 5: [Fifth Step Title]
+    
+    (Explain the fifth step in detail)
+    
+    \`\`\`bash
+    # Commands or code for the fifth step
+    \`\`\`
+    
+    (Explain what the code does and why it's important)
+    
+    ## Testing Your Work
+    
+    (Explain how to verify that everything is working correctly)
+    
+    \`\`\`bash
+    # Testing commands or code
+    \`\`\`
+    
+    ## Troubleshooting
+    
+    (Common issues users might encounter and how to resolve them)
+    
+    ## Next Steps
+    
+    (Suggest additional resources, advanced topics, or projects to try next)
+    
+    ## Additional Resources
+    
+    (Links to documentation, community resources, or related tutorials)`;
+    // Initial message if none provided
+    const startingMessages = initialMessages.length > 0
+        ? initialMessages
+        : [
+            {
+                role: "user",
+                content: `Create a comprehensive tutorial about ${title}.\n\n${prompt}\n\nDifficulty level: ${difficulty}\nEstimated time to complete: ${estimatedTime} minutes`,
+            },
+        ];
+    // Generate the initial tutorial
+    console.log(`Tutorial: Generating initial tutorial for "${title}"`);
+    let tutorial = await Document(`document`, {
+        title: title,
+        path: typeof outFile === "string" ? outFile : outFile.path,
+        model,
+        messages: startingMessages,
+        system: docSystemPrompt,
+    });
+    console.log(`Tutorial: Initial tutorial generated for "${title}" (${tutorial.content.length} chars)`);
+    // Review and improve the tutorial in a loop
+    let iteration = 0;
+    let approved = false;
+    let finalMessages = tutorial.messages;
+    while (!approved && iteration < maxIterations) {
+        iteration++;
+        console.log(`Tutorial: Starting review iteration ${iteration}/${maxIterations} for "${title}"`);
+        // Review the tutorial using system prompt
+        console.log(`Tutorial: Requesting review for iteration ${iteration}`);
+        const review = await Review(`review-${iteration}`, {
+            messages: finalMessages,
+            system: await alchemy `Please review this tutorial for correctness, conciseness, logical flow, and accurateness. 
+        
+      The tutorial should:
+      1. Be technically accurate and free of errors
+      2. Be concise without over-explaining
+      3. Have a logical flow from basic to advanced concepts
+      4. Be accurate in its descriptions and instructions
+      5. Be appropriate for the ${difficulty} difficulty level
+      6. Be completable within approximately ${estimatedTime} minutes
+      
+      Provide specific feedback on areas that need improvement.`,
+            model,
+        });
+        // Extract the actual review content from the last assistant message
+        const reviewContent = review.messages[review.messages.length - 1]?.content || "";
+        console.log(`Tutorial: Review received for iteration ${iteration} (${reviewContent.length} chars)`);
+        // Check if the tutorial is approved using system prompt
+        console.log(`Tutorial: Evaluating approval for iteration ${iteration}`);
+        const approvalResult = await Approve(`approval-${iteration}`, {
+            messages: review.messages,
+            system: await alchemy `Based on the review above, determine if the tutorial meets the quality standards.
+      The tutorial should be approved if:
+      1. It is technically accurate and free of errors
+      2. It is concise without over-explaining
+      3. It has a logical flow from basic to advanced concepts
+      4. It is accurate in its descriptions and instructions
+      5. It is appropriate for the ${difficulty} difficulty level
+      6. It is completable within approximately ${estimatedTime} minutes
+      
+      Respond with APPROVED or DENIED, followed by your explanation.`,
+        });
+        console.log(`Tutorial: Approval result for iteration ${iteration}: ${approvalResult.approved ? "APPROVED" : "DENIED"}`);
+        // Log approval status
+        if (approvalResult.approved) {
+            console.log(`Tutorial: Final tutorial approved: ${approvalResult.explanation}`);
+            approved = true;
+            finalMessages = approvalResult.messages;
+        }
+        else {
+            console.log(`Tutorial: Tutorial needs improvement: ${approvalResult.explanation}`);
+            // Add improvement request and generate an improved tutorial
+            const improvementMessages = [
+                ...approvalResult.messages,
+                {
+                    role: "user",
+                    content: `Please create an improved version of the tutorial that addresses the issues identified in the review: ${approvalResult.explanation}`,
+                },
+            ];
+            console.log(`Tutorial: Regenerating tutorial based on feedback for iteration ${iteration}`);
+            tutorial = await Document(`tutorial-${iteration}`, {
+                title: title,
+                path: typeof outFile === "string" ? outFile : outFile.path,
+                model,
+                messages: improvementMessages,
+                system: docSystemPrompt,
+            });
+            console.log(`Tutorial: Improved tutorial generated for iteration ${iteration} (${tutorial.content.length} chars)`);
+            finalMessages = tutorial.messages;
+        }
+    }
+    if (!approved) {
+        console.log(`Tutorial: Tutorial not approved after ${maxIterations} iterations. Using the best version available.`);
+    }
+    console.log(`Tutorial: Completed creation of "${title}" (ID: ${id})`);
+    // Return the tutorial resource
+    return this({
+        ...props,
+        document: tutorial,
+        content: tutorial.content,
+        messages: finalMessages,
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+    });
+});

package/lib/resource.js

@@ -15,7 +15,14 @@ export function Resource(type, ...args) {
         if (scope.resources.has(resourceID)) {
             // TODO(sam): do we want to throw?
             // it's kind of awesome that you can re-create a resource and call apply
-            // console.warn(`Resource ${id} already exists in the stack: ${stack.id}`);
+            const otherResource = scope.resources.get(resourceID);
+            if (otherResource?.Kind !== type) {
+                scope.fail();
+                throw new Error(`Resource ${resourceID} already exists in the stack and is of a different type: '${otherResource?.Kind}' !== '${type}'`);
+            }
+            // console.warn(
+            //   `Resource ${resourceID} already exists in the stack: ${scope.chain.join("/")}`,
+            // );
         }
         // get a sequence number (unique within the scope) for the resource
         const seq = scope.seq();

package/lib/scope.d.ts

@@ -1,5 +1,5 @@
 import type { PendingResource, ResourceID } from "./resource";
-import { type StateStore, type StateStoreType } from "./state";
+import type { StateStore, StateStoreType } from "./state";
 export type ScopeOptions = {
     appName?: string;
     stage: string;

package/lib/scope.js

@@ -1,6 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { destroy } from "./destroy";
-import { FileSystemStateStore, } from "./state";
+import { FileSystemStateStore } from "./fs/file-system-state-store";
 const scopeStorage = new AsyncLocalStorage();
 export class Scope {
     static get() {
@@ -32,7 +32,9 @@ export class Scope {
             throw new Error("Scope name is required when creating a child scope");
         }
         this.password = options.password;
-        this.state = new (options.stateStore ?? FileSystemStateStore)(this);
+        this.state = options.stateStore
+            ? options.stateStore(this)
+            : new FileSystemStateStore(this);
     }
     async delete(resourceID) {
         await this.state.delete(resourceID);

package/lib/state.d.ts

@@ -11,7 +11,7 @@ export interface State<Kind extends string = string, Props extends ResourceProps
     oldProps?: Props;
     output: Out;
 }
-export type StateStoreType = new (scope: Scope) => StateStore;
+export type StateStoreType = (scope: Scope) => StateStore;
 export interface StateStore {
     /** Initialize the state container if one is required */
     init?(): Promise<void>;
@@ -27,18 +27,3 @@ export interface StateStore {
     set(key: string, value: State): Promise<void>;
     delete(key: string): Promise<void>;
 }
-export declare class FileSystemStateStore implements StateStore {
-    readonly scope: Scope;
-    readonly dir: string;
-    constructor(scope: Scope);
-    init(): Promise<void>;
-    deinit(): Promise<void>;
-    count(): Promise<number>;
-    list(): Promise<string[]>;
-    get(key: string): Promise<State | undefined>;
-    set(key: string, value: State): Promise<void>;
-    delete(key: string): Promise<void>;
-    all(): Promise<Record<string, State>>;
-    getBatch(ids: string[]): Promise<Record<string, State>>;
-    private getPath;
-}

package/lib/state.js

@@ -1,87 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import { ignore } from "./util/ignore";
-import { deserialize, serialize } from "./util/serde";
-const stateRootDir = path.join(process.cwd(), ".alchemy");
-export class FileSystemStateStore {
-    scope;
-    dir;
-    constructor(scope) {
-        this.scope = scope;
-        this.dir = path.join(stateRootDir, ...scope.chain);
-    }
-    async init() {
-        await fs.promises.mkdir(stateRootDir, { recursive: true });
-        await fs.promises.mkdir(this.dir, { recursive: true });
-    }
-    async deinit() {
-        await ignore("ENOENT", () => fs.promises.rmdir(this.dir));
-    }
-    async count() {
-        return Object.keys(await this.list()).length;
-    }
-    async list() {
-        try {
-            const files = await fs.promises.readdir(this.dir, {
-                withFileTypes: true,
-            });
-            return files
-                .filter((dirent) => dirent.isFile() && dirent.name.endsWith(".json"))
-                .map((dirent) => dirent.name.replace(/\.json$/, ""))
-                .map((key) => key.replaceAll(":", "/"));
-        }
-        catch (error) {
-            if (error.code === "ENOENT") {
-                return [];
-            }
-            throw error;
-        }
-    }
-    async get(key) {
-        try {
-            const content = await fs.promises.readFile(await this.getPath(key), "utf8");
-            const state = (await deserialize(this.scope, JSON.parse(content)));
-            if (state.output === undefined) {
-                state.output = {};
-            }
-            state.output.Scope = this.scope;
-            return state;
-        }
-        catch (error) {
-            if (error.code === "ENOENT") {
-                return undefined;
-            }
-            throw error;
-        }
-    }
-    async set(key, value) {
-        return fs.promises.writeFile(await this.getPath(key), JSON.stringify(await serialize(this.scope, value), null, 2));
-    }
-    async delete(key) {
-        return fs.promises.unlink(await this.getPath(key));
-    }
-    async all() {
-        return this.getBatch(await this.list());
-    }
-    async getBatch(ids) {
-        return Object.fromEntries((await Promise.all(Array.from(ids).flatMap(async (id) => {
-            const s = await this.get(id);
-            if (s === undefined) {
-                return [];
-            }
-            return [[id, s]];
-        }))).flat());
-    }
-    async getPath(key) {
-        if (key.includes(":")) {
-            throw new Error(`ID cannot include colons: ${key}`);
-        }
-        if (key.includes("/")) {
-            key = key.replaceAll("/", ":");
-        }
-        const file = path.join(this.dir, `${key}.json`);
-        const dir = path.dirname(file);
-        await fs.promises.mkdir(dir, { recursive: true });
-        return file;
-    }
-}