workmap 0.1.0__py3-none-any.whl

workmap/tui/onboarding.py

@@ -0,0 +1,266 @@
+"""How setup looks.
+
+Setup is the first thing anybody sees, and it is the only screen that has to
+sell the tool before the tool has done anything. So it uses the same vocabulary
+as the desk, rounded panels, the hairline rail, one restrained palette, and
+not a second style invented for the occasion.
+
+Presentation only. Every decision setup makes lives in `workmap/setup.py`;
+nothing here knows what a root or an agent is, which is why it can be rendered
+into a string and asserted on.
+"""
+from __future__ import annotations
+
+import itertools
+import os
+import sys
+import threading
+import time
+
+from .text import (AMBER, BOLD, DIM, RESET, cell, fg, strip_ansi)
+from .widgets import RAIL_ON, box_bot, box_row, box_top, frame_width
+
+# Progress glyphs. Filled / current / not yet, the same "state at a glance"
+# idea as the project rail, so the two screens read as one product.
+DONE, CURRENT, TODO = "●", "◆", "○"
+CHECK, CROSS = "✓", "·"
+
+ACCENT = 111        # the blue the panels lean on
+MUTED = 244
+
+SPINNER = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
+FRAME_S = 0.08
+REVEAL_S = 0.035    # per-row stagger; small enough to feel like one motion
+
+
+def colour() -> bool:
+    """Style output? Not when piped, and not when asked not to.
+
+    NO_COLOR is honoured because a setup screen is exactly the kind of thing
+    people capture into an issue or a terminal recording.
+    """
+    if os.environ.get("NO_COLOR"):
+        return False
+    return sys.stdout.isatty()
+
+
+def animate() -> bool:
+    """Motion is for people watching. Never for pipes, CI, or a recording."""
+    return colour() and not os.environ.get("WORKMAP_NO_ANIM")
+
+
+def _style(s: str, *codes: str) -> str:
+    return "".join(codes) + s + RESET if colour() else s
+
+
+def plain(line: str) -> str:
+    """Drop styling when nobody can see it.
+
+    The panel helpers in widgets.py always colour their borders, they were
+    written for a TUI, which is only ever on a terminal. Setup is not: people
+    pipe it, capture it into issues, and run it in CI, and escape codes in a
+    pasted transcript are noise.
+    """
+    return line if colour() else strip_ansi(line)
+
+
+def say(line: str = "") -> None:
+    """One line, styled only if it will be seen."""
+    print(plain(line))
+
+
+def width() -> int:
+    try:
+        cols = os.get_terminal_size().columns
+    except OSError:
+        cols = 80
+    # No cap of its own: `frame_width` already stops at FRAME_MAX. This used
+    # to read `min(cols, 100)`, which says a setup panel can be a hundred
+    # columns wide. It cannot, at any width, and a second ceiling written in
+    # a different number is a ceiling somebody will one day raise.
+    return frame_width(max(46, cols))
+
+
+def rail(step: int, total: int) -> str:
+    """● ● ◆ ○, where you are, without spending a line saying so."""
+    marks = []
+    for i in range(1, total + 1):
+        if i < step:
+            marks.append(_style(DONE, fg(ACCENT)))
+        elif i == step:
+            marks.append(_style(CURRENT, fg(ACCENT), BOLD))
+        else:
+            marks.append(_style(TODO, DIM))
+    return " ".join(marks)
+
+
+def panel(title: str, body: list[str], *, step: int, total: int) -> list[str]:
+    """One step, framed. `body` lines may carry ANSI; they are padded safely."""
+    inner = width() - 4
+    head = _style("workmap setup", BOLD)
+    lines = [box_top(inner, title=head, tail=rail(step, total)), box_row(inner)]
+    lines.append(box_row(inner, "  " + _style(title, BOLD)))
+    lines.append(box_row(inner))
+    for line in body:
+        lines.append(box_row(inner, "  " + line if line else ""))
+    lines.append(box_row(inner))
+    lines.append(box_bot(inner))
+    return lines
+
+
+def render(lines: list[str], *, stagger: bool = True) -> None:
+    """Print a panel, one row at a time when someone is watching."""
+    delay = REVEAL_S if (stagger and animate()) else 0
+    for line in lines:
+        sys.stdout.write(plain(line) + "\n")
+        if delay:
+            sys.stdout.flush()
+            time.sleep(delay)
+    if not delay:
+        sys.stdout.flush()
+
+
+def found(label: str, detail: str = "", *, ok: bool = True) -> str:
+    """A checklist row: mark, name, and a dim detail column."""
+    mark = _style(CHECK, fg(ACCENT)) if ok else _style(CROSS, DIM)
+    name = cell(label, 12)
+    name = _style(name, BOLD) if ok else _style(name, DIM)
+    return f"{mark} {name}{_style(detail, DIM)}"
+
+
+def listing(text: str, *, ok: bool = False) -> str:
+    """A checklist row whose label is prose, not a name to line up."""
+    mark = _style(CHECK, fg(ACCENT)) if ok else _style(CROSS, DIM)
+    return f"{mark} {_style(text, DIM)}"
+
+
+def path_label(path) -> str:
+    """`~/dev/Company` rather than the whole thing.
+
+    Panels are a fixed measure and paths are the longest thing in them, so
+    the part that identifies the directory is the part worth keeping.
+    """
+    text = str(path)
+    home = str(os.path.expanduser("~"))
+    if text == home:
+        return "~"
+    if text.startswith(home + os.sep):
+        return "~" + text[len(home):]
+    return text
+
+
+def command(cmd: str) -> str:
+    """Something you can literally type, on its own line.
+
+    Paired with command_note() underneath rather than a description beside
+    it: `work acme-api` plus a sentence does not fit across a panel, and a
+    command that wraps is a command you cannot copy.
+    """
+    return f"{_style(RAIL_ON, fg(ACCENT))} {_style(cmd, BOLD)}"
+
+
+def command_note(what: str) -> str:
+    """What the command above does."""
+    return f"  {_style(what, DIM)}"
+
+
+def note(text: str) -> str:
+    return _style(text, DIM)
+
+
+def warn(text: str) -> str:
+    return _style(text, AMBER)
+
+
+def bullet(text: str) -> str:
+    return f"{_style(RAIL_ON, fg(ACCENT))} {text}"
+
+
+def spin(label: str, work):
+    """Run `work()` behind a spinner. The spinner tracks real work only.
+
+    If the work finishes instantly the spinner is never drawn, because a
+    loader for something that did not take time is a small lie.
+    """
+    if not animate():
+        result = work()
+        say("  " + listing(label, ok=True))
+        return result
+
+    box: dict = {}
+
+    def run():
+        try:
+            box["value"] = work()
+        except BaseException as exc:  # surfaced by the caller
+            box["error"] = exc
+
+    thread = threading.Thread(target=run, daemon=True)
+    thread.start()
+    for frame in itertools.cycle(SPINNER):
+        thread.join(timeout=FRAME_S)
+        if not thread.is_alive():
+            break
+        sys.stdout.write(f"\r  {_style(frame, fg(ACCENT))} {note(label)}")
+        sys.stdout.flush()
+    sys.stdout.write("\r\033[2K")
+    if "error" in box:
+        raise box["error"]
+    return box.get("value")
+
+
+def ask(question: str, *, enter_does: str, default: str = "") -> str:
+    """A question, and what the Enter key will do about it.
+
+    `enter_does` is not optional on purpose. The first version of this screen
+    rendered "change them? colon-separated paths [keep]" and the first person
+    to use it did not know that pressing Enter would move on, a prompt that
+    does not name its own default is a prompt you have to guess at.
+    """
+    arrow = _style("›", fg(ACCENT))
+    hint = _style(f"(Enter = {enter_does})", DIM)
+    try:
+        answer = input(f"  {arrow} {question}  {hint}  ").strip()
+    except (EOFError, KeyboardInterrupt):
+        print()
+        return default
+    return answer or default
+
+
+def title_card(steps: list[str]) -> list[str]:
+    """What is about to happen, and how to get through it.
+
+    Listing the steps up front costs four lines and buys the thing every
+    setup screen is missing: knowing how long this is and what it wants.
+    """
+    inner = width() - 4
+    out = [
+        box_top(inner, title=_style("workmap", BOLD)),
+        box_row(inner),
+        box_row(inner, "  " + _style("Let's get you set up.", BOLD)),
+        box_row(inner),
+    ]
+    for i, step in enumerate(steps, 1):
+        out.append(box_row(inner, f"  {_style(str(i), fg(ACCENT), BOLD)}  {step}"))
+    out.append(box_row(inner))
+    out.append(box_row(inner, "  " + _style(
+        "Each question suggests an answer in grey.", DIM)))
+    out.append(box_row(inner, "  " + _style(
+        "Press Enter to take it, or type your own.", DIM)))
+    out.append(box_row(inner))
+    out.append(box_bot(inner))
+    return out
+
+
+def done_card(lines: list[str], title: str = "you're all set") -> list[str]:
+    """The last screen. `title` because a run where a step was skipped is not
+    one where you are all set, and saying so anyway is the kind of small lie
+    that makes the rest of the screen worth less."""
+    inner = width() - 4
+    head = (fg(ACCENT) + BOLD + title + RESET if colour() else title)
+    out = [box_top(inner, title=head), box_row(inner)]
+    for line in lines:
+        out.append(box_row(inner, "  " + line if line else ""))
+    out.append(box_row(inner))
+    out.append(box_bot(inner))
+    return out

workmap/tui/text.py

@@ -0,0 +1,156 @@
+"""ANSI styling and the display-width model.
+
+Terminal titles carry CJK and emoji, so every pad/truncate measures display
+columns rather than len(). Pure string maths, no state, no I/O."""
+from __future__ import annotations
+
+import re
+import unicodedata
+
+
+RESET = "\033[0m"
+
+DIM = "\033[2m"
+
+BOLD = "\033[1m"
+
+REV = "\033[7m"
+
+HIDE = "\033[?25l"
+
+SHOW = "\033[?25h"
+
+ALT_ON = "\033[?1049h"
+
+ALT_OFF = "\033[?1049l"
+
+HOME = "\033[H"
+
+CLEAR_LINE = "\033[2K"
+
+# Restrained palette: borders recede, chips pop, amber = needs attention.
+BORDER = "\033[38;5;240m"
+
+CHIP_BG = "\033[48;5;238m"
+
+CHIP_TX = "\033[38;5;231m"
+
+AMBER = "\033[38;5;208m"  # real warnings only: swap pressure, confirmations
+
+TAG = "\033[38;5;137m"  # muted marker for the inline "orphaned" tag
+
+GOOD = "\033[38;5;114m"
+
+
+def fg(n: int) -> str:
+    return f"\033[38;5;{n}m"
+
+# ---------------------------------------------------------------- width model
+# Every pad/truncate goes through display columns, not len(). Terminal titles
+# carry CJK and emoji; len() would silently skew whole columns.
+_ANSI_RE = re.compile(r"\033\[[0-9;?]*[ -/]*[@-~]")
+
+
+def _char_w(ch: str) -> int:
+    if unicodedata.combining(ch):
+        return 0
+    o = ord(ch)
+    if o < 32 or o == 0x7F:
+        return 0
+    if unicodedata.east_asian_width(ch) in ("W", "F"):
+        return 2
+    if 0x1F300 <= o <= 0x1FAFF or 0x1F004 <= o <= 0x1F0CF:
+        return 2
+    return 1
+
+
+def disp_width(s: str) -> int:
+    """Display columns of PLAIN text."""
+    return sum(_char_w(c) for c in s)
+
+
+def strip_ansi(s: str) -> str:
+    return _ANSI_RE.sub("", s)
+
+
+def visible_len(s: str) -> int:
+    """Display columns of possibly-styled text."""
+    return disp_width(strip_ansi(s))
+
+
+def cell(text: str, width: int, *, align: str = "left") -> str:
+    """Exact-width PLAIN cell. Truncate/pad before any ANSI is applied.
+
+    Control characters are dropped rather than measured. They are zero columns
+    wide, so the arithmetic here was always right, but a cell is composed into
+    a screen the caller has already laid out and an escape character carries no
+    width while still moving the cursor. Project names come from directory
+    names and session labels from window titles, so this is the last point
+    where either can still be text rather than instructions.
+
+    A combining mark at the front is dropped for the same reason. It has
+    nothing inside the cell to attach to, so the terminal draws it over
+    whatever occupies the column to the left: the rail glyph, or the last
+    character of the cell before. One cell putting a mark in another one is
+    the same class of problem as an escape moving the cursor.
+    """
+    text = "".join(" " if ch in "\t\n\r" else ch
+                   for ch in text if (ch >= " " and ch != "\x7f") or ch in "\t\n\r")
+    lead = 0
+    while lead < len(text) and unicodedata.combining(text[lead]):
+        lead += 1
+    text = text[lead:]
+    if width <= 0:
+        return ""
+    w = disp_width(text)
+    if w > width:
+        out = ""
+        used = 0
+        for ch in text:
+            cw = _char_w(ch)
+            if used + cw > width - 1:
+                break
+            out += ch
+            used += cw
+        return out + "…" + " " * (width - 1 - used)
+    return (" " * (width - w)) + text if align == "right" else text + (" " * (width - w))
+
+
+def pad_ansi(s: str, width: int) -> str:
+    """Pad/truncate styled text to exact display columns (ANSI-safe)."""
+    w = visible_len(s)
+    if w <= width:
+        return s + " " * (width - w)
+    out: list[str] = []
+    used = 0
+    i = 0
+    while i < len(s):
+        if s[i] == "\033":
+            m = _ANSI_RE.match(s, i)
+            if m:
+                out.append(m.group())
+                i = m.end()
+                continue
+        cw = _char_w(s[i])
+        if used + cw > max(0, width - 1):
+            break
+        out.append(s[i])
+        used += cw
+        i += 1
+    return "".join(out) + "…" + RESET + " " * max(0, width - used - 1)
+
+
+def wrap_plain(text: str, width: int) -> list[str]:
+    words = text.split()
+    lines: list[str] = []
+    cur = ""
+    for w in words:
+        trial = f"{cur} {w}".strip()
+        if disp_width(trial) <= width or not cur:
+            cur = trial
+        else:
+            lines.append(cur)
+            cur = w
+    if cur:
+        lines.append(cur)
+    return lines or [""]

workmap/tui/widgets.py

@@ -0,0 +1,189 @@
+"""The visual vocabulary: rounded panels, key chips, and table rows.
+
+Every function returns a string of an exact display width, so the caller can
+compose without re-measuring."""
+from __future__ import annotations
+
+from .text import (AMBER, BOLD, CHIP_BG, CHIP_TX, DIM, RESET, REV, BORDER,
+                   TAG, cell, disp_width, pad_ansi,
+                   strip_ansi, visible_len)
+
+
+# ------------------------------------------------------------------- geometry
+# One measure for the whole UI: header, list and command panels share edges.
+FRAME_MIN = 44
+
+FRAME_MAX = 66
+
+RAIL_W = 1
+
+PROJ_W = 14
+
+THEME_W = 14
+
+RAM_W = 7
+
+META_GAP = 2  # THEME → RAM
+
+TABLE_MIN = RAIL_W + PROJ_W + 1 + THEME_W + META_GAP + RAM_W  # 39
+
+CHIP_W = 5  # widest chip is " Esc "
+
+RAIL_OFF = "▏"  # hairline rail, distinct from the panel's own │ border
+
+RAIL_ON = "▊"  # selected project's rail lights up
+
+
+def frame_width(cols: int) -> int:
+    """Total width of the boxed UI, borders included."""
+    return max(FRAME_MIN, min(cols - 2, FRAME_MAX))
+
+
+def boxed(cols: int) -> bool:
+    return cols >= FRAME_MIN + 2
+
+
+def inner_width(cols: int) -> int:
+    """Content measure. Same column engine boxed or not, only borders differ."""
+    return frame_width(cols) - 4 if boxed(cols) else max(TABLE_MIN, cols - 1)
+
+# ---------------------------------------------------------------------- boxes
+TL, TR, BL, BR, HBAR, VBAR = "╭", "╮", "╰", "╯", "─", "│"
+
+
+def _edge(inner: int, left: str, right: str, title: str = "", tail: str = "") -> str:
+    """Rounded rule with optional inline title (left) and tail (right)."""
+    span = inner + 2
+    t = f" {title} " if title else ""
+    e = f" {tail} " if tail else ""
+    fill = span - 2 - visible_len(t) - visible_len(e)
+    if fill < 1 and e:
+        e = ""
+        fill = span - 2 - visible_len(t)
+    if fill < 1 and t:
+        t = cell(strip_ansi(title), max(1, span - 4))
+        t = f" {t} "
+        fill = max(0, span - 2 - visible_len(t))
+    bar = BORDER + HBAR + RESET
+    return (
+        f"{BORDER}{left}{RESET}{bar}{t}{BORDER}{HBAR * fill}{RESET}"
+        f"{e}{bar}{BORDER}{right}{RESET}"
+    )
+
+
+def box_top(inner: int, title: str = "", tail: str = "") -> str:
+    return _edge(inner, TL, TR, title, tail)
+
+
+def box_bot(inner: int, title: str = "", tail: str = "") -> str:
+    return _edge(inner, BL, BR, title, tail)
+
+
+def box_row(inner: int, content: str = "") -> str:
+    v = f"{BORDER}{VBAR}{RESET}"
+    return f"{v} {pad_ansi(content, inner)} {v}"
+
+# ------------------------------------------------------------- command panels
+
+
+def chip(key: str, width: int = CHIP_W) -> str:
+    """Key glyph on a solid chip so the eye lands on keys before labels."""
+    body = f" {key} "
+    pad = max(0, width - disp_width(body))
+    return f"{CHIP_BG}{CHIP_TX}{BOLD}{body}{RESET}" + " " * pad
+
+
+def cmd_cell(key: str, label: str, width: int) -> str:
+    # Labels may carry ANSI (dim counts), measure and pad in display columns.
+    return chip(key) + pad_ansi(label, max(0, width - CHIP_W))
+
+
+def longest_label(items: list[tuple], short: bool = False) -> int:
+    idx = 2 if short else 1
+    return max(visible_len(str(i[idx])) for i in items) if items else 0
+
+
+def panel(width: int, title: str, items: list[tuple], *, columns: int = 1,
+          short: bool = False, min_rows: int = 0) -> list[str]:
+    """A titled command panel exactly `width` display columns wide.
+
+    min_rows pads with empty rows so side-by-side panels close on the same
+    line, uneven bottom edges read as a layout bug, not as design.
+    """
+    inner = width - 4
+    idx = 2 if short else 1
+    lines = [box_top(inner, title=title)]
+    per = (inner - 2 * (columns - 1)) // columns
+    for i in range(0, len(items), columns):
+        chunk = items[i : i + columns]
+        cells = [cmd_cell(it[0], str(it[idx]), per) for it in chunk]
+        while len(cells) < columns:
+            cells.append(" " * per)
+        lines.append(box_row(inner, "  ".join(cells)))
+    while len(lines) - 1 < min_rows:
+        lines.append(box_row(inner, ""))
+    lines.append(box_bot(inner))
+    return lines
+
+
+def flat_panel(width: int, title: str, items: list[tuple], *,
+               short: bool = False) -> list[str]:
+    """Borderless panel for terminals too narrow to spend 2 columns on chrome."""
+    idx = 2 if short else 1
+    return [f" {title}"] + [
+        " " + cmd_cell(it[0], str(it[idx]), width - 1) for it in items
+    ]
+
+
+def fit_strip(bits: list[tuple[str, str]], width: int) -> str:
+    """Chip strip that sheds commands rather than getting cut mid-label.
+
+    Sheds from the back but keeps the last pair pinned, the tail is the way
+    out (`q quit`), and a strip that can't tell you how to leave is a trap.
+    """
+    items = list(bits)
+
+    def render(seq):
+        return " ".join(f"{chip(k, disp_width(k) + 2)} {lab}" for k, lab in seq)
+
+    while len(items) > 1:
+        if visible_len(render(items)) <= width:
+            return render(items)
+        items.pop(-2)
+    return render(items) if items and visible_len(render(items)) <= width else ""
+
+
+def side_by_side(left: list[str], lw: int, right: list[str], rw: int) -> list[str]:
+    """Two panels on one row; short one is padded so both bottoms line up."""
+    n = max(len(left), len(right))
+    out = []
+    for i in range(n):
+        a = left[i] if i < len(left) else " " * lw
+        b = right[i] if i < len(right) else " " * rw
+        out.append(f"{pad_ansi(a, lw)} {pad_ansi(b, rw)}")
+    return out
+
+# ------------------------------------------------------------------ list rows
+
+
+def project_row(name: str, theme: str, ram: str, inner: int, *,
+                rail: str, selected: bool) -> str:
+    """rail | PROJECT | THEME … RAM, identity clustered left, size anchored right."""
+    gutter = max(META_GAP, inner - TABLE_MIN + META_GAP)
+    p = cell(name, PROJ_W)
+    t = cell(theme, THEME_W)
+    r = cell(ram, RAM_W, align="right")
+    p_out = f"{REV}{p}{RESET}" if selected else p
+    return f"{rail}{p_out} {DIM}{t}{RESET}{' ' * gutter}{BOLD}{r}{RESET}"
+
+
+def session_row(rail: str, label: str, extra: str, ram: str, inner: int) -> str:
+    """Session lines get the full measure, long agent titles stay readable."""
+    label_w = inner - RAIL_W - META_GAP - RAM_W
+    tail = f" · {extra}" if extra else ""
+    # Truncate the label, never the "· orphaned" tag it's qualified by.
+    keep = max(1, min(disp_width(label), label_w - disp_width(tail)))
+    accent = TAG if extra == "orphaned" else DIM
+    body = f"{DIM}{cell(label, keep)}{RESET}{accent}{cell(tail, label_w - keep)}{RESET}"
+    r = cell(ram, RAM_W, align="right")
+    return f"{rail}{body}{' ' * META_GAP}{DIM}{r}{RESET}"