@caddis/cli 0.0.0 → 0.2.0

package/bundles/antigravity-plugin/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/bundles/antigravity-plugin/skills/mermaid-diagrams/references/troubleshooting.md

@@ -0,0 +1,335 @@
+# Mermaid Troubleshooting Guide
+
+Common issues and solutions when working with Mermaid diagrams.
+
+## Diagram Won't Render
+
+### Issue: Blank output or error message
+
+**Symptoms:**
+- GitHub shows blank space where diagram should be
+- Mermaid Live shows "Syntax Error"
+- VS Code preview doesn't display diagram
+
+**Solutions:**
+
+1. **Check diagram type declaration:**
+   ```mermaid
+   ❌ classdiagram          # Wrong - typo
+   ❌ class-diagram         # Wrong - hyphen
+   ✅ classDiagram          # Correct
+   ```
+
+2. **Verify syntax at mermaid.live:**
+   - Copy your diagram code
+   - Paste at https://mermaid.live
+   - Check error messages in the editor
+
+3. **Check for special characters:**
+   ```mermaid
+   ❌ class User {name}     # Braces break syntax
+   ✅ class User {+name}    # Add visibility modifier
+   
+   ❌ A[Order {id}]         # Braces in label
+   ✅ A["Order {id}"]       # Quote the label
+   ```
+
+4. **Ensure proper indentation (especially in YAML/Markdown):**
+   ````markdown
+   ❌ Wrong:
+   ```mermaid
+   classDiagram
+   class User
+   ```
+   
+   ✅ Correct:
+   ```mermaid
+   classDiagram
+       class User
+   ```
+   ````
+
+## Arrows Not Connecting
+
+### Issue: Arrows don't connect to nodes
+
+**Symptoms:**
+- Arrow appears but doesn't touch nodes
+- Error: "Node not found"
+- Disconnected elements
+
+**Solutions:**
+
+1. **Match node IDs exactly (case-sensitive):**
+   ```mermaid
+   ❌ flowchart TD
+       Start --> process    # 'process' doesn't exist
+       Process[Do work]     # 'Process' defined (capital P)
+   
+   ✅ flowchart TD
+       Start --> Process
+       Process[Do work]
+   ```
+
+2. **Define nodes before connecting:**
+   ```mermaid
+   ❌ sequenceDiagram
+       User->>API           # API not defined
+   
+   ✅ sequenceDiagram
+       participant User
+       participant API
+       User->>API
+   ```
+
+3. **Use correct arrow syntax for diagram type:**
+   ```mermaid
+   # Flowchart
+   A --> B              # Standard connection
+   
+   # Sequence diagram
+   A->>B                # Sync message
+   A-->>B               # Response
+   
+   # Class diagram
+   A --> B              # Association
+   A --|> B             # Inheritance
+   A --* B              # Composition
+   ```
+
+## Layout Issues
+
+### Issue: Diagram layout looks wrong or crowded
+
+**Solutions:**
+
+1. **Try different direction:**
+   ```mermaid
+   flowchart TD    # Top to bottom (default)
+   flowchart LR    # Left to right
+   flowchart RL    # Right to left
+   flowchart BT    # Bottom to top
+   ```
+
+2. **Use subgraphs to group elements:**
+   ```mermaid
+   flowchart TD
+       subgraph Frontend
+           A[React App]
+           B[Redux Store]
+       end
+       
+       subgraph Backend
+           C[API Server]
+           D[Database]
+       end
+       
+       A --> C
+       C --> D
+   ```
+
+3. **Split complex diagrams:**
+   ```mermaid
+   # Instead of one massive diagram
+   # Create multiple focused diagrams:
+   # - diagram-overview.mmd
+   # - diagram-auth-flow.mmd
+   # - diagram-payment-flow.mmd
+   ```
+
+4. **Add invisible links to force layout:**
+   ```mermaid
+   flowchart LR
+       A --> B
+       B --> C
+       A ~~~ D    # Invisible link to align D with A
+   ```
+
+## Syntax Errors
+
+### Issue: Specific syntax not working
+
+**Common mistakes:**
+
+1. **Missing spaces around arrows:**
+   ```mermaid
+   ❌ A-->B             # Works but harder to read
+   ✅ A --> B           # Better
+   ```
+
+2. **Wrong relationship syntax (class diagrams):**
+   ```mermaid
+   ❌ User -> Order     # Wrong syntax
+   ✅ User --> Order    # Association
+   ✅ User --|> Order   # Inheritance
+   ```
+
+3. **Incorrect cardinality (ERD):**
+   ```mermaid
+   ❌ USER 1--* ORDER   # Wrong
+   ✅ USER ||--o{ ORDER # One to many
+   ```
+
+4. **Missing participant declaration (sequence):**
+   ```mermaid
+   ❌ sequenceDiagram
+       User->>API       # Implicit participant (works but not best practice)
+   
+   ✅ sequenceDiagram
+       participant User
+       participant API
+       User->>API
+   ```
+
+## Rendering Performance
+
+### Issue: Diagram is slow to render or times out
+
+**Solutions:**
+
+1. **Reduce complexity:**
+   - Limit to 15-20 nodes per diagram
+   - Split into multiple diagrams
+   - Remove unnecessary details
+
+2. **Avoid deep nesting:**
+   ```mermaid
+   ❌ flowchart TD
+       A --> B
+           B --> C
+               C --> D
+                   D --> E
+                       # Too deep!
+   
+   ✅ flowchart TD
+       A --> B --> C
+       C --> D --> E
+   ```
+
+3. **Use ELK layout for complex diagrams:**
+   ```mermaid
+   %%{init: {"flowchart": {"defaultRenderer": "elk"}} }%%
+   flowchart TD
+       # Complex diagram
+   ```
+
+## Labels and Text Issues
+
+### Issue: Text not displaying correctly
+
+**Solutions:**
+
+1. **Quote labels with special characters:**
+   ```mermaid
+   ❌ A[User: Admin]        # Colon breaks it
+   ✅ A["User: Admin"]      # Quote it
+   
+   ❌ B[Price: $100]        # Dollar sign breaks it
+   ✅ B["Price: $100"]      # Quote it
+   ```
+
+2. **Use HTML entities for special characters:**
+   ```mermaid
+   A["Price: #36;100"]      # $ = #36;
+   B["Name: #60;User#62;"]  # < and > = #60; #62;
+   ```
+
+3. **Use `<br>` for line breaks:**
+   ```mermaid
+   A["First Line<br>Second Line<br>Third Line"]
+   ```
+
+4. **Escape backticks in code labels:**
+   ```mermaid
+   A["`function() { return 'code'; }`"]
+   ```
+
+## Export Issues
+
+### Issue: Exported diagram looks different from preview
+
+**Solutions:**
+
+1. **Use Mermaid Live for consistent exports:**
+   - Go to https://mermaid.live
+   - Paste your diagram
+   - Export as PNG or SVG
+
+2. **Use Mermaid CLI for batch exports:**
+   ```bash
+   npm install -g @mermaid-js/mermaid-cli
+   mmdc -i diagram.mmd -o diagram.png
+   ```
+
+3. **Specify theme in diagram:**
+   ```mermaid
+   %%{init: {'theme':'base'}}%%
+   flowchart TD
+       A --> B
+   ```
+
+## GitHub/GitLab Rendering
+
+### Issue: Diagram doesn't render on GitHub
+
+**Solutions:**
+
+1. **Ensure proper code fence:**
+   ````markdown
+   ❌ '''mermaid          # Wrong quote type
+   
+   ✅ ```mermaid          # Correct
+   classDiagram
+   ```
+   ````
+
+2. **Check file extension:**
+   - `.md` or `.markdown` files render automatically
+   - `.mmd` files need to be viewed raw
+
+3. **Verify syntax in Mermaid Live first:**
+   - GitHub's Mermaid version may lag behind
+   - Test at https://mermaid.live
+
+## Version Compatibility
+
+### Issue: Diagram works locally but not in production
+
+**Solutions:**
+
+1. **Check Mermaid version:**
+   - Different platforms support different versions
+   - GitHub: ~v9.x-10.x
+   - GitLab: ~v9.x
+   - Notion: ~v8.x
+
+2. **Use stable syntax:**
+   - Avoid newest features if targeting older platforms
+   - Stick to core syntax that works everywhere
+
+3. **Test on target platform:**
+   - Create test file in actual environment
+   - Validate before committing
+
+## Quick Debugging Checklist
+
+When a diagram breaks, check:
+
+- [ ] Diagram type spelled correctly (case-sensitive)
+- [ ] All node IDs match exactly (case-sensitive)
+- [ ] Arrows use correct syntax for diagram type
+- [ ] Special characters are quoted or escaped
+- [ ] No typos in relationship symbols (-->, --|>, etc.)
+- [ ] Syntax validates at https://mermaid.live
+- [ ] Code fence uses triple backticks: ```mermaid
+- [ ] Indentation is consistent
+- [ ] No unescaped braces {} in labels
+- [ ] All participants declared (sequence diagrams)
+
+## Still Stuck?
+
+1. **Copy error-free example** from this skill's references
+2. **Modify incrementally** to match your needs
+3. **Test after each change** to isolate the problem
+4. **Check official docs:** https://mermaid.js.org
+5. **Search GitHub issues:** https://github.com/mermaid-js/mermaid/issues