swarmcraft 0.0.1 → 0.1.1

package/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "vendor/multi-agent-protocol"]
+	path = vendor/multi-agent-protocol
+	url = https://github.com/multi-agent-protocol/multi-agent-protocol.git

package/.storybook/main.ts

@@ -0,0 +1,15 @@
+import type { StorybookConfig } from '@storybook/react-vite';
+
+const config: StorybookConfig = {
+  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
+  addons: [
+    '@storybook/addon-essentials',
+    '@storybook/addon-interactions',
+  ],
+  framework: {
+    name: '@storybook/react-vite',
+    options: {},
+  },
+};
+
+export default config;

package/.storybook/preview.tsx

@@ -0,0 +1,30 @@
+import React from 'react';
+import type { Preview } from '@storybook/react-vite';
+import '../src/index.css';
+
+const preview: Preview = {
+  parameters: {
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i,
+      },
+    },
+    backgrounds: {
+      default: 'dark',
+      values: [
+        { name: 'dark', value: '#0a0a0f' },
+        { name: 'light', value: '#ffffff' },
+      ],
+    },
+  },
+  decorators: [
+    (Story) => (
+      <div className="bg-background text-foreground min-h-screen p-4">
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export default preview;

package/CLAUDE.md

@@ -0,0 +1,253 @@
+# CLAUDE.md - Development Guidelines for AI Agents
+
+This document provides context and guidelines for AI agents working on the SwarmCraft codebase.
+
+## Project Overview
+
+SwarmCraft is a full-stack MAP (Multi-Agent Protocol) client for monitoring and steering coding agents on a codebase graph. It combines code graph visualization (Cytoscape/Sigma) with real-time agent monitoring via the MAP protocol and interactive ACP (Agent Client Protocol) conversations.
+
+## Quick Start Commands
+
+```bash
+npm install            # Install dependencies (single package)
+npm run dev            # Start Vite dev server (frontend only)
+npm run dev:server     # Start backend server (tsx watch)
+npm run build          # Build server + UI (TypeScript check + Vite)
+npm test               # Run all tests (UI + server, single run)
+npm run test:ui:watch  # Run UI tests in watch mode
+npm run test:server:watch  # Run server tests in watch mode
+npm run typecheck      # TypeScript check all projects
+```
+
+## Architecture Overview
+
+### System Architecture
+
+```
+Browser (React) ↔ Backend (Fastify REST/WS) ↔ MAP Server(s) ↔ Agents
+```
+
+### Monorepo Layout
+
+This is a **single-package monorepo** with frontend and backend co-located:
+
+```
+src/
+├── ui/                    # Frontend (React + Vite)
+│   ├── components/        # React components
+│   ├── hooks/             # React hooks
+│   ├── services/          # API client, WS client, ACP service
+│   ├── core/              # Graph DB, MCP client, ingestion pipeline
+│   ├── types/             # Frontend type definitions
+│   └── contexts/          # React contexts
+├── server/                # Backend (Fastify)
+│   ├── routes/            # REST API endpoints
+│   ├── map/               # MAP protocol integration
+│   ├── websocket/         # WebSocket hub
+│   ├── db/                # SQLite persistence (provider pattern)
+│   ├── subprocess/        # Process spawning
+│   └── terminal/          # PTY management
+```
+
+### Frontend (`src/ui/`)
+
+1. **Visualization Layer** (`src/ui/components/`)
+   - Sigma.js: WebGL-based, high-performance rendering for large graphs
+   - Cytoscape.js: Feature-rich, DOM-based rendering with advanced interactions
+   - ViewSwitcher allows toggling between renderers
+   - Agent overlay on codebase graph with position calculator
+
+2. **Data Layer** (`src/ui/core/`)
+   - Graphology: In-memory graph data structure
+   - Kuzu: WASM-based graph database for persistence
+   - Adapters convert between data formats
+
+3. **Agent Layer** (MAP-based)
+   - `src/ui/hooks/useSwarmCraft.ts` — Main agent state hook (agents, positions, messages)
+   - `src/ui/services/swarmcraft-api.ts` — REST client to backend
+   - `src/ui/services/swarmcraft-ws.ts` — WebSocket client with auto-reconnection and event batching
+   - `src/ui/services/acp-service.ts` — ACP stream management and message assembly
+
+4. **Types** (`src/ui/types/`)
+   - `src/ui/types/map.ts` — MAP protocol types (MAPAgent, MAPMessage, MAPEvent, etc.)
+   - `src/ui/types/acp.ts` — ACP types (streams, messages, parts, permissions, questions)
+
+### Backend (`src/server/`)
+
+1. **MAP Integration** (`src/server/map/`)
+   - `client-manager.ts` — Manages `ClientConnection` instances to MAP servers via `@multi-agent-protocol/sdk`
+   - `event-handler.ts` — Processes MAP events (agent lifecycle, messages, scopes)
+   - `acp-manager.ts` — Manages `ACPStreamConnection` instances for ACP conversations
+
+2. **REST API** (`src/server/routes/`)
+   - Agent, message, task, scope, and event CRUD
+   - MAP server management (add, connect, disconnect)
+   - ACP stream lifecycle (create, initialize, prompt, permission/question reply, extension calls)
+   - Subprocess spawning and management
+
+3. **WebSocket Hub** (`src/server/websocket/hub.ts`)
+   - Real-time event broadcast with topic-based subscriptions
+   - Heartbeat/ping-pong for connection liveness
+   - Topics: agents, messages, events, tasks, positions, acp
+
+4. **Database** (`src/server/db/`)
+   - SQLite persistence via provider pattern (`SQLiteSwarmCraftProvider`)
+   - Repository classes for agents, messages, events, tasks, positions, ACP conversations, MAP servers
+   - Plugin registers `fastify.swarmcraft.*` decorated services
+
+5. **Subprocess Management** (`src/server/subprocess/`)
+   - Spawn/stop MAP server processes (e.g. macro-agent)
+   - Auto-connect to spawned servers
+   - Log streaming
+
+### Key Design Patterns
+
+- **Provider Pattern**: Database access via `fastify.swarmcraft.*` (NOT legacy singleton services)
+- **Adapter Pattern**: Data conversion between Graphology, Cytoscape, and Agent formats
+- **Provider Pattern**: React contexts for shared state
+- **Event-Driven**: MAP events → backend EventEmitter → WebSocket → frontend React state
+- **ACP Streaming**: `pendingParts[]` accumulation with part-based message assembly
+
+## MAP Protocol Integration
+
+### Agent States
+
+9 states: `registered`, `active`, `busy`, `idle`, `suspended`, `stopping`, `stopped`, `failed`, `orphaned`
+
+### ACP (Agent Client Protocol)
+
+Interactive conversations with agents, proxied through the backend:
+
+```
+Frontend (acp-service.ts)
+  → REST: POST /acp/streams/:id/prompt
+    → Backend (acp-manager.ts)
+      → ACPStreamConnection.prompt()
+        → MAP Server → Agent
+Agent response streams back via:
+  ACPStreamConnection events
+    → Backend EventEmitter
+      → WebSocket broadcast
+        → Frontend acp-service.ts (message assembly)
+```
+
+### ACP Message Assembly
+
+Messages are assembled from streaming parts:
+- `ACPTextPart` — Streaming text content
+- `ACPToolCallPart` — Tool invocations
+- `ACPToolResultPart` — Tool outputs
+- `ACPStepStartPart` / `ACPStepFinishPart` — Step lifecycle
+
+### ACP Interactive Requests
+
+- **Permissions**: Agent requests tool execution approval → frontend shows dialog → user approves/denies
+- **Questions**: Agent asks structured questions with options → frontend shows selection UI → user answers
+
+## Cytoscape Integration
+
+### Component Hierarchy
+
+```
+CytoscapeProvider (context)
+└── CytoscapeCanvas (main visualization)
+    ├── NavigationControls (zoom/pan UI)
+    └── Minimap (overview navigation)
+```
+
+### Services (`src/ui/components/cytoscape/services/`)
+
+| Service | Responsibility |
+|---------|----------------|
+| `SelectionService` | Multi-select, focus mode, selection expansion |
+| `NavigationService` | Zoom, pan, fit, viewport history |
+| `HistoryService` | Undo/redo for graph changes |
+| `ThemeService` | Theme switching, CSS variables, custom themes |
+| `PerformanceService` | LOD rendering, debounced layouts, batch ops |
+| `AnimationService` | Node/edge animations |
+| `ContextMenuService` | Right-click context menus |
+| `HoverMenuService` | Hover tooltips and menus |
+
+## Testing Guidelines
+
+### Test Framework
+- **Vitest** with jsdom environment
+- Tests co-located in `__tests__` directories
+- Global setup in `src/ui/test/setup.ts`
+
+### Running Tests
+
+```bash
+npm test                       # Run all tests once (UI + server)
+npm run test:ui:watch          # UI tests in watch mode
+npm run test:server:watch      # Server tests in watch mode
+npm run test:coverage          # With coverage report
+```
+
+### Test Principles
+
+1. **Minimal Mocking**: Use real Graphology instances where possible
+2. **Integration-style**: Test service interactions, not just units
+3. **Event Verification**: Verify events are emitted correctly
+4. **State Assertions**: Check state changes, not implementation details
+
+## Key Files Reference
+
+| Purpose | File |
+|---------|------|
+| App entry | `src/ui/App.tsx` |
+| Main state hook | `src/ui/hooks/useAppState.tsx` |
+| Agent state hook | `src/ui/hooks/useSwarmCraft.ts` |
+| ACP service | `src/ui/services/acp-service.ts` |
+| REST API client | `src/ui/services/swarmcraft-api.ts` |
+| WebSocket client | `src/ui/services/swarmcraft-ws.ts` |
+| MAP types | `src/ui/types/map.ts` |
+| ACP types | `src/ui/types/acp.ts` |
+| Backend entry | `src/server/index.ts` |
+| Backend plugin | `src/server/plugin.ts` |
+| MAP client manager | `src/server/map/client-manager.ts` |
+| ACP stream manager | `src/server/map/acp-manager.ts` |
+| MAP event handler | `src/server/map/event-handler.ts` |
+| WebSocket hub | `src/server/websocket/hub.ts` |
+| ACP routes | `src/server/routes/acp.ts` |
+| DB provider | `src/server/db/provider.ts` |
+
+## Dependencies of Note
+
+| Package | Purpose |
+|---------|---------|
+| `cytoscape` | Graph visualization |
+| `cytoscape-cola` | Force-directed layout |
+| `graphology` | Graph data structure |
+| `sigma` | WebGL graph rendering |
+| `kuzu-wasm` | Graph database (frontend) |
+| `@multi-agent-protocol/sdk` | MAP protocol SDK (backend) |
+| `fastify` | Backend HTTP framework |
+| `@fastify/websocket` | WebSocket support |
+| `better-sqlite3` | SQLite database (backend) |
+
+## Common Gotchas
+
+### TypeScript Build Errors in Tests
+
+Test files are excluded from the production build via `tsconfig.ui.json`. If you add new test patterns, update the exclusion list.
+
+### MAP Agent State vs Display State
+
+`getAgentDisplayState()` in `src/ui/types/map.ts` maps raw MAP states to display-friendly states. Always use this for UI rendering.
+
+### ACP Stream State Split
+
+Frontend `acp-service.ts` and backend `acp-manager.ts` each maintain separate stream state. Backend broadcasts lifecycle events that frontend consumes to stay in sync.
+
+### Database Access Pattern
+
+Use the provider pattern (`fastify.swarmcraft.db.*`) for database access. Do NOT use the legacy singleton services in `src/server/services/`.
+
+## Contributing
+
+1. Run `npm run build` before committing to catch type errors
+2. Run `npm test` to ensure tests pass
+3. Follow existing patterns for new services/adapters
+4. Add tests for new functionality
+5. Update this file if adding significant new patterns or components

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Ngai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1 +1,130 @@
-# swarmcraft
+# SwarmCraft
+
+A visual code exploration and multi-agent orchestration platform. SwarmCraft enables developers to visualize codebases as interactive graphs, manage AI agent swarms, and explore code relationships through an intuitive web interface.
+
+## Features
+
+### Code Visualization
+- **Interactive Graph Canvas**: Visualize code structure as a navigable graph using Sigma.js or Cytoscape.js
+- **Dual View Modes**: Switch between Sigma (fast, WebGL-based) and Cytoscape (feature-rich, DOM-based) renderers
+- **File Tree Navigation**: Browse and navigate the codebase structure
+- **Code References Panel**: View code snippets and relationships for selected nodes
+
+### Session Visualization (Cytoscape)
+- **VoiceTree-inspired Design**: Hierarchical agent visualization with conversation flow
+- **Multi-select & Focus Mode**: Select multiple nodes with keyboard modifiers, focus on specific subgraphs
+- **Undo/Redo History**: Track and revert graph changes with full history support
+- **Viewport Navigation**: Zoom, pan, fit-to-view with viewport history (back/forward navigation)
+- **Theme System**: Light/dark/high-contrast themes with custom theme support
+- **Minimap**: Overview navigation for large graphs
+- **Performance Optimization**: Level-of-Detail (LOD) rendering, debounced layouts, batch operations
+
+### Multi-Agent Orchestration
+- **Agent Swarm Management**: Create, monitor, and coordinate multiple AI agents via MAP protocol
+- **ACP Conversations**: Interactive conversations with agents (permissions, questions, tool calls)
+- **Task Assignment**: Create and assign tasks to agents
+- **Real-time Messaging**: Monitor inter-agent communication
+
+### Code Analysis
+- **Embeddings Pipeline**: Generate code embeddings using WebGPU or WASM
+- **Semantic Search**: Find related code using vector similarity
+
+## Tech Stack
+
+- **Frontend**: React 18, TypeScript, Tailwind CSS
+- **Graph Libraries**: Sigma.js, Cytoscape.js, Graphology
+- **Database**: Kuzu (WASM, frontend), SQLite (backend)
+- **Code Parsing**: Tree-sitter (WASM)
+- **Backend**: Fastify, @multi-agent-protocol/sdk
+- **Build**: Vite
+
+## Getting Started
+
+### Prerequisites
+- Node.js 18+
+- npm
+
+### Installation
+
+```bash
+# Install dependencies
+npm install
+
+# Start frontend dev server
+npm run dev
+
+# Start backend server (in a separate terminal)
+npm run dev:server
+
+# Build for production
+npm run build
+
+# Run tests
+npm test
+```
+
+### Usage
+
+1. **Load a Repository**: Drag and drop a ZIP file or clone from a Git URL
+2. **Explore the Graph**: Navigate the code structure using pan, zoom, and node selection
+3. **Use Agents**: Open the SwarmCraft panel to connect MAP servers and manage AI agents
+
+## Project Structure
+
+```
+src/
+├── ui/                        # Frontend (React + Vite)
+│   ├── components/
+│   │   ├── cytoscape/         # Cytoscape visualization components
+│   │   │   ├── adapters/      # Data adapters (Graphology, Agent)
+│   │   │   ├── services/      # Core services (Selection, Navigation, History, Theme, Performance)
+│   │   │   └── hooks/         # React hooks for Cytoscape integration
+│   │   ├── agents/            # Agent management UI
+│   │   ├── acp/               # ACP conversation panels
+│   │   ├── swarmcraft/        # SwarmCraft dashboard components
+│   │   └── ...                # Other UI components
+│   ├── core/
+│   │   ├── embeddings/        # Code embedding generation
+│   │   ├── graph/             # Graph operations and algorithms
+│   │   ├── ingestion/         # Code ingestion pipeline
+│   │   ├── kuzu/              # Kuzu database integration
+│   │   ├── mcp/               # MCP client implementation
+│   │   └── search/            # Search functionality
+│   ├── hooks/                 # Shared React hooks
+│   ├── services/              # API client, WS client, ACP service
+│   └── types/                 # TypeScript type definitions
+├── server/                    # Backend (Fastify)
+│   ├── routes/                # REST API endpoints
+│   ├── map/                   # MAP protocol integration
+│   ├── websocket/             # WebSocket hub
+│   ├── db/                    # SQLite persistence
+│   ├── subprocess/            # Process management
+│   └── terminal/              # PTY management
+```
+
+## Testing
+
+The project uses Vitest for testing.
+
+```bash
+npm test                       # Run all tests once
+npm run test:ui:watch          # UI tests in watch mode
+npm run test:server:watch      # Server tests in watch mode
+npm run test:coverage          # With coverage report
+```
+
+### Test Structure
+- Tests are co-located with source files in `__tests__` directories
+- Mock helpers are in `src/ui/components/cytoscape/__tests__/helpers/`
+- Global test setup is in `src/ui/test/setup.ts`
+
+## Environment Variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `VITE_SWARMCRAFT_API_URL` | `http://localhost:3001/api` | Backend API URL |
+| `VITE_SWARMCRAFT_WS_URL` | `ws://localhost:3001/ws` | Backend WebSocket URL |
+
+## License
+
+MIT

package/api/proxy.ts

@@ -0,0 +1,104 @@
+import type { VercelRequest, VercelResponse } from '@vercel/node';
+
+/**
+ * CORS Proxy for isomorphic-git
+ * 
+ * isomorphic-git calls: /api/proxy?url=https://github.com/...
+ */
+export default async function handler(req: VercelRequest, res: VercelResponse) {
+  // Handle CORS preflight
+  if (req.method === 'OPTIONS') {
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, Git-Protocol, Accept');
+    res.status(200).end();
+    return;
+  }
+
+  // Get URL from query parameter
+  const { url } = req.query;
+  
+  if (!url || typeof url !== 'string') {
+    res.status(400).json({ error: 'Missing url query parameter' });
+    return;
+  }
+
+  // Only allow GitHub URLs for security
+  const allowedHosts = ['github.com', 'raw.githubusercontent.com'];
+  let parsedUrl: URL;
+  
+  try {
+    parsedUrl = new URL(url);
+  } catch {
+    res.status(400).json({ error: 'Invalid URL' });
+    return;
+  }
+  
+  if (!allowedHosts.some(host => parsedUrl.hostname.endsWith(host))) {
+    res.status(403).json({ error: 'Only GitHub URLs are allowed' });
+    return;
+  }
+
+  try {
+    const headers: Record<string, string> = {
+      'User-Agent': 'git/isomorphic-git',
+    };
+    
+    // Forward relevant headers
+    if (req.headers.authorization) {
+      headers['Authorization'] = req.headers.authorization as string;
+    }
+    if (req.headers['content-type']) {
+      headers['Content-Type'] = req.headers['content-type'] as string;
+    }
+    if (req.headers['git-protocol']) {
+      headers['Git-Protocol'] = req.headers['git-protocol'] as string;
+    }
+    if (req.headers.accept) {
+      headers['Accept'] = req.headers.accept as string;
+    }
+
+    // Get request body for POST requests
+    let body: Buffer | undefined;
+    if (req.method === 'POST') {
+      const chunks: Buffer[] = [];
+      for await (const chunk of req) {
+        chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+      }
+      body = Buffer.concat(chunks);
+    }
+
+    const response = await fetch(url, {
+      method: req.method || 'GET',
+      headers,
+      body: body ? new Uint8Array(body) : undefined,
+    });
+
+    // Set CORS headers
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Expose-Headers', '*');
+
+    // Forward response headers (except ones that cause issues)
+    const skipHeaders = [
+      'content-encoding', 
+      'transfer-encoding', 
+      'connection',
+      'www-authenticate', // IMPORTANT: Strip this to prevent browser's native auth popup!
+    ];
+    
+    response.headers.forEach((value, key) => {
+      if (!skipHeaders.includes(key.toLowerCase())) {
+        res.setHeader(key, value);
+      }
+    });
+
+    res.status(response.status);
+    const buffer = await response.arrayBuffer();
+    res.send(Buffer.from(buffer));
+    
+  } catch (error) {
+    console.error('Proxy error:', error);
+    res.status(500).json({ error: 'Proxy request failed', details: String(error) });
+  }
+}
+

package/dist/server/app.d.ts

@@ -0,0 +1,3 @@
+import { FastifyInstance } from 'fastify';
+export declare function buildApp(): Promise<FastifyInstance>;
+//# sourceMappingURL=app.d.ts.map

package/dist/server/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../src/server/app.ts"],"names":[],"mappings":"AAAA,OAAgB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAYnD,wBAAsB,QAAQ,IAAI,OAAO,CAAC,eAAe,CAAC,CAyIzD"}