@event4u/agent-config 5.10.1 → 6.0.0

package/src/scripts/_lib/global_deploy_inventory.py

@@ -0,0 +1,282 @@
+"""Per-tool inventory of files written by global deploys — and stale reaping.
+
+Sidecar at ``~/.event4u/agent-config/deployed-files.json``. Records, per
+tool, the anchor directory and the relative paths of every file the most
+recent global deploy maintains there. On the next deploy the previous
+inventory is diffed against the current expected file set and **only**
+previously-recorded, now-orphaned files are deleted.
+
+Why this exists (2026-06 Zed fix follow-up): deploy anchors are SHARED
+directories — ``~/.agents/skills/`` holds the user's own Zed skills next to
+agent-config's deployed bundle, ``~/.claude/commands/`` holds user-authored
+commands. A naive "delete everything not in the source" sync would destroy
+user files, so the installer historically deleted nothing — and renamed or
+removed package skills (e.g. the pre-fix colon-named command-as-skill
+entries from 2026-05-13) rotted in place until Zed rejected them with
+"Skill name must contain only lowercase letters, numbers, and hyphens".
+The inventory provides the ownership proof that makes reaping safe: a path
+is deleted only if a previous agent-config deploy recorded writing it AND
+the current deploy no longer ships it.
+
+Safety properties:
+
+- Never deletes a path that was not recorded by a previous deploy.
+- Never deletes outside the recorded anchor (resolved containment check).
+- Never deletes directories — only files/symlinks, then prunes empty dirs.
+- Anchor moved between installs → no reaping (the old tree is unknown
+  territory; the new inventory simply replaces the record).
+- Missing / corrupt inventory → no reaping (first run records only).
+
+Schema (JSON)::
+
+    {
+      "schema_version": 1,
+      "tools": {
+        "<tool_id>": {
+          "anchor": "/abs/path/to/anchor",
+          "files": ["skills/foo/SKILL.md", ...]   # anchor-relative, sorted
+        }
+      }
+    }
+"""
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Optional
+
+try:  # package-style import (pytest, installed package)
+    from scripts._lib import user_global_paths
+except ImportError:  # pragma: no cover — script-style sys.path fallback
+    from _lib import user_global_paths  # type: ignore[no-redef]
+
+SCHEMA_VERSION = 1
+INVENTORY_BASENAME = "deployed-files.json"
+INVENTORY_ENV = "AGENT_CONFIG_DEPLOY_INVENTORY"
+
+
+def inventory_path(env: Optional[dict] = None) -> Path:
+    """Canonical inventory location, honoring the test/env override."""
+    env_map = env if env is not None else os.environ
+    override = env_map.get(INVENTORY_ENV)
+    if override:
+        return Path(override).expanduser()
+    return user_global_paths.write_target(INVENTORY_BASENAME, env=env)
+
+
+def load_inventory(path: Optional[Path] = None) -> dict:
+    """Read the inventory; missing or malformed files yield an empty shell."""
+    target = path or inventory_path()
+    try:
+        data = json.loads(target.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {"schema_version": SCHEMA_VERSION, "tools": {}}
+    if not isinstance(data, dict) or not isinstance(data.get("tools"), dict):
+        return {"schema_version": SCHEMA_VERSION, "tools": {}}
+    return data
+
+
+def save_inventory(data: dict, path: Optional[Path] = None) -> Path:
+    """Atomically write the inventory (tempfile + os.replace)."""
+    target = path or inventory_path()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    payload = json.dumps(data, indent=2, sort_keys=True) + "\n"
+    fd, tmp_name = tempfile.mkstemp(
+        prefix=target.name + ".", dir=str(target.parent)
+    )
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(payload)
+        os.replace(tmp_name, target)
+    except OSError:
+        try:
+            os.unlink(tmp_name)
+        except OSError:
+            pass
+        raise
+    return target
+
+
+def expected_deploy_files(src: Path, dest_rel: Path) -> set[str]:
+    """Anchor-relative paths the deploy of ``src`` → ``<anchor>/<dest_rel>``
+    maintains — written OR skipped-as-identical.
+
+    Mirrors the traversal of ``install._copy_dir_dereferencing_symlinks``:
+    symlinked files resolve to file entries, symlinked subdirectories are
+    walked through their resolved targets. ``dest_rel`` may be empty
+    (``Path('')``) for plan entries that deploy into the anchor root.
+    """
+    out: set[str] = set()
+    if not src.exists():
+        return out
+    if not src.is_dir():
+        out.add(dest_rel.as_posix())
+        return out
+
+    def _walk(node: Path, prefix: Path) -> None:
+        for entry in sorted(node.iterdir()):
+            rel = prefix / entry.name
+            if entry.is_dir() and not entry.is_symlink():
+                _walk(entry, rel)
+                continue
+            resolved = entry.resolve()
+            if resolved.is_dir():
+                _walk(resolved, rel)
+                continue
+            out.add(rel.as_posix())
+
+    _walk(src, dest_rel)
+    return out
+
+
+def reap_stale(
+    tool_id: str,
+    anchor: Path,
+    current_files: set[str],
+    inventory: dict,
+) -> list[Path]:
+    """Delete previously-deployed files that the current deploy dropped.
+
+    Returns the absolute paths actually deleted. Mutates nothing in
+    ``inventory`` — callers record the new state via :func:`record_deploy`.
+    """
+    entry = inventory.get("tools", {}).get(tool_id)
+    if not isinstance(entry, dict):
+        return []
+    recorded_anchor = entry.get("anchor")
+    prev_files = entry.get("files")
+    if not isinstance(recorded_anchor, str) or not isinstance(prev_files, list):
+        return []
+    anchor_resolved = anchor.expanduser().resolve()
+    if Path(recorded_anchor).expanduser().resolve() != anchor_resolved:
+        # Anchor moved between installs — the old tree is not provably
+        # ours anymore; record-only, never delete.
+        return []
+
+    deleted: list[Path] = []
+    prune_candidates: set[Path] = set()
+    for rel in sorted(set(prev_files) - current_files):
+        if not isinstance(rel, str) or not rel or rel.startswith(("/", "..")):
+            continue
+        target = anchor_resolved / rel
+        try:
+            # Containment proof: the path (sans final component, which may
+            # be a dangling symlink) must stay inside the anchor.
+            target.parent.resolve().relative_to(anchor_resolved)
+        except ValueError:
+            continue
+        if target.is_dir() and not target.is_symlink():
+            continue  # never delete directories
+        try:
+            target.unlink()
+        except FileNotFoundError:
+            continue
+        except OSError:
+            continue
+        deleted.append(target)
+        prune_candidates.add(target.parent)
+
+    # Prune now-empty directories left behind, up to (exclusive) the anchor.
+    for start in sorted(prune_candidates, key=lambda p: len(p.parts),
+                        reverse=True):
+        node = start
+        while node != anchor_resolved and anchor_resolved in node.parents:
+            try:
+                node.rmdir()  # only succeeds when empty
+            except OSError:
+                break
+            node = node.parent
+    return deleted
+
+
+def bootstrap_reap_tagged(
+    anchor: Path,
+    dest_subs: list[str],
+    current_files: set[str],
+    package_tag: str,
+) -> list[Path]:
+    """First-run reaping for PRE-inventory installs (marker-based ownership).
+
+    Existing installs in the wild predate the inventory sidecar, so
+    :func:`reap_stale` has nothing to diff against on the first upgraded
+    deploy — the legacy mess (renamed skills, retired command-as-skill
+    entries, the 2026-05-13 colon-named shapes) would rot forever. Every
+    deployed ``.md`` however carries the injected ``package:`` frontmatter
+    tag (install P5.1), which is exactly the ownership proof reaping needs.
+
+    Deletes ``.md`` files under ``<anchor>/<dest_sub>`` that (a) carry
+    ``package: <package_tag>`` in their frontmatter and (b) are not in the
+    current expected file set; then prunes empty directories. Untagged
+    files (user-authored skills in shared anchors) are never touched.
+    Returns the absolute paths deleted.
+    """
+    anchor_resolved = anchor.expanduser().resolve()
+    deleted: list[Path] = []
+    prune_candidates: set[Path] = set()
+    needle = f"package: {package_tag}"
+    for dest_sub in dest_subs:
+        root = anchor_resolved / dest_sub if dest_sub else anchor_resolved
+        if not root.is_dir():
+            continue
+        for md in root.rglob("*.md"):
+            if md.is_dir():
+                continue
+            rel = md.relative_to(anchor_resolved).as_posix()
+            if rel in current_files:
+                continue
+            try:
+                md.parent.resolve().relative_to(anchor_resolved)
+            except ValueError:
+                continue
+            try:
+                head = md.read_text(encoding="utf-8", errors="replace")
+            except OSError:
+                continue
+            if not head.startswith("---"):
+                continue
+            end = head.find("\n---", 3)
+            block = head[: end if end != -1 else len(head)]
+            if not any(
+                line.strip() == needle for line in block.splitlines()
+            ):
+                continue
+            try:
+                md.unlink()
+            except OSError:
+                continue
+            deleted.append(md)
+            prune_candidates.add(md.parent)
+    for start in sorted(prune_candidates, key=lambda p: len(p.parts),
+                        reverse=True):
+        node = start
+        while node != anchor_resolved and anchor_resolved in node.parents:
+            try:
+                node.rmdir()  # only succeeds when empty
+            except OSError:
+                break
+            node = node.parent
+    return deleted
+
+
+def record_deploy(
+    tool_id: str,
+    anchor: "Path | str",
+    current_files: set[str],
+    inventory: dict,
+) -> dict:
+    """Upsert the tool's inventory entry; returns the mutated inventory.
+
+    ``anchor`` is stored AS GIVEN — pass the unexpanded form (``~/.agents/``)
+    so the inventory content stays identical across machines/homes (GUI/CLI
+    parity) and survives a home relocation. :func:`reap_stale` expands the
+    recorded value at comparison time.
+    """
+    tools = inventory.setdefault("tools", {})
+    tools[tool_id] = {
+        "anchor": str(anchor),
+        "files": sorted(current_files),
+    }
+    inventory["schema_version"] = SCHEMA_VERSION
+    return inventory

package/src/scripts/_lib/install_regenerator.py

@@ -0,0 +1,134 @@
+"""Provision the roadmap-progress regenerator into a consumer.
+
+Phase 3 of `road-to-hooks-actually-fire-in-consumers`.
+
+The roadmap-progress hook (`scripts/roadmap_progress_hook.py`)
+searches three locations for `update_roadmap_progress.py`. Only the
+**canonical** location is reliable in marketplace-install consumers:
+`.augment/scripts/update_roadmap_progress.py`. This helper pins the
+contract and copies the script idempotently.
+
+Canonical paths:
+
+| Side | Path |
+|---|---|
+| Source-of-truth (package) | `packages/core/.agent-src.uncondensed/scripts/update_roadmap_progress.py` |
+| Package self-use (dogfooding) | `dist/agent-src/scripts/update_roadmap_progress.py` (and `.augment/scripts/update_roadmap_progress.py` after `task sync`) |
+| Consumer install target | `<consumer_root>/.augment/scripts/update_roadmap_progress.py` |
+
+Used by:
+  - `scripts/install.py`'s init / full-install path.
+  - `scripts/_dispatch.bash::cmd_hooks_install --regen`.
+
+Contract: idempotent; preserves executable bit; never blocks.
+"""
+from __future__ import annotations
+
+import shutil
+import stat
+import sys
+from pathlib import Path
+from typing import Optional
+
+
+REGENERATOR_REL = "scripts/update_roadmap_progress.py"
+"""Path of the script relative to the package's source-of-truth tree."""
+
+CONSUMER_REGENERATOR_REL = ".augment/scripts/update_roadmap_progress.py"
+"""Canonical destination path inside a consumer repo."""
+
+
+def package_source(package_root: Path) -> Optional[Path]:
+    """Resolve the package-side source-of-truth for the regenerator.
+
+    Searches the package layout in priority order:
+      1. `packages/core/.agent-src.uncondensed/scripts/update_roadmap_progress.py`
+      2. `dist/agent-src/scripts/update_roadmap_progress.py` (condensed projection)
+      3. `.augment/scripts/update_roadmap_progress.py` (tool projection)
+
+    Returns the first existing file, or None if none exist (which is
+    a misconfigured package and should be a hard error at the call
+    site).
+    """
+    candidates = [
+        # 6.0.x (ADR-051): uncondensed source container moved to src/agent-src/.
+        package_root / "src" / "agent-src" / REGENERATOR_REL,
+        # Back-compat: pre-collapse packages/core/ layout.
+        package_root / "packages" / "core" / ".agent-src.uncondensed" / REGENERATOR_REL,
+        package_root / "dist/agent-src" / REGENERATOR_REL,
+        package_root / ".augment" / REGENERATOR_REL,
+    ]
+    for c in candidates:
+        if c.is_file():
+            return c
+    return None
+
+
+def consumer_target(consumer_root: Path) -> Path:
+    """Canonical destination path inside the consumer repo."""
+    return consumer_root / CONSUMER_REGENERATOR_REL
+
+
+def install_regenerator(package_root: Path, consumer_root: Path) -> tuple[bool, str]:
+    """Copy the regenerator into the consumer. Idempotent.
+
+    Returns (success, message). `success=False` means the call site
+    should surface the message; the helper never raises.
+    """
+    source = package_source(package_root)
+    if source is None:
+        return (
+            False,
+            "regenerator source not found in package "
+            "(searched src/agent-src/, packages/core/.agent-src.uncondensed/, "
+            "dist/agent-src/, .augment/)",
+        )
+    target = consumer_target(consumer_root)
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        # Idempotent: skip the copy if content is byte-identical.
+        if target.exists() and target.read_bytes() == source.read_bytes():
+            return (True, f"regenerator already current at {target}")
+        shutil.copyfile(source, target)
+        # Preserve executable bit so the hook can subprocess-call it.
+        mode = target.stat().st_mode
+        target.chmod(
+            mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH
+        )
+        return (True, f"regenerator installed at {target}")
+    except OSError as exc:
+        return (False, f"failed to install regenerator: {exc}")
+
+
+def is_installed(consumer_root: Path) -> bool:
+    """Quick boolean — does the canonical regenerator exist + is executable?"""
+    target = consumer_target(consumer_root)
+    if not target.is_file():
+        return False
+    import os
+    return os.access(target, os.X_OK)
+
+
+def main() -> int:
+    """CLI entry point — `python3 -m scripts._lib.install_regenerator <consumer-root>`."""
+    if len(sys.argv) < 2:
+        print(
+            "usage: install_regenerator.py <consumer_root> [<package_root>]",
+            file=sys.stderr,
+        )
+        return 2
+    consumer_root = Path(sys.argv[1]).resolve()
+    package_root = (
+        Path(sys.argv[2]).resolve()
+        # __file__ = src/scripts/_lib/install_regenerator.py → package root is
+        # four levels up (_lib → scripts → src → root) since 6.0.0-D.
+        if len(sys.argv) > 2
+        else Path(__file__).resolve().parents[3]
+    )
+    ok, msg = install_regenerator(package_root, consumer_root)
+    print(msg)
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/scripts/_lib/installed_lock.py

@@ -0,0 +1,256 @@
+"""Global-install lockfile at ``~/.event4u/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.
+
+Path resolution is delegated to :mod:`scripts._lib.user_global_paths`
+(Phase 1 of road-to-event4u-namespace-and-claude-desktop.md): writes
+land at ``~/.event4u/agent-config/installed.lock``; reads fall back to
+the legacy ``~/.config/agent-config/installed.lock`` if the new path
+is missing, so pre-2.4 installs keep working during the transition.
+"""
+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
+
+from scripts._lib import user_global_paths
+
+LOCKFILE_ENV = "AGENT_CONFIG_INSTALLED_LOCK"
+SCHEMA_VERSION = 1
+
+
+def _default_lockfile() -> Path:
+    """Canonical write target for the lockfile (new namespace)."""
+    return user_global_paths.write_target("installed.lock")
+
+
+# Module-level constant retained for back-compat with importers that read
+# ``installed_lock.DEFAULT_LOCKFILE`` directly. Derived from the helper so
+# the path tracks any future override of ``event4u_root()``.
+DEFAULT_LOCKFILE = _default_lockfile()
+
+_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 for **reads**, honoring overrides.
+
+    Resolution order:
+
+    1. ``$AGENT_CONFIG_INSTALLED_LOCK``  — explicit full-path override.
+    2. ``~/.event4u/agent-config/installed.lock`` if it exists on disk.
+    3. ``~/.config/agent-config/installed.lock``  (legacy fallback, read-only).
+    4. Canonical write target under the new namespace (Step 2 fallthrough).
+
+    Readers benefit from (3) so pre-2.4 installs keep working while the
+    migration shim has not yet run. Writers must use
+    :func:`lockfile_write_path` so a stale legacy file does not anchor
+    subsequent writes to the deprecated location.
+    """
+    env = env if env is not None else os.environ
+    override = env.get(LOCKFILE_ENV)
+    if override:
+        return Path(override).expanduser()
+    resolved = user_global_paths.resolve_with_fallback("installed.lock", env=env)
+    if resolved is not None:
+        return resolved
+    return user_global_paths.write_target("installed.lock", env=env)
+
+
+def lockfile_write_path(env: Optional[dict] = None) -> Path:
+    """Return the canonical write target for the lockfile.
+
+    Unlike :func:`lockfile_path`, this never falls back to the legacy
+    ``~/.config/agent-config/`` location. Honors the
+    ``$AGENT_CONFIG_INSTALLED_LOCK`` override for tests, otherwise pins
+    to ``~/.event4u/agent-config/installed.lock``. Callers in
+    ``init``, ``update``, and ``uninstall`` use this so writes always
+    land in the new namespace regardless of whether a stale legacy
+    lockfile is still present.
+    """
+    env = env if env is not None else os.environ
+    override = env.get(LOCKFILE_ENV)
+    if override:
+        return Path(override).expanduser()
+    return user_global_paths.write_target("installed.lock", env=env)
+
+
+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)
+
+
+_SEMVER_RE = re.compile(r"^\s*v?(\d+)\.(\d+)\.(\d+)")
+
+
+def _parse_semver(version: str) -> Optional[tuple[int, int, int]]:
+    """Parse ``X.Y.Z[-suffix]`` into a ``(major, minor, patch)`` tuple.
+
+    Returns ``None`` when the leading three numeric segments cannot be
+    extracted. Suffixes (``-rc1``, ``+build.5``) are ignored: the
+    classification only needs the numeric prefix to decide upgrade vs
+    downgrade.
+    """
+    match = _SEMVER_RE.match(version)
+    if not match:
+        return None
+    return int(match.group(1)), int(match.group(2)), int(match.group(3))
+
+
+def classify_mismatch(
+    installed_version: str, recorded: Optional[str],
+) -> str:
+    """Classify the relationship between recorded and installed versions.
+
+    Returns one of:
+      * ``"none"``        — no lockfile yet; install proceeds clean.
+      * ``"match"``       — recorded equals installed.
+      * ``"upgrade"``     — recorded < installed; auto-heal allowed.
+      * ``"downgrade"``   — recorded > installed; refuse without ``--force``.
+      * ``"unparseable"`` — recorded shape unrecognizable (pre-1.0, 1.x
+        legacy formats from the namespace migration); treated as
+        upgrade by the install path.
+    """
+    if recorded is None:
+        return "none"
+    if recorded == installed_version:
+        return "match"
+    rec = _parse_semver(recorded)
+    inst = _parse_semver(installed_version)
+    if rec is None or inst is None:
+        return "unparseable"
+    if rec < inst:
+        return "upgrade"
+    return "downgrade"
+
+
+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[3]
+    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"