user-facing error messages

Redbot · Redbot · commit 652f4dc63f97 · 2026-04-04T00:23:35.000-05:00
diff --git a/src/redfetch/api.py b/src/redfetch/api.py
@@ -54,8 +54,10 @@ async def fetch_resource_record(client: httpx.AsyncClient, resource_id: str) ->
         current_files = resource.get('current_files') or []
         if not resource.get('can_download', False):
             status: RemoteStatus = 'access_denied'
-        elif len(current_files) != 1:
-            status = 'missing_files'
+        elif len(current_files) == 0:
+            status = 'no_files'
+        elif len(current_files) > 1:
+            status = 'multiple_files'
         else:
             status = 'downloadable'
         return ResourceRecord(resource_id=resource_id, status=status, resource=resource)
diff --git a/src/redfetch/listener.py b/src/redfetch/listener.py
@@ -62,7 +62,7 @@ async def handle_health(request: web.Request) -> web.Response:
 
         if version_local is None:
             return web.json_response({"action": "install"})
-        elif version_local != remote_version:
+        elif version_local < remote_version:
             return web.json_response({"action": "update"})
         else:
             return web.json_response({"action": "re-install"})
diff --git a/src/redfetch/sync.py b/src/redfetch/sync.py
@@ -10,22 +10,74 @@
 from redfetch import sync_executor
 from redfetch import sync_planner
 from redfetch import sync_remote
-from redfetch.sync_types import ExecutionPlan, ExecutionResult, SyncEventCallback
+from redfetch.sync_types import (
+    ExecutionPlan,
+    ExecutionResult,
+    PLAN_REASON_META,
+    ReasonInfo,
+    SyncEventCallback,
+    reason_message,
+)
 
 
 _sync_lock: asyncio.Lock | None = None
+_DEFAULT_REASON = ReasonInfo(message="")
 
 
-def _print_plan_summary(execution_plan: ExecutionPlan) -> None:
+def _print_plan_summary(
+    execution_plan: ExecutionPlan,
+    resource_ids: list[str] | None = None,
+) -> None:
+    is_full_sync = resource_ids is None
+    all_blocked = [
+        action for action in execution_plan.actions.values()
+        if action.action == "block"
+    ]
+    if is_full_sync:
+        quiet = [a for a in all_blocked if PLAN_REASON_META.get(a.reason, _DEFAULT_REASON).quiet]
+        blocked = [a for a in all_blocked if not PLAN_REASON_META.get(a.reason, _DEFAULT_REASON).quiet]
+    else:
+        quiet = []
+        blocked = all_blocked
+
     counts = execution_plan.action_counts()
     print(f"Resources in scope: >>> {len(execution_plan.actions)} <<<")
     print(f"Resources to download: >>> {counts.get('download', 0)} <<<")
-    if counts.get("block", 0):
-        print(f"Resources blocked: >>> {counts.get('block', 0)} <<<")
+    if blocked:
+        print(f"Resources blocked: >>> {len(blocked)} <<<")
+        for action in blocked:
+            label = action.title or action.resource_id
+            print(f"  - {label} (id={action.resource_id}): {reason_message(action.reason)}")
+
+    summary_buckets: dict[str, int] = {}
+    for action in quiet:
+        label = PLAN_REASON_META[action.reason].summary_label
+        if label:
+            summary_buckets[label] = summary_buckets.get(label, 0) + 1
+    for label, count in summary_buckets.items():
+        print(f"{label}: >>> {count} <<<")
+
     if counts.get("untrack", 0):
         print(f"Resources to untrack: >>> {counts.get('untrack', 0)} <<<")
 
 
+def _print_failure_detail(
+    execution_plan: ExecutionPlan,
+    resource_ids: list[str],
+) -> None:
+    """Print a hint when a targeted sync fails with zero scoped actions (resource not in scope at all)."""
+    requested = {str(rid) for rid in resource_ids}
+    has_scoped_actions = any(
+        action.root_resource_id in requested
+        for action in execution_plan.actions.values()
+    )
+    if not has_scoped_actions:
+        print(
+            f"No valid resources found for IDs: {resource_ids}. "
+            "Are you in the right server env? Did you opt_in in your settings.local.toml?"
+        )
+
+
 def _run_succeeded(
     *,
     execution_plan: ExecutionPlan,
@@ -92,7 +144,7 @@ async def sync(
         settings_env=settings_env,
     )
 
-    _print_plan_summary(execution_plan)
+    _print_plan_summary(execution_plan, resource_ids=resource_ids)
     if on_event:
         on_event(("total", len(execution_plan.actions), None))
 
@@ -129,19 +181,18 @@ async def sync(
     )
 
     if execution_result.has_errors():
-        errored_resources = [
-            item.resource_id
+        errored_items = [
+            item
             for item in execution_result.items.values()
             if item.outcome == "error"
         ]
-        if errored_resources:
+        if errored_items:
             print("One or more resources failed to download.")
-            print(f"Failed resources: {errored_resources}")
+            for item in errored_items:
+                detail = f": {item.error_detail}" if item.error_detail else ""
+                print(f"  - {item.resource_id}{detail}")
     elif resource_ids is not None and not success:
-        print(
-            f"No valid resources found for IDs: {resource_ids}. "
-            "Are you in the right server env? Did you opt_in in your settings.local.toml?"
-        )
+        _print_failure_detail(execution_plan, resource_ids)
     elif any(item.outcome == "downloaded" for item in execution_result.items.values()):
         print("All resources downloaded successfully.")
     else:
diff --git a/src/redfetch/sync_planner.py b/src/redfetch/sync_planner.py
@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from redfetch import config
 from redfetch.sync_discovery import (
     is_special_resource,
     resolve_dependency_path,
@@ -21,7 +22,7 @@
 )
 
 
-BLOCKING_STATUSES = {"access_denied", "missing_files", "not_found", "fetch_error"}
+BLOCKING_STATUSES = {"access_denied", "no_files", "multiple_files", "not_found", "fetch_error"}
 
 
 def _desired_targets_in_order(desired_set: DesiredSet) -> list[DesiredInstallTarget]:
@@ -64,8 +65,9 @@ def _resolve_target_path(
         category_id = target.category_id
         if category_id is None and remote_state is not None:
             category_id = remote_state.category_id
-        if category_id is None and not is_special_resource(target.resource_id, settings_env):
-            return None, target.subfolder
+        if not is_special_resource(target.resource_id, settings_env):
+            if category_id is None or category_id not in config.CATEGORY_MAP:
+                return None, target.subfolder
         return resolve_root_path(target.resource_id, category_id, settings_env), None
 
     if parent_action is None or not parent_action.resolved_path or target.parent_id is None:
@@ -118,6 +120,8 @@ def _decide_action(
         return "block", "fetch_error"
     if remote_state.status in BLOCKING_STATUSES:
         return "block", remote_state.status  # type: ignore[return-value]
+    if resolved_path is None and target.target_kind == "root":
+        return "block", "unknown_category"
     if _install_context_changed(
         local_state, resolved_path=resolved_path, subfolder=subfolder, target=target,
     ):
diff --git a/src/redfetch/sync_remote.py b/src/redfetch/sync_remote.py
@@ -63,19 +63,6 @@ def _payload_details(payload: dict | None) -> _PayloadDetails:
     )
 
 
-def _payload_state(resource_id: str, payload: dict | None, *, status: str, source_note: str) -> RemoteResourceState:
-    title, category_id, version_id, artifact = _payload_details(payload)
-    return RemoteResourceState(
-        resource_id=resource_id,
-        title=title,
-        category_id=category_id,
-        version_id=version_id,
-        status=status,
-        artifact=artifact if status == "downloadable" else None,
-        source_note=source_note,
-    )
-
-
 def _needs_live_check(
     *,
     desired_targets: list[DesiredInstallTarget],
@@ -109,25 +96,18 @@ def _blocked_state(
     *,
     status: str,
     manifest_details: _PayloadDetails | None,
-    payload: dict | None,
+    live_title: str | None = None,
+    live_category_id: int | None = None,
 ) -> RemoteResourceState:
     """Build a RemoteResourceState for a resource that is blocked."""
-    if payload:
-        return _payload_state(
-            resource_id,
-            payload,
-            status=status,
-            source_note="api_fallback",
-        )
-
     return RemoteResourceState(
         resource_id=resource_id,
-        title=manifest_details.title if manifest_details else None,
-        category_id=manifest_details.category_id if manifest_details else None,
+        title=(manifest_details.title if manifest_details else None) or live_title,
+        category_id=(manifest_details.category_id if manifest_details and manifest_details.category_id is not None else live_category_id),
         version_id=manifest_details.version_id if manifest_details else None,
         status=status,
         artifact=None,
-        source_note="manifest_only" if manifest_details else "api_fallback",
+        source_note="manifest" if manifest_details else "live_access_only",
     )
 
 
@@ -173,35 +153,27 @@ async def fetch_remote_snapshot(
         for record in live_records:
             resource_id = record.resource_id
             manifest_details = manifest_cache.get(resource_id)
-            payload = record.resource
-            status = record.status
+            live_title = payload_title(record.resource)
+            live_category_id = payload_category_id(record.resource)
 
-            if status != "downloadable":
+            if record.status != "downloadable":
                 remote_resources[resource_id] = _blocked_state(
                     resource_id,
-                    status=status,
+                    status=record.status,
                     manifest_details=manifest_details,
-                    payload=payload,
+                    live_title=live_title,
+                    live_category_id=live_category_id,
                 )
                 continue
 
-            if manifest_details is not None and manifest_details.version_id is not None and manifest_details.artifact is not None:
-                live_details = _payload_details(payload)
-                remote_resources[resource_id] = RemoteResourceState(
-                    resource_id=resource_id,
-                    title=manifest_details.title or live_details.title,
-                    category_id=manifest_details.category_id if manifest_details.category_id is not None else live_details.category_id,
-                    version_id=manifest_details.version_id,
-                    status="downloadable",
-                    artifact=manifest_details.artifact,
-                    source_note="manifest_plus_access_check",
-                )
-            else:
-                remote_resources[resource_id] = _payload_state(
-                    resource_id,
-                    payload,
-                    status="downloadable",
-                    source_note="api_fallback",
-                )
+            remote_resources[resource_id] = RemoteResourceState(
+                resource_id=resource_id,
+                title=(manifest_details.title if manifest_details else None) or live_title,
+                category_id=(manifest_details.category_id if manifest_details and manifest_details.category_id is not None else live_category_id),
+                version_id=manifest_details.version_id if manifest_details else None,
+                status="downloadable",
+                artifact=manifest_details.artifact if manifest_details else None,
+                source_note="manifest_plus_access_check" if manifest_details else "live_access_only",
+            )
 
     return RemoteSnapshot(resources=remote_resources)
diff --git a/src/redfetch/sync_types.py b/src/redfetch/sync_types.py
@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from collections.abc import Callable
+from dataclasses import dataclass
 from typing import Literal, Union
 
 from pydantic import BaseModel, ConfigDict, Field
@@ -13,7 +14,8 @@
     "manifest_current",
     "downloadable",
     "access_denied",
-    "missing_files",
+    "no_files",
+    "multiple_files",
     "not_found",
     "fetch_error",
 ]
@@ -25,15 +27,48 @@
     "install_context_changed",
     "not_desired",
     "access_denied",
-    "missing_files",
+    "no_files",
+    "multiple_files",
     "not_found",
     "fetch_error",
     "parent_blocked",
     "parent_failed",
     "dependency_cycle",
+    "unknown_category",
 ]
 ResultOutcome = Literal["downloaded", "skipped", "blocked", "untracked", "error"]
 
+@dataclass(frozen=True, slots=True)
+class ReasonInfo:
+    """Display metadata for a single PlanReason value."""
+
+    message: str
+    quiet: bool = False
+    summary_label: str | None = None
+
+
+PLAN_REASON_META: dict[PlanReason, ReasonInfo] = {
+    "access_denied":           ReasonInfo("You don't have permission to download this resource."),
+    "no_files":                ReasonInfo("This resource has no downloadable files.", quiet=True, summary_label="Resources with no files"),
+    "multiple_files":          ReasonInfo("This resource has multiple files and cannot be auto-synced. Ask the author to release it as a .zip file."),
+    "not_found":               ReasonInfo("This resource was not found."),
+    "fetch_error":             ReasonInfo("Failed to retrieve this resource from the server."),
+    "unknown_category":        ReasonInfo("This resource's category is not mapped to an install location, but you can specify one manually in settings.local.toml"),
+    "parent_blocked":          ReasonInfo("Skipped because its parent resource is blocked.", quiet=True),
+    "parent_failed":           ReasonInfo("Skipped because its parent resource failed to download."),
+    "dependency_cycle":        ReasonInfo("Skipped due to a circular dependency."),
+    "not_desired":             ReasonInfo("No longer watched or licensed; untracking."),
+    "outdated":                ReasonInfo("A newer version is available."),
+    "not_installed":           ReasonInfo("Not yet installed locally."),
+    "already_current":         ReasonInfo("Already up to date."),
+    "install_context_changed": ReasonInfo("Install location or settings changed; re-downloading."),
+}
+
+
+def reason_message(reason: PlanReason) -> str:
+    meta = PLAN_REASON_META.get(reason)
+    return meta.message if meta else reason
+
 SyncEvent = Union[
     tuple[Literal["total"], int, None],
     tuple[Literal["add_total"], int, None],
diff --git a/tests/test_special_resources_e2e.py b/tests/test_special_resources_e2e.py
@@ -334,12 +334,26 @@ async def mock_fetch_licenses(client):
         return []
     
     async def mock_fetch_manifest(client):
-        # Return a manifest with our special resources
         return {
             'resources': {
-                '151': {'last_update': 9999999999},
-                '153': {'last_update': 9999999999},
-                '1865': {'last_update': 9999999999}
+                '151': {
+                    'version_id': 100, 'last_update': 9999999999, 'title': 'MySEQ Open',
+                    'parent_category_id': 11,
+                    'current_files': [{'id': 1001, 'filename': 'myseqserver.ini',
+                                       'download_url': 'https://example.com/myseqserver.ini', 'hash': 'abc123'}],
+                },
+                '153': {
+                    'version_id': 200, 'last_update': 9999999999, 'title': "Brewall's Maps",
+                    'parent_category_id': 11,
+                    'current_files': [{'id': 1002, 'filename': 'brewall-maps_20241203.zip',
+                                       'download_url': 'https://example.com/brewall-maps.zip', 'hash': 'def456'}],
+                },
+                '1865': {
+                    'version_id': 300, 'last_update': 9999999999, 'title': 'MySEQ',
+                    'parent_category_id': 11,
+                    'current_files': [{'id': 1003, 'filename': 'myseq.zip',
+                                       'download_url': 'https://example.com/myseq.zip', 'hash': 'ghi789'}],
+                },
             }
         }
     
diff --git a/tests/test_sync_pipeline_regressions.py b/tests/test_sync_pipeline_regressions.py
diff --git a/tests/test_sync_queue_rules.py b/tests/test_sync_queue_rules.py
