ara-cli 0.1.9.75__py3-none-any.whl → 0.1.9.77__py3-none-any.whl

ara_cli/__main__.py

@@ -19,7 +19,7 @@ from ara_cli.ara_command_action import (
     set_user_action,
     classifier_directory_action,
     scan_action,
-    autofix_action
+    autofix_action,
 )
 import argcomplete
 import sys
@@ -44,7 +44,7 @@ def define_action_mapping():
         "set-user": set_user_action,
         "classifier-directory": classifier_directory_action,
         "scan": scan_action,
-        "autofix": autofix_action
+        "autofix": autofix_action,
     }
 
 
@@ -54,14 +54,21 @@ def handle_invalid_action(args):
 
 def cli():
     parser = action_parser()
-    parser.add_argument('-v', '--version', action='version', version=f'%(prog)s {__version__}')
+
+    # Show examples when help is called
+    if any(arg in sys.argv for arg in ["-h", "--help"]):
+        parser.add_examples = True
+
+    parser.add_argument(
+        "-v", "--version", action="version", version=f"%(prog)s {__version__}"
+    )
 
     action_mapping = define_action_mapping()
 
     argcomplete.autocomplete(parser)
 
     args = parser.parse_args()
-    if not hasattr(args, 'action') or not args.action:
+    if not hasattr(args, "action") or not args.action:
         parser.print_help()
         return
     action = action_mapping.get(args.action, handle_invalid_action)

ara_cli/ara_command_parser.py

@@ -1,6 +1,11 @@
 import argparse
+import sys
 from ara_cli.classifier import Classifier
-from ara_cli.commandline_completer import ArtefactCompleter, ParentNameCompleter, StatusCompleter
+from ara_cli.commandline_completer import (
+    ArtefactCompleter,
+    ParentNameCompleter,
+    StatusCompleter,
+)
 from ara_cli.template_manager import SpecificationBreakdownAspects
 
 
@@ -9,33 +14,71 @@ aspects = SpecificationBreakdownAspects.VALID_ASPECTS
 
 
 def create_parser(subparsers):
-    create_parser = subparsers.add_parser("create", help="Create a classified artefact with data directory")
-    create_parser.add_argument("classifier", choices=classifiers, help="Classifier that also serves as file extension for the artefact file to be created. Valid Classifiers are: businessgoal, capability, keyfeature, feature, epic, userstory, example, task")
-    create_parser.add_argument("parameter", help="Artefact name that serves as filename").completer = ArtefactCompleter()
+    create_parser = subparsers.add_parser(
+        "create", help="Create a classified artefact with data directory"
+    )
+    create_parser.add_argument(
+        "classifier",
+        choices=classifiers,
+        help="Classifier that also serves as file extension for the artefact file to be created. Valid Classifiers are: businessgoal, capability, keyfeature, feature, epic, userstory, example, task",
+    )
+    create_parser.add_argument(
+        "parameter", help="Artefact name that serves as filename"
+    ).completer = ArtefactCompleter()
 
     option_parser = create_parser.add_subparsers(dest="option")
 
     contribution_parser = option_parser.add_parser("contributes-to")
-    contribution_parser.add_argument("parent_classifier", choices=classifiers, help="Classifier of the parent")
-    contribution_parser.add_argument("parent_name",  help="Name of a parent artefact").completer = ParentNameCompleter()
+    contribution_parser.add_argument(
+        "parent_classifier", choices=classifiers, help="Classifier of the parent"
+    )
+    contribution_parser.add_argument(
+        "parent_name", help="Name of a parent artefact"
+    ).completer = ParentNameCompleter()
     contribution_parser.add_argument("-r", "--rule", dest="rule", action="store")
 
     aspect_parser = option_parser.add_parser("aspect")
-    aspect_parser.add_argument("aspect", choices=aspects, help="Adds additional specification breakdown aspects in data directory.")
+    aspect_parser.add_argument(
+        "aspect",
+        choices=aspects,
+        help="Adds additional specification breakdown aspects in data directory.",
+    )
 
 
 def delete_parser(subparsers):
-    delete_parser = subparsers.add_parser("delete", help="Delete an artefact file including its data directory")
-    delete_parser.add_argument("classifier", choices=classifiers, help="Classifier of the artefact to be deleted")
-    delete_parser.add_argument("parameter", help="Filename of artefact").completer = ArtefactCompleter()
-    delete_parser.add_argument("-f", "--force", dest="force", action="store_true", help="ignore nonexistent files and arguments, never prompt")
+    delete_parser = subparsers.add_parser(
+        "delete", help="Delete an artefact file including its data directory"
+    )
+    delete_parser.add_argument(
+        "classifier",
+        choices=classifiers,
+        help="Classifier of the artefact to be deleted",
+    )
+    delete_parser.add_argument(
+        "parameter", help="Filename of artefact"
+    ).completer = ArtefactCompleter()
+    delete_parser.add_argument(
+        "-f",
+        "--force",
+        dest="force",
+        action="store_true",
+        help="ignore nonexistent files and arguments, never prompt",
+    )
 
 
 def rename_parser(subparsers):
-    rename_parser = subparsers.add_parser("rename", help="Rename a classified artefact and its data directory")
-    rename_parser.add_argument("classifier", choices=classifiers, help="Classifier of the artefact")
-    rename_parser.add_argument("parameter", help="Filename of artefact").completer = ArtefactCompleter()
-    rename_parser.add_argument("aspect", help="New artefact name and new data directory name")
+    rename_parser = subparsers.add_parser(
+        "rename", help="Rename a classified artefact and its data directory"
+    )
+    rename_parser.add_argument(
+        "classifier", choices=classifiers, help="Classifier of the artefact"
+    )
+    rename_parser.add_argument(
+        "parameter", help="Filename of artefact"
+    ).completer = ArtefactCompleter()
+    rename_parser.add_argument(
+        "aspect", help="New artefact name and new data directory name"
+    )
 
 
 def add_filter_flags(parser):
@@ -44,27 +87,27 @@ def add_filter_flags(parser):
         "--include-content",
         nargs="+",
         default=None,
-        help="filter for files which include given content"
+        help="filter for files which include given content",
     )
     parser.add_argument(
         "-E",
         "--exclude-content",
         nargs="+",
         default=None,
-        help="filter for files which do not include given content"
+        help="filter for files which do not include given content",
     )
 
     parser.add_argument(
         "--include-tags",
         nargs="+",
         default=None,
-        help="filter for files which include given tags"
+        help="filter for files which include given tags",
     )
     parser.add_argument(
         "--exclude-tags",
         nargs="+",
         default=None,
-        help="filter for files which do not include given tags"
+        help="filter for files which do not include given tags",
     )
 
     extension_group = parser.add_mutually_exclusive_group()
@@ -73,16 +116,16 @@ def add_filter_flags(parser):
         "--include-extension",
         "--include-classifier",
         dest="include_extension",
-        nargs='+',
-        help='list of extensions to include in listing'
+        nargs="+",
+        help="list of extensions to include in listing",
     )
     extension_group.add_argument(
         "-e",
         "--exclude-extension",
         "--exclude-classifier",
         dest="exclude_extension",
-        nargs='+',
-        help='list of extensions to exclude from listing'
+        nargs="+",
+        help="list of extensions to exclude from listing",
     )
 
 
@@ -94,134 +137,260 @@ def list_parser(subparsers):
 
     argument_group = list_parser.add_mutually_exclusive_group()
     argument_group.add_argument(
-        "-b", "--branch",
+        "-b",
+        "--branch",
         dest="branch_args",
         nargs=2,
         metavar=("classifier", "artefact_name"),
-        help="List artefacts in the parent chain of the artefact with specified classifier and artefact_name"
+        help="List artefacts in the parent chain of the artefact with specified classifier and artefact_name",
     )
     argument_group.add_argument(
-        "-c", "--children",
+        "-c",
+        "--children",
         dest="children_args",
         nargs=2,
         metavar=("classifier", "artefact_name"),
-        help="List child artefacts of the artefact with specified classifier and artefact_name"
+        help="List child artefacts of the artefact with specified classifier and artefact_name",
     )
     argument_group.add_argument(
-        "-d", "--data",
+        "-d",
+        "--data",
         dest="data_args",
         nargs=2,
         metavar=("classifier", "artefact_name"),
-        help="List file in the data directory of the artefact with specified classifier and artefact_name"
+        help="List file in the data directory of the artefact with specified classifier and artefact_name",
     )
 
     list_parser.set_defaults(
-        branch_args=(None, None),
-        children_args=(None, None),
-        data_args=(None, None)
+        branch_args=(None, None), children_args=(None, None), data_args=(None, None)
     )
 
 
 def list_tags_parser(subparsers):
     tags_parser = subparsers.add_parser("list-tags", help="Show tags")
-    tags_parser.add_argument("--json", "-j", help="Output tags as JSON", action=argparse.BooleanOptionalAction)
-    tags_parser.add_argument("--include-classifier", choices=classifiers, help="Show tags for an artefact type")
-    tags_parser.add_argument("--exclude_classifier", choices=classifiers, help="Show tags for an artefact type")
-    tags_parser.add_argument("--filtered-extra-column", action="store_true", help="Filter tags for extra column") 
+    tags_parser.add_argument(
+        "--json",
+        "-j",
+        help="Output tags as JSON",
+        action=argparse.BooleanOptionalAction,
+    )
+    tags_parser.add_argument(
+        "--include-classifier",
+        choices=classifiers,
+        help="Show tags for an artefact type",
+    )
+    tags_parser.add_argument(
+        "--exclude_classifier",
+        choices=classifiers,
+        help="Show tags for an artefact type",
+    )
+    tags_parser.add_argument(
+        "--filtered-extra-column",
+        action="store_true",
+        help="Filter tags for extra column",
+    )
 
 
 def add_chat_arguments(chat_parser):
-    chat_parser.add_argument("chat_name", help="Optional name for a specific chat. Pass the .md file to continue an existing chat", nargs='?', default=None)
+    chat_parser.add_argument(
+        "chat_name",
+        help="Optional name for a specific chat. Pass the .md file to continue an existing chat",
+        nargs="?",
+        default=None,
+    )
 
-    chat_parser.add_argument("-r", "--reset", dest="reset", action=argparse.BooleanOptionalAction, help="Reset the chat file if it exists")
+    chat_parser.add_argument(
+        "-r",
+        "--reset",
+        dest="reset",
+        action=argparse.BooleanOptionalAction,
+        help="Reset the chat file if it exists",
+    )
     chat_parser.set_defaults(reset=None)
 
-    chat_parser.add_argument("--out", dest="output_mode", action="store_true", help="Output the contents of the chat file instead of entering interactive chat mode")
+    chat_parser.add_argument(
+        "--out",
+        dest="output_mode",
+        action="store_true",
+        help="Output the contents of the chat file instead of entering interactive chat mode",
+    )
 
-    chat_parser.add_argument("--append", nargs='*', default=None, help="Append strings to the chat file")
+    chat_parser.add_argument(
+        "--append", nargs="*", default=None, help="Append strings to the chat file"
+    )
 
-    chat_parser.add_argument("--restricted", dest="restricted", action=argparse.BooleanOptionalAction, help="Start with a limited set of commands")
+    chat_parser.add_argument(
+        "--restricted",
+        dest="restricted",
+        action=argparse.BooleanOptionalAction,
+        help="Start with a limited set of commands",
+    )
 
 
 def prompt_parser(subparsers):
-    prompt_parser = subparsers.add_parser("prompt", help="Base command for prompt interaction mode")
+    prompt_parser = subparsers.add_parser(
+        "prompt", help="Base command for prompt interaction mode"
+    )
 
-    steps = ['init', 'load', 'send', 'load-and-send', 'extract', 'update', 'chat', 'init-rag']
-    steps_parser = prompt_parser.add_subparsers(dest='steps')
+    steps = [
+        "init",
+        "load",
+        "send",
+        "load-and-send",
+        "extract",
+        "update",
+        "chat",
+        "init-rag",
+    ]
+    steps_parser = prompt_parser.add_subparsers(dest="steps")
     for step in steps:
         step_parser = steps_parser.add_parser(step)
-        step_parser.add_argument("classifier", choices=classifiers, help="Classifier of the artefact")
-        step_parser.add_argument("parameter", help="Name of artefact data directory for prompt creation and interaction").completer = ArtefactCompleter()
-        if step == 'chat':
+        step_parser.add_argument(
+            "classifier", choices=classifiers, help="Classifier of the artefact"
+        )
+        step_parser.add_argument(
+            "parameter",
+            help="Name of artefact data directory for prompt creation and interaction",
+        ).completer = ArtefactCompleter()
+        if step == "chat":
             add_chat_arguments(step_parser)
 
 
 def chat_parser(subparsers):
-    chat_parser = subparsers.add_parser("chat", help="Command line chatbot. Chat control with SEND/s | RERUN/r | QUIT/q")
+    chat_parser = subparsers.add_parser(
+        "chat", help="Command line chatbot. Chat control with SEND/s | RERUN/r | QUIT/q"
+    )
     add_chat_arguments(chat_parser)
 
 
 def template_parser(subparsers):
-    template_parser = subparsers.add_parser("template", help="Outputs a classified ara template in the terminal")
-    template_parser.add_argument("classifier", choices=classifiers, help="Classifier of the artefact type")
+    template_parser = subparsers.add_parser(
+        "template", help="Outputs a classified ara template in the terminal"
+    )
+    template_parser.add_argument(
+        "classifier", choices=classifiers, help="Classifier of the artefact type"
+    )
 
 
 def fetch_templates_parser(subparsers):
-    subparsers.add_parser("fetch-templates", help="Fetches templates and stores them in .araconfig")
+    subparsers.add_parser(
+        "fetch-templates", help="Fetches templates and stores them in .araconfig"
+    )
 
 
 def read_parser(subparsers):
     read_parser = subparsers.add_parser("read", help="Reads contents of artefacts")
-    read_parser.add_argument("classifier", choices=classifiers, help="Classifier of the artefact type")
-    read_parser.add_argument("parameter", help="Filename of artefact").completer = ArtefactCompleter()
+    read_parser.add_argument(
+        "classifier", choices=classifiers, help="Classifier of the artefact type"
+    )
+    read_parser.add_argument(
+        "parameter", help="Filename of artefact"
+    ).completer = ArtefactCompleter()
 
     branch_group = read_parser.add_mutually_exclusive_group()
-    branch_group.add_argument("-b", "--branch", dest="read_mode", action="store_const", const="branch",
-                              help="Output the contents of artefacts in the parent chain")
-    branch_group.add_argument("-c", "--children", dest="read_mode", action="store_const", const="children",
-                              help="Output the contents of child artefacts")
+    branch_group.add_argument(
+        "-b",
+        "--branch",
+        dest="read_mode",
+        action="store_const",
+        const="branch",
+        help="Output the contents of artefacts in the parent chain",
+    )
+    branch_group.add_argument(
+        "-c",
+        "--children",
+        dest="read_mode",
+        action="store_const",
+        const="children",
+        help="Output the contents of child artefacts",
+    )
 
     read_parser.set_defaults(read_mode=None)
 
 
 def reconnect_parser(subparsers):
-    reconnect_parser = subparsers.add_parser("reconnect", help="Connect an artefact to a parent artefact")
-    reconnect_parser.add_argument("classifier", choices=classifiers, help="Classifier of the artefact type")
-    reconnect_parser.add_argument("parameter", help="Filename of artefact").completer = ArtefactCompleter()
-    reconnect_parser.add_argument("parent_classifier", choices=classifiers, help="Classifier of the parent artefact type")
-    reconnect_parser.add_argument("parent_name", help="Filename of parent artefact").completer = ParentNameCompleter()
+    reconnect_parser = subparsers.add_parser(
+        "reconnect", help="Connect an artefact to a parent artefact"
+    )
+    reconnect_parser.add_argument(
+        "classifier", choices=classifiers, help="Classifier of the artefact type"
+    )
+    reconnect_parser.add_argument(
+        "parameter", help="Filename of artefact"
+    ).completer = ArtefactCompleter()
+    reconnect_parser.add_argument(
+        "parent_classifier",
+        choices=classifiers,
+        help="Classifier of the parent artefact type",
+    )
+    reconnect_parser.add_argument(
+        "parent_name", help="Filename of parent artefact"
+    ).completer = ParentNameCompleter()
     reconnect_parser.add_argument("-r", "--rule", dest="rule", action="store")
 
 
 def read_status_parser(subparsers):
-    read_status_parser = subparsers.add_parser("read-status", help="Read status of an artefact by checking its tags")
-    read_status_parser.add_argument("classifier", choices=classifiers, help="Classifier of the artefact type")
-    read_status_parser.add_argument("parameter", help="Filename of artefact").completer = ArtefactCompleter()
+    read_status_parser = subparsers.add_parser(
+        "read-status", help="Read status of an artefact by checking its tags"
+    )
+    read_status_parser.add_argument(
+        "classifier", choices=classifiers, help="Classifier of the artefact type"
+    )
+    read_status_parser.add_argument(
+        "parameter", help="Filename of artefact"
+    ).completer = ArtefactCompleter()
 
 
 def read_user_parser(subparsers):
-    read_user_parser = subparsers.add_parser("read-user", help="Read user of an artefact by checking its tags")
-    read_user_parser.add_argument("classifier", choices=classifiers, help="Classifier of the artefact type")
-    read_user_parser.add_argument("parameter", help="Filename of artefact").completer = ArtefactCompleter()
+    read_user_parser = subparsers.add_parser(
+        "read-user", help="Read user of an artefact by checking its tags"
+    )
+    read_user_parser.add_argument(
+        "classifier", choices=classifiers, help="Classifier of the artefact type"
+    )
+    read_user_parser.add_argument(
+        "parameter", help="Filename of artefact"
+    ).completer = ArtefactCompleter()
 
 
 def set_status_parser(subparsers):
-    set_status_parser = subparsers.add_parser("set-status", help="Set the status of a task")
-    set_status_parser.add_argument("classifier", choices=classifiers, help="Classifier of the artefact type, typically 'task'")
-    set_status_parser.add_argument("parameter", help="Name of the task artefact").completer = ArtefactCompleter()
-    set_status_parser.add_argument("new_status", help="New status to set for the task").completer = StatusCompleter()
+    set_status_parser = subparsers.add_parser(
+        "set-status", help="Set the status of a task"
+    )
+    set_status_parser.add_argument(
+        "classifier",
+        choices=classifiers,
+        help="Classifier of the artefact type, typically 'task'",
+    )
+    set_status_parser.add_argument(
+        "parameter", help="Name of the task artefact"
+    ).completer = ArtefactCompleter()
+    set_status_parser.add_argument(
+        "new_status", help="New status to set for the task"
+    ).completer = StatusCompleter()
 
 
 def set_user_parser(subparsers):
     set_user_parser = subparsers.add_parser("set-user", help="Set the user of a task")
-    set_user_parser.add_argument("classifier", choices=classifiers, help="Classifier of the artefact type, typically 'task'")
-    set_user_parser.add_argument("parameter", help="Name of the task artefact").completer = ArtefactCompleter()
+    set_user_parser.add_argument(
+        "classifier",
+        choices=classifiers,
+        help="Classifier of the artefact type, typically 'task'",
+    )
+    set_user_parser.add_argument(
+        "parameter", help="Name of the task artefact"
+    ).completer = ArtefactCompleter()
     set_user_parser.add_argument("new_user", help="New user to assign to the task")
 
 
 def classifier_directory_parser(subparsers):
-    classifier_directory_parser = subparsers.add_parser("classifier-directory", help="Print the ara subdirectory for an artefact classifier")
-    classifier_directory_parser.add_argument("classifier", choices=classifiers, help="Classifier of the artefact type")
+    classifier_directory_parser = subparsers.add_parser(
+        "classifier-directory",
+        help="Print the ara subdirectory for an artefact classifier",
+    )
+    classifier_directory_parser.add_argument(
+        "classifier", choices=classifiers, help="Classifier of the artefact type"
+    )
 
 
 def scan_parser(subparsers):
@@ -229,22 +398,38 @@ def scan_parser(subparsers):
 
 
 def autofix_parser(subparsers):
-    autofix_parser = subparsers.add_parser("autofix", help="Fix ARA tree with llm models for scanned artefacts with ara scan command. By default three attemps for every file.")
-    autofix_parser.add_argument("--single-pass", action="store_true", help="Run the autofix once for every scaned file.")
+    autofix_parser = subparsers.add_parser(
+        "autofix",
+        help="Fix ARA tree with llm models for scanned artefacts with ara scan command. By default three attemps for every file.",
+    )
+    autofix_parser.add_argument(
+        "--single-pass",
+        action="store_true",
+        help="Run the autofix once for every scaned file.",
+    )
     determinism_group = autofix_parser.add_mutually_exclusive_group()
-    determinism_group.add_argument("--deterministic", "-d", action="store_true", help="Run only deterministic fixes e.g Title-FileName Mismatch fix")
-    determinism_group.add_argument("--non-deterministic", "-nd", action="store_true", help="Run only non-deterministic fixes")
+    determinism_group.add_argument(
+        "--deterministic",
+        "-d",
+        action="store_true",
+        help="Run only deterministic fixes e.g Title-FileName Mismatch fix",
+    )
+    determinism_group.add_argument(
+        "--non-deterministic",
+        "-nd",
+        action="store_true",
+        help="Run only non-deterministic fixes",
+    )
 
 
 class CustomHelpFormatter(argparse.HelpFormatter):
+    def __init__(self, *args, **kwargs):
+        self.add_examples = kwargs.pop("add_examples", False)
+        super().__init__(*args, **kwargs)
+
     def format_help(self):
-        from sys import argv
-        # Get the default help message
         help_message = super().format_help()
-
-        # Check if '-h' or '--help' is in the arguments
-        if '-h' in argv or '--help' in argv:
-            # Add custom examples or additional information
+        if self.add_examples:
             examples = (
                 "\nValid classified artefacts are: businessgoal, vision, capability, keyfeature, feature, epic, userstory, example, feature, task.\n"
                 "The default ara directory structure of classified artefact of the ara cli tool is:\n"
@@ -274,7 +459,7 @@ class CustomHelpFormatter(argparse.HelpFormatter):
                 "  > list artefact data with .md and .json file extensions                            ara list --data {classifier} {artefact_name} --include-extension .md .json\n"
                 "  > list everything but userstories                                                  ara list --exclude-extension .userstory\n"
                 "  > list all existing features:                                                      ara list --include-extension .feature\n"
-                "  > list all child artefacts contributing value to a parent artefact:                ara list --include-content \"Contributes to {name_of_parent_artefact} {ara classifier_of_parent_artefact}\"\n"
+                '  > list all child artefacts contributing value to a parent artefact:                ara list --include-content "Contributes to {name_of_parent_artefact} {ara classifier_of_parent_artefact}"\n'
                 "  > list tasks which contain 'example content'                                       ara list --include-extension .task --include-content \"example content\"\n"
                 "  > list children artefacts of a userstory                                           ara list --children userstory {name_of_userstory}\n"
                 "  > list parent artefacts of a userstory                                             ara list --branch userstory {name_of_userstory}\n"
@@ -293,17 +478,40 @@ class CustomHelpFormatter(argparse.HelpFormatter):
                 "  > load selected templates in config_prompt_templates.md for the task {task_name}:  ara prompt load task {task_name}\n"
                 "  > create and send configured prompt of the task {task_name} to the configured LLM: ara prompt send task {task_name}\n"
                 "  > extract the selected LLM response in task.exploration.md and save to disk:       ara prompt extract task {task_name}\n"
-
             )
-            # Combine the default help message with the examples
             return help_message + examples
-
         return help_message
 
 
+class CustomArgumentParser(argparse.ArgumentParser):
+    def __init__(self, *args, **kwargs):
+        self.add_examples = False
+        kwargs["formatter_class"] = CustomHelpFormatter
+        super().__init__(*args, **kwargs)
+
+    def _get_formatter(self):
+        # Pass add_examples flag to formatter
+        return self.formatter_class(prog=self.prog, add_examples=self.add_examples)
+
+    def print_help(self, file=None):
+        # Use the formatter with the current add_examples
+        if file is None:
+            file = sys.stdout
+        file.write(self.format_help())
+        file.write("\n")
+
+    def error(self, message):
+        self.add_examples = True
+        sys.stderr.write(f"error: {message}\n")
+        self.print_help(sys.stderr)
+        sys.exit(2)
+
+
 def action_parser():
-    # Use the CustomHelpFormatter here
-    parser = argparse.ArgumentParser(description="The ara cli terminal tool is a management tool for classified ara artefacts.", formatter_class=CustomHelpFormatter)
+    # Use the CustomArgumentParser instead of argparse.ArgumentParser
+    parser = CustomArgumentParser(
+        description="The ara cli terminal tool is a management tool for classified ara artefacts."
+    )
 
     subparsers = parser.add_subparsers(dest="action", help="Action to perform")
     create_parser(subparsers)