diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..6441710 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Thai Napires + +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. diff --git a/README.md b/README.md index e561197..fd9fd71 100644 --- a/README.md +++ b/README.md @@ -1,43 +1,203 @@ -### Git Fusion 🐱🦊 +# Git Fusion -![scr-gitfusion](https://github.com/user-attachments/assets/74ffba42-7f8f-465d-b18f-ad364412a995) +![Git Fusion Preview](./public/images/gitfusion-readme-preview.png) +Git Fusion is a Next.js app that brings GitHub and GitLab activity into one authenticated dashboard. Users can sign up, connect their provider accounts through OAuth, and view consolidated contribution insights without relying on personal access tokens in the browser. More providers are planned to the future. -### šŸš€ Try out Git Fusion: [https://gitfusion.vercel.app](https://gitfusion.vercel.app) +Try it out: [https://gitfusion.vercel.app](https://gitfusion.vercel.app) -Git Fusion is a tool that seamlessly combines contribution data from GitHub and GitLab into a unified, interactive graph. Whether you're an open-source enthusiast, a professional developer, or managing multiple repositories across platforms, Git Fusion provides a clear, comprehensive view of your coding activity. +## Features -> Stay on top of your development journey with Git Fusion—because your work deserves to be seen, no matter where you code. +- Supabase authentication with sign in and sign up pages. +- Authenticated dashboard for connected GitHub and GitLab accounts. +- OAuth-based provider connection and disconnection flows. +- Consolidated contribution overview across providers. +- Dashboard metrics, contribution chart, repository highlights, and recent activity. +- Profile settings with avatar upload through Supabase Storage. +- Cached dashboard overview backed by persisted daily contribution totals. +- Server-side token handling with encrypted provider tokens. -#### Key Features +## Tech Stack -- Unified Contribution Graph: Merge and visualize your contributions from GitHub and GitLab in one place. -- Cross-Platform Insights: Track your commits numbers from both platforms. -- Developer-Focused: Built for developers who want a centralized view of their contributions without switching between platforms. +- [Next.js](https://nextjs.org/) 15 +- [React](https://react.dev/) 19 +- [Supabase](https://supabase.com/) for auth, database, and avatar storage +- [HeroUI](https://www.heroui.com/) and Tailwind CSS for UI +- [TanStack Query](https://tanstack.com/query) for client-side data fetching +- [Framer Motion](https://www.framer.com/motion/) for animation -#### Possible future features: +## Getting Started -### Possible Future Features +### 1. Install dependencies -- **Customizable Views**: Filter contributions by repository, time range, or platform to better analyze your work. -- **User Profiles**: Integrate with GitHub/GitLab user profiles to display additional details about contributions. -- **Automated Reports**: Generate daily, weekly, or monthly reports summarizing your contributions. -- **Authentication**: Add a user login/register so there's no need to always type the profile usernames to request again. +```bash +npm install +``` + +### 2. Configure environment variables + +Copy the example file and fill in the required values: + +```bash +cp .env.local.example .env.local +``` + +Required variables: + +```env +NEXT_PUBLIC_SUPABASE_URL= +NEXT_PUBLIC_SUPABASE_ANON_KEY= + +SUPABASE_SERVICE_ROLE_KEY= + +GITHUB_OAUTH_CLIENT_ID= +GITHUB_OAUTH_CLIENT_SECRET= +GITLAB_OAUTH_CLIENT_ID= +GITLAB_OAUTH_CLIENT_SECRET= + +# Recommended for production token encryption +GITFUSION_TOKEN_ENCRYPTION_KEY= +``` + +Notes: + +- `NEXT_PUBLIC_SUPABASE_URL` and `NEXT_PUBLIC_SUPABASE_ANON_KEY` are public client-side Supabase values. +- `SUPABASE_SERVICE_ROLE_KEY` must stay server-side only. +- `GITFUSION_TOKEN_ENCRYPTION_KEY` should be a long, stable random string. Do not rotate it after users connect accounts unless you are prepared to invalidate/reconnect encrypted provider tokens. +- Use the exact variable name `GITFUSION_TOKEN_ENCRYPTION_KEY` in every environment. If production and local use different encryption keys, existing connected accounts may need to be reconnected. +- If `GITFUSION_TOKEN_ENCRYPTION_KEY` is not set, the app falls back to `SUPABASE_SERVICE_ROLE_KEY` for token encryption, but a dedicated key is recommended. + +### 3. Configure Supabase + +Create a Supabase project, then link it locally: + +```bash +npm run supabase:link +``` + +Apply the database migrations: + +```bash +npm run supabase:push +``` + +The migrations create: + +- `profiles` +- public `avatars` storage bucket +- `connected_accounts` +- `oauth_states` +- `dashboard_overview_cache` +- `sync_runs` +- `contribution_daily_totals` +- required RLS policies, grants, indexes, and triggers + +### 4. Configure OAuth apps + +Create OAuth applications for GitHub and GitLab, then add their client IDs and secrets to `.env.local`. + +Use these callback URLs: + +```txt +http://localhost:3000/api/integrations/github/callback +http://localhost:3000/api/integrations/gitlab/callback +``` -#### Setup +For production, replace the origin with your deployed domain: -1. Installation -```sh -npm i +```txt +https://your-domain.com/api/integrations/github/callback +https://your-domain.com/api/integrations/gitlab/callback ``` -2. Copy the contents of ```.env.local.example``` into a new file called ```.env.local``` and add your GitHub access token. +Provider scopes used by the app: -2. Usage -```sh +- GitHub: `read:user user:email` +- GitLab: `read_user read_api` + +### 5. Run the app + +```bash +npm run dev +``` + +Open [http://localhost:3000](http://localhost:3000). + +## Scripts + +```bash npm run dev +npm run build +npm run start +npm run lint +npm run typecheck +npm run test +npm run test:run +npm run ci +npm run supabase:link +npm run supabase:push ``` -### Credits +## Testing and CI + +The project uses Vitest for focused server/API tests. The current suite covers: + +- `/api/integrations/accounts` account listing and disconnect behavior +- `/api/dashboard/overview` authorization, refresh handling, and known application errors +- provider token encryption/decryption behavior, including mismatched encryption keys + +Run the tests locally: + +```bash +npm run test:run +``` + +Run the same verification chain used by CI: + +```bash +npm run ci +``` + +The CI workflow in `.github/workflows/pr-checks.yml` runs on pull requests targeting `main` and on pushes to `main`. It installs dependencies with `npm ci`, then runs lint, typecheck, tests, and the production build. + +## Project Structure + +```txt +src/app Next.js routes and API handlers +src/components Shared UI components +src/lib Client/server utilities and provider helpers +src/server Server-side services, repositories, and domain modules +src/types Shared TypeScript types +supabase/migrations Database schema migrations +``` + +## Dashboard Data Flow + +The dashboard overview is loaded through `/api/dashboard/overview`. + +The server attempts to use data in this order: + +1. Fresh `dashboard_overview_cache` +2. Stored `contribution_daily_totals`, when accounts have a recent sync +3. Provider APIs, followed by persistence of daily totals and cache refresh + +Provider tokens are stored encrypted in Supabase and are never returned to the frontend. + +## Deployment Notes + +- Configure public variables as regular config values: + - `NEXT_PUBLIC_SUPABASE_URL` + - `NEXT_PUBLIC_SUPABASE_ANON_KEY` + - `GITHUB_OAUTH_CLIENT_ID` + - `GITLAB_OAUTH_CLIENT_ID` +- Configure sensitive values as secrets: + - `SUPABASE_SERVICE_ROLE_KEY` + - `GITFUSION_TOKEN_ENCRYPTION_KEY` + - `GITHUB_OAUTH_CLIENT_SECRET` + - `GITLAB_OAUTH_CLIENT_SECRET` +- Apply Supabase migrations before connecting production accounts. +- Make sure production OAuth callback URLs match the deployed domain exactly. + +## License -Git Fusion is inspired by the Contra project, which you can find [here](https://github.com/ahmetkorkmaz3/contra). Contra was built with Vue.js, but I decided to reimagine it using Next.js. Also, I used Typescript to add more code clarity and maintainability. In addition to the framework shift, I made enhancements to the UI and adapted various elements for React, including integrating a new library for calendar contributions. There’s more to come as I continue to enhance this project! +This project is licensed under the MIT License. \ No newline at end of file diff --git a/package.json b/package.json index 6d5137f..83f9286 100644 --- a/package.json +++ b/package.json @@ -43,5 +43,6 @@ "tailwindcss": "^4", "typescript": "^5", "vitest": "^2.1.9" - } + }, + "license": "MIT" } diff --git a/public/images/gitfusion-readme-preview.png b/public/images/gitfusion-readme-preview.png new file mode 100644 index 0000000..1fed789 Binary files /dev/null and b/public/images/gitfusion-readme-preview.png differ