nabla-cli 0.2.0__tar.gz → 0.3.0__tar.gz

{nabla_cli-0.2.0 → nabla_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nabla-cli
-Version: 0.2.0
+Version: 0.3.0
 Summary: Call-site harvester: scan OpenAI call sites, record real traffic, emit site profiles
 License: MIT
 Requires-Python: >=3.11
@@ -8,6 +8,7 @@ Description-Content-Type: text/markdown
 Requires-Dist: jsonschema
 Requires-Dist: pydantic>=2
 Requires-Dist: openai>=1.40
+Requires-Dist: rich>=13.0
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 

{nabla_cli-0.2.0 → nabla_cli-0.3.0}/nabla/__init__.py

@@ -1,3 +1,3 @@
 """nabla — call-site harvester CLI (pre-Phase-0)."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

nabla_cli-0.3.0/nabla/branding.py

@@ -0,0 +1,50 @@
+"""nabla terminal branding: the ∇ logo and startup banner.
+
+The banner prints only on a real terminal — piped output, tests, and
+--json consumers never see it. Block glyphs render via the Windows
+console's UTF-16 writer, so no legacy-codepage fallback is needed on an
+interactive console.
+"""
+
+from __future__ import annotations
+
+from rich.console import Console
+from rich.text import Text
+
+from . import __version__
+
+_LOGO = [
+    "▛▀▀▀▀▀▀▀▜",
+    " ▚     ▞",
+    "  ▚   ▞",
+    "   ▚ ▞",
+    "    ▘",
+]
+
+_BRAND_STYLE = "bold cyan"
+
+
+def banner_lines() -> list[tuple[str, str]]:
+    """(logo_line, tagline) pairs; taglines are empty on the outer rows."""
+    taglines = [
+        "",
+        f"nabla v{__version__}",
+        "OpenAI call-site harvester",
+        "scan · record · profile",
+        "",
+    ]
+    return list(zip(_LOGO, taglines))
+
+
+def print_banner(console: Console | None = None) -> None:
+    console = console or Console()
+    if not console.is_terminal:
+        return
+    console.print()
+    for logo_line, tagline in banner_lines():
+        row = Text()
+        row.append(f"  {logo_line:<12}", style=_BRAND_STYLE)
+        if tagline:
+            row.append(tagline, style="bold" if tagline.startswith("nabla") else "dim")
+        console.print(row)
+    console.print()

{nabla_cli-0.2.0 → nabla_cli-0.3.0}/nabla/cli.py

@@ -9,13 +9,29 @@ import sys
 from getpass import getpass
 from pathlib import Path
 
+from rich.console import Console
+
+from . import __version__
+from .branding import print_banner
 from .config import PROVIDERS, apply_to_env, save_config
-from .contract import Example, is_supported
+from .contract import Example, Verifiability, is_supported
 from .profile import build_profile, find_site
 from .recorder import RecordSource, ZeroTrafficError, record
 from .scanner import scan
 from .schema_resolver import resolve_schema
 
+
+def _make_console(stderr: bool = False) -> Console:
+    console = Console(stderr=stderr, highlight=False)
+    if not console.is_terminal:
+        # Wide fixed width so captured/piped output never wraps or truncates.
+        console = Console(stderr=stderr, highlight=False, width=200)
+    return console
+
+
+_out = _make_console()
+_errcon = _make_console(stderr=True)
+
 _PROVIDER_DESCRIPTIONS = {
     "openai": "real OpenAI API, uses your OPENAI_API_KEY",
     "groq": "free tier, openai/gpt-oss-120b",
@@ -36,6 +52,7 @@ def _build_parser() -> argparse.ArgumentParser:
             "  nabla profile   write the site profile\n"
         ),
     )
+    parser.add_argument("--version", action="version", version=f"nabla {__version__}")
     sub = parser.add_subparsers(dest="command", required=True)
 
     p_init = sub.add_parser(
@@ -114,6 +131,34 @@ def _build_parser() -> argparse.ArgumentParser:
     return parser
 
 
+def _ok(msg: str) -> None:
+    _out.print(f"✓ {msg}" if _out.is_terminal else msg, style="green", markup=False)
+
+
+def _warn(msg: str) -> None:
+    _errcon.print(msg, style="yellow", markup=False)
+
+
+def _fail(msg: str) -> None:
+    _errcon.print(msg, style="red", markup=False)
+
+
+def _next_step(cmd: str) -> None:
+    _out.print(f"→ next: {cmd}" if _out.is_terminal else f"next: {cmd}", style="cyan", markup=False)
+
+
+def _unconfigured() -> bool:
+    """True when no provider is set up anywhere — the state where record/
+    profile will fail and the user should be nudged toward `nabla init`."""
+    try:
+        provider = apply_to_env()
+    except Exception:
+        provider = None
+    return provider is None and not (
+        os.environ.get("OPENAI_API_KEY") or os.environ.get("NABLA_UPSTREAM_API_KEY")
+    )
+
+
 def main(argv: list[str] | None = None) -> int:
     # LLM-produced text (goal descriptions, error bodies) can contain
     # characters legacy Windows consoles (cp1252) can't encode; degrade to
@@ -132,6 +177,7 @@ def main(argv: list[str] | None = None) -> int:
     parser = _build_parser()
     argv = sys.argv[1:] if argv is None else argv
     if not argv:
+        print_banner(_out)
         parser.print_help()
         return 0
 
@@ -145,13 +191,43 @@ def main(argv: list[str] | None = None) -> int:
     return commands[args.command](args)
 
 
+def _read_api_key(prompt: str) -> str:
+    """Read a secret with visible masking: one `*` per character, backspace
+    supported, pasting shows a `*` per pasted character — so the user can
+    see that their input (typed or pasted) actually arrived. Falls back to
+    fully hidden input where character-level reading isn't available."""
+    if sys.platform == "win32" and sys.stdin.isatty():
+        import msvcrt
+
+        print(prompt, end="", flush=True)
+        chars: list[str] = []
+        while True:
+            ch = msvcrt.getwch()
+            if ch in ("\r", "\n"):
+                print()
+                break
+            if ch == "\x03":  # Ctrl+C
+                raise KeyboardInterrupt
+            if ch == "\b":
+                if chars:
+                    chars.pop()
+                    print("\b \b", end="", flush=True)
+            elif ch >= " ":
+                chars.append(ch)
+                print("*", end="", flush=True)
+        return "".join(chars).strip()
+    return getpass(f"{prompt} (input is hidden — paste and press Enter): ").strip()
+
+
 def _cmd_init(args) -> int:
+    print_banner(_out)
     provider = args.provider
     if provider is None:
         names = list(PROVIDERS)
-        print("Pick a provider:")
+        _out.print("Pick a provider:", style="bold")
         for i, name in enumerate(names, start=1):
-            print(f"  {i}) {name} — {_PROVIDER_DESCRIPTIONS.get(name, '')}")
+            _out.print(f"  [cyan]{i})[/cyan] [bold]{name}[/bold] — "
+                       f"{_PROVIDER_DESCRIPTIONS.get(name, '')}")
         choice = input("> ").strip()
         if choice.isdigit() and 1 <= int(choice) <= len(names):
             provider = names[int(choice) - 1]
@@ -161,25 +237,25 @@ def _cmd_init(args) -> int:
     api_key = args.api_key
     if api_key is None:
         key_env = PROVIDERS.get(provider, {}).get("api_key_env", "API key")
-        api_key = getpass(f"Paste your {key_env}: ").strip()
+        api_key = _read_api_key(f"Paste your {key_env}: ")
 
     if not api_key:
-        print("nabla init: no API key given", file=sys.stderr)
+        _fail("nabla init: no API key given")
         return 2
 
     try:
         path = save_config(provider, api_key)
     except ValueError as exc:
-        print(f"nabla init: {exc}", file=sys.stderr)
+        _fail(f"nabla init: {exc}")
         return 2
 
     masked = f"...{api_key[-4:]}" if len(api_key) >= 4 else "..."
-    print(f"nabla init: saved to {path} (key: {masked})")
+    _ok(f"nabla init: saved to {path} (key: {masked})")
     try:
         _ensure_scripts_on_path()
     except Exception:
         pass  # PATH help is best-effort; setup itself already succeeded
-    print("Setup complete — try: nabla scan")
+    _next_step("nabla scan  (run it from inside the repo you want to harvest)")
     return 0
 
 
@@ -245,11 +321,42 @@ def _cmd_scan(args) -> int:
     if args.json:
         print(json.dumps(rows, indent=2))
         return 0
-    print(f"{'SYMBOL':<22} {'FILE':<28} {'KIND':<6} {'VERIFIABILITY':<22} FLAGS")
+
+    from rich import box as rich_box
+    from rich.table import Table
+    from rich.text import Text
+
+    table = Table(box=rich_box.SIMPLE_HEAD, header_style="bold", pad_edge=False)
+    for col in ("SYMBOL", "FILE", "KIND", "VERIFIABILITY", "HARVESTABLE", "FLAGS"):
+        table.add_column(col, overflow="fold")
+    supported_count = 0
     for r in rows:
-        print(f"{r['symbol']:<22} {r['file']:<28} {r['kind']:<6} "
-              f"{r['verifiability']:<22} {','.join(r['flags']) or '-'}")
-    print(f"\n{len(rows)} call sites found.")
+        verif = r["verifiability"]
+        harvestable = is_supported(Verifiability(verif), r["flags"])
+        if harvestable:
+            supported_count += 1
+        if verif in ("json_schema", "pydantic_parse"):
+            verif_color = "green"
+        elif verif in ("tool_call", "json_object_no_schema"):
+            verif_color = "yellow"
+        else:
+            verif_color = "dim"
+        table.add_row(
+            Text(r["symbol"], style="cyan"),
+            r["file"],
+            r["kind"],
+            Text(verif, style=verif_color),
+            Text("yes", style="green") if harvestable else Text("no", style="dim"),
+            ",".join(r["flags"]) or "-",
+        )
+    _out.print(table)
+    noun = "call site" if len(rows) == 1 else "call sites"
+    _out.print(f"{len(rows)} {noun} found — {supported_count} harvestable.", markup=False)
+    if supported_count:
+        _next_step("nabla record" + (f" {args.repo}" if args.repo != "." else ""))
+    if _unconfigured():
+        _warn("tip: run `nabla init` once to set up a provider — `nabla record` "
+              "and `nabla profile` need one")
     return 0
 
 
@@ -282,7 +389,8 @@ def _resolve_site(args, sites):
 
     if len(supported) == 1:
         site = supported[0]
-        print(f"nabla: using site {site.symbol} (the only supported call site)")
+        _out.print(f"nabla: using site {site.symbol} (the only supported call site)",
+                   style="dim", markup=False)
         return site, None
 
     candidates = supported or sites
@@ -307,14 +415,11 @@ def _cmd_record(args) -> int:
     if err is not None:
         return err
 
-    if apply_to_env() is None and not (
-        os.environ.get("OPENAI_API_KEY") or os.environ.get("NABLA_UPSTREAM_API_KEY")
-    ):
-        print(
+    if _unconfigured():
+        _warn(
             "nabla record: warning — no API key configured (OPENAI_API_KEY / "
             "NABLA_UPSTREAM_API_KEY unset, and no saved config). Run `nabla init` "
-            "first unless this call site never reaches a real upstream.",
-            file=sys.stderr,
+            "first unless this call site never reaches a real upstream."
         )
 
     source_kind = None  # written to the JSONL; may differ from source.kind
@@ -338,17 +443,21 @@ def _cmd_record(args) -> int:
     try:
         examples = record(site, source, args.repo)
     except ZeroTrafficError as exc:
-        print(f"nabla record: {exc}", file=sys.stderr)
+        _fail(f"nabla record: {exc}")
         return 1
     out = args.out or f"{site.symbol}.recorded.jsonl"
     with open(out, "w", encoding="utf-8") as f:
         for ex in examples:
             f.write(json.dumps({**ex.to_dict(), "_source_kind": source_kind or source.kind}) + "\n")
-    print(f"nabla record: {len(examples)} examples -> {out}")
+    _ok(f"recorded {len(examples)} (prompt, completion) pairs from "
+        f"site {site.symbol} -> {out}")
+    if source_kind == "generated_samples":
+        _warn(f"inputs were synthetic — edit {site.symbol}.samples.jsonl with real "
+              "data and rerun for a higher-fidelity harvest")
     if args.out is None and args.site is None:
-        print(f"next: nabla profile {args.repo}")
+        _next_step(f"nabla profile{'' if args.repo == '.' else ' ' + args.repo}")
     else:
-        print(f"next: nabla profile {args.repo} --site {site.symbol} --examples {out}")
+        _next_step(f"nabla profile {args.repo} --site {site.symbol} --examples {out}")
     return 0
 
 
@@ -425,13 +534,16 @@ def _cmd_profile(args) -> int:
     out = args.out or f"{site.symbol}.profile.json"
     Path(out).write_text(json.dumps(profile, indent=2), encoding="utf-8")
     supported = profile["classification"]["supported"]
-    print(f"nabla profile: wrote {out} "
-          f"(site {profile['site_id'][:12]}…, supported={supported}, "
-          f"{len(examples)} examples)")
+    _ok(f"wrote {out} — the handoff artifact for site {site.symbol}")
+    _out.print(f"  site id      {profile['site_id'][:16]}…", markup=False)
+    _out.print(f"  supported    {supported}", markup=False)
+    _out.print(f"  examples     {len(examples)} ({recorded_from})", markup=False)
+    _out.print(f"  goal         {goal.description[:90]}", markup=False)
+    dims = ", ".join(d["name"] for d in goal.difficulty_dimensions[:4])
+    _out.print(f"  difficulty   {dims}", markup=False)
     if len(examples) < 20:
-        print(f"nabla profile: WARNING — {len(examples)} examples < 20; "
-              "Phase-0-ready profiles need >=20 (cli-plan §5.4)", file=sys.stderr)
-    print(f"goal: {goal.description[:100]}")
+        _warn(f"only {len(examples)} examples (< 20) — enough for a look, "
+              "but a handoff-quality profile wants 20+ real-traffic pairs")
     return 0
 
 

nabla_cli-0.3.0/nabla/term.py

@@ -0,0 +1,53 @@
+"""Minimal terminal styling — ANSI colors with zero dependencies.
+
+Colors are applied only when the target stream is a real terminal and
+NO_COLOR is unset, so piped/captured output stays plain (tests, --json
+consumers, CI logs). init_terminal() switches Windows consoles into VT
+mode, which cmd.exe does not enable by default.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+_CODES = {
+    "bold": "1",
+    "dim": "2",
+    "red": "31",
+    "green": "32",
+    "yellow": "33",
+    "cyan": "36",
+}
+
+
+def init_terminal() -> None:
+    if sys.platform != "win32":
+        return
+    try:
+        import ctypes
+
+        kernel32 = ctypes.windll.kernel32
+        for handle_id in (-11, -12):  # stdout, stderr
+            handle = kernel32.GetStdHandle(handle_id)
+            mode = ctypes.c_ulong()
+            if kernel32.GetConsoleMode(handle, ctypes.byref(mode)):
+                kernel32.SetConsoleMode(handle, mode.value | 0x0004)  # ENABLE_VIRTUAL_TERMINAL_PROCESSING
+    except Exception:
+        pass  # styling is cosmetic; never let it break a command
+
+
+def supports_color(stream=None) -> bool:
+    stream = stream or sys.stdout
+    if os.environ.get("NO_COLOR"):
+        return False
+    return hasattr(stream, "isatty") and stream.isatty()
+
+
+def style(text: str, *names: str, stream=None) -> str:
+    """Wrap text in ANSI codes when the stream supports it. Apply AFTER any
+    column padding — escape codes are invisible but count toward len()."""
+    if not names or not supports_color(stream):
+        return text
+    codes = ";".join(_CODES[n] for n in names)
+    return f"\x1b[{codes}m{text}\x1b[0m"

{nabla_cli-0.2.0 → nabla_cli-0.3.0}/nabla_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nabla-cli
-Version: 0.2.0
+Version: 0.3.0
 Summary: Call-site harvester: scan OpenAI call sites, record real traffic, emit site profiles
 License: MIT
 Requires-Python: >=3.11
@@ -8,6 +8,7 @@ Description-Content-Type: text/markdown
 Requires-Dist: jsonschema
 Requires-Dist: pydantic>=2
 Requires-Dist: openai>=1.40
+Requires-Dist: rich>=13.0
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 

{nabla_cli-0.2.0 → nabla_cli-0.3.0}/nabla_cli.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ README.md
 pyproject.toml
 nabla/__init__.py
 nabla/__main__.py
+nabla/branding.py
 nabla/cli.py
 nabla/config.py
 nabla/contract.py
@@ -12,6 +13,7 @@ nabla/recorder.py
 nabla/samplegen.py
 nabla/scanner.py
 nabla/schema_resolver.py
+nabla/term.py
 nabla/schemas/site_profile.schema.json
 nabla_cli.egg-info/PKG-INFO
 nabla_cli.egg-info/SOURCES.txt

{nabla_cli-0.2.0 → nabla_cli-0.3.0}/nabla_cli.egg-info/requires.txt

@@ -1,6 +1,7 @@
 jsonschema
 pydantic>=2
 openai>=1.40
+rich>=13.0
 
 [dev]
 pytest

{nabla_cli-0.2.0 → nabla_cli-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nabla-cli"
-version = "0.2.0"
+version = "0.3.0"
 description = "Call-site harvester: scan OpenAI call sites, record real traffic, emit site profiles"
 readme = "README.md"
 license = { text = "MIT" }
@@ -9,6 +9,7 @@ dependencies = [
     "jsonschema",
     "pydantic>=2",
     "openai>=1.40",
+    "rich>=13.0",
 ]
 
 [project.optional-dependencies]

{nabla_cli-0.2.0 → nabla_cli-0.3.0}/tests/test_cli_ux.py

@@ -80,7 +80,7 @@ def test_init_writes_config(tmp_path, monkeypatch, capsys):
     out = capsys.readouterr().out
     assert "gsk_test" not in out  # the full key must never be echoed
     assert "test" in out  # masked last-4 tail is shown
-    assert "Setup complete — try: nabla scan" in out
+    assert "next: nabla scan" in out
 
 
 def test_init_bad_provider_exits_nonzero_with_helpful_message(capsys):
@@ -282,7 +282,7 @@ def test_profile_finds_recorded_file_by_convention(tmp_path, monkeypatch, capsys
     assert (tmp_path / "extract_receipt.profile.json").exists()
     stdout = capsys.readouterr().out
     assert "using extract_receipt.recorded.jsonl" in stdout
-    assert "goal: Extracts receipt fields." in stdout
+    assert "Extracts receipt fields." in stdout
 
 
 def test_profile_without_recorded_file_exits_2_with_record_command(tmp_path, monkeypatch, capsys):
@@ -330,3 +330,21 @@ def test_ensure_scripts_on_path_non_windows_prints_instruction(monkeypatch, caps
     out = capsys.readouterr().out
     assert "PATH" in out
     assert "python -m nabla" in out
+
+
+def test_scan_prints_init_tip_when_unconfigured(capsys):
+    rc = main(["scan", FIXTURE_REPO])
+    assert rc == 0
+    assert "nabla init" in capsys.readouterr().err
+
+
+def test_scan_json_output_stays_clean_json(capsys):
+    rc = main(["scan", FIXTURE_REPO, "--json"])
+    assert rc == 0
+    json.loads(capsys.readouterr().out)  # must parse — no tip/color on stdout
+
+
+def test_style_is_plain_when_not_a_tty(capsys):
+    from nabla.term import style
+
+    assert style("hello", "red") == "hello"  # captured stdout is not a tty