🐛 Fix orgs/projects showing only one org due to project-scoped token

[Robdel12]

Summary

• vizzly orgs and vizzly projects only showed data from one org when run inside a linked project directory. The commands used loadConfig() which picks up the project-scoped token (from vizzly project link) before falling back to the user auth token. Project tokens are scoped to a single org, so the API only returned that org's data.
• Both commands now prefer the user auth token (from vizzly login) since listing orgs/projects are user-level operations. Falls back to config.apiKey when no user auth token exists (e.g., VIZZLY_TOKEN or --token).
• Fixed CLAUDE.md incorrectly referencing vitest as the test runner — the CLI uses Node's built-in test runner (node --test), not vitest. The vitest references were causing confusion across sessions.

Test plan

• Run vizzly login and verify all orgs are shown
• Run vizzly orgs inside a linked project directory — should now show all orgs, not just one
• Run vizzly projects inside a linked project directory — should now show projects across all orgs
• Run vizzly orgs without being logged in but with VIZZLY_TOKEN set — should still work via fallback
• Run npm test to verify all 1910 tests pass

[claude]

Code Review

This PR fixes a real bug where vizzly orgs and vizzly projects commands incorrectly showed data from only one organization when run inside a linked project directory. The fix is straightforward and well-motivated.

Strengths

Correct Problem Diagnosis:

• The issue is accurately identified: loadConfig() prioritizes project-scoped tokens (from vizzly project link) which are limited to a single organization
• The fix correctly prefers the user auth token for these user-level operations

Minimal, Focused Changes:

• Only modifies the two affected commands (orgs.js and projects.js)
• Changes are identical and symmetrical across both files
• Clear comments explain the rationale: "Prefer user auth token for orgs — project-scoped tokens only see one org"

Good Documentation:

• CLAUDE.md corrections fix misleading vitest references (the CLI actually uses Node's test runner)

Issues & Recommendations

1. Missing Token Expiration Handling

The commands use getAccessToken() which doesn't check token expiration. Looking at global-config.js:201-204:

export async function getAccessToken() {
  const auth = await getAuthTokens();
  return auth?.accessToken || null;
}

This returns expired tokens without validation. Compare with hasValidTokens() (global-config.js:175-195) which checks expiration with a 5-minute buffer.

Impact: Users might get cryptic API errors when their token is expired rather than helpful "Please run vizzly login" messages.

Recommendation: Either:

• Use hasValidTokens() before calling getAccessToken(), or
• Have getAccessToken() internally validate expiration

2. Missing Test Coverage

Neither orgs.js nor projects.js have test files:

• tests/commands/orgs.test.js doesn't exist
• tests/commands/projects.test.js doesn't exist

The test plan in the PR description shows manual testing, but automated tests would catch regressions.

Recommendation: Add integration tests covering:

• User logged in (user token exists) → shows all orgs/projects
• Inside linked project (project token exists) → still shows all orgs/projects due to the fix
• No auth at all → shows appropriate error
• Only VIZZLY_TOKEN env var set → works via fallback

3. Token Priority Logic Could Be More Explicit

The current code:

let token = (await getAccessToken()) || config.apiKey;

This works but requires understanding that config.apiKey might contain:

1. Environment variable (VIZZLY_TOKEN)
2. CLI flag (--token)
3. Project-scoped token (from vizzly project link)
4. User auth token (from vizzly login) — but this is now checked first

The fallback chain is spread across multiple files (config-loader.js, these commands), making it harder to reason about.

Recommendation (Optional): Consider a comment explaining the full fallback chain, e.g.:

// Prefer user auth token for listing orgs/projects (project tokens are org-scoped)
// Falls back to config.apiKey which may contain: VIZZLY_TOKEN, --token flag, or project token
let token = (await getAccessToken()) || config.apiKey;

4. Potential Edge Case: Both User Token and Project Token Present

When a user is logged in AND in a linked project directory:

1. getAccessToken() returns user token → used ✓
2. config.apiKey contains project token → ignored ✓

This works correctly, but it changes behavior from before. Previously, the project token would be used. Now the user token is always preferred.

Question: Could this cause issues if:

• User's auth token has different permissions than the project token?
• User is logged into a different account than the project was linked with?

This seems unlikely to cause real problems (user tokens should have broader permissions), but worth considering.

Code Quality

Positive:

• Consistent formatting and style
• Clear variable names
• Error messages guide users to solutions
• Comments explain non-obvious logic

No Security Concerns:

• Token handling looks appropriate
• No new vulnerabilities introduced
• Maintains existing secure patterns (tokens stored in ~/.vizzly/config.json with 0o600 permissions)

Performance:

• Negligible impact (one additional async call to getAccessToken())
• No N+1 queries or inefficient patterns

Summary

This is a solid bug fix with clear motivation and correct implementation. The main areas for improvement are:

1. Critical: Add token expiration validation to prevent cryptic errors
2. Important: Add automated tests to prevent regressions
3. Nice-to-have: Clearer documentation of token priority logic

The code is ready to merge with the understanding that token expiration handling should be addressed in a follow-up (or as part of this PR).

---

Recommendation: Approve with suggestion to add token expiration check and tests in follow-up PR.

[vizzly-testing]

Vizzly - Visual Test Results

CLI Reporter - 9 changes need review

Status	Count
Passed	10
Changed	9
Auto-approved	10

Changes needing review (9)

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

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

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

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

viewer-overlay-mode · Firefox · 1920×1080 · 5.6% diff

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

...and 3 more in Vizzly.

Review changes

CLI TUI - 1 change needs review

Status	Count
Changed	1
Auto-approved	4

Changes needing review (1)

vizzly-tdd-help · 1202×578 · 14.2% diff

Review changes

---

_{fix/user-token-for-orgs-projects · f772e010}