alchemy 0.60.2 → 0.62.0

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,6 +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 {
@@ -22,6 +23,10 @@ import {
   createLoggerInstance,
   type LoggerApi,
 } from "./util/cli.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";
@@ -32,7 +37,7 @@ export class RootScopeStateAttemptError extends Error {
   }
 }
 
-export interface ScopeOptions {
+export interface ScopeOptions extends ProviderCredentials {
   stage?: string;
   parent: Scope | undefined;
   scopeName: string;
@@ -64,8 +69,44 @@ export interface ScopeOptions {
    * @default "sequential"
    */
   destroyStrategy?: DestroyStrategy;
+  /**
+   * The telemetry client to use for the scope.
+   *
+   */
   telemetryClient?: ITelemetryClient;
+  /**
+   * The logger to use for the scope.
+   */
   logger?: LoggerApi;
+  /**
+   * The path to the .alchemy directory.
+   *
+   * @default "./.alchemy"
+   */
+  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<{
@@ -140,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;
@@ -154,10 +198,34 @@ export class Scope {
     return this.scopeName;
   }
 
+  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) {
@@ -166,19 +234,23 @@ export class Scope {
         `Scope name "${this.scopeName}" cannot contain double colons`,
       );
     }
+    this.dotAlchemy =
+      options.dotAlchemy ??
+      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()
@@ -188,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.",
@@ -203,19 +275,37 @@ 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();
   }
 
+  public async spawn<
+    E extends ((line: string) => string | undefined) | undefined,
+  >(
+    // TODO(sam): validate uniqueness? Ensure a flat .logs/${id}.log dir? Or nest in scope dirs?
+    id: string,
+    options: Omit<IdempotentSpawnOptions, "log" | "stateFile">,
+  ) {
+    const dotAlchemy = path.join(process.cwd(), ".alchemy");
+    const logsDir = path.join(dotAlchemy, "logs");
+    const pidsDir = path.join(dotAlchemy, "pids");
+
+    const extracted = await idempotentSpawn({
+      log: path.join(logsDir, `${id}.log`),
+      stateFile: path.join(pidsDir, `${id}.pid.json`),
+      ...options,
+    });
+    return extracted as E extends undefined ? undefined : string;
+  }
+
   /**
    * @internal
    */
@@ -419,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)),
@@ -546,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}`,

package/src/util/idempotent-spawn.ts

@@ -0,0 +1,303 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { AsyncMutex } from "./mutex.ts";
+
+export interface IdempotentSpawnOptions {
+  cmd: string;
+  cwd?: string;
+  env?: Record<string, string>;
+  log: string;
+  stateFile?: string;
+  overlapBytes?: number;
+  resume?: boolean;
+  isSameProcess?: (pid: number) => Promise<boolean>;
+  processName?: string;
+  extract?: (line: string) => string | undefined;
+  /**
+   * If true, the child's stdout and stderr will not be mirrored to this process's console.
+   */
+  quiet?: boolean;
+}
+
+/**
+ * Idempotently ensure a long-lived child is running with stdout/stderr -> files,
+ * and mirror those logs to THIS process's console with persisted offsets.
+ *
+ * Use: await ensureLoggedChildAndMirror({ cmd: "vite dev" })
+ */
+export async function idempotentSpawn({
+  cmd,
+  cwd,
+  env,
+  stateFile = "state.json",
+  overlapBytes = 0,
+  resume = false,
+  log = "log.txt",
+  processName,
+  extract,
+  isSameProcess,
+  quiet = false,
+}: IdempotentSpawnOptions): Promise<string | undefined> {
+  if (!processName && !isSameProcess) {
+    processName = cmd.split(" ")[0];
+  }
+
+  const outPath = log;
+  await Promise.all([
+    fsp.mkdir(path.dirname(stateFile), { recursive: true }),
+    fsp.mkdir(path.dirname(log), { recursive: true }),
+  ]);
+
+  const { promise: extracted, resolve: resolveExtracted } =
+    Promise.withResolvers<string | undefined>();
+
+  if (!extract) {
+    resolveExtracted(undefined);
+  }
+
+  await ensureChildRunning();
+
+  const write = quiet
+    ? () => false
+    : (buf: Buffer) => process.stdout.write(buf);
+
+  // Start followers (stdout/stderr) and mirror to this process
+  await followFilePersisted(outPath, {
+    stateKey: `${path.resolve(outPath)}::stdout`,
+    write,
+  });
+
+  return extracted;
+
+  function isPidAlive(pid: number) {
+    if (!pid || Number.isNaN(pid)) return false;
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async function writeJsonAtomic(file: string, data: any) {
+    const dir = path.dirname(file);
+    const tmp = path.join(
+      dir,
+      `.${path.basename(file)}.${process.pid}.${Date.now()}.tmp`,
+    );
+    await fsp.writeFile(tmp, JSON.stringify(data, null, 2), { mode: 0o600 });
+    await fsp.rename(tmp, file); // atomic on POSIX
+  }
+
+  async function readJson(file: string) {
+    try {
+      return JSON.parse(await fsp.readFile(file, "utf8"));
+    } catch {
+      return undefined;
+    }
+  }
+
+  async function spawnLoggedChild() {
+    const out = await fsp.open(outPath, "a");
+
+    // shell:true, NO args — pass a single command string
+    const child = spawn(cmd, {
+      shell: true,
+      cwd,
+      stdio: ["ignore", out.fd, out.fd], // stdout/stderr -> files (OS-level)
+      env,
+      detached: false,
+    });
+
+    // Child now owns dup'd fds; close our handles.
+    await out.close();
+
+    // Persist PID into the shared state file
+    const stateAll = (await readJson(stateFile)) ?? {};
+    stateAll.pid = child.pid;
+    await writeJsonAtomic(stateFile, stateAll);
+    return child;
+  }
+
+  async function ensureChildRunning() {
+    const stateAll = await readJson(stateFile);
+    if (stateAll) {
+      const pid = Number.parseInt(stateAll.pid, 10);
+      if (isPidAlive(pid)) return pid;
+      if (await isSameProcess?.(pid)) return pid;
+      if (processName) {
+        const { default: find } = await import("find-process");
+        const processes = await find("pid", pid);
+        if (processes.length > 1) {
+          console.warn(
+            `Found multiple processes with PID ${pid}, using the first one`,
+          );
+        }
+        if (processes.length > 0) {
+          if (processes[0].name.startsWith(processName)) {
+            return pid;
+          }
+        }
+      }
+    }
+    // not running, let's clear pid and state
+    await Promise.all([
+      fsp.rm(stateFile).catch(() => {}),
+      fsp.rm(log).catch(() => {}),
+    ]);
+    return (await spawnLoggedChild()).pid;
+  }
+
+  // Follow a file from persisted offset and mirror to a sink (stdout/stderr)
+  async function followFilePersisted(
+    logPath: string,
+    {
+      write,
+      chunkSize = 64 * 1024,
+      // tickMs = 100,
+    }: {
+      stateKey: string;
+      write: (buf: Buffer) => boolean;
+      chunkSize?: number;
+      tickMs?: number;
+    },
+  ) {
+    logPath = path.resolve(logPath);
+    let state = (await readJson(stateFile)) ?? {};
+
+    let fh = await fsp.open(logPath, "r");
+    let st = await fh.stat();
+    let ino = Number(st.ino ?? 0);
+    let dev = Number(st.dev ?? 0);
+
+    // Resume policy: if resume is enabled and same file, start at saved offset (with overlap); else start from end.
+    let offset =
+      resume &&
+      state.ino === ino &&
+      state.dev === dev &&
+      typeof state.offset === "number"
+        ? Math.max(0, Math.min(st.size, state.offset - overlapBytes))
+        : st.size;
+
+    let closed = false;
+    const drainMutex = new AsyncMutex();
+
+    // we read the log file and stream in chunks, not lines
+    // so we need to keep track of the remainder of the last line
+    let remainder: string | undefined;
+
+    // if we are resuming, then re-parse the log lines to extract the value
+    if (offset > 0) {
+      // read from start to offset
+      const fullBuffer = Buffer.allocUnsafe(offset);
+      await fh.read({
+        position: 0,
+        buffer: fullBuffer,
+        length: offset,
+      });
+      const content = fullBuffer.toString("utf8");
+      parse(content);
+    }
+
+    await drain();
+
+    const watcher = fs.watch(logPath, async () => {
+      if (closed) return;
+      try {
+        const cur = await fh.stat();
+        const curIno = Number(cur.ino ?? 0);
+        const curDev = Number(cur.dev ?? 0);
+        if (curIno !== ino || curDev !== dev) {
+          // Rotated/replaced: reopen and start at beginning of new file
+          await fh.close().catch(() => {});
+          fh = await fsp.open(logPath, "r");
+          const cur2 = await fh.stat();
+          ino = Number(cur2.ino ?? 0);
+          dev = Number(cur2.dev ?? 0);
+          offset = 0;
+        }
+      } catch {
+        // File might briefly disappear during rotation
+      }
+      await drain();
+    });
+
+    // TODO(sam): do we need this?
+    // const tick = setInterval(() => {
+    //   drain().catch(() => {});
+    // }, tickMs);
+
+    return async function stop() {
+      closed = true;
+      watcher.close();
+      // clearInterval(tick);
+      await fh.close().catch(() => {});
+      await persist();
+    };
+
+    async function persist() {
+      try {
+        const cur = await fh.stat();
+        state = {
+          ...state,
+          offset,
+          ino: Number(cur.ino ?? ino),
+          dev: Number(cur.dev ?? dev),
+          size: cur.size,
+          mtimeMs: cur.mtimeMs,
+        };
+        await writeJsonAtomic(stateFile, state);
+      } catch {
+        // If the file vanished mid-rotation, we'll catch up on the next event.
+      }
+    }
+
+    function parse(content: string) {
+      const lines = content.split("\n");
+      if (extract) {
+        if (lines.length > 0) {
+          remainder = lines[lines.length - 1];
+        }
+        // parse all lines except the last one (which may be a partial line)
+        for (const line of lines.slice(0, -1)) {
+          const extracted = extract(line);
+          if (extracted) {
+            resolveExtracted(extracted);
+            break;
+          }
+        }
+      }
+    }
+
+    function drain() {
+      return drainMutex.lock(async () => {
+        while (true) {
+          const cur = await fh.stat().catch(() => null);
+          if (!cur) break;
+
+          if (cur.size < offset) offset = 0; // truncated
+          const toRead = Math.min(chunkSize, cur.size - offset);
+          if (toRead <= 0) break;
+
+          const { bytesRead, buffer } = await fh.read({
+            position: offset,
+            buffer: Buffer.allocUnsafe(toRead),
+            length: toRead,
+          });
+          if (!bytesRead) break;
+
+          const chunk = buffer.subarray(0, bytesRead);
+
+          // write the newly read content to the stream
+          write(chunk);
+          // parse the previous remainder and the new chunk
+          parse(`${remainder || ""}${chunk.toString("utf8")}`);
+          offset += bytesRead;
+        }
+        await persist();
+      });
+    }
+  }
+}

package/src/util/index.ts

@@ -0,0 +1 @@
+export * from "./safe-fetch.ts";