- 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
4.1 KiB
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 inclient/src/i18n/locales/en.json).
Docs
- README.md - overview
- docs/architecture.md - services and modules
- docs/development.md - local setup, running, testing, Docker
- docs/scenario.md - scenario execution, script
contextAPI, versioning, export/import, Playwright traces - docs/mcp.md - MCP tool reference
- CHANGELOG.md - release notes per version
- .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):
# 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-anyintest/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 createserver/data/(git-ignored).
Committing a new version
When asked to commit:
- 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).
- Run the code quality checks above.
- Bump
versionin the rootpackage.jsonand in both places at the top ofpackage-lock.json(the root entry andpackages[""]).server/package.jsonandclient/package.jsonkeep their own versions; don't bump them. - Add a
## <version> - <YYYY-MM-DD>entry at the top ofCHANGELOG.md("Changes since :", then### Added/### Changed/### Fixed). Mark breaking changes with Breaking:. - Update the docs affected by the change (
docs/*.md,README.md,.env.example, MCP tool descriptions). - Build the commit message with the
/git-commitskill 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 <version>), not in the subject line. This overrides the skill's rule of putting versions in the subject. Then make the commit with that message. - 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.