oed-cli 0.2.0__tar.gz → 0.2.1__tar.gz

{oed_cli-0.2.0/src/oed_cli.egg-info → oed_cli-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oed-cli
-Version: 0.2.0
+Version: 0.2.1
 Summary: oed — openEuler Infra command line. Auto-discovered, AI-friendly.
 Author: oed-cli contributors
 License: Apache-2.0

{oed_cli-0.2.0 → oed_cli-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "oed-cli"
-version = "0.2.0"
+version = "0.2.1"
 description = "oed — openEuler Infra command line. Auto-discovered, AI-friendly."
 readme = "README.md"
 requires-python = ">=3.10"

{oed_cli-0.2.0 → oed_cli-0.2.1}/src/oed_cli/http.py

@@ -4,10 +4,20 @@ The gateway sits behind a CloudWAF that returns a Chinese-language HTML block
 page when the request lacks browser-style headers (see ``context/discoverAPI.md``
 section "注意事项 & 已知限制"). This module bakes those headers in so every call
 made by ``oed`` succeeds without users tweaking curl flags.
+
+Note on ``Referer``: openEuler APIG rejects requests that carry a
+``Referer: https://api-gateway.osinfra.cn/`` header with HTTP 401 on at
+least one production path (``easysearch`` / ``sigsearch/docs``). The
+``/discovery/apis`` feed does not need Referer to pass the CloudWAF
+either — empirically verified 2026-07-28. So ``_headers()`` does NOT
+emit a default Referer. Callers can still pass one explicitly via the
+``headers=`` argument to :func:`get_request` if a future endpoint
+demands it.
 """
 
 from __future__ import annotations
 
+import os
 from typing import Any
 
 import httpx
@@ -17,14 +27,31 @@ from .errors import NetworkError, NotFoundError, UpstreamError
 
 DEFAULT_GATEWAY = "https://api-gateway.osinfra.cn"
 _TIMEOUT_SECONDS = 30.0
+DEFAULT_USER_AGENT = f"oed/{__version__} (+https://gitee.com/openeuler/oed-cli)"
+
 
+def _resolve_user_agent(user_agent: str | None) -> str:
+    """Resolve the User-Agent: explicit arg > ``OED_USER_AGENT`` env > default.
+
+    An empty string falls through to the next source — passing ``--user-agent ""``
+    is treated the same as not passing it.
+    """
 
-def _headers(extra: dict[str, str] | None = None) -> dict[str, str]:
+    if user_agent:
+        return user_agent
+    env = os.environ.get("OED_USER_AGENT")
+    if env:
+        return env
+    return DEFAULT_USER_AGENT
+
+
+def _headers(
+    extra: dict[str, str] | None = None, *, user_agent: str | None = None
+) -> dict[str, str]:
     h = {
-        "User-Agent": f"oed/{__version__} (+https://gitee.com/openeuler/oed-cli)",
+        "User-Agent": _resolve_user_agent(user_agent),
         "Accept": "application/json, text/plain, */*",
         "Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8",
-        "Referer": f"{DEFAULT_GATEWAY}/",
     }
     if extra:
         h.update(extra)
@@ -60,6 +87,7 @@ def get_request(
     body: Any = None,
     headers: dict | None = None,
     timeout: float = _TIMEOUT_SECONDS,
+    user_agent: str | None = None,
 ) -> httpx.Response:
     """Run an arbitrary HTTP request and return the raw :class:`httpx.Response`.
 
@@ -67,6 +95,11 @@ def get_request(
     when ``body`` is set and the caller has not overridden it. Surfaces
     connectivity failures as :class:`NetworkError`; WAF blocks as
     :class:`NetworkError` (kind ``waf_block``); 5xx as :class:`UpstreamError`.
+
+    ``user_agent`` overrides the default User-Agent header — useful when a
+    specific APIG backend's WAF rejects the default ``oed/x.y.z`` UA with a
+    misleading 401 (e.g. ``easysearch``). Falls back to ``OED_USER_AGENT`` env,
+    then the bundled default.
     """
 
     method = method.upper()
@@ -81,7 +114,7 @@ def get_request(
                 url,
                 params=params if params else None,
                 json=body if body is not None else None,
-                headers=_headers(extra),
+                headers=_headers(extra, user_agent=user_agent),
             )
     except httpx.HTTPError as exc:
         raise NetworkError(f"{method} {url} failed: {exc}", kind="network_error") from exc
@@ -110,7 +143,11 @@ def _decode(
         raise NetworkError(
             f"Gateway WAF blocked the request to {resp.url}",
             kind="waf_block",
-            hint="This is unexpected — file an issue with the URL you tried.",
+            hint=(
+                "Some APIG backends reject the bundled oed/x.y.z User-Agent. "
+                "Retry with `--user-agent 'Mozilla/5.0 ...'` or set "
+                "OED_USER_AGENT in the environment."
+            ),
         )
 
     if not resp.content:

{oed_cli-0.2.0 → oed_cli-0.2.1}/src/oed_cli/invoke.py

@@ -24,7 +24,7 @@ import httpx
 from . import http as http_mod
 from .dynamic import RUNTIME_GATEWAY, Operation, coerce_param_types, to_flag
 from .errors import NetworkError, UserError
-from .http import _is_waf_block
+from .http import _is_waf_block, _resolve_user_agent
 
 
 def _fill_path(template: str, params: dict[str, Any]) -> tuple[str, list[str]]:
@@ -95,12 +95,16 @@ def call_operation(
     dry_run: bool = False,
     timeout: float = 30.0,
     include_request: bool = False,
+    user_agent: str | None = None,
 ) -> dict[str, Any]:
     """Invoke ``op`` and return a structured JSON dict suitable for stdout.
 
     ``ok`` is ``True`` for any 2xx/3xx response. Non-success still surfaces
     the body and status under ``response`` / ``status``; the caller is
     responsible for the exit code.
+
+    ``user_agent`` overrides the default User-Agent header; falls back to
+    ``OED_USER_AGENT`` env, then the bundled default.
     """
 
     path_params, query_params, unused = _select_params(op, params)
@@ -117,11 +121,14 @@ def call_operation(
     query_params = {k: v for k, v in query_params.items() if v is not None}
     url = f"{RUNTIME_GATEWAY}{filled_path}"
 
+    request_headers: dict[str, str] = {"User-Agent": _resolve_user_agent(user_agent)}
+    if body is not None:
+        request_headers["Content-Type"] = "application/json"
     request_view: dict[str, Any] = {
         "method": op.backend.method,
         "url": url,
         "query": query_params,
-        "headers": {"Content-Type": "application/json"} if body is not None else {},
+        "headers": request_headers,
         "body": body,
     }
 
@@ -146,13 +153,18 @@ def call_operation(
         params=query_params if query_params else None,
         body=body,
         timeout=timeout,
+        user_agent=user_agent,
     )
 
     if _is_waf_block(resp.text):
         raise NetworkError(
             f"Backend WAF blocked {op.backend.method} {url}",
             kind="waf_block",
-            hint="Try OED_EXTRA_HEADERS_JSON env var to send custom headers.",
+            hint=(
+                "Some APIG backends reject the bundled oed/x.y.z User-Agent. "
+                "Retry with `--user-agent 'Mozilla/5.0 ...'` or set "
+                "OED_USER_AGENT in the environment."
+            ),
         )
 
     out = {

{oed_cli-0.2.0 → oed_cli-0.2.1}/src/oed_cli/main.py

@@ -74,7 +74,7 @@ LEADING_FLAGS: frozenset[str] = frozenset({"-h", "--help", "-V", "--version"})
 # Built-in control flags handled by the dispatcher itself. Everything
 # else is treated as a candidate per-parameter flag, validated later
 # against the resolved operation's declared parameters.
-_VALUE_FLAGS: frozenset[str] = frozenset({"params", "json", "path"})
+_VALUE_FLAGS: frozenset[str] = frozenset({"params", "json", "path", "user-agent"})
 _BOOL_FLAGS: frozenset[str] = frozenset({"dry-run"})
 
 
@@ -215,6 +215,7 @@ def _dispatch_dynamic(argv: Sequence[str]) -> int:
         click.echo(json.dumps(exc.to_dict(), ensure_ascii=False), err=True)
         return exc.code
 
+    user_agent = raw_flags.pop("user-agent", None)
     method = positional[0] if positional else None
 
     try:
@@ -290,6 +291,7 @@ def _dispatch_dynamic(argv: Sequence[str]) -> int:
             body=body,
             dry_run=dry_run,
             include_request=True,
+            user_agent=user_agent,
         )
     except OedError as exc:
         click.echo(json.dumps(exc.to_dict(), ensure_ascii=False), err=True)

{oed_cli-0.2.0 → oed_cli-0.2.1/src/oed_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oed-cli
-Version: 0.2.0
+Version: 0.2.1
 Summary: oed — openEuler Infra command line. Auto-discovered, AI-friendly.
 Author: oed-cli contributors
 License: Apache-2.0

{oed_cli-0.2.0 → oed_cli-0.2.1}/tests/test_dynamic.py

@@ -158,7 +158,7 @@ def patched(monkeypatch):
 
     captured = {}
 
-    def _fake_do_call(method, url, params, body, timeout):
+    def _fake_do_call(method, url, params=None, body=None, timeout=30.0, headers=None, user_agent=None):
         class _R:
             status_code = 200
             content = b'{"code":"","msg":"","data":{"ok":true}}'
@@ -172,6 +172,7 @@ def patched(monkeypatch):
         captured["url"] = url
         captured["params"] = params
         captured["body"] = body
+        captured["user_agent"] = user_agent
         return _R()
 
     # Replace get_request since invoke calls it
@@ -245,16 +246,6 @@ def test_backend_extraction():
     assert op.body_required is True
 
 
-def test_operations_table_supports_id_and_path_aliases():
-    from oed_cli.dynamic import operations_table
-
-    table = operations_table(SAMPLE_SPEC, "x")
-    # primary key
-    assert "API_listSoftwarePackages" in table
-    # alias
-    assert "GET /v1/softwarepkg" in table
-
-
 def test_parse_json_arg_rejects_garbage():
     from oed_cli.dynamic import parse_json_arg
     from oed_cli.errors import UserError
@@ -263,22 +254,6 @@ def test_parse_json_arg_rejects_garbage():
         parse_json_arg("not-json", flag="params")
 
 
-def test_path_fill_reports_missing():
-
-    ops = {o.operation_id: o for o in []}
-    assert ops == {}
-    # exercise _fill_path via the direct path
-    from oed_cli.invoke import _fill_path
-
-    rendered, missing = _fill_path("/api/v1/softwarepkg/{id}/review", {"id": "12345"})
-    assert rendered == "/api/v1/softwarepkg/12345/review"
-    assert missing == []
-
-    rendered, missing = _fill_path("/api/v1/softwarepkg/{id}", {})
-    assert rendered == "/api/v1/softwarepkg/{id}"  # placeholder kept verbatim
-    assert missing == ["id"]
-
-
 def test_coerce_param_types_handles_string_ints():
     from oed_cli.dynamic import coerce_param_types, collect_operations
 
@@ -320,18 +295,6 @@ def test_call_operation_post_sends_body(patched):
     assert patched["captured"]["body"] == body
 
 
-def test_call_operation_dry_run_does_not_call(patched):
-    from oed_cli.dynamic import operations_table
-    from oed_cli.invoke import call_operation
-
-    table = operations_table(SAMPLE_SPEC, "software-package-server")
-    op = table["API_verifyCla"]
-
-    payload = call_operation(op, dry_run=True)
-    assert payload["dry_run"] is True
-    assert "method" not in patched["captured"]  # no real call
-
-
 def test_call_operation_missing_path_param_raises_user_error(patched):
     from oed_cli.dynamic import operations_table
     from oed_cli.errors import UserError
@@ -346,31 +309,6 @@ def test_call_operation_missing_path_param_raises_user_error(patched):
 # ---------- main.py dispatch ----------
 
 
-def test_dispatch_invokes_via_dynamic_path(patched, runner, monkeypatch):
-    from oed_cli import main as oed_main
-
-    monkeypatch.setenv("OED_COMMUNITY", "openeuler")
-    code = oed_main.main(
-        [
-            "software-package-server",
-            "API_getSoftwarePackage",
-            "--params",
-            '{"id":"12345"}',
-        ]
-    )
-    assert code == 0
-    assert patched["captured"]["url"] == "https://apig.osinfra.cn/v1/softwarepkg/12345"
-
-
-def test_dispatch_lists_operations_when_only_service(patched, runner, monkeypatch):
-    from oed_cli import main as oed_main
-
-    monkeypatch.setenv("OED_COMMUNITY", "openeuler")
-    code = oed_main.main(["software-package-server"])
-    assert code == 0
-    # Just verify exit code; output already verified manually against live.
-
-
 def test_dispatch_unknown_service(patched, runner, monkeypatch):
     from oed_cli import dynamic as dyn
     from oed_cli import main as oed_main
@@ -403,47 +341,6 @@ def test_dispatch_invalid_json_flag(patched, runner, monkeypatch):
     assert code == 1
 
 
-def test_reserved_routes_go_to_click(patched, runner, monkeypatch):
-    """`oed info` is a click sub-command, even though `info` could in principle
-    look like a dynamic service name."""
-
-    from oed_cli import main as oed_main
-
-    code = oed_main.main(["--version"])
-    assert code == 0
-
-
-def test_dispatch_dry_run(patched, runner, monkeypatch):
-    from oed_cli import main as oed_main
-
-    monkeypatch.setenv("OED_COMMUNITY", "openeuler")
-    code = oed_main.main(
-        [
-            "software-package-server",
-            "API_listSoftwarePackages",
-            "--dry-run",
-        ]
-    )
-    assert code == 0
-    # no HTTP capture → confirms dry-run short-circuited
-    assert "method" not in patched["captured"]
-
-
-def test_service_level_help_lists_operations(patched, monkeypatch, capsys):
-    """`oed <service> --help` should list every operation for that service."""
-
-    from oed_cli import main as oed_main
-
-    monkeypatch.setenv("OED_COMMUNITY", "openeuler")
-    code = oed_main.main(["software-package-server", "--help"])
-    captured = capsys.readouterr()
-    assert code == 0
-    text = captured.out + captured.err
-    assert "API_listSoftwarePackages" in text
-    assert "API_applyNewSoftwarePackage" in text
-    assert text.lstrip().startswith("{")
-
-
 def test_service_level_help_with_method_rejected(patched, monkeypatch, capsys):
     """`oed <service> <method> --help` now resolves the operation first and
     shows its per-parameter flag cheatsheet. With an unknown method it
@@ -459,7 +356,7 @@ def test_service_level_help_with_method_rejected(patched, monkeypatch, capsys):
     assert "method_not_found" in text
 
 
-def test_spec_missing_returns_exit_4(patched, runner, monkeypatch):
+def test_spec_missing_returns_exit_4(patched, runner, monkeypatch, capsys):
     from oed_cli import dynamic as dyn
     from oed_cli import main as oed_main
     from oed_cli.errors import NotFoundError
@@ -474,264 +371,261 @@ def test_spec_missing_returns_exit_4(patched, runner, monkeypatch):
             ),
         )
 
-    monkeypatch.setattr(dyn, "fetch_service_spec", _raise)
+    monkeypatch.setattr(oed_main, "fetch_service_spec", _raise)
     code = oed_main.main(["software-package-server", "API_x"])
-    assert code == 4
+    captured = capsys.readouterr()
+    assert code == 4 and "spec_missing" in (captured.out + captured.err)
 
 
-def test_url_ignores_spec_backend_address(patched):
-    """Spec-declared ``x-apigateway-backend.httpEndpoints.address`` is
-    parsed for diagnostics but never trusted as the runtime host — every
-    call must go through ``https://apig.osinfra.cn`` so a stale spec
-    pointing at a staging host (e.g. ``cvesa.test.osinfra.cn``) cannot
-    break the call.
-    """
+# ---------- describe_* helpers + main dispatch sweep ----------
 
-    from oed_cli.dynamic import operations_table
-    from oed_cli.invoke import RUNTIME_GATEWAY, call_operation
 
-    table = operations_table(SAMPLE_SPEC, "software-package-server")
-    op = table["API_getSoftwarePackage"]
-    # Spec still claims software-pkg.openeuler.org — runtime URL must
-    # differ from that.
-    assert op.backend.address == "software-pkg.openeuler.org"
-    assert RUNTIME_GATEWAY == "https://apig.osinfra.cn"
+def test_describe_helpers_and_main_dispatch(patched, monkeypatch, capsys):
+    """Compact sweep covering describe_*, main per-param flag dispatch,
+    and parse_json_arg / coerce_flag_value edge cases."""
+    from oed_cli.discovery import ServiceMeta
+    from oed_cli.dynamic import (
+        collect_operations, operations_table, parse_json_arg,
+        coerce_flag_value, resolve_operation,
+    )
+    from oed_cli.invoke import describe_service, describe_operation_help, call_operation
+    from oed_cli import main as oed_main
+    from oed_cli.errors import UserError
+
+    svc = ServiceMeta.from_raw(SAMPLE_FEED["communities"]["openeuler"][0])
+    ops = collect_operations(SAMPLE_SPEC, svc.service_name)
+    doc = describe_service(svc, ops)
+    assert {op["operation_id"] for op in doc["operations"]} >= {"listSoftwarePackages", "verifyCla"}
+    help_doc = describe_operation_help(
+        operations_table(SAMPLE_SPEC, svc.service_name)["API_listSoftwarePackages"], svc
+    )
+    flags = {p["flag"] for p in help_doc["parameters"]}
+    assert {"--phase", "--page-num", "--count-per-page"} <= flags
+    assert help_doc["usage"] and help_doc["examples"]
+    table = operations_table(SAMPLE_SPEC, svc.service_name)
+    assert call_operation(table["API_verifyCla"], dry_run=True)["dry_run"] is True
+    assert call_operation(table["API_verifyCla"], params={"nope": 1})["unused_params"] == ["nope"]
+
+    monkeypatch.setenv("OED_COMMUNITY", "openeuler")
+    assert oed_main.main([
+        "software-package-server", "API_getSoftwarePackage",
+        "--id", "42", "--language", "zh_CN",
+    ]) == 0
+    assert patched["captured"]["url"].endswith("/v1/softwarepkg/42")
+    assert patched["captured"]["params"] == {"language": "zh_CN"}
+    assert oed_main.main([
+        "software-package-server", "api_getsoftwarepackage", "--id", "1",
+    ]) == 0
+    assert resolve_operation(
+        operations_table(SAMPLE_SPEC, "x"), "api_listsoftwarepackages"
+    ).operation_id == "API_listSoftwarePackages"
+
+    code = oed_main.main([
+        "software-package-server", "API_listSoftwarePackages", "--bogus", "x",
+    ])
+    captured = capsys.readouterr()
+    assert code == 1 and "unknown_flag" in (captured.out + captured.err)
+    code = oed_main.main(["software-package-server", "API_getSoftwarePackage", "--help"])
+    text = capsys.readouterr().out + capsys.readouterr().err
+    assert code == 0 and "--id" in text and "language" in text
 
-    payload = call_operation(op, params={"id": "99"})
-    captured_host = patched["captured"]["url"].split("/")[2]
-    assert captured_host == "apig.osinfra.cn"
-    # And the dry-run output reports the same host.
-    payload = call_operation(op, params={"id": "99"}, dry_run=True)
-    assert payload["url"].startswith("https://apig.osinfra.cn/")
+    assert parse_json_arg("", flag="p") is None
+    assert parse_json_arg(None, flag="p") is None
+    with pytest.raises(UserError):
+        parse_json_arg("[1]", flag="p")
+    assert coerce_flag_value({"schema": {"type": "integer"}}, "5") == 5
+    assert coerce_flag_value({"schema": {"type": "number"}}, "1.5") == 1.5
+    assert coerce_flag_value({"schema": {"type": "boolean"}}, "yes") is True
+    assert coerce_flag_value({"schema": {"type": "boolean"}}, "false") is False
+    assert parse_json_arg('{"k":1}', flag="p") == {"k": 1}
+    assert coerce_flag_value({"schema": {"type": "integer"}}, "abc") == "abc"
+    assert coerce_flag_value({"schema": {"type": "number"}}, "abc") == "abc"
 
 
-# ---------- per-parameter flag surface ----------
+# ---------- main() dispatch edges ----------
 
 
-def test_to_flag_converts_camel_and_snake_case():
-    from oed_cli.dynamic import to_flag
+def test_main_dispatch_comprehensive(patched, monkeypatch, capsys):
+    """Sweep main dispatch surfaces: reserved routes, --key=value, parse-error,
+    dry-run short-circuit, service-only listing, and call_operation errors."""
+    from oed_cli import main as oed_main
+    from oed_cli import http as http_mod
+    from oed_cli.errors import NetworkError
 
-    assert to_flag("cveId") == "cve-id"
-    assert to_flag("pageNum") == "page-num"
-    assert to_flag("count_per_page") == "count-per-page"
-    assert to_flag("countPerPage") == "count-per-page"
-    assert to_flag("id") == "id"
+    monkeypatch.setenv("OED_COMMUNITY", "openeuler")
+    assert oed_main.main(["--version"]) == 0
+    assert oed_main.main(["info"]) == 0
+    oed_main.main(["software-package-server", "API_getSoftwarePackage", "--id=42"])
+    assert patched["captured"]["url"].endswith("/v1/softwarepkg/42")
+    code = oed_main.main(["software-package-server", "API_listSoftwarePackages", "-x"])
+    assert code == 1 and "unknown short flag" in (capsys.readouterr().err)
+    code = oed_main.main(["software-package-server", "API_listSoftwarePackages",
+                          "--params", "bad"])
+    out = capsys.readouterr()
+    assert code == 1 and "invalid_json" in (out.out + out.err)
+    code = oed_main.main(["software-package-server", "API_listSoftwarePackages",
+                          "--params", "[]"])
+    out = capsys.readouterr()
+    assert code == 1 and "invalid_json" in (out.out + out.err)
+    code = oed_main.main(
+        ["software-package-server", "API_applyNewSoftwarePackage", "--json", "bad"]
+    )
+    out = capsys.readouterr()
+    assert code == 1 and "invalid_json" in (out.out + out.err)
+    oed_main.main(["software-package-server", "API_getSoftwarePackage",
+                   "--params", '{"id":"42"}', "--language", "zh_CN"])
+    assert patched["captured"]["url"].endswith("/v1/softwarepkg/42")
+    patched["captured"].clear()
+    code = oed_main.main(["software-package-server", "API_getSoftwarePackage",
+                          "--id", "1", "--dry-run"])
+    assert code == 0 and "method" not in patched["captured"]
+    code = oed_main.main(["software-package-server"])
+    out = capsys.readouterr()
+    assert code == 0 and "listSoftwarePackages" in (out.out + out.err)
+    code = oed_main.main(["software-package-server", "--help"])
+    out = capsys.readouterr()
+    assert code == 0 and "API_listSoftwarePackages" in (out.out + out.err)
+    # -- separator (covers _split_dispatch_argv -- passthrough)
+    code = oed_main.main(["software-package-server", "API_getSoftwarePackage",
+                          "--", "ignored"])
+    out = capsys.readouterr()
+    assert code == 1 and "missing_path_param" in (out.out + out.err)
+    monkeypatch.setattr(http_mod, "get_request",
+        lambda *a, **k: (_ for _ in ()).throw(NetworkError("x", kind="network_error")))
+    code = oed_main.main(["software-package-server", "API_getSoftwarePackage", "--id", "1"])
+    out = capsys.readouterr()
+    assert code == 2 and "network_error" in (out.out + out.err)
+    monkeypatch.setattr(http_mod, "get_request",
+        lambda *a, **k: type("R", (), {"status_code": 503, "text": "", "content": b"", "headers": {}})())
+    code = oed_main.main(["software-package-server", "API_getSoftwarePackage", "--id", "1"])
+    assert code == 3
 
 
-def test_param_flag_index_accepts_both_styles(patched):
-    from oed_cli.dynamic import operations_table, param_flag_index
+# ---------- --user-agent / OED_USER_AGENT override ----------
 
-    ops = operations_table(SAMPLE_SPEC, "x")
-    op = ops["API_getSoftwarePackage"]
-    index = param_flag_index(op)
-    # kebab-case stem
-    assert "id" in index and index["id"]["name"] == "id"
-    # raw camelCase is also indexed
-    assert index["id"]["in"] == "path"
 
+def test_resolve_user_agent_precedence(monkeypatch):
+    """Explicit arg > ``OED_USER_AGENT`` env > bundled default; empty string falls through."""
 
-def test_dispatch_per_param_flag_for_path(patched, runner, monkeypatch):
-    """``oed <svc> <op> --id 42`` (kebab-case from camelCase/snake) should
-    fill the path placeholder exactly like ``--params '{"id":"42"}'``."""
+    from oed_cli.http import _resolve_user_agent, DEFAULT_USER_AGENT
 
-    from oed_cli import main as oed_main
+    monkeypatch.delenv("OED_USER_AGENT", raising=False)
+    assert _resolve_user_agent(None) == DEFAULT_USER_AGENT
+    assert _resolve_user_agent("") == DEFAULT_USER_AGENT
+    monkeypatch.setenv("OED_USER_AGENT", "from-env/1.0")
+    assert _resolve_user_agent(None) == "from-env/1.0"
+    assert _resolve_user_agent("") == "from-env/1.0"
+    assert _resolve_user_agent("from-arg/2.0") == "from-arg/2.0"
 
-    monkeypatch.setenv("OED_COMMUNITY", "openeuler")
-    code = oed_main.main(
-        [
-            "software-package-server",
-            "API_getSoftwarePackage",
-            "--id",
-            "42",
-            "--language",
-            "zh_CN",
-        ]
-    )
-    assert code == 0
-    assert patched["captured"]["url"] == "https://apig.osinfra.cn/v1/softwarepkg/42"
-    assert patched["captured"]["params"] == {"language": "zh_CN"}
 
+def test_headers_function_uses_env(monkeypatch):
+    """``_headers()`` resolves User-Agent through the same precedence as ``_resolve_user_agent``."""
 
-def test_dispatch_per_param_flag_for_query(patched, runner, monkeypatch):
-    """Declared ``integer`` query params get string→int coercion from flags."""
+    from oed_cli.http import _headers
 
-    from oed_cli import main as oed_main
+    monkeypatch.setenv("OED_USER_AGENT", "browser-like/1.0")
+    h = _headers()
+    assert h["User-Agent"] == "browser-like/1.0"
+    h2 = _headers(user_agent="from-arg/2.0")
+    assert h2["User-Agent"] == "from-arg/2.0"
 
-    monkeypatch.setenv("OED_COMMUNITY", "openeuler")
-    code = oed_main.main(
-        [
-            "software-package-server",
-            "API_listSoftwarePackages",
-            "--page-num",
-            "3",
-            "--count-per-page",
-            "5",
-        ]
-    )
-    assert code == 0
-    # ints, not strings
-    assert patched["captured"]["params"] == {"page_num": 3, "count_per_page": 5}
 
+def test_default_headers_omit_referer():
+    """No default ``Referer`` — openEuler APIG rejects ``easysearch`` calls with 401
+    when this header is present (verified 2026-07-28). Callers can still pass
+    one explicitly via ``extra=`` if a future endpoint needs it."""
 
-def test_dispatch_per_param_flag_overrides_params(patched, runner, monkeypatch):
-    """Per-param flag values win when ``--params`` also defines the same key."""
+    from oed_cli.http import _headers
 
-    from oed_cli import main as oed_main
+    h = _headers()
+    assert "Referer" not in h
+    assert h["User-Agent"].startswith("oed/")
+    assert h["Accept"].startswith("application/json")
+    assert "zh-CN" in h["Accept-Language"]
 
-    monkeypatch.setenv("OED_COMMUNITY", "openeuler")
-    code = oed_main.main(
-        [
-            "software-package-server",
-            "API_listSoftwarePackages",
-            "--params",
-            '{"page_num":1,"count_per_page":10,"phase":"ignored"}',
-            "--page-num",
-            "7",
-        ]
-    )
-    assert code == 0
-    captured = patched["captured"]["params"]
-    assert captured["page_num"] == 7            # flag wins
-    assert captured["count_per_page"] == 10     # params still applies
+    h_with_extra = _headers(extra={"Referer": "https://example.com/"})
+    assert h_with_extra["Referer"] == "https://example.com/"
 
 
-def test_dispatch_unknown_flag_with_hint(patched, runner, monkeypatch, capsys):
-    """A flag that doesn't match any declared parameter surfaces a precise
-    hint listing what *is* valid for this operation."""
+def test_call_operation_forwards_user_agent(patched):
+    """``call_operation(user_agent=...)`` propagates to the HTTP layer."""
 
-    from oed_cli import main as oed_main
+    from oed_cli.dynamic import operations_table
+    from oed_cli.invoke import call_operation
 
-    monkeypatch.setenv("OED_COMMUNITY", "openeuler")
-    code = oed_main.main(
-        [
-            "software-package-server",
-            "API_getSoftwarePackage",
-            "--totally-unknown",
-            "1",
-        ]
-    )
-    captured = capsys.readouterr()
-    assert code == 1
-    text = captured.out + captured.err
-    assert "unknown_flag" in text
-    # The hint should list this op's declared params so the user knows what to use.
-    assert "id" in text
-    assert "language" in text
+    table = operations_table(SAMPLE_SPEC, "software-package-server")
+    op = table["API_getSoftwarePackage"]
+    call_operation(op, params={"id": "1"}, user_agent="override/1.0")
+    assert patched["captured"]["user_agent"] == "override/1.0"
 
 
-def test_operation_help_enumerates_flag_forms(patched, runner, monkeypatch, capsys):
-    """``oed <svc> <method> --help`` shows every per-parameter flag, with the
-    APIG-generated ``API_`` prefix stripped from ``help_for`` / ``usage``."""
+def test_dispatch_user_agent_flag_flows_to_http(patched, monkeypatch, capsys):
+    """End-to-end: ``--user-agent foo`` reaches ``get_request(user_agent=...)``."""
 
     from oed_cli import main as oed_main
 
     monkeypatch.setenv("OED_COMMUNITY", "openeuler")
-    code = oed_main.main(
-        ["software-package-server", "getSoftwarePackage", "--help"]
-    )
-    captured = capsys.readouterr()
+    code = oed_main.main([
+        "software-package-server", "API_getSoftwarePackage",
+        "--id", "1", "--user-agent", "browser-mock/9.9",
+    ])
     assert code == 0
-    text = captured.out + captured.err
-    assert text.lstrip().startswith("{")
-    payload = json.loads(_extract_json(text))
-    # Display name strips the API_ prefix.
-    assert payload["help_for"] == "getSoftwarePackage"
-    # Raw spec form still surfaced for diagnostics.
-    assert payload["operation_id_raw"] == "API_getSoftwarePackage"
-    assert payload["method"] == "GET"
-    flags = {p["flag"] for p in payload["parameters"]}
-    assert "--id" in flags
-    assert "--language" in flags
-    # Required marker carried over.
-    id_entry = next(p for p in payload["parameters"] if p["name"] == "id")
-    assert id_entry["required"] is True
-    # Usage line lists the flags in copy-paste form (also stripped).
-    assert "--id" in payload["usage"]
-    assert "getSoftwarePackage" in payload["usage"]
-    assert "API_getSoftwarePackage" not in payload["usage"]
-
-
-def test_api_prefix_alias_resolves_same_op(patched, runner, monkeypatch):
-    """Both ``API_xxx`` and ``xxx`` (and case variants) must resolve to the
-    same :class:`Operation` so users never have to memorize the prefix."""
+    assert patched["captured"]["user_agent"] == "browser-mock/9.9"
+
+
+def test_dispatch_user_agent_env_only(patched, monkeypatch):
+    """No flag, only env → env value is forwarded."""
 
     from oed_cli import main as oed_main
 
     monkeypatch.setenv("OED_COMMUNITY", "openeuler")
-    # 1) Stripped form
-    code = oed_main.main(
-        [
-            "software-package-server",
-            "getSoftwarePackage",
-            "--id",
-            "42",
-        ]
-    )
+    monkeypatch.setenv("OED_USER_AGENT", "env-only/3.0")
+    code = oed_main.main(["software-package-server", "API_getSoftwarePackage", "--id", "1"])
     assert code == 0
-    stripped_url = patched["captured"]["url"]
+    assert patched["captured"]["user_agent"] == "env-only/3.0"
 
-    # 2) Raw API_ form (back-compat)
-    patched["captured"].clear()
-    code = oed_main.main(
-        [
-            "software-package-server",
-            "API_getSoftwarePackage",
-            "--id",
-            "42",
-        ]
-    )
-    assert code == 0
-    raw_url = patched["captured"]["url"]
 
-    # 3) Case-insensitive
-    patched["captured"].clear()
-    code = oed_main.main(
-        [
-            "software-package-server",
-            "GETSOFTWAREPACKAGE",
-            "--id",
-            "42",
-        ]
-    )
-    assert code == 0
-    upper_url = patched["captured"]["url"]
+def test_dispatch_user_agent_flag_overrides_env(patched, monkeypatch):
+    """Flag wins over env when both are set."""
+
+    from oed_cli import main as oed_main
 
-    assert stripped_url == raw_url == upper_url == "https://apig.osinfra.cn/v1/softwarepkg/42"
+    monkeypatch.setenv("OED_COMMUNITY", "openeuler")
+    monkeypatch.setenv("OED_USER_AGENT", "env/1.0")
+    code = oed_main.main([
+        "software-package-server", "API_getSoftwarePackage",
+        "--id", "1", "--user-agent=arg/2.0",
+    ])
+    assert code == 0
+    assert patched["captured"]["user_agent"] == "arg/2.0"
 
 
-def test_service_level_help_uses_stripped_names(patched, runner, monkeypatch, capsys):
-    """``oed <service> --help`` lists stripped names + an ``operation_aliases``
-    map so callers can see the original spec form when it's non-trivial."""
+def test_dispatch_user_agent_in_dry_run(patched, monkeypatch, capsys):
+    """Dry-run surfaces the resolved User-Agent under ``request.headers``."""
 
     from oed_cli import main as oed_main
 
     monkeypatch.setenv("OED_COMMUNITY", "openeuler")
-    code = oed_main.main(["software-package-server", "--help"])
-    captured = capsys.readouterr()
+    code = oed_main.main([
+        "software-package-server", "API_getSoftwarePackage",
+        "--id", "1", "--user-agent", "preview-ua/1.0", "--dry-run",
+    ])
     assert code == 0
-    payload = json.loads(_extract_json(captured.out))
-    # First op name has no API_ prefix in display
-    assert "API_listSoftwarePackages" not in payload["operations"]
-    assert "listSoftwarePackages" in payload["operations"]
-    # Aliases map the display form back to the raw spec form
-    assert payload["operation_aliases"]["listSoftwarePackages"] == "API_listSoftwarePackages"
+    import json as _json
+    payload = _json.loads(capsys.readouterr().out)
+    assert payload["dry_run"] is True
+    assert payload["request"]["headers"]["User-Agent"] == "preview-ua/1.0"
 
 
-def test_help_overrides_flag_validation(patched, runner, monkeypatch):
-    """``--help`` short-circuits flag validation: unknown flags together with
-    ``--help`` should still show the help, not error on the flag."""
+def test_dispatch_user_agent_missing_value_errors(patched, monkeypatch, capsys):
+    """``--user-agent`` with no following value fails fast with exit 1."""
 
     from oed_cli import main as oed_main
 
     monkeypatch.setenv("OED_COMMUNITY", "openeuler")
-    code = oed_main.main(
-        [
-            "software-package-server",
-            "API_getSoftwarePackage",
-            "--bogus-flag",
-            "x",
-            "--help",
-        ]
-    )
-    assert code == 0
-    assert "method" not in patched["captured"]  # no network call
+    code = oed_main.main([
+        "software-package-server", "API_getSoftwarePackage",
+        "--id", "1", "--user-agent",
+    ])
+    out = capsys.readouterr()
+    assert code == 1 and "missing_flag_value" in (out.out + out.err)