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/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
|
-
#
|
|
1
|
+
# librebot-tools
|
|
2
2
|
|
|
3
|
-
|
|
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.
|
package/bin/librebot.js
ADDED
|
@@ -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.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
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
|
+
}
|