rex-worktrees 0.0.0-stage → 0.1.1

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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Samuel Ho
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,157 @@
1
- # Temporary Holding Version
1
+ # Rex Worktrees
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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.
4
+
5
+ ## Install
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.
8
+
9
+ ### npm
10
+
11
+ ```sh
12
+ npm install -g rex-worktrees
13
+ rex-worktrees setup --bin "$(npm root -g)/rex-worktrees/dist/rex-worktrees"
14
+ rex config reload
15
+ ```
16
+
17
+ `--bin` registers the executable in the global npm package rather than copying it, so the path continues to work after package upgrades under the same npm global prefix. After an upgrade, repeat setup and `rex config reload` to update the Rex integration.
18
+
19
+ ### GitHub Releases
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:
22
+
23
+ ```sh
24
+ /absolute/path/to/rex-worktrees setup --bin /absolute/path/to/rex-worktrees
25
+ rex config reload
26
+ ```
27
+
28
+ Keep the executable at that path when replacing it with a newer release, then repeat setup and `rex config reload`. Each release also provides the relinkable application bundle and matching runtime sources described below.
29
+
30
+ ### Build from source
31
+
32
+ Building requires Bun 1.3.13. From a source checkout, run:
33
+
34
+ ```sh
35
+ bun install --frozen-lockfile
36
+ bun run build
37
+ ./dist/rex-worktrees setup
38
+ rex config reload
39
+ ```
40
+
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
+
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.
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.
46
+
47
+ ## Open a worktree
48
+
49
+ Choose **Open Worktree…** in the Rex palette or run:
50
+
51
+ ```sh
52
+ rex do worktrees_open
53
+ ```
54
+
55
+ No keyboard shortcut is installed by default. To add one, put an unused native binding outside the managed section of your Rex config:
56
+
57
+ ```lua
58
+ rex.bind("ctrl+alt+w", "worktrees_open")
59
+ ```
60
+
61
+ For a manual Lua installation, supply an absolute executable path with `require("rex-worktrees").setup({ bin = "/absolute/path/to/rex-worktrees" })`.
62
+
63
+ The chooser has six fields:
64
+
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.
69
+ - **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.
71
+
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.
73
+
74
+ ## Projects and checkout locations
75
+
76
+ Configuration is optional and belongs on the **execution machine** at `${XDG_CONFIG_HOME:-~/.config}/rex-worktrees/config.json`:
77
+
78
+ ```json
79
+ {
80
+ "projects": [
81
+ "/absolute/path/to/project",
82
+ {
83
+ "path": "/absolute/path/to/another-project",
84
+ "worktreeRoot": "/absolute/path/to/another-project-checkouts"
85
+ }
86
+ ],
87
+ "roots": ["/absolute/path/to/projects"],
88
+ "worktreeRoot": "/absolute/path/to/checkouts"
89
+ }
90
+ ```
91
+
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.
93
+
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.
95
+
96
+ ## CLI
97
+
98
+ ```sh
99
+ rex-worktrees popup
100
+ rex-worktrees launch-popup --session session:FULL-ID
101
+ rex-worktrees launch-popup --session session:FULL-ID --host workstation
102
+
103
+ rex-worktrees open --repo /absolute/path/project \
104
+ --branch feature/name --worktree-name feature-task \
105
+ --session session:FULL-ID --name Feature
106
+
107
+ rex-worktrees open --host workstation --repo /destination/path/project \
108
+ --worktree /destination/path/existing-checkout \
109
+ --session session:DESTINATION-ID --name Existing
110
+ ```
111
+
112
+ `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
+
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.
115
+
116
+ ## Safety and limits
117
+
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.
119
+
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.
121
+
122
+ ## Contributing
123
+
124
+ ```sh
125
+ bun install
126
+ bun run check
127
+ bun run test
128
+ bun run build
129
+ ```
130
+
131
+ ## License and runtime sources
132
+
133
+ Project code is [MIT-licensed](LICENSE). The standalone executable embeds Bun; bundled components retain their upstream licenses, reproduced in [the third-party notices](licenses/THIRD-PARTY-NOTICES). Normal use requires no Bun installation or runtime source files.
134
+
135
+ <details>
136
+ <summary>Rebuilding with a modified runtime</summary>
137
+
138
+ Each [release](https://github.com/samuelho-dev/rex-worktrees/releases) includes the application's relinkable `rex-worktrees.js` bundle in the binary archive, plus matching Bun, WebKit/JavaScriptCore, and tinycc source archives. `SHA256SUMS` covers every download.
139
+
140
+ Runtime source revisions are Bun 1.3.13 (`bf2e2cecf27e800962b1e7f03d66278f9d5d2e79`), WebKit (`4d5e75ebd84a14edbc7ae264245dcd77fe597c10`), and tinycc (`12882eee073cfe5c7621bcfadf679e1372d4537b`). Rebuilding requires the toolchain described in [Bun's contributing guide](https://github.com/oven-sh/bun/blob/bun-v1.3.13/CONTRIBUTING.md), including its LLVM requirements.
141
+
142
+ Extract the Bun source and matching library snapshots, make the desired library changes, then rebuild the runtime and application:
143
+
144
+ ```sh
145
+ mkdir -p bun-source/vendor/WebKit bun-source/vendor/tinycc
146
+ tar -xzf bun-1.3.13-source.tar.gz -C bun-source --strip-components 1
147
+ tar -xzf bun-webkit-source.tar.gz -C bun-source/vendor/WebKit --strip-components 1
148
+ tar -xzf bun-tinycc-source.tar.gz -C bun-source/vendor/tinycc --strip-components 1
149
+ cd bun-source
150
+ bun install --frozen-lockfile
151
+ GIT_SHA=bf2e2cecf27e800962b1e7f03d66278f9d5d2e79 bun run build:release:local
152
+ ./build/release-local/bun build /absolute/path/to/rex-worktrees.js \
153
+ --compile --outfile /absolute/path/to/rex-worktrees-relinked
154
+ codesign --force --sign - /absolute/path/to/rex-worktrees-relinked
155
+ ```
156
+
157
+ </details>
@@ -0,0 +1,4 @@
1
+ [diffend] Oversized file quarantined before diffing.
2
+ name: package/dist/rex-worktrees
3
+ size: 64409232 bytes
4
+ sha256: 99f1cf022838efb16dc1ebf9aaca5f6171f9d9d1c32a0d347b7041ba910f0d65