alchemy 0.3.1 → 0.4.1

package/src/{util/encrypt.ts → encrypt.ts}

@@ -7,17 +7,14 @@ import sodium from "libsodium-wrappers";
  * @param key - The encryption key
  * @returns The base64-encoded encrypted value with nonce
  */
-export async function encryptWithKey(
-  value: string,
-  key: string,
-): Promise<string> {
+export async function encrypt(value: string, key: string): Promise<string> {
   // Initialize libsodium
   await sodium.ready;
 
   // Derive a key from the passphrase
   const cryptoKey = sodium.crypto_generichash(
     sodium.crypto_secretbox_KEYBYTES,
-    sodium.from_string(key),
+    sodium.from_string(key)
   );
 
   // Generate a random nonce
@@ -27,7 +24,7 @@ export async function encryptWithKey(
   const encryptedBin = sodium.crypto_secretbox_easy(
     sodium.from_string(value),
     nonce,
-    cryptoKey,
+    cryptoKey
   );
 
   // Combine nonce and ciphertext, then encode to base64
@@ -47,7 +44,7 @@ export async function encryptWithKey(
  */
 export async function decryptWithKey(
   encryptedValue: string,
-  key: string,
+  key: string
 ): Promise<string> {
   // Initialize libsodium
   await sodium.ready;
@@ -55,13 +52,13 @@ export async function decryptWithKey(
   // Derive a key from the passphrase
   const cryptoKey = sodium.crypto_generichash(
     sodium.crypto_secretbox_KEYBYTES,
-    sodium.from_string(key),
+    sodium.from_string(key)
   );
 
   // Decode the base64 combined value
   const combined = sodium.from_base64(
     encryptedValue,
-    sodium.base64_variants.ORIGINAL,
+    sodium.base64_variants.ORIGINAL
   );
 
   // Extract nonce and ciphertext
@@ -72,7 +69,7 @@ export async function decryptWithKey(
   const decryptedBin = sodium.crypto_secretbox_open_easy(
     ciphertext,
     nonce,
-    cryptoKey,
+    cryptoKey
   );
 
   return sodium.to_string(decryptedBin);

package/src/fs/file-system-state-store.ts

@@ -1,9 +1,9 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import type { Scope } from "../scope";
+import { deserialize, serialize } from "../serde";
 import type { State, StateStore } from "../state";
 import { ignore } from "../util/ignore";
-import { deserialize, serialize } from "../util/serde";
 
 const stateRootDir = path.join(process.cwd(), ".alchemy");
 
@@ -48,7 +48,7 @@ export class FileSystemStateStore implements StateStore {
       const content = await fs.readFile(await this.getPath(key), "utf8");
       const state = (await deserialize(
         this.scope,
-        JSON.parse(content),
+        JSON.parse(content)
       )) as State;
       if (state.output === undefined) {
         state.output = {} as any;
@@ -66,7 +66,7 @@ export class FileSystemStateStore implements StateStore {
   async set(key: string, value: State): Promise<void> {
     return fs.writeFile(
       await this.getPath(key),
-      JSON.stringify(await serialize(this.scope, value), null, 2),
+      JSON.stringify(await serialize(this.scope, value), null, 2)
     );
   }
 
@@ -88,9 +88,9 @@ export class FileSystemStateStore implements StateStore {
               return [] as const;
             }
             return [[id, s]] as const;
-          }),
+          })
         )
-      ).flat(),
+      ).flat()
     );
   }
 

package/src/fs/file.ts

@@ -52,6 +52,28 @@ declare module "../alchemy" {
      */
     files(paths: string[]): Promise<FileCollection>;
     files(path: string, ...paths: string[]): Promise<FileCollection>;
+
+    /**
+     * Gets all of the files in a directory.
+     * @param path Path to the directory
+     * @param props Optional properties
+     * @returns Promise resolving to a FileCollection
+     *
+     * @example
+     * // Get all files in a directory
+     * const files = await alchemy.folder("./docs");
+     *
+     */
+    folder(
+      path: string,
+      props?: {
+        /**
+         * Whether to recursively get all files in the directory
+         * @default false
+         */
+        recursive?: boolean;
+      }
+    ): Promise<FileCollection>;
   }
 }
 
@@ -78,6 +100,13 @@ alchemy.files = async (
   };
 };
 
+alchemy.folder = async (dir: string, props?: { recursive?: boolean }) => {
+  const files = await fs.promises.readdir(dir, {
+    recursive: props?.recursive ?? false,
+  });
+  return alchemy.files(files.map((file) => path.join(dir, file)));
+};
+
 /**
  * Base file resource type
  */

package/src/internal/docs/providers.ts

@@ -0,0 +1,281 @@
+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;
+
+  /**
+   * Whether to run in parallel.
+   *
+   * @default true
+   */
+  parallel?: boolean;
+}
+
+export type Providers = {
+  dir: string;
+  provider: string;
+  documents: Document[];
+}[];
+
+export async function Providers({
+  srcDir,
+  outDir,
+  filter,
+  parallel = true,
+}: DocsProps): Promise<Providers> {
+  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);
+  }
+
+  if (parallel) {
+    return await Promise.all(
+      providers.map((provider) =>
+        generateProviderDocs({ provider, outDir, parallel })
+      )
+    );
+  } else {
+    const generatedProviders = [];
+    for (const provider of providers) {
+      generatedProviders.push(
+        await generateProviderDocs({ provider, outDir, parallel })
+      );
+    }
+    return generatedProviders;
+  }
+}
+
+async function generateProviderDocs({
+  provider,
+  outDir,
+  parallel,
+}: {
+  provider: string;
+  outDir: string;
+  parallel: boolean;
+}) {
+  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"));
+
+  type Group = (typeof groups)[number];
+
+  const {
+    object: { groups },
+  } = await Data(`docs/${providerName}`, {
+    model: {
+      id: "o3-mini",
+      provider: "openai",
+      options: {
+        reasoningEffort: "high",
+      },
+    },
+    temperature: 0.1,
+    schema: type({
+      groups: type({
+        identifier: type("string").describe(
+          "The identifier of the file's primary exported Resource/Function/Type, e.g. Bucket or StaticSite, AstroFile, TypeScriptFile"
+        ),
+        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(...)
+    `,
+  });
+
+  const providerDocsDir = (await Folder(path.join(outDir, providerName))).path;
+
+  let documents: Document[] = [];
+  if (parallel) {
+    documents = await Promise.all(
+      groups.filter((g) => g.category === "Resource").map(generateDocument)
+    );
+  } else {
+    for (const g of groups.filter((g) => g.category === "Resource")) {
+      documents.push(await generateDocument(g));
+    }
+  }
+
+  async function generateDocument(g: Group) {
+    return Document(`docs/${providerName}/${g.identifier}`, {
+      title: g.identifier,
+      path: path.join(
+        providerDocsDir,
+        `${g.filename.replace(".ts", "").replace(".md", "")}.md`
+      ),
+      freeze: true,
+      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.identifier}" 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.identifier}
+
+        (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.identifier.replaceAll(" ", "")} } from "alchemy/${providerName}";
+
+        (example)
+        \`\`\`
+
+        # (one heading per variation)
+
+        (brief 1-2 sentences of what it does)
+
+        \`\`\`ts
+        import { ${g.identifier.replaceAll(" ", "")} } from "alchemy/${providerName}";
+
+        (example)
+        \`\`\`
+
+        Before writing the document, think through:
+        1. What is the minimal, most common example use case for this resource?
+        2. What are the variations (e.g. combination of different options) that are also commonly used, e.g. specifying the memory size of a lambda function.
+        3. Make sure to draw from the examples and your understanding of Alchemy.
+
+        Refer to alchemy docs to understand the context of how this documentation is consumed:
+        - ${alchemy.file("./alchemy-web/docs/what-is-alchemy.md")}
+        - ${alchemy.file("./alchemy-web/docs/getting-started.md")}
+        - ${alchemy.folder("./alchemy-web/docs/concepts/")}
+        
+        ${
+          providerName === "cloudflare"
+            ? await alchemy`# Bind to a Worker
+        (if it is a Cloudflare Resource)
+
+        (brief 1-2 sentences of what it does)
+
+        \`\`\`ts
+        import { Worker, ${g.identifier.replaceAll(" ", "")} } from "alchemy/${providerName}";
+
+        const myResource = await ${g.identifier.replaceAll(" ", "")}("my-resource", {
+          // ...
+        });
+
+        await Worker("my-worker", {
+          name: "my-worker",
+          script: "console.log('Hello, world!')",
+          bindings: {
+            myResource,
+          },
+        });
+        \`\`\``
+            : ""
+        }
+      `,
+    });
+  }
+
+  return {
+    dir: providerDocsDir,
+    provider: providerName,
+    documents,
+  };
+}

package/src/secret.ts

@@ -83,3 +83,19 @@ export function secret<S extends string | undefined>(unencrypted: S): Secret {
   }
   return new Secret(unencrypted);
 }
+
+export namespace secret {
+  export async function env(
+    name: string,
+    value?: string,
+    error?: string
+  ): Promise<Secret> {
+    const alchemy = await import("./alchemy");
+    const result = await alchemy.env(name, value, error);
+    if (typeof result === "string") {
+      return secret(result);
+    } else {
+      throw new Error(`Secret environment variable ${name} is not a string`);
+    }
+  }
+}

package/src/{util/serde.ts → serde.ts}

@@ -1,6 +1,6 @@
-import { Scope } from "../scope";
-import { Secret } from "../secret";
-import { decryptWithKey, encryptWithKey } from "./encrypt";
+import { decryptWithKey, encrypt } from "./encrypt";
+import { Scope } from "./scope";
+import { Secret } from "./secret";
 
 import type { Type } from "arktype";
 
@@ -18,7 +18,7 @@ export async function serialize(
   value: any,
   options?: {
     encrypt?: boolean;
-  },
+  }
 ): Promise<any> {
   if (Array.isArray(value)) {
     return Promise.all(value.map((value) => serialize(scope, value, options)));
@@ -29,13 +29,17 @@ export async function serialize(
     return {
       "@secret":
         options?.encrypt !== false
-          ? await encryptWithKey(value.unencrypted, scope.password)
+          ? await encrypt(value.unencrypted, scope.password)
           : value.unencrypted,
     };
   } else if (isType(value)) {
     return {
       "@schema": value.toJSON(),
     };
+  } else if (value instanceof Date) {
+    return {
+      "@date": value.toISOString(),
+    };
   } else if (value instanceof Scope) {
     return undefined;
   } else if (value && typeof value === "object") {
@@ -44,8 +48,8 @@ export async function serialize(
         Object.entries(value).map(async ([key, value]) => [
           key,
           await serialize(scope, value, options),
-        ]),
-      ),
+        ])
+      )
     );
   }
   return value;
@@ -54,7 +58,7 @@ export async function serialize(
 export async function deserialize(scope: Scope, value: any): Promise<any> {
   if (Array.isArray(value)) {
     return await Promise.all(
-      value.map(async (item) => await deserialize(scope, item)),
+      value.map(async (item) => await deserialize(scope, item))
     );
   } else if (value && typeof value === "object") {
     if (typeof value["@secret"] === "string") {
@@ -64,14 +68,16 @@ export async function deserialize(scope: Scope, value: any): Promise<any> {
       return new Secret(await decryptWithKey(value["@secret"], scope.password));
     } else if ("@schema" in value) {
       return value["@schema"];
+    } else if ("@date" in value) {
+      return new Date(value["@date"]);
     } else {
       return Object.fromEntries(
         await Promise.all(
           Object.entries(value).map(async ([key, value]) => [
             key,
             await deserialize(scope, value),
-          ]),
-        ),
+          ])
+        )
       );
     }
   }

package/src/test/bun.ts

@@ -78,7 +78,7 @@ type test = {
     name: string,
     options: TestOptions,
     fn: (scope: Scope) => Promise<any>,
-    timeout?: number,
+    timeout?: number
   ): void;
 
   /**
@@ -121,6 +121,7 @@ type test = {
  * ```
  */
 export function test(meta: ImportMeta, defaultOptions?: TestOptions): test {
+  let isFailed = false;
   defaultOptions = defaultOptions ?? {};
   if (
     defaultOptions.stateStore === undefined &&
@@ -129,7 +130,7 @@ export function test(meta: ImportMeta, defaultOptions?: TestOptions): test {
   ) {
     defaultOptions.stateStore = (scope) =>
       new R2RestStateStore(scope, {
-        apiKey: process.env.CLOUDFLARE_API_KEY,
+        apiKey: alchemy.secret(process.env.CLOUDFLARE_API_KEY),
         email: process.env.CLOUDFLARE_EMAIL,
         bucketName: process.env.CLOUDFLARE_BUCKET_NAME!,
       });
@@ -150,7 +151,7 @@ export function test(meta: ImportMeta, defaultOptions?: TestOptions): test {
     {
       // parent: globalTestScope,
       stateStore: defaultOptions?.stateStore,
-    },
+    }
   );
   test.scope = localTestScope;
 
@@ -170,7 +171,7 @@ export function test(meta: ImportMeta, defaultOptions?: TestOptions): test {
 
   // Clean up test scope after all tests complete
   afterAll(async () => {
-    if (defaultOptions?.destroy !== false) {
+    if (defaultOptions?.destroy !== false && !isFailed) {
       await alchemy.destroy(test.scope);
     }
   });
@@ -192,8 +193,8 @@ export function test(meta: ImportMeta, defaultOptions?: TestOptions): test {
       obj && typeof obj === "object"
         ? Object.fromEntries(
             Object.entries(obj).flatMap(([k, v]) =>
-              v !== undefined ? [[k, v]] : [],
-            ),
+              v !== undefined ? [[k, v]] : []
+            )
           )
         : {};
 
@@ -229,7 +230,7 @@ export function test(meta: ImportMeta, defaultOptions?: TestOptions): test {
             }
           }
         });
-      },
+      }
     );
   }
 }

package/src/util/sha256.ts

@@ -0,0 +1,5 @@
+import { createHash } from "node:crypto";
+
+export function sha256(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}

package/src/web/vitepress/config.ts

@@ -1,11 +1,12 @@
 import path from "path";
-import type { DefaultTheme, ThemeOptions } from "vitepress";
+import type { DefaultTheme, HeadConfig, ThemeOptions } from "vitepress";
 import { StaticTypeScriptFile } from "../../fs/static-typescript-file";
 
 export type VitePressConfigProps = {
   cwd: string;
   title?: string;
   description?: string;
+  head?: HeadConfig[];
   theme?: ThemeOptions;
   themeConfig: DefaultTheme.Config;
 };
@@ -23,6 +24,7 @@ import { defineConfig } from "vitepress";
 export default defineConfig({
   title: ${JSON.stringify(props.title || "Alchemy")},
   description: ${JSON.stringify(props.description || "Alchemy Docs")},
+  head: ${JSON.stringify(props.head || [])},
   markdown: {
     // @ts-ignore
     codeTransformers: [transformerTwoslash()],

package/src/web/vitepress/index.ts

@@ -1,4 +1,5 @@
 export * from "./config";
 export * from "./custom-theme";
 export * from "./home-page";
+export * from "./process-front-matter-files";
 export * from "./vitepress";