@sassywares/skills 0.10.0 → 0.11.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/CONCEPTS.md +26 -1
- package/README.md +53 -1
- package/package.json +1 -1
- package/skills/sassy-commit/SKILL.md +1 -1
- package/skills/sassy-commit-push-pr/SKILL.md +1 -1
- package/skills/sassy-dogfood/SKILL.md +2 -2
- package/skills/sassy-handoff/SKILL.md +2 -1
- package/skills/sassy-handoff/references/read.md +1 -1
- package/skills/sassy-handoff/references/write.md +1 -1
- package/skills/sassy-scout/SKILL.md +4 -3
- package/skills/sassy-setup/SKILL.md +17 -9
- package/skills/sassy-setup/assets/dogfood-recipe.md +2 -0
- package/skills/sassy-setup/assets/roster +1 -0
- package/skills/sassy-setup/assets/worktree/_lib.sh +269 -0
- package/skills/sassy-setup/assets/worktree/create +104 -0
- package/skills/sassy-setup/assets/worktree/list +78 -0
- package/skills/sassy-setup/assets/worktree/prune +84 -0
- package/skills/sassy-setup/assets/worktree/remove +85 -0
- package/skills/sassy-setup/assets/worktree/stop +61 -0
- package/skills/sassy-setup/references/branching.md +19 -5
- package/skills/sassy-setup/references/config.md +62 -7
- package/skills/sassy-setup/references/dogfood.md +40 -4
- package/skills/sassy-setup/references/harness.md +14 -5
- package/skills/sassy-setup/references/worktree.md +151 -0
- package/skills/sassy-setup/scripts/detect.sh +138 -4
- package/skills/sassy-setup/scripts/hash-skill.mjs +110 -0
- package/skills/sassy-setup/scripts/lockcheck.mjs +26 -37
- package/skills/sassy-worktree/SKILL.md +87 -0
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
# Add a worktree for one branch and claim its port.
|
|
3
|
+
#
|
|
4
|
+
# Idempotent: a branch already in a worktree of ours is reported, not recreated,
|
|
5
|
+
# and nobody else's checkout holding it is a stop rather than a clobber.
|
|
6
|
+
#
|
|
7
|
+
# Usage: .sassywares/worktree/create <branch> [--from <start-point>] [--env]
|
|
8
|
+
# .sassywares/worktree/create --version
|
|
9
|
+
set -euo pipefail
|
|
10
|
+
|
|
11
|
+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
|
12
|
+
# shellcheck source=./_lib.sh
|
|
13
|
+
source "$SCRIPT_DIR/_lib.sh"
|
|
14
|
+
|
|
15
|
+
usage() {
|
|
16
|
+
cat <<'EOF'
|
|
17
|
+
Usage: .sassywares/worktree/create <branch> [--from <start-point>] [--env]
|
|
18
|
+
|
|
19
|
+
Create (or report) the worktree for <branch>, claim its port, and print the
|
|
20
|
+
namespace a run inherits: WT_PATH, WT_BRANCH, WT_SLUG, WT_NAMESPACE, WT_PORT,
|
|
21
|
+
WT_BASE_URL.
|
|
22
|
+
|
|
23
|
+
--from <ref> where a new branch is cut from (default HEAD). A caller that has
|
|
24
|
+
already resolved the base passes it; this script never guesses.
|
|
25
|
+
--env print only `WT_*=<value>` lines, for eval.
|
|
26
|
+
EOF
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
branch=""
|
|
30
|
+
from="HEAD"
|
|
31
|
+
env_only=0
|
|
32
|
+
while [ $# -gt 0 ]; do
|
|
33
|
+
case "$1" in
|
|
34
|
+
-h|--help) usage; exit 0 ;;
|
|
35
|
+
--version) printf '%s\n' "$WT_VERSION"; exit 0 ;;
|
|
36
|
+
--env) env_only=1 ;;
|
|
37
|
+
--from) shift; from="${1:-}"; [ -n "$from" ] || die "--from needs a start point" ;;
|
|
38
|
+
--from=*) from="${1#*=}" ;;
|
|
39
|
+
-*) die "unknown flag: $1 (try --help)" ;;
|
|
40
|
+
*) [ -z "$branch" ] || die "one branch at a time"; branch="$1" ;;
|
|
41
|
+
esac
|
|
42
|
+
shift
|
|
43
|
+
done
|
|
44
|
+
[ -n "$branch" ] || { usage >&2; exit 2; }
|
|
45
|
+
|
|
46
|
+
need_git
|
|
47
|
+
wt_enabled || die "worktrees are off here — set worktrees.enabled: true in .sassywares/config.yaml"
|
|
48
|
+
|
|
49
|
+
slug="$(wt_slug "$branch")"
|
|
50
|
+
path="$(wt_path "$slug")"
|
|
51
|
+
|
|
52
|
+
report() { # $1 path, $2 branch
|
|
53
|
+
local port addr ns
|
|
54
|
+
ns="$(wt_namespace "$slug")"
|
|
55
|
+
port="$(wt_claim "$slug")"
|
|
56
|
+
addr="http://localhost:$port"
|
|
57
|
+
if [ "$env_only" -eq 1 ]; then
|
|
58
|
+
printf 'WT_PATH=%s\nWT_BRANCH=%s\nWT_SLUG=%s\nWT_NAMESPACE=%s\nWT_PORT=%s\nWT_BASE_URL=%s\n' \
|
|
59
|
+
"$1" "$2" "$slug" "$ns" "$port" "$addr"
|
|
60
|
+
return 0
|
|
61
|
+
fi
|
|
62
|
+
ok worktree "$1"
|
|
63
|
+
ok branch "$2"
|
|
64
|
+
ok namespace "$ns"
|
|
65
|
+
ok port "$port"
|
|
66
|
+
ok address "$addr"
|
|
67
|
+
local hooks n
|
|
68
|
+
hooks="$(wt_hook after_create "$2")"
|
|
69
|
+
if [ -z "$hooks" ]; then
|
|
70
|
+
ok hook "hooks.worktree.after_create — none declared"
|
|
71
|
+
else
|
|
72
|
+
while IFS= read -r n; do
|
|
73
|
+
[ -n "$n" ] || continue
|
|
74
|
+
ok hook "after_create → $n (dispatch it, with WT_* above)"
|
|
75
|
+
done <<<"$hooks"
|
|
76
|
+
fi
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
# Already in a worktree of ours: report and stop. This is the second call in a
|
|
80
|
+
# resumed run, and it must not fail.
|
|
81
|
+
existing="$(wt_find "$branch" || true)"
|
|
82
|
+
if [ -n "$existing" ]; then
|
|
83
|
+
epath="${existing%%$'\t'*}"
|
|
84
|
+
if wt_is_main "$epath"; then
|
|
85
|
+
die "'$branch' is checked out in the main checkout — leave it, or switch the main checkout first"
|
|
86
|
+
fi
|
|
87
|
+
report "$epath" "$branch"
|
|
88
|
+
exit 0
|
|
89
|
+
fi
|
|
90
|
+
|
|
91
|
+
if [ -e "$path" ]; then
|
|
92
|
+
die "'$path' exists but no worktree is registered for '$branch' — inspect it, then prune"
|
|
93
|
+
fi
|
|
94
|
+
|
|
95
|
+
(umask 077; mkdir -p "$(wt_home)/ports")
|
|
96
|
+
printf '%s\n' "$MAIN" > "$(wt_home)/.repo"
|
|
97
|
+
|
|
98
|
+
if git show-ref --verify --quiet "refs/heads/$branch"; then
|
|
99
|
+
git worktree add --quiet "$path" "$branch"
|
|
100
|
+
else
|
|
101
|
+
git worktree add --quiet -b "$branch" "$path" "$from"
|
|
102
|
+
fi
|
|
103
|
+
|
|
104
|
+
report "$path" "$branch"
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
# Show every worktree of this repo: branch, path, address, whether anything is
|
|
3
|
+
# listening there, and the last dogfood verdict.
|
|
4
|
+
#
|
|
5
|
+
# Liveness is probed, never read from a pid file — a killed preview leaves no
|
|
6
|
+
# stale entry to believe.
|
|
7
|
+
#
|
|
8
|
+
# Usage: .sassywares/worktree/list [--address <slug>] [--path <slug>] [--version]
|
|
9
|
+
set -euo pipefail
|
|
10
|
+
|
|
11
|
+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
|
12
|
+
# shellcheck source=./_lib.sh
|
|
13
|
+
source "$SCRIPT_DIR/_lib.sh"
|
|
14
|
+
|
|
15
|
+
usage() {
|
|
16
|
+
cat <<'EOF'
|
|
17
|
+
Usage: .sassywares/worktree/list [--address <slug>] [--path <slug>]
|
|
18
|
+
|
|
19
|
+
Print every worktree with its address and last verdict.
|
|
20
|
+
|
|
21
|
+
--address <slug> print only the base URL of one worktree
|
|
22
|
+
--path <slug> print only the path of one worktree (for cd "$(...)")
|
|
23
|
+
EOF
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
want="" kind=""
|
|
27
|
+
while [ $# -gt 0 ]; do
|
|
28
|
+
case "$1" in
|
|
29
|
+
-h|--help) usage; exit 0 ;;
|
|
30
|
+
--version) printf '%s\n' "$WT_VERSION"; exit 0 ;;
|
|
31
|
+
--address|--path) kind="${1#--}"; shift; want="${1:-}"; [ -n "$want" ] || die "$kind needs a slug" ;;
|
|
32
|
+
-*) die "unknown flag: $1 (try --help)" ;;
|
|
33
|
+
*) die "unexpected argument: $1 (try --help)" ;;
|
|
34
|
+
esac
|
|
35
|
+
shift
|
|
36
|
+
done
|
|
37
|
+
|
|
38
|
+
need_git
|
|
39
|
+
|
|
40
|
+
one() { # $1 path, $2 branch
|
|
41
|
+
local p="$1" b="$2" slug port
|
|
42
|
+
slug="$(wt_slug "$b")"
|
|
43
|
+
if wt_is_main "$p"; then
|
|
44
|
+
die "the main checkout has no derived port — it uses whatever the app defaults to"
|
|
45
|
+
fi
|
|
46
|
+
case "$kind" in
|
|
47
|
+
path) printf '%s\n' "$p" ;;
|
|
48
|
+
address)
|
|
49
|
+
port="$(wt_port_for "$slug")"
|
|
50
|
+
printf 'http://localhost:%s\n' "$port"
|
|
51
|
+
;;
|
|
52
|
+
esac
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
if [ -n "$kind" ]; then
|
|
56
|
+
rec="$(wt_require "$want")"
|
|
57
|
+
one "${rec%%$'\t'*}" "${rec##*$'\t'}"
|
|
58
|
+
exit 0
|
|
59
|
+
fi
|
|
60
|
+
|
|
61
|
+
printf ' %-34s %-50s %-22s %-5s %s\n' "BRANCH" "WORKTREE" "ADDRESS" "LIVE" "LAST RUN"
|
|
62
|
+
count=0
|
|
63
|
+
while IFS=$'\t' read -r p b; do
|
|
64
|
+
[ -n "$p" ] || continue
|
|
65
|
+
count=$(( count + 1 ))
|
|
66
|
+
slug="$(wt_slug "$b")"
|
|
67
|
+
shown="${p/#$HOME/~}"
|
|
68
|
+
if wt_is_main "$p"; then
|
|
69
|
+
printf ' %-34s %-50s %-22s %-5s %s\n' "$b (main checkout)" "$shown" "—" "—" "—"
|
|
70
|
+
continue
|
|
71
|
+
fi
|
|
72
|
+
port="$(wt_port_for "$slug")"
|
|
73
|
+
if tcp_up "$port"; then live="up"; else live="down"; fi
|
|
74
|
+
last="$(wt_verdict "$p")"
|
|
75
|
+
printf ' %-34s %-50s %-22s %-5s %s\n' "$b" "$shown" "http://localhost:$port" "$live" "${last:-—}"
|
|
76
|
+
done < <(wt_all)
|
|
77
|
+
|
|
78
|
+
[ "$count" -gt 0 ] || log " no checkouts found — is this a git repository?"
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
# List worktrees whose work is already safely on a remote, and remove the ones
|
|
3
|
+
# you approve. This is the mode that keeps the worktree home from becoming tens
|
|
4
|
+
# of gigabytes.
|
|
5
|
+
#
|
|
6
|
+
# Only merged-or-gone branches that are clean, fully pushed, and not running are
|
|
7
|
+
# ever candidates. Nothing is removed without --yes.
|
|
8
|
+
#
|
|
9
|
+
# Usage: .sassywares/worktree/prune [--yes] [--version]
|
|
10
|
+
set -euo pipefail
|
|
11
|
+
|
|
12
|
+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
|
13
|
+
# shellcheck source=./_lib.sh
|
|
14
|
+
source "$SCRIPT_DIR/_lib.sh"
|
|
15
|
+
|
|
16
|
+
usage() {
|
|
17
|
+
cat <<'EOF'
|
|
18
|
+
Usage: .sassywares/worktree/prune [--yes]
|
|
19
|
+
|
|
20
|
+
Show every worktree that is merged into its upstream (or whose upstream is gone)
|
|
21
|
+
and safe to remove, then — with --yes — remove those and release their ports.
|
|
22
|
+
EOF
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
yes=0
|
|
26
|
+
while [ $# -gt 0 ]; do
|
|
27
|
+
case "$1" in
|
|
28
|
+
-h|--help) usage; exit 0 ;;
|
|
29
|
+
--version) printf '%s\n' "$WT_VERSION"; exit 0 ;;
|
|
30
|
+
--yes) yes=1 ;;
|
|
31
|
+
-*) die "unknown flag: $1 (try --help)" ;;
|
|
32
|
+
*) die "unexpected argument: $1 (try --help)" ;;
|
|
33
|
+
esac
|
|
34
|
+
shift
|
|
35
|
+
done
|
|
36
|
+
|
|
37
|
+
need_git
|
|
38
|
+
|
|
39
|
+
printf ' %-32s %-9s %-6s %-9s %s\n' "BRANCH" "UPSTREAM" "DIRTY" "UNPUSHED" "ACTION"
|
|
40
|
+
n_candidates=0
|
|
41
|
+
n_removed=0
|
|
42
|
+
while IFS=$'\t' read -r p b; do
|
|
43
|
+
[ -n "$p" ] || continue
|
|
44
|
+
wt_is_main "$p" && continue
|
|
45
|
+
slug="$(wt_slug "$b")"
|
|
46
|
+
state="$(wt_upstream_state "$p")"
|
|
47
|
+
if wt_dirty "$p"; then dirty="yes"; else dirty="no"; fi
|
|
48
|
+
unpushed="$(wt_unpushed "$p")"
|
|
49
|
+
port="$(wt_port_for "$slug")"
|
|
50
|
+
if tcp_up "$port"; then live="yes"; else live="no"; fi
|
|
51
|
+
|
|
52
|
+
action=""
|
|
53
|
+
if [ "$state" = "unmerged" ]; then
|
|
54
|
+
action="skipped — unmerged"
|
|
55
|
+
elif [ "$dirty" = "yes" ]; then
|
|
56
|
+
action="skipped — dirty"
|
|
57
|
+
elif [ "$unpushed" != "0" ]; then
|
|
58
|
+
action="skipped — $unpushed unpushed"
|
|
59
|
+
elif [ "$live" = "yes" ]; then
|
|
60
|
+
action="skipped — running on :$port"
|
|
61
|
+
else
|
|
62
|
+
action="removable"
|
|
63
|
+
n_candidates=$(( n_candidates + 1 ))
|
|
64
|
+
fi
|
|
65
|
+
|
|
66
|
+
printf ' %-32s %-9s %-6s %-9s %s\n' "$b" "$state" "$dirty" "$unpushed" "$action"
|
|
67
|
+
|
|
68
|
+
if [ "$yes" -eq 1 ] && [ "$action" = "removable" ]; then
|
|
69
|
+
hooks="$(wt_hook before_remove "$b")"
|
|
70
|
+
if [ -n "$hooks" ]; then
|
|
71
|
+
warn skipped "$b has a before_remove hook — run remove <$slug> so it runs"
|
|
72
|
+
continue
|
|
73
|
+
fi
|
|
74
|
+
git worktree remove "$p" && wt_release "$port" "$slug" && n_removed=$(( n_removed + 1 ))
|
|
75
|
+
fi
|
|
76
|
+
done < <(wt_all)
|
|
77
|
+
|
|
78
|
+
if [ "$yes" -eq 1 ]; then
|
|
79
|
+
ok pruned "$n_removed removed, $(( n_candidates - n_removed )) left"
|
|
80
|
+
elif [ "$n_candidates" -gt 0 ]; then
|
|
81
|
+
hint "re-run with --yes to remove the $n_candidates removable worktree(s)"
|
|
82
|
+
else
|
|
83
|
+
ok pruned "nothing to remove"
|
|
84
|
+
fi
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
# Remove a worktree, after proving nothing would be lost.
|
|
3
|
+
#
|
|
4
|
+
# Refuses: the main checkout, a dirty tree, commits that are on no remote, and a
|
|
5
|
+
# preview that is still running. A declared `hooks.worktree.before_remove` runs
|
|
6
|
+
# first — the script cannot dispatch a skill, so it fails closed until the caller
|
|
7
|
+
# says the hook has been dispatched.
|
|
8
|
+
#
|
|
9
|
+
# Usage: .sassywares/worktree/remove <slug|branch> [--hook-ok] [--force]
|
|
10
|
+
# .sassywares/worktree/remove --version
|
|
11
|
+
set -euo pipefail
|
|
12
|
+
|
|
13
|
+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
|
14
|
+
# shellcheck source=./_lib.sh
|
|
15
|
+
source "$SCRIPT_DIR/_lib.sh"
|
|
16
|
+
|
|
17
|
+
usage() {
|
|
18
|
+
cat <<'EOF'
|
|
19
|
+
Usage: .sassywares/worktree/remove <slug|branch> [--hook-ok] [--force]
|
|
20
|
+
|
|
21
|
+
--hook-ok the project's hooks.worktree.before_remove has already been
|
|
22
|
+
dispatched — required when one is declared (exit 3 otherwise)
|
|
23
|
+
--force skip the dirty-tree and unpushed-commit refusals. Never skips the
|
|
24
|
+
main checkout, the preview check, or the hook handshake.
|
|
25
|
+
EOF
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
target=""
|
|
29
|
+
hook_ok=0
|
|
30
|
+
force=0
|
|
31
|
+
while [ $# -gt 0 ]; do
|
|
32
|
+
case "$1" in
|
|
33
|
+
-h|--help) usage; exit 0 ;;
|
|
34
|
+
--version) printf '%s\n' "$WT_VERSION"; exit 0 ;;
|
|
35
|
+
--hook-ok) hook_ok=1 ;;
|
|
36
|
+
--force) force=1 ;;
|
|
37
|
+
-*) die "unknown flag: $1 (try --help)" ;;
|
|
38
|
+
*) [ -z "$target" ] || die "one worktree at a time"; target="$1" ;;
|
|
39
|
+
esac
|
|
40
|
+
shift
|
|
41
|
+
done
|
|
42
|
+
[ -n "$target" ] || { usage >&2; exit 2; }
|
|
43
|
+
|
|
44
|
+
need_git
|
|
45
|
+
rec="$(wt_require "$target")"
|
|
46
|
+
path="${rec%%$'\t'*}"
|
|
47
|
+
branch="${rec##*$'\t'}"
|
|
48
|
+
slug="$(wt_slug "$branch")"
|
|
49
|
+
|
|
50
|
+
wt_is_main "$path" && die "that is the main checkout — it cannot be removed"
|
|
51
|
+
|
|
52
|
+
hooks="$(wt_hook before_remove "$branch")"
|
|
53
|
+
if [ -n "$hooks" ] && [ "$hook_ok" -eq 0 ]; then
|
|
54
|
+
while IFS= read -r n; do
|
|
55
|
+
[ -n "$n" ] || continue
|
|
56
|
+
log "require-hook $n"
|
|
57
|
+
done <<<"$hooks"
|
|
58
|
+
printf ' %-9s %s\n' "→" "dispatch it, then re-run with --hook-ok" >&2
|
|
59
|
+
exit 3
|
|
60
|
+
fi
|
|
61
|
+
|
|
62
|
+
port="$(wt_port_for "$slug")"
|
|
63
|
+
if tcp_up "$port"; then
|
|
64
|
+
die "something is still listening on :$port — stop <$slug> first"
|
|
65
|
+
fi
|
|
66
|
+
|
|
67
|
+
if [ "$force" -eq 0 ]; then
|
|
68
|
+
wt_dirty "$path" && die "not clean — $(git -C "$path" status --porcelain | wc -l | tr -d ' ') path(s) modified. Commit, discard, or --force."
|
|
69
|
+
n="$(wt_unpushed "$path")"
|
|
70
|
+
case "$n" in
|
|
71
|
+
0) ;;
|
|
72
|
+
unknown) die "cannot tell whether this branch is pushed — inspect it, or --force" ;;
|
|
73
|
+
*) die "$n commit(s) on '$branch' are on no remote — push, or --force" ;;
|
|
74
|
+
esac
|
|
75
|
+
fi
|
|
76
|
+
|
|
77
|
+
if [ "$force" -eq 1 ]; then
|
|
78
|
+
git worktree remove --force "$path"
|
|
79
|
+
else
|
|
80
|
+
git worktree remove "$path"
|
|
81
|
+
fi
|
|
82
|
+
wt_release "$port" "$slug"
|
|
83
|
+
|
|
84
|
+
ok released ":$port"
|
|
85
|
+
ok removed "$path"
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
# Stop whatever is listening on a worktree's port.
|
|
3
|
+
#
|
|
4
|
+
# By port, not by pid file: a preview that already died leaves nothing to
|
|
5
|
+
# believe, and a port that answers is the only proof that something is running.
|
|
6
|
+
#
|
|
7
|
+
# Usage: .sassywares/worktree/stop <slug|branch> [--version]
|
|
8
|
+
set -euo pipefail
|
|
9
|
+
|
|
10
|
+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
|
11
|
+
# shellcheck source=./_lib.sh
|
|
12
|
+
source "$SCRIPT_DIR/_lib.sh"
|
|
13
|
+
|
|
14
|
+
usage() {
|
|
15
|
+
cat <<'EOF'
|
|
16
|
+
Usage: .sassywares/worktree/stop <slug|branch>
|
|
17
|
+
|
|
18
|
+
Kill the processes listening on that worktree's port. Nothing listening is a
|
|
19
|
+
success with a note, so stopping twice is safe.
|
|
20
|
+
EOF
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
case "${1:-}" in
|
|
24
|
+
-h|--help) usage; exit 0 ;;
|
|
25
|
+
--version) printf '%s\n' "$WT_VERSION"; exit 0 ;;
|
|
26
|
+
"") usage >&2; exit 2 ;;
|
|
27
|
+
esac
|
|
28
|
+
|
|
29
|
+
need_git
|
|
30
|
+
rec="$(wt_require "$1")"
|
|
31
|
+
path="${rec%%$'\t'*}"
|
|
32
|
+
branch="${rec##*$'\t'}"
|
|
33
|
+
slug="$(wt_slug "$branch")"
|
|
34
|
+
|
|
35
|
+
wt_is_main "$path" && die "the main checkout has no derived port to stop"
|
|
36
|
+
port="$(wt_port_for "$slug")"
|
|
37
|
+
|
|
38
|
+
if ! tcp_up "$port"; then
|
|
39
|
+
ok status "nothing listening on :$port"
|
|
40
|
+
exit 0
|
|
41
|
+
fi
|
|
42
|
+
|
|
43
|
+
command -v lsof >/dev/null 2>&1 || die "lsof not found — stop the process on :$port yourself"
|
|
44
|
+
|
|
45
|
+
pids="$(lsof -ti "tcp:$port" 2>/dev/null | tr '\n' ' ' || true)"
|
|
46
|
+
[ -n "$pids" ] || die "something answers on :$port but lsof cannot name it — is it yours?"
|
|
47
|
+
|
|
48
|
+
n="$(printf '%s' "$pids" | wc -w | tr -d ' ')"
|
|
49
|
+
kill -TERM $pids 2>/dev/null || true
|
|
50
|
+
for _ in 1 2 3 4 5; do
|
|
51
|
+
sleep 1
|
|
52
|
+
tcp_up "$port" || break
|
|
53
|
+
done
|
|
54
|
+
if tcp_up "$port"; then
|
|
55
|
+
kill -KILL $pids 2>/dev/null || true
|
|
56
|
+
sleep 1
|
|
57
|
+
tcp_up "$port" && die ":$port still answers after SIGKILL (pids: $pids)"
|
|
58
|
+
ok stopped "$n process(es) on :$port (SIGKILL)"
|
|
59
|
+
else
|
|
60
|
+
ok stopped "$n process(es) on :$port"
|
|
61
|
+
fi
|
|
@@ -77,16 +77,30 @@ config. This applies to every token these skills forward, not just `branch`.
|
|
|
77
77
|
"release" is not a neutral name.
|
|
78
78
|
5. If the name already exists: reuse it when it descends from `start-point`;
|
|
79
79
|
stop and ask when it has diverged.
|
|
80
|
-
6.
|
|
81
|
-
|
|
82
|
-
|
|
80
|
+
6. **Create the branch — in a worktree when the project asked for one.**
|
|
81
|
+
With `worktrees.enabled: true` (per `worktree.md`), run the `sassy-worktree`
|
|
82
|
+
skill's `create` for this run instead of checking out in place: it cuts the
|
|
83
|
+
branch and the checkout together, so the branch can never be held twice, and
|
|
84
|
+
it prints the `WT_*` namespace the run inherits. Two things follow, and both
|
|
85
|
+
are the orchestrator's to carry:
|
|
86
|
+
- **Every step from here on works in `WT_PATH`,** and every delegated brief
|
|
87
|
+
names that absolute path. The main checkout is read-only for the rest of the
|
|
88
|
+
run — config, listing, nothing else.
|
|
89
|
+
- **A dirty tree does not come along,** unlike a checkout: the worktree starts
|
|
90
|
+
clean from `start-point`. Say in the gate summary that uncommitted work stays
|
|
91
|
+
behind, because that is a change in what a run means.
|
|
92
|
+
Otherwise `git checkout -b <name> <start-point>` here, and uncommitted work
|
|
93
|
+
comes along — say so in the gate summary if the tree was dirty.
|
|
94
|
+
7. Report the branch, the start point, `pr-base`, and the checkout it landed in.
|
|
83
95
|
|
|
84
96
|
### `reuse`
|
|
85
97
|
|
|
86
|
-
Report `head` and carry on. Do **not** re-cut because
|
|
98
|
+
Report `head` and the checkout you are in, and carry on. Do **not** re-cut because
|
|
99
|
+
`commit.branch` is `new`:
|
|
87
100
|
a second phase, a resumed run, or a handed-off session is already standing on
|
|
88
101
|
the branch the first one cut. That is the whole reason this is inferred rather
|
|
89
|
-
than forced.
|
|
102
|
+
than forced. It is also what keeps a run inside its own worktree: it finds itself
|
|
103
|
+
on a non-base branch and reuses it rather than nesting another checkout.
|
|
90
104
|
|
|
91
105
|
### `commit-here`
|
|
92
106
|
|
|
@@ -79,6 +79,14 @@ hooks:
|
|
|
79
79
|
push:
|
|
80
80
|
"*":
|
|
81
81
|
after_push: [] # commit.branch: current only
|
|
82
|
+
# worktree: # worktrees only; keyed by the checkout's branch
|
|
83
|
+
# "*":
|
|
84
|
+
# after_create: [] # derive .env, seed, copy the session
|
|
85
|
+
# before_remove: [] # drop the database, shut the device
|
|
86
|
+
worktrees:
|
|
87
|
+
enabled: false # true = a run may work in its own checkout
|
|
88
|
+
dir: ~/.sassywares/worktrees # parent of the per-repo folder; ~ is allowed here
|
|
89
|
+
ports: 3000-3099 # the range a checkout claims a port from
|
|
82
90
|
dogfood:
|
|
83
91
|
enabled: false # true = sassy-plan writes Mode: Auto QA rows
|
|
84
92
|
recipe: .sassywares/dogfood/recipe.md # the procedure
|
|
@@ -109,6 +117,9 @@ dogfood:
|
|
|
109
117
|
| `dogfood.recipe` | `.sassywares/dogfood/recipe.md` | The stored procedure `sassy-dogfood` executes. Its `Prove it:` step is the verdict |
|
|
110
118
|
| `dogfood.reports` | `.sassywares/dogfood/reports` | Where a run writes its summary, step logs, and artifacts. Must be gitignored |
|
|
111
119
|
| `dogfood.timeout` | `900` | Wall-clock for one run. A timeout is a failure, never a hang |
|
|
120
|
+
| `worktrees.enabled` | `false` | `true` lets a run work in its own checkout instead of this one. Needs `commit.branch: new` |
|
|
121
|
+
| `worktrees.dir` | `~/.sassywares/worktrees` | Parent of the per-repo worktree folder. The one path here that may be absolute or `~/` |
|
|
122
|
+
| `worktrees.ports` | `3000-3099` | The range a checkout claims its private port from |
|
|
112
123
|
|
|
113
124
|
Paths are relative to the config's own directory, never to the cwd.
|
|
114
125
|
|
|
@@ -302,6 +313,13 @@ targets. `hooks.pr.staging` means *PRs whose source is staging*.
|
|
|
302
313
|
| `before_merge` | `sassy-babysit` | the PR looks ready **and** this run will merge it |
|
|
303
314
|
| `after_merge` | `sassy-babysit` | this run observed the PR merged |
|
|
304
315
|
| `hooks.push.after_push` | `sassy-ship` | right after a successful push under `commit.branch: current` |
|
|
316
|
+
| `hooks.worktree.after_create` | `sassy-worktree` | just after a checkout exists, before anyone works in it |
|
|
317
|
+
| `hooks.worktree.before_remove` | `sassy-worktree` | before the checkout is deleted — drop its database, shut its device |
|
|
318
|
+
|
|
319
|
+
`hooks.worktree` has the same shape and resolution as the other two kinds, keyed
|
|
320
|
+
by the head branch the checkout holds. It needs `worktrees.enabled`; a shell
|
|
321
|
+
script cannot dispatch a skill, so `worktree:remove` fails closed (exit `3`,
|
|
322
|
+
`require-hook <name>`) until the caller has run it.
|
|
305
323
|
|
|
306
324
|
`hooks.push` has the same shape and resolution as `hooks.pr`, but its key is the
|
|
307
325
|
pushed head branch and its only point is `after_push`. It runs only under
|
|
@@ -376,6 +394,34 @@ partial failures explicitly. Never collapse it into one status.
|
|
|
376
394
|
fan-out means one `sassy-babysit` run per PR; merging a fan-out needs an explicit
|
|
377
395
|
per-PR say-so, because one switch would merge N PRs nobody re-read.
|
|
378
396
|
|
|
397
|
+
## Worktrees
|
|
398
|
+
|
|
399
|
+
Parallel work in one repo: a checkout per branch, each with its own derived
|
|
400
|
+
namespace and port, so two runs never fight over a working tree.
|
|
401
|
+
|
|
402
|
+
```yaml
|
|
403
|
+
worktrees:
|
|
404
|
+
enabled: true
|
|
405
|
+
dir: ~/.sassywares/worktrees
|
|
406
|
+
ports: 3000-3099
|
|
407
|
+
```
|
|
408
|
+
|
|
409
|
+
Three keys, no commands. The scripts in `.sassywares/worktree/` own the
|
|
410
|
+
mechanics and `sassy-worktree` orchestrates them. `dir` is the one path in this
|
|
411
|
+
file that may be absolute or start with `~/` — it names machine-local state, not
|
|
412
|
+
something a teammate clones.
|
|
413
|
+
|
|
414
|
+
**Two conditions.**
|
|
415
|
+
|
|
416
|
+
- `enabled: true` needs `commit.branch: new`. Under `current` a run commits where
|
|
417
|
+
it stands and never cuts a branch, so nothing would ever create a worktree;
|
|
418
|
+
`--check` says so rather than leaving a switch that does nothing.
|
|
419
|
+
- It needs the `repo` topology. A `workspace` root and a `none` folder have no
|
|
420
|
+
git to cut a checkout from.
|
|
421
|
+
|
|
422
|
+
The namespace, the port claim, the two hooks, and every refusal are in
|
|
423
|
+
[`worktree.md`](worktree.md).
|
|
424
|
+
|
|
379
425
|
## Dogfood
|
|
380
426
|
|
|
381
427
|
Agent QA: a stored procedure that proves a change works in the running product,
|
|
@@ -422,9 +468,15 @@ report layout, the verdict classes, and the lint are in
|
|
|
422
468
|
- `git.repo` is `workspace`, `none`, or one existing remote name.
|
|
423
469
|
- `git.remote` is required when `git.repo: workspace`; forbidden otherwise.
|
|
424
470
|
`git.mirror_branch` and `repos` are workspace-only too.
|
|
425
|
-
- `hooks` is allowed only with the four
|
|
426
|
-
under `hooks.push`,
|
|
427
|
-
`.agents/skills/<name>/SKILL.md`.
|
|
471
|
+
- `hooks` is allowed only with the four points under `hooks.pr`, `after_push`
|
|
472
|
+
under `hooks.push`, and `after_create`/`before_remove` under `hooks.worktree`,
|
|
473
|
+
each a list of skill names that resolve to `.agents/skills/<name>/SKILL.md`.
|
|
474
|
+
- `worktrees.enabled` is `true` or `false`; `worktrees.ports` is `<from>-<to>`
|
|
475
|
+
inside 1–65535 with `<from>` no greater than `<to>`. A checkout must resolve
|
|
476
|
+
outside the working tree, must not hold a branch `base_map` names as a base,
|
|
477
|
+
and must not leave a port claimed by a worktree that no longer exists. An
|
|
478
|
+
`enabled: true` with no tooling installed, or with the wrong tooling version,
|
|
479
|
+
is drift.
|
|
428
480
|
- `commit.branch` is `current` or `new`; `pr.*` are `true` or `false`. Write
|
|
429
481
|
booleans as `true`/`false`, never `on`/`off` — bare `on`/`off` are YAML 1.1
|
|
430
482
|
booleans and parse inconsistently.
|
|
@@ -444,7 +496,10 @@ a `drift:` line, exiting non-zero. When the suite is installed in project
|
|
|
444
496
|
scope it also verifies the vendored pin offline: every `.agents/skills/<name>` folder whose name is a suite skill (a name in the suite's roster, `assets/roster` in sassy-setup, not merely `sassy-`-prefixed) is hashed with the `skills` CLI's own
|
|
445
497
|
definition and compared to `computedHash` in `skills-lock.json`, the lock is
|
|
446
498
|
checked against the installed set in both directions, and git-tracked state of
|
|
447
|
-
the lock is reported.
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
499
|
+
the lock is reported. Both lock eras count: the definition named by the lock's
|
|
500
|
+
`version` is tried first and the other second, so a pin written by an older
|
|
501
|
+
`skills` CLI reads as a match (with a note) rather than as drift — the
|
|
502
|
+
`skills` CLI changed its folder hash and still reads both. A stale, hand-edited,
|
|
503
|
+
or half-installed suite is drift even when the config itself matches the tree. A
|
|
504
|
+
user-scope install (`~/.agents/skills/`) has no pin to verify; the check notes
|
|
505
|
+
it, and a suite found in neither scope is noted, not drift.
|
|
@@ -48,13 +48,14 @@ promise that a check exists: an unfinished recipe degrades to Manual rows
|
|
|
48
48
|
```text
|
|
49
49
|
.sassywares/
|
|
50
50
|
├── config.yaml
|
|
51
|
+
├── .gitignore /session/ and /dogfood/reports/ — setup-owned
|
|
52
|
+
├── session/ cookie jar, storage state, token — shared, never committed
|
|
51
53
|
└── dogfood/
|
|
52
54
|
├── recipe.md the procedure — committed, reviewed like code
|
|
53
|
-
├── .gitignore one line: /reports/
|
|
54
55
|
└── reports/ run output — never committed
|
|
55
56
|
```
|
|
56
57
|
|
|
57
|
-
The
|
|
58
|
+
The two ignore lines are setup-owned. `--check` reports it missing as drift,
|
|
58
59
|
because a project that "helpfully" removes it commits screenshots by accident.
|
|
59
60
|
|
|
60
61
|
## Recipe format
|
|
@@ -69,6 +70,8 @@ copy `.env.example` → `.env` and fill `DOGFOOD_USER`, `DOGFOOD_PASS`.
|
|
|
69
70
|
|
|
70
71
|
**Reset:** `bun run db:reset`; `rm -rf .sassywares/dogfood/reports/*`
|
|
71
72
|
|
|
73
|
+
**Preview:** `bun dev --port $PORT`, then open `$BASE_URL`
|
|
74
|
+
|
|
72
75
|
## catalog — a search returns matching products
|
|
73
76
|
|
|
74
77
|
1. **Do** `bun run db:seed -- --fixtures catalog-small`
|
|
@@ -102,6 +105,11 @@ why the recipe outlives whatever tool the agent happens to have this quarter.
|
|
|
102
105
|
it set up state and assert along the way; the prove step is the machine-readable
|
|
103
106
|
answer. A section without one has no verdict.
|
|
104
107
|
|
|
108
|
+
**One `**Preview:**` line**, optional: how a human sees this checkout running. A
|
|
109
|
+
URL, a simulator name, a desktop app — whatever `sassy-worktree mode:preview`
|
|
110
|
+
should print once the app is up. Without one, the address is `$WT_BASE_URL`. It
|
|
111
|
+
is prose, like every other line here: no tool, no schema.
|
|
112
|
+
|
|
105
113
|
**Rules.**
|
|
106
114
|
|
|
107
115
|
- Ordered, numbered, **append-only**: add steps at the end of their section;
|
|
@@ -117,6 +125,31 @@ answer. A section without one has no verdict.
|
|
|
117
125
|
- **No tool names.** Never "use Playwright" or "use the Chrome MCP". Say what to
|
|
118
126
|
do and what to see, and let the run discover how.
|
|
119
127
|
|
|
128
|
+
## Sessions, and a second checkout
|
|
129
|
+
|
|
130
|
+
Authentication is the one thing that cannot be standardized: a cookie jar, a
|
|
131
|
+
storage-state file, a bearer token, a client certificate, a device-code flow —
|
|
132
|
+
each project is different, and the mechanism is *discovered* rather than
|
|
133
|
+
configured. Two things follow, and they are all this file says about it:
|
|
134
|
+
|
|
135
|
+
- **Session material lives in `.sassywares/session/`**, gitignored with the same
|
|
136
|
+
setup-owned file as the reports. The suite never inspects what is in there. A
|
|
137
|
+
step that needs a credential names an env var or points at that directory and
|
|
138
|
+
never carries a value.
|
|
139
|
+
- **The procedure says how it is obtained and used** — in *Set up once*, in
|
|
140
|
+
`**Preview:**`, or in a plain section of its own. `mode:discover` writes it
|
|
141
|
+
once, after finding out what actually works, and `mode:run` or
|
|
142
|
+
`mode:preview` stops with an env-class report when the session is missing
|
|
143
|
+
rather than retrying against a login page.
|
|
144
|
+
|
|
145
|
+
A worktree gets a fresh, empty `session/`. When a project's provider registers a
|
|
146
|
+
single callback URL, a second checkout usually cannot log in on its own, so the
|
|
147
|
+
usual answer is to copy or link the main checkout's session in the
|
|
148
|
+
`after_create` hook. Worth writing down, because a **cookie** is host-scoped and
|
|
149
|
+
crosses ports freely while a **`localStorage`** session is origin-scoped, port
|
|
150
|
+
included, and has to be injected per origin — the difference looks like a broken
|
|
151
|
+
transplant when it is only the wrong mechanism.
|
|
152
|
+
|
|
120
153
|
## Reports
|
|
121
154
|
|
|
122
155
|
```text
|
|
@@ -188,7 +221,8 @@ lying switch.
|
|
|
188
221
|
|----------|-------|
|
|
189
222
|
| `dogfood:` block in the config | `sassy-setup` — the only skill that writes the config |
|
|
190
223
|
| `.sassywares/dogfood/recipe.md` | `sassy-dogfood` (`mode:discover` authors and repairs it; a `mode:run` never edits it to pass) |
|
|
191
|
-
| `.sassywares
|
|
224
|
+
| `.sassywares/.gitignore` | `sassy-setup`; never removes a line |
|
|
225
|
+
| `.sassywares/session/` contents | the project — obtained and written by its own step or hook, never by this skill |
|
|
192
226
|
| `reports/` | `sassy-dogfood`, always gitignored, pruned to ten |
|
|
193
227
|
| `Mode: Auto` QA rows | `sassy-plan`, a section name per row |
|
|
194
228
|
| Row results | `sassy-work`, from a passing report — never from an opinion |
|
|
@@ -202,7 +236,9 @@ Structural, never executed:
|
|
|
202
236
|
- `recipe` exists when `enabled` is `true` — absent, it is "created by the first
|
|
203
237
|
`sassy-dogfood` run", a note rather than drift.
|
|
204
238
|
- `reports` is gitignored in a `repo` topology (`git check-ignore`), since a run
|
|
205
|
-
once committed would be drift nobody catches later.
|
|
239
|
+
once committed would be drift nobody catches later. The same check covers
|
|
240
|
+
`.sassywares/session` whenever that directory exists — a committed session is a
|
|
241
|
+
credential leak, not a heavy history.
|
|
206
242
|
- The recipe has at least one `## ` section, every section has a `**Prove it:**`
|
|
207
243
|
line, every numbered step has an `**Expect**`, and the file carries no
|
|
208
244
|
secret-shaped strings.
|