mirror of
https://github.com/ZTatman/myst.git
synced 2026-11-21 04:17:59 +00:00
docs(web): clarify snapshot and share-link terminology
This commit is contained in:
parent
d04219a36c
commit
e4848c71ee
9 changed files with 32 additions and 21 deletions
|
|
@ -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
|
||||
|
||||
|
|
|
|||
11
docs/glossary.md
Normal file
11
docs/glossary.md
Normal file
|
|
@ -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.
|
||||
|
|
@ -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)
|
||||
|
||||
|
|
|
|||
|
|
@ -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"],
|
||||
|
|
|
|||
|
|
@ -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 @@
|
|||
<div>
|
||||
<h2 id="snapshot-title" class="picker-title">Select a snapshot</h2>
|
||||
<p id="snapshot-description" class="picker-description">
|
||||
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.
|
||||
</p>
|
||||
</div>
|
||||
<button type="button"
|
||||
|
|
@ -64,14 +64,14 @@
|
|||
{% endif %}
|
||||
<section class="grid gap-4 md:grid-cols-3">
|
||||
<div class="p-4 card">
|
||||
<p class="section-header-subtle">Active links</p>
|
||||
<p class="section-header-subtle">Active share links</p>
|
||||
<p class="mt-3 text-2xl font-semibold text-foreground">0</p>
|
||||
<p class="mt-2 text-xs text-muted-foreground">No repository snapshots published yet.</p>
|
||||
<p class="mt-2 text-xs text-muted-foreground">No active share links yet.</p>
|
||||
</div>
|
||||
<div class="p-4 card">
|
||||
<p class="section-header-subtle">Default expiry</p>
|
||||
<p class="mt-3 text-2xl font-semibold text-foreground">7 days</p>
|
||||
<p class="mt-2 text-xs text-muted-foreground">Applied to newly created links.</p>
|
||||
<p class="mt-2 text-xs text-muted-foreground">Applied to newly created share links.</p>
|
||||
</div>
|
||||
<div class="p-4 card">
|
||||
<p class="section-header-subtle">Audit events</p>
|
||||
|
|
@ -83,7 +83,7 @@
|
|||
<div class="rounded-lg border border-warning-muted bg-warning-muted/40 px-5 py-4">
|
||||
<p class="text-sm font-semibold text-warning-foreground">Access token required</p>
|
||||
<p class="mt-1 text-sm text-muted-foreground">
|
||||
Register a Forgejo access token to create share links.
|
||||
Register a Forgejo access token to browse repositories and select a snapshot.
|
||||
</p>
|
||||
<a href="/settings" class="btn btn-sm btn-primary mt-3 w-fit">Go to Settings</a>
|
||||
</div>
|
||||
|
|
@ -91,7 +91,7 @@
|
|||
<div class="space-y-3">
|
||||
<div>
|
||||
<h2 class="text-base font-semibold">Share links</h2>
|
||||
<p class="mt-2 text-sm text-muted-foreground">Repository snapshots published from this account.</p>
|
||||
<p class="mt-2 text-sm text-muted-foreground">Share links you’ve created.</p>
|
||||
</div>
|
||||
<section class="card">
|
||||
<div class="overflow-x-auto">
|
||||
|
|
|
|||
|
|
@ -28,7 +28,7 @@
|
|||
<span class="mt-2 block">Draw a boundary around your code. Let them look, but don't let them scrape.</span>
|
||||
</p>
|
||||
<p class="mt-7 max-w-xl rounded-lg border border-[#f7f2e8]/14 bg-[#17191c]/42 px-5 py-4 text-sm leading-6 text-[#f7f2e8]/76 shadow-[0_18px_50px_rgb(0_0_0_/0.24)] backdrop-blur-sm sm:text-[0.9375rem]">
|
||||
Firebreak creates temporary, read-only links to private Forgejo repository snapshots.
|
||||
Firebreak is designed for sharing read-only snapshots of private Forgejo repositories through temporary share links.
|
||||
Sign in using Forgejo, register an access token, and control what can be viewed and by whom.
|
||||
</p>
|
||||
<div class="mt-7 flex flex-wrap items-center justify-center gap-3">
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@
|
|||
<h2 class="text-base font-semibold">Forgejo access token</h2>
|
||||
<p class="mt-2 text-sm text-muted-foreground">
|
||||
A <code class="rounded-sm bg-secondary px-1.5 py-0.5 text-foreground">read:repository</code>-scoped
|
||||
Personal Access Token is required for share link viewing.
|
||||
personal access token lets Firebreak browse your repositories and preview snapshots.
|
||||
</p>
|
||||
{% if pat_registered %}
|
||||
<div class="mt-4 card">
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@
|
|||
name="repo"
|
||||
required
|
||||
{% if not options %}disabled{% endif %}
|
||||
hx-get="/links/snapshot-picker/branch"
|
||||
hx-get="{{ url_for('get_snapshot_picker_step', step='branch').path }}"
|
||||
hx-trigger="change"
|
||||
hx-target="#snapshot-branch-content"
|
||||
hx-swap="innerHTML"
|
||||
|
|
@ -36,7 +36,7 @@
|
|||
name="ref"
|
||||
required
|
||||
{% if step != "branch" or not options %}disabled{% endif %}
|
||||
hx-get="/links/snapshot-picker/commit"
|
||||
hx-get="{{ url_for('get_snapshot_picker_step', step='commit').path }}"
|
||||
hx-trigger="change"
|
||||
hx-include="#snapshot-repository"
|
||||
hx-target="#snapshot-commit-content"
|
||||
|
|
@ -57,7 +57,7 @@
|
|||
{% if error %}
|
||||
<button type="button"
|
||||
class="btn btn-xs btn-secondary"
|
||||
hx-get="/links/snapshot-picker/branch"
|
||||
hx-get="{{ url_for('get_snapshot_picker_step', step='branch').path }}"
|
||||
hx-include="#snapshot-repository"
|
||||
hx-target="#snapshot-branch-content"
|
||||
hx-swap="innerHTML"
|
||||
|
|
@ -79,7 +79,7 @@
|
|||
<div>
|
||||
<label for="snapshot-commit" class="picker-step-label">Commit</label>
|
||||
{% if step == "commit" and repo and ref %}
|
||||
<form hx-get="/links/snapshot-picker/preview"
|
||||
<form hx-get="{{ url_for('preview_snapshot').path }}"
|
||||
hx-target="#snapshot-picker-body"
|
||||
hx-swap="innerHTML"
|
||||
hx-indicator="#snapshot-picker-scope"
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@
|
|||
</div>
|
||||
<button type="button"
|
||||
class="btn btn-xs btn-secondary"
|
||||
hx-get="/links/snapshot-picker/preview"
|
||||
hx-get="{{ url_for('preview_snapshot').path }}"
|
||||
hx-target="#selected-snapshot"
|
||||
hx-swap="outerHTML">Clear</button>
|
||||
</div>
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue