Expose createProject to public API (#2483)

* Expose createProject to public API

In order to allow creating a new NativeScript project when {N} CLI is required as a library, we should add createProject method to public API. This requires some modifications in method's implementation - we cannot rely on `$options` as it is not populated correctly when the CLI is used as a library. Pass object describing the project that we have to create. Fix unit tests accordingly and uncomment (and fix) all tests in project-service.

Add unit tests that will check if a method is really exposed in public API.

Add PublicAPI.md file, which describes all methods that can be used when using CLI as a library.

* Require only modules we need from mobile-cli-lib

Author: rosen-vladimirov

PublicAPI.md

@@ -0,0 +1,121 @@
+Public API
+==
+
+This document describes all methods that can be invoked when NativeScript CLI is required as library, i.e.
+
+<table>
+	<tr>
+        <td>
+        	JavaScript
+        </td>
+        <td>
+        	TypeScript
+        </td>
+    </tr>
+    <tr>
+    	<td>
+<pre lang="javascript">
+const tns = require("nativescript");
+</pre>
+        </td>
+    	<td>
+<pre lang="typescript">
+import * as tns from "nativescript";
+</pre>
+        </td>
+    </tr>
+
+</table>
+
+## Module projectService
+
+`projectService` modules allow you to create new NativeScript application.
+
+* `createProject(projectSettings: IProjectSettings): Promise<void>` - Creates new NativeScript application. By passing `projectSettings` argument you specify the name of the application, the template that will be used, etc.:
+```TypeScript
+/**
+ * Describes available settings when creating new NativeScript application.
+ */
+interface IProjectSettings {
+	/**
+	 * Name of the newly created application.
+	 */
+	projectName: string;
+
+	/**
+	 * Selected template from which to create the project. If not specified, defaults to hello-world template.
+	 * Template can be any npm package, local dir, github url, .tgz file.
+	 * If it is set to `angular` or `ng`, default NativeScript Angular Hello World template will be used.
+	 * If it is set to `typescript` or `tsc`, default NativeScript TypeScript Hello World template will be used.
+	 */
+	template?: string;
+
+	/**
+	 * Application identifier for the newly created application. If not specified, defaults to org.nativescript.<projectName>.
+	 */
+	appId?: string;
+
+	/**
+	 * Path where the project will be created. If not specified, defaults to current working dir.
+	 */
+	pathToProject?: string;
+
+	/**
+	 * Defines if invalid application name can be used for project creation.
+	 */
+	force?: boolean;
+
+	/**
+	 * Defines whether the `npm install` command should be executed with `--ignore-scripts` option.
+	 * When it is passed, all scripts (postinstall for example) will not be executed.
+	 */
+	ignoreScripts?: boolean;
+}
+```
+
+Sample usage:
+<table>
+	<tr>
+        <td>
+        	JavaScript
+        </td>
+        <td>
+        	TypeScript
+        </td>
+    </tr>
+    <tr>
+    	<td>
+<pre lang="javascript">
+const projectSettings = {
+	projectName: "my-ns-app",
+    template: "ng",
+    pathToProject: "/home/my-user/project-dir"
+};
+
+tns.projectService.createProject(projectSettings)
+	.then(() => console.log("Project successfully created."))
+    .catch((err) => console.log("Unable to create project, reason: ", err);
+</pre>
+        </td>
+    	<td>
+<pre lang="typescript">
+const projectSettings: IProjectSettings = {
+	projectName: "my-ns-app",
+    template: "ng",
+    pathToProject: "/home/my-user/project-dir"
+};
+
+tns.projectService.createProject(projectSettings)
+	.then(() => console.log("Project successfully created."))
+    .catch((err) => console.log("Unable to create project, reason: ", err);
+</pre>
+        </td>
+    </tr>
+</table>
+
+## 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.

lib/bootstrap.ts

@@ -7,7 +7,7 @@ $injector.require("nativescript-cli", "./nativescript-cli");
 
 $injector.require("projectData", "./project-data");
 $injector.require("projectDataService", "./services/project-data-service");
-$injector.require("projectService", "./services/project-service");
+$injector.requirePublic("projectService", "./services/project-service");
 $injector.require("androidProjectService", "./services/android-project-service");
 $injector.require("iOSProjectService", "./services/ios-project-service");
 $injector.require("iOSProvisionService", "./services/ios-provision-service");

lib/commands/create-project.ts

@@ -23,7 +23,14 @@ export class CreateProjectCommand implements ICommand {
 			selectedTemplate = this.$options.template;
 		}
 
-		await this.$projectService.createProject(args[0], selectedTemplate);
+		await this.$projectService.createProject({
+			projectName: args[0],
+			template: selectedTemplate,
+			appId: this.$options.appid,
+			pathToProject: this.$options.path,
+			force: this.$options.force,
+			ignoreScripts: this.$options.ignoreScripts
+		});
 	}
 }
 

lib/common

@@ -1,6 +1,49 @@
+/**
+ * Describes available settings when creating new NativeScript application.
+ */
+interface IProjectSettings {
+	/**
+	 * Name of the newly created application.
+	 */
+	projectName: string;
+
+	/**
+	 * Selected template from which to create the project. If not specified, defaults to hello-world template.
+	 * Template can be any npm package, local dir, github url, .tgz file.
+	 * If it is set to `angular` or `ng`, default NativeScript Angular Hello World template will be used.
+	 * If it is set to `typescript` or `tsc`, default NativeScript TypeScript Hello World template will be used.
+	 */
+	template?: string;
+
+	/**
+	 * Application identifier for the newly created application. If not specified, defaults to org.nativescript.<projectName>.
+	 */
+	appId?: string;
+
+	/**
+	 * Path where the project will be created. If not specified, defaults to current working dir.
+	 */
+	pathToProject?: string;
+
+	/**
+	 * Defines if invalid application name can be used for project creation.
+	 */
+	force?: boolean;
+
+	/**
+	 * Defines whether the `npm install` command should be executed with `--ignore-scripts` option.
+	 * When it is passed, all scripts (postinstall for example) will not be executed.
+	 */
+	ignoreScripts?: boolean;
+}
 
 interface IProjectService {
-	createProject(projectName: string, selectedTemplate?: string): Promise<void>;
+	/**
+	 * Creates new NativeScript application.
+	 * @param {any} projectSettings Options describing new project - its name, appId, path and template from which to be created.
+	 * @returns {Promise<void>}
+	 */
+	createProject(projectSettings: IProjectSettings): Promise<void>;
 }
 
 interface IProjectData {

lib/definitions/project.d.ts

@@ -5,4 +5,6 @@ $injector.overrideAlreadyRequiredModule = true;
 // Temporary!!! Should not require appbuilder's entry point of mobile-cli-lib,
 // but once we separate logics in mobile-cli-lib, we should be able to require only specific bootstrap.
 // Use this hack for now, as this will allow requiring {N} CLI as library directly and executing some device specific operations.
-require("./common/appbuilder/proton-bootstrap");
+$injector.requirePublic("companionAppsService", "./common/appbuilder/services/livesync/companion-apps-service");
+$injector.requirePublicClass("deviceEmitter", "./common/appbuilder/device-emitter");
+$injector.requirePublicClass("deviceLogProvider", "./common/appbuilder/device-log-provider");

lib/nativescript-cli-lib-bootstrap.ts

@@ -1,6 +1,7 @@
 import * as constants from "../constants";
 import * as path from "path";
 import * as shelljs from "shelljs";
+import { exportedPromise } from "../common/decorators";
 
 export class ProjectService implements IProjectService {
 
@@ -11,22 +12,29 @@ export class ProjectService implements IProjectService {
 		private $projectDataService: IProjectDataService,
 		private $projectHelper: IProjectHelper,
 		private $projectNameService: IProjectNameService,
-		private $projectTemplatesService: IProjectTemplatesService,
-		private $options: IOptions) { }
+		private $projectTemplatesService: IProjectTemplatesService) { }
+
+	@exportedPromise("projectService")
+	public async createProject(projectOptions: IProjectSettings): Promise<void> {
+		let projectName = projectOptions.projectName,
+			selectedTemplate = projectOptions.template;
 
-	public async createProject(projectName: string, selectedTemplate?: string): Promise<void> {
 		if (!projectName) {
 			this.$errors.fail("You must specify <App name> when creating a new project.");
 		}
-		projectName = await this.$projectNameService.ensureValidName(projectName, { force: this.$options.force });
 
-		let projectDir = path.join(path.resolve(this.$options.path || "."), projectName);
+		projectName = await this.$projectNameService.ensureValidName(projectName, { force: projectOptions.force });
+
+		const selectedPath = path.resolve(projectOptions.pathToProject || ".");
+		const projectDir = path.join(selectedPath, projectName);
+
 		this.$fs.createDirectory(projectDir);
+
 		if (this.$fs.exists(projectDir) && !this.$fs.isEmptyDir(projectDir)) {
 			this.$errors.fail("Path already exists and is not empty %s", projectDir);
 		}
 
-		let projectId = this.$options.appid || this.$projectHelper.generateDefaultAppId(projectName, constants.DEFAULT_APP_IDENTIFIER_PREFIX);
+		let projectId = projectOptions.appId || this.$projectHelper.generateDefaultAppId(projectName, constants.DEFAULT_APP_IDENTIFIER_PREFIX);
 		this.createPackageJson(projectDir, projectId);
 
 		this.$logger.trace(`Creating a new NativeScript project with name ${projectName} and id ${projectId} at location ${projectDir}`);
@@ -45,7 +53,7 @@ export class ProjectService implements IProjectService {
 			this.mergeProjectAndTemplateProperties(projectDir, templatePackageJsonData); //merging dependencies from template (dev && prod)
 			this.removeMergedDependencies(projectDir, templatePackageJsonData);
 
-			await this.$npm.install(projectDir, projectDir, { "ignore-scripts": this.$options.ignoreScripts });
+			await this.$npm.install(projectDir, projectDir, { "ignore-scripts": projectOptions.ignoreScripts });
 
 			let templatePackageJson = this.$fs.readJson(path.join(templatePath, "package.json"));
 			await this.$npm.uninstall(templatePackageJson.name, { save: true }, projectDir);

lib/services/project-service.ts

@@ -12,13 +12,34 @@ describe("nativescript-cli-lib", () => {
 		assert.deepEqual(jsonContent.main, expectedEntryPoint);
 	});
 
-	it("resolves publicly available module - deviceEmitter, when it is required", () => {
-		const pathToEntryPoint = path.join(__dirname, "..", "lib", "nativescript-cli-lib.js").replace(/\\/g, "\\\\");
-		// HACK: If we try to require the entry point directly, the below code will fail as mocha requires all test files before starting the tests.
-		// When the files are required, $injector.register adds each dependency to $injector's cache.
-		// For example $injector.register("errors", Errors) will add the errors module with its resolver (Errors) to $injector's cache.
-		// Calling $injector.require("errors", <path to errors file>), that's executed in our bootstrap, will fail, as the module errors is already in the cache.
-		// In order to workaround this problem, start new process and assert there. This way all files will not be required in it and $injector.require(...) will work correctly.
-		childProcess.execSync(`"${process.execPath}" ${nodeArgs.join(" ")} -e "var assert = require('chai').assert; var result = require('${pathToEntryPoint}'); assert.ok(result.deviceEmitter);"`);
+	const publicApi: any = {
+		deviceEmitter: null,
+		projectService: ["createProject"]
+	};
+
+	const pathToEntryPoint = path.join(__dirname, "..", "lib", "nativescript-cli-lib.js").replace(/\\/g, "\\\\");
+
+	_.each(publicApi, (methods: string[], moduleName: string) => {
+
+		it(`resolves publicly available module - ${moduleName}${methods && methods.length ? " and its publicly available methods: " + methods.join(", ") : ""}`, () => {
+			// HACK: If we try to require the entry point directly, the below code will fail as mocha requires all test files before starting the tests.
+			// When the files are required, $injector.register adds each dependency to $injector's cache.
+			// For example $injector.register("errors", Errors) will add the errors module with its resolver (Errors) to $injector's cache.
+			// Calling $injector.require("errors", <path to errors file>), that's executed in our bootstrap, will fail, as the module errors is already in the cache.
+			// In order to workaround this problem, start new process and assert there. This way all files will not be required in it and $injector.require(...) will work correctly.
+			let testMethod = `"${process.execPath}" ${nodeArgs.join(" ")} -e "` +
+				"var assert = require('chai').assert;" +
+				`var result = require('${pathToEntryPoint}');` +
+				`assert.ok(result.${moduleName});`;
+
+			_.each(methods, method => {
+				testMethod += `assert.ok(result.${moduleName}.${method});`;
+			});
+
+			testMethod += '"'; // Really important - close the " of node -e ""
+
+			childProcess.execSync(testMethod);
+		});
+
 	});
 });

test/nativescript-cli-lib.ts

@@ -10,8 +10,8 @@ let isProjectCreated: boolean;
 let dummyArgs = ["dummyArgsString"];
 
 class ProjectServiceMock implements IProjectService {
-	async createProject(projectName: string, selectedTemplate?: string): Promise<void> {
-		selectedTemplateName = selectedTemplate;
+	async createProject(projectOptions: IProjectSettings): Promise<void> {
+		selectedTemplateName = projectOptions.template;
 		isProjectCreated = true;
 	}
 }