@event4u/agent-config 6.1.0 → 7.0.1

package/src/scripts/_cli/cmd_update.py

@@ -1,279 +0,0 @@
-"""``agent-config update`` — explicit, opt-in update of the version pin.
-
-Phase 3 of road-to-portable-runtime-and-update-check (P3.1). The
-command is the only user-driven path that flips
-``agent_config_version`` in ``.agent-settings.yml``; the daily banner
-(P2) never writes settings files.
-
-Flags:
-
-* ``--check`` — print the available latest version + return; no write.
-* ``--to <version>`` — pin to an exact version (registry-existence
-  checked). Downgrades are allowed; the pin is a project decision.
-* (no flag) — pin to the registry's ``latest`` tag.
-
-Write target: the **deepest** ``.agent-settings.yml`` in the project
-cascade that already carries the ``agent_config_version`` key. When no
-file carries it, the repo-root file is created/edited. Comments and
-key ordering are preserved by line-based substitution.
-
-The npx cache is warmed via
-``npx --yes @event4u/agent-config@<new> --version`` so the next
-invocation is offline-fast. The P2 state file is refreshed in
-lockstep — the new ``installed_version`` is recorded so the banner
-does not yell about the old pin.
-"""
-from __future__ import annotations
-
-import argparse
-import json
-import os
-import re
-import subprocess
-import sys
-import urllib.error
-import urllib.request
-from datetime import datetime, timezone
-from pathlib import Path
-from typing import Optional
-
-from scripts._lib import installed_lock, update_check
-from scripts._lib.agent_settings import (
-    DEFAULT_PROJECT_FILE,
-    _resolve_cascade_paths,
-    find_project_root,
-    resolve_project_root,
-)
-
-PACKAGE_NAME = "@event4u/agent-config"
-PIN_KEY = "agent_config_version"
-REGISTRY_VERSION_URL = f"https://registry.npmjs.org/{PACKAGE_NAME}/{{version}}"
-PIN_LINE_RE = re.compile(r"^(\s*agent_config_version\s*:\s*)(.*)$")
-
-
-def _normalize(version: str) -> str:
-    return version.strip().lstrip("v")
-
-
-def _registry_has_version(version: str, *, timeout: float = 1.0) -> bool:
-    url = REGISTRY_VERSION_URL.format(version=_normalize(version))
-    try:
-        req = urllib.request.Request(url, headers={"Accept": "application/json"})
-        with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310
-            return resp.status == 200
-    except (urllib.error.URLError, TimeoutError, OSError):
-        return False
-
-
-def _find_pin_file(cwd: Path) -> Path:
-    """Return the deepest cascade file that carries the pin, else repo root."""
-    cascade = _resolve_cascade_paths(cwd, None)
-    for path in reversed(cascade):
-        if path.is_file() and _read_pin_line(path) is not None:
-            return path
-    # No file carries it — pick the repo-root cascade entry (shallowest).
-    if cascade:
-        return cascade[0]
-    return cwd / DEFAULT_PROJECT_FILE
-
-
-def _read_pin_line(path: Path) -> Optional[int]:
-    try:
-        with path.open("r", encoding="utf-8") as fh:
-            for idx, line in enumerate(fh):
-                if PIN_LINE_RE.match(line):
-                    return idx
-    except OSError:
-        return None
-    return None
-
-
-def _write_pin(path: Path, new_version: str) -> bool:
-    """Rewrite the pin in ``path``; return ``True`` if the file changed."""
-    target = f'agent_config_version: "{_normalize(new_version)}"\n'
-    try:
-        lines = path.read_text(encoding="utf-8").splitlines(keepends=True)
-    except FileNotFoundError:
-        path.parent.mkdir(parents=True, exist_ok=True)
-        path.write_text(target, encoding="utf-8")
-        return True
-    for idx, line in enumerate(lines):
-        if PIN_LINE_RE.match(line):
-            if lines[idx] == target:
-                return False
-            lines[idx] = target
-            path.write_text("".join(lines), encoding="utf-8")
-            return True
-    # File exists but has no pin line — append at end.
-    if lines and not lines[-1].endswith("\n"):
-        lines.append("\n")
-    lines.append(target)
-    path.write_text("".join(lines), encoding="utf-8")
-    return True
-
-
-def _warm_npx_cache(version: str, *, runner=subprocess.run) -> None:
-    try:
-        runner(
-            ["npx", "--yes", f"{PACKAGE_NAME}@{_normalize(version)}", "--version"],
-            stdout=subprocess.DEVNULL,
-            stderr=subprocess.DEVNULL,
-            timeout=120,
-            check=False,
-        )
-    except (OSError, subprocess.TimeoutExpired):
-        pass
-
-
-def _refresh_state(installed: str, latest: str, state_path: Path) -> None:
-    state = update_check._read_state(state_path)
-    payload = {
-        "last_check_utc": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
-        "last_seen_version": latest,
-        "installed_version": installed,
-    }
-    state.update(payload)
-    try:
-        update_check._write_state(state_path, state)
-    except OSError:
-        pass
-
-
-def main(
-    argv: Optional[list[str]] = None,
-    *,
-    cwd: Optional[Path] = None,
-    installed_version: Optional[str] = None,
-    fetcher=update_check.fetch_latest_from_npm,
-    version_checker=_registry_has_version,
-    cache_warmer=_warm_npx_cache,
-    state_path: Optional[Path] = None,
-    out=sys.stdout,
-    err=sys.stderr,
-) -> int:
-    """Entry point. ``scripts/agent-config`` dispatches here."""
-    parser = argparse.ArgumentParser(
-        prog="agent-config update",
-        description="Update the agent_config_version pin in .agent-settings.yml.",
-    )
-    parser.add_argument("--check", action="store_true",
-                        help="Print the latest available version and exit. No file is written.")
-    parser.add_argument("--to", metavar="VERSION",
-                        help="Pin to an explicit version (registry-existence checked).")
-    parser.add_argument("--offline", action="store_true",
-                        help="Skip the npm registry check; requires --to <version> "
-                             "(without --to there is no source for 'latest').")
-    args = parser.parse_args(argv)
-
-    # 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
-
-    # AGENT_CONFIG_OFFLINE=1 (set by `install.py --offline`) is honored
-    # as an env-level kill-switch. Mirrors cmd_versions.py.
-    offline = args.offline or os.environ.get("AGENT_CONFIG_OFFLINE") == "1"
-
-    if offline and not args.to:
-        print(
-            "❌  agent-config: --offline requires --to <version> "
-            "(no registry, no 'latest' to fetch).",
-            file=err,
-        )
-        return 1
-
-    if args.to:
-        target = _normalize(args.to)
-        if offline:
-            # Trust the caller; air-gapped env can't reach the registry.
-            latest = target
-        elif not version_checker(target):
-            print(
-                f"❌  agent-config: version {target} not found on the npm registry.",
-                file=err,
-            )
-            return 1
-        else:
-            latest = target
-    else:
-        latest = fetcher()
-        if not latest:
-            print(
-                "❌  agent-config: failed to fetch latest version from the npm registry.",
-                file=err,
-            )
-            return 1
-        latest = _normalize(latest)
-
-    if args.check:
-        if update_check._is_newer(latest, installed_version):
-            print(f"agent-config {latest} available (you have {installed_version}).", file=out)
-            print(f"Update: npx {PACKAGE_NAME} update", file=out)
-        else:
-            print(f"agent-config is up to date ({installed_version}).", file=out)
-        return 0
-
-    pin_file = _find_pin_file(cwd)
-    changed = _write_pin(pin_file, latest)
-    try:
-        rel = pin_file.relative_to(cwd)
-    except ValueError:
-        rel = pin_file
-
-    if changed:
-        print(f"✅  Pinned {PACKAGE_NAME} to {latest} in {rel}.", file=out)
-    else:
-        print(f"ℹ️  {rel} already pins to {latest}.", file=out)
-
-    # `npx --yes <pkg>@<v> --version` would hit the registry; skip it
-    # offline so the air-gap guarantee holds end-to-end.
-    if not offline:
-        cache_warmer(latest)
-    _refresh_state(latest, latest, state_path)
-    _refresh_global_lockfile(latest, out=out)
-    return 0
-
-
-def _refresh_global_lockfile(version: str, *, out=sys.stdout) -> None:
-    """Update the global ``installed.lock`` if it exists.
-
-    Resolution prefers ``~/.event4u/agent-config/installed.lock`` and
-    falls back to the legacy ``~/.config/agent-config/installed.lock``.
-
-    Phase 1.6 — the lockfile is only present when the user has run a
-    global install; we never create one here, but we keep it in lockstep
-    when ``update`` flips the pin. Atomic write goes through
-    ``installed_lock.write_lockfile``.
-    """
-    read_path = installed_lock.lockfile_path()
-    write_path = installed_lock.lockfile_write_path()
-    existing = installed_lock.read_lockfile(path=read_path)
-    if existing is None:
-        return
-    recorded = existing.get("agent_config_version")
-    tools = list(existing.get("tools", []))
-    if recorded == version and read_path == write_path:
-        print(f"ℹ️  {write_path} already records {version}.", file=out)
-        return
-    installed_lock.write_lockfile(version, tools, path=write_path)
-    print(f"✅  Refreshed global lockfile at {write_path}.", file=out)
-
-
-def _detect_installed_version() -> str:
-    """Read ``version`` from the package's own ``package.json``."""
-    pkg_json = Path(__file__).resolve().parents[3] / "package.json"
-    try:
-        data = json.loads(pkg_json.read_text(encoding="utf-8"))
-        version = data.get("version")
-        if isinstance(version, str) and version.strip():
-            return version.strip()
-    except (OSError, ValueError, json.JSONDecodeError):
-        pass
-    return "0.0.0"
-
-
-if __name__ == "__main__":  # pragma: no cover
-    sys.exit(main())
-

package/src/scripts/_cli/cmd_upgrade.py

@@ -1,172 +0,0 @@
-"""``agent-config upgrade`` — fetch + install the latest global binary + refresh.
-
-Distinct from ``agent-config update`` (which only flips the
-``agent_config_version`` pin in ``.agent-settings.yml`` — a project
-decision, see :mod:`scripts._cli.cmd_update`). ``upgrade`` is the
-**global** self-update path mandated by ADR-020's "no per-repo bump"
-goal: it installs the latest published package globally and re-runs the
-global install so new skills / rules / hooks reach every consumer at
-once.
-
-Side effects, in order:
-
-1. ``npm install -g @event4u/agent-config@latest`` — refresh the global
-   binary on PATH (the binary the Claude plugin hook resolves).
-2. ``agent-config global`` (→ ``install.py --global``) — refresh the
-   global root (``~/.event4u/agent-config/``) + regenerate plugin hooks.
-3. If run from inside a consumer project that already has a
-   ``./agent-config`` wrapper, re-stamp that wrapper from the canonical
-   template so an older, fallback-less copy cannot linger and break the
-   hooks. Skipped in the source repo and never creates a wrapper.
-
-The **Claude marketplace plugin** updates on Claude Code's own cadence,
-independent of npm; ``upgrade`` cannot drive it. ``agent-config doctor``
-surfaces binary↔plugin drift so the user knows when to update the plugin
-from the marketplace.
-
-Flags:
-
-* ``--check`` — report installed vs latest; install nothing. Exit 0.
-* ``--dry-run`` — print the exact commands that would run; execute none.
-* (no flag) — perform the upgrade.
-
-Exit codes: ``0`` success / already-latest / check / dry-run · ``1`` a
-step failed.
-"""
-from __future__ import annotations
-
-import argparse
-import subprocess
-import sys
-from pathlib import Path
-from typing import Callable, Optional
-
-from scripts._lib import installed_lock, update_check
-
-PACKAGE_NAME = "@event4u/agent-config"
-
-# A runner is injected in tests so the global-mutating commands are never
-# executed in CI / sandbox. Returns the subprocess return code.
-Runner = Callable[[list[str]], int]
-
-
-def _default_runner(cmd: list[str]) -> int:
-    try:
-        return subprocess.run(cmd, check=False).returncode
-    except OSError as exc:  # npm / bash missing
-        sys.stderr.write(f"agent-config upgrade: cannot run {cmd[0]}: {exc}\n")
-        return 1
-
-
-def _installed_version() -> str:
-    lock = installed_lock.read_lockfile()
-    if isinstance(lock, dict):
-        v = lock.get("agent_config_version")
-        if isinstance(v, str) and v:
-            return v.strip().lstrip("v")
-    return ""
-
-
-def _agent_config_bin() -> str:
-    """The global wrapper the second step invokes. Prefer the binary on
-    PATH; fall back to the package-local wrapper so a maintainer dev-loop
-    (no global install yet) still refreshes."""
-    from shutil import which
-    return which("agent-config") or str(
-        Path(__file__).resolve().parents[3] / "agent-config")
-
-
-def _maybe_refresh_project_wrapper(project_root: Path, out, err) -> None:
-    """Re-stamp the project-local ``./agent-config`` wrapper after a global
-    upgrade — but only when the upgrade was run from inside a consumer
-    project that *already* has a wrapper. Never creates one (that is an
-    install action, out of scope), never touches the source repo.
-
-    This closes the gap where ``upgrade`` refreshed the global binary while
-    an older, fallback-less project wrapper kept breaking the Claude hooks.
-    """
-    from scripts._lib import cli_wrapper
-    from scripts._cli.cmd_refresh import _is_source_repo
-
-    if _is_source_repo(project_root):
-        return
-    if not (project_root / "agent-config").is_file():
-        return  # not a consumer project root (or never installed) — leave it
-    if not cli_wrapper.needs_refresh(project_root):
-        return
-    wrapper = cli_wrapper.install_cli_wrapper(project_root)
-    if wrapper is not None:
-        print(f"✅  refreshed stale project wrapper: {wrapper}", file=out)
-
-
-def main(
-    argv: Optional[list[str]] = None,
-    *,
-    runner: Runner = _default_runner,
-    fetcher=update_check.fetch_latest_from_npm,
-    installed: Optional[str] = None,
-    project_root: Optional[Path] = None,
-    out=sys.stdout,
-    err=sys.stderr,
-) -> int:
-    parser = argparse.ArgumentParser(
-        prog="agent-config upgrade",
-        description="Install the latest @event4u/agent-config globally and "
-                    "refresh the global install.",
-    )
-    parser.add_argument("--check", action="store_true",
-                        help="Report installed vs latest; install nothing.")
-    parser.add_argument("--dry-run", action="store_true",
-                        help="Print the commands that would run; execute none.")
-    args = parser.parse_args(argv)
-
-    installed = installed if installed is not None else _installed_version()
-    latest = fetcher() or ""
-
-    if args.check:
-        if not latest:
-            print("agent-config upgrade: latest version unavailable "
-                  "(registry unreachable).", file=err)
-            return 0
-        if installed and not installed_lock_is_newer(latest, installed):
-            print(f"✅  agent-config is up to date ({installed}).", file=out)
-        else:
-            print(f"ℹ️  agent-config {latest} available "
-                  f"(installed: {installed or 'unknown'}). Run "
-                  f"`agent-config upgrade`.", file=out)
-        return 0
-
-    target = f"{PACKAGE_NAME}@latest"
-    steps = [
-        ["npm", "install", "-g", target],
-        [_agent_config_bin(), "global"],
-    ]
-
-    if args.dry_run:
-        print("agent-config upgrade — dry run, would execute:", file=out)
-        for cmd in steps:
-            print("  " + " ".join(cmd), file=out)
-        return 0
-
-    for cmd in steps:
-        print("→ " + " ".join(cmd), file=out)
-        rc = runner(cmd)
-        if rc != 0:
-            print(f"❌  agent-config upgrade: step failed (exit {rc}): "
-                  f"{' '.join(cmd)}", file=err)
-            return 1
-
-    _maybe_refresh_project_wrapper(project_root or Path.cwd(), out, err)
-
-    print("✅  agent-config upgraded. Run `agent-config doctor` to verify "
-          "PATH + plugin parity.", file=out)
-    return 0
-
-
-def installed_lock_is_newer(latest: str, installed: str) -> bool:
-    """Thin wrapper around update_check._is_newer for one import site."""
-    return update_check._is_newer(latest, installed)
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

package/src/scripts/_cli/cmd_validate.py

@@ -1,177 +0,0 @@
-"""``agent-config validate`` — drift detection for the installed-tools manifest.
-
-Phase 3.4 of road-to-global-first-install.md (ADR-008). Read-only check —
-never edits the manifest, never re-runs the installer. Exits non-zero if any
-drift is found so CI can gate on it. Surfaces three drift kinds documented in
-ADR-008 §Lifecycle:
-
-1. **marker_missing**     — recorded ``bridge_marker`` path does not exist.
-2. **scope_divergence**   — recorded scope is ``project`` but the marker only
-   exists at the user-scope anchor (or vice versa); the manifest is lying
-   about where the tool actually lives.
-3. **version_drift**      — manifest's ``agent_config_version`` no longer
-   matches the package's currently-installed version (single repo-level
-   check, surfaced once not per-tool).
-"""
-from __future__ import annotations
-
-import argparse
-import os
-import sys
-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
-
-
-def _resolve_marker(project_root: Path, bridge_marker: str, scope: str) -> Path:
-    if scope == "global":
-        return Path(bridge_marker).expanduser()
-    candidate = Path(bridge_marker)
-    return candidate if candidate.is_absolute() else (project_root / candidate)
-
-
-def _counterpart_path(project_root: Path, tool_id: str, scope: str) -> Path | None:
-    """Return the *other* scope's canonical marker path, or None if unknown."""
-    if scope == "project":
-        anchor = USER_SCOPE_PATHS.get(tool_id)
-        return Path(anchor).expanduser() if anchor else None
-    rel = PROJECT_BRIDGE_MARKERS.get(tool_id)
-    return (project_root / rel) if rel else None
-
-
-def _check_entry(project_root: Path, entry: dict) -> list[dict]:
-    name = str(entry.get("name", "")).strip()
-    scope = str(entry.get("scope", "")).strip()
-    bridge_marker = str(entry.get("bridge_marker", "")).strip()
-    issues: list[dict] = []
-    if not name or scope not in ("project", "global") or not bridge_marker:
-        issues.append({
-            "kind": "manifest_corrupt",
-            "name": name or "<unknown>",
-            "detail": f"entry missing required fields (scope={scope!r}, marker={bridge_marker!r})",
-        })
-        return issues
-    target = _resolve_marker(project_root, bridge_marker, scope)
-    if not target.exists():
-        counterpart = _counterpart_path(project_root, name, scope)
-        if counterpart is not None and counterpart.exists():
-            other_scope = "global" if scope == "project" else "project"
-            issues.append({
-                "kind": "scope_divergence",
-                "name": name,
-                "detail": (
-                    f"recorded scope={scope} ({target}) is missing, but "
-                    f"counterpart at scope={other_scope} ({counterpart}) exists"
-                ),
-            })
-        else:
-            issues.append({
-                "kind": "marker_missing",
-                "name": name,
-                "detail": f"bridge_marker not found: {target}",
-            })
-    return issues
-
-
-def _version_drift(manifest_version: str, current_version: str) -> dict | None:
-    if not manifest_version or not current_version:
-        return None
-    if manifest_version != current_version:
-        return {
-            "kind": "version_drift",
-            "name": "<manifest>",
-            "detail": (
-                f"manifest recorded agent_config_version={manifest_version}; "
-                f"currently installed package is {current_version}"
-            ),
-        }
-    return None
-
-
-def _parse(argv: list[str]) -> argparse.Namespace:
-    parser = argparse.ArgumentParser(
-        prog="agent-config validate",
-        description=(
-            "Read-only drift detection for agents/installed-tools.lock. "
-            "Exits 1 if any drift is found."
-        ),
-    )
-    parser.add_argument("--project", default=None, help="Override project root.")
-    parser.add_argument(
-        "--quiet", action="store_true", help="Suppress non-essential output.",
-    )
-    parser.add_argument(
-        "--skip-version-check",
-        action="store_true",
-        help="Skip the manifest-vs-package version drift check.",
-    )
-    return parser.parse_args(argv)
-
-
-def _emit(quiet: bool, msg: str) -> None:
-    if not quiet:
-        print(msg)
-
-
-def _format(issue: dict) -> str:
-    return f"  ❌  [{issue['kind']}] {issue['name']}: {issue['detail']}"
-
-
-def main(argv: list[str]) -> int:
-    opts = _parse(argv)
-    # 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)
-
-    if data is None:
-        _emit(opts.quiet, f"❌  No manifest found at {manifest}")
-        _emit(opts.quiet, "    Run `./agent-config init --tools=<id>` to create one.")
-        _emit(opts.quiet, "    Diagnose: `./agent-config doctor --check manifest-integrity`")
-        return 1
-
-    entries = list(data.get("tools") or [])
-    issues: list[dict] = []
-    for entry in entries:
-        issues.extend(_check_entry(project_root, entry))
-
-    if not opts.skip_version_check:
-        manifest_version = str(data.get("agent_config_version", "")).strip()
-        current_version = installed_lock.current_package_version()
-        drift = _version_drift(manifest_version, current_version)
-        if drift is not None:
-            issues.append(drift)
-
-    _emit(opts.quiet, f"Manifest:  {manifest}")
-    _emit(opts.quiet, f"Tools:     {len(entries)} entries")
-
-    if not issues:
-        _emit(opts.quiet, "✅  No drift detected.")
-        return 0
-
-    _emit(opts.quiet, f"Drift:     {len(issues)} issue(s)")
-    for issue in issues:
-        _emit(opts.quiet, _format(issue))
-    _emit(opts.quiet, "")
-    _emit(opts.quiet, "Run `./agent-config sync` to replay missing bridges, or")
-    _emit(opts.quiet, "`./agent-config init --tools=<id> --force` to refresh the manifest.")
-    # Deeplink: route per-kind to the matching `doctor` check so users can
-    # copy-paste even though `doctor` is Tier-1 and absent from --help.
-    kinds = {issue["kind"] for issue in issues}
-    if "version_drift" in kinds:
-        _emit(opts.quiet, "Diagnose:  `./agent-config doctor --check lockfile-freshness`")
-    if kinds & {"marker_missing", "scope_divergence"}:
-        _emit(opts.quiet, "Diagnose:  `./agent-config doctor --check bridge-drift`")
-    if "manifest_corrupt" in kinds:
-        _emit(opts.quiet, "Diagnose:  `./agent-config doctor --check manifest-integrity`")
-    return 1
-
-
-if __name__ == "__main__":
-    sys.exit(main(sys.argv[1:]))