clue2app-cli 0.2.7__py3-none-any.whl

clue2app_cli/entrypoint_check.py

@@ -0,0 +1,215 @@
+"""Pre-flight check that catches common "app will build but never start"
+mistakes before c2a creates an app on the platform.
+
+Background: Paketo buildpacks happily produce a runnable image even when
+the source has no declared web entry point. The container then exits with
+ExitCode 0 at launch because there's nothing to run, and the Knative
+service sits in a permanent failed state. Most users won't recognize
+this — they'll see "build succeeded" and assume the deploy worked.
+
+This module shallow-clones the user's repo, inspects the file layout,
+and returns a human-readable error explaining what's missing if it
+spots one of the known traps. The SDK then refuses to create the app
+and the user fixes their repo before re-running.
+
+Detection is intentionally conservative — only reject when we're highly
+confident something is wrong. Unknown frameworks pass through.
+"""
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+
+
+# Paketo Node-Start auto-detects these (and .cjs/.mjs variants) at repo root.
+_NODE_AUTO_ENTRYPOINTS = {
+    "server.js", "server.cjs", "server.mjs",
+    "app.js", "app.cjs", "app.mjs",
+    "main.js", "main.cjs", "main.mjs",
+    "index.js", "index.cjs", "index.mjs",
+}
+
+# Python frameworks Paketo CAN auto-start without a Procfile.
+# Django: manage.py at root + wsgi.py somewhere.
+# Generic WSGI/ASGI apps and FastAPI/Flask all need an explicit Procfile.
+_PYTHON_DJANGO_MARKERS = {"manage.py"}
+
+
+@dataclass(frozen=True)
+class EntryPointIssue:
+    """A detected problem with the repo's web entry point.
+
+    `summary` is one-liner safe for log lines / table cells.
+    `detail` is multi-line guidance suitable for showing to the user.
+    """
+
+    summary: str
+    detail: str
+
+    def __str__(self) -> str:
+        return f"{self.summary}\n\n{self.detail}"
+
+
+def detect_entrypoint_issue(
+    git_url: str,
+    *,
+    branch: str = "main",
+    git_username: str = "",
+    git_password: str = "",
+) -> EntryPointIssue | None:
+    """Shallow-clone `git_url` at `branch` and inspect for known traps.
+
+    Returns None if the repo looks runnable, or an `EntryPointIssue`
+    describing the specific gap. Network/clone failures return None so
+    we don't block users on transient issues — Paketo will surface the
+    real problem at build time as a fallback.
+    """
+    auth_url = _inject_basic_auth(git_url, git_username, git_password)
+
+    tmp = Path(tempfile.mkdtemp(prefix="c2a-entry-check-"))
+    try:
+        proc = subprocess.run(
+            ["git", "clone", "--depth", "1", "--branch", branch, "--quiet", auth_url, str(tmp)],
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        if proc.returncode != 0:
+            # Don't block on clone failures — wrong branch name, transient
+            # network, private repo with bad creds, etc. The platform's own
+            # build step will surface these clearly enough.
+            return None
+        return _inspect_repo(tmp)
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return None
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+
+
+def _inject_basic_auth(git_url: str, username: str, password: str) -> str:
+    """Embed credentials into an https URL so the clone doesn't prompt."""
+    if not password or not git_url.startswith("https://"):
+        return git_url
+    user = username or "x-oauth-basic"
+    return git_url.replace("https://", f"https://{user}:{password}@", 1)
+
+
+def _inspect_repo(root: Path) -> EntryPointIssue | None:
+    """Decide whether the repo declares a working web entry point."""
+    has_procfile_web = _procfile_has_web_line(root / "Procfile")
+    files_at_root = {p.name for p in root.iterdir() if p.is_file()}
+
+    # Java: any pom.xml / build.gradle / build.gradle.kts → buildpack runs
+    # the produced JAR. Always fine.
+    if {"pom.xml", "build.gradle", "build.gradle.kts"} & files_at_root:
+        return None
+
+    # Go: go.mod → buildpack runs the compiled binary. Always fine.
+    if "go.mod" in files_at_root:
+        return None
+
+    # Node: needs Procfile OR one of the auto-detected entrypoints at root.
+    if "package.json" in files_at_root:
+        if has_procfile_web:
+            return None
+        if files_at_root & _NODE_AUTO_ENTRYPOINTS:
+            return None
+        return EntryPointIssue(
+            summary="Node repo has no Procfile and no auto-detectable entry point",
+            detail=(
+                "Paketo's Node-Start buildpack only auto-launches one of:\n"
+                "    server.js | app.js | main.js | index.js (or .cjs / .mjs variants)\n\n"
+                "Your repo has package.json but none of those at the root.\n"
+                "Add a Procfile, e.g. for an Express app:\n\n"
+                "    web: node dist/server.js\n\n"
+                "Or rename your entry file to one of the auto-detected names."
+            ),
+        )
+
+    # Python: FastAPI/Flask/generic WSGI need a Procfile. Django (manage.py)
+    # is auto-detected.
+    python_markers = {"requirements.txt", "pyproject.toml", "Pipfile"}
+    if files_at_root & python_markers:
+        if has_procfile_web:
+            return None
+        if files_at_root & _PYTHON_DJANGO_MARKERS:
+            return None
+        framework = _detect_python_framework(root, files_at_root)
+        return EntryPointIssue(
+            summary=f"{framework or 'Python'} repo has no Procfile (only Django auto-launches without one)",
+            detail=_python_procfile_guidance(framework),
+        )
+
+    # Unknown stack — let it through. Paketo will surface anything wrong.
+    return None
+
+
+def _procfile_has_web_line(procfile_path: Path) -> bool:
+    if not procfile_path.is_file():
+        return False
+    try:
+        for raw_line in procfile_path.read_text(errors="replace").splitlines():
+            line = raw_line.strip()
+            if not line or line.startswith("#"):
+                continue
+            # Procfile format: `<process-type>: <command>`
+            if re.match(r"^web\s*:\s*\S", line):
+                return True
+    except OSError:
+        return False
+    return False
+
+
+def _detect_python_framework(root: Path, files_at_root: set[str]) -> str | None:
+    """Best-effort framework detection from common requirements files."""
+    needles = (
+        ("FastAPI", "fastapi"),
+        ("Flask", "flask"),
+    )
+    for candidate in ("requirements.txt", "pyproject.toml", "Pipfile"):
+        path = root / candidate
+        if path.name not in files_at_root:
+            continue
+        try:
+            content = path.read_text(errors="replace").lower()
+        except OSError:
+            continue
+        for label, needle in needles:
+            if needle in content:
+                return label
+    return None
+
+
+def _python_procfile_guidance(framework: str | None) -> str:
+    if framework == "FastAPI":
+        return (
+            "Paketo's Python buildpack only auto-launches Django apps.\n"
+            "Detected FastAPI in your requirements; add a Procfile at the\n"
+            "repo root with the start command, e.g.:\n\n"
+            "    web: uvicorn main:app --host 0.0.0.0 --port ${PORT:-8080}\n\n"
+            "Replace `main:app` with `<module>:<app-variable>` if your\n"
+            "FastAPI app lives in a different file."
+        )
+    if framework == "Flask":
+        return (
+            "Paketo's Python buildpack only auto-launches Django apps.\n"
+            "Detected Flask in your requirements; add a Procfile at the\n"
+            "repo root with the start command, e.g.:\n\n"
+            "    web: gunicorn app:app --bind 0.0.0.0:${PORT:-8080}\n\n"
+            "Replace `app:app` with `<module>:<app-variable>` if your\n"
+            "Flask app lives in a different file."
+        )
+    return (
+        "Paketo's Python buildpack only auto-launches Django apps\n"
+        "(detected via manage.py + wsgi.py). Your repo doesn't have that\n"
+        "layout, so add a Procfile at the repo root with the start command.\n\n"
+        "Examples:\n"
+        "    web: uvicorn main:app --host 0.0.0.0 --port ${PORT:-8080}     # FastAPI\n"
+        "    web: gunicorn app:app --bind 0.0.0.0:${PORT:-8080}            # Flask / WSGI\n"
+        "    web: python my_server.py                                      # generic\n\n"
+        "Then commit + push and re-run the create command."
+    )