feat(shared): add shared package with grouping logic and models

- Created a new shared package with package.json and TypeScript configuration.
- Implemented domain grouping and purity calculation functions in grouping.ts.
- Defined various data models using Zod schemas in models.ts.
- Added TypeScript build configuration for the shared package.

test(e2e): add end-to-end tests for extension functionality

- Implemented tests for real extension popup authentication and session saving.
- Created full workflow tests to validate API interactions and session management.
- Added grouping tests to ensure correct domain grouping logic.
- Included integration tests for server API endpoints and security checks.

test(unit): add unit tests for grouping logic and schemas

- Added unit tests for domain grouping and purity functions.
- Implemented schema validation tests for session schema using Zod.

chore: add uploads for testing file upload functionality

- Added sample files for testing file upload and download features.

chore: update tsconfig for multi-package workspace

- Configured root tsconfig.json to reference shared and server packages.

Author: dragonscypher

.env.example

@@ -0,0 +1,14 @@
+# Environment configuration for Groupem
+# Copy to .env and adjust values as needed.
+
+# Server listening port (auto-increments if busy)
+PORT=8080
+
+# JWT signing secret (change in production!)
+JWT_SECRET=change-me-dev-secret
+
+# SQLite database URL for Prisma
+DATABASE_URL="file:./dev.db"
+
+# External ML service base URL (FastAPI service). If unreachable, server/extension fallbacks kick in.
+ML_URL=http://localhost:8000

.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  build-test:
+    runs-on: ubuntu-latest
+    services:
+      ml:
+        image: python:3.11
+        env: {}
+        ports:
+          - 8000:8000
+        options: >-
+          --health-cmd "curl -f http://localhost:8000/health || exit 1" --health-interval 10s --health-retries 5 --health-timeout 5s
+        command: ["bash", "-c", "pip install fastapi uvicorn scikit-learn numpy sentence-transformers hdbscan bs4 cachetools && uvicorn app.main:app --host 0.0.0.0 --port 8000 --app-dir ml-service/app"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install node deps
+        run: npm install
+      - name: Install python deps (for local ml usage)
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r ml-service/requirements.txt || true
+      - name: Build packages
+        run: npm run build
+      - name: Run tests
+        run: npm test
+      - name: Playwright Browsers
+        run: npx playwright install --with-deps chromium
+      - name: Run E2E (headless)
+        env:
+          ML_URL: http://localhost:8000
+        run: npx playwright test --project=chromium || true

.gitignore

@@ -0,0 +1,12 @@
+node_modules/
+dist/
+build/
+.env
+*.log
+.prisma/
+coverage/
+.playwright-cache/
+playwright-report/
+ml-service/.venv/
+ml-service/__pycache__/
+ml-service/.mypy_cache/

CONTRIBUTING.md

@@ -0,0 +1,68 @@
+# Contributing to Groupem
+
+## Development Environment
+1. Clone repo and install dependencies:
+```powershell
+npm install
+```
+2. Generate Prisma client:
+```powershell
+cd mcp-server
+npx prisma generate
+cd ..
+```
+3. Copy `.env.example` to `.env` and adjust.
+4. (Optional) Start ML service:
+```powershell
+cd ml-service
+python -m venv .venv
+. .venv/Scripts/Activate.ps1
+pip install -r requirements.txt
+uvicorn app.main:app --port 8000
+```
+5. Run server + ML concurrently:
+```powershell
+npm run dev
+```
+6. Build extension:
+```powershell
+npm -w extension run build
+```
+
+## Scripts Overview
+- `npm run dev:mcp` – MCP server (ts-node-dev)
+- `npm run dev:ml` – FastAPI ML service
+- `npm run dev` – Concurrent server + ML
+- `npm run build` – Build shared libs, server, extension
+- `npm test` – Unit/integration tests
+- `npm run test:e2e` – Playwright tests
+
+## Code Style
+- TypeScript strictness maintained; avoid unnecessary any.
+- Keep functions small and purposeful.
+- Do not commit generated `dist/` except for packaged extension release branches.
+
+## Security & Secrets
+- Never commit real secrets. `.env` is ignored.
+- Rotate `JWT_SECRET` for production deployments.
+
+## Pull Requests
+- Include description & rationale.
+- Ensure `npm test` passes locally.
+- Run `npm -w shared run build` if modifying shared models.
+
+## Commit Messages
+Follow conventional style (recommended):
+- `feat: add X`
+- `fix: correct Y`
+- `docs: update README`
+- `refactor: simplify Z`
+
+## Testing Guidance
+- Add unit tests for new utilities.
+- Extend Playwright E2E if UI flows change.
+
+## Issue Reporting
+Include reproduction steps, expected vs actual behavior, and environment (OS, Node, Python versions).
+
+Happy hacking!

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Groupem Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,90 @@
+# Groupem
+
+Cross-browser tab grouping extension with secure MCP server and optional ML microservice.
+
+## Components
+- Extension (Chrome/Firefox) in `extension/`
+- MCP Server (Node/TypeScript + Prisma + SQLite) in `mcp-server/`
+- ML Service (FastAPI) in `ml-service/`
+- Shared models in `shared/`
+
+## Quick Start (PowerShell)
+```powershell
+# Install root deps
+npm install
+
+# Generate Prisma client
+setx DATABASE_URL "file:./dev.db"
+cd mcp-server; npx prisma generate; cd ..
+
+# Run server (port 8080 default; will auto-increment if busy)
+# Optionally set explicit port
+$env:PORT=8080; npm run dev:mcp
+
+# Run extension build (dev)
+cd extension; npm run dev
+```
+
+## ML Service
+```powershell
+cd ml-service
+python -m venv .venv
+. .venv/Scripts/Activate.ps1
+pip install -r requirements.txt
+uvicorn app.main:app --reload --port 8000
+
+### Health
+MCP server exposes `GET /ml/health` reflecting reachability of `ML_URL` (default `http://localhost:8000`).
+Set a custom ML URL:
+```powershell
+$env:ML_URL="http://localhost:9000"; npm run dev:mcp
+```
+If unreachable, embeddings in extension fall back to:
+1. (Future) Local ONNX model (placeholder)
+2. Server-side TF-IDF stub
+Check server logs for: `ML service unreachable at ...`.
+
+### Ports
+Server attempts desired `$env:PORT` (default 8080) then increments up to 10 times if occupied.
+Use `/` root route for basic health and `/ml/health` for ML status.
+
+## Environment Variables
+See `.env.example` for documented defaults:
+- `PORT` – MCP server port (auto-increment fallback)
+- `JWT_SECRET` – Signing key (change for production)
+- `DATABASE_URL` – Prisma SQLite path
+- `ML_URL` – Base URL for ML microservice
+
+## CI
+GitHub Actions workflow (`.github/workflows/ci.yml`) installs dependencies, builds all packages, runs tests, and executes a Chromium Playwright project (soft-fail for E2E).
+
+## Contributing
+See `CONTRIBUTING.md` for guidelines, scripts, and commit style.
+
+## Release Checklist
+- Update version numbers (extension + server) if public release.
+- Run `npm run build` and `npm test`.
+- Tag release: `git tag -a vX.Y.Z -m "Release vX.Y.Z"; git push --tags`.
+- Upload packaged extension (zip `extension/dist`).
+```
+
+## Tests
+```powershell
+# (After installing deps) build shared & server
+npm -w shared run build
+npm -w mcp-server run build
+npm test
+```
+
+## Security Notes
+- Argon2id used for password hashing.
+- AES-GCM encryption of sessions and storage with per-user random key unwrapped at login (kept in-memory only).
+- TOTP enrollment and verification endpoints provided.
+- Simplified WebAuthn (mock) endpoints included; not production secure.
+- Registration now supports optional `phone` and automatic TOTP secret provisioning (returned in `totpSecret`). Store it in an authenticator app to use during login.
+
+## Embeddings
+Current implementation uses a simple TF-IDF style embedding in the server; ML service provides higher quality embeddings & clustering if integrated via future enhancement.
+
+## Disclaimer
+This repository is a functional baseline but additional hardening, full WebAuthn ceremony, and production deployment considerations (HTTPS, key management) are required before production use.

extension/flattenHtml.mjs

@@ -0,0 +1,19 @@
+import { promises as fs } from 'fs';
+import { resolve } from 'path';
+
+async function run() {
+    const dist = resolve('./dist/src');
+    const root = resolve('./dist');
+    for (const name of ['popup.html', 'options.html']) {
+        const from = resolve(dist, name);
+        try {
+            await fs.access(from);
+            const to = resolve(root, name);
+            await fs.copyFile(from, to);
+            console.log('Copied', from, '->', to);
+        } catch {
+            // ignore if not exists
+        }
+    }
+}
+run();

extension/groupem-extension.zip

@@ -0,0 +1,24 @@
+{
+    "name": "groupem-extension",
+    "version": "1.0.0",
+    "private": true,
+    "scripts": {
+        "build": "vite build && node ./flattenHtml.mjs",
+        "dev": "vite",
+        "pack": "npm run build && powershell -NoLogo -Command Compress-Archive -Path dist/* -DestinationPath groupem-extension.zip -Force",
+        "test": "echo 'No extension tests yet'"
+    },
+    "dependencies": {
+        "react": "18.2.0",
+        "react-dom": "18.2.0",
+        "webextension-polyfill": "^0.10.0",
+        "onnxruntime-web": "^1.18.0"
+    },
+    "devDependencies": {
+        "typescript": "^5.4.5",
+        "@types/react": "^18.2.21",
+        "@types/react-dom": "^18.2.7",
+        "vite": "^5.2.0",
+        "@vitejs/plugin-react": "^4.2.1"
+    }
+}

extension/package.json

@@ -0,0 +1,4 @@
+// Content script to ping background and ensure MV3 service worker wakes.
+try {
+    chrome.runtime?.sendMessage?.({ type: 'groupem-activate' });
+} catch { }