librebot-tools 0.0.0-stage → 0.4.4
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 +270 -2
- package/bin/librebot.js +262 -0
- package/package.json +34 -4
- package/schema/v1/bot-yaml-schema.json +193 -0
- package/schema/v1/skills-sources-schema.json +31 -0
- package/src/errors.js +28 -0
- package/src/icon.js +130 -0
- package/src/index.d.ts +275 -0
- package/src/index.js +50 -0
- package/src/parse.js +702 -0
- package/src/scaffold.js +279 -0
- package/src/schema.js +14 -0
- package/src/skills-import.js +50 -0
- package/src/skills-lock.js +697 -0
- package/src/util.js +27 -0
- package/src/validate.js +851 -0
- package/test/assets.test.mjs +82 -0
- package/test/export.test.mjs +155 -0
- package/test/gitlab-preview.test.mjs +23 -0
- package/test/gitlab-triggers.test.mjs +53 -0
- package/test/icon.test.mjs +137 -0
- package/test/lock.test.mjs +92 -0
- package/test/malformed.test.mjs +79 -0
- package/test/readme.test.mjs +109 -0
- package/test/semantics.test.mjs +186 -0
- package/test/standard-skills.test.mjs +41 -0
- package/test/vendor.test.mjs +135 -0
- package/test/whatsapp-actions.test.mjs +31 -0
package/src/scaffold.js
ADDED
|
@@ -0,0 +1,279 @@
|
|
|
1
|
+
// Scaffold (new bot skeleton) and export (BotDraft -> source tree) helpers.
|
|
2
|
+
// Both return in-memory maps; the `*Bot` fs variants write them to disk.
|
|
3
|
+
|
|
4
|
+
import { mkdir, readdir, writeFile } from "node:fs/promises";
|
|
5
|
+
import { join } from "node:path";
|
|
6
|
+
import { stringify as stringifyYaml } from "yaml";
|
|
7
|
+
import { toBytes } from "./util.js";
|
|
8
|
+
import { DEFAULT_ICON, iconPath, validateIcon } from "./icon.js";
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
function skeletonInstructions(name) {
|
|
12
|
+
return `# ${name}\n\nDescribe what this bot does, how it should behave, and any\npolicies it must follow. This file becomes the bot's main prompt.\n`;
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
// User-facing manual published on the bot page; placeholders tell the author
|
|
16
|
+
// what bot users need to know before clicking Use.
|
|
17
|
+
function skeletonReadme(name, description) {
|
|
18
|
+
return `# ${name}
|
|
19
|
+
|
|
20
|
+
${description}
|
|
21
|
+
|
|
22
|
+
## Good for
|
|
23
|
+
|
|
24
|
+
- Replace with the jobs this bot helps with and the result users get.
|
|
25
|
+
|
|
26
|
+
## Not for
|
|
27
|
+
|
|
28
|
+
- Replace with requests this bot does not handle.
|
|
29
|
+
|
|
30
|
+
## What you need
|
|
31
|
+
|
|
32
|
+
- **AI access**: an AI credential that can run the bot's main model.
|
|
33
|
+
- **Connections**: none. If the bot declares repositories, actions, triggers,
|
|
34
|
+
or MCP connectors, list each connection here with why it is needed, the
|
|
35
|
+
permissions it uses, and whether it is required or optional.
|
|
36
|
+
|
|
37
|
+
## Get started
|
|
38
|
+
|
|
39
|
+
1. Click **Use** and choose the main model in **Models**.
|
|
40
|
+
2. Open **Tasks** and start a **New task**.
|
|
41
|
+
|
|
42
|
+
## Example requests
|
|
43
|
+
|
|
44
|
+
- Replace with a request this bot handles well.
|
|
45
|
+
|
|
46
|
+
## What the bot changes
|
|
47
|
+
|
|
48
|
+
Nothing outside its task conversation.
|
|
49
|
+
`;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
function skeletonKnowledgeReadme(name) {
|
|
53
|
+
return `# Knowledge\n\nFiles in this directory are the bot's knowledge assets. Any file format\nis accepted in source; large or binary files travel as content-addressed\nassets alongside the parsed definition.\n\n- \`product-guide.md\` — sample knowledge document for ${name}.\n`;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
function skeletonSkill() {
|
|
57
|
+
return `---\nname: demo\ndescription: Sample skill demonstrating the SKILL.md convention.\n---\n\n# Demo skill\n\nInstructions the bot follows when this skill applies.\n`;
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/**
|
|
61
|
+
* Build a new-bot skeleton file map.
|
|
62
|
+
* @param {{ name: string; description?: string }} input
|
|
63
|
+
* @returns {Record<string, string>}
|
|
64
|
+
*/
|
|
65
|
+
export function scaffoldBotFiles(input) {
|
|
66
|
+
const name = String(input?.name ?? "").trim();
|
|
67
|
+
if (!name || name.length > 100) {
|
|
68
|
+
throw new Error("scaffold requires a name of 1-100 chars");
|
|
69
|
+
}
|
|
70
|
+
const description = String(input?.description ?? "").trim() || `Bot named ${name}.`;
|
|
71
|
+
const botYaml = {
|
|
72
|
+
formatVersion: 1,
|
|
73
|
+
name,
|
|
74
|
+
description,
|
|
75
|
+
icon: "./assets/icon.svg",
|
|
76
|
+
modelRoles: [{ role: "default", label: "Main" }],
|
|
77
|
+
workspace: [],
|
|
78
|
+
triggers: [],
|
|
79
|
+
actions: [],
|
|
80
|
+
connectors: [],
|
|
81
|
+
};
|
|
82
|
+
return {
|
|
83
|
+
"bot.yaml": stringifyYaml(botYaml),
|
|
84
|
+
"README.md": skeletonReadme(name, description),
|
|
85
|
+
"assets/icon.svg": DEFAULT_ICON,
|
|
86
|
+
"instructions.md": skeletonInstructions(name),
|
|
87
|
+
"knowledge/README.md": skeletonKnowledgeReadme(name),
|
|
88
|
+
"knowledge/product-guide.md": `# Product guide\n\nReplace this sample with real knowledge for ${name}.\n`,
|
|
89
|
+
"skills/demo/SKILL.md": skeletonSkill(),
|
|
90
|
+
};
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* Export a parsed draft back to a source tree. Inline knowledge/skill
|
|
95
|
+
* content round-trips; binary knowledge needs its `assets` entry and skill
|
|
96
|
+
* supporting files need `skillFiles` (same shapes parseBotFiles returns).
|
|
97
|
+
* Resource/repo knowledge (url, no content) round-trips through
|
|
98
|
+
* bot.yaml `knowledgeSources`. Vendor grouping is flattened to
|
|
99
|
+
* skills/<id>/: re-running resolve-skills restores pins while content
|
|
100
|
+
* bytes stay identical.
|
|
101
|
+
*
|
|
102
|
+
* Filenames are derived from the stable entry id (sanitized), never the
|
|
103
|
+
* display name: legacy names may contain separators or traversal, and only
|
|
104
|
+
* ids are guaranteed unique. Asset paths tolerate a redundant `knowledge/`
|
|
105
|
+
* prefix (never doubled) and are segment-sanitized.
|
|
106
|
+
*/
|
|
107
|
+
export function exportBotFiles(
|
|
108
|
+
draft,
|
|
109
|
+
{ assets = [], skillFiles = [], icon, sourcesText, lockText } = {},
|
|
110
|
+
) {
|
|
111
|
+
if (typeof draft !== "object" || draft === null) {
|
|
112
|
+
throw new Error("export requires a draft object");
|
|
113
|
+
}
|
|
114
|
+
const {
|
|
115
|
+
name,
|
|
116
|
+
description,
|
|
117
|
+
botPrompt,
|
|
118
|
+
modelRoles,
|
|
119
|
+
workspace,
|
|
120
|
+
triggers,
|
|
121
|
+
actions,
|
|
122
|
+
connectors,
|
|
123
|
+
} = draft;
|
|
124
|
+
if (typeof name !== "string" || typeof botPrompt !== "string") {
|
|
125
|
+
throw new Error("export requires at least draft name and botPrompt");
|
|
126
|
+
}
|
|
127
|
+
if (typeof draft.readme !== "string" || !draft.readme.trim()) {
|
|
128
|
+
throw new Error("export requires a non-empty draft readme");
|
|
129
|
+
}
|
|
130
|
+
const readme = draft.readme.trim();
|
|
131
|
+
if (readme.length > 100000) {
|
|
132
|
+
throw new Error("draft readme is too long (max 100000 chars)");
|
|
133
|
+
}
|
|
134
|
+
/** @type {Record<string, string|Uint8Array>} */
|
|
135
|
+
const files = {};
|
|
136
|
+
const usedPaths = new Set();
|
|
137
|
+
const claimPath = (wanted) => {
|
|
138
|
+
let candidate = wanted;
|
|
139
|
+
let counter = 2;
|
|
140
|
+
while (usedPaths.has(candidate)) {
|
|
141
|
+
const dot = wanted.lastIndexOf(".");
|
|
142
|
+
candidate = dot > 0 ? `${wanted.slice(0, dot)}__${counter}${wanted.slice(dot)}` : `${wanted}__${counter}`;
|
|
143
|
+
counter++;
|
|
144
|
+
}
|
|
145
|
+
usedPaths.add(candidate);
|
|
146
|
+
return candidate;
|
|
147
|
+
};
|
|
148
|
+
const knowledgeSources = [];
|
|
149
|
+
const assetById = new Map((assets ?? []).map((a) => [a.knowledgeId, a]));
|
|
150
|
+
for (const item of draft.knowledge ?? []) {
|
|
151
|
+
if (typeof item.url === "string" && item.url) {
|
|
152
|
+
// External reference: structured source entry, never a file.
|
|
153
|
+
const source = { id: item.id, name: item.name, kind: item.kind, url: item.url };
|
|
154
|
+
if (item.ref !== undefined) source.ref = item.ref;
|
|
155
|
+
knowledgeSources.push(source);
|
|
156
|
+
continue;
|
|
157
|
+
}
|
|
158
|
+
if (typeof item.content === "string") {
|
|
159
|
+
files[claimPath(`knowledge/${exportKnowledgeFilename(item)}`)] = item.content;
|
|
160
|
+
} else {
|
|
161
|
+
const asset = assetById.get(item.id);
|
|
162
|
+
if (!asset) {
|
|
163
|
+
throw new Error(`knowledge ${item.id} has no content and no asset bytes`);
|
|
164
|
+
}
|
|
165
|
+
files[claimPath(`knowledge/${sanitizeAssetRel(asset.path)}`)] = asset.bytes;
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
if (draft.icon !== undefined) {
|
|
169
|
+
const path = iconPath(draft.icon);
|
|
170
|
+
const asset = validateIcon(path, icon?.bytes);
|
|
171
|
+
if (Object.hasOwn(files, path) || ["bot.yaml", "instructions.md", "knowledge/README.md", "skills/sources.yaml", "skills/sources.lock"].includes(path) || path.startsWith("skills/")) {
|
|
172
|
+
throw new Error(`icon path conflicts with exported source: ${path}`);
|
|
173
|
+
}
|
|
174
|
+
files[path] = asset.bytes;
|
|
175
|
+
}
|
|
176
|
+
files["bot.yaml"] = stringifyYaml({
|
|
177
|
+
formatVersion: 1,
|
|
178
|
+
name,
|
|
179
|
+
description: description ?? "",
|
|
180
|
+
...(draft.icon !== undefined ? { icon: `./${iconPath(draft.icon)}` } : {}),
|
|
181
|
+
modelRoles: modelRoles ?? [{ role: "default", label: "Main" }],
|
|
182
|
+
workspace: workspace ?? [],
|
|
183
|
+
triggers: triggers ?? [],
|
|
184
|
+
actions: actions ?? [],
|
|
185
|
+
connectors: (connectors ?? []).map(({ id, ...connector }) => connector),
|
|
186
|
+
knowledgeSources,
|
|
187
|
+
});
|
|
188
|
+
files["instructions.md"] = botPrompt;
|
|
189
|
+
files["README.md"] = readme;
|
|
190
|
+
files["knowledge/README.md"] =
|
|
191
|
+
"# Knowledge\n\nFiles in this directory are the bot's knowledge assets.\n";
|
|
192
|
+
const skillExtras = new Map();
|
|
193
|
+
for (const file of skillFiles ?? []) {
|
|
194
|
+
if (!skillExtras.has(file.skillId)) skillExtras.set(file.skillId, []);
|
|
195
|
+
skillExtras.get(file.skillId).push(file);
|
|
196
|
+
}
|
|
197
|
+
for (const skill of draft.skills ?? []) {
|
|
198
|
+
const skillId = sanitizePathSegment(skill.id, "skill");
|
|
199
|
+
files[`skills/${skillId}/SKILL.md`] = withSkillFrontmatter(skill);
|
|
200
|
+
for (const extra of skillExtras.get(skill.id) ?? []) {
|
|
201
|
+
files[`skills/${skillId}/${sanitizeAssetRel(extra.path)}`] = extra.bytes;
|
|
202
|
+
}
|
|
203
|
+
}
|
|
204
|
+
if (sourcesText !== undefined) files["skills/sources.yaml"] = sourcesText;
|
|
205
|
+
if (lockText !== undefined) files["skills/sources.lock"] = lockText;
|
|
206
|
+
return files;
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
/** Stable export filename from the entry id; the display name only lends an extension. */
|
|
210
|
+
export function exportKnowledgeFilename(item) {
|
|
211
|
+
const ext = /\.([A-Za-z0-9]{1,10})$/.exec(String(item.name ?? ""));
|
|
212
|
+
const id = sanitizePathSegment(item.id, "knowledge");
|
|
213
|
+
const suffix = ext ? `.${ext[1].toLowerCase()}` : "";
|
|
214
|
+
return id.toLowerCase().endsWith(suffix) ? id : id + suffix;
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
/** Sanitize one path segment: no traversal, no separators, non-empty. */
|
|
218
|
+
export function sanitizePathSegment(segment, what) {
|
|
219
|
+
let clean = String(segment ?? "").replace(/[^A-Za-z0-9._-]/g, "_");
|
|
220
|
+
if (!/^[A-Za-z0-9]/.test(clean)) clean = `${what}_` + clean;
|
|
221
|
+
return clean.slice(0, 64) || `${what}_file`;
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
/**
|
|
225
|
+
* Sanitize a multi-segment relative path. A redundant leading `knowledge/`
|
|
226
|
+
* prefix is stripped (never doubled); `..`/empty segments are neutralized
|
|
227
|
+
* by per-segment sanitizing, so the result always stays in place.
|
|
228
|
+
*/
|
|
229
|
+
export function sanitizeAssetRel(rel) {
|
|
230
|
+
const segments = String(rel ?? "").replace(/\\/g, "/").split("/");
|
|
231
|
+
if (segments[0] === "knowledge") segments.shift();
|
|
232
|
+
const clean = segments.map((s) => sanitizePathSegment(s, "file")).filter(Boolean);
|
|
233
|
+
return clean.length > 0 ? clean.join("/") : "file";
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
/**
|
|
237
|
+
* Ensure SKILL.md content carries frontmatter so name/description survive a
|
|
238
|
+
* re-parse round-trip. Legacy skill content without a frontmatter block
|
|
239
|
+
* gets one injected from the draft fields (JSON-quoted: valid YAML).
|
|
240
|
+
*/
|
|
241
|
+
export function withSkillFrontmatter(skill) {
|
|
242
|
+
const content = String(skill.content ?? "");
|
|
243
|
+
if (/^---\r?\n[\s\S]*?\r?\n---(\r?\n|$)/.test(content)) return content;
|
|
244
|
+
const name = JSON.stringify(String(skill.name ?? skill.id));
|
|
245
|
+
const description = JSON.stringify(String(skill.description ?? ""));
|
|
246
|
+
return `---\nname: ${name}\ndescription: ${description}\n---\n\n${content}`;
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
/** Write a file map to disk, creating directories as needed. */
|
|
250
|
+
export async function writeFiles(dir, files) {
|
|
251
|
+
const paths = Object.keys(files).sort();
|
|
252
|
+
for (const rel of paths) {
|
|
253
|
+
if (rel.includes("..") || rel.startsWith("/") || rel === "") {
|
|
254
|
+
throw new Error(`refusing to write outside the target: ${rel}`);
|
|
255
|
+
}
|
|
256
|
+
const full = join(dir, rel);
|
|
257
|
+
await mkdir(join(full, ".."), { recursive: true });
|
|
258
|
+
const value = files[rel];
|
|
259
|
+
await writeFile(full, typeof value === "string" ? value : toBytes(value));
|
|
260
|
+
}
|
|
261
|
+
return paths;
|
|
262
|
+
}
|
|
263
|
+
|
|
264
|
+
/**
|
|
265
|
+
* Create a scaffold in `dir`. Refuses non-empty directories unless `force`.
|
|
266
|
+
* @returns {Promise<string[]>} written relative paths
|
|
267
|
+
*/
|
|
268
|
+
export async function scaffoldBot(dir, input, { force = false } = {}) {
|
|
269
|
+
if (!force) {
|
|
270
|
+
const existing = await readdir(dir).catch((error) => {
|
|
271
|
+
if (error?.code === "ENOENT") return [];
|
|
272
|
+
throw error;
|
|
273
|
+
});
|
|
274
|
+
if (existing.length > 0) {
|
|
275
|
+
throw new Error(`directory is not empty (use force to overwrite): ${dir}`);
|
|
276
|
+
}
|
|
277
|
+
}
|
|
278
|
+
return writeFiles(dir, scaffoldBotFiles(input));
|
|
279
|
+
}
|
package/src/schema.js
ADDED
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
// Versioned bot.yaml JSON Schema loading.
|
|
2
|
+
|
|
3
|
+
import { readFile } from "node:fs/promises";
|
|
4
|
+
|
|
5
|
+
export const SCHEMA_VERSIONS = ["v1"];
|
|
6
|
+
|
|
7
|
+
/** Load the versioned bot.yaml JSON Schema (parsed object). */
|
|
8
|
+
export async function loadSchema(version = "v1") {
|
|
9
|
+
if (version !== "v1") {
|
|
10
|
+
throw new Error(`unknown schema version ${version} (available: v1)`);
|
|
11
|
+
}
|
|
12
|
+
const url = new URL("../schema/v1/bot-yaml-schema.json", import.meta.url);
|
|
13
|
+
return JSON.parse(await readFile(url, "utf8"));
|
|
14
|
+
}
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
// Developer-only adapter for the source formats accepted by the standard skills CLI.
|
|
2
|
+
// The server never calls this module: it consumes committed, content-locked files.
|
|
3
|
+
import { execFile } from 'node:child_process';
|
|
4
|
+
import { promisify } from 'node:util';
|
|
5
|
+
import { mkdtemp, readdir, readFile, lstat, rm } from 'node:fs/promises';
|
|
6
|
+
import { tmpdir } from 'node:os';
|
|
7
|
+
import { join, resolve, isAbsolute } from 'node:path';
|
|
8
|
+
import { canonicalJson, sha256Hex } from './util.js';
|
|
9
|
+
|
|
10
|
+
const execute = promisify(execFile);
|
|
11
|
+
export const SKILLS_CLI_VERSION = '1.7.4';
|
|
12
|
+
|
|
13
|
+
export function vendorContentHash(files, prefix) {
|
|
14
|
+
const entries = Object.entries(files).filter(([name]) => name.startsWith(prefix)).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
|
|
15
|
+
return sha256Hex(new TextEncoder().encode(canonicalJson(entries.map(([name, bytes]) => [name.slice(prefix.length), sha256Hex(bytes)]))));
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
export async function importSkillSource(source, { sourceBaseDir = process.cwd() } = {}) {
|
|
19
|
+
const directory = await mkdtemp(join(tmpdir(), 'librebot-skills-'));
|
|
20
|
+
try {
|
|
21
|
+
let locator = source.repo.source;
|
|
22
|
+
if (locator.startsWith('.') || isAbsolute(locator)) locator = resolve(sourceBaseDir, locator);
|
|
23
|
+
const args = ['--yes', `--package=skills@${SKILLS_CLI_VERSION}`, '--', 'skills', 'add', locator, '--copy', '--yes', '--agent', 'codex', ...(source.skills.length ? ['--skill', ...source.skills] : [])];
|
|
24
|
+
await execute(process.platform === 'win32' ? 'npx.cmd' : 'npx', args, {
|
|
25
|
+
cwd: directory, timeout: 180_000, maxBuffer: 1024 * 1024,
|
|
26
|
+
env: { ...process.env, DISABLE_TELEMETRY: '1', DO_NOT_TRACK: '1', CI: '1' },
|
|
27
|
+
});
|
|
28
|
+
const files = {};
|
|
29
|
+
let size = 0;
|
|
30
|
+
const prefix = `skills/.vendor/${source.name}/`;
|
|
31
|
+
const walk = async (root, rel = '') => {
|
|
32
|
+
for (const name of (await readdir(root)).sort()) {
|
|
33
|
+
const path = join(root, name);
|
|
34
|
+
const relative = rel ? `${rel}/${name}` : name;
|
|
35
|
+
const stat = await lstat(path);
|
|
36
|
+
if (stat.isSymbolicLink()) throw new Error(`Installed skill contains a symbolic link: ${relative}`);
|
|
37
|
+
if (stat.isDirectory()) await walk(path, relative);
|
|
38
|
+
else if (stat.isFile()) {
|
|
39
|
+
if (stat.size > 1024 * 1024) throw new Error(`Skill file exceeds 1 MiB: ${relative}`);
|
|
40
|
+
if (Object.keys(files).length >= 5000 || size + stat.size > 20 * 1024 * 1024) throw new Error('Installed skills exceed file or byte limits');
|
|
41
|
+
files[prefix + relative] = new Uint8Array(await readFile(path));
|
|
42
|
+
size += stat.size;
|
|
43
|
+
} else throw new Error(`Installed skill is not a regular file: ${relative}`);
|
|
44
|
+
}
|
|
45
|
+
};
|
|
46
|
+
await walk(join(directory, '.agents', 'skills'));
|
|
47
|
+
if (!Object.keys(files).some(path => path.endsWith('/SKILL.md'))) throw new Error('The skills CLI installed no SKILL.md files');
|
|
48
|
+
return { files, contentSha256: vendorContentHash(files, prefix) };
|
|
49
|
+
} finally { await rm(directory, { recursive: true, force: true }); }
|
|
50
|
+
}
|