# SkillGuard

SkillGuard ist eine deutschsprachige Web-App zum Auditieren von Agent-"Skills" (SKILL.md + Skripte + Ressourcen) auf zwei Achsen: IT-Sicherheit und Datenschutz/Systemkompromittierung.

## Run & Operate

- `pnpm --filter @workspace/api-server run dev` — API-Server (Port 8080; build + start, kein Watch)
- `pnpm --filter @workspace/skillguard run dev` — Frontend (Vite)
- `pnpm run typecheck` — vollständiger Typecheck über alle Pakete
- `pnpm run typecheck:libs` — nur die `lib/`-Pakete neu bauen (bei stale dist / TS2305)
- `pnpm run build` — Typecheck + Build aller Pakete
- `pnpm --filter @workspace/api-spec run codegen` — React-Query-Hooks und Zod-Schemas aus dem OpenAPI-Spec neu generieren
- `pnpm --filter @workspace/db run push` — DB-Schema pushen (nur Dev)
- Required env: `DATABASE_URL` — Postgres-Verbindung

## Stack

- pnpm workspaces, Node.js 24, TypeScript 5.9
- API: Express 5
- DB: PostgreSQL + Drizzle ORM
- Validation: Zod (`zod/v4`), `drizzle-zod`
- API codegen: Orval (aus OpenAPI-Spec)
- Frontend: React + Vite + wouter, TanStack Query, shadcn/ui, Tailwind
- ZIP-Parsing: fflate

## Where things live

- Regelwerk (statische Prüfregeln): `artifacts/api-server/src/lib/ruleCatalog.ts`
- Scan-Engine (Scoring/Verdict): `artifacts/api-server/src/lib/scanEngine.ts`
- Skill-Parser (zip/file/text): `artifacts/api-server/src/lib/skillParser.ts`
- KI-Analyse (OpenAI-kompatibel + Anthropic): `artifacts/api-server/src/lib/aiAnalysis.ts`
- Seeding der Standard-Regeln/Prompts: `artifacts/api-server/src/lib/seed.ts` (läuft beim Start)
- API-Routen: `artifacts/api-server/src/routes/*.ts` (scans, dashboard, providers, prompts, rules)
- DB-Schema (source of truth): `lib/db/src/schema/*.ts`
- API-Contract (source of truth): `lib/api-spec/openapi.yaml`
- Frontend-Seiten: `artifacts/skillguard/src/pages/*.tsx`

## Architecture decisions

- KI ist Replit-unabhängig: Nutzer konfigurieren AI-Provider, Modelle, Prompts und API-Tokens im Admin-Backend. Keine Replit-AI-Integration. Tokens werden serverseitig gespeichert, API gibt nur `tokenPreview` + `hasToken` zurück.
- Analyse = deterministische statische Regel-Engine + optionale KI-semantische Analyse. Statische Analyse funktioniert ohne Provider.
- Befehls-Erkennungsregeln gelten `appliesTo: ALL` (nicht nur Skripte), damit auch eingefügter SKILL.md-Text mit eingebetteten Shell-Befehlen geprüft wird.
- Risk Score 0-100, Gewichte: critical 50, high 18, medium 7, low 2. Verdict: block bei critical>0 || score>=70; review bei high>0 || score>=20; sonst pass.

## Product

- Drei Upload-Methoden: ZIP-Archiv, Einzeldatei, eingefügter Text.
- Seiten: Dashboard, Skill Prüfen (`/pruefen`), Bericht (`/berichte/:id`), Verlauf (`/verlauf`), Administration (`/admin`: KI-Provider, Prompts, Regelwerk).
- Bericht exportierbar als JSON. Komplett deutsche UI, keine Emojis.

## User preferences

- Sprache: Deutsch. Keine Emojis in der UI.
- KI muss Replit-unabhängig bleiben — Konfiguration ausschließlich über das Admin-Backend.

## Gotchas

- api-server läuft als build+start (kein Watch): nach Backend-Änderungen `restart_workflow` ausführen.
- Backend direkt testen über `localhost:8080/api/*`; der Proxy `$REPLIT_DEV_DOMAIN/api/*` liefert erst Inhalte, wenn die Web-App läuft.
- Scan-Eingabefelder (POST /api/scans): `source` ('zip'|'file'|'text'), `useAi` (boolean), `contentBase64` (zip/file), `filename`, `text` (für source=text).
- Bei TS2305 aus `lib/`-Imports zuerst `pnpm run typecheck:libs` ausführen (stale dist).

## Pointers

- See the `pnpm-workspace` skill for workspace structure, TypeScript setup, and package details