feat: mirror the API's validators as Click choices

Every enumeration the REST API validates is now restated in sp_cli/constants.py
and wired into the commands as click.Choice, so a bad --status or --platform
fails instantly as a usage error instead of costing a round trip and coming
back as an HTTP 400.

The values are not invented; each one mirrors a specific validator in the
merged mod_api blueprint, and the module says which. The ones that are easy to
guess wrong:

- /runs?status= only accepts queued|running|canceled. It is derived from the
  latest TestProgress row, so pass/fail -- which are per-sample outcomes, not
  run states -- are deliberately absent. Use `sp run summary` for those.
- _VALID_SAMPLE_STATUSES is pass|fail|missing_output|not_started. No 'skipped',
  no 'running'.
- /regression-tests?active is a two-way switch, not tri-state: omitting it
  lists active tests only, so --active/--all was wrong and is now
  --active/--inactive.
- There are seven token scopes, not six: system:write is separate from
  system:read so a monitoring token cannot reconfigure the platform.

Also fills in filters the API supports but the CLI was not exposing (sample
--sha256/--status, queue --limit/--offset, run --repository/--sort and the
date window).

ApiContractTests pins all of this, so a validator changing upstream fails here
loudly rather than in production.

Author: gaurav-dev02

sp_cli/commands/auth.py

@@ -1,38 +1,81 @@
-"""``sp auth`` — obtain and revoke API tokens."""
+"""``sp auth`` — obtain, list, and revoke API tokens."""
+
+from typing import Optional, Tuple
 
 import click
 
 from sp_cli.client import ApiError
+from sp_cli.constants import TOKEN_MAX_DAYS, TOKEN_MIN_DAYS, TOKEN_SCOPES
 from sp_cli.output import render, render_error
+from sp_cli.runner import clean_params, fetch_and_render
 
 
 @click.group()
 def auth() -> None:
-    """Obtain and revoke API tokens."""
+    """Obtain, list, and revoke API tokens."""
 
 
 @auth.command('login')
 @click.option('--email', prompt=True, help='Account email.')
 @click.option('--password', prompt=True, hide_input=True, help='Account password (never stored).')
-@click.option('--name', 'token_name', default='sp-cli', show_default=True, help='Token label.')
-@click.option('--days', 'expires_in_days', type=int, default=30, show_default=True,
-              help='Token lifetime in days (max 90).')
+@click.option('--name', 'token_name', default='sp-cli', show_default=True,
+              help='Token label; must match ^[a-zA-Z0-9_-]+$.')
+@click.option('--days', 'expires_in_days', type=click.IntRange(TOKEN_MIN_DAYS, TOKEN_MAX_DAYS),
+              default=TOKEN_MAX_DAYS, show_default=True, help='Token lifetime in days.')
+@click.option('--scope', 'scopes', multiple=True, type=click.Choice(TOKEN_SCOPES),
+              help='Grant a specific scope; repeatable. Omit for the server default set.')
 @click.pass_context
-def auth_login(ctx: click.Context, email: str, password: str,
-               token_name: str, expires_in_days: int) -> None:
-    """Create an API token; store the printed value in SP_API_TOKEN."""
+def auth_login(ctx: click.Context, email: str, password: str, token_name: str,
+               expires_in_days: int, scopes: Tuple[str, ...]) -> None:
+    """Create an API token; store the printed value in SP_API_TOKEN.
+
+    The plaintext token is returned exactly once, at creation. Later `sp auth
+    tokens` calls list metadata only, so capture it now or create a new one.
+    """
     client = ctx.obj['client']
     output = ctx.obj['output']
     body = {'email': email, 'password': password,
             'token_name': token_name, 'expires_in_days': expires_in_days}
+    if scopes:
+        body['scopes'] = list(scopes)
     try:
         result = client.request('POST', '/auth/tokens', json_body=body)
     except ApiError as error:
         render_error(error, output)
         raise SystemExit(error.exit_code)
+
     render(result, output)
 
 
+@auth.command('tokens')
+@click.option('--limit', type=int, default=None, help='Page size (max 100).')
+@click.option('--offset', type=int, default=None, help='Pagination offset.')
+@click.pass_context
+def auth_tokens(ctx: click.Context, limit: Optional[int], offset: Optional[int]) -> None:
+    """List this account's API tokens (metadata only, never the token itself)."""
+    params = clean_params({'limit': limit, 'offset': offset})
+    fetch_and_render(ctx, '/auth/tokens', params)
+
+
+@auth.command('revoke')
+@click.argument('token_id', type=int)
+@click.pass_context
+def auth_revoke(ctx: click.Context, token_id: int) -> None:
+    """Revoke one token by id, leaving the token in use untouched.
+
+    Use `sp auth tokens` to find the id. To revoke the token you are currently
+    authenticating with, use `sp auth logout` instead.
+    """
+    client = ctx.obj['client']
+    output = ctx.obj['output']
+    try:
+        client.request('DELETE', f'/auth/tokens/{token_id}')
+    except ApiError as error:
+        render_error(error, output)
+        raise SystemExit(error.exit_code)
+    click.echo(f'Token {token_id} revoked.')
+
+
 @auth.command('logout')
 @click.pass_context
 def auth_logout(ctx: click.Context) -> None:

sp_cli/commands/regression.py

@@ -15,15 +15,21 @@ def regression() -> None:
 @regression.command('ls')
 @click.option('--category', default=None, help='Filter by category name.')
 @click.option('--tag', default=None, help='Filter by tag.')
-@click.option('--active/--all', 'active', default=None, help='Only active tests (default: all).')
+@click.option('--active/--inactive', 'active', default=None,
+              help='Select active or inactive tests (default: active only).')
 @click.option('--sample-id', type=int, default=None, help='Filter by sample id.')
 @click.option('--limit', type=int, default=None, help='Page size (max 100).')
 @click.option('--offset', type=int, default=None, help='Pagination offset.')
 @click.pass_context
 def regression_ls(ctx: click.Context, category: Optional[str], tag: Optional[str],
                   active: Optional[bool], sample_id: Optional[int],
                   limit: Optional[int], offset: Optional[int]) -> None:
-    """List regression-test definitions."""
+    """List regression-test definitions.
+
+    The API's ``active`` filter is a two-way switch with no "everything"
+    setting: omitting it lists active tests only, and ``--inactive`` lists
+    inactive ones only. Run the command twice to see both.
+    """
     params = clean_params({'category': category, 'tag': tag, 'active': active,
                            'sample_id': sample_id, 'limit': limit, 'offset': offset})
     fetch_and_render(ctx, '/regression-tests', params)

sp_cli/commands/run.py

@@ -5,6 +5,8 @@
 import click
 
 from sp_cli.client import ApiError
+from sp_cli.constants import (CANCEL_REASON_MIN_LENGTH, PLATFORMS,
+                              RUN_STATUSES, SAMPLE_STATUSES)
 from sp_cli.output import render, render_error
 from sp_cli.runner import clean_params, fetch_and_render
 from sp_cli.triage import classify_sample, is_failure
@@ -16,18 +18,34 @@ def run() -> None:
 
 
 @run.command('ls')
-@click.option('--status', default=None, help='queued|running|pass|fail|canceled|error|incomplete')
-@click.option('--platform', default=None, help='linux|windows')
+@click.option('--status', type=click.Choice(RUN_STATUSES), default=None,
+              help='Filter by lifecycle status. The API only tracks these three.')
+@click.option('--platform', type=click.Choice(PLATFORMS), default=None, help='Test platform.')
 @click.option('--branch', default=None, help='Filter by branch name.')
 @click.option('--commit', 'commit_sha', default=None, help='Full 40-char commit SHA.')
+@click.option('--repository', default=None, help='Filter by fork, as owner/repo.')
+@click.option('--sort', default=None, help='Sort key, e.g. -created_at (default) or run_id.')
+@click.option('--created-after', 'created_after', default=None,
+              help='Only runs first seen at/after this time (ISO 8601).')
+@click.option('--created-before', 'created_before', default=None,
+              help='Only runs first seen at/before this time (ISO 8601).')
 @click.option('--limit', type=int, default=None, help='Page size (max 100).')
 @click.option('--offset', type=int, default=None, help='Pagination offset.')
 @click.pass_context
 def run_ls(ctx: click.Context, status: Optional[str], platform: Optional[str], branch: Optional[str],
-           commit_sha: Optional[str], limit: Optional[int], offset: Optional[int]) -> None:
-    """List CI runs (newest first)."""
+           commit_sha: Optional[str], repository: Optional[str], sort: Optional[str],
+           created_after: Optional[str], created_before: Optional[str],
+           limit: Optional[int], offset: Optional[int]) -> None:
+    """List CI runs (newest first).
+
+    --status only accepts queued, running, and canceled: the API derives them
+    from the latest TestProgress row, and pass/fail are per-sample outcomes
+    rather than run states. Use `sp run summary` for a run's pass/fail split.
+    """
     params = clean_params({'status': status, 'platform': platform, 'branch': branch,
-                           'commit_sha': commit_sha, 'limit': limit, 'offset': offset})
+                           'commit_sha': commit_sha, 'repository': repository, 'sort': sort,
+                           'created_after': created_after, 'created_before': created_before,
+                           'limit': limit, 'offset': offset})
     fetch_and_render(ctx, '/runs', params)
 
 
@@ -66,14 +84,20 @@ def run_failures(ctx: click.Context, run_id: int) -> None:
 
 @run.command('results')
 @click.argument('run_id', type=int)
-@click.option('--status', default=None, help='pass|fail|skipped|missing_output|running|not_started')
+@click.option('--status', type=click.Choice(SAMPLE_STATUSES), default=None,
+              help='Filter by per-sample outcome.')
+@click.option('--name', default=None, help='Substring match on the sample name.')
+@click.option('--tag', default=None, help='Filter by sample tag.')
+@click.option('--category', default=None, help='Filter by regression-test category.')
 @click.option('--limit', type=int, default=None, help='Page size (max 100).')
 @click.option('--offset', type=int, default=None, help='Pagination offset.')
 @click.pass_context
-def run_results(ctx: click.Context, run_id: int, status: Optional[str],
+def run_results(ctx: click.Context, run_id: int, status: Optional[str], name: Optional[str],
+                tag: Optional[str], category: Optional[str],
                 limit: Optional[int], offset: Optional[int]) -> None:
     """List all regression-test results in a run."""
-    params = clean_params({'status': status, 'limit': limit, 'offset': offset})
+    params = clean_params({'status': status, 'name': name, 'tag': tag, 'category': category,
+                           'limit': limit, 'offset': offset})
     fetch_and_render(ctx, f'/runs/{run_id}/samples', params)
 
 
@@ -167,6 +191,90 @@ def run_approve_baseline(ctx: click.Context, run_id: int, sample_id: int,
     render(result, output)
 
 
+@run.command('progress')
+@click.argument('run_id', type=int)
+@click.option('--limit', type=int, default=None, help='Page size (max 100).')
+@click.option('--offset', type=int, default=None, help='Pagination offset.')
+@click.pass_context
+def run_progress(ctx: click.Context, run_id: int, limit: Optional[int],
+                 offset: Optional[int]) -> None:
+    """Show the timeline of progress events the CI worker recorded for a run."""
+    params = clean_params({'limit': limit, 'offset': offset})
+    fetch_and_render(ctx, f'/runs/{run_id}/progress', params)
+
+
+@run.command('config')
+@click.argument('run_id', type=int)
+@click.pass_context
+def run_config(ctx: click.Context, run_id: int) -> None:
+    """Show the platform, branch, commit, and regression tests a run was launched with."""
+    fetch_and_render(ctx, f'/runs/{run_id}/config')
+
+
+@run.command('cancel')
+@click.argument('run_id', type=int)
+@click.option('--reason', default=None,
+              help=f'Why the run is being canceled (min {CANCEL_REASON_MIN_LENGTH} characters).')
+@click.pass_context
+def run_cancel(ctx: click.Context, run_id: int, reason: Optional[str]) -> None:
+    """Cancel a queued or running test.
+
+    Requires the ``runs:write`` scope. Idempotent: canceling a run that has
+    already finished succeeds and reports ``status=no_op`` rather than failing.
+    """
+    client = ctx.obj['client']
+    output = ctx.obj['output']
+    if reason is not None and len(reason.strip()) < CANCEL_REASON_MIN_LENGTH:
+        raise click.BadParameter(
+            f'must be at least {CANCEL_REASON_MIN_LENGTH} characters', param_hint='--reason')
+    body = {'reason': reason} if reason else None
+    try:
+        result = client.request('POST', f'/runs/{run_id}/cancel', json_body=body)
+    except ApiError as error:
+        render_error(error, output)
+        raise SystemExit(error.exit_code)
+    render(result, output)
+
+
+@run.command('output')
+@click.argument('run_id', type=int)
+@click.argument('sample_id', type=int)
+@click.option('--regression', 'regression_id', type=int, default=None,
+              help='Regression test id (auto-resolved if omitted).')
+@click.option('--output', 'output_id', type=int, default=None,
+              help='Output file id (auto-resolved if omitted).')
+@click.option('--side', type=click.Choice(('expected', 'actual')), default='actual',
+              show_default=True, help='Which side of the comparison to fetch.')
+@click.option('--format', 'fmt', default=None, help='Response format accepted by the API.')
+@click.pass_context
+def run_output(ctx: click.Context, run_id: int, sample_id: int, regression_id: Optional[int],
+               output_id: Optional[int], side: str, fmt: Optional[str]) -> None:
+    """Fetch one side of a result's output file.
+
+    Resolves the (media sample, regression, output) ids the same way `sp run
+    diff` does, so the hidden ids the web UI needs are not required here.
+
+    Note: for an output that matched, the API answers ``actual`` with a 303
+    redirect to ``expected`` -- requests follows it, so the expected content is
+    what comes back.
+    """
+    client = ctx.obj['client']
+    output = ctx.obj['output']
+    try:
+        targets = _resolve_diff_targets(client, run_id, sample_id, regression_id, output_id)
+        if not targets:
+            raise ApiError('not_found', 'No output to fetch for this result', 404)
+        media_sample_id, reg_id, out_id = targets[0]
+        payload = client.get(
+            f'/runs/{run_id}/samples/{media_sample_id}'
+            f'/regression-tests/{reg_id}/outputs/{out_id}/{side}',
+            params=clean_params({'format': fmt}))
+    except ApiError as error:
+        render_error(error, output)
+        raise SystemExit(error.exit_code)
+    render(payload, output)
+
+
 @run.command('artifacts')
 @click.argument('run_id', type=int)
 @click.pass_context

sp_cli/commands/sample.py

@@ -4,6 +4,8 @@
 
 import click
 
+from sp_cli.constants import (PLATFORMS, SAMPLE_CATALOG_STATUSES,
+                              SAMPLE_STATUSES)
 from sp_cli.runner import clean_params, fetch_and_render
 
 
@@ -13,17 +15,21 @@ def sample() -> None:
 
 
 @sample.command('ls')
-@click.option('--name', default=None, help='Filter by sample name.')
+@click.option('--name', default=None, help='Substring match on the original sample name.')
 @click.option('--tag', default=None, help='Filter by tag.')
 @click.option('--extension', default=None, help='Filter by file extension.')
+@click.option('--sha256', default=None, help='Filter by exact SHA-256 hash.')
+@click.option('--status', type=click.Choice(SAMPLE_CATALOG_STATUSES), default=None,
+              help='Catalog visibility, not a test outcome.')
 @click.option('--limit', type=int, default=None, help='Page size (max 100).')
 @click.option('--offset', type=int, default=None, help='Pagination offset.')
 @click.pass_context
-def sample_ls(ctx: click.Context, name: Optional[str], tag: Optional[str],
-              extension: Optional[str], limit: Optional[int], offset: Optional[int]) -> None:
+def sample_ls(ctx: click.Context, name: Optional[str], tag: Optional[str], extension: Optional[str],
+              sha256: Optional[str], status: Optional[str],
+              limit: Optional[int], offset: Optional[int]) -> None:
     """List known media samples."""
-    params = clean_params({'name': name, 'tag': tag, 'extension': extension,
-                           'limit': limit, 'offset': offset})
+    params = clean_params({'name': name, 'tag': tag, 'extension': extension, 'sha256': sha256,
+                           'status': status, 'limit': limit, 'offset': offset})
     fetch_and_render(ctx, '/samples', params)
 
 
@@ -37,11 +43,27 @@ def sample_show(ctx: click.Context, sample_id: int) -> None:
 
 @sample.command('history')
 @click.argument('sample_id', type=int)
-@click.option('--platform', default=None, help='linux|windows')
+@click.option('--platform', type=click.Choice(PLATFORMS), default=None, help='Test platform.')
+@click.option('--branch', default=None, help='Filter by branch name.')
+@click.option('--status', type=click.Choice(SAMPLE_STATUSES), default=None,
+              help='Filter by this sample\'s outcome in each run.')
+@click.option('--created-after', 'created_after', default=None,
+              help='Only runs first seen at/after this time (ISO 8601).')
+@click.option('--created-before', 'created_before', default=None,
+              help='Only runs first seen at/before this time (ISO 8601).')
 @click.option('--limit', type=int, default=None, help='Page size (max 100).')
+@click.option('--offset', type=int, default=None, help='Pagination offset.')
 @click.pass_context
 def sample_history(ctx: click.Context, sample_id: int, platform: Optional[str],
-                   limit: Optional[int]) -> None:
-    """Show this sample's result history across runs."""
-    params = clean_params({'platform': platform, 'limit': limit})
+                   branch: Optional[str], status: Optional[str], created_after: Optional[str],
+                   created_before: Optional[str], limit: Optional[int],
+                   offset: Optional[int]) -> None:
+    """Show this sample's result history across runs.
+
+    Each entry carries a ``failure_signature``, which is what separates a real
+    regression from an infra flake that happens to fail the same test.
+    """
+    params = clean_params({'platform': platform, 'branch': branch, 'status': status,
+                           'created_after': created_after, 'created_before': created_before,
+                           'limit': limit, 'offset': offset})
     fetch_and_render(ctx, f'/samples/{sample_id}/history', params)

sp_cli/commands/system.py

@@ -4,6 +4,7 @@
 
 import click
 
+from sp_cli.constants import PLATFORMS, QUEUE_STATUSES
 from sp_cli.runner import clean_params, fetch_and_render
 
 
@@ -15,9 +16,19 @@ def health(ctx: click.Context) -> None:
 
 
 @click.command('queue')
-@click.option('--platform', default=None, help='linux|windows')
-@click.option('--status', default=None, help='queued|running')
+@click.option('--platform', type=click.Choice(PLATFORMS), default=None, help='Test platform.')
+@click.option('--status', type=click.Choice(QUEUE_STATUSES), default=None,
+              help='Restrict to one side of the queue.')
+@click.option('--limit', type=int, default=None, help='Page size (max 100).')
+@click.option('--offset', type=int, default=None, help='Pagination offset.')
 @click.pass_context
-def queue(ctx: click.Context, platform: Optional[str], status: Optional[str]) -> None:
-    """Show queue depth and currently running jobs."""
-    fetch_and_render(ctx, '/system/queue', clean_params({'platform': platform, 'status': status}))
+def queue(ctx: click.Context, platform: Optional[str], status: Optional[str],
+          limit: Optional[int], offset: Optional[int]) -> None:
+    """Show queue depth and currently running jobs.
+
+    Completed and canceled runs are excluded. The per-item ``position`` field
+    is only populated when ``--status queued`` is passed; otherwise it is null.
+    """
+    params = clean_params({'platform': platform, 'status': status,
+                           'limit': limit, 'offset': offset})
+    fetch_and_render(ctx, '/system/queue', params)