substratum-cli 0.2.7__tar.gz → 0.2.8__tar.gz

{substratum_cli-0.2.7 → substratum_cli-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: substratum-cli
-Version: 0.2.7
+Version: 0.2.8
 Summary: Substratum: verified-or-refused code, with provenance. The terminal over the comprehension engine.
 Author: Substratum
 License: LicenseRef-Proprietary

{substratum_cli-0.2.7 → substratum_cli-0.2.8}/substratum_cli/__init__.py

@@ -5,4 +5,4 @@ Import budget: this package is stdlib-only; the ONLY module reaching into backen
 """
 # SINGLE SOURCE OF TRUTH for the release version. pyproject reads this (dynamic version), the boot shows
 # it, and the update-check compares against it. To cut a release, bump ONLY this line, then publish.
-__version__ = "0.2.7"
+__version__ = "0.2.8"

substratum_cli-0.2.8/substratum_cli/_tui.py

@@ -0,0 +1,435 @@
+"""Substratum's interactive surfaces: the command PALETTE ("/") and the LOOP VIEWER (help).
+
+Not a generic menu -- the instrument's own language: the ◆ brand mark is the selector, panels
+carry the verdict rail (│ ... └──), verbs render PROVEN green, transitions gold. The help viewer's
+tab bar IS the loop (1 understand ▸ 2 build ▸ 3 land ▸ 4 remember ▸ setup ▸ more): left/right
+walks the workflow itself, the active stage lit, and YOUR live state pinned at the bottom.
+
+Stdlib only (termios + ANSI), POSIX, drawn on the alternate screen so the session scrollback stays
+pristine. Every entry point degrades gracefully off-TTY (returns None; callers fall back to the
+static text). Keys: type to filter · up/down move · left/right stages · Enter select · Esc close.
+"""
+from __future__ import annotations
+
+import os
+import sys
+from typing import List, Optional, Sequence, Tuple
+
+from . import style as S
+
+_ALT_ON = "\x1b[?1049h\x1b[H"
+_ALT_OFF = "\x1b[?1049l"
+_CLEAR = "\x1b[2J\x1b[H"
+_HIDE = "\x1b[?25l"
+_SHOW = "\x1b[?25h"
+_R = S.RESET if hasattr(S, "RESET") else "\x1b[0m"
+
+
+def _term_size() -> Tuple[int, int]:
+    try:
+        sz = os.get_terminal_size()
+        return sz.columns, sz.lines
+    except OSError:
+        return 100, 30
+
+
+_PENDING: dict = {}                     # fd -> bytearray of pushed-back bytes
+
+
+def _getch(fd: int, wait: float = None) -> bytes:
+    """One byte, honoring pushback. wait=None blocks; wait=seconds returns b"" on timeout."""
+    q = _PENDING.get(fd)
+    if q:
+        b = bytes(q[:1])
+        del q[:1]
+        return b
+    if wait is not None:
+        import select
+        if not select.select([fd], [], [], wait)[0]:
+            return b""
+    return os.read(fd, 1)
+
+
+def _push(fd: int, b: bytes) -> None:
+    _PENDING.setdefault(fd, bytearray()).extend(b)
+
+
+def read_key(fd: int) -> str:
+    """One LOGICAL keypress: up/down/left/right/home/end/delete/enter/esc/backspace or the decoded
+    character. Byte-wise with pushback: a lone Esc never swallows the keys typed after it, and
+    escape sequences survive byte-at-a-time arrival (fast typing, ptys, slow ssh)."""
+    ch = _getch(fd)
+    if not ch:
+        raise EOFError
+    if ch == b"\x1b":
+        nxt = _getch(fd, wait=0.05)
+        if not nxt:
+            return "esc"
+        if nxt != b"[" and nxt != b"O":
+            _push(fd, nxt)                 # a lone Esc followed by a normal key: keep the key
+            return "esc"
+        fin = _getch(fd, wait=0.10) or b""
+        m = {b"A": "up", b"B": "down", b"C": "right", b"D": "left", b"H": "home", b"F": "end"}
+        if fin in m:
+            return m[fin]
+        if fin == b"3":
+            _getch(fd, wait=0.05)          # the trailing ~ of delete
+            return "delete"
+        return "esc"
+    if ch in (b"\r", b"\n"):
+        return "enter"
+    if ch in (b"\x7f", b"\x08"):
+        return "backspace"
+    if ch == b"\x03":
+        raise KeyboardInterrupt
+    if ch == b"\x04":
+        return "ctrl-d"
+    if ch == b"\x01":
+        return "ctrl-a"
+    if ch == b"\x05":
+        return "ctrl-e"
+    if ch == b"\x15":
+        return "ctrl-u"
+    if ch == b"\x0b":
+        return "ctrl-k"
+    if ch == b"\x17":
+        return "ctrl-w"
+    if ch == b"\t":
+        return "tab"
+    return _read_utf8(fd, ch)
+
+
+class _raw:
+    def __init__(self, fd: int):
+        self.fd = fd
+
+    def __enter__(self):
+        import termios
+        import tty
+        self.saved = termios.tcgetattr(self.fd)
+        tty.setcbreak(self.fd)
+        return self
+
+    def __exit__(self, *a):
+        import termios
+        termios.tcsetattr(self.fd, termios.TCSADRAIN, self.saved)
+
+
+def tty_ok() -> bool:
+    return sys.stdin.isatty() and sys.stdout.isatty() and os.name == "posix"
+
+
+def filter_items(items: Sequence[Tuple[str, str]], needle: str) -> List[Tuple[str, str]]:
+    """The palette's live filter: name-prefix matches first, then substring (name or blurb)."""
+    n = needle.lower()
+    if not n:
+        return list(items)
+    pref = [i for i in items if i[0].lower().startswith(n)]
+    sub = [i for i in items if i not in pref
+           and (n in i[0].lower() or n in i[1].lower())]
+    return pref + sub
+
+
+def palette(items: Sequence[Tuple[str, str]]) -> Optional[str]:
+    """The command palette: ◆-marked selection, verdict-rail panel, live filter. Returns the
+    selected command name, or None (Esc / off-TTY)."""
+    if not tty_ok():
+        return None
+    fd = sys.stdin.fileno()
+    needle, cursor = "", 0
+    out = sys.stdout
+    rail = f"{S.CHROME}{S.g('rail')}{_R}"
+    try:
+        out.write(_ALT_ON + _HIDE)
+        with _raw(fd):
+            while True:
+                cols, lines = _term_size()
+                view = filter_items(items, needle)
+                cursor = max(0, min(cursor, max(0, len(view) - 1)))
+                vis = max(4, lines - 7)
+                top = max(0, min(cursor - vis // 2, max(0, len(view) - vis)))
+                out.write(_CLEAR)
+                out.write(f" {S.GOLD}{S.g('brand')} substratum{_R}   "
+                          f"{S.LABEL}type to filter · ↵ choose · esc close{_R}\n")
+                out.write(f" {rail} {S.GOLD}/{_R}{needle}\n {rail}\n")
+                for i, (name, desc) in enumerate(view[top:top + vis]):
+                    j = top + i
+                    mark = f"{S.GOLD}{S.g('brand')}{_R}" if j == cursor else " "
+                    verb = f"{S.PROVEN_B if j == cursor else S.PROVEN}{name.ljust(15)}{_R}"
+                    blurb = desc[:max(10, cols - 26)]
+                    tint = _R if j == cursor else S.LABEL
+                    out.write(f" {rail} {mark} {verb} {tint}{blurb}{_R}\n")
+                if not view:
+                    out.write(f" {rail}   {S.LABEL}nothing matches {needle!r}{_R}\n")
+                out.write(f" {S.CHROME}{S.g('foot')}{S.g('bar') * 2}{_R}\n")
+                out.flush()
+                k = read_key(fd)
+                if k == "esc":
+                    return None
+                if k == "enter":
+                    return view[cursor][0] if view else None
+                if k == "up":
+                    cursor -= 1
+                elif k == "down":
+                    cursor += 1
+                elif k == "backspace":
+                    needle = needle[:-1]
+                elif len(k) == 1 and k.isprintable():
+                    needle += k
+                    cursor = 0
+    finally:
+        out.write(_SHOW + _ALT_OFF)
+        out.flush()
+
+
+def loop_viewer(stages, footer_line: str = "") -> Optional[str]:
+    """The help menu: plain section tabs (active lit), ↑/↓ moves the ◆ through the section's
+    commands, Enter returns the picked verb (the caller runs it or prefills it -- parameterless
+    commands just run), ←/→ switches sections, Esc closes. One dim bottom line carries the keys +
+    the live state. Returns the verb or None; no-op off-TTY."""
+    if not tty_ok():
+        return None
+    fd = sys.stdin.fileno()
+    ti, sel = 0, 0
+    out = sys.stdout
+    rail = f"{S.CHROME}{S.g('rail')}{_R}"
+    try:
+        out.write(_ALT_ON + _HIDE)
+        with _raw(fd):
+            while True:
+                cols, lines = _term_size()
+                tabs = "   ".join(
+                    f"{S.GOLD}{n}{_R}" if i == ti else f"{S.LABEL}{n}{_R}"
+                    for i, (n, _) in enumerate(stages))
+                rows = list(stages[ti][1])
+                sel = max(0, min(sel, len(rows) - 1))
+                vis = max(4, lines - 6)
+                top = max(0, min(sel - vis // 2, max(0, len(rows) - vis)))
+                out.write(_CLEAR)
+                out.write(f" {S.GOLD}{S.g('brand')} Help{_R}   {tabs}\n {rail}\n")
+                for i, (cmd, desc) in enumerate(rows[top:top + vis]):
+                    j = top + i
+                    mark = f"{S.GOLD}{S.g('brand')}{_R}" if j == sel else " "
+                    verb = f"{S.PROVEN_B if j == sel else S.PROVEN}{cmd.ljust(28)}{_R}"
+                    tint = _R if j == sel else S.LABEL
+                    out.write(f" {rail} {mark} {verb} {tint}{desc[:max(10, cols - 40)]}{_R}\n")
+                out.write(f" {S.CHROME}{S.g('foot')}{S.g('bar') * 2}{_R}\n")
+                keys = "↑↓ choose · ↵ run · ←→ sections · esc"
+                line = keys + (f"   {S.g('dot')} {footer_line}" if footer_line else "")
+                out.write(f" {S.LABEL}{line[:cols - 3]}{_R}\n")
+                out.flush()
+                k = read_key(fd)
+                if k in ("esc", "q"):
+                    return None
+                if k == "enter":
+                    return rows[sel][0].split()[0].strip('"') if rows else None
+                if k == "right":
+                    ti = (ti + 1) % len(stages)
+                    sel = 0
+                elif k == "left":
+                    ti = (ti - 1) % len(stages)
+                    sel = 0
+                elif k == "up":
+                    sel -= 1
+                elif k == "down":
+                    sel += 1
+    finally:
+        out.write(_SHOW + _ALT_OFF)
+        out.flush()
+
+
+def dropdown(fd: int, out, prompt: str, items) -> Optional[str]:
+    """The Claude-Code-shaped dropdown, in Substratum's language: rendered INLINE under the live
+    prompt (never a screen takeover). Type to filter, up/down move (◆ marks the pick), Enter
+    returns the pick, Esc dismisses; either way every dropdown row is erased and the prompt line
+    is exactly where you left it."""
+    needle, cursor, prev_rows = "", 0, 0
+    VIS = 8
+
+    def render():
+        nonlocal prev_rows
+        view = filter_items(items, needle)
+        nonlocal cursor
+        cursor = max(0, min(cursor, max(0, len(view) - 1)))
+        top = max(0, min(cursor - VIS // 2, max(0, len(view) - VIS)))
+        rows = []
+        for i, (name, desc) in enumerate(view[top:top + VIS]):
+            j = top + i
+            mark = f"{S.GOLD}{S.g('brand')}{_R}" if j == cursor else " "
+            verb = f"{S.PROVEN_B if j == cursor else S.PROVEN}{name.ljust(15)}{_R}"
+            rows.append(f"  {mark} {verb} {S.LABEL}{desc[:70]}{_R}")
+        if len(view) > VIS:
+            rows.append(f"    {S.CHROME}{S.g('dot')} {len(view) - VIS} more -- keep typing{_R}")
+        if not view:
+            rows.append(f"    {S.LABEL}no match -- ↵ runs /{needle} literally · esc closes{_R}")
+        # draw the prompt line, then the rows; pad with blank lines to erase stale ones
+        out.write("\r\x1b[K" + prompt + f"{S.GOLD}/{_R}" + needle)
+        n = max(len(rows), prev_rows)
+        for i in range(n):
+            out.write("\n\x1b[K" + (rows[i] if i < len(rows) else ""))
+        out.write(f"\x1b[{n}A" + "\r\x1b[K" + prompt + f"{S.GOLD}/{_R}" + needle)
+        out.flush()
+        prev_rows = len(rows)
+        return view
+
+    def erase():
+        n = prev_rows
+        for _ in range(n):
+            out.write("\n\x1b[K")
+        if n:
+            out.write(f"\x1b[{n}A")
+        out.write("\r\x1b[K")
+        out.flush()
+
+    view = render()
+    while True:
+        k = read_key(fd)
+        if k == "esc":
+            erase()
+            return None
+        if k == "enter":
+            pick = view[cursor][0] if view else ("/" + needle if needle else None)
+            erase()
+            return pick
+        if k == "up":
+            cursor -= 1
+        elif k == "down":
+            cursor += 1
+        elif k == "backspace":
+            if not needle:                 # backspacing past the "/" closes the dropdown
+                erase()
+                return None
+            needle = needle[:-1]
+            cursor = 0
+        elif len(k) == 1 and k.isprintable():
+            needle += k
+            cursor = 0
+        view = render()
+
+
+# ---- the prompt editor: readline-feel, with "/" opening the dropdown INSTANTLY ------------------
+
+def _read_utf8(fd: int, first: bytes) -> str:
+    """Complete a UTF-8 char whose first byte was already read (paste-safe)."""
+    b = first[0]
+    n = 1 if b < 0x80 else (2 if b < 0xE0 else (3 if b < 0xF0 else 4))
+    data = first + (os.read(fd, n - 1) if n > 1 else b"")
+    try:
+        return data.decode("utf-8")
+    except UnicodeDecodeError:
+        return ""
+
+
+def read_line(prompt: str, history: list, complete_words, palette_items, state: dict,
+              should_submit=None) -> str:
+    """A raw-mode line editor for the MAIN prompt. Readline-feel for the common keys (chars,
+    backspace/delete, arrows, home/end, ctrl-a/e/u/k/w, up/down history, tab word-complete,
+    ctrl-c clears via KeyboardInterrupt, ctrl-d on empty raises EOFError) -- and pressing "/" on
+    an EMPTY line opens the inline dropdown immediately, inserting the pick into the live buffer.
+
+    `state` is a shared dict async notices read ({"buffer": str}); a "prefill" key seeds the line."""
+    fd = sys.stdin.fileno()
+    out = sys.stdout
+    submit = state.pop("submit", "")
+    if submit:                                             # a picked parameterless command: run it
+        out.write("\r\x1b[K" + prompt + submit + "\n")
+        out.flush()
+        state["buffer"] = ""
+        return submit
+    buf = state.pop("prefill", "")
+    buf = (buf + " ") if buf else ""
+    cur = len(buf)
+    hist_i, stash = len(history), ""
+
+    def draw():
+        state["buffer"] = buf
+        out.write("\r\x1b[K" + prompt + buf)
+        if cur < len(buf):
+            out.write(f"\x1b[{len(buf) - cur}D")
+        out.flush()
+
+    draw()
+    with _raw(fd):
+        if state.pop("open_dropdown", False):              # a handed-off "/" opens it right here
+            pick = dropdown(fd, out, prompt, palette_items())
+            if pick and pick.startswith("/"):
+                out.write("\r\x1b[K" + prompt + pick + "\n")
+                out.flush()
+                state["buffer"] = ""
+                return pick
+            if pick:
+                buf = pick + " "
+                cur = len(buf)
+            draw()
+        while True:
+            k = read_key(fd)
+            if k == "ctrl-d":
+                if not buf:
+                    raise EOFError
+                continue
+            if k == "enter":
+                out.write("\n")
+                out.flush()
+                state["buffer"] = ""
+                return buf
+            if k == "up":
+                if hist_i > 0:
+                    if hist_i == len(history):
+                        stash = buf
+                    hist_i -= 1
+                    buf = history[hist_i]
+                    cur = len(buf)
+            elif k == "down":
+                if hist_i < len(history):
+                    hist_i += 1
+                    buf = history[hist_i] if hist_i < len(history) else stash
+                    cur = len(buf)
+            elif k == "right":
+                cur = min(len(buf), cur + 1)
+            elif k == "left":
+                cur = max(0, cur - 1)
+            elif k == "home" or k == "ctrl-a":
+                cur = 0
+            elif k == "end" or k == "ctrl-e":
+                cur = len(buf)
+            elif k == "delete":
+                if cur < len(buf):
+                    buf = buf[:cur] + buf[cur + 1:]
+            elif k == "backspace":
+                if cur > 0:
+                    buf = buf[:cur - 1] + buf[cur:]
+                    cur -= 1
+            elif k == "ctrl-u":
+                buf, cur = "", 0
+            elif k == "ctrl-k":
+                buf = buf[:cur]
+            elif k == "ctrl-w":
+                left = buf[:cur].rstrip()
+                cut = left.rfind(" ") + 1
+                buf, cur = buf[:cut] + buf[cur:], cut
+            elif k == "tab":
+                head = buf[:cur]
+                if " " not in head.strip():
+                    cands = [w for w in complete_words() if w.startswith(head.strip())]
+                    if len(cands) == 1:
+                        buf = cands[0] + " " + buf[cur:].lstrip()
+                        cur = len(cands[0]) + 1
+                    elif len(cands) > 1:
+                        out.write("\n  " + "  ".join(cands[:14]) + "\n")
+            elif k == "esc":
+                pass
+            elif k == "/" and not buf:                         # the dropdown: instant, inline
+                pick = dropdown(fd, out, prompt, palette_items())
+                if pick and (pick.startswith("/")
+                             or (should_submit and should_submit(pick))):
+                    out.write("\r\x1b[K" + prompt + pick + "\n")
+                    out.flush()
+                    state["buffer"] = ""
+                    return pick                                # slash-commands + parameterless: run
+                if pick:
+                    buf = pick + " "
+                    cur = len(buf)
+            elif len(k) >= 1 and k.isprintable():
+                buf = buf[:cur] + k + buf[cur:]
+                cur += len(k)
+            draw()