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

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

@@ -5,6 +5,19 @@ 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.5.0] - 2026-05-27
+
+### Changed
+
+- Bare `convertible` (no subcommand) now opens the interactive harness (the `session` palette) when run at a terminal — the natural "get in and drive" gesture. Piped, redirected, or otherwise non-interactive, it still prints usage, preserving the discoverable surface for scripts and agents. `-h/--help` is unaffected.
+- Reframed `convertible drive` help and `explain` text to lead with the goal/instruction ("drive toward a goal") rather than "run a repo task"; the repo is the target, not the headline. No behavior change.
+
+## [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.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: convertible-cli
-Version: 0.3.0
+Version: 0.5.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
@@ -17,6 +17,27 @@ Description-Content-Type: text/markdown
 
 # convertible
 
+```text
+                      ,"^,::,:::::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 is a swappable coder-agent harness that turns different models
 > into repo workers behind one shared task contract.
 >
@@ -65,6 +86,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
@@ -102,10 +127,13 @@ engine, so it binds equally to `mock`, `vllm-openai`, and any future wheel.
 uv sync
 uv run pytest -n auto                          # full suite, no network needed
 
+# Open the interactive harness (the session palette) at a terminal:
+uv run convertible
+
 # Discover the engines installed in this environment:
 uv run convertible wheels list
 
-# Drive a task with the deterministic mock engine (no model, no network):
+# Drive toward a goal with the deterministic mock engine (no model, no network):
 uv run convertible drive "add a CONTRIBUTING.md stub" --repo . --engine mock --no-pr
 ```
 
@@ -293,6 +321,11 @@ loop, hooks, and artifact — no parallel code path):
 uv run convertible session --repo /path/to/repo --engine vllm-openai
 ```
 
+Running `convertible` with no arguments **at a terminal** opens this same palette
+(with the default engine and repo) — the natural "get in and drive" gesture.
+Piped, redirected, or otherwise non-interactive, bare `convertible` prints usage
+instead, so scripts and agents keep a discoverable surface.
+
 The session loops until the user enters `q`, `quit`, or an empty line. Any
 driver flags accepted by `drive` (`--engine`, `--no-pr`, `--base-url`, etc.)
 are also accepted by `session`.
@@ -329,7 +362,7 @@ rely on a non-existent flag.
 
 | Verb | What it does |
 |------|--------------|
-| `drive <instruction>` | Run a repo task through a coder engine; write the artifact; hand off. |
+| `drive <goal>` | Drive toward a goal/instruction: work autonomously through a coder engine; write the artifact; hand off. |
 | `drive --command <name> [args…]` | Expand a saved command template and drive it. |
 | `commands list` | List discovered command templates for a repo. |
 | `commands overview` | Describe the commands surface. |

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

@@ -1,5 +1,26 @@
 # convertible
 
+```text
+                      ,"^,::,:::::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 is a swappable coder-agent harness that turns different models
 > into repo workers behind one shared task contract.
 >
@@ -48,6 +69,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
@@ -85,10 +110,13 @@ engine, so it binds equally to `mock`, `vllm-openai`, and any future wheel.
 uv sync
 uv run pytest -n auto                          # full suite, no network needed
 
+# Open the interactive harness (the session palette) at a terminal:
+uv run convertible
+
 # Discover the engines installed in this environment:
 uv run convertible wheels list
 
-# Drive a task with the deterministic mock engine (no model, no network):
+# Drive toward a goal with the deterministic mock engine (no model, no network):
 uv run convertible drive "add a CONTRIBUTING.md stub" --repo . --engine mock --no-pr
 ```
 
@@ -276,6 +304,11 @@ loop, hooks, and artifact — no parallel code path):
 uv run convertible session --repo /path/to/repo --engine vllm-openai
 ```
 
+Running `convertible` with no arguments **at a terminal** opens this same palette
+(with the default engine and repo) — the natural "get in and drive" gesture.
+Piped, redirected, or otherwise non-interactive, bare `convertible` prints usage
+instead, so scripts and agents keep a discoverable surface.
+
 The session loops until the user enters `q`, `quit`, or an empty line. Any
 driver flags accepted by `drive` (`--engine`, `--no-pr`, `--base-url`, etc.)
 are also accepted by `session`.
@@ -312,7 +345,7 @@ rely on a non-existent flag.
 
 | Verb | What it does |
 |------|--------------|
-| `drive <instruction>` | Run a repo task through a coder engine; write the artifact; hand off. |
+| `drive <goal>` | Drive toward a goal/instruction: work autonomously through a coder engine; write the artifact; hand off. |
 | `drive --command <name> [args…]` | Expand a saved command template and drive it. |
 | `commands list` | List discovered command templates for a repo. |
 | `commands overview` | Describe the commands surface. |

{convertible_cli-0.3.0 → convertible_cli-0.5.0}/convertible/cli/__init__.py

@@ -61,6 +61,17 @@ def _argv_has_json(argv: list[str] | None) -> bool:
     return any(t == "--json" or t.startswith("--json=") for t in tokens)
 
 
+def _stdio_is_interactive() -> bool:
+    """Whether stdin and stdout are both interactive terminals.
+
+    Bare ``convertible`` opens the interactive harness only at a real terminal;
+    isolated as a module function so tests can force the interactive branch
+    without a TTY (mirrors :func:`convertible.cli._banner._isatty`). Both streams
+    must be a TTY: the palette reads from stdin and renders its chrome to stdout.
+    """
+    return sys.stdin.isatty() and sys.stdout.isatty()
+
+
 def _build_parser() -> argparse.ArgumentParser:
     from convertible.cli._commands import cli as _cli_group
     from convertible.cli._commands import commands as _commands_group
@@ -136,6 +147,14 @@ def main(argv: list[str] | None = None) -> int:
     args = parser.parse_args(argv)
 
     if args.command is None:
+        # Bare `convertible` opens the interactive harness at a terminal; piped /
+        # redirected / non-interactive it prints usage so scripts and agents keep
+        # a discoverable surface. `-h/--help` is handled by argparse before here,
+        # so the help surface (and the teken rubric, which probes --help) stay
+        # available either way. Re-parsing ["session"] reuses the session
+        # subparser's defaults and func wiring — no parallel code path.
+        if _stdio_is_interactive():
+            return _dispatch(parser.parse_args(["session"]))
         parser.print_help()
         return 0
 

convertible_cli-0.5.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.5.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.5.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.5.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(
@@ -219,7 +224,10 @@ def cmd_drive(args: argparse.Namespace) -> int:
 def register(sub: argparse._SubParsersAction) -> None:
     p = sub.add_parser(
         "drive",
-        help="Run a repo task through a coder engine and hand off the result.",
+        help=(
+            "Drive toward a goal: work autonomously on a request or instruction "
+            "through a coder engine, then hand off the result."
+        ),
     )
     # ``instruction`` is now zero-or-more positional tokens (nargs="*") so
     # ``--command`` can be the sole input without argparse raising an error.
@@ -227,7 +235,7 @@ def register(sub: argparse._SubParsersAction) -> None:
         "instruction",
         nargs="*",
         help=(
-            "What the engine should do in the repo.  "
+            "A goal or instruction to pursue autonomously.  "
             "Mutually exclusive with --command.  "
             "When --command is used, any positional tokens are passed as template arguments."
         ),

{convertible_cli-0.3.0 → convertible_cli-0.5.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.5.0}/convertible/explain/catalog.py

@@ -18,9 +18,13 @@ A clonable template for AgentCulture mesh agents. It carries an agent-first CLI
 buildable/deployable package baseline. Clone it, rename the package, edit
 `culture.yaml`, and you have a new agent.
 
+Run `convertible` with no verb at a terminal to open the interactive harness (the
+`session` palette); piped or non-interactive, it prints this usage instead.
+
 ## Verbs
 
-- `convertible drive <instruction>` — run a repo task through a coder engine.
+- `convertible drive <goal>` — drive toward a goal/instruction; work autonomously
+  through a coder engine and hand off the result.
 - `convertible session` — foreground interactive palette over the drive path.
 - `convertible wheels list` — list discovered engine wheels.
 - `convertible whoami` — identity probe from `culture.yaml`.
@@ -122,10 +126,11 @@ itself (distinct from the global `overview`, which describes the agent).
 _DRIVE = """\
 # convertible drive
 
-Run a repo task through a coder engine: select an engine wheel, run the bounded
-agentic tool-loop against the repo, write a result artifact, and hand off the
-change as a branch + PR. The same invocation works for every engine — only
-`--engine` changes.
+Drive toward a goal: hand convertible a request or instruction and it works
+autonomously — selecting an engine wheel, running the bounded agentic tool-loop,
+writing a result artifact, and handing off the change as a branch + PR. The repo
+is the target (`--repo`, default cwd); the same invocation works for every
+engine — only `--engine` changes.
 
 ## Usage
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "convertible-cli"
-version = "0.3.0"
+version = "0.5.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.5.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.5.0}/tests/test_cli.py

@@ -18,12 +18,34 @@ def test_version_flag(capsys: pytest.CaptureFixture[str]) -> None:
     assert __version__ in capsys.readouterr().out
 
 
-def test_no_args_prints_help(capsys: pytest.CaptureFixture[str]) -> None:
+def test_no_args_non_tty_prints_help(
+    capsys: pytest.CaptureFixture[str], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    # Force the non-interactive branch so this is deterministic regardless of
+    # pytest's capture mode: under `pytest -s` from a real terminal stdin/stdout
+    # would be TTYs and bare invocation would otherwise open the session loop
+    # (and block on input()). Non-interactive must fall back to usage, preserving
+    # the discoverable surface for scripts and agents.
+    monkeypatch.setattr("convertible.cli._stdio_is_interactive", lambda: False)
     rc = main([])
     assert rc == 0
     assert "usage: convertible" in capsys.readouterr().out
 
 
+def test_no_args_tty_opens_session(
+    capsys: pytest.CaptureFixture[str], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    # At an interactive terminal, bare `convertible` opens the session harness.
+    # Force the interactive branch via the isolated seam, and stub input() to a
+    # quit token so the session renders its palette header then exits cleanly.
+    monkeypatch.setattr("convertible.cli._stdio_is_interactive", lambda: True)
+    monkeypatch.setattr("builtins.input", lambda *a, **k: "q")
+    rc = main([])
+    assert rc == 0
+    out = capsys.readouterr().out
+    assert "convertible session" in out
+
+
 def test_unknown_command_errors(capsys: pytest.CaptureFixture[str]) -> None:
     with pytest.raises(SystemExit) as exc:
         main(["bogus"])

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

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