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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: py_wlcli
-Version: 0.8.1
+Version: 0.9.0
 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.9.0/VERSION

@@ -0,0 +1 @@
+0.9.0

{py_wlcli-0.8.1 → py_wlcli-0.9.0}/pyproject.toml

@@ -50,6 +50,11 @@ default = true
 requires = [ "hatchling>=1.27",]
 build-backend = "hatchling.build"
 
+[dependency-groups]
+dev = [
+    "jsonschema>=4.26.0",
+]
+
 [tool.hatch.version]
 source = "regex"
 path = "VERSION"

{py_wlcli-0.8.1 → py_wlcli-0.9.0}/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):
@@ -33,6 +33,7 @@ SCHEMA_VERSION = 1
 #: data ships in (the release bump happens outside this change).
 CAPABILITY_SINCE: dict[str, str] = {
     "cc.check": "0.8.0",
+    "cc.check.schema": "0.9.0",
     "cc.hooks": "0.8.0",
     "cc.init": "0.8.0",
     "cc.mcp": "0.8.0",
@@ -41,8 +42,12 @@ CAPABILITY_SINCE: dict[str, str] = {
     "cc.settings": "0.8.0",
     "cc.stamps": "0.8.0",
     "cc.statusline": "0.8.0",
+    "cc.token.set": "0.9.0",
+    "cc.token.status": "0.9.0",
+    "cc.token.verify": "0.9.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.9.0}/src/wl_cli/cc/checks.py

@@ -66,6 +66,14 @@ if TYPE_CHECKING:
 #: Stable tool name in the envelope's ``tool`` key.
 TOOL = "cc check"
 
+#: The ``cc.check`` payload schema version (#240). The packaged
+#: ``cc/schemas/cc_check.schema.json`` is the single owner of the shape; this
+#: constant mirrors its top-level ``const``, and the tests pin the two
+#: together. It is deliberately separate from
+#: :data:`wl_cli.capabilities.SCHEMA_VERSION`, which only serves the
+#: deprecated ``wl self capabilities`` payload.
+CC_CHECK_SCHEMA_VERSION = 1
+
 #: Required plugins -- the consumer-side copy of wlcc
 #: ``references/stamps.md``'s ``wl-required-plugins`` key block (#226 there).
 #: Entries are the full ``name@marketplace`` form, so a name cannot match a
@@ -107,6 +115,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 +625,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 +751,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 +765,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 +797,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 +811,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)
 
 
@@ -1101,5 +1269,12 @@ def build_report() -> tuple[str, str | None, dict[str, Any]]:
 def emit_check() -> int:
     """Write the ``cc check`` envelope to stdout and return its exit code."""
     status, reason, fields = build_report()
-    dump(status, status in OK_STATUSES, tool=TOOL, reason=reason, **fields)
+    dump(
+        status,
+        status in OK_STATUSES,
+        tool=TOOL,
+        reason=reason,
+        schema_version=CC_CHECK_SCHEMA_VERSION,
+        **fields,
+    )
     return exit_code(status)

{py_wlcli-0.8.1 → py_wlcli-0.9.0}/src/wl_cli/cc/cli.py

@@ -19,13 +19,15 @@ can never disagree with ``repair``.
 
 from __future__ import annotations
 
+from importlib import resources
 from typing import TYPE_CHECKING, Any
 
 import click
 
 from ..envelope import OK_STATUSES, dump, exit_code
 from . import mutate
-from .checks import TOOL, build_report
+from . import token as token_ops
+from .checks import CC_CHECK_SCHEMA_VERSION, TOOL, build_report
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -35,6 +37,24 @@ _HOST_SECTIONS = ("plugins", "mcp", "settings", "stamps", "hooks", "statusline")
 
 _JSON_HELP = "Emit one five-state JSON envelope on stdout."
 
+_SCHEMA_HELP = (
+    "Print the packaged cc.check JSON Schema and exit without running any probe."
+)
+
+
+def schema_bytes() -> bytes:
+    """Return the packaged ``cc_check.schema.json`` bytes, unchanged.
+
+    The schema file is the single owner of the ``wl cc check --json`` payload
+    shape (#240, ruling #234). Reading it through :mod:`importlib.resources`
+    means an installed wheel serves the same bytes as the source tree.
+    """
+    return (
+        resources.files("wl_cli.cc")
+        .joinpath("schemas", "cc_check.schema.json")
+        .read_bytes()
+    )
+
 
 def _section_line(name: str, section: dict[str, Any]) -> str:
     """Render one ``name: status -- reason`` line."""
@@ -146,7 +166,13 @@ def cc_group() -> None:
     is_flag=True,
     help=_JSON_HELP,
 )
-def check(as_json: bool) -> None:
+@click.option(
+    "--schema",
+    "show_schema",
+    is_flag=True,
+    help=_SCHEMA_HELP,
+)
+def check(as_json: bool, show_schema: bool) -> None:
     """Report the Claude Code host state without writing anything.
 
     The report nests the same-process ``wl env check`` payload under ``env``
@@ -156,10 +182,26 @@ def check(as_json: bool) -> None:
     hides the others. In ``--json`` mode stdout is exactly one envelope line
     and diagnostics go to stderr; the probe is read-only, and the dispatcher
     skips the startup ``.wl`` self-sync (#220).
+
+    ``--schema`` prints the packaged JSON Schema byte-for-byte and exits 0
+    without probing anything; it cannot be combined with ``--json``.
     """
+    if show_schema:
+        if as_json:
+            raise click.UsageError("--schema and --json are mutually exclusive")
+        click.echo(schema_bytes(), nl=False)
+        raise SystemExit(0)
+
     status, reason, sections = build_report()
     if as_json:
-        dump(status, status in OK_STATUSES, tool=TOOL, reason=reason, **sections)
+        dump(
+            status,
+            status in OK_STATUSES,
+            tool=TOOL,
+            reason=reason,
+            schema_version=CC_CHECK_SCHEMA_VERSION,
+            **sections,
+        )
         raise SystemExit(exit_code(status))
 
     for line in _summary_lines(status, reason, sections):
@@ -368,3 +410,55 @@ def stamps_check(as_json: bool) -> None:
     are reported and kept here and there.
     """
     _run_single("cc stamps check", lambda: mutate.probe_section("stamps"), as_json)
+
+
+@cc_group.group(name="token")
+def token_group() -> None:
+    """GitLab credential status, set and verify (never echoes the token).
+
+    The three subcommands are ADR-0012's command surface: ``status`` is a
+    local-only probe, ``set`` is stdin-only and ``verify`` is the one explicit
+    network call. Reasons are the closed ADR-0012 §6 prefixes.
+    """
+
+
+@token_group.command(name="status")
+@click.option("--json", "as_json", is_flag=True, help=_JSON_HELP)
+def token_status(as_json: bool) -> None:
+    """Report the credential source and whether the local file decrypts.
+
+    Returns ``source`` / ``path`` / ``exists`` / ``mode`` / ``decryptable``
+    only -- never the token, the hostname, the username or the plaintext
+    length. ``dangling`` (with ``no_token:``, ``token_undecryptable:`` or
+    ``token_insecure_permissions:``) still exits 0: the probe holds and the
+    reason names the one pending action.
+    """
+    _run_single("cc token status", token_ops.status, as_json)
+
+
+@token_group.command(name="set")
+@click.option("--json", "as_json", is_flag=True, help=_JSON_HELP)
+def token_set(as_json: bool) -> None:
+    """Encrypt and atomically write the token read from stdin.
+
+    A TTY prompts without echo; a pipe is read directly. There is deliberately
+    no ``--from-file`` / ``--path`` / ``--force`` / ``--dry-run``: argv and
+    environment variables are a second leak surface for a secret.
+    """
+
+    def action() -> dict[str, Any]:
+        return token_ops.set_token(token_ops.read_token_stdin())
+
+    _run_single("cc token set", action, as_json)
+
+
+@token_group.command(name="verify")
+@click.option("--json", "as_json", is_flag=True, help=_JSON_HELP)
+def token_verify(as_json: bool) -> None:
+    """Check the token against GitLab (``GET /api/v4/user``).
+
+    The only subcommand that uses the network. It reports ``http_code`` and
+    ``host`` only; the response body is never echoed, redirects are never
+    followed and TLS verification cannot be disabled.
+    """
+    _run_single("cc token verify", token_ops.verify, as_json)

{py_wlcli-0.8.1 → py_wlcli-0.9.0}/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,