charisma-cli 0.2.2__tar.gz → 0.3.1__tar.gz

{charisma_cli-0.2.2 → charisma_cli-0.3.1}/.gitignore

@@ -136,3 +136,7 @@ allure-results/*
 allure-results-live/
 *tasks.meta.json
 *.code-workspace
+
+# Session-specific work-state tracking (see .kiro update-work-state skill)
+.current-task.md
+.agents/pipeline-status.json

{charisma_cli-0.2.2 → charisma_cli-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: charisma-cli
-Version: 0.2.2
+Version: 0.3.1
 Summary: CLI tool that watches allure-results and streams test results + attachments to Charisma.
 Author: Charisma Team
 License-Expression: MIT
@@ -75,15 +75,31 @@ charismactl watch --results allure-results -- uv run pytest -n 4 tests/
 | `CHARISMA_TOKEN`      | Yes      | Service or CI bearer token                         |
 | `CHARISMA_PROJECT_ID` | Yes      | Project alias for result routing                   |
 | `CHARISMA_RESULTS`    | No       | Path to allure-results (default: `allure-results`) |
+| `CHARISMA_RUN_KEY`    | No       | Run identity / merge key (`--run-key` fallback)    |
+| `BUILD_ID`            | No       | CI build identifier (`--build-id` fallback; `CHARISMA_BUILD_ID` also honored) |
+| `BUILD_PLAN_KEY`      | No       | Build plan key (`--build-plan-key` fallback; `CHARISMA_BUILD_PLAN_KEY` also honored) |
+| `ENVIRONMENT`         | No       | Environment code (`--environment` fallback; `CHARISMA_ENVIRONMENT` also honored) |
+| `COMPONENT`           | No       | Component alias (`--component` fallback; `CHARISMA_COMPONENT` also honored) |
+| `SOURCE_URL`          | No       | CI/CD build link (`--source-url` fallback; `CHARISMA_SOURCE_URL` also honored) |
 
 ## Flags
 
-| Flag             | Description                                  |
-| ---------------- | -------------------------------------------- |
-| `--results PATH` | Allure results directory (overrides env var) |
-| `--project ID`   | Project alias (overrides env var)            |
-| `--silent`       | Don't fail pipeline if upload errors occur   |
-| `--skip-too-big` | Skip result files larger than 2MB            |
+Both `upload` and `watch` accept the identical option set.
+
+| Flag                 | Description                                                      |
+| -------------------- | --------------------------------------------------------------- |
+| `--endpoint URL`     | Charisma API endpoint (overrides `CHARISMA_ENDPOINT`)           |
+| `--token TOKEN`      | Bearer token (overrides `CHARISMA_TOKEN`)                       |
+| `--results PATH`     | Allure results directory (overrides env var)                    |
+| `--project ID`       | Project alias (overrides env var)                               |
+| `--silent`           | Don't fail pipeline if upload errors occur                      |
+| `--skip-too-big`     | Skip result files larger than 2MB                               |
+| `--component ALIAS`  | Component alias within the project                              |
+| `--source-url URL`   | CI/CD build link for this run                                   |
+| `--build-plan-key K` | Explicit build plan key for resolution (forwarded as `buildPlanKey`) |
+| `--build-id ID`      | CI build identifier for this run (forwarded as `buildId`)       |
+| `--environment ENV`  | Environment code (e.g. `qat`, `prod`), stored on the launch     |
+| `--run-key KEY`      | Run identity / merge key (reruns + parallel workers share it)   |
 
 ## Launch URL in CI
 

{charisma_cli-0.2.2 → charisma_cli-0.3.1}/README.md

@@ -50,15 +50,31 @@ charismactl watch --results allure-results -- uv run pytest -n 4 tests/
 | `CHARISMA_TOKEN`      | Yes      | Service or CI bearer token                         |
 | `CHARISMA_PROJECT_ID` | Yes      | Project alias for result routing                   |
 | `CHARISMA_RESULTS`    | No       | Path to allure-results (default: `allure-results`) |
+| `CHARISMA_RUN_KEY`    | No       | Run identity / merge key (`--run-key` fallback)    |
+| `BUILD_ID`            | No       | CI build identifier (`--build-id` fallback; `CHARISMA_BUILD_ID` also honored) |
+| `BUILD_PLAN_KEY`      | No       | Build plan key (`--build-plan-key` fallback; `CHARISMA_BUILD_PLAN_KEY` also honored) |
+| `ENVIRONMENT`         | No       | Environment code (`--environment` fallback; `CHARISMA_ENVIRONMENT` also honored) |
+| `COMPONENT`           | No       | Component alias (`--component` fallback; `CHARISMA_COMPONENT` also honored) |
+| `SOURCE_URL`          | No       | CI/CD build link (`--source-url` fallback; `CHARISMA_SOURCE_URL` also honored) |
 
 ## Flags
 
-| Flag             | Description                                  |
-| ---------------- | -------------------------------------------- |
-| `--results PATH` | Allure results directory (overrides env var) |
-| `--project ID`   | Project alias (overrides env var)            |
-| `--silent`       | Don't fail pipeline if upload errors occur   |
-| `--skip-too-big` | Skip result files larger than 2MB            |
+Both `upload` and `watch` accept the identical option set.
+
+| Flag                 | Description                                                      |
+| -------------------- | --------------------------------------------------------------- |
+| `--endpoint URL`     | Charisma API endpoint (overrides `CHARISMA_ENDPOINT`)           |
+| `--token TOKEN`      | Bearer token (overrides `CHARISMA_TOKEN`)                       |
+| `--results PATH`     | Allure results directory (overrides env var)                    |
+| `--project ID`       | Project alias (overrides env var)                               |
+| `--silent`           | Don't fail pipeline if upload errors occur                      |
+| `--skip-too-big`     | Skip result files larger than 2MB                               |
+| `--component ALIAS`  | Component alias within the project                              |
+| `--source-url URL`   | CI/CD build link for this run                                   |
+| `--build-plan-key K` | Explicit build plan key for resolution (forwarded as `buildPlanKey`) |
+| `--build-id ID`      | CI build identifier for this run (forwarded as `buildId`)       |
+| `--environment ENV`  | Environment code (e.g. `qat`, `prod`), stored on the launch     |
+| `--run-key KEY`      | Run identity / merge key (reruns + parallel workers share it)   |
 
 ## Launch URL in CI
 

{charisma_cli-0.2.2 → charisma_cli-0.3.1}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "charisma-cli"
-version = "0.2.2"
+version = "0.3.1"
 description = "CLI tool that watches allure-results and streams test results + attachments to Charisma."
 readme = "README.md"
 license = "MIT"

charisma_cli-0.3.1/src/charisma_cli/__init__.py

@@ -0,0 +1,7 @@
+"""charisma-cli: Stream allure results to Charisma in real time."""
+
+# Single source of truth for the CLI version. At build time the wheel metadata
+# is generated from pyproject.toml [project].version, so keeping this literal
+# equal to pyproject guarantees `--version` reports the published version. The
+# prepare-commit step owns the PATCH bump — do not hand-bump here.
+__version__ = "0.3.1"

charisma_cli-0.3.1/src/charisma_cli/config.py

@@ -0,0 +1,149 @@
+"""Configuration dataclass with env var + CLI flag resolution."""
+
+import os
+from dataclasses import dataclass
+
+import click
+
+
+def _resolve_env(bare_name: str) -> str | None:
+    """Resolve an env var by its bare name, falling back to the CHARISMA_ prefix.
+
+    Bare-name-first (e.g. ``BUILD_ID``) keeps parity with CI systems that export
+    generic build metadata, while the ``CHARISMA_`` prefixed form (e.g.
+    ``CHARISMA_BUILD_ID``) is honored as a namespaced fallback. Returns the first
+    non-empty value, or None.
+    """
+    for name in (bare_name, f"CHARISMA_{bare_name}"):
+        value = os.getenv(name)
+        if value and value.strip():
+            return value.strip()
+    return None
+
+
+@dataclass
+class Config:
+    """Resolved configuration for charismactl.
+
+    Fields are populated via from_env() which merges CLI flag overrides
+    with environment variable fallbacks.
+    """
+
+    endpoint: str
+    token: str
+    project: str
+    results_dir: str
+    silent: bool
+    skip_too_big: bool
+    drain_timeout: int
+    build_id: str | None
+    commit_sha: str | None
+    branch: str | None
+    component: str | None = None
+    source_url: str | None = None
+    build_plan_key: str | None = None
+    environment: str | None = None
+    name: str | None = None
+    tags: list[str] | None = None
+    run_key: str | None = None
+
+    @classmethod
+    def from_env(
+        cls,
+        *,
+        endpoint: str | None = None,
+        token: str | None = None,
+        project: str | None = None,
+        results: str | None = None,
+        silent: bool = False,
+        skip_too_big: bool = False,
+        drain_timeout: int = 30,
+        component: str | None = None,
+        source_url: str | None = None,
+        build_plan_key: str | None = None,
+        build_id: str | None = None,
+        environment: str | None = None,
+        run_key: str | None = None,
+    ) -> "Config":
+        """Build Config by resolving CLI flags over environment variables.
+
+        Resolution order: CLI flag (if not None) > env var > default.
+
+        Args:
+            endpoint: --endpoint flag override
+            token: --token flag override
+            project: --project flag override
+            results: --results flag override
+            silent: --silent flag
+            skip_too_big: --skip-too-big flag
+            drain_timeout: drain timeout in seconds
+            component: --component flag override (component alias within the
+                project). Env: COMPONENT, fallback CHARISMA_COMPONENT.
+            source_url: --source-url flag override (CI/CD build link). Env:
+                SOURCE_URL, fallback CHARISMA_SOURCE_URL.
+            build_plan_key: --build-plan-key flag override (explicit build plan
+                key). Env: BUILD_PLAN_KEY, fallback CHARISMA_BUILD_PLAN_KEY.
+            build_id: --build-id flag override (CI build identifier). Env:
+                BUILD_ID, fallback CHARISMA_BUILD_ID. Flag wins over env.
+            environment: --environment flag override (env code, e.g. "qat").
+                Persisted to the first-class launch environment column. Env:
+                ENVIRONMENT, fallback CHARISMA_ENVIRONMENT.
+            run_key: --run-key flag override. Client-supplied merge key: the
+                backend derives the launch id as uuid5(project/run_key) and
+                get-or-creates, so reruns and parallel producers sharing a key
+                land in one launch. Empty/whitespace resolves to None (a new
+                random launch, unchanged behavior).
+
+        Returns:
+            Fully resolved Config instance.
+
+        Raises:
+            click.UsageError: If required fields (endpoint, token) are missing.
+        """
+        # Connection config resolves from the CHARISMA_-prefixed name ONLY (no
+        # bare form): a generic ENDPOINT/TOKEN/PROJECT_ID/RUN_KEY in the
+        # environment must not silently reconfigure the client. Build/run
+        # metadata below uses _resolve_env (bare-first, prefixed fallback) so it
+        # picks up generic CI variables. Do NOT "unify" these — the split is
+        # intentional and mirrors pytest-charisma (bare_env_var=None for config).
+        resolved_endpoint = (endpoint or os.getenv("CHARISMA_ENDPOINT", "")).strip()
+        resolved_token = (token or os.getenv("CHARISMA_TOKEN", "")).strip()
+        resolved_project = (project or os.getenv("CHARISMA_PROJECT_ID", "")).strip()
+        resolved_results = results or os.getenv("CHARISMA_RESULTS", "allure-results")
+        resolved_run_key = (run_key or os.getenv("CHARISMA_RUN_KEY", "")).strip() or None
+        resolved_component = (component or _resolve_env("COMPONENT") or "").strip() or None
+        resolved_source_url = (source_url or _resolve_env("SOURCE_URL") or "").strip() or None
+        resolved_build_plan_key = (build_plan_key or _resolve_env("BUILD_PLAN_KEY") or "").strip() or None
+        resolved_build_id = (build_id or _resolve_env("BUILD_ID") or "").strip() or None
+        resolved_environment = (environment or _resolve_env("ENVIRONMENT") or "").strip() or None
+        # Human-readable launch name (LAUNCH_NAME) and comma-separated tags
+        # (TAGS, e.g. "CI/CD,performance") shown on the Launches page.
+        resolved_name = (_resolve_env("LAUNCH_NAME") or "").strip() or None
+        resolved_tags = [t.strip() for t in (_resolve_env("TAGS") or "").split(",") if t.strip()] or None
+
+        if not resolved_endpoint:
+            raise click.UsageError(
+                "Missing required configuration: endpoint. Set CHARISMA_ENDPOINT or pass --endpoint."
+            )
+        if not resolved_token:
+            raise click.UsageError("Missing required configuration: token. Set CHARISMA_TOKEN or pass --token.")
+
+        return cls(
+            endpoint=resolved_endpoint,
+            token=resolved_token,
+            project=resolved_project,
+            results_dir=resolved_results,
+            silent=silent,
+            skip_too_big=skip_too_big,
+            drain_timeout=drain_timeout,
+            build_id=resolved_build_id,
+            commit_sha=_resolve_env("COMMIT_SHA"),
+            branch=_resolve_env("BRANCH"),
+            component=resolved_component,
+            source_url=resolved_source_url,
+            build_plan_key=resolved_build_plan_key,
+            environment=resolved_environment,
+            name=resolved_name,
+            tags=resolved_tags,
+            run_key=resolved_run_key,
+        )

{charisma_cli-0.2.2 → charisma_cli-0.3.1}/src/charisma_cli/main.py

@@ -2,6 +2,7 @@
 
 import signal
 import sys
+from collections.abc import Callable
 from pathlib import Path
 from queue import PriorityQueue
 
@@ -39,6 +40,12 @@ def _resolve_config(
     results: str,
     silent: bool,
     skip_too_big: bool,
+    component: str | None = None,
+    source_url: str | None = None,
+    build_plan_key: str | None = None,
+    build_id: str | None = None,
+    environment: str | None = None,
+    run_key: str | None = None,
 ) -> Config:
     """Resolve CLI config from flags + env vars. Re-raises UsageError on failure."""
     return Config.from_env(
@@ -48,6 +55,12 @@ def _resolve_config(
         results=results,
         silent=silent,
         skip_too_big=skip_too_big,
+        component=component,
+        source_url=source_url,
+        build_plan_key=build_plan_key,
+        build_id=build_id,
+        environment=environment,
+        run_key=run_key,
     )
 
 
@@ -133,13 +146,50 @@ def _print_summary(uploader: Uploader) -> None:
     )
 
 
+def _common_options(func: Callable) -> Callable:
+    """Apply the shared connection + launch-metadata options to a command.
+
+    `watch` and `upload` accept the identical option set; defining it once here
+    keeps them from drifting (a new launch field is added in one place, not two).
+    Decorators apply bottom-up, so the visible order on the command matches the
+    order below.
+    """
+    options = [
+        click.option("--endpoint", envvar="CHARISMA_ENDPOINT", default=None, help="Charisma API endpoint."),
+        click.option("--token", envvar="CHARISMA_TOKEN", default=None, help="Bearer token."),
+        click.option(
+            "--results", envvar="CHARISMA_RESULTS", default="allure-results", help="Allure results directory."
+        ),
+        click.option("--project", envvar="CHARISMA_PROJECT_ID", required=True, help="Project alias."),
+        click.option("--silent", is_flag=True, default=False, help="Don't fail if upload errors occur."),
+        click.option("--skip-too-big", is_flag=True, default=False, help="Skip result files larger than 2MB."),
+        click.option("--component", default=None, help="Component alias within the project."),
+        click.option("--source-url", default=None, help="CI/CD build link for this run."),
+        click.option("--build-plan-key", default=None, help="Explicit build plan key for resolution."),
+        click.option("--build-id", default=None, help="CI build identifier for this run (forwarded as buildId)."),
+        click.option(
+            "--environment",
+            default=None,
+            help="Environment code (e.g. 'qat', 'prod'). Stored as the launch environment.",
+        ),
+        click.option(
+            "--run-key",
+            envvar="CHARISMA_RUN_KEY",
+            default=None,
+            help="Run identity / merge key (NOT the build id). Producers sharing this key "
+            "stream into one launch (launch id = uuid5(project/run-key)) — powers "
+            "rerun-in-place and parallel workers; reruns record retry attempts. Use your "
+            "CI run/pipeline id (e.g. GITHUB_RUN_ID) so retries merge but separate runs "
+            "stay separate. Omit for a new launch.",
+        ),
+    ]
+    for option in reversed(options):
+        func = option(func)
+    return func
+
+
 @cli.command()
-@click.option("--endpoint", envvar="CHARISMA_ENDPOINT", default=None, help="Charisma API endpoint.")
-@click.option("--token", envvar="CHARISMA_TOKEN", default=None, help="Bearer token.")
-@click.option("--results", envvar="CHARISMA_RESULTS", default="allure-results", help="Allure results directory.")
-@click.option("--project", envvar="CHARISMA_PROJECT_ID", required=True, help="Project alias.")
-@click.option("--silent", is_flag=True, default=False, help="Don't fail if upload errors occur.")
-@click.option("--skip-too-big", is_flag=True, default=False, help="Skip result files larger than 2MB.")
+@_common_options
 @click.argument("command", nargs=-1, required=True)
 def watch(
     endpoint: str | None,
@@ -148,13 +198,32 @@ def watch(
     project: str,
     silent: bool,
     skip_too_big: bool,
+    component: str | None,
+    source_url: str | None,
+    build_plan_key: str | None,
+    build_id: str | None,
+    environment: str | None,
+    run_key: str | None,
     command: tuple[str, ...],
 ) -> None:
     """Watch allure-results and stream to Charisma while running COMMAND.
 
     Usage: charismactl watch --project my-project -- pytest -n 4 tests/
     """
-    config = _resolve_config(endpoint, token, project, results, silent, skip_too_big)
+    config = _resolve_config(
+        endpoint,
+        token,
+        project,
+        results,
+        silent,
+        skip_too_big,
+        component,
+        source_url,
+        build_plan_key,
+        build_id,
+        environment,
+        run_key,
+    )
 
     queue: PriorityQueue[FileEvent] = PriorityQueue()
     uploader = Uploader(config, queue)
@@ -207,7 +276,12 @@ def watch(
 
     # Drain and close — stop the watcher AFTER drain so the consumer's final
     # queue flush still sees anything the observer enqueued during drain.
-    uploader.drain(timeout=config.drain_timeout)
+    # drain() is progress-based and returns False if it stalled or any send
+    # failed — same partial-send guard as `upload`. In watch mode a dropped
+    # upload must not be masked by a passing test run (exit 0), so an incomplete
+    # drain forces a non-zero exit while still preserving a failing test's own
+    # exit code.
+    fully_drained = uploader.drain(timeout=config.drain_timeout)
     watcher.stop()
     uploader.stop()
 
@@ -219,16 +293,22 @@ def watch(
 
     _warn_if_results_unsent(uploader, config)
     _print_summary(uploader)
+
+    if not fully_drained:
+        click.echo(
+            "Error: upload did not finish — the consumer stalled or results "
+            "failed to send; some results were dropped. Exiting non-zero so this "
+            "run is not treated as a successful upload.",
+            err=True,
+        )
+        # Preserve a failing test's exit code; otherwise surface the upload
+        # failure as exit 1 instead of letting a passing test mask it.
+        sys.exit(exit_code if exit_code != 0 else 1)
     sys.exit(exit_code)
 
 
 @cli.command()
-@click.option("--endpoint", envvar="CHARISMA_ENDPOINT", default=None, help="Charisma API endpoint.")
-@click.option("--token", envvar="CHARISMA_TOKEN", default=None, help="Bearer token.")
-@click.option("--results", envvar="CHARISMA_RESULTS", default="allure-results", help="Allure results directory.")
-@click.option("--project", envvar="CHARISMA_PROJECT_ID", required=True, help="Project alias.")
-@click.option("--silent", is_flag=True, default=False, help="Don't fail if upload errors occur.")
-@click.option("--skip-too-big", is_flag=True, default=False, help="Skip result files larger than 2MB.")
+@_common_options
 def upload(
     endpoint: str | None,
     token: str | None,
@@ -236,12 +316,31 @@ def upload(
     project: str,
     silent: bool,
     skip_too_big: bool,
+    component: str | None,
+    source_url: str | None,
+    build_plan_key: str | None,
+    build_id: str | None,
+    environment: str | None,
+    run_key: str | None,
 ) -> None:
     """Upload completed allure-results to Charisma (post-execution).
 
     Usage: charismactl upload --project my-project --results allure-results
     """
-    config = _resolve_config(endpoint, token, project, results, silent, skip_too_big)
+    config = _resolve_config(
+        endpoint,
+        token,
+        project,
+        results,
+        silent,
+        skip_too_big,
+        component,
+        source_url,
+        build_plan_key,
+        build_id,
+        environment,
+        run_key,
+    )
 
     queue: PriorityQueue[FileEvent] = PriorityQueue()
     uploader = Uploader(config, queue)
@@ -268,9 +367,14 @@ def upload(
             if category is not None:
                 queue.put(FileEvent(path=filepath, category=category))
 
-    # Process and drain
+    # Process and drain. drain() is progress-based: it runs to completion for a
+    # healthy upload of any size and only returns False if the consumer STALLS
+    # (no progress for drain_timeout seconds). A False return means results were
+    # dropped — we must still close the launch and print the summary, then exit
+    # non-zero so CI sees a failure instead of a green build with a partial send
+    # (the upload results_sent=700/10158-queued bug).
     uploader.start()
-    uploader.drain(timeout=config.drain_timeout)
+    fully_drained = uploader.drain(timeout=config.drain_timeout)
     uploader.stop()
 
     # Close launch
@@ -279,3 +383,12 @@ def upload(
     uploader.stop()
 
     _print_summary(uploader)
+
+    if not fully_drained:
+        click.echo(
+            "Error: upload did not finish — the consumer stalled and some results "
+            "were not sent. Exiting non-zero so this run is not treated as a "
+            "successful upload.",
+            err=True,
+        )
+        sys.exit(1)

{charisma_cli-0.2.2 → charisma_cli-0.3.1}/src/charisma_cli/models.py

@@ -4,32 +4,69 @@ from dataclasses import dataclass, field
 from enum import IntEnum
 from pathlib import Path
 from typing import Any
-from uuid import NAMESPACE_URL, uuid5
 
+# Backend field-size contract (mirror of backend
+# models/testresults.py::MAX_ERROR_MESSAGE_BYTES / MAX_STACK_TRACE_BYTES).
+# The streaming ingestion API rejects the WHOLE batch (400 INVALID_INPUT) if any
+# result's error_message > 10KB or stack_trace > 100KB (UTF-8 bytes). Keep these
+# byte-identical to the backend; oversized fields spill to an attachment rather
+# than truncate (see uploader._spill_oversized_field).
+MAX_ERROR_MESSAGE_BYTES = 10 * 1024  # 10KB
+MAX_STACK_TRACE_BYTES = 100 * 1024  # 100KB
 
-def backend_result_id(launch_id: str, test_id: str) -> str:
-    """Derive the result identity the Charisma backend stores and validates against.
 
-    The backend computes ``test_results.id`` as
-    ``uuid5(NAMESPACE_URL, f"{launch_id}/{test_id}")`` (see backend
-    ``models/testresults.py`` ``to_canonical``). Attachment uploads are validated
-    against that stored id, so the CLI MUST send the same value as ``resultId`` —
-    not the raw Allure ``uuid``, which the backend discards. This function is the
-    single CLI-side mirror of that contract; keep the namespace, separator, and
-    field order byte-identical to the backend.
+# Cap for a synthesized attachment filename derived from a test's historyId,
+# which is arbitrary client-supplied text (Allure historyId, or fullName
+# fallback) that may contain path separators or be very long.
+MAX_ATTACHMENT_FILENAME_LENGTH = 200
+
+
+def safe_attachment_filename(history_id: str, suffix: str) -> str:
+    """Build a safe ``text/plain`` attachment filename from a test identity.
+
+    ``history_id`` is arbitrary client-supplied text (Allure ``historyId``, or
+    the ``fullName`` fallback) and can contain path separators (``/``, ``\\``),
+    ``..``, control characters, or be very long. This strips it to a basename,
+    replaces any remaining unsafe characters, and length-caps the stem so the
+    multipart filename sent to the backend is well-formed and bounded.
+
+    Args:
+        history_id: The owning result's test identity.
+        suffix: A short descriptor appended to the stem (e.g. ``error-message``).
+
+    Returns:
+        A sanitized ``{stem}-{suffix}.txt`` filename.
+    """
+    # Drop any path structure, then keep only filename-safe characters.
+    base = history_id.replace("\\", "/").rsplit("/", 1)[-1]
+    safe = "".join(c if (c.isalnum() or c in "-_.") else "_" for c in base)
+    stem = safe[:MAX_ATTACHMENT_FILENAME_LENGTH] or "result"
+    return f"{stem}-{suffix}.txt"
+
+
+def head_snippet(text: str, max_bytes: int) -> str:
+    """Return the longest UTF-8 prefix of ``text`` that fits in ``max_bytes``.
+
+    Cuts on a character boundary — never splits a multibyte code point — by
+    encoding, slicing the byte string, and decoding with ``errors="ignore"`` to
+    drop a trailing partial character. Used to keep an inline head of an
+    oversized field (the full value goes to an attachment).
 
     Args:
-        launch_id: The open launch UUID returned by the backend.
-        test_id: The result's test identity — the SAME value the CLI sends as
-            ``test_id`` in the results batch. This is the Allure ``historyId``,
-            falling back to ``fullName`` when ``historyId`` is absent (see
-            ``parser.parse_result_file``). Matching the backend requires only
-            that both sides key off this same value, whichever it is.
+        text: The source string.
+        max_bytes: Maximum size of the returned prefix in UTF-8 bytes.
 
     Returns:
-        The deterministic result id string matching the backend's stored id.
+        A prefix of ``text`` whose UTF-8 encoding is ``<= max_bytes`` bytes.
     """
-    return str(uuid5(NAMESPACE_URL, f"{launch_id}/{test_id}"))
+    encoded = text.encode("utf-8")
+    # Clamp: a non-positive budget must yield an empty prefix, never a Python
+    # negative slice (encoded[:-n]) which would return almost the whole string.
+    if max_bytes <= 0:
+        return ""
+    if len(encoded) <= max_bytes:
+        return text
+    return encoded[:max_bytes].decode("utf-8", errors="ignore")
 
 
 class FileCategory(IntEnum):