trinity-method-sdk 2.0.9 → 2.2.0

package/dist/templates/trinity/templates/documentation/discovery/framework-detection.md.template

@@ -0,0 +1,205 @@
+# Framework Detection Patterns
+**Category:** Discovery
+**Purpose:** Detect backend frameworks, frontend frameworks, databases, ORMs, and testing frameworks from package.json
+**Used By:** JUNO (Phase 1), APO-1, APO-2, APO-3 (Fallback Mode)
+
+---
+
+## Overview
+
+This template provides patterns for detecting technologies used in a codebase by analyzing `package.json` dependencies.
+
+---
+
+## How to Use
+
+1. Read and parse the project's `package.json` file
+2. Check both `dependencies` and `devDependencies` for framework matches
+3. Identify frameworks by package name patterns
+4. Store detected frameworks for template variable substitution
+
+---
+
+## Framework Detection Logic
+
+### Package Analysis Pattern
+
+```javascript
+const pkg_json = Read("package.json");
+const pkg = JSON.parse(pkg_json);
+
+// Combine all dependencies
+const all_deps = {
+  ...pkg.dependencies,
+  ...pkg.devDependencies
+};
+
+// Detect frameworks by package name
+```
+
+---
+
+## Detection Categories
+
+### 1. Backend Frameworks
+
+**Patterns to detect:**
+- `express` → Express.js
+- `fastify` → Fastify
+- `koa` → Koa
+- `hapi` → Hapi
+- `@nestjs/core` or `@nestjs/common` → NestJS
+- `next` → Next.js (full-stack)
+
+**Example:**
+```javascript
+if (all_deps['express']) backend_framework = 'Express.js';
+if (all_deps['@nestjs/core']) backend_framework = 'NestJS';
+```
+
+---
+
+### 2. Frontend Frameworks
+
+**Patterns to detect:**
+- `react` → React
+- `vue` → Vue.js
+- `@angular/core` → Angular
+- `svelte` → Svelte
+- `solid-js` → SolidJS
+- `preact` → Preact
+
+**Example:**
+```javascript
+if (all_deps['react']) frontend_framework = 'React';
+if (all_deps['vue']) frontend_framework = 'Vue.js';
+```
+
+---
+
+### 3. Database & ORM
+
+**Patterns to detect:**
+- `prisma` or `@prisma/client` → Prisma
+- `typeorm` → TypeORM
+- `sequelize` → Sequelize
+- `mongoose` → Mongoose (MongoDB)
+- `knex` → Knex.js
+- `pg` → PostgreSQL (direct driver)
+- `mysql` or `mysql2` → MySQL (direct driver)
+- `mongodb` → MongoDB (direct driver)
+
+**Example:**
+```javascript
+if (all_deps['@prisma/client']) orm = 'Prisma';
+if (all_deps['typeorm']) orm = 'TypeORM';
+if (all_deps['pg']) database = 'PostgreSQL';
+```
+
+---
+
+### 4. Testing Frameworks
+
+**Patterns to detect:**
+- `jest` → Jest
+- `vitest` → Vitest
+- `mocha` → Mocha
+- `jasmine` → Jasmine
+- `cypress` → Cypress (E2E)
+- `playwright` or `@playwright/test` → Playwright (E2E)
+- `@testing-library/react` → React Testing Library
+
+**Example:**
+```javascript
+if (all_deps['jest']) test_framework = 'Jest';
+if (all_deps['vitest']) test_framework = 'Vitest';
+if (all_deps['cypress']) e2e_framework = 'Cypress';
+```
+
+---
+
+## Fallback Detection
+
+If `package.json` is missing or cannot be parsed:
+1. **Backend:** Search for `server.js`, `app.js`, `index.ts` in `src/`, `server/` directories
+2. **Frontend:** Check for `index.html`, `App.tsx`, `App.vue` in `src/`, `client/` directories
+3. **Database:** Look for `prisma/schema.prisma`, TypeORM entity files with `@Entity` decorator
+4. **Testing:** Check for `jest.config.js`, `vitest.config.ts`, `cypress.config.js`
+
+---
+
+## Template Variable Mapping
+
+**Variables to populate:**
+- `{{BACKEND_FRAMEWORK}}` → Backend framework name (e.g., "Express.js", "NestJS")
+- `{{FRONTEND_FRAMEWORK}}` → Frontend framework name (e.g., "React", "Vue.js")
+- `{{DATABASE}}` → Database system (e.g., "PostgreSQL", "MongoDB")
+- `{{ORM}}` → ORM/Query builder (e.g., "Prisma", "TypeORM")
+- `{{TEST_FRAMEWORK}}` → Testing framework (e.g., "Jest", "Vitest")
+- `{{E2E_FRAMEWORK}}` → E2E testing framework (e.g., "Cypress", "Playwright")
+
+---
+
+## Error Handling
+
+**If no frameworks detected:**
+- Log warning: "⚠️ FALLBACK: No frameworks detected in package.json - manual detection required"
+- Use fallback detection methods (file system scanning)
+- If still unsuccessful, mark as "Unknown" but continue processing
+
+**If multiple frameworks detected (uncommon but possible):**
+- Select primary framework (most commonly used)
+- Log info: "ℹ️ Multiple frameworks detected: [list] - using [primary]"
+
+---
+
+## Examples
+
+### Example 1: Express + React + Prisma Stack
+
+```javascript
+// package.json dependencies:
+{
+  "express": "^4.18.2",
+  "react": "^18.2.0",
+  "@prisma/client": "^5.0.0",
+  "jest": "^29.5.0"
+}
+
+// Detection result:
+BACKEND_FRAMEWORK = "Express.js"
+FRONTEND_FRAMEWORK = "React"
+ORM = "Prisma"
+TEST_FRAMEWORK = "Jest"
+```
+
+### Example 2: NestJS + Angular + TypeORM Stack
+
+```javascript
+// package.json dependencies:
+{
+  "@nestjs/core": "^10.0.0",
+  "@angular/core": "^16.0.0",
+  "typeorm": "^0.3.17",
+  "pg": "^8.11.0",
+  "jest": "^29.5.0"
+}
+
+// Detection result:
+BACKEND_FRAMEWORK = "NestJS"
+FRONTEND_FRAMEWORK = "Angular"
+ORM = "TypeORM"
+DATABASE = "PostgreSQL"
+TEST_FRAMEWORK = "Jest"
+```
+
+---
+
+## Best Practices
+
+1. **Always check both `dependencies` and `devDependencies`** - Testing frameworks are often in `devDependencies`
+2. **Use specific package names** - Don't use fuzzy matching to avoid false positives
+3. **Log all detections** - Help debugging if detection fails
+4. **Graceful degradation** - If detection fails, continue with "Unknown" rather than aborting
+
+---

package/dist/templates/trinity/templates/documentation/guides/api-development.md.template

@@ -0,0 +1,375 @@
+# API Development Guide
+
+This guide covers best practices for developing REST API endpoints in {{PROJECT_NAME}}.
+
+---
+
+## Architecture Overview
+
+{{PROJECT_NAME}} follows a **{{ARCHITECTURE_PATTERN}}** architecture:
+
+- **Framework:** {{FRAMEWORK}} {{FRAMEWORK_VERSION}}
+- **Database:** {{DATABASE_TYPE}}
+- **ORM:** {{DATABASE_ORM}}
+- **Authentication:** {{AUTH_METHOD}}
+- **Validation:** {{VALIDATION_LIBRARY}}
+
+---
+
+## Project Structure
+
+```
+{{API_DIRECTORY}}/
+├── routes/              # API route definitions
+├── controllers/         # Request handlers
+├── models/             # Data models ({{DATABASE_ORM}})
+├── middleware/         # Custom middleware
+├── validators/         # Request validation schemas
+└── services/           # Business logic
+```
+
+---
+
+## Creating a New Endpoint
+
+### Step 1: Define the Route
+
+**File:** `{{ROUTES_DIRECTORY}}/{{EXAMPLE_RESOURCE}}.routes.ts`
+
+```typescript
+import express from 'express';
+import { {{EXAMPLE_CONTROLLER}} } from '../controllers/{{EXAMPLE_RESOURCE}}.controller';
+{{AUTH_IMPORT}}
+
+const router = express.Router();
+
+// GET /api/{{EXAMPLE_RESOURCE}}
+router.get('/', {{EXAMPLE_CONTROLLER}}.getAll);
+
+// GET /api/{{EXAMPLE_RESOURCE}}/:id
+router.get('/:id', {{EXAMPLE_CONTROLLER}}.getById);
+
+// POST /api/{{EXAMPLE_RESOURCE}}
+router.post('/', {{AUTH_MIDDLEWARE}}, {{EXAMPLE_CONTROLLER}}.create);
+
+// PUT /api/{{EXAMPLE_RESOURCE}}/:id
+router.put('/:id', {{AUTH_MIDDLEWARE}}, {{EXAMPLE_CONTROLLER}}.update);
+
+// DELETE /api/{{EXAMPLE_RESOURCE}}/:id
+router.delete('/:id', {{AUTH_MIDDLEWARE}}, {{EXAMPLE_CONTROLLER}}.delete);
+
+export default router;
+```
+
+### Step 2: Create the Controller
+
+**File:** `{{CONTROLLERS_DIRECTORY}}/{{EXAMPLE_RESOURCE}}.controller.ts`
+
+```typescript
+import { Request, Response } from 'express';
+import { {{EXAMPLE_SERVICE}} } from '../services/{{EXAMPLE_RESOURCE}}.service';
+
+export const {{EXAMPLE_CONTROLLER}} = {
+  async getAll(req: Request, res: Response) {
+    try {
+      const items = await {{EXAMPLE_SERVICE}}.findAll();
+      res.json(items);
+    } catch (error) {
+      res.status(500).json({ error: error.message });
+    }
+  },
+
+  async getById(req: Request, res: Response) {
+    try {
+      const item = await {{EXAMPLE_SERVICE}}.findById(req.params.id);
+      if (!item) {
+        return res.status(404).json({ error: 'Not found' });
+      }
+      res.json(item);
+    } catch (error) {
+      res.status(500).json({ error: error.message });
+    }
+  },
+
+  async create(req: Request, res: Response) {
+    try {
+      const item = await {{EXAMPLE_SERVICE}}.create(req.body);
+      res.status(201).json(item);
+    } catch (error) {
+      res.status(400).json({ error: error.message });
+    }
+  },
+
+  async update(req: Request, res: Response) {
+    try {
+      const item = await {{EXAMPLE_SERVICE}}.update(req.params.id, req.body);
+      if (!item) {
+        return res.status(404).json({ error: 'Not found' });
+      }
+      res.json(item);
+    } catch (error) {
+      res.status(400).json({ error: error.message });
+    }
+  },
+
+  async delete(req: Request, res: Response) {
+    try {
+      await {{EXAMPLE_SERVICE}}.delete(req.params.id);
+      res.status(204).send();
+    } catch (error) {
+      res.status(500).json({ error: error.message });
+    }
+  }
+};
+```
+
+### Step 3: Implement the Service
+
+**File:** `{{SERVICES_DIRECTORY}}/{{EXAMPLE_RESOURCE}}.service.ts`
+
+```typescript
+import { {{ORM_CLIENT}} } from '../db';
+
+export const {{EXAMPLE_SERVICE}} = {
+  async findAll() {
+    return {{ORM_CLIENT}}.{{EXAMPLE_MODEL}}.findMany();
+  },
+
+  async findById(id: string) {
+    return {{ORM_CLIENT}}.{{EXAMPLE_MODEL}}.findUnique({ where: { id } });
+  },
+
+  async create(data: any) {
+    return {{ORM_CLIENT}}.{{EXAMPLE_MODEL}}.create({ data });
+  },
+
+  async update(id: string, data: any) {
+    return {{ORM_CLIENT}}.{{EXAMPLE_MODEL}}.update({ where: { id }, data });
+  },
+
+  async delete(id: string) {
+    return {{ORM_CLIENT}}.{{EXAMPLE_MODEL}}.delete({ where: { id } });
+  }
+};
+```
+
+### Step 4: Register the Route
+
+**File:** `{{MAIN_SERVER_FILE}}`
+
+```typescript
+import {{EXAMPLE_RESOURCE}}Routes from './routes/{{EXAMPLE_RESOURCE}}.routes';
+
+app.use('/api/{{EXAMPLE_RESOURCE}}', {{EXAMPLE_RESOURCE}}Routes);
+```
+
+---
+
+## Request Validation
+
+{{VALIDATION_SECTION}}
+
+---
+
+## Authentication & Authorization
+
+{{AUTHENTICATION_SECTION}}
+
+---
+
+## Error Handling
+
+### Standard Error Response Format
+
+```json
+{
+  "error": "Error message",
+  "statusCode": 400,
+  "timestamp": "2026-01-15T12:00:00Z",
+  "path": "/api/{{EXAMPLE_RESOURCE}}"
+}
+```
+
+### Error Handler Middleware
+
+```typescript
+app.use((error: Error, req: Request, res: Response, next: NextFunction) => {
+  const statusCode = error.statusCode || 500;
+  res.status(statusCode).json({
+    error: error.message,
+    statusCode,
+    timestamp: new Date().toISOString(),
+    path: req.path
+  });
+});
+```
+
+---
+
+## Testing API Endpoints
+
+### Unit Tests
+
+**File:** `{{TEST_DIRECTORY}}/{{EXAMPLE_RESOURCE}}.test.ts`
+
+```typescript
+import { {{EXAMPLE_SERVICE}} } from '../services/{{EXAMPLE_RESOURCE}}.service';
+
+describe('{{EXAMPLE_SERVICE}}', () => {
+  it('should create a new item', async () => {
+    const data = { name: 'Test Item' };
+    const result = await {{EXAMPLE_SERVICE}}.create(data);
+    expect(result.name).toBe('Test Item');
+  });
+
+  it('should find item by id', async () => {
+    const item = await {{EXAMPLE_SERVICE}}.findById('123');
+    expect(item).toBeDefined();
+  });
+});
+```
+
+### Integration Tests
+
+```typescript
+import request from 'supertest';
+import app from '../app';
+
+describe('{{EXAMPLE_RESOURCE}} API', () => {
+  it('GET /api/{{EXAMPLE_RESOURCE}} should return all items', async () => {
+    const response = await request(app).get('/api/{{EXAMPLE_RESOURCE}}');
+    expect(response.status).toBe(200);
+    expect(Array.isArray(response.body)).toBe(true);
+  });
+
+  it('POST /api/{{EXAMPLE_RESOURCE}} should create item', async () => {
+    const data = { name: 'New Item' };
+    const response = await request(app)
+      .post('/api/{{EXAMPLE_RESOURCE}}')
+      .send(data);
+    expect(response.status).toBe(201);
+    expect(response.body.name).toBe('New Item');
+  });
+});
+```
+
+---
+
+## Best Practices
+
+### 1. Use Async/Await
+
+Always use async/await for database operations and external API calls.
+
+### 2. Validate Input
+
+Use {{VALIDATION_LIBRARY}} to validate request data before processing.
+
+### 3. Handle Errors Properly
+
+Catch all errors and return appropriate HTTP status codes.
+
+### 4. Implement Authentication
+
+Protect sensitive endpoints with authentication middleware.
+
+### 5. Write Tests
+
+Aim for 80%+ test coverage on API endpoints.
+
+### 6. Document Endpoints
+
+Update API documentation when adding or modifying endpoints.
+
+---
+
+## Database Migrations
+
+{{DATABASE_MIGRATION_SECTION}}
+
+---
+
+## API Versioning
+
+{{API_VERSIONING_SECTION}}
+
+---
+
+## Performance Optimization
+
+### Database Query Optimization
+
+- Use indexes on frequently queried fields
+- Implement pagination for large datasets
+- Use eager loading to avoid N+1 queries
+- Cache frequently accessed data
+
+### Example: Pagination
+
+```typescript
+async findAll(page: number = 1, limit: number = 20) {
+  const skip = (page - 1) * limit;
+  return {{ORM_CLIENT}}.{{EXAMPLE_MODEL}}.findMany({
+    skip,
+    take: limit,
+    orderBy: { createdAt: 'desc' }
+  });
+}
+```
+
+---
+
+## Common Patterns
+
+### Pattern: Resource CRUD
+
+All resources follow the same CRUD pattern:
+- GET /api/{resource} - List all
+- GET /api/{resource}/:id - Get by ID
+- POST /api/{resource} - Create
+- PUT /api/{resource}/:id - Update
+- DELETE /api/{resource}/:id - Delete
+
+### Pattern: Nested Resources
+
+```typescript
+// GET /api/users/:userId/posts
+router.get('/users/:userId/posts', postsController.getByUserId);
+```
+
+### Pattern: Query Parameters
+
+```typescript
+// GET /api/{{EXAMPLE_RESOURCE}}?search=term&limit=10&page=2
+router.get('/', async (req: Request, res: Response) => {
+  const { search, limit = 20, page = 1 } = req.query;
+  // Implementation
+});
+```
+
+---
+
+## Debugging
+
+### Enable Debug Logging
+
+{{DEBUG_LOGGING_SECTION}}
+
+### API Testing Tools
+
+- **Postman:** GUI for testing API endpoints
+- **cURL:** Command-line API testing
+- **Thunder Client:** VS Code extension for API testing
+
+---
+
+## Related Documentation
+
+- [API Reference](../api/README.md) - Complete endpoint documentation
+- [Getting Started](./getting-started.md) - Project setup guide
+- [Deployment Guide](./deployment.md) - Production deployment
+- [Contributing Guidelines](../CONTRIBUTING.md) - Code standards
+
+---
+
+*Last updated: {{GENERATION_DATE}}*