Skip to content

feat(#563): graceful setup experience for unconfigured projects - #573

Merged
xsovad06 merged 6 commits into
mainfrom
feat/issue-563
Jul 31, 2026
Merged

xsovad06 merged 6 commits into
mainfrom
feat/issue-563

Conversation

@xsovad06

Copy link
Copy Markdown
Owner

Summary

  • Fixed JavaScript temporal dead zone crash on supervisor page caused by EPIC_BADGE_WIDTH being referenced before declaration
  • Added graceful setup experience for unconfigured projects with configuration guidance and one-click label creation
  • Implemented label audit and creation API endpoints with parallel request handling and error recovery

Changes

Supervisor page (supervisor.html)

  • Moved EPIC_BADGE_WIDTH constant declaration before first use (line 842 → 835) to fix TDZ crash affecting any project with priority labels
  • Added setup prompt UI when graph is empty or adapter not configured, with links to settings and label management
  • Setup prompt detects missing GitHub/Jira configuration and provides actionable next steps

Label management API (routers/settings.py)

  • Added _REQUIRED_LABELS constant defining 24 SOVA labels (type, priority, area, agent state, review verdict)
  • Implemented GET /settings/labels/audit endpoint to detect missing labels via GitHub CLI
  • Implemented POST /settings/labels/create endpoint with parallel creation (semaphore limit: 5), comprehensive error handling, and truncated error reporting
  • Added _validate_github_config() helper rejecting Jira projects (label operations GitHub-only for now)

Settings UI (settings.html)

  • Added "Labels" section below "Operations Persona" with audit and create buttons
  • Shows missing label count and names after audit
  • Displays creation results with success count and error details (max 10 errors shown, truncated to 200 chars each)
  • Error messaging for GitHub CLI unavailability

Review guidance

  • TDZ fix: verify EPIC_BADGE_WIDTH declaration now precedes all references (check lines 835 vs 842, 858)
  • Setup prompt logic: confirm empty graph and unconfigured adapter both trigger the prompt correctly
  • Label creation safety: parallel creation uses semaphore to avoid rate limits; error truncation prevents unbounded responses
  • GitHub-only constraint: Jira label management deferred (validation blocks Jira projects from using label endpoints)

Test plan

  • Tested supervisor page on unconfigured project (no crash, setup prompt shown)
  • Tested supervisor page on project with priority labels (no TDZ crash)
  • Tested label audit on SOVA repo (returns missing labels correctly)
  • Tested label creation flow end-to-end (audit → create → verify in GitHub)
  • Verified error handling for missing GitHub CLI and authentication failures

Closes #563

@xsovad06 xsovad06 self-assigned this Jul 31, 2026
@coderabbitai

coderabbitai Bot commented Jul 31, 2026 •

Copy link
Copy Markdown

Review Change Stack

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 4f67a76c-80ce-4bd5-be23-c843be4193b9

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review

Walkthrough

Adds GitHub label audit and creation endpoints to the settings router with matching UI in settings.html, using GitHub CLI for label diffing and creation with concurrency control. Also fixes supervisor graph node-selection persistence, adds a 503 setup-required panel, and centralizes epic badge dimension constants.

Changes

GitHub Label Management

Layer / File(s) Summary
Label audit and creation endpoints
sova/dashboard/routers/settings.py
Adds _REQUIRED_LABELS (22 labels), _validate_github_config(), GET /settings/labels/audit to diff repo labels via GitHub CLI, and POST /settings/labels/create to create missing labels in parallel (concurrency 5) with error truncation and caps.
Label audit and creation UI
sova/dashboard/templates/settings.html
Adds a GitHub Labels card, loadLabelsStatus() wired into config loading, and createMissingLabels() with loading state, toasts, and retry handling.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Supervisor Graph Fixes

Layer / File(s) Summary
Graph state, error handling, and badge rendering fixes
sova/dashboard/templates/supervisor.html
Moves _selectedNodeId to shared graph state so selection persists across renders, replaces generic 503 error with a setup-required panel and settings link, and centralizes epic badge width/height constants with height increased from 14 to 16 pixels.

Estimated code review effort: 2 (Simple) | ~12 minutes

Possibly related PRs

  • xsovad06/sova#462: Modifies the same supervisor.html dependency graph visualization, including state handling and error handling for load failures.
  • xsovad06/sova#559: Modifies epic node rendering in supervisor.html, related to the epic badge dimension changes here.
  • xsovad06/sova#475: Modifies the same sova/dashboard/templates/settings.html file, though for unrelated settings deep-link logic.

Suggested reviewers: dsova06

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly summarizes the primary graceful setup changes for unconfigured projects.
Description check ✅ Passed The description explains the changes, testing, and issue linkage, but it omits the required Type of Change and Checklist sections.
Linked Issues check ✅ Passed The changes address issue #563 by fixing the graph crash, adding setup guidance, and providing GitHub label audit and creation support.
Out of Scope Changes check ✅ Passed The supervisor, settings API, and settings UI changes directly support the objectives in issue #563.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

coderabbitai[bot]
coderabbitai Bot previously requested changes Jul 31, 2026

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 6

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@sova/dashboard/routers/settings.py`:
- Around line 301-448: Add tests covering the new audit_labels and
create_missing_labels endpoints, mocking sova.utils.shell.run and related
GitHub/config dependencies. Exercise missing GitHub configuration (400),
unavailable CLI, malformed JSON, invalid label colors, permission-denied
creation failures, and truncation at _MAX_LABEL_ERRORS, while verifying async
behavior and response payloads.
- Around line 369-379: Extract the audit and missing-label computation from
audit_labels() into a private helper that accepts the already loaded cfg and
returns the missing-labels result. Update audit_labels() to load and validate
cfg once before calling the helper, and update create_missing_labels() to pass
its existing cfg directly instead of calling audit_labels(), preserving the
current error handling and label-creation behavior.
- Around line 84-97: Import ProjectConfig from sova.config.models and update the
cfg parameter of _validate_github_config to use the ProjectConfig type hint,
preserving the existing validation logic and return annotation.
- Around line 316-331: Update audit_labels around the run("gh", ...) call to
catch FileNotFoundError raised when the GitHub CLI is unavailable, returning
{"error": "GitHub CLI not available or not authenticated", "missing": []}
instead of propagating the exception. Preserve the existing result.success and
stderr handling for commands that return a ShellResult.

In `@sova/dashboard/templates/supervisor.html`:
- Around line 406-410: Update the “Setup Required” panel in the supervisor
template to use generic project-configuration guidance rather than asserting
that the task source adapter is missing. Align the message with the HTTP 503
`_ConfigError` response from the dependencies router, covering malformed or
unavailable project configuration without selecting a specific adapter cause.
- Around line 417-419: Update the non-503 error branch in loadGraph() to clear
errorEl’s existing contents before setting the generic HTTP failure message,
ensuring stale “Setup Required” heading and link markup is removed while
preserving the current paragraph text.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 9d08e050-bf62-4ebe-aaed-4a324ecdb497

📥 Commits

Reviewing files that changed from the base of the PR and between 8fef615 and e622033.

📒 Files selected for processing (3)
  • sova/dashboard/routers/settings.py
  • sova/dashboard/templates/settings.html
  • sova/dashboard/templates/supervisor.html

Comment thread sova/dashboard/routers/settings.py Resolved
Comment thread sova/dashboard/routers/settings.py Resolved
Comment thread sova/dashboard/routers/settings.py Resolved
Comment thread sova/dashboard/routers/settings.py Resolved

@xsovad06 xsovad06 left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PR Summary

This PR by xsovad06 adds graceful setup experience for unconfigured SOVA projects with 7 commits, 768 additions, and 10 deletions. It fixes a JavaScript temporal dead zone crash on the supervisor page, adds a setup guidance panel for 503 errors, and implements GitHub label audit and creation endpoints with comprehensive test coverage.

Findings

[HIGH] Correctness: FileNotFoundError not caught in label audit
Location: sova/dashboard/routers/settings.py:307
Problem: asyncio.create_subprocess_exec raises FileNotFoundError when gh is not installed, bypassing the ShellResult return path. The audit endpoint returns a 500 with the raw subprocess exception instead of the graceful "GitHub CLI not available or not authenticated" message at line 312.
Suggestion: Wrap the await run() call in a try/except block that catches FileNotFoundError and returns the error dict early:

try:
    result = await run("gh", "label", "list", "--repo", cfg.github_repo, "--json", "name", env=env)
except FileNotFoundError:
    return {"error": "GitHub CLI not available or not authenticated"}

[HIGH] Performance: Duplicate config loading and audit in create_missing_labels
Location: sova/dashboard/routers/settings.py:426-431
Problem: create_missing_labels() loads config at line 427, validates it at line 428, then calls _fetch_existing_labels(cfg) at line 431. But _fetch_existing_labels is also called by audit_labels(), which independently loads config and validates again. This results in two load_config() calls, two _validate_github_config() calls, and two gh label list API roundtrips whenever the create endpoint is used (the audit runs first from the UI).
Suggestion: Extract the audit and missing-label computation from audit_labels() into a private helper _compute_missing_labels(cfg) that accepts the already-loaded config and returns the missing-labels result. Have audit_labels() load config once and call the helper. Have create_missing_labels() pass its existing cfg directly to the helper instead of calling _fetch_existing_labels(). This eliminates the duplicate work while preserving the same error handling and response structure.

[MEDIUM] Consistency: Missing ProjectConfig type hint
Location: sova/dashboard/routers/settings.py:84
Problem: The cfg parameter of _validate_github_config is untyped. The function receives a project configuration object and has a return type hint, but the parameter is plain cfg.
Suggestion: Import ProjectConfig from sova.config.models and add the type hint: def _validate_github_config(cfg: ProjectConfig) -> None:.

[MEDIUM] Correctness: 503 setup panel assumes task source adapter is missing
Location: sova/dashboard/templates/supervisor.html:408-409
Problem: The setup panel text says "Project configuration is unavailable. Check your settings to ensure the project is properly configured." But the HTTP 503 _ConfigError response from dependencies.py lines 199-227 can be raised for any malformed configuration, not just a missing task source adapter. If the config file has syntax errors or other validation failures, this panel reports the wrong cause.
Suggestion: Use more generic project-configuration guidance that doesn't assert a specific failure mode. The current message is already fairly generic, so this is a minor concern. Alternatively, parse the 503 response detail to identify the specific error type and show a targeted message.

[MEDIUM] Correctness: Non-503 error path doesn't clear stale HTML
Location: sova/dashboard/templates/supervisor.html:418
Problem: When loadGraph() receives a non-503 bad response, it only updates errorEl.innerHTML with a generic failure text. If the previous errorEl.innerHTML contained the "Setup Required" markup (heading, link, icon), the non-503 path doesn't explicitly clear it first. While innerHTML = assignment replaces the content, it's safer to explicitly clear to avoid any edge cases where previous markup persists.
Suggestion: Explicitly clear before setting the generic failure text: errorEl.innerHTML = ''; errorEl.innerHTML = \

Failed to load graph: HTTP ${res.status}

`;`. Or more concisely, ensure the assignment fully replaces the content (which it does in this case, so this is a low-priority nitpick).

Confirmed Bot Findings

Agree with CodeRabbit on sova/dashboard/routers/settings.py:84: Add ProjectConfig type hint. See my MEDIUM finding above.

Agree with CodeRabbit on sova/dashboard/routers/settings.py:307: Handle FileNotFoundError. See my HIGH finding above.

Agree with CodeRabbit on sova/dashboard/routers/settings.py:379: Avoid re-running audit in create_missing_labels. See my HIGH finding above.

Agree with CodeRabbit on sova/dashboard/templates/supervisor.html:408: Generic 503 message assumption. See my MEDIUM finding above.

Agree with CodeRabbit on sova/dashboard/templates/supervisor.html:418: Clear errorEl before non-503 errors. See my MEDIUM finding above.

Disagree with CodeRabbit on sova/dashboard/routers/settings.py:458: Tests WERE added. Commits b255304 and 3c0f342 added 11 comprehensive tests covering audit_labels, create_missing_labels, error cases, truncation, and all edge cases. The bot's comment about missing tests is incorrect.

Verdict

Request changes: two HIGH findings (FileNotFoundError not caught, duplicate config loading) and three MEDIUM findings (missing type hint, 503 message assumption, stale HTML not cleared) must be addressed before merge. The HIGH findings affect correctness and performance; the MEDIUM findings improve code quality and error handling clarity.

(Posted as comment: GitHub does not allow self-reviews with formal approval/rejection state.)

What's Done Well

Excellent test coverage with 11 new tests covering all edge cases including auth failures, permission denied, error truncation, and mixed success/failure scenarios. The tests brought SonarCloud coverage from 10.6% to 93.5% on new code.

Good use of async concurrency control with asyncio.Semaphore to limit parallel label creation requests, preventing rate limit issues while maintaining performance.

Clean separation of concerns with helper functions _fetch_existing_labels, _create_single_label, and _build_label_response extracted to module level for reusability and testability.

xsovad06 added 6 commits July 31, 2026 11:09
Add two new REST endpoints to settings router for managing GitHub labels:
- GET /settings/labels/audit: checks for missing SOVA required labels
- POST /settings/labels/create: creates all missing labels in parallel

Includes validation helpers, error handling with truncation, and concurrency
limits to prevent rate limiting. Supports graceful degradation when GitHub
CLI is unavailable or not authenticated.
Extract _compute_missing_labels helper to eliminate duplicate logic between
audit and create endpoints. Add type hint to _validate_github_config and
FileNotFoundError handling to _fetch_existing_labels for better error recovery.

Reduces cognitive complexity score from 12 to 7.
Add interactive card to settings page showing:
- Missing label count with color-coded list
- Create button to batch-create missing labels
- Success/error toast notifications
- Auto-refresh on completion

Integrates with new /settings/labels/audit and /settings/labels/create endpoints.
…rror paths

Replace querySelector-based error message updates with innerHTML assignment
to prevent null reference errors when error element structure changes.
Improves HTTP 503 handling with styled setup guidance card.
Replace generic "Project configuration is unavailable" with actionable
message explaining that task source adapter needs configuration.
Guides users to configure GitHub or Jira integration.
… endpoints

Add 14 test cases covering:
- GitHub adapter validation (not GitHub, missing repo)
- GitHub CLI availability and authentication
- JSON parsing errors
- Permission denied scenarios
- Invalid color format validation
- Error truncation (max 10 errors)
- Message length truncation (max 200 chars)
- Partial success handling
- Success path with no missing labels

Achieves full coverage of _fetch_existing_labels, _create_single_label,
_build_label_response, _compute_missing_labels, audit_labels, and
create_missing_labels endpoints.
@sonarqubecloud

Copy link
Copy Markdown

@xsovad06
xsovad06 dismissed coderabbitai[bot]’s stale review July 31, 2026 09:22

Findings addressed in latest push.

@xsovad06
xsovad06 merged commit 02e0762 into main Jul 31, 2026
8 checks passed
@xsovad06
xsovad06 deleted the feat/issue-563 branch July 31, 2026 11:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(supervisor): graceful setup experience for unconfigured projects

1 participant