alchemy 2.0.0-beta.2 → 2.0.0-beta.3

package/src/Cloudflare/Workers/Workflow.ts

@@ -186,30 +186,72 @@ export class WorkflowScope extends Context.Service<
 >()("Cloudflare.Workflow") {}
 
 /**
- * Declare a Cloudflare Workflow inside a Worker program.
+ * A Cloudflare Workflow that orchestrates durable, multi-step tasks with
+ * automatic retries and at-least-once delivery.
  *
- * The outer Effect resolves infrastructure dependencies (Durable Objects,
- * etc.) and returns the workflow body -- an Effect that uses `WorkflowEvent`
- * and step primitives (`task`, `sleep`, `sleepUntil`).
+ * A Workflow follows the same two-phase pattern as Workers and Durable
+ * Objects. The outer `Effect.gen` resolves shared dependencies. The inner
+ * `Effect.gen` is the workflow body — it reads the triggering event and
+ * runs steps using `task`, `sleep`, and `sleepUntil`.
  *
- * Internally this creates a `WorkflowResource` that manages the Cloudflare
- * Workflows API lifecycle (PUT / DELETE), similar to how `bindContainer`
- * creates a `ContainerApplication`.
+ * ```typescript
+ * Effect.gen(function* () {
+ *   // Phase 1: resolve dependencies
+ *   const notifier = yield* NotificationService;
+ *
+ *   return Effect.gen(function* () {
+ *     // Phase 2: workflow body (durable steps)
+ *     const event = yield* Cloudflare.WorkflowEvent;
+ *     const result = yield* Cloudflare.task("process", doWork(event.payload));
+ *     yield* Cloudflare.sleep("cooldown", "10 seconds");
+ *     return result;
+ *   });
+ * })
+ * ```
+ *
+ * @resource
  *
- * @example
+ * @section Defining a Workflow
+ * @example Minimal workflow
  * ```typescript
  * export default class MyWorkflow extends Cloudflare.Workflow<MyWorkflow>()(
  *   "MyWorkflow",
  *   Effect.gen(function* () {
  *     return Effect.gen(function* () {
  *       const event = yield* Cloudflare.WorkflowEvent;
- *       const data = yield* Cloudflare.task("fetch-data", Effect.succeed({ ok: true }));
- *       yield* Cloudflare.sleep("pause", "5 seconds");
- *       return data;
+ *       return { received: event.payload };
  *     });
  *   }),
  * ) {}
  * ```
+ *
+ * @section Step Primitives
+ * @example Running a named task
+ * ```typescript
+ * const result = yield* Cloudflare.task(
+ *   "process-order",
+ *   Effect.succeed({ orderId: "abc", total: 42 }),
+ * );
+ * ```
+ *
+ * @example Sleeping between steps
+ * ```typescript
+ * yield* Cloudflare.sleep("cooldown", "30 seconds");
+ * ```
+ *
+ * @section Starting and Monitoring Instances
+ * @example Creating an instance from a Worker
+ * ```typescript
+ * const workflow = yield* MyWorkflow;
+ * const instance = yield* workflow.create({ orderId: "abc" });
+ * ```
+ *
+ * @example Checking instance status
+ * ```typescript
+ * const workflow = yield* MyWorkflow;
+ * const handle = yield* workflow.get(instanceId);
+ * const status = yield* handle.status();
+ * ```
  */
 export const Workflow: WorkflowClass = taggedFunction(WorkflowScope, ((
   ...args: [] | [name: string, impl: Effect.Effect<WorkflowBody>]

package/src/Cloudflare/Workers/index.ts

@@ -1,6 +1,6 @@
 export * from "./Assets.ts";
 export * from "./ConfigProvider.ts";
-export * from "./DurableObject.ts";
+export * from "./DurableObjectNamespace.ts";
 export * from "./DynamicWorkerLoader.ts";
 export * from "./Fetch.ts";
 export * from "./HttpServer.ts";

package/src/GitHub/Comment.ts

@@ -0,0 +1,224 @@
+import { Octokit } from "@octokit/rest";
+import * as Effect from "effect/Effect";
+import * as Provider from "../Provider.ts";
+import { Resource } from "../Resource.ts";
+import { dedent } from "../Util/dedent.ts";
+
+export interface CommentProps {
+  /**
+   * 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).
+   *
+   * The body is automatically dedented, so you can use indented template
+   * literals without worrying about leading whitespace. Accepts
+   * `Output<string>` at the call site via `Output.interpolate` to embed
+   * resource attributes that are not yet resolved.
+   */
+  body: string;
+
+  /**
+   * Whether to allow deletion of the comment when the resource is destroyed.
+   * By default, comments are never deleted to preserve discussion history.
+   * @default false
+   */
+  allowDelete?: boolean;
+
+  /**
+   * GitHub API token. If not provided, falls back to
+   * `GITHUB_ACCESS_TOKEN` or `GITHUB_TOKEN` environment variables.
+   */
+  token?: string;
+}
+
+export interface Comment extends Resource<
+  "GitHub.Comment",
+  CommentProps,
+  {
+    /**
+     * The numeric ID of the comment in GitHub.
+     */
+    commentId: number;
+
+    /**
+     * URL to view the comment in a browser.
+     */
+    htmlUrl: string;
+
+    /**
+     * ISO-8601 timestamp of the last update.
+     */
+    updatedAt: string;
+  }
+> {}
+
+/**
+ * A GitHub issue or pull request comment.
+ *
+ * `Comment` manages the lifecycle of a single comment on an issue or pull
+ * request. Comments are created on the first deploy and updated in place on
+ * subsequent deploys when the `body` changes. By default, comments are never
+ * deleted to preserve discussion history — set `allowDelete: true` to opt in.
+ *
+ * Authentication is resolved in order: explicit `token` prop,
+ * `GITHUB_ACCESS_TOKEN` env var, `GITHUB_TOKEN` env var. The token needs
+ * `repo` scope for private repositories or `public_repo` for public ones.
+ *
+ * @section Creating Comments
+ * @example Comment on an Issue
+ * ```typescript
+ * const comment = yield* GitHub.Comment("issue-comment", {
+ *   owner: "my-org",
+ *   repository: "my-repo",
+ *   issueNumber: 123,
+ *   body: "This is a comment created by Alchemy!",
+ * });
+ * ```
+ *
+ * @example Comment on a Pull Request
+ * ```typescript
+ * const prComment = yield* GitHub.Comment("pr-comment", {
+ *   owner: "my-org",
+ *   repository: "my-repo",
+ *   issueNumber: 456,
+ *   body: "## Deployment Status\n\nSuccessfully deployed to staging!",
+ * });
+ * ```
+ *
+ * @section Updating Comments
+ * Deploy with the same logical ID and a different `body` to update the
+ * existing comment in place rather than creating a new one.
+ *
+ * @example Update Comment Content
+ * ```typescript
+ * const comment = yield* GitHub.Comment("status-comment", {
+ *   owner: "my-org",
+ *   repository: "my-repo",
+ *   issueNumber: 789,
+ *   body: "Deployment completed successfully!",
+ * });
+ * ```
+ *
+ * @section Deleting Comments
+ * @example Allow Comment Deletion
+ * ```typescript
+ * const comment = yield* GitHub.Comment("temp-comment", {
+ *   owner: "my-org",
+ *   repository: "my-repo",
+ *   issueNumber: 123,
+ *   body: "This comment can be deleted",
+ *   allowDelete: true,
+ * });
+ * ```
+ *
+ * @section CI Preview Comments
+ * A common pattern is posting a preview-deployment URL on every pull request.
+ * The comment auto-updates on each push because the logical ID stays the same.
+ *
+ * @example PR Preview Comment
+ * ```typescript
+ * if (process.env.PULL_REQUEST) {
+ *   yield* GitHub.Comment("preview-comment", {
+ *     owner: "my-org",
+ *     repository: "my-repo",
+ *     issueNumber: Number(process.env.PULL_REQUEST),
+ *     body: Output.interpolate`
+ *       ## Preview Deployed
+ *
+ *       **URL:** ${website.url}
+ *     `,
+ *   });
+ * }
+ * ```
+ */
+export const Comment = Resource<Comment>("GitHub.Comment");
+
+function resolveToken(props: CommentProps): string | undefined {
+  return (
+    props.token ?? process.env.GITHUB_ACCESS_TOKEN ?? process.env.GITHUB_TOKEN
+  );
+}
+
+function createClient(props: CommentProps): Octokit {
+  return new Octokit({ auth: resolveToken(props) });
+}
+
+export const CommentProvider = () =>
+  Provider.succeed(Comment, {
+    stables: ["commentId"],
+
+    create: Effect.fn(function* ({ news }) {
+      const octokit = createClient(news);
+      const body = dedent(news.body);
+
+      const { data } = yield* Effect.tryPromise(() =>
+        octokit.rest.issues.createComment({
+          owner: news.owner,
+          repo: news.repository,
+          issue_number: news.issueNumber,
+          body,
+        }),
+      );
+
+      return {
+        commentId: data.id,
+        htmlUrl: data.html_url,
+        updatedAt: data.updated_at,
+      };
+    }),
+
+    update: Effect.fn(function* ({ news, output }) {
+      const octokit = createClient(news);
+      const body = dedent(news.body);
+
+      const { data } = yield* Effect.tryPromise(() =>
+        octokit.rest.issues.updateComment({
+          owner: news.owner,
+          repo: news.repository,
+          comment_id: output.commentId,
+          body,
+        }),
+      );
+
+      return {
+        commentId: data.id,
+        htmlUrl: data.html_url,
+        updatedAt: data.updated_at,
+      };
+    }),
+
+    delete: Effect.fn(function* ({ olds, output }) {
+      if (!olds.allowDelete) {
+        return;
+      }
+
+      const octokit = createClient(olds);
+
+      yield* Effect.tryPromise(async () => {
+        try {
+          await octokit.rest.issues.deleteComment({
+            owner: olds.owner,
+            repo: olds.repository,
+            comment_id: output.commentId,
+          });
+        } catch (error: any) {
+          if (error.status !== 404) {
+            throw error;
+          }
+        }
+      });
+    }),
+  });

package/src/GitHub/Secret.ts

@@ -0,0 +1,212 @@
+import { Octokit } from "@octokit/rest";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import * as Provider from "../Provider.ts";
+import { Resource } from "../Resource.ts";
+
+export interface SecretProps {
+  /**
+   * Repository owner (user or organization).
+   */
+  owner: string;
+
+  /**
+   * Repository name.
+   */
+  repository: string;
+
+  /**
+   * Secret name (e.g. `AWS_ROLE_ARN`).
+   */
+  name: string;
+
+  /**
+   * Secret value. Wrap with `Redacted.make` to prevent the value from
+   * appearing in logs or state.
+   */
+  value: Redacted.Redacted;
+
+  /**
+   * Optional environment name. When set the secret is scoped to that
+   * GitHub Actions environment instead of the whole repository.
+   */
+  environment?: string;
+
+  /**
+   * GitHub API token. If not provided, falls back to
+   * `GITHUB_ACCESS_TOKEN` or `GITHUB_TOKEN` environment variables.
+   */
+  token?: string;
+}
+
+export interface Secret extends Resource<
+  "GitHub.Secret",
+  SecretProps,
+  {
+    /**
+     * ISO-8601 timestamp of the last update.
+     */
+    updatedAt: string;
+  }
+> {}
+
+/**
+ * A GitHub Actions repository or environment secret.
+ *
+ * Secrets are encrypted using the repository's (or environment's) public
+ * key before being stored. The resource is idempotent — calling it with
+ * the same name will update the secret value in place.
+ *
+ * @section Repository Secrets
+ * @example Create a Repository Secret
+ * ```typescript
+ * yield* GitHub.Secret("aws-role", {
+ *   owner: "my-org",
+ *   repository: "my-repo",
+ *   name: "AWS_ROLE_ARN",
+ *   value: Redacted.make(role.roleArn),
+ * });
+ * ```
+ *
+ * @section Environment Secrets
+ * @example Create an Environment Secret
+ * ```typescript
+ * yield* GitHub.Secret("deploy-key", {
+ *   owner: "my-org",
+ *   repository: "my-repo",
+ *   environment: "production",
+ *   name: "DEPLOY_KEY",
+ *   value: Redacted.make("my-secret-value"),
+ * });
+ * ```
+ */
+export const Secret = Resource<Secret>("GitHub.Secret");
+
+function resolveToken(props: SecretProps): string | undefined {
+  return (
+    props.token ?? process.env.GITHUB_ACCESS_TOKEN ?? process.env.GITHUB_TOKEN
+  );
+}
+
+function createClient(props: SecretProps): Octokit {
+  return new Octokit({ auth: resolveToken(props) });
+}
+
+async function encryptValue(
+  plaintext: string,
+  publicKey: string,
+): Promise<string> {
+  const sodium = await import("libsodium-wrappers");
+  await sodium.ready;
+  const binKey = sodium.from_base64(
+    publicKey,
+    sodium.base64_variants.ORIGINAL,
+  );
+  const binMessage = sodium.from_string(plaintext);
+  const encrypted = sodium.crypto_box_seal(binMessage, binKey);
+  return sodium.to_base64(encrypted, sodium.base64_variants.ORIGINAL);
+}
+
+export const SecretProvider = () =>
+  Provider.succeed(Secret, {
+    create: Effect.fn(function* ({ news }) {
+      const octokit = createClient(news);
+      yield* upsertSecret(octokit, news);
+      return { updatedAt: new Date().toISOString() };
+    }),
+
+    update: Effect.fn(function* ({ news, olds, output }) {
+      const octokit = createClient(news);
+
+      const wasEnv = !!olds.environment;
+      const isEnv = !!news.environment;
+      if (wasEnv !== isEnv || olds.environment !== news.environment) {
+        yield* deleteSecret(octokit, olds);
+      }
+
+      yield* upsertSecret(octokit, news);
+      return { updatedAt: new Date().toISOString() };
+    }),
+
+    delete: Effect.fn(function* ({ olds }) {
+      const octokit = createClient(olds);
+      yield* deleteSecret(octokit, olds);
+    }),
+  });
+
+const upsertSecret = Effect.fn(function* (
+  octokit: Octokit,
+  props: SecretProps,
+) {
+  const plaintext = Redacted.value(props.value);
+  const isEnv = !!props.environment;
+
+  const publicKey = yield* Effect.tryPromise(async () => {
+    if (isEnv) {
+      const { data } = await octokit.rest.actions.getEnvironmentPublicKey({
+        owner: props.owner,
+        repo: props.repository,
+        environment_name: props.environment!,
+      });
+      return data;
+    }
+    const { data } = await octokit.rest.actions.getRepoPublicKey({
+      owner: props.owner,
+      repo: props.repository,
+    });
+    return data;
+  });
+
+  const encrypted = yield* Effect.tryPromise(() =>
+    encryptValue(plaintext, publicKey.key),
+  );
+
+  yield* Effect.tryPromise(async () => {
+    if (isEnv) {
+      await octokit.rest.actions.createOrUpdateEnvironmentSecret({
+        owner: props.owner,
+        repo: props.repository,
+        environment_name: props.environment!,
+        secret_name: props.name,
+        encrypted_value: encrypted,
+        key_id: publicKey.key_id,
+      });
+    } else {
+      await octokit.rest.actions.createOrUpdateRepoSecret({
+        owner: props.owner,
+        repo: props.repository,
+        secret_name: props.name,
+        encrypted_value: encrypted,
+        key_id: publicKey.key_id,
+      });
+    }
+  });
+});
+
+const deleteSecret = Effect.fn(function* (
+  octokit: Octokit,
+  props: SecretProps,
+) {
+  yield* Effect.tryPromise(async () => {
+    try {
+      if (props.environment) {
+        await octokit.rest.actions.deleteEnvironmentSecret({
+          owner: props.owner,
+          repo: props.repository,
+          environment_name: props.environment,
+          secret_name: props.name,
+        });
+      } else {
+        await octokit.rest.actions.deleteRepoSecret({
+          owner: props.owner,
+          repo: props.repository,
+          secret_name: props.name,
+        });
+      }
+    } catch (error: any) {
+      if (error.status !== 404) {
+        throw error;
+      }
+    }
+  });
+});

package/src/GitHub/Variable.ts

@@ -0,0 +1,123 @@
+import { Octokit } from "@octokit/rest";
+import * as Effect from "effect/Effect";
+import * as Provider from "../Provider.ts";
+import { Resource } from "../Resource.ts";
+
+export interface VariableProps {
+  /**
+   * Repository owner (user or organization).
+   */
+  owner: string;
+
+  /**
+   * Repository name.
+   */
+  repository: string;
+
+  /**
+   * Variable name (e.g. `AWS_ROLE_ARN`).
+   */
+  name: string;
+
+  /**
+   * Variable value.
+   */
+  value: string;
+
+  /**
+   * GitHub API token. If not provided, falls back to
+   * `GITHUB_ACCESS_TOKEN` or `GITHUB_TOKEN` environment variables.
+   */
+  token?: string;
+}
+
+export interface Variable extends Resource<
+  "GitHub.Variable",
+  VariableProps,
+  {
+    /**
+     * ISO-8601 timestamp of the last update.
+     */
+    updatedAt: string;
+  }
+> {}
+
+/**
+ * A GitHub Actions repository variable.
+ *
+ * Variables are stored in plain text and are suitable for non-sensitive
+ * configuration like region names or role ARNs.
+ *
+ * @section Repository Variables
+ * @example Create a Repository Variable
+ * ```typescript
+ * yield* GitHub.Variable("aws-region", {
+ *   owner: "my-org",
+ *   repository: "my-repo",
+ *   name: "AWS_REGION",
+ *   value: "us-east-1",
+ * });
+ * ```
+ */
+export const Variable = Resource<Variable>("GitHub.Variable");
+
+function resolveToken(props: VariableProps): string | undefined {
+  return (
+    props.token ?? process.env.GITHUB_ACCESS_TOKEN ?? process.env.GITHUB_TOKEN
+  );
+}
+
+function createClient(props: VariableProps): Octokit {
+  return new Octokit({ auth: resolveToken(props) });
+}
+
+export const VariableProvider = () =>
+  Provider.succeed(Variable, {
+    create: Effect.fn(function* ({ news }) {
+      const octokit = createClient(news);
+
+      yield* Effect.tryPromise(() =>
+        octokit.rest.actions.createRepoVariable({
+          owner: news.owner,
+          repo: news.repository,
+          name: news.name,
+          value: news.value,
+        }),
+      );
+
+      return { updatedAt: new Date().toISOString() };
+    }),
+
+    update: Effect.fn(function* ({ news }) {
+      const octokit = createClient(news);
+
+      yield* Effect.tryPromise(() =>
+        octokit.rest.actions.updateRepoVariable({
+          owner: news.owner,
+          repo: news.repository,
+          name: news.name,
+          value: news.value,
+        }),
+      );
+
+      return { updatedAt: new Date().toISOString() };
+    }),
+
+    delete: Effect.fn(function* ({ olds }) {
+      const octokit = createClient(olds);
+
+      yield* Effect.tryPromise(async () => {
+        try {
+          await octokit.rest.actions.deleteRepoVariable({
+            owner: olds.owner,
+            repo: olds.repository,
+            name: olds.name,
+          });
+        } catch (error: any) {
+          if (error.status !== 404) {
+            throw error;
+          }
+        }
+      });
+    }),
+  });

package/src/GitHub/index.ts

@@ -0,0 +1,3 @@
+export * from "./Comment.ts";
+export * from "./Secret.ts";
+export * from "./Variable.ts";

package/src/Provider.ts

@@ -369,7 +369,7 @@ export const tryFindProviderByType: {
   const Tag = Provider<R>(resourceType) as Context.Service<Provider<R>, any>;
   const direct = yield* Effect.serviceOption(Tag);
   if (Option.isSome(direct)) {
-    return direct.value;
+    return direct;
   }
 
   const context = yield* Effect.context<never>();