lekha-poth-cli 2.1.0__tar.gz

lekha_poth_cli-2.1.0/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+.pytest_cache/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.DS_Store
+.env
+config.json
+
+# skill-creator eval workspace (snapshots, run outputs) — local only
+skills/*-workspace/

lekha_poth_cli-2.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.5
+Name: lekha-poth-cli
+Version: 2.1.0
+Summary: Production Typer CLI covering every Lekha Poth HTTP API endpoint.
+Author: Hermes Agent
+License: MIT
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic-settings>=2.4.0
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: typer>=0.15.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+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
+`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.
+
+## Install
+
+```bash
+uv venv
+uv pip install -e ~/.hermes/skills/software-development/lekha-poth/lpcli
+# or: uv tool install -e that-path
+lp --help
+```
+
+The wrapper `~/.local/bin/lp` should point at this package.
+
+## Configure (once)
+
+```bash
+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
+lp config set-defaults --output pretty --default-size 20
+lp status
+lp whoami
+```
+
+Config file: `~/.config/lekha-poth/config.json` (mode `0600`).
+Existing keys (`api_base`, `api_key`, `site_url`, `key_name`, `created_at`) are kept.
+
+Env overrides: `LEKHA_POTH_API_BASE`, `LEKHA_POTH_API_KEY`, `LEKHA_POTH_SITE_URL`, `LEKHA_POTH_CONFIG`.
+
+## Coverage
+
+```bash
+lp endpoints              # every route, from endpoints.json
+lp endpoints --admin
+lp --help
+lp admin items --help
+lp items get --help       # every query/body field is a flag
+```
+
+Raw escape hatch:
+
+```bash
+lp api request GET /items --param size=5 --param kind=text
+lp api request GET /health --root
+```
+
+Staff media (initiate → direct PUT → complete → poll):
+
+```bash
+lp upload ./ep.mp4 --visibility public --role original --item-id UUID --wait
+```
+
+## Iron rules (from the live API)
+
+- Wire JSON is **camelCase** except pagination: `{size, next_cursor, has_next}` (never `hasNext`, no `total` on public lists).
+- Errors: `{"error": {code, message, details, request_id}}` — branch on `error.code`.
+- `coverUrl` is stable or `null`. `assets[].url` may be presigned (~15 min); match assets by `role`.
+- Legacy `/chapters` and `/series` exist only when `APP_LEGACY_API_ENABLED`.
+- Never store presigned URLs. Never put `lpak_` in git, skills, or Hermes memory.
+
+## Regenerating the route catalogue
+
+`src/lekha_poth_cli/endpoints.json` drives every command, and it is **derived
+from the live FastAPI app** — there is no intermediate artefact to keep in sync:
+
+```bash
+cd backend
+uv run python ../scripts/agent/lpcli/scripts/generate_spec.py          # rewrite it
+uv run python ../scripts/agent/lpcli/scripts/generate_spec.py --check  # verify only
+```
+
+`--check` writes nothing and exits non-zero when the tracked file is stale.
+`backend/tests/unit/test_agent_spec_current.py` runs the same comparison in CI,
+so adding a route to the API without regenerating fails the build.
+
+A **new** route stops the generator with an error rather than inventing a
+command name for it: the id is what a person types, so it is a decision. Add an
+entry to `NEW_IDENTITY` in the generator and re-run. Existing ids, `auth` values
+and hand-shortened flag names (`--status` for the parameter `status_filter`) are
+preserved on every run — they are the public CLI surface.
+
+Regenerating covers the **routes**. `docs/agent/*`, `agent/SKILL.md`,
+`public/llms.txt` and `public/.well-known/agent.json` are still updated by hand.

lekha_poth_cli-2.1.0/README.md

@@ -0,0 +1,93 @@
+# 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
+`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.
+
+## Install
+
+```bash
+uv venv
+uv pip install -e ~/.hermes/skills/software-development/lekha-poth/lpcli
+# or: uv tool install -e that-path
+lp --help
+```
+
+The wrapper `~/.local/bin/lp` should point at this package.
+
+## Configure (once)
+
+```bash
+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
+lp config set-defaults --output pretty --default-size 20
+lp status
+lp whoami
+```
+
+Config file: `~/.config/lekha-poth/config.json` (mode `0600`).
+Existing keys (`api_base`, `api_key`, `site_url`, `key_name`, `created_at`) are kept.
+
+Env overrides: `LEKHA_POTH_API_BASE`, `LEKHA_POTH_API_KEY`, `LEKHA_POTH_SITE_URL`, `LEKHA_POTH_CONFIG`.
+
+## Coverage
+
+```bash
+lp endpoints              # every route, from endpoints.json
+lp endpoints --admin
+lp --help
+lp admin items --help
+lp items get --help       # every query/body field is a flag
+```
+
+Raw escape hatch:
+
+```bash
+lp api request GET /items --param size=5 --param kind=text
+lp api request GET /health --root
+```
+
+Staff media (initiate → direct PUT → complete → poll):
+
+```bash
+lp upload ./ep.mp4 --visibility public --role original --item-id UUID --wait
+```
+
+## Iron rules (from the live API)
+
+- Wire JSON is **camelCase** except pagination: `{size, next_cursor, has_next}` (never `hasNext`, no `total` on public lists).
+- Errors: `{"error": {code, message, details, request_id}}` — branch on `error.code`.
+- `coverUrl` is stable or `null`. `assets[].url` may be presigned (~15 min); match assets by `role`.
+- Legacy `/chapters` and `/series` exist only when `APP_LEGACY_API_ENABLED`.
+- Never store presigned URLs. Never put `lpak_` in git, skills, or Hermes memory.
+
+## Regenerating the route catalogue
+
+`src/lekha_poth_cli/endpoints.json` drives every command, and it is **derived
+from the live FastAPI app** — there is no intermediate artefact to keep in sync:
+
+```bash
+cd backend
+uv run python ../scripts/agent/lpcli/scripts/generate_spec.py          # rewrite it
+uv run python ../scripts/agent/lpcli/scripts/generate_spec.py --check  # verify only
+```
+
+`--check` writes nothing and exits non-zero when the tracked file is stale.
+`backend/tests/unit/test_agent_spec_current.py` runs the same comparison in CI,
+so adding a route to the API without regenerating fails the build.
+
+A **new** route stops the generator with an error rather than inventing a
+command name for it: the id is what a person types, so it is a decision. Add an
+entry to `NEW_IDENTITY` in the generator and re-run. Existing ids, `auth` values
+and hand-shortened flag names (`--status` for the parameter `status_filter`) are
+preserved on every run — they are the public CLI surface.
+
+Regenerating covers the **routes**. `docs/agent/*`, `agent/SKILL.md`,
+`public/llms.txt` and `public/.well-known/agent.json` are still updated by hand.

lekha_poth_cli-2.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "lekha-poth-cli"
+version = "2.1.0"
+description = "Production Typer CLI covering every Lekha Poth HTTP API endpoint."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [{ name = "Hermes Agent" }]
+dependencies = [
+  "typer>=0.15.0",
+  "pydantic>=2.7.0",
+  "pydantic-settings>=2.4.0",
+  "httpx>=0.27.0",
+  "rich>=13.7.0",
+]
+
+[project.scripts]
+lp = "lekha_poth_cli.app:main"
+lekha-poth = "lekha_poth_cli.app:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lekha_poth_cli"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/lekha_poth_cli/endpoints.json" = "lekha_poth_cli/endpoints.json"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

lekha_poth_cli-2.1.0/scripts/generate_catalog_v2.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+"""Regenerate ``docs/agent/API_CATALOG_V2.md``'s route table from ``endpoints.json``.
+
+Run from anywhere in the repo::
+
+    python3 scripts/agent/lpcli/scripts/generate_catalog_v2.py
+    python3 scripts/agent/lpcli/scripts/generate_catalog_v2.py --check
+
+``--check`` writes nothing and exits non-zero when the tracked file is stale —
+the same contract ``generate_spec.py`` uses, so this can guard CI the same way
+(see ``backend/tests/unit/test_agent_spec_current.py``, which this script's
+own currency should eventually join — #172).
+
+Why this exists
+----------------
+``API_CATALOG_V2.md`` claims to be "Generated from FastAPI routers" and had no
+generator. It was hand-maintained, drifted to 120 routes while the live app
+served 132/114, and stayed wrong through several releases because nothing
+could regenerate it and nothing checked it (#64). ``endpoints.json`` is
+already the single source of truth for the CLI's route surface (regenerated
+from the live app by ``generate_spec.py``) — this script derives the table
+mechanically from it instead of transcribing by hand a second time.
+
+What this script does NOT own
+------------------------------
+The free-text sections above and below the table (the intro, the field
+documentation) are hand-written and preserved verbatim between the
+``<!-- BEGIN:route-table -->`` / ``<!-- END:route-table -->`` markers this
+script owns. Nothing here can generate prose explaining what ``coverUrl`` is.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[4]
+ENDPOINTS = ROOT / "scripts" / "agent" / "lpcli" / "src" / "lekha_poth_cli" / "endpoints.json"
+CATALOG = ROOT / "docs" / "agent" / "API_CATALOG_V2.md"
+
+BEGIN = "<!-- BEGIN:route-table -->"
+END = "<!-- END:route-table -->"
+
+
+def _cli_command(endpoint_id: str) -> str:
+    """``admin.characters.extract`` -> ``lp admin characters extract``."""
+    return "lp " + endpoint_id.replace(".", " ")
+
+
+def build_table(endpoints: list[dict]) -> str:
+    on = len(endpoints)
+    off = sum(1 for e in endpoints if not e["deprecated"])
+    lines = [
+        BEGIN,
+        f"Total routes: **{on}** with the deprecated legacy aliases on "
+        f"(`APP_LEGACY_API_ENABLED=true`), **{off}** with them off (the "
+        "production default). `lp endpoints` is the live count; this table is "
+        "regenerated from the same source.",
+        "",
+        "| CLI | Method | Path | Auth | Deprecated |",
+        "|-----|--------|------|------|------------|",
+    ]
+    for e in sorted(endpoints, key=lambda e: (e["path"], e["method"])):
+        deprecated = "yes" if e["deprecated"] else ""
+        lines.append(
+            f"| `{_cli_command(e['id'])}` | {e['method']} | `{e['path']}` | "
+            f"{e['auth']} | {deprecated} |"
+        )
+    lines.append(END)
+    return "\n".join(lines)
+
+
+def render(endpoints: list[dict], existing: str) -> str:
+    table = build_table(endpoints)
+    start = existing.find(BEGIN)
+    end = existing.find(END)
+    if start == -1 or end == -1:
+        raise SystemExit(
+            f"{CATALOG.relative_to(ROOT)} is missing the {BEGIN!r}/{END!r} "
+            "markers this script owns — restore them (see the top of "
+            "API_CATALOG_V2.md in git history) before regenerating."
+        )
+    return existing[:start] + table + existing[end + len(END) :]
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--check", action="store_true", help="exit non-zero if the tracked file is stale"
+    )
+    args = parser.parse_args()
+
+    if not ENDPOINTS.is_file():
+        raise SystemExit(
+            f"{ENDPOINTS.relative_to(ROOT)} is missing — regenerate it first:\n"
+            "  cd backend && uv run python ../scripts/agent/lpcli/scripts/generate_spec.py"
+        )
+    endpoints = json.loads(ENDPOINTS.read_text(encoding="utf-8"))["endpoints"]
+    existing = CATALOG.read_text(encoding="utf-8")
+    updated = render(endpoints, existing)
+
+    if args.check:
+        if updated != existing:
+            print(f"{CATALOG.relative_to(ROOT)} is stale. Regenerate it:")
+            print("  python3 scripts/agent/lpcli/scripts/generate_catalog_v2.py")
+            return 1
+        print(f"{CATALOG.relative_to(ROOT)} is current.")
+        return 0
+
+    if updated == existing:
+        print(f"{CATALOG.relative_to(ROOT)} already current.")
+        return 0
+    CATALOG.write_text(updated, encoding="utf-8")
+    print(f"wrote {CATALOG.relative_to(ROOT)} ({len(endpoints)} endpoints)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())