synapse-hub 2.2.3 → 2.4.0

package/tools/setup_project.py

@@ -20,6 +20,7 @@ Automated actions:
 
 import os
 import sys
+import json
 import shutil
 import argparse
 from pathlib import Path
@@ -95,7 +96,7 @@ def detect_tech_stack(target_dir):
             "language": "Groovy",
             "page_dir": "Keywords/pages",
             "test_dir": "Scripts",
-            "run_cmd": "./tools/run_headless_kre.sh (or katalonc CLI)"
+            "run_cmd": "katalonc -noSplash -runMode=console"
         }
 
     # 2. Playwright check
@@ -121,7 +122,21 @@ def detect_tech_stack(target_dir):
             "run_cmd": "npx cypress run --headless"
         }
 
-    # 4. Pytest check
+    # 4. Selenium WebDriver check
+    req_txt = target_path / "requirements.txt"
+    has_selenium_req = req_txt.exists() and "selenium" in req_txt.read_text(encoding="utf-8", errors="ignore").lower()
+    has_selenium_code = any("selenium" in f.read_text(encoding="utf-8", errors="ignore") for f in list(target_path.glob("**/*.py"))[:10]) if list(target_path.glob("**/*.py")) else False
+    if has_selenium_req or has_selenium_code:
+        return {
+            "name": target_path.name,
+            "framework": "Selenium WebDriver",
+            "language": "Python",
+            "page_dir": "pages",
+            "test_dir": "tests",
+            "run_cmd": "pytest tests/ -v"
+        }
+
+    # 5. Pytest check
     if (target_path / "pytest.ini").exists() or list(target_path.glob("test_*.py")):
         return {
             "name": target_path.name,
@@ -143,7 +158,7 @@ def detect_tech_stack(target_dir):
     }
 
 
-def ensure_project_ai_guide(target_dir, stack_info):
+def ensure_project_ai_guide(target_dir, stack_info, profile="full"):
     """Generates PROJECT_AI_GUIDE.md tailored to the target project if missing."""
     guide_path = os.path.join(target_dir, "PROJECT_AI_GUIDE.md")
     if os.path.exists(guide_path):
@@ -167,6 +182,14 @@ def ensure_project_ai_guide(target_dir, stack_info):
     content = content.replace("tests/e2e/... or Scripts/...", stack_info["test_dir"])
     content = content.replace("[e.g., npx playwright test --project=chromium --reporter=html,junit:results.xml]", stack_info["run_cmd"])
 
+    profile_line = f"- **Active Skills Profile:** `{profile.upper()}`"
+    if profile_line not in content:
+        lang_target = f"- **Script Language:** `{stack_info['language']}`"
+        if lang_target in content:
+            content = content.replace(lang_target, f"{lang_target}\n{profile_line}")
+        else:
+            content = content.replace("## 1. General System Under Test", f"## 1. General System Under Test\n{profile_line}")
+
     with open(guide_path, "w", encoding="utf-8") as f:
         f.write(content)
 
@@ -195,7 +218,7 @@ def install_git_pre_push_hook(target_dir):
         try:
             with open(manifest_file, "r", encoding="utf-8") as f:
                 pkg_ver = json.load(f).get("version", pkg_ver)
-        except Exception:
+        except (IOError, json.JSONDecodeError, KeyError):
             pass
 
     verify_all_script = os.path.join(SCRIPT_DIR, "verify_all.py").replace("\\", "/")
@@ -204,22 +227,31 @@ def install_git_pre_push_hook(target_dir):
     hook_snippet = f"""
 # --- Synapse-Hub Pre-Push Quality Gate (v{pkg_ver}) ---
 echo "\\n[AI-GUARD] Running Pre-Push Verification (Quality Gates DoD)..."
-if command -v npx >/dev/null 2>&1; then
-    npx synapse-hub@{pkg_ver} verify || npx synapse-hub verify
-elif [ -f "{verify_all_script}" ]; then
+# Prioritize local tool execution to run offline without network latency or registry dependency
+if [ -f "{verify_all_script}" ]; then
     python3 "{verify_all_script}" || python "{verify_all_script}"
+elif command -v synapse-hub >/dev/null 2>&1; then
+    synapse-hub verify
+elif command -v agent-qa >/dev/null 2>&1; then
+    agent-qa verify
+elif command -v npx >/dev/null 2>&1; then
+    npx --no-install synapse-hub verify 2>/dev/null || npx synapse-hub@{pkg_ver} verify
 fi
 if [ $? -ne 0 ]; then
     echo "\\n[AI-GUARD - REJECTED] Git Push aborted: Quality Gates verification failed!"
-    echo "Please fix defects or run 'npx synapse-hub@{pkg_ver} verify' locally before pushing.\\n"
+    echo "Please fix defects or run 'python tools/verify_all.py' locally before pushing.\\n"
     exit 1
 fi
 
 echo "[AI-GUARD - PASSED] Quality Gates satisfied. Syncing project health report..."
-if command -v npx >/dev/null 2>&1; then
-    npx synapse-hub@{pkg_ver} analyze || npx synapse-hub analyze
-elif [ -f "{analyze_script}" ]; then
+if [ -f "{analyze_script}" ]; then
     python3 "{analyze_script}" || python "{analyze_script}"
+elif command -v synapse-hub >/dev/null 2>&1; then
+    synapse-hub analyze
+elif command -v agent-qa >/dev/null 2>&1; then
+    agent-qa analyze
+elif command -v npx >/dev/null 2>&1; then
+    npx --no-install synapse-hub analyze 2>/dev/null || npx synapse-hub@{pkg_ver} analyze
 fi
 echo "[AI-GUARD - READY] Pushing to remote...\\n"
 # --- End Synapse-Hub Quality Gate ---
@@ -250,7 +282,7 @@ echo "[AI-GUARD - READY] Pushing to remote...\\n"
         # Attempt to make executable on Unix-like environments
         try:
             os.chmod(hook_file, 0o755)
-        except Exception:
+        except OSError:
             pass
 
         print(f"  {GREEN}[OK] Configured automated Pre-Push Git Hook:{RESET} {hook_file} (pinned to v{pkg_ver})")
@@ -260,6 +292,82 @@ echo "[AI-GUARD - READY] Pushing to remote...\\n"
         return False
 
 
+def ensure_gitignore_protection(target_dir):
+    """Ensures local cache and generated AST intelligence artifacts are ignored in target repo."""
+    gitignore_path = os.path.join(target_dir, ".gitignore")
+    entries = [".synapse/", "repo_map.txt", "repo_map.json"]
+    try:
+        existing = ""
+        if os.path.exists(gitignore_path):
+            with open(gitignore_path, "r", encoding="utf-8", errors="ignore") as f:
+                existing = f.read()
+        missing = [e for e in entries if e not in existing]
+        if missing:
+            with open(gitignore_path, "a", encoding="utf-8") as f:
+                if existing and not existing.endswith("\n"):
+                    f.write("\n")
+                f.write("\n# Synapse-Hub Local Cache & AST Intelligence\n")
+                for e in missing:
+                    f.write(f"{e}\n")
+            print(f"  {GREEN}[OK] Protected local cache in .gitignore:{RESET} {gitignore_path}")
+            return True
+    except OSError:
+        pass
+    return False
+
+
+def install_git_post_merge_hook(target_dir):
+    """
+    Installs or appends an automated post-merge hook into target project's .git repository.
+    When a developer pulls code for the first time via 'git pull', this triggers the
+    welcome landing page once, then silently records it as completed.
+    """
+    git_dir = os.path.join(target_dir, ".git")
+    if not os.path.isdir(git_dir):
+        return False
+
+    hooks_dir = os.path.join(git_dir, "hooks")
+    os.makedirs(hooks_dir, exist_ok=True)
+    hook_file = os.path.join(hooks_dir, "post-merge")
+
+    welcome_script = os.path.join(SCRIPT_DIR, "welcome_page.py").replace("\\", "/")
+
+    hook_snippet = f"""# --- Synapse-Hub Post-Merge First-Pull Sentinel ---
+# Security invariant: Never execute relative scripts from target repository
+if [ -f "{welcome_script}" ]; then
+    python3 "{welcome_script}" --first-run 2>/dev/null || python "{welcome_script}" --first-run 2>/dev/null || true
+elif command -v synapse-hub >/dev/null 2>&1; then
+    synapse-hub welcome --first-run 2>/dev/null || true
+elif command -v agent-qa >/dev/null 2>&1; then
+    agent-qa welcome --first-run 2>/dev/null || true
+fi
+"""
+    try:
+        if os.path.exists(hook_file):
+            with open(hook_file, "r", encoding="utf-8", errors="ignore") as f:
+                existing_content = f.read()
+
+            if "Synapse-Hub Post-Merge" in existing_content:
+                return True
+
+            final_content = existing_content.rstrip() + "\n" + hook_snippet
+        else:
+            final_content = "#!/bin/sh\n" + hook_snippet
+
+        with open(hook_file, "w", encoding="utf-8", newline="\n") as f:
+            f.write(final_content)
+
+        try:
+            os.chmod(hook_file, 0o755)
+        except OSError:
+            pass
+
+        print(f"  {GREEN}[OK] Configured Post-Merge First-Pull Git Hook:{RESET} {hook_file}")
+        return True
+    except (OSError, UnicodeDecodeError):
+        return False
+
+
 def inject_antigravity_global_plugin():
     """
     Automatically injects Synapse-Hub into Antigravity's Global Plugin Directory
@@ -295,7 +403,7 @@ def inject_antigravity_global_plugin():
             if os.path.islink(dst):
                 try:
                     os.unlink(dst)
-                except Exception:
+                except OSError:
                     pass
             if sys.platform == "win32":
                 try:
@@ -303,7 +411,7 @@ def inject_antigravity_global_plugin():
                     if not os.path.exists(dst):
                         _winapi.CreateJunction(src, dst)
                         return
-                except Exception:
+                except (OSError, ImportError, AttributeError):
                     pass
             shutil.copytree(src, dst, dirs_exist_ok=True, ignore=shutil.ignore_patterns("__pycache__", "*.pyc", "*.tmp"))
 
@@ -405,7 +513,65 @@ def install_universal_ai_bridges(target_dir):
     return True
 
 
-def run_setup(target_repo):
+def uninstall_setup(target_repo: str) -> int:
+    """Safely reverts and removes files installed by setup_project in the target repo."""
+    print(f"\n{BOLD}{YELLOW}======================================================================{RESET}")
+    print(f"{BOLD}{YELLOW}          SYNAPSE HUB — REVERT & UNINSTALL SETUP                      {RESET}")
+    print(f"{BOLD}{YELLOW}======================================================================{RESET}")
+    print(f"Target Repository: {target_repo}")
+
+    reverted_items = 0
+
+    # 1. Remove PROJECT_AI_GUIDE.md
+    guide_file = os.path.join(target_repo, "PROJECT_AI_GUIDE.md")
+    if os.path.exists(guide_file):
+        os.remove(guide_file)
+        print(f"  {GREEN}[REMOVED]{RESET} {guide_file}")
+        reverted_items += 1
+
+    # 2. Restore/Remove Git Pre-Push Hook
+    hook_file = os.path.join(target_repo, ".git", "hooks", "pre-push")
+    backup_file = os.path.join(target_repo, ".git", "hooks", "pre-push.bak")
+    if os.path.exists(backup_file):
+        if os.path.exists(hook_file):
+            os.remove(hook_file)
+        shutil.move(backup_file, hook_file)
+        print(f"  {GREEN}[RESTORED]{RESET} Restored original pre-push hook from backup")
+        reverted_items += 1
+    elif os.path.exists(hook_file):
+        with open(hook_file, "r", encoding="utf-8", errors="ignore") as f:
+            content = f.read()
+        if "Synapse-Hub" in content or "synapse-hub" in content:
+            os.remove(hook_file)
+            print(f"  {GREEN}[REMOVED]{RESET} Cleaned Synapse-Hub pre-push hook")
+            reverted_items += 1
+
+    # 3. Remove Cursor rule
+    cursor_rule = os.path.join(target_repo, ".cursor", "rules", "synapse-qa.mdc")
+    if os.path.exists(cursor_rule):
+        os.remove(cursor_rule)
+        print(f"  {GREEN}[REMOVED]{RESET} {cursor_rule}")
+        reverted_items += 1
+
+    # 4. Remove Copilot instruction
+    copilot_file = os.path.join(target_repo, ".github", "copilot-instructions.md")
+    if os.path.exists(copilot_file):
+        os.remove(copilot_file)
+        print(f"  {GREEN}[REMOVED]{RESET} {copilot_file}")
+        reverted_items += 1
+
+    # 5. Remove Windsurf rules
+    windsurf_file = os.path.join(target_repo, ".windsurfrules")
+    if os.path.exists(windsurf_file):
+        os.remove(windsurf_file)
+        print(f"  {GREEN}[REMOVED]{RESET} {windsurf_file}")
+        reverted_items += 1
+
+    print(f"\n{GREEN}✅ Uninstall complete! Cleaned {reverted_items} configuration files/hooks.{RESET}\n")
+    return 0
+
+
+def run_setup(target_repo, dry_run=False, profile="auto", no_global=True, no_git_hook=False, no_browser=True, open_browser=False):
     """Main execution entrypoint for automated project setup."""
     print(f"\n{BOLD}{CYAN}======================================================================{RESET}")
     print(f"{BOLD}{CYAN}      AUTONOMOUS ZERO-COMMAND PROJECT BOOTSTRAP (AI-READY SETUP)     {RESET}")
@@ -417,9 +583,42 @@ def run_setup(target_repo):
     print(f"🔍 Detected Stack  : {BOLD}{stack_info['framework']}{RESET} ({stack_info['language']})")
     print(f"📂 Structure Scope : Pages: `{stack_info['page_dir']}` | Tests: `{stack_info['test_dir']}`\n")
 
+    # Resolve active profile
+    if profile == "auto":
+        fw = stack_info.get("framework", "").lower()
+        lang = stack_info.get("language", "").lower()
+        if "playwright" in fw:
+            profile = "playwright"
+        elif "selenium" in fw:
+            profile = "selenium"
+        elif "cypress" in fw:
+            profile = "cypress"
+        elif "katalon" in fw:
+            profile = "katalon"
+        elif "pytest" in fw or "python" in lang:
+            profile = "pytest"
+        else:
+            profile = "full"
+
+    print(f"🎯 Selected Profile: {BOLD}{profile.upper()}{RESET}")
+    if dry_run:
+        print(f"Operational Mode   : {YELLOW}DRY-RUN (Simulating without modifying files on disk){RESET}\n")
+    else:
+        print(f"Operational Mode   : APPLY CHANGES\n")
+
+    if dry_run:
+        print(f"{YELLOW}[DRY-RUN PREVIEW]{RESET}")
+        print(f"  • Profile: {profile.upper()}")
+        print(f"  • Would generate: {os.path.join(target_repo, 'PROJECT_AI_GUIDE.md')}")
+        print(f"  • Would deploy AI bridges: .cursor/rules/synapse-qa.mdc, .github/copilot-instructions.md, .windsurfrules")
+        print(f"  • Would install pre-push hook: {os.path.join(target_repo, '.git', 'hooks', 'pre-push')}")
+        print(f"  • Would initialize: Central Agent Memory (~/.agent_memory/global_cache.db)")
+        print(f"\n{GREEN}✅ Dry-run completed successfully. Zero changes written to disk.{RESET}\n")
+        return 0
+
     # 2. Ensure PROJECT_AI_GUIDE.md & PROJECT_STATE.md
     print(f"{BOLD}[1/5] Checking Project AI Guide & State Anchor...{RESET}")
-    guide_created = ensure_project_ai_guide(target_repo, stack_info)
+    guide_created = ensure_project_ai_guide(target_repo, stack_info, profile=profile)
     project_state.init_state(target_repo)
 
     # 3. Deploy Universal AI Bridges (Cursor, Claude Code, GitHub Copilot, Windsurf)
@@ -427,35 +626,66 @@ def run_setup(target_repo):
     bridges_deployed = install_universal_ai_bridges(target_repo)
 
     # 4. Inject Antigravity Global Plugin
-    print(f"\n{BOLD}[3/5] Injecting Antigravity Global Plugin (~/.gemini/config/plugins)...{RESET}")
-    plugin_injected = inject_antigravity_global_plugin()
-
-    # 4.1 Initialize Central Agent Memory (SQLite Cache)
-    try:
-        import cache_resolver
-        cache_resolver.init_db(seed=True)
-        print(f"  {GREEN}[OK] Initialized Central Agent Memory (SQLite):{RESET} ~/.agent_memory/global_cache.db")
-    except Exception as e:
-        print(f"  ⚠️ Could not initialize memory cache: {e}")
+    plugin_injected = False
+    if no_global:
+        print(f"\n{BOLD}[3/5] Checking Antigravity Global Plugin (~/.gemini/config/plugins)...{RESET}")
+        print(f"  {YELLOW}[SKIP] Local-only mode (default). Skipped global plugin injection (pass --global to install globally).{RESET}")
+    else:
+        print(f"\n{BOLD}[3/5] Injecting Antigravity Global Plugin (~/.gemini/config/plugins)...{RESET}")
+        plugin_injected = inject_antigravity_global_plugin()
 
-    # 5. Install Pre-Push Git Hook
-    print(f"\n{BOLD}[4/5] Installing Zero-Leakage Git Pre-Push Hook...{RESET}")
-    hook_installed = install_git_pre_push_hook(target_repo)
+        # 4.1 Initialize Central Agent Memory (SQLite Cache)
+        try:
+            import cache_resolver
+            cache_resolver.init_db(seed=True)
+            print(f"  {GREEN}[OK] Initialized Central Agent Memory (SQLite):{RESET} ~/.agent_memory/global_cache.db")
+        except Exception as e:
+            print(f"  ⚠️ Could not initialize memory cache: {e}")
+
+        # 4.2 Protect local cache in .gitignore
+        ensure_gitignore_protection(target_repo)
+
+    # 5. Install Pre-Push & Post-Merge Git Hooks
+    hook_installed = False
+    if no_git_hook:
+        print(f"\n{BOLD}[4/5] Installing Zero-Leakage Git Hooks...{RESET}")
+        print(f"  {YELLOW}[SKIP] Skipped Git hook installation (--no-git-hook).{RESET}")
+    else:
+        print(f"\n{BOLD}[4/5] Installing Zero-Leakage Git Hooks...{RESET}")
+        hook_installed = install_git_pre_push_hook(target_repo)
+        install_git_post_merge_hook(target_repo)
 
     # 6. Run 5-in-1 Comprehensive Health & AST Analysis
     print(f"\n{BOLD}[5/5] Executing Initial Health Audit & AST Mapping...{RESET}")
     analysis_code = analyze_project.run_full_analysis(target_repo)
 
+    # 7. Generate & Launch Interactive Visual Landing Page (Silent by default unless --open)
+    welcome_url = None
+    try:
+        from welcome_page import generate_welcome_page
+        should_open = (not no_browser) and open_browser and (not os.environ.get("CI")) and (not os.environ.get("HEADLESS")) and ("unittest" not in sys.modules) and ("pytest" not in sys.modules)
+        welcome_file = generate_welcome_page(
+            target_repo=target_repo,
+            stack_info=stack_info,
+            open_browser=should_open
+        )
+        welcome_url = f"file://{welcome_file}"
+    except (ImportError, OSError, ValueError):
+        pass
+
     print(f"\n{BOLD}{CYAN}======================================================================{RESET}")
     print(f"{BOLD}{CYAN}            🎉 PROJECT IS NOW 100% AI-READY (LEVEL 5 SETUP)           {RESET}")
     print(f"{BOLD}{CYAN}======================================================================{RESET}")
     print(f"  Target Framework    : {stack_info['framework']}")
+    print(f"  Active Profile      : {profile.upper()}")
     print(f"  AI Project Guide    : {os.path.join(target_repo, 'PROJECT_AI_GUIDE.md')}")
     print(f"  Universal Bridges   : Cursor (.cursor/rules), Claude Code, Copilot, Windsurf")
     print(f"  Antigravity Plugin  : {'ACTIVE (~/.gemini/config/plugins/synapse-hub)' if plugin_injected else 'STANDALONE'}")
     print(f"  AST Method Map      : {os.path.join(target_repo, 'repo_map.txt')}")
     print(f"  Health Report       : {os.path.join(target_repo, 'PROJECT_HEALTH_REPORT.md')}")
     print(f"  Pre-Push Sentinel   : {'ACTIVE (.git/hooks/pre-push)' if hook_installed else 'MANUAL (No .git folder)'}")
+    if welcome_url:
+        print(f"  Visual Landing Page : {welcome_url}")
     print(f"{BOLD}{CYAN}======================================================================{RESET}\n")
 
     return analysis_code
@@ -465,6 +695,24 @@ def main():
     parser = argparse.ArgumentParser(description="Autonomous Enterprise QA Project Setup")
     parser.add_argument("target", nargs="?", default=None, help="Target repository path to setup")
     parser.add_argument("--repo", "--path", dest="repo_path", default=None, help="Target repository path")
+    parser.add_argument(
+        "--profile",
+        default="auto",
+        choices=["auto", "core", "web-e2e", "api-perf", "full", "playwright", "pytest", "cypress", "katalon"],
+        help="Skills profile to install (auto, core, web-e2e, api-perf, full, playwright, pytest, cypress, katalon)"
+    )
+    parser.add_argument("--dry-run", action="store_true", help="Simulate setup actions without modifying disk")
+    parser.add_argument("--uninstall", action="store_true", help="Revert and remove files installed by setup_project")
+    parser.add_argument("--global", action="store_true", dest="enable_global", default=False,
+                        help="Inject Synapse-Hub into Antigravity global plugins (~/.gemini/config/plugins) and central memory")
+    parser.add_argument("--local-only", "--no-global", action="store_true", dest="no_global", default=True,
+                        help="Only configure project-local assets (PROJECT_AI_GUIDE.md, bridges), do not touch ~/.gemini (default: True)")
+    parser.add_argument("--no-git-hook", action="store_true",
+                        help="Skip installing automated .git/hooks/pre-push")
+    parser.add_argument("--open", action="store_true", dest="open_browser",
+                        help="Launch landing page in web browser")
+    parser.add_argument("--no-browser", "--no-open", action="store_true", dest="no_browser", default=True,
+                        help="Do not automatically launch landing page in web browser (default: True)")
     args = parser.parse_args()
 
     try:
@@ -473,7 +721,23 @@ def main():
         print(f"❌ Error: {e}")
         return 1
 
-    return run_setup(target_repo)
+    if args.uninstall:
+        return uninstall_setup(target_repo)
+
+    # When --open is explicitly requested, honor it
+    no_browser = False if getattr(args, "open_browser", False) else True
+    open_browser = bool(getattr(args, "open_browser", False))
+    use_no_global = False if getattr(args, "enable_global", False) else True
+
+    return run_setup(
+        target_repo,
+        dry_run=args.dry_run,
+        profile=args.profile,
+        no_global=use_no_global,
+        no_git_hook=args.no_git_hook,
+        no_browser=no_browser,
+        open_browser=open_browser
+    )
 
 
 if __name__ == "__main__":

package/tools/skillspector.py

@@ -165,7 +165,7 @@ PROHIBITION_PREFIX = re.compile(
 )
 
 ALERT_BLOCK_PREFIX = re.compile(
-    r"^\s*>\s*\[!(?:WARNING|CAUTION|DANGER|ALERT|IMPORTANT|NOTE|TIP)\]",
+    r"^\s*>\s*\[!(?:WARNING|CAUTION|DANGER|ALERT)\]",
     re.IGNORECASE | re.MULTILINE,
 )
 
@@ -189,23 +189,20 @@ def is_in_prohibition_context(content: str, start: int, end: int) -> bool:
     if PROHIBITION_PREFIX.search(current_line):
         return True
 
-    # 2. Markdown Caution/Warning Callout Block
-    if any(ALERT_BLOCK_PREFIX.search(line) for line in lines[-5:]):
+    # 2. Markdown Caution/Warning Callout Block with explicit negative imperative
+    has_alert = any(ALERT_BLOCK_PREFIX.search(line) for line in lines[-5:])
+    if has_alert and any(re.search(r'\b(never|do not|don[\'’]t|must not|forbidden|prohibited|avoid)\b', line, re.IGNORECASE) for line in lines[-5:]):
         return True
 
     # 3. Defensive Guideline headings ("Anti-Pattern Blacklist", "Forbidden actions")
     preceding_lower = preceding_text.lower()
     defensive_markers = (
-        "anti-pattern",
+        "anti-pattern blacklist",
         "mistake / anti-pattern",
         "strictly forbidden",
         "never use",
         "mandatory avoidance",
         "forbidden actions",
-        "prohibited",
-        "blacklist",
-        "threat model",
-        "vulnerability check",
         "zero-token error blacklist",
     )
     if any(marker in preceding_lower for marker in defensive_markers):
@@ -927,6 +924,9 @@ def scan_target(target_path: str) -> ScanReport:
         pass
 
     path_obj = Path(target_path).resolve()
+    if not path_obj.exists():
+        raise FileNotFoundError(f"Target path does not exist: {target_path}")
+
     all_findings: List[Finding] = []
     scanned_count = 0