@mind-fold/open-flow 0.1.17 → 0.2.2

package/dist/templates/markdown/structure/backend/index.md.txt

@@ -0,0 +1,88 @@
+# Backend Development Guidelines
+
+> Best practices for backend development
+
+---
+
+## Overview
+
+This collection of guidelines covers essential patterns and best practices for building robust backend applications.
+
+---
+
+## Guidelines Index
+
+### Core Patterns
+
+| Guide | Description |
+|-------|-------------|
+| [Directory Structure](./directory-structure.md) | Module organization and file layout |
+| [Type Safety](./type-safety.md) | Zod validation, non-null handling, type inference |
+| [Quality Guidelines](./quality-guidelines.md) | Forbidden patterns, code standards |
+
+### Database & Data
+
+| Guide | Description |
+|-------|-------------|
+| [Database Guidelines](./database-guidelines.md) | ORM patterns, batch operations, migrations |
+
+### Operations
+
+| Guide | Description |
+|-------|-------------|
+| [Logging Guidelines](./logging-guidelines.md) | Structured logging, log levels, context |
+| [Error Handling](./error-handling.md) | Error types, handling strategies |
+
+---
+
+## Quick Reference
+
+### Directory Structure
+
+```
+server/
+├── db/                      # Database (client, schema)
+├── lib/                     # Shared utilities
+├── middleware/              # Middleware
+├── routes/                  # API routes (domain-driven)
+│   └── {domain}/
+│       ├── types.ts         # Zod schemas + types
+│       ├── router.ts        # Route definitions
+│       ├── procedures/      # One file per endpoint
+│       └── lib/             # Domain-specific logic
+└── types.ts                 # Shared types
+```
+
+### Key Rules
+
+| Rule | Description |
+|------|-------------|
+| No `!` assertions | Use null checks with local variables |
+| No `console.log` | Use structured logger |
+| No `await` in loops | Use batch queries with `inArray` |
+| Validate all inputs | Use Zod schemas |
+
+---
+
+## Getting Started
+
+1. **New to this codebase?** Start with [Directory Structure](./directory-structure.md)
+2. **Setting up database?** Read [Database Guidelines](./database-guidelines.md)
+3. **Before commit?** Check [Quality Guidelines](./quality-guidelines.md)
+
+---
+
+## Common Tasks
+
+### Create a New API Module
+
+```bash
+mkdir -p server/routes/{domain}/procedures
+touch server/routes/{domain}/{types.ts,router.ts}
+```
+
+See: [Directory Structure](./directory-structure.md)
+
+---
+
+**Language**: All documentation must be written in **English**.

package/dist/templates/markdown/structure/backend/logging-guidelines.md.txt

@@ -0,0 +1,212 @@
+# Logging Guidelines
+
+> Structured logging best practices
+
+---
+
+## Core Rules
+
+1. **Never use `console.log`** - Use structured logger
+2. **Include context** - Add relevant IDs and metadata
+3. **Use appropriate levels** - Match severity to log level
+4. **Use snake_case** - For log message names
+
+---
+
+## Log Levels
+
+| Level | Use Case | Example |
+|-------|----------|---------|
+| `error` | Errors that need attention | Database connection failed |
+| `warn` | Potential issues, degraded state | Rate limit approaching |
+| `info` | Normal operations, business events | User created, order placed |
+| `debug` | Development details | Query executed, cache hit |
+
+---
+
+## Structured Logging
+
+### Basic Pattern
+
+```typescript
+// ✅ GOOD: Structured with context
+logger.info('user_created', { 
+  userId: user.id, 
+  email: user.email 
+});
+
+logger.error('payment_failed', error, { 
+  userId: user.id, 
+  amount: order.total 
+});
+
+// ❌ BAD: Unstructured string concatenation
+console.log('User created: ' + user.id);
+logger.info('Error: ' + error.message);
+```
+
+### With Request Context
+
+```typescript
+// In route handler
+app.get('/api/users/:id', async (c) => {
+  const logger = c.get('logger');
+  const userId = c.req.param('id');
+  
+  logger.info('fetching_user', { userId });
+  
+  const user = await getUser(userId);
+  if (!user) {
+    logger.warn('user_not_found', { userId });
+    return c.json({ error: 'Not found' }, 404);
+  }
+  
+  logger.info('user_fetched', { userId, email: user.email });
+  return c.json(user);
+});
+```
+
+---
+
+## Standard Log Messages
+
+Use consistent message names across the codebase:
+
+| Message | Level | When |
+|---------|-------|------|
+| `request_start` | info | Request begins |
+| `request_end` | info | Request completes |
+| `request_error` | error | Unhandled error |
+| `{entity}_created` | info | Entity created |
+| `{entity}_updated` | info | Entity updated |
+| `{entity}_deleted` | info | Entity deleted |
+| `{entity}_not_found` | warn | Entity lookup failed |
+| `validation_error` | warn | Input validation failed |
+| `auth_failed` | warn | Authentication failed |
+| `permission_denied` | warn | Authorization failed |
+
+---
+
+## Error Logging
+
+Always include the error object for stack traces:
+
+```typescript
+try {
+  await riskyOperation();
+} catch (error) {
+  if (error instanceof Error) {
+    logger.error('operation_failed', error, {
+      operationId: opId,
+      step: currentStep,
+    });
+  } else {
+    logger.error('operation_failed', undefined, { 
+      error: String(error) 
+    });
+  }
+  throw error;  // Re-throw or handle appropriately
+}
+```
+
+---
+
+## Performance Logging
+
+Track duration for slow operations:
+
+```typescript
+async function syncData(logger: Logger) {
+  const startTime = Date.now();
+  
+  try {
+    await performSync();
+    
+    const duration = Date.now() - startTime;
+    logger.info('sync_completed', { durationMs: duration });
+    
+    if (duration > 5000) {
+      logger.warn('sync_slow', { durationMs: duration });
+    }
+  } catch (error) {
+    logger.error('sync_failed', error, { 
+      durationMs: Date.now() - startTime 
+    });
+    throw error;
+  }
+}
+```
+
+---
+
+## What NOT to Log
+
+| Never Log | Reason |
+|-----------|--------|
+| Passwords | Security |
+| API keys / tokens | Security |
+| Full credit card numbers | PCI compliance |
+| Personal health info | HIPAA compliance |
+| Session cookies | Security |
+
+```typescript
+// ❌ BAD
+logger.info('login_attempt', { email, password });
+
+// ✅ GOOD
+logger.info('login_attempt', { email });
+```
+
+---
+
+## Logger Setup Example
+
+```typescript
+// lib/logger.ts
+export interface Logger {
+  info(message: string, meta?: Record<string, unknown>): void;
+  warn(message: string, meta?: Record<string, unknown>): void;
+  error(message: string, error?: Error, meta?: Record<string, unknown>): void;
+  debug(message: string, meta?: Record<string, unknown>): void;
+}
+
+export function createLogger(context: Record<string, unknown> = {}): Logger {
+  const log = (level: string, message: string, meta: Record<string, unknown> = {}) => {
+    const entry = {
+      timestamp: new Date().toISOString(),
+      level,
+      message,
+      ...context,
+      ...meta,
+    };
+    console.log(JSON.stringify(entry));
+  };
+
+  return {
+    info: (message, meta) => log('info', message, meta),
+    warn: (message, meta) => log('warn', message, meta),
+    error: (message, error, meta) => log('error', message, {
+      ...meta,
+      error: error?.message,
+      stack: error?.stack,
+    }),
+    debug: (message, meta) => log('debug', message, meta),
+  };
+}
+```
+
+---
+
+## Summary
+
+| Rule | Description |
+|------|-------------|
+| No `console.log` | Use structured logger |
+| snake_case messages | `user_created` not `User Created` |
+| Include IDs | Add entity IDs to context |
+| No sensitive data | Never log passwords/tokens |
+| Track duration | Log `durationMs` for slow ops |
+
+---
+
+**Language**: All documentation must be written in **English**.

package/dist/templates/markdown/structure/backend/quality-guidelines.md.txt

@@ -0,0 +1,219 @@
+# Quality Guidelines
+
+> Code standards and forbidden patterns
+
+---
+
+## Before Every Commit
+
+Run these checks before committing:
+
+```bash
+# Must pass with 0 errors
+pnpm lint
+
+# Must pass with no type errors  
+pnpm type-check
+
+# Run tests
+pnpm test
+```
+
+---
+
+## Forbidden Patterns
+
+### Non-Null Assertions
+
+```typescript
+// ❌ FORBIDDEN
+const name = user!.name;
+const data = response!.data;
+
+// ✅ REQUIRED
+const user = await getUser(id);
+if (!user) {
+  throw new NotFoundError('User not found');
+}
+const name = user.name;
+```
+
+### Console.log
+
+```typescript
+// ❌ FORBIDDEN
+console.log('Debug:', data);
+console.error('Error:', error);
+
+// ✅ REQUIRED
+logger.debug('processing_data', { data });
+logger.error('operation_failed', error);
+```
+
+### Await in Loops
+
+```typescript
+// ❌ FORBIDDEN
+for (const id of ids) {
+  await db.select().from(users).where(eq(users.id, id));
+}
+
+// ✅ REQUIRED
+const results = await db
+  .select()
+  .from(users)
+  .where(inArray(users.id, ids));
+```
+
+### Type Assertions Without Validation
+
+```typescript
+// ❌ FORBIDDEN
+const data = input as UserData;
+const config = JSON.parse(str) as Config;
+
+// ✅ REQUIRED
+const data = userDataSchema.parse(input);
+const config = configSchema.parse(JSON.parse(str));
+```
+
+### Any Type
+
+```typescript
+// ❌ FORBIDDEN
+function process(data: any) { ... }
+const result: any = await fetch(...);
+
+// ✅ REQUIRED
+function process(data: unknown) {
+  const validated = schema.parse(data);
+  ...
+}
+```
+
+---
+
+## Required Patterns
+
+### Error Handling
+
+```typescript
+// Always handle errors explicitly
+try {
+  await riskyOperation();
+} catch (error) {
+  logger.error('operation_failed', error);
+  throw new AppError('Operation failed', { cause: error });
+}
+```
+
+### Input Validation
+
+```typescript
+// All API inputs must be validated
+app.post('/users', async (c) => {
+  const input = createUserSchema.parse(await c.req.json());
+  // Now input is type-safe
+});
+```
+
+### Null Checks
+
+```typescript
+// Always check nullable values before use
+const user = await getUser(id);
+if (!user) {
+  return c.json({ error: 'User not found' }, 404);
+}
+// TypeScript knows user is not null here
+```
+
+---
+
+## Code Style
+
+### Naming
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Variables | camelCase | `userName`, `isActive` |
+| Functions | camelCase | `createUser`, `validateInput` |
+| Types/Interfaces | PascalCase | `UserData`, `CreateUserInput` |
+| Constants | SCREAMING_SNAKE | `MAX_RETRIES`, `API_TIMEOUT` |
+| Files | kebab-case | `user-service.ts`, `auth-middleware.ts` |
+
+### Function Length
+
+- Keep functions under 50 lines
+- Extract helper functions for complex logic
+- One function = one responsibility
+
+### Comments
+
+```typescript
+// ✅ GOOD: Explain WHY, not WHAT
+// Skip validation for internal calls to avoid performance overhead
+const data = trustInternalData(input);
+
+// ❌ BAD: Obvious comment
+// Get user by id
+const user = await getUser(id);
+```
+
+---
+
+## Documentation
+
+### API Endpoints
+
+Document every public API endpoint:
+
+```typescript
+/**
+ * Create a new user
+ * 
+ * @route POST /api/users
+ * @param email - User's email address
+ * @param name - User's display name
+ * @returns Created user object
+ * @throws 400 - Invalid input
+ * @throws 409 - Email already exists
+ */
+```
+
+### Complex Logic
+
+Document non-obvious business logic:
+
+```typescript
+/**
+ * Calculate user's subscription tier based on usage.
+ * 
+ * Tier calculation:
+ * - Free: < 100 requests/month
+ * - Pro: 100-10000 requests/month  
+ * - Enterprise: > 10000 requests/month
+ * 
+ * Note: Calculated at month end, not real-time.
+ */
+```
+
+---
+
+## Checklist
+
+Before submitting code for review:
+
+- [ ] No `console.log` statements
+- [ ] No `!` non-null assertions
+- [ ] No `any` types
+- [ ] No `await` in loops
+- [ ] All inputs validated with Zod
+- [ ] Errors logged with context
+- [ ] `pnpm lint` passes
+- [ ] `pnpm type-check` passes
+- [ ] Tests pass
+
+---
+
+**Language**: All documentation must be written in **English**.

package/dist/templates/markdown/structure/backend/type-safety.md.txt

@@ -0,0 +1,192 @@
+# Type Safety
+
+> Zod validation, non-null handling, and type inference patterns
+
+---
+
+## Core Principles
+
+1. **Validate at boundaries** - All external inputs must be validated
+2. **Infer from schemas** - Don't duplicate type definitions
+3. **No assertions** - Never use `!` or `as` without validation
+4. **Explicit nullability** - Handle null/undefined explicitly
+
+---
+
+## Zod Schema Patterns
+
+### Basic Schema
+
+```typescript
+import { z } from 'zod';
+
+export const userSchema = z.object({
+  id: z.string(),
+  email: z.string().email(),
+  name: z.string().min(1).max(100),
+  age: z.number().int().positive().optional(),
+  role: z.enum(['admin', 'user', 'guest']),
+  createdAt: z.date(),
+});
+
+// Infer type from schema
+export type User = z.infer<typeof userSchema>;
+```
+
+### Input vs Output Schemas
+
+```typescript
+// Input: what client sends
+export const createUserInput = z.object({
+  email: z.string().email(),
+  name: z.string().min(1),
+  password: z.string().min(8),
+});
+
+// Output: what server returns (no password!)
+export const userOutput = z.object({
+  id: z.string(),
+  email: z.string(),
+  name: z.string(),
+  createdAt: z.date(),
+});
+
+export type CreateUserInput = z.infer<typeof createUserInput>;
+export type UserOutput = z.infer<typeof userOutput>;
+```
+
+### Partial and Pick
+
+```typescript
+// For updates - all fields optional
+export const updateUserInput = createUserInput.partial();
+
+// Pick specific fields
+export const userSummary = userSchema.pick({
+  id: true,
+  name: true,
+});
+```
+
+---
+
+## No Non-Null Assertions
+
+**Never use `!` operator.** It bypasses TypeScript's null safety.
+
+### Problem
+
+```typescript
+// ❌ BAD: Crashes if user is null
+const user = await getUser(id);
+const name = user!.name;  // TypeScript trusts you, runtime doesn't
+```
+
+### Solution: Guard with Local Variable
+
+```typescript
+// ✅ GOOD: Explicit null check
+const user = await getUser(id);
+if (!user) {
+  throw new NotFoundError('User not found');
+}
+// TypeScript now knows user is not null
+const name = user.name;  // Safe access
+```
+
+### Solution: Early Return
+
+```typescript
+// ✅ GOOD: Early return pattern
+async function getUserName(id: string): Promise<string> {
+  const user = await getUser(id);
+  if (!user) {
+    throw new NotFoundError('User not found');
+  }
+  return user.name;
+}
+```
+
+---
+
+## Type Inference from Database
+
+### Drizzle ORM
+
+```typescript
+import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core';
+
+export const users = sqliteTable('users', {
+  id: text('id').primaryKey(),
+  email: text('email').notNull(),
+  name: text('name').notNull(),
+  createdAt: integer('created_at', { mode: 'timestamp_ms' }).notNull(),
+});
+
+// Infer types from schema
+export type User = typeof users.$inferSelect;
+export type InsertUser = typeof users.$inferInsert;
+```
+
+### Align Zod with Database
+
+```typescript
+// Database schema is source of truth
+// Zod schema for API validation should match
+
+export const createUserInput = z.object({
+  email: z.string().email(),
+  name: z.string().min(1),
+}) satisfies z.ZodType<Omit<InsertUser, 'id' | 'createdAt'>>;
+```
+
+---
+
+## Forbidden Patterns
+
+| Pattern | Problem | Solution |
+|---------|---------|----------|
+| `user!.name` | Runtime crash if null | Null check + local variable |
+| `data as User` | No runtime validation | Use Zod `.parse()` |
+| `any` type | Disables type checking | Use `unknown` + validation |
+| Duplicate types | Drift between definitions | Infer from single source |
+
+---
+
+## Best Practices
+
+### DO
+
+```typescript
+// Parse external data
+const data = userSchema.parse(externalInput);
+
+// Use safeParse for graceful handling
+const result = userSchema.safeParse(input);
+if (!result.success) {
+  return { error: result.error.format() };
+}
+
+// Explicit null handling
+const user = await db.query.users.findFirst({ where: eq(users.id, id) });
+if (!user) {
+  throw new NotFoundError(`User ${id} not found`);
+}
+```
+
+### DON'T
+
+```typescript
+// Trust external data
+const data = externalInput as User;  // ❌
+
+// Use non-null assertion
+const name = user!.name;  // ❌
+
+// Ignore parse errors
+const data = userSchema.parse(input);  // ❌ Throws on invalid
+```
+
+---
+
+**Language**: All documentation must be written in **English**.