feat(cli): add options to control client generator output behavior

Author: huynguyengl99

chanx/cli/main.py

@@ -93,12 +93,33 @@ def cli() -> None:
     default=False,
     help="Skip README.md generation",
 )
+@click.option(
+    "--clear-output",
+    is_flag=True,
+    default=False,
+    help="Remove entire output directory before generation",
+)
+@click.option(
+    "--override-base",
+    is_flag=True,
+    default=False,
+    help="Regenerate base files even if they already exist",
+)
+@click.option(
+    "--no-clear-channels",
+    is_flag=True,
+    default=False,
+    help="Keep existing channel folders instead of clearing them",
+)
 def generate_client(
     schema: str,
     output: Path,
     formatter: str | None,
     no_format: bool,
     no_readme: bool,
+    clear_output: bool,
+    override_base: bool,
+    no_clear_channels: bool,
 ) -> None:
     """
     Generate a type-safe WebSocket client from an AsyncAPI schema.
@@ -127,6 +148,15 @@ def generate_client(
         # Skip README generation
         chanx generate-client --schema asyncapi.json --output ./myclient --no-readme
 
+        # Clear entire output directory before generation
+        chanx generate-client --schema asyncapi.json --output ./myclient --clear-output
+
+        # Force regenerate base files
+        chanx generate-client --schema asyncapi.json --output ./myclient --override-base
+
+        # Keep existing channel folders (don't clear them)
+        chanx generate-client --schema asyncapi.json --output ./myclient --no-clear-channels
+
         # With URL
         chanx generate-client --schema https://example.com/api/asyncapi.json --output ./myclient
     """
@@ -138,6 +168,9 @@ def generate_client(
             schema_path=schema,
             output_dir=str(output),
             generate_readme=not no_readme,
+            clear_output=clear_output,
+            override_base=override_base,
+            clear_channels=not no_clear_channels,
         )
 
         # Display parsed info

chanx/client_generator/generator.py

@@ -41,6 +41,9 @@ def __init__(
         schema_path: str,
         output_dir: str,
         generate_readme: bool = True,
+        clear_output: bool = False,
+        override_base: bool = False,
+        clear_channels: bool = True,
     ):
         """
         Initialize client generator.
@@ -49,10 +52,16 @@ def __init__(
             schema_path: Path to AsyncAPI schema file
             output_dir: Output directory for generated code
             generate_readme: Whether to generate README.md file
+            clear_output: Whether to remove entire output directory before generation
+            override_base: Whether to regenerate base files even if they exist
+            clear_channels: Whether to clear channel folders (except base) before generation
         """
         self.schema_path = schema_path
         self.output_dir = Path(output_dir)
         self.generate_readme = generate_readme
+        self.clear_output = clear_output
+        self.override_base = override_base
+        self.clear_channels = clear_channels
 
         # Load and parse schema
         schema_dict = SchemaLoader.load(schema_path)
@@ -91,9 +100,18 @@ def generate(self) -> None:
 
     def _create_directory_structure(self) -> None:
         """Create output directory structure."""
-        # Remove existing directory if it exists
         if self.output_dir.exists():
-            shutil.rmtree(self.output_dir)
+            if self.clear_output:
+                # Remove entire directory
+                shutil.rmtree(self.output_dir)
+            elif self.clear_channels:
+                # Remove everything except base folder
+                for item in self.output_dir.iterdir():
+                    if item.name != "base":
+                        if item.is_dir():
+                            shutil.rmtree(item)
+                        else:
+                            item.unlink()
 
         # Create directories
         self.output_dir.mkdir(parents=True, exist_ok=True)
@@ -109,11 +127,12 @@ def _create_directory_structure(self) -> None:
 
     def _generate_base(self) -> None:
         """Generate base client class."""
-        # Copy the base directory from the client generator to the output directory
         source_base_dir = self.client_generator_path / "base"
         target_base_dir = self.output_dir / "base"
 
-        shutil.copytree(source_base_dir, target_base_dir, dirs_exist_ok=True)
+        # Only regenerate base if it doesn't exist or override_base is True
+        if self.override_base or not target_base_dir.exists():
+            shutil.copytree(source_base_dir, target_base_dir, dirs_exist_ok=True)
 
     def _generate_shared_schemas(self) -> None:
         """Generate shared message schemas used across multiple channels."""
@@ -194,7 +213,7 @@ def _generate_channel_messages(
                     if m.payload and m.payload.title
                 )
             )
-            lines.append(f'IncomingMessage = {" | ".join(incoming_titles)}')
+            lines.append(f"IncomingMessage = {' | '.join(incoming_titles)}")
             exported_classes.append("IncomingMessage")
 
         if outgoing_messages:
@@ -205,7 +224,7 @@ def _generate_channel_messages(
                     if m.payload and m.payload.title
                 )
             )
-            lines.append(f'OutgoingMessage = {" | ".join(outgoing_titles)}')
+            lines.append(f"OutgoingMessage = {' | '.join(outgoing_titles)}")
             exported_classes.append("OutgoingMessage")
 
         if lines:

docs/user-guide/client-generator.rst

@@ -219,6 +219,18 @@ Basic Usage
 ``--no-readme``
     Skip README.md generation
 
+``--clear-output``
+    Remove entire output directory before generation
+
+``--override-base``
+    Regenerate base files even if they already exist
+
+``--no-clear-channels``
+    Keep existing channel folders instead of clearing them
+
+.. note::
+   By default, regeneration keeps the ``base/`` folder (preserving customizations) and clears channel folders. Use ``--clear-output`` for a fresh start or ``--override-base`` to update base files.
+
 Examples
 ~~~~~~~~
 
@@ -273,6 +285,24 @@ Examples
         --output ./myclient \
         --no-readme
 
+**Fresh Regeneration (Clear Everything):**
+
+.. code-block:: bash
+
+    chanx generate-client \
+        --schema asyncapi.json \
+        --output ./myclient \
+        --clear-output
+
+**Update Base Files:**
+
+.. code-block:: bash
+
+    chanx generate-client \
+        --schema asyncapi.json \
+        --output ./myclient \
+        --override-base
+
 
 Generated Client Structure
 --------------------------

tests/client_generation/test_cli.py

@@ -159,6 +159,9 @@ def test_generate_client_help(self) -> None:
         assert "--formatter" in result.output
         assert "--no-format" in result.output
         assert "--no-readme" in result.output
+        assert "--clear-output" in result.output
+        assert "--override-base" in result.output
+        assert "--no-clear-channels" in result.output
 
     def test_generate_client_with_custom_formatter(self) -> None:
         """Test client generation with custom formatter command."""
@@ -206,8 +209,8 @@ def test_generate_client_formatter_not_found(self) -> None:
             or "Formatter" in result.output
         )
 
-    def test_generate_client_overwrites_existing_directory(self) -> None:
-        """Test that generating to existing directory overwrites it."""
+    def test_generate_client_default_keeps_base(self) -> None:
+        """Test that default generation keeps base folder but clears channels."""
         output_dir = self.tmp_path / "client"
 
         # Generate once
@@ -224,7 +227,11 @@ def test_generate_client_overwrites_existing_directory(self) -> None:
         )
         assert result1.exit_code == 0
 
-        # Create a dummy file
+        # Create a custom file in base
+        base_custom = output_dir / "base" / "custom.txt"
+        base_custom.write_text("Custom base file")
+
+        # Create a dummy file in root
         dummy_file = output_dir / "dummy.txt"
         dummy_file.write_text("This should be removed")
 
@@ -242,9 +249,132 @@ def test_generate_client_overwrites_existing_directory(self) -> None:
         )
         assert result2.exit_code == 0
 
-        # Dummy file should be removed
+        # Base custom file should still exist
+        assert base_custom.exists()
+        # Root dummy file should be removed
         assert not dummy_file.exists()
 
+    def test_generate_client_clear_output(self) -> None:
+        """Test that --clear-output removes entire directory."""
+        output_dir = self.tmp_path / "client"
+
+        # Generate once
+        result1 = self.runner.invoke(
+            cli,
+            [
+                "generate-client",
+                "--schema",
+                str(self.schema_path),
+                "--output",
+                str(output_dir),
+                "--no-format",
+            ],
+        )
+        assert result1.exit_code == 0
+
+        # Create a custom file in base
+        base_custom = output_dir / "base" / "custom.txt"
+        base_custom.write_text("Custom base file")
+
+        # Generate again with --clear-output
+        result2 = self.runner.invoke(
+            cli,
+            [
+                "generate-client",
+                "--schema",
+                str(self.schema_path),
+                "--output",
+                str(output_dir),
+                "--no-format",
+                "--clear-output",
+            ],
+        )
+        assert result2.exit_code == 0
+
+        # Base custom file should be removed (entire directory was cleared)
+        assert not base_custom.exists()
+
+    def test_generate_client_override_base(self) -> None:
+        """Test that --override-base regenerates base files."""
+        output_dir = self.tmp_path / "client"
+
+        # Generate once
+        result1 = self.runner.invoke(
+            cli,
+            [
+                "generate-client",
+                "--schema",
+                str(self.schema_path),
+                "--output",
+                str(output_dir),
+                "--no-format",
+            ],
+        )
+        assert result1.exit_code == 0
+
+        # Modify a file in base
+        client_file = output_dir / "base" / "client.py"
+        original_content = client_file.read_text()
+        client_file.write_text("# Modified content")
+
+        # Generate again with --override-base
+        result2 = self.runner.invoke(
+            cli,
+            [
+                "generate-client",
+                "--schema",
+                str(self.schema_path),
+                "--output",
+                str(output_dir),
+                "--no-format",
+                "--override-base",
+            ],
+        )
+        assert result2.exit_code == 0
+
+        # Base client.py should be restored to original
+        assert client_file.read_text() == original_content
+
+    def test_generate_client_no_clear_channels(self) -> None:
+        """Test that --no-clear-channels keeps existing channel files."""
+        output_dir = self.tmp_path / "client"
+
+        # Generate once
+        result1 = self.runner.invoke(
+            cli,
+            [
+                "generate-client",
+                "--schema",
+                str(self.schema_path),
+                "--output",
+                str(output_dir),
+                "--no-format",
+            ],
+        )
+        assert result1.exit_code == 0
+
+        # Create a custom file in a channel
+        channel_custom = output_dir / "chat" / "custom.txt"
+        channel_custom.write_text("Custom channel file")
+
+        # Generate again with --no-clear-channels
+        result2 = self.runner.invoke(
+            cli,
+            [
+                "generate-client",
+                "--schema",
+                str(self.schema_path),
+                "--output",
+                str(output_dir),
+                "--no-format",
+                "--no-clear-channels",
+            ],
+        )
+        assert result2.exit_code == 0
+
+        # Custom channel file should still exist
+        assert channel_custom.exists()
+
     def test_generate_client_formatter_timeout(self) -> None:
         """Test that formatter timeout is handled gracefully."""
         import subprocess