alchemy 0.27.0 → 0.29.0

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

@@ -8,7 +8,7 @@ import {
   createDummyLogger,
   createLoggerInstance,
   type LoggerApi,
-} from "./util/cli.tsx";
+} from "./util/cli.ts";
 import type { ITelemetryClient } from "./util/telemetry/client.ts";
 
 export interface ScopeOptions {
@@ -21,6 +21,7 @@ export interface ScopeOptions {
   quiet?: boolean;
   phase?: Phase;
   telemetryClient?: ITelemetryClient;
+  logger?: LoggerApi;
 }
 
 // TODO: support browser
@@ -97,11 +98,14 @@ export class Scope {
 
     this.logger = this.quiet
       ? createDummyLogger()
-      : createLoggerInstance({
-          phase: this.phase,
-          stage: this.stage,
-          appName: this.appName ?? "",
-        });
+      : createLoggerInstance(
+          {
+            phase: this.phase,
+            stage: this.stage,
+            appName: this.appName ?? "",
+          },
+          options.logger,
+        );
 
     this.stateStore =
       options.stateStore ??

package/src/util/cli.ts

@@ -0,0 +1,117 @@
+import packageJson from "../../package.json" with { type: "json" };
+import type { Phase } from "../alchemy.ts";
+import { dedent } from "./dedent.ts";
+
+// ANSI color codes
+const colors = {
+  reset: "\x1b[0m",
+  cyanBright: "\x1b[96m",
+  yellowBright: "\x1b[93m",
+  magenta: "\x1b[35m",
+  greenBright: "\x1b[92m",
+  redBright: "\x1b[91m",
+  gray: "\x1b[90m",
+} as const;
+
+type ColorName = keyof typeof colors;
+
+// Check if colors should be disabled
+const shouldDisableColors = (): boolean => {
+  return Boolean(
+    process.env.CI || process.env.NO_COLOR || !process.stdout.isTTY,
+  );
+};
+
+// Apply color if colors are enabled
+const colorize = (text: string, color: ColorName): string => {
+  if (shouldDisableColors()) {
+    return text;
+  }
+  return `${colors[color]}${text}${colors.reset}`;
+};
+
+export type Task = {
+  prefix?: string;
+  prefixColor?: string;
+  resource?: string;
+  message: string;
+  status?: "pending" | "success" | "failure";
+};
+
+export type LoggerApi = {
+  log: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+  error: (...args: unknown[]) => void;
+  task: (id: string, data: Task) => void;
+  exit: () => void;
+};
+
+type AlchemyInfo = {
+  phase: Phase;
+  stage: string;
+  appName: string;
+};
+
+let loggerApi: LoggerApi | null = null;
+export const createLoggerInstance = (
+  alchemyInfo: AlchemyInfo,
+  customLogger?: LoggerApi,
+) => {
+  if (loggerApi) return loggerApi;
+
+  // Use custom logger if provided, otherwise use the basic fallback logger
+  loggerApi = customLogger ?? createFallbackLogger(alchemyInfo);
+  return loggerApi;
+};
+
+export const createDummyLogger = (): LoggerApi => {
+  return {
+    log: () => {},
+    error: () => {},
+    warn: () => {},
+    task: () => {},
+    exit: () => {},
+  };
+};
+
+export const createFallbackLogger = (alchemyInfo: AlchemyInfo): LoggerApi => {
+  console.log(dedent`
+    ${colorize("Alchemy", "cyanBright")} (v${packageJson.version})
+    App: ${alchemyInfo.appName}
+    Phase: ${alchemyInfo.phase}
+    Stage: ${alchemyInfo.stage}
+    
+  `);
+
+  return {
+    log: console.log,
+    error: (...args: unknown[]) =>
+      console.error(colorize("ERROR", "redBright"), ...args),
+    warn: (...args: unknown[]) =>
+      console.warn(colorize("WARN", "yellowBright"), ...args),
+    task: (_id: string, data: Task) => {
+      const prefix = data.prefix ? `[${data.prefix}]` : "";
+
+      // Pad the prefix to ensure consistent alignment (12 characters total including brackets)
+      const paddedPrefix = prefix.padEnd(12);
+      const prefixWithColor =
+        data.prefixColor && prefix
+          ? colorize(paddedPrefix, data.prefixColor as ColorName)
+          : paddedPrefix;
+
+      const resource = data.resource ? colorize(data.resource, "gray") : "";
+      const message = data.message;
+
+      if (prefixWithColor && resource) {
+        console.log(`${prefixWithColor}${resource} ${message}`);
+      } else if (prefixWithColor) {
+        console.log(`${prefixWithColor}${message}`);
+      } else {
+        console.log(`${message}`);
+      }
+    },
+    exit: () => {},
+  };
+};
+
+export const formatFQN = (fqn: string) => fqn.split("/").slice(2).join(" > ");

package/src/util/logger.ts

@@ -1,5 +1,5 @@
 import { Scope } from "../scope.ts";
-import type { LoggerApi } from "./cli.tsx";
+import type { LoggerApi } from "./cli.ts";
 
 export const logger = new Proxy({} as LoggerApi, {
   get: (_, prop: keyof LoggerApi) => {

package/src/util/telemetry/client.ts

@@ -51,7 +51,7 @@ export class TelemetryClient implements ITelemetryClient {
 
   record(event: Telemetry.EventInput, timestamp = Date.now()) {
     if (!this.context) {
-      throw new Error("Context not initialized");
+      return;
     }
     const payload = {
       ...event,

package/src/util/cli.tsx

@@ -1,221 +0,0 @@
-import { Box, render, Static, Text, useApp } from "ink";
-import Spinner from "ink-spinner";
-import { format } from "node:util";
-import { useCallback, useEffect, useRef, useState } from "react";
-import packageJson from "../../package.json" with { type: "json" };
-import type { Phase } from "../alchemy.ts";
-import { dedent } from "./dedent.ts";
-
-export type Color = Parameters<typeof Text>[0]["color"];
-export type Task = {
-  prefix?: string;
-  prefixColor?: Color;
-  resource?: string;
-  message: string;
-  status?: "pending" | "success" | "failure";
-};
-
-export type LogMessage = {
-  id: number;
-  text: string;
-};
-
-export type LoggerApi = {
-  log: (...args: unknown[]) => void;
-  warn: (...args: unknown[]) => void;
-  error: (...args: unknown[]) => void;
-  task: (id: string, data: Task) => void;
-  exit: () => void;
-};
-
-type AlchemyInfo = {
-  phase: Phase;
-  stage: string;
-  appName: string;
-};
-
-type LoggerCLIProps = {
-  alchemyInfo: AlchemyInfo;
-  setLogger: (logger: LoggerApi) => void;
-};
-
-export function LoggerCLI({ alchemyInfo, setLogger }: LoggerCLIProps) {
-  const [logs, setLogs] = useState<LogMessage[]>([{ id: 0, text: "#heading" }]);
-  const [tasks, setTasks] = useState<Map<string, Task>>(new Map());
-  const { exit } = useApp();
-  let nextId = useRef(1);
-
-  const log = useCallback(
-    (...args: unknown[]) =>
-      setLogs((prev) => [
-        ...prev,
-        { id: nextId.current++, text: format(...args) },
-      ]),
-    [],
-  );
-
-  const task = useCallback((id: string, data: Task) => {
-    setTasks((prev) => {
-      prev.set(id, data);
-      return prev;
-    });
-  }, []);
-
-  useEffect(() => {
-    setLogger({
-      log: log,
-      warn: log,
-      error: log,
-      task: task,
-      exit: () => exit(),
-    });
-
-    return () => {
-      setTasks(new Map());
-      setLogs([]);
-    };
-  }, [exit, log, setLogger, task]);
-
-  return (
-    <>
-      <Static items={logs}>
-        {(log) => {
-          if (log.id === 0) {
-            return (
-              <Box flexDirection="column" key={log.text}>
-                <Box flexDirection="column" borderStyle="round" padding={1}>
-                  <Text color="green" bold>
-                    Alchemy (v{packageJson.version})
-                  </Text>
-                  <Text color="gray" bold>
-                    App:{" "}
-                    <Text color="magenta" bold={false}>
-                      {alchemyInfo.appName}
-                    </Text>
-                  </Text>
-                  <Text color="gray" bold>
-                    Phase:{" "}
-                    <Text color="magenta" bold={false}>
-                      {alchemyInfo.phase}
-                    </Text>
-                  </Text>
-                  <Text color="gray" bold>
-                    Stage:{" "}
-                    <Text color="magenta" bold={false}>
-                      {alchemyInfo.stage}
-                    </Text>
-                  </Text>
-                </Box>
-                <Text color="green" bold>
-                  Logs
-                </Text>
-              </Box>
-            );
-          }
-
-          return (
-            <Text color="gray" key={log.id} wrap="wrap">
-              {log.text}
-            </Text>
-          );
-        }}
-      </Static>
-
-      <Box flexDirection="column" marginTop={1}>
-        <Text color="green" bold>
-          Tasks
-        </Text>
-        <Box flexDirection="column" paddingLeft={1}>
-          {Array.from(tasks.entries()).map(([id, task]) => (
-            <Box key={id} flexDirection="row" gap={1}>
-              {!task.status || task.status === "pending" ? (
-                <Spinner />
-              ) : task.status === "success" ? (
-                <Text color="green">✓</Text>
-              ) : (
-                <Text color="red">✗</Text>
-              )}
-
-              {task.prefix && (
-                <Text color={task.prefixColor ?? "white"} bold>
-                  {task.prefix.padStart(9)}
-                </Text>
-              )}
-
-              {task.resource && (
-                <Text color="gray" bold>
-                  [{task.resource}]
-                </Text>
-              )}
-
-              <Text bold>{task.message}</Text>
-            </Box>
-          ))}
-        </Box>
-      </Box>
-    </>
-  );
-}
-
-let loggerApi: LoggerApi | null = null;
-export const createLoggerInstance = (alchemyInfo: AlchemyInfo) => {
-  if (loggerApi) return loggerApi;
-
-  if (
-    process.env.CI ||
-    process.env.USE_FALLBACK_LOGGER ||
-    !process.stdin.isTTY
-  ) {
-    loggerApi = createFallbackLogger(alchemyInfo);
-    return loggerApi;
-  }
-
-  render(
-    <LoggerCLI
-      alchemyInfo={alchemyInfo}
-      setLogger={(logger) => {
-        loggerApi = logger;
-      }}
-    />,
-    {
-      exitOnCtrlC: true,
-    },
-  );
-
-  process.on("SIGINT", () => {
-    loggerApi?.exit();
-    process.exit(0);
-  });
-
-  return loggerApi!;
-};
-
-export const createDummyLogger = (): LoggerApi => {
-  return {
-    log: () => {},
-    error: () => {},
-    warn: () => {},
-    task: () => {},
-    exit: () => {},
-  };
-};
-
-export const createFallbackLogger = (alchemyInfo: AlchemyInfo): LoggerApi => {
-  console.log(dedent`
-    Alchemy (v${packageJson.version})
-    App: ${alchemyInfo.appName}
-    Phase: ${alchemyInfo.phase}
-    Stage: ${alchemyInfo.stage}
-    
-  `);
-
-  return {
-    log: console.log,
-    error: console.error,
-    warn: console.warn,
-    task: () => {},
-    exit: () => {},
-  };
-};
-
-export const formatFQN = (fqn: string) => fqn.split("/").slice(2).join(" > ");