@regardio/dev 1.24.0 → 2.0.1

package/docs/en/agents.md

@@ -0,0 +1,57 @@
+---
+
+title: AI Agent Guidelines
+type: guide
+status: published
+summary: Instructions for AI coding assistants working with Regardio projects
+related: [coding-standards, react-standards, development-principles]
+locale: en-US
+---
+
+# AI Agent Guidelines
+
+Baseline expectations for AI coding assistants working in Regardio projects. Follow the linked standards — they apply equally to agent and human contributions.
+
+## How Agents Should Work
+
+- **Scope changes tightly** - Only change what the task requires. Do not refactor adjacent code, add features, or reorganize files unless asked.
+- **Read before writing** - Understand existing patterns in the file and its neighbors before editing. Match the style you find.
+- **Avoid unnecessary complexity** - Only implement what is explicitly required. Do not introduce abstractions, helpers, or utilities speculatively.
+- **No emojis** - Unless explicitly requested.
+- **Preserve comments and documentation** - Do not add or remove comments unless the task calls for it.
+- **Explain uncertainty** - If something is ambiguous, say so rather than guessing.
+
+## Implementation Workflow
+
+When working on any non-trivial task, follow this sequence:
+
+1. **Understand the business logic** — Gather context before writing code. Read relevant domain documents. Know what is actually needed; do not implement what was not asked for.
+2. **Evaluate existing solutions** — Check for well-maintained libraries or utilities before writing custom code. Do not reinvent; do not introduce a dependency without verifying it exists and is actively maintained.
+3. **Define tests first** — Identify what tests describe the expected behavior before implementing. Tests are a contract. Do not modify tests to make them pass.
+4. **Implement with reusability in mind** — Prefer simple, readable code. Duplicate until a clear pattern emerges, then extract. Avoid speculative abstractions.
+5. **Stop if it gets complicated** — Growing complexity despite good preparation is a signal. Surface the difficulty, reconsider the approach, and back out rather than pushing through.
+6. **Document intent, stay lean** — Comments explain *why*, not *what*. Check existing documentation and business logic context before starting work.
+
+## Standards
+
+- [Coding Standards](./standards/coding.md) — TypeScript, React, and general coding patterns
+- [React and TypeScript Standards](./standards/react.md) — Component, hook, and state patterns
+- [SQL Schema Standards](./standards/sql.md) — PostgreSQL naming, structure, and access control
+- [Development Principles](./standards/principles.md) — Code quality, architecture, security
+- [API Standards](./standards/api.md) — API design and implementation
+- [Naming Conventions](./standards/naming.md) — Naming across TypeScript, SQL, CSS, Git
+- [Testing Approach](./standards/testing.md) — Testing philosophy and patterns
+- [Commit Conventions](./standards/commits.md) — Conventional commits and changelog generation
+- [Documentation Standard](./standards/documentation.md) — Document structure and conventions
+- [Writing](./standards/writing.md) — Voice, tone, and language
+
+## Commands
+
+```bash
+pnpm fix        # Fix and lint everything
+pnpm lint       # Lint only
+pnpm test       # Run tests
+pnpm typecheck  # Type check
+```
+
+Run `typecheck` and `lint` before marking a task complete.

package/docs/en/standards/api.md

@@ -0,0 +1,324 @@
+---
+
+title: "API"
+description: "REST endpoint shape, error handling, security, and performance patterns for Regardio APIs."
+publishedAt: 2026-04-17
+order: 8
+language: "en"
+status: "published"
+kind: "reference"
+area: "dev"
+---
+
+Regardio APIs are resource-oriented, predictable, and consistent about errors. This page catalogues the shape of endpoints, the response envelope, and the patterns for authentication, validation, caching, and testing. The contract a client sees — URL, verb, status, envelope — stays stable; the implementation behind it is free to change.
+
+## Design
+
+### RESTful URLs
+
+- One resource per URL
+- Standard HTTP verbs carry the operation
+- Status codes carry the outcome
+
+```text
+GET    /api/users          List users
+GET    /api/users/:id      Get a specific user
+POST   /api/users          Create a user
+PATCH  /api/users/:id      Update a user
+DELETE /api/users/:id      Delete a user
+```
+
+### Response envelope
+
+Every response wraps its payload in a discriminated union so that a client never has to guess whether it received success or failure:
+
+```typescript
+interface SuccessResponse<T> {
+  success: true;
+  data: T;
+  meta?: { page?: number; limit?: number; total?: number };
+}
+
+interface ErrorResponse {
+  success: false;
+  error: { code: string; message: string; details?: unknown };
+}
+
+type ApiResponse<T> = SuccessResponse<T> | ErrorResponse;
+```
+
+Breaking changes go through versioning; consistency across versions keeps clients portable.
+
+## Errors
+
+### Categories
+
+```typescript
+enum ApiErrorType {
+  VALIDATION = 'validation',
+  AUTHENTICATION = 'authentication',
+  PERMISSION = 'permission',
+  NOT_FOUND = 'not_found',
+  CONFLICT = 'conflict',
+  RATE_LIMIT = 'rate_limit',
+  SERVER = 'server',
+}
+
+class ApiError extends Error {
+  constructor(
+    message: string,
+    public type: ApiErrorType,
+    public code: string,
+    public statusCode: number,
+    public details?: unknown,
+  ) {
+    super(message);
+    this.name = 'ApiError';
+  }
+}
+```
+
+### Status codes
+
+| Code | Use |
+|------|-----|
+| 200 | Successful GET, PATCH, DELETE |
+| 201 | Successful POST |
+| 400 | Invalid request |
+| 401 | Missing or invalid authentication |
+| 403 | Insufficient permissions |
+| 404 | Resource not found |
+| 409 | Resource conflict |
+| 422 | Validation failure |
+| 429 | Rate limit exceeded |
+| 500 | Server error |
+
+### Error payload
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid input data",
+    "details": { "fields": { "email": "Invalid email format" } }
+  }
+}
+```
+
+### Client handling
+
+```typescript
+async function fetchUser(id: string): Promise<User> {
+  const response = await fetch(`/api/users/${id}`);
+  const result: ApiResponse<User> = await response.json();
+
+  if (!result.success) {
+    throw new ApiError(
+      result.error.message,
+      mapErrorCode(result.error.code),
+      result.error.code,
+      response.status,
+    );
+  }
+
+  return result.data;
+}
+```
+
+## Security
+
+### Authentication
+
+- Token-based (JWT or equivalent)
+- HTTPS in every environment that sees real traffic
+- Tokens expire; refresh is explicit
+
+```typescript
+interface AuthTokens {
+  accessToken: string;
+  refreshToken: string;
+  expiresAt: number;
+}
+```
+
+### Authorisation
+
+- Minimum necessary permissions
+- Role-based access for cross-resource actions
+- Ownership verified on every resource-scoped action
+- Server-side validation is the line; the client is untrusted
+
+```typescript
+async function updateUser(id: string, data: Partial<User>): Promise<User> {
+  const currentUser = await getCurrentUser();
+
+  if (currentUser.id !== id && !currentUser.roles.includes('admin')) {
+    throw new ApiError('Permission denied', ApiErrorType.PERMISSION, 'PERMISSION_DENIED', 403);
+  }
+
+  const validatedData = validateUserUpdate(data);
+  return userRepository.update(id, validatedData);
+}
+```
+
+### Input validation
+
+Types, ranges, and formats are validated on the server. A schema library carries the shape so the contract stays single-sourced:
+
+```typescript
+import { z } from 'zod';
+
+const UserUpdateSchema = z.object({
+  email: z.string().email().optional(),
+  displayName: z.string().min(2).max(50).optional(),
+  age: z.number().int().min(18).max(120).optional(),
+});
+
+function validateUserUpdate(data: unknown): Partial<User> {
+  try {
+    return UserUpdateSchema.parse(data);
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      throw new ApiError(
+        'Validation failed',
+        ApiErrorType.VALIDATION,
+        'VALIDATION_ERROR',
+        422,
+        { fields: error.flatten().fieldErrors },
+      );
+    }
+    throw error;
+  }
+}
+```
+
+## Performance
+
+### Pagination
+
+List endpoints paginate; limits are capped so a client cannot ask for the world:
+
+```typescript
+interface ListParams {
+  page?: number;
+  limit?: number;
+  sortBy?: string;
+  sortOrder?: 'asc' | 'desc';
+}
+
+async function listUsers(params: ListParams): Promise<ApiResponse<User[]>> {
+  const page = params.page ?? 1;
+  const limit = Math.min(params.limit ?? 20, 100);
+  const offset = (page - 1) * limit;
+
+  const [users, total] = await Promise.all([
+    userRepository.findMany({ offset, limit, sortBy: params.sortBy, sortOrder: params.sortOrder }),
+    userRepository.count(),
+  ]);
+
+  return {
+    success: true,
+    data: users,
+    meta: { page, limit, total, totalPages: Math.ceil(total / limit) },
+  };
+}
+```
+
+### Caching and rate limiting
+
+- `Cache-Control` and ETags where the resource tolerates it
+- Rate limits protect against runaway clients and scraped keys
+
+```typescript
+app.get('/api/users/:id', async (req, res) => {
+  const user = await userRepository.findById(req.params.id);
+  if (!user) {
+    return res.status(404).json({
+      success: false,
+      error: { code: 'NOT_FOUND', message: 'User not found' },
+    });
+  }
+  res.set('Cache-Control', 'private, max-age=300');
+  res.json({ success: true, data: user });
+});
+
+const apiLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000,
+  max: 100,
+  message: { success: false, error: { code: 'RATE_LIMIT_EXCEEDED', message: 'Too many requests' } },
+});
+app.use('/api/', apiLimiter);
+```
+
+## Documentation
+
+Each endpoint carries:
+
+- Purpose and authentication requirement
+- Parameters and response shape
+- Error codes that can arise
+- A request/response example
+
+```typescript
+/**
+ * Update a user profile.
+ * @route  PATCH /api/users/:id
+ * @auth   Required
+ * @param  id  User ID
+ * @returns    Updated user
+ * @throws 401 UNAUTHORIZED
+ * @throws 403 PERMISSION_DENIED
+ * @throws 422 VALIDATION_ERROR
+ */
+```
+
+For large APIs, OpenAPI/Swagger carries the same contract in a form tooling can consume.
+
+## Testing
+
+- **Unit tests** — individual handlers and helpers
+- **Integration tests** — endpoints against a real database
+- **Contract tests** — request/response shape held to the documented contract
+
+```typescript
+describe('User API', () => {
+  it('updates user profile successfully', async () => {
+    const user = await createTestUser();
+    const token = await generateAuthToken(user);
+
+    const response = await request(app)
+      .patch(`/api/users/${user.id}`)
+      .set('Authorization', `Bearer ${token}`)
+      .send({ displayName: 'Updated Name' });
+
+    expect(response.status).toBe(200);
+    expect(response.body.data.displayName).toBe('Updated Name');
+  });
+
+  it('returns 403 when updating another user', async () => {
+    const user1 = await createTestUser();
+    const user2 = await createTestUser();
+    const token = await generateAuthToken(user1);
+
+    const response = await request(app)
+      .patch(`/api/users/${user2.id}`)
+      .set('Authorization', `Bearer ${token}`)
+      .send({ displayName: 'Hacked' });
+
+    expect(response.status).toBe(403);
+    expect(response.body.error.code).toBe('PERMISSION_DENIED');
+  });
+});
+```
+
+## Related
+
+- [React](./react.md) — Patterns for the clients that consume the API
+- [SQL](./sql.md) — Naming, structure, and access on the database side
+- [Testing](./testing.md) — Testing philosophy and layers
+- [Principles](./principles.md) — Shared principles
+
+---
+
+**License**: [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) © Regardio

package/docs/en/standards/coding.md

@@ -0,0 +1,144 @@
+---
+
+title: "Coding"
+description: "TypeScript and general coding patterns Regardio projects hold to across packages and apps."
+publishedAt: 2026-04-17
+order: 5
+language: "en"
+status: "published"
+kind: "reference"
+area: "dev"
+---
+
+Regardio code is TypeScript across the board. What keeps the packages readable to each other is a small set of patterns held consistently: strict types, small modules, small functions, deliberate error handling. This page catalogues those patterns.
+
+## TypeScript
+
+### Type safety
+
+- Strict TypeScript is on
+- Data shapes are defined as `interface`; unions and aliases use `type`
+- `any` stays rare and gets a comment explaining why
+- Return types are explicit when inference leaves the reader guessing
+
+### Modules and exports
+
+- One responsibility per module
+- No barrel files; `package.json` `exports` names the public surface
+- Internal helpers stay internal, even when they look generally useful
+
+### Function design
+
+- Small, focused functions
+- Parameters and non-obvious return types are typed explicitly
+
+```typescript
+interface UserProfile {
+  id: string;
+  displayName: string;
+  createdAt: Date;
+}
+
+async function fetchUserProfile(userId: string): Promise<UserProfile> {
+  const response = await api.get(`/users/${userId}`);
+  return response.data;
+}
+```
+
+## React
+
+### Components
+
+- Functional components with hooks
+- One responsibility per component
+- Explicit props interfaces
+- Composition over inheritance
+
+### Hooks
+
+- Dependencies declared in full for `useEffect`, `useMemo`, `useCallback`
+- Reusable logic extracts into custom hooks (`use` prefix)
+- Subscriptions, timers, and listeners are torn down in cleanup
+- `useEffect` reads as a code smell; most cases have a better form elsewhere
+
+### State
+
+- Local state stays close to where it is used
+- Related state collapses into one object or a `useReducer`
+- Server state lives in a query layer, not in `useState`
+
+```typescript
+interface ButtonProps {
+  variant: 'primary' | 'secondary';
+  isDisabled?: boolean;
+  onClick: () => void;
+  children: React.ReactNode;
+}
+
+function Button({ variant, isDisabled, onClick, children }: ButtonProps) {
+  return (
+    <button className={`btn btn--${variant}`} disabled={isDisabled} onClick={onClick}>
+      {children}
+    </button>
+  );
+}
+```
+
+See [React](./react.md) for the longer form.
+
+## General
+
+### Comments carry the *why*
+
+A comment that restates the next line gets deleted. A comment that names the reason behind a non-obvious choice stays.
+
+```typescript
+// Reset to 1-based index for display
+counter += 1;
+```
+
+### Errors are designed, not caught and dropped
+
+The paths that fail are known when the function is written. Result types are preferred at API boundaries; thrown errors inside a module where the flow is clearer. No `catch` block silently swallows.
+
+```typescript
+try {
+  const result = await riskyOperation();
+  return { success: true, data: result };
+} catch (error) {
+  logger.error('Operation failed', { error });
+  return { success: false, error: 'Operation failed' };
+}
+```
+
+### Inference where it reads, explicit where it doesn't
+
+```typescript
+const names = ['Alice', 'Bob'];           // inferred as string[]
+const config: AppConfig = loadConfig();    // explicit where the type isn't obvious
+```
+
+### Exceptions leave a reason
+
+Lint suppressions and type escapes carry a comment:
+
+```typescript
+// biome-ignore lint/complexity/noForEach: forEach is clearer for side effects here
+items.forEach(sendNotification);
+
+// @ts-expect-error: library types are incorrect for this overload
+const result = legacyLib.process(data);
+```
+
+An unjustified suppression is a regression.
+
+## Related
+
+- [Principles](./principles.md) — Shared principles the patterns build on
+- [React](./react.md) — Component, hook, and state patterns
+- [Naming](./naming.md) — Names across languages
+- [Testing](./testing.md) — Testing philosophy
+
+---
+
+**License**: [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) © Regardio

package/docs/en/standards/commits.md

@@ -0,0 +1,111 @@
+---
+
+title: "Commits"
+description: "Conventional Commits format Regardio projects hold to, so history reads and changelogs generate."
+publishedAt: 2026-04-17
+order: 10
+language: "en"
+status: "published"
+kind: "reference"
+area: "dev"
+---
+
+Commit subjects feed the changelog the outside world reads, and the git history is what a future contributor reaches for when a line of code raises a question. Short, imperative subjects with a type and an optional scope keep both useful.
+
+## Format
+
+```text
+<type>(<scope>): <subject>
+[optional body]
+[optional footer]
+```
+
+- **type** — category of change (required)
+- **scope** — area affected (optional)
+- **subject** — imperative mood, up to 100 characters (required)
+
+## Types
+
+| Type | Description | Changelog |
+|------|-------------|-----------|
+| `feat` | New feature | Features |
+| `fix` | Bug fix | Bug Fixes |
+| `docs` | Documentation only | — |
+| `style` | Formatting | — |
+| `refactor` | Code change with no fix or feature | — |
+| `perf` | Performance improvement | Performance |
+| `test` | Tests | — |
+| `build` | Build or dependency change | — |
+| `ci` | CI configuration | — |
+| `chore` | Other changes | — |
+| `BREAKING CHANGE` | Breaking API change | Breaking Changes |
+
+## Examples
+
+```bash
+# Simple
+feat: add user authentication
+fix: resolve login redirect loop
+
+# With scope
+feat(auth): implement OAuth2 flow
+fix(api): handle null response gracefully
+
+# With body
+fix: prevent race condition in data sync
+
+The previous implementation could cause data corruption.
+A mutex now guards the sequential path.
+
+Closes #123
+
+# Breaking change
+feat!: redesign authentication API
+
+BREAKING CHANGE: auth.login() now returns a Promise.
+Update call sites to use async/await.
+```
+
+## Practices
+
+### Imperative mood
+
+```bash
+# Good
+feat: add validation for email field
+
+# Not good
+feat: added validation for email field
+```
+
+### Atomic commits
+
+Each commit carries one logical change. When a branch has done several things, the history reflects them as separate commits.
+
+### References to issues
+
+```bash
+fix: correct calculation of total price
+
+Closes #456
+Refs #123, #789
+```
+
+## Enforcement
+
+Commit messages are validated by [Commitlint](../tools/commitlint.md) through git hooks.
+
+## Changelog generation
+
+Changelogs are generated from [Changesets](../tools/releases.md) — one-line descriptions authors write with `pnpm changeset` alongside their change. `ship-production` consumes pending changesets at ship time and writes them into each package's `CHANGELOG.md`. The changeset description is what users read, so write it for that reader from the start.
+
+## Related
+
+- [Commitlint](../tools/commitlint.md) — Commit message validation
+- [Releases](../tools/releases.md) — Release workflow that consumes the commits
+- [Naming](./naming.md) — Branch and package naming
+- [Conventional Commits](https://www.conventionalcommits.org/) — The spec this follows
+
+---
+
+**License**: [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) © Regardio