py-wlcli 0.8.0__py3-none-any.whl

wl_cli/cc/cli.py

@@ -0,0 +1,370 @@
+"""Click namespace for the ``cc`` domain (issues #220, #222, #223).
+
+``wl cc check`` reports the Claude Code host state as the shared five-state
+envelope :mod:`wl_cli.envelope`. The six host sections are read-only (see
+:mod:`wl_cli.cc.checks`); the nested ``env`` field reuses
+:func:`wl_cli.env_status.build_payload` in this process, so ``wl cc check``
+and ``wl env check`` cannot answer the environment question differently.
+
+``wl cc init`` / ``wl cc repair`` / ``wl cc upgrade`` and the granular
+``plugins|mcp|settings|statusline|hooks|stamps`` commands are the write side
+(:mod:`wl_cli.cc.mutate`). They reuse the very same probes: probe first, then
+act only on the difference -- so a second ``init`` is a no-op and ``check``
+can never disagree with ``repair``.
+
+``cc`` is allowed to import ``wl_cli.env`` (one-way), but ``env``/``mcp``/
+``quality`` may not import ``wl_cli.cc`` -- enforced by
+``tests/test_domain_import_direction.py``.
+"""
+
+from __future__ import annotations
+
+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
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+#: Host sections rendered by the human-readable summary, in payload order.
+_HOST_SECTIONS = ("plugins", "mcp", "settings", "stamps", "hooks", "statusline")
+
+_JSON_HELP = "Emit one five-state JSON envelope on stdout."
+
+
+def _section_line(name: str, section: dict[str, Any]) -> str:
+    """Render one ``name: status -- reason`` line."""
+    reason = section.get("reason")
+    suffix = f" -- {reason}" if reason else ""
+    return f"{name}: {section.get('status')}{suffix}"
+
+
+def _summary_lines(
+    status: str, reason: str | None, sections: dict[str, Any]
+) -> list[str]:
+    """Render the human-readable ``check`` summary (no ``--json``)."""
+    lines = [f"wl cc check: {status}"]
+    env = sections.get("env", {})
+    if env.get("status") == "ok":
+        lines.append(f"env: ok (wl {env.get('version')}, Python {env.get('python')})")
+    else:
+        lines.append(_section_line("env", env))
+    lines.extend(_section_line(name, sections.get(name, {})) for name in _HOST_SECTIONS)
+    if reason:
+        lines.append(f"reason: {reason}")
+    return lines
+
+
+def _split(result: dict[str, Any]) -> tuple[str, str | None, dict[str, Any]]:
+    """Split a mutation result into ``(status, reason, payload)``."""
+    reason = result.get("reason")
+    fields = {
+        key: value for key, value in result.items() if key not in ("status", "reason")
+    }
+    return str(result["status"]), reason if isinstance(reason, str) else None, fields
+
+
+def _changed_lines(changed: Any) -> list[str]:
+    """Render the ``changed`` action list; an empty list says so explicitly."""
+    items = [str(item) for item in changed] if isinstance(changed, list) else []
+    if not items:
+        return ["changed: none"]
+    return ["changed:", *(f"  - {item}" for item in items)]
+
+
+def _summary(
+    tool: str, status: str, reason: str | None, fields: dict[str, Any]
+) -> list[str]:
+    """Render one section command's human-readable summary."""
+    lines = [f"{tool}: {status}" + (f" -- {reason}" if reason else "")]
+    lines.extend(_changed_lines(fields.get("changed")))
+    return lines
+
+
+def _report_summary(
+    tool: str, status: str, reason: str | None, fields: dict[str, Any]
+) -> list[str]:
+    """Render ``init`` / ``repair``: the aggregate plus every section."""
+    lines = [f"{tool}: {status}" + (f" -- {reason}" if reason else "")]
+    if fields.get("dry_run"):
+        lines.append("dry run: nothing was written")
+    for name in mutate.SECTION_ORDER:
+        section = fields.get(name)
+        if isinstance(section, dict):
+            lines.append(_section_line(name, section))
+    lines.extend(_changed_lines(fields.get("changed")))
+    return lines
+
+
+def _emit(
+    tool: str,
+    status: str,
+    reason: str | None,
+    fields: dict[str, Any],
+    *,
+    as_json: bool,
+    summary: list[str],
+) -> None:
+    """Write the envelope or the human summary, then exit with the status code."""
+    if as_json:
+        dump(status, status in OK_STATUSES, tool=tool, reason=reason, **fields)
+    else:
+        for line in summary:
+            click.echo(line)
+    raise SystemExit(exit_code(status))
+
+
+def _run_single(tool: str, action: Callable[[], dict[str, Any]], as_json: bool) -> None:
+    """Run one section mutation and report it."""
+    status, reason, fields = _split(action())
+    _emit(
+        tool,
+        status,
+        reason,
+        fields,
+        as_json=as_json,
+        summary=_summary(tool, status, reason, fields),
+    )
+
+
+@click.group(
+    name="cc",
+    help="Claude Code integration helpers (machine-readable five-state JSON).",
+)
+def cc_group() -> None:
+    """Claude Code domain entry point (``check`` plus the write commands)."""
+
+
+@cc_group.command(name="check")
+@click.option(
+    "--json",
+    "as_json",
+    is_flag=True,
+    help=_JSON_HELP,
+)
+def check(as_json: bool) -> None:
+    """Report the Claude Code host state without writing anything.
+
+    The report nests the same-process ``wl env check`` payload under ``env``
+    and adds the read-only host sections ``plugins`` / ``mcp`` / ``settings``
+    / ``stamps`` / ``hooks`` / ``statusline``. Every section carries its own
+    five-state ``status`` and a readable ``reason``; one failing section never
+    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).
+    """
+    status, reason, sections = build_report()
+    if as_json:
+        dump(status, status in OK_STATUSES, tool=TOOL, reason=reason, **sections)
+        raise SystemExit(exit_code(status))
+
+    for line in _summary_lines(status, reason, sections):
+        click.echo(line)
+    raise SystemExit(exit_code(status))
+
+
+@cc_group.command(name="init")
+@click.option("--json", "as_json", is_flag=True, help=_JSON_HELP)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    help="Run every probe and report the plan without writing anything.",
+)
+def init_command(as_json: bool, dry_run: bool) -> None:
+    """Provision the host and write the ``init-done`` stamp (idempotent).
+
+    Every section is probed first and only its difference is acted on, so a
+    second run is a no-op. ``env`` is reported but never mutated: installing
+    ``wl`` itself is ``wl env repair``'s single literal. The ``init-done``
+    stamp is skipped when a section is ``error`` or ``unverifiable``.
+    """
+    status, reason, fields = mutate.run_init(dry_run=dry_run)
+    _emit(
+        "cc init",
+        status,
+        reason,
+        fields,
+        as_json=as_json,
+        summary=_report_summary("cc init", status, reason, fields),
+    )
+
+
+@cc_group.command(name="repair")
+@click.option("--json", "as_json", is_flag=True, help=_JSON_HELP)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    help="Run every probe and report the plan without writing anything.",
+)
+@click.option(
+    "--section",
+    "sections",
+    multiple=True,
+    type=click.Choice(mutate.MUTABLE_SECTIONS),
+    help="Repair only this section (repeatable; default: all of them).",
+)
+def repair_command(as_json: bool, dry_run: bool, sections: tuple[str, ...]) -> None:
+    """Repair the selected sections; only the difference is written.
+
+    ``disabled`` plugins are never re-enabled, an existing claude-mem
+    ``settings.json`` and a conflicting statusline are never overwritten, and
+    the MCP stamp is written only when both servers registered. ``repaired``
+    is reported only for a section that actually wrote.
+    """
+    status, reason, fields = mutate.run_repair(sections or None, dry_run=dry_run)
+    _emit(
+        "cc repair",
+        status,
+        reason,
+        fields,
+        as_json=as_json,
+        summary=_report_summary("cc repair", status, reason, fields),
+    )
+
+
+@cc_group.command(name="upgrade")
+@click.option("--json", "as_json", is_flag=True, help=_JSON_HELP)
+def upgrade_command(as_json: bool) -> None:
+    """Upgrade the wlcc Claude Code plugin (not the ``wl`` binary).
+
+    Refreshes the ``wlcc`` marketplace (adding it when unregistered) and runs
+    ``claude plugin update wlcc@wlcc -s user``. The installed version comes
+    from ``installed_plugins.json``'s ``scope: user`` entry; a changed version
+    sets ``requires_restart``. ``wl self update`` / ``wl env repair`` own the
+    CLI itself and are deliberately a different command.
+    """
+    _run_single("cc upgrade", mutate.upgrade_wlcc, as_json)
+
+
+@cc_group.group(name="plugins")
+def plugins_group() -> None:
+    """Required-plugin provisioning (never re-enables a disabled plugin)."""
+
+
+@plugins_group.command(name="ensure")
+@click.option("--json", "as_json", is_flag=True, help=_JSON_HELP)
+def plugins_ensure(as_json: bool) -> None:
+    """Install only the missing required plugins.
+
+    Disabled plugins are already installed and are never re-enabled; only an
+    entry absent from the registry is installed.
+    """
+    _run_single("cc plugins ensure", mutate.ensure_plugins, as_json)
+
+
+@plugins_group.command(name="list")
+@click.option("--json", "as_json", is_flag=True, help=_JSON_HELP)
+def plugins_list(as_json: bool) -> None:
+    """Report plugin presence and enable state without writing."""
+    _run_single("cc plugins list", lambda: mutate.probe_section("plugins"), as_json)
+
+
+@cc_group.group(name="mcp")
+def mcp_group() -> None:
+    """MCP server registration and the version stamp."""
+
+
+@mcp_group.command(name="ensure")
+@click.option("--json", "as_json", is_flag=True, help=_JSON_HELP)
+def mcp_ensure(as_json: bool) -> None:
+    """Re-register both MCP servers; the stamp is written only on full success."""
+    _run_single("cc mcp ensure", mutate.ensure_mcp, as_json)
+
+
+@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."""
+    _run_single("cc mcp list", lambda: mutate.probe_section("mcp"), as_json)
+
+
+@cc_group.group(name="settings")
+def settings_group() -> None:
+    """Host-side settings: gstack skill and claude-mem configuration."""
+
+
+@settings_group.command(name="apply")
+@click.option("--json", "as_json", is_flag=True, help=_JSON_HELP)
+def settings_apply(as_json: bool) -> None:
+    """Provision gstack and write claude-mem's settings only when they are absent.
+
+    An existing claude-mem ``settings.json`` is never overwritten; a differing
+    model stays a merge-it-yourself state.
+    """
+    _run_single("cc settings apply", mutate.ensure_settings, as_json)
+
+
+@settings_group.command(name="check")
+@click.option("--json", "as_json", is_flag=True, help=_JSON_HELP)
+def settings_check(as_json: bool) -> None:
+    """Report gstack and claude-mem without writing."""
+    _run_single("cc settings check", lambda: mutate.probe_section("settings"), as_json)
+
+
+@cc_group.group(name="statusline")
+def statusline_group() -> None:
+    """The claude-hud statusLine (merge-write, never overwrite a conflict)."""
+
+
+@statusline_group.command(name="write")
+@click.option("--json", "as_json", is_flag=True, help=_JSON_HELP)
+def statusline_write(as_json: bool) -> None:
+    """Write the claude-hud command; a conflicting statusline is never overwritten.
+
+    The write is backed up, atomically replaced and self-checked: every key
+    other than ``statusLine`` must stay byte-identical.
+    """
+    _run_single("cc statusline write", mutate.write_statusline, as_json)
+
+
+@statusline_group.command(name="check")
+@click.option("--json", "as_json", is_flag=True, help=_JSON_HELP)
+def statusline_check(as_json: bool) -> None:
+    """Report the configured statusline without writing."""
+    _run_single(
+        "cc statusline check", lambda: mutate.probe_section("statusline"), as_json
+    )
+
+
+@cc_group.group(name="hooks")
+def hooks_group() -> None:
+    """Dangling hook commands (rewrite preferred over prune)."""
+
+
+@hooks_group.command(name="check")
+@click.option("--json", "as_json", is_flag=True, help=_JSON_HELP)
+def hooks_check(as_json: bool) -> None:
+    """Report dangling hook commands without writing."""
+    _run_single("cc hooks check", lambda: mutate.probe_section("hooks"), as_json)
+
+
+@hooks_group.command(name="repair")
+@click.option("--json", "as_json", is_flag=True, help=_JSON_HELP)
+def hooks_repair(as_json: bool) -> None:
+    """Rewrite or prune dangling hook commands with a backup and self-check.
+
+    Rewrite wins over prune; only a command whose every dangling path has no
+    local counterpart is pruned. Nothing is written when the plan is identical
+    to the file.
+    """
+    _run_single("cc hooks repair", mutate.repair_hooks, as_json)
+
+
+@cc_group.group(name="stamps")
+def stamps_group() -> None:
+    """The wlcc stamp registry under ``~/.config/wlcc``."""
+
+
+@stamps_group.command(name="check")
+@click.option("--json", "as_json", is_flag=True, help=_JSON_HELP)
+def stamps_check(as_json: bool) -> None:
+    """Report retired and unregistered stamps without deleting anything.
+
+    Deleting the retired list is part of ``wl cc repair``; unregistered entries
+    are reported and kept here and there.
+    """
+    _run_single("cc stamps check", lambda: mutate.probe_section("stamps"), as_json)