zexus 1.7.1 → 1.7.2

package/src/zexus/zexus_ast.py

@@ -2,6 +2,10 @@
 
 # Base classes
 class Node: 
+    # Source location for debugger / error reporting (set by parser)
+    line: int = 0
+    column: int = 0
+
     def __repr__(self):
         return f"{self.__class__.__name__}()"
 
@@ -33,13 +37,16 @@ class ConstStatement(Statement):
     """Const statement - immutable variable declaration
     
     const MAX_VALUE = 100;
+    const PI: float = 3.14;
     """
-    def __init__(self, name, value):
+    def __init__(self, name, value, type_annotation=None):
         self.name = name
         self.value = value
+        self.type_annotation = type_annotation
 
     def __repr__(self):
-        return f"ConstStatement(name={self.name}, value={self.value})"
+        type_str = f", type={self.type_annotation}" if self.type_annotation else ""
+        return f"ConstStatement(name={self.name}, value={self.value}{type_str})"
 
 class DataStatement(Statement):
     """Data statement - dataclass definition
@@ -386,13 +393,15 @@ class DebugStatement(Statement):
 
 # NEW: Try-catch statement  
 class TryCatchStatement(Statement):
-    def __init__(self, try_block, error_variable, catch_block):
+    def __init__(self, try_block, error_variable, catch_block, finally_block=None):
         self.try_block = try_block
         self.error_variable = error_variable
         self.catch_block = catch_block
+        self.finally_block = finally_block
 
     def __repr__(self):
-        return f"TryCatchStatement(error_var={self.error_variable})"
+        has_finally = " +finally" if self.finally_block else ""
+        return f"TryCatchStatement(error_var={self.error_variable}{has_finally})"
 
 # NEW: External function declaration
 class ExternalDeclaration(Statement):
@@ -464,11 +473,13 @@ class TrailStatement(Statement):
 
 # Expression Nodes
 class Identifier(Expression):
-    def __init__(self, value): 
+    def __init__(self, value, type_annotation=None): 
         self.value = value
+        self.type_annotation = type_annotation  # Optional[str] for typed parameters
 
     def __repr__(self):
-        return f"Identifier('{self.value}')"
+        type_str = f": {self.type_annotation}" if self.type_annotation else ""
+        return f"Identifier('{self.value}{type_str}')"
     
     def __str__(self):
         return self.value
@@ -497,6 +508,19 @@ class StringLiteral(Expression):
     def __str__(self):
         return self.value
 
+class StringInterpolationExpression(Expression):
+    """String interpolation: "hello ${name}, you are ${age} years old"
+    
+    parts is a list of (type, value) where type is "str" or "expr".
+    For "str" parts, value is a string literal.
+    For "expr" parts, value is a parsed Expression AST node.
+    """
+    def __init__(self, parts):
+        self.parts = parts  # list of ("str", string) or ("expr", Expression)
+    
+    def __repr__(self):
+        return f"StringInterpolation({len(self.parts)} parts)"
+
 class Boolean(Expression):
     def __init__(self, value): 
         self.value = value
@@ -519,6 +543,25 @@ class ThisExpression(Expression):
         return "ThisExpression()"
 
 
+class DestructurePattern(Expression):
+    """Destructuring pattern for let/const assignments.
+    
+    kind='map':  let {a, b} = expr  or  let {a: x, b: y} = expr
+    kind='list': let [x, y, z] = expr
+    
+    bindings: list of (source_key, target_name) tuples
+      - map:  [("a", "a"), ("b", "renamed")] for {a, b: renamed}
+      - list: [(0, "x"), (1, "y")] for [x, y]
+    rest: optional name for rest element (..rest)
+    """
+    def __init__(self, kind, bindings, rest=None):
+        self.kind = kind          # 'map' or 'list'
+        self.bindings = bindings  # list of (source, target_name_str)
+        self.rest = rest          # optional rest variable name
+
+    def __repr__(self):
+        return f"DestructurePattern(kind={self.kind}, bindings={len(self.bindings)}, rest={self.rest})"
+
 class ListLiteral(Expression):
     def __init__(self, elements): 
         self.elements = elements
@@ -647,6 +690,17 @@ class PropertyAccessExpression(Expression):
     def __repr__(self):
         return f"PropertyAccessExpression(object={self.object}, property={self.property}, computed={self.computed})"
 
+
+class SliceExpression(Expression):
+    """Slice expression: obj[start:end]"""
+    def __init__(self, object, start=None, end=None):
+        self.object = object
+        self.start = start
+        self.end = end
+
+    def __repr__(self):
+        return f"SliceExpression(object={self.object}, start={self.start}, end={self.end})"
+
 class AssignmentExpression(Expression):
     def __init__(self, name, value):
         self.name = name
@@ -1163,9 +1217,6 @@ class WatchStatement(Statement):
     def __repr__(self):
         return f"WatchStatement(expr={self.watched_expr}, reaction={self.reaction})"
 
-    def __repr__(self):
-        return f"WatchStatement(watch={self.watched_expr})"
-
 
 class LogStatement(Statement):
     """Log statement - Redirect output to file
@@ -1574,12 +1625,13 @@ class StateStatement(Statement):
     state owner = TX.caller;
     state locked = false;
     """
-    def __init__(self, name, initial_value=None):
+    def __init__(self, name, initial_value=None, modifiers=None):
         self.name = name  # Identifier: state variable name
         self.initial_value = initial_value  # Optional Expression: initial value
+        self.modifiers = modifiers or []  # List[str]: modifiers (private, public, etc.)
 
     def __repr__(self):
-        return f"StateStatement(name={self.name}, initial={self.initial_value})"
+        return f"StateStatement(name={self.name}, initial={self.initial_value}, modifiers={self.modifiers})"
 
 
 class ContractStatement(Statement):

package/src/zexus/zexus_token.py

@@ -32,6 +32,16 @@ OR = "||"
 QUESTION = "?"          # Ternary operator: condition ? true_val : false_val
 NULLISH = "??"          # Nullish coalescing: value ?? default
 
+# Compound Assignment Operators
+PLUS_ASSIGN = "+="      # Addition assignment: x += 5
+MINUS_ASSIGN = "-="     # Subtraction assignment: x -= 5
+STAR_ASSIGN = "*="      # Multiplication assignment: x *= 5
+SLASH_ASSIGN = "/="     # Division assignment: x /= 5
+MOD_ASSIGN = "%="       # Modulo assignment: x %= 5
+POWER = "**"            # Exponentiation: x ** 2
+POWER_ASSIGN = "**="    # Exponentiation assignment: x **= 2
+INTERP_STRING = "INTERP_STRING"  # String interpolation: "hello ${name}"
+
 # Delimiters
 COMMA = ","
 SEMICOLON = ";"
@@ -87,6 +97,7 @@ LAMBDA = "LAMBDA"
 DEBUG = "DEBUG"      # NEW: Debug token
 TRY = "TRY"          # NEW: Try token
 CATCH = "CATCH"      # NEW: Catch token
+FINALLY = "FINALLY"  # NEW: Finally token
 CONTINUE = "CONTINUE" # NEW: Continue on error token
 BREAK = "BREAK"      # NEW: Break loop statement
 THROW = "THROW"      # NEW: Throw error statement
@@ -177,7 +188,6 @@ LIMIT = "LIMIT"                # Gas/resource limit: action transfer() limit 100
 GAS = "GAS"                    # Gas tracking: gas_used(), gas_remaining()
 PERSISTENT = "PERSISTENT"
 STORAGE = "STORAGE"
-REQUIRE = "REQUIRE"
 
 # PERFORMANCE OPTIMIZATION TOKENS
 NATIVE = "NATIVE"            # Call C/C++ code: native { "func_name", arg1, arg2 }
@@ -190,9 +200,10 @@ SIMD = "SIMD"                # Vector operations: simd(operation, vector1, vecto
 DEFER = "DEFER"              # Cleanup code execution: defer cleanup_code;
 PATTERN = "PATTERN"          # Pattern matching: pattern value { case x => ...; }
 MATCH = "MATCH"              # Match expression: match value { Point(x, y) => ... }
+CASE = "CASE"                # Case clause in match/pattern
+DEFAULT = "DEFAULT"          # Default case in match
 
 # ADVANCED FEATURES TOKENS
-ENUM = "ENUM"                # Type-safe enumerations: enum Color { Red, Green, Blue }
 STREAM = "STREAM"            # Event streaming: stream name as event => handler;
 WATCH = "WATCH"              # Reactive state management: watch variable => reaction;
 LOG = "LOG"                  # Output logging: log > filename.txt
@@ -201,9 +212,6 @@ LOG = "LOG"                  # Output logging: log > filename.txt
 PUBLIC = "PUBLIC"
 PRIVATE = "PRIVATE"
 SEALED = "SEALED"
-ASYNC = "ASYNC"
-NATIVE = "NATIVE"
-INLINE = "INLINE"
 SECURE = "SECURE"
 PURE = "PURE"
 VIEW = "VIEW"                  # View function (alias for pure, read-only)

package/src/zexus/zpm/installer.py

@@ -4,6 +4,7 @@ Package Installer - Handles package installation and dependencies
 import os
 import json
 import shutil
+import tarfile
 from pathlib import Path
 from typing import Dict, Optional
 
@@ -11,9 +12,10 @@ from typing import Dict, Optional
 class PackageInstaller:
     """Handles package installation"""
     
-    def __init__(self, install_dir: Path):
+    def __init__(self, install_dir: Path, registry=None):
         self.install_dir = Path(install_dir)
         self.install_dir.mkdir(parents=True, exist_ok=True)
+        self.registry = registry  # PackageRegistry for tarball downloads
     
     def install(self, package_info: Dict) -> bool:
         """Install a package"""
@@ -40,14 +42,12 @@ class PackageInstaller:
         if pkg_type == "builtin":
             self._install_builtin(name, version, target_dir)
         else:
-            # TODO: Download and extract package
             self._install_from_source(package_info, target_dir)
         
         return True
     
     def _install_builtin(self, name: str, version: str, target_dir: Path):
         """Install a built-in package"""
-        # Create package.json
         pkg_json = {
             "name": name,
             "version": version,
@@ -58,7 +58,6 @@ class PackageInstaller:
         with open(target_dir / "zexus.json", "w") as f:
             json.dump(pkg_json, f, indent=2)
         
-        # Create stub main file
         main_file = target_dir / "index.zx"
         main_file.write_text(f"""// {name} - Built-in Zexus package
 // Version: {version}
@@ -72,23 +71,64 @@ export {{
 """)
     
     def _install_from_source(self, package_info: Dict, target_dir: Path):
-        """Install package from source/tarball"""
-        # TODO: Implement actual download and extraction
-        
-        # For now, create placeholder
+        """Install package from a remote tarball or local path.
+
+        If the package metadata contains a ``tarball`` key pointing to a
+        local file, that tarball is extracted directly.  Otherwise the
+        installer attempts to download the tarball from the registry via
+        ``registry.download_tarball(name, version)``.
+        """
+        name = package_info["name"]
+        version = package_info["version"]
+
+        # 1. Check for a local tarball path in the metadata
+        tarball_path = package_info.get("tarball")
+        if tarball_path and os.path.isfile(tarball_path):
+            self._extract_tarball(Path(tarball_path), target_dir, name)
+            return
+
+        # 2. Try to download from the remote registry
+        if self.registry is not None:
+            downloaded = self.registry.download_tarball(name, version)
+            if downloaded and downloaded.exists():
+                print(f"📦 Downloaded {name}@{version}")
+                self._extract_tarball(downloaded, target_dir, name)
+                return
+
+        # 3. Fallback — create placeholder with metadata
+        print(f"⚠️  Could not download {name}@{version} — creating placeholder")
         pkg_json = {
-            "name": package_info["name"],
-            "version": package_info["version"],
+            "name": name,
+            "version": version,
             "description": package_info.get("description", ""),
         }
-        
         with open(target_dir / "zexus.json", "w") as f:
             json.dump(pkg_json, f, indent=2)
-        
         main_file = target_dir / "index.zx"
-        main_file.write_text(f"""// {package_info['name']}
-// Placeholder - package installation from remote sources not yet implemented
-""")
+        main_file.write_text(f'// {name}@{version} — placeholder (tarball not available)\n')
+
+    @staticmethod
+    def _extract_tarball(tarball_path: Path, target_dir: Path, package_name: str):
+        """Extract a ``.tar.gz`` tarball into *target_dir*.
+
+        Tarballs created by ``PackagePublisher`` contain files under a
+        ``<package_name>/`` prefix.  We strip that prefix so the files
+        land directly in *target_dir*.
+        """
+        with tarfile.open(tarball_path, "r:gz") as tar:
+            # Security: filter out absolute paths and ..'s
+            safe_members = []
+            prefix = f"{package_name}/"
+            for member in tar.getmembers():
+                if member.name.startswith("/") or ".." in member.name:
+                    continue
+                # Strip the package-name prefix from the archive path
+                if member.name.startswith(prefix):
+                    member.name = member.name[len(prefix):]
+                elif member.name == package_name:
+                    continue  # skip the bare directory entry
+                safe_members.append(member)
+            tar.extractall(path=target_dir, members=safe_members)
     
     def uninstall(self, package: str) -> bool:
         """Uninstall a package"""

package/src/zexus/zpm/package_manager.py

@@ -23,7 +23,7 @@ class PackageManager:
         self.installer = PackageInstaller(self.zpm_dir)
         self.publisher = PackagePublisher(self.registry)
         
-    def init(self, name: str = None, version: str = "1.7.1") -> Dict:
+    def init(self, name: str = None, version: str = "1.7.2") -> Dict:
         """Initialize a new Zexus project with package.json"""
         if self.config_file.exists():
             print(f"⚠️  {self.config_file} already exists")

package/src/zexus/zpm/registry.py

@@ -1,27 +1,136 @@
 """
 Package Registry - Manages package discovery and metadata
+
+Supports both a local cache and a remote HTTP registry.
+The registry URL defaults to ``https://registry.zexus.dev`` and can be
+overridden via the ``ZPM_REGISTRY`` environment variable.
+
+Auth tokens are read from ``~/.zpm/auth_token`` or the ``ZPM_AUTH_TOKEN``
+environment variable.
+
+REST API contract
+-----------------
+The following endpoints are expected on the registry server:
+
+    GET  /packages/<name>                 → package metadata (latest)
+    GET  /packages/<name>/<version>       → package metadata for version
+    GET  /packages/<name>/versions        → {"versions": ["0.1.0", …]}
+    GET  /search?q=<query>               → {"results": [{…}, …]}
+    POST /packages                        → publish (multipart: meta + tarball)
+    GET  /packages/<name>/<version>/download → tarball stream
 """
 import os
 import json
+import urllib.request
+import urllib.error
+import urllib.parse
 from pathlib import Path
 from typing import Dict, List, Optional
 
 
+class RegistryError(Exception):
+    """Raised when a registry operation fails."""
+
+
 class PackageRegistry:
     """Package registry for discovering and managing packages"""
     
     def __init__(self, registry_url: str = None):
-        self.registry_url = registry_url or os.environ.get(
-            "ZPM_REGISTRY",
-            "https://registry.zexus.dev"  # Default registry
-        )
+        self.registry_url = (
+            registry_url
+            or os.environ.get("ZPM_REGISTRY", "https://registry.zexus.dev")
+        ).rstrip("/")
         
         # Local cache directory
         self.cache_dir = Path.home() / ".zpm" / "cache"
         self.cache_dir.mkdir(parents=True, exist_ok=True)
         
+        # Auth token for publish operations
+        self._auth_token: Optional[str] = None
+        
         # Built-in packages
         self.builtin_packages = self._load_builtin_packages()
+
+    # ------------------------------------------------------------------
+    # Auth helpers
+    # ------------------------------------------------------------------
+
+    @property
+    def auth_token(self) -> Optional[str]:
+        """Lazily resolve the auth token from env or disk."""
+        if self._auth_token is not None:
+            return self._auth_token
+        # 1. Environment variable
+        token = os.environ.get("ZPM_AUTH_TOKEN")
+        if token:
+            self._auth_token = token
+            return token
+        # 2. Token file
+        token_path = Path.home() / ".zpm" / "auth_token"
+        if token_path.exists():
+            token = token_path.read_text().strip()
+            if token:
+                self._auth_token = token
+                return token
+        return None
+
+    def login(self, token: str) -> None:
+        """Store an auth token to ``~/.zpm/auth_token``."""
+        self._auth_token = token
+        token_path = Path.home() / ".zpm" / "auth_token"
+        token_path.parent.mkdir(parents=True, exist_ok=True)
+        token_path.write_text(token + "\n")
+        # Restrict permissions (owner-only read/write)
+        try:
+            token_path.chmod(0o600)
+        except OSError:
+            pass
+
+    # ------------------------------------------------------------------
+    # HTTP helpers
+    # ------------------------------------------------------------------
+
+    def _request(self, path: str, *, method: str = "GET",
+                 data: bytes = None, headers: dict = None,
+                 timeout: int = 30) -> Optional[bytes]:
+        """Perform an HTTP request against the registry.
+
+        Returns the response body on success, or ``None`` when the
+        resource is not found (HTTP 404).  Raises ``RegistryError`` for
+        other HTTP errors or connection failures.
+        """
+        url = f"{self.registry_url}{path}"
+        hdrs = {"User-Agent": "zpm/1.0"}
+        if self.auth_token:
+            hdrs["Authorization"] = f"Bearer {self.auth_token}"
+        if headers:
+            hdrs.update(headers)
+
+        req = urllib.request.Request(url, data=data, headers=hdrs, method=method)
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as resp:
+                return resp.read()
+        except urllib.error.HTTPError as exc:
+            if exc.code == 404:
+                return None
+            raise RegistryError(
+                f"Registry HTTP {exc.code} for {method} {path}: {exc.reason}"
+            ) from exc
+        except urllib.error.URLError as exc:
+            raise RegistryError(
+                f"Cannot reach registry at {self.registry_url}: {exc.reason}"
+            ) from exc
+
+    def _get_json(self, path: str) -> Optional[Dict]:
+        """GET ``path`` and parse the JSON body.  Returns None on 404."""
+        body = self._request(path)
+        if body is None:
+            return None
+        return json.loads(body)
+
+    # ------------------------------------------------------------------
+    # Built-in packages
+    # ------------------------------------------------------------------
     
     def _load_builtin_packages(self) -> Dict:
         """Load built-in package definitions"""
@@ -55,56 +164,176 @@ class PackageRegistry:
                 "files": []
             }
         }
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
     
     def get_package(self, name: str, version: str = "latest") -> Optional[Dict]:
-        """Get package metadata from registry"""
-        # Check built-in packages first
+        """Get package metadata from registry.
+
+        Resolution order:
+        1. Built-in packages
+        2. Local cache (``~/.zpm/cache/<name>-<version>.json``)
+        3. Remote registry (``GET /packages/<name>[/<version>]``)
+        """
+        # 1. Check built-in packages
         if name in self.builtin_packages:
             return self.builtin_packages[name]
         
-        # Check cache
+        # 2. Check local cache
         cache_file = self.cache_dir / f"{name}-{version}.json"
         if cache_file.exists():
             with open(cache_file) as f:
                 return json.load(f)
         
-        # TODO: Fetch from remote registry
-        # For now, return None if not found
+        # 3. Fetch from remote registry
+        try:
+            path = f"/packages/{urllib.parse.quote(name)}"
+            if version and version != "latest":
+                path += f"/{urllib.parse.quote(version)}"
+            meta = self._get_json(path)
+            if meta:
+                # Cache the result locally
+                self._cache_metadata(name, meta.get("version", version), meta)
+                return meta
+        except RegistryError as e:
+            # Log but don't crash — fall through to None
+            print(f"⚠️  Registry lookup failed for {name}: {e}")
+
         return None
     
     def search(self, query: str) -> List[Dict]:
-        """Search for packages"""
+        """Search for packages.
+
+        Searches built-in packages locally *and* queries the remote
+        registry via ``GET /search?q=<query>``.
+        """
         results = []
         
         # Search built-in packages
+        q = query.lower()
         for name, pkg in self.builtin_packages.items():
-            if query.lower() in name.lower() or query.lower() in pkg.get("description", "").lower():
+            if q in name.lower() or q in pkg.get("description", "").lower():
                 results.append(pkg)
         
-        # TODO: Search remote registry
+        # Search remote registry
+        try:
+            encoded = urllib.parse.urlencode({"q": query})
+            data = self._get_json(f"/search?{encoded}")
+            if data and isinstance(data.get("results"), list):
+                for pkg in data["results"]:
+                    # Deduplicate against builtins
+                    if pkg.get("name") not in self.builtin_packages:
+                        results.append(pkg)
+        except RegistryError as e:
+            print(f"⚠️  Remote search failed: {e}")
         
         return results
     
     def publish_package(self, package_data: Dict, files: List[str]) -> bool:
-        """Publish a package to registry"""
-        # For now, just cache locally
-        name = package_data["name"]
-        version = package_data["version"]
-        
-        cache_file = self.cache_dir / f"{name}-{version}.json"
-        with open(cache_file, "w") as f:
-            json.dump(package_data, f, indent=2)
-        
-        print(f"✅ Package cached locally at {cache_file}")
-        print(f"⚠️  Remote registry publication not yet implemented")
-        
-        # TODO: Upload to remote registry
-        return True
+        """Publish a package to the registry.
+
+        Sends a multipart POST to ``/packages`` with the package metadata
+        (JSON) and the tarball (binary).  Requires an auth token.
+        """
+        name = package_data.get("name", "")
+        version = package_data.get("version", "")
+
+        # Always cache locally first
+        self._cache_metadata(name, version, package_data)
+
+        # Attempt remote publish
+        if not self.auth_token:
+            print(f"⚠️  No auth token — package cached locally only.")
+            print(f"   Run 'zpm login <token>' to enable remote publishing.")
+            return True
+
+        tarball_path = package_data.get("tarball")
+        try:
+            import mimetypes
+            boundary = "----ZPMPublishBoundary"
+            body_parts = []
+
+            # Part 1: metadata JSON
+            body_parts.append(f"--{boundary}".encode())
+            body_parts.append(b'Content-Disposition: form-data; name="metadata"')
+            body_parts.append(b"Content-Type: application/json")
+            body_parts.append(b"")
+            body_parts.append(json.dumps(package_data).encode())
+
+            # Part 2: tarball file (if present)
+            if tarball_path and os.path.isfile(tarball_path):
+                body_parts.append(f"--{boundary}".encode())
+                body_parts.append(
+                    f'Content-Disposition: form-data; name="tarball"; '
+                    f'filename="{os.path.basename(tarball_path)}"'.encode()
+                )
+                body_parts.append(b"Content-Type: application/gzip")
+                body_parts.append(b"")
+                with open(tarball_path, "rb") as f:
+                    body_parts.append(f.read())
+
+            body_parts.append(f"--{boundary}--".encode())
+            body = b"\r\n".join(body_parts)
+
+            self._request(
+                "/packages",
+                method="POST",
+                data=body,
+                headers={"Content-Type": f"multipart/form-data; boundary={boundary}"},
+            )
+            print(f"✅ Published {name}@{version} to {self.registry_url}")
+            return True
+        except RegistryError as e:
+            print(f"❌ Remote publish failed: {e}")
+            print(f"   Package was cached locally at ~/.zpm/cache/")
+            return False
     
     def get_versions(self, package: str) -> List[str]:
-        """Get all available versions of a package"""
+        """Get all available versions of a package."""
         if package in self.builtin_packages:
             return [self.builtin_packages[package]["version"]]
         
-        # TODO: Query remote registry
+        # Check remote registry
+        try:
+            encoded = urllib.parse.quote(package)
+            data = self._get_json(f"/packages/{encoded}/versions")
+            if data and isinstance(data.get("versions"), list):
+                return data["versions"]
+        except RegistryError as e:
+            print(f"⚠️  Version lookup failed for {package}: {e}")
+        
         return []
+
+    def download_tarball(self, name: str, version: str) -> Optional[Path]:
+        """Download a package tarball from the registry.
+
+        Returns the local path to the downloaded ``.tar.gz`` file,
+        or ``None`` on failure.
+        """
+        tarball_cache = self.cache_dir / f"{name}-{version}.tar.gz"
+        if tarball_cache.exists():
+            return tarball_cache
+
+        try:
+            encoded_name = urllib.parse.quote(name)
+            encoded_ver = urllib.parse.quote(version)
+            body = self._request(f"/packages/{encoded_name}/{encoded_ver}/download")
+            if body is None:
+                return None
+            tarball_cache.write_bytes(body)
+            return tarball_cache
+        except RegistryError as e:
+            print(f"⚠️  Tarball download failed for {name}@{version}: {e}")
+            return None
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _cache_metadata(self, name: str, version: str, meta: Dict) -> None:
+        """Write package metadata to the local cache."""
+        cache_file = self.cache_dir / f"{name}-{version}.json"
+        with open(cache_file, "w") as f:
+            json.dump(meta, f, indent=2)