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

scaffold_ca_python/commands/_entry_point_rules.py

@@ -0,0 +1,53 @@
+"""Validation rules for entry-point creation: flag compatibility and conflict detection."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import typer
+
+from scaffold_ca_python.commands._shared import console
+from scaffold_ca_python.factory.entry_points.base import EntryPointFactory, EntryPointFlag
+
+if TYPE_CHECKING:
+    pass
+
+
+def check_flags(
+    type_key: str,
+    factory: type[EntryPointFactory],
+    active_flags: list[EntryPointFlag],
+    registry: dict[str, type[EntryPointFactory]],
+) -> None:
+    """Exit with an error if any active flag is not supported by the factory."""
+    for flag in active_flags:
+        if flag not in factory.supported_flags:
+            types_supporting = [k for k, f in registry.items() if flag in f.supported_flags]
+            if len(types_supporting) == 1:
+                msg = f"{flag.label} {flag.verb} only valid with --type {types_supporting[0]}."
+            else:
+                msg = f"{flag.label} {flag.verb} not valid with --type {type_key}."
+            console.print(f"[red]Error:[/red] {msg}")
+            raise typer.Exit(code=1)
+
+
+def check_conflicts(
+    project_root: Path,
+    pkg: str,
+    type_key: str,
+    factory: type[EntryPointFactory],
+) -> None:
+    """Exit with an error if any conflicting entry-point directory already exists."""
+    pkg_ep = project_root / "src" / pkg / "infrastructure" / "entry_points"
+    for conflict in factory.conflicts:
+        conflict_dir = pkg_ep / conflict.subdir
+        if conflict_dir.exists():
+            rel = conflict_dir.relative_to(project_root)
+            console.print(
+                f"[red]Error:[/red] Incompatible entry point '[bold]{conflict.label}[/bold]' "
+                f"already exists at: {rel}\n"
+                "[dim]Hint:[/dim] A project may have only one entry-point type. "
+                f"Remove '{rel}' before adding {type_key}."
+            )
+            raise typer.Exit(code=1)

scaffold_ca_python/commands/_shared.py

@@ -0,0 +1,109 @@
+"""Shared utilities for CLI commands."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from pathlib import Path
+from typing import TYPE_CHECKING, Literal, NoReturn
+
+import typer
+from rich.console import Console
+from rich.markup import escape
+from rich.tree import Tree
+
+from scaffold_ca_python.core.name_utils import ScaffoldError
+from scaffold_ca_python.core.project_detector import find_project_root
+
+if TYPE_CHECKING:
+    from scaffold_ca_python.core.module_builder import ModuleBuilder
+    from scaffold_ca_python.factory import ModuleFactory
+
+console = Console()
+
+PROJECT_NOT_FOUND = "No scaffold-ca-python project found. Run 'scaffold ca' first."
+
+
+def fail(message: str, hint: str | None = None) -> NoReturn:
+    """Print an error (and optional hint) then exit with code 1."""
+    console.print(f"[red]Error:[/red] {message}")
+    if hint is not None:
+        console.print(f"[dim]Hint:[/dim] {hint}")
+    raise typer.Exit(code=1)
+
+
+def require_project_root(not_found_message: str | None = PROJECT_NOT_FOUND) -> Path:
+    """Return the project root, or exit 1 if not found.
+
+    Args:
+        not_found_message: Text to print on failure. Pass ``None`` to print the
+            ``ScaffoldError`` text from ``find_project_root`` instead.
+    """
+    try:
+        return find_project_root()
+    except ScaffoldError as exc:
+        if not_found_message is None:
+            console.print(f"[red]Error:[/red] {exc}")
+        else:
+            console.print(f"[red]Error:[/red] {not_found_message}")
+        raise typer.Exit(code=1) from None
+
+
+def validate_name_or_exit(name: str, validator: Callable[[str], object]) -> None:
+    """Run *validator* on *name*, calling ``fail()`` if it raises ``ScaffoldError``."""
+    try:
+        validator(name)
+    except ScaffoldError as exc:
+        fail(str(exc))
+
+
+def ensure_absent(
+    path: Path,
+    project_root: Path,
+    *,
+    kind: Literal["File", "Directory"],
+    hint: str,
+) -> None:
+    """Exit 1 if *path* already exists."""
+    if not path.exists():
+        return
+    rel = path.relative_to(project_root)
+    suffix = "/" if kind == "Directory" else ""
+    fail(f"{kind} '{rel}{suffix}' already exists.", hint=hint)
+
+
+def print_dry_run_tree(title: str, paths: Iterable[Path], base: Path) -> None:
+    """Render a Rich tree of *paths* (sorted, relative to *base*) with a dry-run label."""
+    tree = Tree(f"[bold]{title}[/bold] (dry run)")
+    for p in sorted(paths):
+        try:
+            tree.add(str(p.relative_to(base)))
+        except ValueError:
+            tree.add(str(p))
+    console.print(tree)
+
+
+def print_pending_dependencies(builder: ModuleBuilder) -> None:
+    """Print dry-run summaries for queued dependency injections."""
+    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]")
+
+
+def build_and_persist(factory: ModuleFactory, builder: ModuleBuilder) -> list[Path]:
+    """Build and persist module operations, returning the affected paths."""
+    factory.build(builder)
+    return builder.persist()
+
+
+def dry_run_option(help: str = "Preview without writing.") -> typer.models.OptionInfo:
+    """Return a ``--dry-run/--no-dry-run`` Typer option."""
+    return typer.models.OptionInfo(
+        default=False,
+        param_decls=("--dry-run/--no-dry-run",),
+        help=help,
+        rich_help_panel="Options",
+        show_default=True,
+    )

scaffold_ca_python/commands/add_mcp_tool.py

@@ -0,0 +1,200 @@
+"""add_mcp_tool: append a tool stub to an existing MCP entry point."""
+
+from __future__ import annotations
+
+import ast
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import typer
+from rich.syntax import Syntax
+
+from scaffold_ca_python.commands._shared import console, require_project_root
+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 load_project_context, resolve_tests_root
+from scaffold_ca_python.models.context import ProjectContext
+
+if TYPE_CHECKING:
+    from scaffold_ca_python.models.options import EntryPointOptions
+
+_TEST_TOOLS_STRUCTURE_ERROR = (
+    "[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]."
+)
+
+
+def _check_add_tool_flags(options: EntryPointOptions) -> None:
+    flags = options.creation_flags()
+    if flags:
+        console.print(f"[red]Error:[/red] --add-tool is incompatible with {flags[0]}.")
+        raise typer.Exit(code=1)
+    if options.type_ != "mcp":
+        console.print("[red]Error:[/red] --add-tool is only valid with --type mcp.")
+        raise typer.Exit(code=1)
+    if options.name is None:
+        console.print("[red]Error:[/red] --name is required with --add-tool.")
+        raise typer.Exit(code=1)
+
+
+def _build_spec(options: EntryPointOptions) -> mcp_tool_spec.ToolSpec:
+    if options.name is None:  # guard; _check_add_tool_flags exits before this if name is None
+        raise typer.Exit(code=1)
+    params = list(options.params) if options.params else None
+    try:
+        return mcp_tool_spec.build_tool_spec(options.name, params, options.returns, options.description)
+    except (ValueError, ScaffoldError) as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(code=1) from None
+
+
+def _resolve_paths(project_root: Path, ctx: ProjectContext) -> tuple[Path, Path]:
+    tools_py = project_root / "src" / ctx.python_package / "infrastructure" / "entry_points" / "mcp_server" / "tools.py"
+    test_tools_py = (
+        resolve_tests_root(project_root) / "infrastructure" / "entry_points" / "mcp_server" / "test_tools.py"
+    )
+    return tools_py, test_tools_py
+
+
+def _read_sources(paths: tuple[Path, Path]) -> tuple[str, str]:
+    tools_py, test_tools_py = paths
+    if not tools_py.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)
+    try:
+        tools_src = tools_py.read_text(encoding="utf-8")
+    except OSError as e:
+        console.print(f"[red]Error:[/red] Cannot read {tools_py}: {e}")
+        raise typer.Exit(code=1) from None
+    try:
+        test_tools_src = test_tools_py.read_text(encoding="utf-8")
+    except OSError:
+        console.print(_TEST_TOOLS_STRUCTURE_ERROR)
+        raise typer.Exit(code=1) from None
+    return tools_src, test_tools_src
+
+
+def _check_structure(sources: tuple[str, str], spec: mcp_tool_spec.ToolSpec) -> None:
+    tools_src, test_tools_src = sources
+    if not mcp_tool_spec.has_bind_tools_function(tools_src):
+        console.print(
+            "[red]Error:[/red] infrastructure/entry_points/mcp_server/tools.py was generated by an older "
+            "scaffold\nversion 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)
+    if not mcp_tool_spec.has_test_registration_structure(test_tools_src):
+        console.print(_TEST_TOOLS_STRUCTURE_ERROR)
+        raise typer.Exit(code=1)
+    existing = mcp_tool_spec.find_existing_tool_names(tools_src)
+    if spec.name in existing:
+        if spec.name == "bind_tools":
+            console.print(
+                f"[red]Error:[/red] '{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 '{spec.name}' already exists in tools.py.")
+        raise typer.Exit(code=1)
+
+
+def _check_writable(paths: tuple[Path, Path], project_root: Path) -> None:
+    for path in paths:
+        if not os.access(path, os.W_OK):
+            console.print(
+                f"[red]Error:[/red] Cannot write to {path.relative_to(project_root)}.\n"
+                "[dim]Hint:[/dim] Check the file's permissions and re-run the command."
+            )
+            raise typer.Exit(code=1)
+
+
+def _persist_with_restore(
+    builder: ModuleBuilder,
+    originals: tuple[Path, str, Path, str],
+) -> list[Path]:
+    tools_py, tools_src, test_tools_py, test_tools_src = originals
+    try:
+        return builder.persist()
+    except OSError as e:
+        try:
+            tools_py.write_text(tools_src, encoding="utf-8")
+            test_tools_py.write_text(test_tools_src, encoding="utf-8")
+        except OSError:
+            pass
+        fname = Path(e.filename).name if e.filename else "tools.py"
+        console.print(
+            f"[red]Error:[/red] Failed to write {fname} ({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
+
+
+def _report_add_tool(
+    modified_paths: list[Path],
+    tool_stub: str,
+    test_stub: str,
+    spec: mcp_tool_spec.ToolSpec,
+    project_root: Path,
+    dry_run: bool,
+) -> 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, "python", theme="monokai", line_numbers=False))
+        console.print("\n[yellow]Test stub preview:[/yellow]")
+        console.print(Syntax(test_stub, "python", theme="monokai", line_numbers=False))
+    else:
+        console.print(f"[green]✓[/green] Added tool '{spec.name}' to MCP entry point.")
+
+
+def add_mcp_tool(options: EntryPointOptions) -> None:
+    """Add a tool stub to an existing MCP entry point."""
+    _check_add_tool_flags(options)
+    spec = _build_spec(options)
+    project_root = require_project_root(not_found_message=None)
+    project_ctx = load_project_context(project_root)
+    paths = _resolve_paths(project_root, project_ctx)
+    sources = _read_sources(paths)
+    _check_structure(sources, spec)
+
+    tools_py, test_tools_py = paths
+    tools_src, test_tools_src = sources
+
+    builder = ModuleBuilder(project_root=project_root, project_ctx=project_ctx, dry_run=options.dry_run)
+    tool_stub = builder.render(
+        "entry_point/mcp/tool_stub.py.jinja2",
+        {
+            "name": spec.name,
+            "params": [{"name": p.name, "type": p.type} for p in spec.params],
+            "returns": spec.returns,
+            "docstring": spec.docstring,
+        },
+    )
+    test_stub = builder.render("entry_point/mcp/test_tool_stub.py.jinja2", {"name": spec.name})
+
+    try:
+        ast.parse(tools_src + tool_stub)
+    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) from None
+
+    _check_writable(paths, project_root)
+    builder.append_to_file(tools_py, tool_stub)
+    builder.append_to_file(test_tools_py, test_stub)
+    modified = _persist_with_restore(builder, (tools_py, tools_src, test_tools_py, test_tools_src))
+    _report_add_tool(modified, tool_stub, test_stub, spec, project_root, options.dry_run)

scaffold_ca_python/commands/delete_module.py

@@ -1,132 +1,58 @@
-"""delete_module: safely remove a previously generated module and its test mirror (T039)."""
+"""delete_module: safely remove a previously generated module and its test mirror."""
 
 from __future__ import annotations
 
-import tomllib
 from pathlib import Path
 from typing import Annotated
 
 import typer
-from rich.console import Console
 
+from scaffold_ca_python.commands._shared import console, require_project_root, validate_name_or_exit
 from scaffold_ca_python.core.module_builder import ModuleBuilder
-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.core.module_locator import find_module_targets
+from scaffold_ca_python.core.name_utils import to_snake_case, validate_module_name
+from scaffold_ca_python.core.project_detector import load_project_context
 from scaffold_ca_python.factory.simple.delete_module_factory import DeleteModuleFactory
-from scaffold_ca_python.models.context import ModuleContext, ProjectContext
+from scaffold_ca_python.models.context import ModuleContext
 from scaffold_ca_python.models.layer import Layer
 
-console = Console()
-
-_REGISTRY: dict[str, type[ModuleFactory]] = {
-    "delete": DeleteModuleFactory,
-}
-
 _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 my_adapter\n\n"
 
 
-# ---------------------------------------------------------------------------
-# Module discovery helpers
-# ---------------------------------------------------------------------------
-
-
-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:
-      1. domain/model/<snake>.py
-      2. domain/usecase/<snake>.py
-      3. infrastructure/driven_adapters/<snake>/
-      4. infrastructure/entry_points/<snake>/
-      5. infrastructure/helpers/<snake>/
-    """
-    src_root = project_root / "src" / pkg
-    tests_root = resolve_tests_root(project_root)
-
-    candidates: list[tuple[Path, Path | None]] = []
-
-    # Single-file layers (domain/model, domain/usecase)
-    for src_rel, test_rel in [
-        (src_root / "domain" / "model" / f"{snake}.py", tests_root / "domain" / "model" / f"test_{snake}.py"),
-        (src_root / "domain" / "usecase" / f"{snake}.py", tests_root / "domain" / "usecase" / f"test_{snake}.py"),
-    ]:
-        if src_rel.exists():
-            candidates.append((src_rel, test_rel if test_rel.exists() else None))
-
-    # Directory-based layers (infrastructure sub-dirs)
-    for src_rel, test_rel in [
-        (
-            src_root / "infrastructure" / "driven_adapters" / snake,
-            tests_root / "infrastructure" / "driven_adapters" / snake,
-        ),
-        (
-            src_root / "infrastructure" / "entry_points" / snake,
-            tests_root / "infrastructure" / "entry_points" / snake,
-        ),
-        (
-            src_root / "infrastructure" / "helpers" / snake,
-            tests_root / "infrastructure" / "helpers" / snake,
-        ),
-    ]:
-        if src_rel.exists():
-            candidates.append((src_rel, test_rel if test_rel.exists() else None))
-
-    return candidates
-
-
-# ---------------------------------------------------------------------------
-# Implementation
-# ---------------------------------------------------------------------------
-
-
-def _delete_module_impl(name: str, confirm: bool, dry_run: bool) -> None:
-    # Validate name
+def _display(path: Path, root: Path) -> Path:
     try:
-        validate_module_name(name)
-    except ScaffoldError as exc:
-        console.print(f"[red]Error:[/red] {exc}")
-        raise typer.Exit(code=1) from None
+        return path.relative_to(root)
+    except ValueError:
+        return path
 
-    # Locate project root
-    try:
-        project_root = find_project_root()
-    except ScaffoldError:
-        console.print("[red]Error:[/red] No scaffold-ca-python project found. Run 'scaffold ca' first.")
-        raise typer.Exit(code=1) from None
 
-    project_ctx = _load_project_context(project_root)
+def _delete_module_impl(name: str, confirm: bool, dry_run: bool) -> None:
+    validate_name_or_exit(name, validate_module_name)
+    project_root = require_project_root()
+    project_ctx = load_project_context(project_root)
 
     # Create a placeholder ModuleContext for the factory (layer doesn't matter for delete)
     module_ctx = ModuleContext(name=name, layer=Layer.HELPERS, project=project_ctx)
 
     # Find targets
     snake = to_snake_case(name)
-    targets = _find_module_targets(project_ctx.python_package, project_root, snake)
+    targets = find_module_targets(project_root, project_ctx.python_package, snake)
 
     if not targets:
         console.print(
             f"[red]Error:[/red] No module named '{snake}' found in project.\n"
             "[dim]Hint:[/dim] Check spelling with 'scaffold vs' to list modules."
         )
-        raise typer.Exit(code=1) from None
+        raise typer.Exit(code=1)
 
     # dry_run OR no --confirm → preview mode only
     if dry_run or not confirm:
         console.print("The following files would be deleted:\n")
         for src_path, test_path in targets:
-            try:
-                display = src_path.relative_to(project_root)
-            except ValueError:
-                display = src_path
-            console.print(f"  {display}")
+            console.print(f"  {_display(src_path, project_root)}")
             if test_path:
-                try:
-                    display = test_path.relative_to(project_root)
-                except ValueError:
-                    display = test_path
-                console.print(f"  {display}")
+                console.print(f"  {_display(test_path, project_root)}")
         console.print("\nRun with --confirm to proceed.")
         return
 
@@ -138,9 +64,7 @@ def _delete_module_impl(name: str, confirm: bool, dry_run: bool) -> None:
         dry_run=False,
     )
 
-    factory_class = _REGISTRY["delete"]
-    factory = factory_class()
-    factory.build(builder)
+    DeleteModuleFactory().build(builder)
 
     # Persist deletion
     builder.persist()
@@ -184,18 +108,3 @@ def register(app: typer.Typer) -> None:
             typer.echo(ctx.get_help())
             raise typer.Exit(0)
         _delete_module_impl(name, confirm, dry_run)
-
-
-# ---------------------------------------------------------------------------
-# Helpers
-# ---------------------------------------------------------------------------
-
-
-def _load_project_context(root: Path) -> ProjectContext:
-    pyproject = root / "pyproject.toml"
-    with pyproject.open("rb") as fh:
-        data = tomllib.load(fh)
-    section = data.get("tool", {}).get("scaffold-ca-python", {})
-    return ProjectContext(
-        name=section.get("name", root.name),
-    )