Proposal to add a WebApp for Repo Report

[CapriciousRebel]

Currently, Repo report is a cli-only tool. Having the tool in the CLI itself is great for the user who loves to live in the terminal. However, displaying tables with multiple columns in the terminal breaks the UI when the columns overflow. Following are a few examples (tested on macOS terminal):

1. Overflowing columns for the default run command with no options passed.

   

2. Overflowing columns for the run command with the --all option.

   

It is very difficult to be able to read what each tick represents without scrolling all the way to the top to see what column does the tick belongs to.

3. Expanding the terminal to full screen does help slightly, but the columns still overflow.

   

4. The only viable solution to this is by reducing the text size/zooming out of the terminal, but that makes the text too small to read.

   

I propose we create a single-page, responsive web application for repo-report using the latest frontend development tools. Following is a rough markup of the UI I feel would work the best for this use case (note that I am not a designer, and this is just an example of how I imagine the UI/UX):

Features:

• Ability to run commands via the on-screen terminal or choosing the required command from the dropdown and clicking the run button.
• Ability to scroll through the table of results (the top row and left column will remain visible at all times during scrolling so that the user does not have to scroll back to see what a particular tick is representing).
• It's responsive and can be used via mobile as well, this will be helpful for a user who wants to use repo-report while traveling or in any other situation where they don't have access to a desktop.

Things that need to be discussed further:

• [ ] Tech Stack to be used for the frontend.
• [ ] Strategies to convert the current implementation to a web app.
• [ ] Exploring the GitHub API to see if there is an ability to fetch a user's personal access token via Oauth for a better UX.
• [ ] UI/UX design.

[ljharb]

This sounds great.

Let's maybe start by adding an option to generate HTML locally, and then figure out how to make it easy for folks to consume. Since this requires an API token, it would probably need to be a forked github repo with a cron action that deploys to github pages - which would mean we'd need to make another repo so that people could fork it.

[CapriciousRebel]

I like the idea of starting with an option to generate the HTML locally, that would be good for a quick POC. However making a repo that needs to be forked by users and running on GitHub actions to use sounds like a tedious user experience, also, having people run a GitHub action every time they try to run a command sounds quite slow to me.

I propose we go with the following flow:

1. [User downloads repo-report and installs the cli]
2. [User runs a command like repo-report --gui]
3. [If the personal access token is missing, a prompt is made to copy-paste it in the terminal]
4. [The web app opens up on the browser, say, on http://localhost:5009 where the user is now fully authenticated]

The user can choose to use repo-report as a cli-only app at step-2.

[CapriciousRebel]

In order to generate the webapp on the system, we could use the following tech stack:

Backend:

• Server: expressJS: (unpacked: 208 kB) to build a wrapper around existing repo-report codebase and provide an API.

Frontend:

• TailwindCSS: (production build size ~2KB ) for rapidly generating lightweight styling for the webpage.
• axios: (unpacked: 388 kB) to make promise-based HTTP requests to the expressJS server.
• ReactJS: (unpacked: 291 kB) to generate component-based UI with multiple useful features like react-hooks, state management right out of the box, which will make the development much straightforward and not force us to reinvent the wheel.

[rosekamallove]

Hey If you'd like a partner to work on this, I am up for working on the web app! @CapriciousRebel hmu.

[CapriciousRebel]

@rosekamallove Of course! I would love that.

[rosekamallove]

Can we probably stup a meet or something?

[CapriciousRebel]

Sure, let's move the scheduling discussion to discord channel!

[rosekamallove]

Since there is going to be a backend in the web app we can also add the ability to edit those metrics from the dashboard itself. It would save to hassle to find that repo on GH and then edit the metric.

Opinion required @ljharb

[ljharb]

I don’t think it’d be very scalable to run a backend for this - and since GitHub api tokens are unique to users and also have points quotas, the web app has to be able to make requests on a user’s behalf. I’m not sure logging in with GitHub provides this or not - but GitHub actions does.

With the the forked repo approach, the action would be a cron - meaning, it automatically runs on a schedule (once every 10 minutes, say) without any user action.

[CapriciousRebel]

My issue with cron job actions is that it updates once at every time interval, so say, I open the portal, find an issue, solve the issue. Now I have to wait for the cron to update the page for me. Instead, I would prefer the update to happen instantly on refresh or live( using a webhook maybe :D ). Perhaps Instead of writing an entire backend, we can always write APIs that talk to the GitHub API from the frontend itself. The personal access token could be taken as an input and stored safely in the browser storage (perhaps as a cookie)

[ljharb]

Requiring a user to manually provide an API token to a webpage, and then potentially storing it unsafely (if the computer is shared, for example) seems tricky.

That's a fair point that you'd have to wait for it to refresh to get new results.

[CapriciousRebel]

We can always ask the user a prompt "Remember me?" User says yes => store as a cookie User says no => store as a session variable

[CapriciousRebel]

Summary of our last meeting:

The best approach would be to implement this functionality in stages as follows: Stage 1: Implement static webpage generation:

• User runs the repo report command with the corresponding options on the terminal.
• A static webpage is generated in the form of HTML/CSS files.
• The user can view the UI on a browser
• The user cannot interact with repo-report via the webpage but has to run the command in the terminal each time to generate the UI.

Stage 2: Implement dynamic webpage:

• User runs the repo report command with a command to use the GUI example: repo-report --gui.
• A webpage opens up in the browser on the localhost.
• User can run commands via the web page and the UI updates in real-time.
• A wrapper needs to be written over the current codebase of repo-report to expose a lightweight server(expressJS) that provides an API over repo-report to the frontend.

Both of these cases use the token saved in the environment variables and thus eliminate any browser-storage-based security risks discussed above and in the meeting.

For stage 3 we could explore building repo-report as a third-party app, deployed on a domain that works via the GitHub OAuth flow and provides a one-stop destination for users to use repo-report, but of course, providing repo-report as a service would involve deployment costs, security risks, regular maintenance, and other costs as well.

[ljharb]

I'd actually have 4 stages - stage 2 is "implement a static webserver", and stage 3 is "make that webserver dynamic", and then stage 4 is a hosted solution.