refactor: use prefetch module instead of threading promises

Replace the BgOrgDetection type and promise-threading through
WizardOptions with a simpler warm/consume prefetch module.

init.ts calls warmOrgDetection() to start background work, and
local-ops.ts transparently consumes the cached results via
resolveOrgPrefetched() and listOrgsPrefetched() — no plumbing
needed between the two.

Author: MathurAditya724

src/commands/init.ts

@@ -19,15 +19,14 @@
 
 import path from "node:path";
 import type { SentryContext } from "../context.js";
-import { listOrganizations } from "../lib/api-client.js";
 import { looksLikePath, parseOrgProjectArg } from "../lib/arg-parsing.js";
 import { buildCommand } from "../lib/command.js";
 import { ContextError } from "../lib/errors.js";
-import type { BgOrgDetection } from "../lib/init/types.js";
+import { warmOrgDetection } from "../lib/init/prefetch.js";
 import { runWizard } from "../lib/init/wizard-runner.js";
 import { validateResourceId } from "../lib/input-validation.js";
 import { logger } from "../lib/logger.js";
-import { resolveOrg, resolveProjectBySlug } from "../lib/resolve-target.js";
+import { resolveProjectBySlug } from "../lib/resolve-target.js";
 
 const log = logger.withTag("init");
 
@@ -231,15 +230,11 @@ export const initCommand = buildCommand<
       await resolveTarget(targetArg);
 
     // 5. Start background org detection when org is not yet known.
-    //    These promises run concurrently with the preamble user-interaction
-    //    (experimental confirm, git status check) so the results are ready
-    //    by the time the wizard needs to create a Sentry project.
-    let bgOrgDetection: BgOrgDetection | undefined;
+    //    The prefetch runs concurrently with the preamble, the wizard startup,
+    //    and all early suspend/resume rounds — by the time the wizard needs the
+    //    org (inside createSentryProject), the result is already cached.
     if (!explicitOrg) {
-      bgOrgDetection = {
-        orgPromise: resolveOrg({ cwd: targetDir }).catch(() => null),
-        orgListPromise: listOrganizations().catch(() => []),
-      };
+      warmOrgDetection(targetDir);
     }
 
     // 6. Run the wizard
@@ -251,7 +246,6 @@ export const initCommand = buildCommand<
       team: flags.team,
       org: explicitOrg,
       project: explicitProject,
-      bgOrgDetection,
     });
   },
 });

src/lib/init/local-ops.ts

@@ -9,14 +9,8 @@ import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { isCancel, select } from "@clack/prompts";
-import {
-  createProject,
-  getProject,
-  listOrganizations,
-  tryGetPrimaryDsn,
-} from "../api-client.js";
+import { createProject, getProject, tryGetPrimaryDsn } from "../api-client.js";
 import { ApiError } from "../errors.js";
-import { resolveOrg } from "../resolve-target.js";
 import { resolveOrCreateTeam } from "../resolve-team.js";
 import { buildProjectUrl } from "../sentry-urls.js";
 import { slugify } from "../utils.js";
@@ -25,9 +19,9 @@ import {
   MAX_FILE_BYTES,
   MAX_OUTPUT_BYTES,
 } from "./constants.js";
+import { listOrgsPrefetched, resolveOrgPrefetched } from "./prefetch.js";
 import type {
   ApplyPatchsetPayload,
-  BgOrgDetection,
   CreateSentryProjectPayload,
   DirEntry,
   FileExistsBatchPayload,
@@ -660,26 +654,24 @@ function applyPatchset(
  * Resolve the org slug from local config, env vars, or by listing the user's
  * organizations from the API as a fallback.
  *
- * When `bgDetection` is provided, its pre-started promises are awaited instead
- * of making fresh calls — this eliminates the 2-5 s cold-start DSN scan that
- * would otherwise block here, because the scan was already running in the
- * background during the preamble user-interaction phase.
+ * Uses the prefetch-aware helpers from `./prefetch.ts` — if
+ * {@link warmOrgDetection} was called earlier (by `init.ts`), the results are
+ * already cached and this function returns near-instantly.  Otherwise it falls
+ * back to live calls transparently.
  *
  * @returns The org slug on success, or a {@link LocalOpResult} error to return early.
  */
 async function resolveOrgSlug(
   cwd: string,
-  yes: boolean,
-  bgDetection?: BgOrgDetection
+  yes: boolean
 ): Promise<string | LocalOpResult> {
-  // Use the pre-fetched org detection if available, otherwise run live
-  const resolved = await (bgDetection?.orgPromise ?? resolveOrg({ cwd }));
+  const resolved = await resolveOrgPrefetched(cwd);
   if (resolved) {
     return resolved.org;
   }
 
-  // Fallback: use pre-fetched org list if available, otherwise fetch live
-  const orgs = await (bgDetection?.orgListPromise ?? listOrganizations());
+  // Fallback: list user's organizations from API (prefetch-aware)
+  const orgs = await listOrgsPrefetched();
   if (orgs.length === 0) {
     return {
       ok: false,
@@ -779,11 +771,7 @@ async function createSentryProject(
     if (options.org) {
       orgSlug = options.org;
     } else {
-      const orgResult = await resolveOrgSlug(
-        payload.cwd,
-        options.yes,
-        options.bgOrgDetection
-      );
+      const orgResult = await resolveOrgSlug(payload.cwd, options.yes);
       if (typeof orgResult !== "string") {
         return orgResult;
       }

src/lib/init/prefetch.ts

@@ -0,0 +1,69 @@
+/**
+ * Background Org Detection Prefetch
+ *
+ * Provides a warm/consume pattern for org resolution during `sentry init`.
+ * Call {@link warmOrgDetection} early (before the preamble) to start DSN
+ * scanning and org-list fetching in the background.  Later, call
+ * {@link resolveOrgPrefetched} or {@link listOrgsPrefetched} — they return
+ * the cached result instantly if the background work has finished, or
+ * fall back to a live call if it hasn't been warmed.
+ *
+ * This keeps the hot path (inside the wizard's `createSentryProject`)
+ * free of explicit promise-threading — callers just swap in the
+ * prefetch-aware functions.
+ */
+
+import { listOrganizations } from "../api-client.js";
+import type { ResolvedOrg } from "../resolve-target.js";
+import { resolveOrg } from "../resolve-target.js";
+
+type OrgResult = ResolvedOrg | null;
+type OrgListResult = Array<{ id: string; slug: string; name: string }>;
+
+let orgPromise: Promise<OrgResult> | undefined;
+let orgListPromise: Promise<OrgListResult> | undefined;
+
+/**
+ * Kick off background org detection and org-list fetching.
+ *
+ * Safe to call multiple times — subsequent calls are no-ops.
+ * Errors are silently swallowed so the foreground path can retry.
+ */
+export function warmOrgDetection(cwd: string): void {
+  if (!orgPromise) {
+    orgPromise = resolveOrg({ cwd }).catch(() => null);
+  }
+  if (!orgListPromise) {
+    orgListPromise = listOrganizations().catch(() => []);
+  }
+}
+
+/**
+ * Resolve the org, using the prefetched result if available.
+ * Falls back to a live call when {@link warmOrgDetection} was not called.
+ */
+export function resolveOrgPrefetched(cwd: string): Promise<OrgResult> {
+  if (orgPromise) {
+    return orgPromise;
+  }
+  return resolveOrg({ cwd }).catch(() => null);
+}
+
+/**
+ * List organizations, using the prefetched result if available.
+ * Falls back to a live call when {@link warmOrgDetection} was not called.
+ */
+export function listOrgsPrefetched(): Promise<OrgListResult> {
+  if (orgListPromise) {
+    return orgListPromise;
+  }
+  return listOrganizations().catch(() => []);
+}
+
+/**
+ * Reset prefetch state.  Used by tests to prevent cross-test leakage.
+ */
+export function resetPrefetch(): void {
+  orgPromise = undefined;
+  orgListPromise = undefined;
+}

src/lib/init/types.ts

@@ -4,22 +4,6 @@ export type DirEntry = {
   type: "file" | "directory";
 };
 
-/**
- * Pre-started background promises for org detection.
- *
- * Fired early in the `sentry init` flow (before the preamble user-interaction
- * phase) so that DSN scanning and org-list fetching overlap with the user
- * confirming the experimental warning and git status checks.  When the wizard
- * later needs the org (inside `createSentryProject`), the results are already
- * available — eliminating 2-5 s of cold-start latency.
- */
-export type BgOrgDetection = {
-  /** Resolves to the auto-detected org (from DSN/env/config), or `null` if none found. */
-  orgPromise: Promise<{ org: string; detectedFrom?: string } | null>;
-  /** Resolves to the user's accessible organizations, or `[]` on failure. */
-  orgListPromise: Promise<Array<{ id: string; slug: string; name: string }>>;
-};
-
 export type WizardOptions = {
   directory: string;
   yes: boolean;
@@ -31,8 +15,6 @@ export type WizardOptions = {
   org?: string;
   /** Explicit project name from CLI arg (e.g., "my-app" from "acme/my-app"). Overrides wizard-detected name. */
   project?: string;
-  /** Pre-started org detection promises. Skipped when org is already explicit. */
-  bgOrgDetection?: BgOrgDetection;
 };
 
 // Local-op suspend payloads

test/commands/init.test.ts

@@ -9,10 +9,11 @@
 import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
 import path from "node:path";
 import { initCommand } from "../../src/commands/init.js";
-// biome-ignore lint/performance/noNamespaceImport: spyOn requires object reference
-import * as apiClient from "../../src/lib/api-client.js";
 import { ContextError } from "../../src/lib/errors.js";
 // biome-ignore lint/performance/noNamespaceImport: spyOn requires object reference
+import * as prefetchNs from "../../src/lib/init/prefetch.js";
+import { resetPrefetch } from "../../src/lib/init/prefetch.js";
+// biome-ignore lint/performance/noNamespaceImport: spyOn requires object reference
 import * as wizardRunner from "../../src/lib/init/wizard-runner.js";
 // biome-ignore lint/performance/noNamespaceImport: spyOn requires object reference
 import * as resolveTarget from "../../src/lib/resolve-target.js";
@@ -21,8 +22,7 @@ import * as resolveTarget from "../../src/lib/resolve-target.js";
 let capturedArgs: Record<string, unknown> | undefined;
 let runWizardSpy: ReturnType<typeof spyOn>;
 let resolveProjectSpy: ReturnType<typeof spyOn>;
-let resolveOrgSpy: ReturnType<typeof spyOn>;
-let listOrgsSpy: ReturnType<typeof spyOn>;
+let warmSpy: ReturnType<typeof spyOn>;
 
 const func = (await initCommand.loader()) as unknown as (
   this: {
@@ -49,6 +49,7 @@ const DEFAULT_FLAGS = { yes: true, "dry-run": false } as const;
 
 beforeEach(() => {
   capturedArgs = undefined;
+  resetPrefetch();
   runWizardSpy = spyOn(wizardRunner, "runWizard").mockImplementation(
     (args: Record<string, unknown>) => {
       capturedArgs = args;
@@ -63,21 +64,19 @@ beforeEach(() => {
     org: "resolved-org",
     project: slug,
   }));
-  // Mock resolveOrg and listOrganizations to prevent real DSN scans / API calls
-  // from the background detection promises fired in init's func()
-  resolveOrgSpy = spyOn(resolveTarget, "resolveOrg").mockImplementation(
-    async () => null
-  );
-  listOrgsSpy = spyOn(apiClient, "listOrganizations").mockImplementation(
-    async () => []
+  // Spy on warmOrgDetection to verify it's called/skipped appropriately.
+  // The mock prevents real DSN scans and API calls from the background.
+  warmSpy = spyOn(prefetchNs, "warmOrgDetection").mockImplementation(
+    // biome-ignore lint/suspicious/noEmptyBlockStatements: intentional no-op mock
+    () => {}
   );
 });
 
 afterEach(() => {
   runWizardSpy.mockRestore();
   resolveProjectSpy.mockRestore();
-  resolveOrgSpy.mockRestore();
-  listOrgsSpy.mockRestore();
+  warmSpy.mockRestore();
+  resetPrefetch();
 });
 
 describe("init command func", () => {
@@ -342,55 +341,44 @@ describe("init command func", () => {
   // ── Background org detection ──────────────────────────────────────────
 
   describe("background org detection", () => {
-    test("passes bgOrgDetection when org is not explicit", async () => {
+    test("warms prefetch when org is not explicit", async () => {
       const ctx = makeContext();
       await func.call(ctx, DEFAULT_FLAGS);
-      const bg = capturedArgs?.bgOrgDetection as
-        | { orgPromise: Promise<unknown>; orgListPromise: Promise<unknown> }
-        | undefined;
-      expect(bg).toBeDefined();
-      expect(bg?.orgPromise).toBeInstanceOf(Promise);
-      expect(bg?.orgListPromise).toBeInstanceOf(Promise);
+      expect(warmSpy).toHaveBeenCalledTimes(1);
+      expect(warmSpy).toHaveBeenCalledWith("/projects/app");
     });
 
-    test("fires resolveOrg for background detection", async () => {
-      const ctx = makeContext();
-      await func.call(ctx, DEFAULT_FLAGS);
-      expect(resolveOrgSpy).toHaveBeenCalled();
-    });
-
-    test("fires listOrganizations for background detection", async () => {
-      const ctx = makeContext();
-      await func.call(ctx, DEFAULT_FLAGS);
-      expect(listOrgsSpy).toHaveBeenCalled();
-    });
-
-    test("omits bgOrgDetection when org is explicit", async () => {
+    test("skips prefetch when org is explicit", async () => {
       const ctx = makeContext();
       await func.call(ctx, DEFAULT_FLAGS, "acme/my-app");
-      expect(capturedArgs?.bgOrgDetection).toBeUndefined();
+      expect(warmSpy).not.toHaveBeenCalled();
     });
 
-    test("omits bgOrgDetection when org-only is explicit", async () => {
+    test("skips prefetch when org-only is explicit", async () => {
       const ctx = makeContext();
       await func.call(ctx, DEFAULT_FLAGS, "acme/");
-      expect(capturedArgs?.bgOrgDetection).toBeUndefined();
+      expect(warmSpy).not.toHaveBeenCalled();
     });
 
-    test("passes bgOrgDetection for bare slug (project-search resolves org)", async () => {
-      // Even though resolveProjectBySlug finds an org, the bgDetection
-      // is skipped because explicitOrg is set from the resolved result
+    test("skips prefetch for bare slug (project-search resolves org)", async () => {
       const ctx = makeContext();
       await func.call(ctx, DEFAULT_FLAGS, "my-app");
-      // resolveProjectBySlug returns { org: "resolved-org", project: "my-app" }
-      // so explicitOrg is set → bgOrgDetection should be undefined
-      expect(capturedArgs?.bgOrgDetection).toBeUndefined();
+      // resolveProjectBySlug returns { org: "resolved-org" } → org is known
+      expect(warmSpy).not.toHaveBeenCalled();
     });
 
-    test("passes bgOrgDetection for path-only arg", async () => {
+    test("warms prefetch for path-only arg", async () => {
       const ctx = makeContext();
       await func.call(ctx, DEFAULT_FLAGS, "./subdir");
-      expect(capturedArgs?.bgOrgDetection).toBeDefined();
+      expect(warmSpy).toHaveBeenCalledTimes(1);
+    });
+
+    test("warms prefetch with resolved directory path", async () => {
+      const ctx = makeContext("/projects/app");
+      await func.call(ctx, DEFAULT_FLAGS, "./subdir");
+      expect(warmSpy).toHaveBeenCalledWith(
+        path.resolve("/projects/app", "./subdir")
+      );
     });
   });
 });