@marktoflow/gui 2.0.0-alpha.13 → 2.0.0-alpha.14

package/README.md

@@ -45,8 +45,11 @@ marktoflow gui
 # With options
 marktoflow gui --port 3000        # Custom port
 marktoflow gui --open             # Open browser automatically
+marktoflow gui --workflow-dir ./workflows  # Custom workflow directory
 ```
 
+The GUI will start at `http://localhost:3001` (or your specified port) and automatically watch your workflow directory for changes.
+
 ### Programmatic Usage
 
 ```typescript
@@ -61,6 +64,41 @@ const server = await startServer({
 console.log('GUI available at http://localhost:3001');
 ```
 
+## Using the GUI
+
+### Opening Workflows
+
+1. **From File System**: The GUI automatically discovers workflows in your configured directory
+2. **Create New**: Click "New Workflow" to start from scratch or use a template
+3. **Import**: Drag and drop `.md` workflow files into the browser
+
+### Editing Workflows
+
+#### Visual Mode
+- Drag tools from the sidebar onto the canvas
+- Connect steps by dragging from output to input ports
+- Edit step properties in the right panel
+- Add conditions, loops, and error handling visually
+
+#### Code Mode
+- Switch to the Monaco editor for direct markdown editing
+- Syntax highlighting for YAML and markdown
+- Auto-completion for tool actions and inputs
+
+#### AI-Assisted Mode
+- Type natural language commands in the AI prompt box
+- Examples:
+  - "Add a step to send a Slack message when the build fails"
+  - "Create a loop to process all GitHub PRs"
+  - "Add error handling to retry failed API calls"
+
+### Running Workflows
+
+1. Click the "Run" button in the toolbar
+2. Provide inputs if required
+3. Watch real-time execution status via WebSocket updates
+4. View execution results in the Properties panel
+
 ## Interface Overview
 
 ```
@@ -146,24 +184,208 @@ ollama serve
 # The GUI will automatically detect Ollama at localhost:11434
 ```
 
-## API Endpoints
+## API Reference
+
+The GUI server exposes a comprehensive REST API for programmatic access:
+
+### Workflow Operations
+
+#### List All Workflows
+```bash
+GET /api/workflows
+
+Response:
+{
+  "workflows": [
+    {
+      "path": "daily-standup/workflow.md",
+      "id": "daily-standup",
+      "name": "Daily Standup Report",
+      "triggers": [...],
+      "modified": "2026-01-31T10:00:00Z"
+    }
+  ]
+}
+```
+
+#### Get Workflow
+```bash
+GET /api/workflows/:path
+
+Response:
+{
+  "workflow": {
+    "id": "daily-standup",
+    "name": "Daily Standup Report",
+    "tools": {...},
+    "steps": [...],
+    "content": "# Markdown content..."
+  }
+}
+```
+
+#### Create/Update Workflow
+```bash
+POST /api/workflows
+Content-Type: application/json
+
+{
+  "path": "my-workflow/workflow.md",
+  "content": "---\nworkflow:\n  id: my-workflow\n..."
+}
+
+Response:
+{
+  "success": true,
+  "path": "my-workflow/workflow.md"
+}
+```
+
+### AI Operations
+
+#### List AI Providers
+```bash
+GET /api/ai/providers
+
+Response:
+{
+  "activeProvider": "claude-code",
+  "providers": [
+    {
+      "id": "claude-code",
+      "name": "Claude Code (SDK)",
+      "status": "ready",
+      "isActive": true,
+      "description": "Model: claude-sonnet-4-20250514"
+    },
+    {
+      "id": "copilot",
+      "name": "GitHub Copilot",
+      "status": "needs_config",
+      "isActive": false
+    },
+    {
+      "id": "demo",
+      "name": "Demo Mode (No API)",
+      "status": "ready",
+      "isActive": false
+    }
+  ]
+}
+```
+
+**Status values:**
+- `ready` - Provider is configured and available
+- `needs_config` - Provider requires configuration (API key, etc.)
+- `unavailable` - Provider failed to initialize
 
-The GUI server exposes a REST API:
+#### Set Active Provider
+```bash
+POST /api/ai/providers/:id
+Content-Type: application/json
+
+{
+  "apiKey": "optional-api-key",
+  "baseUrl": "optional-base-url",
+  "model": "optional-model-name"
+}
+
+Response:
+{
+  "success": true,
+  "status": {
+    "activeProvider": "claude-code",
+    "providers": [...]
+  }
+}
+```
 
+#### Send AI Prompt
 ```bash
-# Workflow operations
-GET  /api/workflows              # List all workflows
-GET  /api/workflows/:path        # Get workflow by path
-POST /api/workflows              # Create/update workflow
+POST /api/ai/prompt
+Content-Type: application/json
+
+{
+  "prompt": "Add a step to send Slack notification",
+  "workflowId": "daily-standup",
+  "context": {...}
+}
+
+Response:
+{
+  "success": true,
+  "changes": {
+    "steps": [...],
+    "description": "Added Slack notification step"
+  }
+}
+```
 
-# AI operations
-GET  /api/ai/providers           # List AI providers and status
-POST /api/ai/providers/:id       # Set active AI provider
-POST /api/ai/prompt              # Send prompt to AI
+### Workflow Execution
 
-# Execution
-POST /api/execute/:path          # Execute a workflow
-GET  /api/execute/status/:runId  # Get execution status
+#### Execute Workflow
+```bash
+POST /api/execute/:path
+Content-Type: application/json
+
+{
+  "inputs": {
+    "message": "Hello World"
+  },
+  "dryRun": false
+}
+
+Response:
+{
+  "success": true,
+  "runId": "run_abc123",
+  "status": "running"
+}
+```
+
+#### Get Execution Status
+```bash
+GET /api/execute/status/:runId
+
+Response:
+{
+  "runId": "run_abc123",
+  "status": "completed",
+  "startTime": "2026-01-31T10:00:00Z",
+  "endTime": "2026-01-31T10:00:15Z",
+  "steps": [
+    {
+      "action": "slack.chat.postMessage",
+      "status": "completed",
+      "output": {...}
+    }
+  ]
+}
+```
+
+### WebSocket Events
+
+Connect to `ws://localhost:3001` for real-time updates:
+
+```javascript
+const ws = new WebSocket('ws://localhost:3001');
+
+// Listen for execution updates
+ws.on('execution:start', (data) => {
+  console.log('Workflow started:', data.runId);
+});
+
+ws.on('execution:step', (data) => {
+  console.log('Step completed:', data.step);
+});
+
+ws.on('execution:complete', (data) => {
+  console.log('Workflow completed:', data.result);
+});
+
+ws.on('execution:error', (data) => {
+  console.error('Workflow error:', data.error);
+});
 ```
 
 ## Keyboard Shortcuts
@@ -194,31 +416,175 @@ OLLAMA_BASE_URL=...        # For Ollama provider
 
 ## Development
 
+### Setting Up Development Environment
+
 ```bash
+# Clone the repository
+git clone https://github.com/marktoflow/marktoflow.git
+cd marktoflow
+
 # Install dependencies
 pnpm install
 
-# Start development server
+# Build all packages
+pnpm build
+
+# Start GUI in development mode
+cd packages/gui
+pnpm dev
+```
+
+The development server will start:
+- **Frontend**: `http://localhost:5173` (Vite dev server with HMR)
+- **Backend API**: `http://localhost:3001` (Express server)
+- **WebSocket**: `ws://localhost:3001` (Real-time updates)
+
+### Development Commands
+
+```bash
+# Start dev server with hot reload
 pnpm dev
 
 # Build for production
 pnpm build
 
+# Preview production build
+pnpm preview
+
 # Run tests
 pnpm test
+
+# Type checking
+pnpm type-check
+
+# Linting
+pnpm lint
+```
+
+### Project Structure
+
+```
+packages/gui/
+├── src/
+│   ├── components/          # React components
+│   │   ├── Canvas/         # Workflow canvas (React Flow)
+│   │   ├── Sidebar/        # Workflow and tool browser
+│   │   ├── Properties/     # Step properties editor
+│   │   └── AIPrompt/       # AI assistance interface
+│   ├── server/             # Express + Socket.IO backend
+│   │   ├── api/            # REST API routes
+│   │   ├── websocket/      # WebSocket handlers
+│   │   └── workflow/       # Workflow execution
+│   ├── stores/             # Zustand state management
+│   ├── hooks/              # React hooks
+│   ├── types/              # TypeScript types
+│   └── utils/              # Utility functions
+├── public/                 # Static assets
+└── dist/                   # Production build
 ```
 
+### Adding New Features
+
+1. **New Tool Integration**: Add to `src/components/Sidebar/ToolPalette.tsx`
+2. **New API Endpoint**: Add to `src/server/api/routes.ts`
+3. **New AI Provider**: Add to `src/server/ai/providers/`
+4. **New Canvas Node**: Add to `src/components/Canvas/nodes/`
+
+### Technology Stack
+
+- **Frontend**: React 18, TypeScript, Vite
+- **UI Framework**: Radix UI, Tailwind CSS
+- **State Management**: Zustand
+- **Canvas**: React Flow
+- **Code Editor**: Monaco Editor
+- **Backend**: Express, Socket.IO
+- **File Watching**: Chokidar
+- **Testing**: Vitest, React Testing Library
+
 ## Requirements
 
 - Node.js 18+
 - Modern browser (Chrome, Firefox, Safari, Edge)
 - Screen resolution: 1280x720 minimum
 
+## Troubleshooting
+
+### GUI Not Starting
+
+```bash
+# Check if port is already in use
+lsof -i :3001
+
+# Use a different port
+marktoflow gui --port 3002
+```
+
+### AI Provider Not Available
+
+```bash
+# For Claude Code
+claude  # Verify Claude CLI is authenticated
+
+# For GitHub Copilot
+copilot auth login  # Re-authenticate
+
+# For Ollama
+ollama serve  # Ensure Ollama is running
+```
+
+### Workflows Not Appearing
+
+```bash
+# Check workflow directory
+marktoflow gui --workflow-dir ./workflows
+
+# Verify workflow files are valid markdown
+marktoflow workflow validate workflow.md
+```
+
+### WebSocket Connection Issues
+
+If real-time updates aren't working:
+1. Check browser console for WebSocket errors
+2. Verify firewall isn't blocking WebSocket connections
+3. Try restarting the GUI server
+
+### Build Issues
+
+```bash
+# Clean and rebuild
+pnpm clean
+pnpm build
+
+# Clear node_modules
+rm -rf node_modules
+pnpm install
+```
+
+## Examples
+
+Load any workflow from the [examples/](https://github.com/marktoflow/marktoflow/tree/main/examples) directory:
+
+```bash
+# Start GUI with examples
+marktoflow gui --workflow-dir ./examples
+
+# Open specific example
+marktoflow gui --open examples/daily-standup/workflow.md
+```
+
+Try these workflows in the GUI:
+- **daily-standup** - See AI-generated summaries in action
+- **code-review** - Visualize multi-step PR review flow
+- **web-automation** - Watch browser automation steps execute
+- **copilot-code-review** - See GitHub Copilot SDK integration
+
 ## Documentation
 
 - [User Guide](../../docs/GUI_USER_GUIDE.md)
 - [API Reference](../../docs/GUI_API_REFERENCE.md)
 - [Developer Guide](../../docs/GUI_DEVELOPER_GUIDE.md)
+- [Examples](https://github.com/marktoflow/marktoflow/tree/main/examples)
 
 ## License