@sentry/wizard 3.38.0 → 3.40.0

package/src/flutter/flutter-wizard.ts

@@ -0,0 +1,164 @@
+import { WizardOptions } from '../utils/types';
+import * as Sentry from '@sentry/node';
+import * as codetools from './code-tools';
+import * as fs from 'fs';
+import * as path from 'path';
+import { showCopyPasteInstructions } from '../utils/clack-utils';
+import { pubspecSnippetColored, initSnippetColored } from './templates';
+import { fetchSdkVersion } from '../utils/release-registry';
+// @ts-ignore - clack is ESM and TS complains about that. It works though
+import * as clack from '@clack/prompts';
+import chalk from 'chalk';
+
+import {
+  confirmContinueIfNoOrDirtyGitRepo,
+  getOrAskForProjectData,
+  printWelcome,
+} from '../utils/clack-utils';
+
+import { traceStep, withTelemetry } from '../telemetry';
+import { findFile } from './code-tools';
+
+export async function runFlutterWizard(options: WizardOptions): Promise<void> {
+  return withTelemetry(
+    {
+      enabled: options.telemetryEnabled,
+      integration: 'flutter',
+      wizardOptions: options,
+    },
+    () => runFlutterWizardWithTelemetry(options),
+  );
+}
+
+async function runFlutterWizardWithTelemetry(
+  options: WizardOptions,
+): Promise<void> {
+  printWelcome({
+    wizardName: 'Sentry Flutter Wizard',
+    promoCode: options.promoCode,
+  });
+
+  await confirmContinueIfNoOrDirtyGitRepo();
+
+  const { selectedProject, selfHosted, sentryUrl, authToken } =
+    await getOrAskForProjectData(options, 'flutter');
+
+  const projectDir = process.cwd();
+  const pubspecFile = path.join(projectDir, 'pubspec.yaml');
+  if (!fs.existsSync(pubspecFile)) {
+    clack.log.error(
+      `Could not find ${chalk.cyan(
+        'pubspec.yaml',
+      )}. Make sure you run the wizard in the projects root folder.`,
+    );
+    return;
+  }
+
+  // ======== STEP 1. Add sentry_flutter and sentry_dart_plugin to pubspec.yaml ============
+
+  clack.log.step(
+    `Adding ${chalk.bold('Sentry')} to your apps ${chalk.cyan(
+      'pubspec.yaml',
+    )} file.`,
+  );
+
+  const flutterVersion = await fetchSdkVersion('sentry.dart.flutter');
+  const flutterVersionOrAny = flutterVersion ? `^${flutterVersion}` : 'any';
+
+  const pluginVersion = await fetchSdkVersion('sentry.dart.plugin');
+  const pluginVersionOrAny = pluginVersion ? `^${pluginVersion}` : 'any';
+
+  const pubspecPatched = traceStep('Patch pubspec.yaml', () =>
+    codetools.patchPubspec(
+      pubspecFile,
+      flutterVersionOrAny,
+      pluginVersionOrAny,
+      selectedProject.slug,
+      selectedProject.organization.slug,
+    ),
+  );
+  if (!pubspecPatched) {
+    clack.log.warn(
+      `Could not patch ${chalk.cyan(
+        'pubspec.yaml',
+      )}. Add the dependencies to it.`,
+    );
+    await showCopyPasteInstructions(
+      'pubspec.yaml',
+      pubspecSnippetColored(
+        flutterVersionOrAny,
+        pluginVersionOrAny,
+        selectedProject.slug,
+        selectedProject.organization.slug,
+      ),
+      'This ensures the Sentry SDK and plugin can be imported.',
+    );
+  }
+  Sentry.setTag('pubspec-patched', pubspecPatched);
+
+  // ======== STEP 2. Add sentry.properties with auth token ============
+
+  const propertiesAdded = traceStep('Add sentry.properties', () =>
+    codetools.addProperties(pubspecFile, authToken),
+  );
+  if (!propertiesAdded) {
+    clack.log.warn(
+      `We could not add ${chalk.cyan(
+        'sentry.properties',
+      )} file in your project directory in order to provide an auth token for Sentry CLI. You'll have to add it manually, or you can set the SENTRY_AUTH_TOKEN environment variable instead. See https://docs.sentry.io/cli/configuration/#auth-token for more information.`,
+    );
+  } else {
+    clack.log.info(
+      `We created ${chalk.cyan(
+        'sentry.properties',
+      )} file in your project directory in order to provide an auth token for Sentry CLI.\nIt was also added to your ".gitignore" file.\nAt your CI enviroment, you can set the SENTRY_AUTH_TOKEN environment variable instead. See https://docs.sentry.io/cli/configuration/#auth-token for more information.`,
+    );
+  }
+  Sentry.setTag('sentry-properties-added', pubspecPatched);
+
+  // ======== STEP 3. Patch main.dart with setup and a test error snippet ============
+
+  clack.log.step(
+    `Patching ${chalk.cyan('main.dart')} with setup and test error snippet.`,
+  );
+
+  const mainFile = findFile(`${projectDir}/lib`, 'main.dart');
+  const dsn = selectedProject.keys[0].dsn.public;
+  const canEnableProfiling =
+    fs.existsSync(`${projectDir}/ios`) || fs.existsSync(`${projectDir}/macos`);
+
+  const mainPatched = await traceStep('Patch main.dart', () =>
+    codetools.patchMain(mainFile, dsn, canEnableProfiling),
+  );
+  if (!mainPatched) {
+    clack.log.warn(
+      `Could not patch ${chalk.cyan(
+        'main.dart',
+      )} file. Place the following code snippet within the apps main function.`,
+    );
+    await showCopyPasteInstructions(
+      'main.dart',
+      initSnippetColored(dsn),
+      'This ensures the Sentry SDK is ready to capture errors.',
+    );
+  }
+  Sentry.setTag('main-patched', mainPatched);
+
+  // ======== OUTRO ========
+
+  const issuesPageLink = selfHosted
+    ? `${sentryUrl}organizations/${selectedProject.organization.slug}/issues/?project=${selectedProject.id}`
+    : `https://${selectedProject.organization.slug}.sentry.io/issues/?project=${selectedProject.id}`;
+
+  clack.outro(`
+    ${chalk.greenBright('Successfully installed the Sentry Flutter SDK!')}
+    
+    ${chalk.cyan(
+      `You can validate your setup by launching your application and checking Sentry issues page afterwards
+    ${issuesPageLink}`,
+    )}
+    
+    Check out the SDK documentation for further configuration:
+    https://docs.sentry.io/platforms/flutter/
+  `);
+}

package/src/flutter/templates.ts

@@ -0,0 +1,90 @@
+import { makeCodeSnippet } from '../utils/clack-utils';
+
+export const sentryImport = `import 'package:sentry_flutter/sentry_flutter.dart';\n`;
+
+export function pubspecOptions(project: string, org: string): string {
+  return `sentry:
+  upload_debug_symbols: true
+  upload_source_maps: true
+  project: ${project}
+  org: ${org}
+`;
+}
+
+export function sentryProperties(authToken: string): string {
+  return `auth_token=${authToken}`;
+}
+
+export function initSnippet(
+  dsn: string,
+  selectedFeaturesMap: {
+    tracing: boolean;
+    profiling: boolean;
+  },
+  runApp: string,
+): string {
+  let snippet = `await SentryFlutter.init(
+    (options) {
+      options.dsn = '${dsn}';`;
+
+  if (selectedFeaturesMap.tracing) {
+    snippet += `
+      // Set tracesSampleRate to 1.0 to capture 100% of transactions for tracing.
+      // We recommend adjusting this value in production.
+      options.tracesSampleRate = 1.0;`;
+  }
+
+  if (selectedFeaturesMap.profiling && selectedFeaturesMap.tracing) {
+    snippet += `
+      // The sampling rate for profiling is relative to tracesSampleRate
+      // Setting to 1.0 will profile 100% of sampled transactions:
+      options.profilesSampleRate = 1.0;`;
+  }
+
+  snippet += `
+    },
+    appRunner: () => runApp(SentryWidget(child: ${runApp})),
+  );
+  // TODO: Remove this line after sending the first sample event to sentry.
+  await Sentry.captureException(Exception('This is a sample exception.'));`;
+
+  return snippet;
+}
+
+export function pubspecSnippetColored(
+  sentryVersion: string,
+  pluginVersion: string,
+  project: string,
+  org: string,
+): string {
+  const snippet = `dependencies:
+  sentry_flutter: ${sentryVersion}
+
+dev_dependencies:
+  sentry_dart_plugin: ${pluginVersion}
+  
+${pubspecOptions(project, org)}`;
+
+  return makeCodeSnippet(true, (_unchanged, plus, _minus) => {
+    return plus(snippet);
+  });
+}
+
+export function initSnippetColored(dsn: string): string {
+  const snippet = `import 'package:sentry_flutter/sentry_flutter.dart';
+
+Future<void>main() async {
+  await SentryFlutter.init(
+    (options) {
+      options.dsn = '${dsn}';
+      // Set tracesSampleRate to 1.0 to capture 100% of transactions for tracing.
+      // We recommend adjusting this value in production.
+      options.tracesSampleRate = 1.0;
+    },
+    appRunner: () => runApp(SentryWidget(child: YourApp())),
+  )
+}`;
+  return makeCodeSnippet(true, (_unchanged, plus, _minus) => {
+    return plus(snippet);
+  });
+}

package/src/nextjs/nextjs-wizard.ts

@@ -926,7 +926,7 @@ async function createExamplePage(
  * It's valuable enough to for users to justify asking the additional question.
  */
 async function askShouldSetTunnelRoute() {
-  return await traceStep('ask-tunnelRoute-option', async () => {
+  return await traceStep('ask-tunnelRoute-option', async (span) => {
     const shouldSetTunnelRoute = await abortIfCancelled(
       clack.select({
         message:
@@ -953,6 +953,9 @@ async function askShouldSetTunnelRoute() {
       );
     }
 
+    span?.setAttribute('tunnelRoute', shouldSetTunnelRoute);
+    Sentry.setTag('tunnelRoute', shouldSetTunnelRoute);
+
     return shouldSetTunnelRoute;
   });
 }

package/src/run.ts

@@ -5,6 +5,7 @@ import { runReactNativeWizard } from './react-native/react-native-wizard';
 
 import { run as legacyRun } from '../lib/Setup';
 import type { PreselectedProject, WizardOptions } from './utils/types';
+import { runFlutterWizard } from './flutter/flutter-wizard';
 import { runAndroidWizard } from './android/android-wizard';
 import { runAppleWizard } from './apple/apple-wizard';
 import { runNextjsWizard } from './nextjs/nextjs-wizard';
@@ -18,6 +19,7 @@ import type { PackageDotJson } from './utils/package-json';
 
 type WizardIntegration =
   | 'reactNative'
+  | 'flutter'
   | 'ios'
   | 'android'
   | 'cordova'
@@ -100,6 +102,7 @@ export async function run(argv: Args) {
         message: 'What do you want to set up?',
         options: [
           { value: 'reactNative', label: 'React Native' },
+          { value: 'flutter', label: 'Flutter' },
           { value: 'ios', label: 'iOS' },
           { value: 'android', label: 'Android' },
           { value: 'cordova', label: 'Cordova' },
@@ -139,6 +142,10 @@ export async function run(argv: Args) {
       });
       break;
 
+    case 'flutter':
+      await runFlutterWizard(wizardOptions);
+      break;
+
     case 'ios':
       await runAppleWizard(wizardOptions);
       break;

package/src/sourcemaps/sourcemaps-wizard.ts

@@ -267,13 +267,9 @@ export async function configureCI(
     'create-react-app',
   ].includes(selectedTool);
 
-  // some non-cli-based flows also use the .sentryclirc file
-  const usesSentryCliRc = selectedTool === 'nextjs';
-
-  const authTokenFile =
-    isCliBasedFlowTool || usesSentryCliRc
-      ? SENTRY_CLI_RC_FILE
-      : SENTRY_DOT_ENV_FILE;
+  const authTokenFile = isCliBasedFlowTool
+    ? SENTRY_CLI_RC_FILE
+    : SENTRY_DOT_ENV_FILE;
 
   if (!isUsingCI) {
     clack.log.info(

package/src/telemetry.ts

@@ -9,6 +9,7 @@ import {
   setTag,
   startSpan,
   flush,
+  Span,
 } from '@sentry/node';
 import packageJson from '../package.json';
 import { WizardOptions } from './utils/types';
@@ -110,9 +111,12 @@ function createSentryInstance(enabled: boolean, integration: string) {
   return { sentryHub: hub, sentryClient: client };
 }
 
-export function traceStep<T>(step: string, callback: () => T): T {
+export function traceStep<T>(
+  step: string,
+  callback: (span: Span | undefined) => T,
+): T {
   updateProgress(step);
-  return startSpan({ name: step, op: 'wizard.step' }, () => callback());
+  return startSpan({ name: step, op: 'wizard.step' }, (span) => callback(span));
 }
 
 export function updateProgress(step: string) {

package/src/utils/clack-utils.ts

@@ -881,7 +881,8 @@ export async function getOrAskForProjectData(
     | 'javascript-sveltekit'
     | 'apple-ios'
     | 'android'
-    | 'react-native',
+    | 'react-native'
+    | 'flutter',
 ): Promise<{
   sentryUrl: string;
   selfHosted: boolean;
@@ -1043,7 +1044,8 @@ async function askForWizardLogin(options: {
     | 'javascript-sveltekit'
     | 'apple-ios'
     | 'android'
-    | 'react-native';
+    | 'react-native'
+    | 'flutter';
   orgSlug?: string;
   projectSlug?: string;
 }): Promise<WizardProjectData> {
@@ -1096,9 +1098,10 @@ async function askForWizardLogin(options: {
 
   if (!hasSentryAccount) {
     loginUrl.searchParams.set('signup', '1');
-    if (options.platform) {
-      loginUrl.searchParams.set('project_platform', options.platform);
-    }
+  }
+
+  if (options.platform) {
+    loginUrl.searchParams.set('project_platform', options.platform);
   }
 
   if (options.promoCode) {

package/src/utils/package-manager.ts

@@ -9,7 +9,6 @@ import { getPackageDotJson, updatePackageDotJson } from './clack-utils';
 export interface PackageManager {
   name: string;
   label: string;
-  lockFile: string;
   installCommand: string;
   buildCommand: string;
   /* The command that the package manager uses to run a script from package.json */
@@ -22,12 +21,14 @@ export interface PackageManager {
 export const BUN: PackageManager = {
   name: 'bun',
   label: 'Bun',
-  lockFile: 'bun.lockb',
   installCommand: 'bun add',
   buildCommand: 'bun run build',
   runScriptCommand: 'bun run',
   flags: '',
-  detect: () => fs.existsSync(path.join(process.cwd(), BUN.lockFile)),
+  detect: () =>
+    ['bun.lockb', 'bun.lock'].some((lockFile) =>
+      fs.existsSync(path.join(process.cwd(), lockFile)),
+    ),
   addOverride: async (pkgName, pkgVersion): Promise<void> => {
     const packageDotJson = await getPackageDotJson();
     const overrides = packageDotJson.overrides || {};
@@ -44,7 +45,6 @@ export const BUN: PackageManager = {
 export const YARN_V1: PackageManager = {
   name: 'yarn',
   label: 'Yarn V1',
-  lockFile: 'yarn.lock',
   installCommand: 'yarn add',
   buildCommand: 'yarn build',
   runScriptCommand: 'yarn',
@@ -52,7 +52,7 @@ export const YARN_V1: PackageManager = {
   detect: () => {
     try {
       return fs
-        .readFileSync(path.join(process.cwd(), YARN_V1.lockFile), 'utf-8')
+        .readFileSync(path.join(process.cwd(), 'yarn.lock'), 'utf-8')
         .slice(0, 500)
         .includes('yarn lockfile v1');
     } catch (e) {
@@ -76,7 +76,6 @@ export const YARN_V1: PackageManager = {
 export const YARN_V2: PackageManager = {
   name: 'yarn',
   label: 'Yarn V2/3/4',
-  lockFile: 'yarn.lock',
   installCommand: 'yarn add',
   buildCommand: 'yarn build',
   runScriptCommand: 'yarn',
@@ -84,7 +83,7 @@ export const YARN_V2: PackageManager = {
   detect: () => {
     try {
       return fs
-        .readFileSync(path.join(process.cwd(), YARN_V2.lockFile), 'utf-8')
+        .readFileSync(path.join(process.cwd(), 'yarn.lock'), 'utf-8')
         .slice(0, 500)
         .includes('__metadata');
     } catch (e) {
@@ -107,12 +106,11 @@ export const YARN_V2: PackageManager = {
 export const PNPM: PackageManager = {
   name: 'pnpm',
   label: 'PNPM',
-  lockFile: 'pnpm-lock.yaml',
   installCommand: 'pnpm add',
   buildCommand: 'pnpm build',
   runScriptCommand: 'pnpm',
   flags: '--ignore-workspace-root-check',
-  detect: () => fs.existsSync(path.join(process.cwd(), PNPM.lockFile)),
+  detect: () => fs.existsSync(path.join(process.cwd(), 'pnpm-lock.yaml')),
   addOverride: async (pkgName, pkgVersion): Promise<void> => {
     const packageDotJson = await getPackageDotJson();
     const pnpm = packageDotJson.pnpm || {};
@@ -133,12 +131,11 @@ export const PNPM: PackageManager = {
 export const NPM: PackageManager = {
   name: 'npm',
   label: 'NPM',
-  lockFile: 'package-lock.json',
   installCommand: 'npm add',
   buildCommand: 'npm run build',
   runScriptCommand: 'npm run',
   flags: '',
-  detect: () => fs.existsSync(path.join(process.cwd(), NPM.lockFile)),
+  detect: () => fs.existsSync(path.join(process.cwd(), 'package-lock.json')),
   addOverride: async (pkgName, pkgVersion): Promise<void> => {
     const packageDotJson = await getPackageDotJson();
     const overrides = packageDotJson.overrides || {};

package/test/flutter/code-tools.test.ts

@@ -0,0 +1,212 @@
+//@ts-ignore
+import {
+  patchMainContent,
+  getDependenciesLocation,
+  getDevDependenciesLocation,
+  getLastImportLineLocation,
+} from '../../src/flutter/code-tools';
+//@ts-ignore
+import { initSnippet } from '../../src/flutter/templates';
+
+describe('code-tools', () => {
+  const pubspec = `name: flutter_example
+description: An example flutter app.
+version: 1.0.0
+publish_to: 'none' # Remove this line if you wish to publish to pub.dev
+
+environment:
+  sdk: '>=2.17.0 <4.0.0'
+  flutter: '>=3.0.0'
+
+dependencies:
+  flutter:
+    sdk: flutter
+
+dev_dependencies:
+  flutter_lints: ^2.0.0
+`;
+
+  const simpleRunApp = `import 'package:flutter/widgets.dart';
+
+void main() {
+  runApp(const MyApp());
+}
+`;
+
+  const asyncRunApp = `import 'package:flutter/widgets.dart';
+
+void main() {
+  runApp(const MyApp());
+}
+`;
+
+  const selectedFeaturesMap = {
+    tracing: true,
+    profiling: true,
+  };
+
+  const simpleRunAppPatched = `import 'package:flutter/widgets.dart';
+import 'package:sentry_flutter/sentry_flutter.dart';
+
+Future<void> main() async {
+  ${initSnippet('dsn', selectedFeaturesMap, 'const MyApp()')}
+}
+`;
+
+  const paramRunApp = `import 'package:flutter/widgets.dart';
+
+Future<void> main() async {
+  await someFunction();
+  runApp(MyApp(param: SomeParam()));
+  await anotherFunction();
+}
+`;
+
+  const paramRunAppPatched = `import 'package:flutter/widgets.dart';
+import 'package:sentry_flutter/sentry_flutter.dart';
+
+Future<void> main() async {
+  await someFunction();
+  ${initSnippet('dsn', selectedFeaturesMap, 'MyApp(param: SomeParam())')}
+  await anotherFunction();
+}
+`;
+
+  const multilineRunApp = `import 'package:flutter/widgets.dart';
+
+void main() {
+  runApp(
+    MyApp(
+      param: Param(),
+      multi: Another(1),
+      line: await bites(the: "dust"),
+    ),
+  );
+  anotherFunction();
+}
+`;
+
+  const multilineRunAppPatched = `import 'package:flutter/widgets.dart';
+import 'package:sentry_flutter/sentry_flutter.dart';
+
+Future<void> main() async {
+  ${initSnippet(
+    'dsn',
+    selectedFeaturesMap,
+    `
+    MyApp(
+      param: Param(),
+      multi: Another(1),
+      line: await bites(the: "dust"),
+    ),
+  `,
+  )}
+  anotherFunction();
+}
+`;
+
+  describe('patchMainContent', () => {
+    it('wraps simple runApp', () => {
+      expect(patchMainContent('dsn', simpleRunApp, selectedFeaturesMap)).toBe(
+        simpleRunAppPatched,
+      );
+    });
+
+    it('wraps async runApp', () => {
+      expect(patchMainContent('dsn', asyncRunApp, selectedFeaturesMap)).toBe(
+        simpleRunAppPatched,
+      );
+    });
+
+    it('wraps runApp with parameterized app', () => {
+      expect(patchMainContent('dsn', paramRunApp, selectedFeaturesMap)).toBe(
+        paramRunAppPatched,
+      );
+    });
+
+    it('wraps multiline runApp', () => {
+      expect(
+        patchMainContent('dsn', multilineRunApp, selectedFeaturesMap),
+      ).toBe(multilineRunAppPatched);
+    });
+  });
+
+  describe('pubspec', () => {
+    it('returns proper line index for dependencies', () => {
+      expect(getDependenciesLocation(pubspec)).toBe(
+        pubspec.indexOf('  flutter:\n'),
+      );
+    });
+
+    it('returns proper line index for dev-dependencies', () => {
+      expect(getDevDependenciesLocation(pubspec)).toBe(
+        pubspec.indexOf('  flutter_lints: ^2.0.0\n'),
+      );
+    });
+  });
+
+  describe('getLastImportLineLocation', () => {
+    it('returns proper line index', () => {
+      const code =
+        `import 'foo:bar';\n` + `//<insert-location>\n` + `class X {}`;
+      expect(getLastImportLineLocation(code)).toBe(
+        code.indexOf('//<insert-location>'),
+      );
+    });
+
+    it('returns proper line index when alias import is used', () => {
+      const code =
+        `import 'package:my_library/utils.dart' as utils;\n` +
+        `//<insert-location>\n` +
+        `class X {}`;
+      expect(getLastImportLineLocation(code)).toBe(
+        code.indexOf('//<insert-location>'),
+      );
+    });
+
+    it('returns proper line index when specific parts import is used', () => {
+      const code =
+        `import 'dart:math' show pi, sin;\n` +
+        `//<insert-location>\n` +
+        `class X {}`;
+      expect(getLastImportLineLocation(code)).toBe(
+        code.indexOf('//<insert-location>'),
+      );
+    });
+
+    it('returns proper line index when hide import is used', () => {
+      const code =
+        `import 'dart:math' hide Random;\n` +
+        `//<insert-location>\n` +
+        `class X {}`;
+      expect(getLastImportLineLocation(code)).toBe(
+        code.indexOf('//<insert-location>'),
+      );
+    });
+
+    it('returns proper line index when deferred import is used', () => {
+      const code =
+        `import 'package:my_library/large_library.dart' deferred as largeLibrary;\n` +
+        `//<insert-location>\n` +
+        `class X {}`;
+      expect(getLastImportLineLocation(code)).toBe(
+        code.indexOf('//<insert-location>'),
+      );
+    });
+
+    it('returns proper line index when multiple imports (with newlines) are present', () => {
+      const code =
+        `import 'foo:bar';\n` +
+        `import 'package:my_library/utils.dart' as utils;\n` +
+        `import 'dart:math' show pi, sin;\n` +
+        `import 'dart:math' hide Random;\n` +
+        `\n` +
+        `import 'package:my_library/large_library.dart' deferred as largeLibrary;\n` +
+        `//<insert-location>\n` +
+        `class X {}`;
+      expect(getLastImportLineLocation(code)).toBe(
+        code.indexOf('//<insert-location>'),
+      );
+    });
+  });
+});