devex-cli 0.24.0__py3-none-any.whl

agent_experience/commands/doctor/scripts/doctor.py

@@ -0,0 +1,394 @@
+"""`agex doctor` — read-only health check.
+
+Composes a list of per-check `CheckResult` rows grouped into categories, then
+renders them through the Jinja report template.  No side effects: never calls
+``ensure_init`` or touches the filesystem outside of read attempts.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from dataclasses import dataclass, field
+from importlib.resources import as_file, files
+from importlib.resources.abc import Traversable
+from pathlib import Path
+from typing import Literal
+
+import yaml
+
+from agent_experience import __version__
+from agent_experience.core.paths import (
+    GITIGNORE_CONTENT,
+    agex_dir,
+    config_path,
+    data_dir,
+)
+from agent_experience.core.prog import error_prefix
+from agent_experience.core.render import render_string
+from agent_experience.core.skill_loader import load_skill
+
+Status = Literal["ok", "warn", "fail", "info"]
+_ROLE_RE = re.compile(r"^[a-z][a-z0-9-]*$")
+_MIN_PYTHON = (3, 10)
+
+# Check-row names — kept as constants so each appears once in source
+# (sonar python:S1192).
+_NAME_AGEX_VERSION = "agex version"
+_NAME_PYTHON = "Python"
+_NAME_PACKAGE_RESOURCES = "Package resources"
+_NAME_AGEX_DIR = "`.agex/` directory"
+_NAME_CONFIG_TOML = "`.agex/config.toml`"
+_NAME_GITIGNORE = "`.agex/.gitignore`"
+_NAME_DATA_DIR = "`.agex/data/`"
+_NAME_SKILL_MD = "Shipped SKILL.md frontmatter"
+_NAME_CAPABILITY_YAML = "Backend capability YAML"
+
+
+@dataclass
+class CheckResult:
+    name: str
+    status: Status
+    detail: str
+
+
+@dataclass
+class Category:
+    title: str
+    results: list[CheckResult] = field(default_factory=list)
+
+
+def _commands_root() -> Traversable:
+    return files("agent_experience.commands")
+
+
+def _doctor_assets() -> Traversable:
+    return files("agent_experience.commands").joinpath("doctor", "assets")
+
+
+# --- Install checks --------------------------------------------------------
+
+
+def _check_version() -> CheckResult:
+    if not __version__:
+        return CheckResult(
+            _NAME_AGEX_VERSION,
+            "fail",
+            "Could not resolve `agent_experience.__version__`. Reinstall with "
+            "`uv pip install -e .[dev]`, `pipx install agex-cli`, "
+            "`pipx install agent-devex`, or `pipx install devex-cli`.",
+        )
+    return CheckResult(_NAME_AGEX_VERSION, "ok", __version__)
+
+
+def _check_python() -> CheckResult:
+    cur = sys.version_info[:3]
+    detail = ".".join(str(p) for p in cur)
+    if cur[:2] < _MIN_PYTHON:
+        return CheckResult(
+            _NAME_PYTHON,
+            "fail",
+            f"{detail} (need >= {_MIN_PYTHON[0]}.{_MIN_PYTHON[1]})",
+        )
+    return CheckResult(_NAME_PYTHON, "ok", detail)
+
+
+def _check_resources() -> CheckResult:
+    # Probe assets that doctor itself depends on at runtime, plus a sentinel
+    # from a sibling command — broken packaging surfaces here rather than
+    # later when a render call raises.
+    required = [
+        ("explain", "assets", "topics", "agex.md"),
+        ("doctor", "assets", "report.md.j2"),
+    ]
+    try:
+        cmds = _commands_root()
+        for parts in required:
+            if not cmds.joinpath(*parts).is_file():
+                return CheckResult(
+                    _NAME_PACKAGE_RESOURCES,
+                    "fail",
+                    f"missing shipped asset `commands/{'/'.join(parts)}`. "
+                    "Reinstall the package.",
+                )
+    except Exception as exc:  # pragma: no cover - defensive only
+        return CheckResult(_NAME_PACKAGE_RESOURCES, "fail", f"resource lookup raised: {exc}")
+    return CheckResult(_NAME_PACKAGE_RESOURCES, "ok", "all shipped assets reachable")
+
+
+# --- Project state checks --------------------------------------------------
+
+
+def _check_agex_dir() -> CheckResult:
+    root = agex_dir()
+    if not root.exists():
+        return CheckResult(
+            _NAME_AGEX_DIR,
+            "info",
+            f"not initialized at `{root}` — run any backend-aware command "
+            "(e.g. `agex overview --agent claude-code`) to bootstrap.",
+        )
+    if not root.is_dir():
+        return CheckResult(
+            _NAME_AGEX_DIR,
+            "fail",
+            f"`{root}` exists but is not a directory.",
+        )
+    return CheckResult(_NAME_AGEX_DIR, "ok", str(root))
+
+
+def _check_config_toml() -> CheckResult:
+    path = config_path()
+    if not path.exists():
+        return CheckResult(
+            _NAME_CONFIG_TOML,
+            "info",
+            "not present (expected when `.agex/` is uninitialized).",
+        )
+
+    # Parse defensively — config.load() raises on malformed TOML, which we
+    # catch and surface as a fail row rather than letting bubble up.
+    try:
+        from agent_experience.core import config as config_module
+
+        cfg = config_module.load()
+    except Exception as exc:
+        return CheckResult(
+            _NAME_CONFIG_TOML,
+            "fail",
+            f"failed to parse: {exc}. Edit or delete the file.",
+        )
+
+    if cfg.agex_version and cfg.agex_version != __version__:
+        return CheckResult(
+            _NAME_CONFIG_TOML,
+            "warn",
+            (
+                f'`agex_version = "{cfg.agex_version}"` does not match installed '
+                f"`{__version__}`. Will reconcile on next write."
+            ),
+        )
+    return CheckResult(_NAME_CONFIG_TOML, "ok", f"version {cfg.agex_version}")
+
+
+def _check_gitignore() -> CheckResult:
+    root = agex_dir()
+    gi = root / ".gitignore"
+    if not root.exists():
+        return CheckResult(_NAME_GITIGNORE, "info", "skipped (no `.agex/`).")
+    if not gi.exists():
+        return CheckResult(
+            _NAME_GITIGNORE,
+            "warn",
+            "missing — `data/` may end up tracked. Re-run any agex command to restore.",
+        )
+    try:
+        actual = gi.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        return CheckResult(
+            _NAME_GITIGNORE,
+            "fail",
+            f"could not read `{gi}`: {exc}. Check permissions and encoding.",
+        )
+    if actual != GITIGNORE_CONTENT:
+        return CheckResult(
+            _NAME_GITIGNORE,
+            "warn",
+            "content drifted from the managed default — `data/` may not be ignored.",
+        )
+    return CheckResult(_NAME_GITIGNORE, "ok", "matches managed content")
+
+
+def _check_data_dir() -> CheckResult:
+    if not agex_dir().exists():
+        return CheckResult(_NAME_DATA_DIR, "info", "skipped (no `.agex/`).")
+    d = data_dir()
+    if not d.exists():
+        return CheckResult(
+            _NAME_DATA_DIR,
+            "warn",
+            f"`{d}` is missing — re-run any agex command to recreate it.",
+        )
+    if not d.is_dir():
+        return CheckResult(_NAME_DATA_DIR, "fail", f"`{d}` is not a directory.")
+    # Read-only contract — no probe write. Just check perms.
+    import os
+
+    if not os.access(d, os.W_OK):
+        return CheckResult(_NAME_DATA_DIR, "fail", f"`{d}` is not writable.")
+    return CheckResult(_NAME_DATA_DIR, "ok", str(d))
+
+
+# --- Internal consistency checks -------------------------------------------
+
+
+def _iter_skill_relpaths() -> list[str]:
+    with as_file(_commands_root()) as root:
+        return sorted("/".join(p.relative_to(root).parts) for p in root.glob("**/SKILL.md"))
+
+
+def _check_skill_md_consistency() -> CheckResult:
+    relpaths = _iter_skill_relpaths()
+    if not relpaths:
+        return CheckResult(
+            _NAME_SKILL_MD,
+            "fail",
+            "No SKILL.md files discovered — package data is missing.",
+        )
+    failures: list[str] = []
+    with as_file(_commands_root()) as root:
+        for rel in relpaths:
+            try:
+                load_skill(root / rel)
+            except Exception as exc:
+                failures.append(f"{rel}: {exc}")
+    if failures:
+        return CheckResult(
+            _NAME_SKILL_MD,
+            "fail",
+            f"{len(failures)} of {len(relpaths)} failed: {'; '.join(failures)}",
+        )
+    return CheckResult(
+        _NAME_SKILL_MD,
+        "ok",
+        f"{len(relpaths)} files parse cleanly",
+    )
+
+
+def _check_capability_yaml() -> CheckResult:
+    failures: list[str] = []
+    count = 0
+    with as_file(_commands_root()) as root:
+        for path in root.glob("**/assets/backends/*.yaml"):
+            count += 1
+            try:
+                yaml.safe_load(path.read_text(encoding="utf-8"))
+            except Exception as exc:
+                failures.append(f"{path.relative_to(root)}: {exc}")
+    if failures:
+        return CheckResult(
+            _NAME_CAPABILITY_YAML,
+            "fail",
+            f"{len(failures)} of {count} failed: {'; '.join(failures)}",
+        )
+    if count == 0:
+        # `overview` already ships per-backend YAMLs, so finding zero at
+        # runtime indicates a broken wheel rather than expected state.
+        return CheckResult(
+            _NAME_CAPABILITY_YAML,
+            "fail",
+            "no per-backend YAML files found — package data is missing. Reinstall.",
+        )
+    return CheckResult(_NAME_CAPABILITY_YAML, "ok", f"{count} files parse cleanly")
+
+
+# --- Operator verification (markdown-only, no programmatic check) ----------
+
+
+_OPERATOR_CHECKLIST = [
+    "Confirm `.agex/config.toml` is committed and `.agex/data/` is gitignored.",
+    "Confirm your shell tool can invoke `agex --version` and `agex doctor`.",
+    "If you installed hooks via `agex gamify`, confirm the backend hook file "
+    "still contains the `agex:` fragment IDs recorded in `.agex/config.toml`.",
+]
+
+
+# --- Role section ----------------------------------------------------------
+
+
+def _resolve_role(role: str) -> Traversable | None:
+    if not _ROLE_RE.match(role):
+        return None
+    candidate = _doctor_assets().joinpath("roles", f"{role}.md.j2")
+    return candidate if candidate.is_file() else None
+
+
+# --- Aggregation -----------------------------------------------------------
+
+
+def _build_categories() -> list[Category]:
+    return [
+        Category(
+            "Install",
+            [_check_version(), _check_python(), _check_resources()],
+        ),
+        Category(
+            "Project state",
+            [
+                _check_agex_dir(),
+                _check_config_toml(),
+                _check_gitignore(),
+                _check_data_dir(),
+            ],
+        ),
+        Category(
+            "Internal consistency",
+            [_check_skill_md_consistency(), _check_capability_yaml()],
+        ),
+    ]
+
+
+def _summarize(categories: list[Category]) -> dict[str, int]:
+    summary = {"ok": 0, "warn": 0, "fail": 0, "info": 0}
+    for cat in categories:
+        for r in cat.results:
+            summary[r.status] += 1
+    return summary
+
+
+def run(role: str | None = None) -> tuple[str, int, str]:
+    """Return ``(stdout, exit_code, stderr)``.
+
+    Read-only.  Never initializes ``.agex/``.
+    """
+    if role is not None and _ROLE_RE.match(role) is None:
+        return ("", 2, error_prefix(f"invalid role slug '{role}'"))
+
+    role_section: str | None = None
+    if role is not None:
+        trav = _resolve_role(role)
+        if trav is None:
+            return ("", 2, error_prefix(f"unknown role '{role}'"))
+        try:
+            role_text = trav.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError) as exc:
+            return ("", 1, error_prefix(f"could not read role asset for '{role}': {exc}"))
+        # Role assets are Jinja templates per the addendum spec; v0.1 passes
+        # an empty context but rendering still resolves any `{% raw %}` /
+        # `{{ }}` markup the role file may use, rather than dumping it raw.
+        try:
+            role_section = render_string(role_text, {})
+        except Exception as exc:
+            return ("", 1, error_prefix(f"failed to render role '{role}': {exc}"))
+
+    categories = _build_categories()
+    summary = _summarize(categories)
+
+    try:
+        template_text = _doctor_assets().joinpath("report.md.j2").read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        return (
+            "",
+            1,
+            error_prefix(
+                f"could not read `doctor/assets/report.md.j2`: {exc}. "
+                "Reinstall the package."
+            ),
+        )
+    out = render_string(
+        template_text,
+        {
+            "version": __version__,
+            "project_dir": str(Path.cwd()),
+            "categories": categories,
+            "operator_checklist": _OPERATOR_CHECKLIST,
+            "role": role,
+            "role_section": role_section,
+            "summary": summary,
+        },
+    )
+
+    if summary["fail"] > 0:
+        stderr = error_prefix(f"{summary['fail']} health check(s) failed")
+        return (out, 1, stderr)
+    return (out, 0, "")

agent_experience/commands/explain/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: explain
+description: Emit markdown documentation for any agex command, lesson, or concept.
+type: command
+---
+
+# `agex explain <topic>`
+
+Use this to get authoritative, deterministic documentation on an agex command, lesson, or concept without invoking a lesson or running a probe.
+
+## How it resolves
+
+1. `commands/<topic>/SKILL.md` (command-level, wins if present)
+2. `commands/learn/assets/topics/<topic>/SKILL.md` (lesson-level)
+3. `commands/explain/assets/topics/<topic>.md` (concept-level override)
+
+First match wins.
+
+## From your shell tool
+
+```bash
+agex explain overview
+agex explain gamify
+agex explain levelup
+agex explain agex          # self-describing page
+```

agent_experience/commands/explain/assets/topics/agex.md

@@ -0,0 +1,37 @@
+# `agex` — agent-operated developer-experience CLI
+
+`agex` is a non-agentic Python CLI that emits deterministic per-backend markdown for autonomous agents. You (the agent) invoke it from your shell tool to learn about and configure your own runtime.
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `agex overview --agent X` | Snapshot of the project's current setup for backend X. |
+| `agex learn --agent X` | Menu of lesson topics available for backend X. |
+| `agex learn <topic> --agent X` | Teach a lesson (e.g., introspect, visualize, gamify, levelup). |
+| `agex gamify --agent X` | Install usage-tracking hooks (or unsupported notice). |
+| `agex gamify --uninstall --agent X` | Reverse `gamify`. |
+| `agex hook write <event> [...]` | Append a tracking event. Called by installed hooks. |
+| `agex hook read --agent X` | Show tracked events as markdown + source path. |
+| `agex doctor` | Diagnose agex install + repo setup. |
+| `agex explain <topic>` | You're reading this. |
+
+## First steps
+
+```bash
+agex explain agex              # this page
+agex doctor                    # is the install + repo healthy?
+agex learn --agent claude-code  # what can I learn for my backend?
+agex overview --agent claude-code  # what's in this project?
+```
+
+## Design invariants
+
+- **Non-agentic.** Zero LLM calls inside agex. All output is deterministic.
+- **Markdown is the universal format.** No `--json` flag.
+- **`--agent` is required** on backend-sensitive commands.
+- **Unsupported is success.** If your backend lacks a feature, you get a markdown notice + link to file an issue — exit code 0.
+
+## Repo
+
+<https://github.com/agentculture/devex>

agent_experience/commands/explain/scripts/explain.py

@@ -0,0 +1,64 @@
+import re
+from importlib.resources import files
+from importlib.resources.abc import Traversable
+
+from agent_experience.core.prog import error_prefix
+from agent_experience.core.skill_loader import Skill, load_skill
+
+_TOPIC_RE = re.compile(r"^[a-z][a-z0-9-]*$")
+
+
+def _commands_root() -> Traversable:
+    return files("agent_experience.commands")
+
+
+def resolve_topic(topic: str) -> tuple[str, Traversable] | None:
+    """Resolve topic per spec precedence. Returns (kind, traversable) or None.
+
+    Rejects any topic that isn't a simple slug to prevent path traversal.
+    """
+    if not _TOPIC_RE.match(topic):
+        return None
+
+    cmds = _commands_root()
+
+    cmd_skill = cmds.joinpath(topic, "SKILL.md")
+    if cmd_skill.is_file():
+        return ("command", cmd_skill)
+
+    lesson_skill = cmds.joinpath("learn", "assets", "topics", topic, "SKILL.md")
+    if lesson_skill.is_file():
+        return ("lesson", lesson_skill)
+
+    concept = cmds.joinpath("explain", "assets", "topics", f"{topic}.md")
+    if concept.is_file():
+        return ("concept", concept)
+
+    return None
+
+
+def _load_skill_from_traversable(trav: Traversable) -> Skill:
+    # load_skill expects a pathlib.Path; resolve via as_file when needed. Since
+    # our package resources are on a real filesystem (hatch force-include), the
+    # Traversable is a MultiplexedPath / PosixPath wrapper whose .read_text()
+    # works directly. We rebuild a Skill by parsing the body in-line to avoid
+    # Path coupling.
+    from importlib.resources import as_file
+
+    with as_file(trav) as path:
+        return load_skill(path)
+
+
+def run(topic: str) -> tuple[str, int, str]:
+    """Return (stdout, exit_code, stderr)."""
+    resolved = resolve_topic(topic)
+    if resolved is None:
+        agex_page = _commands_root().joinpath("explain", "assets", "topics", "agex.md")
+        body = agex_page.read_text(encoding="utf-8") if agex_page.is_file() else ""
+        return (body, 2, error_prefix(f"unknown topic '{topic}'"))
+
+    kind, trav = resolved
+    if kind == "concept":
+        return (trav.read_text(encoding="utf-8"), 0, "")
+    skill = _load_skill_from_traversable(trav)
+    return (skill.body, 0, "")

agent_experience/commands/gamify/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: gamify
+description: Install or uninstall backend-native hooks that track usage via agex hook write.
+type: command
+---
+
+# `agex gamify --agent <backend>` / `agex gamify --uninstall --agent <backend>`
+
+## What it does
+
+Writes backend-native hook fragments (each tagged with a stable `agex:*` ID) that call `agex hook write <event>` on PostToolUse, UserPromptSubmit, and Stop events. Agent-authored skills (e.g., `levelup`) read the accumulated data via `agex hook read`.
+
+## Why it's safe
+
+- Idempotent: re-running is a no-op.
+- Reversible: `--uninstall` removes exactly the `agex:*` fragments; user-authored hooks are untouched.
+- Calling `agex gamify` explicitly is the confirmation — no separate prompt.
+
+## Unsupported backends
+
+If your backend doesn't support hooks, you get a markdown notice + issue link instead.
+
+## From your shell tool
+
+```bash
+agex gamify --agent claude-code
+# ... use your runtime for a while ...
+agex hook read --agent claude-code
+# ... later, to undo:
+agex gamify --uninstall --agent claude-code
+```

agent_experience/commands/gamify/assets/hooks/claude-code.json

@@ -0,0 +1,28 @@
+{
+  "fragments": [
+    {
+      "id": "agex:post-tool-use",
+      "event": "PostToolUse",
+      "hook": {
+        "type": "command",
+        "command": "agex hook write post-tool-use tool=\"$CLAUDE_TOOL_NAME\""
+      }
+    },
+    {
+      "id": "agex:user-prompt",
+      "event": "UserPromptSubmit",
+      "hook": {
+        "type": "command",
+        "command": "agex hook write user-prompt"
+      }
+    },
+    {
+      "id": "agex:stop",
+      "event": "Stop",
+      "hook": {
+        "type": "command",
+        "command": "agex hook write stop"
+      }
+    }
+  ]
+}