chore: prepare @liferay/cli and target-platforms review

projects/js-toolkit/packages/liferay-cli/README.md

@@ -1,3 +1,223 @@
 # @liferay/cli
 
-This project hosts the Liferay JS Toolkit CLI Tool
+This project hosts the Liferay JS Toolkit CLI Tool.
+
+Inspired by other frameworks, like React, Angular, or Vue.js, the Liferay JS
+Toolkit provides a CLI tool to invoke all implemented features, like project
+generation, build, deployment, etc.
+
+> 👀 Note that this tool still uses the JS Toolkit under the hood, so please
+> refer to
+> [its documentation](https://github.com/liferay/liferay-frontend-projects/blob/master/maintenance/projects/js-toolkit/docs/README.md)
+> for more details on configuration and behavior.
+
+## Installation
+
+The `@liferay/cli` tool may be installed globally using `npm install -g @liferay/cli` or `yarn global add @liferay/cli`, to make it available from the
+command line.
+
+However, if you don't want to mess with global installations, you can also run
+it using `npx @liferay/cli ...`. This ensures that you always use the latest
+version, and won't install it locally.
+
+If you install globally, simple invoke `liferay` from the command line, which
+is the name of the
+[binary provided by `@liferay/cli`](https://github.com/liferay/liferay-frontend-projects/blob/master/projects/js-toolkit/packages/liferay-cli/bin/liferay.js).
+
+## Available actions
+
+Currently, the `@liferay/cli` tool supports the following features:
+
+-   [Project generation](#project-generation)
+-   [Project adaptation](#project-adaptation)
+-   [Project build](#project-build)
+-   [Project deployment](#project-deployment)
+-   [Project clean](#project-clean)
+
+## Project generation
+
+Project generation lets you create new projects for the following
+frameworks[^1]:
+
+-   [React](https://reactjs.org/)
+-   [Angular](https://angular.io/)
+-   [Vue.js](https://vuejs.org/)
+
+> 👀 This feature is a replacement of the
+> [older Yeoman Liferay JavaScript generator](https://github.com/liferay/liferay-frontend-projects/tree/master/maintenance/projects/js-toolkit/packages/generator-liferay-js)
+> but it doesn't rely on Yeoman any more.
+
+### Usage
+
+```sh
+$ liferay new my-project ↩
+```
+
+The above command will start a wizard that will generate a project called
+`my-project` in the current folder. Simply answer the questions you are asked,
+and let the generator do its duties.
+
+Once the project is created, you may change to its folder and run
+`npm|yarn install` to install the dependencies, then invoke the supported
+actions (like `build`, `deploy`, etc.) with `npm|yarn run <command>`.
+
+#### Target platform
+
+One of the key questions in the wizard is related to the platform you wish to
+target. A target platform defines:
+
+-   The set of rules to build the project
+-   The default dependencies of the project
+
+So, for example, when using
+[`portal-7.4-ga1`](https://github.com/liferay/liferay-frontend-projects/tree/master/target-platforms/packages/portal-7.4-ga1)
+you are saying that your project will be deployed to Liferay Portal CE 7.4 GA1
+and thus your project will have access to
+[any JavaScript API available in that version](https://github.com/liferay/liferay-frontend-projects/blob/master/target-platforms/packages/portal-7.4-ga1/config.json#L21-L171)
+(for instance, if you use React, the copy of `react` that comes bundled with
+Liferay Portal will be used in your project, instead of referring to a new one,
+local to the project).
+
+Note that, if you don't want to couple your project to any version of
+Liferay Portal, you may choose to use the
+[`portal-agnostic`](https://github.com/liferay/liferay-frontend-projects/tree/master/target-platforms/packages/portal-agnostic)
+target platform. By choosing the agnostic platform your project will not be
+injected with any of the packages that come bundled with Liferay Portal.
+
+## Project adaptation
+
+Project adaptation lets you transform you native React, Angular and Vue.js
+projects[^1] into Liferay widgets that you can deploy to your Liferay Portal
+instance[^2].
+
+> 👀 This feature is a replacement of the
+> [older Yeoman Liferay JavaScript generator](https://github.com/liferay/liferay-frontend-projects/tree/master/maintenance/projects/js-toolkit/packages/generator-liferay-js)
+> but it doesn't rely on Yeoman any more.
+
+### Usage
+
+In your native project's directory run:
+
+```sh
+$ liferay adapt ↩
+```
+
+The above command will start a wizard that will adapt your project to be
+deployable to Liferay portal.
+
+Once the project is adapted you may use the `build:liferay`, `deploy:liferay`,
+`clean:liferay`, etc. tasks to perform the same tasks you would do for a true
+Liferay project (ie: one that had been generated with `liferay new`).
+
+Learn more about project adaptation in
+[JS Toolkit's documentation on adaptation](https://github.com/liferay/liferay-frontend-projects/blob/master/maintenance/projects/js-toolkit/docs/How-to-adapt-most-popular-frameworks-projects.md#supported-projects).
+
+## Project build
+
+The `build` command will build your project and leave the resulting JAR file in
+the `dist` directory. You may then deploy it to a Liferay Portal instance
+copying the file by hand, or using the [Liferay deployment](#project-deployment)
+feature.
+
+### Usage
+
+```sh
+$ liferay build ↩
+
+# or
+
+$ npm run build ↩
+
+# or
+
+$ yarn build ↩
+```
+
+Note that `npm|yarn run build` is an alias to `liferay build` (you can see that
+by inspecting your project's `package.json` file).
+
+## Project deployment
+
+The `deploy` command will copy the JAR file created by the
+[project build](#project-build), in the `dist` directory, to your local Liferay
+Portal instance.
+
+The first time you run this task it will ask you for your Liferay Portal
+directory and store your answer in a `.liferay.json` file in your project for
+subsequent runs.
+
+### Usage
+
+```sh
+$ liferay deploy ↩
+
+# or
+
+$ npm run deploy ↩
+
+# or
+
+$ yarn deploy ↩
+```
+
+Note that `npm|yarn run deploy` is an alias to `liferay deploy` (you can see
+that by inspecting your project's `package.json` file).
+
+## Project clean
+
+The `clean` command will delete the `build` and `dist` directories created by
+[project build](#project-build) and [project deployment](#project-deployment)
+tasks.
+
+### Usage
+
+```sh
+$ liferay clean ↩
+
+# or
+
+$ npm run clean ↩
+
+# or
+
+$ yarn clean ↩
+```
+
+Note that `npm|yarn run clean` is an alias to `liferay clean` (you can see
+that by inspecting your project's `package.json` file).
+
+## Internal architecture
+
+The big majority of `@liferay/cli`'s source code is devoted to project
+generation and adaptation, this what previously located in our Yeoman
+generator.
+
+The rest of the commands (those used on generated/adapted projects) are simply
+delegated to the selected target platform (see
+[Target platform](#target-platform) above).
+
+That means that, in those cases the `liferay` command is simply a bridge that
+looks inside your project's `node_modules` folder to locate the selected target
+platform and invoke it to do its duties.
+
+This eases maintenance and evolution of `@liferay/cli` because we don't need to
+maintain a huge monolith of code targeting disparate targets.
+
+To gain more insights on target platforms and what they are intended for, you
+may have a look at
+[their project directory](https://github.com/liferay/liferay-frontend-projects/tree/master/target-platforms).
+
+---
+
+[^1]:
+    We aim to support the latest version of these frameworks but, given the
+    fast pace at which they evolve, there may be some lag between the time when a
+    framework's version is published and the time `@liferay/cli` supports it.
+
+[^2]:
+    Note that adaptation is a best effort heuristic process so don't expect
+    every native framework functionality to work when a project is adapted. This
+    is mainly due to the fact that there's some mismatch between these
+    frameworks' application model (they assume a SPA deployed as a single webapp)
+    and the one of Liferay, that assumes that many unrelated portlets cooperate
+    together to produce a single HTML page.

projects/js-toolkit/packages/liferay-cli/package.json

@@ -6,6 +6,7 @@
 	"dependencies": {
 		"@liferay/js-toolkit-core": "^4.0.0",
 		"inquirer": "^7.3.1",
+		"liferay-npm-build-tools-common": "^2.27.0",
 		"resolve": "^1.8.1",
 		"update-check": "^1.5.4",
 		"yargs": "^14.0.0"
@@ -34,5 +35,5 @@
 		"preversion": "liferay-workspace-scripts ci",
 		"test": "liferay-workspace-scripts test"
 	},
-	"version": "1.0.0-pre.2"
+	"version": "1.0.0"
 }

support/packages/local-npm/lib/index.js

@@ -94,7 +94,7 @@ function publish(projects) {
 
 		console.log(`       ${pkgId}`);
 
-		run('npm', 'unpublish', pkgId);
+		run('npm', 'unpublish', pkgId, {lenient: true});
 		run('yarn', 'cache', 'clean', pkgId);
 	});
 
@@ -150,6 +150,7 @@ function registrySet(which) {
 
 function run(cmd, ...args) {
 	let options = {
+		lenient: false, // set to true to ignore error return codes
 		shell: true,
 		stdio: 'pipe',
 	};
@@ -171,7 +172,7 @@ function run(cmd, ...args) {
 		process.exit(1);
 	}
 
-	if (result.status !== 0) {
+	if (!options.lenient && result.status !== 0) {
 		if (result.stdout) {
 			console.error(result.stdout.toString());
 			console.error(result.stderr.toString());

target-platforms/README.md

@@ -1,4 +1,4 @@
-# liferay-target-platforms
+# target-platforms
 
 This repository holds Target Platforms for the Liferay CE Portal and DXP
 products.
@@ -9,21 +9,73 @@ A Target Platform is a single `npm` dependency that you may use in your
 JavaScript projects to have all needed dependencies and tools to deploy it in a
 specific release of Liferay CE Portal or DXP.
 
-The Target Platform dependencies takes care of all configuration details for
-you, so that you don't need to bother about dependency numbers or configuring
-the parts of the build that can be inferred from the target version of Liferay
-CE Portal/DXP.
+The Target Platform takes care of all configuration details for you, so that
+you don't need to bother about dependency numbers or configuring the parts of
+the build that can be inferred from the target version of Liferay CE
+Portal/DXP.
 
 ## Supported Target Platforms
 
-Right now we support the following platforms:
+To view the list of supported target platforms browse
+[the packages folder](./packages).
+
+All platform names describe the target product and version (for instance:
+`portal-7.4-ga1` refers to Liferay CE Portal 7.4 GA1) except for some special
+ones that are listed here:
+
+-   `portal-adapt-angular-cli`: a special target platform that is used when
+    adapting native Angular projects for deployment to Liferay.
+-   `portal-adapt-create-react-app`: a special target platform that is used when
+    adapting native React projects for deployment to Liferay.
+-   `portal-adapt-vue-cli`: a special target platform that is used when adapting
+    native Vue.js projects for deployment to Liferay.
+-   `portal-agnostic`: a target platform to avoid coupling of the project with
+-   any
+    specific Liferay version.
+-   `portal-master`: an internal target platform used by this project to be able
+    to target current development version of Liferay Portal.
 
 ## How to use Target Platforms
 
-Even though you can use Target Platforms alone, they are intended to be
-pre-configured by tools like the
-[JS Toolkit Generator](https://github.com/liferay/liferay-frontend-projects/blob/master/maintenance/projects/js-toolkit/docs/How-to-use-generator-liferay-js.md)
-or
-[Liferay Workspace](https://learn.liferay.com/dxp/latest/en/developing-applications/tooling/liferay-workspace/what-is-liferay-workspace.html)
-so please refer to those tools' documentation on how to leverage Target
-Platforms.
+Target platforms are provided as a npm dependency in projects created with the
+[`@liferay/cli` tool](https://github.com/izaera/liferay-frontend-projects/blob/doc-toolkit-3/projects/js-toolkit/packages/liferay-cli).
+They provide all dependencies needed to build, deploy and run the project when
+targeting the selected platform.
+
+That means you don't need to do anything specific to use them. `@liferay/cli`
+will inject all Liferay dependencies needed in your projects.
+
+### A note about contents of target platforms
+
+Among other things, target platforms contain:
+
+-   The npm dependencies: for example
+    [these ones](https://github.com/izaera/liferay-frontend-projects/blob/doc-toolkit-3/target-platforms/packages/portal-7.4-ga1/package.json#L5-L131).
+-   The `liferay-npm-bundler` configuration used to build the project: for
+-   example
+    [this one](https://github.com/izaera/liferay-frontend-projects/blob/doc-toolkit-3/target-platforms/packages/portal-7.4-ga1/config.json).
+-   The `liferay.js` file that will be invoked by the `@liferay/cli` to delegate
+    its tasks to the target platform: for example
+    [this one](https://github.com/izaera/liferay-frontend-projects/blob/doc-toolkit-3/target-platforms/packages/portal-7.4-ga1/liferay.js).
+
+Note that `@liferay/cli` delegates tasks like `build`, `deploy`, etc. to the
+aforementioned `liferay.js` scripts inside target platforms. This is a strategy
+to make evolution and support of `@liferay/cli` easier.
+
+However, at the same time, most target platforms use the same code so, instead
+of replicating it for each platform, we
+["undo" the delegation referring to shared projects](https://github.com/izaera/liferay-frontend-projects/blob/doc-toolkit-3/target-platforms/packages/portal-7.4-ga1/liferay.js#L8)
+that implement the logic for platforms of the same kind.
+
+Two examples of those shared projects are:
+
+-   [portal-base](https://github.com/izaera/liferay-frontend-projects/tree/doc-toolkit-3/projects/js-toolkit/packages/portal-base):
+    contains logic to build projects targeting Liferay Portal.
+-   [portal-adapt-base](https://github.com/izaera/liferay-frontend-projects/tree/doc-toolkit-3/projects/js-toolkit/packages/portal-adapt-base):
+    contains logic to build adapted Angular, React and Vue.js projects.
+
+We may add or refactor these shared projects in the future, depending on how
+the list of target platforms and types evolve but, thanks to the `@liferay/cli`
+delegation and the `liferay.js` files contained inside target platforms, nobody
+should be affected by those changes, as they will happen transparently to the
+projects using the target platforms.