wexample-cli 2.1.6__tar.gz → 2.2.0__tar.gz

{wexample_cli-2.1.6 → wexample_cli-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: wexample-cli
-Version: 2.1.6
+Version: 2.2.0
 Summary: Supplies command decorators, typed options, and a composable middleware pipeline for kernels built on wexample-app
 Author-Email: weeger <contact@wexample.com>
 License: MIT
@@ -10,8 +10,8 @@ Classifier: Operating System :: OS Independent
 Project-URL: homepage, https://github.com/wexample/python-cli
 Requires-Python: >=3.10
 Requires-Dist: attrs>=23.1.0
-Requires-Dist: wexample-app>=19.3.0
-Requires-Dist: wexample-helpers>=20.3.0
+Requires-Dist: wexample-app>=19.4.0
+Requires-Dist: wexample-helpers>=20.5.0
 Requires-Dist: wexample-prompt>=16.0.0
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
@@ -20,7 +20,7 @@ Description-Content-Type: text/markdown
 
 # cli
 
-Version: 2.1.6
+Version: 2.2.0
 
 `wexample-cli` supplies the decorator layer — `@command`, `@option`, and `@middleware` — that turns plain Python methods into typed, discoverable commands for kernels built on `wexample-app`. Options are declared with Python types, short names, defaults, required flags, and per-value validators; a composable middleware pipeline can fan a single invocation across multiple execution contexts, run them in parallel, and abort on the first failure. It is aimed at Python developers building or extending a `wexample-app` kernel with new CLI commands.
 
@@ -230,13 +230,11 @@ This package is part of the Wexample Suite — a collection of high-quality, mod
 
 The suite includes packages for configuration management, file handling, prompts, and more. Each package can be used independently or as part of the integrated suite.
 
-Visit the [Wexample Suite documentation](https://docs.wexample.com) for the complete package ecosystem.
-
 ## Dependencies
 
 - attrs: >=23.1.0
-- wexample-app: >=19.3.0
-- wexample-helpers: >=20.3.0
+- wexample-app: >=19.4.0
+- wexample-helpers: >=20.5.0
 - wexample-prompt: >=16.0.0
 
 ## Versioning & Compatibility Policy
@@ -263,6 +261,8 @@ This packages suite embodies this spirit. Trusted by professionals and enthusias
 
 Wexample cultivates a culture of mastery. Each package, each contribution carries the mark of a community that values precision, ethics, and innovation — a community proud to shape the future of digital craftsmanship.
 
+Built and maintained by [Romain Weeger](https://weeger.io).
+
 ## Known Limitations & Roadmap
 
 Current limitations and planned features are tracked in the GitHub issues.
@@ -282,7 +282,6 @@ See the [project roadmap](https://github.com/wexample/python-cli/issues) for upc
 ## Useful Links
 
 - **Homepage**: https://github.com/wexample/python-cli
-- **Documentation**: [docs.wexample.com](https://docs.wexample.com)
 - **Issue Tracker**: https://github.com/wexample/python-cli/issues
 - **Discussions**: https://github.com/wexample/python-cli/discussions
 - **PyPI**: [pypi.org/project/wexample-cli](https://pypi.org/project/wexample-cli/)

{wexample_cli-2.1.6 → wexample_cli-2.2.0}/README.md

@@ -1,6 +1,6 @@
 # cli
 
-Version: 2.1.6
+Version: 2.2.0
 
 `wexample-cli` supplies the decorator layer — `@command`, `@option`, and `@middleware` — that turns plain Python methods into typed, discoverable commands for kernels built on `wexample-app`. Options are declared with Python types, short names, defaults, required flags, and per-value validators; a composable middleware pipeline can fan a single invocation across multiple execution contexts, run them in parallel, and abort on the first failure. It is aimed at Python developers building or extending a `wexample-app` kernel with new CLI commands.
 
@@ -210,13 +210,11 @@ This package is part of the Wexample Suite — a collection of high-quality, mod
 
 The suite includes packages for configuration management, file handling, prompts, and more. Each package can be used independently or as part of the integrated suite.
 
-Visit the [Wexample Suite documentation](https://docs.wexample.com) for the complete package ecosystem.
-
 ## Dependencies
 
 - attrs: >=23.1.0
-- wexample-app: >=19.3.0
-- wexample-helpers: >=20.3.0
+- wexample-app: >=19.4.0
+- wexample-helpers: >=20.5.0
 - wexample-prompt: >=16.0.0
 
 ## Versioning & Compatibility Policy
@@ -243,6 +241,8 @@ This packages suite embodies this spirit. Trusted by professionals and enthusias
 
 Wexample cultivates a culture of mastery. Each package, each contribution carries the mark of a community that values precision, ethics, and innovation — a community proud to shape the future of digital craftsmanship.
 
+Built and maintained by [Romain Weeger](https://weeger.io).
+
 ## Known Limitations & Roadmap
 
 Current limitations and planned features are tracked in the GitHub issues.
@@ -262,7 +262,6 @@ See the [project roadmap](https://github.com/wexample/python-cli/issues) for upc
 ## Useful Links
 
 - **Homepage**: https://github.com/wexample/python-cli
-- **Documentation**: [docs.wexample.com](https://docs.wexample.com)
 - **Issue Tracker**: https://github.com/wexample/python-cli/issues
 - **Discussions**: https://github.com/wexample/python-cli/discussions
 - **PyPI**: [pypi.org/project/wexample-cli](https://pypi.org/project/wexample-cli/)

{wexample_cli-2.1.6 → wexample_cli-2.2.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "pdm.backend"
 
 [project]
 name = "wexample-cli"
-version = "2.1.6"
+version = "2.2.0"
 description = "Supplies command decorators, typed options, and a composable middleware pipeline for kernels built on wexample-app"
 authors = [
     { name = "weeger", email = "contact@wexample.com" },
@@ -19,8 +19,8 @@ classifiers = [
 ]
 dependencies = [
     "attrs>=23.1.0",
-    "wexample-app>=19.3.0",
-    "wexample-helpers>=20.3.0",
+    "wexample-app>=19.4.0",
+    "wexample-helpers>=20.5.0",
     "wexample-prompt>=16.0.0",
 ]
 

{wexample_cli-2.1.6 → wexample_cli-2.2.0}/src/wexample_cli/const/tags.py

@@ -30,6 +30,10 @@ class AudienceTag:
     """Who can safely invoke the command."""
 
     AGENT_SAFE = "audience:agent-safe"
+    # Callable over HTTP by the server a board runs commands through: what a
+    # board asks wex to do — write a record, a file — is a command that also
+    # runs from a terminal, and this says which ones it may call.
+    API = "audience:api"
     REQUIRES_CONFIRMATION = "audience:requires-confirmation"
     DANGEROUS = "audience:dangerous"
     HUMAN_ONLY = "audience:human-only"

wexample_cli-2.2.0/src/wexample_cli/decorator/api_command.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from wexample_helpers.const.types import AnyCallable
+
+    from wexample_cli.common.command_method_wrapper import CommandMethodWrapper
+
+OPTION_NAME_COMMIT: str = "commit"
+OPTION_NAME_COMMIT_AUTHOR: str = "commit_author"
+
+# Where a command marked for the API says which paths it wrote: a list of
+# absolute paths in its response's content, committed with `--commit`.
+CONTENT_KEY_WRITTEN: str = "written"
+# Where the commits made of them are said back, by repository.
+CONTENT_KEY_COMMITS: str = "commits"
+
+COMMIT_MESSAGE: str = "Autocommit"
+
+
+def api_command(commit_subject: str | None = None) -> AnyCallable:
+    """Mark a command as callable over HTTP by a board.
+
+    Tags it `AudienceTag.API`, which the command registry already carries, so
+    the server that runs commands for a board finds out which ones it may run
+    without any registry field of its own. The command stays an ordinary one:
+    what a board asks for over HTTP runs the same from a terminal.
+
+    Adds `--commit` and `--commit-author`, the same for every such command:
+    the paths it says it wrote (`written` in its content) are committed once
+    it is done, those and nothing else, signed by the author given. A board
+    switches them on when its auto commit is; the command itself knows
+    nothing of git.
+
+    `commit_subject` says what kind of write the command makes, for the commit
+    message (`Autocommit: file edition`).
+
+    Usage::
+
+        @api_command(commit_subject="file edition")
+        @command(type=COMMAND_TYPE_ADDON)
+        def my__group__command(context): ...
+    """
+
+    def decorator(command_wrapper: CommandMethodWrapper) -> CommandMethodWrapper:
+        from functools import partial
+
+        from wexample_app.command.option import Option
+
+        from wexample_cli.const.tags import AudienceTag
+
+        if AudienceTag.API not in command_wrapper.tags:
+            command_wrapper.tags.append(AudienceTag.API)
+
+        command_wrapper.set_option(
+            Option(
+                name=OPTION_NAME_COMMIT,
+                type=bool,
+                description="Commit the paths the command wrote, and nothing else.",
+                default=False,
+                is_flag=True,
+            )
+        )
+        command_wrapper.set_option(
+            Option(
+                name=OPTION_NAME_COMMIT_AUTHOR,
+                type=str,
+                description="`Name <email>` the commit is signed by; git's own when left out.",
+                default=None,
+                required=False,
+            )
+        )
+        command_wrapper.register_pipeline_wrapper(
+            partial(_commit_wrapper, commit_subject=commit_subject)
+        )
+
+        return command_wrapper
+
+    return decorator
+
+
+def autocommit_message(subject: str | None = None) -> str:
+    """`Autocommit: <subject>`, what a commit nobody wrote the message of says it is.
+
+    The subject names the kind of write — `file edition`, `agent creation` — so a
+    history made of them still tells one origin from another; `Autocommit` alone when
+    there is none to give.
+    """
+    return f"{COMMIT_MESSAGE}: {subject}" if subject else COMMIT_MESSAGE
+
+
+def _commit(written: list[str], message: str, author: str | None) -> dict[str, Any]:
+    """Each repository's share of what was written, committed on its own."""
+    from pathlib import Path
+
+    from wexample_helpers.helper.git import git_commit_paths, git_repository_root
+
+    by_repository: dict[Path, list[Path]] = {}
+    for raw in written:
+        path = Path(raw)
+        repository = git_repository_root(path)
+        if repository is not None:
+            by_repository.setdefault(repository, []).append(path)
+
+    return {
+        str(repository): git_commit_paths(repository, paths, message, author=author)
+        for repository, paths in by_repository.items()
+    }
+
+
+def _commit_wrapper(
+    next_dispatch: AnyCallable,
+    function_kwargs: dict[str, Any],
+    request: Any,
+    commit_subject: str | None = None,
+) -> Any:
+    # Always taken off, so the command never receives what it does not declare.
+    commit = function_kwargs.pop(OPTION_NAME_COMMIT, False)
+    author = function_kwargs.pop(OPTION_NAME_COMMIT_AUTHOR, None)
+
+    response = next_dispatch(function_kwargs)
+
+    content = response.content
+    if commit and isinstance(content, dict) and content.get(CONTENT_KEY_WRITTEN):
+        content[CONTENT_KEY_COMMITS] = _commit(
+            content[CONTENT_KEY_WRITTEN], autocommit_message(commit_subject), author
+        )
+
+    return response