Use One GitHub Repository Per User

[DevOlabode]

Use a Dedicated GitHub Repository for Each Vizably User

Description

Summary

Update Vizably's GitHub storage architecture so that each Vizably account has a dedicated GitHub repository for storing its account data and scan results.

Vizably determines the repository location automatically. Users do not choose or enter a repository name.

Storage Discovery and Creation

• New Vizably storage repositories are created using the following naming order:

  • viz_scans
  • viz_scans-2
  • viz_scans-3
  • Continue incrementing until an available name is found.

• Existing repositories are discovered by looking for a repository containing vizably.json, rather than by matching the repository name.

• The existing vizably.json manifest remains the source of truth for identifying a Vizably storage repository.

• Existing repositories do not need to be migrated. They continue to work because discovery is manifest-based.

Discovery Order

Repository discovery should use the cheapest available source first:

1. Use the storageRef already stored on the user's session, when available.
2. If no session storage reference is available, perform a direct GET against the expected repository name.
3. If the repository is not found through the expected name, list the user's repositories and search for one containing vizably.json.

Only a device without an existing session should need to reach the repository-listing fallback.

Connect Flow

The GitHub connection flow should become a single Connect action.

Remove:

• The repository name input field.
• The "Use an existing repository" option.

Vizably should automatically discover or create the appropriate storage repository.

If discovery finds exactly one storage repository, use it automatically.

If discovery finds two storage repositories, display a chooser so the user can select which discovered storage to use. The repository picker should only exist for this ambiguity case.

Provider-Neutral Resolution

The storage resolution and discovery logic should remain provider-neutral so the same resolution model can be reused by other storage providers, including the Google Drive storage implementation planned for Phase 3.

Permissions and Ownership

Vizably should not implement its own repository permission or ownership checks.

GitHub's existing permissions determine who can access or write to a repository. Whoever has permission to write to the repository owns the ability to use that storage.

Vizably should not attempt to enforce an additional application-level rule preventing a user from accessing another repository.

Acceptance Criteria

• New Vizably storage repositories are automatically created using viz_scans, then viz_scans-2, viz_scans-3, etc. when names are already taken.
• Users are not required to choose or enter a repository name.
• Existing storage repositories are discovered by the presence of vizably.json, not by repository-name matching.
• Discovery checks the session's existing storageRef first.
• Discovery performs a direct GET against the expected repository name before falling back to repository listing.
• Repository listing is only required when the earlier discovery methods do not resolve storage.
• A single discovered storage repository is selected automatically.
• A chooser is displayed only when multiple storage repositories are discovered.
• vizably.json, scan indexes, and scan results continue to be stored in the resolved Vizably repository.
• Existing repositories continue to work without migration.
• Storage resolution logic is provider-neutral and can be reused for future storage providers.
• Existing GitHub authentication and storage functionality continues to work.
• Automated tests cover repository discovery, creation, manifest-based identification, multiple-store resolution, and the discovery order.
• The implementation does not add application-level repository permission or ownership checks.

Out of Scope

• Migrating or renaming existing Vizably repositories.
• Allowing users to manually select or name a repository during the normal Connect flow.
• Adding custom application-level GitHub permission or ownership enforcement.
• Requiring repository names to follow a viz_* naming convention for discovery.

Related

Closes #99 and supersedes #104.

[ieliofficial]

Picking this up instead of #104. A few decisions first, then update the issue body to match and I'll take a look.

Vizably picks the location, the user doesn't. New stores are created as viz_scans, falling back to viz_scans-2, viz_scans-3 if taken.

Find the account by looking for a repo that contains vizably.json, never by matching the name. My own store is ieliofficial/vizably-scans with 9 scans in it, and a viz_* name match would lose it.

Discovery order, cheapest first: the storageRef already on the session, then a direct GET on the expected name so the normal case is one API call, then listing repos as a fallback. Only a device with no session gets to the third step.

Connect becomes one button. The repository name field and the "Use an existing repository" option both go. Right now that screen manages to show "Vizably account found, 9 saved scans" and "vizably-scans is TAKEN" at the same time, which is what this removes.

If discovery finds two stores, show a chooser. That's the only place a picker survives.

Keep the resolution logic provider-neutral so the Drive folder can reuse it in Phase 3.

Two things to leave out. We don't add our own permission checks, whoever can write to the repo owns the account, and GitHub's own permissions are the only thing deciding that. And no migration for existing stores, they keep working because discovery is manifest-based.

Also worth updating the two lines that currently point the other way: "handle repository creation and selection through the existing flow" keeps the picker, and "prevent one user's data being accessed through another's repository" implies we enforce something we don't.

Closes #99 and supersedes #104.

[DevOlabode]

Updated the issue based on your comment. I’ll start implementing it as soon as #104 is closed.