create-yss-spec 1.0.0

package/template/.trae/skills/excalidraw-diagram-generator/scripts/add-icon-to-diagram.py

@@ -0,0 +1,407 @@
+#!/usr/bin/env python3
+"""
+Add icons from Excalidraw libraries to diagrams.
+
+This script reads an icon JSON file from an Excalidraw library, transforms its coordinates
+to a target position, generates unique IDs, and adds it to an existing Excalidraw diagram.
+Works with any Excalidraw library (AWS, GCP, Azure, Kubernetes, etc.).
+
+Usage:
+    python add-icon-to-diagram.py <diagram_path> <icon_name> <x> <y> [OPTIONS]
+
+Options:
+    --library-path PATH    Path to the icon library directory (default: aws-architecture-icons)
+    --label TEXT           Add a text label below the icon
+    --use-edit-suffix      Edit via .excalidraw.edit to avoid editor overwrite issues (enabled by default; use --no-use-edit-suffix to disable)
+
+Examples:
+    python add-icon-to-diagram.py diagram.excalidraw EC2 500 300
+    python add-icon-to-diagram.py diagram.excalidraw EC2 500 300 --label "Web Server"
+    python add-icon-to-diagram.py diagram.excalidraw VPC 200 150 --library-path libraries/gcp-icons
+    python add-icon-to-diagram.py diagram.excalidraw EC2 500 300 --use-edit-suffix
+"""
+
+import json
+import sys
+import uuid
+from pathlib import Path
+from typing import Dict, List, Any, Tuple
+
+
+def generate_unique_id() -> str:
+    """Generate a unique ID for Excalidraw elements."""
+    return str(uuid.uuid4()).replace('-', '')[:16]
+
+
+def calculate_bounding_box(elements: List[Dict[str, Any]]) -> Tuple[float, float, float, float]:
+    """Calculate the bounding box (min_x, min_y, max_x, max_y) of icon elements."""
+    if not elements:
+        return (0, 0, 0, 0)
+    
+    min_x = float('inf')
+    min_y = float('inf')
+    max_x = float('-inf')
+    max_y = float('-inf')
+    
+    for element in elements:
+        if 'x' in element and 'y' in element:
+            x = element['x']
+            y = element['y']
+            width = element.get('width', 0)
+            height = element.get('height', 0)
+            
+            min_x = min(min_x, x)
+            min_y = min(min_y, y)
+            max_x = max(max_x, x + width)
+            max_y = max(max_y, y + height)
+    
+    return (min_x, min_y, max_x, max_y)
+
+
+def transform_icon_elements(
+    elements: List[Dict[str, Any]], 
+    target_x: float, 
+    target_y: float
+) -> List[Dict[str, Any]]:
+    """
+    Transform icon elements to target coordinates with unique IDs.
+    
+    Args:
+        elements: Icon elements from JSON file
+        target_x: Target X coordinate (top-left position)
+        target_y: Target Y coordinate (top-left position)
+    
+    Returns:
+        Transformed elements with new coordinates and IDs
+    """
+    if not elements:
+        return []
+    
+    # Calculate bounding box
+    min_x, min_y, max_x, max_y = calculate_bounding_box(elements)
+    
+    # Calculate offset
+    offset_x = target_x - min_x
+    offset_y = target_y - min_y
+    
+    # Create ID mapping: old_id -> new_id
+    id_mapping = {}
+    for element in elements:
+        if 'id' in element:
+            old_id = element['id']
+            id_mapping[old_id] = generate_unique_id()
+    
+    # Create group ID mapping
+    group_id_mapping = {}
+    for element in elements:
+        if 'groupIds' in element:
+            for old_group_id in element['groupIds']:
+                if old_group_id not in group_id_mapping:
+                    group_id_mapping[old_group_id] = generate_unique_id()
+    
+    # Transform elements
+    transformed = []
+    for element in elements:
+        new_element = element.copy()
+        
+        # Update coordinates
+        if 'x' in new_element:
+            new_element['x'] = new_element['x'] + offset_x
+        if 'y' in new_element:
+            new_element['y'] = new_element['y'] + offset_y
+        
+        # Update ID
+        if 'id' in new_element:
+            new_element['id'] = id_mapping[new_element['id']]
+        
+        # Update group IDs
+        if 'groupIds' in new_element:
+            new_element['groupIds'] = [
+                group_id_mapping[gid] for gid in new_element['groupIds']
+            ]
+        
+        # Update binding references if they exist
+        if 'startBinding' in new_element and new_element['startBinding']:
+            if 'elementId' in new_element['startBinding']:
+                old_id = new_element['startBinding']['elementId']
+                if old_id in id_mapping:
+                    new_element['startBinding']['elementId'] = id_mapping[old_id]
+        
+        if 'endBinding' in new_element and new_element['endBinding']:
+            if 'elementId' in new_element['endBinding']:
+                old_id = new_element['endBinding']['elementId']
+                if old_id in id_mapping:
+                    new_element['endBinding']['elementId'] = id_mapping[old_id]
+        
+        # Update containerId if it exists
+        if 'containerId' in new_element and new_element['containerId']:
+            old_id = new_element['containerId']
+            if old_id in id_mapping:
+                new_element['containerId'] = id_mapping[old_id]
+        
+        # Update boundElements if they exist
+        if 'boundElements' in new_element and new_element['boundElements']:
+            new_bound_elements = []
+            for bound_elem in new_element['boundElements']:
+                if isinstance(bound_elem, dict) and 'id' in bound_elem:
+                    old_id = bound_elem['id']
+                    if old_id in id_mapping:
+                        bound_elem['id'] = id_mapping[old_id]
+                new_bound_elements.append(bound_elem)
+            new_element['boundElements'] = new_bound_elements
+        
+        transformed.append(new_element)
+    
+    return transformed
+
+
+def load_icon(icon_name: str, library_path: Path) -> List[Dict[str, Any]]:
+    """
+    Load icon elements from library.
+    
+    Args:
+        icon_name: Name of the icon (e.g., "EC2", "VPC")
+        library_path: Path to the icon library directory
+    
+    Returns:
+        List of icon elements
+    """
+    icon_file = library_path / "icons" / f"{icon_name}.json"
+    
+    if not icon_file.exists():
+        raise FileNotFoundError(f"Icon file not found: {icon_file}")
+    
+    with open(icon_file, 'r', encoding='utf-8') as f:
+        icon_data = json.load(f)
+    
+    return icon_data.get('elements', [])
+
+
+def prepare_edit_path(diagram_path: Path, use_edit_suffix: bool) -> tuple[Path, Path | None]:
+    """
+    Prepare a safe edit path to avoid editor overwrite issues.
+
+    Returns:
+        (work_path, final_path)
+        - work_path: file path to read/write during edit
+        - final_path: file path to rename back to (or None if not used)
+    """
+    if not use_edit_suffix:
+        return diagram_path, None
+
+    if diagram_path.suffix != ".excalidraw":
+        return diagram_path, None
+
+    edit_path = diagram_path.with_suffix(diagram_path.suffix + ".edit")
+
+    if diagram_path.exists():
+        if edit_path.exists():
+            raise FileExistsError(f"Edit file already exists: {edit_path}")
+        diagram_path.rename(edit_path)
+
+    return edit_path, diagram_path
+
+
+def finalize_edit_path(work_path: Path, final_path: Path | None) -> None:
+    """Finalize edit by renaming .edit back to .excalidraw if needed."""
+    if final_path is None:
+        return
+
+    if final_path.exists():
+        final_path.unlink()
+
+    work_path.rename(final_path)
+
+
+def create_text_label(text: str, x: float, y: float) -> Dict[str, Any]:
+    """
+    Create a text label element.
+    
+    Args:
+        text: Label text
+        x: X coordinate
+        y: Y coordinate
+    
+    Returns:
+        Text element dictionary
+    """
+    return {
+        "id": generate_unique_id(),
+        "type": "text",
+        "x": x,
+        "y": y,
+        "width": len(text) * 10,  # Approximate width
+        "height": 20,
+        "angle": 0,
+        "strokeColor": "#1e1e1e",
+        "backgroundColor": "transparent",
+        "fillStyle": "solid",
+        "strokeWidth": 2,
+        "strokeStyle": "solid",
+        "roughness": 1,
+        "opacity": 100,
+        "groupIds": [],
+        "frameId": None,
+        "index": "a0",
+        "roundness": None,
+        "seed": 1000000000 + hash(text) % 1000000000,
+        "version": 1,
+        "versionNonce": 2000000000 + hash(text) % 1000000000,
+        "isDeleted": False,
+        "boundElements": [],
+        "updated": 1738195200000,
+        "link": None,
+        "locked": False,
+        "text": text,
+        "fontSize": 16,
+        "fontFamily": 5,  # Excalifont
+        "textAlign": "center",
+        "verticalAlign": "top",
+        "containerId": None,
+        "originalText": text,
+        "autoResize": True,
+        "lineHeight": 1.25
+    }
+
+
+def add_icon_to_diagram(
+    diagram_path: Path,
+    icon_name: str,
+    x: float,
+    y: float,
+    library_path: Path,
+    label: str = None
+) -> None:
+    """
+    Add an icon to an Excalidraw diagram.
+    
+    Args:
+        diagram_path: Path to the Excalidraw diagram file
+        icon_name: Name of the icon to add
+        x: Target X coordinate
+        y: Target Y coordinate
+        library_path: Path to the icon library directory
+        label: Optional text label to add below the icon
+    """
+    # Load icon elements
+    print(f"Loading icon: {icon_name}")
+    icon_elements = load_icon(icon_name, library_path)
+    print(f"  Loaded {len(icon_elements)} elements")
+    
+    # Transform icon elements
+    print(f"Transforming to position ({x}, {y})")
+    transformed_elements = transform_icon_elements(icon_elements, x, y)
+    
+    # Calculate icon bounding box for label positioning
+    if label and transformed_elements:
+        min_x, min_y, max_x, max_y = calculate_bounding_box(transformed_elements)
+        icon_width = max_x - min_x
+        icon_height = max_y - min_y
+        
+        # Position label below icon, centered
+        label_x = min_x + (icon_width / 2) - (len(label) * 5)
+        label_y = max_y + 10
+        
+        label_element = create_text_label(label, label_x, label_y)
+        transformed_elements.append(label_element)
+        print(f"  Added label: '{label}'")
+    
+    # Load diagram
+    print(f"Loading diagram: {diagram_path}")
+    with open(diagram_path, 'r', encoding='utf-8') as f:
+        diagram = json.load(f)
+    
+    # Add transformed elements
+    if 'elements' not in diagram:
+        diagram['elements'] = []
+    
+    original_count = len(diagram['elements'])
+    diagram['elements'].extend(transformed_elements)
+    print(f"  Added {len(transformed_elements)} elements (total: {original_count} -> {len(diagram['elements'])})")
+    
+    # Save diagram
+    print(f"Saving diagram")
+    with open(diagram_path, 'w', encoding='utf-8') as f:
+        json.dump(diagram, f, indent=2, ensure_ascii=False)
+    
+    print(f"✓ Successfully added '{icon_name}' icon to diagram")
+
+
+def main():
+    """Main entry point."""
+    if hasattr(sys.stdout, "reconfigure"):
+        # Ensure consistent UTF-8 output on Windows consoles.
+        sys.stdout.reconfigure(encoding="utf-8")
+    if len(sys.argv) < 5:
+        print("Usage: python add-icon-to-diagram.py <diagram_path> <icon_name> <x> <y> [OPTIONS]")
+        print("\nOptions:")
+        print("  --library-path PATH    Path to icon library directory")
+        print("  --label TEXT           Add text label below icon")
+        print("  --use-edit-suffix      Edit via .excalidraw.edit to avoid editor overwrite issues (enabled by default; use --no-use-edit-suffix to disable)")
+        print("\nExamples:")
+        print("  python add-icon-to-diagram.py diagram.excalidraw EC2 500 300")
+        print("  python add-icon-to-diagram.py diagram.excalidraw EC2 500 300 --label 'Web Server'")
+        sys.exit(1)
+    
+    diagram_path = Path(sys.argv[1])
+    icon_name = sys.argv[2]
+    x = float(sys.argv[3])
+    y = float(sys.argv[4])
+    
+    # Default library path
+    script_dir = Path(__file__).parent
+    default_library_path = script_dir.parent / "libraries" / "aws-architecture-icons"
+    
+    # Parse optional arguments
+    library_path = default_library_path
+    label = None
+    # Default: use edit suffix to avoid editor overwrite issues
+    use_edit_suffix = True
+    
+    i = 5
+    while i < len(sys.argv):
+        if sys.argv[i] == '--library-path':
+            if i + 1 < len(sys.argv):
+                library_path = Path(sys.argv[i + 1])
+                i += 2
+            else:
+                print("Error: --library-path requires a path argument")
+                sys.exit(1)
+        elif sys.argv[i] == '--label':
+            if i + 1 < len(sys.argv):
+                label = sys.argv[i + 1]
+                i += 2
+            else:
+                print("Error: --label requires a text argument")
+                sys.exit(1)
+        elif sys.argv[i] == '--use-edit-suffix':
+            use_edit_suffix = True
+            i += 1
+        elif sys.argv[i] == '--no-use-edit-suffix':
+            use_edit_suffix = False
+            i += 1
+        else:
+            print(f"Error: Unknown option: {sys.argv[i]}")
+            sys.exit(1)
+    
+    # Validate inputs
+    if not diagram_path.exists():
+        print(f"Error: Diagram file not found: {diagram_path}")
+        sys.exit(1)
+    
+    if not library_path.exists():
+        print(f"Error: Library path not found: {library_path}")
+        sys.exit(1)
+    
+    try:
+        work_path, final_path = prepare_edit_path(diagram_path, use_edit_suffix)
+        add_icon_to_diagram(work_path, icon_name, x, y, library_path, label)
+        finalize_edit_path(work_path, final_path)
+    except Exception as e:
+        print(f"Error: {e}")
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()
+

package/template/.trae/skills/excalidraw-diagram-generator/scripts/split-excalidraw-library.py

@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+"""
+Excalidraw Library Splitter
+
+This script splits an Excalidraw library file (*.excalidrawlib) into individual
+icon JSON files and generates a reference.md file for easy lookup.
+
+The script expects the following structure:
+  skills/excalidraw-diagram-generator/libraries/{icon-set-name}/
+    {icon-set-name}.excalidrawlib  (place this file first)
+
+Usage:
+    python split-excalidraw-library.py <path-to-library-directory>
+
+Example:
+    python split-excalidraw-library.py skills/excalidraw-diagram-generator/libraries/aws-architecture-icons/
+"""
+
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+
+def sanitize_filename(name: str) -> str:
+    """
+    Sanitize icon name to create a valid filename.
+
+    Args:
+        name: Original icon name
+
+    Returns:
+        Sanitized filename safe for all platforms
+    """
+    # Replace spaces with hyphens
+    filename = name.replace(' ', '-')
+
+    # Remove or replace special characters
+    filename = re.sub(r'[^\w\-.]', '', filename)
+
+    # Remove multiple consecutive hyphens
+    filename = re.sub(r'-+', '-', filename)
+
+    # Remove leading/trailing hyphens
+    filename = filename.strip('-')
+
+    return filename
+
+
+def find_library_file(directory: Path) -> Path:
+    """
+    Find the .excalidrawlib file in the given directory.
+
+    Args:
+        directory: Directory to search
+
+    Returns:
+        Path to the library file
+
+    Raises:
+        SystemExit: If no library file or multiple library files found
+    """
+    library_files = list(directory.glob('*.excalidrawlib'))
+
+    if len(library_files) == 0:
+        print(f"Error: No .excalidrawlib file found in {directory}")
+        print(f"Please place a .excalidrawlib file in {directory} first.")
+        sys.exit(1)
+
+    if len(library_files) > 1:
+        print(f"Error: Multiple .excalidrawlib files found in {directory}")
+        print(f"Please keep only one library file in {directory}.")
+        sys.exit(1)
+
+    return library_files[0]
+
+
+def split_library(library_dir: str) -> None:
+    """
+    Split an Excalidraw library file into individual icon files.
+
+    Args:
+        library_dir: Path to the directory containing the .excalidrawlib file
+    """
+    library_dir = Path(library_dir)
+
+    if not library_dir.exists():
+        print(f"Error: Directory not found: {library_dir}")
+        sys.exit(1)
+
+    if not library_dir.is_dir():
+        print(f"Error: Path is not a directory: {library_dir}")
+        sys.exit(1)
+
+    # Find the library file
+    library_path = find_library_file(library_dir)
+    print(f"Found library: {library_path.name}")
+
+    # Load library file
+    print(f"Loading library data...")
+    with open(library_path, 'r', encoding='utf-8') as f:
+        library_data = json.load(f)
+
+    # Validate library structure
+    if 'libraryItems' not in library_data:
+        print("Error: Invalid library file format (missing 'libraryItems')")
+        sys.exit(1)
+
+    # Create icons directory
+    icons_dir = library_dir / 'icons'
+    icons_dir.mkdir(exist_ok=True)
+    print(f"Output directory: {library_dir}")
+
+    # Process each library item (icon)
+    library_items = library_data['libraryItems']
+    icon_list = []
+
+    print(f"Processing {len(library_items)} icons...")
+
+    for item in library_items:
+        # Get icon name
+        icon_name = item.get('name', 'Unnamed')
+
+        # Create sanitized filename
+        filename = sanitize_filename(icon_name) + '.json'
+
+        # Save icon data
+        icon_path = icons_dir / filename
+        with open(icon_path, 'w', encoding='utf-8') as f:
+            json.dump(item, f, ensure_ascii=False, indent=2)
+
+        # Add to reference list
+        icon_list.append({
+            'name': icon_name,
+            'filename': filename
+        })
+
+        print(f"  ✓ {icon_name} → {filename}")
+
+    # Sort icon list by name
+    icon_list.sort(key=lambda x: x['name'])
+
+    # Generate reference.md
+    library_name = library_path.stem
+    reference_path = library_dir / 'reference.md'
+    with open(reference_path, 'w', encoding='utf-8') as f:
+        f.write(f"# {library_name} Reference\n\n")
+        f.write(f"This directory contains {len(icon_list)} icons extracted from `{library_path.name}`.\n\n")
+        f.write("## Available Icons\n\n")
+        f.write("| Icon Name | Filename |\n")
+        f.write("|-----------|----------|\n")
+
+        for icon in icon_list:
+            f.write(f"| {icon['name']} | `icons/{icon['filename']}` |\n")
+
+        f.write("\n## Usage\n\n")
+        f.write("Each icon JSON file contains the complete `elements` array needed to render that icon in Excalidraw.\n")
+        f.write("You can copy the elements from these files into your Excalidraw diagrams.\n")
+
+    print(f"\n✅ Successfully split library into {len(icon_list)} icons")
+    print(f"📄 Reference file created: {reference_path}")
+    print(f"📁 Icons directory: {icons_dir}")
+
+
+def main():
+    """Main entry point."""
+    if hasattr(sys.stdout, "reconfigure"):
+        # Ensure consistent UTF-8 output on Windows consoles.
+        sys.stdout.reconfigure(encoding="utf-8")
+    if len(sys.argv) != 2:
+        print("Usage: python split-excalidraw-library.py <path-to-library-directory>")
+        print("\nExample:")
+        print("  python split-excalidraw-library.py skills/excalidraw-diagram-generator/libraries/aws-architecture-icons/")
+        print("\nNote: The directory should contain a .excalidrawlib file.")
+        sys.exit(1)
+
+    library_dir = sys.argv[1]
+    split_library(library_dir)
+
+
+if __name__ == '__main__':
+    main()