sin-code-bundle 0.9.2__py3-none-any.whl

sin_code_bundle/tools/pypi_setup.py

@@ -0,0 +1,289 @@
+# Purpose: One-click PyPI Trusted Publisher registration via API token.
+# Docs: pypi_setup.doc.md
+"""One-click PyPI Trusted Publisher setup via API token.
+
+Replaces the manual flow at https://pypi.org/manage/account/publishing/
+with a single CLI invocation. After setup, every `git tag v*` + `git push`
+auto-publishes to PyPI via GitHub Actions OIDC (no API token needed in CI).
+
+Docs: pypi_setup.doc.md
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+import urllib.error
+import urllib.request
+from typing import Any, Dict, Optional, Tuple
+
+PYPI_API = "https://pypi.org"
+PUBLISHER_ENDPOINT = f"{PYPI_API}/_/v1/publisher"
+FALLBACK_URL = "https://pypi.org/manage/account/publishing/"
+
+
+def normalise_project_name(name: str) -> str:
+    """Normalise a project name per PEP 503.
+
+    PyPI normalises project names to lowercase, replacing runs of
+    ``.``, ``_``, ``-`` with a single ``-``. The Trusted Publisher
+    registration endpoint requires the normalised form.
+    """
+    return re.sub(r"[-_.]+", "-", name).lower()
+
+
+def get_pending_publisher_payload(
+    project: str,
+    owner: str,
+    repo: str,
+    workflow: str,
+    environment: str,
+) -> Dict[str, Any]:
+    """Build the JSON payload for a new pending Trusted Publisher.
+
+    Args:
+        project: PyPI project name (normalised to PEP 503 form).
+        owner: GitHub owner (org or user). May be ``org`` or ``user/repo``.
+        repo: GitHub repository name.
+        workflow: Workflow filename (e.g. ``release.yml``).
+        environment: GitHub Actions environment name (e.g. ``pypi``).
+
+    Returns:
+        Dict matching the PyPI ``_/v1/publisher`` schema.
+    """
+    # The schema uses `repository_owner` for the GitHub login (org or user).
+    # If `owner` happens to contain a `/`, take the first segment — that's
+    # the GitHub login the rest of the payload already uses.
+    repo_owner = owner.split("/", 1)[0] if "/" in owner else owner
+    return {
+        "name": normalise_project_name(project),
+        "owner": repo_owner,
+        "repository": repo,
+        "workflow_filename": workflow,
+        "environment": environment,
+    }
+
+
+def add_pending_publisher(
+    api_token: str,
+    payload: Dict[str, Any],
+    *,
+    timeout: float = 15.0,
+    base_url: str = PYPI_API,
+) -> Tuple[bool, str]:
+    """POST a pending-publisher registration to PyPI.
+
+    Args:
+        api_token: PyPI API token (format: ``pypi-...``). NOT a password.
+        payload: The dict produced by :func:`get_pending_publisher_payload`.
+        timeout: HTTP timeout in seconds.
+        base_url: Override the PyPI base URL (for test fixtures).
+
+    Returns:
+        Tuple ``(success, message)``. ``success`` is ``True`` only when
+        PyPI returns HTTP 201. The ``message`` is a human-readable
+        description suitable for printing to a terminal.
+    """
+    url = f"{base_url}/_/v1/publisher"
+    body = json.dumps(payload).encode("utf-8")
+    req = urllib.request.Request(
+        url,
+        data=body,
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Token {api_token}",
+        },
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            status = resp.status
+            text = resp.read().decode("utf-8", errors="replace")
+            if status == 201:
+                return True, (
+                    "Pending publisher created. PyPI emailed the maintainer "
+                    "at the account email. Click the magic link to confirm."
+                )
+            return False, f"PyPI returned HTTP {status}: {text}"
+    except urllib.error.HTTPError as e:
+        # The error body often carries machine-readable details. We surface
+        # both the status and the body so the maintainer can diagnose
+        # without re-running the request.
+        err_body = e.read().decode("utf-8", errors="replace")
+        return False, f"HTTP {e.code}: {err_body}"
+    except urllib.error.URLError as e:
+        return False, f"Network error: {e.reason}"
+    except TimeoutError:
+        return False, f"Request timed out after {timeout}s."
+    except Exception as e:  # pragma: no cover — defensive
+        return False, f"Unexpected error: {e}"
+
+
+def build_argparser() -> argparse.ArgumentParser:
+    """Construct the CLI argument parser.
+
+    Kept as a separate function so tests can introspect / invoke it
+    without spawning the full ``main()`` flow.
+    """
+    parser = argparse.ArgumentParser(
+        prog="python -m sin_code_bundle.tools.pypi_setup",
+        description=(
+            "One-click PyPI Trusted Publisher setup for "
+            "OpenSIN-Code/SIN-Code-Bundle (tokenless OIDC publishing)."
+        ),
+    )
+    parser.add_argument(
+        "--project",
+        default="sin-code-bundle",
+        help="PyPI project name (default: %(default)s)",
+    )
+    parser.add_argument(
+        "--owner",
+        default="OpenSIN-Code",
+        help="GitHub owner/org (default: %(default)s)",
+    )
+    parser.add_argument(
+        "--repo",
+        default="SIN-Code-Bundle",
+        help="GitHub repository name (default: %(default)s)",
+    )
+    parser.add_argument(
+        "--workflow",
+        default="release.yml",
+        help="GitHub Actions workflow filename (default: %(default)s)",
+    )
+    parser.add_argument(
+        "--environment",
+        default="pypi",
+        help="GitHub Actions environment name (default: %(default)s)",
+    )
+    parser.add_argument(
+        "--api-token",
+        required=True,
+        help="PyPI API token (format: pypi-...). NOT a password.",
+    )
+    parser.add_argument(
+        "--timeout",
+        type=float,
+        default=15.0,
+        help="HTTP timeout in seconds (default: %(default)s)",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print the payload that would be sent, then exit 0.",
+    )
+    parser.add_argument(
+        "--json",
+        dest="as_json",
+        action="store_true",
+        help="Emit the result as a single JSON line (for piping).",
+    )
+    return parser
+
+
+def _print_human(
+    project: str,
+    owner: str,
+    repo: str,
+    workflow: str,
+    environment: str,
+    payload: Dict[str, Any],
+    result: Tuple[bool, str],
+) -> None:
+    """Pretty-print the result to stdout/stderr for human operators."""
+    out = sys.stdout
+    print("=== PyPI Trusted Publisher setup ===", file=out)
+    print(f"Project:    {project}", file=out)
+    print(f"Owner:      {owner}", file=out)
+    print(f"Repository: {repo}", file=out)
+    print(f"Workflow:   {workflow}", file=out)
+    print(f"Environment: {environment}", file=out)
+    print("", file=out)
+    print("Payload:", file=out)
+    print(json.dumps(payload, indent=2), file=out)
+    print("", file=out)
+
+    success, message = result
+    if success:
+        print(f"OK  {message}", file=out)
+        print("", file=out)
+        print("Next steps:", file=out)
+        print("  1. Check the email registered on the PyPI account.", file=out)
+        print("  2. Click the magic link PyPI sent.", file=out)
+        print(
+            "  3. From now on, every `git tag v*.*.* && git push origin v*.*.*` in",
+            file=out,
+        )
+        print(
+            f"     {owner}/{repo} auto-publishes to PyPI in ~30s.",
+            file=out,
+        )
+    else:
+        print(f"FAIL  {message}", file=sys.stderr)
+        print("", file=sys.stderr)
+        print("Manual fallback:", file=sys.stderr)
+        print(f"  1. Open {FALLBACK_URL}", file=sys.stderr)
+        print("  2. Click 'Add a new pending publisher'.", file=sys.stderr)
+        print(f"  3. Project name:        {project}", file=sys.stderr)
+        print(f"  4. Owner:               {owner}", file=sys.stderr)
+        print(f"  5. Repository name:     {repo}", file=sys.stderr)
+        print(f"  6. Workflow filename:   {workflow}", file=sys.stderr)
+        print(f"  7. Environment name:    {environment}", file=sys.stderr)
+
+
+def main(argv: Optional[list] = None) -> int:
+    """CLI entry point.
+
+    Args:
+        argv: Optional argument list (defaults to ``sys.argv[1:]``).
+
+    Returns:
+        Process exit code — ``0`` on success, ``1`` on any failure.
+    """
+    args = build_argparser().parse_args(argv)
+    payload = get_pending_publisher_payload(
+        args.project,
+        args.owner,
+        args.repo,
+        args.workflow,
+        args.environment,
+    )
+
+    if args.dry_run:
+        if args.as_json:
+            print(json.dumps({"dry_run": True, "payload": payload}))
+        else:
+            print(json.dumps(payload, indent=2))
+        return 0
+
+    result = add_pending_publisher(args.api_token, payload, timeout=args.timeout)
+
+    if args.as_json:
+        print(
+            json.dumps(
+                {
+                    "success": result[0],
+                    "message": result[1],
+                    "payload": payload,
+                }
+            )
+        )
+    else:
+        _print_human(
+            args.project,
+            args.owner,
+            args.repo,
+            args.workflow,
+            args.environment,
+            payload,
+            result,
+        )
+
+    return 0 if result[0] else 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

sin_code_bundle/vfs.py

@@ -0,0 +1,264 @@
+# SPDX-License-Identifier: MIT
+"""Purpose: Virtual Filesystem Layer (URI Schemes) for SIN-Code v2.
+
+Docs: vfs.doc.md
+
+Exposes semantic tools as URI schemes for any MCP client:
+    sckg://module/<name>/dependencies  -> SCKG graph query
+    sckg://module/<name>/callers       -> SCKG reverse lookup
+    sckg://module/<name>/neighbors     -> SCKG neighbors
+    poc://strategy/<name>              -> POC strategy list
+    ibd://diff/<file>                  -> IBD parse file
+    adw://smell/<name>                 -> ADW smell analyzer
+    efsm://service/<name>              -> EFSM mock service
+    oracle://strategy/<name>           -> Oracle verifier
+    conflict://<id>                    -> Git conflict interface
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+URI_SCHEMES = {
+    "sckg": "Semantic Codebase Knowledge Graph",
+    "poc": "Proof of Correctness",
+    "ibd": "Intent-Based Semantic Diff",
+    "adw": "Architectural Debt Watchdog",
+    "efsm": "Ephemeral Full-Stack Mock",
+    "oracle": "Verification Oracle",
+    "conflict": "Merge Conflict Resolution",
+}
+
+
+# ── SINVirtualFS: URI Dispatcher + Resolvers ───────────────────────────────
+class SINVirtualFS:
+    """Resolves SIN-specific URI schemes.
+
+    Usage:
+        vfs = SINVirtualFS(Path("/path/to/repo"))
+        result = vfs.resolve("sckg://module/auth/dependencies")
+    """
+
+    def __init__(self, repo_root: Optional[Path] = None):
+        self.repo_root = repo_root or Path.cwd()
+        # _cache avoids recomputing expensive SCKG queries on repeated
+        # resolve() calls (e.g. when an agent re-reads the same module
+        # graph mid-session). Bounded only by session lifetime — fine
+        # for our short-lived agent processes.
+        self._cache: Dict[str, Any] = {}
+
+    def resolve(self, uri: str) -> Dict[str, Any]:
+        """Resolve a SIN URI to structured content."""
+        # URI grammar per RFC 3986-ish: `scheme://path`. \w+ matches
+        # `[A-Za-z0-9_]+` which covers all our scheme names (sckg, poc,
+        # ibd, adw, efsm, oracle, conflict) and rejects whitespace,
+        # colons, and other URI-illegal chars early.
+        match = re.match(r"^(\w+)://(.+)$", uri)
+        if not match:
+            return {"error": f"Invalid URI format: {uri}"}
+        scheme, path = match.group(1), match.group(2)
+
+        cache_key = f"{scheme}://{path}"
+        if cache_key in self._cache:
+            return self._cache[cache_key]
+
+        handler = getattr(self, f"_resolve_{scheme}", None)
+        if not handler:
+            return {"error": f"Unknown scheme: {scheme}"}
+        result = handler(path)
+        self._cache[cache_key] = result
+        return result
+
+    def list_schemes(self) -> Dict[str, str]:
+        """List all available URI schemes."""
+        return dict(URI_SCHEMES)
+
+    # ── SCKG resolver (uses REAL KnowledgeGraph API) ─────────────────
+    def _resolve_sckg(self, path: str) -> Dict[str, Any]:
+        parts = path.split("/")
+        if len(parts) < 2 or parts[0] != "module":
+            return {"error": "Use sckg://module/<name>/<query_type>"}
+        module_name = parts[1]
+        query_type = parts[2] if len(parts) > 2 else "neighbors"
+        # try/except around every resolver = graceful degradation:
+        # if one subsystem breaks or is missing, the others still resolve.
+        try:
+            from sin_code_sckg import KnowledgeGraph
+
+            kg = KnowledgeGraph(str(self.repo_root))
+            kg.build_from_repo()
+            node_id = "module:" + module_name
+            result_data = {
+                "module": module_name,
+                "query_type": query_type,
+            }
+            if query_type == "neighbors":
+                result_data["data"] = [str(n) for n in kg.get_neighbors(node_id)]
+            elif query_type == "overview":
+                result_data["data"] = kg.to_dict()
+            else:
+                result_data["data"] = kg.query(
+                    f"MATCH (n:Module) WHERE n.name='{module_name}' RETURN n"
+                )
+            return {"type": "sckg_module", **result_data}
+        except ImportError:
+            return {"error": "SCKG not installed (pip install sin-code-sckg)"}
+        except Exception as e:
+            return {"error": f"SCKG error: {e}"}
+
+    # ── POC resolver (uses REAL POC API) ─────────────────────────────
+    def _resolve_poc(self, path: str) -> Dict[str, Any]:
+        parts = path.split("/")
+        if len(parts) < 2:
+            return {"error": "Use poc://strategy/<name>"}
+        strategy_name = parts[1]
+        # try/except around every resolver = graceful degradation:
+        # if one subsystem breaks or is missing, the others still resolve.
+        try:
+            from sin_code_poc import list_properties, property_metadata  # noqa: F401
+
+            # Use the property registry for strategy listing
+            props = property_metadata() if callable(property_metadata) else {}
+            # [:50] limits blast radius — not the whole catalog — so the
+            # response stays LLM-prompt-friendly (POC has hundreds of
+            # properties, we only need a discoverable subset here).
+            return {
+                "type": "poc_strategy",
+                "strategy": strategy_name,
+                "available_properties": list(props.keys())[:50] if isinstance(props, dict) else [],
+                "note": f"Run: sin poc verify --strategy={strategy_name} <file>",
+            }
+        except ImportError:
+            return {"error": "POC not installed"}
+
+    # ── IBD resolver (uses REAL IBD API) ─────────────────────────────
+    def _resolve_ibd(self, path: str) -> Dict[str, Any]:
+        parts = path.split("/")
+        if len(parts) < 2 or parts[0] != "diff":
+            return {"error": "Use ibd://diff/<file_path>"}
+        file_path = self.repo_root / parts[1]
+        if not file_path.exists():
+            return {"error": f"File not found: {file_path}"}
+        try:
+            from sin_code_ibd import ASTDiff
+
+            diff = ASTDiff(str(file_path))
+            return {
+                "type": "ibd_diff",
+                "file": str(file_path),
+                "ast": diff.to_dict() if hasattr(diff, "to_dict") else str(diff),
+            }
+        except ImportError:
+            return {"error": "IBD not installed"}
+
+    # ── ADW resolver (uses REAL ADW API) ─────────────────────────────
+    def _resolve_adw(self, path: str) -> Dict[str, Any]:
+        parts = path.split("/")
+        if len(parts) < 2 or parts[0] != "smell":
+            return {"error": "Use adw://smell/<name>"}
+        smell_name = parts[1]
+        # try/except around every resolver = graceful degradation:
+        # if one subsystem breaks or is missing, the others still resolve.
+        try:
+            from sin_code_adw import smells
+
+            # ADW doesn't expose a unified query API, so we surface the
+            # available analyzers and tell the user to call them directly
+            # (same rationale as EFSM/Oracle/POC below).
+            available = [
+                m for m in dir(smells) if not m.startswith("_") and callable(getattr(smells, m))
+            ]
+            return {
+                "type": "adw_smell",
+                "name": smell_name,
+                "available_analyzers": available,
+            }
+        except ImportError:
+            return {"error": "ADW not installed"}
+
+    # ── EFSM resolver (uses REAL EFSM API) ───────────────────────────
+    def _resolve_efsm(self, path: str) -> Dict[str, Any]:
+        parts = path.split("/")
+        if len(parts) < 2 or parts[0] != "service":
+            return {"error": "Use efsm://service/<name>"}
+        service_name = parts[1]
+        # try/except around every resolver = graceful degradation:
+        # if one subsystem breaks or is missing, the others still resolve.
+        try:
+            from sin_code_efsm import services
+
+            # EFSM doesn't expose a unified query API, so we surface the
+            # available services and tell the user to call them directly
+            # (same rationale as ADW/Oracle/POC above).
+            available = [m for m in dir(services) if not m.startswith("_")]
+            return {
+                "type": "efsm_service",
+                "name": service_name,
+                "available": available,
+                "note": f"Run: sin efsm create --service={service_name}",
+            }
+        except ImportError:
+            return {"error": "EFSM not installed"}
+
+    # ── Oracle resolver (uses REAL Oracle API) ───────────────────────
+    def _resolve_oracle(self, path: str) -> Dict[str, Any]:
+        parts = path.split("/")
+        if len(parts) < 2 or parts[0] != "strategy":
+            return {"error": "Use oracle://strategy/<name>"}
+        strategy_name = parts[1]
+        # try/except around every resolver = graceful degradation:
+        # if one subsystem breaks or is missing, the others still resolve.
+        try:
+            from sin_code_oracle import verifier
+
+            available = [
+                m for m in dir(verifier) if not m.startswith("_") and callable(getattr(verifier, m))
+            ]
+            # [:20] limits blast radius — Oracle's verifier module can
+            # have many callables; we just need enough to be discoverable.
+            # Oracle doesn't expose a unified query API either, so we
+            # return the available verifiers and let the user call them
+            # directly (same rationale as ADW/EFSM/POC above).
+            return {
+                "type": "oracle_strategy",
+                "strategy": strategy_name,
+                "available": available[:20],
+            }
+        except ImportError:
+            return {"error": "Oracle not installed"}
+
+    # ── Conflict resolver (git-based) ────────────────────────────────
+    def _resolve_conflict(self, path: str) -> Dict[str, Any]:
+        try:
+            # git-based and cheap: `git diff --name-only --diff-filter=U`
+            # lists unmerged (U-status) paths. We don't need to parse
+            # conflict markers ourselves — just surface the file list.
+            # 10s timeout — `git diff` is in-memory; only a broken index would
+            # make it slow, and we want to fail fast in that case.
+            result = subprocess.run(
+                ["git", "diff", "--name-only", "--diff-filter=U"],
+                capture_output=True,
+                text=True,
+                cwd=self.repo_root,
+                timeout=10,
+            )
+            conflicted = [f for f in result.stdout.splitlines() if f]
+        except Exception as e:
+            return {"error": f"git failed: {e}"}
+
+        if path == "*" or path == "":
+            # conflict://* = bulk list (most common, agents usually want
+            # "what files are in conflict?" not a single one).
+            return {"type": "conflict_bulk", "files": conflicted, "count": len(conflicted)}
+        if path.isdigit():
+            idx = int(path)
+            if 0 <= idx < len(conflicted):
+                return {"type": "conflict_single", "file": conflicted[idx]}
+            return {"error": f"Conflict index {idx} out of range (have {len(conflicted)})"}
+        return {"error": "Use conflict://* for all or conflict://<N> for specific"}
+
+
+__all__ = ["SINVirtualFS", "URI_SCHEMES"]