alchemy 0.3.1 → 0.4.1

package/src/ai/review.ts

@@ -1,213 +0,0 @@
-import { generateText, type CoreMessage } from "ai";
-import type { Context } from "../context";
-import { Resource } from "../resource";
-import type { Secret } from "../secret";
-import { createModel, withRateLimitRetry, type ModelConfig } from "./client";
-
-/**
- * Properties for creating or updating a Review
- */
-export interface ReviewProps {
-  /**
-   * Content to be reviewed
-   * Use alchemy template literals to include file context:
-   * @example
-   * content: await alchemy`
-   *   Review this code:
-   *   ${alchemy.file("src/api.ts")}
-   * `
-   *
-   * Required unless messages are provided
-   */
-  content?: string;
-
-  /**
-   * Prompt for the review
-   * This should include specific instructions for the review
-   * @example
-   * prompt: "Review this code for security vulnerabilities, performance issues, and best practices."
-   *
-   * Required unless messages are provided
-   */
-  prompt?: string;
-
-  /**
-   * Message history for the conversation
-   * If provided, this will be used instead of the prompt and content
-   */
-  messages?: CoreMessage[];
-
-  /**
-   * System prompt for the model
-   * This is used to provide instructions to the model about how to format the response
-   * The default system prompt instructs the model to act as a reviewer
-   */
-  system?: string;
-
-  /**
-   * AI 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;
-
-  /**
-   * Maximum number of tokens to generate.
-   * Higher values allow for longer documents but may increase cost and generation time.
-   * @default 10000
-   */
-  maxTokens?: number;
-}
-
-/**
- * Output returned after Review creation/update
- */
-export interface Review extends ReviewProps, Resource<"ai::Review"> {
-  /**
-   * Content of the review
-   */
-  content: string;
-
-  /**
-   * Updated message history with the review response appended
-   */
-  messages: CoreMessage[];
-
-  /**
-   * Time at which the review was created
-   */
-  createdAt: number;
-
-  /**
-   * Time at which the review was last updated
-   */
-  updatedAt: number;
-}
-
-/**
- * Default system prompt for review generation
- */
-const DEFAULT_REVIEW_SYSTEM_PROMPT = `You are an expert code reviewer and technical writer. Your task is to provide a thorough review of the provided content. Your review should include:
-
-1. A high-level summary of the content
-2. Detailed feedback on the content's quality, accuracy, and completeness
-3. Specific suggestions for improvement
-4. Alternative approaches or solutions where applicable
-5. Best practices that should be followed
-6. Potential issues or concerns that should be addressed
-
-Provide your review in a clear, well-structured format.`;
-
-/**
- * Creates or updates a Review resource
- *
- * @example
- * // Create a review of a code file
- * const codeReview = await Review("api-review", {
- *   content: await alchemy`
- *     Review this API implementation:
- *     ${alchemy.file("src/api.ts")}
- *   `,
- *   prompt: "Review this API implementation for security vulnerabilities, performance issues, and best practices. Suggest improvements and alternative approaches."
- * });
- *
- * @example
- * // Create a review of a document
- * const docReview = await Review("tutorial-review", {
- *   content: await alchemy`
- *     Review this tutorial:
- *     ${alchemy.file("docs/tutorials/getting-started.md")}
- *   `,
- *   prompt: "Review this tutorial for clarity, accuracy, and completeness. Suggest improvements to make it more user-friendly."
- * });
- *
- * @example
- * // Create a review with message history
- * const reviewWithHistory = await Review("code-review-iteration-2", {
- *   content: "Updated code implementation",
- *   prompt: "Review this updated implementation",
- *   messages: [
- *     { role: "user", content: "Can you review my code?" },
- *     { role: "assistant", content: "I'll review your code. Please share it." },
- *     { role: "user", content: "Here's my implementation: [code]" },
- *     { role: "assistant", content: "Here's my review of your code: [previous review]" }
- *   ]
- * });
- */
-export const Review = Resource(
-  "ai::Review",
-  async function (
-    this: Context<Review>,
-    id: string,
-    props: ReviewProps
-  ): Promise<Review> {
-    if (this.phase === "delete") {
-      return this.destroy();
-    }
-
-    // Use provided system prompt or default
-    const system = props.system || DEFAULT_REVIEW_SYSTEM_PROMPT;
-
-    // Create messages array if not provided
-    const messages =
-      props.messages ||
-      (props.content && props.prompt
-        ? [
-            {
-              role: "user",
-              content: `${props.content}\n\n${props.prompt}`,
-            },
-          ]
-        : []);
-
-    if (messages.length === 0) {
-      throw new Error(
-        "Either messages or both content and prompt must be provided"
-      );
-    }
-
-    // Generate review content with rate limit retry
-    const { text } = await withRateLimitRetry(async () => {
-      return generateText({
-        model: createModel(props),
-        messages,
-        system,
-        maxTokens: props.maxTokens || 8192,
-        providerOptions: props.model?.options,
-        ...(props.temperature === undefined
-          ? {}
-          : { temperature: props.temperature }),
-      });
-    });
-
-    // Create updated message history with the AI's response
-    const updatedMessages = [
-      ...messages,
-      {
-        role: "assistant" as const,
-        content: text,
-      },
-    ];
-
-    // Return the review with the direct text from the LLM and updated messages
-    return this({
-      ...props,
-      content: text,
-      messages: updatedMessages,
-      createdAt: Date.now(),
-      updatedAt: Date.now(),
-    });
-  }
-);

package/src/internal/getting-started.ts

@@ -1,115 +0,0 @@
-import { Document } from "../ai";
-import type { ModelConfig } from "../ai/client";
-import { alchemy } from "../alchemy";
-import type { Folder } from "../fs";
-
-export interface GettingStartedProps {
-  /**
-   * The output directory for the getting started document.
-   */
-  path: string | Folder;
-
-  /**
-   * The prompt to use for generating the getting started guide.
-   * This should include specific details about the product or framework.
-   */
-  prompt: string;
-
-  /**
-   * Optional model configuration for generating the getting started guide.
-   * Defaults to Claude 3.5 Sonnet.
-   */
-  model?: ModelConfig;
-}
-
-export type GettingStarted = Document;
-
-export async function GettingStarted({
-  path: outFile,
-  prompt,
-  model = {
-    id: "claude-3-5-sonnet-latest",
-    provider: "anthropic",
-  },
-}: GettingStartedProps): Promise<Document> {
-  return Document(`docs/getting-started`, {
-    title: "Getting Started Guide",
-    path: typeof outFile === "string" ? outFile : outFile.path,
-    model,
-    prompt: await alchemy`
-      You are a technical writer creating a getting started guide.
-      
-      ${prompt}
-      
-      If you need a template structure to follow, use this format:
-      
-      # Getting Started with [Product/Framework Name]
-      
-      (Brief introduction to the product/framework)
-      
-      ## Installation
-      
-      \`\`\`bash
-      # Installation command
-      \`\`\`
-      
-      ## Creating Your First Project
-      
-      (Step-by-step guide to creating a basic project)
-      
-      \`\`\`ts
-      // Example of a simple project
-      \`\`\`
-      
-      ## Core Concepts
-      
-      ### [Concept 1]
-      
-      (Explanation of the first core concept)
-      
-      \`\`\`ts
-      // Example of using the concept
-      \`\`\`
-      
-      ### [Concept 2]
-      
-      (Explanation of the second core concept)
-      
-      \`\`\`ts
-      // Example of using the concept
-      \`\`\`
-      
-      ## Working with [Feature]
-      
-      (How to use a specific feature)
-      
-      \`\`\`ts
-      // Example of using the feature
-      \`\`\`
-      
-      ## Testing
-      
-      (How to test your project)
-      
-      \`\`\`ts
-      // Example of testing
-      \`\`\`
-      
-      ## Deployment
-      
-      (How to deploy your project)
-      
-      \`\`\`ts
-      // Example of deployment
-      \`\`\`
-      
-      ## Next Steps
-      
-      (Where to go next to learn more)
-      
-      > [!TIP]
-      > Make sure the examples follow a natural progression from minimal examples to more complex use cases.
-      > Keep explanations concise and focused on high-value information.
-    `,
-  });
-}

package/src/internal/index.ts

@@ -1,3 +0,0 @@
-export * from "./getting-started";
-export * from "./providers";
-export * from "./tutorial";

package/src/internal/providers.ts

@@ -1,241 +0,0 @@
-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 interface DocsProps {
-  /**
-   * The output directory for the docs.
-   */
-  outDir: string | Folder;
-
-  /**
-   * The source directory for the docs.
-   */
-  srcDir: string;
-
-  /**
-   * Whether to filter the docs.
-   * If true, include all docs.
-   * If false, include none.
-   * If a number, include that many providers.
-   *
-   * @default true (all docs)
-   */
-  filter?: boolean | number;
-}
-
-export type AlchemyProviderDocs = {
-  dir: string;
-  provider: string;
-  documents: Document[];
-}[];
-
-export async function AlchemyProviderDocs({
-  srcDir,
-  outDir,
-  filter,
-}: DocsProps): Promise<AlchemyProviderDocs> {
-  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,
-      } as const;
-    })
-  );
-}