alchemy 0.28.0 → 0.29.1

package/src/alchemy.ts

@@ -19,6 +19,39 @@ import { logger } from "./util/logger.ts";
 import { TelemetryClient } from "./util/telemetry/client.ts";
 import type { LoggerApi } from "./util/cli.ts";
 
+/**
+ * Parses CLI arguments to extract alchemy options
+ */
+function parseCliArgs(): Partial<AlchemyOptions> {
+  const args = process.argv.slice(2);
+  const options: Partial<AlchemyOptions> = {};
+
+  // Parse phase from CLI arguments
+  if (args.includes("--destroy")) {
+    options.phase = "destroy";
+  } else if (args.includes("--read")) {
+    options.phase = "read";
+  }
+
+  // Parse quiet flag
+  if (args.includes("--quiet")) {
+    options.quiet = true;
+  }
+
+  // Parse stage argument (--stage my-stage)
+  const stageIndex = args.indexOf("--stage");
+  if (stageIndex !== -1 && stageIndex + 1 < args.length) {
+    options.stage = args[stageIndex + 1];
+  }
+
+  // Get password from environment variables
+  if (process.env.ALCHEMY_PASSWORD) {
+    options.password = process.env.ALCHEMY_PASSWORD;
+  }
+
+  return options;
+}
+
 /**
  * Type alias for semantic highlighting of `alchemy` as a type keyword
  */
@@ -29,9 +62,16 @@ export const alchemy: Alchemy = _alchemy as any;
 /**
  * The Alchemy interface provides core functionality and is augmented by providers.
  * Supports both application scoping with secrets and template string interpolation.
+ * Automatically parses CLI arguments for common options.
  *
  * @example
- * // Create an application scope with stage and secret handling
+ * // Simple usage with automatic CLI argument parsing
+ * const app = await alchemy("my-app");
+ * // Now supports: --destroy, --read, --quiet, --stage my-stage
+ * // Environment variables: PASSWORD, ALCHEMY_PASSWORD, ALCHEMY_STAGE, USER
+ *
+ * @example
+ * // Create an application scope with explicit options (overrides CLI args)
  * const app = await alchemy("github:alchemy", {
  *   stage: "prod",
  *   phase: "up",
@@ -69,8 +109,15 @@ export interface Alchemy {
   /**
    * Creates a new application scope with the given name and options.
    * Used to create and manage resources with proper secret handling.
+   * Automatically parses CLI arguments: --destroy, --read, --quiet, --stage <name>
+   * Environment variables: PASSWORD, ALCHEMY_PASSWORD, ALCHEMY_STAGE, USER
+   *
+   * @example
+   * // Simple usage with CLI argument parsing
+   * const app = await alchemy("my-app");
    *
    * @example
+   * // With explicit options (overrides CLI args)
    * const app = await alchemy("my-app", {
    *   stage: "prod",
    *   // Required for encrypting/decrypting secrets
@@ -115,20 +162,29 @@ async function _alchemy(
 ): Promise<Scope | string | never> {
   if (typeof args[0] === "string") {
     const [appName, options] = args as [string, AlchemyOptions?];
-    const phase = isRuntime ? "read" : (options?.phase ?? "up");
+
+    // Parse CLI arguments and merge with provided options (explicit options take precedence)
+    const cliOptions = parseCliArgs();
+    const mergedOptions = {
+      ...cliOptions,
+      ...options,
+    };
+
+    const phase = isRuntime ? "read" : (mergedOptions?.phase ?? "up");
     const telemetryClient =
-      options?.parent?.telemetryClient ??
+      mergedOptions?.parent?.telemetryClient ??
       TelemetryClient.create({
         phase,
-        enabled: options?.telemetry ?? true,
-        quiet: options?.quiet ?? false,
+        enabled: mergedOptions?.telemetry ?? true,
+        quiet: mergedOptions?.quiet ?? false,
       });
     const root = new Scope({
-      ...options,
+      ...mergedOptions,
       appName,
-      stage: options?.stage ?? process.env.ALCHEMY_STAGE,
+      stage:
+        mergedOptions?.stage ?? process.env.ALCHEMY_STAGE ?? process.env.USER,
       phase,
-      password: options?.password ?? process.env.ALCHEMY_PASSWORD,
+      password: mergedOptions?.password ?? process.env.ALCHEMY_PASSWORD,
       telemetryClient,
     });
     try {
@@ -138,7 +194,7 @@ async function _alchemy(
       // see Scope.finalize for where we pop the global scope
       Scope.globals.push(root);
     }
-    if (options?.phase === "destroy") {
+    if (mergedOptions?.phase === "destroy") {
       await destroy(root);
       return process.exit(0);
     }

package/src/apply.ts

@@ -41,12 +41,6 @@ async function _apply<Out extends Resource>(
   const scope = resource[ResourceScope];
   const start = performance.now();
   try {
-    logger.task(resource[ResourceFQN], {
-      prefix: "SETUP",
-      prefixColor: "cyanBright",
-      resource: formatFQN(resource[ResourceFQN]),
-      message: "Setting up Resource...",
-    });
     const quiet = props?.quiet ?? scope.quiet;
     await scope.init();
     let state: State | undefined = (await scope.state.get(
@@ -112,7 +106,7 @@ async function _apply<Out extends Resource>(
       ) {
         if (!quiet) {
           logger.task(resource[ResourceFQN], {
-            prefix: "SKIPPED",
+            prefix: "skipped",
             prefixColor: "yellowBright",
             resource: formatFQN(resource[ResourceFQN]),
             message: "Skipped Resource (no changes)",
@@ -141,7 +135,7 @@ async function _apply<Out extends Resource>(
 
     if (!quiet) {
       logger.task(resource[ResourceFQN], {
-        prefix: phase === "create" ? "CREATING" : "UPDATING",
+        prefix: phase === "create" ? "creating" : "updating",
         prefixColor: "magenta",
         resource: formatFQN(resource[ResourceFQN]),
         message: `${phase === "create" ? "Creating" : "Updating"} Resource...`,
@@ -191,7 +185,7 @@ async function _apply<Out extends Resource>(
     );
     if (!quiet) {
       logger.task(resource[ResourceFQN], {
-        prefix: phase === "create" ? "CREATED" : "UPDATED",
+        prefix: phase === "create" ? "created" : "updated",
         prefixColor: "greenBright",
         resource: formatFQN(resource[ResourceFQN]),
         message: `${phase === "create" ? "Created" : "Updated"} Resource`,

package/src/cloudflare/do-state-store/internal.ts

@@ -104,6 +104,7 @@ export async function upsertStateStoreWorker(
   api: CloudflareApi,
   workerName: string,
   token: string,
+  force: boolean,
 ) {
   const key = `worker:${workerName}`;
   const cached = cache.get(key);
@@ -111,7 +112,7 @@ export async function upsertStateStoreWorker(
     return;
   }
   const { found, tag } = await getWorkerStatus(api, workerName);
-  if (found && tag === TAG) {
+  if (found && tag === TAG && !force) {
     cache.set(key, TAG);
     return;
   }

package/src/cloudflare/do-state-store/store.ts

@@ -88,7 +88,12 @@ export class DOStateStore implements StateStore {
     const api = await createCloudflareApi(this.options);
     const [subdomain, _] = await Promise.all([
       getAccountSubdomain(api),
-      upsertStateStoreWorker(api, workerName, token),
+      upsertStateStoreWorker(
+        api,
+        workerName,
+        token,
+        this.options.worker?.force ?? false,
+      ),
     ]);
     const client = new DOStateStoreClient({
       app: this.scope.appName ?? "alchemy",
@@ -97,9 +102,26 @@ export class DOStateStore implements StateStore {
       token,
     });
     // This ensures the token is correct and the worker is ready to use.
-    // RPC methods are retried, which is what we want here in case the worker is not ready yet.
-    await client.rpc("validate", null);
-    return client;
+    let last: Response | undefined;
+    let delay = 1000;
+    for (let i = 0; i < 20; i++) {
+      const res = await client.validate();
+      if (res.ok) {
+        return client;
+      }
+      if (!last) {
+        console.log("Waiting for state store deployment...");
+      }
+      last = res;
+      // Exponential backoff with jitter
+      const jitter = Math.random() * 0.1 * delay;
+      await new Promise((resolve) => setTimeout(resolve, delay + jitter));
+      delay *= 1.5; // Increase the delay for next attempt
+      delay = Math.min(delay, 10000); // Cap at 10 seconds
+    }
+    throw new Error(
+      `Failed to access state store: ${last?.status} ${last?.statusText}`,
+    );
   }
 
   private async getClient() {

package/src/cloudflare/secrets-store.ts

@@ -220,33 +220,34 @@ const _SecretsStore = Resource("cloudflare::SecretsStore", async function <
 
     await insertSecrets(api, storeId, props);
   } else {
-    try {
+    // If adopt is true, first check if a store with this name already exists
+    if (props.adopt) {
+      console.log(`Checking for existing secrets store '${name}' to adopt`);
+      const existingStore = await findSecretsStoreByName(api, name);
+
+      if (existingStore) {
+        console.log(`Found existing secrets store '${name}', adopting it`);
+        storeId = existingStore.id;
+        createdAt = existingStore.createdAt || Date.now();
+      } else {
+        console.log(
+          `No existing secrets store '${name}' found, creating new one`,
+        );
+        const { id } = await createSecretsStore(api, {
+          ...props,
+          name,
+        });
+        createdAt = Date.now();
+        storeId = id;
+      }
+    } else {
+      // Default behavior: create a new store
       const { id } = await createSecretsStore(api, {
         ...props,
         name,
       });
       createdAt = Date.now();
       storeId = id;
-    } catch (error) {
-      if (
-        props.adopt &&
-        error instanceof Error &&
-        error.message.includes("already exists")
-      ) {
-        console.log(`Secrets store '${name}' already exists, adopting it`);
-        const existingStore = await findSecretsStoreByName(api, name);
-
-        if (!existingStore) {
-          throw new Error(
-            `Failed to find existing secrets store '${name}' for adoption`,
-          );
-        }
-
-        storeId = existingStore.id;
-        createdAt = existingStore.createdAt || Date.now();
-      } else {
-        throw error;
-      }
     }
 
     await insertSecrets(api, storeId, props);

package/src/cloudflare/worker-assets.ts

@@ -3,6 +3,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { AsyncQueue } from "../util/async-queue.ts";
 import { getContentType } from "../util/content-type.ts";
+import { CloudflareApiError } from "./api-error.ts";
 import type { CloudflareApi } from "./api.ts";
 import type { Assets } from "./assets.ts";
 import type { AssetsConfig, WorkerProps } from "./worker.ts";
@@ -84,6 +85,21 @@ export async function uploadAssets(
   const sessionData =
     (await uploadSessionResponse.json()) as UploadSessionResponse;
 
+  if (!sessionData?.success) {
+    if (sessionData?.errors) {
+      throw new CloudflareApiError(
+        `Failed to start assets upload session:\n${sessionData.errors
+          .map((error) => `- ${error.code}: ${error.message}`)
+          .join("\n")}`,
+        uploadSessionResponse,
+      );
+    }
+    throw new CloudflareApiError(
+      `Failed to start assets upload session: ${uploadSessionResponse.statusText}`,
+      uploadSessionResponse,
+    );
+  }
+
   // If there are no buckets, assets are already uploaded or empty
   if (!sessionData.result.buckets || sessionData.result.buckets.length === 0) {
     return {

package/src/destroy.ts

@@ -89,8 +89,8 @@ export async function destroy<Type extends string>(
   try {
     if (!quiet) {
       logger.task(instance[ResourceFQN], {
-        prefix: "DELETING",
-        prefixColor: "magenta",
+        prefix: "deleting",
+        prefixColor: "redBright",
         resource: formatFQN(instance[ResourceFQN]),
         message: "Deleting Resource...",
       });
@@ -150,7 +150,7 @@ export async function destroy<Type extends string>(
 
     if (!quiet) {
       logger.task(instance[ResourceFQN], {
-        prefix: "DELETED",
+        prefix: "deleted",
         prefixColor: "greenBright",
         resource: formatFQN(instance[ResourceFQN]),
         message: "Deleted Resource",

package/src/github/comment.ts

@@ -0,0 +1,278 @@
+import type { Context } from "../context.ts";
+import { Resource } from "../resource.ts";
+import type { Secret } from "../secret.ts";
+import { logger } from "../util/logger.ts";
+import { createGitHubClient, verifyGitHubAuth } from "./client.ts";
+
+/**
+ * Properties for creating or updating a GitHub Comment
+ */
+export interface GitHubCommentProps {
+  /**
+   * Repository owner (user or organization)
+   */
+  owner: string;
+
+  /**
+   * Repository name
+   */
+  repository: string;
+
+  /**
+   * Issue or Pull Request number to comment on
+   */
+  issueNumber: number;
+
+  /**
+   * Comment body (supports GitHub Markdown)
+   */
+  body: string;
+
+  /**
+   * Whether to allow deletion of the comment
+   * By default, comments are never deleted to preserve discussion history
+   * @default false
+   */
+  allowDelete?: boolean;
+
+  /**
+   * Optional GitHub API token (overrides environment variable)
+   * If not provided, will use GITHUB_TOKEN or GITHUB_ACCESS_TOKEN environment variables
+   * Token must have 'repo' scope for private repositories
+   * or 'public_repo' scope for public repositories
+   */
+  token?: Secret;
+}
+
+/**
+ * Output returned after Comment creation/update
+ */
+export interface GitHubComment
+  extends Resource<"github::Comment">,
+    Omit<GitHubCommentProps, "token"> {
+  /**
+   * The ID of the resource
+   */
+  id: string;
+
+  /**
+   * The numeric ID of the comment in GitHub
+   */
+  commentId: number;
+
+  /**
+   * URL to view the comment
+   */
+  htmlUrl: string;
+
+  /**
+   * Time at which the comment was created/updated
+   */
+  updatedAt: string;
+}
+
+/**
+ * Resource for managing GitHub issue and pull request comments
+ *
+ * By default, comments are never deleted to preserve discussion history.
+ * Set `allowDelete: true` to enable deletion when the resource is destroyed.
+ *
+ * Authentication is handled in the following order:
+ * 1. `token` parameter in the resource props (if provided)
+ * 2. `GITHUB_ACCESS_TOKEN` environment variable (for actions with admin permissions)
+ * 3. `GITHUB_TOKEN` environment variable
+ * 4. GitHub CLI token (if gh is installed and authenticated)
+ *
+ * The token must have the following permissions:
+ * - 'repo' scope for private repositories
+ * - 'public_repo' scope for public repositories
+ *
+ * @example
+ * ## Create a comment on an issue
+ *
+ * Create a comment on issue #123 using the default GITHUB_TOKEN
+ *
+ * ```ts
+ * const comment = await GitHubComment("issue-comment", {
+ *   owner: "my-org",
+ *   repository: "my-repo",
+ *   issueNumber: 123,
+ *   body: "This is a comment created by Alchemy!"
+ * });
+ * ```
+ *
+ * @example
+ * ## Create a comment on a pull request
+ *
+ * Comments work the same way for pull requests
+ *
+ * ```ts
+ * const prComment = await GitHubComment("pr-comment", {
+ *   owner: "my-org",
+ *   repository: "my-repo",
+ *   issueNumber: 456, // PR number
+ *   body: "## Deployment Status\n\n✅ Successfully deployed to staging!"
+ * });
+ * ```
+ *
+ * @example
+ * ## Update comment content
+ *
+ * Comments can be updated by changing the body content
+ *
+ * ```ts
+ * const comment = await GitHubComment("status-comment", {
+ *   owner: "my-org",
+ *   repository: "my-repo",
+ *   issueNumber: 789,
+ *   body: "🔄 Deployment in progress..."
+ * });
+ *
+ * // Later, update the comment
+ * await GitHubComment("status-comment", {
+ *   owner: "my-org",
+ *   repository: "my-repo",
+ *   issueNumber: 789,
+ *   body: "✅ Deployment completed successfully!"
+ * });
+ * ```
+ *
+ * @example
+ * ## Allow comment deletion
+ *
+ * By default comments are preserved, but you can opt-in to deletion
+ *
+ * ```ts
+ * const comment = await GitHubComment("temp-comment", {
+ *   owner: "my-org",
+ *   repository: "my-repo",
+ *   issueNumber: 123,
+ *   body: "This comment can be deleted",
+ *   allowDelete: true
+ * });
+ * ```
+ *
+ * @example
+ * ## Use custom authentication token
+ *
+ * Pass a custom GitHub token for authentication
+ *
+ * ```ts
+ * const comment = await GitHubComment("authenticated-comment", {
+ *   owner: "my-org",
+ *   repository: "my-repo",
+ *   issueNumber: 123,
+ *   body: "Comment with custom token",
+ *   token: alchemy.secret(process.env.CUSTOM_GITHUB_TOKEN)
+ * });
+ * ```
+ */
+export const GitHubComment = Resource(
+  "github::Comment",
+  async function (
+    this: Context<GitHubComment>,
+    _id: string,
+    props: GitHubCommentProps,
+  ): Promise<GitHubComment> {
+    // Create authenticated Octokit client - will automatically handle token resolution
+    const octokit = await createGitHubClient({
+      token: props.token?.unencrypted,
+    });
+
+    // Verify authentication and permissions
+    if (!this.quiet) {
+      await verifyGitHubAuth(octokit, props.owner, props.repository);
+    }
+
+    if (this.phase === "delete") {
+      if (this.output?.commentId && props.allowDelete) {
+        try {
+          // Delete the comment
+          await octokit.rest.issues.deleteComment({
+            owner: props.owner,
+            repo: props.repository,
+            comment_id: this.output.commentId,
+          });
+        } catch (error: any) {
+          // Ignore 404 errors (comment already deleted)
+          if (error.status === 404) {
+            logger.log("Comment doesn't exist, ignoring");
+          } else {
+            throw error;
+          }
+        }
+      } else if (this.output?.commentId && !props.allowDelete) {
+        logger.log(
+          "Comment deletion skipped - allowDelete is false (default behavior to preserve discussion history)",
+        );
+      }
+
+      // Return void (a deleted resource has no content)
+      return this.destroy();
+    }
+
+    try {
+      if (this.phase === "update" && this.output?.commentId) {
+        // Update existing comment
+        const { data: updatedComment } =
+          await octokit.rest.issues.updateComment({
+            owner: props.owner,
+            repo: props.repository,
+            comment_id: this.output.commentId,
+            body: props.body,
+          });
+
+        return this({
+          id: `${props.owner}/${props.repository}/issues/${props.issueNumber}/comments/${updatedComment.id}`,
+          commentId: updatedComment.id,
+          owner: props.owner,
+          repository: props.repository,
+          issueNumber: props.issueNumber,
+          body: props.body,
+          allowDelete: props.allowDelete,
+          htmlUrl: updatedComment.html_url,
+          updatedAt: updatedComment.updated_at,
+        });
+      } else {
+        // Create new comment
+        const { data: newComment } = await octokit.rest.issues.createComment({
+          owner: props.owner,
+          repo: props.repository,
+          issue_number: props.issueNumber,
+          body: props.body,
+        });
+
+        return this({
+          id: `${props.owner}/${props.repository}/issues/${props.issueNumber}/comments/${newComment.id}`,
+          commentId: newComment.id,
+          owner: props.owner,
+          repository: props.repository,
+          issueNumber: props.issueNumber,
+          body: props.body,
+          allowDelete: props.allowDelete,
+          htmlUrl: newComment.html_url,
+          updatedAt: newComment.updated_at,
+        });
+      }
+    } catch (error: any) {
+      if (error.status === 403) {
+        logger.error(
+          "\n⚠️ Error creating/updating GitHub comment: Insufficient permissions.",
+        );
+        logger.error(
+          "Make sure your GitHub token has the required permissions (repo scope for private repos).\n",
+        );
+      } else if (error.status === 404) {
+        logger.error(
+          `\n⚠️ Issue or Pull Request #${props.issueNumber} not found in ${props.owner}/${props.repository}`,
+        );
+        logger.error(
+          "Make sure the issue/PR exists and you have access to it\n",
+        );
+      } else {
+        logger.error("Error creating/updating GitHub comment:", error.message);
+      }
+      throw error;
+    }
+  },
+);

package/src/github/index.ts

@@ -1,2 +1,3 @@
+export * from "./comment.ts";
 export * from "./repository-environment.ts";
 export * from "./secret.ts";

package/src/index.ts

@@ -1,7 +1,7 @@
 export type { AlchemyOptions, Phase } from "./alchemy.ts";
 export type * from "./context.ts";
 export * from "./resource.ts";
-export type * from "./scope.ts";
+export * from "./scope.ts";
 export * from "./secret.ts";
 export * from "./serde.ts";
 export * from "./state.ts";

package/src/scope.ts

@@ -27,10 +27,15 @@ export interface ScopeOptions {
 // TODO: support browser
 const DEFAULT_STAGE = process.env.ALCHEMY_STAGE ?? process.env.USER ?? "dev";
 
+declare global {
+  var __ALCHEMY_STORAGE__: AsyncLocalStorage<Scope>;
+}
+
 export class Scope {
   public static readonly KIND = "alchemy::Scope" as const;
 
-  public static storage = new AsyncLocalStorage<Scope>();
+  public static storage = (globalThis.__ALCHEMY_STORAGE__ ??=
+    new AsyncLocalStorage<Scope>());
   public static globals: Scope[] = [];
 
   public static get(): Scope | undefined {
@@ -98,11 +103,14 @@ export class Scope {
 
     this.logger = this.quiet
       ? createDummyLogger()
-      : createLoggerInstance({
-          phase: this.phase,
-          stage: this.stage,
-          appName: this.appName ?? "",
-        }, options.logger);
+      : createLoggerInstance(
+          {
+            phase: this.phase,
+            stage: this.stage,
+            appName: this.appName ?? "",
+          },
+          options.logger,
+        );
 
     this.stateStore =
       options.stateStore ??