# ACS Bumper — Agent Instructions

Internal tool for TiDB Cloud delivery engineers. Built with Next.js 16, React 19, TypeScript, and Vitest. It manages image bumps and config/deployment sync across regions in the `app-delivery` repo.

All change workflows are **preview-first, then execute**, and all final changes are delivered via GitHub PRs.

## Tech Stack

- Next.js App Router
- TypeScript
- Vitest + Testing Library
- Tailwind CSS v4
- `simple-git`, `js-yaml`, `recharts`, `gh` CLI

## Core Product Model

### API Route Categories

- **Read**: query-only endpoints (for example regions and version stats).
- **Preview**: dry-run diff generation with preview tokens.
- **Execute**: SSE execution with token/hash re-check for TOCTOU protection.

### Domain Modules (`src/lib/`)

- `regions`: region discovery from directory conventions (`discovery`) and ArgoCd sync status (`argocd-sync-status`).
- `bump`: image bump planning/apply (`planner`), strategies, and section guardrails (`section-policy`).
- `sync`: `engine` (shared path-level YAML sync engine), `execution` (SSE stage orchestration and error mapping), `file-sync` (config/deployment pipeline adapter built on the engine).
- `checks`: post-PR validation gates (`image-tag-check`, `helm-dryrun-check`).
- `observe`: read models over the observability backends (summary/trends/logs/agents, `datasources/`, `client`).
- `api-route` / `api-client`: server-side response helpers and browser-side API parsing.

### Safety Constraints

All write pipelines must enforce:

- preview-token hash verification (TOCTOU prevention)
- type change rejection
- target conflict detection
- section policy checks for Vector/VMagent

## Engineering Workflow (TDD First)

TDD is the default and preferred workflow for all feature work and bug fixes.

Use **Red -> Green -> Refactor**:

1. Write a failing test that captures expected behavior.
2. Implement the minimum code to make the test pass.
3. Refactor while keeping tests green.

Do not start implementation by writing production code first unless there is a hard technical reason.

### Local Verification Commands

- `npm test` - run full test suite once
- `npm run test:watch` - watch mode
- `npm run typecheck` - TypeScript check
- `npm run lint` - ESLint check

Recommended pre-PR order:

1. `npm test`
2. `npm run typecheck`
3. `npm run lint`

## Unit Test Global Style

Follow the existing global test style in this project. Keep tests consistent with current files in `src/lib/`, `src/components/`, and `src/app/api/`.

- Co-locate test files with source: `foo.ts` -> `foo.test.ts`, `foo.tsx` -> `foo.test.tsx`.
- Use Vitest primitives (`describe`, `it`, `expect`, `vi`) and existing naming style.
- Prefer deterministic tests: no real network calls, no flaky time/random dependence.
- Use `vi.mock` / `vi.fn` for mocking, matching current conventions.
- Keep tests behavior-focused and readable; avoid over-coupling to implementation details.
- Add regression tests for bug fixes before implementing the fix.
- Remove obsolete tests promptly when related features, APIs, or behaviors are removed; do not keep stale legacy tests in the repository.

## UI and Style Global Style

Follow the existing global UI and styling conventions. Do not introduce a separate visual system.

- Reuse global design tokens from `src/app/globals.css` (semantic color variables and shared theme mapping).
- Prefer existing Tailwind utility patterns and component structure already used in `src/components/` and `src/app/`.
- Keep visual consistency across spacing, typography, borders, states, and interaction feedback.
- Avoid hardcoded one-off colors when a semantic token already exists.
- Keep style changes scoped, minimal, and aligned with existing pages.

## Change Scope Rules

- Make surgical changes only; avoid unrelated refactors.
- Follow existing naming, file layout, and test organization.
- Keep implementations simple (YAGNI) and easy to review.
- If behavior changes, update or add tests in the same change.
- If behavior is removed, delete superseded tests and legacy code in the same change.

## Done Criteria

A change is considered done only when:

- behavior is covered by tests (new or updated)
- `npm test` passes
- `npm run typecheck` passes
- `npm run lint` passes
- docs and behavior remain consistent with preview-first and safety constraints