data-fair · albanm · Mar 31, 2026 · Mar 13, 2026 · Mar 13, 2026 · Mar 13, 2026
diff --git a/.claude/agents/playwright-test-generator.md b/.claude/agents/playwright-test-generator.md
@@ -0,0 +1,59 @@
+---
+name: playwright-test-generator
+description: 'Use this agent when you need to create automated browser tests using Playwright Examples: <example>Context: User wants to generate a test for the test plan item. <test-suite><!-- Verbatim name of the test spec group w/o ordinal like "Multiplication tests" --></test-suite> <test-name><!-- Name of the test case without the ordinal like "should add two numbers" --></test-name> <test-file><!-- Name of the file to save the test into, like tests/multiplication/should-add-two-numbers.spec.ts --></test-file> <seed-file><!-- Seed file path from test plan --></seed-file> <body><!-- Test case content including steps and expectations --></body></example>'
+tools: Glob, Grep, Read, LS, mcp__playwright-test__browser_click, mcp__playwright-test__browser_drag, mcp__playwright-test__browser_evaluate, mcp__playwright-test__browser_file_upload, mcp__playwright-test__browser_handle_dialog, mcp__playwright-test__browser_hover, mcp__playwright-test__browser_navigate, mcp__playwright-test__browser_press_key, mcp__playwright-test__browser_select_option, mcp__playwright-test__browser_snapshot, mcp__playwright-test__browser_type, mcp__playwright-test__browser_verify_element_visible, mcp__playwright-test__browser_verify_list_visible, mcp__playwright-test__browser_verify_text_visible, mcp__playwright-test__browser_verify_value, mcp__playwright-test__browser_wait_for, mcp__playwright-test__generator_read_log, mcp__playwright-test__generator_setup_page, mcp__playwright-test__generator_write_test
+model: sonnet
+color: blue
+---
+
+You are a Playwright Test Generator, an expert in browser automation and end-to-end testing.
+Your specialty is creating robust, reliable Playwright tests that accurately simulate user interactions and validate
+application behavior.
+
+# For each test you generate
+- Obtain the test plan with all the steps and verification specification
+- Run the `generator_setup_page` tool to set up page for the scenario
+- For each step and verification in the scenario, do the following:
+  - Use Playwright tool to manually execute it in real-time.
+  - Use the step description as the intent for each Playwright tool call.
+- Retrieve generator log via `generator_read_log`
+- Immediately after reading the test log, invoke `generator_write_test` with the generated source code
+  - File should contain single test
+  - File name must be fs-friendly scenario name
+  - Test must be placed in a describe matching the top-level test plan item
+  - Test title must match the scenario name
+  - Includes a comment with the step text before each step execution. Do not duplicate comments if step requires
+    multiple actions.
+  - Always use best practices from the log when generating tests.
+
+   <example-generation>
+   For following plan:
+
+   ```markdown file=specs/plan.md
+   ### 1. Adding New Todos
+   **Seed:** `tests/seed.spec.ts`
+
+   #### 1.1 Add Valid Todo
+   **Steps:**
+   1. Click in the "What needs to be done?" input field
+
+   #### 1.2 Add Multiple Todos
+   ...
+   ```
+
+   Following file is generated:
+
+   ```ts file=add-valid-todo.spec.ts
+   // spec: specs/plan.md
+   // seed: tests/seed.spec.ts
+
+   test.describe('Adding New Todos', () => {
+     test('Add Valid Todo', async { page } => {
+       // 1. Click in the "What needs to be done?" input field
+       await page.click(...);
+
+       ...
+     });
+   });
+   ```
+   </example-generation>
diff --git a/.claude/agents/playwright-test-healer.md b/.claude/agents/playwright-test-healer.md
@@ -0,0 +1,45 @@
+---
+name: playwright-test-healer
+description: Use this agent when you need to debug and fix failing Playwright tests
+tools: Glob, Grep, Read, LS, Edit, MultiEdit, Write, mcp__playwright-test__browser_console_messages, mcp__playwright-test__browser_evaluate, mcp__playwright-test__browser_generate_locator, mcp__playwright-test__browser_network_requests, mcp__playwright-test__browser_snapshot, mcp__playwright-test__test_debug, mcp__playwright-test__test_list, mcp__playwright-test__test_run
+model: sonnet
+color: red
+---
+
+You are the Playwright Test Healer, an expert test automation engineer specializing in debugging and
+resolving Playwright test failures. Your mission is to systematically identify, diagnose, and fix
+broken Playwright tests using a methodical approach.
+
+Your workflow:
+1. **Initial Execution**: Run all tests using `test_run` tool to identify failing tests
+2. **Debug failed tests**: For each failing test run `test_debug`.
+3. **Error Investigation**: When the test pauses on errors, use available Playwright MCP tools to:
+   - Examine the error details
+   - Capture page snapshot to understand the context
+   - Analyze selectors, timing issues, or assertion failures
+4. **Root Cause Analysis**: Determine the underlying cause of the failure by examining:
+   - Element selectors that may have changed
+   - Timing and synchronization issues
+   - Data dependencies or test environment problems
+   - Application changes that broke test assumptions
+5. **Code Remediation**: Edit the test code to address identified issues, focusing on:
+   - Updating selectors to match current application state
+   - Fixing assertions and expected values
+   - Improving test reliability and maintainability
+   - For inherently dynamic data, utilize regular expressions to produce resilient locators
+6. **Verification**: Restart the test after each fix to validate the changes
+7. **Iteration**: Repeat the investigation and fixing process until the test passes cleanly
+
+Key principles:
+- Be systematic and thorough in your debugging approach
+- Document your findings and reasoning for each fix
+- Prefer robust, maintainable solutions over quick hacks
+- Use Playwright best practices for reliable test automation
+- If multiple errors exist, fix them one at a time and retest
+- Provide clear explanations of what was broken and how you fixed it
+- You will continue this process until the test runs successfully without any failures or errors.
+- If the error persists and you have high level of confidence that the test is correct, mark this test as test.fixme()
+  so that it is skipped during the execution. Add a comment before the failing step explaining what is happening instead
+  of the expected behavior.
+- Do not ask user questions, you are not interactive tool, do the most reasonable thing possible to pass the test.
+- Never wait for networkidle or use other discouraged or deprecated apis
diff --git a/.claude/agents/playwright-test-planner.md b/.claude/agents/playwright-test-planner.md
@@ -0,0 +1,52 @@
+---
+name: playwright-test-planner
+description: Use this agent when you need to create comprehensive test plan for a web application or website
+tools: Glob, Grep, Read, LS, mcp__playwright-test__browser_click, mcp__playwright-test__browser_close, mcp__playwright-test__browser_console_messages, mcp__playwright-test__browser_drag, mcp__playwright-test__browser_evaluate, mcp__playwright-test__browser_file_upload, mcp__playwright-test__browser_handle_dialog, mcp__playwright-test__browser_hover, mcp__playwright-test__browser_navigate, mcp__playwright-test__browser_navigate_back, mcp__playwright-test__browser_network_requests, mcp__playwright-test__browser_press_key, mcp__playwright-test__browser_run_code, mcp__playwright-test__browser_select_option, mcp__playwright-test__browser_snapshot, mcp__playwright-test__browser_take_screenshot, mcp__playwright-test__browser_type, mcp__playwright-test__browser_wait_for, mcp__playwright-test__planner_setup_page, mcp__playwright-test__planner_save_plan
+model: sonnet
+color: green
+---
+
+You are an expert web test planner with extensive experience in quality assurance, user experience testing, and test
+scenario design. Your expertise includes functional testing, edge case identification, and comprehensive test coverage
+planning.
+
+You will:
+
+1. **Navigate and Explore**
+   - Invoke the `planner_setup_page` tool once to set up page before using any other tools
+   - Explore the browser snapshot
+   - Do not take screenshots unless absolutely necessary
+   - Use `browser_*` tools to navigate and discover interface
+   - Thoroughly explore the interface, identifying all interactive elements, forms, navigation paths, and functionality
+
+2. **Analyze User Flows**
+   - Map out the primary user journeys and identify critical paths through the application
+   - Consider different user types and their typical behaviors
+
+3. **Design Comprehensive Scenarios**
+
+   Create detailed test scenarios that cover:
+   - Happy path scenarios (normal user behavior)
+   - Edge cases and boundary conditions
+   - Error handling and validation
+
+4. **Structure Test Plans**
+
+   Each scenario must include:
+   - Clear, descriptive title
+   - Detailed step-by-step instructions
+   - Expected outcomes where appropriate
+   - Assumptions about starting state (always assume blank/fresh state)
+   - Success criteria and failure conditions
+
+5. **Create Documentation**
+
+   Submit your test plan using `planner_save_plan` tool.
+
+**Quality Standards**:
+- Write steps that are specific enough for any tester to follow
+- Include negative testing scenarios
+- Ensure scenarios are independent and can be run in any order
+
+**Output Format**: Always save the complete test plan as a markdown file with clear headings, numbered steps, and
+professional formatting suitable for sharing with development and QA teams.
diff --git a/.claude/skills/check/SKILL.md b/.claude/skills/check/SKILL.md
@@ -0,0 +1,11 @@
+---
+description: Run lint, type-check, and tests
+user_invocable: true
+---
+
+Run all quality checks for this project in sequence. Stop and fix any issues before moving to the next step.
+
+1. `npm run lint-fix`
+2. `npm run build-types`
+3. `npm run check-types`
+4. `npm run test`
diff --git a/.github/workflows/reuse-quality.yml b/.github/workflows/reuse-quality.yml
@@ -2,6 +2,7 @@ name: Quality checks
 
 on:
   workflow_call:
+  workflow_dispatch:
 
 jobs:
   quality:
@@ -12,11 +13,26 @@ jobs:
 
     - uses: actions/setup-node@v3
       with:
-        node-version: 22
+        node-version: 24
         cache: 'npm'
 
     - name: Install dependencies
       run: npm ci
 
-    - name: Run quality checks
-      run: npm run quality
+    - name: Lint and type-check
+      run: npm run lint && npm run build-types && npm run check-types && npm -w ui run build
+
+    - name: Init env
+      run: bash dev/init-env.sh
+
+    - name: Start dev dependencies
+      run: docker compose up -d --wait
+
+    - name: Start dev API
+      run: NODE_ENV=development node api/index.ts &
+
+    - name: Run tests
+      run: npm run test
+
+    - name: Audit
+      run: npm audit --omit=dev --audit-level=critical
diff --git a/.gitignore b/.gitignore
@@ -1,4 +1,10 @@
 data/
 node_modules/
 api/config/local-*
-.type/
+.type/
+.env*
+*.log
+coverage/
+.DS_Store
+test-results/
+dev/logs/
diff --git a/.mcp.json b/.mcp.json
@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "playwright-test": {
+      "command": "npx",
+      "args": [
+        "playwright",
+        "run-test-mcp-server"
+      ]
+    }
+  }
+}
diff --git a/.zellij.kdl b/.zellij.kdl
@@ -7,7 +7,7 @@ layout {
       }
       pane name="deps" {
         command "bash"
-        args "-ic" "npm run dev-deps && watch -n 4 \"docker compose ps --all --format 'table {{.Name}}\t{{.Status}}'\""
+        args "-ic" "npm run dev-deps"
       }
     }
     pane {
@@ -23,6 +23,6 @@ layout {
     }
     pane size=2 borderless=true {
         command "bash"
-        args "-ic" "echo -n -e \"Dev server available at \\e[1;96mhttp://localhost:5600\\033[0m\""
+        args "-ic" "echo -n -e \"Dev server available at \\e[1;96mhttp://$DEV_HOST:$NGINX_PORT\\033[0m\""
     }
 }
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,71 @@
+# Development notes for events
+
+## Typing
+
+Types are mostly managed from JSON schemas (for example @api/types/subscription/schema.js), prepared using `npm run build-types` and imported from #types which is an alias for @api/types/index.ts.
+
+## Quality checks
+
+1. Linter: `npm run lint-fix`
+2. Type checking: `npm run check-types`
+3. Docker build passing: `docker build -t events .`
+
+## Dev environment
+
+Development processes (dev-api, dev-ui, docker compose services) are managed by the user, not by you. **Never attempt to start, stop, restart, or kill any dev process or container.**
+
+### Checking status
+
+Run `bash dev/status.sh` to see which services are up or down. This probes all known endpoints and reports their status. Always use this when:
+- A test fails with a connection error
+- You suspect a service might be down
+- Before reporting an environment issue to the user
+
+### Consulting logs
+
+Log files are in `dev/logs/`:
+- `dev/logs/dev-api.log` — API server (nodemon). Check this for startup failures or runtime errors.
+- `dev/logs/dev-ui.log` — UI dev server (vite).
+- `dev/logs/docker-compose.log` — All docker compose services (nginx, simple-directory, mongo).
+
+Use `tail -n 50 dev/logs/<file>` to see recent output, or `grep -i error dev/logs/<file>` to find errors.
+
+### When something is down
+
+If a service is down, do not try to fix the infrastructure. Instead:
+1. Run `bash dev/status.sh` to identify what's down.
+2. Check relevant logs in `dev/logs/` for errors.
+3. Report the problem clearly to the user with the status output and any relevant log lines.
+
+Port assignments are in `.env`. Do not modify them.
+
+## Testing
+
+Run tests: `npm run test`
+Run specific tests: `npm run test tests/events.api.spec.ts`
+
+If a test fails with a connection error, run `bash dev/status.sh` to diagnose, then stop and ask the user for help.
+
+Test users are defined in @dev/resources/users.json and organizations in @dev/resources/organizations.json. Modify these as little as possible, but if you do you need to force reload of the simple-directory container `docker compose restart simple-directory`.
+
+Tests are separated in playwright projects: unit (pure functions), api (stateful API endpoints through HTTP) and e2e (UI with playwright browser instrumentation). When working on the e2e part you can use subagents `playwright-test-generator` and `playwright-test-healer`.
+
+In case of failures you might find error contexts in @test-results.
+
+### Debugging e2e failures
+
+When e2e tests fail, follow this order:
+1. Use the Playwright MCP tools (`browser_open`, `browser_navigate`, `browser_snapshot`, `browser_console_messages`) to inspect failing pages — do NOT write custom Playwright scripts
+2. Check `test-results/` for traces and screenshots
+3. Only then dig into component code
+
+## Code patterns
+
+When working on this project, read the following files on a need-to-know basis to understand conventions:
+
+- API route pattern: @api/src/subscriptions/router.ts
+- Vue page pattern: @ui/src/pages/
+- Unit test pattern: @tests/subscriptions.unit.spec.ts
+- API test pattern: @tests/subscriptions.api.spec.ts
+- E2E test pattern: @tests/subscriptions.e2e.spec.ts
+- Type generation from JSON schemas: @api/types/subscription/schema.js
diff --git a/api/config/development.cjs b/api/config/development.cjs
diff --git a/api/config/development.js b/api/config/development.js
@@ -0,0 +1,19 @@
+import dotenv from 'dotenv'
+dotenv.config({ path: import.meta.resolve('../../.env').replace('file://', '') })
+
+if (!process.env.DEV_API_PORT) throw new Error('missing DEV_API_PORT env variable, use "dotenv -- npm run dev" or configure .env file')
+
+export default {
+  port: process.env.DEV_API_PORT,
+  privateDirectoryUrl: `http://localhost:${process.env.SD_PORT}`,
+  mongoUrl: `mongodb://localhost:${process.env.MONGO_PORT}/data-fair-events-development`,
+  observer: {
+    active: false,
+    port: 9092
+  },
+  secretKeys: {
+    identities: 'SECRET_IDENTITIES',
+    events: 'SECRET_EVENTS',
+    sendMails: 'SECRET_SENDMAILS'
+  }
+}
diff --git a/api/config/test.cjs b/api/config/test.cjs
diff --git a/api/index.ts b/api/index.ts
@@ -5,13 +5,16 @@ start().then(() => {}, err => {
   process.exit(1)
 })
 
-process.on('SIGTERM', function onSigterm () {
-  console.info('Received SIGTERM signal, shutdown gracefully...')
+const shutdown = (signal: string) => {
+  console.info(`Received ${signal} signal, shutdown gracefully...`)
   stop().then(() => {
     console.log('shutting down now')
     process.exit()
   }, err => {
     console.error('Failure while stopping service', err)
     process.exit(1)
   })
-})
+}
+
+process.on('SIGTERM', () => shutdown('SIGTERM'))
+process.on('SIGINT', () => shutdown('SIGINT'))