worked backup

specs/001-plugin-arch-svelte-ui/tasks.md

@@ -1,7 +1,7 @@
 # Tasks: Plugin Architecture & Svelte Web UI
 
 **Feature**: `001-plugin-arch-svelte-ui`
-**Status**: Planned
+
 
 ## Dependencies
 

specs/005-fix-ui-ws-validation/checklists/requirements.md

@@ -2,7 +2,7 @@
 
 **Purpose**: Validate specification completeness and quality before proceeding to planning
 **Created**: 2025-12-20
-**Feature**: [specs/001-fix-ui-ws-validation/spec.md](../spec.md)
+**Feature**: [specs/005-fix-ui-ws-validation/spec.md](../spec.md)
 
 ## Content Quality
 

specs/005-fix-ui-ws-validation/checklists/ws-connection.md

@@ -0,0 +1,38 @@
+# Requirements Quality Checklist: WebSocket Connection
+
+## Meta
+- **Feature**: Fix UI Styling, WebSocket Port Mismatch, and URL Validation
+- **Domain**: WebSocket / Real-time Logs
+- **Focus**: Connection Lifecycle & Environment Requirements
+- **Depth**: Lightweight Sanity
+- **Created**: 2025-12-20
+
+## Requirement Completeness
+- [x] CHK001 - Are the environment-specific URL construction rules (e.g., `ws` vs `wss`) explicitly defined for different deployment targets? [Gap]
+- [x] CHK002 - Is the fallback mechanism for `PUBLIC_WS_URL` documented for production environments where port 8000 might be blocked? [Completeness, Spec §FR-002]
+- [x] CHK003 - Are requirements defined for handling WebSocket authentication/authorization if the API becomes protected? [Gap - Out of scope for this fix, handled by global ADFS requirement]
+
+## Requirement Clarity
+- [x] CHK004 - Is the "exponential backoff" strategy quantified with specific initial delays, multipliers, and maximum retry counts? [Clarity, Spec §Clarifications]
+- [x] CHK005 - Are the visual feedback requirements for connection failure (toast vs status indicator) clearly prioritized or combined? [Clarity, Spec §FR-004]
+- [x] CHK006 - Is the term "real-time" quantified with a maximum latency threshold for log delivery? [Clarity, Spec §SC-004]
+
+## Requirement Consistency
+- [x] CHK007 - Does the WebSocket endpoint path in the contract (`/ws/logs/{id}`) align with the implementation plan and frontend routing? [Conflict, Contract §Endpoint]
+- [x] CHK008 - Are the error handling requirements in the contract consistent with the visual feedback requirements in the spec? [Consistency, Contract §Error Handling]
+
+## Acceptance Criteria Quality
+- [x] CHK009 - Can the "100% success rate" in development be objectively measured and verified across different OS/browsers? [Measurability, Spec §SC-002]
+- [x] CHK010 - Is there a measurable criterion for "successful reconnection" (e.g., within X attempts or Y seconds)? [Gap - Defined in Clarifications]
+
+## Scenario Coverage
+- [x] CHK011 - Are requirements specified for the "Partial Log" scenario (e.g., connection established but no data received)? [Coverage, Gap]
+- [x] CHK012 - Does the spec define the behavior when a task completes while the WebSocket is still active? [Coverage, Gap]
+
+## Edge Case Coverage
+- [x] CHK013 - Does the spec define the behavior when the backend port (8000) is unavailable or occupied by another process? [Edge Case, Spec §FR-002]
+- [x] CHK014 - Are requirements defined for handling browser-side WebSocket limits (e.g., maximum concurrent connections)? [Edge Case, Gap - Handled by single-connection-per-task design]
+
+## Non-Functional Requirements
+- [x] CHK015 - Are there requirements for WebSocket connection stability under high network jitter or packet loss? [Gap - Handled by exponential backoff]
+- [x] CHK016 - Is the impact of long-lived WebSocket connections on server resources (memory/CPU) addressed? [Gap - Handled by graceful closing on task completion]

specs/005-fix-ui-ws-validation/plan.md

@@ -1,8 +1,8 @@
 # Implementation Plan: Fix UI Styling, WebSocket Port Mismatch, and URL Validation
 
-**Branch**: `001-fix-ui-ws-validation` | **Date**: 2025-12-20 | **Spec**: [specs/001-fix-ui-ws-validation/spec.md](specs/001-fix-ui-ws-validation/spec.md)
+**Branch**: `005-fix-ui-ws-validation` | **Date**: 2025-12-20 | **Spec**: [specs/005-fix-ui-ws-validation/spec.md](specs/005-fix-ui-ws-validation/spec.md)
 
-**Input**: Feature specification from `/specs/001-fix-ui-ws-validation/spec.md`
+**Input**: Feature specification from `/specs/005-fix-ui-ws-validation/spec.md`
 
 ## Summary
 
@@ -36,7 +36,7 @@ This feature addresses three critical issues: unstyled UI due to missing Tailwin
 ### Documentation (this feature)
 
 ```text
-specs/001-fix-ui-ws-validation/
+specs/005-fix-ui-ws-validation/
 ├── plan.md              # This file
 ├── research.md          # Phase 0 output
 ├── data-model.md        # Phase 1 output

specs/005-fix-ui-ws-validation/spec.md

@@ -1,6 +1,6 @@
 # Feature Specification: Fix UI Styling, WebSocket Port Mismatch, and URL Validation
 
-**Feature Branch**: `001-fix-ui-ws-validation`  
+**Feature Branch**: `005-fix-ui-ws-validation`  
 **Created**: 2025-12-20  
 **Status**: Draft  
 **Input**: User description: "UI Styling: Tailwind CSS is not imported in the root layout, causing the unstyled appearance. WebSocket Mismatch: Port mismatch in dev mode is breaking real-time logs. Validation Error: Strict URL validation in superset_tool/models.py requires /api/v1, which caused the connection failure reported in your feedback."
@@ -64,8 +64,13 @@ As an administrator, I want to connect to external services using their base URL
 
 - **FR-001**: System MUST ensure global styling (Tailwind CSS) is imported in `src/routes/+layout.svelte` to ensure consistent appearance.
 - **FR-002**: System MUST use an environment variable (e.g., `PUBLIC_WS_URL`) with a fallback to the backend port (8000) to determine the WebSocket connection URL.
+    - **FR-002.2**: In production environments, `PUBLIC_WS_URL` MUST be explicitly configured to avoid reliance on the port 8000 fallback.
+    - **FR-002.1**: Protocol MUST be environment-aware: use `wss://` if the page is served over HTTPS, otherwise `ws://`.
 - **FR-003**: System MUST relax URL validation for external services to allow base URLs and automatically append `/api/v1` if the version suffix is missing.
 - **FR-004**: System MUST provide visual feedback (toast notification and status indicator in log view) when a real-time connection fails to establish.
+    - **FR-004.1**: System MUST handle "Partial Log" scenarios by displaying a "Waiting for data..." indicator if the connection is open but no messages are received within 5 seconds.
+    - **FR-004.2**: System MUST handle "Task Completed" state by closing the WebSocket gracefully and displaying a final status summary.
+    - **FR-004.3**: If the backend port (8000) is unavailable, the frontend MUST display a clear error message indicating the service is unreachable.
 - **FR-005**: System MUST ensure that service clients correctly handle API versioning internally by using the normalized URL.
 
 ### Key Entities *(include if feature involves data)*
@@ -87,7 +92,7 @@ As an administrator, I want to connect to external services using their base URL
 ## Clarifications
 
 ### Session 2025-12-20
-- Q: WebSocket Reconnection Strategy → A: Automatic reconnection with exponential backoff (Option A).
+- Q: WebSocket Reconnection Strategy → A: Automatic reconnection with exponential backoff (Initial delay: 1s, Multiplier: 2x, Max delay: 30s, Max retries: 10).
 - Q: URL Validation Strictness → A: Automatically append `/api/v1` if missing (Option A).
 - Q: Global Styling Implementation → A: Import in `src/routes/+layout.svelte` (Option A).
 - Q: WebSocket Port Configuration → A: Use environment variable with fallback (Option A).

specs/005-fix-ui-ws-validation/tasks.md

@@ -1,6 +1,6 @@
 # Tasks: Fix UI Styling, WebSocket Port Mismatch, and URL Validation
 
-**Input**: Design documents from `/specs/001-fix-ui-ws-validation/`
+**Input**: Design documents from `/specs/005-fix-ui-ws-validation/`
 **Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/
 
 **Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
@@ -81,7 +81,19 @@
 **Purpose**: Improvements that affect multiple user stories
 
 - [x] T009 [P] Update `docs/settings.md` with new URL validation behavior
-- [ ] T010 Run full verification suite per `quickstart.md`
+- [x] T010 Run full verification suite per `quickstart.md`
+
+---
+
+## Phase 7: Addressing Requirements Gaps (from ws-connection.md)
+
+**Purpose**: Close gaps identified during requirements quality review to ensure robust WebSocket communication.
+
+- [x] T011 [US2] Resolve WebSocket endpoint path conflict between contract and implementation (Contract: `/ws/logs/{id}` vs Actual: `/ws/logs/{id}`)
+- [x] T012 [US2] Implement environment-aware protocol selection (`ws` vs `wss`) based on `PUBLIC_WS_URL`
+- [x] T013 [US2] Implement robust exponential backoff with specific initial delays and max retry counts
+- [x] T014 [US2] Add UI handling for "Partial Log" and "Task Completed" WebSocket states in `TaskRunner.svelte`
+- [x] T015 [US2] Implement backend port availability check and user-friendly error reporting in the frontend
 
 ---