@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
|
@@ -30,13 +30,12 @@ For any other harness, give the skill name and its arguments and let the user in
|
|
|
30
30
|
|
|
31
31
|
## Temp files
|
|
32
32
|
|
|
33
|
-
Every file a skill or agent writes outside the repo goes under **`/tmp/sassywares/<
|
|
33
|
+
Every file a skill or agent writes outside the repo goes under **`/tmp/sassywares/<purpose>/`** — never loose in `/tmp`, never inside the working tree. One folder per purpose, shared by every harness: a handoff written in one harness has to be findable from another, which is the whole point of the file.
|
|
34
34
|
|
|
35
35
|
```bash
|
|
36
36
|
SW=/tmp/sassywares
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
for d in "$SW" "$SW/$HARNESS" "$DIR"; do [ -L "$d" ] && { echo "unsafe symlink: $d" >&2; exit 1; }; done
|
|
37
|
+
DIR="$SW/<purpose>"
|
|
38
|
+
[ -L "$SW" ] && { echo "unsafe symlink: $SW" >&2; exit 1; }
|
|
40
39
|
(umask 077; mkdir -p "$DIR")
|
|
41
40
|
[ -O "$SW" ] || { echo "not owned by you: $SW" >&2; exit 1; }
|
|
42
41
|
```
|
|
@@ -49,4 +48,14 @@ for d in "$SW" "$SW/$HARNESS" "$DIR"; do [ -L "$d" ] && { echo "unsafe symlink:
|
|
|
49
48
|
| PR bodies | `prs/` | `sassy-commit-push-pr` |
|
|
50
49
|
| Anything else — clones, captured output, drafts | `scratch/` | any skill or agent |
|
|
51
50
|
|
|
52
|
-
Name files so a run can find its own: a UTC timestamp
|
|
51
|
+
Name files so a run can find its own: a UTC timestamp, a short slug, and a short random suffix (`20261027T101500Z-fix-checkout-4f2a.txt`). The suffix keeps two harnesses writing in the same second apart, now that they share a folder. A clone or any temporary tree gets its own `mktemp -d` under `scratch/` for the same reason. Delete scratch you no longer need; `/tmp` clearing on reboot covers the rest. A new purpose gets a new row here, not a new top-level folder.
|
|
52
|
+
|
|
53
|
+
**Harness is not a path segment.** It is recorded inside the file where it still matters — a handoff carries `**Harness:**` so a reader knows which agent wrote it — and the resume command is generated for whoever is reading, not for the writer. When a file needs it:
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
HARNESS="${SASSY_HARNESS:-$(if [ -n "${CLAUDECODE:-}" ]; then echo claude; elif [ -n "${PI_CODING_AGENT:-}" ]; then echo pi; else echo other; fi)}"
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## Durable state
|
|
60
|
+
|
|
61
|
+
`/tmp` is for files a run produces and forgets. Anything that must survive a reboot lives under **`~/.sassywares/<purpose>/`**: today that is `worktrees/`, whose checkouts carry uncommitted work (see `worktree.md`). Never put working state under `/tmp`, and never bury durable state inside a checkout — `/tmp` clearing is harmless for a handoff and fatal for a worktree.
|
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
# Worktrees
|
|
2
|
+
|
|
3
|
+
Parallel work in one repo: each run gets its own checkout, its own branch, and
|
|
4
|
+
its own port, without a second clone and without fighting the checkout somebody
|
|
5
|
+
else is using.
|
|
6
|
+
|
|
7
|
+
Read this when the project has `worktrees.enabled: true`, or when the user asks
|
|
8
|
+
to run two agents in one project.
|
|
9
|
+
|
|
10
|
+
## Install
|
|
11
|
+
|
|
12
|
+
Setup copies `assets/worktree/*` flat into `.sassywares/worktree/`, makes the
|
|
13
|
+
scripts executable, and wires one `worktree:<script>` alias per script into the
|
|
14
|
+
project's manifest — the same exception `workspace:*` uses. They are tracked: a
|
|
15
|
+
worktree is a checkout of the repo, so every worktree carries the tooling.
|
|
16
|
+
|
|
17
|
+
```text
|
|
18
|
+
.sassywares/worktree/
|
|
19
|
+
├── _lib.sh shared helpers; reads `worktrees:`; carries worktree-version
|
|
20
|
+
├── create add a worktree, claim a port, print the namespace
|
|
21
|
+
├── list the table; --address / --path for scripting
|
|
22
|
+
├── stop kill whatever is on that worktree's port
|
|
23
|
+
├── remove refuse unsafe removals, then delete
|
|
24
|
+
└── prune merged-or-gone candidates; removes only what you approve
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Nothing else lives there. No state, no registry, no pid file.
|
|
28
|
+
|
|
29
|
+
`_lib.sh` carries `# worktree-version: N`. Bump `N` when an asset changes;
|
|
30
|
+
`--check` compares the installed copy and reports a stale one. Ask before
|
|
31
|
+
overwriting an existing copy — from the first install it is the project's file.
|
|
32
|
+
|
|
33
|
+
## Where things live
|
|
34
|
+
|
|
35
|
+
```text
|
|
36
|
+
~/.sassywares/worktrees/
|
|
37
|
+
└── <repo>/ <- the worktree home; .repo records which checkout owns it
|
|
38
|
+
├── .repo absolute path of the main checkout
|
|
39
|
+
├── ports/ claim directories, one per claimed port
|
|
40
|
+
└── <slug>/ a checkout
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
`worktrees.dir` sets the parent (default `~/.sassywares/worktrees`). It is the
|
|
44
|
+
one path in the config that may be absolute or start with `~/` — it names
|
|
45
|
+
machine-local state, not something a teammate clones.
|
|
46
|
+
|
|
47
|
+
**Never put checkouts inside `.git` or inside the working tree.** Inside `.git`
|
|
48
|
+
is undocumented and breaks where `.git` is a file (linked worktrees, submodules,
|
|
49
|
+
`--separate-git-dir`). Inside the working tree is destroyed by `git clean -xdf`
|
|
50
|
+
and crawled by every scanner that does not read `.gitignore` (`tsc`, Docker).
|
|
51
|
+
|
|
52
|
+
**Never `rm -rf` the worktree home.** It is full of checkouts with uncommitted
|
|
53
|
+
work; `remove` and `prune` are the only safe exits.
|
|
54
|
+
|
|
55
|
+
## The namespace
|
|
56
|
+
|
|
57
|
+
`create` derives and prints, for the caller and the hook:
|
|
58
|
+
|
|
59
|
+
| Variable | Example | Use |
|
|
60
|
+
|---|---|---|
|
|
61
|
+
| `WT_PATH` | `~/.sassywares/worktrees/shop/feat-catalog` | where the checkout is |
|
|
62
|
+
| `WT_BRANCH` | `feat/catalog` | the branch, as git names it |
|
|
63
|
+
| `WT_SLUG` | `feat-catalog` | the directory name, port key, registry key |
|
|
64
|
+
| `WT_NAMESPACE` | `shop-feat-catalog` | database schema, compose project, simulator name |
|
|
65
|
+
| `WT_PORT` | `3041` | the private port this checkout owns |
|
|
66
|
+
| `WT_BASE_URL` | `http://localhost:3041` | what to open |
|
|
67
|
+
|
|
68
|
+
Derived, never invented downstream: a hook that needs a database name uses
|
|
69
|
+
`$WT_NAMESPACE` rather than building its own, so two worktrees cannot collide by
|
|
70
|
+
accident.
|
|
71
|
+
|
|
72
|
+
**Ports.** The slug hashes into `worktrees.ports`, then the claim is taken with
|
|
73
|
+
an atomic `mkdir` and probed forward one port at a time on a collision. A claim
|
|
74
|
+
belongs to a slug, so a restarted app returns to the same port, and two slugs
|
|
75
|
+
that hash alike do not fight. `list` probes for liveness and never trusts a
|
|
76
|
+
recorded pid: a killed process leaves nothing to believe.
|
|
77
|
+
|
|
78
|
+
## Hooks
|
|
79
|
+
|
|
80
|
+
Two points, keyed by head branch like every other hook:
|
|
81
|
+
|
|
82
|
+
```yaml
|
|
83
|
+
hooks:
|
|
84
|
+
worktree:
|
|
85
|
+
"*":
|
|
86
|
+
after_create: [shop-worktree]
|
|
87
|
+
before_remove: [shop-worktree]
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
`after_create` runs **after** the checkout exists — that is when a project
|
|
91
|
+
installs dependencies, derives `.env` from `$WT_NAMESPACE`, seeds a database or
|
|
92
|
+
creates a simulator, and copies the session. `before_remove` runs **before** the
|
|
93
|
+
files go, and is where the derived database or device is dropped.
|
|
94
|
+
|
|
95
|
+
A shell script cannot dispatch a skill, so `remove` fails closed: with a hook
|
|
96
|
+
declared and `--hook-ok` missing, it prints `require-hook <name>` and exits `3`.
|
|
97
|
+
|
|
98
|
+
**Never write a hook skill yourself** — the same rule as every other hook. Setup
|
|
99
|
+
records the name; the project writes the body.
|
|
100
|
+
|
|
101
|
+
## Previewing a worktree
|
|
102
|
+
|
|
103
|
+
`sassy-worktree mode:preview` brings the product up in a checkout and prints
|
|
104
|
+
`how_to_see`, using the dogfood recipe's bring-up steps — everything up to, but
|
|
105
|
+
not including, that section's `Prove it:` step. It leaves the app running, and
|
|
106
|
+
`stop` (or `remove`) reaps it by port.
|
|
107
|
+
|
|
108
|
+
There is no separate preview configuration. How the app comes up is the recipe's
|
|
109
|
+
job, because it is the only place that knowledge is allowed to live.
|
|
110
|
+
|
|
111
|
+
**Sessions and third-party origins.** A worktree gets a fresh, empty
|
|
112
|
+
`.sassywares/session/`. Most providers register one callback URL, so a worktree
|
|
113
|
+
usually cannot log in on its own; the recipe's *Working in a second checkout*
|
|
114
|
+
section says how this project solves that, and the `after_create` hook does it —
|
|
115
|
+
copying or linking the main checkout's session is the common answer. A cookie is
|
|
116
|
+
host-scoped and crosses ports freely; a `localStorage` session is origin-scoped,
|
|
117
|
+
port included, and has to be injected per origin. That difference is worth
|
|
118
|
+
writing down once in the recipe rather than rediscovering it.
|
|
119
|
+
|
|
120
|
+
## Refusals
|
|
121
|
+
|
|
122
|
+
`remove` refuses, and `prune` skips rows it cannot prove safe:
|
|
123
|
+
|
|
124
|
+
| Condition | Why |
|
|
125
|
+
|---|---|
|
|
126
|
+
| It is the main checkout | the repo itself |
|
|
127
|
+
| Dirty tree | uncommitted work |
|
|
128
|
+
| Commits on no remote | nothing to recover from |
|
|
129
|
+
| Something listening on its port | stop the app first |
|
|
130
|
+
| A `before_remove` hook not yet run | the project has cleanup to do |
|
|
131
|
+
|
|
132
|
+
`--force` skips the dirty and unpushed checks and nothing else. It is never
|
|
133
|
+
implied.
|
|
134
|
+
|
|
135
|
+
## Concurrency rules
|
|
136
|
+
|
|
137
|
+
- **One worktree per run.** `references/branching.md` decides; a run already on
|
|
138
|
+
a non-base branch reuses it, so a second `sassy-work` in the same checkout does
|
|
139
|
+
not nest another worktree.
|
|
140
|
+
- **Never operate on another worktree.** A delegation brief carries the absolute
|
|
141
|
+
path of the checkout it may touch; `MAIN` is for reading config and listing.
|
|
142
|
+
- **Never `git stash`.** It is repository-global: a stash taken in one worktree
|
|
143
|
+
appears in all of them. A worktree already gives you what stash was for.
|
|
144
|
+
- **Never `git checkout` a branch in two places.** Git refuses it — that refusal
|
|
145
|
+
is a feature, and `create` reports it as such.
|
|
146
|
+
- **Do not copy `node_modules`.** Hardlink copies share inodes, so a rewrite
|
|
147
|
+
through one checkout corrupts the other. Let the package manager's store do
|
|
148
|
+
the deduplicating.
|
|
149
|
+
- **`worktrees.enabled` needs `commit.branch: new`.** Under `current` a run
|
|
150
|
+
commits where it stands and never cuts a branch, so no run would ever create a
|
|
151
|
+
worktree; `--check` notes the combination.
|
|
@@ -72,6 +72,7 @@ is_suite_skill() {
|
|
|
72
72
|
}
|
|
73
73
|
ASSET_SNAPSHOT="$SKILL_DIR/assets/snapshot"
|
|
74
74
|
ASSET_WORKSPACE="$SKILL_DIR/assets/workspace"
|
|
75
|
+
ASSET_WORKTREE="$SKILL_DIR/assets/worktree"
|
|
75
76
|
|
|
76
77
|
# The nearest config wins, walking up. Report where it is if one exists.
|
|
77
78
|
CONFIG=""
|
|
@@ -257,6 +258,7 @@ hook_points() {
|
|
|
257
258
|
case "$1" in
|
|
258
259
|
pr) printf '%s' "before_create after_create before_merge after_merge" ;;
|
|
259
260
|
push) printf '%s' "after_push" ;;
|
|
261
|
+
worktree) printf '%s' "after_create before_remove" ;;
|
|
260
262
|
esac
|
|
261
263
|
}
|
|
262
264
|
|
|
@@ -410,6 +412,7 @@ if (( CHECK )); then
|
|
|
410
412
|
commit.branch) ;;
|
|
411
413
|
pr.babysit|pr.merge|pr.delete_branch) ;;
|
|
412
414
|
dogfood.enabled|dogfood.recipe|dogfood.reports|dogfood.timeout) ;;
|
|
415
|
+
worktrees.enabled|worktrees.dir|worktrees.ports) ;;
|
|
413
416
|
hooks.*) ;; # shape checked with the hooks
|
|
414
417
|
*) bad "unknown key '$key' — it is ignored, so the run uses the default" ;;
|
|
415
418
|
esac
|
|
@@ -561,7 +564,7 @@ if (( CHECK )); then
|
|
|
561
564
|
if [[ -n "$(yflat "hooks${US}pr${US}before_create")" ]]; then
|
|
562
565
|
bad "hooks.pr.<point> is now nested by head branch — write hooks.pr.\"*\".<point>"
|
|
563
566
|
fi
|
|
564
|
-
for kind in pr push; do
|
|
567
|
+
for kind in pr push worktree; do
|
|
565
568
|
while IFS= read -r pat; do
|
|
566
569
|
[[ -n "$pat" ]] || continue
|
|
567
570
|
case "$pat" in
|
|
@@ -591,8 +594,8 @@ if (( CHECK )); then
|
|
|
591
594
|
[[ -n "$depth" ]] || continue
|
|
592
595
|
kind="${hpath#hooks$US}"; kind="${kind%%$US*}"
|
|
593
596
|
case "$kind" in
|
|
594
|
-
pr|push) ;;
|
|
595
|
-
*) bad "hooks kind '$kind' is not one of pr|push"; continue ;;
|
|
597
|
+
pr|push|worktree) ;;
|
|
598
|
+
*) bad "hooks kind '$kind' is not one of pr|push|worktree"; continue ;;
|
|
596
599
|
esac
|
|
597
600
|
if [[ "$depth" != "4" ]]; then
|
|
598
601
|
bad "hooks entry '${hpath//$US/.}' is not head -> point -> list"
|
|
@@ -612,7 +615,7 @@ if (( CHECK )); then
|
|
|
612
615
|
if [[ "$TOPOLOGY" == "repo" ]]; then
|
|
613
616
|
note " base for '$HEAD_ARG': $(base_for_head "$HEAD_ARG")"
|
|
614
617
|
fi
|
|
615
|
-
for kind in pr push; do
|
|
618
|
+
for kind in pr push worktree; do
|
|
616
619
|
for point in $(hook_points "$kind"); do
|
|
617
620
|
resolved="$(hooks_for_head_point "$HEAD_ARG" "$point" "$kind")"
|
|
618
621
|
note " head '$HEAD_ARG' → $point: $( [[ -n "$resolved" ]] && printf '%s' "$resolved" || printf 'none' )"
|
|
@@ -691,6 +694,114 @@ if (( CHECK )); then
|
|
|
691
694
|
esac
|
|
692
695
|
fi
|
|
693
696
|
|
|
697
|
+
# Worktrees: a switch and three mechanical settings. Creating, claiming, and
|
|
698
|
+
# refusing all belong to the scripts, so this validates only what a run reads.
|
|
699
|
+
wt_on="$(block_value worktrees enabled || true)"
|
|
700
|
+
wt_dir="$(block_value worktrees dir || true)"
|
|
701
|
+
wt_ports="$(block_value worktrees ports || true)"
|
|
702
|
+
case "$wt_on" in
|
|
703
|
+
"") ;;
|
|
704
|
+
true|false) note " worktrees.enabled: $wt_on" ;;
|
|
705
|
+
*) bad "worktrees.enabled '$wt_on' must be true|false" ;;
|
|
706
|
+
esac
|
|
707
|
+
if [[ -n "$wt_ports" ]]; then
|
|
708
|
+
case "$wt_ports" in
|
|
709
|
+
*-*) wt_lo="${wt_ports%%-*}"; wt_hi="${wt_ports##*-}" ;;
|
|
710
|
+
*) wt_lo=""; wt_hi=""; bad "worktrees.ports '$wt_ports' is not <from>-<to>" ;;
|
|
711
|
+
esac
|
|
712
|
+
if [[ -n "$wt_lo" ]]; then
|
|
713
|
+
case "$wt_lo$wt_hi" in
|
|
714
|
+
*[!0-9]*) bad "worktrees.ports '$wt_ports' is not numeric" ;;
|
|
715
|
+
*) if (( wt_lo < 1 || wt_hi > 65535 || wt_lo > wt_hi )); then
|
|
716
|
+
bad "worktrees.ports '$wt_ports' is not a usable port range"
|
|
717
|
+
else
|
|
718
|
+
note " worktrees.ports: $wt_ports"
|
|
719
|
+
fi ;;
|
|
720
|
+
esac
|
|
721
|
+
fi
|
|
722
|
+
fi
|
|
723
|
+
|
|
724
|
+
if [[ "$wt_on" == "true" ]]; then
|
|
725
|
+
if [[ "$TOPOLOGY" != "repo" ]]; then
|
|
726
|
+
bad "worktrees.enabled needs a repo — this folder is '$TOPOLOGY', and a checkout needs git"
|
|
727
|
+
else
|
|
728
|
+
if [[ "$(yflat "commit${US}branch" 2>/dev/null || true)" == "current" ]]; then
|
|
729
|
+
note " worktrees.enabled with commit.branch: current — a run never cuts a branch, so no run creates one"
|
|
730
|
+
fi
|
|
731
|
+
|
|
732
|
+
wt_lib="$ROOT/.sassywares/worktree/_lib.sh"
|
|
733
|
+
if [[ -f "$wt_lib" ]]; then
|
|
734
|
+
installed_wt="$(sed -n 's/^# worktree-version: //p' "$wt_lib" | head -n 1)"
|
|
735
|
+
asset_wt="$(sed -n 's/^# worktree-version: //p' "$ASSET_WORKTREE/_lib.sh" | head -n 1)"
|
|
736
|
+
if [[ -z "$installed_wt" ]]; then
|
|
737
|
+
bad "installed .sassywares/worktree/_lib.sh has no worktree-version line"
|
|
738
|
+
elif [[ -n "$asset_wt" && "$installed_wt" != "$asset_wt" ]]; then
|
|
739
|
+
bad "installed worktree tooling is v${installed_wt}, this skill ships v${asset_wt} — re-run setup"
|
|
740
|
+
else
|
|
741
|
+
note " worktree tooling v${installed_wt}"
|
|
742
|
+
fi
|
|
743
|
+
for helper in create list stop remove prune; do
|
|
744
|
+
[[ -x "$ROOT/.sassywares/worktree/$helper" ]] \
|
|
745
|
+
|| bad "missing or not executable: .sassywares/worktree/$helper"
|
|
746
|
+
done
|
|
747
|
+
else
|
|
748
|
+
bad "worktrees.enabled but .sassywares/worktree/_lib.sh is missing — re-run setup"
|
|
749
|
+
fi
|
|
750
|
+
|
|
751
|
+
# A checkout must live outside the working tree — inside it, `git clean
|
|
752
|
+
# -xdf` deletes uncommitted work and every scanner that ignores .gitignore
|
|
753
|
+
# crawls a second copy of the source. And a worktree parked on a configured
|
|
754
|
+
# base is a run that will commit onto a shared branch unobserved.
|
|
755
|
+
root_real="$(cd "$ROOT" && pwd -P)"
|
|
756
|
+
BASE_VALUES="$(yaml_flat "$CONFIG" \
|
|
757
|
+
| awk -F'\t' -v us="$US" '{n=split($1,a,us); if (n==3 && a[1]=="git" && a[2]=="base_map") print $2}' \
|
|
758
|
+
| tr '\n' ' ')"
|
|
759
|
+
wt_paths=()
|
|
760
|
+
while IFS=$'\t' read -r wpath wbranch; do
|
|
761
|
+
[[ -n "$wpath" ]] || continue
|
|
762
|
+
wt_paths+=("$wpath")
|
|
763
|
+
[[ "$wpath" == "$root_real" ]] && continue # the main checkout
|
|
764
|
+
case "$wpath" in
|
|
765
|
+
"$root_real"/*) bad "worktree '$wpath' is inside the working tree — move worktrees.dir outside it" ;;
|
|
766
|
+
esac
|
|
767
|
+
case " $BASE_VALUES " in
|
|
768
|
+
*" $wbranch "*) bad "a worktree holds '$wbranch', which base_map names as a base" ;;
|
|
769
|
+
esac
|
|
770
|
+
done < <(git -C "$ROOT" worktree list --porcelain 2>/dev/null \
|
|
771
|
+
| awk '/^worktree /{p=$2} /^branch /{b=$2; sub(/^refs\/heads\//,"",b); print p "\t" b; p=""} /^detached/{print p "\t(detached)"; p=""}')
|
|
772
|
+
|
|
773
|
+
# Orphan port claims: the worktree is gone but its port is still taken, so
|
|
774
|
+
# a later checkout is pushed off it for no reason.
|
|
775
|
+
wt_homef=""
|
|
776
|
+
d="${wt_dir:-$HOME/.sassywares/worktrees}"
|
|
777
|
+
case "$d" in
|
|
778
|
+
"~") d="$HOME" ;;
|
|
779
|
+
"~/"*) d="$HOME/${d#\~/}" ;;
|
|
780
|
+
/*) ;;
|
|
781
|
+
*) d="$ROOT/$d" ;;
|
|
782
|
+
esac
|
|
783
|
+
cand="$d/$(basename "$ROOT")"
|
|
784
|
+
if [[ -f "$cand/.repo" && "$(cat "$cand/.repo" 2>/dev/null)" != "$root_real" ]]; then
|
|
785
|
+
cand="$d/$(basename "$ROOT")-$(printf '%s' "$root_real" | shasum -a 256 | cut -c1-6)"
|
|
786
|
+
fi
|
|
787
|
+
[[ -d "$cand" ]] && wt_homef="$cand"
|
|
788
|
+
if [[ -n "$wt_homef" && -d "$wt_homef/ports" ]]; then
|
|
789
|
+
for claim in "$wt_homef"/ports/*; do
|
|
790
|
+
[[ -d "$claim" ]] || continue
|
|
791
|
+
owner="$(cat "$claim/owner" 2>/dev/null || true)"
|
|
792
|
+
[[ -n "$owner" ]] || continue
|
|
793
|
+
found=0
|
|
794
|
+
if (( ${#wt_paths[@]} )); then
|
|
795
|
+
for p in "${wt_paths[@]}"; do
|
|
796
|
+
[[ "$p" == *"/$owner" ]] && found=1
|
|
797
|
+
done
|
|
798
|
+
fi
|
|
799
|
+
(( found )) || bad "port $(basename "$claim") is claimed by '$owner', which has no worktree"
|
|
800
|
+
done
|
|
801
|
+
fi
|
|
802
|
+
fi
|
|
803
|
+
fi
|
|
804
|
+
|
|
694
805
|
# Dogfood is a pointer and a switch, never commands: the recipe holds the
|
|
695
806
|
# procedure and its `Prove it:` step is the verdict. Everything below is
|
|
696
807
|
# structural. A check run never runs the product — a validator that boots an
|
|
@@ -736,6 +847,16 @@ if (( CHECK )); then
|
|
|
736
847
|
fi
|
|
737
848
|
fi
|
|
738
849
|
|
|
850
|
+
# A committed session is a credential leak, not merely a heavy history. Only
|
|
851
|
+
# checked once the folder exists, so a project that never uses one is silent.
|
|
852
|
+
if [[ "$TOPOLOGY" == "repo" && -d "$ROOT/.sassywares/session" ]]; then
|
|
853
|
+
if git -C "$ROOT" check-ignore -q -- ".sassywares/session/probe" 2>/dev/null; then
|
|
854
|
+
note " .sassywares/session is gitignored"
|
|
855
|
+
else
|
|
856
|
+
bad ".sassywares/session is not gitignored — a session artifact must never be committed"
|
|
857
|
+
fi
|
|
858
|
+
fi
|
|
859
|
+
|
|
739
860
|
if [[ -n "$dg_recipe" ]]; then
|
|
740
861
|
if [[ ! -f "$ROOT/$dg_recipe" ]]; then
|
|
741
862
|
if [[ "$dg_enabled" == "true" ]]; then
|
|
@@ -1162,6 +1283,19 @@ cat <<'EOF'
|
|
|
1162
1283
|
EOF
|
|
1163
1284
|
cat <<'EOF'
|
|
1164
1285
|
|
|
1286
|
+
# --- Worktrees ------------------------------------------------------------
|
|
1287
|
+
# Parallel work in one repo: a checkout per branch, each with its own derived
|
|
1288
|
+
# namespace and port, so two runs never fight over one working tree. enabled:
|
|
1289
|
+
# true lets a run create one instead of working here — and needs
|
|
1290
|
+
# commit.branch: new, because `current` never cuts a branch. The scripts in
|
|
1291
|
+
# .sassywares/worktree/ own the mechanics; nothing else reads these values.
|
|
1292
|
+
worktrees:
|
|
1293
|
+
EOF
|
|
1294
|
+
kv enabled false 34 '# true = a run may work in its own checkout'
|
|
1295
|
+
kv dir '~/.sassywares/worktrees' 34 '# parent of the per-repo folder; ~ is allowed'
|
|
1296
|
+
kv ports 3000-3099 34 '# the range a checkout claims a port from'
|
|
1297
|
+
cat <<'EOF'
|
|
1298
|
+
|
|
1165
1299
|
# --- Dogfood --------------------------------------------------------------
|
|
1166
1300
|
# Agent QA: a stored procedure that proves a change works in the running
|
|
1167
1301
|
# product. This block only points at it — commands live in the recipe, because
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
// The `skills` CLI's skill-folder hash, as sassy-setup checks it.
|
|
2
|
+
//
|
|
3
|
+
// Two eras are live in the wild and the lock's `version` says which one wrote
|
|
4
|
+
// its `computedHash`:
|
|
5
|
+
//
|
|
6
|
+
// lock v1 (skills CLI <= 1.7.x) sha256 over, per file sorted by
|
|
7
|
+
// localeCompare: relative path, then bytes.
|
|
8
|
+
// lock v2 (skills CLI >= 1.8.x) sha256 over, per file sorted by Buffer
|
|
9
|
+
// compare: relative path, "\0", byte length,
|
|
10
|
+
// "\0", bytes — CRLF normalized to LF, and
|
|
11
|
+
// metadata.json, .git, __pycache__ and
|
|
12
|
+
// __pypackages__ excluded.
|
|
13
|
+
//
|
|
14
|
+
// Both are transcriptions of the CLI's own collectFiles + hashSkillFiles (the
|
|
15
|
+
// CLI keeps the v1 one to migrate old locks), so a folder this module calls
|
|
16
|
+
// clean is a folder `skills check` calls clean. A hash that drifts from the
|
|
17
|
+
// CLI's is not a cosmetic bug: it reports a sound pin as drift on every suite
|
|
18
|
+
// skill. Re-read the CLI's source when bumping, and keep the golden vectors in
|
|
19
|
+
// tests/sassy-setup-roster.sh honest.
|
|
20
|
+
//
|
|
21
|
+
// No side effects: lockcheck.mjs and tests/hash-lock.mjs import it.
|
|
22
|
+
|
|
23
|
+
import { createHash } from "node:crypto";
|
|
24
|
+
import { readdir, readFile, realpath, stat } from "node:fs/promises";
|
|
25
|
+
import { join, relative, sep } from "node:path";
|
|
26
|
+
|
|
27
|
+
// skills CLI >= 1.8.x, for lock v2 and later.
|
|
28
|
+
const EXCLUDE_FILES = new Set(["metadata.json"]);
|
|
29
|
+
const EXCLUDE_DIRS = new Set([".git", "__pycache__", "__pypackages__"]);
|
|
30
|
+
|
|
31
|
+
async function walk(base, dir, realRoot, ancestors, files) {
|
|
32
|
+
const realDir = await realpath(dir);
|
|
33
|
+
if (ancestors.has(realDir)) return;
|
|
34
|
+
const branch = new Set(ancestors).add(realDir);
|
|
35
|
+
for (const entry of await readdir(dir, { withFileTypes: true })) {
|
|
36
|
+
if (EXCLUDE_FILES.has(entry.name)) continue;
|
|
37
|
+
if (entry.isDirectory() && EXCLUDE_DIRS.has(entry.name)) continue;
|
|
38
|
+
const full = join(dir, entry.name);
|
|
39
|
+
let isDirectory = entry.isDirectory();
|
|
40
|
+
if (entry.isSymbolicLink()) {
|
|
41
|
+
const target = await realpath(full).catch(() => null);
|
|
42
|
+
// A link out of the skill folder is not part of the skill; one that stays
|
|
43
|
+
// inside is (a user scope links each skill to a working copy).
|
|
44
|
+
if (!target || (target !== realRoot && !target.startsWith(realRoot + sep))) continue;
|
|
45
|
+
isDirectory = (await stat(target)).isDirectory();
|
|
46
|
+
if (isDirectory && EXCLUDE_DIRS.has(entry.name)) continue;
|
|
47
|
+
} else if (!isDirectory && !entry.isFile()) {
|
|
48
|
+
continue;
|
|
49
|
+
}
|
|
50
|
+
if (isDirectory) {
|
|
51
|
+
await walk(base, full, realRoot, branch, files);
|
|
52
|
+
} else {
|
|
53
|
+
files.push({
|
|
54
|
+
path: relative(base, full).split("\\").join("/"),
|
|
55
|
+
body: await readFile(full),
|
|
56
|
+
});
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
// The v1 walk: no exclusions beyond .git/node_modules, no symlinks followed.
|
|
62
|
+
async function walkLegacy(base, dir, files) {
|
|
63
|
+
for (const entry of await readdir(dir, { withFileTypes: true })) {
|
|
64
|
+
const full = join(dir, entry.name);
|
|
65
|
+
if (entry.isDirectory()) {
|
|
66
|
+
if (entry.name === ".git" || entry.name === "node_modules") continue;
|
|
67
|
+
await walkLegacy(base, full, files);
|
|
68
|
+
} else if (entry.isFile()) {
|
|
69
|
+
files.push({
|
|
70
|
+
path: relative(base, full).split("\\").join("/"),
|
|
71
|
+
body: await readFile(full),
|
|
72
|
+
});
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
// CRLF to LF, unless the file holds a NUL or has none — the CLI's own rule.
|
|
78
|
+
function normalizeLineEndings(body) {
|
|
79
|
+
if (body.includes(0) || !body.includes("\r\n")) return body;
|
|
80
|
+
return Buffer.from(body.toString("latin1").replaceAll("\r\n", "\n"), "latin1");
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
// Hash one skill folder the way the CLI does for a lock of the given era.
|
|
84
|
+
export async function hashSkillFolder(dir, legacy = false) {
|
|
85
|
+
const hash = createHash("sha256");
|
|
86
|
+
if (legacy) {
|
|
87
|
+
const files = [];
|
|
88
|
+
await walkLegacy(dir, dir, files);
|
|
89
|
+
files.sort((a, b) => a.path.localeCompare(b.path));
|
|
90
|
+
for (const file of files) hash.update(file.path).update(file.body);
|
|
91
|
+
return hash.digest("hex");
|
|
92
|
+
}
|
|
93
|
+
const files = [];
|
|
94
|
+
await walk(dir, dir, await realpath(dir), new Set(), files);
|
|
95
|
+
const entries = files
|
|
96
|
+
.map((file) => ({
|
|
97
|
+
path: Buffer.from(file.path, "utf8"),
|
|
98
|
+
body: normalizeLineEndings(file.body),
|
|
99
|
+
}))
|
|
100
|
+
.sort((a, b) => Buffer.compare(a.path, b.path));
|
|
101
|
+
for (const entry of entries) {
|
|
102
|
+
hash
|
|
103
|
+
.update(entry.path)
|
|
104
|
+
.update("\0")
|
|
105
|
+
.update(String(entry.body.length))
|
|
106
|
+
.update("\0")
|
|
107
|
+
.update(entry.body);
|
|
108
|
+
}
|
|
109
|
+
return hash.digest("hex");
|
|
110
|
+
}
|
|
@@ -7,10 +7,12 @@
|
|
|
7
7
|
// install has a pin to verify; a user install is reported, and a missing suite
|
|
8
8
|
// is reported without counting as drift.
|
|
9
9
|
//
|
|
10
|
-
// Read-only, offline. The folder hash is the `skills` CLI's own definition
|
|
11
|
-
//
|
|
12
|
-
//
|
|
13
|
-
// the
|
|
10
|
+
// Read-only, offline. The folder hash is the `skills` CLI's own definition
|
|
11
|
+
// (./hash-skill.mjs), so "identical to the pin" is a fact this script asserts,
|
|
12
|
+
// not a claim the agent has to make in prose. Both hash eras are live — the
|
|
13
|
+
// lock's version names the one it was written with — so the definition that
|
|
14
|
+
// version names is tried first and the other second. Trying both cannot hide an
|
|
15
|
+
// edited folder: edited bytes match neither.
|
|
14
16
|
//
|
|
15
17
|
// Usage: lockcheck.mjs [--root DIR] [--roster a,b,c]
|
|
16
18
|
// A suite skill is a name in --roster (assets/roster in sassy-setup); without
|
|
@@ -18,13 +20,15 @@
|
|
|
18
20
|
// Prints "<drift|note>\t<message>" per finding and always exits 0: the caller
|
|
19
21
|
// owns the verdict and the formatting.
|
|
20
22
|
|
|
21
|
-
import { createHash } from "node:crypto";
|
|
22
|
-
import { readdir, readFile } from "node:fs/promises";
|
|
23
23
|
import { existsSync, readdirSync } from "node:fs";
|
|
24
|
+
import { readdir, readFile } from "node:fs/promises";
|
|
24
25
|
import { homedir } from "node:os";
|
|
25
|
-
import { join
|
|
26
|
+
import { join } from "node:path";
|
|
27
|
+
|
|
28
|
+
import { hashSkillFolder } from "./hash-skill.mjs";
|
|
26
29
|
|
|
27
30
|
const SUITE = "sassywares/sassy-skills";
|
|
31
|
+
|
|
28
32
|
let roster = null; // suite skill names (--roster a,b,c); null falls back to the sassy- prefix
|
|
29
33
|
const isSuite = (name) => (roster ? roster.has(name) : /^sassy-/.test(name));
|
|
30
34
|
|
|
@@ -45,33 +49,6 @@ const lines = [];
|
|
|
45
49
|
const drift = (message) => lines.push(`drift\t${message}`);
|
|
46
50
|
const note = (message) => lines.push(`note\t${message}`);
|
|
47
51
|
|
|
48
|
-
async function collect(base, dir, files) {
|
|
49
|
-
for (const entry of await readdir(dir, { withFileTypes: true })) {
|
|
50
|
-
const full = join(dir, entry.name);
|
|
51
|
-
if (entry.isDirectory()) {
|
|
52
|
-
if (entry.name === ".git" || entry.name === "node_modules") continue;
|
|
53
|
-
await collect(base, full, files);
|
|
54
|
-
} else if (entry.isFile()) {
|
|
55
|
-
files.push({
|
|
56
|
-
path: relative(base, full).split("\\").join("/"),
|
|
57
|
-
body: await readFile(full),
|
|
58
|
-
});
|
|
59
|
-
}
|
|
60
|
-
}
|
|
61
|
-
}
|
|
62
|
-
|
|
63
|
-
async function folderHash(dir) {
|
|
64
|
-
const files = [];
|
|
65
|
-
await collect(dir, dir, files);
|
|
66
|
-
files.sort((a, b) => a.path.localeCompare(b.path));
|
|
67
|
-
const hash = createHash("sha256");
|
|
68
|
-
for (const file of files) {
|
|
69
|
-
hash.update(file.path);
|
|
70
|
-
hash.update(file.body);
|
|
71
|
-
}
|
|
72
|
-
return hash.digest("hex");
|
|
73
|
-
}
|
|
74
|
-
|
|
75
52
|
// suite skills in a skills directory. Follows symlinks: a user scope may link
|
|
76
53
|
// each skill to a working copy rather than holding the files.
|
|
77
54
|
function suiteIn(dir) {
|
|
@@ -122,23 +99,32 @@ async function main() {
|
|
|
122
99
|
return;
|
|
123
100
|
}
|
|
124
101
|
|
|
102
|
+
// The lock's version names the hash era; the other era is the fallback.
|
|
103
|
+
const legacyFirst = Number(lock.version) === 1;
|
|
125
104
|
const installed = (await readdir(suite, { withFileTypes: true }))
|
|
126
105
|
.filter((entry) => entry.isDirectory() && isSuite(entry.name))
|
|
127
106
|
.map((entry) => entry.name);
|
|
128
107
|
const installedNames = new Set(installed);
|
|
129
108
|
const pinnedNames = new Set(pinned.map(([name]) => name));
|
|
130
109
|
let matched = 0;
|
|
110
|
+
let otherEra = 0;
|
|
131
111
|
|
|
132
112
|
for (const [name, entry] of pinned) {
|
|
133
113
|
if (!installedNames.has(name)) {
|
|
134
114
|
drift(`vendored ${name} is missing from .agents/skills — re-install with npx skills add ${SUITE}`);
|
|
135
115
|
continue;
|
|
136
116
|
}
|
|
137
|
-
|
|
138
|
-
|
|
117
|
+
const dir = join(suite, name);
|
|
118
|
+
if ((await hashSkillFolder(dir, legacyFirst)) === entry.computedHash) {
|
|
119
|
+
matched += 1;
|
|
139
120
|
continue;
|
|
140
121
|
}
|
|
141
|
-
|
|
122
|
+
if ((await hashSkillFolder(dir, !legacyFirst)) === entry.computedHash) {
|
|
123
|
+
matched += 1;
|
|
124
|
+
otherEra += 1;
|
|
125
|
+
continue;
|
|
126
|
+
}
|
|
127
|
+
drift(`${name} does not match the pin — edited locally or half-installed; re-install, or re-pin with npx skills add ${SUITE}`);
|
|
142
128
|
}
|
|
143
129
|
|
|
144
130
|
for (const name of installed) {
|
|
@@ -150,6 +136,9 @@ async function main() {
|
|
|
150
136
|
if (matched > 0) {
|
|
151
137
|
note(`${matched}/${pinned.length} suite skill folders match skills-lock.json byte for byte`);
|
|
152
138
|
}
|
|
139
|
+
if (otherEra > 0) {
|
|
140
|
+
note(`${otherEra} of them matched the other skills-lock hash era — the next npx skills add ${SUITE} migrates the lock`);
|
|
141
|
+
}
|
|
153
142
|
|
|
154
143
|
const sources = [...new Set(pinned.map(([, entry]) => String(entry.source ?? "unknown")))];
|
|
155
144
|
if (sources.length === 1 && sources[0] !== SUITE) {
|