@caddis/cli 0.1.0 → 0.2.0

package/bundles/antigravity-plugin-extras/skills/excalidraw/references/excalidraw-schema.md

@@ -0,0 +1,356 @@
+# Excalidraw JSON Schema Reference
+
+This document describes the structure of Excalidraw `.excalidraw` files for diagram generation.
+
+## Top-Level Structure
+
+```typescript
+interface ExcalidrawFile {
+  type: "excalidraw";
+  version: number;           // Always 2
+  source: string;            // "https://excalidraw.com"
+  elements: ExcalidrawElement[];
+  appState: AppState;
+  files: Record<string, any>; // Usually empty {}
+}
+```
+
+## AppState
+
+```typescript
+interface AppState {
+  viewBackgroundColor: string; // Hex color, e.g., "#ffffff"
+  gridSize: number;            // Typically 20
+}
+```
+
+## ExcalidrawElement Base Properties
+
+All elements share these common properties:
+
+```typescript
+interface BaseElement {
+  id: string;                  // Unique identifier
+  type: ElementType;           // See Element Types below
+  x: number;                   // X coordinate (pixels from top-left)
+  y: number;                   // Y coordinate (pixels from top-left)
+  width: number;               // Width in pixels
+  height: number;              // Height in pixels
+  angle: number;               // Rotation angle in radians (usually 0)
+  strokeColor: string;         // Hex color, e.g., "#1e1e1e"
+  backgroundColor: string;     // Hex color or "transparent"
+  fillStyle: "solid" | "hachure" | "cross-hatch";
+  strokeWidth: number;         // 1-4 typically
+  strokeStyle: "solid" | "dashed" | "dotted";
+  roughness: number;           // 0-2, controls hand-drawn effect (1 = default)
+  opacity: number;             // 0-100
+  groupIds: string[];          // IDs of groups this element belongs to
+  frameId: null;               // Usually null
+  index: string;               // Stacking order identifier
+  roundness: Roundness | null;
+  seed: number;                // Random seed for deterministic rendering
+  version: number;             // Element version (increment on edit)
+  versionNonce: number;        // Random number changed on edit
+  isDeleted: boolean;          // Should be false
+  boundElements: any;          // Usually null
+  updated: number;             // Timestamp in milliseconds
+  link: null;                  // External link (usually null)
+  locked: boolean;             // Whether element is locked
+}
+```
+
+## Element Types
+
+### Rectangle
+
+```typescript
+interface RectangleElement extends BaseElement {
+  type: "rectangle";
+  roundness: { type: 3 };      // 3 = rounded corners
+  text?: string;               // Optional text inside
+  fontSize?: number;           // Font size (16-32 typical)
+  fontFamily?: number;         // 5 = Excalifont (default), 2 = Helvetica, 3 = Cascadia
+  textAlign?: "left" | "center" | "right";
+  verticalAlign?: "top" | "middle" | "bottom";
+}
+```
+
+**Example:**
+```json
+{
+  "id": "rect1",
+  "type": "rectangle",
+  "x": 100,
+  "y": 100,
+  "width": 200,
+  "height": 100,
+  "strokeColor": "#1e1e1e",
+  "backgroundColor": "#a5d8ff",
+  "text": "My Box",
+  "fontSize": 20,
+  "textAlign": "center",
+  "verticalAlign": "middle",
+  "roundness": { "type": 3 }
+}
+```
+
+### Ellipse
+
+```typescript
+interface EllipseElement extends BaseElement {
+  type: "ellipse";
+  text?: string;
+  fontSize?: number;
+  fontFamily?: number;
+  textAlign?: "left" | "center" | "right";
+  verticalAlign?: "top" | "middle" | "bottom";
+}
+```
+
+### Diamond
+
+```typescript
+interface DiamondElement extends BaseElement {
+  type: "diamond";
+  text?: string;
+  fontSize?: number;
+  fontFamily?: number;
+  textAlign?: "left" | "center" | "right";
+  verticalAlign?: "top" | "middle" | "bottom";
+}
+```
+
+### Arrow
+
+```typescript
+interface ArrowElement extends BaseElement {
+  type: "arrow";
+  points: [number, number][];  // Array of [x, y] coordinates relative to element
+  startBinding: Binding | null;
+  endBinding: Binding | null;
+  roundness: { type: 2 };      // 2 = curved arrow
+}
+```
+
+**Example:**
+```json
+{
+  "id": "arrow1",
+  "type": "arrow",
+  "x": 100,
+  "y": 100,
+  "width": 200,
+  "height": 0,
+  "points": [
+    [0, 0],
+    [200, 0]
+  ],
+  "roundness": { "type": 2 },
+  "startBinding": null,
+  "endBinding": null
+}
+```
+
+**Points explanation:**
+- First point `[0, 0]` is relative to `(x, y)`
+- Subsequent points are relative to the first point
+- For straight horizontal arrow: `[[0, 0], [width, 0]]`
+- For straight vertical arrow: `[[0, 0], [0, height]]`
+
+### Line
+
+```typescript
+interface LineElement extends BaseElement {
+  type: "line";
+  points: [number, number][];
+  startBinding: Binding | null;
+  endBinding: Binding | null;
+  roundness: { type: 2 } | null;
+}
+```
+
+### Text
+
+```typescript
+interface TextElement extends BaseElement {
+  type: "text";
+  text: string;
+  fontSize: number;
+  fontFamily: number;          // 5 = Excalifont (default)
+  textAlign: "left" | "center" | "right";
+  verticalAlign: "top" | "middle" | "bottom";
+  roundness: null;             // Text has no roundness
+}
+```
+
+**Example:**
+```json
+{
+  "id": "text1",
+  "type": "text",
+  "x": 100,
+  "y": 100,
+  "width": 150,
+  "height": 25,
+  "text": "Hello World",
+  "fontSize": 20,
+  "fontFamily": 5,
+  "textAlign": "left",
+  "verticalAlign": "top",
+  "roundness": null
+}
+```
+
+**Width/Height calculation:**
+- Width ≈ `text.length * fontSize * 0.6`
+- Height ≈ `fontSize * 1.2 * numberOfLines`
+
+## Bindings
+
+Bindings connect arrows to shapes:
+
+```typescript
+interface Binding {
+  elementId: string;           // ID of bound element
+  focus: number;               // -1 to 1, position along edge
+  gap: number;                 // Distance from element edge
+}
+```
+
+## Common Colors
+
+| Color Name | Hex Code | Use Case |
+|------------|----------|----------|
+| Black | `#1e1e1e` | Default stroke |
+| Light Blue | `#a5d8ff` | Primary entities |
+| Light Green | `#b2f2bb` | Process steps |
+| Yellow | `#ffd43b` | Important/Central |
+| Light Red | `#ffc9c9` | Warnings/Errors |
+| Cyan | `#96f2d7` | Secondary items |
+| Transparent | `transparent` | No fill |
+| White | `#ffffff` | Background |
+
+## ID Generation
+
+IDs should be unique strings. Common patterns:
+
+```javascript
+// Timestamp-based
+const id = Date.now().toString(36) + Math.random().toString(36).substr(2);
+
+// Sequential
+const id = "element-" + counter++;
+
+// Descriptive
+const id = "step-1", "entity-user", "arrow-1-to-2";
+```
+
+## Seed Generation
+
+Seeds are used for deterministic randomness in hand-drawn effect:
+
+```javascript
+const seed = Math.floor(Math.random() * 2147483647);
+```
+
+## Version and VersionNonce
+
+```javascript
+const version = 1;  // Increment when element is edited
+const versionNonce = Math.floor(Math.random() * 2147483647);
+```
+
+## Coordinate System
+
+- Origin `(0, 0)` is top-left corner
+- X increases to the right
+- Y increases downward
+- All units are in pixels
+
+## Recommended Spacing
+
+| Context | Spacing |
+|---------|---------|
+| Horizontal gap between elements | 200-300px |
+| Vertical gap between rows | 100-150px |
+| Minimum margin from edge | 50px |
+| Arrow-to-box clearance | 20-30px |
+
+## Font Families
+
+Use **Excalifont** (ID `5`) as the default; do not use Virgil (ID 1). Optionally use Comic Shanns for headings, Lilita One for emphasis, Nunito for legends (if available in your Excalidraw version).
+
+| ID | Name | Description |
+|----|------|-------------|
+| 1 | Virgil | Legacy hand-drawn; prefer Excalifont instead |
+| 2 | Helvetica | Clean sans-serif |
+| 3 | Cascadia | Monospace |
+| 5 | **Excalifont** | **Default.** Hand-drawn, improved legibility |
+| (varies) | Comic Shanns | Use for headings (if available) |
+| (varies) | Lilita One | Use for important/emphasis (if available) |
+| (varies) | Nunito | Use for legends (if available) |
+
+## Validation Rules
+
+✅ **Required:**
+- All IDs must be unique
+- `type` must match actual element type
+- `version` must be an integer ≥ 1
+- `opacity` must be 0-100
+
+⚠️ **Recommended:**
+- Keep `roughness` at 1 for consistency
+- Use `strokeWidth` of 2 for clarity
+- Set `isDeleted` to `false`
+- Set `locked` to `false`
+- Keep `frameId`, `boundElements`, `link` as `null`
+
+## Complete Minimal Example
+
+```json
+{
+  "type": "excalidraw",
+  "version": 2,
+  "source": "https://excalidraw.com",
+  "elements": [
+    {
+      "id": "box1",
+      "type": "rectangle",
+      "x": 100,
+      "y": 100,
+      "width": 200,
+      "height": 100,
+      "angle": 0,
+      "strokeColor": "#1e1e1e",
+      "backgroundColor": "#a5d8ff",
+      "fillStyle": "solid",
+      "strokeWidth": 2,
+      "strokeStyle": "solid",
+      "roughness": 1,
+      "opacity": 100,
+      "groupIds": [],
+      "frameId": null,
+      "index": "a0",
+      "roundness": { "type": 3 },
+      "seed": 1234567890,
+      "version": 1,
+      "versionNonce": 987654321,
+      "isDeleted": false,
+      "boundElements": null,
+      "updated": 1706659200000,
+      "link": null,
+      "locked": false,
+      "text": "Hello",
+      "fontSize": 20,
+      "fontFamily": 5,
+      "textAlign": "center",
+      "verticalAlign": "middle"
+    }
+  ],
+  "appState": {
+    "viewBackgroundColor": "#ffffff",
+    "gridSize": 20
+  },
+  "files": {}
+}
+```

package/bundles/antigravity-plugin-extras/skills/excalidraw/references/reliable-diagrams.md

@@ -0,0 +1,115 @@
+# Producing Reliable Excalidraw Diagrams
+
+This reference ensures text never clips and arrows visibly connect to elements. Follow these rules for architecture, flowcharts, network, and ER diagrams. Use the brand color palette in this skill for all elements.
+
+---
+
+## 1. Text Sizing (No Clipping)
+
+Excalidraw clips text to the element's `width` and `height`. If either is too small, labels are cut off.
+
+### Rule
+
+For every `type: "text"` element:
+
+- **Width:** At least **max(line length) × fontSize × 0.7**, **plus 16–24px of horizontal padding**. Use the longest line in the string.
+- **Height:** At least **fontSize × 1.2 × number of lines**, then round up and add **~10–20% extra** for vertical padding.
+- **Do not** use a fixed small width (e.g. 180) for variable-length or long content.
+
+### Formula
+
+```text
+lineLength   = max(length(line) for each line in text)
+baseWidth    = lineLength * fontSize * 0.7
+width        = ceil(baseWidth) + 16           // horizontal padding
+
+baseHeight   = fontSize * 1.2 * numberOfLines
+height       = ceil(baseHeight * 1.1)        // ~10% vertical padding
+```
+
+### Examples
+
+1. Two-line feature label
+
+- Text: `"Lane 2: New Feature\n@planner -> @implement -> @tester"` (two lines; longest line length 32).
+- fontSize: 16.
+- **Width (min):** `32 × 16 × 0.7 ≈ 358` → `≈ 374` after padding → **use 380+**.
+- **Height (min):** `16 × 1.2 × 2 ≈ 38` → `≈ 42` after padding → **use 44+**.
+
+2. Outcome label from workflow mental model
+
+- Text: `"LANE 3 — PRD → Build"` (single line; length 22).
+- fontSize: 14.
+- **Width (min):** `22 × 14 × 0.7 ≈ 216` → `≈ 232` after padding → **use 240+**.
+- **Height (min):** `14 × 1.2 × 1 ≈ 17` → `≈ 19` after padding → **use 22+**.
+
+### Compatibility
+
+Include on text elements: `originalText` (same as `text`) and `lineHeight`: 1.25.
+
+---
+
+## 2. Arrow Connections (Bindings)
+
+Arrows that should **attach** to shapes must use `startBinding` and `endBinding` so they stick to the source and target elements. Unbound arrows can look disconnected.
+
+### Binding structure
+
+```json
+{
+  "elementId": "<id of the rectangle/ellipse/diamond>",
+  "focus": 0.5,
+  "gap": 0
+}
+```
+
+- **elementId:** The `id` of the element to attach to.
+- **focus:** Position along the edge (-1 to 1). Use 0.5 for center of edge.
+- **gap:** Distance in pixels from the element edge (0 = flush).
+
+### Example: Arrow from Box A to Box B
+
+Box A has `id: "box-a"`, right edge at x = 280. Box B has `id: "box-b"`, left edge at x = 400. Arrow:
+
+```json
+{
+  "id": "arrow-a-b",
+  "type": "arrow",
+  "x": 280,
+  "y": 135,
+  "width": 120,
+  "height": 0,
+  "points": [[0, 0], [120, 0]],
+  "roundness": { "type": 2 },
+  "startBinding": {
+    "elementId": "box-a",
+    "focus": 0.5,
+    "gap": 0
+  },
+  "endBinding": {
+    "elementId": "box-b",
+    "focus": 0.5,
+    "gap": 0
+  }
+}
+```
+
+### If not using bindings
+
+Compute arrow `(x, y)` and `points` so the line runs **from the source shape edge to the target shape edge**. Arrow direction and length must match the intended flow (e.g. "YES → L3" means the arrow goes toward the L3 element).
+
+---
+
+## 3. Decision / Flow Direction
+
+For decision diamonds or branch points:
+
+- Each branch arrow must **point toward** the element that branch leads to.
+- Place the label (e.g. YES, NO) next to the correct arrow.
+- If using bindings, set `endBinding.elementId` to the target shape so the arrow attaches to it.
+
+---
+
+## Golden Template
+
+A minimal working example with correct text sizing and bound arrows, using the brand palette, is in **`templates/reliable-flowchart.excalidraw`** in this skill. Use it as a starting point or reference for valid structure.

package/bundles/antigravity-plugin-extras/skills/excalidraw/scripts/README.md

@@ -0,0 +1,60 @@
+# Excalidraw Scripts
+
+Scripts for working with Excalidraw diagrams and libraries. Run from the skill folder or pass paths as arguments.
+
+## add-arrow.py
+
+Adds a straight arrow between two points in an existing `.excalidraw` diagram. Supports optional labels and line styles.
+
+**Usage:**
+```bash
+python add-arrow.py <diagram-path> <from-x> <from-y> <to-x> <to-y> [OPTIONS]
+```
+
+**Options:** `--style {solid|dashed|dotted}`, `--color HEX`, `--label TEXT`, `--use-edit-suffix` / `--no-use-edit-suffix`
+
+**Examples:**
+```bash
+python add-arrow.py diagram.excalidraw 300 200 500 300
+python add-arrow.py diagram.excalidraw 300 200 500 300 --label "HTTPS"
+python add-arrow.py diagram.excalidraw 400 350 600 400 --style dashed --color "#7950f2"
+```
+
+## add-icon-to-diagram.py
+
+Adds an icon from a split Excalidraw library into an existing diagram. Requires a library directory created by `split-excalidraw-library.py`.
+
+**Usage:**
+```bash
+python add-icon-to-diagram.py <diagram-path> <icon-name> <x> <y> [OPTIONS]
+```
+
+**Options:** `--library-path PATH`, `--label TEXT`, `--use-edit-suffix` / `--no-use-edit-suffix`
+
+**Examples:**
+```bash
+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 path/to/libraries/gcp-icons
+```
+
+Default library path: `../libraries/aws-architecture-icons` relative to this script (create it with `split-excalidraw-library.py` first).
+
+## split-excalidraw-library.py
+
+Splits an Excalidraw library file (`*.excalidrawlib`) into individual icon JSON files and a `reference.md` for lookup.
+
+**Usage:**
+```bash
+python split-excalidraw-library.py <path-to-library-directory>
+```
+
+**Workflow:**
+1. Create a directory for the library (e.g. `libraries/aws-architecture-icons`).
+2. Download a `.excalidrawlib` from [Excalidraw Libraries](https://libraries.excalidraw.com/) and place it in that directory.
+3. Run the script on that directory. It creates an `icons/` subfolder and `reference.md`.
+
+**Example:**
+```bash
+python split-excalidraw-library.py path/to/libraries/aws-architecture-icons/
+```