@event4u/agent-config 2.0.0 → 2.2.0

package/scripts/_cli/cmd_validate.py

@@ -0,0 +1,164 @@
+"""``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.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)
+    project_root = Path(
+        opts.project or os.environ.get("PROJECT_ROOT") or os.getcwd()
+    ).resolve()
+    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.")
+        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.")
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/scripts/_lib/installed_lock.py

@@ -0,0 +1,160 @@
+"""Global-install lockfile at ``~/.config/agent-config/installed.lock``.
+
+Phase 1.6 of road-to-global-first-install (ADR-007 D5). Records the
+package version that performed the most recent user-scope install plus
+the tools that were scaffolded. ``init --global`` reads this file: on
+version mismatch the install refuses unless ``--force`` is passed; the
+``update`` subcommand refreshes the entry in lockstep with the pin
+flip in ``.agent-settings.yml``.
+
+The schema is intentionally minimal YAML so the module can read and
+write without depending on ``pyyaml``. Atomic writes go through
+``tempfile + os.replace`` per ADR-007 risk-mitigation row.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+LOCKFILE_ENV = "AGENT_CONFIG_INSTALLED_LOCK"
+DEFAULT_LOCKFILE = Path.home() / ".config" / "agent-config" / "installed.lock"
+SCHEMA_VERSION = 1
+
+_VERSION_RE = re.compile(r'^\s*agent_config_version\s*:\s*"?([^"\s]+)"?\s*$')
+_SCHEMA_RE = re.compile(r"^\s*schema_version\s*:\s*(\d+)\s*$")
+_INSTALLED_AT_RE = re.compile(r'^\s*installed_at\s*:\s*"?([^"\s]+)"?\s*$')
+_TOOL_RE = re.compile(r"^\s*-\s*([A-Za-z0-9_\-.]+)\s*$")
+
+
+def lockfile_path(env: Optional[dict] = None) -> Path:
+    """Return the active lockfile path, honoring the env override."""
+    env = env if env is not None else os.environ
+    override = env.get(LOCKFILE_ENV)
+    if override:
+        return Path(override).expanduser()
+    return DEFAULT_LOCKFILE
+
+
+def read_lockfile(path: Optional[Path] = None) -> Optional[dict]:
+    """Parse ``path`` (or the default) into a dict; return ``None`` if absent.
+
+    Tolerates partial / malformed files: missing keys yield missing dict
+    entries rather than raising, so a hand-edited corrupt file does not
+    brick ``init``.
+    """
+    target = path or lockfile_path()
+    try:
+        text = target.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return None
+    except OSError:
+        return None
+
+    data: dict = {"tools": []}
+    in_tools = False
+    for raw_line in text.splitlines():
+        if _SCHEMA_RE.match(raw_line):
+            data["schema_version"] = int(_SCHEMA_RE.match(raw_line).group(1))
+            in_tools = False
+            continue
+        if _VERSION_RE.match(raw_line):
+            data["agent_config_version"] = _VERSION_RE.match(raw_line).group(1)
+            in_tools = False
+            continue
+        if _INSTALLED_AT_RE.match(raw_line):
+            data["installed_at"] = _INSTALLED_AT_RE.match(raw_line).group(1)
+            in_tools = False
+            continue
+        if raw_line.strip().startswith("tools:"):
+            in_tools = True
+            continue
+        if in_tools:
+            m = _TOOL_RE.match(raw_line)
+            if m:
+                data["tools"].append(m.group(1))
+            elif raw_line.strip() and not raw_line.startswith((" ", "\t", "-")):
+                in_tools = False
+    return data
+
+
+def _render(version: str, tools: list[str], installed_at: str) -> str:
+    lines = [
+        f"schema_version: {SCHEMA_VERSION}",
+        f'agent_config_version: "{version}"',
+        f'installed_at: "{installed_at}"',
+        "tools:",
+    ]
+    for tool in tools:
+        lines.append(f"  - {tool}")
+    return "\n".join(lines) + "\n"
+
+
+def write_lockfile(
+    version: str,
+    tools: list[str],
+    *,
+    path: Optional[Path] = None,
+    now: Optional[datetime] = None,
+) -> Path:
+    """Atomically write the lockfile; return the path written."""
+    target = path or lockfile_path()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    stamp = (now or datetime.now(timezone.utc)).strftime("%Y-%m-%dT%H:%M:%SZ")
+    rendered = _render(version, sorted(set(tools)), stamp)
+    # Atomic write: tempfile in the same dir + os.replace. The same-dir
+    # constraint keeps the rename atomic across all POSIX filesystems
+    # and Windows when the file already exists.
+    fd, tmp_name = tempfile.mkstemp(
+        prefix=".installed.lock.", dir=str(target.parent), text=False
+    )
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            fh.write(rendered)
+        os.replace(tmp_name, target)
+    except Exception:
+        try:
+            os.unlink(tmp_name)
+        except OSError:
+            pass
+        raise
+    return target
+
+
+def check_version(
+    installed_version: str,
+    *,
+    path: Optional[Path] = None,
+) -> tuple[bool, Optional[str]]:
+    """Compare ``installed_version`` against the lockfile's recorded version.
+
+    Returns ``(ok, recorded_version_or_none)``:
+      * ``(True, None)``  — no lockfile yet; ``init`` may proceed.
+      * ``(True, vX)``    — matches; ``init`` may proceed.
+      * ``(False, vY)``   — mismatch; caller must refuse without ``--force``.
+    """
+    existing = read_lockfile(path=path)
+    if existing is None:
+        return True, None
+    recorded = existing.get("agent_config_version")
+    if not recorded:
+        return True, None
+    return (recorded == installed_version, recorded)
+
+
+def current_package_version(repo_root: Optional[Path] = None) -> str:
+    """Read ``version`` from the package's own ``package.json``."""
+    if repo_root is None:
+        repo_root = Path(__file__).resolve().parents[2]
+    try:
+        data = json.loads((repo_root / "package.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"

package/scripts/_lib/installed_tools.py

@@ -0,0 +1,237 @@
+"""Project-scope installed-tools manifest at ``agents/installed-tools.lock``.
+
+Phase 3 of road-to-global-first-install (ADR-008). Committed
+bill-of-materials for AI tooling a project depends on. Sibling to the
+global lockfile (``installed_lock.py``) but architecturally distinct:
+
+- ``installed_lock.py`` lives in ``~/.config/agent-config/`` and tracks
+  the user-scope environment (a single ``agent_config_version`` and a
+  flat ``tools[]`` list).
+- ``installed_tools.py`` lives in ``agents/`` and tracks **per-project**
+  tooling with richer per-entry metadata (``scope``, ``bridge_marker``,
+  ``installed_at``).
+
+The file is machine-managed: ``init`` appends / merges; ``sync`` replays;
+``validate`` drift-checks. Schema is YAML; ``pyyaml`` is used when
+available, otherwise a constrained manual parser handles the documented
+schema (no anchors, no flow style, single-level nesting under
+``tools``).
+"""
+from __future__ import annotations
+
+import os
+import re
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+MANIFEST_ENV = "AGENT_CONFIG_INSTALLED_TOOLS"
+DEFAULT_MANIFEST_RELATIVE = Path("agents") / "installed-tools.lock"
+SCHEMA_VERSION = 1
+
+_VALID_SCOPES = ("global", "project")
+
+
+def manifest_path(project_root: Path, env: Optional[dict] = None) -> Path:
+    """Return the active manifest path, honoring the env override."""
+    env = env if env is not None else os.environ
+    override = env.get(MANIFEST_ENV)
+    if override:
+        return Path(override).expanduser()
+    return project_root / DEFAULT_MANIFEST_RELATIVE
+
+
+# ---------------------------------------------------------------------------
+# Read
+# ---------------------------------------------------------------------------
+
+_TOP_KEY_RE = re.compile(r'^([A-Za-z_][A-Za-z0-9_]*)\s*:\s*"?([^"\n]*?)"?\s*$')
+_LIST_DASH_RE = re.compile(r"^\s*-\s*(.+?)\s*$")
+_INDENT_KEY_RE = re.compile(r'^\s+([A-Za-z_][A-Za-z0-9_]*)\s*:\s*"?([^"\n]*?)"?\s*$')
+
+
+def read_manifest(path: Path) -> Optional[dict[str, Any]]:
+    """Parse the manifest into a dict; return ``None`` if absent.
+
+    Tolerates partial / malformed files: missing keys yield missing dict
+    entries rather than raising, so a corrupted file does not brick
+    ``init``.
+    """
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (FileNotFoundError, OSError):
+        return None
+    try:
+        import yaml  # type: ignore[import-untyped]
+        data = yaml.safe_load(text) or {}
+        if isinstance(data, dict):
+            data.setdefault("tools", [])
+            return data
+    except ImportError:
+        pass
+    except Exception:
+        # Fall through to the manual parser; corrupt YAML is recoverable
+        # from our strict schema as long as the top-level shape holds.
+        pass
+    return _parse_manual(text)
+
+
+def _parse_manual(text: str) -> dict[str, Any]:
+    data: dict[str, Any] = {"tools": []}
+    in_tools = False
+    current: Optional[dict[str, Any]] = None
+    for raw in text.splitlines():
+        stripped = raw.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        if stripped == "tools:":
+            in_tools = True
+            current = None
+            continue
+        if in_tools:
+            m = _LIST_DASH_RE.match(raw)
+            if m:
+                first = m.group(1)
+                current = {}
+                data["tools"].append(current)
+                # Could be inline like `- name: foo` — handle that.
+                inline = _TOP_KEY_RE.match(first)
+                if inline:
+                    current[inline.group(1)] = inline.group(2)
+                continue
+            mk = _INDENT_KEY_RE.match(raw)
+            if mk and current is not None:
+                current[mk.group(1)] = mk.group(2)
+                continue
+        m_top = _TOP_KEY_RE.match(raw)
+        if m_top:
+            key, value = m_top.group(1), m_top.group(2)
+            if key == "schema_version":
+                try:
+                    data[key] = int(value)
+                except ValueError:
+                    data[key] = value
+            else:
+                data[key] = value
+            in_tools = False
+            current = None
+    return data
+
+
+# ---------------------------------------------------------------------------
+# Write
+# ---------------------------------------------------------------------------
+
+
+def _render(
+    version: str,
+    tools: list[dict[str, Any]],
+) -> str:
+    lines = [
+        f"schema_version: {SCHEMA_VERSION}",
+        f'agent_config_version: "{version}"',
+        "tools:",
+    ]
+    for tool in tools:
+        lines.append(f"  - name: {tool['name']}")
+        lines.append(f"    scope: {tool['scope']}")
+        lines.append(f"    bridge_marker: {tool['bridge_marker']}")
+        lines.append(f'    installed_at: "{tool["installed_at"]}"')
+    return "\n".join(lines) + "\n"
+
+
+def write_manifest(
+    path: Path,
+    version: str,
+    tools: list[dict[str, Any]],
+) -> Path:
+    """Atomically write the manifest; return the path written."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    rendered = _render(version, tools)
+    fd, tmp_name = tempfile.mkstemp(
+        prefix=".installed-tools.lock.", dir=str(path.parent), text=False
+    )
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            fh.write(rendered)
+        os.replace(tmp_name, path)
+    except Exception:
+        try:
+            os.unlink(tmp_name)
+        except OSError:
+            pass
+        raise
+    return path
+
+
+# ---------------------------------------------------------------------------
+# Mutation helpers
+# ---------------------------------------------------------------------------
+
+
+class ScopeMismatchError(RuntimeError):
+    """Raised when an existing manifest entry conflicts with the new scope."""
+
+    def __init__(self, name: str, recorded_scope: str, new_scope: str):
+        super().__init__(
+            f"tool {name!r} is committed as scope={recorded_scope}; "
+            f"refusing to change it to scope={new_scope} without --force"
+        )
+        self.name = name
+        self.recorded_scope = recorded_scope
+        self.new_scope = new_scope
+
+
+def upsert_tool(
+    existing: list[dict[str, Any]],
+    *,
+    name: str,
+    scope: str,
+    bridge_marker: str,
+    installed_at: Optional[str] = None,
+    force: bool = False,
+) -> list[dict[str, Any]]:
+    """Return a new tools list with ``name`` added or refreshed.
+
+    Idempotency rules from ADR-008 §Lifecycle:
+    * Same name, same scope → no-op (timestamp preserved).
+    * Same name, different scope → raise ``ScopeMismatchError`` unless
+      ``force=True``, in which case the entry is rewritten.
+    * New name → appended in install order (not alphabetised).
+    """
+    if scope not in _VALID_SCOPES:
+        raise ValueError(f"scope must be one of {_VALID_SCOPES}: {scope!r}")
+    stamp = installed_at or _today()
+    result: list[dict[str, Any]] = []
+    found = False
+    for entry in existing:
+        if entry.get("name") == name:
+            found = True
+            recorded = str(entry.get("scope", ""))
+            if recorded == scope:
+                # Idempotent no-op — preserve original installed_at.
+                result.append(entry)
+                continue
+            if not force:
+                raise ScopeMismatchError(name, recorded, scope)
+            result.append({
+                "name": name,
+                "scope": scope,
+                "bridge_marker": bridge_marker,
+                "installed_at": stamp,
+            })
+            continue
+        result.append(entry)
+    if not found:
+        result.append({
+            "name": name,
+            "scope": scope,
+            "bridge_marker": bridge_marker,
+            "installed_at": stamp,
+        })
+    return result
+
+
+def _today() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%d")

package/scripts/agent-config

@@ -98,6 +98,19 @@ Commands:
                              Flags: --check (read-only) | --to <version> (explicit pin)
   migrate                    One-shot migration off legacy composer / npm install paths
                              Flags: --dry-run (detect only)
+  global                     Install to user-scope paths (~/.claude/, ~/.cursor/, …)
+                             Forwards to `scripts/install --global` (ADR-007).
+                             Flags: --tools=<list> | --ai=<list> | --yes | --force
+  export                     Eject a tool's canonical content into a chosen path
+                             (real file, no symlink). Idempotent; --force overrides
+                             content drift. See `./agent-config export --list`.
+                             Flags: --tool=<id> | --output=<path> | --force | --list
+  sync                       Replay agents/installed-tools.lock — re-installs any
+                             tool whose bridge marker is missing locally (ADR-008).
+                             Flags: --dry-run | --force | --project=<path>
+  validate                   Read-only drift detection on the manifest
+                             (marker missing, scope divergence, version drift).
+                             Exits 1 on drift. Flags: --quiet | --skip-version-check
   help                       Show this help
   --version, -V              Print package version
 
@@ -126,6 +139,14 @@ Examples:
   ./agent-config council:estimate prompt.txt
   ./agent-config council:run prompt.txt --output agents/council-sessions/out.json --confirm
   ./agent-config council:render agents/council-sessions/out.json
+  ./agent-config global --tools=claude-code --yes
+  ./agent-config global --ai=cursor,windsurf
+  ./agent-config export --list
+  ./agent-config export --tool=agents-md --output=AGENTS.md
+  ./agent-config export --tool=copilot-instructions --output=.github/copilot-instructions.md
+  ./agent-config sync --dry-run
+  ./agent-config sync
+  ./agent-config validate
 
 All commands operate on the CURRENT DIRECTORY (your project root).
 The CLI is strictly consumer-facing. Maintainer tasks live in Taskfile.yml.
@@ -524,6 +545,43 @@ cmd_migrate() {
   exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_migrate "$@"
 }
 
+# `agent-config global` — user-scope install entry point. Forwards to the
+# bash installer with `--global` set (ADR-007). Phase 1.2 of
+# road-to-global-first-install.md. The bash wrapper handles option parsing
+# and forwards to `scripts/install.py --global`, where `install_global()`
+# currently scaffolds the per-tool anchor paths from USER_SCOPE_PATHS.
+# Concrete writes land in Phase 1.5 (export) and Phase 1.6 (lockfile).
+cmd_global() {
+  local script
+  script="$(resolve_script "scripts/install")" || return 1
+  exec bash "$script" --global "$@"
+}
+
+# `agent-config export` — write a tool's canonical content into a
+# user-chosen path. ADR-007 D3 / Phase 1.5 of
+# road-to-global-first-install.md. Replaces the rejected symlink-bridge.
+# See scripts/_cli/cmd_export.py for the registry and idempotency logic.
+cmd_export() {
+  require_python3
+  exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_export "$@"
+}
+
+# `agent-config sync` — replay agents/installed-tools.lock (ADR-008
+# Phase 3.3). Re-installs any tool whose bridge marker is missing on
+# disk. Typical onboarding flow: clone → `./agent-config sync` → done.
+cmd_sync() {
+  require_python3
+  exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_sync "$@"
+}
+
+# `agent-config validate` — read-only drift detection (ADR-008 Phase 3.4).
+# Surfaces marker-missing, scope-divergence, and version-drift; exits 1 on
+# any drift. Never edits the manifest or re-runs the installer.
+cmd_validate() {
+  require_python3
+  exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_validate "$@"
+}
+
 main() {
   local cmd="${1-}"
   [[ $# -gt 0 ]] && shift || true
@@ -564,6 +622,10 @@ main() {
     council:render)          cmd_council render "$@" ;;
     update)                  cmd_update "$@" ;;
     migrate)                 cmd_migrate "$@" ;;
+    global)                  cmd_global "$@" ;;
+    export)                  cmd_export "$@" ;;
+    sync)                    cmd_sync "$@" ;;
+    validate)                cmd_validate "$@" ;;
     help|--help|-h|"")        usage ;;
     --version|-V)            print_version ;;
     *)