lekha-poth-cli 2.2.0__tar.gz → 2.3.0__tar.gz

{lekha_poth_cli-2.2.0 → lekha_poth_cli-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: lekha-poth-cli
-Version: 2.2.0
+Version: 2.3.0
 Summary: Production Typer CLI covering every Lekha Poth HTTP API endpoint.
 Author: Hermes Agent
 License: MIT
@@ -17,12 +17,12 @@ Description-Content-Type: text/markdown
 # Lekha Poth CLI (`lp`) v2
 
 Production Typer + Pydantic client for **every** Lekha Poth HTTP endpoint,
-generated from `backend/src/app/api` on `main` (kept in sync — currently
-140 routes as of product v0.16.2 / `6d2c833`; regenerate with
+generated from `backend/src/app/api` on `main` (kept in sync — `lp endpoints`
+for the live count, synced at product v0.20.1 / `bf5ea4e`; regenerate with
 `generate_spec.py` after any route change, guarded in CI by
 `backend/tests/unit/test_agent_spec_current.py`).
 
-Replaces the old stdlib `scripts/agent/lp.py` reader CLI.
+It replaced the stdlib `lp.py` / `lp_media.py`, which were removed in #389.
 
 ## Install
 
@@ -68,7 +68,7 @@ lp config set --api-base "$LEKHA_POTH_API_BASE" \
               --site-url "$LEKHA_POTH_SITE_URL" \
               --api-key lpak_…
 # hosted production example:
-#   --api-base https://api.lekhapoth.com/api/v1 --site-url https://lekhapoth.com
+#   --api-base https://api.lekhapoth.com/api/v1 --site-url https://www.lekhapoth.com
 lp config set-defaults --output pretty --default-size 20
 lp status
 lp whoami

{lekha_poth_cli-2.2.0 → lekha_poth_cli-2.3.0}/README.md

@@ -1,12 +1,12 @@
 # Lekha Poth CLI (`lp`) v2
 
 Production Typer + Pydantic client for **every** Lekha Poth HTTP endpoint,
-generated from `backend/src/app/api` on `main` (kept in sync — currently
-140 routes as of product v0.16.2 / `6d2c833`; regenerate with
+generated from `backend/src/app/api` on `main` (kept in sync — `lp endpoints`
+for the live count, synced at product v0.20.1 / `bf5ea4e`; regenerate with
 `generate_spec.py` after any route change, guarded in CI by
 `backend/tests/unit/test_agent_spec_current.py`).
 
-Replaces the old stdlib `scripts/agent/lp.py` reader CLI.
+It replaced the stdlib `lp.py` / `lp_media.py`, which were removed in #389.
 
 ## Install
 
@@ -52,7 +52,7 @@ lp config set --api-base "$LEKHA_POTH_API_BASE" \
               --site-url "$LEKHA_POTH_SITE_URL" \
               --api-key lpak_…
 # hosted production example:
-#   --api-base https://api.lekhapoth.com/api/v1 --site-url https://lekhapoth.com
+#   --api-base https://api.lekhapoth.com/api/v1 --site-url https://www.lekhapoth.com
 lp config set-defaults --output pretty --default-size 20
 lp status
 lp whoami

{lekha_poth_cli-2.2.0 → lekha_poth_cli-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "lekha-poth-cli"
-version = "2.2.0"
+version = "2.3.0"
 description = "Production Typer CLI covering every Lekha Poth HTTP API endpoint."
 readme = "README.md"
 requires-python = ">=3.12"

{lekha_poth_cli-2.2.0 → lekha_poth_cli-2.3.0}/scripts/generate_spec.py

@@ -64,6 +64,10 @@ API_V1_PREFIX = "/api/v1"
 #: Routes that are infrastructure, not API surface.
 SKIP_PATHS = {"/docs", "/openapi.json", "/redoc", "/metrics"}
 
+#: Service-to-service routes (#381): the Cloudflare jobs Worker's endpoint.
+#: Not for agents or any user credential, so never catalogued.
+SKIP_PREFIXES = ("/api/v1/internal/",)
+
 
 def _ensure_backend_importable() -> None:
     src = REPO_ROOT / "backend" / "src"
@@ -133,9 +137,27 @@ def _cli_type(annotation: Any) -> str:
     if annotation in (dict, Any) or origin is dict:
         return "json"
     if origin in (list, set, tuple):
-        inner = _cli_type(args[0]) if args else "str"
-        return f"{inner}_list"
+        if not args:
+            return "str_list"
+        inner = args[0]
+        # `list[tuple[str, float]]` (library import history) has its own CLI
+        # type; flattening it to a list of strings sent a shape the API refuses.
+        if typing.get_origin(inner) is tuple and list(typing.get_args(inner)) == [str, float]:
+            return "str_float_pairs"
+        # A list of objects, or of lists, has no flag spelling: take it as JSON.
+        if _is_model(inner):
+            return "json"
+        inner_type = _cli_type(inner)
+        if inner_type == "json" or inner_type.endswith(("_list", "_pairs")):
+            return "json"
+        return f"{inner_type}_list"
     if origin is not None and args:
+        # `str | list[str]`: the list arm decides the flag's type, or a repeated
+        # flag would collapse to one string (see `is_scalar_or_list`).
+        if origin is not typing.Annotated:
+            listy = [a for a in args if typing.get_origin(a) in (list, set, tuple)]
+            if listy:
+                return _cli_type(listy[0])
         # Optional[X] / Union[X, None] / Annotated[X, ...] -> X
         return _cli_type(args[0])
     for python_type, name in _SCALARS.items():
@@ -144,6 +166,29 @@ def _cli_type(annotation: Any) -> str:
     return "str"
 
 
+def _is_model(annotation: Any) -> bool:
+    from pydantic import BaseModel
+
+    return isinstance(annotation, type) and issubclass(annotation, BaseModel)
+
+
+def is_scalar_or_list(annotation: Any) -> bool:
+    """True for ``str | list[str]`` (optionally ``| None``): one value or many.
+
+    The CLI flag is repeatable. One value goes on the wire as the scalar and
+    several as a list, so ``--value my-series`` for ``move-collection`` stays a
+    string while ``--value a --value b`` for ``retag`` becomes ``["a", "b"]``.
+    """
+    import types
+    import typing
+
+    if typing.get_origin(annotation) not in (typing.Union, types.UnionType):
+        return False
+    args = [a for a in typing.get_args(annotation) if a is not type(None)]
+    listy = [a for a in args if typing.get_origin(a) in (list, set, tuple)]
+    return bool(listy) and len(listy) < len(args)
+
+
 #: The PATCH "leave alone" marker. A field whose annotation admits it also
 #: admits ``None``, which means "clear" — so the CLI must be able to send null.
 _UNSET_SENTINEL = "unset"
@@ -202,6 +247,15 @@ def choices_from_pattern(pattern: str | None) -> list[str] | None:
     return words
 
 
+def _max_length(field_info: Any) -> int | None:
+    """``Field(max_length=N)`` on a list field: the most values the API accepts."""
+    for node in getattr(field_info, "metadata", None) or []:
+        value = getattr(node, "max_length", None)
+        if isinstance(value, int):
+            return value
+    return None
+
+
 def _pattern_of(field_info: Any) -> str | None:
     """The ``pattern=`` constraint on a field, wherever pydantic/FastAPI put it."""
     nodes: list[Any] = list(getattr(field_info, "metadata", None) or [])
@@ -283,6 +337,8 @@ def _params(route: Any) -> tuple[list[dict[str, Any]], list[dict[str, Any]], lis
             "required": required,
             "multiple": cli_type.endswith("_list"),
         }
+        if is_scalar_or_list(annotation):
+            entry["scalar_if_single"] = True
         choices = field_choices(p.field_info)
         if choices:
             entry["choices"] = choices
@@ -336,6 +392,11 @@ def _body(route: Any) -> tuple[list[dict[str, Any]], bool]:
             entry["required"] = True
         if cli_type.endswith("_list"):
             entry["multiple"] = True
+            max_items = _max_length(info)
+            if max_items is not None:
+                entry["max_items"] = max_items
+        if is_scalar_or_list(annotation):
+            entry["scalar_if_single"] = True
         choices = field_choices(info)
         if choices:
             entry["choices"] = choices
@@ -343,10 +404,37 @@ def _body(route: Any) -> tuple[list[dict[str, Any]], bool]:
             # `--cover-asset-id null` must reach the API as JSON null (clear),
             # which is distinct from omitting the flag (leave alone).
             entry["sentinel_null"] = True
+        default = info.default
+        if (
+            not info.is_required()
+            and isinstance(default, (bool, int, float, str))
+            and default != _UNSET_SENTINEL
+        ):
+            # Documentation only: an unset flag is omitted and the API applies
+            # this itself. `--include-media` is worth knowing defaults to true.
+            entry["default"] = default
         out.append(entry)
     return out, _is_required(field)
 
 
+def _needs_session(route: Any) -> bool:
+    """True when the route depends on ``require_jwt_session`` at any depth.
+
+    Those routes refuse a personal API key (403) and want the bearer token of
+    an interactive login. Derived, never curated: a hand-kept list is how the
+    docs ended up telling agents to run ``lp keys permissions`` with a key.
+    """
+    from app.core.security import require_jwt_session
+
+    stack = [route.dependant]
+    while stack:
+        dependant = stack.pop()
+        if dependant.call is require_jwt_session:
+            return True
+        stack.extend(dependant.dependencies)
+    return False
+
+
 def _infer_auth(path: str) -> str:
     """Only for NEW routes; tracked ones keep whatever was curated."""
     if path.startswith(("/admin", "/me")):
@@ -444,7 +532,7 @@ def build(legacy: bool) -> list[dict[str, Any]]:
 
     entries: list[dict[str, Any]] = []
     for full_path, route in walk_routes(app):
-        if full_path in SKIP_PATHS:
+        if full_path in SKIP_PATHS or full_path.startswith(SKIP_PREFIXES):
             continue
         mount = "v1" if full_path.startswith(API_V1_PREFIX) else "root"
         path = full_path.removeprefix(API_V1_PREFIX) or "/"
@@ -466,7 +554,7 @@ def build(legacy: bool) -> list[dict[str, Any]]:
                     "path": path,
                     "summary": (route.summary or "").strip(),
                     "deprecated": bool(route.deprecated),
-                    "auth": _infer_auth(path),
+                    "auth": "session" if _needs_session(route) else _infer_auth(path),
                     "path_params": path_params,
                     "query": query,
                     "headers": headers,
@@ -525,6 +613,12 @@ def merge(
         kept = dict(entry)
         for field in ("id", "group", "name", "auth", "stream"):
             kept[field] = existing[field]
+        # "session" is derived from the route's dependencies, so it overrides a
+        # curated value in both directions: gained or lost with the dependency.
+        if entry["auth"] == "session":
+            kept["auth"] = "session"
+        elif existing["auth"] == "session":
+            kept["auth"] = entry["auth"]
         # A curated body is richer than the derived one only when derivation
         # found nothing at all.
         if existing.get("body") and not kept["body"]:

{lekha_poth_cli-2.2.0 → lekha_poth_cli-2.3.0}/skills/lp-cli/README.md

@@ -1,7 +1,7 @@
 # lp-cli — an agent skill for the Lekha Poth CLI
 
 This directory is a self-contained [agent skill](https://docs.claude.com/en/docs/agents-and-tools/agent-skills)
-that teaches an LLM agent to operate [Lekha Poth](https://lekhapoth.com) through
+that teaches an LLM agent to operate [Lekha Poth](https://www.lekhapoth.com) through
 `lp`, the full-coverage command-line client published on PyPI as
 [`lekha-poth-cli`](https://pypi.org/project/lekha-poth-cli/).
 
@@ -43,6 +43,8 @@ lp-cli/
 │   ├── chats.md                 # generated — persona chat
 │   ├── admin.md                 # generated — every /admin/* command
 │   ├── legacy.md                # generated — deprecated /chapters, /series aliases
+│   ├── workflows.md             # hand-written — setup, login, media, publish (the non-generated commands)
+│   ├── manifest.md              # hand-written — `lp publish manifest` JSON schema
 │   └── vocab.md                 # hand-written — what each allowed value means
 ├── scripts/
 │   └── generate_references.py   # rebuilds references/*.md from the CLI's endpoints.json
@@ -52,7 +54,7 @@ lp-cli/
 
 ## Keeping the references in step with your CLI
 
-The six generated reference files describe the CLI at contract **2.2.0**. If
+The six generated reference files describe the CLI at contract **2.3.0**. If
 `lp --version` reports something newer, rebuild them from the spec that ships
 inside the installed package — no checkout required:
 
@@ -61,8 +63,9 @@ uv run --no-project --with lekha-poth-cli python3 scripts/generate_references.py
 uv run --no-project --with lekha-poth-cli python3 scripts/generate_references.py --check  # report only
 ```
 
-`SKILL.md` and `references/vocab.md` are hand-written and are not touched by
-the script; where they and `lp <command> --help` disagree, `--help` is current.
+`SKILL.md`, `references/vocab.md`, `references/workflows.md` and
+`references/manifest.md` are hand-written and are not touched by the script;
+where they and `lp <command> --help` disagree, `--help` is current.
 
 ## For maintainers (inside the Lekha Poth repository)
 
@@ -88,11 +91,15 @@ What still needs a human:
 - **Behaviour that isn't visible from the schema.** Record it in
   `ENDPOINT_NOTES` / `FIELD_VOCAB_HINTS` in `generate_references.py`, only
   after reading the backend code.
-- **`references/vocab.md` and `SKILL.md`.** Every claim should name the
-  source file it was checked against.
+- **`SKILL.md`, `references/vocab.md`, `workflows.md`, `manifest.md`.** Every
+  claim should name the source file it was checked against. A change to a
+  hand-written command (`app.py`, `auth_flow.py`, `media.py`, `publish.py`)
+  means updating `workflows.md` / `manifest.md`.
 - **A new route** needs an entry in `NEW_IDENTITY` in `generate_spec.py`; the
   generator refuses to invent command names.
-- **A CLI behaviour change** means bumping `lpcli`'s `__version__` together
-  with the contract version in `SKILL.md`'s title and §11, the repo's
-  `agent/SKILL.md` `version` / `cli_package`, and publishing the new version
-  to PyPI — a user who only has `uv tool upgrade` sees nothing until then.
+- **A CLI behaviour change** ships through **Actions → Release
+  (lekha-poth-cli)**, which runs `scripts/ci/stamp-lpcli-version.py` to update
+  every copy of the contract version (package, this skill's title, §0 and §11,
+  this README, `agent/SKILL.md`, `public/.well-known/agent.json`) and
+  publishes to PyPI. Don't bump them by hand: a user who only has
+  `uv tool upgrade` sees nothing until the release.