paper-draft 0.1.0__py3-none-any.whl

paper/draft/cli/commands/__init__.py

@@ -0,0 +1,2 @@
+from paper.draft.cli.commands import init, new, validate, run
+__all__ = ["init", "new", "validate", "run"]

paper/draft/cli/commands/init.py

@@ -0,0 +1,204 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# PaperDraft CLI — init command
+# File: paper/draft/cli/commands/init.py
+# ─────────────────────────────────────────────────────────────────────────────
+# Usage:
+#   draft init my-api
+#   draft init my-api --port 8000
+#
+# Creates:
+#   my-api/
+#     main.py, dependencies.py, config.py, requirements.txt,
+#     .gitignore, .env.dev, services/
+#
+# Then runs:
+#   python -m venv .venv
+#   pip install -r requirements.txt
+# ─────────────────────────────────────────────────────────────────────────────
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from jinja2 import Environment, FileSystemLoader
+from rich.console import Console
+from rich.panel import Panel
+from rich.tree import Tree as RichTree
+
+app:     typer.Typer = typer.Typer(help="Initialise a new PaperDraft project.", no_args_is_help=True)
+console: Console     = Console()
+err:     Console     = Console(stderr=True)
+
+_TEMPLATES_DIR: Path = Path(__file__).parent.parent / "templates"
+
+
+def _render(template_name: str, context: dict) -> str:
+    env = Environment(
+        loader        = FileSystemLoader(str(_TEMPLATES_DIR)),
+        trim_blocks   = True,
+        lstrip_blocks = True,
+    )
+    return env.get_template(template_name).render(**context)
+
+
+@app.callback(invoke_without_command=True)
+def init_cmd(
+    name: Annotated[
+        str,
+        typer.Argument(help="Application name — also used as the root folder name.")
+    ],
+    port: Annotated[
+        int,
+        typer.Option("--port", "-p", help="Port this service runs on.")
+    ],
+    description: Annotated[
+        str,
+        typer.Option("--description", "-d", help="Application description.")
+    ] = "PaperDraft REST API",
+    version: Annotated[
+        str,
+        typer.Option("--version", help="Application version.")
+    ] = "1.0.0",
+    skip_install: Annotated[
+        bool,
+        typer.Option("--skip-install", help="Skip venv creation and package installation.")
+    ] = False,
+) -> None:
+    """
+    Initialise a new PaperDraft project in a new <name> directory.
+
+    Creates the project folder, scaffolds all root files and services/,
+    sets up a Python virtual environment, and installs all dependencies.
+    """
+    package_name: str = name.lower().replace(" ", "-")
+    cwd: Path         = Path.cwd() / package_name
+
+    # ── Guard — don't overwrite an existing project ───────────────────────────
+    if cwd.exists():
+        err.print(
+            f"[bold red]✗[/bold red]  [yellow]{package_name}/[/yellow] already exists."
+        )
+        raise typer.Exit(code=2)
+
+    cwd.mkdir(parents=True)
+    context: dict = {
+        "app_name":        name,
+        "app_description": description,
+        "app_version":     version,
+        "package_name":    package_name,
+        "port":            port,
+    }
+
+    console.print(f"\n[bold]Initialising[/bold] [green]{name}[/green]...\n")
+    created: list[str] = []
+
+    # ── Root files ────────────────────────────────────────────────────────────
+    def write(filename: str, template: str) -> None:
+        path: Path = cwd / filename
+        path.write_text(_render(template, context), encoding="utf-8")
+        created.append(filename)
+
+    write("main.py",          "main.py.j2")
+    write("dependencies.py",  "dependencies.py.j2")
+    write("config.py",        "config.py.j2")
+    write(".gitignore",       "gitignore.j2")
+
+    # requirements.txt — straight copy, no templating
+    req_src: Path = Path(__file__).parent.parent / "templates" / "requirements.txt"
+    if req_src.exists():
+        (cwd / "requirements.txt").write_text(req_src.read_text(), encoding="utf-8")
+    else:
+        (cwd / "requirements.txt").write_text("# Add your dependencies here\n", encoding="utf-8")
+    created.append("requirements.txt")
+
+    # .env stub
+    env_content: str = (
+        "ENV=dev\n"
+        "APP_URL=http://localhost:{port}\n"
+        "APP_PORT={port}\n\n"
+        "POSTGRES_CONN_STRING=\n"
+        "POSTGRES_ADMIN_CONN_STRING=\n\n"
+        "ENCRYPTION_PUBLIC_KEY=\n"
+        "ENCRYPTION_PRIVATE_KEY=\n\n"
+        "EMAIL_SMTP_HOST=\n"
+        "EMAIL_SMTP_PORT=587\n"
+        "EMAIL_SMTP_USERNAME=\n"
+        "EMAIL_SMTP_PASSWORD=\n"
+        "EMAIL_SENDER_NAME=\n"
+        "EMAIL_SENDER_ADDRESS=\n"
+    ).format(port=port)
+    (cwd / ".env.dev").write_text(env_content, encoding="utf-8")
+    created.append(".env.dev")
+
+    # ── Directories ───────────────────────────────────────────────────────────
+    (cwd / "services").mkdir(exist_ok=True)
+    created.append("services/")
+
+    # ── Print scaffold tree ───────────────────────────────────────────────────
+    tree = RichTree(f"[bold]{package_name}/[/bold]")
+    for item in sorted(created):
+        if item.endswith("/"):
+            tree.add(f"[bold blue]{item}[/bold blue]")
+        elif item.startswith("."):
+            tree.add(f"[dim]{item}[/dim]")
+        elif item == "main.py":
+            tree.add(f"[bold green]{item}[/bold green]")
+        else:
+            tree.add(item)
+    console.print(tree)
+    console.print()
+
+    if skip_install:
+        console.print("[dim]Skipping installation (--skip-install)[/dim]")
+        _print_next_steps(name)
+        return
+
+    # ── Python venv ───────────────────────────────────────────────────────────
+    _run_step(
+        label   = "Creating Python virtual environment",
+        command = [sys.executable, "-m", "venv", ".venv"],
+        cwd     = cwd,
+    )
+
+    # ── pip install ───────────────────────────────────────────────────────────
+    venv_pip: str = str(cwd / ".venv" / ("Scripts" if sys.platform == "win32" else "bin") / "pip")
+    _run_step(
+        label   = "Installing Python packages",
+        command = [venv_pip, "install", "-r", "requirements.txt", "--quiet"],
+        cwd     = cwd,
+    )
+
+    _print_next_steps(name)
+
+
+def _run_step(label: str, command: list[str], cwd: Path) -> None:
+    console.print(f"  [dim]{label}...[/dim]", end="")
+    try:
+        result = subprocess.run(
+            command, cwd=cwd,
+            capture_output=True, text=True
+        )
+        if result.returncode == 0:
+            console.print(" [bold green]✓[/bold green]")
+        else:
+            console.print(" [bold red]✗[/bold red]")
+            err.print(f"[dim]{result.stderr.strip()}[/dim]")
+    except FileNotFoundError as e:
+        console.print(f" [bold yellow]skipped[/bold yellow] [dim]({e.filename} not found)[/dim]")
+
+
+def _print_next_steps(name: str) -> None:
+    package_name: str = name.lower().replace(" ", "-")
+    console.print(Panel(
+        f"[bold]Next steps:[/bold]\n\n"
+        f"  1. [bold]cd {package_name}[/bold]\n"
+        f"  2. Fill in [yellow].env.dev[/yellow] with your DB and encryption keys\n"
+        f"  3. Run [bold]draft new service [name][/bold] to add a service\n"
+        f"  4. Run [bold]draft run[/bold] to start the app",
+        title        = f"[bold green]✓  {name} initialised[/bold green]",
+        border_style = "green",
+    ))

paper/draft/cli/commands/new.py

@@ -0,0 +1,204 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# PaperDraft CLI — new command
+# File: paper/draft/cli/commands/new.py
+# ─────────────────────────────────────────────────────────────────────────────
+# Usage:
+#   draft new service location --prefix location
+#
+# Creates:
+#   services/location/
+#     __init__.py
+#     router.py
+#     controller.py
+#     service.py
+#
+# Then patches main.py:
+#   from services.location.router import router as location_router
+#   app.include_router(location_router, prefix="/location", tags=["Location"])
+# ─────────────────────────────────────────────────────────────────────────────
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from jinja2 import Environment, FileSystemLoader
+from rich.console import Console
+from rich.panel import Panel
+from rich.tree import Tree as RichTree
+
+app:     typer.Typer = typer.Typer(help="Scaffold a new resource.", no_args_is_help=True)
+console: Console     = Console()
+err:     Console     = Console(stderr=True)
+
+_TEMPLATES_DIR: Path = Path(__file__).parent.parent / "templates"
+
+# ── Markers written into main.py so we can patch it reliably ─────────────────
+_ROUTERS_MARKER: str = "# ── Routers"
+
+
+def _render(template_name: str, context: dict) -> str:
+    env = Environment(
+        loader        = FileSystemLoader(str(_TEMPLATES_DIR)),
+        trim_blocks   = True,
+        lstrip_blocks = True,
+    )
+    return env.get_template(template_name).render(**context)
+
+
+def _to_class_name(name: str) -> str:
+    return "".join(p.capitalize() for p in name.replace("-", "_").split("_"))
+
+
+@app.command("service")
+def new_service(
+    name: Annotated[
+        str,
+        typer.Argument(help="Service name — e.g. location, user, product.")
+    ],
+    prefix: Annotated[
+        str,
+        typer.Option("--prefix", "-p", help="URL prefix for this service — e.g. location, refs/cycle.")
+    ] = "",
+    force: Annotated[
+        bool,
+        typer.Option("--force", "-f", help="Overwrite existing service files.")
+    ] = False,
+) -> None:
+    """
+    Scaffold a new service and register it in main.py.
+
+    Creates router.py, controller.py, service.py, and __init__.py
+    inside services/<name>/. Then patches main.py with the router import
+    and app.include_router() call.
+    """
+    cwd: Path = Path.cwd()
+
+    # ── Validate project root ─────────────────────────────────────────────────
+    main_py: Path = cwd / "main.py"
+    if not main_py.exists():
+        err.print(
+            "[bold red]✗[/bold red]  No [yellow]main.py[/yellow] found in current directory. "
+            "Run [bold]draft init[/bold] first."
+        )
+        raise typer.Exit(code=2)
+
+    name        = name.strip().lower().replace(" ", "-")
+    prefix      = prefix.strip().strip("/")
+    class_name  = _to_class_name(name)
+    route_prefix = f"/{prefix}" if prefix else f"/{name}"
+
+    service_dir: Path = cwd / "services" / name
+
+    if service_dir.exists() and not force:
+        err.print(
+            f"[bold red]✗[/bold red]  [yellow]services/{name}/[/yellow] already exists. "
+            f"Use [bold]--force[/bold] to overwrite."
+        )
+        raise typer.Exit(code=2)
+
+    # ── Render and write service files ────────────────────────────────────────
+    context: dict = {
+        "service_name": name,
+        "class_name":   class_name,
+        "prefix":       route_prefix,
+    }
+
+    service_dir.mkdir(parents=True, exist_ok=True)
+    (service_dir / "__init__.py").write_text("", encoding="utf-8")
+    (service_dir / "router.py").write_text(
+        _render("router.py.j2", context), encoding="utf-8"
+    )
+    (service_dir / "controller.py").write_text(
+        _render("controller.py.j2", context), encoding="utf-8"
+    )
+    (service_dir / "service.py").write_text(
+        _render("service.py.j2", context), encoding="utf-8"
+    )
+
+    # ── Patch main.py ─────────────────────────────────────────────────────────
+    _patch_main(main_py, name, class_name, route_prefix)
+
+    # ── Print result ──────────────────────────────────────────────────────────
+    tree = RichTree(f"[bold]services/{name}/[/bold]")
+    tree.add("[dim]__init__.py[/dim]")
+    tree.add("[green]router.py[/green]")
+    tree.add("[green]controller.py[/green]")
+    tree.add("[green]service.py[/green]")
+
+    console.print()
+    console.print(tree)
+    console.print()
+    console.print(Panel(
+        f"[bold]Service:[/bold]  {name}\n"
+        f"[bold]Prefix:[/bold]   {route_prefix}\n"
+        f"[bold]Router:[/bold]   registered in main.py\n\n"
+        f"Next: define your routes in "
+        f"[yellow]services/{name}/router.py[/yellow]",
+        title        = f"[bold green]✓  {class_name} service created[/bold green]",
+        border_style = "green",
+    ))
+
+
+def _patch_main(main_py: Path, name: str, class_name: str, prefix: str) -> None:
+    """
+    Insert the import and include_router() call into main.py.
+    Uses the # ── Routers marker as the insertion point.
+    Idempotent — won't add duplicates.
+    """
+    content: str = main_py.read_text(encoding="utf-8")
+
+    import_line: str = (
+        f"from services.{name}.router import router as {name}_router"
+    )
+    router_line: str = (
+        f'app.include_router({name}_router, prefix="{prefix}", tags=["{class_name}"])'
+    )
+
+    # Skip if already registered
+    if import_line in content:
+        console.print(
+            f"  [dim]main.py — {name} already registered, skipping[/dim]"
+        )
+        return
+
+    # Insert import after the last existing service import
+    # Pattern: find the last "from services." import line and insert after it,
+    # or insert right after the # ── Routers marker if no service imports yet
+    lines: list[str] = content.splitlines(keepends=True)
+    insert_import_at: int = -1
+    insert_router_at: int = -1
+
+    for i, line in enumerate(lines):
+        if line.startswith("from services.") and "router" in line:
+            insert_import_at = i  # keep updating → lands after last one
+
+    if insert_import_at >= 0:
+        # Insert import after the last service import line
+        lines.insert(insert_import_at + 1, import_line + "\n")
+        # After insertion, router block shifted by 1
+        insert_router_at = insert_import_at + 2
+    else:
+        # No service imports yet — insert after the Routers marker comment
+        for i, line in enumerate(lines):
+            if line.startswith(_ROUTERS_MARKER):
+                lines.insert(i + 1, import_line + "\n")
+                insert_router_at = i + 2
+                break
+
+    # Now find the right place for the include_router call
+    # Insert after the last app.include_router(...) line
+    last_router_line: int = -1
+    for i, line in enumerate(lines):
+        if "app.include_router(" in line:
+            last_router_line = i
+
+    if last_router_line >= 0:
+        lines.insert(last_router_line + 1, router_line + "\n")
+    elif insert_router_at >= 0:
+        lines.insert(insert_router_at, "\n" + router_line + "\n")
+
+    main_py.write_text("".join(lines), encoding="utf-8")
+    console.print(f"  [dim]main.py — {name} router registered at {prefix}[/dim]")

paper/draft/cli/commands/run.py

@@ -0,0 +1,101 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# PaperDraft CLI — run command
+# File: paper/draft/cli/commands/run.py
+# ─────────────────────────────────────────────────────────────────────────────
+# Usage:
+#   draft run              ← uvicorn with auto-reload (dev)
+#   draft run --prod       ← uvicorn with 4 workers, no reload (production)
+# ─────────────────────────────────────────────────────────────────────────────
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.rule import Rule
+
+app:     typer.Typer = typer.Typer(help="Run the application.", no_args_is_help=False)
+console: Console     = Console()
+err:     Console     = Console(stderr=True)
+
+
+@app.callback(invoke_without_command=True)
+def run_cmd(
+    prod: Annotated[
+        bool,
+        typer.Option("--prod", help="Production mode — 4 workers, no reload.")
+    ] = False,
+    host: Annotated[
+        str,
+        typer.Option("--host", help="Bind host.")
+    ] = "0.0.0.0",
+) -> None:
+    """
+    Run the PaperDraft application with uvicorn.
+
+    Port is read from APP_PORT in main.py.
+    Default: auto-reload enabled (dev).
+    --prod:  4 workers, no reload (production).
+    """
+    cwd: Path = Path.cwd()
+
+    main_py: Path = cwd / "main.py"
+    if not main_py.exists():
+        err.print(
+            "[bold red]✗[/bold red]  No [yellow]main.py[/yellow] found. "
+            "Run [bold]draft init[/bold] first."
+        )
+        raise typer.Exit(code=2)
+
+    port: int = _read_port(cwd)
+
+    mode:    str  = "production" if prod else "dev"
+    reload:  bool = not prod
+    workers: int  = 4 if prod else 1
+
+    console.print()
+    console.print(Rule(f"[bold green]PaperDraft[/bold green] — {mode}"))
+    console.print(f"  [dim]Address:[/dim] http://{host}:{port}")
+    console.print(f"  [dim]Reload:[/dim]  {reload}")
+    if prod:
+        console.print(f"  [dim]Workers:[/dim] {workers}")
+    console.print(Rule())
+    console.print()
+
+    try:
+        import uvicorn
+        uvicorn.run("main:app", host=host, port=port, reload=reload, workers=workers if prod else None)
+    except ImportError:
+        err.print(
+            "[bold red]✗[/bold red]  uvicorn not installed. "
+            "Run [bold]pip install uvicorn[/bold]."
+        )
+        raise typer.Exit(code=3)
+
+
+def _read_port(cwd: Path) -> int:
+    """
+    Read APP_PORT from the active .env file.
+    Checks .env for ENV= to determine which .env.{env} file to load,
+    then reads APP_PORT from it. Falls back to 8000 if not found.
+    """
+    env: str = "dev"
+    base_env: Path = cwd / ".env"
+    if base_env.exists():
+        for line in base_env.read_text(encoding="utf-8").splitlines():
+            if line.startswith("ENV="):
+                env = line.split("=", 1)[1].strip()
+                break
+
+    env_file: Path = cwd / f".env.{env}"
+    if env_file.exists():
+        for line in env_file.read_text(encoding="utf-8").splitlines():
+            if line.startswith("APP_PORT="):
+                value: str = line.split("=", 1)[1].strip()
+                if value.isdigit():
+                    return int(value)
+
+    err.print("[bold yellow]![/bold yellow]  APP_PORT not found in env file — defaulting to 8000.")
+    return 8000

paper/draft/cli/commands/validate.py

@@ -0,0 +1,169 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# PaperDraft CLI — validate command
+# File: paper/draft/cli/commands/validate.py
+# ─────────────────────────────────────────────────────────────────────────────
+# Usage:
+#   draft validate location
+#   draft validate location --quiet
+#
+# Checks:
+#   1. services/<n>/ folder exists
+#   2. router.py, controller.py, service.py, __init__.py all present
+#   3. router.py imports the controller
+#   4. service.py defines the service class
+#   5. controller.py defines the controller class
+#   6. main.py imports and registers this router
+# ─────────────────────────────────────────────────────────────────────────────
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+app:     typer.Typer = typer.Typer(help="Validate a service.", no_args_is_help=True)
+console: Console     = Console()
+err:     Console     = Console(stderr=True)
+
+
+def _to_class_name(name: str) -> str:
+    return "".join(p.capitalize() for p in name.replace("-", "_").split("_"))
+
+
+@app.callback(invoke_without_command=True)
+def validate_cmd(
+    service: Annotated[
+        str,
+        typer.Argument(help="Service name to validate — e.g. location, user.")
+    ],
+    quiet: Annotated[
+        bool,
+        typer.Option("--quiet", "-q", help="Suppress output on success.")
+    ] = False,
+) -> None:
+    """
+    Validate a service — checks file structure and main.py registration.
+
+    Exits 0 on success, 1 on validation errors, 2 on missing project root.
+    """
+    cwd: Path = Path.cwd()
+
+    # ── Project root check ────────────────────────────────────────────────────
+    main_py: Path = cwd / "main.py"
+    if not main_py.exists():
+        err.print(
+            "[bold red]✗[/bold red]  No [yellow]main.py[/yellow] found. "
+            "Run [bold]draft init[/bold] first."
+        )
+        raise typer.Exit(code=2)
+
+    service    = service.strip().lower()
+    class_name = _to_class_name(service)
+    svc_dir:   Path = cwd / "services" / service
+
+    issues: list[tuple[str, str]] = []   # (check, message)
+    passes: list[str]             = []
+
+    # ── 1. Service directory ──────────────────────────────────────────────────
+    if not svc_dir.exists():
+        issues.append(("directory", f"services/{service}/ does not exist"))
+    else:
+        passes.append(f"services/{service}/ exists")
+
+    # ── 2. Required files ─────────────────────────────────────────────────────
+    required_files: list[str] = [
+        "__init__.py", "router.py", "controller.py", "service.py"
+    ]
+    for fname in required_files:
+        fpath: Path = svc_dir / fname
+        if not fpath.exists():
+            issues.append((fname, f"services/{service}/{fname} is missing"))
+        else:
+            passes.append(f"services/{service}/{fname} exists")
+
+    # ── 3. router.py — imports controller ────────────────────────────────────
+    router_path: Path = svc_dir / "router.py"
+    if router_path.exists():
+        router_content: str = router_path.read_text(encoding="utf-8")
+        if f"{class_name}Controller" in router_content:
+            passes.append(f"router.py references {class_name}Controller")
+        else:
+            issues.append((
+                "router.py",
+                f"{class_name}Controller not referenced in router.py"
+            ))
+
+    # ── 4. controller.py — defines controller class ───────────────────────────
+    ctrl_path: Path = svc_dir / "controller.py"
+    if ctrl_path.exists():
+        ctrl_content: str = ctrl_path.read_text(encoding="utf-8")
+        if f"class {class_name}Controller" in ctrl_content:
+            passes.append(f"controller.py defines {class_name}Controller")
+        else:
+            issues.append((
+                "controller.py",
+                f"class {class_name}Controller not found in controller.py"
+            ))
+
+    # ── 5. service.py — defines service class ────────────────────────────────
+    svc_path: Path = svc_dir / "service.py"
+    if svc_path.exists():
+        svc_content: str = svc_path.read_text(encoding="utf-8")
+        if f"class {class_name}Service" in svc_content:
+            passes.append(f"service.py defines {class_name}Service")
+        else:
+            issues.append((
+                "service.py",
+                f"class {class_name}Service not found in service.py"
+            ))
+
+    # ── 6. main.py — router imported and registered ───────────────────────────
+    main_content: str = main_py.read_text(encoding="utf-8")
+    import_line:  str = f"from services.{service}.router import router"
+    router_line:  str = f"app.include_router({service}_router"
+
+    if import_line in main_content:
+        passes.append(f"main.py imports services.{service}.router")
+    else:
+        issues.append((
+            "main.py",
+            f"services.{service}.router not imported in main.py"
+        ))
+
+    if router_line in main_content:
+        passes.append(f"main.py registers {service}_router")
+    else:
+        issues.append((
+            "main.py",
+            f"{service}_router not registered via app.include_router() in main.py"
+        ))
+
+    # ── Output ────────────────────────────────────────────────────────────────
+    valid: bool = len(issues) == 0
+
+    if valid and not quiet:
+        console.print(
+            f"[bold green]✓[/bold green]  [bold]{service}[/bold] — "
+            f"valid, {len(passes)} checks passed."
+        )
+        raise typer.Exit(code=0)
+
+    if not valid:
+        table = Table(show_header=False, box=None, padding=(0, 2))
+        for check, msg in issues:
+            table.add_row(
+                f"[bold red]✗[/bold red]",
+                f"[bold]{check}[/bold]",
+                f"[dim]{msg}[/dim]"
+            )
+        console.print(Panel(
+            table,
+            title        = f"[bold red]Validation failed — {len(issues)} issue(s)[/bold red]",
+            border_style = "red",
+            subtitle     = service,
+        ))
+        raise typer.Exit(code=1)

paper/draft/cli/main.py

@@ -0,0 +1,23 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# PaperDraft CLI  v0.1
+# File: paper/draft/cli/main.py
+# ─────────────────────────────────────────────────────────────────────────────
+
+import typer
+from paper.draft.cli.commands import init, new, validate, run
+
+app: typer.Typer = typer.Typer(
+    name             = "draft",
+    help             = "PaperDraft — opinionated REST API framework.",
+    add_completion   = True,
+    no_args_is_help  = True,
+    rich_markup_mode = "rich",
+)
+
+app.add_typer(init.app,     name="init")
+app.add_typer(new.app,      name="new")
+app.add_typer(validate.app, name="validate")
+app.add_typer(run.app,      name="run")
+
+if __name__ == "__main__":
+    app()

paper_draft-0.1.0.dist-info/METADATA

@@ -0,0 +1,468 @@
+Metadata-Version: 2.4
+Name: paper-draft
+Version: 0.1.0
+Summary: Opinionated FastAPI toolkit with CLI-driven architecture
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: paper-core
+Requires-Dist: typer
+Requires-Dist: jinja2
+Requires-Dist: rich
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: httpx; extra == "dev"
+
+# PaperDraft
+
+Opinionated Python REST API framework with CLI-driven architecture.
+
+PaperDraft scaffolds projects and services with an enforced layered structure, and ships a production-ready core library covering auth, database, encryption, email, middleware, and more.
+
+> **Status:** pre-release · v0.1 in progress · Paper Plane Consulting LLC
+
+---
+
+## Table of Contents
+
+1. [Installation](#installation)
+2. [Setup](#setup)
+3. [CLI Reference](#cli-reference)
+4. [Building with paper-draft](#building-with-paper-draft)
+5. [Project Structure](#project-structure)
+6. [Extending paper-draft](#extending-paper-draft)
+7. [Architecture](#architecture)
+
+---
+
+## Packages
+
+PaperDraft is split into two packages:
+
+| Package | Purpose |
+|---|---|
+| `paper-core` | Runtime library — auth, DB, security, middleware, email, errors, audit |
+| `paper-draft` | CLI tooling — project scaffolding and service generation |
+
+---
+
+## Installation
+
+**Requirements:** Python 3.11+
+
+```bash
+pip install paper-draft
+```
+
+`paper-core` is installed automatically as a dependency.
+
+---
+
+## Local Development Setup
+
+**Prerequisites:** Python 3.11+
+
+```bash
+# 1. Clone the CLI repo
+git clone https://flypaperplane@bitbucket.org/ppc-llc/paper-draft.git
+cd paper-draft
+
+# 2. Create and activate a virtual environment
+python -m venv .venv
+source .venv/bin/activate        # macOS/Linux
+.venv\Scripts\activate           # Windows
+
+# 3. Install paper-core
+pip install paper-core
+
+# 4. Install paper-draft CLI in editable mode with dev dependencies
+pip install -e ".[dev]"
+```
+
+Once installed, the `draft` CLI is available in your environment:
+
+```bash
+draft --help
+```
+
+---
+
+## Setup
+
+### Environment Files
+
+PaperDraft uses layered `.env` files. The base `.env` sets the active environment, and the environment-specific file is loaded on top.
+
+```
+.env               ← sets ENV=dev (or staging, production)
+.env.dev           ← development values (auto-created by draft init)
+.env.staging       ← staging values (create manually)
+.env.production    ← production values (create manually)
+```
+
+**`.env`** (minimal — sets the active environment):
+```env
+ENV=dev
+```
+
+**`.env.dev`** (created automatically by `draft init`):
+```env
+ENV=dev
+APP_URL=http://localhost:8000
+APP_PORT=8000
+
+POSTGRES_CONN_STRING=postgresql+asyncpg://user:password@localhost:5432/dbname
+POSTGRES_ADMIN_CONN_STRING=postgresql+asyncpg://user:password@localhost:5432/postgres
+
+ENCRYPTION_PUBLIC_KEY=<base64-encoded PEM public key>
+ENCRYPTION_PRIVATE_KEY=<base64-encoded PEM private key>
+
+EMAIL_SMTP_HOST=smtp.example.com
+EMAIL_SMTP_PORT=587
+EMAIL_SMTP_USERNAME=your@email.com
+EMAIL_SMTP_PASSWORD=your-smtp-password
+EMAIL_SENDER_NAME=Your App
+EMAIL_SENDER_ADDRESS=no-reply@example.com
+```
+
+### Generating Encryption Keys
+
+PaperDraft uses RSA key pairs (RS256) for JWT signing and field-level encryption.
+
+```bash
+# Generate a 2048-bit RSA private key
+openssl genrsa -out private.pem 2048
+
+# Derive the public key
+openssl rsa -in private.pem -pubout -out public.pem
+
+# Base64-encode each for .env storage
+base64 -w 0 private.pem   # → ENCRYPTION_PRIVATE_KEY
+base64 -w 0 public.pem    # → ENCRYPTION_PUBLIC_KEY
+```
+
+---
+
+## CLI Reference
+
+### `draft init <name> --port <port>`
+
+Creates a new project in a `<name>/` directory.
+
+```bash
+draft init my-api --port 8000
+```
+
+**Creates:**
+```
+my-api/
+├── main.py            # FastAPI app entry point
+├── dependencies.py    # DB + auth dependency injection
+├── config.py          # Pydantic Settings configuration
+├── requirements.txt   # App dependencies
+├── .gitignore
+├── .env.dev           # Pre-filled environment stub
+├── services/          # Your services go here
+└── .venv/             # Python virtual environment (auto-created)
+```
+
+**Then:**
+```bash
+cd my-api
+# Fill in .env.dev with your DB connection string and keys
+# Activate the venv: source .venv/bin/activate (macOS/Linux) or .venv\Scripts\activate (Windows)
+```
+
+---
+
+### `draft new service <name>`
+
+Scaffolds a new service inside an existing project.
+
+```bash
+draft new service users
+draft new service users --prefix api/v1/users   # custom URL prefix
+```
+
+**Creates:**
+```
+services/users/
+├── __init__.py
+├── router.py       # FastAPI APIRouter — define your routes here
+├── controller.py   # UsersController — validate + orchestrate
+└── service.py      # UsersService — business logic
+```
+
+Also patches `main.py` to import and register the router automatically.
+
+---
+
+### `draft validate <service>`
+
+Validates a service's structure and `main.py` registration.
+
+```bash
+draft validate users
+draft validate users --quiet   # suppress output on success
+```
+
+**Checks:**
+- `services/users/` directory exists
+- `router.py`, `controller.py`, `service.py`, `__init__.py` all present
+- `router.py` references `UsersController`
+- `controller.py` defines `class UsersController`
+- `service.py` defines `class UsersService`
+- `main.py` imports and registers the router
+
+Exits `0` on success, `1` on validation errors, `2` if not in a project root.
+
+---
+
+### `draft run`
+
+Runs the app with uvicorn. Port is read from `APP_PORT` in your `.env.{ENV}` file.
+
+```bash
+draft run               # dev mode — auto-reload enabled
+draft run --prod        # production — 4 workers, no reload
+draft run --host 0.0.0.0 --prod
+```
+
+---
+
+## Building with PaperDraft
+
+### Workflow
+
+```bash
+# 1. Create a new project
+draft init my-api --port 8000
+cd my-api
+
+# 2. Fill in .env.dev
+
+# 3. Add a service
+draft new service users
+
+# 4. Define your routes in services/users/router.py
+# 5. Implement controller logic in services/users/controller.py
+# 6. Implement business logic in services/users/service.py
+
+# 7. Validate
+draft validate users
+
+# 8. Run
+draft run
+```
+
+### Layer Responsibilities
+
+Each scaffolded service has three layers with strict responsibilities:
+
+```
+router.py       ← HTTP only. Receives request, injects dependencies, returns response.
+                  No logic. No direct DB access.
+
+controller.py   ← Validates the request. Orchestrates service calls.
+                  No business logic. No direct DB access.
+
+service.py      ← All business logic lives here.
+                  Calls the DB via injected Postgres instance.
+```
+
+### Dependency Injection
+
+`dependencies.py` wires up DB and config — inject them directly in route signatures:
+
+```python
+from dependencies import MasterDb, TenantDb, Configuration
+
+@router.get("")
+async def retrieve(
+    db:     MasterDb,
+    config: Configuration,
+    claims: Dict[str, Any] = Depends(Authenticate())
+):
+    return await UsersController.retrieve(db, config, claims)
+```
+
+### Auth
+
+Use `Authenticate` for any valid JWT, `Authorize` for role enforcement:
+
+```python
+from paper.core.auth import Authenticate, Authorize
+
+# Any authenticated user
+claims = Depends(Authenticate())
+
+# Role-restricted
+claims = Depends(Authorize(["admin", "manager"]))
+```
+
+---
+
+## Project Structure
+
+A full PaperDraft project looks like this:
+
+```
+my-api/
+├── main.py                   # FastAPI app, middleware, router registration
+├── dependencies.py           # DB + auth dependency wiring
+├── config.py                 # Pydantic Settings
+├── requirements.txt
+├── .env                      # Sets ENV=dev|staging|production
+├── .env.dev                  # Dev config (never commit)
+├── services/
+│   ├── users/
+│   │   ├── router.py
+│   │   ├── controller.py
+│   │   └── service.py
+│   └── auth/
+│       ├── router.py
+│       ├── controller.py
+│       └── service.py
+└── .venv/
+```
+
+---
+
+## Extending PaperDraft
+
+PaperDraft's core components are built on abstract base classes. Extend them to add new database engines, encryption algorithms, or email providers while keeping the same interface everywhere.
+
+---
+
+### Custom Database Engine
+
+Extend `Repository` to add a new DB engine (MySQL, MongoDB, etc.).
+
+```python
+from paper.core.db.base import Repository, FilterType
+from typing import Any, Dict, List, Optional
+
+class MySQLRepository(Repository[T, M]):
+
+    def __init__(self, connection_string: str) -> None:
+        # set up your engine here
+        ...
+
+    async def create(self, entity, model, data):
+        ...
+
+    async def retrieve(self, entity, model, filter=None):
+        ...
+
+    async def single(self, entity, model, id):
+        ...
+
+    async def update(self, entity, model, id, data):
+        ...
+
+    async def delete(self, entity, id):
+        ...
+```
+
+Inject it the same way as `Postgres` via `dependencies.py`.
+
+---
+
+### Custom Encryption Algorithm
+
+Extend `BaseCrypto` to add a new cipher (AES, ChaCha20, etc.).
+
+```python
+from paper.core.security.base import BaseCrypto
+
+class AESCrypto(BaseCrypto):
+
+    def __init__(self, key: str) -> None:
+        self._key = key
+
+    def encrypt(self, value: str) -> str:
+        ...
+
+    def decrypt(self, cipher: str) -> str:
+        ...
+
+    def encrypt_urlsafe(self, value: str) -> str:
+        ...
+
+    def decrypt_urlsafe(self, cipher: str) -> str:
+        ...
+
+    def encrypt_raw(self, value: str) -> bytes:
+        ...
+
+    def decrypt_raw(self, cipher_bytes: bytes) -> str:
+        ...
+```
+
+Pass your implementation to `MultiTenantDbDependency` or anywhere `BaseCrypto` is accepted:
+
+```python
+crypto = AESCrypto(key=config.ENCRYPTION.KEY.SYMMETRIC)
+```
+
+---
+
+### Custom Email Provider
+
+Extend `BaseEmailService` to add a new provider (SendGrid, SES, Postmark, etc.).
+
+```python
+from paper.core.email.base import BaseEmailService
+from typing import Dict
+
+class SendGridEmailService(BaseEmailService):
+
+    def __init__(self, api_key: str, sender_name: str, sender_email: str) -> None:
+        self._api_key      = api_key
+        self._sender_name  = sender_name
+        self._sender_email = sender_email
+
+    def send(
+        self,
+        subject:         str,
+        recipient_name:  str,
+        recipient_email: str,
+        data:            Dict[str, str],
+    ) -> bool:
+        # implement SendGrid API call here
+        ...
+```
+
+Instantiate in `dependencies.py` and inject wherever email is needed.
+
+---
+
+## Architecture
+
+```
+HTTP Request
+    ↓
+[ Router ]            receives request, injects dependencies, returns response
+    ↓
+[ Auth Middleware ]    JWT validation + RBAC — always first, never skipped
+    ↓
+[ Custom Middleware ]  CORS, HIPAA headers, rate limiting, audit logging
+    ↓
+[ Controller ]        validates request, orchestrates service calls
+    ↓
+[ Service ]           all business logic lives here
+    ↓
+[ Postgres / DB ]     async SQLAlchemy — injected, never instantiated directly
+```
+
+**Core modules available via `paper.core`:**
+
+| Module | Contents |
+|--------|----------|
+| `paper.core.auth` | `Authenticate`, `Authorize`, `LoginAttemptLimit`, `Password`, JWT utils |
+| `paper.core.db` | `Postgres`, `Repository`, `FilterType`, `MultiTenantDbDependency` |
+| `paper.core.security` | `RSACrypto`, `BaseCrypto`, `Crypto`, `Hasher`, `Pem` |
+| `paper.core.email` | `SMTPEmailService`, `BaseEmailService`, `Subject`, `EmailTheme` |
+| `paper.core.errors` | `ErrorHandler`, `ErrorMessage` |
+| `paper.core.middleware` | `HipaaResponseHeaders`, `RequestLoggingMiddleware`, `RequestIdMiddleware` |
+| `paper.core.audit` | `Audit` |

paper_draft-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+paper/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+paper/draft/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+paper/draft/cli/main.py,sha256=CdqGFqlx8hq5eNtJ2-gkyq7Qtq8s0cU8inDK35Wonl4,1032
+paper/draft/cli/commands/__init__.py,sha256=1G1KmELqWS3iPgM3-KmUNtpEYdgh97jrHRkw6wrDumM,106
+paper/draft/cli/commands/init.py,sha256=fwKp7q2qJ7BRjTDDyB3FbQE_0dwY6-EcL43xuS7_w24,8203
+paper/draft/cli/commands/new.py,sha256=cfi7p8nJwadl9JJbFaw_oyj31gH6War01frVaGmFZec,8137
+paper/draft/cli/commands/run.py,sha256=WYc72KME4WkXcgZG6E2_tN0UnCTl2zLSwIek3jB0nC4,3789
+paper/draft/cli/commands/validate.py,sha256=EWE0QHq5DwSCjhdrkJdSKmw0zMEg6ebsEgYxVTsEqWg,7307
+paper_draft-0.1.0.dist-info/METADATA,sha256=Gl4I8TTlf7mr_uylIlf5qnLw3TVavhaoha6wDDLFPtM,12223
+paper_draft-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+paper_draft-0.1.0.dist-info/entry_points.txt,sha256=ZXlns9uk-lu9KyszQ5D7ZJxUo8oXIBhPJv4l0fjTLXg,51
+paper_draft-0.1.0.dist-info/top_level.txt,sha256=4NSK5piDx1QcezDlTFhYZtyixZ0wEqRP_fvBQex6byk,6
+paper_draft-0.1.0.dist-info/RECORD,,

paper_draft-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

paper_draft-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+draft = paper.draft.cli.main:app

paper_draft-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+paper