scar-cli 0.7.0__tar.gz → 0.8.0__tar.gz

scar_cli-0.8.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.8.0"
+}

scar_cli-0.8.0/.scars/candidates/rich-output-nontty-must-bypass-rich.md

@@ -0,0 +1,42 @@
+---
+# COPY THIS FILE — do not edit the template itself.
+# New scars: write to .scars/candidates/<slug>.md with status: candidate.
+# A human reviewer promotes to .scars/NNNN-<slug>.<type>.md with status: active.
+id: 0                      # assigned at promotion (next free NNNN)
+type: landmine             # deadend = tried+failed | fence = looks wrong, intentional | landmine = touching A breaks B
+title: Read commands' non-tty branch must bypass Rich — Rich wraps to 80 cols and breaks path-substring tests
+severity: high
+confidence: 0.9
+created: 2026-06-30
+authors: ["claude-code"]
+anchors:
+  - path: src/scar/cli.py
+  - path: src/scar/output.py
+  - pattern: "output\.render\("
+evidence:
+  - issue: 78
+  - note: "187-test suite asserts plain substrings like '0001-bad.deadend.md' and long anchor paths on main([...]) under capsys"
+expires:
+  condition: "the test suite stops asserting on plain stdout substrings (e.g. moves to asserting structured --json only)"
+  review_after: 2027-06-30
+status: candidate
+---
+
+The five read commands (status, lint, check, why, orphan) route output 3 ways:
+--json, Rich (tty), and plain print() (non-tty). The non-tty branch MUST keep
+emitting the legacy plain lines byte-for-byte. It looks redundant — "why not
+just always render with Rich?" — but it is load-bearing.
+
+Rich's Console wraps and truncates to ~80 columns when it does not detect a wide
+terminal. Many existing tests call main([...]) under pytest's capsys (stdout is
+NOT a tty) and assert on plain SUBSTRINGS, including long anchor paths like
+`src/long_gone/` and filenames like `0001-bad.deadend.md`. If you route the
+non-tty branch through Rich, those strings get wrapped/elided and the assertions
+fail in subtle, hard-to-trace ways (the value is "there" visually but split
+across a wrapped line).
+
+What a future editor must do: keep `output.is_tty()` gating Rich. Only branch 2
+(real tty) may call a `_*_rich` renderer. The `plain()` closure in each handler
+is the contract for non-tty + CI consumers — change its text only if you also
+update the corresponding test substrings. Do NOT collapse the plain branch into
+the Rich branch. See issue #78 and src/scar/output.py's module docstring.

{scar_cli-0.7.0 → scar_cli-0.8.0}/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.8.0](https://github.com/Daily-Nerd/Scar/compare/v0.7.0...v0.8.0) (2026-06-30)
+
+
+### Features
+
+* **cli:** add --version flag to report installed version ([#76](https://github.com/Daily-Nerd/Scar/issues/76)) ([e45805d](https://github.com/Daily-Nerd/Scar/commit/e45805d01d171e2264a37a102f73a5254d5cedeb)), closes [#75](https://github.com/Daily-Nerd/Scar/issues/75)
+* **cli:** Rich output for read commands (TTY-detect + --json) ([#79](https://github.com/Daily-Nerd/Scar/issues/79)) ([3ff9d40](https://github.com/Daily-Nerd/Scar/commit/3ff9d4036138e7c898cae8dc18c9affc26553525))
+
 ## [0.7.0](https://github.com/Daily-Nerd/Scar/compare/v0.6.1...v0.7.0) (2026-06-30)
 
 

{scar_cli-0.7.0 → scar_cli-0.8.0}/PKG-INFO

@@ -1,10 +1,11 @@
 Metadata-Version: 2.4
 Name: scar-cli
-Version: 0.7.0
+Version: 0.8.0
 Summary: SCAR — version control for negative knowledge (deadends, fences, landmines)
 License: MIT
 License-File: LICENSE
 Requires-Python: >=3.10
+Requires-Dist: rich>=15.0.0
 Description-Content-Type: text/markdown
 
 # SCAR — Version Control for Negative Knowledge

{scar_cli-0.7.0 → scar_cli-0.8.0}/plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "scar",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "SCAR — version control for negative knowledge (deadends, fences, landmines)",
   "hooks": {
     "PreToolUse": [

{scar_cli-0.7.0 → scar_cli-0.8.0}/pyproject.toml

@@ -1,11 +1,13 @@
 [project]
 name = "scar-cli"
-version = "0.7.0"
+version = "0.8.0"
 description = "SCAR — version control for negative knowledge (deadends, fences, landmines)"
 readme = "README.md"
 requires-python = ">=3.10"
 license = { text = "MIT" }
-dependencies = []
+dependencies = [
+    "rich>=15.0.0",
+]
 
 [project.scripts]
 scar = "scar.cli:main"

{scar_cli-0.7.0 → scar_cli-0.8.0}/src/scar/cli.py

@@ -11,6 +11,7 @@ import argparse
 import json
 import sys
 import time
+from importlib.metadata import PackageNotFoundError, version as _dist_version
 from pathlib import Path
 
 from .lint import lint_text
@@ -25,6 +26,7 @@ from .orphan import (
 )
 from .render import injection_context, label_line
 from .store import ScarStore, init_scars
+from . import output
 
 
 def _require_store(start: Path | None = None) -> ScarStore | None:
@@ -66,51 +68,198 @@ def _partial_rot_reason(finding) -> str:
     return "partial rot — dead anchor(s) (" + _dead_anchor_summary(finding) + ")"
 
 
+# ---------------------------------------------------------------------------
+# Rich renderers (Issue #78). These run ONLY on a real tty — never under capsys
+# or when piped, where the legacy plain output is the byte-preserved contract.
+# They consume the same structured data the --json branch emits (or, for check/
+# why, the parsed Scar objects) so the three surfaces never drift in substance.
+# ---------------------------------------------------------------------------
+_TYPE_STYLE = {"deadend": "red", "fence": "yellow", "landmine": "magenta"}
+
+
+def _type_label(t: str) -> str:
+    return f"[{_TYPE_STYLE.get(t, 'white')}]{t}[/]"
+
+
+def _status_rich(data: dict) -> None:
+    from rich.panel import Panel
+    from rich.table import Table
+
+    console = output.console
+    c = data["counts"]
+    console.print(Panel.fit(
+        f"[bold]{data['scars_dir']}[/]\n"
+        f"{c['active']} active · {c['candidates']} candidate(s) pending review",
+        title="scar status"))
+
+    if data["active"]:
+        t = Table(title="Active scars", show_edge=False, expand=False)
+        t.add_column("type"); t.add_column("id", justify="right")
+        t.add_column("severity"); t.add_column("title")
+        for s in data["active"]:
+            t.add_row(_type_label(s["type"]), f"#{s['id']}", s["severity"], s["title"])
+        console.print(t)
+    for s in data["challenged"]:
+        console.print(f"  [dim]challenged[/] {_type_label(s['type'])} #{s['id']} {s['title']}")
+    for name in data["candidates"]:
+        console.print(f"  [cyan]candidate:[/] {name}")
+    for s in data["review_due"]:
+        console.print(f"  [yellow]REVIEW DUE[/] {_type_label(s['type'])} #{s['id']} "
+                      f"review_after {s['review_after']}")
+
+    console.print(f"  [bold]{c['orphan_detected']}[/] orphan-detected · "
+                  f"[bold]{c['orphaned']}[/] orphaned (persisted) · "
+                  f"[bold]{c['partial_rot']}[/] partial-rot")
+    for o in data["orphan_detected"]:
+        console.print(f"    [red]orphan-detected[/] [#{o['scar_id']}] {o['reason']}")
+    for s in data["orphaned"]:
+        console.print(f"    [dim]orphaned[/] {_type_label(s['type'])} #{s['id']} {s['title']}")
+    for pr in data["partial_rot"]:
+        console.print(f"    [yellow]partial-rot[/] [#{pr['scar_id']}] {pr['reason']}")
+    if data["broken"]:
+        console.print(f"  [bold red]WARNING:[/] {len(data['broken'])} unparseable "
+                      f"(can NEVER fire): " + ", ".join(data["broken"]))
+
+
+def _lint_rich(data: dict) -> None:
+    from rich.table import Table
+
+    console = output.console
+    if data["findings"]:
+        t = Table(title="Lint findings", show_edge=False)
+        t.add_column("file"); t.add_column("level"); t.add_column("message")
+        for f in data["findings"]:
+            style = "red" if f["level"] == "error" else "yellow"
+            t.add_row(f["file"], f"[{style}]{f['level']}[/]", f["message"])
+        console.print(t)
+    for o in data["orphans"]:
+        console.print(f"[yellow]WARNING orphan-detected:[/] scar #{o['scar_id']} — {o['reason']}")
+    for pr in data["partial_rot"]:
+        console.print(f"[cyan]HINT partial-rot:[/] scar #{pr['scar_id']} — {pr['reason']}")
+    for h in data["reverse_hints"]:
+        console.print(f"[cyan]HINT:[/] scar #{h['id']} marked orphaned but anchors live again")
+    if data["shallow_clone"]:
+        console.print("[dim]note: shallow clone — evidence-reachability check skipped[/]")
+    for ue in data["unreachable_evidence"]:
+        console.print(f"[yellow]WARNING evidence-unreachable:[/] scar #{ue['scar_id']} — "
+                      f"commit {ue['sha']} {ue['reason']}")
+    style = "red" if data["failed"] else "green"
+    console.print(f"[{style}]lint:[/] {data['files']} file(s), {data['failed']} with errors, "
+                  f"{len(data['orphans'])} orphan(s), {len(data['partial_rot'])} partial-rot, "
+                  f"{len(data['unreachable_evidence'])} unreachable-evidence")
+
+
+def _check_rich(path: str, hits) -> None:
+    from rich.panel import Panel
+
+    console = output.console
+    if not hits:
+        console.print(f"[green]no scars anchored to[/] {path}")
+        return
+    for s in hits:
+        title = (f"{_type_label(s.type)} #{s.id} · severity: {s.severity} · "
+                 f"confidence: {s.confidence}")
+        console.print(Panel(s.body[:200].strip(), title=title,
+                            subtitle=f"[bold]{s.title}[/]", title_align="left"))
+
+
+def _why_rich(rel: str, records) -> None:
+    from rich.panel import Panel
+
+    console = output.console
+    if not records:
+        console.print(f"[green]no recorded pain for[/] {rel}")
+        return
+    console.print(f"[bold]History of pain for[/] {rel}")
+    for f, s in records:
+        title = f"[{s.status}] {_type_label(s.type)} #{s.id} — {s.title}"
+        console.print(Panel(s.body[:300].strip(), title=title, subtitle=f"[dim]{f.name}[/]",
+                            title_align="left"))
+
+
+def _orphan_rich(findings, partial) -> None:
+    console = output.console
+    if not findings:
+        console.print("[green]no orphan-detected scars[/]")
+    else:
+        for of in findings:
+            console.print(f"[red]orphan-detected[/] [#{of.scar_id}] {_orphan_reason(of)}")
+        console.print(f"[bold]{len(findings)}[/] orphan(s) detected — review, then "
+                      "`scar orphan --apply --id N --reason ...` to persist")
+    for pr in partial:
+        console.print(f"[yellow]partial-rot[/] [#{pr.scar_id}] {_partial_rot_reason(pr)}")
+    if partial:
+        console.print(f"[bold]{len(partial)}[/] partial-rot — advisory; re-anchor the dead "
+                      "anchor(s). Not an orphan (still firing on survivors).")
+
+
 def _cmd_lint(args) -> int:
     store = _require_store()
     if store is None:
         return 1
     failed = 0
     files = store._scar_files() + store.candidates()
+    findings_by_file: list[tuple[str, list]] = []
     for f in files:
         findings = lint_text(f.read_text(encoding="utf-8"))
-        for finding in findings:
-            print(f"{f.relative_to(store.root)}: {finding}")
+        findings_by_file.append((str(f.relative_to(store.root)), findings))
         if any(fi.level == "error" for fi in findings):
             failed += 1
 
     ctx = build_repo_context(store.root)
     orphans = detect_orphans(store, ctx)
-    for of in orphans:
-        print(f"WARNING orphan-detected: scar #{of.scar_id} — {_orphan_reason(of)}")
-
-    # partial rot (#35): firing scars with a dead anchor among live ones.
-    # Advisory only — never a blocking gate, even under --fail-orphans.
     partial = detect_partial_rot(store, ctx)
-    for pr in partial:
-        print(f"HINT partial-rot: scar #{pr.scar_id} — {_partial_rot_reason(pr)} "
-              "— re-anchor to restore full coverage")
-
-    # reverse hint: persisted-orphaned scars whose anchors resolve again
-    for _f, s in store.parsed():
-        if s.status == "orphaned" and not anchors_all_dead(s, ctx):
-            print(f"HINT: scar #{s.id} is marked orphaned but its anchors live "
-                  "again — consider re-activating (scar challenge/archive note)")
+    reverse_hints = [s for _f, s in store.parsed()
+                     if s.status == "orphaned" and not anchors_all_dead(s, ctx)]
 
     # evidence reachability (#43, scar #5): commit-SHA receipts that no longer
     # resolve from HEAD. None = shallow clone, reachability indeterminate → skip.
     unreachable = unreachable_evidence(store, store.root)
-    if unreachable is None:
-        print("note: shallow clone — evidence-reachability check skipped "
-              "(actions/checkout defaults to depth 1; use fetch-depth: 0)")
+    shallow = unreachable is None
+    if shallow:
         unreachable = []
-    for ue in unreachable:
-        print(f"WARNING evidence-unreachable: scar #{ue.scar_id} — commit "
-              f"{ue.sha} {ue.reason}, not reachable from HEAD")
 
-    print(f"lint: {len(files)} file(s), {failed} with errors, "
-          f"{len(orphans)} orphan(s), {len(partial)} partial-rot, "
-          f"{len(unreachable)} unreachable-evidence")
+    data = {
+        "files": len(files),
+        "findings": [{"file": rel, "level": fi.level, "message": fi.message}
+                     for rel, fs in findings_by_file for fi in fs],
+        "orphans": [{"scar_id": of.scar_id, "reason": _orphan_reason(of)} for of in orphans],
+        "partial_rot": [{"scar_id": pr.scar_id, "reason": _partial_rot_reason(pr)} for pr in partial],
+        "reverse_hints": [{"id": s.id} for s in reverse_hints],
+        "shallow_clone": shallow,
+        "unreachable_evidence": [{"scar_id": ue.scar_id, "sha": ue.sha, "reason": ue.reason}
+                                 for ue in unreachable],
+        "failed": failed,
+    }
+
+    def plain():
+        for rel, findings in findings_by_file:
+            for finding in findings:
+                print(f"{rel}: {finding}")
+        for of in orphans:
+            print(f"WARNING orphan-detected: scar #{of.scar_id} — {_orphan_reason(of)}")
+        # partial rot (#35): firing scars with a dead anchor among live ones.
+        # Advisory only — never a blocking gate, even under --fail-orphans.
+        for pr in partial:
+            print(f"HINT partial-rot: scar #{pr.scar_id} — {_partial_rot_reason(pr)} "
+                  "— re-anchor to restore full coverage")
+        # reverse hint: persisted-orphaned scars whose anchors resolve again
+        for s in reverse_hints:
+            print(f"HINT: scar #{s.id} is marked orphaned but its anchors live "
+                  "again — consider re-activating (scar challenge/archive note)")
+        if shallow:
+            print("note: shallow clone — evidence-reachability check skipped "
+                  "(actions/checkout defaults to depth 1; use fetch-depth: 0)")
+        for ue in unreachable:
+            print(f"WARNING evidence-unreachable: scar #{ue.scar_id} — commit "
+                  f"{ue.sha} {ue.reason}, not reachable from HEAD")
+        print(f"lint: {len(files)} file(s), {failed} with errors, "
+              f"{len(orphans)} orphan(s), {len(partial)} partial-rot, "
+              f"{len(unreachable)} unreachable-evidence")
+
+    output.render(data=data, json_flag=getattr(args, "json", False),
+                  tty=lambda: _lint_rich(data), plain=plain)
+
     if failed:
         return 1
     if orphans and getattr(args, "fail_orphans", False):
@@ -118,24 +267,14 @@ def _cmd_lint(args) -> int:
     return 0
 
 
-def _cmd_status(_args) -> int:
+def _cmd_status(args) -> int:
     store = _require_store()
     if store is None:
         return 1
     active, broken, cands = store.active(), store.broken(), store.candidates()
-    print(f"{store.scars_dir}: {len(active)} active, {len(cands)} candidate(s) pending review")
-    for f, s in active:
-        print(f"  [{s.type} #{s.id} | {s.severity}] {s.title}")
-    for f, s in store.parsed():
-        if s.status == "challenged":
-            print(f"  [challenged {s.type} #{s.id}] {s.title}")
-    for c in cands:
-        print(f"  candidate: {c.name}")
+    challenged = [(f, s) for f, s in store.parsed() if s.status == "challenged"]
     today = time.strftime("%Y-%m-%d")
     due = [s for _, s in store.firing() if s.review_after and s.review_after < today]
-    for s in due:
-        print(f"  REVIEW DUE [{s.type} #{s.id}] review_after {s.review_after} — "
-              "re-verify, then update the date or archive")
 
     # Orphans: detected (firing scars whose anchors all died — not yet persisted)
     # and persisted (already flipped to status: orphaned, invisible until now).
@@ -143,19 +282,54 @@ def _cmd_status(_args) -> int:
     detected = detect_orphans(store, ctx)
     persisted = [s for _, s in store.parsed() if s.status == "orphaned"]
     partial = detect_partial_rot(store, ctx)
-    print(f"  {len(detected)} orphan-detected (firing, anchors gone), "
-          f"{len(persisted)} orphaned (persisted), "
-          f"{len(partial)} partial-rot (firing, ≥1 anchor dead)")
-    for of in detected:
-        print(f"    orphan-detected [#{of.scar_id}] {_orphan_reason(of)}")
-    for s in persisted:
-        print(f"    orphaned [{s.type} #{s.id}] {s.title}")
-    for pr in partial:
-        print(f"    partial-rot [#{pr.scar_id}] {_partial_rot_reason(pr)}")
 
-    if broken:
-        print(f"  WARNING: {len(broken)} unparseable (can NEVER fire): "
-              + ", ".join(b.name for b in broken))
+    data = {
+        "scars_dir": str(store.scars_dir),
+        "active": [{"type": s.type, "id": s.id, "severity": s.severity, "title": s.title}
+                   for _f, s in active],
+        "challenged": [{"type": s.type, "id": s.id, "title": s.title} for _f, s in challenged],
+        "candidates": [c.name for c in cands],
+        "review_due": [{"type": s.type, "id": s.id, "review_after": s.review_after} for s in due],
+        "orphan_detected": [{"scar_id": of.scar_id, "reason": _orphan_reason(of)} for of in detected],
+        "orphaned": [{"type": s.type, "id": s.id, "title": s.title} for s in persisted],
+        "partial_rot": [{"scar_id": pr.scar_id, "reason": _partial_rot_reason(pr)} for pr in partial],
+        "broken": [b.name for b in broken],
+        "counts": {
+            "active": len(active),
+            "candidates": len(cands),
+            "orphan_detected": len(detected),
+            "orphaned": len(persisted),
+            "partial_rot": len(partial),
+            "broken": len(broken),
+        },
+    }
+
+    def plain():
+        print(f"{store.scars_dir}: {len(active)} active, {len(cands)} candidate(s) pending review")
+        for f, s in active:
+            print(f"  [{s.type} #{s.id} | {s.severity}] {s.title}")
+        for f, s in challenged:
+            print(f"  [challenged {s.type} #{s.id}] {s.title}")
+        for c in cands:
+            print(f"  candidate: {c.name}")
+        for s in due:
+            print(f"  REVIEW DUE [{s.type} #{s.id}] review_after {s.review_after} — "
+                  "re-verify, then update the date or archive")
+        print(f"  {len(detected)} orphan-detected (firing, anchors gone), "
+              f"{len(persisted)} orphaned (persisted), "
+              f"{len(partial)} partial-rot (firing, ≥1 anchor dead)")
+        for of in detected:
+            print(f"    orphan-detected [#{of.scar_id}] {_orphan_reason(of)}")
+        for s in persisted:
+            print(f"    orphaned [{s.type} #{s.id}] {s.title}")
+        for pr in partial:
+            print(f"    partial-rot [#{pr.scar_id}] {_partial_rot_reason(pr)}")
+        if broken:
+            print(f"  WARNING: {len(broken)} unparseable (can NEVER fire): "
+                  + ", ".join(b.name for b in broken))
+
+    output.render(data=data, json_flag=getattr(args, "json", False),
+                  tty=lambda: _status_rich(data), plain=plain)
     return 0
 
 
@@ -191,12 +365,23 @@ def _cmd_check(args) -> int:
         return 1
     hits = rank_for_edit(store, Path(args.path).resolve(), args.content or "",
                          top_k=args.top_k)
-    if not hits:
-        print(f"no scars anchored to {args.path}")
-        return 0
-    for s in hits:
-        print(label_line(s))
-        print("  " + s.body[:200].replace("\n", "\n  "))
+    data = {
+        "path": args.path,
+        "scars": [{"type": s.type, "id": s.id, "severity": s.severity,
+                   "confidence": s.confidence, "status": s.status, "title": s.title,
+                   "body": s.body[:200]} for s in hits],
+    }
+
+    def plain():
+        if not hits:
+            print(f"no scars anchored to {args.path}")
+            return
+        for s in hits:
+            print(label_line(s))
+            print("  " + s.body[:200].replace("\n", "\n  "))
+
+    output.render(data=data, json_flag=getattr(args, "json", False),
+                  tty=lambda: _check_rich(args.path, hits), plain=plain)
     return 0
 
 
@@ -228,20 +413,31 @@ def _cmd_orphan(args) -> int:
 
     if not args.apply:
         partial = detect_partial_rot(store, ctx)
-        if not findings:
-            print("no orphan-detected scars")
-        else:
-            for of in findings:
-                print(f"orphan-detected [#{of.scar_id}] {_orphan_reason(of)}")
-            print(f"{len(findings)} orphan(s) detected — review, then "
-                  "`scar orphan --apply --id N --reason ...` to persist")
-        # Partial rot is advisory and surfaced separately — never persisted as
-        # orphaned (the fix is re-anchoring, not a status transition). #35.
-        for pr in partial:
-            print(f"partial-rot [#{pr.scar_id}] {_partial_rot_reason(pr)}")
-        if partial:
-            print(f"{len(partial)} partial-rot — advisory; re-anchor the dead "
-                  "anchor(s). Not an orphan (still firing on survivors).")
+        data = {
+            "orphan_detected": [{"scar_id": of.scar_id, "reason": _orphan_reason(of)}
+                                for of in findings],
+            "partial_rot": [{"scar_id": pr.scar_id, "reason": _partial_rot_reason(pr)}
+                            for pr in partial],
+        }
+
+        def plain():
+            if not findings:
+                print("no orphan-detected scars")
+            else:
+                for of in findings:
+                    print(f"orphan-detected [#{of.scar_id}] {_orphan_reason(of)}")
+                print(f"{len(findings)} orphan(s) detected — review, then "
+                      "`scar orphan --apply --id N --reason ...` to persist")
+            # Partial rot is advisory and surfaced separately — never persisted as
+            # orphaned (the fix is re-anchoring, not a status transition). #35.
+            for pr in partial:
+                print(f"partial-rot [#{pr.scar_id}] {_partial_rot_reason(pr)}")
+            if partial:
+                print(f"{len(partial)} partial-rot — advisory; re-anchor the dead "
+                      "anchor(s). Not an orphan (still firing on survivors).")
+
+        output.render(data=data, json_flag=getattr(args, "json", False),
+                      tty=lambda: _orphan_rich(findings, partial), plain=plain)
         return 0
 
     # --apply: persist. Human-only (never wire into CI/lint).
@@ -273,11 +469,21 @@ def _cmd_why(args) -> int:
         return 1
     rel = str(Path(args.path).resolve().relative_to(store.root))
     records = store.scars_for_path(rel)
-    for f, s in records:
-        print(f"[{s.status} {s.type} #{s.id}] {s.title}  ({f.name})")
-        print("  " + s.body[:300].replace("\n", "\n  ") + "\n")
-    if not records:
-        print(f"no recorded pain for {rel}")
+    data = {
+        "path": rel,
+        "records": [{"status": s.status, "type": s.type, "id": s.id, "title": s.title,
+                     "file": f.name, "body": s.body[:300]} for f, s in records],
+    }
+
+    def plain():
+        for f, s in records:
+            print(f"[{s.status} {s.type} #{s.id}] {s.title}  ({f.name})")
+            print("  " + s.body[:300].replace("\n", "\n  ") + "\n")
+        if not records:
+            print(f"no recorded pain for {rel}")
+
+    output.render(data=data, json_flag=getattr(args, "json", False),
+                  tty=lambda: _why_rich(rel, records), plain=plain)
     return 0
 
 
@@ -514,16 +720,30 @@ def _cmd_skill_lifecycle(args) -> int:
     return skill_status()
 
 
+def _scar_version() -> str:
+    """Installed package version (pyproject is the source of truth via
+    release-please). 'unknown' when run from a tree that was never installed."""
+    try:
+        return _dist_version("scar-cli")
+    except PackageNotFoundError:
+        return "unknown"
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(prog="scar",
                                      description="version control for negative knowledge")
+    # argparse's version action prints and exits during optional parsing, before
+    # the required-subcommand check below — so `scar --version` needs no command.
+    parser.add_argument("--version", action="version", version=f"scar {_scar_version()}")
     sub = parser.add_subparsers(dest="command", required=True)
 
     sub.add_parser("init", help="create .scars/ layout in the current repo")
     p = sub.add_parser("lint", help="validate every scar and candidate")
     p.add_argument("--fail-orphans", action="store_true",
                    help="exit non-zero when any scar is orphan-detected")
-    sub.add_parser("status", help="counts, titles, broken-file warnings")
+    p.add_argument("--json", action="store_true", help="emit machine-readable JSON")
+    p = sub.add_parser("status", help="counts, titles, broken-file warnings")
+    p.add_argument("--json", action="store_true", help="emit machine-readable JSON")
 
     p = sub.add_parser("promote", help="review a candidate into an active scar")
     p.add_argument("candidate", help="candidate filename (or unique substring)")
@@ -533,9 +753,11 @@ def main(argv: list[str] | None = None) -> int:
     p.add_argument("path")
     p.add_argument("--content", default="", help="new code to test pattern anchors against")
     p.add_argument("--top-k", type=int, default=10)
+    p.add_argument("--json", action="store_true", help="emit machine-readable JSON")
 
     p = sub.add_parser("why", help="history of pain for a path (any status)")
     p.add_argument("path")
+    p.add_argument("--json", action="store_true", help="emit machine-readable JSON")
 
     p = sub.add_parser("challenge", help="dispute a scar (still fires, marked challenged)")
     p.add_argument("id", type=int)
@@ -552,6 +774,8 @@ def main(argv: list[str] | None = None) -> int:
                    help="with --apply: the detected scar id to persist")
     p.add_argument("--reason", default="anchors no longer resolve",
                    help="with --apply: why it is being orphaned (recorded in the note)")
+    p.add_argument("--json", action="store_true",
+                   help="emit machine-readable JSON (read mode only)")
 
     p = sub.add_parser("harvest", help="mine git history for candidate scars")
     p.add_argument("repo", nargs="?", default=".")

scar_cli-0.8.0/src/scar/output.py

@@ -0,0 +1,52 @@
+"""3-way output dispatch for the human-facing read commands (Issue #78).
+
+Each read command builds a structured data object, then routes it here:
+
+1. ``--json``           → ``json.dumps(data, indent=2)`` — the stable machine contract.
+2. ``sys.stdout.isatty()`` → the Rich renderer (Table/Panel/colour). Pretty path.
+3. otherwise (piped / captured / non-tty) → the legacy plain ``print()`` output,
+   byte-for-byte unchanged.
+
+Critical invariant: Rich must NEVER run in the non-tty branch. Rich wraps and
+truncates to ~80 cols, which would break the long-path substring assertions the
+test suite (and CI consumers) rely on. The plain renderer is the source of truth
+for non-tty; Rich is strictly additive on top of a real terminal.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, Callable
+
+from rich.console import Console
+
+# One shared console for every Rich-rendered surface — keeps width/colour policy
+# in a single place. ``file`` is resolved lazily by Rich at print time, so tests
+# that swap sys.stdout (capsys) still capture output.
+console = Console()
+
+
+def is_tty() -> bool:
+    """True when stdout is an interactive terminal. Pulled out as a function so
+    tests can monkeypatch the branch without faking a real tty."""
+    return sys.stdout.isatty()
+
+
+def render(
+    *,
+    data: Any,
+    json_flag: bool,
+    tty: Callable[[], None],
+    plain: Callable[[], None],
+) -> None:
+    """Dispatch one command's output the 3 ways. ``data`` is the structured
+    object (only consumed by the JSON branch); ``tty`` and ``plain`` are
+    zero-arg renderers that close over the shared console / legacy print lines."""
+    if json_flag:
+        print(json.dumps(data, indent=2))
+        return
+    if is_tty():
+        tty()
+        return
+    plain()

{scar_cli-0.7.0 → scar_cli-0.8.0}/tests/test_cli.py

@@ -52,6 +52,17 @@ def test_lint_broken_scar_exits_nonzero_names_file(repo, capsys):
     assert "0001-bad.deadend.md" in capsys.readouterr().out
 
 
+def test_version_flag_prints_version_and_exits_zero(capsys):
+    import re
+
+    with pytest.raises(SystemExit) as exc:
+        main(["--version"])
+    assert exc.value.code == 0
+    out = capsys.readouterr().out
+    assert out.startswith("scar ")
+    assert re.search(r"\d+\.\d+", out)
+
+
 def test_status_counts(repo, capsys):
     init_scars(repo)
     (repo / ".scars" / "candidates" / "x.md").write_text(CANDIDATE)
@@ -657,3 +668,116 @@ def test_agent_skill_prints_body_with_three_types(repo, capsys):
     assert "name: scar-authoring" in out
     for kind in ("deadend", "fence", "landmine"):
         assert kind in out
+
+
+# ---------------------------------------------------------------------------
+# Rich output (Issue #78): the five human-facing read commands gain a 3-way
+# surface — --json (machine), Rich (tty), plain (non-tty, byte-preserved). The
+# plain non-tty assertions live in the tests above; here we cover --json keys
+# and that the Rich tty path renders without crashing.
+# ---------------------------------------------------------------------------
+
+
+def _force_tty(monkeypatch):
+    """Force the tty branch so the Rich renderer runs (under capsys stdout is
+    never a real tty). We assert no crash + exit 0, never exact ANSI."""
+    import scar.output as out
+    monkeypatch.setattr(out, "is_tty", lambda: True)
+
+
+def test_status_json_emits_structured_counts(repo, capsys):
+    init_scars(repo)
+    (repo / ".scars" / "candidates" / "x.md").write_text(CANDIDATE)
+    assert main(["status", "--json"]) == 0
+    data = json.loads(capsys.readouterr().out)
+    assert data["counts"]["candidates"] == 1
+    assert data["counts"]["active"] == 0
+    assert isinstance(data["active"], list)
+
+
+def test_status_tty_renders_without_crashing(repo, capsys, monkeypatch):
+    init_scars(repo)
+    (repo / ".scars" / "candidates" / "x.md").write_text(CANDIDATE)
+    _force_tty(monkeypatch)
+    assert main(["status"]) == 0
+
+
+def test_lint_json_emits_findings_and_summary(repo, capsys):
+    init_scars(repo)
+    (repo / ".scars" / "0001-gone.deadend.md").write_text(ORPHAN_SCAR)
+    assert main(["lint", "--json"]) == 0
+    data = json.loads(capsys.readouterr().out)
+    assert data["files"] >= 1
+    assert any(o["scar_id"] == 1 for o in data["orphans"])
+    assert "failed" in data
+
+
+def test_lint_json_broken_scar_exit_one_and_lists_file(repo, capsys):
+    init_scars(repo)
+    (repo / ".scars" / "0001-bad.deadend.md").write_text("# nope\n")
+    assert main(["lint", "--json"]) == 1
+    data = json.loads(capsys.readouterr().out)
+    assert any("0001-bad.deadend.md" in f["file"] for f in data["findings"])
+
+
+def test_lint_tty_renders_without_crashing(repo, capsys, monkeypatch):
+    init_scars(repo)
+    (repo / ".scars" / "0001-gone.deadend.md").write_text(ORPHAN_SCAR)
+    _force_tty(monkeypatch)
+    assert main(["lint"]) == 0
+
+
+def test_check_json_lists_anchored_scars(repo, capsys):
+    init_scars(repo)
+    (repo / ".scars" / "candidates" / "tried-x.md").write_text(CANDIDATE)
+    main(["promote", "tried-x", "--reviewer", "k"])
+    (repo / "src").mkdir()
+    capsys.readouterr()
+    assert main(["check", "src/thing.py", "--json"]) == 0
+    data = json.loads(capsys.readouterr().out)
+    assert data["path"] == "src/thing.py"
+    assert any(s["title"] == "Tried X, failed" for s in data["scars"])
+
+
+def test_check_tty_renders_without_crashing(repo, capsys, monkeypatch):
+    init_scars(repo)
+    (repo / ".scars" / "candidates" / "tried-x.md").write_text(CANDIDATE)
+    main(["promote", "tried-x", "--reviewer", "k"])
+    (repo / "src").mkdir()
+    _force_tty(monkeypatch)
+    assert main(["check", "src/thing.py"]) == 0
+
+
+def test_why_json_lists_records(repo, capsys):
+    init_scars(repo)
+    (repo / ".scars" / "candidates" / "tried-x.md").write_text(CANDIDATE)
+    main(["promote", "tried-x", "--reviewer", "k"])
+    (repo / "src").mkdir()
+    capsys.readouterr()
+    assert main(["why", "src", "--json"]) == 0
+    data = json.loads(capsys.readouterr().out)
+    assert any(r["title"] == "Tried X, failed" for r in data["records"])
+
+
+def test_why_tty_renders_without_crashing(repo, capsys, monkeypatch):
+    init_scars(repo)
+    (repo / ".scars" / "candidates" / "tried-x.md").write_text(CANDIDATE)
+    main(["promote", "tried-x", "--reviewer", "k"])
+    (repo / "src").mkdir()
+    _force_tty(monkeypatch)
+    assert main(["why", "src"]) == 0
+
+
+def test_orphan_json_lists_detected(repo, capsys):
+    init_scars(repo)
+    (repo / ".scars" / "0005-both.deadend.md").write_text(MULTI_ANCHOR_ORPHAN)
+    assert main(["orphan", "--json"]) == 0
+    data = json.loads(capsys.readouterr().out)
+    assert any(o["scar_id"] == 5 for o in data["orphan_detected"])
+
+
+def test_orphan_tty_renders_without_crashing(repo, capsys, monkeypatch):
+    init_scars(repo)
+    (repo / ".scars" / "0005-both.deadend.md").write_text(MULTI_ANCHOR_ORPHAN)
+    _force_tty(monkeypatch)
+    assert main(["orphan"]) == 0

scar_cli-0.8.0/tests/test_output.py

@@ -0,0 +1,48 @@
+"""The 3-way output dispatch: JSON, Rich-tty, plain non-tty.
+
+The non-tty branch must call the plain renderer verbatim (byte-preserving for
+CI/substring consumers); Rich must NEVER render there. Only the tty branch uses
+Rich. JSON short-circuits both.
+"""
+
+import json
+
+from scar import output
+
+
+def test_json_flag_emits_indented_json_and_skips_renderers(capsys):
+    calls = []
+    output.render(
+        data={"a": 1, "b": ["x"]},
+        json_flag=True,
+        tty=lambda: calls.append("tty"),
+        plain=lambda: calls.append("plain"),
+    )
+    out = capsys.readouterr().out
+    assert json.loads(out) == {"a": 1, "b": ["x"]}
+    assert "\n  " in out  # indent=2 pretty print
+    assert calls == []  # neither renderer ran
+
+
+def test_non_tty_calls_plain_renderer_only(monkeypatch, capsys):
+    monkeypatch.setattr(output, "is_tty", lambda: False)
+    calls = []
+    output.render(
+        data={"a": 1},
+        json_flag=False,
+        tty=lambda: calls.append("tty"),
+        plain=lambda: calls.append("plain"),
+    )
+    assert calls == ["plain"]
+
+
+def test_tty_calls_tty_renderer_only(monkeypatch):
+    monkeypatch.setattr(output, "is_tty", lambda: True)
+    calls = []
+    output.render(
+        data={"a": 1},
+        json_flag=False,
+        tty=lambda: calls.append("tty"),
+        plain=lambda: calls.append("plain"),
+    )
+    assert calls == ["tty"]

{scar_cli-0.7.0 → scar_cli-0.8.0}/uv.lock

@@ -32,6 +32,27 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/cb/b1/3846dd7f199d53cb17f49cba7e651e9ce294d8497c8c150530ed11865bb8/iniconfig-2.3.0-py3-none-any.whl", hash = "sha256:f631c04d2c48c52b84d0d0549c99ff3859c98df65b3101406327ecc7d53fbf12", size = 7484, upload-time = "2025-10-18T21:55:41.639Z" },
 ]
 
+[[package]]
+name = "markdown-it-py"
+version = "4.2.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "mdurl" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/06/ff/7841249c247aa650a76b9ee4bbaeae59370dc8bfd2f6c01f3630c35eb134/markdown_it_py-4.2.0.tar.gz", hash = "sha256:04a21681d6fbb623de53f6f364d352309d4094dd4194040a10fd51833e418d49", size = 82454, upload-time = "2026-05-07T12:08:28.36Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b3/81/4da04ced5a082363ecfa159c010d200ecbd959ae410c10c0264a38cac0f5/markdown_it_py-4.2.0-py3-none-any.whl", hash = "sha256:9f7ebbcd14fe59494226453aed97c1070d83f8d24b6fc3a3bcf9a38092641c4a", size = 91687, upload-time = "2026-05-07T12:08:27.182Z" },
+]
+
+[[package]]
+name = "mdurl"
+version = "0.1.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d6/54/cfe61301667036ec958cb99bd3efefba235e65cdeb9c84d24a8293ba1d90/mdurl-0.1.2.tar.gz", hash = "sha256:bb413d29f5eea38f31dd4754dd7377d4465116fb207585f97bf925588687c1ba", size = 8729, upload-time = "2022-08-14T12:40:10.846Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b3/38/89ba8ad64ae25be8de66a6d463314cf1eb366222074cfda9ee839c56a4b4/mdurl-0.1.2-py3-none-any.whl", hash = "sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8", size = 9979, upload-time = "2022-08-14T12:40:09.779Z" },
+]
+
 [[package]]
 name = "packaging"
 version = "26.2"
@@ -77,10 +98,26 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/d4/24/a372aaf5c9b7208e7112038812994107bc65a84cd00e0354a88c2c77a617/pytest-9.0.3-py3-none-any.whl", hash = "sha256:2c5efc453d45394fdd706ade797c0a81091eccd1d6e4bccfcd476e2b8e0ab5d9", size = 375249, upload-time = "2026-04-07T17:16:16.13Z" },
 ]
 
+[[package]]
+name = "rich"
+version = "15.0.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "markdown-it-py" },
+    { name = "pygments" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/c0/8f/0722ca900cc807c13a6a0c696dacf35430f72e0ec571c4275d2371fca3e9/rich-15.0.0.tar.gz", hash = "sha256:edd07a4824c6b40189fb7ac9bc4c52536e9780fbbfbddf6f1e2502c31b068c36", size = 230680, upload-time = "2026-04-12T08:24:00.75Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/82/3b/64d4899d73f91ba49a8c18a8ff3f0ea8f1c1d75481760df8c68ef5235bf5/rich-15.0.0-py3-none-any.whl", hash = "sha256:33bd4ef74232fb73fe9279a257718407f169c09b78a87ad3d296f548e27de0bb", size = 310654, upload-time = "2026-04-12T08:24:02.83Z" },
+]
+
 [[package]]
 name = "scar-cli"
-version = "0.6.1"
+version = "0.7.0"
 source = { editable = "." }
+dependencies = [
+    { name = "rich" },
+]
 
 [package.dev-dependencies]
 dev = [
@@ -88,6 +125,7 @@ dev = [
 ]
 
 [package.metadata]
+requires-dist = [{ name = "rich", specifier = ">=15.0.0" }]
 
 [package.metadata.requires-dev]
 dev = [{ name = "pytest", specifier = ">=8.0" }]

scar_cli-0.7.0/.release-please-manifest.json

@@ -1,3 +0,0 @@
-{
-  ".": "0.7.0"
-}