@event4u/agent-config 2.15.0 → 2.17.0

package/scripts/_cli/cmd_doctor.py

@@ -35,6 +35,7 @@ from __future__ import annotations
 import argparse
 import hashlib
 import json
+import os
 import re
 import shutil
 import sys
@@ -42,6 +43,13 @@ from pathlib import Path
 from typing import Any
 
 from scripts._lib import installed_tools
+from scripts._lib.agent_settings import (
+    PROJECT_ROOT_ENV,
+    ROOT_OVERRIDE_ENV,
+    ProjectRootError,
+    find_project_root_with_trace,
+    resolve_project_root,
+)
 
 
 class _Sentinel:
@@ -56,10 +64,155 @@ class _Sentinel:
 NO_FRONTMATTER = _Sentinel()
 
 
-def _resolve_project_root(arg: str | None) -> Path:
-    if arg:
-        return Path(arg).expanduser().resolve()
-    return Path.cwd().resolve()
+def _resolve_project_root(arg: str | None) -> tuple[Path, str]:
+    """Resolve the doctor's project root via the shared Phase-3 helper.
+
+    Returns ``(root, origin)`` where ``origin`` is one of the anchor
+    names from :mod:`scripts._lib.agent_settings` (``agents-dir``,
+    ``git``, ``agent-settings``) or one of the origin tags
+    ``root-flag`` / ``explicit`` / ``env`` / ``cwd-fallback``. The tag
+    is surfaced in both human and JSON output so subdir invocations
+    are auditable.
+    """
+    return resolve_project_root(arg)
+
+
+#: Path of the install-mode marker file (Step 8 A5). One-line file:
+#: ``minimal\n`` or ``full\n``. Written by ``install.py``; consumed by
+#: ``doctor --context`` to surface install state without re-deriving it
+#: from filesystem heuristics.
+_INSTALL_MODE_MARKER_REL = "agents/.agent-state/install-mode.txt"
+
+
+def _detect_install_mode(project_root: Path) -> tuple[str, str]:
+    """Return ``(mode, source)`` for the project install state.
+
+    Hybrid detection (Step 8 council decision Q5):
+
+    1. ``agents/.agent-state/install-mode.txt`` if present (authoritative
+       for installs since Step 8) → ``source="marker-file"``.
+    2. Filesystem heuristic for back-compat: ``AGENTS.md`` + copilot
+       bridges → ``full``; otherwise ``minimal`` → ``source="heuristic"``.
+
+    Heuristic is fragile by design — users who delete ``AGENTS.md`` but
+    keep copilot bridges get misreported. The marker file is the
+    intended source of truth for installs from Step 8 onward.
+    """
+    marker = project_root / _INSTALL_MODE_MARKER_REL
+    if marker.is_file():
+        try:
+            value = marker.read_text(encoding="utf-8").strip()
+        except OSError:
+            value = ""
+        if value in ("minimal", "full"):
+            return value, "marker-file"
+    has_agents_md = (project_root / "AGENTS.md").exists()
+    has_copilot = (project_root / ".github" / "copilot-instructions.md").exists()
+    if has_agents_md and has_copilot:
+        return "full", "heuristic"
+    return "minimal", "heuristic"
+
+
+def _settings_layer_chain(project_root: Path) -> list[str]:
+    """Return the ordered ``.agent-settings.yml`` layer files that exist.
+
+    Shallowest first (user-global → project root). Used by ``--context``
+    to surface which layers will participate in the cascade merge.
+    """
+    layers: list[str] = []
+    from scripts._lib import user_global_paths
+    user_global = user_global_paths.resolve_with_fallback("agent-settings.yml")
+    if user_global is not None and user_global.is_file():
+        layers.append(str(user_global))
+    project_settings = project_root / ".agent-settings.yml"
+    if project_settings.is_file():
+        layers.append(str(project_settings))
+    return layers
+
+
+def _detect_wrapper(project_root: Path) -> dict[str, Any]:
+    """Return ``{path, exists, embedded_root}`` for the project wrapper.
+
+    The ``./agent-config`` wrapper at the project root pins
+    ``AGENT_CONFIG_PROJECT_ROOT`` to its own ``SELF_DIR``, so the
+    "embedded root" is just the wrapper's directory. Surfaced for
+    debugging wrapper-coupling issues (Step 8 A3-coupling).
+    """
+    wrapper = project_root / "agent-config"
+    if not wrapper.exists():
+        return {"path": str(wrapper), "exists": False, "embedded_root": None}
+    return {
+        "path": str(wrapper),
+        "exists": True,
+        "embedded_root": str(project_root),
+    }
+
+
+def _emit_trace_text(
+    root: Path | None,
+    anchor: str | None,
+    trace: list[dict[str, Any]],
+    origin: str,
+) -> None:
+    """Render the discovery trace as human-readable text."""
+    print(f"  📍  start: {Path.cwd()}")
+    print(f"  📍  origin: {origin}")
+    if trace:
+        print("  trace:")
+        for record in trace:
+            hit = record["hit"]
+            symbol = "✅" if hit else "·"
+            tag = f"[{record['pass']}]"
+            anchor_str = f" → {hit}" if hit else ""
+            print(
+                f"    {symbol} {tag} {record['ancestor']}"
+                f"{anchor_str}  ({record['reason']})"
+            )
+    if root is not None:
+        print(f"  📍  resolved root: {root} (anchor: {anchor or 'n/a'})")
+    else:
+        print("  ⚠️   no anchor found in chain")
+
+
+def _emit_trace_json(
+    root: Path | None,
+    anchor: str | None,
+    trace: list[dict[str, Any]],
+    origin: str,
+) -> None:
+    """Render the discovery trace as a JSON payload."""
+    payload: dict[str, Any] = {
+        "start": str(Path.cwd()),
+        "origin": origin,
+        "resolved_root": str(root) if root is not None else None,
+        "anchor": anchor,
+        "trace": trace,
+    }
+    print(json.dumps(payload, indent=2))
+
+
+def _emit_context_text(ctx: dict[str, Any]) -> None:
+    """Render the install / discovery context as human-readable text."""
+    print(f"  📍  project_root: {ctx['project_root']}  (origin: {ctx['origin']})")
+    print(f"  📦  install_mode: {ctx['install_mode']}  (source: {ctx['install_mode_source']})")
+    env_pin = ctx.get("env_pin")
+    if env_pin:
+        marker = " (--root override)" if ctx.get("root_override") else ""
+        print(f"  🔒  env_pin: {env_pin}{marker}")
+    else:
+        print("  🔒  env_pin: (unset)")
+    layers = ctx.get("settings_layers") or []
+    if layers:
+        print(f"  📑  settings layers ({len(layers)}):")
+        for layer in layers:
+            print(f"        - {layer}")
+    else:
+        print("  📑  settings layers: (none)")
+    wrapper = ctx.get("wrapper") or {}
+    if wrapper.get("exists"):
+        print(f"  🧩  wrapper: {wrapper['path']}  (embedded root: {wrapper.get('embedded_root')})")
+    else:
+        print(f"  🧩  wrapper: (not present at {wrapper.get('path')})")
 
 
 def _resolve_path(project_root: Path, raw: str) -> Path:
@@ -872,6 +1025,7 @@ def _emit_json(
     foreign: list[dict[str, Any]],
     tag_drift: list[dict[str, Any]],
     checks: list[dict[str, Any]] | None = None,
+    origin: str | None = None,
 ) -> None:
     payload: dict[str, Any] = {
         "project_root": str(project_root),
@@ -880,6 +1034,8 @@ def _emit_json(
         "foreign": foreign,
         "tag_drift": tag_drift,
     }
+    if origin is not None:
+        payload["project_root_origin"] = origin
     if checks is not None:
         payload["checks"] = checks
     print(json.dumps(payload, indent=2))
@@ -948,17 +1104,89 @@ def _parse(argv: list[str]) -> argparse.Namespace:
         help=("run a single health check by id "
               f"({' · '.join(CHECK_IDS)})"),
     )
+    parser.add_argument(
+        "--trace-root", action="store_true",
+        help=("print every ancestor checked during project-root discovery "
+              "plus the winning anchor; short-circuits the drift report"),
+    )
+    parser.add_argument(
+        "--context", action="store_true",
+        help=("print effective project root, anchor, env-pin, settings "
+              "layer chain, wrapper, and install-mode; short-circuits "
+              "the drift report"),
+    )
     return parser.parse_args(argv)
 
 
+def _run_trace_root(opts: argparse.Namespace) -> int:
+    """Handle ``--trace-root``: discovery walk + records, no drift report."""
+    start = Path.cwd()
+    root, anchor, trace = find_project_root_with_trace(start)
+    # Determine origin label even when no anchor is found.
+    if os.environ.get(ROOT_OVERRIDE_ENV) == "1" and os.environ.get(PROJECT_ROOT_ENV):
+        origin = "root-flag"
+    elif opts.project:
+        origin = "explicit"
+    elif os.environ.get(PROJECT_ROOT_ENV):
+        origin = "env"
+    elif root is not None:
+        origin = anchor or "unknown"
+    else:
+        origin = "cwd-fallback"
+    if opts.json:
+        _emit_trace_json(root, anchor, trace, origin)
+    else:
+        _emit_trace_text(root, anchor, trace, origin)
+    return 0
+
+
+def _run_context(opts: argparse.Namespace) -> int:
+    """Handle ``--context``: install + discovery snapshot, no drift report."""
+    try:
+        project_root, origin = _resolve_project_root(opts.project)
+    except ProjectRootError as exc:
+        print(f"❌  doctor: {exc}", file=sys.stderr)
+        return 2
+    mode, mode_source = _detect_install_mode(project_root)
+    ctx: dict[str, Any] = {
+        "project_root": str(project_root),
+        "origin": origin,
+        "install_mode": mode,
+        "install_mode_source": mode_source,
+        "env_pin": os.environ.get(PROJECT_ROOT_ENV) or None,
+        "root_override": os.environ.get(ROOT_OVERRIDE_ENV) == "1",
+        "settings_layers": _settings_layer_chain(project_root),
+        "wrapper": _detect_wrapper(project_root),
+    }
+    if opts.json:
+        print(json.dumps(ctx, indent=2))
+    else:
+        _emit_context_text(ctx)
+    return 0
+
+
 def main(argv: list[str] | None = None) -> int:
     opts = _parse(list(argv) if argv is not None else sys.argv[1:])
-    project_root = _resolve_project_root(opts.project)
+    if opts.trace_root:
+        return _run_trace_root(opts)
+    if opts.context:
+        return _run_context(opts)
+    try:
+        project_root, origin = _resolve_project_root(opts.project)
+    except ProjectRootError as exc:
+        print(f"❌  doctor: {exc}", file=sys.stderr)
+        return 2
     manifest_pth = installed_tools.manifest_path(project_root)
     manifest = installed_tools.read_manifest(manifest_pth)
     if manifest is None:
-        print(f"❌  doctor: no project lockfile at {manifest_pth}",
-              file=sys.stderr)
+        print(
+            f"❌  doctor: no project lockfile at {manifest_pth}",
+            file=sys.stderr,
+        )
+        print(
+            f"    project_root: {project_root} (origin: {origin})",
+            file=sys.stderr,
+        )
         print("    run `./agent-config init` to create one",
               file=sys.stderr)
         return 2
@@ -978,9 +1206,11 @@ def main(argv: list[str] | None = None) -> int:
     if opts.json:
         _emit_json(
             project_root, missing, modified, foreign, tag_drift,
-            checks=checks,
+            checks=checks, origin=origin,
         )
     else:
+        if opts.check is None:
+            print(f"  📍  project_root: {project_root} (origin: {origin})")
         _emit_checks_text(checks)
         if opts.check is None:
             _emit_text(project_root, missing, modified, foreign, tag_drift)

package/scripts/_cli/cmd_migrate.py

@@ -32,6 +32,8 @@ import sys
 from pathlib import Path
 from typing import Iterable, Optional
 
+from scripts._lib.agent_settings import resolve_project_root
+
 PACKAGE_NAME_NPM = "@event4u/agent-config"
 PACKAGE_NAME_COMPOSER = "event4u/agent-config"
 LEGACY_DIRS = ("vendor", "node_modules")
@@ -221,7 +223,10 @@ def main(
                         help="Detect only; do not write any files.")
     args = parser.parse_args(argv)
 
-    project = (cwd or Path.cwd()).resolve()
+    # Phase 3 — honor AGENT_CONFIG_PROJECT_ROOT + anchor walk so
+    # ``agent-config migrate`` invoked from a subdir still targets the
+    # real project root. ``cwd`` kwarg is preserved for test injection.
+    project, _ = resolve_project_root(None, cwd=cwd)
     version = version or _detect_installed_version()
 
     if _detect_already_migrated(project):

package/scripts/_cli/cmd_prune.py

@@ -43,13 +43,18 @@ import sys
 from pathlib import Path
 
 from scripts._lib import installed_tools
+from scripts._lib.agent_settings import resolve_project_root
 from scripts.install import PROJECT_BRIDGE_MARKERS
 
 
 def _resolve_project_root(arg: str | None) -> Path:
-    if arg:
-        return Path(arg).expanduser().resolve()
-    return Path.cwd().resolve()
+    """Resolve the project root using the shared Phase-3 helper.
+
+    Drops the origin tag — ``prune`` does not surface it in output but
+    still honors ``AGENT_CONFIG_PROJECT_ROOT`` and the anchor walk.
+    """
+    root, _ = resolve_project_root(arg)
+    return root
 
 
 def _load_manifest(project_root: Path, *, force_empty: bool

package/scripts/_cli/cmd_sync.py

@@ -19,6 +19,7 @@ from pathlib import Path
 from typing import Iterable
 
 from scripts._lib import installed_tools
+from scripts._lib.agent_settings import resolve_project_root
 from scripts.install import main as install_main
 
 
@@ -108,9 +109,12 @@ def _emit(quiet: bool, msg: str) -> None:
 
 def main(argv: list[str]) -> int:
     opts = _parse(argv)
-    project_root = Path(
-        opts.project or os.environ.get("PROJECT_ROOT") or os.getcwd()
-    ).resolve()
+    # Phase 3 — shared helper honors AGENT_CONFIG_PROJECT_ROOT (set by
+    # the ./agent-config wrapper) and the Step-7 anchor walk. Legacy
+    # ``PROJECT_ROOT`` env var is preserved as an explicit fallback so
+    # existing CI scripts that set it keep working.
+    arg = opts.project or os.environ.get("PROJECT_ROOT")
+    project_root, _ = resolve_project_root(arg)
     manifest = installed_tools.manifest_path(project_root)
     data = installed_tools.read_manifest(manifest)
 

package/scripts/_cli/cmd_uninstall.py

@@ -38,14 +38,15 @@ from pathlib import Path
 from typing import Any, Iterable
 
 from scripts._lib import fs_atomic, installed_lock, installed_tools
+from scripts._lib.agent_settings import resolve_project_root
 from scripts._lib.json_pointers import subtract_pointers
 from scripts.install import PROJECT_BRIDGE_MARKERS, USER_SCOPE_PATHS
 
 
 def _resolve_project_root(arg: str | None) -> Path:
-    if arg:
-        return Path(arg).expanduser().resolve()
-    return Path.cwd().resolve()
+    """Resolve the project root using the shared Phase-3 helper."""
+    root, _ = resolve_project_root(arg)
+    return root
 
 
 def _filter_tools(all_tools: Iterable[str], requested: str | None) -> list[str]:

package/scripts/_cli/cmd_update.py

@@ -42,6 +42,7 @@ from scripts._lib.agent_settings import (
     DEFAULT_PROJECT_FILE,
     _resolve_cascade_paths,
     find_project_root,
+    resolve_project_root,
 )
 
 PACKAGE_NAME = "@event4u/agent-config"
@@ -164,7 +165,10 @@ def main(
                              "(without --to there is no source for 'latest').")
     args = parser.parse_args(argv)
 
-    cwd = (cwd or Path.cwd()).resolve()
+    # Phase 3 — anchor walk + AGENT_CONFIG_PROJECT_ROOT honored so
+    # ``agent-config update`` from a subdir writes to the right file.
+    # ``cwd`` is kept as a kwarg for test injection.
+    cwd, _ = resolve_project_root(None, cwd=cwd)
     installed_version = installed_version or _detect_installed_version()
     state_path = state_path or update_check.DEFAULT_STATE_PATH
 

package/scripts/_cli/cmd_validate.py

@@ -22,6 +22,7 @@ from pathlib import Path
 from typing import Iterable
 
 from scripts._lib import installed_lock, installed_tools
+from scripts._lib.agent_settings import resolve_project_root
 from scripts.install import PROJECT_BRIDGE_MARKERS, USER_SCOPE_PATHS
 
 
@@ -121,9 +122,11 @@ def _format(issue: dict) -> str:
 
 def main(argv: list[str]) -> int:
     opts = _parse(argv)
-    project_root = Path(
-        opts.project or os.environ.get("PROJECT_ROOT") or os.getcwd()
-    ).resolve()
+    # Phase 3 — honor AGENT_CONFIG_PROJECT_ROOT + anchor walk via the
+    # shared helper. Legacy ``PROJECT_ROOT`` env var stays as a fallback
+    # so existing CI scripts keep working.
+    arg = opts.project or os.environ.get("PROJECT_ROOT")
+    project_root, _ = resolve_project_root(arg)
     manifest = installed_tools.manifest_path(project_root)
     data = installed_tools.read_manifest(manifest)
 

package/scripts/_cli/cmd_versions.py

@@ -18,14 +18,27 @@ import subprocess
 import sys
 from pathlib import Path
 
+from scripts._lib.agent_settings import resolve_project_root
+
 PACKAGE_NAME = "@event4u/agent-config"
 
 
+def _project_root() -> Path:
+    """Resolve the consumer project root via the Phase-3 helper.
+
+    Honors ``AGENT_CONFIG_PROJECT_ROOT`` and the Step-7 anchor walk so
+    ``agent-config versions`` invoked from a subdir reads the correct
+    ``.agent-settings.yml`` / ``package.json``.
+    """
+    root, _ = resolve_project_root(None)
+    return root
+
+
 def _local_package_version() -> str:
     """Return ``version`` from the local ``package.json``, or ``""`` if absent."""
     candidates = [
         Path(__file__).resolve().parents[2] / "package.json",
-        Path.cwd() / "package.json",
+        _project_root() / "package.json",
     ]
     for p in candidates:
         if p.exists():
@@ -38,7 +51,7 @@ def _local_package_version() -> str:
 
 def _pinned_version() -> str:
     """Return the ``agent_config_version`` pin from ``.agent-settings.yml``."""
-    settings = Path.cwd() / ".agent-settings.yml"
+    settings = _project_root() / ".agent-settings.yml"
     if not settings.exists():
         return ""
     try: