✨ Add --org flag to builds and comparisons commands

[Robdel12]

Summary

When two projects across different orgs share the same slug (e.g., "storybook"), vizzly builds --project storybook returns builds from both projects with no way to tell them apart. This adds an --org flag to disambiguate.

• Add --org <slug> option to builds and comparisons commands
• Pass organization query parameter through to the API
• Include organization in the searchComparisons endpoint params
• Add tests for org filter passthrough on both commands
• Update help text examples showing the new flag

vizzly builds --project storybook --org gq
vizzly comparisons --name "Button" --project storybook --org my-org

Test plan

• All 1,881 existing tests pass
• New tests verify org filter is passed to API for both commands
• Lint passes
• Verify vizzly builds --help shows --org option
• Verify vizzly comparisons --help shows --org option
• Test against live API with --project storybook --org <slug> to confirm scoped results

[claude]

Code Review

This is a clean, well-executed feature addition that follows existing patterns in the codebase. The implementation is consistent and properly tested.

✅ Strengths

1. Consistent with existing patterns

• The --org flag follows the same structure as --project, --branch, etc.
• Uses the established buildQueryParams() helper in getBuilds (src/api/endpoints.js:48)
• Uses buildEndpointWithParams() consistently in searchComparisons (src/api/endpoints.js:246)
• Proper conditional parameter handling: if (organization) params.organization = organization;

2. Thorough test coverage

• Added tests for both builds and comparisons commands
• Tests verify the filter is correctly passed through to the API layer
• Follows existing test patterns with mock injection and assertion on captured filters

3. Good documentation

• Updated help text with practical examples showing the new flag
• Examples clearly demonstrate the use case (disambiguating projects with same slug)
• PR description explains the motivation well

4. Code quality

• No security concerns (just passing a filter parameter)
• No performance impact (single optional query parameter)
• Follows gitmoji convention (✨ for new feature)
• No unnecessary changes or over-engineering

🔍 Minor observations

1. Naming consistency
The option is named --org but the internal parameter is organization. This is actually good UX (shorter flag for CLI users) and the mapping is clear:

• CLI: --org <slug>
• Internal/API: organization

This matches other patterns in the codebase where CLI flags are often abbreviated.

2. No validation on the org parameter
The code doesn't validate the org slug format, but this is consistent with how --project, --branch, etc. are handled. The API will return appropriate errors for invalid values, which is the right place for this validation.

3. JSDoc update
The searchComparisons function's JSDoc comment at src/api/endpoints.js:232 mentions "Optional filters (branch, limit, offset)" but doesn't list project or the new organization. Consider updating this in a future refactor (not blocking for this PR).

📋 Test plan completion

The PR checklist shows two items as incomplete:

• Verify vizzly builds --help shows --org option
• Verify vizzly comparisons --help shows --org option

These can be verified with:

npm run build
./bin/vizzly builds --help | grep -A1 "org"
./bin/vizzly comparisons --help | grep -A1 "org"

✅ Recommendation

Approve and merge. This is a straightforward feature addition that solves a real problem (disambiguating projects with identical slugs across different orgs). The implementation is solid, well-tested, and follows all project conventions.

The changes are minimal (58 additions, 2 deletions across 6 files), reducing risk. All existing tests pass, and new tests provide good coverage of the feature.

[vizzly-testing]

Vizzly - Visual Test Results

CLI Reporter - 10 changes need review

Status	Count
Passed	9
Changed	10
Auto-approved	9

Changes needing review (10)

filter-failed-only · Firefox · 1920×1080 · 0.2% diff

fullscreen-viewer · Firefox · 1920×1080 · 0.1% diff

bulk-accept-dialog · Firefox · 1920×1080 · 10.4% diff

viewer-toggle-mode · Firefox · 1920×1080 · 0.1% diff

viewer-slide-mode · Firefox · 1920×1080 · 0.5% diff

viewer-zoomed-100 · Firefox · 1920×1080 · 0.5% diff

...and 4 more in Vizzly.

Review changes

CLI TUI - Processing...

Build in progress...

---

_{feat/org-filter-builds-comparisons · 6dbe3a8f}