@oronts/vendure-data-hub-plugin 0.1.1 → 0.1.2

package/dist/dashboard/routes/pipelines/components/ValidationPanel.tsx

@@ -0,0 +1,121 @@
+import * as React from 'react';
+import {
+    Button,
+    Dialog,
+    DialogClose,
+    DialogContent,
+    DialogDescription,
+    DialogHeader,
+    DialogTitle,
+} from '@vendure/dashboard';
+import type { ValidationIssue, ValidationState } from '../../../types';
+import { DIALOG_DIMENSIONS, SCROLL_HEIGHTS } from '../../../constants';
+
+export interface ValidationPanelProps {
+    validation: ValidationState;
+    isLoading: boolean;
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+}
+
+export function ValidationPanel({
+    validation,
+    isLoading,
+    open,
+    onOpenChange,
+}: ValidationPanelProps) {
+    return (
+        <Dialog open={open} onOpenChange={onOpenChange}>
+            <DialogContent className={DIALOG_DIMENSIONS.MAX_WIDTH_2XL} data-testid="validation-dialog">
+                <DialogHeader>
+                    <DialogTitle>Validation Issues</DialogTitle>
+                    <DialogDescription>Fix the following before publishing.</DialogDescription>
+                </DialogHeader>
+                <div className={`space-y-2 ${SCROLL_HEIGHTS.VALIDATION_PANEL} overflow-auto`}>
+                    {isLoading ? (
+                        <div className="flex items-center gap-2 text-muted-foreground py-4 justify-center">
+                            <div className="animate-spin h-4 w-4 border-2 border-current border-t-transparent rounded-full" />
+                            <span>Validating...</span>
+                        </div>
+                    ) : validation.issues.length === 0 ? (
+                        <div className="text-sm text-muted-foreground">No issues.</div>
+                    ) : (
+                        validation.issues.map((issue) => (
+                            <ValidationIssueItem key={`${issue.stepKey ?? 'global'}-${issue.field ?? 'none'}-${issue.message}`} issue={issue} />
+                        ))
+                    )}
+                    {validation.warnings.length > 0 && (
+                        <div className="mt-4">
+                            <div className="text-sm font-medium text-amber-800 mb-2">Warnings</div>
+                            {validation.warnings.map((warning) => (
+                                <ValidationIssueItem key={`warning-${warning.stepKey ?? 'global'}-${warning.field ?? 'none'}-${warning.message}`} issue={warning} variant="warning" />
+                            ))}
+                        </div>
+                    )}
+                </div>
+                <div className="flex justify-end">
+                    <DialogClose asChild>
+                        <Button variant="outline" data-testid="validation-dialog-close-button">Close</Button>
+                    </DialogClose>
+                </div>
+            </DialogContent>
+        </Dialog>
+    );
+}
+
+interface ValidationIssueItemProps {
+    issue: ValidationIssue;
+    variant?: 'error' | 'warning';
+}
+
+function ValidationIssueItem({ issue, variant = 'error' }: ValidationIssueItemProps) {
+    const bgClass = variant === 'warning' ? 'bg-amber-50 dark:bg-amber-950/30 border-amber-200 dark:border-amber-800' : '';
+
+    return (
+        <div className={`border rounded p-2 ${bgClass}`}>
+            <div className="text-sm">{issue.message}</div>
+            <div className="text-xs text-muted-foreground">
+                {issue.stepKey ? `Step: ${issue.stepKey}` : ''}
+                {issue.field ? ` - Field: ${issue.field}` : ''}
+                {issue.reason ? ` - Code: ${issue.reason}` : ''}
+            </div>
+        </div>
+    );
+}
+
+/**
+ * Validation status badge component for inline display
+ */
+export interface ValidationStatusBadgeProps {
+    validation: ValidationState;
+    isLoading: boolean;
+    onShowIssues: () => void;
+}
+
+export function ValidationStatusBadge({
+    validation,
+    isLoading,
+    onShowIssues,
+}: ValidationStatusBadgeProps) {
+    if (isLoading) {
+        return <span className="text-xs text-muted-foreground">Validating...</span>;
+    }
+
+    if (validation.isValid === true) {
+        return <span className="text-xs px-2 py-0.5 rounded bg-emerald-100 text-emerald-800">Valid</span>;
+    }
+
+    if (validation.isValid === false) {
+        return (
+            <button
+                type="button"
+                className="text-xs px-2 py-0.5 rounded bg-amber-100 text-amber-800 hover:underline"
+                onClick={onShowIssues}
+            >
+                Issues: {validation.count}
+            </button>
+        );
+    }
+
+    return null;
+}

package/dist/dashboard/routes/pipelines/components/VersionHistoryDialog.tsx

@@ -0,0 +1,131 @@
+import * as React from 'react';
+import {
+    Badge,
+    Button,
+    Dialog,
+    DialogClose,
+    DialogContent,
+    DialogDescription,
+    DialogHeader,
+    DialogTitle,
+} from '@vendure/dashboard';
+import { useQuery } from '@tanstack/react-query';
+import { api } from '@vendure/dashboard';
+import { pipelineTimelineDocument, pipelineKeys } from '../../../hooks';
+import { REVISION_TYPE, UI_LIMITS, DIALOG_DIMENSIONS, RUN_STATUS } from '../../../constants';
+import { formatDateTime } from '../../../utils';
+
+export interface TimelineEntry {
+    revision: {
+        id: string;
+        createdAt: string;
+        version: number;
+        type: string;
+        commitMessage?: string | null;
+        authorName?: string | null;
+        changesSummary?: unknown;
+        isLatest: boolean;
+        isCurrent: boolean;
+    };
+    runCount: number;
+    lastRunAt?: string | null;
+    lastRunStatus?: string | null;
+}
+
+export interface VersionHistoryDialogProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    pipelineId: string | undefined;
+}
+
+export function VersionHistoryDialog({
+    open,
+    onOpenChange,
+    pipelineId,
+}: VersionHistoryDialogProps) {
+    const { data: timeline = [], isPending: historyPending, isError } = useQuery({
+        queryKey: pipelineKeys.timeline(pipelineId ?? '', UI_LIMITS.TIMELINE_LIMIT),
+        queryFn: () =>
+            api.query(pipelineTimelineDocument, { pipelineId: pipelineId!, limit: UI_LIMITS.TIMELINE_LIMIT })
+                .then(res => (res?.dataHubPipelineTimeline ?? []) as TimelineEntry[]),
+        enabled: open && !!pipelineId,
+    });
+
+    return (
+        <Dialog open={open} onOpenChange={onOpenChange}>
+            <DialogContent className={`${DIALOG_DIMENSIONS.MAX_WIDTH_2XL} ${DIALOG_DIMENSIONS.MAX_HEIGHT_80VH} flex flex-col`}>
+                <DialogHeader className="flex-none">
+                    <DialogTitle>Version history</DialogTitle>
+                    <DialogDescription>Timeline of pipeline revisions</DialogDescription>
+                </DialogHeader>
+                <div className="flex-1 min-h-0 overflow-auto">
+                    {isError ? (
+                        <p className="text-sm text-destructive text-center py-4">Failed to load version history</p>
+                    ) : historyPending ? (
+                        <div className="flex items-center justify-center py-8 text-muted-foreground">Loading...</div>
+                    ) : timeline.length === 0 ? (
+                        <div className="flex items-center justify-center py-8 text-muted-foreground">No version history</div>
+                    ) : (
+                        <div className="space-y-2">
+                            {timeline.map((entry) => (
+                                <div
+                                    key={entry.revision.id}
+                                    className={`border rounded-md p-3 ${entry.revision.isCurrent ? 'border-primary bg-primary/5' : ''}`}
+                                >
+                                    <div className="flex items-center justify-between mb-1">
+                                        <div className="flex items-center gap-2">
+                                            <span className="font-medium">
+                                                {entry.revision.type === REVISION_TYPE.PUBLISHED ? `v${entry.revision.version}` : 'Draft'}
+                                            </span>
+                                            {entry.revision.isCurrent && (
+                                                <Badge variant="default" className="text-xs">Current</Badge>
+                                            )}
+                                            {entry.revision.isLatest && !entry.revision.isCurrent && (
+                                                <Badge variant="secondary" className="text-xs">Latest</Badge>
+                                            )}
+                                            <Badge variant={entry.revision.type === REVISION_TYPE.PUBLISHED ? 'default' : 'outline'} className="text-xs">
+                                                {entry.revision.type}
+                                            </Badge>
+                                        </div>
+                                        <span className="text-xs text-muted-foreground">
+                                            {formatDateTime(entry.revision.createdAt)}
+                                        </span>
+                                    </div>
+                                    {entry.revision.commitMessage && (
+                                        <div className="text-sm text-foreground mb-1">{entry.revision.commitMessage}</div>
+                                    )}
+                                    <div className="flex items-center gap-4 text-xs text-muted-foreground">
+                                        {entry.revision.authorName && <span>by {entry.revision.authorName}</span>}
+                                        {entry.runCount > 0 && <span>{entry.runCount} run{entry.runCount !== 1 ? 's' : ''}</span>}
+                                        {entry.lastRunStatus && (
+                                            <span className={entry.lastRunStatus === RUN_STATUS.COMPLETED ? 'text-green-600' : entry.lastRunStatus === RUN_STATUS.FAILED ? 'text-red-600' : ''}>
+                                                Last: {entry.lastRunStatus}
+                                            </span>
+                                        )}
+                                    </div>
+                                    {entry.revision.changesSummary && typeof entry.revision.changesSummary === 'object' && (
+                                        <div className="mt-2 text-xs text-muted-foreground">
+                                            {(() => {
+                                                const cs = entry.revision.changesSummary as { stepsAdded?: string[]; stepsRemoved?: string[]; stepsModified?: string[]; totalChanges?: number };
+                                                const parts: string[] = [];
+                                                if (cs.stepsAdded?.length) parts.push(`+${cs.stepsAdded.length} step${cs.stepsAdded.length > 1 ? 's' : ''}`);
+                                                if (cs.stepsRemoved?.length) parts.push(`-${cs.stepsRemoved.length} step${cs.stepsRemoved.length > 1 ? 's' : ''}`);
+                                                if (cs.stepsModified?.length) parts.push(`~${cs.stepsModified.length} modified`);
+                                                return parts.length ? parts.join(', ') : `${cs.totalChanges ?? 0} changes`;
+                                            })()}
+                                        </div>
+                                    )}
+                                </div>
+                            ))}
+                        </div>
+                    )}
+                </div>
+                <div className="flex justify-end gap-2 pt-3 flex-none">
+                    <DialogClose asChild>
+                        <Button variant="secondary">Close</Button>
+                    </DialogClose>
+                </div>
+            </DialogContent>
+        </Dialog>
+    );
+}

package/dist/dashboard/routes/pipelines/components/index.ts

@@ -0,0 +1,25 @@
+export { DryRunDialog } from './DryRunDialog';
+export type { DryRunDialogProps } from './DryRunDialog';
+
+export { VersionHistoryDialog } from './VersionHistoryDialog';
+export type { VersionHistoryDialogProps, TimelineEntry } from './VersionHistoryDialog';
+
+export { ValidationPanel } from './ValidationPanel';
+export type { ValidationPanelProps } from './ValidationPanel';
+// Re-export ValidationState from central types for convenience
+export type { ValidationState } from '../../../types';
+
+export { PipelineActionButtons } from './PipelineActionButtons';
+export type { PipelineActionButtonsProps } from './PipelineActionButtons';
+
+export { ReviewActionsPanel } from './ReviewActionsPanel';
+export type { ReviewActionsPanelProps } from './ReviewActionsPanel';
+
+export { PipelineWebhookInfo } from './PipelineWebhookInfo';
+export type { PipelineWebhookInfoProps } from './PipelineWebhookInfo';
+
+export { PipelineEditorToggle } from './PipelineEditorToggle';
+export type { PipelineEditorToggleProps, EditorMode } from './PipelineEditorToggle';
+
+export { PipelineFormFields } from './PipelineFormFields';
+export type { PipelineFormFieldsProps } from './PipelineFormFields';

package/dist/dashboard/routes/pipelines/hooks/index.ts

@@ -0,0 +1 @@
+export { usePipelineValidation } from './use-pipeline-validation';

package/dist/dashboard/routes/pipelines/hooks/use-pipeline-validation.ts

@@ -0,0 +1,114 @@
+import * as React from 'react';
+import { useMutation } from '@tanstack/react-query';
+import { api } from '@vendure/dashboard';
+import { validatePipelineDefinitionDocument } from '../../../hooks';
+import type { PipelineValidationResult, ValidationIssue } from '../../../types';
+import { getErrorMessage } from '../../../../shared';
+import type { ValidationState } from '../components';
+
+/** Debounce delay (ms) before triggering validation after definition changes. */
+const VALIDATION_DEBOUNCE_MS = 300;
+
+const EMPTY_VALIDATION: ValidationState = {
+    isValid: null,
+    count: 0,
+    issues: [],
+    warnings: [],
+};
+
+/**
+ * Parse the raw validation API response into a ValidationState.
+ */
+function parseValidationResult(out: PipelineValidationResult | undefined): ValidationState {
+    const issues: ValidationIssue[] = Array.isArray(out?.issues)
+        ? out.issues.map((i) => ({
+              message: i.message,
+              stepKey: i.stepKey ?? null,
+              reason: i.reason ?? null,
+              field: i.field ?? null,
+          }))
+        : [];
+
+    const warnings: ValidationIssue[] = Array.isArray(out?.warnings)
+        ? out.warnings.map((i) => ({
+              message: i.message,
+              stepKey: i.stepKey ?? null,
+              reason: i.reason ?? null,
+              field: i.field ?? null,
+          }))
+        : [];
+
+    return {
+        isValid: Boolean(out?.isValid),
+        count: issues.length,
+        issues,
+        warnings,
+    };
+}
+
+/**
+ * Hook for auto-validating a pipeline definition with debouncing.
+ *
+ * Uses React Query `useMutation` for the API call while preserving
+ * debounce (300ms) and race condition protection via a request counter.
+ *
+ * @param definition - The current pipeline definition to validate
+ * @returns Validation state and pending status
+ */
+export function usePipelineValidation(definition: unknown): {
+    validation: ValidationState;
+    validationPending: boolean;
+    setValidation: React.Dispatch<React.SetStateAction<ValidationState>>;
+} {
+    const [validation, setValidation] = React.useState<ValidationState>(EMPTY_VALIDATION);
+    const requestIdRef = React.useRef(0);
+
+    const validateMutation = useMutation({
+        mutationFn: async (def: unknown) => {
+            const res = await api.query(validatePipelineDefinitionDocument, {
+                definition: def,
+                level: 'FULL',
+            });
+            return res?.validateDataHubPipelineDefinition as PipelineValidationResult | undefined;
+        },
+    });
+
+    React.useEffect(() => {
+        if (!definition) {
+            setValidation(EMPTY_VALIDATION);
+            validateMutation.reset();
+            return;
+        }
+
+        const requestId = ++requestIdRef.current;
+
+        const timer = setTimeout(async () => {
+            try {
+                const out = await validateMutation.mutateAsync(definition);
+                if (requestId !== requestIdRef.current) return;
+                setValidation(parseValidationResult(out));
+            } catch (e) {
+                if (requestId !== requestIdRef.current) return;
+                setValidation({
+                    isValid: false,
+                    count: 1,
+                    issues: [
+                        {
+                            message: getErrorMessage(e),
+                        },
+                    ],
+                    warnings: [],
+                });
+            }
+        }, VALIDATION_DEBOUNCE_MS);
+
+        return () => {
+            clearTimeout(timer);
+        };
+        // validateMutation is intentionally excluded: including it would cause infinite
+        // re-triggers since useMutation returns a new object each render.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [definition]);
+
+    return { validation, validationPending: validateMutation.isPending, setValidation };
+}

package/dist/dashboard/routes/pipelines/index.ts

@@ -0,0 +1,4 @@
+export { pipelinesList } from './PipelinesList';
+export { pipelineDetail } from './PipelineDetail';
+export { importWizardPage } from './ImportWizardPage';
+export { exportWizardPage } from './ExportWizardPage';

package/dist/dashboard/routes/pipelines/utils/index.ts

@@ -0,0 +1 @@
+export { toVisualDefinition, toCanonicalDefinition, layoutDagNodes } from './pipeline-conversion';

package/dist/dashboard/routes/pipelines/utils/pipeline-conversion.ts

@@ -0,0 +1,261 @@
+/**
+ * Utility functions for converting between canonical (steps-based) and visual (nodes/edges-based)
+ * pipeline definitions.
+ */
+import type { PipelineDefinition } from '../../../../shared/types';
+import type { VisualPipelineDefinition, PipelineNode } from '../../../types';
+import { NODE_LAYOUT, mapStepTypeToCategory, mapCategoryToStepType } from '../../../constants';
+
+/**
+ * Calculate node levels in DAG based on edge connections.
+ * Nodes at the same level can run in parallel.
+ * Protected against cycles with max iteration limit.
+ */
+function calculateNodeLevels(
+    nodes: PipelineNode[],
+    edges: Array<{ source: string; target: string }>
+): Map<string, number> {
+    const levels = new Map<string, number>();
+    const incomingEdges = new Map<string, string[]>();
+    const outgoingEdges = new Map<string, string[]>();
+
+    for (const node of nodes) {
+        incomingEdges.set(node.id, []);
+        outgoingEdges.set(node.id, []);
+    }
+
+    for (const edge of edges) {
+        const incoming = incomingEdges.get(edge.target) ?? [];
+        incoming.push(edge.source);
+        incomingEdges.set(edge.target, incoming);
+
+        const outgoing = outgoingEdges.get(edge.source) ?? [];
+        outgoing.push(edge.target);
+        outgoingEdges.set(edge.source, outgoing);
+    }
+
+    const entryNodes = nodes.filter(n => (incomingEdges.get(n.id) ?? []).length === 0);
+    for (const node of entryNodes) {
+        levels.set(node.id, 0);
+    }
+
+    const queue = [...entryNodes.map(n => n.id)];
+    const maxIterations = nodes.length * edges.length + nodes.length;
+    let iterations = 0;
+
+    while (queue.length > 0 && iterations < maxIterations) {
+        iterations++;
+        const nodeId = queue.shift()!;
+        const currentLevel = levels.get(nodeId) ?? 0;
+
+        for (const targetId of outgoingEdges.get(nodeId) ?? []) {
+            const existingLevel = levels.get(targetId);
+            const newLevel = currentLevel + 1;
+
+            if (existingLevel === undefined || newLevel > existingLevel) {
+                levels.set(targetId, newLevel);
+                queue.push(targetId);
+            }
+        }
+    }
+
+    for (const node of nodes) {
+        if (!levels.has(node.id)) {
+            levels.set(node.id, 0);
+        }
+    }
+
+    return levels;
+}
+
+/**
+ * Auto-layout nodes in DAG format - parallel nodes stacked vertically.
+ */
+export function layoutDagNodes(def: VisualPipelineDefinition): VisualPipelineDefinition {
+    const nodes = def.nodes ?? [];
+    const edges = def.edges ?? [];
+
+    if (nodes.length === 0) {
+        return def;
+    }
+
+    const levels = calculateNodeLevels(nodes, edges);
+
+    const nodesByLevel = new Map<number, PipelineNode[]>();
+    for (const node of nodes) {
+        const level = levels.get(node.id) ?? 0;
+        const levelNodes = nodesByLevel.get(level) ?? [];
+        levelNodes.push(node);
+        nodesByLevel.set(level, levelNodes);
+    }
+
+    const levelValues = Array.from(levels.values());
+    const maxLevel = levelValues.length > 0 ? Math.max(...levelValues) : 0;
+    const repositionedNodes: PipelineNode[] = [];
+
+    for (let level = 0; level <= maxLevel; level++) {
+        const levelNodes = nodesByLevel.get(level) ?? [];
+        const count = levelNodes.length;
+        const centerY = NODE_LAYOUT.INITIAL_Y;
+        const startY = centerY - ((count - 1) * NODE_LAYOUT.SPACING_Y) / 2;
+
+        for (let i = 0; i < levelNodes.length; i++) {
+            const node = levelNodes[i];
+            repositionedNodes.push({
+                ...node,
+                position: {
+                    x: NODE_LAYOUT.INITIAL_X + level * NODE_LAYOUT.SPACING_X,
+                    y: startY + i * NODE_LAYOUT.SPACING_Y,
+                },
+            });
+        }
+    }
+
+    return {
+        ...def,
+        nodes: repositionedNodes,
+    };
+}
+
+/**
+ * Convert a canonical pipeline definition to a visual definition for the ReactFlow editor.
+ *
+ * @param def - The canonical or visual pipeline definition
+ * @returns A visual pipeline definition with nodes and edges
+ */
+export function toVisualDefinition(
+    def: PipelineDefinition | VisualPipelineDefinition | undefined
+): VisualPipelineDefinition {
+    if (!def) {
+        return {
+            nodes: [],
+            edges: [],
+            variables: {},
+            capabilities: undefined,
+            dependsOn: undefined,
+            trigger: undefined,
+        };
+    }
+
+    // Already in visual format
+    if ('nodes' in def && def.nodes) {
+        return def as VisualPipelineDefinition;
+    }
+
+    const canonicalDef = def as PipelineDefinition;
+    const steps = Array.isArray(canonicalDef.steps) ? canonicalDef.steps : [];
+
+    const nodes: PipelineNode[] = steps.map((step, i) => {
+        const id = String(step.key ?? `step-${i}`);
+        const category = mapStepTypeToCategory(step.type);
+        const adapterCode = step.config?.adapterCode;
+        const label = step.name || step.key || `Step ${i + 1}`;
+
+        return {
+            id,
+            type: category,
+            position: { x: 0, y: 0 },
+            data: {
+                label,
+                type: category,
+                adapterCode,
+                config: step.config ?? {},
+            },
+        };
+    });
+
+    const canonicalEdges = canonicalDef.edges;
+    let edges: Array<{ id: string; source: string; target: string }>;
+
+    if (Array.isArray(canonicalEdges) && canonicalEdges.length) {
+        edges = canonicalEdges.map((e, idx) => ({
+            id: String(e.id ?? `edge-${idx}`),
+            source: String(e.from),
+            target: String(e.to),
+        }));
+    } else {
+        edges = nodes.slice(1).map((n, i) => ({
+            id: `edge-${i}`,
+            source: nodes[i].id,
+            target: n.id,
+        }));
+    }
+
+    const visualDef: VisualPipelineDefinition = {
+        nodes,
+        edges,
+        variables: canonicalDef.context ?? {},
+        capabilities: canonicalDef.capabilities,
+        dependsOn: canonicalDef.dependsOn,
+        trigger: canonicalDef.trigger,
+    };
+
+    return layoutDagNodes(visualDef);
+}
+
+/**
+ * Convert a visual pipeline definition back to canonical format for storage.
+ *
+ * @param def - The visual or canonical pipeline definition
+ * @returns A canonical pipeline definition with steps and edges
+ */
+export function toCanonicalDefinition(
+    def: VisualPipelineDefinition | PipelineDefinition | undefined
+): PipelineDefinition {
+    if (!def) {
+        return { version: 1, steps: [] };
+    }
+
+    // Check if it's a visual definition with nodes
+    if ('nodes' in def && Array.isArray(def.nodes) && def.nodes.length > 0) {
+        const visualDef = def as VisualPipelineDefinition;
+        const steps = visualDef.nodes.map((node, idx) => {
+            const stepType = mapCategoryToStepType(node.data?.type);
+            const adapterCode =
+                node.data?.adapterCode || (node.data?.config?.adapterCode as string) || '';
+            const existingConfig = node.data?.config ?? {};
+            const { adapterCode: _, ...restConfig } = existingConfig;
+
+            return {
+                key: node.id ?? `step-${idx}`,
+                type: stepType,
+                name: node.data?.label,
+                config: {
+                    ...restConfig,
+                    adapterCode,
+                },
+            };
+        });
+
+        const edges = (visualDef.edges ?? []).map((e, i) => ({
+            id: e.id ?? `edge-${i}`,
+            from: e.source,
+            to: e.target,
+        }));
+
+        return {
+            version: 1,
+            steps,
+            edges,
+            context: visualDef.variables ?? {},
+            ...(visualDef.capabilities ? { capabilities: visualDef.capabilities } : {}),
+            ...(visualDef.dependsOn ? { dependsOn: visualDef.dependsOn } : {}),
+            ...(visualDef.trigger ? { trigger: visualDef.trigger } : {}),
+        };
+    }
+
+    // Check if it's already canonical format
+    if ('steps' in def && Array.isArray(def.steps)) {
+        const canonicalDef = def as PipelineDefinition;
+        return {
+            ...canonicalDef,
+            version:
+                typeof canonicalDef.version === 'number' && canonicalDef.version > 0
+                    ? canonicalDef.version
+                    : 1,
+        };
+    }
+
+    // Fallback: return default with any extra properties
+    return { version: 1, steps: [], ...def };
+}