pyproject.toml

[build-system]
requires = ["hatchling>=1.21"]
build-backend = "hatchling.build"

[project]
name = "claude-comms"
version = "0.6.0"
description = "Distributed inter-Claude messaging platform"
requires-python = ">=3.10"
license = "MIT"
authors = [{name = "Phil LaFayette", email = "plafaydev@gmail.com"}]
readme = "README.md"
keywords = ["mqtt", "chat", "claude", "mcp", "svelte", "tui"]
classifiers = [
    "Development Status :: 3 - Alpha",
    "Intended Audience :: Developers",
    "License :: OSI Approved :: MIT License",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Programming Language :: Python :: 3.13",
    "Topic :: Communications :: Chat",
    "Topic :: Software Development :: Libraries :: Python Modules",
]
dependencies = [
    # Pinned to the 0.11.x line: the single-origin /mqtt broker bridge depends
    # on the public ``Broker.external_connected`` + ``ExternalServer`` API and
    # the ``ReaderAdapter`` / ``WriterAdapter`` interface (amqtt/adapters.py).
    # Cap below 0.12 so an upstream rename of that API can't break the bridge
    # silently.
    "amqtt>=0.11,<0.12",
    "aiomqtt>=2.0.0",
    # uvicorn needs a WebSocket protocol implementation for the /mqtt bridge.
    # ``websockets`` is already an amqtt transitive dep and uvicorn auto-detects
    # it; pin it explicitly so a WS-capable uvicorn is guaranteed in fresh
    # installs (independent of amqtt's resolution).
    "websockets>=12",
    "mcp>=1.20.0,<2",
    "typer>=0.15.0,<0.16.0",
    "pyyaml>=6.0",
    "rich>=13.0",
    "pydantic>=2.0",
    # pydantic-core imports typing_extensions.Sentinel (PEP 661), added in
    # 4.12.0. Without this floor a clean install can resolve an older
    # typing_extensions and the daemon fails to start with ImportError.
    # Surfaced by the e2e CI gate (daemon spawn in a fresh environment).
    "typing_extensions>=4.12.0",
]

[project.optional-dependencies]
tui = ["textual>=0.80.0"]
web = []
all = ["claude-comms[tui,web]"]
dev = [
    "pytest>=7.0",
    "pytest-asyncio>=0.21",
    # Parallelizes the unit-test suite across CPU cores. The suite is
    # parallel-safe: every test that binds a real socket uses an
    # OS-assigned ephemeral port, and all filesystem state goes through
    # per-test ``tmp_path`` / ``monkeypatch`` (each xdist worker is its own
    # process with its own tmp base), so 8 workers never collide.
    "pytest-xdist>=3.0",
]

[project.scripts]
claude-comms = "claude_comms.cli:app"

[project.urls]
Homepage = "https://github.com/Aztec03hub/claude-comms"
Repository = "https://github.com/Aztec03hub/claude-comms"
Issues = "https://github.com/Aztec03hub/claude-comms/issues"

# Run hatch_build.py during every wheel/sdist build — compiles the Svelte
# web UI and ensures src/claude_comms/web/dist/ is populated before the
# wheel is sealed. No-op when assets are already built (CI prebuild, repeat
# builds, etc.).
[tool.hatch.build.hooks.custom]
path = "hatch_build.py"

[tool.hatch.build.targets.wheel]
packages = ["src/claude_comms"]
# `artifacts` opts gitignored built assets into the wheel. The web UI lives
# under src/claude_comms/web/dist/, which is gitignored (built output), so
# we name it explicitly here.
artifacts = ["src/claude_comms/web/dist/**"]

[tool.hatch.build.targets.sdist]
include = [
    "src/claude_comms/**",
    "web/**",
    "hatch_build.py",
    "pyproject.toml",
    "README.md",
    "LICENSE",
    "CHANGELOG.md",
    "USAGE.md",
    "CONTRIBUTING.md",
]
exclude = [
    "web/node_modules",
    "web/.svelte-kit",
    "web/dist",
    "src/claude_comms/web/dist",
    "web/test-results",
    "web/playwright-report",
    "**/__pycache__",
]

[tool.pytest.ini_options]
testpaths = ["tests"]
# Run the suite in parallel across all CPU cores (pytest-xdist). The suite is
# parallel-safe (ephemeral ports + per-test tmp_path/monkeypatch state), so
# this is a pure wall-clock win with identical results. ``worksteal`` rebalances
# the queue so a worker that finishes its share picks up pending tests from
# busier workers — important because the textual TUI tests are much slower than
# the rest. Override locally with ``-n0`` to force serial (e.g. for a debugger).
addopts = "-n auto --dist=worksteal"
# Targeted warning filters so `pytest -q` runs clean. Each entry silences a
# SPECIFIC, understood category — not a blanket ignore — so a genuinely new
# warning still surfaces.
filterwarnings = [
    # Our own config validator intentionally warns when MQTT auth is enabled
    # without a password set; many CLI/config/hook tests exercise that exact
    # path on purpose (the warning is the behavior under test elsewhere).
    "ignore:MQTT auth is enabled but no password is set:UserWarning",
    # starlette's TestClient drives httpx, which starlette itself now flags as
    # deprecated (StarletteDeprecationWarning subclasses UserWarning). External
    # to us; TestClient is used exactly as documented.
    "ignore:Using `httpx` with `starlette.testclient` is deprecated:UserWarning",
    # Transitive websockets/uvicorn deprecations surfaced through the daemon's
    # websocket bridge (uvicorn + amqtt pull in websockets.legacy). Not
    # actionable from this codebase.
    "ignore:websockets.legacy is deprecated:DeprecationWarning",
    "ignore:websockets.server.WebSocketServerProtocol is deprecated:DeprecationWarning",
    "ignore:remove second argument of ws_handler:DeprecationWarning",
    # passlib (transitive, via the broker auth stack) imports the stdlib
    # ``crypt`` module, deprecated for removal in 3.11+. External.
    "ignore:'crypt' is deprecated and slated for removal:DeprecationWarning",
]

# basedpyright runs in its strict default ("recommended") mode. That mode bundles
# two very different kinds of diagnostics:
#   1. CORRECTNESS rules — real bugs (undefined names, bad args/returns, optional
#      member access, missing imports, redeclarations, attribute errors). These stay ON.
#   2. INFERENCE-STRICTNESS rules — a project-wide style stance demanding fully
#      explicit type annotations on every symbol, parameter, attribute, and generic.
#
# Policy (see PR "Annotate src/ for real"): the SHIPPED PACKAGE (src/) is held to the
# HIGH-VALUE strictness rules — every parameter, generic argument, and class attribute is
# genuinely annotated. To keep that strictness scoped to source WITHOUT churning the test
# suite, dev scripts, or build hooks (which deliberately lean on inference and dynamic
# payloads), the global block below keeps every inference-strictness rule OFF — exactly as
# it shipped — and a single `root = "src"` execution environment turns the high-value ones
# back ON for the package only. tests/, tools/, scripts/, and hatch_build.py therefore keep
# their prior, relaxed treatment; src/ is the one tree that must satisfy the strict rules.
# Re-enable any line to audit that class on demand.
[tool.basedpyright]
# "x has type Any" / explicit `Any` annotations — pervasive with dynamic JSON/dict payloads
# (MQTT messages, MCP tool args, YAML config) where a precise static type does not exist;
# forcing these would push blanket casts everywhere, strictly worse than honest `Any` at the
# boundary. Kept OFF even for src (correctness rules still flag real misuse of those values).
reportAny = false
reportExplicitAny = false
# "type of x is unknown/partially unknown" inference-completeness noise — turned back ON for
# src/ via the executionEnvironment below; OFF here so tests/tools/scripts stay relaxed.
reportUnknownMemberType = false
reportUnknownVariableType = false
reportUnknownParameterType = false
reportUnknownArgumentType = false
reportUnknownLambdaType = false
# Demands explicit annotations on every parameter / generic / class attribute — turned back
# ON for src/ below; OFF here for everything else.
reportMissingParameterType = false
reportMissingTypeArgument = false
reportUnannotatedClassAttribute = false
# Style preferences, not correctness (OFF everywhere, src/ included):
reportImplicitOverride = false            # @override decorator not required here
reportCallInDefaultInitializer = false    # typer.Option(...) defaults are idiomatic
reportUnusedCallResult = false            # not every call result must be bound/used
reportImplicitStringConcatenation = false # intentional multi-line string literals
# Intra-package access of module-level underscore-prefixed helpers (`_registry`,
# `_publish_fn`, `_mqtt_subscriber`, ...) is idiomatic here and the cross-module correctness
# signal is low; renaming them all to public would be churn without value. OFF everywhere.
reportPrivateUsage = false
# Third-party libs (amqtt, textual, mcp, etc.) ship without type stubs — not actionable here.
reportMissingTypeStubs = false

# SOURCE (src/) is the shipped package and is held to the high-value inference-strictness
# rules: every parameter, return, generic argument, and class attribute is genuinely
# annotated (see PR "Annotate src/ for real"). These are turned back ON here at their
# recommended-mode severities (reportMissingTypeArgument is an error; the rest warnings),
# overriding the global OFF above for the source tree only.
[[tool.basedpyright.executionEnvironments]]
root = "src"
reportUnknownMemberType = true
reportUnknownVariableType = true
reportUnknownParameterType = true
reportUnknownArgumentType = true
reportUnknownLambdaType = true
reportMissingParameterType = true
reportMissingTypeArgument = true
reportUnannotatedClassAttribute = true

# SOURCE keeps default unused-symbol / unreachable reporting so genuinely dead code or
# unreachable branches in src/ still surface (the source-tree hits were cleaned in #34).
# The tests/ tree intentionally carries unused throwaways — pytest fixtures pulled in for
# their side effects, signature-parity params, mock callback args — which are noise, so the
# unused/unreachable classes are disabled THERE ONLY via a scoped execution environment.
# (Verified: forcing reportUnusedParameter on globally still reports 0 under tests/.)
# The inference-strictness rules are already OFF globally, so tests/ inherits that and needs
# no extra disables for them.
[[tool.basedpyright.executionEnvironments]]
root = "tests"
reportUnusedParameter = false
reportUnusedVariable = false
reportUnusedFunction = false
reportUnreachable = false
reportUnnecessaryTypeIgnoreComment = false
# Tests deliberately reference a symbol re-exported into another module (to monkeypatch
# the module's own reference); harmless in test code, kept ON for src.
reportPrivateLocalImportUsage = false