alchemy 0.2.2 → 0.2.4

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, { path: dirPath }: {
-    path: string;
-}) => Promise<Folder>) | (((this: any, id: string, props: {
-    path: string;
-}) => 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,10 +1,35 @@
 import fs from "node:fs";
 import { Resource } from "../resource";
 import { ignore } from "../util/ignore";
-export const Folder = Resource("fs::Folder", async function (id, { path: dirPath }) {
+/**
+ * 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) => 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>);

package/lib/github/secret.js

@@ -3,11 +3,71 @@ import { Resource } from "../resource";
 import { createGitHubClient, verifyGitHubAuth } from "./client";
 /**
  * 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", async function (id, props) {
     // 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) {
         await verifyGitHubAuth(octokit, props.owner, props.repository);

package/lib/internal/docs.d.ts

@@ -0,0 +1,5 @@
+export interface DocsProps {
+    docs?: boolean | number;
+}
+export type AlchemyDocs = Awaited<ReturnType<typeof AlchemyDocs>>;
+export declare function AlchemyDocs({ docs: isDocsEnabled }: DocsProps): Promise<void>;