xrefkit 0.7.7__tar.gz → 0.7.8__tar.gz

{xrefkit-0.7.7/xrefkit.egg-info → xrefkit-0.7.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xrefkit
-Version: 0.7.7
+Version: 0.7.8
 Summary: Portable XID, Skill, Knowledge, workflow, and MCP runtime for XRefKit
 Author: synthaicode
 License: MIT License

{xrefkit-0.7.7 → xrefkit-0.7.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "xrefkit"
-version = "0.7.7"
+version = "0.7.8"
 description = "Portable XID, Skill, Knowledge, workflow, and MCP runtime for XRefKit"
 readme = "README.md"
 requires-python = ">=3.11"

xrefkit-0.7.8/tests/test_package_knowledge_resolution.py

@@ -0,0 +1,166 @@
+from dataclasses import replace
+
+import pytest
+
+from xrefkit.discovery import DiscoveredSkillPackage
+from xrefkit.loaders import load_package_manifest
+from xrefkit.mcp.catalog import XRefCatalog
+
+
+def package_catalog(tmp_path, asset_path="knowledge/rules.md"):
+    import yaml
+    package_root = tmp_path / "package"
+    package_root.mkdir()
+    (package_root / "knowledge").mkdir()
+    (package_root / "knowledge/rules.md").write_text("# Package rules\n\nRequired rules.\n")
+    (package_root / "method.md").write_text("# Method\n")
+    manifest = package_root / "package_manifest.yaml"
+    manifest.write_text(yaml.safe_dump({
+        "package_id": "example.rules", "package_type": "skill_package", "version": "1.0.0",
+        "requires": {"xrefkit_core": ">=2.0.0 <3.0.0"},
+        "provides": {
+            "skills": [{"id": "example.review", "xid": "xid-skill-example", "path": "method.md"}],
+            "knowledge": [{"id": "rules", "xid": "xid-knowledge-rules", "path": asset_path}],
+        },
+        "contract": {},
+    }))
+    package = DiscoveredSkillPackage("example", package_root, manifest, load_package_manifest(manifest))
+    repo = tmp_path / "repo"
+    repo.mkdir()
+    return replace(XRefCatalog.build(repo), discovered_packages=(package,))
+
+
+def test_manifest_identity_resolves_without_inline_xid(tmp_path):
+    catalog = package_catalog(tmp_path)
+    document = catalog.get_document_by_xid("xid-knowledge-rules")
+    assert document["content"] == catalog.expand_knowledge("xid-knowledge-rules")["content"]
+    assert document["xid"] == "xid-knowledge-rules"
+    assert catalog.search_knowledge_catalog("Required rules")[0]["xid"] == "xid-knowledge-rules"
+    cached = catalog.get_document_by_xid("xid-knowledge-rules", document["content_hash"])
+    assert cached["content_hash"] == document["content_hash"]
+    assert cached["content_omitted"] == document["cache_policy"]["cache_recommended"]
+
+
+def test_duplicate_package_xid_refuses_selection(tmp_path):
+    catalog = package_catalog(tmp_path)
+    catalog = replace(catalog, discovered_packages=catalog.discovered_packages * 2)
+    assert catalog.get_document_by_xid("xid-knowledge-rules")["error"] == "xid_conflict"
+    with pytest.raises(ValueError, match="knowledge xid conflict"):
+        catalog.expand_knowledge("xid-knowledge-rules")
+
+
+def test_package_path_cannot_escape_root(tmp_path):
+    catalog = package_catalog(tmp_path, "../outside.md")
+    with pytest.raises(ValueError, match="escapes root"):
+        catalog.get_document_by_xid("xid-knowledge-rules")
+
+
+def installed_catalog(tmp_path, monkeypatch):
+    """Simulate entry-point installation, then use the real package discovery loader."""
+    import yaml
+    from types import SimpleNamespace
+    from xrefkit import discovery
+    catalog = package_catalog(tmp_path)
+    package = catalog.discovered_packages[0]
+    root = package.package_root
+    manifest = yaml.safe_load(package.manifest_path.read_text())
+    manifest["provides"]["skills"][0]["path"] = "method.skill.yaml"
+    manifest["provides"]["skills"][0]["required_knowledge"] = ["xid-knowledge-rules"]
+    manifest["provides"]["review_axes"] = [{"id": "axis", "xid": "xid-axis-rules", "path": "axis.yaml"}]
+    manifest["provides"]["schemas"] = [{"id": "schema", "xid": "xid-schema-rules", "path": "schema.json"}]
+    package.manifest_path.write_text(yaml.safe_dump(manifest))
+    (root / "method.skill.yaml").write_text(yaml.safe_dump({
+        "skill_id": "example.review", "xid": "xid-skill-example",
+        "entry": {"xid": "xid-entry-example", "path": "method.md", "load_policy": "required_inline"},
+        "required_outputs": ["report"], "required_knowledge": ["xid-knowledge-rules"],
+        "review_axes": ["xid-axis-rules"], "schemas": ["xid-schema-rules"],
+        "must_not": [], "extension_policy": {},
+    }))
+    (root / "axis.yaml").write_text("axis_id: example\nxid: xid-axis-rules\nchecks: []\n")
+    (root / "schema.json").write_text('{"type":"object"}\n')
+    ep = SimpleNamespace(name="example", load=lambda: lambda: root)
+    monkeypatch.setattr(discovery, "_select_entry_points", lambda group: [ep])
+    return XRefCatalog.build(catalog.repo_root, discover_packages=True)
+
+
+def test_discovered_required_knowledge_is_resolved_and_all_declared_assets_are_fetchable(tmp_path, monkeypatch):
+    catalog = installed_catalog(tmp_path, monkeypatch)
+    skill = catalog.get_skill("example.review")
+    assert skill["required_knowledge"] == [{"xid": "xid-knowledge-rules", "required": True, "reason": "package declaration"}]
+    resolved = catalog.resolve_skill_knowledge("example.review")
+    assert not resolved["unsatisfied_required"]
+    assert resolved["slots"][0]["bind"] == "xid-knowledge-rules"
+    assert resolved["slots"][0]["required"] is True and resolved["slots"][0]["satisfied"] is True
+    for xid in ("xid-knowledge-rules", "xid-axis-rules", "xid-schema-rules", "xid-entry-example", "xid-skill-example"):
+        assert catalog.get_document_by_xid(xid)["content"]
+    assert catalog.expand_knowledge("xid-knowledge-rules")["content"].startswith("# Package rules")
+
+
+def test_undeclared_file_is_not_exposed_and_absent_need_remains_unsatisfied(tmp_path, monkeypatch):
+    catalog = installed_catalog(tmp_path, monkeypatch)
+    package = catalog.discovered_packages[0]
+    (package.package_root / "secret.md").write_text("<!-- xid: ABCDEF123456 -->\n# Never declared")
+    with pytest.raises(KeyError):
+        catalog.get_document_by_xid("ABCDEF123456")
+    package.manifest.provides.knowledge.clear()
+    resolved = catalog.resolve_skill_knowledge("example.review")
+    assert resolved["unsatisfied_required"] == ["xid-knowledge-rules"]
+    assert resolved["slots"][0]["candidates"] == []
+    with pytest.raises(KeyError):
+        catalog.expand_knowledge("xid-knowledge-rules")
+
+
+def test_live_asset_changes_invalidate_catalog_and_document_cache(tmp_path, monkeypatch):
+    catalog = installed_catalog(tmp_path, monkeypatch)
+    path = catalog.discovered_packages[0].package_root / "axis.yaml"
+    before = catalog.catalog_version
+    document = catalog.get_document_by_xid("xid-axis-rules")
+    path.write_text(path.read_text() + "summary: revised\n")
+    current = catalog.get_document_by_xid("xid-axis-rules", document["content_hash"])
+    assert not current["content_omitted"]
+    assert current["content_hash"] != document["content_hash"]
+    assert catalog.catalog_version != before
+
+
+def test_duplicate_knowledge_cannot_silently_satisfy_required_slot(tmp_path, monkeypatch):
+    catalog = installed_catalog(tmp_path, monkeypatch)
+    (catalog.repo_root / "knowledge").mkdir()
+    (catalog.repo_root / "knowledge/local.md").write_text("<!-- xid: xid-knowledge-rules -->\n# Conflicting local rules")
+    with pytest.raises(ValueError, match="knowledge xid conflict"):
+        catalog.resolve_skill_knowledge("example.review")
+
+
+@pytest.mark.parametrize("relative", ["../outside.md", "/absolute.md", "C:/absolute.md", "knowledge/../rules.md", "knowledge\\rules.md"])
+def test_nonportable_or_escaping_declarations_refused(tmp_path, relative):
+    catalog = package_catalog(tmp_path, relative)
+    with pytest.raises(ValueError, match="package asset escapes root"):
+        catalog.get_document_by_xid("xid-knowledge-rules")
+
+
+def test_symlink_escape_is_not_exposed(tmp_path):
+    catalog = package_catalog(tmp_path)
+    outside = tmp_path / "outside.md"
+    outside.write_text("private outside content")
+    inside = catalog.discovered_packages[0].package_root / "knowledge/rules.md"
+    inside.unlink()
+    try:
+        inside.symlink_to(outside)
+    except OSError:
+        pytest.skip("symlink creation not available")
+    with pytest.raises(ValueError, match="escapes root"):
+        catalog.get_document_by_xid("xid-knowledge-rules")
+
+
+def test_package_cannot_shadow_embedded_startup_identity(tmp_path):
+    catalog = package_catalog(tmp_path)
+    catalog.discovered_packages[0].manifest.provides.knowledge[0].xid = "0B5C58B5E5B2"
+    with pytest.raises(ValueError, match="core startup XID"):
+        catalog.get_document_by_xid("0B5C58B5E5B2")
+
+
+def test_inline_identity_mismatch_refused(tmp_path):
+    catalog = package_catalog(tmp_path)
+    path = catalog.discovered_packages[0].package_root / "knowledge/rules.md"
+    path.write_text("<!-- xid: ABCDEF123456 -->\n# Wrong identity")
+    with pytest.raises(ValueError, match="identity does not match"):
+        catalog.expand_knowledge("xid-knowledge-rules")

{xrefkit-0.7.7 → xrefkit-0.7.8}/tests/test_package_skill_run.py

@@ -18,6 +18,13 @@ def test_installed_package_run_binds_over_mcp(tmp_path, module, reference, xid):
     from pathlib import Path
 
     pytest.importorskip(module)
+    from xrefkit.discovery import discover_skill_packages
+    package_id = reference.split("::")[0]
+    package = next(item for item in discover_skill_packages() if item.package_id == package_id)
+    package_knowledge_xids = [asset.xid for asset in package.manifest.provides.knowledge]
+    package_reference_xids = [asset.xid for asset in (
+        *package.manifest.provides.review_axes, *package.manifest.provides.schemas
+    )]
     anyio = pytest.importorskip("anyio")
     pytest.importorskip("mcp")
     from mcp.client.session import ClientSession
@@ -94,8 +101,30 @@ def test_installed_package_run_binds_over_mcp(tmp_path, module, reference, xid):
                     )
                     assert not requirements.isError, requirements.content
                     assert not requirements.structuredContent["missing"]
+                    for xid in package_knowledge_xids:
+                        document = await session.call_tool("get_document_by_xid", {"xid": xid})
+                        assert not document.isError, document.content
+                        expanded = await session.call_tool("expand_knowledge", {"xid": xid})
+                        assert not expanded.isError, expanded.content
+                        assert expanded.structuredContent["content"]
+
                     skill = await session.call_tool("get_skill", {"skill_id": run["skill_id"]})
                     assert not skill.isError, skill.content
                     assert skill.structuredContent["skill_id"] == run["skill_id"]
+                    for asset_xid in package_reference_xids:
+                        document = await session.call_tool("get_document_by_xid", {"xid": asset_xid})
+                        assert not document.isError, document.content
+                        assert document.structuredContent["content"]
+                    resolved = await session.call_tool(
+                        "resolve_skill_knowledge", {"skill_id": run["skill_id"]}
+                    )
+                    assert not resolved.isError, resolved.content
+                    required_xids = {need["xid"] for need in skill.structuredContent["required_knowledge"]}
+                    assert required_xids <= {slot["bind"] for slot in resolved.structuredContent["slots"]}
+                    for slot in resolved.structuredContent["slots"]:
+                        if slot["bind"] in package_knowledge_xids:
+                            assert slot["satisfied"]
+                        if not slot["satisfied"]:
+                            assert slot["slot"] in resolved.structuredContent["unsatisfied_required"]
 
     anyio.run(scenario)

{xrefkit-0.7.7 → xrefkit-0.7.8}/xrefkit/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.7.7"
+__version__ = "0.7.8"

{xrefkit-0.7.7 → xrefkit-0.7.8}/xrefkit/mcp/catalog.py

@@ -5,8 +5,9 @@ import io
 import json
 import re
 import zipfile
+from collections.abc import Iterator
 from dataclasses import dataclass, replace
-from pathlib import Path
+from pathlib import Path, PurePosixPath, PureWindowsPath
 
 from .contracts import builtin_tool_contracts
 from .legacy_migration import migration_context
@@ -683,14 +684,63 @@ class XRefCatalog:
                 for entry in self.skills
             ]
             + [
-                f"{package.package_id}{package.version}"
-                for package in self.discovered_packages
+                f"{package.package_id}{package.version}{xid}{stable_hash(read_text(path))}"
+                for package, xid, path, _kind in self._package_assets()
             ]
             + [tool.tool_id + tool.version for tool in self.tools]
             + ([self.ownership.content_hash] if self.ownership else [])
         )
         return stable_hash(version_basis)[:16]
 
+    def _package_assets(self) -> Iterator[tuple[DiscoveredSkillPackage, str, Path, str]]:
+        """Resolve only manifest-declared assets and split Skill references."""
+        for package in self.discovered_packages:
+            root = package.package_root.resolve()
+            seen = set()
+            provides = package.manifest.provides
+            groups = {
+                "knowledge": provides.knowledge,
+                "fragment": provides.fragments,
+                "review_axis": provides.review_axes,
+                "schema": provides.schemas,
+                "template": provides.templates,
+                "skill": provides.skills,
+            }
+            for kind, assets in groups.items():
+                for asset in assets:
+                    path = _package_asset_path(root, asset.path)
+                    if _embedded_startup_document(asset.xid) is not None:
+                        raise ValueError(f"package asset conflicts with core startup XID: {asset.xid}")
+                    key = (asset.xid, path)
+                    if key not in seen:
+                        seen.add(key)
+                        yield package, asset.xid, path, kind
+                    if kind == "skill" and path.suffix.lower() != ".md":
+                        skill = load_package_skill_definition(path)
+                        if skill.xid != asset.xid or skill.skill_id != asset.id:
+                            raise ValueError("package Skill identity does not match manifest")
+                        for fragment in [skill.entry, *skill.required_fragments, *skill.branches]:
+                            target = _package_asset_path(root, fragment.path)
+                            if _embedded_startup_document(fragment.xid) is not None:
+                                raise ValueError(f"package fragment conflicts with core startup XID: {fragment.xid}")
+                            key = (fragment.xid, target)
+                            if key not in seen:
+                                seen.add(key)
+                                yield package, fragment.xid, target, "fragment"
+
+    def _package_document(self, package: DiscoveredSkillPackage, xid: str, path: Path, text: str) -> XRefDocument:
+        if path.suffix.lower() == ".md" and first_xid(text) and first_xid(text) != xid:
+            raise ValueError(f"package document identity does not match manifest: {xid}")
+        return XRefDocument(
+            xid=xid,
+            title=first_heading(text, path.stem),
+            path=f"package:{package.package_id}/{path.relative_to(package.package_root.resolve()).as_posix()}",
+            summary=first_paragraph(text),
+            content=text,
+            links=markdown_xid_link_targets(text),
+            content_hash=stable_hash(text),
+        )
+
     def _scan_knowledge(self) -> list[tuple[KnowledgeCatalogEntry, str]]:
         """One consistent read per file: entry hash and body come from the
         same text, so they can never disagree."""
@@ -714,6 +764,17 @@ class XRefCatalog:
                 text = read_text(path)
                 if first_xid(text) not in known:
                     entries.append((_knowledge_entry(builtin_root, None, path, text), text))
+        for package, xid, path, kind in self._package_assets():
+            if kind != "knowledge":
+                continue
+            text = read_text(path)
+            entry = _knowledge_entry(package.package_root.resolve(), None, path, text)
+            document = self._package_document(package, xid, path, text)
+            entries.append((replace(
+                entry, xid=xid, path=document.path, missing=[],
+                zone_metadata={"source": "installed_skill_package", "package_id": package.package_id,
+                               "package_version": package.version},
+            ), text))
         return entries
 
     def get_repository_identity(self) -> dict[str, str]:
@@ -742,6 +803,7 @@ class XRefCatalog:
     def build_knowledge_context(self, query: str, limit: int = 5) -> dict:
         scanned = self._scan_knowledge()
         ranked = _rank_entries(query, [entry for entry, _text in scanned])[:limit]
+        _require_unique_knowledge([entry for entry, _ in scanned])
         by_xid = {entry.xid: (entry, text) for entry, text in scanned}
         expanded: list[dict] = []
         missing: list[dict] = []
@@ -899,6 +961,7 @@ class XRefCatalog:
         """
         entry = self._skill_by_id(skill_id)
         knowledge = self.knowledge
+        _require_unique_knowledge(knowledge)
         by_xid = {item.xid: item for item in knowledge}
         if entry.definition_format == "skill_definition_v1":
             needs = entry.knowledge_slots
@@ -1234,6 +1297,18 @@ class XRefCatalog:
             for local_xid, path in local_knowledge_files(self.repo_root)
             if local_xid == xid
         )
+        package_documents = {}
+        for package, asset_xid, path, _kind in self._package_assets():
+            if asset_xid == xid:
+                text = read_text(path)
+                matches.append((path, text))
+                package_documents[path] = self._package_document(package, xid, path, text)
+        if package_documents:
+            # Installed packages cannot shadow a core migration document merely
+            # because the consumer repository does not contain that document.
+            builtin_root = Path(__file__).resolve().parents[1] / "resources" / "migration"
+            if self.repo_root != builtin_root and builtin_root.is_dir():
+                matches.extend(_managed_markdown_matches_by_xid(builtin_root, None, xid))
         # An active local edit is an explicit overlay of its source document.
         # Suppress only the corresponding source path; unrelated documents
         # declaring the same XID remain a conflict.
@@ -1277,12 +1352,19 @@ class XRefCatalog:
                 "xid": xid,
                 "message": "multiple catalog-visible documents declare this XID; refusing path-order selection",
                 "matches": [
-                    _document_conflict_match(self.repo_root, self.ownership, path, text)
+                    ({"source": "installed_skill_package",
+                      "content_hash": package_documents[path].content_hash}
+                     if path in package_documents else
+                     _document_conflict_match(self.repo_root, self.ownership, path, text))
                     for path, text in matches
                 ],
             }
         if len(matches) == 1:
             path, text = matches[0]
+            if path in package_documents:
+                return _conditional_document_response(
+                    package_documents[path], known_version, self.repository_fingerprint,
+                )
             for entry in (self.skills if self.skill_definition_paths else []):
                 if (entry.definition_format == "skill_definition_v1"
                         and entry.package_id is None
@@ -1638,6 +1720,27 @@ def _knowledge_entry(
     )
 
 
+def _package_asset_path(root: Path, relative: str) -> Path:
+    """Manifest paths are portable relative allowlist entries, never glob roots."""
+    portable = PurePosixPath(relative)
+    if ("\\" in relative or ":" in relative or portable.is_absolute()
+            or PureWindowsPath(relative).drive or ".." in portable.parts
+            or portable.as_posix() != relative):
+        raise ValueError(f"package asset escapes root or is not a portable relative path: {relative}")
+    path = (root / relative).resolve()
+    if not path.is_relative_to(root):
+        raise ValueError(f"package asset escapes root: {relative}")
+    return path
+
+
+def _require_unique_knowledge(entries: list[KnowledgeCatalogEntry]) -> None:
+    seen: set[str] = set()
+    for entry in entries:
+        if entry.xid in seen:
+            raise ValueError(f"knowledge xid conflict: {entry.xid} appears in multiple catalog-visible knowledge entries")
+        seen.add(entry.xid)
+
+
 def _external_knowledge_entry(root: Path, path: Path, text: str) -> KnowledgeCatalogEntry:
     xid = first_xid(text)
     if not xid:
@@ -2400,14 +2503,16 @@ def _build_package_skills(package: DiscoveredSkillPackage) -> list[SkillCatalogE
             )
             continue
         skill = load_package_skill_definition(skill_path)
-        entry_path = package.package_root / skill.entry.path
+        if skill.xid != provided.xid or skill.skill_id != provided.id:
+            raise ValueError("package Skill identity does not match manifest")
+        entry_path = _package_asset_path(package_root, skill.entry.path)
         entry_text = read_text(entry_path) if entry_path.exists() else ""
         summary = first_paragraph(entry_text) or f"Package Skill {skill.skill_id}"
         rel_skill = skill_path.relative_to(package_root).as_posix()
         rel_entry = skill.entry.path.replace("\\", "/")
         required_knowledge = [
             {"xid": xid, "required": True, "reason": "package declaration"}
-            for xid in skill.required_knowledge
+            for xid in dict.fromkeys([*provided.required_knowledge, *skill.required_knowledge])
         ]
         entries.append(
             SkillCatalogEntry(
@@ -2443,7 +2548,8 @@ def _build_package_skills(package: DiscoveredSkillPackage) -> list[SkillCatalogE
                 ),
                 responsibility=skill.role or "package Skill execution",
                 preconditions=[],
-                knowledge_slots=[],
+                knowledge_slots=[{"slot": need["xid"], "bind": need["xid"], "required": True, "min": 1}
+                                 for need in required_knowledge],
                 missing=[],
                 zone_metadata={
                     "source": "installed_skill_package",

{xrefkit-0.7.7 → xrefkit-0.7.8/xrefkit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xrefkit
-Version: 0.7.7
+Version: 0.7.8
 Summary: Portable XID, Skill, Knowledge, workflow, and MCP runtime for XRefKit
 Author: synthaicode
 License: MIT License

{xrefkit-0.7.7 → xrefkit-0.7.8}/xrefkit.egg-info/SOURCES.txt

@@ -79,6 +79,7 @@ tests/test_os_family_definition.py
 tests/test_os_knowledge_family_definition.py
 tests/test_os_selected_family.py
 tests/test_ownership.py
+tests/test_package_knowledge_resolution.py
 tests/test_package_skill_run.py
 tests/test_packaged_native_governance.py
 tests/test_packmeta.py