librebot-tools 0.0.0-stage → 0.4.5

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.
@@ -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
+ }