Improve debugService public API

When using Chrome DevTools to debug iOS applications, CLI returns a url that points to a specific commit of the dev tools. This way, in case a new version of the dev tools introduces a breaking change, the debugging will still work.
However, in some cases (inside Electron app), we cannot use the remote url, so we must use the bundled one. So introduce a new option (only available when requiring CLI as a library), that defines that the returned url will use the bundled dev tools.
The default behavior (used in CLI), will still return the url that includes remote url.
Also change the definition of `debug` method in the interface, so now the DebugService can safely implement it.
Add a new check in the debug service - in case the device's status is not Connected, we are unable to start debug operation. So fail with correct error message in this case.
Add JSDocs for all debug related interfaces.
Add documentation in PublicAPI.md for the `debugService`.
Add debugService to tests of public API.

Author: rosen-vladimirov

PublicAPI.md

@@ -180,10 +180,10 @@ for (let promise of loadExtensionsPromises) {
 }
 ```
 
-## settings
-`settings` module provides a way to configure various settings.
+## settingsService
+`settingsService` module provides a way to configure various settings.
 
-### set
+### setSettings
 Used to set various settings in order to modify the behavior of some methods.
 * Auxiliary interfaces:
 ```TypeScript
@@ -339,9 +339,128 @@ tns.npm.view(["nativescript"], {}).then(result => {
 });
 ```
 
+## debugService
+Provides methods for debugging applications on devices. The service is also event emitter, that raises the following events:
+* `connectionError` event - this event is raised when the debug operation cannot start on iOS device. The causes can be:
+  * Application is not running on the specified iOS Device.
+  * Application is not built in debug configuration on the specified iOS device.
+  The event is raised with the following information:
+```TypeScript
+{
+	/**
+	 * Device identifier on which the debug process cannot start.
+	 */
+	deviceId: string;
+
+	/**
+	 * The error message.
+	 */
+	message: string;
+
+	/**
+	 * Code of the error.
+	 */
+	code: number
+}
+```
+
+* Usage:
+```JavaScript
+tns.debugService.on("connectionError", errorData => {
+	console.log(`Unable to start debug operation on device ${errorData.deviceId}. Error is: ${errorData.message}.`);
+});
+```
+
+### debug
+The `debug` method allows starting a debug operation for specified application on a specific device. The method returns a Promise, which is resolved with a url. The url should be opened in Chrome DevTools in order to debug the application.
+
+The returned Promise will be rejected in case any error occurs. It will also be rejected in case:
+1. Specified deviceIdentifier is not found in current list of attached devices.
+1. The device, specified as deviceIdentifier is connected but not trusted.
+1. The specified application is not installed on the device.
+1. Trying to debug applications on connected iOS device on Linux.
+1. In case the application is not running on the specified device.
+1. In case the installed application is not built in debug configuration.
+
+* Definition:
+```TypeScript
+/**
+ * Starts debug operation based on the specified debug data.
+ * @param {IDebugData} debugData Describes information for device and application that will be debugged.
+ * @param {IDebugOptions} debugOptions Describe possible options to modify the behaivor of the debug operation, for example stop on the first line.
+ * @returns {Promise<string>} URL that should be opened in Chrome DevTools.
+ */
+debug(debugData: IDebugData, debugOptions: IDebugOptions): Promise<string>;
+```
+
+The type of arguments that you can pass are described below:
+```TypeScript
+/**
+ * Describes information for starting debug process.
+ */
+interface IDebugData {
+	/**
+	 * Id of the device on which the debug process will be started.
+	 */
+	deviceIdentifier: string;
+
+	/**
+	 * Application identifier of the app that it will be debugged.
+	 */
+	applicationIdentifier: string;
+
+	/**
+	 * Path to .app built for iOS Simulator.
+	 */
+	pathToAppPackage?: string;
+
+	/**
+	 * The name of the application, for example `MyProject`.
+	 */
+	projectName?: string;
+
+	/**
+	 * Path to project.
+	 */
+	projectDir?: string;
+}
+
+/**
+ * Describes all options that define the behavior of debug.
+ */
+interface IDebugOptions {
+	/**
+	 * Defines if bundled Chrome DevTools should be used or specific commit. Valid for iOS only.
+	 */
+	useBundledDevTools?: boolean;
+}
+```
+
+* Usage:
+```JavaScript
+tns.debugService.on("connectionError", errorData => {
+	console.log(`Unable to start debug operation on device ${errorData.deviceId}. Error is: ${errorData.message}.`);
+});
+
+const debugData = {
+	deviceIdentifier: "4df18f307d8a8f1b",
+	applicationIdentifier: "com.telerik.app1",
+	projectName: "app1",
+	projectDir: "/Users/myUser/app1"
+};
+
+const debugOptions = {
+	useBundledDevTools: true
+};
+
+tns.debugService.debug(debugData, debugOptions)
+	.then(url => console.log(`Open the following url in Chrome DevTools: ${url}`))
+	.catch(err => console.log(`Unable to start debug operation, reason: ${err.message}.`));
+```
+
 ## How to add a new method to Public API
 CLI is designed as command line tool and when it is used as a library, it does not give you access to all of the methods. This is mainly implementation detail. Most of the CLI's code is created to work in command line, not as a library, so before adding method to public API, most probably it will require some modification.
 For example the `$options` injected module contains information about all `--` options passed on the terminal. When the CLI is used as a library, the options are not populated. Before adding method to public API, make sure its implementation does not rely on `$options`.
 
 More information how to add a method to public API is available [here](https://github.com/telerik/mobile-cli-lib#how-to-make-a-method-public).
-After that add each method that you've exposed to the tests in `tests/nativescript-cli-lib.ts` file. There you'll find an object describing each publicly available module and the methods that you can call.
+After that add each method that you've exposed to the tests in `tests/nativescript-cli-lib.ts` file. There you'll find an object describing each publicly available module and the methods that you can call.

lib/commands/debug.ts

@@ -36,7 +36,7 @@ export abstract class DebugPlatformCommand implements ICommand {
 		await this.$platformService.trackProjectType(this.$projectData);
 
 		if (this.$options.start) {
-			return this.printDebugInformation(await this.debugService.debug(debugData, debugOptions));
+			return this.printDebugInformation(await this.debugService.debug<string[]>(debugData, debugOptions));
 		}
 
 		const appFilesUpdaterOptions: IAppFilesUpdaterOptions = { bundle: this.$options.bundle, release: this.$options.release };
@@ -58,7 +58,7 @@ export abstract class DebugPlatformCommand implements ICommand {
 			const buildConfig: IBuildConfig = _.merge({ buildForDevice: !deviceAppData.device.isEmulator }, deployOptions);
 			debugData.pathToAppPackage = this.$platformService.lastOutputPath(this.debugService.platform, buildConfig, projectData);
 
-			this.printDebugInformation(await this.debugService.debug(debugData, debugOptions));
+			this.printDebugInformation(await this.debugService.debug<string[]>(debugData, debugOptions));
 		};
 
 		return this.$usbLiveSyncService.liveSync(this.$devicesService.platform, this.$projectData, applicationReloadAction);

lib/common

@@ -1,31 +1,124 @@
+/**
+ * Describes information for starting debug process.
+ */
 interface IDebugData {
+	/**
+	 * Id of the device on which the debug process will be started.
+	 */
 	deviceIdentifier: string;
+
+	/**
+	 * Application identifier of the app that it will be debugged.
+	 */
 	applicationIdentifier: string;
+
+	/**
+	 * Path to .app built for iOS Simulator.
+	 */
 	pathToAppPackage?: string;
+
+	/**
+	 * The name of the application, for example `MyProject`.
+	 */
 	projectName?: string;
+
+	/**
+	 * Path to project.
+	 */
 	projectDir?: string;
 }
 
+/**
+ * Describes all options that define the behavior of debug.
+ */
 interface IDebugOptions {
+	/**
+	 * Defines if Chrome-Dev Tools should be used for debugging.
+	 */
 	chrome?: boolean;
+
+	/**
+	 * Defines if thе application is already started on device.
+	 */
 	start?: boolean;
+
+	/**
+	 * Defines if we should stop the currently running debug process.
+	 */
 	stop?: boolean;
+
+	/**
+	 * Defines if debug process is for emulator (not for real device).
+	 */
 	emulator?: boolean;
+
+	/**
+	 * Defines if the debug process should break on the first line.
+	 */
 	debugBrk?: boolean;
+
+	/**
+	 * Defines if the debug process will not have a client attached (i.e. the process will be started, but NativeScript Inspector will not be started and it will not attach to the running debug process).
+	 */
 	client?: boolean;
+
+	/**
+	 * Defines if the process will watch for further changes in the project and transferrs them to device immediately, resulting in restar of the debug process.
+	 */
 	justlaunch?: boolean;
+
+	/**
+	 * Defines if bundled Chrome DevTools should be used or specific commit. Valid for iOS only.
+	 */
+	useBundledDevTools?: boolean;
 }
 
+/**
+ * Describes methods to create debug data object used by other methods.
+ */
 interface IDebugDataService {
+	/**
+	 * Creates the debug data based on specified options.
+	 * @param {IProjectData} projectData The data describing project that will be debugged.
+	 * @param {IOptions} options The options based on which debugData will be created
+	 * @returns {IDebugData} Data describing the required information for starting debug process.
+	 */
 	createDebugData(projectData: IProjectData, options: IOptions): IDebugData;
 }
 
+/**
+ * Describes methods for debug operation.
+ */
 interface IDebugService extends NodeJS.EventEmitter {
-	debug(debugData: IDebugData, debugOptions: IDebugOptions): Promise<string[]>;
+	/**
+	 * Starts debug operation based on the specified debug data.
+	 * @param {IDebugData} debugData Describes information for device and application that will be debugged.
+	 * @param {IDebugOptions} debugOptions Describe possible options to modify the behaivor of the debug operation, for example stop on the first line.
+	 * @returns {Promise<T>} Array of URLs that can be used for debugging or a string representing a single url that can be used for debugging.
+	 */
+	debug<T>(debugData: IDebugData, debugOptions: IDebugOptions): Promise<T>;
 }
 
+/**
+ * Describes actions required for debugging on specific platform (Android or iOS).
+ */
 interface IPlatformDebugService extends IDebugService {
+	/**
+	 * Starts debug operation.
+	 * @param {IDebugData} debugData Describes information for device and application that will be debugged.
+	 * @param {IDebugOptions} debugOptions Describe possible options to modify the behaivor of the debug operation, for example stop on the first line.
+	 * @returns {Promise<void>}
+	 */
 	debugStart(debugData: IDebugData, debugOptions: IDebugOptions): Promise<void>;
+
+	/**
+	 * Stops debug operation.
+	 * @returns {Promise<void>}
+	 */
 	debugStop(): Promise<void>
+
+	/**
+	 * Mobile platform of the device - Android or iOS.
+	 */
 	platform: string;
 }

lib/definitions/debug.d.ts

@@ -1,10 +1,9 @@
 import { platform } from "os";
 import { EventEmitter } from "events";
 import { CONNECTION_ERROR_EVENT_NAME } from "../constants";
+import { CONNECTED_STATUS } from "../common/constants";
 
-// This service can't implement IDebugService because
-// the debug method returns only one result.
-class DebugService extends EventEmitter {
+class DebugService extends EventEmitter implements IDebugService {
 	constructor(private $devicesService: Mobile.IDevicesService,
 		private $androidDebugService: IPlatformDebugService,
 		private $iOSDebugService: IPlatformDebugService,
@@ -23,6 +22,10 @@ class DebugService extends EventEmitter {
 			this.$errors.failWithoutHelp(`Can't find device with identifier ${debugData.deviceIdentifier}`);
 		}
 
+		if (device.deviceInfo.status !== CONNECTED_STATUS) {
+			this.$errors.failWithoutHelp(`The device with identifier ${debugData.deviceIdentifier} is unreachable. Make sure it is Trusted and try again.`);
+		}
+
 		if (!(await device.applicationManager.isApplicationInstalled(debugData.applicationIdentifier))) {
 			this.$errors.failWithoutHelp(`The application ${debugData.applicationIdentifier} is not installed on device with identifier ${debugData.deviceIdentifier}.`);
 		}
@@ -51,9 +54,9 @@ class DebugService extends EventEmitter {
 				this.$errors.failWithoutHelp(`Debugging on iOS devices is not supported for ${platform()} yet.`);
 			}
 
-			result = await debugService.debug(debugData, debugOptions);
+			result = await debugService.debug<string[]>(debugData, debugOptions);
 		} else if (this.$mobileHelper.isAndroidPlatform(device.deviceInfo.platform)) {
-			result = await debugService.debug(debugData, debugOptions);
+			result = await debugService.debug<string[]>(debugData, debugOptions);
 		}
 
 		return _.first(result);

lib/services/debug-service.ts

@@ -197,7 +197,13 @@ class IOSDebugService extends DebugServiceBase implements IPlatformDebugService
 			this._socketProxy = await this.$socketProxyFactory.createWebSocketProxy(this.getSocketFactory(device));
 
 			const commitSHA = "02e6bde1bbe34e43b309d4ef774b1168d25fd024"; // corresponds to 55.0.2883 Chrome version
-			return `chrome-devtools://devtools/remote/serve_file/@${commitSHA}/inspector.html?experiments=true&ws=localhost:${this._socketProxy.options.port}`;
+			let chromeDevToolsPrefix = `chrome-devtools://devtools/remote/serve_file/@${commitSHA}`;
+
+			if (debugOptions.useBundledDevTools) {
+				chromeDevToolsPrefix = "chrome-devtools://devtools/bundled";
+			}
+
+			return `${chromeDevToolsPrefix}/inspector.html?experiments=true&ws=localhost:${this._socketProxy.options.port}`;
 		} else {
 			this._socketProxy = await this.$socketProxyFactory.createTCPSocketProxy(this.getSocketFactory(device));
 			await this.openAppInspector(this._socketProxy.address(), debugData, debugOptions);

lib/services/ios-debug-service.ts

@@ -19,7 +19,8 @@ describe("nativescript-cli-lib", () => {
 		localBuildService: ["build"],
 		deviceLogProvider: null,
 		npm: ["install", "uninstall", "view", "search"],
-		extensibilityService: ["loadExtensions", "getInstalledExtensions", "installExtension", "uninstallExtension"]
+		extensibilityService: ["loadExtensions", "getInstalledExtensions", "installExtension", "uninstallExtension"],
+		debugService: ["debug"]
 	};
 
 	const pathToEntryPoint = path.join(__dirname, "..", "lib", "nativescript-cli-lib.js").replace(/\\/g, "\\\\");