toolfuncs 0.5.0__tar.gz → 0.7.0__tar.gz

{toolfuncs-0.5.0 → toolfuncs-0.7.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: toolfuncs
-Version: 0.5.0
-Summary: Executable typed Python function tools discovered through PATH
+Version: 0.7.0
+Summary: Executable typed Python function tools invoked by path or discovered through PATH
 Project-URL: Repository, https://github.com/nimashoghi/toolfuncs
 Project-URL: Issues, https://github.com/nimashoghi/toolfuncs/issues
 Author-email: Nima Shoghi <nima@boltz.bio>
@@ -20,7 +20,7 @@ Description-Content-Type: text/markdown
 
 `toolfuncs` turns typed Python functions into tools that have matching Python and command-line interfaces.
 
-A toolfunc is one executable Python script on `PATH`. Its lowercase kebab-case filename is its command name, and its Python import name is the same spelling with hyphens replaced by underscores. Its implementation may import any packages declared in its PEP 723 requirements, but packages and projects are not themselves discoverable toolfuncs.
+A toolfunc is one executable Python script. Its lowercase kebab-case filename is its command name, and its Python import name is the same spelling with hyphens replaced by underscores. A known source can be called or imported directly from any path. Putting it on `PATH` additionally makes its filename a shell command and exposes it to discovery and dynamic Python lookup. Its implementation may import any packages declared in its PEP 723 requirements, but packages and projects are not themselves toolfuncs.
 
 ## Write a toolfunc
 
@@ -45,28 +45,55 @@ app = toolsdk.App()
 
 @app.command
 def current(city: str) -> dict[str, object]:
+    """Read current conditions for one city.
+
+    Parameters
+    ----------
+    city:
+        City whose current conditions should be read.
+    """
+
     return weather_client.current(city)
 ```
 
-Make it executable and place it in any existing `PATH` directory:
+Make it executable:
 
 ```console
 chmod +x weather-report
-mv weather-report ~/.local/bin/
 ```
 
-That is the complete registration operation.
+No registration operation is required. Move it to an existing `PATH` directory only when it should be globally discoverable:
+
+```console
+mv weather-report ~/.local/bin/
+```
 
 ## Call it
 
-The executable is the CLI:
+A known source can be run explicitly without adding it to `PATH`:
+
+```console
+$ toolfuncs ./weather-report current London
+{"city": "London", "temperature": 18}
+```
+
+When the source is on `PATH`, its filename is also the CLI:
 
 ```console
 $ weather-report current London
 {"city": "London", "temperature": 18}
 ```
 
-The same file is dynamically importable in a Python process that has `toolfuncs` installed and the same `PATH`:
+A known source is importable by path:
+
+```python
+import toolfuncs as tools
+
+weather_report = tools.import_path("./weather-report")
+conditions = weather_report.current("London")
+```
+
+When the source is on `PATH`, the same file is also dynamically importable by name in a Python process with that `PATH`:
 
 ```python
 import toolfuncs as tools
@@ -74,8 +101,7 @@ import toolfuncs as tools
 conditions = tools.weather_report.current("London")
 ```
 
-`import_path()` is the narrower utility for a local script whose path is already
-known:
+`import_path()` also works for an ordinary local Python script whose path is already known:
 
 ```python
 import toolfuncs as tools
@@ -83,8 +109,7 @@ import toolfuncs as tools
 module = tools.import_path("scripts/prepare_data.py")
 ```
 
-It accepts one ordinary `.py` file or extensionless script and derives the
-module name from its filename. It does not require a shebang, executable bit,
+It accepts one ordinary `.py` file or extensionless script and derives the module name from its filename. An extensionless lowercase kebab-case filename is mapped to its snake-case Python name. It does not require a shebang, executable bit,
 `[tool.toolfuncs]` metadata, or `App`, and it does not import packages, projects,
 distributions, or URLs. When an optional PEP 723 block exists, the default
 installer installs all declared requirements together into the running Python
@@ -102,14 +127,15 @@ Direct Python calls return ordinary Python objects and raise the original except
 
 ## Source contract
 
-A discoverable toolfunc must:
+A toolfunc source must:
 
-1. be one executable file in a directory on `PATH`;
+1. be one executable file;
 2. have an extensionless lowercase ASCII kebab-case filename;
 3. start with one of the two exact toolfuncs shebangs described below;
 4. contain exactly one PEP 723 `script` block with `dependencies`, a one-line description, and required `cli_name` and `python_name` documentation that exactly matches the filename-derived identities;
 5. define a module-level `app = toolsdk.App()` after `import toolfuncs.sdk as toolsdk`;
-6. register each CLI-callable function explicitly with `@app.command`.
+6. give the module and every registered operation a docstring, annotate every operation parameter and return value, and provide effective Cyclopts help for every visible CLI argument;
+7. register each CLI-callable function explicitly with `@app.command`.
 
 The PEP 723 dependency list contains the packages needed in addition to the running toolfuncs environment. Listing `toolfuncs` itself is accepted but normally redundant because the shebang has already started the toolfuncs runtime before dependencies are prepared.
 
@@ -153,6 +179,30 @@ The first executable filename claims a command name even when it is not a toolfu
 
 `toolfuncs list` returns one JSON object with `tools` and `invalid_tools`. Valid records contain `cli_name`, `python_name`, `path`, and `description`. An opted-in but invalid tool is reported with its path and validation error without hiding unrelated valid tools; the command also prints a concise warning to stderr and exits successfully. Listing never imports a tool, prepares its dependencies, or executes its source.
 
+## Validate a tool while authoring
+
+Run the doctor against one explicit source before installing or committing it:
+
+```console
+toolfuncs doctor ./weather-report
+```
+
+The doctor validates the static source contract, prepares the declared dependencies, loads the source, and inspects the actual Cyclopts command graph. It requires a module docstring, at least one registered operation, a docstring and complete annotations for every operation, effective help text for every visible parsed CLI argument, and successful root and command help generation. Aliases are inspected once through their underlying command.
+
+The result is always one strict-JSON tagged union. A valid source exits zero:
+
+```json
+{"status": "success", "path": "/path/to/weather-report", "commands": ["current"]}
+```
+
+Expected authoring failures return `status: "error"`, list every independently detectable operation error, and exit nonzero without using an exception as the result:
+
+```json
+{"status": "error", "path": "/path/to/weather-report", "errors": ["current: CLI argument '--city' must have help text"]}
+```
+
+Loading is intentional: the registered command graph and Cyclopts' effective parameter help can be constructed dynamically and should not be approximated with a second source parser. Run the doctor in a suitable disposable environment when dependency isolation matters.
+
 ## Install the runtime
 
 ```console
@@ -182,11 +232,13 @@ Setup does not discover, copy, register, link, synchronize, or remove tools. The
 ## Management commands
 
 ```console
+toolfuncs SOURCE [ARGS...]
+toolfuncs doctor SOURCE
 toolfuncs list
 toolfuncs setup [--bin-dir DIRECTORY]
 ```
 
-The source-path argument supplied automatically by `#!/usr/bin/env toolfuncs` is runtime plumbing rather than another user-facing command. Tools are invoked directly by their own names.
+`toolfuncs SOURCE [ARGS...]` runs a known source directly. This is the explicit-source interface, not a name dispatcher: `toolfuncs weather-report` resolves `weather-report` as a source path rather than searching `PATH` for that tool name. A toolfunc on `PATH` can instead be invoked directly by its own filename.
 
 ## Agent integration
 
@@ -211,7 +263,7 @@ uv run ruff check .
 uv run basedpyright
 ```
 
-The exact 0.4 guarantees and non-goals are recorded in [the contract](docs/contract.md).
+The exact guarantees and non-goals are recorded in [the contract](docs/contract.md).
 
 ## Releasing
 

{toolfuncs-0.5.0 → toolfuncs-0.7.0}/README.md

@@ -2,7 +2,7 @@
 
 `toolfuncs` turns typed Python functions into tools that have matching Python and command-line interfaces.
 
-A toolfunc is one executable Python script on `PATH`. Its lowercase kebab-case filename is its command name, and its Python import name is the same spelling with hyphens replaced by underscores. Its implementation may import any packages declared in its PEP 723 requirements, but packages and projects are not themselves discoverable toolfuncs.
+A toolfunc is one executable Python script. Its lowercase kebab-case filename is its command name, and its Python import name is the same spelling with hyphens replaced by underscores. A known source can be called or imported directly from any path. Putting it on `PATH` additionally makes its filename a shell command and exposes it to discovery and dynamic Python lookup. Its implementation may import any packages declared in its PEP 723 requirements, but packages and projects are not themselves toolfuncs.
 
 ## Write a toolfunc
 
@@ -27,28 +27,55 @@ app = toolsdk.App()
 
 @app.command
 def current(city: str) -> dict[str, object]:
+    """Read current conditions for one city.
+
+    Parameters
+    ----------
+    city:
+        City whose current conditions should be read.
+    """
+
     return weather_client.current(city)
 ```
 
-Make it executable and place it in any existing `PATH` directory:
+Make it executable:
 
 ```console
 chmod +x weather-report
-mv weather-report ~/.local/bin/
 ```
 
-That is the complete registration operation.
+No registration operation is required. Move it to an existing `PATH` directory only when it should be globally discoverable:
+
+```console
+mv weather-report ~/.local/bin/
+```
 
 ## Call it
 
-The executable is the CLI:
+A known source can be run explicitly without adding it to `PATH`:
+
+```console
+$ toolfuncs ./weather-report current London
+{"city": "London", "temperature": 18}
+```
+
+When the source is on `PATH`, its filename is also the CLI:
 
 ```console
 $ weather-report current London
 {"city": "London", "temperature": 18}
 ```
 
-The same file is dynamically importable in a Python process that has `toolfuncs` installed and the same `PATH`:
+A known source is importable by path:
+
+```python
+import toolfuncs as tools
+
+weather_report = tools.import_path("./weather-report")
+conditions = weather_report.current("London")
+```
+
+When the source is on `PATH`, the same file is also dynamically importable by name in a Python process with that `PATH`:
 
 ```python
 import toolfuncs as tools
@@ -56,8 +83,7 @@ import toolfuncs as tools
 conditions = tools.weather_report.current("London")
 ```
 
-`import_path()` is the narrower utility for a local script whose path is already
-known:
+`import_path()` also works for an ordinary local Python script whose path is already known:
 
 ```python
 import toolfuncs as tools
@@ -65,8 +91,7 @@ import toolfuncs as tools
 module = tools.import_path("scripts/prepare_data.py")
 ```
 
-It accepts one ordinary `.py` file or extensionless script and derives the
-module name from its filename. It does not require a shebang, executable bit,
+It accepts one ordinary `.py` file or extensionless script and derives the module name from its filename. An extensionless lowercase kebab-case filename is mapped to its snake-case Python name. It does not require a shebang, executable bit,
 `[tool.toolfuncs]` metadata, or `App`, and it does not import packages, projects,
 distributions, or URLs. When an optional PEP 723 block exists, the default
 installer installs all declared requirements together into the running Python
@@ -84,14 +109,15 @@ Direct Python calls return ordinary Python objects and raise the original except
 
 ## Source contract
 
-A discoverable toolfunc must:
+A toolfunc source must:
 
-1. be one executable file in a directory on `PATH`;
+1. be one executable file;
 2. have an extensionless lowercase ASCII kebab-case filename;
 3. start with one of the two exact toolfuncs shebangs described below;
 4. contain exactly one PEP 723 `script` block with `dependencies`, a one-line description, and required `cli_name` and `python_name` documentation that exactly matches the filename-derived identities;
 5. define a module-level `app = toolsdk.App()` after `import toolfuncs.sdk as toolsdk`;
-6. register each CLI-callable function explicitly with `@app.command`.
+6. give the module and every registered operation a docstring, annotate every operation parameter and return value, and provide effective Cyclopts help for every visible CLI argument;
+7. register each CLI-callable function explicitly with `@app.command`.
 
 The PEP 723 dependency list contains the packages needed in addition to the running toolfuncs environment. Listing `toolfuncs` itself is accepted but normally redundant because the shebang has already started the toolfuncs runtime before dependencies are prepared.
 
@@ -135,6 +161,30 @@ The first executable filename claims a command name even when it is not a toolfu
 
 `toolfuncs list` returns one JSON object with `tools` and `invalid_tools`. Valid records contain `cli_name`, `python_name`, `path`, and `description`. An opted-in but invalid tool is reported with its path and validation error without hiding unrelated valid tools; the command also prints a concise warning to stderr and exits successfully. Listing never imports a tool, prepares its dependencies, or executes its source.
 
+## Validate a tool while authoring
+
+Run the doctor against one explicit source before installing or committing it:
+
+```console
+toolfuncs doctor ./weather-report
+```
+
+The doctor validates the static source contract, prepares the declared dependencies, loads the source, and inspects the actual Cyclopts command graph. It requires a module docstring, at least one registered operation, a docstring and complete annotations for every operation, effective help text for every visible parsed CLI argument, and successful root and command help generation. Aliases are inspected once through their underlying command.
+
+The result is always one strict-JSON tagged union. A valid source exits zero:
+
+```json
+{"status": "success", "path": "/path/to/weather-report", "commands": ["current"]}
+```
+
+Expected authoring failures return `status: "error"`, list every independently detectable operation error, and exit nonzero without using an exception as the result:
+
+```json
+{"status": "error", "path": "/path/to/weather-report", "errors": ["current: CLI argument '--city' must have help text"]}
+```
+
+Loading is intentional: the registered command graph and Cyclopts' effective parameter help can be constructed dynamically and should not be approximated with a second source parser. Run the doctor in a suitable disposable environment when dependency isolation matters.
+
 ## Install the runtime
 
 ```console
@@ -164,11 +214,13 @@ Setup does not discover, copy, register, link, synchronize, or remove tools. The
 ## Management commands
 
 ```console
+toolfuncs SOURCE [ARGS...]
+toolfuncs doctor SOURCE
 toolfuncs list
 toolfuncs setup [--bin-dir DIRECTORY]
 ```
 
-The source-path argument supplied automatically by `#!/usr/bin/env toolfuncs` is runtime plumbing rather than another user-facing command. Tools are invoked directly by their own names.
+`toolfuncs SOURCE [ARGS...]` runs a known source directly. This is the explicit-source interface, not a name dispatcher: `toolfuncs weather-report` resolves `weather-report` as a source path rather than searching `PATH` for that tool name. A toolfunc on `PATH` can instead be invoked directly by its own filename.
 
 ## Agent integration
 
@@ -193,7 +245,7 @@ uv run ruff check .
 uv run basedpyright
 ```
 
-The exact 0.4 guarantees and non-goals are recorded in [the contract](docs/contract.md).
+The exact guarantees and non-goals are recorded in [the contract](docs/contract.md).
 
 ## Releasing
 

{toolfuncs-0.5.0 → toolfuncs-0.7.0}/docs/contract.md

@@ -1,4 +1,4 @@
-# toolfuncs 0.4 contract
+# toolfuncs 0.7 contract
 
 ## Purpose
 
@@ -6,9 +6,9 @@ Toolfuncs projects one explicitly registered set of typed Python functions into
 
 ## Tool identity and source
 
-A toolfunc is one executable regular file or symlink in a directory on `PATH`. Its first line is exactly `#!/usr/bin/env toolfuncs`, or the explicit floating-VCS form `#!/usr/bin/env -S toolfuncs --allow-floating-vcs`.
+A toolfunc is one executable regular file or symlink. Its first line is exactly `#!/usr/bin/env toolfuncs`, or the explicit floating-VCS form `#!/usr/bin/env -S toolfuncs --allow-floating-vcs`.
 
-The PATH-visible extensionless filename is the CLI command and must use lowercase ASCII kebab-case: a letter followed by letters or digits, with optional single hyphens separating further nonempty letter-or-digit segments. The Python name is the CLI name with every hyphen replaced by an underscore. A Python name that conflicts with `toolfuncs.sdk` or `toolfuncs.import_path` is invalid.
+The extensionless filename is the CLI command and must use lowercase ASCII kebab-case: a letter followed by letters or digits, with optional single hyphens separating further nonempty letter-or-digit segments. The Python name is the CLI name with every hyphen replaced by an underscore. A Python name that conflicts with `toolfuncs.sdk` or `toolfuncs.import_path` is invalid.
 
 The source contains exactly one PEP 723 `script` block. `dependencies` is a list of valid Python requirement strings and `requires-python` is optional. `[tool.toolfuncs]` contains exactly three required documentation fields:
 
@@ -21,7 +21,7 @@ python_name = "session_history"
 
 The declared names do not override runtime identity. `cli_name` must equal the PATH entry's filename, and `python_name` must equal the mechanically derived Python name. A source reached through a symlink therefore documents the symlink basename rather than its target basename. One source has one supported CLI identity; aliases are not part of the contract.
 
-The source imports the authoring API as `import toolfuncs.sdk as toolsdk`, defines a module-level `app`, normally `app = toolsdk.App()`, and registers every CLI-callable operation explicitly. Function signatures, annotations, defaults, docstrings, return values, side effects, and exceptions define the operations. `__all__` retains its ordinary Python meaning and does not register commands.
+The source imports the authoring API as `import toolfuncs.sdk as toolsdk`, defines a module-level `app`, normally `app = toolsdk.App()`, and registers every CLI-callable operation explicitly. The module and every registered operation have docstrings. Every operation parameter and return value is annotated, and every visible parsed CLI argument has effective Cyclopts help from its function docstring or richer parameter metadata. Function signatures, annotations, defaults, docstrings, return values, side effects, and exceptions define the operations. `__all__` retains its ordinary Python meaning and does not register commands.
 
 `toolsdk.App` supplies strict JSON serialization as its default result action. An explicit `result_action=` replaces that default unchanged. Advanced builder values such as `Parameter`, `Group`, validators, and result helpers live under `toolfuncs.sdk`, not the package root.
 
@@ -40,7 +40,7 @@ Dynamic attribute lookup maps the requested snake-case Python name to its kebab-
 
 The package root publicly exposes only dynamic tools and `import_path`. There is no public `load`, discovery, setup, record, error, or builder API at the root. `import toolfuncs.NAME` is not promised because discovered tools are dynamic package attributes rather than installed submodules.
 
-`import_path` remains separate. It imports one already-known local `.py` file or extensionless script, derives its module name from that source filename, optionally prepares ordinary PEP 723 dependencies, and does not require the toolfuncs shebang, identity metadata, executable permission, or a module-level app.
+`import_path` remains separate. It imports one already-known local `.py` file or extensionless script, derives its module name from that source filename, maps a valid extensionless kebab-case filename to snake case, optionally prepares ordinary PEP 723 dependencies, and does not require the toolfuncs shebang, identity metadata, executable permission, or a module-level app.
 
 ## Dependencies
 
@@ -60,9 +60,15 @@ An exact-shebang source opts into validation. Discovery records an invalid opted
 
 Direct invocation or Python lookup of an invalid tool fails with its validation error.
 
+## Authoring validation
+
+`toolfuncs doctor SOURCE` validates one explicit source, including a source that is not yet on `PATH`. The source must still be executable and satisfy the ordinary filename, shebang, metadata, identity, and dependency policies. Doctor prepares its dependencies, imports the source, resolves its actual Cyclopts command graph, and validates the module docstring, registered operations, operation docstrings and annotations, effective help for every visible parsed CLI argument, and root and command help generation. Aliases are deduplicated through the underlying command object, and nested commands are inspected recursively.
+
+The command emits one strict-JSON tagged union. `DoctorSuccess` has `status: "success"`, the absolute source path, and the resolved command paths; it exits zero. `DoctorFailure` has `status: "error"`, the absolute source path, and all independently detectable errors; it exits nonzero. A source validation, dependency, or import failure prevents runtime inspection and therefore produces one loading error. Expected authoring failures are result values rather than exceptions; unexpected failures in the doctor itself retain ordinary exception behavior.
+
 ## CLI execution
 
-When the operating system executes a tool, `/usr/bin/env` resolves the managed `toolfuncs` wrapper on `PATH` and passes it the PATH-visible source path followed by the user's arguments. The wrapper validates dependency policy, starts one uv-prepared environment, and invokes the runtime. Toolfuncs validates identity metadata, imports the source under `python_name`, obtains its module-level app, preserves the exact CLI filename as the Cyclopts program name, and invokes the app with the remaining arguments.
+`toolfuncs SOURCE [ARGS...]` runs a known source without requiring that source to be on `PATH`. It resolves `SOURCE` as a filesystem path and does not search `PATH` for a tool name. When the operating system executes a tool that is on `PATH`, `/usr/bin/env` resolves the managed `toolfuncs` wrapper and passes it the source path followed by the user's arguments. In either form, the wrapper validates dependency policy, starts one uv-prepared environment, and invokes the runtime. Toolfuncs validates identity metadata, imports the source under `python_name`, obtains its module-level app, preserves the exact CLI filename as the Cyclopts program name, and invokes the app with the remaining arguments.
 
 The source is imported rather than executed as `__main__`. A main guard is neither required nor used. Plain `python SOURCE ...` does not invoke the CLI and does not prepare PEP 723 dependencies.
 
@@ -74,8 +80,8 @@ Successful default CLI operations emit one strict JSON value. CLI parsing, valid
 
 Setup does not discover, install, copy, link, register, synchronize, or remove tool sources. Adding and removing tools are ordinary filesystem operations in directories already on `PATH`.
 
-The public management commands are `toolfuncs list` and `toolfuncs setup [--bin-dir DIRECTORY]`. Tools are invoked directly by their own CLI names. There is no universal name dispatcher, `run`, `exec`, `describe`, or `sync` command.
+The public management commands are `toolfuncs doctor SOURCE`, `toolfuncs list`, and `toolfuncs setup [--bin-dir DIRECTORY]`. The explicit-source execution form is `toolfuncs SOURCE [ARGS...]`; it is not a universal name dispatcher. Tools on `PATH` are invoked directly by their own CLI names. There is no `run`, `exec`, `describe`, or `sync` command.
 
 ## Compatibility
 
-Version 0.4 intentionally does not accept the former underscore executable names, missing identity declarations, root-level builder exports, public `load`, or public discovery records. All controlled tools must migrate with the runtime.
+Version 0.7 adds public explicit-source CLI execution and maps extensionless kebab-case names to snake case in `import_path`. It retains the 0.6 runtime, identity, discovery, and authoring contracts. It intentionally does not accept the former underscore executable names, missing identity declarations, root-level builder exports, public `load`, or public discovery records. All controlled tools must migrate with the runtime.

{toolfuncs-0.5.0 → toolfuncs-0.7.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "toolfuncs"
-version = "0.5.0"
-description = "Executable typed Python function tools discovered through PATH"
+version = "0.7.0"
+description = "Executable typed Python function tools invoked by path or discovered through PATH"
 readme = "README.md"
 authors = [
     { name = "Nima Shoghi", email = "nima@boltz.bio" }

{toolfuncs-0.5.0 → toolfuncs-0.7.0}/src/toolfuncs/__main__.py

@@ -13,6 +13,7 @@ from typing import Any
 
 from pydantic_core import to_jsonable_python
 
+from ._doctor import doctor
 from ._setup import setup
 from ._tools import (
     ALLOW_FLOATING_VCS_SHEBANG,
@@ -28,12 +29,17 @@ from .sdk import _run
 _HELP = f"""\
 Usage:
   toolfuncs --version
+  toolfuncs SOURCE [ARGS...]
+  toolfuncs doctor SOURCE
   toolfuncs list
   toolfuncs setup [--bin-dir DIRECTORY]
 
-A toolfunc is an executable Python script on PATH whose first line is exactly:
+A toolfunc is an executable Python script whose first line is exactly:
   {TOOL_SHEBANG}
 
+Run a known source with `toolfuncs SOURCE [ARGS...]`. Put it on PATH to invoke
+it by filename and make it available to discovery and dynamic Python lookup.
+
 Floating Git revisions require the explicit shebang:
   {ALLOW_FLOATING_VCS_SHEBANG}
 """
@@ -85,6 +91,12 @@ def main(argv: Sequence[str] | None = None) -> int:
         _print_json(asdict(catalog))
         _warn_invalid_tools(catalog.invalid_tools)
         return 0
+    if command == "doctor":
+        if len(tokens) != 1:
+            raise SystemExit("usage: toolfuncs doctor SOURCE")
+        result = doctor(tokens[0])
+        _print_json(asdict(result))
+        return 0 if result.status == "success" else 1
     if command == "setup":
         destination = _parse_setup(tokens)
         _print_json(asdict(setup(destination)))

toolfuncs-0.7.0/src/toolfuncs/_doctor.py

@@ -0,0 +1,181 @@
+"""Validate the runtime interface of one toolfunc source."""
+
+from __future__ import annotations
+
+import inspect
+import io
+import os
+from collections import deque
+from collections.abc import Callable, Iterator
+from contextlib import redirect_stderr, redirect_stdout
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+
+from cyclopts import App
+
+from ._tools import _load_source
+from .sdk import _application
+
+
+@dataclass(frozen=True, slots=True)
+class DoctorSuccess:
+    """Successful validation of one toolfunc source."""
+
+    status: Literal["success"] = field(default="success", init=False)
+    path: Path
+    commands: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class DoctorFailure:
+    """Expected validation failures for one toolfunc source."""
+
+    status: Literal["error"] = field(default="error", init=False)
+    path: Path
+    errors: tuple[str, ...]
+
+
+DoctorResult = DoctorSuccess | DoctorFailure
+
+
+def doctor(source: str | os.PathLike[str]) -> DoctorResult:
+    """Validate one toolfunc source and its registered runtime interface."""
+
+    path = _absolute_path(source)
+    if path.is_file() and not os.access(path, os.X_OK):
+        return DoctorFailure(path=path, errors=("source must be executable",))
+    try:
+        with redirect_stdout(io.StringIO()), redirect_stderr(io.StringIO()):
+            module = _load_source(path)
+    except (Exception, SystemExit) as exc:
+        return DoctorFailure(path=path, errors=(f"could not load source: {_exception_text(exc)}",))
+
+    try:
+        app = _application(module)
+    except Exception as exc:
+        return DoctorFailure(path=path, errors=(f"invalid application: {_exception_text(exc)}",))
+
+    errors: list[str] = []
+    if not inspect.getdoc(module):
+        errors.append("module must have a docstring")
+
+    try:
+        command_apps = tuple(_command_apps(app))
+    except Exception as exc:
+        errors.append(f"could not resolve command graph: {_exception_text(exc)}")
+        return DoctorFailure(path=path, errors=tuple(errors))
+    commands = tuple(
+        _command_name(chain) for chain, command_app in command_apps if command_app.default_command
+    )
+    operations = _unique_operations(command_apps)
+    if not operations:
+        errors.append("application must register at least one operation")
+
+    for command, command_app, operation in operations:
+        _inspect_operation(command, command_app, operation, errors)
+
+    for chain, _ in command_apps:
+        try:
+            with redirect_stdout(io.StringIO()), redirect_stderr(io.StringIO()):
+                app.help_print(chain)
+        except (Exception, SystemExit) as exc:
+            errors.append(
+                f"{_command_name(chain)}: could not generate help: {_exception_text(exc)}"
+            )
+
+    if errors:
+        return DoctorFailure(path=path, errors=tuple(errors))
+    return DoctorSuccess(path=path, commands=commands)
+
+
+def _absolute_path(source: str | os.PathLike[str]) -> Path:
+    raw = os.fspath(source)
+    if isinstance(raw, bytes):
+        raise TypeError("source must be a string path, not bytes")
+    return Path(os.path.abspath(Path(raw).expanduser()))
+
+
+def _command_apps(root: App) -> Iterator[tuple[tuple[str, ...], App]]:
+    pending: deque[tuple[tuple[str, ...], App]] = deque([((), root)])
+    seen: set[int] = set()
+    while pending:
+        chain, app = pending.popleft()
+        if id(app) in seen:
+            continue
+        seen.add(id(app))
+        yield chain, app
+
+        builtins = {*app.help_flags, *app.version_flags}
+        for name, child in app.resolved_commands().items():
+            if name not in builtins:
+                pending.append(((*chain, name), child))
+
+
+def _unique_operations(
+    command_apps: tuple[tuple[tuple[str, ...], App], ...],
+) -> tuple[tuple[str, App, Callable[..., Any]], ...]:
+    operations: list[tuple[str, App, Callable[..., Any]]] = []
+    seen: set[int] = set()
+    for chain, app in command_apps:
+        operation = app.default_command
+        if operation is None or id(operation) in seen:
+            continue
+        seen.add(id(operation))
+        operations.append((_command_name(chain), app, operation))
+    return tuple(operations)
+
+
+def _inspect_operation(
+    command: str,
+    app: App,
+    operation: Callable[..., Any],
+    errors: list[str],
+) -> None:
+    if not inspect.getdoc(operation):
+        errors.append(f"{command}: operation must have a docstring")
+
+    try:
+        signature = inspect.signature(operation)
+    except (TypeError, ValueError) as exc:
+        errors.append(f"{command}: could not inspect signature: {_exception_text(exc)}")
+        return
+
+    for parameter in signature.parameters.values():
+        if parameter.annotation is inspect.Parameter.empty:
+            errors.append(f"{command}: parameter {parameter.name!r} must have a type annotation")
+    if signature.return_annotation is inspect.Signature.empty:
+        errors.append(f"{command}: return value must have a type annotation")
+
+    try:
+        arguments = app.assemble_argument_collection(parse_docstring=True)
+    except Exception as exc:
+        errors.append(f"{command}: could not inspect CLI arguments: {_exception_text(exc)}")
+        return
+
+    for argument in arguments:
+        if argument.show and argument.parse and not argument.parameter.help:
+            errors.append(
+                f"{command}: CLI argument {_argument_name(argument)!r} must have help text"
+            )
+
+
+def _command_name(chain: tuple[str, ...]) -> str:
+    return " ".join(chain) if chain else "<default>"
+
+
+def _argument_name(argument: Any) -> str:
+    names = tuple(argument.names)
+    if names:
+        return names[0]
+    if argument.keys:
+        return ".".join(argument.keys)
+    return argument.field_info.name
+
+
+def _exception_text(exc: BaseException) -> str:
+    message = str(exc)
+    return f"{type(exc).__name__}: {message}" if message else type(exc).__name__
+
+
+__all__ = ["DoctorFailure", "DoctorResult", "DoctorSuccess", "doctor"]

{toolfuncs-0.5.0 → toolfuncs-0.7.0}/src/toolfuncs/_import_path.py

@@ -37,6 +37,7 @@ _PEP723_BLOCK = re.compile(
     r"(?m)^# /// (?P<type>[a-zA-Z0-9-]+)[ \t]*$[\r\n]"
     r"(?P<content>(?:^#(?:| .*)$[\r\n]?)+)^# ///[ \t]*$"
 )
+_EXTENSIONLESS_MODULE_NAME = re.compile(r"[a-z][a-z0-9]*(?:-[a-z0-9]+)*\Z")
 _IMPORT_LOCK = threading.RLock()
 
 
@@ -87,10 +88,11 @@ def import_path(
     """Import one local Python script.
 
     ``source`` may be an ordinary ``.py`` file or an extensionless script. Its
-    filename determines the module name. When the source contains PEP 723
-    metadata, its requirements are installed as one list before import. Pass a
-    custom ``dependency_installer`` to replace the default current-interpreter
-    pip installation.
+    filename determines the module name; valid extensionless kebab-case names
+    map to snake case. When the source contains PEP 723 metadata, its
+    requirements are installed as one list before import. Pass a custom
+    ``dependency_installer`` to replace the default current-interpreter pip
+    installation.
     """
 
     path = _source_path(source)
@@ -152,6 +154,8 @@ def _module_name(source: Path) -> str:
         name = source.stem
     elif not source.suffix:
         name = source.name
+        if _EXTENSIONLESS_MODULE_NAME.fullmatch(name):
+            name = name.replace("-", "_")
     else:
         raise ValueError(f"Python script must be extensionless or end in '.py': {source}")
     if not name.isidentifier() or keyword.iskeyword(name):

toolfuncs-0.7.0/tests/test_doctor.py

@@ -0,0 +1,185 @@
+from __future__ import annotations
+
+import json
+import stat
+from pathlib import Path
+
+from toolfuncs._tools import TOOL_SHEBANG
+
+from .conftest import run_python
+
+
+def _script(cli_name: str, body: str) -> str:
+    return (
+        f"{TOOL_SHEBANG}\n"
+        "# /// script\n"
+        '# requires-python = ">=3.10"\n'
+        "# dependencies = []\n"
+        "# [tool.toolfuncs]\n"
+        '# description = "Doctor fixture."\n'
+        f"# cli_name = {json.dumps(cli_name)}\n"
+        f"# python_name = {json.dumps(cli_name.replace('-', '_'))}\n"
+        "# ///\n"
+        f"{body}"
+    )
+
+
+def _write_executable(path: Path, content: str) -> None:
+    path.write_text(content, encoding="utf-8")
+    path.chmod(path.stat().st_mode | stat.S_IXUSR)
+
+
+def test_doctor_reports_a_valid_runtime_interface(tmp_path: Path) -> None:
+    source = tmp_path / "renderer"
+    _write_executable(
+        source,
+        _script(
+            "renderer",
+            '\n"""Render values."""\n\n'
+            "from pathlib import Path\n\n"
+            "import toolfuncs.sdk as toolsdk\n\n"
+            "app = toolsdk.App()\n\n"
+            "@app.command(alias='show')\n"
+            "def render(value: str, *, output: Path | None = None) -> dict[str, object]:\n"
+            '    """Render one value.\n\n'
+            "    Parameters\n"
+            "    ----------\n"
+            "    value:\n"
+            "        Value to render.\n"
+            "    output:\n"
+            "        Optional output path.\n"
+            '    """\n\n'
+            "    return {'value': value, 'output': output}\n",
+        ),
+    )
+
+    completed = run_python(["-m", "toolfuncs", "doctor", str(source)], cwd=tmp_path)
+
+    assert completed.returncode == 0, completed.stderr
+    assert json.loads(completed.stdout) == {
+        "status": "success",
+        "path": str(source),
+        "commands": ["render"],
+    }
+    assert completed.stderr == ""
+
+
+def test_doctor_aggregates_operation_and_argument_errors(tmp_path: Path) -> None:
+    source = tmp_path / "broken"
+    _write_executable(
+        source,
+        _script(
+            "broken",
+            "\nimport toolfuncs.sdk as toolsdk\n\n"
+            "app = toolsdk.App()\n\n"
+            "@app.command\n"
+            "def first(value, *, quiet: bool):\n"
+            "    return value\n\n"
+            "@app.command\n"
+            "def second(path: str) -> str:\n"
+            '    """Read a path."""\n'
+            "    return path\n",
+        ),
+    )
+
+    completed = run_python(["-m", "toolfuncs", "doctor", str(source)], cwd=tmp_path)
+
+    assert completed.returncode == 1
+    payload = json.loads(completed.stdout)
+    assert payload["status"] == "error"
+    assert payload["path"] == str(source)
+    assert payload["errors"] == [
+        "module must have a docstring",
+        "first: operation must have a docstring",
+        "first: parameter 'value' must have a type annotation",
+        "first: return value must have a type annotation",
+        "first: CLI argument '--value' must have help text",
+        "first: CLI argument '--quiet' must have help text",
+        "second: CLI argument '--path' must have help text",
+    ]
+    assert completed.stderr == ""
+
+
+def test_doctor_accepts_effective_parameter_help_from_cyclopts(tmp_path: Path) -> None:
+    source = tmp_path / "annotated-help"
+    _write_executable(
+        source,
+        _script(
+            "annotated-help",
+            '\n"""Use explicit Cyclopts help."""\n\n'
+            "from typing import Annotated\n\n"
+            "import toolfuncs.sdk as toolsdk\n\n"
+            "app = toolsdk.App()\n\n"
+            "@app.command\n"
+            "def run(value: Annotated[str, toolsdk.Parameter(help='Value to use.')]) -> str:\n"
+            '    """Use one value."""\n'
+            "    return value\n",
+        ),
+    )
+
+    completed = run_python(["-m", "toolfuncs", "doctor", str(source)], cwd=tmp_path)
+
+    assert completed.returncode == 0, completed.stderr
+    assert json.loads(completed.stdout)["status"] == "success"
+
+
+def test_doctor_inspects_nested_commands_once_through_aliases(tmp_path: Path) -> None:
+    source = tmp_path / "nested"
+    _write_executable(
+        source,
+        _script(
+            "nested",
+            '\n"""Run nested commands."""\n\n'
+            "import toolfuncs.sdk as toolsdk\n\n"
+            "app = toolsdk.App()\n"
+            "group = toolsdk.App(name='group')\n"
+            "app.command(group)\n\n"
+            "@group.command(alias='do')\n"
+            "def act(value: str) -> str:\n"
+            '    """Act on one value.\n\n'
+            "    Parameters\n"
+            "    ----------\n"
+            "    value:\n"
+            "        Value to act on.\n"
+            '    """\n\n'
+            "    return value\n",
+        ),
+    )
+
+    completed = run_python(["-m", "toolfuncs", "doctor", str(source)], cwd=tmp_path)
+
+    assert completed.returncode == 0, completed.stderr
+    assert json.loads(completed.stdout)["commands"] == ["group act"]
+
+
+def test_doctor_requires_an_executable_source(tmp_path: Path) -> None:
+    source = tmp_path / "not-executable"
+    source.write_text(_script("not-executable", '\n"""Not executable."""\n'), encoding="utf-8")
+
+    completed = run_python(["-m", "toolfuncs", "doctor", str(source)], cwd=tmp_path)
+
+    assert completed.returncode == 1
+    assert json.loads(completed.stdout)["errors"] == ["source must be executable"]
+
+
+def test_doctor_returns_a_tagged_failure_when_loading_fails(tmp_path: Path) -> None:
+    source = tmp_path / "load-failure"
+    _write_executable(
+        source,
+        _script(
+            "load-failure",
+            '\n"""Fail while loading."""\n\n'
+            'print("import noise")\n'
+            'raise RuntimeError("broken import")\n',
+        ),
+    )
+
+    completed = run_python(["-m", "toolfuncs", "doctor", str(source)], cwd=tmp_path)
+
+    assert completed.returncode == 1
+    assert json.loads(completed.stdout) == {
+        "status": "error",
+        "path": str(source),
+        "errors": ["could not load source: RuntimeError: broken import"],
+    }
+    assert completed.stderr == ""

{toolfuncs-0.5.0 → toolfuncs-0.7.0}/tests/test_import_path.py

@@ -43,6 +43,30 @@ def test_import_path_accepts_extensionless_script(
     assert imported.VALUE == 43
 
 
+def test_import_path_maps_extensionless_kebab_case_to_snake_case(
+    tmp_path: Path,
+    unique_name: str,
+) -> None:
+    source = tmp_path / f"{unique_name}-job"
+    source.write_text("VALUE = 44\n", encoding="utf-8")
+
+    imported = import_path(source)
+
+    assert imported.__name__ == f"{unique_name}_job"
+    assert imported.VALUE == 44
+
+
+def test_import_path_rejects_malformed_extensionless_kebab_case(
+    tmp_path: Path,
+    unique_name: str,
+) -> None:
+    source = tmp_path / f"{unique_name}--job"
+    source.write_text("VALUE = 45\n", encoding="utf-8")
+
+    with pytest.raises(ValueError, match="valid Python module name"):
+        import_path(source)
+
+
 def test_pep723_dependencies_are_passed_as_one_list_before_import(
     tmp_path: Path,
     unique_name: str,

{toolfuncs-0.5.0 → toolfuncs-0.7.0}/tests/test_sdk_cli.py

@@ -34,7 +34,16 @@ def test_cli_prints_installed_version(tmp_path: Path, flag: str) -> None:
     completed = run_python(["-m", "toolfuncs", flag], cwd=tmp_path)
 
     assert completed.returncode == 0
-    assert completed.stdout == "0.5.0\n"
+    assert completed.stdout == "0.7.0\n"
+    assert completed.stderr == ""
+
+
+def test_cli_help_advertises_explicit_source_execution(tmp_path: Path) -> None:
+    completed = run_python(["-m", "toolfuncs", "--help"], cwd=tmp_path)
+
+    assert completed.returncode == 0
+    assert "toolfuncs SOURCE [ARGS...]" in completed.stdout
+    assert "Run a known source" in completed.stdout
     assert completed.stderr == ""
 
 
@@ -106,6 +115,31 @@ def test_runtime_requires_a_module_level_app(tmp_path: Path) -> None:
     assert "must define 'app'" in completed.stderr
 
 
+def test_explicit_source_runs_without_being_on_path(tmp_path: Path) -> None:
+    source = tmp_path / "local-tool"
+    _write_executable(
+        source,
+        _script(
+            "local-tool",
+            "Local tool",
+            "import toolfuncs.sdk as toolsdk\n\n"
+            "app = toolsdk.App()\n\n"
+            "@app.command\n"
+            "def ping() -> str:\n"
+            "    return 'pong'\n",
+        ),
+    )
+
+    completed = run_python(
+        ["-m", "toolfuncs", str(source), "ping"],
+        cwd=tmp_path,
+        env={"PATH": os.defpath},
+    )
+
+    assert completed.returncode == 0, completed.stderr
+    assert json.loads(completed.stdout) == "pong"
+
+
 @pytest.mark.parametrize("prepared", [False, True])
 @pytest.mark.parametrize(
     ("app_definition", "expected_name"),

{toolfuncs-0.5.0 → toolfuncs-0.7.0}/uv.lock

@@ -601,7 +601,7 @@ wheels = [
 
 [[package]]
 name = "toolfuncs"
-version = "0.5.0"
+version = "0.7.0"
 source = { editable = "." }
 dependencies = [
     { name = "cyclopts" },