shopping-cli 3.0.1__tar.gz → 3.0.2__tar.gz

{shopping_cli-3.0.1/shopping_cli.egg-info → shopping_cli-3.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shopping-cli
-Version: 3.0.1
+Version: 3.0.2
 Summary: Standalone local-commerce AI consultation marketplace runtime
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -209,13 +209,15 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: psutil>=5.9
 Provides-Extra: api
-Requires-Dist: fastapi>=0.110; extra == "api"
+Requires-Dist: fastapi>=0.141.1; extra == "api"
 Requires-Dist: pydantic>=2; extra == "api"
 Requires-Dist: uvicorn>=0.27; extra == "api"
 Provides-Extra: dev
 Requires-Dist: build>=1.2; extra == "dev"
 Requires-Dist: coverage[toml]>=7.6; extra == "dev"
+Requires-Dist: httpx>=0.28; extra == "dev"
 Requires-Dist: mypy>=1.11; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: ruff>=0.8; extra == "dev"
 Dynamic: license-file
 

{shopping_cli-3.0.1 → shopping_cli-3.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "shopping-cli"
-version = "3.0.1"
+version = "3.0.2"
 description = "Standalone local-commerce AI consultation marketplace runtime"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -20,17 +20,24 @@ shopping-cli-agent = "shopping_cli.agents.agent_cli:main"
 
 [project.optional-dependencies]
 api = [
-  "fastapi>=0.110",
+  "fastapi>=0.141.1",
   "pydantic>=2",
   "uvicorn>=0.27",
 ]
 dev = [
   "build>=1.2",
   "coverage[toml]>=7.6",
+  "httpx>=0.28",
   "mypy>=1.11",
+  "pytest>=8.0",
   "ruff>=0.8",
 ]
 
+[tool.uv]
+# Keep the optional API stack above the currently published Starlette security
+# floor while retaining an upper bound for deliberate compatibility upgrades.
+constraint-dependencies = ["fastapi>=0.141.1,<0.142", "starlette>=1.3.1,<1.7", "uvicorn<0.36"]
+
 [tool.ruff]
 target-version = "py311"
 line-length = 120
@@ -58,3 +65,6 @@ omit = ["shopping_cli/__main__.py"]
 [tool.setuptools.packages.find]
 where = ["."]
 include = ["shopping_cli*"]
+
+[tool.setuptools.package-data]
+shopping_cli = ["contracts/*.json"]

{shopping_cli-3.0.1 → shopping_cli-3.0.2}/shopping_cli/__init__.py

@@ -1,3 +1,3 @@
 """Standalone shopping-cli consultation runtime."""
 
-VERSION = "3.0.1"
+VERSION = "3.0.2"

{shopping_cli-3.0.1 → shopping_cli-3.0.2}/shopping_cli/agents/buyer_cli.py

@@ -131,7 +131,12 @@ def summarize(conn: sqlite3.Connection, conversation_id: str) -> dict[str, Any]:
             missing_facts.append("merchant contact")
         if not option["delivery"].get("service_area"):
             missing_facts.append("delivery rule")
-        if option["stock"] <= 0:
+        # 审查 P2-1：公开投影只携带 availability_hint（精确库存不下发）；
+        # 历史快照可能仍是旧形状（stock），两者都按"缺货"语义处理。
+        stock = option.get("stock")
+        if stock is None:
+            stock = 0 if option.get("availability_hint") == "out_of_stock" else 1
+        if stock <= 0:
             warnings.append("Product is out of stock.")
     warnings.extend(status_warnings(conversation))
     for flag in conversation["flags"]:

{shopping_cli-3.0.1 → shopping_cli-3.0.2}/shopping_cli/agents/merchant_daemon.py

@@ -1,9 +1,18 @@
-"""Local lifecycle management for resident merchant-agent processes."""
+"""Local lifecycle management for resident merchant-agent processes.
+
+Pure path-naming / id-sanitization / counter-coercion / error-classification
+helpers moved move-only to :mod:`shopping_cli.agents.merchant_state_helpers`;
+the public names are re-exported here (``as`` aliases) so
+``merchant_daemon.safe_merchant_id`` / ``agent_paths`` / ``safe_replied_count``
+/ ``permanent_agent_error`` / ``state_dir_from`` / ``DEFAULT_STATE_DIR`` keep
+their exact surface, path naming, return types and call order. This module
+still owns process start/stop, PID-file locking, signals, log rotation/tailing,
+state file I/O and the process loop.
+"""
 
 from __future__ import annotations
 
 import json
-import hashlib
 import os
 import secrets
 import signal
@@ -30,10 +39,17 @@ except ImportError:  # pragma: no cover - optional runtime dependency
     psutil = None
 
 from shopping_cli.agents import merchant_agent
+from shopping_cli.agents.merchant_state_helpers import (
+    DEFAULT_STATE_DIR as DEFAULT_STATE_DIR,
+    agent_paths as agent_paths,
+    permanent_agent_error as permanent_agent_error,
+    safe_merchant_id as safe_merchant_id,
+    safe_replied_count as safe_replied_count,
+    state_dir_from as state_dir_from,
+)
 from shopping_cli.db.session import db_session, decode_json, now_iso
 from shopping_cli.core.limits import safe_non_negative_int, safe_positive_float, safe_non_negative_float_with_max as safe_non_negative_float
 
-DEFAULT_STATE_DIR = Path.home() / ".local" / "state" / "shopping-cli"
 MAX_AGENT_INTERVAL_SECONDS = 3600.0
 MAX_AGENT_STOP_TIMEOUT_SECONDS = 300.0
 MAX_AGENT_LOG_TAIL = 1000
@@ -42,30 +58,6 @@ MAX_AGENT_LOG_BACKUPS = 3
 MAX_AGENT_ERROR_BACKOFF_SECONDS = 60.0
 
 
-def state_dir_from(value: str | Path | None = None) -> Path:
-    return Path(value or os.environ.get("SHOPPING_CLI_STATE_DIR") or DEFAULT_STATE_DIR).expanduser()
-
-
-def safe_merchant_id(merchant_id: str) -> str:
-    raw = str(merchant_id or "")
-    slug = "".join(ch if ch.isalnum() or ch in {"-", "_", "."} else "_" for ch in raw).strip("._-")
-    slug = (slug or "merchant")[:64]
-    digest = hashlib.sha256(raw.encode("utf-8")).hexdigest()[:16]
-    return f"{slug}-{digest}"
-
-
-def agent_paths(merchant_id: str, state_dir: str | Path | None = None) -> dict[str, Path]:
-    root = state_dir_from(state_dir)
-    safe_id = safe_merchant_id(merchant_id)
-    return {
-        "state_dir": root,
-        "pid_file": root / "agents" / f"{safe_id}.pid",
-        "state_file": root / "agents" / f"{safe_id}.state.json",
-        "stop_file": root / "agents" / f"{safe_id}.stop",
-        "log_file": root / "logs" / f"{safe_id}.log",
-    }
-
-
 def ensure_agent_dirs(paths: dict[str, Path]) -> None:
     paths["pid_file"].parent.mkdir(parents=True, exist_ok=True)
     paths["state_file"].parent.mkdir(parents=True, exist_ok=True)
@@ -86,9 +78,25 @@ def rotate_agent_log(log_file: Path) -> bool:
         if source.exists():
             source.replace(log_file.with_suffix(log_file.suffix + f".{index + 1}"))
     log_file.replace(log_file.with_suffix(log_file.suffix + ".1"))
+    # 审查 P2-07：rename 保留源文件权限——旧日志若世界可读，备份必须 0600
+    for index in range(1, MAX_AGENT_LOG_BACKUPS + 1):
+        backup = log_file.with_suffix(log_file.suffix + f".{index}")
+        if backup.exists():
+            os.chmod(backup, 0o600)
     return True
 
 
+def _open_log_append(log_path: Path):
+    """以 0600 创建/复用 daemon 日志文件。
+
+    审查 P2-07：日志含会话内容，且 os.open 的 mode 只在新建时生效——对
+    已存在文件也要显式 chmod 0600。
+    """
+    fd = os.open(str(log_path), os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o600)
+    os.chmod(log_path, 0o600)
+    return os.fdopen(fd, "ab", buffering=0)
+
+
 def _redirect_stdout_to(log_path: Path) -> None:
     """Repoint stdout at a freshly rotated log file.
 
@@ -99,7 +107,10 @@ def _redirect_stdout_to(log_path: Path) -> None:
         target_fd = sys.stdout.fileno()
     except (OSError, ValueError):
         return
-    fd = os.open(str(log_path), os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o644)
+    # 审查 P3/P2-07：日志含会话内容——0600，避免多用户机器上世界可读；
+    # mode 只对新文件生效，已存在文件同样 chmod。
+    fd = os.open(str(log_path), os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o600)
+    os.chmod(log_path, 0o600)
     try:
         os.dup2(fd, target_fd)
     finally:
@@ -137,24 +148,23 @@ def read_json(path: Path, default: Any) -> Any:
     return decoded
 
 
-
-
-
-def safe_replied_count(value: Any) -> int:
-    if not isinstance(value, list):
-        return 0
-    return len(value)
-
-
-def permanent_agent_error(error: str) -> bool:
-    lowered = str(error or "").lower()
-    return any(marker in lowered for marker in ("invalid authorization", "revoked authorization", "expired authorization", "token required", "unknown merchant"))
-
-
 def write_json_atomic(path: Path, value: Any) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
     tmp = path.with_name(f"{path.name}.tmp")
     tmp.write_text(json.dumps(value, ensure_ascii=False, indent=2, sort_keys=True), encoding="utf-8")
+    # 审查 P3：pid/state 文件含 launch_token —— 0600（此前继承 umask 0644
+    # 世界可读）。原子替换前 chmod，rename 后权限即为目标值。
+    os.chmod(tmp, 0o600)
+    tmp.replace(path)
+
+
+def _write_private_text(path: Path, text: str) -> None:
+    """原子写凭据类文本文件并强制 0600（审查 P2-07：stop 文件含
+    launch_token，open() 默认 mode 继承 umask 可能世界可读）。"""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(f"{path.name}.tmp")
+    tmp.write_text(text, encoding="utf-8")
+    os.chmod(tmp, 0o600)
     tmp.replace(path)
 
 
@@ -472,7 +482,9 @@ def start_agent(
             elif merchant_token:
                 env["SHOPPING_MERCHANT_TOKEN"] = merchant_token
                 env.pop("SHOPPING_AGENT_TOKEN", None)
-        with paths["log_file"].open("ab", buffering=0) as log:
+        # 审查 P2-07：新建/已存在的日志文件都须 0600（open() 默认 mode 继承
+        # umask，多用户机器上可能 0644 世界可读）
+        with _open_log_append(paths["log_file"]) as log:
             process = subprocess.Popen(
                 command,
                 stdin=subprocess.DEVNULL,
@@ -568,8 +580,9 @@ def stop_agent(
         )
 
     if was_running:
-        paths["stop_file"].parent.mkdir(parents=True, exist_ok=True)
-        paths["stop_file"].write_text(launch_token, encoding="utf-8")
+        # 审查 P2-07：stop 文件含 launch_token——0600（open() 默认 mode 会
+        # 继承 umask 0644 世界可读）
+        _write_private_text(paths["stop_file"], launch_token)
         if psutil is not None:
             try:
                 os.kill(pid, signal.SIGTERM)

shopping_cli-3.0.2/shopping_cli/agents/merchant_state_helpers.py

@@ -0,0 +1,58 @@
+"""Pure merchant-daemon state helpers: path naming, id sanitization, counters.
+
+Move-only extraction from :mod:`shopping_cli.agents.merchant_daemon`: this leaf
+module owns the merchant-id sanitization (path isolation via slug + digest),
+the state/log/pid/stop file path naming, the replied-count coercion and the
+permanent-error classification. It never starts or stops processes, takes
+locks, installs signal handlers, touches the database or network, writes files,
+or drives state transitions — everything here is a pure function of its
+inputs plus the ``SHOPPING_CLI_STATE_DIR`` environment override.
+
+The parent module re-exports these names unchanged (``as`` aliases) so the
+public ``merchant_daemon`` surface, path naming, return types and call order
+are preserved.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from pathlib import Path
+from typing import Any
+
+DEFAULT_STATE_DIR = Path.home() / ".local" / "state" / "shopping-cli"
+
+
+def state_dir_from(value: str | Path | None = None) -> Path:
+    return Path(value or os.environ.get("SHOPPING_CLI_STATE_DIR") or DEFAULT_STATE_DIR).expanduser()
+
+
+def safe_merchant_id(merchant_id: str) -> str:
+    raw = str(merchant_id or "")
+    slug = "".join(ch if ch.isalnum() or ch in {"-", "_", "."} else "_" for ch in raw).strip("._-")
+    slug = (slug or "merchant")[:64]
+    digest = hashlib.sha256(raw.encode("utf-8")).hexdigest()[:16]
+    return f"{slug}-{digest}"
+
+
+def agent_paths(merchant_id: str, state_dir: str | Path | None = None) -> dict[str, Path]:
+    root = state_dir_from(state_dir)
+    safe_id = safe_merchant_id(merchant_id)
+    return {
+        "state_dir": root,
+        "pid_file": root / "agents" / f"{safe_id}.pid",
+        "state_file": root / "agents" / f"{safe_id}.state.json",
+        "stop_file": root / "agents" / f"{safe_id}.stop",
+        "log_file": root / "logs" / f"{safe_id}.log",
+    }
+
+
+def safe_replied_count(value: Any) -> int:
+    if not isinstance(value, list):
+        return 0
+    return len(value)
+
+
+def permanent_agent_error(error: str) -> bool:
+    lowered = str(error or "").lower()
+    return any(marker in lowered for marker in ("invalid authorization", "revoked authorization", "expired authorization", "token required", "unknown merchant"))

{shopping_cli-3.0.1 → shopping_cli-3.0.2}/shopping_cli/agents/tools.py

@@ -260,6 +260,7 @@ class HTTPMerchantAgentTools:
         merchant_token: str,
         timeout: float = 10.0,
         opener: Any | None = None,
+        transport: Any | None = None,
         host: str = "",
         session_id: str = "",
         allow_insecure_http: bool = False,
@@ -275,6 +276,7 @@ class HTTPMerchantAgentTools:
             self.merchant_token,
             timeout=timeout,
             opener=opener,
+            transport=transport,
             allow_insecure_http=allow_insecure_http,
         )
         self.base_url = self.http.base_url

shopping_cli-3.0.2/shopping_cli/api/app.py

@@ -0,0 +1,121 @@
+"""Marketplace API app factory.
+
+FastAPI is used when installed. The lightweight fallback keeps route metadata
+available for local tests in environments where optional API dependencies have
+not been installed yet.
+
+装配拆分（move-only，行为不变）：可执行路由表与 handler wrapper 在
+``api.route_table``（_ROUTE_TABLE / resolve_route），FastAPI 路由安装与
+header 默认值在 ``api.fastapi_routes``（register_fastapi_routes）。本模块
+保留公共门面——create_app / handle_request / _ROUTE_TABLE / RouteEntry /
+resolve_route / FastAPI / AUTHORIZATION_HEADER / IDEMPOTENCY_KEY_HEADER——
+route_registry、fallback ASGI 与既有导入方不变。
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+from shopping_cli import VERSION
+from shopping_cli.api.fallback_asgi import MarketplaceASGIApp
+from shopping_cli.api.fastapi_routes import (
+    AUTHORIZATION_HEADER,  # noqa: F401 - compat re-export for external importers
+    FastAPI,
+    Header,  # noqa: F401 - compat re-export for external importers
+    IDEMPOTENCY_KEY_HEADER,  # noqa: F401 - compat re-export for external importers
+    JSONResponse,  # noqa: F401 - compat re-export for external importers
+    Request,  # noqa: F401 - compat re-export for external importers
+    RequestValidationError,  # noqa: F401 - compat re-export for external importers
+    Response,  # noqa: F401 - compat re-export for external importers
+    StarletteHTTPException,  # noqa: F401 - compat re-export for external importers
+    register_fastapi_routes,
+)
+from shopping_cli.api.limits import validate_payload
+from shopping_cli.api.request_dispatch import (
+    RouteEntry,  # noqa: F401 - compat re-export for external importers
+    dispatch_request,
+)
+from shopping_cli.api.request_limits import (
+    ASGIApp as _ASGIApp,  # noqa: F401 - compat re-export for external importers
+    ASGIReceive as _ASGIReceive,  # noqa: F401 - compat re-export for external importers
+    ASGISend as _ASGISend,  # noqa: F401 - compat re-export for external importers
+    RequestBodyLimitMiddleware as _RequestBodyLimitMiddleware,  # noqa: F401 - compat re-export for external importers
+)
+from shopping_cli.api.route_table import _ROUTE_TABLE, resolve_route
+from shopping_cli.core.errors import (
+    AuthError,
+    ConflictError,
+    IdempotencyConflict,
+    MethodNotAllowedError,
+    NotFoundError,
+    PermissionDenied,
+    RateLimitError,
+    PayloadTooLargeError,
+    ShoppingCliError,
+    ValidationError,
+)
+
+logger = logging.getLogger("shopping-cli")
+
+
+def handle_request(
+    db_path: str | Path,
+    method: str,
+    path: str,
+    payload: dict[str, Any] | None = None,
+    query: dict[str, Any] | None = None,
+) -> tuple[int, dict[str, Any]]:
+    payload = payload or {}
+    query = query or {}
+    try:
+        validate_payload(payload)
+        return dispatch_request(db_path, method, path, payload, query, _ROUTE_TABLE)
+    except AuthError as exc:
+        return 403, {"ok": False, "error": str(exc)}
+    except PermissionDenied as exc:
+        return 403, {"ok": False, "error": str(exc)}
+    except IdempotencyConflict as exc:
+        return 409, {"ok": False, "error": str(exc)}
+    except ConflictError as exc:
+        return 409, {"ok": False, "error": str(exc)}
+    except NotFoundError as exc:
+        return 404, {"ok": False, "error": str(exc)}
+    except RateLimitError as exc:
+        return 429, {"ok": False, "error": str(exc)}
+    except PayloadTooLargeError as exc:
+        return 413, {"ok": False, "error": str(exc)}
+    except MethodNotAllowedError as exc:
+        return 405, {"ok": False, "error": str(exc)}
+    except ValidationError as exc:
+        return 400, {"ok": False, "error": str(exc)}
+    except ShoppingCliError as exc:
+        return 400, {"ok": False, "error": str(exc)}
+    except Exception:
+        logger.exception("unhandled error handling %s %s", method, path)
+        return 500, {"ok": False, "error": "internal server error"}
+
+
+def create_app(db_path: str | Path = "shopping-cli.sqlite") -> Any:
+    from shopping_cli.api.route_registry import route_info
+
+    routes = route_info()
+    if FastAPI is None:
+        return MarketplaceASGIApp(
+            db_path,
+            route_provider=lambda: routes,
+            route_resolver=lambda method, path: resolve_route(method, path, routes=routes),
+        )
+
+    app = FastAPI(
+        title="shopping-cli Marketplace API",
+        version=VERSION,
+        docs_url=None,
+        redoc_url=None,
+        openapi_url=None,
+    )
+    app.state.db_path = str(db_path)
+    app.state.fastapi_available = True
+    register_fastapi_routes(app, db_path)
+    return app

shopping_cli-3.0.2/shopping_cli/api/error_handlers.py

@@ -0,0 +1,117 @@
+"""FastAPI exception-handler registration for the marketplace API.
+
+Centralizes the business exception → HTTP mapping (status code, JSON envelope,
+error string) that :func:`shopping_cli.api.app.create_app` used to register
+inline, so the transport layer only wires the registration in. This module has
+no hard dependency on FastAPI: the response factory and the optional
+Starlette/FastAPI exception types are injected by the caller, matching how the
+dual API stack isolates optional imports (see ``app.py``'s try/except import
+block).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from shopping_cli.api.error_response import build_error_response
+from shopping_cli.core.errors import (
+    AuthError,
+    ConflictError,
+    IdempotencyConflict,
+    MethodNotAllowedError,
+    NotFoundError,
+    PayloadTooLargeError,
+    PermissionDenied,
+    RateLimitError,
+    ShoppingCliError,
+    ValidationError,
+)
+
+logger = logging.getLogger("shopping-cli")
+
+
+def _json_error_response(json_response: Any, status_code: int, error: str) -> Any:
+    return build_error_response(status_code, error, json_response)
+
+
+def register_error_handlers(
+    app: Any,
+    *,
+    json_response: Any = None,
+    request_validation_error: Any = None,
+    starlette_http_exception: Any = None,
+) -> None:
+    """Register business and transport error handlers on *app*.
+
+    *app* must expose ``exception_handler`` (a FastAPI app or a test double).
+    ``json_response`` is the FastAPI ``JSONResponse`` class, or ``None`` when
+    FastAPI is not installed (handlers then return the fallback
+    ``SimpleNamespace`` envelope). ``request_validation_error`` and
+    ``starlette_http_exception`` are the optional FastAPI/Starlette exception
+    types; passing ``None`` skips those handlers, mirroring ``app.py``'s
+    conditional registration.
+
+    Registration order is load-bearing: specific business exceptions come
+    before their base classes and before the catch-all ``Exception`` handler,
+    so a first-match handler walk (as done by the FakeFastAPI test harness)
+    resolves a subclass to its own status rather than a base class's.
+    """
+    @app.exception_handler(AuthError)
+    def auth_error_handler(_request: Any, exc: AuthError) -> Any:
+        return _json_error_response(json_response, 403, str(exc))
+
+    @app.exception_handler(PermissionDenied)
+    def permission_denied_handler(_request: Any, exc: PermissionDenied) -> Any:
+        return _json_error_response(json_response, 403, str(exc))
+
+    @app.exception_handler(IdempotencyConflict)
+    def idempotency_conflict_handler(_request: Any, exc: IdempotencyConflict) -> Any:
+        return _json_error_response(json_response, 409, str(exc))
+
+    @app.exception_handler(ConflictError)
+    def conflict_error_handler(_request: Any, exc: ConflictError) -> Any:
+        return _json_error_response(json_response, 409, str(exc))
+
+    @app.exception_handler(NotFoundError)
+    def not_found_error_handler(_request: Any, exc: NotFoundError) -> Any:
+        return _json_error_response(json_response, 404, str(exc))
+
+    @app.exception_handler(RateLimitError)
+    def rate_limit_error_handler(_request: Any, exc: RateLimitError) -> Any:
+        return _json_error_response(json_response, 429, str(exc))
+
+    @app.exception_handler(PayloadTooLargeError)
+    def payload_too_large_handler(_request: Any, exc: PayloadTooLargeError) -> Any:
+        return _json_error_response(json_response, 413, str(exc))
+
+    @app.exception_handler(MethodNotAllowedError)
+    def method_not_allowed_handler(_request: Any, exc: MethodNotAllowedError) -> Any:
+        return _json_error_response(json_response, 405, str(exc))
+
+    @app.exception_handler(ValidationError)
+    def validation_error_handler(_request: Any, exc: ValidationError) -> Any:
+        return _json_error_response(json_response, 400, str(exc))
+
+    @app.exception_handler(ShoppingCliError)
+    def shopping_cli_error_handler(_request: Any, exc: ShoppingCliError) -> Any:
+        return _json_error_response(json_response, 400, str(exc))
+
+    if request_validation_error is not None:  # pragma: no cover - exercised with fastapi installed
+        @app.exception_handler(request_validation_error)
+        def request_validation_error_handler(request: Any, exc: Exception) -> Any:
+            # 不回显 str(exc)：包含 schema 内部结构并回显调用方输入。
+            logger.warning("request validation failed on %s: %s", getattr(request, "url", "?"), exc)
+            return _json_error_response(json_response, 400, "invalid request body")
+
+    if starlette_http_exception is not None:  # pragma: no cover - exercised with fastapi installed
+        @app.exception_handler(starlette_http_exception)
+        def http_exception_handler(_request: Any, exc: Any) -> Any:
+            status = int(exc.status_code)
+            message = "not found" if status == 404 else "method not allowed" if status == 405 else str(exc.detail)
+            return _json_error_response(json_response, status, message)
+
+    @app.exception_handler(Exception)
+    def unexpected_error_handler(request: Any, exc: Exception) -> Any:
+        logger.exception("unhandled error on %s %s", getattr(request, "method", "?"), getattr(request, "url", "?"))
+        return _json_error_response(json_response, 500, "internal server error")

shopping_cli-3.0.2/shopping_cli/api/error_response.py

@@ -0,0 +1,22 @@
+"""Transport-only error response construction for the dual API stack."""
+
+from __future__ import annotations
+
+import json
+from types import SimpleNamespace
+from typing import Any, Callable
+
+
+def build_error_response(
+    status_code: int,
+    error: str,
+    response_factory: Callable[..., Any] | None = None,
+) -> Any:
+    """Build the existing JSON error envelope for FastAPI or fallback mode."""
+    payload = {"ok": False, "error": error}
+    if response_factory is not None:
+        return response_factory(status_code=status_code, content=payload)
+    return SimpleNamespace(
+        status_code=status_code,
+        body=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
+    )