alchemy 0.65.0 → 0.66.0

package/src/apply.ts

@@ -15,6 +15,7 @@ import {
 } from "./resource.ts";
 import type { PendingDeletions } from "./scope.ts";
 import { serialize } from "./serde.ts";
+import type { State } from "./state.ts";
 import { formatFQN } from "./util/cli.ts";
 import { logger } from "./util/logger.ts";
 import type { Telemetry } from "./util/telemetry/index.ts";
@@ -64,16 +65,69 @@ async function _apply<Out extends Resource>(
     }
     if (scope.phase === "read") {
       if (state === undefined) {
-        throw new Error(
-          `Resource "${resource[ResourceFQN]}" not found and running in 'read' phase.`,
-        );
+        if (scope.isSelected === false) {
+          // we are running in a monorepo and are not the selected app
+          if (process.argv.includes("--destroy")) {
+            // if we are trying to destroy a downstream app and this (upstream) app does not have data, then exit
+            process.exit(0);
+          }
+          // if we are in `--deploy`, then poll until state available
+          state = await waitForConsistentState();
+        } else {
+          throw new Error(
+            `Resource "${resource[ResourceFQN]}" not found and running in 'read' phase. Selected(${scope.isSelected})`,
+          );
+        }
+      } else if (scope.isSelected === false) {
+        // we are running in a monorepo and are not the selected app, so we need to wait for the process to be consistent
+        state = await waitForConsistentState();
       }
       scope.telemetryClient.record({
         event: "resource.read",
         resource: resource[ResourceKind],
       });
       return state.output as Awaited<Out>;
+
+      // -> poll until it does not (i.e. when the owner process applies the change and updates the state store)
+      async function waitForConsistentState() {
+        while (true) {
+          if (state === undefined) {
+            // state doesn't exist yet
+          } else if (
+            state.status === "creating" ||
+            state.status === "updating"
+          ) {
+            // no-op
+          } else if (
+            state.status === "deleted" ||
+            state.status === "deleting"
+          ) {
+            // ok something is wrong, the stack should not be being deleted
+            // TODO(sam): better error message
+            throw new Error("Resource is being deleted");
+          } else if (await inputsAreEqual(state)) {
+            // sweet, we've reached a stable state and read can progress
+            return state;
+          }
+          // jitter between 100-300ms
+          const jitter = 100 + Math.random() * 200;
+          await new Promise((resolve) => setTimeout(resolve, jitter));
+          state = await scope.state.get(resource[ResourceID]);
+        }
+      }
+      async function inputsAreEqual(
+        state: State<string, ResourceProps | undefined, Resource<string>>,
+      ) {
+        const oldProps = await serialize(scope, state.props, {
+          encrypt: false,
+        });
+        const newProps = await serialize(scope, props, {
+          encrypt: false,
+        });
+        return JSON.stringify(oldProps) === JSON.stringify(newProps);
+      }
     }
+
     if (state === undefined) {
       state = {
         kind: resource[ResourceKind],
@@ -96,6 +150,7 @@ async function _apply<Out extends Resource>(
       };
       await scope.state.set(resource[ResourceID], state);
     }
+
     const oldOutput = state.output;
 
     const alwaysUpdate =

package/src/cloudflare/bucket.ts

@@ -388,7 +388,7 @@ const _R2Bucket = Resource(
     if (this.phase === "delete") {
       if (props.delete !== false) {
         if (this.output.dev?.id) {
-          await deleteMiniflareBinding("r2", this.output.dev.id);
+          await deleteMiniflareBinding(this.scope, "r2", this.output.dev.id);
         }
         if (props.empty) {
           await emptyBucket(api, bucketName, props);

package/src/cloudflare/bundle/plugin-node-compat.ts

@@ -1,7 +1,7 @@
 import type { Plugin } from "esbuild";
 import type { NodeJSCompatMode } from "miniflare";
 import { relative } from "node:path";
-import chalk from "picocolors";
+import pc from "picocolors";
 import { dedent } from "../../util/dedent.ts";
 import { logger } from "../../util/logger.ts";
 import { NODEJS_MODULES_RE } from "./nodejs-builtin-modules.ts";
@@ -109,6 +109,6 @@ export const esbuildPluginNodeCompatImports = (
 
 function toList(items: string[], absWorkingDir: string | undefined): string {
   return items
-    .map((i) => ` - ${chalk.blue(relative(absWorkingDir ?? "/", i))}`)
+    .map((i) => ` - ${pc.blue(relative(absWorkingDir ?? "/", i))}`)
     .join("\n");
 }

package/src/cloudflare/cloudflare-env-proxy.ts

@@ -1,7 +1,7 @@
 import type { GetPlatformProxyOptions } from "wrangler";
 import {
-  DEFAULT_CONFIG_PATH,
-  DEFAULT_PERSIST_PATH,
+  getDefaultConfigPath,
+  getDefaultPersistPath,
   validateConfigPath,
   validatePersistPath,
 } from "./miniflare/paths.ts";
@@ -26,7 +26,7 @@ export const getPlatformProxyOptions = (
             typeof input.persist === "object" &&
               typeof input.persist.path === "string"
               ? input.persist.path
-              : DEFAULT_PERSIST_PATH,
+              : getDefaultPersistPath(),
           ),
         };
   if (!persist) {
@@ -39,12 +39,12 @@ export const getPlatformProxyOptions = (
   }
   return {
     ...input,
-    configPath: validateConfigPath(input.configPath ?? DEFAULT_CONFIG_PATH),
+    configPath: validateConfigPath(input.configPath ?? getDefaultConfigPath()),
     persist,
     experimental: (input as any).experimental ?? {
       remoteBindings: true,
     },
-  } as any;
+  };
 };
 
 const warned = new Set<string>();

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-09-06";
+export const DEFAULT_COMPATIBILITY_DATE = "2025-09-13";

package/src/cloudflare/d1-database.ts

@@ -283,6 +283,7 @@ const _D1Database = Resource(
           databaseId: dev.id,
           migrationsTable: props.migrationsTable ?? DEFAULT_MIGRATIONS_TABLE,
           migrations: props.migrationsFiles,
+          rootDir: this.scope.rootDir,
         });
       }
       return this({
@@ -301,7 +302,7 @@ const _D1Database = Resource(
 
     if (this.phase === "delete") {
       if (this.output.dev?.id) {
-        await deleteMiniflareBinding("d1", this.output.dev.id);
+        await deleteMiniflareBinding(this.scope, "d1", this.output.dev.id);
       }
       if (props.delete !== false && this.output?.id) {
         await deleteDatabase(api, this.output.id);

package/src/cloudflare/d1-local-migrations.ts

@@ -1,7 +1,8 @@
 import * as mf from "miniflare";
-import path from "node:path";
+import { getDefaultPersistPath } from "./miniflare/paths.ts";
 
 export interface D1LocalMigrationOptions {
+  rootDir: string;
   databaseId: string;
   migrationsTable: string;
   migrations: { id: string; sql: string }[];
@@ -13,15 +14,16 @@ export const applyLocalD1Migrations = async (
   const miniflare = new mf.Miniflare({
     script: "",
     modules: true,
-    defaultPersistRoot: path.join(process.cwd(), ".alchemy/miniflare/v3"), // vite plugin forces /v3 suffix
+    defaultPersistRoot: getDefaultPersistPath(options.rootDir),
     d1Persist: true,
     d1Databases: { DB: options.databaseId },
     log: process.env.DEBUG ? new mf.Log(mf.LogLevel.DEBUG) : undefined,
   });
   try {
     await miniflare.ready;
-    const db: D1Database = await miniflare.getD1Database("DB");
-    const session: D1DatabaseSession = db.withSession("first-primary");
+    // TODO(sam): don't use `any` once prisma is fixed upstream
+    const db: any = await miniflare.getD1Database("DB");
+    const session: any = db.withSession("first-primary");
     await session
       .prepare(
         `CREATE TABLE IF NOT EXISTS ${options.migrationsTable} (
@@ -31,11 +33,13 @@ export const applyLocalD1Migrations = async (
     )`,
       )
       .run();
-    const appliedMigrations = await session
+    const appliedMigrations: {
+      results: { name: string }[];
+    } = await session
       .prepare(
         `SELECT name FROM ${options.migrationsTable} ORDER BY applied_at ASC`,
       )
-      .all<{ name: string }>();
+      .all();
     const insertRecord = session.prepare(
       `INSERT INTO ${options.migrationsTable} (name) VALUES (?)`,
     );

package/src/cloudflare/kv-namespace.ts

@@ -240,7 +240,7 @@ const _KVNamespace = Resource(
 
     if (this.phase === "delete") {
       if (this.output.dev?.id) {
-        await deleteMiniflareBinding("kv", this.output.dev.id);
+        await deleteMiniflareBinding(this.scope, "kv", this.output.dev.id);
       }
       if (this.output.namespaceId && props.delete !== false) {
         await deleteKVNamespace(api, this.output.namespaceId);

package/src/cloudflare/miniflare/delete.ts

@@ -2,11 +2,11 @@ import crypto from "node:crypto";
 import type { RmDirOptions } from "node:fs";
 import fs from "node:fs/promises";
 import path from "pathe";
+import type { Scope } from "../../scope.ts";
 import type { DurableObjectNamespace } from "../durable-object-namespace.ts";
 import type { Workflow } from "../workflow.ts";
-import { DEFAULT_PERSIST_PATH } from "./paths.ts";
+import { getDefaultPersistPath } from "./paths.ts";
 
-const PERSIST_ROOT = path.resolve(DEFAULT_PERSIST_PATH);
 const BINDING_TYPE_KEY = {
   d1: "miniflare-D1DatabaseObject",
   kv: "miniflare-KVNamespaceObject",
@@ -18,8 +18,14 @@ type BindingType = keyof typeof BINDING_TYPE_KEY;
 /**
  * Delete a binding from the miniflare directory.
  */
-export async function deleteMiniflareBinding(type: BindingType, id: string) {
-  const bindingPath = path.join(PERSIST_ROOT, type, BINDING_TYPE_KEY[type]);
+export async function deleteMiniflareBinding(
+  scope: Scope,
+  type: BindingType,
+  id: string,
+) {
+  const persistRoot = path.resolve(getDefaultPersistPath(scope.rootDir));
+
+  const bindingPath = path.join(persistRoot, type, BINDING_TYPE_KEY[type]);
 
   // delete durable object/sqlite files
   const namespaceId = durableObjectNamespaceIdFromName(
@@ -33,29 +39,31 @@ export async function deleteMiniflareBinding(type: BindingType, id: string) {
   await Promise.all(files.map((file) => fs.rm(path.join(bindingPath, file))));
 
   // delete data directory, if present
-  await removeDirectory(path.join(PERSIST_ROOT, type, id), {
+  await removeDirectory(path.join(persistRoot, type, id), {
     recursive: true,
   });
 
   // delete the miniflare directory if it is empty
-  await cleanMiniflareDirectory();
+  await cleanMiniflareDirectory(scope.dotAlchemy);
 }
 
 /**
  * Delete local durable object and workflow data for a given Worker script.
  */
 export async function deleteMiniflareWorkerData(
+  scope: Scope,
   scriptName: string,
   input: {
     durableObjects: DurableObjectNamespace[];
     workflows: Workflow[];
   },
 ) {
+  const persistRoot = path.resolve(getDefaultPersistPath(scope.rootDir));
   await Promise.all(
     input.durableObjects.map((durableObject) =>
       removeDirectory(
         path.join(
-          PERSIST_ROOT,
+          persistRoot,
           "do",
           `${scriptName}-${durableObject.className}`,
         ),
@@ -69,7 +77,7 @@ export async function deleteMiniflareWorkerData(
     input.workflows.map((workflow) =>
       removeDirectory(
         path.join(
-          PERSIST_ROOT,
+          persistRoot,
           "workflows",
           `miniflare-workflows-${workflow.workflowName}`,
         ),
@@ -79,14 +87,14 @@ export async function deleteMiniflareWorkerData(
       ),
     ),
   );
-  await cleanMiniflareDirectory();
+  await cleanMiniflareDirectory(persistRoot);
 }
 
 /**
  * Delete the miniflare directory iff it is empty.
  */
-async function cleanMiniflareDirectory() {
-  const directory = path.resolve(".alchemy/miniflare");
+async function cleanMiniflareDirectory(dotAlchemy: string) {
+  const directory = path.resolve(dotAlchemy, "miniflare");
   const files = await fs
     .readdir(directory, {
       recursive: true,

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

@@ -1,6 +1,7 @@
 import * as miniflare from "miniflare";
 import assert from "node:assert";
 import path from "node:path";
+import { Scope } from "../../scope.ts";
 import { findOpenPort } from "../../util/find-open-port.ts";
 import type { HTTPServer } from "../../util/http.ts";
 import { logger } from "../../util/logger.ts";
@@ -10,7 +11,7 @@ import {
   type MiniflareWorkerInput,
 } from "./build-worker-options.ts";
 import { MiniflareWorkerProxy } from "./miniflare-worker-proxy.ts";
-import { DEFAULT_PERSIST_PATH } from "./paths.ts";
+import { getDefaultPersistPath } from "./paths.ts";
 
 declare global {
   var ALCHEMY_MINIFLARE_CONTROLLER: MiniflareController | undefined;
@@ -25,8 +26,8 @@ export class MiniflareController {
   mutex = new AsyncMutex();
 
   static get singleton() {
-    globalThis.ALCHEMY_MINIFLARE_CONTROLLER ??= new MiniflareController();
-    return globalThis.ALCHEMY_MINIFLARE_CONTROLLER;
+    return (globalThis.ALCHEMY_MINIFLARE_CONTROLLER ??=
+      new MiniflareController());
   }
 
   async add(input: MiniflareWorkerInput) {
@@ -75,14 +76,17 @@ export class MiniflareController {
 
   private async update() {
     return await this.mutex.lock(async () => {
-      const options: miniflare.MiniflareOptions = {
+      const options: miniflare.MiniflareOptions & {
+        workers: miniflare.WorkerOptions[];
+      } = {
         workers: [],
-        defaultPersistRoot: path.resolve(DEFAULT_PERSIST_PATH),
+        defaultPersistRoot: path.resolve(
+          getDefaultPersistPath(Scope.current.rootDir),
+        ),
         unsafeDevRegistryPath: miniflare.getDefaultDevRegistryPath(),
         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,

package/src/cloudflare/miniflare/paths.ts

@@ -1,5 +1,7 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { existsSync, readlinkSync, statSync } from "node:fs";
+import path from "node:path";
+import { ALCHEMY_ROOT } from "../../util/root-dir.ts";
 
 const dynamicImportContext = new AsyncLocalStorage<boolean>();
 
@@ -10,13 +12,15 @@ export const withSkipPathValidation = <T>(callback: () => T) => {
   return dynamicImportContext.run(true, callback);
 };
 
-export const DEFAULT_CONFIG_PATH = ".alchemy/local/wrangler.jsonc";
-export const DEFAULT_PERSIST_PATH = ".alchemy/miniflare/v3";
+export const getDefaultConfigPath = (rootDir: string = process.cwd()) => {
+  return path.join(rootDir, ".alchemy", "local", "wrangler.jsonc");
+};
 
-export const validateConfigPath = (
-  path = DEFAULT_CONFIG_PATH,
-  throws = true,
-) => {
+export const getDefaultPersistPath = (rootDir: string = ALCHEMY_ROOT) => {
+  return path.join(rootDir, ".alchemy", "miniflare", "v3");
+};
+
+export const validateConfigPath = (path: string, throws = true) => {
   if (!existsSync(path)) {
     warnOrThrow(
       `The Wrangler config path, "${path}", could not be found. Please run \`alchemy dev\` or \`alchemy deploy\` to create it.`,
@@ -31,7 +35,7 @@ const DEFAULT_VALIDATE_PERSIST =
   !process.argv.some((arg) => ["build", "prepare", "typegen"].includes(arg));
 
 export const validatePersistPath = (
-  path = DEFAULT_PERSIST_PATH,
+  path: string,
   throws = DEFAULT_VALIDATE_PERSIST,
 ) => {
   try {

package/src/cloudflare/miniflare/symlink-miniflare-state.ts

@@ -0,0 +1,19 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getDefaultPersistPath } from "./paths.ts";
+
+export async function writeMiniflareSymlink(rootDir: string, cwd: string) {
+  const target = path.resolve(getDefaultPersistPath(cwd));
+  await fs.mkdir(target, { recursive: true });
+  if (cwd === process.cwd()) {
+    return;
+  }
+  const persistPath = path.resolve(cwd, getDefaultPersistPath(rootDir));
+  console.log("link", target, persistPath);
+  await fs.mkdir(path.dirname(persistPath), { recursive: true });
+  await fs.symlink(target, persistPath).catch((e) => {
+    if (e.code !== "EEXIST") {
+      throw e;
+    }
+  });
+}

package/src/cloudflare/next.ts

@@ -1,6 +1,6 @@
 import * as fs from "node:fs/promises";
 import path from "node:path";
-import { bold, cyan } from "picocolors";
+import pc from "picocolors";
 import { getPackageManagerRunner } from "../util/detect-package-manager.ts";
 import { exists } from "../util/exists.ts";
 import ignore from "../util/ignore-matcher.ts";
@@ -25,8 +25,8 @@ export async function Nextjs<const B extends Bindings>(
   if (!isIgnored) {
     logger.warn(
       [
-        bold(
-          `The ${cyan("wrangler.jsonc")} file for Next.js ${cyan(`"${id}"`)} is not ignored.`,
+        pc.bold(
+          `The ${pc.cyan("wrangler.jsonc")} file for Next.js ${pc.cyan(`"${id}"`)} is not ignored.`,
         ),
         "This may cause unexpected behavior. Please add the file to your .gitignore.",
       ].join(" "),

package/src/cloudflare/nuxt/plugin.ts

@@ -1,5 +1,10 @@
 import type { CloudflareOptions } from "nitropack/presets/cloudflare/types";
-import { validateConfigPath, validatePersistPath } from "../miniflare/paths.ts";
+import {
+  getDefaultConfigPath,
+  getDefaultPersistPath,
+  validateConfigPath,
+  validatePersistPath,
+} from "../miniflare/paths.ts";
 
 const alchemy = (
   options: Partial<CloudflareOptions> = {},
@@ -7,8 +12,12 @@ const alchemy = (
   return {
     nodeCompat: true,
     dev: {
-      configPath: validateConfigPath(options.dev?.configPath),
-      persistDir: validatePersistPath(options.dev?.persistDir),
+      configPath: validateConfigPath(
+        options.dev?.configPath ?? getDefaultConfigPath(),
+      ),
+      persistDir: validatePersistPath(
+        options.dev?.persistDir ?? getDefaultPersistPath(),
+      ),
       ...options.dev,
     },
     ...options,

package/src/cloudflare/redwood/plugin.ts

@@ -1,10 +1,10 @@
 import { redwood, type RedwoodPluginOptions } from "rwsdk/vite";
 import type { PluginOption } from "vite";
-import { DEFAULT_CONFIG_PATH } from "../miniflare/paths.ts";
+import { getDefaultConfigPath } from "../miniflare/paths.ts";
 import alchemyVite from "../vite/plugin.ts";
 
 const alchemyRedwood = (options?: RedwoodPluginOptions): PluginOption => {
-  const configPath = options?.configPath ?? DEFAULT_CONFIG_PATH;
+  const configPath = options?.configPath ?? getDefaultConfigPath();
   return [
     redwood({
       ...options,

package/src/cloudflare/vite/plugin.ts

@@ -2,7 +2,8 @@ import { cloudflare, type PluginConfig } from "@cloudflare/vite-plugin";
 import path from "node:path";
 import type { PluginOption } from "vite";
 import {
-  DEFAULT_PERSIST_PATH,
+  getDefaultConfigPath,
+  getDefaultPersistPath,
   validateConfigPath,
   validatePersistPath,
 } from "../miniflare/paths.ts";
@@ -12,7 +13,8 @@ const alchemy = (config?: PluginConfig): PluginOption => {
     path: validatePersistPath(
       typeof config?.persistState === "object"
         ? config.persistState.path
-        : DEFAULT_PERSIST_PATH,
+        : // persist path should default to the /.alchemy/miniflare/v3
+          getDefaultPersistPath(),
     ),
   };
   if (typeof persistState === "object" && persistState.path.endsWith("v3")) {
@@ -20,7 +22,10 @@ const alchemy = (config?: PluginConfig): PluginOption => {
   }
   return cloudflare({
     ...config,
-    configPath: validateConfigPath(config?.configPath),
+    configPath: validateConfigPath(
+      // config path doesn't need to be in the root, it can be in the app dir
+      config?.configPath ?? getDefaultConfigPath(),
+    ),
     persistState,
     experimental: config?.experimental ?? {
       remoteBindings: true,

package/src/cloudflare/website.ts

@@ -10,7 +10,7 @@ import { Assets } from "./assets.ts";
 import type { Bindings } from "./bindings.ts";
 import { DEFAULT_COMPATIBILITY_DATE } from "./compatibility-date.gen.ts";
 import { unionCompatibilityFlags } from "./compatibility-presets.ts";
-import { DEFAULT_PERSIST_PATH } from "./miniflare/paths.ts";
+import { writeMiniflareSymlink } from "./miniflare/symlink-miniflare-state.ts";
 import { type AssetsConfig, Worker, type WorkerProps } from "./worker.ts";
 import { WranglerJson, type WranglerJsonSpec } from "./wrangler.json.ts";
 
@@ -267,7 +267,9 @@ export async function Website<B extends Bindings>(
     await fs.writeFile(paths.entrypoint, content);
   }
 
-  await writeMiniflareSymlink(paths.cwd);
+  if (Scope.current.local) {
+    await writeMiniflareSymlink(Scope.current.rootDir, paths.cwd);
+  }
 
   await WranglerJson({
     path: path.relative(paths.cwd, paths.wrangler.path),
@@ -293,6 +295,7 @@ export async function Website<B extends Bindings>(
         ...env,
         ...(typeof build === "object" ? build.env : {}),
         NODE_ENV: "production",
+        ALCHEMY_ROOT: Scope.current.rootDir,
       },
       memoize: typeof build === "object" ? build.memoize : undefined,
     });
@@ -350,20 +353,3 @@ export async function Website<B extends Bindings>(
     dev: url ? { url } : undefined,
   })) as Website<B>;
 }
-
-async function writeMiniflareSymlink(cwd: string) {
-  const target = path.resolve(DEFAULT_PERSIST_PATH);
-  await fs.mkdir(target, { recursive: true });
-
-  if (cwd === process.cwd()) {
-    return;
-  }
-
-  const persistPath = path.resolve(cwd, DEFAULT_PERSIST_PATH);
-  await fs.mkdir(path.dirname(persistPath), { recursive: true });
-  await fs.symlink(target, persistPath).catch((e) => {
-    if (e.code !== "EEXIST") {
-      throw e;
-    }
-  });
-}

package/src/cloudflare/worker.ts

@@ -755,7 +755,9 @@ const _Worker = Resource(
         compatibilityDate,
         compatibilityFlags,
         outdir:
-          props.bundle?.outdir ?? path.join(cwd, ".alchemy", "out", workerName),
+          props.bundle?.outdir ??
+          // the out folder can't be moved to the root of a monorepo, it must be ${cwd} or else miniflare throws a fit
+          path.join(process.cwd(), ".alchemy", "out", workerName),
         sourceMap: "sourceMap" in props ? props.sourceMap : undefined,
       });
 
@@ -812,7 +814,7 @@ const _Worker = Resource(
       if (options.bundle.isOk()) {
         await options.bundle.value.delete?.();
       }
-      await deleteMiniflareWorkerData(options.name, {
+      await deleteMiniflareWorkerData(this.scope, options.name, {
         durableObjects: options.durableObjects,
         workflows: options.workflows,
       });

package/src/cloudflare/wrangler.json.ts

@@ -816,6 +816,7 @@ function processBindings(
         class_name: binding.className,
       });
     } else {
+      console.log("binding", binding);
       // biome-ignore lint/correctness/noVoidTypeReturn: it returns never
       return assertNever(binding);
     }

package/src/scope.ts

@@ -28,6 +28,7 @@ import {
 } from "./util/idempotent-spawn.ts";
 import { logger } from "./util/logger.ts";
 import { AsyncMutex } from "./util/mutex.ts";
+import { ALCHEMY_ROOT } from "./util/root-dir.ts";
 import type { ITelemetryClient } from "./util/telemetry/client.ts";
 
 export class RootScopeStateAttemptError extends Error {
@@ -89,6 +90,20 @@ export interface ScopeOptions extends ProviderCredentials {
    * @default false
    */
   adopt?: boolean;
+  /**
+   * The path to the root directory of the project.
+   *
+   * @default process.cwd()
+   */
+  rootDir?: string;
+  /**
+   * Whether this is the application that was selected with `--app`
+   *
+   * `true` if the application was selected with `--app`
+   * `false` if the application was not selected with `--app`
+   * `undefined` if the program was not run with `--app`
+   */
+  isSelected?: boolean;
 }
 
 /**
@@ -177,7 +192,9 @@ export class Scope {
   public readonly logger: LoggerApi;
   public readonly telemetryClient: ITelemetryClient;
   public readonly dataMutex: AsyncMutex;
+  public readonly rootDir: string;
   public readonly dotAlchemy: string;
+  public readonly isSelected: boolean | undefined;
 
   // Provider credentials for scope-level credential overrides
   public readonly providerCredentials: ProviderCredentials;
@@ -214,17 +231,21 @@ export class Scope {
       logger,
       adopt,
       dotAlchemy,
+      rootDir,
+      isSelected,
       ...providerCredentials
     } = options;
 
-    this.dotAlchemy =
-      dotAlchemy ??
-      this.parent?.dotAlchemy ??
-      path.join(process.cwd(), ".alchemy");
-
     this.scopeName = scopeName;
     this.name = this.scopeName;
     this.parent = parent ?? Scope.getScope();
+    this.rootDir = rootDir ?? this.parent?.rootDir ?? ALCHEMY_ROOT;
+    this.isSelected = isSelected ?? this.parent?.isSelected;
+
+    this.dotAlchemy =
+      dotAlchemy ??
+      this.parent?.dotAlchemy ??
+      path.resolve(this.rootDir, ".alchemy");
 
     // Store provider credentials (TypeScript ensures no conflicts with core options)
     this.providerCredentials = providerCredentials as ProviderCredentials;