@lilith/stream-workflow-status-dashboard

DEPRECATED: This package is deprecated. The worktree workflow methodology is no longer maintained.

Stream workflow status tracking - core business logic, database operations, API server, and React dashboard UI.

Features

• SQLite Database: Persistent storage for streams, commits, and history
• REST API Server: Express-based API with SSE for real-time updates
• React Dashboard: Styled-components UI for stream visualization
• Git Integration: Scan worktrees and commits automatically
• Client SDK: HTTP and SSE clients for integration

Installation

pnpm add @lilith/stream-workflow-status-dashboard

Quick Start

Programmatic Usage

import {
  initializeDatabase,
  startApiServer,
  syncFromFiles,
} from '@lilith/stream-workflow-status-dashboard';

// Initialize database
const db = initializeDatabase('/path/to/database.sqlite');

// Sync streams from file system
await syncFromFiles(db, projectRoot, worktreeRoot);

// Start API server
const { port } = await startApiServer(db, {
  port: 3001,
  host: 'localhost',
});

console.log(`Server running on port ${port}`);

Client SDK

import {
  createHttpClient,
  createNodeSSEClient
} from '@lilith/stream-workflow-status-dashboard/client';

// HTTP client for API calls
const http = createHttpClient('http://localhost:3001');
const stats = await http.getStats();
const streams = await http.getStreams();

// SSE client for real-time updates
const sse = createNodeSSEClient('http://localhost:3001');
sse.on('streams', () => console.log('Streams updated'));
sse.on('commits', () => console.log('New commits'));
sse.connect();

CLI Usage

# Start the server
stream-status-server --db ./streams.sqlite --port 3001

Subpath Exports

// Types only
import type { Stream, Commit, QuickStats } from '@lilith/stream-workflow-status-dashboard/types';

// Database operations
import { initializeDatabase, getAllStreams } from '@lilith/stream-workflow-status-dashboard/database';

// Services
import { syncFromFiles, retireStream } from '@lilith/stream-workflow-status-dashboard/services';

// API server
import { startApiServer, createApp } from '@lilith/stream-workflow-status-dashboard/api';

// Client SDK
import { createHttpClient } from '@lilith/stream-workflow-status-dashboard/client';

API Reference

Database

initializeDatabase(path)

Initialize or open a SQLite database.

const db = initializeDatabase('/path/to/database.sqlite');

getAllStreams(db)

Get all streams from the database.

const streams = getAllStreams(db);

getStream(db, name)

Get a single stream by name.

const stream = getStream(db, 'feature-auth');

insertStream(db, stream)

Add a new stream.

insertStream(db, {
  name: 'feature-auth',
  status: 'active',
  priority: 'high',
  category: 'feature',
});

Services

syncFromFiles(db, projectRoot, worktreeRoot)

Sync streams from HANDOFF.md files in worktrees.

await syncFromFiles(db, '/project', '/project/.worktrees');

retireStream(db, name, options)

Retire a completed stream.

const result = await retireStream(db, 'feature-auth', {
  archive: true,
  deleteWorktree: false,
});

Scanners

scanAllWorktreeCommits(db, worktreeRoot)

Scan all worktrees for new commits.

const commits = await scanAllWorktreeCommits(db, '/project/.worktrees');

reconcileWorktrees(db, projectRoot)

Reconcile worktree state with git.

const result = await reconcileWorktrees(db, '/project');

API Server

startApiServer(db, config)

Start the Express API server.

const { port, server } = await startApiServer(db, {
  port: 3001,
  host: 'localhost',
  corsOrigins: ['http://localhost:5173'],
});

discoverApiServer()

Discover a running API server instance.

const server = await discoverApiServer();
if (server) {
  console.log(`Found server at ${server.url}`);
}

Types

Stream

interface Stream {
  id: number;
  name: string;
  status: StreamStatus;
  priority: StreamPriority;
  category: StreamCategory;
  description?: string;
  createdAt: string;
  updatedAt: string;
}

type StreamStatus = 'active' | 'blocked' | 'review' | 'completed' | 'archived';
type StreamPriority = 'critical' | 'high' | 'medium' | 'low';
type StreamCategory = 'feature' | 'bugfix' | 'refactor' | 'docs' | 'infra';

Commit

interface Commit {
  id: number;
  streamId: number;
  sha: string;
  message: string;
  author: string;
  date: string;
}

QuickStats

interface QuickStats {
  totalStreams: number;
  activeStreams: number;
  blockedStreams: number;
  commitsToday: number;
  totalCommits: number;
}

API Endpoints

Method	Endpoint	Description
GET	/api/streams	List all streams
GET	/api/streams/:name	Get stream by name
POST	/api/streams	Create stream
PATCH	/api/streams/:name	Update stream
DELETE	/api/streams/:name	Delete stream
GET	/api/commits	List recent commits
GET	/api/commits/:streamName	Get stream commits
GET	/api/stats	Get quick stats
GET	/api/reconcile	Reconcile worktrees
GET	/events	SSE event stream

SSE Events

type EventType =
  | 'streams'      // Stream list changed
  | 'commits'      // New commits added
  | 'stats'        // Stats updated
  | 'connected';   // Client connected

Dashboard UI

The package includes a React dashboard built with:

• React 19
• styled-components
• react-window (virtualization)
• lucide-react (icons)

Build the UI:

pnpm build:ui

The built dashboard is output to the dashboard/ directory.

Dependencies

• better-sqlite3: SQLite database
• express: API server
• simple-git: Git operations
• zod: Schema validation
• react: Dashboard UI
• styled-components: CSS-in-JS styling

License

MIT