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

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

@@ -1,404 +0,0 @@
-#!/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())