@frcloudsolutions/agent-skills 0.0.0-stage → 0.2.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/LICENSE +21 -0
- package/README.md +98 -2
- package/bin/agent-skills.mjs +8 -0
- package/package.json +42 -4
- package/plugins/docs-generator/skills/docs-generator/SKILL.md +68 -0
- package/plugins/docs-generator/skills/docs-generator/assets/README.md +8 -0
- package/plugins/docs-generator/skills/docs-generator/assets/fonts/OFL.txt +93 -0
- package/plugins/docs-generator/skills/docs-generator/assets/fonts/PublicSans-Bold.ttf +0 -0
- package/plugins/docs-generator/skills/docs-generator/assets/fonts/PublicSans-BoldItalic.ttf +0 -0
- package/plugins/docs-generator/skills/docs-generator/assets/fonts/PublicSans-Italic.ttf +0 -0
- package/plugins/docs-generator/skills/docs-generator/assets/fonts/PublicSans-Regular.ttf +0 -0
- package/plugins/docs-generator/skills/docs-generator/assets/paged.polyfill.min.js +4 -0
- package/plugins/docs-generator/skills/docs-generator/locales/en.json +14 -0
- package/plugins/docs-generator/skills/docs-generator/locales/es.json +14 -0
- package/plugins/docs-generator/skills/docs-generator/locales/pt-BR.json +14 -0
- package/plugins/docs-generator/skills/docs-generator/package-lock.json +1697 -0
- package/plugins/docs-generator/skills/docs-generator/package.json +28 -0
- package/plugins/docs-generator/skills/docs-generator/references/from-design-system.md +48 -0
- package/plugins/docs-generator/skills/docs-generator/references/source-format.md +96 -0
- package/plugins/docs-generator/skills/docs-generator/references/theme-format.md +77 -0
- package/plugins/docs-generator/skills/docs-generator/references/writing-guide.md +39 -0
- package/plugins/docs-generator/skills/docs-generator/scripts/docs.mjs +226 -0
- package/plugins/docs-generator/skills/docs-generator/scripts/lib/docx.mjs +377 -0
- package/plugins/docs-generator/skills/docs-generator/scripts/lib/html.mjs +273 -0
- package/plugins/docs-generator/skills/docs-generator/scripts/lib/images.mjs +25 -0
- package/plugins/docs-generator/skills/docs-generator/scripts/lib/office.mjs +184 -0
- package/plugins/docs-generator/skills/docs-generator/scripts/lib/pdf.mjs +70 -0
- package/plugins/docs-generator/skills/docs-generator/scripts/lib/source.mjs +270 -0
- package/plugins/docs-generator/skills/docs-generator/scripts/lib/theme.mjs +219 -0
- package/plugins/docs-generator/skills/docs-generator/themes/clean-modern.json +36 -0
- package/plugins/docs-generator/skills/docs-generator/themes/docs-theme.schema.json +119 -0
- package/src/cli/main.mjs +222 -0
- package/src/cli/prompt.mjs +142 -0
- package/src/lib/catalog.mjs +28 -0
- package/src/lib/frontmatter.mjs +23 -0
- package/src/lib/install.mjs +67 -0
- package/src/lib/tools.mjs +77 -0
- package/src/lib/validate.mjs +86 -0
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
// Small terminal prompts with no dependencies: checkbox list, single select, confirm.
|
|
2
|
+
// Keys: up/down (or k/j) move, space toggles, "a" toggles all, enter confirms,
|
|
3
|
+
// Ctrl+C or Esc cancels (resolves to null). Prompts draw on `output` (stderr by default)
|
|
4
|
+
// so stdout stays clean for --json.
|
|
5
|
+
import { emitKeypressEvents } from "node:readline";
|
|
6
|
+
|
|
7
|
+
const CSI = "\x1b[";
|
|
8
|
+
|
|
9
|
+
function run({ input, output, render, onKey }) {
|
|
10
|
+
return new Promise((resolve) => {
|
|
11
|
+
emitKeypressEvents(input);
|
|
12
|
+
const wasRaw = input.isRaw;
|
|
13
|
+
input.setRawMode?.(true);
|
|
14
|
+
input.resume();
|
|
15
|
+
output.write(`${CSI}?25l`);
|
|
16
|
+
let drawn = 0;
|
|
17
|
+
|
|
18
|
+
const draw = (text) => {
|
|
19
|
+
const cols = Math.max(20, (output.columns || 80) - 1);
|
|
20
|
+
const lines = text.split("\n").map((l) => (visibleLength(l) > cols ? truncate(l, cols) : l));
|
|
21
|
+
if (drawn) output.write(`\r${CSI}${drawn}A${CSI}0J`);
|
|
22
|
+
output.write(lines.join("\n") + "\n");
|
|
23
|
+
drawn = lines.length;
|
|
24
|
+
};
|
|
25
|
+
|
|
26
|
+
const finish = (value, summary) => {
|
|
27
|
+
input.off("keypress", handler);
|
|
28
|
+
input.setRawMode?.(wasRaw ?? false);
|
|
29
|
+
input.pause();
|
|
30
|
+
draw(summary);
|
|
31
|
+
output.write(`${CSI}?25h`);
|
|
32
|
+
resolve(value);
|
|
33
|
+
};
|
|
34
|
+
|
|
35
|
+
const handler = (str, key = {}) => {
|
|
36
|
+
if ((key.ctrl && key.name === "c") || key.name === "escape") return finish(null, render({ cancelled: true }));
|
|
37
|
+
const result = onKey(str, key);
|
|
38
|
+
if (result && "done" in result) return finish(result.value, render({ done: true }));
|
|
39
|
+
draw(render({}));
|
|
40
|
+
};
|
|
41
|
+
|
|
42
|
+
input.on("keypress", handler);
|
|
43
|
+
draw(render({}));
|
|
44
|
+
});
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
const visibleLength = (s) => s.replace(/\x1b\[[0-9;]*m/g, "").length;
|
|
48
|
+
const truncate = (s, n) => s.replace(/\x1b\[[0-9;]*m/g, "").slice(0, n - 1) + "…";
|
|
49
|
+
const dim = (s) => `${CSI}2m${s}${CSI}22m`;
|
|
50
|
+
const bold = (s) => `${CSI}1m${s}${CSI}22m`;
|
|
51
|
+
|
|
52
|
+
function windowed(choices, cursor, rows) {
|
|
53
|
+
const size = Math.min(choices.length, Math.max(3, (rows || 24) - 4));
|
|
54
|
+
const start = Math.min(Math.max(0, cursor - Math.floor(size / 2)), Math.max(0, choices.length - size));
|
|
55
|
+
return { start, end: start + size };
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
function move(cursor, key, length) {
|
|
59
|
+
if (key.name === "up" || key.name === "k") return (cursor - 1 + length) % length;
|
|
60
|
+
if (key.name === "down" || key.name === "j") return (cursor + 1) % length;
|
|
61
|
+
return cursor;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* @param {{message: string, choices: {value: string, label: string, hint?: string, checked?: boolean}[], input, output}} o
|
|
66
|
+
* @returns {Promise<string[]|null>} selected values, [] when confirmed empty, null when cancelled
|
|
67
|
+
*/
|
|
68
|
+
export function checkbox({ message, choices, input = process.stdin, output = process.stderr }) {
|
|
69
|
+
let cursor = 0;
|
|
70
|
+
const checked = new Set(choices.filter((c) => c.checked).map((c) => c.value));
|
|
71
|
+
const selected = () => choices.filter((c) => checked.has(c.value)).map((c) => c.value);
|
|
72
|
+
return run({
|
|
73
|
+
input,
|
|
74
|
+
output,
|
|
75
|
+
render: ({ done, cancelled }) => {
|
|
76
|
+
if (cancelled) return `${bold("?")} ${message} ${dim("cancelled")}`;
|
|
77
|
+
if (done) return `${bold("✔")} ${message} ${selected().join(", ") || dim("none")}`;
|
|
78
|
+
const { start, end } = windowed(choices, cursor, output.rows);
|
|
79
|
+
const lines = [`${bold("?")} ${message} ${dim("(↑/↓ move, space select, a all, enter confirm)")}`];
|
|
80
|
+
if (start > 0) lines.push(dim(" ↑ more"));
|
|
81
|
+
for (let i = start; i < end; i++) {
|
|
82
|
+
const c = choices[i];
|
|
83
|
+
const pointer = i === cursor ? "❯" : " ";
|
|
84
|
+
const box = checked.has(c.value) ? "◉" : "◯";
|
|
85
|
+
lines.push(`${pointer} ${box} ${c.label}${c.hint ? dim(` — ${c.hint}`) : ""}`);
|
|
86
|
+
}
|
|
87
|
+
if (end < choices.length) lines.push(dim(" ↓ more"));
|
|
88
|
+
return lines.join("\n");
|
|
89
|
+
},
|
|
90
|
+
onKey: (str, key) => {
|
|
91
|
+
if (key.name === "return" || key.name === "enter") return { done: true, value: selected() };
|
|
92
|
+
if (key.name === "space") {
|
|
93
|
+
const v = choices[cursor].value;
|
|
94
|
+
checked.has(v) ? checked.delete(v) : checked.add(v);
|
|
95
|
+
} else if (str === "a") {
|
|
96
|
+
if (checked.size === choices.length) checked.clear();
|
|
97
|
+
else choices.forEach((c) => checked.add(c.value));
|
|
98
|
+
} else cursor = move(cursor, key, choices.length);
|
|
99
|
+
},
|
|
100
|
+
});
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/** @returns {Promise<string|null>} */
|
|
104
|
+
export function select({ message, choices, initial, input = process.stdin, output = process.stderr }) {
|
|
105
|
+
let cursor = Math.max(0, choices.findIndex((c) => c.value === initial));
|
|
106
|
+
return run({
|
|
107
|
+
input,
|
|
108
|
+
output,
|
|
109
|
+
render: ({ done, cancelled }) => {
|
|
110
|
+
if (cancelled) return `${bold("?")} ${message} ${dim("cancelled")}`;
|
|
111
|
+
if (done) return `${bold("✔")} ${message} ${choices[cursor].value}`;
|
|
112
|
+
const lines = [`${bold("?")} ${message} ${dim("(↑/↓ move, enter confirm)")}`];
|
|
113
|
+
choices.forEach((c, i) => {
|
|
114
|
+
lines.push(`${i === cursor ? "❯" : " "} ${c.label}${c.hint ? dim(` — ${c.hint}`) : ""}`);
|
|
115
|
+
});
|
|
116
|
+
return lines.join("\n");
|
|
117
|
+
},
|
|
118
|
+
onKey: (_str, key) => {
|
|
119
|
+
if (key.name === "return" || key.name === "enter") return { done: true, value: choices[cursor].value };
|
|
120
|
+
cursor = move(cursor, key, choices.length);
|
|
121
|
+
},
|
|
122
|
+
});
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
/** @returns {Promise<boolean|null>} */
|
|
126
|
+
export function confirm({ message, initial = true, input = process.stdin, output = process.stderr }) {
|
|
127
|
+
let answer = initial;
|
|
128
|
+
return run({
|
|
129
|
+
input,
|
|
130
|
+
output,
|
|
131
|
+
render: ({ done, cancelled }) => {
|
|
132
|
+
if (cancelled) return `${bold("?")} ${message} ${dim("cancelled")}`;
|
|
133
|
+
if (done) return `${bold("✔")} ${message} ${answer ? "yes" : "no"}`;
|
|
134
|
+
return `${bold("?")} ${message} ${dim(initial ? "(Y/n)" : "(y/N)")}`;
|
|
135
|
+
},
|
|
136
|
+
onKey: (str, key) => {
|
|
137
|
+
if (key.name === "return" || key.name === "enter") return { done: true, value: answer };
|
|
138
|
+
if (str === "y" || str === "Y") return { done: true, value: (answer = true) };
|
|
139
|
+
if (str === "n" || str === "N") return { done: true, value: (answer = false) };
|
|
140
|
+
},
|
|
141
|
+
});
|
|
142
|
+
}
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
// Finds the skills bundled under <root>/plugins/<plugin>/skills/<skill>/SKILL.md.
|
|
2
|
+
import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
|
|
3
|
+
import { join } from "node:path";
|
|
4
|
+
import { parseFrontmatter } from "./frontmatter.mjs";
|
|
5
|
+
|
|
6
|
+
export function subdirs(path) {
|
|
7
|
+
if (!existsSync(path)) return [];
|
|
8
|
+
return readdirSync(path)
|
|
9
|
+
.filter((d) => !d.startsWith(".") && statSync(join(path, d)).isDirectory())
|
|
10
|
+
.sort();
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
/** @returns {{name: string, plugin: string, description: string, dir: string}[]} sorted by name */
|
|
14
|
+
export function findSkills(root) {
|
|
15
|
+
const skills = [];
|
|
16
|
+
const pluginsDir = join(root, "plugins");
|
|
17
|
+
for (const plugin of subdirs(pluginsDir)) {
|
|
18
|
+
const skillsDir = join(pluginsDir, plugin, "skills");
|
|
19
|
+
for (const folder of subdirs(skillsDir)) {
|
|
20
|
+
const dir = join(skillsDir, folder);
|
|
21
|
+
const file = join(dir, "SKILL.md");
|
|
22
|
+
if (!existsSync(file)) continue;
|
|
23
|
+
const fm = parseFrontmatter(readFileSync(file, "utf8")) ?? {};
|
|
24
|
+
skills.push({ name: fm.name || folder, plugin, description: fm.description || "", dir });
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
return skills.sort((a, b) => a.name.localeCompare(b.name));
|
|
28
|
+
}
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
// Minimal YAML frontmatter reader for SKILL.md files: top-level `key: value`
|
|
2
|
+
// pairs, quoted values and `>` / `|` block scalars. No dependencies.
|
|
3
|
+
|
|
4
|
+
export function parseFrontmatter(text) {
|
|
5
|
+
const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---(\r?\n|$)/);
|
|
6
|
+
if (!m) return null;
|
|
7
|
+
const data = {};
|
|
8
|
+
const lines = m[1].split(/\r?\n/);
|
|
9
|
+
for (let i = 0; i < lines.length; i++) {
|
|
10
|
+
const kv = lines[i].match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
|
|
11
|
+
if (!kv) continue;
|
|
12
|
+
let [, key, value] = kv;
|
|
13
|
+
if (/^[>|][+-]?$/.test(value)) {
|
|
14
|
+
const block = [];
|
|
15
|
+
while (i + 1 < lines.length && (/^\s+/.test(lines[i + 1]) || lines[i + 1] === "")) block.push(lines[++i].trim());
|
|
16
|
+
value = block.join(value.startsWith(">") ? " " : "\n").trim();
|
|
17
|
+
} else if (/^(['"]).*\1$/.test(value)) {
|
|
18
|
+
value = value.slice(1, -1);
|
|
19
|
+
}
|
|
20
|
+
data[key] = value.trim();
|
|
21
|
+
}
|
|
22
|
+
return data;
|
|
23
|
+
}
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
// Plans and performs skill installs and removals in tools' skills folders.
|
|
2
|
+
import { cpSync, existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
|
|
3
|
+
import { basename, join } from "node:path";
|
|
4
|
+
import { skillsDir } from "./tools.mjs";
|
|
5
|
+
|
|
6
|
+
export const PACKAGE_NAME = "@frcloudsolutions/agent-skills";
|
|
7
|
+
export const MARKER = ".agent-skills.json";
|
|
8
|
+
const SKIP = new Set(["node_modules", MARKER]);
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* One target per (skill, folder). Tools that resolve to the same folder share a target.
|
|
12
|
+
* @returns {{skill: object, tools: string[], path: string}[]}
|
|
13
|
+
*/
|
|
14
|
+
export function planTargets(skills, tools, scope, env) {
|
|
15
|
+
const targets = new Map();
|
|
16
|
+
for (const skill of skills) {
|
|
17
|
+
for (const tool of tools) {
|
|
18
|
+
const path = join(skillsDir(tool, scope, env), skill.name);
|
|
19
|
+
if (!targets.has(path)) targets.set(path, { skill, tools: [], path });
|
|
20
|
+
targets.get(path).tools.push(tool);
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
return [...targets.values()];
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
export function readMarker(path) {
|
|
27
|
+
try {
|
|
28
|
+
const data = JSON.parse(readFileSync(join(path, MARKER), "utf8"));
|
|
29
|
+
return data?.package === PACKAGE_NAME ? data : null;
|
|
30
|
+
} catch {
|
|
31
|
+
return null;
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/** @returns {"installed"|"replaced"|"skipped"|"would-install"|"would-replace"} */
|
|
36
|
+
export function install(target, { force = false, dryRun = false, version, now = new Date() }) {
|
|
37
|
+
const exists = existsSync(target.path);
|
|
38
|
+
if (exists && !force) return { status: "skipped", message: "already exists (use --force to replace it)" };
|
|
39
|
+
if (dryRun) return { status: exists ? "would-replace" : "would-install" };
|
|
40
|
+
if (exists) rmSync(target.path, { recursive: true, force: true });
|
|
41
|
+
cpSync(target.skill.dir, target.path, {
|
|
42
|
+
recursive: true,
|
|
43
|
+
filter: (src) => !SKIP.has(basename(src)),
|
|
44
|
+
});
|
|
45
|
+
const marker = { package: PACKAGE_NAME, version, skill: target.skill.name, installedAt: now.toISOString() };
|
|
46
|
+
writeFileSync(join(target.path, MARKER), JSON.stringify(marker, null, 2) + "\n");
|
|
47
|
+
return { status: exists ? "replaced" : "installed" };
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/** @returns {"removed"|"would-remove"|"not-found"|"not-managed"} */
|
|
51
|
+
export function remove(target, { dryRun = false }) {
|
|
52
|
+
if (!existsSync(target.path)) return { status: "not-found", message: "not installed here" };
|
|
53
|
+
if (!readMarker(target.path)) return { status: "not-managed", message: "not installed by agent-skills; left in place" };
|
|
54
|
+
if (dryRun) return { status: "would-remove" };
|
|
55
|
+
rmSync(target.path, { recursive: true, force: true });
|
|
56
|
+
return { status: "removed" };
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
// "not-found" counts as success: removal is idempotent, the requested end state already holds.
|
|
60
|
+
export const OK_STATUSES = new Set(["installed", "replaced", "would-install", "would-replace", "removed", "would-remove", "not-found"]);
|
|
61
|
+
|
|
62
|
+
/** Skills from the catalog that this CLI installed for at least one of the tools. */
|
|
63
|
+
export function installedSkills(catalog, tools, scope, env) {
|
|
64
|
+
return catalog.filter((skill) =>
|
|
65
|
+
tools.some((tool) => readMarker(join(skillsDir(tool, scope, env), skill.name))),
|
|
66
|
+
);
|
|
67
|
+
}
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
// Where each supported tool reads Agent Skills from.
|
|
2
|
+
// User-scope paths are relative to the home directory, project-scope paths to the
|
|
3
|
+
// current working directory. Checked against each vendor's docs on 2026-11-19.
|
|
4
|
+
import { existsSync } from "node:fs";
|
|
5
|
+
import { join } from "node:path";
|
|
6
|
+
|
|
7
|
+
export const TOOLS = {
|
|
8
|
+
claude: {
|
|
9
|
+
label: "Claude Code",
|
|
10
|
+
user: ".claude/skills",
|
|
11
|
+
project: ".claude/skills",
|
|
12
|
+
detect: [".claude"],
|
|
13
|
+
source: "https://docs.claude.com/en/docs/claude-code/skills",
|
|
14
|
+
},
|
|
15
|
+
codex: {
|
|
16
|
+
label: "OpenAI Codex",
|
|
17
|
+
user: ".agents/skills",
|
|
18
|
+
project: ".agents/skills",
|
|
19
|
+
detect: [".codex", ".agents"],
|
|
20
|
+
source: "https://developers.openai.com/codex/skills",
|
|
21
|
+
},
|
|
22
|
+
gemini: {
|
|
23
|
+
label: "Gemini CLI",
|
|
24
|
+
user: ".gemini/skills",
|
|
25
|
+
project: ".gemini/skills",
|
|
26
|
+
detect: [".gemini"],
|
|
27
|
+
alsoReads: [".agents/skills"],
|
|
28
|
+
note: "Gemini CLI may need Agent Skills enabled in its settings: https://geminicli.com/docs/cli/skills/",
|
|
29
|
+
source: "https://geminicli.com/docs/cli/skills/",
|
|
30
|
+
},
|
|
31
|
+
cursor: {
|
|
32
|
+
label: "Cursor",
|
|
33
|
+
user: ".cursor/skills",
|
|
34
|
+
project: ".cursor/skills",
|
|
35
|
+
detect: [".cursor"],
|
|
36
|
+
alsoReads: [".claude/skills", ".codex/skills"],
|
|
37
|
+
source: "https://cursor.com/docs/skills",
|
|
38
|
+
},
|
|
39
|
+
copilot: {
|
|
40
|
+
label: "GitHub Copilot",
|
|
41
|
+
user: ".copilot/skills",
|
|
42
|
+
project: ".github/skills",
|
|
43
|
+
detect: [".copilot"],
|
|
44
|
+
alsoReads: [".claude/skills", ".agents/skills"],
|
|
45
|
+
source: "https://docs.github.com/en/copilot/concepts/agents/about-agent-skills",
|
|
46
|
+
},
|
|
47
|
+
};
|
|
48
|
+
|
|
49
|
+
export const TOOL_IDS = Object.keys(TOOLS);
|
|
50
|
+
export const SCOPES = ["user", "project"];
|
|
51
|
+
|
|
52
|
+
/** Absolute skills folder for an tool and scope. */
|
|
53
|
+
export function skillsDir(tool, scope, { home, cwd }) {
|
|
54
|
+
const a = TOOLS[tool];
|
|
55
|
+
return scope === "project" ? join(cwd, a.project) : join(home, a.user);
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/** Tools whose user configuration folder exists in `home`. */
|
|
59
|
+
export function detectTools(home) {
|
|
60
|
+
return TOOL_IDS.filter((id) => TOOLS[id].detect.some((d) => existsSync(join(home, d))));
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* Pairs of selected tools where one also reads the other's folder, so a skill
|
|
65
|
+
* installed for both may be listed twice by the first.
|
|
66
|
+
*/
|
|
67
|
+
export function overlaps(tools, scope) {
|
|
68
|
+
const out = [];
|
|
69
|
+
for (const reader of tools) {
|
|
70
|
+
for (const other of tools) {
|
|
71
|
+
if (reader === other) continue;
|
|
72
|
+
const otherPath = TOOLS[other][scope];
|
|
73
|
+
if ((TOOLS[reader].alsoReads ?? []).includes(otherPath)) out.push({ reader, other, path: otherPath });
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
return out;
|
|
77
|
+
}
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
// Repository checks for skills and the plugin marketplace manifest.
|
|
2
|
+
import { existsSync, readFileSync } from "node:fs";
|
|
3
|
+
import { join, relative, resolve, sep } from "node:path";
|
|
4
|
+
import { parseFrontmatter } from "./frontmatter.mjs";
|
|
5
|
+
import { subdirs } from "./catalog.mjs";
|
|
6
|
+
|
|
7
|
+
// Paths in messages always use "/" so output is the same on every OS.
|
|
8
|
+
const relPath = (root, p) => relative(root, p).split(sep).join("/");
|
|
9
|
+
|
|
10
|
+
const NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
|
|
11
|
+
|
|
12
|
+
export function validateSkill(skillDir, { root, expectedName = skillDir.split(/[\\/]/).pop() }) {
|
|
13
|
+
const rel = (p) => relPath(root, p);
|
|
14
|
+
const file = join(skillDir, "SKILL.md");
|
|
15
|
+
const out = [];
|
|
16
|
+
if (!existsSync(file)) return [`${rel(skillDir)}: missing SKILL.md`];
|
|
17
|
+
const fm = parseFrontmatter(readFileSync(file, "utf8"));
|
|
18
|
+
if (!fm) return [`${rel(file)}: missing YAML frontmatter`];
|
|
19
|
+
if (!fm.name) out.push(`${rel(file)}: frontmatter is missing "name"`);
|
|
20
|
+
else {
|
|
21
|
+
if (!NAME_RE.test(fm.name)) out.push(`${rel(file)}: name "${fm.name}" must be kebab-case`);
|
|
22
|
+
if (fm.name.length > 64) out.push(`${rel(file)}: name is longer than 64 characters`);
|
|
23
|
+
if (expectedName && fm.name !== expectedName)
|
|
24
|
+
out.push(`${rel(file)}: name "${fm.name}" does not match folder "${expectedName}"`);
|
|
25
|
+
}
|
|
26
|
+
if (!fm.description) out.push(`${rel(file)}: frontmatter is missing "description"`);
|
|
27
|
+
else if (fm.description.length > 1024) out.push(`${rel(file)}: description is longer than 1024 characters`);
|
|
28
|
+
return out;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/** @returns {{errors: string[], skillCount: number}} */
|
|
32
|
+
export function validateRepo(root, { template = "skill-name" } = {}) {
|
|
33
|
+
const rel = (p) => relPath(root, p);
|
|
34
|
+
const errors = [];
|
|
35
|
+
const pluginsDir = join(root, "plugins");
|
|
36
|
+
|
|
37
|
+
// Skills, and unique names across plugins
|
|
38
|
+
let skillCount = 0;
|
|
39
|
+
const byName = new Map();
|
|
40
|
+
for (const plugin of subdirs(pluginsDir)) {
|
|
41
|
+
for (const skill of subdirs(join(pluginsDir, plugin, "skills"))) {
|
|
42
|
+
skillCount++;
|
|
43
|
+
const dir = join(pluginsDir, plugin, "skills", skill);
|
|
44
|
+
errors.push(...validateSkill(dir, { root }));
|
|
45
|
+
if (!byName.has(skill)) byName.set(skill, []);
|
|
46
|
+
byName.get(skill).push(rel(dir));
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
for (const [name, dirs] of byName) {
|
|
50
|
+
if (dirs.length > 1) errors.push(`skill name "${name}" is used more than once: ${dirs.join(", ")}`);
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
// Template (validated against its placeholder name)
|
|
54
|
+
const templateDir = join(root, "templates", "skill");
|
|
55
|
+
if (existsSync(templateDir)) errors.push(...validateSkill(templateDir, { root, expectedName: template }));
|
|
56
|
+
|
|
57
|
+
// Manifest
|
|
58
|
+
const manifestPath = join(root, ".claude-plugin", "marketplace.json");
|
|
59
|
+
let manifest;
|
|
60
|
+
try {
|
|
61
|
+
manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
|
|
62
|
+
} catch (e) {
|
|
63
|
+
errors.push(`${rel(manifestPath)}: ${e.message}`);
|
|
64
|
+
}
|
|
65
|
+
if (manifest) {
|
|
66
|
+
if (!manifest.name) errors.push(`${rel(manifestPath)}: missing "name"`);
|
|
67
|
+
if (!manifest.owner?.name) errors.push(`${rel(manifestPath)}: missing "owner.name"`);
|
|
68
|
+
if (!Array.isArray(manifest.plugins)) errors.push(`${rel(manifestPath)}: "plugins" must be an array`);
|
|
69
|
+
else {
|
|
70
|
+
const listed = new Set();
|
|
71
|
+
for (const p of manifest.plugins) {
|
|
72
|
+
if (!p.name || !p.source) {
|
|
73
|
+
errors.push(`${rel(manifestPath)}: plugin entry needs "name" and "source": ${JSON.stringify(p)}`);
|
|
74
|
+
continue;
|
|
75
|
+
}
|
|
76
|
+
listed.add(resolve(root, p.source));
|
|
77
|
+
if (!existsSync(resolve(root, p.source)))
|
|
78
|
+
errors.push(`${rel(manifestPath)}: plugin "${p.name}" source "${p.source}" does not exist`);
|
|
79
|
+
}
|
|
80
|
+
for (const plugin of subdirs(pluginsDir)) {
|
|
81
|
+
if (!listed.has(join(pluginsDir, plugin))) errors.push(`plugins/${plugin}: not listed in ${rel(manifestPath)}`);
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
return { errors, skillCount };
|
|
86
|
+
}
|