2026-06-27 06:42:11 -07:00
|
|
|
# CLAUDE.md
|
|
|
|
|
|
|
|
|
|
Operational guide for AI agents working in this repo. Long-form human docs:
|
|
|
|
|
`CONTRIBUTING.md` (setup, testing philosophy) and `frontend/README.md`.
|
|
|
|
|
Read those before large changes. This file is the short, must-follow version.
|
docs: move architecture map into docs/ and refresh it against the live tree
The architecture/code map previously lived in .claude/CLAUDE.md, which was
gitignored (local-only) and auto-loaded into every agent session alongside
the root CLAUDE.md. Track it in docs/architecture.md instead and reference
it from CLAUDE.md so it is read on demand.
While moving it, fact-check the whole map against the current tree:
- add the missing internal/eventbus and internal/tunnelmonitor packages,
the service/email subpackage, and util/wirecodec
- document node mTLS (tls_client.go, node_mtls.go, setting_mtls.go) and the
fourth TLS verify mode
- add the Host, ClientExternalLink, NodeClientIp and ClientGlobalTraffic
models plus their symptom-index rows
- correct the cron table (check_cpu_usage is 1m not 10s; add
check_memory_usage and free_os_memory), the middleware chain
(MaxBodyBytes, ConfigEnvelope, CSRF) and the controller route prefixes
- refresh the sub/ and service/ file listings, frontend pages (hosts/,
index/), CI workflow list, and replace stale exact line counts with
rounded sizes
2026-07-02 05:21:21 -07:00
|
|
|
For a deep navigation map (request lifecycle, cron-job table, symptom → file
|
|
|
|
|
index, layering rules), read `docs/architecture.md` on demand — do not guess
|
|
|
|
|
file locations when it can answer in one hop.
|
2026-06-27 06:42:11 -07:00
|
|
|
|
|
|
|
|
## Stack
|
|
|
|
|
- Backend: Go 1.26 (`module github.com/mhsanaei/3x-ui/v3`), Gin, GORM.
|
|
|
|
|
Runs Xray-core as a managed child process (`internal/xray/process.go`) and
|
|
|
|
|
imports `github.com/xtls/xray-core` for config types + gRPC stats/handler/router
|
2026-07-06 07:04:32 -07:00
|
|
|
API. MTProto inbounds run a second managed child — the `mtg-multi` binary
|
docs(claude): correct enforced-guard claims and add the runtime dispatch rule
Fact-checked every line of CLAUDE.md against the tree. Six claims were wrong,
and two told an agent the opposite of the truth.
The file said nothing checks endpoints.ts against the Go routes and nothing
fails the build on a missing i18n key. Both guards exist and both run in
make verify: TestRouteRegistryContract diffs the real router against the
registry in both directions, and i18n-dead-keys.test.ts rejects a locale that
misses an en-US key as well as an en-US key nothing references. An agent
trusting the old text either skips a step it thinks is unenforced or is
blindsided when a "silent" omission turns the suite red.
The rest: the Go locale returns an empty string for an unknown key, not the raw
key; mtg-multi is a prebuilt binary fetched at build time, not a Go dependency
built from source; commits are type(area): summary, not <area>: summary, and
perf is in active use; make verify is the fast gate, not a mirror of CI, which
also runs race, vulncheck, a live-Postgres job where a SKIP is a failure, and a
fuzz smoke.
Add the five facts most likely to burn an agent, all reproduced before writing
them down. A fresh clone has no internal/web/dist, so go build dies on the embed
pattern while thirty-odd packages pass — it reads as a broken repo rather than a
missing make dist-stub. Every state-changing inbound/client op must dispatch
through runtime.Runtime; a direct xray/api.go call passes all local tests and
silently breaks every multi-node install, which is exactly what a hard rule is
for. Node 24 is required because make gen imports .ts directly. Postgres, xray
e2e and scale tests skip themselves without their env vars. An endpoint change
has a fourth step nothing checks: syncing docs/public/openapi.json.
Definition of done loses its first step — verify's gen-check already runs gen
and fails on a dirty generated diff.
2026-08-01 07:06:55 -07:00
|
|
|
(a multi-secret mtg fork — NOT a Go dependency; its prebuilt release binary is
|
|
|
|
|
fetched at image/release build time by `DockerInit.sh` + `release.yml`,
|
|
|
|
|
panel-side code in `internal/mtproto/`) — outside Xray, one process per inbound
|
|
|
|
|
serving each
|
feat(mtproto): per-client ad-tags, management-API auth, and record secret sync
Catch the panel up to the mtg-multi README (v1.14.0):
- Each client can now carry its own 32-hex advertising tag overriding the
inbound-level one. The tag lives on the client (settings JSON is the
source of truth, clients.ad_tag is the UI projection), is rendered into
the fork's [secret-ad-tags] section for active secrets only (mtg rejects
a config whose override names an unknown secret), is pushed per entry
through PUT /secrets, and is part of the reload fingerprint so a tag
edit hot-applies without dropping connections.
- The loopback management API can replace the whole secret set, so every
mtg process now gets a random per-process api-token; the manager sends
it as a bearer token on PUT /secrets and GET /stats and reuses it across
config rewrites, because mtg reads the token only at startup.
- Malformed tags are rejected at every save path and additionally dropped
in InstanceFromInbound: one bad tag would otherwise fail the whole
generated config and take every client of the inbound down with it.
- SyncInbound never copied a re-keyed mtproto secret into the canonical
clients table, so the clients page and subscription links kept serving
the old secret, which mtg then rejects. It is now guarded-copied like
the other credentials.
2026-07-07 03:00:43 -07:00
|
|
|
client's FakeTLS secret via the fork's `[secrets]` section (plus per-client
|
2026-07-08 06:30:56 -07:00
|
|
|
ad-tags via `[secret-ad-tags]` and per-client data quota / expiry via
|
|
|
|
|
`[secret-limits]`, mapped from the client's `totalGB`/`expiryTime`). Client,
|
|
|
|
|
ad-tag and quota/expiry edits are hot-applied through the fork's management API
|
|
|
|
|
(`PUT /secrets`, bearer-token guarded) so connections survive; the manager
|
|
|
|
|
falls back to a process restart on older binaries. A client's panel-side
|
|
|
|
|
traffic reset also calls `POST /secrets/{name}/reset-quota` so a renewed client
|
|
|
|
|
is not re-blocked by the sidecar's quota counter.
|
2026-06-27 06:42:11 -07:00
|
|
|
- Storage: SQLite by default (`/etc/x-ui/x-ui.db` on Linux; the executable dir on
|
|
|
|
|
Windows), PostgreSQL optional (`XUI_DB_TYPE` / `XUI_DB_DSN`). The CGo SQLite
|
|
|
|
|
driver (`mattn/go-sqlite3`) needs a C compiler — `CGO_ENABLED=0` builds fail.
|
|
|
|
|
- Frontend: React 19 + Ant Design 6 + Vite 8 + TypeScript in `frontend/`,
|
|
|
|
|
built into `internal/web/dist/` (gitignored) and embedded via `embed.FS`.
|
|
|
|
|
|
|
|
|
|
## Repo map
|
|
|
|
|
- `main.go` — entry point + `x-ui` CLI (run, migrate, migrate-db, setting, cert).
|
|
|
|
|
- `internal/config/` — env parsing (XUI_DEBUG, XUI_LOG_LEVEL, XUI_LOG_FOLDER,
|
|
|
|
|
XUI_BIN_FOLDER, XUI_SKIP_HSTS, XUI_PORT, XUI_DB_*).
|
docs(claude): correct enforced-guard claims and add the runtime dispatch rule
Fact-checked every line of CLAUDE.md against the tree. Six claims were wrong,
and two told an agent the opposite of the truth.
The file said nothing checks endpoints.ts against the Go routes and nothing
fails the build on a missing i18n key. Both guards exist and both run in
make verify: TestRouteRegistryContract diffs the real router against the
registry in both directions, and i18n-dead-keys.test.ts rejects a locale that
misses an en-US key as well as an en-US key nothing references. An agent
trusting the old text either skips a step it thinks is unenforced or is
blindsided when a "silent" omission turns the suite red.
The rest: the Go locale returns an empty string for an unknown key, not the raw
key; mtg-multi is a prebuilt binary fetched at build time, not a Go dependency
built from source; commits are type(area): summary, not <area>: summary, and
perf is in active use; make verify is the fast gate, not a mirror of CI, which
also runs race, vulncheck, a live-Postgres job where a SKIP is a failure, and a
fuzz smoke.
Add the five facts most likely to burn an agent, all reproduced before writing
them down. A fresh clone has no internal/web/dist, so go build dies on the embed
pattern while thirty-odd packages pass — it reads as a broken repo rather than a
missing make dist-stub. Every state-changing inbound/client op must dispatch
through runtime.Runtime; a direct xray/api.go call passes all local tests and
silently breaks every multi-node install, which is exactly what a hard rule is
for. Node 24 is required because make gen imports .ts directly. Postgres, xray
e2e and scale tests skip themselves without their env vars. An endpoint change
has a fourth step nothing checks: syncing docs/public/openapi.json.
Definition of done loses its first step — verify's gen-check already runs gen
and fails on a dirty generated diff.
2026-08-01 07:06:55 -07:00
|
|
|
- `internal/database/` + `internal/database/model/` — GORM schema (~24 models;
|
|
|
|
|
Inbound, Client, Setting, User are the core), inbound Protocol enum,
|
|
|
|
|
AutoMigrate + hand-written migrations in `db.go`.
|
2026-06-27 06:42:11 -07:00
|
|
|
- `internal/xray/` — Xray child-process lifecycle, config generation, gRPC API.
|
2026-07-06 07:04:32 -07:00
|
|
|
- `internal/mtproto/` — MTProto inbounds via the bundled `mtg-multi` binary.
|
2026-06-27 06:42:11 -07:00
|
|
|
- `internal/sub/` — subscription server (raw / JSON / Clash).
|
|
|
|
|
- `internal/eventbus/` — in-process pub/sub (outbound/node health, xray.crash,
|
|
|
|
|
cpu.high, memory.high, login.attempt).
|
|
|
|
|
- `internal/logger/`, `internal/util/` (link, crypto, sys, ldap, …),
|
|
|
|
|
`internal/tunnelmonitor/` — shared infrastructure.
|
|
|
|
|
- `internal/web/` — Gin server (embeds `dist/` + `translation/`).
|
|
|
|
|
- `controller/` — panel + REST API handlers; OpenAPI at /panel/api/openapi.json.
|
|
|
|
|
- `service/` — business logic (InboundService, SettingService, XrayService,
|
|
|
|
|
node sync); subpackages tgbot/, email/, outbound/, panel/, integration/.
|
docs(claude): correct enforced-guard claims and add the runtime dispatch rule
Fact-checked every line of CLAUDE.md against the tree. Six claims were wrong,
and two told an agent the opposite of the truth.
The file said nothing checks endpoints.ts against the Go routes and nothing
fails the build on a missing i18n key. Both guards exist and both run in
make verify: TestRouteRegistryContract diffs the real router against the
registry in both directions, and i18n-dead-keys.test.ts rejects a locale that
misses an en-US key as well as an en-US key nothing references. An agent
trusting the old text either skips a step it thinks is unenforced or is
blindsided when a "silent" omission turns the suite red.
The rest: the Go locale returns an empty string for an unknown key, not the raw
key; mtg-multi is a prebuilt binary fetched at build time, not a Go dependency
built from source; commits are type(area): summary, not <area>: summary, and
perf is in active use; make verify is the fast gate, not a mirror of CI, which
also runs race, vulncheck, a live-Postgres job where a SKIP is a failure, and a
fuzz smoke.
Add the five facts most likely to burn an agent, all reproduced before writing
them down. A fresh clone has no internal/web/dist, so go build dies on the embed
pattern while thirty-odd packages pass — it reads as a broken repo rather than a
missing make dist-stub. Every state-changing inbound/client op must dispatch
through runtime.Runtime; a direct xray/api.go call passes all local tests and
silently breaks every multi-node install, which is exactly what a hard rule is
for. Node 24 is required because make gen imports .ts directly. Postgres, xray
e2e and scale tests skip themselves without their env vars. An endpoint change
has a fourth step nothing checks: syncing docs/public/openapi.json.
Definition of done loses its first step — verify's gen-check already runs gen
and fails on a dirty generated diff.
2026-08-01 07:06:55 -07:00
|
|
|
- `job/` — 17 cron jobs (traffic, fail2ban IP-limit, node heartbeat/sync, LDAP,
|
|
|
|
|
CPU/memory watchdogs, …); full table in `docs/architecture.md` §5.4.
|
2026-06-27 06:42:11 -07:00
|
|
|
- `middleware/`, `entity/`, `global/`, `session/` (CSRF), `network/`,
|
|
|
|
|
`runtime/` (master/sub-node over mTLS), `websocket/`.
|
|
|
|
|
- `locale/` + `translation/` — i18n, 13 embedded locale JSON files.
|
|
|
|
|
- `frontend/` — React + TS source (see `frontend/CLAUDE.md`).
|
|
|
|
|
- `tools/openapigen/` — Go generator that emits frontend types + Zod/JSON schemas
|
|
|
|
|
into `frontend/src/generated/` from Go structs. The OpenAPI doc itself
|
|
|
|
|
(`frontend/public/openapi.json`) is assembled from those + `endpoints.ts` by
|
docs(claude): correct enforced-guard claims and add the runtime dispatch rule
Fact-checked every line of CLAUDE.md against the tree. Six claims were wrong,
and two told an agent the opposite of the truth.
The file said nothing checks endpoints.ts against the Go routes and nothing
fails the build on a missing i18n key. Both guards exist and both run in
make verify: TestRouteRegistryContract diffs the real router against the
registry in both directions, and i18n-dead-keys.test.ts rejects a locale that
misses an en-US key as well as an en-US key nothing references. An agent
trusting the old text either skips a step it thinks is unenforced or is
blindsided when a "silent" omission turns the suite red.
The rest: the Go locale returns an empty string for an unknown key, not the raw
key; mtg-multi is a prebuilt binary fetched at build time, not a Go dependency
built from source; commits are type(area): summary, not <area>: summary, and
perf is in active use; make verify is the fast gate, not a mirror of CI, which
also runs race, vulncheck, a live-Postgres job where a SKIP is a failure, and a
fuzz smoke.
Add the five facts most likely to burn an agent, all reproduced before writing
them down. A fresh clone has no internal/web/dist, so go build dies on the embed
pattern while thirty-odd packages pass — it reads as a broken repo rather than a
missing make dist-stub. Every state-changing inbound/client op must dispatch
through runtime.Runtime; a direct xray/api.go call passes all local tests and
silently breaks every multi-node install, which is exactly what a hard rule is
for. Node 24 is required because make gen imports .ts directly. Postgres, xray
e2e and scale tests skip themselves without their env vars. An endpoint change
has a fourth step nothing checks: syncing docs/public/openapi.json.
Definition of done loses its first step — verify's gen-check already runs gen
and fails on a dirty generated diff.
2026-08-01 07:06:55 -07:00
|
|
|
`frontend/scripts/build-openapi.mjs`. (`tools/seedperf/` is a separate seeding
|
|
|
|
|
/load helper.)
|
|
|
|
|
- `docs/` — separate Next.js/Fumadocs site (pnpm, own CI in `docs-ci.yml`,
|
|
|
|
|
outside `make verify`). Holds a THIRD independent implementation of
|
|
|
|
|
link/subscription generation in `docs/lib/xray/` — check it whenever
|
|
|
|
|
share-link or install-command output changes.
|
2026-06-27 06:42:11 -07:00
|
|
|
|
|
|
|
|
## Hard rules (non-negotiable)
|
2026-08-01 06:18:35 -07:00
|
|
|
- Fix size must match bug size. Find the root cause, then make the SMALLEST
|
|
|
|
|
change that removes it — a one-line guard beats a new subsystem. A small bug
|
|
|
|
|
does not earn new columns, jobs, abstractions, config knobs or helper layers.
|
|
|
|
|
If a fix genuinely needs new architecture, say so and get agreement first;
|
|
|
|
|
never ship it unasked next to the fix.
|
|
|
|
|
- Comments in committed Go/TS: 2 lines MAX per comment block. Make the name
|
|
|
|
|
carry the meaning first and rename rather than annotate; spend the 2 lines on
|
|
|
|
|
the *why* a name cannot hold — an invariant, an issue number, a non-obvious
|
|
|
|
|
constraint. Exempt: `//go:build`, `//go:generate`, and other directives.
|
2026-06-27 06:42:11 -07:00
|
|
|
HTML `<!-- -->` is fine. (A linter cannot enforce this — you must.)
|
|
|
|
|
- New `g.POST`/`g.GET` in `internal/web/controller/` REQUIRES a matching entry
|
|
|
|
|
in `frontend/src/pages/api-docs/endpoints.ts`, then `make gen` (or
|
docs(claude): correct enforced-guard claims and add the runtime dispatch rule
Fact-checked every line of CLAUDE.md against the tree. Six claims were wrong,
and two told an agent the opposite of the truth.
The file said nothing checks endpoints.ts against the Go routes and nothing
fails the build on a missing i18n key. Both guards exist and both run in
make verify: TestRouteRegistryContract diffs the real router against the
registry in both directions, and i18n-dead-keys.test.ts rejects a locale that
misses an en-US key as well as an en-US key nothing references. An agent
trusting the old text either skips a step it thinks is unenforced or is
blindsided when a "silent" omission turns the suite red.
The rest: the Go locale returns an empty string for an unknown key, not the raw
key; mtg-multi is a prebuilt binary fetched at build time, not a Go dependency
built from source; commits are type(area): summary, not <area>: summary, and
perf is in active use; make verify is the fast gate, not a mirror of CI, which
also runs race, vulncheck, a live-Postgres job where a SKIP is a failure, and a
fuzz smoke.
Add the five facts most likely to burn an agent, all reproduced before writing
them down. A fresh clone has no internal/web/dist, so go build dies on the embed
pattern while thirty-odd packages pass — it reads as a broken repo rather than a
missing make dist-stub. Every state-changing inbound/client op must dispatch
through runtime.Runtime; a direct xray/api.go call passes all local tests and
silently breaks every multi-node install, which is exactly what a hard rule is
for. Node 24 is required because make gen imports .ts directly. Postgres, xray
e2e and scale tests skip themselves without their env vars. An endpoint change
has a fourth step nothing checks: syncing docs/public/openapi.json.
Definition of done loses its first step — verify's gen-check already runs gen
and fails on a dirty generated diff.
2026-08-01 07:06:55 -07:00
|
|
|
`cd frontend && npm run gen`). Hand-maintained but pinned both ways by
|
|
|
|
|
`TestRouteRegistryContract` (`internal/web/routes_contract_test.go`): a missing
|
|
|
|
|
OR stale entry fails `make test-go`. Scope: `/panel/api/*` + a few session
|
|
|
|
|
routes; sub-server routes are exempt.
|
2026-06-27 06:42:11 -07:00
|
|
|
- Response examples come from Go struct `example:` tags via `tools/openapigen` —
|
|
|
|
|
never hand-write them. A new struct must be added to openapigen's `StructAllow`
|
|
|
|
|
allowlist (`tools/openapigen/main.go`) or it is silently omitted from
|
|
|
|
|
schemas/examples (and `build-openapi.mjs` then fails on the missing schema).
|
docs(claude): correct enforced-guard claims and add the runtime dispatch rule
Fact-checked every line of CLAUDE.md against the tree. Six claims were wrong,
and two told an agent the opposite of the truth.
The file said nothing checks endpoints.ts against the Go routes and nothing
fails the build on a missing i18n key. Both guards exist and both run in
make verify: TestRouteRegistryContract diffs the real router against the
registry in both directions, and i18n-dead-keys.test.ts rejects a locale that
misses an en-US key as well as an en-US key nothing references. An agent
trusting the old text either skips a step it thinks is unenforced or is
blindsided when a "silent" omission turns the suite red.
The rest: the Go locale returns an empty string for an unknown key, not the raw
key; mtg-multi is a prebuilt binary fetched at build time, not a Go dependency
built from source; commits are type(area): summary, not <area>: summary, and
perf is in active use; make verify is the fast gate, not a mirror of CI, which
also runs race, vulncheck, a live-Postgres job where a SKIP is a failure, and a
fuzz smoke.
Add the five facts most likely to burn an agent, all reproduced before writing
them down. A fresh clone has no internal/web/dist, so go build dies on the embed
pattern while thirty-odd packages pass — it reads as a broken repo rather than a
missing make dist-stub. Every state-changing inbound/client op must dispatch
through runtime.Runtime; a direct xray/api.go call passes all local tests and
silently breaks every multi-node install, which is exactly what a hard rule is
for. Node 24 is required because make gen imports .ts directly. Postgres, xray
e2e and scale tests skip themselves without their env vars. An endpoint change
has a fourth step nothing checks: syncing docs/public/openapi.json.
Definition of done loses its first step — verify's gen-check already runs gen
and fails on a dirty generated diff.
2026-08-01 07:06:55 -07:00
|
|
|
- A new or renamed endpoint has a FOURTH step nothing checks: copy
|
|
|
|
|
`frontend/public/openapi.json` → `docs/public/openapi.json`, then
|
|
|
|
|
`cd docs && pnpm gen:api` to refresh the MDX under
|
|
|
|
|
`docs/content/docs/en/reference/api/`. `docs-ci.yml` fires only on `docs/**`.
|
|
|
|
|
- A new English i18n key goes in EVERY locale JSON in `internal/web/translation/`
|
|
|
|
|
(13 files) AND must be referenced from `frontend/src` or Go in the SAME commit —
|
|
|
|
|
`frontend/src/test/i18n-dead-keys.test.ts` fails both ways. It is a frontend
|
|
|
|
|
test, so run `npm test`, not just `make test-go`. At runtime the frontend falls
|
|
|
|
|
back to en-US; Go (`internal/web/locale/`) returns "" for an unknown key.
|
2026-06-27 06:42:11 -07:00
|
|
|
- DB / model changes require a migration in `internal/database/db.go`.
|
docs(claude): correct enforced-guard claims and add the runtime dispatch rule
Fact-checked every line of CLAUDE.md against the tree. Six claims were wrong,
and two told an agent the opposite of the truth.
The file said nothing checks endpoints.ts against the Go routes and nothing
fails the build on a missing i18n key. Both guards exist and both run in
make verify: TestRouteRegistryContract diffs the real router against the
registry in both directions, and i18n-dead-keys.test.ts rejects a locale that
misses an en-US key as well as an en-US key nothing references. An agent
trusting the old text either skips a step it thinks is unenforced or is
blindsided when a "silent" omission turns the suite red.
The rest: the Go locale returns an empty string for an unknown key, not the raw
key; mtg-multi is a prebuilt binary fetched at build time, not a Go dependency
built from source; commits are type(area): summary, not <area>: summary, and
perf is in active use; make verify is the fast gate, not a mirror of CI, which
also runs race, vulncheck, a live-Postgres job where a SKIP is a failure, and a
fuzz smoke.
Add the five facts most likely to burn an agent, all reproduced before writing
them down. A fresh clone has no internal/web/dist, so go build dies on the embed
pattern while thirty-odd packages pass — it reads as a broken repo rather than a
missing make dist-stub. Every state-changing inbound/client op must dispatch
through runtime.Runtime; a direct xray/api.go call passes all local tests and
silently breaks every multi-node install, which is exactly what a hard rule is
for. Node 24 is required because make gen imports .ts directly. Postgres, xray
e2e and scale tests skip themselves without their env vars. An endpoint change
has a fourth step nothing checks: syncing docs/public/openapi.json.
Definition of done loses its first step — verify's gen-check already runs gen
and fails on a dirty generated diff.
2026-08-01 07:06:55 -07:00
|
|
|
- Every state-changing inbound/client op dispatches through `runtime.Runtime`
|
|
|
|
|
(`internal/web/runtime/`) — never straight to `internal/xray/api.go`, never from
|
|
|
|
|
a controller or cron job. A direct call passes every local test and silently
|
|
|
|
|
breaks every multi-node deployment. Other layering rules: `docs/architecture.md` §8.
|
|
|
|
|
- Conventional commits: `type(area): short imperative summary`, then a body
|
|
|
|
|
explaining the why. Types in use: `fix`, `feat`, `chore`, `refactor`, `perf`,
|
|
|
|
|
`docs`, `style`.
|
2026-06-27 06:42:11 -07:00
|
|
|
|
|
|
|
|
## Go conventions
|
|
|
|
|
- Stdlib `testing` only (no testify). Table-driven, `t.Run` subtests,
|
|
|
|
|
`t.Helper()` on helpers. Assert the exact value / typed error / emitted
|
|
|
|
|
string, never just `err != nil`. Prefer real deps over mocks: throwaway DB via
|
|
|
|
|
`database.InitDB(filepath.Join(t.TempDir(), "x-ui.db"))` +
|
|
|
|
|
`t.Cleanup(func() { _ = database.CloseDB() })`; `httptest` for HTTP.
|
|
|
|
|
`internal/sub`'s `initSubDB(t)` is the template.
|
2026-08-01 06:18:35 -07:00
|
|
|
- A test must fail without its fix. Write it, revert the fix, watch it go red,
|
|
|
|
|
restore. A test that passes either way is worse than no test: it certifies
|
|
|
|
|
nothing and then gets cited as proof the fix works.
|
|
|
|
|
- Test what can actually break. No test for a getter, a constant, a rename, a
|
|
|
|
|
pure map lookup, or inputs the function can never receive. One real test that
|
|
|
|
|
drives the bug through the actual code path beats five that restate the code.
|
2026-06-27 06:42:11 -07:00
|
|
|
- Code must pass `golangci-lint run` (gofumpt + goimports formatting): `make lint`.
|
docs(claude): correct enforced-guard claims and add the runtime dispatch rule
Fact-checked every line of CLAUDE.md against the tree. Six claims were wrong,
and two told an agent the opposite of the truth.
The file said nothing checks endpoints.ts against the Go routes and nothing
fails the build on a missing i18n key. Both guards exist and both run in
make verify: TestRouteRegistryContract diffs the real router against the
registry in both directions, and i18n-dead-keys.test.ts rejects a locale that
misses an en-US key as well as an en-US key nothing references. An agent
trusting the old text either skips a step it thinks is unenforced or is
blindsided when a "silent" omission turns the suite red.
The rest: the Go locale returns an empty string for an unknown key, not the raw
key; mtg-multi is a prebuilt binary fetched at build time, not a Go dependency
built from source; commits are type(area): summary, not <area>: summary, and
perf is in active use; make verify is the fast gate, not a mirror of CI, which
also runs race, vulncheck, a live-Postgres job where a SKIP is a failure, and a
fuzz smoke.
Add the five facts most likely to burn an agent, all reproduced before writing
them down. A fresh clone has no internal/web/dist, so go build dies on the embed
pattern while thirty-odd packages pass — it reads as a broken repo rather than a
missing make dist-stub. Every state-changing inbound/client op must dispatch
through runtime.Runtime; a direct xray/api.go call passes all local tests and
silently breaks every multi-node install, which is exactly what a hard rule is
for. Node 24 is required because make gen imports .ts directly. Postgres, xray
e2e and scale tests skip themselves without their env vars. An endpoint change
has a fourth step nothing checks: syncing docs/public/openapi.json.
Definition of done loses its first step — verify's gen-check already runs gen
and fails on a dirty generated diff.
2026-08-01 07:06:55 -07:00
|
|
|
- Postgres, xray-gRPC-e2e and scale tests `t.Skip` unless `XUI_TEST_PG_DSN`,
|
|
|
|
|
`XUI_DB_TYPE`+`XUI_DB_DSN`, `XRAY_E2E_BINARY` or `XUI_SCALE_TEST` is set — a
|
|
|
|
|
green `go test ./...` does not mean those paths ran.
|
2026-06-27 06:42:11 -07:00
|
|
|
|
|
|
|
|
## Frontend conventions (summary; full version in frontend/CLAUDE.md)
|
|
|
|
|
- Ant Design 6 only — no Tailwind/shadcn. Targeted tweaks, not rewrites.
|
|
|
|
|
- TS strict; `@typescript-eslint/no-explicit-any` is an error. Zod schemas in
|
|
|
|
|
`src/schemas/` are the source of truth; infer types with `z.infer`, never
|
|
|
|
|
hand-write. Do not edit `src/generated/`.
|
docs(claude): correct enforced-guard claims and add the runtime dispatch rule
Fact-checked every line of CLAUDE.md against the tree. Six claims were wrong,
and two told an agent the opposite of the truth.
The file said nothing checks endpoints.ts against the Go routes and nothing
fails the build on a missing i18n key. Both guards exist and both run in
make verify: TestRouteRegistryContract diffs the real router against the
registry in both directions, and i18n-dead-keys.test.ts rejects a locale that
misses an en-US key as well as an en-US key nothing references. An agent
trusting the old text either skips a step it thinks is unenforced or is
blindsided when a "silent" omission turns the suite red.
The rest: the Go locale returns an empty string for an unknown key, not the raw
key; mtg-multi is a prebuilt binary fetched at build time, not a Go dependency
built from source; commits are type(area): summary, not <area>: summary, and
perf is in active use; make verify is the fast gate, not a mirror of CI, which
also runs race, vulncheck, a live-Postgres job where a SKIP is a failure, and a
fuzz smoke.
Add the five facts most likely to burn an agent, all reproduced before writing
them down. A fresh clone has no internal/web/dist, so go build dies on the embed
pattern while thirty-odd packages pass — it reads as a broken repo rather than a
missing make dist-stub. Every state-changing inbound/client op must dispatch
through runtime.Runtime; a direct xray/api.go call passes all local tests and
silently breaks every multi-node install, which is exactly what a hard rule is
for. Node 24 is required because make gen imports .ts directly. Postgres, xray
e2e and scale tests skip themselves without their env vars. An endpoint change
has a fourth step nothing checks: syncing docs/public/openapi.json.
Definition of done loses its first step — verify's gen-check already runs gen
and fails on a dirty generated diff.
2026-08-01 07:06:55 -07:00
|
|
|
- Node 24 (`.nvmrc`) — `make gen` imports `.ts` directly and needs its type
|
|
|
|
|
stripping; Node 22 dies with `ERR_UNKNOWN_FILE_EXTENSION`. `npm test` includes
|
|
|
|
|
a headless-Chromium Storybook project, so run
|
|
|
|
|
`npx playwright install --with-deps chromium` once or `make verify` fails.
|
2026-06-27 06:42:11 -07:00
|
|
|
- Editing `frontend/src` does NOT change what users see until the Vite build is
|
|
|
|
|
regenerated into `internal/web/dist/`. In `XUI_DEBUG=true`, HTML is served from
|
|
|
|
|
the frozen embedded FS but JS/CSS off disk — after `npm run build` you MUST
|
|
|
|
|
restart `go run .` or you get a blank page with 404s.
|
|
|
|
|
- After touching share-link logic (`src/lib/xray/`), run `npm run test` (golden
|
|
|
|
|
fixtures); regenerate snapshots (`npx vitest run -u`) only for intentional
|
|
|
|
|
output changes, never to make a red test green.
|
|
|
|
|
|
|
|
|
|
## Build, test, verify
|
docs(claude): correct enforced-guard claims and add the runtime dispatch rule
Fact-checked every line of CLAUDE.md against the tree. Six claims were wrong,
and two told an agent the opposite of the truth.
The file said nothing checks endpoints.ts against the Go routes and nothing
fails the build on a missing i18n key. Both guards exist and both run in
make verify: TestRouteRegistryContract diffs the real router against the
registry in both directions, and i18n-dead-keys.test.ts rejects a locale that
misses an en-US key as well as an en-US key nothing references. An agent
trusting the old text either skips a step it thinks is unenforced or is
blindsided when a "silent" omission turns the suite red.
The rest: the Go locale returns an empty string for an unknown key, not the raw
key; mtg-multi is a prebuilt binary fetched at build time, not a Go dependency
built from source; commits are type(area): summary, not <area>: summary, and
perf is in active use; make verify is the fast gate, not a mirror of CI, which
also runs race, vulncheck, a live-Postgres job where a SKIP is a failure, and a
fuzz smoke.
Add the five facts most likely to burn an agent, all reproduced before writing
them down. A fresh clone has no internal/web/dist, so go build dies on the embed
pattern while thirty-odd packages pass — it reads as a broken repo rather than a
missing make dist-stub. Every state-changing inbound/client op must dispatch
through runtime.Runtime; a direct xray/api.go call passes all local tests and
silently breaks every multi-node install, which is exactly what a hard rule is
for. Node 24 is required because make gen imports .ts directly. Postgres, xray
e2e and scale tests skip themselves without their env vars. An endpoint change
has a fourth step nothing checks: syncing docs/public/openapi.json.
Definition of done loses its first step — verify's gen-check already runs gen
and fails on a dirty generated diff.
2026-08-01 07:06:55 -07:00
|
|
|
A fresh clone has no `internal/web/dist/`, so a bare `go build ./...` dies with
|
|
|
|
|
`pattern all:dist: no matching files found` while ~35 other packages pass — it
|
|
|
|
|
reads as a broken repo, not a missing step. Run `make dist-stub` once; every
|
|
|
|
|
`make` Go target already depends on it, which is why `make test-go` beats
|
|
|
|
|
`go test ./...`. Run `make help` for all targets. The local gate:
|
2026-06-27 06:42:11 -07:00
|
|
|
|
docs(claude): correct enforced-guard claims and add the runtime dispatch rule
Fact-checked every line of CLAUDE.md against the tree. Six claims were wrong,
and two told an agent the opposite of the truth.
The file said nothing checks endpoints.ts against the Go routes and nothing
fails the build on a missing i18n key. Both guards exist and both run in
make verify: TestRouteRegistryContract diffs the real router against the
registry in both directions, and i18n-dead-keys.test.ts rejects a locale that
misses an en-US key as well as an en-US key nothing references. An agent
trusting the old text either skips a step it thinks is unenforced or is
blindsided when a "silent" omission turns the suite red.
The rest: the Go locale returns an empty string for an unknown key, not the raw
key; mtg-multi is a prebuilt binary fetched at build time, not a Go dependency
built from source; commits are type(area): summary, not <area>: summary, and
perf is in active use; make verify is the fast gate, not a mirror of CI, which
also runs race, vulncheck, a live-Postgres job where a SKIP is a failure, and a
fuzz smoke.
Add the five facts most likely to burn an agent, all reproduced before writing
them down. A fresh clone has no internal/web/dist, so go build dies on the embed
pattern while thirty-odd packages pass — it reads as a broken repo rather than a
missing make dist-stub. Every state-changing inbound/client op must dispatch
through runtime.Runtime; a direct xray/api.go call passes all local tests and
silently breaks every multi-node install, which is exactly what a hard rule is
for. Node 24 is required because make gen imports .ts directly. Postgres, xray
e2e and scale tests skip themselves without their env vars. An endpoint change
has a fourth step nothing checks: syncing docs/public/openapi.json.
Definition of done loses its first step — verify's gen-check already runs gen
and fails on a dirty generated diff.
2026-08-01 07:06:55 -07:00
|
|
|
make verify # gen-check + lint + typecheck + test + build + build-storybook
|
|
|
|
|
|
|
|
|
|
That is the *fast* gate, not all of CI. `ci.yml` also runs `make race`,
|
|
|
|
|
`make vulncheck`, a live-Postgres job (where a SKIP counts as a failure) and a
|
|
|
|
|
30s fuzz smoke on `FuzzParseLink`/`FuzzDecodeCertPin` — run those locally when
|
|
|
|
|
you touch DB/dialect or parser code.
|
2026-06-27 06:42:11 -07:00
|
|
|
|
|
|
|
|
Common targets: `make gen` (regenerate Zod/OpenAPI), `make lint` (Go + frontend),
|
|
|
|
|
`make test` (Go `-shuffle=on` + frontend), `make race`, `make build`. See `Makefile`.
|
|
|
|
|
|
|
|
|
|
## Definition of done (before opening a PR)
|
docs(claude): correct enforced-guard claims and add the runtime dispatch rule
Fact-checked every line of CLAUDE.md against the tree. Six claims were wrong,
and two told an agent the opposite of the truth.
The file said nothing checks endpoints.ts against the Go routes and nothing
fails the build on a missing i18n key. Both guards exist and both run in
make verify: TestRouteRegistryContract diffs the real router against the
registry in both directions, and i18n-dead-keys.test.ts rejects a locale that
misses an en-US key as well as an en-US key nothing references. An agent
trusting the old text either skips a step it thinks is unenforced or is
blindsided when a "silent" omission turns the suite red.
The rest: the Go locale returns an empty string for an unknown key, not the raw
key; mtg-multi is a prebuilt binary fetched at build time, not a Go dependency
built from source; commits are type(area): summary, not <area>: summary, and
perf is in active use; make verify is the fast gate, not a mirror of CI, which
also runs race, vulncheck, a live-Postgres job where a SKIP is a failure, and a
fuzz smoke.
Add the five facts most likely to burn an agent, all reproduced before writing
them down. A fresh clone has no internal/web/dist, so go build dies on the embed
pattern while thirty-odd packages pass — it reads as a broken repo rather than a
missing make dist-stub. Every state-changing inbound/client op must dispatch
through runtime.Runtime; a direct xray/api.go call passes all local tests and
silently breaks every multi-node install, which is exactly what a hard rule is
for. Node 24 is required because make gen imports .ts directly. Postgres, xray
e2e and scale tests skip themselves without their env vars. An endpoint change
has a fourth step nothing checks: syncing docs/public/openapi.json.
Definition of done loses its first step — verify's gen-check already runs gen
and fails on a dirty generated diff.
2026-08-01 07:06:55 -07:00
|
|
|
1. `make verify` passes — its `gen-check` already runs `make gen` and fails on a
|
|
|
|
|
dirty `frontend/src/generated` / `frontend/public/openapi.json`.
|
|
|
|
|
2. Diff is focused; refactors are separate from feature work.
|