pychestrate-service 0.0.7rc0__py3-none-any.whl

ccai/pychestrate/admin/__init__.py

@@ -0,0 +1,17 @@
+"""
+.. module:: pychestrate.admin
+    :platform: Darwin, Linux, Unix, Windows
+    :synopsis: Operator-facing administrative CLI tooling for Pychestrate.
+
+.. moduleauthor:: Code Craft AI LLC
+
+The ``pychestrate-admin`` console script entry point lives here. It is
+deliberately separate from the runtime web-service code under
+``pychestrate.webservice`` so service deployments do not pull in CLI
+argparse / Jinja2 / file-generation utilities at request time.
+"""
+
+__author__ = "Code Craft AI LLC"
+__copyright__ = "Copyright 2025, Code Craft AI LLC"
+__credits__ = []
+__version__ = "1.0.0"

ccai/pychestrate/admin/__main__.py

@@ -0,0 +1,108 @@
+"""
+.. module:: pychestrate.admin.__main__
+    :platform: Darwin, Linux, Unix, Windows
+    :synopsis: ``pychestrate-admin`` entry point dispatcher.
+
+.. moduleauthor:: Code Craft AI LLC
+
+Routes the first positional argument to a registered subsystem:
+``pack-template`` and ``backup`` (create / list / verify / restore
+backups, see :mod:`ccai.pychestrate.webservice.backup.cli`); future
+subsystems (``manifest``, ``extensions``, …) register themselves here.
+"""
+
+__author__ = "Code Craft AI LLC"
+__copyright__ = "Copyright 2025, Code Craft AI LLC"
+__credits__ = []
+__version__ = "1.0.0"
+
+
+import sys
+
+from typing import List, Optional, Sequence
+
+from ccai.pychestrate.webservice.extension.pack_template import cli as pack_template_cli
+
+
+SUBSYSTEM_PACK_TEMPLATE: str = "pack-template"
+SUBSYSTEM_BACKUP: str = "backup"
+
+
+_SUBSYSTEM_HELP_LINES: List[str] = [
+    "usage: pychestrate-admin <subsystem> [args]",
+    "",
+    "subsystems:",
+    "  pack-template   Generate / upgrade pychestrate-ext-<name> packs.",
+    "  backup          Create, list, verify and restore backups.",
+    "",
+]
+
+
+def _print_top_level_help() -> None:
+    """
+        Print the top-level help summary.
+
+        :returns: None.
+    """
+    sys.stderr.write("\n".join(_SUBSYSTEM_HELP_LINES))
+    return
+
+
+def main(*, argv: Optional[Sequence[str]]) -> int:
+    """
+        Dispatch a ``pychestrate-admin`` invocation.
+
+        :param argv: Override argv (mainly for tests). ``None`` defaults
+                     to :data:`sys.argv` slicing.
+
+        :returns: Process exit code.
+    """
+    if argv is None:
+        argv_list: Sequence[str] = sys.argv[1:]
+    else:
+        argv_list = argv
+
+    if len(argv_list) == 0:
+        _print_top_level_help()
+        rtnval = 2
+        return rtnval
+
+    subsystem = argv_list[0]
+    remainder: List[str] = list(argv_list[1:])
+
+    if subsystem == SUBSYSTEM_PACK_TEMPLATE:
+        rtnval = pack_template_cli.main(argv=remainder)
+        return rtnval
+
+    if subsystem == SUBSYSTEM_BACKUP:
+        # Imported here: the backup command pulls in SQLAlchemy and the
+        # service models, which pack-template does not need.
+        from ccai.pychestrate.webservice.backup import cli as backup_cli
+        rtnval = backup_cli.main(argv=remainder)
+        return rtnval
+
+    if subsystem in ("-h", "--help", "help"):
+        _print_top_level_help()
+        rtnval = 0
+        return rtnval
+
+    sys.stderr.write("error: unknown subsystem '{}'\n".format(subsystem))
+    _print_top_level_help()
+    rtnval = 2
+    return rtnval
+
+
+def console_main() -> None:
+    """
+        The ``pychestrate-admin`` console script's entry point (declared in
+        ``pyproject.toml``): runs :func:`main` on :data:`sys.argv` and exits with
+        its code. ``main`` takes ``argv`` as a keyword-only argument, so a console
+        script cannot name it directly.
+
+        :returns: None (raises :class:`SystemExit`).
+    """
+    sys.exit(main(argv=None))
+
+
+if __name__ == "__main__":
+    console_main()

ccai/pychestrate/cli/__init__.py

@@ -0,0 +1,41 @@
+"""
+.. module:: pychestrate.cli
+    :platform: Darwin, Linux, Unix, Windows
+    :synopsis: ``pyc`` CLI consuming Pychestrate's REST API.
+
+.. moduleauthor:: Code Craft AI LLC
+
+The CLI lives under ``source/site/ccai/pychestrate/cli/``, talks to
+the service only through ``/api/v1``, and imports nothing but the
+Python standard library and this package, so it is also packaged on
+its own (``packages/pychestrate-cli``, the ``pychestrate-cli``
+distribution):
+
+* :mod:`entry` -- the dispatcher and console script
+  (:func:`entry.console_main`);
+* :mod:`version` -- the one definition of pyc's version;
+* :mod:`commands` -- ``login`` / ``logout`` / ``whoami``, ``config``,
+  ``version``, the commands generated from the server's OpenAPI
+  document, ``runs wait``, ``ext`` and ``plugin-api catalog``;
+* :mod:`renderer` / :mod:`pagination` -- table / JSON / YAML / TSV /
+  raw output, ``--fields``, ``--quiet``, ``--all`` / ``--limit``;
+* :mod:`argparsing` / :mod:`suggestions` -- parsers that never exit
+  the process, and "did you mean" for typos;
+* :mod:`credentials` / :mod:`paths` / :mod:`context` -- profiles in
+  ``$XDG_CONFIG_HOME/pychestrate/credentials`` (mode ``0600``) and the
+  ``PYC_SERVER_URL`` / ``PYC_TOKEN`` environment overrides;
+* :mod:`transport` -- HTTP with the profile's API token as a bearer
+  token, no redirect following, and one exception per exit-code
+  category;
+* :mod:`parser` / :mod:`command_names` / :mod:`openapi_cache` /
+  :mod:`builtin_operations` -- the command tree built from
+  ``/api/v1/_meta/openapi.json`` (explicit command names, cached, with
+  a built-in fallback);
+* :mod:`extensions` -- the ``CLISubcommandExtension`` surface behind
+  ``pyc ext <ext-name> <verb>``.
+"""
+
+__author__ = "Code Craft AI LLC"
+__copyright__ = "Copyright 2025, Code Craft AI LLC"
+__credits__ = []
+__version__ = "1.0.0"

ccai/pychestrate/cli/argparsing.py

@@ -0,0 +1,136 @@
+"""
+.. module:: cli.argparsing
+    :platform: Darwin, Linux, Unix, Windows
+    :synopsis: An :class:`argparse.ArgumentParser` that writes to the
+               invocation's streams and never exits the process.
+
+.. moduleauthor:: Code Craft AI LLC
+
+``pyc`` is callable in-process (tests, embedding), so a parser must
+not call :func:`sys.exit` or write to the real ``sys.stdout``. Help
+output goes to the context's stdout and raises :class:`ParserExit`
+with status 0; a parse error raises :class:`CliUsageError`, which the
+dispatcher reports and turns into exit code 2.
+
+Options must be spelled out (no ``--per`` for ``--per-page``), and an
+unrecognized option is reported with the closest known ones
+("did you mean '--state'?").
+"""
+
+__author__ = "Code Craft AI LLC"
+__copyright__ = "Copyright 2026, Code Craft AI LLC"
+__credits__ = []
+__version__ = "1.0.0"
+
+
+import argparse
+import sys
+
+from typing import Any, List, Optional, TextIO
+
+from ccai.pychestrate.cli import suggestions
+from ccai.pychestrate.cli.exceptions import CliUsageError
+
+
+_UNRECOGNIZED_PREFIX: str = "unrecognized arguments: "
+
+#: pyc's global options (accepted anywhere on the line, parsed before
+#: any command's parser runs). They are suggestion candidates too, so a
+#: mistyped global -- or the pod client's "--service-url" -- names the
+#: right spelling.
+GLOBAL_OPTION_NAMES = (
+    "--profile", "--server-url", "--timeout", "--output", "-o", "--fields", "--quiet", "-q",
+)
+
+
+class ParserExit(Exception):
+    """
+        Raised instead of :func:`sys.exit` when a parser finishes early
+        (``--help``).
+
+        :param status: Exit status the parser asked for.
+    """
+
+    def __init__(self, status: int) -> None:
+        super().__init__("parser exit {}".format(status))
+        self.status: int = status
+        return
+
+
+class CliArgumentParser(argparse.ArgumentParser):
+    """
+        Argument parser bound to explicit output streams.
+    """
+
+    def __init__(self, *args: Any, out_stream: TextIO, err_stream: TextIO, **kwargs: Any) -> None:
+        kwargs.setdefault("formatter_class", argparse.RawDescriptionHelpFormatter)
+        kwargs.setdefault("allow_abbrev", False)
+        super().__init__(*args, **kwargs)
+        self._out_stream: TextIO = out_stream
+        self._err_stream: TextIO = err_stream
+        return
+
+    def _print_message(self, message: str, file: Optional[TextIO] = None) -> None:
+        if not message:
+            return
+        if file is None or file is sys.stdout:
+            self._out_stream.write(message)
+        else:
+            self._err_stream.write(message)
+        return
+
+    def exit(self, status: int = 0, message: Optional[str] = None) -> None:
+        if message:
+            self._err_stream.write(message)
+        raise ParserExit(status)
+
+    def known_option_strings(self) -> List[str]:
+        """
+            Every listed option spelling of this parser (hidden
+            aliases excluded).
+
+            :returns: Option strings.
+        """
+        known: List[str] = []
+        for action in self._actions:
+            if action.help == argparse.SUPPRESS:
+                continue
+            known.extend(action.option_strings)
+        rtnval = known
+        return rtnval
+
+    def _suggest_for_unrecognized(self, message: str) -> str:
+        """
+            Add "did you mean" hints to argparse's "unrecognized
+            arguments" message.
+
+            :param message: argparse's message.
+
+            :returns: Message (unchanged when nothing is close).
+        """
+        if not message.startswith(_UNRECOGNIZED_PREFIX):
+            return message
+        hints: List[str] = []
+        candidates = self.known_option_strings() + list(GLOBAL_OPTION_NAMES)
+        for token in message[len(_UNRECOGNIZED_PREFIX):].split():
+            if not token.startswith("-"):
+                continue
+            option = token.split("=", 1)[0]
+            hint = suggestions.did_you_mean(word=option, candidates=candidates)
+            if len(hint) > 0:
+                hints.append("{}: {}".format(option, hint))
+        if len(hints) == 0:
+            return message
+        rtnval = "{} ({})".format(message, "; ".join(hints))
+        return rtnval
+
+    def error(self, message: str) -> None:
+        self.print_usage(self._err_stream)
+        raise CliUsageError("{}: {}".format(self.prog, self._suggest_for_unrecognized(message)))
+
+
+__all__ = [
+    "CliArgumentParser",
+    "GLOBAL_OPTION_NAMES",
+    "ParserExit",
+]

ccai/pychestrate/cli/builtin_operations.py

@@ -0,0 +1,84 @@
+"""
+.. module:: cli.builtin_operations
+    :platform: Darwin, Linux, Unix, Windows
+    :synopsis: The commands ``pyc`` knows without the server's OpenAPI
+               document.
+
+.. moduleauthor:: Code Craft AI LLC
+
+``pyc`` builds its API commands from the server's
+``/api/v1/_meta/openapi.json``. When that document cannot be fetched
+(an older server, a proxy that blocks it, no network yet) and no
+cached copy exists, the CLI falls back to this small built-in
+document so the everyday commands still work and the real request
+reports the real problem (unreachable, 401, ...).
+"""
+
+__author__ = "Code Craft AI LLC"
+__copyright__ = "Copyright 2026, Code Craft AI LLC"
+__credits__ = []
+__version__ = "1.0.0"
+
+
+from typing import Any, Dict
+
+
+_SLUG_PARAM: Dict[str, Any] = {
+    "name": "slug", "in": "path", "required": True, "schema": {"type": "string"},
+}
+_RUN_ID_PARAM: Dict[str, Any] = {
+    "name": "run_id", "in": "path", "required": True, "schema": {"type": "string"},
+}
+_PAGE_PARAMS = [
+    {"name": "page", "in": "query", "required": False, "schema": {"type": "integer"}},
+    {"name": "per_page", "in": "query", "required": False, "schema": {"type": "integer"}},
+]
+
+#: Minimal OpenAPI document (same shape and operation ids as the
+#: server's) used when the real one is unavailable.
+FALLBACK_OPENAPI_DOCUMENT: Dict[str, Any] = {
+    "openapi": "3.1.0",
+    "info": {"title": "Pychestrate (pyc built-in fallback)", "version": "pyc-builtin"},
+    "servers": [{"url": "/api/v1"}],
+    "paths": {
+        "/me": {
+            "get": {
+                "operationId": "me_get_identity", "tags": ["me"],
+                "summary": "Who the caller is and how the request authenticated.",
+            },
+        },
+        "/projects": {
+            "get": {
+                "operationId": "projects_list", "tags": ["projects"],
+                "summary": "List projects.", "parameters": list(_PAGE_PARAMS),
+            },
+            "post": {
+                "operationId": "projects_create", "tags": ["projects"],
+                "summary": "Create a project.", "requestBody": {"required": True},
+            },
+        },
+        "/projects/{slug}": {
+            "get": {
+                "operationId": "projects_get_by_slug", "tags": ["projects"],
+                "summary": "Read a project by slug.", "parameters": [_SLUG_PARAM],
+            },
+        },
+        "/runs": {
+            "get": {
+                "operationId": "runs_list", "tags": ["runs"],
+                "summary": "List runs.", "parameters": list(_PAGE_PARAMS),
+            },
+        },
+        "/runs/{run_id}": {
+            "get": {
+                "operationId": "runs_get_by_id", "tags": ["runs"],
+                "summary": "Read one run.", "parameters": [_RUN_ID_PARAM],
+            },
+        },
+    },
+}
+
+
+__all__ = [
+    "FALLBACK_OPENAPI_DOCUMENT",
+]

ccai/pychestrate/cli/command_names.py

@@ -0,0 +1,255 @@
+"""
+.. module:: cli.command_names
+    :platform: Darwin, Linux, Unix, Windows
+    :synopsis: The ``pyc <noun> <verb>`` names of the server's REST
+               operations.
+
+.. moduleauthor:: Code Craft AI LLC
+
+Every operation of the server's OpenAPI document is one
+``pyc <noun> <verb>`` command. Its name comes from, in order:
+
+1. the operation's ``x-cli`` extension in the OpenAPI document
+   (``x-cli: {noun: rpa-jobs, verb: trigger}``), so the REST contract
+   can name its own commands;
+2. :data:`COMMAND_NAMES` below, for the operations whose derived name
+   reads badly: a tag that groups several REST resources (``rpa``
+   holds job types, specifications and jobs), or a verb that repeats
+   the resource (``notifications list-channels``);
+3. derivation (see :mod:`cli.parser`): the first tag is the noun and
+   the ``operationId`` without the tag prefix is the verb, with the
+   :data:`VERB_SYNONYMS` spellings (``read`` and ``get-by-<x>`` are
+   ``get``, ``patch`` is ``update``) when that verb is still free.
+
+Nouns are the plural REST resource names (``projects``,
+``rpa-jobs``); a singular noun is accepted too. The derived name always
+stays an alias, so ``pyc projects get-by-slug demo`` still works next
+to ``pyc projects get demo``.
+
+The table is keyed by ``operationId``; the REST <-> CLI parity test
+(``test_p27p_pyc_command_names_m3``) fails when an entry names an
+operation the document no longer has, or when two operations end up
+with the same name.
+"""
+
+__author__ = "Code Craft AI LLC"
+__copyright__ = "Copyright 2026, Code Craft AI LLC"
+__credits__ = []
+__version__ = "1.0.0"
+
+
+import re
+
+from typing import Dict, Optional, Tuple
+
+
+#: The OpenAPI operation extension that names an operation's command.
+X_CLI_EXTENSION: str = "x-cli"
+
+#: Derived verbs spelled with the standard verb instead, when free.
+VERB_SYNONYMS: Dict[str, str] = {
+    "read": "get",
+    "patch": "update",
+}
+
+#: ``get-by-<anything>`` (``get-by-slug``, ``get-by-id``) is ``get``.
+GET_BY_VERB_PATTERN = re.compile(r"^get-by-[a-z0-9-]+$")
+
+#: Explicit names: ``operationId`` -> ``(noun, verb)``.
+COMMAND_NAMES: Dict[str, Tuple[str, str]] = {
+    # agents: agent rollouts, and the capability records of clients.
+    "agents_create_rollout": ("agent-rollouts", "create"),
+    "agents_start_rollout": ("agent-rollouts", "start"),
+    "agents_get_client_capabilities": ("clients", "get-capabilities"),
+    "agents_put_client_capabilities": ("clients", "set-capabilities"),
+    "agents_get_client_inventory": ("clients", "inventory"),
+
+    # api_tokens
+    "api_tokens_read_mine": ("api-tokens", "get-mine"),
+
+    # artifacts, and the result-upload calls pods make (tag results).
+    "artifacts_get_entry": ("artifacts", "get"),
+    "artifacts_list_for_run": ("artifacts", "list"),
+    "artifacts_local_upload": ("artifacts", "local-upload"),
+    "artifacts_presign_upload": ("artifacts", "presign-upload"),
+    "results_post_complete": ("results", "complete"),
+
+    # dispatch: the envelope-signing keys pods verify jobs with, and
+    # the acknowledgement a pod sends for a dispatched run.
+    "envelope_signing_keys_jwks": ("envelope-signing-keys", "jwks"),
+    "envelope_signing_keys_list": ("envelope-signing-keys", "list"),
+    "dispatch_ack_run": ("runs", "ack-dispatch"),
+
+    # progress: the live-progress frames a pod posts for a run.
+    "progress_post_frame": ("runs", "post-progress"),
+
+    # drift
+    "drift_check_trigger": ("drift", "check"),
+    "drift_status_read": ("drift", "status"),
+
+    # enrollment: tokens pods enroll with.
+    "enrollment_create_token": ("enrollment-tokens", "create"),
+    "enrollment_delete_token": ("enrollment-tokens", "delete"),
+    "enrollment_list_tokens": ("enrollment-tokens", "list"),
+    "enrollment_redeem": ("enrollment-tokens", "redeem"),
+    "enrollment_revoke_client": ("enrollment-tokens", "revoke-client"),
+
+    # flags
+    "flags_get_history": ("flags", "history"),
+
+    # me
+    "me_get_identity": ("me", "get"),
+    "me_get_navigation": ("me", "navigation"),
+    "me_get_permissions": ("me", "permissions"),
+    "me_ui_surfaces_read": ("me", "get-ui-surfaces"),
+    "me_ui_surfaces_update": ("me", "set-ui-surfaces"),
+    "me_ui_surfaces_delete": ("me", "delete-ui-surfaces"),
+
+    # metrics
+    "metrics_catalog_list": ("metrics", "catalog"),
+    "metrics_test_read": ("metrics", "tests"),
+    "metrics_timeseries_query": ("metrics", "query"),
+
+    # notifications: notification channels.
+    "notifications_create_channel": ("notification-channels", "create"),
+    "notifications_get_channel": ("notification-channels", "get"),
+    "notifications_list_channels": ("notification-channels", "list"),
+
+    # pipelines: pipeline runs are their own resource.
+    "pipeline_runs_list": ("pipeline-runs", "list"),
+    "pipeline_runs_read": ("pipeline-runs", "get"),
+    "pipeline_runs_trigger": ("pipeline-runs", "trigger"),
+
+    # pods: pod definitions and pod templates are their own resources.
+    "pods_create_definition": ("pod-definitions", "create"),
+    "pods_get_definition": ("pod-definitions", "get"),
+    "pods_list_definitions": ("pod-definitions", "list"),
+    "pods_create_template": ("pod-templates", "create"),
+    "pods_delete_template": ("pod-templates", "delete"),
+    "pods_list_templates": ("pod-templates", "list"),
+    "pods_materialize_template": ("pod-templates", "materialize"),
+    "pods_update_template_parameters": ("pod-templates", "set-parameters"),
+    "pods_apply_state_transition": ("pods", "transition"),
+    "pods_get_registration": ("pods", "registration"),
+    "pods_list_registrations": ("pods", "registrations"),
+    "pods_get_state": ("pods", "state"),
+    "pods_get_state_history": ("pods", "state-history"),
+    "pods_get_topology": ("pods", "topology"),
+
+    # provisioning: provisioning runs.
+    "provisioning_runs_list": ("provisioning-runs", "list"),
+    "provisioning_runs_read": ("provisioning-runs", "get"),
+    "provisioning_runs_trigger": ("provisioning-runs", "trigger"),
+
+    # resources
+    "resources_list_usage_history": ("resources", "usage-history"),
+    "resources_read_health": ("resources", "health"),
+    "resources_transition_state": ("resources", "transition"),
+
+    # retention: retention policies.
+    "retention_create": ("retention-policies", "create"),
+    "retention_get_by_id": ("retention-policies", "get"),
+    "retention_list": ("retention-policies", "list"),
+    "retention_publish": ("retention-policies", "publish"),
+
+    # rpa: job types (and their versions), specifications, jobs.
+    "rpa_execution_modes_list": ("rpa-execution-modes", "list"),
+    "rpa_job_type_versions_deprecate": ("rpa-job-types", "deprecate-version"),
+    "rpa_job_type_versions_publish": ("rpa-job-types", "publish-version"),
+    "rpa_job_type_versions_retire": ("rpa-job-types", "retire-version"),
+    "rpa_job_types_create": ("rpa-job-types", "create"),
+    "rpa_job_types_list": ("rpa-job-types", "list"),
+    "rpa_job_types_read": ("rpa-job-types", "get"),
+    "rpa_job_types_retire": ("rpa-job-types", "retire"),
+    "rpa_job_types_update": ("rpa-job-types", "update"),
+    "rpa_jobs_cancel": ("rpa-jobs", "cancel"),
+    "rpa_jobs_list": ("rpa-jobs", "list"),
+    "rpa_jobs_logs": ("rpa-jobs", "logs"),
+    "rpa_jobs_read": ("rpa-jobs", "get"),
+    "rpa_jobs_trigger": ("rpa-jobs", "trigger"),
+    "rpa_specs_create": ("rpa-specs", "create"),
+    "rpa_specs_delete": ("rpa-specs", "delete"),
+    "rpa_specs_list": ("rpa-specs", "list"),
+    "rpa_specs_read": ("rpa-specs", "get"),
+    "rpa_specs_update": ("rpa-specs", "update"),
+
+    # runs
+    "runs_subscribe_events": ("runs", "events"),
+
+    # system
+    "system_health_read": ("system", "health"),
+
+    # tagging: the /tags resource.
+    "tagging_attach": ("tags", "attach"),
+    "tagging_detach": ("tags", "detach"),
+    "tagging_list_for_entity": ("tags", "list"),
+    "tagging_list_taxonomies": ("tags", "taxonomies"),
+    "tagging_search": ("tags", "search"),
+
+    # variables
+    "variables_delete_one": ("variables", "delete"),
+    "variables_get_effective": ("variables", "effective"),
+    "variables_get_one": ("variables", "get"),
+    "variables_list_scope": ("variables", "list"),
+    "variables_put_one": ("variables", "set"),
+
+    # webhooks: inbound integrations and outbound subscriptions.
+    "webhooks_in_create_integration": ("webhook-integrations", "create"),
+    "webhooks_in_list_integrations": ("webhook-integrations", "list"),
+    "webhooks_in_update_integration": ("webhook-integrations", "update"),
+    "webhooks_in_list_deliveries": ("webhook-integrations", "deliveries"),
+    "webhooks_in_receive": ("webhook-integrations", "receive"),
+    "webhooks_out_create_subscription": ("webhook-subscriptions", "create"),
+    "webhooks_out_delete_subscription": ("webhook-subscriptions", "delete"),
+    "webhooks_out_list_deliveries": ("webhook-subscriptions", "deliveries"),
+    "webhooks_out_list_subscriptions": ("webhook-subscriptions", "list"),
+    "webhooks_out_read_subscription": ("webhook-subscriptions", "get"),
+    "webhooks_out_test_subscription": ("webhook-subscriptions", "test"),
+    "webhooks_out_update_subscription": ("webhook-subscriptions", "update"),
+}
+
+#: A well-formed noun or verb: lower-case words joined by ``-``.
+COMMAND_WORD_PATTERN = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
+
+
+def synonym_verb(verb: str) -> Optional[str]:
+    """
+        The standard spelling of a derived verb (``read`` -> ``get``,
+        ``get-by-slug`` -> ``get``, ``patch`` -> ``update``), or
+        ``None`` when the verb is already standard.
+
+        :param verb: Derived, normalized verb.
+
+        :returns: Standard verb or ``None``.
+    """
+    if verb in VERB_SYNONYMS:
+        rtnval: Optional[str] = VERB_SYNONYMS[verb]
+        return rtnval
+    if GET_BY_VERB_PATTERN.match(verb) is not None:
+        rtnval = "get"
+        return rtnval
+    rtnval = None
+    return rtnval
+
+
+def is_well_formed_word(word: str) -> bool:
+    """
+        Whether ``word`` is a well-formed noun or verb (lower case,
+        ``-`` between words, no spaces or underscores).
+
+        :param word: Noun or verb.
+
+        :returns: Boolean.
+    """
+    rtnval = COMMAND_WORD_PATTERN.match(word or "") is not None
+    return rtnval
+
+
+__all__ = [
+    "COMMAND_NAMES",
+    "COMMAND_WORD_PATTERN",
+    "VERB_SYNONYMS",
+    "X_CLI_EXTENSION",
+    "is_well_formed_word",
+    "synonym_verb",
+]

ccai/pychestrate/cli/commands/__init__.py

@@ -0,0 +1,21 @@
+"""
+.. module:: cli.commands
+    :platform: Darwin, Linux, Unix, Windows
+    :synopsis: ``pyc`` command implementations.
+
+.. moduleauthor:: Code Craft AI LLC
+
+* :mod:`api` -- the commands generated from the server's OpenAPI
+  document (``pyc <noun> <verb>``), plus ``pyc commands``.
+* :mod:`auth` -- ``pyc login``, ``pyc logout``, ``pyc whoami``.
+* :mod:`config` -- ``pyc config init|set|get|unset|profiles|path``.
+* :mod:`ext` -- ``pyc ext list``, ``pyc ext <ext-name> <verb>``,
+  ``pyc plugin-api catalog``.
+* :mod:`runs` -- ``pyc runs wait`` and ``--wait``.
+* :mod:`version` -- ``pyc version``.
+"""
+
+__author__ = "Code Craft AI LLC"
+__copyright__ = "Copyright 2026, Code Craft AI LLC"
+__credits__ = []
+__version__ = "1.0.0"