Tmuxinator(fix[startup_targets]): Respect tmux base indices during import

why: tmuxinator numeric startup_window and startup_pane values are tmux
indices, not Python list offsets. Importing them as list positions changes
which window or pane receives focus and breaks compatibility with existing
configs, especially when base-index or pane-base-index are nonzero.
what:
- resolve numeric startup targets against tmux base-index and pane-base-index
- read live tmux index settings in the tmuxinator import CLI path
- add importer and CLI coverage for base-index aware conversion and fallback

Author: tony

src/tmuxp/cli/import_config.py

@@ -9,6 +9,8 @@
 import sys
 import typing as t
 
+from libtmux.common import tmux_cmd
+
 from tmuxp._internal.config_reader import ConfigReader
 from tmuxp._internal.private_path import PrivatePath
 from tmuxp.workspace import importers
@@ -89,6 +91,59 @@ def _resolve_path_no_overwrite(workspace_file: str) -> str:
     return str(path)
 
 
+def _read_tmux_index_option(*args: str) -> int | None:
+    """Return tmux index option value, or ``None`` when unavailable.
+
+    Examples
+    --------
+    >>> from collections import namedtuple
+    >>> import tmuxp.cli.import_config as import_config
+    >>> FakeResponse = namedtuple("FakeResponse", "returncode stdout")
+    >>> monkeypatch.setattr(
+    ...     import_config,
+    ...     "tmux_cmd",
+    ...     lambda *args: FakeResponse(returncode=0, stdout=["1"]),
+    ... )
+    >>> import_config._read_tmux_index_option("show-options", "-gv", "base-index")
+    1
+    """
+    try:
+        response = tmux_cmd(*args)
+    except Exception:
+        return None
+
+    if response.returncode != 0 or not response.stdout:
+        return None
+
+    try:
+        return int(response.stdout[0])
+    except ValueError:
+        return None
+
+
+def _get_tmuxinator_base_indices() -> tuple[int, int]:
+    """Return tmux base-index and pane-base-index for tmuxinator import.
+
+    Examples
+    --------
+    >>> import tmuxp.cli.import_config as import_config
+    >>> monkeypatch.setattr(
+    ...     import_config,
+    ...     "_read_tmux_index_option",
+    ...     lambda *args: 1 if args[-1] == "base-index" else 2,
+    ... )
+    >>> import_config._get_tmuxinator_base_indices()
+    (1, 2)
+    """
+    base_index = _read_tmux_index_option("show-options", "-gv", "base-index")
+    pane_base_index = _read_tmux_index_option(
+        "show-window-options",
+        "-gv",
+        "pane-base-index",
+    )
+    return (base_index or 0, pane_base_index or 0)
+
+
 def command_import(
     workspace_file: str,
     print_list: str,
@@ -253,12 +308,21 @@ def command_import_tmuxinator(
     """
     color_mode = get_color_mode(color)
     colors = Colors(color_mode)
+    base_index, pane_base_index = _get_tmuxinator_base_indices()
 
     workspace_file = find_workspace_file(
         workspace_file,
         workspace_dir=get_tmuxinator_dir(),
     )
-    import_config(workspace_file, importers.import_tmuxinator, colors=colors)
+
+    def tmuxinator_importer(workspace_dict: dict[str, t.Any]) -> dict[str, t.Any]:
+        return importers.import_tmuxinator(
+            workspace_dict,
+            base_index=base_index,
+            pane_base_index=pane_base_index,
+        )
+
+    import_config(workspace_file, tmuxinator_importer, colors=colors)
 
 
 def command_import_teamocil(

src/tmuxp/workspace/importers.py

@@ -61,7 +61,56 @@ def _convert_named_panes(panes: list[t.Any]) -> list[t.Any]:
     return result
 
 
-def import_tmuxinator(workspace_dict: dict[str, t.Any]) -> dict[str, t.Any]:
+def _resolve_tmux_list_position(
+    target: str | int,
+    *,
+    base_index: int,
+    item_count: int,
+) -> int | None:
+    """Resolve a tmux index into a Python list position.
+
+    Parameters
+    ----------
+    target : str or int
+        tmux index from tmuxinator configuration
+    base_index : int
+        tmux base index for the list being resolved
+    item_count : int
+        number of items in the generated tmuxp list
+
+    Returns
+    -------
+    int or None
+        Python list position if the target resolves within bounds
+
+    Examples
+    --------
+    >>> _resolve_tmux_list_position(1, base_index=1, item_count=2)
+    0
+
+    >>> _resolve_tmux_list_position("2", base_index=1, item_count=2)
+    1
+
+    >>> _resolve_tmux_list_position(3, base_index=1, item_count=2) is None
+    True
+    """
+    try:
+        list_position = int(target) - base_index
+    except ValueError:
+        return None
+
+    if 0 <= list_position < item_count:
+        return list_position
+
+    return None
+
+
+def import_tmuxinator(
+    workspace_dict: dict[str, t.Any],
+    *,
+    base_index: int = 0,
+    pane_base_index: int = 0,
+) -> dict[str, t.Any]:
     """Return tmuxp workspace from a `tmuxinator`_ yaml workspace.
 
     .. _tmuxinator: https://github.com/aziz/tmuxinator
@@ -243,26 +292,18 @@ def import_tmuxinator(workspace_dict: dict[str, t.Any]) -> dict[str, t.Any]:
                 _matched = True
                 break
         if not _matched:
-            try:
-                _idx = int(_startup_window)
-                if 0 <= _idx < len(tmuxp_workspace["windows"]):
-                    tmuxp_workspace["windows"][_idx]["focus"] = True
-                    logger.warning(
-                        "startup_window %r resolved as 0-based list index, "
-                        "which may differ from tmuxinator's tmux base-index "
-                        "semantics; use window name for reliable matching",
-                        _startup_window,
-                    )
-                else:
-                    logger.warning(
-                        "startup_window index %d out of range (0-%d)",
-                        _idx,
-                        len(tmuxp_workspace["windows"]) - 1,
-                    )
-            except (ValueError, IndexError):
+            _idx = _resolve_tmux_list_position(
+                _startup_window,
+                base_index=base_index,
+                item_count=len(tmuxp_workspace["windows"]),
+            )
+            if _idx is not None:
+                tmuxp_workspace["windows"][_idx]["focus"] = True
+            else:
                 logger.warning(
-                    "startup_window %s not found",
+                    "startup_window %r not found for tmux base-index %d",
                     _startup_window,
+                    base_index,
                 )
 
     if _startup_pane is not None and tmuxp_workspace["windows"]:
@@ -271,33 +312,25 @@ def import_tmuxinator(workspace_dict: dict[str, t.Any]) -> dict[str, t.Any]:
             tmuxp_workspace["windows"][0],
         )
         if "panes" in _target:
-            try:
-                _pidx = int(_startup_pane)
-                if 0 <= _pidx < len(_target["panes"]):
-                    _pane = _target["panes"][_pidx]
-                    if isinstance(_pane, dict):
-                        _pane["focus"] = True
-                    else:
-                        _target["panes"][_pidx] = {
-                            "shell_command": [_pane] if _pane else [],
-                            "focus": True,
-                        }
-                    logger.warning(
-                        "startup_pane %r resolved as 0-based list index, "
-                        "which may differ from tmuxinator's tmux "
-                        "pane-base-index semantics",
-                        _startup_pane,
-                    )
+            _pidx = _resolve_tmux_list_position(
+                _startup_pane,
+                base_index=pane_base_index,
+                item_count=len(_target["panes"]),
+            )
+            if _pidx is not None:
+                _pane = _target["panes"][_pidx]
+                if isinstance(_pane, dict):
+                    _pane["focus"] = True
                 else:
-                    logger.warning(
-                        "startup_pane index %d out of range (0-%d)",
-                        _pidx,
-                        len(_target["panes"]) - 1,
-                    )
-            except (ValueError, IndexError):
+                    _target["panes"][_pidx] = {
+                        "shell_command": [_pane] if _pane else [],
+                        "focus": True,
+                    }
+            else:
                 logger.warning(
-                    "startup_pane %s not found",
+                    "startup_pane %r not found for tmux pane-base-index %d",
                     _startup_pane,
+                    pane_base_index,
                 )
 
     return tmuxp_workspace

tests/cli/test_import.py

@@ -10,6 +10,7 @@
 
 from tests.fixtures import utils as test_utils
 from tmuxp import cli
+from tmuxp.cli import import_config as import_config_module
 
 if t.TYPE_CHECKING:
     import pathlib
@@ -173,3 +174,95 @@ def test_import_tmuxinator(
 
     new_config_yaml = tmp_path / "la.yaml"
     assert new_config_yaml.exists()
+
+
+def test_get_tmuxinator_base_indices_reads_live_tmux_options(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Tmuxinator import reads tmux base indices from live tmux options."""
+
+    class FakeTmuxResponse(t.NamedTuple):
+        """Fake tmux command response."""
+
+        returncode: int
+        stdout: list[str]
+
+    def fake_tmux_cmd(*args: str) -> FakeTmuxResponse:
+        if args == ("show-options", "-gv", "base-index"):
+            return FakeTmuxResponse(returncode=0, stdout=["1"])
+        if args == ("show-window-options", "-gv", "pane-base-index"):
+            return FakeTmuxResponse(returncode=0, stdout=["2"])
+        msg = f"unexpected tmux args: {args!r}"
+        raise AssertionError(msg)
+
+    monkeypatch.setattr(import_config_module, "tmux_cmd", fake_tmux_cmd)
+
+    assert import_config_module._get_tmuxinator_base_indices() == (1, 2)
+
+
+def test_get_tmuxinator_base_indices_falls_back_when_tmux_unavailable(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Tmuxinator import falls back to tmux defaults when lookup fails."""
+
+    def raise_tmux_error(*args: str) -> t.NoReturn:
+        msg = f"tmux unavailable for {args!r}"
+        raise RuntimeError(msg)
+
+    monkeypatch.setattr(import_config_module, "tmux_cmd", raise_tmux_error)
+
+    assert import_config_module._get_tmuxinator_base_indices() == (0, 0)
+
+
+def test_command_import_tmuxinator_passes_resolved_base_indices(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Tmuxinator import command passes resolved tmux indices to the importer."""
+    captured: dict[str, t.Any] = {}
+
+    def fake_find_workspace_file(
+        workspace_file: str,
+        workspace_dir: t.Any,
+    ) -> str:
+        captured["workspace_file"] = workspace_file
+        captured["workspace_dir"] = workspace_dir
+        return workspace_file
+
+    def fake_import_config(
+        workspace_file: str,
+        importfunc: t.Callable[[dict[str, t.Any]], dict[str, t.Any]],
+        parser: t.Any = None,
+        colors: t.Any = None,
+    ) -> None:
+        captured["workspace_file"] = workspace_file
+        captured["parser"] = parser
+        captured["colors"] = colors
+        captured["imported"] = importfunc(
+            {
+                "name": "sample",
+                "startup_window": 1,
+                "startup_pane": 2,
+                "windows": [{"editor": ["vim", "logs"]}],
+            }
+        )
+
+    monkeypatch.setattr(
+        import_config_module,
+        "find_workspace_file",
+        fake_find_workspace_file,
+    )
+    monkeypatch.setattr(import_config_module, "import_config", fake_import_config)
+    monkeypatch.setattr(
+        import_config_module,
+        "_get_tmuxinator_base_indices",
+        lambda: (1, 2),
+    )
+
+    import_config_module.command_import_tmuxinator("sample.yml")
+
+    imported = captured["imported"]
+    assert imported["windows"][0]["focus"] is True
+    assert imported["windows"][0]["panes"][0] == {
+        "shell_command": ["vim"],
+        "focus": True,
+    }