vouchington-tooling 0.70.0 → 0.72.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
@@ -247,6 +247,21 @@ and `git_worktree_main_path` fails when git reports no worktree. Its
247
247
  `scripts/worktree/git-index-lock.sh` removes only a 0-byte `index.lock`. A non-empty lock is left
248
248
  in place.
249
249
 
250
+ `scripts/worktree/operation-lock.sh` holds a host-wide lock across a region of the sourcing script,
251
+ for code that shares shell state with its surroundings and so cannot run under
252
+ `vouchington with-host-lock`, which wraps one command and forbids nesting. The lock is a symlink
253
+ named `lock` whose target is an owner token; a file with that name holds the owner PID. Pass the
254
+ absolute lock root to each call or set `WORKTREE_OPERATION_LOCK_ROOT`; there is no default.
255
+ `worktree_operation_lock_acquire [root]` takes the lock or prints the holder's PID (or says the
256
+ lock is stale) and returns 1 without waiting. `worktree_operation_lock_release` is a no-op unless
257
+ this shell holds the lock, so `trap worktree_operation_lock_release EXIT` is safe.
258
+ `worktree_operation_lock_clear_stale [root]` removes a lock whose owner PID is dead and sets
259
+ `WORKTREE_OPERATION_LOCK_CLEANUP_STATUS` to `missing`, `removed`, `active`, `invalid` or `busy` (another clearer is running, or the lock
260
+ changed during cleanup); it returns 2 for a missing or relative root, 0 for `missing` and
261
+ `removed`, and 1 otherwise. The root must be owned by the calling user and is meant for one user's
262
+ processes; run `clear_stale` only as operator recovery while no operation is starting, because
263
+ releasing and clearing are not serialized against each other.
264
+
250
265
  `scripts/worktree/reset-worktree.sh --base-ref <ref>` checks out a new `reset-<hex>` branch and
251
266
  hard-resets it to `<ref>`. A `remote/branch` ref is fetched first; `refs/...` and a local ref are
252
267
  not. It refuses uncommitted or untracked changes unless `--force` is set, refuses a non-empty
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vouchington-tooling",
3
- "version": "0.70.0",
3
+ "version": "0.72.0",
4
4
  "description": "Vouchington CLI and extractable tooling libraries.",
5
5
  "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
6
6
  "bugs": {
@@ -0,0 +1,197 @@
1
+ #!/usr/bin/env bash
2
+ # Source this file for a host-wide operation lock held by the sourcing shell.
3
+ #
4
+ # The lock is a symlink named `lock` under a root directory. Its target is an owner token, and a
5
+ # file with that token's name inside the root holds the owner PID. Creating the symlink is atomic,
6
+ # so exactly one process holds the lock. A holder whose PID is gone is stale and can be cleared.
7
+ #
8
+ # Unlike with-host-lock.sh, which wraps one command, these functions protect a region of a
9
+ # sourcing script that shares shell state with the code around it.
10
+ #
11
+ # The root is the first argument, or WORKTREE_OPERATION_LOCK_ROOT. There is no default.
12
+ #
13
+ # Functions:
14
+ # worktree_operation_lock_acquire [root] - take the lock, or print why not and return 1
15
+ # worktree_operation_lock_release - release a lock this shell holds; no-op otherwise
16
+ # worktree_operation_lock_clear_stale [root] - remove a lock whose owner PID is dead
17
+ #
18
+ # Variables set:
19
+ # WORKTREE_OPERATION_LOCK_TOKEN owner token while the lock is held
20
+ # WORKTREE_OPERATION_LOCK_HELD_ROOT root of the lock this shell holds
21
+ # WORKTREE_OPERATION_LOCK_CLEANUP_STATUS after clear_stale: missing, removed, active, invalid or busy
22
+ #
23
+ # Release with a trap, for example: `trap worktree_operation_lock_release EXIT`.
24
+
25
+ _worktree_operation_lock_resolve_root() {
26
+ local root=${1:-${WORKTREE_OPERATION_LOCK_ROOT:-}}
27
+ if [ -z "$root" ]; then
28
+ echo "Error: worktree operation lock root is not set (pass it or set WORKTREE_OPERATION_LOCK_ROOT)." >&2
29
+ return 1
30
+ fi
31
+ case "$root" in
32
+ /*) ;;
33
+ *)
34
+ echo "Error: worktree operation lock root must be an absolute path: $root" >&2
35
+ return 1
36
+ ;;
37
+ esac
38
+ printf '%s' "$root"
39
+ }
40
+
41
+ _worktree_operation_lock_pid_is_live() {
42
+ local error
43
+ [[ "$1" =~ ^[0-9]+$ ]] || return 1
44
+ error=$(export LC_ALL=C; kill -0 "$1" 2>&1) && return 0
45
+ # A live process owned by another user answers "not permitted".
46
+ case "$error" in
47
+ *[Oo]peration*not*permitted* | *[Pp]ermission*denied*) return 0 ;;
48
+ esac
49
+ return 1
50
+ }
51
+
52
+ # Set WORKTREE_OPERATION_LOCK_SELF_PID to the PID of the running (sub)shell. $$ names the
53
+ # top-level shell, and Bash 3.2 has no BASHPID, so a child shell is asked for its parent. This
54
+ # cannot be a command substitution, which would report its own subshell.
55
+ _worktree_operation_lock_set_self_pid() {
56
+ if [ -n "${BASHPID:-}" ]; then
57
+ WORKTREE_OPERATION_LOCK_SELF_PID=$BASHPID
58
+ else
59
+ WORKTREE_OPERATION_LOCK_SELF_PID=$(exec sh -c 'printf %s "$PPID"')
60
+ fi
61
+ }
62
+
63
+ worktree_operation_lock_acquire() {
64
+ local lock_root lock_path token owner_path held_owner_path held_pid held_token self_pid
65
+ _worktree_operation_lock_set_self_pid
66
+ self_pid=$WORKTREE_OPERATION_LOCK_SELF_PID
67
+ if [ -n "${WORKTREE_OPERATION_LOCK_TOKEN:-}" ]; then
68
+ echo "Error: this shell already holds a worktree operation lock: ${WORKTREE_OPERATION_LOCK_HELD_ROOT:-}" >&2
69
+ return 1
70
+ fi
71
+ lock_root=$(_worktree_operation_lock_resolve_root "${1:-}") || return 1
72
+ lock_path="$lock_root/lock"
73
+ token="owner.$self_pid.$RANDOM$RANDOM"
74
+ owner_path="$lock_root/$token"
75
+
76
+ mkdir -p "$lock_root" || return 1
77
+ # Owner files are PID records, so the root must be private to one user: another user's
78
+ # process could not be probed or trusted, and a shared root would let it delete live locks.
79
+ if [ ! -O "$lock_root" ]; then
80
+ echo "Error: worktree operation lock root is not owned by this user: $lock_root" >&2
81
+ return 1
82
+ fi
83
+ if ! printf '%s\n' "$self_pid" >"$owner_path"; then
84
+ rm -f "$owner_path"
85
+ echo "Error: cannot record the worktree operation lock owner: $owner_path" >&2
86
+ return 1
87
+ fi
88
+
89
+ if [ -e "$lock_path" ] && [ ! -L "$lock_path" ]; then
90
+ rm -f "$owner_path"
91
+ echo "Error: worktree operation lock is not a symbolic link: $lock_path" >&2
92
+ return 1
93
+ fi
94
+ if ln -s "$token" "$lock_path" 2>/dev/null; then
95
+ if [ "$(readlink "$lock_path" 2>/dev/null || true)" = "$token" ]; then
96
+ WORKTREE_OPERATION_LOCK_TOKEN=$token
97
+ WORKTREE_OPERATION_LOCK_HELD_ROOT=$lock_root
98
+ return 0
99
+ fi
100
+ # `ln -s` onto a symlink to a directory creates the link inside that directory.
101
+ held_token=$(readlink "$lock_path" 2>/dev/null || true)
102
+ if [[ "$held_token" =~ ^owner\.[0-9]+\.[0-9]+$ ]] \
103
+ && [ -L "$lock_root/$held_token/$token" ] \
104
+ && [ "$(readlink "$lock_root/$held_token/$token")" = "$token" ]; then
105
+ rm -f "$lock_root/$held_token/$token"
106
+ fi
107
+ fi
108
+ if [ ! -L "$lock_path" ]; then
109
+ rm -f "$owner_path"
110
+ echo "Error: worktree operation lock is not a symbolic link: $lock_path" >&2
111
+ return 1
112
+ fi
113
+ held_token=$(readlink "$lock_path")
114
+ if [[ ! "$held_token" =~ ^owner\.[0-9]+\.[0-9]+$ ]]; then
115
+ rm -f "$owner_path"
116
+ echo "Error: worktree operation lock has an invalid owner: $lock_path" >&2
117
+ return 1
118
+ fi
119
+ held_owner_path="$lock_root/$held_token"
120
+ held_pid=$(cat "$held_owner_path" 2>/dev/null || true)
121
+ rm -f "$owner_path"
122
+ if _worktree_operation_lock_pid_is_live "$held_pid"; then
123
+ echo "Error: another worktree operation is running (PID $held_pid)." >&2
124
+ else
125
+ echo "Error: the worktree operation lock is stale; clear it with worktree_operation_lock_clear_stale when no operation is running: $lock_path" >&2
126
+ fi
127
+ return 1
128
+ }
129
+
130
+ worktree_operation_lock_clear_stale() {
131
+ local lock_root lock_path clearing_path clearer_pid status
132
+ WORKTREE_OPERATION_LOCK_CLEANUP_STATUS=missing
133
+ lock_root=$(_worktree_operation_lock_resolve_root "${1:-}") || return 2
134
+ lock_path="$lock_root/lock"
135
+ [ -L "$lock_path" ] || return 0
136
+ # Serialize clearers so one cannot delete a lock another clearer replaced. The mutex is a
137
+ # symlink to the clearer's PID, created atomically, so a clearer that died holding it is
138
+ # recognizable and its mutex is recovered.
139
+ clearing_path="$lock_root/clearing"
140
+ _worktree_operation_lock_set_self_pid
141
+ clearer_pid=$WORKTREE_OPERATION_LOCK_SELF_PID
142
+ if ! ln -s "$clearer_pid" "$clearing_path" 2>/dev/null; then
143
+ status=$(readlink "$clearing_path" 2>/dev/null || true)
144
+ if _worktree_operation_lock_pid_is_live "$status" \
145
+ || [ "$(readlink "$clearing_path" 2>/dev/null || true)" != "$status" ]; then
146
+ WORKTREE_OPERATION_LOCK_CLEANUP_STATUS=busy
147
+ return 1
148
+ fi
149
+ rm -f "$clearing_path"
150
+ if ! ln -s "$clearer_pid" "$clearing_path" 2>/dev/null; then
151
+ WORKTREE_OPERATION_LOCK_CLEANUP_STATUS=busy
152
+ return 1
153
+ fi
154
+ fi
155
+ status=0
156
+ _worktree_operation_lock_clear_locked "$lock_root" || status=$?
157
+ rm -f "$clearing_path"
158
+ return "$status"
159
+ }
160
+
161
+ _worktree_operation_lock_clear_locked() {
162
+ local lock_root=$1 lock_path="$1/lock" held_owner_path held_pid held_token
163
+ [ -L "$lock_path" ] || return 0
164
+ held_token=$(readlink "$lock_path")
165
+ if [[ ! "$held_token" =~ ^owner\.[0-9]+\.[0-9]+$ ]]; then
166
+ WORKTREE_OPERATION_LOCK_CLEANUP_STATUS=invalid
167
+ return 1
168
+ fi
169
+ held_owner_path="$lock_root/$held_token"
170
+ held_pid=$(cat "$held_owner_path" 2>/dev/null || true)
171
+ if _worktree_operation_lock_pid_is_live "$held_pid"; then
172
+ WORKTREE_OPERATION_LOCK_CLEANUP_STATUS=active
173
+ return 1
174
+ fi
175
+ # Another process may have cleared and re-taken the lock since the read above.
176
+ [ "$(readlink "$lock_path" 2>/dev/null || true)" = "$held_token" ] || return 1
177
+ rm -f "$lock_path"
178
+ rm -f "$held_owner_path"
179
+ WORKTREE_OPERATION_LOCK_CLEANUP_STATUS=removed
180
+ }
181
+
182
+ worktree_operation_lock_release() {
183
+ local token=${WORKTREE_OPERATION_LOCK_TOKEN:-}
184
+ local lock_root=${WORKTREE_OPERATION_LOCK_HELD_ROOT:-}
185
+ [ -n "$token" ] && [ -n "$lock_root" ] || return 0
186
+ # A subshell inherits these variables but must not release its parent's lock.
187
+ _worktree_operation_lock_set_self_pid
188
+ case "$token" in
189
+ owner."$WORKTREE_OPERATION_LOCK_SELF_PID".*) ;;
190
+ *) return 0 ;;
191
+ esac
192
+ if [ "$(readlink "$lock_root/lock" 2>/dev/null || true)" = "$token" ]; then
193
+ rm -f "$lock_root/lock"
194
+ fi
195
+ rm -f "$lock_root/$token"
196
+ unset WORKTREE_OPERATION_LOCK_TOKEN WORKTREE_OPERATION_LOCK_HELD_ROOT WORKTREE_OPERATION_LOCK_SELF_PID
197
+ }