agent-skills-doctor 1.2.0 → 1.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -0
- package/cli.mjs +91 -13
- package/package.json +1 -1
package/README.md
CHANGED
package/cli.mjs
CHANGED
|
@@ -91,7 +91,52 @@ function expand(path, project) {
|
|
|
91
91
|
return isAbsolute(path) ? path : join(project, path);
|
|
92
92
|
}
|
|
93
93
|
|
|
94
|
-
const
|
|
94
|
+
const IGNORED_DIRS = new Set(['.git', 'node_modules']);
|
|
95
|
+
|
|
96
|
+
// Deterministic hash + latest mtime across the whole skill directory so drift
|
|
97
|
+
// catches changes in companion scripts/references as well as SKILL.md.
|
|
98
|
+
function hashSkillDir(rootDir) {
|
|
99
|
+
const hasher = createHash('sha256');
|
|
100
|
+
const visited = new Set();
|
|
101
|
+
let latestMtime = 0;
|
|
102
|
+
|
|
103
|
+
function walkDir(dir, prefix) {
|
|
104
|
+
const real = safeRealpath(dir);
|
|
105
|
+
if (visited.has(real)) return;
|
|
106
|
+
visited.add(real);
|
|
107
|
+
|
|
108
|
+
let entries;
|
|
109
|
+
try {
|
|
110
|
+
entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
|
|
111
|
+
} catch {
|
|
112
|
+
return;
|
|
113
|
+
}
|
|
114
|
+
for (const entry of entries) {
|
|
115
|
+
if (IGNORED_DIRS.has(entry.name) || entry.name === '.DS_Store') continue;
|
|
116
|
+
const full = join(dir, entry.name);
|
|
117
|
+
const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
|
|
118
|
+
let stats;
|
|
119
|
+
try {
|
|
120
|
+
stats = statSync(full);
|
|
121
|
+
} catch {
|
|
122
|
+
continue;
|
|
123
|
+
}
|
|
124
|
+
if (stats.isDirectory()) {
|
|
125
|
+
walkDir(full, rel);
|
|
126
|
+
} else if (stats.isFile()) {
|
|
127
|
+
hasher.update(`${rel}\0`);
|
|
128
|
+
try {
|
|
129
|
+
const buf = readFileSync(full);
|
|
130
|
+
hasher.update(buf);
|
|
131
|
+
if (stats.mtimeMs > latestMtime) latestMtime = stats.mtimeMs;
|
|
132
|
+
} catch {}
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
walkDir(rootDir, '');
|
|
138
|
+
return { hash: hasher.digest('hex'), mtimeMs: latestMtime };
|
|
139
|
+
}
|
|
95
140
|
|
|
96
141
|
// Only `name` and `description` are read; a full YAML parser is not worth it
|
|
97
142
|
// here. Values are unquoted so `name: "foo"` and `name: foo` behave the same.
|
|
@@ -201,13 +246,15 @@ function loadSkill(dir, file) {
|
|
|
201
246
|
}
|
|
202
247
|
const chars = name.trim().length + description.trim().length;
|
|
203
248
|
const payloadChars = text.length;
|
|
249
|
+
const dirDigest = hashSkillDir(dir);
|
|
204
250
|
return {
|
|
205
251
|
name: name.trim() || dirName,
|
|
206
252
|
declaredName: name.trim(),
|
|
207
253
|
dir,
|
|
208
254
|
path: join(dir, file),
|
|
209
255
|
description: description.trim(),
|
|
210
|
-
hash: hash
|
|
256
|
+
hash: dirDigest.hash,
|
|
257
|
+
mtimeMs: dirDigest.mtimeMs,
|
|
211
258
|
chars,
|
|
212
259
|
tokens: Math.ceil(chars / 4),
|
|
213
260
|
payloadChars,
|
|
@@ -302,6 +349,7 @@ export function findDuplicates(roots) {
|
|
|
302
349
|
path: skill.path || skill.dir,
|
|
303
350
|
dir: skill.dir,
|
|
304
351
|
hash: skill.hash,
|
|
352
|
+
mtimeMs: skill.mtimeMs || 0,
|
|
305
353
|
real: safeRealpath(skill.dir),
|
|
306
354
|
linked: skill.linked,
|
|
307
355
|
});
|
|
@@ -359,11 +407,15 @@ export function cmdCatalog(project, { includeUser = true } = {}) {
|
|
|
359
407
|
const shadowed = [];
|
|
360
408
|
for (const root of roots) {
|
|
361
409
|
for (const skill of root.skills) {
|
|
410
|
+
const real = safeRealpath(skill.dir);
|
|
362
411
|
if (winners.has(skill.name)) {
|
|
363
|
-
|
|
412
|
+
const winner = winners.get(skill.name);
|
|
413
|
+
if (winner.real !== real) {
|
|
414
|
+
shadowed.push({ name: skill.name, kept: winner.root, dropped: root.rel });
|
|
415
|
+
}
|
|
364
416
|
continue;
|
|
365
417
|
}
|
|
366
|
-
winners.set(skill.name, { skill, root: root.rel });
|
|
418
|
+
winners.set(skill.name, { skill, root: root.rel, real });
|
|
367
419
|
}
|
|
368
420
|
}
|
|
369
421
|
const entries = [...winners.values()];
|
|
@@ -442,7 +494,10 @@ export function audit(options = {}) {
|
|
|
442
494
|
);
|
|
443
495
|
const scanned = roots.map((root) => scanRoot(root, project));
|
|
444
496
|
const present = scanned.filter((root) => root.exists);
|
|
445
|
-
const
|
|
497
|
+
const ignored = new Set(options.ignore || []);
|
|
498
|
+
const duplicates = findDuplicates(present).map((d) =>
|
|
499
|
+
ignored.has(d.name) ? { ...d, ignored: true } : d,
|
|
500
|
+
);
|
|
446
501
|
const cmd = cmdCatalog(project, { includeUser: options.includeGlobal !== false });
|
|
447
502
|
const invalid = present.flatMap((root) =>
|
|
448
503
|
root.skills.filter((s) => s.problems.length).map((s) => ({ root: root.rel, dir: s.dir, name: s.name, problems: s.problems })),
|
|
@@ -480,20 +535,29 @@ function pct(tokens, window) {
|
|
|
480
535
|
return `${((tokens / window) * 100).toFixed(1)}%`;
|
|
481
536
|
}
|
|
482
537
|
|
|
538
|
+
function formatDate(ms) {
|
|
539
|
+
if (!ms) return '';
|
|
540
|
+
return new Date(ms).toISOString().slice(0, 10);
|
|
541
|
+
}
|
|
542
|
+
|
|
483
543
|
function groupByHash(copies) {
|
|
484
544
|
const groups = new Map();
|
|
485
545
|
for (const copy of copies) {
|
|
486
|
-
const group = groups.get(copy.hash) || { hash: copy.hash, roots: [] };
|
|
487
|
-
groups.set(copy.hash, {
|
|
546
|
+
const group = groups.get(copy.hash) || { hash: copy.hash, roots: [], mtimeMs: 0 };
|
|
547
|
+
groups.set(copy.hash, {
|
|
548
|
+
hash: copy.hash,
|
|
549
|
+
roots: [...group.roots, copy.root],
|
|
550
|
+
mtimeMs: Math.max(group.mtimeMs, copy.mtimeMs || 0),
|
|
551
|
+
});
|
|
488
552
|
}
|
|
489
|
-
return [...groups.values()].sort((a, b) => b.roots.length - a.roots.length);
|
|
553
|
+
return [...groups.values()].sort((a, b) => b.mtimeMs - a.mtimeMs || b.roots.length - a.roots.length);
|
|
490
554
|
}
|
|
491
555
|
|
|
492
556
|
function report(result) {
|
|
493
557
|
const lines = [];
|
|
494
558
|
const scanned = result.scanned.filter((r) => r.exists);
|
|
495
559
|
const absent = result.scanned.length - scanned.length;
|
|
496
|
-
const drift = result.duplicates.filter((d) => d.status === 'drift');
|
|
560
|
+
const drift = result.duplicates.filter((d) => d.status === 'drift' && !d.ignored);
|
|
497
561
|
const identical = result.duplicates.filter((d) => d.status === 'identical');
|
|
498
562
|
const linked = result.duplicates.filter((d) => d.status === 'linked');
|
|
499
563
|
|
|
@@ -580,8 +644,16 @@ function report(result) {
|
|
|
580
644
|
issues.push(`drift: ${drift.length} skill(s) have copies with different content`);
|
|
581
645
|
for (const d of drift) {
|
|
582
646
|
issues.push(` ${d.name} (${d.copies.length} copies)`);
|
|
583
|
-
|
|
584
|
-
|
|
647
|
+
const groups = groupByHash(d.copies);
|
|
648
|
+
const maxMtime = Math.max(...groups.map((g) => g.mtimeMs));
|
|
649
|
+
const minMtime = Math.min(...groups.map((g) => g.mtimeMs));
|
|
650
|
+
const showNewest = groups.length > 1 && maxMtime - minMtime > 1000;
|
|
651
|
+
for (const group of groups) {
|
|
652
|
+
const meta = [group.hash.slice(0, 8)];
|
|
653
|
+
const date = formatDate(group.mtimeMs);
|
|
654
|
+
if (date) meta.push(date);
|
|
655
|
+
if (showNewest && group.mtimeMs === maxMtime) meta.push('newest');
|
|
656
|
+
issues.push(` [${group.roots.length}] ${group.roots.join(', ')} (${meta.join(', ')})`);
|
|
585
657
|
}
|
|
586
658
|
}
|
|
587
659
|
}
|
|
@@ -623,6 +695,7 @@ function help() {
|
|
|
623
695
|
' --no-global skip user-level global roots',
|
|
624
696
|
' --no-project skip project-level roots',
|
|
625
697
|
' --root <dir> extra root to scan (repeatable)',
|
|
698
|
+
' --ignore <name> ignore drift for a skill (repeatable)',
|
|
626
699
|
' -h, --help show this help text',
|
|
627
700
|
'',
|
|
628
701
|
'exit: 0 clean, 1 problems found, 2 usage error',
|
|
@@ -630,7 +703,7 @@ function help() {
|
|
|
630
703
|
}
|
|
631
704
|
|
|
632
705
|
function parseArgs(argv) {
|
|
633
|
-
const options = { extraRoots: [] };
|
|
706
|
+
const options = { extraRoots: [], ignore: [] };
|
|
634
707
|
for (let i = 0; i < argv.length; i++) {
|
|
635
708
|
const arg = argv[i];
|
|
636
709
|
if (arg === '--json') options.json = true;
|
|
@@ -648,6 +721,11 @@ function parseArgs(argv) {
|
|
|
648
721
|
options.by = val;
|
|
649
722
|
}
|
|
650
723
|
else if (arg === '--root') options.extraRoots.push(argv[++i]);
|
|
724
|
+
else if (arg === '--ignore') {
|
|
725
|
+
const val = argv[++i];
|
|
726
|
+
if (!val || val.startsWith('-')) return { error: 'missing value for --ignore' };
|
|
727
|
+
options.ignore.push(val);
|
|
728
|
+
}
|
|
651
729
|
else if (arg === '--help' || arg === '-h') options.help = true;
|
|
652
730
|
else return { error: `unknown argument: ${arg}` };
|
|
653
731
|
}
|
|
@@ -671,7 +749,7 @@ function main(argv) {
|
|
|
671
749
|
result.invalid.length +
|
|
672
750
|
result.broken.length +
|
|
673
751
|
(result.missing?.length || 0) +
|
|
674
|
-
result.duplicates.filter((d) => d.status === 'drift').length;
|
|
752
|
+
result.duplicates.filter((d) => d.status === 'drift' && !d.ignored).length;
|
|
675
753
|
if (result.budget?.exceeded) count++;
|
|
676
754
|
|
|
677
755
|
if (options.json) {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "agent-skills-doctor",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.3.0",
|
|
4
4
|
"description": "Zero-dependency health check, linter, and token auditor for AI agent skills across Claude Code, OpenCode, Cursor, and 13 other harnesses",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "cli.mjs",
|