feat: run deploy hooks (#54)

* feat: run deploy hooks

* chore: update command snapshot

* fix: work with Deployables

* chore: bump oclif/core

* chore: bump plugin-project-utils

* fix: use latest plugin-project-utils

* chore: add docs

* fix: set max listeners

* feat: handle non-interactive scenario

* chore: code review

* chore: bump plugin-command-snapshot

* chore: bump plugin-command-snapshot

Author: mdonnalley

CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Add a new project command
+
+The project plugin does not have any commands for deploying or or retrieving specific pieces of a salesforce project (e.g. metadata to a scratch or functions to a compute environment). Instead, we ask developers to create their own plugin with those commands. In order for the `project deploy` or `project retrieve` command to know about the individual plugins, each plugin must implement an [oclif hook](https://oclif.io/docs/hooks) which returns [`Deployers`](https://github.com/salesforcecli/plugin-project-utils/blob/main/src/deployer.ts) and `Retirevers`.
+
+This method allows developers to own their own plugins while also allowing a simple way for the overarching `project` topic to interact with those plugins.
+
+## Deploy
+
+To implement the oclif hook for the deploy commands, you must implement a `project:findDeployers` hook in your project. To do this you need to specify the location of the hook in your package.json and implement the hook. For example, in your package.json
+
+```json
+"oclif": {
+  "hooks": {
+    "project:findDeployers": "./lib/hooks/findDeployers"
+  }
+}
+```
+
+And then in your code, you'll have a `findDeployers.ts` file under the `hooks` directory. Here's an example of a very basic implementation:
+
+```typescript
+// hooks/findDeployers.ts
+import { Deployer, Options } from '@salesforce/plugin-project-utils';
+
+const hook = async function (options: Options): Promise<Deployer[]> {
+  return []; // return your Deployers here
+};
+
+export default hook;
+```
+
+### Deployers
+
+The [Deployer class](https://github.com/salesforcecli/plugin-project-utils/blob/main/src/deployer.ts) is a simple interface for setting up and executing deploys. It has two primary methods, `setup` and `deploy`.
+
+The `setup` method allows developers to do any setup that's required before a deploy can be executed. This could be anything - in some cases you might need to prompt the user for additional information or in other cases you might need to do some environment setup.
+
+The `deploy` method is where you will write the code that executes the deploy. Again, developers have full autonomy over how this is implemented.

README.md

@@ -22,6 +22,8 @@ sf plugins:install [email protected]
 8. Sign CLA (see [CLA](#cla) below).
 9. Send us a pull request when you are done. We'll review your code, suggest any needed changes, and merge it in.
 
+To add a new project command see the [contributing guide](CONTRIBUTING.md)
+
 ### CLA
 
 External contributors will be required to sign a Contributor's License
@@ -75,10 +77,10 @@ OPTIONS
   --target-env=target-env  TBD
 
 DESCRIPTION
-  Deploy a project, including org metadata and functions. Be default, the deploy analyze your project and assume 
-  sensible defaults when possible, otherwise it will prompt. To always prompt and not assume defaults, use 
+  Deploy a project, including org metadata and functions. Be default, the deploy analyze your project and assume
+  sensible defaults when possible, otherwise it will prompt. To always prompt and not assume defaults, use
   "--interctive".
-  To run specialized deploys, especially when interactivity isn't an option like continuous deployment, used the scoped 
+  To run specialized deploys, especially when interactivity isn't an option like continuous deployment, used the scoped
   deploy commands like "sf project deploy org" or "sf project deploy functions"
 
 EXAMPLES

command-snapshot.json

@@ -1,7 +1,9 @@
 [
-  {
-    "command": "project:deploy",
-    "plugin": "@salesforce/plugin-project",
-    "flags": ["directory", "interactive", "target-env"]
-  }
-]
+    {
+        "command": "project:deploy",
+        "plugin": "@salesforce/plugin-project",
+        "flags": [
+            "interactive"
+        ]
+    }
+]

messages/messages.json

@@ -0,0 +1,25 @@
+# summary
+
+Deploy a project interactively to any Salesforce environment.
+
+# description
+
+The command first analyzes your project, active or logged-into environments, and local defaults to determine what to deploy and where. The command then prompts you for information about this particular deployment and provides intelligent choices based on its analysis.
+
+For example, if your local project contains a package directory with metadata source files, the command asks if you want to deploy that Salesforce app to an org. The command lists your connected orgs and asks which one you want to deploy to.  If the command finds Apex tests, it asks if you want to run them and at which level.
+
+Similarly, if the command finds a local functions directory, the command prompts if you want to deploy it and to which compute environment. The command prompts and connects you to a compute environment of your choice if you’re not currently connected to any.
+
+This command must be run from within a project.
+
+The command stores your responses in a local file and uses them as defaults when you rerun the command. Specify --interactive to force the command to reprompt.
+
+Use this command for quick and simple deploys. For more complicated deployments, use the environment-specific commands, such as "sf project deploy org", that provide additional flags.
+
+# examples
+
+- <%= config.bin %> <%= command.id %>
+
+# flags.interactive.summary
+
+Force the CLI to prompt for all deployment inputs.

messages/project.deploy.md

@@ -5,17 +5,20 @@
   "author": "Salesforce",
   "bugs": "https://github.com/forcedotcom/cli/issues",
   "dependencies": {
-    "@oclif/core": "^0.5.0",
-    "@salesforce/core": "^2.23.1",
+    "@oclif/core": "^0.5.19",
+    "@salesforce/core": "^3.1.1-v3.1",
+    "@salesforce/plugin-project-utils": "^0.0.5",
     "tslib": "^2"
   },
   "devDependencies": {
-    "@oclif/dev-cli": "^1",
-    "@oclif/plugin-command-snapshot": "^2.1.1",
+    "@oclif/dev-cli": "^1.26.0",
+    "@oclif/plugin-command-snapshot": "^2.2.2",
     "@salesforce/cli-plugins-testkit": "^1.1.5",
     "@salesforce/dev-config": "^2.1.2",
     "@salesforce/dev-scripts": "^0.9.14",
     "@salesforce/plugin-command-reference": "^1.3.0",
+    "@salesforce/plugin-functions": "^0.2.13",
+    "@salesforce/plugin-project-org": "^0.0.1",
     "@salesforce/prettier-config": "^0.0.2",
     "@salesforce/ts-sinon": "1.3.18",
     "@typescript-eslint/eslint-plugin": "^4.2.0",
@@ -73,7 +76,9 @@
     "devPlugins": [
       "@oclif/plugin-help",
       "@oclif/plugin-command-snapshot",
-      "@salesforce/plugin-command-reference"
+      "@salesforce/plugin-command-reference",
+      "@salesforce/plugin-project-org",
+      "@salesforce/plugin-functions"
     ],
     "topics": {
       "project": {

messages/project.json

@@ -1,41 +1,103 @@
 /*
- * Copyright (c) 2020, salesforce.com, inc.
+ * Copyright (c) 2021, salesforce.com, inc.
  * All rights reserved.
  * Licensed under the BSD 3-Clause license.
  * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
  */
 
-import * as os from 'os';
 import { Command, Flags } from '@oclif/core';
-import { Messages } from '@salesforce/core';
+import { fs, Messages } from '@salesforce/core';
+import { Env } from '@salesforce/kit';
+import { Deployable, Deployer, generateTableChoices, Prompter } from '@salesforce/plugin-project-utils';
 
 Messages.importMessagesDirectory(__dirname);
 
-const messages = Messages.loadMessages('@salesforce/plugin-project', 'project');
-
-export type DeployResult = Record<string, unknown>;
+const messages = Messages.loadMessages('@salesforce/plugin-project', 'project.deploy');
 
 export default class ProjectDeploy extends Command {
-  public static description = messages.getMessage('deploy.commandDescription');
-
-  public static examples = messages.getMessage('deploy.examples').split(os.EOL);
+  public static summary = messages.getMessage('summary');
+  public static description = messages.getMessage('description');
+  public static examples = messages.getMessages('examples');
+  public static disableJsonFlag = true;
 
   public static flags = {
-    directory: Flags.string({
-      description: 'directory to deploy',
-    }),
-    'target-env': Flags.string({
-      description: 'TBD',
-      multiple: true,
-    }),
     interactive: Flags.boolean({
-      description: 'TBD',
+      summary: messages.getMessage('flags.interactive.summary'),
     }),
   };
 
-  public async run(): Promise<DeployResult> {
+  public async run(): Promise<void> {
+    process.setMaxListeners(new Env().getNumber('SF_MAX_EVENT_LISTENERS') || 1000);
     const { flags } = await this.parse(ProjectDeploy);
-    this.log(JSON.stringify(flags));
-    return {};
+
+    flags.interactive = await this.isInteractive(flags.interactive);
+
+    this.log('Analyzing project');
+
+    let deployers = (await this.config.runHook('project:findDeployers', {})) as Deployer[];
+    deployers = deployers.reduce((x, y) => x.concat(y), [] as Deployer[]);
+
+    if (deployers.length === 0) {
+      this.log('Found nothing in the project to deploy');
+    } else {
+      deployers = await this.selectDeployers(deployers);
+
+      if (deployers.length === 0) {
+        this.log('Nothing was selected to deploy.');
+      }
+
+      for (const deployer of deployers) {
+        await deployer.setup(flags);
+        await deployer.deploy();
+      }
+    }
+  }
+
+  /**
+   * If the deploy file exists, we do not want the command to be interactive. But if the file
+   * does not exist then we want to force the command to be interactive.
+   */
+  public async isInteractive(interactive: boolean): Promise<boolean> {
+    if (interactive) return true;
+    const deployFileExists = await fs.fileExists('project-deploy-options.json');
+    return deployFileExists ? false : true;
+  }
+
+  public async selectDeployers(deployers: Deployer[]): Promise<Deployer[]> {
+    const deployables: Deployable[] = deployers.reduce((x, y) => x.concat(y.deployables), [] as Deployable[]);
+    const columns = { name: 'APP OR PACKAGE', type: 'TYPE', path: 'PATH' };
+    const options = deployables.map((deployable) => ({
+      name: deployable.getAppName(),
+      type: deployable.getAppType(),
+      path: deployable.getAppPath(),
+      value: deployable,
+    }));
+    const prompter = new Prompter();
+    const responses = await prompter.prompt<{ deployables: Deployable[] }>([
+      {
+        name: 'deployables',
+        message: 'Select apps and packages to deploy:',
+        type: 'checkbox',
+        choices: generateTableChoices<Deployable>(columns, options),
+      },
+    ]);
+
+    const chosenDeployers: Map<Deployer, Deployable[]> = new Map();
+    for (const deployable of responses.deployables) {
+      const parent = deployable.getParent();
+      if (chosenDeployers.has(parent)) {
+        const existing = chosenDeployers.get(parent) || [];
+        chosenDeployers.set(parent, [...existing, deployable]);
+      } else {
+        chosenDeployers.set(parent, [deployable]);
+      }
+    }
+
+    const final: Deployer[] = [];
+    for (const [parent, children] of chosenDeployers.entries()) {
+      parent.selectDeployables(children);
+      final.push(parent);
+    }
+    return final;
   }
 }