roar-cli 0.3.0__tar.gz → 0.3.2__tar.gz

{roar_cli-0.3.0 → roar_cli-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roar-cli
-Version: 0.3.0
+Version: 0.3.2
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
@@ -69,7 +69,7 @@ Requires Python 3.10+.
 
 > For the full prereqs, platform support matrix, tracer-backend setup,
 > macOS SIP notes, and sdist build steps, see the canonical
-> [Installing roar](https://glaas.ai/docs/roar-guide#installing-roar) docs page.
+> [Installation](https://glaas.ai/docs/installation) docs page.
 > What's below is a TL;DR.
 
 ### Platform Support

{roar_cli-0.3.0 → roar_cli-0.3.2}/README.md

@@ -20,7 +20,7 @@ Requires Python 3.10+.
 
 > For the full prereqs, platform support matrix, tracer-backend setup,
 > macOS SIP notes, and sdist build steps, see the canonical
-> [Installing roar](https://glaas.ai/docs/roar-guide#installing-roar) docs page.
+> [Installation](https://glaas.ai/docs/installation) docs page.
 > What's below is a TL;DR.
 
 ### Platform Support

{roar_cli-0.3.0 → roar_cli-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "roar-cli"
-version = "0.3.0"
+version = "0.3.2"
 description = "Reproducibility and provenance tracker for ML training pipelines"
 authors = [
     { name="TReqs Team", email="info@treqs.ai" }

roar_cli-0.3.2/roar/__init__.py

@@ -0,0 +1,11 @@
+"""roar - Run Observation & Artifact Registration."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _version
+
+try:
+    __version__: str = _version("roar-cli")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["__version__"]

{roar_cli-0.3.0 → roar_cli-0.3.2}/roar/application/publish/git_remote.py

@@ -84,10 +84,11 @@ def resolve_canonical_remote(repo_root: Path | str, configured_remote: str | Non
     if not remotes:
         raise GitRemoteError(
             "No git remote configured. `roar register` needs a remote to push "
-            "roar tags to so teammates can resolve GLaaS links.\n"
+            "roar tags to so anyone reading the GLaaS record can resolve them "
+            "back to the commit.\n"
             "Add one: `git remote add origin <url>`.\n"
             "Or skip the push: `roar config set git.push_tags_on_register never` "
-            "(local-only — GLaaS links will not resolve for teammates)."
+            "(commit links on GLaaS may be broken)."
         )
     if len(remotes) > 1:
         raise GitRemoteError(

{roar_cli-0.3.0 → roar_cli-0.3.2}/roar/application/publish/register_tag_push.py

@@ -81,7 +81,7 @@ def _create_local_tags(repo_root: Path, commit_to_tag: Iterable[tuple[str, str]]
                 "If the commit is no longer reachable locally (e.g. rebase, "
                 "garbage collection), recover it via `git reflog` before retrying — "
                 "or set `git.push_tags_on_register=never` to register local-only "
-                "(GLaaS links will not resolve for teammates)."
+                "(commit links on GLaaS may be broken)."
             )
 
 

{roar_cli-0.3.0 → roar_cli-0.3.2}/roar/application/publish/results.py

@@ -36,6 +36,7 @@ class RegisterLineageResponse:
     secrets_redacted: bool = False
     aborted_by_user: bool = False
     tag_summary: RegisterTagSummary | None = None
+    warnings: list[str] = field(default_factory=list)
 
 
 @dataclass(frozen=True)

{roar_cli-0.3.0 → roar_cli-0.3.2}/roar/application/publish/service.py

@@ -476,10 +476,17 @@ def register_lineage_target(request: RegisterLineageRequest) -> RegisterLineageR
 
         # P1-23: push roar tags BEFORE writing the GLaaS record so the
         # record never references a tag that doesn't yet exist on the
-        # canonical remote. Fail-closed.
+        # canonical remote. Attributed registers fail-closed here.
+        #
+        # Anonymous registers degrade tag-push failures to warnings: the
+        # user explicitly opted into a no-account publish, so requiring
+        # git-remote auth (a separate concern from GLaaS) would defeat
+        # the whole point. The local tag still gets created; only the
+        # push to the canonical remote is skipped on failure.
         from ...integrations.config import config_get
         from .register_tag_push import TagPushError, ensure_roar_tags_pushed
 
+        tag_push_warning: str | None = None
         try:
             tag_summary = ensure_roar_tags_pushed(
                 repo_root=prepared.git_tag_repo_root or request.cwd,
@@ -493,11 +500,14 @@ def register_lineage_target(request: RegisterLineageRequest) -> RegisterLineageR
                 logger=logger,
             )
         except TagPushError as exc:
-            return RegisterLineageResponse(
-                success=False,
-                artifact_hash=collected_lineage.artifact_hash,
-                error=str(exc),
-            )
+            if not request.anonymous:
+                return RegisterLineageResponse(
+                    success=False,
+                    artifact_hash=collected_lineage.artifact_hash,
+                    error=str(exc),
+                )
+            tag_push_warning = _format_anonymous_tag_push_warning(str(exc))
+            tag_summary = None
 
         service = RegisterService(
             glaas_client=runtime.glaas_client,
@@ -514,6 +524,10 @@ def register_lineage_target(request: RegisterLineageRequest) -> RegisterLineageR
             prepared=prepared,
         )
 
+        warnings: list[str] = []
+        if tag_push_warning:
+            warnings.append(tag_push_warning)
+
         return RegisterLineageResponse(
             success=result.success,
             session_hash=result.session_hash,
@@ -527,11 +541,37 @@ def register_lineage_target(request: RegisterLineageRequest) -> RegisterLineageR
             secrets_redacted=result.secrets_redacted,
             aborted_by_user=result.aborted_by_user,
             tag_summary=tag_summary,
+            warnings=warnings,
         )
     except PublishAuthError as exc:
         return RegisterLineageResponse(success=False, error=str(exc))
 
 
+def _format_anonymous_tag_push_warning(tag_push_error: str) -> str:
+    """Wrap a tag-push failure as a self-contained user-facing warning.
+
+    Anonymous register continues past the push failure (GLaaS publish
+    succeeds), so the message has to (a) make clear the failure is git
+    remote auth, not GLaaS, (b) tell the user GLaaS registration still
+    happened, (c) explain why the missing push matters (the GLaaS
+    record references a tag that doesn't yet exist on the remote, so
+    anyone reading the record can't ``git checkout`` it), and
+    (d) point at the real fix (configure git remote auth + push the
+    tag). We deliberately do *not* suggest
+    ``git.push_tags_on_register=never`` here — that "fix" breaks
+    reproducibility for everyone viewing the GLaaS record, not just
+    silences a local warning.
+    """
+    return (
+        "roar tag push to git remote failed (git auth, not GLaaS) — "
+        "anonymous register continued without pushing the tag.\n"
+        "  The local tag exists, but viewers of the GLaaS record need it "
+        "on the remote to reproduce.\n"
+        "  Fix git remote auth, then push: `git push <remote> <tag>`.\n"
+        f"  Verbatim git error: {tag_push_error}"
+    )
+
+
 def put_artifacts(request: PutRequest) -> PutResponse:
     """Run the `roar put` application workflow."""
     if not request.dry_run:

roar_cli-0.3.2/roar/application/run/dirty_tree_classify.py

@@ -0,0 +1,123 @@
+"""Classify dirty-tree paths into buckets so the start-of-run error
+can recommend the right fix per bucket.
+
+Three buckets:
+
+* **code** — tracked file with an uncommitted modification (porcelain
+  status code starts with ``M`` / ``A`` / ``D`` / ``R`` / ``C`` / ``U``).
+  Right fix is ``git add`` + ``git commit``.
+* **roar_output** — untracked path that the local roar DB already
+  knows about (artifact ``first_seen_path`` matches). Looks like an
+  output of an earlier ``roar run``. Right fix is ``.gitignore`` —
+  or commit if the user really wants the file in the repo.
+* **unknown** — untracked, no match in the local DB. Could be a stray
+  log, a fresh dataset, anything. Offer both options.
+
+We deliberately do *not* hash untracked files to look for content
+matches in the DB. Hashing every untracked file on every blocked run
+isn't worth it just to choose between two near-identical hint blocks
+(``roar_output`` vs ``unknown`` both recommend the same fix — the only
+difference is the framing line).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Protocol
+
+
+@dataclass(frozen=True)
+class DirtyClassification:
+    """Bucketed view of a ``git status --porcelain`` output."""
+
+    code: list[str] = field(default_factory=list)
+    roar_outputs: list[str] = field(default_factory=list)
+    unknown: list[str] = field(default_factory=list)
+
+    @property
+    def is_empty(self) -> bool:
+        return not (self.code or self.roar_outputs or self.unknown)
+
+    @property
+    def all_code(self) -> bool:
+        return bool(self.code) and not self.roar_outputs and not self.unknown
+
+    @property
+    def all_roar_outputs(self) -> bool:
+        return bool(self.roar_outputs) and not self.code and not self.unknown
+
+    @property
+    def all_unknown(self) -> bool:
+        return bool(self.unknown) and not self.code and not self.roar_outputs
+
+
+class _ArtifactLookup(Protocol):
+    """Minimal protocol the classifier needs from the DB."""
+
+    def get_by_path(self, path: str) -> Any: ...
+
+
+def classify_dirty_paths(
+    status_output: str,
+    repo_root: str | Path,
+    artifact_lookup: _ArtifactLookup | None,
+) -> DirtyClassification:
+    """Bucket each path in a porcelain output into code / roar-output / unknown.
+
+    ``artifact_lookup`` may be ``None`` when no DB context is available
+    (very early in a fresh init, for example). In that case the
+    classifier never produces ``roar_output`` entries — everything
+    untracked falls through to ``unknown``.
+    """
+    code: list[str] = []
+    roar_outputs: list[str] = []
+    unknown: list[str] = []
+
+    repo_path = Path(repo_root)
+    for status_code, path in _parse_porcelain(status_output):
+        if _is_tracked_modification(status_code):
+            code.append(path)
+            continue
+        if artifact_lookup is not None and _is_known_roar_output(artifact_lookup, repo_path, path):
+            roar_outputs.append(path)
+            continue
+        unknown.append(path)
+
+    return DirtyClassification(code=code, roar_outputs=roar_outputs, unknown=unknown)
+
+
+def _parse_porcelain(status_output: str) -> list[tuple[str, str]]:
+    """Yield ``(status_code, path)`` pairs from porcelain v1 output.
+
+    Porcelain v1 format is ``XY path``, where ``X`` and ``Y`` are the
+    index/worktree status codes. For renames the line is ``XY old -> new``;
+    we keep the new path (that's what the user works with).
+    """
+    pairs: list[tuple[str, str]] = []
+    for line in status_output.splitlines():
+        if not line:
+            continue
+        code = line[:2]
+        path = line[3:] if len(line) > 3 else line
+        if " -> " in path:
+            path = path.split(" -> ", 1)[1]
+        path = path.strip().strip('"')
+        if path:
+            pairs.append((code, path))
+    return pairs
+
+
+def _is_tracked_modification(status_code: str) -> bool:
+    """A status code other than ``??`` means git is tracking the path."""
+    return status_code.strip() != "??"
+
+
+def _is_known_roar_output(artifact_lookup: _ArtifactLookup, repo_root: Path, rel_path: str) -> bool:
+    """True if the path matches an artifact's recorded ``first_seen_path``."""
+    abs_path = str((repo_root / rel_path).resolve())
+    try:
+        record = artifact_lookup.get_by_path(abs_path)
+    except Exception:
+        return False
+    return bool(record)

roar_cli-0.3.2/roar/application/run/dirty_tree_error.py

@@ -0,0 +1,279 @@
+"""Construct the user-facing error message for a dirty git working tree.
+
+When ``roar run`` / ``roar build`` detects uncommitted changes, the
+error has to teach (a) *why* roar requires a clean tree, (b) the right
+remediation for what's actually dirty, and (c) handle two common
+fresh-install pitfalls:
+
+* The dirty file is roar's own state directory (``.roar/``) — usually a
+  fresh ``roar init`` whose ``.gitignore`` change isn't committed yet.
+* The user is running ``roar`` from ``$HOME`` instead of a project dir.
+
+The message is a single string raised as ``ValueError(message)``,
+which the CLI surface presents.
+
+The path-classifier (``dirty_tree_classify``) splits dirty paths into
+three buckets — code changes, prior-roar outputs (path match in DB),
+and unknown untracked files — so the message can recommend the right
+fix per bucket. When buckets mix, the message segments accordingly.
+"""
+
+from __future__ import annotations
+
+import os
+import shlex
+from pathlib import Path
+from typing import Any
+
+from .dirty_tree_classify import DirtyClassification, classify_dirty_paths
+from .gitignore_suggest import gitignore_lines
+
+DOCS_URL = "https://glaas.ai/docs/why-clean-commits"
+_MAX_LISTED_PATHS = 8
+_MAX_NAMED_FOR_GIT_ADD = 5
+
+
+def _all_under_roar_dir(paths: list[str]) -> bool:
+    if not paths:
+        return False
+    return all(p == ".roar" or p.startswith(".roar/") for p in paths)
+
+
+def _is_home_dir(repo_root: str | Path) -> bool:
+    home = os.path.expanduser("~")
+    if not home:
+        return False
+    try:
+        return Path(repo_root).resolve() == Path(home).resolve()
+    except OSError:
+        return False
+
+
+def _format_user_command(verb: str, args: list[str] | None) -> str:
+    if not args:
+        return f"roar {verb} <your-command>"
+    return f"roar {verb} " + " ".join(shlex.quote(a) for a in args)
+
+
+def _format_git_add(paths: list[str]) -> str:
+    if len(paths) <= _MAX_NAMED_FOR_GIT_ADD:
+        return "git add " + " ".join(shlex.quote(p) for p in paths)
+    return "git add -A"
+
+
+def _format_capped_list(paths: list[str]) -> list[str]:
+    visible = paths[:_MAX_LISTED_PATHS]
+    lines = [f"  {p}" for p in visible]
+    if len(paths) > _MAX_LISTED_PATHS:
+        lines.append(f"  ... and {len(paths) - _MAX_LISTED_PATHS} more")
+    return lines
+
+
+def format_dirty_tree_error(
+    *,
+    status_output: str,
+    repo_root: str | Path,
+    verb: str = "run",
+    args: list[str] | None = None,
+    artifact_lookup: Any = None,
+) -> str:
+    """Build the user-facing dirty-tree refusal message.
+
+    ``artifact_lookup`` is an optional object with a ``get_by_path``
+    method (typically ``db_ctx.artifacts``). When provided, untracked
+    paths that match a recorded artifact are classified as
+    ``roar_outputs`` and the message recommends ``.gitignore`` for
+    them. When ``None``, every untracked path is treated as unknown
+    (the message offers both commit and gitignore).
+    """
+    user_cmd = _format_user_command(verb, args)
+
+    if _is_home_dir(repo_root):
+        return _format_home_dir_message(user_cmd)
+
+    classification = classify_dirty_paths(status_output, repo_root, artifact_lookup)
+    all_paths = classification.code + classification.roar_outputs + classification.unknown
+    if _all_under_roar_dir(all_paths):
+        return _format_roar_only_message(user_cmd)
+
+    if classification.all_code:
+        return _format_code_only_message(classification.code, user_cmd)
+    if classification.all_roar_outputs:
+        return _format_roar_outputs_only_message(classification.roar_outputs, user_cmd)
+    if classification.all_unknown:
+        return _format_unknown_only_message(classification.unknown, user_cmd)
+    return _format_mixed_message(classification, user_cmd)
+
+
+# ---------------------------------------------------------------------------
+# Variants
+# ---------------------------------------------------------------------------
+
+
+def _format_code_only_message(paths: list[str], user_cmd: str) -> str:
+    lines = [
+        "Run blocked: working tree is dirty.",
+        "",
+        "roar tags every run with the current git commit SHA so the lineage",
+        'record answers "what code produced this artifact?" Uncommitted',
+        "changes mean we can't record that honestly — same reason you wouldn't",
+        "deploy uncommitted code to production.",
+        "",
+    ]
+    if len(paths) > _MAX_NAMED_FOR_GIT_ADD:
+        lines.append("Dirty files:")
+        lines.extend(_format_capped_list(paths))
+        lines.append("")
+    lines.extend(
+        [
+            "To proceed:",
+            f"  {_format_git_add(paths)}",
+            '  git commit -m "<describe your changes>"',
+            f"  {user_cmd}",
+            "",
+            f"Why: {DOCS_URL}",
+        ]
+    )
+    return "\n".join(lines)
+
+
+def _format_roar_outputs_only_message(paths: list[str], user_cmd: str) -> str:
+    lines = [
+        "Run blocked: untracked outputs from earlier roar run(s).",
+        "",
+        "These match artifacts in the local roar DB — they look like",
+        "products of past runs, not source code roar should pin commits to.",
+        "",
+        "Untracked outputs:",
+    ]
+    lines.extend(_format_capped_list(paths))
+    lines.extend(
+        [
+            "",
+            "Fix — gitignore them:",
+        ]
+    )
+    lines.extend(f"  {sug}" for sug in gitignore_lines(paths))
+    lines.extend(
+        [
+            "  git add .gitignore && git commit -m 'ignore roar outputs'",
+            f"  {user_cmd}",
+            "",
+            "(Or `git add` + `git commit` them if they belong in the repo.)",
+            "",
+            f"Why: {DOCS_URL}",
+        ]
+    )
+    return "\n".join(lines)
+
+
+def _format_unknown_only_message(paths: list[str], user_cmd: str) -> str:
+    lines = [
+        "Run blocked: untracked files in the working tree.",
+        "",
+        "roar tags every run with the current git commit SHA. Untracked",
+        "files mean the commit alone can't explain what was on disk at",
+        "run time.",
+        "",
+        "Untracked files:",
+    ]
+    lines.extend(_format_capped_list(paths))
+    lines.extend(
+        [
+            "",
+            "If they're outputs you want kept around but not in the repo, gitignore them:",
+        ]
+    )
+    lines.extend(f"  {sug}" for sug in gitignore_lines(paths))
+    lines.extend(
+        [
+            "  git add .gitignore && git commit -m 'ignore outputs'",
+            "",
+            "If they belong in the repo, commit them:",
+            f"  {_format_git_add(paths)}",
+            '  git commit -m "<describe your changes>"',
+            "",
+            f"Then retry: {user_cmd}",
+            "",
+            f"Why: {DOCS_URL}",
+        ]
+    )
+    return "\n".join(lines)
+
+
+def _format_mixed_message(classification: DirtyClassification, user_cmd: str) -> str:
+    lines = [
+        "Run blocked: working tree is dirty.",
+        "",
+    ]
+
+    if classification.code:
+        lines.append("Code changes:")
+        lines.extend(_format_capped_list(classification.code))
+        lines.append("")
+        lines.append("Fix:")
+        lines.append(f"  {_format_git_add(classification.code)}")
+        lines.append('  git commit -m "<describe your changes>"')
+        lines.append("")
+
+    if classification.roar_outputs:
+        lines.append("Roar outputs (untracked):")
+        lines.extend(_format_capped_list(classification.roar_outputs))
+        lines.append("")
+        lines.append("Fix — gitignore them:")
+        lines.extend(f"  {sug}" for sug in gitignore_lines(classification.roar_outputs))
+        lines.append("  git add .gitignore && git commit -m 'ignore roar outputs'")
+        lines.append("")
+
+    if classification.unknown:
+        lines.append("Other untracked files:")
+        lines.extend(_format_capped_list(classification.unknown))
+        lines.append("")
+        lines.append("Fix — gitignore or commit:")
+        lines.extend(f"  {sug}" for sug in gitignore_lines(classification.unknown))
+        lines.append("  git add .gitignore && git commit -m 'ignore outputs'")
+        lines.append(f"  (or `{_format_git_add(classification.unknown)}` + commit)")
+        lines.append("")
+
+    lines.append(f"Then retry: {user_cmd}")
+    lines.append("")
+    lines.append(f"Why: {DOCS_URL}")
+    return "\n".join(lines)
+
+
+def _format_roar_only_message(user_cmd: str) -> str:
+    return "\n".join(
+        [
+            "Run blocked: working tree is dirty.",
+            "",
+            "The only dirty path is roar's own state directory (.roar/).",
+            "It should be in .gitignore so it doesn't trip future runs.",
+            "",
+            "Quickest fix:",
+            "  echo '.roar/' >> .gitignore",
+            "  git add .gitignore && git commit -m 'ignore .roar/'",
+            f"  {user_cmd}",
+            "",
+            "Or re-run `roar init` — it will set this up for you.",
+            "",
+            f"Why: {DOCS_URL}",
+        ]
+    )
+
+
+def _format_home_dir_message(user_cmd: str) -> str:
+    return "\n".join(
+        [
+            "Run blocked: you're running roar from your home directory.",
+            "",
+            "roar tags every run with the current git commit SHA. Your home",
+            "directory is rarely under clean version control, and is almost",
+            "never the right place to track ML pipeline lineage.",
+            "",
+            "Switch to your project directory and run there:",
+            "  cd <your project>",
+            f"  {user_cmd}",
+            "",
+            f"Why: {DOCS_URL}",
+        ]
+    )