@bernierllc/temporal-workflow-ui/README.md

Thin domain-specific wrapper around @bernierllc/generic-workflow-ui for Temporal workflows

# @bernierllc/temporal-workflow-ui

Thin domain-specific wrapper around @bernierllc/generic-workflow-ui for Temporal workflows.

## Installation

```bash
npm install @bernierllc/temporal-workflow-ui
```

## Phase 1: Core Types & Adapters

This package is currently in **Phase 1**, providing foundational types, adapters, and validation for Temporal workflows. Components will be added in Phase 2.

### What's Included (Phase 1)

- ✅ **Type Definitions** - Complete TypeScript types for Temporal workflows
- ✅ **Adapters** - Bidirectional conversion between Temporal, Generic, and JSON formats
- ✅ **Validation** - Comprehensive validation functions for workflows, stages, and transitions
- ⏳ **Components** - Coming in Phase 2

## Usage

### Type Definitions

```typescript
import {
  TemporalWorkflow,
  TemporalWorkflowStage,
  TemporalWorkflowTransition,
  TemporalActivityMetadata,
  TemporalAgentMetadata,
} from '@bernierllc/temporal-workflow-ui';

// Define a Temporal workflow
const workflow: TemporalWorkflow = {
  id: 'wf-1',
  name: 'Data Processing Workflow',
  description: 'Process and analyze data',
  stages: [
    {
      id: 'trigger-1',
      name: 'Manual Trigger',
      order: 0,
      type: 'trigger',
      metadata: {
        nodeType: 'trigger',
        triggerType: 'manual',
      },
    },
    {
      id: 'activity-1',
      name: 'Fetch Data',
      order: 1,
      type: 'activity',
      metadata: {
        nodeType: 'activity',
        activityName: 'fetchDataActivity',
        taskQueue: 'data-processing',
        retryPolicy: {
          maximumAttempts: 3,
          backoffCoefficient: 2,
          initialInterval: 1000,
        },
        timeout: {
          startToCloseTimeout: 30000,
        },
      },
    },
    {
      id: 'agent-1',
      name: 'AI Analyzer',
      order: 2,
      type: 'agent',
      metadata: {
        nodeType: 'agent',
        agentPromptId: 'analyzer-prompt-123',
        agentName: 'Data Analyzer',
        taskQueue: 'ai-processing',
        modelProvider: 'openai',
        modelName: 'gpt-4',
        temperature: 0.7,
      },
    },
  ],
  transitions: [
    {
      id: 'trans-1',
      from: 'trigger-1',
      to: 'activity-1',
    },
    {
      id: 'trans-2',
      from: 'activity-1',
      to: 'agent-1',
      condition: 'result.status === "success"',
      metadata: {
        label: 'On Success',
      },
    },
  ],
  defaultTaskQueue: 'default',
  workflowTimeout: 300000,
};
```

### Adapters

#### Temporal ↔ Generic Conversion

```typescript
import { temporalToGeneric, genericToTemporal } from '@bernierllc/temporal-workflow-ui';

// Convert Temporal workflow to Generic workflow
const genericWorkflow = temporalToGeneric(workflow);

// Use with generic-workflow-ui components
import { GenericWorkflowStepper } from '@bernierllc/generic-workflow-ui';
<GenericWorkflowStepper workflow={genericWorkflow} />;

// Convert back to Temporal
const temporalWorkflow = genericToTemporal(genericWorkflow);
```

#### Temporal ↔ JSON Conversion

```typescript
import { temporalWorkflowToJSON, jsonToTemporalWorkflow } from '@bernierllc/temporal-workflow-ui';

// Export workflow to JSON (n8n-style)
const jsonDefinition = temporalWorkflowToJSON(workflow);

// Save to file
fs.writeFileSync('workflow.json', JSON.stringify(jsonDefinition, null, 2));

// Import from JSON
const loadedWorkflow = jsonToTemporalWorkflow(jsonDefinition);
```

### Validation

```typescript
import { validateTemporalWorkflow, validateTaskQueue, validateRetryPolicy } from '@bernierllc/temporal-workflow-ui';

// Validate complete workflow
const result = validateTemporalWorkflow(workflow);

if (!result.valid) {
  console.error('Validation errors:');
  result.errors.forEach(error => {
    console.error(`- ${error.message}`, {
      stageId: error.stageId,
      field: error.field,
      severity: error.severity,
    });
  });
}

// Validate task queue
const taskQueueResult = validateTaskQueue({
  id: 'queue-1',
  name: 'processing-queue',
  workerCount: 5,
});

// Validate retry policy
const retryPolicyResult = validateRetryPolicy({
  maximumAttempts: 3,
  backoffCoefficient: 2,
  initialInterval: 1000,
  maximumInterval: 60000,
});
```

### Validation Rules

The validator enforces these rules:

**Workflow-Level:**
- ✅ Workflow must have a name
- ✅ Workflow must have at least one trigger node
- ✅ All stage IDs must be unique
- ✅ All transition IDs must be unique
- ✅ All transitions must reference valid stages
- ✅ No circular dependencies in workflow transitions
- ✅ All stages must have names
- ✅ All signal names must be unique (v1.1.0)
- ✅ All query names must be unique (v1.1.0)
- ✅ All work queue names must be unique (v1.1.0)
- ✅ No circular dependencies in blockUntil (v1.1.0)

**Node-Level:**
- ✅ Activities must have `activityName` and `taskQueue`
- ✅ Agents must have `agentPromptId`, `agentName`, and `taskQueue`
- ✅ Signals must have `signalName`
- ✅ Triggers must have `triggerType`
- ✅ Queries must have `queryName` (v1.1.0)
- ✅ Scheduled workflows must have `workflowName`, `taskQueue`, and valid `cronExpression` (v1.1.0)
- ✅ Work queues must have `queueId`, `queueName`, `signalName`, and `queryName` (v1.1.0)
- ✅ Child workflows with `blockUntil` must reference existing stages (v1.1.0)
- ✅ Retry policy values must be valid
- ✅ Timeout values must be valid

## New in v1.1.0

### Query Nodes

Query nodes enable parent-child workflow communication:

```typescript
{
  id: 'query-1',
  name: 'Check Parent Status',
  order: 3,
  type: 'query',
  metadata: {
    nodeType: 'query',
    queryName: 'getParentStatus',
    queryType: 'send',
    targetWorkflowId: 'parent-workflow-123',
    returnType: 'WorkflowStatus',
    timeout: 5000,
  },
}
```

### Scheduled Workflow Nodes

Schedule child workflows to run on a cron schedule:

```typescript
{
  id: 'scheduled-1',
  name: 'Daily Report Generator',
  order: 4,
  type: 'scheduled-workflow',
  metadata: {
    nodeType: 'scheduled-workflow',
    workflowName: 'generateDailyReport',
    taskQueue: 'reporting-queue',
    cronExpression: '0 9 * * *', // Every day at 9 AM
    timezone: 'America/New_York',
    parameters: {
      reportType: 'daily',
      recipients: ['team@example.com'],
    },
  },
}
```

### Work Queue Nodes

Coordinate work queues with signal/query patterns:

```typescript
{
  id: 'queue-1',
  name: 'High Priority Tasks',
  order: 5,
  type: 'work-queue',
  metadata: {
    nodeType: 'work-queue',
    queueId: 'high-priority-queue',
    queueName: 'highPriorityTasks',
    signalName: 'addHighPriorityTask',
    queryName: 'getQueueStatus',
    maxSize: 100,
    priority: 10,
    taskQueue: 'worker-queue',
  },
}
```

### Enhanced Child Workflow Metadata

Child workflows now support parent communication and dependency blocking:

```typescript
{
  id: 'child-1',
  name: 'Data Processor',
  order: 6,
  type: 'child-workflow',
  metadata: {
    nodeType: 'child-workflow',
    workflowName: 'processDataWorkflow',
    taskQueue: 'processing-queue',
    // Signal back to parent when done
    signalToParent: {
      signalName: 'notifyParent',
      autoCreate: true,
      queueName: 'notifications',
    },
    // Query parent for configuration
    queryParent: {
      queryName: 'getProcessingConfig',
      queueName: 'config-requests',
    },
    // Wait for other child workflows to complete
    blockUntil: ['child-fetch-data', 'child-validate'],
  },
}
```

### Workflow-Level Arrays

Workflows can now define signals, queries, and work queues at the top level:

```typescript
const workflow: TemporalWorkflow = {
  id: 'wf-1',
  name: 'Advanced Workflow',
  stages: [...],
  transitions: [...],
  // Define signals that child workflows can use
  signals: [
    {
      id: 'sig-1',
      name: 'notifyProgress',
      parameters: { progress: 'number' },
      autoGenerated: false
    },
  ],
  // Define queries for parent-child communication
  queries: [
    {
      id: 'q-1',
      name: 'getStatus',
      returnType: 'WorkflowStatus',
      autoGenerated: false
    },
  ],
  // Define work queues for coordination
  workQueues: [
    {
      id: 'wq-1',
      name: 'taskQueue',
      signalName: 'addTask',
      queryName: 'getQueueStatus',
      maxSize: 50,
      priority: 5,
    },
  ],
};
```

## API Reference

### Types

#### Core Types

- `TemporalWorkflow` - Complete workflow definition
- `TemporalWorkflowStage` - Individual workflow stage
- `TemporalWorkflowTransition` - Transition between stages
- `TemporalNodeType` - Node type union ('activity' | 'agent' | 'signal' | 'query' | 'scheduled-workflow' | 'work-queue' | etc.)

#### Metadata Types

- `TemporalActivityMetadata` - Activity-specific metadata
- `TemporalAgentMetadata` - Agent-specific metadata
- `TemporalSignalMetadata` - Signal-specific metadata
- `TemporalTriggerMetadata` - Trigger-specific metadata
- `TemporalChildWorkflowMetadata` - Child workflow metadata (enhanced in v1.1.0)
- `TemporalParallelMetadata` - Parallel execution metadata
- `TemporalConditionMetadata` - Conditional branching metadata
- `TemporalQueryMetadata` - Query operations metadata (new in v1.1.0)
- `TemporalScheduledWorkflowMetadata` - Cron-scheduled workflows (new in v1.1.0)
- `TemporalWorkQueueMetadata` - Work queue coordinator (new in v1.1.0)
- `TemporalRetryPolicy` - Retry configuration
- `TemporalTimeout` - Timeout configuration
- `TaskQueue` - Task queue definition

#### Execution Types

- `TemporalWorkflowExecution` - Workflow execution state
- `TemporalWorkflowExecutionStatus` - Execution status enum
- `TemporalStageExecutionStatus` - Stage execution status enum
- `TemporalWorkflowEvent` - Workflow event in history

#### Validation Types

- `ValidationResult` - Validation result with errors
- `ValidationError` - Individual validation error
- `ValidationSeverity` - Error severity ('error' | 'warning')

### Adapters

- `temporalToGeneric(workflow)` - Convert Temporal → Generic
- `genericToTemporal(workflow)` - Convert Generic → Temporal
- `temporalWorkflowToJSON(workflow)` - Convert Temporal → JSON
- `jsonToTemporalWorkflow(json)` - Convert JSON → Temporal

### Validation Functions

- `validateTemporalWorkflow(workflow)` - Validate complete workflow
- `validateStage(stage)` - Validate individual stage
- `validateTransition(transition)` - Validate individual transition
- `validateTaskQueue(taskQueue)` - Validate task queue
- `validateRetryPolicy(policy)` - Validate retry policy

## Design Philosophy

This package follows a **thin wrapper philosophy**:

- **Minimal Abstraction** - Delegates to `@bernierllc/generic-workflow-ui` for UI components
- **Type Safety First** - Full TypeScript support with strict mode
- **Lossless Conversion** - Bidirectional adapters preserve all data
- **Domain-Specific** - Temporal-specific types and validation
- **Flexible** - Access underlying generic components when needed

## Integration Status

- **Logger**: not-applicable
- **Docs-Suite**: ready
- **NeverHub**: not-applicable

## Roadmap

### Phase 1 (Current) ✅
- ✅ Type definitions
- ✅ Adapters (Temporal ↔ Generic ↔ JSON)
- ✅ Validation functions
- ✅ Comprehensive tests (85%+ coverage)

### Phase 2 (Next)
- ⏳ `TemporalWorkflowBuilder` - Visual workflow builder
- ⏳ `TemporalWorkflowStepper` - Progress visualization
- ⏳ `TemporalActivityCard` - Activity detail display
- ⏳ `TemporalAgentCard` - Agent detail display
- ⏳ `TemporalComponentPalette` - Drag-and-drop palette
- ⏳ `TemporalPropertyPanel` - Property editor
- ⏳ `TemporalTaskQueueSelector` - Task queue selector
- ⏳ `TemporalRetryPolicyEditor` - Retry policy editor
- ⏳ `TemporalTimeoutEditor` - Timeout editor

### Phase 3 (Future)
- ⏳ `TemporalWorkflowTimeline` - Execution history
- ⏳ `TemporalWorkflowExecutionPanel` - Complete monitoring panel
- ⏳ `useTemporalWorkflow` - Workflow state hook
- ⏳ `useTemporalExecution` - Execution monitoring hook

## Contributing

This package is part of the BernierLLC tools monorepo. See the root README for development guidelines.

## License

Copyright (c) 2025 Bernier LLC

This file is licensed to the client under a limited-use license.
The client may use and modify this code *only within the scope of the project it was delivered for*.
Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.

## See Also

- [@bernierllc/generic-workflow-ui](../generic-workflow-ui) - Generic workflow UI components
- [Temporal Documentation](https://docs.temporal.io/) - Official Temporal docs