XingfenD
0b25a39e7b
- docs/ROADMAP.md: decompose enhancement work into sub-projects P0-P8 (ops foundation -> product value -> governance) with ordering rationale - docs/CHANGELOG.md: start the wrapper changelog - AGENTS.md: monorepo wrapper role, master-direct commits scoped to the wrapper, all specs/plans live in this repo's docs/ from now on
53 lines
4.4 KiB
Markdown
53 lines
4.4 KiB
Markdown
# AGENTS.md
|
|
|
|
## Repository role
|
|
|
|
Monorepo wrapper for the crearte full stack. This repo tracks `AGENTS.md`, `clone_all.sh`, and `docs/` (roadmap and all cross-repo design/plan docs). The three product repos are nested clones, each with its own git history and `AGENTS.md`:
|
|
|
|
```
|
|
crearte-monorepo/ # this repo (wrapper)
|
|
├── crearte/ # frontend (build context for web-* images)
|
|
├── crearte-server/ # backend Go API (build context for api-* images)
|
|
└── crearte-deploy/ # compose orchestration, no app code
|
|
```
|
|
|
|
Everything runs in containers. Do not introduce host-run workflows (no `npm run dev` / `go run` on the host) in docs, scripts, or compose.
|
|
|
|
## Safety Rules
|
|
|
|
- Branch naming: `{feat|fix|docs|chore}/{branch-name}` (e.g. `fix/compose-port-clash`).
|
|
- Commits in this monorepo wrapper may go directly on `master` (user-approved 2026-09-29). In the inner repos (`crearte/`, `crearte-server/`, `crearte-deploy/`): before `git commit`, run `git branch --show-current`. If on `master`, do NOT commit — ask the user for a branch name, create it, and commit there.
|
|
- `.env` is gitignored and must stay that way. Never commit secrets. Any new secret must land in `.env.example` as an empty placeholder (with a comment) in the same commit that introduces it.
|
|
- Changes → `docs/CHANGELOG.md` of the repo being changed (this wrapper's `docs/CHANGELOG.md`, or an inner repo's `docs/CHANGELOG.md` for its own changes). This workspace is not under `web/`, so `CHANGELOG_webui.md` never applies. Higher versions on top.
|
|
- CHANGELOG entry format: same entry has English line then Chinese line on consecutive lines (no blank line between them); different entries are separated by a blank line.
|
|
- Merging into `master`: always create a merge commit — `git merge --no-ff <branch>` (never fast-forward, the integration point must be recorded). Delete the merged branch afterwards.
|
|
- Compose changes that alter usage must update `README.md` in the same commit.
|
|
|
|
## Compose invariants (breaking these loses data or breaks the stack)
|
|
|
|
- Sibling layout: build contexts are `../crearte` and `../crearte-server`. Never repoint them or inline copies of the app code.
|
|
- dev and prod both publish host port `8080` — the profiles are mutually exclusive. Keep it that way unless README is updated accordingly.
|
|
- Volume names are data identity: renaming a volume orphans its data. Never rename `pgdata-*`, `bundle-keys-*`, `minio-data-*`, or the `*_node_modules` volumes.
|
|
- `db-test` (`pgdata-test`, 127.0.0.1:5432) is the integration-test database and is truncated freely. Never point `TEST_DATABASE_URL` at dev data — `db-debug` shares the `pgdata-dev` volume with `db-dev`, so a misdirected test run wipes development data.
|
|
- Never run `docker compose ... down -v` unless the user explicitly asks: it destroys postgres data, bundle keys, and MinIO objects, and the MinIO bucket init must then be redone by hand.
|
|
- Required secrets use `${VAR:?…}` so compose fails fast when missing. Keep the `:?` guard and `.env.example` in sync for every new secret.
|
|
- The one-time MinIO bucket init (`mc mb local/crearte` + anonymous download) exists because the volume is empty on first creation — do not silently automate it away; document any change in README.
|
|
- Keep `depends_on` health gating (api waits for `service_healthy` db); removing it makes first-boot races routine.
|
|
|
|
## Verification (required before claiming a compose change works)
|
|
|
|
1. `docker compose config -q` for each touched profile (`--profile dev|prod|debug|mock`).
|
|
2. `docker compose --profile <p> up -d --build`, then `docker compose ps` — healthchecks must pass.
|
|
3. Smoke-test the affected path (e.g. `docker compose exec api-dev wget -qO- http://127.0.0.1:8080/healthz`, or the upload flow through http://localhost:8080).
|
|
4. Tear down with plain `down` (never `-v`) unless the task is specifically about destroying data.
|
|
|
|
## Documentation
|
|
|
|
- All specs, implementation plans, roadmaps, and cross-repo coordination docs live in this wrapper's `docs/` (`docs/ROADMAP.md`, `docs/specs/`, `docs/plans/`). Do not scatter them into the inner repos; their `docs/superpowers/` copies are legacy (in `crearte` that path is gitignored). This supersedes the crearte-deploy 0.3.0 "canonical home" convention.
|
|
- Register every new spec/plan in the doc index table at the bottom of `docs/ROADMAP.md`.
|
|
|
|
## Layout notes
|
|
|
|
- No app code, no tests, no build scripts live here; those belong to `crearte` / `crearte-server`.
|
|
|