ixt-cli 0.8.0__py3-none-any.whl

ixt/core/export.py

@@ -0,0 +1,419 @@
+"""Generate ixt.toml from installed tools, preserving user install intent.
+
+Unlike the removed ``freeze`` command (which always force-pinned ``==X.Y.Z``),
+``export`` rebuilds each tool entry from ``ixt.json``, keeping the version
+constraint as the user originally wrote it at install time (range, pin, or no
+constraint). Extra fields (``asset_pattern`` for binary, ``node_shim`` and
+``runtime`` for node) are also preserved.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from ixt.config.asset_index import canonical_github_spec, platform_key
+from ixt.config.models import ToolRecord
+from ixt.config.settings import Settings, get_settings
+from ixt.config.toml import IxtConfig, ToolSpec, serialize_config
+from ixt.core.backend import BackendType
+from ixt.core.install import ToolNotInstalledError
+from ixt.core.save import tool_entry_key, tool_install_spec
+from ixt.net.source import parse_spec
+from ixt.platform import OS, Arch
+
+__all__ = [
+    "ToolNotInstalledError",
+    "export_asset_index",
+    "export_asset_index_json",
+    "export_config",
+    "export_toml",
+]
+
+
+def export_toml(
+    names: list[str] | None = None,
+    *,
+    settings: Settings | None = None,
+) -> str:
+    """Return a TOML string for the requested tools (all if *names* is None)."""
+    config = export_config(names, settings=settings)
+    return serialize_config(config)
+
+
+def export_config(
+    names: list[str] | None = None,
+    *,
+    settings: Settings | None = None,
+) -> IxtConfig:
+    """Build an IxtConfig from installed tools' metadata.
+
+    When *names* is given, only those tools are exported. Unknown names raise
+    ToolNotInstalledError. When *names* is None or empty, every installed tool
+    is exported.
+    """
+    settings = settings or get_settings()
+
+    records_by_name: dict[str, ToolRecord] = {}
+    for meta_file in settings.iter_installed_metadata():
+        record = ToolRecord.load_json(meta_file)
+        records_by_name[record.name] = record
+
+    if names:
+        selected: dict[str, ToolRecord] = {}
+        for name in names:
+            from ixt.core.install import resolve_tool_arg
+
+            tool_id = resolve_tool_arg(name, settings=settings)
+            if tool_id not in records_by_name:
+                raise ToolNotInstalledError(name)
+            selected[tool_id] = records_by_name[tool_id]
+    else:
+        selected = records_by_name
+
+    tools: dict[str, ToolSpec] = {}
+    for record in selected.values():
+        # Local installs (--from <path>) are not reproducible cross-machine.
+        if record.source == "local":
+            continue
+        spec = _record_to_spec(record, settings)
+        tools[spec.name] = spec
+
+    return IxtConfig(tools=tools)
+
+
+def export_asset_index(
+    *,
+    settings: Settings | None = None,
+    from_registry: Path | None = None,
+    all_platforms: bool = False,
+    warn: Callable[[str], None] | None = None,
+) -> dict[str, Any]:
+    """Return portable binary-resolution metadata from the local cache.
+
+    This exports metadata, not installed environments and not the user's
+    ``ixt.toml`` intent. It intentionally omits local cache paths.
+    """
+    settings = settings or get_settings()
+    if from_registry is not None:
+        return _asset_index_from_registry(
+            from_registry,
+            all_platforms=all_platforms,
+            warn=warn,
+        )
+    if all_platforms:
+        _warn(
+            warn,
+            "--all-platforms is ignored without --from-registry; "
+            "cache-based asset-index export only knows the current platform",
+        )
+    return _asset_index_from_cache(settings)
+
+
+def export_asset_index_json(
+    *,
+    settings: Settings | None = None,
+    from_registry: Path | None = None,
+    all_platforms: bool = False,
+    warn: Callable[[str], None] | None = None,
+) -> str:
+    """Return ``asset_index.json`` content for the local metadata cache."""
+    return (
+        json.dumps(
+            export_asset_index(
+                settings=settings,
+                from_registry=from_registry,
+                all_platforms=all_platforms,
+                warn=warn,
+            ),
+            indent=2,
+            sort_keys=True,
+        )
+        + "\n"
+    )
+
+
+# -- Internal helpers --------------------------------------------------------
+
+
+def _record_to_spec(record: ToolRecord, settings: Settings | None = None) -> ToolSpec:
+    """Convert a ToolRecord into a ToolSpec faithful to user install intent."""
+    settings = settings or get_settings()
+    name = _config_key_for_record(record)
+    version = _version_constraint(record)
+    asset_pattern = _read_asset_pattern(record) if record.backend == "binary" else None
+    runtime = _read_node_runtime(record) if record.backend == "node" else None
+    install = None
+    slot = _slot_for_record(record, name, settings)
+    if slot is not None:
+        name = slot
+        install = tool_install_spec(record.spec, BackendType(record.backend))
+
+    return ToolSpec(
+        name=name,
+        install=install,
+        version=version,
+        expose=list(record.expose_rules),
+        inject=list(record.injected),
+        node_shim=record.node_shim,
+        runtime=runtime,
+        asset_pattern=asset_pattern,
+        env_base=record.env_base,
+        env_allow=list(record.env_allow),
+        env_deny=dict(record.env_deny),
+        fs_base=record.fs_base,
+        fs_ro=list(record.fs_ro),
+        fs_rw=list(record.fs_rw),
+        fs_scratch=list(record.fs_scratch),
+    )
+
+
+def _config_key_for_record(record: ToolRecord) -> str:
+    """Return the canonical install-spec key to write in ``ixt.toml``."""
+    return tool_entry_key(record.name, record.spec, BackendType(record.backend))
+
+
+def _slot_for_record(record: ToolRecord, install_spec: str, settings: Settings) -> str | None:
+    from ixt.core.identity import slot_from_id
+    from ixt.core.install import plan_install
+
+    try:
+        base_id = plan_install(install_spec, settings=settings).tool_name
+    except Exception:
+        return None
+    return slot_from_id(record.name, base_id)
+
+
+def _version_constraint(record: ToolRecord) -> str | None:
+    """Extract the version constraint the user wrote at install time.
+
+    Returns None when the user didn't pin anything. The shape depends on the
+    backend: PEP 508 for python/node (``==0.5.0``, ``>=1.0``), plain-tag-with-``==``
+    for binary (``==14.1.0``).
+    """
+    spec = record.spec
+    if record.backend == "python":
+        from ixt.libs.req_spec import parse_requirement
+
+        try:
+            return parse_requirement(spec).version_constraint
+        except ValueError:
+            return None
+
+    if record.backend == "node":
+        from ixt.backends.node import parse_npm_spec
+
+        _name, version = parse_npm_spec(spec)
+        if not version:
+            return None
+        # npm version can already carry an operator (``^5.0``, ``~1.2``). Keep
+        # ixt.toml's PEP-508-ish convention: bare semver → prefix ``==``.
+        if version[0] in "^~><=*":
+            return version
+        return f"=={version}"
+
+    if record.backend == "binary":
+        from ixt.net.source import parse_spec as parse_repo_spec
+
+        repo = parse_repo_spec(spec)
+        if repo is None or not repo.version:
+            return None
+        return f"=={repo.version}"
+
+    return None
+
+
+def _read_asset_pattern(record: ToolRecord) -> str | None:
+    """Return the ``asset_pattern`` to export, if any.
+
+    Only forced patterns (``--asset-pattern`` CLI or ``ixt.setup.toml`` author)
+    are exported — patterns derived from the resolved asset name bake in
+    OS/arch and would break cross-machine ``apply``.
+    """
+    if not record.asset_pattern_forced:
+        return None
+    return record.asset_pattern if record.asset_pattern else None
+
+
+def _read_node_runtime(record: ToolRecord) -> str | None:
+    """Return the non-default node runtime to export, if any."""
+    from ixt.backends.node import read_metadata
+
+    data = read_metadata(Path(record.env_dir))
+    if data and data.get("runtime") == "node":
+        return "node"
+    return None
+
+
+def _load_asset_patterns(settings: Settings) -> dict[str, str]:
+    path = settings.metadata_dir / "asset_patterns.json"
+    try:
+        with path.open(encoding="utf-8") as f:
+            data = json.load(f)
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return {}
+    if not isinstance(data, dict):
+        return {}
+    return {k: v for k, v in data.items() if isinstance(k, str) and isinstance(v, str)}
+
+
+def _load_downloads(settings: Settings) -> list[dict[str, Any]]:
+    from ixt.core.cache import downloads_index_path
+
+    try:
+        with downloads_index_path(settings=settings).open(encoding="utf-8") as f:
+            data = json.load(f)
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return []
+    if not isinstance(data, dict):
+        return []
+    entries = data.get("entries", [])
+    if not isinstance(entries, list):
+        return []
+    return [
+        entry
+        for entry in entries
+        if isinstance(entry, dict) and entry.get("kind") == "binary-asset"
+    ]
+
+
+def _asset_index_from_cache(settings: Settings) -> dict[str, Any]:
+    result: dict[str, dict[str, Any]] = {}
+    key = platform_key()
+    patterns = _load_asset_patterns(settings)
+    for owner_repo, pattern in sorted(patterns.items()):
+        owner, sep, repo = owner_repo.partition("/")
+        if not sep or not owner or not repo:
+            continue
+        entry = _asset_index_entry(result, owner=owner, repo=repo)
+        entry.setdefault("patterns", {})[key] = pattern
+
+    downloads = sorted(
+        _load_downloads(settings),
+        key=lambda item: _str(item.get("downloaded_at")),
+    )
+    for download in downloads:
+        if download.get("platform") != "github" or download.get("host") != "github.com":
+            continue
+        owner = _str(download.get("owner"))
+        repo = _str(download.get("repo"))
+        tag = _str(download.get("tag"))
+        asset = _str(download.get("asset"))
+        if not owner or not repo or not tag or not asset:
+            continue
+        entry = _asset_index_entry(result, owner=owner, repo=repo)
+        entry.setdefault("assets", {})[key] = {
+            "tag": tag,
+            "asset": asset,
+            "url": _str(download.get("url")),
+        }
+    return _prune_empty_asset_index(result)
+
+
+def _asset_index_from_registry(
+    path: Path,
+    *,
+    all_platforms: bool,
+    warn: Callable[[str], None] | None,
+) -> dict[str, Any]:
+    from ixt.backends.binary import derive_asset_pattern, make_source
+    from ixt.config.heuristics import select_asset
+    from ixt.config.toml import _load_toml
+    from ixt.core.backend import strip_protocol
+
+    data = _load_toml(path)
+    tools = data.get("tools", {})
+    if not isinstance(tools, dict):
+        return {}
+
+    result: dict[str, dict[str, Any]] = {}
+    platforms = _export_platforms(all_platforms=all_platforms)
+    for name, raw_spec in sorted(tools.items()):
+        if not isinstance(name, str) or not isinstance(raw_spec, str):
+            continue
+        try:
+            _forced, clean_spec = strip_protocol(raw_spec)
+            repo_spec = parse_spec(clean_spec)
+            if repo_spec is None or repo_spec.platform != "github":
+                continue
+            canonical = canonical_github_spec(repo_spec)
+            if canonical is None:
+                continue
+            release = make_source(repo_spec).get_latest_release(repo_spec.owner, repo_spec.repo)
+            entry = result.setdefault(canonical, {"names": [], "patterns": {}})
+            if name not in entry["names"]:
+                entry["names"].append(name)
+            for os_value, arch_value in platforms:
+                key = platform_key(os_override=os_value, arch_override=arch_value)
+                asset = select_asset(
+                    release.assets,
+                    repo_spec.repo,
+                    release.tag.removeprefix("v"),
+                    os_override=os_value,
+                    arch_override=arch_value,
+                )
+                if asset is None:
+                    _warn(warn, f"{name}: no asset for {key} in {release.tag}")
+                    continue
+                pattern = derive_asset_pattern(asset.name, release.tag)
+                if pattern is None:
+                    _warn(warn, f"{name}: cannot derive pattern for {asset.name}")
+                    continue
+                entry["patterns"][key] = pattern
+        except Exception as exc:
+            _warn(warn, f"{name}: {type(exc).__name__}: {exc}")
+            continue
+
+    return _prune_empty_asset_index(result)
+
+
+def _asset_index_entry(
+    result: dict[str, dict[str, Any]],
+    *,
+    owner: str,
+    repo: str,
+) -> dict[str, Any]:
+    canonical = f"@gh:{owner}/{repo}"
+    return result.setdefault(canonical, {})
+
+
+def _prune_empty_asset_index(data: dict[str, dict[str, Any]]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for canonical, entry in sorted(data.items()):
+        cleaned: dict[str, Any] = {}
+        names = entry.get("names")
+        patterns = entry.get("patterns")
+        assets = entry.get("assets")
+        if isinstance(names, list) and names:
+            cleaned["names"] = sorted({name for name in names if isinstance(name, str)})
+        if isinstance(patterns, dict) and patterns:
+            cleaned["patterns"] = dict(sorted(patterns.items()))
+        if isinstance(assets, dict) and assets:
+            cleaned["assets"] = dict(sorted(assets.items()))
+        if "patterns" in cleaned or "assets" in cleaned:
+            result[canonical] = cleaned
+    return result
+
+
+def _export_platforms(*, all_platforms: bool) -> list[tuple[OS, Arch]]:
+    if not all_platforms:
+        from ixt.platform import get_arch, get_os
+
+        return [(get_os(), get_arch())]
+    return [
+        (OS.LINUX, Arch.X86_64),
+        (OS.LINUX, Arch.ARM64),
+        (OS.MACOS, Arch.X86_64),
+        (OS.MACOS, Arch.ARM64),
+    ]
+
+
+def _warn(warn: Callable[[str], None] | None, message: str) -> None:
+    if warn is not None:
+        warn(message)
+
+
+def _str(value: object) -> str:
+    return value if isinstance(value, str) else ""