rpr-cli 0.1.1__py3-none-any.whl

rpr/application/catalog.py

@@ -0,0 +1,427 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+
+@dataclass(slots=True, frozen=True)
+class CommandOption:
+    long_name: str = field(
+        metadata={
+            "description": "Long option name rendered and invoked as --<long-name>."
+        }
+    )
+    description: str = field(
+        metadata={"description": "Help text shown in discovery and help output."}
+    )
+    kind: Literal["flag", "value"] = field(
+        metadata={
+            "description": "Whether the option is a boolean flag or requires a value."
+        }
+    )
+    short_name: str | None = field(
+        default=None,
+        metadata={
+            "description": "Optional short alias rendered and invoked as -<short-name>."
+        },
+    )
+    value_name: str | None = field(
+        default=None,
+        metadata={
+            "description": "Placeholder shown when the option expects a value, e.g. MODEL or PATH."
+        },
+    )
+
+
+@dataclass(slots=True, frozen=True)
+class CommandArgument:
+    name: str = field(
+        metadata={"description": "Positional argument name used in usage text."}
+    )
+    description: str = field(
+        metadata={"description": "Meaning of the argument for help and picker UIs."}
+    )
+    required: bool = field(
+        default=True,
+        metadata={"description": "Whether the argument is required."},
+    )
+
+
+@dataclass(slots=True, frozen=True)
+class CommandDefinition:
+    name: str = field(
+        metadata={
+            "description": "Canonical command token shared by CLI and slash-command adapters."
+        }
+    )
+    description: str = field(
+        metadata={"description": "Short description shown in help and command pickers."}
+    )
+    action_id: str | None = field(
+        default=None,
+        metadata={
+            "description": "Stable application action identifier used for leaf-command dispatch."
+        },
+    )
+    aliases: tuple[str, ...] = field(
+        default_factory=tuple,
+        metadata={
+            "description": "Alternative tokens that resolve to the same command."
+        },
+    )
+    arguments: tuple[CommandArgument, ...] = field(
+        default_factory=tuple,
+        metadata={"description": "Positional arguments accepted by this command."},
+    )
+    options: tuple[CommandOption, ...] = field(
+        default_factory=tuple,
+        metadata={"description": "Supported flags and value options."},
+    )
+    children: tuple[CommandDefinition, ...] = field(
+        default_factory=tuple,
+        metadata={
+            "description": "Nested subcommands for grouped commands such as generate or sync."
+        },
+    )
+    chat_enabled: bool = field(
+        default=True,
+        metadata={
+            "description": "Whether the command is available as a slash command in the chat shell."
+        },
+    )
+    cli_enabled: bool = field(
+        default=True,
+        metadata={
+            "description": "Whether the command is available from the top-level CLI."
+        },
+    )
+    interactive: bool = field(
+        default=False,
+        metadata={
+            "description": "Whether the command opens a follow-up interactive flow."
+        },
+    )
+    default_root_command: bool = field(
+        default=False,
+        metadata={
+            "description": "Marks the command that runs when rpr is invoked without a subcommand."
+        },
+    )
+
+
+COMMAND_CATALOG: tuple[CommandDefinition, ...] = (
+    CommandDefinition(
+        name="chat",
+        description="Start the primary interactive chat shell.",
+        action_id="chat.start",
+        interactive=True,
+        default_root_command=True,
+        options=(
+            CommandOption(
+                "--provider",
+                "Override the AI provider.",
+                kind="value",
+                value_name="PROVIDER",
+            ),
+            CommandOption(
+                "--model", "Override the model name.", kind="value", value_name="MODEL"
+            ),
+            CommandOption(
+                "--approval-mode",
+                "Override the default approval mode.",
+                kind="value",
+                value_name="MODE",
+            ),
+        ),
+    ),
+    CommandDefinition(
+        name="init",
+        description="Bootstrap an NX workspace with UV workspace configuration.",
+        action_id="init.run",
+        arguments=(
+            CommandArgument(
+                "project-name", "Name of the workspace to create.", required=False
+            ),
+        ),
+        options=(
+            CommandOption(
+                "--python", "Python version to use.", kind="value", value_name="VERSION"
+            ),
+            CommandOption("--dry-run", "Preview changes without writing.", kind="flag"),
+            CommandOption(
+                "--integrated", "Use integrated NX workspace style.", kind="flag"
+            ),
+        ),
+    ),
+    CommandDefinition(
+        name="generate",
+        description="Run an existing scaffolding command from chat.",
+        action_id="generate.dispatch",
+        children=(
+            CommandDefinition(
+                name="domain",
+                description="Generate a domain package.",
+                action_id="generate.domain",
+                arguments=(CommandArgument("name", "Package name."),),
+                options=(
+                    CommandOption(
+                        "--dry-run", "Preview changes without writing.", kind="flag"
+                    ),
+                ),
+            ),
+            CommandDefinition(
+                name="api",
+                description="Generate an API app.",
+                action_id="generate.api",
+                arguments=(CommandArgument("name", "App name."),),
+                options=(
+                    CommandOption(
+                        "--dry-run", "Preview changes without writing.", kind="flag"
+                    ),
+                ),
+            ),
+            CommandDefinition(
+                name="ui",
+                description="Generate a UI package.",
+                action_id="generate.ui",
+                arguments=(CommandArgument("name", "Package name."),),
+                options=(
+                    CommandOption(
+                        "--dry-run", "Preview changes without writing.", kind="flag"
+                    ),
+                ),
+            ),
+            CommandDefinition(
+                name="engine",
+                description="Generate a Rust engine package.",
+                action_id="generate.engine",
+                arguments=(CommandArgument("name", "Package name."),),
+                options=(
+                    CommandOption(
+                        "--dry-run", "Preview changes without writing.", kind="flag"
+                    ),
+                ),
+            ),
+            CommandDefinition(
+                name="storybook",
+                description="Generate Storybook configuration for a UI package.",
+                action_id="generate.storybook",
+                options=(
+                    CommandOption(
+                        "--ui-package",
+                        "Target UI package.",
+                        kind="value",
+                        value_name="PACKAGE",
+                    ),
+                    CommandOption(
+                        "--dry-run", "Preview changes without writing.", kind="flag"
+                    ),
+                ),
+            ),
+        ),
+    ),
+    CommandDefinition(
+        name="sync",
+        description="Sync AI instructions through the existing generators.",
+        action_id="sync.dispatch",
+        children=(
+            CommandDefinition(
+                name="rules",
+                description="Read instructions and generate AI tool config files.",
+                action_id="sync.rules",
+                options=(
+                    CommandOption(
+                        "--target",
+                        "Limit sync to one generator.",
+                        kind="value",
+                        short_name="-t",
+                        value_name="GENERATOR",
+                    ),
+                    CommandOption(
+                        "--dry-run", "Preview changes without writing.", kind="flag"
+                    ),
+                ),
+            ),
+        ),
+    ),
+    CommandDefinition(
+        name="add",
+        description="Write a registered template into the current project.",
+        action_id="add.dispatch",
+        children=(
+            CommandDefinition(
+                name="template",
+                description="Apply a registered code template to the project.",
+                action_id="add.template",
+                arguments=(
+                    CommandArgument(
+                        "template-id", "Template identifier to apply.", required=False
+                    ),
+                ),
+                options=(
+                    CommandOption(
+                        "--list",
+                        "List all available templates.",
+                        kind="flag",
+                        short_name="-l",
+                    ),
+                    CommandOption(
+                        "--name",
+                        "App or package name for variable interpolation.",
+                        kind="value",
+                        short_name="-n",
+                        value_name="NAME",
+                    ),
+                    CommandOption(
+                        "--force",
+                        "Overwrite existing files.",
+                        kind="flag",
+                        short_name="-f",
+                    ),
+                    CommandOption(
+                        "--source",
+                        "Path to the rules source directory.",
+                        kind="value",
+                        value_name="PATH",
+                    ),
+                    CommandOption(
+                        "--dry-run", "Preview changes without writing.", kind="flag"
+                    ),
+                ),
+            ),
+        ),
+    ),
+    CommandDefinition(
+        name="check",
+        description="Run workspace health checks through the shared application service.",
+        action_id="check.run",
+        options=(
+            CommandOption(
+                "--group",
+                "Limit checks to one group.",
+                kind="value",
+                value_name="GROUP",
+            ),
+        ),
+    ),
+    CommandDefinition(
+        name="map",
+        description="Generate the current code-map output from chat.",
+        action_id="map.run",
+        options=(
+            CommandOption(
+                "--root", "Root directory to scan.", kind="value", value_name="PATH"
+            ),
+            CommandOption(
+                "--output", "Output file path.", kind="value", value_name="PATH"
+            ),
+            CommandOption("--dry-run", "Preview changes without writing.", kind="flag"),
+        ),
+    ),
+    CommandDefinition(
+        name="settings",
+        description="Inspect or mutate persisted shell settings.",
+        action_id="settings.dispatch",
+        children=(
+            CommandDefinition(
+                name="list",
+                description="List all settings.",
+                action_id="settings.list",
+            ),
+            CommandDefinition(
+                name="get",
+                description="Read one setting value.",
+                action_id="settings.get",
+                arguments=(CommandArgument("key", "Setting key to inspect."),),
+            ),
+            CommandDefinition(
+                name="set",
+                description="Update one setting value.",
+                action_id="settings.set",
+                arguments=(
+                    CommandArgument("key", "Setting key to update."),
+                    CommandArgument("value", "New value to persist."),
+                ),
+            ),
+        ),
+    ),
+    CommandDefinition(
+        name="help",
+        description="List slash commands and usage.",
+        action_id="help.show",
+        cli_enabled=False,
+    ),
+    CommandDefinition(
+        name="exit",
+        description="End the interactive session.",
+        action_id="chat.exit",
+        cli_enabled=False,
+    ),
+)
+
+
+def find_command(
+    catalog: tuple[CommandDefinition, ...],
+    tokens: list[str],
+) -> CommandDefinition | None:
+    """Recursively find a command by token path.
+
+    Examples::
+
+        find_command(COMMAND_CATALOG, ["generate", "ui"])  # → CommandDefinition(name="ui")
+        find_command(COMMAND_CATALOG, ["init"])             # → CommandDefinition(name="init")
+        find_command(COMMAND_CATALOG, ["unknown"])          # → None
+    """
+    if not tokens:
+        return None
+    head, *tail = tokens
+    for cmd in catalog:
+        if cmd.name == head or head in cmd.aliases:
+            if not tail:
+                return cmd
+            if cmd.children:
+                return find_command(cmd.children, tail)
+            return None
+    return None
+
+
+def chat_commands(
+    catalog: tuple[CommandDefinition, ...],
+) -> tuple[CommandDefinition, ...]:
+    """Return top-level commands available in the chat shell (chat_enabled=True)."""
+    return tuple(cmd for cmd in catalog if cmd.chat_enabled)
+
+
+def cli_commands(
+    catalog: tuple[CommandDefinition, ...],
+) -> tuple[CommandDefinition, ...]:
+    """Return top-level commands available from the CLI (cli_enabled=True)."""
+    return tuple(cmd for cmd in catalog if cmd.cli_enabled)
+
+
+def usage_string(cmd: CommandDefinition) -> str:
+    """Generate a usage string from a CommandDefinition.
+
+    Group commands show pipe-separated child names::
+
+        /generate <domain|api|ui|engine|storybook>
+
+    Leaf commands show arguments and options::
+
+        /init [project-name] [--python VERSION] [--dry-run]
+    """
+    if cmd.children:
+        child_names = "|".join(c.name for c in cmd.children)
+        return f"/{cmd.name} <{child_names}>"
+
+    parts: list[str] = [f"/{cmd.name}"]
+    for arg in cmd.arguments:
+        bracket = f"<{arg.name}>" if arg.required else f"[{arg.name}]"
+        parts.append(bracket)
+    for opt in cmd.options:
+        if opt.kind == "flag":
+            parts.append(f"[{opt.long_name}]")
+        else:
+            placeholder = opt.value_name or opt.long_name.lstrip("-").upper()
+            parts.append(f"[{opt.long_name} {placeholder}]")
+    return " ".join(parts)