railmux 0.4.0.dev34__tar.gz → 0.4.0.dev36__tar.gz

{railmux-0.4.0.dev34/src/railmux.egg-info → railmux-0.4.0.dev36}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: railmux
-Version: 0.4.0.dev34
+Version: 0.4.0.dev36
 Summary: Terminal UI to navigate, resume, and start Claude Code and Codex sessions
 Author-email: Rightglow <zhang.taian@foxmail.com>
 License-Expression: MIT

railmux-0.4.0.dev36/src/railmux/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.4.0.dev36"

railmux-0.4.0.dev36/src/railmux/project_favorites.py

@@ -0,0 +1,79 @@
+"""Persistent favorite project tracking.
+
+Project favorites are deliberately separate from session favorites.  A
+project is identified by the absolute path Railmux already discovered, while
+session favorites are provider UUIDs and retain their released JSON schema.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from railmux.atomic_file import atomic_write_text
+
+
+_MAX_FAVORITES = 10_000
+_MAX_PATH_LENGTH = 4096
+
+
+def _project_favorites_path() -> Path:
+    return Path.home() / ".config" / "railmux" / "project-favorites.json"
+
+
+def _path_key(path: Path) -> str:
+    """Return the stable absolute spelling used by project discovery."""
+    return str(path if path.is_absolute() else path.absolute())
+
+
+class ProjectFavorites:
+    """In-memory set of favorite absolute project paths, backed by JSON."""
+
+    def __init__(self) -> None:
+        self._paths: set[str] = set()
+        self._path = _project_favorites_path()
+        self._load()
+
+    def _load(self) -> None:
+        if not self._path.is_file():
+            return
+        try:
+            data = json.loads(self._path.read_text(encoding="utf-8"))
+            if (
+                not isinstance(data, list)
+                or len(data) > _MAX_FAVORITES
+                or any(
+                    not isinstance(value, str)
+                    or not value
+                    or "\x00" in value
+                    or len(value) > _MAX_PATH_LENGTH
+                    or not Path(value).is_absolute()
+                    for value in data
+                )
+            ):
+                return
+            self._paths = set(data)
+        except (json.JSONDecodeError, OSError, UnicodeError):
+            self._paths = set()
+
+    def _save(self) -> None:
+        try:
+            atomic_write_text(
+                self._path,
+                json.dumps(sorted(self._paths), ensure_ascii=False, indent=2),
+            )
+        except OSError:
+            pass
+
+    def is_favorite(self, path: Path) -> bool:
+        return _path_key(path) in self._paths
+
+    def set(self, path: Path, favorite: bool) -> None:
+        key = _path_key(path)
+        updated = self._paths | {key} if favorite else self._paths - {key}
+        if updated == self._paths:
+            return
+        self._paths = updated
+        self._save()
+
+    def get_paths(self) -> set[Path]:
+        return {Path(value) for value in self._paths}

{railmux-0.4.0.dev34 → railmux-0.4.0.dev36}/src/railmux/provider_paths.py

@@ -9,13 +9,15 @@ import sys
 from collections.abc import Mapping
 from pathlib import Path
 
+from railmux.release_version import PROJECT_VERSION_PATTERN
+
 
 _DRIVE_PATH = re.compile(r"^(?:\\\\\?\\)?([A-Za-z]):[\\/](.*)\Z")
 _MANAGED_BASE_MARKER = Path("/railmux-base.json")
 _MANAGED_BASE_CONTENT_MARKER = Path("/railmux-base-content-v1.json")
 _MANAGED_APP_ROOT = Path("/opt/railmux/apps")
 _MANAGED_APP_ID = re.compile(
-    r"railmux-[0-9]+(?:\.[0-9]+)*(?:\.dev[0-9]+)?\Z"
+    rf"railmux-{PROJECT_VERSION_PATTERN}\Z"
 )
 
 

railmux-0.4.0.dev36/src/railmux/release_version.py

@@ -0,0 +1,111 @@
+"""Narrow version grammar shared by managed Windows app-layer identities."""
+from __future__ import annotations
+
+import re
+from functools import total_ordering
+from typing import Any
+
+
+class InvalidVersion(ValueError):
+    """A version is outside Railmux's canonical persisted grammar."""
+
+
+@total_ordering
+class ProjectVersion:
+    """Small standard-library ordering type for native bootstrap identities."""
+
+    __slots__ = ("_key", "_value")
+
+    def __init__(
+        self,
+        value: str,
+        release: tuple[int, ...],
+        stage: int,
+        stage_number: int,
+    ) -> None:
+        normalized = release
+        while len(normalized) > 1 and normalized[-1] == 0:
+            normalized = normalized[:-1]
+        self._value = value
+        self._key = (normalized, stage, stage_number)
+
+    def __str__(self) -> str:
+        return self._value
+
+    def __repr__(self) -> str:
+        return f"ProjectVersion({self._value!r})"
+
+    def __hash__(self) -> int:
+        return hash(self._key)
+
+    def __eq__(self, other: Any) -> bool:
+        if not isinstance(other, ProjectVersion):
+            return NotImplemented
+        return self._key == other._key
+
+    def __lt__(self, other: Any) -> bool:
+        if not isinstance(other, ProjectVersion):
+            return NotImplemented
+        return self._key < other._key
+
+
+# Railmux app directories are security-sensitive persisted identities.  Accept
+# only the spellings that this project publishes: a final, an RC, or a
+# development release.  PEP 440 aliases, epochs, post releases, and local
+# versions are deliberately excluded so equal versions have one path spelling.
+_CANONICAL_INTEGER_PATTERN = r"(?:0|[1-9][0-9]*)"
+PROJECT_VERSION_PATTERN = (
+    rf"{_CANONICAL_INTEGER_PATTERN}"
+    rf"(?:\.{_CANONICAL_INTEGER_PATTERN})*"
+    rf"(?:rc{_CANONICAL_INTEGER_PATTERN}|\.dev{_CANONICAL_INTEGER_PATTERN})?"
+)
+PROJECT_VERSION_RE = re.compile(PROJECT_VERSION_PATTERN + r"\Z")
+_PROJECT_VERSION_PARTS_RE = re.compile(
+    rf"(?P<release>{_CANONICAL_INTEGER_PATTERN}"
+    rf"(?:\.{_CANONICAL_INTEGER_PATTERN})*)"
+    rf"(?:(?:rc(?P<rc>{_CANONICAL_INTEGER_PATTERN}))|"
+    rf"(?:\.dev(?P<dev>{_CANONICAL_INTEGER_PATTERN})))?\Z"
+)
+
+
+def parse_project_version(value: str) -> ProjectVersion:
+    """Return the canonical supported Railmux version or raise InvalidVersion."""
+    match = _PROJECT_VERSION_PARTS_RE.fullmatch(value)
+    if match is None:
+        raise InvalidVersion(value)
+    release_parts = match.group("release").split(".")
+    stage_text = match.group("rc") or match.group("dev")
+    numeric_parts = release_parts + ([stage_text] if stage_text else [])
+    if any(
+        len(part) > 1 and part.startswith("0")
+        for part in numeric_parts
+    ):
+        raise InvalidVersion(
+            f"non-canonical Railmux version spelling: {value!r}"
+        )
+    if match.group("dev") is not None:
+        stage = 0
+        stage_number = int(match.group("dev"))
+    elif match.group("rc") is not None:
+        stage = 1
+        stage_number = int(match.group("rc"))
+    else:
+        stage = 2
+        stage_number = 0
+    return ProjectVersion(
+        value,
+        tuple(int(part) for part in release_parts),
+        stage,
+        stage_number,
+    )
+
+
+def is_project_version(value: object) -> bool:
+    """Return whether *value* is one canonical published-version spelling."""
+    if not isinstance(value, str):
+        return False
+    try:
+        parse_project_version(value)
+    except InvalidVersion:
+        return False
+    return True

{railmux-0.4.0.dev34 → railmux-0.4.0.dev36}/src/railmux/ui/app.py

@@ -37,6 +37,7 @@ from railmux.display_transport import (
 )
 from railmux.discovery import invalidate_session, list_projects
 from railmux.favorites import Favorites
+from railmux.project_favorites import ProjectFavorites
 from railmux.fast_display_input import is_termux_environment
 from railmux.help_workspace import (
     is_help_workspace,
@@ -813,6 +814,7 @@ class App:
         self._renames = Renames()
         self._session_cache = SessionCache(self._renames)
         self._favorites = Favorites()
+        self._project_favorites = ProjectFavorites()
         self._settings = Settings()
         self._layout_profile = self._settings.layout_profile
         self._active_sidebar_permille = (
@@ -1002,7 +1004,9 @@ class App:
             projects,
             on_select=self._on_project_select,
             on_double_click=self._on_project_double_click,
+            on_context=self._open_project_context_menu,
             provider_label=initial_mode.label,
+            favorite_paths=self._project_favorites.get_paths(),
             boxed=False,
         )
         self._sessions_pane = SessionsPane(
@@ -1218,6 +1222,19 @@ class App:
         pane_id = slot.pane_id
         if pane_id is None or not pane_id.startswith("%"):
             return
+        marker = self._transcript_source_marker(session_id, tmux_name)
+        tmux_ctl.set_pane_user_option(
+            pane_id,
+            tmux_server.TRANSCRIPT_SOURCE_OPTION,
+            marker,
+        )
+
+    def _transcript_source_marker(
+        self,
+        session_id: str | None,
+        tmux_name: str | None,
+    ) -> str | None:
+        """Build the bounded read-only Preview locator for one live target."""
         marker = None
         running = self._by_tmux(tmux_name) if tmux_name else None
         logical_id = (
@@ -1248,11 +1265,78 @@ class App:
                     representative.session_id,
                     representative.jsonl_path,
                 )
-        tmux_ctl.set_pane_user_option(
-            pane_id,
-            tmux_server.TRANSCRIPT_SOURCE_OPTION,
-            marker,
+        return marker
+
+    def _sync_attached_slot_projection(
+        self,
+        slot: AgentSlot,
+        tmux_name: str,
+    ) -> None:
+        """Publish non-authoritative pane projections with one tmux client.
+
+        The display transport has already verified and committed the pane
+        ownership transaction.  These options advertise the explicit Preview
+        source and the prefix-Tab Target; neither grants authority to move,
+        resume, or kill a provider.  Batching them removes one deterministic
+        MSYS2 process startup while retaining the established helpers as a
+        fail-safe fallback.
+        """
+        pane_id = slot.pane_id
+        if (
+            pane_id is None
+            or not pane_id.startswith("%")
+            or tmux_ctl.tmux_version() < (3, 0)
+        ):
+            self._sync_slot_transcript_source(
+                slot,
+                self._session_id_for_tmux_target(tmux_name),
+                tmux_name,
+            )
+            return
+
+        session_id = self._session_id_for_tmux_target(tmux_name)
+        marker = self._transcript_source_marker(session_id, tmux_name)
+        if marker is None:
+            transcript_command = (
+                "set-option", "-p", "-t", pane_id,
+                "-u", tmux_server.TRANSCRIPT_SOURCE_OPTION,
+            )
+        else:
+            transcript_command = (
+                "set-option", "-p", "-t", pane_id,
+                tmux_server.TRANSCRIPT_SOURCE_OPTION, marker,
+            )
+        commands: list[tuple[str, ...]] = [transcript_command]
+
+        manager = getattr(self, "_tmux_binding_manager", None)
+        owner = getattr(self, "_railmux_pane_id", None)
+        desired_target: str | None = None
+        if (
+            slot.key == self._agent_workspace().target_slot_key
+            and owner is not None
+            and getattr(manager, "target_toggle_available", False)
+        ):
+            desired_target = pane_id
+            commands.append((
+                "set-window-option", "-t", owner,
+                tmux_ctl.RAILMUX_TARGET_OPTION, desired_target,
+            ))
+
+        if tmux_ctl.run_command_queue(tuple(commands)):
+            if desired_target is not None:
+                self._projected_target_pane_id = desired_target
+            return
+
+        # A presentation-only batch failure must not turn a verified attach
+        # into a provider/session failure. Retry each released helper so one
+        # unsupported option cannot suppress the other projection.
+        self._sync_slot_transcript_source(
+            slot,
+            session_id,
+            tmux_name,
         )
+        if desired_target is not None:
+            self._sync_target_pane_option()
 
     def _paint_slot_active_target(
         self,
@@ -1312,13 +1396,18 @@ class App:
         )
 
     def _set_active_tmux_target(
-        self, tmux_name: str, slot: AgentSlot | None = None,
+        self,
+        tmux_name: str,
+        slot: AgentSlot | None = None,
+        *,
+        sync_transcript_source: bool = True,
     ) -> None:
         slot = slot or self._primary_slot
         self._set_slot_active_target(
             slot,
             self._session_id_for_tmux_target(tmux_name),
             tmux_name,
+            sync_transcript_source=sync_transcript_source,
         )
 
     def _sync_border_indicators(self, arrows: bool) -> bool:
@@ -1381,8 +1470,13 @@ class App:
         """
         workspace = self._agent_workspace()
         layout = workspace.layout
-        target_pane = None if active else workspace.target.pane_id
-        state = (active, layout, target_pane)
+        # Border formats depend on focus, layout, and the logical Target slot,
+        # not on the physical pane ID currently swapped into that slot.  Using
+        # the pane ID here rewrote identical gray borders after every
+        # live-session switch, which is especially visible on MSYS2 where each
+        # tmux client startup is comparatively expensive.
+        target_slot = None if active else workspace.target.key
+        state = (active, layout, target_slot)
         if not force and self._divider_active == state:
             return
         gray = "fg=colour240"
@@ -1416,7 +1510,7 @@ class App:
         desired_state = (
             active,
             workspace.layout,
-            None if active else workspace.target.pane_id,
+            None if active else workspace.target.key,
         )
         state = getattr(self, "_divider_active", None)
         if state != desired_state:
@@ -1437,7 +1531,7 @@ class App:
         if now - getattr(self, "_last_border_verify_at", 0.0) < 2.0:
             return
         self._last_border_verify_at = now
-        active, layout, _target_pane = state
+        active, layout, _target_slot = state
         gray = "fg=colour240"
         green = f"fg={_GRASS_GREEN}"
         if not active:
@@ -2477,7 +2571,13 @@ class App:
         slot.agent_tmux_name = agent_tmux_name
         mode = self._modes().for_tmux_name(agent_tmux_name)
         slot.mode_key = mode.key if mode is not None else None
-        self._set_active_tmux_target(agent_tmux_name, slot)
+        self._set_active_tmux_target(
+            agent_tmux_name,
+            slot,
+            sync_transcript_source=not outcome.display_stable,
+        )
+        if outcome.display_stable and not outcome.target_unchanged:
+            self._sync_attached_slot_projection(slot, agent_tmux_name)
         self._set_railmux_focus(
             not steal_focus and not self._double_focus_visual_pending,
             force_border=not outcome.display_stable,
@@ -2556,10 +2656,20 @@ class App:
         if worker is not None and worker.is_alive():
             return
         manager = getattr(self, "_tmux_binding_manager", None)
+        target_was_available = bool(
+            manager is not None and manager.target_toggle_available)
         opened = manager is not None and manager.open()
-        self._finish_tmux_bindings(opened)
+        self._finish_tmux_bindings(
+            opened,
+            force_target=not target_was_available,
+        )
 
-    def _finish_tmux_bindings(self, opened: bool) -> None:
+    def _finish_tmux_bindings(
+        self,
+        opened: bool,
+        *,
+        force_target: bool = True,
+    ) -> None:
         """Project pane-local state after the shared lease is prepared."""
         manager = getattr(self, "_tmux_binding_manager", None)
         selection = getattr(self, "_selection_isolation_manager", None)
@@ -2571,7 +2681,7 @@ class App:
             )
         if opened:
             if manager.target_toggle_available:
-                self._sync_target_pane_option(force=True)
+                self._sync_target_pane_option(force=force_target)
             elif not getattr(self, "_target_toggle_warning_shown", False):
                 self._target_toggle_warning_shown = True
                 self._set_status(
@@ -7887,6 +7997,7 @@ class App:
     def _close_modal(self) -> None:
         if self._loop is not None:
             self._loop.widget = self._frame
+        self._projects_pane.set_context_selected(None)
         self._sessions_pane.set_selected_session(None)
         self._running_pane.set_selected(None)
 
@@ -10458,6 +10569,61 @@ class App:
 
     # --- context menu (right-click) ---
 
+    def _open_project_context_menu(self, project: Project) -> None:
+        """Open actions for the exact Projects row that was right-clicked."""
+        if self._railmux_pane_id:
+            tmux_ctl.select_pane(self._railmux_pane_id)
+        self._projects_pane.set_context_selected(project.encoded_name)
+        is_starred = self._project_favorites.is_favorite(project.real_path)
+        items: list[tuple[str, Callable[[], None]]] = [
+            (_context_menu_label("Copy path", "c"),
+             lambda p=project: self._copy_project_path(p)),
+            (_context_menu_label("Unstar" if is_starred else "Star", "s"),
+             lambda p=project: self._do_context_project_star(p)),
+            (_context_menu_label("Info", "i"),
+             lambda p=project: self._do_context_project_info(p)),
+            (_context_menu_label("Term", "t"),
+             lambda p=project: self._open_terminal_for_project(p)),
+        ]
+        menu = ContextMenu(items, on_close=self._close_modal)
+        self._show_overlay(
+            menu,
+            width=36,
+            height=10,
+            click_outside_to_close=True,
+            fixed_width=True,
+            fixed_height=True,
+        )
+
+    def _copy_project_path(self, project: Project) -> None:
+        path = project.real_path
+        absolute = path if path.is_absolute() else path.absolute()
+        text = str(absolute)
+        if tmux_ctl.copy_to_clipboard(text):
+            self._set_status(f"Copied path: {text}", "success")
+        else:
+            self._set_status(
+                "Could not copy path; terminal clipboard is unavailable",
+                "warn",
+            )
+
+    def _do_context_project_star(self, project: Project) -> None:
+        now_star = not self._project_favorites.is_favorite(project.real_path)
+        self._project_favorites.set(project.real_path, now_star)
+        self._projects_pane.set_favorite_paths(
+            self._project_favorites.get_paths())
+        label = "★" if now_star else "unstarred"
+        self._set_status(f"{label} {project.display_name}")
+
+    def _do_context_project_info(self, project: Project) -> None:
+        modal = ProjectInfoModal(project=project, on_close=self._close_modal)
+        self._show_overlay(
+            modal,
+            width=60,
+            height=40,
+            click_outside_to_close=True,
+        )
+
     def _on_running_context_menu(self, entry: RunningEntry) -> None:
         r = self._by_tmux(entry.tmux_name)
         if r is None:

{railmux-0.4.0.dev34 → railmux-0.4.0.dev36}/src/railmux/ui/projects_pane.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 from collections.abc import Callable
+from pathlib import Path
 
 from railmux.fuzzy import fuzzy_match
 
@@ -18,21 +19,24 @@ from railmux.ui._widgets import (
 
 class _ProjectRow(ClickableRow):
     def __init__(self, project: Project, selected: bool = False,
+                 is_favorite: bool = False,
                  on_click: "Callable[[], None] | None" = None,
-                 on_double_click: "Callable[[], None] | None" = None) -> None:
+                 on_double_click: "Callable[[], None] | None" = None,
+                 on_right_click: "Callable[[], None] | None" = None) -> None:
         self.project = project
         # Keep the count in a fixed right-hand column.  An inline ``[12]``
         # makes project names jitter as counts change and becomes difficult to
         # scan once names have different lengths.
         count = str(project.session_count)
+        marker = "★ " if is_favorite else ""
         label = urwid.Columns([
-            urwid.Text(f"  {project.display_name}", wrap="ellipsis"),
+            urwid.Text(f"  {marker}{project.display_name}", wrap="ellipsis"),
             ("fixed", max(3, len(count) + 1),
              urwid.Text(f"{count} ", align="right", wrap="clip")),
         ], dividechars=0)
         attr = "selected" if selected else None
         super().__init__(urwid.AttrMap(label, attr, focus_map="focus"),
-                         on_click, on_double_click,
+                         on_click, on_double_click, on_right_click,
                          click_key=project.encoded_name,
                          immediate_click=True)
 
@@ -65,15 +69,20 @@ class ProjectsPane(ScrollableSidebarPane, urwid.WidgetWrap):
                  on_select: Callable[[Project | None], None],
                  on_double_click: Callable[[Project | None], None] | None = None,
                  provider_label: str = "Agent",
-                 *, boxed: bool = True) -> None:
+                 *, on_context: Callable[[Project], None] | None = None,
+                 favorite_paths: set[Path] | None = None,
+                 boxed: bool = True) -> None:
         self._all_projects = projects
         self._on_select = on_select
         self._on_double_click = on_double_click
+        self._on_context = on_context
         self._provider_label = provider_label
         self._boxed = boxed
         self._filter = ""
         self._loading = False
         self._selected_encoded_name: str | None = None
+        self._context_encoded_name: str | None = None
+        self._favorite_paths = set(favorite_paths or ())
 
         self._new_row = _NewProjectRow(on_click=lambda: self._on_select(None))
         self._walker = urwid.SimpleFocusListWalker(self._build_rows(projects))
@@ -102,11 +111,18 @@ class ProjectsPane(ScrollableSidebarPane, urwid.WidgetWrap):
 
     def _build_rows(self, projects: list[Project]) -> list:
         sel = self._selected_encoded_name
+        context = self._context_encoded_name
         rows = [
-            _ProjectRow(p, selected=(p.encoded_name == sel),
-                        on_click=lambda p=p: self._on_select(p),
-                        on_double_click=(lambda p=p: self._on_double_click(p))
-                                        if self._on_double_click else None)
+            _ProjectRow(
+                p,
+                selected=(p.encoded_name in {sel, context}),
+                is_favorite=p.real_path in self._favorite_paths,
+                on_click=lambda p=p: self._on_select(p),
+                on_double_click=(lambda p=p: self._on_double_click(p))
+                                if self._on_double_click else None,
+                on_right_click=(lambda p=p: self._on_context(p))
+                               if self._on_context else None,
+            )
             for p in self._visible_projects(projects)
         ]
         if not rows:
@@ -127,12 +143,19 @@ class ProjectsPane(ScrollableSidebarPane, urwid.WidgetWrap):
         self, projects: list[Project] | None = None,
     ) -> list[Project]:
         needle = self._filter.lower()
-        return [
+        visible = [
             project for project in (
                 self._all_projects if projects is None else projects
             )
             if fuzzy_match(needle, str(project.real_path))
         ]
+        # Discovery already orders projects by recent activity. A stable sort
+        # moves favorites to the front without disturbing that order within
+        # either group.
+        return sorted(
+            visible,
+            key=lambda project: project.real_path not in self._favorite_paths,
+        )
 
     def set_provider_label(self, label: str) -> None:
         """Update provider-specific empty text, including empty-to-empty switches."""
@@ -160,6 +183,18 @@ class ProjectsPane(ScrollableSidebarPane, urwid.WidgetWrap):
         self._selected_encoded_name = encoded_name
         self._refresh_rows()
 
+    def set_context_selected(self, encoded_name: str | None) -> None:
+        if self._context_encoded_name == encoded_name:
+            return
+        self._context_encoded_name = encoded_name
+        self._refresh_rows()
+
+    def set_favorite_paths(self, paths: set[Path]) -> None:
+        if self._favorite_paths == paths:
+            return
+        self._favorite_paths = set(paths)
+        self._refresh_rows()
+
     def set_filter(self, needle: str) -> None:
         if self._filter == needle:
             return