failproofai 1.0.1-beta.1 → 1.0.2-beta.0

package/.next/standalone/fp-cloud-cli/tests/test_policy_check.py

@@ -0,0 +1,191 @@
+"""Syntax checking and the local policy runner.
+
+The gap these close: nothing between an author and a fleet parsed policy source.
+The CLI rejected a NUL byte, the server checked the id and a size ceiling, and a
+file that was not JavaScript at all published, deployed, and failed on the
+machine at enforcement time.
+
+Every test here needs `node`, so each skips without it rather than failing —
+node is a real dependency of the check but deliberately not of the CLI.
+"""
+from __future__ import annotations
+
+import pytest
+
+from fp_cli.policy_check import check_syntax, node_available, run_policy
+
+needs_node = pytest.mark.skipif(not node_available(), reason="node is not on PATH")
+
+VALID = '''import { customPolicies, allow, deny, instruct } from "failproofai";
+customPolicies.add({
+  name: "t", description: "d", match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    const cmd = String(ctx.toolInput?.command ?? "");
+    if (cmd.includes("force")) return deny("nope");
+    if (cmd.includes("apply")) return instruct("add a note");
+    return allow();
+  },
+});'''
+
+
+# ── syntax ───────────────────────────────────────────────────────────────────
+
+
+@needs_node
+def test_a_real_policy_parses():
+    r = check_syntax(VALID)
+    assert r.ok and r.checked and r.message == ""
+
+
+@needs_node
+@pytest.mark.parametrize("src,label", [
+    ("this is not javascript at all {{{", "prose"),
+    ("export default { name: 'x'", "unclosed brace"),
+    ("const x = ;", "bad expression"),
+    ("# python comment\nprint('hi')", "python"),
+    ("function f( {", "unclosed paren"),
+])
+def test_broken_source_is_caught(src, label):
+    r = check_syntax(src)
+    assert r.ok is False and r.checked is True, label
+    assert r.message, "a refusal with no explanation is not a refusal"
+
+
+@needs_node
+def test_esm_import_syntax_is_accepted():
+    """Policies are ESM. Checking them as a script would reject every real one."""
+    assert check_syntax('import { deny } from "failproofai";\nexport const x = 1;').ok
+
+
+@needs_node
+def test_top_level_await_is_valid_in_a_module():
+    assert check_syntax('const x = await Promise.resolve(1);\nexport default x;').ok
+
+
+@needs_node
+def test_the_error_keeps_the_caret_and_drops_nodes_own_stack():
+    """The caret is the useful part; node's internal frames and version banner
+    are node talking about itself inside an error about the user's policy."""
+    msg = check_syntax("this is not javascript {{{").message
+    assert "^" in msg
+    assert "node:internal" not in msg and "Node.js v" not in msg
+
+
+def test_a_missing_node_is_reported_as_unchecked_not_as_passing(monkeypatch):
+    """"we did not look" must never render as "we looked and it passed"."""
+    monkeypatch.setattr("fp_cli.policy_check.node_available", lambda: False)
+    r = check_syntax("anything at all")
+    assert r.ok is True and r.checked is False and "node" in r.message
+
+
+# ── running ──────────────────────────────────────────────────────────────────
+
+
+@needs_node
+@pytest.mark.parametrize("cmd,expected", [
+    ("git push --force origin main", "deny"),
+    ("kubectl apply -f x.yaml", "instruct"),
+    ("git status", "allow"),
+])
+def test_the_policy_decides_per_input(cmd, expected):
+    run = run_policy(VALID, tool="Bash", command=cmd)
+    assert run.ok and run.decision == expected
+
+
+@needs_node
+def test_the_bare_failproofai_import_resolves():
+    """The file under test is byte-identical to the one that gets published, so
+    its bare specifier has to resolve the way node resolves it in production."""
+    assert run_policy(VALID, command="git status").ok
+
+
+@needs_node
+def test_the_strictest_decision_wins():
+    """One refusal is a refusal regardless of what the other policies said."""
+    two = VALID + '''
+customPolicies.add({ name: "always-allow", match: { events: ["PreToolUse"] },
+  fn: async () => allow() });'''
+    run = run_policy(two, command="git push --force x")
+    assert run.decision == "deny" and len(run.results) == 2
+
+
+@needs_node
+def test_a_file_registering_nothing_says_so():
+    """An empty result is not an allow — it means the file never called add()."""
+    run = run_policy('export const x = 1;')
+    assert run.ok is False and "registered no policies" in run.error
+
+
+@needs_node
+def test_a_policy_that_throws_is_reported_per_policy_not_as_a_crash():
+    boom = '''import { customPolicies } from "failproofai";
+customPolicies.add({ name: "boom", fn: async () => { throw new Error("kaboom"); } });'''
+    run = run_policy(boom, command="x")
+    assert run.ok and "kaboom" in run.results[0]["error"]
+
+
+@needs_node
+def test_an_infinite_loop_times_out_instead_of_hanging():
+    """A policy that cannot decide in five seconds cannot sit on a hook either."""
+    spin = '''import { customPolicies } from "failproofai";
+customPolicies.add({ name: "spin", fn: async () => { while (true) {} } });'''
+    run = run_policy(spin, command="x")
+    assert run.ok is False and "finish" in run.error
+
+
+@needs_node
+def test_file_path_inputs_reach_the_policy():
+    src = '''import { customPolicies, allow, deny } from "failproofai";
+customPolicies.add({ name: "env", fn: async (ctx) =>
+  /\\.env/.test(String(ctx.toolInput?.file_path ?? "")) ? deny("no") : allow() });'''
+    assert run_policy(src, tool="Write", file_path=".env").decision == "deny"
+    assert run_policy(src, tool="Write", file_path="README.md").decision == "allow"
+
+
+def test_running_without_node_fails_loudly(monkeypatch):
+    monkeypatch.setattr("fp_cli.policy_check.node_available", lambda: False)
+    run = run_policy(VALID, command="x")
+    assert run.ok is False and "node" in run.error
+
+
+def test_a_slow_machine_is_not_reported_as_a_bad_policy(monkeypatch):
+    """A syntax-check timeout says nothing about the source.
+
+    `node --check` runs none of the policy, so a timeout is a statement about the
+    machine, not the file. It used to share the EXECUTION budget (5s, sized so a
+    looping policy fails instead of hanging) and report `ok=False` — which reads
+    as "your policy is broken" and made `fp policies publish` refuse a perfectly
+    good file because the box was busy. Seen on CI the moment the fp-cloud-cli matrix
+    widened to four concurrent interpreters: three legs passed and the fourth
+    timed out on this same source.
+
+    `checked=False` is the honest verdict and the one `SyntaxResult` already
+    models — the same shape as node being absent entirely.
+    """
+    import subprocess
+
+    from fp_cli import policy_check
+
+    def _timeout(*a, **kw):
+        raise subprocess.TimeoutExpired(cmd="node", timeout=policy_check._SYNTAX_TIMEOUT_SECS)
+
+    monkeypatch.setattr(policy_check, "node_available", lambda: True)
+    monkeypatch.setattr(subprocess, "run", _timeout)
+
+    result = check_syntax(VALID)
+    assert result.ok is True, "a busy machine must not be reported as a syntax error"
+    assert result.checked is False, "'we did not look' must never render as 'we looked and it passed'"
+    assert "not checked" in result.message
+
+
+def test_parsing_and_executing_have_separate_budgets():
+    """The tight budget is a product statement about hook latency.
+
+    It applies to running a policy, where an accidental infinite loop must fail
+    the command rather than hang it. Parsing runs no user code, so nothing there
+    can loop and the same number is only a cold-start race.
+    """
+    from fp_cli import policy_check
+
+    assert policy_check._TIMEOUT_SECS == 5
+    assert policy_check._SYNTAX_TIMEOUT_SECS > policy_check._TIMEOUT_SECS

package/.next/standalone/fp-cloud-cli/tests/test_readme_matches_reality.py

@@ -0,0 +1,125 @@
+"""The README ships inside the wheel and IS the PyPI landing page.
+
+Nothing else checks it, and it had rotted before this file existed: it documented
+`fp incidents` (renamed to `issues` long ago) and claimed the dashboard URL was
+required with no default (there is one). Both would have been the first thing a new
+user read.
+
+These tests pin the README's factual claims to the code that implements them.
+"""
+
+from __future__ import annotations
+
+import pathlib
+import re
+
+from typer.main import get_command
+
+from fp_cli import config, errors
+from fp_cli.app import app
+
+README = pathlib.Path(__file__).resolve().parent.parent / "README.md"
+
+
+def _registered() -> set[str]:
+    return set(get_command(app).commands)  # type: ignore[attr-defined]
+
+
+def _readme() -> str:
+    return README.read_text(encoding="utf-8")
+
+
+def test_readme_exists_and_is_substantial():
+    """Guards every assertion below from passing vacuously on a missing file."""
+    assert README.is_file(), f"{README} is missing — it ships in the wheel"
+    assert len(_readme()) > 2000
+
+
+def test_every_command_the_readme_documents_actually_exists():
+    text = _readme()
+    documented = set(re.findall(r"^fp ([a-z][a-z-]*)\b", text, re.M))
+    documented |= set(re.findall(r"`fp ([a-z][a-z-]*)[ `]", text))
+    # Global flags and shell noise are not commands.
+    documented = {d for d in documented if not d.startswith("-")}
+    unknown = documented - _registered()
+    assert not unknown, (
+        f"the README documents commands that do not exist: {sorted(unknown)} "
+        f"(registered: {sorted(_registered())})"
+    )
+
+
+def test_every_subcommand_the_readme_documents_actually_exists():
+    """The group-level check above anchors on `^fp <group>` and never looks at the
+    pipe-separated verb lists beside it. `fp audits ... |update|` sat in the README
+    documenting a verb that does not exist (it is `edit`) and passed CI.
+    """
+    cmd = get_command(app)
+    text = _readme()
+    bad = []
+    for line in text.split("\n"):
+        m = re.match(r"^fp ([a-z][a-z-]*) ([a-z][a-z|-]*)", line)
+        if not m:
+            continue
+        group, verbs = m.group(1), m.group(2)
+        sub = cmd.commands.get(group)  # type: ignore[attr-defined]
+        if sub is None or not hasattr(sub, "commands"):
+            continue  # not a group; the group-level test covers it
+        real = set(sub.commands)
+        for verb in verbs.split("|"):
+            if verb and verb not in real:
+                bad.append(f"`fp {group} {verb}` (real verbs: {sorted(real)})")
+    assert not bad, "the README documents subcommands that do not exist:\n  " + "\n  ".join(bad)
+
+
+def test_the_readme_install_instructions_name_the_distribution_not_the_command():
+    """`pip install fp` installs somebody else's package. The dist is `fp-cloud-cli`."""
+    text = _readme()
+    bad = re.findall(r"(?:pipx|pip|uv tool) install fp(?![-\w])", text)
+    assert not bad, f"install instructions must say fp-cloud-cli, not fp: {bad}"
+
+
+def test_the_documented_default_base_url_is_the_real_one():
+    assert config.DEFAULT_BASE_URL in _readme(), (
+        f"README does not mention the real default base URL {config.DEFAULT_BASE_URL}"
+    )
+
+
+def test_the_readme_exit_code_table_matches_the_error_classes():
+    """The exit codes are a public scripting contract, restated in four places."""
+    text = _readme()
+    table = dict(
+        (int(code), meaning.strip())
+        for code, meaning in re.findall(r"^\|\s*(\d)\s*\|\s*([^|]+)\|", text, re.M)
+    )
+    assert table, "no exit-code table found in the README"
+    actual = {
+        e.exit_code
+        for e in vars(errors).values()
+        if isinstance(e, type)
+        and issubclass(e, Exception)
+        and isinstance(getattr(e, "exit_code", None), int)
+    }
+    documented = set(table)
+    missing = actual - documented
+    assert not missing, f"exit codes raised by the CLI but undocumented: {sorted(missing)}"
+    assert 0 in documented, "the README must document exit code 0"
+
+
+def test_the_readme_does_not_link_private_repo_paths():
+    """This README is published to PyPI; enterprise-docs/ is a private-repo path."""
+    text = _readme()
+    for needle in ("enterprise-docs/", "agenteye-enterprise/", "github.com/agenteye"):
+        assert needle not in text, f"private path {needle!r} must not ship in a public README"
+
+
+def test_the_readme_documents_only_env_vars_the_cli_reads():
+    """A documented-but-unread env var is worse than an undocumented one: the user
+    sets it, nothing happens, and there is no error to search for."""
+    import fp_cli
+
+    pkg = pathlib.Path(fp_cli.__file__).resolve().parent
+    source = "\n".join(p.read_text(encoding="utf-8") for p in pkg.rglob("*.py"))
+    documented = set(re.findall(r"`(FP_[A-Z_]+)`", _readme()))
+    assert documented, "the README documents no FP_* env vars — did the table move?"
+    unread = {v for v in documented if f'"{v}"' not in source}
+    assert not unread, f"README documents env vars the CLI never reads: {sorted(unread)}"

package/.next/standalone/fp-cloud-cli/tests/test_review_fixes.py

@@ -0,0 +1,161 @@
+"""Tests for the review-driven fixes: json-aware error contract, resolver, SQL detail,
+NaN-safe JSON, markup-safe tables, settings int parsing, and the org-switch json path."""
+
+from __future__ import annotations
+
+import json
+from types import SimpleNamespace
+
+from fp_cli import _click_compat as click  # the Click Typer is running
+import httpx
+import pytest
+import respx
+
+from fp_cli import client, output
+from fp_cli.app import app
+from fp_cli.commands import _write
+from fp_cli.errors import NotFoundError
+
+BASE = "http://dash.test"
+
+
+# --- json-aware error contract (envelope on stdout) ------------------------------
+
+
+@respx.mock
+def test_json_error_envelope_not_found(logged_in, runner):
+    respx.get(f"{BASE}/api/users").mock(return_value=httpx.Response(200, json=[]))
+    result = runner.invoke(app, ["--json", "users", "show", "nobody@x.com"])
+    assert result.exit_code == 6
+    data = json.loads(result.stdout)  # must be a clean JSON object on stdout
+    assert "nobody@x.com" in data["error"]
+    assert data["exit_code"] == 6
+    assert "hint" in data  # the "run `fp users list`" hint rides along
+
+
+def test_json_error_envelope_usage(logged_in, runner):
+    # A client-side validation error is ALSO a JSON envelope on stdout under --json.
+    result = runner.invoke(app, ["--json", "sessions", "--since", "bogus"])
+    assert result.exit_code == 2
+    data = json.loads(result.stdout)
+    assert data["exit_code"] == 2
+    assert "since" in data["error"].lower()
+
+
+@respx.mock
+def test_json_error_envelope_carries_status_and_request_id(logged_in, runner):
+    respx.get(f"{BASE}/api/sessions").mock(
+        return_value=httpx.Response(500, json={"error": "boom"}, headers={"x-request-id": "req-123"})
+    )
+    result = runner.invoke(app, ["--json", "sessions"])
+    assert result.exit_code == 1
+    data = json.loads(result.stdout)
+    assert data["error"] == "boom" and data["exit_code"] == 1 and data["status"] == 500
+    assert data["request_id"] == "req-123"  # kept for server-log correlation
+    assert "HTTP" not in data["error"]  # clean message; status is a separate field
+
+
+def test_unknown_command_json_envelope_via_env(logged_in, runner):
+    # An error raised BEFORE the group callback runs (unknown command) still honors --json via the
+    # env fallback, so an agent that typos a command under --json gets a parseable error on stdout.
+    result = runner.invoke(app, ["frobnicate"], env={"FP_JSON": "1"})
+    assert result.exit_code == 2
+    data = json.loads(result.stdout)
+    assert "frobnicate" in data["error"] and data["exit_code"] == 2
+
+
+def test_flag_placement_hint(logged_in, runner):
+    # A global flag AFTER the command nudges toward the right placement.
+    result = runner.invoke(app, ["sessions", "--json"])
+    assert result.exit_code == 2
+    assert "before the command" in result.stderr
+
+
+# --- shared resolve_one ----------------------------------------------------------
+
+
+def test_resolve_one_resolves_by_name_and_id():
+    items = [SimpleNamespace(name="a", id="1"), SimpleNamespace(name="b", id="2")]
+    assert _write.resolve_one(items, "a", kind="key", list_cmd="keys list").id == "1"
+    assert _write.resolve_one(items, "2", kind="key", list_cmd="keys list").name == "b"
+
+
+def test_resolve_one_not_found_raises_exit_6():
+    with pytest.raises(NotFoundError) as exc:
+        _write.resolve_one([], "zzz", kind="key", list_cmd="keys list")
+    assert exc.value.exit_code == 6
+    assert exc.value.hint  # carries a "run `fp keys list`" hint
+
+
+def test_resolve_one_ambiguous_raises_usage():
+    dup = [SimpleNamespace(name="a", id="1"), SimpleNamespace(name="a", id="2")]
+    with pytest.raises(click.UsageError):
+        _write.resolve_one(dup, "a", kind="key", list_cmd="keys list")
+
+
+# --- client._extract_error folds in the server `detail` --------------------------
+
+
+def test_extract_error_includes_detail():
+    resp = httpx.Response(400, json={"error": "query failed", "detail": "syntax error near 'FORM'"})
+    assert client._extract_error(resp) == "query failed: syntax error near 'FORM'"
+
+
+def test_extract_error_without_detail():
+    resp = httpx.Response(404, json={"error": "Not found."})
+    assert client._extract_error(resp) == "Not found."
+
+
+# --- emit_json is always valid JSON (no NaN/Infinity tokens) ---------------------
+
+
+def test_emit_json_coerces_non_finite(capsys):
+    output.emit_json({"a": float("nan"), "b": float("inf"), "c": float("-inf"), "d": 1.5})
+    data = json.loads(capsys.readouterr().out)  # would raise on a bare NaN token
+    assert data == {"a": None, "b": None, "c": None, "d": 1.5}
+
+
+# --- print_table never raises MarkupError on bracketed cells ---------------------
+
+
+def test_print_table_escapes_markup(capsys):
+    output.configure(no_color=True)
+    output.print_table(["k", "v"], [["x", "[/]"], ["y", "[red]bad[/red]"]])  # must not raise
+    out = capsys.readouterr().out
+    assert "[/]" in out and "[red]bad[/red]" in out  # rendered literally
+
+
+# --- settings set --value coercion never crashes on odd input --------------------
+
+
+@respx.mock
+def test_settings_set_unicode_value_no_crash(logged_in, runner):
+    respx.get(f"{BASE}/api/settings").mock(
+        return_value=httpx.Response(200, json={"settings": [
+            {"key": "session_ttl_secs", "value": 100, "schema": {"kind": "positive_int"}}]})
+    )
+    respx.put(f"{BASE}/api/settings/session_ttl_secs").mock(
+        return_value=httpx.Response(422, json={"error": "must be an integer"})
+    )
+    result = runner.invoke(app, ["--json", "settings", "set", "session_ttl_secs", "--value", "²"])
+    assert "Traceback" not in result.output  # the old isdigit()/int() path raised here
+    assert result.exit_code == 1
+    assert json.loads(result.stdout)["error"] == "must be an integer"
+
+
+# --- orgs switch not-found now emits a JSON envelope (was silent under --json) ----
+
+
+@respx.mock
+def test_orgs_switch_not_found_json_emits_error(logged_in, runner):
+    respx.get(f"{BASE}/api/auth/session").mock(return_value=httpx.Response(200, json={
+        "id": "u1", "email": "me@test", "is_instance_admin": False,
+        "memberships": [{"org_id": "o1", "org_slug": "acme", "org_name": "Acme",
+                         "permissions": ["events:read"], "permission_set": "standard"}],
+    }))
+    result = runner.invoke(app, ["--json", "orgs", "switch", "acm"])
+    assert result.exit_code == 2
+    data = json.loads(result.stdout)
+    assert "no org named acm" in data["error"]
+    assert data["exit_code"] == 2
+    assert "acme" in data.get("hint", "")

package/.next/standalone/fp-cloud-cli/tests/test_telemetry_completeness.py

@@ -0,0 +1,90 @@
+"""Anti-drift guard: every command and flag must be tracked by telemetry.
+
+Introspects the assembled Typer/Click app and asserts the derived telemetry catalog
+covers every command, every leaf subcommand, and every option token. This fails the
+moment a new command or flag is added without being trackable — so usage signal can
+never silently go missing and a flag VALUE can never leak (a flag must be allowlisted
+by name to be emitted at all).
+"""
+
+from __future__ import annotations
+
+import pytest
+from typer.main import get_command
+
+from fp_cli import _click_compat as click  # the Click Typer is running
+from fp_cli import analytics
+from fp_cli import analytics_registry as reg
+from fp_cli.app import app
+
+
+def _leaf_commands():
+    """Yield (path_tuple, click.Command) for every leaf command in the app."""
+    cli = get_command(app)
+
+    def walk(cmd, prefix):
+        subs = getattr(cmd, "commands", None)
+        if subs:
+            for name, sub in subs.items():
+                yield from walk(sub, prefix + (name,))
+        else:
+            yield prefix, cmd
+
+    yield from walk(cli, ())
+
+
+def _all_option_tokens():
+    cli = get_command(app)
+    tokens = set()
+
+    def walk(cmd):
+        for p in getattr(cmd, "params", []):
+            if click.is_option(p):
+                tokens.update(p.opts)
+                tokens.update(p.secondary_opts)
+        for sub in (getattr(cmd, "commands", None) or {}).values():
+            walk(sub)
+
+    walk(cli)
+    return tokens
+
+
+def test_every_command_is_known():
+    known, leaves, _flags, _vf = reg.build()
+    missing = []
+    for path, _cmd in _leaf_commands():
+        group = path[0]
+        if group not in known:
+            missing.append(group)
+        if len(path) >= 2 and path[1] not in leaves.get(group, frozenset()):
+            missing.append(" ".join(path))
+    assert not missing, f"commands not tracked by telemetry catalog: {sorted(set(missing))}"
+
+
+def test_every_option_is_tracked():
+    _known, _leaves, flags, _vf = reg.build()
+    untracked = sorted(t for t in _all_option_tokens() if t not in flags)
+    assert not untracked, f"option flags missing from telemetry catalog: {untracked}"
+
+
+def test_resolve_command_path_for_nested_groups():
+    # A nested invocation resolves to (group, leaf) using only static catalog names.
+    assert analytics._resolve_command_path(["--json", "orgs", "list"]) == ("orgs", "list")
+    assert analytics._resolve_command_path(["orgs", "switch", "acme"]) == ("orgs", "switch")
+    assert analytics._resolve_command_path(["--org", "acme", "agent", "show", "s1"]) == ("agent", "show")
+    assert analytics._resolve_command_path(["whoami"]) == ("whoami", None)
+
+
+def test_sanitize_flags_never_emits_values_for_any_command():
+    # For every leaf command, feed its own option tokens with fake values and assert
+    # the sanitised output contains only known flag names (never the values).
+    _known, _leaves, flags, _vf = reg.build()
+    for path, cmd in _leaf_commands():
+        argv = list(path)
+        for p in getattr(cmd, "params", []):
+            if click.is_option(p) and p.opts:
+                argv += [p.opts[0], "SECRET-VALUE"]
+        emitted = analytics._sanitize_flags(argv)
+        assert "SECRET-VALUE" not in emitted
+        for f in emitted:
+            assert f in set(flags.values()), f"{f} not a canonical flag name"

package/.next/standalone/fp-cloud-cli/tests/test_usage.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import json
+
+import httpx
+import respx
+
+from fp_cli.app import app
+
+BASE = "http://dash.test"
+
+USAGE = {
+    "org_id": "00000000-0000-0000-0000-000000000001",
+    "billing_anchor": "2026-07-15T00:00:00Z",
+    "window": {
+        "start": "2026-07-15T00:00:00Z",
+        "end": "2026-08-14T00:00:00Z",
+        "current": True,
+    },
+    "usage": {
+        "events_ingested": 12840,
+        "sessions": 146,
+        "agents": 12,
+        "environments": 3,
+        "evaluation_runs": 84,
+        "evaluation_finishes": 79,
+        "evaluations": 420,
+        "metrics": 1260,
+        "queries_created": 31,
+        "dashboards_created": 6,
+        "alerts_created": 11,
+        "issues_created": 34,
+        "audit_runs": 18,
+        "audit_finishes": 16,
+        "keys_created": 5,
+        "keys_active": 3,
+        "users_created": 5,
+        "users_active": 1,
+    },
+    "calculated_at": "2026-07-31T12:00:00Z",
+    "stale_after": "2026-07-31T12:01:00Z",
+}
+
+
+@respx.mock
+def test_usage_json_returns_dashboard_contract_unchanged(logged_in, runner):
+    request = respx.get(f"{BASE}/api/usage").mock(
+        return_value=httpx.Response(200, json=USAGE)
+    )
+
+    result = runner.invoke(app, ["--json", "usage"])
+
+    assert result.exit_code == 0, result.output
+    assert json.loads(result.stdout) == USAGE
+    assert request.called
+
+
+@respx.mock
+def test_usage_human_output_is_grouped_and_readable(logged_in, runner):
+    respx.get(f"{BASE}/api/usage").mock(return_value=httpx.Response(200, json=USAGE))
+
+    result = runner.invoke(app, ["--no-color", "usage"])
+
+    assert result.exit_code == 0, result.output
+    assert "Jul 15, 2026" in result.stdout
+    assert "12,840" in result.stdout
+    assert "PIPELINE COMPLETION" in result.stdout
+    assert "WORKSPACE & ACCESS" in result.stdout
+    assert "94%" in result.stdout
+
+
+@respx.mock
+def test_usage_names_required_permission(logged_in, runner):
+    respx.get(f"{BASE}/api/usage").mock(
+        return_value=httpx.Response(
+            403,
+            json={"error": "forbidden", "required_permission": "usage:read"},
+        )
+    )
+
+    result = runner.invoke(app, ["--json", "usage"])
+
+    assert result.exit_code == 5
+    assert json.loads(result.stdout)["error"] == "you don't have the usage:read permission"
+
+
+@respx.mock
+def test_usage_reports_missing_billing_date(logged_in, runner):
+    respx.get(f"{BASE}/api/usage").mock(
+        return_value=httpx.Response(404, json={"error": "billing date is not set"})
+    )
+
+    result = runner.invoke(app, ["--json", "usage"])
+
+    assert result.exit_code == 6
+    assert json.loads(result.stdout)["error"] == "billing date is not set"
+
+
+@respx.mock
+def test_usage_rejects_non_object_success_response(logged_in, runner):
+    respx.get(f"{BASE}/api/usage").mock(return_value=httpx.Response(200, json=[]))
+
+    result = runner.invoke(app, ["--json", "usage"])
+
+    assert result.exit_code == 1
+    assert json.loads(result.stdout)["error"] == "The dashboard returned an invalid usage response."
+
+
+def test_usage_is_one_command_with_help_but_no_subcommands(home, runner):
+    help_result = runner.invoke(app, ["usage", "--help"])
+    assert help_result.exit_code == 0
+    assert "current fixed 30-day metering window" in help_result.stdout
+
+    child_result = runner.invoke(app, ["usage", "history"])
+    assert child_result.exit_code == 2