From ac123018185759209069a47e494590db9127a993 Mon Sep 17 00:00:00 2001 From: Andrii Arsenin Date: Wed, 30 Sep 2026 18:45:59 +0300 Subject: [PATCH] docs: add CLAUDE.md and rename compose file to compose.yaml - add CLAUDE.md with app overview, compose deployment details, doc references, code quality checks and the release/commit workflow - rename docker-compose.yaml to compose.yaml, the preferred compose spec file name --- CLAUDE.md | 58 +++++++++++++++++++++++++++++ docker-compose.yaml => compose.yaml | 0 2 files changed, 58 insertions(+) create mode 100644 CLAUDE.md rename docker-compose.yaml => compose.yaml (100%) diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..6903d2d --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,58 @@ +# liqa + +liqa (liquio-qa-bot) is a QA automation service for Liquio environments. It stores **scenarios** (ordered Playwright steps), **snippets** (reusable code run via `context.runSnippet`), **environments**, **credentials** and **sessions**, and runs scenarios in headless Chromium. Scenarios and snippets are versioned; each run records the scenario version it executed. + +It is an npm workspace with two packages: + +- `server/` - NestJS API + scheduler + MCP server, SQLite via TypeORM (`synchronize: true`, so entity changes alter the schema on startup - there are no migrations). REST API under `/api/v1`, Swagger UI at `/docs`, MCP at `/mcp`, health at `/health`. +- `client/` - React 19 + Vite SPA (i18n strings in `client/src/i18n/locales/en.json`). + +## Docs + +- [README.md](README.md) - overview +- [docs/architecture.md](docs/architecture.md) - services and modules +- [docs/development.md](docs/development.md) - local setup, running, testing, Docker +- [docs/scenario.md](docs/scenario.md) - scenario execution, script `context` API, versioning, export/import, Playwright traces +- [docs/mcp.md](docs/mcp.md) - MCP tool reference +- [CHANGELOG.md](CHANGELOG.md) - release notes per version +- [.env.example](.env.example) - all configuration variables (validated in `server/src/config/app.config.ts`) + +## Default deployment (docker compose) + +`compose.yaml` at the repo root runs two containers: + +| Service | URL | Notes | +|---|---|---| +| `server` | http://localhost:13000 | Built from `server/Dockerfile`; reads `.env`; mounts `./data` (SQLite DB `data/liqa.db` + stored files) and `./keys` | +| `client` | http://localhost:13001 | Built from `client/Dockerfile`; nginx serves the SPA and proxies `/api/` to `server:3000` | + +Rebuild and restart: `docker compose up -d --build`. Check with `docker compose ps`, `curl localhost:13000/health` and `docker compose logs server`. + +The live database is `data/liqa.db`. Because the schema is synced on startup, back it up before deploying entity changes. + +## Code quality + +Before committing, run and pass all of these (and report the results): + +```bash +# server +cd server && npm run lint && npx tsc --noEmit -p tsconfig.json && npm test && npm run build +# client +cd client && npm run lint && npm run build +``` + +- The server lint has some pre-existing errors (e.g. `no-explicit-any` in `test/mcp.controller.spec.ts`). Don't add new ones; compare against the last commit if unsure. +- Don't run prettier over whole existing files; several aren't prettier-clean and it produces unrelated diffs. Format only new files or the lines you changed. +- Server tests use an in-memory DB and a Playwright mock (`server/test/__mocks__/playwright.ts`). They create `server/data/` (git-ignored). + +## Committing a new version + +When asked to commit: + +1. **Ask which version to bump** - major, minor or patch - and propose a sensible default based on the changes: patch for fixes and small behavior/default tweaks, minor for new features, major for breaking changes (e.g. changed API or export/import formats that old clients or files can't use). +2. Run the code quality checks above. +3. Bump `version` in the root `package.json` and in both places at the top of `package-lock.json` (the root entry and `packages[""]`). `server/package.json` and `client/package.json` keep their own versions; don't bump them. +4. Add a `## - ` entry at the top of `CHANGELOG.md` ("Changes since :", then `### Added` / `### Changed` / `### Fixed`). Mark breaking changes with **Breaking:**. +5. Update the docs affected by the change (`docs/*.md`, `README.md`, `.env.example`, MCP tool descriptions). +6. Build the commit message with the `/git-commit` skill if it is available, following its format and rules. Otherwise use a conventional commit message (`type(scope): subject`, then a bullet list body). Either way, put the version bump in the body as a bullet (e.g. `- bump version to `), not in the subject line. This overrides the skill's rule of putting versions in the subject. Then make the commit with that message. +7. **After committing, ask the user whether to rebuild and restart the docker compose containers** (`docker compose up -d --build`); don't do it without confirmation. diff --git a/docker-compose.yaml b/compose.yaml similarity index 100% rename from docker-compose.yaml rename to compose.yaml