1#!/usr/bin/env python3
2"""
3Add arrows (connections) between elements in Excalidraw diagrams.
4 
5Usage:
6    python add-arrow.py <diagram_path> <from_x> <from_y> <to_x> <to_y> [OPTIONS]
7 
8Options:
9    --style {solid|dashed|dotted}    Arrow line style (default: solid)
10    --color HEX                      Arrow color (default: #1e1e1e)
11    --label TEXT                     Add text label on the arrow
12    --use-edit-suffix                Edit via .excalidraw.edit to avoid editor overwrite issues (enabled by default; use --no-use-edit-suffix to disable)
13 
14Examples:
15    python add-arrow.py diagram.excalidraw 300 200 500 300
16    python add-arrow.py diagram.excalidraw 300 200 500 300 --label "HTTP"
17    python add-arrow.py diagram.excalidraw 300 200 500 300 --style dashed --color "#7950f2"
18    python add-arrow.py diagram.excalidraw 300 200 500 300 --use-edit-suffix
19"""
20 
21import json
22import sys
23import uuid
24from pathlib import Path
25from typing import Dict, Any
26 
27 
28def generate_unique_id() -> str:
29    """Generate a unique ID for Excalidraw elements."""
30    return str(uuid.uuid4()).replace('-', '')[:16]
31 
32 
33def prepare_edit_path(diagram_path: Path, use_edit_suffix: bool) -> tuple[Path, Path | None]:
34    """
35    Prepare a safe edit path to avoid editor overwrite issues.
36 
37    Returns:
38        (work_path, final_path)
39        - work_path: file path to read/write during edit
40        - final_path: file path to rename back to (or None if not used)
41    """
42    if not use_edit_suffix:
43        return diagram_path, None
44 
45    if diagram_path.suffix != ".excalidraw":
46        return diagram_path, None
47 
48    edit_path = diagram_path.with_suffix(diagram_path.suffix + ".edit")
49 
50    if diagram_path.exists():
51        if edit_path.exists():
52            raise FileExistsError(f"Edit file already exists: {edit_path}")
53        diagram_path.rename(edit_path)
54 
55    return edit_path, diagram_path
56 
57 
58def finalize_edit_path(work_path: Path, final_path: Path | None) -> None:
59    """Finalize edit by renaming .edit back to .excalidraw if needed."""
60    if final_path is None:
61        return
62 
63    if final_path.exists():
64        final_path.unlink()
65 
66    work_path.rename(final_path)
67 
68 
69def create_arrow(
70    from_x: float,
71    from_y: float,
72    to_x: float,
73    to_y: float,
74    style: str = "solid",
75    color: str = "#1e1e1e",
76    label: str = None
77) -> list:
78    """
79    Create an arrow element.
80    
81    Args:
82        from_x: Starting X coordinate
83        from_y: Starting Y coordinate
84        to_x: Ending X coordinate
85        to_y: Ending Y coordinate
86        style: Line style (solid, dashed, dotted)
87        color: Arrow color
88        label: Optional text label on the arrow
89    
90    Returns:
91        List of elements (arrow and optional label)
92    """
93    elements = []
94    
95    # Arrow element
96    arrow = {
97        "id": generate_unique_id(),
98        "type": "arrow",
99        "x": from_x,
100        "y": from_y,
101        "width": to_x - from_x,
102        "height": to_y - from_y,
103        "angle": 0,
104        "strokeColor": color,
105        "backgroundColor": "transparent",
106        "fillStyle": "solid",
107        "strokeWidth": 2,
108        "strokeStyle": style,
109        "roughness": 1,
110        "opacity": 100,
111        "groupIds": [],
112        "frameId": None,
113        "index": "a0",
114        "roundness": {
115            "type": 2
116        },
117        "seed": 1000000000 + hash(f"{from_x}{from_y}{to_x}{to_y}") % 1000000000,
118        "version": 1,
119        "versionNonce": 2000000000 + hash(f"{from_x}{from_y}{to_x}{to_y}") % 1000000000,
120        "isDeleted": False,
121        "boundElements": [],
122        "updated": 1738195200000,
123        "link": None,
124        "locked": False,
125        "points": [
126            [0, 0],
127            [to_x - from_x, to_y - from_y]
128        ],
129        "startBinding": None,
130        "endBinding": None,
131        "startArrowhead": None,
132        "endArrowhead": "arrow",
133        "lastCommittedPoint": None
134    }
135    elements.append(arrow)
136    
137    # Optional label
138    if label:
139        mid_x = (from_x + to_x) / 2 - (len(label) * 5)
140        mid_y = (from_y + to_y) / 2 - 10
141        
142        label_element = {
143            "id": generate_unique_id(),
144            "type": "text",
145            "x": mid_x,
146            "y": mid_y,
147            "width": len(label) * 10,
148            "height": 20,
149            "angle": 0,
150            "strokeColor": color,
151            "backgroundColor": "transparent",
152            "fillStyle": "solid",
153            "strokeWidth": 2,
154            "strokeStyle": "solid",
155            "roughness": 1,
156            "opacity": 100,
157            "groupIds": [],
158            "frameId": None,
159            "index": "a0",
160            "roundness": None,
161            "seed": 1000000000 + hash(label) % 1000000000,
162            "version": 1,
163            "versionNonce": 2000000000 + hash(label) % 1000000000,
164            "isDeleted": False,
165            "boundElements": [],
166            "updated": 1738195200000,
167            "link": None,
168            "locked": False,
169            "text": label,
170            "fontSize": 14,
171            "fontFamily": 5,
172            "textAlign": "center",
173            "verticalAlign": "top",
174            "containerId": None,
175            "originalText": label,
176            "autoResize": True,
177            "lineHeight": 1.25
178        }
179        elements.append(label_element)
180    
181    return elements
182 
183 
184def add_arrow_to_diagram(
185    diagram_path: Path,
186    from_x: float,
187    from_y: float,
188    to_x: float,
189    to_y: float,
190    style: str = "solid",
191    color: str = "#1e1e1e",
192    label: str = None
193) -> None:
194    """
195    Add an arrow to an Excalidraw diagram.
196    
197    Args:
198        diagram_path: Path to the Excalidraw diagram file
199        from_x: Starting X coordinate
200        from_y: Starting Y coordinate
201        to_x: Ending X coordinate
202        to_y: Ending Y coordinate
203        style: Line style (solid, dashed, dotted)
204        color: Arrow color
205        label: Optional text label
206    """
207    print(f"Creating arrow from ({from_x}, {from_y}) to ({to_x}, {to_y})")
208    arrow_elements = create_arrow(from_x, from_y, to_x, to_y, style, color, label)
209    
210    if label:
211        print(f"  With label: '{label}'")
212    
213    # Load diagram
214    print(f"Loading diagram: {diagram_path}")
215    with open(diagram_path, 'r', encoding='utf-8') as f:
216        diagram = json.load(f)
217    
218    # Add arrow elements
219    if 'elements' not in diagram:
220        diagram['elements'] = []
221    
222    original_count = len(diagram['elements'])
223    diagram['elements'].extend(arrow_elements)
224    print(f"  Added {len(arrow_elements)} elements (total: {original_count} -> {len(diagram['elements'])})")
225    
226    # Save diagram
227    print(f"Saving diagram")
228    with open(diagram_path, 'w', encoding='utf-8') as f:
229        json.dump(diagram, f, indent=2, ensure_ascii=False)
230    
231    print(f"✓ Successfully added arrow to diagram")
232 
233 
234def main():
235    """Main entry point."""
236    if len(sys.argv) < 6:
237        print("Usage: python add-arrow.py <diagram_path> <from_x> <from_y> <to_x> <to_y> [OPTIONS]")
238        print("\nOptions:")
239        print("  --style {solid|dashed|dotted}    Line style (default: solid)")
240        print("  --color HEX                      Color (default: #1e1e1e)")
241        print("  --label TEXT                     Text label on arrow")
242        print("  --use-edit-suffix                Edit via .excalidraw.edit to avoid editor overwrite issues (enabled by default; use --no-use-edit-suffix to disable)")
243        print("\nExamples:")
244        print("  python add-arrow.py diagram.excalidraw 300 200 500 300")
245        print("  python add-arrow.py diagram.excalidraw 300 200 500 300 --label 'HTTP'")
246        sys.exit(1)
247    
248    diagram_path = Path(sys.argv[1])
249    from_x = float(sys.argv[2])
250    from_y = float(sys.argv[3])
251    to_x = float(sys.argv[4])
252    to_y = float(sys.argv[5])
253    
254    # Parse optional arguments
255    style = "solid"
256    color = "#1e1e1e"
257    label = None
258    # Default: use edit suffix to avoid editor overwrite issues
259    use_edit_suffix = True
260    
261    i = 6
262    while i < len(sys.argv):
263        if sys.argv[i] == '--style':
264            if i + 1 < len(sys.argv):
265                style = sys.argv[i + 1]
266                if style not in ['solid', 'dashed', 'dotted']:
267                    print(f"Error: Invalid style '{style}'. Must be: solid, dashed, or dotted")
268                    sys.exit(1)
269                i += 2
270            else:
271                print("Error: --style requires an argument")
272                sys.exit(1)
273        elif sys.argv[i] == '--color':
274            if i + 1 < len(sys.argv):
275                color = sys.argv[i + 1]
276                i += 2
277            else:
278                print("Error: --color requires an argument")
279                sys.exit(1)
280        elif sys.argv[i] == '--label':
281            if i + 1 < len(sys.argv):
282                label = sys.argv[i + 1]
283                i += 2
284            else:
285                print("Error: --label requires a text argument")
286                sys.exit(1)
287        elif sys.argv[i] == '--use-edit-suffix':
288            use_edit_suffix = True
289            i += 1
290        elif sys.argv[i] == '--no-use-edit-suffix':
291            use_edit_suffix = False
292            i += 1
293        else:
294            print(f"Error: Unknown option: {sys.argv[i]}")
295            sys.exit(1)
296    
297    # Validate inputs
298    if not diagram_path.exists():
299        print(f"Error: Diagram file not found: {diagram_path}")
300        sys.exit(1)
301    
302    try:
303        work_path, final_path = prepare_edit_path(diagram_path, use_edit_suffix)
304        add_arrow_to_diagram(work_path, from_x, from_y, to_x, to_y, style, color, label)
305        finalize_edit_path(work_path, final_path)
306    except Exception as e:
307        print(f"Error: {e}")
308        sys.exit(1)
309 
310 
311if __name__ == '__main__':
312    main()
313