xrefkit 0.5.1__tar.gz → 0.6.1__tar.gz

{xrefkit-0.5.1 → xrefkit-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xrefkit
-Version: 0.5.1
+Version: 0.6.1
 Summary: Portable XID, Skill, Knowledge, workflow, and MCP runtime for XRefKit
 Author: synthaicode
 License: MIT License
@@ -47,7 +47,7 @@ record evidence, preserve human judgment, and apply explicit completion checks.
 
 ## Why XRefKit?
 
-Experimental local tool: [Attention Pet](projects/attention-pet/README.md) helps
+Experimental local tool: [Attention Pet](projects/attention-pet/README.en.md) helps
 people assess capability sufficiency and lower inference-cost candidates separately.
 Its Model Fit / Cost Fit estimates use uncalibrated profiles; it does not measure internal
 attention or switch models automatically.
@@ -61,6 +61,11 @@ pet. It also shows lower inference-cost comparison candidates when the
 experimental profiles support one. The estimate is observational and does not
 change the Codex model, reasoning level, or chat.
 
+It does not measure token usage. It estimates the structural complexity of the
+work context the AI must handle, including retained items, dependencies,
+constraints, decision depth, conflicts, and dispersed evidence. It does not
+read model-internal attention or remaining context-window capacity.
+
 Run it from a Codex terminal in this repository so `CODEX_THREAD_ID` identifies
 the current chat:
 
@@ -77,7 +82,7 @@ This Codex preview is bound to the chat that launched it. Selecting another
 chat does not move the Pet automatically; launch it again from that chat when
 you want a separate view. The model and reasoning dropdowns only compare
 estimates and do not change the active Codex settings. See the
-[Attention Pet guide](projects/attention-pet/README.md) for interpretation,
+[Attention Pet guide](projects/attention-pet/README.en.md) for interpretation,
 limitations, client integration, and API details.
 
 Using AI for real work creates recurring operating problems:
@@ -151,6 +156,20 @@ This command starts the optional catalog and runtime MCP adapter. This checkout
 does not implement management upload, staging, sealing, review, or adoption of
 uploaded SkillDefinition bytes into the active catalog.
 
+To connect VS Code/Copilot, run from your target workspace:
+
+```powershell
+python -m pip install "xrefkit[mcp]"
+python -m xrefkit mcp setup --repo . --output .xrefkit/setup-review
+python -m xrefkit mcp setup apply --repo . --source .xrefkit/setup-review
+```
+
+Review the generated files before applying them, open the workspace in VS Code,
+and start the `xrefkit` MCP server. In Copilot chat, ask: "Call XRefKit's
+get_startup_context and help me get started." The AI receives any needed legacy
+migration guidance; you can describe your goal without specifying Skill names.
+Opening VS Code alone does not guarantee an AI conversation starts.
+
 ## Where to go next
 
 - [Install XRefKit and register Skill Packages](docs/guides/089_xrefkit_package_first_registration.md#xid-4F8C2A7D1E90)

{xrefkit-0.5.1 → xrefkit-0.6.1}/README.md

@@ -8,7 +8,7 @@ record evidence, preserve human judgment, and apply explicit completion checks.
 
 ## Why XRefKit?
 
-Experimental local tool: [Attention Pet](projects/attention-pet/README.md) helps
+Experimental local tool: [Attention Pet](projects/attention-pet/README.en.md) helps
 people assess capability sufficiency and lower inference-cost candidates separately.
 Its Model Fit / Cost Fit estimates use uncalibrated profiles; it does not measure internal
 attention or switch models automatically.
@@ -22,6 +22,11 @@ pet. It also shows lower inference-cost comparison candidates when the
 experimental profiles support one. The estimate is observational and does not
 change the Codex model, reasoning level, or chat.
 
+It does not measure token usage. It estimates the structural complexity of the
+work context the AI must handle, including retained items, dependencies,
+constraints, decision depth, conflicts, and dispersed evidence. It does not
+read model-internal attention or remaining context-window capacity.
+
 Run it from a Codex terminal in this repository so `CODEX_THREAD_ID` identifies
 the current chat:
 
@@ -38,7 +43,7 @@ This Codex preview is bound to the chat that launched it. Selecting another
 chat does not move the Pet automatically; launch it again from that chat when
 you want a separate view. The model and reasoning dropdowns only compare
 estimates and do not change the active Codex settings. See the
-[Attention Pet guide](projects/attention-pet/README.md) for interpretation,
+[Attention Pet guide](projects/attention-pet/README.en.md) for interpretation,
 limitations, client integration, and API details.
 
 Using AI for real work creates recurring operating problems:
@@ -112,6 +117,20 @@ This command starts the optional catalog and runtime MCP adapter. This checkout
 does not implement management upload, staging, sealing, review, or adoption of
 uploaded SkillDefinition bytes into the active catalog.
 
+To connect VS Code/Copilot, run from your target workspace:
+
+```powershell
+python -m pip install "xrefkit[mcp]"
+python -m xrefkit mcp setup --repo . --output .xrefkit/setup-review
+python -m xrefkit mcp setup apply --repo . --source .xrefkit/setup-review
+```
+
+Review the generated files before applying them, open the workspace in VS Code,
+and start the `xrefkit` MCP server. In Copilot chat, ask: "Call XRefKit's
+get_startup_context and help me get started." The AI receives any needed legacy
+migration guidance; you can describe your goal without specifying Skill names.
+Opening VS Code alone does not guarantee an AI conversation starts.
+
 ## Where to go next
 
 - [Install XRefKit and register Skill Packages](docs/guides/089_xrefkit_package_first_registration.md#xid-4F8C2A7D1E90)

{xrefkit-0.5.1 → xrefkit-0.6.1}/pyproject.toml

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

{xrefkit-0.5.1 → xrefkit-0.6.1}/tests/test_attention_pet_client_protocol.py

@@ -101,10 +101,16 @@ def test_handshake_authentication_and_active_session_switching(tmp_path):
             get("/api/state?lang=fr")
         assert error.value.code == 400
 
-        post("/api/active-session", payload("session-b", 2, 2))
-        second = get("/api/state")
+        next_session = payload("session-b", 2, 2)
+        next_session["model"] = "gpt-6-astra"
+        next_session["reasoning"] = "high"
+        post("/api/active-session", next_session)
+        second = get("/api/state?model=&reasoning=medium")
         assert second["source"]["sessionId"] == "session-b"
+        assert second["fit"]["selectedProfile"] == {"model": "astra", "reasoning": "high"}
         assert second["state"]["features"]["active_items"] == 2
+        manual_comparison = get("/api/state?model=sol&reasoning=medium")
+        assert manual_comparison["fit"]["selectedProfile"] == {"model": "sol", "reasoning": "medium"}
 
         with pytest.raises(HTTPError) as error:
             post("/api/active-session", payload("session-a", 1, 1))
@@ -116,6 +122,95 @@ def test_handshake_authentication_and_active_session_switching(tmp_path):
         thread.join(timeout=5)
 
 
+def test_state_response_keeps_one_session_when_activation_follows_snapshot(tmp_path, monkeypatch):
+    source = ClientStateSource(tmp_path / "sessions", Weights())
+    source.activate(ClientState.model_validate(payload("session-a", 1)))
+    next_session = payload("session-b", 2)
+    next_session["model"] = "gpt-6-astra"
+    next_session["reasoning"] = "high"
+    next_state = ClientState.model_validate(next_session)
+    original_snapshot = source.snapshot
+
+    def switch_after_snapshot(fallback_store):
+        snapshot = original_snapshot(fallback_store)
+        source.activate(next_state)
+        return snapshot
+
+    monkeypatch.setattr(source, "snapshot", switch_after_snapshot)
+    server, launch = make_server(Store(), source=source)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    try:
+        with urlopen(launch + "api/state?model=&reasoning=medium", timeout=5) as response:
+            before = json.load(response)
+        assert before["state"]["taskId"] == "task-session-a"
+        assert before["source"]["sessionId"] == "session-a"
+        assert before["fit"]["selectedProfile"] == {"model": "sol", "reasoning": "medium"}
+
+        monkeypatch.setattr(source, "snapshot", original_snapshot)
+        with urlopen(launch + "api/state?model=&reasoning=medium", timeout=5) as response:
+            after = json.load(response)
+        assert after["state"]["taskId"] == "task-session-b"
+        assert after["source"]["sessionId"] == "session-b"
+        assert after["fit"]["selectedProfile"] == {"model": "astra", "reasoning": "high"}
+    finally:
+        server.shutdown()
+        server.server_close()
+        thread.join(timeout=5)
+
+
+def test_client_snapshot_blocks_activation_until_all_session_fields_are_read(tmp_path, monkeypatch):
+    source = ClientStateSource(tmp_path / "sessions", Weights())
+    source.activate(ClientState.model_validate(payload("session-a", 1)))
+    next_session = payload("session-b", 2)
+    next_session["model"] = "gpt-6-astra"
+    next_session["reasoning"] = "high"
+    next_state = ClientState.model_validate(next_session)
+    view_read = threading.Event()
+    resume_view = threading.Event()
+    activation_started = threading.Event()
+    activation_done = threading.Event()
+    captured = {}
+    original_view = source.view
+
+    def pause_after_view(fallback_store):
+        result = original_view(fallback_store)
+        view_read.set()
+        assert resume_view.wait(timeout=5)
+        return result
+
+    def read_snapshot():
+        captured["snapshot"] = source.snapshot(Store())
+
+    def activate_next():
+        activation_started.set()
+        source.activate(next_state)
+        activation_done.set()
+
+    monkeypatch.setattr(source, "view", pause_after_view)
+    reader = threading.Thread(target=read_snapshot)
+    activator = threading.Thread(target=activate_next)
+    reader.start()
+    try:
+        assert view_read.wait(timeout=5)
+        activator.start()
+        assert activation_started.wait(timeout=5)
+        assert not activation_done.wait(timeout=0.1)
+    finally:
+        resume_view.set()
+        reader.join(timeout=5)
+        if activator.ident is not None:
+            activator.join(timeout=5)
+
+    assert not reader.is_alive() and not activator.is_alive()
+    result, selection, status = captured["snapshot"]
+    assert result["state"]["taskId"] == "task-session-a"
+    assert selection == ("sol", "medium")
+    assert status["sessionId"] == "session-a"
+    assert activation_done.is_set()
+    assert source.status()["sessionId"] == "session-b"
+
+
 def test_client_contract_rejects_mismatched_session_and_manual_mode(tmp_path):
     source = ClientStateSource(tmp_path / "sessions", Weights())
     server, launch = make_server(Store(), source=source)

{xrefkit-0.5.1 → xrefkit-0.6.1}/tests/test_attention_pet_codex_session.py

@@ -38,7 +38,7 @@ def test_one_bound_chat_updates_incrementally_without_saving_text(tmp_path):
     store = Store(saved)
     source.sync(store)
     first = store.view()
-    assert source.selection() == ("sol", "standard")
+    assert source.selection() == ("sol", "medium")
     assert source.status()["observedUserTurns"] == 1
     assert first["state"]["coverage"] == "partial"
     assert len(first["workingSet"]["items"]) == 1
@@ -55,7 +55,7 @@ def test_one_bound_chat_updates_incrementally_without_saving_text(tmp_path):
     assert "この修正は不要" not in saved.read_text(encoding="utf-8")
     append(log, "2026-09-26T12:00:03Z", "turn_context", {"model": "gpt-6-terra", "effort": "low"})
     source.sync(store)
-    assert source.selection() == ("terra", "light")
+    assert source.selection() == ("terra", "low")
     assert store.view() == second
     append(log, "2026-09-26T12:00:04Z", "turn_context", {"model": "unrecognized-model", "effort": "medium"})
     source.sync(store)
@@ -80,7 +80,7 @@ def test_live_api_defaults_to_observed_model_allows_comparison_and_rejects_mutat
         assert value["source"]["mode"] == "codex-chat"
         assert value["source"]["observedUserTurns"] == 1
         assert value["source"]["profile"] == "sol"
-        assert value["source"]["reasoning"] == "standard"
+        assert value["source"]["reasoning"] == "medium"
         assert value["fit"]["selected"]["model"] == "astra"
         assert value["fit"]["selected"]["reasoning"] == "high"
         with urlopen(Request(base + "/api/state?model=&reasoning=standard"), timeout=5) as response:

{xrefkit-0.5.1 → xrefkit-0.6.1}/tests/test_attention_pet_fit.py

@@ -16,6 +16,50 @@ from xrefkit.attention_pet.server import make_server
 from xrefkit.attention_pet.store import Store
 
 
+def test_execution_profile_search_crosses_models_and_efforts(monkeypatch):
+    # Controlled hypotheses make the two cross-axis cases independent of scenario thresholds.
+    state = {"ral": 50, "causes": [], "features": {"active_items": 1},
+             "coverage": "reviewed", "trajectoryEvidence": []}
+    for model, base in (("luna", 20), ("sol", 40)):
+        monkeypatch.setitem(PROFILES, model, PROFILES[model].model_copy(
+            update={"capability": Capability(reasoning=base, constraint_tracking=base,
+                                             evidence_handling=base)}))
+    for model in ("terra", "astra"):
+        monkeypatch.setitem(PROFILES, model, PROFILES[model].model_copy(
+            update={"relative_inference_cost": 100.0}))
+    result = evaluate_fit(state, "sol", "high")
+    assert result["modelFit"] == "Sufficient"
+    assert result["costFit"] == "LowerCostCandidateAvailable"
+    assert { (c["model"], c["reasoning"]) for c in result["lowerCostCandidates"] } >= {
+        ("luna", "xhigh"), ("sol", "medium")}
+    assert not next(c for c in result["alternatives"] if
+                    (c["model"], c["reasoning"]) == ("luna", "high"))["meetsRequirements"]
+    assert result["lowerCostCandidate"] == {"model": "sol", "reasoning": "medium"}
+    assert result["selectedProfile"] == {"model": "sol", "reasoning": "high"}
+    assert result["expectedTotalCost"] is None
+
+    underpowered = evaluate_fit(state, "sol", "low")
+    assert underpowered["modelFit"] == "Underpowered"
+    assert underpowered["costFit"] == "RetryRisk"
+    assert underpowered["lowerCostCandidate"] is None
+    assert underpowered["lowerCostCandidates"] == []
+
+
+def test_unknown_and_legacy_execution_profiles():
+    state = evaluate(task())
+    for model, reasoning in (("absent", "high"), ("sol", "absent"),
+                             ("terra", "xhigh")):
+        result = evaluate_fit(state, model, reasoning)
+        assert result["modelFit"] == result["costFit"] == "Unknown"
+        assert result["presentation"]["petState"] == "Unknown"
+    assert evaluate_fit(state, "sol", "light")["selected"]["reasoning"] == "light"
+    assert evaluate_fit(state, "sol", "standard")["selected"]["reasoning"] == "standard"
+    assert evaluate_fit(state, "sol", "light")["selectedProfile"] == {"model": "sol", "reasoning": "low"}
+    assert evaluate_fit(state, "sol", "standard")["selectedProfile"] == {"model": "sol", "reasoning": "medium"}
+    assert evaluate_fit(state, "sol", "standard")["selected"]["capability"] == \
+        evaluate_fit(state, "sol", "medium")["selected"]["capability"]
+
+
 def task(name="A", step=5):
     return WorkingSet.model_validate(scenario(name, step)["workingSet"])
 
@@ -70,10 +114,10 @@ def test_comparison_is_pure_and_total_cost_is_unknown():
     assert {r["baseRal"] for r in results} == {state["ral"]}
     for result in results:
         assert result["expectedTotalCost"] is None
-        assert all(result[k] is None for k in ("inferenceCost", "retryCost", "correctionCost", "failureRiskCost"))
+        assert all(result[k] is None for k in ("inferenceCost", "retryCost", "correctionCost", "latencyCost", "failureRiskCost"))
         assert result["calibration"] == "uncalibrated"
     assert results[0]["costFit"] == "RetryRisk"
-    assert results[1]["costFit"] == "NoLowerCostCandidate"
+    assert results[1]["costFit"] == "LowerCostCandidateAvailable"
     assert results[2]["costFit"] == "LowerCostCandidateAvailable"
 
 
@@ -121,9 +165,9 @@ def test_schema_matches_python_cost_fit_contract():
 
 
 @pytest.mark.parametrize("name,step,costs,faces", [
-    ("A", 5, ["NoLowerCostCandidate"] + ["LowerCostCandidateAvailable"] * 3, ["Balanced"] + ["Relaxed"] * 3),
-    ("B", 3, ["RetryRisk", "NoLowerCostCandidate", "LowerCostCandidateAvailable", "LowerCostCandidateAvailable"], ["Strained", "Balanced", "Relaxed", "Relaxed"]),
-    ("B", 5, ["RetryRisk"] * 3 + ["NoLowerCostCandidate"], ["Strained"] * 3 + ["Balanced"]),
+    ("A", 5, ["LowerCostCandidateAvailable"] * 4, ["Relaxed"] * 4),
+    ("B", 3, ["RetryRisk"] + ["LowerCostCandidateAvailable"] * 3, ["Strained"] + ["Relaxed"] * 3),
+    ("B", 5, ["RetryRisk"] * 3 + ["LowerCostCandidateAvailable"], ["Strained"] * 3 + ["Relaxed"]),
     ("D", 5, ["RetryRisk"] * 4, ["Strained"] * 4),
     ("C", 3, ["ReviewNeeded"] * 4, ["Review"] * 4),
 ])
@@ -141,11 +185,11 @@ def test_scenarios_separate_cost_and_presentation(name, step, costs, faces):
 
 def test_other_prices_do_not_change_model_fit(monkeypatch):
     state = evaluate(task())
-    before = evaluate_fit(state, "astra")
+    before = evaluate_fit(state, "astra", "low")
     assert before["costFit"] == "LowerCostCandidateAvailable"
     for name in ("luna", "terra", "sol"):
         monkeypatch.setitem(PROFILES, name, PROFILES[name].model_copy(update={"relative_inference_cost": 100.0}))
-    after = evaluate_fit(state, "astra")
+    after = evaluate_fit(state, "astra", "low")
     assert before["modelFit"] == after["modelFit"] == "Sufficient"
     assert after["costFit"] == "NoLowerCostCandidate"
     assert after["lowerCostCandidates"] == []
@@ -153,9 +197,9 @@ def test_other_prices_do_not_change_model_fit(monkeypatch):
 
 @pytest.mark.parametrize("name,step,model,status,target", [
     ("A", 5, "astra", "Available", "Luna"),
-    ("B", 3, "astra", "Available", "Terra"),
-    ("B", 3, "sol", "Available", "Terra"),
-    ("B", 3, "terra", "NoLowerCandidate", None),
+    ("B", 3, "astra", "Available", "Sol"),
+    ("B", 3, "sol", "Available", "Sol"),
+    ("B", 3, "terra", "Available", "Sol"),
     ("B", 3, "luna", "Underpowered", None),
     ("C", 3, "astra", "HoldForReview", None),
     ("D", 5, "astra", "Underpowered", None),
@@ -168,7 +212,7 @@ def test_lowest_sufficient_downgrade_guidance(name, step, model, status, target)
     if target:
         assert f"低コスト比較候補: {target}" in guide["modelGuide"]
         assert target in guide["modelGuideShort"]
-        assert "同じ考える深さ" in guide["modelGuide"]
+        assert " / " in guide["modelGuideShort"]
         assert "再試行・修正時間・失敗損失を含む総コストは未比較" in guide["modelGuideDetail"]
         assert "仮の必要能力3軸を満たす試算" in guide["modelGuideDetail"]
         lowest = min(fit["lowerCostCandidates"], key=lambda c: c["relativeInferenceCost"])
@@ -241,7 +285,7 @@ def test_english_presentation_preserves_evaluation_meaning():
     ("Unknown", "Unknown", "Unknown", "まだ評価できません", "情報が不足"),
     ("Underpowered", "RetryRisk", "Strained", "能力が不足する可能性", "一部を満たしていません"),
     ("Sufficient", "NoLowerCostCandidate", "Balanced", "必要な能力を満たす試算", "候補は確認されていません"),
-    ("Sufficient", "LowerCostCandidateAvailable", "Relaxed", "より低い推論コストの候補", "現在のモデルでも必要能力を満たす試算"),
+    ("Sufficient", "LowerCostCandidateAvailable", "Relaxed", "より低い推論コストの候補", "現在の実行プロファイルでも必要能力を満たす試算"),
     ("Sufficient", "ReviewNeeded", "Review", "実際の結果", "モデル能力だけを原因とは判断していません"),
     ("Underpowered", "ReviewNeeded", "Review", "実際の結果", "モデル能力だけを原因とは判断していません"),
 ])
@@ -309,6 +353,13 @@ def test_profiles_reject_invalid_costs(field, value):
         ModelProfile.model_validate(data)
 
 
+def test_profiles_reject_reasoning_without_depth_definition():
+    data = PROFILES["luna"].model_dump()
+    data["supported_reasoning"] = ("low", "ultra")
+    with pytest.raises(ValidationError, match="unsupported reasoning levels: ultra"):
+        ModelProfile.model_validate(data)
+
+
 def test_api_model_selection_is_read_only_and_invalid_queries_cannot_mutate():
     store = Store()
     before = store.submit(task("B", 3))
@@ -324,6 +375,12 @@ def test_api_model_selection_is_read_only_and_invalid_queries_cannot_mutate():
             return json.load(response)
 
     try:
+        catalog = request("/api/profiles")
+        assert next(p for p in catalog["models"] if p["id"] == "luna")["reasoning"] == [
+            "low", "medium", "high", "xhigh"]
+        assert catalog["legacyAliases"] == {"light": "low", "standard": "medium"}
+        unknown = request("/api/state?model=absent&reasoning=xhigh")
+        assert unknown["fit"]["modelFit"] == "Unknown"
         for model, expected in zip(PROFILES, ["Underpowered", "Sufficient", "Sufficient", "Sufficient"], strict=True):
             value = request(f"/api/state?model={model}&reasoning=standard")
             assert value["fit"]["modelFit"] == expected

xrefkit-0.6.1/tests/test_legacy_migration.py

@@ -0,0 +1,231 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+import subprocess
+import os
+from pathlib import Path
+
+import pytest
+
+from xrefkit.mcp.catalog import XRefCatalog
+from xrefkit.mcp.legacy_migration import (
+    STATE, dismiss_legacy_migration, import_legacy_assets, migration_context,
+    plan_legacy_migration, record_mcp_retrieval,
+)
+
+
+def legacy(tmp_path: Path) -> tuple[Path, Path]:
+    source, root = tmp_path / "legacy", tmp_path / "target"
+    root.mkdir()
+    (source / "skills" / "nested" / "review").mkdir(parents=True)
+    (source / "knowledge").mkdir()
+    (source / "skills" / "nested" / "review" / "SKILL.md").write_text(
+        "# Review\n\nUse [rules](../../../knowledge/rules.md).\n", encoding="utf-8")
+    (source / "knowledge" / "rules.md").write_text("# Rules\n\nKeep evidence.\n", encoding="utf-8")
+    (source / "knowledge" / "unlinked.txt").write_text("Independent knowledge.\n", encoding="utf-8")
+    return source, root
+
+
+def snapshot(root: Path) -> dict[str, bytes]:
+    return {p.relative_to(root).as_posix(): p.read_bytes() for p in root.rglob("*") if p.is_file()}
+
+
+def documents(root: Path) -> list[dict]:
+    data = json.loads((root / STATE).read_text(encoding="utf-8"))
+    catalog = XRefCatalog.build(root)
+    return [catalog.get_document_by_xid(a["xid"]) for unit in data["units"].values()
+            for a in unit.get("artifacts", []) if unit["status"] == "installed"]
+
+
+def test_first_partial_complete_restart_and_upgrade(tmp_path, monkeypatch):
+    source, root = legacy(tmp_path)
+    original = snapshot(source)
+    catalog = XRefCatalog.build(root)
+    first = catalog.get_startup_context()["legacy_migration"]
+    assert first["status"] == "not_started"
+    assert first["client_instructions"]
+    assert not (root / STATE).exists()
+    plan = plan_legacy_migration(root, str(source))
+    assert "knowledge/unlinked.txt" in plan["targets"]
+    assert "skills/nested/review" in plan["targets"]
+    assert not (root / STATE).exists()  # inventory has no write side effect
+    result = import_legacy_assets(root, str(source), plan["targets"])
+    assert result["ok"]
+    assert migration_context(root)["status"] == "in_progress"
+    bodies = documents(root)
+    # Catalog/CLI verification does not masquerade as an MCP retrieval.
+    assert migration_context(root)["status"] == "in_progress"
+    record_mcp_retrieval(root, bodies[:1])
+    remaining = migration_context(root)
+    assert remaining["status"] == "in_progress"
+    assert sum(len(u["retrievals"]) for u in remaining["remaining"]) < len(bodies)
+    record_mcp_retrieval(root, bodies)
+    completed = migration_context(root)
+    assert completed["status"] == "completed"
+    assert completed["client_instructions"] == []
+    assert completed["remaining"] == []
+    state = (root / STATE).read_bytes()
+    import xrefkit.mcp
+    monkeypatch.setattr(xrefkit.mcp, "__version__", "999.0.0")
+    restarted = XRefCatalog.build(root).get_startup_context({"irrelevant": "cached"})
+    assert restarted["legacy_migration"]["status"] == "completed"
+    assert (root / STATE).read_bytes() == state
+    assert snapshot(source) == original
+
+
+def test_explicit_scope_and_dismissal(tmp_path):
+    source, root = legacy(tmp_path)
+    assert dismiss_legacy_migration(root)["status"] == "not_required"
+    assert XRefCatalog.build(root).get_startup_context()["legacy_migration"]["client_instructions"] == []
+    result = import_legacy_assets(root, str(source), ["knowledge/unlinked.txt"])
+    assert result["ok"]
+    assert not (root / "skills").exists()
+    with pytest.raises(ValueError, match="cannot dismiss"):
+        dismiss_legacy_migration(root)
+    record_mcp_retrieval(root, documents(root))
+    assert migration_context(root)["status"] == "completed"
+
+
+def test_conflict_failure_retry_and_existing_assets_protected(tmp_path):
+    source, root = legacy(tmp_path)
+    protected = root / "skills" / "imported.nested_review" / "SKILL.md"
+    protected.parent.mkdir(parents=True)
+    protected.write_bytes(b"Existing customized skill\n")
+    result = import_legacy_assets(root, str(source), ["skills/nested/review", "knowledge/unlinked.txt"], prefix="imported")
+    assert not result["ok"]
+    remaining = migration_context(root)["remaining"]
+    assert remaining[0]["status"] == "failed"
+    assert "refusing to overwrite" in remaining[0]["error"]
+    assert protected.read_bytes() == b"Existing customized skill\n"
+    record_mcp_retrieval(root, documents(root))
+    assert [u["target"] for u in migration_context(root)["remaining"]] == ["skills/nested/review"]
+    # Simulate a user moving their customized file aside after reviewing conflict.
+    protected.rename(protected.with_suffix(".backup"))
+    assert import_legacy_assets(root, str(source), ["skills/nested/review"], prefix="imported")["ok"]
+    record_mcp_retrieval(root, documents(root))
+    assert migration_context(root)["status"] == "completed"
+    assert protected.with_suffix(".backup").read_bytes() == b"Existing customized skill\n"
+
+
+def test_partial_publish_retry_is_stable(tmp_path, monkeypatch):
+    source, root = legacy(tmp_path)
+    real_link = os.link
+    failed = False
+    def fail_once(source_path, destination, *args, **kwargs):
+        nonlocal failed
+        if Path(destination).name == "meta.md" and not failed:
+            failed = True
+            raise OSError("fixture disk failure")
+        return real_link(source_path, destination, *args, **kwargs)
+    monkeypatch.setattr(os, "link", fail_once)
+    assert not import_legacy_assets(root, str(source), ["skills/nested/review"])["ok"]
+    published = snapshot(root / "skills")
+    assert import_legacy_assets(root, str(source), ["skills/nested/review"])["ok"]
+    assert all(snapshot(root / "skills")[p] == b for p, b in published.items())
+    record_mcp_retrieval(root, documents(root))
+    assert migration_context(root)["status"] == "completed"
+
+
+def test_receipts_require_matching_body_identity_and_content(tmp_path):
+    source, root = legacy(tmp_path)
+    import_legacy_assets(root, str(source), ["knowledge/unlinked.txt"])
+    body = documents(root)[0]
+    for wrong in ({**body, "content": None}, {**body, "content": "wrong"},
+                  {**body, "path": "other.md"}, {**body, "xid": "wrong"}):
+        record_mcp_retrieval(root, [wrong])
+        assert migration_context(root)["status"] == "in_progress"
+    record_mcp_retrieval(root, [body])
+    assert migration_context(root)["status"] == "completed"
+    state = json.loads((root / STATE).read_text(encoding="utf-8"))
+    path = root / next(iter(state["units"].values()))["artifacts"][0]["path"]
+    path.write_text("Customized after migration", encoding="utf-8")
+    assert migration_context(root)["status"] == "in_progress"
+    assert not import_legacy_assets(root, str(source), ["knowledge/unlinked.txt"])["ok"]
+    assert path.read_text(encoding="utf-8") == "Customized after migration"
+
+
+def test_corrupt_state_and_overlap_are_not_reset(tmp_path):
+    source, root = legacy(tmp_path)
+    for bad in ("{", '{"schema_version": 999, "units": {}}'):
+        (root / STATE).parent.mkdir(exist_ok=True)
+        (root / STATE).write_text(bad, encoding="utf-8")
+        assert migration_context(root)["status"] == "blocked"
+        with pytest.raises(ValueError):
+            import_legacy_assets(root, str(source), ["knowledge/unlinked.txt"])
+        assert (root / STATE).read_text(encoding="utf-8") == bad
+    for overlap in (root, root.parent):
+        with pytest.raises(ValueError, match="non-overlapping"):
+            plan_legacy_migration(root, str(overlap))
+    with pytest.raises(ValueError, match="exact targets"):
+        import_legacy_assets(root, str(source), ["../escape"])
+
+
+def test_existing_xid_conflict_preserves_catalog_and_source(tmp_path):
+    source, root = legacy(tmp_path)
+    xid = "ABCDEF012345"
+    (source / "knowledge" / "rules.md").write_text(f"<!-- xid: {xid} -->\n# Legacy rules\n", encoding="utf-8")
+    existing = root / "knowledge" / "existing.md"
+    existing.parent.mkdir()
+    existing.write_text(f"<!-- xid: {xid} -->\n# Customized rules\n", encoding="utf-8")
+    before = snapshot(source)
+    result = import_legacy_assets(root, str(source), ["knowledge/rules.md"])
+    assert not result["ok"]
+    assert "XID conflict" in result["migration"]["remaining"][0]["error"]
+    assert XRefCatalog.build(root).get_document_by_xid(xid)["title"] == "Customized rules"
+    assert snapshot(source) == before
+
+
+def test_unsupported_skill_resources_are_reported_without_false_completion(tmp_path):
+    source, root = legacy(tmp_path)
+    (source / "skills/nested/review/helper.py").write_text("print('legacy')", encoding="utf-8")
+    plan = plan_legacy_migration(root, str(source))
+    assert "skills/nested/review/helper.py" in plan["unsupported"]
+    assert not import_legacy_assets(root, str(source), ["skills/nested/review"])["ok"]
+    assert migration_context(root)["status"] == "in_progress"
+    assert not (root / "skills").exists()
+
+
+def test_live_stdio_retrieval_and_restart(tmp_path):
+    pytest.importorskip("mcp")
+    from mcp.client.session import ClientSession
+    from mcp.client.stdio import StdioServerParameters, stdio_client
+    source, root = legacy(tmp_path)
+    original = snapshot(source)
+    params = StdioServerParameters(command=sys.executable,
+                                  args=["-m", "xrefkit", "mcp", "serve", "--repo", str(root)])
+    async def exercise():
+        async def call(session, tool, arguments=None):
+            result = await session.call_tool(tool, arguments or {})
+            assert not result.isError, result
+            return result.structuredContent or json.loads(result.content[0].text)
+        async with stdio_client(params) as (read, write):
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+                startup = await call(session, "get_startup_context")
+                assert startup["legacy_migration"]["status"] == "not_started"
+                plan = await call(session, "plan_legacy_migration", {"source": str(source)})
+                argv = [sys.executable, *plan["client_import_command"][1:]]
+                for target in plan["targets"]:
+                    argv.extend(["--target", target])
+                proc = await asyncio.to_thread(subprocess.run, argv, capture_output=True, text=True, check=False)
+                assert proc.returncode == 0, proc.stdout + proc.stderr
+                result = json.loads(proc.stdout)
+                assert result["ok"]
+                skill_id = result["converted_skills"][0]["skill_id"]
+                await call(session, "get_skill", {"skill_id": skill_id})
+                context = (await call(session, "get_startup_context"))["legacy_migration"]
+                assert context["status"] == "in_progress"
+                for unit in context["remaining"]:
+                    for pending in unit["retrievals"]:
+                        await call(session, "get_document_by_xid", {"xid": pending["xid"]})
+                assert (await call(session, "get_startup_context"))["legacy_migration"]["status"] == "completed"
+        async with stdio_client(params) as (read, write):
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+                context = (await call(session, "get_startup_context"))["legacy_migration"]
+                assert context["status"] == "completed"
+                assert not context["client_instructions"]
+    asyncio.run(exercise())
+    assert snapshot(source) == original

{xrefkit-0.5.1 → xrefkit-0.6.1}/xrefkit/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.5.1"
+__version__ = "0.6.1"