trinity-method-sdk 2.0.8 → 2.1.0

package/dist/templates/trinity/templates/documentation/mermaid-diagrams/component-hierarchy.md.template

@@ -0,0 +1,60 @@
+# Component Hierarchy Diagram Template
+
+<!--
+  This template generates a Mermaid flowchart showing frontend component tree structure.
+
+  Variables:
+  - {{COMPONENT_GROUPS}}: Component definitions and relationships
+  - {{ROOT_COMPONENT}}: Root/App component name
+
+  Usage: Replace variables with actual component structure before writing to docs/images/
+
+  Example COMPONENT_GROUPS format (Mermaid flowchart syntax):
+    App[App]
+    Layout[Layout]
+    Header[Header]
+    Navigation[Navigation]
+    Content[Content]
+    HomePage[HomePage]
+    UserList[UserList]
+    UserCard[UserCard]
+
+    App --> Layout
+
+    Layout --> Header
+    Layout --> Content
+    Header --> Navigation
+    Content --> HomePage
+    HomePage --> UserList
+    UserList --> UserCard
+
+-->
+
+```mermaid
+flowchart TD
+{{COMPONENT_GROUPS}}
+```
+
+## Description
+
+This component hierarchy diagram illustrates the structure of the frontend application's component tree:
+
+- **Root Component**: {{ROOT_COMPONENT}} (entry point)
+- **Layout Components**: Structural components (headers, footers, navigation)
+- **Page Components**: Top-level views and routes
+- **Feature Components**: Reusable UI elements and widgets
+
+**Understanding the Hierarchy:**
+
+- Parent components pass props and context to children
+- Data flows down the tree
+- Events bubble up from children to parents
+- Shared components may appear in multiple branches
+
+**Benefits:**
+
+- Understand component relationships and dependencies
+- Plan component refactoring and extraction
+- Identify opportunities for component reuse
+- Visualize state management flow
+- Plan testing strategy (test leaf components first)

package/dist/templates/trinity/templates/documentation/mermaid-diagrams/database-er.md.template

@@ -0,0 +1,49 @@
+# Database Entity-Relationship Diagram Template
+
+<!--
+  This template generates a Mermaid ER diagram showing database schema structure.
+
+  Variables:
+  - {{ENTITIES}}: Entity definitions in Mermaid ER syntax
+  - {{RELATIONSHIPS}}: Relationship definitions between entities
+
+  Usage: Replace variables with actual schema structure before writing to docs/images/
+
+  Example ENTITIES format:
+    USER {
+      int id PK
+      string email UK
+      string password
+      datetime created_at
+    }
+    ORDER {
+      int id PK
+      int user_id FK
+      decimal total
+      string status
+    }
+
+  Example RELATIONSHIPS format:
+    USER ||--o{ ORDER : places
+-->
+
+```mermaid
+erDiagram
+{{ENTITIES}}
+{{RELATIONSHIPS}}
+```
+
+## Description
+
+This entity-relationship diagram shows the database schema structure for the application, including:
+
+- **Entities**: Tables/collections with their fields and types
+- **Relationships**: How entities relate to each other (one-to-one, one-to-many, many-to-many)
+- **Keys**: Primary keys (PK), foreign keys (FK), and unique keys (UK)
+
+Understanding these relationships is essential for:
+
+- Writing efficient queries
+- Maintaining data integrity
+- Planning schema migrations
+- Optimizing database performance

package/dist/templates/trinity/templates/documentation/mermaid-diagrams/mvc-flow.md.template

@@ -0,0 +1,41 @@
+# MVC Request Flow Diagram Template
+
+<!--
+  This template generates a Mermaid sequence diagram showing the typical MVC request flow.
+
+  Variables:
+  - {{DATABASE}}: Database type (e.g., "PostgreSQL", "SQLite", "MongoDB")
+  - {{FRAMEWORK}}: Backend framework name (e.g., "Express", "Fastify", "Koa")
+
+  Usage: Replace variables with actual project values before writing to docs/images/
+-->
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Routes
+    participant Controller
+    participant Service
+    participant {{DATABASE}}
+
+    Client->>Routes: HTTP Request
+    Routes->>Controller: Route Handler
+    Controller->>Service: Business Logic
+    Service->>{{DATABASE}}: Query Data
+    {{DATABASE}}-->>Service: Return Results
+    Service-->>Controller: Processed Data
+    Controller-->>Routes: Response Data
+    Routes-->>Client: HTTP Response
+```
+
+## Description
+
+This diagram illustrates the typical request flow in an MVC (Model-View-Controller) architecture:
+
+1. **Client** sends an HTTP request to the {{FRAMEWORK}} server
+2. **Routes** match the request to the appropriate controller
+3. **Controller** delegates business logic to the service layer
+4. **Service** performs database operations via the {{DATABASE}} connection
+5. Response flows back through the layers to the client
+
+This pattern ensures separation of concerns and maintainable code structure.

package/dist/templates/trinity/templates/documentation/processes/error-handling-protocol.md.template

@@ -0,0 +1,166 @@
+# Error Handling Protocol
+**Category:** Processes
+**Purpose:** 3-tier error handling system for trinity-docs command
+**Used By:** JUNO, APO-1, APO-2, APO-3, Phase 3 Verification
+
+---
+
+## 3-Tier Error System
+
+### Tier 1: ABORT (Critical Errors)
+**Action:** Stop command execution immediately, report failure
+**Use when:** System cannot proceed, data corruption risk, user intervention required
+
+**Examples:**
+- JUNO report completely missing
+- No package.json found (cannot detect framework)
+- Component verification failed (fake component names detected)
+- Template files missing (cannot read required templates)
+- Write permission denied (cannot create documentation files)
+
+**Log Format:**
+```
+❌ CRITICAL ERROR - ABORTING COMMAND
+Agent: [AGENT_NAME]
+Task: [TASK_NAME]
+Error: [ERROR_DESCRIPTION]
+Recommendation: [HOW_TO_FIX]
+```
+
+### Tier 2: WARN (Recoverable Issues)
+**Action:** Log warning, activate fallback, continue execution
+**Use when:** Data incomplete but work can continue, fallback mechanisms available
+
+**Examples:**
+- JUNO report incomplete (some variables missing)
+- Optional template variables not found
+- Framework detection partial (backend found, frontend unknown)
+- Some environment variables missing
+- API endpoints partially discovered
+
+**Log Format:**
+```
+⚠️ WARNING - Using fallback mechanism
+Agent: [AGENT_NAME]
+Issue: [ISSUE_DESCRIPTION]
+Fallback: [FALLBACK_ACTION_TAKEN]
+Impact: [WHAT_WILL_BE_DIFFERENT]
+```
+
+### Tier 3: LOG (Informational)
+**Action:** Log message only, continue normally
+**Use when:** Normal process updates, optional data, FYI messages
+
+**Examples:**
+- Process milestones ("Reading JUNO report...")
+- File creation confirmations ("Created mvc-flow.md")
+- Discovery counts ("Found 15 components")
+- Optional fields missing (non-critical)
+- Performance metrics ("Execution time: 18s")
+
+**Log Format:**
+```
+ℹ️ INFO - [MESSAGE]
+Agent: [AGENT_NAME]
+Details: [ADDITIONAL_INFO]
+```
+
+---
+
+## Error Handling by Agent
+
+### JUNO Errors
+
+**Tier 1 (ABORT):**
+- Cannot read package.json
+- Cannot write audit report to global state
+- All discovery methods failed (no data found)
+
+**Tier 2 (WARN):**
+- Some discovery methods returned no data
+- Optional metadata missing
+- Framework detection uncertain
+
+**Tier 3 (LOG):**
+- Discovery progress updates
+- Variable extraction counts
+- Report generation milestones
+
+### APO-1 Errors
+
+**Tier 1 (ABORT):**
+- Cannot read JUNO report from global state
+- Component verification failed (fake components)
+- Cannot write diagram files (permission denied)
+
+**Tier 2 (WARN):**
+- Database schema not found (skip database-er.md)
+- No API endpoints discovered (skip api-endpoint-map.md)
+- Mermaid syntax warning (diagram created but may have issues)
+
+**Tier 3 (LOG):**
+- Diagram generation progress
+- File creation confirmations
+- Fallback usage notifications
+
+### APO-2 Errors
+
+**Tier 1 (ABORT):**
+- Cannot read JUNO report from global state
+- Cannot read guide templates from trinity/templates/documentation/
+- Cannot write guide files (permission denied)
+
+**Tier 2 (WARN):**
+- Framework-specific examples unavailable (use generic examples)
+- Test framework unknown (use generic test instructions)
+- Deployment steps uncertain (use common deployment pattern)
+
+**Tier 3 (LOG):**
+- Guide generation progress
+- File creation confirmations
+- Template variable substitutions
+
+### APO-3 Errors
+
+**Tier 1 (ABORT):**
+- Cannot read JUNO report from global state
+- Cannot write .env.example or README.md (permission denied)
+- Security violation detected (real secrets in .env.example)
+
+**Tier 2 (WARN):**
+- No environment variables discovered (.env.example will be minimal)
+- README.md doesn't exist (create new README with warning)
+- Environment variable detection uncertain
+
+**Tier 3 (LOG):**
+- Configuration file generation progress
+- Environment variable counts
+- README update confirmations
+
+---
+
+## Fallback Activation
+
+**When Tier 2 WARN occurs, activate fallback:**
+
+```javascript
+if (juno_incomplete || data_missing) {
+  LOG: "⚠️ FALLBACK MODE ACTIVATED";
+  LOG: `Reason: ${fallback_reason}`;
+
+  // Use discovery templates directly
+  // See trinity/templates/discovery/ for patterns
+
+  // Mark fallback usage
+  fallback_used = true;
+}
+```
+
+**After fallback completes:**
+```javascript
+if (fallback_used && task_complete) {
+  LOG: "✅ FALLBACK SUCCESS - Task completed using direct analysis";
+}
+```
+
+---

package/dist/templates/trinity/templates/documentation/processes/fallback-mechanism.md.template

@@ -0,0 +1,88 @@
+# APO Fallback Mechanisms
+
+When automated discovery fails, APO agents use these fallback procedures to generate documentation.
+
+## Framework Detection Fallback
+
+**If automated framework detection fails:**
+
+1. Check `package.json` for framework dependencies:
+   - Express.js: `"express"` in dependencies
+   - NestJS: `"@nestjs/core"` in dependencies
+   - Next.js: `"next"` in dependencies
+   - React: `"react"` in dependencies
+
+2. Check file patterns:
+   - Django: `manage.py`, `settings.py`
+   - Flask: `app.py`, `@app.route` decorators
+   - Rails: `Gemfile`, `config/routes.rb`
+
+3. Manual fallback: Create generic architecture diagram with placeholder note:
+   ```
+   NOTE: Framework could not be auto-detected.
+   Update this diagram after manual framework identification.
+   ```
+
+## Component Discovery Fallback
+
+**If component scanning finds no results:**
+
+1. Check common directory names: `src/`, `lib/`, `app/`, `server/`
+2. Search for file patterns: `*Controller.js`, `*Service.js`, `*Model.js`
+3. Fallback to directory-based documentation:
+   ```
+   Components organized by directory structure.
+   See subdirectory READMEs for details.
+   ```
+
+## Database Schema Fallback
+
+**If schema files not found:**
+
+1. Check for migration files: `migrations/`, `db/migrate/`
+2. Search for ORM model files: `models/`, `entities/`
+3. Fallback to placeholder ER diagram:
+   ```
+   Database schema not detected in standard locations.
+   Generate schema from migration files or ORM models manually.
+   ```
+
+## API Endpoints Fallback
+
+**If endpoint scanner finds no routes:**
+
+1. Search for route files: `routes/`, `controllers/`, `api/`
+2. Look for route decorators: `@Get`, `@Post`, `@app.route`
+3. Fallback to manual endpoint documentation:
+   ```
+   API endpoints not auto-detected.
+   Document endpoints in docs/api/ manually.
+   ```
+
+## Environment Variables Fallback
+
+**If `.env.example` not found:**
+
+1. Search for `.env` files (do NOT read secrets)
+2. Check for config files: `config/`, `settings.py`, `application.yml`
+3. Generate minimal `.env.example`:
+   ```
+   # Environment Configuration
+   NODE_ENV=development
+   PORT=3000
+
+   # Add environment variables as discovered
+   ```
+
+## Quality Gate: Fallback Detection
+
+APO agents must log when fallback mechanisms are used:
+
+```javascript
+if (fallback_used) {
+  LOG: "⚠️  FALLBACK USED: {fallback_type}";
+  LOG: "   Reason: {detection_failure_reason}";
+  LOG: "   Action: {fallback_action_taken}";
+  LOG: "   Manual review recommended for: {affected_documentation}";
+}
+```