alchemy 0.60.2 → 0.61.0

package/lib/util/idempotent-spawn.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 declare function idempotentSpawn({ cmd, cwd, stateFile, overlapBytes, resume, log, processName, extract, isSameProcess, quiet, }: {
+    cmd: string;
+    cwd?: 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;
+}): Promise<string | undefined>;
+//# sourceMappingURL=idempotent-spawn.d.ts.map

package/lib/util/idempotent-spawn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotent-spawn.d.ts","sourceRoot":"","sources":["../../src/util/idempotent-spawn.ts"],"names":[],"mappings":"AAMA;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,EACpC,GAAG,EACH,GAAG,EACH,SAAwB,EACxB,YAAgB,EAChB,MAAc,EACd,GAAe,EACf,WAAW,EACX,OAAO,EACP,aAAa,EACb,KAAa,GACd,EAAE;IACD,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAC/C;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAwP9B"}

package/lib/util/idempotent-spawn.js

@@ -0,0 +1,218 @@
+import find from "find-process";
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+/**
+ * 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, stateFile = "state.json", overlapBytes = 0, resume = false, log = "log.txt", processName, extract, isSameProcess, quiet = false, }) {
+    if (!processName && !isSameProcess) {
+        throw new Error("Either processName or isSameProcess must be provided to resume a process");
+    }
+    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();
+    if (!extract) {
+        console.warn("No extract function provided, will not return a value. This is probably a bug.");
+        resolveExtracted(undefined);
+    }
+    // ------------------------ helpers ------------------------
+    function isPidAlive(pid) {
+        if (!pid || Number.isNaN(pid))
+            return false;
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async function writeJsonAtomic(file, data) {
+        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) {
+        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: process.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 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) {
+                    return processes[0].name.startsWith(processName);
+                }
+            }
+        }
+        // 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, { write = (buf) => process.stdout.write(buf), chunkSize = 64 * 1024, tickMs = 100, }) {
+        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;
+        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.
+            }
+        }
+        async function drain() {
+            while (true) {
+                const cur = await fh.stat().catch(() => null);
+                if (!cur)
+                    break;
+                if (cur.size < offset)
+                    offset = 0; // truncated
+                if (offset > 0 && extract) {
+                    // read from start to offset
+                    const fullBuffer = Buffer.allocUnsafe(offset);
+                    await fh.read({
+                        position: 0,
+                        buffer: fullBuffer,
+                        length: offset,
+                    });
+                    const content = fullBuffer.toString("utf8");
+                    const lines = content.split("\n");
+                    for (const line of lines) {
+                        const extracted = extract(line);
+                        if (extracted) {
+                            resolveExtracted(extracted);
+                            break;
+                        }
+                    }
+                }
+                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;
+                offset += bytesRead;
+                write(buffer.subarray(0, bytesRead));
+            }
+            await persist();
+        }
+        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();
+        };
+    }
+    // ------------------------ main flow ------------------------
+    await ensureChildRunning();
+    if (!quiet) {
+        const write = quiet
+            ? () => false
+            : (buf) => process.stdout.write(buf);
+        // Start followers (stdout/stderr) and mirror to this process
+        await followFilePersisted(outPath, {
+            stateKey: `${path.resolve(outPath)}::stdout`,
+            write,
+        });
+    }
+    // Return a stopper for this instance's mirroring (child keeps running)
+    return extracted;
+}
+//# sourceMappingURL=idempotent-spawn.js.map

package/lib/util/idempotent-spawn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotent-spawn.js","sourceRoot":"","sources":["../../src/util/idempotent-spawn.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alchemy",
-  "version": "0.60.2",
+  "version": "0.61.0",
   "license": "Apache-2.0",
   "author": "Sam Goodwin <sam@alchemy.run>",
   "homepage": "https://alchemy.run",
@@ -180,6 +180,7 @@
     "execa": "^9.6.0",
     "fast-json-patch": "^3.1.1",
     "fast-xml-parser": "^5.2.5",
+    "find-process": "^2.0.0",
     "glob": "^10.0.0",
     "jszip": "^3.0.0",
     "kleur": "^4.1.5",

package/src/alchemy.ts

@@ -193,6 +193,7 @@ If this is a mistake, you can disable this check by setting the ALCHEMY_CI_STATE
     });
     onExit((code) => {
       root.cleanup().then(() => {
+        code = code === 130 ? 0 : (code ?? 0);
         process.exit(code);
       });
       return true;

package/src/cloudflare/bucket.ts

@@ -5,8 +5,8 @@ import { Scope } from "../scope.ts";
 import { withExponentialBackoff } from "../util/retry.ts";
 import { CloudflareApiError } from "./api-error.ts";
 import {
-  extractCloudflareError,
   extractCloudflareResult,
+  type CloudflareApiErrorPayload,
 } from "./api-response.ts";
 import {
   createCloudflareApi,
@@ -518,11 +518,6 @@ export async function* listObjects(
     `/accounts/${api.accountId}/r2/buckets/${bucketName}/objects?${params.toString()}`,
     { headers: withJurisdiction(props) },
   );
-  if (!response.ok) {
-    throw new Error(
-      `Failed to list objects in bucket "${bucketName}": ${await extractCloudflareError(response)}`,
-    );
-  }
   const json: {
     result: { key: string }[];
     result_info?: {
@@ -530,7 +525,20 @@ export async function* listObjects(
       is_truncated: boolean;
       per_page: number;
     };
+    success: boolean;
+    errors: CloudflareApiErrorPayload[];
   } = await response.json();
+  if (!json.success) {
+    // 10006 indicates that the bucket does not exist, so there are no objects to list
+    if (json.errors.some((e) => e.code === 10006)) {
+      return;
+    }
+    throw new CloudflareApiError(
+      `Failed to list objects in bucket "${bucketName}": ${json.errors.map((e) => `- [${e.code}] ${e.message}${e.documentation_url ? ` (${e.documentation_url})` : ""}`).join("\n")}`,
+      response,
+      json.errors,
+    );
+  }
   for (const object of json.result) {
     yield object.key;
   }

package/src/cloudflare/compatibility-date.gen.ts

@@ -4,4 +4,4 @@
 /**
  * The default Cloudflare Workers compatibility date, set based on the latest workerd release at the time of build.
  */
-export const DEFAULT_COMPATIBILITY_DATE = "2025-08-10";
+export const DEFAULT_COMPATIBILITY_DATE = "2025-08-13";

package/src/cloudflare/d1-migrations.ts

@@ -1,3 +1,4 @@
+import { glob } from "glob";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { logger } from "../util/logger.ts";
@@ -159,11 +160,9 @@ async function migrateLegacySchema(
 export async function listMigrationsFiles(
   migrationsDir: string,
 ): Promise<Array<{ id: string; sql: string }>> {
-  const entries = await Array.fromAsync(
-    fs.glob("**/*.sql", {
-      cwd: migrationsDir,
-    }),
-  );
+  const entries = await glob("**/*.sql", {
+    cwd: migrationsDir,
+  });
 
   const sqlFiles = entries.sort((a: string, b: string) => {
     const aNum = getPrefix(a);

package/src/cloudflare/index.ts

@@ -39,13 +39,14 @@ export * from "./permission-groups.ts";
 export * from "./pipeline.ts";
 export * from "./queue-consumer.ts";
 export * from "./queue.ts";
+export * from "./quick-tunnel.ts";
 export * from "./rate-limit.ts";
 export * from "./react-router/react-router.ts";
 export * from "./redirect-rule.ts";
 export * from "./redwood/redwood.ts";
 export * from "./route.ts";
-export * from "./ruleset.ts";
 export * from "./rule.ts";
+export * from "./ruleset.ts";
 export * from "./secret-key.ts";
 export * from "./secret.ts";
 export * from "./secrets-store.ts";

package/src/cloudflare/miniflare/build-worker-options.ts

@@ -69,9 +69,15 @@ export const buildWorkerOptions = async (
     name: input.name,
     compatibilityDate: input.compatibilityDate,
     compatibilityFlags: input.compatibilityFlags,
-    // TODO: Setting `proxy: true` here causes the following error when connecting via a websocket:
-    // workerd/io/worker.c++:2164: info: uncaught exception; source = Uncaught (in promise); stack = TypeError: Invalid URL string.
-    unsafeDirectSockets: [{ proxy: false }],
+    unsafeDirectSockets: [
+      // This matches the Wrangler configuration by exposing the default handler (e.g. `export default { fetch }`).
+      // However, unlike Wrangler, we set `proxy: false` to avoid the following error when connecting via a websocket:
+      // workerd/io/worker.c++:2164: info: uncaught exception; source = Uncaught (in promise); stack = TypeError: Invalid URL string.
+      {
+        entrypoint: "default",
+        proxy: false,
+      },
+    ],
     containerEngine: {
       localDocker: {
         socketPath:
@@ -164,6 +170,13 @@ export const buildWorkerOptions = async (
           scriptName: binding.scriptName,
           useSQLite: binding.sqlite,
         };
+        // This matches Wrangler configuration for exposing durable objects as an entrypoint.
+        // See https://github.com/cloudflare/workers-sdk/blob/ae0c806087c203da6a3d7da450e8fabe0d81c987/packages/wrangler/src/dev/miniflare/index.ts#L1266
+        options.unsafeDirectSockets!.push({
+          entrypoint: binding.className,
+          serviceName: binding.scriptName,
+          proxy: true,
+        });
         break;
       }
       case "hyperdrive": {

package/src/cloudflare/miniflare/miniflare-controller.ts

@@ -82,6 +82,10 @@ export class MiniflareController {
         log: process.env.DEBUG
           ? new miniflare.Log(miniflare.LogLevel.DEBUG)
           : undefined,
+
+        // This is required to allow websites and other separate processes
+        // to detect Alchemy-managed Durable Objects via the Wrangler dev registry.
+        unsafeDevRegistryDurableObjectProxy: true,
       };
       for (const worker of this.options.values()) {
         options.workers.push(worker);

package/src/cloudflare/quick-tunnel.ts

@@ -0,0 +1,30 @@
+import type { Scope } from "../scope.ts";
+
+/**
+ * Starts a Cloudflare Quick Tunnel to a local server.
+ *
+ * @returns the Local URL and the publicly accessible URL of the Quick Tunnel
+ */
+export const quickTunnel = async (
+  scope: Scope,
+  localUrl = "http://localhost:8080",
+) => ({
+  /**
+   * The URL of the local server.
+   */
+  localUrl,
+  /**
+   * The URL of the publicly accessible Quick Tunnel.
+   */
+  tunnelUrl: await scope.spawn("tunnel", {
+    cmd: `cloudflared tunnel --url ${localUrl}`,
+    // used to check if a PID is a cloudflared process when the parent exits, for resumability
+    processName: "cloudflared",
+    extract: (line) => {
+      const match = line.match(/https:\/\/([^\s]+)\.trycloudflare\.com/);
+      if (match) {
+        return `https://${match[1]}.trycloudflare.com`;
+      }
+    },
+  }),
+});

package/src/cloudflare/sveltekit/plugin.ts

@@ -1,12 +1,12 @@
 import adapter, { type AdapterOptions } from "@sveltejs/adapter-cloudflare";
 import { getPlatformProxyOptions } from "../cloudflare-env-proxy.ts";
 
-const alchemy = (options?: AdapterOptions) => {
-  const platformProxy = getPlatformProxyOptions(options?.platformProxy);
+export default (options?: AdapterOptions) => {
+  const { platformProxy: proxyOptions, ...config } = options ?? {};
+  const platformProxy = getPlatformProxyOptions(proxyOptions);
   return adapter({
     platformProxy,
-    ...options,
+    config: platformProxy.configPath,
+    ...config,
   });
 };
-
-export default alchemy;

package/src/cloudflare/worker-bundle.ts

@@ -1,4 +1,5 @@
 import esbuild from "esbuild";
+import { globIterate } from "glob";
 import { err, ok, type Result } from "neverthrow";
 import fs from "node:fs/promises";
 import path from "pathe";
@@ -222,7 +223,7 @@ export namespace WorkerBundleSource {
       const fileNames = new Set<string>();
       await Promise.all(
         this.globs.map(async (glob) => {
-          for await (const file of fs.glob(glob, { cwd: this.root })) {
+          for await (const file of globIterate(glob, { cwd: this.root })) {
             fileNames.add(file);
           }
         }),

package/src/scope.ts

@@ -1,5 +1,6 @@
 import kleur from "kleur";
 import { AsyncLocalStorage } from "node:async_hooks";
+import path from "node:path";
 import util from "node:util";
 import type { Phase } from "./alchemy.ts";
 import { destroy, destroyAll, DestroyStrategy } from "./destroy.ts";
@@ -22,6 +23,7 @@ import {
   createLoggerInstance,
   type LoggerApi,
 } from "./util/cli.ts";
+import { idempotentSpawn } 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";
@@ -64,8 +66,21 @@ 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;
 }
 
 export type PendingDeletions = Array<{
@@ -154,6 +169,8 @@ export class Scope {
     return this.scopeName;
   }
 
+  public readonly dotAlchemy: string;
+
   constructor(options: ScopeOptions) {
     this.scopeName = options.scopeName;
     this.name = this.scopeName;
@@ -166,6 +183,10 @@ 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.parent?.children.set(this.scopeName!, this);
@@ -216,6 +237,46 @@ export class Scope {
     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: {
+      /**
+       * 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>;
+    },
+  ) {
+    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
    */