@sassywares/skills 0.11.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sassywares/skills",
3
- "version": "0.11.0",
3
+ "version": "0.11.1",
4
4
  "description": "Lean, explicit-invocation Agent Skills for shipping fast: plan, work, review, validate, ship.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -496,7 +496,10 @@ a `drift:` line, exiting non-zero. When the suite is installed in project
496
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
497
497
  definition and compared to `computedHash` in `skills-lock.json`, the lock is
498
498
  checked against the installed set in both directions, and git-tracked state of
499
- the lock is reported. A stale, hand-edited, or half-installed suite is drift
500
- even when the config itself matches the tree. A user-scope install
501
- (`~/.agents/skills/`) has no pin to verify; the check notes it, and a suite
502
- found in neither scope is noted, not drift.
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.
@@ -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
- // sha256 over each file's relative path then its bytes, files sorted by relative
12
- // path — so "identical to the pin" is a fact this script asserts, not a claim
13
- // the agent has to make in prose.
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, relative } from "node:path";
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
- if ((await folderHash(join(suite, name))) !== entry.computedHash) {
138
- drift(`${name} does not match the pin — edited locally or half-installed; re-install, or re-pin with npx skills add ${SUITE}`);
117
+ const dir = join(suite, name);
118
+ if ((await hashSkillFolder(dir, legacyFirst)) === entry.computedHash) {
119
+ matched += 1;
139
120
  continue;
140
121
  }
141
- matched += 1;
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) {