alchemy 0.61.0 → 0.62.0

package/src/cloudflare/website.ts

@@ -1,15 +1,11 @@
 import assert from "node:assert";
-import { spawn } from "node:child_process";
-import { once } from "node:events";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { alchemy } from "../alchemy.ts";
 import { Exec } from "../os/index.ts";
 import { Scope } from "../scope.ts";
-import { isSecret, type Secret } from "../secret.ts";
+import { isSecret } from "../secret.ts";
 import { dedent } from "../util/dedent.ts";
-import { DeferredPromise } from "../util/deferred-promise.ts";
-import { exists } from "../util/exists.ts";
 import { logger } from "../util/logger.ts";
 import { Assets } from "./assets.ts";
 import type { Bindings } from "./bindings.ts";
@@ -304,14 +300,38 @@ export async function Website<B extends Bindings>(
 
     let url: string | undefined;
     if (dev && scope.local) {
-      url = await runDevCommand(scope, {
-        id,
-        command: typeof dev === "string" ? dev : dev.command,
+      url = await scope.spawn(name, {
+        cmd: typeof dev === "string" ? dev : dev.command,
+        cwd: paths.cwd,
+        extract: (line) => {
+          const URL_REGEX =
+            /http:\/\/(localhost|0\.0\.0\.0|127\.0\.0\.1|\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}):\d+\/?/;
+          const match = line
+            .replace(/\x1B\[[0-9;]*[a-zA-Z]/g, "")
+            .match(URL_REGEX);
+          if (match) {
+            return match[0];
+          }
+        },
         env: {
-          ...env,
+          ...Object.fromEntries(
+            Object.entries(env ?? {}).flatMap(([key, value]) => {
+              if (isSecret(value)) {
+                return [[key, value.unencrypted]];
+              }
+              if (typeof value === "string") {
+                return [[key, value]];
+              }
+              return [];
+            }),
+          ),
           ...(typeof dev === "object" ? dev.env : {}),
+          FORCE_COLOR: "1",
+          ...process.env,
+          // NOTE: we must set this to ensure the user does not accidentally set `NODE_ENV=production`
+          // which breaks `vite dev` (it won't, for example, re-write `process.env.TSS_APP_BASE` in the `.js` client side bundle)
+          NODE_ENV: "development",
         },
-        cwd: paths.cwd,
       });
     }
 
@@ -348,104 +368,3 @@ async function writeMiniflareSymlink(cwd: string) {
     }
   });
 }
-
-async function runDevCommand(
-  scope: Scope,
-  props: {
-    id: string;
-    command: string;
-    env: Record<string, string | Secret<string> | undefined>;
-    cwd?: string;
-  },
-) {
-  const persistFile = path.join(process.cwd(), ".alchemy", `${props.id}.pid`);
-  if (await exists(persistFile)) {
-    const pid = Number.parseInt(await fs.readFile(persistFile, "utf8"));
-    try {
-      // Actually kill the process if it's alive
-      process.kill(pid, "SIGTERM");
-    } catch {
-      // ignore
-    }
-    try {
-      await fs.unlink(persistFile);
-    } catch {
-      // ignore
-    }
-  }
-  const command = props.command.split(" ");
-  const [cmd, ...args] = command;
-
-  const childProcess = spawn(cmd, args, {
-    cwd: props.cwd,
-    shell: true,
-    env: {
-      FORCE_COLOR: "1",
-      ...process.env,
-      ...Object.fromEntries(
-        Object.entries(props.env ?? {}).flatMap(([key, value]) => {
-          if (isSecret(value)) {
-            return [[key, value.unencrypted]];
-          }
-          if (typeof value === "string") {
-            return [[key, value]];
-          }
-          return [];
-        }),
-      ),
-      // NOTE: we must set this to ensure the user does not accidentally set `NODE_ENV=production`
-      // which breaks `vite dev` (it won't, for example, re-write `process.env.TSS_APP_BASE` in the `.js` client side bundle)
-      NODE_ENV: "development",
-    },
-    stdio: "pipe",
-  });
-  await once(childProcess, "spawn");
-  scope.onCleanup(async () => {
-    if (childProcess.exitCode === null && !childProcess.killed) {
-      childProcess.kill("SIGTERM");
-      await Promise.any([
-        once(childProcess, "exit"),
-        new Promise((resolve) => setTimeout(resolve, 5000)),
-      ]);
-      if (!childProcess.killed) {
-        childProcess.kill("SIGKILL");
-      }
-    }
-    try {
-      await fs.unlink(persistFile);
-    } catch {
-      // ignore
-    }
-  });
-  if (childProcess.pid) {
-    await fs.mkdir(path.dirname(persistFile), { recursive: true });
-    await fs.writeFile(persistFile, childProcess.pid.toString());
-  }
-  const URL_REGEX =
-    /http:\/\/(?:(?:localhost|0\.0\.0\.0|127\.0\.0\.1)|(?:\d{1,3}\.){3}\d{1,3}):\d+(?:\/)?/;
-  const promise = new DeferredPromise<string>();
-  childProcess.stdout.on("data", (data) => {
-    if (promise.status === "pending") {
-      const match = data
-        .toString()
-        .replace(/\x1B\[[0-9;]*[a-zA-Z]/g, "")
-        .match(URL_REGEX);
-      if (match) {
-        promise.resolve(match[0]);
-      }
-    }
-    process.stdout.write(data);
-  });
-  childProcess.stderr.on("data", (data) => {
-    process.stderr.write(data);
-  });
-
-  return await Promise.race([
-    promise.value,
-    once(childProcess, "exit").then(([code, signal]) => {
-      throw new Error(
-        `Dev command "${props.command}" for "${props.id}" failed to start (code: ${code}, signal: ${signal})`,
-      );
-    }),
-  ]);
-}

package/src/cloudflare/worker-bundle.ts

@@ -93,21 +93,22 @@ export namespace WorkerBundle {
     paths: string[],
     format: "esm" | "cjs",
   ): WorkerBundle.Module[] => {
-    return paths.map((path) => {
-      const ext = path.split(".").pop();
+    return paths.map((filePath) => {
+      const normalizedPath = path.normalize(filePath);
+      const ext = normalizedPath.split(".").pop();
       switch (ext) {
         case "js":
-          return { type: format, path };
+          return { type: format, path: normalizedPath };
         case "mjs":
-          return { type: "esm", path };
+          return { type: "esm", path: normalizedPath };
         case "cjs":
-          return { type: "cjs", path };
+          return { type: "cjs", path: normalizedPath };
         case "wasm":
-          return { type: "wasm", path };
+          return { type: "wasm", path: normalizedPath };
         case "map":
-          return { type: "sourcemap", path };
+          return { type: "sourcemap", path: normalizedPath };
         default:
-          return { type: "text", path };
+          return { type: "text", path: normalizedPath };
       }
     });
   };

package/src/cloudflare/worker-tail.ts

@@ -1,4 +1,4 @@
-import kleur from "kleur";
+import pc from "picocolors";
 import { WebSocket } from "ws";
 import { logger } from "../util/logger.ts";
 import type { CloudflareApiResponse } from "./api-response.ts";
@@ -102,7 +102,7 @@ class TailClient {
     });
     ws.on("message", (message) => {
       const data: TailEventMessage = JSON.parse(message.toString());
-      const prefix = kleur.blue(`[${this.id}]`);
+      const prefix = pc.blue(`[${this.id}]`);
       if (data.event && "request" in data.event) {
         // TODO: handle other event types
         const event = data.event;
@@ -110,18 +110,16 @@ class TailClient {
         const status = event.response?.status ?? 500;
         // TODO: make this look nicer
         logger.log(
-          `${prefix} ${kleur.gray(event.request.method)} ${url.pathname} ${kleur.dim(">")} ${status >= 200 && status < 300 ? kleur.green(status) : kleur.red(status)} ${kleur.gray(`(cpu: ${Math.round(data.cpuTime)}ms, wall: ${Math.round(data.wallTime)}ms)`)}`,
+          `${prefix} ${pc.gray(event.request.method)} ${url.pathname} ${pc.dim(">")} ${status >= 200 && status < 300 ? pc.green(status) : pc.red(status)} ${pc.gray(`(cpu: ${Math.round(data.cpuTime)}ms, wall: ${Math.round(data.wallTime)}ms)`)}`,
         );
       }
       for (const log of data.logs) {
-        logger.log(
-          `${prefix} ${kleur.gray(log.level)} ${log.message.join(" ")}`,
-        );
+        logger.log(`${prefix} ${pc.gray(log.level)} ${log.message.join(" ")}`);
       }
       for (const exception of data.exceptions) {
-        const start = `${prefix} ${kleur.red(exception.name)}`;
+        const start = `${prefix} ${pc.red(exception.name)}`;
         logger.log(
-          `${start} ${exception.message}\n${kleur.gray(exception.stack)}`,
+          `${start} ${exception.message}\n${pc.gray(exception.stack)}`,
         );
       }
     });

package/src/resource.ts

@@ -5,6 +5,7 @@ import { Scope as _Scope, type Scope } from "./scope.ts";
 
 declare global {
   var ALCHEMY_PROVIDERS: Map<ResourceKind, Provider<string, any>>;
+  var ALCHEMY_HANDLERS: Map<ResourceKind, ResourceLifecycleHandler>;
   var ALCHEMY_DYNAMIC_RESOURCE_RESOLVERS: DynamicResourceResolver[];
 }
 
@@ -15,6 +16,12 @@ export const PROVIDERS: Map<
   ResourceKind,
   Provider<string, any>
 >());
+const HANDLERS: Map<ResourceKind, ResourceLifecycleHandler> =
+  (globalThis.ALCHEMY_HANDLERS ??= new Map<
+    ResourceKind,
+    ResourceLifecycleHandler
+  >());
+
 const DYNAMIC_RESOURCE_RESOLVERS: DynamicResourceResolver[] =
   (globalThis.ALCHEMY_DYNAMIC_RESOURCE_RESOLVERS ??= []);
 
@@ -132,10 +139,20 @@ export function Resource<
   const Type extends ResourceKind,
   F extends ResourceLifecycleHandler,
 >(type: Type, ...args: [Partial<ProviderOptions>, F] | [F]): Handler<F> {
+  const [options, handler] = args.length === 2 ? args : [undefined, args[0]];
   if (PROVIDERS.has(type)) {
-    throw new Error(`Resource ${type} already exists`);
+    // We want Alchemy to work in a PNPM monorepo environment unfortunately,
+    // global registries do not work because PNPM's symlinks result in multiple
+    // instances of alchemy being loaded even if the package version is the
+    // same (peers do not fix this).
+    // MITIGATION: to ensure that most cases of accidental double-registration
+    // are caught, we're going to check the handler's toString() to see if it's
+    // the same as the previous handler. if it is, we're going to overwrite it.
+    if (HANDLERS.get(type)!.toString() !== handler.toString()) {
+      throw new Error(`Resource ${type} already exists`);
+    }
   }
-  const [options, handler] = args.length === 2 ? args : [undefined, args[0]];
+  HANDLERS.set(type, handler);
 
   type Out = Awaited<ReturnType<F>>;
 

package/src/scope.ts

@@ -1,7 +1,7 @@
-import kleur from "kleur";
 import { AsyncLocalStorage } from "node:async_hooks";
 import path from "node:path";
 import util from "node:util";
+import pc from "picocolors";
 import type { Phase } from "./alchemy.ts";
 import { destroy, destroyAll, DestroyStrategy } from "./destroy.ts";
 import {
@@ -23,7 +23,10 @@ import {
   createLoggerInstance,
   type LoggerApi,
 } from "./util/cli.ts";
-import { idempotentSpawn } from "./util/idempotent-spawn.ts";
+import {
+  idempotentSpawn,
+  type IdempotentSpawnOptions,
+} from "./util/idempotent-spawn.ts";
 import { logger } from "./util/logger.ts";
 import { AsyncMutex } from "./util/mutex.ts";
 import type { ITelemetryClient } from "./util/telemetry/client.ts";
@@ -34,7 +37,7 @@ export class RootScopeStateAttemptError extends Error {
   }
 }
 
-export interface ScopeOptions {
+export interface ScopeOptions extends ProviderCredentials {
   stage?: string;
   parent: Scope | undefined;
   scopeName: string;
@@ -83,6 +86,29 @@ export interface ScopeOptions {
   dotAlchemy?: string;
 }
 
+/**
+ * Base interface for provider credentials that can be extended by each provider.
+ * This allows providers to add their own credential properties without modifying the core scope interface.
+ *
+ * Provider credentials cannot conflict with core ScopeOptions properties.
+ *
+ * Providers can extend this interface using module augmentation:
+ *
+ * @example
+ * ```typescript
+ * // In aws/scope-extensions.ts
+ * declare module "../scope.ts" {
+ *   interface ProviderCredentials {
+ *     aws?: AwsClientProps;
+ *   }
+ * }
+ * ```
+ */
+export interface ProviderCredentials extends Record<string, unknown> {
+  // Provider credentials should not conflict with core scope properties
+  // TypeScript will enforce this at compile time when providers extend this interface
+}
+
 export type PendingDeletions = Array<{
   resource: Resource<string>;
   oldProps?: ResourceProps;
@@ -155,6 +181,9 @@ export class Scope {
   public readonly telemetryClient: ITelemetryClient;
   public readonly dataMutex: AsyncMutex;
 
+  // Provider credentials for scope-level credential overrides
+  public readonly providerCredentials: ProviderCredentials;
+
   private isErrored = false;
   private isSkipped = false;
   private finalized = false;
@@ -172,9 +201,31 @@ export class Scope {
   public readonly dotAlchemy: string;
 
   constructor(options: ScopeOptions) {
-    this.scopeName = options.scopeName;
+    // Extract core scope options first
+    const {
+      scopeName,
+      parent,
+      stage,
+      password,
+      stateStore,
+      quiet,
+      phase,
+      local,
+      watch,
+      force,
+      destroyStrategy,
+      telemetryClient,
+      logger,
+      dotAlchemy,
+      ...providerCredentials
+    } = options;
+
+    this.scopeName = scopeName;
     this.name = this.scopeName;
-    this.parent = options.parent ?? Scope.getScope();
+    this.parent = parent ?? Scope.getScope();
+
+    // Store provider credentials (TypeScript ensures no conflicts with core options)
+    this.providerCredentials = providerCredentials as ProviderCredentials;
 
     const isChild = this.parent !== undefined;
     if (this.scopeName?.includes(":") && isChild) {
@@ -188,18 +239,18 @@ export class Scope {
       this.parent?.dotAlchemy ??
       path.join(process.cwd(), ".alchemy");
 
-    this.stage = options?.stage ?? this.parent?.stage ?? DEFAULT_STAGE;
+    this.stage = stage ?? this.parent?.stage ?? DEFAULT_STAGE;
     this.parent?.children.set(this.scopeName!, this);
-    this.quiet = options.quiet ?? this.parent?.quiet ?? false;
+    this.quiet = quiet ?? this.parent?.quiet ?? false;
     if (this.parent && !this.scopeName) {
       throw new Error("Scope name is required when creating a child scope");
     }
-    this.password = options.password ?? this.parent?.password;
-    const phase = options.phase ?? this.parent?.phase;
-    if (phase === undefined) {
+    this.password = password ?? this.parent?.password;
+    const resolvedPhase = phase ?? this.parent?.phase;
+    if (resolvedPhase === undefined) {
       throw new Error("Phase is required");
     }
-    this.phase = phase;
+    this.phase = resolvedPhase;
 
     this.logger = this.quiet
       ? createDummyLogger()
@@ -209,14 +260,14 @@ export class Scope {
             stage: this.stage,
             appName: this.appName ?? "",
           },
-          options.logger,
+          logger,
         );
 
-    this.local = options.local ?? this.parent?.local ?? false;
-    this.watch = options.watch ?? this.parent?.watch ?? false;
-    this.force = options.force ?? this.parent?.force ?? false;
+    this.local = local ?? this.parent?.local ?? false;
+    this.watch = watch ?? this.parent?.watch ?? false;
+    this.force = force ?? this.parent?.force ?? false;
     this.destroyStrategy =
-      options.destroyStrategy ?? this.parent?.destroyStrategy ?? "sequential";
+      destroyStrategy ?? this.parent?.destroyStrategy ?? "sequential";
     if (this.local) {
       this.logger.warnOnce(
         "Development mode is in beta. Please report any issues to https://github.com/sam-goodwin/alchemy/issues.",
@@ -224,14 +275,13 @@ export class Scope {
     }
 
     this.stateStore =
-      options.stateStore ?? this.parent?.stateStore ?? defaultStateStore;
-    this.telemetryClient =
-      options.telemetryClient ?? this.parent?.telemetryClient!;
+      stateStore ?? this.parent?.stateStore ?? defaultStateStore;
+    this.telemetryClient = telemetryClient ?? this.parent?.telemetryClient!;
     this.state = new InstrumentedStateStore(
       this.stateStore(this),
       this.telemetryClient,
     );
-    if (!options.telemetryClient && !this.parent?.telemetryClient) {
+    if (!telemetryClient && !this.parent?.telemetryClient) {
       throw new Error("Telemetry client is required");
     }
     this.dataMutex = new AsyncMutex();
@@ -242,28 +292,7 @@ export class Scope {
   >(
     // TODO(sam): validate uniqueness? Ensure a flat .logs/${id}.log dir? Or nest in scope dirs?
     id: string,
-    options: {
-      /**
-       * The command to run (e.g. `cloudflared tunnel --url http://localhost:8080`).
-       */
-      cmd: string;
-      /**
-       * Function executed on each line of the process's output (stdout and stderr) to extract a value.
-       */
-      extract?: E;
-      /**
-       * Name of the process - used to check if a PID is a cloudflared process when the parent exits, for resumability
-       */
-      processName?: string;
-      /**
-       * Function to check if a PID is the same process as the one that was spawned.
-       *
-       * Used to check if a PID is a cloudflared process when the parent exits, for resumability.
-       *
-       * One of {@link extract} or {@link processName} must be provided.
-       */
-      isSameProcess?: (pid: number) => Promise<boolean>;
-    },
+    options: Omit<IdempotentSpawnOptions, "log" | "stateFile">,
   ) {
     const dotAlchemy = path.join(process.cwd(), ".alchemy");
     const logsDir = path.join(dotAlchemy, "logs");
@@ -480,6 +509,7 @@ export class Scope {
     if (!this.isErrored && !this.isSkipped) {
       // TODO: need to detect if it is in error
       const resourceIds = await this.state.list();
+
       const aliveIds = new Set(this.resources.keys());
       const orphanIds = Array.from(
         resourceIds.filter((id) => !aliveIds.has(id)),
@@ -607,7 +637,7 @@ export class Scope {
    */
   public async cleanup() {
     if (this.parent || this.cleanups.length === 0) return;
-    this.logger.log(kleur.gray("Exiting..."));
+    this.logger.log(pc.gray("Exiting..."));
     await Promise.allSettled(this.cleanups.map((cleanup) => cleanup()));
   }
 

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

@@ -15,6 +15,7 @@ import type { Scope } from "../scope.ts";
 import type { Secret } from "../secret.ts";
 import { logger } from "../util/logger.ts";
 import { memoize } from "../util/memoize.ts";
+import { safeFetch } from "../util/safe-fetch.ts";
 import { StateStoreProxy } from "./proxy.ts";
 
 export interface CloudflareStateStoreOptions extends CloudflareApiOptions {
@@ -70,7 +71,7 @@ export class CloudflareStateStore extends StateStoreProxy {
         params,
         context: { chain: this.scope.chain },
       };
-      const response = await fetch(url, {
+      const response = await safeFetch(url, {
         method: "POST",
         headers: {
           Authorization: `Bearer ${token}`,