Files

T

Steven RYDELL d9b073ad6c feat(dev): add scripts/dev-seed to populate sample test data

New scripts/dev-seed.sh (+ .ps1), run after dev-server-init: seeds the
test server with Users (alice, bob, carol — spanning User/Admin roles,
group membership, an alias), Groups (engineering, marketing), Mailing
Lists (newsletter, support), and custom Roles (Support Agent,
Read-only Auditor), so each admin panel screen has real data to test
against instead of an empty list.

Idempotent (skips if 'alice' already exists), documented as workflow
step 3 in DEVELOPMENT.md (renumbering the steps after it) and listed
in AGENTS.md. Verified end-to-end with both scripts against a fresh
server, including idempotency and the resulting UI (Accounts, Groups,
Mailing Lists, Roles all populated as expected).

2026-08-01 22:10:43 +02:00

2.5 KiB

Raw Blame History

Stalwart WebUI Fork

Community fork of stalwartlabs/webui, a schema-driven admin panel for Stalwart. The server's JSON schema (fetched from /api/schema) is the single source of truth for forms, fields, filters, columns, and navigation.

Tech Stack

React 19 + Vite + TypeScript, Zustand stores, JMAP (RFC 8620) for all data operations.

Commands

npm run dev:server - Start a local disposable Stalwart test server (Docker); npm run dev:server:down to stop it
bash scripts/dev-server-init.sh (or pwsh ./scripts/dev-server-init.ps1) - One-time setup of that server (bootstrap, dev admin account, 3h default token lifetime); idempotent
bash scripts/dev-seed.sh (or pwsh ./scripts/dev-seed.ps1) - Optional: seed sample Users/Groups/Mailing Lists/Roles for testing; idempotent
bash scripts/dev-token.sh [duration_seconds] (or pwsh ./scripts/dev-token.ps1 [-DurationSeconds N]) - Get a dev access token from that server, 3h by default
npm run dev - Dev server (proxies /api and /jmap to the test server)
npm run typecheck - tsc --noEmit
npm run lint - ESLint
npm run test - Vitest (npm run test:watch to watch)
npm run build - tsc -b && vite build

Full local dev workflow, including how to run it end-to-end without a browser: DEVELOPMENT.md.

Rules

The detailed rules live in .agents/rules/. Read the relevant file before acting:

Schema fidelity - .agents/rules/schema-fidelity.md - Stay schema-driven; how to handle cases the schema can't cover yet

Universal Rules

This applies to every AI coding agent working in this repo (Claude Code, Codex, Kimi, or any other) — not just one tool.
Never hardcode object types, field names, filters, or columns as a shortcut. Read .agents/rules/schema-fidelity.md before adding anything that touches lists, forms, or navigation.
CRITICAL: src/types/schema.ts mirrors the official server/webui schema contract and must never be edited to accommodate a deviation, not even to add an optional field. Deviation-only type augmentations go in src/lib/schemaDeviationTypes.ts (or the deviation's own module) as an intersection with the official type — see .agents/rules/schema-fidelity.md.
Any client-side workaround for something the official schema doesn't support yet must be documented in SCHEMA_DEVIATIONS.md and tagged // SCHEMA-DEVIATION: <id> in code. Never add one silently.