py-wlcli 0.8.1__tar.gz → 0.8.2__tar.gz

{py_wlcli-0.8.1 → py_wlcli-0.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: py_wlcli
-Version: 0.8.1
+Version: 0.8.2
 Summary: wl_cli - Python项目
 Project-URL: Homepage, https://gitlab.gewinnrobo.com/Humuyuan/wl-cli
 Project-URL: Issues, https://gitlab.gewinnrobo.com/Humuyuan/wl-cli/-/issues

py_wlcli-0.8.2/VERSION

@@ -0,0 +1 @@
+0.8.2

{py_wlcli-0.8.1 → py_wlcli-0.8.2}/src/wl_cli/capabilities.py

@@ -1,4 +1,4 @@
-"""The shared capability registry for the ``wl`` CLI (issues #270, #221).
+"""The shared capability registry for the ``wl`` CLI (issues #270, #221, #231).
 
 Capabilities are the stable, dotted names a consumer (wlcc) probes instead of
 grepping ``--help`` for an implementation flag (wlcc ADR-0010, decision 6):
@@ -43,6 +43,7 @@ CAPABILITY_SINCE: dict[str, str] = {
     "cc.statusline": "0.8.0",
     "cc.upgrade": "0.8.0",
     "env.check": "0.8.0",
+    "env.check.require": "0.8.2",
     "env.repair": "0.8.0",
     "mcp.gitlab": "0.8.0",
     "mcp.k8s": "0.8.0",

{py_wlcli-0.8.1 → py_wlcli-0.8.2}/src/wl_cli/cc/checks.py

@@ -107,6 +107,15 @@ MCP_SERVE_ARGS: dict[str, str] = {
     "k8s-diagnose": "k8s",
 }
 
+#: Environment the registered argv needs, per server (#229). ``gitlab`` owns
+#: its default host inside ``server.py``; ``k8s-diagnose`` cannot discover the
+#: SSH target, so the registration must carry it. This is the single source
+#: for both the ``claude mcp add -e`` argv and the registration check.
+MCP_SERVE_ENV: dict[str, tuple[tuple[str, str], ...]] = {
+    "gitlab": (),
+    "k8s-diagnose": (("K8S_SSH_HOST", "ubuntu-server"),),
+}
+
 #: Capability the ``wl`` on ``PATH`` must advertise before a registration argv
 #: counts as verifiable (#228). Consumers (wlcc) use the same bit to decide
 #: that registration goes through ``wl mcp serve``.
@@ -608,6 +617,124 @@ def _wl_reason(fields: dict[str, Any]) -> str:
     return f"the wl CLI on PATH is not usable ({state or 'unknown state'})"
 
 
+def mcp_config_path() -> Path:
+    """Return Claude Code's user-scope config file (``claude mcp add -s user``).
+
+    ``CLAUDE_CONFIG_DIR`` moves the file *inside* that directory, while the
+    default location is ``~/.claude.json`` -- a sibling of ``~/.claude``, not
+    ``~/.claude/.claude.json``. ``HostContext.config_root`` therefore cannot
+    supply this path on its own. Verified against the CLI on 2026-11-05.
+    """
+    raw = os.environ.get("CLAUDE_CONFIG_DIR")
+    if raw:
+        # The real CLI resolves this relative to the cwd and does **not**
+        # expand ``~`` (measured 2026-11-05), so neither may we.
+        return Path(os.path.abspath(raw)) / ".claude.json"
+    return Path(os.path.expanduser("~/.claude.json"))
+
+
+def _registration_status(name: str, entry: Any, wl: str) -> str:
+    """Classify one stored registration as ``ok``, ``missing`` or ``stale``.
+
+    The stamp alone is not evidence: a payload swap that keeps the version
+    leaves the old argv pointing at a deleted plugin file (#229), so the
+    stored command, args and required environment are compared verbatim.
+    """
+    if not isinstance(entry, dict):
+        return "missing"
+    if entry.get("type", "stdio") != "stdio":
+        return "stale"
+    if entry.get("command") != wl:
+        return "stale"
+    if entry.get("args") != ["mcp", "serve", MCP_SERVE_ARGS[name]]:
+        return "stale"
+    env = entry.get("env")
+    if env is None:
+        env = {}
+    if not isinstance(env, dict):
+        return "stale"
+    for key, _default in MCP_SERVE_ENV[name]:
+        # Only presence matters: a user's custom host (e.g. a real K8S_SSH_HOST)
+        # is a working registration and must not be rewritten to the default.
+        if not env.get(key):
+            return "stale"
+    return "ok"
+
+
+def _cwd() -> str:
+    """The working directory Claude Code keys the local scope by."""
+    return os.path.abspath(os.getcwd())
+
+
+def _shadowing_servers(config: dict[str, Any]) -> dict[str, str]:
+    """Return server name -> scope for entries that shadow the user scope.
+
+    Claude Code resolves ``mcpServers`` for the working directory: the local
+    scope in ``projects[<cwd>].mcpServers`` and the project ``<cwd>/.mcp.json``
+    both take precedence over the user-scope map (#229 review). A shadowing
+    entry is reported, never rewritten -- it belongs to the project, not wlcc.
+    """
+    shadowed: dict[str, str] = {}
+    cwd = _cwd()
+    projects = config.get("projects")
+    if isinstance(projects, dict):
+        local = projects.get(cwd)
+        if isinstance(local, dict):
+            servers = local.get("mcpServers")
+            if isinstance(servers, dict):
+                for name in MCP_SERVERS:
+                    if name in servers:
+                        shadowed[name] = "local"
+    project_data, _ = _read_json_object(Path(cwd) / ".mcp.json")
+    if project_data is not None:
+        servers = project_data.get("mcpServers")
+        if isinstance(servers, dict):
+            for name in MCP_SERVERS:
+                shadowed.setdefault(name, "project")
+    return shadowed
+
+
+def probe_mcp_registrations(wl: str) -> dict[str, Any]:
+    """Report the user-scope registrations for the servers wlcc owns.
+
+    A missing config file reads as "no registrations" rather than an error --
+    ``claude mcp add`` creates it, so the first repair must be allowed to
+    write. An unreadable file is reported through ``error`` and never
+    rewritten. ``stale`` lists the server names whose stored argv does not
+    match ``<wl> mcp serve <sub>``; ``shadowed`` names the same-name entries
+    in the local/project scopes that override the user registration.
+    """
+    path = mcp_config_path()
+    data, error = _read_json_object(path)
+    report: dict[str, Any] = {
+        "config": str(path),
+        "servers": {},
+        "stale": [],
+        "shadowed": {},
+        "error": error,
+    }
+    if data is None:
+        return report
+    servers = data.get("mcpServers")
+    if servers is None:
+        servers = {}
+    elif not isinstance(servers, dict):
+        report["error"] = f"{path}: 'mcpServers' is not an object"
+        return report
+    for name in MCP_SERVERS:
+        entry = servers.get(name)
+        status = _registration_status(name, entry, wl)
+        report["servers"][name] = {
+            "status": status,
+            "command": entry.get("command") if isinstance(entry, dict) else None,
+            "args": entry.get("args") if isinstance(entry, dict) else None,
+        }
+        if status != "ok":
+            report["stale"].append(name)
+    report["shadowed"] = _shadowing_servers(data)
+    return report
+
+
 def probe_mcp(host: HostContext) -> dict[str, Any]:
     """§3: the registration target, version stamp and interpreter visibility.
 
@@ -616,6 +743,11 @@ def probe_mcp(host: HostContext) -> dict[str, Any]:
     instead of looking for a plugin-root ``mcp-tools/server.py``. The
     interpreter probe stays a report field but can no longer gate the section
     -- ``python`` is not part of the registered command any more.
+
+    Since #229 the version stamp is not the only evidence: the stored
+    user-scope registration is read back and compared verbatim, because a
+    payload swap that keeps the version number used to leave a dead
+    ``mcp-tools/server.py`` argv behind while this section still said ``ok``.
     """
     cache = _wlcc_cache(host)
     fields: dict[str, Any] = {
@@ -625,6 +757,8 @@ def probe_mcp(host: HostContext) -> dict[str, Any]:
         "plugin_root": None,
         "rejected": False,
         "servers": list(MCP_SERVERS),
+        "mcp_config": str(mcp_config_path()),
+        "registrations": {},
         "wl": _probe_wl_serve(),
         "python": _probe_python(),
     }
@@ -655,6 +789,13 @@ def probe_mcp(host: HostContext) -> dict[str, Any]:
     if not wl_state.startswith("ok:"):
         return _result("unverifiable", _wl_reason(fields["wl"]), **fields)
 
+    registration = probe_mcp_registrations(str(fields["wl"].get("path") or ""))
+    fields["mcp_config"] = registration["config"]
+    fields["registrations"] = registration["servers"]
+    fields["shadowed"] = registration["shadowed"]
+    if registration["error"]:
+        return _result("unverifiable", registration["error"], **fields)
+
     if registered != version:
         return _result(
             "dangling",
@@ -662,6 +803,25 @@ def probe_mcp(host: HostContext) -> dict[str, Any]:
             "wl cc repair will re-register",
             **fields,
         )
+
+    if registration["shadowed"]:
+        scopes = ", ".join(
+            f"{name} ({scope})" for name, scope in registration["shadowed"].items()
+        )
+        return _result(
+            "dangling",
+            f"MCP registration shadowed by a higher scope: {scopes}; "
+            "remove the shadowing project entry manually",
+            **fields,
+        )
+    if registration["stale"]:
+        return _result(
+            "dangling",
+            "stale MCP registration for "
+            + ", ".join(registration["stale"])
+            + "; wl cc repair will re-register",
+            **fields,
+        )
     return _result("ok", None, **fields)
 
 

{py_wlcli-0.8.1 → py_wlcli-0.8.2}/src/wl_cli/cc/mutate.py

@@ -87,11 +87,17 @@ GSTACK_REPO = "https://github.com/garrytan/gstack.git"
 #: wlcc marketplace source when it is not registered yet (``/wl-upgrade`` §2).
 WLCC_MARKETPLACE_REPO = "https://gitlab.gewinnrobo.com/Humuyuan/wlcc.git"
 
-#: Per-server extra argv for ``claude mcp add`` (check.sh §3). The GitLab host
-#: is deliberately *not* passed: ``server.py`` owns that default (#242).
+#: Per-server extra argv for ``claude mcp add`` (check.sh §3), derived from
+#: the same ``checks.MCP_SERVE_ENV`` table the registration check reads, so
+#: the written argv and the verified argv cannot drift (#229). The GitLab
+#: host is deliberately *not* passed: ``server.py`` owns that default (#242).
 MCP_SERVER_EXTRA: dict[str, tuple[str, ...]] = {
-    "gitlab": (),
-    "k8s-diagnose": ("-e", "K8S_SSH_HOST=ubuntu-server"),
+    name: tuple(
+        part
+        for key, value in checks.MCP_SERVE_ENV[name]
+        for part in ("-e", f"{key}={value}")
+    )
+    for name in checks.MCP_SERVERS
 }
 
 #: How many timestamped ``settings.json`` backups are kept (hooks-drift).
@@ -494,9 +500,12 @@ def ensure_mcp() -> dict[str, Any]:
     Since #228 the registered argv is ``<wl> mcp serve <sub>`` -- the plugin
     tree's ``mcp-tools/server.py`` is neither required nor kept as a fallback.
     A rejected plugin root or a missing/unusable ``wl`` is reported as
-    ``unverifiable`` and never registered. The stamp is the idempotency latch,
-    so it is written only after *both* ``claude mcp add`` calls returned 0; one
-    failure leaves the old stamp in place and the next run retries.
+    ``unverifiable`` and never registered. Since #229 the idempotency latch is
+    the *pair* of the version stamp and the stored registration: a matching
+    stamp with a stale argv (same version, swapped payload) is repaired rather
+    than reported ``ok``. The stamp is written only after *both* ``claude mcp
+    add`` calls returned 0; one failure leaves the old stamp in place and the
+    next run retries.
     """
     before = checks.probe_mcp(checks.load_host_context())
     fields = _section_fields(before)
@@ -506,6 +515,17 @@ def ensure_mcp() -> dict[str, Any]:
     if before["status"] == "ok":
         return _result("ok", None, changed, **fields)
 
+    shadowed = before.get("shadowed")
+    if isinstance(shadowed, dict) and shadowed:
+        scopes = ", ".join(f"{name} ({scope})" for name, scope in shadowed.items())
+        return _result(
+            "dangling",
+            f"MCP registration shadowed by a higher scope: {scopes}; "
+            "remove the shadowing project entry manually",
+            changed,
+            **fields,
+        )
+
     plugin_root = before.get("plugin_root")
     if not isinstance(plugin_root, str) or not plugin_root:
         return _result(
@@ -534,7 +554,10 @@ def ensure_mcp() -> dict[str, Any]:
     for name in checks.MCP_SERVERS:
         subcommand = checks.MCP_SERVE_ARGS[name]
         try:
-            _run([claude, "mcp", "remove", name])
+            # ``-s user`` is required: without it the CLI refuses to remove
+            # when the same name also exists in the local/project scope, and
+            # the following ``add -s user`` then fails as a duplicate.
+            _run([claude, "mcp", "remove", name, "-s", "user"])
             proc = _run(
                 [
                     claude,

{py_wlcli-0.8.1 → py_wlcli-0.8.2}/src/wl_cli/env/cli.py

@@ -74,18 +74,31 @@ def _summary_lines(
     is_flag=True,
     help="Emit one five-state JSON envelope on stdout.",
 )
-def check(as_json: bool) -> None:
+@click.option(
+    "--require",
+    "require",
+    multiple=True,
+    metavar="CAPABILITY",
+    help=(
+        "Assert a capability is available (repeatable). The consumer contract "
+        "is the capability name, not a version string; a missing or unknown "
+        "name exits 1 with status 'error'."
+    ),
+)
+def check(as_json: bool, require: tuple[str, ...]) -> None:
     """Report the running wl: version, executable, platform and capabilities.
 
     Read-only. In ``--json`` mode stdout is exactly one envelope line and
     diagnostics go to stderr; the probe itself runs in a temporary CWD and the
     dispatcher skips the startup ``.wl`` self-sync (#220), so the caller's
-    directory is never written to.
+    directory is never written to. ``--require`` turns the report into an
+    assertion: consumers gate on capability names, never on a version string
+    (#231).
     """
     if as_json:
-        raise SystemExit(emit_check())
+        raise SystemExit(emit_check(require))
 
-    status, reason, fields = build_payload()
+    status, reason, fields = build_payload(require=require)
     for line in _summary_lines(status, reason, fields):
         click.echo(line)
     raise SystemExit(exit_code(status))

{py_wlcli-0.8.1 → py_wlcli-0.8.2}/src/wl_cli/env_status.py

@@ -15,10 +15,11 @@ commands (#220).
 
 Envelope contract: ``status`` is ``ok`` for a supported interpreter,
 ``unverifiable`` when the platform matrix rejects it (unreachable for an
-installed wl -- the wheel requires Python 3.11+), and ``error`` only when the
-payload itself cannot be built. The envelope's ``reason`` is the platform
-reason when unsupported; the matrix's own ``reason`` is always carried as
-``platform_reason``, so the two keys never collide.
+installed wl -- the wheel requires Python 3.11+), and ``error`` when the
+payload itself cannot be built or a ``--require`` assertion fails (#231). The
+envelope's ``reason`` is the platform reason when unsupported; the matrix's
+own ``reason`` is always carried as ``platform_reason``, so the two keys never
+collide.
 """
 
 from __future__ import annotations
@@ -36,7 +37,7 @@ from .envelope import OK_STATUSES, dump, exit_code
 from .platform import platform_payload
 
 if TYPE_CHECKING:
-    from collections.abc import Generator
+    from collections.abc import Generator, Sequence
 
 #: Stable tool name in the envelope's ``tool`` key (the alias reuses it: both
 #: commands answer the same question, so consumers key off one name).
@@ -101,15 +102,71 @@ def install_fields() -> dict[str, str]:
     return {"command": INSTALL_COMMAND, "floor": INSTALL_FLOOR}
 
 
-def build_payload() -> tuple[str, str | None, dict[str, Any]]:
+#: Reason prefixes for the ``--require`` contract (#231). A known capability
+#: that this build does not advertise is ``no_capability:``; a name that is
+#: not in the registry at all is ``unknown_capability:`` -- reporting a typo as
+#: satisfied would turn one misspelling into a gate that never fails.
+NO_CAPABILITY = "no_capability:"
+UNKNOWN_CAPABILITY = "unknown_capability:"
+
+
+def evaluate_requirements(
+    required: Sequence[str],
+    capabilities: Sequence[str],
+) -> tuple[str | None, list[str]]:
+    """Evaluate ``--require`` names against the advertised capabilities (#231).
+
+    The registry (:data:`wl_cli.capabilities.CAPABILITY_SINCE`) answers "is
+    this a capability name at all"; the envelope's ``capabilities`` list
+    answers "does this build have it". A registered name that is not
+    advertised is missing (``no_capability:<names>``); an unregistered name is
+    a typo (``unknown_capability:<names>``), never a satisfied requirement.
+
+    Names are de-duplicated in request order. When both classes are present
+    the unknown names win the ``reason`` (the request itself is invalid while
+    ``missing`` still carries every known-but-unavailable name), so a caller
+    fixing the payload sees the typo first.
+
+    Args:
+        required: Capability names from ``--require``, in request order.
+        capabilities: The names this build advertises (the envelope payload).
+
+    Returns:
+        ``(reason, missing)``. ``reason`` is ``None`` when every requested
+        capability is advertised; ``missing`` is always the known-but-
+        unavailable names in request order.
+    """
+    known = set(CAPABILITY_SINCE)
+    advertised = set(capabilities)
+    ordered = list(dict.fromkeys(required))
+    unknown = [name for name in ordered if name not in known]
+    missing = [name for name in ordered if name in known and name not in advertised]
+    if unknown:
+        return UNKNOWN_CAPABILITY + ",".join(unknown), missing
+    if missing:
+        return NO_CAPABILITY + ",".join(missing), missing
+    return None, missing
+
+
+def build_payload(
+    *, require: Sequence[str] = ()
+) -> tuple[str, str | None, dict[str, Any]]:
     """Build the ``wl env check`` fields.
 
+    Args:
+        require: Capability names asserted with ``--require`` (#231). They are
+            checked against the advertised ``capabilities`` only when the
+            probe itself holds; a platform failure keeps its own status and
+            reason, as before.
+
     Returns:
         ``(status, reason, fields)``. ``status`` is ``ok`` when the running
         interpreter is supported, ``unverifiable`` when the shared platform
-        matrix says otherwise, and ``error`` only when the payload cannot be
-        built at all. ``reason`` carries the readable platform reason when the
-        status is not ``ok``; ``fields`` is the envelope payload.
+        matrix says otherwise, and ``error`` when the payload cannot be built
+        at all or a requested capability is missing/unknown. ``reason``
+        carries the readable explanation when the status is not ``ok``;
+        ``fields`` is the envelope payload, with a ``missing`` list only when
+        a requested capability is known but not advertised.
     """
     executable = executable_path()
     try:
@@ -142,16 +199,39 @@ def build_payload() -> tuple[str, str | None, dict[str, Any]]:
         )
 
     if fields["supported"] is True:
-        return "ok", None, fields
-    return "unverifiable", platform_reason or "unsupported platform", fields
+        status, reason = "ok", None
+    else:
+        status, reason = "unverifiable", platform_reason or "unsupported platform"
+
+    # Capability requirements are an assertion about a healthy probe: when the
+    # platform itself is unsupported, the platform reason is the actionable
+    # answer and stays untouched.
+    if status in OK_STATUSES and require:
+        requirement_reason, missing = evaluate_requirements(
+            require, fields["capabilities"]
+        )
+        if requirement_reason is not None:
+            status, reason = "error", requirement_reason
+            if missing:
+                fields["missing"] = missing
+    return status, reason, fields
 
 
-def emit_check() -> int:
+def emit_check(required: Sequence[str] = ()) -> int:
     """Write the ``env check`` envelope to stdout and return its exit code.
 
     Both ``wl env check --json`` and the deprecated ``wl self capabilities
     --json`` alias call this, so the two commands cannot answer differently.
+    ``required`` carries the repeatable ``--require`` names (empty for the
+    alias, which reports rather than asserts).
+
+    Args:
+        required: Capability names the caller asserts, in request order.
+
+    Returns:
+        The envelope exit code: ``0`` when the probe holds and every required
+        capability is present, ``1`` otherwise.
     """
-    status, reason, fields = build_payload()
+    status, reason, fields = build_payload(require=required)
     dump(status, status in OK_STATUSES, tool=TOOL, reason=reason, **fields)
     return exit_code(status)

py_wlcli-0.8.1/VERSION

@@ -1 +0,0 @@
-0.8.1