scaffold-ca-python 0.1.1__py3-none-any.whl

scaffold_ca_python/core/file_writer.py

@@ -0,0 +1,128 @@
+"""file_writer: atomic file creation and deletion using tempdir staging (T023)."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from scaffold_ca_python.models.file_operation import CreateFile, DeleteFile, FileOperation, InsertAfter
+
+if TYPE_CHECKING:
+    pass
+
+
+class FileWriter:
+    """Execute a list of :class:`FileOperation` objects.
+
+    Real mode:  Uses a temporary directory for staging, then ``os.replace()``
+                (atomic on POSIX) to commit every file.  If staging fails for
+                *any* file the temp directory is discarded and no partial writes
+                reach the target tree.
+
+    Dry-run mode: Returns a list of target :class:`Path` objects that *would*
+                  be created or deleted, without touching disk.
+    """
+
+    def execute(
+        self,
+        operations: list[FileOperation],
+        *,
+        dry_run: bool = False,
+    ) -> list[Path]:
+        """Execute *operations*.
+
+        Parameters
+        ----------
+        operations:
+            Sequence of :class:`CreateFile` or :class:`DeleteFile` operations.
+        dry_run:
+            When ``True`` no disk writes occur; the method returns the list of
+            paths that *would* be affected.
+
+        Returns
+        -------
+        list[Path]
+            In dry-run mode: the paths that would be written/deleted.
+            In real mode: the paths that were successfully written.
+        """
+        if dry_run:
+            return self._dry_run(operations)
+        return self._commit(operations)
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    def _dry_run(self, operations: list[FileOperation]) -> list[Path]:
+        result: list[Path] = []
+        for op in operations:
+            if isinstance(op, CreateFile):
+                result.append(op.file.path)
+            elif isinstance(op, (DeleteFile, InsertAfter)):
+                result.append(op.path)
+        return result
+
+    def _commit(self, operations: list[FileOperation]) -> list[Path]:
+        """Stage all creates in a temp dir, then commit atomically."""
+        creates: list[CreateFile] = []
+        deletes: list[DeleteFile] = []
+        for op in operations:
+            if isinstance(op, CreateFile):
+                creates.append(op)
+            elif isinstance(op, DeleteFile):
+                deletes.append(op)
+
+        committed: list[Path] = []
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            # Stage all created files — any error here rolls back automatically
+            # because the TemporaryDirectory is discarded on __exit__.
+            staged: list[tuple[Path, Path]] = []
+            for i, op in enumerate(creates):
+                tmp_file = Path(tmpdir) / f"staged_{i}"
+                tmp_file.write_text(op.file.content, encoding="utf-8")
+                staged.append((tmp_file, op.file.path))
+
+            # Pre-flight: create ALL parent directories before any os.replace().
+            # If any mkdir fails, the exception propagates here; the TemporaryDirectory
+            # is cleaned up on __exit__ and no target files are committed yet.
+            for op, (_, target) in zip(creates, staged):
+                target.parent.mkdir(parents=True, exist_ok=True)
+                if target.exists() and not op.file.overwrite:
+                    raise FileExistsError(
+                        f"File already exists: {target}. Use overwrite=True on GeneratedFile to replace it."
+                    )
+
+            # All parents exist — commit via os.replace (atomic on POSIX)
+            for tmp_file, target in staged:
+                os.replace(tmp_file, target)
+                committed.append(target)
+
+        # Process deletes after all creates are committed
+        for op in deletes:
+            if op.path.exists():
+                op.path.unlink()
+
+        # Process insert_after mutations in declaration order
+        inserts: list[InsertAfter] = [op for op in operations if isinstance(op, InsertAfter)]
+        for op in inserts:
+            self._apply_insert_after(op)
+
+        return committed
+
+    @staticmethod
+    def _apply_insert_after(op: InsertAfter) -> None:
+        """Insert *op.content* on a new line after the first line containing *op.anchor*."""
+        if not op.path.exists():
+            raise FileNotFoundError(f"insert_after target not found: {op.path}")
+        original = op.path.read_text(encoding="utf-8")
+        lines = original.splitlines(keepends=True)
+        for i, line in enumerate(lines):
+            if op.anchor in line:
+                insertion = op.content if op.content.endswith("\n") else op.content + "\n"
+                lines.insert(i + 1, insertion)
+                op.path.write_text("".join(lines), encoding="utf-8")
+                return
+        raise ValueError(f"insert_after anchor {op.anchor!r} not found in {op.path}")

scaffold_ca_python/core/module_builder.py

@@ -0,0 +1,127 @@
+"""ModuleBuilder orchestration layer for factory-based module generation."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel
+
+from scaffold_ca_python.core.file_writer import FileWriter
+from scaffold_ca_python.core.pyproject_writer import (
+    dry_run_inject,
+    dry_run_scripts_update,
+    inject_dependencies,
+    update_project_scripts,
+)
+from scaffold_ca_python.core.template_renderer import TemplateRenderer
+from scaffold_ca_python.models.file_operation import CreateFile, DeleteFile, FileOperation, GeneratedFile, InsertAfter
+
+if TYPE_CHECKING:
+    from scaffold_ca_python.models.context import ModuleContext, ProjectContext
+
+
+class ModuleBuilder:
+    """Collect and persist module generation operations.
+
+    Factory implementations should only interact with this class, not with lower-level
+    infrastructure helpers such as FileWriter/TemplateRenderer/pyproject_writer.
+    """
+
+    def __init__(
+        self,
+        *,
+        project_root: Path,
+        project_ctx: ProjectContext,
+        module_ctx: ModuleContext | None = None,
+        dry_run: bool = False,
+        file_writer: FileWriter | None = None,
+        template_renderer: TemplateRenderer | None = None,
+    ) -> None:
+        self.project_root = project_root
+        self.project_ctx = project_ctx
+        self.module_ctx = module_ctx
+        self.dry_run = dry_run
+
+        self._file_writer = file_writer or FileWriter()
+        self._renderer = template_renderer or TemplateRenderer()
+
+        self._operations: list[FileOperation] = []
+        self._dependencies: list[str] = []
+        self._params: dict[str, object] = {}
+
+    def add_file(
+        self,
+        path: Path,
+        content: str,
+        *,
+        template_name: str,
+        is_test: bool = False,
+        overwrite: bool = False,
+    ) -> None:
+        """Queue a file creation operation."""
+        self._operations.append(
+            CreateFile(
+                file=GeneratedFile(
+                    path=path,
+                    content=content,
+                    template_name=template_name,
+                    is_test=is_test,
+                    overwrite=overwrite,
+                )
+            )
+        )
+
+    def delete_file(self, path: Path) -> None:
+        """Queue a file deletion operation."""
+        self._operations.append(DeleteFile(path=path))
+
+    def insert_after(self, path: Path, anchor: str, content: str) -> None:
+        """Queue an insert-after operation on an existing file.
+
+        *content* will be inserted on a new line immediately after the first
+        line in *path* that contains *anchor*.  In dry-run mode the path is
+        included in the preview list without modifying the file.
+        """
+        self._operations.append(InsertAfter(path=path, anchor=anchor, content=content))
+
+    def render(self, template_name: str, context: BaseModel | dict[str, Any]) -> str:
+        """Render a template through the shared renderer."""
+        return self._renderer.render(template_name, context)
+
+    def add_dependency(self, package: str) -> None:
+        """Queue a package dependency to inject into pyproject.toml."""
+        self._dependencies.append(package)
+
+    def add_param(self, key: str, value: object) -> None:
+        """Store an ad-hoc value used by factories/commands."""
+        self._params[key] = value
+
+    def get_param(self, key: str, default: object | None = None) -> object | None:
+        """Read a previously stored parameter value."""
+        return self._params.get(key, default)
+
+    def persist(self) -> list[Path]:
+        """Persist queued file and dependency operations.
+
+        In dry-run mode no writes occur; the method returns the paths that would be
+        affected by file operations.
+        """
+        paths = self._file_writer.execute(self._operations, dry_run=self.dry_run)
+
+        if self._dependencies:
+            if self.dry_run:
+                dry_run_inject(self.project_root, self._dependencies)
+            else:
+                inject_dependencies(self.project_root, self._dependencies)
+
+        # Optional script update hook used by entry-point factory implementations.
+        if bool(self._params.get("scripts_entry", False)):
+            pkg = self.project_ctx
+            entry_fn: str = str(self._params.get("scripts_entry_fn", "start_server"))
+            if self.dry_run:
+                dry_run_scripts_update(self.project_root, pkg, entry_fn)
+            else:
+                update_project_scripts(self.project_root, pkg, entry_fn)
+
+        return paths

scaffold_ca_python/core/name_utils.py

@@ -0,0 +1,59 @@
+"""name_utils: name validation, snake_case, and PascalCase conversion (T021)."""
+
+from __future__ import annotations
+
+import re
+
+NAME_RE = re.compile(r"^[a-z][a-z0-9]*([_-][a-z0-9]+)*$")
+
+# Matches transitions: lowercase→uppercase and letter→digit boundary runs
+_CAMEL_BOUNDARY_RE = re.compile(r"(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])")
+
+
+class ScaffoldError(Exception):
+    """Raised for user-facing errors (exit code 1)."""
+
+
+# ---------------------------------------------------------------------------
+# Public helpers
+# ---------------------------------------------------------------------------
+
+
+def validate_name(name: str) -> str:
+    """Validate *name* against the allowed identifier pattern.
+
+    Raises :class:`ScaffoldError` with a hint if the name is invalid.
+    Returns the original name unchanged when valid.
+    """
+    if not NAME_RE.match(name):
+        raise ScaffoldError(
+            f"Invalid name {name!r}. Use kebab-case (e.g., 'my-project') or snake_case (e.g., 'my_project')."
+        )
+    return name
+
+
+def to_snake_case(name: str) -> str:
+    """Convert *name* (PascalCase, camelCase, kebab-case, or already snake_case) to snake_case."""
+    # Normalise hyphens to underscores first (kebab-case support)
+    name = name.replace("-", "_")
+    # Insert underscores at camelCase / PascalCase boundaries first
+    s = _CAMEL_BOUNDARY_RE.sub("_", name)
+    return s.lower()
+
+
+def to_kebab_case(name: str) -> str:
+    """Convert *name* (PascalCase, snake_case, or already kebab-case) to kebab-case."""
+    # Normalise underscores to hyphens first (snake_case support)
+    name = name.replace("_", "-")
+    # Insert hyphens at camelCase / PascalCase boundaries
+    s = _CAMEL_BOUNDARY_RE.sub("-", name)
+    return s.lower()
+
+
+def to_pascal_case(name: str) -> str:
+    """Convert *name* (snake_case, kebab-case, PascalCase, or single word) to PascalCase."""
+    # Normalise hyphens to underscores first (kebab-case support)
+    name = name.replace("-", "_")
+    # Use [0].upper() + [1:] instead of capitalize() to preserve inner case
+    # e.g. "MyOrder" → "MyOrder" (not "Myorder")
+    return "".join(part[0].upper() + part[1:] for part in name.split("_") if part)

scaffold_ca_python/core/project_detector.py

@@ -0,0 +1,93 @@
+"""project_detector: locate the Clean Architecture project root (T022)."""
+
+from __future__ import annotations
+
+import tomllib
+from collections.abc import Iterator
+from pathlib import Path
+
+from scaffold_ca_python.core.name_utils import ScaffoldError
+
+_CA_MARKERS: frozenset[str] = frozenset({"domain", "infrastructure", "application"})
+_SCAFFOLD_SECTION = "scaffold-ca-python"
+
+
+def find_project_root(cwd: Path | None = None) -> Path:
+    """Walk upward from *cwd* to locate the project root.
+
+    Strategy (R-10):
+    1. Look for a ``pyproject.toml`` that contains ``[tool.scaffold-ca-python]``.
+    2. If not found, fall back to a directory whose children include the three
+       canonical CA layout directories (``domain/``, ``infrastructure/``,
+       ``application/``).
+
+    Raises
+    ------
+    ScaffoldError
+        When neither strategy finds a suitable root before reaching the
+        filesystem boundary.
+    """
+    current = (cwd or Path.cwd()).resolve()
+
+    # --- Strategy 1: pyproject.toml with [tool.scaffold-ca-python] ----------
+    candidate: Path | None = None
+    for directory in _iter_parents(current):
+        pyproject = directory / "pyproject.toml"
+        if pyproject.is_file():
+            try:
+                with pyproject.open("rb") as fh:
+                    data = tomllib.load(fh)
+                if _SCAFFOLD_SECTION in data.get("tool", {}):
+                    candidate = directory
+                    break
+            except Exception:  # malformed TOML — skip silently
+                pass
+
+    if candidate is not None:
+        return candidate
+
+    # --- Strategy 2: canonical CA directory layout --------------------------
+    for directory in _iter_parents(current):
+        children = {p.name for p in directory.iterdir() if p.is_dir()}
+        if _CA_MARKERS.issubset(children):
+            return directory
+
+    raise ScaffoldError(
+        "Could not find a scaffold-ca-python project root. "
+        "Ensure you are inside a project directory or run 'scaffold generate-project' first. "
+        "Hint: a valid project root has either [tool.scaffold-ca-python] in pyproject.toml "
+        "or the canonical CA directory layout (domain/, infrastructure/, application/)."
+    )
+
+
+def resolve_tests_root(project_root: Path) -> Path:
+    """Return the tests root for a project, probing for src-layout vs root-layout.
+
+    Resolution order:
+    1. ``project_root/src/tests/`` if it already exists (src-layout, post-feature).
+    2. ``project_root/tests/`` if it already exists (root-layout, pre-feature).
+    3. ``project_root/src/tests/`` as the default for new projects.
+    """
+    src_tests = project_root / "src" / "tests"
+    if src_tests.exists():
+        return src_tests
+    root_tests = project_root / "tests"
+    if root_tests.exists():
+        return root_tests
+    return src_tests
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _iter_parents(start: Path) -> Iterator[Path]:
+    """Yield *start* and each parent up to (and including) the filesystem root."""
+    current = start
+    while True:
+        yield current
+        parent = current.parent
+        if parent == current:
+            break
+        current = parent

scaffold_ca_python/core/pyproject_writer.py

@@ -0,0 +1,169 @@
+"""pyproject_writer: inject dependencies into [project.dependencies] in pyproject.toml."""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+import tomli_w
+
+from scaffold_ca_python.models.context import ProjectContext
+
+
+def _name_prefix(package: str) -> str:
+    """Extract the bare package name, stripping version specifier and extras.
+
+    Examples::
+
+        "fastapi>=0.100"        -> "fastapi"
+        "uvicorn[standard]>=0.20" -> "uvicorn"
+        "a2a-sdk>=0.1"          -> "a2a-sdk"
+    """
+    name = package.split(">=")[0].split("==")[0].split("<")[0].split("!=")[0]
+    name = name.split("[")[0]
+    return name.strip().lower()
+
+
+def _missing(existing: list[str], packages: list[str]) -> list[str]:
+    """Return packages not already present in *existing* (by name prefix)."""
+    existing_names = {_name_prefix(d) for d in existing}
+    return [p for p in packages if _name_prefix(p) not in existing_names]
+
+
+def inject_dependencies(project_root: Path, packages: list[str]) -> list[str]:
+    """Add *packages* to ``[project.dependencies]`` in ``pyproject.toml``.
+
+    Idempotent: a package whose bare name is already present is skipped.
+    Does not reformat unrelated sections.
+
+    Parameters
+    ----------
+    project_root:
+        Directory containing ``pyproject.toml``.
+    packages:
+        Packages to inject, e.g. ``["fastapi>=0.100", "uvicorn[standard]>=0.20"]``.
+
+    Returns
+    -------
+    list[str]
+        The packages that were actually added (empty when all were already present).
+
+    Raises
+    ------
+    FileNotFoundError
+        If ``pyproject.toml`` does not exist in *project_root*.
+    tomllib.TOMLDecodeError
+        If ``pyproject.toml`` is malformed.
+    """
+    pyproject = project_root / "pyproject.toml"
+    with pyproject.open("rb") as fh:
+        data = tomllib.load(fh)
+
+    deps: list[str] = data.setdefault("project", {}).setdefault("dependencies", [])
+    to_add = _missing(deps, packages)
+    if not to_add:
+        return []
+
+    deps.extend(to_add)
+
+    with pyproject.open("wb") as fh:
+        tomli_w.dump(data, fh)
+
+    return to_add
+
+
+def dry_run_inject(project_root: Path, packages: list[str]) -> list[str]:
+    """Return packages that *would* be added without writing to disk.
+
+    Parameters
+    ----------
+    project_root:
+        Directory containing ``pyproject.toml``.
+    packages:
+        Packages to check.
+
+    Returns
+    -------
+    list[str]
+        The packages that would be added if :func:`inject_dependencies` were called.
+
+    Raises
+    ------
+    FileNotFoundError
+        If ``pyproject.toml`` does not exist in *project_root*.
+    tomllib.TOMLDecodeError
+        If ``pyproject.toml`` is malformed.
+    """
+    pyproject = project_root / "pyproject.toml"
+    with pyproject.open("rb") as fh:
+        data = tomllib.load(fh)
+
+    deps: list[str] = data.get("project", {}).get("dependencies", [])
+    return _missing(deps, packages)
+
+
+def update_project_scripts(project_root: Path, pkg: ProjectContext, entry_fn: str = "start_server") -> bool:
+    """Rewrite ``[project.scripts]`` so the CLI entry calls *entry_fn*.
+
+    Sets ``<pkg> = "<pkg>.server:<entry_fn>"`` in ``pyproject.toml``.
+    Idempotent: returns ``False`` immediately when the entry already has the
+    correct value, leaving the file unchanged.
+
+    Parameters
+    ----------
+    project_root:
+        Directory containing ``pyproject.toml``.
+    pkg:
+        The Python package name (e.g. ``"my_app"``).
+    entry_fn:
+        The function name in ``server.py`` to use as the entry point
+        (default ``"start_server"``).  Pass ``"main"`` for MCP projects.
+
+    Returns
+    -------
+    bool
+        ``True`` if the file was written, ``False`` if it was already correct.
+    """
+    pyproject = project_root / "pyproject.toml"
+    with pyproject.open("rb") as fh:
+        data = tomllib.load(fh)
+
+    new_value = f"{pkg.python_package}.server:{entry_fn}"
+    scripts: dict[str, str] = data.setdefault("project", {}).setdefault("scripts", {})
+    if scripts.get(pkg.python_package_script) == new_value:
+        return False
+
+    scripts[pkg.python_package_script] = new_value
+    with pyproject.open("wb") as fh:
+        tomli_w.dump(data, fh)
+    return True
+
+
+def dry_run_scripts_update(project_root: Path, pkg: ProjectContext, entry_fn: str = "start_server") -> bool:
+    """Return whether ``update_project_scripts`` *would* write to disk.
+
+    Read-only: never modifies ``pyproject.toml``.
+
+    Parameters
+    ----------
+    project_root:
+        Directory containing ``pyproject.toml``.
+    pkg:
+        The Python package name (e.g. ``"my_app"``).
+    entry_fn:
+        The function name in ``server.py`` to use as the entry point
+        (default ``"start_server"``).  Pass ``"main"`` for MCP projects.
+
+    Returns
+    -------
+    bool
+        ``True`` if the current entry differs from ``<pkg>.server:<entry_fn>``,
+        ``False`` if no change would be needed.
+    """
+    pyproject = project_root / "pyproject.toml"
+    with pyproject.open("rb") as fh:
+        data = tomllib.load(fh)
+
+    new_value = f"{pkg.python_package}.server:{entry_fn}"
+    scripts: dict[str, str] = data.get("project", {}).get("scripts", {})
+    return scripts.get(pkg.python_package_script) != new_value