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 ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Librebot contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,271 @@
1
- # Temporary Holding Version
1
+ # librebot-tools
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Public source-format tooling for Librebot bots: parse, validate, preview,
4
+ scaffold, and external-skill lock resolution. Standalone ESM package, no
5
+ build step, hand-written types in `src/index.d.ts`.
6
+
7
+ ## Source format (v1)
8
+
9
+ ```text
10
+ bot.yaml # identity, description, format version, model roles,
11
+ # workspace mounts, triggers, actions, connectors
12
+ instructions.md # main prompt (-> BotDraft.botPrompt)
13
+ README.md # required user documentation (-> BotDraft.readme)
14
+
15
+ knowledge/
16
+ README.md # human/agent index only; never a knowledge entry
17
+ product-guide.md # inline text knowledge (UTF-8, <=100KB)
18
+ image.png # binary knowledge -> content-addressed asset
19
+
20
+ skills/
21
+ sources.yaml # sources accepted by npx skills, or explicit GitHub pins
22
+ sources.lock # immutable commit/archive pins or vendored content digests
23
+ review/
24
+ SKILL.md # local skill (Agent Skills convention, content inlined)
25
+ reference.md # supporting files travel with the skill
26
+ .vendor/<source>/... # vendored external skill content (committed)
27
+ ```
28
+
29
+ Editor schemas ship as `schema/v1/bot-yaml-schema.json` and
30
+ `schema/v1/skills-sources-schema.json`.
31
+
32
+ Rules:
33
+
34
+ - `bot.yaml` keys are strict: unknown fields are errors. `tools` was
35
+ removed — builtin tools are always on, never declared.
36
+ - Required root `README.md` becomes `draft.readme`: strict UTF-8, trimmed,
37
+ non-empty, and at most 100000 characters after trimming.
38
+ It is presentation-only user documentation, never `botPrompt` or knowledge,
39
+ and is distinct from the optional `knowledge/README.md` index.
40
+ Export requires a non-empty string `draft.readme` and writes it back to root
41
+ `README.md`; sources without root documentation fail validation.
42
+ New scaffolds include a user-manual README skeleton (purpose, limits, what
43
+ you need, getting started, examples, what the bot changes) for the author
44
+ to complete; it is published on new bot pages as-is.
45
+ - Optional root `icon` is a repository-relative SVG, PNG, or WebP path.
46
+ New scaffolds include `icon: ./assets/icon.svg` and the default bot glyph.
47
+ Raster images must be square (512 × 512 recommended, not required); SVG
48
+ requires a square viewBox. Maximum edge is 4096 and maximum file size is
49
+ 256 KiB. Transparent backgrounds, colored shapes, groups, transforms,
50
+ gradients, local fragment references, and allowlisted inline presentation
51
+ styles are supported. Scripts, event handlers, external references,
52
+ stylesheets, fonts, images, animation, DOCTYPE, and entities are rejected.
53
+ Prefer simple artwork with adequate padding.
54
+ - Parsed `icon` is separate from knowledge and contains
55
+ `{ path, bytes, mime, sha256, size, width, height }`; `draft.icon` retains
56
+ the normalized `./` source reference. Export with
57
+ `exportBotFiles(parsed.draft, { icon: parsed.icon, assets: parsed.assets,
58
+ skillFiles: parsed.skillFiles })`. An icon reference without asset bytes
59
+ fails export rather than inventing replacement artwork. CLI preview shows
60
+ metadata only, never icon bytes.
61
+ - Visibility is platform-managed and is not a source field. Workspace mounts,
62
+ action groups, and triggers declare explicit stable `key` values. Mounts have
63
+ `path`, actions and triggers use common `kind: gitrepo`; provider and target
64
+ bindings belong to instances. Connectors retain unique labels and platform
65
+ identities. Knowledge source IDs remain portable references.
66
+ - `modelRoles[]` accepts optional `requirements: { tools?, vision?,
67
+ reasoning?, minContextWindow? }`, validated and preserved end to end.
68
+ - `knowledge/README.md` is the index, not an entry. Every other file under
69
+ `knowledge/` is one knowledge asset: UTF-8 text inlines as `content`;
70
+ anything else is returned as an `assets[]` entry
71
+ `{ knowledgeId, path, bytes, sha256, size, mime }` for the platform to
72
+ persist (GCS) and extract. Per-file cap 10 MiB, matching platform validation.
73
+ - Structured external references live in bot.yaml `knowledgeSources[]`
74
+ (`resource` with `url`, `repo` with https `url` + optional `ref`).
75
+ Links in `knowledge/README.md` stay human documentation and are never
76
+ crawled. File-tree ids and `knowledgeSources` ids share one namespace.
77
+ - Local skills are `skills/<id>/SKILL.md` (`SKILL.md`, not
78
+ `instructions.md`). Optional YAML frontmatter supplies `name:` /
79
+ `description:`. Every other file in the skill directory is preserved in
80
+ `skillFiles[]` (`{ skillId, path, bytes, sha256, size }`) so the runtime
81
+ materializes the full skill directory, not just SKILL.md.
82
+ - External skills are declared in `skills/sources.yaml`. A simple list under
83
+ `sources` accepts the source locators supported by `npx skills` (including
84
+ repository URLs, `owner/repo@skill`, and local directories). Named entries
85
+ can specify `source` and optional `skills` selections. Run
86
+ `librebot resolve-skills <dir> --network --vendor` locally: it invokes
87
+ pinned `skills@1.7.4` in a temporary project with telemetry disabled, copies
88
+ the selected files into `skills/.vendor/`, and locks their content digest.
89
+ Existing content-locked vendor trees can be restored offline. Use
90
+ `--update --network --vendor` to intentionally adopt upstream changes.
91
+ Explicit GitHub `ref` declarations also support direct commit/archive
92
+ locking without invoking the CLI. Server parsing stays fully offline,
93
+ verifies content locks, and never executes the installer.
94
+ - Connectors declare capabilities and, for remote MCP servers, an optional
95
+ `endpoint:` (https only). The runtime binds only the declared endpoint.
96
+ Local-execution servers (stdio/command) are rejected: declaring one must
97
+ never authorize host-level execution. Credentials are never stored in
98
+ source.
99
+ - `exportBotFiles` derives filenames from the stable entry id (never the
100
+ display name, which may contain separators), tolerates a redundant
101
+ `knowledge/` asset prefix without doubling it, and injects SKILL.md
102
+ frontmatter from draft fields when legacy content lacks it — so an
103
+ export->parse round-trip preserves names, references, and bytes.
104
+ import {
105
+ parseBotFiles, // (files: Record<string, Uint8Array|string>) -> { formatVersion, draft, icon?, assets, skillFiles, warnings, source, lock }
106
+ parseBotSource, // (dir) -> same; throws BotSourceError on invalid source
107
+ validateFiles, // non-throwing: { ok, errors, warnings, ... }
108
+ validateSource, // (dir) -> same; never throws on invalid source (only on IO)
109
+ scaffoldBotFiles, // ({ name, description? }) -> Record<string, string>
110
+ scaffoldBot, // (dir, input, { force? }) -> written paths
111
+ exportBotFiles, // (draft, { icon?: {bytes}, assets?, skillFiles?, sourcesText?, lockText? }) -> file map
112
+ resolveSkillsLock, // ({ sources, existingLock?, update?, network?, vendor?, fetchImpl? })
113
+ fetchLockedSkills, // (lock, { fetchImpl? }) -> { vendorFiles, errors }
114
+ readTarEntries, // (tarball bytes) -> [{ name, bytes, skipped }]; Recht-safe tar: skips specials, rejects traversal, enforces caps
115
+ loadSchema, // ('v1') -> bot.yaml JSON Schema object
116
+ } from "librebot-tools";
117
+ ```
118
+
119
+ - `validateSource(dir)` return shape: `{ ok: true, errors: [], warnings,
120
+ formatVersion, draft, icon?, assets, skillFiles, source, lock }` or
121
+ `{ ok: false, errors: [{ file, field, message }], warnings }`. It never
122
+ throws for invalid source (filesystem failures throw natively).
123
+ `parseBotSource(dir)` throws `BotSourceError` (with `.errors[]` /
124
+ `.warnings[]`) instead. Same contract for `validateFiles` / `parseBotFiles`.
125
+ - No author-configured shell commands are executed. Standard skill
126
+ installation uses fixed CLI arguments only after explicit local
127
+ `--network --vendor` consent; source locators are passed as arguments,
128
+ never shell strings. GitHub commit pins use bounded, hash-verified HTTP.
129
+
130
+ ## Portable repository declarations
131
+
132
+ Workspace slots, action groups, and triggers have independent explicit stable
133
+ `key` values (up to 64 characters, letters/digits followed by letters/digits,
134
+ periods, underscores, or hyphens). Keys are unique within each section.
135
+
136
+ ```yaml
137
+ workspace:
138
+ - key: source
139
+ label: Source checkout
140
+ path: ./repo
141
+ actions:
142
+ - key: issues
143
+ kind: gitrepo
144
+ capabilities: [read_issue, comment_issue, propose_change]
145
+ triggers:
146
+ - key: new-issue
147
+ label: New issue
148
+ kind: gitrepo
149
+ eventTypes: [issue.opened]
150
+ deciderInstructions: Decide whether this issue needs assistance.
151
+ ```
152
+
153
+ Action capabilities are `read_issue`, `push_branch`, `propose_change`,
154
+ `comment_issue`, `search_issues`, `read_change_request`, `read_repository`,
155
+ `update_issue_labels`, `react_issue`, `update_issue_body`, `update_issue_title`,
156
+ `publish_attachments` (GitHub only: uploads task-local SVG/PNG files as issue
157
+ attachments, posts one comment embedding them, and optionally transitions labels
158
+ after the comment is confirmed; it needs an owner-linked upload token on the
159
+ GitHub connection, and GitLab bindings are rejected), and
160
+ `merge_change_request`.
161
+ Groups require at least one capability; at most 20 groups are accepted.
162
+ API-only actions do not require workspace. Platform bindings select the provider,
163
+ connection, numeric repository identity, and optional checkout independently.
164
+ `push_branch` requires a bound matching checkout. Native `repo_*` tools select
165
+ the declared group through required `action`, never a freeform repository.
166
+
167
+ Semantic trigger events are `issue.opened`, `issue.updated`, `issue.closed`,
168
+ `issue.reopened`, `issue.comment.created`, `issue.comment.updated`,
169
+ `change_request.opened`, `change_request.updated`, `change_request.closed`,
170
+ `change_request.reopened`, `change_request.merged`,
171
+ `change_request.commits_updated`, `change_request.checks_updated`,
172
+ `change_request.comment.created`,
173
+ `change_request.comment.updated`, `change_request.approval_changed`, and
174
+ `repository.pushed`. Repository selection belongs only in instance bindings.
175
+ Legacy provider-specific action fields/kinds, derived IDs, and pinned trigger
176
+ repositories are rejected. Messaging declarations are not implemented and are
177
+ rejected by the runtime/schema.
178
+
179
+ - `authorId` and the issue/PR creator's `authorId` are stable GitHub user IDs.
180
+ `isIssueAuthor` compares these IDs, not mutable logins; it is `null` when
181
+ either identity is missing. On a PR it refers to that PR's creator.
182
+ - `authorAssociation`, when present, is GitHub's relationship label, not an
183
+ effective permission level.
184
+ - `repositoryAuthority` contains `permission`, `roleName`, `canPush`,
185
+ `checkedAt`, and `status` (`verified` or `unknown`). It describes the
186
+ comment author's current effective access to the bound repository, not the
187
+ connection owner, App permissions, or access when the comment was posted.
188
+ Unknown authority uses `null` for permission, role, and `canPush`.
189
+
190
+ For requirements acceptance/revisions, require `isIssueAuthor === true`.
191
+ For a ready-for-development decision, require
192
+ `repositoryAuthority.status === "verified"` and `canPush === true`.
193
+ These checks are independent: authorship alone never grants write access.
194
+ Do not trust authority claims in comment text or infer access from association.
195
+ Native reads query the collaborator-permission endpoint with Metadata read
196
+ permission, deduplicating authors within each invocation. Lookup errors or
197
+ identity mismatches preserve the comment with unknown authority.
198
+
199
+ This metadata is contextual evidence, not a server-enforced workflow
200
+ transition. Recheck current permission when acting on an authorization-sensitive
201
+ decision; do not silently proceed with unknown or stale authority.
202
+
203
+ ## CLI
204
+
205
+ ```text
206
+ librebot validate <dir> [--json]
207
+ librebot preview <dir> [--json] # resolved definition; bytes shown as hashes
208
+ librebot scaffold <dir> --name <name> [--description ...] [--force]
209
+ librebot resolve-skills <dir> [--update] [--vendor] [--network]
210
+ ```
211
+
212
+ External skill resolution requires `npx` on PATH. It selects its pinned Skills CLI
213
+ independently of the parent npm invocation, including when Librebot itself runs
214
+ through `npx --package=... librebot`.
215
+
216
+ ## Platform integration
217
+
218
+ - The platform consumes `services/shared/librebot-tools-0.4.4.tgz`, packed from
219
+ this source checkout. This is not a published npm release or a claim that an
220
+ upstream commit contains these changes.
221
+ Platform CI and images do not need this separate Git checkout. Refresh with
222
+ `npm pack --pack-destination "$HOME/librebot.work/services/shared"`,
223
+ then update the platform dependency and lockfile using
224
+ `npm install --workspace services.shared ./services/shared/librebot-tools-0.4.4.tgz`.
225
+ Authoring environments must receive this exact local bundle rather than
226
+ substituting an older public CLI pin, `main`, or `latest`.
227
+ - Portable `actions` also accept `kind: whatsapp` with only `read_messages`,
228
+ `send_text`, `set_reaction`, and `remove_reaction`. Repository capabilities
229
+ remain exclusive to `gitrepo`. Exact sender-phone bindings, independent read
230
+ context, destination policies, and automated-write consent belong to owner
231
+ instance settings, never portable source. Version 0.4.1 added this parser/schema
232
+ contract; 0.4.2 replaces the scaffold README with a user-manual skeleton;
233
+ 0.4.3 adds the `publish_attachments` repository capability; 0.4.4 adds the
234
+ `merge_change_request` repository capability and the
235
+ `change_request.checks_updated` trigger event.
236
+ All are locally bundled, not published to npm.
237
+ - Portable WhatsApp triggers use `kind: whatsapp`, semantic `message.created`
238
+ and/or `reaction.changed`, and the existing keyed decider definition fields.
239
+ Event namespaces are checked against the selected trigger kind.
240
+ - Ingestion: `parseBotFiles(tree)` -> persist `assets` bytes to GCS, fill
241
+ the platform `BotKnowledge` path/storage fields, materialize `skillFiles`
242
+ per skill, then run platform validation. `draft` carries no `tools` field.
243
+ - `BotConnector.endpoint?` (remote MCP): the runtime must validate the
244
+ bound connection's endpoint matches the declared endpoint.
245
+
246
+ ## Development and publishing
247
+
248
+ Node.js 24 or newer is required. From this repository, install the locked
249
+ dependencies, run the tests, and inspect the package before publishing:
250
+
251
+ ```sh
252
+ npm ci
253
+ npm test
254
+ npm pack --dry-run
255
+ npm publish --access public
256
+ ```
257
+
258
+ ## Tests
259
+
260
+ `npm test` runs the `node:test` suite in `test/` without network access:
261
+ malformed trees, semantic cross-references, binary assets,
262
+ export round-trips, and skill-lock reproducibility.
263
+
264
+ ## Limits (mirror platform validation)
265
+
266
+ 750 KB draft cap (UTF-8 bytes); knowledge <= 100 entries (files + `knowledgeSources`
267
+ combined); skills <= 100; connectors <= 50; triggers <= 20; workspace
268
+ mounts <= 10; model roles 1-4 including `default`; SKILL.md <= 50,000 bytes
269
+ and non-empty; text knowledge <= 100,000 chars inline (empty files inline
270
+ as empty content, matching platform acceptance); knowledge assets
271
+ <= 10 MiB; skill supporting files <= 1 MiB each.
@@ -0,0 +1,262 @@
1
+ #!/usr/bin/env node
2
+ // librebot CLI: validate, preview, scaffold, resolve-skills.
3
+
4
+ import { parseArgs } from "node:util";
5
+ import { writeFile, mkdir, rm } from "node:fs/promises";
6
+ import { join } from "node:path";
7
+ import {
8
+ readDirFiles,
9
+ scaffoldBot,
10
+ validateSource,
11
+ } from "../src/index.js";
12
+ import {
13
+ parseSourcesText,
14
+ parseSourcesYaml,
15
+ resolveSkillsLock,
16
+ serializeLock,
17
+ } from "../src/skills-lock.js";
18
+ import { toBytes } from "../src/util.js";
19
+
20
+ function fail(message, issues) {
21
+ console.error(`error: ${message}`);
22
+ for (const issue of issues ?? []) {
23
+ console.error(` ${issue.file || "."}:${issue.field || "-"}: ${issue.message}`);
24
+ }
25
+ process.exit(1);
26
+ }
27
+
28
+ function printWarnings(warnings, json) {
29
+ if (json) return;
30
+ for (const warning of warnings) {
31
+ console.error(
32
+ `warning: ${warning.file || "."}:${warning.field || "-"}: ${warning.message}`,
33
+ );
34
+ }
35
+ }
36
+
37
+ /** Draft/assets summary with bytes replaced by hashes (JSON-safe). */
38
+ function previewShape(result) {
39
+ return {
40
+ formatVersion: result.formatVersion,
41
+ draft: {
42
+ ...result.draft,
43
+ knowledge: result.draft.knowledge.map((k) => ({
44
+ ...k,
45
+ ...(k.content !== undefined ? { contentChars: k.content.length, content: undefined } : {}),
46
+ })),
47
+ skills: result.draft.skills.map((s) => ({
48
+ ...s,
49
+ contentChars: s.content.length,
50
+ content: undefined,
51
+ })),
52
+ },
53
+ icon: result.icon ? (({ bytes, ...metadata }) => metadata)(result.icon) : undefined,
54
+ assets: result.assets.map((a) => ({
55
+ knowledgeId: a.knowledgeId,
56
+ path: a.path,
57
+ sha256: a.sha256,
58
+ size: a.size,
59
+ mime: a.mime,
60
+ })),
61
+ skillFiles: result.skillFiles.map((f) => ({
62
+ skillId: f.skillId,
63
+ path: f.path,
64
+ sha256: f.sha256,
65
+ size: f.size,
66
+ })),
67
+ warnings: result.warnings,
68
+ source: result.source,
69
+ lock: result.lock,
70
+ };
71
+ }
72
+
73
+ async function cmdValidate(dir, json) {
74
+ const result = await validateSource(dir).catch((error) =>
75
+ fail(`could not read ${dir}: ${error.message}`),
76
+ );
77
+ printWarnings(result.warnings, json);
78
+ if (!result.ok) {
79
+ if (json) {
80
+ console.log(JSON.stringify({ ok: false, errors: result.errors, warnings: result.warnings }, null, 2));
81
+ process.exit(1);
82
+ }
83
+ fail("invalid bot source", result.errors);
84
+ }
85
+ if (json) {
86
+ console.log(JSON.stringify({ ok: true, warnings: result.warnings }, null, 2));
87
+ } else {
88
+ console.log(
89
+ `valid: ${result.draft.name} (${result.draft.knowledge.length} knowledge, ` +
90
+ `${result.draft.skills.length} skills, ${result.assets.length} assets, ` +
91
+ `${result.skillFiles.length} skill files)`,
92
+ );
93
+ }
94
+ }
95
+
96
+ async function cmdPreview(dir, json) {
97
+ const result = await validateSource(dir).catch((error) =>
98
+ fail(`could not read ${dir}: ${error.message}`),
99
+ );
100
+ if (!result.ok) fail("invalid bot source", result.errors);
101
+ const shape = previewShape(result);
102
+ if (json) {
103
+ console.log(JSON.stringify(shape, null, 2));
104
+ return;
105
+ }
106
+ const { draft } = result;
107
+ console.log(`# ${draft.name}`);
108
+ console.log(`${draft.description}\n`);
109
+ console.log(`prompt: instructions.md (${draft.botPrompt.length} chars)`);
110
+ if (result.icon) console.log(`icon: ${result.icon.path} ${result.icon.mime} ${result.icon.width}×${result.icon.height} ${result.icon.size}B sha256:${result.icon.sha256}`);
111
+ console.log(`roles: ${draft.modelRoles.map((r) => r.role).join(", ")}`);
112
+ console.log(`knowledge (${draft.knowledge.length}):`);
113
+ for (const item of draft.knowledge) {
114
+ const asset = result.assets.find((a) => a.knowledgeId === item.id);
115
+ console.log(
116
+ ` - ${item.name} [${item.id}]` +
117
+ (asset ? ` asset ${asset.mime} ${asset.size}B sha256:${asset.sha256.slice(0, 12)}` : item.url ? ` ${item.kind} ${item.url}` : ` inline ${item.content.length} chars`),
118
+ );
119
+ }
120
+ console.log(`skills (${draft.skills.length}):`);
121
+ for (const skill of draft.skills) {
122
+ const extras = result.skillFiles.filter((f) => f.skillId === skill.id).length;
123
+ console.log(` - ${skill.name} [${skill.id}]${extras > 0 ? ` +${extras} files` : ""}`);
124
+ }
125
+ if (draft.connectors.length > 0) {
126
+ console.log(`connectors (${draft.connectors.length}):`);
127
+ for (const conn of draft.connectors) {
128
+ console.log(` - ${conn.label} [${conn.id}]${conn.endpoint ? ` -> ${conn.endpoint}` : ""}`);
129
+ }
130
+ }
131
+ if (draft.triggers.length > 0) {
132
+ console.log("triggers:");
133
+ for (const trigger of draft.triggers) {
134
+ console.log(` - ${trigger.label} [${trigger.key}; ${trigger.kind}] ${trigger.eventTypes.join(", ")}`);
135
+ }
136
+ }
137
+ if (draft.workspace.length > 0) {
138
+ console.log(`workspace: ${draft.workspace.map((w) => `${w.key}: ${w.path}`).join(", ")}`);
139
+ }
140
+ if (draft.actions.length > 0) {
141
+ console.log("actions:");
142
+ for (const group of draft.actions) console.log(` - ${group.key} [${group.kind}]: ${group.capabilities.join(", ")}`);
143
+ }
144
+ if (result.lock) {
145
+ console.log(`skill lock: ${result.lock.resolved.length} sources pinned`);
146
+ }
147
+ printWarnings(result.warnings, false);
148
+ }
149
+
150
+ async function cmdScaffold(dir, options) {
151
+ const name = options.name;
152
+ if (!name) fail("scaffold requires --name");
153
+ try {
154
+ const written = await scaffoldBot(
155
+ dir,
156
+ { name, description: options.description ?? "" },
157
+ { force: options.force === true },
158
+ );
159
+ if (!options.json) {
160
+ console.log(`scaffolded ${written.length} files in ${dir}`);
161
+ } else {
162
+ console.log(JSON.stringify({ dir, written }, null, 2));
163
+ }
164
+ } catch (error) {
165
+ fail(error.message);
166
+ }
167
+ }
168
+
169
+ async function cmdResolveSkills(dir, options) {
170
+ const files = await readDirFiles(dir).catch((error) =>
171
+ fail(`could not read ${dir}: ${error.message}`),
172
+ );
173
+ const raw = files["skills/sources.yaml"];
174
+ if (raw === undefined) fail("no skills/sources.yaml in " + dir);
175
+ const sink = { errors: [], warnings: [] };
176
+ const parsed = parseSourcesYaml(parseSourcesText(new TextDecoder().decode(raw)), sink);
177
+ if (!parsed) fail("invalid skills/sources.yaml", sink.errors);
178
+ let existingLock;
179
+ const lockRaw = files["skills/sources.lock"];
180
+ if (lockRaw !== undefined && !options.update) {
181
+ try {
182
+ const { checkSourcesLock } = await import("../src/skills-lock.js");
183
+ const lockSink = { errors: [], warnings: [] };
184
+ existingLock = checkSourcesLock(
185
+ parsed,
186
+ parseSourcesText(new TextDecoder().decode(lockRaw)),
187
+ lockSink,
188
+ ) ?? undefined;
189
+ } catch {
190
+ existingLock = undefined;
191
+ }
192
+ }
193
+ const { lock, vendorFiles, errors, warnings } = await resolveSkillsLock({
194
+ sources: parsed,
195
+ existingLock,
196
+ update: options.update === true,
197
+ network: options.network === true,
198
+ vendor: options.vendor === true,
199
+ sourceBaseDir: dir,
200
+ currentFiles: files,
201
+ });
202
+ for (const warning of [...sink.warnings, ...warnings]) {
203
+ if (!options.json) {
204
+ console.error(`warning: ${warning.file}:${warning.field}: ${warning.message}`);
205
+ }
206
+ }
207
+ if (errors.length > 0) fail("could not resolve skill sources", errors);
208
+ await writeFile(join(dir, "skills/sources.lock"), serializeLock(lock));
209
+ if (options.vendor) {
210
+ await rm(join(dir, "skills", ".vendor"), { recursive: true, force: true });
211
+ for (const [rel, bytes] of Object.entries(vendorFiles)) {
212
+ await mkdir(join(dir, rel.split("/").slice(0, -1).join("/")), { recursive: true });
213
+ await writeFile(join(dir, rel), toBytes(bytes));
214
+ }
215
+ }
216
+ const shape = {
217
+ lock: join(dir, "skills/sources.lock"),
218
+ sources: lock.resolved.length,
219
+ vendored: Object.keys(vendorFiles).length,
220
+ };
221
+ if (options.json) {
222
+ console.log(JSON.stringify(shape, null, 2));
223
+ } else {
224
+ console.log(
225
+ `locked ${shape.sources} sources -> ${shape.lock}` +
226
+ (options.vendor ? ` (${shape.vendored} vendored files)` : ""),
227
+ );
228
+ }
229
+ }
230
+
231
+ const [command, dir] = process.argv.slice(2).filter((a) => !a.startsWith("-"));
232
+ const { values } = parseArgs({
233
+ args: process.argv.slice(2),
234
+ options: {
235
+ json: { type: "boolean", default: false },
236
+ name: { type: "string" },
237
+ description: { type: "string" },
238
+ force: { type: "boolean", default: false },
239
+ update: { type: "boolean", default: false },
240
+ vendor: { type: "boolean", default: false },
241
+ network: { type: "boolean", default: false },
242
+ },
243
+ allowPositionals: true,
244
+ });
245
+
246
+ if (command === "validate") {
247
+ if (!dir) fail("usage: librebot validate <dir> [--json]");
248
+ await cmdValidate(dir, values.json);
249
+ } else if (command === "preview") {
250
+ if (!dir) fail("usage: librebot preview <dir> [--json]");
251
+ await cmdPreview(dir, values.json);
252
+ } else if (command === "scaffold") {
253
+ if (!dir) fail("usage: librebot scaffold <dir> --name <name> [--description ...] [--force]");
254
+ await cmdScaffold(dir, values);
255
+ } else if (command === "resolve-skills") {
256
+ if (!dir) fail("usage: librebot resolve-skills <dir> [--update] [--vendor] [--network]");
257
+ await cmdResolveSkills(dir, values);
258
+ } else {
259
+ console.error("usage: librebot <validate|preview|scaffold|resolve-skills> <dir> [options]");
260
+ process.exit(1);
261
+ }
262
+
package/package.json CHANGED
@@ -1,6 +1,36 @@
1
1
  {
2
2
  "name": "librebot-tools",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.4.4",
4
+ "description": "Public source-format tooling for Librebot bots: parse, validate, preview, scaffold, and skill-lock resolution.",
5
+ "type": "module",
6
+ "scripts": {
7
+ "test": "node --test test/*.test.mjs"
8
+ },
9
+ "license": "MIT",
10
+ "engines": {
11
+ "node": ">=24"
12
+ },
13
+ "exports": {
14
+ ".": {
15
+ "types": "./src/index.d.ts",
16
+ "default": "./src/index.js"
17
+ }
18
+ },
19
+ "types": "./src/index.d.ts",
20
+ "bin": {
21
+ "librebot": "./bin/librebot.js"
22
+ },
23
+ "files": [
24
+ "src/",
25
+ "schema/",
26
+ "bin/",
27
+ "test/",
28
+ "README.md",
29
+ "LICENSE"
30
+ ],
31
+ "dependencies": {
32
+ "image-size": "2.1.0",
33
+ "saxes": "6.0.0",
34
+ "yaml": "2.9.1"
35
+ }
36
+ }