code-ai-installer 3.0.0 → 4.0.0

package/domains/development/locales/en/.agents/skills/tdd-workflow-reference/SKILL.md

@@ -0,0 +1,458 @@
+---
+name: tdd-workflow-reference
+description: "Canonical TDD code reference — detailed DO/DON'T examples across 5 topics — Unit tests (Vitest, mocks), Integration tests (supertest, HTTP+DB), React components (Testing Library, renderHook), E2E (Playwright), antipatterns (brittle selectors, dependencies, missing error paths). Activate when looking up a specific TDD pattern."
+type: reference
+domain: development
+owners:
+  - senior_full_stack
+gates:
+  - DEV
+tech: []
+topic:
+  - general
+  - testing
+triggers:
+  - TDD code example
+  - Vitest mock code
+  - supertest integration code
+  - Testing Library getByRole code
+  - renderHook useDebounce code
+  - Playwright e2e code
+  - antipattern test example
+related:
+  - tdd-workflow
+  - testing-strategy-js
+  - testing-strategy-js-reference
+  - react-beast-practices
+  - typescript-beast-practices
+  - typescript-beast-practices-reference
+  - qa-e2e-playwright
+  - tests-quality-review
+  - dev-reference-snippets
+budget_lines: 750
+schema_version: 1
+---
+
+
+# Skill: TDD Code Reference (DO/DON'T)
+
+Canonical reference of TDD code patterns. Decision rules + algorithm + checklists — in `$tdd-workflow`.
+
+**Sections:**
+2. [Formulation of test cases](#2-formulation)
+3. [Unit tests](#3-unit)
+4. [Integration tests](#4-integration)
+5. [React components](#5-react)
+6. [E2E (Playwright)](#6-e2e)
+7. [Antipatterns](#7-antipatterns)
+
+> Algorithm RED→GREEN→REFACTOR + 2 checklists + level table → `$tdd-workflow` §1, §6.
+
+---
+
+## 2. Formulation of test cases
+
+### ✅ DO: user journey template → test cases
+```
+User Journey: "A manager creates a new user in the system"
+
+Happy path:
+  - creates a user with valid data → returns id and status 201
+
+Edge cases:
+  - email is already taken → returns 409 CONFLICT
+  - name is empty → returns 422 VALIDATION_ERROR
+  - email without @ → returns 422 VALIDATION_ERROR
+  - role is not from enum → returns 422 VALIDATION_ERROR
+
+Error paths:
+  - DB is unavailable → returns 500, does not leak error details
+  - unauthorized request → returns 401
+  - authorized but not admin → returns 403
+```
+
+### ✅ DO: naming tests — "what it does under what condition"
+```ts
+// ✅ Good: the test case reads like a specification
+describe("usersService.create", () => {
+  it("returns new user id when input is valid", ...);
+  it("throws CONFLICT when email already exists", ...);
+  it("throws VALIDATION_ERROR when email is malformed", ...);
+  it("throws UNAUTHORIZED when actor is not authenticated", ...);
+});
+
+// ❌ Bad: uninformative names
+describe("usersService", () => {
+  it("works", ...);
+  it("test1", ...);
+  it("should do stuff", ...);
+});
+```
+
+---
+
+## 3. Unit tests
+
+### ✅ DO: test behavior, not implementation details
+```ts
+// ─── Tested function ───────────────────────────────────────────
+// src/lib/pricing.ts
+export function calculateDiscount(price: number, userType: "regular" | "premium"): number {
+  if (price <= 0) throw new Error("Price must be positive");
+  const rate = userType === "premium" ? 0.2 : 0.05;
+  return Math.round(price * rate * 100) / 100;
+}
+
+// ─── Tests ────────────────────────────────────────────────────────
+// src/lib/pricing.test.ts
+import { describe, it, expect } from "vitest";
+import { calculateDiscount } from "./pricing";
+
+describe("calculateDiscount", () => {
+  // ✅ Happy path
+  it("applies 5% discount for regular users", () => {
+    expect(calculateDiscount(100, "regular")).toBe(5);
+  });
+
+  it("applies 20% discount for premium users", () => {
+    expect(calculateDiscount(100, "premium")).toBe(20);
+  });
+
+  // ✅ Edge cases
+  it("rounds to 2 decimal places", () => {
+    expect(calculateDiscount(99.99, "regular")).toBe(5); // 4.9995 → 5
+  });
+
+  // ✅ Error paths
+  it("throws when price is zero", () => {
+    expect(() => calculateDiscount(0, "regular")).toThrow("Price must be positive");
+  });
+
+  it("throws when price is negative", () => {
+    expect(() => calculateDiscount(-10, "regular")).toThrow("Price must be positive");
+  });
+});
+```
+
+### ✅ DO: mock dependencies, not details
+```ts
+// src/domain/services/users.service.test.ts
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { usersService } from "./users.service";
+import { usersRepo } from "../../data/repos/users.repo";
+
+// ✅ Mock the repository (external dependency), not ORM or SQL
+vi.mock("../../data/repos/users.repo");
+
+const mockRepo = vi.mocked(usersRepo);
+
+describe("usersService.create", () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it("returns created user when email is not taken", async () => {
+    mockRepo.findByEmail.mockResolvedValue(null);
+    mockRepo.insert.mockResolvedValue({ id: "usr_1", email: "a@b.com", name: "Alice" });
+
+    const user = await usersService.create({ email: "a@b.com", name: "Alice" });
+
+    expect(user.id).toBe("usr_1");
+    expect(mockRepo.insert).toHaveBeenCalledWith({ email: "a@b.com", name: "Alice" });
+  });
+
+  it("throws CONFLICT when email is already taken", async () => {
+    mockRepo.findByEmail.mockResolvedValue({ id: "existing", email: "a@b.com", name: "Bob" });
+
+    await expect(usersService.create({ email: "a@b.com", name: "Alice" }))
+      .rejects.toMatchObject({ code: "CONFLICT" });
+
+    expect(mockRepo.insert).not.toHaveBeenCalled(); // ✅ did not create a duplicate
+  });
+});
+```
+
+---
+
+## 4. Integration tests
+
+### ✅ DO: test the HTTP layer from route to response
+```ts
+// src/http/routes/users.routes.test.ts
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import request from "supertest";
+import { app } from "../../app";
+import { db } from "../../lib/db";
+import { seedTestUser, cleanupTestData } from "../../test/helpers";
+
+describe("POST /api/users", () => {
+  beforeAll(() => db.connect());
+  afterAll(async () => {
+    await cleanupTestData();
+    await db.disconnect();
+  });
+
+  // ✅ Happy path: check status and response shape
+  it("returns 201 and user id when input is valid", async () => {
+    const res = await request(app)
+      .post("/api/users")
+      .set("Authorization", "Bearer test-admin-token")
+      .send({ email: "new@example.com", name: "Alice" });
+
+    expect(res.status).toBe(201);
+    expect(res.body).toMatchObject({ id: expect.stringMatching(/^usr_/) });
+  });
+
+  // ✅ Validation: check error_code, not the message text (it can change)
+  it("returns 422 when email is malformed", async () => {
+    const res = await request(app)
+      .post("/api/users")
+      .set("Authorization", "Bearer test-admin-token")
+      .send({ email: "not-an-email", name: "Alice" });
+
+    expect(res.status).toBe(422);
+    expect(res.body.error_code).toBe("VALIDATION_ERROR");
+    expect(res.body.details).toBeDefined();
+  });
+
+  // ✅ Conflict
+  it("returns 409 when email already exists", async () => {
+    await seedTestUser({ email: "existing@example.com" });
+
+    const res = await request(app)
+      .post("/api/users")
+      .set("Authorization", "Bearer test-admin-token")
+      .send({ email: "existing@example.com", name: "Bob" });
+
+    expect(res.status).toBe(409);
+    expect(res.body.error_code).toBe("CONFLICT");
+  });
+
+  // ✅ Authentication
+  it("returns 401 without auth token", async () => {
+    const res = await request(app)
+      .post("/api/users")
+      .send({ email: "a@b.com", name: "Alice" });
+
+    expect(res.status).toBe(401);
+  });
+});
+```
+
+---
+
+## 5. React components
+
+### ✅ DO: Testing Library — roles and text, not classes and id
+```tsx
+// src/components/LoginForm.test.tsx
+import { describe, it, expect, vi } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { LoginForm } from "./LoginForm";
+
+describe("LoginForm", () => {
+  it("calls onSubmit with email and password on valid submit", async () => {
+    const user = userEvent.setup();
+    const onSubmit = vi.fn().mockResolvedValue(undefined);
+    render(<LoginForm onSubmit={onSubmit} />);
+
+    // ✅ Search by role and label — like a user
+    await user.type(screen.getByLabelText("Email"), "alice@example.com");
+    await user.type(screen.getByLabelText("Password"), "password123");
+    await user.click(screen.getByRole("button", { name: "Sign in" }));
+
+    await waitFor(() => {
+      expect(onSubmit).toHaveBeenCalledWith({
+        email: "alice@example.com",
+        password: "password123",
+      });
+    });
+  });
+
+  it("shows validation error when email is empty", async () => {
+    const user = userEvent.setup();
+    render(<LoginForm onSubmit={vi.fn()} />);
+
+    await user.click(screen.getByRole("button", { name: "Sign in" }));
+
+    // ✅ Search by role alert — not by class .error-message
+    expect(screen.getByRole("alert")).toHaveTextContent(/email/i);
+  });
+
+  it("disables submit button while submitting", async () => {
+    const user = userEvent.setup();
+    // Simulate a long request
+    const onSubmit = vi.fn().mockImplementation(() => new Promise(() => {}));
+    render(<LoginForm onSubmit={onSubmit} />);
+
+    await user.type(screen.getByLabelText("Email"), "alice@example.com");
+    await user.type(screen.getByLabelText("Password"), "password123");
+    await user.click(screen.getByRole("button", { name: "Sign in" }));
+
+    expect(screen.getByRole("button", { name: /signing in/i })).toBeDisabled();
+  });
+});
+```
+
+### ✅ DO: test custom hooks via renderHook
+```ts
+import { renderHook, act } from "@testing-library/react";
+import { useDebounce } from "./useDebounce";
+
+describe("useDebounce", () => {
+  it("returns initial value immediately", () => {
+    const { result } = renderHook(() => useDebounce("initial", 300));
+    expect(result.current).toBe("initial");
+  });
+
+  it("debounces value update", async () => {
+    vi.useFakeTimers();
+    const { result, rerender } = renderHook(({ v }) => useDebounce(v, 300), {
+      initialProps: { v: "a" },
+    });
+
+    rerender({ v: "b" });
+    expect(result.current).toBe("a"); // has not updated
+
+    await act(() => vi.advanceTimersByTimeAsync(300));
+    expect(result.current).toBe("b"); // has updated
+
+    vi.useRealTimers();
+  });
+});
+```
+
+---
+
+## 6. E2E (Playwright)
+
+### ✅ DO: only for critical user flows
+```ts
+// e2e/auth.spec.ts
+import { test, expect } from "@playwright/test";
+
+// ✅ E2E covers the full flow that cannot be adequately unit-tested
+test("user can log in and see dashboard", async ({ page }) => {
+  await page.goto("/login");
+
+  await page.getByLabel("Email").fill("alice@example.com");
+  await page.getByLabel("Password").fill("password123");
+  await page.getByRole("button", { name: "Sign in" }).click();
+
+  // ✅ Wait for navigation, not just the presence of an element
+  await expect(page).toHaveURL("/dashboard");
+  await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible();
+});
+
+test("unauthenticated user is redirected to login", async ({ page }) => {
+  await page.goto("/dashboard");
+  await expect(page).toHaveURL("/login");
+});
+```
+
+---
+
+## 7. Antipatterns
+
+### ❌ Test checks implementation, not behavior
+```ts
+// ❌ Bad: test knows about an internal variable
+it("sets isLoading to true", () => {
+  const service = new UserService();
+  service.fetchUser("1");
+  expect(service._isLoading).toBe(true); // internal detail
+});
+
+// ✅ Good: test checks what the user/calling code sees
+it("shows loading state while fetching", async () => {
+  render(<UserProfile userId="1" />);
+  expect(screen.getByRole("status")).toBeInTheDocument(); // spinner
+});
+```
+
+### ❌ Fragile selectors
+```ts
+// ❌ Bad: will break upon CSS refactoring or DOM structure change
+screen.getByTestId("submit-btn-v2");       // testId is an implementation detail
+container.querySelector(".btn-primary");   // CSS class
+document.getElementById("form-submit");    // id
+
+// ✅ Good: semantic selectors — how the user interacts
+screen.getByRole("button", { name: "Sign in" });
+screen.getByLabelText("Email");
+screen.getByText("Save");
+```
+
+### ❌ Dependency of tests on each other
+```ts
+// ❌ Bad: test 2 breaks if test 1 did not run
+let createdUserId: string;
+
+it("creates user", async () => {
+  const user = await usersService.create(...);
+  createdUserId = user.id; // global variable
+});
+
+it("deletes user", async () => {
+  await usersService.delete(createdUserId); // depends on the test above
+});
+
+// ✅ Good: each test is isolated via beforeEach / fixtures
+describe("usersService.delete", () => {
+  let userId: string;
+  beforeEach(async () => {
+    const user = await usersService.create(...); // its own fixture
+    userId = user.id;
+  });
+
+  it("removes user from DB", async () => {
+    await usersService.delete(userId);
+    const found = await usersRepo.findById(userId);
+    expect(found).toBeNull();
+  });
+});
+```
+
+### ❌ Ignored error paths
+```ts
+// ❌ Bad: only happy path — the most important thing is not covered
+describe("payment.process", () => {
+  it("processes valid payment", ...);
+  // No tests for: insufficient funds, network failed, invalid card
+});
+
+// ✅ Good: error paths are mandatory for critical logic
+describe("payment.process", () => {
+  it("processes valid payment and returns transaction id", ...);
+  it("throws INSUFFICIENT_FUNDS when balance is too low", ...);
+  it("throws NETWORK_ERROR and does not charge when gateway fails", ...);
+  it("throws INVALID_CARD when card number is malformed", ...);
+});
+```
+
+### ❌ Test without assert (forever green)
+```ts
+// ❌ Bad: test is always green regardless of behavior
+it("sends email", async () => {
+  await emailService.send({ to: "a@b.com", subject: "Hi" });
+  // no expect — test says nothing
+});
+
+// ✅ Good: explicit assert
+it("sends email to correct recipient", async () => {
+  const spy = vi.spyOn(mailTransport, "send");
+  await emailService.send({ to: "a@b.com", subject: "Hi" });
+  expect(spy).toHaveBeenCalledWith(expect.objectContaining({ to: "a@b.com" }));
+});
+```
+
+---
+
+## See also
+- `$tdd-workflow` — RED→GREEN→REFACTOR algorithm + checklists + level table + rule list
+- `$testing-strategy-js` — general test strategy (pyramid)
+- `$testing-strategy-js-reference` — testing code reference
+- `$react-beast-practices` — testable React components
+- `$typescript-beast-practices` — mock typing
+- `$qa-e2e-playwright` — E2E via Playwright
+- `$tests-quality-review` — test quality review
+- `$dev-reference-snippets` — TDD example with slugify

package/domains/development/locales/en/.agents/skills/tdd-workflow-reference/agents/claude.json

@@ -0,0 +1,17 @@
+{
+  "name": "tdd-workflow-reference",
+  "display_name": "TDD Code Reference (DO/DON'T)",
+  "description": "Canonical TDD code reference — detailed DO/DON'T examples across 5 topics — Unit tests (Vitest, mocks), Integration tests (supertest, HTTP+DB), React components (Testing Library, renderHook), E2E (Playwright), antipatterns (brittle selectors, dependencies, missing error paths). Activate when looking up a specific TDD pattern."how to test X\", \"why the test breaks during refactoring\", \"what is a good test\".",
+  "default_prompt": "Use $tdd-workflow-reference when the task matches the \"TDD Code Reference (DO/DON'T)\" skill.",
+  "triggers": [
+    "tdd-workflow-reference",
+    "tdd workflow reference",
+    "Development strictly according to TDD (RED→GREEN→REFACTOR)"
+  ],
+  "capabilities": [
+    "tdd",
+    "reference"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/development/locales/en/.agents/skills/tdd-workflow-reference/agents/copilot.json

@@ -0,0 +1,17 @@
+{
+  "name": "tdd-workflow-reference",
+  "display_name": "TDD Code Reference (DO/DON'T)",
+  "description": "Canonical TDD code reference — detailed DO/DON'T examples across 5 topics — Unit tests (Vitest, mocks), Integration tests (supertest, HTTP+DB), React components (Testing Library, renderHook), E2E (Playwright), antipatterns (brittle selectors, dependencies, missing error paths). Activate when looking up a specific TDD pattern."how to test X\", \"why the test breaks during refactoring\", \"what is a good test\".",
+  "default_prompt": "Use $tdd-workflow-reference when the task matches the \"TDD Code Reference (DO/DON'T)\" skill.",
+  "triggers": [
+    "tdd-workflow-reference",
+    "tdd workflow reference",
+    "Development strictly according to TDD (RED→GREEN→REFACTOR)"
+  ],
+  "capabilities": [
+    "tdd",
+    "reference"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/development/locales/en/.agents/skills/tdd-workflow-reference/agents/gemini.json

@@ -0,0 +1,17 @@
+{
+  "name": "tdd-workflow-reference",
+  "display_name": "TDD Code Reference (DO/DON'T)",
+  "description": "Canonical TDD code reference — detailed DO/DON'T examples across 5 topics — Unit tests (Vitest, mocks), Integration tests (supertest, HTTP+DB), React components (Testing Library, renderHook), E2E (Playwright), antipatterns (brittle selectors, dependencies, missing error paths). Activate when looking up a specific TDD pattern."how to test X\", \"why the test breaks during refactoring\", \"what is a good test\".",
+  "default_prompt": "Use $tdd-workflow-reference when the task matches the \"TDD Code Reference (DO/DON'T)\" skill.",
+  "triggers": [
+    "tdd-workflow-reference",
+    "tdd workflow reference",
+    "Development strictly according to TDD (RED→GREEN→REFACTOR)"
+  ],
+  "capabilities": [
+    "tdd",
+    "reference"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/development/locales/en/.agents/skills/tdd-workflow-reference/agents/kimi.yaml

@@ -0,0 +1,13 @@
+name: "tdd-workflow-reference"
+display_name: "TDD Code Reference (DO/DON'T)"
+description: "Canonical TDD code reference — detailed DO/DON'T examples across 5 topics — Unit tests (Vitest, mocks), Integration tests (supertest, HTTP+DB), React components (Testing Library, renderHook), E2E (Playwright), antipatterns (brittle selectors, dependencies, missing error paths). Activate when looking up a specific TDD pattern."how to test X\", \"why the test breaks during refactoring\", \"what is a good test\"."
+default_prompt: "Use $tdd-workflow-reference when the task matches the \"TDD Code Reference (DO/DON'T)\" skill."
+triggers:
+  - "tdd-workflow-reference"
+  - "tdd workflow reference"
+  - "Development strictly according to TDD (RED→GREEN→REFACTOR)"
+capabilities:
+  - "tdd"
+  - "reference"
+tools: []
+implicit_invocation: true

package/domains/development/locales/en/.agents/skills/tdd-workflow-reference/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "TDD Code Reference (DO/DON'T)"
+  short_description: "Canonical TDD code reference — detailed DO/DON'T examples across 5 topics — Unit tests (Vitest, mocks), Integration tests (supertest, HTTP+DB), React components (Testing Library, renderHook), E2E (Playwright), antipatterns (brittle selectors, dependencies, missing error paths). Activate when looking up a specific TDD pattern."
+  default_prompt: "Use $tdd-workflow-reference when the task matches the \"TDD Code Reference (DO/DON'T)\" skill."
+dependencies:
+  tools: []
+policy:
+  allow_implicit_invocation: true

package/domains/development/locales/en/.agents/skills/tdd-workflow-reference/agents/qwen.json

@@ -0,0 +1,17 @@
+{
+  "name": "tdd-workflow-reference",
+  "display_name": "TDD Code Reference (DO/DON'T)",
+  "description": "Canonical TDD code reference — detailed DO/DON'T examples across 5 topics — Unit tests (Vitest, mocks), Integration tests (supertest, HTTP+DB), React components (Testing Library, renderHook), E2E (Playwright), antipatterns (brittle selectors, dependencies, missing error paths). Activate when looking up a specific TDD pattern."how to test X\", \"why the test breaks during refactoring\", \"what is a good test\".",
+  "default_prompt": "Use $tdd-workflow-reference when the task matches the \"TDD Code Reference (DO/DON'T)\" skill.",
+  "triggers": [
+    "tdd-workflow-reference",
+    "tdd workflow reference",
+    "Development strictly according to TDD (RED→GREEN→REFACTOR)"
+  ],
+  "capabilities": [
+    "tdd",
+    "reference"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/development/locales/en/.agents/skills/tdd-workflow-reference/agents/skill.yaml

@@ -0,0 +1,21 @@
+version: 1
+name: "tdd-workflow-reference"
+display_name: "TDD Code Reference (DO/DON'T)"
+description: "Canonical TDD code reference — detailed DO/DON'T examples across 5 topics — Unit tests (Vitest, mocks), Integration tests (supertest, HTTP+DB), React components (Testing Library, renderHook), E2E (Playwright), antipatterns (brittle selectors, dependencies, missing error paths). Activate when looking up a specific TDD pattern."how to test X\", \"why the test breaks during refactoring\", \"what is a good test\"."
+default_prompt: "Use $tdd-workflow-reference when the task matches the \"TDD Code Reference (DO/DON'T)\" skill."
+triggers:
+  - "tdd-workflow-reference"
+  - "tdd workflow reference"
+  - "Development strictly according to TDD (RED→GREEN→REFACTOR)"
+capabilities:
+  - "tdd"
+  - "reference"
+tools: []
+invocation:
+  explicit: true
+  implicit: true
+localization:
+  default_locale: "en"
+  available_locales:
+    - "ru"
+    - "en"