nativescript 9.0.0-alpha.2 → 9.0.0-alpha.3

package/lib/controllers/migrate-controller.js

@@ -12,8 +12,12 @@ const helpers_1 = require("../common/helpers");
 const yok_1 = require("../common/yok");
 const temp = require("temp");
 const color_1 = require("../color");
+// const wait: (ms: number) => Promise<void> = (ms: number = 1000) =>
+// 	new Promise((resolve) => setTimeout(resolve, ms));
 class MigrateController extends update_controller_base_1.UpdateControllerBase {
-    constructor($fs, $platformCommandHelper, $platformsDataService, $packageInstallationManager, $packageManager, $pacoteService, $logger, $errors, $pluginsService, $projectDataService, $projectConfigService, $options, $resources, $injector, $settingsService, $staticConfig, $terminalSpinnerService, $projectCleanupService, $projectBackupService, $childProcess) {
+    constructor($fs, $platformCommandHelper, $platformsDataService, $packageInstallationManager, $packageManager, $pacoteService, 
+    // private $androidResourcesMigrationService: IAndroidResourcesMigrationService,
+    $logger, $errors, $pluginsService, $projectDataService, $projectConfigService, $options, $resources, $injector, $settingsService, $staticConfig, $terminalSpinnerService, $projectCleanupService, $projectBackupService, $childProcess) {
         super($fs, $platformCommandHelper, $platformsDataService, $packageInstallationManager, $packageManager, $pacoteService);
         this.$fs = $fs;
         this.$platformCommandHelper = $platformCommandHelper;
@@ -151,15 +155,18 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
             {
                 packageName: "node-sass",
                 replaceWith: "sass",
-                minVersion: "0.0.0",
+                minVersion: "0.0.0", // ignore
                 isDev: true,
+                // shouldRemove: true,
             },
             {
                 packageName: "sass",
-                minVersion: "0.0.0",
+                minVersion: "0.0.0", // ignore
                 desiredVersion: "^1.49.9",
                 isDev: true,
+                // shouldRemove: true,
             },
+            // runtimes
             {
                 packageName: "tns-ios",
                 minVersion: "6.5.3",
@@ -202,8 +209,10 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
                 remainingPlatforms.push(platform);
                 continue;
             }
+            // should only run in loose mode...
             const cachedResult = await this.getCachedShouldMigrate(projectDir, platform);
             this.$logger.trace(`Got cached result for shouldMigrate for platform: ${platform}: ${cachedResult}`);
+            // the cached result is only used if it's false, otherwise we need to check again
             if (cachedResult !== false) {
                 remainingPlatforms.push(platform);
             }
@@ -215,6 +224,7 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
                 loose,
             });
             this.$logger.trace(`Executed shouldMigrate for platforms: ${remainingPlatforms}. Result is: ${shouldMigrate}`);
+            // only cache results if running in loose mode
             if (!shouldMigrate && loose) {
                 for (const remainingPlatform of remainingPlatforms) {
                     await this.setCachedShouldMigrate(projectDir, remainingPlatform);
@@ -241,37 +251,46 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
             platforms,
             loose: loose,
         });
+        // ensure in git repo and require --force if not (for safety)
+        // ensure git branch is clean
         const canMigrate = await this.ensureGitCleanOrForce(projectDir);
         if (!canMigrate) {
             this.spinner.fail("Pre-Migration verification failed");
             return;
         }
         this.spinner.succeed("Pre-Migration verification complete");
+        // back up project files and folders
         this.spinner.info("Backing up project files before migration");
         const backup = await this.backupProject(projectDir);
         this.spinner.succeed("Project files have been backed up");
+        // clean up project files
         this.spinner.info("Cleaning up project files before migration");
         await this.cleanUpProject(projectData);
         this.spinner.succeed("Project files have been cleaned up");
+        // clean up artifacts
         this.spinner.info("Cleaning up old artifacts");
         await this.handleAutoGeneratedFiles(backup, projectData);
         this.spinner.succeed("Cleaned old artifacts");
         const newConfigPath = path.resolve(projectDir, "nativescript.config.ts");
         if (!this.$fs.exists(newConfigPath)) {
+            // migrate configs
             this.spinner.info(`Migrating project to use ${color_1.color.green("nativescript.config.ts")}`);
             await this.migrateConfigs(projectDir);
             this.spinner.succeed(`Project has been migrated to use ${color_1.color.green("nativescript.config.ts")}`);
         }
+        // update dependencies
         this.spinner.info("Updating project dependencies");
         await this.migrateDependencies(projectData, platforms, loose);
         this.spinner.succeed("Project dependencies have been updated");
         const isAngular = this.hasDependency({
             packageName: "@nativescript/angular",
         }, projectData);
+        // ensure polyfills.ts exists in angular projects
         let polyfillsPath;
         if (isAngular) {
             polyfillsPath = await this.checkOrCreatePolyfillsTS(projectData);
         }
+        // update tsconfig
         const tsConfigPath = path.resolve(projectDir, "tsconfig.json");
         if (this.$fs.exists(tsConfigPath)) {
             this.spinner.info(`Updating ${color_1.color.yellow("tsconfig.json")}`);
@@ -283,11 +302,19 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
             this.spinner.succeed(`Updated ${color_1.color.yellow("tsconfig.json")}`);
         }
         await this.migrateWebpack5(projectDir, projectData);
+        // run @nativescript/eslint over codebase
         await this.runESLint(projectDir);
         this.spinner.succeed("Migration complete.");
         this.$logger.info("");
         this.$logger.printMarkdown("Project has been successfully migrated. The next step is to run `ns run <platform>` to ensure everything is working properly." +
             "\n\nPlease note that you may need additional changes to complete the migration.");
+        // print markdown for next steps:
+        // if no runtime has been added, print a message that it will be added when they run ns run <platform>
+        // if all is good, run ns migrate clean to clean up backup folders
+        // in case of failure, print diagnostic data: what failed and why
+        // restore all files - or perhaps let the user sort it out
+        // or ns migrate restore - to restore from pre-migration backup
+        // for some known cases, print suggestions perhaps
     }
     async _shouldMigrate({ projectDir, platforms, loose, }) {
         const isMigrate = _.get(this.$options, "argv._[0]") === "migrate";
@@ -304,6 +331,7 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
                 if (dependency.shouldAddIfMissing) {
                     this.$logger.trace(`${shouldMigrateCommonMessage}'${dependency.packageName}' is missing.`);
                     if (loose) {
+                        // in loose mode we ignore missing dependencies
                         continue;
                     }
                     return true;
@@ -319,6 +347,7 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
             }
             if (dependency.replaceWith || dependency.shouldRemove) {
                 this.$logger.trace(`${shouldMigrateCommonMessage}'${dependency.packageName}' is deprecated.`);
+                // in loose mode we ignore deprecated dependencies
                 if (loose) {
                     continue;
                 }
@@ -361,11 +390,32 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
         const projectPackageJsonFilePath = path.join(projectDir, constants.PACKAGE_JSON_FILE_NAME);
         return await this.$fs.getFileShasum(projectPackageJsonFilePath);
     }
+    // private async migrateOldAndroidAppResources(
+    // 	projectData: IProjectData,
+    // 	backupDir: string
+    // ) {
+    // 	const appResourcesPath = projectData.getAppResourcesDirectoryPath();
+    // 	if (!this.$androidResourcesMigrationService.hasMigrated(appResourcesPath)) {
+    // 		this.spinner.info("Migrate old Android App_Resources structure.");
+    // 		try {
+    // 			await this.$androidResourcesMigrationService.migrate(
+    // 				appResourcesPath,
+    // 				backupDir
+    // 			);
+    // 		} catch (error) {
+    // 			this.$logger.warn(
+    // 				"Migrate old Android App_Resources structure failed: ",
+    // 				error.message
+    // 			);
+    // 		}
+    // 	}
+    // }
     async ensureGitCleanOrForce(projectDir) {
         const git = (0, simple_git_1.default)(projectDir);
         const isGit = await git.checkIsRepo();
         const isForce = this.$options.force;
         if (!isGit) {
+            // not a git repo and no --force
             if (!isForce) {
                 this.$logger.printMarkdown(`Running \`ns migrate\` in a non-git project is not recommended. If you want to skip this check run \`ns migrate --force\`.`);
                 this.$errors.fail("Not in Git repo.");
@@ -412,6 +462,7 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
         const { dependencies, devDependencies } = await this.$pluginsService.getDependenciesFromPackageJson(projectData.projectDir);
         const hasSchematics = [...dependencies, ...devDependencies].find((p) => p.name === "@nativescript/schematics");
         if (!hasSchematics) {
+            // clean tsconfig.tns.json if not in a shared project
             await this.$projectCleanupService.clean([
                 constants.TSCCONFIG_TNS_JSON_NAME,
             ]);
@@ -458,12 +509,14 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
         });
     }
     isOutdatedVersion(current, target, loose) {
+        // in loose mode, a falsy version is not considered outdated
         if (!current && loose) {
             return false;
         }
         const installed = semver.coerce(current);
         const min = semver.coerce(target.minVersion);
         const desired = semver.coerce(target.desiredVersion);
+        // in loose mode we check if we satisfy the min version
         if (loose) {
             if (!installed || !min) {
                 return false;
@@ -473,6 +526,7 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
         if (!installed || !desired) {
             return true;
         }
+        // otherwise we compare with the desired version
         return semver.lt(installed, desired);
     }
     detectAppPath(projectDir, configData) {
@@ -535,6 +589,7 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
     async migrateDependency(dependency, projectData, loose) {
         var _a, _b, _c, _d, _e;
         const hasDependency = this.hasDependency(dependency, projectData);
+        // show warning if needed
         if (hasDependency && dependency.warning) {
             this.$logger.warn(dependency.warning);
         }
@@ -550,7 +605,9 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
             return;
         }
         if (dependency.replaceWith || dependency.shouldRemove) {
+            // remove
             this.$pluginsService.removeFromPackageJson(dependency.packageName, projectData.projectDir);
+            // no replacement required - we're done
             if (!dependency.replaceWith) {
                 return;
             }
@@ -559,6 +616,7 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
                 this.$errors.fail("Failed to find replacement dependency.");
             }
             const version = (_d = (_c = (_b = replacementDep.desiredVersion) !== null && _b !== void 0 ? _b : replacementDep.minVersion) !== null && _c !== void 0 ? _c : dependency.desiredVersion) !== null && _d !== void 0 ? _d : dependency.minVersion;
+            // add replacement dependency
             this.$pluginsService.addToPackageJson(replacementDep.packageName, version, replacementDep.isDev, projectData.projectDir);
             this.spinner.clear();
             this.$logger.info(`  - ${color_1.color.yellow(dependency.packageName)} has been replaced with ${color_1.color.cyan(replacementDep.packageName)} ${color_1.color.green(version)}`);
@@ -578,40 +636,57 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
     }
     async migrateConfigs(projectDir) {
         const projectData = this.$projectDataService.getProjectData(projectDir);
+        // package.json
         const rootPackageJsonPath = path.resolve(projectDir, constants.PACKAGE_JSON_FILE_NAME);
+        // nested package.json
         const embeddedPackageJsonPath = path.resolve(projectData.projectDir, projectData.getAppDirectoryRelativePath(), constants.PACKAGE_JSON_FILE_NAME);
+        // nsconfig.json
         const legacyNsConfigPath = path.resolve(projectData.projectDir, constants.CONFIG_NS_FILE_NAME);
         let rootPackageJsonData = {};
         if (this.$fs.exists(rootPackageJsonPath)) {
             rootPackageJsonData = this.$fs.readJson(rootPackageJsonPath);
         }
+        // write the default config unless it already exists
         const newConfigPath = this.$projectConfigService.writeDefaultConfig(projectData.projectDir);
+        // force legacy config mode
         this.$projectConfigService.setForceUsingLegacyConfig(true);
+        // all different sources are combined into configData (nested package.json, nsconfig and root package.json[nativescript])
         const configData = this.$projectConfigService.readConfig(projectData.projectDir);
+        // we no longer want to force legacy config mode
         this.$projectConfigService.setForceUsingLegacyConfig(false);
+        // move main key into root package.json
         if (configData.main) {
             rootPackageJsonData.main = configData.main;
             delete configData.main;
         }
+        // detect appPath and App_Resources path
         configData.appPath = this.detectAppPath(projectDir, configData);
         configData.appResourcesPath = this.detectAppResourcesPath(projectDir, configData);
+        // delete nativescript key from root package.json
         if (rootPackageJsonData.nativescript) {
             delete rootPackageJsonData.nativescript;
         }
+        // force the config service to use nativescript.config.ts
         this.$projectConfigService.setForceUsingNewConfig(true);
-        const hasUpdatedConfigSuccessfully = await this.$projectConfigService.setValue("", configData);
+        // migrate data into nativescript.config.ts
+        const hasUpdatedConfigSuccessfully = await this.$projectConfigService.setValue("", // root
+        configData);
         if (!hasUpdatedConfigSuccessfully) {
             if (typeof newConfigPath === "string") {
+                // only clean the config if it was created by the migration script
                 await this.$projectCleanupService.cleanPath(newConfigPath);
             }
             this.$errors.fail(`Failed to migrate project to use ${constants.CONFIG_FILE_NAME_TS}. One or more values could not be updated.`);
         }
+        // save root package.json
         this.$fs.writeJson(rootPackageJsonPath, rootPackageJsonData);
+        // delete migrated files
         await this.$projectCleanupService.cleanPath(embeddedPackageJsonPath);
         await this.$projectCleanupService.cleanPath(legacyNsConfigPath);
         return true;
     }
     async migrateUnitTestRunner(projectData, migrationBackupDirPath) {
+        // Migrate karma.conf.js
         const pathToKarmaConfig = path.join(migrationBackupDirPath, constants.KARMA_CONFIG_NAME);
         if (this.$fs.exists(pathToKarmaConfig)) {
             const oldKarmaContent = this.$fs.readText(pathToKarmaConfig);
@@ -629,6 +704,7 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
             });
             this.$fs.writeFile(path.join(projectData.projectDir, constants.KARMA_CONFIG_NAME), karmaConf);
         }
+        // Dependencies to migrate
         const dependencies = [
             {
                 packageName: "karma-webpack",
@@ -670,6 +746,7 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
     async migrateTSConfig({ tsConfigPath, isAngular, polyfillsPath, }) {
         try {
             const configContents = this.$fs.readJson(tsConfigPath);
+            // update
             configContents.compilerOptions = configContents.compilerOptions || {};
             configContents.compilerOptions.target = "es2020";
             configContents.compilerOptions.module = "esnext";
@@ -680,6 +757,7 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
                 ...new Set([...(configContents.compilerOptions.lib || []), "ESNext"]),
             ];
             if (isAngular) {
+                // make sure polyfills.ts is in files
                 if (configContents.files) {
                     configContents.files = [
                         ...new Set([
@@ -713,8 +791,10 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
         const tempDir = temp.mkdirSync({
             prefix: "migrate-angular-polyfills",
         });
+        // get from default angular template
         await this.$pacoteService.extractPackage(constants.RESERVED_TEMPLATE_NAMES["angular"], tempDir);
         this.$fs.copyFile(path.resolve(tempDir, "src/polyfills.ts"), possiblePaths[0]);
+        // clean up temp project
         this.$fs.deleteDirectory(tempDir);
         this.spinner.succeed(`Created fresh ${color_1.color.cyan("polyfills.ts")}`);
         return "./" + path.relative(projectDir, possiblePaths[0]);
@@ -783,6 +863,7 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
                 desiredVersion: "~0.15.0",
                 shouldAddIfMissing: true,
             },
+            // devDependencies
             {
                 packageName: "@angular/cli",
                 minVersion,
@@ -853,10 +934,12 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
                 packageName: "@babel/preset-env",
                 shouldRemove: true,
             },
+            // remove any version of vue
             {
                 packageName: "vue",
                 shouldRemove: true,
             },
+            // add latest
             {
                 packageName: "vue",
                 desiredVersion: "2.6.12",
@@ -952,6 +1035,7 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
                 return;
             }
         }
+        // clean old config before generating new one
         await this.$projectCleanupService.clean(["webpack.config.js"]);
         this.spinner.info(`Initializing new ${color_1.color.yellow("webpack.config.js")}`);
         const { desiredVersion: webpackVersion } = this.migrationDependencies.find((dep) => dep.packageName === constants.WEBPACK_PLUGIN_NAME);
@@ -1026,6 +1110,7 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
     }
 }
 exports.MigrateController = MigrateController;
+// static readonly typescriptPackageName: string = "typescript";
 MigrateController.backupFolderName = ".migration_backup";
 MigrateController.pathsToBackup = [
     constants.LIB_DIR_NAME,
@@ -1038,3 +1123,4 @@ MigrateController.pathsToBackup = [
     constants.CONFIG_NS_FILE_NAME,
 ];
 yok_1.injector.register("migrateController", MigrateController);
+//# sourceMappingURL=migrate-controller.js.map

package/lib/controllers/platform-controller.js

@@ -84,9 +84,13 @@ class PlatformController {
                 desiredRuntimePackage.version = version;
             }
             if (!desiredRuntimePackage.version) {
+                // if no version is explicitly added, then we use the latest
                 desiredRuntimePackage.version =
                     await this.$packageInstallationManager.getLatestCompatibleVersion(desiredRuntimePackage.name);
             }
+            // const currentPlatformData = this.$projectDataService.getNSValue(projectData.projectDir, platformData.frameworkPackageName);
+            // version = (currentPlatformData && currentPlatformData.version) ||
+            // 	await this.$packageInstallationManager.getLatestCompatibleVersion(platformData.frameworkPackageName);
             result = `${desiredRuntimePackage.name}@${desiredRuntimePackage.version}`;
         }
         return result;
@@ -98,11 +102,14 @@ class PlatformController {
         const prepareInfo = this.$projectChangesService.getPrepareInfo(platformData);
         const requiresNativePlatformAdd = prepareInfo &&
             prepareInfo.nativePlatformStatus ===
-                "1";
+                "1" /* NativePlatformStatus.requiresPlatformAdd */;
         const shouldAddPlatform = !hasPlatformDirectory ||
             (shouldAddNativePlatform && requiresNativePlatformAdd);
         if (hasPlatformDirectory && !shouldAddPlatform) {
             const platformDirectoryItemCount = this.$fs.readDirectory(path.join(projectData.platformsDir, platformName)).length;
+            // 2 is a magic number to approximate a valid platform folder
+            // any valid platform should contain at least 2 files/folders
+            // we choose 2 to avoid false-positives due to system files like .DS_Store etc.
             if (platformDirectoryItemCount <= 2) {
                 this.$logger.warn(`The platforms/${platformName} folder appears to be invalid. If the build fails, run 'ns clean' and rebuild the app.`, { wrapMessageWithBorders: true });
             }
@@ -112,3 +119,4 @@ class PlatformController {
 }
 exports.PlatformController = PlatformController;
 yok_1.injector.register("platformController", PlatformController);
+//# sourceMappingURL=platform-controller.js.map

package/lib/controllers/prepare-controller.js

@@ -76,6 +76,10 @@ class PrepareController extends events_1.EventEmitter {
         await this.$platformController.addPlatformIfNeeded(prepareData, projectData);
         await this.trackRuntimeVersion(prepareData.platform, projectData);
         this.$logger.info("Preparing project...");
+        // we need to mark the ~/package.json (used by core modules)
+        // as external for us to be able to write the config to it
+        // in writeRuntimePackageJson() below, because otherwise
+        // webpack will inline it into the bundle/vendor chunks
         prepareData.env = prepareData.env || {};
         prepareData.env.externals = prepareData.env.externals || [];
         prepareData.env.externals.push("~/package.json");
@@ -116,8 +120,8 @@ class PrepareController extends events_1.EventEmitter {
                 },
             };
         }
-        await this.startJSWatcherWithPrepare(platformData, projectData, prepareData);
-        const hasNativeChanges = await this.startNativeWatcherWithPrepare(platformData, projectData, prepareData);
+        await this.startJSWatcherWithPrepare(platformData, projectData, prepareData); // -> start watcher + initial compilation
+        const hasNativeChanges = await this.startNativeWatcherWithPrepare(platformData, projectData, prepareData); // -> start watcher + initial prepare
         const result = {
             platform: platformData.platformNameLowerCase,
             hasNativeChanges,
@@ -126,6 +130,7 @@ class PrepareController extends events_1.EventEmitter {
         if (hasPersistedDataWithNativeChanges) {
             result.hasNativeChanges = true;
         }
+        // TODO: Do not persist this in `this` context. Also it should be per platform.
         this.isInitialPrepareReady = true;
         if (this.persistedData && this.persistedData.length) {
             this.emitPrepareEvent({
@@ -178,7 +183,7 @@ class PrepareController extends events_1.EventEmitter {
                 pollInterval: 100,
                 stabilityThreshold: 500,
             },
-            ignored: ["**/.*", ".*"],
+            ignored: ["**/.*", ".*"], // hidden files
         };
         const watcher = (0, chokidar_1.watch)(patterns, watcherOptions).on("all", async (event, filePath) => {
             if (this.isFileWatcherPaused())
@@ -220,6 +225,9 @@ class PrepareController extends events_1.EventEmitter {
             .concat(pluginsPackageJsonFiles);
         return patterns;
     }
+    /**
+     * TODO: move this logic to the webpack side of things - WIP and deprecate here with a webpack version check...
+     */
     async writeRuntimePackageJson(projectData, platformData, prepareData = null) {
         const configInfo = this.$projectConfigService.detectProjectConfigs(projectData.projectDir);
         if (configInfo.usingNSConfig) {
@@ -252,7 +260,11 @@ class PrepareController extends events_1.EventEmitter {
             packagePath = path.join(platformData.projectRoot, this.$options.hostProjectModuleName, "src", this.$options.hostProjectPath ? "nativescript" : "main", "assets", "app", "package.json");
         }
         try {
+            // this will read the package.json that is already emitted by
+            // the GenerateNativeScriptEntryPointsPlugin webpack plugin
             const emittedPackageData = this.$fs.readJson(packagePath);
+            // since ns7 we only care about the main key from the emitted
+            // package.json, the rest is coming from the new config.
             if (emittedPackageData === null || emittedPackageData === void 0 ? void 0 : emittedPackageData.main) {
                 packageData.main = emittedPackageData.main;
             }
@@ -280,7 +292,7 @@ class PrepareController extends events_1.EventEmitter {
             return;
         }
         await this.$analyticsService.trackEventActionInGoogleAnalytics({
-            action: "Using Runtime Version",
+            action: "Using Runtime Version" /* TrackActionNames.UsingRuntimeVersion */,
             additionalData: `${platform.toLowerCase()}${constants_1.AnalyticsEventLabelDelimiter}${version}`,
         });
     }
@@ -325,3 +337,4 @@ __decorate([
     (0, decorators_1.cache)()
 ], PrepareController.prototype, "trackRuntimeVersion", null);
 yok_1.injector.register("prepareController", PrepareController);
+//# sourceMappingURL=prepare-controller.js.map

package/lib/controllers/run-controller.js

@@ -78,11 +78,14 @@ class RunController extends events_1.EventEmitter {
         const { projectDir, deviceIdentifiers, stopOptions } = data;
         const liveSyncProcessInfo = this.$liveSyncProcessDataService.getPersistedData(projectDir);
         if (liveSyncProcessInfo && !liveSyncProcessInfo.isStopped) {
+            // In case we are coming from error during livesync, the current action is the one that erred (but we are still executing it),
+            // so we cannot await it as this will cause infinite loop.
             const shouldAwaitPendingOperation = !stopOptions || stopOptions.shouldAwaitAllActions;
             const deviceIdentifiersToRemove = deviceIdentifiers && deviceIdentifiers.length
                 ? deviceIdentifiers
                 : _.map(liveSyncProcessInfo.deviceDescriptors, (d) => d.identifier);
             const removedDeviceIdentifiers = _.remove(liveSyncProcessInfo.deviceDescriptors, (descriptor) => _.includes(deviceIdentifiersToRemove, descriptor.identifier)).map((descriptor) => descriptor.identifier);
+            // Handle the case when no more devices left for any of the persisted platforms
             for (let i = 0; i < liveSyncProcessInfo.platforms.length; i++) {
                 const platform = liveSyncProcessInfo.platforms[i];
                 const devices = this.$devicesService.getDevicesForPlatform(platform);
@@ -90,6 +93,7 @@ class RunController extends events_1.EventEmitter {
                     await this.$prepareController.stopWatchers(projectDir, platform);
                 }
             }
+            // In case deviceIdentifiers are not passed, we should stop the whole LiveSync.
             if (!deviceIdentifiers ||
                 !deviceIdentifiers.length ||
                 !liveSyncProcessInfo.deviceDescriptors ||
@@ -120,6 +124,7 @@ class RunController extends events_1.EventEmitter {
                 shouldAwaitPendingOperation) {
                 await liveSyncProcessInfo.currentSyncAction;
             }
+            // Emit RunOnDevice stopped when we've really stopped.
             _.each(removedDeviceIdentifiers, (deviceIdentifier) => {
                 this.emitCore(constants_2.RunOnDeviceEvents.runOnDeviceStopped, {
                     projectDir,
@@ -157,6 +162,8 @@ class RunController extends events_1.EventEmitter {
             shouldSkipEmitLiveSyncNotification: true,
             shouldCheckDeveloperDiscImage: true,
         });
+        // we do not stop the application when debugBrk is false, so we need to attach, instead of launch
+        // if we try to send the launch request, the debugger port will not be printed and the command will timeout
         debugOptions.start = !debugOptions.debugBrk;
         debugOptions.forceDebuggerAttachedEvent = refreshInfo.didRestart;
         await this.$debugController.enableDebuggingCoreWithoutWaitingCurrentAction(projectData.projectDir, deviceDescriptor.identifier, debugOptions);
@@ -224,6 +231,7 @@ class RunController extends events_1.EventEmitter {
     getDeviceDescriptorsForInitialSync(projectDir, deviceDescriptors) {
         const currentRunData = this.$liveSyncProcessDataService.getPersistedData(projectDir);
         const isAlreadyLiveSyncing = currentRunData && !currentRunData.isStopped;
+        // Prevent cases where liveSync is called consecutive times with the same device, for example [ A, B, C ] and then [ A, B, D ] - we want to execute initialSync only for D.
         const deviceDescriptorsForInitialSync = isAlreadyLiveSyncing
             ? _.differenceBy(deviceDescriptors, currentRunData.deviceDescriptors, "identifier")
             : deviceDescriptors;
@@ -277,6 +285,8 @@ class RunController extends events_1.EventEmitter {
             const platformData = this.$platformsDataService.getPlatformData(device.deviceInfo.platform, projectData);
             try {
                 let packageFilePath = null;
+                // Case where we have three devices attached, a change that requires build is found,
+                // we'll rebuild the app only for the first device, but we should install new package on all three devices.
                 if (rebuiltInformation[platformData.platformNameLowerCase] &&
                     (this.$mobileHelper.isAndroidPlatform(platformData.platformNameLowerCase) ||
                         rebuiltInformation[platformData.platformNameLowerCase]
@@ -300,7 +310,7 @@ class RunController extends events_1.EventEmitter {
                     }
                     else {
                         await this.$analyticsService.trackEventActionInGoogleAnalytics({
-                            action: "LiveSync",
+                            action: "LiveSync" /* TrackActionNames.LiveSync */,
                             device,
                             projectDir: projectData.projectDir,
                         });
@@ -370,6 +380,9 @@ class RunController extends events_1.EventEmitter {
                 const watchInfo = {
                     liveSyncDeviceData: deviceDescriptor,
                     projectData,
+                    // todo: remove stale files once everything is stable
+                    // currently, watcher fires multiple times & may clean up unsynced files
+                    // filesToRemove: data.staleFiles ?? [],
                     filesToRemove: [],
                     filesToSync,
                     hmrData: data.hmrData,
@@ -415,6 +428,7 @@ class RunController extends events_1.EventEmitter {
                         const fullSyncAction = async () => {
                             watchInfo.filesToSync = allAppFiles;
                             const fullLiveSyncResultInfo = await platformLiveSyncService.liveSyncWatchAction(device, watchInfo);
+                            // IMPORTANT: keep the same instance as we rely on side effects
                             _.assign(liveSyncResultInfo, fullLiveSyncResultInfo);
                         };
                         await this.$hooksService.executeBeforeHooks("watchAction", {
@@ -429,6 +443,7 @@ class RunController extends events_1.EventEmitter {
                         await this.refreshApplication(projectData, liveSyncResultInfo, data, deviceDescriptor, fullSyncAction);
                         if (!liveSyncResultInfo.didRecover && isInHMRMode) {
                             const status = await this.$hmrStatusService.getHmrStatus(device.deviceInfo.identifier, data.hmrData.hash);
+                            // the timeout is assumed OK as the app could be blocked on a breakpoint
                             if (status === constants_1.HmrConstants.HMR_ERROR_STATUS) {
                                 await fullSyncAction();
                                 liveSyncResultInfo.isFullSync = true;
@@ -510,3 +525,4 @@ __decorate([
     (0, decorators_1.cache)()
 ], RunController.prototype, "attachDeviceLostHandler", null);
 yok_1.injector.register("runController", RunController);
+//# sourceMappingURL=run-controller.js.map

package/lib/controllers/update-controller-base.js

@@ -69,3 +69,4 @@ class UpdateControllerBase {
     }
 }
 exports.UpdateControllerBase = UpdateControllerBase;
+//# sourceMappingURL=update-controller-base.js.map

package/lib/controllers/update-controller.js

@@ -28,12 +28,15 @@ class UpdateController extends update_controller_base_1.UpdateControllerBase {
         this.spinner = this.$terminalSpinnerService.createSpinner();
         const projectData = this.$projectDataService.getProjectData(updateOptions.projectDir);
         updateOptions.version = updateOptions.version || constants_1.PackageVersion.LATEST;
+        // back up project files and folders
         this.spinner.info("Backing up project files before update");
         await this.backupProject();
         this.spinner.succeed("Project files have been backed up");
+        // clean up project files
         this.spinner.info("Cleaning up project files before update");
         await this.cleanUpProject();
         this.spinner.succeed("Project files have been cleaned up");
+        // update dependencies
         this.spinner.info("Updating project dependencies");
         await this.updateDependencies(projectData, updateOptions.version);
         this.spinner.succeed("Project dependencies have been updated");
@@ -79,6 +82,10 @@ class UpdateController extends update_controller_base_1.UpdateControllerBase {
         if (!shouldUpdate) {
             return;
         }
+        // check if the coerced version is the same as desired and prefix it with a ~
+        // for example:
+        // 8.0.0 -> ~8.0.0
+        // 8.0.8-next-XXX -> 8.0.8-next-XXX
         const updatedVersion = (() => {
             if (desiredVersion === version) {
                 return desiredVersion;
@@ -131,9 +138,11 @@ class UpdateController extends update_controller_base_1.UpdateControllerBase {
 }
 exports.UpdateController = UpdateController;
 UpdateController.updatableDependencies = [
+    // dependencies
     {
         packageName: "@nativescript/core",
     },
+    // devDependencies
     {
         packageName: "@nativescript/webpack",
         isDev: true,
@@ -142,6 +151,7 @@ UpdateController.updatableDependencies = [
         packageName: "@nativescript/types",
         isDev: true,
     },
+    // runtimes
     {
         packageName: "@nativescript/ios",
         isDev: true,
@@ -161,3 +171,4 @@ UpdateController.pathsToBackup = [
     constants.CONFIG_NS_FILE_NAME,
 ];
 yok_1.injector.register("updateController", UpdateController);
+//# sourceMappingURL=update-controller.js.map

package/lib/data/build-data.js

@@ -42,3 +42,4 @@ class AndroidBuildData extends BuildData {
     }
 }
 exports.AndroidBuildData = AndroidBuildData;
+//# sourceMappingURL=build-data.js.map

package/lib/data/controller-data-base.js

@@ -9,3 +9,4 @@ class ControllerDataBase {
     }
 }
 exports.ControllerDataBase = ControllerDataBase;
+//# sourceMappingURL=controller-data-base.js.map

package/lib/data/debug-data.js

@@ -4,3 +4,4 @@ exports.DebugData = void 0;
 class DebugData {
 }
 exports.DebugData = DebugData;
+//# sourceMappingURL=debug-data.js.map

package/lib/data/platform-data.js

@@ -11,3 +11,4 @@ class AddPlatformData extends controller_data_base_1.ControllerDataBase {
     }
 }
 exports.AddPlatformData = AddPlatformData;
+//# sourceMappingURL=platform-data.js.map

package/lib/data/prepare-data.js

@@ -49,3 +49,4 @@ exports.IOSPrepareData = IOSPrepareData;
 class AndroidPrepareData extends PrepareData {
 }
 exports.AndroidPrepareData = AndroidPrepareData;
+//# sourceMappingURL=prepare-data.js.map

package/lib/data/run-data.js

@@ -9,3 +9,4 @@ class RunData {
     }
 }
 exports.RunData = RunData;
+//# sourceMappingURL=run-data.js.map