Tooling, CI & Release Workflow
Developer Tooling Stack
Section titled “Developer Tooling Stack”The monorepo uses a fast, modern Rust + TypeScript quality toolchain modeled after @vicacha-devs/astro-tiptap-blocks:
| Tool | Config File | Command | Purpose |
|---|---|---|---|
| Oxfmt | .oxfmtrc.json |
pnpm format / pnpm format:check |
Sub-second formatting & import sorting across all workspace files |
| Oxlint | .oxlintrc.json |
pnpm lint:oxc |
Fast static analysis (typescript, unicorn, oxc, import plugins) |
| ESLint v10 | eslint.config.ts |
pnpm lint:eslint |
Flat config enforcing max-lines: 500, sonarjs, jsx-a11y, and JSON validation |
| TypeScript 5.9 | tsconfig.json |
pnpm check |
Strict tsc --noEmit across both admin/tsconfig.json and server/tsconfig.json |
| Strapi SDK | package.json |
pnpm verify:sdk |
Runs strapi-plugin verify across all 17 plugins |
| Publint | scripts/publint-all.ts |
pnpm publint |
Packs each plugin with pnpm and enforces publint({ strict: true }) |
| Plugin Scaffolder | scripts/create-plugin.ts |
pnpm plugin:new -- <slug> |
Generates a compliant Strapi v5 plugin with 5-locale i18n, dual tsconfigs, offline tests & dashboard wiring |
| QA Control Center | scripts/qa/*, docker-compose.qa.yml |
pnpm qa:verify / pnpm qa:report |
Offline doctor, adversarial judges, multi-repo HTML Control Center (.qa/dashboard.html) & Dashboard Playwright E2E |
| Husky + lint-staged | .husky/*, .lintstagedrc.json |
Git hooks | Runs commitlint on commit-msg, lint-staged on pre-commit, and lint + check + test on pre-push |
| Semantic Release | .releaserc.json, scripts/release.ts |
pnpm release / pnpm release:dry |
Per-package conventional-commit version calculation, changelog generation, and pnpm publish with npm OIDC provenance |
Commit Message Convention (commitlint.config.ts)
Section titled “Commit Message Convention (commitlint.config.ts)”All commits must follow Conventional Commits (type(scope): subject), with an optional [TICKET-123] prefix:
feat(calendar): add RFC 5545 EXDATE exception date editorfix(certificates): enforce constant-time token comparison on QR verification[MOSQUE-42] feat(islam): sync confirmed Hilal offset to calendar plugindocs(events): add RSVP waitlist promotion sequence diagramAllowed types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert.
How to Use & Navigate the Documentation Portal
Section titled “How to Use & Navigate the Documentation Portal”Every plugin in the @vicacha-devs suite is documented through four complementary layers:
- Overview (
/<plugin-slug>/): Synchronized directly frompackages/<dir>/README.mdwith quick-install snippets, feature tables, and high-resolution Playwright captures of the Strapi v5 Admin workspace and Settings panel. - Content Types & Use Cases (
/<plugin-slug>/use-cases/): Plugin-by-plugin Content-Type entity directory (strapi.documents), Strapi v5 Admin locations, interactive Pele (https://pele.run/) SVG Mermaid architecture & workflow diagrams, and real Strapi v5 screenshots for each use case. - Developer Guide & Admin UI Tour (
/<plugin-slug>/guide/): Deep-dive architectural reference detailing Content-Type UIDs (schema.jsonattributes), Admin UI translation coverage across 13 locales, TypeScript service & custom field integration examples, and a full endpoint summary table. - Interactive OpenAPI 3.0.3 Reference (
/<plugin-slug>/api/): Generated automatically byscripts/generate-openapi.tsfrom each plugin’sserver/src/routes/index.tsandcontent-types/*/schema.json, complete with request/response schemas andbearerAuthsecurity definitions. - AI / LLM Context Index (
/llms.txt&/llms-full.txt): Generated at build time viastarlight-llms-txtso AI coding assistants (Cursor, Windsurf, Claude Code, Antigravity) can ingest the entire monorepo documentation in a single request. - Quadrilingual Switcher (
/,/es/,/ar/,/tr/): Use the top-right language selector to switch between English, Español, العربية (with nativedir="rtl"layout), and Türkçe.
Documentation Build & Adversarial Verification
Section titled “Documentation Build & Adversarial Verification”The documentation site in apps/docs automatically synchronizes with the plugin packages on every build:
# Start interactive local development server at http://localhost:4321pnpm --filter @vicacha-devs/docs dev
# 1. Generate OpenAPI 3.0.3 YAML schemas from all 17 plugins' server routes & content-typespnpm --filter @vicacha-devs/docs generate:openapi
# 2. Sync package README.md files + generate localized (en, es, ar, tr) Overview & Guide pagespnpm --filter @vicacha-devs/docs sync:readmes
# 3. Capture fresh 1440x900 Strapi v5 Admin screenshots via Playwrightpnpm --filter @vicacha-devs/docs capture:screenshots
# 4. Build the static multi-locale Starlight site (EN, ES, AR, TR + Pagefind + llms.txt)pnpm --filter @vicacha-devs/docs build
# 5. Run the 5 Adversarial Judges (Modularity <=500 lines, Completeness, 4-Locale i18n/RTL, Visual/Links, Security)pnpm --filter @vicacha-devs/docs test:judgesAdding or Updating a Plugin in apps/docs
Section titled “Adding or Updating a Plugin in apps/docs”- Register the package in
apps/docs/docs-packages.tswith itsslug,dir,npmName,pluginId,label,category,schemaFile,screenshot,settingsScreenshot, and localizedsummary(en,es,ar,tr). - Document Content-Type entities & use cases in
apps/docs/scripts/lib/plugin-use-cases.tssosync-readmes.tsandcapture-screenshots.tsinclude full Strapi v5 entity paths, workflows, and screenshots. - Run
pnpm --filter @vicacha-devs/docs build && pnpm --filter @vicacha-devs/docs test:judgesto generate the OpenAPI spec, sync all 4 locales, and verify all 5 adversarial judges pass.
Automated Plugin Scaffolding & QA Control Center
Section titled “Automated Plugin Scaffolding & QA Control Center”Create new plugins and run cross-repo quality checks without manual boilerplate:
# Scaffold a new Strapi v5 plugin with 5-locale i18n parity & optional dashboard wiringpnpm plugin:new -- announcements --display-name "Announcements" --with-content-type --wire-dashboard
# Run offline QA doctor, adversarial judges, plugin unit suites & generate .qa/dashboard.htmlpnpm qa:doctorpnpm qa:judgespnpm qa:verifypnpm qa:report
# Boot port-isolated 127.0.0.1 QA infra (Postgres 5434, Valkey 6381, Typesense 8110, Mailpit 1027)pnpm qa:docker:uppnpm qa:smokepnpm qa:e2epnpm qa:docker:downCI runs Dashboard boot smoke tests and Playwright Admin E2E automatically via .github/workflows/qa-e2e.yml, uploading .qa/dashboard.html and the Playwright HTML report as artifacts.