procesio-cli 0.1.1__py3-none-any.whl

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

@@ -0,0 +1,74 @@
+"""Auth / identity actions: connectivity, current user, API-key + LLM-key mgmt."""
+from __future__ import annotations
+
+import argparse
+
+from actiondef import ActionDef
+
+
+def check(client, args) -> dict:
+    """Connectivity + auth probe via GET /auth/me."""
+    me = client.get("/auth/me")
+    return {"ok": True, "email": me.get("email"), "role": me.get("role"),
+            "has_llm_key": me.get("has_llm_key"), "base_url": client.base_url}
+
+
+def whoami(client, args) -> dict:
+    """Full GET /auth/me for the authenticated principal."""
+    return client.get("/auth/me")
+
+
+def list_api_keys(client, args) -> dict:
+    keys = client.get("/auth/api-keys")
+    return {"api_keys": keys, "count": len(keys) if isinstance(keys, list) else None}
+
+
+def create_api_key(client, args) -> dict:
+    """POST /auth/api-keys — returns full_key ONCE (store it immediately)."""
+    return client.post("/auth/api-keys", {"name": args.name})
+
+
+def revoke_api_key(client, args) -> dict:
+    return client.delete(f"/auth/api-keys/{args.id}")
+
+
+def set_llm_key(client, args) -> dict:
+    """POST /auth/llm-key — set the LLM provider key used to power builds."""
+    return client.post("/auth/llm-key",
+                       {"api_key": args.api_key, "provider": args.provider})
+
+
+def delete_llm_key(client, args) -> dict:
+    return client.delete("/auth/llm-key")
+
+
+def _create_api_key_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--name", required=True, help="Label for the new API key")
+
+
+def _revoke_api_key_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--id", required=True, help="API key id to revoke")
+
+
+def _set_llm_key_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--api-key", dest="api_key", required=True,
+                   help="LLM provider API key (e.g. sk-ant-... / sk-...)")
+    p.add_argument("--provider", required=True,
+                   help="Provider id, e.g. anthropic | openai")
+
+
+ACTIONS: dict[str, ActionDef] = {
+    "check": ActionDef(check, description="Connectivity + auth probe (GET /auth/me)."),
+    "whoami": ActionDef(whoami, description="Full current-user record (GET /auth/me)."),
+    "list-api-keys": ActionDef(list_api_keys, description="List your API keys."),
+    "create-api-key": ActionDef(
+        create_api_key, _create_api_key_args,
+        description="Create an API key (full_key shown only once)."),
+    "revoke-api-key": ActionDef(
+        revoke_api_key, _revoke_api_key_args, description="Revoke an API key by id."),
+    "set-llm-key": ActionDef(
+        set_llm_key, _set_llm_key_args,
+        description="Set the LLM provider key that powers builds."),
+    "delete-llm-key": ActionDef(
+        delete_llm_key, description="Remove the stored LLM provider key."),
+}

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

@@ -0,0 +1,396 @@
+"""Build lifecycle actions — the heart of the connector pipeline.
+
+Stage flow (documentation/04-PIPELINE-ENGINE.md):
+  create -> gather (GATHER+CLARIFY) -> answer (->PLAN) -> approve-plan (->GENERATE,
+  pauses) -> approve-generate (->VALIDATE/COMPILE/FIX/DELIVER) -> artifact (.nupkg).
+Feedback loops: revise-plan, regenerate / regenerate-file, validate-*, retry,
+override-stage, post-message.
+"""
+from __future__ import annotations
+
+import argparse
+
+from actiondef import ActionDef
+from client import build_is_settled
+from errors import UsageError
+from handlers.common import (add_build_id, add_pagination, add_wait_args,
+                             parse_json, run_with_optional_wait)
+
+
+# --------------------------------------------------------------------------- #
+# Read / list
+# --------------------------------------------------------------------------- #
+
+def list_builds(client, args) -> dict:
+    params = {"page": args.page, "per_page": args.per_page}
+    if args.status:
+        params["status"] = args.status
+    if args.archive_status:
+        params["archive_status"] = args.archive_status
+    if args.created_by:
+        params["created_by"] = args.created_by
+    return client.get("/builds", params)
+
+
+def get_build(client, args) -> dict:
+    return client.get(f"/builds/{args.build_id}")
+
+
+def stage_override_options(client, args) -> dict:
+    return client.get("/builds/stage-override-options")
+
+
+# --------------------------------------------------------------------------- #
+# Create + run
+# --------------------------------------------------------------------------- #
+
+def create_build(client, args) -> dict:
+    body: dict = {}
+    if args.api_url:
+        body["api_url"] = args.api_url
+    if args.api_urls:
+        body["api_urls"] = parse_json(args.api_urls, what="api-urls", expect=list)
+    if args.api_docs_text:
+        body["api_docs_text"] = args.api_docs_text
+    if args.user_requirements:
+        body["user_requirements"] = args.user_requirements
+    if not (body.get("api_url") or body.get("api_urls") or body.get("api_docs_text")):
+        raise UsageError("provide at least one of --api-url / --api-urls / --api-docs-text")
+    return client.post("/builds", body)
+
+
+def start_build(client, args) -> dict:
+    """Launch the FULL pipeline as a background task (no per-stage pauses)."""
+    return client.post(f"/builds/{args.build_id}/start")
+
+
+def gather(client, args) -> dict:
+    """Run GATHER + CLARIFY synchronously; returns api_profile + questions.
+    With --wait, survives the proxy 504 by polling to the clarify pause."""
+    return run_with_optional_wait(
+        client, args.build_id,
+        lambda: client.post(f"/builds/{args.build_id}/gather"), args)
+
+
+def answer(client, args) -> dict:
+    """Submit clarification answers; triggers PLAN. With --wait, polls to the
+    plan-review pause (survives the proxy 504)."""
+    answers = parse_json(args.answers, what="answers", expect=dict) or {}
+    return run_with_optional_wait(
+        client, args.build_id,
+        lambda: client.post(f"/builds/{args.build_id}/answers", {"answers": answers}),
+        args)
+
+
+def approve_plan(client, args) -> dict:
+    """Approve the plan; triggers GENERATE (pauses after generation)."""
+    return client.post(f"/builds/{args.build_id}/approve")
+
+
+def revise_plan(client, args) -> dict:
+    """Send free-text feedback to revise the implementation plan. With --wait,
+    polls back to the plan-review pause (survives the proxy 504)."""
+    return run_with_optional_wait(
+        client, args.build_id,
+        lambda: client.post(f"/builds/{args.build_id}/revise-plan",
+                            {"feedback": args.feedback}), args)
+
+
+def wait_build(client, args) -> dict:
+    """Poll get-build until the build settles (waiting_user or terminal), or
+    only-terminal with --until terminal. Use after approve-generate/retry/
+    start-build to block until compile finishes."""
+    build = client.wait_for_settled(
+        args.build_id, timeout=args.wait_timeout, interval=args.poll_interval,
+        until=args.until)
+    out = dict(build)
+    out["waited"] = True
+    out["settled"] = build_is_settled(build, args.until)
+    return out
+
+
+def approve_generate(client, args) -> dict:
+    """Accept generated files; triggers VALIDATE -> COMPILE -> FIX -> DELIVER."""
+    return client.post(f"/builds/{args.build_id}/generate/approve")
+
+
+def regenerate(client, args) -> dict:
+    """Regenerate with per-file and/or general instructions."""
+    body: dict = {}
+    if args.file_instructions:
+        body["file_instructions"] = parse_json(
+            args.file_instructions, what="file-instructions", expect=dict)
+    if args.step_instructions:
+        body["step_instructions"] = args.step_instructions
+    return client.post(f"/builds/{args.build_id}/generate/regenerate", body)
+
+
+def regenerate_file(client, args) -> dict:
+    return client.post(
+        f"/builds/{args.build_id}/generate/regenerate-file",
+        {"filename": args.filename, "instructions": args.instructions})
+
+
+def validate_autofix(client, args) -> dict:
+    return client.post(f"/builds/{args.build_id}/validate/autofix")
+
+
+def validate_continue(client, args) -> dict:
+    return client.post(f"/builds/{args.build_id}/validate/continue")
+
+
+def validate_return_to_generate(client, args) -> dict:
+    return client.post(f"/builds/{args.build_id}/validate/return-to-generate")
+
+
+def retry(client, args) -> dict:
+    body: dict = {}
+    if args.from_step is not None:
+        body["from_step"] = args.from_step
+    return client.post(f"/builds/{args.build_id}/retry", body)
+
+
+def override_stage(client, args) -> dict:
+    return client.post(
+        f"/builds/{args.build_id}/override-stage",
+        {"target_step": args.target_step, "target_status": args.target_status})
+
+
+def reset(client, args) -> dict:
+    return client.post(f"/builds/{args.build_id}/reset")
+
+
+def revise(client, args) -> dict:
+    return client.post(f"/builds/{args.build_id}/revise")
+
+
+def set_version(client, args) -> dict:
+    return client.patch(
+        f"/builds/{args.build_id}/version",
+        {"major": args.major, "minor": args.minor, "patch": args.patch})
+
+
+def archive(client, args) -> dict:
+    return client.patch(f"/builds/{args.build_id}/archive")
+
+
+def unarchive(client, args) -> dict:
+    return client.patch(f"/builds/{args.build_id}/unarchive")
+
+
+# --------------------------------------------------------------------------- #
+# Logs / events / messages
+# --------------------------------------------------------------------------- #
+
+def logs(client, args) -> dict:
+    params = {"page": args.page, "page_size": args.page_size}
+    for f in ("stage", "model", "model_search", "after", "before"):
+        v = getattr(args, f)
+        if v:
+            params[f] = v
+    if args.success is not None:
+        params["success"] = str(args.success).lower()
+    return client.get(f"/builds/{args.build_id}/logs", params)
+
+
+def events(client, args) -> dict:
+    params = {"page": args.page, "per_page": args.per_page}
+    for f in ("step", "level", "event_type"):
+        v = getattr(args, f)
+        if v:
+            params[f] = v
+    return client.get(f"/builds/{args.build_id}/events", params)
+
+
+def list_messages(client, args) -> dict:
+    params = {"page": args.page, "per_page": args.per_page}
+    if args.step:
+        params["step"] = args.step
+    return client.get(f"/builds/{args.build_id}/messages", params)
+
+
+def post_message(client, args) -> dict:
+    return client.post(f"/builds/{args.build_id}/messages",
+                       {"step": args.step, "content": args.content})
+
+
+# --------------------------------------------------------------------------- #
+# argparse
+# --------------------------------------------------------------------------- #
+
+def _list_builds_args(p: argparse.ArgumentParser) -> None:
+    add_pagination(p)
+    p.add_argument("--status", help="Filter by pipeline status")
+    p.add_argument("--archive-status", dest="archive_status",
+                   help="active | archived | all")
+    p.add_argument("--created-by", dest="created_by",
+                   help="UUID CSV (admin only)")
+
+
+def _create_build_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--api-url", dest="api_url", help="Single API docs URL")
+    p.add_argument("--api-urls", dest="api_urls", help="JSON array of doc URLs")
+    p.add_argument("--api-docs-text", dest="api_docs_text",
+                   help="Pasted API documentation text")
+    p.add_argument("--user-requirements", dest="user_requirements",
+                   help="What the connector should do")
+
+
+def _gather_args(p: argparse.ArgumentParser) -> None:
+    add_build_id(p)
+    add_wait_args(p)
+
+
+def _answer_args(p: argparse.ArgumentParser) -> None:
+    add_build_id(p)
+    p.add_argument("--answers", required=True,
+                   help='JSON object {"q1":"a1","q2":"a2"}')
+    add_wait_args(p)
+
+
+def _revise_plan_args(p: argparse.ArgumentParser) -> None:
+    add_build_id(p)
+    p.add_argument("--feedback", required=True, help="Plan revision feedback")
+    add_wait_args(p)
+
+
+def _wait_build_args(p: argparse.ArgumentParser) -> None:
+    add_build_id(p)
+    p.add_argument("--wait-timeout", dest="wait_timeout", type=int, default=600,
+                   help="Max seconds to poll (default 600)")
+    p.add_argument("--poll-interval", dest="poll_interval", type=int, default=8,
+                   help="Seconds between polls (default 8)")
+    p.add_argument("--until", default="settled",
+                   help="settled (waiting_user or terminal) | terminal (only completed/failed/...)")
+
+
+def _regenerate_args(p: argparse.ArgumentParser) -> None:
+    add_build_id(p)
+    p.add_argument("--file-instructions", dest="file_instructions",
+                   help='JSON object {"File.cs":"instructions"}')
+    p.add_argument("--step-instructions", dest="step_instructions",
+                   help="General feedback for the whole generation step")
+
+
+def _regenerate_file_args(p: argparse.ArgumentParser) -> None:
+    add_build_id(p)
+    p.add_argument("--filename", required=True, help="File to regenerate")
+    p.add_argument("--instructions", required=True, help="Instructions for the file")
+
+
+def _retry_args(p: argparse.ArgumentParser) -> None:
+    add_build_id(p)
+    p.add_argument("--from-step", dest="from_step", type=int,
+                   help="Stage number to retry from (default: last failed)")
+
+
+def _override_stage_args(p: argparse.ArgumentParser) -> None:
+    add_build_id(p)
+    p.add_argument("--target-step", dest="target_step", type=int, required=True,
+                   help="Target stage 1-8")
+    p.add_argument("--target-status", dest="target_status", required=True,
+                   help="running | waiting_user")
+
+
+def _set_version_args(p: argparse.ArgumentParser) -> None:
+    add_build_id(p)
+    p.add_argument("--major", type=int, required=True)
+    p.add_argument("--minor", type=int, required=True)
+    p.add_argument("--patch", type=int, required=True)
+
+
+def _post_message_args(p: argparse.ArgumentParser) -> None:
+    add_build_id(p)
+    p.add_argument("--step", required=True, help="Pipeline step, e.g. clarify | plan")
+    p.add_argument("--content", required=True, help="Message text")
+
+
+def _logs_args(p: argparse.ArgumentParser) -> None:
+    add_build_id(p)
+    p.add_argument("--page", type=int, default=1)
+    p.add_argument("--page-size", dest="page_size", type=int, default=100,
+                   help="Max 500")
+    p.add_argument("--stage", help="Comma-separated stage names")
+    p.add_argument("--success", type=lambda v: v.lower() in ("1", "true", "yes"),
+                   default=None, help="Filter by success true/false")
+    p.add_argument("--model", help="Comma-separated model names")
+    p.add_argument("--model-search", dest="model_search", help="Substring model search")
+    p.add_argument("--after", help="ISO datetime lower bound")
+    p.add_argument("--before", help="ISO datetime upper bound")
+
+
+def _events_args(p: argparse.ArgumentParser) -> None:
+    add_build_id(p)
+    add_pagination(p, 100)
+    p.add_argument("--step", help="Filter by step")
+    p.add_argument("--level", help="Filter by level")
+    p.add_argument("--event-type", dest="event_type", help="Filter by event type")
+
+
+def _messages_args(p: argparse.ArgumentParser) -> None:
+    add_build_id(p)
+    add_pagination(p, 100)
+    p.add_argument("--step", help="Filter by step")
+
+
+def _build_id_only(p: argparse.ArgumentParser) -> None:
+    add_build_id(p)
+
+
+ACTIONS: dict[str, ActionDef] = {
+    "list-builds": ActionDef(list_builds, _list_builds_args,
+                             description="List builds (paginated, filterable)."),
+    "get-build": ActionDef(get_build, _build_id_only,
+                           description="Full build detail (all JSONB fields)."),
+    "stage-override-options": ActionDef(
+        stage_override_options,
+        description="Valid stage-override targets for override-stage."),
+    "create-build": ActionDef(create_build, _create_build_args,
+                              description="Create a build from URL(s) / pasted docs."),
+    "start-build": ActionDef(start_build, _build_id_only,
+                             description="Run the FULL pipeline as a background task."),
+    "gather": ActionDef(gather, _gather_args,
+                        description="Run GATHER+CLARIFY (profile+questions); --wait survives the 504."),
+    "wait-build": ActionDef(wait_build, _wait_build_args,
+                            description="Poll get-build until settled/terminal (use after approve-generate/retry)."),
+    "answer": ActionDef(answer, _answer_args,
+                        description="Submit clarification answers; triggers PLAN."),
+    "approve-plan": ActionDef(approve_plan, _build_id_only,
+                              description="Approve plan; triggers GENERATE (then pauses)."),
+    "revise-plan": ActionDef(revise_plan, _revise_plan_args,
+                             description="Revise the plan with free-text feedback."),
+    "approve-generate": ActionDef(
+        approve_generate, _build_id_only,
+        description="Accept generated files; runs VALIDATE->COMPILE->FIX->DELIVER."),
+    "regenerate": ActionDef(regenerate, _regenerate_args,
+                            description="Regenerate files with per-file/general instructions."),
+    "regenerate-file": ActionDef(regenerate_file, _regenerate_file_args,
+                                 description="Regenerate a single file with instructions."),
+    "validate-autofix": ActionDef(validate_autofix, _build_id_only,
+                                  description="Auto-fix validation findings."),
+    "validate-continue": ActionDef(validate_continue, _build_id_only,
+                                   description="Continue past validation to COMPILE."),
+    "validate-return-to-generate": ActionDef(
+        validate_return_to_generate, _build_id_only,
+        description="Return from VALIDATE back to GENERATE."),
+    "retry": ActionDef(retry, _retry_args,
+                       description="Retry the pipeline from a step (or last failed)."),
+    "override-stage": ActionDef(override_stage, _override_stage_args,
+                                description="Jump the build to a target step/status."),
+    "reset": ActionDef(reset, _build_id_only,
+                       description="Reset a failed/clarifying/planning build to pending."),
+    "revise": ActionDef(revise, _build_id_only,
+                        description="Re-open a COMPLETED build to the generate pause for a small fix (then regenerate-file + approve-generate); bumps the version."),
+    "set-version": ActionDef(set_version, _set_version_args,
+                             description="Set Major.Minor.Patch (at Plan/waiting_user)."),
+    "archive": ActionDef(archive, _build_id_only, description="Archive a build (admin)."),
+    "unarchive": ActionDef(unarchive, _build_id_only,
+                           description="Unarchive a build (admin)."),
+    "logs": ActionDef(logs, _logs_args,
+                      description="Per-build stage logs (model/cost/token breakdown)."),
+    "events": ActionDef(events, _events_args, description="Per-build pipeline events."),
+    "list-messages": ActionDef(list_messages, _messages_args,
+                               description="Chat/system messages for a build."),
+    "post-message": ActionDef(post_message, _post_message_args,
+                              description="Post a chat message to a build/step."),
+}

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

@@ -0,0 +1,104 @@
+"""Shared argparse + JSON-parsing helpers for connector-builder handlers."""
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any, Callable
+
+import requests
+
+from client import build_is_settled
+from errors import ApiError, UsageError
+
+
+def parse_json(raw: str | None, *, what: str = "value", expect: type | None = None) -> Any:
+    """Parse a JSON CLI argument; raise UsageError with a helpful message."""
+    if raw is None:
+        return None
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as e:
+        raise UsageError(f"--{what} must be valid JSON, got: {e}") from e
+    if expect is not None and not isinstance(data, expect):
+        names = expect.__name__ if isinstance(expect, type) else " or ".join(
+            t.__name__ for t in expect)
+        raise UsageError(f"--{what} must be a JSON {names}")
+    return data
+
+
+def load_text_or_file(inline: str | None, file_path: str | None, *, what: str) -> str | None:
+    """Return inline text, or read it from a file (file wins precedence check is
+    XOR-ish: at most one). Used for content / config payloads that may be large."""
+    if inline is not None and file_path is not None:
+        raise UsageError(f"pass either --{what} or --{what}-file, not both")
+    if file_path is not None:
+        p = Path(file_path)
+        if not p.is_file():
+            raise UsageError(f"--{what}-file not found: {file_path}")
+        return p.read_text(encoding="utf-8")
+    return inline
+
+
+def add_build_id(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--build-id", dest="build_id", required=True,
+                   help="Build UUID")
+
+
+def add_pagination(p: argparse.ArgumentParser, default_per_page: int = 20) -> None:
+    p.add_argument("--page", type=int, default=1, help="Page number (default 1)")
+    p.add_argument("--per-page", dest="per_page", type=int, default=default_per_page,
+                   help=f"Items per page (default {default_per_page})")
+
+
+def add_wait_args(p: argparse.ArgumentParser) -> None:
+    """Opt-in polling for a synchronous LLM stage that 504s at the proxy but
+    completes server-side."""
+    p.add_argument("--wait", action="store_true",
+                   help="Poll get-build until the stage settles (survives the proxy 504)")
+    p.add_argument("--wait-timeout", dest="wait_timeout", type=int, default=600,
+                   help="Max seconds to poll when --wait (default 600)")
+    p.add_argument("--poll-interval", dest="poll_interval", type=int, default=8,
+                   help="Seconds between polls when --wait (default 8)")
+
+
+# Proxy/gateway statuses that mean "the backend is still working" rather than a
+# real failure — swallow these under --wait and fall through to polling.
+_TRANSIENT_HTTP = {502, 503, 504}
+
+
+def run_with_optional_wait(client, build_id: str, trigger: Callable[[], Any],
+                           args, *, until: str = "settled") -> dict:
+    """Run a stage-triggering call. Without --wait, return its result verbatim.
+    With --wait: record the build's updated_at, fire the trigger (swallowing a
+    502/503/504 or a client-side timeout — the stage keeps running server-side),
+    then poll get-build until settled. Returns the settled build detail plus
+    ``waited``/``settled`` markers (and ``trigger_note`` if the trigger 504'd)."""
+    if not getattr(args, "wait", False):
+        return trigger()
+
+    baseline = None
+    try:
+        baseline = client.get_build(build_id).get("updated_at")
+    except Exception:  # noqa: BLE001 - baseline is best-effort
+        baseline = None
+
+    note = None
+    try:
+        trigger()
+    except ApiError as e:
+        if e.status_code not in _TRANSIENT_HTTP:
+            raise
+        note = f"trigger returned HTTP {e.status_code}; polled for completion"
+    except (requests.exceptions.Timeout, requests.exceptions.ConnectionError):
+        note = "trigger timed out client-side; polled for completion"
+
+    build = client.wait_for_settled(
+        build_id, timeout=args.wait_timeout, interval=args.poll_interval,
+        until=until, baseline_updated_at=baseline)
+    out = dict(build)
+    out["waited"] = True
+    out["settled"] = build_is_settled(build, until)
+    if note:
+        out["trigger_note"] = note
+    return out

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

@@ -0,0 +1,111 @@
+"""Generated-file + artifact actions: versions, content read/write, downloads.
+
+The compiled `.nupkg` (download-artifact) is the bridge to PROCESIO: hand it to
+`procesio customaction-upload --file <nupkg>` to install the connector for live
+testing.
+"""
+from __future__ import annotations
+
+import argparse
+
+from actiondef import ActionDef
+from errors import UsageError
+from handlers.common import add_build_id, load_text_or_file
+
+
+def list_file_versions(client, args) -> dict:
+    return client.get(f"/builds/{args.build_id}/files/versions")
+
+
+def get_file_version(client, args) -> dict:
+    return client.get(
+        f"/builds/{args.build_id}/files/{args.filename}/versions/{args.version}")
+
+
+def update_file(client, args) -> dict:
+    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"/builds/{args.build_id}/files/{args.filename}",
+                      {"content": content})
+
+
+def set_file_instructions(client, args) -> dict:
+    return client.put(
+        f"/builds/{args.build_id}/files/{args.filename}/instructions",
+        {"instructions": args.instructions})
+
+
+def download_file(client, args) -> dict:
+    return client.download(
+        f"/builds/{args.build_id}/files/{args.filename}/download", args.out)
+
+
+def download_all(client, args) -> dict:
+    return client.download(f"/builds/{args.build_id}/files/download-all", args.out)
+
+
+def download_artifact(client, args) -> dict:
+    """Download the compiled .nupkg (or .zip fallback). This is the package you
+    upload to PROCESIO via `procesio customaction-upload`."""
+    return client.download(f"/builds/{args.build_id}/artifact", args.out)
+
+
+def _versions_args(p: argparse.ArgumentParser) -> None:
+    add_build_id(p)
+
+
+def _get_file_version_args(p: argparse.ArgumentParser) -> None:
+    add_build_id(p)
+    p.add_argument("--filename", required=True)
+    p.add_argument("--version", required=True, help="Version number")
+
+
+def _update_file_args(p: argparse.ArgumentParser) -> None:
+    add_build_id(p)
+    p.add_argument("--filename", required=True)
+    p.add_argument("--content", help="New file content (inline)")
+    p.add_argument("--content-file", dest="content_file",
+                   help="Read new content from this path")
+
+
+def _set_file_instructions_args(p: argparse.ArgumentParser) -> None:
+    add_build_id(p)
+    p.add_argument("--filename", required=True)
+    p.add_argument("--instructions", required=True)
+
+
+def _download_file_args(p: argparse.ArgumentParser) -> None:
+    add_build_id(p)
+    p.add_argument("--filename", required=True)
+    p.add_argument("--out", required=True, help="Output file path")
+
+
+def _download_target_args(p: argparse.ArgumentParser) -> None:
+    add_build_id(p)
+    p.add_argument("--out", required=True, help="Output file path")
+
+
+ACTIONS: dict[str, ActionDef] = {
+    "list-file-versions": ActionDef(
+        list_file_versions, _versions_args,
+        description="Version metadata for every file in a build (no content)."),
+    "get-file-version": ActionDef(
+        get_file_version, _get_file_version_args,
+        description="Full content of one file at a specific version."),
+    "update-file": ActionDef(
+        update_file, _update_file_args,
+        description="Overwrite a file's content (inline or from --content-file)."),
+    "set-file-instructions": ActionDef(
+        set_file_instructions, _set_file_instructions_args,
+        description="Save per-file regeneration instructions."),
+    "download-file": ActionDef(
+        download_file, _download_file_args,
+        description="Download one generated file to --out."),
+    "download-all": ActionDef(
+        download_all, _download_target_args,
+        description="Download all generated files as a zip to --out."),
+    "download-artifact": ActionDef(
+        download_artifact, _download_target_args,
+        description="Download the compiled .nupkg to --out (upload to PROCESIO)."),
+}