Files

T

Steven RYDELL f4c8f8f21c feat(dev): add one-command local Stalwart test server + workflow docs

Add docker-compose.yml: a disposable Stalwart instance with a fixed dev
admin account (STALWART_RECOVERY_ADMIN), matching the credentials
scripts/dev-token.ps1 already expected. Wired up via new npm scripts
(dev:server, dev:server:down, dev:server:logs).

scripts/dev-token.ps1 was previously untracked (the whole scripts/
directory was gitignored) even though it's part of the documented dev
workflow — un-ignored it, and added scripts/dev-token.sh, a POSIX
equivalent for non-Windows shells and AI agents without PowerShell.

New DEVELOPMENT.md documents the full loop end-to-end (start server,
get a token, run the dev server, verify), written so it's actionable by
both humans and AI coding agents without needing a browser. Linked from
AGENTS.md (Commands) and README.md (Getting started).

Verified manually: docker compose up brings the server to a healthy
state, /api/auth + /auth/token issue a working bearer token, and
/jmap/session returns 200 with it end-to-end.

2026-08-01 18:05:43 +02:00

2.1 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-token.sh (or pwsh ./scripts/dev-token.ps1 on Windows) - Get a dev access token from that server
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.