Add repository audit/upgrade plan, web UI hardening, file previews, and CI workflow

.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+  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 dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+      - name: Compile check
+        run: python -m compileall project_prompter
+      - name: Run tests
+        run: pytest
+      - name: Ruff lint
+        run: ruff check .
+      - name: Mypy (core modules)
+        run: mypy project_prompter/audit.py project_prompter/web_security.py
+      - name: Bandit security scan
+        run: bandit -q -r project_prompter || true
+      - name: Dependency audit
+        run: pip-audit || true

README.md

@@ -20,6 +20,7 @@ This tool solves all of these by intelligent filtering, fast static analysis, se
 - **Deep Compatibility:** Tailors output automatically for ChatGPT, Claude, Gemini, and MiniMax via meticulously constructed prompts formats.
 - **Structural Analysis:** Parses and detects standard architectures out of Python, Javascript, generic backend routing and data configuration.
 - **Dynamic Risk & Domain Classification:** Flags large unmanageable files, and applies bespoke contextual prompts for specific domains (like e-commerce, content CMS, or audio).
+- **Hardened Web API:** Input validation for scan limits and ignore-directory entries, safer error responses, and bounded output previews to prevent memory abuse.
 
 ## Security Model
 
@@ -60,10 +61,27 @@ project-prompter "C:/dev/my-project" --mode fast --target-model all
 
 # Access the Web UI
 project-prompter --ui
+
+# Generate repo upgrade/security plan
+project-prompter ./my-project --plan --output ./output
 ```
 
 Then visit `http://127.0.0.1:8787` in your browser.
 
+## Demo
+
+![Web UI Demo](docs/demo.gif)
+
+## Prompt Quality: Before / After
+
+### Before (raw prompt)
+> "Analyze this project. Tell me what's wrong."
+
+### After (generated by project-prompter)
+> Structured prompt with tech stack evidence, prioritized risks, redaction notes, and actionable refactor tasks.
+
+Result: more deterministic, architecture-aware responses with lower hallucination risk.
+
 ## CLI Usage
 
 Run tests over your workspace:

ai-context/PROJECT_BRIEF.md

@@ -0,0 +1,12 @@
+# PROJECT BRIEF
+
+## Security Review Notes
+
+- We must constrain user-provided Ollama base URLs to loopback-only targets unless explicit opt-in is introduced.
+- Relevant implementation files:
+  - `project_prompter/web.py`
+  - `project_prompter/ollama_client.py`
+- Sensitive local Ollama endpoints in scope:
+  - `/api/tags`
+  - `/api/generate`
+- Threat model focus: SSRF-style misuse through analysis configuration and model endpoint routing.

project_prompter/audit.py

@@ -0,0 +1,120 @@
+"""Repository quality/security audit helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class AuditFinding:
+    category: str
+    severity: str
+    title: str
+    detail: str
+    recommendation: str
+
+
+def run_repo_audit(project_path: Path) -> list[AuditFinding]:
+    findings: list[AuditFinding] = []
+
+    if not (project_path / "tests").exists():
+        findings.append(
+            AuditFinding(
+                category="quality",
+                severity="high",
+                title="Automated test suite missing",
+                detail="No top-level tests directory was found.",
+                recommendation="Add pytest-based smoke/unit tests for CLI and web API critical paths.",
+            )
+        )
+
+    if not (project_path / ".github" / "workflows").exists():
+        findings.append(
+            AuditFinding(
+                category="quality",
+                severity="medium",
+                title="CI workflow missing",
+                detail="No GitHub Actions workflow directory detected.",
+                recommendation="Add CI for lint, tests, and packaging checks on pull requests.",
+            )
+        )
+
+    if not (project_path / "SECURITY.md").exists():
+        findings.append(
+            AuditFinding(
+                category="security",
+                severity="high",
+                title="No security policy file",
+                detail="SECURITY.md file is missing.",
+                recommendation="Publish a security policy with disclosure contact and supported versions.",
+            )
+        )
+
+    if not (project_path / "pyproject.toml").exists():
+        findings.append(
+            AuditFinding(
+                category="quality",
+                severity="high",
+                title="Missing pyproject.toml",
+                detail="Project metadata and tooling configuration are missing.",
+                recommendation="Adopt pyproject.toml and define lint/test/type/audit tool configs.",
+            )
+        )
+
+    if not any((project_path / f).exists() for f in ("poetry.lock", "requirements.txt", "requirements.lock", "uv.lock")):
+        findings.append(
+            AuditFinding(
+                category="security",
+                severity="medium",
+                title="Dependency lockfile/constraints missing",
+                detail="No dependency lockfile or pinned requirements file detected.",
+                recommendation="Add a lockfile or pinned requirements to improve supply-chain reproducibility.",
+            )
+        )
+
+    has_cov_config = (project_path / ".coveragerc").exists()
+    if (project_path / "pyproject.toml").exists():
+        text = (project_path / "pyproject.toml").read_text(encoding="utf-8", errors="ignore")
+        has_cov_config = has_cov_config or "[tool.coverage." in text
+    if not has_cov_config:
+        findings.append(
+            AuditFinding(
+                category="quality",
+                severity="low",
+                title="Coverage policy missing",
+                detail="No coverage configuration found to enforce quality thresholds.",
+                recommendation="Configure coverage and enforce a minimum threshold in CI.",
+            )
+        )
+
+    return findings
+
+
+def build_upgrade_plan(project_path: Path, findings: list[AuditFinding]) -> str:
+    lines = [
+        f"# Project Upgrade Plan ({project_path.name})",
+        "",
+        "## Phase 1 — Trust & Security",
+        "1. Add API abuse tests for validation and path restrictions.",
+        "2. Add regression tests for secret redaction and output safety.",
+        "",
+        "## Phase 2 — Engineering Quality",
+        "1. Introduce CI (tests + static checks).",
+        "2. Add baseline test coverage for CLI/web flows.",
+        "",
+        "## Phase 3 — Star-worthy Productization",
+        "1. Ship polished demo assets and usage GIFs.",
+        "2. Publish contribution guide + issue templates.",
+        "",
+        "## Current Findings",
+    ]
+    if not findings:
+        lines.append("- No major structural gaps detected by baseline audit.")
+    else:
+        for item in findings:
+            lines.append(
+                f"- [{item.severity.upper()}] {item.title}: {item.detail} → {item.recommendation}"
+            )
+    lines.append("")
+    return "\n".join(lines)

project_prompter/cli.py

@@ -222,6 +222,11 @@ def create_parser() -> argparse.ArgumentParser:
         action="version",
         version=f"%(prog)s {__version__}",
     )
+    parser.add_argument(
+        "--plan",
+        action="store_true",
+        help="Run repository audit and generate a practical upgrade plan.",
+    )
 
     return parser
 
@@ -306,6 +311,9 @@ def main() -> int:
         print("\nError: project_path is required unless --ui is specified.", file=sys.stderr)
         return 1
 
+    if args.plan:
+        return _run_plan(args)
+
     # Validate conflicting flags
     error = _validate_flags(args)
     if error:
@@ -393,6 +401,32 @@ def _clear_cache_only(args: argparse.Namespace) -> int:
     return 0
 
 
+def _run_plan(args: argparse.Namespace) -> int:
+    """Run repo audit and generate an actionable plan markdown file."""
+    from .audit import build_upgrade_plan, run_repo_audit
+
+    project_path = Path(args.project_path).resolve()
+    if not project_path.exists() or not project_path.is_dir():
+        print(f"Error: invalid project path: {project_path}", file=sys.stderr)
+        return 1
+
+    findings = run_repo_audit(project_path)
+    plan = build_upgrade_plan(project_path, findings)
+    output_path = Path(args.output).resolve()
+    output_path.mkdir(parents=True, exist_ok=True)
+    plan_file = output_path / "upgrade_plan.md"
+    plan_file.write_text(plan, encoding="utf-8")
+
+    print("Repository audit complete.")
+    print(f"Findings: {len(findings)}")
+    print(f"Plan file: {plan_file}")
+    if findings:
+        print("\nTop issues:")
+        for item in findings:
+            print(f"- [{item.severity}] {item.title}")
+    return 0
+
+
 def _start_ui(args: argparse.Namespace) -> int:
     """Start the local web UI."""
     try:

project_prompter/web.py

@@ -15,7 +15,7 @@
     from fastapi.middleware.cors import CORSMiddleware
     from fastapi.responses import FileResponse, HTMLResponse, JSONResponse
     from fastapi.staticfiles import StaticFiles
-    from pydantic import BaseModel
+    from pydantic import BaseModel, Field
     import uvicorn
     WEB_AVAILABLE = True
 except ImportError:
@@ -25,11 +25,15 @@
 from .mode_config import MODE_DEFAULTS, get_mode_defaults
 from .models import ScanOptions
 from .ollama_client import list_ollama_models, check_ollama_available, validate_ollama_url
+from .web_services import build_file_previews
+from .web_security import enforce_analyze_rate_limit, validate_extra_ignore_dirs
 
 # In-memory scan store
 _scans: Dict[str, Dict[str, Any]] = {}
 MAX_SCANS = 100
 _SCAN_EVICTION_BATCH = 10
+MAX_PREVIEW_CHARS_PER_FILE = 40_000
+MAX_TOTAL_PREVIEW_CHARS = 500_000
 
 STATIC_DIR = Path(__file__).parent / "static"
 ALLOWED_SCAN_ROOT_ENV = "ALLOWED_SCAN_ROOT"
@@ -49,13 +53,13 @@ class AnalyzeRequest(BaseModel):
         mode: Literal["fast", "balanced", "deep"] = "fast"
         model: str = "qwen2.5-coder:1.5b"
         ollama_url: str = "http://localhost:11434"
-        max_files: Optional[int] = None       # None = use mode default
-        max_chars_per_file: Optional[int] = None  # None = use mode default
+        max_files: Optional[int] = Field(default=None, ge=1, le=500)       # None = use mode default
+        max_chars_per_file: Optional[int] = Field(default=None, ge=100, le=200_000)  # None = use mode default
         use_ollama: bool = False
         target_model: str = "all"
         use_cache: bool = True
         clear_cache: bool = False
-        extra_ignore_dirs: List[str] = []
+        extra_ignore_dirs: List[str] = Field(default_factory=list, max_length=200)
 else:
     AnalyzeRequest = None  # type: ignore
 
@@ -281,13 +285,25 @@ async def mode_defaults():
     async def analyze(request: AnalyzeRequest, background_tasks: BackgroundTasks):
         """Start a project analysis scan."""
         try:
+            enforce_analyze_rate_limit()
             project_path, output_path, ollama_url = _validate_analysis_inputs(request)
         except ValueError as exc:
-            raise HTTPException(status_code=400, detail=str(exc)) from exc
+            message = str(exc)
+            if message.startswith("rate limit exceeded:"):
+                retry_after = "60"
+                if "|" in message:
+                    message, retry_after = message.split("|", 1)
+                raise HTTPException(
+                    status_code=429,
+                    detail=message,
+                    headers={"Retry-After": retry_after},
+                ) from exc
+            raise HTTPException(status_code=400, detail=message) from exc
 
         request.project_path = str(project_path)
         request.output_path = str(output_path)
         request.ollama_url = ollama_url
+        request.extra_ignore_dirs = validate_extra_ignore_dirs(request.extra_ignore_dirs)
 
         _evict_old_scans()
         scan_id = str(uuid.uuid4())[:12]
@@ -363,6 +379,7 @@ def progress(msg: str) -> None:
 
     try:
         project_path, output_base_path, ollama_url = _validate_analysis_inputs(request)
+        request.extra_ignore_dirs = validate_extra_ignore_dirs(request.extra_ignore_dirs)
         output_path = output_base_path / scan_id
         mode = request.mode
         defaults = get_mode_defaults(mode)
@@ -413,13 +430,11 @@ def progress(msg: str) -> None:
                     outputs[rel] = str(f)
 
         # Read file contents for preview
-        file_contents = {}
-        for rel_path, abs_path in outputs.items():
-            try:
-                content = Path(abs_path).read_text(encoding="utf-8")
-                file_contents[rel_path] = content
-            except Exception:
-                file_contents[rel_path] = "(could not read file)"
+        file_contents, previews_truncated = build_file_previews(
+            outputs=outputs,
+            per_file_limit=MAX_PREVIEW_CHARS_PER_FILE,
+            total_limit=MAX_TOTAL_PREVIEW_CHARS,
+        )
 
         scan["status"] = "completed"
         scan["completed_at"] = datetime.now(timezone.utc).isoformat()
@@ -434,12 +449,18 @@ def progress(msg: str) -> None:
         }
         scan["redaction_count"] = len(analysis.redaction_findings)
         scan["files_scanned"] = analysis.scan_metadata.files_scanned if analysis.scan_metadata else 0
+        scan["preview_truncated"] = previews_truncated
 
-    except Exception as e:
+    except ValueError as e:
         scan["status"] = "failed"
         scan["error"] = str(e)
         scan["completed_at"] = datetime.now(timezone.utc).isoformat()
         progress(f"✗ Analysis failed: {e}")
+    except Exception as e:
+        scan["status"] = "failed"
+        scan["error"] = "Analysis failed. Check server logs for details."
+        scan["completed_at"] = datetime.now(timezone.utc).isoformat()
+        progress(f"✗ Analysis failed: {e}")
 
 
 def _fallback_html() -> str:

project_prompter/web_routes.py

@@ -0,0 +1,8 @@
+"""Route-level helpers for web API composition."""
+
+from __future__ import annotations
+
+HEALTH_PATH = "/api/health"
+ANALYZE_PATH = "/api/analyze"
+RESULTS_PATH = "/api/results/{scan_id}"
+DOWNLOAD_PATH = "/api/download/{scan_id}/{filename:path}"