alchemy 0.3.0 → 0.3.1

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/web/vitepress/config.d.ts

@@ -0,0 +1,10 @@
+import type { DefaultTheme, ThemeOptions } from "vitepress";
+export type VitePressConfigProps = {
+    cwd: string;
+    title?: string;
+    description?: string;
+    theme?: ThemeOptions;
+    themeConfig: DefaultTheme.Config;
+};
+export type VitePressConfig = Awaited<ReturnType<typeof VitePressConfig>>;
+export declare function VitePressConfig(props: VitePressConfigProps): Promise<import("../../fs").File>;

package/lib/web/vitepress/config.js

@@ -0,0 +1,31 @@
+import path from "path";
+import { StaticTypeScriptFile } from "../../fs/static-typescript-file";
+export function VitePressConfig(props) {
+    return StaticTypeScriptFile(path.join(props.cwd, ".vitepress", "config.mts"), `import { transformerTwoslash } from "@shikijs/vitepress-twoslash";
+import footnotePlugin from "markdown-it-footnote";
+import { defineConfig } from "vitepress";
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: ${JSON.stringify(props.title || "Alchemy")},
+  description: ${JSON.stringify(props.description || "Alchemy Docs")},
+  markdown: {
+    // @ts-ignore
+    codeTransformers: [transformerTwoslash()],
+    theme: ${JSON.stringify(props.theme ?? {
+        light: "light-plus",
+        dark: "dark-plus",
+    })},
+    config: (md) => md.use(footnotePlugin),
+  },
+  // https://vitepress.dev/reference/default-theme-config
+  themeConfig: ${JSON.stringify({
+        ...props.themeConfig,
+        search: props.themeConfig.search ?? { provider: "local" },
+        nav: props.themeConfig.nav ?? [{ text: "Home", link: "/" }],
+        sidebar: props.themeConfig.sidebar ?? [],
+        socialLinks: props.themeConfig.socialLinks ?? [],
+    })}
+});
+`);
+}

package/lib/web/vitepress/home-page.d.ts

@@ -1,3 +1,5 @@
+import { Document } from "../../ai/document";
+import { StaticTextFile } from "../../fs";
 import type { Secret } from "../../secret";
 /**
  * Image that can be themed for light/dark mode
@@ -151,11 +153,11 @@ export interface HomePageProps {
     /**
      * User prompt describing the design of the home page
      */
-    prompt: string;
+    prompt?: string;
     /**
      * Optional extension to the built-in system prompt
      */
-    systemPromptExtension?: string;
+    system?: string;
     /**
      * Base URL for the OpenAI API
      * @default 'https://api.openai.com/v1'
@@ -179,7 +181,7 @@ export interface HomePageProps {
 /**
  * Output type for the HomePage resource
  */
-export type HomePage = import("../../ai/document").Document;
+export type HomePage = StaticTextFile | Document;
 /**
  * Parse YAML frontmatter to home page config
  */

package/lib/web/vitepress/home-page.js

@@ -1,6 +1,7 @@
-import alchemy from "alchemy";
 import yaml from "yaml";
 import { Document } from "../../ai/document";
+import { alchemy } from "../../alchemy";
+import { StaticTextFile } from "../../fs";
 /**
  * Parse YAML frontmatter to home page config
  */
@@ -90,45 +91,57 @@ Follow these guidelines:
 6. Ensure all links are properly formatted
 7. Use appropriate markdown formatting for headings, lists, etc.
 
-${props.systemPromptExtension || ""}
+${props.system || ""}
 `;
     // Convert hero and features to YAML strings if provided
     const heroYaml = props.hero ? JSON.stringify(props.hero, null, 2) : "";
     const featuresYaml = props.features
         ? JSON.stringify(props.features, null, 2)
         : "";
-    // Create the document using the AI Document resource
-    return Document(`${id}`, {
-        title: props.title,
-        path: props.outFile,
-        baseURL: props.baseURL,
-        apiKey: props.apiKey,
-        model: props.model ?? {
-            id: "claude-3-7-sonnet-latest",
-            provider: "anthropic",
-        },
-        temperature: props.temperature ?? 0.7,
-        prompt: await alchemy `
-${systemPrompt}
-
-Create a VitePress homepage based on the following description:
-${props.prompt}
-
-${props.hero
-            ? `Use this hero section configuration:
-\`\`\`json
-${heroYaml}
-\`\`\``
-            : ""}
-
-${props.features
-            ? `Use these features:
-\`\`\`json
-${featuresYaml}
-\`\`\``
-            : ""}
+    if (props.prompt) {
+        return Document(id, {
+            title: props.title,
+            path: props.outFile,
+            baseURL: props.baseURL,
+            apiKey: props.apiKey,
+            model: props.model ?? {
+                id: "claude-3-7-sonnet-latest",
+                provider: "anthropic",
+            },
+            temperature: props.temperature ?? 0.7,
+            prompt: await alchemy `
+    ${systemPrompt}
+    
+    Create a VitePress homepage based on the following description:
+    ${props.prompt}
     
-    The output should be a complete index.md file with proper YAML frontmatter and markdown content.
-    `,
-    });
+    ${props.hero
+                ? `Use this hero section configuration:
+    \`\`\`json
+    ${heroYaml}
+    \`\`\``
+                : ""}
+    
+    ${props.features
+                ? `Use these features:
+    \`\`\`json
+    ${featuresYaml}
+    \`\`\``
+                : ""}
+        
+        The output should be a complete index.md file with proper YAML frontmatter and markdown content.
+        `,
+        });
+    }
+    else {
+        return StaticTextFile(id, props.outFile, `---
+${yaml.stringify({
+            layout: "home",
+            name: props.title,
+            hero: props.hero,
+            features: props.features,
+        })}
+---
+`);
+    }
 }

package/lib/web/vitepress/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./config";
 export * from "./custom-theme";
 export * from "./home-page";
 export * from "./vitepress";

package/lib/web/vitepress/index.js

@@ -1,3 +1,4 @@
+export * from "./config";
 export * from "./custom-theme";
 export * from "./home-page";
 export * from "./vitepress";

package/lib/web/vitepress/vitepress.d.ts

@@ -1,4 +1,3 @@
-import type { DefaultTheme, ThemeOptions } from "vitepress";
 import type { Context } from "../../context";
 import { Resource } from "../../resource";
 export interface VitePressProjectProps {
@@ -47,11 +46,9 @@ export interface VitePressProjectProps {
     /**
      * The theme options to use
      */
-    theme?: ThemeOptions;
     /**
      * The theme config to use
      */
-    themeConfig: DefaultTheme.Config;
     /**
      * Whether to delete the project folder during the delete phase
      * @default true
@@ -69,5 +66,9 @@ export interface VitePressProject extends VitePressProjectProps, Resource {
      * The name/path of the project
      */
     name: string;
+    /**
+     * The directory of the project
+     */
+    dir: string;
 }
-export declare const VitePressProject: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<VitePressProject>, id: string, props: VitePressProjectProps) => Promise<VitePressProject>);
+export declare const VitepressProject: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<VitePressProject>, id: string, props: VitePressProjectProps) => Promise<VitePressProject>);

package/lib/web/vitepress/vitepress.js

@@ -6,7 +6,7 @@ import { Folder, StaticJsonFile, StaticTextFile, StaticTypeScriptFile, } from ".
 import { Resource } from "../../resource";
 import { InstallDependencies, fixedDependencies } from "./dependencies";
 const execAsync = promisify(exec);
-export const VitePressProject = Resource("project::VitePressProject", {
+export const VitepressProject = Resource("project::VitepressProject", {
     alwaysUpdate: true,
 }, async function (id, props) {
     const dir = props.dir ?? props.name;
@@ -57,11 +57,18 @@ export const VitePressProject = Resource("project::VitePressProject", {
     await Folder(path.join(cwd, ".vitepress", "theme"));
     await Promise.all([
         StaticTextFile(path.join(cwd, ".gitignore"), `.vitepress/cache\n`),
-        StaticJsonFile(path.join(cwd, "tsconfig.json"), {
-            extends: props.tsconfig?.extends,
-            references: props.tsconfig?.references?.map((path) => ({ path })),
-            compilerOptions: props.tsconfig?.compilerOptions,
-        }),
+        // StaticJsonFile(path.join(cwd, "tsconfig.json"), {
+        //   extends: props.tsconfig?.extends,
+        //   references: props.tsconfig?.references?.map((path) => ({ path })),
+        //   compilerOptions: props.tsconfig?.compilerOptions ?? {
+        //     target: "ES2020",
+        //     module: "ESNext",
+        //     moduleResolution: "Node",
+        //     allowJs: true,
+        //     skipLibCheck: true,
+        //     forceConsistentCasingInFileNames: true,
+        //   },
+        // }),
         //       TypeScriptFile(
         //         path.join(cwd, "alchemy.run.ts"),
         //         `import alchemy from "alchemy";
@@ -232,34 +239,10 @@ export default {
 .DocSearch {
   --docsearch-primary-color: var(--vp-c-brand-1) !important;
 }
-`),
-        StaticTypeScriptFile(path.join(cwd, ".vitepress", "config.mts"), `import { transformerTwoslash } from "@shikijs/vitepress-twoslash";
-import footnotePlugin from "markdown-it-footnote";
-import { defineConfig } from "vitepress";
-
-// https://vitepress.dev/reference/site-config
-export default defineConfig({
-  title: ${JSON.stringify(props.title || "Alchemy")},
-  description: ${JSON.stringify(props.description || "Alchemy Docs")},
-  markdown: {
-    // @ts-ignore
-    codeTransformers: [transformerTwoslash()],
-    theme: ${JSON.stringify(props.theme ?? {
-            light: "light-plus",
-            dark: "dark-plus",
-        })},
-    config: (md) => md.use(footnotePlugin),
-  },
-  // https://vitepress.dev/reference/default-theme-config
-  themeConfig: ${JSON.stringify({
-            ...props.themeConfig,
-            search: props.themeConfig.search ?? { provider: "local" },
-            nav: props.themeConfig.nav ?? [{ text: "Home", link: "/" }],
-            sidebar: props.themeConfig.sidebar ?? [],
-            socialLinks: props.themeConfig.socialLinks ?? [],
-        })}
-});
 `),
     ]);
-    return this(props);
+    return this({
+        ...props,
+        dir,
+    });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alchemy",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "module": "./lib/index.js",
   "scripts": {