fix: resolve issues #248 and #249 - settings validation and addConnection errors

Issue #248: Settings validation error
- Add callerPolicy to workflowSettingsSchema to support valid n8n property
- Implement settings filtering in cleanWorkflowForUpdate() to prevent API errors
- Filter out UI-only properties like timeSavedPerExecution
- Preserve only whitelisted settings properties
- Add comprehensive unit tests for settings filtering

Issue #249: Misleading error messages for addConnection
- Enhanced validateAddConnection() with parameter validation
- Detect common mistakes like using sourceNodeId/targetNodeId instead of source/target
- Provide helpful error messages with correct parameter names
- List available nodes when source/target not found
- Add unit tests for all error scenarios

All tests passing (183 total):
- n8n-validation: 73/73 tests (100% coverage)
- workflow-diff-engine: 110/110 tests

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

src/services/n8n-validation.ts

@@ -45,6 +45,7 @@ export const workflowSettingsSchema = z.object({
   saveExecutionProgress: z.boolean().default(true),
   executionTimeout: z.number().optional(),
   errorWorkflow: z.string().optional(),
+  callerPolicy: z.enum(['any', 'workflowsFromSameOwner', 'workflowsFromAList']).optional(),
 });
 
 // Default settings for workflow creation
@@ -95,14 +96,17 @@ export function cleanWorkflowForCreate(workflow: Partial<Workflow>): Partial<Wor
 
 /**
  * Clean workflow data for update operations.
- * 
+ *
  * This function removes read-only and computed fields that should not be sent
  * in API update requests. It does NOT add any default values or new fields.
- * 
+ *
  * Note: Unlike cleanWorkflowForCreate, this function does not add default settings.
  * The n8n API will reject update requests that include properties not present in
  * the original workflow ("settings must NOT have additional properties" error).
- * 
+ *
+ * Settings are filtered to only include whitelisted properties to prevent API
+ * errors when workflows from n8n contain UI-only or deprecated properties.
+ *
  * @param workflow - The workflow object to clean
  * @returns A cleaned partial workflow suitable for API updates
  */
@@ -129,6 +133,30 @@ export function cleanWorkflowForUpdate(workflow: Workflow): Partial<Workflow> {
     ...cleanedWorkflow
   } = workflow as any;
 
+  // Filter settings to only include valid properties (Issue #248 fix)
+  // Prevents "settings must NOT have additional properties" API errors
+  if (cleanedWorkflow.settings) {
+    const allowedSettingsKeys = [
+      'executionOrder',
+      'timezone',
+      'saveDataErrorExecution',
+      'saveDataSuccessExecution',
+      'saveManualExecutions',
+      'saveExecutionProgress',
+      'executionTimeout',
+      'errorWorkflow',
+      'callerPolicy',
+    ];
+
+    const filteredSettings: any = {};
+    for (const key of allowedSettingsKeys) {
+      if (key in cleanedWorkflow.settings) {
+        filteredSettings[key] = cleanedWorkflow.settings[key];
+      }
+    }
+    cleanedWorkflow.settings = filteredSettings;
+  }
+
   return cleanedWorkflow;
 }
 

src/services/workflow-diff-engine.ts

@@ -362,16 +362,36 @@ export class WorkflowDiffEngine {
 
   // Connection operation validators
   private validateAddConnection(workflow: Workflow, operation: AddConnectionOperation): string | null {
+    // Check for common parameter mistakes (Issue #249)
+    const operationAny = operation as any;
+    if (operationAny.sourceNodeId || operationAny.targetNodeId) {
+      const wrongParams: string[] = [];
+      if (operationAny.sourceNodeId) wrongParams.push('sourceNodeId');
+      if (operationAny.targetNodeId) wrongParams.push('targetNodeId');
+
+      return `Invalid parameter(s): ${wrongParams.join(', ')}. Use 'source' and 'target' instead. Example: {type: "addConnection", source: "Node Name", target: "Target Name"}`;
+    }
+
+    // Check for missing required parameters
+    if (!operation.source) {
+      return `Missing required parameter 'source'. The addConnection operation requires both 'source' and 'target' parameters. Check that you're using 'source' (not 'sourceNodeId').`;
+    }
+    if (!operation.target) {
+      return `Missing required parameter 'target'. The addConnection operation requires both 'source' and 'target' parameters. Check that you're using 'target' (not 'targetNodeId').`;
+    }
+
     const sourceNode = this.findNode(workflow, operation.source, operation.source);
     const targetNode = this.findNode(workflow, operation.target, operation.target);
-    
+
     if (!sourceNode) {
-      return `Source node not found: ${operation.source}`;
+      const availableNodes = workflow.nodes.map(n => n.name).join(', ');
+      return `Source node not found: "${operation.source}". Available nodes: ${availableNodes}`;
     }
     if (!targetNode) {
-      return `Target node not found: ${operation.target}`;
+      const availableNodes = workflow.nodes.map(n => n.name).join(', ');
+      return `Target node not found: "${operation.target}". Available nodes: ${availableNodes}`;
     }
-    
+
     // Check if connection already exists
     const sourceOutput = operation.sourceOutput || 'main';
     const existing = workflow.connections[sourceNode.name]?.[sourceOutput];
@@ -383,7 +403,7 @@ export class WorkflowDiffEngine {
         return `Connection already exists from "${sourceNode.name}" to "${targetNode.name}"`;
       }
     }
-    
+
     return null;
   }