Files
liqa/CLAUDE.md
ars9 78f4c35d56
CI / changes (push) Successful in 6s
CI / server (push) Skipped
CI / client (push) Skipped
CI / image (push) Skipped
docs(claude): forbid co-author trailers and issue refs in commits
- keep issue references like Closes #12 for pull request descriptions
2026-10-07 19:22:02 +03:00

6.6 KiB

liqa

liqa is a browser automation and QA service for web applications. 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; the schema is managed by migrations in server/src/database/migrations/ (see "Database migrations" in docs/development.md). Any entity change needs a generated migration - test/migrations.spec.ts fails otherwise. REST API under /api/v1, Swagger UI at /docs, MCP at /mcp, health at /health, public client configuration at /manifest.json.
  • client/ - React 19 + Vite SPA (i18n strings in client/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 context API, versioning, export/import, Playwright traces
  • docs/mcp.md - MCP tool reference
  • examples/ - ready-to-import example resources (YAML); server/test/examples.spec.ts imports each file, so keep them in sync with the import format
  • CHANGELOG.md - release notes per version
  • Dockerfile - single image: builds client and server, runtime serves both
  • .env.example - all configuration variables (validated in server/src/config/app.config.ts)

Default deployment (docker compose)

compose.yaml at the repo root runs a single liqa container, built from the root Dockerfile, at http://localhost:13000. The server serves everything: the UI at / (the built client, via CLIENT_DIR), the REST API at /api/v1, MCP at /mcp, Swagger at /docs. It reads .env if present (optional - every setting has a default) and mounts ./data (SQLite DB data/liqa.db + stored files).

Rebuild and restart: docker compose up -d --build. Check with docker compose ps, curl localhost:13000/health and docker compose logs liqa.

The live database is data/liqa.db. The container applies pending migrations before starting the server, so back it up before deploying a release with new migrations.

Branching

Never commit directly to master when implementing a feature, chore or bug fix: create a separate branch for the work first, forked from master. These commits don't change the version or CHANGELOG.md; the branch is merged back to master through a pull request. Only release commits (see "Releasing a new version") are made on master.

Never add a Co-Authored-By trailer to commit messages. Don't put issue references like Closes #12 in commit messages either; they belong only in the pull request description.

When committing on a work branch, also update the docs affected by the change (docs/*.md, README.md, .env.example, MCP tool descriptions) in the same branch.

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 && npm run test:storybook
  • Lint must stay clean in both packages (no errors, no warnings).
  • test:storybook runs every story in client/.storybook/stories/ in headless Chromium (needs npx playwright install --only-shell chromium once, and again after Playwright updates). Add or update a story when adding or changing a client/src/ui/ component.
  • 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, a Playwright mock (server/test/__mocks__/playwright.ts), and a temporary files directory per test app (see server/test/app.harness.ts).
  • Import Node.js built-in modules with the node: prefix (node:fs, node:path, node:crypto, ...).

Releasing a new version

A release is cut on master after one or more work branches have been merged (their pull request checks are already green). CI builds and pushes the Docker image only when a vX.Y.Z tag is pushed, not on merges.

When asked to release:

  1. Make sure you're on an up-to-date, clean master (git switch master && git pull), and collect the changes since the last release: git log --oneline "$(git describe --tags --abbrev=0)"..HEAD.

  2. Ask which version to bump - major, minor or patch - and propose a sensible default based on those 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).

  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 ## <version> - <YYYY-MM-DD> entry at the top of CHANGELOG.md ("Changes since :", then ### Added / ### Changed / ### Fixed). Mark breaking changes with Breaking:.

  5. Commit only these release changes on master. 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 <version>), not in the subject line. This overrides the skill's rule of putting versions in the subject.

  6. Tag the release commit with an annotated tag v<version> whose message is that version's CHANGELOG.md entry, verbatim (from its ## <version> heading up to the next version's heading). --cleanup=whitespace is required: the default cleanup strips lines starting with #, which would drop the entry's headings:

    v=<version>
    awk -v v="$v" 'index($0, "## " v " ") == 1 {p = 1; print; next} p && /^## / {exit} p' CHANGELOG.md \
      | git tag -a "v$v" --cleanup=whitespace -F -
    
  7. Ask the user before pushing, then push the commit and the tag together with git push --follow-tags (it also pushes annotated tags). The tag push triggers the image build; it fails if the tag doesn't match the package.json version.

  8. Ask the user whether to rebuild and restart the docker compose containers (docker compose up -d --build); don't do it without confirmation.