vouchington-tooling 0.70.0 → 0.71.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.
|
|
3
|
+
"version": "0.71.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": {
|
|
Binary file
|
|
@@ -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
|
+
}
|