This is an automated email from the ASF dual-hosted git repository. zehnder pushed a commit to branch add-agents-md in repository https://gitbox.apache.org/repos/asf/streampipes.git
commit e019b48096af8086440fbcfb3dca882372081f21 Author: Philipp Zehnder <[email protected]> AuthorDate: Thu Feb 19 22:32:50 2026 +0100 docs: Add AGENTS guides for various modules in the repository --- AGENTS.md | 31 +++++++++++++++++++ streampipes-extensions/AGENTS.md | 21 +++++++++++++ streampipes-pipeline-management/AGENTS.md | 22 ++++++++++++++ streampipes-resource-management/AGENTS.md | 21 +++++++++++++ streampipes-rest/AGENTS.md | 18 +++++++++++ streampipes-service-core/AGENTS.md | 23 ++++++++++++++ streampipes-storage-couchdb/AGENTS.md | 22 ++++++++++++++ streampipes-user-management/AGENTS.md | 21 +++++++++++++ ui/AGENTS.md | 35 ++++++++++++++++++++++ .../streampipes/platform-services/AGENTS.md | 22 ++++++++++++++ ui/projects/streampipes/shared-ui/AGENTS.md | 23 ++++++++++++++ 11 files changed, 259 insertions(+) diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..e4fc47bd01 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,31 @@ +# AGENTS Guide (Repository Root) + +## Scope +Applies to the whole repository unless a deeper `AGENTS.md` overrides it. + +## Monorepo Rules +- Keep changes scoped to requested modules; avoid opportunistic cross-module refactors. +- Preserve Apache license headers in source files. +- Keep backward compatibility for public APIs, serialized models, and storage contracts unless explicitly requested. + +## Java Standards +- Follow style and import order from: + - `tools/maven/checkstyle.xml` + - `tools/maven/streampipes-code-formatter.xml` + - `tools/maven/checkstyle-header.txt` +- Prefer constructor/typed APIs over loosely typed maps when extending domain logic. + +## Architecture Boundaries +- `streampipes-service-core`: bootstrapping, security, migrations, scheduling. +- `streampipes-rest`: HTTP/resource layer. +- `*-management` modules: business/domain logic. +- `streampipes-storage-*`: persistence abstractions/implementations. +- Avoid moving business logic into controllers/resources. + +## Validation +- For backend changes, run targeted module checks first: + - `mvn -pl <module> -am test` +- Run only additional modules affected by dependency edges. + +## UI +- UI-specific rules live in `ui/AGENTS.md` and deeper UI-level files. diff --git a/streampipes-extensions/AGENTS.md b/streampipes-extensions/AGENTS.md new file mode 100644 index 0000000000..2a8e87220a --- /dev/null +++ b/streampipes-extensions/AGENTS.md @@ -0,0 +1,21 @@ +# AGENTS Guide (Extensions Aggregator) + +## Scope +Applies to `streampipes-extensions/` and all its submodules unless overridden. + +## Module Intent +- Parent for adapters/connectors/processors/sinks and extension bundle modules. + +## Best Practices +- Keep changes narrowly scoped to the affected extension submodule. +- Avoid broad multi-extension edits unless explicitly requested. +- Preserve extension metadata/resources (`documentation.md`, `strings.*`, icons) for changed elements. +- Keep migration classes and tests aligned when changing extension model versions. +- Preserve bundle startup/packaging behavior in `streampipes-extensions-all-*` modules. + +## Build Notes +- Parent uses `streampipes-maven-plugin`; avoid changing plugin behavior unless explicitly required. + +## Validation +- Run tests/build from changed submodule(s), for example: + - `mvn -pl streampipes-extensions/<submodule> -am test` diff --git a/streampipes-pipeline-management/AGENTS.md b/streampipes-pipeline-management/AGENTS.md new file mode 100644 index 0000000000..da7db4d0cb --- /dev/null +++ b/streampipes-pipeline-management/AGENTS.md @@ -0,0 +1,22 @@ +# AGENTS Guide (Pipeline Management) + +## Scope +Applies to `streampipes-pipeline-management/`. + +## Module Intent +- Core pipeline domain behavior: matching, verification, graph construction, execution orchestration, migrations, setup tasks, permission handling. + +## High-Risk Areas +- Verification/matching pipelines (`manager/verification`, `manager/matching`, `manager/matching/v2`). +- Graph logic (`manager/data/PipelineGraph*`). +- Execution task pipeline and status updates (`manager/execution`). +- Pipeline element migrations (`manager/migration`). + +## Best Practices +- Keep verification deterministic and side-effect free where intended. +- Keep pipeline graph and output schema behavior backward compatible. +- Treat migration failures explicitly; do not hide partial migration states. +- Preserve permission and ownership behavior when creating/updating/deleting pipelines. + +## Validation +- `mvn -pl streampipes-pipeline-management -am test` diff --git a/streampipes-resource-management/AGENTS.md b/streampipes-resource-management/AGENTS.md new file mode 100644 index 0000000000..2a1903d9cf --- /dev/null +++ b/streampipes-resource-management/AGENTS.md @@ -0,0 +1,21 @@ +# AGENTS Guide (Resource Management) + +## Scope +Applies to `streampipes-resource-management/`. + +## Module Intent +- Cross-resource orchestration and lifecycle management (permissions, users, adapters, pipelines, notifications, secret handling). + +## High-Risk Areas +- Permission creation/deletion coupling in CRUD/resource managers. +- User onboarding/account activation/password recovery flows (`UserResourceManager`). +- Secret encryption/decryption handlers (`secret/*`). + +## Best Practices +- Keep side effects explicit and consistent (storage + permission + notification updates). +- Preserve idempotency for delete/update operations where possible. +- Avoid orphaning permissions/assets when deleting entities. +- Keep mail-triggering flows resilient and error-aware. + +## Validation +- `mvn -pl streampipes-resource-management -am test` diff --git a/streampipes-rest/AGENTS.md b/streampipes-rest/AGENTS.md new file mode 100644 index 0000000000..b21fc7ef02 --- /dev/null +++ b/streampipes-rest/AGENTS.md @@ -0,0 +1,18 @@ +# AGENTS Guide (REST API) + +## Scope +Applies to `streampipes-rest/`. + +## Module Intent +- HTTP API/resource layer (`impl`, `impl/admin`, `impl/connect`, `impl/datalake`, `impl/runtime`). +- Security-related endpoint behavior (`rest/security`). + +## Best Practices +- Keep resources thin: request parsing, auth/permission checks, delegation, response mapping. +- Keep business/domain logic in management modules. +- Preserve endpoint contracts and semantics unless explicitly requested. +- Apply consistent error handling and status codes; avoid silent behavioral changes. +- Preserve permission evaluation behavior (`SpPermissionEvaluator`) for protected operations. + +## Validation +- `mvn -pl streampipes-rest -am test` diff --git a/streampipes-service-core/AGENTS.md b/streampipes-service-core/AGENTS.md new file mode 100644 index 0000000000..bc9965808a --- /dev/null +++ b/streampipes-service-core/AGENTS.md @@ -0,0 +1,23 @@ +# AGENTS Guide (Service Core) + +## Scope +Applies to `streampipes-service-core/`. + +## Module Intent +- Backend entrypoint and runtime wiring (`StreamPipesCoreApplication`). +- Security setup (`WebSecurityConfig`, token filter, OAuth handlers). +- Startup tasks, migrations, and schedulers. + +## High-Risk Areas +- Authentication flow and unauthenticated endpoint configuration. +- Migration registration/execution (`migrations/AvailableMigrations`, `MigrationsHandler`). +- Scheduled side effects (for example data lake and certificate jobs). + +## Best Practices +- Keep this module orchestration-focused; domain behavior belongs in management modules. +- New migrations must be idempotent and explicitly registered. +- Preserve existing startup behavior for OAuth and non-OAuth deployments. +- Avoid introducing long-running/blocking work on startup thread paths. + +## Validation +- `mvn -pl streampipes-service-core -am test` diff --git a/streampipes-storage-couchdb/AGENTS.md b/streampipes-storage-couchdb/AGENTS.md new file mode 100644 index 0000000000..1856baa0fc --- /dev/null +++ b/streampipes-storage-couchdb/AGENTS.md @@ -0,0 +1,22 @@ +# AGENTS Guide (Storage CouchDB) + +## Scope +Applies to `streampipes-storage-couchdb/`. + +## Module Intent +- CouchDB implementation of storage interfaces (`impl/*`, `dao/*`, `serializer/*`). +- Central wiring via `CouchDbStorageManager`. + +## High-Risk Areas +- DAO/query/view behavior (`dao`, `CouchDbViewGenerator`). +- Serialization compatibility (`serializer/*`). +- Storage manager wiring and interface coverage. + +## Best Practices +- Keep implementations aligned with `streampipes-storage-api` contracts. +- Preserve document and view compatibility unless migrations are included. +- When adding a storage type, wire it through `CouchDbStorageManager` and corresponding API abstractions. +- Keep serializer changes backward compatible for persisted entities. + +## Validation +- `mvn -pl streampipes-storage-couchdb -am test` diff --git a/streampipes-user-management/AGENTS.md b/streampipes-user-management/AGENTS.md new file mode 100644 index 0000000000..e6938d4ba7 --- /dev/null +++ b/streampipes-user-management/AGENTS.md @@ -0,0 +1,21 @@ +# AGENTS Guide (User Management) + +## Scope +Applies to `streampipes-user-management/`. + +## Module Intent +- Authentication, token handling, role/privilege resolution, and user principal composition. + +## High-Risk Areas +- JWT/token creation and validation (`jwt/*`, `service/TokenService`). +- Password and secret handling (`authentication/*`, `util/PasswordUtil`, `encryption/*`). +- Default role/privilege definitions (`authorization/RoleManager`, `authorization/PrivilegeManager`). + +## Best Practices +- Treat security changes as high-risk and preserve secure defaults. +- Never store or log raw secrets/tokens/passwords. +- Keep role/privilege updates consistent with existing permission model and setup flows. +- Preserve compatibility with storage-backed user/group/role resolution. + +## Validation +- `mvn -pl streampipes-user-management -am test` diff --git a/ui/AGENTS.md b/ui/AGENTS.md new file mode 100644 index 0000000000..be8e7c44ca --- /dev/null +++ b/ui/AGENTS.md @@ -0,0 +1,35 @@ +# AGENTS Guide (UI) + +## Scope + +Applies to everything under `ui/` unless overridden by deeper `AGENTS.md` files. + +## Source of Truth + +- Follow: + - `ui/STYLEGUIDE.md` + - `ui/.eslintrc.json` + - `ui/.prettierrc.json` + - `ui/angular.json` + +## Build and Validation + +- Standard checks: + - `npm run lint` + - `npm run format` + - `npm test` +- For full app packaging, use: + - `npm run build` + +## UI Best Practices + +- Use shared design-system components before creating new equivalents (`sp-basic-view`, `sp-form-field`, `sp-table`, alert/banner components). +- Keep user-facing strings translatable (`| translate`). +- Keep button usage consistent (`mat-flat-button` per style guide). +- Keep feature logic in `ui/src/app`; keep shared/reusable building blocks in library projects. + +## Change Safety + +- Preserve routing and guard behavior in `ui/src/app/_guards`. +- Keep service contract compatibility with `@streampipes/platform-services` APIs. +- Prefer incremental UI changes over broad structural rewrites. diff --git a/ui/projects/streampipes/platform-services/AGENTS.md b/ui/projects/streampipes/platform-services/AGENTS.md new file mode 100644 index 0000000000..35e20cfce3 --- /dev/null +++ b/ui/projects/streampipes/platform-services/AGENTS.md @@ -0,0 +1,22 @@ +# AGENTS Guide (UI Platform Services) + +## Scope + +Applies to `ui/projects/streampipes/platform-services/`. + +## Module Intent + +- API client and platform-level model/query/service layer for the UI. +- Public surface is exported via `ui/projects/streampipes/platform-services/src/public-api.ts`. + +## Best Practices + +- Keep services transport-focused (HTTP/query/model mapping), not feature-UI specific. +- Treat exports in `src/public-api.ts` as compatibility-sensitive. +- Keep generated model files in `src/lib/model/gen/` stable; avoid manual edits unless regeneration is part of the task. +- Prefer typed request/response objects and explicit model mapping over `any`. + +## Validation + +- `ng build @streampipes/platform-services` +- `ng test @streampipes/platform-services` diff --git a/ui/projects/streampipes/shared-ui/AGENTS.md b/ui/projects/streampipes/shared-ui/AGENTS.md new file mode 100644 index 0000000000..8a76b5c8bd --- /dev/null +++ b/ui/projects/streampipes/shared-ui/AGENTS.md @@ -0,0 +1,23 @@ +# AGENTS Guide (UI Shared Components) + +## Scope + +Applies to `ui/projects/streampipes/shared-ui/`. + +## Module Intent + +- Reusable, cross-feature UI components/dialogs/services. +- Public surface is exported via `ui/projects/streampipes/shared-ui/src/public-api.ts`. + +## Best Practices + +- Keep components generic and reusable; avoid feature-specific business logic. +- Reuse existing shared primitives (`sp-table`, `sp-form-field`, `basic-*`, dialog base components) before adding new ones. +- Preserve UX and visual consistency with `ui/STYLEGUIDE.md`. +- Keep component APIs translation-friendly and accessibility-aware. +- Treat `src/public-api.ts` exports as a compatibility boundary. + +## Validation + +- `ng build @streampipes/shared-ui` +- `ng test @streampipes/shared-ui`
