@adia-ai/adia-ui-factory 0.2.2 → 0.2.4

package/skills/adia-ui-kit/scripts/check-adia-versions.py

@@ -0,0 +1,404 @@
+#!/usr/bin/env python3
+"""
+check-adia-versions.py — verify your @adia-ai/* install is sane.
+
+Run this from any consumer project (not just the monorepo). Walks three
+sources and reports drift:
+
+  1. Installed (node_modules/@adia-ai/<pkg>/package.json)
+  2. Declared (your package.json `dependencies` + `devDependencies`)
+  3. Latest published (npm view @adia-ai/<pkg> version — needs network)
+
+Exits 0 when everything lines up. Exits 1 on drift. Exits 2 on
+unrecoverable error (missing node_modules, malformed package.json).
+
+Usage
+-----
+  ./check-adia-versions.py                 # full check (network)
+  ./check-adia-versions.py --offline       # skip npm view, lockstep only
+  ./check-adia-versions.py --json          # machine-readable output
+  ./check-adia-versions.py --root .        # explicit consumer root
+
+Why this exists
+---------------
+The 9 `@adia-ai/*` packages ship in lockstep — one stale install desyncs
+the whole bundle. Plus the skill documents fixes that only apply at
+specific versions (e.g. F-014/F-015: v0.6.7 ships broken absolute-path
+imports in `@adia-ai/web-modules`, fix lands in v0.6.8). Without a
+verification step, agents trust their installed snapshot blindly and
+ship advice that's wrong for the user's actual install.
+
+Output legend
+-------------
+  ✓ ok          installed == declared, and matches latest (or --offline)
+  🔗 linked     declared as `file:...`, `link:...`, or `workspace:*` —
+                local development link, not an npm version (informational)
+  ⚠ stale       installed < latest published — `npm update` recommended
+  ⚠ split       lockstep broken — packages disagree on version
+  ⚠ undeclared  installed in node_modules but missing from package.json
+  ⚠ uninstalled declared but missing from node_modules — `npm install`
+  ✗ ahead       installed > latest published — local source build /
+                pre-publish state (informational, not an error in this
+                monorepo where you may dev against unpublished cuts)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+
+PACKAGE_NAMES = [
+    "@adia-ai/web-components",
+    "@adia-ai/web-modules",
+    "@adia-ai/llm",
+    "@adia-ai/a2ui-runtime",
+    "@adia-ai/a2ui-compose",
+    "@adia-ai/a2ui-corpus",
+    "@adia-ai/a2ui-mcp",
+    "@adia-ai/a2ui-retrieval",
+    "@adia-ai/a2ui-validator",
+]
+
+
+@dataclass
+class PackageStatus:
+    name: str
+    installed: Optional[str] = None
+    declared: Optional[str] = None          # raw range from package.json
+    declared_normalized: Optional[str] = None  # version stripped of ^~
+    latest: Optional[str] = None
+    symlinked: bool = False                  # node_modules/<name> is a symlink
+    issues: list[str] = field(default_factory=list)
+
+
+def read_json(path: Path) -> Optional[dict]:
+    try:
+        return json.loads(path.read_text())
+    except (FileNotFoundError, json.JSONDecodeError):
+        return None
+
+
+def is_link_spec(spec: Optional[str]) -> bool:
+    """Detect local-development link specs (file:, link:, workspace:)."""
+    if not spec:
+        return False
+    return spec.startswith(("file:", "link:", "workspace:", "portal:"))
+
+
+def normalize_range(spec: str) -> str:
+    """Strip leading ^ ~ >= etc. from a semver range to get a version."""
+    if not spec:
+        return ""
+    # Link specs aren't semver — leave them alone for display
+    if is_link_spec(spec):
+        return spec
+    m = re.match(r"^[\^~><=\s]*([\d]+\.[\d]+\.[\d]+(?:-[\w.]+)?)", spec)
+    return m.group(1) if m else spec
+
+
+def parse_semver(v: Optional[str]) -> tuple[int, int, int]:
+    if not v:
+        return (0, 0, 0)
+    m = re.match(r"^(\d+)\.(\d+)\.(\d+)", v)
+    if not m:
+        return (0, 0, 0)
+    return (int(m.group(1)), int(m.group(2)), int(m.group(3)))
+
+
+def get_installed(root: Path, name: str) -> Optional[str]:
+    pkg = root / "node_modules" / name / "package.json"
+    data = read_json(pkg)
+    return data.get("version") if data else None
+
+
+def is_symlinked(root: Path, name: str) -> bool:
+    """Check whether node_modules/<name> is a symlink (linked) vs a real dir."""
+    pkg_dir = root / "node_modules" / name
+    try:
+        return pkg_dir.is_symlink()
+    except OSError:
+        return False
+
+
+def get_declared(consumer_pkg: dict, name: str) -> Optional[str]:
+    for field_name in ("dependencies", "devDependencies", "peerDependencies"):
+        spec = (consumer_pkg.get(field_name) or {}).get(name)
+        if spec:
+            return spec
+    return None
+
+
+def get_latest(name: str, timeout: int = 10) -> Optional[str]:
+    """Query npm registry for the dist-tag latest version. Network call."""
+    try:
+        result = subprocess.run(
+            ["npm", "view", name, "version"],
+            capture_output=True, text=True, timeout=timeout,
+        )
+        if result.returncode == 0:
+            return result.stdout.strip() or None
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        pass
+    return None
+
+
+def check_lockstep(statuses: list[PackageStatus]) -> Optional[str]:
+    """Return the consensus installed version, or None if split."""
+    versions = {s.installed for s in statuses if s.installed}
+    if len(versions) == 0:
+        return None
+    if len(versions) == 1:
+        return versions.pop()
+    return None  # split
+
+
+def run_audit(root: Path, offline: bool) -> tuple[list[PackageStatus], dict]:
+    consumer_pkg = read_json(root / "package.json") or {}
+
+    # Monorepo-root detection: if this package.json declares "workspaces",
+    # we're inside the @adia-ai/* source monorepo, not a consumer project.
+    # In that case, "undeclared" is expected (the packages are workspaces,
+    # not external deps) — suppress the noise.
+    is_monorepo_root = bool(consumer_pkg.get("workspaces"))
+
+    # "undeclared" classification — only flag when it likely reflects a
+    # mistake. In a consumer project, sub-packages like @adia-ai/llm,
+    # a2ui-runtime, a2ui-mcp are commonly transitive deps pulled in by
+    # @adia-ai/web-components or web-modules; "undeclared" there is noise.
+    # We only flag undeclared when:
+    #   (a) we are NOT in the monorepo root (workspaces detected), AND
+    #   (b) the package is one of the user-facing entry points
+    #       (web-components, web-modules) AND it's installed.
+    # This catches the real failure mode (someone deleted the dep but
+    # node_modules still has it = phantom install) without spamming on
+    # legitimate transitive deps.
+    USER_FACING = {"@adia-ai/web-components", "@adia-ai/web-modules"}
+
+    statuses: list[PackageStatus] = []
+    for name in PACKAGE_NAMES:
+        s = PackageStatus(name=name)
+        s.installed = get_installed(root, name)
+        s.declared = get_declared(consumer_pkg, name)
+        s.declared_normalized = normalize_range(s.declared) if s.declared else None
+        s.symlinked = is_symlinked(root, name)
+        if not offline:
+            s.latest = get_latest(name)
+
+        declared_is_link = is_link_spec(s.declared)
+
+        # Per-package classification
+        if s.declared and not s.installed:
+            s.issues.append("uninstalled")
+        if (s.installed and not s.declared
+                and not is_monorepo_root
+                and name in USER_FACING):
+            s.issues.append("undeclared")
+        # Link-spec packages get a "linked" marker; suppress version-drift
+        # warnings since semver comparison doesn't apply to file:/link:/workspace:.
+        if declared_is_link:
+            s.issues.append("linked")
+            # Pitfall warning: declared as link but installed as real dir
+            # (npm sometimes copies instead of linking)
+            if s.installed and not s.symlinked:
+                s.issues.append("link-copied-not-symlinked")
+        elif s.installed and s.latest:
+            inst = parse_semver(s.installed)
+            late = parse_semver(s.latest)
+            if inst < late:
+                s.issues.append("stale")
+            elif inst > late:
+                s.issues.append("ahead")
+
+        statuses.append(s)
+
+    consensus = check_lockstep(statuses)
+    summary = {
+        "consumer_root": str(root.resolve()),
+        "consensus_installed": consensus,
+        "split_lockstep": consensus is None and any(s.installed for s in statuses),
+        "offline": offline,
+        "is_monorepo_root": is_monorepo_root,
+    }
+    return statuses, summary
+
+
+def render_text(statuses: list[PackageStatus], summary: dict) -> int:
+    """Human-readable output. Returns process exit code."""
+    print(f"@adia-ai install audit — {summary['consumer_root']}")
+    if summary.get("is_monorepo_root"):
+        print("(monorepo-root mode — workspaces detected, 'undeclared' suppressed)")
+    print("─" * 78)
+
+    any_issues = False
+    consensus_latest = None
+    for s in statuses:
+        if s.latest:
+            consensus_latest = s.latest
+            break  # first one with a latest is enough for the header line
+
+    if consensus_latest:
+        print(f"Latest published (npm view): {consensus_latest}")
+    if summary["consensus_installed"]:
+        print(f"Consensus installed:        {summary['consensus_installed']}")
+    elif summary["split_lockstep"]:
+        print("Consensus installed:        ⚠ SPLIT — packages disagree")
+        any_issues = True
+    print()
+
+    # Per-package table
+    name_width = max(len(s.name) for s in statuses) + 2
+    print(f"  {'package'.ljust(name_width)}  {'installed':<10}  {'declared':<26}  {'latest':<10}  status")
+    print(f"  {'-' * name_width}  {'-' * 10}  {'-' * 26}  {'-' * 10}  {'-' * 24}")
+
+    for s in statuses:
+        installed = s.installed or "—"
+        declared = s.declared or "—"
+        # Truncate long file: specs for table readability
+        if declared and len(declared) > 26:
+            declared = declared[:23] + "..."
+        latest = s.latest or ("(offline)" if summary["offline"] else "—")
+
+        if not s.issues:
+            status = "✓ ok"
+        else:
+            status_parts = []
+            for i in s.issues:
+                if i == "linked":
+                    status_parts.append("🔗 linked")
+                elif i == "ahead":
+                    status_parts.append("ⓘ ahead")
+                elif i == "link-copied-not-symlinked":
+                    status_parts.append("⚠ copied-not-linked")
+                else:
+                    status_parts.append(f"⚠ {i}")
+            status = " · ".join(status_parts)
+            # Only count as a real failure if it's not purely informational
+            real_issues = [i for i in s.issues
+                           if i not in ("ahead", "linked")]
+            if real_issues:
+                any_issues = True
+
+        print(f"  {s.name.ljust(name_width)}  {installed:<10}  {declared:<26}  {latest:<10}  {status}")
+
+    print()
+
+    # Diagnostics
+    if summary["split_lockstep"]:
+        print("✗ Lockstep broken — the 9 @adia-ai/* packages must share a version.")
+        print("  Fix: `npm install @adia-ai/web-components@<v> @adia-ai/web-modules@<v> ...`")
+        print("  or delete node_modules + package-lock.json and `npm install`.")
+        print()
+
+    stale_pkgs = [s for s in statuses if "stale" in s.issues]
+    if stale_pkgs:
+        print(f"⚠ Stale: {len(stale_pkgs)} package(s) behind latest. Suggested:")
+        print(f"  npm install {' '.join(f'{s.name}@latest' for s in stale_pkgs)}")
+        print()
+
+    ahead_pkgs = [s for s in statuses if "ahead" in s.issues]
+    if ahead_pkgs:
+        print(f"ⓘ Ahead: {len(ahead_pkgs)} package(s) installed past latest published.")
+        print("  This is normal in the monorepo (pre-publish dev cut) or if you")
+        print("  installed from a local tarball / git tag. Not an error.")
+        print()
+
+    linked_pkgs = [s for s in statuses if "linked" in s.issues]
+    if linked_pkgs:
+        all_linked = len(linked_pkgs) == sum(1 for s in statuses if s.declared)
+        print(f"🔗 Linked: {len(linked_pkgs)} package(s) declared as local "
+              f"dev link ({'all declared' if all_linked else 'subset'}).")
+        print("  Version comparison disabled for these — they resolve to source")
+        print("  on disk, not an npm-published version. The 'installed' column")
+        print("  shows the version from the linked source's package.json.")
+        if not all_linked and sum(1 for s in statuses if s.declared) > len(linked_pkgs):
+            print()
+            print("  ⚠ Mixed link + npm declarations risk split-lockstep when the")
+            print("    linked source's transitive deps disagree with what npm")
+            print("    resolved. Recommended: link ALL 9 @adia-ai/* packages, or")
+            print("    link NONE. See §LocalLink in the adia-ui-kit skill.")
+        print()
+
+    copied_pkgs = [s for s in statuses if "link-copied-not-symlinked" in s.issues]
+    if copied_pkgs:
+        print(f"⚠ Link copied, not symlinked: {len(copied_pkgs)} package(s).")
+        print("  npm sometimes copies file: deps instead of symlinking — edits")
+        print("  to source won't be reflected. Fix:")
+        print("    rm -rf node_modules/@adia-ai")
+        print("    npm install --install-links=false")
+        print("  Then re-run this script to confirm symlinks are in place.")
+        print()
+
+    uninstalled = [s for s in statuses if "uninstalled" in s.issues]
+    if uninstalled:
+        print(f"⚠ Declared but uninstalled: {len(uninstalled)} package(s).")
+        print("  Fix: `npm install`")
+        print()
+
+    if not any_issues:
+        print("✓ All clean — lockstep aligned, declarations match installs, "
+              "and (if online) installs match latest published.")
+        return 0
+
+    return 1
+
+
+def render_json(statuses: list[PackageStatus], summary: dict) -> int:
+    payload = {
+        "summary": summary,
+        "packages": [
+            {
+                "name": s.name,
+                "installed": s.installed,
+                "declared": s.declared,
+                "declared_normalized": s.declared_normalized,
+                "latest": s.latest,
+                "symlinked": s.symlinked,
+                "issues": s.issues,
+            }
+            for s in statuses
+        ],
+    }
+    print(json.dumps(payload, indent=2))
+    # 'ahead' and 'linked' are informational, not failures
+    real_issues = summary["split_lockstep"] or any(
+        i for s in statuses for i in s.issues if i not in ("ahead", "linked")
+    )
+    return 1 if real_issues else 0
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Verify @adia-ai/* install lockstep + freshness.",
+    )
+    parser.add_argument("--root", default=".",
+                        help="Consumer project root (default: cwd).")
+    parser.add_argument("--offline", action="store_true",
+                        help="Skip npm view (no network).")
+    parser.add_argument("--json", action="store_true",
+                        help="Machine-readable JSON output.")
+    args = parser.parse_args(argv)
+
+    root = Path(args.root).resolve()
+    if not (root / "package.json").exists():
+        print(f"✗ No package.json at {root}", file=sys.stderr)
+        return 2
+    if not (root / "node_modules").exists():
+        print(f"⚠ No node_modules at {root} — run `npm install` first", file=sys.stderr)
+        return 2
+
+    statuses, summary = run_audit(root, args.offline)
+
+    if args.json:
+        return render_json(statuses, summary)
+    return render_text(statuses, summary)
+
+
+if __name__ == "__main__":
+    sys.exit(main())