toolfuncs 0.7.0__tar.gz → 0.8.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: toolfuncs
-Version: 0.7.0
+Version: 0.8.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
@@ -139,6 +139,27 @@ A toolfunc source must:
 
 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.
 
+Descriptions are static by default. A tool whose available domain surface changes at runtime may opt into a last-known catalog description with `dynamic = true`:
+
+```toml
+[tool.toolfuncs]
+description = "Use connected services."
+dynamic = true
+cli_name = "connected-services"
+python_name = "connected_services"
+```
+
+After refreshing its own state, the tool publishes one current line without changing its source:
+
+```python
+toolsdk.publish_description(
+    "connected-services",
+    "Use connected services: Gmail, Google Drive, and Slack.",
+)
+```
+
+Toolfuncs stores the line at `${XDG_STATE_HOME:-~/.local/state}/toolfuncs/descriptions/connected-services`. Missing or invalid state uses the required static description. The CLI and Python identities always remain static.
+
 Git requirements must use a full 40- or 64-hex commit object ID. Branches such as `@main`, tags, abbreviated hashes, and omitted revisions fail before uv resolves them. A tool that deliberately accepts floating-ref refresh and concurrency costs must say so in its source:
 
 ```python
@@ -177,7 +198,7 @@ Toolfuncs reads the current process's `PATH` from left to right. It considers on
 
 The first executable filename claims a command name even when it is not a toolfunc. Therefore an ordinary executable earlier on `PATH` hides a same-named toolfunc later on `PATH`, matching what the shell actually executes. Repeated directories are scanned once, inaccessible directories are skipped, and discovered records are sorted by CLI name.
 
-`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.
+`toolfuncs list` returns one JSON object with `tools` and `invalid_tools`. Valid records contain `cli_name`, `python_name`, `path`, and the effective `description`. For `dynamic = true`, discovery reads the optional one-line state file and otherwise uses the static 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, executes its source, or accesses the network.
 
 ## Validate a tool while authoring
 
@@ -251,7 +272,7 @@ Available toolfuncs:
   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.
+The hook reads executable headers and PEP 723 metadata, plus the optional one-line state file for tools declaring `dynamic = true`. 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, resolve their dependencies, execute them, or access the network. The hook itself is harness infrastructure, not a toolfunc, and therefore does not carry the toolfuncs shebang or appear in the catalog.
 
 ## Development
 

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

@@ -121,6 +121,27 @@ A toolfunc source must:
 
 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.
 
+Descriptions are static by default. A tool whose available domain surface changes at runtime may opt into a last-known catalog description with `dynamic = true`:
+
+```toml
+[tool.toolfuncs]
+description = "Use connected services."
+dynamic = true
+cli_name = "connected-services"
+python_name = "connected_services"
+```
+
+After refreshing its own state, the tool publishes one current line without changing its source:
+
+```python
+toolsdk.publish_description(
+    "connected-services",
+    "Use connected services: Gmail, Google Drive, and Slack.",
+)
+```
+
+Toolfuncs stores the line at `${XDG_STATE_HOME:-~/.local/state}/toolfuncs/descriptions/connected-services`. Missing or invalid state uses the required static description. The CLI and Python identities always remain static.
+
 Git requirements must use a full 40- or 64-hex commit object ID. Branches such as `@main`, tags, abbreviated hashes, and omitted revisions fail before uv resolves them. A tool that deliberately accepts floating-ref refresh and concurrency costs must say so in its source:
 
 ```python
@@ -159,7 +180,7 @@ Toolfuncs reads the current process's `PATH` from left to right. It considers on
 
 The first executable filename claims a command name even when it is not a toolfunc. Therefore an ordinary executable earlier on `PATH` hides a same-named toolfunc later on `PATH`, matching what the shell actually executes. Repeated directories are scanned once, inaccessible directories are skipped, and discovered records are sorted by CLI name.
 
-`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.
+`toolfuncs list` returns one JSON object with `tools` and `invalid_tools`. Valid records contain `cli_name`, `python_name`, `path`, and the effective `description`. For `dynamic = true`, discovery reads the optional one-line state file and otherwise uses the static 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, executes its source, or accesses the network.
 
 ## Validate a tool while authoring
 
@@ -233,7 +254,7 @@ Available toolfuncs:
   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.
+The hook reads executable headers and PEP 723 metadata, plus the optional one-line state file for tools declaring `dynamic = true`. 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, resolve their dependencies, execute them, or access the network. The hook itself is harness infrastructure, not a toolfunc, and therefore does not carry the toolfuncs shebang or appear in the catalog.
 
 ## Development
 

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

@@ -1,4 +1,4 @@
-# toolfuncs 0.7 contract
+# toolfuncs 0.8 contract
 
 ## Purpose
 
@@ -21,10 +21,14 @@ 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.
 
+`dynamic` is an optional boolean and defaults to `false`. When it is `true`, catalog discovery may replace the static description with the valid one-line UTF-8 contents of `${XDG_STATE_HOME:-~/.local/state}/toolfuncs/descriptions/<cli_name>`. The static description remains required and is the fallback for missing, unreadable, undecodable, empty, or multiline state. The flag does not make either identity dynamic and does not describe the command graph.
+
 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.
 
+`toolsdk.publish_description(cli_name, description)` validates the ordinary CLI-name and one-line description rules and atomically replaces that CLI identity's dynamic description file. It returns the written path. Published descriptions are last-known state with no framework expiry; a tool overwrites the line when its domain inventory changes.
+
 ## Python interface
 
 The standard Python interface is:
@@ -56,7 +60,7 @@ Discovery reads the current `PATH` from left to right. The first executable file
 
 An exact-shebang source opts into validation. Discovery records an invalid opted-in source instead of raising and suppressing unrelated tools. The internal catalog contains sorted valid `Tool(cli_name, python_name, path, description)` records and sorted `InvalidTool(path, error)` records.
 
-`toolfuncs list` emits one JSON object with `tools` and `invalid_tools`, prints a concise warning with invalid paths and errors to stderr, and exits successfully even when invalid entries exist. The startup hook advertises valid tools and reports invalid tools separately. Discovery and listing never import source, prepare dependencies, or execute tool code.
+`toolfuncs list` emits one JSON object with `tools` and `invalid_tools`, prints a concise warning with invalid paths and errors to stderr, and exits successfully even when invalid entries exist. The startup hook advertises valid tools and reports invalid tools separately. For a tool declaring `dynamic = true`, the record's description is the valid published line when present and the static description otherwise. Discovery and listing never import source, prepare dependencies, execute tool code, or access the network.
 
 Direct invocation or Python lookup of an invalid tool fails with its validation error.
 
@@ -84,4 +88,4 @@ The public management commands are `toolfuncs doctor SOURCE`, `toolfuncs list`,
 
 ## Compatibility
 
-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.
+Version 0.8 adds explicit opt-in last-known dynamic descriptions through `[tool.toolfuncs].dynamic` and `toolsdk.publish_description`. It retains the 0.7 identity, static-default discovery, runtime, and authoring contracts. Existing tools need no changes and incur no dynamic-description lookup unless they opt in.

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

@@ -1,6 +1,6 @@
 [project]
 name = "toolfuncs"
-version = "0.7.0"
+version = "0.8.0"
 description = "Executable typed Python function tools invoked by path or discovered through PATH"
 readme = "README.md"
 authors = [

toolfuncs-0.8.0/src/toolfuncs/_descriptions.py

@@ -0,0 +1,52 @@
+"""Persistent one-line catalog descriptions for explicitly dynamic tools."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+
+def _normalize_description(value: str) -> str | None:
+    description = value.strip()
+    if not description or len(description.splitlines()) != 1:
+        return None
+    return description
+
+
+def _description_path(cli_name: str) -> Path:
+    if raw_state_home := os.environ.get("XDG_STATE_HOME"):
+        state_home = Path(raw_state_home).expanduser()
+    else:
+        state_home = Path.home() / ".local" / "state"
+    return state_home / "toolfuncs" / "descriptions" / cli_name
+
+
+def _published_description(cli_name: str) -> str | None:
+    try:
+        value = _description_path(cli_name).read_text(encoding="utf-8")
+    except (OSError, UnicodeError):
+        return None
+    return _normalize_description(value)
+
+
+def _publish_description(cli_name: str, description: str) -> Path:
+    normalized = _normalize_description(description)
+    if normalized is None:
+        raise ValueError("description must contain exactly one nonempty line")
+
+    target = _description_path(cli_name)
+    target.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    descriptor, raw_temp = tempfile.mkstemp(prefix=f".{cli_name}.", dir=target.parent)
+    temp = Path(raw_temp)
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            handle.write(f"{normalized}\n")
+        temp.replace(target)
+    except BaseException:
+        temp.unlink(missing_ok=True)
+        raise
+    return target
+
+
+__all__ = []

{toolfuncs-0.7.0 → toolfuncs-0.8.0}/src/toolfuncs/_tools.py

@@ -25,6 +25,7 @@ if sys.version_info >= (3, 11):
 else:
     import tomli as tomllib
 
+from ._descriptions import _normalize_description, _published_description
 from ._errors import DependencyError, InvalidToolError, ToolConflictError, ToolNotFoundError
 
 TOOL_SHEBANG = "#!/usr/bin/env toolfuncs"
@@ -74,6 +75,7 @@ class _Metadata:
     description: str
     cli_name: str
     python_name: str
+    dynamic: bool
 
 
 @dataclass(frozen=True, slots=True)
@@ -237,7 +239,8 @@ def _inspect(source: Path, *, cli_name: str) -> Tool:
         cli_name=cli_name,
         python_name=python_name,
         path=source,
-        description=metadata.description,
+        description=(_published_description(cli_name) if metadata.dynamic else None)
+        or metadata.description,
     )
 
 
@@ -293,14 +296,14 @@ def _metadata(source: Path) -> _Metadata:
     raw_config = raw_tool.get("toolfuncs") if isinstance(raw_tool, dict) else None
     if not isinstance(raw_config, dict):
         raise InvalidToolError(f"{source}: PEP 723 metadata must define [tool.toolfuncs]")
-    if unknown := sorted(set(raw_config) - {"cli_name", "description", "python_name"}):
+    if unknown := sorted(set(raw_config) - {"cli_name", "description", "dynamic", "python_name"}):
         rendered = ", ".join(repr(field) for field in unknown)
         raise InvalidToolError(f"{source}: unknown [tool.toolfuncs] fields: {rendered}")
     raw_description = raw_config.get("description")
     if not isinstance(raw_description, str) or not raw_description.strip():
         raise InvalidToolError(f"{source}: [tool.toolfuncs].description must be a nonempty string")
-    description = raw_description.strip()
-    if len(description.splitlines()) != 1:
+    description = _normalize_description(raw_description)
+    if description is None:
         raise InvalidToolError(
             f"{source}: [tool.toolfuncs].description must contain exactly one line"
         )
@@ -312,12 +315,16 @@ def _metadata(source: Path) -> _Metadata:
     if not isinstance(raw_python_name, str) or not raw_python_name.strip():
         raise InvalidToolError(f"{source}: [tool.toolfuncs].python_name must be a nonempty string")
     python_name = raw_python_name
+    dynamic = raw_config.get("dynamic", False)
+    if not isinstance(dynamic, bool):
+        raise InvalidToolError(f"{source}: [tool.toolfuncs].dynamic must be a boolean")
     return _Metadata(
         tuple(dependencies),
         requires_python,
         description,
         cli_name,
         python_name,
+        dynamic,
     )
 
 

{toolfuncs-0.7.0 → toolfuncs-0.8.0}/src/toolfuncs/sdk.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import json
 from collections.abc import Iterable
 from functools import partial
+from pathlib import Path
 from types import ModuleType
 from typing import Any
 
@@ -22,7 +23,9 @@ from cyclopts import (
 )
 from pydantic_core import to_jsonable_python
 
+from ._descriptions import _publish_description
 from ._errors import ToolDefinitionError
+from ._tools import _python_name_for_cli_name
 
 
 def json_result_action() -> ResultAction:
@@ -35,6 +38,13 @@ def json_result_action() -> ResultAction:
     ]
 
 
+def publish_description(cli_name: str, description: str) -> Path:
+    """Publish one tool's current one-line description for catalog discovery."""
+
+    _python_name_for_cli_name(cli_name)
+    return _publish_description(cli_name, description)
+
+
 class App(CycloptsApp):
     """Cyclopts App with strict JSON output as its default result action.
 
@@ -72,6 +82,7 @@ __all__ = [
     "ResultAction",
     "Token",
     "json_result_action",
+    "publish_description",
     "to_jsonable_python",
     "types",
     "validators",

{toolfuncs-0.7.0 → toolfuncs-0.8.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.7.0\n"
+    assert completed.stdout == "0.8.0\n"
     assert completed.stderr == ""
 
 
@@ -52,7 +52,12 @@ def _avoid_installing_live_agent_hooks(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.setattr(setup_impl, "_install_hooks", lambda _hook_wrapper: None)
 
 
-def _script(cli_name: str, description: str, body: str = "") -> str:
+@pytest.fixture(autouse=True)
+def _isolated_state_home(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("XDG_STATE_HOME", str(tmp_path / "state"))
+
+
+def _script(cli_name: str, description: str, body: str = "", *, dynamic: bool = False) -> str:
     return (
         f"{TOOL_SHEBANG}\n"
         "# /// script\n"
@@ -60,6 +65,7 @@ def _script(cli_name: str, description: str, body: str = "") -> str:
         "# dependencies = []\n"
         "# [tool.toolfuncs]\n"
         f"# description = {json.dumps(description)}\n"
+        f"# dynamic = {str(dynamic).lower()}\n"
         f"# cli_name = {json.dumps(cli_name)}\n"
         f"# python_name = {json.dumps(cli_name.replace('-', '_'))}\n"
         "# ///\n"
@@ -348,6 +354,32 @@ def test_listing_does_not_import_source(tmp_path: Path) -> None:
     }
 
 
+def test_listing_uses_published_description_without_importing_source(tmp_path: Path) -> None:
+    bin_dir = tmp_path / "bin"
+    bin_dir.mkdir()
+    _write_executable(
+        bin_dir / "dynamic-tool",
+        _script(
+            "dynamic-tool",
+            "Static fallback",
+            "raise RuntimeError('source was imported')\n",
+            dynamic=True,
+        ),
+    )
+    toolsdk.publish_description("dynamic-tool", "Current apps: Gmail and Slack.")
+
+    completed = run_python(
+        ["-m", "toolfuncs", "list"],
+        cwd=tmp_path,
+        env={"PATH": str(bin_dir), "XDG_STATE_HOME": str(tmp_path / "state")},
+    )
+
+    assert completed.returncode == 0, completed.stderr
+    assert json.loads(completed.stdout)["tools"][0]["description"] == (
+        "Current apps: Gmail and Slack."
+    )
+
+
 def test_listing_warns_about_invalid_tools_without_hiding_valid_tools(
     tmp_path: Path,
 ) -> None:

{toolfuncs-0.7.0 → toolfuncs-0.8.0}/tests/test_tools.py

@@ -20,6 +20,7 @@ from toolfuncs._tools import (
     _discover,
     _load_python_name,
 )
+from toolfuncs.sdk import publish_description
 
 from .conftest import run_python
 
@@ -34,6 +35,7 @@ def _script(
     shebang: str = TOOL_SHEBANG,
     declared_cli_name: str | None = None,
     declared_python_name: str | None = None,
+    dynamic: bool = False,
 ) -> str:
     return (
         f"{shebang}\n"
@@ -42,6 +44,7 @@ def _script(
         f"# dependencies = {json.dumps(dependencies or [])}\n"
         "# [tool.toolfuncs]\n"
         f"# description = {json.dumps(description)}\n"
+        f"# dynamic = {str(dynamic).lower()}\n"
         f"# cli_name = {json.dumps(declared_cli_name or cli_name)}\n"
         f"# python_name = "
         f"{json.dumps(declared_python_name or cli_name.replace('-', '_'))}\n"
@@ -59,6 +62,11 @@ def _path(*directories: Path) -> str:
     return os.pathsep.join(str(directory) for directory in directories)
 
 
+@pytest.fixture(autouse=True)
+def _isolated_state_home(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("XDG_STATE_HOME", str(tmp_path / "state"))
+
+
 def test_path_order_matches_shell_precedence(tmp_path: Path) -> None:
     first = tmp_path / "first"
     second = tmp_path / "second"
@@ -75,6 +83,58 @@ def test_path_order_matches_shell_precedence(tmp_path: Path) -> None:
     assert tools["second-only"].path == second / "second-only"
 
 
+def test_dynamic_description_is_an_explicit_last_known_override(tmp_path: Path) -> None:
+    bin_dir = tmp_path / "bin"
+    bin_dir.mkdir()
+    _write_tool(bin_dir / "dynamic-tool", _script("dynamic-tool", "Static", dynamic=True))
+    _write_tool(bin_dir / "static-tool", _script("static-tool", "Static"))
+
+    dynamic_path = publish_description("dynamic-tool", "Current apps: Gmail and Slack.")
+    static_path = publish_description("static-tool", "Must not be used.")
+    tools = {tool.cli_name: tool for tool in _discover(path=str(bin_dir)).tools}
+
+    assert dynamic_path.read_text(encoding="utf-8") == "Current apps: Gmail and Slack.\n"
+    assert static_path.read_text(encoding="utf-8") == "Must not be used.\n"
+    assert tools["dynamic-tool"].description == "Current apps: Gmail and Slack."
+    assert tools["static-tool"].description == "Static"
+
+
+@pytest.mark.parametrize("published", ["", "first\nsecond\n", "invalid-utf8"])
+def test_invalid_dynamic_description_state_falls_back_to_static(
+    tmp_path: Path, published: str
+) -> None:
+    bin_dir = tmp_path / "bin"
+    bin_dir.mkdir()
+    _write_tool(bin_dir / "dynamic-tool", _script("dynamic-tool", "Static", dynamic=True))
+    description_path = tmp_path / "state" / "toolfuncs" / "descriptions" / "dynamic-tool"
+    description_path.parent.mkdir(parents=True)
+    if published == "invalid-utf8":
+        description_path.write_bytes(b"\xff")
+    else:
+        description_path.write_text(published, encoding="utf-8")
+
+    assert _discover(path=str(bin_dir)).tools[0].description == "Static"
+
+
+def test_publish_description_validates_name_and_one_line_text() -> None:
+    with pytest.raises(InvalidToolError, match="lowercase ASCII kebab-case"):
+        publish_description("not_valid", "Description")
+    with pytest.raises(ValueError, match="exactly one nonempty line"):
+        publish_description("valid-tool", "first\nsecond")
+
+
+def test_dynamic_metadata_must_be_boolean(tmp_path: Path) -> None:
+    bin_dir = tmp_path / "bin"
+    bin_dir.mkdir()
+    source = _script("dynamic-tool", "Static").replace("# dynamic = false", '# dynamic = "yes"')
+    _write_tool(bin_dir / "dynamic-tool", source)
+
+    catalog = _discover(path=str(bin_dir))
+
+    assert len(catalog.invalid_tools) == 1
+    assert "dynamic must be a boolean" in catalog.invalid_tools[0].error
+
+
 def test_ordinary_executable_shadows_later_toolfunc(tmp_path: Path) -> None:
     first = tmp_path / "first"
     second = tmp_path / "second"

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

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