mirror of
https://github.com/prompt-security/clawsec.git
synced 2026-06-15 14:31:21 +03:00
davida-ps
95c856ad8a
* docs(repo): refresh docs and wiki alignment * fix(feed): align frontend advisory URL with canonical endpoint
108 lines
4.4 KiB
Markdown
108 lines
4.4 KiB
Markdown
# Module: Frontend Web App
|
|
|
|
## Responsibilities
|
|
- Render the ClawSec website for home, skills catalog/detail, and advisory feed/detail experiences.
|
|
- Render repository wiki content from `wiki/` markdown and expose per-page `llms.txt` links.
|
|
- Provide resilient JSON fetch behavior that handles SPA HTML fallback cases.
|
|
- Display install commands, checksums, and advisory metadata in a browser-focused UX.
|
|
|
|
## Key Files
|
|
- `index.tsx`: React bootstrap and root mount.
|
|
- `App.tsx`: Router map and page entry wiring.
|
|
- `pages/Home.tsx`: Landing page, install card, animated platform/file labels.
|
|
- `pages/SkillsCatalog.tsx`: Catalog fetch/filter state machine and empty-state handling.
|
|
- `pages/SkillDetail.tsx`: Loads `skill.json`, checksums, README/SKILL docs with markdown renderer.
|
|
- `pages/FeedSetup.tsx`: Advisory listing UI with pagination.
|
|
- `pages/AdvisoryDetail.tsx`: Advisory deep-dive view and source links.
|
|
- `pages/WikiBrowser.tsx`: In-app wiki renderer with wiki-page and `llms.txt` links.
|
|
- `components/Layout.tsx` + `components/Header.tsx`: Shared shell and nav behavior.
|
|
|
|
## Public Interfaces
|
|
- Browser routes:
|
|
- `/`
|
|
- `/skills`
|
|
- `/skills/:skillId`
|
|
- `/feed`
|
|
- `/feed/:advisoryId`
|
|
- `/wiki/*`
|
|
- Static fetch targets:
|
|
- `/skills/index.json`
|
|
- `/skills/<skill>/skill.json`
|
|
- `/skills/<skill>/checksums.json`
|
|
- `/advisories/feed.json`
|
|
- `/wiki/llms.txt`
|
|
- `/wiki/<page>/llms.txt`
|
|
- Display contracts:
|
|
- `SkillMetadata`, `SkillJson`, `SkillChecksums`, `AdvisoryFeed`, `Advisory` from `types.ts`.
|
|
|
|
## Inputs and Outputs
|
|
Inputs/outputs are summarized in the table below.
|
|
|
|
| Type | Name | Location | Description |
|
|
| --- | --- | --- | --- |
|
|
| Input | Skills index JSON | `/skills/index.json` | List of published skills and metadata. |
|
|
| Input | Skill payload files | `/skills/<id>/skill.json`, markdown docs, `checksums.json` | Detail-page content and integrity table. |
|
|
| Input | Advisory feed JSON | `/advisories/feed.json`, then `https://clawsec.prompt.security/advisories/feed.json` (legacy mirror fallback to `/releases/latest/download/feed.json`) | Advisory list/detail content. |
|
|
| Output | Route-specific UI states | Browser view state | Loading, empty, error, and populated experiences. |
|
|
| Output | Copy-to-clipboard commands | Clipboard API | Install and checksum snippets copied for users. |
|
|
|
|
## Configuration
|
|
- Build/runtime config comes from:
|
|
- `vite.config.ts` (port, host, path alias)
|
|
- `index.html` Tailwind config + custom fonts/colors
|
|
- `constants.ts` (`ADVISORY_FEED_URL`, `LOCAL_FEED_PATH`)
|
|
- Wiki markdown source lives in `wiki/`; `scripts/generate-wiki-llms.mjs` generates `public/wiki/**/llms.txt` (via `predev`/`prebuild`).
|
|
- Runtime behavior assumptions:
|
|
- JSON responses may be empty or HTML fallback and must be validated.
|
|
- Advisory list pagination uses `ITEMS_PER_PAGE = 9`.
|
|
|
|
## Example Snippets
|
|
```tsx
|
|
// Catalog fetch logic guards against HTML fallback responses
|
|
const contentType = response.headers.get('content-type') ?? '';
|
|
const raw = await response.text();
|
|
if (!raw.trim() || contentType.includes('text/html') || isProbablyHtmlDocument(raw)) {
|
|
setSkills([]);
|
|
setFilteredSkills([]);
|
|
return;
|
|
}
|
|
```
|
|
|
|
```tsx
|
|
// Route map defined in App.tsx
|
|
<Route path="/skills/:skillId" element={<SkillDetail />} />
|
|
<Route path="/feed/:advisoryId" element={<AdvisoryDetail />} />
|
|
<Route path="/wiki/*" element={<WikiBrowser />} />
|
|
```
|
|
|
|
## Edge Cases
|
|
- Missing `skills/index.json` returns empty catalog instead of hard failure.
|
|
- Some environments return `index.html` for missing JSON paths with status `200`; code defends against this.
|
|
- Skill detail tolerates missing/malformed checksums and missing markdown docs.
|
|
- Advisory detail handles absent optional fields (`cvss_score`, `reporter`, `references`).
|
|
|
|
## Tests
|
|
| Test Type | Location | Notes |
|
|
| --- | --- | --- |
|
|
| Type/lint/build checks | `scripts/prepare-to-push.sh` + CI | Frontend confidence comes from static checks and build success. |
|
|
| App-wide CI gates | `.github/workflows/ci.yml` | Multi-OS TypeScript/ESLint/build checks. |
|
|
| Manual smoke checks | `npm run dev` | Validate route rendering and fetch paths during development. |
|
|
|
|
## Source References
|
|
- index.tsx
|
|
- App.tsx
|
|
- pages/Home.tsx
|
|
- pages/SkillsCatalog.tsx
|
|
- pages/SkillDetail.tsx
|
|
- pages/FeedSetup.tsx
|
|
- pages/AdvisoryDetail.tsx
|
|
- pages/WikiBrowser.tsx
|
|
- pages/Checksums.tsx
|
|
- components/Layout.tsx
|
|
- components/Header.tsx
|
|
- constants.ts
|
|
- types.ts
|
|
- vite.config.ts
|
|
- index.html
|
|
- scripts/generate-wiki-llms.mjs
|