scaffold-ca-python 0.1.3__py3-none-any.whl → 0.2.0__py3-none-any.whl

scaffold_ca_python/commands/delete_module.py

@@ -10,7 +10,7 @@ import typer
 from rich.console import Console
 
 from scaffold_ca_python.core.module_builder import ModuleBuilder
-from scaffold_ca_python.core.name_utils import ScaffoldError, to_snake_case, validate_name
+from scaffold_ca_python.core.name_utils import ScaffoldError, to_snake_case, validate_module_name
 from scaffold_ca_python.core.project_detector import find_project_root, resolve_tests_root
 from scaffold_ca_python.factory import ModuleFactory
 from scaffold_ca_python.factory.simple.delete_module_factory import DeleteModuleFactory
@@ -24,7 +24,7 @@ _REGISTRY: dict[str, type[ModuleFactory]] = {
 }
 
 _DM_HELP = "Delete a previously generated module and its test mirror. Alias 'dm'."
-_DM_EPILOG = "Examples:\n\n  * scaffold dm --name Order\n\n  * scaffold delete-module --name MyAdapter\n\n"
+_DM_EPILOG = "Examples:\n\n  * scaffold dm --name order\n\n  * scaffold delete-module --name my_adapter\n\n"
 
 
 # ---------------------------------------------------------------------------
@@ -32,7 +32,7 @@ _DM_EPILOG = "Examples:\n\n  * scaffold dm --name Order\n\n  * scaffold delete-m
 # ---------------------------------------------------------------------------
 
 
-def _find_module_targets(project_root: Path, snake: str) -> list[tuple[Path, Path | None]]:
+def _find_module_targets(pkg: str, project_root: Path, snake: str) -> list[tuple[Path, Path | None]]:
     """Return a list of (target_path, test_path_or_None) for all matches of *snake*.
 
     Searches across:
@@ -42,7 +42,6 @@ def _find_module_targets(project_root: Path, snake: str) -> list[tuple[Path, Pat
       4. infrastructure/entry_points/<snake>/
       5. infrastructure/helpers/<snake>/
     """
-    pkg = _get_python_package(project_root)
     src_root = project_root / "src" / pkg
     tests_root = resolve_tests_root(project_root)
 
@@ -77,20 +76,6 @@ def _find_module_targets(project_root: Path, snake: str) -> list[tuple[Path, Pat
     return candidates
 
 
-def _get_python_package(root: Path) -> str:
-    pyproject = root / "pyproject.toml"
-    with pyproject.open("rb") as fh:
-        data = tomllib.load(fh)
-    section = data.get("tool", {}).get("scaffold-ca-python", {})
-    name = section.get("name", root.name)
-    import re
-
-    s = name.replace("-", "_")
-    s = re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1_\2", s)
-    s = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", s)
-    return s.lower()
-
-
 # ---------------------------------------------------------------------------
 # Implementation
 # ---------------------------------------------------------------------------
@@ -99,7 +84,7 @@ def _get_python_package(root: Path) -> str:
 def _delete_module_impl(name: str, confirm: bool, dry_run: bool) -> None:
     # Validate name
     try:
-        validate_name(name)
+        validate_module_name(name)
     except ScaffoldError as exc:
         console.print(f"[red]Error:[/red] {exc}")
         raise typer.Exit(code=1) from None
@@ -118,7 +103,7 @@ def _delete_module_impl(name: str, confirm: bool, dry_run: bool) -> None:
 
     # Find targets
     snake = to_snake_case(name)
-    targets = _find_module_targets(project_root, snake)
+    targets = _find_module_targets(project_ctx.python_package, project_root, snake)
 
     if not targets:
         console.print(
@@ -174,7 +159,7 @@ def register(app: typer.Typer) -> None:
     def delete_module(
         ctx: typer.Context,
         name: Annotated[
-            str | None, typer.Option("--name", help="Module name (PascalCase).", rich_help_panel="Required")
+            str | None, typer.Option("--name", help="Module name (snake_case).", rich_help_panel="Required")
         ] = None,
         confirm: Annotated[
             bool,

scaffold_ca_python/commands/generate_driven_adapter.py

@@ -8,10 +8,11 @@ from typing import Annotated
 
 import typer
 from rich.console import Console
+from rich.markup import escape
 from rich.tree import Tree
 
 from scaffold_ca_python.core.module_builder import ModuleBuilder
-from scaffold_ca_python.core.name_utils import ScaffoldError, to_snake_case, validate_name
+from scaffold_ca_python.core.name_utils import ScaffoldError, to_snake_case, validate_module_name
 from scaffold_ca_python.core.project_detector import find_project_root
 from scaffold_ca_python.factory import ModuleFactory
 from scaffold_ca_python.factory.driven_adapters.da_generic import DrivenAdapterGeneric
@@ -37,7 +38,7 @@ _GDA_EPILOG = (
     " ==================================================\n\n"
     "Examples:\n\n"
     "  * scaffold gda --type rest-consumer\n\n"
-    "  * scaffold generate-driven-adapter --type generic --name MyAdapter\n\n"
+    "  * scaffold generate-driven-adapter --type generic --name my_adapter\n\n"
 )
 
 
@@ -55,7 +56,7 @@ def _generate_driven_adapter_impl(type_: str, name: str | None, dry_run: bool) -
     # --- Validate name if provided ---
     if name:
         try:
-            validate_name(name)
+            validate_module_name(name)
         except ScaffoldError as exc:
             console.print(f"[red]Error:[/red] {exc}")
             raise typer.Exit(code=1) from None
@@ -116,8 +117,12 @@ def _generate_driven_adapter_impl(type_: str, name: str | None, dry_run: bool) -
         for p in sorted(created):
             tree.add(str(p.relative_to(project_root)))
         console.print(tree)
-        if builder._dependencies:
-            console.print(f"[dim]Would add to [project.dependencies]: {', '.join(builder._dependencies)}[/dim]")
+        if builder.pending_dependencies:
+            target = escape("[project.dependencies]")
+            console.print(f"[dim]Would add to {target}: {', '.join(builder.pending_dependencies)}[/dim]")
+        for grp, pkgs in builder.pending_group_dependencies.items():
+            target = escape(f"[dependency-groups.{grp}]")
+            console.print(f"[dim]Would add to {target}: {', '.join(pkgs)}[/dim]")
         return
 
     console.print(f"[green]✓[/green] Driven adapter [bold]{subdir}[/bold] created. Created {len(created)} file(s).")
@@ -146,7 +151,7 @@ def register(app: typer.Typer) -> None:
             str | None,
             typer.Option(
                 "--name",
-                help="Adapter name (required for --type generic).",
+                help="Adapter name in snake_case, e.g. my_adapter (required for --type generic).",
                 rich_help_panel="Options",
             ),
         ] = None,

scaffold_ca_python/commands/generate_entry_point.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import ast
 import json
 import tomllib
 from pathlib import Path
@@ -10,11 +11,14 @@ from typing import Annotated
 import typer
 import yaml
 from rich.console import Console
+from rich.markup import escape
+from rich.syntax import Syntax
 from rich.tree import Tree
 
+from scaffold_ca_python.core import mcp_tool_spec
 from scaffold_ca_python.core.module_builder import ModuleBuilder
-from scaffold_ca_python.core.name_utils import ScaffoldError
-from scaffold_ca_python.core.project_detector import find_project_root
+from scaffold_ca_python.core.name_utils import ScaffoldError, to_snake_case
+from scaffold_ca_python.core.project_detector import find_project_root, resolve_tests_root
 from scaffold_ca_python.factory import ModuleFactory
 from scaffold_ca_python.factory.entry_points.ep_agent import EntryPointAgent
 from scaffold_ca_python.factory.entry_points.ep_generic import EntryPointGeneric
@@ -44,12 +48,11 @@ _GEP_EPILOG = (
     "  * mcp        MCP server entry point\n\n"
     "  * generic    Plain entry point\n\n"
     " ==================================================\n\n"
-    "Notes: --enable-kafka and --enable-mcp-client are agent type only.\n\n"
-    " ==================================================\n\n"
     "Examples:\n\n"
     "  * scaffold gep --type restapi\n\n"
     "  * scaffold gep --type agent --enable-kafka\n\n"
     "  * scaffold gep --type mcp\n\n"
+    "  * scaffold gep --type mcp --add-tool --name create_file --param path:str --returns str\n\n"
     "  * scaffold generate-entry-point --type generic\n"
 )
 
@@ -59,10 +62,239 @@ def _load_project_context(project_root: Path) -> ProjectContext:
     pyproject_path = project_root / "pyproject.toml"
     with open(pyproject_path, "rb") as f:
         data = tomllib.load(f)
-    project_name = data.get("project", {}).get("name", "project").replace("-", "_")
+    project_name = to_snake_case(data.get("project", {}).get("name", "project"))
     return ProjectContext(name=project_name)
 
 
+def _add_tool_impl(
+    type_: str,
+    swagger: str | None,
+    enable_kafka: bool,
+    enable_mcp_client: bool,
+    with_resources: bool,
+    with_prompts: bool,
+    name: str | None,
+    param: list[str] | None,
+    returns: str,
+    description: str | None,
+    dry_run: bool,
+) -> None:
+    """Add a tool to an existing MCP entry point (T018-T021, T027-T030a).
+
+    Implements User Story 1 and 2: appends a tool stub to tools.py and a registration
+    test to test_tools.py in an existing MCP project, with comprehensive guard rails.
+    """
+    # T028: Flag/type incompatibility guards (FR-011, FR-012) - before project access
+    # Check creation-only flags
+    creation_flags = []
+    if swagger is not None:
+        creation_flags.append("--swagger")
+    if enable_kafka:
+        creation_flags.append("--enable-kafka")
+    if enable_mcp_client:
+        creation_flags.append("--enable-mcp-client")
+    if with_resources:
+        creation_flags.append("--with-resources")
+    if with_prompts:
+        creation_flags.append("--with-prompts")
+
+    if creation_flags:
+        flag = creation_flags[0]
+        console.print(f"[red]Error:[/red] --add-tool is incompatible with {flag}.")
+        raise typer.Exit(code=1)
+
+    # Check type compatibility (FR-012) - handled by T016(a) for --type omitted
+    # Here we check non-mcp types
+    if type_ != "mcp":
+        console.print("[red]Error:[/red] --add-tool is only valid with --type mcp.")
+        raise typer.Exit(code=1)
+
+    # T018: Format-only validation (no filesystem access yet)
+    if name is None:
+        console.print("[red]Error:[/red] --name is required with --add-tool.")
+        raise typer.Exit(code=1)
+
+    try:
+        tool_spec = mcp_tool_spec.build_tool_spec(name, param, returns, description)
+    except (ValueError, ScaffoldError) as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(code=1) from None
+
+    # T019: Resolve project root and check entry point exists
+    try:
+        project_root = find_project_root()
+    except ScaffoldError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(code=1) from None
+
+    project_ctx = _load_project_context(project_root)
+
+    tools_py_path = (
+        project_root
+        / "src"
+        / project_ctx.python_package
+        / "infrastructure"
+        / "entry_points"
+        / "mcp_server"
+        / "tools.py"
+    )
+    test_tools_py_path = (
+        resolve_tests_root(project_root) / "infrastructure" / "entry_points" / "mcp_server" / "test_tools.py"
+    )
+
+    if not tools_py_path.exists():
+        console.print(
+            "[red]Error:[/red] No MCP entry point found at infrastructure/entry_points/mcp_server/.\n"
+            "[dim]Hint:[/dim] Run [cyan]scaffold gep --type mcp[/cyan] first to create one."
+        )
+        raise typer.Exit(code=1)
+
+    # T020: Read files and check structure
+    try:
+        original_tools_py = tools_py_path.read_text(encoding="utf-8")
+    except OSError as e:
+        console.print(f"[red]Error:[/red] Cannot read {tools_py_path}: {e}")
+        raise typer.Exit(code=1) from None
+
+    try:
+        original_test_tools_py = test_tools_py_path.read_text(encoding="utf-8")
+    except OSError:
+        console.print(
+            "[red]Error:[/red] tests/infrastructure/entry_points/mcp_server/test_tools.py is missing or "
+            "does not have\n"
+            "the structure --add-tool needs to append a registration test.\n"
+            "[dim]Hint:[/dim] Restore test_tools.py, or regenerate the entry point with "
+            "[cyan]scaffold gep --type mcp[/cyan]."
+        )
+        raise typer.Exit(code=1)
+
+    # Check bind_tools is last top-level statement
+    if not mcp_tool_spec.has_bind_tools_function(original_tools_py):
+        console.print(
+            "[red]Error:[/red] infrastructure/entry_points/mcp_server/tools.py was generated by an older "
+            "scaffold\n"
+            "version and does not support --add-tool.\n"
+            "[dim]Hint:[/dim] Make [cyan]async def bind_tools[/cyan] the last function in tools.py, or "
+            "regenerate the entry point\n"
+            "(back up any custom tools first) with [cyan]scaffold gep --type mcp[/cyan]."
+        )
+        raise typer.Exit(code=1)
+
+    # Check test file has required structure
+    if not mcp_tool_spec.has_test_registration_structure(original_test_tools_py):
+        console.print(
+            "[red]Error:[/red] tests/infrastructure/entry_points/mcp_server/test_tools.py is missing or "
+            "does not have\n"
+            "the structure --add-tool needs to append a registration test.\n"
+            "[dim]Hint:[/dim] Restore test_tools.py, or regenerate the entry point with "
+            "[cyan]scaffold gep --type mcp[/cyan]."
+        )
+        raise typer.Exit(code=1)
+
+    # Check for duplicate tool names
+    existing_names = mcp_tool_spec.find_existing_tool_names(original_tools_py)
+    if tool_spec.name in existing_names:
+        if tool_spec.name == "bind_tools":
+            console.print(
+                f"[red]Error:[/red] '{tool_spec.name}' is reserved by the tool-binding function and "
+                "cannot be used as a tool name."
+            )
+        else:
+            console.print(f"[red]Error:[/red] A tool named '{tool_spec.name}' already exists in tools.py.")
+        raise typer.Exit(code=1)
+
+    # T021: Render templates and append
+    builder = ModuleBuilder(
+        project_root=project_root,
+        project_ctx=project_ctx,
+        dry_run=dry_run,
+    )
+
+    # Render tool stub (4-space-indented nested function)
+    tool_stub_content = builder.render(
+        "entry_point/mcp/tool_stub.py.jinja2",
+        {
+            "name": tool_spec.name,
+            "params": [{"name": p.name, "type": p.type} for p in tool_spec.params],
+            "returns": tool_spec.returns,
+            "docstring": tool_spec.docstring,
+        },
+    )
+
+    # Render test stub
+    test_stub_content = builder.render(
+        "entry_point/mcp/test_tool_stub.py.jinja2",
+        {"name": tool_spec.name},
+    )
+
+    # Safety check: ensure appended content will parse
+    try:
+        ast.parse(original_tools_py + tool_stub_content)
+    except SyntaxError:
+        console.print(
+            "[red]Error:[/red] infrastructure/entry_points/mcp_server/tools.py cannot accept the new tool stub.\n"
+            "[dim]Hint:[/dim] Regenerate the entry point with [cyan]scaffold gep --type mcp[/cyan]."
+        )
+        raise typer.Exit(code=1)
+
+    # T030a: Check writability before any writes (FR-019)
+    import os
+
+    if not os.access(tools_py_path, os.W_OK):
+        console.print(
+            f"[red]Error:[/red] Cannot write to {tools_py_path.relative_to(project_root)}.\n"
+            "[dim]Hint:[/dim] Check the file's permissions and re-run the command."
+        )
+        raise typer.Exit(code=1)
+
+    if not os.access(test_tools_py_path, os.W_OK):
+        console.print(
+            f"[red]Error:[/red] Cannot write to {test_tools_py_path.relative_to(project_root)}.\n"
+            "[dim]Hint:[/dim] Check the file's permissions and re-run the command."
+        )
+        raise typer.Exit(code=1)
+
+    # Queue append operations
+    builder.append_to_file(tools_py_path, tool_stub_content)
+    builder.append_to_file(test_tools_py_path, test_stub_content)
+
+    # T030a: Persist changes with restore-on-failure (FR-019)
+    try:
+        modified_paths = builder.persist()
+    except OSError as e:
+        # Restore original content
+        try:
+            tools_py_path.write_text(original_tools_py, encoding="utf-8")
+            test_tools_py_path.write_text(original_test_tools_py, encoding="utf-8")
+        except OSError:
+            pass  # Best effort restore
+
+        # Determine which file failed
+        error_str = str(e).lower()
+        if "test_tools" in error_str or str(test_tools_py_path) in str(e):
+            failed_file = "test_tools.py"
+        else:
+            failed_file = "tools.py"
+
+        console.print(
+            f"[red]Error:[/red] Failed to write {failed_file} ({e}). "
+            "tools.py was restored; no changes were made.\n"
+            "[dim]Hint:[/dim] Fix the underlying problem (permissions, disk space) and re-run the command."
+        )
+        raise typer.Exit(code=1) from None
+
+    if dry_run:
+        console.print("\n[yellow]Dry run:[/yellow] Would modify:\n")
+        for path in modified_paths:
+            console.print(f"  • {path.relative_to(project_root)}")
+        console.print("\n[yellow]Tool stub preview:[/yellow]")
+        console.print(Syntax(tool_stub_content, "python", theme="monokai", line_numbers=False))
+        console.print("\n[yellow]Test stub preview:[/yellow]")
+        console.print(Syntax(test_stub_content, "python", theme="monokai", line_numbers=False))
+    else:
+        console.print(f"[green]✓[/green] Added tool '{tool_spec.name}' to MCP entry point.")
+
+
 def _generate_entry_point_impl(
     type_: str,
     swagger: str | None,
@@ -70,8 +302,30 @@ def _generate_entry_point_impl(
     enable_mcp_client: bool,
     with_resources: bool,
     with_prompts: bool,
+    add_tool: bool,
+    name: str | None,
+    param: list[str] | None,
+    returns: str,
+    description: str | None,
     dry_run: bool,
 ) -> None:
+    # T016(b): Dispatch to --add-tool implementation if flag is set
+    if add_tool:
+        _add_tool_impl(
+            type_,
+            swagger,
+            enable_kafka,
+            enable_mcp_client,
+            with_resources,
+            with_prompts,
+            name,
+            param,
+            returns,
+            description,
+            dry_run,
+        )
+        return
+
     # --- Validate type ---
     if type_ not in _REGISTRY:
         console.print(f"[red]Error:[/red] Unknown type '{type_}'. Allowed: {', '.join(_REGISTRY.keys())}.")
@@ -190,9 +444,10 @@ def _generate_entry_point_impl(
             tree.add(str(p.relative_to(project_root)))
         console.print(tree)
 
-        # Check if dependencies were collected by looking at builder internals
-        if builder._dependencies:
-            console.print(f"[dim]Would add to [project.dependencies]: {', '.join(builder._dependencies)}[/dim]")
+        # Report any runtime dependencies queued for injection
+        if builder.pending_dependencies:
+            target = escape("[project.dependencies]")
+            console.print(f"[dim]Would add to {target}: {', '.join(builder.pending_dependencies)}[/dim]")
 
         if type_ == "restapi":
             main_py = project_root / "src" / pkg / "main.py"
@@ -285,6 +540,24 @@ def register(app: typer.Typer) -> None:
                 show_default=True,
             ),
         ] = False,
+        add_tool: Annotated[
+            bool,
+            typer.Option(
+                "--add-tool/--no-add-tool",
+                help="Add a tool to an existing MCP entry point (mcp only).",
+                rich_help_panel="Options",
+                show_default=True,
+            ),
+        ] = False,
+        name: Annotated[str | None, typer.Option("--name", help="Tool name (required with --add-tool).")] = None,
+        param: Annotated[
+            list[str] | None,
+            typer.Option("--param", help="Tool parameter in 'name:type' format (repeatable)."),
+        ] = None,
+        returns: Annotated[str, typer.Option("--returns", help="Tool return type.")] = "str",
+        description: Annotated[
+            str | None, typer.Option("--description", help="Tool description for docstring.")
+        ] = None,
         dry_run: Annotated[
             bool,
             typer.Option(
@@ -296,9 +569,25 @@ def register(app: typer.Typer) -> None:
         ] = False,
     ) -> None:
         """Scaffold an entry point inside infrastructure/entry_points/."""
+        # T016(a): Check --add-tool without --type before the help shortcut
+        if add_tool and type_ is None:
+            console.print("[red]Error:[/red] --add-tool is only valid with --type mcp.")
+            raise typer.Exit(code=1)
+
         if type_ is None:
             typer.echo(ctx.get_help())
             raise typer.Exit(0)
         _generate_entry_point_impl(
-            type_, swagger, enable_kafka, enable_mcp_client, with_resources, with_prompts, dry_run
+            type_,
+            swagger,
+            enable_kafka,
+            enable_mcp_client,
+            with_resources,
+            with_prompts,
+            add_tool,
+            name,
+            param,
+            returns,
+            description,
+            dry_run,
         )

scaffold_ca_python/commands/generate_helper.py

@@ -11,7 +11,7 @@ from rich.console import Console
 from rich.tree import Tree
 
 from scaffold_ca_python.core.module_builder import ModuleBuilder
-from scaffold_ca_python.core.name_utils import ScaffoldError, to_snake_case, validate_name
+from scaffold_ca_python.core.name_utils import ScaffoldError, to_snake_case, validate_module_name
 from scaffold_ca_python.core.project_detector import find_project_root
 from scaffold_ca_python.factory import ModuleFactory
 from scaffold_ca_python.factory.simple.helper_factory import HelperFactory
@@ -25,13 +25,13 @@ _REGISTRY: dict[str, type[ModuleFactory]] = {
 }
 
 _GH_HELP = "Scaffold a helper utility module and test stub. Alias 'gh'."
-_GH_EPILOG = "Example:\n\n  * scaffold gh --name JsonParser\n\n  * scaffold generate-helper --name JsonParser\n\n"
+_GH_EPILOG = "Example:\n\n  * scaffold gh --name json_parser\n\n  * scaffold generate-helper --name json_parser\n\n"
 
 
 def _generate_helper_impl(name: str, dry_run: bool) -> None:
     # --- Validate name ---
     try:
-        validate_name(name)
+        validate_module_name(name)
     except ScaffoldError as exc:
         console.print(f"[red]Error:[/red] {exc}")
         raise typer.Exit(code=1) from None
@@ -100,7 +100,7 @@ def register(app: typer.Typer) -> None:
     def generate_helper(
         ctx: typer.Context,
         name: Annotated[
-            str | None, typer.Option("--name", help="Helper name (PascalCase).", rich_help_panel="Required")
+            str | None, typer.Option("--name", help="Helper name (snake_case).", rich_help_panel="Required")
         ] = None,
         dry_run: Annotated[
             bool,

scaffold_ca_python/commands/generate_model.py

@@ -11,7 +11,7 @@ from rich.console import Console
 from rich.tree import Tree
 
 from scaffold_ca_python.core.module_builder import ModuleBuilder
-from scaffold_ca_python.core.name_utils import ScaffoldError, validate_name
+from scaffold_ca_python.core.name_utils import ScaffoldError, validate_module_name
 from scaffold_ca_python.core.project_detector import find_project_root
 from scaffold_ca_python.factory import ModuleFactory
 from scaffold_ca_python.factory.simple.model_factory import ModelFactory
@@ -24,13 +24,13 @@ _REGISTRY: dict[str, type[ModuleFactory]] = {
     "model": ModelFactory,
 }
 _GM_HELP = "Scaffold a Pydantic v2 domain model and test stub. Alias 'gm'."
-_GM_EPILOG = "Example:\n\n  * scaffold gm --name Order\n\n  * scaffold generate-model --name Order\n\n"
+_GM_EPILOG = "Example:\n\n  * scaffold gm --name order\n\n  * scaffold generate-model --name order\n\n"
 
 
 def _generate_model_impl(name: str, dry_run: bool) -> None:
     # --- Validate name ---
     try:
-        validate_name(name)
+        validate_module_name(name)
     except ScaffoldError as exc:
         console.print(f"[red]Error:[/red] {exc}")
         raise typer.Exit(code=1) from None
@@ -100,7 +100,7 @@ def register(app: typer.Typer) -> None:
     def generate_model(
         ctx: typer.Context,
         name: Annotated[
-            str | None, typer.Option("--name", help="Model name (PascalCase).", rich_help_panel="Required")
+            str | None, typer.Option("--name", help="Model name (snake_case).", rich_help_panel="Required")
         ] = None,
         dry_run: Annotated[
             bool,

scaffold_ca_python/commands/generate_project.py

@@ -151,7 +151,7 @@ def register(app: typer.Typer) -> None:
             str,
             typer.Option(
                 "--name",
-                help="Project name (PascalCase or snake_case).",
+                help="Project name (kebab-case or snake_case).",
                 rich_help_panel="Required",
             ),
         ] = None,  # type: ignore[assignment]

scaffold_ca_python/commands/generate_use_case.py

@@ -11,7 +11,7 @@ from rich.console import Console
 from rich.tree import Tree
 
 from scaffold_ca_python.core.module_builder import ModuleBuilder
-from scaffold_ca_python.core.name_utils import ScaffoldError, to_snake_case, validate_name
+from scaffold_ca_python.core.name_utils import ScaffoldError, to_snake_case, validate_module_name
 from scaffold_ca_python.core.project_detector import find_project_root
 from scaffold_ca_python.factory import ModuleFactory
 from scaffold_ca_python.factory.simple.use_case_factory import UseCaseFactory
@@ -24,13 +24,15 @@ _REGISTRY: dict[str, type[ModuleFactory]] = {
     "use_case": UseCaseFactory,
 }
 _GUC_HELP = "Scaffold a use case in domain/usecase/. Alias 'guc'."
-_GUC_EPILOG = "Example:\n\n  * scaffold guc --name CreateOrder\n\n  * scaffold generate-use-case --name CreateOrder\n\n"
+_GUC_EPILOG = (
+    "Example:\n\n  * scaffold guc --name create_order\n\n  * scaffold generate-use-case --name create_order\n\n"
+)
 
 
 def _generate_use_case_impl(name: str, dry_run: bool) -> None:
     # --- Validate name ---
     try:
-        validate_name(name)
+        validate_module_name(name)
     except ScaffoldError as exc:
         console.print(f"[red]Error:[/red] {exc}")
         raise typer.Exit(code=1) from None
@@ -102,7 +104,7 @@ def register(app: typer.Typer) -> None:
     def generate_use_case(
         ctx: typer.Context,
         name: Annotated[
-            str | None, typer.Option("--name", help="Use case name (PascalCase).", rich_help_panel="Required")
+            str | None, typer.Option("--name", help="Use case name (snake_case).", rich_help_panel="Required")
         ] = None,
         dry_run: Annotated[
             bool,

scaffold_ca_python/core/file_writer.py

@@ -7,7 +7,7 @@ import tempfile
 from pathlib import Path
 from typing import TYPE_CHECKING
 
-from scaffold_ca_python.models.file_operation import CreateFile, DeleteFile, FileOperation, InsertAfter
+from scaffold_ca_python.models.file_operation import AppendToFile, CreateFile, DeleteFile, FileOperation, InsertAfter
 
 if TYPE_CHECKING:
     pass
@@ -60,7 +60,7 @@ class FileWriter:
         for op in operations:
             if isinstance(op, CreateFile):
                 result.append(op.file.path)
-            elif isinstance(op, (DeleteFile, InsertAfter)):
+            elif isinstance(op, (DeleteFile, InsertAfter, AppendToFile)):
                 result.append(op.path)
         return result
 
@@ -110,6 +110,11 @@ class FileWriter:
         for op in inserts:
             self._apply_insert_after(op)
 
+        # Process append_to_file mutations in declaration order
+        appends: list[AppendToFile] = [op for op in operations if isinstance(op, AppendToFile)]
+        for op in appends:
+            self._apply_append_to_file(op)
+
         return committed
 
     @staticmethod
@@ -126,3 +131,23 @@ class FileWriter:
                 op.path.write_text("".join(lines), encoding="utf-8")
                 return
         raise ValueError(f"insert_after anchor {op.anchor!r} not found in {op.path}")
+
+    @staticmethod
+    def _apply_append_to_file(op: AppendToFile) -> None:
+        """Append *op.content* to the end of *op.path*, or create the file.
+
+        When the file exists, trailing blank lines are normalized to a single newline
+        before appending. When it doesn't exist, it's created with *op.content* as
+        initial contents (leading blank lines stripped).
+        """
+        if op.path.exists():
+            # File exists - normalize trailing newlines and append
+            original = op.path.read_text(encoding="utf-8")
+            # Strip all trailing newlines, then ensure exactly one
+            normalized = original.rstrip("\n") + "\n"
+            op.path.write_text(normalized + op.content, encoding="utf-8")
+        else:
+            # File doesn't exist - create it with content (strip leading blank lines)
+            op.path.parent.mkdir(parents=True, exist_ok=True)
+            content = op.content.lstrip("\n")
+            op.path.write_text(content, encoding="utf-8")