Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.
Decouple pipelex-tools, add plxt tests, rule sync (#791)
Louis Choquelae86f057b828
diff --git a/CLAUDE.md b/CLAUDE.mdindex d96e829a3..16df444c9 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -30,7 +30,9 @@### Running Tests- After you're finished making code changes, you must always run tests using `make agent-test`.+ After making code changes, run **targeted tests** based on what you changed. See `tests/CLAUDE.md` for the source-to-test mapping and the pytest command template.++ Fall back to the full suite when changes are broad (3+ areas), touch shared infrastructure, or when preparing a release/push/commit to remote:```bashmake agent-test@@ -144,7 +146,7 @@ This document outlines the core coding standards, best practices, and quality co#### **Imports at the top of the file**- - Import all necessary libraries at the top of the file+ - Avoid as much as possible import statements outside of a module's top-level scope.- Do not import libraries in functions or classes unless in very specific cases, to be discussed with the user, as they would required a `# noqa: ...` comment to pass linting- Do not bother with ordering the imports or removing unused imports, our Ruff linter will handle it for us.- `if TYPE_CHECKING:` blocks must always be the **last** block in the imports section, placed after all regular imports.diff --git a/pipelex/cli/agent_cli/commands/agent_output.py b/pipelex/cli/agent_cli/commands/agent_output.pyindex bc54648c0..0696b1faf 100644--- a/pipelex/cli/agent_cli/commands/agent_output.py+++ b/pipelex/cli/agent_cli/commands/agent_output.py@@ -46,7 +46,7 @@ AGENT_ERROR_HINTS: dict[str, str] = {"GatewayTermsNotAcceptedError": "Run 'pipelex init config' to accept gateway terms, or disable pipelex_gateway in backends.toml","GatewayApiKeyMissingError": "Set the PIPELEX_GATEWAY_API_KEY environment variable, or disable pipelex_gateway in backends.toml","GatewayDoNotTrackConflictError": "Unset the DO_NOT_TRACK environment variable, or disable pipelex_gateway in backends.toml",- "BinaryNotFoundError": "Install pipelex-tools: pip install pipelex-tools",+ "BinaryNotFoundError": "Install pipelex-tools: uv tool install pipelex-tools","RemoteConfigFetchError": "Check internet connection and firewall settings, or disable pipelex_gateway in backends.toml","RemoteConfigValidationError": ("This is a server-side issue; report it on Discord/GitHub. Disable pipelex_gateway in backends.toml as a workaround"diff --git a/pipelex/cli/agent_cli/commands/plxt_passthrough.py b/pipelex/cli/agent_cli/commands/plxt_passthrough.pyindex 9bd2ca0a0..dc8474e1f 100644--- a/pipelex/cli/agent_cli/commands/plxt_passthrough.py+++ b/pipelex/cli/agent_cli/commands/plxt_passthrough.py@@ -11,8 +11,8 @@ from pipelex.cli.agent_cli.commands.agent_output import agent_errordef run_plxt(subcommand: str, file_path: str) -> None:"""Execute a plxt subcommand with full stdin/stdout/stderr passthrough.- Locates the plxt binary (guaranteed co-installed via pipelex-tools dependency),- runs ``plxt <subcommand> <file_path>``, and exits with the same return code.+ Locates the plxt binary, runs ``plxt <subcommand> <file_path>``,+ and exits with the same return code.Args:subcommand: The plxt subcommand to run (e.g., "fmt", "lint").@@ -21,7 +21,7 @@ def run_plxt(subcommand: str, file_path: str) -> None:plxt_path = shutil.which("plxt")if plxt_path is None:agent_error(- message="plxt binary not found. It should be installed as part of pipelex-tools. Try: pip install pipelex-tools",+ message="plxt binary not found. Install via: uv tool install pipelex-tools",error_type="BinaryNotFoundError",)diff --git a/pyproject.toml b/pyproject.tomlindex efa44ac3a..b50291b77 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -36,7 +36,6 @@ dependencies = ["opentelemetry-semantic-conventions","opentelemetry-sdk","pillow>=11.2.1",- "pipelex-tools>=0.3.2", # plxt CLI for MTHDS/TOML/PLX formatting & linting, needed by client projects too"polyfactory>=2.21.0","portkey-ai>=2.1.0","posthog>=6.7.0",@@ -87,6 +86,7 @@ dev = ["boto3-stubs>=1.35.24","moto[s3]>=5.0.0","mypy==1.19.1",+ "pipelex-tools>=0.3.2","pyright==1.1.408","pylint==4.0.4","pytest>=9.0.2",diff --git a/tests/CLAUDE.md b/tests/CLAUDE.mdnew file mode 100644index 000000000..71b215cd7--- /dev/null+++ b/tests/CLAUDE.md@@ -0,0 +1,64 @@+# Targeted Test Guide++Instead of running the full suite (`make agent-test`) every time, run only the tests relevant to what you changed.++## Command template++```bash+.venv/bin/pytest -n auto \+ -m "(dry_runnable or not (inference or llm or img_gen or extract or search)) and not pipelex_api" \+ -o log_level=WARNING --tb=short -q \+ <paths>+```++Replace `<paths>` with the test directories from the mapping below. Concatenate paths when multiple source areas are touched.++## Source-to-test mapping++| Changed source | Test paths to run |+|---|---|+| `pipelex/builder/` | `tests/unit/pipelex/builder/ tests/integration/pipelex/builder/` |+| `pipelex/cli/` | `tests/unit/pipelex/cli/ tests/integration/pipelex/cli/ tests/e2e/pipelex/cli/` |+| `pipelex/cogt/` | `tests/unit/pipelex/cogt/ tests/integration/pipelex/cogt/` |+| `pipelex/core/` | `tests/unit/pipelex/core/ tests/integration/pipelex/core/ tests/integration/pipelex/pipes/` |+| `pipelex/graph/` | `tests/unit/pipelex/graph/ tests/e2e/pipelex/graph/` |+| `pipelex/kit/` | `tests/unit/pipelex/kit/ tests/integration/pipelex/kit/` |+| `pipelex/language/` | `tests/unit/pipelex/language/ tests/integration/pipelex/language/` |+| `pipelex/libraries/` | `tests/unit/pipelex/libraries/ tests/integration/pipelex/libraries/` |+| `pipelex/pipe_controllers/` | `tests/unit/pipelex/pipe_controllers/ tests/integration/pipelex/pipes/` |+| `pipelex/pipe_operators/` | `tests/unit/pipelex/pipe_operators/ tests/integration/pipelex/pipes/` |+| `pipelex/pipe_run/` | `tests/unit/pipelex/pipe_run/ tests/integration/pipelex/pipes/` |+| `pipelex/pipeline/` | `tests/integration/pipelex/pipeline/` |+| `pipelex/plugins/` | `tests/unit/pipelex/plugins/ tests/integration/pipelex/plugins/` |+| `pipelex/system/` | `tests/unit/pipelex/system/ tests/integration/pipelex/system/` |+| `pipelex/temporal/` | `tests/unit/pipelex/temporal/ tests/integration/pipelex/temporal/` |+| `pipelex/tools/` | `tests/unit/pipelex/tools/ tests/integration/pipelex/tools/` |++Note: `pipe_controllers/`, `pipe_operators/`, and `pipe_run/` share integration tests at `tests/integration/pipelex/pipes/` -- deduplicate the path when multiple of these areas are touched.++## Cross-cutting triggers++Add these to any targeted run when applicable:++- **Config TOML changes** (`pipelex/pipelex.toml`, `pipelex/kit/configs/`): also run `make tb` (boot test)+- **`.mthds` file changes**: also add `tests/unit/pipelex/builder/ tests/integration/pipelex/builder/ tests/integration/pipelex/pipes/`+- **Test fixtures changed** (`tests/data/`, `tests/cases/`): also run tests that import from those fixtures++## When to run full `make agent-test`++Fall back to the full suite when:++- Changes span 3+ source areas from the mapping above+- Changes touch `pyproject.toml`, `tests/conftest.py`, or `tests/helpers/`+- Changes touch root-level modules: `pipelex/__init__.py`, `pipelex/hub.py`, `pipelex/types.py`+- Changes touch `pipelex/system/configuration/` (config loading affects everything)+- Refactors touching base exceptions or shared base classes+- Preparing a release, a push, or a commit intended for remote (e.g. `/release`, `/commit-push`, `/ship`, or when the context makes it obvious the work is about to land)++## Quick reference++| Command | When to use |+|---|---|+| `make tb` | Config/TOML-only changes (boot sanity check) |+| `make agent-check` | Always run after code changes (linting, formatting, type checking) |+| `make agent-test` | Full suite fallback for broad changes |diff --git a/tests/unit/pipelex/cli/agent_cli/commands/test_plxt_passthrough.py b/tests/unit/pipelex/cli/agent_cli/commands/test_plxt_passthrough.pynew file mode 100644index 000000000..2afe24c18--- /dev/null+++ b/tests/unit/pipelex/cli/agent_cli/commands/test_plxt_passthrough.py@@ -0,0 +1,121 @@+"""Unit tests for plxt passthrough, fmt_cmd, and lint_cmd."""++from __future__ import annotations++import json+import subprocess # noqa: S404+from typing import TYPE_CHECKING++import pytest+import typer++from pipelex.cli.agent_cli.commands.fmt_cmd import fmt_cmd+from pipelex.cli.agent_cli.commands.lint_cmd import lint_cmd+from pipelex.cli.agent_cli.commands.plxt_passthrough import run_plxt++if TYPE_CHECKING:+ from pytest_mock import MockerFixture+++class TestPlxtPassthrough:+ """Tests for run_plxt(), fmt_cmd(), and lint_cmd() delegation to the plxt binary."""++ def test_run_plxt_raises_binary_not_found_error_when_plxt_missing(+ self,+ mocker: MockerFixture,+ capsys: pytest.CaptureFixture[str],+ ) -> None:+ """run_plxt exits with code 1 and BinaryNotFoundError when plxt is not on PATH."""+ mocker.patch("shutil.which", return_value=None)++ with pytest.raises(typer.Exit) as exc_info:+ run_plxt("fmt", "file.mthds")++ assert exc_info.value.exit_code == 1+ parsed = json.loads(capsys.readouterr().err)+ assert parsed["error_type"] == "BinaryNotFoundError"++ def test_error_message_references_uv_tool_install(+ self,+ mocker: MockerFixture,+ capsys: pytest.CaptureFixture[str],+ ) -> None:+ """Error message tells the user how to install pipelex-tools."""+ mocker.patch("shutil.which", return_value=None)++ with pytest.raises(typer.Exit):+ run_plxt("lint", "file.mthds")++ parsed = json.loads(capsys.readouterr().err)+ assert "uv tool install pipelex-tools" in parsed["message"]++ @pytest.mark.parametrize(+ ("topic", "exit_code"),+ [+ ("success", 0),+ ("general failure", 1),+ ("custom exit code", 42),+ ],+ )+ def test_run_plxt_propagates_exit_code(+ self,+ mocker: MockerFixture,+ topic: str, # noqa: ARG002+ exit_code: int,+ ) -> None:+ """run_plxt propagates the subprocess exit code via typer.Exit."""+ mocker.patch("shutil.which", return_value="/usr/bin/plxt")+ mocker.patch(+ "subprocess.run",+ return_value=subprocess.CompletedProcess(args=[], returncode=exit_code),+ )++ with pytest.raises(typer.Exit) as exc_info:+ run_plxt("fmt", "file.mthds")++ assert exc_info.value.exit_code == exit_code++ def test_subprocess_args_passed_correctly(+ self,+ mocker: MockerFixture,+ ) -> None:+ """run_plxt passes [plxt_path, subcommand, file_path] to subprocess.run."""+ mocker.patch("shutil.which", return_value="/usr/bin/plxt")+ mock_run = mocker.patch(+ "subprocess.run",+ return_value=subprocess.CompletedProcess(args=[], returncode=0),+ )++ with pytest.raises(typer.Exit):+ run_plxt("fmt", "/path/to/file.mthds")++ mock_run.assert_called_once_with(+ ["/usr/bin/plxt", "fmt", "/path/to/file.mthds"],+ check=False,+ )++ def test_fmt_cmd_delegates_to_plxt_with_fmt_subcommand(+ self,+ mocker: MockerFixture,+ ) -> None:+ """fmt_cmd calls run_plxt with 'fmt' subcommand."""+ mock_run_plxt = mocker.patch(+ "pipelex.cli.agent_cli.commands.fmt_cmd.run_plxt",+ )++ fmt_cmd("some/file.mthds")++ mock_run_plxt.assert_called_once_with("fmt", "some/file.mthds")++ def test_lint_cmd_delegates_to_plxt_with_lint_subcommand(+ self,+ mocker: MockerFixture,+ ) -> None:+ """lint_cmd calls run_plxt with 'lint' subcommand."""+ mock_run_plxt = mocker.patch(+ "pipelex.cli.agent_cli.commands.lint_cmd.run_plxt",+ )++ lint_cmd("some/file.mthds")++ mock_run_plxt.assert_called_once_with("lint", "some/file.mthds")diff --git a/uv.lock b/uv.lockindex aef707837..65260c78d 100644--- a/uv.lock+++ b/uv.lock@@ -3470,7 +3470,6 @@ dependencies = [{ name = "opentelemetry-sdk" },{ name = "opentelemetry-semantic-conventions" },{ name = "pillow" },- { name = "pipelex-tools" },{ name = "polyfactory" },{ name = "portkey-ai" },{ name = "posthog" },@@ -3500,6 +3499,7 @@ dev = [{ name = "boto3-stubs" },{ name = "moto", extra = ["s3"] },{ name = "mypy" },+ { name = "pipelex-tools" },{ name = "pylint" },{ name = "pyright" },{ name = "pytest" },@@ -3597,7 +3597,7 @@ requires-dist = [{ name = "opentelemetry-sdk" },{ name = "opentelemetry-semantic-conventions" },{ name = "pillow", specifier = ">=11.2.1" },- { name = "pipelex-tools", specifier = ">=0.3.2" },+ { name = "pipelex-tools", marker = "extra == 'dev'", specifier = ">=0.3.2" },{ name = "polyfactory", specifier = ">=2.21.0" },{ name = "portkey-ai", specifier = ">=2.1.0" },{ name = "posthog", specifier = ">=6.7.0" },