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

alchemy 0.3.0 → 0.4.0

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 (154) hide show

package/README.md +8 -3
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 +76 -5
package/lib/ai/document.js +112 -56
package/lib/ai/html-file.js +7 -24
package/lib/ai/json-file.js +11 -32
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.d.ts +5 -0
package/lib/alchemy.js +61 -3
package/lib/apply.js +18 -11
package/lib/aws/account-id.d.ts +4 -1
package/lib/aws/account-id.js +1 -1
package/lib/aws/credentials.d.ts +5 -0
package/lib/aws/credentials.js +0 -0
package/lib/aws/oidc/oidc-provider.js +2 -2
package/lib/aws/role.js +35 -23
package/lib/cloudflare/account-api-token.d.ts +168 -0
package/lib/cloudflare/account-api-token.js +179 -0
package/lib/cloudflare/account-id.d.ts +1 -0
package/lib/cloudflare/account-id.js +0 -0
package/lib/cloudflare/api.d.ts +38 -1
package/lib/cloudflare/api.js +55 -4
package/lib/cloudflare/bucket.d.ts +118 -3
package/lib/cloudflare/bucket.js +269 -89
package/lib/cloudflare/custom-domain.d.ts +75 -0
package/lib/cloudflare/custom-domain.js +154 -0
package/lib/cloudflare/{dns.js → dns-records.js} +14 -1
package/lib/cloudflare/generate-asset-manifest.js +1 -1
package/lib/cloudflare/index.d.ts +5 -1
package/lib/cloudflare/index.js +5 -1
package/lib/cloudflare/permission-groups.d.ts +78 -0
package/lib/cloudflare/permission-groups.js +48 -0
package/lib/cloudflare/r2-rest-state-store.d.ts +2 -1
package/lib/cloudflare/r2-rest-state-store.js +3 -2
package/lib/cloudflare/static-site-router.js +16 -7
package/lib/cloudflare/static-site.d.ts +17 -18
package/lib/cloudflare/static-site.js +19 -7
package/lib/cloudflare/upload-asset-manifest.js +4 -2
package/lib/{util/encrypt.d.ts → encrypt.d.ts} +1 -1
package/lib/{util/encrypt.js → encrypt.js} +1 -1
package/lib/fs/copy-file.d.ts +54 -0
package/lib/fs/copy-file.js +63 -0
package/lib/fs/file-system-state-store.js +1 -1
package/lib/fs/file.d.ts +31 -0
package/lib/fs/file.js +30 -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/{providers.d.ts → docs/providers.d.ts} +14 -4
package/lib/internal/docs/providers.js +196 -0
package/lib/secret.d.ts +3 -0
package/lib/secret.js +13 -0
package/lib/{util/serde.d.ts → serde.d.ts} +1 -1
package/lib/{util/serde.js → serde.js} +12 -4
package/lib/test/bun.js +3 -2
package/lib/util/sha256.d.ts +1 -0
package/lib/util/sha256.js +4 -0
package/lib/web/vitepress/config.d.ts +11 -0
package/lib/web/vitepress/config.js +32 -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 +2 -0
package/lib/web/vitepress/index.js +2 -0
package/lib/web/vitepress/process-front-matter-files.d.ts +18 -0
package/lib/web/vitepress/process-front-matter-files.js +68 -0
package/lib/web/vitepress/vitepress.d.ts +5 -4
package/lib/web/vitepress/vitepress.js +20 -36
package/package.json +8 -4
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 +171 -66
package/src/ai/html-file.ts +11 -30
package/src/ai/json-file.ts +13 -37
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 +74 -9
package/src/apply.ts +27 -26
package/src/aws/account-id.ts +6 -2
package/src/aws/credentials.ts +6 -0
package/src/aws/oidc/oidc-provider.ts +17 -17
package/src/aws/role.ts +68 -54
package/src/cloudflare/account-api-token.ts +365 -0
package/src/cloudflare/account-id.ts +0 -0
package/src/cloudflare/api.ts +88 -17
package/src/cloudflare/bucket.ts +493 -133
package/src/cloudflare/custom-domain.ts +318 -0
package/src/cloudflare/{dns.ts → dns-records.ts} +36 -22
package/src/cloudflare/generate-asset-manifest.ts +4 -4
package/src/cloudflare/index.ts +5 -1
package/src/cloudflare/permission-groups.ts +137 -0
package/src/cloudflare/r2-rest-state-store.ts +14 -13
package/src/cloudflare/static-site-router.ts +18 -8
package/src/cloudflare/static-site.ts +27 -35
package/src/cloudflare/upload-asset-manifest.ts +6 -4
package/src/cloudflare/worker.ts +44 -43
package/src/dns/import-dns.ts +4 -4
package/src/{util/encrypt.ts → encrypt.ts} +7 -10
package/src/fs/copy-file.ts +115 -0
package/src/fs/file-system-state-store.ts +5 -5
package/src/fs/file.ts +64 -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/docs/providers.ts +281 -0
package/src/secret.ts +16 -0
package/src/{util/serde.ts → serde.ts} +16 -10
package/src/test/bun.ts +8 -7
package/src/util/sha256.ts +5 -0
package/src/web/vitepress/config.ts +50 -0
package/src/web/vitepress/home-page.ts +54 -42
package/src/web/vitepress/index.ts +2 -0
package/src/web/vitepress/process-front-matter-files.ts +98 -0
package/src/web/vitepress/vitepress.ts +34 -50
package/lib/internal/getting-started.d.ts +0 -10
package/lib/internal/getting-started.js +0 -94
package/lib/internal/project.d.ts +0 -13
package/lib/internal/project.js +0 -101
package/lib/internal/providers.js +0 -148
package/src/internal/getting-started.ts +0 -107
package/src/internal/project.ts +0 -119
package/src/internal/providers.ts +0 -209
/package/lib/cloudflare/{dns.d.ts → dns-records.d.ts} +0 -0

package/lib/fs/static-astro-file.d.ts ADDED Viewed

@@ -0,0 +1,34 @@
+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 declare function StaticAstroFile(id: string, ...args: [content: string] | [path: string, content: string]): Promise<StaticAstroFile>;

package/lib/fs/static-astro-file.js ADDED Viewed

@@ -0,0 +1,39 @@
+import { File } from "./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, ...args) {
+    const [path, content] = args.length === 1 ? [id, args[0]] : args;
+    return File(id, {
+        path,
+        content,
+    });
+}

package/lib/fs/static-css-file.d.ts ADDED Viewed

@@ -0,0 +1,24 @@
+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 declare function StaticCSSFile(id: string, ...args: [content: string] | [path: string, content: string]): Promise<StaticCSSFile>;

package/lib/fs/static-css-file.js ADDED Viewed

@@ -0,0 +1,29 @@
+import { File } from "./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, ...args) {
+    const [path, content] = args.length === 1 ? [id, args[0]] : args;
+    return File(id, {
+        path,
+        content,
+    });
+}

package/lib/fs/static-html-file.d.ts ADDED Viewed

@@ -0,0 +1,31 @@
+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 declare function StaticHTMLFile(id: string, ...args: [content: string] | [path: string, content: string]): Promise<StaticHTMLFile>;

package/lib/fs/static-html-file.js ADDED Viewed

@@ -0,0 +1,36 @@
+import { File } from "./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, ...args) {
+    const [path, content] = args.length === 1 ? [id, args[0]] : args;
+    return File(id, {
+        path,
+        content,
+    });
+}

package/lib/fs/static-json-file.d.ts CHANGED Viewed

@@ -4,7 +4,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"
@@ -13,4 +13,4 @@ import { File } from "./file";
  * });
  */
 export type StaticJsonFile = File;
-export declare function StaticJsonFile(id: string, content: any): Promise<StaticJsonFile>;
+export declare function StaticJsonFile(id: string, ...args: [content: any] | [path: string, content: any]): Promise<StaticJsonFile>;

package/lib/fs/static-json-file.js CHANGED Viewed

@@ -1,8 +1,9 @@
 import { File } from "./file";
-export async function StaticJsonFile(id, content) {
+export async function StaticJsonFile(id, ...args) {
+    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/lib/fs/static-text-file.d.ts CHANGED Viewed

@@ -9,4 +9,4 @@ import { File } from "./file";
  * );
  */
 export type StaticTextFile = File;
-export declare function StaticTextFile(id: string, content: string): Promise<StaticTextFile>;
+export declare function StaticTextFile(id: string, ...args: [content: string] | [path: string, content: string]): Promise<StaticTextFile>;

package/lib/fs/static-text-file.js CHANGED Viewed

@@ -1,7 +1,8 @@
 import { File } from "./file";
-export function StaticTextFile(id, content) {
+export function StaticTextFile(id, ...args) {
+    const [path, content] = args.length === 1 ? [id, args[0]] : args;
     return File(id, {
-        path: id,
+        path,
         content,
     });
 }

package/lib/fs/static-typescript-file.d.ts CHANGED Viewed

@@ -4,7 +4,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;
@@ -16,4 +16,4 @@ import { File } from "./file";
  * `);
  */
 export type StaticTypeScriptFile = File;
-export declare function StaticTypeScriptFile(id: string, content: string): Promise<StaticTypeScriptFile>;
+export declare function StaticTypeScriptFile(id: string, ...args: [content: string] | [path: string, content: string]): Promise<StaticTypeScriptFile>;

package/lib/fs/static-typescript-file.js CHANGED Viewed

@@ -1,8 +1,9 @@
 import { File } from "./file";
-export async function StaticTypeScriptFile(id, content) {
+export async function StaticTypeScriptFile(id, ...args) {
+    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/lib/fs/static-vue-file.d.ts ADDED Viewed

@@ -0,0 +1,28 @@
+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 declare function StaticVueFile(id: string, ...args: [content: string] | [path: string, content: string]): Promise<StaticVueFile>;

package/lib/fs/static-vue-file.js ADDED Viewed

@@ -0,0 +1,33 @@
+import { File } from "./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, ...args) {
+    const [path, content] = args.length === 1 ? [id, args[0]] : args;
+    return File(id, {
+        path,
+        content,
+    });
+}

package/lib/fs/static-yaml-file.d.ts CHANGED Viewed

@@ -4,16 +4,19 @@ 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 declare function StaticYamlFile(id: string, content: any): Promise<StaticYamlFile>;
+export declare function StaticYamlFile(id: string, ...args: [content: any] | [path: string, content: any]): Promise<StaticYamlFile>;

package/lib/fs/static-yaml-file.js CHANGED Viewed

@@ -1,8 +1,9 @@
 import { File } from "./file";
-export async function StaticYamlFile(id, content) {
+export async function StaticYamlFile(id, ...args) {
+    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/lib/internal/{providers.d.ts → docs/providers.d.ts} RENAMED Viewed

@@ -1,10 +1,14 @@
-import { Document } from "alchemy/ai";
-import { Folder } from "alchemy/fs";
+import { Document } from "../../ai";
+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.
@@ -14,10 +18,16 @@ export interface DocsProps {
      * @default true (all docs)
      */
     filter?: boolean | number;
+    /**
+     * Whether to run in parallel.
+     *
+     * @default true
+     */
+    parallel?: boolean;
 }
-export type AlchemyProviderDocs = {
+export type Providers = {
     dir: string;
     provider: string;
     documents: Document[];
 }[];
-export declare function AlchemyProviderDocs({ outDir, filter, }: DocsProps): Promise<AlchemyProviderDocs>;
+export declare function Providers({ srcDir, outDir, filter, parallel, }: DocsProps): Promise<Providers>;

package/lib/internal/docs/providers.js ADDED Viewed

@@ -0,0 +1,196 @@
+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 Providers({ srcDir, outDir, filter, parallel = true, }) {
+    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, }) {
+    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({
+                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 = [];
+    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) {
+        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/lib/secret.d.ts CHANGED Viewed

@@ -72,3 +72,6 @@ export declare function isSecret(binding: any): binding is Secret;
  * @throws {Error} If no password is set in the alchemy application options or current scope
  */
 export declare function secret<S extends string | undefined>(unencrypted: S): Secret;
+export declare namespace secret {
+    function env(name: string, value?: string, error?: string): Promise<Secret>;
+}

package/lib/secret.js CHANGED Viewed

@@ -82,3 +82,16 @@ export function secret(unencrypted) {
     }
     return new Secret(unencrypted);
 }
+(function (secret) {
+    async function env(name, value, error) {
+        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`);
+        }
+    }
+    secret.env = env;
+})(secret || (secret = {}));

package/lib/{util/serde.d.ts → serde.d.ts} RENAMED Viewed

@@ -1,4 +1,4 @@
-import { Scope } from "../scope";
+import { Scope } from "./scope";
 export declare function serialize(scope: Scope, value: any, options?: {
     encrypt?: boolean;
 }): Promise<any>;