[Scenario Guide] Initialize the first official version (Azure#5309)

.github/CODEOWNERS

@@ -251,3 +251,5 @@
 /src/elastic-san/ @calvinhzy
 
 /src/reservation/ @gaoyp830 @rkapso @msft-adrianma @sornaks @juhee0202
+
+/src/scenario-guide/ @zhoxing-ms @ReaNAiveD

linter_exclusions.yml

@@ -2695,3 +2695,8 @@ vmware private-cloud create:
     circuit_secondary_subnet:
       rule_exclusions:
       - option_length_too_long
+scenario guide:
+  parameters:
+    search_keyword:
+      rule_exclusions:
+        - no_positional_parameters

src/scenario-guide/HISTORY.rst

@@ -0,0 +1,8 @@
+.. :changelog:
+
+Release History
+===============
+
+0.1.0
+++++++
+* Initial release.

src/scenario-guide/README.rst

@@ -0,0 +1,5 @@
+Microsoft Azure CLI 'scenario-guide' Extension
+==========================================
+
+This package is for the 'scenario-guide' extension.
+i.e. 'az scenario guide "scale server" --top 10 --scope scenario'

src/scenario-guide/azext_scenario_guide/__init__.py

@@ -0,0 +1,28 @@
+# --------------------------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for license information.
+# --------------------------------------------------------------------------------------------
+
+from azure.cli.core import AzCommandsLoader
+from ._help import helps  # pylint: disable=unused-import
+
+
+class ScenarioGuideCommandsLoader(AzCommandsLoader):
+
+    def __init__(self, cli_ctx=None):
+        from azure.cli.core.commands import CliCommandType
+        scenario_guide_custom = CliCommandType(
+            operations_tmpl='azext_scenario_guide.custom#{}')
+        super().__init__(cli_ctx=cli_ctx, custom_command_type=scenario_guide_custom)
+
+    def load_command_table(self, args):
+        from .commands import load_command_table
+        load_command_table(self, args)
+        return self.command_table
+
+    def load_arguments(self, command):
+        from ._params import load_arguments
+        load_arguments(self, command)
+
+
+COMMAND_LOADER_CLS = ScenarioGuideCommandsLoader

src/scenario-guide/azext_scenario_guide/_clierror.py

@@ -0,0 +1,13 @@
+# --------------------------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for license information.
+# --------------------------------------------------------------------------------------------
+
+from azure.cli.core.azclierror import ClientRequestError
+
+# pylint: disable=unnecessary-pass
+
+
+class ScenarioGuideError(ClientRequestError):
+    """ The client error raised by `az scenario guide`. """
+    pass

src/scenario-guide/azext_scenario_guide/_help.py

@@ -0,0 +1,51 @@
+# coding=utf-8
+# --------------------------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for license information.
+# --------------------------------------------------------------------------------------------
+
+from knack.help_files import helps  # pylint: disable=unused-import
+
+
+helps['scenario'] = """
+type: group
+short-summary: E2E Scenario Usage Guidance
+"""
+
+
+helps['scenario guide'] = """
+type: command
+short-summary: Fuzzy search E2E scenario examples and execute them with walk-through
+long-summary: >
+
+    This an intelligent guidance tool that can help you find and execute E2E scenario samples!
+    It supports fuzzy search and sort the searched results according to the matching degree from high to low.
+    It supports flexible search scenarios, you can specify the search scope and customize the matching rules.
+    Moreover, it helps you execute these E2E scenarios more efficiently with a friendly walk-through process.\n
+
+    There are some custom configurations:\n
+
+    [1] az config set scenario_guide.execute_in_prompt=True/False
+        Turn on/off the step of executing scenario commands in interactive mode. Turn on by default.
+
+    [2] az config set scenario_guide.output=json/jsonc/none/table/tsv/yaml/yamlc/status
+        Set default output format. Status is the default.
+
+    [3] az config set scenario_guide.show_arguments=True/False
+        Show/hide the arguments of scenario commands. False is the default.
+
+    [4] az config set scenario_guide.print_help=True/False
+        Enable/disable whether to print help actively before executing each command. False is the default.
+
+examples:
+  - name: Search and execute scenario examples of how to connect the App Service to SQL Database.
+    text: |-
+        az scenario guide "app service database"
+  - name: Search and execute scenario examples whose title or description related to app service or web app.
+    text: |-
+        az scenario guide "web app service" --scope "scenario" --match-rule "or"
+  - name: Search and execute top 3 scenario examples whose commands contain keywords "network","vnet" and "subnet" at the same time.
+    text: |-
+        az scenario guide "network vnet subnet" --scope "command" --match-rule "and" --top 3
+
+"""

src/scenario-guide/azext_scenario_guide/_params.py

@@ -0,0 +1,19 @@
+# --------------------------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for license information.
+# --------------------------------------------------------------------------------------------
+# pylint: disable=line-too-long
+
+
+def load_arguments(self, _):
+
+    from azure.cli.core.commands.parameters import get_enum_type
+
+    with self.argument_context('scenario guide') as c:
+        c.positional('search_keyword', nargs='+', help="Keywords for search. If there are multiple keywords, please separate them with spaces. Fuzzy search is supported, and the returned results are sorted by keyword matching degree.")
+        c.argument('scope', arg_type=get_enum_type(["all", "scenario", "command"], default='all'),
+                   help='The scope of search: "scenario" is to search whether the title and description in E2E scenario data contain keywords, "command" is to search whether the commands in E2E scenario data contain keywords, "all" is to search all contents.')
+        c.argument('match_rule', arg_type=get_enum_type(["all", "and", "or"]), default="all",
+                   help='The matching rules for multi-keywords: "and" is to search scenarios that match all keywords, "or" is to search scenarios that match any keyword, "all" is to search scenarios that match all keywords first, if the number is not enough then search any keyword.')
+        c.argument('top', type=int, default=5,
+                   help='Specify the number of results to return. The maximum value is limited to 20. ')

src/scenario-guide/azext_scenario_guide/azext_metadata.json

@@ -0,0 +1,4 @@
+{
+    "azext.isExperimental": true,
+    "azext.minCliCoreVersion": "2.20.0"
+}

src/scenario-guide/azext_scenario_guide/commands.py

@@ -0,0 +1,10 @@
+# --------------------------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for license information.
+# --------------------------------------------------------------------------------------------
+
+
+def load_command_table(self, _):
+
+    with self.command_group('scenario') as g:
+        g.custom_command('guide', 'scenario_guide')

src/scenario-guide/azext_scenario_guide/constants.py

@@ -0,0 +1,63 @@
+# --------------------------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for license information.
+# --------------------------------------------------------------------------------------------
+
+
+from enum import Enum
+
+
+class SearchScope(int, Enum):
+    All = 1
+    Scenario = 2
+    Command = 3
+
+    @staticmethod
+    def get(scope):
+        if not scope:
+            return SearchScope.All
+
+        if scope.lower() == "scenario":
+            return SearchScope.Scenario
+
+        if scope.lower() == "command":
+            return SearchScope.Command
+
+        return SearchScope.All
+
+
+class MatchRule(int, Enum):
+    All = 1
+    And = 2
+    Or = 3
+
+    @staticmethod
+    def get(rule):
+        if not rule:
+            return MatchRule.All
+
+        if rule.lower() == "and":
+            return MatchRule.And
+
+        if rule.lower() == "or":
+            return MatchRule.Or
+
+        return MatchRule.All
+
+
+SEARCH_SERVICE_URL = "https://cli-recommendation.azurewebsites.net/api/SearchService"
+
+
+HIGHLIGHT_MARKER = ("<em>", "</em>")
+
+
+class FeedbackOption(int, Enum):
+    NO_RESULT = -1
+    """`az scenario guide` get no result from search service"""
+    NO_SELECT = 0
+    """User selects none of the results and exits immediately after searching"""
+
+    @staticmethod
+    def SELECT(option):
+        """User selects the option-th scenario in results"""
+        return option