boost-skill-cli 1.0.264__tar.gz → 1.0.265__tar.gz

{boost_skill_cli-1.0.264 → boost_skill_cli-1.0.265}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.0.264
+Version: 1.0.265
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE

{boost_skill_cli-1.0.264 → boost_skill_cli-1.0.265}/boost_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.0.264'
-__version_tuple__ = version_tuple = (1, 0, 264)
+__version__ = version = '1.0.265'
+__version_tuple__ = version_tuple = (1, 0, 265)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.0.264 → boost_skill_cli-1.0.265}/boost_cli/commands/info.py

@@ -540,6 +540,26 @@ def cmd_explain(argv):
     return 0
 
 
+def _diag_line(line: str) -> str:
+    """Render one stored log line for display, whether it is text or JSON.
+
+    ``BOOST_LOG_FORMAT=json`` makes the file JSONL, which is the point — but
+    this command is the *human* view of that same file, and raw JSONL is not
+    it. Anything that is not a boost log object passes through untouched, so a
+    file whose format changed mid-life still reads end to end.
+    """
+    if not line.startswith("{"):
+        return line
+    try:
+        rec = json.loads(line)
+    except ValueError:
+        return line
+    if not isinstance(rec, dict) or "msg" not in rec:
+        return line
+    return "%s %-7s %s: %s" % (rec.get("ts", ""), rec.get("level", ""),
+                               rec.get("logger", ""), rec["msg"])
+
+
 def _show_diagnostics(limit):
     lp = logs.log_path()
     if not lp.exists():
@@ -548,7 +568,7 @@ def _show_diagnostics(limit):
     lines = lp.read_text(encoding="utf-8", errors="replace").splitlines()
     out.heading("diagnostic log — %s" % lp)
     for line in lines[-limit:]:
-        out.info(line)
+        out.info(_diag_line(line))
     return 0
 
 

{boost_skill_cli-1.0.264 → boost_skill_cli-1.0.265}/boost_cli/core/config.py

@@ -30,6 +30,10 @@ DEFAULTS = {
         # See core/logs.py and docs/DEBUGGING.md.
         "level": "OFF",
         "file": True,  # set false (or BOOST_NO_LOG=1) to disable the log file
+        # "text" (default) or "json". json emits one JSON object per line —
+        # the same fields, but readable by jq or a log collector without a
+        # regex. Overridden by BOOST_LOG_FORMAT.
+        "format": "text",
     },
 }
 

{boost_skill_cli-1.0.264 → boost_skill_cli-1.0.265}/boost_cli/core/logs.py

@@ -28,10 +28,21 @@ to disable the file.
 Each invocation bookends the trail with an ``invoke:`` line and a ``done:`` line
 that carries the exit code and wall-clock duration, so the log doubles as a
 lightweight timing record for spotting slow commands after the fact.
+
+Line *format* is resolved separately from verbosity, same precedence shape:
+
+  1. ``BOOST_LOG_FORMAT=json|text``
+  2. config ``logging.format`` (default ``text``)
+
+``json`` emits one JSON object per line — the same fields the text formatter
+renders — so ``~/.boost/logs/boost.log`` pipes straight into ``jq`` or a log
+collector instead of needing a regex. It is the same JSONL shape
+``core.journal`` already writes for the pulse feed.
 """
 from __future__ import annotations
 
 import contextlib
+import json
 import logging
 import logging.handlers
 import os
@@ -51,6 +62,9 @@ BACKUP_COUNT = 3       # … times (N+1) files kept = ~4 MB ceiling
 KEEP_CRASH_REPORTS = 20
 
 _LEVELS = ("DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL")
+_FORMATS = ("text", "json")
+_TEXT_FMT = "%(asctime)s %(levelname)-7s %(name)s: %(message)s"
+_DATE_FMT = "%Y-%m-%dT%H:%M:%SZ"
 
 # Set by configure(); read by main()'s exception handler to decide whether to
 # print a full traceback or a friendly one-liner.
@@ -98,6 +112,54 @@ def _console_level(verbose: bool, debug: bool, quiet: bool) -> Optional[int]:
     return getattr(logging, cfg) if cfg in _LEVELS else None
 
 
+class JsonFormatter(logging.Formatter):
+    """One JSON object per line, carrying the text formatter's own fields.
+
+    Hand-rolled rather than pulled from a dependency: the runtime is
+    stdlib-only, ``core.journal`` already writes JSONL by hand for the pulse
+    feed, and a formatter that can raise is a formatter that loses the trail it
+    exists to keep — hence ``default=str``, so an unexpected object in a record
+    degrades to its repr instead of killing the handler.
+
+    ``converter`` is set on the instance by :func:`_formatter`, not here: as a
+    class attribute mypy binds it as a method and the signature stops matching
+    the base class's.
+    """
+
+    def format(self, record: logging.LogRecord) -> str:
+        payload = {
+            "ts": self.formatTime(record, _DATE_FMT),
+            "level": record.levelname,
+            "logger": record.name,
+            "msg": record.getMessage(),
+        }
+        if record.exc_info:
+            payload["exc"] = self.formatException(record.exc_info)
+        return json.dumps(payload, ensure_ascii=False, default=str)
+
+
+def log_format() -> str:
+    """Resolve the log line format: env first, then config, else ``text``."""
+    env = (os.environ.get("BOOST_LOG_FORMAT") or "").strip().lower()
+    if env in _FORMATS:
+        return env
+    from . import config
+    cfg = str(config.get("logging.format", "text") or "text").strip().lower()
+    return cfg if cfg in _FORMATS else "text"
+
+
+def _formatter(fmt_name: str) -> logging.Formatter:
+    """Build the formatter both handlers share."""
+    fmt: logging.Formatter = (JsonFormatter() if fmt_name == "json"
+                              else logging.Formatter(_TEXT_FMT,
+                                                     datefmt=_DATE_FMT))
+    # Both stamp a literal ``Z`` (UTC) suffix, so the timestamp has to be
+    # rendered in UTC — otherwise it uses local time and every line is
+    # mislabelled by the machine's offset. gmtime keeps it honest.
+    fmt.converter = time.gmtime
+    return fmt
+
+
 def _file_enabled() -> bool:
     if os.environ.get("BOOST_NO_LOG"):
         return False
@@ -141,14 +203,10 @@ def configure(verbose: bool = False, debug: bool = False,
         return logger
     _configured = True
 
-    fmt = logging.Formatter(
-        "%(asctime)s %(levelname)-7s %(name)s: %(message)s",
-        datefmt="%Y-%m-%dT%H:%M:%SZ",
-    )
-    # datefmt stamps a literal ``Z`` (UTC) suffix, so the timestamp must be
-    # rendered in UTC — otherwise ``%(asctime)s`` uses local time and every
-    # line is mislabelled by the machine's offset. gmtime keeps it honest.
-    fmt.converter = time.gmtime
+    # One formatter for both handlers: a user who asked for JSON asked for it
+    # everywhere, and a file/console split would make `--debug` disagree with
+    # the file it is meant to be showing.
+    fmt = _formatter(log_format())
 
     # File handler — always DEBUG, best-effort (never break the CLI over a log).
     if _file_enabled():

{boost_skill_cli-1.0.264 → boost_skill_cli-1.0.265}/boost_skill_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.0.264
+Version: 1.0.265
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE

{boost_skill_cli-1.0.264 → boost_skill_cli-1.0.265}/docs/DEBUGGING.md

@@ -80,6 +80,33 @@ BOOST_NO_LOG=1 boost install foo      # this run writes no file
 boost config set logging.file false   # permanently
 ```
 
+### Structured (JSON) log lines
+
+The trail is plain text by default. `json` emits **one JSON object per line**
+carrying the same fields, so the file pipes straight into `jq` or a log
+collector instead of needing a regex:
+
+```bash
+BOOST_LOG_FORMAT=json boost install foo    # this run
+boost config set logging.format json       # permanently
+
+jq -r 'select(.level=="WARNING") | .msg' ~/.boost/logs/boost.log
+```
+
+| Field | Meaning |
+|-------|---------|
+| `ts` | UTC timestamp, `2026-07-27T14:03:11Z` |
+| `level` | `DEBUG` … `CRITICAL` |
+| `logger` | always `boost` today |
+| `msg` | the formatted message, arguments already interpolated |
+| `exc` | the traceback — present only on records logged with an exception |
+
+The format applies to the console channel too, so `--debug` shows the same
+shape the file is recording. `boost log --diagnostics` renders JSON lines back
+as text, so switching format doesn't cost you the built-in viewer, and a file
+whose format changed mid-life still reads end to end. An unrecognised value
+falls back to `text` rather than failing the run.
+
 ---
 
 ## Crash reports
@@ -149,6 +176,7 @@ Everything that changes boost's runtime behaviour, in one place:
 | `BOOST_AGENTS_STORE` | override `~/.agents/skills` (the canonical store) |
 | `BOOST_DEBUG` | `=1` → console `DEBUG` + tracebacks |
 | `BOOST_LOG_LEVEL` | explicit console diagnostic level |
+| `BOOST_LOG_FORMAT` | `text` (default) or `json` — one JSON object per log line |
 | `BOOST_NO_LOG` | `=1` → don't write the diagnostic log file |
 | `BOOST_NO_AI` | `=1` → disable all AI calls (offline / deterministic) |
 | `BOOST_ASSUME_YES` | `=1` → auto-confirm prompts (also `--yes`/`-y`) |

{boost_skill_cli-1.0.264 → boost_skill_cli-1.0.265}/tests/unit/test_logs.py

@@ -1,10 +1,13 @@
 """Diagnostic logging & crash reporting."""
 from __future__ import annotations
 
+import json
 import logging
 import logging.handlers
 import pathlib
+import re
 import time
+from datetime import datetime, timezone
 
 import pytest
 
@@ -471,3 +474,140 @@ def test_a_real_crash_shows_up_in_the_listing(boost, monkeypatch):
     res = boost("log", "--crashes")
     assert crashed == ["count"]
     assert "command:  boost count" in res.out
+
+
+# ── BOOST_LOG_FORMAT=json ────────────────────────────────────────────────────
+
+class TestLogFormatResolution:
+    """Env beats config beats the `text` default — same shape as the level."""
+
+    def test_defaults_to_text(self, env):
+        assert logs.log_format() == "text"
+
+    def test_env_selects_json(self, env, monkeypatch):
+        monkeypatch.setenv("BOOST_LOG_FORMAT", "json")
+        assert logs.log_format() == "json"
+
+    def test_env_is_case_and_space_insensitive(self, env, monkeypatch):
+        monkeypatch.setenv("BOOST_LOG_FORMAT", "  JSON ")
+        assert logs.log_format() == "json"
+
+    def test_an_unknown_env_value_falls_back_to_text(self, env, monkeypatch):
+        # A typo must not silently disable logging or crash configure().
+        monkeypatch.setenv("BOOST_LOG_FORMAT", "yaml")
+        assert logs.log_format() == "text"
+
+    def test_config_selects_json_when_env_is_unset(self, env, monkeypatch):
+        from boost_cli.core import config
+        monkeypatch.delenv("BOOST_LOG_FORMAT", raising=False)
+        config.set_value("logging.format", "json")
+        assert logs.log_format() == "json"
+
+    def test_env_wins_over_config(self, env, monkeypatch):
+        from boost_cli.core import config
+        config.set_value("logging.format", "json")
+        monkeypatch.setenv("BOOST_LOG_FORMAT", "text")
+        assert logs.log_format() == "text"
+
+
+class TestJsonFileOutput:
+    def _records(self, env, monkeypatch):
+        monkeypatch.setenv("BOOST_LOG_FORMAT", "json")
+        logs.configure()
+        logs.get_logger().info("hello %s", "world")
+        text = logs.log_path().read_text(encoding="utf-8")
+        return [json.loads(ln) for ln in text.splitlines() if ln.strip()]
+
+    def test_one_json_object_per_line(self, env, monkeypatch):
+        recs = self._records(env, monkeypatch)
+        assert len(recs) == 1
+        assert recs[0]["msg"] == "hello world", "args must be interpolated"
+        assert recs[0]["level"] == "INFO"
+        assert recs[0]["logger"] == "boost"
+
+    def test_the_timestamp_is_utc_with_a_z(self, env, monkeypatch):
+        ts = self._records(env, monkeypatch)[0]["ts"]
+        assert re.match(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$", ts), ts
+        # Parsed as UTC it must be within a minute of now; a local-time stamp
+        # wearing a Z would be off by the machine's offset.
+        parsed = datetime.strptime(ts, "%Y-%m-%dT%H:%M:%SZ").replace(
+            tzinfo=timezone.utc)
+        assert abs((datetime.now(timezone.utc) - parsed).total_seconds()) < 60
+
+    def test_an_exception_is_carried_in_its_own_field(self, env, monkeypatch):
+        monkeypatch.setenv("BOOST_LOG_FORMAT", "json")
+        logs.configure()
+        try:
+            raise ValueError("boom")
+        except ValueError:
+            logs.get_logger().exception("caught it")
+        rec = [json.loads(ln) for ln in
+               logs.log_path().read_text(encoding="utf-8").splitlines()][-1]
+        assert rec["msg"] == "caught it"
+        assert "ValueError: boom" in rec["exc"]
+        assert "\n" not in json.dumps(rec), "one physical line per record"
+
+    def test_an_unserializable_arg_degrades_instead_of_losing_the_line(
+            self, env, monkeypatch):
+        # A formatter that raises loses the trail it exists to keep.
+        class Weird:
+            def __repr__(self):
+                return "<weird>"
+
+        monkeypatch.setenv("BOOST_LOG_FORMAT", "json")
+        logs.configure()
+        logs.get_logger().info("got %r", Weird())
+        rec = [json.loads(ln) for ln in
+               logs.log_path().read_text(encoding="utf-8").splitlines()][-1]
+        assert rec["msg"] == "got <weird>"
+
+    def test_text_mode_is_unchanged(self, env, monkeypatch):
+        monkeypatch.delenv("BOOST_LOG_FORMAT", raising=False)
+        logs.configure()
+        logs.get_logger().info("plain line")
+        text = logs.log_path().read_text(encoding="utf-8")
+        assert "INFO" in text and "boost: plain line" in text
+        assert not text.lstrip().startswith("{")
+
+
+class TestJsonConsoleOutput:
+    def test_the_console_handler_uses_the_same_format(self, env, monkeypatch,
+                                                      capsys):
+        # A `--debug` stream that disagrees with the file it is showing would
+        # be its own bug report.
+        monkeypatch.setenv("BOOST_LOG_FORMAT", "json")
+        logs.configure(debug=True)
+        logs.get_logger().error("stderr line")
+        err = capsys.readouterr().err.strip().splitlines()[-1]
+        assert json.loads(err)["msg"] == "stderr line"
+
+
+class TestDiagnosticsViewerReadsBothFormats:
+    """`boost log --diagnostics` is the human view of that same file."""
+
+    def _diag(self):
+        from boost_cli.commands import info
+        return info._diag_line
+
+    def test_a_json_line_is_rendered_back_as_text(self):
+        line = json.dumps({"ts": "2026-07-27T00:00:00Z", "level": "INFO",
+                           "logger": "boost", "msg": "invoke: boost count"})
+        assert self._diag()(line) == \
+            "2026-07-27T00:00:00Z INFO    boost: invoke: boost count"
+
+    def test_a_plain_text_line_passes_through(self):
+        line = "2026-07-27T00:00:00Z INFO    boost: invoke: boost count"
+        assert self._diag()(line) == line
+
+    def test_a_line_that_only_looks_like_json_passes_through(self):
+        # A mixed file (the format changed mid-life) has to read end to end.
+        for line in ("{not json at all", json.dumps({"other": "shape"}),
+                     json.dumps([1, 2, 3])):
+            assert self._diag()(line) == line
+
+    def test_the_command_renders_a_json_trail(self, boost, monkeypatch):
+        monkeypatch.setenv("BOOST_LOG_FORMAT", "json")
+        boost("count")
+        res = boost("log", "--diagnostics")
+        assert "invoke: boost count" in res.out
+        assert "{" not in res.out, "raw JSONL is not the human view"