alchemy 0.2.5 → 0.3.0

package/src/dns/record.ts

@@ -0,0 +1,121 @@
+/**
+ * DNS record types supported across different providers
+ */
+export type DnsRecordType =
+  | "A"
+  | "AAAA"
+  | "MX"
+  | "TXT"
+  | "NS"
+  | "CNAME"
+  | "SOA"
+  | "SRV"
+  | "PTR";
+
+/**
+ * Default DNS record types to fetch
+ */
+export const DEFAULT_RECORD_TYPES: readonly DnsRecordType[] = [
+  "A",
+  "AAAA",
+  "MX",
+  "TXT",
+  "NS",
+  "CNAME",
+  "SOA",
+  "SRV",
+] as const;
+
+/**
+ * Base DNS record interface with common properties
+ */
+export interface DnsRecordBase {
+  /**
+   * DNS record name (e.g., "example.com", "subdomain.example.com")
+   */
+  name: string;
+
+  /**
+   * Record type (A, AAAA, CNAME, etc.)
+   */
+  type: DnsRecordType;
+}
+
+/**
+ * DNS record response structure from DNS-over-HTTPS APIs
+ */
+export interface DohDnsRecord extends DnsRecordBase {
+  /**
+   * Time To Live in seconds
+   */
+  TTL: number;
+
+  /**
+   * Record data/content (varies by record type)
+   */
+  data: string;
+}
+
+/**
+ * Comprehensive DNS record structure for creating/managing records
+ */
+export interface DnsRecord extends DnsRecordBase {
+  /**
+   * DNS record content (e.g., IP address, hostname)
+   */
+  content: string;
+
+  /**
+   * Time To Live (TTL) in seconds
+   * Setting to 1 means 'automatic'
+   * Value must be between 60 and 86400, with minimum reduced to 30 for Enterprise zones
+   * @default 1
+   */
+  ttl?: number;
+
+  /**
+   * Whether the record is receiving proxied traffic through Cloudflare
+   * @default false
+   */
+  proxied?: boolean;
+
+  /**
+   * Comments or notes about the record
+   */
+  comment?: string;
+
+  /**
+   * Record tags
+   */
+  tags?: string[];
+
+  /**
+   * Priority value for MX/SRV records
+   */
+  priority?: number;
+}
+
+/**
+ * DNS record with provider-specific ID and metadata
+ */
+export interface DnsRecordWithMetadata extends DnsRecord {
+  /**
+   * Record ID
+   */
+  id: string;
+
+  /**
+   * Zone or domain ID the record belongs to
+   */
+  zoneId: string;
+
+  /**
+   * Time at which the record was created
+   */
+  createdAt: number;
+
+  /**
+   * Time at which the record was last modified
+   */
+  modifiedAt?: number;
+}

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

@@ -0,0 +1,109 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { Scope } from "../scope";
+import type { State, StateStore } from "../state";
+import { ignore } from "../util/ignore";
+import { deserialize, serialize } from "../util/serde";
+
+const stateRootDir = path.join(process.cwd(), ".alchemy");
+
+export class FileSystemStateStore implements StateStore {
+  public readonly dir: string;
+  constructor(public readonly scope: Scope) {
+    this.dir = path.join(stateRootDir, ...scope.chain);
+  }
+
+  async init(): Promise<void> {
+    await fs.mkdir(stateRootDir, { recursive: true });
+    await fs.mkdir(this.dir, { recursive: true });
+  }
+
+  async deinit(): Promise<void> {
+    await ignore("ENOENT", () => fs.rmdir(this.dir));
+  }
+
+  async count(): Promise<number> {
+    return Object.keys(await this.list()).length;
+  }
+
+  async list(): Promise<string[]> {
+    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: any) {
+      if (error.code === "ENOENT") {
+        return [];
+      }
+      throw error;
+    }
+  }
+
+  async get(key: string): Promise<State | undefined> {
+    try {
+      const content = await fs.readFile(await this.getPath(key), "utf8");
+      const state = (await deserialize(
+        this.scope,
+        JSON.parse(content),
+      )) as State;
+      if (state.output === undefined) {
+        state.output = {} as any;
+      }
+      state.output.Scope = this.scope;
+      return state;
+    } catch (error: any) {
+      if (error.code === "ENOENT") {
+        return undefined;
+      }
+      throw error;
+    }
+  }
+
+  async set(key: string, value: State): Promise<void> {
+    return fs.writeFile(
+      await this.getPath(key),
+      JSON.stringify(await serialize(this.scope, value), null, 2),
+    );
+  }
+
+  async delete(key: string): Promise<void> {
+    return fs.unlink(await this.getPath(key));
+  }
+
+  async all(): Promise<Record<string, State>> {
+    return this.getBatch(await this.list());
+  }
+
+  async getBatch(ids: string[]): Promise<Record<string, State>> {
+    return Object.fromEntries(
+      (
+        await Promise.all(
+          Array.from(ids).flatMap(async (id) => {
+            const s = await this.get(id);
+            if (s === undefined) {
+              return [] as const;
+            }
+            return [[id, s]] as const;
+          }),
+        )
+      ).flat(),
+    );
+  }
+
+  private async getPath(key: string): Promise<string> {
+    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/src/fs/folder.ts

@@ -13,6 +13,18 @@ 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;
 }
 
 /**
@@ -56,13 +68,13 @@ export const Folder = Resource(
       if (props?.delete !== false) {
         // we just do a best effort attempt
         await ignore(["ENOENT", "ENOTEMPTY"], async () =>
-          fs.promises.rmdir(dirPath),
+          fs.promises.rmdir(dirPath, { recursive: props?.clean ?? false }),
         );
       }
       return this.destroy();
     } else {
       await ignore("EEXIST", async () =>
-        fs.promises.mkdir(dirPath, { recursive: true }),
+        fs.promises.mkdir(dirPath, { recursive: props?.recursive ?? true }),
       );
     }
     return this({

package/src/fs/index.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/src/fs/{json-file.ts → static-json-file.ts}

@@ -13,11 +13,21 @@ import { File } from "./file";
  *   features: ["auth", "logging"]
  * });
  */
-export type JsonFile = File;
+export type StaticJsonFile = File;
 
-export function JsonFile(id: string, content: any): Promise<JsonFile> {
+export async function StaticJsonFile(
+  id: string,
+  content: any,
+): Promise<StaticJsonFile> {
+  const prettier = await import("prettier");
   return File(id, {
     path: id,
-    content: JSON.stringify(content, null, 2),
+    content: await prettier.format(JSON.stringify(content), {
+      parser: "json",
+      editor: {
+        tabWidth: 2,
+        indentWidth: 2,
+      },
+    }),
   });
 }

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

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

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

@@ -16,12 +16,12 @@ import { File } from "./file";
  *   }
  * `);
  */
-export type TypeScriptFile = File;
+export type StaticTypeScriptFile = File;
 
-export async function TypeScriptFile(
+export async function StaticTypeScriptFile(
   id: string,
   content: string,
-): Promise<TypeScriptFile> {
+): Promise<StaticTypeScriptFile> {
   const prettier = await import("prettier");
   return File(id, {
     path: id,

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

@@ -15,9 +15,12 @@ import { File } from "./file";
  *       max: 10
  * });
  */
-export type YamlFile = File;
+export type StaticYamlFile = File;
 
-export async function YamlFile(id: string, content: any): Promise<YamlFile> {
+export async function StaticYamlFile(
+  id: string,
+  content: any,
+): Promise<StaticYamlFile> {
   const yaml = await import("yaml");
   return File(id, {
     path: id,

package/src/internal/getting-started.ts

@@ -0,0 +1,107 @@
+import alchemy from "alchemy";
+import { Document } from "alchemy/ai";
+import type { Folder } from "alchemy/fs";
+import path from "path";
+
+export interface GettingStartedProps {
+  /**
+   * The output directory for the getting started document.
+   */
+  outDir: string | Folder;
+}
+
+export type GettingStarted = Document;
+
+export async function GettingStarted({
+  outDir,
+}: GettingStartedProps): Promise<Document> {
+  outDir = typeof outDir === "string" ? outDir : outDir.path;
+  return Document(`docs/getting-started`, {
+    title: "Getting Started with Alchemy",
+    path: path.join(outDir, "index.md"),
+    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/src/internal/project.ts

@@ -0,0 +1,119 @@
+import path from "path";
+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 function AlchemyProject({
+  hero,
+  docs,
+}: AlchemyProjectProps): Promise<AlchemyProject> {
+  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",
+        },
+      ],
+    },
+  });
+}