@bruslan/vibeflow

v0.3.2

Published

3 months ago

Cloudflare Workflows development tool

0High
0Medium
0Low

VibeFlow - Workflow Visualization & Debugging CLI

A CLI tool for visualizing, debugging, and tracing Cloudflare Workflows. Connect to any codebase and instantly see your workflows as interactive diagrams.

npx vibeflow init ./src/workflows
npx vibeflow dev

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         VIBEFLOW                                 │
│           AI-Powered Workflow Visualization Platform             │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   Frontend (React + XYFlow)  ──▶  Backend (Bun)  ──▶  Cloudflare │
│   vibeflow_ui/                    src/server.ts      Workflows   │
│   - Flow visualization            - REST API         src/workflows/
│   - WebSocket logs                - AI generation                │
│   - VSCode integration            - Wrangler mgmt                │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Tech Stack

| Layer | Stack | |-------|-------| | Runtime | Bun 1.3.5+ | | Frontend | React 19, XYFlow, Tailwind 4 | | Backend | Bun.serve() with WebSocket | | AI | Claude Haiku 4.5 (Anthropic SDK) | | Workflows | Cloudflare Workers | | Types | TypeScript 5.9 |

Key Features

AI Visualization: TypeScript workflow code → ReactFlow JSON via Claude Haiku
Live Execution: Run workflows locally with real-time log streaming
Source Navigation: Click nodes to open source files in VSCode
Interactive UI: Pan, zoom, and explore workflow graphs

Overview

This project demonstrates a complete Cloudflare Workflows setup with:

6-step workflow pipeline: Webhook receiver → Context fetcher → LLM analyzer → Tool executor → LLM evaluator → Response sender
WhatsApp integration: Receives webhook messages, processes them, and sends responses
Mocked AI services: Image generation, video generation, and LLM analysis (all simulated locally)
Type-safe TypeScript: Strict typing throughout with comprehensive interfaces
Bun-native: Uses Bun for runtime, testing, and package management

Project Structure

vibeflow/
├── src/
│   ├── index.ts                      # Main entry point with fetch handler
│   ├── workflows/
│   │   └── whatsapp-processor.ts     # Main workflow orchestration
│   ├── steps/                        # Individual workflow steps
│   │   ├── webhook-receiver.ts
│   │   ├── context-fetcher.ts
│   │   ├── llm-analyzer.ts
│   │   ├── tool-executor.ts
│   │   ├── llm-evaluator.ts
│   │   └── response-sender.ts
│   ├── types/                        # TypeScript type definitions
│   ├── mocks/                        # Mocked external services
│   └── env.d.ts                      # Environment type definitions
├── test/
│   ├── fixtures/                     # Sample webhook payloads
│   └── steps/                        # Unit tests
├── wrangler.toml                     # Cloudflare configuration
└── package.json

Installation

bun install

Development

Start the local Cloudflare Workers development server:

bun run dev

This starts the workflow on http://localhost:8787 with hot reloading enabled.

Testing the Workflow

1. Test WhatsApp Webhook Verification

curl "http://localhost:8787/webhook/whatsapp?hub.mode=subscribe&hub.verify_token=vibeflow_verify_token&hub.challenge=test123"

2. Send a Text Message

curl -X POST http://localhost:8787/webhook/whatsapp \
  -H "Content-Type: application/json" \
  -d @test/fixtures/text-message.json

3. Send an Image Generation Request

curl -X POST http://localhost:8787/webhook/whatsapp \
  -H "Content-Type: application/json" \
  -d @test/fixtures/image-request.json

4. Send a Video Generation Request

curl -X POST http://localhost:8787/webhook/whatsapp \
  -H "Content-Type: application/json" \
  -d @test/fixtures/video-request.json

5. Check Workflow Status

# Use the instanceId returned from the POST request
curl http://localhost:8787/workflow/status/{instanceId}

Workflow Pipeline

Webhook Receiver - Validates and extracts message data
Context Fetcher - Retrieves conversation history (mocked)
LLM Analyzer - Analyzes intent and determines if tools are needed (mocked)
Tool Executor - Generates images/videos if requested (mocked, conditional)
LLM Evaluator - Evaluates results and creates final message (mocked)
Response Sender - Sends response back via WhatsApp (mocked)

Running Tests

# Run all tests
bun test

# Run tests in watch mode
bun run test:watch

API Endpoints

GET /webhook/whatsapp - WhatsApp webhook verification
POST /webhook/whatsapp - Receive WhatsApp messages (triggers workflow)
GET /workflow/status/:id - Check workflow instance status
GET / - API information

Mock Services

All external services are mocked for local development:

WhatsApp API: Simulated send/receive with rate limiting
LLM Analysis: Intent detection based on keywords
Image Generation: Returns placeholder images (3-5s delay)
Video Generation: Returns sample video (5-10s delay)

Workflow Configuration

Each step has specific retry and timeout policies:

| Step | Retries | Backoff | Timeout | |------|---------|---------|---------| | webhook-receiver | 0 | - | - | | context-fetcher | 3 | exponential | 30s | | llm-analyzer | 2 | exponential | 60s | | tool-executor | 1 | exponential | 5min | | llm-evaluator | 2 | exponential | 60s | | response-sender | 3 | exponential | 30s |

Technologies

Runtime: Bun v1.3.5+
Framework: Cloudflare Workflows
Language: TypeScript 5+
Testing: bun:test
Development: Wrangler 4.54+

Deployment

# Generate type definitions
bun run types

# Deploy to Cloudflare Workers
bun run deploy

CLI Commands (Planned)

# Initialize vibeflow for an existing project
vibeflow init /path/to/workflows
  → Scans for workflow patterns
  → Generates vibeflow.config.ts
  → Creates workflow visualizations

# Start development server + UI
vibeflow dev [--workflow <name>] [--port 3001]
  → Starts wrangler dev
  → Launches visualization UI
  → Streams logs with tracing

# Generate/regenerate visualization
vibeflow generate [--workflow <name>] [--all]
  → AI-powered flow generation
  → Validates structure

# List discovered workflows
vibeflow list
  → Shows all workflows with metadata

# Validate workflow structure
vibeflow validate [--workflow <name>]
  → Checks imports resolve
  → Verifies step implementations

Config File: `vibeflow.config.ts`

export default {
  workflowsDir: "./src/workflows",
  stepsDir: "./src/steps",
  port: 3001,
  wranglerConfig: "./wrangler.toml",
  tracing: {
    enabled: true,
    captureInputs: true,
    captureOutputs: true,
  }
}

Workflow Development Pain Points (Why This Tool Exists)

1. Debugging is Blind

Silent step failures with no centralized error tracking
Console.log disappears after execution
Can't see which step is running during long operations
No request tracing across steps

2. Conditional Logic is Opaque

Complex decisions buried in step functions
No visualization of decision trees
Unclear why workflow terminated early

3. Performance is Unmeasurable

No execution metrics per step
Can't identify bottleneck steps

4. Error Context is Lost

No unified error response format
Retry behavior is invisible

DX Features Roadmap

Tier 1: Core CLI (MVP)

[ ] vibeflow init - Project scanning & config generation
[ ] vibeflow dev - Server + wrangler integration
[ ] vibeflow list - Workflow discovery
[ ] Bundle UI with CLI

Tier 2: Execution Tracing

[ ] Step execution timeline visualization
[ ] Decision path visualization
[ ] State snapshots (input/output per step)
[ ] trace() wrapper for opt-in rich tracing

import { trace } from 'vibeflow/trace';
const result = await trace(step.do("my-step", () => myFunction()));

Tier 3: Advanced Debugging

[ ] Error reconstruction with breadcrumbs
[ ] Performance profiler
[ ] Replay mode (re-run with captured inputs)

Tier 4: Orchestration

[ ] Workflow composition (chain workflows)
[ ] Workflow templates
[ ] Hot reload for steps

Future Vision: SaaS Platform

vibeflow.dev/github/username/repo

GitHub Integration: Connect repos, auto-detect workflows, generate on push
Hosted Visualization: Share diagrams via URL, embed in docs
Cloud Execution: Trigger workflows from UI, view traces
Analytics: Execution metrics, error rates, performance trends

┌─────────────────────────────────────────────────────────────┐
│                    vibeflow.dev (SaaS)                       │
├─────────────────────────────────────────────────────────────┤
│   GitHub App  →  Worker (Clone & Parse)  →  D1 (Metadata)   │
│                          ↓                                   │
│                   R2 (Generated Assets)                      │
│                          ↓                                   │
│                   Pages (Hosted UI)                          │
└─────────────────────────────────────────────────────────────┘

Current Limitations

Mock Services: LLM analysis, image/video generation, and WhatsApp API are mocked
No Authentication: API endpoints are currently unprotected
In-Memory Storage: Rate limiting and conversation data lost on restart
Read-Only Visualization: Workflow graphs generated from code, not editable in UI

Project created using Bun

This project was created using bun init and follows Bun best practices. Bun is a fast all-in-one JavaScript runtime.

The error indicates your npm access token has expired. You need to log in again:

npm login After logging in, run the publish command again:

bun run publish:patch Note: Since the version was already bumped to 0.3.0, you may want to publish directly without bumping again:

npm publish --access public