fix(init): enable interactive Ink UI for npx/Node via ESM sidecar

Ship the pre-bundled ink-app.js sidecar in the npm package so
`npx sentry@latest init` gets the full interactive Ink UI on Node,
not just LoggingUI.

The text-import-plugin now emits a path string (not an external
require) for the `with { type: "file" }` import in CJS bundles.
`createInkUI` resolves it via import.meta.url and loads the
self-contained ESM sidecar via dynamic import(). The factory no
longer gates on isBunRuntime() — Ink works on both runtimes.

Fixes #937

Author: MathurAditya724

package.json

@@ -66,7 +66,8 @@
   "files": [
     "dist/bin.cjs",
     "dist/index.cjs",
-    "dist/index.d.cts"
+    "dist/index.d.cts",
+    "dist/ink-app.js"
   ],
   "license": "FSL-1.1-Apache-2.0",
   "packageManager": "bun@1.3.13",

script/bundle.ts

@@ -216,18 +216,14 @@ const result = await build({
     "import.meta.url": "import_meta_url",
   },
   // Externalize Node.js built-ins, plus Ink + React + companions.
-  // Ink uses top-level await (in `node_modules/ink/build/reconciler.js`
-  // and `yoga-layout/dist/src/index.js`) which esbuild can't emit in
-  // a CJS bundle, so the packages must stay external for the
-  // npm/Node distribution. The factory in `factory.ts` lazy-imports
-  // the Ink path via `with { type: "file" }` and falls back to
-  // `LoggingUI` on import failure, so a Node user without Ink
-  // installed simply gets the non-TUI flow without a crash.
-  //
-  // The Bun compile (`script/build.ts`) embeds `ink-app.tsx` as a
-  // file resource — at runtime Bun's loader resolves Ink + React
-  // fresh, sidestepping the same CJS-wrapping bug that'd hit if
-  // these were bundled into the binary's pre-compiled JS.
+  // These packages are NOT bundled into the main CJS output because
+  // they use top-level await (esbuild can't emit that in CJS).
+  // Instead, the Ink UI lives in a separate self-contained ESM
+  // sidecar (`dist/ink-app.js`) that the text-import-plugin
+  // pre-bundles with all deps inlined. The main bundle references
+  // the sidecar via a path string and loads it lazily via dynamic
+  // `import()` at runtime. The external list here prevents esbuild
+  // from trying to resolve these packages in the main bundle graph.
   external: [
     "node:*",
     "ink",
@@ -300,18 +296,11 @@ await Bun.write("./dist/index.d.cts", TYPE_DECLARATIONS);
 console.log("  -> dist/bin.cjs (CLI wrapper)");
 console.log("  -> dist/index.d.cts (type declarations)");
 
-// Clean up the `ink-app.js` sidecar that the text-import-plugin
-// drops into `dist/` when it pre-bundles the `with { type: "file" }`
-// import in `src/lib/init/ui/ink-ui.ts`. The npm distribution
-// doesn't run the InkUI factory at all (it's gated to the Bun
-// binary because Ink uses top-level await that we can't bundle
-// into CJS), so the sidecar is unused — removing it just keeps the
-// local `dist/` directory tidy.
-try {
-  await unlink("./dist/ink-app.js");
-} catch {
-  // Sidecar may not exist (e.g. plugin path not exercised) — fine.
-}
+// The `ink-app.js` sidecar (pre-bundled by text-import-plugin) ships
+// with the npm package so `npx sentry@latest init` can load the
+// interactive Ink UI on Node via dynamic import(). The sidecar is
+// self-contained ESM with all deps inlined — no runtime dependencies
+// needed.
 
 // Calculate bundle size (only the main bundle, not source maps)
 const bundleOutput = result.metafile?.outputs["dist/index.cjs"];

script/text-import-plugin.ts

@@ -47,6 +47,7 @@ import { basename, dirname, extname, resolve as resolvePath } from "node:path";
 import { build as esbuildBuild, type Plugin } from "esbuild";
 
 const TEXT_IMPORT_NS = "text-import";
+const FILE_PATH_NS = "file-path-import";
 const ANY_FILTER = /.*/;
 
 /** Extensions that need TypeScript/JSX transpilation before embedding. */
@@ -127,10 +128,24 @@ export const textImportPlugin: Plugin = {
           );
         }
 
+        // For CJS bundles (npm distribution), emit a virtual module that
+        // exports the sidecar filename as a string. The consumer resolves
+        // the full path at runtime using import.meta.url. For ESM bundles
+        // (Bun binary build), mark external so Bun.compile embeds the file.
+        if (build.initialOptions.format === "cjs") {
+          return {
+            path: outFilename,
+            namespace: FILE_PATH_NS,
+          };
+        }
         return { path: `./${outFilename}`, external: true };
       }
       return null;
     });
+    build.onLoad({ filter: ANY_FILTER, namespace: FILE_PATH_NS }, (args) => ({
+      contents: `export default ${JSON.stringify(`./${args.path}`)};`,
+      loader: "js",
+    }));
     build.onLoad({ filter: ANY_FILTER, namespace: TEXT_IMPORT_NS }, (args) => {
       const content = readFileSync(args.path, "utf-8");
       return {

src/lib/init/ui/factory.ts

@@ -16,21 +16,17 @@
  *    context this means the wizard becomes effectively non-interactive
  *    (any prompt aborts), so users hitting this path will need to set
  *    every choice via flags or rely on auto-detection.
- * 3. Running outside the Bun-compiled binary (i.e. on Node) — also
- *    `LoggingUI`. Ink uses top-level await in its reconciler and the
- *    `yoga-layout` dependency, which esbuild can't emit in our CJS
- *    bundle, so the npm distribution can't load Ink at runtime. The
- *    Bun binary embeds Ink + React + ink-app.tsx via
- *    `with { type: "file" }`, sidestepping the bundler entirely. The
- *    npm package's `--help` output and onboarding docs direct users
- *    to the Bun binary for the interactive `sentry init` experience.
- * 4. Default (Bun binary, interactive, no opt-out) — `InkUI`.
+ * 3. Default (interactive, no opt-out) — `InkUI`. Works on both the
+ *    Bun binary (Ink embedded via `with { type: "file" }`) and the
+ *    npm/Node distribution (self-contained ESM sidecar loaded via
+ *    dynamic `import()`). Falls back to `LoggingUI` if the import
+ *    fails for any reason.
  *
  * Implementation history:
  *   - PR 4: replaced `ClackUI` with `OpenTuiUI` as the default.
  *   - This PR: replaced `OpenTuiUI` with `InkUI`. OpenTUI's Zig
- *     bindings added ~10.7 MB to the binary; Ink + React + companions
- *     add a fraction of that and use no native code.
+ *     bindings added ~10.7 MB to the compiled binary; Ink + React +
+ *     companions add a fraction of that and use no native code.
  */
 
 import { LoggingUI } from "./logging-ui.js";
@@ -85,8 +81,8 @@ export function isInteractiveTerminal(): boolean {
 
 /**
  * Returns `true` when the `LoggingUI` should be used — i.e. we're in
- * a non-interactive context, the user opted out of the TUI, the env
- * var override is set, or the runtime can't load Ink.
+ * a non-interactive context, the user opted out of the TUI, or the
+ * env var override is set.
  */
 function shouldUseLogging(opts: UIFactoryOptions): boolean {
   if (process.env.SENTRY_INIT_TUI === "0") {
@@ -101,18 +97,15 @@ function shouldUseLogging(opts: UIFactoryOptions): boolean {
   if (!isInteractiveTerminal()) {
     return true;
   }
-  if (!isBunRuntime()) {
-    return true;
-  }
   return false;
 }
 
 /**
- * Async factory — picks `InkUI` for interactive runs on the Bun
- * binary, otherwise `LoggingUI`. The async form exists because
- * instantiating `InkUI` requires a lazy `import("ink")` (the package
- * isn't bundled into the npm/Node distribution and would fail to
- * resolve if statically imported there).
+ * Async factory — picks `InkUI` for interactive runs, otherwise
+ * `LoggingUI`. Works on both the Bun binary and the npm/Node
+ * distribution (the Ink sidecar is self-contained ESM loaded via
+ * dynamic `import()`). Falls back to `LoggingUI` if the Ink import
+ * fails for any reason.
  *
  * Callers should treat the return value as an `AsyncDisposable` and
  * use `await using ui = await getUIAsync(...)` to guarantee teardown

src/lib/init/ui/ink-ui.ts

@@ -37,11 +37,13 @@
  * process. We close the stream on dispose to release the libuv
  * handle.
  *
- * **Lazy import.** `ink`, `ink-spinner`, and `react` are all
- * dynamically imported by `createInkUI()` so the npm bundle (which
- * excludes them from the bundle graph) never sees the imports at
- * module-load time. This keeps the `LoggingUI` path cheap to
- * instantiate when interactive UI is not needed.
+ * **Lazy import.** The Ink app sidecar (`ink-app.js`) is a
+ * self-contained ESM bundle with all deps (ink, react, yoga-layout)
+ * inlined. It's loaded lazily by `createInkUI()` via dynamic
+ * `import()` so the `LoggingUI` path stays cheap to instantiate
+ * when interactive UI is not needed. On the Bun binary the sidecar
+ * is embedded in `/$bunfs/`; on the npm/Node distribution it ships
+ * as `dist/ink-app.js` alongside the CJS bundle.
  */
 
 import { openSync } from "node:fs";
@@ -170,20 +172,19 @@ function severityForStopCode(code: SpinnerExitCode): LogSeverity {
  * `text-import-plugin` in `script/build.ts` intercepts this during
  * esbuild: it pre-bundles the .tsx source into self-contained JS
  * (stripping TypeScript, inlining local deps and npm packages,
- * injecting a `createRequire` banner for CJS deps), then marks the
- * import external so Bun.compile picks up the resulting .js file.
+ * injecting a `createRequire` banner for CJS deps).
  *
  * Why pre-bundle? Bun's `/$bunfs/` virtual FS uses a JavaScript
  * parser, not TypeScript — raw .tsx fails on `import { type Foo }`.
  * The `/$bunfs/` environment also has no `node_modules`, so all
  * deps (ink, react, local modules) must be inlined.
  *
- * The npm/Node distribution never reaches `createInkUI()` (the
- * factory routes there only on the Bun binary because Ink uses
- * top-level await that esbuild can't emit in our CJS bundle), so
- * the embedded file is unused on Node. We still produce it because
- * the static import is unconditional; the bundle.ts cleanup step
- * `unlink`s the unused sidecar after bundling.
+ * For the Bun binary build (ESM), the import is marked external so
+ * Bun.compile embeds the file. For the npm CJS bundle, the plugin
+ * emits a virtual module that exports the sidecar filename as a
+ * string — `createInkUI` then resolves it relative to the bundle
+ * and loads it via dynamic `import()`. The sidecar ships as
+ * `dist/ink-app.js` in the npm package.
  */
 // @ts-expect-error: `with { type: "file" }` is Bun-specific and not yet typed in @types/bun
 import inkAppPath from "./ink-app.tsx" with { type: "file" };
@@ -213,24 +214,32 @@ function openFreshTtyForInk(): ReadStream | null {
 export async function createInkUI(
   opts: CreateInkUIOptions = {}
 ): Promise<InkUI> {
-  // Import the Ink App sidecar. In compiled binaries the path
-  // points to `/$bunfs/root/ink-app-xxx.js` (pre-bundled by
-  // text-import-plugin). In dev mode it's the raw filesystem path
-  // to `ink-app.tsx`.
+  // Import the Ink App sidecar. Three runtime contexts:
   //
-  // Query-string cache-bust: Bun's module loader caches the
-  // `with { type: "file" }` import result (a path string) under
-  // the same specifier key. A bare `await import(inkAppPath)` in
-  // dev mode returns `{ default: "/abs/path" }` instead of the
-  // module's actual exports. Appending `?bridge=1` forces a
-  // distinct cache key so the .tsx is evaluated as a module.
+  // 1. Bun binary: inkAppPath is "/$bunfs/root/ink-app-xxx.js"
+  //    (embedded by Bun.compile). Import directly — no query string
+  //    (/$bunfs/ doesn't support them).
   //
-  // In compiled binaries the path lives under `/$bunfs/` which
-  // does NOT support query strings (ENOENT). There the cache
-  // collision doesn't occur because Bun.compile resolves the
-  // `with { type: "file" }` import differently.
-  const isEmbedded = inkAppPath.startsWith("/$bunfs/");
-  const importPath = isEmbedded ? inkAppPath : `${inkAppPath}?bridge=1`;
+  // 2. Dev mode (bun run src/bin.ts): inkAppPath is the absolute
+  //    filesystem path to ink-app.tsx. Append ?bridge=1 to bust
+  //    Bun's module cache (otherwise the import returns the path
+  //    string instead of the module's exports).
+  //
+  // 3. Node/npm (npx sentry@latest): inkAppPath is a relative path
+  //    like "./ink-app.js" (emitted by text-import-plugin as a
+  //    string literal). Resolve it to an absolute file:// URL using
+  //    import.meta.url so Node's dynamic import() can load the
+  //    self-contained ESM sidecar from the dist/ directory.
+  let importPath: string;
+  if (inkAppPath.startsWith("/$bunfs/")) {
+    importPath = inkAppPath;
+  } else if (inkAppPath.startsWith("./")) {
+    // Node/npm bundle — resolve relative to the bundle location
+    importPath = new URL(inkAppPath, import.meta.url).href;
+  } else {
+    // Dev mode — absolute filesystem path, cache-bust for Bun
+    importPath = `${inkAppPath}?bridge=1`;
+  }
   const app = (await import(importPath)) as typeof import("./ink-app.js");
 
   const store = new WizardStore({

src/lib/init/ui/types.ts

@@ -5,14 +5,14 @@
  * provide the actual rendering:
  *
  * - `InkUI`       — Ink-based React UI. Default for interactive runs on
- *                   the Bun-compiled binary. Ink is pure JS but uses
- *                   top-level await internally, which esbuild can't emit
- *                   in our CJS npm bundle — so the npm/Node distribution
- *                   falls back to `LoggingUI` instead.
+ *                   both the Bun binary and the npm/Node distribution.
+ *                   The Bun binary embeds Ink via `with { type: "file" }`;
+ *                   the npm package ships a self-contained ESM sidecar
+ *                   (`dist/ink-app.js`) loaded via dynamic `import()`.
  * - `LoggingUI`   — plain stdout/stderr writes for CI, `--yes`, non-TTY
- *                   environments, the npm/Node distribution, and the
- *                   `--no-tui` escape hatch. Prompts throw —
- *                   non-interactive callers must supply defaults.
+ *                   environments, and the `--no-tui` escape hatch.
+ *                   Prompts throw — non-interactive callers must supply
+ *                   defaults.
  *
  * The factory in `factory.ts` picks an implementation per run.
  *

test/lib/init/wizard-runner.test.ts

@@ -775,6 +775,29 @@ describe("runWizard", () => {
 
     expect(spinnerMock.stop).toHaveBeenCalledWith("Using existing project");
   });
+
+  test("shows --yes hint when LoggingUI prompt fails", async () => {
+    const { LoggingUIPromptError } = await import(
+      "../../../src/lib/init/ui/logging-ui.js"
+    );
+    const { ui } = createMockUI();
+    const failingUI: WizardUI = {
+      ...ui,
+      spinner: () => spinnerMock,
+      select: () =>
+        Promise.reject(
+          new LoggingUIPromptError(
+            "select",
+            "This is experimental and will modify files"
+          )
+        ),
+    };
+    getUISpy.mockResolvedValue(failingUI);
+
+    await expect(
+      forceStdinTty(() => runWizard(makeOptions({ yes: false })))
+    ).rejects.toThrow("Run with --yes for non-interactive mode.");
+  });
 });
 
 describe("runWizard — MastraClient lifecycle", () => {