@sassywares/skills 0.11.0 → 0.11.2
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 +11 -4
- package/README.md +18 -8
- package/package.json +1 -1
- package/skills/sassy-dogfood/SKILL.md +36 -11
- package/skills/sassy-plan/references/plan-format.md +1 -1
- package/skills/sassy-setup/SKILL.md +4 -4
- package/skills/sassy-setup/assets/dogfood-recipe.md +1 -1
- package/skills/sassy-setup/assets/worktree/_lib.sh +71 -5
- package/skills/sassy-setup/assets/worktree/create +21 -7
- package/skills/sassy-setup/assets/worktree/list +31 -8
- package/skills/sassy-setup/assets/worktree/prune +14 -6
- package/skills/sassy-setup/assets/worktree/remove +9 -6
- package/skills/sassy-setup/assets/worktree/stop +6 -3
- package/skills/sassy-setup/references/config.md +16 -9
- package/skills/sassy-setup/references/dogfood.md +63 -12
- package/skills/sassy-setup/references/harness.md +6 -0
- package/skills/sassy-setup/references/worktree.md +39 -12
- package/skills/sassy-setup/scripts/detect.sh +44 -8
- 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 +11 -8
|
@@ -86,7 +86,7 @@ hooks:
|
|
|
86
86
|
worktrees:
|
|
87
87
|
enabled: false # true = a run may work in its own checkout
|
|
88
88
|
dir: ~/.sassywares/worktrees # parent of the per-repo folder; ~ is allowed here
|
|
89
|
-
ports: 3000-3099 #
|
|
89
|
+
ports: 3000-3099 # optional; delete for a non-port preview
|
|
90
90
|
dogfood:
|
|
91
91
|
enabled: false # true = sassy-plan writes Mode: Auto QA rows
|
|
92
92
|
recipe: .sassywares/dogfood/recipe.md # the procedure
|
|
@@ -119,7 +119,7 @@ dogfood:
|
|
|
119
119
|
| `dogfood.timeout` | `900` | Wall-clock for one run. A timeout is a failure, never a hang |
|
|
120
120
|
| `worktrees.enabled` | `false` | `true` lets a run work in its own checkout instead of this one. Needs `commit.branch: new` |
|
|
121
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 |
|
|
122
|
+
| `worktrees.ports` | `3000-3099` | The range a checkout claims its private port from. **Optional**: without it a checkout holds no port and is addressed by the recipe's preview line — which is how a mobile, desktop, or CLI project previews |
|
|
123
123
|
|
|
124
124
|
Paths are relative to the config's own directory, never to the cwd.
|
|
125
125
|
|
|
@@ -407,7 +407,11 @@ worktrees:
|
|
|
407
407
|
```
|
|
408
408
|
|
|
409
409
|
Three keys, no commands. The scripts in `.sassywares/worktree/` own the
|
|
410
|
-
mechanics and `sassy-worktree` orchestrates them.
|
|
410
|
+
mechanics and `sassy-worktree` orchestrates them.
|
|
411
|
+
|
|
412
|
+
**A port is a resource, not the model.** Delete `ports` for an app whose preview
|
|
413
|
+
is not a URL: no port is derived, `WT_PORT` and `WT_BASE_URL` are absent, and
|
|
414
|
+
`list` shows the recipe's `**Preview:**` line instead. `dir` is the one path in this
|
|
411
415
|
file that may be absolute or start with `~/` — it names machine-local state, not
|
|
412
416
|
something a teammate clones.
|
|
413
417
|
|
|
@@ -471,8 +475,8 @@ report layout, the verdict classes, and the lint are in
|
|
|
471
475
|
- `hooks` is allowed only with the four points under `hooks.pr`, `after_push`
|
|
472
476
|
under `hooks.push`, and `after_create`/`before_remove` under `hooks.worktree`,
|
|
473
477
|
each a list of skill names that resolve to `.agents/skills/<name>/SKILL.md`.
|
|
474
|
-
- `worktrees.enabled` is `true` or `false`; `worktrees.ports` is
|
|
475
|
-
inside 1–65535 with `<from>` no greater than `<to>`. A checkout must resolve
|
|
478
|
+
- `worktrees.enabled` is `true` or `false`; when `worktrees.ports` is present it
|
|
479
|
+
is `<from>-<to>` inside 1–65535 with `<from>` no greater than `<to>`. A checkout must resolve
|
|
476
480
|
outside the working tree, must not hold a branch `base_map` names as a base,
|
|
477
481
|
and must not leave a port claimed by a worktree that no longer exists. An
|
|
478
482
|
`enabled: true` with no tooling installed, or with the wrong tooling version,
|
|
@@ -496,7 +500,10 @@ a `drift:` line, exiting non-zero. When the suite is installed in project
|
|
|
496
500
|
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
|
|
497
501
|
definition and compared to `computedHash` in `skills-lock.json`, the lock is
|
|
498
502
|
checked against the installed set in both directions, and git-tracked state of
|
|
499
|
-
the lock is reported.
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
+
the lock is reported. Both lock eras count: the definition named by the lock's
|
|
504
|
+
`version` is tried first and the other second, so a pin written by an older
|
|
505
|
+
`skills` CLI reads as a match (with a note) rather than as drift — the
|
|
506
|
+
`skills` CLI changed its folder hash and still reads both. A stale, hand-edited,
|
|
507
|
+
or half-installed suite is drift even when the config itself matches the tree. A
|
|
508
|
+
user-scope install (`~/.agents/skills/`) has no pin to verify; the check notes
|
|
509
|
+
it, and a suite found in neither scope is noted, not drift.
|
|
@@ -70,7 +70,12 @@ copy `.env.example` → `.env` and fill `DOGFOOD_USER`, `DOGFOOD_PASS`.
|
|
|
70
70
|
|
|
71
71
|
**Reset:** `bun run db:reset`; `rm -rf .sassywares/dogfood/reports/*`
|
|
72
72
|
|
|
73
|
-
**Preview:**
|
|
73
|
+
**Preview:** open `http://localhost:${WT_PORT:-3000}`
|
|
74
|
+
|
|
75
|
+
**Upstream:** `api.example.com` — a service this run does not control. Down is
|
|
76
|
+
`env`, never a retry.
|
|
77
|
+
|
|
78
|
+
**Uncovered:** mobile (nothing), admin (unit tests only)
|
|
74
79
|
|
|
75
80
|
## catalog — a search returns matching products
|
|
76
81
|
|
|
@@ -101,14 +106,45 @@ a check, and `--check` reports it as drift. `Do` is a command *or* an
|
|
|
101
106
|
instruction ("open `/catalog`, sign in as `DOGFOOD_USER`") — the instruction is
|
|
102
107
|
why the recipe outlives whatever tool the agent happens to have this quarter.
|
|
103
108
|
|
|
104
|
-
**One `Prove it:` per section**,
|
|
109
|
+
**One `Prove it:` per section**, naming a step (`step 5`) or saying `none`. A
|
|
110
|
+
named step's exit code is the verdict; `none` is a legal, explicit "this surface
|
|
111
|
+
has no machine verdict" — the section still records what a person should check,
|
|
112
|
+
and every QA row for it stays `Manual`.
|
|
113
|
+
|
|
114
|
+
**Steps after the `Prove it:` step are cleanup.** They always run, they never
|
|
115
|
+
change the exit code, and that is where a port is freed or a process is stopped.
|
|
116
|
+
Putting teardown before the verdict means a failed run leaves the port held. Steps before
|
|
105
117
|
it set up state and assert along the way; the prove step is the machine-readable
|
|
106
118
|
answer. A section without one has no verdict.
|
|
107
119
|
|
|
108
|
-
**One `**Preview:**` line**, optional:
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
is
|
|
120
|
+
**One `**Preview:**` line**, optional: **what you look at**, not the command that
|
|
121
|
+
starts it. The command belongs in the section's steps, where its `Expect` can be
|
|
122
|
+
checked. The result — a URL, a simulator, a window — is the project's own answer
|
|
123
|
+
to "what is the address", and it is why the suite never has to assume a browser.
|
|
124
|
+
|
|
125
|
+
`$WT_SLUG`, `$WT_NAMESPACE`, `$WT_PATH`, `$WT_PORT`, and `$WT_BASE_URL` are
|
|
126
|
+
substituted into the preview line and into every step. The last two exist only
|
|
127
|
+
when `worktrees.ports` is configured, and a recipe must also run in the **main
|
|
128
|
+
checkout**, where no worktree exists — so write the port with the project's own
|
|
129
|
+
default: `${WT_PORT:-5180}`. One expansion that works in both places is what
|
|
130
|
+
keeps a recipe runnable outside a worktree.
|
|
131
|
+
|
|
132
|
+
| Project | Preview line |
|
|
133
|
+
|---|---|
|
|
134
|
+
| Web | `http://localhost:${WT_PORT:-5180}` |
|
|
135
|
+
| Mobile | `simulator "$WT_NAMESPACE"` — booted by the `after_create` hook |
|
|
136
|
+
| Desktop | `the app window is already open` |
|
|
137
|
+
| CLI | *(none — there is nothing to look at)* |
|
|
138
|
+
|
|
139
|
+
**`**Upstream:**` and `**Uncovered:**`** are optional header lines that make the
|
|
140
|
+
two dangerous facts visible without reading every step: which third-party services
|
|
141
|
+
the recipe depends on, and which parts have no machine verdict at all. `Uncovered`
|
|
142
|
+
may name a sub-area of a covered surface — "the web surface's auth and write
|
|
143
|
+
flows" — which is where a no-third-party-mutation rule usually lands. A section
|
|
144
|
+
with no verdict ends `**Prove it:** none`, so a plan keeps its rows `Manual`
|
|
145
|
+
instead of inventing an Auto row for a check that does not exist.
|
|
146
|
+
|
|
147
|
+
Prose, like every other line here: no tool, no schema.
|
|
112
148
|
|
|
113
149
|
**Rules.**
|
|
114
150
|
|
|
@@ -118,12 +154,22 @@ is prose, like every other line here: no tool, no schema.
|
|
|
118
154
|
step needs one, it names the variable and the project's own gitignored env file
|
|
119
155
|
holds the value.
|
|
120
156
|
- **Local or staging only.** A recipe that names production is a bug.
|
|
157
|
+
- **A prerequisite carries its command.** *Set up once* is commands, not prose: a
|
|
158
|
+
required Node, JDK, or database names the command that provides it (`nvm use 24`)
|
|
159
|
+
as well as the requirement. A run may not improvise activation, so a stated
|
|
160
|
+
requirement with no command only works on machines that happen to be ready.
|
|
161
|
+
- **No dependency churn.** *Set up once* installs frozen when a lockfile exists.
|
|
162
|
+
A broke lockfile is `env`; repairing it silently re-resolves versions and makes
|
|
163
|
+
every checkout dirty.
|
|
164
|
+
- **No third-party mutation.** A step never registers a user, sends mail, or
|
|
165
|
+
writes to a shared service. Log in by hand and copy the session in.
|
|
121
166
|
- **The happy path plus its checks.** Debris ("metro holds 8081") is a learning,
|
|
122
167
|
not a step: it goes to `artifacts.solutions` via `sassy-compound`, which
|
|
123
168
|
scouting already reads. This is what keeps a busy project's recipe at forty
|
|
124
169
|
lines instead of becoming a wiki.
|
|
125
|
-
- **No
|
|
126
|
-
|
|
170
|
+
- **No harness tools.** Never "use Playwright" or "use the Chrome MCP" — a driver,
|
|
171
|
+
MCP server, or emulator is a harness choice, not a procedure. Ordinary shell
|
|
172
|
+
utilities (`curl`, `lsof`, `grep`) are fine: they are how a step is written.
|
|
127
173
|
|
|
128
174
|
## Sessions, and a second checkout
|
|
129
175
|
|
|
@@ -188,11 +234,15 @@ A killed session therefore leaves an accurate breadcrumb, and the next one reads
|
|
|
188
234
|
one file to know where it stopped.
|
|
189
235
|
|
|
190
236
|
- **`status`** — `running` | `pass` | `failed`.
|
|
191
|
-
- **`class`** — `code` (a finding for the rework cycle) | `env` (the
|
|
192
|
-
|
|
237
|
+
- **`class`** — `code` (a finding for the rework cycle) | `env` (the environment
|
|
238
|
+
cannot produce a verdict: a missing dependency, exit 75 or 127, or a third-party
|
|
239
|
+
service nobody in this run owns being down — report and park, never loop) |
|
|
193
240
|
`recipe` (the procedure itself is stale: a renamed script, a dead URL, a step
|
|
194
241
|
that cannot be followed). `recipe` is the rot signal: the run proposes a
|
|
195
242
|
one-line diff and never quietly improvises around it.
|
|
243
|
+
- **A preflight or bring-up failure** has no step id: its log is `steps/00-setup.log`
|
|
244
|
+
and its table row is `setup`. It is a verdict about the environment, so it still
|
|
245
|
+
gets a `class`.
|
|
196
246
|
- **One log per executed step**, capped head-and-tail (~64 KB) with a
|
|
197
247
|
`[truncated N lines]` marker, so a runaway loop cannot fill the disk.
|
|
198
248
|
- **Redaction happens before the write.** Every value of an env var the recipe
|
|
@@ -240,6 +290,7 @@ Structural, never executed:
|
|
|
240
290
|
`.sassywares/session` whenever that directory exists — a committed session is a
|
|
241
291
|
credential leak, not a heavy history.
|
|
242
292
|
- The recipe has at least one `## ` section, every section has a `**Prove it:**`
|
|
243
|
-
line
|
|
244
|
-
secret-shaped strings.
|
|
293
|
+
line whose value names a step (`step 3`) or is `none`, every numbered step has an
|
|
294
|
+
`**Expect**`, and the file carries no secret-shaped strings. A `Prove it:` that
|
|
295
|
+
is neither is a typo, and a typo reads as a verdict.
|
|
245
296
|
- `dogfood.*` is a known key block; anything else in it is an unknown key.
|
|
@@ -50,6 +50,12 @@ DIR="$SW/<purpose>"
|
|
|
50
50
|
|
|
51
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
52
|
|
|
53
|
+
**A recipe may use fixed paths.** The timestamp-plus-suffix rule exists so two runs
|
|
54
|
+
never collide. A file a *recipe* re-runs — a dev-server log, a pid — must have the
|
|
55
|
+
same path every time, so a step may use a fixed name under `scratch/`, keyed by
|
|
56
|
+
`$WT_NAMESPACE` when the project uses worktrees (`scratch/<namespace>-dev.log`).
|
|
57
|
+
Predictability is the point there; uniqueness is the point everywhere else.
|
|
58
|
+
|
|
53
59
|
**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
60
|
|
|
55
61
|
```bash
|
|
@@ -44,6 +44,11 @@ overwriting an existing copy — from the first install it is the project's file
|
|
|
44
44
|
one path in the config that may be absolute or start with `~/` — it names
|
|
45
45
|
machine-local state, not something a teammate clones.
|
|
46
46
|
|
|
47
|
+
The folder is named after the repo. When another **live** clone of the same name
|
|
48
|
+
already owns it, this one takes `<repo>-<hash>` instead; a home whose recorded
|
|
49
|
+
owner no longer exists is reclaimed, so a finished project does not squat the name
|
|
50
|
+
for ever. `.repo` is what makes that decision, and `create` rewrites it.
|
|
51
|
+
|
|
47
52
|
**Never put checkouts inside `.git` or inside the working tree.** Inside `.git`
|
|
48
53
|
is undocumented and breaks where `.git` is a file (linked worktrees, submodules,
|
|
49
54
|
`--separate-git-dir`). Inside the working tree is destroyed by `git clean -xdf`
|
|
@@ -62,18 +67,29 @@ work; `remove` and `prune` are the only safe exits.
|
|
|
62
67
|
| `WT_BRANCH` | `feat/catalog` | the branch, as git names it |
|
|
63
68
|
| `WT_SLUG` | `feat-catalog` | the directory name, port key, registry key |
|
|
64
69
|
| `WT_NAMESPACE` | `shop-feat-catalog` | database schema, compose project, simulator name |
|
|
65
|
-
| `WT_PORT` | `3041` |
|
|
66
|
-
| `WT_BASE_URL` | `http://localhost:3041` |
|
|
70
|
+
| `WT_PORT` | `3041` | a private port — **only when `ports:` is configured** |
|
|
71
|
+
| `WT_BASE_URL` | `http://localhost:3041` | the URL on that port — same condition |
|
|
72
|
+
|
|
73
|
+
The same five names expand inside the recipe, including the dashed form
|
|
74
|
+
`${WT_PORT:-5180}` that makes a recipe runnable in the main checkout too.
|
|
67
75
|
|
|
68
76
|
Derived, never invented downstream: a hook that needs a database name uses
|
|
69
77
|
`$WT_NAMESPACE` rather than building its own, so two worktrees cannot collide by
|
|
70
78
|
accident.
|
|
71
79
|
|
|
72
|
-
**
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
80
|
+
**A port is a resource, not the model.** `worktrees.ports` is optional, and
|
|
81
|
+
deleting it is how a project says "my preview is not a URL". Then no port is
|
|
82
|
+
derived, nothing is claimed, `WT_PORT` and `WT_BASE_URL` are absent, and the
|
|
83
|
+
checkout is addressed by the recipe's `**Preview:**` line instead. That covers a
|
|
84
|
+
mobile app (a simulator named `$WT_NAMESPACE`), a desktop app (a window), and a
|
|
85
|
+
CLI or library (nothing to look at).
|
|
86
|
+
|
|
87
|
+
When a range *is* configured: the slug hashes into it, the claim is taken with an
|
|
88
|
+
atomic `mkdir`, and a collision probes forward one port at a time. A claim
|
|
89
|
+
belongs to a slug, so a restarted app returns to the same port and two slugs that
|
|
90
|
+
hash alike do not fight. `list` probes for liveness and never trusts a recorded
|
|
91
|
+
pid. Without a port there is nothing to probe, so `LIVE` reads `—` and stopping
|
|
92
|
+
the preview is the project's job — its `before_remove` hook, or the recipe.
|
|
77
93
|
|
|
78
94
|
## Hooks
|
|
79
95
|
|
|
@@ -100,10 +116,17 @@ records the name; the project writes the body.
|
|
|
100
116
|
|
|
101
117
|
## Previewing a worktree
|
|
102
118
|
|
|
103
|
-
`sassy-worktree mode:preview` brings the product up in a checkout and prints
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
119
|
+
`sassy-worktree mode:preview` brings the product up in a checkout and prints how
|
|
120
|
+
to see it, using the dogfood recipe's bring-up steps — everything up to, but not
|
|
121
|
+
including, that section's `Prove it:` step. It leaves the app running.
|
|
122
|
+
|
|
123
|
+
How to see it is the recipe's `**Preview:**` line with the namespace substituted,
|
|
124
|
+
so it is a URL, a simulator, or a window depending on the project and never a
|
|
125
|
+
guess by this tooling. `list` prints that same line in its `HOW TO SEE` column,
|
|
126
|
+
which is why the column is not called "address".
|
|
127
|
+
|
|
128
|
+
What stops a preview follows from the same split: kill it by port when there is
|
|
129
|
+
one, hand it to the project when there is not.
|
|
107
130
|
|
|
108
131
|
There is no separate preview configuration. How the app comes up is the recipe's
|
|
109
132
|
job, because it is the only place that knowledge is allowed to live.
|
|
@@ -126,9 +149,13 @@ writing down once in the recipe rather than rediscovering it.
|
|
|
126
149
|
| It is the main checkout | the repo itself |
|
|
127
150
|
| Dirty tree | uncommitted work |
|
|
128
151
|
| Commits on no remote | nothing to recover from |
|
|
129
|
-
| Something listening on its port | stop the app first |
|
|
152
|
+
| Something listening on its port | stop the app first (only when `ports:` is set) |
|
|
130
153
|
| A `before_remove` hook not yet run | the project has cleanup to do |
|
|
131
154
|
|
|
155
|
+
`remove` deletes the checkout, the port claim, and nothing else. **The branch
|
|
156
|
+
survives** — git keeps it, so the work is still reachable after the worktree is
|
|
157
|
+
gone. Deleting it is the user's call, or `pr.delete_branch`'s after a merge.
|
|
158
|
+
|
|
132
159
|
`--force` skips the dirty and unpushed checks and nothing else. It is never
|
|
133
160
|
implied.
|
|
134
161
|
|
|
@@ -194,7 +194,14 @@ recipe_lint() {
|
|
|
194
194
|
if (index($0, "-->")) incomment = 0
|
|
195
195
|
next
|
|
196
196
|
}
|
|
197
|
-
index($0, "**Prove it:**") {
|
|
197
|
+
index($0, "**Prove it:**") {
|
|
198
|
+
prove = 1
|
|
199
|
+
val = $0; sub(/^.*\*\*Prove it:\*\*[[:space:]]*/, "", val)
|
|
200
|
+
low = tolower(val)
|
|
201
|
+
if (low !~ /^none/ && low !~ /^step[[:space:]]+[0-9]/)
|
|
202
|
+
printf "a **Prove it:** line must name a step (`step 3`) or say `none` — got \"%s\"\n", val
|
|
203
|
+
next
|
|
204
|
+
}
|
|
198
205
|
/^## / {
|
|
199
206
|
if (sec != "" && !prove)
|
|
200
207
|
printf "section \"%s\" has no **Prove it:** line — it has no verdict\n", sname
|
|
@@ -725,6 +732,9 @@ if (( CHECK )); then
|
|
|
725
732
|
if [[ "$TOPOLOGY" != "repo" ]]; then
|
|
726
733
|
bad "worktrees.enabled needs a repo — this folder is '$TOPOLOGY', and a checkout needs git"
|
|
727
734
|
else
|
|
735
|
+
if [[ -z "$wt_ports" ]]; then
|
|
736
|
+
note " worktrees: no port resource — a checkout is addressed by the recipe's preview line"
|
|
737
|
+
fi
|
|
728
738
|
if [[ "$(yflat "commit${US}branch" 2>/dev/null || true)" == "current" ]]; then
|
|
729
739
|
note " worktrees.enabled with commit.branch: current — a run never cuts a branch, so no run creates one"
|
|
730
740
|
fi
|
|
@@ -748,6 +758,16 @@ if (( CHECK )); then
|
|
|
748
758
|
bad "worktrees.enabled but .sassywares/worktree/_lib.sh is missing — re-run setup"
|
|
749
759
|
fi
|
|
750
760
|
|
|
761
|
+
# A declared worktree hook is how a project prepares a checkout, so say
|
|
762
|
+
# that it resolved — silence reads as "nothing is configured".
|
|
763
|
+
for point in after_create before_remove; do
|
|
764
|
+
declared="$(yflat "hooks${US}worktree${US}*${US}${point}" 2>/dev/null || true)"
|
|
765
|
+
while IFS= read -r entry; do
|
|
766
|
+
[[ -n "$entry" ]] || continue
|
|
767
|
+
note " hooks.worktree.\"*\".$point: ${entry%% *}"
|
|
768
|
+
done < <(list_items "$declared")
|
|
769
|
+
done
|
|
770
|
+
|
|
751
771
|
# A checkout must live outside the working tree — inside it, `git clean
|
|
752
772
|
# -xdf` deletes uncommitted work and every scanner that ignores .gitignore
|
|
753
773
|
# crawls a second copy of the source. And a worktree parked on a configured
|
|
@@ -808,6 +828,12 @@ if (( CHECK )); then
|
|
|
808
828
|
# app is a validator nobody runs.
|
|
809
829
|
dg_enabled="$(block_value dogfood enabled || true)"
|
|
810
830
|
dg_recipe="$(block_value dogfood recipe || true)"
|
|
831
|
+
# The default path applies even when the key is absent: the scripts use it, so
|
|
832
|
+
# --check must lint what they will actually read. Only for a project that has
|
|
833
|
+
# dogfood on, or a recipe already sitting at the default, to avoid noise.
|
|
834
|
+
if [[ -z "$dg_recipe" ]] && { [[ "$dg_enabled" == "true" ]] || [[ -f "$ROOT/.sassywares/dogfood/recipe.md" ]]; }; then
|
|
835
|
+
dg_recipe=".sassywares/dogfood/recipe.md"
|
|
836
|
+
fi
|
|
811
837
|
dg_reports="$(block_value dogfood reports || true)"
|
|
812
838
|
dg_timeout="$(block_value dogfood timeout || true)"
|
|
813
839
|
case "$dg_enabled" in
|
|
@@ -1186,6 +1212,8 @@ EOF
|
|
|
1186
1212
|
printf ' # staging: main # uncomment when a branch releases somewhere else\n'
|
|
1187
1213
|
printf ' # release/*: main # a family of heads, longest prefix wins\n'
|
|
1188
1214
|
cat <<'EOF'
|
|
1215
|
+
# remote: owner/backup # workspace only: the snapshot mirror
|
|
1216
|
+
# mirror_branch: main # workspace only: the mirror's branch
|
|
1189
1217
|
|
|
1190
1218
|
# workspace only: each nested repo folder -> the base its PRs target
|
|
1191
1219
|
# repos:
|
|
@@ -1258,8 +1286,8 @@ kv delete_branch false 24 '# true | false — delete the head branch once merged
|
|
|
1258
1286
|
cat <<'EOF'
|
|
1259
1287
|
|
|
1260
1288
|
# --- Hooks ----------------------------------------------------------------
|
|
1261
|
-
# Project steps injected into the PR pipeline,
|
|
1262
|
-
# commit.branch: current, keyed by the
|
|
1289
|
+
# Project steps injected into the PR pipeline, after a push under
|
|
1290
|
+
# commit.branch: current, or across a worktree's life, keyed by the branch — the
|
|
1263
1291
|
# branch the PR comes from, never the one it targets. `"*"` is the default;
|
|
1264
1292
|
# a name overrides per point, and `release/*` matches a family. Each entry is
|
|
1265
1293
|
# `<skill> <args…>`, resolved at .agents/skills/<name>/SKILL.md; args are passed
|
|
@@ -1280,20 +1308,28 @@ cat <<'EOF'
|
|
|
1280
1308
|
# push: # commit.branch: current only; keyed by the pushed branch
|
|
1281
1309
|
# "*":
|
|
1282
1310
|
# after_push: []
|
|
1311
|
+
# worktree: # worktrees only; keyed by the checkout's branch
|
|
1312
|
+
# "*":
|
|
1313
|
+
# after_create: [] # derive .env, seed the database, copy the session in
|
|
1314
|
+
# before_remove: [] # drop the database, shut the device
|
|
1283
1315
|
EOF
|
|
1284
1316
|
cat <<'EOF'
|
|
1285
1317
|
|
|
1286
1318
|
# --- Worktrees ------------------------------------------------------------
|
|
1287
1319
|
# Parallel work in one repo: a checkout per branch, each with its own derived
|
|
1288
|
-
# namespace
|
|
1289
|
-
#
|
|
1290
|
-
#
|
|
1291
|
-
#
|
|
1320
|
+
# namespace, so two runs never fight over one working tree. enabled: true lets a
|
|
1321
|
+
# run create one instead of working here — and needs commit.branch: new, because
|
|
1322
|
+
# `current` never cuts a branch. The scripts in .sassywares/worktree/ own the
|
|
1323
|
+
# mechanics; nothing else reads these values.
|
|
1324
|
+
#
|
|
1325
|
+
# A port is a resource, not the definition of a preview: delete `ports` for a
|
|
1326
|
+
# mobile, desktop, or CLI project, and the checkout is addressed by the recipe's
|
|
1327
|
+
# preview line instead (`$WT_NAMESPACE` names a simulator, a window, a path).
|
|
1292
1328
|
worktrees:
|
|
1293
1329
|
EOF
|
|
1294
1330
|
kv enabled false 34 '# true = a run may work in its own checkout'
|
|
1295
1331
|
kv dir '~/.sassywares/worktrees' 34 '# parent of the per-repo folder; ~ is allowed'
|
|
1296
|
-
kv ports 3000-3099 34 '#
|
|
1332
|
+
kv ports 3000-3099 34 '# a private port per checkout; delete for non-port previews'
|
|
1297
1333
|
cat <<'EOF'
|
|
1298
1334
|
|
|
1299
1335
|
# --- Dogfood --------------------------------------------------------------
|
|
@@ -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) {
|