81 lines
4.6 KiB
Markdown
81 lines
4.6 KiB
Markdown
## OliveTin – Agent Guide
|
||
|
||
This document helps AI agents contribute effectively to OliveTin.
|
||
|
||
If you are looking for OliveTin's AI policy, you can find it in `AI.md`.
|
||
|
||
### Project Overview
|
||
- **Service (Go)**: `service/` with business logic under `service/internal/*`
|
||
- API (Connect RPC): `service/internal/api`
|
||
- Command execution: `service/internal/executor`
|
||
- HTTP frontends/proxy: `service/internal/httpservers`
|
||
- Config/types/entities: `service/internal/config`, `service/internal/entities`
|
||
- **Frontend (Vue 3)**: `frontend/` (served by the service)
|
||
- **Integration tests**: `integration-tests/`
|
||
- **Protos/Generated**: `proto/`, `service/gen/...`
|
||
- **Specs**: `specs/` — Markdown specs that define how code should behave in human-readable form. When changing behavior in a spec-covered area, keep implementation and tests aligned with the spec; do not reference code or symbols in specs (English only).
|
||
|
||
### How to Run
|
||
- Run the server (dev):
|
||
- From repo root: `go run ./service`
|
||
- Unit tests (Go):
|
||
- From repo root: `cd service && make unittests`
|
||
- Code style (after editing code in `service/`):
|
||
- From repo root: `cd service && make codestyle`
|
||
- Integration tests (Mocha + Selenium):
|
||
- Single test: `cd integration-tests && npx --yes mocha test/general.mjs`
|
||
- All tests: `cd integration-tests && npx --yes mocha`
|
||
|
||
### Test Notes and Gotchas
|
||
- The top-level Makefile does not expose `unittests`; use `cd service && make unittests`.
|
||
- Connect RPC API must be mounted correctly; in tests, create the handler via `GetNewHandler(ex)` and serve under `/api/`.
|
||
- Frontend “ready” state: the app sets `document.body` attribute `loaded-dashboard="<name>"` when loading a dashboard. Integration helpers that test dashboard functionality wait for this before selecting elements. Certain conditions enforcing login will mean that this attribute is not set until a user is logged in.
|
||
- Modern UI uses Vue components:
|
||
- Action buttons are rendered as `.action-button button`.
|
||
- Logs and Diagnostics are Vue router links available via `/logs` and `/diagnostics`.
|
||
- Some legacy DOM ids (e.g., `contentActions`) no longer exist; prefer class-based selectors.
|
||
- Hidden UI features:
|
||
- Footer visibility is controlled by `showFooter` from Init API; tests may assert the footer is absent when config disables it.
|
||
|
||
### Coding Standards (Go)
|
||
- Avoid adding superflous comments that explain what the code is doing. Comments are only to describe business logic decisions.
|
||
- Prefer clear, descriptive names; avoid 1–2 letter identifiers.
|
||
- Use early returns and handle edge cases first.
|
||
- Do not swallow errors; propagate or log meaningfully.
|
||
- Match existing formatting; avoid unrelated reformatting.
|
||
- Be safe around nils in executor steps (e.g., guard `req.Binding` and `req.Binding.Action`).
|
||
- Cyclomatic complexity over 4 is not permitted.
|
||
|
||
### API and Execution Flow (High-level)
|
||
1. Client calls Connect RPC (e.g., `Init`, `GetDashboard`, `StartAction`).
|
||
2. API translates requests to `executor.ExecutionRequest` and calls `Executor.ExecRequest`.
|
||
3. Executor runs a chain of steps: request binding → concurrency/rate/ACL checks → arg parsing → exec → post-exec → logging/triggering.
|
||
4. Logs are stored and can be fetched via `ExecutionStatus`/`GetLogs`.
|
||
|
||
### Common Tasks
|
||
- Add/modify actions: update `config.yaml` and ensure `executor.RebuildActionMap()` is called when needed.
|
||
- Adjust dashboard rendering: see `service/internal/api/dashboards.go` and `apiActions.go`.
|
||
- Frontend behavior:
|
||
- Router: `frontend/resources/vue/router.js`
|
||
- Main shell/layout: `frontend/resources/vue/App.vue`
|
||
- Action button behavior: `frontend/resources/vue/ActionButton.vue`
|
||
|
||
### Contributing Checklist
|
||
- Review the contributing guidelines at `CONTRIBUTING.adoc`.
|
||
- Review the AI guidance in `AI.md`.
|
||
- Review the pull request template at `.github/PULL_REQUEST_TEMPLATE.md`.
|
||
- When changing behaviour covered by a spec in `specs/`, ensure implementation and tests match the spec.
|
||
|
||
### Branch Naming
|
||
Use conventional-commit-style branch names with a type prefix, optional issue reference, and a short kebab-case description:
|
||
|
||
- `feat/[#123]-add-justification-prompt`
|
||
- `fix/[#456]-websocket-reconnect`
|
||
|
||
Do **not** use `feat-...`, `feature/...`, or other variants. Omit the `[#<issue>]` segment only when there is no linked issue.
|
||
|
||
### Troubleshooting
|
||
- API tests failing with content-type errors: ensure Connect handler is served under `/api/` and the client targets that base URL.
|
||
- Executor panics: check for nil `Binding/Action` and add guards in step functions.
|
||
- Integration timeouts: wait for `loaded-dashboard` and use selectors matching the Vue UI.
|