From db9ebbbb41f3267cd92e95b01efac2901cb9b297 Mon Sep 17 00:00:00 2001 From: Florian Forster Date: Mon, 16 Feb 2026 20:45:53 -0800 Subject: [PATCH] chore(agents): add agents files (#11497) --- .cursorrules | 21 +++++++++++++ .github/copilot-instructions.md | 24 ++++++++++++++- .gitignore | 3 +- agents.md => AGENTS.md | 52 ++++++++++++++++++++++++++++++++- CONTRIBUTING.md | 8 ++--- apps/api/AGENTS.md | 22 ++++++++++++++ apps/docs/AGENTS.md | 24 +++++++++++++++ apps/login/AGENTS.md | 24 +++++++++++++++ console/AGENTS.md | 23 +++++++++++++++ internal/AGENTS.md | 20 +++++++++++++ packages/AGENTS.md | 18 ++++++++++++ proto/AGENTS.md | 17 +++++++++++ tests/functional-ui/AGENTS.md | 15 ++++++++++ 13 files changed, 263 insertions(+), 8 deletions(-) create mode 100644 .cursorrules rename agents.md => AGENTS.md (59%) create mode 100644 apps/api/AGENTS.md create mode 100644 apps/docs/AGENTS.md create mode 100644 apps/login/AGENTS.md create mode 100644 console/AGENTS.md create mode 100644 internal/AGENTS.md create mode 100644 packages/AGENTS.md create mode 100644 proto/AGENTS.md create mode 100644 tests/functional-ui/AGENTS.md diff --git a/.cursorrules b/.cursorrules new file mode 100644 index 0000000000..cd73648384 --- /dev/null +++ b/.cursorrules @@ -0,0 +1,21 @@ +# Cursor Rules for ZITADEL + +You are working in the ZITADEL monorepo. + +**ALWAYS** read `AGENTS.md` files in this order: +1. Root `AGENTS.md` +2. The nearest scoped `AGENTS.md` for the files you are changing + +If you touch Go code or run Go tooling, inspect `go.mod` first for the required Go version/toolchain. + +Use verified Nx targets only. If a target is unclear or missing, run `pnpm nx show project `. + +- **Root Context**: [AGENTS.md](AGENTS.md) +- **API App**: [apps/api/AGENTS.md](apps/api/AGENTS.md) +- **Login App**: [apps/login/AGENTS.md](apps/login/AGENTS.md) +- **Docs Site**: [apps/docs/AGENTS.md](apps/docs/AGENTS.md) +- **Management Console**: [console/AGENTS.md](console/AGENTS.md) +- **Backend Internal**: [internal/AGENTS.md](internal/AGENTS.md) +- **Proto Definitions**: [proto/AGENTS.md](proto/AGENTS.md) +- **Shared Packages**: [packages/AGENTS.md](packages/AGENTS.md) +- **Functional UI Tests**: [tests/functional-ui/AGENTS.md](tests/functional-ui/AGENTS.md) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 48a8ce1b60..f2f8cd1e2f 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1 +1,23 @@ -Always respect the terminology defined in the 'Technical Glossary' section of agents.md when generating UI text or documentation. +# GitHub Copilot Instructions for ZITADEL + +You are working in the ZITADEL monorepo. This codebase uses specific conventions for its Go backend and Angular/Next.js frontends. + +**CRITICAL**: Read `AGENTS.md` in the root first, then the nearest scoped `AGENTS.md` for changed files. + +## Key References +- `AGENTS.md`: Root architecture map and global commands. +- `apps/api/AGENTS.md`: API app workflows and backend orchestration targets. +- `apps/login/AGENTS.md`: Specifics for the Next.js Login UI. +- `apps/docs/AGENTS.md`: Specifics for the Fumadocs documentation. +- `console/AGENTS.md`: Specifics for the Angular Console. +- `internal/AGENTS.md`: Backend domain and event-sourcing boundaries. +- `proto/AGENTS.md`: API schema and generation guidance. +- `packages/AGENTS.md`: Shared client/proto package workflows. +- `tests/functional-ui/AGENTS.md`: Cypress functional UI test workflows. + +## Behavior +- Before Go-related work, inspect `go.mod` for required Go version/toolchain. +- Use verified Nx targets only; if unsure, run `pnpm nx show project `. +- For backend changes, note we are in transition: relational data is becoming the system of record, while event writes are still required for history/audit. +- Respect terminology defined in the `Technical Glossary` section of `AGENTS.md` when generating UI text or documentation. +- Distinguish between `apps/login` (Next.js) and `console` (Angular) when suggesting frontend code. diff --git a/.gitignore b/.gitignore index 94b8d77b58..f5c6eb6669 100644 --- a/.gitignore +++ b/.gitignore @@ -102,8 +102,7 @@ go.work.sum # AI Files CLAUDE.md -AGENTS.md .mcp.json .gemini/* -docs_old \ No newline at end of file +docs_old diff --git a/agents.md b/AGENTS.md similarity index 59% rename from agents.md rename to AGENTS.md index 4b162a8f05..d369ec312f 100644 --- a/agents.md +++ b/AGENTS.md @@ -1,3 +1,35 @@ +# ZITADEL Monorepo Guide for AI Agents + +## Mission & Context +ZITADEL is an open-source Identity Management System (IAM) written in Go and Angular/React. It provides secure login, multi-tenancy, and audit trails. + +## Read Order +1. Read this file first. +2. Read the nearest scoped `AGENTS.md` for the area you edit. +3. If multiple scopes apply, use the most specific path. + +## Repository Structure Map +- **`apps/`**: Consumer-facing web applications. + - **`login`**: Next.js authentication UI. See `apps/login/AGENTS.md`. + - **`docs`**: Fumadocs documentation app. See `apps/docs/AGENTS.md`. + - **`api`**: Backend Nx app target. See `apps/api/AGENTS.md`. +- **`console/`**: Angular Management Console. See `console/AGENTS.md`. +- **`internal/`**: Backend domain and service logic. See `internal/AGENTS.md`. +- **`proto/`**: API definitions. See `proto/AGENTS.md`. +- **`packages/`**: Shared TypeScript packages. See `packages/AGENTS.md`. +- **`tests/functional-ui/`**: Cypress functional UI tests. See `tests/functional-ui/AGENTS.md`. + +## Technology Stack & Conventions +- **Orchestration**: Nx is used for build and task orchestration. +- **Package Manager**: pnpm. +- **Backend**: + - **Go Version Source of Truth**: Inspect `go.mod` before Go work (`go` and optional `toolchain` directives). + - **Communication**: For V2 APIs, connectRPC is the primary transport. gRPC and HTTP/JSON endpoints are also supported. + - **Pattern**: The backend is transitioning to a relational design. Events are still persisted in a separate table for history/audit, but events are not the system of record. +- **Frontend**: + - **Console**: Angular + RxJS. + - **Login/Docs**: Next.js + React. + ## ZITADEL Domain & Multi-Tenancy Logic ### 1. Hierarchy & Ownership @@ -5,7 +37,7 @@ ZITADEL follows a strict hierarchical containment model. When generating code, logic, or translations, adhere to this structure: - **System (Installation):** The entire ZITADEL deployment. Global settings are applied through runtime configuration files or environment variables. See `cmd/defaults.yaml`. -- **Instance (The "Identity System"):** +- **Instance (The "Identity System"):** - **Definition:** A logical partition/virtual tenant. It is a "System inside a System." - **Isolation:** Data and configurations are strictly isolated between instances. - **Translation Rule:** NEVER translate as "Example" or "Case." Use technical terms like "Tenant," "Environment," or the local equivalent of "Logical System Entity." @@ -43,3 +75,21 @@ If a translation is requested for a language not listed above, follow these prio 2. **Priority 2 (System Entity):** Use a term that implies a "running process" or "logical environment." 3. **Priority 3 (Tenant):** If 'Instance' is ambiguous, use the local word for 'Tenant' (e.g., 租户 in Chinese). 4. **Strict Ban:** NEVER use words that mean "an illustration", "a case", "a sample", or "an example." + +## Command Rules +Run commands from the repository root. + +- Use verified Nx targets only. +- If target availability is unclear, run `pnpm nx show project `. +- Do not assume all projects have `test`, `lint`, `build`, or `generate` targets. +- Known exception: `@zitadel/console` has no configured `test` target. + +## Verified Common Targets +- `@zitadel/api`: `prod`, `build`, `generate`, `lint`, `test`, `test-unit`, `test-integration` +- `@zitadel/login`: `dev`, `build`, `lint`, `test`, `test-unit`, `test-integration` +- `@zitadel/docs`: `dev`, `build`, `generate`, `check-links`, `check-types`, `test`, `lint` +- `@zitadel/console`: `dev`, `build`, `generate`, `lint` + +## Documentation +- **Human Guide**: See `CONTRIBUTING.md` for setup and contribution details. +- **API Design**: See `API_DESIGN.md` for API specific guidelines. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cd027016c8..ec2a092694 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,13 +1,13 @@ # Contributing to Zitadel -Zitadel is an open-source identity and access management platform built with a modern tech stack including Go (API), Next.js/React (Login), Angular (Console), and Docusaurus (Docs) - all orchestrated through an Nx monorepo with pnpm for efficient development workflows. +Zitadel is an open-source identity and access management platform built with a modern tech stack including Go (API), Next.js/React (Login), Angular (Console), and Fumadocs (Docs) - all orchestrated through an Nx monorepo with pnpm for efficient development workflows. ## Quick Start 1. Clone the repository: `git clone https://github.com/zitadel/zitadel` or [open it in a local Dev Container](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/zitadel/zitadel) or [create a GitHub Codespace](https://codespaces.new/zitadel/zitadel) 2. If you cloned the repository to your local machine, install the required development dependencies - [Node.js v22.x](https://nodejs.org/en/download/) - Required for UI development and to run development commands `pnpm nx ...` - - [Go 1.24.x](https://go.dev/doc/install) - Required for API development + - [Go](https://go.dev/doc/install) - Required for API development. Use the version declared in `go.mod`. - [Docker](https://docs.docker.com/engine/install/) - Required for supporting services like the development database and for tests. - [Cypress runtime dependencies](https://docs.cypress.io/guides/continuous-integration/introduction#Dependencies) - Required for Browser UI tests
@@ -129,7 +129,7 @@ The code consists of the following parts: | API definitions | Specifications of the API | [Protobuf](https://developers.google.com/protocol-buffers) | [./proto/zitadel](./proto/zitadel) | [Contribute to API](#contribute-to-api) | | Management Console | Frontend the user interacts with after log in | [Angular](https://angular.io), [Typescript](https://www.typescriptlang.org) | [./console](./console) | [Contribute to Frontend](#contribute-to-frontend) | | Login | Modern authentication UI built with Next.js | [Next.js](https://nextjs.org), [React](https://reactjs.org), [TypeScript](https://www.typescriptlang.org) | [./apps/login](./apps/login) | [Contribute to Frontend](#contribute-to-frontend) | -| Docs | Project documentation made with docusaurus | [Docusaurus](https://docusaurus.io/) | [./apps/docs](./apps/docs) | [Contribute to Frontend](#contribute-to-frontend) | +| Docs | Project documentation made with Fumadocs | [Fumadocs](https://fumadocs.dev/) | [./apps/docs](./apps/docs) | [Contribute to Frontend](#contribute-to-frontend) | | translations | Internationalization files for default languages | YAML | [./console](./console) and [./internal](./internal) | [Contribute Translations](#contribute-translations) | Please follow the guides to validate and test the code before you contribute. @@ -368,7 +368,7 @@ Choose your contribution area: - **[Login App](#contribute-to-login)** (Next.js/React) - Modern authentication flows - **[Console](#contribute-to-console)** (Angular) - Admin dashboard and user management -- **[Docs](#contribute-to-docs)** (Docusaurus) - Project documentation +- **[Docs](#contribute-to-docs)** (Fumadocs) - Project documentation - **[Client Packages](#client-packages)** - Shared libraries for API communication ### Project Dependencies diff --git a/apps/api/AGENTS.md b/apps/api/AGENTS.md new file mode 100644 index 0000000000..b6b8d42fa0 --- /dev/null +++ b/apps/api/AGENTS.md @@ -0,0 +1,22 @@ +# ZITADEL API App Guide for AI Agents + +## Context +The **API App** (`apps/api`) is the Nx application target for building and running the Go backend. Most backend implementation lives in `internal/`, while this project orchestrates build, generate, lint, and test workflows. + +## Source of Truth +- **Go Toolchain**: Inspect root `go.mod` before Go work. +- **API Design Contract**: Follow `API_DESIGN.md` for service and resource conventions. +- **Domain Logic Location**: For implementation details, also read `internal/AGENTS.md`. + +## Verified Nx Targets +- **Run API (prod profile)**: `pnpm nx run @zitadel/api:prod` +- **Build**: `pnpm nx run @zitadel/api:build` +- **Generate (all)**: `pnpm nx run @zitadel/api:generate` +- **Lint**: `pnpm nx run @zitadel/api:lint` +- **Test (all)**: `pnpm nx run @zitadel/api:test` +- **Test (unit)**: `pnpm nx run @zitadel/api:test-unit` +- **Test (integration)**: `pnpm nx run @zitadel/api:test-integration` + +## Generation Notes +- `@zitadel/api:generate` can update generated, tracked files (stubs/assets/statik). Run it intentionally. +- API changes in `proto/` often require regenerating API, package, and docs artifacts. diff --git a/apps/docs/AGENTS.md b/apps/docs/AGENTS.md new file mode 100644 index 0000000000..ab42e6576b --- /dev/null +++ b/apps/docs/AGENTS.md @@ -0,0 +1,24 @@ +# ZITADEL Docs Guide for AI Agents + +## Context +The **Docs App** (`apps/docs`) hosts the ZITADEL documentation. It has recently migrated to **Fumadocs**. + +## Key Technology +- **Framework**: Fumadocs (built on Next.js). +- **Content**: MDX (Markdown + React Components). +- **Orchestration**: Nx. + +## Content Conventions +- **Frontmatter**: Ensure standard Fumadocs frontmatter is used (title, description). +- **Links**: Use absolute paths or standard MDX linking. +- **Components**: Use only MDX components that are documented in the official Fumadocs MDX component reference and any project-specific MDX component documentation in this repo; do not introduce or rely on undocumented components. +- **API Docs**: Changes in `proto/` or API response schemas often require regeneration via docs generation targets. + +## Verified Nx Targets +- **Dev Server**: `pnpm nx run @zitadel/docs:dev` +- **Build**: `pnpm nx run @zitadel/docs:build` +- **Generate**: `pnpm nx run @zitadel/docs:generate` +- **Lint**: `pnpm nx run @zitadel/docs:lint` +- **Check Links**: `pnpm nx run @zitadel/docs:check-links` +- **Check Types**: `pnpm nx run @zitadel/docs:check-types` +- **Test**: `pnpm nx run @zitadel/docs:test` diff --git a/apps/login/AGENTS.md b/apps/login/AGENTS.md new file mode 100644 index 0000000000..f8bd368624 --- /dev/null +++ b/apps/login/AGENTS.md @@ -0,0 +1,24 @@ +# ZITADEL Login App Guide for AI Agents + +## Context +The **Login App** (`apps/login`) provides the user interface for authentication flows (Login, Register, MFA, etc.). It is built with Next.js and React. + +## Key Technology +- **Framework**: Next.js (React). +- **Styling**: TailwindCSS, configured via `apps/login/tailwind.config.mjs`. +- **Data Fetching**: Primarily server-side interaction with ZITADEL APIs via `@zitadel/client` or direct gRPC calls where applicable. +- **Language**: TypeScript. + +## Architecture & Conventions +- **Routing**: Uses the Next.js App Router (routes are defined under `src/app/`). +- **Composability**: Components should be small and reusable. +- **State**: Critical authentication state is often managed via URL parameters (Auth Requests) and cookies/sessions. +- **Scope Rule**: For shared API typings and client behavior, also read `packages/AGENTS.md` and `proto/AGENTS.md`. + +## Verified Nx Targets +- **Dev Server**: `pnpm nx run @zitadel/login:dev` +- **Build**: `pnpm nx run @zitadel/login:build` +- **Lint**: `pnpm nx run @zitadel/login:lint` +- **Test (all)**: `pnpm nx run @zitadel/login:test` +- **Test (unit)**: `pnpm nx run @zitadel/login:test-unit` +- **Test (integration)**: `pnpm nx run @zitadel/login:test-integration` diff --git a/console/AGENTS.md b/console/AGENTS.md new file mode 100644 index 0000000000..537252304a --- /dev/null +++ b/console/AGENTS.md @@ -0,0 +1,23 @@ +# ZITADEL Console Guide for AI Agents + +## Context +The **Management Console** (`console/`) is the administrative interface for ZITADEL. It allows developers and administrators to configure organizations, projects, and users. + +## Key Technology +- **Framework**: Angular. +- **Language**: TypeScript. +- **State Management**: Reactive patterns with RxJS. +- **UI Component Library**: Angular Material (see `console/package.json`, `@angular/material` ^20.2.14). + +## Architecture & Conventions +- **Services**: Business logic should reside in injectable services, not components. +- **Modules**: Angular Modules (NgModule) are used for grouping features. +- **gRPC**: Heavy usage of gRPC-web or REST mappings to talk to the ZITADEL API. + +## Verified Nx Targets +- **Dev Server**: `pnpm nx run @zitadel/console:dev` +- **Build**: `pnpm nx run @zitadel/console:build` +- **Lint**: `pnpm nx run @zitadel/console:lint` +- **Generate**: `pnpm nx run @zitadel/console:generate` +- **Test**: The `@zitadel/console` project currently has no `test` target configured in Nx. +- **Functional UI Tests**: Use `pnpm nx run @zitadel/functional-ui:test` (see `tests/functional-ui/AGENTS.md`). diff --git a/internal/AGENTS.md b/internal/AGENTS.md new file mode 100644 index 0000000000..66688eb6f2 --- /dev/null +++ b/internal/AGENTS.md @@ -0,0 +1,20 @@ +# ZITADEL Internal Backend Guide for AI Agents + +## Context +`internal/` contains core backend domain logic for ZITADEL: commands, queries, repositories, eventstore integration, API service layers, and supporting infrastructure. + +## Source of Truth +- **Go Toolchain**: Inspect root `go.mod` before Go work. +- **Architecture Pattern**: Relational data is the system of record; keep existing event writes that provide history/audit trails. +- **API Contract**: For API-facing schema decisions, follow `API_DESIGN.md` and `proto/AGENTS.md`. + +## Boundary Rules +- Prefer implementing business behavior in command/query layers and repository packages, not in transport handlers. +- Avoid bypassing established event/repository flows with ad-hoc direct persistence patterns. +- Keep API/service adapters thin; place reusable domain behavior in internal domain packages. + +## Validation Workflow +- Use API project targets to validate backend changes: + - `pnpm nx run @zitadel/api:lint` + - `pnpm nx run @zitadel/api:test-unit` + - `pnpm nx run @zitadel/api:test-integration` diff --git a/packages/AGENTS.md b/packages/AGENTS.md new file mode 100644 index 0000000000..716f270218 --- /dev/null +++ b/packages/AGENTS.md @@ -0,0 +1,18 @@ +# ZITADEL Packages Guide for AI Agents + +## Context +`packages/` contains shared TypeScript libraries used by frontend applications and external consumers. + +## Main Packages +- **`packages/zitadel-proto`** (`@zitadel/proto`): generated protobuf TypeScript artifacts. +- **`packages/zitadel-client`** (`@zitadel/client`): higher-level client library built on generated proto/connect types. + +## Verified Nx Targets +- **Proto generation**: `pnpm nx run @zitadel/proto:generate` +- **Client build**: `pnpm nx run @zitadel/client:build` +- **Client lint**: `pnpm nx run @zitadel/client:lint` +- **Client tests**: `pnpm nx run @zitadel/client:test` + +## Workflow Notes +- When changing `proto/`, regenerate `@zitadel/proto` first, then validate/build `@zitadel/client`. +- Keep package exports and public typings stable unless a breaking release is explicitly intended. diff --git a/proto/AGENTS.md b/proto/AGENTS.md new file mode 100644 index 0000000000..855d7b0763 --- /dev/null +++ b/proto/AGENTS.md @@ -0,0 +1,17 @@ +# ZITADEL Proto Guide for AI Agents + +## Context +`proto/` defines ZITADEL API contracts. Changes here affect generated clients, backend stubs, and docs API references. + +## Source of Truth +- Follow `API_DESIGN.md` for naming, versioning, deprecations, and resource-oriented API design. +- Keep changes backward compatible within major versions unless a new major version is introduced. + +## Verified Nx Targets +- **Generate TS Proto Package**: `pnpm nx run @zitadel/proto:generate` +- **Generate API Assets/Stubs**: `pnpm nx run @zitadel/api:generate` +- **Generate Docs Artifacts**: `pnpm nx run @zitadel/docs:generate` + +## Workflow Notes +- After proto changes, validate dependent consumers (`@zitadel/client`, `@zitadel/api`, `@zitadel/docs`). +- If Go code is touched during generation or follow-up fixes, inspect root `go.mod` before running Go tooling. diff --git a/tests/functional-ui/AGENTS.md b/tests/functional-ui/AGENTS.md new file mode 100644 index 0000000000..87827d8b9c --- /dev/null +++ b/tests/functional-ui/AGENTS.md @@ -0,0 +1,15 @@ +# ZITADEL Functional UI Test Guide for AI Agents + +## Context +`tests/functional-ui` contains Cypress-based end-to-end tests focused on Management Console flows against a running ZITADEL API. + +## Verified Nx Targets +- **Open interactive Cypress runner**: `pnpm nx run @zitadel/functional-ui:open` +- **Run test suite**: `pnpm nx run @zitadel/functional-ui:test` +- **Start test DB only**: `pnpm nx run @zitadel/functional-ui:run-db` +- **Start test API only**: `pnpm nx run @zitadel/functional-ui:run-api` +- **Stop test infra**: `pnpm nx run @zitadel/functional-ui:stop` + +## Workflow Notes +- Functional UI tests are the primary test path for Console user journeys, since `@zitadel/console` has no Nx `test` target. +- These tests depend on API build/run orchestration; avoid changing API startup assumptions without updating this suite.