toolfuncs 0.4.0__tar.gz → 0.6.0__tar.gz

{toolfuncs-0.4.0 → toolfuncs-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: toolfuncs
-Version: 0.4.0
+Version: 0.6.0
 Summary: Executable typed Python function tools discovered through PATH
 Project-URL: Repository, https://github.com/nimashoghi/toolfuncs
 Project-URL: Issues, https://github.com/nimashoghi/toolfuncs/issues
@@ -45,6 +45,14 @@ 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)
 ```
 
@@ -109,7 +117,8 @@ A discoverable toolfunc must:
 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 +162,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,6 +215,7 @@ Setup does not discover, copy, register, link, synchronize, or remove tools. The
 ## Management commands
 
 ```console
+toolfuncs doctor SOURCE
 toolfuncs list
 toolfuncs setup [--bin-dir DIRECTORY]
 ```
@@ -196,7 +230,7 @@ The installed hook runs at initial session start and at the session-start event
 Available toolfuncs:
 - `weather_report`: Read current weather conditions.
   CLI: `weather-report --help`
-  Python: `import toolfuncs as tools; tools.weather_report`
+  Python: `import toolfuncs as tools; help(tools.weather_report)`
 ```
 
 The hook reads only executable headers and PEP 723 metadata. It advertises valid tools and lists invalid tool paths and errors separately; one invalid tool does not suppress the others. It does not import tools or resolve their dependencies. The hook itself is harness infrastructure, not a toolfunc, and therefore does not carry the toolfuncs shebang or appear in the catalog.

{toolfuncs-0.4.0 → toolfuncs-0.6.0}/README.md

@@ -27,6 +27,14 @@ 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)
 ```
 
@@ -91,7 +99,8 @@ A discoverable toolfunc must:
 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 +144,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,6 +197,7 @@ Setup does not discover, copy, register, link, synchronize, or remove tools. The
 ## Management commands
 
 ```console
+toolfuncs doctor SOURCE
 toolfuncs list
 toolfuncs setup [--bin-dir DIRECTORY]
 ```
@@ -178,7 +212,7 @@ The installed hook runs at initial session start and at the session-start event
 Available toolfuncs:
 - `weather_report`: Read current weather conditions.
   CLI: `weather-report --help`
-  Python: `import toolfuncs as tools; tools.weather_report`
+  Python: `import toolfuncs as tools; help(tools.weather_report)`
 ```
 
 The hook reads only executable headers and PEP 723 metadata. It advertises valid tools and lists invalid tool paths and errors separately; one invalid tool does not suppress the others. It does not import tools or resolve their dependencies. The hook itself is harness infrastructure, not a toolfunc, and therefore does not carry the toolfuncs shebang or appear in the catalog.

{toolfuncs-0.4.0 → toolfuncs-0.6.0}/docs/contract.md

@@ -1,4 +1,4 @@
-# toolfuncs 0.4 contract
+# toolfuncs 0.6 contract
 
 ## Purpose
 
@@ -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.
 
@@ -60,6 +60,12 @@ 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.
@@ -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]`. Tools are invoked directly by their own CLI names. There is no universal name dispatcher, `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.6 retains the 0.4 runtime and identity contract and adds the authoring doctor. 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.4.0 → toolfuncs-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "toolfuncs"
-version = "0.4.0"
+version = "0.6.0"
 description = "Executable typed Python function tools discovered through PATH"
 readme = "README.md"
 authors = [

{toolfuncs-0.4.0 → toolfuncs-0.6.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,6 +29,7 @@ from .sdk import _run
 _HELP = f"""\
 Usage:
   toolfuncs --version
+  toolfuncs doctor SOURCE
   toolfuncs list
   toolfuncs setup [--bin-dir DIRECTORY]
 
@@ -85,6 +87,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.6.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.4.0 → toolfuncs-0.6.0}/src/toolfuncs/agent_hooks.py

@@ -25,7 +25,7 @@ def catalog_context(catalog: Catalog) -> str | None:
             (
                 f"- `{tool.python_name}`: {tool.description}",
                 f"  CLI: `{tool.cli_name} --help`",
-                f"  Python: `import toolfuncs as tools; tools.{tool.python_name}`",
+                f"  Python: `import toolfuncs as tools; help(tools.{tool.python_name})`",
             )
         )
     if catalog.invalid_tools:

{toolfuncs-0.4.0 → toolfuncs-0.6.0}/tests/test_agent_hooks.py

@@ -52,10 +52,10 @@ def test_catalog_context_shows_cli_and_python_usage() -> None:
         "Available toolfuncs:\n"
         "- `session_history`: Search prior sessions.\n"
         "  CLI: `session-history --help`\n"
-        "  Python: `import toolfuncs as tools; tools.session_history`\n"
+        "  Python: `import toolfuncs as tools; help(tools.session_history)`\n"
         "- `screenpipe`: Search recorded activity.\n"
         "  CLI: `screenpipe --help`\n"
-        "  Python: `import toolfuncs as tools; tools.screenpipe`\n"
+        "  Python: `import toolfuncs as tools; help(tools.screenpipe)`\n"
         "</toolfuncs>"
     )
 
@@ -107,7 +107,7 @@ def test_session_start_handler_advertises_startup_and_post_compaction(
     assert isinstance(result, shared.outputs.AddContext)
     assert "`weather`" in result.text
     assert "CLI: `weather --help`" in result.text
-    assert "Python: `import toolfuncs as tools; tools.weather`" in result.text
+    assert "Python: `import toolfuncs as tools; help(tools.weather)`" in result.text
 
 
 def test_session_start_handler_emits_nothing_for_an_empty_path(

toolfuncs-0.6.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.4.0 → toolfuncs-0.6.0}/tests/test_sdk_cli.py

@@ -34,7 +34,7 @@ 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.4.0\n"
+    assert completed.stdout == "0.6.0\n"
     assert completed.stderr == ""
 
 

{toolfuncs-0.4.0 → toolfuncs-0.6.0}/uv.lock

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