shikiru-cli 0.2.0__py3-none-any.whl

shikiru/tmux/decorator.py

@@ -0,0 +1,225 @@
+"""Pane and window decorations and titles."""
+
+from __future__ import annotations
+
+from string import Formatter
+from typing import TYPE_CHECKING
+
+from shikiru.errors import ConfigError
+from shikiru.palette import (
+    BACKGROUND_COLOR,
+    PRIMARY_TEXT_COLOR,
+    SECONDARY_TEXT_COLOR,
+    SELECTED_SURFACE_COLOR,
+)
+from shikiru.tmux.client import (
+    pane_option_commands,
+    pane_title_command,
+    rename_window_command,
+    window_option_commands,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from shikiru.tmux.client import Tmux
+
+PANE_COLOR_OPTION = "@shk_color"
+PANE_GLYPH_OPTION = "@shk_glyph"
+WINDOW_STATE_COLOR_OPTION = "@shk_state_color"
+WINDOW_STATE_GLYPH_OPTION = "@shk_state_glyph"
+PANE_TITLE_FORMAT_OPTION = "@shk_title_format"
+
+PANE_BORDER_FORMAT = (
+    f"#[fg={PRIMARY_TEXT_COLOR},bg={BACKGROUND_COLOR}] "
+    f"#{{?{PANE_TITLE_FORMAT_OPTION},#{{{PANE_TITLE_FORMAT_OPTION}}},#{{pane_title}}}}"
+    f" #[fg={PRIMARY_TEXT_COLOR},bg={BACKGROUND_COLOR}]"
+)
+WINDOW_STATUS_FORMAT = (
+    f"#[default]#[fg=#{{{WINDOW_STATE_COLOR_OPTION}}},bg={BACKGROUND_COLOR}] "
+    f"#{{{WINDOW_STATE_GLYPH_OPTION}}} "
+    f"#[fg={SECONDARY_TEXT_COLOR},bg={BACKGROUND_COLOR}]#{{window_index}}:"
+    f"#[fg={PRIMARY_TEXT_COLOR},bg={BACKGROUND_COLOR}]#{{window_name}}"
+    f"#[default]#[fg={PRIMARY_TEXT_COLOR},bg={BACKGROUND_COLOR}]"
+)
+WINDOW_STATUS_CURRENT_FORMAT = (
+    f"#[fg={PRIMARY_TEXT_COLOR},bg={SELECTED_SURFACE_COLOR},bold]["
+    f"#[fg=#{{{WINDOW_STATE_COLOR_OPTION}}},bg={SELECTED_SURFACE_COLOR}]"
+    f"#{{{WINDOW_STATE_GLYPH_OPTION}}} "
+    f"#[fg={SECONDARY_TEXT_COLOR},bg={SELECTED_SURFACE_COLOR}]#{{window_index}}:"
+    f"#[fg={PRIMARY_TEXT_COLOR},bg={SELECTED_SURFACE_COLOR}]#{{window_name}}"
+    f" #[fg={PRIMARY_TEXT_COLOR},bg={SELECTED_SURFACE_COLOR},bold]]"
+    f"#[default]#[fg={PRIMARY_TEXT_COLOR},bg={BACKGROUND_COLOR}]"
+)
+HOME_WINDOW_STATUS_FORMAT = (
+    f"#[default]#[fg={PRIMARY_TEXT_COLOR},bg={BACKGROUND_COLOR}]#{{window_index}}:"
+    f"#{{window_name}}#[default]#[fg={PRIMARY_TEXT_COLOR},bg={BACKGROUND_COLOR}]"
+)
+HOME_WINDOW_STATUS_CURRENT_FORMAT = (
+    f"#[fg={PRIMARY_TEXT_COLOR},bg={SELECTED_SURFACE_COLOR},bold]["
+    f"#{{window_index}}:#{{window_name}}]"
+    f"#[default]#[fg={PRIMARY_TEXT_COLOR},bg={BACKGROUND_COLOR}]"
+)
+
+_PANE_BORDER_FORMAT_OPTION = "pane-border-format"
+_WINDOW_STATUS_FORMAT_OPTION = "window-status-format"
+_WINDOW_STATUS_CURRENT_FORMAT_OPTION = "window-status-current-format"
+_TMUX_FORMAT_HASH = "#"
+_TMUX_FORMAT_ESCAPED_HASH = "##"
+
+
+def render_title(template: str, fields: Mapping[str, object]) -> str:
+    """Render a `dashboard.titles` template, failing loudly on any field it can't fill."""
+    try:
+        return template.format(**fields)
+    except KeyError as error:
+        message = f"title template {template!r} references unknown field {error.args[0]!r}"
+        raise ConfigError(message) from error
+
+
+def _render_styled_title(
+    template: str,
+    fields: Mapping[str, object],
+    field_colors: Mapping[str, str],
+    field_segments: Mapping[str, tuple[tuple[str, str], ...]],
+) -> str:
+    render_title(template, fields)
+    formatter = Formatter()
+    output: list[str] = [f"#[fg={PRIMARY_TEXT_COLOR},bg={BACKGROUND_COLOR}]"]
+    literal_parts: list[str] = []
+    for literal, field_name, format_spec, conversion in formatter.parse(template):
+        literal_parts.append(literal)
+        if field_name is None:
+            continue
+        if literal_parts:
+            output.extend(
+                (
+                    f"#[fg={PRIMARY_TEXT_COLOR},bg={BACKGROUND_COLOR}]",
+                    _escape_tmux_format("".join(literal_parts)),
+                )
+            )
+            literal_parts.clear()
+        value, _ = formatter.get_field(field_name, (), fields)
+        if conversion is not None:
+            value = formatter.convert_field(value, conversion)
+        resolved_spec = ""
+        if format_spec is not None:
+            resolved_spec = formatter.vformat(format_spec, (), fields)
+        rendered = formatter.format_field(value, resolved_spec)
+        segments = field_segments.get(field_name)
+        if segments is not None and "".join(text for text, _ in segments) == rendered:
+            for segment_text, color in segments:
+                output.extend(
+                    (
+                        f"#[fg={color},bg={BACKGROUND_COLOR}]",
+                        _escape_tmux_format(segment_text),
+                    )
+                )
+        else:
+            color = field_colors.get(field_name, PRIMARY_TEXT_COLOR)
+            output.extend((f"#[fg={color},bg={BACKGROUND_COLOR}]", _escape_tmux_format(rendered)))
+    if literal_parts:
+        output.extend(
+            (
+                f"#[fg={PRIMARY_TEXT_COLOR},bg={BACKGROUND_COLOR}]",
+                _escape_tmux_format("".join(literal_parts)),
+            )
+        )
+    output.append(f"#[fg={PRIMARY_TEXT_COLOR},bg={BACKGROUND_COLOR}]")
+    return "".join(output)
+
+
+def _escape_tmux_format(text: str) -> str:
+    return text.replace(_TMUX_FORMAT_HASH, _TMUX_FORMAT_ESCAPED_HASH)
+
+
+class PaneDecorator:
+    """Sets the `@shk_*` decorations, their formats, and renders pane and window titles."""
+
+    def __init__(self, tmux: Tmux) -> None:
+        """Decorate through `tmux`."""
+        self._tmux = tmux
+
+    async def configure_formats(self, window_target: str) -> None:
+        """Set the border and window-status formats that read the `@shk_*` options."""
+        await self._tmux.batch(
+            window_option_commands(
+                window_target,
+                {
+                    _PANE_BORDER_FORMAT_OPTION: PANE_BORDER_FORMAT,
+                    _WINDOW_STATUS_FORMAT_OPTION: WINDOW_STATUS_FORMAT,
+                    _WINDOW_STATUS_CURRENT_FORMAT_OPTION: WINDOW_STATUS_CURRENT_FORMAT,
+                },
+            )
+        )
+
+    async def set_pane_title_styling(
+        self,
+        pane_target: str,
+        template: str,
+        fields: Mapping[str, object],
+        *,
+        field_colors: Mapping[str, str],
+        field_segments: Mapping[str, tuple[tuple[str, str], ...]],
+    ) -> None:
+        """Set pane `pane_target`'s title and its styled border row in one tmux call."""
+        await self._set_pane_title(
+            pane_target,
+            template,
+            fields,
+            field_colors=field_colors,
+            field_segments=field_segments,
+        )
+
+    async def set_pane_state(self, pane_target: str, *, color: str, glyph: str) -> None:
+        """Set pane `pane_target`'s `@shk_color` and `@shk_glyph`."""
+        await self._tmux.batch(
+            pane_option_commands(pane_target, {PANE_COLOR_OPTION: color, PANE_GLYPH_OPTION: glyph})
+        )
+
+    async def refresh_window(
+        self,
+        window_target: str,
+        template: str,
+        fields: Mapping[str, object],
+        *,
+        color: str,
+        glyph: str,
+    ) -> None:
+        """Set window `window_target`'s state and rename it to `template` rendered with `fields`."""
+        title = render_title(template, fields)
+        await self._tmux.batch(
+            [
+                rename_window_command(window_target, title),
+                *window_option_commands(
+                    window_target,
+                    {WINDOW_STATE_COLOR_OPTION: color, WINDOW_STATE_GLYPH_OPTION: glyph},
+                ),
+            ]
+        )
+
+    async def set_pane_title(
+        self, pane_target: str, template: str, fields: Mapping[str, object]
+    ) -> None:
+        """Render `template` with `fields` and set it as pane `pane_target`'s title."""
+        await self._set_pane_title(
+            pane_target, template, fields, field_colors={}, field_segments={}
+        )
+
+    async def _set_pane_title(
+        self,
+        pane_target: str,
+        template: str,
+        fields: Mapping[str, object],
+        *,
+        field_colors: Mapping[str, str],
+        field_segments: Mapping[str, tuple[tuple[str, str], ...]],
+    ) -> None:
+        title = render_title(template, fields)
+        title_format = _render_styled_title(template, fields, field_colors, field_segments)
+        await self._tmux.batch(
+            [
+                pane_title_command(pane_target, title),
+                *pane_option_commands(pane_target, {PANE_TITLE_FORMAT_OPTION: title_format}),
+            ]
+        )

shikiru/tmux/layout.py

@@ -0,0 +1,200 @@
+"""Builds a task window's panes from `dashboard.layout`."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from shikiru.config.settings import LayoutSplit, PaneLeaf
+from shikiru.errors import ConfigError
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from pathlib import Path
+
+    from shikiru.config.settings import LayoutNode, LayoutSplit
+    from shikiru.tmux.client import Tmux
+
+_FULL_PERCENT = 100
+_RESTORE_SPLIT_PERCENT = 50
+_VERTICAL_STACK_LAYOUT = "even-vertical"
+_VERTICAL_AXIS = "v"
+_MIN_STACK_PANES = 2
+
+
+class LayoutBuilder:
+    """Splits a window's base pane into the tree `dashboard.layout` describes."""
+
+    def __init__(self, tmux: Tmux) -> None:
+        """Split panes through `tmux`."""
+        self._tmux = tmux
+
+    async def build(
+        self, base_pane_id: str, root: LayoutNode, *, cwd: Path | None = None
+    ) -> dict[str, str]:
+        """Build `root` starting from `base_pane_id`, returning `{pane name: pane id}`.
+
+        Raises `ConfigError` if two leaves share a pane name.
+        """
+        panes: dict[str, str] = {}
+        await self._place(base_pane_id, root, panes, cwd)
+        return panes
+
+    async def restore_missing(
+        self,
+        root: LayoutNode,
+        existing: Mapping[str, str],
+        *,
+        cwd: Path,
+    ) -> dict[str, str]:
+        """Restore absent layout leaves beside surviving leaves and return their pane ids."""
+        panes = dict(existing)
+        await self._restore_node(root, panes, cwd)
+        return panes
+
+    async def restore_vertical_stack(
+        self, window_id: str, root: LayoutSplit, panes: Mapping[str, str]
+    ) -> None:
+        """Reapply configured sizes to a direct vertical leaf stack without replacing panes."""
+        if root.split != _VERTICAL_AXIS or not all(
+            isinstance(child, PaneLeaf) for child in root.panes
+        ):
+            return
+        leaves = [child for child in root.panes if isinstance(child, PaneLeaf)]
+        if len(leaves) < _MIN_STACK_PANES:
+            return
+        await self._tmux.select_layout(window_id, _VERTICAL_STACK_LAYOUT)
+        fractions = _resolve_fractions([leaf.size for leaf in leaves])
+        available_height = sum(
+            [int(await self._tmux.display(panes[leaf.pane], "#{pane_height}")) for leaf in leaves]
+        )
+        heights = _allocate_heights(fractions, available_height)
+        for leaf, height in zip(leaves[:-1], heights[:-1], strict=True):
+            await self._tmux.resize_pane_height(panes[leaf.pane], height)
+
+    async def _restore_node(self, node: LayoutNode, panes: dict[str, str], cwd: Path) -> None:
+        if isinstance(node, PaneLeaf):
+            return
+        for index, child in enumerate(node.panes):
+            names = _leaf_names(child)
+            if names.issubset(panes):
+                if not isinstance(child, PaneLeaf):
+                    await self._restore_node(child, panes, cwd)
+                continue
+            if names.intersection(panes):
+                await self._restore_node(child, panes, cwd)
+                continue
+            target, before = _neighbor_pane(node.panes, index, panes)
+            if target is None:
+                message = "dashboard.layout cannot restore panes without a surviving neighbor"
+                raise ConfigError(message)
+            base_pane = await self._tmux.split_window(
+                target,
+                axis=node.split,
+                size_pct=_RESTORE_SPLIT_PERCENT,
+                cwd=cwd,
+                detached=True,
+                before=before,
+            )
+            await self._place(base_pane, child, panes, cwd)
+
+    async def _place(
+        self, pane_id: str, node: LayoutNode, panes: dict[str, str], cwd: Path | None
+    ) -> None:
+        if isinstance(node, PaneLeaf):
+            if node.pane in panes:
+                message = f"dashboard.layout has more than one pane named {node.pane!r}"
+                raise ConfigError(message)
+            panes[node.pane] = pane_id
+            return
+        await self._place_split(pane_id, node, panes, cwd)
+
+    async def _place_split(
+        self, pane_id: str, node: LayoutSplit, panes: dict[str, str], cwd: Path | None
+    ) -> None:
+        sizes = [child.size if isinstance(child, PaneLeaf) else None for child in node.panes]
+        fractions = _resolve_fractions(sizes)
+        remaining_fraction = 1.0
+        current_pane_id = pane_id
+        for child, fraction in zip(node.panes[:-1], fractions[:-1], strict=True):
+            rest_fraction = remaining_fraction - fraction
+            rest_pct = round(rest_fraction / remaining_fraction * _FULL_PERCENT)
+            rest_pane_id = await self._tmux.split_window(
+                current_pane_id,
+                axis=node.split,
+                size_pct=rest_pct,
+                cwd=cwd,
+                detached=True,
+            )
+            await self._place(current_pane_id, child, panes, cwd)
+            current_pane_id = rest_pane_id
+            remaining_fraction = rest_fraction
+        await self._place(current_pane_id, node.panes[-1], panes, cwd)
+
+
+def _leaf_names(node: LayoutNode) -> set[str]:
+    if isinstance(node, PaneLeaf):
+        return {node.pane}
+    names: set[str] = set()
+    for child in node.panes:
+        names.update(_leaf_names(child))
+    return names
+
+
+def _neighbor_pane(
+    siblings: list[LayoutNode], index: int, panes: Mapping[str, str]
+) -> tuple[str | None, bool]:
+    for sibling in reversed(siblings[:index]):
+        names = _leaf_names(sibling).intersection(panes)
+        if names:
+            return panes[_last_leaf_name(sibling, names)], False
+    for sibling in siblings[index + 1 :]:
+        names = _leaf_names(sibling).intersection(panes)
+        if names:
+            return panes[_first_leaf_name(sibling, names)], True
+    return None, False
+
+
+def _first_leaf_name(node: LayoutNode, existing: set[str]) -> str:
+    if isinstance(node, PaneLeaf):
+        return node.pane
+    for child in node.panes:
+        names = _leaf_names(child).intersection(existing)
+        if names:
+            return _first_leaf_name(child, names)
+    message = "dashboard.layout has no first surviving pane"
+    raise ConfigError(message)
+
+
+def _last_leaf_name(node: LayoutNode, existing: set[str]) -> str:
+    if isinstance(node, PaneLeaf):
+        return node.pane
+    for child in reversed(node.panes):
+        names = _leaf_names(child).intersection(existing)
+        if names:
+            return _last_leaf_name(child, names)
+    message = "dashboard.layout has no last surviving pane"
+    raise ConfigError(message)
+
+
+def _resolve_fractions(sizes: list[int | None]) -> list[float]:
+    explicit_total = sum(size for size in sizes if size is not None)
+    if explicit_total > _FULL_PERCENT:
+        message = f"dashboard.layout pane sizes add up to more than 100% ({explicit_total}%)"
+        raise ConfigError(message)
+    unsized_count = sizes.count(None)
+    share = (_FULL_PERCENT - explicit_total) / unsized_count if unsized_count else 0.0
+    return [(size if size is not None else share) / _FULL_PERCENT for size in sizes]
+
+
+def _allocate_heights(fractions: list[float], total_height: int) -> list[int]:
+    exact_heights = [fraction * total_height for fraction in fractions]
+    heights = [int(height) for height in exact_heights]
+    remaining = total_height - sum(heights)
+    remainders = sorted(
+        range(len(heights)),
+        key=lambda index: exact_heights[index] - heights[index],
+        reverse=True,
+    )
+    for index in remainders[:remaining]:
+        heights[index] += 1
+    return heights