Code Style

This page is for contributors to the Plugwerk codebase in plugwerk/plugwerk. Every PR runs through formatting, linting, and license-header checks in CI; PRs that violate any of them fail the build before review.

Run the relevant checks locally before every commit.

Backend (Kotlin)

Backend formatting and basic style are enforced by Spotless with ktlint.

./gradlew spotlessApply   # auto-fix
./gradlew spotlessCheck   # verify (fails build on violations)

The Spotless configuration lives in the root build.gradle.kts and is applied per module so each module gets its correct license header automatically.

Frontend (TypeScript / TSX)

The frontend uses ESLint and Prettier. Run from plugwerk-server/plugwerk-server-frontend/:

npm run format    # Prettier auto-fix
npm run lint      # ESLint

CI enforces both — Prettier via the Gradle npmFormatCheck task that runs as part of ./gradlew build, and ESLint as a dedicated step.

License headers

Plugwerk uses a dual-license model:

| Module | License | | ------------------------------------------------------------- | -------------- | | plugwerk-server (backend + frontend) | AGPL-3.0 | | plugwerk-spi, plugwerk-descriptor, plugwerk-client-plugin, plugwerk-api-model | Apache-2.0 |

Every Kotlin and TypeScript source file must begin with the correct header for its module. Spotless applies the right Kotlin header automatically. For TypeScript, run from the frontend directory:

npm run license:check     # verify
npm run license:add       # add missing headers

Generated files are excluded automatically.

Pre-commit checklist

Before every commit, run:

• ./gradlew spotlessApply (from repo root) — if you touched Kotlin
• npm run format and npm run lint (from plugwerk-server/plugwerk-server-frontend/) — if you touched TypeScript
• npm run license:check (from the frontend directory) — if you added new TypeScript files

CI re-runs all of these on every push.