Support for private repositories

[rocketstack-matt]

Implementation Plan

Depends on #10 (GitHub App Integration).

Context

The .roadmapper key approach fundamentally cannot work for private repos — the shared GITHUB_TOKEN PAT doesn't have access to arbitrary private repos. However, the GitHub App architecture from #10 already supports private repos: when a user installs the app on a private repo, the installation token has access to that repo's issues.

This plan extends #10 to remove the "public only" constraint, add the necessary permission, and improve error handling so users with private repos are guided toward installing the GitHub App.

---

Changes to Issue #10 Plan

1. Remove "public repos only" constraint

Current: Constraints say "Public repos only for now (permissions: issues:read, metadata:read)"

Updated: Remove that line. Replace with:

• Public and private repos supported via GitHub App (installation token has access to granted repos)
• Private repos require the GitHub App — the .roadmapper key approach only works for public repos

2. Add contents:read permission

Current: App permissions are issues:read, metadata:read

Updated: Add contents:read. This allows the installation token to read .roadmapper files from private repos, supporting users who have both the GitHub App installed AND a .roadmapper key (e.g., to use a paid tier).

Permission	Purpose
issues:read	Fetch issues for roadmap
contents:read	Read .roadmapper file from private repos (fallback verification)
metadata:read	Repo existence checks (implicit/default)

3. Improve error messages in lib/verify.js

Current: When fetchRoadmapperFile can't access a repo, verifyRepo returns "No .roadmapper file found in repository". Misleading for private repos — the file might exist but we can't see it.

Updated: After .roadmapper fallback fails, check if the GitHub App is configured and add guidance:

if (!keyContent) {
  const reason = isGitHubAppConfigured()
    ? 'No .roadmapper file found. If this is a private repository, install the Roadmapper GitHub App.'
    : 'No .roadmapper file found in repository';
  return { verified: false, reason };
}

4. Handle private repo registration in api/register.js

Current: Registration checks repo existence via GET /repos/{owner}/{repo}. For private repos without the app, returns 404 — indistinguishable from "repo doesn't exist."

Updated: When 404 and the GitHub App is configured, return a more helpful error:

if (error.response && error.response.status === 404) {
  const { isGitHubAppConfigured } = require('../lib/github-app');
  const message = isGitHubAppConfigured()
    ? `Repository ${owner}/${repo} not found. If this is a private repo, install the Roadmapper GitHub App first.`
    : `Repository ${owner}/${repo} not found on GitHub`;
  res.status(404).json({ error: message });
  return;
}

5. Update landing page messaging in api/index.js

Extend the #10 plan's "Install GitHub App" section with public/private guidance:

• GitHub App section: "Works with public and private repositories. One-click install on GitHub."
• API Key section: "Works with public repositories. Register below to get your API key."
• Below the GitHub App install button: "Required for private repositories"

6. Update api/github/setup.js redirect

Pass ?app_installed=true to the landing page redirect so it can show a confirmation banner: "GitHub App installed! Your repositories are now ready to use."

7. Update GitHub App Registration Checklist

Permissions: Issues: Read, Contents: Read, Metadata: Read

---

Additional Tests

tests/lib/verify.test.js:

• .roadmapper fallback fails + GitHub App configured → error message includes "install the Roadmapper GitHub App"
• .roadmapper fallback fails + GitHub App NOT configured → original error message

tests/api-register.test.js:

• Repo 404 + GitHub App configured → error suggests installing app
• Repo 404 + GitHub App NOT configured → original error message

tests/lib/github-app.test.js:

• getTokenForRepo with a private repo (mocked)
• Installation token used for all API calls (issues, contents, metadata)

---

Verification

1. npm test — all tests pass including new error message tests
2. Public repo without app — .roadmapper key path still works (no regression)
3. Public repo with app — GitHub App path works, installation token used
4. Private repo with app — Installation token grants access, roadmap renders correctly
5. Private repo without app — Clear error: "install the Roadmapper GitHub App"
6. Private repo registration without app — 404 suggests installing the app