macpkg-migrate-core 0.3.0__py3-none-any.whl

macpkg_migrate_core/__init__.py

@@ -0,0 +1,22 @@
+"""Lightweight shared planning and safety primitives for Mac package migration."""
+
+__version__ = "0.3.0"
+
+from .core import (
+    AUTOMATIC,
+    REVIEW,
+    Candidate,
+    Identity,
+    candidates_for,
+    choose_candidate,
+    dry_run,
+    install_allowed,
+    load_snapshot,
+    plan_record,
+)
+
+__all__ = [
+    "AUTOMATIC", "REVIEW", "Candidate", "Identity", "candidates_for",
+    "choose_candidate", "dry_run", "install_allowed", "load_snapshot",
+    "plan_record",
+]

macpkg_migrate_core/core.py

@@ -0,0 +1,177 @@
+"""Manager-neutral migration planning primitives.
+
+This package deliberately knows nothing about Homebrew, MacPorts, or Fink
+commands. It handles catalog records, candidate selection, plan records, and
+the shared safety policy used by manager-specific front ends.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any, Iterable, Mapping
+
+AUTOMATIC = "automatic"
+REVIEW = "needs-review"
+SAFE_STATUSES = frozenset({AUTOMATIC, "installed"})
+
+
+@dataclass(frozen=True)
+class Identity:
+    manager: str
+    package_type: str
+    native_name: str
+
+    @classmethod
+    def from_record(cls, record: Mapping[str, Any]) -> "Identity":
+        return cls(
+            record.get("manager", ""),
+            record.get("package_type", record.get("type", "")),
+            record.get("native_name", record.get("name", "")),
+        )
+
+    def as_dict(self) -> dict[str, str]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class Candidate:
+    target: Identity
+    relation_type: str
+    confidence: float
+    review_status: str
+    matching_method: str
+    evidence: tuple[Any, ...]
+    source_catalog_versions: Mapping[str, Any]
+
+    @classmethod
+    def from_relation(cls, relation: Mapping[str, Any]) -> "Candidate":
+        return cls(
+            target=Identity.from_record(relation.get("target", {})),
+            relation_type=relation.get("type", "equivalent"),
+            confidence=float(relation.get("confidence", 0)),
+            review_status=relation.get("review_status", REVIEW),
+            matching_method=relation.get("matching_method", "unknown"),
+            evidence=tuple(relation.get("evidence", ())),
+            source_catalog_versions=relation.get("source_catalog_versions", {}),
+        )
+
+    def as_dict(self) -> dict[str, Any]:
+        result = asdict(self)
+        result["target"] = self.target.as_dict()
+        result["evidence"] = list(self.evidence)
+        result["source_catalog_versions"] = dict(self.source_catalog_versions)
+        return result
+
+
+def load_snapshot(path: str | Path) -> dict[str, Any]:
+    """Load a catalog JSON snapshot or SQLite export without network access."""
+    path = Path(path)
+    if path.suffix in {".sqlite", ".db"}:
+        with sqlite3.connect(path) as connection:
+            packages = [dict(row) for row in connection.execute("SELECT * FROM packages")]
+            relations = [dict(row) for row in connection.execute("SELECT * FROM relations")]
+            metadata = {
+                key: json.loads(value)
+                for key, value in connection.execute("SELECT key, value FROM metadata")
+            } if _has_table(connection, "metadata") else {}
+        return {"packages": packages, "relations": relations, **metadata}
+    data = json.loads(path.read_text())
+    if isinstance(data, list):
+        return {"relations": data}
+    if not isinstance(data, dict):
+        raise ValueError("catalog snapshot must be a JSON object or relation array")
+    return data
+
+
+def _has_table(connection: sqlite3.Connection, name: str) -> bool:
+    return connection.execute(
+        "SELECT 1 FROM sqlite_master WHERE type='table' AND name=?", (name,)
+    ).fetchone() is not None
+
+
+def candidates_for(
+    relations: Iterable[Mapping[str, Any]], source: Identity
+) -> list[Candidate]:
+    """Return catalog candidates whose source exactly matches ``source``."""
+    candidates = []
+    for relation in relations:
+        if Identity.from_record(relation.get("source", {})) == source:
+            candidate = Candidate.from_relation(relation)
+            if candidate.target.native_name:
+                candidates.append(candidate)
+    return candidates
+
+
+def choose_candidate(
+    candidates: Iterable[Candidate], preference: Iterable[str] = ()
+) -> Candidate | None:
+    """Choose only an automatic candidate, never a review-only near-hit."""
+    preference = tuple(preference)
+    eligible = [candidate for candidate in candidates if candidate.review_status == AUTOMATIC]
+    eligible.sort(
+        key=lambda candidate: (
+            -candidate.confidence,
+            preference.index(candidate.target.manager)
+            if candidate.target.manager in preference else len(preference),
+            candidate.target.native_name,
+        )
+    )
+    return eligible[0] if eligible else None
+
+
+def plan_record(
+    source: Identity,
+    candidates: Iterable[Candidate],
+    catalog_version: str | None,
+    preference: Iterable[str] = (),
+) -> dict[str, Any]:
+    """Build a serializable, manager-neutral migration plan record."""
+    candidates = list(candidates)
+    chosen = choose_candidate(candidates, preference)
+    recommendation = None
+    if chosen:
+        recommendation = {
+            "manager": chosen.target.manager,
+            "type": chosen.target.package_type,
+            "name": chosen.target.native_name,
+            "confidence": chosen.confidence,
+            "status": chosen.review_status,
+            "method": chosen.matching_method,
+            "relation_type": chosen.relation_type,
+            "evidence": list(chosen.evidence),
+            "source_catalog_versions": dict(chosen.source_catalog_versions),
+            "review_status": chosen.review_status,
+            "target": chosen.target.as_dict(),
+        }
+    return {
+        "source": source.as_dict(),
+        "catalog_version": catalog_version,
+        "candidates": [candidate.as_dict() for candidate in candidates],
+        "recommendation": recommendation,
+        "action": "consolidate" if chosen else "review",
+        "install_authorized": bool(chosen),
+    }
+
+
+def install_allowed(record: Mapping[str, Any]) -> bool:
+    """Return whether shared policy permits unattended installation."""
+    recommendation = record.get("recommendation") or {}
+    return bool(
+        record.get("install_authorized")
+        and recommendation.get("review_status") == AUTOMATIC
+        and recommendation.get("target", {}).get("manager") in {"macports", "fink"}
+    )
+
+
+def dry_run(record: Mapping[str, Any]) -> dict[str, Any]:
+    """Return a safe preview result; this function never invokes a manager."""
+    return {
+        "source": record.get("source"),
+        "recommendation": record.get("recommendation"),
+        "would_install": install_allowed(record),
+        "would_remove": False,
+        "rollback": "No packages changed; discard the plan or uninstall only after explicit review.",
+    }

macpkg_migrate_core-0.3.0.dist-info/METADATA

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: macpkg-migrate-core
+Version: 0.3.0
+Summary: Manager-neutral planning and safety primitives for Mac package migration
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# macpkg-migrate-core
+
+Lightweight, manager-neutral planning and safety primitives shared by
+`brew2port`, `brew2fink`, and `macpkg-migrate`.
+
+The package handles catalog snapshot loading, exact candidate selection,
+review-only near-hit policy, serializable migration plan records, and the
+shared no-implicit-removal safety rule. It never invokes Homebrew, MacPorts,
+Fink, or any other package manager.
+
+The public API is available from `macpkg_migrate_core`:
+
+```python
+from macpkg_migrate_core import Identity, candidates_for, plan_record
+```
+
+Manager-specific applications retain inventory, target availability checks,
+installation, verification, rollback guidance, and user-facing workflows.
+
+Releases are published to PyPI from the `pypi` GitHub environment using
+trusted publishing. Configure `tomck/macpkg-migrate-core` as a trusted
+publisher on PyPI before publishing the first release.
+
+## First PyPI release
+
+Publishing uses PyPI Trusted Publishing through GitHub Actions; no API token,
+GPG key, or local signing setup is required. A repository administrator must
+first create the project on PyPI (or configure its pending publisher) with:
+
+- Owner: `tomck`
+- Repository: `macpkg-migrate-core`
+- Workflow: `publish.yml`
+- GitHub environment: `pypi`
+
+The workflow requests the required OIDC permission and publishes only when a
+GitHub Release is marked published. After the PyPI publisher is saved, create
+a GitHub Release for tag `v0.3.0`. The action builds and publishes the package
+without storing a PyPI credential in GitHub.
+
+After the workflow succeeds, verify the public installation in a clean
+environment:
+
+```sh
+python3 -m venv /tmp/macpkg-migrate-core-check
+. /tmp/macpkg-migrate-core-check/bin/activate
+python -m pip install --upgrade pip
+python -m pip install macpkg-migrate-core==0.3.0
+python -c 'import macpkg_migrate_core; print(macpkg_migrate_core.__version__)'
+```
+
+Update consumer lock/checksum or Homebrew formula metadata only after this
+clean installation succeeds.

macpkg_migrate_core-0.3.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+macpkg_migrate_core/__init__.py,sha256=ijknRgGKpJumoWQlVLTBaUb7moEAU8_ljY8GjP1mUr8,472
+macpkg_migrate_core/core.py,sha256=6pGwT1fKMOW1zLDj6cRtAzpMf-WyHq60LEV-dZrT7P8,6473
+macpkg_migrate_core-0.3.0.dist-info/METADATA,sha256=mNyjut4nDUcFOc8r9cQ9yXzACy63lEdOnw1vAaz8o-Q,2218
+macpkg_migrate_core-0.3.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+macpkg_migrate_core-0.3.0.dist-info/top_level.txt,sha256=SZoilNs4rcklCvmXXjqmVHZ_xVgFft9_SGnUzH2tsro,20
+macpkg_migrate_core-0.3.0.dist-info/RECORD,,

macpkg_migrate_core-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

macpkg_migrate_core-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+macpkg_migrate_core