diff --git a/README.md b/README.md index c595d1b..a899461 100644 --- a/README.md +++ b/README.md @@ -76,7 +76,9 @@ Open `http://localhost:8000` in your browser. On first boot, Firebreak redirects ### 4. Sign In and Register Your Token -After setup, sign in with your Forgejo account via OAuth. On first login, Firebreak prompts you to register a `read:repository`-scoped Personal Access Token (PAT) to enable share link viewing. +After setup, sign in with your Forgejo account via OAuth. On first login, Firebreak prompts you to register a `read:repository`-scoped personal access token (PAT) so you can browse your repositories and preview snapshots. + +See the [Firebreak glossary](docs/glossary.md) for the difference between snapshots, share links, and grants. ### 5. Alternative Deployments diff --git a/docs/glossary.md b/docs/glossary.md new file mode 100644 index 0000000..554586b --- /dev/null +++ b/docs/glossary.md @@ -0,0 +1,11 @@ +# Firebreak glossary + +A **share link** opens a **snapshot**. A **grant** is the internal record Firebreak checks to decide whether to allow access. + +| Term | Meaning | Where it belongs | +| --- | --- | --- | +| **Snapshot** | A repository's content at a specific commit SHA. The branch helps users find a commit; it does not change what a link opens later. | Picker, preview, and viewer copy. A snapshot doesn't need a separate database model. | +| **Share link** | The URL someone copies and sends to let others view a snapshot. | Dashboard copy, share-link API names, and `/links` routes for creating and managing links. | +| **Grant** | The stored access record: the repository and commit SHA, expiration, revocation, and any recipient restriction. | The `Grant` model, `grants` table, and backend authorization code. Use **share link**, not **grant**, in user-facing copy. | + +The dashboard's snapshot picker lives under `/dashboard/snapshot-picker`. Selecting or clearing a preview does not create, publish, or revoke a share link. Existing JSON repository listings stay under `/links/repositories` for compatibility. diff --git a/web/app/main.py b/web/app/main.py index 5370aad..25128dc 100644 --- a/web/app/main.py +++ b/web/app/main.py @@ -91,6 +91,7 @@ app.mount( app.include_router(auth.router) app.include_router(links.router) app.include_router(repositories.router) +app.include_router(repositories.picker_router) app.include_router(settings.router) app.include_router(setup.router) diff --git a/web/app/routers/repositories.py b/web/app/routers/repositories.py index 88e43ea..aa32679 100644 --- a/web/app/routers/repositories.py +++ b/web/app/routers/repositories.py @@ -17,6 +17,7 @@ from app.settings import get_app_settings, get_fernet from app.templating import templates router = APIRouter(prefix="/links", tags=["repositories"]) +picker_router = APIRouter(prefix="/dashboard/snapshot-picker", include_in_schema=False) async def get_forgejo_token( @@ -131,9 +132,7 @@ RECENT_COMMITS = 30 PICKER_PAGE_SIZE = 50 -@router.get( - "/snapshot-picker/preview", response_class=HTMLResponse, include_in_schema=False -) +@picker_router.get("/preview", response_class=HTMLResponse) async def preview_snapshot( request: Request, _session: Annotated[UserBrowserSession, Depends(get_current_session)], @@ -152,9 +151,7 @@ async def preview_snapshot( ) -@router.get( - "/snapshot-picker/{step}", response_class=HTMLResponse, include_in_schema=False -) +@picker_router.get("/{step}", response_class=HTMLResponse) async def get_snapshot_picker_step( request: Request, step: Literal["repository", "branch", "commit"], diff --git a/web/app/templates/dashboard.html b/web/app/templates/dashboard.html index 76f0dd4..6b8519e 100644 --- a/web/app/templates/dashboard.html +++ b/web/app/templates/dashboard.html @@ -13,7 +13,7 @@ class="btn btn-primary w-fit" commandfor="snapshot-picker" command="show-modal" - hx-get="/links/snapshot-picker/repository" + hx-get="{{ url_for('get_snapshot_picker_step', step='repository').path }}" hx-target="#snapshot-picker-body" hx-swap="innerHTML" hx-indicator="#snapshot-picker-scope" @@ -34,7 +34,7 @@
- Choose a repository, then a branch and commit. Nothing is published until you create a link. + Choose a repository, then a branch and commit. This previews a snapshot without creating a share link.