alchemy 0.2.5 → 0.3.0

package/lib/internal/docs.js

@@ -1,287 +0,0 @@
-import { type } from "arktype";
-import fs from "fs/promises";
-import path from "path";
-import { Data } from "../ai/data";
-import { Document } from "../ai/document";
-import { alchemy } from "../alchemy";
-import { Folder } from "../fs/folder";
-import { VitePressProject } from "../vitepress/vitepress";
-export async function AlchemyDocs({ docs: isDocsEnabled }) {
-    const root = (await Folder("alchemy-web")).path;
-    const docs = (await Folder(path.join(root, "docs"))).path;
-    const providersDir = (await Folder(path.join(docs, "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 (isDocsEnabled === false) {
-        return;
-    }
-    else if (typeof isDocsEnabled === "number") {
-        providers = providers.slice(0, isDocsEnabled);
-    }
-    const providerDocs = 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}`, {
-            schema: type({
-                groups: type({
-                    title: type("string").describe("The title of the group, should be the Resource Name exactly 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, e.g. "Bucket" or "Function", except with spaces, e.g. "Static Site" instead of "StaticSite". Maintain all other casing.
-        `,
-        });
-        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,
-        };
-    }));
-    await VitePressProject("docs", {
-        name: "alchemy-web",
-        title: "Alchemy",
-        description: "Alchemy is an TypeScript-native, embeddable IaC library",
-        overwrite: true,
-        delete: false,
-        tsconfig: {
-            extends: "../tsconfig.base.json",
-            references: ["../alchemy/tsconfig.json"],
-        },
-        devDependencies: {
-            alchemy: "workspace:*",
-        },
-        theme: {
-            light: "light-plus",
-            dark: "dark-plus",
-        },
-        home: {
-            layout: "home",
-            hero: {
-                name: "Alchemy",
-                text: "Materialize all the things! 🪄",
-                tagline: "TypeScript-native Infrastructure-as-Code (IaC)",
-                image: {
-                    src: "./public/alchemist.png",
-                    alt: "The Alchemist",
-                },
-                actions: [
-                    {
-                        text: "Get Started",
-                        link: "/docs",
-                        theme: "brand",
-                    },
-                ],
-            },
-            features: [
-                {
-                    title: "JS-native",
-                    details: "No second language, toolchains, dependencies, processes, services, etc. to lug around.",
-                },
-                {
-                    title: "Async",
-                    details: "Resources are just async functions - no complex abstraction to learn.",
-                },
-                {
-                    title: "ESM",
-                    details: "Built exclusively on ESM, with a slight preference for modern JS runtimes like Bun.",
-                },
-                {
-                    title: "Embeddable",
-                    details: "Runs in any JavaScript/TypeScript environment, including the browser!",
-                },
-                {
-                    title: "Extensible",
-                    details: "Implement your own resources with a simple function.",
-                },
-                {
-                    title: "AI-first",
-                    details: "Create, copy, fork, and modify resources using LLMs to fit your needs.",
-                },
-                {
-                    title: "No dependencies",
-                    details: "The alchemy core package has 0 required dependencies.",
-                },
-                {
-                    title: "No service",
-                    details: "State files are stored locally in your project for easy inspection and version control.",
-                },
-                {
-                    title: "No strong opinions",
-                    details: "Structure your codebase however you want, store state anywhere - we don't care!",
-                },
-            ],
-        },
-        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: providerDocs
-                            .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)),
-                    },
-                ],
-                "/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/shadcn/index.d.ts

@@ -1 +0,0 @@
-export * from "./component";

package/lib/shadcn/index.js

@@ -1 +0,0 @@
-export * from "./component";

package/lib/vite/index.d.ts

@@ -1 +0,0 @@
-export * from "./vite";

package/lib/vite/index.js

@@ -1 +0,0 @@
-export * from "./vite";

package/lib/vitepress/home-page.d.ts

@@ -1,133 +0,0 @@
-/**
- * Image that can be themed for light/dark mode
- */
-export interface ThemeableImage {
-    /**
-     * Image source URL
-     */
-    src?: string;
-    /**
-     * Image alt text
-     */
-    alt?: string;
-    /**
-     * Light theme image URL
-     */
-    light?: string;
-    /**
-     * Dark theme image URL
-     */
-    dark?: string;
-}
-/**
- * Hero action button configuration
- */
-export interface HeroAction {
-    /**
-     * Color theme of the button
-     * @default "brand"
-     */
-    theme?: "brand" | "alt";
-    /**
-     * Label of the button
-     */
-    text: string;
-    /**
-     * Destination link of the button
-     */
-    link: string;
-    /**
-     * Link target attribute
-     */
-    target?: string;
-    /**
-     * Link rel attribute
-     */
-    rel?: string;
-}
-/**
- * Hero section configuration
- */
-export interface Hero {
-    /**
-     * The string shown top of text. Comes with brand color
-     * and expected to be short, such as product name.
-     */
-    name?: string;
-    /**
-     * The main text for the hero section. This will be defined
-     * as h1 tag.
-     */
-    text: string;
-    /**
-     * Tagline displayed below text
-     */
-    tagline?: string;
-    /**
-     * The image displayed next to the text and tagline area
-     */
-    image?: string | ThemeableImage;
-    /**
-     * Action buttons to display in home hero section
-     */
-    actions?: HeroAction[];
-}
-/**
- * Feature item configuration
- */
-export interface Feature {
-    /**
-     * Show icon on each feature box
-     */
-    icon?: string | ThemeableImage;
-    /**
-     * Title of the feature
-     */
-    title: string;
-    /**
-     * Details of the feature
-     */
-    details: string;
-    /**
-     * Link when clicked on feature component
-     */
-    link?: string;
-    /**
-     * Link text to be shown inside feature component
-     */
-    linkText?: string;
-    /**
-     * Link rel attribute
-     */
-    rel?: string;
-    /**
-     * Link target attribute
-     */
-    target?: string;
-}
-/**
- * VitePress home page configuration
- */
-export interface HomePage {
-    /**
-     * Use home page layout
-     */
-    layout: "home";
-    /**
-     * Hero section configuration
-     */
-    hero?: Hero;
-    /**
-     * Features section configuration
-     */
-    features?: Feature[];
-    /**
-     * Whether to apply default markdown styles
-     * @default true
-     */
-    markdownStyles?: boolean;
-}
-/**
- * Parse YAML frontmatter to home page config
- */
-export declare function parseHomePage(content: string): HomePage;

package/lib/vitepress/home-page.js

@@ -1,11 +0,0 @@
-import yaml from "yaml";
-/**
- * Parse YAML frontmatter to home page config
- */
-export function parseHomePage(content) {
-    const match = content.match(/^---\n([\s\S]*?)\n---/);
-    if (!match) {
-        throw new Error("Invalid frontmatter format");
-    }
-    return yaml.parse(match[1]);
-}

package/src/cloudflare/state.ts

@@ -1,138 +0,0 @@
-import type { KVNamespace } from "@cloudflare/workers-types";
-import type { State, StateStore } from "../state";
-
-/**
- * Options for CloudflareStateStore
- */
-export interface CloudflareStateStoreOptions {
-  /**
-   * The prefix to use for keys in the KV namespace
-   * This allows multiple state stores to use the same KV namespace
-   */
-  prefix?: string;
-}
-
-/**
- * State store implementation using Cloudflare KV Namespace
- */
-export class CloudflareStateStore implements StateStore {
-  private namespace: KVNamespace;
-  private prefix: string;
-
-  /**
-   * Create a new CloudflareStateStore
-   *
-   * @param namespace The KV namespace to use for storing state
-   * @param options Options for the state store
-   */
-  constructor(
-    namespace: KVNamespace,
-    options: CloudflareStateStoreOptions = {},
-  ) {
-    this.namespace = namespace;
-    this.prefix = options.prefix || "alchemy-state:";
-  }
-
-  /**
-   * No initialization needed for KV namespaces as they are pre-provisioned
-   */
-  async init(): Promise<void> {
-    // KV namespaces are pre-provisioned in Cloudflare, so no initialization is needed
-  }
-
-  /**
-   * KV namespaces cannot be deleted programmatically
-   */
-  async deinit(): Promise<void> {
-    // KV namespaces can only be deleted through the Cloudflare dashboard or API
-    // We cannot delete the namespace itself here
-  }
-
-  /**
-   * List all resources in the state store
-   */
-  async list(): Promise<string[]> {
-    const list = await this.namespace.list({ prefix: this.prefix });
-    return list.keys.map((key) => key.name.slice(this.prefix.length));
-  }
-
-  /**
-   * Count the number of items in the state store
-   */
-  async count(): Promise<number> {
-    const list = await this.namespace.list({ prefix: this.prefix });
-    return list.keys.length;
-  }
-
-  /**
-   * Get a state by key
-   *
-   * @param key The key to look up
-   * @returns The state or undefined if not found
-   */
-  async get(key: string): Promise<State | undefined> {
-    const data = await this.namespace.get(this.getNamespacedKey(key), "json");
-    return data as State | undefined;
-  }
-
-  /**
-   * Get multiple states by their keys
-   *
-   * @param ids Array of keys to fetch
-   * @returns Record mapping keys to their states
-   */
-  async getBatch(ids: string[]): Promise<Record<string, State>> {
-    const result: Record<string, State> = {};
-
-    // KV doesn't have a native batch get operation, so we need to make multiple requests
-    // We could optimize this with Promise.all for parallel fetching
-    const promises = ids.map(async (id) => {
-      const state = await this.get(id);
-      if (state) {
-        result[id] = state;
-      }
-    });
-
-    await Promise.all(promises);
-    return result;
-  }
-
-  /**
-   * Get all states in the store
-   *
-   * @returns Record mapping all keys to their states
-   */
-  async all(): Promise<Record<string, State>> {
-    const keys = await this.list();
-    return this.getBatch(keys);
-  }
-
-  /**
-   * Set a state for a key
-   *
-   * @param key The key to set
-   * @param value The state to store
-   */
-  async set(key: string, value: State): Promise<void> {
-    await this.namespace.put(this.getNamespacedKey(key), JSON.stringify(value));
-  }
-
-  /**
-   * Delete a state by key
-   *
-   * @param key The key to delete
-   */
-  async delete(key: string): Promise<void> {
-    await this.namespace.delete(this.getNamespacedKey(key));
-  }
-
-  /**
-   * Get the namespaced key for storage
-   *
-   * @param key The original key
-   * @returns The key with prefix for use in the KV namespace
-   */
-  private getNamespacedKey(key: string): string {
-    return `${this.prefix}${key}`;
-  }
-}