app-auditor 0.1.0__tar.gz

app_auditor-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest tests/ -v
+
+      - name: Lint
+        run: |
+          pip install ruff
+          ruff check src/

app_auditor-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+*.env
+.env
+.DS_Store
+.pytest_cache/
+htmlcov/

app_auditor-0.1.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: app-auditor
+Version: 0.1.0
+Summary: Detect tech stack and production-readiness issues from a live URL or GitHub repo. Zero config, one command.
+Project-URL: Repository, https://github.com/nometria/app-auditor
+License: MIT
+Keywords: audit,cli,devtools,github,production,stack-detection
+Requires-Python: >=3.10
+Requires-Dist: beautifulsoup4>=4.12.0
+Requires-Dist: requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: responses>=0.25.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# app-auditor
+
+> Detect tech stack and surface production-readiness issues from any live URL or GitHub repo. One command, zero config.
+
+---
+
+## Quick start
+
+```bash
+# Clone and install
+git clone https://github.com/ownmy-app/app-auditor
+cd app-auditor
+pip install -e .
+
+# Audit a live URL
+app-audit url https://vercel.com
+
+# Audit a GitHub repo
+app-audit repo myorg/myrepo
+
+# JSON output
+app-audit url https://myapp.com --format json
+```
+
+---
+
+## Usage
+
+### Audit a live URL
+
+```bash
+app-audit url https://myapp.com
+
+# JSON output
+app-audit url https://myapp.com --format json
+```
+
+Output:
+```
+URL: https://myapp.com
+Title: My App
+Stack: nextjs, react, supabase
+
+Risks:
+  • Supabase client: verify auth flow, RLS, and env key exposure in client.
+  • Hosting on Vercel/Netlify: ensure env vars and serverless limits are documented.
+```
+
+### Audit a GitHub repo
+
+```bash
+app-audit repo github.com/myorg/myrepo
+# or shorthand
+app-audit repo myorg/myrepo
+```
+
+Output:
+```
+Repo: myorg/myrepo
+Detected: vite, react, supabase
+
+Missing:
+  ⚠ No Dockerfile found — containerization recommended for production.
+  ⚠ No GitHub Actions workflows — consider adding CI/CD.
+
+Suggestions:
+  → Vite SPA: add Dockerfile and ensure server rewrite rules for SPA routing.
+  → Supabase: verify RLS, auth flow, and env key exposure in client.
+```
+
+### Set GitHub token to avoid rate limiting
+
+```bash
+export GITHUB_TOKEN=ghp_...
+app-audit repo myorg/myrepo
+```
+
+---
+
+## Use as a library
+
+```python
+from app_auditor import audit_url, analyze_repo_url
+
+# Website audit
+result = audit_url("https://myapp.com")
+print(result["detected_stack"])  # {"nextjs": True, "react": True, ...}
+print(result["risks"])           # ["Supabase client: verify RLS...", ...]
+
+# GitHub repo audit
+result = analyze_repo_url("https://github.com/vercel/next.js")
+print(result["detected"])        # {"nextjs": True, "docker": False, ...}
+print(result["missing"])         # ["No Dockerfile found..."]
+print(result["suggestions"])     # ["Next.js: check output mode..."]
+```
+
+---
+
+## Detected stack signals
+
+| Signal | Detection method |
+|--------|-----------------|
+| Next.js | `__next` in HTML, `_next/` paths, `next.js` in server header |
+| Vite | `/assets/` + `modulepreload` in HTML |
+| React | `react` / `reactdom` in HTML or `package.json` |
+| Vue | `v-bind` or `vue` in HTML |
+| Supabase | `supabase` in HTML or repo file paths |
+| Vercel | `vercel` in HTML, server header, or `vercel.json` |
+| Netlify | `netlify` in HTML, header, or config files |
+| Docker | `Dockerfile` in repo tree |
+| GitHub Actions | `.github/workflows/` in repo tree |
+
+---
+
+## Commercial viability
+
+- Free tier: CLI and library (open source)
+- Paid: API with bulk auditing, team dashboards, Slack notifications
+- Inbound funnel: developers debugging production issues → upgrade path to managed services
+
+---
+
+## Example output
+
+### `app-audit url https://vercel.com`
+
+```
+URL: https://vercel.com/
+Title: Vercel: Build and deploy the best web experiences with the AI Cloud
+Stack: nextjs, react, vercel
+
+Risks:
+  • Hosting on Vercel/Netlify: ensure env vars and serverless limits are documented.
+```
+
+### `app-audit url https://supabase.com`
+
+```
+URL: https://supabase.com/
+Title: Supabase | The Postgres Development Platform.
+Stack: nextjs, react, vue, supabase, vercel
+
+Risks:
+  • Supabase client: verify auth flow, RLS, and env key exposure in client.
+  • Hosting on Vercel/Netlify: ensure env vars and serverless limits are documented.
+```

app_auditor-0.1.0/README.md

@@ -0,0 +1,146 @@
+# app-auditor
+
+> Detect tech stack and surface production-readiness issues from any live URL or GitHub repo. One command, zero config.
+
+---
+
+## Quick start
+
+```bash
+# Clone and install
+git clone https://github.com/ownmy-app/app-auditor
+cd app-auditor
+pip install -e .
+
+# Audit a live URL
+app-audit url https://vercel.com
+
+# Audit a GitHub repo
+app-audit repo myorg/myrepo
+
+# JSON output
+app-audit url https://myapp.com --format json
+```
+
+---
+
+## Usage
+
+### Audit a live URL
+
+```bash
+app-audit url https://myapp.com
+
+# JSON output
+app-audit url https://myapp.com --format json
+```
+
+Output:
+```
+URL: https://myapp.com
+Title: My App
+Stack: nextjs, react, supabase
+
+Risks:
+  • Supabase client: verify auth flow, RLS, and env key exposure in client.
+  • Hosting on Vercel/Netlify: ensure env vars and serverless limits are documented.
+```
+
+### Audit a GitHub repo
+
+```bash
+app-audit repo github.com/myorg/myrepo
+# or shorthand
+app-audit repo myorg/myrepo
+```
+
+Output:
+```
+Repo: myorg/myrepo
+Detected: vite, react, supabase
+
+Missing:
+  ⚠ No Dockerfile found — containerization recommended for production.
+  ⚠ No GitHub Actions workflows — consider adding CI/CD.
+
+Suggestions:
+  → Vite SPA: add Dockerfile and ensure server rewrite rules for SPA routing.
+  → Supabase: verify RLS, auth flow, and env key exposure in client.
+```
+
+### Set GitHub token to avoid rate limiting
+
+```bash
+export GITHUB_TOKEN=ghp_...
+app-audit repo myorg/myrepo
+```
+
+---
+
+## Use as a library
+
+```python
+from app_auditor import audit_url, analyze_repo_url
+
+# Website audit
+result = audit_url("https://myapp.com")
+print(result["detected_stack"])  # {"nextjs": True, "react": True, ...}
+print(result["risks"])           # ["Supabase client: verify RLS...", ...]
+
+# GitHub repo audit
+result = analyze_repo_url("https://github.com/vercel/next.js")
+print(result["detected"])        # {"nextjs": True, "docker": False, ...}
+print(result["missing"])         # ["No Dockerfile found..."]
+print(result["suggestions"])     # ["Next.js: check output mode..."]
+```
+
+---
+
+## Detected stack signals
+
+| Signal | Detection method |
+|--------|-----------------|
+| Next.js | `__next` in HTML, `_next/` paths, `next.js` in server header |
+| Vite | `/assets/` + `modulepreload` in HTML |
+| React | `react` / `reactdom` in HTML or `package.json` |
+| Vue | `v-bind` or `vue` in HTML |
+| Supabase | `supabase` in HTML or repo file paths |
+| Vercel | `vercel` in HTML, server header, or `vercel.json` |
+| Netlify | `netlify` in HTML, header, or config files |
+| Docker | `Dockerfile` in repo tree |
+| GitHub Actions | `.github/workflows/` in repo tree |
+
+---
+
+## Commercial viability
+
+- Free tier: CLI and library (open source)
+- Paid: API with bulk auditing, team dashboards, Slack notifications
+- Inbound funnel: developers debugging production issues → upgrade path to managed services
+
+---
+
+## Example output
+
+### `app-audit url https://vercel.com`
+
+```
+URL: https://vercel.com/
+Title: Vercel: Build and deploy the best web experiences with the AI Cloud
+Stack: nextjs, react, vercel
+
+Risks:
+  • Hosting on Vercel/Netlify: ensure env vars and serverless limits are documented.
+```
+
+### `app-audit url https://supabase.com`
+
+```
+URL: https://supabase.com/
+Title: Supabase | The Postgres Development Platform.
+Stack: nextjs, react, vue, supabase, vercel
+
+Risks:
+  • Supabase client: verify auth flow, RLS, and env key exposure in client.
+  • Hosting on Vercel/Netlify: ensure env vars and serverless limits are documented.
+```

app_auditor-0.1.0/app_auditor/__init__.py

@@ -0,0 +1,10 @@
+from .website_auditor import audit_url, detect_stack_from_html
+from .github_auditor import analyze_repo_url, analyze_repo, parse_repo_url
+
+__all__ = [
+    "audit_url",
+    "detect_stack_from_html",
+    "analyze_repo_url",
+    "analyze_repo",
+    "parse_repo_url",
+]

app_auditor-0.1.0/app_auditor/cli.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""
+app-auditor CLI
+
+Commands:
+  app-audit url <url>     Audit a website URL (stack detection + production risks)
+  app-audit repo <url>    Audit a GitHub repo (structure, missing files, suggestions)
+"""
+import argparse
+import json
+import logging
+import sys
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="app-audit",
+        description="Detect tech stack and surface production-readiness issues.",
+    )
+    parser.add_argument(
+        "command",
+        choices=["url", "repo"],
+        help="What to audit: a live URL or a GitHub repo",
+    )
+    parser.add_argument("target", help="URL or GitHub repo (owner/repo or full URL)")
+    parser.add_argument(
+        "--format",
+        choices=["json", "text"],
+        default="text",
+        help="Output format (default: text)",
+    )
+    parser.add_argument("--verbose", "-v", action="store_true", help="Debug logging")
+
+    args = parser.parse_args()
+
+    if args.verbose:
+        logging.basicConfig(level=logging.DEBUG)
+    else:
+        logging.basicConfig(level=logging.WARNING)
+
+    if args.command == "url":
+        from .website_auditor import audit_url
+        result = audit_url(args.target)
+    else:
+        from .github_auditor import analyze_repo_url
+        result = analyze_repo_url(args.target)
+
+    if args.format == "json":
+        print(json.dumps(result, indent=2))
+        return
+
+    # Human-readable text output
+    if not result.get("ok"):
+        print(f"ERROR: {result.get('error', 'Unknown error')}", file=sys.stderr)
+        sys.exit(1)
+
+    if args.command == "url":
+        print(f"\nURL: {result['url']}")
+        print(f"Title: {result.get('title') or '(none)'}")
+        stack = [k for k, v in result.get("detected_stack", {}).items() if v]
+        print(f"Stack: {', '.join(stack) or 'unknown'}")
+        print("\nRisks:")
+        for r in result.get("risks", []):
+            print(f"  • {r}")
+    else:
+        print(f"\nRepo: {result.get('owner')}/{result.get('repo')}")
+        detected = [k for k, v in result.get("detected", {}).items() if v]
+        print(f"Detected: {', '.join(detected) or 'nothing notable'}")
+        if result.get("missing"):
+            print("\nMissing:")
+            for m in result["missing"]:
+                print(f"  ⚠ {m}")
+        if result.get("suggestions"):
+            print("\nSuggestions:")
+            for s in result["suggestions"]:
+                print(f"  → {s}")
+
+
+if __name__ == "__main__":
+    main()

app_auditor-0.1.0/app_auditor/github_auditor.py

@@ -0,0 +1,173 @@
+"""
+GitHub repo auditor: analyze a public repo's structure and report stack, missing files, and suggestions.
+"""
+import base64
+import logging
+import os
+import re
+from typing import Any, Dict, List, Optional
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+# Timeouts and retries
+GITHUB_TIMEOUT = 25
+GITHUB_HEADERS: Optional[Dict[str, str]] = None
+
+
+def _github_headers() -> Dict[str, str]:
+    global GITHUB_HEADERS
+    if GITHUB_HEADERS is not None:
+        return GITHUB_HEADERS
+    import os
+    token = os.getenv("GITHUB_TOKEN")
+    h = {"Accept": "application/vnd.github+json"}
+    if token:
+        h["Authorization"] = f"Bearer {token}"
+    GITHUB_HEADERS = h
+    return h
+
+
+def parse_repo_url(url: str) -> Optional[tuple[str, str]]:
+    """Return (owner, repo) or None if invalid."""
+    url = url.strip().rstrip("/")
+    # https://github.com/owner/repo or github.com/owner/repo
+    m = re.match(r"(?:https?://)?(?:www\.)?github\.com/([^/]+)/([^/]+?)(?:\.git)?/?$", url, re.I)
+    if m:
+        return m.group(1), m.group(2)
+    # owner/repo
+    if "/" in url and " " not in url and len(url) < 100:
+        parts = url.split("/", 1)
+        if len(parts) == 2 and parts[0] and parts[1]:
+            return parts[0], parts[1]
+    return None
+
+
+def get_repo_tree(owner: str, repo: str) -> List[Dict[str, Any]]:
+    """Fetch repo file tree (recursive). Raises on HTTP error."""
+    url = f"https://api.github.com/repos/{owner}/{repo}/git/trees/HEAD?recursive=1"
+    r = requests.get(url, headers=_github_headers(), timeout=GITHUB_TIMEOUT)
+    r.raise_for_status()
+    data = r.json()
+    return data.get("tree") or []
+
+
+def get_repo_info(owner: str, repo: str) -> Dict[str, Any]:
+    """Fetch repo metadata (description, default branch, etc.)."""
+    url = f"https://api.github.com/repos/{owner}/{repo}"
+    r = requests.get(url, headers=_github_headers(), timeout=GITHUB_TIMEOUT)
+    if r.status_code != 200:
+        return {}
+    return r.json()
+
+
+def get_readme(owner: str, repo: str) -> Optional[str]:
+    """Fetch README content if present."""
+    url = f"https://api.github.com/repos/{owner}/{repo}/readme"
+    r = requests.get(url, headers={**_github_headers(), "Accept": "application/vnd.github.raw"}, timeout=GITHUB_TIMEOUT)
+    if r.status_code != 200:
+        return None
+    return r.text[:8000]
+
+
+def analyze_repo(owner: str, repo: str) -> Dict[str, Any]:
+    """
+    Analyze repo structure and return detected stack, missing items, and migration suggestions.
+    """
+    try:
+        tree = get_repo_tree(owner, repo)
+    except requests.RequestException as e:
+        logger.warning("get_repo_tree failed: %s", e)
+        return {
+            "ok": False,
+            "error": str(e),
+            "detected": {},
+            "missing": [],
+            "suggestions": ["Could not fetch repo; check URL and token."],
+        }
+
+    paths = [item["path"] for item in tree]
+    detected = {
+        "nextjs": any(
+            p in paths for p in ("next.config.js", "next.config.mjs", "next.config.ts")
+        ),
+        "vite": any(
+            p in paths for p in ("vite.config.ts", "vite.config.js", "vite.config.mts")
+        ),
+        "react": False,
+        "docker": any(p in paths for p in ("Dockerfile", "Dockerfile.dev")),
+        "github_actions": any(p.startswith(".github/workflows/") for p in paths),
+        "supabase": any("supabase" in p.lower() for p in paths),
+        "vercel": "vercel.json" in paths or any(p.startswith(".vercel") for p in paths),
+        "env_example": ".env.example" in paths or "env.example" in paths,
+    }
+
+    if "package.json" in paths:
+        try:
+            content = _fetch_file_content(owner, repo, "package.json")
+            if content and "react" in content.lower():
+                detected["react"] = True
+        except Exception:
+            pass
+    if not detected["react"] and "react" in " ".join(paths).lower():
+        detected["react"] = True
+
+    missing = []
+    if not detected["docker"]:
+        missing.append("No Dockerfile found — containerization recommended for production.")
+    if not detected["github_actions"]:
+        missing.append("No GitHub Actions workflows — consider adding CI/CD.")
+    if not detected["env_example"]:
+        missing.append("No .env.example — document required env vars for deployment.")
+
+    suggestions = []
+    if detected["vite"] and not detected["docker"]:
+        suggestions.append("Vite SPA: add Dockerfile and ensure server rewrite rules for SPA routing.")
+    if detected["supabase"]:
+        suggestions.append("Supabase: verify RLS, auth flow, and env key exposure in client.")
+    if detected["nextjs"]:
+        suggestions.append("Next.js: check output mode (standalone/docker) and env at build time.")
+
+    return {
+        "ok": True,
+        "owner": owner,
+        "repo": repo,
+        "detected": detected,
+        "missing": missing,
+        "suggestions": suggestions or ["Review security and env handling before production."],
+        "repo_info": get_repo_info(owner, repo),
+    }
+
+
+def _fetch_file_content(owner: str, repo: str, path: str) -> Optional[str]:
+    url = f"https://api.github.com/repos/{owner}/{repo}/contents/{path}"
+    r = requests.get(url, headers=_github_headers(), timeout=GITHUB_TIMEOUT)
+    if r.status_code != 200:
+        return None
+    data = r.json()
+    if data.get("encoding") == "base64":
+        return base64.b64decode(data.get("content", "")).decode("utf-8", errors="ignore")
+    return None
+
+
+def analyze_repo_url(repo_url: str) -> Dict[str, Any]:
+    """Convenience: parse URL and run analyze_repo."""
+    parsed = parse_repo_url(repo_url)
+    if not parsed:
+        return {
+            "ok": False,
+            "error": "Invalid GitHub repo URL or owner/repo",
+            "detected": {},
+            "missing": [],
+            "suggestions": [],
+        }
+    return analyze_repo(parsed[0], parsed[1])
+
+
+if __name__ == "__main__":
+    import json
+    logging.basicConfig(level=logging.INFO)
+    url = sys.argv[1] if len(sys.argv) > 1 else "https://github.com/vercel/next.js"
+    result = analyze_repo_url(url)
+    print(json.dumps(result, indent=2))

app_auditor-0.1.0/app_auditor/website_auditor.py

@@ -0,0 +1,115 @@
+"""
+Website auditor: detect tech stack from HTML/headers and report production-readiness risks.
+"""
+import logging
+import re
+import sys
+from typing import Any, Dict, List, Optional
+
+import requests
+from bs4 import BeautifulSoup
+
+logger = logging.getLogger(__name__)
+
+REQUEST_TIMEOUT = 15
+USER_AGENT = "GrowthToolsAuditor/1.0 (compatible; +https://github.com)"
+
+
+def fetch_page(url: str) -> tuple[Optional[str], Optional[str], Optional[Dict], int]:
+    """
+    Fetch URL. Returns (html, final_url, headers_dict, status_code).
+    """
+    try:
+        r = requests.get(
+            url,
+            timeout=REQUEST_TIMEOUT,
+            headers={"User-Agent": USER_AGENT},
+            allow_redirects=True,
+        )
+        r.raise_for_status()
+        return r.text, r.url, dict(r.headers), r.status_code
+    except requests.RequestException as e:
+        logger.warning("fetch_page failed: %s", e)
+        return None, None, None, getattr(e, "response", None) and getattr(e.response, "status_code", None) or 0
+
+
+def detect_stack_from_html(html: str, headers: Optional[Dict[str, str]] = None) -> Dict[str, bool]:
+    """Detect likely tech stack from HTML and optional response headers."""
+    headers = headers or {}
+    html_lower = html.lower() if html else ""
+    # Server header can reveal platform
+    server = (headers.get("Server") or headers.get("x-powered-by") or "").lower()
+
+    detected = {
+        "nextjs": "__next" in html_lower or "_next/" in html_lower or "next.js" in server or "next" in html_lower[:2000],
+        "vite": "/assets/" in html_lower and "modulepreload" in html_lower,
+        "react": "react" in html_lower or "reactdom" in html_lower,
+        "vue": "vue" in html_lower or "v-bind" in html_lower,
+        "supabase": "supabase" in html_lower,
+        "vercel": "vercel" in html_lower or "vercel" in server,
+        "netlify": "netlify" in html_lower or "netlify" in server,
+    }
+    return detected
+
+
+def infer_risks(detected: Dict[str, bool]) -> List[str]:
+    """Suggest risks based on detected stack."""
+    risks = []
+    if detected.get("vite"):
+        risks.append("Likely SPA (Vite): check rewrite rules and SEO/SSR if needed.")
+    if detected.get("supabase"):
+        risks.append("Supabase client: verify auth flow, RLS, and env key exposure in client.")
+    if detected.get("react") and not detected.get("nextjs"):
+        risks.append("Client-side React: consider SSR/SSG for SEO and first load.")
+    if detected.get("vercel") or detected.get("netlify"):
+        risks.append("Hosting on Vercel/Netlify: ensure env vars and serverless limits are documented.")
+    if not risks:
+        risks.append("Review security headers and CSP for production.")
+    return risks
+
+
+def audit_url(url: str) -> Dict[str, Any]:
+    """
+    Full audit: fetch URL, detect stack, return title, detected_stack, risks, next_step.
+    """
+    url = url.strip()
+    if not url.startswith(("http://", "https://")):
+        url = "https://" + url
+
+    html, final_url, headers, status = fetch_page(url)
+    if html is None:
+        return {
+            "ok": False,
+            "url": url,
+            "error": "Could not fetch URL (timeout or HTTP error)",
+            "status_code": status,
+            "title": None,
+            "detected_stack": {},
+            "risks": [],
+            "next_step": "Check URL and try again.",
+        }
+
+    soup = BeautifulSoup(html, "html.parser")
+    title = None
+    if soup.title and soup.title.string:
+        title = soup.title.string.strip()[:500]
+
+    detected = detect_stack_from_html(html, headers)
+    risks = infer_risks(detected)
+
+    return {
+        "ok": True,
+        "url": final_url or url,
+        "status_code": status,
+        "title": title,
+        "detected_stack": detected,
+        "risks": risks,
+        "next_step": "Connect GitHub repo for a deeper production audit and migration checklist.",
+    }
+
+
+if __name__ == "__main__":
+    import json
+    logging.basicConfig(level=logging.INFO)
+    u = sys.argv[1] if len(sys.argv) > 1 else "https://example.com"
+    print(json.dumps(audit_url(u), indent=2))

app_auditor-0.1.0/examples/supabase-audit.txt

@@ -0,0 +1,8 @@
+
+URL: https://supabase.com/
+Title: Supabase | The Postgres Development Platform.
+Stack: nextjs, react, vue, supabase, vercel
+
+Risks:
+  • Supabase client: verify auth flow, RLS, and env key exposure in client.
+  • Hosting on Vercel/Netlify: ensure env vars and serverless limits are documented.

app_auditor-0.1.0/examples/vercel-audit.txt

@@ -0,0 +1,7 @@
+
+URL: https://vercel.com/
+Title: Vercel: Build and deploy the best web experiences with the AI Cloud
+Stack: nextjs, react, vercel
+
+Risks:
+  • Hosting on Vercel/Netlify: ensure env vars and serverless limits are documented.

app_auditor-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "app-auditor"
+version = "0.1.0"
+description = "Detect tech stack and production-readiness issues from a live URL or GitHub repo. Zero config, one command."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+keywords = ["audit", "stack-detection", "github", "production", "devtools", "cli"]
+dependencies = [
+    "requests>=2.31.0",
+    "beautifulsoup4>=4.12.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-cov", "responses>=0.25.0"]
+
+[project.scripts]
+app-audit = "app_auditor.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/app_auditor"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[project.urls]
+Repository = "https://github.com/nometria/app-auditor"

app_auditor-0.1.0/src/app_auditor/__init__.py

@@ -0,0 +1,10 @@
+from .website_auditor import audit_url, detect_stack_from_html
+from .github_auditor import analyze_repo_url, analyze_repo, parse_repo_url
+
+__all__ = [
+    "audit_url",
+    "detect_stack_from_html",
+    "analyze_repo_url",
+    "analyze_repo",
+    "parse_repo_url",
+]

app_auditor-0.1.0/src/app_auditor/cli.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""
+app-auditor CLI
+
+Commands:
+  app-audit url <url>     Audit a website URL (stack detection + production risks)
+  app-audit repo <url>    Audit a GitHub repo (structure, missing files, suggestions)
+"""
+import argparse
+import json
+import logging
+import sys
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="app-audit",
+        description="Detect tech stack and surface production-readiness issues.",
+    )
+    parser.add_argument(
+        "command",
+        choices=["url", "repo"],
+        help="What to audit: a live URL or a GitHub repo",
+    )
+    parser.add_argument("target", help="URL or GitHub repo (owner/repo or full URL)")
+    parser.add_argument(
+        "--format",
+        choices=["json", "text"],
+        default="text",
+        help="Output format (default: text)",
+    )
+    parser.add_argument("--verbose", "-v", action="store_true", help="Debug logging")
+
+    args = parser.parse_args()
+
+    if args.verbose:
+        logging.basicConfig(level=logging.DEBUG)
+    else:
+        logging.basicConfig(level=logging.WARNING)
+
+    if args.command == "url":
+        from .website_auditor import audit_url
+        result = audit_url(args.target)
+    else:
+        from .github_auditor import analyze_repo_url
+        result = analyze_repo_url(args.target)
+
+    if args.format == "json":
+        print(json.dumps(result, indent=2))
+        return
+
+    # Human-readable text output
+    if not result.get("ok"):
+        print(f"ERROR: {result.get('error', 'Unknown error')}", file=sys.stderr)
+        sys.exit(1)
+
+    if args.command == "url":
+        print(f"\nURL: {result['url']}")
+        print(f"Title: {result.get('title') or '(none)'}")
+        stack = [k for k, v in result.get("detected_stack", {}).items() if v]
+        print(f"Stack: {', '.join(stack) or 'unknown'}")
+        print("\nRisks:")
+        for r in result.get("risks", []):
+            print(f"  • {r}")
+    else:
+        print(f"\nRepo: {result.get('owner')}/{result.get('repo')}")
+        detected = [k for k, v in result.get("detected", {}).items() if v]
+        print(f"Detected: {', '.join(detected) or 'nothing notable'}")
+        if result.get("missing"):
+            print("\nMissing:")
+            for m in result["missing"]:
+                print(f"  ⚠ {m}")
+        if result.get("suggestions"):
+            print("\nSuggestions:")
+            for s in result["suggestions"]:
+                print(f"  → {s}")
+
+
+if __name__ == "__main__":
+    main()

app_auditor-0.1.0/src/app_auditor/github_auditor.py

@@ -0,0 +1,173 @@
+"""
+GitHub repo auditor: analyze a public repo's structure and report stack, missing files, and suggestions.
+"""
+import base64
+import logging
+import os
+import re
+from typing import Any, Dict, List, Optional
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+# Timeouts and retries
+GITHUB_TIMEOUT = 25
+GITHUB_HEADERS: Optional[Dict[str, str]] = None
+
+
+def _github_headers() -> Dict[str, str]:
+    global GITHUB_HEADERS
+    if GITHUB_HEADERS is not None:
+        return GITHUB_HEADERS
+    token = os.getenv("GITHUB_TOKEN")
+    h = {"Accept": "application/vnd.github+json"}
+    if token:
+        h["Authorization"] = f"Bearer {token}"
+    GITHUB_HEADERS = h
+    return h
+
+
+def parse_repo_url(url: str) -> Optional[tuple[str, str]]:
+    """Return (owner, repo) or None if invalid."""
+    url = url.strip().rstrip("/")
+    # https://github.com/owner/repo or github.com/owner/repo
+    m = re.match(r"(?:https?://)?(?:www\.)?github\.com/([^/]+)/([^/]+?)(?:\.git)?/?$", url, re.I)
+    if m:
+        return m.group(1), m.group(2)
+    # owner/repo
+    if "/" in url and " " not in url and len(url) < 100:
+        parts = url.split("/", 1)
+        if len(parts) == 2 and parts[0] and parts[1]:
+            return parts[0], parts[1]
+    return None
+
+
+def get_repo_tree(owner: str, repo: str) -> List[Dict[str, Any]]:
+    """Fetch repo file tree (recursive). Raises on HTTP error."""
+    url = f"https://api.github.com/repos/{owner}/{repo}/git/trees/HEAD?recursive=1"
+    r = requests.get(url, headers=_github_headers(), timeout=GITHUB_TIMEOUT)
+    r.raise_for_status()
+    data = r.json()
+    return data.get("tree") or []
+
+
+def get_repo_info(owner: str, repo: str) -> Dict[str, Any]:
+    """Fetch repo metadata (description, default branch, etc.)."""
+    url = f"https://api.github.com/repos/{owner}/{repo}"
+    r = requests.get(url, headers=_github_headers(), timeout=GITHUB_TIMEOUT)
+    if r.status_code != 200:
+        return {}
+    return r.json()
+
+
+def get_readme(owner: str, repo: str) -> Optional[str]:
+    """Fetch README content if present."""
+    url = f"https://api.github.com/repos/{owner}/{repo}/readme"
+    r = requests.get(url, headers={**_github_headers(), "Accept": "application/vnd.github.raw"}, timeout=GITHUB_TIMEOUT)
+    if r.status_code != 200:
+        return None
+    return r.text[:8000]
+
+
+def analyze_repo(owner: str, repo: str) -> Dict[str, Any]:
+    """
+    Analyze repo structure and return detected stack, missing items, and migration suggestions.
+    """
+    try:
+        tree = get_repo_tree(owner, repo)
+    except requests.RequestException as e:
+        logger.warning("get_repo_tree failed: %s", e)
+        return {
+            "ok": False,
+            "error": str(e),
+            "detected": {},
+            "missing": [],
+            "suggestions": ["Could not fetch repo; check URL and token."],
+        }
+
+    paths = [item["path"] for item in tree]
+    detected = {
+        "nextjs": any(
+            p in paths for p in ("next.config.js", "next.config.mjs", "next.config.ts")
+        ),
+        "vite": any(
+            p in paths for p in ("vite.config.ts", "vite.config.js", "vite.config.mts")
+        ),
+        "react": False,
+        "docker": any(p in paths for p in ("Dockerfile", "Dockerfile.dev")),
+        "github_actions": any(p.startswith(".github/workflows/") for p in paths),
+        "supabase": any("supabase" in p.lower() for p in paths),
+        "vercel": "vercel.json" in paths or any(p.startswith(".vercel") for p in paths),
+        "env_example": ".env.example" in paths or "env.example" in paths,
+    }
+
+    if "package.json" in paths:
+        try:
+            content = _fetch_file_content(owner, repo, "package.json")
+            if content and "react" in content.lower():
+                detected["react"] = True
+        except Exception:
+            pass
+    if not detected["react"] and "react" in " ".join(paths).lower():
+        detected["react"] = True
+
+    missing = []
+    if not detected["docker"]:
+        missing.append("No Dockerfile found — containerization recommended for production.")
+    if not detected["github_actions"]:
+        missing.append("No GitHub Actions workflows — consider adding CI/CD.")
+    if not detected["env_example"]:
+        missing.append("No .env.example — document required env vars for deployment.")
+
+    suggestions = []
+    if detected["vite"] and not detected["docker"]:
+        suggestions.append("Vite SPA: add Dockerfile and ensure server rewrite rules for SPA routing.")
+    if detected["supabase"]:
+        suggestions.append("Supabase: verify RLS, auth flow, and env key exposure in client.")
+    if detected["nextjs"]:
+        suggestions.append("Next.js: check output mode (standalone/docker) and env at build time.")
+
+    return {
+        "ok": True,
+        "owner": owner,
+        "repo": repo,
+        "detected": detected,
+        "missing": missing,
+        "suggestions": suggestions or ["Review security and env handling before production."],
+        "repo_info": get_repo_info(owner, repo),
+    }
+
+
+def _fetch_file_content(owner: str, repo: str, path: str) -> Optional[str]:
+    url = f"https://api.github.com/repos/{owner}/{repo}/contents/{path}"
+    r = requests.get(url, headers=_github_headers(), timeout=GITHUB_TIMEOUT)
+    if r.status_code != 200:
+        return None
+    data = r.json()
+    if data.get("encoding") == "base64":
+        return base64.b64decode(data.get("content", "")).decode("utf-8", errors="ignore")
+    return None
+
+
+def analyze_repo_url(repo_url: str) -> Dict[str, Any]:
+    """Convenience: parse URL and run analyze_repo."""
+    parsed = parse_repo_url(repo_url)
+    if not parsed:
+        return {
+            "ok": False,
+            "error": "Invalid GitHub repo URL or owner/repo",
+            "detected": {},
+            "missing": [],
+            "suggestions": [],
+        }
+    return analyze_repo(parsed[0], parsed[1])
+
+
+if __name__ == "__main__":
+    import sys
+    import json
+    logging.basicConfig(level=logging.INFO)
+    url = sys.argv[1] if len(sys.argv) > 1 else "https://github.com/vercel/next.js"
+    result = analyze_repo_url(url)
+    print(json.dumps(result, indent=2))

app_auditor-0.1.0/src/app_auditor/website_auditor.py

@@ -0,0 +1,114 @@
+"""
+Website auditor: detect tech stack from HTML/headers and report production-readiness risks.
+"""
+import logging
+import sys
+from typing import Any, Dict, List, Optional
+
+import requests
+from bs4 import BeautifulSoup
+
+logger = logging.getLogger(__name__)
+
+REQUEST_TIMEOUT = 15
+USER_AGENT = "GrowthToolsAuditor/1.0 (compatible; +https://github.com)"
+
+
+def fetch_page(url: str) -> tuple[Optional[str], Optional[str], Optional[Dict], int]:
+    """
+    Fetch URL. Returns (html, final_url, headers_dict, status_code).
+    """
+    try:
+        r = requests.get(
+            url,
+            timeout=REQUEST_TIMEOUT,
+            headers={"User-Agent": USER_AGENT},
+            allow_redirects=True,
+        )
+        r.raise_for_status()
+        return r.text, r.url, dict(r.headers), r.status_code
+    except requests.RequestException as e:
+        logger.warning("fetch_page failed: %s", e)
+        return None, None, None, getattr(e, "response", None) and getattr(e.response, "status_code", None) or 0
+
+
+def detect_stack_from_html(html: str, headers: Optional[Dict[str, str]] = None) -> Dict[str, bool]:
+    """Detect likely tech stack from HTML and optional response headers."""
+    headers = headers or {}
+    html_lower = html.lower() if html else ""
+    # Server header can reveal platform
+    server = (headers.get("Server") or headers.get("x-powered-by") or "").lower()
+
+    detected = {
+        "nextjs": "__next" in html_lower or "_next/" in html_lower or "next.js" in server or "next" in html_lower[:2000],
+        "vite": "/assets/" in html_lower and "modulepreload" in html_lower,
+        "react": "react" in html_lower or "reactdom" in html_lower,
+        "vue": "vue" in html_lower or "v-bind" in html_lower,
+        "supabase": "supabase" in html_lower,
+        "vercel": "vercel" in html_lower or "vercel" in server,
+        "netlify": "netlify" in html_lower or "netlify" in server,
+    }
+    return detected
+
+
+def infer_risks(detected: Dict[str, bool]) -> List[str]:
+    """Suggest risks based on detected stack."""
+    risks = []
+    if detected.get("vite"):
+        risks.append("Likely SPA (Vite): check rewrite rules and SEO/SSR if needed.")
+    if detected.get("supabase"):
+        risks.append("Supabase client: verify auth flow, RLS, and env key exposure in client.")
+    if detected.get("react") and not detected.get("nextjs"):
+        risks.append("Client-side React: consider SSR/SSG for SEO and first load.")
+    if detected.get("vercel") or detected.get("netlify"):
+        risks.append("Hosting on Vercel/Netlify: ensure env vars and serverless limits are documented.")
+    if not risks:
+        risks.append("Review security headers and CSP for production.")
+    return risks
+
+
+def audit_url(url: str) -> Dict[str, Any]:
+    """
+    Full audit: fetch URL, detect stack, return title, detected_stack, risks, next_step.
+    """
+    url = url.strip()
+    if not url.startswith(("http://", "https://")):
+        url = "https://" + url
+
+    html, final_url, headers, status = fetch_page(url)
+    if html is None:
+        return {
+            "ok": False,
+            "url": url,
+            "error": "Could not fetch URL (timeout or HTTP error)",
+            "status_code": status,
+            "title": None,
+            "detected_stack": {},
+            "risks": [],
+            "next_step": "Check URL and try again.",
+        }
+
+    soup = BeautifulSoup(html, "html.parser")
+    title = None
+    if soup.title and soup.title.string:
+        title = soup.title.string.strip()[:500]
+
+    detected = detect_stack_from_html(html, headers)
+    risks = infer_risks(detected)
+
+    return {
+        "ok": True,
+        "url": final_url or url,
+        "status_code": status,
+        "title": title,
+        "detected_stack": detected,
+        "risks": risks,
+        "next_step": "Connect GitHub repo for a deeper production audit and migration checklist.",
+    }
+
+
+if __name__ == "__main__":
+    import json
+    logging.basicConfig(level=logging.INFO)
+    u = sys.argv[1] if len(sys.argv) > 1 else "https://example.com"
+    print(json.dumps(audit_url(u), indent=2))

app_auditor-0.1.0/tests/test_auditors.py

@@ -0,0 +1,111 @@
+"""Tests for app-auditor — no live HTTP required (uses mocking)."""
+import sys
+import os
+import pytest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+
+# ---------------------------------------------------------------------------
+# website_auditor tests
+# ---------------------------------------------------------------------------
+
+def test_detect_nextjs_from_html():
+    from website_auditor import detect_stack_from_html
+    html = '<html><head></head><body><div id="__next"></div></body></html>'
+    result = detect_stack_from_html(html)
+    assert result["nextjs"] is True
+
+
+def test_detect_vite_from_html():
+    from website_auditor import detect_stack_from_html
+    html = '<html><head><link rel="modulepreload" href="/assets/index-abc.js"></head></html>'
+    result = detect_stack_from_html(html)
+    assert result["vite"] is True
+
+
+def test_detect_supabase_from_html():
+    from website_auditor import detect_stack_from_html
+    html = '<script src="https://cdn.supabase.co/supabase.js"></script>'
+    result = detect_stack_from_html(html)
+    assert result["supabase"] is True
+
+
+def test_empty_html_returns_all_false():
+    from website_auditor import detect_stack_from_html
+    result = detect_stack_from_html("")
+    assert all(v is False for v in result.values())
+
+
+def test_infer_risks_vite():
+    from website_auditor import infer_risks
+    risks = infer_risks({"vite": True, "supabase": False, "react": False, "nextjs": False, "vercel": False, "netlify": False, "vue": False})
+    assert any("vite" in r.lower() or "spa" in r.lower() for r in risks)
+
+
+def test_infer_risks_supabase():
+    from website_auditor import infer_risks
+    risks = infer_risks({"vite": False, "supabase": True, "react": False, "nextjs": False, "vercel": False, "netlify": False, "vue": False})
+    assert any("supabase" in r.lower() or "rls" in r.lower() for r in risks)
+
+
+def test_audit_url_unreachable_returns_ok_false():
+    from website_auditor import audit_url
+    result = audit_url("https://this-url-does-not-exist-xyz-12345.invalid")
+    assert result["ok"] is False
+    assert "error" in result
+
+
+# ---------------------------------------------------------------------------
+# github_auditor tests
+# ---------------------------------------------------------------------------
+
+def test_parse_repo_url_full():
+    from github_auditor import parse_repo_url
+    assert parse_repo_url("https://github.com/vercel/next.js") == ("vercel", "next.js")
+
+
+def test_parse_repo_url_shorthand():
+    from github_auditor import parse_repo_url
+    assert parse_repo_url("facebook/react") == ("facebook", "react")
+
+
+def test_parse_repo_url_invalid():
+    from github_auditor import parse_repo_url
+    assert parse_repo_url("not-a-url") is None
+    assert parse_repo_url("") is None
+
+
+def test_analyze_repo_url_invalid_returns_error():
+    from github_auditor import analyze_repo_url
+    result = analyze_repo_url("not-a-github-url")
+    assert result["ok"] is False
+    assert "error" in result
+
+
+def test_analyze_repo_detects_docker(monkeypatch):
+    """Mock GitHub API to return a tree with Dockerfile."""
+    import github_auditor
+
+    def mock_get_repo_tree(owner, repo):
+        return [
+            {"path": "Dockerfile"},
+            {"path": "package.json"},
+            {"path": ".github/workflows/ci.yml"},
+            {"path": ".env.example"},
+        ]
+
+    def mock_get_repo_info(owner, repo):
+        return {"full_name": f"{owner}/{repo}", "default_branch": "main"}
+
+    monkeypatch.setattr(github_auditor, "get_repo_tree", mock_get_repo_tree)
+    monkeypatch.setattr(github_auditor, "get_repo_info", mock_get_repo_info)
+    monkeypatch.setattr(github_auditor, "_fetch_file_content", lambda *a: None)
+
+    result = github_auditor.analyze_repo("myorg", "myrepo")
+    assert result["ok"] is True
+    assert result["detected"]["docker"] is True
+    assert result["detected"]["github_actions"] is True
+    assert result["detected"]["env_example"] is True
+    # No Dockerfile missing warning since it's present
+    assert not any("dockerfile" in m.lower() for m in result["missing"])