alchemy 0.2.2 → 0.2.4

package/src/esbuild/bundle.ts

@@ -4,60 +4,110 @@ import fs from "node:fs";
 import path from "node:path";
 import type { Context } from "../context";
 import { Resource } from "../resource";
+
+/**
+ * Properties for creating or updating an esbuild bundle
+ */
 export interface BundleProps {
   /**
    * Entry point for the bundle
+   * Path to the source file to bundle (e.g., "src/handler.ts")
    */
   entryPoint: string;
+
   /**
    * Output directory for the bundle
+   * Directory where the bundled file will be written
    */
   outdir?: string;
+
   /**
    * Output filename for the bundle
+   * Full path to the output file, overrides outdir if specified
    */
   outfile?: string;
+
   /**
-   * Bundle format (iife, cjs, esm)
+   * Bundle format
+   * iife: Immediately Invoked Function Expression
+   * cjs: CommonJS
+   * esm: ECMAScript Modules
    */
   format?: "iife" | "cjs" | "esm";
+
   /**
-   * Target environment (e.g., 'node16', 'es2020')
+   * Target environment
+   * Examples: 'node16', 'node18', 'es2020'
    */
   target?: string | string[];
+
   /**
    * Whether to minify the output
    */
   minify?: boolean;
+
   /**
    * Whether to generate sourcemaps
+   * inline: Include sourcemap in bundle
+   * external: Generate separate .map file
+   * both: Generate both inline and external
    */
   sourcemap?: boolean | "inline" | "external" | "both";
+
   /**
    * External packages to exclude from bundle
+   * Array of package names to mark as external
    */
   external?: string[];
+
   /**
-   * Platform to target (browser, node, neutral)
+   * Platform to target
+   * browser: Browser environment
+   * node: Node.js environment
+   * neutral: Platform-agnostic
    */
   platform?: "browser" | "node" | "neutral";
+
   /**
    * Additional esbuild options
+   * Any other valid esbuild BuildOptions
    */
   options?: Partial<esbuild.BuildOptions>;
 }
 
+/**
+ * Output returned after bundle creation/update
+ */
 export interface Bundle extends Resource<"esbuild::Bundle"> {
   /**
    * Path to the bundled file
+   * Absolute or relative path to the generated bundle
    */
   path: string;
+
   /**
    * SHA-256 hash of the bundle contents
+   * Used for cache busting and content verification
    */
   hash: string;
 }
 
+/**
+ * esbuild Bundle Resource
+ *
+ * Creates and manages bundled JavaScript/TypeScript files using esbuild.
+ * Supports various output formats, sourcemaps, and platform targets.
+ *
+ * @example
+ * // Bundle a TypeScript file for Node.js
+ * const bundle = await Bundle("handler", {
+ *   entryPoint: "src/handler.ts",
+ *   outdir: ".alchemy/.out",
+ *   format: "esm",
+ *   platform: "node",
+ *   target: "node18"
+ * });
+ */
 export const Bundle = Resource(
   "esbuild::Bundle",
   {

package/src/fs/file-collection.ts

@@ -0,0 +1,24 @@
+/**
+ * Collection of files with their contents
+ */
+export type FileCollection = {
+  /**
+   * Type identifier for FileCollection
+   */
+  type: "fs::FileCollection";
+  /**
+   * Map of relative paths to file contents
+   */
+  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"
+  );
+}

package/src/fs/file-ref.ts

@@ -0,0 +1,22 @@
+/**
+ * Reference to a file in the filesystem
+ */
+export type FileRef = {
+  /**
+   * Type identifier for FileRef
+   */
+  kind: "fs::FileRef";
+  /**
+   * Path to the file
+   */
+  path: string;
+};
+
+export function isFileRef(value: unknown): value is FileRef {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "kind" in value &&
+    value.kind === "fs::FileRef"
+  );
+}

package/src/fs/file.ts

@@ -4,24 +4,125 @@ import type { Context } from "../context";
 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>;
+  }
+}
+
+alchemy.file = async (path: string) => ({
+  kind: "fs::FileRef",
+  path,
+});
+
+alchemy.files = async (
+  ...args: [paths: string[]] | [...paths: string[]]
+): Promise<FileCollection> => {
+  const paths: string[] =
+    typeof args[0] === "string" ? (args as string[]) : args[0];
+  return {
+    type: "fs::FileCollection",
+    files: Object.fromEntries(
+      await Promise.all(
+        paths.map(async (path) => [
+          path,
+          await fs.promises.readFile(path, "utf-8"),
+        ]),
+      ),
+    ),
+  };
+};
+
+/**
+ * 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 (
     this: Context<File>,
     id: string,
-    {
-      path: filePath,
-      content,
-    }: {
+    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();
@@ -29,11 +130,11 @@ export const File = Resource(
       await fs.promises.mkdir(path.dirname(filePath), {
         recursive: true,
       });
-      await fs.promises.writeFile(filePath, content);
+      await fs.promises.writeFile(filePath, props.content);
     }
     return this({
       path: filePath,
-      content,
+      content: props.content,
     });
   },
 );

package/src/fs/folder.ts

@@ -3,22 +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,
-    { path: dirPath }: { 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) {