OliveTin/AGENTS.md

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/...

How to Run

• Run the server (dev):
  • From repo root: go run ./service
• Unit tests (Go):
  • From repo root: cd service && make unittests
• 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 initial-marshal-complete="true" when loaded. Integration helpers wait for this before selecting elements.
• 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).

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.

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 initial-marshal-complete and use selectors matching the Vue UI.