tses 0.1.0__py3-none-any.whl

tses/__init__.py

@@ -0,0 +1,3 @@
+"""TSES scaffold generator package."""
+
+__version__ = "0.1.0"

tses/__main__.py

@@ -0,0 +1,7 @@
+"""Module entry point for `python -m tses`."""
+
+from tses.cli import run
+
+
+if __name__ == "__main__":
+    run()

tses/cli.py

@@ -0,0 +1,79 @@
+"""Command-line interface for the TSES scaffold generator."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from tses import __version__
+from tses.commands.startproject import handle_startproject
+from tses.core.errors import TsesError
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the top-level CLI parser."""
+
+    parser = argparse.ArgumentParser(
+        prog="tses",
+        description="Generate curated Django or FastAPI project scaffolds.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"tses {__version__}",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    startproject_parser = subparsers.add_parser(
+        "startproject",
+        help="Generate a project scaffold into the target directory.",
+    )
+    startproject_parser.add_argument(
+        "target",
+        help="Target directory to generate into. Use '.' for the current directory.",
+    )
+    startproject_parser.add_argument(
+        "-f",
+        "--framework",
+        required=True,
+        choices=("django", "fastapi"),
+        help="Framework scaffold to generate.",
+    )
+    startproject_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite scaffold-managed files in a non-empty target directory.",
+    )
+    startproject_parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print planned actions without writing files.",
+    )
+    startproject_parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Print per-file actions during generation.",
+    )
+    startproject_parser.set_defaults(handler=handle_startproject)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the CLI and return an exit code."""
+
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        return args.handler(args)
+    except TsesError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+
+def run() -> None:
+    """Run the CLI as a console-script entry point."""
+
+    raise SystemExit(main())

tses/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command handlers for TSES."""

tses/commands/startproject.py

@@ -0,0 +1,75 @@
+"""Implementation of the `tses startproject` command."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from tses.core.filesystem import PlannedAction
+from tses.core.generator import GenerationResult, generate_scaffold
+
+
+def handle_startproject(args) -> int:
+    """Generate the requested scaffold and print user-facing output."""
+
+    result = generate_scaffold(
+        framework=args.framework,
+        target=Path(args.target),
+        force=args.force,
+        dry_run=args.dry_run,
+    )
+
+    if args.dry_run:
+        print(f"Dry run for {result.framework} scaffold")
+        print(f"Target: {result.target_dir}")
+        for action in result.actions:
+            _print_action(action, prefix="Would")
+        print(
+            f"Would create {result.created_count} files and overwrite "
+            f"{result.overwritten_count} files."
+        )
+        return 0
+
+    if args.verbose:
+        for action in result.actions:
+            _print_action(action)
+
+    print("Project generated successfully.")
+    print(f"Framework: {result.framework}")
+    print(f"Target: {result.target_dir}")
+    print(f"Project name: {result.metadata.project_name}")
+    print(f"Force mode: {'yes' if args.force else 'no'}")
+    print(f"Created files: {result.created_count}")
+    print(f"Overwritten files: {result.overwritten_count}")
+    print("Next steps:")
+    for step in _build_next_steps(result):
+        print(f"  {step}")
+    return 0
+
+
+def _print_action(action: PlannedAction, prefix: str | None = None) -> None:
+    """Print one planned or completed file action."""
+
+    verb = action.kind if prefix is None else f"{prefix} {action.kind}"
+    print(f"{verb:>16}  {action.relative_path.as_posix()}")
+
+
+def _build_next_steps(result: GenerationResult) -> list[str]:
+    """Return framework-specific follow-up steps for the user."""
+
+    steps: list[str] = []
+    if result.original_target != Path("."):
+        steps.append(f"cd {result.target_dir}")
+
+    env_example = result.target_dir / ".env.example"
+    env_file = result.target_dir / ".env"
+    if env_example.exists() and not env_file.exists():
+        steps.append("cp .env.example .env")
+
+    if result.framework == "django":
+        steps.append("docker compose up --build")
+        steps.append("python manage.py migrate")
+    else:
+        steps.append("docker compose up --build")
+        steps.append("alembic upgrade head")
+
+    return steps

tses/core/__init__.py

@@ -0,0 +1 @@
+"""Core generation utilities for TSES."""

tses/core/errors.py

@@ -0,0 +1,17 @@
+"""Custom exceptions raised by the TSES scaffold generator."""
+
+
+class TsesError(Exception):
+    """Base exception for user-facing generator errors."""
+
+
+class UnsupportedFrameworkError(TsesError):
+    """Raised when a framework choice is not supported."""
+
+
+class UnsafeTargetError(TsesError):
+    """Raised when generation would write into an unsafe target directory."""
+
+
+class GenerationError(TsesError):
+    """Raised when file generation cannot complete safely."""

tses/core/filesystem.py

@@ -0,0 +1,91 @@
+"""Filesystem planning helpers for scaffold generation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterator
+
+from importlib.abc import Traversable
+
+from tses.core.errors import GenerationError, UnsafeTargetError
+
+
+@dataclass(frozen=True)
+class PlannedAction:
+    """One file action required to realize a scaffold generation request."""
+
+    kind: str
+    relative_path: Path
+    source: Traversable
+    destination: Path
+
+
+def prepare_target_directory(target_dir: Path, *, force: bool, dry_run: bool) -> None:
+    """Validate the target directory and create it when appropriate."""
+
+    if target_dir.exists() and not target_dir.is_dir():
+        raise UnsafeTargetError(f"Target path is not a directory: {target_dir}")
+
+    if target_dir.exists():
+        if any(target_dir.iterdir()) and not force:
+            raise UnsafeTargetError(
+                "Target directory is not empty. Re-run with --force to overwrite "
+                "scaffold-managed files."
+            )
+        return
+
+    if not dry_run:
+        target_dir.mkdir(parents=True, exist_ok=True)
+
+
+def plan_actions(template_root: Traversable, target_dir: Path) -> list[PlannedAction]:
+    """Plan the file actions required to copy a scaffold into the target."""
+
+    actions: list[PlannedAction] = []
+    for source, relative_path in iter_template_files(template_root):
+        destination = target_dir / relative_path
+        _validate_parent_paths(target_dir=target_dir, destination=destination)
+
+        if destination.exists() and destination.is_dir():
+            raise GenerationError(
+                f"Cannot overwrite directory with file: {destination}"
+            )
+
+        action_kind = "overwrite" if destination.exists() else "create"
+        actions.append(
+            PlannedAction(
+                kind=action_kind,
+                relative_path=relative_path,
+                source=source,
+                destination=destination,
+            )
+        )
+
+    return actions
+
+
+def iter_template_files(
+    root: Traversable,
+    relative_path: Path = Path(),
+) -> Iterator[tuple[Traversable, Path]]:
+    """Yield every file under a template root with a stable relative path."""
+
+    for child in sorted(root.iterdir(), key=lambda entry: entry.name):
+        child_relative_path = relative_path / child.name
+        if child.is_dir():
+            yield from iter_template_files(child, child_relative_path)
+        elif child.is_file():
+            yield child, child_relative_path
+
+
+def _validate_parent_paths(*, target_dir: Path, destination: Path) -> None:
+    """Ensure no parent segment that should be a directory is already a file."""
+
+    current = destination.parent
+    while current != target_dir.parent:
+        if current.exists() and not current.is_dir():
+            raise GenerationError(f"Path segment is a file, not a directory: {current}")
+        if current == target_dir:
+            break
+        current = current.parent

tses/core/generator.py

@@ -0,0 +1,90 @@
+"""High-level scaffold generation orchestration."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from importlib import resources
+from importlib.abc import Traversable
+from pathlib import Path
+
+from tses.core.errors import GenerationError, UnsupportedFrameworkError
+from tses.core.filesystem import PlannedAction, plan_actions, prepare_target_directory
+from tses.core.metadata import GenerationMetadata, build_generation_metadata
+from tses.core.renderer import apply_action
+
+
+SUPPORTED_FRAMEWORKS = {"django", "fastapi"}
+
+
+@dataclass(frozen=True)
+class GenerationResult:
+    """Summary of one scaffold generation run."""
+
+    framework: str
+    original_target: Path
+    target_dir: Path
+    metadata: GenerationMetadata
+    actions: list[PlannedAction]
+
+    @property
+    def created_count(self) -> int:
+        """Return the number of created files."""
+
+        return sum(1 for action in self.actions if action.kind == "create")
+
+    @property
+    def overwritten_count(self) -> int:
+        """Return the number of overwritten files."""
+
+        return sum(1 for action in self.actions if action.kind == "overwrite")
+
+
+def generate_scaffold(
+    *,
+    framework: str,
+    target: Path,
+    force: bool = False,
+    dry_run: bool = False,
+) -> GenerationResult:
+    """Generate a vendored framework scaffold into the target directory."""
+
+    normalized_framework = framework.strip().lower()
+    template_root = get_template_root(normalized_framework)
+
+    target_dir = target.expanduser().resolve()
+    metadata = build_generation_metadata(
+        framework=normalized_framework,
+        target_dir=target_dir,
+    )
+
+    prepare_target_directory(target_dir, force=force, dry_run=dry_run)
+    actions = plan_actions(template_root, target_dir)
+
+    if not dry_run:
+        for action in actions:
+            apply_action(action, metadata)
+
+    return GenerationResult(
+        framework=normalized_framework,
+        original_target=target,
+        target_dir=target_dir,
+        metadata=metadata,
+        actions=actions,
+    )
+
+
+def get_template_root(framework: str) -> Traversable:
+    """Return the vendored template root for a supported framework."""
+
+    if framework not in SUPPORTED_FRAMEWORKS:
+        raise UnsupportedFrameworkError(
+            f"Unsupported framework '{framework}'. Expected one of: django, fastapi."
+        )
+
+    template_root = resources.files("tses.templates").joinpath(framework)
+    if not template_root.exists() or not template_root.is_dir():
+        raise GenerationError(
+            f"Vendored template for framework '{framework}' is missing. "
+            "Run tools/sync_scaffolds.py to refresh scaffold snapshots."
+        )
+    return template_root

tses/core/headers.py

@@ -0,0 +1,78 @@
+"""Generated-file header insertion helpers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from tses.core.metadata import GenerationMetadata
+
+
+HASH_COMMENT_FILENAMES = {
+    ".dockerignore",
+    ".env",
+    ".env.example",
+    ".gitignore",
+    "Dockerfile",
+    "Makefile",
+}
+HASH_COMMENT_SUFFIXES = {
+    ".conf",
+    ".cfg",
+    ".env",
+    ".ini",
+    ".py",
+    ".pyi",
+    ".requirements",
+    ".sh",
+    ".sql",
+    ".toml",
+    ".yaml",
+    ".yml",
+}
+BLOCK_COMMENT_SUFFIXES = {".css", ".js", ".jsx", ".ts", ".tsx"}
+HTML_COMMENT_SUFFIXES = {".html", ".htm", ".markdown", ".md", ".svg", ".xml"}
+
+
+def inject_generated_header(
+    content: str,
+    relative_path: Path,
+    metadata: GenerationMetadata,
+) -> str:
+    """Inject a generated-file header when the file type supports comments."""
+
+    comment = _build_comment(relative_path, metadata.header_text)
+    if comment is None:
+        return content
+
+    insertion = f"{comment}\n"
+    if content.startswith("#!"):
+        return _insert_after_first_line(content, insertion)
+    if content.startswith("<?xml"):
+        return _insert_after_first_line(content, insertion)
+    return f"{insertion}{content}"
+
+
+def _build_comment(relative_path: Path, text: str) -> str | None:
+    """Return the correctly formatted comment string for a file path."""
+
+    name = relative_path.name
+    suffixes = set(relative_path.suffixes)
+
+    if name in HASH_COMMENT_FILENAMES or suffixes & HASH_COMMENT_SUFFIXES:
+        return f"# {text}"
+    if suffixes & BLOCK_COMMENT_SUFFIXES:
+        return f"/* {text} */"
+    if suffixes & HTML_COMMENT_SUFFIXES:
+        return f"<!-- {text} -->"
+    if name.startswith("requirements"):
+        return f"# {text}"
+    return None
+
+
+def _insert_after_first_line(content: str, insertion: str) -> str:
+    """Insert text immediately after the first line of a file."""
+
+    newline_index = content.find("\n")
+    if newline_index == -1:
+        return f"{content}\n{insertion}"
+    return f"{content[: newline_index + 1]}{insertion}{content[newline_index + 1:]}"

tses/core/metadata.py

@@ -0,0 +1,55 @@
+"""Metadata helpers for scaffold generation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+import re
+
+from tses.core.errors import GenerationError
+
+
+@dataclass(frozen=True)
+class GenerationMetadata:
+    """Context values associated with one generation run."""
+
+    framework: str
+    project_name: str
+    project_slug: str
+    target_dir: Path
+    generated_at: str
+
+    @property
+    def header_text(self) -> str:
+        """Return the canonical generated-file header text."""
+
+        return f"Generated by Tses {self.generated_at}"
+
+
+def build_generation_metadata(*, framework: str, target_dir: Path) -> GenerationMetadata:
+    """Build normalized metadata for a generation request."""
+
+    resolved_target = target_dir.resolve()
+    project_name = resolved_target.name.strip()
+    if not project_name:
+        raise GenerationError("Could not derive a project name from the target path.")
+
+    project_slug = slugify(project_name)
+    generated_at = datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace(
+        "+00:00", "Z"
+    )
+    return GenerationMetadata(
+        framework=framework,
+        project_name=project_name,
+        project_slug=project_slug,
+        target_dir=resolved_target,
+        generated_at=generated_at,
+    )
+
+
+def slugify(value: str) -> str:
+    """Normalize a directory-derived value into a simple slug."""
+
+    normalized = re.sub(r"[^a-zA-Z0-9]+", "-", value.strip().lower()).strip("-")
+    return normalized or "project"

tses/core/renderer.py

@@ -0,0 +1,48 @@
+"""Rendering and file-write helpers for scaffold generation."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from tses.core.filesystem import PlannedAction
+from tses.core.headers import inject_generated_header
+from tses.core.metadata import GenerationMetadata
+
+
+def apply_action(action: PlannedAction, metadata: GenerationMetadata) -> None:
+    """Render one planned file action to disk."""
+
+    raw_bytes = action.source.read_bytes()
+    rendered_bytes = render_bytes(
+        raw_bytes=raw_bytes,
+        relative_path=action.relative_path,
+        metadata=metadata,
+    )
+
+    action.destination.parent.mkdir(parents=True, exist_ok=True)
+    action.destination.write_bytes(rendered_bytes)
+    _apply_permissions(action.destination, action.relative_path)
+
+
+def render_bytes(
+    *,
+    raw_bytes: bytes,
+    relative_path: Path,
+    metadata: GenerationMetadata,
+) -> bytes:
+    """Render bytes for a generated file, injecting headers where allowed."""
+
+    try:
+        text = raw_bytes.decode("utf-8")
+    except UnicodeDecodeError:
+        return raw_bytes
+
+    rendered_text = inject_generated_header(text, relative_path, metadata)
+    return rendered_text.encode("utf-8")
+
+
+def _apply_permissions(destination: Path, relative_path: Path) -> None:
+    """Apply deterministic executable permissions for generated scripts."""
+
+    if relative_path.suffix == ".sh":
+        destination.chmod(destination.stat().st_mode | 0o111)

tses/templates/__init__.py

@@ -0,0 +1 @@
+"""Vendored scaffold templates packaged with TSES."""

tses/templates/django/.docker/Dockerfile

@@ -0,0 +1,22 @@
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    DJANGO_SETTINGS_MODULE=config.settings
+
+WORKDIR /app
+
+COPY requirements.txt /app/requirements.txt
+
+RUN pip install --upgrade pip \
+    && pip install -r /app/requirements.txt
+
+COPY . /app
+
+RUN chmod +x /app/.docker/entrypoint.sh
+
+EXPOSE 8000
+
+ENTRYPOINT ["/bin/sh", "/app/.docker/entrypoint.sh"]
+
+CMD ["python", "manage.py", "runserver", "0.0.0.0:8000"]

tses/templates/django/.docker/entrypoint.sh

@@ -0,0 +1,15 @@
+#!/bin/sh
+set -e
+
+python manage.py check
+
+if [ "${DJANGO_RUN_MIGRATIONS:-1}" = "1" ]; then
+    python manage.py migrate --noinput
+fi
+
+# static collection opt-in because project may not define STATIC_ROOT yet.
+if [ "${DJANGO_COLLECTSTATIC:-0}" = "1" ]; then
+    python manage.py collectstatic --noinput
+fi
+
+exec "$@"

tses/templates/django/.dockerignore

@@ -0,0 +1,24 @@
+.git/
+.agents/
+.codex/
+
+.env
+.env.*
+!.env.example
+
+__pycache__/
+*.py[cod]
+*.sqlite3
+.python-version
+.venv/
+venv/
+env/
+
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+staticfiles/
+media/

tses/templates/django/.env.example

@@ -0,0 +1,32 @@
+# Django
+DJANGO_SETTINGS_MODULE=config.settings
+SECRET_KEY=change-me
+DEBUG=True
+ALLOWED_HOSTS=localhost,127.0.0.1
+
+# Database
+DB_HOST=postgres
+DB_PORT=5432
+DB_NAME=postgres
+DB_USER=postgres
+DB_PASSWORD=postgres
+
+# JWT
+SIGNING_KEY=change-me
+
+# Container startup
+DJANGO_RUN_MIGRATIONS=1
+DJANGO_COLLECTSTATIC=0
+
+# Celery
+CELERY_BROKER_URL=redis://redis:6379/0
+CELERY_RESULT_BACKEND=redis://redis:6379/0
+
+# Email
+EMAIL_HOST=localhost
+EMAIL_PORT=25
+EMAIL_USE_SSL=False
+EMAIL_USE_TLS=False
+EMAIL_HOST_USER=
+EMAIL_HOST_PASSWORD=
+DEFAULT_FROM_EMAIL=no-reply@example.com