Merge branch 'master' of https://github.com/markcocker/zowe-cli-cics-deploy-plugin

Author: markcocker

__tests__/__src__/environment/TestEnvironment.ts

@@ -147,7 +147,7 @@ export class TestEnvironment {
     private static async installPlugin(testEnvironment: ITestEnvironment) {
         let installScript: string = TemporaryScripts.SHEBANG;
         installScript += TemporaryScripts.ZOWE_BIN + " plugins install ../../../../\n"; // install plugin from root of project
-        installScript += TemporaryScripts.ZOWE_BIN + " plugins validate @brightside/zowe-cli-cics-deploy-plugin\n";
+        installScript += TemporaryScripts.ZOWE_BIN + " plugins validate zowe-cli-cics-deploy-plugin\n";
         installScript += TemporaryScripts.ZOWE_BIN + " cdep --help\n"; // check that the plugin help is available
         const scriptPath = testEnvironment.workingDir + "/install_plugin.sh";
         IO.writeFile(scriptPath, Buffer.from(installScript));
@@ -156,7 +156,7 @@ export class TestEnvironment {
 
         if (output.status !== 0) {
             throw new ImperativeError({
-                msg: "Install of '@brightside/zowe-cli-cics-deploy-plugin' plugin failed! You should delete the script: \n'" + scriptPath + "' " +
+                msg: "Install of 'zowe-cli-cics-deploy-plugin' plugin failed! You should delete the script: \n'" + scriptPath + "' " +
                     "after reviewing it to check for possible errors.\n Output of the plugin install command:\n" + output.stderr.toString() +
                     output.stdout.toString()
             });

__tests__/api/BundlePush/BundlePusher.test.ts

@@ -24,6 +24,12 @@ const DEFAULT_PARAMTERS: IHandlerParameters = {
     },
     profiles: {
         get: (type: string) => {
+            if (type === "zosmf") {
+              return zosmfProfile;
+            }
+            if (type === "ssh") {
+              return sshProfile;
+            }
             return {};
         }
     } as any,
@@ -60,6 +66,8 @@ const IS_NOT_DIRECTORY: any = {
   isDirectory: jest.fn((directory) => (false))
 };
 let consoleText = "";
+let zosmfProfile = {};
+let sshProfile = {};
 
 // Initialise xml2json before mocking anything
 const parser = require("xml2json");
@@ -99,6 +107,8 @@ describe("BundlePusher01", () => {
         readdirSpy = jest.spyOn(fs, "readdirSync").mockImplementation(() => ([]));
         lstatSpy = jest.spyOn(fs, "lstatSync").mockImplementation(() => ( IS_NOT_DIRECTORY ));
         consoleText = "";
+        zosmfProfile = {};
+        sshProfile = {};
     });
     afterEach(() => {
         jest.restoreAllMocks();
@@ -191,6 +201,38 @@ describe("BundlePusher01", () => {
         expect(zosMFSpy).toHaveBeenCalledTimes(1);
         expect(sshSpy).toHaveBeenCalledTimes(1);
     });
+    it("should complain with mismatching zOSMF and SSH profile host names", async () => {
+        zosmfProfile = { host: "wibble" };
+        sshProfile = { host: "wobble" };
+
+        await runPushTest("__tests__/__resources__/ExampleBundle01", true,
+              "PUSH operation completed.");
+        expect(consoleText).toContain("WARNING: ssh profile --host value 'wobble' does not match zosmf value 'wibble'.");
+    });
+    it("should not complain with matching zOSMF and SSH profile host names", async () => {
+        zosmfProfile = { host: "wibble" };
+        sshProfile = { host: "wibble" };
+
+        await runPushTest("__tests__/__resources__/ExampleBundle01", true,
+              "PUSH operation completed.");
+        expect(consoleText).not.toContain("WARNING: ssh profile");
+    });
+    it("should complain with mismatching zOSMF and SSH profile user names", async () => {
+        zosmfProfile = { host: "wibble", user: "fred" };
+        sshProfile = { host: "wibble", user: "joe" };
+
+        await runPushTest("__tests__/__resources__/ExampleBundle01", true,
+              "PUSH operation completed.");
+        expect(consoleText).toContain("WARNING: ssh profile --user value 'joe' does not match zosmf value 'fred'.");
+    });
+    it("should not complain with matching zOSMF and SSH profile user names", async () => {
+        zosmfProfile = { host: "wibble", user: "fred" };
+        sshProfile = { host: "wibble", user: "fred" };
+
+        await runPushTest("__tests__/__resources__/ExampleBundle01", true,
+              "PUSH operation completed.");
+        expect(consoleText).not.toContain("WARNING: ssh profile");
+    });
     it("should complain if remote bundle dir mkdir fails", async () => {
         createSpy.mockImplementationOnce(() => { throw new Error( "Injected Create error" ); });
         await runPushTestWithError("__tests__/__resources__/ExampleBundle01",  false,

docs/_data/sidebars/cdp_sidebar.yml

@@ -53,6 +53,9 @@ entries:
     - title: Log and trace files
       url: /cdp-Troubleshooting-General.html
       output: web
+    - title: Potential problems
+      url: /cdp-Troubleshooting-Symptoms.html
+      output: web
 
   - title: Commands - zowe profiles
     output: web

docs/js/customscripts.js

@@ -26,7 +26,7 @@ $(document).ready(function () {
      * Modified to use a fontawesome icon.
      */
     // get all <pre> elements
-    var allCodeBlocksElements = $("pre");
+    var allCodeBlocksElements = $("pre:not(.messageText)");
 
     allCodeBlocksElements.each(function (i) {
         // add different id for each code block

docs/pages/cdp/cdp-Troubleshooting-General.md

@@ -8,10 +8,54 @@ permalink: cdp-Troubleshooting-General.html
 folder: cdp
 ---
 
+### Console output
+All Zowe CLI cics deploy plugin commands send output to the console when invoked. Very often, enough information is provided for you to diagnose and pinpoint the cause of a problem. The commands `cics-deploy push`, `cics-deploy deploy` and `cics-deploy undeploy` accept a `--verbose` command-line option which can generate extra information if needed.  
+
 ### zowe.log
-The .zowe directory contains log files, profiles, and plug-ins. The location of this directory can be customised as described in [ Setting the Zowe CLI home directory](https://zowe.github.io/docs-site/latest/user-guide/cli-configuringcli.html#setting-the-zowe-cli-home-directory) and logging level set as described in [Setting Zowe CLI log levels](https://zowe.github.io/docs-site/latest/user-guide/cli-configuringcli.html#setting-zowe-cli-log-levels).
+The .zowe directory on your local workstation contains log files, profiles, and plug-ins. The location of this directory can be customised as described in [ Setting the Zowe CLI home directory](https://zowe.github.io/docs-site/latest/user-guide/cli-configuringcli.html#setting-the-zowe-cli-home-directory) and logging level set as described in [Setting Zowe CLI log levels](https://zowe.github.io/docs-site/latest/user-guide/cli-configuringcli.html#setting-zowe-cli-log-levels).
 
 You can use the following command to display messages written to the log file as they occur. This can be useful when troubleshooting problems when using `zowe` and `zowe cics-plugin` commands in another terminal.
-```console
-tail -f -n 0 ~/.zowe/zowe/logs/zowe.log
-```
+<ul id="profileTabs" class="nav nav-tabs">
+    <li class="active"><a href="#windows" data-toggle="tab">Windows</a></li>
+    <li><a href="#linux" data-toggle="tab">Linux</a></li>
+    <li><a href="#macos" data-toggle="tab">macOS</a></li>
+</ul>
+  <div class="tab-content">
+<div role="tabpanel" class="tab-pane active" id="windows">
+<p>On Windows, use the Powershell command 
+<br/><br/>
+<tt>Get-Content $env:USERPROFILE\.zowe\zowe\logs\zowe.log -Tail 30 -wait</tt></p>
+</div>
+
+<div role="tabpanel" class="tab-pane" id="linux">
+    <p>On Linux, use <tt>tail -f -n 0 ~/.zowe/zowe/logs/zowe.log</tt></p></div>
+
+<div role="tabpanel" class="tab-pane" id="macos">
+    <p>On macOS, use <tt>tail -f -n 0 ~/.zowe/zowe/logs/zowe.log</tt></p>
+</div>
+</div>
+
+### Node.js logs
+By default, CICS writes Node.js log files on z/OS to the `/tmp` directory. However, the `generate bundle` command creates a number of files including `nodejsapps/<my app name>.profile` (often referred to as the Node.js profile), which you can edit to specify a more convenient log file location. Such logs get written to the directory referenced by the environment variable `WORK_DIR`. For example, you might edit your Node.js profile so that it includes the line:
+
+```
+WORK_DIR=/u/<your user id>/nodelogs
+```
+This causes CICS to write all Node.js logs to the specified directory.
+
+Files typically written to `WORK_DIR` include:
+
+* LOG
+* STDERR
+* STDOUT
+* TRACE
+
+They can all be useful when identifying the cause of an error, especially STDERR.
+
+{% include note.html content="If you use [Visual Studio Code](https://code.visualstudio.com/) as your editor, there is a [zowe extension](https://github.com/zowe/vscode-extension-for-zowe) that enables you to interact with USS files from your local workstation." %}
+
+### JES job logs
+DFHDPLOY is a CICS utility which provides a set of commands that you can use to deploy, undeploy and set the state of CICS bundles. When you deploy or undeploy a Node.js application to or from CICS, a batch DFHDPLOY job is initiated on z/OS.
+
+If you are familiar with the z/OS environment, you can often find some useful diagnostics by accessing z/OS file assigned to the MSGUSR DD name for the deploy/undeploy job associated with your CICS region. If you are not so fluent with the world of z/OS, you may need to discuss your needs with one of your organization's CICS Systems Programmers.
+

docs/pages/cdp/cdp-Troubleshooting-Symptoms.md

@@ -0,0 +1,51 @@
+---
+title: Possible problems and their resolution
+tags: [troubleshooting]
+keywords:
+summary: "This section describes sets of problem symptoms, their possible causes and suggested solutions."
+sidebar: cdp_sidebar
+permalink: cdp-Troubleshooting-Symptoms.html
+folder: cdp
+---
+
+{% include important.html content="To definitively diagnose a problem based on the suggested symptoms, you will need to refer to one or more [system logs and traces](cdp-Troubleshooting-General) particularly the STDERR Node.js log and the file assigned the MSGUSR DD name in the relevant CICS DFHDPLOY job. Depending on your familiarity with z/OS and CICS, and your system privileges, you may need to consult a CICS Systems Programmer to get to the bottom of certain problems." %}
+
+## Deployment errors
+
+### Application incorrectly deploys in a DISABLED state
+*Possible cause*: The port requested by the application is already in use.
+
+*Suggested action*: Choose a new port number after double-checking that it is not in use. Redeploy the application using the new value for the port.
+
+{% include note.html content="An application in a `DISABLED` state does not necessarily indicate an error condition. The `cics-deploy deploy`, `cics-deploy push` and `cics-deploy undeploy` commands allow you to specify a `--target-state` option which you may deliberately choose to set to `DISABLED`." %}
+
+### Command error: DFHDPLOY stopped processing due to an error
+*Possible causes*:
+  * The `--scope` and/or `--cicsplex` settings for the current deploy profile are wrong, and don't correctly identify a current CICS system, CICS System Group and/or a correct CICSPlex respectively.
+
+  * The CMAS for the current CICSPlex is inactive.
+
+  * CPSM is not functioning correctly.
+
+*Representative output*:
+<pre class="messageText">
+16:22:50.058844 :  DFHDPLOY CICS TS APPLICATION DEPLOYMENT  2019/04/10 4:22pm
+16:22:50.059562 :  RELEASE: HCI7300.   SERVICE LEVEL: HCI7300.
+16:22:50.060903 :  *
+16:22:50.060910 :  SET CICSPLEX(CAPLE);
+16:22:50.062721 :  DFHRL2057S DFHDPLOY is unable to connect to CICSPLEX(CAPLE).
+16:22:50.065729 :  DFHRL2055I Errors have occurred, processing terminated.
+</pre>
+
+*Suggested actions*:
+  * Confirm that the `--scope` and `--cicsplex` settings are correct.
+
+  * Ask your CICS Systems Programmer to check that the CMAS for the current CICSPlex is alive and that CPSM is working properly.
+
+
+
+## General errors
+
+TBC 
+
+

package.json

@@ -34,8 +34,8 @@
     "xml2json": "^0.11.2"
   },
   "devDependencies": {
-    "@zowe/cli": "^5.3.0-alpha.201904291733",
-    "@zowe/imperative": "^4.1.2-alpha.201905061426",
+    "@zowe/cli": "^5.5.0",
+    "@zowe/imperative": "^4.1.2",
     "@types/fs-extra": "^5.0.5",
     "@types/jest": "^22.2.3",
     "@types/node": "^8.0.28",
@@ -66,8 +66,8 @@
     "uuid": "^3.3.2"
   },
   "peerDependencies": {
-    "@zowe/cli": "^3.2.0",
-    "@zowe/imperative": "^3.0.0"
+    "@zowe/cli": "^5.5.0",
+    "@zowe/imperative": "^4.1.2"
   },
   "jest": {
     "modulePathIgnorePatterns": [

src/api/BundlePush/BundlePusher.ts

@@ -11,7 +11,7 @@
 
 "use strict";
 
-import { IHandlerParameters, AbstractSession, ITaskWithStatus, TaskStage, TaskProgress, Logger } from "@zowe/imperative";
+import { IHandlerParameters, AbstractSession, ITaskWithStatus, TaskStage, TaskProgress, Logger, IProfile } from "@zowe/imperative";
 import { List, ZosmfSession, SshSession, Shell, Upload, IUploadOptions, ZosFilesAttributes, Create } from "@zowe/cli";
 import { BundleDeployer } from "../BundleDeploy/BundleDeployer";
 import { Bundle } from "../BundleContent/Bundle";
@@ -69,10 +69,15 @@ export class BundlePusher {
                                         "_" + bundle.getVersion();
     }
 
+    // Get the profiles
+    const zosMFProfile = this.getProfile("zosmf");
+    const sshProfile = this.getProfile("ssh");
+    this.validateProfiles(zosMFProfile, sshProfile);
+
     // Create a zOSMF session
-    const zosMFSession = await this.createZosMFSession();
+    const zosMFSession = await this.createZosMFSession(zosMFProfile);
     // Create an SSH session
-    const sshSession = await this.createSshSession();
+    const sshSession = await this.createSshSession(sshProfile);
 
     // Start a progress bar (but only in non-verbose mode)
     this.progressBar = { percentComplete: 0,
@@ -176,23 +181,43 @@ export class BundlePusher {
     }
   }
 
-  private async createZosMFSession(): Promise<AbstractSession> {
-    // Create a zosMF session
-    const zosmfProfile = this.params.profiles.get("zosmf");
+  private getProfile(type: string): IProfile {
+    const profile =  this.params.profiles.get(type);
 
-    if (zosmfProfile === undefined) {
-      throw new Error("No zosmf profile found");
+    if (profile === undefined) {
+      throw new Error("No " + type + " profile found");
     }
-    return ZosmfSession.createBasicZosmfSession(zosmfProfile);
+
+    return profile;
   }
 
-  private async createSshSession(): Promise<SshSession> {
-    // Create an SSH session
-    const sshProfile = this.params.profiles.get("ssh");
+  private issueWarning(msg: string) {
+    const warningMsg = "WARNING: " + msg + "\n";
+    this.endProgressBar();
+    this.params.response.console.log(Buffer.from(warningMsg));
+    if (this.params.arguments.silent === undefined) {
+      const logger = Logger.getAppLogger();
+      logger.warn(warningMsg);
+    }
+    this.startProgressBar();
+  }
 
-    if (sshProfile === undefined) {
-      throw new Error("No ssh profile found");
+  private validateProfiles(zosmfProfile: IProfile, sshProfile: IProfile) {
+    // Do they share the same host name?
+    if (zosmfProfile.host !== sshProfile.host) {
+      this.issueWarning("ssh profile --host value '" + sshProfile.host + "' does not match zosmf value '" + zosmfProfile.host + "'.");
+    }
+    // Do they share the same user name?
+    if (zosmfProfile.user !== sshProfile.user) {
+      this.issueWarning("ssh profile --user value '" + sshProfile.user + "' does not match zosmf value '" + zosmfProfile.user + "'.");
     }
+  }
+
+  private async createZosMFSession(zosmfProfile: IProfile): Promise<AbstractSession> {
+    return ZosmfSession.createBasicZosmfSession(zosmfProfile);
+  }
+
+  private async createSshSession(sshProfile: IProfile): Promise<SshSession> {
     return SshSession.createBasicSshSession(sshProfile);
   }
 
@@ -433,14 +458,7 @@ export class BundlePusher {
     }
 
     // A project specific .zosattributes has not been found, so use a default
-    const warningMsg = "WARNING: No .zosAttributes file found in the bundle directory, default values will be applied.";
-    this.endProgressBar();
-    this.params.response.console.log(Buffer.from(warningMsg));
-    if (this.params.arguments.silent === undefined) {
-      const logger = Logger.getAppLogger();
-      logger.warn(warningMsg);
-    }
-    this.startProgressBar();
+    this.issueWarning("No .zosAttributes file found in the bundle directory, default values will be applied.");
     return new ZosFilesAttributes(Bundle.getTemplateZosAttributesFile());
   }
 
@@ -468,13 +486,13 @@ export class BundlePusher {
   }
 
   private startProgressBar() {
-    if (this.params.arguments.verbose !== true) {
+    if (this.params.arguments.verbose !== true && this.progressBar !== undefined) {
       this.params.response.progress.startBar({task: this.progressBar});
     }
   }
 
   private endProgressBar() {
-    if (this.params.arguments.verbose !== true) {
+    if (this.params.arguments.verbose !== true && this.progressBar !== undefined) {
       this.params.response.progress.endBar();
     }
   }