Skip to content

AGENTS.md

Latest commit

 

History

History
105 lines (85 loc) · 4.61 KB

AGENTS.md

File metadata and controls

105 lines (85 loc) · 4.61 KB
Raw

AGENTS.md

Instructions for automated coding agents working in this repository.

Scope

These instructions apply to the whole repository.

Project Overview

bi-web is a Vue 2.7 frontend for Breeding Insight. It uses Vue CLI 4, TypeScript, Vuex, Vue Router, Buefy/Bulma, Vuelidate, CASL abilities, and an axios wrapper for API calls.

Important directories:

  • src/views: route-level pages.
  • src/components: reusable Vue components and layout templates.
  • src/store: Vuex root store and feature modules.
  • src/breeding-insight/model: application domain models.
  • src/breeding-insight/dao: raw API access using src/util/api.
  • src/breeding-insight/service: business logic and response mapping.
  • src/breeding-insight/brapi/model: generated BrAPI/OpenAPI models.
  • tests/unit: Jest and Vue Test Utils unit tests.
  • tests/e2e: Cypress end-to-end tests.
  • task: Node task wrappers used by npm scripts.

Setup

  • Use npm and package-lock.json; do not introduce Yarn or pnpm.
  • Use npm install for local setup, or npm ci for clean/install-in-CI style runs.
  • The Dockerfile uses Node 14 and npm 8.12.1. Avoid dependency or syntax changes that require a newer runtime unless the runtime is intentionally updated.
  • npm run githooks configures the repository's commit message hook.
  • Local environment overrides belong in ignored .env.local or .env.*.local files, not in tracked env files.

Common Commands

  • npm run serve: start the dev server. The default port is 8080; PORT overrides it.
  • npm run build: production build. The task wrapper runs npm audit checks before building.
  • npm run lint: run Vue CLI ESLint.
  • npm run test:unit: run existing Jest unit tests only when explicitly requested.
  • npm run test:e2e: run existing Cypress e2e tests only when explicitly requested.
  • npm run test:accessibility: run pa11y accessibility checks. This expects the dev server to be running and task/.pa11yTargets.json to exist; use it only when explicitly requested.

This repository does not add or maintain tests as part of normal feature or bug work. Do not create new tests, update existing tests, add test-only selectors, or spend time repairing unrelated test failures unless the user explicitly asks for test work. Prefer npm run lint, npm run build, or a focused manual smoke check for verification when practical.

Coding Conventions

  • Preserve the existing Apache 2.0 notice header when editing files that have it. Add the same header to new .ts, .js, and .vue source files.
  • Keep TypeScript strictness in mind. Prefer explicit domain models and local service/DAO patterns over loose any unless surrounding code already forces it.
  • Use the @/ alias for imports from src when consistent with nearby files.
  • Vue components commonly use class-style components with vue-property-decorator; match the surrounding component style.
  • ESLint requires long-form Vue directives: use v-bind: and v-on: instead of shorthand in templates.
  • Keep API calls centralized through src/util/api. DAOs should make HTTP requests, while services should handle application mapping and user-facing error logic.
  • src/breeding-insight/brapi/model files are generated by Swagger/OpenAPI. Do not hand-edit them unless the task explicitly calls for it.
  • Reuse existing layouts in src/components/layouts and visual conventions from the authenticated /style-guide page. Prefer existing Buefy/Bulma patterns and the configured Feather icon pack.

Configuration Notes

vue.config.js derives frontend runtime values from environment variables:

  • VUE_APP_BI_API_ROOT defaults to http://localhost.
  • VUE_APP_BI_API_V1_PATH is computed as ${VUE_APP_BI_API_ROOT}/v1.
  • VUE_APP_LOG_LEVEL defaults to error.
  • VUE_APP_BRAPI_VENDOR_SUBMISSION_ENABLED and VUE_APP_ALTERNATE_AUTHENTICATION_ENABLED are enabled only when set to the string true.

.env.development maps these values from shell environment variables such as API_BASE_URL, SANDBOX_MODE, and WEB_LOG_LEVEL.

Working Safely

  • Check git status --short before editing and do not overwrite unrelated local changes.
  • Do not commit generated output, node_modules, dist, local env files, IDE files, Cypress screenshots/videos, or task logs.
  • Do not change package-lock.json unless dependency changes are intentional.
  • Keep changes scoped to the requested behavior. Avoid broad refactors unless they are required to make the requested change safely.
  • If backend behavior is relevant, make the frontend assumption explicit in the code review or final notes; this repository only contains the web client.