wandelbots-novaflow 0.1.0.dev1__py3-none-any.whl

novaflow/cli/__init__.py

@@ -0,0 +1,20 @@
+"""The `nf` command-line tool for novaflow action authors.
+
+`nf` is the single user-facing entry point for novaflow developer
+tooling. Today it hosts:
+
+  * `nf actions lint`        — heuristic halt-cleanup check
+  * `nf actions conformance` — halt-conformance harness driver (stub)
+
+Future commands (planned, not yet wired):
+
+  * `nf actions list`        — show handlers discovered in the package
+  * `nf actions validate`    — schema/signature check at dev-time
+  * `nf actions new`         — scaffold a new action service
+  * `nf trees validate`      — schema-check a behaviour-tree JSON
+  * `nf services list`       — query a control-plane for registered services
+
+The pattern: every subcommand is a thin wrapper over functionality
+that already exists in the SDK or schemas. The CLI exists so devs
+only have to learn one command, not five module paths.
+"""

novaflow/cli/actions/__init__.py

@@ -0,0 +1 @@
+"""`nf actions ...` — developer tooling for novaflow action services."""

novaflow/cli/actions/conformance.py

@@ -0,0 +1,47 @@
+"""`nf actions conformance` — halt-conformance harness driver.
+
+Today this is a stub: the harness API
+(`novaflow.conformance.HaltConformanceHarness`) is the supported way
+to write conformance tests, and devs run them under pytest. See
+`docs/halt-conformance.md` for a worked example.
+
+The CLI form here will, in a later step, auto-discover handlers in
+`src/actions/` and write a halt-conformance attestation into the
+action manifest — but per-handler harness wiring (which adapter,
+which fixture, which halt timing) is action-specific, so the pytest
+form remains the source of truth for now.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+
+def add_parser(subparsers: argparse._SubParsersAction) -> argparse.ArgumentParser:
+    p = subparsers.add_parser(
+        "conformance",
+        help="halt-conformance harness driver (stub)",
+        description=(
+            "Halt-conformance is run via the Python harness API "
+            "under pytest today. This CLI will gain auto-discovery "
+            "and manifest-attestation in a later step. For now, "
+            "see docs/halt-conformance.md."
+        ),
+    )
+    p.set_defaults(_run=run)
+    return p
+
+
+def run(args: argparse.Namespace) -> int:
+    print(
+        "nf actions conformance: not yet implemented as a CLI driver.\n"
+        "\n"
+        "Write conformance cases against your handlers using the harness "
+        "API and run them under pytest:\n"
+        "\n"
+        "  from novaflow.conformance import HaltConformanceHarness\n"
+        "  from novaflow.conformance.adapters.httpx import HttpxAdapter\n"
+        "\n"
+        "See docs/halt-conformance.md for a worked example.\n"
+    )
+    return 0

novaflow/cli/actions/lint.py

@@ -0,0 +1,73 @@
+"""`nf actions lint` — wrap the halt-cleanup heuristic lint rule.
+
+This subcommand is a thin shell around `novaflow.lint.halt.main`. It
+exists so devs run one command (`nf actions lint`) instead of
+remembering the module path (`uv run -m novaflow.lint.halt`).
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from novaflow.lint.halt import analyze_paths, _format_warning
+
+
+def add_parser(subparsers: argparse._SubParsersAction) -> argparse.ArgumentParser:
+    p = subparsers.add_parser(
+        "lint",
+        help="halt-cleanup heuristic check (warning-only)",
+        description=(
+            "Scan Python files for action handlers that acquire a "
+            "resource without a paired cleanup (no `async with`, no "
+            "`.close()`, no `halt.on_halt`, not returned). The rule "
+            "is heuristic (~70%% TP / ~30%% FP per Spike I); use it "
+            "as a developer aid, not as a CI gate. The conformance "
+            "harness (`nf actions conformance`) is the authoritative "
+            "safety check."
+        ),
+    )
+    p.add_argument(
+        "paths",
+        nargs="*",
+        default=["src/actions"],
+        help=(
+            "Paths to scan. Default: `src/actions` (the conventional "
+            "novaflow action-handler location). Pass a different "
+            "path or paths to override."
+        ),
+    )
+    p.set_defaults(_run=run)
+    return p
+
+
+def run(args: argparse.Namespace) -> int:
+    paths = [Path(p).resolve() for p in args.paths]
+    missing = [p for p in paths if not p.exists()]
+    if missing:
+        print(
+            f"nf actions lint: paths not found: "
+            f"{', '.join(str(p) for p in missing)}",
+            file=__import__("sys").stderr,
+        )
+        return 2
+
+    common = paths[0] if len(paths) == 1 else None
+    handler_count, warnings = analyze_paths(paths)
+
+    print(f"Inspected {handler_count} action handlers; {len(warnings)} warnings.")
+    if warnings:
+        print()
+        print("Warnings (file:line — variable acquired without obvious cleanup):")
+        for w in warnings:
+            print(_format_warning(w, root=common))
+        print()
+        print("=" * 60)
+        print("Note: this rule is heuristic (~70% TP / ~30% FP).")
+        print("The conformance harness (real-server observation) is the")
+        print("authoritative safety check. Common false-positive shapes:")
+        print("  * Legacy handlers written before the SDK existed")
+        print("  * Module-scope clients initialised in on_startup")
+        print("  * Returned values where the caller is responsible for cleanup")
+    # Always exit 0 — advisory rule, not a CI gate.
+    return 0

novaflow/cli/main.py

@@ -0,0 +1,83 @@
+"""Entry point and subcommand dispatcher for the `nf` CLI.
+
+Argparse-based for minimum dependencies. Subcommand modules expose
+two things:
+
+  * `add_parser(subparsers) -> argparse.ArgumentParser` — registers
+    its flags and options
+  * `run(args) -> int`                                  — executes
+    the subcommand, returns the process exit code
+
+This contract keeps each subcommand self-contained; adding a new
+one is `register_subcommand(subparsers, mod)` in `_build_parser()`.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Any
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="nf",
+        description=(
+            "Developer tooling for novaflow action services. "
+            "Run `nf <command> --help` for details on a subcommand."
+        ),
+    )
+    parser.set_defaults(_run=None)
+
+    subparsers = parser.add_subparsers(
+        title="commands",
+        dest="command",
+        metavar="COMMAND",
+    )
+
+    # `nf actions ...`
+    actions_parser = subparsers.add_parser(
+        "actions",
+        help="action-author tooling (lint, conformance, …)",
+        description=(
+            "Tooling for novaflow action services. Run from the "
+            "package root (the directory containing `pyproject.toml` "
+            "and `src/actions/`)."
+        ),
+    )
+    actions_sub = actions_parser.add_subparsers(
+        title="action commands",
+        dest="actions_command",
+        metavar="SUBCOMMAND",
+    )
+    # When invoked as `nf actions` with no subcommand, print this
+    # parser's help (not the top-level one).
+    actions_parser.set_defaults(_run=lambda _args: (actions_parser.print_help() or 0))
+
+    # Subcommand modules are imported lazily inside their `add_parser`
+    # so import errors in one don't break the whole CLI.
+    from novaflow.cli.actions import lint as lint_cmd
+    lint_cmd.add_parser(actions_sub)
+
+    from novaflow.cli.actions import conformance as conformance_cmd
+    conformance_cmd.add_parser(actions_sub)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    run: Any = getattr(args, "_run", None)
+    if run is None:
+        # No subcommand chosen — print help and exit 0 (consistent
+        # with `git`, `docker`, etc.).
+        parser.print_help()
+        return 0
+
+    return run(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

novaflow/conformance/__init__.py

@@ -0,0 +1,58 @@
+"""Halt-conformance harness for novaflow action services.
+
+The harness verifies that an action handler's halt path actually
+releases the resources it acquired — a property the lint rule
+(novaflow.lint.halt) can only approximate by AST shape. The
+authoritative check is to observe real-server state after a halt
+fires: did the connection drop? did the transaction roll back? did
+the websocket close?
+
+Architecture:
+
+  * `HaltConformanceHarness` orchestrates the test flow: spin up the
+    real dependency, install the adapter's observation hook, dispatch
+    the handler, fire halt mid-execution, query the server.
+  * `Adapter` (protocol) — per-library plugin that knows how to spin
+    up a test container, observe its own resource state, and tear down.
+    Built-in adapters: synthetic (in-process fake; used by the
+    harness's own self-tests) and httpx (in-process asyncio HTTP
+    server with TCP-level peer-close detection — the canonical
+    real-server demo). Custom backends (postgres, gRPC, MQTT, …)
+    are easy to add via the small `Adapter` protocol; see
+    `docs/halt-conformance.md`.
+  * `ResourceTracker` — adapter-side bookkeeping: each acquire is
+    recorded, each release matched off, leaks reported as unmatched
+    acquires.
+
+This package ships with the SDK; third-party action authors run it
+locally or in their own CI. Today the harness is driven via the
+Python API from a `tests/test_halt_conformance.py` in the action
+package — see `docs/halt-conformance.md`. The typical invocation
+is::
+
+    uv run pytest tests/test_halt_conformance.py
+
+A planned `nf actions conformance` CLI will auto-discover handlers
+and write manifest attestations; that's a follow-up.
+
+The result is an attestation in the action manifest. It is *not* a
+runtime gate — the supervisor SIGKILL floor enforces termination
+regardless. Conformance is the quality bar; SIGKILL is the safety
+floor.
+"""
+
+from novaflow.conformance.harness import (
+    ConformanceFailure,
+    ConformanceResult,
+    HaltConformanceHarness,
+    run_conformance,
+)
+from novaflow.conformance.tracker import ResourceTracker
+
+__all__ = [
+    "ConformanceFailure",
+    "ConformanceResult",
+    "HaltConformanceHarness",
+    "ResourceTracker",
+    "run_conformance",
+]

novaflow/conformance/adapters/__init__.py

@@ -0,0 +1,16 @@
+"""Per-library adapters for the halt-conformance harness.
+
+Each adapter knows how to spin up its real dependency, observe its
+own resource state, and tear down. The harness drives them all
+through the `Adapter` protocol.
+
+Built-in adapters:
+  * synthetic — in-memory fake; used by the harness's own self-tests.
+  * httpx     — in-process asyncio HTTP/1.1 server with TCP-level
+                peer-close detection. The canonical real-server demo;
+                no Docker required.
+
+Custom backends (postgres, gRPC, MQTT, vendor-specific clients) live
+in user code; the small `Adapter` protocol makes them straightforward
+to add. See `docs/halt-conformance.md`.
+"""

novaflow/conformance/adapters/httpx.py

@@ -0,0 +1,284 @@
+"""HTTPX adapter — observes real server-side connection state.
+
+Spike E's pattern applied to HTTP clients: spin up a small in-process
+asyncio HTTP server, run the handler against it, count actual
+connections at the server. This catches the leak shape that matters
+for HTTP-API actions: "handler made a request, got a response, but
+never called `client.close()` on the httpx.AsyncClient" — keeping
+the keepalive socket open at the server.
+
+The server does enough HTTP/1.1 to satisfy `httpx.AsyncClient` for
+GET / POST with keepalive. It's intentionally minimal — not a full
+aiohttp app, just enough to make connection state observable.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import time
+import uuid
+from typing import Any
+
+from novaflow.conformance.tracker import LeakReport, ResourceTracker
+
+# HTTP/1.1 keepalive idle timeout. Long enough to stay open across a
+# few sequential requests in one handler; short enough that a "leaky"
+# handler's connection still shows up in the count when leak_report
+# runs.
+_KEEPALIVE_IDLE_TIMEOUT_S = 30.0
+_DEFAULT_DRAIN_TIMEOUT_S = 2.0
+
+
+class HttpxAdapter:
+    """Adapter for halt-conformance against a small in-process HTTP server.
+
+    Usage::
+
+        async with HttpxAdapter() as adapter:
+            harness = HaltConformanceHarness("MyAction", adapter)
+            harness.add_case(ConformanceCase("get_health", my_handler))
+            result = await harness.run()
+
+    Handlers receive a fixture dict with `base_url`. They build their
+    own httpx.AsyncClient against it. Leak detection runs at the
+    server side — the server tracks `connection_made` /
+    `connection_lost` and reports the live count.
+
+    Endpoints exposed by the test server:
+      * GET  /health → 200 ``{"connected": true}``
+      * POST /echo   → 200 ``{"received": "<body>"}``
+
+    These match the shapes a typical HTTP-backed action handler
+    exercises (the canonical test target for this adapter).
+    """
+
+    name = "httpx"
+
+    def __init__(self, drain_timeout_s: float = _DEFAULT_DRAIN_TIMEOUT_S) -> None:
+        self._drain_timeout_s = drain_timeout_s
+        self._tracker = ResourceTracker()
+        self._server: asyncio.Server | None = None
+        self._port: int | None = None
+        self._app_id = uuid.uuid4().hex[:8]
+        # Live transports keyed by id() so we can count and force-close.
+        self._live_transports: dict[int, asyncio.Transport] = {}
+
+    # -- async context manager -----------------------------------------------
+
+    async def __aenter__(self) -> "HttpxAdapter":
+        self._server = await asyncio.start_server(
+            self._handle_client, host="127.0.0.1", port=0
+        )
+        sock = self._server.sockets[0]
+        self._port = sock.getsockname()[1]
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        # Force-close any leaked connections before tearing down.
+        for t in list(self._live_transports.values()):
+            with contextlib.suppress(Exception):
+                t.close()
+        self._live_transports.clear()
+        if self._server is not None:
+            self._server.close()
+            await self._server.wait_closed()
+            self._server = None
+
+    async def reset_for_case(self) -> None:
+        """Drain the live-transport ledger before the next case starts.
+
+        Without this, a keepalive connection that the previous case's
+        BalanceClient (or equivalent) opened and didn't immediately
+        drop at the server still shows in `_live_transports` when
+        the next case's leak check runs — masquerading as a leak the
+        new case caused.
+
+        Force-aborting the transport (rather than `close()`) makes
+        the per-connection handler's `reader.readuntil` see EOF
+        immediately. Plain `transport.close()` schedules a graceful
+        shutdown that may not propagate before the next case begins
+        under pytest-asyncio's per-test loop scheduling.
+        """
+        for t in list(self._live_transports.values()):
+            with contextlib.suppress(Exception):
+                # `abort()` skips the graceful close; the handler's
+                # readuntil sees EOF or ConnectionError on the next
+                # tick and exits.
+                t.abort()
+        # Poll until handlers actually drain themselves (each handler
+        # pops its own entry in the `finally` block).
+        deadline = time.monotonic() + 1.0
+        while self._live_transports and time.monotonic() < deadline:
+            await asyncio.sleep(0.02)
+        self._live_transports.clear()
+
+    # -- harness protocol ----------------------------------------------------
+
+    @property
+    def tracker(self) -> ResourceTracker:
+        return self._tracker
+
+    def fixture(self) -> dict[str, Any]:
+        if self._port is None:
+            raise RuntimeError(
+                "HttpxAdapter.fixture() called outside async with"
+            )
+        return {
+            "base_url": f"http://127.0.0.1:{self._port}",
+            "app_id": self._app_id,
+        }
+
+    # -- real-server observation --------------------------------------------
+
+    def count_server_conns(self) -> int:
+        """How many live client connections does the server hold?"""
+        return len(self._live_transports)
+
+    async def wait_for_zero_conns(
+        self, timeout_s: float | None = None
+    ) -> tuple[bool, float]:
+        """Poll until the server reports zero live connections."""
+        budget = timeout_s if timeout_s is not None else self._drain_timeout_s
+        deadline = time.monotonic() + budget
+        t0 = time.monotonic()
+        while time.monotonic() < deadline:
+            if self.count_server_conns() == 0:
+                return True, time.monotonic() - t0
+            await asyncio.sleep(0.05)
+        return False, time.monotonic() - t0
+
+    async def collect_leak_report(self) -> LeakReport:
+        """Async leak hook called by the harness — polls until the
+        server reports zero live conns or the drain budget expires."""
+        ok, elapsed = await self.wait_for_zero_conns()
+        if ok:
+            return LeakReport(leaked=[], total_acquires=0, total_releases=0)
+
+        from novaflow.conformance.tracker import _Acquired
+
+        n = self.count_server_conns()
+        acquired_at_ms = (time.monotonic() - elapsed) * 1000
+        leaked = [
+            _Acquired(
+                handle_id=tid,
+                resource_kind="httpx.server_connection",
+                acquired_at_ms=acquired_at_ms,
+                metadata={
+                    "drain_timeout_s": self._drain_timeout_s,
+                    "drain_elapsed_s": round(elapsed, 3),
+                },
+            )
+            for tid in list(self._live_transports.keys())
+        ]
+        return LeakReport(leaked=leaked, total_acquires=n, total_releases=0)
+
+    # -- HTTP server (minimal HTTP/1.1) -------------------------------------
+
+    async def _handle_client(
+        self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter
+    ) -> None:
+        """One client connection. Loops over requests on the same
+        socket (keep-alive) until the client closes or idles out."""
+        transport = writer.transport
+        tid = id(transport)
+        self._live_transports[tid] = transport
+        try:
+            while True:
+                try:
+                    headers_blob = await asyncio.wait_for(
+                        reader.readuntil(b"\r\n\r\n"),
+                        timeout=_KEEPALIVE_IDLE_TIMEOUT_S,
+                    )
+                except (asyncio.TimeoutError, asyncio.IncompleteReadError, ConnectionError):
+                    break
+                if not headers_blob:
+                    break
+
+                # Parse just enough to dispatch on path.
+                request_line, _, rest = headers_blob.partition(b"\r\n")
+                try:
+                    method, path, _ = request_line.decode("ascii", errors="replace").split(" ", 2)
+                except ValueError:
+                    break
+
+                # Drain Content-Length body if present so the next
+                # request on this keepalive connection finds clean
+                # bytes.
+                content_length = 0
+                for line in rest.split(b"\r\n"):
+                    lower = line.lower()
+                    if lower.startswith(b"content-length:"):
+                        try:
+                            content_length = int(line.split(b":", 1)[1].strip())
+                        except ValueError:
+                            content_length = 0
+                        break
+                body = b""
+                if content_length > 0:
+                    body = await reader.readexactly(content_length)
+
+                # `/very_slow` blocks the response so a halt fired
+                # mid-request actually catches the request in flight.
+                # Race the sleep against a peer-close detector: if the
+                # client closes its end (mid-flight cancel), `reader.read`
+                # returns immediately and we bail before responding —
+                # mirroring how a real production HTTP server (uvicorn,
+                # aiohttp) handles peer-close during a slow handler.
+                # Without this, the test fixture would falsely flag
+                # leaks because it sat blocked on a fixed-time sleep
+                # while the TCP socket had already been hung up by the
+                # client.
+                if path.split("?", 1)[0] == "/very_slow":
+                    sleep_task = asyncio.create_task(asyncio.sleep(2.0))
+                    peer_close = asyncio.create_task(reader.read(1))
+                    done, pending = await asyncio.wait(
+                        [sleep_task, peer_close],
+                        return_when=asyncio.FIRST_COMPLETED,
+                    )
+                    for t in pending:
+                        t.cancel()
+                        with contextlib.suppress(asyncio.CancelledError, Exception):
+                            # CodeQL FP (py/ineffectual-statement):
+                            # awaited to drain the cancelled task; the
+                            # value is irrelevant.
+                            await t
+                    if peer_close in done:
+                        # Client closed the socket — exit the keepalive
+                        # loop, server's `finally` will clean up.
+                        return
+
+                response = self._dispatch(method, path, body)
+                writer.write(response)
+                await writer.drain()
+        finally:
+            self._live_transports.pop(tid, None)
+            with contextlib.suppress(Exception):
+                writer.close()
+                await writer.wait_closed()
+
+    def _dispatch(self, method: str, path: str, body: bytes) -> bytes:
+        """Tiny router. Returns a complete HTTP/1.1 response."""
+        # Strip query string if present.
+        path_only = path.split("?", 1)[0]
+        if method == "GET" and path_only == "/health":
+            return _build_response(200, b'{"connected": true}')
+        if method == "POST" and path_only == "/echo":
+            payload = b'{"received": ' + (body or b'""') + b"}"
+            return _build_response(200, payload)
+        if method == "GET" and path_only in ("/slow", "/very_slow"):
+            # Note: only `/very_slow` actually delays — the connection
+            # handler sleeps before calling _dispatch for that path.
+            return _build_response(200, b'{"slow": "ok"}')
+        return _build_response(404, b'{"error": "not found"}')
+
+
+def _build_response(status: int, body: bytes) -> bytes:
+    reason = {200: "OK", 404: "Not Found"}.get(status, "OK")
+    return (
+        f"HTTP/1.1 {status} {reason}\r\n"
+        f"Content-Type: application/json\r\n"
+        f"Content-Length: {len(body)}\r\n"
+        f"Connection: keep-alive\r\n"
+        f"\r\n"
+    ).encode("ascii") + body