spec-kitty-cli 0.12.1__py3-none-any.whl

specify_cli/dashboard/diagnostics.py

@@ -0,0 +1,204 @@
+"""Project diagnostics helpers for the dashboard."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any, Dict
+
+__all__ = ["run_diagnostics"]
+
+
+def _ensure_specify_cli_on_path() -> None:
+    """Ensure the repository root (src directory) is on sys.path for fallback imports."""
+    candidate = Path(__file__).resolve().parents[2]  # .../src
+    if str(candidate) not in sys.path:
+        sys.path.insert(0, str(candidate))
+
+
+def run_diagnostics(project_dir: Path) -> Dict[str, Any]:
+    """Run comprehensive diagnostics on the project setup using enhanced verification."""
+    try:
+        from ..manifest import FileManifest, WorktreeStatus  # type: ignore
+        from ..acceptance import detect_feature_slug, AcceptanceError
+    except (ImportError, ValueError):
+        try:
+            from specify_cli.manifest import FileManifest, WorktreeStatus  # type: ignore
+            from specify_cli.acceptance import detect_feature_slug, AcceptanceError
+        except ImportError:
+            _ensure_specify_cli_on_path()
+            from specify_cli.manifest import FileManifest, WorktreeStatus  # type: ignore
+            from specify_cli.acceptance import detect_feature_slug, AcceptanceError
+
+    kittify_dir = project_dir / ".kittify"
+    repo_root = project_dir
+
+    diagnostics: Dict[str, Any] = {
+        'project_path': str(project_dir),
+        'current_working_directory': str(Path.cwd()),
+        'git_branch': None,
+        'in_worktree': False,
+        'worktrees_exist': False,
+        'active_mission': None,
+        'file_integrity': {},
+        'worktree_overview': {},
+        'current_feature': {},
+        'all_features': [],
+        'dashboard_health': {},
+        'observations': [],
+        'issues': [],
+    }
+
+    manifest = FileManifest(kittify_dir)
+    worktree_status = WorktreeStatus(repo_root)
+
+    try:
+        result = subprocess.run(
+            ['git', 'branch', '--show-current'],
+            cwd=project_dir,
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        diagnostics['git_branch'] = result.stdout.strip()
+    except subprocess.CalledProcessError:
+        diagnostics['issues'].append('Could not detect git branch')
+
+    diagnostics['in_worktree'] = '.worktrees' in str(Path.cwd())
+    worktrees_dir = project_dir / '.worktrees'
+    diagnostics['worktrees_exist'] = worktrees_dir.exists()
+    diagnostics['active_mission'] = manifest.active_mission
+
+    file_check = manifest.check_files()
+    expected_files = manifest.get_expected_files()
+
+    total_expected = sum(len(files) for files in expected_files.values())
+    total_present = len(file_check["present"])
+    total_missing = len(file_check["missing"])
+
+    diagnostics['file_integrity'] = {
+        "total_expected": total_expected,
+        "total_present": total_present,
+        "total_missing": total_missing,
+        "missing_files": list(file_check["missing"].keys()) if file_check["missing"] else [],
+    }
+
+    worktree_summary = worktree_status.get_worktree_summary()
+    diagnostics['worktree_overview'] = worktree_summary
+
+    diagnostics['all_features'] = []
+    for feature_slug in worktree_status.get_all_features():
+        feature_status = worktree_status.get_feature_status(feature_slug)
+        diagnostics['all_features'].append({
+            'name': feature_slug,
+            'state': feature_status['state'],
+            'branch_exists': feature_status['branch_exists'],
+            'branch_merged': feature_status['branch_merged'],
+            'worktree_exists': feature_status['worktree_exists'],
+            'worktree_path': feature_status['worktree_path'],
+            'artifacts_in_main': feature_status['artifacts_in_main'],
+            'artifacts_in_worktree': feature_status['artifacts_in_worktree'],
+        })
+
+    try:
+        feature_slug = detect_feature_slug(repo_root, cwd=Path.cwd())
+        if feature_slug:
+            feature_status = worktree_status.get_feature_status(feature_slug.strip())
+            diagnostics['current_feature'] = {
+                'detected': True,
+                'name': feature_slug.strip(),
+                'state': feature_status['state'],
+                'branch_exists': feature_status['branch_exists'],
+                'branch_merged': feature_status['branch_merged'],
+                'worktree_exists': feature_status['worktree_exists'],
+                'worktree_path': feature_status['worktree_path'],
+                'artifacts_in_main': feature_status['artifacts_in_main'],
+                'artifacts_in_worktree': feature_status['artifacts_in_worktree'],
+            }
+    except (AcceptanceError, Exception) as exc:  # type: ignore[misc]
+        diagnostics['current_feature'] = {
+            'detected': False,
+            'error': str(exc),
+        }
+
+    observations = []
+
+    if diagnostics['git_branch'] == 'main' and diagnostics['in_worktree']:
+        observations.append("Unusual: In worktree but on main branch")
+
+    current_feature = diagnostics.get('current_feature') or {}
+    if current_feature.get('detected') and current_feature.get('state') == 'in_development':
+        if not current_feature.get('worktree_exists'):
+            observations.append(
+                f"Feature {current_feature.get('name')} has no worktree but has development artifacts"
+            )
+
+    if total_missing > 0:
+        observations.append(f"Mission integrity: {total_missing} expected files not found")
+
+    if worktree_summary.get('active_worktrees', 0) > 5:
+        observations.append(f"Multiple worktrees active: {worktree_summary['active_worktrees']}")
+
+    # Check dashboard health
+    dashboard_file = kittify_dir / '.dashboard'
+    dashboard_health = {
+        'metadata_exists': dashboard_file.exists(),
+        'can_start': None,
+        'startup_test': None,
+    }
+
+    if dashboard_file.exists():
+        try:
+            from ..dashboard.lifecycle import _parse_dashboard_file, _check_dashboard_health
+            url, port, token, pid = _parse_dashboard_file(dashboard_file)
+            dashboard_health['url'] = url
+            dashboard_health['port'] = port
+            dashboard_health['pid'] = pid
+            dashboard_health['has_pid'] = pid is not None
+
+            if port:
+                is_healthy = _check_dashboard_health(port, project_dir, token)
+                dashboard_health['responding'] = is_healthy
+                if not is_healthy:
+                    diagnostics['issues'].append(f'Dashboard metadata exists but not responding on port {port}')
+                    if pid:
+                        # Check if process is alive
+                        try:
+                            from ..dashboard.lifecycle import _is_process_alive
+                            if _is_process_alive(pid):
+                                diagnostics['issues'].append(f'Dashboard process (PID {pid}) is alive but not responding')
+                            else:
+                                diagnostics['issues'].append(f'Dashboard process (PID {pid}) is dead - stale metadata file')
+                        except Exception:
+                            pass
+        except Exception as e:
+            dashboard_health['parse_error'] = str(e)
+            diagnostics['issues'].append(f'Dashboard metadata file corrupted: {e}')
+    else:
+        # No dashboard running - try to start one and see what happens
+        try:
+            from ..dashboard.lifecycle import ensure_dashboard_running
+            url, port, started = ensure_dashboard_running(project_dir, background_process=False)
+            dashboard_health['can_start'] = True
+            dashboard_health['startup_test'] = 'SUCCESS'
+            dashboard_health['test_url'] = url
+            dashboard_health['test_port'] = port
+
+            # Stop the test dashboard
+            try:
+                from ..dashboard.lifecycle import stop_dashboard
+                stop_dashboard(project_dir)
+            except Exception:
+                pass
+        except Exception as e:
+            dashboard_health['can_start'] = False
+            dashboard_health['startup_test'] = 'FAILED'
+            dashboard_health['startup_error'] = str(e)
+            diagnostics['issues'].append(f'Dashboard cannot start: {e}')
+
+    diagnostics['dashboard_health'] = dashboard_health
+    diagnostics['observations'] = observations
+
+    return diagnostics

specify_cli/dashboard/handlers/__init__.py

@@ -0,0 +1,17 @@
+"""Dashboard HTTP handler subpackage."""
+
+from .api import APIHandler
+from .base import DashboardHandler
+from .features import FeatureHandler
+from .router import DashboardRouter
+from .static import STATIC_DIR, STATIC_URL_PREFIX, StaticHandler
+
+__all__ = [
+    "APIHandler",
+    "DashboardHandler",
+    "DashboardRouter",
+    "FeatureHandler",
+    "StaticHandler",
+    "STATIC_DIR",
+    "STATIC_URL_PREFIX",
+]

specify_cli/dashboard/handlers/api.py

@@ -0,0 +1,143 @@
+"""API-focused dashboard HTTP handlers."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from ..diagnostics import run_diagnostics
+from ..scanner import format_path_for_display, scan_all_features
+from ..templates import get_dashboard_html
+from .base import DashboardHandler
+from specify_cli.mission import MissionError, get_mission_by_name
+
+__all__ = ["APIHandler"]
+
+
+class APIHandler(DashboardHandler):
+    """Serve dashboard root, health, diagnostics, and shutdown endpoints."""
+
+    def handle_root(self) -> None:
+        """Return the rendered dashboard HTML shell."""
+        project_path = Path(self.project_dir).resolve()
+
+        # Derive active mission from the most active feature (per-feature mission model)
+        mission_context = {
+            'name': 'No active feature',
+            'domain': 'unknown',
+            'version': '',
+            'slug': '',
+            'description': '',
+            'path': '',
+        }
+
+        try:
+            features = scan_all_features(project_path)
+
+            # Find active feature: WPs in doing > for_review > most recent
+            active_feature = None
+            for feature in features:
+                stats = feature.get('kanban_stats', {})
+                if stats.get('doing', 0) > 0:
+                    active_feature = feature
+                    break
+                if stats.get('for_review', 0) > 0 and active_feature is None:
+                    active_feature = feature
+
+            if active_feature is None and features:
+                active_feature = features[0]  # Most recent
+
+            if active_feature:
+                feature_mission_key = active_feature.get('meta', {}).get('mission', 'software-dev')
+                kittify_dir = project_path / ".kittify"
+                mission = get_mission_by_name(feature_mission_key, kittify_dir)
+                mission_context = {
+                    'name': mission.name,
+                    'domain': mission.config.domain,
+                    'version': mission.config.version,
+                    'slug': mission.path.name,
+                    'description': mission.config.description or '',
+                    'path': format_path_for_display(str(mission.path)),
+                }
+        except (MissionError, Exception):
+            pass  # Keep default "No active feature" context
+
+        self.send_response(200)
+        self.send_header('Content-type', 'text/html')
+        self.end_headers()
+        self.wfile.write(get_dashboard_html(mission_context=mission_context).encode())
+
+    def handle_health(self) -> None:
+        """Return project health metadata."""
+        self.send_response(200)
+        self.send_header('Content-type', 'application/json')
+        self.send_header('Cache-Control', 'no-cache')
+        self.end_headers()
+
+        try:
+            project_path = str(Path(self.project_dir).resolve())
+        except Exception:
+            project_path = str(self.project_dir)
+
+        response_data = {
+            'status': 'ok',
+            'project_path': project_path,
+        }
+
+        token = getattr(self, 'project_token', None)
+        if token:
+            response_data['token'] = token
+
+        self.wfile.write(json.dumps(response_data).encode())
+
+    def handle_shutdown(self) -> None:
+        """Delegate to the shared shutdown helper."""
+        self._handle_shutdown()
+
+    def handle_diagnostics(self) -> None:
+        """Run diagnostics and report JSON payloads (or errors)."""
+        try:
+            diagnostics = run_diagnostics(Path(self.project_dir))
+            self.send_response(200)
+            self.send_header('Content-type', 'application/json')
+            self.send_header('Cache-Control', 'no-cache')
+            self.end_headers()
+            self.wfile.write(json.dumps(diagnostics).encode())
+        except Exception as exc:  # pragma: no cover - fallback safety
+            import traceback
+
+            error_msg = {
+                "error": str(exc),
+                "traceback": traceback.format_exc(),
+            }
+            self.send_response(500)
+            self.send_header('Content-type', 'application/json')
+            self.end_headers()
+            self.wfile.write(json.dumps(error_msg).encode())
+
+    def handle_constitution(self) -> None:
+        """Serve project-level constitution from .kittify/memory/constitution.md"""
+        try:
+            constitution_path = Path(self.project_dir) / ".kittify" / "memory" / "constitution.md"
+
+            if not constitution_path.exists():
+                self.send_response(404)
+                self.send_header('Content-type', 'text/plain')
+                self.end_headers()
+                self.wfile.write(b'Constitution not found')
+                return
+
+            content = constitution_path.read_text(encoding='utf-8')
+            self.send_response(200)
+            self.send_header('Content-type', 'text/plain; charset=utf-8')
+            self.send_header('Cache-Control', 'no-cache')
+            self.end_headers()
+            self.wfile.write(content.encode('utf-8'))
+        except Exception as exc:  # pragma: no cover - fallback safety
+            import traceback
+
+            error_msg = f"Error loading constitution: {exc}\n{traceback.format_exc()}"
+            self.send_response(500)
+            self.send_header('Content-type', 'text/plain')
+            self.end_headers()
+            self.wfile.write(error_msg.encode())

specify_cli/dashboard/handlers/base.py

@@ -0,0 +1,65 @@
+"""Shared helpers for dashboard HTTP handlers."""
+
+from __future__ import annotations
+
+import json
+import threading
+import time
+import urllib.parse
+from http.server import BaseHTTPRequestHandler
+from typing import Any, Dict, Optional
+
+__all__ = ["DashboardHandler"]
+
+
+class DashboardHandler(BaseHTTPRequestHandler):
+    """Base class that provides shared helpers for router/endpoint handlers."""
+
+    project_dir: Optional[str] = None
+    project_token: Optional[str] = None
+
+    def log_message(self, format: str, *args: Any) -> None:  # noqa: A003 - signature from BaseHTTPRequestHandler
+        """Suppress default HTTP handler logging noise."""
+        del format, args
+
+    def _send_json(self, status_code: int, payload: Dict[str, Any]) -> None:
+        """Write a JSON response with common headers."""
+        self.send_response(status_code)
+        self.send_header('Content-type', 'application/json')
+        self.send_header('Cache-Control', 'no-cache')
+        self.end_headers()
+        self.wfile.write(json.dumps(payload).encode())
+
+    def _handle_shutdown(self) -> None:
+        """Validate shutdown tokens and stop the server."""
+        expected_token = getattr(self, 'project_token', None)
+
+        token = None
+        if self.command == 'POST':
+            content_length = int(self.headers.get('Content-Length') or 0)
+            body = self.rfile.read(content_length) if content_length else b''
+            if body:
+                try:
+                    payload = json.loads(body.decode('utf-8'))
+                    token = payload.get('token')
+                except (UnicodeDecodeError, json.JSONDecodeError):
+                    self._send_json(400, {'error': 'invalid_payload'})
+                    return
+        else:
+            parsed_path = urllib.parse.urlparse(self.path)
+            params = urllib.parse.parse_qs(parsed_path.query)
+            token_values = params.get('token')
+            if token_values:
+                token = token_values[0]
+
+        if expected_token and token != expected_token:
+            self._send_json(403, {'error': 'invalid_token'})
+            return
+
+        self._send_json(200, {'status': 'stopping'})
+
+        def shutdown_server(server):
+            time.sleep(0.05)  # allow response to flush
+            server.shutdown()
+
+        threading.Thread(target=shutdown_server, args=(self.server,), daemon=True).start()