rex-worktrees 0.1.2 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,10 +1,10 @@
1
1
  # Rex Worktrees
2
2
 
3
- Rex Worktrees opens Git worktrees in an exact [Rex](https://www.superlogical.com/rex/docs) session on this machine or an existing Rex host. Its keyboard-driven chooser runs in a floating Rex terminal. Rex manages hosts, connections, and sessions; this tool creates or selects a checkout and opens a shell there.
3
+ Rex Worktrees opens Git worktrees or Jujutsu (JJ) workspaces in an exact [Rex](https://www.superlogical.com/rex/docs) session on this machine or an existing Rex host. Its keyboard-driven chooser runs in a floating Rex terminal. Rex manages hosts, connections, and sessions; this tool creates or selects a checkout and opens a shell there. When a selected logical project has no directory on the destination, the chooser can clone published history and open it there.
4
4
 
5
5
  ## Install
6
6
 
7
- The standalone executable supports Apple Silicon Macs running macOS 15 or later. Git, a running local Rex server, and the Rex CLI are required. Node.js and npm are needed to install the npm package, but not to run the executable; Bun is not required.
7
+ Standalone binaries are built for Apple Silicon Macs running macOS 15 or later and Linux x64 (Ubuntu 24.04 CI runner). Git 2.42 or later, the Rex CLI, and a running local Rex server are required for interactive use; JJ projects additionally require Jujutsu 0.46 or later. Node.js and npm are needed only to install the macOS ARM64 npm package, not to run either standalone executable; Bun is not required.
8
8
 
9
9
  ### npm
10
10
 
@@ -18,14 +18,14 @@ rex config reload
18
18
 
19
19
  ### GitHub Releases
20
20
 
21
- Download the Apple Silicon binary archive from [GitHub Releases](https://github.com/samuelho-dev/rex-worktrees/releases) and extract it to a permanent location. Run setup with the absolute path to the extracted executable:
21
+ Download both `rex-worktrees-macos-arm64.tar.gz` and `rex-worktrees-linux-x64.tar.gz` plus `SHA256SUMS` from [the latest GitHub Release](https://github.com/samuelho-dev/rex-worktrees/releases/latest). Verify them with `shasum -a 256 -c SHA256SUMS` (or `sha256sum -c SHA256SUMS` on Linux), then extract the archive for your platform to a permanent location. Run setup with the absolute path to the extracted executable:
22
22
 
23
23
  ```sh
24
24
  /absolute/path/to/rex-worktrees setup --bin /absolute/path/to/rex-worktrees
25
25
  rex config reload
26
26
  ```
27
27
 
28
- Keep the executable at that path when replacing it with a newer release, then repeat setup and `rex config reload`. Each application archive also contains the relinkable bundle and license notices described below.
28
+ Keep the executable at that path when replacing it with a newer release, then repeat setup and `rex config reload`. Each platform archive contains the relinkable bundle and license notices described below. The stable asset names can be fetched through `releases/latest/download/` without pinning a release version.
29
29
 
30
30
  ### Build from source
31
31
 
@@ -40,9 +40,11 @@ rex config reload
40
40
 
41
41
  Source-build setup copies the executable to `~/.local/bin/rex-worktrees`; `setup --bin PATH` instead registers an existing executable without copying or modifying it. Add `~/.local/bin` to `PATH` for source-build CLI use.
42
42
 
43
- All installation methods place the Lua module beside the active Rex config and add a managed registration without replacing unrelated config. Setup needs `rex` on `PATH`, or `REX_BIN_DIR` set to its absolute directory. Setup from uncompiled source is not supported. Each execution machine needs its own installation; setup does not pair or deploy to another host.
43
+ All installation methods place the Lua module beside the active Rex config and add a managed registration without replacing unrelated config. Setup needs `rex` on `PATH`, or `REX_BIN_DIR` set to its absolute directory. Setup from uncompiled source is not supported. Setup records **this host's executable search `PATH`** for stored Rex actions, whose server-side process may otherwise lack shell-installed tools; run setup from a shell that can find Git and, for JJ projects, `jj`, then `rex config reload`. Repeat setup and reload after changing the tools' search path. Each execution machine needs its own helper installation and, for JJ projects, its own JJ and Git installations; setup does not pair or deploy to another host. The source machine also needs the helper to inspect clone sources.
44
44
 
45
- To update a source build, rebuild and repeat setup and config reload. To uninstall, locate the active Rex config with `rex config check --json`, remove the section from `-- BEGIN rex-worktrees` through `-- END rex-worktrees`, and delete `rex-worktrees.lua` beside that config. Remove the executable with `npm uninstall -g rex-worktrees`, or delete the standalone executable or `~/.local/bin/rex-worktrees` for other installations, then run `rex config reload`. Git worktrees and association state are retained.
45
+ For a stopped Rex server or an image built before Rex starts, run `rex-worktrees setup --config /absolute/path/to/rex/init.lua --bin /absolute/path/to/rex-worktrees`. This uses that explicit config without calling `rex config check`, starting Rex, or reloading it; its managed action registration is loaded when Rex next starts. The file must be a regular file or absent (not a symlink), and the Rex CLI must still be installed in `PATH` or `REX_BIN_DIR` so its directory can be recorded. The managed registration preserves unrelated Lua settings and is safe to repeat.
46
+
47
+ To update a source build, rebuild and repeat setup and config reload. To uninstall, locate the active Rex config with `rex config check --json`, remove the section from `-- BEGIN rex-worktrees` through `-- END rex-worktrees`, and delete `rex-worktrees.lua` beside that config. Remove the executable with `npm uninstall -g rex-worktrees`, or delete the standalone executable or `~/.local/bin/rex-worktrees` for other installations, then run `rex config reload`. Git worktrees, JJ workspaces, and association state are retained.
46
48
 
47
49
  ## Open a worktree
48
50
 
@@ -60,16 +62,16 @@ rex.bind("ctrl+alt+w", "worktrees_open")
60
62
 
61
63
  For a manual Lua installation, supply an absolute executable path with `require("rex-worktrees").setup({ bin = "/absolute/path/to/rex-worktrees" })`.
62
64
 
63
- The chooser has six fields:
65
+ The chooser has six fields (five when opening an existing JJ workspace):
64
66
 
65
- - **Project:** select a known Git project, type a project name, or enter an absolute repository path. Linked checkouts appear under their canonical project.
66
- - **Machine:** select this machine or an existing Rex host. Changing machines keeps the logical project choice but clears checkout, branch, and session bindings; select or enter the actual project directory on the destination.
67
- - **Worktree:** select a checkout reported by Git or type a name for a new checkout directory. Its directory name need not match the branch name.
68
- - **Branch:** select or type a branch. An existing branch without a checkout is attached; one already checked out resolves to that checkout. A new branch starts from the reviewed base commit.
67
+ - **Project:** select a known Git or JJ project, type a project name, or enter an absolute repository path. Linked checkouts appear under their canonical project.
68
+ - **Machine:** select this machine or an existing Rex host. Changing machines keeps the logical project choice but clears host-bound checkout, base, clone destination, and session bindings; select or enter an actual project directory on the destination.
69
+ - **Worktree / Workspace:** Git shows worktrees; JJ shows all registered workspaces, including unavailable entries with an unknown/missing location (visible but not openable). Select an available checkout, type a name for a new checkout/workspace, or choose **Clone this project…** for a known logical project. A clone destination must be an editable absolute path on the destination machine; configured project roots offer suggestions. When cloning, typing a name here optionally creates a separate checkout/workspace; type `none` to use the clone's default.
70
+ - **Branch / Start from:** Git branches retain their existing behavior: attach an unoccupied branch or create a new branch from the reviewed base. For a new JJ workspace, **Start from** selects the repository-configured `trunk()` mainline when it resolves to one valid commit. If no valid mainline is available, choose a source candidate or type a singular revision before creating the workspace. A bookmark or revision selection overrides the default; the action pins its full commit ID. This field is hidden when opening a selected existing JJ workspace, which opens unchanged. A JJ clone can use the clone's native default without a pin, or select/type a source revision resolved on the actual source machine before cloning. Bookmarks are optional; this tool never creates one automatically. Source-only unpublished JJ changes and unpushed Git branches are not available in a destination clone.
69
71
  - **Session:** choose an exact session on the selected machine.
70
- - **Mode:** reuse a matching live tab, open another tab, or split a matching task. If a split has no matching task, it opens a new tab.
72
+ - **Mode:** reuse a matching live tab, open another tab, or split a matching task. If a split has no matching task, it opens a new tab. Cloning always starts a new tab.
71
73
 
72
- Use arrows or `j`/`k` to move, Tab/Shift+Tab to change fields, and Enter to edit or submit. In an editor, type to filter or create, use arrows for existing options, and Ctrl+U to clear. Esc cancels an edit or, from the form, closes the chooser. Review the checkout path and action before submitting. No agent or model is required; the task opens a shell.
74
+ Use arrows or `j`/`k` to move, Tab/Shift+Tab to change fields, and Enter to edit or submit. In an editor, type to filter or create, use arrows for existing options, and Ctrl+U to clear. In the popup, Ctrl+S commits a valid selection or typed edit and submits the reviewed action when available; an invalid edit does not submit, and plain Enter still only selects. Esc cancels an edit or, from the form, closes the chooser. Project and checkout paths appear in the selection lists rather than as extra lines on the main form. Review the checkout path and action before submitting. A clone proposal displays its validated source URL and exact destination, and requires **Clone & Open** consent; merely changing machines never starts cloning. No agent or model is required; the task opens a shell.
73
75
 
74
76
  ## Projects and checkout locations
75
77
 
@@ -89,9 +91,11 @@ Configuration is optional and belongs on the **execution machine** at `${XDG_CON
89
91
  }
90
92
  ```
91
93
 
92
- `projects` explicitly registers paths; optional `roots` scans two directory levels for projects. Without either, the originating Rex pane's directory (or the CLI caller's directory) can suggest its Git project, but no parent directory is scanned. A local directory suggestion is not sent to another machine: enter or select the project directory on that destination. A path typed in the form is interpreted there. Git, not the configuration, determines existing checkouts and branches.
94
+ `projects` explicitly registers paths; optional `roots` scans two directory levels for projects and offers destination-path suggestions when cloning. Without either, the originating Rex pane's directory (or the CLI caller's directory) can suggest its Git or JJ project, but no parent directory is scanned. A local directory suggestion is not sent to another machine: enter or select the project directory on that destination. A path typed in the form is interpreted there. Git and JJ, not configuration, determine their existing checkouts and branches/revisions. A missing directory for a known source project with a validated origin can be proposed for Clone & Open; an existing valid directory continues through ordinary open.
95
+
96
+ For a popup launched from a Rex pane on this machine, the chooser checks that exact pane's reported directory (a local OSC 7 `file://` URI or absolute path). If Rex has not reported one, it uses the same pane's foreground process `cwd` when available. A remote pane or foreign URI is never treated as a local path. Context can legitimately be absent if the pane has no usable local directory, or the directory is not inside a Git or JJ repository; select or enter a project in that case. `--no-context` explicitly disables origin discovery.
93
97
 
94
- New checkout location follows this order: a project's `worktreeRoot/<worktree-name>`, the global `worktreeRoot/<primary-project-name>/<worktree-name>`, or, by default, a sibling `<main-checkout>.worktrees/<worktree-name>`. `~` refers to the destination user's home; relative configuration paths resolve against the config file's directory. Checkout locations must be outside existing checkouts and Git metadata. Collisions and escaping paths are rejected rather than renamed.
98
+ New checkout location follows this order: a project's `worktreeRoot/<name>`, the global `worktreeRoot/<primary-project-name>/<name>`, or, by default, a sibling `<main-checkout>.worktrees/<name>`. `~` refers to the destination user's home; relative configuration paths resolve against the config file's directory. Checkout locations must be outside existing checkouts and version-control metadata. Collisions and escaping paths are rejected rather than renamed. JJ's own `git.colocate` setting governs whether its workspace also has Git metadata; the helper does not emulate colocation.
95
99
 
96
100
  ## CLI
97
101
 
@@ -107,17 +111,21 @@ rex-worktrees open --repo /absolute/path/project \
107
111
  rex-worktrees open --host workstation --repo /destination/path/project \
108
112
  --worktree /destination/path/existing-checkout \
109
113
  --session session:DESTINATION-ID --name Existing
114
+
115
+ rex-worktrees open --repo /absolute/path/jj-workspace \
116
+ --revision 'main@origin' --worktree-name task \
117
+ --session session:FULL-ID --name Task
110
118
  ```
111
119
 
112
120
  `popup` runs the chooser in the invoking terminal; `launch-popup` opens its floating UI in the source Rex window. For `launch-popup` from an external terminal, supply `--session`; inside Rex, the originating session is available automatically. `launch-popup --host` keeps the UI on the caller's server while selecting another execution host. `--host` accepts an existing Rex host label or registry ID; find exact destination session IDs with `rex -S HOST ls --json`. Remote `--repo` and `--worktree` paths must be absolute paths on the destination.
113
121
 
114
- `open` accepts either `--branch` or `--worktree`. `--worktree-name` only applies to `--branch` and sets the new checkout directory name; `--name` independently labels the tab or pane. By default, a matching live tab is reused; `--additional` opens another tab, and `--split` splits a matching task or falls back to a new tab. These two flags cannot be combined. `--client ID` selects an exact Rex app client when needed. See `rex-worktrees --help` for popup origin/context flags.
122
+ `open` detects Git or JJ at `--repo`; no VCS switch is needed. Git accepts `--branch` or `--worktree`, with `--worktree-name` for a new branch checkout. JJ accepts `--worktree` for an existing workspace, or `--revision` plus `--worktree-name` for a new workspace. `--repo` is the actual invoking JJ workspace on the destination: relative revisions such as `@-` resolve there, and creating a new workspace may snapshot it. `--name` independently labels the tab or pane. By default, a matching live tab is reused; `--additional` opens another tab, and `--split` splits a matching task or falls back to a new tab. These two flags cannot be combined. `--client ID` selects an exact Rex app client when needed. See `rex-worktrees --help` for popup origin/context flags.
115
123
 
116
124
  ## Safety and limits
117
125
 
118
- A submitted checkout task can continue after the chooser closes, and closing a tab does not delete its checkout. If a launch times out or Rex reports an uncertain result, inspect Git and the destination session before retrying; a created checkout is retained even when opening Rex fails. The tool does not force checkout, switch, stash, reset, clean, or prune. Linked worktrees have separate files, HEAD, and index, but share Git refs, objects, remotes, and config. Shells are not confined to the checkout. Checkout/tab associations are stored per destination at `${XDG_STATE_HOME:-~/.local/state}/rex-worktrees/associations`; Git remains authoritative if an association becomes stale.
126
+ A submitted checkout or clone task can continue after the chooser closes, and closing a tab does not delete its checkout or clone. If a launch times out or Rex reports an uncertain result, inspect the destination repository and exact session before retrying; partial/registered JJ workspaces and clone destinations are retained rather than blindly removed or retried. Opening or browsing an existing JJ workspace does not snapshot, edit, update-stale, rebase, or move bookmarks. **Creating a JJ workspace invokes native `jj workspace add`, which may snapshot the actual source workspace and change its JJ working-copy commit and Git index intent-to-add entries**; the review notice names that source. Git worktrees keep their separate files, HEAD, and index while sharing refs, objects, remotes, and config. The tool does not force checkout, switch, stash, reset, clean, or prune. A cross-host clone transfers only published Git history from the source origin, not uncommitted files, local-only commits/branches/changes, source credentials, or environment. An explicitly pinned JJ base must be reachable after destination clone or the retained clone requires inspection; omitting a pin uses the clone's native default. Destination credentials and network access must work independently. Shells are not confined to the checkout. Associations live per destination at `${XDG_STATE_HOME:-~/.local/state}/rex-worktrees/associations`; Git/JJ inventory remains authoritative if an association becomes stale.
119
127
 
120
- Local macOS execution is supported. Cross-host worktree execution is experimental; Linux destinations are not yet verified. Each destination requires its own installation and a connected Rex host. Native app navigation requires Rex Remote Control permission. Local endpoints must be Unix endpoints; Windows named pipes are not supported. For a custom local Unix server, set `REX_WORKTREES_LOCAL_ENDPOINT=unix:///absolute/path/server.sock` in the plugin environment.
128
+ The release workflow builds and checks macOS ARM64 and Linux x64 executables in their native CI runners, including Git/JJ integration tests and malformed-request smoke checks. Linux destinations have not been verified against a live remote Rex/JJ setup; cross-host execution and cloning remain experimental. Each execution machine requires a matching Rex Worktrees build (older helper protocols are rejected), its own Git/JJ executables as applicable, and a connected Rex host. Native app navigation requires Rex Remote Control permission. Local endpoints must be Unix endpoints; Windows named pipes are not supported. For a custom local Unix server, set `REX_WORKTREES_LOCAL_ENDPOINT=unix:///absolute/path/server.sock` in the plugin environment.
121
129
 
122
130
  ## Contributing
123
131
 
@@ -1,4 +1,4 @@
1
1
  [diffend] Oversized file quarantined before diffing.
2
2
  name: package/dist/rex-worktrees
3
- size: 64409232 bytes
4
- sha256: 99f1cf022838efb16dc1ebf9aaca5f6171f9d9d1c32a0d347b7041ba910f0d65
3
+ size: 64491792 bytes
4
+ sha256: 5220c32f018d4e838d037d7c364c1cee719591a2b66f42befb8ca827de4388d8