@pasosdejesus/m 0.15.0

package/src/test-utils/README.md

@@ -0,0 +1,638 @@
+# Test Utilities Commons (@pasosdeJesus/m)
+
+**"Y todo lo que hagáis, hacedlo de corazón, como para el Señor y no para los hombres" (Colosenses 3:23)**
+
+This directory contains generic mocking utilities for tests, designed to be reusable across multiple projects using similar stacks. These utilities have been extracted and adapted from the `learn.tg` project to become part of the `@pasosdeJesus/m` library.
+
+### 🕊️ Christian Framework
+
+As part of "Pasos de Jesús" projects, we recognize that our work serves a higher purpose: to bring the Good News to the world through technology. The Word of God is our supreme compass (brújula suprema). We strive to act with faithful diligence, excellence, and love, remembering that our technical work ultimately serves God's kingdom.
+
+"Whatever you do, work at it with all your heart, as working for the Lord, not for human masters" (Colossians 3:23). This includes writing tests and creating tools that help others build reliable, truthful software.
+
+## 🚀 For users of projects generated by `m`
+
+If you're developing a project generated with `m`, you can use these test utilities by importing them directly from the `@pasosdejesus/m` package.
+
+> ⚠️ **Vitest compatibility**: These mocks are designed for **Vitest 2.1.x**.
+> They use `vi.hoisted()` and `vi.mock()`. For vitest 1.x, use version `0.14.x`
+> of `@pasosdejesus/m`.
+
+### Installation
+
+Projects generated by `m` already include the necessary dependencies as `devDependencies`. If you need to install optional dependencies for using specific mocks:
+
+```bash
+# Install optional dependencies as needed
+pnpm add -D @testing-library/react viem next-auth wagmi siwe kysely pg react react-dom
+```
+
+### Quick start
+
+`apiAuthMocks` provee mocks para wagmi, rainbowkit, next-auth, siwe y axios.
+Úsalos directamente en `vitest.setup.ts`:
+
+```typescript
+// vitest.setup.ts
+import { apiAuthMocks } from '@pasosdejesus/m/test-utils/rainbowkit-mocks'
+
+const { mocks, setupDefaultImplementations } = apiAuthMocks
+setupDefaultImplementations()
+
+// vi.mock() para cada módulo — DEBE estar a module scope
+vi.mock('axios', () => ({
+  default: {
+    get: (...args: any[]) => mocks.mockAxiosGet(...args),
+    post: (...args: any[]) => mocks.mockAxiosPost(...args),
+  },
+}))
+vi.mock('siwe', () => ({ SiweMessage: mocks.mockSiweMessage }))
+vi.mock('next-auth/react', () => ({
+  useSession: () => mocks.mockUseSession(),
+  getCsrfToken: () => mocks.mockGetCsrfToken(),
+  SessionProvider: ({ children }: { children: React.ReactNode }) => children,
+}))
+```
+
+Esto configura automáticamente:
+- **wagmi**: `useAccount`, `useConnect`, `useDisconnect`, `useSwitchChain`, `createConfig`, `http`, `WagmiProvider`
+- **next-auth/react**: `useSession`, `getCsrfToken`, `SessionProvider`
+- **@rainbow-me/rainbowkit**: `RainbowKitProvider`, `ConnectButton`
+- **axios**: delegación a `mocks.mockAxiosGet/Post/Put/Delete/Request`
+- **siwe**: `SiweMessage`
+
+> ⚠️ **CRÍTICO**: `vi.mock()` debe estar a **module scope** del archivo que vitest transforma.
+> No funciona desde funciones dentro de módulos importados (como `setupMocks()`).
+> Si usas `apiDbMocks.setupMocks()`, el `vi.mock('kysely')` interno **no se aplica**.
+> Agrega los `vi.mock()` directamente en tu `vitest.setup.ts` o en el test file.
+
+### Basic usage
+
+Import mocks from `@pasosdejesus/m/test-utils`:
+
+```typescript
+// Import individual mocks
+import { createFsMocks } from '@pasosdejesus/m/test-utils/fs-mocks'
+import { createMockKysely } from '@pasosdejesus/m/test-utils/kysely-mocks'
+import { createAuthMocks } from '@pasosdejesus/m/test-utils/rainbowkit-mocks'
+import { viemMocks } from '@pasosdejesus/m/test-utils/viem-mocks'
+
+// radix-mocks is a side-effect import
+import '@pasosdejesus/m/test-utils/radix-mocks'
+
+// Or import everything from the index
+import { createFsMocks, createMockKysely, createAuthMocks } from '@pasosdejesus/m/test-utils'
+```
+
+### Quick example
+
+```typescript
+import { describe, it, expect, beforeAll, beforeEach } from 'vitest'
+import { createFsMocks, createMockKysely, createAuthMocks } from '@pasosdejesus/m/test-utils'
+
+describe('My test', () => {
+  const fsMocks = createFsMocks()
+  const dbMocks = createMockKysely()
+  const authMocks = createAuthMocks()
+
+  beforeAll(() => {
+    fsMocks.setupFsMocks()
+    dbMocks.setupMocks()
+    authMocks.setupMocks()
+    authMocks.setupDefaultImplementations()
+  })
+
+  beforeEach(() => {
+    fsMocks.resetFsMocks()
+    dbMocks.resetMocks()
+    authMocks.resetMocks()
+  })
+
+  it('should use the mocks', () => {
+    // Configure custom responses
+    fsMocks.mockReadFile.mockResolvedValue('test content')
+    dbMocks.mockExecuteTakeFirst.mockResolvedValue({ id: 1, name: 'User' })
+
+    // Your test code here
+  })
+})
+```
+
+### Complete example
+
+Check the example file included in your project: `templates/tests/test-utils.example.test.ts`.
+
+## 📁 Structure
+
+```
+test-utils/
+├── index.ts              # Re-exports all generic mocks
+├── fs-mocks.ts           # Mocks for filesystem (fs/promises)
+├── kysely-mocks.ts       # Mocks for Kysely ORM and PostgreSQL
+├── radix-mocks.tsx       # Mocks for Radix UI components
+├── rainbowkit-mocks.ts   # Mocks for authentication (RainbowKit, Wagmi, NextAuth, SIWE)
+├── viem-mocks.ts         # Mocks for blockchain client Viem
+└── i18n-mock.ts          # Mocks for i18n module
+```
+
+> **mpdj test-utils**: Mocks para los módulos blockchain de `@pasosdejesus/mpdj`
+> (credenciales, deployments, ecosystem-addresses, slearn-info) están en
+> `@pasosdejesus/mpdj/test-utils`. Ver [`packages/mpdj/src/test-utils/README.md`](../../mpdj/src/test-utils/README.md).
+
+## 🧪 Available Modules
+
+### 1. `fs-mocks.ts` – Filesystem
+
+**Purpose:** Mock `fs/promises` and `node:fs/promises` modules for tests that read files.
+
+**Functions:**
+- `createFsMocks(options?)`: Creates configurable mocks with custom content or errors.
+
+**Usage:**
+```typescript
+import { createFsMocks } from '@pasosdejesus/m/test-utils/fs-mocks'
+
+const fsMocks = createFsMocks({
+  readFileContent: '# Mock content',
+  readFileError: new Error('File not found')
+})
+
+beforeAll(() => {
+  fsMocks.setupFsMocks()
+})
+
+beforeEach(() => {
+  fsMocks.resetFsMocks()
+  fsMocks.setupCommonResponses()
+})
+```
+
+**Important points:**
+- Uses `vi.hoisted()` to avoid initialization issues
+- Mocks both `fs/promises` and `node:fs/promises`
+- Includes `setupFsMocks()`, `resetFsMocks()`, `setupCommonResponses()` functions
+
+### 2. `kysely-mocks.ts` – Database ORM
+
+**Purpose:** Mock Kysely and PostgreSQL for database access tests.
+
+**Functions:**
+- `createMockKysely(options?)`: Creates configurable mock Kysely instance with `MockKysely` class and mock functions
+- `createMockDb()`: Flat mock DB object with chainable methods — simple, no class needed
+- `apiDbMocks` / `libDbMocks`: Pre-configured instances for API routes and libraries
+
+> ⚠️ **CRÍTICO**: `vi.mock()` debe estar a **module scope**. El método `setupMocks()`
+> llama `vi.mock()` internamente pero vitest **no lo hoistea** porque está dentro de
+> una factory en un módulo importado. Agrega los `vi.mock()` directamente:
+
+```typescript
+// vitest.setup.ts — module scope
+import { apiDbMocks } from '@pasosdejesus/m/test-utils/kysely-mocks'
+const { mockExecuteTakeFirst, mockExecute, mockSqlExecute, mockSql, mockPgPool } = apiDbMocks
+
+class GlobalMockKysely {
+  selectFrom() { return this }
+  where() { return this }
+  selectAll() { return this }
+  select(..._args: any[]) { return this }
+  orderBy() { return this }
+  limit() { return this }
+  groupBy() { return this }
+  having() { return this }
+  leftJoin() { return this }
+  innerJoin() { return this }
+  insertInto() { return this }
+  values() { return this }
+  returningAll() { return this }
+  updateTable() { return this }
+  set() { return this }
+  deleteFrom() { return this }
+  with() { return this }
+  onConflict() { return this }
+  doNothing() { return this }
+  executeTakeFirst() { return mockExecuteTakeFirst() }
+  executeTakeFirstOrThrow() { return mockExecuteTakeFirst() }
+  execute() { return mockExecute() }
+  transaction() {
+    return {
+      execute: async (callback: any) => {
+        return callback(new GlobalMockKysely())
+      }
+    }
+  }
+  getExecutor() {
+    return {
+      executeQuery: (query: any) => mockSqlExecute(query),
+      provideConnection: async (callback: any) => callback({}),
+      releaseConnection: () => {},
+      transformQuery: (query: any, transformer: any) => query,
+      compileQuery: (query: any, ctx: any) => ({ sql: '', parameters: [] }),
+    }
+  }
+  fn = {
+    countAll: vi.fn(() => ({ as: vi.fn(() => ({})) })),
+    sum: vi.fn(() => ({ as: vi.fn(() => ({})) })),
+    avg: vi.fn(() => ({ as: vi.fn(() => ({})) })),
+    max: vi.fn(() => ({ as: vi.fn(() => ({})) })),
+    min: vi.fn(() => ({ as: vi.fn(() => ({})) })),
+  }
+}
+vi.mock('kysely', () => ({
+  Kysely: GlobalMockKysely,
+  PostgresDialect: vi.fn(),
+  sql: mockSql,
+}))
+vi.mock('pg', () => ({ Pool: mockPgPool }))
+```
+
+**`createMockDb()` — alternativa simple:**
+
+```typescript
+import { createMockDb } from '@pasosdejesus/m/test-utils'
+
+let mockDb: ReturnType<typeof createMockDb>
+beforeEach(() => { mockDb = createMockDb() })
+
+vi.mock('@/.config/kysely-db', () => ({
+  newKyselyPostgresql: vi.fn(() => mockDb),
+}))
+```
+
+**Configurable options (para `createMockKysely`):**
+- `executeTakeFirst`, `execute`, `sqlExecute`: Custom implementations
+- `configPath`: **Deprecated.** No funciona por hoisting de `vi.mock()`.
+- `skipConfigMock`: Si `true`, no mockea el módulo de config.
+
+**Usage:**
+```typescript
+import { createMockKysely } from '@pasosdejesus/m/test-utils/kysely-mocks'
+
+const dbMocks = createMockKysely()
+
+beforeEach(() => {
+  dbMocks.resetMocks()
+  dbMocks.setupCommonResponses()
+  // Configure specific responses
+  dbMocks.mockExecuteTakeFirst.mockResolvedValue({ id: 1 })
+})
+```
+
+**Important points:**
+- Complete Kysely mock with fluent query builder (`selectFrom().where().execute()`)
+- Includes mock for `sql` with `val()` method for template tags, `execute()` for
+  execution, and `as()` for aliases: `mockSql().as('alias')` returns `{}`
+- Mock for `pg.Pool` of PostgreSQL
+- **Lesson learned:** The `sql.val()` method is crucial for queries using template tags
+
+### 3. `radix-mocks.tsx` – UI Components
+
+**Purpose:** Mock Radix UI components for React component tests.
+
+**Included mocks:**
+- `portalMock`, `popoverMock`, `menubarMock`, `dropdownMenuMock`
+- `dialogMock`, `toastMock`, `tooltipMock`, `accordionMock`
+- `scrollAreaMock`, `tabsMock`, and common components (`Slot`, `Label`, `Separator`)
+
+**Usage:**
+```typescript
+// Import at the beginning of test files (before importing components)
+import '@pasosdejesus/m/test-utils/radix-mocks'
+
+// Radix components are now mocked with simplified versions
+// that include data-testid for test selection
+```
+
+**Important points:**
+- All mocks use `React.forwardRef` for compatibility
+- Include `data-testid` for easy test selection
+- **Lesson learned:** Some components like `ScrollArea` render multiple elements with the same `data-testid`; use `getAllByTestId` and select the appropriate element
+- **Lesson learned:** Components using `Portal` must be mocked to render children directly
+
+### 4. `rainbowkit-mocks.ts` – Web3 Authentication
+
+**Purpose:** Mock authentication with RainbowKit, Wagmi, NextAuth and Sign-In With Ethereum (SIWE).
+
+**Functions:**
+- `createAuthMocks(config?)`: Creates configurable mocks
+- `apiAuthMocks`: Pre-configured instance for API routes
+
+**Configuration (`AuthMockConfig`):**
+- `address`, `isConnected`, `sessionData`, `csrfToken`, `siweVerificationSuccess`
+- `chainId`: Chain ID (default: 1)
+- `mockAxios`, `mockWagmi`, `mockSiwe`, `mockNextAuth`: Enable/disable specific mocks
+- `axiosMock`: Custom implementations for axios methods
+
+**Usage:**
+```typescript
+import { createAuthMocks } from '@pasosdejesus/m/test-utils/rainbowkit-mocks'
+
+const authMocks = createAuthMocks({
+  address: '0x123...',
+  chainId: 8453, // Base chain
+  mockAxios: true,
+  axiosMock: {
+    post: vi.fn().mockResolvedValue({ data: { success: true } })
+  }
+})
+
+beforeAll(() => {
+  authMocks.setupMocks()
+  authMocks.setupDefaultImplementations()
+})
+
+beforeEach(() => {
+  authMocks.resetMocks()
+  // Update dynamic configuration
+  authMocks.updateConfig({ isConnected: false })
+})
+```
+
+**Important points:**
+- **Lesson learned:** Some components use `axios.post` while others use `fetch`; mock both appropriately
+- **Lesson learned:** User scores come from APIs, not from `useSession().data.user`; mock `fetch` responses correctly
+- **Lesson learned:** Configure `chainId` correctly for multi-chain tests
+- Includes `updateConfig()` function for dynamic changes during tests
+
+### 5. `viem-mocks.ts` – Blockchain Client
+
+**Purpose:** Mock Viem for blockchain interactions.
+
+**Mocks:**
+- `viemMocks`: `createPublicClient`, `createWalletClient`, `getContract`, `encodeFunctionData`, etc.
+- `viemChainsMocks`: Object with mock chains (`celo`, `celoSepolia` by default)
+
+**Usage:**
+```typescript
+import { viemMocks, viemChainsMocks } from '@pasosdejesus/m/test-utils/viem-mocks'
+
+// Extend available chains
+viemChainsMocks.ethereum = {}
+viemChainsMocks.base = {}
+
+// Use in tests
+viemMocks.createPublicClient.mockReturnValue({ ... })
+```
+
+**Important points:**
+- Mock chains are extensible; add new chains as needed
+- **Lesson learned:** Some functions like `privateKeyToAccount` and `formatUnits` are necessary for transaction tests
+
+## 🚀 Complete Usage Examples
+
+### Configuration for API Route Tests
+
+```typescript
+import { createMockKysely, createAuthMocks } from '@pasosdejesus/m/test-utils'
+
+// Global setup
+const dbMocks = createMockKysely({ skipConfigMock: true })
+const authMocks = createAuthMocks({ mockAxios: false })
+
+beforeAll(() => {
+  dbMocks.setupMocks()
+  authMocks.setupMocks()
+  authMocks.setupDefaultImplementations()
+})
+
+beforeEach(() => {
+  dbMocks.resetMocks()
+  authMocks.resetMocks()
+  // Test-specific configurations
+  dbMocks.mockExecuteTakeFirst.mockResolvedValue({ id: 1 })
+  authMocks.updateConfig({ address: '0xtest...' })
+})
+
+afterAll(() => {
+  vi.clearAllMocks()
+})
+```
+
+### Configuration for Component Tests
+
+```typescript
+import '@pasosdejesus/m/test-utils/radix-mocks'
+import { createAuthMocks } from '@pasosdejesus/m/test-utils/rainbowkit-mocks'
+import { render, screen } from '@testing-library/react'
+
+const authMocks = createAuthMocks({
+  mockAxios: false,
+  mockSiwe: false,
+  mockNextAuth: true
+})
+
+beforeAll(() => {
+  authMocks.setupMocks()
+  authMocks.setupDefaultImplementations()
+})
+
+test('renders component with wallet connection', () => {
+  authMocks.updateConfig({ isConnected: true })
+  render(<MyComponent />)
+  expect(screen.getByText('Connected')).toBeInTheDocument()
+})
+```
+
+## 📝 Important Lessons Learned
+
+### 1. **Import order**
+Radix UI mocks must be imported **before** importing any components that use them. Place `import '@pasosdejesus/m/test-utils/radix-mocks'` at the beginning of test files.
+
+### 2. **Multiple elements with same testid**
+Components like `ScrollArea` render multiple elements with the same `data-testid`. Use `getAllByTestId` and select the appropriate element.
+
+### 3. **axios vs fetch**
+Some components use `axios` while others use native `fetch`. Mock both as appropriate:
+- Components: generally use `fetch` for initial data
+- Handlers: may use `axios.post` for updates
+
+### 4. **User scores**
+User scores (`learningscore`, `profilescore`) come from APIs (`fetch` responses), not from `useSession().data.user`. Mock `fetch` responses correctly.
+
+### 5. **Dynamic configuration**
+Use `updateConfig()` to change authentication state during tests (e.g., simulate disconnection).
+
+### 6. **SQL template tags**
+The Kysely mock must include `sql.val()` for queries using template tags like ```sql`SELECT * FROM table` ``.
+
+### 7. **Error handling**
+Configure mocks to simulate errors (e.g., `mockRejectedValue`) to test error flows.
+
+### 8. **`vi.mock` hoisting in Vitest (CRÍTICO)**
+`vi.mock` calls are hoisted to the top of the **file being transformed by vitest**. NO se hoistean desde funciones dentro de módulos importados. Ejemplo:
+```typescript
+// ❌ NO FUNCIONA — el vi.mock está dentro de setupMocks() en un módulo importado
+import { apiDbMocks } from '@pasosdejesus/m/test-utils'
+apiDbMocks.setupMocks() // vi.mock('kysely') interno NO se aplica
+
+// ✅ FUNCIONA — vi.mock() a module scope del archivo que vitest transforma
+vi.mock('kysely', () => ({ Kysely: MockKysely, PostgresDialect: vi.fn(), sql: mockSql }))
+```
+Esto aplica a TODOS los `setupMocks()` de los test-utils. Para usar `apiDbMocks` correctamente, agrega el `vi.mock()` a module scope en tu `vitest.setup.ts` (ver ejemplo en §2).
+
+### 9. **Variables captured in closures**
+When using `vi.hoisted`, external variables must be captured before the hoisted function. Example:
+```typescript
+// CORRECT: capture before vi.hoisted
+const capturedVar = externalVar
+const mocks = vi.hoisted(() => {
+  // Use capturedVar, not externalVar
+})
+
+// INCORRECT: external variable not accessible
+const mocks = vi.hoisted(() => {
+  // ReferenceError: externalVar is not defined
+})
+```
+
+### 10. **Mocking modules with dynamic paths**
+`vi.mock` doesn't accept dynamic paths (variables) due to hoisting. To mock modules with configurable paths:
+1. Use string literal and configure alias in `vite.config.ts`
+2. Or create multiple mocks for different paths
+3. Or disable the mock (`skipConfigMock: true`) and mock manually
+
+### 11. **Recent common errors and solutions**
+- **`ReferenceError: configPath is not defined`**: Caused by using variable in `vi.mock`. Solution: use string literal `'@/.config/kysely.config'`.
+- **`ReferenceError: axiosMock is not defined`**: Variable not captured in closure. Solution: capture `axiosMock` before `vi.hoisted`.
+- **`ReferenceError: path is not defined`**: Similar to `configPath`, variable not accessible in `vi.mock` scope.
+
+### 12. **Import order for module under test**
+When testing modules that depend on mocked dependencies, import the module **after** setting up mocks. This ensures that the module receives the mocked versions. Example from `queries.test.ts`:
+```typescript
+// 1. Setup mocks first
+vi.mock('kysely', () => ({ Kysely: libDbMocks.MockKysely, ... }))
+// 2. Then import the module
+import * as metricsQueries from '../queries'
+```
+
+### 13. **Pre-configured mock instances**
+The library provides pre-configured instances for common use cases:
+- `libDbMocks` and `apiDbMocks` for Kysely (configured for library vs API route contexts)
+- `apiAuthMocks` for authentication in API routes
+Use these to avoid repetitive configuration. Example:
+```typescript
+import { apiDbMocks } from '@pasosdejesus/m/test-utils/kysely-mocks'
+const { mockExecuteTakeFirst, setupMocks, resetMocks } = apiDbMocks
+```
+
+### 14. **React version alignment**
+Ensure that React versions are consistent between the test utilities package and the consuming project. The `@pasosdejesus/m` package uses React 19 as a peer dependency. If your project uses a different version, you may encounter errors like "A React Element from an older version of React was rendered".
+
+### 15. **Global React setup for mocks**
+When using Radix UI mocks or other React-based mocks in Vitest setup files, set `global.React = React` before importing the mocks to ensure proper React instance sharing. This is especially important when mocks are used in `vitest.setup.ts`.
+
+## 🔧 Configuration for Other Projects
+
+These utilities can be used in other projects with the following adaptations:
+
+### 1. **Kysely Configuration**
+If the project uses a different path for Kysely configuration:
+```typescript
+// ⚠️ configPath currently non-functional due to vi.mock hoisting
+// For different paths, configure aliases in Vite or mock manually
+createMockKysely({ skipConfigMock: true }) // And mock the module manually
+```
+
+### 2. **Blockchain Chains**
+Extend available chains in `viemChainsMocks`:
+```typescript
+import { viemChainsMocks } from '@pasosdejesus/m/test-utils/viem-mocks'
+viemChainsMocks.ethereum = {}
+viemChainsMocks.polygon = {}
+```
+
+### 3. **Radix UI Components**
+If using Radix components not included, extend `radix-mocks.tsx`:
+```typescript
+// In test setup
+vi.mock('@radix-ui/react-slider', () => ({
+  Root: /* mock implementation */
+}))
+```
+
+### 4. **Environment variables**
+Ensure required environment variables are defined in tests:
+```typescript
+process.env.NEXT_PUBLIC_API_URL = 'http://test.example.com'
+```
+
+### 5. **Project-specific modules**
+For mocking project‑specific internal modules, follow the pattern used in `learn.tg`'s `learn‑tg‑mocks.ts`:
+1. Use `vi.hoisted()` to create mock objects that can be referenced in `vi.mock()` calls.
+2. Export factory functions that return those mocks for test‑time configuration.
+3. Provide a `setup*Mocks()` function that calls `vi.mock` for all related modules.
+
+Example:
+```typescript
+// my‑project‑mocks.ts
+import { vi } from 'vitest'
+
+const myModuleMocks = vi.hoisted(() => ({
+  myFunction: vi.fn(),
+  myConstant: 'test',
+}))
+
+export function setupMyMocks() {
+  vi.mock('@/lib/my‑module', () => myModuleMocks)
+}
+
+export function getMyMocks() {
+  return myModuleMocks
+}
+```
+
+## 🤝 Contribution
+
+The utilities are designed to be part of `@pasosdeJesus/m`. To contribute:
+
+1. **Maintain compatibility**: Breaking changes must be versioned
+2. **Document**: Update this documentation with new features
+3. **Test**: Ensure utilities work across multiple projects
+4. **Christian principles**: Work with diligence, humility, and love (Colossians 3:23)
+
+## 🚀 Integration with Existing Projects
+
+These utilities are now part of the `@pasosdeJesus/m` package and ready to use. They have been successfully integrated into the `learn.tg` project, serving as a reference implementation.
+
+### Using with Project-Specific Mocks
+
+In real projects, you'll often combine generic mocks with project-specific mocks. Here's how `learn.tg` structures this:
+
+1. **Generic mocks** (from `@pasosdejesus/m/test-utils`): Mock cross-cutting concerns (database, authentication, UI components, blockchain).
+2. **Project-specific mocks** (in `@/test-utils/`): Mock internal modules unique to the project.
+
+**Example: `vitest.setup.ts` in learn.tg**
+```typescript
+import '@pasosdejesus/m/test-utils/radix-mocks';
+import { apiAuthMocks } from '@pasosdejesus/m/test-utils/rainbowkit-mocks';
+
+// Extract mocks from apiAuthMocks for direct use
+const { mocks, setupDefaultImplementations } = apiAuthMocks;
+setupDefaultImplementations();
+
+// Setup vi.mock for various modules using the provided mocks
+vi.mock('@rainbow-me/rainbowkit', () => ({ ... }));
+vi.mock('wagmi', async (importOriginal) => ({ ... }));
+vi.mock('next-auth/react', () => ({
+  useSession: () => mocks.mockUseSession(),
+  getCsrfToken: () => mocks.mockGetCsrfToken(),
+}));
+```
+
+**Example: Test file combining generic and project mocks**
+```typescript
+import { apiDbMocks } from '@pasosdejesus/m/test-utils/kysely-mocks';
+import { setupApiMocks } from '@/test-utils/learn-tg-mocks';
+
+beforeAll(() => {
+  apiDbMocks.setupMocks();
+  setupApiMocks(); // Sets up project-specific mocks
+});
+```
+
+## 📄 License
+
+Part of `@pasosdeJesus/m` – Utilities for "Pasos de Jesús" projects.
+
+---
+
+*"For God has not given us a spirit of timidity, but of power, love, and self-discipline" (2 Timothy 1:7)*

package/src/util/README.md

@@ -0,0 +1,18 @@
+# Util — Shared CLI Utilities
+
+Shared helpers used across all `../tasks/` command implementations.
+
+## Exports
+
+| File | Export | Purpose |
+|------|--------|---------|
+| `cli-parser.ts` | `parseArgv()`, `parseFlags()` | Minimal CLI argument parser (replaced Commander.js); `parseFlags` handles --flag parsing for multi-command CLI |
+| `colors.ts` | `problem()`, `info()`, `success()`, `warn()` | Colored console output with consistent formatting |
+| `locale.ts` | `detectLocale()`, `setLocale()` | System locale detection via `LANG` env var + override setter |
+| `i18n.ts` | *(removed)* | Former `getCliT()` wrapper. Replaced by `createTranslator` in `../i18n/` — translations are now inline per-file in each `../tasks/*.ts` |
+
+## Why a custom CLI parser
+
+Commander.js interfered with `stdin`/`stdout` handling for interactive commands
+(`db:console`, `m:update`). The custom parser gives full control over the
+process lifecycle. See `ARCHITECTURE.md` §2.1 for details.