alchemy 0.2.5 → 0.3.0

package/lib/fs/file-system-state-store.js

@@ -0,0 +1,87 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { ignore } from "../util/ignore";
+import { deserialize, serialize } from "../util/serde";
+const stateRootDir = path.join(process.cwd(), ".alchemy");
+export class FileSystemStateStore {
+    scope;
+    dir;
+    constructor(scope) {
+        this.scope = scope;
+        this.dir = path.join(stateRootDir, ...scope.chain);
+    }
+    async init() {
+        await fs.mkdir(stateRootDir, { recursive: true });
+        await fs.mkdir(this.dir, { recursive: true });
+    }
+    async deinit() {
+        await ignore("ENOENT", () => fs.rmdir(this.dir));
+    }
+    async count() {
+        return Object.keys(await this.list()).length;
+    }
+    async list() {
+        try {
+            const files = await fs.readdir(this.dir, {
+                withFileTypes: true,
+            });
+            return files
+                .filter((dirent) => dirent.isFile() && dirent.name.endsWith(".json"))
+                .map((dirent) => dirent.name.replace(/\.json$/, ""))
+                .map((key) => key.replaceAll(":", "/"));
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                return [];
+            }
+            throw error;
+        }
+    }
+    async get(key) {
+        try {
+            const content = await fs.readFile(await this.getPath(key), "utf8");
+            const state = (await deserialize(this.scope, JSON.parse(content)));
+            if (state.output === undefined) {
+                state.output = {};
+            }
+            state.output.Scope = this.scope;
+            return state;
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                return undefined;
+            }
+            throw error;
+        }
+    }
+    async set(key, value) {
+        return fs.writeFile(await this.getPath(key), JSON.stringify(await serialize(this.scope, value), null, 2));
+    }
+    async delete(key) {
+        return fs.unlink(await this.getPath(key));
+    }
+    async all() {
+        return this.getBatch(await this.list());
+    }
+    async getBatch(ids) {
+        return Object.fromEntries((await Promise.all(Array.from(ids).flatMap(async (id) => {
+            const s = await this.get(id);
+            if (s === undefined) {
+                return [];
+            }
+            return [[id, s]];
+        }))).flat());
+    }
+    async getPath(key) {
+        if (key.includes(":")) {
+            throw new Error(`ID cannot include colons: ${key}`);
+        }
+        if (key.includes("/")) {
+            key = key.replaceAll("/", ":");
+        }
+        const file = path.join(this.dir, `${key}.json`);
+        const dir = path.dirname(file);
+        await fs.mkdir(dir, { recursive: true });
+        return file;
+    }
+}

package/lib/fs/folder.d.ts

@@ -10,6 +10,16 @@ export interface FolderProps {
      * @default true
      */
     delete?: boolean;
+    /**
+     * Whether to clean the folder during the deletion phase (even if it contains existing files)
+     * @default false
+     */
+    clean?: boolean;
+    /**
+     * Whether to create the folder recursively
+     * @default true
+     */
+    recursive?: boolean;
 }
 /**
  * Base folder resource type

package/lib/fs/folder.js

@@ -28,12 +28,12 @@ export const Folder = Resource("fs::Folder", async function (id, props) {
     if (this.phase === "delete") {
         if (props?.delete !== false) {
             // we just do a best effort attempt
-            await ignore(["ENOENT", "ENOTEMPTY"], async () => fs.promises.rmdir(dirPath));
+            await ignore(["ENOENT", "ENOTEMPTY"], async () => fs.promises.rmdir(dirPath, { recursive: props?.clean ?? false }));
         }
         return this.destroy();
     }
     else {
-        await ignore("EEXIST", async () => fs.promises.mkdir(dirPath, { recursive: true }));
+        await ignore("EEXIST", async () => fs.promises.mkdir(dirPath, { recursive: props?.recursive ?? true }));
     }
     return this({
         path: dirPath,

package/lib/fs/index.d.ts

@@ -2,7 +2,7 @@ export * from "./file";
 export * from "./file-collection";
 export * from "./file-ref";
 export * from "./folder";
-export * from "./json-file";
-export * from "./text-file";
-export * from "./typescript-file";
-export * from "./yaml-file";
+export * from "./static-json-file";
+export * from "./static-text-file";
+export * from "./static-typescript-file";
+export * from "./static-yaml-file";

package/lib/fs/index.js

@@ -2,7 +2,7 @@ export * from "./file";
 export * from "./file-collection";
 export * from "./file-ref";
 export * from "./folder";
-export * from "./json-file";
-export * from "./text-file";
-export * from "./typescript-file";
-export * from "./yaml-file";
+export * from "./static-json-file";
+export * from "./static-text-file";
+export * from "./static-typescript-file";
+export * from "./static-yaml-file";

package/lib/fs/{json-file.d.ts → static-json-file.d.ts}

@@ -12,5 +12,5 @@ import { File } from "./file";
  *   features: ["auth", "logging"]
  * });
  */
-export type JsonFile = File;
-export declare function JsonFile(id: string, content: any): Promise<JsonFile>;
+export type StaticJsonFile = File;
+export declare function StaticJsonFile(id: string, content: any): Promise<StaticJsonFile>;

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

@@ -0,0 +1,14 @@
+import { File } from "./file";
+export async function StaticJsonFile(id, content) {
+    const prettier = await import("prettier");
+    return File(id, {
+        path: id,
+        content: await prettier.format(JSON.stringify(content), {
+            parser: "json",
+            editor: {
+                tabWidth: 2,
+                indentWidth: 2,
+            },
+        }),
+    });
+}

package/lib/fs/{text-file.d.ts → static-text-file.d.ts}

@@ -8,5 +8,5 @@ import { File } from "./file";
  *   "# Project Name\n\nProject description goes here."
  * );
  */
-export type TextFile = File;
-export declare function TextFile(id: string, content: string): Promise<TextFile>;
+export type StaticTextFile = File;
+export declare function StaticTextFile(id: string, content: string): Promise<StaticTextFile>;

package/lib/fs/{text-file.js → static-text-file.js}

@@ -1,5 +1,5 @@
 import { File } from "./file";
-export function TextFile(id, content) {
+export function StaticTextFile(id, content) {
     return File(id, {
         path: id,
         content,

package/lib/fs/{typescript-file.d.ts → static-typescript-file.d.ts}

@@ -15,5 +15,5 @@ import { File } from "./file";
  *   }
  * `);
  */
-export type TypeScriptFile = File;
-export declare function TypeScriptFile(id: string, content: string): Promise<TypeScriptFile>;
+export type StaticTypeScriptFile = File;
+export declare function StaticTypeScriptFile(id: string, content: string): Promise<StaticTypeScriptFile>;

package/lib/fs/{typescript-file.js → static-typescript-file.js}

@@ -1,5 +1,5 @@
 import { File } from "./file";
-export async function TypeScriptFile(id, content) {
+export async function StaticTypeScriptFile(id, content) {
     const prettier = await import("prettier");
     return File(id, {
         path: id,

package/lib/fs/{yaml-file.d.ts → static-yaml-file.d.ts}

@@ -15,5 +15,5 @@ import { File } from "./file";
  *       max: 10
  * });
  */
-export type YamlFile = File;
-export declare function YamlFile(id: string, content: any): Promise<YamlFile>;
+export type StaticYamlFile = File;
+export declare function StaticYamlFile(id: string, content: any): Promise<StaticYamlFile>;

package/lib/fs/{yaml-file.js → static-yaml-file.js}

@@ -1,5 +1,5 @@
 import { File } from "./file";
-export async function YamlFile(id, content) {
+export async function StaticYamlFile(id, content) {
     const yaml = await import("yaml");
     return File(id, {
         path: id,

package/lib/internal/getting-started.d.ts

@@ -0,0 +1,10 @@
+import { Document } from "alchemy/ai";
+import type { Folder } from "alchemy/fs";
+export interface GettingStartedProps {
+    /**
+     * The output directory for the getting started document.
+     */
+    outDir: string | Folder;
+}
+export type GettingStarted = Document;
+export declare function GettingStarted({ outDir, }: GettingStartedProps): Promise<Document>;

package/lib/internal/getting-started.js

@@ -0,0 +1,94 @@
+import alchemy from "alchemy";
+import { Document } from "alchemy/ai";
+import path from "path";
+export async function GettingStarted({ outDir, }) {
+    outDir = typeof outDir === "string" ? outDir : outDir.path;
+    return Document(`docs/getting-started`, {
+        title: "Getting Started with Alchemy",
+        path: path.join(outDir, "index.md"),
+        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:
+      
+      # Getting Started with Alchemy
+      
+      (Brief introduction to Alchemy as an infrastructure as code framework)
+      
+      ## Installation
+      
+      \`\`\`bash
+      # Install Alchemy
+      bun add alchemy
+      \`\`\`
+      
+      ## Creating Your First Alchemy Project
+      
+      (Step-by-step guide to creating a basic Alchemy project)
+      
+      \`\`\`ts
+      // Example of a simple Alchemy project
+      import alchemy from "alchemy";
+      
+      // Sample code here
+      \`\`\`
+      
+      ## Core Concepts
+      
+      ### Resources
+      
+      (Explanation of Alchemy resources and how they work)
+      
+      \`\`\`ts
+      // Example of creating a resource
+      \`\`\`
+      
+      ### Context
+      
+      (Explanation of Alchemy context and lifecycle management)
+      
+      \`\`\`ts
+      // Example of working with context
+      \`\`\`
+      
+      ## Working with Secrets
+      
+      (How to handle secrets in Alchemy)
+      
+      \`\`\`ts
+      // Example of using alchemy.secret()
+      const apiKey = alchemy.secret("API_KEY");
+      \`\`\`
+      
+      ## Testing
+      
+      (How to test Alchemy resources)
+      
+      \`\`\`ts
+      // Example of testing Alchemy resources
+      \`\`\`
+      
+      ## Deployment
+      
+      (How to deploy resources with Alchemy)
+      
+      \`\`\`ts
+      // Example of deployment
+      \`\`\`
+      
+      ## 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.
+      
+      > [!TIP]
+      > Make sure the examples follow a natural progression from minimal examples to more complex use cases.
+    `,
+    });
+}

package/lib/internal/project.d.ts

@@ -0,0 +1,13 @@
+import { VitePressProject } from "../web/vitepress";
+import type { AlchemyProviderDocs } from "./providers";
+export interface AlchemyProjectProps {
+    hero: {
+        text: string;
+        tagline: string;
+    };
+    docs: {
+        providers?: AlchemyProviderDocs;
+    };
+}
+export type AlchemyProject = VitePressProject;
+export declare function AlchemyProject({ hero, docs, }: AlchemyProjectProps): Promise<AlchemyProject>;

package/lib/internal/project.js

@@ -0,0 +1,101 @@
+import path from "path";
+import { VitePressProject } from "../web/vitepress";
+export function AlchemyProject({ hero, docs, }) {
+    return VitePressProject("project", {
+        name: "alchemy-web",
+        title: "Alchemy",
+        dir: process.cwd(),
+        description: "Alchemy is an TypeScript-native, embeddable IaC library",
+        overwrite: true,
+        delete: false,
+        scripts: {
+            deploy: "bun --env-file ../.env alchemy.run.ts",
+        },
+        tsconfig: {
+            extends: "../tsconfig.base.json",
+            references: ["../alchemy/tsconfig.json"],
+        },
+        devDependencies: {
+            alchemy: "workspace:*",
+        },
+        theme: {
+            light: "light-plus",
+            dark: "dark-plus",
+        },
+        themeConfig: {
+            sidebar: {
+                "/blog/": [{ text: "Blog", items: [{ text: "Blog", link: "/blog/" }] }],
+                "/docs/": [
+                    {
+                        text: "Getting Started",
+                        items: [{ text: "Install", link: "/docs/getting-started/install" }],
+                    },
+                    {
+                        text: "Guides",
+                        items: [
+                            {
+                                text: "Custom Resource",
+                                link: "/docs/guides/custom-resource",
+                            },
+                            {
+                                text: "Automating with LLMs",
+                                link: "/docs/guides/llms",
+                            },
+                        ],
+                    },
+                    {
+                        text: "Core",
+                        collapsed: true,
+                        items: [
+                            { text: "App", link: "/docs/core/app" },
+                            { text: "Resource", link: "/docs/core/resource" },
+                            { text: "Scope", link: "/docs/core/scope" },
+                            { text: "Phase", link: "/docs/core/phase" },
+                            { text: "Finalize", link: "/docs/core/finalize" },
+                            { text: "State", link: "/docs/core/state" },
+                            { text: "Secret", link: "/docs/core/secret" },
+                            { text: "Context", link: "/docs/core/context" },
+                        ],
+                    },
+                    {
+                        text: "Providers",
+                        items: (docs.providers ?? [])
+                            .map((provider) => ({
+                            text: provider.provider,
+                            // link: `/docs/providers/${provider.provider}`,
+                            collapsed: true,
+                            items: provider.documents
+                                .map((document) => ({
+                                text: document.title,
+                                link: `/docs/providers/${provider.provider}/${path.basename(document.path, ".md")}`,
+                            }))
+                                .sort((a, b) => a.text.localeCompare(b.text)),
+                        }))
+                            .sort((a, b) => a.text.localeCompare(b.text)),
+                    },
+                ],
+                "/examples/": [
+                    {
+                        text: "Examples",
+                        items: [{ text: "Foo", link: "/examples/foo" }],
+                    },
+                ],
+                "/": [
+                    {
+                        text: "Home",
+                        items: [
+                            { text: "Markdown Examples", link: "/markdown-examples" },
+                            { text: "Runtime API Examples", link: "/api-examples" },
+                        ],
+                    },
+                ],
+            },
+            socialLinks: [
+                {
+                    icon: "github",
+                    link: "https://github.com/sam-goodwin/alchemy",
+                },
+            ],
+        },
+    });
+}

package/lib/internal/providers.d.ts

@@ -0,0 +1,23 @@
+import { Document } from "alchemy/ai";
+import { Folder } from "alchemy/fs";
+export interface DocsProps {
+    /**
+     * The output directory for the docs.
+     */
+    outDir: string | Folder;
+    /**
+     * 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 declare function AlchemyProviderDocs({ outDir, filter, }: DocsProps): Promise<AlchemyProviderDocs>;

package/lib/internal/providers.js

@@ -0,0 +1,148 @@
+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";
+export async function AlchemyProviderDocs({ outDir, filter, }) {
+    outDir = typeof outDir === "string" ? outDir : outDir.path;
+    const providersDir = (await Folder(path.join(outDir, "providers"))).path;
+    const exclude = ["util", "test", "vitepress", "vite", "shadcn", "internal"];
+    // Get all folders in the alchemy/src directory
+    let providers = (await fs.readdir(path.resolve("..", "alchemy", "src"), {
+        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: "gpt-4o",
+                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(providersDir, providerName))).path;
+        const documents = await Promise.all(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`),
+            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
+
+                \`\`\`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,
+                  },
+                });
+                \`\`\``
+                : ""}
+              `,
+        })));
+        return {
+            dir: providerDocsDir,
+            provider: providerName,
+            documents,
+        };
+    }));
+}

package/lib/resource.js

@@ -15,7 +15,14 @@ export function Resource(type, ...args) {
         if (scope.resources.has(resourceID)) {
             // TODO(sam): do we want to throw?
             // it's kind of awesome that you can re-create a resource and call apply
-            // console.warn(`Resource ${id} already exists in the stack: ${stack.id}`);
+            const otherResource = scope.resources.get(resourceID);
+            if (otherResource?.Kind !== type) {
+                scope.fail();
+                throw new Error(`Resource ${resourceID} already exists in the stack and is of a different type: '${otherResource?.Kind}' !== '${type}'`);
+            }
+            // console.warn(
+            //   `Resource ${resourceID} already exists in the stack: ${scope.chain.join("/")}`,
+            // );
         }
         // get a sequence number (unique within the scope) for the resource
         const seq = scope.seq();

package/lib/scope.d.ts

@@ -1,5 +1,5 @@
 import type { PendingResource, ResourceID } from "./resource";
-import { type StateStore, type StateStoreType } from "./state";
+import type { StateStore, StateStoreType } from "./state";
 export type ScopeOptions = {
     appName?: string;
     stage: string;

package/lib/scope.js

@@ -1,6 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { destroy } from "./destroy";
-import { FileSystemStateStore, } from "./state";
+import { FileSystemStateStore } from "./fs/file-system-state-store";
 const scopeStorage = new AsyncLocalStorage();
 export class Scope {
     static get() {
@@ -32,7 +32,9 @@ export class Scope {
             throw new Error("Scope name is required when creating a child scope");
         }
         this.password = options.password;
-        this.state = new (options.stateStore ?? FileSystemStateStore)(this);
+        this.state = options.stateStore
+            ? options.stateStore(this)
+            : new FileSystemStateStore(this);
     }
     async delete(resourceID) {
         await this.state.delete(resourceID);