ara-cli 0.1.13.3__py3-none-any.whl → 0.1.14.0__py3-none-any.whl

ara_cli/ara_subcommands/prompt.py

@@ -1,136 +1,296 @@
 import typer
 from typing import Optional, List
-from .common import ClassifierEnum, MockArgs, ClassifierArgument, ArtefactNameArgument, ChatNameArgument
+from enum import Enum
+from .common import (
+    MockArgs,
+    ChatNameArgument,
+)
 from ara_cli.ara_command_action import prompt_action
+from ara_cli.completers import DynamicCompleters
+from ara_cli.classifier import Classifier
+from ara_cli.error_handler import AraError, ErrorLevel, ErrorHandler
 
 
-def prompt_init(
-    classifier: ClassifierEnum = ClassifierArgument("Classifier of the artefact"),
-    parameter: str = ArtefactNameArgument("Name of artefact data directory")
-):
-    """Initialize a macro prompt."""
-    args = MockArgs(
-        classifier=classifier.value,
-        parameter=parameter,
-        steps="init"
-    )
-    prompt_action(args)
+# Define PromptStep enum for subcommand validation
+class PromptStep(str, Enum):
+    init = "init"
+    load = "load"
+    send = "send"
+    load_and_send = "load-and-send"
+    extract = "extract"
+    update = "update"
+    chat = "chat"
+    init_rag = "init-rag"
 
 
-def prompt_load(
-    classifier: ClassifierEnum = ClassifierArgument("Classifier of the artefact"),
-    parameter: str = ArtefactNameArgument("Name of artefact data directory")
-):
-    """Load selected templates."""
-    args = MockArgs(
-        classifier=classifier.value,
-        parameter=parameter,
-        steps="load"
-    )
-    prompt_action(args)
+# Valid step values for old format detection
+VALID_STEPS = [step.value for step in PromptStep]
 
 
-def prompt_send(
-    classifier: ClassifierEnum = ClassifierArgument("Classifier of the artefact"),
-    parameter: str = ArtefactNameArgument("Name of artefact data directory")
-):
-    """Send configured prompt to LLM."""
-    args = MockArgs(
-        classifier=classifier.value,
-        parameter=parameter,
-        steps="send"
+def PromptStepArgument(help_text: str):
+    """Create a prompt step argument with autocompletion."""
+    return typer.Argument(
+        ...,
+        help=help_text,
+        autocompletion=DynamicCompleters.create_prompt_step_completer(),
     )
-    prompt_action(args)
 
 
-def prompt_load_and_send(
-    classifier: ClassifierEnum = ClassifierArgument("Classifier of the artefact"),
-    parameter: str = ArtefactNameArgument("Name of artefact data directory")
-):
-    """Load templates and send prompt to LLM."""
-    args = MockArgs(
-        classifier=classifier.value,
-        parameter=parameter,
-        steps="load-and-send"
+def _warn_unused_option(option_name: str, step: str, valid_for: str):
+    """Print warning for unused options."""
+    message = (
+        f"'{option_name}' option is ignored for '{step}' command. "
+        f"It is only valid for '{valid_for}'."
+    )
+    error_handler = ErrorHandler()
+    error_handler.report_error(
+        AraError(message, error_code=0, level=ErrorLevel.INFO)
     )
-    prompt_action(args)
 
 
-def prompt_extract(
-    classifier: ClassifierEnum = ClassifierArgument("Classifier of the artefact"),
-    parameter: str = ArtefactNameArgument("Name of artefact data directory"),
-    write: bool = typer.Option(False, "-w", "--write", help="Overwrite existing files without using LLM for merging")
-):
-    """Extract LLM response and save to disk."""
-    args = MockArgs(
-        classifier=classifier.value,
-        parameter=parameter,
-        steps="extract",
-        write=write
+def _warn_deprecated_format(old_cmd: str, new_cmd: str):
+    """Print deprecation warning for old command format."""
+    message = (
+        f"DEPRECATION: The command format has changed.\n"
+        f"   Old: {old_cmd}\n"
+        f"   New: {new_cmd}\n"
+        f"   Please update your scripts. Old format will be removed in 0.1.14.0 version."
+    )
+    error_handler = ErrorHandler()
+    error_handler.report_error(
+        AraError(message, error_code=0, level=ErrorLevel.WARNING)
     )
-    prompt_action(args)
 
 
-def prompt_update(
-    classifier: ClassifierEnum = ClassifierArgument("Classifier of the artefact"),
-    parameter: str = ArtefactNameArgument("Name of artefact data directory")
-):
-    """Update artefact config prompt files."""
-    args = MockArgs(
-        classifier=classifier.value,
-        parameter=parameter,
-        steps="update"
-    )
-    prompt_action(args)
+def _is_old_format(first_arg: str) -> bool:
+    """Check if the first argument is a step (old format) instead of classifier (new format)."""
+    return first_arg in VALID_STEPS
 
 
-def prompt_chat(
-    classifier: ClassifierEnum = ClassifierArgument("Classifier of the artefact"),
-    parameter: str = ArtefactNameArgument("Name of artefact data directory"),
-    chat_name: Optional[str] = ChatNameArgument("Optional name for a specific chat", None),
-    reset: Optional[bool] = typer.Option(None, "-r", "--reset/--no-reset", help="Reset the chat file if it exists"),
-    output_mode: bool = typer.Option(False, "--out", help="Output the contents of the chat file instead of entering interactive chat mode"),
-    append: Optional[List[str]] = typer.Option(None, "--append", help="Append strings to the chat file"),
-    restricted: Optional[bool] = typer.Option(None, "--restricted/--no-restricted", help="Start with a limited set of commands")
-):
-    """Start chat mode for the artefact."""
-    args = MockArgs(
-        classifier=classifier.value,
-        parameter=parameter,
-        steps="chat",
-        chat_name=chat_name,
-        reset=reset,
-        output_mode=output_mode,
-        append=append,
-        restricted=restricted
+def _validate_classifier(classifier: str) -> bool:
+    """Validate that the classifier is valid."""
+    return Classifier.is_valid_classifier(classifier)
+
+
+def _validate_step(step: str) -> bool:
+    """Validate that the step is valid."""
+    return step in VALID_STEPS
+
+
+def _handle_old_format(
+    step_value: str, classifier: str, artefact_name: Optional[str]
+) -> tuple[str, str, str]:
+    """Handle old format: ara prompt <step> <classifier> <artefact>."""
+    if artefact_name is None:
+        typer.echo(
+            "Error: Missing artefact name. "
+            "Usage: ara prompt <step> <classifier> <artefact_name>",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    if not _validate_classifier(classifier):
+        typer.echo(
+            f"Error: Invalid classifier '{classifier}'. "
+            f"Valid classifiers: {', '.join(Classifier.ordered_classifiers())}",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    # Show deprecation warning
+    old_cmd = f"ara prompt {step_value} {classifier} {artefact_name}"
+    new_cmd = f"ara prompt {classifier} {artefact_name} {step_value}"
+    _warn_deprecated_format(old_cmd, new_cmd)
+
+    return classifier, artefact_name, step_value
+
+
+def _handle_new_format(
+    classifier: str, artefact_name: str, step_value: Optional[str]
+) -> tuple[str, str, str]:
+    """Handle new format: ara prompt <classifier> <artefact> <step>."""
+    if not _validate_classifier(classifier):
+        typer.echo(
+            f"Error: Invalid classifier '{classifier}'. "
+            f"Valid classifiers: {', '.join(Classifier.ordered_classifiers())}",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    if step_value is None:
+        typer.echo(
+            "Error: Missing step. "
+            f"Usage: ara prompt <classifier> <artefact_name> <step>\n"
+            f"Valid steps: {', '.join(VALID_STEPS)}",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    if not _validate_step(step_value):
+        typer.echo(
+            f"Error: Invalid step '{step_value}'. "
+            f"Valid steps: {', '.join(VALID_STEPS)}",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    return classifier, artefact_name, step_value
+
+
+def _validate_step_options(
+    step_value: str,
+    write: bool,
+    reset: Optional[bool],
+    output_mode: bool,
+    append: Optional[List[str]],
+    restricted: Optional[bool],
+    chat_name: Optional[str],
+) -> None:
+    """Validate that options are used with correct steps."""
+    if step_value != "extract" and write:
+        _warn_unused_option("--write", step_value, "extract")
+
+    if step_value != "chat":
+        chat_only_options = [
+            (reset is not None, "--reset/--no-reset"),
+            (output_mode, "--out"),
+            (append is not None, "--append"),
+            (restricted is not None, "--restricted/--no-restricted"),
+            (chat_name is not None, "chat_name"),
+        ]
+        for is_set, option_name in chat_only_options:
+            if is_set:
+                _warn_unused_option(option_name, step_value, "chat")
+
+
+def _build_prompt_args(
+    classifier: str,
+    artefact_name: str,
+    step_value: str,
+    write: bool,
+    chat_name: Optional[str],
+    reset: Optional[bool],
+    output_mode: bool,
+    append: Optional[List[str]],
+    restricted: Optional[bool],
+) -> MockArgs:
+    """Build MockArgs for prompt_action."""
+    is_extract = step_value == "extract"
+    is_chat = step_value == "chat"
+
+    return MockArgs(
+        classifier=classifier,
+        parameter=artefact_name,
+        steps=step_value,
+        write=write if is_extract else False,
+        chat_name=chat_name if is_chat else None,
+        reset=reset if is_chat else None,
+        output_mode=output_mode if is_chat else False,
+        append=append if is_chat else None,
+        restricted=restricted if is_chat else None,
     )
-    prompt_action(args)
 
 
-def prompt_init_rag(
-    classifier: ClassifierEnum = ClassifierArgument("Classifier of the artefact"),
-    parameter: str = ArtefactNameArgument("Name of artefact data directory")
+def prompt_main(
+    classifier: str = typer.Argument(
+        ...,
+        help="Classifier of the artefact (e.g., feature, task, userstory)",
+        autocompletion=DynamicCompleters.create_classifier_completer(),
+    ),
+    artefact_name: str = typer.Argument(
+        ...,
+        help="Name of the artefact",
+        autocompletion=DynamicCompleters.create_artefact_name_completer(),
+    ),
+    step: Optional[str] = typer.Argument(
+        None,
+        help="Action: init, load, send, load-and-send, extract, update, chat, init-rag",
+        autocompletion=DynamicCompleters.create_prompt_step_completer(),
+    ),
+    chat_name: Optional[str] = ChatNameArgument(
+        "[chat only] Optional name for a specific chat session", None
+    ),
+    # Extract-specific option
+    write: bool = typer.Option(
+        False,
+        "-w",
+        "--write",
+        help="[extract only] Overwrite existing files without using LLM for merging",
+    ),
+    # Chat-specific options
+    reset: Optional[bool] = typer.Option(
+        None,
+        "-r",
+        "--reset/--no-reset",
+        help="[chat only] Reset the chat file if it exists",
+    ),
+    output_mode: bool = typer.Option(
+        False,
+        "--out",
+        help="[chat only] Output the contents of the chat file instead of entering interactive chat mode",
+    ),
+    append: Optional[List[str]] = typer.Option(
+        None, "--append", help="[chat only] Append strings to the chat file"
+    ),
+    restricted: Optional[bool] = typer.Option(
+        None,
+        "--restricted/--no-restricted",
+        help="[chat only] Start with a limited set of commands",
+    ),
 ):
-    """Initialize RAG prompt."""
-    args = MockArgs(
-        classifier=classifier.value,
-        parameter=parameter,
-        steps="init-rag"
+    """
+    Prompt interaction mode for artefacts.
+
+    Usage:
+        ara prompt <classifier> <artefact_name> <step> [chat_name] [options]
+
+    Steps:
+        init          Initialize prompt templates
+        load          Load selected templates
+        send          Send configured prompt to LLM
+        load-and-send Load templates and send to LLM
+        extract       Extract LLM response and save
+        update        Update artefact config prompt files
+        chat          Start interactive chat mode
+        init-rag      Initialize RAG prompt
+
+    Examples:
+        ara prompt feature my_feature init
+        ara prompt task my_task chat --reset
+        ara prompt userstory my_story extract -w
+        ara prompt feature my_feature chat my_session --out
+    """
+    # Detect and handle old vs new format (backward compatibility)
+    if _is_old_format(classifier):
+        classifier_val, artefact_name_val, step_value = _handle_old_format(
+            classifier, artefact_name, step
+        )
+    else:
+        classifier_val, artefact_name_val, step_value = _handle_new_format(
+            classifier, artefact_name, step
+        )
+
+    # Validate options match the step
+    _validate_step_options(
+        step_value, write, reset, output_mode, append, restricted, chat_name
+    )
+
+    # Build args and execute
+    args = _build_prompt_args(
+        classifier_val,
+        artefact_name_val,
+        step_value,
+        write,
+        chat_name,
+        reset,
+        output_mode,
+        append,
+        restricted,
     )
     prompt_action(args)
 
 
 def register(parent: typer.Typer):
-    prompt_app = typer.Typer(
-        help="Base command for prompt interaction mode",
-        add_completion=False  # Disable completion on subcommand
+    parent.command(name="prompt", help="Prompt interaction mode for artefacts")(
+        prompt_main
     )
-    prompt_app.command("init")(prompt_init)
-    prompt_app.command("load")(prompt_load)
-    prompt_app.command("send")(prompt_send)
-    prompt_app.command("load-and-send")(prompt_load_and_send)
-    prompt_app.command("extract")(prompt_extract)
-    prompt_app.command("update")(prompt_update)
-    prompt_app.command("chat")(prompt_chat)
-    prompt_app.command("init-rag")(prompt_init_rag)
-    parent.add_typer(prompt_app, name="prompt")

ara_cli/artefact_autofix.py

@@ -256,7 +256,7 @@ def _update_rule(
     """Updates the rule in the contribution if a close match is found."""
     rule = artefact.contribution.rule
 
-    content, artefact_data = ArtefactReader.read_artefact_data(
+    content, artefact_data = ArtefactReader().read_artefact_data(
         artefact_name=name,
         classifier=classifier,
         classified_file_info=classified_file_info,
@@ -365,7 +365,7 @@ def set_closest_contribution(
     if not rule:
         return artefact, True
 
-    content, artefact = ArtefactReader.read_artefact_data(
+    content, artefact = ArtefactReader().read_artefact_data(
         artefact_name=name,
         classifier=classifier,
         classified_file_info=classified_file_info,

ara_cli/artefact_converter.py

@@ -1,5 +1,6 @@
 import os
 import logging
+from typing import Optional
 from ara_cli.prompt_handler import LLMSingleton
 from langfuse.api.resources.commons.errors import Error as LangfuseError, NotFoundError
 from ara_cli.classifier import Classifier
@@ -8,6 +9,8 @@ from ara_cli.artefact_creator import ArtefactCreator
 from ara_cli.error_handler import AraError
 from ara_cli.directory_navigator import DirectoryNavigator
 from ara_cli.artefact_deleter import ArtefactDeleter
+from ara_cli.children_contribution_updater import ChildrenContributionUpdater
+from ara_cli.artefact_models.artefact_load import artefact_from_content
 
 
 class AraArtefactConverter:
@@ -15,6 +18,7 @@ class AraArtefactConverter:
         self.file_system = file_system or os
         self.reader = ArtefactReader()
         self.creator = ArtefactCreator(self.file_system)
+        self.children_updater = ChildrenContributionUpdater(self.file_system)
 
     def convert(
         self,
@@ -23,61 +27,147 @@ class AraArtefactConverter:
         new_classifier: str,
         merge: bool = False,
         override: bool = False,
+        force: bool = False,
+        children_action: Optional[str] = None,
+        new_parent_classifier: Optional[str] = None,
+        new_parent_name: Optional[str] = None,
+        json_output: bool = False,
     ):
-        try:
-            self._validate_classifiers(old_classifier, new_classifier)
+        self._validate_classifiers(old_classifier, new_classifier)
+
+        content = self._read_and_validate_source(artefact_name, old_classifier)
+
+        # Handle children contributions BEFORE conversion
+        if not self._handle_children_if_needed(
+            artefact_name,
+            old_classifier,
+            new_classifier,
+            force,
+            children_action,
+            new_parent_classifier,
+            new_parent_name,
+            json_output,
+        ):
+            return  # User cancelled
+
+        target_content_existing = self._resolve_target_content(
+            artefact_name, new_classifier, merge, override
+        )
 
-            content, artefact_info = self.reader.read_artefact_data(
-                artefact_name, old_classifier
-            )
-            if not content or not artefact_info:
-                raise AraError(
-                    f"Artefact '{artefact_name}' of type '{old_classifier}' not found"
-                )
+        self._execute_conversion(
+            old_classifier,
+            new_classifier,
+            artefact_name,
+            content,
+            target_content_existing,
+            merge,
+            override,
+        )
+
+        self._cleanup_after_conversion(old_classifier, new_classifier, artefact_name)
 
-            target_content_existing = self._resolve_target_content(
-                artefact_name, new_classifier, merge, override
+    def _read_and_validate_source(self, artefact_name: str, classifier: str) -> str:
+        """Read source artefact and validate it can be parsed."""
+        content, artefact_info = self.reader.read_artefact_data(
+            artefact_name, classifier
+        )
+        if not content or not artefact_info:
+            raise AraError(
+                f"Artefact '{artefact_name}' of type '{classifier}' not found"
             )
 
-            target_class = self._get_target_class(new_classifier)
+        self._validate_artefact_parseable(content, artefact_name, is_source=True)
+        return content
 
-            prompt = self._get_prompt(
-                old_classifier=old_classifier,
-                new_classifier=new_classifier,
-                artefact_name=artefact_name,
-                content=content,
-                target_content_existing=target_content_existing,
-                merge=merge,
+    def _validate_artefact_parseable(
+        self, content: str, artefact_name: str, is_source: bool = True
+    ) -> None:
+        """Validate that artefact content can be parsed."""
+        artefact_type = "input" if is_source else "target"
+        try:
+            artefact = artefact_from_content(content)
+            if artefact is None:
+                raise AraError(
+                    f'Invalid {artefact_type} artefact: {artefact_name}. Run "ara scan" and "ara autofix" first.'
+                )
+        except AraError:
+            raise
+        except Exception:
+            raise AraError(
+                f'Invalid {artefact_type} artefact: {artefact_name}. Run "ara scan" and "ara autofix" first.'
             )
 
-            print(
-                f"{'Merging' if merge and target_content_existing else 'Converting'} '{artefact_name}' from {old_classifier} to {new_classifier}..."
-            )
+    def _handle_children_if_needed(
+        self,
+        artefact_name: str,
+        old_classifier: str,
+        new_classifier: str,
+        force: bool,
+        children_action: Optional[str],
+        new_parent_classifier: Optional[str],
+        new_parent_name: Optional[str],
+        json_output: bool,
+    ) -> bool:
+        """Handle children contributions if classifier is changing. Returns True to continue."""
+        if old_classifier == new_classifier:
+            return True
+        return self.children_updater.update_children_contributions(
+            artefact_name,
+            old_classifier,
+            new_classifier,
+            force,
+            children_action=children_action,
+            new_parent_classifier=new_parent_classifier,
+            new_parent_name=new_parent_name,
+            json_output=json_output,
+        )
 
-            converted_artefact = self._run_conversion_agent(prompt, target_class)
-            artefact_content = converted_artefact.serialize()
+    def _execute_conversion(
+        self,
+        old_classifier: str,
+        new_classifier: str,
+        artefact_name: str,
+        content: str,
+        target_content_existing: Optional[str],
+        merge: bool,
+        override: bool,
+    ) -> None:
+        """Execute the LLM conversion and write the result."""
+        target_class = self._get_target_class(new_classifier)
+
+        prompt = self._get_prompt(
+            old_classifier=old_classifier,
+            new_classifier=new_classifier,
+            artefact_name=artefact_name,
+            content=content,
+            target_content_existing=target_content_existing,
+            merge=merge,
+        )
 
-            self._write_artefact(
-                new_classifier,
-                artefact_name,
-                artefact_content,
-                merge=merge,
-                override=override,
-            )
+        action = "Merging" if merge and target_content_existing else "Converting"
+        print(
+            f"\n{action} '{artefact_name}' from {old_classifier} to {new_classifier}..."
+        )
 
-            if old_classifier != new_classifier:
-                self._move_data_folder_content(
-                    old_classifier, new_classifier, artefact_name
-                )
-                deleter = ArtefactDeleter(self.file_system)
-                deleter.delete(artefact_name, old_classifier, force=True)
+        converted_artefact = self._run_conversion_agent(prompt, target_class)
+        self._write_artefact(
+            new_classifier,
+            artefact_name,
+            converted_artefact.serialize(),
+            merge,
+            override,
+        )
 
-        except ValueError as e:
-            raise e
-        except AraError as e:
-            raise e
-        except Exception as e:
-            raise e
+    def _cleanup_after_conversion(
+        self, old_classifier: str, new_classifier: str, artefact_name: str
+    ) -> None:
+        """Move data folder and delete old artefact after successful conversion."""
+        if old_classifier == new_classifier:
+            return
+        self._move_data_folder_content(old_classifier, new_classifier, artefact_name)
+        ArtefactDeleter(self.file_system).delete(
+            artefact_name, old_classifier, force=True
+        )
 
     def _validate_classifiers(self, old_classifier: str, new_classifier: str):
         if not Classifier.is_valid_classifier(old_classifier):
@@ -122,20 +212,29 @@ class AraArtefactConverter:
     def _resolve_target_content(
         self, artefact_name: str, new_classifier: str, merge: bool, override: bool
     ):
-        target_content_existing = None
-        if not merge and not override:
-            _, new_artefact_info = self.reader.read_artefact_data(
+        if merge:
+            target_content_existing, _ = self.reader.read_artefact_data(
                 artefact_name, new_classifier
             )
-            if new_artefact_info:
-                raise ValueError(
-                    f"Found already exiting {new_classifier} {artefact_name}. Rerun the command with --override or --merge."
+            return target_content_existing
+
+        if override:
+            return None
+
+        # Check if target already exists
+        target_content, new_artefact_info = self.reader.read_artefact_data(
+            artefact_name, new_classifier
+        )
+        if new_artefact_info:
+            # Only validate if content is not None (artefact file exists and is readable)
+            if target_content is not None:
+                self._validate_artefact_parseable(
+                    target_content, artefact_name, is_source=False
                 )
-        elif merge:
-            target_content_existing, _ = self.reader.read_artefact_data(
-                artefact_name, new_classifier
+            raise ValueError(
+                f"Found already existing {new_classifier} {artefact_name}. Rerun the command with --override or --merge."
             )
-        return target_content_existing
+        return None
 
     def _get_target_class(self, new_classifier: str):
         from ara_cli.artefact_models.artefact_mapping import artefact_type_mapping