nativescript 8.8.0 → 8.8.1

package/lib/controllers/migrate-controller.js

@@ -21,8 +21,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;
@@ -174,13 +178,16 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
                 replaceWith: "sass",
                 minVersion: "0.0.0",
                 isDev: true,
+                // shouldRemove: true,
             },
             {
                 packageName: "sass",
                 minVersion: "0.0.0",
                 desiredVersion: "^1.49.9",
                 isDev: true,
+                // shouldRemove: true,
             },
+            // runtimes
             {
                 packageName: "tns-ios",
                 minVersion: "6.5.3",
@@ -224,8 +231,10 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
                     remainingPlatforms.push(platform);
                     continue;
                 }
+                // should only run in loose mode...
                 const cachedResult = yield 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);
                 }
@@ -237,6 +246,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) {
                         yield this.setCachedShouldMigrate(projectDir, remainingPlatform);
@@ -267,37 +277,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 = yield 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 = yield 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");
             yield this.cleanUpProject(projectData);
             this.spinner.succeed("Project files have been cleaned up");
+            // clean up artifacts
             this.spinner.info("Cleaning up old artifacts");
             yield 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")}`);
                 yield 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");
             yield 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 = yield 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")}`);
@@ -309,11 +328,21 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
                 this.spinner.succeed(`Updated ${color_1.color.yellow("tsconfig.json")}`);
             }
             yield this.migrateWebpack5(projectDir, projectData);
+            // run @nativescript/eslint over codebase
             yield 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.");
+                "\n\nPlease note that you may need additional changes to complete the migration."
+            // + "\n\nYou may restore your project with `ns migrate restore`"
+            );
+            // 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
         });
     }
     _shouldMigrate({ projectDir, platforms, loose, }) {
@@ -332,6 +361,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;
@@ -347,6 +377,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;
                     }
@@ -398,12 +429,33 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
             return yield 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
+    // 			);
+    // 		}
+    // 	}
+    // }
     ensureGitCleanOrForce(projectDir) {
         return __awaiter(this, void 0, void 0, function* () {
             const git = (0, simple_git_1.default)(projectDir);
             const isGit = yield 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.");
@@ -454,6 +506,7 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
             const { dependencies, devDependencies } = yield 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
                 yield this.$projectCleanupService.clean([
                     constants.TSCCONFIG_TNS_JSON_NAME,
                 ]);
@@ -503,12 +556,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;
@@ -518,6 +573,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) {
@@ -585,6 +641,7 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
         var _a, _b, _c, _d, _e;
         return __awaiter(this, void 0, void 0, function* () {
             const hasDependency = this.hasDependency(dependency, projectData);
+            // show warning if needed
             if (hasDependency && dependency.warning) {
                 this.$logger.warn(dependency.warning);
             }
@@ -600,7 +657,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;
                 }
@@ -609,6 +668,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)}`);
@@ -630,35 +690,51 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
     migrateConfigs(projectDir) {
         return __awaiter(this, void 0, void 0, function* () {
             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 = yield this.$projectConfigService.setValue("", configData);
+            // migrate data into nativescript.config.ts
+            const hasUpdatedConfigSuccessfully = yield this.$projectConfigService.setValue("", // root
+            configData);
             if (!hasUpdatedConfigSuccessfully) {
                 if (typeof newConfigPath === "string") {
+                    // only clean the config if it was created by the migration script
                     yield 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
             yield this.$projectCleanupService.cleanPath(embeddedPackageJsonPath);
             yield this.$projectCleanupService.cleanPath(legacyNsConfigPath);
             return true;
@@ -666,6 +742,7 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
     }
     migrateUnitTestRunner(projectData, migrationBackupDirPath) {
         return __awaiter(this, void 0, void 0, function* () {
+            // Migrate karma.conf.js
             const pathToKarmaConfig = path.join(migrationBackupDirPath, constants.KARMA_CONFIG_NAME);
             if (this.$fs.exists(pathToKarmaConfig)) {
                 const oldKarmaContent = this.$fs.readText(pathToKarmaConfig);
@@ -683,6 +760,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",
@@ -726,6 +804,7 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
         return __awaiter(this, void 0, void 0, function* () {
             try {
                 const configContents = this.$fs.readJson(tsConfigPath);
+                // update
                 configContents.compilerOptions = configContents.compilerOptions || {};
                 configContents.compilerOptions.target = "es2020";
                 configContents.compilerOptions.module = "esnext";
@@ -736,6 +815,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([
@@ -771,8 +851,10 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
             const tempDir = temp.mkdirSync({
                 prefix: "migrate-angular-polyfills",
             });
+            // get from default angular template
             yield 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]);
@@ -843,6 +925,7 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
                     desiredVersion: "~0.14.0",
                     shouldAddIfMissing: true,
                 },
+                // devDependencies
                 {
                     packageName: "@angular/cli",
                     minVersion,
@@ -915,10 +998,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",
@@ -1020,6 +1105,7 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
                     return;
                 }
             }
+            // clean old config before generating new one
             yield 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);
@@ -1098,6 +1184,7 @@ class MigrateController extends update_controller_base_1.UpdateControllerBase {
         });
     }
 }
+// static readonly typescriptPackageName: string = "typescript";
 MigrateController.backupFolderName = ".migration_backup";
 MigrateController.pathsToBackup = [
     constants.LIB_DIR_NAME,
@@ -1111,3 +1198,4 @@ MigrateController.pathsToBackup = [
 ];
 exports.MigrateController = MigrateController;
 yok_1.injector.register("migrateController", MigrateController);
+//# sourceMappingURL=migrate-controller.js.map

package/lib/controllers/platform-controller.js

@@ -98,9 +98,13 @@ class PlatformController {
                     desiredRuntimePackage.version = version;
                 }
                 if (!desiredRuntimePackage.version) {
+                    // if no version is explicitly added, then we use the latest
                     desiredRuntimePackage.version =
                         yield 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;
@@ -113,11 +117,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 });
             }
@@ -127,3 +134,4 @@ class PlatformController {
 }
 exports.PlatformController = PlatformController;
 yok_1.injector.register("platformController", PlatformController);
+//# sourceMappingURL=platform-controller.js.map

package/lib/controllers/prepare-controller.js

@@ -90,6 +90,10 @@ class PrepareController extends events_1.EventEmitter {
             yield this.$platformController.addPlatformIfNeeded(prepareData, projectData);
             yield 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");
@@ -132,8 +136,8 @@ class PrepareController extends events_1.EventEmitter {
                     },
                 };
             }
-            yield this.startJSWatcherWithPrepare(platformData, projectData, prepareData);
-            const hasNativeChanges = yield this.startNativeWatcherWithPrepare(platformData, projectData, prepareData);
+            yield this.startJSWatcherWithPrepare(platformData, projectData, prepareData); // -> start watcher + initial compilation
+            const hasNativeChanges = yield this.startNativeWatcherWithPrepare(platformData, projectData, prepareData); // -> start watcher + initial prepare
             const result = {
                 platform: platformData.platformNameLowerCase,
                 hasNativeChanges,
@@ -142,6 +146,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({
@@ -200,7 +205,7 @@ class PrepareController extends events_1.EventEmitter {
                     pollInterval: 100,
                     stabilityThreshold: 500,
                 },
-                ignored: ["**/.*", ".*"],
+                ignored: ["**/.*", ".*"], // hidden files
             };
             const watcher = choki
                 .watch(patterns, watcherOptions)
@@ -247,6 +252,9 @@ class PrepareController extends events_1.EventEmitter {
             return patterns;
         });
     }
+    /**
+     * TODO: move this logic to the webpack side of things - WIP and deprecate here with a webpack version check...
+     */
     writeRuntimePackageJson(projectData, platformData) {
         return __awaiter(this, void 0, void 0, function* () {
             const configInfo = this.$projectConfigService.detectProjectConfigs(projectData.projectDir);
@@ -276,7 +284,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;
                 }
@@ -303,7 +315,7 @@ class PrepareController extends events_1.EventEmitter {
                 return;
             }
             yield this.$analyticsService.trackEventActionInGoogleAnalytics({
-                action: "Using Runtime Version",
+                action: "Using Runtime Version" /* TrackActionNames.UsingRuntimeVersion */,
                 additionalData: `${platform.toLowerCase()}${constants_1.AnalyticsEventLabelDelimiter}${version}`,
             });
         });
@@ -351,3 +363,4 @@ __decorate([
 ], PrepareController.prototype, "trackRuntimeVersion", null);
 exports.PrepareController = PrepareController;
 yok_1.injector.register("prepareController", PrepareController);
+//# sourceMappingURL=prepare-controller.js.map

package/lib/controllers/run-controller.js

@@ -90,11 +90,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);
@@ -102,6 +105,7 @@ class RunController extends events_1.EventEmitter {
                         yield this.$prepareController.stopWatchers(projectDir, platform);
                     }
                 }
+                // In case deviceIdentifiers are not passed, we should stop the whole LiveSync.
                 if (!deviceIdentifiers ||
                     !deviceIdentifiers.length ||
                     !liveSyncProcessInfo.deviceDescriptors ||
@@ -132,6 +136,7 @@ class RunController extends events_1.EventEmitter {
                     shouldAwaitPendingOperation) {
                     yield liveSyncProcessInfo.currentSyncAction;
                 }
+                // Emit RunOnDevice stopped when we've really stopped.
                 _.each(removedDeviceIdentifiers, (deviceIdentifier) => {
                     this.emitCore(constants_2.RunOnDeviceEvents.runOnDeviceStopped, {
                         projectDir,
@@ -173,6 +178,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;
             yield this.$debugController.enableDebuggingCoreWithoutWaitingCurrentAction(projectData.projectDir, deviceDescriptor.identifier, debugOptions);
@@ -243,6 +250,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;
@@ -291,6 +299,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]
@@ -314,7 +324,7 @@ class RunController extends events_1.EventEmitter {
                         }
                         else {
                             yield this.$analyticsService.trackEventActionInGoogleAnalytics({
-                                action: "LiveSync",
+                                action: "LiveSync" /* TrackActionNames.LiveSync */,
                                 device,
                                 projectDir: projectData.projectDir,
                             });
@@ -381,6 +391,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,
@@ -426,6 +439,7 @@ class RunController extends events_1.EventEmitter {
                             const fullSyncAction = () => __awaiter(this, void 0, void 0, function* () {
                                 watchInfo.filesToSync = allAppFiles;
                                 const fullLiveSyncResultInfo = yield platformLiveSyncService.liveSyncWatchAction(device, watchInfo);
+                                // IMPORTANT: keep the same instance as we rely on side effects
                                 _.assign(liveSyncResultInfo, fullLiveSyncResultInfo);
                             });
                             yield this.$hooksService.executeBeforeHooks("watchAction", {
@@ -440,6 +454,7 @@ class RunController extends events_1.EventEmitter {
                             yield this.refreshApplication(projectData, liveSyncResultInfo, data, deviceDescriptor, fullSyncAction);
                             if (!liveSyncResultInfo.didRecover && isInHMRMode) {
                                 const status = yield 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) {
                                     yield fullSyncAction();
                                     liveSyncResultInfo.isFullSync = true;
@@ -524,3 +539,4 @@ __decorate([
 ], RunController.prototype, "attachDeviceLostHandler", null);
 exports.RunController = RunController;
 yok_1.injector.register("runController", RunController);
+//# sourceMappingURL=run-controller.js.map

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

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

package/lib/controllers/update-controller.js

@@ -38,12 +38,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");
             yield this.backupProject();
             this.spinner.succeed("Project files have been backed up");
+            // clean up project files
             this.spinner.info("Cleaning up project files before update");
             yield this.cleanUpProject();
             this.spinner.succeed("Project files have been cleaned up");
+            // update dependencies
             this.spinner.info("Updating project dependencies");
             yield this.updateDependencies(projectData, updateOptions.version);
             this.spinner.succeed("Project dependencies have been updated");
@@ -95,6 +98,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;
@@ -155,9 +162,11 @@ class UpdateController extends update_controller_base_1.UpdateControllerBase {
     }
 }
 UpdateController.updatableDependencies = [
+    // dependencies
     {
         packageName: "@nativescript/core",
     },
+    // devDependencies
     {
         packageName: "@nativescript/webpack",
         isDev: true,
@@ -166,6 +175,7 @@ UpdateController.updatableDependencies = [
         packageName: "@nativescript/types",
         isDev: true,
     },
+    // runtimes
     {
         packageName: "@nativescript/ios",
         isDev: true,
@@ -186,3 +196,4 @@ UpdateController.pathsToBackup = [
 ];
 exports.UpdateController = UpdateController;
 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

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