Merge pull request #3 from amkayondo/copilot/add-github-user-finder

[WIP] Add GitHub user finder for Uganda location

Author: amkayondo

.env.example

@@ -1,3 +1,4 @@
-# Copy this file to .env and fill in your GitHub Personal Access Token.
+# Copy this file to .env (or .env.local for Next.js) and fill in your
+# GitHub Personal Access Token.
 # A classic PAT with at least the public_repo scope is sufficient.
 GITHUB_TOKEN=ghp_your_token_here

.gitignore

@@ -2,3 +2,8 @@ node_modules/
 .env
 uganda_users.json
 uganda_users.csv
+
+# Next.js
+.next/
+out/
+next-env.d.ts

README.md

@@ -1,6 +1,6 @@
 # gitfast
 
-A Node.js script that finds GitHub users who appear to be in **Uganda** by searching GitHub's public API and exporting the results to `uganda_users.json` and `uganda_users.csv`.
+A **Next.js (App Router)** web app and CLI tool that discovers GitHub users who appear to be in **Uganda** using the GitHub API. Search, filter, review results, and download JSON/CSV.
 
 > **Note:** GitHub's `location` field is free-text and self-reported. Results are **best-effort** and may include false positives or miss users who haven't filled in their location.
 
@@ -28,7 +28,44 @@ cp .env.example .env
 
 ---
 
-## Usage
+## Web App (Next.js)
+
+Start the development server:
+
+```bash
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) to use the web UI.
+
+### Features
+
+- **Search form** — select cities, set min repos/followers, max pages, concurrency, and min confidence score
+- **Results table** — avatar, username, name, location, followers, repos, confidence score, profile link
+- **Client-side filters** — text search (login/name/bio), "has bio", "has company", "has blog", "has email"
+- **Sorting** — by score, followers, repos, or newest
+- **Download JSON / CSV** — export results as attachment files
+
+### API Endpoints
+
+| Method | Route | Description |
+|--------|-------|-------------|
+| `POST` | `/api/scrape` | Run a scrape with configurable parameters |
+| `GET` | `/api/export/json?runId=...` | Download JSON results |
+| `GET` | `/api/export/csv?runId=...` | Download CSV results |
+
+### Confidence Scoring
+
+Each user is assigned a score (0–100) based on their location:
+- **100** — location includes "uganda"
+- **85** — location includes "kampala"
+- **75** — other known Uganda cities
+- **50** — "UG" or "U.G." abbreviation
+- **0** — no match
+
+---
+
+## CLI Scraper
 
 ```bash
 npm start

app/api/export/csv/route.ts

@@ -0,0 +1,32 @@
+import { NextRequest, NextResponse } from "next/server";
+import { cacheGet } from "@/lib/cache";
+import { buildCsv } from "@/lib/csv";
+
+export async function GET(request: NextRequest) {
+  const runId = request.nextUrl.searchParams.get("runId");
+  if (!runId) {
+    return NextResponse.json(
+      { error: "Missing runId query parameter" },
+      { status: 400 }
+    );
+  }
+
+  const users = cacheGet(runId);
+  if (!users) {
+    return NextResponse.json(
+      { error: "Run not found or expired" },
+      { status: 404 }
+    );
+  }
+
+  const csv = buildCsv(users);
+
+  return new NextResponse(csv, {
+    status: 200,
+    headers: {
+      "Content-Type": "text/csv",
+      "Content-Disposition":
+        'attachment; filename="uganda_github_users.csv"',
+    },
+  });
+}

app/api/export/json/route.ts

@@ -0,0 +1,29 @@
+import { NextRequest, NextResponse } from "next/server";
+import { cacheGet } from "@/lib/cache";
+
+export async function GET(request: NextRequest) {
+  const runId = request.nextUrl.searchParams.get("runId");
+  if (!runId) {
+    return NextResponse.json(
+      { error: "Missing runId query parameter" },
+      { status: 400 }
+    );
+  }
+
+  const users = cacheGet(runId);
+  if (!users) {
+    return NextResponse.json(
+      { error: "Run not found or expired" },
+      { status: 404 }
+    );
+  }
+
+  return new NextResponse(JSON.stringify(users, null, 2), {
+    status: 200,
+    headers: {
+      "Content-Type": "application/json",
+      "Content-Disposition":
+        'attachment; filename="uganda_github_users.json"',
+    },
+  });
+}

app/api/scrape/route.ts

@@ -0,0 +1,62 @@
+import { NextResponse } from "next/server";
+import { scrapeUsers, ScrapeOptions } from "@/lib/github";
+import { cacheSet } from "@/lib/cache";
+import { ScrapeRequest, ScrapeResponse } from "@/lib/types/user";
+
+export async function POST(request: Request) {
+  let body: ScrapeRequest;
+  try {
+    body = await request.json();
+  } catch {
+    return NextResponse.json({ error: "Invalid JSON body" }, { status: 400 });
+  }
+
+  const {
+    locations = ["Uganda", "Kampala"],
+    minRepos = 0,
+    minFollowers = 0,
+    maxPagesPerQuery = 3,
+    perPage = 100,
+    concurrency = 5,
+    minScore = 50,
+  } = body;
+
+  if (!Array.isArray(locations) || locations.length === 0) {
+    return NextResponse.json(
+      { error: "locations must be a non-empty array" },
+      { status: 400 }
+    );
+  }
+
+  const opts: ScrapeOptions = {
+    locations,
+    minRepos,
+    minFollowers,
+    maxPagesPerQuery: Math.min(maxPagesPerQuery, 10),
+    perPage: Math.min(perPage, 100),
+    concurrency: Math.min(concurrency, 10),
+    minScore,
+  };
+
+  try {
+    const { users, totalCandidates, uniqueUsers } = await scrapeUsers(opts);
+
+    const runId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    cacheSet(runId, users);
+
+    const resp: ScrapeResponse = {
+      runId,
+      stats: {
+        totalCandidates,
+        uniqueUsers,
+        keptAfterFilter: users.length,
+      },
+      users,
+    };
+
+    return NextResponse.json(resp);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "Unknown error";
+    return NextResponse.json({ error: message }, { status: 500 });
+  }
+}

app/layout.tsx

@@ -0,0 +1,21 @@
+import type { Metadata } from "next";
+
+export const metadata: Metadata = {
+  title: "GitHub Uganda User Finder",
+  description:
+    "Discover GitHub users in Uganda — search, filter, and download JSON/CSV.",
+};
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body style={{ margin: 0, fontFamily: "system-ui, sans-serif" }}>
+        {children}
+      </body>
+    </html>
+  );
+}