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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: py_wlcli
-Version: 0.8.0
+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.0 → 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,9 +43,11 @@ 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",
+    "mcp.serve": "0.8.1",
     "test.clean_cache": "0.7.0",
 }
 

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

@@ -15,7 +15,7 @@ the ticket cannot drift from the implementation:
 section      wlcc source
 ===========  ============================================================
 plugins      §1 required plugins + §7 context-mode (optional plugin)
-mcp          §3 plugin root, version stamp and interpreter visibility
+mcp          §3 registered wl command, version stamp, interpreter visibility
 settings     §5 gstack + §6 claude-mem (host-side configuration)
 stamps       §8 stamp registry (report only -- never delete)
 hooks        §9 dangling hook commands (read-only plan)
@@ -98,6 +98,29 @@ RETIRED_STAMPS = frozenset({"gemini-key.enc", "mcp-visionary-pending"})
 #: MCP servers check.sh §3 registers.
 MCP_SERVERS: tuple[str, ...] = ("gitlab", "k8s-diagnose")
 
+#: Registered server name -> ``wl mcp serve`` subcommand (#228). The server
+#: names are the stable interface (tool schema and existing user config); only
+#: the execution path moved from the plugin's ``mcp-tools/server.py`` to the
+#: wl CLI. ``k8s-diagnose`` keeps its name but serves ``wl mcp serve k8s``.
+MCP_SERVE_ARGS: dict[str, str] = {
+    "gitlab": "gitlab",
+    "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``.
+MCP_SERVE_CAPABILITY = "mcp.serve"
+
 #: Literal absolute path anchor from wlcc ``hooks-drift.py``: the dangling rule
 #: is exactly ``*/.claude/*``. Kept with the trailing slash on purpose.
 CLAUDE_SEG = "/.claude/"
@@ -475,7 +498,10 @@ def _interpreter_state(path: str, version: str, returncode: int) -> dict[str, An
 
 
 def _probe_python() -> dict[str, Any]:
-    """Resolve the interpreter MCP servers will run under (check.sh §3).
+    """Report the interpreter check.sh §3 used to run the MCP servers under.
+
+    Since #228 the servers run under ``wl mcp serve`` and no interpreter is
+    part of the registered argv, so the result is informational only.
 
     ``uv --no-cache python find 3.12`` resolves a local installation without
     downloading and keeps its cache in a temporary directory for the duration
@@ -518,8 +544,211 @@ def _probe_python() -> dict[str, Any]:
     return _interpreter_state(path, probe.stdout.strip(), probe.returncode)
 
 
+def _probe_wl_serve() -> dict[str, Any]:
+    """Probe the ``wl`` on ``PATH`` for the ``mcp.serve`` capability (#228).
+
+    The registration argv is ``<wl> mcp serve <sub>``, so the executable that
+    will be registered has to exist *and* advertise the capability. Asking it
+    for ``wl env check --json`` reads the same capability registry wlcc keys
+    off, instead of trusting the wl that happens to be running ``cc check``.
+    Every failure is a state value, never an exception.
+
+    Returns:
+        Fields ``path`` / ``state`` / ``version`` / ``capability``. ``state``
+        is ``ok:<version>`` when the capability is advertised, ``fail:absent``
+        when no ``wl`` is on ``PATH``, and ``fail:unusable`` /
+        ``fail:missing_capability`` (with a readable ``reason``) otherwise.
+    """
+    fields: dict[str, Any] = {
+        "path": None,
+        "state": "fail:absent",
+        "version": None,
+        "capability": MCP_SERVE_CAPABILITY,
+    }
+    wl = shutil.which("wl")
+    if wl is None:
+        return fields
+    fields["path"] = wl
+    try:
+        probe = subprocess.run(
+            [wl, "env", "check", "--json"],
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=30,
+        )
+    except (OSError, subprocess.SubprocessError) as exc:
+        fields.update(state="fail:unusable", reason=str(exc))
+        return fields
+    # ``env check`` exits 1 when the platform matrix says ``unverifiable`` but
+    # still emits the payload; parse first so a supported capability is not
+    # rejected because of an unrelated platform warning.
+    try:
+        payload = json.loads(probe.stdout)
+    except ValueError:
+        payload = None
+    if not isinstance(payload, dict):
+        fields.update(
+            state="fail:unusable",
+            reason=f"wl env check exited {probe.returncode} without a JSON payload",
+        )
+        return fields
+    version = payload.get("version")
+    fields["version"] = version if isinstance(version, str) else None
+    capabilities = payload.get("capabilities")
+    if isinstance(capabilities, list) and MCP_SERVE_CAPABILITY in capabilities:
+        fields["state"] = f"ok:{fields['version'] or 'unknown'}"
+        return fields
+    fields.update(
+        state="fail:missing_capability",
+        reason=f"{wl} does not advertise {MCP_SERVE_CAPABILITY}",
+    )
+    return fields
+
+
+def _wl_reason(fields: dict[str, Any]) -> str:
+    """Return a readable reason for a ``wl`` probe that is not ``ok``."""
+    state = str(fields.get("state", ""))
+    if state == "fail:absent":
+        return "the wl CLI is not on PATH"
+    reason = fields.get("reason")
+    if isinstance(reason, str) and reason:
+        return reason
+    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: plugin-root trust, version stamp and interpreter visibility."""
+    """§3: the registration target, version stamp and interpreter visibility.
+
+    Since #228 the registered argv is ``<wl> mcp serve <sub>``: the probe
+    verifies that the ``wl`` on ``PATH`` exists and advertises ``mcp.serve``
+    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] = {
         "cache_root": str(cache),
@@ -528,6 +757,9 @@ 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(),
     }
     try:
@@ -552,17 +784,17 @@ def probe_mcp(host: HostContext) -> dict[str, Any]:
         fields["rejected"] = True
         return _result("unverifiable", root_error, **fields)
     fields["plugin_root"] = str(root)
-    server = root / ".claude" / "mcp-tools" / "server.py"
-    if server.is_symlink():
-        fields["rejected"] = True
-        return _result(
-            "unverifiable", f"MCP server script is a symlink: {server}", **fields
-        )
-    if not server.is_file():
-        fields["rejected"] = True
-        return _result(
-            "unverifiable", f"MCP server script is missing: {server}", **fields
-        )
+
+    wl_state = str(fields["wl"].get("state", ""))
+    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(
@@ -571,10 +803,24 @@ def probe_mcp(host: HostContext) -> dict[str, Any]:
             "wl cc repair will re-register",
             **fields,
         )
-    python_state = str(fields["python"].get("state", ""))
-    if not python_state.startswith(("supplied:", "ok:")):
+
+    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", f"MCP interpreter is not usable: {python_state}", **fields
+            "dangling",
+            "stale MCP registration for "
+            + ", ".join(registration["stale"])
+            + "; wl cc repair will re-register",
+            **fields,
         )
     return _result("ok", None, **fields)
 

{py_wlcli-0.8.0 → py_wlcli-0.8.2}/src/wl_cli/cc/cli.py

@@ -278,7 +278,7 @@ def mcp_ensure(as_json: bool) -> None:
 @mcp_group.command(name="list")
 @click.option("--json", "as_json", is_flag=True, help=_JSON_HELP)
 def mcp_list(as_json: bool) -> None:
-    """Report the plugin root, interpreter, stamp and servers without writing."""
+    """Report the wl target, plugin root, interpreter, stamp and servers."""
     _run_single("cc mcp list", lambda: mutate.probe_section("mcp"), as_json)
 
 

{py_wlcli-0.8.0 → 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).
@@ -488,22 +494,18 @@ def ensure_plugins() -> dict[str, Any]:
 # --------------------------------------------------------------------------- #
 
 
-def _mcp_script(plugin_root: Path, name: str) -> Path:
-    """Return the registered server script for *name* under the plugin root."""
-    tools = plugin_root / ".claude" / "mcp-tools"
-    if name == "gitlab":
-        return tools / "server.py"
-    return tools / name / "server.py"
-
-
 def ensure_mcp() -> dict[str, Any]:
-    """Re-register both MCP servers and write the version stamp only on success.
-
-    A rejected plugin root or an unusable interpreter is reported as
-    ``unverifiable`` and never registered -- the same closed set of states
-    ``check.sh`` §3 uses. 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.
+    """Re-register both MCP servers as ``wl mcp serve`` and stamp on success.
+
+    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. 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)
@@ -513,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(
@@ -521,15 +534,12 @@ def ensure_mcp() -> dict[str, Any]:
             changed,
             **fields,
         )
-    python = before.get("python")
-    python_path = python.get("path") if isinstance(python, dict) else None
-    python_state = python.get("state") if isinstance(python, dict) else None
-    if not isinstance(python_path, str) or not str(python_state).startswith(
-        ("supplied:", "ok:")
-    ):
+    wl_probe = before.get("wl")
+    wl = wl_probe.get("path") if isinstance(wl_probe, dict) else None
+    if not isinstance(wl, str) or not wl:
         return _result(
             "unverifiable",
-            f"MCP interpreter is not usable: {python_state}",
+            before.get("reason") or "the wl CLI is not on PATH",
             changed,
             **fields,
         )
@@ -541,11 +551,13 @@ def ensure_mcp() -> dict[str, Any]:
         )
 
     failures: list[str] = []
-    root = Path(plugin_root)
     for name in checks.MCP_SERVERS:
-        script = str(_mcp_script(root, name))
+        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,
@@ -556,15 +568,17 @@ def ensure_mcp() -> dict[str, Any]:
                     "-s",
                     "user",
                     "--",
-                    python_path,
-                    script,
+                    wl,
+                    "mcp",
+                    "serve",
+                    subcommand,
                 ]
             )
         except (OSError, subprocess.SubprocessError) as exc:
             failures.append(f"{name}: {exc}")
             continue
         if proc.returncode == 0:
-            changed.append(f"mcp: registered {name} -> {script}")
+            changed.append(f"mcp: registered {name} -> {wl} mcp serve {subcommand}")
         else:
             failures.append(f"{name}: {_failure(proc)}")
 

{py_wlcli-0.8.0 → 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))