feat(cli): --json output mode on read-only commands (SPEC C2)

`ai-config-kit --json <verb>` now produces a single JSON document
for the four read-only verbs that scripts care about. Mutating
verbs (install, uninstall, sync, decisions apply, …) stay text-only
by design — their side effects are the value, not the report.

Wired:

- status      -> {content_dir, target_base, hostname, tracked_files,
                  untracked_candidates, git_clean, git_summary}
- doctor      -> {healthy, issues, [heal: {summary, findings}]}
                  Exit code still reflects health.
- validate    -> {ok, issues, warnings}; exit code matches ok.
- decisions list -> {packs: [{name, description, version, files, readme}]}
- decisions show -> single pack object (same shape as a list entry)

Library surface gains `.to_json_dict()` on DoctorReport,
StatusReport, ValidationReport, DecisionPack, DecisionsListReport.
Path values stringify to absolute paths.

4 new tests (264 total): valid JSON from each verb, doctor exit
code matches healthy field, validate exit matches ok, packs array
populated.

SPEC §5 updated: C2, C3, C4 all marked _shipped 2026-05-16_ with
brief notes on the actual ships. C1, C5, C6 remain.

Author: imanimanyara

docs/SPEC.md

@@ -301,9 +301,9 @@ Status matrix at v0.3.0:
 | # | Where | Issue |
 |---|---|---|
 | C1 | `src/ai_config_kit/manager.py` | The 1500+ line file is dense. Consider extracting `decisions_*` methods to a sibling `decisions.py` module while keeping `ClaudeConfig` as the orchestrator. |
-| C2 | All commands | We don't have a `--json` output mode anywhere. Adding one would let other tools script around `ai-config-kit status` etc. |
-| C3 | `cli.py` | The bootstrap command's `--remote URL` flag accepts arbitrary URLs. Validate it's https:// or git@ before passing to git. |
-| C4 | `decisions apply` | When `--force` is given, doesn't show a diff first. Add a confirm-with-diff for tty users. |
+| C2 | _shipped 2026-05-16_ | `--json` flag wired on status, doctor, validate, decisions list/show. Reports gained `.to_json_dict()`. Mutating verbs stay text-only by design (their side effects are the value, not the report). |
+| C3 | _shipped 2026-05-16_ | `bootstrap --remote URL` validated against a transport allowlist (https/http/ssh/git/git@/file) and shell-metachar blocklist. |
+| C4 | _shipped 2026-05-16_ | `decisions apply --force` on a TTY shows unified diff + y/N prompt before applying. `--yes` / `--dry-run` / non-tty bypass. |
 | C5 | Cross-project | Audit-checklist + agent-loop instructions are duplicated between this SPEC and `get-installer/SPEC.md`. If a third project adopts the pattern, factor into a shared template. |
 | C6 | `tests/` | We test the manager's surface but not the integration with the symlinks-on-real-FS edge cases (e.g., bind-mounted target). Add a few integration tests. |
 

src/ai_config_kit/cli.py

@@ -21,6 +21,7 @@
 from __future__ import annotations
 
 import argparse
+import json
 import sys
 from pathlib import Path
 
@@ -98,6 +99,14 @@ def _build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="Print only essential output.",
     )
+    p.add_argument(
+        "--json",
+        action="store_true",
+        help=(
+            "Output a single JSON document on read-only commands "
+            "(status, doctor, validate, list, decisions list/show)."
+        ),
+    )
     p.add_argument(
         "-V", "--version",
         action="version",
@@ -580,17 +589,31 @@ def main(argv: list[str] | None = None) -> int:
             return 0
 
         if args.cmd == "status":
-            print(cfg.status().to_text())
+            status_report = cfg.status()
+            if args.json:
+                print(json.dumps(status_report.to_json_dict(), indent=2))
+            else:
+                print(status_report.to_text())
             return 0
 
         if args.cmd == "doctor":
             doctor_report = cfg.doctor()
-            print(doctor_report.summary())
-            if getattr(args, "heal", False):
-                heal_report = cfg.audit_permissions()
-                print(heal_report.summary())
-                for finding in heal_report.findings:
-                    _print_finding(finding)
+            if args.json:
+                payload = doctor_report.to_json_dict()
+                if getattr(args, "heal", False):
+                    heal_report = cfg.audit_permissions()
+                    payload["heal"] = {
+                        "summary": heal_report.summary(),
+                        "findings": [str(f) for f in heal_report.findings],
+                    }
+                print(json.dumps(payload, indent=2))
+            else:
+                print(doctor_report.summary())
+                if getattr(args, "heal", False):
+                    heal_report = cfg.audit_permissions()
+                    print(heal_report.summary())
+                    for finding in heal_report.findings:
+                        _print_finding(finding)
             return 0 if doctor_report.healthy else 1
 
         if args.cmd == "heal":
@@ -622,7 +645,10 @@ def main(argv: list[str] | None = None) -> int:
 
         if args.cmd == "validate":
             val_report = cfg.validate()
-            print(val_report.summary())
+            if args.json:
+                print(json.dumps(val_report.to_json_dict(), indent=2))
+            else:
+                print(val_report.summary())
             return 0 if val_report.ok else 1
 
         if args.cmd == "cleanup":
@@ -646,14 +672,21 @@ def main(argv: list[str] | None = None) -> int:
 
         if args.cmd == "decisions":
             if args.decisions_cmd == "list":
-                print(cfg.decisions_list().summary())
+                dec_list_report = cfg.decisions_list()
+                if args.json:
+                    print(json.dumps(dec_list_report.to_json_dict(), indent=2))
+                else:
+                    print(dec_list_report.summary())
                 return 0
             if args.decisions_cmd == "show":
                 pack = cfg.decisions_show(args.name)
-                print(pack.summary())
-                if pack.readme:
-                    print()
-                    print(pack.readme.rstrip())
+                if args.json:
+                    print(json.dumps(pack.to_json_dict(), indent=2))
+                else:
+                    print(pack.summary())
+                    if pack.readme:
+                        print()
+                        print(pack.readme.rstrip())
                 return 0
             if args.decisions_cmd == "apply":
                 # SPEC C4: when --force is requested on a TTY (and the

src/ai_config_kit/manager.py

@@ -149,6 +149,9 @@ def summary(self) -> str:
             return "all symlinks healthy"
         return f"{len(self.issues)} issue(s):\n  " + "\n  ".join(self.issues)
 
+    def to_json_dict(self) -> dict[str, Any]:
+        return {"healthy": self.healthy, "issues": list(self.issues)}
+
 
 @dataclass(frozen=True)
 class StatusReport:
@@ -185,6 +188,17 @@ def to_text(self, max_listed: int = 30) -> str:
             lines.append(self.git_summary)
         return "\n".join(lines)
 
+    def to_json_dict(self) -> dict[str, Any]:
+        return {
+            "content_dir": str(self.content_dir),
+            "target_base": str(self.target_base),
+            "hostname": self.hostname,
+            "tracked_files": list(self.tracked_files),
+            "untracked_candidates": list(self.untracked_candidates),
+            "git_clean": self.git_clean,
+            "git_summary": self.git_summary,
+        }
+
 
 @dataclass(frozen=True)
 class SyncReport:
@@ -302,6 +316,13 @@ def summary(self) -> str:
             lines.extend(f"  - {w}" for w in self.warnings)
         return "\n".join(lines)
 
+    def to_json_dict(self) -> dict[str, Any]:
+        return {
+            "ok": self.ok,
+            "issues": list(self.issues),
+            "warnings": list(self.warnings),
+        }
+
 
 @dataclass(frozen=True)
 class FetchReport:
@@ -487,11 +508,26 @@ def summary(self) -> str:
             f"  files ({len(self.files)}):\n{files}"
         )
 
+    def to_json_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "description": self.description,
+            "version": self.version,
+            "files": [
+                {"src": f.src, "dest": f.dest, "mode": f.mode}
+                for f in self.files
+            ],
+            "readme": self.readme,
+        }
+
 
 @dataclass(frozen=True)
 class DecisionsListReport:
     packs: list[DecisionPack] = field(default_factory=list)
 
+    def to_json_dict(self) -> dict[str, Any]:
+        return {"packs": [p.to_json_dict() for p in self.packs]}
+
     def summary(self) -> str:
         if not self.packs:
             return "no bundled decision packs"

tests/test_cli.py

@@ -76,6 +76,90 @@ def test_status_runs(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None
     assert "Tracked files" in out
 
 
+# --- --json output mode (SPEC C2) -----------------------------------------
+
+
+def test_status_json_outputs_valid_json(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    import json as _json
+    content = tmp_path / "content"
+    target = tmp_path / "target"
+    (content / "claude").mkdir(parents=True)
+    target.mkdir()
+    rc = main([
+        "--content", str(content), "--target", str(target), "--json", "status",
+    ])
+    assert rc == 0
+    out = capsys.readouterr().out
+    doc = _json.loads(out)
+    assert "content_dir" in doc
+    assert "tracked_files" in doc
+    assert isinstance(doc["tracked_files"], list)
+
+
+def test_doctor_json_outputs_healthy_field(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    import json as _json
+    content = tmp_path / "content"
+    target = tmp_path / "target"
+    (content / "claude").mkdir(parents=True)
+    (content / "claude" / "CLAUDE.md").write_text("x")
+    target.mkdir()
+    # No install -> doctor finds issue, exits 1, but JSON still valid
+    rc = main([
+        "--content", str(content), "--target", str(target), "--json", "doctor",
+    ])
+    assert rc == 1
+    out = capsys.readouterr().out
+    doc = _json.loads(out)
+    assert "healthy" in doc
+    assert doc["healthy"] is False
+    assert isinstance(doc["issues"], list)
+
+
+def test_validate_json_emits_ok_field(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    import json as _json
+    content = tmp_path / "content"
+    target = tmp_path / "target"
+    (content / "claude").mkdir(parents=True)
+    target.mkdir()
+    rc = main([
+        "--content", str(content), "--target", str(target), "--json", "validate",
+    ])
+    out = capsys.readouterr().out
+    doc = _json.loads(out)
+    assert "ok" in doc
+    assert "issues" in doc
+    assert "warnings" in doc
+    # rc matches ok semantics:
+    assert (rc == 0) == bool(doc["ok"])
+
+
+def test_decisions_list_json_outputs_packs_array(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    import json as _json
+    content = tmp_path / "content"
+    target = tmp_path / "target"
+    (content / "claude").mkdir(parents=True)
+    target.mkdir()
+    rc = main([
+        "--content", str(content), "--target", str(target), "--json",
+        "decisions", "list",
+    ])
+    assert rc == 0
+    out = capsys.readouterr().out
+    doc = _json.loads(out)
+    assert "packs" in doc
+    assert isinstance(doc["packs"], list)
+    assert doc["packs"]  # at least one bundled pack
+    assert "name" in doc["packs"][0]
+
+
 def test_invalid_json_config_exits_two(
     tmp_path: Path, capsys: pytest.CaptureFixture[str]
 ) -> None: