Skip to content

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.

feature/Pipelex-root-inputs-file · L-261016-d36082 (#1451)

Louis Choquel0a1679d3d06c
diff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.toml
index 598d1f4ed..d543e5479 100644
--- a/.drift/acks/cli-docs.toml
+++ b/.drift/acks/cli-docs.toml
@@ -1,8 +1,8 @@
contract = "cli-docs"
-digest = "sha256:d1722558e88c5052fb5b204cd39b7caec1acaec8ccf07b1690ff09a9cc9a9ad6"
+digest = "sha256:6e4c4adafc41b29144d9050309870127e58bbc085b899894e2b93e9a543dca63"
reviewed_by = "Louis Choquel"
-reviewed_at = "2026-10-17T01:00:26Z"
-rationale = "real-catch: the fix write scope is now the method tree's root and --diff mirrors that root, build inputs/output load the entry with its whole folder and name the command in failures, a refused tree on agent fix is the FixBundleError envelope, and a pre-boot configuration error is reported as the failed boot; docs/tools/cli/fix.md, validate.md, agent-cli.md, build/inputs.md, build/output.md and pipelex/cli/agent_cli/CLAUDE.md now say so, and validate.md and agent-cli.md say a nested package, a dependency and the -L directories load without being judged."
+reviewed_at = "2026-10-17T05:02:24Z"
+rationale = "real-catch: the auto-detected inputs file is now read through a descriptor opened without following a link and judged by fstat, and its bytes flow to the parsers, so docs/tools/cli/run.md says it is read without following a link and that a link the tree holds refuses the tree itself; the sentences saying the inputs file stays out of the method tree, true only from the mthds release implementing the run-inputs default, are removed from run.md and build/inputs.md. agent-cli.md stays accurate, and pipelex/cli/agent_cli/CLAUDE.md describes no inputs auto-detection."
[trigger_files]
"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"
@@ -43,7 +43,7 @@ rationale = "real-catch: the fix write scope is now the method tree's root and -
"pipelex/cli/agent_cli/commands/run/bundle_cmd.py" = "blob:6ee1041a4b5201cca1863fe9acaa3850c70faf03"
"pipelex/cli/agent_cli/commands/run/method_cmd.py" = "blob:776d1cf4bfbdce645f3cbfcd28be46bfb97174b0"
"pipelex/cli/agent_cli/commands/run/pipe_cmd.py" = "blob:f421c75ee696c18f85a7f63805455ef23637302f"
-"pipelex/cli/agent_cli/commands/run/stdin_resolver.py" = "blob:c7c7d7495508f1c4e5a46eba336a4ab1694ebcf7"
+"pipelex/cli/agent_cli/commands/run/stdin_resolver.py" = "blob:5349c102b62136e7dc26ad74a319f219a40e5a60"
"pipelex/cli/agent_cli/commands/validate/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/agent_cli/commands/validate/_validate_core.py" = "blob:b15fb5ee5b3d84cb229f3eb3353df8354cfd488d"
"pipelex/cli/agent_cli/commands/validate/app.py" = "blob:1982684a2aae81e0d634bb3b262457a5f187d979"
@@ -108,15 +108,15 @@ rationale = "real-catch: the fix write scope is now the method tree's root and -
"pipelex/cli/commands/resolve_cmd.py" = "blob:88237df0f048bbf5a02e585baef932bfc355e1ee"
"pipelex/cli/commands/run/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/commands/run/_hosted_sources.py" = "blob:d2e7efc8e0f9bb5f061d30afc586165c47d2dac8"
-"pipelex/cli/commands/run/_inputs_file_loader.py" = "blob:957e6eb00531d168b3b1e179a517717d069cb7fc"
+"pipelex/cli/commands/run/_inputs_file_loader.py" = "blob:8039ca6b29f4f9091d0ea7406c8b8a4590848131"
"pipelex/cli/commands/run/_inputs_path_resolver.py" = "blob:c8ec89d98718e18af7aaaded44c9f545be60adab"
"pipelex/cli/commands/run/_main_stuff_file.py" = "blob:ca806e55085aa2e5748492751521296ce1f42960"
-"pipelex/cli/commands/run/_run_core.py" = "blob:5b46ee698300deca87491d0491177fd4fe891220"
-"pipelex/cli/commands/run/_run_hosted.py" = "blob:261439461abc1532d16393f33baf32f770207814"
+"pipelex/cli/commands/run/_run_core.py" = "blob:2bc88a004d2d55f6f85c786b133718dd168678c6"
+"pipelex/cli/commands/run/_run_hosted.py" = "blob:80df4e50e7f4ece31ebf4d51e34dbddef9466cae"
"pipelex/cli/commands/run/_run_output_folder.py" = "blob:5834889a5e35e6457acf24761b408bc6a7bbfd6c"
"pipelex/cli/commands/run/app.py" = "blob:e312b159625e0a72bc9a18d3bfd2c73e7ac59f24"
-"pipelex/cli/commands/run/bundle_cmd.py" = "blob:ecb22be793b5cd49ad1a195ec2f40013aa58aff7"
-"pipelex/cli/commands/run/exceptions.py" = "blob:e9552226e597922b6ac0757f7b52eb880a2e1472"
+"pipelex/cli/commands/run/bundle_cmd.py" = "blob:50b6c6e1f931f41a611a979b081f08e560773ce8"
+"pipelex/cli/commands/run/exceptions.py" = "blob:84a90e632e2a1ede6aa9de15ab566b7f3b23b8d6"
"pipelex/cli/commands/run/method_cmd.py" = "blob:924bca6e242d8490e32eeb9ed2329db3d1b58b8d"
"pipelex/cli/commands/run/pipe_cmd.py" = "blob:eafdc4bcf3f3f84042ecf9644e0f17fc355e0e17"
"pipelex/cli/commands/show_cmd.py" = "blob:4c87c70058ea3b15827d03a370f3345569a2b705"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 94597f96d..269447111 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,6 +21,7 @@
### Security
+- **An auto-detected inputs file must be a regular file (Breaking)**: `pipelex run bundle <folder>` and `pipelex-agent run bundle <folder>` read the folder's `inputs.json` or `inputs.toml` only when it is a regular file, opened without following a link and judged on the descriptor its bytes are read from, and refuse a symbolic link, a directory or any other entry of either name with the new `AutoDetectedInputsFileError`, an input error pointing to `--inputs`; they used to follow a link the method's tree keeps out, such as one its `.gitignore` ignores, so a method you checked out could point its inputs at data outside its folder. An inputs file named with `--inputs` is read as given, a link followed.
- **A `jwt` caller's `read_scope` is bound to its own id (Breaking)**: on a deployment with `AUTH_MODE=jwt`, every route taking a `read_scope` (the run routes, `/v1/validate`, `/v1/resolve`, `/v1/codegen`, `/v1/pipe-io` and `POST /v1/blobs/missing`) refuses a scope that does not lie under the caller's token `user_id` with a `403 ReadScopeForbidden`, so a caller holding its own token can no longer read another caller's blobs or run under another's scope. With `AUTH_MODE=none` or `api_key`, the caller is a trusted host or a single tenant, and the scope is taken as before.
## [v0.88.0] - 2026-10-16
diff --git a/docs/errors/auto-detected-inputs-file-error.md b/docs/errors/auto-detected-inputs-file-error.md
new file mode 100644
index 000000000..7ff8c2bca
--- /dev/null
+++ b/docs/errors/auto-detected-inputs-file-error.md
@@ -0,0 +1,22 @@
+---
+title: "Auto-detected inputs file is not a regular file"
+description: "Reference for the `AutoDetectedInputsFileError` Pipelex error class."
+---
+
+<!-- pipelex:generated -->
+
+# Auto-detected inputs file is not a regular file
+
+Raised when the inputs file auto-detection finds in a bundle directory is not a regular file.
+
+| Field | Value |
+|---|---|
+| `error_type` | `AutoDetectedInputsFileError` |
+| `title` | Auto-detected inputs file is not a regular file |
+| `type_uri` | `https://docs.pipelex.com/latest/errors/auto-detected-inputs-file-error/` |
+| `error_domain` | `input` |
+| Defined in | `pipelex.cli.commands.run.exceptions` |
+| Parent class | [`PipelexError`](pipelex-error.md) |
+| `user_action` | `change_input` — Replace it with the file itself, or name the inputs file with --inputs <path> |
+
+[Back to Error Reference](index.md)
diff --git a/docs/errors/platform-and-tooling.md b/docs/errors/platform-and-tooling.md
index 859c2789e..cb6105632 100644
--- a/docs/errors/platform-and-tooling.md
+++ b/docs/errors/platform-and-tooling.md
@@ -85,6 +85,7 @@ own page. Classes are grouped by subsystem.
## CLI
- [`AmbiguousInputsFilesError`](ambiguous-inputs-files-error.md) — Ambiguous inputs files
+- [`AutoDetectedInputsFileError`](auto-detected-inputs-file-error.md) — Auto-detected inputs file is not a regular file
- [`DriftAckError`](drift-ack-error.md) — Drift ack
- [`DriftError`](drift-error.md) — Drift
- [`DriftGitError`](drift-git-error.md) — Drift git
diff --git a/docs/tools/cli/agent-cli.md b/docs/tools/cli/agent-cli.md
index 419e6c28a..15ce91cf9 100644
--- a/docs/tools/cli/agent-cli.md
+++ b/docs/tools/cli/agent-cli.md
@@ -62,7 +62,7 @@ The success envelope has the shape of a local run's. Compact, it is the main out
A run refuses an invalid bundle while loading it, before any pipe runs, with exit code `1` and an error envelope whose `error_type` is `ValidateBundleError` and whose `validation_errors` array holds the items `validate` gives for that bundle, each with its pipe, its field and its suggested fix when it has one. A refusal found while loading a library directory you pass with `-L` (or the method's folder, for `run bundle <dir>`) is reported the same way, its items naming their file in `source`; a bundle file run on its own is loaded from its text, so the items of a refusal found while loading it carry no `source`, while a bundle that does not parse when `run bundle` looks for its `main_pipe` (no `--pipe`) names its file. In markdown, the items render as the same grouped prose `validate` prints.
!!! note "Stdin inputs stay JSON"
- The agent CLI can also read inputs from stdin (a flat dict or a `working_memory` envelope). Stdin inputs are **JSON-only** — the extension-based TOML discrimination applies to `--inputs` file paths only. Like the main CLI, `run bundle <dir>` auto-detects `inputs.json` / `inputs.toml` when `--inputs` is omitted, erroring if both exist. In a `working_memory` envelope each stuff must name its concept as the ref string; anything else there — the full concept object an older runtime dumped, for instance — is refused under `"error_type": "StdinEnvelopeShapeError"`, which is the label for an envelope that parsed as JSON but does not hold the shape the contract asks for, as distinct from the `JSONDecodeError` that means the JSON itself did not parse.
+ The agent CLI can also read inputs from stdin (a flat dict or a `working_memory` envelope). Stdin inputs are **JSON-only** — the extension-based TOML discrimination applies to `--inputs` file paths only. Like the main CLI, `run bundle <dir>` auto-detects `inputs.json` / `inputs.toml` when `--inputs` is omitted, erroring if both exist, and refuses one that is not a regular file, such as a symbolic link, which it never follows, under `"error_type": "AutoDetectedInputsFileError"`; a file named with `--inputs` is read as given, a link followed. In a `working_memory` envelope each stuff must name its concept as the ref string; anything else there — the full concept object an older runtime dumped, for instance — is refused under `"error_type": "StdinEnvelopeShapeError"`, which is the label for an envelope that parsed as JSON but does not hold the shape the contract asks for, as distinct from the `JSONDecodeError` that means the JSON itself did not parse.
### Validate
diff --git a/docs/tools/cli/run.md b/docs/tools/cli/run.md
index 1c414bedc..bc9590574 100644
--- a/docs/tools/cli/run.md
+++ b/docs/tools/cli/run.md
@@ -80,7 +80,7 @@ pipelex run pipe my_pipe -L ./pipelines --hosted --inputs data.json
pipelex run bundle <PATH> [OPTIONS]
```
-Runs a method from a bundle file (`.mthds`) or a method's folder, read through its [method tree](../../building-methods/method-trees.md). A folder is the method rooted at the nearest `METHODS.toml` at or above it, else at the folder itself, and with no `--pipe` the run starts at the manifest's `main_pipe`, or, with no manifest, at the one `main_pipe` its bundles declare; none or several is refused, naming each bundle by its path in the tree. An inputs file (`inputs.json` or `inputs.toml`) in the folder is auto-detected when `--inputs` is not passed (see [Input File Formats](#input-file-formats)). A bundle file named alone starts at its own `main_pipe`, and with no `METHODS.toml` at or above its folder its method is that one file, so a step naming a file beside it, such as a `template_file`, is refused: run the folder instead, or add a `METHODS.toml`.
+Runs a method from a bundle file (`.mthds`) or a method's folder, read through its [method tree](../../building-methods/method-trees.md). A folder is the method rooted at the nearest `METHODS.toml` at or above it, else at the folder itself, and with no `--pipe` the run starts at the manifest's `main_pipe`, or, with no manifest, at the one `main_pipe` its bundles declare; none or several is refused, naming each bundle by its path in the tree. An inputs file (`inputs.json` or `inputs.toml`) in the folder is auto-detected when `--inputs` is not passed (see [Auto-detection and ambiguity](#auto-detection-and-ambiguity)). A bundle file named alone starts at its own `main_pipe`, and with no `METHODS.toml` at or above its folder its method is that one file, so a step naming a file beside it, such as a `template_file`, is refused: run the folder instead, or add a `METHODS.toml`.
The run prints the digest of the tree it read with its recap, and records the tree as `method_tree.json` in its output folder (see [The results directory](#the-results-directory)).
@@ -279,6 +279,8 @@ country = "France"
`run bundle <dir>` auto-detects a default inputs file inside the directory when `--inputs` is omitted: it looks for `inputs.json`, then `inputs.toml`. If **both** exist, the run fails with an ambiguity error asking you to pass `--inputs` explicitly — passing `--inputs` always bypasses auto-detection.
+The file it finds must be a regular file, and it is read without following a link. A symbolic link of either name, a folder or any other entry fails the run with an `AutoDetectedInputsFileError` naming it, so a method you checked out cannot point its `inputs.json` at data outside its folder, even when its `.gitignore` keeps the link out of its [method tree](../../building-methods/method-trees.md#what-a-tree-holds); a link the tree holds refuses the tree itself, as any symbolic link in a method tree does. Replace the link with the file itself, or name the file with `--inputs`, which reads a link as given.
+
## Output Format
The output JSON contains the complete working memory after pipeline execution, including all intermediate results and the final output.
diff --git a/pipelex/cli/agent_cli/commands/run/stdin_resolver.py b/pipelex/cli/agent_cli/commands/run/stdin_resolver.py
index c7c7d7495..5349c102b 100644
--- a/pipelex/cli/agent_cli/commands/run/stdin_resolver.py
+++ b/pipelex/cli/agent_cli/commands/run/stdin_resolver.py
@@ -8,9 +8,9 @@ from pathlib import Path
from typing import Any, NamedTuple, cast
from pipelex.cli.agent_cli.commands.agent_output import agent_error
-from pipelex.cli.commands.run._inputs_file_loader import find_default_inputs_file, load_inputs_dict_from_path
+from pipelex.cli.commands.run._inputs_file_loader import load_inputs_dict_from_bytes, load_inputs_dict_from_path, read_default_inputs_file
from pipelex.cli.commands.run._inputs_path_resolver import resolve_inputs_paths
-from pipelex.cli.commands.run.exceptions import AmbiguousInputsFilesError
+from pipelex.cli.commands.run.exceptions import AmbiguousInputsFilesError, AutoDetectedInputsFileError
from pipelex.tools.misc.exceptions import JsonTypeError, TomlError
WORKING_MEMORY_KEY = "working_memory"
@@ -172,11 +172,12 @@ def parse_cli_inputs(
if auto_inputs_dir is not None:
try:
- auto_inputs_file = find_default_inputs_file(directory=auto_inputs_dir)
- except AmbiguousInputsFilesError as ambiguity_exc:
- agent_error(ambiguity_exc.message, error_type="AmbiguousInputsFilesError", cause=ambiguity_exc)
- if auto_inputs_file is not None:
- return _parse_inputs_arg(str(auto_inputs_file))
+ detected_inputs = read_default_inputs_file(directory=auto_inputs_dir)
+ except (AmbiguousInputsFilesError, AutoDetectedInputsFileError) as inputs_file_exc:
+ agent_error(inputs_file_exc.message, error_type=type(inputs_file_exc).__name__, cause=inputs_file_exc)
+ if detected_inputs is not None:
+ # Parsed from the bytes the probe read without following a link, never by opening the path again.
+ return _parse_inputs_file(inputs_path=detected_inputs.path, label=str(detected_inputs.path), data=detected_inputs.data)
return ParsedCliInputs(pipeline_inputs=None, inputs_base_dir=None)
@@ -197,22 +198,36 @@ def _parse_inputs_arg(inputs_arg: str) -> ParsedCliInputs:
except json.JSONDecodeError as exc:
agent_error(f"Failed to parse inline JSON inputs: {exc}", error_type="JSONDecodeError", cause=exc)
return ParsedCliInputs(pipeline_inputs=result, inputs_base_dir=None)
+ # expanduser so a quoted / `=`-form `~/inputs.json` resolves to the home dir, not a
+ # literal `~` component (unquoted `~` is shell-expanded, but the quoted/`=` forms are not).
+ return _parse_inputs_file(inputs_path=Path(inputs_arg).expanduser(), label=inputs_arg, data=None)
+
+
+def _parse_inputs_file(*, inputs_path: Path, label: str, data: bytes | None) -> ParsedCliInputs:
+ """Parse an inputs file: from ``data`` when auto-detection read it, else by reading the file, a link followed.
+
+ Args:
+ inputs_path: The inputs file, whose suffix selects the parser and whose directory anchors relative paths.
+ label: How error messages name the file: the ``--inputs`` value as given, or the auto-detected path.
+ data: The bytes auto-detection read from the file, or None to read the file named with ``--inputs``.
+
+ Returns:
+ A :class:`ParsedCliInputs` carrying the file's parent directory, so bare relative file-ish / CSV
+ inputs resolve against it (D3).
+ """
try:
- # expanduser so a quoted / `=`-form `~/inputs.json` resolves to the home dir, not a
- # literal `~` component (unquoted `~` is shell-expanded, but the quoted/`=` forms are not).
- inputs_path = Path(inputs_arg).expanduser()
- loaded = load_inputs_dict_from_path(inputs_path)
+ loaded = load_inputs_dict_from_path(inputs_path) if data is None else load_inputs_dict_from_bytes(data=data, path=inputs_path)
# Resolve relative url paths against the inputs file's parent directory. The same directory
# rides to the runner as inputs_base_dir so the shaper can resolve bare relative file-ish /
# CSV strings (whose declared concept the signature-blind CLI cannot see).
base_dir = inputs_path.parent.resolve()
return ParsedCliInputs(pipeline_inputs=resolve_inputs_paths(loaded, base_dir=base_dir), inputs_base_dir=base_dir)
except FileNotFoundError as exc:
- agent_error(f"Input file not found: {inputs_arg}", error_type="FileNotFoundError", cause=exc)
+ agent_error(f"Input file not found: {label}", error_type="FileNotFoundError", cause=exc)
except json.JSONDecodeError as exc:
- agent_error(f"Input file contains invalid JSON: {inputs_arg}: {exc}", error_type="JSONDecodeError", cause=exc)
+ agent_error(f"Input file contains invalid JSON: {label}: {exc}", error_type="JSONDecodeError", cause=exc)
except JsonTypeError as exc:
- agent_error(f"Input file must be a valid JSON dictionary: {inputs_arg}", error_type="JsonTypeError", cause=exc)
+ agent_error(f"Input file must be a valid JSON dictionary: {label}", error_type="JsonTypeError", cause=exc)
except TomlError as exc:
agent_error(exc.message, error_type="TomlError", cause=exc)
diff --git a/pipelex/cli/commands/run/_inputs_file_loader.py b/pipelex/cli/commands/run/_inputs_file_loader.py
index 957e6eb00..8039ca6b2 100644
--- a/pipelex/cli/commands/run/_inputs_file_loader.py
+++ b/pipelex/cli/commands/run/_inputs_file_loader.py
@@ -5,24 +5,45 @@ through the TOML parser, every other suffix (``.json``, extensionless, ...)
keeps the JSON behavior. Both the main CLI (``pipelex run``) and the agent CLI
(``pipelex-agent run``) load inputs files through this module so the two
surfaces cannot drift — same deal for the ``inputs.json`` / ``inputs.toml``
-auto-detect probe and its ambiguity rule.
+auto-detect probe, its ambiguity rule and its refusal of anything but a
+regular file.
"""
from __future__ import annotations
import datetime
+import errno
+import os
+import stat
from pathlib import Path
-from typing import Any
+from typing import Any, NamedTuple
-from pipelex.cli.commands.run.exceptions import AmbiguousInputsFilesError
+from pipelex.cli.commands.run.exceptions import AmbiguousInputsFilesError, AutoDetectedInputsFileError
from pipelex.core.stuffs.date_content import DateContent
from pipelex.core.stuffs.time_content import TimeContent
from pipelex.pipeline.default_file_names import DEFAULT_INPUTS_FILE_NAME, DEFAULT_INPUTS_TOML_FILE_NAME
-from pipelex.tools.misc.json_utils import load_json_dict_from_path
-from pipelex.tools.misc.toml_utils import load_toml_from_path
+from pipelex.tools.misc.json_utils import load_json_dict_from_bytes
+from pipelex.tools.misc.toml_utils import load_toml_from_bytes
TOML_SUFFIX = ".toml"
+# Opening the auto-detected inputs file: read-only, never following a link in its last component, and never blocking
+# on a named pipe, so the descriptor `fstat` judges is the one the bytes are read from. `O_NOFOLLOW` and `O_NONBLOCK`
+# do not exist on Windows, where the `lstat` check before the open is the only guard; `O_BINARY` exists only there.
+_NO_FOLLOW_READ_FLAGS = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0) | getattr(os, "O_BINARY", 0)
+_READ_CHUNK_BYTES = 1 << 16
+
+
+class DetectedInputsFile(NamedTuple):
+ """The inputs file auto-detection found in a bundle directory, with the bytes read from it.
+
+ The bytes were read from a descriptor opened without following a link, so whoever loads the file parses these
+ bytes and never opens its path again.
+ """
+
+ path: Path
+ data: bytes
+
def load_inputs_dict_from_path(path: Path) -> dict[str, Any]:
"""Load a pipeline-inputs dict from a JSON or TOML file, discriminated by extension.
@@ -44,11 +65,26 @@ def load_inputs_dict_from_path(path: Path) -> dict[str, Any]:
json.JSONDecodeError: If a JSON file has invalid JSON syntax.
JsonTypeError: If a JSON file does not hold a dictionary.
"""
+ return load_inputs_dict_from_bytes(data=path.read_bytes(), path=path)
+
+
+def load_inputs_dict_from_bytes(*, data: bytes, path: Path) -> dict[str, Any]:
+ """Load a pipeline-inputs dict from the bytes of a JSON or TOML file, as ``load_inputs_dict_from_path`` loads the file.
+
+ Args:
+ data: The bytes read from the inputs file.
+ path: The file they were read from: its suffix selects the parser, and a parsing error names it.
+
+ Raises:
+ TomlError: If a ``.toml`` file has invalid TOML syntax.
+ json.JSONDecodeError: If a JSON file has invalid JSON syntax.
+ JsonTypeError: If a JSON file does not hold a dictionary.
+ """
inputs_dict: dict[str, Any]
if path.suffix.lower() == TOML_SUFFIX:
- inputs_dict = load_toml_from_path(path)
+ inputs_dict = load_toml_from_bytes(data=data, source=path)
else:
- inputs_dict = load_json_dict_from_path(path)
+ inputs_dict = load_json_dict_from_bytes(data=data, source=path)
return _convert_temporal_inputs(inputs_dict)
@@ -80,35 +116,110 @@ def resolve_inputs_arg_against_dir(inputs_arg: str | None, *, base_dir: Path) ->
return str(base_dir / inputs_path)
-def find_default_inputs_file(*, directory: Path) -> Path | None:
- """Probe a bundle directory for the default inputs file (JSON or TOML).
+def read_default_inputs_file(*, directory: Path) -> DetectedInputsFile | None:
+ """Probe a bundle directory for the default inputs file (JSON or TOML), and read it.
+
+ Each name is looked up by ``lstat``, never following a link, and only a regular file is read: a link named
+ ``inputs.json`` in a checked-out method, which the method's tree can keep out, for instance through a
+ ``.gitignore``, would otherwise carry JSON from outside the method's folder into the run. The file is read through
+ a descriptor opened without following a link and judged by ``fstat``, so an entry swapped for a link or for
+ anything else between the lookup and the read is refused too, and its bytes are returned so that nothing opens the
+ path again. An inputs file the caller names with ``--inputs`` never comes through here, and is read as given, a
+ link followed.
Args:
directory: The bundle/pipeline directory to probe.
Returns:
- The path to ``inputs.json`` or ``inputs.toml`` when exactly one exists,
+ The path to ``inputs.json`` or ``inputs.toml`` and the bytes read from it, when exactly one exists,
None when neither does.
Raises:
- AmbiguousInputsFilesError: When both default files exist — the caller
+ AmbiguousInputsFilesError: When an entry of each name exists — the caller
must pass ``--inputs`` explicitly.
+ AutoDetectedInputsFileError: When the one entry found is a symbolic link,
+ a directory or any other entry that is not a regular file.
"""
json_file = directory / DEFAULT_INPUTS_FILE_NAME
toml_file = directory / DEFAULT_INPUTS_TOML_FILE_NAME
- json_exists = json_file.is_file()
- toml_exists = toml_file.is_file()
- if json_exists and toml_exists:
+ json_mode = _entry_mode(path=json_file)
+ toml_mode = _entry_mode(path=toml_file)
+ if json_mode is not None and toml_mode is not None:
msg = (
f"Directory '{directory}' holds both '{DEFAULT_INPUTS_FILE_NAME}' and '{DEFAULT_INPUTS_TOML_FILE_NAME}', "
"so inputs auto-detection is ambiguous. Pass --inputs explicitly to choose one."
)
raise AmbiguousInputsFilesError(msg)
- if json_exists:
- return json_file
- if toml_exists:
- return toml_file
- return None
+ found: Path
+ if json_mode is not None:
+ _refuse_unless_regular_file(path=json_file, mode=json_mode)
+ found = json_file
+ elif toml_mode is not None:
+ _refuse_unless_regular_file(path=toml_file, mode=toml_mode)
+ found = toml_file
+ else:
+ return None
+ return DetectedInputsFile(path=found, data=_read_regular_file_without_following_link(path=found))
+
+
+def _entry_mode(*, path: Path) -> int | None:
+ """The mode of the entry at ``path``, a symbolic link not followed, or None when there is none."""
+ try:
+ return path.lstat().st_mode
+ except (FileNotFoundError, NotADirectoryError):
+ return None
+
+
+def _read_regular_file_without_following_link(*, path: Path) -> bytes:
+ """The bytes of the regular file at ``path``, read from a descriptor opened without following a link.
+
+ Raises:
+ AutoDetectedInputsFileError: When ``path`` is a symbolic link, which fails the open, or the opened entry is
+ not a regular file.
+ """
+ try:
+ descriptor = os.open(path, _NO_FOLLOW_READ_FLAGS)
+ except OSError as exc:
+ if exc.errno == errno.ELOOP:
+ # The entry was swapped for a link since it was looked up: `O_NOFOLLOW` refuses to open a link.
+ raise _not_a_regular_file_error(path=path, mode=stat.S_IFLNK) from exc
+ raise
+ try:
+ _refuse_unless_regular_file(path=path, mode=os.fstat(descriptor).st_mode)
+ chunks: list[bytes] = []
+ while chunk := os.read(descriptor, _READ_CHUNK_BYTES):
+ chunks.append(chunk)
+ return b"".join(chunks)
+ finally:
+ os.close(descriptor)
+
+
+def _refuse_unless_regular_file(*, path: Path, mode: int) -> None:
+ """Refuse an auto-detected inputs file that is not a regular file, naming what it is.
+
+ Raises:
+ AutoDetectedInputsFileError: When ``mode`` is not a regular file's.
+ """
+ if stat.S_ISREG(mode):
+ return
+ raise _not_a_regular_file_error(path=path, mode=mode)
+
+
+def _not_a_regular_file_error(*, path: Path, mode: int) -> AutoDetectedInputsFileError:
+ """The refusal of an auto-detected inputs file of mode ``mode``, which is not a regular file's, naming what it is."""
+ what: str
+ if stat.S_ISLNK(mode):
+ what = "a symbolic link"
+ elif stat.S_ISDIR(mode):
+ what = "a directory"
+ else:
+ what = "not a regular file"
+ msg = (
+ f"'{path}' was found as the run's inputs because no --inputs was given, but it is {what}. "
+ "An inputs file found automatically must be a regular file, so that a link never carries data from outside "
+ "the method's folder into the run. Replace it with the file itself, or name the inputs with --inputs <path>."
+ )
+ return AutoDetectedInputsFileError(msg)
def _convert_temporal_inputs(inputs_dict: dict[str, Any]) -> dict[str, Any]:
diff --git a/pipelex/cli/commands/run/_run_core.py b/pipelex/cli/commands/run/_run_core.py
index 5b46ee698..2bc88a004 100644
--- a/pipelex/cli/commands/run/_run_core.py
+++ b/pipelex/cli/commands/run/_run_core.py
@@ -12,7 +12,7 @@ from rich.markup import escape
from pipelex import log
from pipelex.base_exceptions import PipelexError
from pipelex.cli.cli_factory import make_pipelex_for_cli
-from pipelex.cli.commands.run._inputs_file_loader import load_inputs_dict_from_path
+from pipelex.cli.commands.run._inputs_file_loader import DetectedInputsFile, load_inputs_dict_from_bytes, load_inputs_dict_from_path
from pipelex.cli.commands.run._inputs_path_resolver import resolve_inputs_paths
from pipelex.cli.commands.run._main_stuff_file import save_main_stuff_file
from pipelex.cli.commands.run._run_output_folder import make_run_output_folder, run_output_label, write_method_tree_record
@@ -96,54 +96,66 @@ class LoadedRunInputs(NamedTuple):
inputs_base_dir: Path | None
-def load_run_inputs(*, inputs: str | None) -> LoadedRunInputs:
- """Load `--inputs`: inline JSON (a `{` prefix) or a JSON or TOML file, its relative `url` paths resolved against its directory.
+def load_run_inputs(*, inputs: str | DetectedInputsFile | None) -> LoadedRunInputs:
+ """Load a run's inputs, their relative `url` paths resolved against the inputs file's directory.
- Shared by local and hosted runs, so both read the same inputs the same way.
+ `inputs` is `--inputs` as given, inline JSON (a `{` prefix) or a JSON or TOML file, read as given, a link
+ followed, or the inputs file auto-detection found in a bundle directory, parsed from the bytes it read without
+ following a link and never opened again. Shared by local and hosted runs, so both read the same inputs the same way.
Raises:
typer.Exit: If the inputs cannot be read or parsed, after printing why.
"""
- pipeline_inputs: dict[str, Any] | None = None
- # Directory bare relative file paths resolve against (Smart Inputs D3). Set only when inputs are
- # file-loaded (its parent); None for inline JSON — an inline caller has no file to anchor to.
- inputs_base_dir: Path | None = None
- if inputs:
- if inputs.startswith("{"):
- try:
- pipeline_inputs = json.loads(inputs)
- except json.JSONDecodeError as json_decode_exc:
- print_traceback_if_requested(console=get_console())
- typer.secho(f"Failed to parse inline JSON inputs: {json_decode_exc}", fg=typer.colors.RED, err=True)
- raise typer.Exit(1) from json_decode_exc
- else:
- try:
- # expanduser so a quoted / `=`-form `~/inputs.json` resolves to the home dir, not a
- # literal `~` component (unquoted `~` is shell-expanded, but the quoted/`=` forms are not).
- inputs_path = Path(inputs).expanduser()
- pipeline_inputs = load_inputs_dict_from_path(inputs_path)
- # Resolve relative url paths against the inputs file's parent directory. The same
- # directory is threaded to the runner as inputs_base_dir so the shaper can resolve
- # bare relative file-ish / CSV strings (whose declared concept the CLI cannot see).
- inputs_base_dir = inputs_path.parent.resolve()
- pipeline_inputs = resolve_inputs_paths(pipeline_inputs, base_dir=inputs_base_dir)
- typer.echo(f"Loaded inputs from: {inputs}")
- except FileNotFoundError as file_not_found_exc:
- print_traceback_if_requested(console=get_console())
- typer.secho(f"Failed to load input file '{inputs}': file not found", fg=typer.colors.RED, err=True)
- raise typer.Exit(1) from file_not_found_exc
- except json.JSONDecodeError as json_decode_exc:
- print_traceback_if_requested(console=get_console())
- typer.secho(f"Failed to parse input file '{inputs}': invalid JSON: {json_decode_exc}", fg=typer.colors.RED, err=True)
- raise typer.Exit(1) from json_decode_exc
- except JsonTypeError as json_type_error_exc:
- print_traceback_if_requested(console=get_console())
- typer.secho(f"Failed to parse input file '{inputs}': must be a valid JSON dictionary", fg=typer.colors.RED, err=True)
- raise typer.Exit(1) from json_type_error_exc
- except TomlError as toml_error_exc:
- print_traceback_if_requested(console=get_console())
- typer.secho(f"Failed to parse input file: {toml_error_exc.message}", fg=typer.colors.RED, err=True)
- raise typer.Exit(1) from toml_error_exc
+ if isinstance(inputs, DetectedInputsFile):
+ return _load_run_inputs_file(inputs_path=inputs.path, label=str(inputs.path), data=inputs.data)
+ if not inputs:
+ return LoadedRunInputs(pipeline_inputs=None, inputs_base_dir=None)
+ if inputs.startswith("{"):
+ try:
+ inline_inputs: dict[str, Any] = json.loads(inputs)
+ except json.JSONDecodeError as json_decode_exc:
+ print_traceback_if_requested(console=get_console())
+ typer.secho(f"Failed to parse inline JSON inputs: {json_decode_exc}", fg=typer.colors.RED, err=True)
+ raise typer.Exit(1) from json_decode_exc
+ # Inline JSON has no file to anchor relative paths to.
+ return LoadedRunInputs(pipeline_inputs=inline_inputs, inputs_base_dir=None)
+ # expanduser so a quoted / `=`-form `~/inputs.json` resolves to the home dir, not a
+ # literal `~` component (unquoted `~` is shell-expanded, but the quoted/`=` forms are not).
+ return _load_run_inputs_file(inputs_path=Path(inputs).expanduser(), label=inputs, data=None)
+
+
+def _load_run_inputs_file(*, inputs_path: Path, label: str, data: bytes | None) -> LoadedRunInputs:
+ """Load an inputs file: from `data` when auto-detection read it, else by reading the file, a link followed.
+
+ `label` names the file in what is printed: the `--inputs` value as given, or the auto-detected path.
+
+ Raises:
+ typer.Exit: If the file cannot be read or parsed, after printing why.
+ """
+ try:
+ pipeline_inputs = load_inputs_dict_from_path(inputs_path) if data is None else load_inputs_dict_from_bytes(data=data, path=inputs_path)
+ # Resolve relative url paths against the inputs file's parent directory. The same
+ # directory is threaded to the runner as inputs_base_dir so the shaper can resolve
+ # bare relative file-ish / CSV strings (whose declared concept the CLI cannot see).
+ inputs_base_dir = inputs_path.parent.resolve()
+ pipeline_inputs = resolve_inputs_paths(pipeline_inputs, base_dir=inputs_base_dir)
+ typer.echo(f"Loaded inputs from: {label}")
+ except FileNotFoundError as file_not_found_exc:
+ print_traceback_if_requested(console=get_console())
+ typer.secho(f"Failed to load input file '{label}': file not found", fg=typer.colors.RED, err=True)
+ raise typer.Exit(1) from file_not_found_exc
+ except json.JSONDecodeError as json_decode_exc:
+ print_traceback_if_requested(console=get_console())
+ typer.secho(f"Failed to parse input file '{label}': invalid JSON: {json_decode_exc}", fg=typer.colors.RED, err=True)
+ raise typer.Exit(1) from json_decode_exc
+ except JsonTypeError as json_type_error_exc:
+ print_traceback_if_requested(console=get_console())
+ typer.secho(f"Failed to parse input file '{label}': must be a valid JSON dictionary", fg=typer.colors.RED, err=True)
+ raise typer.Exit(1) from json_type_error_exc
+ except TomlError as toml_error_exc:
+ print_traceback_if_requested(console=get_console())
+ typer.secho(f"Failed to parse input file: {toml_error_exc.message}", fg=typer.colors.RED, err=True)
+ raise typer.Exit(1) from toml_error_exc
return LoadedRunInputs(pipeline_inputs=pipeline_inputs, inputs_base_dir=inputs_base_dir)
@@ -180,7 +192,7 @@ async def _execute_run(
*,
pipe_code: str | None,
bundle_path: str | None,
- inputs: str | None,
+ inputs: str | DetectedInputsFile | None,
save_working_memory: bool,
working_memory_path: str | None,
save_main_stuff: bool,
@@ -502,7 +514,7 @@ def execute_run(
*,
pipe_code: str | None,
bundle_path: str | None,
- inputs: str | None,
+ inputs: str | DetectedInputsFile | None,
save_working_memory: bool,
working_memory_path: str | None,
save_main_stuff: bool,
@@ -525,6 +537,7 @@ def execute_run(
Shared between the ``method``, ``pipe`` and ``bundle`` subcommands, for a run that executes on this machine. It
prints the deck staleness notice, which the root callback leaves to it: only a local run reads the deck.
+ ``inputs`` is ``--inputs`` as given, or the inputs file ``run bundle`` auto-detected (see ``load_run_inputs``).
"""
warn_if_deck_stale()
# A dry run makes no inference call, so it must not demand credentials: `needs_inference=False`
diff --git a/pipelex/cli/commands/run/_run_hosted.py b/pipelex/cli/commands/run/_run_hosted.py
index 261439461..80df4e50e 100644
--- a/pipelex/cli/commands/run/_run_hosted.py
+++ b/pipelex/cli/commands/run/_run_hosted.py
@@ -38,6 +38,8 @@ if TYPE_CHECKING:
from pipelex_sdk.client import PipelexAPIClient
from pipelex_sdk.crate_models import MthdsFileItem
+ from pipelex.cli.commands.run._inputs_file_loader import DetectedInputsFile
+
_NATIVE_TEXT_CONCEPT_REF = "native.Text"
_MAIN_STUFF_NAME = "main_stuff"
_WORKING_MEMORY_FILENAME = "working_memory.json"
@@ -184,7 +186,7 @@ def execute_hosted_run(
method_ref: str | None = None,
method_id: str | None = None,
pipe_code: str | None,
- inputs: str | None,
+ inputs: str | DetectedInputsFile | None,
dynamic_output_concept_ref: str | None,
base_url: str | None,
output_label: str,
@@ -198,8 +200,8 @@ def execute_hosted_run(
"""Run on the hosted API, print the main output, and save the outputs as a local run saves them.
The method is named by exactly one of `mthds_files`, `method_ref` and `method_id`. `inputs` is `--inputs` as the
- command resolved it: inline JSON or a JSON or TOML file, read as a local run reads it, and a local file it names
- at a document or image input is uploaded first.
+ command resolved it, inline JSON or a JSON or TOML file, or the inputs file auto-detection read from a bundle
+ directory, read as a local run reads it, and a local file it names at a document or image input is uploaded first.
The outputs go to `<output_dir>/<output_label>_output_NN/`: `main_stuff.json` (and `main_stuff.md` for a text
output), `working_memory.json`, and `graphspec.json` when the hosted API returned the run's graph, which
diff --git a/pipelex/cli/commands/run/bundle_cmd.py b/pipelex/cli/commands/run/bundle_cmd.py
index ecb22be79..50b6c6e1f 100644
--- a/pipelex/cli/commands/run/bundle_cmd.py
+++ b/pipelex/cli/commands/run/bundle_cmd.py
@@ -8,11 +8,11 @@ import typer
from pipelex.base_exceptions import PipelexConfigError, PipelexUnexpectedError
from pipelex.cli.bundle_target_resolution import list_bundle_file_tree, resolve_method_folder_run
from pipelex.cli.commands.run._hosted_sources import collect_mthds_files, hosted_library_dirs
-from pipelex.cli.commands.run._inputs_file_loader import find_default_inputs_file
+from pipelex.cli.commands.run._inputs_file_loader import DetectedInputsFile, read_default_inputs_file
from pipelex.cli.commands.run._run_core import COMMAND, execute_run, validate_run_flag_combination
from pipelex.cli.commands.run._run_hosted import bundle_main_pipe_code, execute_hosted_run, refuse_local_only_flags, resolve_cli_run_execution
from pipelex.cli.commands.run._run_output_folder import run_output_label
-from pipelex.cli.commands.run.exceptions import AmbiguousInputsFilesError
+from pipelex.cli.commands.run.exceptions import AmbiguousInputsFilesError, AutoDetectedInputsFileError
from pipelex.cli.error_handlers import handle_pre_boot_config_error, handle_validate_bundle_error
from pipelex.hosted.exceptions import HostedRunSourceError
from pipelex.mthds_parsing.helpers import is_pipelex_file
@@ -145,6 +145,8 @@ def run_bundle_cmd(
pipe_code: str | None = pipe
bundle_path: str | None = None
+ # `--inputs` as given, or the inputs file auto-detection read from the method's folder.
+ run_inputs: str | DetectedInputsFile | None = inputs
target_path = Path(path)
# The method tree the run reads, whose digest the run records: the folder's, or the bundle file's own.
@@ -168,16 +170,17 @@ def run_bundle_cmd(
hosted_pipe_code = folder_run.entry.pipe_ref
typer.echo(f"Starting at the method's main pipe {folder_run.entry.pipe_ref}, in {folder_run.entry.tree_path}")
- # Auto-detect inputs (inputs.json or inputs.toml) if --inputs not explicitly provided
+ # Auto-detect inputs (inputs.json or inputs.toml) if --inputs not explicitly provided. The run parses the
+ # bytes the probe read without following a link, and never opens the path again.
if not inputs:
try:
- inputs_file = find_default_inputs_file(directory=target_path)
- except AmbiguousInputsFilesError as ambiguity_exc:
- typer.secho(f"Failed to run: {ambiguity_exc.message}", fg=typer.colors.RED, err=True)
- raise typer.Exit(1) from ambiguity_exc
- if inputs_file is not None:
- inputs = str(inputs_file)
- typer.echo(f"Auto-detected inputs: {inputs}")
+ detected_inputs = read_default_inputs_file(directory=target_path)
+ except (AmbiguousInputsFilesError, AutoDetectedInputsFileError) as inputs_file_exc:
+ typer.secho(f"Failed to run: {inputs_file_exc.message}", fg=typer.colors.RED, err=True)
+ raise typer.Exit(1) from inputs_file_exc
+ if detected_inputs is not None:
+ run_inputs = detected_inputs
+ typer.echo(f"Auto-detected inputs: {detected_inputs.path}")
# Add directory as library dir
target_dir_str = str(target_path)
@@ -234,7 +237,7 @@ def run_bundle_cmd(
execute_hosted_run(
mthds_files=bundle_files,
pipe_code=hosted_pipe_code,
- inputs=inputs,
+ inputs=run_inputs,
dynamic_output_concept_ref=dynamic_output_concept_ref,
base_url=base_url,
output_label=run_output_label(pipe_ref=hosted_pipe_code),
@@ -250,7 +253,7 @@ def run_bundle_cmd(
execute_run(
pipe_code=pipe_code,
bundle_path=bundle_path,
- inputs=inputs,
+ inputs=run_inputs,
save_working_memory=save_working_memory,
working_memory_path=working_memory_path,
save_main_stuff=save_main_stuff,
diff --git a/pipelex/cli/commands/run/exceptions.py b/pipelex/cli/commands/run/exceptions.py
index e9552226e..84a90e632 100644
--- a/pipelex/cli/commands/run/exceptions.py
+++ b/pipelex/cli/commands/run/exceptions.py
@@ -18,3 +18,21 @@ class AmbiguousInputsFilesError(PipelexError):
)
# The message describes a fault in the caller's own bundle directory — caller-facing copy.
_authors_caller_facing_message = True
+
+
+class AutoDetectedInputsFileError(PipelexError):
+ """Raised when the inputs file auto-detection finds in a bundle directory is not a regular file.
+
+ Auto-detection reads ``inputs.json`` or ``inputs.toml`` only when it is a regular file, judged without
+ following a link, so a symbolic link in a method's folder never carries data from outside the folder
+ into a run; a directory or any other entry of either name is refused the same way.
+ """
+
+ _declared_title = "Auto-detected inputs file is not a regular file"
+ error_domain = ErrorDomain.INPUT
+ user_action = UserAction(
+ kind=UserActionKind.CHANGE_INPUT,
+ detail="Replace it with the file itself, or name the inputs file with --inputs <path>",
+ )
+ # The message describes a fault in the caller's own bundle directory — caller-facing copy.
+ _authors_caller_facing_message = True
diff --git a/pipelex/tools/misc/json_utils.py b/pipelex/tools/misc/json_utils.py
index f9bb00a6b..3560eb6a7 100644
--- a/pipelex/tools/misc/json_utils.py
+++ b/pipelex/tools/misc/json_utils.py
@@ -177,8 +177,8 @@ def load_json_from_path(path: Path) -> JsonContent:
def load_json_dict_from_path(path: Path) -> dict[str, Any]:
"""Loads a JSON file and ensures it contains a dictionary.
- This function reads a JSON file and verifies that its content is a dictionary.
- It uses load_json_from_path internally and adds type checking.
+ This function reads a JSON file and verifies that its content is a dictionary,
+ through load_json_dict_from_bytes.
Args:
path (Path): The file path to the JSON file to be loaded.
@@ -192,9 +192,27 @@ def load_json_dict_from_path(path: Path) -> dict[str, Any]:
json.JSONDecodeError: If the file contains invalid JSON.
"""
- json_content: JsonContent = load_json_from_path(path)
+ return load_json_dict_from_bytes(data=path.read_bytes(), source=path)
+
+
+def load_json_dict_from_bytes(*, data: bytes, source: str | Path) -> dict[str, Any]:
+ """Parses a JSON file's bytes, decoded as UTF-8, and ensures they hold a dictionary.
+
+ Args:
+ data: The bytes read from the file.
+ source: The file the bytes were read from, named in the error when they hold no dictionary.
+
+ Returns:
+ Dict[str, Any]: The parsed JSON content as a Python dictionary.
+
+ Raises:
+ JsonTypeError: If the JSON content is not a dictionary.
+ json.JSONDecodeError: If the bytes hold invalid JSON.
+
+ """
+ json_content: JsonContent = json.loads(data.decode("utf-8"))
if not isinstance(json_content, dict):
- msg = f"{path} is not a dict"
+ msg = f"{source} is not a dict"
raise JsonTypeError(msg)
return json_content
diff --git a/pipelex/tools/misc/toml_utils.py b/pipelex/tools/misc/toml_utils.py
index d37dd7ed3..930cebe0a 100644
--- a/pipelex/tools/misc/toml_utils.py
+++ b/pipelex/tools/misc/toml_utils.py
@@ -34,12 +34,30 @@ def load_toml_from_path(path: str | Path) -> dict[str, Any]:
Raises:
toml.TomlDecodeError: If TOML parsing fails, with file path included
+ """
+ with open(path, "rb") as file:
+ data = file.read()
+ return load_toml_from_bytes(data=data, source=path)
+
+
+def load_toml_from_bytes(*, data: bytes, source: str | Path) -> dict[str, Any]:
+ """Load TOML from a file's bytes, decoded as UTF-8 as tomli decodes a file it reads.
+
+ Args:
+ data: The bytes read from the file
+ source: The file the bytes were read from, named in a parsing error
+
+ Returns:
+ Dictionary loaded from TOML
+
+ Raises:
+ TomlError: If TOML parsing fails, with the file path included
+
"""
try:
- with open(path, "rb") as file:
- return tomli.load(file)
+ return tomli.loads(data.decode())
except tomli.TOMLDecodeError as exc:
- msg = f"TOML parsing error in file '{path}': {exc.msg}"
+ msg = f"TOML parsing error in file '{source}': {exc.msg}"
raise TomlError(message=msg, doc=exc.doc, pos=exc.pos, lineno=exc.lineno, colno=exc.colno) from exc
diff --git a/tests/data/errors/error_identity.txt b/tests/data/errors/error_identity.txt
index 04bc9e6f3..93a7f72f5 100644
--- a/tests/data/errors/error_identity.txt
+++ b/tests/data/errors/error_identity.txt
@@ -15,6 +15,7 @@ AnthropicSDKUnsupportedError | Anthropic SDK unsupported | https://docs.pipelex.
AnthropicWorkerConfigurationError | Anthropic worker configuration | https://docs.pipelex.com/latest/errors/anthropic-worker-configuration-error/
ArgumentTypeError | Argument type | https://docs.pipelex.com/latest/errors/argument-type-error/
AsyncExecutionNotEnabledError | Async execution not enabled | https://docs.pipelex.com/latest/errors/async-execution-not-enabled-error/
+AutoDetectedInputsFileError | Auto-detected inputs file is not a regular file | https://docs.pipelex.com/latest/errors/auto-detected-inputs-file-error/
AwsCredentialsError | Aws credentials | https://docs.pipelex.com/latest/errors/aws-credentials-error/
AzureCredentialsError | Azure credentials | https://docs.pipelex.com/latest/errors/azure-credentials-error/
BatchParamsError | Batch params | https://docs.pipelex.com/latest/errors/batch-params-error/
diff --git a/tests/unit/pipelex/cli/agent_cli/test_run_bundle_auto_inputs.py b/tests/unit/pipelex/cli/agent_cli/test_run_bundle_auto_inputs.py
index 17246a712..c5825586b 100644
--- a/tests/unit/pipelex/cli/agent_cli/test_run_bundle_auto_inputs.py
+++ b/tests/unit/pipelex/cli/agent_cli/test_run_bundle_auto_inputs.py
@@ -4,6 +4,7 @@ from __future__ import annotations
import io
import json
+import sys
from typing import TYPE_CHECKING, Any
import pytest
@@ -18,6 +19,9 @@ if TYPE_CHECKING:
from pytest_mock import MockerFixture
RUN_BUNDLE_MODULE = "pipelex.cli.agent_cli.commands.run.bundle_cmd"
+_NO_SYMLINKS_ON_WINDOWS = pytest.mark.skipif(
+ sys.platform == "win32", reason="creating a symbolic link takes a privilege Windows does not grant by default"
+)
class TestAgentRunBundleAutoInputs:
@@ -102,3 +106,46 @@ class TestAgentRunBundleAutoInputs:
capsys.readouterr()
assert run_core_mock.call_args.kwargs["inputs"] == {"topic": "toml"}
+
+ @_NO_SYMLINKS_ON_WINDOWS
+ @pytest.mark.usefixtures("tty_stdin")
+ def test_an_auto_detected_link_is_refused(self, mocker: MockerFixture, bundle_dir: Path, capsys: pytest.CaptureFixture[str]) -> None:
+ """A link named inputs.json is never followed: the command emits the refusal envelope pointing to --inputs and runs nothing."""
+ set_agent_cli_error_format(CliOutputFormat.JSON)
+ run_core_mock = self._patch_run(mocker, {"answer": "42"})
+ outside = bundle_dir.parent / f"{bundle_dir.name}-outside.json"
+ outside.write_text('{"topic": "outside-sentinel"}', encoding="utf-8")
+ # The folder ignores its inputs file, as a checked-out method may, so its tree never holds the link and the
+ # auto-detection alone judges it.
+ (bundle_dir / ".gitignore").write_text("inputs.json\n", encoding="utf-8")
+ (bundle_dir / "inputs.json").symlink_to(outside)
+
+ with pytest.raises(typer.Exit) as exc_info:
+ run_bundle_cmd(path=str(bundle_dir), pipe="my_pipe", output_format=CliOutputFormat.JSON)
+
+ assert exc_info.value.exit_code == 1
+ envelope = json.loads(capsys.readouterr().err)
+ assert envelope["error_type"] == "AutoDetectedInputsFileError"
+ assert envelope["error_domain"] == "input"
+ assert "symbolic link" in envelope["message"]
+ assert "--inputs" in envelope["hint"]
+ assert "outside-sentinel" not in json.dumps(envelope)
+ run_core_mock.assert_not_called()
+
+ @_NO_SYMLINKS_ON_WINDOWS
+ @pytest.mark.usefixtures("tty_stdin")
+ def test_an_explicit_inputs_link_is_followed(self, mocker: MockerFixture, bundle_dir: Path, capsys: pytest.CaptureFixture[str]) -> None:
+ """An inputs file the caller names with --inputs is read as given, through a link."""
+ run_core_mock = self._patch_run(mocker, {"answer": "42"})
+ outside = bundle_dir.parent / f"{bundle_dir.name}-outside.json"
+ outside.write_text('{"topic": "outside-sentinel"}', encoding="utf-8")
+ # The folder ignores its inputs file, as a checked-out method may, so its tree never holds the link and the
+ # auto-detection alone judges it.
+ (bundle_dir / ".gitignore").write_text("inputs.json\n", encoding="utf-8")
+ link = bundle_dir / "inputs.json"
+ link.symlink_to(outside)
+
+ run_bundle_cmd(path=str(bundle_dir), pipe="my_pipe", inputs=str(link), output_format=CliOutputFormat.JSON)
+
+ capsys.readouterr()
+ assert run_core_mock.call_args.kwargs["inputs"] == {"topic": "outside-sentinel"}
diff --git a/tests/unit/pipelex/cli/commands/run/test_bundle_cmd_auto_inputs.py b/tests/unit/pipelex/cli/commands/run/test_bundle_cmd_auto_inputs.py
index 50136b000..9d5e72a75 100644
--- a/tests/unit/pipelex/cli/commands/run/test_bundle_cmd_auto_inputs.py
+++ b/tests/unit/pipelex/cli/commands/run/test_bundle_cmd_auto_inputs.py
@@ -2,11 +2,13 @@
from __future__ import annotations
+import sys
from typing import TYPE_CHECKING
import pytest
import typer
+from pipelex.cli.commands.run._inputs_file_loader import DetectedInputsFile
from pipelex.cli.commands.run.bundle_cmd import run_bundle_cmd
if TYPE_CHECKING:
@@ -15,6 +17,9 @@ if TYPE_CHECKING:
from pytest_mock import MockerFixture
BUNDLE_CMD_MODULE = "pipelex.cli.commands.run.bundle_cmd"
+_NO_SYMLINKS_ON_WINDOWS = pytest.mark.skipif(
+ sys.platform == "win32", reason="creating a symbolic link takes a privilege Windows does not grant by default"
+)
_BUNDLE = """
domain = "auto_inputs_tests"
@@ -37,22 +42,22 @@ class TestBundleCmdAutoInputs:
return tmp_path
def test_auto_detects_inputs_toml(self, mocker: MockerFixture, bundle_dir: Path) -> None:
- """With only inputs.toml in the directory, it is auto-detected and forwarded."""
+ """With only inputs.toml in the directory, it is auto-detected and forwarded with the bytes read from it."""
mock_execute = mocker.patch(f"{BUNDLE_CMD_MODULE}.execute_run")
(bundle_dir / "inputs.toml").write_text('topic = "cats"\n', encoding="utf-8")
run_bundle_cmd(path=str(bundle_dir))
- assert mock_execute.call_args.kwargs["inputs"] == str(bundle_dir / "inputs.toml")
+ assert mock_execute.call_args.kwargs["inputs"] == DetectedInputsFile(path=bundle_dir / "inputs.toml", data=b'topic = "cats"\n')
def test_auto_detects_inputs_json(self, mocker: MockerFixture, bundle_dir: Path) -> None:
- """With only inputs.json in the directory, today's auto-detection is unchanged."""
+ """With only inputs.json in the directory, it is auto-detected and forwarded with the bytes read from it."""
mock_execute = mocker.patch(f"{BUNDLE_CMD_MODULE}.execute_run")
(bundle_dir / "inputs.json").write_text('{"topic": "cats"}', encoding="utf-8")
run_bundle_cmd(path=str(bundle_dir))
- assert mock_execute.call_args.kwargs["inputs"] == str(bundle_dir / "inputs.json")
+ assert mock_execute.call_args.kwargs["inputs"] == DetectedInputsFile(path=bundle_dir / "inputs.json", data=b'{"topic": "cats"}')
def test_both_inputs_files_error(self, mocker: MockerFixture, bundle_dir: Path, capsys: pytest.CaptureFixture[str]) -> None:
"""With both inputs.json and inputs.toml present, the command exits telling the user to pass --inputs."""
@@ -77,3 +82,39 @@ class TestBundleCmdAutoInputs:
run_bundle_cmd(path=str(bundle_dir), inputs=str(explicit))
assert mock_execute.call_args.kwargs["inputs"] == str(explicit)
+
+ @_NO_SYMLINKS_ON_WINDOWS
+ def test_an_auto_detected_link_is_refused(self, mocker: MockerFixture, bundle_dir: Path, capsys: pytest.CaptureFixture[str]) -> None:
+ """A link named inputs.json is never followed, so a checked-out method cannot send data from outside its folder."""
+ mock_execute = mocker.patch(f"{BUNDLE_CMD_MODULE}.execute_run")
+ outside = bundle_dir.parent / f"{bundle_dir.name}-outside.json"
+ outside.write_text('{"topic": "outside-sentinel"}', encoding="utf-8")
+ # The folder ignores its inputs file, as a checked-out method may, so its tree never holds the link and the
+ # auto-detection alone judges it.
+ (bundle_dir / ".gitignore").write_text("inputs.json\n", encoding="utf-8")
+ (bundle_dir / "inputs.json").symlink_to(outside)
+
+ with pytest.raises(typer.Exit) as exc_info:
+ run_bundle_cmd(path=str(bundle_dir))
+
+ assert exc_info.value.exit_code == 1
+ stderr = capsys.readouterr().err
+ assert "symbolic link" in stderr
+ assert "--inputs" in stderr
+ mock_execute.assert_not_called()
+
+ @_NO_SYMLINKS_ON_WINDOWS
+ def test_an_explicit_inputs_link_is_followed(self, mocker: MockerFixture, bundle_dir: Path) -> None:
+ """An inputs file the caller names is read as given, a link included."""
+ mock_execute = mocker.patch(f"{BUNDLE_CMD_MODULE}.execute_run")
+ outside = bundle_dir.parent / f"{bundle_dir.name}-outside.json"
+ outside.write_text('{"topic": "outside-sentinel"}', encoding="utf-8")
+ # The folder ignores its inputs file, as a checked-out method may, so its tree never holds the link and the
+ # auto-detection alone judges it.
+ (bundle_dir / ".gitignore").write_text("inputs.json\n", encoding="utf-8")
+ link = bundle_dir / "inputs.json"
+ link.symlink_to(outside)
+
+ run_bundle_cmd(path=str(bundle_dir), inputs=str(link))
+
+ assert mock_execute.call_args.kwargs["inputs"] == str(link)
diff --git a/tests/unit/pipelex/cli/commands/run/test_inputs_file_loader.py b/tests/unit/pipelex/cli/commands/run/test_inputs_file_loader.py
index 9d0ae12c8..546ca0b3c 100644
--- a/tests/unit/pipelex/cli/commands/run/test_inputs_file_loader.py
+++ b/tests/unit/pipelex/cli/commands/run/test_inputs_file_loader.py
@@ -9,6 +9,7 @@ from typing import TYPE_CHECKING
import pytest
from pipelex.cli.commands.run._inputs_file_loader import (
+ load_inputs_dict_from_bytes,
load_inputs_dict_from_path, # pyright: ignore[reportPrivateUsage]
)
from pipelex.core.stuffs.date_content import DateContent
@@ -78,6 +79,19 @@ class TestInputsFileLoader:
with pytest.raises(JsonTypeError):
load_inputs_dict_from_path(inputs_file)
+ @pytest.mark.parametrize(
+ ("file_name", "data", "expected"),
+ [
+ ("inputs.toml", b'topic = "cats"\nwhen = 2026-10-17\n', {"topic": "cats", "when": DateContent(date=datetime.date(2026, 10, 17))}),
+ ("inputs.json", b'{"topic": "dogs"}', {"topic": "dogs"}),
+ ],
+ )
+ def test_bytes_load_as_the_file_would_without_opening_the_path(
+ self, tmp_path: Path, file_name: str, data: bytes, expected: dict[str, object]
+ ) -> None:
+ """The path only selects the parser: the bytes are parsed, and the path, which does not exist here, is never opened."""
+ assert load_inputs_dict_from_bytes(data=data, path=tmp_path / "absent" / file_name) == expected
+
def test_missing_file_raises_file_not_found(self, tmp_path: Path) -> None:
"""A missing file raises FileNotFoundError for both formats."""
with pytest.raises(FileNotFoundError):
diff --git a/tests/unit/pipelex/cli/commands/run/test_inputs_file_probe.py b/tests/unit/pipelex/cli/commands/run/test_inputs_file_probe.py
index e7c23c4ef..8793eaca9 100644
--- a/tests/unit/pipelex/cli/commands/run/test_inputs_file_probe.py
+++ b/tests/unit/pipelex/cli/commands/run/test_inputs_file_probe.py
@@ -2,37 +2,45 @@
from __future__ import annotations
+import os
+import stat
+import sys
from typing import TYPE_CHECKING
import pytest
-from pipelex.cli.commands.run._inputs_file_loader import (
- find_default_inputs_file, # pyright: ignore[reportPrivateUsage]
-)
-from pipelex.cli.commands.run.exceptions import AmbiguousInputsFilesError
+from pipelex.cli.commands.run._inputs_file_loader import DetectedInputsFile, read_default_inputs_file
+from pipelex.cli.commands.run.exceptions import AmbiguousInputsFilesError, AutoDetectedInputsFileError
if TYPE_CHECKING:
from pathlib import Path
+ from pytest_mock import MockerFixture
+
+LOADER_MODULE = "pipelex.cli.commands.run._inputs_file_loader"
+_NO_SYMLINKS_ON_WINDOWS = pytest.mark.skipif(
+ sys.platform == "win32", reason="creating a symbolic link takes a privilege Windows does not grant by default"
+)
+
-class TestFindDefaultInputsFile:
- def test_json_only_is_found(self, tmp_path: Path) -> None:
- """With only inputs.json present, the probe returns it."""
+class TestReadDefaultInputsFile:
+ def test_json_only_is_found_and_read(self, tmp_path: Path) -> None:
+ """With only inputs.json present, the probe returns it with its bytes."""
json_file = tmp_path / "inputs.json"
- json_file.write_text("{}", encoding="utf-8")
+ json_file.write_text('{"topic": "cats"}', encoding="utf-8")
- assert find_default_inputs_file(directory=tmp_path) == json_file
+ assert read_default_inputs_file(directory=tmp_path) == DetectedInputsFile(path=json_file, data=b'{"topic": "cats"}')
- def test_toml_only_is_found(self, tmp_path: Path) -> None:
- """With only inputs.toml present, the probe returns it."""
+ def test_toml_only_is_found_and_read(self, tmp_path: Path) -> None:
+ """With only inputs.toml present, the probe returns it with its bytes."""
toml_file = tmp_path / "inputs.toml"
- toml_file.write_text("", encoding="utf-8")
+ toml_file.write_text('topic = "cats"\n', encoding="utf-8")
- assert find_default_inputs_file(directory=tmp_path) == toml_file
+ assert read_default_inputs_file(directory=tmp_path) == DetectedInputsFile(path=toml_file, data=b'topic = "cats"\n')
def test_neither_returns_none(self, tmp_path: Path) -> None:
"""With neither default file present, the probe returns None."""
- assert find_default_inputs_file(directory=tmp_path) is None
+ assert read_default_inputs_file(directory=tmp_path) is None
def test_both_present_raises_ambiguity_error(self, tmp_path: Path) -> None:
"""With both default files present, the probe hard-errors telling the user to pass --inputs."""
@@ -40,7 +48,88 @@ class TestFindDefaultInputsFile:
(tmp_path / "inputs.toml").write_text("", encoding="utf-8")
with pytest.raises(AmbiguousInputsFilesError) as exc_info:
- find_default_inputs_file(directory=tmp_path)
+ read_default_inputs_file(directory=tmp_path)
assert "--inputs" in exc_info.value.message
assert "inputs.json" in exc_info.value.message
assert "inputs.toml" in exc_info.value.message
+
+ @_NO_SYMLINKS_ON_WINDOWS
+ @pytest.mark.parametrize("name", ["inputs.json", "inputs.toml"])
+ @pytest.mark.parametrize(
+ ("entry", "described_as"),
+ [
+ ("link_outside", "a symbolic link"),
+ ("dangling_link", "a symbolic link"),
+ ("directory", "a directory"),
+ ],
+ )
+ def test_an_entry_that_is_not_a_regular_file_is_refused(self, tmp_path: Path, name: str, entry: str, described_as: str) -> None:
+ """A link is never followed, so a method's folder cannot point its inputs at data outside it; a directory is refused too."""
+ method_dir = tmp_path / "method"
+ method_dir.mkdir()
+ candidate = method_dir / name
+ if entry == "link_outside":
+ outside = tmp_path / "secrets.json"
+ outside.write_text('{"token": "not-for-the-run"}', encoding="utf-8")
+ candidate.symlink_to(outside)
+ elif entry == "dangling_link":
+ candidate.symlink_to(tmp_path / "nowhere.json")
+ else:
+ candidate.mkdir()
+
+ with pytest.raises(AutoDetectedInputsFileError) as exc_info:
+ read_default_inputs_file(directory=method_dir)
+
+ message = exc_info.value.message
+ assert str(candidate) in message
+ assert described_as in message
+ assert "--inputs" in message
+ assert "not-for-the-run" not in message
+
+ @_NO_SYMLINKS_ON_WINDOWS
+ def test_a_link_beside_a_regular_file_of_the_other_name_is_ambiguous(self, tmp_path: Path) -> None:
+ """Both names are present whatever each entry is, so the ambiguity rule answers first and asks for --inputs."""
+ (tmp_path / "inputs.json").write_text("{}", encoding="utf-8")
+ (tmp_path / "inputs.toml").symlink_to(tmp_path / "inputs.json")
+
+ with pytest.raises(AmbiguousInputsFilesError):
+ read_default_inputs_file(directory=tmp_path)
+
+ @_NO_SYMLINKS_ON_WINDOWS
+ @pytest.mark.parametrize(
+ ("swapped_in", "described_as"),
+ [
+ ("link", "a symbolic link"),
+ ("directory", "a directory"),
+ ("named_pipe", "not a regular file"),
+ ],
+ )
+ def test_an_entry_swapped_after_the_lookup_is_refused_when_opened(
+ self, mocker: MockerFixture, tmp_path: Path, swapped_in: str, described_as: str
+ ) -> None:
+ """The lookup saw a regular file, then the entry changed: the open never follows a link nor blocks, and the descriptor is judged."""
+ if swapped_in == "named_pipe" and not hasattr(os, "mkfifo"):
+ pytest.skip("this platform has no named pipes")
+ method_dir = tmp_path / "method"
+ method_dir.mkdir()
+ candidate = method_dir / "inputs.json"
+ if swapped_in == "link":
+ outside = tmp_path / "secrets.json"
+ outside.write_text('{"token": "not-for-the-run"}', encoding="utf-8")
+ candidate.symlink_to(outside)
+ elif swapped_in == "directory":
+ candidate.mkdir()
+ else:
+ os.mkfifo(candidate)
+
+ def mode_seen_before_the_swap(*, path: Path) -> int | None:
+ """What the lookup saw before the swap: a regular file named inputs.json, and no inputs.toml."""
+ return stat.S_IFREG | 0o644 if path == candidate else None
+
+ mocker.patch(f"{LOADER_MODULE}._entry_mode", side_effect=mode_seen_before_the_swap)
+
+ with pytest.raises(AutoDetectedInputsFileError) as exc_info:
+ read_default_inputs_file(directory=method_dir)
+
+ assert described_as in exc_info.value.message
+ assert "not-for-the-run" not in exc_info.value.message
diff --git a/tests/unit/pipelex/cli/commands/run/test_load_run_inputs.py b/tests/unit/pipelex/cli/commands/run/test_load_run_inputs.py
new file mode 100644
index 000000000..5d0cbd887
--- /dev/null
+++ b/tests/unit/pipelex/cli/commands/run/test_load_run_inputs.py
@@ -0,0 +1,31 @@
+"""Unit tests for `load_run_inputs`, the run CLI's reading of `--inputs` or of the inputs file auto-detection found."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pipelex.cli.commands.run._inputs_file_loader import DetectedInputsFile
+from pipelex.cli.commands.run._run_core import LoadedRunInputs, load_run_inputs
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+
+class TestLoadRunInputs:
+ def test_an_auto_detected_file_is_parsed_from_the_bytes_read_and_never_reopened(self, tmp_path: Path) -> None:
+ """The path now holds other content, as an entry swapped after the read would: the bytes auto-detection read are what loads."""
+ inputs_file = tmp_path / "inputs.json"
+ inputs_file.write_text('{"topic": "swapped-in-after-the-read"}', encoding="utf-8")
+
+ loaded = load_run_inputs(inputs=DetectedInputsFile(path=inputs_file, data=b'{"topic": "read-without-following-a-link"}'))
+
+ assert loaded == LoadedRunInputs(pipeline_inputs={"topic": "read-without-following-a-link"}, inputs_base_dir=tmp_path.resolve())
+
+ def test_an_explicit_inputs_file_is_read_from_its_path(self, tmp_path: Path) -> None:
+ """A file named with --inputs is read as given."""
+ inputs_file = tmp_path / "inputs.toml"
+ inputs_file.write_text('topic = "cats"\n', encoding="utf-8")
+
+ loaded = load_run_inputs(inputs=str(inputs_file))
+
+ assert loaded == LoadedRunInputs(pipeline_inputs={"topic": "cats"}, inputs_base_dir=tmp_path.resolve())
diff --git a/tests/unit/pipelex/libraries/test_method_trees.py b/tests/unit/pipelex/libraries/test_method_trees.py
index aad74b62f..8db4853e7 100644
--- a/tests/unit/pipelex/libraries/test_method_trees.py
+++ b/tests/unit/pipelex/libraries/test_method_trees.py
@@ -240,3 +240,38 @@ class TestMethodTrees:
sources.update(tree_python_sources(tree=library_tree.tree, library_dir=library_tree.library_dir))
assert sources == {"top_funcs.py": "X = 1\n", "checkouts/reports/models/report.py": "X = 2\n"}
+
+ def test_a_directory_named_like_an_inputs_file_is_entered_and_kept(self, tmp_path: Path) -> None:
+ """A directory named like a run's inputs file is an ordinary directory: the scan enters `inputs.json/` and its bundle loads."""
+ _touch(directory=tmp_path, tree_path="top.mthds")
+ _touch(directory=tmp_path, tree_path="vendor/tool/inputs.json/flow.mthds")
+ _touch(directory=tmp_path, tree_path="vendor/tool/inputs.toml/notes.md", content="kept")
+ (tmp_path / "vendor" / "tool" / ".git").mkdir()
+
+ library_trees = list_library_dir_trees(library_dirs=[tmp_path])
+
+ tool_tree = next(
+ library_tree.tree for library_tree in library_trees if library_tree.tree.directory == (tmp_path / "vendor" / "tool").resolve()
+ )
+ assert tool_tree.tree_paths == ["inputs.json/flow.mthds", "inputs.toml/notes.md"]
+ bundle_paths = {bundle_file.path for bundle_file in list_library_bundle_files(library_dirs=[tmp_path])}
+ assert bundle_paths == {tmp_path / "top.mthds", tmp_path / "vendor" / "tool" / "inputs.json" / "flow.mthds"}
+
+ @pytest.mark.xfail(
+ raises=MethodTreeLoadError,
+ reason="The run-inputs default is applied by the mthds lister from the mthds release implementing it, not pinned yet",
+ )
+ def test_a_run_s_inputs_file_is_no_member_of_any_tree_at_any_depth(self, tmp_path: Path) -> None:
+ """An inputs.json or inputs.toml, regular file or link never followed, stays out at the root and below; names match byte for byte."""
+ outside = _touch(directory=tmp_path, tree_path="outside/secrets.json", content='{"token": "x"}')
+ method_dir = tmp_path / "method"
+ _touch(directory=method_dir, tree_path="method.mthds")
+ _touch(directory=method_dir, tree_path="inputs.json", content='{"topic": "cats"}')
+ _touch(directory=method_dir, tree_path="steps/inputs.toml", content='topic = "cats"\n')
+ _touch(directory=method_dir, tree_path="cases/Inputs.json", content="{}")
+ (method_dir / "examples").mkdir()
+ (method_dir / "examples" / "inputs.json").symlink_to(outside)
+
+ (library_tree,) = list_library_dir_trees(library_dirs=[method_dir])
+
+ assert library_tree.tree.tree_paths == ["cases/Inputs.json", "method.mthds"]