@event4u/agent-config 2.1.0 → 2.2.0

package/scripts/_cli/cmd_sync.py

@@ -0,0 +1,162 @@
+"""``agent-config sync`` — replay the installed-tools manifest (ADR-008).
+
+Phase 3.3 of road-to-global-first-install.md. Reads
+``agents/installed-tools.lock``, then re-runs the bridge install for every
+tool whose ``bridge_marker`` is missing on disk. Tools whose marker already
+exists are skipped — the typical clone-and-sync flow is therefore idempotent
+on the second invocation.
+
+Sync never edits the manifest itself; ``init`` is the only writer. Sync only
+calls the installer with ``--scope`` / ``--tools`` derived from the manifest
+entries, so the manifest is the single source of truth.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+from typing import Iterable
+
+from scripts._lib import installed_tools
+from scripts.install import main as install_main
+
+
+def _marker_exists(project_root: Path, bridge_marker: str, scope: str) -> bool:
+    if not bridge_marker:
+        return True  # substrate-only entries (rare); treat as present
+    if scope == "global":
+        target = Path(bridge_marker).expanduser()
+    else:
+        # Project-scope: relative to the project root unless absolute.
+        candidate = Path(bridge_marker)
+        target = candidate if candidate.is_absolute() else (project_root / candidate)
+    return target.exists()
+
+
+def _group_by_scope(
+    entries: Iterable[dict],
+    project_root: Path,
+) -> tuple[dict[str, list[str]], list[tuple[str, str]]]:
+    """Return ({scope: [tool_names]}, [(name, marker_path)]) for missing tools.
+
+    The second list is the human-readable summary of what will be replayed.
+    """
+    missing: dict[str, list[str]] = {"project": [], "global": []}
+    surfaced: list[tuple[str, str]] = []
+    for entry in entries:
+        name = str(entry.get("name", "")).strip()
+        scope = str(entry.get("scope", "")).strip()
+        bridge_marker = str(entry.get("bridge_marker", "")).strip()
+        if not name or scope not in ("project", "global"):
+            continue
+        if _marker_exists(project_root, bridge_marker, scope):
+            continue
+        missing[scope].append(name)
+        surfaced.append((name, bridge_marker))
+    return missing, surfaced
+
+
+def _run_install(scope: str, tools: list[str], project_root: Path, *, force: bool, dry_run: bool) -> int:
+    if not tools:
+        return 0
+    argv = [f"--scope={scope}", f"--tools={','.join(sorted(set(tools)))}"]
+    if scope == "project":
+        argv += [f"--project={project_root}", "--no-smoke"]
+    if force:
+        argv.append("--force")
+    if dry_run:
+        argv.append("--skip-bridges")
+    return install_main(argv)
+
+
+def _parse(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="agent-config sync",
+        description=(
+            "Replay agents/installed-tools.lock — re-installs any tool whose "
+            "bridge marker is missing locally. Idempotent."
+        ),
+    )
+    parser.add_argument(
+        "--project",
+        default=None,
+        help="Override the project root (defaults to PROJECT_ROOT or cwd).",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print the planned replay set without touching bridges.",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Forwarded to the installer (overwrites existing bridge files).",
+    )
+    parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Suppress non-essential output.",
+    )
+    return parser.parse_args(argv)
+
+
+def _emit(quiet: bool, msg: str) -> None:
+    if not quiet:
+        print(msg)
+
+
+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 [])
+    if not entries:
+        _emit(opts.quiet, f"ℹ️  Manifest is empty: {manifest}")
+        return 0
+
+    missing, surfaced = _group_by_scope(entries, project_root)
+    total_missing = sum(len(v) for v in missing.values())
+    total_present = len(entries) - total_missing
+
+    _emit(opts.quiet, f"Manifest:  {manifest}")
+    _emit(opts.quiet, f"Tools:     {len(entries)} listed, {total_present} present, {total_missing} missing")
+    if total_missing == 0:
+        _emit(opts.quiet, "✅  All bridges already installed. Nothing to do.")
+        return 0
+
+    for name, marker in surfaced:
+        _emit(opts.quiet, f"  • {name:<15} → {marker} (missing)")
+
+    if opts.dry_run:
+        _emit(opts.quiet, "")
+        _emit(opts.quiet, "Dry-run: no bridges written.")
+        return 0
+
+    _emit(opts.quiet, "")
+    for scope in ("project", "global"):
+        tools = missing[scope]
+        if not tools:
+            continue
+        _emit(opts.quiet, f"Replaying scope={scope}: {', '.join(sorted(tools))}")
+        rc = _run_install(scope, tools, project_root, force=opts.force, dry_run=False)
+        if rc != 0:
+            _emit(opts.quiet, f"❌  Installer failed for scope={scope} (rc={rc}); aborting.")
+            return rc
+
+    _emit(opts.quiet, "")
+    _emit(opts.quiet, "✅  Sync complete.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/scripts/_cli/cmd_update.py

@@ -36,7 +36,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Optional
 
-from scripts._lib import update_check
+from scripts._lib import installed_lock, update_check
 from scripts._lib.agent_settings import (
     DEFAULT_PROJECT_FILE,
     _resolve_cascade_paths,
@@ -205,9 +205,31 @@ def main(
 
     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 ``~/.config/agent-config/installed.lock`` if it exists.
+
+    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``.
+    """
+    lock_path = installed_lock.lockfile_path()
+    existing = installed_lock.read_lockfile(path=lock_path)
+    if existing is None:
+        return
+    recorded = existing.get("agent_config_version")
+    tools = list(existing.get("tools", []))
+    if recorded == version:
+        print(f"ℹ️  {lock_path} already records {version}.", file=out)
+        return
+    installed_lock.write_lockfile(version, tools, path=lock_path)
+    print(f"✅  Refreshed global lockfile at {lock_path}.", file=out)
+
+
 def _detect_installed_version() -> str:
     """Read ``version`` from the package's own ``package.json``."""
     pkg_json = Path(__file__).resolve().parents[2] / "package.json"

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"