VERIFICATION.md — profileShare

This document describes what "done" looks like for profileShare and how a coding agent should verify it. It is based only on the specification interview. Where the developer explicitly left a decision open, this is noted rather than assumed.

Purpose

profileShare lets a developer share a read-only overview of selected GitHub projects (including private ones) via a link, without making repositories public or adding viewers as collaborators. Viewers are primarily potential hiring managers. The link works for a limited time period, then expires.

The core goal, restated by the developer: "an overview of my code." Nothing more complex.

Definition of Done

The project is done when all of the following behaviors hold.

1. Connecting to GitHub and selecting repositories

• The owner can authenticate with their GitHub account and grant access.
• Access is granted only to the repositories the owner points to, not to all repositories. [S19]
• The owner sees their repositories and can click to select which ones to share. [S9]

2. Creating a share link

• The owner selects specific repositories and generates a simple URL to share. [S9]
• The owner can set a time period for how long the link is valid (e.g. 7 days), and this period is customizable. [S9]
• The shared content is a snapshot taken at the moment the link is created — it does not update as the source repositories change. [S15]

3. Viewing a shared link (no account required)

• A viewer can open the link without needing a GitHub account. [S5]
• Anyone with the link can open it while it is valid; there is no per-person restriction, and forwarding the link is acceptable. [S23]
• The landing page is the owner's profile page. [S39]

4. Profile page contents

The profile page shows GitHub-style basic profile information and the list of selected projects. Supported items mentioned: name, photo, short bio, and the list of projects; profile activity is also desirable. [S12][S3]

• From the profile page, the viewer clicks a repository to open it. [S39]

5. Inside a project

• The viewer can browse the project's files, opening a file by name to read the code on screen. [S44]
• Folders (including nested folders) can be opened to find files. [S44][S45]
• The viewer can see the project's commit history: a list of what changed and when. [S42]
• If feasible, a commit should be clickable to show which lines changed. [S43]

6. Navigation

• A button at the top returns the viewer to the profile page. [S47]
• The viewer can step back up through nested folders and back out of a project. [S48][S38]

7. Expiration

• When a link is opened after its time period has ended, the viewer sees a simple message that the URL is expired. [S21]

Explicitly Out of Scope

Do not implement these:

• Comments. [S31]
• Downloading code. [S31]
• Editing by the viewer. [S32]
• A full clone of all GitHub functionality — only an overview. [S32][S33]
• Per-recipient access control / preventing link forwarding. [S23]
• Live/continuously-updating content (snapshot only). [S15]

Open / Undecided Items (do not treat as requirements)

• Whether the tool supports only the owner or multiple sign-up users. [S7]
• Whether stored snapshots are deleted on expiry or retained. [S26][S27]
• Size, link-count, or performance limits — developer only said it should "work normally." [S25]
• Mobile support was not requested; viewing is oriented to a computer. [S28][S29]

How to Verify

Since automated commands are not specified in the interview, verification is primarily behavioral. A coding agent should provide runnable build/start commands and then confirm the behaviors below.

Build / run

• Provide and run the project's standard install and start commands (e.g. install dependencies, start the server).
• Confirm the app launches without errors and the owner can reach the GitHub authentication flow.

Manual acceptance walkthrough (owner's own check) [S34][S35][S36][S37]

The developer's own acceptance test is to open the generated link himself and confirm:

1. All the projects he selected appear — no more, no less. [S37]
2. All commits appear for those projects. [S37]

Extend this into the full check:

1. Repo selection & access scope

   • Authenticate with GitHub.
   • Confirm only the pointed-to repositories are accessed, not all repos. [S19]
   • Select specific repositories and generate a link.

2. Link generation

   • Confirm a simple shareable URL is produced.
   • Confirm a customizable expiration period can be set. [S9]

3. Snapshot behavior

   • After creating a link, change the source repository.
   • Reopen the link and confirm the page still shows the original snapshot, not the change. [S15]

4. Viewer experience (no login)

   • Open the link in a context without a GitHub session/account and confirm it loads. [S5]
   • Confirm the profile page shows at least name, photo, bio, and the selected project list. [S12]

5. Navigation into projects

   • From the profile, click a repository and confirm you enter it. [S39]
   • Open files (including files inside nested folders) and read code on screen. [S44][S45]
   • View the commit list (what changed and when). [S42]
   • If implemented, click a commit to view changed lines. [S43]
   • Use the top button to return to the profile. [S47]
   • Step back up through nested folders / out of a project. [S48]

6. Expiration

   • Open (or simulate opening) a link after its period ends.
   • Confirm a simple "URL is expired" message is shown and content is not served. [S21]

7. Out-of-scope confirmation

   • Confirm there is no comment feature, no download option, and no way for the viewer to edit content. [S31][S32]

Pass criteria

The build succeeds and starts; the owner can connect GitHub, select specific repos, generate a time-limited link showing a snapshot; a viewer without an account can browse the profile, projects, files (including nested folders), and commits, and navigate back to the profile; and an expired link shows the expired message. Comments, downloads, and editing are absent.