procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/tools/connector-builder/actiondef.py

@@ -0,0 +1,24 @@
+"""ActionDef - dispatchable action unit for the connector-builder tool.
+
+Mirrors the redmine/quickmail-web pattern. Actions that talk to the API receive
+a live ``client`` first (so tests inject a fake and run with no network);
+``needs_client`` decides that. Pure/local actions (none today, but kept for
+parity) leave it False and receive only the parsed argparse namespace.
+"""
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+from typing import Callable
+
+
+def _no_args(_parser: argparse.ArgumentParser) -> None:
+    return None
+
+
+@dataclass
+class ActionDef:
+    func: Callable
+    add_args: Callable[[argparse.ArgumentParser], None] = _no_args
+    needs_client: bool = True
+    description: str = ""

procesio_cli/tools/connector-builder/client.py

@@ -0,0 +1,251 @@
+"""HTTP client for the AI Connector Builder API (connector-builder.procesio.app).
+
+Both supported auth modes resolve to the SAME wire shape: an
+``Authorization: Bearer <token>`` header (verified against the backend's
+``app/core/permissions.py`` — an API key is just a bearer token that starts with
+``acb_``). So the client only ever sets one header; how the token is obtained is
+the only difference between the two modes:
+
+  1. **API key** (default, simplest): the ``acb_...`` key, stored under
+     ``agents-and-tools:connector-builder:api-key``. Used verbatim as the bearer.
+  2. **Username / password**: ``username`` + ``password`` secrets → ``POST
+     /auth/login`` → ``access_token`` (a JWT) → used as the bearer. This is the
+     "web-tool" login the user referred to, done over the REST API instead of a
+     browser (the app exposes the same backend at ``/api/*``).
+
+Selection order (override with env ``CONNECTOR_BUILDER_AUTH=apikey|userpass``):
+api-key if stored, else username+password. Base URL defaults to the production
+host and is overridable via env ``CONNECTOR_BUILDER_BASE_URL``.
+
+See CONNECTOR-BUILDER-API-NOTES.md for the wire details.
+"""
+from __future__ import annotations
+
+import os
+import time
+from pathlib import Path
+from typing import Any, Optional
+
+import requests
+
+from errors import ApiError, CredentialError
+
+# A build is "done for now" when it pauses for the user or reaches a terminal
+# state. The sync LLM stages (gather/answer/revise-plan) 504 at the proxy but
+# keep running server-side, so --wait polls get-build until one of these holds.
+TERMINAL_STATUSES = {"completed", "failed", "delivered", "succeeded", "cancelled"}
+
+
+def build_is_settled(build: dict, until: str = "settled") -> bool:
+    """until='terminal' → only completed/failed/... ; 'settled' → also a
+    waiting_user pause (a stage finished and is waiting for the next action)."""
+    status = (build.get("status") or "").lower()
+    step = (build.get("step_status") or "").lower()
+    if status in TERMINAL_STATUSES:
+        return True
+    if until == "settled" and step == "waiting_user":
+        return True
+    return False
+
+TOOL = "connector-builder"
+
+# Production: Caddy strips the /api/* prefix and forwards to the backend, so the
+# REST surface documented in documentation/03-API-REFERENCE.md lives under /api.
+DEFAULT_BASE_URL = "https://connector-builder.procesio.app/api"
+
+TIMEOUT_CONNECT = 10
+TIMEOUT_READ = 180  # pipeline gather/plan calls can be slow; downloads stream
+
+
+def get_base_url() -> str:
+    return os.environ.get("CONNECTOR_BUILDER_BASE_URL", DEFAULT_BASE_URL).rstrip("/")
+
+
+def _cred(name: str) -> Optional[str]:
+    # Env override first (handy for CI / tests), then Credential Manager.
+    env = os.environ.get(f"CONNECTOR_BUILDER_{name.upper().replace('-', '_')}")
+    if env:
+        return env
+    import sys
+    framework_root = Path(__file__).resolve().parents[2]
+    if str(framework_root) not in sys.path:
+        sys.path.insert(0, str(framework_root))
+    from tools._lib import creds
+    return creds.get_optional(TOOL, name)
+
+
+def resolve_token() -> str:
+    """Resolve the bearer token per the configured/derived auth mode."""
+    mode = os.environ.get("CONNECTOR_BUILDER_AUTH", "").strip().lower()
+    api_key = _cred("api-key")
+    username = _cred("username")
+    password = _cred("password")
+
+    if not mode:
+        mode = "apikey" if api_key else ("userpass" if username and password else "")
+
+    if mode == "apikey":
+        if not api_key:
+            raise CredentialError(
+                "auth mode 'apikey' but no api-key stored. Store it with:\n"
+                "    python scripts/set-credential.py connector-builder api-key")
+        return api_key
+    if mode == "userpass":
+        if not (username and password):
+            raise CredentialError(
+                "auth mode 'userpass' but username/password not both stored. Set:\n"
+                "    python scripts/set-credential.py connector-builder username\n"
+                "    python scripts/set-credential.py connector-builder password")
+        return login(username, password)
+    raise CredentialError(
+        "no connector-builder credential found. Store an API key:\n"
+        "    python scripts/set-credential.py connector-builder api-key\n"
+        "or a username + password:\n"
+        "    python scripts/set-credential.py connector-builder username\n"
+        "    python scripts/set-credential.py connector-builder password")
+
+
+def login(username: str, password: str, base_url: Optional[str] = None) -> str:
+    """POST /auth/login → access_token (JWT). Used by the userpass auth mode."""
+    base = (base_url or get_base_url()).rstrip("/")
+    r = requests.post(
+        f"{base}/auth/login",
+        json={"email": username, "password": password},
+        timeout=(TIMEOUT_CONNECT, TIMEOUT_READ),
+    )
+    if r.status_code >= 400:
+        raise ApiError(r.status_code, "/auth/login", _detail(r))
+    tok = r.json().get("access_token")
+    if not tok:
+        raise ApiError(r.status_code, "/auth/login", "login returned no access_token")
+    return tok
+
+
+def _detail(resp: "requests.Response") -> str:
+    try:
+        body = resp.json()
+        if isinstance(body, dict):
+            return str(body.get("detail") or body.get("message") or body)
+        return str(body)
+    except ValueError:
+        return (resp.text or "")[:500]
+
+
+class ConnectorBuilderClient:
+    """Thin REST wrapper. One method per HTTP verb, plus multipart + binary
+    download. Every response is JSON except the binary download helpers."""
+
+    def __init__(self, base_url: Optional[str] = None, token: Optional[str] = None,
+                 session: Any = None):
+        self.base_url = (base_url or get_base_url()).rstrip("/")
+        self._token = token  # lazily resolved on first use if None
+        self._s = session or requests.Session()
+
+    # -- auth ---------------------------------------------------------------
+    @property
+    def token(self) -> str:
+        if self._token is None:
+            self._token = resolve_token()
+        return self._token
+
+    def _headers(self, extra: Optional[dict] = None) -> dict:
+        h = {
+            "Authorization": f"Bearer {self.token}",
+            "Accept": "application/json",
+            "User-Agent": "agents-and-tools-connector-builder/0.1",
+        }
+        if extra:
+            h.update(extra)
+        return h
+
+    def _url(self, path: str) -> str:
+        return f"{self.base_url}/{path.lstrip('/')}"
+
+    # -- verbs --------------------------------------------------------------
+    def request(self, method: str, path: str, *, params: Optional[dict] = None,
+                json_body: Any = None) -> Any:
+        r = self._s.request(
+            method.upper(), self._url(path),
+            params=params, json=json_body,
+            headers=self._headers(),
+            timeout=(TIMEOUT_CONNECT, TIMEOUT_READ),
+        )
+        if r.status_code >= 400:
+            raise ApiError(r.status_code, path, _detail(r))
+        if r.status_code == 204 or not (r.content or b"").strip():
+            return {}
+        try:
+            return r.json()
+        except ValueError:
+            return {"raw": r.text}
+
+    def get(self, path: str, params: Optional[dict] = None) -> Any:
+        return self.request("GET", path, params=params)
+
+    def post(self, path: str, json_body: Any = None, params: Optional[dict] = None) -> Any:
+        return self.request("POST", path, params=params, json_body=json_body)
+
+    def put(self, path: str, json_body: Any = None) -> Any:
+        return self.request("PUT", path, json_body=json_body)
+
+    def patch(self, path: str, json_body: Any = None) -> Any:
+        return self.request("PATCH", path, json_body=json_body)
+
+    def delete(self, path: str, params: Optional[dict] = None) -> Any:
+        return self.request("DELETE", path, params=params)
+
+    # -- polling ------------------------------------------------------------
+    def get_build(self, build_id: str) -> dict:
+        return self.get(f"/builds/{build_id}")
+
+    def wait_for_settled(self, build_id: str, *, timeout: int = 600,
+                         interval: int = 8, until: str = "settled",
+                         baseline_updated_at: Optional[str] = None,
+                         sleep=time.sleep, clock=time.monotonic) -> dict:
+        """Poll get-build until the build is settled (per `until`) AND — when a
+        baseline is given — its updated_at has advanced past it (so we never
+        return the pre-trigger state on a fast poll). Returns the last build seen
+        even if the timeout is hit (caller checks build_is_settled)."""
+        deadline = clock() + max(0, timeout)
+        build = self.get_build(build_id)
+        while True:
+            advanced = baseline_updated_at is None or \
+                build.get("updated_at") != baseline_updated_at
+            if advanced and build_is_settled(build, until):
+                return build
+            if clock() >= deadline:
+                return build
+            sleep(interval)
+            build = self.get_build(build_id)
+
+    # -- binary download ----------------------------------------------------
+    def download(self, path: str, out_path: str, params: Optional[dict] = None) -> dict:
+        """Stream a binary endpoint (artifact / file download / zip) to disk.
+        Returns {out, bytes, filename, content_type}."""
+        r = self._s.get(
+            self._url(path), params=params, headers=self._headers(),
+            timeout=(TIMEOUT_CONNECT, TIMEOUT_READ), stream=True,
+        )
+        if r.status_code >= 400:
+            raise ApiError(r.status_code, path, _detail(r))
+        out = Path(out_path)
+        out.parent.mkdir(parents=True, exist_ok=True)
+        total = 0
+        with open(out, "wb") as f:
+            for chunk in r.iter_content(chunk_size=65536):
+                if chunk:
+                    f.write(chunk)
+                    total += len(chunk)
+        return {
+            "out": str(out),
+            "bytes": total,
+            "filename": _content_disposition_filename(r) or out.name,
+            "content_type": r.headers.get("Content-Type"),
+        }
+
+
+def _content_disposition_filename(resp: "requests.Response") -> Optional[str]:
+    cd = resp.headers.get("Content-Disposition", "")
+    if "filename=" in cd:
+        return cd.split("filename=", 1)[1].strip().strip('"').split(";", 1)[0]
+    return None

procesio_cli/tools/connector-builder/errors.py

@@ -0,0 +1,44 @@
+"""Map exceptions to the framework error envelope: (code, message, details, exit).
+
+JSON in / JSON out: every uncaught exception becomes an {"error": {...}} object.
+We classify by exception type so an auth failure, a bad argument, and an HTTP
+4xx/5xx each surface with a distinct, stable code.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+class UsageError(Exception):
+    """Bad/invalid arguments. Maps to 'invalid_argument', exit 2."""
+
+
+class CredentialError(Exception):
+    """No usable credential (neither api-key nor username+password stored).
+    Maps to 'auth_required', exit 1."""
+
+
+class ApiError(Exception):
+    """A non-2xx HTTP response from the connector-builder API.
+    Maps to 'api_error', exit 1. Carries status + the server's detail."""
+
+    def __init__(self, status_code: int, path: str, detail: str = "",
+                 details: dict[str, Any] | None = None):
+        self.status_code = status_code
+        self.path = path
+        self.detail = (detail or "")[:500]
+        self.details = details or {}
+        self.details.setdefault("status_code", status_code)
+        self.details.setdefault("path", path)
+        super().__init__(f"{status_code} on {path}: {self.detail}")
+
+
+def classify(exc: Exception) -> tuple[str, str, dict, int]:
+    if isinstance(exc, UsageError):
+        return "invalid_argument", str(exc) or "invalid argument", {}, 2
+    if isinstance(exc, CredentialError):
+        return "auth_required", str(exc), {}, 1
+    if isinstance(exc, ApiError):
+        code = "auth_failed" if exc.status_code in (401, 403) else "api_error"
+        return code, str(exc), exc.details, 1
+    return "error", str(exc) or exc.__class__.__name__, {"type": type(exc).__name__}, 1

procesio_cli/tools/connector-builder/gen_manifest.py

@@ -0,0 +1,142 @@
+"""Generate tool.yaml from the live ACTIONS dict (single source of truth).
+
+Introspects each action's argparse to emit the manifest's actions/args, so the
+manifest can never drift from the dispatcher (the manifest-sync test enforces the
+same invariant). Run after adding/changing an action:
+
+    .venv/Scripts/python tools/connector-builder/gen_manifest.py
+
+Header metadata (name/description/secrets/routing) is curated here.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+import yaml
+
+TOOL_ROOT = Path(__file__).resolve().parent
+FRAMEWORK_ROOT = TOOL_ROOT.parents[1]
+for _p in (str(TOOL_ROOT), str(FRAMEWORK_ROOT)):
+    if _p not in sys.path:
+        sys.path.insert(0, _p)
+
+import main  # noqa: E402
+
+DESCRIPTION = (
+    "AI Connector Builder (connector-builder.procesio.app): turn API documentation "
+    "into a compiled PROCESIO Custom Action .nupkg connector via an 8-stage LLM "
+    "pipeline (gather -> clarify -> plan -> generate -> validate -> compile -> fix "
+    "-> deliver). Drive the whole build lifecycle, read/write generated files, "
+    "download the .nupkg artifact (to upload to PROCESIO for live testing), inspect "
+    "logs/telemetry, and edit the builder's own knowledge base (prompts, spec "
+    "modules, examples, validation rules). Two auth modes, both -> Bearer token: an "
+    "acb_ API key, or username/password via /auth/login."
+)
+
+SECRETS = [
+    {"name": "api-key",
+     "description": "Connector Builder API key (acb_...). Used verbatim as the bearer token."},
+    {"name": "username",
+     "description": "Login email for username/password auth mode (e.g. user@example.com)."},
+    {"name": "password",
+     "description": "Login password for username/password auth mode (-> POST /auth/login -> JWT)."},
+]
+
+ROUTING = {
+    "triggers": [
+        "build a PROCESIO custom action / connector from API docs",
+        "generate a .nupkg connector for PROCESIO from documentation",
+        "create / run / drive an AI Connector Builder build",
+        "approve / revise the plan / regenerate files / download the connector artifact",
+        "edit the connector builder's prompts / spec modules / examples (improve generation)",
+    ],
+    "primary_action": "create-build",
+    "example": ("connector-builder create-build --api-url <docs-url> --user-requirements '...'   "
+                "(then gather / answer / approve-plan / approve-generate / download-artifact)"),
+}
+
+# Per-action one-line output hints (optional; advisory only).
+OUTPUT_SCHEMAS = {
+    "check": '{ "ok": true, "email": "...", "role": "admin", "base_url": "..." }',
+    "create-build": '{ "id": "uuid", "status": "pending", ... }',
+    "gather": '{ "status": "clarifying", "api_profile": {...}, "clarification_questions": [...] }',
+    "answer": '{ "status": "planning", "implementation_plan": {...} }',
+    "approve-plan": '{ "status": "generating", "step_status": "waiting_user", "generated_files": {...} }',
+    "approve-generate": '{ "status": "approved", "build_id": "uuid" }',
+    "download-artifact": '{ "out": "...", "bytes": N, "filename": "..._PROCESIO.API.nupkg" }',
+    "list-builds": '{ "builds": [...], "total": N, "page": 1, "per_page": 20 }',
+}
+
+# argparse type object -> manifest type string.
+_TYPE_MAP = {int: "integer", float: "number"}
+
+
+def _arg_type(action: argparse.Action) -> str:
+    if isinstance(action, (argparse._StoreTrueAction, argparse._StoreFalseAction)):
+        return "boolean"
+    t = getattr(action, "type", None)
+    if t in _TYPE_MAP:
+        return _TYPE_MAP[t]
+    # The --success / boolean-lambda flags parse to bool.
+    if callable(t) and getattr(t, "__name__", "") == "<lambda>":
+        return "boolean"
+    return "string"
+
+
+def _args_for(defn) -> list[dict]:
+    parser = argparse.ArgumentParser()
+    defn.add_args(parser)
+    out: list[dict] = []
+    for action in parser._actions:
+        opts = [o for o in action.option_strings if o.startswith("--") and o != "--help"]
+        if not opts:
+            continue
+        name = opts[0][2:]
+        entry: dict = {"name": name, "type": _arg_type(action)}
+        if getattr(action, "required", False):
+            entry["required"] = True
+        if action.help:
+            entry["description"] = action.help
+        out.append(entry)
+    return out
+
+
+def build_manifest() -> dict:
+    actions = []
+    for name in sorted(main.ACTIONS):
+        defn = main.ACTIONS[name]
+        entry: dict = {"name": name, "description": defn.description}
+        args = _args_for(defn)
+        if args:
+            entry["args"] = args
+        if name in OUTPUT_SCHEMAS:
+            entry["output_schema"] = OUTPUT_SCHEMAS[name]
+        actions.append(entry)
+    return {
+        "name": "connector-builder",
+        "description": DESCRIPTION,
+        "version": "0.2.0",
+        "runtime": "python",
+        "entrypoint": "main.py",
+        "secrets": SECRETS,
+        "routing": ROUTING,
+        "actions": actions,
+    }
+
+
+def main_gen() -> None:
+    manifest = build_manifest()
+    text = yaml.safe_dump(manifest, sort_keys=False, allow_unicode=True, width=100)
+    out = TOOL_ROOT / "tool.yaml"
+    header = ("# GENERATED by gen_manifest.py from the live ACTIONS dict — do not\n"
+              "# hand-edit actions/args; edit the handlers + header consts and rerun:\n"
+              "#   .venv/Scripts/python tools/connector-builder/gen_manifest.py\n")
+    out.write_text(header + text, encoding="utf-8")
+    print(f"wrote {out} ({len(text)} bytes, {len(manifest['actions'])} actions)",
+          file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main_gen()

procesio_cli/tools/connector-builder/handlers/__init__.py

@@ -0,0 +1 @@
+"""connector-builder action handlers (imported by BARE name from main.py)."""

procesio_cli/tools/connector-builder/handlers/admin.py

@@ -0,0 +1,182 @@
+"""Admin actions (admin role): pipeline/provider/compilation config, the
+knowledge base (prompts, spec_modules, examples, validation_rules, clarification),
+the compiler self-test, users, and issue cases.
+
+The knowledge actions are how you improve the BUILDER ITSELF — editing the prompt
+templates, connector spec modules, and few-shot examples changes how every future
+build generates code. That is the deepest feedback loop after a PROCESIO test.
+"""
+from __future__ import annotations
+
+import argparse
+
+from actiondef import ActionDef
+from errors import UsageError
+from handlers.common import add_pagination, load_text_or_file, parse_json
+
+_CONFIG_KINDS = ("pipeline", "providers", "compilation", "maintenance")
+_MODULE_TYPES = ("prompt", "spec_module", "example", "validation_rule", "clarification")
+
+
+# -- config ------------------------------------------------------------------
+
+def get_config(client, args) -> dict:
+    if args.which not in _CONFIG_KINDS:
+        raise UsageError(f"--which must be one of {', '.join(_CONFIG_KINDS)}")
+    suffix = "/config/maintenance" if args.which == "maintenance" else f"/config/{args.which}"
+    return client.get(f"/admin{suffix}")
+
+
+def update_config(client, args) -> dict:
+    if args.which not in _CONFIG_KINDS:
+        raise UsageError(f"--which must be one of {', '.join(_CONFIG_KINDS)}")
+    raw = load_text_or_file(args.data, args.data_file, what="data")
+    if raw is None:
+        raise UsageError("provide --data (JSON) or --data-file")
+    body = parse_json(raw, what="data", expect=dict)
+    suffix = "/config/maintenance" if args.which == "maintenance" else f"/config/{args.which}"
+    return client.put(f"/admin{suffix}", body)
+
+
+def reload_config(client, args) -> dict:
+    return client.post("/admin/config/reload")
+
+
+# -- knowledge ---------------------------------------------------------------
+
+def knowledge_list(client, args) -> dict:
+    _check_module_type(args.module_type)
+    return {"module_type": args.module_type,
+            "modules": client.get(f"/admin/knowledge/{args.module_type}")}
+
+
+def knowledge_get(client, args) -> dict:
+    _check_module_type(args.module_type)
+    return client.get(f"/admin/knowledge/{args.module_type}/{args.name}")
+
+
+def knowledge_create(client, args) -> dict:
+    _check_module_type(args.module_type)
+    content = load_text_or_file(args.content, args.content_file, what="content")
+    if content is None:
+        raise UsageError("provide --content or --content-file")
+    return client.post(f"/admin/knowledge/{args.module_type}",
+                       {"name": args.name, "content": content})
+
+
+def knowledge_update(client, args) -> dict:
+    _check_module_type(args.module_type)
+    content = load_text_or_file(args.content, args.content_file, what="content")
+    if content is None:
+        raise UsageError("provide --content or --content-file")
+    return client.put(f"/admin/knowledge/{args.module_type}/{args.name}",
+                      {"content": content})
+
+
+def knowledge_delete(client, args) -> dict:
+    _check_module_type(args.module_type)
+    return client.delete(f"/admin/knowledge/{args.module_type}/{args.name}")
+
+
+def _check_module_type(mt: str) -> None:
+    if mt not in _MODULE_TYPES:
+        raise UsageError(f"--module-type must be one of {', '.join(_MODULE_TYPES)}")
+
+
+# -- selftest / users / issues ----------------------------------------------
+
+def build_selftest(client, args) -> dict:
+    """POST /admin/build-selftest — end-to-end compiler health (trivial 2-file C#)."""
+    return client.post("/admin/build-selftest")
+
+
+def list_users(client, args) -> dict:
+    return {"users": client.get("/admin/users")}
+
+
+def list_issues(client, args) -> dict:
+    params = {"page": args.page, "per_page": args.per_page}
+    for f in ("stage", "severity", "status", "build_id", "error_category", "search"):
+        v = getattr(args, f)
+        if v:
+            params[f] = v
+    return client.get("/admin/issues", params)
+
+
+def get_issue(client, args) -> dict:
+    return client.get(f"/admin/issues/{args.id}")
+
+
+# -- argparse ----------------------------------------------------------------
+
+def _get_config_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--which", required=True,
+                   help="pipeline | providers | compilation | maintenance")
+
+
+def _update_config_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--which", required=True,
+                   help="pipeline | providers | compilation | maintenance")
+    p.add_argument("--data", help="Config payload as JSON (inline)")
+    p.add_argument("--data-file", dest="data_file", help="Read JSON payload from path")
+
+
+def _knowledge_list_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--module-type", dest="module_type", required=True,
+                   help=f"one of {', '.join(_MODULE_TYPES)}")
+
+
+def _knowledge_get_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--module-type", dest="module_type", required=True,
+                   help=f"one of {', '.join(_MODULE_TYPES)}")
+    p.add_argument("--name", required=True, help="Module name, e.g. clarify.md")
+
+
+def _knowledge_write_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--module-type", dest="module_type", required=True,
+                   help=f"one of {', '.join(_MODULE_TYPES)}")
+    p.add_argument("--name", required=True, help="Module name, e.g. clarify.md")
+    p.add_argument("--content", help="Module content (inline)")
+    p.add_argument("--content-file", dest="content_file",
+                   help="Read module content from path")
+
+
+def _list_issues_args(p: argparse.ArgumentParser) -> None:
+    add_pagination(p)
+    p.add_argument("--stage", help="Pipeline stage filter")
+    p.add_argument("--severity", help="Severity filter")
+    p.add_argument("--status", help="Status filter")
+    p.add_argument("--build-id", dest="build_id", help="Filter by build")
+    p.add_argument("--error-category", dest="error_category", help="Error category filter")
+    p.add_argument("--search", help="Free-text search")
+
+
+def _get_issue_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--id", required=True, help="Issue case id")
+
+
+ACTIONS: dict[str, ActionDef] = {
+    "get-config": ActionDef(get_config, _get_config_args,
+                            description="Read a config block (pipeline/providers/...)."),
+    "update-config": ActionDef(update_config, _update_config_args,
+                               description="Update a config block from JSON."),
+    "reload-config": ActionDef(reload_config,
+                               description="Reload all YAML config + knowledge cache."),
+    "knowledge-list": ActionDef(knowledge_list, _knowledge_list_args,
+                                description="List knowledge modules of a type."),
+    "knowledge-get": ActionDef(knowledge_get, _knowledge_get_args,
+                               description="Get one knowledge module's content."),
+    "knowledge-create": ActionDef(knowledge_create, _knowledge_write_args,
+                                  description="Create a new knowledge module."),
+    "knowledge-update": ActionDef(knowledge_update, _knowledge_write_args,
+                                  description="Update an existing knowledge module."),
+    "knowledge-delete": ActionDef(knowledge_delete, _knowledge_get_args,
+                                  description="Delete a knowledge module."),
+    "build-selftest": ActionDef(build_selftest,
+                                description="Compiler health self-test (trivial C#)."),
+    "list-users": ActionDef(list_users, description="List all users (admin)."),
+    "list-issues": ActionDef(list_issues, _list_issues_args,
+                             description="List issue cases (failures), filterable."),
+    "get-issue": ActionDef(get_issue, _get_issue_args,
+                           description="Full issue-case detail incl. snapshots."),
+}