[WIP] workflow builder

work-summary/2026-02-23-workflow-builder-ui.md

@@ -0,0 +1,93 @@
+# Workflow Builder UI Implementation
+
+**Date:** 2026-02-23
+
+## Summary
+
+Implemented a visual workflow builder interface for creating and editing workflow actions. The builder is accessible from the Actions page and provides a node-based canvas for constructing workflows using installed actions as task building blocks.
+
+## Changes
+
+### Frontend (Web UI)
+
+#### New Pages
+- **`web/src/pages/actions/WorkflowBuilderPage.tsx`** — Main workflow builder page with:
+  - Top toolbar with pack selector, workflow name/label/version inputs, save button
+  - Description, tags, and enabled toggle in a secondary row
+  - Three-panel layout: action palette (left), canvas (center), task inspector (right)
+  - Definition JSON preview panel (toggleable)
+  - Validation error display
+  - Support for both create (`/actions/workflows/new`) and edit (`/actions/workflows/:ref/edit`) modes
+
+#### New Components (`web/src/components/workflows/`)
+- **`ActionPalette.tsx`** — Searchable sidebar listing all available actions grouped by pack. Clicking an action adds it as a task to the canvas with auto-populated input parameters from the action's schema.
+- **`WorkflowCanvas.tsx`** — Visual canvas with:
+  - Draggable task nodes with absolute positioning
+  - SVG edge rendering for task transitions
+  - Interactive connection mode: click a port on one node, then click another node to create success/failure transitions
+  - Grid background, empty state with guidance
+  - Floating "add task" button
+- **`TaskNode.tsx`** — Individual task node component showing task name, action reference, input count, badges for conditions/retry/iteration, and connection/configure/delete action buttons
+- **`WorkflowEdges.tsx`** — SVG overlay rendering curved bezier edges between connected nodes with color-coded and dash-styled lines per transition type (success=green, failure=red dashed, complete=indigo, timeout=amber, decision=violet). Includes arrow markers and edge labels.
+- **`TaskInspector.tsx`** — Right-side property panel with collapsible sections for:
+  - Basic settings (name, type, condition)
+  - Action selection (dropdown of all actions) with auto-populate from schema
+  - Transitions (on_success, on_failure, on_complete, on_timeout dropdowns)
+  - Iteration (with_items, batch_size, concurrency)
+  - Retry & timeout configuration
+  - Publish variables (key=value pairs for workflow variable publishing)
+
+#### New Types & Utilities (`web/src/types/workflow.ts`)
+- TypeScript types for workflow builder state, tasks, edges, parameters, YAML definition format
+- `builderStateToDefinition()` — Converts builder state to the YAML-compatible definition format
+- `definitionToBuilderState()` — Converts existing workflow definitions back to builder state (for edit mode)
+- `deriveEdges()` — Extracts visual edges from task transition properties
+- `validateWorkflow()` — Client-side validation (name, label, version, pack, task names, action assignments, transition references)
+- Utility functions: `generateTaskId()`, `createEmptyTask()`, `generateUniqueTaskName()`
+
+#### New Hooks (`web/src/hooks/useWorkflows.ts`)
+- `useWorkflows()` — List workflows with filtering
+- `useWorkflow()` — Get single workflow by ref
+- `useCreateWorkflow()` / `useUpdateWorkflow()` / `useDeleteWorkflow()` — Standard CRUD mutations
+- `useSaveWorkflowFile()` — Calls `POST /api/v1/packs/{pack_ref}/workflow-files` to save workflow file to disk
+- `useUpdateWorkflowFile()` — Calls `PUT /api/v1/workflows/{ref}/file` to update workflow file on disk
+
+#### Modified Files
+- **`web/src/pages/actions/ActionsPage.tsx`** — Added "Workflow" button in the header that navigates to `/actions/workflows/new`
+- **`web/src/App.tsx`** — Added lazy-loaded routes for `WorkflowBuilderPage` at `/actions/workflows/new` and `/actions/workflows/:ref/edit`
+
+### Backend (API)
+
+#### New Endpoints
+- **`POST /api/v1/packs/{pack_ref}/workflow-files`** — Saves a new workflow:
+  1. Validates the request and checks the pack exists
+  2. Checks for duplicate workflow ref
+  3. Writes `{name}.workflow.yaml` to `{packs_base_dir}/{pack_ref}/actions/workflows/`
+  4. Creates the `workflow_definition` record in the database
+  5. Returns the workflow response
+
+- **`PUT /api/v1/workflows/{ref}/file`** — Updates an existing workflow:
+  1. Validates the request and finds the existing workflow
+  2. Overwrites the YAML file on disk
+  3. Updates the database record
+  4. Returns the updated workflow response
+
+#### New DTO
+- **`SaveWorkflowFileRequest`** in `crates/api/src/dto/workflow.rs` — Request body with name, label, description, version, pack_ref, definition (JSON), param_schema, out_schema, tags, enabled
+
+#### Modified Files
+- **`crates/api/src/routes/workflows.rs`** — Added `save_workflow_file`, `update_workflow_file` handlers and helper function `write_workflow_yaml`. Updated routes to include new endpoints. Added unit tests.
+- **`crates/api/src/dto/workflow.rs`** — Added `SaveWorkflowFileRequest` DTO
+
+## Workflow File Storage
+
+Workflow files are saved to: `{packs_base_dir}/{pack_ref}/actions/workflows/{name}.workflow.yaml`
+
+This is a new path (`actions/workflows/`) distinct from the existing `workflows/` directory used by the pack sync mechanism. The definition is serialized as YAML and simultaneously persisted to both disk and database.
+
+## Testing
+
+- All 89 existing unit tests pass
+- 2 new unit tests added for `SaveWorkflowFileRequest` validation
+- TypeScript compilation passes with zero errors from new code
+- Rust workspace compilation passes with zero warnings