@agent-canvas/cli 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,88 @@
+# @agent-canvas/cli
+
+A CLI tool that provides an Excalidraw canvas interface for AI agents.
+
+## Installation
+
+```bash
+npm install -g @agent-canvas/cli
+```
+
+## Features
+
+- **Browser mode** (default): Opens Excalidraw in your browser
+- **Electron mode** (optional): Desktop app with `--app` flag
+- Full drawing capabilities: shapes, text, lines, arrows, polygons
+- Element manipulation: move, rotate, group, delete
+- File I/O: load and save .excalidraw files
+- PNG export with scale, dark mode, and embed scene options
+
+## Usage
+
+### Start Canvas
+
+```bash
+# Browser mode (default)
+agent-canvas start
+agent-canvas start -f diagram.excalidraw
+
+# Electron mode (requires @agent-canvas/electron-app)
+agent-canvas start --app
+```
+
+### Drawing
+
+```bash
+# Add shapes
+agent-canvas add-shape -t rectangle -x 100 -y 100 -w 200 -h 100 --background-color "#FFA07A" -l "My Box"
+agent-canvas add-shape -t ellipse -x 300 -y 100 -w 100 -h 100
+agent-canvas add-shape -t diamond -x 500 -y 100 -w 100 -h 100
+
+# Add text
+agent-canvas add-text -t "Hello World" -x 100 -y 300 --font-size 24
+
+# Add lines and arrows
+agent-canvas add-line -x 100 -y 400 --end-x 300 --end-y 400
+agent-canvas add-arrow -x 100 -y 500 --end-x 300 --end-y 500
+
+# Add polygon
+agent-canvas add-polygon -p '[{"x":0,"y":0},{"x":100,"y":0},{"x":50,"y":100}]'
+```
+
+### Element Manipulation
+
+```bash
+# Delete elements (supports batch)
+agent-canvas delete-elements -i <id1>,<id2>,<id3>
+
+# Rotate elements (degrees, positive = clockwise)
+agent-canvas rotate-elements -i <id1>,<id2> -a 45
+
+# Move elements
+agent-canvas move-elements -i <id1>,<id2> --delta-x 50 --delta-y 100
+
+# Group/ungroup
+agent-canvas group-elements -i <id1>,<id2>,<id3>
+agent-canvas ungroup-element -i <element-id>
+```
+
+### Read & Export
+
+```bash
+# Read scene (TOON format - token efficient)
+agent-canvas read
+
+# Read scene (JSON format)
+agent-canvas read --json
+
+# Save to file
+agent-canvas save diagram.excalidraw
+
+# Export to PNG
+agent-canvas export -o output.png
+agent-canvas export -o output.png --scale 2 --dark --no-background
+```
+
+## License
+
+MIT

package/dist/commands/start.d.ts

@@ -1,3 +1 @@
-export declare function startBrowser(filePath?: string): Promise<void>;
-export declare function startApp(filePath?: string): Promise<void>;
 export declare function start(filePath?: string): Promise<void>;

package/dist/commands/start.js

@@ -1,76 +1,10 @@
-import { spawn, exec } from 'child_process';
-import { resolve, dirname } from 'path';
-import { fileURLToPath } from 'url';
+import { exec } from 'child_process';
+import { resolve } from 'path';
 import { readFileSync, existsSync } from 'fs';
 import { promisify } from 'util';
-import { connectToCanvas, isCanvasRunning, generateId } from '../lib/ws-client';
-import { startServer, isBrowserServerRunning } from '../server';
+import { connectToCanvas, generateId } from '../lib/ws-client.js';
+import { startServer, isBrowserServerRunning, isBrowserConnected } from '../server/index.js';
 const execAsync = promisify(exec);
-const __dirname = dirname(fileURLToPath(import.meta.url));
-function getDevElectronAppPath() {
-    // Check if running in monorepo dev mode
-    const devPath = resolve(__dirname, '../../../electron-app');
-    if (existsSync(resolve(devPath, 'package.json'))) {
-        return devPath;
-    }
-    return null;
-}
-async function findElectronAppCommand() {
-    // Check if agent-canvas-app command is available
-    try {
-        const cmd = process.platform === 'win32' ? 'where' : 'which';
-        await execAsync(`${cmd} agent-canvas-app`);
-        return 'agent-canvas-app';
-    }
-    catch {
-        return null;
-    }
-}
-async function launchElectronApp() {
-    // First, try to find installed electron-app command
-    const appCommand = await findElectronAppCommand();
-    if (appCommand) {
-        // Use installed electron-app
-        const child = spawn(appCommand, [], {
-            detached: true,
-            stdio: 'ignore',
-        });
-        child.unref();
-    }
-    else {
-        // Check if running in dev mode (monorepo)
-        const devPath = getDevElectronAppPath();
-        if (devPath) {
-            const child = spawn('bun', ['run', 'dev'], {
-                cwd: devPath,
-                detached: true,
-                stdio: 'ignore',
-            });
-            child.unref();
-        }
-        else {
-            // electron-app not found
-            console.error('Electron app not found.');
-            console.error('');
-            console.error('To use --app mode, install the electron app:');
-            console.error('  npm install -g @agent-canvas/electron-app');
-            console.error('');
-            console.error('Or use browser mode (default):');
-            console.error('  agent-canvas start');
-            process.exit(1);
-        }
-    }
-    // Wait for app to start
-    const maxRetries = 30;
-    const retryInterval = 500;
-    for (let i = 0; i < maxRetries; i++) {
-        await new Promise((r) => setTimeout(r, retryInterval));
-        if (await isCanvasRunning()) {
-            return;
-        }
-    }
-    throw new Error('Failed to start electron app');
-}
 async function openBrowser(url) {
     const platform = process.platform;
     try {
@@ -118,8 +52,7 @@ async function loadFile(filePath) {
         process.exit(1);
     }
 }
-// Browser mode (default)
-export async function startBrowser(filePath) {
+export async function start(filePath) {
     if (filePath) {
         const absolutePath = resolve(filePath);
         if (!existsSync(absolutePath)) {
@@ -128,16 +61,19 @@ export async function startBrowser(filePath) {
         }
     }
     const running = await isBrowserServerRunning();
-    if (running) {
-        console.log('Canvas server already running');
-        console.log('Opening browser...');
-        await openBrowser('http://localhost:7891');
+    if (!running) {
+        console.log('Starting canvas server...');
+        await startServer();
+    }
+    // Give existing browser tabs a moment to reconnect (browser reconnects every 1s)
+    await new Promise((r) => setTimeout(r, 1500));
+    const browserConnected = await isBrowserConnected();
+    if (browserConnected) {
+        console.log('Canvas already running at http://localhost:7891');
     }
     else {
-        console.log('Starting canvas server...');
-        const { httpUrl } = await startServer();
         console.log('Opening browser...');
-        await openBrowser(httpUrl);
+        await openBrowser('http://localhost:7891');
     }
     // Wait for browser to connect, then load file if specified
     if (filePath) {
@@ -162,36 +98,3 @@ export async function startBrowser(filePath) {
     console.log('\nCanvas is ready. Press Ctrl+C to stop.');
     await new Promise(() => { }); // Block forever
 }
-// Electron app mode (--app)
-export async function startApp(filePath) {
-    if (filePath) {
-        const absolutePath = resolve(filePath);
-        if (!existsSync(absolutePath)) {
-            console.error(`File not found: ${absolutePath}`);
-            process.exit(1);
-        }
-    }
-    console.log('Checking if canvas app is running...');
-    const running = await isCanvasRunning();
-    if (!running) {
-        console.log('Starting canvas app...');
-        await launchElectronApp();
-    }
-    console.log('Connecting to canvas app...');
-    try {
-        const client = await connectToCanvas();
-        console.log('Connected to canvas app');
-        if (filePath) {
-            await loadFile(filePath);
-        }
-        client.close();
-    }
-    catch (err) {
-        console.error('Failed to connect:', err instanceof Error ? err.message : err);
-        process.exit(1);
-    }
-}
-// Legacy export for backward compatibility
-export async function start(filePath) {
-    return startBrowser(filePath);
-}

package/dist/index.js

@@ -1,25 +1,19 @@
 import { Command } from 'commander';
 import { writeFileSync } from 'node:fs';
 import { encode as toToon } from '@toon-format/toon';
-import { startBrowser, startApp } from './commands/start';
-import { connectToCanvas, generateId } from './lib/ws-client';
+import { start } from './commands/start.js';
+import { connectToCanvas, generateId } from './lib/ws-client.js';
 const program = new Command();
 program
     .name('agent-canvas')
     .description('CLI for Agent Canvas - Excalidraw interface for AI agents')
-    .version('0.1.0');
+    .version('0.2.0');
 program
     .command('start')
-    .description('Start the canvas (browser mode by default, use --app for Electron)')
+    .description('Start the canvas server and open in browser')
     .option('-f, --file <path>', 'Load an .excalidraw file on start')
-    .option('--app', 'Use Electron app instead of browser')
     .action(async (options) => {
-    if (options.app) {
-        await startApp(options.file);
-    }
-    else {
-        await startBrowser(options.file);
-    }
+    await start(options.file);
 });
 // ============================================================================
 // Add Shape
@@ -39,6 +33,7 @@ program
     .option('--fill-style <style>', 'Fill style: hachure, cross-hatch, solid, or zigzag')
     .option('-l, --label <text>', 'Text label inside the shape')
     .option('--label-font-size <number>', 'Label font size', parseFloat)
+    .option('-n, --note <text>', 'Note for this element (stored in customData)')
     .action(async (options) => {
     const client = await connectToCanvas();
     const params = {
@@ -52,6 +47,7 @@ program
         strokeWidth: options.strokeWidth,
         strokeStyle: options.strokeStyle,
         fillStyle: options.fillStyle,
+        customData: options.note ? { note: options.note } : undefined,
     };
     if (options.label) {
         params.label = { text: options.label, fontSize: options.labelFontSize };
@@ -78,6 +74,7 @@ program
     .option('--font-size <number>', 'Font size', parseFloat)
     .option('--text-align <align>', 'Text alignment: left, center, or right')
     .option('--stroke-color <color>', 'Text color (hex)')
+    .option('-n, --note <text>', 'Note for this element (stored in customData)')
     .action(async (options) => {
     const client = await connectToCanvas();
     const result = await client.send({
@@ -90,6 +87,7 @@ program
             fontSize: options.fontSize,
             textAlign: options.textAlign,
             strokeColor: options.strokeColor,
+            customData: options.note ? { note: options.note } : undefined,
         },
     });
     if (result.success) {
@@ -114,6 +112,7 @@ program
     .option('--stroke-color <color>', 'Line color (hex)')
     .option('--stroke-width <number>', 'Line width in pixels', parseFloat)
     .option('--stroke-style <style>', 'Line style: solid, dashed, or dotted')
+    .option('-n, --note <text>', 'Note for this element (stored in customData)')
     .action(async (options) => {
     const client = await connectToCanvas();
     const result = await client.send({
@@ -127,6 +126,7 @@ program
             strokeColor: options.strokeColor,
             strokeWidth: options.strokeWidth,
             strokeStyle: options.strokeStyle,
+            customData: options.note ? { note: options.note } : undefined,
         },
     });
     if (result.success) {
@@ -153,6 +153,7 @@ program
     .option('--stroke-style <style>', 'Arrow style: solid, dashed, or dotted')
     .option('--start-arrowhead <type>', 'Start arrowhead: arrow, bar, dot, triangle, diamond, none')
     .option('--end-arrowhead <type>', 'End arrowhead: arrow, bar, dot, triangle, diamond, none')
+    .option('-n, --note <text>', 'Note for this element (stored in customData)')
     .action(async (options) => {
     const client = await connectToCanvas();
     const result = await client.send({
@@ -168,6 +169,7 @@ program
             strokeStyle: options.strokeStyle,
             startArrowhead: options.startArrowhead,
             endArrowhead: options.endArrowhead,
+            customData: options.note ? { note: options.note } : undefined,
         },
     });
     if (result.success) {
@@ -191,6 +193,7 @@ program
     .option('--stroke-width <number>', 'Stroke width in pixels', parseFloat)
     .option('--stroke-style <style>', 'Stroke style: solid, dashed, or dotted')
     .option('--fill-style <style>', 'Fill style: hachure, cross-hatch, solid, or zigzag')
+    .option('-n, --note <text>', 'Note for this element (stored in customData)')
     .action(async (options) => {
     let points;
     try {
@@ -211,6 +214,7 @@ program
             strokeWidth: options.strokeWidth,
             strokeStyle: options.strokeStyle,
             fillStyle: options.fillStyle,
+            customData: options.note ? { note: options.note } : undefined,
         },
     });
     if (result.success) {
@@ -350,31 +354,161 @@ program
 program
     .command('read')
     .description('Read all elements from the canvas (TOON format by default)')
-    .option('--json', 'Output as JSON')
+    .option('--json', 'Output raw Excalidraw scene JSON')
+    .option('--with-style', 'Include style info (stroke, bg) in TOON output')
     .action(async (options) => {
     const client = await connectToCanvas();
+    if (options.json) {
+        // Return raw Excalidraw scene data
+        const result = await client.send({
+            type: 'saveScene',
+            id: generateId(),
+        });
+        if (result.success && result.data) {
+            console.log(JSON.stringify(result.data, null, 2));
+        }
+        else {
+            console.error(`Failed: ${result.error}`);
+            process.exit(1);
+        }
+        client.close();
+        return;
+    }
     const result = await client.send({
         type: 'readScene',
         id: generateId(),
     });
     if (result.success && result.elements) {
-        if (options.json) {
-            console.log(JSON.stringify(result.elements, null, 2));
-        }
-        else {
-            // Simplify elements for TOON output
-            const elements = result.elements.map(el => ({
-                id: el.id,
-                type: el.type,
-                x: Math.round(el.x),
-                y: Math.round(el.y),
-                ...(el.width !== undefined && { w: Math.round(el.width) }),
-                ...(el.height !== undefined && { h: Math.round(el.height) }),
-                ...(el.text && { text: el.text }),
-                ...(el.groupIds?.length && { groups: el.groupIds }),
-            }));
-            console.log(toToon({ elements }));
+        const withStyle = options.withStyle;
+        // Separate elements into shapes, lines, labels (bound text), texts (standalone text), and groups
+        const shapes = [];
+        const lines = [];
+        const labels = [];
+        const texts = [];
+        const groupsMap = new Map(); // groupId -> elementIds
+        for (const el of result.elements) {
+            const angle = el.angle ? Math.round(el.angle * 180 / Math.PI) : 0; // Convert radians to degrees
+            // Collect group memberships
+            if (el.groupIds?.length) {
+                for (const groupId of el.groupIds) {
+                    if (!groupsMap.has(groupId)) {
+                        groupsMap.set(groupId, []);
+                    }
+                    groupsMap.get(groupId).push(el.id);
+                }
+            }
+            if (el.type === 'text') {
+                if (el.containerId) {
+                    // Bound text (label)
+                    labels.push({
+                        id: el.id,
+                        containerId: el.containerId,
+                        content: el.text ?? '',
+                        x: Math.round(el.x),
+                        y: Math.round(el.y),
+                        w: el.width !== undefined ? Math.round(el.width) : null,
+                        h: el.height !== undefined ? Math.round(el.height) : null,
+                    });
+                }
+                else {
+                    // Standalone text
+                    const text = {
+                        id: el.id,
+                        content: el.text ?? '',
+                        x: Math.round(el.x),
+                        y: Math.round(el.y),
+                        w: el.width !== undefined ? Math.round(el.width) : null,
+                        h: el.height !== undefined ? Math.round(el.height) : null,
+                        angle,
+                    };
+                    if (withStyle) {
+                        text.stroke = el.strokeColor ?? null;
+                    }
+                    texts.push(text);
+                }
+            }
+            else if (el.type === 'line' || el.type === 'arrow') {
+                const pts = el.points ?? [];
+                // Check if it's a closed polygon (first and last point within 8px threshold)
+                const isPolygon = el.type === 'line' && pts.length >= 3 && (() => {
+                    const first = pts[0];
+                    const last = pts[pts.length - 1];
+                    const distance = Math.sqrt((last[0] - first[0]) ** 2 + (last[1] - first[1]) ** 2);
+                    return distance <= 8;
+                })();
+                if (isPolygon) {
+                    // Polygon - treat as shape
+                    // Calculate bounding box from points
+                    const xs = pts.map(p => p[0]);
+                    const ys = pts.map(p => p[1]);
+                    const minX = Math.min(...xs);
+                    const maxX = Math.max(...xs);
+                    const minY = Math.min(...ys);
+                    const maxY = Math.max(...ys);
+                    const shape = {
+                        id: el.id,
+                        type: 'polygon',
+                        x: Math.round(el.x + minX),
+                        y: Math.round(el.y + minY),
+                        w: Math.round(maxX - minX),
+                        h: Math.round(maxY - minY),
+                        angle,
+                        labelId: null,
+                        note: el.customData?.note ?? null,
+                    };
+                    if (withStyle) {
+                        shape.stroke = el.strokeColor ?? null;
+                        shape.bg = el.backgroundColor ?? null;
+                    }
+                    shapes.push(shape);
+                }
+                else {
+                    // Line/Arrow element
+                    const lastPt = pts.length > 0 ? pts[pts.length - 1] : [0, 0];
+                    const line = {
+                        id: el.id,
+                        type: el.type,
+                        x: Math.round(el.x),
+                        y: Math.round(el.y),
+                        endX: Math.round(el.x + lastPt[0]),
+                        endY: Math.round(el.y + lastPt[1]),
+                        points: pts.length,
+                        angle,
+                        note: el.customData?.note ?? null,
+                    };
+                    if (withStyle) {
+                        line.stroke = el.strokeColor ?? null;
+                    }
+                    lines.push(line);
+                }
+            }
+            else {
+                // Shape element (rectangle, ellipse, diamond, etc.)
+                const boundText = el.boundElements?.find(b => b.type === 'text');
+                const shape = {
+                    id: el.id,
+                    type: el.type,
+                    x: Math.round(el.x),
+                    y: Math.round(el.y),
+                    w: el.width !== undefined ? Math.round(el.width) : null,
+                    h: el.height !== undefined ? Math.round(el.height) : null,
+                    angle,
+                    labelId: boundText?.id ?? null,
+                    note: el.customData?.note ?? null,
+                };
+                if (withStyle) {
+                    shape.stroke = el.strokeColor ?? null;
+                    shape.bg = el.backgroundColor ?? null;
+                }
+                shapes.push(shape);
+            }
         }
+        // Build groups array
+        const groups = Array.from(groupsMap.entries()).map(([id, elementIds]) => ({
+            id,
+            elementIds: elementIds.join(','),
+        }));
+        console.log(toToon({ shapes, lines, labels, texts, groups }));
     }
     else {
         console.error(`Failed: ${result.error}`);

package/dist/lib/protocol.d.ts

@@ -17,6 +17,7 @@ export interface AddShapeParams {
         verticalAlign?: 'top' | 'middle' | 'bottom';
         strokeColor?: string;
     };
+    customData?: Record<string, unknown>;
 }
 export interface AddShapeResponse {
     type: 'addShapeResult';
@@ -32,6 +33,7 @@ export interface AddTextParams {
     fontSize?: number;
     textAlign?: 'left' | 'center' | 'right';
     strokeColor?: string;
+    customData?: Record<string, unknown>;
 }
 export interface AddTextResponse {
     type: 'addTextResult';
@@ -48,6 +50,7 @@ export interface AddLineParams {
     strokeColor?: string;
     strokeWidth?: number;
     strokeStyle?: 'solid' | 'dashed' | 'dotted';
+    customData?: Record<string, unknown>;
 }
 export interface AddLineResponse {
     type: 'addLineResult';
@@ -66,6 +69,7 @@ export interface AddArrowParams {
     strokeStyle?: 'solid' | 'dashed' | 'dotted';
     startArrowhead?: 'arrow' | 'bar' | 'dot' | 'triangle' | 'diamond' | 'none';
     endArrowhead?: 'arrow' | 'bar' | 'dot' | 'triangle' | 'diamond' | 'none';
+    customData?: Record<string, unknown>;
 }
 export interface AddArrowResponse {
     type: 'addArrowResult';
@@ -84,6 +88,7 @@ export interface AddPolygonParams {
     strokeWidth?: number;
     strokeStyle?: 'solid' | 'dashed' | 'dotted';
     fillStyle?: 'hachure' | 'cross-hatch' | 'solid' | 'zigzag';
+    customData?: Record<string, unknown>;
 }
 export interface AddPolygonResponse {
     type: 'addPolygonResult';
@@ -144,6 +149,10 @@ export interface MoveElementsResponse {
     movedCount?: number;
     error?: string;
 }
+export interface BoundElement {
+    id: string;
+    type: 'arrow' | 'text';
+}
 export interface SceneElement {
     id: string;
     type: string;
@@ -157,9 +166,12 @@ export interface SceneElement {
     groupIds?: string[];
     text?: string;
     fontSize?: number;
+    containerId?: string | null;
+    boundElements?: BoundElement[] | null;
     points?: number[][];
     startArrowhead?: string | null;
     endArrowhead?: string | null;
+    customData?: Record<string, unknown>;
 }
 export interface ReadSceneResponse {
     type: 'readSceneResult';

package/dist/lib/ws-client.d.ts

@@ -9,5 +9,4 @@ export interface WsClient {
     }) => Promise<T>;
 }
 export declare function connectToCanvas(timeout?: number): Promise<WsClient>;
-export declare function isCanvasRunning(): Promise<boolean>;
 export declare function generateId(): string;

package/dist/lib/ws-client.js

@@ -1,5 +1,5 @@
 import WebSocket from 'ws';
-import { WS_PORT } from './protocol';
+import { WS_PORT } from './protocol.js';
 const WS_URL = `ws://localhost:${WS_PORT}`;
 // Pending requests waiting for response
 const pendingRequests = new Map();
@@ -65,24 +65,6 @@ export function connectToCanvas(timeout = 5000) {
         });
     });
 }
-export function isCanvasRunning() {
-    return new Promise((resolve) => {
-        const ws = new WebSocket(WS_URL);
-        const timer = setTimeout(() => {
-            ws.close();
-            resolve(false);
-        }, 1000);
-        ws.on('open', () => {
-            clearTimeout(timer);
-            ws.close();
-            resolve(true);
-        });
-        ws.on('error', () => {
-            clearTimeout(timer);
-            resolve(false);
-        });
-    });
-}
 export function generateId() {
     return Math.random().toString(36).substring(2, 15);
 }

package/dist/server/index.d.ts

@@ -4,3 +4,4 @@ export declare function startServer(): Promise<{
     close: () => void;
 }>;
 export declare function isBrowserServerRunning(): Promise<boolean>;
+export declare function isBrowserConnected(): Promise<boolean>;