ninchi-cli 0.2.0__tar.gz

ninchi_cli-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,113 @@
+# 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/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ninchi-cli"
+version = "0.2.0"
+description = "Command-line client and MCP server for Ninchi checks"
+readme = "README.md"
+requires-python = ">=3.11"
+# License decision pending founder sign-off before first publish: Proprietary
+# is the conservative default; flipping to MIT/Apache-2.0 is a one-line change.
+license = { text = "Proprietary" }
+authors = [{ name = "Ninchi", email = "support@ninchi.ai" }]
+keywords = ["ninchi", "code-review", "verification", "mcp", "cli"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: Other/Proprietary License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Quality Assurance",
+]
+
+dependencies = [
+  "httpx>=0.27,<1.0",
+  # ENT-040: `ninchi mcp` serves the same client over the Model Context
+  # Protocol. Hard dependency so a pipx install is MCP-ready out of the box.
+  "mcp>=1.2,<2",
+]
+
+[project.urls]
+Homepage = "https://ninchi.ai"
+Documentation = "https://ninchi.ai/docs/cli"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8,<9",
+]
+
+[project.scripts]
+ninchi = "ninchi_cli.main:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

ninchi_cli-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ninchi_cli-0.2.0/src/ninchi_cli/__init__.py

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

ninchi_cli-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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