08a31cacf5
Tighten the repo-state automation so canonical bot commits remain predictable while leaving main clean after each sync. Make the public catalog UI more honest by hiding dev-only sync, turning stars into explicit browser-local saves, aligning risk types, and removing hardcoded catalog counts. Add shared public asset URL helpers, risk suggestion plumbing, safer unpack/sync guards, and CI coverage gates so release and maintainer workflows catch drift earlier.
94 lines
3.7 KiB
Markdown
94 lines
3.7 KiB
Markdown
# Antigravity Web App
|
|
|
|
This app is the static catalog and skill browser for `antigravity-awesome-skills`. It ships the generated registry, renders searchable skill detail pages, and publishes the public site to GitHub Pages.
|
|
|
|
## What This App Does
|
|
|
|
- Loads the generated skill catalog and related metadata from tracked assets in `public/`.
|
|
- Renders home, category, bundle, and skill detail routes for the published library.
|
|
- Adds SEO metadata, sitemap-backed URLs, and static asset resolution for GitHub Pages.
|
|
- Supports a local-only "refresh skills" developer flow through the Vite dev server plugin.
|
|
|
|
## Architecture
|
|
|
|
- `src/pages/` contains top-level route screens such as `Home.tsx` and `SkillDetail.tsx`.
|
|
- `src/context/` holds catalog loading and shared app state.
|
|
- `src/hooks/` contains feature-specific client hooks such as star state and filters.
|
|
- `src/utils/` contains URL, SEO, and content helpers.
|
|
- `public/` contains generated catalog artifacts copied from the repo root as part of maintainer sync flows.
|
|
|
|
The app intentionally assumes a static hosting model in production. Anything that depends on `/api/*` is development-only unless it is backed by a real serverless or backend implementation.
|
|
|
|
## Development
|
|
|
|
From the repo root:
|
|
|
|
```bash
|
|
npm run app:install
|
|
npm run app:dev
|
|
```
|
|
|
|
Or directly from this directory:
|
|
|
|
```bash
|
|
npm ci
|
|
npm run dev
|
|
```
|
|
|
|
Useful root-level commands:
|
|
|
|
```bash
|
|
npm run app:build
|
|
npm run sync:web-assets
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
The app reads configuration from `.env` files in `apps/web-app/`.
|
|
|
|
- `VITE_SUPABASE_URL` and `VITE_SUPABASE_ANON_KEY`: optional read access for read-only community save counts.
|
|
- `VITE_ENABLE_SKILLS_SYNC=true`: explicitly exposes the local maintainer-only sync button during development.
|
|
- `VITE_SYNC_SKILLS_TOKEN`: local development token accepted by the Vite refresh plugin.
|
|
- `VITE_SITE_URL`: optional override for canonical URL generation when testing non-default hosts.
|
|
|
|
Saving a skill is intentionally browser-local for now. The UI should not imply a shared write path until the project has a real backend contract for persistence, abuse controls, and deployment.
|
|
|
|
## Deploy Model
|
|
|
|
Production deploys use GitHub Pages and publish the built `dist/` output from this app. That means:
|
|
|
|
- production is static
|
|
- Vite `configureServer` hooks are not available in production
|
|
- any refresh or sync endpoint exposed by a dev plugin must be hidden or replaced by a real backend before being treated as a public feature
|
|
|
|
Maintainers should treat `public/skills.json.backup`, `public/sitemap.xml`, and other generated assets as derived artifacts synced from the repo root during release and hygiene workflows.
|
|
|
|
## Catalog Data Flow
|
|
|
|
The high-level maintainer flow is:
|
|
|
|
1. update skill sources under `skills/`
|
|
2. regenerate canonical registry artifacts from the repo root
|
|
3. sync tracked web assets into `apps/web-app/public/`
|
|
4. build this app for Pages
|
|
|
|
`npm run sync:repo-state` and `npm run sync:release-state` are the safest entrypoints because they keep the root catalog and the web assets aligned.
|
|
|
|
## Testing
|
|
|
|
From the repo root:
|
|
|
|
```bash
|
|
cd apps/web-app && npm run test
|
|
cd apps/web-app && npm run test:coverage
|
|
npm run test
|
|
```
|
|
|
|
The repo-level test suite also contains workflow and documentation guardrails outside `src/`, so changes to this app can fail tests in `tools/scripts/tests/` even when the React code itself is untouched.
|
|
|
|
## Troubleshooting
|
|
|
|
- If the app shows stale catalog data, run `npm run sync:web-assets` from the repo root and rebuild.
|
|
- If a feature works in `npm run app:dev` but not on GitHub Pages, check whether it depends on a dev-only Vite plugin or non-static runtime behavior.
|
|
- If canonical URLs or asset links look wrong, inspect the shared path/base URL helpers before patching individual pages.
|