alchemy 0.2.5 → 0.3.1

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/copy-file.ts

@@ -0,0 +1,115 @@
+import fs from "node:fs";
+import type { Context } from "../context";
+import { Resource } from "../resource";
+import { ignore } from "../util/ignore";
+
+/**
+ * Properties for creating a CopyFile resource
+ */
+export interface CopyFileProps {
+  /**
+   * Source path of the file to copy
+   */
+  src: string;
+
+  /**
+   * Destination path where the file should be copied to
+   */
+  dest: string;
+
+  /**
+   * Whether to overwrite the destination file if it already exists
+   * @default true
+   */
+  overwrite?: boolean;
+}
+
+/**
+ * Output returned after CopyFile creation/update
+ */
+export interface CopyFile extends Resource<"fs::CopyFile">, CopyFileProps {
+  /**
+   * Time at which the object was created
+   */
+  createdAt: number;
+
+  /**
+   * Whether the file was successfully copied
+   */
+  copied: boolean;
+}
+
+/**
+ * CopyFile Resource
+ *
+ * Copies a file from a source location to a destination location.
+ *
+ * @example
+ * // Copy a file to a new location
+ * const copiedFile = await CopyFile("config-copy", {
+ *   src: "config.json",
+ *   dest: "backup/config.json"
+ * });
+ *
+ * @example
+ * // Copy a file without overwriting if destination exists
+ * const safeCopy = await CopyFile("safe-copy", {
+ *   src: "data.json",
+ *   dest: "backup/data.json",
+ *   overwrite: false
+ * });
+ */
+export const CopyFile = Resource(
+  "fs::CopyFile",
+  async function (
+    this: Context<CopyFile>,
+    id: string,
+    props: CopyFileProps
+  ): Promise<CopyFile> {
+    const { src, dest, overwrite = true } = props;
+
+    if (this.phase === "delete") {
+      // When deleting, remove the destination file
+      await ignore("ENOENT", async () => fs.promises.unlink(dest));
+      return this.destroy();
+    } else {
+      try {
+        // Check if source file exists
+        await fs.promises.access(src, fs.constants.F_OK);
+
+        // If this is an update and the destination has changed, delete the old file
+        if (
+          this.phase === "update" &&
+          this.output?.dest &&
+          this.output.dest !== dest
+        ) {
+          await ignore("ENOENT", async () =>
+            fs.promises.unlink(this.output.dest)
+          );
+        }
+
+        // Check if destination file exists
+        const destinationExists = await fs.promises
+          .access(dest, fs.constants.F_OK)
+          .then(() => true)
+          .catch(() => false);
+
+        // Copy file if destination doesn't exist or overwrite is true
+        if (!destinationExists || overwrite) {
+          await fs.promises.copyFile(src, dest);
+        }
+
+        return this({
+          src,
+          dest,
+          overwrite,
+          copied: true,
+          createdAt: Date.now(),
+        });
+      } catch (error) {
+        console.error(`Error copying file from ${src} to ${dest}:`, error);
+        throw error;
+      }
+    }
+  }
+);

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/file.ts

@@ -72,8 +72,8 @@ alchemy.files = async (
         paths.map(async (path) => [
           path,
           await fs.promises.readFile(path, "utf-8"),
-        ]),
-      ),
+        ])
+      )
     ),
   };
 };
@@ -111,6 +111,19 @@ export interface File extends Resource<"fs::File"> {
  *   path: "logs/app.log",
  *   content: "application log entry"
  * });
+ *
+ * @example
+ * // Update file content and path
+ * let file = await File("config.json", {
+ *   path: "config.json",
+ *   content: '{ "version": "1.0.0" }'
+ * });
+ *
+ * // Later, update the path and content (old file will be removed)
+ * file = await File("config.json", {
+ *   path: "config/config.json",
+ *   content: '{ "version": "1.0.1" }'
+ * });
  */
 export const File = Resource(
   "fs::File",
@@ -120,21 +133,34 @@ export const File = Resource(
     props: {
       path: string;
       content: string;
-    },
+    }
   ): Promise<File> {
     const filePath = props?.path ?? id;
+
     if (this.phase === "delete") {
       await ignore("ENOENT", async () => fs.promises.unlink(filePath));
       return this.destroy();
-    } else {
-      await fs.promises.mkdir(path.dirname(filePath), {
-        recursive: true,
-      });
-      await fs.promises.writeFile(filePath, props.content);
+    } else if (
+      this.phase === "update" &&
+      this.output &&
+      this.output.path !== filePath
+    ) {
+      // If path has changed, delete the old file
+      console.log(
+        `File: Path changed from ${this.output.path} to ${filePath}, removing old file`
+      );
+      await ignore("ENOENT", async () => fs.promises.unlink(this.output.path));
     }
+
+    // Create directory and write file
+    await fs.promises.mkdir(path.dirname(filePath), {
+      recursive: true,
+    });
+    await fs.promises.writeFile(filePath, props.content);
+
     return this({
       path: filePath,
       content: props.content,
     });
-  },
+  }
 );

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

@@ -1,8 +1,14 @@
+export * from "./copy-file";
 export * from "./file";
 export * from "./file-collection";
 export * from "./file-ref";
+export * from "./file-system-state-store";
 export * from "./folder";
-export * from "./json-file";
-export * from "./text-file";
-export * from "./typescript-file";
-export * from "./yaml-file";
+export * from "./static-astro-file";
+export * from "./static-css-file";
+export * from "./static-html-file";
+export * from "./static-json-file";
+export * from "./static-text-file";
+export * from "./static-typescript-file";
+export * from "./static-vue-file";
+export * from "./static-yaml-file";

package/src/fs/static-astro-file.ts

@@ -0,0 +1,45 @@
+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 function StaticAstroFile(
+  id: string,
+  ...args: [content: string] | [path: string, content: string]
+): Promise<StaticAstroFile> {
+  const [path, content] = args.length === 1 ? [id, args[0]] : args;
+  return File(id, {
+    path,
+    content,
+  });
+}

package/src/fs/static-css-file.ts

@@ -0,0 +1,35 @@
+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 function StaticCSSFile(
+  id: string,
+  ...args: [content: string] | [path: string, content: string]
+): Promise<StaticCSSFile> {
+  const [path, content] = args.length === 1 ? [id, args[0]] : args;
+  return File(id, {
+    path,
+    content,
+  });
+}

package/src/fs/static-html-file.ts

@@ -0,0 +1,42 @@
+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 function StaticHTMLFile(
+  id: string,
+  ...args: [content: string] | [path: string, content: string]
+): Promise<StaticHTMLFile> {
+  const [path, content] = args.length === 1 ? [id, args[0]] : args;
+  return File(id, {
+    path,
+    content,
+  });
+}

package/src/fs/static-json-file.ts

@@ -0,0 +1,34 @@
+import { File } from "./file";
+
+/**
+ * Creates a JSON file with formatted content
+ *
+ * @example
+ * // Create a JSON configuration file
+ * const config = await StaticJsonFile("config.json", {
+ *   api: {
+ *     endpoint: "https://api.example.com",
+ *     version: "v1"
+ *   },
+ *   features: ["auth", "logging"]
+ * });
+ */
+export type StaticJsonFile = File;
+
+export async function StaticJsonFile(
+  id: string,
+  ...args: [content: any] | [path: string, content: any]
+): Promise<StaticJsonFile> {
+  const [path, content] = args.length === 1 ? [id, args[0]] : args;
+  const prettier = await import("prettier");
+  return File(id, {
+    path,
+    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,11 +9,17 @@ 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,
+  ...args: 
+  | [content: string]
+  | [path: string, content: string]
+): Promise<StaticTextFile> {
+  const [path, content] = args.length === 1 ? [id, args[0]] : args;
   return File(id, {
-    path: id,
+    path,
     content,
   });
 }

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

@@ -5,7 +5,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,15 +16,16 @@ 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> {
+  ...args: [content: string] | [path: string, content: string]
+): Promise<StaticTypeScriptFile> {
+  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: {