ninchi-cli 0.2.0__py3-none-any.whl

ninchi_cli/__init__.py

@@ -0,0 +1,5 @@
+"""Ninchi command-line client."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

ninchi_cli/client.py

@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+
+class NinchiAPIError(RuntimeError):
+    def __init__(self, message: str, *, status_code: int | None = None, payload: Any = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.payload = payload
+
+
+@dataclass(frozen=True)
+class DeviceCode:
+    device_code: str
+    user_code: str
+    verification_url: str
+    interval: int
+    expires_in: int | None = None
+
+
+def _detail(response: httpx.Response) -> str:
+    try:
+        payload = response.json()
+    except ValueError:
+        return response.text.strip() or response.reason_phrase
+    detail = payload.get("detail") if isinstance(payload, dict) else None
+    if isinstance(detail, str):
+        return detail
+    if detail is not None:
+        return str(detail)
+    return response.reason_phrase
+
+
+class NinchiClient:
+    def __init__(
+        self,
+        *,
+        api_url: str,
+        token: str | None = None,
+        timeout: float = 30.0,
+        transport: httpx.BaseTransport | None = None,
+    ):
+        self.api_url = api_url.rstrip("/")
+        self.token = token
+        self._client = httpx.Client(base_url=self.api_url, timeout=timeout, transport=transport)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "NinchiClient":
+        return self
+
+    def __exit__(self, *_exc) -> None:
+        self.close()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        expected: tuple[int, ...] = (200,),
+        allow: tuple[int, ...] = (),
+    ) -> httpx.Response:
+        headers = {}
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        try:
+            response = self._client.request(method, path, json=json, params=params, headers=headers)
+        except httpx.HTTPError as exc:
+            raise NinchiAPIError(f"HTTP request failed: {exc}") from exc
+        if response.status_code in expected or response.status_code in allow:
+            return response
+        raise NinchiAPIError(_detail(response), status_code=response.status_code, payload=_safe_json(response))
+
+    def start_device_login(self) -> DeviceCode:
+        response = self._request(
+            "POST",
+            "/auth/device/code",
+            json={"client_label": "Ninchi CLI"},
+            expected=(200, 201),
+        )
+        payload = response.json()
+        verification_url = (
+            payload.get("verification_url")
+            or payload.get("verification_uri_complete")
+            or payload.get("verification_uri")
+            or payload.get("user_code_url")
+        )
+        if not payload.get("device_code") or not payload.get("user_code") or not verification_url:
+            raise NinchiAPIError("Device login response was missing required fields.", payload=payload)
+        return DeviceCode(
+            device_code=payload["device_code"],
+            user_code=payload["user_code"],
+            verification_url=verification_url,
+            interval=int(payload.get("interval") or 5),
+            expires_in=payload.get("expires_in"),
+        )
+
+    def poll_device_token(self, device_code: str) -> str | None:
+        response = self._request(
+            "POST",
+            "/auth/device/token",
+            json={"device_code": device_code},
+            expected=(200,),
+            allow=(428,),
+        )
+        if response.status_code == 428:
+            return None
+        payload = response.json()
+        token = payload.get("access_token") or payload.get("token") or payload.get("api_token")
+        if not token:
+            raise NinchiAPIError("Device token response was missing a token.", payload=payload)
+        return token
+
+    def wait_for_device_token(self, code: DeviceCode, *, timeout_seconds: int = 600) -> str:
+        deadline = time.monotonic() + timeout_seconds
+        while time.monotonic() < deadline:
+            token = self.poll_device_token(code.device_code)
+            if token:
+                return token
+            time.sleep(max(1, code.interval))
+        raise NinchiAPIError("Timed out waiting for device approval.")
+
+    def submit_check(self, org_id: str, payload: dict[str, Any]) -> str:
+        response = self._request("POST", f"/orgs/{org_id}/checks", json=payload, expected=(202,))
+        body = response.json()
+        challenge_id = body.get("challenge_id") or body.get("id")
+        if not challenge_id:
+            raise NinchiAPIError("Check submission response was missing challenge_id.", payload=body)
+        return str(challenge_id)
+
+    def get_challenge(self, challenge_id: str) -> dict[str, Any] | None:
+        response = self._request("GET", f"/challenges/{challenge_id}", allow=(202,))
+        if response.status_code == 202:
+            return None
+        return response.json()
+
+    def wait_for_challenge(self, challenge_id: str, *, interval: float = 2.0, timeout_seconds: int = 600) -> dict[str, Any]:
+        deadline = time.monotonic() + timeout_seconds
+        while time.monotonic() < deadline:
+            challenge = self.get_challenge(challenge_id)
+            if challenge is not None:
+                return challenge
+            time.sleep(interval)
+        raise NinchiAPIError("Timed out waiting for challenge generation.")
+
+    def submit_answer(
+        self,
+        challenge_id: str,
+        *,
+        answer_text: str,
+        answering_actor: str,
+        time_taken_seconds: int | None = None,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "answer_text": answer_text,
+            "answering_actor": answering_actor,
+        }
+        if time_taken_seconds is not None:
+            payload["time_taken_seconds"] = time_taken_seconds
+        response = self._request("POST", f"/challenges/{challenge_id}/answer", json=payload, expected=(202,))
+        return response.json()
+
+    def get_result(self, challenge_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/challenges/{challenge_id}/result").json()
+
+    def wait_for_result(self, challenge_id: str, *, interval: float = 2.0, timeout_seconds: int = 600) -> dict[str, Any]:
+        deadline = time.monotonic() + timeout_seconds
+        while time.monotonic() < deadline:
+            result = self.get_result(challenge_id)
+            if result.get("status") in {"passed", "failed", "expired", "error"}:
+                return result
+            time.sleep(interval)
+        raise NinchiAPIError("Timed out waiting for challenge result.")
+
+    def history(self, *, limit: int = 20) -> dict[str, Any]:
+        return self._request("GET", "/analytics/me/challenges", params={"limit": limit}).json()
+
+
+def _safe_json(response: httpx.Response) -> Any:
+    try:
+        return response.json()
+    except ValueError:
+        return None

ninchi_cli/config.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+DEFAULT_API_URL = "https://api.ninchi.ai"
+ENV_API_URL = "NINCHI_API_URL"
+ENV_TOKEN = "NINCHI_API_TOKEN"
+ENV_CONFIG_DIR = "NINCHI_CONFIG_DIR"
+
+
+@dataclass(frozen=True)
+class Credentials:
+    token: str | None
+    api_url: str
+    source: str
+
+
+def config_dir() -> Path:
+    override = os.environ.get(ENV_CONFIG_DIR)
+    if override:
+        return Path(override).expanduser()
+    xdg_home = os.environ.get("XDG_CONFIG_HOME")
+    if xdg_home:
+        return Path(xdg_home).expanduser() / "ninchi"
+    return Path.home() / ".config" / "ninchi"
+
+
+def credentials_path() -> Path:
+    return config_dir() / "credentials"
+
+
+def _read_file(path: Path) -> Credentials | None:
+    if not path.exists():
+        return None
+    raw = path.read_text(encoding="utf-8").strip()
+    if not raw:
+        return None
+    if raw.startswith("{"):
+        payload = json.loads(raw)
+        return Credentials(
+            token=payload.get("token"),
+            api_url=payload.get("api_url") or DEFAULT_API_URL,
+            source=str(path),
+        )
+    return Credentials(token=raw, api_url=DEFAULT_API_URL, source=str(path))
+
+
+def load_credentials(path: Path | None = None) -> Credentials:
+    path = path or credentials_path()
+    file_creds = _read_file(path)
+    api_url = os.environ.get(ENV_API_URL) or (file_creds.api_url if file_creds else DEFAULT_API_URL)
+    token = os.environ.get(ENV_TOKEN)
+    if token:
+        return Credentials(token=token, api_url=api_url, source=ENV_TOKEN)
+    if file_creds:
+        return Credentials(token=file_creds.token, api_url=api_url, source=file_creds.source)
+    return Credentials(token=None, api_url=api_url, source="none")
+
+
+def save_credentials(token: str, api_url: str, path: Path | None = None) -> Path:
+    path = path or credentials_path()
+    path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    try:
+        path.parent.chmod(0o700)
+    except PermissionError:
+        # Best effort on shared/dev filesystems.
+        pass
+
+    tmp = path.with_name(f"{path.name}.tmp")
+    payload = {"api_url": api_url, "token": token}
+    tmp.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+    tmp.chmod(0o600)
+    tmp.replace(path)
+    path.chmod(0o600)
+    return path

ninchi_cli/diffs.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+
+class DiffError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class CheckSubject:
+    payload: dict
+    label: str
+
+
+def collect_check_subject(args) -> CheckSubject:
+    if args.file:
+        path = Path(args.file)
+        content = path.read_text(encoding="utf-8")
+        if not content.strip():
+            raise DiffError(f"{path} is empty.")
+        region = {"path": str(path), "content": content}
+        if args.language:
+            region["language"] = args.language
+        return CheckSubject(payload={"code_region": region}, label=str(path))
+
+    if args.stdin:
+        diff_text = sys.stdin.read()
+        return _diff_subject(diff_text, "stdin")
+
+    if args.commit:
+        diff_text = _git(["show", "--format=", "--no-ext-diff", "--unified=3", args.commit])
+        return _diff_subject(diff_text, args.commit)
+
+    if args.staged:
+        diff_text = _git(["diff", "--staged", "--no-ext-diff"])
+        return _diff_subject(diff_text, "staged diff")
+
+    diff_text = _git(["diff", "HEAD", "--no-ext-diff"])
+    return _diff_subject(diff_text, "working tree diff")
+
+
+def _diff_subject(diff_text: str, label: str) -> CheckSubject:
+    if not diff_text.strip():
+        raise DiffError(f"No diff content found for {label}.")
+    return CheckSubject(payload={"diff_text": diff_text}, label=label)
+
+
+def _git(args: list[str]) -> str:
+    try:
+        completed = subprocess.run(
+            ["git", *args],
+            check=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+        )
+    except FileNotFoundError as exc:
+        raise DiffError("git is not installed or not on PATH.") from exc
+    except subprocess.CalledProcessError as exc:
+        message = (exc.stderr or exc.stdout or "git command failed").strip()
+        raise DiffError(message) from exc
+    return completed.stdout

ninchi_cli/main.py

@@ -0,0 +1,328 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import textwrap
+import time
+from typing import Any
+
+from .client import NinchiAPIError, NinchiClient
+from .config import DEFAULT_API_URL, load_credentials, save_credentials
+from .diffs import DiffError, collect_check_subject
+
+
+EXIT_PASS = 0
+EXIT_FAIL = 1
+EXIT_PENDING_OR_ERROR = 2
+
+ACTORS = ("human_attested", "agent_assisted", "agent_autonomous")
+
+
+class CLIError(RuntimeError):
+    pass
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not hasattr(args, "func"):
+        parser.print_help()
+        return EXIT_PENDING_OR_ERROR
+    try:
+        return args.func(args)
+    except (CLIError, DiffError, NinchiAPIError) as exc:
+        return fail(exc, json_output=getattr(args, "json", False))
+    except KeyboardInterrupt:
+        return fail(CLIError("Interrupted."), json_output=getattr(args, "json", False))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--api-url", default=None, help=f"Ninchi API URL. Default: {DEFAULT_API_URL}")
+    common.add_argument("--json", action="store_true", help="Emit machine-readable JSON.")
+
+    parser = argparse.ArgumentParser(prog="ninchi", description="Ninchi command-line client")
+    sub = parser.add_subparsers(dest="command")
+
+    login = sub.add_parser("login", parents=[common], help="Authenticate with the Ninchi device flow.")
+    login.add_argument("--timeout", type=int, default=600, help="Seconds to wait for approval.")
+    login.set_defaults(func=cmd_login)
+
+    check = sub.add_parser("check", parents=[common], help="Submit a local subject and answer its challenge.")
+    source = check.add_mutually_exclusive_group()
+    source.add_argument("--stdin", action="store_true", help="Read a diff from stdin.")
+    source.add_argument("--staged", action="store_true", help="Use git diff --staged.")
+    source.add_argument("--commit", metavar="SHA", help="Use a single commit diff.")
+    source.add_argument("--file", metavar="PATH", help="Submit one file as a code region.")
+    check.add_argument("--org-id", default=None, help="Target organization ID. Defaults to NINCHI_ORG_ID.")
+    check.add_argument("--language", default=None, help="Language hint for --file.")
+    check.add_argument("--answer", default=None, help="Answer non-interactively.")
+    check.add_argument("--actor", choices=ACTORS, default=None, help="Answering actor provenance override.")
+    check.add_argument("--poll-interval", type=float, default=2.0, help="Polling interval in seconds.")
+    check.add_argument("--timeout", type=int, default=600, help="Seconds to wait for generation/evaluation.")
+    check.set_defaults(func=cmd_check)
+
+    result = sub.add_parser("result", parents=[common], help="Fetch a challenge result.")
+    result.add_argument("challenge_id")
+    result.set_defaults(func=cmd_result)
+
+    history = sub.add_parser("history", parents=[common], help="List your recent challenge history.")
+    history.add_argument("--limit", type=int, default=20)
+    history.set_defaults(func=cmd_history)
+
+    mcp = sub.add_parser(
+        "mcp",
+        help="Run the Ninchi MCP server over stdio (for Cursor, Claude Code, etc.).",
+    )
+    mcp.set_defaults(func=cmd_mcp)
+
+    return parser
+
+
+def cmd_mcp(args) -> int:
+    # Lazy import: the MCP SDK is only loaded when actually serving, so every
+    # other command stays fast and works even if the SDK install is broken.
+    try:
+        from .mcp_server import run_stdio
+    except ImportError as exc:
+        raise CLIError(
+            f"MCP support unavailable ({exc}). Reinstall the package: "
+            "pipx install ninchi-cli"
+        ) from exc
+    return run_stdio()
+
+
+def cmd_login(args) -> int:
+    api_url = resolve_api_url(args)
+    with NinchiClient(api_url=api_url) as client:
+        code = client.start_device_login()
+        if args.json:
+            emit_json({
+                "ok": True,
+                "user_code": code.user_code,
+                "verification_url": code.verification_url,
+                "interval": code.interval,
+                "expires_in": code.expires_in,
+            })
+        else:
+            print("Ninchi device login")
+            print()
+            print(f"Open: {code.verification_url}")
+            print(f"Code: {code.user_code}")
+            print()
+            print("Waiting for approval...")
+        token = client.wait_for_device_token(code, timeout_seconds=args.timeout)
+    path = save_credentials(token, api_url)
+    if args.json:
+        emit_json({"ok": True, "credentials_path": str(path), "api_url": api_url})
+    else:
+        print(f"Saved credentials to {path}")
+    return EXIT_PASS
+
+
+def cmd_check(args) -> int:
+    org_id = args.org_id or os.environ.get("NINCHI_ORG_ID")
+    if not org_id:
+        raise CLIError("Missing --org-id or NINCHI_ORG_ID.")
+
+    creds = resolve_credentials(args)
+    require_token(creds.token)
+    subject = collect_check_subject(args)
+    payload = dict(subject.payload)
+    payload["client_attribution"] = "cli"
+
+    with NinchiClient(api_url=creds.api_url, token=creds.token) as client:
+        challenge_id = client.submit_check(org_id, payload)
+        if not args.json:
+            print(f"Submitted {subject.label}. Challenge: {challenge_id}")
+            print("Waiting for question...")
+        challenge = client.wait_for_challenge(
+            challenge_id,
+            interval=args.poll_interval,
+            timeout_seconds=args.timeout,
+        )
+        if args.json and args.answer is None:
+            emit_json({
+                "ok": False,
+                "challenge": challenge,
+                "error": "Pass --answer to complete a check in JSON mode.",
+            })
+            return EXIT_PENDING_OR_ERROR
+
+        if not args.json:
+            render_question(challenge)
+
+        started = time.monotonic()
+        answer, prompted = resolve_answer(args)
+        if not answer.strip():
+            raise CLIError("Answer cannot be empty.")
+        actor = args.actor or ("human_attested" if prompted else "agent_assisted")
+        elapsed = max(0, int(time.monotonic() - started))
+        client.submit_answer(
+            challenge_id,
+            answer_text=answer,
+            answering_actor=actor,
+            time_taken_seconds=elapsed,
+        )
+        if not args.json:
+            print("Answer submitted. Waiting for result...")
+        result = client.wait_for_result(
+            challenge_id,
+            interval=args.poll_interval,
+            timeout_seconds=args.timeout,
+        )
+
+    exit_code = result_exit_code(result)
+    if args.json:
+        emit_json({"ok": exit_code == EXIT_PASS, "challenge": challenge, "result": result, "actor": actor})
+    else:
+        render_result(result)
+    return exit_code
+
+
+def cmd_result(args) -> int:
+    creds = resolve_credentials(args)
+    require_token(creds.token)
+    with NinchiClient(api_url=creds.api_url, token=creds.token) as client:
+        result = client.get_result(args.challenge_id)
+    if args.json:
+        emit_json({"ok": result_exit_code(result) == EXIT_PASS, "result": result})
+    else:
+        render_result(result)
+    return result_exit_code(result)
+
+
+def cmd_history(args) -> int:
+    creds = resolve_credentials(args)
+    require_token(creds.token)
+    with NinchiClient(api_url=creds.api_url, token=creds.token) as client:
+        history = client.history(limit=args.limit)
+    if args.json:
+        emit_json({"ok": True, "history": history})
+    else:
+        items = history.get("items") if isinstance(history, dict) else history
+        if not items:
+            print("No challenges found.")
+            return EXIT_PASS
+        for item in items:
+            challenge_id = item.get("challenge_id") or item.get("id")
+            status = item.get("status", "unknown")
+            title = item.get("title") or item.get("pr_title") or item.get("source_title") or "Untitled"
+            print(f"{challenge_id}  {status:>9}  {title}")
+    return EXIT_PASS
+
+
+def resolve_credentials(args):
+    creds = load_credentials()
+    api_url = resolve_api_url(args, fallback=creds.api_url)
+    return type(creds)(token=creds.token, api_url=api_url, source=creds.source)
+
+
+def resolve_api_url(args, *, fallback: str | None = None) -> str:
+    return args.api_url or os.environ.get("NINCHI_API_URL") or fallback or DEFAULT_API_URL
+
+
+def require_token(token: str | None) -> None:
+    if not token:
+        raise CLIError("Not authenticated. Run `ninchi login` or set NINCHI_API_TOKEN.")
+
+
+def resolve_answer(args) -> tuple[str, bool]:
+    if args.answer is not None:
+        return args.answer, False
+    if not can_prompt():
+        raise CLIError("No terminal available for an interactive answer. Pass --answer for automation.")
+    return prompt_multiline("Your answer (press Enter twice when done):"), True
+
+
+def can_prompt() -> bool:
+    if sys.stdin.isatty():
+        return True
+    try:
+        with open("/dev/tty", "r", encoding="utf-8"):
+            return True
+    except OSError:
+        return False
+
+
+def prompt_multiline(prompt: str) -> str:
+    print(prompt)
+    print()
+    lines: list[str] = []
+    if sys.stdin.isatty():
+        stream = sys.stdin
+        close = False
+    else:
+        stream = open("/dev/tty", "r", encoding="utf-8")
+        close = True
+    try:
+        while True:
+            line = stream.readline()
+            if line == "":
+                break
+            line = line.rstrip("\n")
+            if line == "" and lines and lines[-1] == "":
+                break
+            lines.append(line)
+    finally:
+        if close:
+            stream.close()
+    return "\n".join(lines).strip()
+
+
+def render_question(challenge: dict[str, Any]) -> None:
+    print()
+    print("=" * 72)
+    print(f"Difficulty: {challenge.get('difficulty', 'unknown')}")
+    target = challenge.get("target_filename") or challenge.get("source_title")
+    if target:
+        print(f"Target:     {target}")
+    tags = challenge.get("tags") or []
+    if tags:
+        print(f"Tags:       {', '.join(tags)}")
+    print("-" * 72)
+    question = challenge.get("question_text") or ""
+    for line in textwrap.wrap(question, width=72):
+        print(line)
+    print("=" * 72)
+    print()
+
+
+def render_result(result: dict[str, Any]) -> None:
+    status = result.get("status", "unknown")
+    score = result.get("score")
+    print()
+    print(f"Status: {status}")
+    if score is not None:
+        print(f"Score:  {score}/100")
+    feedback = result.get("feedback")
+    if feedback:
+        print()
+        print(feedback)
+
+
+def result_exit_code(result: dict[str, Any]) -> int:
+    status = result.get("status")
+    if status == "passed" or result.get("passed") is True:
+        return EXIT_PASS
+    if status == "failed" or result.get("passed") is False:
+        return EXIT_FAIL
+    return EXIT_PENDING_OR_ERROR
+
+
+def emit_json(payload: dict[str, Any]) -> None:
+    print(json.dumps(payload, sort_keys=True))
+
+
+def fail(exc: Exception, *, json_output: bool) -> int:
+    if json_output:
+        emit_json({"ok": False, "error": str(exc), "type": exc.__class__.__name__})
+    else:
+        print(f"ninchi: {exc}", file=sys.stderr)
+    return EXIT_PENDING_OR_ERROR
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ninchi_cli/mcp_server.py

@@ -0,0 +1,300 @@
+"""Ninchi MCP server (ENT-040): the CLI's HTTP client exposed as MCP tools.
+
+Run via ``ninchi mcp`` (stdio transport). Any MCP-capable editor/agent
+(Cursor, Claude Code, etc.) can then submit checks, fetch questions, submit
+answers, and read results through the same authenticated API surface the
+CLI uses (ENT-036 PATs + ENT-037 submission API).
+
+Design decisions (see the New Surfaces plan + Decision Log 2026-07-16):
+
+- ``submit_answer`` REQUIRES an ``actor`` argument. There is deliberately
+  no default: honesty about who authored the answer is the contract. Agents
+  must pass ``agent_autonomous`` when they wrote the answer themselves,
+  ``agent_assisted`` when a human meaningfully directed it, and
+  ``human_attested`` only when relaying a human's own words. The server
+  enforces org policy regardless — orgs may reject agent answers entirely,
+  and that rejection is surfaced with guidance to hand the question to the
+  human user. No human-in-the-loop assumption is baked in here: it is org
+  policy, not client behavior.
+- Client attribution: submissions carry ``client_attribution:
+  "mcp:<client-name>"`` from the MCP handshake (GTM-013's high-fidelity
+  authorship feed).
+- Auth reuses the CLI credentials file / ``NINCHI_API_TOKEN`` env var; run
+  ``ninchi login`` first.
+
+The tool bodies live in ``_impl``-suffixed functions that take an explicit
+``NinchiClient`` so tests exercise them hermetically; the FastMCP-decorated
+wrappers only resolve credentials and construct the client.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Literal
+
+# Imported at module level so PEP 563 string annotations on the tool
+# functions resolve against module globals. Laziness is preserved one level
+# up: main.py only imports this module when `ninchi mcp` actually runs.
+from mcp.server.fastmcp import Context, FastMCP
+
+from .client import NinchiAPIError, NinchiClient
+from .config import load_credentials
+
+# Bounded server-side waits so tool calls return promptly enough for agent
+# UIs while still absorbing normal generation/evaluation latency.
+DEFAULT_WAIT_SECONDS = 90
+MAX_WAIT_SECONDS = 300
+
+Actor = Literal["human_attested", "agent_assisted", "agent_autonomous"]
+
+
+class NinchiMCPError(RuntimeError):
+    """Raised for tool-level failures; FastMCP surfaces the message."""
+
+
+def _make_client() -> NinchiClient:
+    creds = load_credentials()
+    if not creds.token:
+        raise NinchiMCPError(
+            "Not authenticated. Run `ninchi login` in a terminal first (or set "
+            "NINCHI_API_TOKEN); the MCP server reuses the CLI credentials."
+        )
+    return NinchiClient(api_url=creds.api_url, token=creds.token)
+
+
+def _client_attribution(ctx: Any) -> str:
+    """``mcp:<client-name>`` from the MCP handshake, fail-open to ``mcp``."""
+    try:
+        name = ctx.session.client_params.clientInfo.name  # type: ignore[union-attr]
+    except AttributeError:
+        name = None
+    if not name:
+        return "mcp"
+    slug = re.sub(r"[^a-z0-9._-]+", "-", str(name).strip().lower())[:48].strip("-")
+    return f"mcp:{slug}" if slug else "mcp"
+
+
+def _clamp_wait(seconds: int) -> int:
+    return max(0, min(int(seconds), MAX_WAIT_SECONDS))
+
+
+# ─── Tool bodies (hermetically testable) ──────────────────────────────────────
+
+def submit_check_impl(
+    client: NinchiClient,
+    *,
+    org_id: str,
+    attribution: str,
+    diff_text: str | None = None,
+    content: str | None = None,
+    title: str | None = None,
+    file_path: str | None = None,
+    file_content: str | None = None,
+    language: str | None = None,
+) -> dict[str, Any]:
+    subjects = [s for s in (diff_text, content, file_content) if s is not None]
+    if len(subjects) != 1:
+        raise NinchiMCPError(
+            "Provide exactly one subject: diff_text, OR content (+ optional "
+            "title), OR file_content + file_path (+ optional language)."
+        )
+    payload: dict[str, Any] = {"client_attribution": attribution}
+    if diff_text is not None:
+        payload["diff_text"] = diff_text
+    elif content is not None:
+        payload["content"] = content
+        if title:
+            payload["title"] = title
+    else:
+        if not file_path:
+            raise NinchiMCPError("file_content requires file_path.")
+        region: dict[str, Any] = {"path": file_path, "content": file_content}
+        if language:
+            region["language"] = language
+        payload["code_region"] = region
+
+    challenge_id = client.submit_check(org_id, payload)
+    return {
+        "challenge_id": challenge_id,
+        "status": "generating",
+        "next_step": "Call get_challenge to retrieve the question.",
+    }
+
+
+def get_challenge_impl(
+    client: NinchiClient, *, challenge_id: str, wait_seconds: int
+) -> dict[str, Any]:
+    wait = _clamp_wait(wait_seconds)
+    if wait == 0:
+        challenge = client.get_challenge(challenge_id)
+    else:
+        try:
+            challenge = client.wait_for_challenge(challenge_id, timeout_seconds=wait)
+        except NinchiAPIError as exc:
+            if "Timed out" in str(exc):
+                return {
+                    "status": "generating",
+                    "challenge_id": challenge_id,
+                    "note": "Still generating — call get_challenge again.",
+                }
+            raise
+    if challenge is None:
+        return {
+            "status": "generating",
+            "challenge_id": challenge_id,
+            "note": "Still generating — call get_challenge again.",
+        }
+    return challenge
+
+
+def submit_answer_impl(
+    client: NinchiClient, *, challenge_id: str, answer_text: str, actor: str
+) -> dict[str, Any]:
+    if not answer_text.strip():
+        raise NinchiMCPError("answer_text cannot be empty.")
+    try:
+        return client.submit_answer(
+            challenge_id, answer_text=answer_text, answering_actor=actor
+        )
+    except NinchiAPIError as exc:
+        if exc.status_code == 403 and actor != "human_attested":
+            raise NinchiMCPError(
+                f"The organization's policy rejected an agent-authored answer: "
+                f"{exc}. Hand the question text to the human user, let them "
+                f"answer in their own words, and relay it with "
+                f"actor='human_attested' — do not answer on their behalf."
+            ) from exc
+        raise
+
+
+def get_result_impl(
+    client: NinchiClient, *, challenge_id: str, wait_seconds: int
+) -> dict[str, Any]:
+    wait = _clamp_wait(wait_seconds)
+    if wait == 0:
+        return client.get_result(challenge_id)
+    try:
+        return client.wait_for_result(challenge_id, timeout_seconds=wait)
+    except NinchiAPIError as exc:
+        if "Timed out" in str(exc):
+            return {
+                "status": "evaluating",
+                "challenge_id": challenge_id,
+                "note": "Still evaluating — call get_result again.",
+            }
+        raise
+
+
+def list_history_impl(client: NinchiClient, *, limit: int) -> dict[str, Any]:
+    return client.history(limit=max(1, min(int(limit), 100)))
+
+
+# ─── FastMCP registration ─────────────────────────────────────────────────────
+
+def build_server() -> FastMCP:
+    """Construct the FastMCP server with the five Ninchi tools registered."""
+    server = FastMCP(
+        "ninchi",
+        instructions=(
+            "Ninchi verifies that a person understands a code change by asking "
+            "a comprehension question and grading the answer. Typical flow: "
+            "submit_check → get_challenge → (a HUMAN answers) → submit_answer "
+            "→ get_result. Be honest in submit_answer's actor argument: if "
+            "you (the agent) authored the answer, that is agent_autonomous. "
+            "Some organizations block agent answers by policy; in that case "
+            "show the question to the human user and relay their answer."
+        ),
+    )
+
+    @server.tool()
+    def submit_check(
+        org_id: str,
+        ctx: Context,
+        diff_text: str | None = None,
+        content: str | None = None,
+        title: str | None = None,
+        file_path: str | None = None,
+        file_content: str | None = None,
+        language: str | None = None,
+    ) -> dict:
+        """Submit a verification subject to Ninchi and start challenge
+        generation. Provide EXACTLY ONE subject: `diff_text` (a unified git
+        diff), OR `content` (arbitrary text/code, optional `title`), OR
+        `file_content` + `file_path` (a code region, optional `language`).
+        Returns a challenge_id; the question is ready shortly after
+        (get_challenge). Requires the org to have programmatic checks
+        enabled; counts against the developer's programmatic-check quota."""
+        with _make_client() as client:
+            return submit_check_impl(
+                client,
+                org_id=org_id,
+                attribution=_client_attribution(ctx),
+                diff_text=diff_text,
+                content=content,
+                title=title,
+                file_path=file_path,
+                file_content=file_content,
+                language=language,
+            )
+
+    @server.tool()
+    def get_challenge(
+        challenge_id: str, wait_seconds: int = DEFAULT_WAIT_SECONDS
+    ) -> dict:
+        """Fetch a challenge's question (waits up to `wait_seconds` for
+        generation to finish; returns status="generating" if not ready yet —
+        call again). The question is meant to be answered by the HUMAN
+        developer unless their organization permits agent answers."""
+        with _make_client() as client:
+            return get_challenge_impl(
+                client, challenge_id=challenge_id, wait_seconds=wait_seconds
+            )
+
+    @server.tool()
+    def submit_answer(challenge_id: str, answer_text: str, actor: Actor) -> dict:
+        """Submit an answer for evaluation. `actor` is REQUIRED and must be
+        honest — it is recorded as evidence provenance:
+        - "human_attested": the human developer wrote this answer themselves;
+          you are only relaying it verbatim.
+        - "agent_assisted": a human meaningfully directed the answer's content.
+        - "agent_autonomous": you (the agent) authored the answer.
+        Never upgrade the actor to make an answer acceptable; organizations
+        may block agent answers by policy, in which case show the question to
+        the human and relay their own answer as human_attested."""
+        with _make_client() as client:
+            return submit_answer_impl(
+                client,
+                challenge_id=challenge_id,
+                answer_text=answer_text,
+                actor=actor,
+            )
+
+    @server.tool()
+    def get_result(
+        challenge_id: str, wait_seconds: int = DEFAULT_WAIT_SECONDS
+    ) -> dict:
+        """Fetch the evaluation result (waits up to `wait_seconds`; returns
+        status="evaluating" if grading is still running — call again).
+        Status "passed"/"failed" is final, with score and feedback."""
+        with _make_client() as client:
+            return get_result_impl(
+                client, challenge_id=challenge_id, wait_seconds=wait_seconds
+            )
+
+    @server.tool()
+    def list_history(limit: int = 20) -> dict:
+        """List the authenticated developer's recent challenges (most recent
+        first): ids, statuses, and titles."""
+        with _make_client() as client:
+            return list_history_impl(client, limit=limit)
+
+    return server
+
+
+def run_stdio() -> int:
+    """Entry point for `ninchi mcp`: serve MCP over stdio until the client
+    disconnects. Never print to stdout here — stdout is the protocol
+    channel."""
+    server = build_server()
+    server.run("stdio")
+    return 0

ninchi_cli-0.2.0.dist-info/METADATA

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: ninchi-cli
+Version: 0.2.0
+Summary: Command-line client and MCP server for Ninchi checks
+Author-email: Ninchi <support@ninchi.ai>
+License: Proprietary
+Project-URL: Homepage, https://ninchi.ai
+Project-URL: Documentation, https://ninchi.ai/docs/cli
+Keywords: ninchi,code-review,verification,mcp,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: mcp<2,>=1.2
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8; extra == "dev"
+
+# Ninchi CLI
+
+Thin HTTP client for running Ninchi checks from a terminal, hook, or CI job.
+The CLI does not import the backend or core engine; it talks to the public API.
+
+## Install
+
+```bash
+pipx install .
+```
+
+From this repo during development:
+
+```bash
+cd cli
+python -m pip install -e ".[dev]"
+```
+
+## Auth
+
+Interactive login uses the Ninchi device-code flow and stores a personal
+access token in `~/.config/ninchi/credentials` with mode `0600`:
+
+```bash
+ninchi login
+```
+
+CI can skip the credentials file:
+
+```bash
+export NINCHI_API_TOKEN="ninchi_pat_example_for_docs"
+```
+
+Use `NINCHI_API_URL` or `--api-url` to target a local/dev backend.
+
+## Checks
+
+Submit a diff from stdin and answer the generated challenge interactively:
+
+```bash
+git diff | ninchi check --stdin --org-id "$NINCHI_ORG_ID"
+```
+
+Other subject sources:
+
+```bash
+ninchi check --staged --org-id "$NINCHI_ORG_ID"
+ninchi check --commit HEAD --org-id "$NINCHI_ORG_ID"
+ninchi check --file src/app.py --language python --org-id "$NINCHI_ORG_ID"
+```
+
+Automation mode uses JSON output and exit codes:
+
+```bash
+git diff --staged | ninchi check --stdin --answer "$ANSWER" --json --org-id "$NINCHI_ORG_ID"
+```
+
+Exit codes:
+
+- `0`: challenge passed
+- `1`: challenge failed
+- `2`: pending, configuration, auth, API, or other operational error
+
+When an answer is typed interactively, the CLI submits
+`answering_actor=human_attested`. When `--answer` is supplied or the process has
+no terminal to prompt from, it submits `answering_actor=agent_assisted` unless
+`--actor` overrides it. The server enforces org policy.
+
+## Pre-push Hook
+
+Example `.git/hooks/pre-push`:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+base="${NINCHI_BASE_REF:-origin/main}"
+git diff --patch "$base"...HEAD | ninchi check \
+  --stdin \
+  --org-id "${NINCHI_ORG_ID:?set NINCHI_ORG_ID}" \
+```
+
+For human-attested hook usage, omit `--answer` and let the CLI prompt in the
+terminal.
+
+## MCP Server (`ninchi mcp`)
+
+The same client, served over the Model Context Protocol for agent-capable
+editors (Cursor, Claude Code, etc.). Authenticate once with `ninchi login`,
+then register the server — e.g. in Cursor (`.cursor/mcp.json` or global MCP
+settings):
+
+```json
+{
+  "mcpServers": {
+    "ninchi": { "command": "ninchi", "args": ["mcp"] }
+  }
+}
+```
+
+Tools: `submit_check`, `get_challenge`, `submit_answer`, `get_result`,
+`list_history`.
+
+Two things agents (and their humans) should know:
+
+- `submit_answer` requires an honest `actor` argument
+  (`human_attested` / `agent_assisted` / `agent_autonomous`). Provenance is
+  recorded with the attempt; organizations may block agent-authored answers
+  by policy, in which case the tool returns guidance to hand the question to
+  the human. There is no client-side human-only rule — policy lives with the
+  org.
+- Submissions carry `client_attribution: "mcp:<client-name>"` from the MCP
+  handshake, which feeds Ninchi's AI-authorship analytics.

ninchi_cli-0.2.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+ninchi_cli/__init__.py,sha256=njyPL_0adBPuFykUXoPqdX47C38uHuillF45sy8ORpw,84
+ninchi_cli/client.py,sha256=k3kQPE1FQju2QvHJ1r-38onPOlY9V427X4CvFfNDccM,6956
+ninchi_cli/config.py,sha256=9I1_lB5DtC8wHBdwfXmxR-q0uoxoacccDUdinMUnjhQ,2344
+ninchi_cli/diffs.py,sha256=yC5rOmr-Gdbdu_cLAfN9B2a6MRSykTrMM8eLS0-bdQI,1985
+ninchi_cli/main.py,sha256=UyIYHrBZlgEABIWbITD4KEaeITDkteUnC2FXw7pP8C8,11369
+ninchi_cli/mcp_server.py,sha256=b0iIQ6w3tMLWQzPI9oe8s5qLqKcIefXvjnlJnPTHvig,11925
+ninchi_cli-0.2.0.dist-info/METADATA,sha256=ONQJFVOD4P2g2mXvhSYmVrL8JxGiQs1PyZU2eh03duQ,3870
+ninchi_cli-0.2.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+ninchi_cli-0.2.0.dist-info/entry_points.txt,sha256=ptm9Wpp87DNeYkpHlTiQrjzacH9TZVIw0Jo6EklL4ug,48
+ninchi_cli-0.2.0.dist-info/top_level.txt,sha256=0P8L4w-RrYp6TLzhl4C4RzFwdSiFRvw7nMfFFVy49bU,11
+ninchi_cli-0.2.0.dist-info/RECORD,,

ninchi_cli-0.2.0.dist-info/WHEEL

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

ninchi_cli-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ninchi = ninchi_cli.main:main

ninchi_cli-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ninchi_cli