alchemy 0.2.3 → 0.2.5

package/lib/esbuild/bundle.d.ts

@@ -1,25 +1,35 @@
 import * as esbuild from "esbuild";
 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[];
     /**
@@ -28,32 +38,61 @@ export interface BundleProps {
     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;
 }
-export declare const Bundle: ((this: Context<Bundle>, id: string, props: BundleProps) => Promise<Bundle>) | (((this: any, id: string, props?: BundleProps | undefined) => never) & (new (_: never) => never));
+/**
+ * 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 declare const Bundle: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<Bundle>, id: string, props: BundleProps) => Promise<Bundle>);
 export declare function bundle(props: BundleProps): Promise<esbuild.BuildResult<{
     bundle: boolean;
     splitting?: boolean;

package/lib/esbuild/bundle.js

@@ -3,6 +3,22 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { Resource } from "../resource";
+/**
+ * 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", {
     alwaysUpdate: true,
 }, async function (id, props) {

package/lib/fs/file-collection.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 declare function isFileCollection(value: unknown): value is FileCollection;

package/lib/fs/file-collection.js

@@ -0,0 +1,6 @@
+export function isFileCollection(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "type" in value &&
+        value.type === "fs::FileCollection");
+}

package/lib/fs/file-ref.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Reference to a file in the filesystem
+ */
+export type FileRef = {
+    /**
+     * Type identifier for FileRef
+     */
+    kind: "fs::FileRef";
+    /**
+     * Path to the file
+     */
+    path: string;
+};
+export declare function isFileRef(value: unknown): value is FileRef;

package/lib/fs/file-ref.js

@@ -0,0 +1,6 @@
+export function isFileRef(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "kind" in value &&
+        value.kind === "fs::FileRef");
+}

package/lib/fs/file.d.ts

@@ -1,40 +1,86 @@
 import type { Context } from "../context";
 import { Resource } from "../resource";
+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 declare function isFileRef(value: unknown): value is FileRef;
-export type FileCollection = {
-    type: "fs::FileCollection";
-    files: {
-        [relativePath: string]: string;
-    };
-};
-export declare function isFileCollection(value: unknown): value is FileCollection;
+/**
+ * Base file resource type
+ */
 export interface File extends Resource<"fs::File"> {
+    /**
+     * Path to the file
+     */
     path: string;
+    /**
+     * Content of the file
+     */
     content: string;
 }
-export declare const File: ((this: Context<File>, id: string, props: {
-    path: string;
-    content: string;
-}) => Promise<File>) | (((this: any, id: string, props?: {
+/**
+ * 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 declare const File: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<File>, id: string, props: {
     path: string;
     content: string;
-} | undefined) => never) & (new (_: never) => never));
-export type JsonFile = File;
-export declare function JsonFile(id: string, content: any): Promise<JsonFile>;
-export type TextFile = File;
-export declare function TextFile(id: string, content: string): Promise<TextFile>;
-export type YamlFile = File;
-export declare function YamlFile(id: string, content: any): Promise<YamlFile>;
-export type TypeScriptFile = File;
-export declare function TypeScriptFile(id: string, content: string): Promise<TypeScriptFile>;
+}) => Promise<File>);

package/lib/fs/file.js

@@ -3,18 +3,6 @@ import path from "node:path";
 import { Resource } from "../resource";
 import { ignore } from "../util/ignore";
 import { alchemy } from "../alchemy";
-export function isFileRef(value) {
-    return (typeof value === "object" &&
-        value !== null &&
-        "kind" in value &&
-        value.kind === "fs::FileRef");
-}
-export function isFileCollection(value) {
-    return (typeof value === "object" &&
-        value !== null &&
-        "type" in value &&
-        value.type === "fs::FileCollection");
-}
 alchemy.file = async (path) => ({
     kind: "fs::FileRef",
     path,
@@ -29,6 +17,26 @@ alchemy.files = async (...args) => {
         ]))),
     };
 };
+/**
+ * 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 (id, props) {
     const filePath = props?.path ?? id;
     if (this.phase === "delete") {
@@ -46,35 +54,3 @@ export const File = Resource("fs::File", async function (id, props) {
         content: props.content,
     });
 });
-export function JsonFile(id, content) {
-    return File(id, {
-        path: id,
-        content: JSON.stringify(content, null, 2),
-    });
-}
-export function TextFile(id, content) {
-    return File(id, {
-        path: id,
-        content,
-    });
-}
-export async function YamlFile(id, content) {
-    const yaml = await import("yaml");
-    return File(id, {
-        path: id,
-        content: yaml.stringify(content),
-    });
-}
-export async function TypeScriptFile(id, content) {
-    const prettier = await import("prettier");
-    return File(id, {
-        path: id,
-        content: await prettier.format(content, {
-            parser: "typescript",
-            editor: {
-                tabWidth: 2,
-                indentWidth: 2,
-            },
-        }),
-    });
-}

package/lib/fs/folder.d.ts

@@ -1,10 +1,42 @@
 import type { Context } from "../context";
 import { Resource } from "../resource";
+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;
 }
-export declare const Folder: ((this: Context<Folder>, id: string, props?: {
-    path: string;
-}) => Promise<Folder>) | (((this: any, id: string, props?: {
-    path: string;
-} | undefined) => never) & (new (_: never) => never));
+/**
+ * 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 declare const Folder: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<Folder>, id: string, props?: FolderProps) => Promise<Folder>);

package/lib/fs/folder.js

@@ -1,11 +1,35 @@
 import fs from "node:fs";
 import { Resource } from "../resource";
 import { ignore } from "../util/ignore";
+/**
+ * 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 (id, props) {
     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 {

package/lib/fs/index.d.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/lib/fs/index.js

@@ -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/lib/fs/json-file.d.ts

@@ -0,0 +1,16 @@
+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 declare function JsonFile(id: string, content: any): Promise<JsonFile>;

package/lib/fs/json-file.js

@@ -0,0 +1,7 @@
+import { File } from "./file";
+export function JsonFile(id, content) {
+    return File(id, {
+        path: id,
+        content: JSON.stringify(content, null, 2),
+    });
+}

package/lib/fs/text-file.d.ts

@@ -0,0 +1,12 @@
+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 declare function TextFile(id: string, content: string): Promise<TextFile>;

package/lib/fs/text-file.js

@@ -0,0 +1,7 @@
+import { File } from "./file";
+export function TextFile(id, content) {
+    return File(id, {
+        path: id,
+        content,
+    });
+}

package/lib/fs/typescript-file.d.ts

@@ -0,0 +1,19 @@
+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 declare function TypeScriptFile(id: string, content: string): Promise<TypeScriptFile>;

package/lib/fs/typescript-file.js

@@ -0,0 +1,14 @@
+import { File } from "./file";
+export async function TypeScriptFile(id, content) {
+    const prettier = await import("prettier");
+    return File(id, {
+        path: id,
+        content: await prettier.format(content, {
+            parser: "typescript",
+            editor: {
+                tabWidth: 2,
+                indentWidth: 2,
+            },
+        }),
+    });
+}

package/lib/fs/yaml-file.d.ts

@@ -0,0 +1,19 @@
+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 declare function YamlFile(id: string, content: any): Promise<YamlFile>;

package/lib/fs/yaml-file.js

@@ -0,0 +1,8 @@
+import { File } from "./file";
+export async function YamlFile(id, content) {
+    const yaml = await import("yaml");
+    return File(id, {
+        path: id,
+        content: yaml.stringify(content),
+    });
+}

package/lib/github/secret.d.ts

@@ -23,8 +23,11 @@ export interface GitHubSecretProps {
     value: Secret;
     /**
      * 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;
 }
 /**
  * Output returned after Secret creation/update
@@ -41,5 +44,63 @@ export interface GitHubSecretOutput extends Resource<"github::Secret">, Omit<Git
 }
 /**
  * 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 declare const GitHubSecret: ((this: Context<GitHubSecretOutput>, id: string, props: GitHubSecretProps) => Promise<GitHubSecretOutput>) | (((this: any, id: string, props?: GitHubSecretProps | undefined) => never) & (new (_: never) => never));
+export declare const GitHubSecret: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<GitHubSecretOutput>, id: string, props: GitHubSecretProps) => Promise<GitHubSecretOutput>);