failproofai 1.0.1 → 1.0.2-beta.0

package/.next/standalone/fp-cloud-cli/README.md

@@ -0,0 +1,259 @@
+# FailproofAI Cloud CLI (`fp`)
+
+A command-line client for the **FailproofAI Cloud** API. It lets a developer —
+or the coding agent working alongside them — authenticate and query agent
+sessions, event logs, and evaluations from the terminal, with a `--json` flag on
+every command for scripting.
+
+> **The package is `fp-cloud-cli`; the command is `fp`.** They differ because `fp` was
+> already taken on PyPI. This is also distinct from `failproofai` on npm, which is
+> the Enforcement CLI — that one runs inside the agent loop and decides what an
+> agent may do; this one reads back what it did.
+
+## Install
+
+```bash
+pipx install fp-cloud-cli      # recommended (isolated)
+# or: uv tool install fp-cloud-cli  /  pip install fp-cloud-cli
+```
+
+Then the command is `fp`:
+
+```bash
+fp --version
+fp help
+```
+
+For development in this repo:
+
+```bash
+cd fp-cloud-cli
+uv sync --extra dev
+uv run fp --help
+```
+
+## Authentication
+
+The CLI talks to your dashboard (set `--base-url` or `FP_DASHBOARD_URL`) and logs in with
+an emailed one-time code:
+
+```bash
+fp login --email you@example.com
+# enter the 6-digit code; the session is stored in
+# ~/.failproofai/fpcli/cli-auth.json (mode 0600)
+fp whoami
+fp logout
+```
+
+Sessions expire (24h by default); re-run `fp login` when prompted.
+
+## Working across orgs (multi-tenant)
+
+Your account can belong to more than one org. The active org is chosen **at login** and saved:
+
+```bash
+fp login --org acme              # pick the tenant at login (saved for later commands)
+fp orgs list                     # your orgs + your role in each (active one marked)
+fp orgs switch globex            # switch the active org (pass a slug…)
+fp orgs switch                   # …or omit it to pick from a list (in a terminal)
+fp orgs current                  # which org you're acting as right now (identity card)
+fp orgs perms                    # your permissions in the active org (grouped by resource)
+fp --org globex sessions         # override for a single command
+```
+
+If you belong to exactly one org it's selected automatically. If you belong to several, you
+pick at login (or with `orgs switch`); pass `--org` to choose non-interactively. A slug you
+can't access (non-existent, or not yours) is rejected rather than saved. The active org is
+sent as the `X-AgentEye-Org` header on every request, and your permissions are resolved per
+org. (All tenant commands live under one group: `orgs list` / `orgs switch` / `orgs current` /
+`orgs perms`.)
+
+## Commands
+
+**Query & observability**
+
+```text
+fp sessions [--since 24h] [--status error] [--agent-id <id>] [--all]   # runs: time/env/agent/session/status
+fp evals [--score helpfulness:..0.5] [--all]   # eval results + scores
+fp evals --aggregate [--since 7d]              # rolled-up eval health (status mix + per-metric score stats)
+fp events --session-id <id> [--event-type tool_use,tool_result] [--env prod] [--all]
+fp errors [--since 24h] [--error-type TimeoutError] [--all]   # list errored events
+fp errors --aggregate [--since 7d]            # error summary (count + sessions/agents/last seen)
+fp list <thing>                   # discover dropdown values to filter on:
+#   envs · agents · event_types · score_filters · models · hooks · tools · error_types
+```
+
+**Manage your org** (each gated by the matching permission)
+
+```text
+fp keys list|show|create|update|disable|regenerate     # API keys (secret shown once)
+fp users list|show|create|update|disable|enable
+fp settings list|schema|set
+fp alerts list|show|create|update|delete|test
+fp issues list|count|show|ack|assign|resolve|comment-add|comment-list|comment-delete|subscribe|subscribers|unsubscribe|open
+fp audits list|show|create|edit|delete|run|runs|findings|finding    # scheduled audits
+fp audits ack|assign|resolve|dismiss|mute|reopen                    # triage a finding
+fp audits context-show|context-set|context-refresh                  # reference context
+fp usage                                         # org usage for the metering window
+```
+
+**Analytics & assistant**
+
+```text
+fp query list|show|create|update|delete|run|schema   # saved SQL + ad-hoc runner
+fp agent health|models|chats|show|rename|delete|ask
+#   agent models                 → models available for --model (with the default marked)
+#   agent ask "…"                → starts a NEW chat, answers + persists, prints the chat id
+#   agent ask --chat <id> "…"    → continue that chat (shows in the dashboard; 1st Q auto-titles)
+#   agent chats|show <id>|rename <id> --title …|delete <id>   → manage saved chats
+fp version | help
+```
+
+**Mutations are non-interactive-safe.** Create/update/delete prompt for confirmation in a
+terminal, but auto-skip the prompt under `--json` or when stdin isn't a TTY (so scripts/agents
+never hang). Pass `--yes`/`-y` to skip it explicitly. Request bodies can be supplied with
+`--file payload.json` (or `--file -` for stdin) on `alerts` and `settings` — mutually
+exclusive with the discrete flags. `users create`/`update` take only the discrete
+flags (`--permission-set`, `--add`, `--remove`). (Saved-query SQL uses `--sql @file.sql`.)
+
+Every command and subcommand has `--help` / `-h`; `fp -h` documents auth, exit codes, and
+the global options. **Global options go before the command** (`fp --json events`, not
+`fp events --json`).
+
+Add `--json` for machine-readable output, and `--fields` to project just the keys you need:
+
+```bash
+fp --json events --session-id run-001 --all | jq '.events[].payload'
+fp --json sessions --since 7d --fields session_id,status,scores
+```
+
+### Cloud-managed policies
+
+Three commands for the three jobs the dashboard splits across three pages —
+`fp policies` writes a policy version, `fp fleet` decides which machines run it,
+`fp guardrails summary` reports what it actually blocked.
+
+```bash
+fp policies publish no-force-push ./rule.mjs   # path, @path, a pipe, - or a paste
+fp fleet deploy ci-runner-01 --add no-force-push
+fp guardrails summary --since 24h
+```
+
+**A deploy REPLACES a machine's whole policy set.** The server takes the full
+list and does not merge, so `fleet deploy` reads what the machine currently runs,
+applies your `--add`/`--remove`, prints the complete resulting set, and writes
+that. Use `--set` only when you mean "exactly these, drop the rest".
+
+```bash
+fp fleet deploy ci-runner-01 \
+    --add no-force-push \            # keeps its pinned version if already deployed
+    --add prod-guard@1:observe \     # id@version:effect
+    --remove old-rule
+```
+
+Three things worth knowing before you script it:
+
+* A bare `--add` of a policy the machine already runs keeps its **pinned
+  version**. Pass `id@version` to move it — a pin is usually deliberate.
+* The endpoint has no lock. The CLI records the deployment generation it read and
+  **refuses** if the write does not land at exactly one higher, because that means
+  somebody deployed in between and a replace does not merge.
+* The exit code separates your mistake from the server's answer. A malformed ref,
+  `--set` alongside `--add`/`--remove`, or no flags at all is **2**; a ref that
+  parses but names a policy that does not exist is **1**; an unknown machine is
+  **6**. Branch on those rather than on the message.
+
+`fp fleet diff` shows intent versus delivery: a machine can be deployed-to and
+still enforcing an older set until it next polls. It refuses a machine id nobody
+has reported under rather than rendering it as an empty fleet.
+
+These commands are **session-only** (`fp login`). They are absent from the
+versioned API an API key authenticates against, so `--api-key` exits 2 with the
+reason rather than failing at the request.
+
+## Configuration
+
+| Setting | Flag | Env var | Default |
+|---|---|---|---|
+| Dashboard URL | `--base-url` | `FP_DASHBOARD_URL` | `https://app.befailproof.ai` |
+| Active org/tenant | `--org` | `FP_ORG` | chosen at login; saved in `~/.failproofai/fpcli/cli-auth.json` |
+| Session token | `--token` | `FP_TOKEN` | from `~/.failproofai/fpcli/cli-auth.json` |
+| API key (CI) | `--api-key` | `FP_API_KEY` | none; never written to disk |
+| JSON output | `--json` | `FP_JSON` | off |
+| Skip TLS verification | `--insecure` / `--secure` | `FP_INSECURE` | off (saved at login) |
+| Disable usage telemetry | _(none)_ | `FP_ANALYTICS_DISABLED` (or `DO_NOT_TRACK`) | off — [this build sends nothing](#telemetry) |
+
+Precedence is **flag > environment variable > config file > built-in default**. A fresh
+install points at the hosted product with no configuration; set `--base-url` or
+`FP_DASHBOARD_URL` for a self-hosted or dev instance and it is saved after `login`.
+
+The session lives at `~/.failproofai/fpcli/cli-auth.json` (mode `0600`). The directory
+is resolved as `FP_HOME` > `$FAILPROOFAI_HOME/fpcli` > `~/.failproofai/fpcli` — `FP_HOME`
+names the CLI's own directory and is used as-is, so an existing export keeps addressing
+the same place; `FAILPROOFAI_HOME` names the shared home root, so `fpcli/` is appended.
+
+The CLI only ever creates. It will bring `~/.failproofai` into existence on a machine
+that has never run the Enforcement CLI, and leaves a populated one exactly as it found
+it — nothing here removes or rewrites a path it does not own. The file is registered in
+that home's layout (`src/hooks/fp-home.ts`) and classified `user-typed`, which is what
+keeps a layout migration from dropping it.
+
+The Python SDK writes its spool under `$FAILPROOFAI_HOME/custom-agents/events`,
+otherwise `~/.failproofai/custom-agents/events` — it moved onto the shared umbrella in
+the same release that renamed this CLI. `FAILPROOFAI_HOME` relocates it the same way it
+relocates this CLI's own directory; what no longer works is `AGENTEYE_HOME`, and nothing
+moves the spool *off* the umbrella except `configure(base_dir=...)` in the application.
+`failproofaid` still drains `~/.agenteye/events` as well, for SDKs old enough to write
+there.
+
+> **Upgrading from a version that used `~/.fp/cli.json`?** Nothing to do — the old
+> session is adopted on your next command, so you are not signed out. It is copied, not
+> moved, so rolling back to an older `fp` still works; remove `~/.fp/` yourself once you
+> are happy.
+
+For a dashboard with a self-signed or internal TLS certificate, add `--insecure` to skip
+certificate verification (saved at login, so you set it once). This disables protection
+against man-in-the-middle attacks — prefer a valid certificate outside internal/testing use.
+
+## Telemetry
+
+**Telemetry is currently disabled and this build sends nothing.**
+`TELEMETRY_DISABLED` is `True` in `fp_cli/analytics_config.py`: when the analytics
+host is unreachable the send path stalls every command for ~5s — the shutdown flush
+is bounded, but the client build and first connect attempt are not — so it stays off
+until that path is fully non-blocking. Nothing was removed; re-enabling is one
+constant.
+
+The rest of this section describes what it collects **if** it is re-enabled, so you
+can review it in advance rather than discover it in a release note:
+
+- which command ran (including its subcommand, e.g. `keys create`), success/exit
+  status and duration, the **names** of flags used, and a per-action event for
+  mutations (e.g. `api_key_created`, `query_run`) carrying only static names/enums
+  and coarse counts;
+- **no data, URLs, tokens, emails, ids, SQL, key secrets, or query values are ever
+  sent**, and operators are identified only by an opaque id.
+
+`FP_ANALYTICS_DISABLED=1` (or the cross-tool `DO_NOT_TRACK=1`) opts out, and keeps
+working as an opt-out if it is ever switched back on. See
+<https://docs.befailproof.ai/reference/cloud-cli> for the full privacy details.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | Unexpected error (e.g. an unhandled server status) |
+| 2 | Usage error (bad arguments) |
+| 3 | Cannot reach the dashboard |
+| 4 | Not logged in / session expired |
+| 5 | Authenticated but missing permission |
+| 6 | Resource not found |
+
+## Tests
+
+```bash
+cd fp-cloud-cli
+uv run --extra dev pytest
+```
+

package/.next/standalone/fp-cloud-cli/fp_cli/__init__.py

@@ -0,0 +1,10 @@
+"""FailproofAI Cloud CLI — a command-line client for the FailproofAI Cloud API.
+
+The query layer lives in :mod:`fp_cli.client` as pure functions that take a
+``ClientContext`` and return plain dataclasses. They never print and never import
+Typer/Rich, so a future MCP server can wrap them with zero duplication.
+"""
+
+from ._version import __version__
+
+__all__ = ["__version__"]

package/.next/standalone/fp-cloud-cli/fp_cli/__main__.py

@@ -0,0 +1,4 @@
+from .app import main_entry
+
+if __name__ == "__main__":
+    main_entry()

package/.next/standalone/fp-cloud-cli/fp_cli/_click_compat.py

@@ -0,0 +1,64 @@
+"""The Click that Typer is actually running. Import Click through here, never directly.
+
+Typer 0.26 vendored Click into ``typer._click`` and dropped its dependency on the pip
+``click`` distribution. The vendored classes are *different class objects* from pip
+Click's, so every place we hand Click an object, or ask Click about one, breaks when
+the two disagree — and each break is silent, because the code still imports, still
+compiles, and every happy path still passes:
+
+* ``ClickException`` — Typer's command runner catches only *its* Click's exception
+  class. Errors subclassing pip Click's escape **uncaught**: a typed failure that
+  should print ``✗ …`` and exit 5 exits **1 with an empty stderr**, and the
+  ``rich_format_error`` hook in ``app.py`` (reached only *after* that catch) never
+  runs. Same for the ``UsageError``/``BadParameter`` we raise by hand.
+* ``Abort`` — ``typer.prompt`` raises its own Click's ``Abort`` on closed stdin, so a
+  pip-Click ``except click.Abort`` stops matching and the clean "no TTY, pass a slug"
+  usage error becomes a bare abort.
+* Options — Typer 0.26+ has no ``Option`` class in its vendored Click *at all*: every
+  option in a Typer-built tree is a ``typer.core.TyperOption``, subclassing
+  ``Parameter`` directly. ``isinstance(param, click.Option)`` is then quietly always
+  False, which emptied the telemetry flag catalog (``analytics_registry``) while its
+  own anti-drift test stayed green — the test asked the same broken question.
+
+So: resolve the Click that Typer imported, and speak that one.
+``tests/test_click_compat.py`` asserts the package never imports ``click`` directly
+again, and that our errors are still the class Typer catches.
+"""
+
+from __future__ import annotations
+
+try:
+    # typer >= 0.26. pip `click` may well still be installed — it is simply not the
+    # Click in play, so binding to it here would reintroduce the whole class of bug.
+    from typer._click import ClickException, Command, Parameter
+    from typer._click.exceptions import Abort, BadParameter, UsageError
+except ImportError:  # typer < 0.26 drives the pip `click` distribution directly
+    from click import (  # type: ignore[assignment]
+        Abort,
+        BadParameter,
+        ClickException,
+        Command,
+        Parameter,
+        UsageError,
+    )
+
+__all__ = [
+    "Abort",
+    "BadParameter",
+    "ClickException",
+    "Command",
+    "Parameter",
+    "UsageError",
+    "is_option",
+]
+
+
+def is_option(param: Parameter) -> bool:
+    """True if ``param`` is an option (``--flag``), not a positional argument.
+
+    Class identity cannot answer this across both Clicks — the vendored one has no
+    ``Option`` class to test against — so read the ``param_type_name`` that Click sets
+    on every parameter (``"option"`` / ``"argument"``). That holds for pip Click's
+    ``Option`` and for ``TyperOption`` alike.
+    """
+    return getattr(param, "param_type_name", None) == "option"

package/.next/standalone/fp-cloud-cli/fp_cli/_context.py

@@ -0,0 +1,332 @@
+"""Shared command-layer state and helpers.
+
+Kept separate from ``app.py`` so command modules can import these without a
+circular dependency (``app.py`` imports the command modules).
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import math
+import re
+from dataclasses import dataclass
+from typing import List, Optional, Sequence, Tuple
+
+from . import _click_compat as click  # the Click Typer is running; see _click_compat
+from . import config as cfgmod
+from . import dates as _dates
+
+# `AuthMode` is DEFINED in `client.py`, not here, even though it is this layer that
+# resolves it: the import runs `_context` -> `client` (below), and `client` needs the
+# enum at runtime for its bearer-vs-cookie branch — defining it here would make that
+# a cycle. Re-exported so `from ._context import AuthMode` reads naturally beside
+# AppState, which is where most callers want it.
+from .client import AuthMode, ClientContext
+from .errors import AuthError, KeyModeUnsupportedError
+
+
+@dataclass
+class AppState:
+    json: bool
+    base_url: Optional[str]
+    token: Optional[str]
+    timeout: float
+    config: cfgmod.CliConfig
+    insecure: bool = False
+    org: Optional[str] = None  # active tenant slug (flag > env > config)
+    # The EXPLICITLY-supplied tenant (global `--org` or `FP_ORG`), before
+    # the saved-config fallback. `login` uses this so a *saved* tenant never
+    # silently bypasses the interactive org picker — only an explicit choice does.
+    # Key mode reuses it as the ONLY org it will ever send (see `build_context`).
+    org_explicit: Optional[str] = None
+    # The bearer credential in key mode. NEVER written to `cli.json` — see
+    # `resolve_auth`.
+    api_key: Optional[str] = None
+    # Which credential this invocation carries. Defaults to NONE so an AppState
+    # built by another path (tests, embedders) is never silently treated as key
+    # mode; the transport reads it directly, and everything that is not API_KEY
+    # takes the cookie path.
+    auth_mode: AuthMode = AuthMode.NONE
+
+
+def resolve_auth(
+    *,
+    api_key: Optional[str],
+    api_key_on_cli: bool,
+    token: Optional[str],
+    token_on_cli: bool,
+    saved_token: Optional[str],
+) -> Tuple[AuthMode, Optional[str], Optional[str]]:
+    """Resolve the one credential this invocation uses → ``(mode, api_key, token)``.
+
+    Precedence, highest first::
+
+        --api-key AND --token   -> usage error, exit 2 (never guess)
+        --api-key               -> key mode
+        --token                 -> session mode
+        FP_API_KEY    -> key mode      (a key env var beats a token env var)
+        FP_TOKEN      -> session mode
+        cli.json session_token  -> session mode
+        nothing                 -> AuthMode.NONE (require_auth then exits 4)
+
+    ``*_on_cli`` distinguishes a flag from its env var, which the *values* cannot:
+    an explicit ``--token`` has to beat ``FP_API_KEY`` while
+    ``FP_API_KEY`` beats ``FP_TOKEN``. Click's
+    ``ctx.get_parameter_source`` is the only thing that knows the difference.
+
+    ``--api-key ""`` (an unset CI variable spelled out) means "no override": the mode
+    stays KEY with an empty credential, so `require_auth` raises instead of quietly
+    acting as whichever human is logged in on this machine. That mirrors the
+    established ``--token ""`` rule exactly.
+
+    The key is returned for this process only and is never persisted: a session token
+    expires in ~24h, which bounds the blast radius of a leaked `cli.json`; an API key
+    is valid until someone revokes it. There is also no honest revocation path from
+    here — `keys disable` needs `keys:disable`, which a scoped CI key will not hold —
+    so a "clear the saved key" command could not actually revoke anything.
+    """
+    if api_key_on_cli and token_on_cli:
+        raise click.UsageError(
+            "--api-key and --token are mutually exclusive: --api-key authenticates as an "
+            "API key against /v1, --token as a signed-in user session. Pass exactly one."
+        )
+    if api_key_on_cli:
+        return AuthMode.API_KEY, api_key, None
+    if token_on_cli:
+        return AuthMode.SESSION, None, token
+    # Neither flag was given: whatever Click resolved came from the environment.
+    # (Click treats an empty env var as unset, so `FP_API_KEY=""` falls
+    # through to the next rung rather than becoming an empty-credential key mode.)
+    if api_key is not None:
+        return AuthMode.API_KEY, api_key, None
+    if token is not None:
+        return AuthMode.SESSION, None, token
+    if saved_token:
+        return AuthMode.SESSION, None, saved_token
+    return AuthMode.NONE, None, None
+
+
+def deny_in_key_mode(state: "AppState", command: str, reason: str) -> None:
+    """Fail ``command`` with exit 2 when this invocation carries an API key.
+
+    Called as the FIRST statement of every command an API key cannot perform, so the
+    CLI never opens a connection it already knows will fail — a 401/403 from the
+    server would be a much worse explanation than the real one.
+    """
+    if state.auth_mode is AuthMode.API_KEY:
+        raise KeyModeUnsupportedError(
+            f"`fp {command}` does not work with an API key — {reason}.",
+            hint="drop --api-key / FP_API_KEY and sign in with fp login",
+        )
+
+
+def resolved_base_url(state: AppState) -> str:
+    """The effective dashboard URL.
+
+    The app callback already resolves flag/env > saved config > the public
+    default (`config.DEFAULT_BASE_URL`), so `state.base_url` is normally set.
+    This falls back to the same default for any AppState built by another path
+    (tests, embedders), so the CLI always has a URL to talk to.
+    """
+    return state.base_url or cfgmod.DEFAULT_BASE_URL
+
+
+def _org_header(state: AppState) -> Optional[str]:
+    """The tenant slug to send as ``X-AgentEye-Org``.
+
+    In KEY mode only an EXPLICIT ``--org`` / ``FP_ORG`` is ever sent. The saved
+    `cli.json` org belongs to whichever human logged in on this machine and has no
+    bearing on which org a CI key was minted for; sending it would silently ask for
+    another tenant's data and get a 403 that reads like a missing permission.
+
+    (The reverse trap is real too and `whoami` is the pre-flight for it: an
+    instance-scoped key with no `--org` resolves server-side to the DEFAULT org and
+    answers with that org's data, no error anywhere.)
+    """
+    if state.auth_mode is AuthMode.API_KEY:
+        return state.org_explicit
+    return state.org
+
+
+def build_context(state: AppState) -> ClientContext:
+    return ClientContext(
+        base_url=resolved_base_url(state),
+        token=state.token,
+        timeout=state.timeout,
+        verify=not state.insecure,
+        org=_org_header(state),
+        api_key=state.api_key,
+        auth_mode=state.auth_mode,
+    )
+
+
+def require_auth(state: AppState) -> ClientContext:
+    """Return a client context, or raise if no URL is set / not authenticated."""
+    base = resolved_base_url(state)  # the URL is the prerequisite — check it first
+    if state.auth_mode is AuthMode.API_KEY:
+        # `--api-key ""` lands here: key mode, no credential. It must NOT fall back
+        # to a saved cookie session (see `resolve_auth`), so this is an auth failure.
+        if not state.api_key:
+            raise AuthError(
+                "No API key supplied. Pass --api-key <key> or set FP_API_KEY."
+            )
+        # No local expiry check: an API key carries no expiry the CLI can see, and the
+        # server is the only authority on whether it is still live.
+        return ClientContext(
+            base_url=base,
+            api_key=state.api_key,
+            auth_mode=AuthMode.API_KEY,
+            timeout=state.timeout,
+            verify=not state.insecure,
+            org=_org_header(state),
+        )
+    if not state.token:
+        # A pre-move file with no usable session in it (expired, or only ever
+        # held a base_url) reaches here after adoption declined to carry
+        # anything. Name it, so the upgrade is not blamed for the logout.
+        if cfgmod.legacy_install_detected():
+            raise AuthError(
+                "Not logged in. Run fp login.\n"
+                f"The config moved to {cfgmod.config_path()}; "
+                f"{cfgmod.legacy_config_path()} held no usable session to carry "
+                "over. It is left in place — remove it when convenient."
+            )
+        raise AuthError("Not logged in. Run fp login.")
+    # Only enforce local expiry when the token came from the stored config; an
+    # explicit --token / env override has no known expiry, so trust it.
+    if state.token == state.config.session_token and cfgmod.is_expired(state.config):
+        raise AuthError("Session expired. Run fp login.")
+    return ClientContext(
+        base_url=base,
+        token=state.token,
+        timeout=state.timeout,
+        verify=not state.insecure,
+        org=_org_header(state),
+    )
+
+
+def resolve_dates(
+    since: Optional[str], ts_from: Optional[str], ts_to: Optional[str]
+) -> Tuple[Optional[str], Optional[str]]:
+    try:
+        return _dates.resolve_range(since, ts_from, ts_to)
+    except ValueError as exc:
+        raise click.BadParameter(str(exc))
+
+
+def resolve_fields(raw: Optional[str], model_cls: type) -> Optional[List[str]]:
+    """Parse a ``--fields`` CSV into a validated list of model field names (or None).
+
+    Field names must match the dataclass (and thus the ``--json``) keys of the
+    model; unknown names raise a usage error listing the valid set.
+    """
+    if not raw:
+        return None
+    valid = [f.name for f in dataclasses.fields(model_cls)]
+    chosen = [f.strip() for f in raw.split(",") if f.strip()]
+    unknown = [f for f in chosen if f not in valid]
+    if unknown:
+        raise click.BadParameter(
+            f"unknown field(s): {', '.join(unknown)}. Valid fields: {', '.join(valid)}"
+        )
+    return chosen
+
+
+def collect_multi(values: Optional[Sequence[str]]) -> Optional[List[str]]:
+    """Normalize a repeatable + comma-separated CLI option into one flat, de-duplicated list.
+
+    The single reusable helper behind every multi-value filter. Typer hands us a list with
+    one entry per repeated flag (``--env prod --env staging`` → ``["prod", "staging"]``), and
+    each entry may itself be a comma-separated group (``--env prod,staging`` → ``["prod,staging"]``).
+    This splits every entry on commas, trims surrounding whitespace (so ``--env "prod, staging"``
+    works), drops empties (so a trailing comma ``--env prod,`` adds nothing), and de-duplicates
+    while preserving first-seen order. Returns ``None`` when nothing usable remains, so an unset
+    or blank option stays ``None`` and the client drops the param (unchanged single-value path).
+
+    A single value still yields the obvious one-item list (``--env prod`` → ``["prod"]``), which
+    the client serializes back to a bare ``environment=prod`` — fully backward compatible.
+    """
+    if not values:
+        return None
+    out: List[str] = []
+    seen: set = set()
+    for raw in values:
+        for part in str(raw).split(","):
+            v = part.strip()
+            if v and v not in seen:
+                seen.add(v)
+                out.append(v)
+    return out or None
+
+
+def validate_choice(
+    value: Optional[str], allowed: Sequence[str], *, flag: str
+) -> Optional[str]:
+    """Return ``value`` if it's None or one of ``allowed``; else a usage error (exit 2).
+
+    Keeps enum-style flags (``--status``) failing fast client-side with a clear
+    message, consistent with ``--order``/``--source``/``--kind`` — rather than the
+    server's opaque HTTP 400 (exit 1).
+    """
+    if value is None or value in allowed:
+        return value
+    raise click.BadParameter(
+        f"'{value}' is not valid for {flag}. Choose one of: {', '.join(allowed)}.",
+        param_hint=flag,
+    )
+
+
+def validate_limit(limit: Optional[int], *, flag: str = "--limit") -> None:
+    """Reject a non-positive row limit up front with a clean usage error (exit 2), rather
+    than passing ``0``/negative through to the server, which silently defaults/clamps it to
+    a confusing result. Mirrors ``validate_choice`` / ``validate_score_filters``."""
+    if limit is not None and limit <= 0:
+        raise click.BadParameter("must be a positive integer (at least 1).", param_hint=flag)
+
+
+def validate_score_filters(values: Optional[Sequence[str]]) -> None:
+    """Validate ``--score`` values are ``KEY:MIN..MAX`` (either bound optional).
+
+    Without this a malformed value (no ``:`` or no ``..``) is silently sent and
+    dropped server-side, returning the UNFILTERED set — a silent footgun. Raises a
+    usage error (exit 2) on a bad value. Accepts e.g. ``helpfulness:0.5..0.8``,
+    ``x:..0.5``, ``y:0.9..``.
+    """
+    for v in values or []:
+        key, sep, rng = v.partition(":")
+        ok = bool(sep) and bool(key.strip()) and ".." in rng
+        if ok:
+            lo, _, hi = rng.partition("..")
+            # Both bounds empty (`helpfulness:..`) is meaningless: the server silently
+            # drops it and returns the UNFILTERED set, so reject it client-side too.
+            if lo == "" and hi == "":
+                ok = False
+            for bound in (lo, hi):
+                if bound != "":
+                    try:
+                        # `float("nan")`/`float("inf")` succeed but the server silently
+                        # drops the filter — reject non-finite bounds too.
+                        if not math.isfinite(float(bound)):
+                            ok = False
+                            break
+                    except ValueError:
+                        ok = False
+                        break
+        if not ok:
+            raise click.BadParameter(
+                f"'{v}' is not a valid score filter. Use KEY:MIN..MAX (either bound "
+                "optional), e.g. helpfulness:0.5..0.8, tool_efficiency:..0.3, factuality:0.9..",
+                param_hint="--score",
+            )
+
+
+# Appended to every subcommand's --help so an agent that jumps straight to
+# `fp <command> -h` still learns the argument order + where the global options go.
+GLOBALS_EPILOG = (
+    "Argument order: `fp [GLOBAL OPTIONS] <command> [<subcommand>] [ARGS] [OPTIONS]`. "
+    "**Global** options come *before* the command — `--json`, `--base-url`, `--token`, "
+    "`--api-key`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`. A command's (or "
+    "subcommand's) own options come *after* it. "
+    "e.g. `fp --json keys create ci-bot --permission-set read-only` — `--json` is global, "
+    "`keys` the command, `create` the subcommand, `--permission-set` its option."
+)

package/.next/standalone/fp-cloud-cli/fp_cli/_version.py

@@ -0,0 +1 @@
+__version__ = "0.0.1b1"