AGENTS.md

1# Coding Agent Guidelines for Kestra Open Source Edition
2 
3This document provides essential information for AI coding agents working on the Kestra codebase.
4 
5**IMPORTANT — READ FIRST**
6 
7- **Act as a Senior Software Engineer and Software Architect.** Approach software development with:
8    - **Pragmatism**: Favor simple solutions over clever ones
9    - **Skepticism**: Question decisions that could cause technical debt or scalability issues
10    - **Efficiency**: Only challenge when it genuinely matters
11- **Think before coding**: explicitly state assumptions, compare alternatives, and justify choices.
12- **Simplicity first (KISS)**: overengineering and "gas factories" are strictly forbidden.
13- **Surgical changes only**: touch **only** what is strictly necessary to achieve the goal.
14- **Goal-driven execution**: define what success looks like *before* writing the first line of code.
15- **Preserve existing comments**: never delete any existing comment **unless** you are improving its clarity or usefulness.
16- **Keep comments short and only where they earn their place**: a comment you write should be **one sentence**, or two at most when the *why* genuinely needs it (a non-obvious constraint, a workaround, a subtle ordering or concurrency requirement). Do **not** comment obvious code — no restating what the next line plainly says (`// increment the counter`), no narrating a self-explanatory getter, loop, or well-named call. If the code is readable, the comment is noise; if it isn't, prefer making the code clearer over explaining it.
17- **Write clear, maintainable, and well-documented code**
18- **Build & test are mandatory**
19 
20## Project
21 
22Monorepo built with Java (backend) and Vue (frontend), using Gradle as the build system.
23 
24## Tech Stack
25- **Backend:** Java 25, Micronaut Framework, Lombok
26- **Frontend:** Vue 3, TypeScript, Vite, Element Plus, Pinia
27- **Build:** Gradle 8.x with multi-project structure (77 submodules)
28- **Testing:** JUnit 5, Mockito, AssertJ, Vitest, Playwright
29 
30## Critical Code Patterns
31 
32### Dependency Injection
33 
34**DO**: Use constructor injection with final fields.
35 
36```java
37@Singleton
38public class MyService {
39    private final SomeDependency dependency;
40 
41    @Inject
42    public MyService(SomeDependency dependency) {
43        this.dependency = Objects.requireNonNull(dependency);
44    }
45}
46```
47 
48**DON'T**: Use field injection (`@Inject` on fields directly). Always prefer constructor injection.
49 
50### Class Structure
51 
52```java
53// 1. Package declaration and imports
54// 2. Class-level annotations (@Slf4j, @Singleton, etc.)
55// 3. Class declaration with Javadoc
56// 4. Static constants (UPPER_SNAKE_CASE)
57// 5. Injected fields (@Inject)
58// 6. Constructors
59// 7. Public methods
60// 8. Protected methods
61// 9. Private methods
62// 10. Inner classes/records
63```
64 
65### Annotations
66- **Micronaut:** `@Singleton`, `@Inject`, `@Controller`, `@Replaces`, `@Requires`
67- **Validation:** `@Valid`, `@NotNull`, `@Nullable`
68- **Lombok:** `@Slf4j`, `@Getter`, `@NoArgsConstructor`, `@AllArgsConstructor`
69- Use `@Builder` for complex object creation
70 
71### Error Handling
72 
73**DO**:
74- Use specific exception types — extend `KestraException` or `KestraRuntimeException`
75- Use `Optional<T>` for potentially absent returned values
76- Return empty collections (e.g., `List.of()`, `Collections.emptyList()`) for absent values
77- Use try-with-resources for resource management
78- Log errors before re-throwing: `log.error("message", exception)`
79- Write exception messages as plain, complete sentences that state the fact and the actionable detail — build them with `String.formatted()`/`String.format()`, not string concatenation or em dashes, e.g. `"Cannot acquire lock on asset '%s': already locked by '%s' until %s.".formatted(id, owner, until)`
80 
81**DON'T**: Use generic `Exception`. Don't return null for collections. Don't write terse or telegraphic exception messages (e.g. dropping articles/verbs) or string-concatenate message parts.
82 
83### Java Language Features
84- Use java records for simple data carriers
85 
86### Naming Conventions
87- Follow Java naming-convention best practices for Classes, Methods, Variables, Constants.
88- Boolean methods: Start with `is`, `has`, `should`, `can` (e.g., `isReadOnly()`).
89 
90### File Organization
91- Use 4-space indentation (configured in .editorconfig)
92- UTF-8 encoding with LF line endings
93- No trailing whitespace
94 
95### Utility Classes
96* Mark utility classes as `final` with a private constructor
97* Use static methods only
98* Use existing utility classes (e.g., `ListUtils`, `MapUtils`) instead of creating new ones (`io.kestra.core.utils.*`)
99 
100**MANDATORY — never hand-roll Pebble delimiter detection.** Pebble has two block delimiter pairs — print blocks (`{{ ... }}`) and execute/statement blocks (`{% ... %}`) — and code that only checks for `{{`/`}}` silently misses `{%`/`%}` blocks. Use `io.kestra.core.utils.PebbleUtil` (`containsOpeningBlockDelimiter`, `startsWithOpeningBlockDelimiter`, `endsWithClosingBlockDelimiter`, `openingBlockDelimiters()`/`closingBlockDelimiters()`) instead of writing a new delimiter regex or literal — it derives the delimiter pairs from Pebble's own `Syntax.Builder` defaults, so it never drifts from what Pebble actually parses.
101 
102### Enums
103- Use enums for fixed sets of constants, including internal fields not exposed over the API — prefer a typed enum over a raw `String`/`int` whenever the value is drawn from a closed set of known cases, even if the set may only ever have a couple of members
104- Use `@JsonValue` for custom serialization if needed
105- Use `UNKNOWN` enum value for unknown cases in deserialization
106- Compare Constants From The Left (a.k.a., Yoda conditions)
107- Use a static `fromString` method for case-insensitive lookups using `Enums` class.
108 
109e.g.:
110```java
111public enum MyEnum {
112    VALUE_ONE,
113    VALUE_TWO,
114    UNKNOWN;
115 
116    @JsonCreator
117    public static ResourceType fromString(final String value) {
118        return Enums.getForNameIgnoreCase(value, MyEnum.class, UNKNOWN);
119    }
120}
121```
122 
123### Documentation
124- Javadoc for all public classes and methods - be concise
125- Use `@param`, `@return`, `@throws` appropriately
126- Use `{@inheritDoc}` for inherited methods
127- Include usage examples for complex methods
128 
129## Webserver Constraints
130- Put classes used by only controllers in the webserver module (not core)
131- No business code/rule inside controllers - instead use a Service class
132- All APIs must return a valid JSON object
133- APIs should not return a response being a JSON array which cannot be evolved in a backwards-compatible way
134- Unit tests must assert that a user can only access a given API if authorized to do so, and that access is denied otherwise
135- APIs must be documented with OpenAPI annotations
136- Use DTOs for requests/responses
137- Always validate input parameters with `@Valid`
138- Use `@ExecuteOn(TaskExecutors.IO)` for blocking operations
139- Return meaningful error responses in controllers
140 
141## Worker Constraints
142- Never depend on repositories for code called by the workers - instead use MetaStore/StateStore facades
143 
144## Executor Constraints
145- Run the `H2RunnerTest` whenever you update part of the executor
146 
147## Testing Guidelines
148 
149### Java Tests
150 
151**DO**:
152- Place tests in same package structure as source code
153- Simple unit test with mocks over complex integration tests when possible
154- Add // Given-When-Then comments for clarity
155- Test method naming: `should<ExpectedBehavior>When<ConditionOrAction>` (also `...Given<Input>`, `...For<Condition>`, `...If<Condition>`), e.g. `shouldThrowExceptionWhenDividingByZero()`
156- Use `@MicronautTest` for tests that require Micronaut beans
157- Use `@KestraTest` for tests that require running Kestra services (e.g., Executor, Scheduler)
158-
159```java
160@KestraTest
161class ServiceTest {
162    @Inject
163    private ServiceClass service;
164 
165    @Test
166    void shouldPerformActionWhenCondition() {
167        // Given (setup)
168 
169        // When (action)
170 
171        // Then (assertions)
172        assertThat(result).isNotNull();
173    }
174}
175```
176 
177**DON'T**: Use Nested classes for test organization. Avoid complex test hierarchies.
178 
179**Assertions:**
180- Use AssertJ: `assertThat().isEqualTo()`, `assertThat().isNotNull()`, `assertThatThrownBy()`, `assertThatObject()`
181- Prefer descriptive assertion methods
182- Use `@MockBean` for mocking dependencies
183 
184**Test Categories:**
185- Unit tests: Fast, isolated, no external dependencies
186- Integration tests: Test component interaction, use `@Tag("integration")`
187- Flaky tests: Use `@Tag("flaky")` for unreliable tests
188 
189### Frontend Tests
190- Unit tests with Vitest and `@vue/test-utils`
191- E2E tests with Playwright
192- Storybook component tests
193- Use JSdom environment for DOM testing
194 
195## UI Design System
196 
197The full UI design-system rules, component catalogue, token reference, and frontend best practices live in [ui/AGENTS.md](ui/AGENTS.md). That file is auto-loaded by AI coding agents whenever work happens under `ui/` in OSS or `ui-ee/` in Enterprise edition, and should be consulted (and kept up to date) for any frontend change.
198 
199@ui/AGENTS.md
200 
201## Frontend Code Style (Vue 3)
202 
203**File Organization:**
204- Use 2-space indentation for Vue, JSON, YAML, CSS
205- Use 4-space indentation for JavaScript/TypeScript
206- Follow Vue 3 Composition API patterns
207- Organize imports: Vue/framework → third-party → local modules
208 
209**Naming Conventions:**
210- Components: `PascalCase` files (e.g., `MyComponent.vue`)
211- Variables/functions: `camelCase`
212- Constants: `UPPER_SNAKE_CASE`
213- CSS classes: Follow Element Plus conventions
214 
215**TypeScript:**
216- Use strict TypeScript configuration
217- Prefer type definitions over `any`
218- Use interfaces for object shapes
219- Use enums for fixed sets of values
220 
221## Build Commands
222 
223### Java Backend
224 
225```bash
226# Clean build
227./gradlew clean
228 
229# Full build (includes tests)
230./gradlew build
231 
232# Build without tests (faster)
233./gradlew build -x test -x integrationTest -x testCodeCoverageReport --refresh-dependencies --no-daemon --parallel
234```
235 
236### Test Commands
237 
238```bash
239# Run all tests (excludes flaky tests)
240./gradlew test
241 
242# Run only unit tests (fastest)
243./gradlew unitTest
244 
245# Run integration tests
246./gradlew integrationTest
247 
248# Run flaky tests (separate from build)
249./gradlew flakyTest
250 
251# Run tests for specific module
252./gradlew :core:test
253 
254# Run single test class
255./gradlew :module-name:test --tests &quot;ClassName&quot;
256 
257# Run single test method
258./gradlew :module-name:test --tests &quot;ClassName.methodName&quot;
259 
260# After running tests: generate a markdown summary of failures only
261npx --yes @kestra-io/kestra-devtools generateTestReportSummary --only-errors $(pwd)
262```
263 
264### Frontend (UI)
265 
266```bash
267cd ui
268 
269# Install dependencies
270npm install
271 
272# Development server
273npm run dev
274 
275# Type checking
276npm run check:types
277 
278# Build for production
279npm run build
280 
281# Run tests
282npm run test:all        # All tests with coverage
283npm run test:unit       # Unit tests only
284npm run test:storybook  # Storybook tests
285npm run test:e2e        # End-to-end tests
286 
287# Linting
288npm run lint            # Fix linting issues
289npm run test:lint       # Check linting only
290 
291# Storybook
292npm run storybook       # Development
293npm run build-storybook # Build
294```
295 
296## Development Workflow
297 
298### Running Locally
299 
3001. **Start/stop backends:**
301```bash
302# Start databases with Docker Compose
303docker compose -f docker-compose-ci.yml up
304 
305# Stop databases with Docker Compose
306docker compose -f docker-compose-ci.yml down
307```
308 
3092. **Access application:** http://localhost:8080
310 
311### Worktree setup
312 
313When working in an EE worktree (detected by: the working directory is under a `worktrees/` directory):
314```bash
315dev-tools/setup-worktree.sh ../worktrees/foo
316```
317This copies the gitignored `cli/src/main/resources/application-*.yml` files from the main checkout into the worktree. Without this step Kestra cannot boot in the worktree. The script is idempotent — safe to re-run.
318 
319### Security Considerations
320- Use tenant isolation for multi-tenant features
321- Implement proper authorization with `@HasAnyPermission`
322- Handle secrets securely (never log sensitive data)
323 
324### Performance Best Practices
325- Implement pagination for large datasets
326- Use streaming for large file operations
327- Cache frequently accessed data appropriately
328- Initialize collections with the expected size to avoid resizing overhead
329 
330## Troubleshooting
331 
332**Common Issues:**
333- **Build failures:** Run `./gradlew clean` and retry
334- **Test failures:** Check for service dependencies (Docker containers)
335- **Frontend issues:** Ensure Node.js version matches package.json requirements
336 
337**Debugging:**
338- Use IDE debugging with remote JVM debugging
339- Use Micronaut's built-in health endpoints
340- Enable debug logging: `--logging.level.io.kestra=DEBUG`
341- Use JUnit and Vitest reports for test failures
342 
343## Module Structure
344 
345**Core Modules:**
346- `cli` - Command Line Interface
347- `core` - Core functionality
348- `webserver` - Web server
349- `ui` - Vue 3 frontend application
350- `executor` - The component responsible for managing execution state
351- `scheduler` - The component responsible for scheduling polling and schedule triggers
352- `worker` - The component that executes tasks and manages worker instances
353- `worker-controller` - The component that manages worker instances and job distribution
354- `indexer` - The component responsible for indexing executions
355- `plateform` - provides the Platform Bill of Materials (BOM) for dependency management
356 
357**Queuing Layer:**
358- `queue` - Core API for queue implementations
359- `queue-jdbc` - JDBC-based queue implementation
360 
361**Data Layer:**
362- `jdbc-*` - Database implementations (H2, Postgres, MySQL)
363 
364**Testing Modules:**
365- `tests` - Common test utilities and base classes
366- `jmh-benchmark` - JMH benchmarks for performance testing
367 
368**Key Patterns:**
369- Repository pattern for data access
370- Service layer for business logic
371- Controller layer for HTTP endpoints
372- Builder pattern for object construction (often with Lombok `@Builder`)
373 
374## Pull request guidelines
375- Always add tests, keep your branch rebased instead of merged, and adhere to the commit message recommendations from https://www.conventionalcommits.org/en/v1.0.0.
376- Use types: chore, feat, fix, refactor, test, docs, build
377- Use scopes: apps, assets, core, dashboards, deps, design-system, executions, flows, iam, namespaces, plugins, secrets, storage, scheduler, system, tasks, tenants, tests, topology, triggers, variables, version, worker
378 
379## Issue guidelines
380- **Classify an issue with its GitHub issue type, not a `kind/*` label.** The `kind/bug` label is retired — do not add it. Set the type instead: `gh issue create --title … ` followed by `gh issue edit <number> --type Bug`, or `gh issue edit <number> --type Task|Feature|Epic`. Available types are `Task`, `Bug`, `Feature` and `Epic` (list them with `gh api /orgs/kestra-io/issue-types`).
381- **Do add the `area/*` labels** — `area/frontend`, `area/backend`, `area/devops`, `area/docs`, `area/plugin`, `area/qa`, `area/analytics` — since those drive routing and are still in use.
382- Leave triage labels such as `kind/cooldown` to `kestrabot`; it applies them automatically on new issues.
383 
384This document should be updated as the codebase evolves. When in doubt, follow existing patterns in the codebase and maintain consistency with established conventions.
385 
386## UI Translations
387 
388**MANDATORY — never hardcode user-facing strings.** Every label, button, tooltip, placeholder, dialog/section title, table-column header, and toast/confirm message rendered to the user MUST go through vue-i18n: `t("key")` (or `:label`/`:tooltip` bindings) in components, and `<i18n-t keypath="...">` with named slots when the string embeds markup or a component (e.g. a `<code>` fragment). Never write a literal user-facing string in a template, a `:tooltip`/`:label` attribute, or a `toast.*` call. Reuse existing generic keys (`cancel`, `delete`, `edit`, `save`, `add`, `id`, `description`, `namespace`, `revision`, …) instead of duplicating them; put feature-specific strings under one namespaced object (e.g. `"reusableInputs": { … }`). After adding keys to `en.json`, propagate them to every language (translation generation script) so the missing-keys check stays clean — a key present only in `en.json` fails the check.
389 
390Translation files live in `ui/src/translations/`. There is one JSON file per language code (e.g. `de.json`, `fr.json`) plus the source `en.json`.
391 
392### Checking for missing translations
393 
394Run the check script from the `ui/` directory:
395 
396```bash
397cd ui && npm run translations:check
398```
399 
400A clean run reports `No missing keys. No extra keys.` for every language. Any listed missing keys must be added.
401 
402> **Enterprise Edition:** EE-only keys live in `ui-ee/src/translations/ee_translations/en.json` and are checked separately — run `npm run translations:check` in `ui-ee` as well (see `kestra-ee/AGENTS.md` → "Frontend i18n").
403 
404### Adding missing translations
405 
4061. Identify gaps by running `npm run translations:check` (or by diffing the flattened `en.json` keys against each language file).
4072. Translate only the missing keys — do **not** re-translate keys that already have a value.
4083. Follow these translation rules (mirroring `generate_translations.ts`):
409   - **Reserved English terms — never translate:** `kv store`, `namespace`, `flow`, `subflow`, `task`, `log`, `blueprint`, `id`, `trigger`, `label`, `key`, `value`, `input`, `output`, `port`, `worker`, `backfill`, `healthcheck`, `min`, `max`.
410   - **ALL-CAPS status labels stay in English:** `WARNING`, `FAILED`, `SUCCESS`, `PAUSED`, `RUNNING`, etc.
411   - **Preserve `{{placeholder}}` variables** exactly — do not translate the word inside the braces.
412   - **Use natural UI terminology** — avoid false friends or overly literal translations (e.g. German: Execution → Ausführung, Theme → Modus, State → Zustand).
4134. Insert the translated keys into the correct position in the target language JSON, keeping `sort_keys=True` order (alphabetical within each object).
4145. Re-run `npm run translations:check` to confirm everything is clean before committing.
415