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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: lekha-poth-cli
-Version: 2.1.0
+Version: 2.3.0
 Summary: Production Typer CLI covering every Lekha Poth HTTP API endpoint.
 Author: Hermes Agent
 License: MIT
@@ -17,23 +17,49 @@ 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
 
+Published on PyPI as [`lekha-poth-cli`](https://pypi.org/project/lekha-poth-cli/).
+No checkout needed:
+
 ```bash
-uv venv
-uv pip install -e ~/.hermes/skills/software-development/lekha-poth/lpcli
-# or: uv tool install -e that-path
-lp --help
+uv tool install lekha-poth-cli      # → $HOME/.local/bin/lp
+uv tool upgrade lekha-poth-cli      # later, to pick up new routes and flags
+$HOME/.local/bin/lp --version
 ```
 
-The wrapper `~/.local/bin/lp` should point at this package.
+On macOS `/usr/bin/lp` is the print spooler and is on `PATH`, so call the
+Lekha Poth CLI by its absolute path (`$HOME/.local/bin/lp`), or use the
+alias entry point `lekha-poth`, which nothing else claims. To try it without
+installing: `uvx --from lekha-poth-cli lp --help`.
+
+An **agent skill** that teaches an LLM agent to drive this CLI ships in the
+sdist under `skills/lp-cli/` (and in the repository at
+`scripts/agent/lpcli/skills/lp-cli/`); its `README.md` says where to put it.
+
+### Developing against a checkout
+
+```bash
+cd scripts/agent/lpcli
+uv venv .venv && uv pip install --python .venv/bin/python -e ".[dev]"
+.venv/bin/python -m lekha_poth_cli --version
+# or, as a tool that tracks the working tree:  uv tool install -e .
+```
+
+### Releasing
+
+**Actions → Release (lekha-poth-cli) → Run workflow** (`bump` minor by default,
+or an exact `version`). It stamps every copy of the contract version
+(`scripts/ci/stamp-lpcli-version.py`), runs the tests, `uv build`s, commits
+and tags `lpcli-vX.Y.Z` on `main`, then `uv publish`es to PyPI. See
+`docs/CICD.md` → "Releasing the agent CLI".
 
 ## Configure (once)
 
@@ -42,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.1.0 → lekha_poth_cli-2.3.0}/README.md

@@ -1,23 +1,49 @@
 # 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
 
+Published on PyPI as [`lekha-poth-cli`](https://pypi.org/project/lekha-poth-cli/).
+No checkout needed:
+
 ```bash
-uv venv
-uv pip install -e ~/.hermes/skills/software-development/lekha-poth/lpcli
-# or: uv tool install -e that-path
-lp --help
+uv tool install lekha-poth-cli      # → $HOME/.local/bin/lp
+uv tool upgrade lekha-poth-cli      # later, to pick up new routes and flags
+$HOME/.local/bin/lp --version
 ```
 
-The wrapper `~/.local/bin/lp` should point at this package.
+On macOS `/usr/bin/lp` is the print spooler and is on `PATH`, so call the
+Lekha Poth CLI by its absolute path (`$HOME/.local/bin/lp`), or use the
+alias entry point `lekha-poth`, which nothing else claims. To try it without
+installing: `uvx --from lekha-poth-cli lp --help`.
+
+An **agent skill** that teaches an LLM agent to drive this CLI ships in the
+sdist under `skills/lp-cli/` (and in the repository at
+`scripts/agent/lpcli/skills/lp-cli/`); its `README.md` says where to put it.
+
+### Developing against a checkout
+
+```bash
+cd scripts/agent/lpcli
+uv venv .venv && uv pip install --python .venv/bin/python -e ".[dev]"
+.venv/bin/python -m lekha_poth_cli --version
+# or, as a tool that tracks the working tree:  uv tool install -e .
+```
+
+### Releasing
+
+**Actions → Release (lekha-poth-cli) → Run workflow** (`bump` minor by default,
+or an exact `version`). It stamps every copy of the contract version
+(`scripts/ci/stamp-lpcli-version.py`), runs the tests, `uv build`s, commits
+and tags `lpcli-vX.Y.Z` on `main`, then `uv publish`es to PyPI. See
+`docs/CICD.md` → "Releasing the agent CLI".
 
 ## Configure (once)
 
@@ -26,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.1.0 → lekha_poth_cli-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "lekha-poth-cli"
-version = "2.1.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.1.0 → lekha_poth_cli-2.3.0}/scripts/generate_spec.py

@@ -55,6 +55,8 @@ import uuid as _uuid
 from pathlib import Path
 from typing import Any
 
+from pydantic import AwareDatetime, FutureDatetime, NaiveDatetime, PastDatetime
+
 REPO_ROOT = Path(__file__).resolve().parents[4]
 OUT = REPO_ROOT / "scripts" / "agent" / "lpcli" / "src" / "lekha_poth_cli" / "endpoints.json"
 API_V1_PREFIX = "/api/v1"
@@ -62,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"
@@ -105,6 +111,15 @@ _SCALARS: dict[Any, str] = {
     bool: "bool",
     _uuid.UUID: "uuid",
     _dt.datetime: "datetime",
+    # Pydantic's constrained datetimes are distinct classes at runtime, not
+    # `Annotated[datetime, ...]`, so nothing above would unwrap them and the
+    # field would degrade to `str`. `publishedAt` is `AwareDatetime` — the API
+    # refuses a timezone-less value — and the CLI must still call it a
+    # datetime.
+    AwareDatetime: "datetime",
+    NaiveDatetime: "datetime",
+    PastDatetime: "datetime",
+    FutureDatetime: "datetime",
     _dt.date: "date",
 }
 
@@ -122,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():
@@ -133,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"
@@ -145,9 +201,7 @@ def _walk_annotation(annotation: Any) -> list[Any]:
     """The annotation and every type/metadata object nested inside it."""
     import typing
 
-    seen: list[Any] = [annotation]
-    for metadata in getattr(annotation, "__metadata__", ()):
-        seen.append(metadata)
+    seen: list[Any] = [annotation, *getattr(annotation, "__metadata__", ())]
     for arg in typing.get_args(annotation):
         seen.extend(_walk_annotation(arg))
     return seen
@@ -193,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 [])
@@ -274,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
@@ -327,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
@@ -334,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")):
@@ -435,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 "/"
@@ -457,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,
@@ -516,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.3.0/skills/lp-cli/README.md

@@ -0,0 +1,105 @@
+# 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://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/).
+
+You do **not** need the Lekha Poth source repository to use it. You need:
+
+1. **`uv`** — `curl -LsSf https://astral.sh/uv/install.sh | sh` (macOS/Linux).
+2. **The CLI** — `uv tool install lekha-poth-cli`, which puts `lp` at
+   `$HOME/.local/bin/lp`. Keep it current with `uv tool upgrade lekha-poth-cli`.
+3. **This directory**, placed where your agent loads skills from.
+
+## Installing the skill
+
+Copy the whole `lp-cli/` directory (keep `SKILL.md`, `references/`, `scripts/`
+together) into your agent's skills location:
+
+| Agent | Where |
+|---|---|
+| Claude Code, for one user | `~/.claude/skills/lp-cli/` |
+| Claude Code, for one project | `<project>/.claude/skills/lp-cli/` |
+| Any other agent that reads `SKILL.md` frontmatter | its skills directory |
+
+Or package it as a single file with the skill-creator's
+`package_skill.py` and install the resulting `lp-cli.skill`.
+
+The agent reads `SKILL.md` first. It holds the install and pre-flight steps,
+task recipes, the exit-code table and the wire conventions, and routes to one
+of the `references/*.md` files for a command's exact flags.
+
+## Layout
+
+```
+lp-cli/
+├── SKILL.md                     # entry point: pre-flight, recipes, conventions, errors
+├── README.md                    # this file (for humans)
+├── references/
+│   ├── public-content.md        # generated — items, collections, search, tags, sitemap, stats
+│   ├── auth-account.md          # generated — auth, /me, API keys
+│   ├── library.md               # generated — reader library + reports
+│   ├── 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
+└── evals/
+    └── evals.json               # test prompts used to evaluate the skill
+```
+
+## Keeping the references in step with your CLI
+
+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:
+
+```bash
+uv run --no-project --with lekha-poth-cli python3 scripts/generate_references.py          # rewrite
+uv run --no-project --with lekha-poth-cli python3 scripts/generate_references.py --check  # report only
+```
+
+`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)
+
+The skill lives at `scripts/agent/lpcli/skills/lp-cli/` and CI enforces that
+it matches the API. After any backend route or parameter change, from the
+repository root:
+
+```bash
+cd backend && uv run python ../scripts/agent/lpcli/scripts/generate_spec.py   # endpoints.json (types, choices, sentinels)
+cd .. && python3 scripts/agent/lpcli/scripts/generate_catalog_v2.py           # docs/agent/API_CATALOG_V2.md
+python3 scripts/agent/lpcli/skills/lp-cli/scripts/generate_references.py      # references/*.md
+```
+
+`backend/tests/unit/test_agent_spec_current.py` compares the spec with the
+live app; `scripts/agent/lpcli/tests/test_references_current.py` and
+`test_catalog_v2.py` check the two derived documents. When the skill is run
+from inside the checkout, `generate_references.py` reads the repository's
+`endpoints.json` rather than the installed package's, so the check is against
+the code under review. Allowed values are derived from the backend's
+`Literal` and `pattern=` validators, so a new vocabulary appears on its own.
+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.
+- **`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** 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.