npm - alchemy - Versions diffs - 0.3.0 → 0.3.1 - Mend

alchemy 0.3.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (107) hide show

package/lib/ai/approve.d.ts +99 -0
package/lib/ai/approve.js +76 -0
package/lib/ai/astro-file.js +7 -24
package/lib/ai/client.d.ts +7 -0
package/lib/ai/client.js +45 -0
package/lib/ai/css-file.js +7 -24
package/lib/ai/data.d.ts +26 -21
package/lib/ai/data.js +33 -22
package/lib/ai/document.d.ts +64 -4
package/lib/ai/document.js +102 -55
package/lib/ai/html-file.js +7 -24
package/lib/ai/index.d.ts +2 -0
package/lib/ai/index.js +2 -0
package/lib/ai/json-file.js +11 -32
package/lib/ai/review.d.ts +122 -0
package/lib/ai/review.js +101 -0
package/lib/ai/typescript-file.d.ts +1 -2
package/lib/ai/typescript-file.js +8 -39
package/lib/ai/vue-file.js +7 -24
package/lib/ai/yaml-file.js +12 -48
package/lib/alchemy.js +17 -2
package/lib/apply.js +1 -1
package/lib/cloudflare/generate-asset-manifest.js +1 -1
package/lib/cloudflare/static-site-router.js +16 -7
package/lib/cloudflare/static-site.js +3 -0
package/lib/cloudflare/upload-asset-manifest.js +4 -2
package/lib/fs/copy-file.d.ts +54 -0
package/lib/fs/copy-file.js +63 -0
package/lib/fs/file.d.ts +13 -0
package/lib/fs/file.js +24 -5
package/lib/fs/index.d.ts +6 -0
package/lib/fs/index.js +6 -0
package/lib/fs/static-astro-file.d.ts +34 -0
package/lib/fs/static-astro-file.js +39 -0
package/lib/fs/static-css-file.d.ts +24 -0
package/lib/fs/static-css-file.js +29 -0
package/lib/fs/static-html-file.d.ts +31 -0
package/lib/fs/static-html-file.js +36 -0
package/lib/fs/static-json-file.d.ts +2 -2
package/lib/fs/static-json-file.js +3 -2
package/lib/fs/static-text-file.d.ts +1 -1
package/lib/fs/static-text-file.js +3 -2
package/lib/fs/static-typescript-file.d.ts +2 -2
package/lib/fs/static-typescript-file.js +3 -2
package/lib/fs/static-vue-file.d.ts +28 -0
package/lib/fs/static-vue-file.js +33 -0
package/lib/fs/static-yaml-file.d.ts +11 -8
package/lib/fs/static-yaml-file.js +3 -2
package/lib/internal/getting-started.d.ts +15 -4
package/lib/internal/getting-started.js +34 -41
package/lib/internal/index.d.ts +3 -0
package/lib/internal/index.js +3 -0
package/lib/internal/providers.d.ts +7 -3
package/lib/internal/providers.js +42 -18
package/lib/internal/tutorial.d.ts +104 -0
package/lib/internal/tutorial.js +251 -0
package/lib/web/vitepress/config.d.ts +10 -0
package/lib/web/vitepress/config.js +31 -0
package/lib/web/vitepress/home-page.d.ts +5 -3
package/lib/web/vitepress/home-page.js +48 -35
package/lib/web/vitepress/index.d.ts +1 -0
package/lib/web/vitepress/index.js +1 -0
package/lib/web/vitepress/vitepress.d.ts +5 -4
package/lib/web/vitepress/vitepress.js +17 -34
package/package.json +1 -1
package/src/ai/approve.ts +163 -0
package/src/ai/astro-file.ts +11 -30
package/src/ai/client.ts +59 -0
package/src/ai/css-file.ts +11 -30
package/src/ai/data.ts +50 -25
package/src/ai/document.ts +146 -65
package/src/ai/html-file.ts +11 -30
package/src/ai/index.ts +2 -0
package/src/ai/json-file.ts +13 -37
package/src/ai/review.ts +213 -0
package/src/ai/typescript-file.ts +14 -48
package/src/ai/vue-file.ts +11 -30
package/src/ai/yaml-file.ts +13 -53
package/src/alchemy.ts +18 -7
package/src/apply.ts +8 -8
package/src/cloudflare/generate-asset-manifest.ts +4 -4
package/src/cloudflare/static-site-router.ts +18 -8
package/src/cloudflare/static-site.ts +11 -7
package/src/cloudflare/upload-asset-manifest.ts +6 -4
package/src/cloudflare/worker.ts +44 -43
package/src/fs/copy-file.ts +115 -0
package/src/fs/file.ts +35 -9
package/src/fs/index.ts +6 -0
package/src/fs/static-astro-file.ts +45 -0
package/src/fs/static-css-file.ts +35 -0
package/src/fs/static-html-file.ts +42 -0
package/src/fs/static-json-file.ts +4 -3
package/src/fs/static-text-file.ts +5 -2
package/src/fs/static-typescript-file.ts +4 -3
package/src/fs/static-vue-file.ts +39 -0
package/src/fs/static-yaml-file.ts +13 -9
package/src/internal/getting-started.ts +51 -43
package/src/internal/index.ts +3 -0
package/src/internal/providers.ts +59 -27
package/src/internal/tutorial.ts +392 -0
package/src/web/vitepress/config.ts +48 -0
package/src/web/vitepress/home-page.ts +54 -42
package/src/web/vitepress/index.ts +1 -0
package/src/web/vitepress/vitepress.ts +31 -48
package/lib/internal/project.d.ts +0 -13
package/lib/internal/project.js +0 -101
package/src/internal/project.ts +0 -119

package/src/fs/index.ts CHANGED Viewed

@@ -1,8 +1,14 @@
+export * from "./copy-file";
 export * from "./file";
 export * from "./file-collection";
 export * from "./file-ref";
+export * from "./file-system-state-store";
 export * from "./folder";
+export * from "./static-astro-file";
+export * from "./static-css-file";
+export * from "./static-html-file";
 export * from "./static-json-file";
 export * from "./static-text-file";
 export * from "./static-typescript-file";
+export * from "./static-vue-file";
 export * from "./static-yaml-file";

package/src/fs/static-astro-file.ts ADDED Viewed

@@ -0,0 +1,45 @@
+import { File } from "./file";
+export type StaticAstroFile = File;
+/**
+ * Creates a static Astro component file
+ *
+ * @example
+ * // Create an Astro component file with content
+ * const header = await StaticAstroFile("Header.astro",
+ *   `---
+ *   import Logo from '../components/Logo.astro';
+ *   const navItems = ['Home', 'About', 'Contact'];
+ *   ---
+ *
+ *   <header class="header">
+ *     <Logo />
+ *     <nav>
+ *       <ul>
+ *         {navItems.map(item => (
+ *           <li><a href={`/${item.toLowerCase()}`}>{item}</a></li>
+ *         ))}
+ *       </ul>
+ *     </nav>
+ *   </header>
+ *
+ *   <style>
+ *     .header {
+ *       display: flex;
+ *       justify-content: space-between;
+ *       padding: 1rem;
+ *     }
+ *   </style>`
+ * );
+ */
+export function StaticAstroFile(
+  id: string,
+  ...args: [content: string] | [path: string, content: string]
+): Promise<StaticAstroFile> {
+  const [path, content] = args.length === 1 ? [id, args[0]] : args;
+  return File(id, {
+    path,
+    content,
+  });
+}

package/src/fs/static-css-file.ts ADDED Viewed

@@ -0,0 +1,35 @@
+import { File } from "./file";
+export type StaticCSSFile = File;
+/**
+ * Creates a static CSS file
+ *
+ * @example
+ * // Create a CSS file with styles
+ * const styles = await StaticCSSFile("styles.css",
+ *   `.container {
+ *     max-width: 1200px;
+ *     margin: 0 auto;
+ *     padding: 0 1rem;
+ *   }
+ *
+ *   .button {
+ *     background-color: #0062ff;
+ *     color: white;
+ *     border: none;
+ *     padding: 0.5rem 1rem;
+ *     border-radius: 4px;
+ *   }`
+ * );
+ */
+export function StaticCSSFile(
+  id: string,
+  ...args: [content: string] | [path: string, content: string]
+): Promise<StaticCSSFile> {
+  const [path, content] = args.length === 1 ? [id, args[0]] : args;
+  return File(id, {
+    path,
+    content,
+  });
+}

package/src/fs/static-html-file.ts ADDED Viewed

@@ -0,0 +1,42 @@
+import { File } from "./file";
+export type StaticHTMLFile = File;
+/**
+ * Creates a static HTML file
+ *
+ * @example
+ * // Create an HTML file with content
+ * const page = await StaticHTMLFile("index.html",
+ *   `<!DOCTYPE html>
+ *   <html lang="en">
+ *   <head>
+ *     <meta charset="UTF-8">
+ *     <meta name="viewport" content="width=device-width, initial-scale=1.0">
+ *     <title>My Website</title>
+ *     <link rel="stylesheet" href="styles.css">
+ *   </head>
+ *   <body>
+ *     <header>
+ *       <h1>Welcome to My Website</h1>
+ *     </header>
+ *     <main>
+ *       <p>This is the main content of the page.</p>
+ *     </main>
+ *     <footer>
+ *       <p>&copy; 2024 My Company</p>
+ *     </footer>
+ *   </body>
+ *   </html>`
+ * );
+ */
+export function StaticHTMLFile(
+  id: string,
+  ...args: [content: string] | [path: string, content: string]
+): Promise<StaticHTMLFile> {
+  const [path, content] = args.length === 1 ? [id, args[0]] : args;
+  return File(id, {
+    path,
+    content,
+  });
+}

package/src/fs/static-json-file.ts CHANGED Viewed

@@ -5,7 +5,7 @@ import { File } from "./file";
  *
  * @example
  * // Create a JSON configuration file
- * const config = await JsonFile("config.json", {
+ * const config = await StaticJsonFile("config.json", {
  *   api: {
  *     endpoint: "https://api.example.com",
  *     version: "v1"
@@ -17,11 +17,12 @@ export type StaticJsonFile = File;
 export async function StaticJsonFile(
   id: string,
-  content: any,
+  ...args: [content: any] | [path: string, content: any]
 ): Promise<StaticJsonFile> {
+  const [path, content] = args.length === 1 ? [id, args[0]] : args;
   const prettier = await import("prettier");
   return File(id, {
-    path: id,
+    path,
     content: await prettier.format(JSON.stringify(content), {
       parser: "json",
       editor: {

package/src/fs/static-text-file.ts CHANGED Viewed

@@ -13,10 +13,13 @@ export type StaticTextFile = File;
 export function StaticTextFile(
   id: string,
-  content: string,
+  ...args:
+  | [content: string]
+  | [path: string, content: string]
 ): Promise<StaticTextFile> {
+  const [path, content] = args.length === 1 ? [id, args[0]] : args;
   return File(id, {
-    path: id,
+    path,
     content,
   });
 }

package/src/fs/static-typescript-file.ts CHANGED Viewed

@@ -5,7 +5,7 @@ import { File } from "./file";
  *
  * @example
  * // Create a TypeScript file
- * const component = await TypeScriptFile("Component.ts", `
+ * const component = await StaticTypeScriptFile("Component.ts", `
  *   interface Props {
  *     name: string;
  *     age: number;
@@ -20,11 +20,12 @@ export type StaticTypeScriptFile = File;
 export async function StaticTypeScriptFile(
   id: string,
-  content: string,
+  ...args: [content: string] | [path: string, content: string]
 ): Promise<StaticTypeScriptFile> {
+  const [path, content] = args.length === 1 ? [id, args[0]] : args;
   const prettier = await import("prettier");
   return File(id, {
-    path: id,
+    path,
     content: await prettier.format(content, {
       parser: "typescript",
       editor: {

package/src/fs/static-vue-file.ts ADDED Viewed

@@ -0,0 +1,39 @@
+import { File } from "./file";
+export type StaticVueFile = File;
+/**
+ * Creates a static Vue component file
+ *
+ * @example
+ * // Create a Vue component file with content
+ * const button = await StaticVueFile("Button.vue",
+ *   `<template>
+ *     <button class="btn">{{ text }}</button>
+ *   </template>
+ *
+ *   <script>
+ *   export default {
+ *     props: {
+ *       text: String
+ *     }
+ *   }
+ *   </script>
+ *
+ *   <style>
+ *   .btn {
+ *     padding: 0.5rem 1rem;
+ *   }
+ *   </style>`
+ * );
+ */
+export function StaticVueFile(
+  id: string,
+  ...args: [content: string] | [path: string, content: string]
+): Promise<StaticVueFile> {
+  const [path, content] = args.length === 1 ? [id, args[0]] : args;
+  return File(id, {
+    path,
+    content,
+  });
+}

package/src/fs/static-yaml-file.ts CHANGED Viewed

@@ -4,26 +4,30 @@ import { File } from "./file";
  *
  * @example
  * // Create a YAML configuration file
- * const config = await YamlFile("config.yaml", {
- *   server:
- *     host: "localhost"
+ * const config = await StaticYamlFile("config.yaml", {
+ *   server: {
+ *     host: "localhost",
  *     port: 3000
- *   database:
- *     url: "postgresql://localhost:5432/db"
- *     pool:
- *       min: 1
+ *   },
+ *   database: {
+ *     url: "postgresql://localhost:5432/db",
+ *     pool: {
+ *       min: 1,
  *       max: 10
+ *     }
+ *   }
  * });
  */
 export type StaticYamlFile = File;
 export async function StaticYamlFile(
   id: string,
-  content: any,
+  ...args: [content: any] | [path: string, content: any]
 ): Promise<StaticYamlFile> {
+  const [path, content] = args.length === 1 ? [id, args[0]] : args;
   const yaml = await import("yaml");
   return File(id, {
-    path: id,
+    path,
     content: yaml.stringify(content),
   });
 }

package/src/internal/getting-started.ts CHANGED Viewed

@@ -1,93 +1,103 @@
-import alchemy from "alchemy";
-import { Document } from "alchemy/ai";
-import type { Folder } from "alchemy/fs";
-import path from "path";
+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.
    */
-  outDir: string | Folder;
+  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({
-  outDir,
+  path: outFile,
+  prompt,
+  model = {
+    id: "claude-3-5-sonnet-latest",
+    provider: "anthropic",
+  },
 }: GettingStartedProps): Promise<Document> {
-  outDir = typeof outDir === "string" ? outDir : outDir.path;
   return Document(`docs/getting-started`, {
-    title: "Getting Started with Alchemy",
-    path: path.join(outDir, "index.md"),
+    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 for Alchemy, an infrastructure as code (IaC) framework.
-      See ${alchemy.file("../README.md")} to understand the overview of Alchemy.
-      See ${alchemy.file("../.cursorrules")} to better understand the structure and conventions of Alchemy.
-      See ${alchemy.file("../alchemy/test/cloudflare/worker.test.ts")} for an example of how testing works.
-      Write a comprehensive getting started guide for Alchemy that covers the following topics:
+      You are a technical writer creating a getting started guide.
+      ${prompt}
-      # Getting Started with Alchemy
+      If you need a template structure to follow, use this format:
-      (Brief introduction to Alchemy as an infrastructure as code framework)
+      # Getting Started with [Product/Framework Name]
+      (Brief introduction to the product/framework)
       ## Installation
       \`\`\`bash
-      # Install Alchemy
-      bun add alchemy
+      # Installation command
       \`\`\`
-      ## Creating Your First Alchemy Project
+      ## Creating Your First Project
-      (Step-by-step guide to creating a basic Alchemy project)
+      (Step-by-step guide to creating a basic project)
       \`\`\`ts
-      // Example of a simple Alchemy project
-      import alchemy from "alchemy";
-      // Sample code here
+      // Example of a simple project
       \`\`\`
       ## Core Concepts
-      ### Resources
+      ### [Concept 1]
-      (Explanation of Alchemy resources and how they work)
+      (Explanation of the first core concept)
       \`\`\`ts
-      // Example of creating a resource
+      // Example of using the concept
       \`\`\`
-      ### Context
+      ### [Concept 2]
-      (Explanation of Alchemy context and lifecycle management)
+      (Explanation of the second core concept)
       \`\`\`ts
-      // Example of working with context
+      // Example of using the concept
       \`\`\`
-      ## Working with Secrets
+      ## Working with [Feature]
-      (How to handle secrets in Alchemy)
+      (How to use a specific feature)
       \`\`\`ts
-      // Example of using alchemy.secret()
-      const apiKey = alchemy.secret("API_KEY");
+      // Example of using the feature
       \`\`\`
       ## Testing
-      (How to test Alchemy resources)
+      (How to test your project)
       \`\`\`ts
-      // Example of testing Alchemy resources
+      // Example of testing
       \`\`\`
       ## Deployment
-      (How to deploy resources with Alchemy)
+      (How to deploy your project)
       \`\`\`ts
       // Example of deployment
@@ -95,13 +105,11 @@ export async function GettingStarted({
       ## Next Steps
-      (Where to go next to learn more about Alchemy)
-      > [!CAUTION]
-      > Avoid the temptation to over explain or over describe. Focus on concise, simple, high value snippets.
+      (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 ADDED Viewed

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

package/src/internal/providers.ts CHANGED Viewed

@@ -1,15 +1,21 @@
-import alchemy from "alchemy";
-import { Data, Document } from "alchemy/ai";
-import { Folder } from "alchemy/fs";
 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.
@@ -28,17 +34,25 @@ export type AlchemyProviderDocs = {
 }[];
 export async function AlchemyProviderDocs({
+  srcDir,
   outDir,
   filter,
 }: DocsProps): Promise<AlchemyProviderDocs> {
   outDir = typeof outDir === "string" ? outDir : outDir.path;
-  const providersDir = (await Folder(path.join(outDir, "providers"))).path;
-  const exclude = ["util", "test", "vitepress", "vite", "shadcn", "internal"];
+  const exclude = [
+    "util",
+    "test",
+    "vitepress",
+    "vite",
+    "shadcn",
+    "internal",
+    "web",
+  ];
   // Get all folders in the alchemy/src directory
   let providers = (
-    await fs.readdir(path.resolve("..", "alchemy", "src"), {
+    await fs.readdir(srcDir, {
       withFileTypes: true,
     })
   )
@@ -62,7 +76,7 @@ export async function AlchemyProviderDocs({
       )
         .filter((dirent) => dirent.isFile())
         .map((dirent) =>
-          path.relative(process.cwd(), path.resolve(provider, dirent.name)),
+          path.relative(process.cwd(), path.resolve(provider, dirent.name))
         )
         .filter((file) => file.endsWith(".ts") && !file.endsWith("index.ts"));
@@ -70,23 +84,23 @@ export async function AlchemyProviderDocs({
         object: { groups },
       } = await Data(`docs/${providerName}`, {
         model: {
-          id: "gpt-4o",
+          id: "o3-mini",
           provider: "openai",
-          // options: {
-          //   reasoningEffort: "high",
-          // },
+          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.",
+              "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",
+              "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.",
+              "The classification of the Resource's Document, one of: Resource, Client, Utility, or Types."
             ),
           }).array(),
         }),
@@ -97,8 +111,8 @@ export async function AlchemyProviderDocs({
         `,
         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")}.
+          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)}
@@ -117,11 +131,10 @@ export async function AlchemyProviderDocs({
       // console.log(groups);
-      const providerDocsDir = (
-        await Folder(path.join(providersDir, providerName))
-      ).path;
+      const providerDocsDir = (await Folder(path.join(outDir, providerName)))
+        .path;
-      const documents = await Promise.all(
+      const documents = await Promise.allSettled(
         groups
           .filter((g) => g.category === "Resource")
           .map(async (g) =>
@@ -129,12 +142,19 @@ export async function AlchemyProviderDocs({
               title: g.title,
               path: path.join(
                 providerDocsDir,
-                `${g.filename.replace(".ts", "").replace(".md", "")}.md`,
+                `${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.
+                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)}
@@ -157,6 +177,8 @@ export async function AlchemyProviderDocs({
                 # Minimal Example
+                (brief 1-2 sentences of what it does)
                 \`\`\`ts
                 import { ${g.title.replaceAll(" ", "")} } from "alchemy/${providerName}";
@@ -195,15 +217,25 @@ export async function AlchemyProviderDocs({
                     : ""
                 }
               `,
-            }),
-          ),
+            })
+          )
+      );
+      // 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,
+        documents: results,
       } as const;
-    }),
+    })
   );
 }