AGENTS.md · meshery/meshery

Sections

1. Repository Structure
2. Identifier Naming Conventions — MANDATORY
3. API Changes — MUST Go Through Schemas — MANDATORY
4. Build & Development Commands
5. Code Style & Conventions
6. Architecture
7. Testing
8. Security & Compliance
9. Agent Guardrails
10. Extensibility
11. Agent Tooling
12. Reusable Workflows Consumed by Other Repos
13. Further Reading
14. Maintaining this file

First lines (shown under the repo's Apache-2.0 license)

# Project Overview

Meshery is a self-service engineering platform and open source cloud native manager for Kubernetes infrastructure. A CNCF project supporting 300+ integrations with visual GitOps, multi-cluster management, and workspace collaboration.

## Repository Structure

| Directory | Purpose |
|-----------|---------|
| `/server` | Go backend — REST/GraphQL APIs, Kubernetes management, PostgreSQL |
| `/ui` | Next.js/React frontend — MUI, Redux Toolkit, Relay GraphQL |
| `/mesheryctl` | Go CLI with Cobra — install, lifecycle, pattern deployment |
| `/docs` | Hugo documentation site |
| `/install` | Dockerfiles, Kubernetes manifests, Helm charts |
| `/provider-ui` | Provider-specific React UI extensions |
| `/.github` | GitHub Actions, issue templates, Copilot agent definitions |

## Identifier Naming Conventions — MANDATORY

Authoritative guide: <https://github.com/meshery/schemas/blob/master/docs/identifier-naming-contributor-guide.md>

**Wire is camelCase; DB is snake_case; Go fields follow Go idiom; the ORM layer is the sole translation boundary.**

### Per-layer canonical forms

| Layer | Form |
|---|---|
| DB column / `db:` tag | `snake_case` — `user_id`, `org_id`, `created_at` |
| Go struct field | `PascalCase` with Go initialisms — `UserID`, `OrgID`, `CreatedAt` |
| JSON tag | `camelCase` — `json:"userId"`, `json:"orgId"` |
| URL query/path param | `camelCase` — `{orgId}`, `?userId=...` |
| TypeScript property | `camelCase` — `response.userId` |
| OpenAPI schema property | `camelCase` |
| OpenAPI `operationId` | `lower camelCase verbNoun` — `getWorkspaces` |
| `components/schemas` type name | `PascalCase` — `WorkspacePayload` |

### Forbidden (MUST NOT)

- MUST NOT use a `json:` tag matching the `db:` tag — wire is camel, DB is snake.
- MUST NOT hand-roll an RTK query endpoint when `@meshery/schemas/{mesheryApi,cloudApi}` provides one.
- MUST NOT locally redeclare a Go type with an equivalent in `github.com/meshery/schemas/models/...`.
- MUST NOT use `ID` (ALL CAPS) in URL params, JSON tags, or TypeScript properties — use `Id`.
- MUST NOT mix casing within a single resource; introduce a new API version to change wire format.
- MUST NOT import deprecated `v1beta1` in new code; use `v1beta3` (or `v1beta2` where v1beta3 absent).

### Required on every PR

- Run schemas validator: `cd ../schemas && make validate-schemas && make consumer-audit`
- Include test updates for casing/tag changes.
- Include doc updates for user-visible API changes.
- Sign off commits: `git commit -s`

> `meshery/schemas/AGENTS.md` is authoritative. On conflicts, schemas wins.

## API Changes — MUST Go Through Schemas — MANDATORY

**Any new or changed HTTP API (new endpoint, new/renamed query param, new
request/response field) MUST be defined in `meshery/schemas` first and consumed
via the generated client. Do NOT hand-roll RTK Query endpoints, response types,
or ad-hoc `fetch`/`axios` calls for an API that can live in schemas.**

Schemas is the single source of truth: one OpenAPI definition drives the Go
models, TypeScript types, and the RTK Query client (`@meshery/schemas/{mesheryApi,cloudApi}`)
consumed here. Hand-rolling any of these silently diverges the wire contract
across `meshery/meshery` and `meshery-cloud`.

Workflow: define the path in the construct's `api.yml` → regenerate in `../schemas`
(`make bundle-openapi generate-rtk generate-golang`) → validate
(`make validate-schemas && make consumer-audit`) → consume the generated hook.
The full steps, the SSE/streaming exception, the Go models-only rule, and the
release/local-link coupling are in
[Consuming schemas from meshery/meshery](./docs/content/en/project/contributing/contributing-schemas.md).

### Forbidden

- MUST NOT add a `builder.query`/`builder.mutation` in `ui/rtk-query/*` that
  issues a request to an API which is (or should be) defined in schemas.
- MUST NOT hand-write response/param TypeScript types or Go structs that
  duplicate a schemas-generated type.
- MUST NOT change wire casing/field names only in this repo — change the schema
  and regenerate (see the naming conventions above).
- MUST NOT re-declare a generated endpoint to attach a cache tag — use the
  callback form of `enhanceEndpoints` (`appendInvalidatesTags` from
  `ui/rtk-query/utils`). The object form replaces schemas-side tags wholesale.
- MUST NOT add a local endpoint whose name a generated one already defines — it
  is silently discarded dead code and a different request goes over the wire.
  Check first:
  `grep '<name>:t\.' ui/node_modules/@meshery/schemas/dist/mesheryApi.js`.
- MUST NOT keep a local copy of a contract Meshery only decodes from (or encodes
  to) a remote provider — it is the schemas construct, aliased. Where a Go type
  must stay local because it doubles as a GORM model, keep the JSON tags
  identical and pin the column with `gorm:"column:..."`.
- MUST NOT index a credential's persisted `secret` map directly — it has four
  shapes and legacy rows are never rewritten. Delegate to
  `server/models/credential_secret.go` or `ui/utils/credentialSecret.ts`, which
  must keep the same resolution rules.

Detail behind these rules:
[RTK Query integration](./docs/content/en/project/contributing/ui/schemas.md)
(cache tags, the deliberate-override exception, testing the *effective*
endpoint), [consuming schemas](./docs/content/en/project/contributing/contributing-schemas.md)
(consumed contracts, the Go side, rename propagation), and
[connections](./docs/content/en/project/contributing/models/connections.md)
(the credential shape catalogue).

## Build & Development Commands

- Use the `gh-axi` CLI tool to interact with GitHub. Prefer `gh-axi` over `gh`.
- Use `chrome-devtools-axi` for browser automation (navigate, snapshot, click, fill forms, run JS, inspect console/network) in place of raw Playwright/chrome-devtools MCP for ad hoc tasks.
- Run `quota-axi` to check local agent-provider quota windows before long-running work.
- Use the `lavish` skill (`lavish-axi` CLI) to turn a plan, comparison, or report into a reviewable HTML artifact.

### Server (Go)

```bash
make server                    # Run server locally (port 9081)
make server-local              # Run with local provider
make build-server              # Build binary
make golangci                  # Lint Go code
make server-skip-compgen       # Run without Kubernetes components
make server-without-operator   # Run without operator deployment
make error                     # Generate error codes
```

A build failing `compile: version "goX.Y.Z" does not match go tool version` across many
dependencies is a stale `GOROOT`, not a code problem — see
[build environment gotchas](./docs/content/en/project/contributing/contributing-build-environment.md).

### UI (Next.js/React)

```bash
make ui-setup              # Install dependencies
make ui                    # Dev server (port 3000)
make ui-build              # Build and export
make ui-lint               # Lint UI code
make ui-integration-tests  # Run E2E tests
```

- Never commit `ui/tsconfig.tsbuildinfo` — it is tracked and not gitignored, so any
  local `tsc --noEmit` dirties it. Stage explicit paths, never `git add -A`.
- A `@sistent/sistent` bump must cover all three consuming manifests (`ui/`,
  `provider-ui/`, `install/docker-extension/ui/`) and sistent's peers.
- After any local sibling-package build, re-verify with `npm ci` before trusting a
  green run — matching version strings do not prove the installed contents are the
  published ones.

### CLI (mesheryctl)

```bash
cd mesheryctl && make                       # Build binary
cd mesheryctl && go test --short ./...      # Unit tests
cd mesheryctl && go test -run Integration ./...  # Integration tests
make docs-mesheryctl                        # Generate CLI docs
```

`make docs-mesheryctl` rewrites ~100 pages with your local `$HOME` baked in — revert
every page whose only change is that path. See
[build environment gotchas](./docs/content/en/project/contributing/contributing-build-environment.md).

### Releasing