avr-cli 0.4.0__tar.gz → 0.4.1__tar.gz

{avr_cli-0.4.0 → avr_cli-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: avr-cli
-Version: 0.4.0
+Version: 0.4.1
 Summary: Avrea command-line client
 Author-email: Avrea <support@avrea.com>
 License-Expression: Apache-2.0

{avr_cli-0.4.0 → avr_cli-0.4.1}/avr_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: avr-cli
-Version: 0.4.0
+Version: 0.4.1
 Summary: Avrea command-line client
 Author-email: Avrea <support@avrea.com>
 License-Expression: Apache-2.0

{avr_cli-0.4.0 → avr_cli-0.4.1}/avrea_cli/_build_info.py

@@ -1,2 +1,2 @@
 # Auto-generated by .github/workflows/release.yml; do not edit.
-GIT_COMMIT = "5d74471e85fe9ce7a40209ef3daebaad435c38d8"
+GIT_COMMIT = "de175ab9edd3880dab9a4eb3614fff64c9015397"

{avr_cli-0.4.0 → avr_cli-0.4.1}/avrea_cli/commands/sbom.py

@@ -30,6 +30,8 @@ import shlex
 import time
 
 _COMMIT_SHA_RE = re.compile(r"^(?:[0-9a-f]{40}|[0-9a-f]{64})$")
+_COMMIT_PREFIX_RE = re.compile(r"^[0-9a-f]{7,64}$")
+_HISTORY_PAGE_LIMIT = 1000
 
 _ARTIFACT_FILENAMES = {
     "cyclonedx": "bom.cyclonedx.json",
@@ -55,8 +57,8 @@ def _validate_commit(_ctx: click.Context, _param: click.Parameter, value: str |
     if value is None:
         return None
     sha = value.strip().lower()
-    if not _COMMIT_SHA_RE.match(sha):
-        raise click.BadParameter("must be a full 40 or 64 character hex commit SHA.")
+    if not _COMMIT_PREFIX_RE.match(sha):
+        raise click.BadParameter("must be a hex commit SHA or a prefix of at least 7 characters.")
     return sha
 
 
@@ -70,14 +72,56 @@ def _strip_ref(_ctx: click.Context, _param: click.Parameter, value: str | None)
     return ref
 
 
+_commit_argument = click.argument("commit", required=False, callback=_validate_commit)
 _commit_option = click.option(
     "--commit",
-    "commit_sha",
+    "commit_option",
     callback=_validate_commit,
-    help="Full commit SHA of a recorded SBOM. Defaults to the latest SBOM.",
+    help="Same as the COMMIT argument.",
 )
 
 
+def _requested_commit(commit: str | None, commit_option: str | None) -> str | None:
+    if commit and commit_option and commit != commit_option:
+        raise click.UsageError("Pass the commit either as the COMMIT argument or with --commit, not both.")
+    return commit or commit_option
+
+
+def _resolve_commit(client: ApiClient, org_id: str, repo_id: str, commit: str) -> str:
+    """The full SHA for ``commit``, a full SHA or a prefix of one.
+
+    The API addresses SBOMs by full SHA only, so a prefix is matched against the
+    recorded history. Matching stops at a second hit, which already makes the
+    prefix ambiguous."""
+    if _COMMIT_SHA_RE.match(commit):
+        return commit
+    matches: list[str] = []
+    params: dict[str, Any] = {"limit": _HISTORY_PAGE_LIMIT}
+    while len(matches) < 2:
+        try:
+            response = client.public_get(_sbom_path(org_id, repo_id), params=params)
+        except httpx.HTTPStatusError as exc:
+            handle_http_error(exc, "list SBOMs")
+        for row in response.get("data", []):
+            sha = row.get("commit_sha") or ""
+            if sha.startswith(commit) and sha not in matches:
+                matches.append(sha)
+        next_cursor = (response.get("pagination") or {}).get("next_cursor")
+        if not next_cursor:
+            break
+        params = {"limit": _HISTORY_PAGE_LIMIT, "cursor": next_cursor}
+
+    if not matches:
+        raise click.ClickException(
+            f"No recorded SBOM matches commit {commit}. Run `avr sbom list` to see the recorded commits."
+        )
+    if len(matches) > 1:
+        raise click.ClickException(
+            f"Commit {commit} is ambiguous; it matches {matches[0]} and {matches[1]}. Use a longer prefix."
+        )
+    return matches[0]
+
+
 def _resolve_scope(ctx: click.Context, org_id: str | None, repo_id: str | None) -> tuple[ApiClient, str, str]:
     client: ApiClient = ctx.obj["client"]
     config: CliConfig = ctx.obj["config"]
@@ -239,18 +283,23 @@ _SBOM_VIEW_FIELDS = make_schema(
 
 
 @sbom.command("view")
+@_commit_argument
 @_repo_option
 @_org_option
 @_commit_option
 @json_options
 @click.pass_context
-def sbom_view(ctx, repo_id, org_id, commit_sha, json_fields, jq_expr):
+def sbom_view(ctx, commit, repo_id, org_id, commit_option, json_fields, jq_expr):
     """Show an SBOM's summary: dependency counts, licences, and artifacts.
 
+    COMMIT is the commit of a recorded SBOM, as a full SHA or a unique prefix
+    of at least 7 characters such as the one `avr sbom list` shows. Defaults to
+    the latest SBOM.
+
     \b
     Examples:
         avr sbom view --repo acme/api
-        avr sbom view --repo acme/api --commit 3f2c...e91a
+        avr sbom view 3f2c9a1b7d04 --repo acme/api
         avr sbom view --repo acme/api --json summary --jq .summary.licenses
 
     \b
@@ -260,7 +309,10 @@ def sbom_view(ctx, repo_id, org_id, commit_sha, json_fields, jq_expr):
     """
     if handle_json_meta(json_fields, jq_expr, _SBOM_VIEW_FIELDS):
         return
+    commit_sha = _requested_commit(commit, commit_option)
     client, org_id, repo_id = _resolve_scope(ctx, org_id, repo_id)
+    if commit_sha is not None:
+        commit_sha = _resolve_commit(client, org_id, repo_id, commit_sha)
     snapshot = _fetch_snapshot(client, org_id, repo_id, commit_sha)
 
     if json_fields is not None:
@@ -276,12 +328,11 @@ def sbom_view(ctx, repo_id, org_id, commit_sha, json_fields, jq_expr):
             "avr",
             "sbom",
             "download",
+            snapshot.get("commit_sha", ""),
             "--org",
             org_id,
             "--repo",
             repo_id,
-            "--commit",
-            snapshot.get("commit_sha", ""),
             "--format",
             "inventory",
         ]
@@ -342,6 +393,7 @@ def sbom_view(ctx, repo_id, org_id, commit_sha, json_fields, jq_expr):
 
 
 @sbom.command("download")
+@_commit_argument
 @_repo_option
 @_org_option
 @_commit_option
@@ -360,18 +412,25 @@ def sbom_view(ctx, repo_id, org_id, commit_sha, json_fields, jq_expr):
     help='Output file path, or "-" for stdout. Defaults to the artifact filename in the current directory.',
 )
 @click.pass_context
-def sbom_download(ctx, repo_id, org_id, commit_sha, artifact_format, out_path):
+def sbom_download(ctx, commit, repo_id, org_id, commit_option, artifact_format, out_path):
     """Download an SBOM artifact (CycloneDX, SPDX, or dependency inventory).
 
+    COMMIT is the commit of a recorded SBOM, as a full SHA or a unique prefix
+    of at least 7 characters such as the one `avr sbom list` shows. Defaults to
+    the latest SBOM.
+
     \b
     Examples:
         avr sbom download --repo acme/api
         avr sbom download --repo acme/api --format spdx --out api.spdx.json
-        avr sbom download --repo acme/api --commit 3f2c...e91a --out - | jq .components
+        avr sbom download 3f2c9a1b7d04 --repo acme/api --out - | jq .components
     """
+    commit_sha = _requested_commit(commit, commit_option)
     client, org_id, repo_id = _resolve_scope(ctx, org_id, repo_id)
     if commit_sha is None:
         commit_sha = _fetch_snapshot(client, org_id, repo_id, None)["commit_sha"]
+    else:
+        commit_sha = _resolve_commit(client, org_id, repo_id, commit_sha)
 
     filename = _ARTIFACT_FILENAMES[artifact_format]
     try:
@@ -508,14 +567,10 @@ class _TaskTracker:
 
 
 @sbom.command("generate")
+@click.argument("ref", required=False, callback=_strip_ref)
 @_repo_option
 @_org_option
-@click.option(
-    "--ref",
-    default=None,
-    callback=_strip_ref,
-    help="Branch, tag, or commit SHA to analyse. Defaults to the default-branch tip.",
-)
+@click.option("--ref", "ref_option", default=None, callback=_strip_ref, help="Same as the REF argument.")
 @click.option("--wait", is_flag=True, default=False, help="Wait until generation finishes before returning.")
 @click.option(
     "--wait-timeout",
@@ -526,17 +581,22 @@ class _TaskTracker:
 )
 @json_options
 @click.pass_context
-def sbom_generate(ctx, repo_id, org_id, ref, wait, wait_timeout, json_fields, jq_expr):
+def sbom_generate(ctx, ref, repo_id, org_id, ref_option, wait, wait_timeout, json_fields, jq_expr):
     """Start SBOM generation for a repository.
 
+    REF is the branch, tag, or commit SHA to analyse; an abbreviated SHA such
+    as the one `avr sbom list` shows works too. Defaults to the default-branch
+    tip. Without --wait, commit_sha is the full SHA of the commit the run
+    analyses when REF is a full SHA or one the API expanded.
+
     One analysis runs per repository at a time. A request for the same ref as
     the analysis already running joins it; a request for a different ref is
     rejected (HTTP 409) until that analysis finishes. Once an SBOM has been
     recorded for the repository, a new run is refused (HTTP 429) for a
     cooldown period, and the error says how many seconds remain.
 
-    With --wait and --ref set to a full commit SHA, success means a new SBOM
-    for that commit is downloadable, whatever the analysis task's own outcome
+    With --wait and a REF that names a commit, success means a new SBOM for
+    that commit is downloadable, whatever the analysis task's own outcome
     (task_status); commit_sha and recorded_at identify it. A failed analysis
     can still deliver its SBOM later, so such a wait runs to --wait-timeout
     before reporting failure. For a branch, tag, or the default branch the API
@@ -547,8 +607,8 @@ def sbom_generate(ctx, repo_id, org_id, ref, wait, wait_timeout, json_fields, jq
     \b
     Examples:
         avr sbom generate --repo acme/api
-        avr sbom generate --repo acme/api --ref v1.4.0
-        avr sbom generate --repo acme/api --ref "$(git rev-parse HEAD)" --wait
+        avr sbom generate v1.4.0 --repo acme/api
+        avr sbom generate 3f2c9a1b7d04 --repo acme/api --wait
 
     \b
     JSON FIELDS
@@ -556,6 +616,9 @@ def sbom_generate(ctx, repo_id, org_id, ref, wait, wait_timeout, json_fields, jq
     """
     if handle_json_meta(json_fields, jq_expr, _SBOM_GENERATE_FIELDS):
         return
+    if ref and ref_option and ref != ref_option:
+        raise click.UsageError("Pass the ref either as the REF argument or with --ref, not both.")
+    ref = ref or ref_option
     output = _JsonOutput(
         fields=split_fields(json_fields, _SBOM_GENERATE_FIELDS) if json_fields is not None else [],
         jq_expr=jq_expr,
@@ -585,13 +648,20 @@ def sbom_generate(ctx, repo_id, org_id, ref, wait, wait_timeout, json_fields, jq
         "recorded_at": None,
     }
 
+    expanded_sha = response.get("commit_sha")
+    expanded = commit_sha is None and isinstance(expanded_sha, str) and _COMMIT_SHA_RE.match(expanded_sha)
+    if expanded:
+        commit_sha = expanded_sha
+
     if not wait:
+        result["commit_sha"] = commit_sha
         if output.emit(result):
             return
+        target = f" for {commit_sha[:12]}" if commit_sha else ""
         if result["status"] == "already_running":
-            click.echo(f"SBOM generation already running (task {task_id}); joined it.")
+            click.echo(f"SBOM generation already running{target} (task {task_id}); joined it.")
         else:
-            click.echo(f"SBOM generation started (task {task_id}).")
+            click.echo(f"SBOM generation started{target} (task {task_id}).")
         click.echo("Generation takes a few minutes; run `avr sbom view` afterwards to see the result.", err=True)
         return
 
@@ -603,8 +673,13 @@ def sbom_generate(ctx, repo_id, org_id, ref, wait, wait_timeout, json_fields, jq
         _wait_for_task_outcome(waiter)
         return
     snapshot_path = f"{_sbom_path(org_id, repo_id)}/commits/{commit_sha}"
+    if expanded:
+        # The API expanded an abbreviated SHA, so the baseline is read only now,
+        # after the run has started; retry it like the wait's own reads.
+        baseline = _snapshot_after_request(waiter, snapshot_path, commit_sha)
     baseline_recorded_at = baseline.get("recorded_at") if baseline else None
-    _wait_for_commit_delivery(waiter, snapshot_path, commit_sha, baseline_recorded_at)
+    view_command = shlex.join(["avr", "sbom", "view", commit_sha, "--org", org_id, "--repo", repo_id])
+    _wait_for_commit_delivery(waiter, snapshot_path, commit_sha, baseline_recorded_at, view_command)
 
 
 @dataclass(frozen=True)
@@ -647,6 +722,16 @@ class _Wait:
         raise SystemExit(1)
 
 
+def _snapshot_after_request(waiter: _Wait, snapshot_path: str, commit_sha: str) -> dict[str, Any] | None:
+    """The commit's current snapshot, or None; transient errors retry until the deadline."""
+    while True:
+        try:
+            return waiter.poller.get(snapshot_path, action="check for the commit's SBOM", missing_ok=True)
+        except _TransientPollError as exc:
+            if not waiter.poller.sleep(exc.backoff):
+                waiter.time_out(f"the SBOM for {commit_sha[:12]} could not be checked")
+
+
 def _wait_for_task_outcome(waiter: _Wait) -> None:
     """Report the analysis task's own outcome; no SBOM can be attributed to it."""
     tracker = waiter.tracker
@@ -690,7 +775,7 @@ def _echo_task_outcome(tracker: _TaskTracker) -> None:
 
 
 def _wait_for_commit_delivery(
-    waiter: _Wait, snapshot_path: str, commit_sha: str, baseline_recorded_at: str | None
+    waiter: _Wait, snapshot_path: str, commit_sha: str, baseline_recorded_at: str | None, view_command: str
 ) -> None:
     """Wait for the commit's SBOM to be recorded after the baseline.
 
@@ -731,7 +816,7 @@ def _wait_for_commit_delivery(
             "producing the SBOM.",
             err=True,
         )
-    click.echo(f"SBOM generated for {short_sha}. Run `avr sbom view --commit {commit_sha}` to see it.")
+    click.echo(f"SBOM generated for {short_sha}. Run `{view_command}` to see it.")
 
 
 def _echo_undelivered(tracker: _TaskTracker, short_sha: str, wait_timeout: int) -> None:

{avr_cli-0.4.0 → avr_cli-0.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "avr-cli"
-version = "0.4.0"
+version = "0.4.1"
 description = "Avrea command-line client"
 authors = [{ name = "Avrea", email = "support@avrea.com" }]
 readme = "README.md"

{avr_cli-0.4.0 → avr_cli-0.4.1}/tests/test_sbom.py

@@ -67,6 +67,7 @@ HISTORY = {
     ],
     "pagination": {"next_cursor": "Y3Vyc29y"},
 }
+HISTORY_LAST_PAGE = {**HISTORY, "pagination": {"next_cursor": None}}
 
 
 def _http_error(status: int, detail: str = "", headers: dict[str, str] | None = None) -> httpx.HTTPStatusError:
@@ -201,12 +202,37 @@ class TestSbomView:
         assert result.exit_code == 0, result.output
         assert calls.log[-1][1] == f"{BASE}/commits/{SHA}"
 
-    def test_rejects_short_commit(self, runner, calls):
-        result = runner.invoke(cli, ["sbom", "view", "--repo", "rep-123", "--commit", "abc123"])
+    def test_commit_as_argument(self, runner, calls):
+        calls.route("GET", f"{BASE}/commits/{SHA}", SNAPSHOT)
+        result = runner.invoke(cli, ["sbom", "view", SHA, "--repo", "rep-123"])
+        assert result.exit_code == 0, result.output
+        assert calls.log[-1][1] == f"{BASE}/commits/{SHA}"
+
+    def test_short_commit_resolves_through_history(self, runner, calls):
+        calls.route("GET", BASE, HISTORY_LAST_PAGE)
+        calls.route("GET", f"{BASE}/commits/{SHA}", SNAPSHOT)
+        result = runner.invoke(cli, ["sbom", "view", SHA[:12], "--repo", "rep-123"])
+        assert result.exit_code == 0, result.output
+        assert calls.log[-1][1] == f"{BASE}/commits/{SHA}"
+
+    @pytest.mark.parametrize("commit", ["abc123", "xyz1234567", "a" * 65, " "])
+    def test_rejects_invalid_commit(self, runner, calls, commit):
+        result = runner.invoke(cli, ["sbom", "view", "--repo", "rep-123", "--commit", commit])
+        assert result.exit_code == 2
+        assert "at least 7" in result.output
+        assert calls.log == []
+
+    def test_rejects_conflicting_commit_argument_and_option(self, runner, calls):
+        result = runner.invoke(cli, ["sbom", "view", SHA, "--repo", "rep-123", "--commit", OTHER_SHA])
         assert result.exit_code == 2
-        assert "40 or 64" in result.output
+        assert "--commit" in result.output
         assert calls.log == []
 
+    def test_accepts_same_commit_as_argument_and_option(self, runner, calls):
+        calls.route("GET", f"{BASE}/commits/{SHA}", SNAPSHOT)
+        result = runner.invoke(cli, ["sbom", "view", SHA, "--repo", "rep-123", "--commit", SHA.upper()])
+        assert result.exit_code == 0, result.output
+
     def test_not_found_hints_generate(self, runner, calls):
         calls.route("GET", f"{BASE}/latest", _http_error(404, "analysis result not found"))
         result = runner.invoke(cli, ["sbom", "view", "--repo", "rep-123"])
@@ -251,14 +277,14 @@ class TestSbomView:
         omitted = {"omitted": "oversized", "serialized_bytes": 143362}
         calls.route("GET", f"{BASE}/commits/{SHA}", {**SNAPSHOT, "summary": omitted})
         result = runner.invoke(cli, ["sbom", "view", "--repo", "rep-123", "--commit", SHA])
-        expected = f"avr sbom download --org org-default --repo rep-123 --commit {SHA} --format inventory"
+        expected = f"avr sbom download {SHA} --org org-default --repo rep-123 --format inventory"
         assert expected in result.output
 
     def test_copyleft_overflow_hint_pins_the_viewed_snapshot(self, runner, calls):
         summary = {**SUMMARY, "copyleft": ["a"], "copyleft_omitted": 3}
         calls.route("GET", f"{BASE}/latest", {**SNAPSHOT, "summary": summary})
         result = runner.invoke(cli, ["sbom", "view", "--repo", "rep-123"])
-        expected = f"avr sbom download --org org-default --repo rep-123 --commit {SHA} --format inventory"
+        expected = f"avr sbom download {SHA} --org org-default --repo rep-123 --format inventory"
         assert expected in result.output
 
     def test_inventory_hint_quotes_values_for_the_shell(self, runner, calls):
@@ -353,6 +379,72 @@ class TestSbomDownload:
         assert "no artifact" in result.output
         assert not (tmp_path / "x").exists()
 
+    def test_short_commit_argument_downloads_the_resolved_commit(self, runner, calls):
+        calls.route("GET", BASE, HISTORY_LAST_PAGE)
+        calls.route("GET_BYTES", f"{BASE}/commits/{SHA}/artifacts/bom.cyclonedx.json", b'{"ok":true}')
+        result = runner.invoke(cli, ["sbom", "download", SHA[:12], "--repo", "rep-123", "--out", "-"])
+        assert result.exit_code == 0, result.output
+        assert result.stdout == '{"ok":true}'
+        assert calls.log[-1] == ("GET_BYTES", f"{BASE}/commits/{SHA}/artifacts/bom.cyclonedx.json", None)
+
+
+AMBIGUOUS_SHA = "a" * 12 + "f" * 28
+
+
+def _history_page(*shas: str, next_cursor: str | None = None) -> dict[str, Any]:
+    return {"data": [{"commit_sha": sha} for sha in shas], "pagination": {"next_cursor": next_cursor}}
+
+
+class TestSbomCommitPrefix:
+    def test_full_commit_skips_history(self, runner, calls):
+        calls.route("GET_BYTES", f"{BASE}/commits/{SHA}/artifacts/bom.cyclonedx.json", b"{}")
+        result = runner.invoke(cli, ["sbom", "download", SHA, "--repo", "rep-123", "--out", "-"])
+        assert result.exit_code == 0, result.output
+        assert [c[0] for c in calls.log] == ["GET_BYTES"]
+
+    def test_prefix_is_case_insensitive(self, runner, calls):
+        calls.route("GET", BASE, HISTORY_LAST_PAGE)
+        calls.route("GET_BYTES", f"{BASE}/commits/{SHA}/artifacts/bom.cyclonedx.json", b"{}")
+        result = runner.invoke(cli, ["sbom", "download", SHA[:7].upper(), "--repo", "rep-123", "--out", "-"])
+        assert result.exit_code == 0, result.output
+
+    def test_resolution_pages_through_history(self, runner, calls):
+        calls.route("GET", BASE, [_history_page(OTHER_SHA, next_cursor="page2"), _history_page(SHA)])
+        calls.route("GET_BYTES", f"{BASE}/commits/{SHA}/artifacts/bom.cyclonedx.json", b"{}")
+        result = runner.invoke(cli, ["sbom", "download", SHA[:7], "--repo", "rep-123", "--out", "-"])
+        assert result.exit_code == 0, result.output
+        history_params = [c[2] for c in calls.log if c[:2] == ("GET", BASE)]
+        assert history_params == [{"limit": 1000}, {"limit": 1000, "cursor": "page2"}]
+
+    def test_unknown_prefix_names_the_list_command(self, runner, calls):
+        calls.route("GET", BASE, _history_page(OTHER_SHA))
+        result = runner.invoke(cli, ["sbom", "download", SHA[:7], "--repo", "rep-123"])
+        assert result.exit_code == 1
+        assert SHA[:7] in result.output
+        assert "avr sbom list" in result.output
+        assert [c[0] for c in calls.log] == ["GET"]
+
+    def test_ambiguous_prefix_lists_candidates(self, runner, calls):
+        calls.route("GET", BASE, [_history_page(SHA, next_cursor="page2"), _history_page(AMBIGUOUS_SHA)])
+        result = runner.invoke(cli, ["sbom", "view", SHA[:10], "--repo", "rep-123"])
+        assert result.exit_code == 1
+        assert "ambiguous" in result.output
+        assert SHA in result.output
+        assert AMBIGUOUS_SHA in result.output
+
+    def test_longer_prefix_disambiguates(self, runner, calls):
+        calls.route("GET", BASE, _history_page(SHA, AMBIGUOUS_SHA))
+        calls.route("GET", f"{BASE}/commits/{SHA}", SNAPSHOT)
+        result = runner.invoke(cli, ["sbom", "view", SHA[:13], "--repo", "rep-123"])
+        assert result.exit_code == 0, result.output
+        assert calls.log[-1][1] == f"{BASE}/commits/{SHA}"
+
+    def test_history_error_is_reported(self, runner, calls):
+        calls.route("GET", BASE, _http_error(403, "forbidden"))
+        result = runner.invoke(cli, ["sbom", "view", SHA[:7], "--repo", "rep-123"])
+        assert result.exit_code == 1
+        assert "forbidden" in result.output
+
 
 STATE_PATH = "/orgs/org-default/repos/rep-123/ai-task/state"
 LATEST = f"{BASE}/latest"
@@ -587,6 +679,7 @@ class TestSbomGenerateWaitForCommit:
         result = runner.invoke(cli, ["sbom", "generate", "--repo", "rep-123", "--ref", NEW_SHA, "--wait"])
         assert result.exit_code == 0, result.output
         assert f"SBOM generated for {NEW_SHA[:12]}" in result.output
+        assert f"avr sbom view {NEW_SHA} --org org-default --repo rep-123" in result.output
 
     def test_unrelated_snapshot_arrival_does_not_satisfy_wait(self, runner, calls):
         calls.route("GET", COMMIT_PATH, PRIOR_FOR_COMMIT)
@@ -725,6 +818,100 @@ class TestSbomGenerateWaitForCommit:
         assert calls.log == []
 
 
+SHORT_NEW_SHA = NEW_SHA[:12]
+
+
+class TestSbomGenerateRefArgument:
+    def test_usage_shows_ref_as_optional(self, runner):
+        result = runner.invoke(cli, ["sbom", "generate", "--help"])
+        assert "generate [OPTIONS] [REF]" in result.output
+
+    def test_ref_as_argument(self, runner, calls):
+        calls.route("POST", f"{BASE}/generate", {"ai_task_id": "task-1", "status": "generating"})
+        result = runner.invoke(cli, ["sbom", "generate", "v1.2.0", "--repo", "rep-123"])
+        assert result.exit_code == 0, result.output
+        assert calls.log[-1][2] == {"scope": "sbom", "ref": "v1.2.0"}
+
+    def test_rejects_conflicting_ref_argument_and_option(self, runner, calls):
+        result = runner.invoke(cli, ["sbom", "generate", "v1.2.0", "--repo", "rep-123", "--ref", "main"])
+        assert result.exit_code == 2
+        assert "REF argument or with --ref, not both" in result.output
+        assert calls.log == []
+
+    def test_short_sha_is_sent_for_the_api_to_expand(self, runner, calls):
+        calls.route("POST", f"{BASE}/generate", {"ai_task_id": "task-1", "status": "generating"})
+        result = runner.invoke(cli, ["sbom", "generate", SHORT_NEW_SHA, "--repo", "rep-123"])
+        assert result.exit_code == 0, result.output
+        assert calls.log == [("POST", f"{BASE}/generate", {"scope": "sbom", "ref": SHORT_NEW_SHA})]
+
+    def test_wait_follows_the_commit_the_api_expanded(self, runner, calls):
+        calls.route("POST", f"{BASE}/generate", {"ai_task_id": "task-1", "status": "generating", "commit_sha": NEW_SHA})
+        calls.route("GET", COMMIT_PATH, [_http_error(404, "analysis result not found"), NEW_SNAPSHOT])
+        calls.route("GET", STATE_PATH, {"ai_task_id": "task-1", "status": "RUNNING"})
+        result = runner.invoke(
+            cli, ["sbom", "generate", SHORT_NEW_SHA, "--repo", "rep-123", "--wait", "--json", "status,commit_sha"]
+        )
+        assert result.exit_code == 0, result.output
+        assert json.loads(result.stdout) == {"status": "completed", "commit_sha": NEW_SHA}
+        assert [c[1] for c in calls.log[:2]] == [f"{BASE}/generate", COMMIT_PATH]
+
+    def test_wait_for_an_expanded_commit_needs_a_new_delivery(self, runner, calls):
+        calls.route("POST", f"{BASE}/generate", {"ai_task_id": "task-1", "status": "generating", "commit_sha": NEW_SHA})
+        calls.route("GET", COMMIT_PATH, [PRIOR_FOR_COMMIT, PRIOR_FOR_COMMIT, NEW_SNAPSHOT])
+        calls.route("GET", STATE_PATH, {"ai_task_id": "task-1", "status": "RUNNING"})
+        result = runner.invoke(
+            cli, ["sbom", "generate", SHORT_NEW_SHA, "--repo", "rep-123", "--wait", "--json", "recorded_at"]
+        )
+        assert result.exit_code == 0, result.output
+        assert json.loads(result.stdout) == {"recorded_at": NEW_SNAPSHOT["recorded_at"]}
+
+    @pytest.mark.parametrize("expanded", [{}, {"commit_sha": None}, {"commit_sha": SHORT_NEW_SHA}])
+    def test_wait_follows_the_task_without_an_expanded_commit(self, runner, calls, expanded):
+        calls.route("POST", f"{BASE}/generate", {"ai_task_id": "task-1", "status": "generating", **expanded})
+        calls.route("GET", STATE_PATH, {"ai_task_id": "task-1", "status": "COMPLETED"})
+        result = runner.invoke(
+            cli, ["sbom", "generate", SHORT_NEW_SHA, "--repo", "rep-123", "--wait", "--json", "status,commit_sha"]
+        )
+        assert result.exit_code == 0, result.output
+        assert json.loads(result.stdout) == {"status": "completed", "commit_sha": None}
+        assert all("/commits/" not in c[1] for c in calls.log)
+
+    @pytest.mark.parametrize("failure", [_http_error(503), httpx.ConnectError("connection reset")])
+    def test_baseline_after_the_request_retries_transient_errors(self, runner, calls, failure):
+        calls.route("POST", f"{BASE}/generate", {"ai_task_id": "task-1", "status": "generating", "commit_sha": NEW_SHA})
+        calls.route("GET", COMMIT_PATH, [failure, PRIOR_FOR_COMMIT, PRIOR_FOR_COMMIT, NEW_SNAPSHOT])
+        calls.route("GET", STATE_PATH, {"ai_task_id": "task-1", "status": "RUNNING"})
+        result = runner.invoke(
+            cli, ["sbom", "generate", SHORT_NEW_SHA, "--repo", "rep-123", "--wait", "--json", "recorded_at"]
+        )
+        assert result.exit_code == 0, result.output
+        assert json.loads(result.stdout) == {"recorded_at": NEW_SNAPSHOT["recorded_at"]}
+
+    def test_baseline_after_the_request_that_never_succeeds_times_out(self, runner, calls):
+        calls.route("POST", f"{BASE}/generate", {"ai_task_id": "task-1", "status": "generating", "commit_sha": NEW_SHA})
+        calls.route("GET", COMMIT_PATH, _http_error(503))
+        args = ["sbom", "generate", SHORT_NEW_SHA, "--repo", "rep-123", "--wait", "--wait-timeout", "30"]
+        result = runner.invoke(cli, args)
+        assert result.exit_code == 1
+        assert f"the SBOM for {SHORT_NEW_SHA} could not be checked" in result.output
+        assert calls.now >= 30
+        assert all(c[1] != STATE_PATH for c in calls.log)
+
+    @pytest.mark.parametrize(("ref", "response"), [(SHORT_NEW_SHA, {"commit_sha": NEW_SHA}), (NEW_SHA, {})])
+    def test_reports_the_pinned_commit_without_wait(self, runner, calls, ref, response):
+        calls.route("POST", f"{BASE}/generate", {"ai_task_id": "task-1", "status": "generating", **response})
+        json_result = runner.invoke(cli, ["sbom", "generate", ref, "--repo", "rep-123", "--json", "commit_sha"])
+        human_result = runner.invoke(cli, ["sbom", "generate", ref, "--repo", "rep-123"])
+        assert json.loads(json_result.stdout) == {"commit_sha": NEW_SHA}
+        assert f"started for {NEW_SHA[:12]} (task task-1)" in human_result.output
+
+    @pytest.mark.parametrize("response", [{}, {"commit_sha": SHORT_NEW_SHA}])
+    def test_reports_no_commit_without_a_valid_expansion(self, runner, calls, response):
+        calls.route("POST", f"{BASE}/generate", {"ai_task_id": "task-1", "status": "generating", **response})
+        result = runner.invoke(cli, ["sbom", "generate", SHORT_NEW_SHA, "--repo", "rep-123", "--json", "commit_sha"])
+        assert json.loads(result.stdout) == {"commit_sha": None}
+
+
 RUNNING = {"ai_task_id": "task-1", "status": "RUNNING"}
 COMPLETED = {"ai_task_id": "task-1", "status": "COMPLETED"}
 UNPINNED_WAIT = ["sbom", "generate", "--repo", "rep-123", "--wait"]