alchemy 0.2.3 → 0.2.4

package/src/fs/file.ts

@@ -5,45 +5,56 @@ import { Resource } from "../resource";
 import { ignore } from "../util/ignore";
 
 import { alchemy } from "../alchemy";
+import type { FileCollection } from "./file-collection";
+import type { FileRef } from "./file-ref";
 
 declare module "../alchemy" {
   interface Alchemy {
+    /**
+     * Creates a reference to a file in the filesystem.
+     * Used in template string interpolation to include file contents,
+     * commonly for documentation generation.
+     *
+     * @param path Path to the file
+     * @returns Promise resolving to a FileRef
+     *
+     * @example
+     * // Include a file in documentation generation
+     * await Document("api-docs", {
+     *   prompt: await alchemy`
+     *     Generate docs using the contents of:
+     *     ${alchemy.file("./README.md")}
+     *   `
+     * });
+     */
     file(path: string): Promise<FileRef>;
+
+    /**
+     * Creates a collection of files with their contents.
+     * Used in template string interpolation to include multiple file contents,
+     * commonly for bulk documentation generation.
+     *
+     * @param paths Array of file paths to include in collection
+     * @returns Promise resolving to a FileCollection
+     *
+     * @example
+     * // Include multiple source files in documentation generation
+     * await Document("provider-docs", {
+     *   prompt: await alchemy`
+     *     Generate comprehensive docs for these files:
+     *     ${alchemy.files([
+     *       "src/types.ts",
+     *       "src/resource.ts",
+     *       "src/provider.ts"
+     *     ])}
+     *   `
+     * });
+     */
     files(paths: string[]): Promise<FileCollection>;
     files(path: string, ...paths: string[]): Promise<FileCollection>;
   }
 }
 
-export type FileRef = {
-  kind: "fs::FileRef";
-  path: string;
-};
-
-export function isFileRef(value: unknown): value is FileRef {
-  return (
-    typeof value === "object" &&
-    value !== null &&
-    "kind" in value &&
-    value.kind === "fs::FileRef"
-  );
-}
-
-export type FileCollection = {
-  type: "fs::FileCollection";
-  files: {
-    [relativePath: string]: string;
-  };
-};
-
-export function isFileCollection(value: unknown): value is FileCollection {
-  return (
-    typeof value === "object" &&
-    value !== null &&
-    "type" in value &&
-    value.type === "fs::FileCollection"
-  );
-}
-
 alchemy.file = async (path: string) => ({
   kind: "fs::FileRef",
   path,
@@ -67,11 +78,40 @@ alchemy.files = async (
   };
 };
 
+/**
+ * Base file resource type
+ */
 export interface File extends Resource<"fs::File"> {
+  /**
+   * Path to the file
+   */
   path: string;
+  /**
+   * Content of the file
+   */
   content: string;
 }
 
+/**
+ * File Resource
+ *
+ * Creates and manages files in the filesystem with automatic directory creation
+ * and proper cleanup on deletion.
+ *
+ * @example
+ * // Create a simple text file
+ * const config = await File("config.txt", {
+ *   path: "config.txt",
+ *   content: "some configuration data"
+ * });
+ *
+ * @example
+ * // Create a file in a nested directory
+ * const log = await File("logs/app.log", {
+ *   path: "logs/app.log",
+ *   content: "application log entry"
+ * });
+ */
 export const File = Resource(
   "fs::File",
   async function (
@@ -98,50 +138,3 @@ export const File = Resource(
     });
   },
 );
-
-export type JsonFile = File;
-
-export function JsonFile(id: string, content: any): Promise<JsonFile> {
-  return File(id, {
-    path: id,
-    content: JSON.stringify(content, null, 2),
-  });
-}
-
-export type TextFile = File;
-
-export function TextFile(id: string, content: string): Promise<TextFile> {
-  return File(id, {
-    path: id,
-    content,
-  });
-}
-
-export type YamlFile = File;
-
-export async function YamlFile(id: string, content: any): Promise<YamlFile> {
-  const yaml = await import("yaml");
-  return File(id, {
-    path: id,
-    content: yaml.stringify(content),
-  });
-}
-
-export type TypeScriptFile = File;
-
-export async function TypeScriptFile(
-  id: string,
-  content: string,
-): Promise<TypeScriptFile> {
-  const prettier = await import("prettier");
-  return File(id, {
-    path: id,
-    content: await prettier.format(content, {
-      parser: "typescript",
-      editor: {
-        tabWidth: 2,
-        indentWidth: 2,
-      },
-    }),
-  });
-}

package/src/fs/folder.ts

@@ -3,23 +3,62 @@ import type { Context } from "../context";
 import { Resource } from "../resource";
 import { ignore } from "../util/ignore";
 
+export interface FolderProps {
+  /**
+   * The path of the folder
+   */
+  path?: string;
+  /**
+   * Whether to delete the folder during the delete phase
+   * @default true
+   */
+  delete?: boolean;
+}
+
+/**
+ * Base folder resource type
+ */
 export interface Folder extends Resource<"fs::Folder"> {
   path: string;
 }
 
+/**
+ * Folder Resource
+ *
+ * Creates and manages directories in the filesystem with automatic parent
+ * directory creation and cleanup on deletion.
+ *
+ * @example
+ * // Create a directory using id as path
+ * const dir = await Folder("uploads");
+ *
+ * @example
+ * // Create a directory with explicit path
+ * const dir = await Folder("uploads", {
+ *   path: "uploads"
+ * });
+ *
+ * @example
+ * // Create a nested directory structure
+ * const logs = await Folder("var/log/app", {
+ *   path: "var/log/app"
+ * });
+ */
 export const Folder = Resource(
   "fs::Folder",
   async function (
     this: Context<Folder>,
     id: string,
-    props?: { path: string },
+    props?: FolderProps,
   ): Promise<Folder> {
     const dirPath = props?.path ?? id;
     if (this.phase === "delete") {
-      // we just do a best effort attempt
-      await ignore(["ENOENT", "ENOTEMPTY"], async () =>
-        fs.promises.rmdir(dirPath),
-      );
+      if (props?.delete !== false) {
+        // we just do a best effort attempt
+        await ignore(["ENOENT", "ENOTEMPTY"], async () =>
+          fs.promises.rmdir(dirPath),
+        );
+      }
       return this.destroy();
     } else {
       await ignore("EEXIST", async () =>

package/src/fs/index.ts

@@ -1,2 +1,8 @@
 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";

package/src/fs/json-file.ts

@@ -0,0 +1,23 @@
+import { File } from "./file";
+
+/**
+ * Creates a JSON file with formatted content
+ *
+ * @example
+ * // Create a JSON configuration file
+ * const config = await JsonFile("config.json", {
+ *   api: {
+ *     endpoint: "https://api.example.com",
+ *     version: "v1"
+ *   },
+ *   features: ["auth", "logging"]
+ * });
+ */
+export type JsonFile = File;
+
+export function JsonFile(id: string, content: any): Promise<JsonFile> {
+  return File(id, {
+    path: id,
+    content: JSON.stringify(content, null, 2),
+  });
+}

package/src/fs/text-file.ts

@@ -0,0 +1,19 @@
+import { File } from "./file";
+
+/**
+ * Creates a plain text file
+ *
+ * @example
+ * // Create a text file with content
+ * const readme = await TextFile("README.md",
+ *   "# Project Name\n\nProject description goes here."
+ * );
+ */
+export type TextFile = File;
+
+export function TextFile(id: string, content: string): Promise<TextFile> {
+  return File(id, {
+    path: id,
+    content,
+  });
+}

package/src/fs/typescript-file.ts

@@ -0,0 +1,36 @@
+import { File } from "./file";
+
+/**
+ * Creates a TypeScript file with formatted content using prettier
+ *
+ * @example
+ * // Create a TypeScript file
+ * const component = await TypeScriptFile("Component.ts", `
+ *   interface Props {
+ *     name: string;
+ *     age: number;
+ *   }
+ *
+ *   export function Component({ name, age }: Props) {
+ *     return <div>Hello {name}, you are {age} years old</div>;
+ *   }
+ * `);
+ */
+export type TypeScriptFile = File;
+
+export async function TypeScriptFile(
+  id: string,
+  content: string,
+): Promise<TypeScriptFile> {
+  const prettier = await import("prettier");
+  return File(id, {
+    path: id,
+    content: await prettier.format(content, {
+      parser: "typescript",
+      editor: {
+        tabWidth: 2,
+        indentWidth: 2,
+      },
+    }),
+  });
+}

package/src/fs/yaml-file.ts

@@ -0,0 +1,26 @@
+import { File } from "./file";
+/**
+ * Creates a YAML file with formatted content
+ *
+ * @example
+ * // Create a YAML configuration file
+ * const config = await YamlFile("config.yaml", {
+ *   server:
+ *     host: "localhost"
+ *     port: 3000
+ *   database:
+ *     url: "postgresql://localhost:5432/db"
+ *     pool:
+ *       min: 1
+ *       max: 10
+ * });
+ */
+export type YamlFile = File;
+
+export async function YamlFile(id: string, content: any): Promise<YamlFile> {
+  const yaml = await import("yaml");
+  return File(id, {
+    path: id,
+    content: yaml.stringify(content),
+  });
+}

package/src/github/secret.ts

@@ -29,8 +29,11 @@ export interface GitHubSecretProps {
 
   /**
    * Optional GitHub API token (overrides environment variable)
+   * If not provided, will use GITHUB_TOKEN environment variable
+   * Token must have 'repo' scope for private repositories
+   * or 'public_repo' scope for public repositories
    */
-  token?: string;
+  token?: Secret;
 }
 
 /**
@@ -52,6 +55,64 @@ export interface GitHubSecretOutput
 
 /**
  * Resource for managing GitHub repository secrets
+ *
+ * Authentication is handled in the following order:
+ * 1. `token` parameter in the resource props (if provided)
+ * 2. `GITHUB_TOKEN` environment variable
+ *
+ * The token must have the following permissions:
+ * - 'repo' scope for private repositories
+ * - 'public_repo' scope for public repositories
+ *
+ * @example
+ * // Create a secret using GITHUB_TOKEN environment variable:
+ * const secret = await GitHubSecret("my-secret", {
+ *   owner: "my-github-username",
+ *   repository: "my-repo",
+ *   name: "API_KEY",
+ *   value: alchemy.secret("my-secret-value")
+ * });
+ *
+ * @example
+ * // Create a secret with a custom GitHub token:
+ * const secret = await GitHubSecret("my-secret", {
+ *   owner: "my-github-username",
+ *   repository: "my-repo",
+ *   name: "API_KEY",
+ *   value: alchemy.secret("my-secret-value"),
+ *   token: alchemy.secret(process.env.CUSTOM_GITHUB_TOKEN)
+ * });
+ *
+ * @example
+ * // Create multiple secrets with environment variables:
+ * const secrets = await Promise.all([
+ *   GitHubSecret("aws-secret", {
+ *     owner: "my-github-username",
+ *     repository: "cloud-app",
+ *     name: "AWS_ROLE_ARN",
+ *     value: alchemy.secret(process.env.AWS_ROLE_ARN)
+ *   }),
+ *   GitHubSecret("cf-secret", {
+ *     owner: "my-github-username",
+ *     repository: "cloud-app",
+ *     name: "CLOUDFLARE_API_KEY",
+ *     value: alchemy.secret(process.env.CLOUDFLARE_API_KEY)
+ *   })
+ * ]);
+ *
+ * @example
+ * // Create a secret in a secure scope with a password:
+ * await alchemy.run("secure-scope", {
+ *   password: process.env.SECRET_PASSPHRASE
+ * }, async () => {
+ *   const secret = await GitHubSecret("deploy-secret", {
+ *     owner: "my-github-username",
+ *     repository: "my-app",
+ *     name: "DEPLOY_TOKEN",
+ *     value: alchemy.secret(process.env.DEPLOY_TOKEN),
+ *     token: alchemy.secret(process.env.GITHUB_TOKEN)
+ *   });
+ * });
  */
 export const GitHubSecret = Resource(
   "github::Secret",
@@ -62,7 +123,9 @@ export const GitHubSecret = Resource(
   ): Promise<GitHubSecretOutput> {
     // Create authenticated Octokit client - will automatically handle token resolution
     /// TODO: use fetch
-    const octokit = await createGitHubClient({ token: props.token });
+    const octokit = await createGitHubClient({
+      token: props.token?.unencrypted,
+    });
 
     // Verify authentication and permissions
     if (!this.quiet) {