core-cli 2.0.0__tar.gz → 2.1.0__tar.gz

{core_cli-2.0.0 → core_cli-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: core-cli
-Version: 2.0.0
+Version: 2.1.0
 Summary: Consumer governance CLI for CORE — an HTTP client for governing repositories against CORE constitutional rules.
 Project-URL: Homepage, https://github.com/DariuszNewecki/CORE
 Project-URL: Repository, https://github.com/DariuszNewecki/core-cli
@@ -66,6 +66,12 @@ Its only dependencies are `typer`, `rich`, `httpx` and `PyYAML`.
 export CORE_API_URL=http://127.0.0.1:8000
 ```
 
+On the machine running CORE, `core` can use CORE's Unix socket instead of TCP. On that socket the kernel tells CORE who is calling; over TCP it cannot:
+
+```bash
+export CORE_API_URL=unix:///run/core/api.sock
+```
+
 ## Use
 
 ```bash

{core_cli-2.0.0 → core_cli-2.1.0}/README.md

@@ -37,6 +37,12 @@ Its only dependencies are `typer`, `rich`, `httpx` and `PyYAML`.
 export CORE_API_URL=http://127.0.0.1:8000
 ```
 
+On the machine running CORE, `core` can use CORE's Unix socket instead of TCP. On that socket the kernel tells CORE who is calling; over TCP it cannot:
+
+```bash
+export CORE_API_URL=unix:///run/core/api.sock
+```
+
 ## Use
 
 ```bash

{core_cli-2.0.0 → core_cli-2.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "core-cli"
-version = "2.0.0"
+version = "2.1.0"
 description = "Consumer governance CLI for CORE — an HTTP client for governing repositories against CORE constitutional rules."
 readme = "README.md"
 license = {text = "MIT"}

{core_cli-2.0.0 → core_cli-2.1.0}/src/core_cli/client.py

@@ -6,7 +6,9 @@ here is in CORE's published OpenAPI contract, ``docs/reference/openapi.json``
 in the CORE repository; ``tests/test_contract.py`` checks that.
 
 The base URL comes from the ``CORE_API_URL`` environment variable, defaulting
-to the loopback address CORE binds to.
+to the loopback address CORE binds to. ``unix:///path/to/api.sock`` selects
+CORE's Unix socket instead of TCP. On that socket the kernel tells CORE who is
+calling (ADR-132 D10.1 in the CORE repository); over TCP it cannot.
 """
 
 from __future__ import annotations
@@ -19,12 +21,36 @@ import httpx
 
 
 DEFAULT_BASE_URL = "http://127.0.0.1:8000"
+UNIX_SCHEME = "unix://"
+# HTTP needs a host for the request line and Host header; over a Unix socket
+# it names nothing, and CORE does not route on it.
+_UNIX_HTTP_BASE = "http://localhost"
 _TIMEOUT_SECONDS = 30.0
 _LONG_TIMEOUT_SECONDS = 300.0
 _POLL_INTERVAL_SECONDS = 1.0
 _POLL_TERMINAL_STATES = frozenset({"completed", "failed"})
 
 
+# ID: b50ad322-810a-4014-813e-a02a71cd55e7
+def parse_base_url(base_url: str) -> tuple[str, str | None]:
+    """Split a ``CORE_API_URL`` value into (HTTP base URL, Unix socket path).
+
+    ``unix:///run/core/api.sock`` gives ``("http://localhost", "/run/core/api.sock")``;
+    any other value is an HTTP base URL and gives ``(base_url, None)``. The
+    socket path must be absolute, so a mistyped ``unix://`` URL fails here
+    rather than as a confusing connection error.
+    """
+    if not base_url.startswith(UNIX_SCHEME):
+        return base_url, None
+    socket_path = base_url[len(UNIX_SCHEME) :]
+    if not socket_path.startswith("/"):
+        raise ValueError(
+            f"CORE_API_URL {base_url!r}: a Unix socket URL needs an absolute "
+            "path, e.g. unix:///run/core/api.sock"
+        )
+    return _UNIX_HTTP_BASE, socket_path
+
+
 # ID: e5aeda69-d26e-4353-81eb-83e998e968e9
 class CoreApiError(httpx.HTTPStatusError):
     """An error response (status >= 400) from the CORE API.
@@ -59,6 +85,7 @@ class CoreApiClient:
 
     def __init__(self, base_url: str | None = None) -> None:
         self.base_url = base_url or os.environ.get("CORE_API_URL") or DEFAULT_BASE_URL
+        self._http_base, self.socket_path = parse_base_url(self.base_url)
         self.inspect = _Inspect(self)
         self.lane = _Lane(self)
         self.project = _Project(self)
@@ -73,8 +100,11 @@ class CoreApiClient:
         timeout: float = _TIMEOUT_SECONDS,
         **kwargs: Any,
     ) -> dict:
-        async with httpx.AsyncClient(timeout=timeout) as http:
-            response = await http.request(method, f"{self.base_url}{path}", **kwargs)
+        client_kwargs: dict[str, Any] = {"timeout": timeout}
+        if self.socket_path is not None:
+            client_kwargs["transport"] = httpx.AsyncHTTPTransport(uds=self.socket_path)
+        async with httpx.AsyncClient(**client_kwargs) as http:
+            response = await http.request(method, f"{self._http_base}{path}", **kwargs)
         if response.status_code >= 400:
             raise CoreApiError(response)
         return response.json()

{core_cli-2.0.0 → core_cli-2.1.0}/src/core_cli/resources/proposals/manage.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import sys
 from datetime import datetime
 
 import httpx
@@ -62,6 +63,102 @@ def _print_detailed_info(p: dict) -> None:
         console.print(f"\n[red]Failure Reason: {failure_reason}[/red]")
 
 
+def _mark(ok: object) -> str:
+    return "[green]yes[/green]" if ok else "[red]NO[/red]"
+
+
+def _print_review(p: dict) -> None:
+    """The approver's view (CORE ADR-168 Amendment 2026-10-10 R3/R4): who
+    wrote it and why, what it retires, what CORE checked, what resembles it,
+    which decisions touch it. Shown only when the proposal carries them."""
+    constraints = p.get("constitutional_constraints") or {}
+    prov = constraints.get("provenance")
+    if not isinstance(prov, dict):
+        console.print(
+            "\n[yellow]This proposal predates who-and-why records "
+            "(no provenance).[/yellow]"
+        )
+        return
+    console.print("\n[bold]Why it exists:[/bold]")
+    console.print(f"  Anchor: {prov.get('anchor_kind')}")
+    for ref in prov.get("anchor_refs") or []:
+        console.print(f"    {ref}")
+    console.print(f"  Problem owner: {prov.get('problem_owner')}")
+    console.print(f"  Written by: {prov.get('producer')}")
+
+    step_zero = constraints.get("step_zero") or {}
+    retires = step_zero.get("retires")
+    console.print("\n[bold]What it retires:[/bold]")
+    if not retires:
+        console.print("  nothing claimed")
+    for row in retires or []:
+        console.print(
+            f"  {_mark(row.get('verified'))}  {row.get('entry')} - {row.get('reason')}"
+        )
+
+    results = p.get("validation_results") or {}
+    if results:
+        console.print("\n[bold]What CORE checked:[/bold]")
+        for check, ok in sorted(results.items()):
+            console.print(f"  {_mark(ok)}  {check}")
+
+    look = step_zero.get("look_alikes") or {}
+    if look:
+        console.print("\n[bold]Similar existing code:[/bold]")
+        status = look.get("status")
+        if status == "unavailable":
+            console.print(f"  [yellow]not searched: {look.get('reason')}[/yellow]")
+        elif status == "nothing_new":
+            console.print("  no new public function or class")
+        for sym in look.get("symbols") or []:
+            console.print(f"  {sym.get('file')}::{sym.get('symbol')}")
+            for m in (sym.get("matches") or [])[:3]:
+                console.print(
+                    f"    {m.get('score')}  {m.get('file')}::{m.get('symbol')}"
+                )
+
+    decisions = step_zero.get("decisions") or {}
+    mentions = decisions.get("mentions") or {}
+    history = decisions.get("history") or {}
+    if mentions or history:
+        console.print("\n[bold]Decisions touching these files:[/bold]")
+        for path in sorted(set(mentions) | set(history)):
+            named = [
+                f"{a.get('id')} ({a.get('status')})" for a in mentions.get(path) or []
+            ]
+            cited = history.get(path)
+            cited_text = (
+                "history unreadable"
+                if cited is None and path in history
+                else ", ".join(cited or [])
+            )
+            console.print(f"  {path}")
+            if named:
+                console.print(f"    mentioned in: {', '.join(named)}")
+            if cited_text:
+                console.print(f"    cited by past commits: {cited_text}")
+
+
+def _typed_confirmation(proposal_id: str) -> bool:
+    """CORE ADR-168 R2: approval is typed by the human at a real terminal.
+
+    A speed bump, not identity proof (CORE #942): a session without a
+    terminal is refused; a person must type the proposal's short id.
+    """
+    if not sys.stdin.isatty():
+        console.print(
+            "[red]Approval needs a person at a real terminal (CORE ADR-168 R2). "
+            "Not approved.[/red]"
+        )
+        return False
+    expected = proposal_id[:8]
+    typed = typer.prompt(f"Type {expected} to approve this proposal", default="")
+    if typed.strip() != expected:
+        console.print("[yellow]Did not match. Not approved.[/yellow]")
+        return False
+    return True
+
+
 def _print_execution_summary(result: dict) -> None:
     if not result.get("ok") and "actions_executed" not in result:
         console.print(f"Error: {result.get('error', 'Unknown error')}")
@@ -92,6 +189,7 @@ async def show_proposal(proposal_id: str = typer.Argument(...)) -> None:
             raise typer.Exit(1) from exc
         raise
     _print_detailed_info(proposal)
+    _print_review(proposal)
 
 
 @core_command(dangerous=False)
@@ -105,8 +203,23 @@ async def approve_proposal(
         help="Authority under which approval is granted (URS NFR.5).",
     ),
 ) -> None:
-    """Authorize a pending proposal for execution."""
+    """Authorize a pending proposal for execution.
+
+    Shows the proposal and its review, then asks the person at the terminal
+    to type the proposal's short id. Refused without a terminal.
+    """
     client = CoreApiClient()
+    try:
+        proposal = await client.get_proposal(proposal_id)
+    except httpx.HTTPStatusError as exc:
+        if exc.response.status_code == 404:
+            console.print(f"[red]Proposal {proposal_id} not found.[/red]")
+            raise typer.Exit(1) from exc
+        raise
+    _print_detailed_info(proposal)
+    _print_review(proposal)
+    if not _typed_confirmation(proposal["proposal_id"]):
+        raise typer.Exit(1)
     try:
         response = await client.approve_proposal(
             proposal_id, approved_by=by, approval_authority=authority

{core_cli-2.0.0 → core_cli-2.1.0}/tests/test_client.py

@@ -8,6 +8,7 @@ raises what those handlers catch.
 
 from __future__ import annotations
 
+import asyncio
 from unittest.mock import patch
 
 import httpx
@@ -52,3 +53,55 @@ async def test_lane_next_404_reports_empty_lane(capsys: pytest.CaptureFixture) -
     with _serve(404, {"detail": "no delegated findings"}):
         await next_finding.__wrapped__()
     assert "Lane is empty" in capsys.readouterr().out
+
+
+# -- Unix socket transport (CORE_API_URL=unix:///...) ------------------------
+
+
+def test_parse_base_url_http_is_unchanged() -> None:
+    assert client_mod.parse_base_url("http://10.0.0.5:8000") == (
+        "http://10.0.0.5:8000",
+        None,
+    )
+
+
+def test_parse_base_url_unix_gives_socket_path() -> None:
+    assert client_mod.parse_base_url("unix:///run/core/api.sock") == (
+        "http://localhost",
+        "/run/core/api.sock",
+    )
+
+
+def test_parse_base_url_unix_relative_path_is_refused() -> None:
+    with pytest.raises(ValueError, match="absolute path"):
+        client_mod.parse_base_url("unix://run/core/api.sock")
+
+
+def test_env_unix_url_selects_socket(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("CORE_API_URL", "unix:///run/core/api.sock")
+    assert CoreApiClient().socket_path == "/run/core/api.sock"
+
+
+async def test_request_travels_over_the_unix_socket(
+    tmp_path_factory: pytest.TempPathFactory,
+) -> None:
+    """A real HTTP exchange over a real Unix socket, not a mocked transport."""
+    socket_path = tmp_path_factory.mktemp("uds") / "api.sock"
+    seen: list[bytes] = []
+
+    async def handle(reader: asyncio.StreamReader, writer: asyncio.StreamWriter):
+        seen.append(await reader.readuntil(b"\r\n\r\n"))
+        body = b'{"proposals": []}'
+        writer.write(
+            b"HTTP/1.1 200 OK\r\nContent-Type: application/json\r\n"
+            b"Content-Length: " + str(len(body)).encode() + b"\r\n"
+            b"Connection: close\r\n\r\n" + body
+        )
+        await writer.drain()
+        writer.close()
+
+    server = await asyncio.start_unix_server(handle, path=str(socket_path))
+    async with server:
+        client = CoreApiClient(f"unix://{socket_path}")
+        assert await client.list_proposals() == {"proposals": []}
+    assert seen[0].startswith(b"GET /v1/proposals?limit=50 HTTP/1.1")

{core_cli-2.0.0 → core_cli-2.1.0}/tests/test_proposals.py

@@ -4,6 +4,7 @@
 
 from __future__ import annotations
 
+from contextlib import contextmanager
 from unittest.mock import AsyncMock, MagicMock, patch
 
 import httpx
@@ -168,16 +169,36 @@ async def test_show_proposal_not_found() -> None:
 # ---------------------------------------------------------------------------
 
 
-async def test_approve_proposal_success() -> None:
-    mock_client = _make_client()
+@contextmanager
+def _terminal(typed: str | None = "abc123de", tty: bool = True):
+    """A person at a real terminal typing *typed* (CORE ADR-168 R2)."""
+    stdin = MagicMock()
+    stdin.isatty.return_value = tty
+    with (
+        patch("core_cli.resources.proposals.manage.sys.stdin", stdin),
+        patch(
+            "core_cli.resources.proposals.manage.typer.prompt", return_value=typed
+        ) as prompt,
+    ):
+        yield prompt
+
 
+async def _approve(mock_client: AsyncMock, proposal_id: str = "abc123") -> None:
     with patch(_MANAGE_CLIENT, return_value=mock_client):
         await approve_proposal.__wrapped__(
-            proposal_id="abc123",
+            proposal_id=proposal_id,
             by="cli_admin",
             authority="principal.governor",
         )
 
+
+async def test_approve_proposal_success() -> None:
+    mock_client = _make_client()
+
+    with _terminal() as prompt:
+        await _approve(mock_client)
+
+    assert "abc123de" in prompt.call_args.args[0]
     mock_client.approve_proposal.assert_called_once_with(
         "abc123",
         approved_by="cli_admin",
@@ -185,36 +206,93 @@ async def test_approve_proposal_success() -> None:
     )
 
 
+async def test_approve_refused_without_a_terminal() -> None:
+    """A session with no terminal (e.g. a model's shell) cannot approve."""
+    mock_client = _make_client()
+
+    with _terminal(tty=False) as prompt, pytest.raises(typer.Exit) as exc_info:
+        await _approve(mock_client)
+
+    assert exc_info.value.exit_code == 1
+    prompt.assert_not_called()
+    mock_client.approve_proposal.assert_not_called()
+
+
+async def test_approve_refused_when_the_typed_id_does_not_match() -> None:
+    mock_client = _make_client()
+
+    with _terminal(typed="yes"), pytest.raises(typer.Exit):
+        await _approve(mock_client)
+
+    mock_client.approve_proposal.assert_not_called()
+
+
 async def test_approve_proposal_not_found() -> None:
     mock_client = _make_client()
-    mock_client.approve_proposal.side_effect = _http_error(404)
+    mock_client.get_proposal.side_effect = _http_error(404)
 
-    with patch(_MANAGE_CLIENT, return_value=mock_client):
-        with pytest.raises(typer.Exit) as exc_info:
-            await approve_proposal.__wrapped__(
-                proposal_id="missing",
-                by="cli_admin",
-                authority="principal.governor",
-            )
+    with _terminal(), pytest.raises(typer.Exit) as exc_info:
+        await _approve(mock_client, "missing")
 
     assert exc_info.value.exit_code == 1
+    mock_client.approve_proposal.assert_not_called()
 
 
 async def test_approve_proposal_bad_request_prints_detail() -> None:
     mock_client = _make_client()
     mock_client.approve_proposal.side_effect = _http_error(400, "already approved")
 
-    with patch(_MANAGE_CLIENT, return_value=mock_client):
-        with pytest.raises(typer.Exit) as exc_info:
-            await approve_proposal.__wrapped__(
-                proposal_id="abc123",
-                by="cli_admin",
-                authority="principal.governor",
-            )
+    with _terminal(), pytest.raises(typer.Exit) as exc_info:
+        await _approve(mock_client)
 
     assert exc_info.value.exit_code == 1
 
 
+async def test_show_renders_who_why_and_step_zero(capsys) -> None:
+    proposal = _sample_proposal()
+    proposal["validation_results"] = {"full_audit": True, "tests": False}
+    proposal["constitutional_constraints"] = {
+        "provenance": {
+            "anchor_kind": "governor_request",
+            "anchor_refs": ["add a status line"],
+            "problem_owner": "governor",
+            "producer": "claude-session:core-darek",
+            "retires": ["src/old.py"],
+        },
+        "step_zero": {
+            "retires": [
+                {
+                    "entry": "src/old.py",
+                    "verified": True,
+                    "reason": "deleted by the patch",
+                }
+            ],
+            "look_alikes": {"status": "unavailable", "reason": "qdrant down"},
+            "decisions": {
+                "mentions": {"src/old.py": [{"id": "ADR-005", "status": "accepted"}]},
+                "history": {"src/old.py": None},
+            },
+        },
+    }
+    mock_client = _make_client()
+    mock_client.get_proposal.return_value = proposal
+
+    with patch(_MANAGE_CLIENT, return_value=mock_client):
+        await show_proposal.__wrapped__(proposal_id="abc123")
+
+    out = capsys.readouterr().out
+    for text in (
+        "add a status line",
+        "claude-session:core-darek",
+        "deleted by the patch",
+        "full_audit",
+        "not searched: qdrant down",
+        "ADR-005 (accepted)",
+        "history unreadable",
+    ):
+        assert text in out, text
+
+
 # ---------------------------------------------------------------------------
 # execute_proposal
 # ---------------------------------------------------------------------------