convertible-cli 0.3.0__tar.gz → 0.4.0__tar.gz

{convertible_cli-0.3.0 → convertible_cli-0.4.0}/CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/). This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-05-27
+
+### Added
+
+- Convertible ASCII banner on 'drive' and 'session' start (issue #15): decorative chrome shown only on an interactive TTY and suppressed in --json, so it never pollutes the stdout result stream or agent-parsed stderr.
+
 ## [0.3.0] - 2026-05-27
 
 ### Added

{convertible_cli-0.3.0 → convertible_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: convertible-cli
-Version: 0.3.0
+Version: 0.4.0
 Summary: Convertible CLI is a swappable coder-agent harness that turns different models into repo workers behind one shared task contract.
 Project-URL: Homepage, https://github.com/agentculture/convertible
 Project-URL: Issues, https://github.com/agentculture/convertible/issues
@@ -65,6 +65,10 @@ which one ran.
 - **Interactive palette** — `convertible session` opens a foreground command
   browser so operators can select templates and run ad-hoc instructions without
   leaving the shell.
+- **Startup banner** — `convertible drive` and `convertible session` greet an
+  interactive terminal with an ASCII banner. It's decorative chrome: written to
+  stderr, shown only on a TTY, and suppressed under `--json`, so it never
+  pollutes the stdout result stream or agent-parsed output.
 
 **Not in v0** (by design): a multi-engine router/policy gearbox, an execution
 sandbox, a daemon mode, and Codex/Claude/Gemini drivers. The runtime package has

{convertible_cli-0.3.0 → convertible_cli-0.4.0}/README.md

@@ -48,6 +48,10 @@ which one ran.
 - **Interactive palette** — `convertible session` opens a foreground command
   browser so operators can select templates and run ad-hoc instructions without
   leaving the shell.
+- **Startup banner** — `convertible drive` and `convertible session` greet an
+  interactive terminal with an ASCII banner. It's decorative chrome: written to
+  stderr, shown only on a TTY, and suppressed under `--json`, so it never
+  pollutes the stdout result stream or agent-parsed output.
 
 **Not in v0** (by design): a multi-engine router/policy gearbox, an execution
 sandbox, a daemon mode, and Codex/Claude/Gemini drivers. The runtime package has

convertible_cli-0.4.0/convertible/cli/_banner-big.txt

@@ -0,0 +1,37 @@
+                                               ,.  ..^I+[1z}{r]>1_}}]__+___+~++~".";
+                                            ";  ...;^`               |            _.!
+                                            l, Ii                 <    ..         !).''
+                                            n1' 1.                ;--l"-`           C-.~
+    ..^          ''}|{??-J       .. ."'l-,!}m\l .i.`,'.                              r; '.
+   '.     l..ij~_          ;l`  ....        c~?>  ;     |                   `t<t     .'  .
+   ]             .+I `' '  ,^ ..:,^.. "! Il'{> ii '`.  .`>1;:].    n     .~^v. :l!^        `'
+   r                   ._+ "it        "1`<:'c} ~: '`    .     1<   `>    :,. ,_n+\|)`{f| _^ '
+  ']                   l'.    ?I .I`:l.   ..;^ l<'      '.  .zQx)i?tri'^ .':' ..  .  `.`., .Q.>U.  .
+  v{      .   .        'j\ .       "<.:< { Q|<'I?<  j I.*Cj!;1?[>`..,';]`( `"                  ;? .)".^~' ;(;
+   i|    ..].  ^'      ]                  . :!....Cch?> ...  '.                                        . 'c[. .'  <(
+    ;l   ^" "" |1.>i :;U'"                      +. .I          .+.!^                                            l+  l   .! I~
+      t .. .    ?<..   ..  `'.|i.              ,I     ` }!             <\                                             ` .}.   '.'f:
+       . ....'.n.}<"   .l          "~."i                     Y._.            ^.^:                                            `. -     t'.
+        0|[.,^ J. ? `   '                ^ i?  .                  ':\.            ;. ^                                           ."`t     .
+          . ~':!.r      .                      ^<>..                    Y'l'            ~- i                                           .   .-
+           .> .I1."" .I.<`                     ^,    "".t                   `^+              !`'                                        ';` .`
+            '.'+/. ''x.^+" [i'                 ^:           .."`                  ~<                                           fc   ,.'(Iv ."_
+           ;:_:+!. i~.  ;,^]:?...l`            '^               'i.|                 ^,j             i          .c      ,. '-j .lu} `_.!!. ^.
+           ..i;n~'.j   ^x^   .!>i]`. c..        .              ...' `'.i^..              . .,w .    )i      '`. .'<):'  ;j,"..`']^^ '. .'  "
+            `^    ii   }   ;`n   .,l]+:- ~+`   :l .?.lQ.       _` .I+ <.    >i[            i!?^'|"'  I   ^i. ^l-;j^,.~I:. 1~?]`'Qi .~..-It^'
+             . ....             :~'    x;"u:  C..     Y.         .    .          .c,       '   '.    .   ' .._tn:` . .`  i,," ..`' `(.p'  'z
+                                   `!.[    /^lv,i <.+       .. ,"       +._^           < -     1.   :`   ]`?}!!!  .^/1  .``J!t .f.. .  `!    ^.
+                                       . ?.    If"Y.~...|  .^ ^`  f.  ,]   t          .  /'.   .h   ^'   0  .:}h?``io['. .   .+<.. ._^ '  .[
+                                            ;>`,:   fl)'l_'(" .  .-  . ]I'".^.            `^`'{t    ..'l .  .~l` .^;(,.      ) i| +'`'`_.
+                                                ^.)     ^:".  ` f`'^ ? ^'z-l.        1]:.. Xn" .  .:^`..         .":Z:.  ^"c:' , ;x^|'  |m`.
+                                                     <~ `  . .  `!. .x`;<`?`; ].'.^?.I; (`.. <?i>lI^ . .`;"... [j: .I]:  !,)I..   <. [ +;
+                                                         ". ..  .<,} '`(,j`..`.> n.     "" l`          `tO-  .`<1X.)^xC`' `}(    ]~ '.
+                                                             . ..+: ;^f_, `c  '.     :~."v.J|!I`   '/x^  "+b      '".?"(XYX _ ``..
+                                                             ...^+.`I".^.."m  .x       .     .          ^" "      "\` .`:  }.;
+                                                             ., [^|  ]^i Y.Y    . "    .:  "^.-'       ?; `.    '!.'t:. ./,
+                                                              , `+`- j .~;[. :'   .^ ..t"^ ...     "tj," ^[],
+                                                              !: )<r.("~^1^  '    ,
+                                                                ?  `il"!~<  `"   [
+                                                                .;         r.   z^
+                                                                  ``l    1   ".
+                                                                       .  .

convertible_cli-0.4.0/convertible/cli/_banner.py

@@ -0,0 +1,56 @@
+"""Convertible ASCII banner shown at drive/session start (decorative chrome).
+
+The art lives in ``_banner.txt`` next to this module so the wide, trailing-
+whitespace-laden lines never have to satisfy ``black``/``flake8``. It is loaded
+once (``lru_cache``) via :mod:`importlib.resources`, which resolves correctly for
+both editable installs and built wheels — and uses only the standard library, so
+the ``dependencies = []`` rule is preserved.
+
+The banner is purely decorative, so :func:`emit_banner` shows it **only on an
+interactive terminal** and **never in ``--json`` mode**. convertible is itself an
+agent harness: agents (and CI) parse stderr for the ``error:``/``hint:`` rubric,
+so the art must never prepend to machine-read output — only a human at a TTY sees
+it.
+"""
+
+from __future__ import annotations
+
+import sys
+from functools import lru_cache
+from importlib import resources
+from typing import Callable
+
+
+@lru_cache(maxsize=1)
+def banner() -> str:
+    """Return the convertible ASCII banner, loaded once from the data file."""
+    return resources.files(__package__).joinpath("_banner.txt").read_text(encoding="utf-8")
+
+
+def _isatty() -> bool:
+    """Whether the diagnostics stream (stderr) is an interactive terminal.
+
+    Isolated as a module function so tests can force the interactive branch
+    without a real TTY (``monkeypatch.setattr`` this name).
+    """
+    return sys.stderr.isatty()
+
+
+def emit_banner(emit: Callable[[str], None], *, json_mode: bool) -> None:
+    """Emit the banner via ``emit`` — only on an interactive TTY, never in ``--json``.
+
+    The banner is decorative, so two robustness rules apply:
+
+    * A missing/unreadable resource is swallowed — a packaging glitch must never
+      break a real drive (only the art is lost, the task still runs).
+    * Trailing newlines are stripped and each sink adds its own, so rendering is
+      identical whether ``emit`` always appends a newline (``print`` in
+      ``session``) or only when absent (``emit_diagnostic`` in ``drive``).
+    """
+    if json_mode or not _isatty():
+        return
+    try:
+        art = banner()
+    except OSError:
+        return
+    emit(art.rstrip("\n"))

convertible_cli-0.4.0/convertible/cli/_banner.txt

@@ -0,0 +1,23 @@
+                                                                       
+                                                                       
+                                                                       
+                                                                       
+                                                                       
+                      ,"^,::,:::::I::::::^                             
+                     ^!'`       `"^,.    ::`                           
+ `,;;i;,,'  .!^'`",. "<,"  "              ;,^                          
+ ^       '"^";"^```,":::','"'^`"."'.,:^,i::,"".                        
+.I.   '    I-l '",I;!ii,I.,,l;;IlIl:i!:::::,,,^^;",,'                  
+ '^ ""::``':.        .`";,"```"^..                  '^^'":,''.         
+   ::,`;!"..^..'^"^    .'  ..""   ..`"^                    ..`"`'"".   
+    ;;l!i:' ^        '^"`.       `"`..   ',^..                   `` '^ 
+     :i>I!lII".        .' .''^`       '`^'    .`".             ^. :;lI.
+     ",l!`;"':l;,,`.   .'       '",'.      ^...'^`'"...^l'":;Ii!!l:!';.
+      ^''^., '`^^`:l;"^"',!~ .^^^,""..'`^. .^l,I''^.:l!;;;i>|+,!IlI::^ 
+                  `;. :>i":` "`, ',^^"     ";  I.'. :::"^:;iil;'":^; '"
+                      '^"'"IlI,.:,::;:'  .`;"!l:``,,"``',,,^,,:ll!,,l^ 
+                           ":^:,I^:"!;::  :I>l:::"`""::,:I>!<i^ " ;.   
+                              ",;"Il;i^:  ',":;"`'`'^,   ><[il```'     
+                              " ;;I"l:^.^;^''lI"   :^::",:,'           
+                               ,`:;,I.^ ''                             
+                                `.   " "                               

{convertible_cli-0.3.0 → convertible_cli-0.4.0}/convertible/cli/_commands/drive.py

@@ -26,6 +26,7 @@ from pathlib import Path
 
 from convertible import registry
 from convertible.artifact import artifact_dir, failed_result, write
+from convertible.cli._banner import emit_banner
 from convertible.cli._errors import EXIT_ENV_ERROR, EXIT_USER_ERROR, CliError
 from convertible.cli._output import emit_diagnostic, emit_result
 from convertible.commands import CommandError, expand_command
@@ -140,6 +141,10 @@ def execute_drive(
 def cmd_drive(args: argparse.Namespace) -> int:
     json_mode = bool(getattr(args, "json", False))
 
+    # Decorative startup banner — interactive TTY only, suppressed in --json so
+    # neither stdout (the result stream) nor agent-parsed stderr is polluted (issue #15).
+    emit_banner(emit_diagnostic, json_mode=json_mode)
+
     repo = Path(args.repo).expanduser()
     if not repo.is_dir():
         raise CliError(

{convertible_cli-0.3.0 → convertible_cli-0.4.0}/convertible/cli/_commands/session.py

@@ -24,6 +24,7 @@ import sys
 from pathlib import Path
 from typing import Callable, Iterator, Optional
 
+from convertible.cli._banner import emit_banner
 from convertible.cli._commands.drive import execute_drive as _default_drive
 from convertible.cli._errors import CliError
 from convertible.commands import CommandError, discover_commands, expand_command, load_command
@@ -130,6 +131,10 @@ def run_session(
     # mode, but to stderr in --json mode so stdout carries only JSON results.
     chrome: Callable[..., None] = err if json_mode else out
 
+    # Decorative startup banner — interactive TTY only, suppressed in --json (issue #15).
+    # Printed once here (not in the loop) so it greets the session, not each prompt.
+    emit_banner(err, json_mode=json_mode)
+
     config = EngineConfig.resolve(
         base_url=getattr(args, "base_url", None),
         model=getattr(args, "model", None),

{convertible_cli-0.3.0 → convertible_cli-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "convertible-cli"
-version = "0.3.0"
+version = "0.4.0"
 description = "Convertible CLI is a swappable coder-agent harness that turns different models into repo workers behind one shared task contract."
 readme = "README.md"
 license = "MIT"

convertible_cli-0.4.0/tests/test_banner.py

@@ -0,0 +1,145 @@
+"""The convertible startup banner — decorative chrome on drive/session start (issue #15).
+
+Contract under test: the banner is written to **stderr**, shown **only on an
+interactive TTY**, and **suppressed in ``--json`` mode** — in both ``drive`` and
+``session``. So it never pollutes the stdout result stream nor the agent-parsed
+``error:``/``hint:`` stderr that convertible (an agent harness) emits.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+import pytest
+
+from convertible.cli import main
+from convertible.cli._banner import banner, emit_banner
+
+
+def _force_tty(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Make the banner think stderr is interactive (capsys/pipes are not)."""
+    monkeypatch.setattr("convertible.cli._banner._isatty", lambda: True)
+
+
+def _art() -> str:
+    """The banner as ``emit_banner`` renders it (trailing newlines normalized off)."""
+    return banner().rstrip("\n")
+
+
+class _CollectingOut:
+    """Fake output sink that collects all emitted lines (mirrors test_session)."""
+
+    def __init__(self) -> None:
+        self.lines: list[str] = []
+
+    def __call__(self, *args: object, **kwargs: object) -> None:
+        self.lines.append(" ".join(str(a) for a in args))
+
+    def text(self) -> str:
+        return "\n".join(self.lines)
+
+
+def _session_args(tmp_path: Path, *, json_mode: bool) -> argparse.Namespace:
+    return argparse.Namespace(
+        repo=str(tmp_path),
+        engine="mock",
+        no_pr=True,
+        base="main",
+        base_url=None,
+        model=None,
+        api_key=None,
+        max_steps=None,
+        json=json_mode,
+    )
+
+
+def _run_session(args: argparse.Namespace) -> tuple[_CollectingOut, _CollectingOut]:
+    from convertible.cli._commands.session import run_session
+
+    out, err = _CollectingOut(), _CollectingOut()
+    rc = run_session(args, input_fn=iter(["q"]), out=out, err=err)
+    assert rc == 0
+    return out, err
+
+
+def test_banner_loads_nonempty_art() -> None:
+    """The data file loads and yields the multi-line ASCII art."""
+    art = banner()
+    assert art.strip(), "banner should not be empty"
+    assert art.count("\n") >= 5, "expected a multi-line art block"
+    assert banner() is art, "banner() is cached"
+
+
+def test_drive_banner_on_tty(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _force_tty(monkeypatch)
+    rc = main(["drive", "do work", "--repo", str(tmp_path), "--engine", "mock", "--no-pr"])
+    assert rc == 0
+    captured = capsys.readouterr()
+    assert _art() in captured.err, "banner should print to stderr on an interactive drive"
+    assert _art() not in captured.out, "banner must never reach the stdout result stream"
+
+
+def test_drive_no_banner_when_not_a_tty(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    """Without a TTY (pipes, CI, agents), stderr stays clean for the error rubric."""
+    rc = main(["drive", "do work", "--repo", str(tmp_path), "--engine", "mock", "--no-pr"])
+    assert rc == 0
+    captured = capsys.readouterr()
+    assert _art() not in captured.err
+    assert _art() not in captured.out
+
+
+def test_drive_json_suppresses_banner(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _force_tty(monkeypatch)  # even on a TTY, --json suppresses it
+    rc = main(
+        ["drive", "do work", "--repo", str(tmp_path), "--engine", "mock", "--no-pr", "--json"]
+    )
+    assert rc == 0
+    captured = capsys.readouterr()
+    assert _art() not in captured.err, "--json must suppress the banner entirely"
+    assert _art() not in captured.out
+    assert json.loads(captured.out)["status"] == "ok", "stdout is still pure JSON"
+
+
+def test_session_banner_on_tty(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    _force_tty(monkeypatch)
+    out, err = _run_session(_session_args(tmp_path, json_mode=False))
+    assert _art() in err.text(), "banner should greet the session on stderr"
+    assert _art() not in out.text()
+
+
+def test_session_json_suppresses_banner(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    _force_tty(monkeypatch)
+    out, err = _run_session(_session_args(tmp_path, json_mode=True))
+    assert _art() not in err.text(), "--json must suppress the banner in session too"
+    assert _art() not in out.text()
+
+
+def test_drive_and_session_banner_render_identically(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """No trailing-blank-line mismatch between drive (emit_diagnostic) and session (print)."""
+    _force_tty(monkeypatch)
+    main(["drive", "do work", "--repo", str(tmp_path), "--engine", "mock", "--no-pr"])
+    drive_err = capsys.readouterr().err
+    # Drive emits the art followed by exactly one newline (no trailing blank line).
+    assert _art() + "\n" in drive_err
+    assert _art() + "\n\n" not in drive_err
+
+
+def test_emit_banner_swallows_missing_resource(monkeypatch: pytest.MonkeyPatch) -> None:
+    """A missing/unreadable resource must never break a drive — the banner is decorative."""
+    _force_tty(monkeypatch)
+
+    def _boom() -> str:
+        raise FileNotFoundError("_banner.txt")
+
+    monkeypatch.setattr("convertible.cli._banner.banner", _boom)
+    emitted: list[str] = []
+    emit_banner(emitted.append, json_mode=False)  # must not raise
+    assert emitted == [], "no art emitted when the resource is missing"

{convertible_cli-0.3.0 → convertible_cli-0.4.0}/uv.lock

@@ -72,7 +72,7 @@ wheels = [
 
 [[package]]
 name = "convertible-cli"
-version = "0.3.0"
+version = "0.4.0"
 source = { editable = "." }
 
 [package.dev-dependencies]