rexdeck 0.1.0__py3-none-any.whl

rexdeck/plugins/files/launch.py

@@ -0,0 +1,218 @@
+"""Start unmodified Yazi in a native Rex terminal and restore its exact origin."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import socket
+import subprocess
+import sys
+from pathlib import Path
+from urllib.parse import unquote, urlsplit
+
+
+def directory(raw: str) -> str:
+    """Decode only an explicit absolute local directory, never a fallback."""
+    if not raw or "\x00" in raw:
+        raise ValueError(
+            "An explicit local directory without NUL characters is required"
+        )
+    raw.encode("utf-8", errors="strict")
+    if raw.lower().startswith("file:"):
+        if any(ord(char) < 32 or ord(char) == 127 for char in raw):
+            raise ValueError("File URI contains unescaped control characters")
+        uri = urlsplit(raw)
+        authority = uri.netloc.casefold()
+        if (
+            authority not in ("", "localhost")
+            and authority != socket.gethostname().casefold()
+            and authority != socket.getfqdn().casefold()
+        ):
+            raise ValueError("Remote or credentialed file URI is not supported")
+        if "?" in raw or "#" in raw:
+            raise ValueError("File URI must not contain a query or fragment")
+        if re.search(r"%(?![0-9a-fA-F]{2})", uri.path):
+            raise ValueError("File URI contains invalid percent encoding")
+        raw = unquote(uri.path, encoding="utf-8", errors="strict")
+    if "\x00" in raw or not raw.startswith("/") or raw.startswith("//"):
+        raise ValueError("An absolute local directory is required")
+    try:
+        path = Path(raw).resolve(strict=True)
+    except RuntimeError as error:
+        # Python 3.12 reports symlink loops as RuntimeError rather than OSError.
+        raise ValueError(str(error)) from error
+    if not path.is_dir():
+        raise ValueError("The invoking terminal's cwd is not a directory")
+    return str(path)
+
+
+def git_directory(raw: str) -> str:
+    """Keep cwd-based Git discovery; reject inherited repository redirection."""
+    overrides = {
+        "GIT_DIR",
+        "GIT_WORK_TREE",
+        "GIT_COMMON_DIR",
+        "GIT_INDEX_FILE",
+        "GIT_OBJECT_DIRECTORY",
+        "GIT_ALTERNATE_OBJECT_DIRECTORIES",
+        "GIT_NAMESPACE",
+        "GIT_CONFIG",
+        "GIT_CONFIG_COUNT",
+        "GIT_CONFIG_PARAMETERS",
+        "GIT_CEILING_DIRECTORIES",
+        "GIT_DISCOVERY_ACROSS_FILESYSTEM",
+    }
+    selected = sorted(
+        key
+        for key in os.environ
+        if key in overrides or key.startswith(("GIT_CONFIG_KEY_", "GIT_CONFIG_VALUE_"))
+    )
+    if selected:
+        raise ValueError("Ambiguous inherited Git override: " + ", ".join(selected))
+    cwd = directory(raw)
+    search_path = os.pathsep.join(
+        entry
+        for entry in os.environ.get("PATH", os.defpath).split(os.pathsep)
+        if Path(entry).is_absolute()
+    )
+    git = shutil.which("git", path=search_path) if search_path else None
+    if git is None:
+        raise ValueError(
+            "Required executable not found in absolute PATH directories: git"
+        )
+    result = subprocess.run(
+        [git, "rev-parse", "--is-inside-work-tree"],
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+        timeout=10,
+        check=False,
+    )
+    if result.returncode:
+        raise ValueError(result.stderr.strip() or f"Git exited {result.returncode}")
+    if result.stdout.strip() != "true":
+        raise ValueError("Invoking directory is not a non-bare Git worktree")
+    return cwd
+
+
+def acknowledge() -> None:
+    if sys.stdin.isatty():
+        try:
+            input("Press Enter to close RexDeck: ")
+        except (EOFError, KeyboardInterrupt):
+            pass
+
+
+def restore_focus(rex: str, server: str, session: str, origin: str) -> None:
+    """Use API identities, not CLI label/suffix/directional target resolution."""
+    environment = dict(os.environ)
+    environment.pop("REX_SESSION", None)
+    environment.pop("REX_BLOCK", None)
+    environment.pop("REX_CLIENT", None)
+    result = subprocess.run(
+        [
+            rex,
+            "-S",
+            server,
+            "--autostart=false",
+            "--timeout=10s",
+            "api",
+            "call",
+            "session.focus_block",
+            json.dumps({"session_id": session, "block_id": origin}),
+        ],
+        env=environment,
+        capture_output=True,
+        text=True,
+        timeout=15,
+        check=False,
+    )
+    if result.returncode:
+        raise RuntimeError(f"Rex exited {result.returncode}: {result.stderr.strip()}")
+
+
+def run(
+    yazi: str,
+    rex: str,
+    server: str,
+    session: str,
+    origin: str,
+    cwd: str,
+    *,
+    plugin: str = "files",
+) -> int:
+    """Launch the selected native tool at validated cwd, then restore origin focus."""
+    title = "Git" if plugin == "git" else "Files"
+    tool = "lazygit" if plugin == "git" else "Yazi"
+    exit_code = 1
+    try:
+        if not all((server, session, origin)):
+            raise ValueError(
+                "Explicit Rex server, session and origin identities are required"
+            )
+        if not Path(yazi).is_absolute() or not Path(rex).is_absolute():
+            raise ValueError("Absolute tool and Rex executable paths are required")
+        checked_cwd = git_directory(cwd) if plugin == "git" else directory(cwd)
+        # Inherit the actual pane TTY and the tool's normal configuration.
+        exit_code = subprocess.run([yazi], cwd=checked_cwd, check=False).returncode
+        if exit_code < 0:
+            exit_code = 128 - exit_code
+        if exit_code:
+            print(f"RexDeck {title}: {tool} exited {exit_code}", file=sys.stderr)
+            acknowledge()
+    except KeyboardInterrupt:
+        exit_code = 130
+        print(f"RexDeck {title}: {tool} interrupted", file=sys.stderr)
+        acknowledge()
+    except (OSError, ValueError, subprocess.SubprocessError) as error:
+        print(f"RexDeck {title}: cannot launch {tool}: {error}", file=sys.stderr)
+        acknowledge()
+    try:
+        if not all((server, session, origin)) or not Path(rex).is_absolute():
+            raise ValueError(
+                "Cannot restore focus without explicit Rex origin and executable"
+            )
+        restore_focus(rex, server, session, origin)
+    except KeyboardInterrupt:
+        print(
+            f"RexDeck {title}: return focus to original pane {origin!r} interrupted; "
+            "focus outcome is unknown. No replacement pane was selected.",
+            file=sys.stderr,
+        )
+        acknowledge()
+        return exit_code or 1
+    except (OSError, ValueError, RuntimeError, subprocess.TimeoutExpired) as error:
+        print(
+            f"RexDeck {title}: cannot return focus to original pane {origin!r}: {error}. "
+            "No replacement pane was selected.",
+            file=sys.stderr,
+        )
+        acknowledge()
+        return exit_code or 1
+    return exit_code
+
+
+def main() -> int:
+    """Dispatch standalone cwd validation and native pane launch commands."""
+    args = sys.argv[1:]
+    if len(args) == 2 and args[0] in ("cwd", "git-cwd"):
+        try:
+            cwd = git_directory(args[1]) if args[0] == "git-cwd" else directory(args[1])
+            print(json.dumps({"cwd": cwd}))
+            return 0
+        except (OSError, ValueError, subprocess.SubprocessError) as error:
+            print(f"RexDeck: invalid invoking cwd: {error}", file=sys.stderr)
+            return 1
+    if len(args) == 7 and args[0] in ("run", "git-run"):
+        return run(*args[1:], plugin="git" if args[0] == "git-run" else "files")
+    print(
+        "Use [git-]cwd RAW_PWD or [git-]run TOOL REX SERVER SESSION ORIGIN CWD",
+        file=sys.stderr,
+    )
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

rexdeck/plugins/files/main.lua

@@ -0,0 +1,92 @@
+-- Native Rex configuration module; also embedded verbatim by RexDeck's installer.
+return function(opts)
+  if type(opts) ~= 'table' then error('RexDeck Files requires installation options', 0) end
+  local plugin = opts.plugin or 'files'
+  if plugin ~= 'files' and plugin ~= 'git' then error('Unknown RexDeck integration', 0) end
+  local is_git = plugin == 'git'
+  local title = is_git and 'RexDeck Git' or 'RexDeck Files'
+  local tool = is_git and 'lazygit' or 'yazi'
+  local paths = {}
+  for _, key in ipairs({'python', 'rex', tool}) do
+    local value = opts[key]
+    if type(value) ~= 'string' or value:sub(1, 1) ~= '/' or value:find('%z') then
+      error(title .. ' requires an absolute ' .. key .. ' path', 0)
+    end
+    paths[key] = value
+  end
+  local launcher = opts.launcher_code
+  if type(launcher) ~= 'string' or launcher == '' or launcher:find('%z') then
+    error(title .. ' requires its applied Python launcher', 0)
+  end
+  local server = opts.server
+  if type(server) ~= 'string' or server == '' or server:find('%z') then
+    error(title .. ' requires an explicit Rex server', 0)
+  end
+
+  rex.action{
+    name = 'rexdeck_' .. plugin,
+    title = title,
+    category = 'RexDeck',
+    description = 'Open ' .. tool .. ' in the invoking terminal directory',
+    keywords = is_git and 'git lazygit' or 'files yazi explorer',
+    run = function(ctx, args)
+      -- Freeze identity before any call can change focus or mutate the context.
+      local session = type(ctx) == 'table' and ctx.session_id
+      local origin = type(ctx) == 'table' and ctx.block_id
+      if type(session) ~= 'string' or session == '' or type(origin) ~= 'string' or origin == '' then
+        error(title .. ' requires the invoking session and terminal pane', 0)
+      end
+      local attached, attach_error = rex.call('session.attach', {session_id = session})
+      if not attached then
+        error(title .. ' cannot attach to the invoking session: ' .. tostring(attach_error), 0)
+      end
+      local reported, pwd_error = rex.call('com.superlogical.terminal.pwd', {
+        session_id = session, block_id = origin, args = {},
+      })
+      if not reported then
+        error(title .. ' cannot read the invoking terminal cwd: ' .. tostring(pwd_error), 0)
+      end
+      if type(reported.pwd) ~= 'string' or reported.pwd == '' then
+        error(title .. ': the invoking terminal has not reported a cwd', 0)
+      end
+      local checked, exec_error = rex.exec({paths.python, '-I', '-c', launcher,
+        is_git and 'git-cwd' or 'cwd', reported.pwd}, {timeout = 15})
+      if not checked then
+        error(title .. ' cannot validate the invoking cwd: ' .. tostring(exec_error), 0)
+      end
+      if not checked.ok then
+        error(title .. ' refused the invoking cwd: ' .. tostring(checked.stderr), 0)
+      end
+      local decoded, json_error = rex.json.decode(checked.stdout)
+      if json_error or type(decoded) ~= 'table' or type(decoded.cwd) ~= 'string'
+          or decoded.cwd:sub(1, 1) ~= '/' or decoded.cwd:find('%z') then
+        error(title .. ' received an invalid cwd validation result: ' .. tostring(json_error), 0)
+      end
+      local cwd = decoded.cwd
+      local split, split_error = rex.session.new_split{
+        session_id = session,
+        anchor_id = origin,
+        direction = 'horizontal',
+        side = 'after',
+        ratio = 0.5,
+        focus = true,
+        layout = {block = {
+          flavor = 'com.superlogical.terminal.shell',
+          label = title,
+          options = {
+            cwd = cwd,
+            shell = 'none',
+            login = false,
+            exit = {on_completion = true},
+            command = {paths.python, '-I', '-c', launcher, is_git and 'git-run' or 'run',
+              paths[tool], paths.rex, server, session, origin, cwd},
+          },
+        }},
+      }
+      if not split then
+        error(title .. ' cannot open the tool terminal: ' .. tostring(split_error), 0)
+      end
+      return split
+    end,
+  }
+end

rexdeck/settings.py

@@ -0,0 +1,188 @@
+"""Bounded, atomic storage of the explicitly approved native Files target."""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import cast
+
+from rexdeck import lifecycle
+
+_MAX_SETTINGS = 16 * 1024
+_FIELDS = {
+    "version",
+    "kind",
+    "workspace",
+    "data_root",
+    "config",
+    "config_target",
+    "server",
+    "real_server",
+}
+
+
+def xdg_path(name: str, default: Path) -> Path:
+    value = os.environ.get(name)
+    if value is None:
+        return default
+    if not value or not Path(value).is_absolute() or "\x00" in value:
+        raise RuntimeError(f"{name} must be a nonempty absolute path")
+    return Path(value)
+
+
+def settings_path() -> Path:
+    return xdg_path("XDG_CONFIG_HOME", Path.home() / ".config") / "rexdeck/config.json"
+
+
+def default_workspace() -> Path:
+    return (
+        xdg_path("XDG_STATE_HOME", Path.home() / ".local/state") / "rexdeck/files"
+    ).resolve()
+
+
+def default_data_root() -> Path:
+    root = xdg_path("XDG_DATA_HOME", Path.home() / ".local/share") / "rexdeck"
+    if root.is_symlink():
+        raise RuntimeError(f"Files deployment directory is redirected: {root}")
+    return root.resolve()
+
+
+def _absolute(value: object, name: str) -> Path:
+    if not isinstance(value, str) or not value or "\x00" in value:
+        raise RuntimeError(f"Saved {name} must be a nonempty absolute path")
+    path = Path(value)
+    if not path.is_absolute() or str(path) != value or ".." in path.parts:
+        raise RuntimeError(f"Saved {name} must be a normalized absolute path")
+    return path
+
+
+def _object(pairs: list[tuple[str, object]]) -> dict[str, object]:
+    result: dict[str, object] = {}
+    for key, value in pairs:
+        if key in result:
+            raise RuntimeError(f"Duplicate settings field: {key}")
+        result[key] = value
+    return result
+
+
+@dataclass(frozen=True)
+class SavedTarget:
+    workspace: Path
+    data_root: Path
+    config: Path
+    config_target: Path
+    server: str
+    real_server: bool
+
+    def _validate(self, plugin: str | None = None) -> None:
+        """Validate shared frozen identity and only an explicitly selected plugin."""
+        if self.config.resolve(strict=True) != self.config_target:
+            raise RuntimeError(
+                "Saved Rex config target changed; restore the selected symlink before "
+                "using rexdeck setup or changing Files"
+            )
+        if self.workspace.resolve() != self.workspace:
+            raise RuntimeError("Saved Files workspace target changed; restore its path")
+        lifecycle._validate_data_root(self.data_root, plugin)
+        if lifecycle._canonical_server(self.server) != self.server:
+            raise RuntimeError("Saved Rex socket target changed; restore its path")
+
+    def setup(self, plugin: str = "files") -> lifecycle.Setup:
+        """Validate frozen target paths and select one integration's ownership."""
+        self._validate(plugin)
+        return lifecycle.Setup(
+            project=Path(__file__).resolve().parent,
+            workspace=self.workspace,
+            data_root=self.data_root,
+            config=self.config,
+            server=self.server,
+            real_server=self.real_server,
+            plugin=plugin,
+        )
+
+    def document(self) -> dict[str, object]:
+        return {
+            "version": 2,
+            "kind": "native-files",
+            "workspace": str(self.workspace),
+            "data_root": str(self.data_root),
+            "config": str(self.config),
+            "config_target": str(self.config_target),
+            "server": self.server,
+            "real_server": self.real_server,
+        }
+
+
+def load(path: Path) -> SavedTarget | None:
+    """Load bounded settings and validate shared identity before plugin selection."""
+    try:
+        descriptor = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+    except FileNotFoundError:
+        return None
+    try:
+        info = os.fstat(descriptor)
+        if not stat.S_ISREG(info.st_mode) or info.st_size > _MAX_SETTINGS:
+            raise RuntimeError(
+                "RexDeck settings must be a bounded regular non-symlink file"
+            )
+        with os.fdopen(descriptor, "rb", closefd=False) as stream:
+            data = stream.read(_MAX_SETTINGS + 1)
+        if len(data) > _MAX_SETTINGS:
+            raise RuntimeError("RexDeck settings exceed the size limit")
+    finally:
+        os.close(descriptor)
+    try:
+        value: object = json.loads(data, object_pairs_hook=_object)
+    except (ValueError, UnicodeError) as exc:
+        raise RuntimeError(f"Invalid RexDeck settings JSON: {exc}") from exc
+    if not isinstance(value, dict):
+        raise RuntimeError("RexDeck settings must be a JSON object")
+    fields = cast(dict[str, object], value)
+    if (
+        set(fields) != _FIELDS
+        or type(fields["version"]) is not int
+        or fields["version"] != 2
+        or fields["kind"] != "native-files"
+        or type(fields["real_server"]) is not bool
+    ):
+        raise RuntimeError("Unsupported or malformed RexDeck settings schema")
+    server = fields["server"]
+    if not isinstance(server, str) or not server or server != server.strip():
+        raise RuntimeError("Saved server must be a nonempty Unix endpoint")
+    lifecycle._socket_path(server)
+    target = SavedTarget(
+        workspace=_absolute(fields["workspace"], "workspace"),
+        data_root=_absolute(fields["data_root"], "data_root"),
+        config=_absolute(fields["config"], "config"),
+        config_target=_absolute(fields["config_target"], "config_target"),
+        server=server,
+        real_server=fields["real_server"],
+    )
+    if target.config_target.resolve() != target.config_target:
+        raise RuntimeError("Saved config_target must be a resolved absolute path")
+    target._validate()
+    return target
+
+
+def save(path: Path, target: SavedTarget) -> None:
+    data = (json.dumps(target.document(), ensure_ascii=True, indent=2) + "\n").encode()
+    if len(data) > _MAX_SETTINGS:
+        raise RuntimeError("Approved RexDeck settings exceed the size limit")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, temporary = tempfile.mkstemp(prefix=".config-", dir=path.parent)
+    try:
+        with os.fdopen(descriptor, "wb") as stream:
+            stream.write(data)
+            stream.flush()
+            os.fsync(stream.fileno())
+        # Publish a complete file without ever replacing a concurrently saved target.
+        os.link(temporary, path)
+    finally:
+        try:
+            os.unlink(temporary)
+        except FileNotFoundError:
+            pass

rexdeck-0.1.0.dist-info/METADATA

@@ -0,0 +1,127 @@
+Metadata-Version: 2.5
+Name: rexdeck
+Version: 0.1.0
+Summary: Native Rex integrations for independently selectable existing tools
+Project-URL: Homepage, https://github.com/Mathews-Tom/RexDeck
+Project-URL: Repository, https://github.com/Mathews-Tom/RexDeck
+Project-URL: Issues, https://github.com/Mathews-Tom/RexDeck/issues
+Project-URL: Changelog, https://github.com/Mathews-Tom/RexDeck/blob/main/CHANGELOG.md
+Author: Tom Mathews
+License-Expression: MIT
+License-File: LICENSE
+Keywords: lazygit,rex,terminal,yazi
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# RexDeck
+
+A collection of independently selectable plugins and extensions that bring existing tools into your own Rex application.
+
+Files and local Git bring unmodified Yazi and lazygit into native Rex terminals. GitHub workflows, rich viewers, agent/subagent views, and task-provider integrations remain planned. Select the tools you need without installing an unrelated default suite.
+
+## Plugins and extensions
+
+| Integration | Purpose | Status |
+| --- | --- | --- |
+| [Files](plugins/files/README.md) | Browse, preview, and manage files using unmodified Yazi in a native Rex terminal | Available |
+| [Git](plugins/git/README.md) | Inspect, stage, and commit in the invoking repository/worktree using unmodified lazygit | Available |
+| GitHub | Pull-request/issue workflows with explicit repository/host/account | Planned |
+| Rich viewers | Rendered Markdown, PDF, and image viewing | Planned |
+| Agents and subagents | Attention, observed state, and navigation to agent work | Planned |
+| Tasks | Independently selectable Linear and ClickUp workflows | Planned |
+
+Planned integrations are not implemented or installable yet. RexDeck is not published on PyPI; install the current source package as described below.
+
+## Getting started
+
+The qualified platform is **macOS arm64, Rex API revision 10 baseline, and Python 3.12+**. Revision 10 is not an exact-version compatibility gate. Rex must already be installed and running; RexDeck does not bootstrap Rex, Homebrew, Python, or uv. Other platforms, remote hosts, and multi-device operation are not qualified.
+
+Until the approved PyPI release is published, install the pinned public source baseline (Files and Git; before S1 dependency onboarding):
+
+```sh
+uv tool install 'git+https://github.com/Mathews-Tom/RexDeck.git@d7f934e31d2becf53bc435ac931fa6e1b984bbd0'
+```
+
+For the S1 candidate, use its reviewed checkout and record the exact commit:
+
+```sh
+uv tool install .
+rexdeck setup
+rexdeck enable files
+rexdeck status
+```
+
+The installed command works from any directory; the package includes the shared native action and Python launcher for Files and Git. No shell wrapper, `RD_*` variables, or developer checkout is needed at runtime. Ensure the tool executable directory reported by `uv` is on `PATH`.
+
+`setup` remembers the selected Rex configuration and running server without changing Rex configuration. Interactive setup asks for approval before saving a personal-server target. Use `enable files` or `enable git` independently, `status [files|git]` to inspect ownership/registration, and `disable <id>` to remove only that integration. Unqualified `status` reports both integrations, retaining healthy results alongside an integration-specific fault if its sibling cannot be inspected. See the plugin READMEs for prerequisites, capabilities, updates, and removal.
+
+The uv-managed package remains the runtime source. Setup freezes the app data root from `$XDG_DATA_HOME/rexdeck` (default `~/.local/share/rexdeck`); each integration deploys `plugins/<id>/rexdeck_<id>.lua` there with an independently owned tracked loader in Rex's `init.lua`. Approved preferences remain in `$XDG_CONFIG_HOME/rexdeck/config.json`. Files receipt/lock paths remain in the saved `$XDG_STATE_HOME/rexdeck/files` workspace; Git uses its `git/` subdirectory. Later `XDG_DATA_HOME` changes do not retarget the saved installation. Run `disable` for every applied integration before uninstalling RexDeck or deliberately resetting a saved target, including integrations reported as disabled after a failed enable.
+
+### Selected dependencies
+
+`setup` and `status` never install packages. `enable files` validates preinstalled Yazi; `enable git` validates preinstalled Git/lazygit. Qualified versions are **Yazi 26.9.1, lazygit 0.66.2 or 0.66.3**. Missing or unqualified selected tools produce actionable nonzero manual-install/version-check/rerun guidance without registration or installation prompts. RexDeck never installs, upgrades, downloads, cancels package transactions, or removes upstream tools, and never probes or executes Homebrew.
+
+Executable discovery ignores empty and relative `PATH` entries. Absolute entries, including checkout directories and symlinks to them, remain eligible for version probes and lifecycle lookup. Put only trusted tools in absolute `PATH` directories. RexDeck captures followed-target device/inode/mode/size/nanosecond timestamps/owner before the version probe and rechecks that identity afterward and under its operation locks immediately before applying or enabling an integration. Replacement or modification requires rerunning enable. This is metadata-based detection, not pinned execution or protection against an executable changed after the final check.
+
+Install dependencies yourself using qualified upstream releases: [Yazi 26.9.1](https://github.com/sxyazi/yazi/releases/tag/v26.9.1), [lazygit 0.66.2](https://github.com/jesseduffield/lazygit/releases/tag/v0.66.2) or [0.66.3](https://github.com/jesseduffield/lazygit/releases/tag/v0.66.3). Follow [Yazi installation](https://yazi-rs.github.io/docs/installation/) or [lazygit installation](https://github.com/jesseduffield/lazygit#installation); Git must also already be installed for Git integration.
+
+If you choose Homebrew, first run `brew info yazi` or `brew info lazygit` yourself and inspect the selected version and dependency/source-build/upgrade effects. **Skip Homebrew if its selected version is not qualified**; use the qualified upstream release instead. Only if the version qualifies and you accept the package effects, run the selected `brew install yazi` or `brew install lazygit` yourself. RexDeck does not qualify a Homebrew version, prefix or transaction; all package effects remain owner-controlled.
+
+Check `yazi --version` or `lazygit --version` (and `git --version` for Git), then rerun `rexdeck enable files` or `rexdeck enable git`. The pinned pre-S1 source baseline above requires manual dependency provisioning too, but does not contain S1's selected-tool qualification/guidance behavior.
+
+Rex, Yazi, lazygit, Git, Homebrew, Python and uv remain externally managed prerequisites. No install-all, sudo, silent upgrade, tool configuration change, or upstream package removal is performed. `disable` and Python package uninstall leave upstream tools installed.
+
+## Design principles
+
+- **Reuse tools, do not rebuild them.** Preserve their normal interfaces, configuration, authentication, and capabilities.
+- **Prefer native Rex integration.** Use native actions and panes where sufficient. LazyRex is optional only where a particular integration needs an existing capability; it is not a collection-wide dependency.
+- **Keep features independently selectable.** Install only the dependencies needed by the chosen integration; no implicit default suite, hooks, or autostart.
+- **Preserve user context and ownership.** Pass explicit launch context and structured arguments, keep unrelated work intact, and make removal reversible.
+- **Disclose capabilities accurately.** External tools run as your OS account and can be write-capable; they are not sandboxed or automatically read-only.
+
+## Development
+
+Install LuaJIT before running the suite: native Lua behavior tests require `lua` or `luajit` and otherwise skip. On macOS:
+
+```sh
+brew install luajit
+uv sync --locked
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy --strict
+uv run pytest
+```
+
+Plugin-specific syntax checks and real interaction verification belong in each plugin's README. Keep plugin documentation under `plugins/<name>/README.md` and packaged runtime assets under `src/rexdeck/plugins/<name>/`. Link available integrations from the table above. Do not create empty plugin folders for planned features.
+
+## Release preparation and owner gate
+
+Version **0.1.0 is prepared, not evidence of publication**. Do not use a PyPI install command until the release's public registry files and hashes have been verified. A PyPI name lookup returning 404 does not establish ownership, name eligibility, or publishing access.
+
+The manual [`publish.yml`](.github/workflows/publish.yml) workflow supports [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/) using [uv](https://docs.astral.sh/uv/guides/package/#publishing-your-package). No ordinary push, PR, or tag publishes anything; no release-time rebuild occurs.
+
+Before dispatch, the owner must configure a PyPI project or pending publisher for `rexdeck`: GitHub owner `Mathews-Tom`, repository `RexDeck`, workflow `publish.yml`, environment `pypi`. Configure that GitHub environment with `Mathews-Tom` as its **sole required reviewer** and restrict deployment to `main`; GitHub permits any listed reviewer to approve, so additional reviewers do not enforce owner approval. Leave self-review prevention disabled for owner-dispatched runs so the sole owner can approve an assistant-dispatched run under the owner's GitHub identity. These account/environment changes require owner participation and are not performed by setup or this repository. Missing protection or publisher access holds publication.
+
+The S1 publication boundary assumes this remains a personal-account repository with Mathews-Tom as its sole administrator. Owner-controlled bypass/configuration is trusted; transfer to an organization requires re-evaluating that gate.
+
+1. Merge only the reviewed candidate. A successful **push on main** `checks.yml` run builds wheel/sdist once and retains the exact pair as `rexdeck-0.1.0`; download and inspect them, record both SHA-256 hashes, immutable artifact ID, full commit SHA, run URL, and runtime/security/review evidence. Artifacts expire; a rebuild requires fresh hashes and approval.
+2. Obtain explicit owner approval naming that exact commit, artifact ID, both filenames/hashes, and reviewed evidence. Any changed input requires renewed approval. After this approval only, create/verify the annotated `v0.1.0` tag and GitHub Release at that commit, attaching the same files; never rebuild for a tag.
+3. Dispatch `publish.yml` **from main at that approved commit**, entering the exact SHA, artifact ID, hashes and approval-evidence URL. The protected-environment reviewer must compare the dispatch inputs/run summary against the approval before approving the deployment. The workflow verifies repository/run provenance, tag target and hashes, then publishes only `approved/rexdeck-0.1.0.tar.gz` and `approved/rexdeck-0.1.0-py3-none-any.whl` with `uv publish --trusted-publishing always` (no token secret or broad `dist/*` upload).
+4. Verify [PyPI JSON](https://pypi.org/pypi/rexdeck/0.1.0/json) exposes both approved hashes. Then run an isolated no-cache public-index install, allowing index propagation, and repeat actual private Rex use/quit/refresh/disable. Only then document `uv tool install 'rexdeck==0.1.0'` as available:
+
+   ```sh
+   uv --no-cache run --isolated --no-project --index https://pypi.org/simple \
+     --with rexdeck==0.1.0 rexdeck --help
+   ```
+
+CI and private endpoint/TUI captures do not prove owner-app palette, glyph, or desktop visual approval. Successful package installation does not prove native interaction; successful local builds do not prove registry publication. Keep those evidence claims separate.
+
+## License
+
+RexDeck is [MIT licensed](LICENSE), included in wheel/sdist metadata. External executables are **not bundled**: [Yazi is MIT](https://github.com/sxyazi/yazi/blob/main/LICENSE) and [lazygit is MIT](https://github.com/jesseduffield/lazygit/blob/master/LICENSE), retaining upstream notices and terms. Git retains its own upstream license. Rex is an externally installed, separately licensed application prerequisite; RexDeck's MIT license does not grant rights to Rex or redistribute it.

rexdeck-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+rexdeck/__init__.py,sha256=dta1LrrcdEEoTEdYFAwyXieXsx8AWioPIK2xBwkwSfE,55
+rexdeck/cli.py,sha256=N47pPZF-hb4vzIwKK4Grai5IkbYohMabcx4LfZ66Rcg,11452
+rexdeck/dependencies.py,sha256=SX9kCjm7to6KJj9B-WmfePpGCAa9QRg3YYKmsUw0gQ0,3625
+rexdeck/lifecycle.py,sha256=PJWHaSjJHdgBKpA6NAREGniQ1_c8Pdl60kQoOBJx1tI,47725
+rexdeck/settings.py,sha256=EPuMiteAxxMzyiZm2_f6b1s2DUcE6ORuwbKL1ykKgCU,6687
+rexdeck/plugins/files/launch.py,sha256=GDlL2_3rr_rDOU3OqV6IUcvO6X0nXbmt91V7DMPlGqg,7757
+rexdeck/plugins/files/main.lua,sha256=itAOYwyMlGcsPGlumj47ktdCMZFICj8mqKQYfTSjxME,3981
+rexdeck-0.1.0.dist-info/METADATA,sha256=lKr_vnZXnY72uuUnMKSwyJg6OetyJ4v1B3XaBbZHwic,12599
+rexdeck-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+rexdeck-0.1.0.dist-info/entry_points.txt,sha256=GuflU63f8PxKffblz6oBANdiD36nau_AqJ90s82fCMc,45
+rexdeck-0.1.0.dist-info/licenses/LICENSE,sha256=g6qKmvZAxoXVjOFPeSmV4IaCkMZMuRektS4YVmfl8-k,1068
+rexdeck-0.1.0.dist-info/RECORD,,

rexdeck-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

rexdeck-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+rexdeck = rexdeck.cli:main