fix(websets): validate import/scope conflicts and improve CLI help

[benjaminjackson]

Summary

Fixes an issue where users could specify the same import/webset ID in both top-level :import and search[:scope] parameters, causing a 400 error from the API. Adds client-side validation to catch this early with a clear error message.

Also significantly improves CLI help text by adding JSON format examples and clarifying the distinction between :import (data loading) and scope (search filtering).

Changes

Validation

• Added validate_no_duplicate_ids_in_import_and_scope! to CreateValidator
• Detects when same source ID appears in both :import and search[:scope]
• Raises clear ArgumentError with the conflicting IDs listed

Tests

• Added test for duplicate import IDs (should raise error)
• Added test for duplicate webset IDs (should raise error)
• Added test for different IDs (should pass)
• Added test for import without scope (should pass)
• Added test for scope without import (should pass)

CLI Help Text Improvements

webset-create:

• Clarified :import loads data (for enrichment) but doesn't filter searches
• Clarified search.scope filters searches to specific sources
• Added JSON format examples for all parameters
• Added JSON Format Details section with scope/relationship examples
• Added warning about duplicate ID constraint
• Added example showing scoped search within import
• Added example showing import + unscoped search (different datasets)

webset-search-create:

• Added JSON format examples for --criteria, --exclude, --scope, --metadata
• Documented relationship object structure for hop searches
• Clarified --behavior defaults (override with scope, append otherwise)
• Added scoped search example
• Added hop search example with relationship

Test Results

171 runs, 355 assertions, 0 failures, 0 errors, 0 skips

Files Changed

• lib/exa/services/websets/create_validator.rb - validation logic
• test/services/websets/create_validator_test.rb - comprehensive test coverage
• exe/exa-ai-webset-create - improved help text with formats and warnings
• exe/exa-ai-webset-search-create - improved help text with formats and examples

🤖 Generated with Claude Code