xrefkit 0.4.3__tar.gz → 0.4.5__tar.gz

{xrefkit-0.4.3 → xrefkit-0.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xrefkit
-Version: 0.4.3
+Version: 0.4.5
 Summary: Portable XID, Skill, Knowledge, workflow, and MCP runtime for XRefKit
 Author: synthaicode
 License: MIT License
@@ -101,6 +101,38 @@ and handoff records from collapsing into one opaque instruction block.
 
 ![XRefKit repository snapshot](human-docs/en/assets/xrefkit_repository_snapshot/xrefkit_repository_snapshot.png)
 
+## Skills: what you can ask XRefKit to do
+
+XRefKit includes Skills for common stages of software and business work. For
+example:
+
+- **Business discovery and planning**: `business_learning_interview`,
+  `business_intake_scoping`, `requirements_flow`, `planning_flow`, and
+  `estimation_flow`
+- **Investigation, design, and implementation**: `investigation_flow`,
+  `source_structure_overview`, `db_current_state_analysis`, `db_design`,
+  `design_flow`, and `implementation_flow`
+- **Constraint and change analysis**: `constraint_derivation_index`,
+  `dotnet_change_analysis`, `code_constraint_derivation`,
+  `cross_constraint_derivation`, and `integration_scenario_derivation`
+- **Review and quality**: `csharp_review`, `python_review`, `security_review`,
+  `test_flow`, `qa_gate_review`, and `review_report_composition`
+- **Knowledge and Skill operations**: `import_skill`, `skill_flow_authoring`,
+  `knowledge_ontology_management`, `judgment_log`, `doc_ship`, and
+  `skill_calibration_evaluation`
+- **Documents and communication**: `pptx_spec_traceability`,
+  `xlsx_spec_traceability`, `presentation_flow_review`, `editorial_intake`,
+  `draft_authoring`, and `marketing_slide_png`
+
+Each Skill is a reusable procedure with a capability/tuning/responsibility
+identity. Its procedure, routing metadata, domain Knowledge, and run evidence
+remain separate. Describe your goal in natural language and XRefKit routes it
+to the relevant Skill; the [Skill catalog](skills/_index.md#xid-8D91F66DDBB7)
+contains the complete current list and summaries.
+
+To install and enable Skills distributed as Python Packages, follow the
+[package-first registration guide](docs/guides/089_xrefkit_package_first_registration.md#xid-4F8C2A7D1E90).
+
 ## How It Works
 
 1. Original materials are kept in `sources/`.
@@ -126,7 +158,36 @@ reason instead of inventing a criterion.
 
 ## Quick Start
 
-Install the package and initialize an instance:
+### Install from PyPI
+
+XRefKit requires Python 3.11 or later. For a normal installation, create a
+virtual environment and install the published package from PyPI:
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+python -m pip install xrefkit
+xrefkit init
+xrefkit --help
+```
+
+If the `xrefkit` command is not available on `PATH`, use the module form:
+
+```powershell
+python -m xrefkit --help
+```
+
+To use the integrated MCP server, install the optional MCP dependencies:
+
+```powershell
+python -m pip install "xrefkit[mcp]"
+xrefkit mcp serve --repo . --transport stdio
+```
+
+### Install from a checkout
+
+For XRefKit development, install the local checkout in editable mode instead:
 
 ```powershell
 python -m pip install -e .
@@ -140,6 +201,25 @@ Start the integrated MCP server over stdio:
 xrefkit mcp serve --repo . --transport stdio
 ```
 
+To import existing Skills and prepare a reviewable VS Code MCP setup, run:
+
+```powershell
+python -m pip install "xrefkit[mcp]"
+xrefkit mcp setup `
+  --repo C:\dev\itsm\XRefKit `
+  --import C:\work\existing-skills
+```
+
+The command writes `SETUP.md`, `import-report.json`, a VS Code
+`.vscode/mcp.json` example, and reviewed append text for `AGENTS.md` and
+`CLAUDE.md` into a temporary setup folder. Apply those artifacts after review:
+
+```powershell
+xrefkit mcp setup apply `
+  --source C:\Users\<user>\AppData\Local\Temp\xrefkit-setup-<id> `
+  --repo C:\dev\itsm\XRefKit
+```
+
 The server writes structured correlation events to
 `work/mcp/xid_audit.jsonl` by default. After `xrefkit skill run` returns a
 `run_id`, the client calls MCP `bind_skill_run` and executes the returned
@@ -148,6 +228,18 @@ searches and XID resolutions then share the same `run_id` as the client Skill
 Run. The client separately records actual model-context loading and judgment
 application with `xrefkit skill knowledge --action load|apply`.
 
+For a network deployment without MCP protocol sessions, provide a shared HMAC
+secret and enable stateless HTTP. The client must return the `context_id` from
+`get_startup_context` in `_meta.io.xrefkit/context_id` on later requests:
+
+```powershell
+$env:XREFKIT_CONTEXT_SECRET = 'replace-with-a-managed-secret'
+python -m xrefkit.mcp.server --repo . --transport streamable-http --stateless-http
+```
+
+The context token is signed, repository-bound, and short-lived. It is an
+execution-context token, not a canonical XID or an authorization grant.
+
 ## Skill Run Observation Dashboard
 
 The local dashboard lets a human inspect Skill run status, closure and quality

{xrefkit-0.4.3 → xrefkit-0.4.5}/README.md

@@ -62,6 +62,38 @@ and handoff records from collapsing into one opaque instruction block.
 
 ![XRefKit repository snapshot](human-docs/en/assets/xrefkit_repository_snapshot/xrefkit_repository_snapshot.png)
 
+## Skills: what you can ask XRefKit to do
+
+XRefKit includes Skills for common stages of software and business work. For
+example:
+
+- **Business discovery and planning**: `business_learning_interview`,
+  `business_intake_scoping`, `requirements_flow`, `planning_flow`, and
+  `estimation_flow`
+- **Investigation, design, and implementation**: `investigation_flow`,
+  `source_structure_overview`, `db_current_state_analysis`, `db_design`,
+  `design_flow`, and `implementation_flow`
+- **Constraint and change analysis**: `constraint_derivation_index`,
+  `dotnet_change_analysis`, `code_constraint_derivation`,
+  `cross_constraint_derivation`, and `integration_scenario_derivation`
+- **Review and quality**: `csharp_review`, `python_review`, `security_review`,
+  `test_flow`, `qa_gate_review`, and `review_report_composition`
+- **Knowledge and Skill operations**: `import_skill`, `skill_flow_authoring`,
+  `knowledge_ontology_management`, `judgment_log`, `doc_ship`, and
+  `skill_calibration_evaluation`
+- **Documents and communication**: `pptx_spec_traceability`,
+  `xlsx_spec_traceability`, `presentation_flow_review`, `editorial_intake`,
+  `draft_authoring`, and `marketing_slide_png`
+
+Each Skill is a reusable procedure with a capability/tuning/responsibility
+identity. Its procedure, routing metadata, domain Knowledge, and run evidence
+remain separate. Describe your goal in natural language and XRefKit routes it
+to the relevant Skill; the [Skill catalog](skills/_index.md#xid-8D91F66DDBB7)
+contains the complete current list and summaries.
+
+To install and enable Skills distributed as Python Packages, follow the
+[package-first registration guide](docs/guides/089_xrefkit_package_first_registration.md#xid-4F8C2A7D1E90).
+
 ## How It Works
 
 1. Original materials are kept in `sources/`.
@@ -87,7 +119,36 @@ reason instead of inventing a criterion.
 
 ## Quick Start
 
-Install the package and initialize an instance:
+### Install from PyPI
+
+XRefKit requires Python 3.11 or later. For a normal installation, create a
+virtual environment and install the published package from PyPI:
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+python -m pip install xrefkit
+xrefkit init
+xrefkit --help
+```
+
+If the `xrefkit` command is not available on `PATH`, use the module form:
+
+```powershell
+python -m xrefkit --help
+```
+
+To use the integrated MCP server, install the optional MCP dependencies:
+
+```powershell
+python -m pip install "xrefkit[mcp]"
+xrefkit mcp serve --repo . --transport stdio
+```
+
+### Install from a checkout
+
+For XRefKit development, install the local checkout in editable mode instead:
 
 ```powershell
 python -m pip install -e .
@@ -101,6 +162,25 @@ Start the integrated MCP server over stdio:
 xrefkit mcp serve --repo . --transport stdio
 ```
 
+To import existing Skills and prepare a reviewable VS Code MCP setup, run:
+
+```powershell
+python -m pip install "xrefkit[mcp]"
+xrefkit mcp setup `
+  --repo C:\dev\itsm\XRefKit `
+  --import C:\work\existing-skills
+```
+
+The command writes `SETUP.md`, `import-report.json`, a VS Code
+`.vscode/mcp.json` example, and reviewed append text for `AGENTS.md` and
+`CLAUDE.md` into a temporary setup folder. Apply those artifacts after review:
+
+```powershell
+xrefkit mcp setup apply `
+  --source C:\Users\<user>\AppData\Local\Temp\xrefkit-setup-<id> `
+  --repo C:\dev\itsm\XRefKit
+```
+
 The server writes structured correlation events to
 `work/mcp/xid_audit.jsonl` by default. After `xrefkit skill run` returns a
 `run_id`, the client calls MCP `bind_skill_run` and executes the returned
@@ -109,6 +189,18 @@ searches and XID resolutions then share the same `run_id` as the client Skill
 Run. The client separately records actual model-context loading and judgment
 application with `xrefkit skill knowledge --action load|apply`.
 
+For a network deployment without MCP protocol sessions, provide a shared HMAC
+secret and enable stateless HTTP. The client must return the `context_id` from
+`get_startup_context` in `_meta.io.xrefkit/context_id` on later requests:
+
+```powershell
+$env:XREFKIT_CONTEXT_SECRET = 'replace-with-a-managed-secret'
+python -m xrefkit.mcp.server --repo . --transport streamable-http --stateless-http
+```
+
+The context token is signed, repository-bound, and short-lived. It is an
+execution-context token, not a canonical XID or an authorization grant.
+
 ## Skill Run Observation Dashboard
 
 The local dashboard lets a human inspect Skill run status, closure and quality

{xrefkit-0.4.3 → xrefkit-0.4.5}/pyproject.toml

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

xrefkit-0.4.5/tests/test_mcp_setup.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from xrefkit.__main__ import main
+
+
+def test_mcp_setup_writes_reviewable_workspace(tmp_path: Path, capsys) -> None:
+    output = tmp_path / "setup-output"
+    root = tmp_path / "repo"
+
+    assert main(["mcp", "setup", "--repo", str(root), "--output", str(output), "--json"]) == 0
+
+    payload = json.loads(capsys.readouterr().out)
+    assert payload["output"] == str(output.resolve())
+    assert (output / "SETUP.md").is_file()
+    assert (output / "vscode-mcp.json").is_file()
+    assert (output / "AGENTS.md.append.md").is_file()
+    assert (output / "CLAUDE.md.append.md").is_file()
+    assert (output / "import-report.json").is_file()
+
+    vscode = json.loads((output / "vscode-mcp.json").read_text(encoding="utf-8"))
+    server = vscode["servers"]["xrefkit"]
+    assert server["type"] == "stdio"
+    assert server["args"][-2:] == ["--transport", "stdio"]
+
+
+def test_mcp_setup_imports_existing_batch_skill_before_writing_report(tmp_path: Path, capsys) -> None:
+    source = tmp_path / "existing"
+    skill = source / "skills" / "legacy-review"
+    skill.mkdir(parents=True)
+    (skill / "SKILL.md").write_text("# Legacy Review\n\nReview the supplied change.\n", encoding="utf-8")
+    root = tmp_path / "repo"
+    output = tmp_path / "setup-output"
+
+    exit_code = main(
+        [
+            "mcp",
+            "setup",
+            "--repo",
+            str(root),
+            "--import",
+            str(source),
+            "--output",
+            str(output),
+            "--json",
+        ]
+    )
+    payload = json.loads(capsys.readouterr().out)
+    assert exit_code in {0, 1}
+    assert (root / "skills" / "imported.legacy-review" / "SKILL.md").is_file()
+    report = json.loads((output / "import-report.json").read_text(encoding="utf-8"))
+    assert report["import"]["converted_skills"][0]["skill_id"] == "imported.legacy-review"
+    assert payload["output"] == str(output.resolve())
+
+
+def test_mcp_setup_infers_single_skill_id_without_explicit_option(tmp_path: Path, capsys) -> None:
+    source = tmp_path / "existing-skill"
+    source.mkdir()
+    (source / "SKILL.md").write_text("# Existing Skill\n\nUse the supplied workflow.\n", encoding="utf-8")
+    root = tmp_path / "repo"
+    output = tmp_path / "setup-output"
+
+    exit_code = main(
+        [
+            "mcp",
+            "setup",
+            "--repo",
+            str(root),
+            "--import",
+            str(source),
+            "--output",
+            str(output),
+            "--json",
+        ]
+    )
+    payload = json.loads(capsys.readouterr().out)
+    assert exit_code in {0, 1}
+    assert (root / "skills" / "existing-skill" / "SKILL.md").is_file()
+    report = json.loads((output / "import-report.json").read_text(encoding="utf-8"))
+    assert report["import"]["skill_id"] == "existing-skill"
+    assert payload["output"] == str(output.resolve())
+
+
+def test_mcp_setup_defaults_repo_to_current_directory(tmp_path: Path, monkeypatch, capsys) -> None:
+    monkeypatch.chdir(tmp_path)
+    assert main(["mcp", "setup", "--json"]) == 0
+    payload = json.loads(capsys.readouterr().out)
+    assert payload["ok"] is True
+
+
+def test_mcp_setup_apply_copies_config_and_appends_instructions(tmp_path: Path, capsys) -> None:
+    output = tmp_path / "setup-output"
+    root = tmp_path / "repo"
+    root.mkdir()
+    assert main(["mcp", "setup", "--repo", str(root), "--output", str(output)]) == 0
+    capsys.readouterr()
+
+    assert main(["mcp", "setup-apply", "--source", str(output), "--repo", str(root)]) == 0
+    capsys.readouterr()
+    assert (root / ".vscode" / "mcp.json").is_file()
+    agents = (root / "AGENTS.md").read_text(encoding="utf-8")
+    assert "XRefKit MCP Skill Routing" in agents
+
+    assert main(["mcp", "setup-apply", "--source", str(output), "--repo", str(root)]) == 0
+    assert (root / "AGENTS.md").read_text(encoding="utf-8").count("XRefKit MCP Skill Routing") == 1

{xrefkit-0.4.3 → xrefkit-0.4.5}/xrefkit/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.4.3"
+__version__ = "0.4.5"

{xrefkit-0.4.3 → xrefkit-0.4.5}/xrefkit/mcp/__init__.py

@@ -11,6 +11,16 @@ def main(argv: list[str] | None = None) -> int:
     from .server import main as server_main
 
     args = list(argv or [])
+    if args and args[0] == "setup":
+        from .setup import main as setup_main
+
+        if len(args) > 1 and args[1] == "apply":
+            return setup_main(["setup-apply", *args[2:]])
+        return setup_main(args)
+    if args and args[0] == "setup-apply":
+        from .setup import main as setup_main
+
+        return setup_main(args)
     if args and args[0] == "serve":
         args = args[1:]
     return server_main(args)

{xrefkit-0.4.3 → xrefkit-0.4.5}/xrefkit/mcp/bootstrap.py

@@ -37,6 +37,7 @@ import sys
 import urllib.request
 import zipfile
 from pathlib import Path
+from urllib.parse import urlsplit
 
 
 DIST_STATE_RELATIVE_PATH = ".xrefkit/dist-state.json"
@@ -50,6 +51,12 @@ class BootstrapError(RuntimeError):
     pass
 
 
+def _validate_http_url(url: str) -> None:
+    parsed = urlsplit(url)
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        raise BootstrapError("bootstrap endpoints must use an absolute http(s) URL")
+
+
 def _ssl_context(ca_file: str | None) -> ssl.SSLContext:
     if ca_file:
         return ssl.create_default_context(cafile=ca_file)
@@ -57,8 +64,10 @@ def _ssl_context(ca_file: str | None) -> ssl.SSLContext:
 
 
 def http_get(url: str, ca_file: str | None = None, headers: dict[str, str] | None = None) -> bytes:
+    _validate_http_url(url)
     request = urllib.request.Request(url, headers=headers or {})
-    with urllib.request.urlopen(request, context=_ssl_context(ca_file)) as response:
+    # The URL scheme is validated above; B310 cannot infer that from Request.
+    with urllib.request.urlopen(request, context=_ssl_context(ca_file)) as response:  # nosec B310
         return response.read()
 
 
@@ -68,6 +77,7 @@ def http_post_json(
     ca_file: str | None = None,
     headers: dict[str, str] | None = None,
 ) -> tuple[bytes, dict[str, str]]:
+    _validate_http_url(url)
     request_headers = {
         "Content-Type": "application/json",
         "Accept": "application/json, text/event-stream",
@@ -79,7 +89,8 @@ def http_post_json(
         headers=request_headers,
         method="POST",
     )
-    with urllib.request.urlopen(request, context=_ssl_context(ca_file)) as response:
+    # The URL scheme is validated above; B310 cannot infer that from Request.
+    with urllib.request.urlopen(request, context=_ssl_context(ca_file)) as response:  # nosec B310
         return response.read(), {key.lower(): value for key, value in response.headers.items()}
 
 

xrefkit-0.4.5/xrefkit/mcp/context_token.py

@@ -0,0 +1,108 @@
+"""Signed, client-carried context for stateless MCP requests."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import time
+import uuid
+from dataclasses import dataclass
+from typing import Any
+
+
+CONTEXT_META_KEY = "io.xrefkit/context_id"
+
+
+@dataclass(frozen=True)
+class ContextClaims:
+    context_id: str
+    repository_fingerprint: str
+    startup_loaded: bool = False
+    client_tools_unlocked: bool = False
+    run_id: str | None = None
+    skill_id: str | None = None
+    mcp_session_id: str | None = None
+    expires_at: int = 0
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "context_id": self.context_id,
+            "repository_fingerprint": self.repository_fingerprint,
+            "startup_loaded": self.startup_loaded,
+            "client_tools_unlocked": self.client_tools_unlocked,
+            "run_id": self.run_id,
+            "skill_id": self.skill_id,
+            "mcp_session_id": self.mcp_session_id,
+            "expires_at": self.expires_at,
+        }
+
+
+class ContextTokenCodec:
+    def __init__(self, secret: str, repository_fingerprint: str, *, ttl_seconds: int = 3600) -> None:
+        if not secret:
+            raise ValueError("context token secret is required")
+        self._secret = secret.encode("utf-8")
+        self.repository_fingerprint = repository_fingerprint
+        self.ttl_seconds = ttl_seconds
+
+    def issue(
+        self,
+        *,
+        startup_loaded: bool = False,
+        client_tools_unlocked: bool = False,
+        run_id: str | None = None,
+        skill_id: str | None = None,
+        mcp_session_id: str | None = None,
+        context_id: str | None = None,
+    ) -> str:
+        claims = ContextClaims(
+            context_id=context_id or f"xc_{uuid.uuid4().hex}",
+            repository_fingerprint=self.repository_fingerprint,
+            startup_loaded=startup_loaded,
+            client_tools_unlocked=client_tools_unlocked,
+            run_id=run_id,
+            skill_id=skill_id,
+            mcp_session_id=mcp_session_id,
+            expires_at=int(time.time()) + self.ttl_seconds,
+        )
+        body = _encode(claims.to_dict())
+        return f"v1.{body}.{self._signature(body)}"
+
+    def verify(self, token: str) -> ContextClaims:
+        try:
+            version, body, signature = str(token).split(".", 2)
+            if version != "v1" or not hmac.compare_digest(signature, self._signature(body)):
+                raise ValueError("invalid context token signature")
+            payload = json.loads(_decode(body))
+            if payload["repository_fingerprint"] != self.repository_fingerprint:
+                raise ValueError("context token repository mismatch")
+            if int(payload["expires_at"]) < int(time.time()):
+                raise ValueError("context token expired")
+            return ContextClaims(**payload)
+        except (KeyError, TypeError, ValueError, json.JSONDecodeError) as exc:
+            raise ValueError("invalid context token") from exc
+
+    def refresh(self, claims: ContextClaims, **updates: Any) -> str:
+        values = claims.to_dict()
+        values.update(updates)
+        values.pop("context_id", None)
+        return self.issue(context_id=claims.context_id, **{k: values[k] for k in (
+            "startup_loaded", "client_tools_unlocked", "run_id", "skill_id", "mcp_session_id"
+        )})
+
+    def _signature(self, body: str) -> str:
+        return _b64(hmac.new(self._secret, body.encode("ascii"), hashlib.sha256).digest())
+
+
+def _b64(value: bytes) -> str:
+    return base64.urlsafe_b64encode(value).decode("ascii").rstrip("=")
+
+
+def _encode(value: dict[str, Any]) -> str:
+    return _b64(json.dumps(value, sort_keys=True, separators=(",", ":")).encode("utf-8"))
+
+
+def _decode(value: str) -> str:
+    return base64.urlsafe_b64decode(value + "=" * (-len(value) % 4)).decode("utf-8")