mddd-cli 4.2.1 → 4.2.3

package/.agents/skills/mermaid-diagrams/references/sequence-diagrams.md

@@ -0,0 +1,394 @@
+# Sequence Diagrams
+
+Sequence diagrams show interactions between participants over time. They're ideal for API flows, authentication sequences, and system component interactions.
+
+## Basic Syntax
+
+```mermaid
+sequenceDiagram
+    participant A
+    participant B
+    A->>B: Message
+```
+
+## Participants and Actors
+
+```mermaid
+sequenceDiagram
+    actor User
+    participant Frontend
+    participant API
+    participant Database
+    
+    User->>Frontend: Click button
+    Frontend->>API: POST /data
+```
+
+**Difference:**
+- `participant` - System components (services, classes, databases)
+- `actor` - External entities (users, external systems)
+
+## Message Types
+
+### Solid Arrow (Synchronous)
+```mermaid
+sequenceDiagram
+    Client->>Server: Request
+    Server-->>Client: Response
+```
+
+- `->>`  Solid arrow (request)
+- `-->>`  Dotted arrow (response/return)
+
+### Open Arrow (Asynchronous)
+```mermaid
+sequenceDiagram
+    Client-)Server: Async message
+    Server--)Client: Async response
+```
+
+- `-)` Solid open arrow
+- `--)` Dotted open arrow
+
+### Cross/X (Delete)
+```mermaid
+sequenceDiagram
+    Client-xServer: Delete
+```
+
+## Activations
+
+Show when a participant is actively processing:
+
+```mermaid
+sequenceDiagram
+    Client->>+Server: Request
+    Server->>+Database: Query
+    Database-->>-Server: Data
+    Server-->>-Client: Response
+```
+
+- `+` after arrow activates
+- `-` before arrow deactivates
+
+## Alt/Else (Conditional Logic)
+
+```mermaid
+sequenceDiagram
+    User->>API: POST /login
+    API->>Database: Query user
+    Database-->>API: User data
+    
+    alt Valid credentials
+        API-->>User: 200 OK + Token
+    else Invalid credentials
+        API-->>User: 401 Unauthorized
+    else Account locked
+        API-->>User: 403 Forbidden
+    end
+```
+
+## Opt (Optional)
+
+```mermaid
+sequenceDiagram
+    User->>API: POST /order
+    API->>PaymentService: Process payment
+    
+    opt Payment successful
+        API->>EmailService: Send confirmation
+    end
+    
+    API-->>User: Order result
+```
+
+## Par (Parallel)
+
+Show concurrent operations:
+
+```mermaid
+sequenceDiagram
+    API->>Service: Process order
+    
+    par Send email
+        Service->>EmailService: Send confirmation
+    and Update inventory
+        Service->>InventoryService: Reduce stock
+    and Log event
+        Service->>LogService: Log order
+    end
+    
+    Service-->>API: Complete
+```
+
+## Loop
+
+```mermaid
+sequenceDiagram
+    Client->>Server: Request batch
+    
+    loop For each item
+        Server->>Database: Process item
+        Database-->>Server: Result
+    end
+    
+    Server-->>Client: All results
+```
+
+**Loop with condition:**
+```mermaid
+sequenceDiagram
+    loop Every 5 seconds
+        Monitor->>API: Health check
+        API-->>Monitor: Status
+    end
+```
+
+## Break (Early Exit)
+
+```mermaid
+sequenceDiagram
+    User->>API: Submit form
+    API->>Validator: Validate input
+    
+    break Input invalid
+        API-->>User: 400 Bad Request
+    end
+    
+    API->>Database: Save data
+    Database-->>API: Success
+    API-->>User: 200 OK
+```
+
+## Notes
+
+### Note over single participant
+```mermaid
+sequenceDiagram
+    User->>API: Request
+    Note over API: Validates JWT token
+    API-->>User: Response
+```
+
+### Note spanning participants
+```mermaid
+sequenceDiagram
+    Frontend->>API: Request
+    Note over Frontend,API: HTTPS encrypted
+    API-->>Frontend: Response
+```
+
+### Right/Left notes
+```mermaid
+sequenceDiagram
+    User->>System: Action
+    Note right of System: Logs to database
+    System-->>User: Response
+    Note left of User: Updates UI
+```
+
+## Sequence Numbers
+
+Automatically number messages:
+
+```mermaid
+sequenceDiagram
+    autonumber
+    
+    User->>Frontend: Login
+    Frontend->>API: Authenticate
+    API->>Database: Verify credentials
+    Database-->>API: User data
+    API-->>Frontend: JWT token
+    Frontend-->>User: Success
+```
+
+## Links and Tooltips
+
+Add clickable links:
+
+```mermaid
+sequenceDiagram
+    participant A as Service A
+    link A: Dashboard @ https://dashboard.example.com
+    link A: API Docs @ https://docs.example.com
+    
+    A->>B: Message
+```
+
+## Comprehensive Example: User Authentication Flow
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User
+    participant Frontend
+    participant AuthAPI
+    participant Database
+    participant Redis
+    participant EmailService
+    
+    User->>+Frontend: Enter credentials
+    Frontend->>+AuthAPI: POST /auth/login
+    
+    AuthAPI->>+Database: Query user by email
+    Database-->>-AuthAPI: User record
+    
+    alt User not found
+        AuthAPI-->>Frontend: 404 User not found
+        Frontend-->>User: Show error
+    else User found
+        AuthAPI->>AuthAPI: Verify password hash
+        
+        alt Invalid password
+            AuthAPI->>Database: Increment failed attempts
+            
+            opt Failed attempts > 5
+                AuthAPI->>Database: Lock account
+                AuthAPI->>EmailService: Send security alert
+            end
+            
+            AuthAPI-->>Frontend: 401 Invalid credentials
+            Frontend-->>User: Show error
+        else Valid password
+            AuthAPI->>AuthAPI: Generate JWT token
+            AuthAPI->>+Redis: Store session
+            Redis-->>-AuthAPI: Confirm
+            
+            par Update login metadata
+                AuthAPI->>Database: Update last_login
+            and Track analytics
+                AuthAPI->>Database: Log login event
+            end
+            
+            AuthAPI-->>-Frontend: 200 OK + JWT token
+            Frontend->>Frontend: Store token in localStorage
+            Frontend-->>-User: Redirect to dashboard
+            
+            opt First login
+                EmailService->>User: Welcome email
+            end
+        end
+    end
+```
+
+## API Request/Response Example
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant Client
+    participant Gateway
+    participant AuthService
+    participant UserService
+    participant Database
+    
+    Client->>+Gateway: GET /api/users/123
+    Note over Gateway: Rate limiting check
+    
+    Gateway->>+AuthService: Validate JWT
+    AuthService->>AuthService: Verify signature
+    
+    alt Token invalid or expired
+        AuthService-->>Gateway: 401 Unauthorized
+        Gateway-->>Client: 401 Unauthorized
+    else Token valid
+        AuthService-->>-Gateway: User context
+        
+        Gateway->>+UserService: GET /users/123
+        UserService->>+Database: SELECT * FROM users WHERE id=123
+        Database-->>-UserService: User record
+        
+        alt User not found
+            UserService-->>Gateway: 404 Not Found
+            Gateway-->>Client: 404 Not Found
+        else User found
+            UserService-->>-Gateway: 200 OK + User data
+            Gateway-->>-Client: 200 OK + User data
+        end
+    end
+```
+
+## Microservices Communication
+
+```mermaid
+sequenceDiagram
+    actor User
+    participant Gateway
+    participant OrderService
+    participant PaymentService
+    participant InventoryService
+    participant NotificationService
+    participant MessageQueue
+    
+    User->>+Gateway: POST /orders
+    Gateway->>+OrderService: Create order
+    
+    OrderService->>+InventoryService: Check stock
+    InventoryService-->>-OrderService: Stock available
+    
+    break Insufficient stock
+        OrderService-->>Gateway: 400 Out of stock
+        Gateway-->>User: Error message
+    end
+    
+    OrderService->>OrderService: Reserve order
+    OrderService->>+PaymentService: Charge customer
+    
+    alt Payment successful
+        PaymentService-->>-OrderService: Payment confirmed
+        OrderService->>MessageQueue: Publish OrderConfirmed event
+        
+        par Async processing
+            MessageQueue->>InventoryService: Reduce stock
+        and
+            MessageQueue->>NotificationService: Send confirmation
+            NotificationService->>User: Email confirmation
+        end
+        
+        OrderService-->>-Gateway: 201 Created
+        Gateway-->>User: Order confirmed
+    else Payment failed
+        PaymentService-->>OrderService: Payment declined
+        OrderService->>OrderService: Release reservation
+        OrderService-->>Gateway: 402 Payment Required
+        Gateway-->>User: Payment failed
+    end
+```
+
+## Best Practices
+
+1. **Order participants logically** - Typically: User → Frontend → Backend → Database
+2. **Use activations** - Shows when components are actively processing
+3. **Group related logic** - Use alt/opt/par to organize conditional flows
+4. **Add descriptive notes** - Explain complex logic or important details
+5. **Keep diagrams focused** - One scenario per diagram
+6. **Number messages** - Use autonumber for complex flows
+7. **Show error paths** - Document failure scenarios with alt/else
+8. **Indicate async operations** - Use open arrows for fire-and-forget messages
+
+## Common Use Cases
+
+### Authentication
+- Login flows
+- OAuth/SSO flows
+- Token refresh
+- Password reset
+
+### API Operations
+- CRUD operations
+- Search and filtering
+- Batch processing
+- Webhook handling
+
+### System Integration
+- Microservice communication
+- Third-party API calls
+- Message queue processing
+- Event-driven architecture
+
+### Business Processes
+- Order fulfillment
+- Payment processing
+- Approval workflows
+- Notification chains

package/bin/cli.js

@@ -17,7 +17,7 @@ const program = new Command();
 program
   .name('md')
   .description('Manager for co-located specifications for Mermaid Diagram Driven Development (MDDD)')
-  .version('4.2.1');
+  .version('4.2.3');
 
 // ==========================================
 // COMMAND: md init

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mddd-cli",
-  "version": "4.2.1",
+  "version": "4.2.3",
   "description": "Official CLI for modular, co-located, and versioned Mermaid Diagram Driven Development (MDDD).",
   "type": "module",
   "exports": "./bin/cli.js",
@@ -9,7 +9,8 @@
   },
   "files": [
     "src",
-    "system_prompt.md"
+    "system_prompt.md",
+    ".agents/skills"
   ],
   "engines": {
     "node": ">=18.0.0"
@@ -36,7 +37,7 @@
   },
   "homepage": "https://github.com/JulioCRFilho/mermaid-diagram-driven-development#readme",
   "dependencies": {
-    "@mermaid-js/mermaid-cli": "github:mermaid-js/mermaid-cli",
+    "@mermaid-js/mermaid-cli": "^11.4.2",
     "commander": "^12.0.0",
     "picocolors": "^1.0.0"
   }

package/readme.md

@@ -216,12 +216,12 @@ Visual specifications are not centralized in distant folders. They live in the *
 ```
 src/
 └── home/
-    ├── home.spec.md          # 🌎 Global module map (stateDiagram-v2 connecting nodes)
+    ├── home.spec.md          # 🌎 Global module map
     ├── guest/
-    │   ├── guest.spec.md     # 🔬 Screen flow (graph LR) + Decision Matrix
+    │   ├── guest.spec.md     # 🔬 Screen flow with Decision Matrix
     │   └── guest_page.dart   # 💻 Production code generated by AI
     └── consumer/
-        └── consumer.spec.md  # 🔬 Screen flow (graph LR) + Decision Matrix
+        └── consumer.spec.md  # 🔬 Screen flow with Decision Matrix
 
 ```
 
@@ -476,12 +476,12 @@ As especificações visuais não ficam centralizadas em pastas distantes. Elas v
 ```
 src/
 └── home/
-    ├── home.spec.md          # 🌎 Mapa global do módulo (stateDiagram-v2 conectando nós)
+    ├── home.spec.md          # 🌎 Mapa global do módulo
     ├── guest/
-    │   ├── guest.spec.md     # 🔬 Fluxo de tela (graph LR) + Matriz de Decisão
+    │   ├── guest.spec.md     # 🔬 Fluxo de tela com Matriz de Decisão
     │   └── guest_page.dart   # 💻 Código produtivo gerado pela IA
     └── consumer/
-        └── consumer.spec.md  # 🔬 Fluxo de tela (graph LR) + Matriz de Decisão
+        └── consumer.spec.md  # 🔬 Fluxo de tela com Matriz de Decisão
 
 ```
 

package/src/commands/init.js

@@ -26,13 +26,14 @@ function readSystemPrompt() {
 export async function execute(initService) {
   const systemPrompt = readSystemPrompt();
 
-  // Descobre o caminho absoluto real da pasta interna de templates de skills da CLI
+  // 1. Descobre o caminho absoluto real da pasta oculta interna do pacote da CLI
+  // Subindo de: src/commands/ -> src/ -> raiz do pacote CLI -> .agents/skills
   const currentFile = fileURLToPath(import.meta.url);
-  const cliSkillsSourceDir = path.resolve(path.dirname(currentFile), '..', 'skills');
+  const cliSkillsSourceDir = path.resolve(path.dirname(currentFile), '..', '..', '.agents', 'skills');
 
   await initService.createSystemPrompt(systemPrompt);
   
-  // Passa o caminho da pasta de origem em vez do mapa de strings antigas
+  // 2. Passa o caminho da pasta oculta de origem para o serviço clonar recursivamente
   await initService.createSkills(cliSkillsSourceDir, (msg) => console.log(msg));
   
   await initService.createGitHubWorkflow(GITHUB_WORKFLOW_CONTENT, (msg) => console.log(msg));

package/src/templates/spec-template.md

@@ -1,8 +1,3 @@
-%% @spec-version 1.0.0
-%% @domain {{domain_name}}
-%% @feature {{feature_name}}
-%% @author {{author_name}}
-
 # {{Feature Title}} — Specification
 
 **SPEC_VERSION:** v1.0.0 — draft
@@ -28,12 +23,9 @@ Describe **what** this spec governs and **why** it exists.
 
 ## 2. Behavioral Flow (Mermaid)
 
-> Pick the diagram type that best fits the topology:
-> `stateDiagram-v2` for lifecycles, `graph TD/LR` for procedural flows,
-> `sequenceDiagram` for multi-actor protocols, `flowchart` for branching logic.
+> Pick the diagram type that best fits the topology using mermaid-diagrams skill.
 
 ```mermaid
-%% @spec-version 1.0.0
 stateDiagram-v2
     [*] --> Idle: initial entry point
 
@@ -104,15 +96,7 @@ When a `HaltWithConflict` is triggered, document the resolution path here:
 
 ---
 
-## 6. Change History
-
-| Version | Date | Author | Change Description | Change Type |
-| :---: | :--- | :--- | :--- | :---: |
-| 1.0.0 | {{YYYY-MM-DD}} | {{author_name}} | Initial spec creation via `md-new` | MAJOR |
-
----
-
-## 7. Audit History
+## 6. Audit History
 
 <details>
 <summary>Click to expand</summary>

package/system_prompt.md

@@ -88,7 +88,7 @@ Brief description of the purpose and scope of this specification.
 
 src/
 └── [domain_name]/
-    ├── [domain_name].spec.md                   # 🌎 Macro Module Domain (stateDiagram-v2)
+    ├── [domain_name].spec.md                   # 🌎 Macro Module Domain
     ├── [feature_name]/
     │   ├── [feature_name].spec.md              # 🔬 Micro Flow Contract + Decision Matrix
     │   └── [feature_name].[extension]          # 💻 Target Production Code File (Any Extension)
@@ -218,7 +218,7 @@ The UNIVERSAL RULE is now integrated into the main processing diagram at the top
 
 **Before ANY action, the system MUST verify that a `.spec.md` file exists for the target domain/feature.** If no spec exists, only `md-new` and `md-audit` skills are allowed to proceed (to create or propose a spec). All other skills (`md-impl`, `md-edit`, etc.) are DENIED without an existing specification.
 
-Diagrams: Always use mmdc -i <path/to/diagram.md> --checkSyntax to validate diagram syntax (Mandatory)
+Diagrams: Always use "npx md validate <path/to/diagram.md>" to validate diagram syntax (Mandatory)
 
 ```mermaid
 %% @spec-version v2.0.0