diff --git a/docs/plans/2026-02-25-flow-to-library-sync-design.md b/docs/plans/2026-02-25-flow-to-library-sync-design.md new file mode 100644 index 00000000..a1f77b42 --- /dev/null +++ b/docs/plans/2026-02-25-flow-to-library-sync-design.md @@ -0,0 +1,187 @@ +# Flow-to-Library Step Sync Design + +> **Date:** 2026-02-25 +> **Feature:** Automatically sync steps from published flows into the step library + +--- + +## Overview + +When a flow is published, its steps are extracted and written into the `step_library` table so engineers can discover and reuse them when building new flows or inserting ad-hoc steps during a live session. Library entries are flow-owned and read-only — forking creates a personal copy for customization. + +**What gets synced:** +- `procedural` / `maintenance` flows → each `procedure_step` node → `step_type: 'action'` +- `troubleshooting` flows → each `action` node → `step_type: 'action'`; each `solution` node → `step_type: 'solution'` +- `section_header` and `procedure_end` nodes are NOT synced as library entries + +**Sync trigger:** `PUT /trees/{tree_id}` when `status` transitions to `'published'` + +**Sync model:** Upsert keyed on `(source_tree_id, source_node_id)` — subsequent publishes update existing entries without losing usage counts or ratings. + +--- + +## Section 1: Data Model + +### New columns on `step_library` (one migration) + +| Column | Type | Default | Notes | +|--------|------|---------|-------| +| `source_tree_id` | UUID FK → `trees.id` | NULL | SET NULL on tree delete | +| `source_node_id` | String(255) | NULL | Node `id` within `tree_structure` JSONB | +| `is_flow_synced` | Boolean | `false` | Distinguishes synced from manually created entries | +| `last_synced_at` | DateTime(timezone=True) | NULL | Timestamp of last sync | + +### New optional field on `StepContent` schema + +Add `group_label: Optional[str] = None` to `StepContent` in `backend/app/schemas/step_library.py`. For procedural steps that belong to a section, this stores the section header title so steps are browsable/filterable by section in the library. + +### Per-step visibility override on procedural step nodes + +Add optional `library_visibility` field to individual step nodes in `tree_structure` JSONB: +- Type: `'team' | 'public'` (no `'private'` — synced steps are always at minimum team-visible) +- If absent: inherits visibility from the flow (default behavior) +- Stored directly on the step node in `tree_structure` — no schema migration needed (JSONB is flexible) + +### Visibility inheritance mapping + +| Flow state | Resolved step visibility | +|-----------|--------------------------| +| `is_public=True` | `'public'` | +| `is_public=False`, has `account_id` | `'team'` | +| `is_public=False`, no `account_id` | `'team'` | +| Step has `library_visibility` set | Use that value (overrides above) | + +### On flow deactivation / deletion + +When `is_active` is set to `False` on a tree, or the tree is deleted, soft-delete all synced library entries for that tree: `UPDATE step_library SET is_active=False WHERE source_tree_id=:tree_id AND is_flow_synced=True`. + +Forked copies (`is_flow_synced=False`, different `created_by`) are unaffected. + +--- + +## Section 2: Sync Logic (Backend) + +### Trigger location + +`backend/app/api/endpoints/trees.py` — `update_tree()` function, after the block at line ~587 where `status` is confirmed to be transitioning to `'published'`. + +### Extraction logic + +**For procedural/maintenance flows:** +``` +steps = tree_structure.get('steps', []) +for node in steps: + if node['type'] != 'procedure_step': + continue + # find the most recent section_header preceding this step + group_label = last_seen_section_header_title + yield StepLibraryUpsert( + title=node['title'], + step_type='action', + content=StepContent( + instructions=node.get('description') or node['title'], + help_text=node.get('expected_outcome'), + commands=[StepCommand(label=c.get('label',''), command=c['code'], command_type=c.get('language')) + for c in normalize_commands(node.get('commands'))], + group_label=group_label, + ), + visibility=node.get('library_visibility') or resolve_visibility(tree), + source_tree_id=tree.id, + source_node_id=node['id'], + ) +``` + +**For troubleshooting flows:** +``` +walk all nodes recursively +for node with type in ('action', 'solution'): + yield StepLibraryUpsert( + title=node['title'], + step_type='action' if node['type']=='action' else 'solution', + content=StepContent( + instructions=node.get('description') or node['title'], + ), + visibility=resolve_visibility(tree), + source_tree_id=tree.id, + source_node_id=node['id'], + ) +``` + +**Command normalization:** `node.commands` can be a plain string or an array of `{language, code, label}` objects. Normalize both into `StepCommand` list. + +### Upsert query + +```sql +INSERT INTO step_library (id, title, step_type, content, visibility, created_by, + account_id, is_flow_synced, source_tree_id, source_node_id, last_synced_at, ...) +VALUES (...) +ON CONFLICT (source_tree_id, source_node_id) +DO UPDATE SET + title = EXCLUDED.title, + content = EXCLUDED.content, + visibility = EXCLUDED.visibility, + last_synced_at = EXCLUDED.last_synced_at, + is_active = true -- re-activate if previously soft-deleted +``` + +Requires a unique constraint on `(source_tree_id, source_node_id)`. + +### `created_by` for synced entries + +Set to the tree's `author_id`. This gives the flow author "ownership" of the entry, consistent with the flow-owned model. Permissions in `core/permissions.py` already allow the creator to see their own private steps — no change needed. + +--- + +## Section 3: Per-Step Visibility Override (Editor) + +### Where + +`frontend/src/components/procedural-editor/StepEditor.tsx` — inside the existing "More Options" collapsible section. + +### What + +A **"Library Visibility"** select field, shown only for `procedure_step` nodes (not section headers, not end nodes): + +``` +Library Visibility +[ Inherit from flow ▼ ] (options: Inherit from flow / Team only / Public) +``` + +- Default (no `library_visibility` on node): renders as "Inherit from flow" +- Selecting "Team only" or "Public" writes `library_visibility: 'team'` or `library_visibility: 'public'` to the node +- Selecting "Inherit from flow" removes the `library_visibility` key from the node + +Only rendered when `tree_type` is `'procedural'` or `'maintenance'`. Troubleshooting flows have no per-node override (they inherit the flow visibility always). + +--- + +## Section 4: Frontend — Step Library Browser + +### Changes to `StepLibraryBrowser` / step list + +- **"From Flow" badge** on synced entries (`is_flow_synced: true`): small chip — same style as existing type badges. Shows source flow name. +- **Step detail/preview panel**: add "Sourced from: [Flow Name]" line with a link to the flow's navigate/edit page. +- **Read-only indicator**: for `is_flow_synced` entries, replace the Edit button with a lock icon + tooltip: "Managed by source flow — fork to customize." +- **Fork behavior**: existing "Save to Library" copy mechanism unchanged. Forked copy gets `is_flow_synced=false`, `source_tree_id=null`, `created_by=current_user`. + +### API response changes + +`StepLibraryResponse` needs two new fields: +- `is_flow_synced: bool` +- `source_tree_name: Optional[str]` — joined from `trees.name` at query time + +--- + +## Files Changed + +| File | Change | +|------|--------| +| `backend/alembic/versions/030_add_step_library_sync_fields.py` | New migration — add 4 columns + unique constraint | +| `backend/app/models/step_library.py` | Add 4 new columns + FK relationship to Tree | +| `backend/app/schemas/step_library.py` | Add `group_label` to `StepContent`; add `is_flow_synced` + `source_tree_name` to response schema | +| `backend/app/api/endpoints/trees.py` | Add sync logic after publish transition | +| `backend/app/core/step_sync.py` | New module — extraction + upsert logic (keeps trees.py clean) | +| `backend/tests/test_step_sync.py` | New test file | +| `frontend/src/types/step.ts` | Add `is_flow_synced`, `source_tree_name` to `Step` type | +| `frontend/src/components/procedural-editor/StepEditor.tsx` | Add Library Visibility select in More Options | +| `frontend/src/components/step-library/StepLibraryBrowser.tsx` | From Flow badge, read-only indicator, source flow link |