saas-maker 0.1.0__py3-none-any.whl

saas_maker/__init__.py

@@ -0,0 +1,3 @@
+"""SaaS Maker CLI."""
+
+__version__ = "0.1.0"

saas_maker/cli.py

@@ -0,0 +1,162 @@
+"""SaaS Maker CLI — `uvx saas-maker new <name>` / `saas-maker generate module <name>`."""
+
+from pathlib import Path
+
+import typer
+
+from saas_maker import (
+    __version__,
+    module_gen,
+    preflight,
+    scaffold,
+    stack,
+    wizard,
+)
+from saas_maker import (
+    fields as fields_mod,
+)
+from saas_maker.naming import Names, NamingError
+
+app = typer.Typer(
+    name="saas-maker",
+    help="The SaaS Maker generator — multi-tenant SaaS (FastAPI + React), omakase.",
+    no_args_is_help=True,
+)
+generate_app = typer.Typer(help="Code generators (à la `rails generate`).", no_args_is_help=True)
+app.add_typer(generate_app, name="generate")
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"saas-maker {__version__} (template {stack.STACK_REF})")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show the CLI and pinned template versions.",
+    ),
+) -> None:
+    pass
+
+
+@app.command()
+def new(
+    name: str = typer.Argument(..., help="Project name (lowercase, dashes)"),
+    defaults: bool = typer.Option(
+        False, "--defaults", help="Skip the wizard — placeholder config, CI-friendly."
+    ),
+    skip_provision: bool = typer.Option(
+        False, "--skip-provision", help="Write files only; no uv/npm/createdb/migrate."
+    ),
+    ref: str = typer.Option(
+        stack.STACK_REF, "--ref", help="Template tag/branch to scaffold (default: pinned)."
+    ),
+    source: Path | None = typer.Option(
+        None, "--source", help="Local saas-maker checkout to copy instead of downloading (dev)."
+    ),
+    output: Path | None = typer.Option(
+        None, "--output", help="Parent directory for the project (default: current directory)."
+    ),
+) -> None:
+    """Scaffold a configured SaaS project: wizard → branding → .envs → provision → git."""
+    try:
+        slug = scaffold.validate_name(name)
+
+        typer.echo("🔎 Preflight:")
+        for check in preflight.run_checks():
+            mark = "✅" if check.found else "⚠️ "
+            hint = "" if check.found else f"  ({check.hint})"
+            typer.echo(f"  {mark} {check.name}: {check.detail}{hint}")
+        typer.echo("")
+
+        answers = wizard.default_answers(slug) if defaults else wizard.run_wizard(slug)
+        scaffold.run_new(
+            answers,
+            target_parent=(output or Path.cwd()).expanduser().resolve(),
+            ref=ref,
+            source=source,
+            skip_provision=skip_provision,
+            echo=typer.echo,
+        )
+        typer.echo("")
+        typer.echo("Teach your coding agent to extend this project:")
+        typer.echo("  npx skills add SaaS-Maker-Stack/skills --skill '*'")
+    except Exception as exc:
+        if isinstance(exc, typer.Exit):
+            raise
+        typer.secho(f"error: {exc}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1) from exc
+
+
+@generate_app.command("module")
+def gen_module(
+    name: str = typer.Argument(..., help="Module name, snake_case singular (invoice, work_order)"),
+    fields: str | None = typer.Option(
+        None,
+        "--fields",
+        help="name:kind[?][:Label],… — kinds: str text int float bool date datetime. "
+        "First field is the title. Default: " + fields_mod.DEFAULT_FIELDS,
+    ),
+    status: str | None = typer.Option(
+        None, "--status", help="value=Label,… adds a status column, filter and badge."
+    ),
+    label: str | None = typer.Option(None, "--label", help="Spanish singular label (Factura)."),
+    label_plural: str | None = typer.Option(None, "--label-plural", help="Spanish plural label."),
+    feminine: bool = typer.Option(False, "--feminine", help='Feminine noun ("Nueva factura").'),
+    plural: str | None = typer.Option(None, "--plural", help="snake_case plural override."),
+    icon: str = typer.Option("FolderKanban", "--icon", help="lucide-react icon for the sidebar."),
+    defaults: bool = typer.Option(False, "--defaults", help="No prompts; use flags/defaults."),
+    backend_only: bool = typer.Option(False, "--backend-only"),
+    frontend_only: bool = typer.Option(False, "--frontend-only"),
+) -> None:
+    """Scaffold a tenant-scoped CRUD (table, API, page, tests) inside a saas-maker project."""
+    try:
+        if fields is None and not defaults:
+            answers = wizard.run_module_wizard(name, fields_mod.DEFAULT_FIELDS)
+            label = label or answers["label"]
+            label_plural = label_plural or answers["label_plural"]
+            feminine = feminine or answers["feminine"]
+            fields = answers["fields"]
+            status = status or answers["status"]
+        names = Names.build(
+            name,
+            plural=plural,
+            label=label,
+            label_plural=label_plural,
+            feminine=feminine,
+            icon=icon,
+        )
+        parsed_fields = fields_mod.parse_fields(fields or fields_mod.DEFAULT_FIELDS)
+        parsed_status = fields_mod.parse_status(status)
+        written = module_gen.generate(
+            names,
+            parsed_fields,
+            parsed_status,
+            cwd=Path.cwd(),
+            backend=not frontend_only,
+            frontend=not backend_only,
+            echo=typer.echo,
+        )
+    except (module_gen.ModuleGenError, fields_mod.FieldError, NamingError) as exc:
+        typer.secho(f"error: {exc}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1) from exc
+
+    project = module_gen.detect_project(Path.cwd())
+    for path in written:
+        typer.echo(f"  write   {path.relative_to(project)}")
+    typer.echo("\nNext steps:")
+    if not frontend_only:
+        typer.echo("  cd backend && make migrate && make test && make lint")
+    if not backend_only:
+        typer.echo("  cd frontend && npm run lint && npm run typecheck && npm test")
+    typer.echo(f"  document {names.api_prefix} in backend/CLAUDE.md and frontend/CLAUDE.md")
+
+
+if __name__ == "__main__":
+    app()

saas_maker/color.py

@@ -0,0 +1,46 @@
+"""Hex color -> OKLCH hue, so the wizard accepts `#0066ff` as well as `262`.
+
+The template derives its whole accent palette from one OKLCH hue angle
+(`--brand-hue`). sRGB -> linear -> OKLab (Björn Ottosson's matrices) -> hue.
+"""
+
+import math
+import re
+
+HEX_RE = re.compile(r"^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$")
+
+
+def _srgb_to_linear(c: float) -> float:
+    return c / 12.92 if c <= 0.04045 else ((c + 0.055) / 1.055) ** 2.4
+
+
+def hex_to_hue(value: str) -> int:
+    """`#0066ff` -> 262. Raises ValueError for anything that is not a hex color."""
+    match = HEX_RE.match(value.strip())
+    if not match:
+        raise ValueError(f"'{value}' is not a hex color")
+    digits = match.group(1)
+    if len(digits) == 3:
+        digits = "".join(ch * 2 for ch in digits)
+    r, g, b = (_srgb_to_linear(int(digits[i : i + 2], 16) / 255) for i in (0, 2, 4))
+
+    l_ = 0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b
+    m_ = 0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b
+    s_ = 0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b
+    l_, m_, s_ = (math.copysign(abs(x) ** (1 / 3), x) for x in (l_, m_, s_))
+
+    a = 1.9779984951 * l_ - 2.4285922050 * m_ + 0.4505937099 * s_
+    b_ = 0.0259040371 * l_ + 0.7827717662 * m_ - 0.8086757660 * s_
+    if math.hypot(a, b_) < 0.01:
+        raise ValueError(f"'{value}' is a gray — it has no hue; pick a chromatic color")
+    return round(math.degrees(math.atan2(b_, a))) % 360
+
+
+def parse_brand(value: str) -> int:
+    """Accepts a hue angle (0-360) or a hex color."""
+    text = value.strip()
+    if text.isdigit():  # a bare number is an angle; hex colors need the '#'
+        if int(text) > 360:
+            raise ValueError("hue angle must be between 0 and 360 (prefix hex colors with #)")
+        return int(text)
+    return hex_to_hue(text)

saas_maker/envfiles.py

@@ -0,0 +1,152 @@
+"""Pure renderers: answers -> `.env` / `.kamal/secrets` / README text.
+
+Everything here is golden-testable: no I/O, no randomness (secrets come in).
+"""
+
+from saas_maker.secrets_gen import GeneratedSecrets
+from saas_maker.wizard import Answers
+
+
+def render_backend_env(a: Answers, s: GeneratedSecrets) -> str:
+    """Local development `.env` for the backend (Mailpit for mail)."""
+    return f"""# App
+APP_NAME={a.name}
+DEBUG=true
+
+# Database
+POSTGRES_HOST={a.pg_host}
+POSTGRES_PORT={a.pg_port}
+POSTGRES_USER={a.pg_user}
+POSTGRES_PASSWORD={a.pg_password}
+POSTGRES_DB={a.db_name}
+
+# JWT Authentication (generated by saas-maker; rotate with: openssl rand -hex 32)
+JWT_SECRET_KEY={s.jwt_secret}
+JWT_ALGORITHM=HS256
+ACCESS_TOKEN_EXPIRE_MINUTES=30
+REFRESH_TOKEN_EXPIRE_DAYS=7
+
+# Invitation System
+INVITE_TOKEN_EXPIRE_DAYS=7
+FRONTEND_URL=http://localhost:5190
+
+# Email verification
+EMAIL_VERIFICATION_TOKEN_EXPIRE_HOURS=48
+REQUIRE_EMAIL_VERIFICATION=false
+
+# Rate limiting on auth endpoints
+RATE_LIMIT_ENABLED=true
+RATE_LIMIT_AUTH=10/minute
+
+# CORS
+CORS_ORIGINS=http://localhost:5190,http://localhost:5191,http://localhost:3000
+CORS_ALLOW_CREDENTIALS=true
+
+# Email SMTP Configuration (local: Mailpit via docker compose, UI on :8025)
+SMTP_HOST=localhost
+SMTP_PORT=1025
+SMTP_USER=
+SMTP_PASSWORD=
+SMTP_FROM_EMAIL={a.smtp_from}
+SMTP_FROM_NAME={a.name}
+SMTP_TLS=false
+SMTP_SSL=false
+"""
+
+
+def render_vite_env() -> str:
+    return "# API Base URL\nVITE_API_BASE_URL=http://localhost:8090\n"
+
+
+def render_backend_secrets(a: Answers, s: GeneratedSecrets) -> str:
+    """`backend/.kamal/secrets` — production values for Kamal (gitignored)."""
+    return f"""# Docker Registry
+DOCKER_REGISTRY_PASSWORD={a.docker_password}
+
+# Database
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD={a.pg_password}
+POSTGRES_DB={a.db_name}
+
+# JWT
+JWT_SECRET_KEY={s.jwt_secret}
+
+# Frontend URL (for invitation links)
+FRONTEND_URL=https://{a.app_domain}
+
+# SMTP Configuration
+SMTP_HOST={a.smtp_host}
+SMTP_PORT={a.smtp_port}
+SMTP_USER={a.smtp_user}
+SMTP_PASSWORD={a.smtp_password}
+SMTP_FROM_EMAIL={a.smtp_from}
+SMTP_FROM_NAME={a.name}
+SMTP_TLS=true
+SMTP_SSL=false
+"""
+
+
+def render_registry_secrets(a: Answers) -> str:
+    """`frontend/.kamal/secrets` and `admin/.kamal/secrets`."""
+    return f"# Docker Registry\nDOCKER_REGISTRY_PASSWORD={a.docker_password}\n"
+
+
+def render_readme(a: Answers, ref: str) -> str:
+    return f"""# {a.name}
+
+Multi-tenant SaaS generated with [saas-maker](https://github.com/SaaS-Maker-Stack/saas-maker)
+(`saas-maker new`, template `{ref}`).
+
+| Path | Service | Run |
+|------|---------|-----|
+| `backend/` | FastAPI + SQLModel + PostgreSQL (API) | `make dev` (:8090) |
+| `frontend/` | React + Vite — the tenant app | `npm run dev` (:5190) |
+| `admin/` | React + Vite — platform admin panel | `npm run dev` (:5191) |
+
+Each service is its own git repository, deployed independently with Kamal
+(`config/deploy.yml`, secrets in `.kamal/secrets`). `DESIGN.md` is the design
+system; `CLAUDE.md` files guide coding agents.
+
+## Development
+
+```bash
+cd backend && make install && make migrate && make dev      # API on :8090 (docs at /docs)
+cd frontend && npm install && npm run dev                    # app on :5190
+cd admin && npm install && npm run dev                       # admin on :5191
+```
+
+Local mail goes to Mailpit (`docker compose up -d` starts Postgres + Mailpit,
+UI on http://localhost:8025). Configuration lives in each service's `.env`.
+
+## Quality
+
+```bash
+cd backend && make lint && make test && make audit
+cd frontend && npm run lint && npm run typecheck && npm test && npm run audit
+cd admin && npm run lint && npm run typecheck && npm test && npm run audit
+```
+
+## Adding a module
+
+```bash
+uvx saas-maker generate module invoice --label Factura --feminine \\
+  --fields "number:str:Número,amount:float:Monto" --status "draft=Borrador,paid=Pagada"
+```
+
+Generates the tenant-scoped table, API, page, sidebar entry and tests on both
+sides. Review the migration, then `cd backend && make migrate`.
+
+## Production
+
+| Service | URL |
+|---------|-----|
+| App | https://{a.app_domain} |
+| Admin | https://{a.admin_domain} |
+| API | https://{a.api_domain} |
+
+```bash
+cd backend && kamal deploy
+cd frontend && kamal deploy
+cd admin && kamal deploy
+```
+"""

saas_maker/fetch.py

@@ -0,0 +1,103 @@
+"""Degit-style fetch: GitHub tarballs at a pinned ref, no git history.
+
+`--source <path>` swaps the download for a local copy of a saas-maker checkout
+(the dev/test escape hatch).
+"""
+
+import io
+import shutil
+import tarfile
+from pathlib import Path
+
+import httpx
+
+from saas_maker import stack
+
+# Never copy these from a local checkout (dev artifacts / secrets).
+_COPY_IGNORE = shutil.ignore_patterns(
+    ".git",
+    ".venv",
+    "node_modules",
+    "__pycache__",
+    "*.pyc",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".mypy_cache",
+    "dist",
+    "build",
+    ".env",
+    ".claude",
+    ".DS_Store",
+    "secrets",  # .kamal/secrets — regenerated per project
+)
+
+
+class FetchError(RuntimeError):
+    pass
+
+
+def _download_tarball(repo: str, ref: str) -> bytes:
+    url = stack.CODELOAD_URL.format(org=stack.ORG, repo=repo, ref=ref)
+    try:
+        resp = httpx.get(url, follow_redirects=True, timeout=60)
+        resp.raise_for_status()
+    except httpx.HTTPError as exc:
+        raise FetchError(f"Could not download {stack.ORG}/{repo}@{ref}: {exc}") from exc
+    return resp.content
+
+
+def _extract_into(tar_bytes: bytes, dest: Path, only: list[str] | None = None) -> None:
+    """Extract a GitHub tarball into dest, stripping the top-level dir."""
+    dest.mkdir(parents=True, exist_ok=True)
+    with tarfile.open(fileobj=io.BytesIO(tar_bytes), mode="r:gz") as tar:
+        for member in tar.getmembers():
+            parts = member.name.split("/", 1)
+            if len(parts) < 2 or not parts[1]:
+                continue
+            rel = parts[1]
+            if only is not None and rel not in only:
+                continue
+            if member.isdir():
+                (dest / rel).mkdir(parents=True, exist_ok=True)
+                continue
+            if member.issym():
+                if "/" not in member.linkname and ".." not in member.linkname:
+                    target = dest / rel
+                    target.parent.mkdir(parents=True, exist_ok=True)
+                    target.unlink(missing_ok=True)
+                    target.symlink_to(member.linkname)
+                continue
+            if not member.isfile():
+                continue
+            target = dest / rel
+            target.parent.mkdir(parents=True, exist_ok=True)
+            extracted = tar.extractfile(member)
+            if extracted is None:
+                continue
+            target.write_bytes(extracted.read())
+            target.chmod(member.mode)
+
+
+def fetch_stack(dest: Path, ref: str, source: Path | None = None) -> None:
+    """Lay backend + frontend + admin + the parent's root files under dest."""
+    if source is not None:
+        _copy_local(source, dest)
+        return
+    for dirname, repo in stack.SERVICES.items():
+        _extract_into(_download_tarball(repo, ref), dest / dirname)
+    _extract_into(_download_tarball(stack.PARENT_REPO, ref), dest, only=stack.PARENT_ROOT_FILES)
+
+
+def _copy_local(source: Path, dest: Path) -> None:
+    source = source.expanduser().resolve()
+    for dirname in stack.SERVICES:
+        src_dir = source / dirname
+        if not src_dir.is_dir():
+            raise FetchError(f"--source {source} has no {dirname}/ directory")
+        shutil.copytree(src_dir, dest / dirname, ignore=_COPY_IGNORE)
+    for root_file in stack.PARENT_ROOT_FILES:
+        src_file = source / root_file
+        if src_file.is_file():
+            target = dest / root_file
+            target.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(src_file, target)